@paramour-js/next 0.1.0

package/dist/commands/generate.js

@@ -0,0 +1,222 @@
+import { parseCommandFlags } from "../cli-args.js";
+import { resolveInputs } from "../cli-inputs.js";
+import { message, resolveIo } from "../cli-io.js";
+import { RouteCollisionError } from "../collisions.js";
+import { checkArtifact, formatRouteDiff, generate, } from "../generate.js";
+import { acquireWatcherLock, watcherLockPath, } from "../lock.js";
+import { watchRouteDirs } from "../watch.js";
+const SHARED_OPTIONS = {
+    "app-dir": { type: "string" },
+    help: { default: false, short: "h", type: "boolean" },
+    "out-file": { type: "string" },
+    "page-extensions": { type: "string" },
+    "pages-dir": { type: "string" },
+};
+const SHARED_OPTION_LINES = [
+    "  --app-dir <dir>           app directory (default: discovered app/ or src/app/)",
+    "  --help, -h                show this help",
+    "  --out-file <file>         artifact path (default: paramour-env.d.ts)",
+    "  --page-extensions <list>  comma-separated, no leading dots (default: tsx,ts,jsx,js)",
+    "  --pages-dir <dir>         pages directory (default: discovered pages/ or src/pages/)",
+];
+const GENERATE_USAGE = [
+    "Usage: paramour generate [options]",
+    "",
+    "Generate paramour-env.d.ts from the app and pages directories.",
+    "",
+    "Options:",
+    ...SHARED_OPTION_LINES,
+    "  --check                   verify the artifact is current; exit 1 on drift, never writes",
+    "  --watch                   regenerate on route-dir changes",
+].join("\n");
+const CHECK_USAGE = [
+    "Usage: paramour check [options]",
+    "",
+    "Verify the artifact is current; exit 1 on drift, never writes.",
+    "",
+    "Options:",
+    ...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.
+ */
+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 });
+        if ("exit" in parsed)
+            return parsed.exit;
+        flags = parsed.values;
+    }
+    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, {
+            stderr,
+            stdout,
+        });
+        if ("exit" in parsed)
+            return parsed.exit;
+        flags = { ...parsed.values, check: true, watch: false };
+    }
+    if (flags.watch && flags.check) {
+        stderr("paramour: --watch and --check are mutually exclusive");
+        return 2;
+    }
+    const projectRoot = process.cwd();
+    let inputs;
+    try {
+        inputs = await resolveInputs(flags, projectRoot);
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+    if (flags.check)
+        return runCheck(inputs, stdout, stderr);
+    if (flags.watch)
+        return runWatch(inputs, projectRoot, io, stdout, stderr);
+    return runOnce(inputs, stdout, stderr);
+}
+function count(n, noun) {
+    return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
+}
+/** `(2 app routes, 1 pages route)` — per-router so hybrid output reads. */
+function describeRoutes(result) {
+    const parts = [
+        ...(result.appRoutes.length > 0
+            ? [count(result.appRoutes.length, "app route")]
+            : []),
+        ...(result.pagesRoutes.length > 0
+            ? [count(result.pagesRoutes.length, "pages route")]
+            : []),
+    ];
+    return parts.length === 0 ? "0 routes" : parts.join(", ");
+}
+/** `--check` (TR7): exit 1 on any drift, including a missing artifact. */
+function runCheck(inputs, stdout, stderr) {
+    let result;
+    try {
+        result = checkArtifact(inputs);
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+    if (result.upToDate) {
+        stdout(`paramour: ${inputs.artifactPath} is up to date`);
+        return 0;
+    }
+    stderr(result.missingFile
+        ? `paramour: ${inputs.artifactPath} is missing.`
+        : `paramour: ${inputs.artifactPath} is out of date.`);
+    const diff = formatRouteDiff(result.app, result.pages);
+    if (diff.length === 0) {
+        // Byte drift with an identical route set — a hand-edited artifact.
+        stderr("  content differs from generator output");
+    }
+    for (const line of diff)
+        stderr(line);
+    stderr("Run `paramour generate` and commit the result.");
+    return 1;
+}
+/** One-shot `paramour generate` (TR7). */
+function runOnce(inputs, stdout, stderr) {
+    let result;
+    try {
+        result = generate(inputs);
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+    const described = describeRoutes(result);
+    stdout(result.written
+        ? `paramour: wrote ${inputs.artifactPath} (${described})`
+        : `paramour: ${inputs.artifactPath} unchanged (${described})`);
+    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`)
+ * 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
+ * (lock.ts re-raises after cleanup).
+ */
+function runWatch(inputs, projectRoot, io, stdout, stderr) {
+    try {
+        generate(inputs);
+    }
+    catch (error) {
+        // Transient I/O failure (or a collision the user is mid-fixing)
+        // shouldn't kill an editor-companion watcher; only option-resolution
+        // errors (earlier) are fatal.
+        stderr(`paramour: initial generation failed: ${message(error)}`);
+    }
+    let lock;
+    try {
+        lock = acquireWatcherLock(watcherLockPath(projectRoot));
+    }
+    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).
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+    if (!lock.acquired) {
+        stdout(`paramour: watcher already running (pid ${String(lock.ownerPid)}); exiting`);
+        return 0;
+    }
+    const dirs = [inputs.appDir, inputs.pagesDir].filter((dir) => dir !== undefined);
+    let warned = false;
+    const watcher = watchRouteDirs(dirs, {
+        ignorePaths: [inputs.artifactPath],
+        onError: (error) => {
+            if (warned)
+                return;
+            warned = true;
+            stderr(`paramour: watcher error; continuing: ${message(error)}`);
+        },
+        onRescan: () => {
+            try {
+                generate(inputs);
+            }
+            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).
+                    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)
+            }
+        },
+    });
+    stdout(`paramour: watching ${dirs.join(", ")}`);
+    return new Promise((resolveExit) => {
+        const stop = () => {
+            watcher.close();
+            lock.release?.();
+            resolveExit(0);
+        };
+        if (io.signal?.aborted) {
+            stop();
+            return;
+        }
+        io.signal?.addEventListener("abort", stop, { once: true });
+    });
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,9 @@
+import { type CliIo } from "../cli-io.js";
+/**
+ * @internal `paramour init` — non-interactive by design: it runs straight
+ * through with defaults and prints one status line per step. Exit codes: 0
+ * on success INCLUDING manual-fallback wraps (a printed instruction is a
+ * successful outcome, not a failure); 2 only on hard errors (no/broken
+ * package.json, invalid config file, route collisions).
+ */
+export declare function runInit(argv: readonly string[], io: CliIo): Promise<number>;

package/dist/commands/init.js

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { parseCommandFlags } from "../cli-args.js";
+import { NoRouteDirsError, resolveInputs } from "../cli-inputs.js";
+import { message, resolveIo } from "../cli-io.js";
+import { CONFIG_FILE_NAMES, loadConfigFile } from "../config.js";
+import { generate } from "../generate.js";
+import { addPackageScript, checkSetup, paramourConfigTemplate, } from "../init/scaffold.js";
+import { findNextConfig, manualSnippet, wrapNextConfigSource, } from "../init/wrap-next-config.js";
+import { scanRoutes } from "../scan.js";
+const USAGE = [
+    "Usage: paramour init [options]",
+    "",
+    "Set up paramour in this project: scaffold paramour.config.ts, wrap",
+    'next.config with withTypedRoutes, add a "paramour" script, and run the',
+    "first generate. Every step is idempotent and individually skippable.",
+    "",
+    "Options:",
+    "  --dry-run      report every step without writing anything",
+    "  --force        overwrite an existing paramour.config with the scaffold",
+    "  --help, -h     show this help",
+    "  --no-config    skip scaffolding paramour.config.ts",
+    "  --no-generate  skip the first generate",
+    "  --no-script    skip adding the package.json script",
+    "  --no-wrap      skip wrapping next.config",
+].join("\n");
+/**
+ * @internal `paramour init` — non-interactive by design: it runs straight
+ * through with defaults and prints one status line per step. Exit codes: 0
+ * on success INCLUDING manual-fallback wraps (a printed instruction is a
+ * successful outcome, not a failure); 2 only on hard errors (no/broken
+ * package.json, invalid config file, route collisions).
+ */
+export async function runInit(argv, io) {
+    const { stderr, stdout } = resolveIo(io);
+    const parsed = parseCommandFlags(argv, {
+        "dry-run": { default: false, type: "boolean" },
+        force: { default: false, type: "boolean" },
+        help: { default: false, short: "h", type: "boolean" },
+        "no-config": { default: false, type: "boolean" },
+        "no-generate": { default: false, type: "boolean" },
+        "no-script": { default: false, type: "boolean" },
+        "no-wrap": { default: false, type: "boolean" },
+    }, USAGE, { stderr, stdout });
+    if ("exit" in parsed)
+        return parsed.exit;
+    const flags = parsed.values;
+    const projectRoot = process.cwd();
+    const dry = flags["dry-run"];
+    const write = (path, content) => {
+        if (!dry)
+            writeFileSync(path, content);
+    };
+    // The one hard prerequisite: init edits package.json and reasons about
+    // dependencies, so a project without one has nothing to initialize into.
+    const packageJsonPath = join(projectRoot, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        stderr("paramour: no package.json here — run init at the project root");
+        return 2;
+    }
+    stdout(dry ? "paramour init (dry run — nothing written)" : "paramour init");
+    // 1. Scaffold paramour.config.ts.
+    if (!flags["no-config"]) {
+        const existing = CONFIG_FILE_NAMES.find((name) => existsSync(join(projectRoot, name)));
+        if (existing !== undefined && !flags.force) {
+            stdout(`  • ${existing} already exists — skipped (--force overwrites)`);
+        }
+        else {
+            // A .mjs/.json left behind would be shadowed by the scaffold under the
+            // ts-first discovery order (§7.2) — --force must truly replace it.
+            if (existing !== undefined && existing !== "paramour.config.ts" && !dry) {
+                unlinkSync(join(projectRoot, existing));
+            }
+            write(join(projectRoot, "paramour.config.ts"), paramourConfigTemplate());
+            const suffix = existing === undefined
+                ? ""
+                : existing === "paramour.config.ts"
+                    ? " (overwrote via --force)"
+                    : ` (replaced ${existing} via --force)`;
+            stdout(`  ✔ ${dry ? "would create" : "created"} paramour.config.ts${suffix}`);
+        }
+    }
+    // Read whatever config actually exists on disk (the scaffold is
+    // commented-out defaults, so scaffolding never changes these values).
+    let config;
+    try {
+        config = (await loadConfigFile(projectRoot))?.config ?? {};
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+    // 2. Wrap next.config with withTypedRoutes.
+    if (!flags["no-wrap"]) {
+        const found = findNextConfig(projectRoot);
+        if (found === undefined) {
+            stdout("  → no next.config found — create one and wrap it yourself:");
+            for (const line of manualSnippet().split("\n"))
+                stdout(`      ${line}`);
+        }
+        else {
+            const name = basename(found.path);
+            let source;
+            try {
+                source = readFileSync(found.path, "utf8");
+            }
+            catch (error) {
+                // Same stance as the transform's manual fallback: an unreadable
+                // config degrades to the printed snippet, never a crash.
+                stdout(`  → could not read ${name} (${message(error)}) — apply this yourself:`);
+                for (const line of manualSnippet().split("\n"))
+                    stdout(`      ${line}`);
+            }
+            if (source !== undefined) {
+                const result = await wrapNextConfigSource(source);
+                if (result.status === "already-wrapped") {
+                    stdout(`  • ${name} already wraps withTypedRoutes — skipped`);
+                }
+                else if (result.status === "wrapped") {
+                    write(found.path, result.code);
+                    stdout(`  ✔ ${dry ? "would wrap" : "wrapped"} ${name} with withTypedRoutes`);
+                }
+                else {
+                    stdout(`  → could not transform ${name} safely — apply this yourself:`);
+                    for (const line of result.snippet.split("\n")) {
+                        stdout(`      ${line}`);
+                    }
+                }
+            }
+        }
+    }
+    // 3. package.json script.
+    if (!flags["no-script"]) {
+        let result;
+        try {
+            result = addPackageScript(readFileSync(packageJsonPath, "utf8"));
+        }
+        catch (error) {
+            stderr(`paramour: package.json: ${message(error)}`);
+            return 2;
+        }
+        if (result.changed) {
+            write(packageJsonPath, result.text);
+            stdout(`  ✔ ${dry ? "would add" : "added"} "paramour" script to package.json`);
+        }
+        else {
+            stdout(`  • package.json already has a "paramour" script — skipped`);
+        }
+    }
+    // 4. First generate.
+    // resolve, not join — an absolute outFile must win, as it does in
+    // resolveInputs.
+    let artifactPath = resolve(projectRoot, config.outFile ?? "paramour-env.d.ts");
+    if (!flags["no-generate"]) {
+        let inputs;
+        try {
+            inputs = await resolveInputs({}, projectRoot, config);
+        }
+        catch (error) {
+            if (!(error instanceof NoRouteDirsError)) {
+                stderr(`paramour: ${message(error)}`);
+                return 2;
+            }
+            stdout("  ⚠ no route directory yet — skipped generate (run `paramour generate` once app/ or pages/ exists)");
+        }
+        if (inputs !== undefined) {
+            artifactPath = inputs.artifactPath;
+            const artifactRel = relative(projectRoot, artifactPath).replaceAll("\\", "/");
+            try {
+                if (dry) {
+                    const routes = scanRoutes(inputs, inputs.pageExtensions);
+                    stdout(`  ✔ would write ${artifactRel} (${countRoutes(routes)})`);
+                }
+                else {
+                    const result = generate(inputs);
+                    stdout(result.written
+                        ? `  ✔ wrote ${artifactRel} (${countRoutes(result)})`
+                        : `  • ${artifactRel} already up to date (${countRoutes(result)}) — skipped`);
+                }
+            }
+            catch (error) {
+                stderr(`paramour: ${message(error)}`);
+                return 2;
+            }
+        }
+    }
+    return finishWithSummary(projectRoot, artifactPath, stdout);
+}
+function countRoutes(routes) {
+    const total = routes.appRoutes.length + routes.pagesRoutes.length;
+    return `${String(total)} route${total === 1 ? "" : "s"}`;
+}
+function finishWithSummary(projectRoot, artifactPath, stdout) {
+    // Detect-and-verify summary (warn-level — never affects the exit code).
+    stdout("");
+    stdout("setup:");
+    for (const check of checkSetup(projectRoot, artifactPath)) {
+        stdout(`  ${check.ok ? "✔" : "⚠"} ${check.label}`);
+        if (check.detail !== undefined)
+            stdout(`      ${check.detail}`);
+    }
+    stdout("");
+    stdout("Commit the generated artifact — `paramour check` verifies it stays current in CI.");
+    return 0;
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,9 @@
+import { type CliIo } from "../cli-io.js";
+/**
+ * @internal `paramour list`: the filesystem scan is authoritative for WHICH
+ * routes exist (same engine as generate); discovered definitions overlay
+ * the shapes. A filesystem route with no definition and a definition with
+ * no filesystem route are both warnings, not errors — the report doubles
+ * as a coverage check, and warnings exit 0.
+ */
+export declare function runList(argv: readonly string[], io: CliIo): Promise<number>;

package/dist/commands/list.js

@@ -0,0 +1,94 @@
+import { describeRoute } from "paramour";
+import { parseCommandFlags } from "../cli-args.js";
+import { resolveInputs } from "../cli-inputs.js";
+import { message, resolveIo } from "../cli-io.js";
+import { loadConfigFile } from "../config.js";
+import { discoverRouteDefinitions, routeKey, } from "../list/discover-route-defs.js";
+import { buildListJson, renderListReport, } from "../list/render.js";
+import { scanRoutes } from "../scan.js";
+const USAGE = [
+    "Usage: paramour list [options]",
+    "",
+    "Print every filesystem route with its params/search shape.",
+    "",
+    "Shapes come from defineAppRoute/definePagesRoute call sites: list scans",
+    "source files for those calls and EVALUATES the matching modules to read",
+    "their route objects (set `routeFiles` globs in paramour.config to pin",
+    "which modules). Modules that fail to load are reported and skipped.",
+    "",
+    "Options:",
+    "  --app-dir <dir>           app directory (default: discovered app/ or src/app/)",
+    "  --help, -h                show this help",
+    "  --json                    machine-readable output",
+    "  --page-extensions <list>  comma-separated, no leading dots (default: tsx,ts,jsx,js)",
+    "  --pages-dir <dir>         pages directory (default: discovered pages/ or src/pages/)",
+].join("\n");
+/**
+ * @internal `paramour list`: the filesystem scan is authoritative for WHICH
+ * routes exist (same engine as generate); discovered definitions overlay
+ * the shapes. A filesystem route with no definition and a definition with
+ * no filesystem route are both warnings, not errors — the report doubles
+ * as a coverage check, and warnings exit 0.
+ */
+export async function runList(argv, io) {
+    const { stderr, stdout } = resolveIo(io);
+    const parsed = parseCommandFlags(argv, {
+        "app-dir": { type: "string" },
+        help: { default: false, short: "h", type: "boolean" },
+        json: { default: false, type: "boolean" },
+        "page-extensions": { type: "string" },
+        "pages-dir": { type: "string" },
+    }, USAGE, { stderr, stdout });
+    if ("exit" in parsed)
+        return parsed.exit;
+    const flags = parsed.values;
+    const projectRoot = process.cwd();
+    let report;
+    try {
+        const config = (await loadConfigFile(projectRoot))?.config ?? {};
+        const inputs = await resolveInputs(flags, projectRoot, config);
+        const routes = scanRoutes(inputs, inputs.pageExtensions);
+        const discovery = await discoverRouteDefinitions(projectRoot, {
+            routeFiles: config.routeFiles,
+        });
+        const described = new Map();
+        for (const definition of discovery.definitions) {
+            described.set(routeKey(definition.route["~router"], definition.route.path), {
+                description: describeRoute(definition.route),
+                exportName: definition.exportName,
+                file: definition.file,
+            });
+        }
+        const matched = new Set();
+        const overlay = (router, paths) => paths.map((path) => {
+            const key = routeKey(router, path);
+            const definition = described.get(key) ?? null;
+            if (definition !== null)
+                matched.add(key);
+            return { definition, path };
+        });
+        const appRoutes = overlay("app", routes.appRoutes);
+        const pagesRoutes = overlay("pages", routes.pagesRoutes);
+        const orphans = [...described.entries()]
+            .filter(([key]) => !matched.has(key))
+            .map(([, definition]) => definition);
+        report = {
+            appRoutes,
+            duplicates: discovery.duplicates,
+            loadFailures: discovery.loadFailures,
+            orphans,
+            pagesRoutes,
+        };
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+    if (flags.json) {
+        stdout(JSON.stringify(buildListJson(report), null, 2));
+        return 0;
+    }
+    for (const line of renderListReport(report))
+        stdout(line);
+    return 0;
+}

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shape of `paramour.config.{ts,mjs,json}` (§7.2 / TR7) — the CLI's config
+ * file. Every field is optional; the CLI's precedence is flags → this file →
+ * inference. `.ts`/`.mjs` files default-export this object.
+ */
+export interface ParamourConfig {
+    /** App dir, relative to the project root; default: joint discovery (PR8). */
+    appDir?: string;
+    /** Artifact path, relative to the project root (TR3 escape hatch). */
+    outFile?: string;
+    /** Page extensions, no leading dot; default: Next's four. */
+    pageExtensions?: string[];
+    /** Pages dir, relative to the project root; default: joint discovery (PR8). */
+    pagesDir?: string;
+    /**
+     * Globs (relative to the project root) of modules exporting route
+     * definitions, for `paramour list`/`doctor` only — generation never reads
+     * it. Overrides their automatic defineAppRoute/definePagesRoute content
+     * scan when the heuristic misfires.
+     */
+    routeFiles?: string[];
+}
+/** @internal Discovery order at the project root (TR7) — first match wins. */
+export declare const CONFIG_FILE_NAMES: readonly ["paramour.config.ts", "paramour.config.mjs", "paramour.config.json"];
+/**
+ * @internal Load and validate the project's config file, or `undefined`
+ * when none exists. No upward traversal — the documented contract is three
+ * filenames at the project root (TR7). jiti (the §7.2 loader carry-over) is
+ * imported dynamically so only CLI runs that actually have a `.ts`/`.mjs`
+ * config pay for it; `withTypedRoutes` users never execute it.
+ */
+export declare function loadConfigFile(projectRoot: string): Promise<undefined | {
+    config: ParamourConfig;
+    path: string;
+}>;

package/dist/config.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** @internal Discovery order at the project root (TR7) — first match wins. */
+export const CONFIG_FILE_NAMES = [
+    "paramour.config.ts",
+    "paramour.config.mjs",
+    "paramour.config.json",
+];
+/**
+ * @internal Load and validate the project's config file, or `undefined`
+ * when none exists. No upward traversal — the documented contract is three
+ * filenames at the project root (TR7). jiti (the §7.2 loader carry-over) is
+ * imported dynamically so only CLI runs that actually have a `.ts`/`.mjs`
+ * config pay for it; `withTypedRoutes` users never execute it.
+ */
+export async function loadConfigFile(projectRoot) {
+    for (const name of CONFIG_FILE_NAMES) {
+        const path = join(projectRoot, name);
+        if (!existsSync(path))
+            continue;
+        if (name.endsWith(".json")) {
+            const text = readFileSync(path, "utf8");
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (error) {
+                // Name the file: a bare SyntaxError("Unexpected token …") gives the
+                // user nothing to grep for.
+                throw new Error(`${name}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+            return { config: validateConfig(parsed, name), path };
+        }
+        const { createJiti } = await import("jiti");
+        // fsCache off: config files are tiny and user projects shouldn't grow
+        // a transform cache just because the CLI ran.
+        const jiti = createJiti(import.meta.url, {
+            fsCache: false,
+            interopDefault: true,
+        });
+        const mod = await jiti.import(path);
+        const value = typeof mod === "object" && mod !== null && "default" in mod
+            ? mod.default
+            : mod;
+        return { config: validateConfig(value, name), path };
+    }
+    return undefined;
+}
+/**
+ * Hand-rolled validation: a 5-key schema can afford to reject unknown keys —
+ * a silently ignored `pagesExtensions` typo is exactly the footgun this
+ * prevents. Throws with the file and key named; the CLI maps it to exit 2.
+ */
+function validateConfig(value, sourceName) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${sourceName} must export a config object`);
+    }
+    const config = {};
+    for (const [key, entry] of Object.entries(value)) {
+        switch (key) {
+            case "appDir":
+            case "outFile":
+            case "pagesDir": {
+                if (typeof entry !== "string" || entry === "") {
+                    throw new Error(`${sourceName}: \`${key}\` must be a non-empty string`);
+                }
+                config[key] = entry;
+                break;
+            }
+            case "pageExtensions": {
+                if (!Array.isArray(entry) ||
+                    entry.length === 0 ||
+                    !entry.every((ext) => typeof ext === "string" && ext !== "")) {
+                    throw new Error(`${sourceName}: \`pageExtensions\` must be a non-empty array of non-empty strings`);
+                }
+                // A leading dot silently matches nothing (`page..tsx` never exists) —
+                // exactly the class of typo this hand-rolled validation exists for.
+                const dotted = entry.find((ext) => ext.startsWith("."));
+                if (dotted !== undefined) {
+                    throw new Error(`${sourceName}: \`pageExtensions\` entries must not start with a dot: "${dotted}"`);
+                }
+                config.pageExtensions = entry;
+                break;
+            }
+            case "routeFiles": {
+                if (!Array.isArray(entry) ||
+                    entry.length === 0 ||
+                    !entry.every((glob) => typeof glob === "string" && glob !== "")) {
+                    throw new Error(`${sourceName}: \`routeFiles\` must be a non-empty array of non-empty glob strings`);
+                }
+                config.routeFiles = entry;
+                break;
+            }
+            default:
+                throw new Error(`${sourceName}: unknown key \`${key}\``);
+        }
+    }
+    return config;
+}