@nifrajs/cli 4.0.2 → 5.1.0

package/dist/command-catalog.js

@@ -10,7 +10,7 @@ import { formatAssuranceReport } from "./assure.js";
 import { cdnCheckSpec } from "./cdn-check.js";
 import { renderCheckReport } from "./check.js";
 import { dbAuditSpec, dbQuerySpec, dbRoleSpec, dbSchemaSpec } from "./db-tool.js";
-import { errorsSpec, logsSpec } from "./dev-feed-tool.js";
+import { errorsSpec, explainSpec, logsSpec } from "./dev-feed-tool.js";
 import { diagnostic, normalizeSeverity, toSarifLog } from "./diagnostics.js";
 import { i18nCheckPassed, renderI18nCheck } from "./i18n-check.js";
 import { collectPortResult, renderReport } from "./port.js";
@@ -267,14 +267,19 @@ const ROUTES_SCHEMA = input(objectSchema({
     json: { type: "boolean" },
     graph: { type: "boolean" },
     modes: { type: "boolean" },
+    hooks: { type: "boolean" },
+    since: { type: "string" },
     target: { type: "string" },
     dir: { type: "string" },
 }), (value) => {
     const raw = withDir(record(value));
-    if (raw.graph === true && raw.modes === true)
-        throw new TypeError("graph and modes cannot be combined");
+    if ([raw.graph, raw.modes, raw.hooks].filter((flag) => flag === true).length > 1)
+        throw new TypeError("graph, modes and hooks cannot be combined");
+    if (raw.since !== undefined && raw.hooks !== true)
+        throw new TypeError("since compares hook reports and needs hooks");
     return {
-        ...parseBooleanFlags(raw, ["json", "graph", "modes"]),
+        ...parseBooleanFlags(raw, ["json", "graph", "modes", "hooks"]),
+        since: optionalString(raw.since, "since"),
         target: optionalString(raw.target, "target"),
         ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     };
@@ -334,12 +339,13 @@ const MIGRATE_SCHEMA = input(objectSchema({
     from: { type: "string", enum: ["tailwind"] },
     to: { type: "string", enum: ["stylex"] },
     write: { type: "boolean" },
+    zones: { type: "boolean" },
     json: { type: "boolean" },
     dir: { type: "string" },
 }), (value) => {
     const raw = withDir(record(value));
     const flags = {
-        ...parseBooleanFlags(raw, ["write", "json"]),
+        ...parseBooleanFlags(raw, ["write", "zones", "json"]),
         ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     };
     const kind = optionalString(raw.kind, "kind");
@@ -348,6 +354,8 @@ const MIGRATE_SCHEMA = input(objectSchema({
             throw new TypeError("the migration must be `layout` (or --from tailwind --to stylex)");
         return { kind, ...flags };
     }
+    if (raw.zones === true)
+        throw new TypeError("--zones applies to `migrate layout` only");
     const from = optionalString(raw.from, "from");
     const to = optionalString(raw.to, "to");
     if (from !== "tailwind")
@@ -372,6 +380,18 @@ const TYPES_SCHEMA = input(objectSchema({ check: { type: "boolean" }, json: { ty
         ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     };
 });
+const SCHEMAS_SCHEMA = input(objectSchema({
+    write: { type: "boolean" },
+    check: { type: "boolean" },
+    json: { type: "boolean" },
+    dir: { type: "string" },
+}), (value) => {
+    const raw = withDir(record(value));
+    return {
+        ...parseBooleanFlags(raw, ["write", "check", "json"]),
+        ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    };
+});
 const SNAPSHOT_SCHEMA = input(objectSchema({ out: { type: "string" }, json: { type: "boolean" }, dir: { type: "string" } }), (value) => {
     const raw = withDir(record(value));
     return {
@@ -492,10 +512,11 @@ const I18N_SCHEMA = input(objectSchema({
         ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     };
 });
-function loadAppFor(ctx) {
+/** The app as the backend readers see it: an API-only app is its `backend/app.ts` alone. */
+function backendAppFor(ctx) {
     if (ctx.loadApp !== undefined)
-        return ctx.loadApp();
-    return import("./load.js").then(({ loadApp }) => loadApp(ctx.cwd));
+        return ctx.loadApp.backend();
+    return import("./load.js").then(({ loadBackendApp }) => loadBackendApp(ctx.cwd));
 }
 function structuredDiagnostics(out) {
     if (out.structuredDiagnostics !== undefined)
@@ -709,7 +730,7 @@ const manifestSpec = {
 };
 const routesSpec = {
     name: "routes",
-    summary: "List, graph, or target-check every page and API route the app serves.",
+    summary: "List, graph, or target-check every page and API route the app serves, or the hooks each runs.",
     input: ROUTES_SCHEMA,
     output: output({
         type: "object",
@@ -723,12 +744,43 @@ const routesSpec = {
             { name: "json", field: "json", type: "boolean" },
             { name: "graph", field: "graph", type: "boolean" },
             { name: "modes", field: "modes", type: "boolean" },
+            { name: "hooks", field: "hooks", type: "boolean" },
+            { name: "since", field: "since", type: "string" },
             { name: "target", field: "target", type: "string" },
         ],
     },
     async run(value, ctx) {
-        const app = await loadAppFor(ctx);
+        if (value.hooks === true) {
+            const app = await backendAppFor(ctx);
+            const hooks = await import("./hooks-report.js");
+            const report = await hooks.collectHookReport(app.backend);
+            if (value.since === undefined) {
+                return { ok: true, mode: "hooks", data: report, text: hooks.renderHookReport(report) };
+            }
+            const saved = hooks.parseHookReport(await Bun.file(resolve(ctx.cwd, value.since))
+                .text()
+                .catch(() => ""));
+            if (saved === undefined) {
+                return {
+                    ok: false,
+                    mode: "hooks",
+                    data: { report, error: `${value.since} is not a saved hook report` },
+                    text: `[nifra] ${value.since} is not a saved hook report (write one with \`nifra routes --hooks --json\`)`,
+                };
+            }
+            const changes = hooks.diffHookReports(saved, report);
+            return {
+                ok: true,
+                mode: "hooks",
+                data: { report, changes },
+                text: hooks.renderHookDiff(changes),
+            };
+        }
+        const app = await backendAppFor(ctx);
         if (value.modes === true) {
+            if (app.framework === undefined) {
+                throw new Error(`[nifra] routes --modes reads page routes, and ${ctx.cwd} is an API-only app (backend/app.ts, no web config)`);
+            }
             const { buildRouteManifest, renderRouteManifest } = await import("@nifrajs/web/route-manifest");
             const { discoverRoutes } = await import("@nifrajs/web/fs");
             const data = await buildRouteManifest(discoverRoutes(app.routesDir), value.target === undefined ? {} : { target: value.target });
@@ -771,7 +823,7 @@ const contextSpec = {
     async run(value, ctx) {
         return {
             ok: true,
-            text: (await import("./introspect.js")).describeProject(await loadAppFor(ctx), {
+            text: (await import("./introspect.js")).describeProject(await backendAppFor(ctx), {
                 ...(value.path === undefined ? {} : { path: value.path }),
                 ...(value.kind === undefined ? {} : { kind: value.kind }),
             }),
@@ -797,9 +849,7 @@ const openApiSpec = {
         ],
     },
     async run(value, ctx) {
-        const app = ctx.loadApp !== undefined
-            ? await ctx.loadApp()
-            : await import("./load.js").then(({ loadBackendApp }) => loadBackendApp(ctx.cwd));
+        const app = await backendAppFor(ctx);
         const { renderOpenApiWithTypes } = await import("./openapi-tool.js");
         const format = value.format ?? "json";
         return {
@@ -858,6 +908,7 @@ const fixSpec = {
             ok: { type: "boolean" },
             changed: { type: "array" },
             failed: { type: "array" },
+            skipped: { type: "array" },
             diagnostics: { type: "array" },
         },
         required: ["ok", "diagnostics"],
@@ -872,26 +923,38 @@ const fixSpec = {
     },
     async run(value, ctx) {
         const { collectCheckResult } = await import("./check.js");
-        const { applyDiagnosticRecipe } = await import("./fix-recipes.js");
+        const { applyDiagnosticRecipe, getFixRecipe } = await import("./fix-recipes.js");
         const result = await collectCheckResult(ctx.cwd, {
             lintsOnly: true,
             ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
         });
         const changed = [];
         const failed = [];
-        for (const diagnostic of result.structuredDiagnostics ?? [])
-            if (value.code === undefined || diagnostic.code === value.code)
-                // One recipe that cannot act must not cancel the others, and must not pass silently either:
-                // record why and keep going, so a run over many diagnostics still reports every outcome.
-                try {
-                    changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)));
-                }
-                catch (error) {
-                    failed.push({
+        const skipped = [];
+        for (const diagnostic of result.structuredDiagnostics ?? []) {
+            if (value.code !== undefined && diagnostic.code !== value.code)
+                continue;
+            const recipe = diagnostic.fix?.recipe === undefined ? undefined : getFixRecipe(diagnostic.fix.recipe);
+            if (value.code === undefined && recipe?.onlyWhenNamed === true) {
+                if (!skipped.some((entry) => entry.code === diagnostic.code))
+                    skipped.push({
                         code: diagnostic.code,
-                        reason: error instanceof Error ? error.message : String(error),
+                        reason: `${recipe.description} Review the finding, then run \`nifra fix --code ${diagnostic.code}\`.`,
                     });
-                }
+                continue;
+            }
+            // One recipe that cannot act must not cancel the others, and must not pass silently either:
+            // record why and keep going, so a run over many diagnostics still reports every outcome.
+            try {
+                changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)));
+            }
+            catch (error) {
+                failed.push({
+                    code: diagnostic.code,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
         const final = await collectCheckResult(ctx.cwd, {
             lintsOnly: true,
             ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
@@ -900,6 +963,7 @@ const fixSpec = {
             ok: final.ok,
             changed,
             failed,
+            skipped,
             diagnostics: final.structuredDiagnostics ?? final.diagnostics,
         };
     },
@@ -907,6 +971,7 @@ const fixSpec = {
         out.ok ? "✓ fixes applied" : "✖ unresolved diagnostics remain",
         ...out.changed.map((file) => `  changed ${file}`),
         ...out.failed.map((f) => `  could not fix ${f.code}: ${f.reason}`),
+        ...out.skipped.map((s) => `  needs review ${s.code}: ${s.reason}`),
         ...out.diagnostics.map((d) => `  ${String(d.code ?? "diagnostic")}`),
     ],
     success: (out) => out.ok,
@@ -931,6 +996,9 @@ const migrateSpec = {
             splits: { type: "array" },
             moves: { type: "array" },
             rewritten: { type: "array" },
+            tooling: { type: "array" },
+            followUps: { type: "array" },
+            mode: { type: "string" },
         },
         required: ["ok", "write", "issues"],
     }),
@@ -942,6 +1010,7 @@ const migrateSpec = {
             { name: "from", field: "from", type: "string" },
             { name: "to", field: "to", type: "string" },
             { name: "write", field: "write", type: "boolean" },
+            { name: "zones", field: "zones", type: "boolean" },
             { name: "json", field: "json", type: "boolean" },
             { name: "dir", field: "dir", type: "string" },
         ],
@@ -951,7 +1020,8 @@ const migrateSpec = {
         const write = value.write === undefined ? {} : { write: value.write };
         if (value.kind === "layout") {
             const { migrateLayout } = await import("./migrate-layout.js");
-            return { kind: "layout", ...(await migrateLayout(dir, write)) };
+            const options = { ...write, zones: value.zones === true };
+            return { kind: "layout", ...(await migrateLayout(dir, options)) };
         }
         const { migrateTailwindToStylex } = await import("./stylex-migrate.js");
         return migrateTailwindToStylex(dir, write);
@@ -960,12 +1030,17 @@ const migrateSpec = {
         if (out.kind === "layout") {
             return [
                 out.ok
-                    ? `✓ ${out.splits.length} route file${out.splits.length === 1 ? "" : "s"} split, ${out.moves.length} file${out.moves.length === 1 ? "" : "s"} moved`
+                    ? `✓ ${out.mode === "api" ? "API-only app" : `${out.splits.length} route file${out.splits.length === 1 ? "" : "s"} split`}, ${out.moves.length} file${out.moves.length === 1 ? "" : "s"} moved`
                     : `⚠ ${out.issues.length} issue${out.issues.length === 1 ? "" : "s"} need a decision; everything else is planned`,
-                ...out.splits.map((split) => `  split ${split.file} → ${split.backend} (${split.moved.join(", ")})`),
+                ...out.splits.map((split) => `  split ${split.file} → ${split.backend} (${split.moved.join(", ")})${split.shared === undefined ? "" : `, shared data → ${split.shared}`}`),
                 ...out.moves.map((move) => `  move  ${move.from} → ${move.to}`),
                 ...out.rewritten.map((file) => `  edit  ${file} (imports)`),
+                ...out.tooling.map((edit) => `  edit  ${edit.file} (${edit.change})`),
+                ...out.schemas
+                    .filter((entry) => entry.reason === undefined)
+                    .map((entry) => `  draft ${entry.file} ${entry.schema} - review what it lets the browser see${entry.omitted === undefined ? "" : `; leaves out ${entry.omitted.join(", ")}`}${entry.open === undefined ? "" : `; admits any value at ${entry.open.join(", ")}, typed any or unknown`}`),
                 ...out.issues.map((issue) => `  ⚠ ${issue.file}: ${issue.reason}`),
+                ...out.followUps.map((step) => `  next  ${step.file}: ${step.reason} - \`${step.command}\``),
                 ...(out.write ? [] : ["  dry run: pass --write to apply"]),
             ];
         }
@@ -1078,6 +1153,82 @@ const typesSpec = {
     ],
     success: (out) => out.ok,
 };
+const SCHEMA_STATUS_LINE = {
+    missing: "+ would write",
+    generated: "+ wrote",
+    stale: "↻ stale",
+    regenerated: "↻ rewrote",
+    current: "✓ current",
+    declared: "· hand-written",
+    "no-data": "· no data",
+    unreadable: "⚠ unreadable",
+};
+const schemasSpec = {
+    name: "schemas",
+    summary: "Write a reviewable `loaderOutput`/`actionOutput` from the loader's or action's return type where a route has none (`--write`), keep generated ones current, and list returned fields a hand-written schema drops.",
+    input: SCHEMAS_SCHEMA,
+    output: output({
+        type: "object",
+        properties: {
+            ok: { type: "boolean" },
+            write: { type: "boolean" },
+            entries: { type: "array" },
+            written: { type: "array" },
+            warnings: { type: "array" },
+        },
+        required: ["ok", "write", "entries", "written", "warnings"],
+    }),
+    transports: ["cli"],
+    stability: "stable",
+    argv: {
+        flags: [
+            { name: "write", field: "write", type: "boolean" },
+            { name: "check", field: "check", type: "boolean" },
+            { name: "json", field: "json", type: "boolean" },
+            { name: "dir", field: "dir", type: "string" },
+        ],
+    },
+    async run(value, ctx) {
+        const { outputSchemas } = await import("./output-schemas.js");
+        return outputSchemas(resolve(ctx.cwd, value.dir ?? "."), {
+            write: value.write === true,
+            check: value.check === true,
+        });
+    },
+    render: (out) => {
+        const shown = out.entries.filter((entry) => (entry.status !== "current" || entry.open !== undefined) &&
+            entry.status !== "no-data" &&
+            (entry.status !== "declared" || entry.dropped.length > 0));
+        const current = out.entries.filter((entry) => entry.status === "current").length;
+        return [
+            ...out.warnings.map((warning) => `⚠ ${warning}`),
+            `${out.ok ? "✓" : "✖"} ${out.entries.length} output schema${out.entries.length === 1 ? "" : "s"} read, ${current} generated and current`,
+            ...shown.map((entry) => {
+                const detail = entry.reason ??
+                    (entry.edited === true
+                        ? "edited by hand under its nifra:generated line"
+                        : entry.dropped.length > 0
+                            ? `drops ${entry.dropped.join(", ")}`
+                            : entry.omitted !== undefined
+                                ? `leaves out ${entry.omitted.join(", ")}`
+                                : undefined);
+                const open = entry.open === undefined
+                    ? []
+                    : [
+                        `      admits any value at ${entry.open.join(", ")}: the type there is any or unknown, so the output guard drops nothing below it`,
+                    ];
+                return [
+                    `  ${SCHEMA_STATUS_LINE[entry.status]} ${entry.file}:${entry.line} ${entry.schema}${detail === undefined ? "" : ` - ${detail}`}`,
+                    ...open,
+                ].join("\n");
+            }),
+            ...(out.write || !out.entries.some((e) => e.status === "missing" || e.status === "stale")
+                ? []
+                : ["  dry run: pass --write to apply"]),
+        ];
+    },
+    success: (out) => out.ok,
+};
 const snapshotSpec = {
     name: "snapshot",
     summary: "Write the backend API contract as a versioned JSON baseline.",
@@ -1102,11 +1253,9 @@ const snapshotSpec = {
     },
     async run(value, ctx) {
         const mod = await import("./diff-tool.js");
-        const routes = await mod.snapshotBackend(ctx.cwd);
         const file = value.out ?? mod.DEFAULT_SNAPSHOT_FILE;
-        const snapshot = { nifraSnapshot: 1, routes };
-        await Bun.write(resolve(ctx.cwd, file), `${JSON.stringify(snapshot, null, 2)}\n`);
-        return { ok: true, file, routes: routes.length, snapshot };
+        const snapshot = await mod.writeSnapshot(ctx.cwd, file);
+        return { ok: true, file, routes: snapshot.routes.length, snapshot };
     },
     render: (out) => [
         `[nifra] wrote ${out.routes} route${out.routes === 1 ? "" : "s"} to ${out.file}`,
@@ -1129,19 +1278,17 @@ const diffSpec = {
     stability: "stable",
     argv: { positionals: ["baseline"], flags: [{ name: "json", field: "json", type: "boolean" }] },
     async run(value, ctx) {
-        const mod = await import("./diff-tool.js");
-        const baseline = value.baseline ?? mod.DEFAULT_SNAPSHOT_FILE;
-        const file = await Bun.file(resolve(ctx.cwd, baseline)).text();
-        const before = mod.parseSnapshotFile(file, baseline);
-        const current = await mod.snapshotBackend(ctx.cwd);
-        const { diffRouteSnapshots } = await import("@nifrajs/core/diff");
-        const diff = diffRouteSnapshots(before.routes, current);
-        return { ok: !diff.hasBreaking, hasBreaking: diff.hasBreaking, changes: diff.changes };
+        const { diffAgainstBaseline, formatDiff } = await import("./diff-tool.js");
+        const diff = await diffAgainstBaseline(ctx.cwd, value.baseline);
+        return {
+            ok: !diff.hasBreaking,
+            hasBreaking: diff.hasBreaking,
+            changes: diff.changes,
+            text: formatDiff(diff),
+        };
     },
-    render: (out) => [
-        out.ok ? "✓ no breaking changes" : "✖ breaking changes",
-        ...out.changes.map((c) => `${c.method} ${c.path}: ${c.message}`),
-    ],
+    render: (out) => [out.text],
+    json: ({ ok, hasBreaking, changes }) => ({ ok, hasBreaking, changes }),
     success: (out) => out.ok,
 };
 const contractsSpec = {
@@ -1354,6 +1501,7 @@ export const commandSpecs = Object.freeze([
     migrateSpec,
     targetSpec,
     typesSpec,
+    schemasSpec,
     snapshotSpec,
     diffSpec,
     contractsSpec,
@@ -1365,6 +1513,7 @@ export const commandSpecs = Object.freeze([
     portSpec,
     i18nSpec,
     errorsSpec,
+    explainSpec,
     logsSpec,
     cdnCheckSpec,
     dbSchemaSpec,