canary-test-cli 7.0.0 → 7.2.0

package/agents/skills/claude-code/canary-add-framework/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: canary-add-framework
+description: >
+  Add a new testing framework to Canary's registry end-to-end — aligns the
+  classifier↔registry contract, authors the
+  `ts/src/data/frameworks/registry.json` entry, validates the execution command,
+  and ensures every classifier `test_type` still resolves to a non-null
+  framework. Use for "add support for a new framework", "add k6", "support
+  cypress", "we need Locust", or when a classifier `test_type` exists with no
+  framework backing it (registry gap). Not for choosing between existing
+  frameworks at runtime (that's the recommender's job) or adding a one-off
+  framework name with no real CLI.
+---
+
+# Canary: Add Framework
+
+> Add a new testing framework to Canary's registry end-to-end. Confirms the
+> classifier↔registry contract, authors the registry entry, validates the
+> execution command, and ensures every classifier `test_type` still resolves to
+> a non-null framework.
+
+## When to Use
+
+- When the user asks to add support for a new framework ("add k6", "support
+  cypress", "we need Locust")
+- When a classifier `test_type` exists but has no framework backing it (registry
+  gap)
+- When migrating from a deprecated framework — adding the new entry before
+  removing the old one
+- NOT for choosing between existing frameworks at runtime — that's the
+  recommender's job
+- NOT for adding a one-off LLM-generated framework name that doesn't exist as a
+  real tool — frameworks must be real, runnable CLIs
+
+## Process
+
+### Phase 1: SCOPE — Confirm the Framework Belongs in the Registry
+
+1. **Verify the framework is real and installable.** It needs a runnable CLI
+   invocation (the `execution_command` template). If you can't write a one-line
+   shell command that runs a single test file, it doesn't fit Canary's model.
+2. **Identify the category.** Match to an existing `category` value (`e2e_ui`,
+   `python_unit`, `api`, `performance`, `frontend_unit`, etc.). New categories
+   require a coordinated classifier update — see Phase 2.
+3. **Check for overlap.** Is there already a `preferred` framework in this
+   category? If yes, decide intentionally: is the new framework a replacement
+   (demote the old to `legacy`), a peer (add as `supported`), or the new
+   preference (demote the old, mark new as `preferred`)?
+4. **Confirm the user wants this maintained.** Each registry entry is a
+   maintenance commitment. A framework added casually but never validated rots
+   into a routing trap.
+
+### Phase 2: ALIGN — Classifier ↔ Registry Contract
+
+1. **Find the classifier rule that emits this `test_type`.** Open
+   `ts/src/core/classifier.ts` and locate the heuristic block that produces the
+   target category.
+2. **If no classifier rule exists for the category:** Add one _before_ the
+   registry entry. A framework with no routing path is a dead entry. Add a
+   heuristic that maps natural-language signals (keywords, phrases) to the new
+   `test_type`.
+3. **If the category exists but the classifier never emits it confidently:**
+   Strengthen the rule's heuristics. Confidence below 0.7 should trigger a
+   clarification, not a generation.
+4. **Run the contract tests:**
+
+   ```bash
+   pytest tests/unit/test_orchestrator.py
+   ```
+
+   Every `test_type` the classifier can emit must resolve to ≥1 framework via
+   `get_by_category` — the orchestrator tests assert non-null framework
+   resolution per category. This is the gate.
+
+### Phase 3: AUTHOR — Write the Registry Entry
+
+1. **Open `ts/src/data/frameworks/registry.json`.** Add a new object to
+   `frameworks[]`. Required fields:
+   - `name` (unique slug)
+   - `display_name`
+   - `category` (must match the classifier emission)
+   - `languages`
+   - `file_extensions`
+   - `execution_command` (with `{file}` placeholder)
+   - `status` (`preferred` / `supported` / `legacy`)
+2. **Add recommended metadata.** `maturity`, `community_size`,
+   `recommended_for`, `strengths`, `avoid_when`, `ecosystems`. These show up in
+   the recommender's reasoning string — sparse entries produce sparse
+   recommendations.
+3. **Validate the `execution_command`.** It must run a single test file when
+   `{file}` is substituted. Test manually:
+
+   ```bash
+   echo '<minimal test>' > /tmp/sample.<ext>
+   <execution_command with /tmp/sample.<ext> substituted>
+   ```
+
+   Confirm exit code 0 (or expected non-zero) and no missing-config errors.
+
+4. **Confirm the `{file}` placeholder is the only substitution.** The executor
+   tokenizes the template with `shlex.split` before substituting `{file}`, so
+   the file path stays a single argv element; paths with spaces must remain
+   intact.
+
+### Phase 4: VERIFY — Generate, Execute, Promote-Dry
+
+1. **Generate a test that should route to the new framework.** Run the
+   `/canary-write-test` slash command in Claude Code with a prompt that should
+   hit the new `test_type`.
+
+2. **Check the trace.** Classification matches the expected category,
+   recommendation picks the new framework (or the existing preferred — confirm
+   this matches your intent), output file has the right extension.
+3. **Execute with `--execute`.** Confirm the framework's CLI actually runs the
+   generated file. A passing execution validates the `execution_command`
+   template under the real Canary invocation path.
+4. **Don't promote.** This is a registry-validation run, not a real test
+   promotion. Leave the artifact in `tests/generated/`.
+
+### Phase 5: DOCUMENT — Update Guides and State
+
+1. **Update `docs/guides/framework-registry.md`** if you added a new category,
+   changed the contract surface, or introduced a new optional field schema.
+2. **Update the LLM-providers guide** if the new framework only works with
+   specific provider output styles (rare; flag this as a smell if it's true).
+3. **Log to `docs/CANARY_STATE.md`.** One line: framework name, category,
+   status, date added. This is the project ledger; future maintainers grep here
+   first.
+4. **Open a PR.** Title: `feat(registry): add <framework-name> support`. Body
+   should include the validation steps you ran and the generated/executed
+   sample.
+
+## Canary Integration
+
+- **`ts/src/data/frameworks/registry.json`** — Source of truth for entries.
+- **`ts/src/core/framework-registry.ts`** — Loader and lookup methods. Don't add
+  lookup helpers here unless the existing five (`get_all_frameworks`,
+  `get_by_category`, `get_preferred_by_category`, `find_by_name`,
+  `match_by_language`) genuinely don't fit.
+- **`ts/src/core/classifier.ts`** — Routing rules. Coordinate changes with
+  registry entries.
+- **`tests/unit/test_orchestrator.py`** — Contract enforcement. Non-null
+  resolution per `test_type` (api → pytest, e2e_ui → playwright, performance →
+  k6, etc.) is asserted here. `tests/unit/test_factory.py` separately enforces
+  the LLM provider matrix.
+
+## Success Criteria
+
+- New entry validates against the contract test (no orphaned `test_type` in
+  classifier, no null framework resolution in registry)
+- The `/canary-write-test` slash command with a routing prompt resolves to the
+  new framework
+- `--execute` runs the generated file successfully via the new
+  `execution_command`
+- `framework-registry.md` documents any new category or schema field
+- `CANARY_STATE.md` ledger entry is present
+- PR includes the validation transcript
+
+## Rationalizations to Reject
+
+| Rationalization                                                           | Why It Is Wrong                                                                                                                                                                                           |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll add the registry entry now and update the classifier later"         | Orphaned registry entries are routing traps. Either both land together or neither does.                                                                                                                   |
+| "Marking it `preferred` is fine, no need to demote the existing entry"    | Multiple `preferred` entries in one category means `get_preferred_by_category` picks by registry order, not by merit. Demote the loser explicitly.                                                        |
+| "I tested the command with my path — Canary's substitution will work too" | Test the substituted command with a path that contains spaces. The executor's `shlex.split`-then-substitute order exists specifically to handle this case; a broken template will silently corrupt argv.  |
+| "It only needs to work for the happy-path prompt I tried"                 | If the classifier emits this `test_type` with confidence ≥0.7 for _any_ phrasing, the framework must handle the resulting generated file. Test at least two distinct prompts that route to the new entry. |
+| "Sparse metadata is fine, we can fill it in later"                        | The recommender's reasoning string is read by humans and agents. Sparse metadata produces unhelpful recommendations — fill it in now while you have the context.                                          |
+
+## Examples
+
+### Example: Adding Cypress as a peer to Playwright
+
+**Scope:** Cypress already has community demand and a CI image. Category
+`e2e_ui` already has Playwright as `preferred`. Decision: add Cypress as
+`supported`, keep Playwright as `preferred`.
+
+**Classifier:** Already emits `test_type=e2e_ui` on UI-test prompts. No
+classifier change needed.
+
+**Entry (abridged):**
+
+```json
+{
+  "name": "cypress",
+  "display_name": "Cypress",
+  "category": "e2e_ui",
+  "languages": ["javascript", "typescript"],
+  "file_extensions": ["cy.ts", "cy.js"],
+  "execution_command": "npx --yes cypress run --spec {file}",
+  "status": "supported",
+  "strengths": ["Time-travel debugging", "Strong DX for UI tests"],
+  "avoid_when": ["Cross-browser parity required (Playwright is stronger)"]
+}
+```
+
+**Validation:** Generated a UI test prompt, confirmed recommender still picked
+Playwright (correct — `preferred` wins). Verified Cypress is accessible by
+routing a prompt with explicit Cypress mention through a future
+explicit-framework override.
+
+### Example: Adding k6 to a new performance category
+
+**Scope:** Performance category doesn't exist in the registry yet. Classifier
+emits `test_type=performance` on load/stress prompts, but the registry has no
+matching entry — this is the orphan case.
+
+**Phase 2 first:** Confirmed `ts/src/core/classifier.ts` already has the
+performance rule (`if "performance" in p or "load test" in p ...`). No
+classifier change needed.
+
+**Phase 3:**
+
+```json
+{
+  "name": "k6",
+  "display_name": "k6",
+  "category": "performance",
+  "languages": ["javascript"],
+  "file_extensions": ["js"],
+  "execution_command": "k6 run {file}",
+  "status": "preferred",
+  "recommended_for": ["HTTP load testing", "Stress and spike tests"],
+  "avoid_when": ["Browser-level performance (use Playwright tracing)"]
+}
+```
+
+**Validation:** Ran the `/canary-write-test` slash command with "Load test
+/v1/search at 200 RPS for 5 minutes". Confirmed classifier emits
+`test_type=performance` at 0.95 confidence, recommender picks k6, k6 CLI runs
+the generated file without error.
+
+## Escalation
+
+- **When the framework requires a non-trivial config file (e.g.,
+  `playwright.config.ts`):** Document the setup in `avoid_when` or in
+  `recommended_for`. If Canary is expected to generate the config too, that's a
+  scaffolder change, not just a registry change.
+- **When two frameworks legitimately should both be `preferred` for different
+  sub-cases:** Split the category. A single category should have a single
+  `preferred`. If the split isn't clean, surface this to the user as a design
+  decision rather than fudging the registry.
+- **When the classifier doesn't reliably emit the target `test_type`:** Don't
+  add the registry entry yet. Strengthen the classifier first — an unreachable
+  entry is dead weight.
+- **When the framework's CLI doesn't accept a single-file argument:** Canary's
+  model is one-test-per-file generation. Frameworks that only run by directory
+  or by tag don't fit cleanly; raise this with the user before forcing a
+  workaround.

package/agents/skills/claude-code/canary-blackhawk/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: canary-blackhawk
+description:
+  Temporal-dependency linter for test files — statically flags tests that lean
+  on wall-clock time, a real delay, or the local timezone, the ones that pass
+  all day and fail at midnight, across a DST boundary, or on Feb 29. Suppresses
+  itself when the file already installs a frozen clock (fake timers, freezegun,
+  time_machine, MockDate). Self-contained, deterministic, advisory by default.
+cli: scripts/cli.mjs
+requires: [node>=20]
+---
+
+# Canary Blackhawk
+
+A test that reads the wall clock is a test with a scheduled outage. It passes
+every run you watch, then fails at 23:59:59, on the Sunday the clocks move, or
+on Feb 29. Blackhawk finds those lines before the calendar does.
+
+Tier-0 deterministic analysis: no LLM, no network, no secrets, no dependency on
+any other skill.
+
+## Rules
+
+| Rule                           | Severity | Fires on                                                                                                                                      |
+| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BH001-wall-clock`             | high     | `Date.now()`, bare `new Date()`, `moment()`, `datetime.now()` / `.today()` / `.utcnow()`, `date.today()`, `time.time()`, `pd.Timestamp.now()` |
+| `BH002-real-delay`             | medium   | `time.sleep(n)` and `setTimeout(fn, n)` with a literal `n > 0`                                                                                |
+| `BH003-local-timezone`         | medium   | `toLocaleString` / `toLocaleDateString` / `toLocaleTimeString`, `strftime('…%Z…')` or `%z`                                                    |
+| `BH004-naive-datetime-compare` | low      | a comparison against `datetime(2024, …)` or `strptime(…)` with no `tzinfo` / `timezone.utc` / `ZoneInfo` / `pytz` on the line                 |
+
+A pinned constructor is never flagged: `new Date('2024-01-01T00:00:00Z')`,
+`moment('2024-01-01')`, and `datetime(2024, 1, 1)` on its own are all fine.
+
+## Framework-conditioned suppression (the important part)
+
+The single biggest failure mode of a temporal linter is firing on tests that
+**already handle time correctly**. So when a file installs a frozen clock, every
+clock-dependent rule (`BH001`, `BH002`, `BH004`) goes quiet for that file.
+Markers:
+
+`vi.useFakeTimers` · `vi.setSystemTime` · `jest.useFakeTimers` ·
+`jest.setSystemTime` · `sinon.useFakeTimers` · `MockDate` · `freeze_time` /
+`freezegun` · `time_machine`
+
+Two deliberate choices inside that:
+
+- **Suppression is file-wide, not block-scoped.** `vi.useFakeTimers()` inside a
+  `beforeEach` governs tests declared above it, and answering "is the clock
+  frozen _here_" accurately needs a real parser. Blackhawk errs toward silence.
+- **`BH003` is never suppressed.** Freezing the clock pins _when_ a test runs,
+  never _where_. A frozen clock does not stop `toLocaleString()` from returning
+  a different string on a developer laptop than on a UTC runner.
+
+## Inline suppression (per-line escape hatch)
+
+File-wide frozen-clock suppression is too coarse when one intentional real wait
+sits among otherwise-deterministic tests. An inline pragma silences a single
+finding:
+
+```js
+// blackhawk-ignore BH002 -- real MongoDB claim race; deterministic wait impossible
+await new Promise((r) => setTimeout(r, 25));
+```
+
+- **Reason required** (the `-- reason` tail) — keeps suppressions honest and
+  greppable, like `eslint-disable-next-line` / `# noqa`.
+- **Rule-scoped** (`BH002`, or the full `BH002-real-delay`) so it never
+  blanket-silences the line; a `BH001` on the same line still fires.
+- **Placement:** the pragma may trail the offending line or sit on the line
+  directly above it. Comma-separate ids to suppress several (`BH002,BH004`).
+- **Counted separately:** suppressed findings are reported as `N suppressed`,
+  out of the actionable total — so a genuinely clean suite can read zero
+  findings while the known-OK waits stay visible.
+
+## Fidelity limits (regex/AST-lite, on purpose)
+
+Blackhawk is a line scanner with no TypeScript parser dependency, so it ships
+anywhere `node` does. The cost, stated plainly:
+
+- **Line-scoped.** A call split across lines (`setTimeout(\n  fn,\n  500\n)`) is
+  missed, as is a `setTimeout` whose callback body contains a comma.
+- **Comment-blind, one level deep.** Lines starting with `#`, `//`, `*`, `/*`,
+  or a docstring quote are skipped; a multi-line block comment whose inner lines
+  do not start with `*` is still scanned.
+- **String-aware, one line deep.** A match that _starts_ inside a string literal
+  on its own line is rejected as fixture data (`pyFile('time.sleep(1)')` does
+  not fire), while an anchor whose pattern merely reaches into quotes
+  (`strftime('..%Z')`) still does; template `${...}` interpolation is code. A
+  string spanning lines is only seen on its opening line, so a fixture blob's
+  continuation lines are still scanned like code.
+- **No type awareness.** `.toLocaleString()` on a `Number` reads the same as on
+  a `Date`.
+- **Suppression is a substring match.** A mention of `freezegun` in a comment
+  silences the file. That direction is intentional: a missed finding costs less
+  than a false one.
+
+## Which files get scanned
+
+A directory walk only visits **test** files — `*.test.*`, `*.spec.*`,
+`test_*.py`, `*_test.py`, or any supported source under `tests/`, `test/`,
+`__tests__/`, `e2e/`, `spec/`. A file named explicitly on the command line is
+always scanned, test-looking or not. Supported suffixes: `.py`, `.js`, `.jsx`,
+`.ts`, `.tsx`, `.mjs`, `.cjs`.
+
+## Invocation
+
+```bash
+# Scan the repo's test files (advisory — always exits 0):
+canary skills run canary-blackhawk
+
+# Scan a specific suite:
+canary skills run canary-blackhawk -- tests/e2e
+
+# Machine-readable findings:
+canary skills run canary-blackhawk -- tests --json
+
+# Fail the step on any finding:
+canary skills run canary-blackhawk -- tests --strict
+
+# Usage, options, and the full rule list (exits 0):
+canary skills run canary-blackhawk -- --help
+```
+
+An unknown flag is rejected with `unrecognized arguments: <flag>` and exit 2;
+use `--` to end option parsing when a path itself starts with a dash.
+
+`--json` shape:
+
+```json
+{
+  "schema_version": 1,
+  "findings": [
+    {
+      "file": "tests/clock.spec.ts",
+      "line": 12,
+      "rule_id": "BH001-wall-clock",
+      "severity": "high",
+      "snippet": "const t = Date.now();",
+      "why": "reads the wall clock, so the assertion depends on when the suite runs..."
+    }
+  ],
+  "summary": {
+    "files_scanned": 8,
+    "findings": 1,
+    "by_severity": { "high": 1 },
+    "suppressed": 0
+  }
+}
+```
+
+## CI wiring (GitHub Actions)
+
+Advisory first, then promote to blocking once the backlog is drained and the
+signal is trusted — the same path every canary gate takes.
+
+```yaml
+- name: Temporal-dependency lint (advisory)
+  run: canary skills run canary-blackhawk -- tests
+# Once clean, add --strict to make new offenders fail the PR:
+# run: canary skills run canary-blackhawk -- tests --strict
+```
+
+## Fixing what it finds
+
+| Finding | Fix                                                                                                                                              |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BH001` | Freeze the clock (`vi.useFakeTimers()` + `vi.setSystemTime(...)`, `@freeze_time("2024-01-01")`) or inject a clock the test controls.             |
+| `BH002` | Advance a fake timer (`vi.advanceTimersByTime(500)`) or await the real condition instead of a duration.                                          |
+| `BH003` | Assert on a UTC representation (`toISOString()`, `strftime('%Y-%m-%dT%H:%M:%SZ')` on a UTC datetime), or pin the locale and timezone explicitly. |
+| `BH004` | Attach a timezone: `datetime(2024, 1, 1, tzinfo=timezone.utc)`.                                                                                  |

package/agents/skills/claude-code/canary-blackhawk/scripts/cli.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// canary-blackhawk -- temporal-dependency linter for test files.
+//
+// Statically flags tests that depend on wall-clock time, a real delay, or the
+// local timezone: the ones that pass all day and fail at midnight, across a DST
+// boundary, or on Feb 29.
+//
+//   <paths>    files or directories to scan (default: the current directory).
+//   --json     emit machine-readable findings instead of human text.
+//   --strict   exit 1 when there are findings (default is advisory: exit 0).
+//
+// Tier-0 deterministic analysis -- no LLM, no network, no secrets, no
+// dependency on any other skill.
+//
+// Invoked via `canary skills run canary-blackhawk -- [paths] [--json] [--strict]`.
+
+import fs from 'node:fs';
+import { scanPaths, toJson } from './scanner.mjs';
+import { RULES } from './rules.mjs';
+import {
+  createParser,
+  formatUsageError,
+  EXIT_USAGE,
+} from '../../../lib/parse-args.mjs';
+
+export const SCHEMA_VERSION = 1;
+
+const PREFIX = 'canary-blackhawk:';
+
+// --- no-silent-abstention (#508 D2, skill-CLI convention half) ---------------
+//
+// Skill CLIs are deliberately self-contained -- no engine import, no shared
+// module -- so they cannot call `gateOutcome`. They honour the doctrine by
+// CONVENTION instead, emitting the same greppable line the engine helper does.
+// The skill-layer conformance registry (agents/skills/test/gate-conformance.
+// test.ts) is what holds them to it: a row whose fixture collapses the
+// denominator and asserts the loud outcome.
+//
+// U+26A0 / U+2014 are written as escapes so this source stays ASCII, matching
+// ts/src/core/gate-result.ts.
+const ABSTAINED_LINE =
+  '\u{26A0} Abstained \u{2014} verified zero items; this is not a pass.';
+
+// The rules block is GENERATED from RULES, never hand-typed: a new rule shows
+// up in --help the moment it is registered, so the help text cannot drift
+// behind the linter as rules are added.
+const USAGE =
+  'usage: canary-blackhawk [-h] [--json] [--strict] [--] [path ...]\n' +
+  '\n' +
+  'Temporal-dependency linter for test files: flags tests that depend on the\n' +
+  'wall clock, a real delay, or the local timezone.\n' +
+  '\n' +
+  'positional arguments:\n' +
+  '  path        files or directories to scan (default: the current directory)\n' +
+  '\n' +
+  'options:\n' +
+  '  -h, --help  show this help message and exit\n' +
+  '  --json      emit machine-readable findings instead of human text\n' +
+  '  --strict    exit 1 when there are findings (default is advisory: exit 0)\n' +
+  '\n' +
+  'rules:\n' +
+  RULES.map((r) => `  ${r.ruleId} (${r.severity})`).join('\n');
+
+function summary(result) {
+  const bySeverity = {};
+  for (const f of result.findings) {
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+  }
+  return {
+    files_scanned: result.filesScanned,
+    findings: result.findings.length,
+    by_severity: bySeverity,
+    suppressed: result.suppressed ?? 0,
+  };
+}
+
+// A trailing "N suppressed" note keeps inline-ignored lines visible but out of
+// the actionable total - the pattern the PR-guardian sticky comment uses.
+function suppressedNote(result) {
+  const n = result.suppressed ?? 0;
+  return n ? `\n${n} suppressed (inline blackhawk-ignore).` : '';
+}
+
+function renderText(result) {
+  const count = result.findings.length;
+  const files = result.filesScanned;
+  const fp = files === 1 ? '' : 's';
+  // #508: zero findings over zero scanned files is an ABSENT result, not a
+  // clean one. Findings outrank abstention (a finding proves a file was read),
+  // so this is checked only on the no-findings path.
+  if (!count && !files) {
+    return (
+      `${ABSTAINED_LINE} No file matched the given paths, so there is ` +
+      'nothing to report. Point at a directory that holds test files, or ' +
+      'pass a file directly.'
+    );
+  }
+  if (!count) {
+    return (
+      `No temporal-dependency findings (${files} file${fp} scanned).` +
+      suppressedNote(result)
+    );
+  }
+  const sp = count === 1 ? '' : 's';
+  const lines = [
+    `${count} temporal-dependency finding${sp} in ${files} file${fp}:`,
+    '',
+  ];
+  for (const f of result.findings) {
+    lines.push(`  ${f.file}:${f.line}  [${f.severity}] ${f.ruleId}`);
+    lines.push(`      ${f.snippet}`);
+    lines.push(`      why: ${f.why}`);
+  }
+  lines.push('');
+  lines.push(
+    'Advisory by default. Re-run with --strict to fail the step on findings.',
+  );
+  return lines.join('\n') + suppressedNote(result);
+}
+
+/**
+ * blackhawk takes paths, so it gets the `--` end-of-options terminator (a file
+ * literally named `--json` stays reachable) and treats a lone `-` as a
+ * positional, as argparse does. The four shared invariants live in the shared
+ * parser (#479).
+ */
+export const CLI_SPEC = {
+  prog: 'canary-blackhawk',
+  booleans: { '--json': 'json', '--strict': 'strict' },
+  positionals: { key: 'paths', defaults: ['.'] },
+};
+
+const parseArgs = createParser(CLI_SPEC);
+
+export function main(argv = []) {
+  const { positionals: paths, opts, help, error } = parseArgs(argv);
+
+  // Usage and parse errors resolve before any filesystem work, so `--help`
+  // never reports a missing path and a typo never half-runs a scan.
+  if (help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (error) {
+    console.error(formatUsageError(CLI_SPEC.prog, error));
+    return EXIT_USAGE;
+  }
+
+  for (const entry of paths) {
+    if (!fs.existsSync(entry)) {
+      console.error(`${PREFIX} path not found: ${entry}`);
+      return 1;
+    }
+  }
+
+  const result = scanPaths(paths);
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          schema_version: SCHEMA_VERSION,
+          findings: result.findings.map(toJson),
+          summary: summary(result),
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log(renderText(result));
+  }
+
+  // Advisory by default (D3). Under --strict the CLI carries an exit-code
+  // contract, so a collapsed denominator inherits EXIT_ABSTAINED (3) -- distinct
+  // from 1 ("found something real"), so CI can tell them apart.
+  if (opts.strict && !result.filesScanned) return 3;
+  return opts.strict && result.findings.length ? 1 : 0;
+}
+
+// Direct execution (the skill runner execs this file via its shebang).
+//
+// `process.exitCode`, not `process.exit()`: a large `--json` payload exceeds
+// the pipe buffer, and `process.exit` tears the process down mid-write, leaving
+// truncated JSON that still exits 0 (#791).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = main(process.argv.slice(2));
+}