@paramour-js/next 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Paff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/paramour.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Committed bin stub: pnpm creates bin shims at install time and silently
+// skips any whose target doesn't exist yet — dist/cli.js only exists after
+// a build, so pointing `bin` at it left the examples' shims uncreated (and
+// a second install won't retry: an up-to-date lockfile skips the link
+// phase). This file always exists, so the shim is always created; it just
+// delegates to the built CLI.
+import { existsSync } from "node:fs";
+
+const cli = new URL("../dist/cli.js", import.meta.url);
+
+if (!existsSync(cli)) {
+  console.error(
+    "paramour: @paramour-js/next is not built (dist/cli.js is missing). Run `pnpm build:packages` first.",
+  );
+  process.exit(1);
+}
+
+await import(cli.href);

package/dist/app.d.ts

@@ -0,0 +1,76 @@
+import { type AnyAppRoute, type InferRouteParams, type SafeResult, type SearchOutputOf } from "paramour";
+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):
+ *
+ * - 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`,
+ *   `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.
+ *
+ * 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).
+ * - `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).
+ *
+ * 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`).
+ */
+/**
+ * Decoded route params as a `SafeResult` (discriminated on `status`, PR12),
+ * optionally projected through `options.select` (design-07 SEL1/SEL2).
+ *
+ * `useParams()` returns `null` outside an App-Router tree — including the
+ * initial render of every pages-router page in a hybrid app — so a `null`
+ * context degrades to an empty source (`{}`): required params surface as
+ * ordinary "missing" decode issues (a `SafeResult` error arm), never a crash.
+ * Core keeps its loud throw for genuinely non-object sources from plain-JS
+ * callers; the null tolerance lives here at the adapter.
+ */
+export declare function useRouteParams<R extends AnyAppRoute>(route: R): SafeResult<InferRouteParams<R>>;
+export declare function useRouteParams<R extends AnyAppRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): SafeResult<U>;
+/**
+ * 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).
+ *
+ * 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
+ * documented {@link ParamsDecodeError}, not an undocumented error class.
+ */
+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).
+ */
+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).
+ */
+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

@@ -0,0 +1,32 @@
+"use client";
+import { useParams, useSearchParams } from "next/navigation";
+import { decodeParams, decodeSearch, safeDecodeParams, safeDecodeSearch, } from "paramour";
+import { paramsFingerprint, searchParamsFingerprint, useSelectedResult, useSelectedValue, useStableResult, } from "./select.js";
+export function useRouteParams(route, options) {
+    const params = useParams() ?? {};
+    const result = useStableResult(route, paramsFingerprint(route, params), () => safeDecodeParams(route, params));
+    return useSelectedResult(result, options);
+}
+export function useRouteParamsOrThrow(route, options) {
+    const params = useParams() ?? {};
+    const value = useStableResult(route, paramsFingerprint(route, params), () => decodeParams(route, params));
+    return useSelectedValue(value, options);
+}
+export function useSearch(route, options) {
+    const searchParams = useSearchParams();
+    const result = useStableResult(route, searchParamsFingerprint(route, searchParams), () => safeDecodeSearch(route, searchParams));
+    return useSelectedResult(result, options);
+}
+export function useSearchOrThrow(route, options) {
+    const searchParams = useSearchParams();
+    const value = useStableResult(route, searchParamsFingerprint(route, searchParams), 
+    // decodeSearch is keyed on SearchOutputOf (design-04 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
+    // cast bridges that inference gap to the SAME (correct) type, so a
+    // rawSearch route now infers its schema output here, not a garbage
+    // {~kind, ~schema} shape.
+    () => decodeSearch(route["~search"], searchParams));
+    return useSelectedValue(value, options);
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,28 @@
+import { parseArgs, type ParseArgsOptionsConfig } from "node:util";
+import { type ResolvedIo } from "./cli-io.js";
+/** Every command declares `--help` identically; the prologue relies on it. */
+interface HelpOption {
+    help: {
+        default: false;
+        short: "h";
+        type: "boolean";
+    };
+}
+/** What `parseArgs` infers for `values` from an options table `T`. */
+type ParsedValues<T extends ParseArgsOptionsConfig> = ReturnType<typeof parseArgs<{
+    allowPositionals: true;
+    args: string[];
+    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.
+ */
+export declare function parseCommandFlags<const T extends HelpOption & ParseArgsOptionsConfig>(argv: readonly string[], options: T, usage: string, { stderr, stdout }: ResolvedIo): {
+    exit: 0 | 2;
+} | {
+    values: ParsedValues<T>;
+};
+export {};

package/dist/cli-args.js

@@ -0,0 +1,35 @@
+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.
+ */
+export function parseCommandFlags(argv, options, usage, { stderr, stdout }) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            allowPositionals: true,
+            args: [...argv],
+            options,
+        });
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        stderr(usage);
+        return { exit: 2 };
+    }
+    // parseArgs's values type stays opaque while T is unresolved; the
+    // HelpOption constraint guarantees the property exists.
+    if (parsed.values.help === true) {
+        stdout(usage);
+        return { exit: 0 };
+    }
+    if (parsed.positionals.length > 0) {
+        stderr(`paramour: unexpected argument "${parsed.positionals[0] ?? ""}"`);
+        stderr(usage);
+        return { exit: 2 };
+    }
+    return { values: parsed.values };
+}

package/dist/cli-inputs.d.ts

@@ -0,0 +1,32 @@
+import { type ParamourConfig } from "./config.js";
+import { type GenerateInputs } from "./generate.js";
+/**
+ * The shared route-dir/artifact flags — every command that scans
+ * (`generate`, `check`, `list`) parses these and resolves them here.
+ */
+export interface InputFlags {
+    "app-dir"?: string | undefined;
+    "out-file"?: string | undefined;
+    "page-extensions"?: string | undefined;
+    "pages-dir"?: string | undefined;
+}
+/**
+ * The no-route-dirs case as a distinct class: `generate`/`check`/`list`
+ * treat it like any other exit-2 error, but `init` downgrades it to a
+ * warn-and-skip — a fresh project legitimately has no app/ or pages/ yet.
+ */
+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.
+ *
+ * Commands that already loaded the config file (for fields beyond these,
+ * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once.
+ */
+export declare function resolveInputs(flags: InputFlags, projectRoot: string, preloaded?: ParamourConfig): Promise<GenerateInputs>;

package/dist/cli-inputs.js

@@ -0,0 +1,80 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadConfigFile } from "./config.js";
+import {} from "./generate.js";
+import { DEFAULT_PAGE_EXTENSIONS } from "./scan-app.js";
+import { resolveRouteDirs } from "./scan.js";
+/**
+ * The no-route-dirs case as a distinct class: `generate`/`check`/`list`
+ * treat it like any other exit-2 error, but `init` downgrades it to a
+ * warn-and-skip — a fresh project legitimately has no app/ or pages/ yet.
+ */
+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.
+ *
+ * Commands that already loaded the config file (for fields beyond these,
+ * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once.
+ */
+export async function resolveInputs(flags, projectRoot, preloaded) {
+    const file = preloaded ?? (await loadConfigFile(projectRoot))?.config;
+    const pageExtensions = parsePageExtensions(flags["page-extensions"]) ??
+        file?.pageExtensions ??
+        DEFAULT_PAGE_EXTENSIONS;
+    const explicitAppDir = flags["app-dir"] ?? file?.appDir;
+    const explicitPagesDir = flags["pages-dir"] ?? file?.pagesDir;
+    let appDir = explicitAppDir === undefined
+        ? undefined
+        : checkedDir(explicitAppDir, "app", projectRoot);
+    let pagesDir = explicitPagesDir === undefined
+        ? undefined
+        : checkedDir(explicitPagesDir, "pages", projectRoot);
+    if (explicitAppDir === undefined || explicitPagesDir === undefined) {
+        const discovered = resolveRouteDirs(projectRoot, pageExtensions);
+        appDir ??= discovered.appDir;
+        pagesDir ??= discovered.pagesDir;
+    }
+    if (appDir === undefined && pagesDir === undefined) {
+        throw new NoRouteDirsError(`no route directory (app/, pages/, src/app/, or src/pages/) under ${projectRoot}; pass --app-dir/--pages-dir or set appDir/pagesDir in paramour.config`);
+    }
+    return {
+        appDir,
+        artifactPath: resolve(projectRoot, flags["out-file"] ?? file?.outFile ?? "paramour-env.d.ts"),
+        pageExtensions,
+        pagesDir,
+    };
+}
+/** Resolve an explicitly-given dir and require that it exists. */
+function checkedDir(dir, router, projectRoot) {
+    const resolved = resolve(projectRoot, dir);
+    if (!statSync(resolved, { throwIfNoEntry: false })?.isDirectory()) {
+        throw new Error(`${router} directory not found: ${resolved}`);
+    }
+    return resolved;
+}
+/** `--page-extensions tsx,mdx` → `["tsx", "mdx"]`; empty list is an error. */
+function parsePageExtensions(flag) {
+    if (flag === undefined)
+        return undefined;
+    const list = flag
+        .split(",")
+        .map((ext) => ext.trim())
+        .filter((ext) => ext !== "");
+    if (list.length === 0) {
+        throw new Error("--page-extensions requires a comma-separated list");
+    }
+    // Mirrors the config-file validation: a leading dot silently matches
+    // nothing (`page..tsx` never exists on disk).
+    const dotted = list.find((ext) => ext.startsWith("."));
+    if (dotted !== undefined) {
+        throw new Error(`--page-extensions entries must not start with a dot: "${dotted}"`);
+    }
+    return list;
+}

package/dist/cli-io.d.ts

@@ -0,0 +1,15 @@
+/** @internal I/O seams for tests; defaults write to the console. */
+export interface CliIo {
+    /** Aborting stops `generate --watch` and resolves `runCli` with 0. */
+    signal?: AbortSignal;
+    stderr?: (line: string) => void;
+    stdout?: (line: string) => void;
+}
+/** {@link CliIo} with the write seams defaulted. */
+export interface ResolvedIo {
+    stderr: (line: string) => void;
+    stdout: (line: string) => void;
+}
+/** Error message without the stack — CLI output, not a crash report. */
+export declare function message(error: unknown): string;
+export declare function resolveIo(io: CliIo): ResolvedIo;

package/dist/cli-io.js

@@ -0,0 +1,16 @@
+/** Error message without the stack — CLI output, not a crash report. */
+export function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function resolveIo(io) {
+    return {
+        stderr: io.stderr ??
+            ((line) => {
+                console.error(line);
+            }),
+        stdout: io.stdout ??
+            ((line) => {
+                console.log(line);
+            }),
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +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
+// this statement. exitCode, not exit() — pending stdio writes must flush.
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/collisions.d.ts

@@ -0,0 +1,37 @@
+/** A scanned route path labeled with the router that produced it (PR9). */
+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).
+ */
+export declare class RouteCollisionError extends Error {
+    name: string;
+}
+/**
+ * PR9's 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:
+ *   "You cannot use different slug names for the same dynamic path". Within
+ *   one parent, at one segment position, at most one dynamic segment of each
+ *   KIND may exist — across both scanners, and cross-router for a shared
+ *   prefix, which is why the entries carry router labels. Kinds are compared
+ *   separately because `[id]` beside `[...slug]` is Next's documented
+ *   priority pattern (predefined > dynamic > catch-all), not an error; but
+ *   `[...a]` beside `[[...a]]` IS one ("optional and required catch-all at
+ *   the same level"), so the catch-all family compares whole segments.
+ * - **Optional-catch-all specificity**: `/docs` + `/docs/[[...slug]]` — an
+ *   optional catch-all also matches its own base path, so the pair collides
+ *   at `/docs` even though the strings differ.
+ *
+ * Callers: each scanner over its own output, then the orchestrator over the
+ * merged, labeled union (cross-router pairs only surface there).
+ */
+export declare function assertNoStructuralCollisions(routes: readonly ScannedRoute[]): void;

package/dist/collisions.js

@@ -0,0 +1,80 @@
+/**
+ * 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).
+ */
+export class RouteCollisionError extends Error {
+    name = "RouteCollisionError";
+}
+/**
+ * `[[...name]]` → optional catch-all; used for the specificity check below.
+ */
+const OPTIONAL_CATCH_ALL = /^\[\[\.\.\..+\]\]$/;
+/**
+ * Classifies a path segment: `plain` for `[id]`, `catchAll` for `[...slug]`
+ * AND `[[...slug]]` (one family — mixing required and optional at one level
+ * is itself a Next error), `undefined` for a literal segment. Alternatives
+ * ordered most-wrapped first so `[[...x]]` is never misread as a `[name]`
+ * whose name is `[...x]`.
+ */
+const DYNAMIC_SEGMENT = /^(?:\[\[\.\.\.(?<optional>.+)\]\]|\[\.\.\.(?<catchAll>.+)\]|\[(?<plain>[^[\]]+)\])$/;
+/**
+ * PR9's 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:
+ *   "You cannot use different slug names for the same dynamic path". Within
+ *   one parent, at one segment position, at most one dynamic segment of each
+ *   KIND may exist — across both scanners, and cross-router for a shared
+ *   prefix, which is why the entries carry router labels. Kinds are compared
+ *   separately because `[id]` beside `[...slug]` is Next's documented
+ *   priority pattern (predefined > dynamic > catch-all), not an error; but
+ *   `[...a]` beside `[[...a]]` IS one ("optional and required catch-all at
+ *   the same level"), so the catch-all family compares whole segments.
+ * - **Optional-catch-all specificity**: `/docs` + `/docs/[[...slug]]` — an
+ *   optional catch-all also matches its own base path, so the pair collides
+ *   at `/docs` even though the strings differ.
+ *
+ * Callers: each scanner over its own output, then the orchestrator over the
+ * merged, labeled union (cross-router pairs only surface there).
+ */
+export function assertNoStructuralCollisions(routes) {
+    // parent-prefix + position + kind → the first dynamic segment seen there.
+    const dynamicAt = new Map();
+    const byPath = new Map();
+    for (const route of routes)
+        byPath.set(route.path, route);
+    for (const route of routes) {
+        const segments = route.path === "/" ? [] : route.path.slice(1).split("/");
+        for (const [index, segment] of segments.entries()) {
+            const kind = dynamicKind(segment);
+            if (kind === undefined)
+                continue;
+            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)`);
+            }
+            if (existing === undefined) {
+                dynamicAt.set(key, { ...route, segment });
+            }
+        }
+        const last = segments.at(-1);
+        if (last !== undefined && OPTIONAL_CATCH_ALL.test(last)) {
+            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)`);
+            }
+        }
+    }
+}
+function dynamicKind(segment) {
+    const groups = DYNAMIC_SEGMENT.exec(segment)?.groups;
+    if (groups === undefined)
+        return undefined;
+    return groups.plain === undefined ? "catchAll" : "plain";
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,7 @@
+import { type CliIo } from "../cli-io.js";
+/**
+ * @internal `paramour doctor` — a verification, so its exit codes follow
+ * `check`'s class: 0 pass/warn, 1 any fail, 2 only when doctor itself
+ * cannot run.
+ */
+export declare function runDoctor(argv: readonly string[], io: CliIo): Promise<number>;

package/dist/commands/doctor.js

@@ -0,0 +1,56 @@
+import { parseCommandFlags } from "../cli-args.js";
+import { message, resolveIo } from "../cli-io.js";
+import { runDoctorChecks } from "../doctor/checks.js";
+const MARKS = { fail: "✖", pass: "✔", warn: "⚠" };
+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`).",
+    "",
+    "Exit codes: 0 all checks pass (warnings allowed), 1 any check fails.",
+    "",
+    "Options:",
+    "  --help, -h  show this help",
+    "  --json      machine-readable output",
+].join("\n");
+/**
+ * @internal `paramour doctor` — a verification, so its exit codes follow
+ * `check`'s class: 0 pass/warn, 1 any fail, 2 only when doctor itself
+ * cannot run.
+ */
+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 });
+    if ("exit" in parsed)
+        return parsed.exit;
+    const flags = parsed.values;
+    let checks;
+    try {
+        checks = await runDoctorChecks(process.cwd());
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+    const failed = checks.filter((check) => check.status === "fail").length;
+    const warned = checks.filter((check) => check.status === "warn").length;
+    const status = failed > 0 ? "fail" : warned > 0 ? "warn" : "pass";
+    if (flags.json) {
+        stdout(JSON.stringify({ checks, status }, null, 2));
+        return failed > 0 ? 1 : 0;
+    }
+    for (const check of checks) {
+        stdout(`  ${MARKS[check.status]} ${check.label}`);
+        for (const line of check.detail ?? [])
+            stdout(`      ${line}`);
+    }
+    stdout("");
+    stdout(`doctor: ${String(checks.length)} checks — ${String(failed)} failed, ${String(warned)} warning${warned === 1 ? "" : "s"}`);
+    return failed > 0 ? 1 : 0;
+}

package/dist/commands/generate.d.ts

@@ -0,0 +1,11 @@
+import { type CliIo } from "../cli-io.js";
+/**
+ * @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.
+ */
+export declare function runGenerate(argv: readonly string[], io: CliIo, mode: "check" | "generate"): Promise<number>;