@nifrajs/cli 2.2.0 → 2.3.0

package/dist/scaffold.js

@@ -1,10 +1,10 @@
 /**
- * `nifra_scaffold` — turn a URL path into the correct `routes/` file (the convention an agent most often
+ * `nifra_scaffold` - turn a URL path into the correct `routes/` file (the convention an agent most often
  * gets wrong) + a minimal, contract-correct stub. The mapping is the inverse of @nifrajs/web's
  * `filePathToPatterns`: `:id`/`[id]` → `[id]`, `*rest`/`[...rest]` → `[...rest]`, `[[lang]]` optional,
  * `/` → `index`. The framework (→ file extension) comes from the project's `clientModule`.
  *
- * Page stubs are emitted only for the JSX family (react/preact/solid — one shared, verified shape);
+ * Page stubs are emitted only for the JSX family (react/preact/solid - one shared, verified shape);
  * for vue/svelte/vanilla we return the correct PATH + the route-module contract and point at
  * `nifra_example` for the body, rather than hand-writing an SFC we can't typecheck here.
  */
@@ -49,17 +49,17 @@ export function routePathToFile(urlPath, ext) {
     return `routes/${segments.map(segmentToFile).join("/")}.${ext}`;
 }
 const ROUTE_CONTRACT = `A route module may export:
-- \`export default function Page(props: { data: LoaderData<typeof loader> }) { … }\` — the page component.
-- \`export async function loader({ params, request, api }: LoaderArgs<typeof backend>) { … }\` — server-only; data for SSR. Reach the backend via \`api\` (typed) / DB via the backend, NEVER a top-level server-only import.
-- \`export async function action({ request, api }: ActionArgs<typeof backend>) { … }\` — server-only; handles the form POST.
-- \`export const meta = { title, meta:[…] }\` — head tags.
+- \`export default function Page(props: { data: LoaderData<typeof loader> }) { … }\` - the page component.
+- \`export async function loader({ params, request, api }: LoaderArgs<typeof backend>) { … }\` - server-only; data for SSR. Reach the backend via \`api\` (typed) / DB via the backend, NEVER a top-level server-only import.
+- \`export async function action({ request, api }: ActionArgs<typeof backend>) { … }\` - server-only; handles the form POST.
+- \`export const meta = { title, meta:[…] }\` - head tags.
 Path params are typed on \`params\`.`;
 function jsxStub(file, params) {
     const paramsNote = params.length > 0 ? `params.${params.join(", params.")}` : "no path params on this route";
     const loaderLine = params.length > 0
         ? `// export async function loader({ params, api }: LoaderArgs<typeof backend>) { return { /* fetch by ${params[0]} */ } }`
         : `// export async function loader({ api }: LoaderArgs<typeof backend>) { return {} }`;
-    return `// ${file} — server-only loader/action allowed; never top-level-import server-only code (DB/secrets).
+    return `// ${file} - server-only loader/action allowed; never top-level-import server-only code (DB/secrets).
 // Available here: ${paramsNote}. Fetch data in a loader via the typed \`api\`; see nifra_example("loader").
 ${loaderLine}
 export default function Page() {
@@ -125,7 +125,7 @@ export async function writeScaffoldRoute(cwd, urlPath, framework) {
     }
     return { ...result, written: true };
 }
-/** Render the tool result as markdown — the file path, the stub (if any), and the contract note. */
+/** Render the tool result as markdown - the file path, the stub (if any), and the contract note. */
 export function renderScaffold(urlPath, framework) {
     let r;
     try {

package/dist/sync-routes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `nifra sync-routes` - regenerate the route-search types (`nifra-routes.d.ts`) from the current `routes/`
+ * tree, so `navigate({ to, search })` is typed against each static route's `searchSchema`. It runs
+ * `@nifrajs/web`'s `generateRouteSearchTypes` over the discovered routes and writes the `.d.ts` at the
+ * project root; include it in your tsconfig's `include`. Because it is regenerated from the route files, a
+ * stale navigate search shape becomes a `tsc` error - run it after adding/renaming a route or changing a
+ * `searchSchema` (a pure file write, no build). A dynamic route (`:param`/catch-all) is omitted, since its
+ * pattern is not a concrete `to`; those keep the loose object form.
+ */
+/** The committed route-types file `sync-routes` writes, so `nifra check` can recognise + drift-check it. */
+export declare const ROUTE_TYPES_FILE = "nifra-routes.d.ts";
+export interface SyncRoutesResult {
+    /** The written `.d.ts` (relative to the project root). */
+    readonly file: string;
+    /** True when the file's content changed and it was rewritten. */
+    readonly changed: boolean;
+    /** How many static routes got a typed entry. */
+    readonly typedRoutes: number;
+}
+/**
+ * Generate the route-search types `.d.ts` from `<cwd>/routes` (the nifra convention). Returns `null` when
+ * there is no `routes/` directory (an API-only project - nothing to type). Never loads `framework.ts`: it
+ * needs only the route tree, so it works before a build and on a broken framework config.
+ */
+export declare function syncRouteTypes(cwd: string): Promise<SyncRoutesResult | null>;
+/** CLI entry: write/refresh the route-types file and print a one-line summary + the tsconfig reminder. */
+export declare function runSyncRoutes(cwd: string): Promise<boolean>;
+//# sourceMappingURL=sync-routes.d.ts.map

package/dist/sync-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-routes.d.ts","sourceRoot":"","sources":["../src/sync-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,4GAA4G;AAC5G,eAAO,MAAM,gBAAgB,sBAAsB,CAAA;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAkBlF;AAED,0GAA0G;AAC1G,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBjE"}

package/dist/sync-routes.js

@@ -0,0 +1,55 @@
+/**
+ * `nifra sync-routes` - regenerate the route-search types (`nifra-routes.d.ts`) from the current `routes/`
+ * tree, so `navigate({ to, search })` is typed against each static route's `searchSchema`. It runs
+ * `@nifrajs/web`'s `generateRouteSearchTypes` over the discovered routes and writes the `.d.ts` at the
+ * project root; include it in your tsconfig's `include`. Because it is regenerated from the route files, a
+ * stale navigate search shape becomes a `tsc` error - run it after adding/renaming a route or changing a
+ * `searchSchema` (a pure file write, no build). A dynamic route (`:param`/catch-all) is omitted, since its
+ * pattern is not a concrete `to`; those keep the loose object form.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/** The committed route-types file `sync-routes` writes, so `nifra check` can recognise + drift-check it. */
+export const ROUTE_TYPES_FILE = "nifra-routes.d.ts";
+/**
+ * Generate the route-search types `.d.ts` from `<cwd>/routes` (the nifra convention). Returns `null` when
+ * there is no `routes/` directory (an API-only project - nothing to type). Never loads `framework.ts`: it
+ * needs only the route tree, so it works before a build and on a broken framework config.
+ */
+export async function syncRouteTypes(cwd) {
+    const routesDir = join(cwd, "routes");
+    if (!existsSync(routesDir))
+        return null;
+    const { discoverRoutes } = await import("@nifrajs/web/fs");
+    const { generateRouteSearchTypes } = await import("@nifrajs/web");
+    const manifest = discoverRoutes(routesDir);
+    const code = generateRouteSearchTypes(manifest, {
+        // A route file is relative to routesDir (`reports.tsx`, `users/index.tsx`); the `.d.ts` sits at the
+        // project root, so the `typeof import(...)` specifier is `./routes/<file без extension>`.
+        resolve: (file) => `./routes/${file.replace(/\.[^./]+$/, "")}`,
+    });
+    const outFile = join(cwd, ROUTE_TYPES_FILE);
+    const existing = await Bun.file(outFile)
+        .text()
+        .catch(() => "");
+    const changed = existing !== code;
+    if (changed)
+        await Bun.write(outFile, code);
+    return { file: ROUTE_TYPES_FILE, changed, typedRoutes: (code.match(/: SearchOf</g) ?? []).length };
+}
+/** CLI entry: write/refresh the route-types file and print a one-line summary + the tsconfig reminder. */
+export async function runSyncRoutes(cwd) {
+    const result = await syncRouteTypes(cwd);
+    if (result === null) {
+        console.log("nifra sync-routes: no routes/ directory found. Run from your project root.");
+        return true;
+    }
+    const n = result.typedRoutes;
+    const routes = `${n} typed route${n === 1 ? "" : "s"}`;
+    console.log(result.changed
+        ? `✓ wrote ${result.file} (${routes})`
+        : `• ${result.file} already in sync (${routes})`);
+    console.log("  Include it in your tsconfig's `include` so `navigate({ to, search })` is typed per route.");
+    return true;
+}
+//# sourceMappingURL=sync-routes.js.map

package/dist/sync-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-routes.js","sourceRoot":"","sources":["../src/sync-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,4GAA4G;AAC5G,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAA;AAWnD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IACrC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAA;IACvC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAA;IAC1D,MAAM,EAAE,wBAAwB,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAA;IACjE,MAAM,QAAQ,GAAG,cAAc,CAAC,SAAS,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,wBAAwB,CAAC,QAAQ,EAAE;QAC9C,oGAAoG;QACpG,0FAA0F;QAC1F,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE;KAC/D,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAA;IAC3C,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;SACrC,IAAI,EAAE;SACN,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAClB,MAAM,OAAO,GAAG,QAAQ,KAAK,IAAI,CAAA;IACjC,IAAI,OAAO;QAAE,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC3C,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;AACpG,CAAC;AAED,0GAA0G;AAC1G,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;IACxC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,4EAA4E,CAAC,CAAA;QACzF,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,CAAA;IAC5B,MAAM,MAAM,GAAG,GAAG,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAA;IACtD,OAAO,CAAC,GAAG,CACT,MAAM,CAAC,OAAO;QACZ,CAAC,CAAC,WAAW,MAAM,CAAC,IAAI,KAAK,MAAM,GAAG;QACtC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,qBAAqB,MAAM,GAAG,CACnD,CAAA;IACD,OAAO,CAAC,GAAG,CACT,6FAA6F,CAC9F,CAAA;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/types-search.d.ts

@@ -1,7 +1,7 @@
 /**
- * `nifra_types` — the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`
+ * `nifra_types` - the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`
  * (written into this package by `bun run gen:llms`): each entry's `signature` is the literal declaration
- * parsed from the package's BUILT `.d.ts` with the TS compiler — a clean signature, never prose, never
+ * parsed from the package's BUILT `.d.ts` with the TS compiler - a clean signature, never prose, never
  * truncated. So an agent that needs the precise shape of a type (`RateLimitStore`, `RouteSchema`, a
  * function signature) gets the authoritative source here and never has to read a `.d.ts` file.
  *
@@ -12,7 +12,7 @@ export interface TypeEntry {
     readonly name: string;
     readonly kind: "interface" | "type" | "class" | "function" | "enum" | "const";
     readonly package: string;
-    /** The literal declaration text from the `.d.ts` — a clean signature, no implementation. */
+    /** The literal declaration text from the `.d.ts` - a clean signature, no implementation. */
     readonly signature: string;
     /** The declaration's JSDoc block, if any. */
     readonly doc?: string;
@@ -20,7 +20,7 @@ export interface TypeEntry {
 export interface ScoredType extends TypeEntry {
     readonly score: number;
 }
-/** Exact (case-insensitive) name lookup — returns every declaration with that name (a name can exist in
+/** Exact (case-insensitive) name lookup - returns every declaration with that name (a name can exist in
  * more than one package). */
 export declare function lookupType(types: readonly TypeEntry[], name: string): TypeEntry[];
 /** Keyword-score types: a term in the name is worth far more than one in the signature/doc body. */
@@ -28,7 +28,7 @@ export declare function searchTypes(types: readonly TypeEntry[], query: string,
 /**
  * Render the tool result. `name` → the exact declaration(s); else `query` → the top matches; else a
  * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),
- * so this is the complete answer — there is no need to read a `.d.ts` file.
+ * so this is the complete answer - there is no need to read a `.d.ts` file.
  */
 export declare function renderTypesResult(types: readonly TypeEntry[], name: string | undefined, query: string | undefined, limit: number, full?: boolean): string;
 /** Load the bundled type corpus (`docs/types.json`), resolved relative to this module so it works from

package/dist/types-search.js

@@ -1,7 +1,7 @@
 /**
- * `nifra_types` — the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`
+ * `nifra_types` - the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`
  * (written into this package by `bun run gen:llms`): each entry's `signature` is the literal declaration
- * parsed from the package's BUILT `.d.ts` with the TS compiler — a clean signature, never prose, never
+ * parsed from the package's BUILT `.d.ts` with the TS compiler - a clean signature, never prose, never
  * truncated. So an agent that needs the precise shape of a type (`RateLimitStore`, `RouteSchema`, a
  * function signature) gets the authoritative source here and never has to read a `.d.ts` file.
  *
@@ -9,7 +9,7 @@
  * signature/doc body; no args → a per-package index of the available type names.
  */
 import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-terms.js";
-/** Exact (case-insensitive) name lookup — returns every declaration with that name (a name can exist in
+/** Exact (case-insensitive) name lookup - returns every declaration with that name (a name can exist in
  * more than one package). */
 export function lookupType(types, name) {
     const wanted = name.trim().toLowerCase();
@@ -36,7 +36,7 @@ export function searchTypes(types, query, limit) {
     return scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
 }
 function renderEntry(t) {
-    const head = `## ${t.name} — ${t.kind}, \`${t.package}\``;
+    const head = `## ${t.name} - ${t.kind}, \`${t.package}\``;
     const doc = t.doc ? `${t.doc}\n` : "";
     return `${head}\n\n\`\`\`ts\n${doc}${t.signature}\n\`\`\``;
 }
@@ -76,7 +76,7 @@ function collapseSignature(signature) {
 }
 /** A search hit: enough to choose, not the whole declaration. */
 function renderSearchHit(t) {
-    const head = `## ${t.name} — ${t.kind}, \`${t.package}\``;
+    const head = `## ${t.name} - ${t.kind}, \`${t.package}\``;
     const summary = summarize(t.doc);
     const signature = t.signature.length <= SEARCH_SIGNATURE_MAX ? t.signature : collapseSignature(t.signature);
     const note = t.signature.length <= SEARCH_SIGNATURE_MAX
@@ -87,7 +87,7 @@ function renderSearchHit(t) {
 /**
  * Render the tool result. `name` → the exact declaration(s); else `query` → the top matches; else a
  * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),
- * so this is the complete answer — there is no need to read a `.d.ts` file.
+ * so this is the complete answer - there is no need to read a `.d.ts` file.
  */
 export function renderTypesResult(types, name, query, limit, full = false) {
     if (name !== undefined && name.trim() !== "") {
@@ -115,7 +115,7 @@ export function renderTypesResult(types, name, query, limit, full = false) {
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([pkg, names]) => `- **${pkg}**: ${names.sort().join(", ")}`)
         .join("\n");
-    return `# nifra types — index (${types.length} exported symbols; pass \`name\` for the exact declaration, or \`query\` to search)\n\nSignatures are generated from the built \`.d.ts\` — authoritative + complete. Use this instead of reading any \`.d.ts\` file.\n\n${index}`;
+    return `# nifra types - index (${types.length} exported symbols; pass \`name\` for the exact declaration, or \`query\` to search)\n\nSignatures are generated from the built \`.d.ts\` - authoritative + complete. Use this instead of reading any \`.d.ts\` file.\n\n${index}`;
 }
 /** Load the bundled type corpus (`docs/types.json`), resolved relative to this module so it works from
  * `src/` (dev) and `dist/` (published) alike. */

package/dist/upgrade.d.ts

@@ -1,20 +1,20 @@
 /**
- * `nifra upgrade <version>` — an executable, per-release upgrade runner. Framework and shared-package
+ * `nifra upgrade <version>` - an executable, per-release upgrade runner. Framework and shared-package
  * bumps otherwise spread the same mechanical edits across every consuming app by hand; a recipe turns
  * them into `detect → transform → verify`:
  *
- *   1. **pin sweep** — set every matching dependency to the target version across the workspace's
+ *   1. **pin sweep** - set every matching dependency to the target version across the workspace's
  *      package.json files, preserving the caret/tilde/exact style and skipping `workspace:`/`link:` specs.
- *   2. **dependency moves** — replace removed packages with their supported successor without
+ *   2. **dependency moves** - replace removed packages with their supported successor without
  *      reserializing package.json or leaving duplicate dependency keys.
- *   3. **import moves** — rewrite exact import specifiers to their updated module paths.
- *   4. **verify** — reuse the existing `nifra check` gate; no new verification surface.
+ *   3. **import moves** - rewrite exact import specifiers to their updated module paths.
+ *   4. **verify** - reuse the existing `nifra check` gate; no new verification surface.
  *
  * Dry-run by default (prints the plan, writes nothing); `--write` applies. Fail-closed on an unknown
  * target version or a missing package.json, and deterministic (same repo + target → same edits).
  *
  * Deliberately NOT a codemod engine: transforms are string/specifier-level only. Structural (AST)
- * transforms are a future addition — a recipe that needs one is the signal to add the engine, not before.
+ * transforms are a future addition - a recipe that needs one is the signal to add the engine, not before.
  */
 import { type UpgradeRecipe } from "./recipes/index.js";
 export interface UpgradeOptions {
@@ -64,7 +64,7 @@ export interface UpgradePlan {
  */
 export declare function rewriteVersionSpec(spec: string, toVersion: string): string | null;
 /**
- * Apply pin rules to one package.json's TEXT (format-preserving — targeted string replaces, never a
+ * Apply pin rules to one package.json's TEXT (format-preserving - targeted string replaces, never a
  * JSON re-serialize that would reorder keys or drop comments-as-formatting). Returns the new text and
  * the changes made.
  */

package/dist/upgrade.js

@@ -1,20 +1,20 @@
 /**
- * `nifra upgrade <version>` — an executable, per-release upgrade runner. Framework and shared-package
+ * `nifra upgrade <version>` - an executable, per-release upgrade runner. Framework and shared-package
  * bumps otherwise spread the same mechanical edits across every consuming app by hand; a recipe turns
  * them into `detect → transform → verify`:
  *
- *   1. **pin sweep** — set every matching dependency to the target version across the workspace's
+ *   1. **pin sweep** - set every matching dependency to the target version across the workspace's
  *      package.json files, preserving the caret/tilde/exact style and skipping `workspace:`/`link:` specs.
- *   2. **dependency moves** — replace removed packages with their supported successor without
+ *   2. **dependency moves** - replace removed packages with their supported successor without
  *      reserializing package.json or leaving duplicate dependency keys.
- *   3. **import moves** — rewrite exact import specifiers to their updated module paths.
- *   4. **verify** — reuse the existing `nifra check` gate; no new verification surface.
+ *   3. **import moves** - rewrite exact import specifiers to their updated module paths.
+ *   4. **verify** - reuse the existing `nifra check` gate; no new verification surface.
  *
  * Dry-run by default (prints the plan, writes nothing); `--write` applies. Fail-closed on an unknown
  * target version or a missing package.json, and deterministic (same repo + target → same edits).
  *
  * Deliberately NOT a codemod engine: transforms are string/specifier-level only. Structural (AST)
- * transforms are a future addition — a recipe that needs one is the signal to add the engine, not before.
+ * transforms are a future addition - a recipe that needs one is the signal to add the engine, not before.
  */
 import { readFileSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
@@ -26,8 +26,8 @@ const DEP_FIELDS = [
     "peerDependencies",
     "optionalDependencies",
 ];
-// Only a bare semver spec is rewritten. Anything else — workspace:*, link:/file:, npm: aliases, git
-// urls, "*", "latest", or a multi-part range — is intentionally left untouched (skipped, not guessed).
+// Only a bare semver spec is rewritten. Anything else - workspace:*, link:/file:, npm: aliases, git
+// urls, "*", "latest", or a multi-part range - is intentionally left untouched (skipped, not guessed).
 const SEMVER_SPEC = /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 /**
  * Rewrite a dependency version spec to `toVersion`, preserving the range operator (`^`, `~`, …).
@@ -43,7 +43,7 @@ export function rewriteVersionSpec(spec, toVersion) {
 }
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 /**
- * Apply pin rules to one package.json's TEXT (format-preserving — targeted string replaces, never a
+ * Apply pin rules to one package.json's TEXT (format-preserving - targeted string replaces, never a
  * JSON re-serialize that would reorder keys or drop comments-as-formatting). Returns the new text and
  * the changes made.
  */
@@ -268,7 +268,7 @@ function renderPlan(plan, write) {
     if (plan.pins.length === 0 &&
         plan.dependencyMoves.length === 0 &&
         plan.importMoves.length === 0) {
-        lines.push("Already up to date — no changes.");
+        lines.push("Already up to date - no changes.");
         return lines.join("\n");
     }
     if (plan.dependencyMoves.length > 0) {
@@ -325,7 +325,7 @@ export async function runUpgrade(cwd, options) {
         readFileSync(join(cwd, "package.json"), "utf8");
     }
     catch {
-        console.error(`[nifra] no package.json in ${relative(process.cwd(), cwd) || "."} — run from a project root`);
+        console.error(`[nifra] no package.json in ${relative(process.cwd(), cwd) || "."} - run from a project root`);
         return false;
     }
     const write = options.write === true;
@@ -342,7 +342,7 @@ export async function runUpgrade(cwd, options) {
         const ok = await runCheck(cwd, { json: false });
         if (!ok) {
             if (!options.json)
-                console.error("\n[nifra] upgrade applied but `nifra check` failed — review above.");
+                console.error("\n[nifra] upgrade applied but `nifra check` failed - review above.");
             return false;
         }
     }

package/dist/verification.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One project verification, four commands. `nifra check`, `nifra assure`, `nifra levels`, and
+ * `nifra capabilities` are not separate audits - they are renderings of the same reflected project: the
+ * typed-contract scan, the route-assurance evaluation, and the static capability provenance. Historically
+ * each command re-derived the slice it needed, so a caller had to know which command ran which policy (and
+ * `levels` paid for the capability walk twice). `collectProjectVerification` runs each underlying policy
+ * exactly once and hands back a single value; the commands become thin formatters over subsets of it -
+ * `check`/`assure`/`levels` read their view directly, and `capabilities snapshot`/`check` read the same
+ * capability report before writing or diffing the lockfile.
+ *
+ * The typed-contract check is the one heavy pass (source walk + optional `tsc`), and `nifra assure`
+ * never needs it, so it is exposed as a lazily-invoked `check()` rather than computed up front.
+ */
+import { type AssuranceConfig, type AssuranceReport } from "@nifrajs/core/assurance";
+import { type CapabilityProjectReport } from "./capabilities-tool.js";
+import { type CheckResult } from "./check.js";
+export interface CollectProjectVerificationOptions {
+    /** Assurance config path, default `nifra.assurance.ts`. Honored by the assurance + levels views. */
+    readonly config?: string;
+    /** Skip the `tsc` pass in the check view (the agent inner-loop mode). */
+    readonly lintsOnly?: boolean;
+    /** Cancels the check view's typecheck. */
+    readonly signal?: AbortSignal;
+    /** Cap the check view's diagnostics (the `levels` L0 and MCP paths set this). */
+    readonly maxDiagnostics?: number;
+}
+export interface ProjectVerification {
+    readonly cwd: string;
+    /** Whether `nifra.assurance.ts` (or the requested `config` path) exists. */
+    readonly assuranceConfigPresent: boolean;
+    /** The loaded assurance config, when it loaded cleanly. */
+    readonly config?: AssuranceConfig;
+    /** The error from loading/evaluating the config, if any; the assurance views surface or throw it. */
+    readonly configError?: unknown;
+    /** `evaluateRouteAssurance` over the config's source + policy. Present whenever {@link config} is. */
+    readonly routeAssurance?: AssuranceReport;
+    /** Static capability provenance, when the config declares a capabilities policy. */
+    readonly capability?: CapabilityProjectReport;
+    /**
+     * The typed-contract check (scanners + typecheck + the assurance-fed capability/manifest diagnostics).
+     * Lazy and memoized: `nifra assure` never calls it, so that command pays nothing for the source walk.
+     */
+    check(): Promise<CheckResult>;
+}
+/**
+ * Run each verification policy once and return the unified value. The config is loaded (and reflected)
+ * a single time; the resulting route-assurance + capability evidence is both returned for the assurance
+ * views and fed into the check view, so nothing is computed twice.
+ */
+export declare function collectProjectVerification(cwd: string, options?: CollectProjectVerificationOptions): Promise<ProjectVerification>;
+//# sourceMappingURL=verification.d.ts.map

package/dist/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../src/verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAA8B,KAAK,WAAW,EAAsB,MAAM,YAAY,CAAA;AAE7F,MAAM,WAAW,iCAAiC;IAChD,oGAAoG;IACpG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAA;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,qGAAqG;IACrG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,sGAAsG;IACtG,QAAQ,CAAC,cAAc,CAAC,EAAE,eAAe,CAAA;IACzC,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAA;IAC7C;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,mBAAmB,CAAC,CAyD9B"}

package/dist/verification.js

@@ -0,0 +1,80 @@
+/**
+ * One project verification, four commands. `nifra check`, `nifra assure`, `nifra levels`, and
+ * `nifra capabilities` are not separate audits - they are renderings of the same reflected project: the
+ * typed-contract scan, the route-assurance evaluation, and the static capability provenance. Historically
+ * each command re-derived the slice it needed, so a caller had to know which command ran which policy (and
+ * `levels` paid for the capability walk twice). `collectProjectVerification` runs each underlying policy
+ * exactly once and hands back a single value; the commands become thin formatters over subsets of it -
+ * `check`/`assure`/`levels` read their view directly, and `capabilities snapshot`/`check` read the same
+ * capability report before writing or diffing the lockfile.
+ *
+ * The typed-contract check is the one heavy pass (source walk + optional `tsc`), and `nifra assure`
+ * never needs it, so it is exposed as a lazily-invoked `check()` rather than computed up front.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { evaluateRouteAssurance, } from "@nifrajs/core/assurance";
+import { collectCapabilityProjectReport, } from "./capabilities-tool.js";
+import { collectCheckResult } from "./check.js";
+/**
+ * Run each verification policy once and return the unified value. The config is loaded (and reflected)
+ * a single time; the resulting route-assurance + capability evidence is both returned for the assurance
+ * views and fed into the check view, so nothing is computed twice.
+ */
+export async function collectProjectVerification(cwd, options = {}) {
+    const { loadAssuranceConfig, DEFAULT_ASSURANCE_CONFIG } = await import("./assure.js");
+    const configPath = resolve(cwd, options.config ?? DEFAULT_ASSURANCE_CONFIG);
+    const assuranceConfigPresent = existsSync(configPath);
+    let config;
+    let configError;
+    let routeAssurance;
+    let capability;
+    // One try mirrors `check`'s single catch: any failure to load or reflect the config becomes the
+    // `configError` each view then renders in its own idiom (a diagnostic, a throw, a failed rung).
+    try {
+        config = await loadAssuranceConfig(cwd, options.config);
+        routeAssurance = evaluateRouteAssurance(config.source, config.policy, {
+            ...(config.capabilities !== undefined
+                ? { definitions: config.capabilities.definitions }
+                : {}),
+        });
+        if (config.capabilities !== undefined) {
+            capability = await collectCapabilityProjectReport(cwd, config.source, config.capabilities);
+        }
+    }
+    catch (error) {
+        configError = error;
+        config = undefined;
+        routeAssurance = undefined;
+        capability = undefined;
+    }
+    // The check view's assurance inputs. Fed to `check()` only when no custom config path was requested,
+    // so `nifra check` (which always reads the default `nifra.assurance.ts`) and `levels` L0 keep reading
+    // exactly the config they read before; a `--config` override stays a route-assurance/levels concern.
+    const checkContext = {
+        present: assuranceConfigPresent,
+        ...(config !== undefined ? { config } : {}),
+        ...(configError !== undefined ? { error: configError } : {}),
+        ...(routeAssurance !== undefined ? { routeAssurance } : {}),
+        ...(capability !== undefined ? { capability } : {}),
+    };
+    let checkResult;
+    return Object.freeze({
+        cwd,
+        assuranceConfigPresent,
+        ...(config !== undefined ? { config } : {}),
+        ...(configError !== undefined ? { configError } : {}),
+        ...(routeAssurance !== undefined ? { routeAssurance } : {}),
+        ...(capability !== undefined ? { capability } : {}),
+        check() {
+            checkResult ??= collectCheckResult(cwd, {
+                lintsOnly: options.lintsOnly ?? false,
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                ...(options.maxDiagnostics !== undefined ? { maxDiagnostics: options.maxDiagnostics } : {}),
+                ...(options.config === undefined ? { assurance: checkContext } : {}),
+            });
+            return checkResult;
+        },
+    });
+}
+//# sourceMappingURL=verification.js.map

package/dist/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../src/verification.ts"],"names":[],"mappings":"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"}