@paramour-js/next 0.4.0 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 The Next.js integration for [paramour](https://paramour.dev):
 `withTypedRoutes` (build-time registry generation and drift checking),
 typed client hooks for both routers, and the `paramour` CLI
-(`generate` / `check` / `init` / `list` / `doctor`).
+(`generate` / `check` / `init` / `list` / `doctor` / `skills`).
 
 ```sh
 pnpm add paramour @paramour-js/next

package/dist/app.d.ts

@@ -2,67 +2,66 @@ import { type AnyAppRoute, type InferRouteParams, type SafeResult, type SearchOu
 import { type SelectOptions } from "./select.js";
 export type { SelectOptions } from "./select.js";
 /**
- * Client hooks (DESIGN §9, design-07). Each layers over Next's
- * `useSearchParams()` / `useParams()` — App-Router params are synchronous on
- * the client, so there is no loading state, no `useEffect`/`useState`, and
- * the result is SSR-consistent. Two layers per hook (design-07):
+ * Client hooks. Each layers over Next's `useSearchParams()` / `useParams()`
+ * — App-Router params are synchronous on the client, so there is no loading
+ * state, no `useEffect`/`useState`, and the result is SSR-consistent. Two
+ * layers per hook:
  *
- * - Raw-slice stabilization (SEL4): the decode is keyed on the DECLARED
- *   slice of the raw source, not on Next's object reference — a URL change
- *   that only touches keys the route doesn't own (`?utm_source=` churn)
- *   returns the previous result by identity, without re-decoding. Next still
- *   re-renders every subscriber on any URL change (it owns the subscription
- *   — SEL7: selectors stabilize slices, they cannot skip renders); this
- *   layer makes that render cheap and downstream-invisible.
- * - Selection (SEL1–SEL3): every hook takes an optional `{ select }` that
- *   projects the decoded value, with result-equality checking (`Object.is`,
+ * - Raw-slice stabilization: the decode is keyed on the DECLARED slice of
+ *   the raw source, not on Next's object reference — a URL change that only
+ *   touches keys the route doesn't own (`?utm_source=` churn) returns the
+ *   previous result by identity, without re-decoding. Next still re-renders
+ *   every subscriber on any URL change (it owns the subscription; selectors
+ *   stabilize slices, they cannot skip renders); this layer makes that
+ *   render cheap and downstream-invisible.
+ * - Selection: every hook takes an optional `{ select }` that projects the
+ *   decoded value, with result-equality checking (`Object.is`,
  *   `equality: "shallow"` opt-in) so an unchanged selection keeps its
  *   previous reference when OTHER params change.
  *
- * Both layers are render-phase ref caches (SEL8) — the one sanctioned
- * departure from the pure-`useMemo` discipline these hooks previously held.
+ * Both layers are render-phase ref caches — the one sanctioned departure
+ * from the pure-`useMemo` discipline these hooks previously held.
  *
  * Two surfaces per half, mirroring core's server `parse` vs `safeParse`:
  * - `useSearch` / `useRouteParams` return the `SafeResult` union
- *   (discriminated on `status`, PR12) — a user editing the URL never crashes
- *   the component. The selector runs on the success arm only (SEL2).
+ *   (discriminated on `status`) — a user editing the URL never crashes the
+ *   component. The selector runs on the success arm only.
  * - `useSearchOrThrow` / `useRouteParamsOrThrow` throw the decode error in
  *   render, to the nearest client error boundary.
  *
  * Both read the route's blessed-internal `~search` / `~params` via the core
- * decoders (design-03 RL6 — `@paramour/next` is a sanctioned consumer).
+ * decoders — `@paramour/next` is a sanctioned consumer of those internals.
  *
- * Every hook is gated to `AnyAppRoute` (design-06 PR3): a pages-branded route
- * at one of these call sites is a compile error, not a runtime surprise —
- * these hooks read Next's App-Router navigation hooks, whose pages twin has
- * different state cardinality (`@paramour-js/next/pages`).
+ * Every hook is gated to `AnyAppRoute`: a pages-branded route at one of
+ * these call sites is a compile error, not a runtime surprise — these hooks
+ * read Next's App-Router navigation hooks, whose pages twin has different
+ * state cardinality (`@paramour-js/next/pages`).
  *
- * Devtools instrumentation (design-12): each hook reports through the shared
- * emitter in observe.ts — `observe` from inside the `useStableResult`
- * compute callback, which runs exactly on a `(route, fingerprint)` cache
- * miss, so the SEL4 fingerprint layer IS the decode-change dedup (DT4;
- * StrictMode's dev double render reuses the ref cache and cannot
- * double-emit), and `refresh` after the stable result returns, re-emitting
- * the CACHED result when the pathname moved under an unchanged decode so
- * the seam's `navigate`/`pathname` never go stale (DT8). Observations carry
- * the full pre-`select` result (DT12), and the `OrThrow` hooks report the
- * error observation BEFORE rethrowing — only render-phase can, since an
- * effect never runs for a throwing render. Every emit sits behind
- * `process.env.NODE_ENV !== "production"`, which bundlers constant-fold and
- * erase along with the seam module (DT6); the spec each hook hands the
- * emitter is built behind the same literal guard, so prod allocates
- * nothing. `useRouter` and `usePathname` are called unconditionally in
- * every hook (rules of hooks — a build-constant-guarded call would make
- * hook order differ between dev and prod bundles); their cost is a
- * referentially-stable context read each, and only the dev-only spec
- * captures them. The `navigate` capability receives the panel's SEARCH
+ * Devtools instrumentation: each hook reports through the shared emitter in
+ * observe.ts — `observe` from inside the `useStableResult` compute callback,
+ * which runs exactly on a `(route, fingerprint)` cache miss, so the
+ * fingerprint layer IS the decode-change dedup (StrictMode's dev double
+ * render reuses the ref cache and cannot double-emit), and `refresh` after
+ * the stable result returns, re-emitting the CACHED result when the pathname
+ * moved under an unchanged decode so the seam's `navigate`/`pathname` never
+ * go stale. Observations carry the full pre-`select` result, and the
+ * `OrThrow` hooks report the error observation BEFORE rethrowing — only
+ * render-phase can, since an effect never runs for a throwing render. Every
+ * emit sits behind `process.env.NODE_ENV !== "production"`, which bundlers
+ * constant-fold and erase along with the seam module; the spec each hook
+ * hands the emitter is built behind the same literal guard, so prod
+ * allocates nothing. `useRouter` and `usePathname` are called
+ * unconditionally in every hook (rules of hooks — a build-constant-guarded
+ * call would make hook order differ between dev and prod bundles); their
+ * cost is a referentially-stable context read each, and only the dev-only
+ * spec captures them. The `navigate` capability receives the panel's SEARCH
  * STRING only and resolves it against `usePathname()` — basePath-/locale-
- * relative, exactly what `router.replace` expects back (DT8; the live hash
- * is preserved at call time).
+ * relative, exactly what `router.replace` expects back (the live hash is
+ * preserved at call time).
  */
 /**
- * Decoded route params as a `SafeResult` (discriminated on `status`, PR12),
- * optionally projected through `options.select` (design-07 SEL1/SEL2).
+ * Decoded route params as a `SafeResult` (discriminated on `status`),
+ * optionally projected through `options.select`.
  *
  * `useParams()` returns `null` outside an App-Router tree — including the
  * initial render of every pages-router page in a hybrid app — so a `null`
@@ -76,7 +75,7 @@ export declare function useRouteParams<R extends AnyAppRoute, U>(route: R, optio
 /**
  * Decoded route params, or a thrown {@link ParamsDecodeError} (→ nearest
  * client error boundary) on a malformed URL. Optionally projected through
- * `options.select` (design-07 SEL1/SEL2).
+ * `options.select`.
  *
  * A `null` `useParams()` (outside an App-Router tree, e.g. a hybrid app's
  * pages-router initial render) degrades to `{}` so required params throw the
@@ -85,15 +84,15 @@ export declare function useRouteParams<R extends AnyAppRoute, U>(route: R, optio
 export declare function useRouteParamsOrThrow<R extends AnyAppRoute>(route: R): InferRouteParams<R>;
 export declare function useRouteParamsOrThrow<R extends AnyAppRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): U;
 /**
- * Decoded search params as a `SafeResult` (discriminated on `status`, PR12),
- * optionally projected through `options.select` (design-07 SEL1/SEL2).
+ * Decoded search params as a `SafeResult` (discriminated on `status`),
+ * optionally projected through `options.select`.
  */
 export declare function useSearch<R extends AnyAppRoute>(route: R): SafeResult<SearchOutputOf<R["~search"]>>;
 export declare function useSearch<R extends AnyAppRoute, U>(route: R, options: SelectOptions<SearchOutputOf<R["~search"]>, U>): SafeResult<U>;
 /**
  * Decoded search params, or a thrown {@link SearchDecodeError} (→ nearest
  * client error boundary) on a malformed URL. Optionally projected through
- * `options.select` (design-07 SEL1/SEL2).
+ * `options.select`.
  */
 export declare function useSearchOrThrow<R extends AnyAppRoute>(route: R): SearchOutputOf<R["~search"]>;
 export declare function useSearchOrThrow<R extends AnyAppRoute, U>(route: R, options: SelectOptions<SearchOutputOf<R["~search"]>, U>): U;

package/dist/app.js

@@ -54,7 +54,7 @@ export function useRouteParamsOrThrow(route, options) {
         };
     const value = useStableResult(route, paramsFingerprint(route, params), () => {
         // The duplicated decode call across the prod/dev branches is the price
-        // of literal-zero prod cost — the bundler keeps exactly one branch (DT6).
+        // of literal-zero prod cost — the bundler keeps exactly one branch.
         if (process.env.NODE_ENV === "production") {
             return decodeParams(route, params);
         }
@@ -66,7 +66,7 @@ export function useRouteParamsOrThrow(route, options) {
             return data;
         }
         catch (error) {
-            // Report BEFORE the throw reaches the error boundary (DT4). Only the
+            // Report BEFORE the throw reaches the error boundary. Only the
             // decode-error class is observed — foreign errors are not URL facts
             // the panel explains, matching safeDecode*'s taxonomy.
             if (error instanceof ParamsDecodeError && spec !== undefined) {
@@ -127,7 +127,7 @@ export function useSearchOrThrow(route, options) {
             wire: () => searchWireSnapshot(searchParams),
         };
     const value = useStableResult(route, searchParamsFingerprint(route, searchParams), 
-    // decodeSearch is keyed on SearchOutputOf (design-04 SS6) — the correct
+    // decodeSearch is keyed on SearchOutputOf (SS6) — the correct
     // public type — but AnyAppRoute erases its SC to `any`, so for a still-
     // generic R the call's SearchOutputOf<R["~search"]> reduces to `unknown`
     // on the value side while staying deferred on the annotation side. The
@@ -135,22 +135,21 @@ export function useSearchOrThrow(route, options) {
     // rawSearch route now infers its schema output here, not a garbage
     // {~kind, ~schema} shape. The cast appears in both branches below — the
     // prod/dev split (and its duplicated decode call) is the price of
-    // literal-zero prod cost; the bundler keeps exactly one branch (DT6).
+    // literal-zero prod cost; the bundler keeps exactly one branch.
     () => {
         if (process.env.NODE_ENV === "production") {
-            return decodeSearch(route["~search"], searchParams);
+            return decodeSearch(route["~search"], searchParams, route.path);
         }
         try {
-            const data = decodeSearch(route["~search"], searchParams);
+            const data = decodeSearch(route["~search"], searchParams, route.path);
             if (spec !== undefined) {
                 emitter.observe(spec, { data, status: "success" });
             }
             return data;
         }
         catch (error) {
-            // Report BEFORE the throw reaches the error boundary (DT4); only
-            // the decode-error class is observed, matching safeDecode*'s
-            // taxonomy.
+            // Report BEFORE the throw reaches the error boundary; only the
+            // decode-error class is observed, matching safeDecode*'s taxonomy.
             if (error instanceof SearchDecodeError && spec !== undefined) {
                 emitter.observe(spec, { error, status: "error" });
             }
@@ -163,8 +162,8 @@ export function useSearchOrThrow(route, options) {
     return useSelectedValue(value, options);
 }
 /**
- * Real-Next fallback for the adapter seam (design-16 TA3): the /testing
- * provider overrides these reads through {@link AppNavigationContext}; with
+ * Real-Next fallback for the adapter seam: the /testing provider overrides
+ * these reads through {@link AppNavigationContext}; with
  * no provider mounted the context's `null` default resolves here, so
  * production behavior (and this module's `next/navigation`-only bundle
  * graph, per dist.test.ts) is unchanged.
@@ -179,7 +178,7 @@ const realAppAdapter = {
  * Every hook resolves the adapter ONCE at its top and calls the adapter's
  * reads unconditionally, exactly where the direct Next calls previously sat
  * — hook call order is identical across renders and across provider
- * presence (TA4).
+ * presence.
  */
 function useAppNavigation() {
     return useContext(AppNavigationContext) ?? realAppAdapter;

package/dist/cli-args.d.ts

@@ -15,10 +15,10 @@ type ParsedValues<T extends ParseArgsOptionsConfig> = ReturnType<typeof parseArg
     options: T;
 }>>["values"];
 /**
- * The shared command prologue (TR7): parse flags, print usage on a parse
- * error (exit 2) or `--help` (exit 0), and reject positionals — no command
- * takes one. Callers branch on `"exit" in result`; anything past the
- * prologue (mode merging, flag exclusivity) stays per-command.
+ * The shared command prologue: parse flags, print usage on a parse error
+ * (exit 2) or `--help` (exit 0), and reject positionals — no command takes
+ * one. Callers branch on `"exit" in result`; anything past the prologue
+ * (mode merging, flag exclusivity) stays per-command.
  */
 export declare function parseCommandFlags<const T extends HelpOption & ParseArgsOptionsConfig>(argv: readonly string[], options: T, usage: string, { stderr, stdout }: ResolvedIo): {
     exit: 0 | 2;

package/dist/cli-args.js

@@ -1,10 +1,10 @@
 import { parseArgs } from "node:util";
 import { message } from "./cli-io.js";
 /**
- * The shared command prologue (TR7): parse flags, print usage on a parse
- * error (exit 2) or `--help` (exit 0), and reject positionals — no command
- * takes one. Callers branch on `"exit" in result`; anything past the
- * prologue (mode merging, flag exclusivity) stays per-command.
+ * The shared command prologue: parse flags, print usage on a parse error
+ * (exit 2) or `--help` (exit 0), and reject positionals — no command takes
+ * one. Callers branch on `"exit" in result`; anything past the prologue
+ * (mode merging, flag exclusivity) stays per-command.
  */
 export function parseCommandFlags(argv, options, usage, { stderr, stdout }) {
     let parsed;

package/dist/cli-inputs.d.ts

@@ -18,13 +18,12 @@ export interface InputFlags {
 export declare class NoRouteDirsError extends Error {
 }
 /**
- * Precedence lives in exactly this function (TR7 / §7.2): flags → config
- * file → joint discovery (PR8). Paths resolve against the project root
- * (= cwd, where `next` itself would run). Discovery only runs for dirs not
- * explicitly given — passing both bypasses it (and its populated-ignored-dir
- * config error) entirely, which is the documented escape hatch. Only when
- * NEITHER dir exists is that an error (PR8): app-only and pages-only
- * projects are both fine.
+ * Precedence lives in exactly this function: flags → config file → joint
+ * discovery. Paths resolve against the project root (= cwd, where `next`
+ * itself would run). Discovery only runs for dirs not explicitly given —
+ * passing both bypasses it (and its populated-ignored-dir config error)
+ * entirely, which is the documented escape hatch. Only when NEITHER dir
+ * exists is that an error: app-only and pages-only projects are both fine.
  *
  * Commands that already loaded the config file (for fields beyond these,
  * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once.

package/dist/cli-inputs.js

@@ -12,13 +12,12 @@ import { resolveRouteDirs } from "./scan.js";
 export class NoRouteDirsError extends Error {
 }
 /**
- * Precedence lives in exactly this function (TR7 / §7.2): flags → config
- * file → joint discovery (PR8). Paths resolve against the project root
- * (= cwd, where `next` itself would run). Discovery only runs for dirs not
- * explicitly given — passing both bypasses it (and its populated-ignored-dir
- * config error) entirely, which is the documented escape hatch. Only when
- * NEITHER dir exists is that an error (PR8): app-only and pages-only
- * projects are both fine.
+ * Precedence lives in exactly this function: flags → config file → joint
+ * discovery. Paths resolve against the project root (= cwd, where `next`
+ * itself would run). Discovery only runs for dirs not explicitly given —
+ * passing both bypasses it (and its populated-ignored-dir config error)
+ * entirely, which is the documented escape hatch. Only when NEITHER dir
+ * exists is that an error: app-only and pages-only projects are both fine.
  *
  * Commands that already loaded the config file (for fields beyond these,
  * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once.

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 import { runCli } from "./run-cli.js";
-// The bin entry (TR7): all logic lives in run-cli.ts so tests never execute
+// The bin entry: all logic lives in run-cli.ts so tests never execute
 // this statement. exitCode, not exit() — pending stdio writes must flush.
 process.exitCode = await runCli(process.argv.slice(2));

package/dist/collisions.d.ts

@@ -1,21 +1,21 @@
-/** A scanned route path labeled with the router that produced it (PR9). */
+/** A scanned route path labeled with the router that produced it. */
 export interface ScannedRoute {
     path: string;
     router: "app" | "pages";
 }
 /**
- * Route-collision failure mode (PR9): states Next itself refuses to build
- * have no valid artifact, so the scanners throw instead of emitting one.
- * Composition points map this error to their ruled exits — CLI exit 2,
- * `withTypedRoutes` throw during config evaluation, and a non-fatal loud
- * log under watch (the TR5 exception: a collision mid-`--watch` is usually
- * a file mid-move, so the last good artifact stays on disk).
+ * Route-collision failure mode: states Next itself refuses to build have no
+ * valid artifact, so the scanners throw instead of emitting one. Composition
+ * points map this error to their own exits — CLI exit 2, `withTypedRoutes`
+ * throw during config evaluation, and a non-fatal loud log under watch (a
+ * collision mid-`--watch` is usually a file mid-move, so the last good
+ * artifact stays on disk).
  */
 export declare class RouteCollisionError extends Error {
     name: string;
 }
 /**
- * PR9's structural collisions — same detection pass, non-equal strings. Two
+ * Structural collisions — same detection pass, non-equal strings. Two
  * states Next also refuses to build that plain string equality misses:
  *
  * - **Different slug names at one level**: `/x/[id]` + `/x/[slug]` — Next:

package/dist/collisions.js

@@ -1,10 +1,10 @@
 /**
- * Route-collision failure mode (PR9): states Next itself refuses to build
- * have no valid artifact, so the scanners throw instead of emitting one.
- * Composition points map this error to their ruled exits — CLI exit 2,
- * `withTypedRoutes` throw during config evaluation, and a non-fatal loud
- * log under watch (the TR5 exception: a collision mid-`--watch` is usually
- * a file mid-move, so the last good artifact stays on disk).
+ * Route-collision failure mode: states Next itself refuses to build have no
+ * valid artifact, so the scanners throw instead of emitting one. Composition
+ * points map this error to their own exits — CLI exit 2, `withTypedRoutes`
+ * throw during config evaluation, and a non-fatal loud log under watch (a
+ * collision mid-`--watch` is usually a file mid-move, so the last good
+ * artifact stays on disk).
  */
 export class RouteCollisionError extends Error {
     name = "RouteCollisionError";
@@ -22,7 +22,7 @@ const OPTIONAL_CATCH_ALL = /^\[\[\.\.\..+\]\]$/;
  */
 const DYNAMIC_SEGMENT = /^(?:\[\[\.\.\.(?<optional>.+)\]\]|\[\.\.\.(?<catchAll>.+)\]|\[(?<plain>[^[\]]+)\])$/;
 /**
- * PR9's structural collisions — same detection pass, non-equal strings. Two
+ * Structural collisions — same detection pass, non-equal strings. Two
  * states Next also refuses to build that plain string equality misses:
  *
  * - **Different slug names at one level**: `/x/[id]` + `/x/[slug]` — Next:
@@ -56,7 +56,7 @@ export function assertNoStructuralCollisions(routes) {
             const key = `${segments.slice(0, index).join("/")}#${String(index)}#${kind}`;
             const existing = dynamicAt.get(key);
             if (existing !== undefined && existing.segment !== segment) {
-                throw new RouteCollisionError(`route collision: "${existing.path}" (${existing.router}) and "${route.path}" (${route.router}) declare conflicting dynamic segments (${existing.segment} vs ${segment}) at the same position — Next refuses different slug names for the same dynamic path (PR9)`);
+                throw new RouteCollisionError(`route collision: "${existing.path}" (${existing.router}) and "${route.path}" (${route.router}) declare conflicting dynamic segments (${existing.segment} vs ${segment}) at the same position — Next refuses different slug names for the same dynamic path`);
             }
             if (existing === undefined) {
                 dynamicAt.set(key, { ...route, segment });
@@ -67,7 +67,7 @@ export function assertNoStructuralCollisions(routes) {
             const base = segments.length === 1 ? "/" : `/${segments.slice(0, -1).join("/")}`;
             const baseRoute = byPath.get(base);
             if (baseRoute !== undefined) {
-                throw new RouteCollisionError(`route collision: "${route.path}" (${route.router}) also matches "${base}" (${baseRoute.router}) — an optional catch-all has the same specificity as its base path, which Next refuses to build (PR9)`);
+                throw new RouteCollisionError(`route collision: "${route.path}" (${route.router}) also matches "${base}" (${baseRoute.router}) — an optional catch-all has the same specificity as its base path, which Next refuses to build`);
             }
         }
     }

package/dist/commands/doctor.d.ts

@@ -1,4 +1,16 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour doctor` flags — skill-drift test's source of truth. */
+export declare const DOCTOR_OPTIONS: {
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly json: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+};
 /**
  * @internal `paramour doctor` — a verification, so its exit codes follow
  * `check`'s class: 0 pass/warn, 1 any fail, 2 only when doctor itself

package/dist/commands/doctor.js

@@ -6,9 +6,9 @@ const USAGE = [
     "Usage: paramour doctor [options]",
     "",
     "Diagnose the project's paramour setup: config validity, artifact",
-    "freshness, next.config wrapping, version alignment, tsconfig coverage,",
-    "and route-definition discovery (which evaluates matched modules, like",
-    "`paramour list`).",
+    "freshness, next.config wrapping, version alignment, installed agent",
+    "skills, tsconfig coverage, and route-definition discovery (which",
+    "evaluates matched modules, like `paramour list`).",
     "",
     "Exit codes: 0 all checks pass (warnings allowed), 1 any check fails.",
     "",
@@ -16,6 +16,11 @@ const USAGE = [
     "  --help, -h  show this help",
     "  --json      machine-readable output",
 ].join("\n");
+/** @internal `paramour doctor` flags — skill-drift test's source of truth. */
+export const DOCTOR_OPTIONS = {
+    help: { default: false, short: "h", type: "boolean" },
+    json: { default: false, type: "boolean" },
+};
 /**
  * @internal `paramour doctor` — a verification, so its exit codes follow
  * `check`'s class: 0 pass/warn, 1 any fail, 2 only when doctor itself
@@ -23,10 +28,10 @@ const USAGE = [
  */
 export async function runDoctor(argv, io) {
     const { stderr, stdout } = resolveIo(io);
-    const parsed = parseCommandFlags(argv, {
-        help: { default: false, short: "h", type: "boolean" },
-        json: { default: false, type: "boolean" },
-    }, USAGE, { stderr, stdout });
+    const parsed = parseCommandFlags(argv, DOCTOR_OPTIONS, USAGE, {
+        stderr,
+        stdout,
+    });
     if ("exit" in parsed)
         return parsed.exit;
     const flags = parsed.values;

package/dist/commands/generate.d.ts

@@ -1,11 +1,59 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour check` flags — skill-drift test's source of truth. */
+export declare const CHECK_OPTIONS: {
+    readonly "app-dir": {
+        readonly type: "string";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly "out-file": {
+        readonly type: "string";
+    };
+    readonly "page-extensions": {
+        readonly type: "string";
+    };
+    readonly "pages-dir": {
+        readonly type: "string";
+    };
+};
+/** @internal `paramour generate` flags — skill-drift test's source of truth. */
+export declare const GENERATE_OPTIONS: {
+    readonly check: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly watch: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "app-dir": {
+        readonly type: "string";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly "out-file": {
+        readonly type: "string";
+    };
+    readonly "page-extensions": {
+        readonly type: "string";
+    };
+    readonly "pages-dir": {
+        readonly type: "string";
+    };
+};
 /**
- * @internal `paramour generate` and its `check` alias (TR7), in-process
- * testable: returns the exit code instead of exiting. Codes are grep-style
- * so CI can tell drift from breakage: 0 success, 1 check-drift ONLY, 2
- * usage/config/operational errors — route collisions included (PR9: Next
- * itself fails that build, so there is no artifact to emit). Unlike the
- * wrapper's never-load-bearing stance (§7.3), the CLI fails loudly —
- * running it is explicit user intent.
+ * @internal `paramour generate` and its `check` alias, in-process testable:
+ * returns the exit code instead of exiting. Codes are grep-style so CI can
+ * tell drift from breakage: 0 success, 1 check-drift ONLY, 2
+ * usage/config/operational errors — route collisions included (Next itself
+ * fails that build, so there is no artifact to emit). Unlike the wrapper,
+ * which is never load-bearing, the CLI fails loudly — running it is explicit
+ * user intent.
  */
 export declare function runGenerate(argv: readonly string[], io: CliIo, mode: "check" | "generate"): Promise<number>;

package/dist/commands/generate.js

@@ -12,6 +12,14 @@ const SHARED_OPTIONS = {
     "page-extensions": { type: "string" },
     "pages-dir": { type: "string" },
 };
+/** @internal `paramour check` flags — skill-drift test's source of truth. */
+export const CHECK_OPTIONS = SHARED_OPTIONS;
+/** @internal `paramour generate` flags — skill-drift test's source of truth. */
+export const GENERATE_OPTIONS = {
+    ...SHARED_OPTIONS,
+    check: { default: false, type: "boolean" },
+    watch: { default: false, type: "boolean" },
+};
 const SHARED_OPTION_LINES = [
     "  --app-dir <dir>           app directory (default: discovered app/ or src/app/)",
     "  --help, -h                show this help",
@@ -38,24 +46,23 @@ const CHECK_USAGE = [
     ...SHARED_OPTION_LINES,
 ].join("\n");
 /**
- * @internal `paramour generate` and its `check` alias (TR7), in-process
- * testable: returns the exit code instead of exiting. Codes are grep-style
- * so CI can tell drift from breakage: 0 success, 1 check-drift ONLY, 2
- * usage/config/operational errors — route collisions included (PR9: Next
- * itself fails that build, so there is no artifact to emit). Unlike the
- * wrapper's never-load-bearing stance (§7.3), the CLI fails loudly —
- * running it is explicit user intent.
+ * @internal `paramour generate` and its `check` alias, in-process testable:
+ * returns the exit code instead of exiting. Codes are grep-style so CI can
+ * tell drift from breakage: 0 success, 1 check-drift ONLY, 2
+ * usage/config/operational errors — route collisions included (Next itself
+ * fails that build, so there is no artifact to emit). Unlike the wrapper,
+ * which is never load-bearing, the CLI fails loudly — running it is explicit
+ * user intent.
  */
 export async function runGenerate(argv, io, mode) {
     const { stderr, stdout } = resolveIo(io);
     const usage = mode === "check" ? CHECK_USAGE : GENERATE_USAGE;
     let flags;
     if (mode === "generate") {
-        const parsed = parseCommandFlags(argv, {
-            ...SHARED_OPTIONS,
-            check: { default: false, type: "boolean" },
-            watch: { default: false, type: "boolean" },
-        }, usage, { stderr, stdout });
+        const parsed = parseCommandFlags(argv, GENERATE_OPTIONS, usage, {
+            stderr,
+            stdout,
+        });
         if ("exit" in parsed)
             return parsed.exit;
         flags = parsed.values;
@@ -63,7 +70,7 @@ export async function runGenerate(argv, io, mode) {
     else {
         // `check` omits --check/--watch entirely: `paramour check --watch`
         // fails as an unknown option, which is the right message for it.
-        const parsed = parseCommandFlags(argv, SHARED_OPTIONS, usage, {
+        const parsed = parseCommandFlags(argv, CHECK_OPTIONS, usage, {
             stderr,
             stdout,
         });
@@ -105,7 +112,7 @@ function describeRoutes(result) {
     ];
     return parts.length === 0 ? "0 routes" : parts.join(", ");
 }
-/** `--check` (TR7): exit 1 on any drift, including a missing artifact. */
+/** `--check`: exit 1 on any drift, including a missing artifact. */
 function runCheck(inputs, stdout, stderr) {
     let result;
     try {
@@ -132,7 +139,7 @@ function runCheck(inputs, stdout, stderr) {
     stderr("Run `paramour generate` and commit the result.");
     return 1;
 }
-/** One-shot `paramour generate` (TR7). */
+/** One-shot `paramour generate`. */
 function runOnce(inputs, stdout, stderr) {
     let result;
     try {
@@ -149,8 +156,8 @@ function runOnce(inputs, stdout, stderr) {
     return 0;
 }
 /**
- * `--watch` (TR7): TR5 watcher behind the TR6 lock, over both route dirs
- * (PR8). A declined lock exits 0 — another live watcher (usually `next dev`)
+ * `--watch`: the watcher behind the cross-process lock, over both route
+ * dirs. A declined lock exits 0 — another live watcher (usually `next dev`)
  * is the designed dedupe case, and the initial generation already ran.
  * Without an abort signal the returned promise stays pending; the process
  * lives via the FSWatcher refs and dies with the standard signal exits
@@ -172,7 +179,7 @@ function runWatch(inputs, projectRoot, io, stdout, stderr) {
     }
     catch (error) {
         // A corrupt lock location (e.g. a directory at the pidfile path) is an
-        // operational error, not a crash: exit 2 like every other one (TR7).
+        // operational error, not a crash: exit 2 like every other one.
         stderr(`paramour: ${message(error)}`);
         return 2;
     }
@@ -196,13 +203,13 @@ function runWatch(inputs, projectRoot, io, stdout, stderr) {
             }
             catch (error) {
                 if (error instanceof RouteCollisionError) {
-                    // PR9's watch exception: a collision mid-watch is usually a file
-                    // mid-move — log loudly every time, keep the last good artifact
-                    // on disk, keep running (TR5).
+                    // The collision watch exception: a collision mid-watch is usually
+                    // a file mid-move — log loudly every time, keep the last good
+                    // artifact on disk, keep running.
                     stderr(`paramour: ${message(error)}; keeping the last good artifact and watching for the fix`);
                     return;
                 }
-                throw error; // routed to onError by the watcher (TR5 non-fatal)
+                throw error; // routed to onError by the watcher — non-fatal
             }
         },
     });