The Problem

Modern web projects still generate code that relies on legacy APIs, polyfills, and bulky libraries. Training data for LLMs is saturated with these patterns, so coding agents frequently suggest outdated solutions. Developers need a lightweight, token‑efficient reference that natively understands the latest browser capabilities and can be queried or injected into an agent’s prompt.

What This Does

The repository packages a CLI tool, modern‑web‑guidance, that exposes a small set of commands:

  • install – sets up the skill in a project, creating a modern-web-guidance entry in package.json.
  • search <term> – looks up relevant guides in the local skills/ tree and prints concise snippets.
  • retrieve <id> – returns a specific guide by its identifier.
  • legacy-scan <dir> – walks a codebase, matches patterns against the guide corpus, and emits a report of legacy practices that can be modernized.

All guides live under skills/modern-web-guidance/ as Markdown files. The CLI loads these files at runtime and serves them as plain text; no external network calls are made.

How It Is Wired

Entry point – package.json defines a binary:

"bin": { "modern-web-guidance": "src/index.js" }

src/index.js initializes the commander parser, registers subcommands located in src/commands/*.js, and forwards control to the chosen command handler.

Command flow – For example, legacy-scan follows:

  1. src/commands/legacy-scan.js receives the directory argument.
  2. It calls src/lib/scanner.js, which uses Node’s fs and path to enumerate files.
  3. For each file, scanner.js loads the guide corpus (skills/modern-web-guidance/*.md) and applies a simple regex‑based pattern matcher defined in src/lib/patterns.js.
  4. Results are formatted by src/lib/reporter.js and written to stdout.

The only external dependencies are the Node standard library and the commander package declared in package.json. No network or database writes occur; the tool is purely read‑only against the local filesystem.

Responsibility map

FileResponsibility
src/index.jsCLI bootstrap, command registration
src/commands/*.jsIndividual subcommand logic
src/lib/scanner.jsFile traversal & pattern matching
src/lib/patterns.jsRegex definitions for legacy API detection
src/lib/reporter.jsOutput formatting
skills/modern-web-guidance/*.mdGuideline content

The graph is acyclic; the only hub is src/index.js, which delegates to command modules.

How To Use It

Setup

# From a fresh project
npm init -y
npm install modern-web-guidance@latest

Configuration

No environment variables are required. The only configuration file is skills/modern-web-guidance/ where new guides can be added.

Running it

# Search for a phrase
npx modern-web-guidance search "animate a dialog modal backdrop"

# Retrieve a guide by ID
npx modern-web-guidance retrieve "animate-to-from-top-layer"

# Scan a codebase
npx modern-web-guidance legacy-scan .

The CLI outputs plain text; redirect or pipe as needed.

Real‑World Use

A CI job could invoke legacy-scan and fail if legacy patterns exceed a threshold:

steps:
  - uses: actions/checkout@v4
  - name: Install guidance
    run: npm install modern-web-guidance@latest
  - name: Legacy scan
    run: npx modern-web-guidance legacy-scan . > legacy-report.txt
  - name: Fail on legacy
    if: ${{ steps.legacy-scan.outcome != 'success' }}
    run: exit 1

The report can be reviewed manually or fed into an issue template.

Code Health & Issues

  • Low – No lockfile (package-lock.json or pnpm-lock.yaml) → builds may differ across environments.
  • Medium – No CI/CD pipeline (.github/workflows missing) → no automated test or build gate.
  • Low – Only three unit tests; coverage for CLI commands and scanner logic is minimal.

Other than these, the repository contains a license and CI‑friendly README. All files are under version control, and the guide corpus is entirely static.

The Bottom Line

Modern‑web‑guidance is a lean, npm‑installable tool that bridges the gap between legacy code patterns and modern browser APIs. Its design keeps the skill corpus local and versioned, making it easy to embed in existing developer workflows or agents. The lack of a lockfile and CI pipeline are the main maintenance risks; adding a lockfile and a basic GitHub Actions workflow would strengthen reliability. Teams building LLM‑based coding assistants or automated refactoring pipelines would benefit most.