@nifrajs/cli 2.1.0 → 2.3.0

package/dist/examples.js

@@ -1,8 +1,8 @@
 /**
- * `nifra_example` — verified, copy-pasteable code examples for agents. The corpus is `examples.json`
+ * `nifra_example` - verified, copy-pasteable code examples for agents. The corpus is `examples.json`
  * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks
  * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the
- * installed version — the antidote to an agent hallucinating a framework API from stale training.
+ * installed version - the antidote to an agent hallucinating a framework API from stale training.
  *
  * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its
  * code body. No query → a grouped index of what's available (the cheap discovery call).
@@ -42,18 +42,18 @@ export function renderExamplesResult(examples, query, limit) {
         const index = [...byTopic.entries()]
             .map(([topic, names]) => `- **${topic}**: ${names.join(", ")}`)
             .join("\n");
-        return `# nifra examples — index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version — prefer these over recalling an API.\n\n${index}`;
+        return `# nifra examples - index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version - prefer these over recalling an API.\n\n${index}`;
     }
     const matches = searchExamples(examples, query, limit);
     if (matches.length === 0) {
         return `No examples matched ${JSON.stringify(query)}. Call without a query for the index, or try a broader term (e.g. "auth", "upload", "isr", "client").`;
     }
     return matches
-        .map((m) => `## ${m.name} — ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
+        .map((m) => `## ${m.name} - ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
         .join("\n\n---\n\n");
 }
 /** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
- * and `dist/` (published) alike — `docs/examples.json` sits at the package root next to both. */
+ * and `dist/` (published) alike - `docs/examples.json` sits at the package root next to both. */
 export async function loadExamplesCorpus() {
     const url = new URL("../docs/examples.json", import.meta.url);
     try {

package/dist/init-agents.d.ts

@@ -1,18 +1,18 @@
 /**
- * `nifra init-agents` — retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
+ * `nifra init-agents` - retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
  * app ships, so an already-built project adopts the nifra MCP in one command:
  *
- *   .mcp.json          — Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
- *   .cursor/mcp.json   — Cursor's MCP registry (same server config)
- *   CLAUDE.md          — Claude's MCP-first preamble + `@AGENTS.md` import
- *   AGENTS.md          — a `## MCP server` section appended (or a minimal file if none exists)
+ *   .mcp.json          - Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
+ *   .cursor/mcp.json   - Cursor's MCP registry (same server config)
+ *   CLAUDE.md          - Claude's MCP-first preamble + `@AGENTS.md` import
+ *   AGENTS.md          - a `## MCP server` section appended (or a minimal file if none exists)
  *
- * The generators are imported from `create-nifra/agent-files` — the SAME source of truth `create-nifra`
- * uses at scaffold time — so a retrofitted app and a freshly scaffolded one get byte-identical configs.
+ * The generators are imported from `create-nifra/agent-files` - the SAME source of truth `create-nifra`
+ * uses at scaffold time - so a retrofitted app and a freshly scaffolded one get byte-identical configs.
  *
  * Safety: this writes into the user's existing tree, so it NEVER silently clobbers a file they may have
  * customized. By default an existing `.mcp.json` / `CLAUDE.md` / `.cursor/mcp.json` is SKIPPED with a
- * notice; `--force` overwrites. `AGENTS.md` is special-cased — if it already has the MCP section it's
+ * notice; `--force` overwrites. `AGENTS.md` is special-cased - if it already has the MCP section it's
  * left alone, otherwise the section is APPENDED (never overwriting the user's conventions), and `--force`
  * is not needed for that append since it's additive. Every write path is resolved + confined under the
  * cwd (no `..` traversal escaping the project root).
@@ -21,10 +21,10 @@
 export interface InitAgentsFileResult {
     /** Project-root-relative POSIX path. */
     readonly path: string;
-    /** `wrote` — created or (with --force) overwrote; `appended` — added the MCP section to an existing
-     * AGENTS.md; `skipped` — already present and not forced; `present` — MCP section already there. */
+    /** `wrote` - created or (with --force) overwrote; `appended` - added the MCP section to an existing
+     * AGENTS.md; `skipped` - already present and not forced; `present` - MCP section already there. */
     readonly action: "wrote" | "appended" | "skipped" | "present";
-    /** Why it was skipped/left, for the notice (e.g. "exists — pass --force to overwrite"). */
+    /** Why it was skipped/left, for the notice (e.g. "exists - pass --force to overwrite"). */
     readonly note?: string;
 }
 export interface InitAgentsResult {
@@ -36,19 +36,19 @@ export interface InitAgentsOptions {
     readonly force?: boolean;
 }
 /** Confine a project-relative path under `cwd` and return the absolute path. Rejects a spec that escapes
- * the root (defense-in-depth — these specs are constants, but the cwd-confinement invariant is enforced
+ * the root (defense-in-depth - these specs are constants, but the cwd-confinement invariant is enforced
  * at the seam, not assumed). Exported so the invariant is directly testable. */
 export declare function safeJoin(cwd: string, rel: string): string;
 /**
  * Retrofit `cwd` with the four agent-discovery files. Pure enough to unit-test (no argv, no process.exit,
- * no console) — the CLI wrapper handles printing + the exit code.
+ * no console) - the CLI wrapper handles printing + the exit code.
  */
 export declare function initAgents(cwd: string, opts?: InitAgentsOptions): Promise<InitAgentsResult>;
 /** Format the retrofit result for the terminal. */
 export declare function renderInitAgents(result: InitAgentsResult): string;
 /**
  * CLI entry: run the retrofit at `cwd` and print the result. Returns `true` (the command always succeeds
- * unless a write throws — which propagates as a non-zero exit via the dispatcher's catch). `--json`
+ * unless a write throws - which propagates as a non-zero exit via the dispatcher's catch). `--json`
  * emits the structured result for agents/CI.
  */
 export declare function runInitAgents(cwd: string, opts?: {

package/dist/init-agents.js

@@ -1,18 +1,18 @@
 /**
- * `nifra init-agents` — retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
+ * `nifra init-agents` - retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
  * app ships, so an already-built project adopts the nifra MCP in one command:
  *
- *   .mcp.json          — Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
- *   .cursor/mcp.json   — Cursor's MCP registry (same server config)
- *   CLAUDE.md          — Claude's MCP-first preamble + `@AGENTS.md` import
- *   AGENTS.md          — a `## MCP server` section appended (or a minimal file if none exists)
+ *   .mcp.json          - Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
+ *   .cursor/mcp.json   - Cursor's MCP registry (same server config)
+ *   CLAUDE.md          - Claude's MCP-first preamble + `@AGENTS.md` import
+ *   AGENTS.md          - a `## MCP server` section appended (or a minimal file if none exists)
  *
- * The generators are imported from `create-nifra/agent-files` — the SAME source of truth `create-nifra`
- * uses at scaffold time — so a retrofitted app and a freshly scaffolded one get byte-identical configs.
+ * The generators are imported from `create-nifra/agent-files` - the SAME source of truth `create-nifra`
+ * uses at scaffold time - so a retrofitted app and a freshly scaffolded one get byte-identical configs.
  *
  * Safety: this writes into the user's existing tree, so it NEVER silently clobbers a file they may have
  * customized. By default an existing `.mcp.json` / `CLAUDE.md` / `.cursor/mcp.json` is SKIPPED with a
- * notice; `--force` overwrites. `AGENTS.md` is special-cased — if it already has the MCP section it's
+ * notice; `--force` overwrites. `AGENTS.md` is special-cased - if it already has the MCP section it's
  * left alone, otherwise the section is APPENDED (never overwriting the user's conventions), and `--force`
  * is not needed for that append since it's additive. Every write path is resolved + confined under the
  * cwd (no `..` traversal escaping the project root).
@@ -21,7 +21,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
 import { AGENTS_MD_PATH, agentsMcpSection, CLAUDE_MD_PATH, CURSOR_MCP_JSON_PATH, claudeMd, MCP_JSON_PATH, mcpJson, } from "create-nifra/agent-files";
 /** Confine a project-relative path under `cwd` and return the absolute path. Rejects a spec that escapes
- * the root (defense-in-depth — these specs are constants, but the cwd-confinement invariant is enforced
+ * the root (defense-in-depth - these specs are constants, but the cwd-confinement invariant is enforced
  * at the seam, not assumed). Exported so the invariant is directly testable. */
 export function safeJoin(cwd, rel) {
     const abs = resolve(cwd, rel);
@@ -41,7 +41,7 @@ const fileExists = (path) => readFile(path)
 async function writeOwned(cwd, rel, content, force) {
     const abs = safeJoin(cwd, rel);
     if (!force && (await fileExists(abs))) {
-        return { path: rel, action: "skipped", note: "exists — pass --force to overwrite" };
+        return { path: rel, action: "skipped", note: "exists - pass --force to overwrite" };
     }
     // `.cursor/mcp.json` needs its parent dir; `recursive` is a no-op for the root-level files.
     await mkdir(resolve(abs, ".."), { recursive: true });
@@ -51,7 +51,7 @@ async function writeOwned(cwd, rel, content, force) {
 /**
  * AGENTS.md is additive, not owned: if it exists and already has the MCP section, leave it; if it exists
  * without the section, append the section (preserving the user's conventions); if it's absent, write a
- * minimal AGENTS.md that is just the MCP section under a heading. `--force` is irrelevant here — we never
+ * minimal AGENTS.md that is just the MCP section under a heading. `--force` is irrelevant here - we never
  * overwrite the user's existing guidance.
  */
 async function ensureAgentsMd(cwd) {
@@ -78,7 +78,7 @@ async function ensureAgentsMd(cwd) {
 }
 /**
  * Retrofit `cwd` with the four agent-discovery files. Pure enough to unit-test (no argv, no process.exit,
- * no console) — the CLI wrapper handles printing + the exit code.
+ * no console) - the CLI wrapper handles printing + the exit code.
  */
 export async function initAgents(cwd, opts = {}) {
     const force = opts.force ?? false;
@@ -105,12 +105,12 @@ export function renderInitAgents(result) {
     const wroteAny = result.files.some((f) => f.action === "wrote" || f.action === "appended");
     const footer = wroteAny
         ? "\nThe nifra MCP is now registered. Restart your agent so it picks up .mcp.json, then prefer nifra_docs / nifra_example and gate on nifra check."
-        : "\nNothing to do — every file was already present (use --force to overwrite the owned ones).";
+        : "\nNothing to do - every file was already present (use --force to overwrite the owned ones).";
     return `nifra init-agents\n\n${lines.join("\n")}\n${footer}`;
 }
 /**
  * CLI entry: run the retrofit at `cwd` and print the result. Returns `true` (the command always succeeds
- * unless a write throws — which propagates as a non-zero exit via the dispatcher's catch). `--json`
+ * unless a write throws - which propagates as a non-zero exit via the dispatcher's catch). `--json`
  * emits the structured result for agents/CI.
  */
 export async function runInitAgents(cwd, opts = {}) {

package/dist/internal/typescript-import.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The one place the CLI imports TypeScript from.
+ *
+ * The interpolated-SQL rule parses source with the TypeScript compiler, because the regex it replaced
+ * could not tell `sql\`… ${id} …\`` (bound) from a plain template (injectable) without guessing at
+ * string and comment boundaries. That is the right tool, but it is a ~25 MB dependency, and the CLI's
+ * own typecheck step already treats `tsc` as something the PROJECT provides rather than something the
+ * CLI ships. Making it a hard dependency would have contradicted that for every install.
+ *
+ * So it is an optional peer, resolved at the moment the rule runs. Every Nifra project has TypeScript
+ * - the templates all ship a `typecheck` script - so this resolves in practice; the point is that an
+ * install does not pay for it.
+ */
+/** The slice of the compiler the SQL scanner uses. Structural, so the peer stays optional. */
+export type TypeScriptApi = typeof import("typescript");
+/**
+ * Import the project's TypeScript, or `undefined` when it is not installed.
+ *
+ * Only a RESOLUTION failure is absence. A compiler that resolves and then fails while evaluating is a
+ * broken install, not a missing one, and telling that user to install what they already have sends
+ * them the wrong way - so that error is rethrown for the caller to report.
+ */
+export declare function importTypeScript(): Promise<TypeScriptApi | undefined>;
+//# sourceMappingURL=typescript-import.d.ts.map

package/dist/internal/typescript-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-import.d.ts","sourceRoot":"","sources":["../../src/internal/typescript-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG,cAAc,YAAY,CAAC,CAAA;AAEvD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAQ3E"}

package/dist/internal/typescript-import.js

@@ -0,0 +1,32 @@
+/**
+ * The one place the CLI imports TypeScript from.
+ *
+ * The interpolated-SQL rule parses source with the TypeScript compiler, because the regex it replaced
+ * could not tell `sql\`… ${id} …\`` (bound) from a plain template (injectable) without guessing at
+ * string and comment boundaries. That is the right tool, but it is a ~25 MB dependency, and the CLI's
+ * own typecheck step already treats `tsc` as something the PROJECT provides rather than something the
+ * CLI ships. Making it a hard dependency would have contradicted that for every install.
+ *
+ * So it is an optional peer, resolved at the moment the rule runs. Every Nifra project has TypeScript
+ * - the templates all ship a `typecheck` script - so this resolves in practice; the point is that an
+ * install does not pay for it.
+ */
+/**
+ * Import the project's TypeScript, or `undefined` when it is not installed.
+ *
+ * Only a RESOLUTION failure is absence. A compiler that resolves and then fails while evaluating is a
+ * broken install, not a missing one, and telling that user to install what they already have sends
+ * them the wrong way - so that error is rethrown for the caller to report.
+ */
+export async function importTypeScript() {
+    try {
+        return (await import("typescript"));
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (/cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message))
+            return undefined;
+        throw cause;
+    }
+}
+//# sourceMappingURL=typescript-import.js.map

package/dist/internal/typescript-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-import.js","sourceRoot":"","sources":["../../src/internal/typescript-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAkB,CAAA;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,IAAI,sDAAsD,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,SAAS,CAAA;QAC1F,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/introspect.d.ts

@@ -1,6 +1,6 @@
 /**
- * Introspect a loaded nifra project into a Markdown brief — the API routes (`backend.routes()`), the
- * page routes (`discoverRoutes`), and a conventions summary — for piping into an AI coding agent's
+ * Introspect a loaded nifra project into a Markdown brief - the API routes (`backend.routes()`), the
+ * page routes (`discoverRoutes`), and a conventions summary - for piping into an AI coding agent's
  * prompt. Used by `nifra context` (stdout) and the `nifra mcp` server (a tool result), so an agent sees
  * *this* project's actual surface, not just generic docs.
  */
@@ -10,31 +10,31 @@ import type { LoadedApp } from "./load.js";
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
 export declare function backendRoutes(backend: unknown): ReflectedRoute[];
 /**
- * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the
+ * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) - the
  * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).
  * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output
  * is always faithful, just not always minimal.
  */
 export declare function tsTypeOf(schema: unknown, depth?: number): string;
 /**
- * The typed-client call form for a route — the exact `client<typeof app>` proxy chain an agent should
+ * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
  * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
  * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
- * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first —
+ * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
  */
 export declare function clientCall(method: string, path: string, schema: unknown): string;
 /** Markdown section listing the backend's API routes with their request + response field shapes. */
 export declare function apiRoutesSection(routes: readonly ReflectedRoute[]): string;
-/** Compact API-routes INDEX for the no-arg `nifra_context` call — `METHOD path` per route, WITHOUT the
+/** Compact API-routes INDEX for the no-arg `nifra_context` call - `METHOD path` per route, WITHOUT the
  * body/query/response shapes or the per-route `call` line. Bounds the first-call payload on a big backend:
  * an agent gets the full route list (so it knows what's mounted) plus a pointer to fetch any route's full
  * contract via the `path`/`kind` slice, instead of every schema up front. */
 export declare function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string;
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
 export declare function pageRoutesSection(manifest: Manifest | undefined): string;
-/** Optional narrowing for {@link describeProject} — a path prefix and/or one section. A filtered
+/** Optional narrowing for {@link describeProject} - a path prefix and/or one section. A filtered
  * brief omits the conventions block (the agent already has it from its first full call), so
  * follow-up calls cost a fraction of the tokens. */
 export interface ContextFilter {
@@ -42,9 +42,9 @@ export interface ContextFilter {
     readonly kind?: "api" | "pages";
 }
 /**
- * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** — the route list (API
+ * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** - the route list (API
  * routes as `METHOD path`, page routes as `pattern → file`) + conventions + a pointer to fetch full
- * contracts via the slice — so learning a big project is cheap, not a full-surface schema dump. Passing a
+ * contracts via the slice - so learning a big project is cheap, not a full-surface schema dump. Passing a
  * {@link ContextFilter} (`path` prefix and/or `kind`) returns the narrowed, FULL detail (per-route
  * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
  * already has it from the index call).
@@ -61,7 +61,7 @@ export interface RouteJson {
     readonly response?: string;
 }
 /**
- * The backend's API routes as structured JSON — what the `nifra_routes` MCP tool returns, so an agent
+ * The backend's API routes as structured JSON - what the `nifra_routes` MCP tool returns, so an agent
  * consumes the contract programmatically (`list_routes` / `get_route_schema`) instead of parsing the
  * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
  * same `call` form and TS-shaped contracts the Markdown brief shows.
@@ -76,7 +76,7 @@ export interface RouteTableEntry {
     readonly path: string;
     /** Methods this route serves, sorted (page: `GET`, plus `POST` when it has an `action`). */
     readonly methods: readonly string[];
-    /** Source file (page only — the route module path relative to `routes/`). */
+    /** Source file (page only - the route module path relative to `routes/`). */
     readonly file?: string;
     /** True when this API route is auto-mounted under the page router's `apiPrefix` (so it's reachable
      * through the same web app, no hand-wired `if (pathname.startsWith("/api/"))`). Pages are never
@@ -98,7 +98,7 @@ export interface RouteTableInput {
     readonly apiPrefix?: string;
 }
 /**
- * Build the unified, sorted route table from page routes + backend API routes. Pure — the caller
+ * Build the unified, sorted route table from page routes + backend API routes. Pure - the caller
  * supplies page `hasAction` (resolved via a module load) and the API descriptors (`backend.routes()`).
  * Page routes serve `GET` (+ `POST` when they export an `action`); API routes carry their declared
  * method, and are flagged `autoMounted` when at/under `apiPrefix`. Sorted by path, then kind, then the

package/dist/introspect.js

@@ -1,6 +1,6 @@
 /**
- * Introspect a loaded nifra project into a Markdown brief — the API routes (`backend.routes()`), the
- * page routes (`discoverRoutes`), and a conventions summary — for piping into an AI coding agent's
+ * Introspect a loaded nifra project into a Markdown brief - the API routes (`backend.routes()`), the
+ * page routes (`discoverRoutes`), and a conventions summary - for piping into an AI coding agent's
  * prompt. Used by `nifra context` (stdout) and the `nifra mcp` server (a tool result), so an agent sees
  * *this* project's actual surface, not just generic docs.
  */
@@ -11,7 +11,7 @@ export function backendRoutes(backend) {
     return [...reflectRoutes(backend)];
 }
 /**
- * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the
+ * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) - the
  * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).
  * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output
  * is always faithful, just not always minimal.
@@ -58,7 +58,7 @@ export function tsTypeOf(schema, depth = 0) {
     }
 }
 /** One route's request/response field shapes, indented under its line. Reads the declared schemas off the
- * descriptor so an agent gets the exact input + output contract — not just "this route is validated". */
+ * descriptor so an agent gets the exact input + output contract - not just "this route is validated". */
 function schemaLines(schema) {
     const s = schema;
     if (!s)
@@ -77,11 +77,11 @@ function schemaLines(schema) {
 }
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 /**
- * The typed-client call form for a route — the exact `client<typeof app>` proxy chain an agent should
+ * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
  * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
  * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
- * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first —
+ * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
  */
 export function clientCall(method, path, schema) {
@@ -125,9 +125,9 @@ export function apiRoutesSection(routes) {
         ...schemaLines(r.schema),
         `    - call: \`${clientCall(r.method, r.path, r.schema)}\` → \`{ ok, status, data, error }\``,
     ]);
-    return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract — the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`;
+    return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract - the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`;
 }
-/** Compact API-routes INDEX for the no-arg `nifra_context` call — `METHOD path` per route, WITHOUT the
+/** Compact API-routes INDEX for the no-arg `nifra_context` call - `METHOD path` per route, WITHOUT the
  * body/query/response shapes or the per-route `call` line. Bounds the first-call payload on a big backend:
  * an agent gets the full route list (so it knows what's mounted) plus a pointer to fetch any route's full
  * contract via the `path`/`kind` slice, instead of every schema up front. */
@@ -138,7 +138,7 @@ export function apiRoutesIndexSection(routes) {
     const lines = [...routes]
         .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
         .map((r) => `- \`${r.method} ${r.path}\``);
-    return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form — or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`;
+    return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form - or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`;
 }
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
 export function pageRoutesSection(manifest) {
@@ -154,27 +154,27 @@ const CONVENTIONS = `## Conventions (summary)
 
 - **Backend:** \`server()\` from \`@nifrajs/core\`; returning a value sends JSON. Validate untrusted input with
   a route schema (\`{ body, query, params }\` using \`t\` from \`@nifrajs/schema\` or any Standard Schema) and read
-  the typed \`c.body\` / \`c.query\` / \`c.params\` — never hand-parse.
+  the typed \`c.body\` / \`c.query\` / \`c.params\` - never hand-parse.
 - **Cross-cutting concerns** (rate limit / \`429\`, CORS, auth, CSRF, caching, security headers, body limits)
   → \`@nifrajs/middleware\`, applied with \`app.use(...)\`. Don't hand-roll them; call \`nifra_docs("middleware")\`
   for the full list + usage.
 - **Need the exact TypeScript of a \`@nifrajs/*\` symbol?** Call \`nifra_types({ name })\` (e.g. \`RateLimitStore\`,
-  \`RouteSchema\`) — the authoritative, complete declaration. Never read \`@nifrajs\` \`.d.ts\` files.
+  \`RouteSchema\`) - the authoritative, complete declaration. Never read \`@nifrajs\` \`.d.ts\` files.
 - **Response contract (no drift):** declare \`{ response: t.object({...}) }\` on a route to lock its output
-  shape — the handler is type-checked against it and the client sees exactly that shape. The contract above
+  shape - the handler is type-checked against it and the client sees exactly that shape. The contract above
   is the single source of truth for both sides.
-- **Client — ALWAYS use this for API calls:** \`client<typeof app>(url)\` derives request inputs AND
+- **Client - ALWAYS use this for API calls:** \`client<typeof app>(url)\` derives request inputs AND
   \`res.data\` from the backend's route types, so the compiler catches any frontend/backend drift. Never
-  hand-roll \`fetch\` + ad-hoc response types for an internal API — that's exactly how screens drift. It
+  hand-roll \`fetch\` + ad-hoc response types for an internal API - that's exactly how screens drift. It
   never throws: branch on \`res.ok ? res.data : res.error\`.
 - **Pages:** file-routed under \`routes/\`; \`loader\`/\`action\` are server-only but the module is also bundled
-  for the browser — **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
+  for the browser - **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
   file; reach it via \`ctx.api\` / \`ctx.env\`.
 - \`app.fetch(Request)\` is the universal entry. Full reference: this repo's \`AGENTS.md\`, or \`llms-full.txt\`.`;
 /**
- * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** — the route list (API
+ * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** - the route list (API
  * routes as `METHOD path`, page routes as `pattern → file`) + conventions + a pointer to fetch full
- * contracts via the slice — so learning a big project is cheap, not a full-surface schema dump. Passing a
+ * contracts via the slice - so learning a big project is cheap, not a full-surface schema dump. Passing a
  * {@link ContextFilter} (`path` prefix and/or `kind`) returns the narrowed, FULL detail (per-route
  * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
  * already has it from the index call).
@@ -185,7 +185,7 @@ export function describeProject(app, filter) {
         manifest = discoverRoutes(app.routesDir);
     }
     catch {
-        // No (or unreadable) routes/ — the page-routes section reports that.
+        // No (or unreadable) routes/ - the page-routes section reports that.
     }
     const prefix = filter?.path;
     let routes = backendRoutes(app.backend);
@@ -201,10 +201,10 @@ export function describeProject(app, filter) {
     const isIndex = filter?.kind === undefined && (prefix === undefined || prefix === "");
     const sections = [`# nifra project: ${app.cwd.slice(app.cwd.lastIndexOf("/") + 1)}`];
     if (isIndex) {
-        sections.push("A full-stack nifra app — Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).", 
-        // Point agents at the verified surface, not recalled APIs — nifra is young, so training data is the
+        sections.push("A full-stack nifra app - Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).", 
+        // Point agents at the verified surface, not recalled APIs - nifra is young, so training data is the
         // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
-        "> **Build against THIS surface + the verified tools — do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.");
+        "> **Build against THIS surface + the verified tools - do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.");
     }
     if (filter?.kind !== "pages") {
         // Index → compact `METHOD path` list; a slice → the full schema + call-form detail.
@@ -217,7 +217,7 @@ export function describeProject(app, filter) {
     return sections.join("\n\n");
 }
 /**
- * The backend's API routes as structured JSON — what the `nifra_routes` MCP tool returns, so an agent
+ * The backend's API routes as structured JSON - what the `nifra_routes` MCP tool returns, so an agent
  * consumes the contract programmatically (`list_routes` / `get_route_schema`) instead of parsing the
  * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
  * same `call` form and TS-shaped contracts the Markdown brief shows.
@@ -261,7 +261,7 @@ function isUnderPrefix(path, prefix) {
     return path === prefix || path.startsWith(`${prefix}/`);
 }
 /**
- * Build the unified, sorted route table from page routes + backend API routes. Pure — the caller
+ * Build the unified, sorted route table from page routes + backend API routes. Pure - the caller
  * supplies page `hasAction` (resolved via a module load) and the API descriptors (`backend.routes()`).
  * Page routes serve `GET` (+ `POST` when they export an `action`); API routes carry their declared
  * method, and are flagged `autoMounted` when at/under `apiPrefix`. Sorted by path, then kind, then the
@@ -342,7 +342,7 @@ export async function describeRoutes(app, opts = {}) {
         manifest = discoverRoutes(app.routesDir);
     }
     catch {
-        // No (or unreadable) routes/ — fall through with no pages; the table still shows API routes.
+        // No (or unreadable) routes/ - fall through with no pages; the table still shows API routes.
     }
     const pages = [];
     for (const route of manifest?.routes ?? []) {

package/dist/levels-tool.d.ts

@@ -1,20 +1,20 @@
 /**
- * `nifra levels` — the verification ladder, computed from gates that already exist:
+ * `nifra levels` - the verification ladder, computed from gates that already exist:
  *
- *   L0 typed contract      — `nifra check` passes (compiler-enforced frontend↔backend contract)
- *   L1 route assurance     — `nifra.assurance.ts` present and every route satisfies its policy
- *   L2 capability lockfile — capability/effect assurance passes and the lockfile is in sync
- *   L3 route manifest      — the emitted manifest hash-verifies and matches the current app
- *   L4 invariant-tested    — every route passes through an explicitly isolated executor
+ *   L0 typed contract      - `nifra check` passes (compiler-enforced frontend↔backend contract)
+ *   L1 route assurance     - `nifra.assurance.ts` present and every route satisfies its policy
+ *   L2 capability lockfile - capability/effect assurance passes and the lockfile is in sync
+ *   L3 route manifest      - the emitted manifest hash-verifies and matches the current app
+ *   L4 invariant-tested    - every route passes through an explicitly isolated executor
  *
- * A level counts only when every level below it holds — the ladder is cumulative, so "L3" is one
+ * A level counts only when every level below it holds - the ladder is cumulative, so "L3" is one
  * honest word for a whole posture. Levels are computed, never self-declared.
  */
 export interface VerificationLevelStatus {
     readonly level: number;
     readonly name: string;
     readonly ok: boolean;
-    /** Why the level does not hold — a gate failure or a missing prerequisite. Empty when ok. */
+    /** Why the level does not hold - a gate failure or a missing prerequisite. Empty when ok. */
     readonly reasons: readonly string[];
 }
 export interface VerificationLevelsResult {

package/dist/levels-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"levels-tool.d.ts","sourceRoot":"","sources":["../src/levels-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,uBAAuB,EAAE,CAAA;CACpD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,iGAAiG;AACjG,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAwInC;AAqBD,2FAA2F;AAC3F,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GACtF,OAAO,CAAC,OAAO,CAAC,CAkBlB"}
+{"version":3,"file":"levels-tool.d.ts","sourceRoot":"","sources":["../src/levels-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,uBAAuB,EAAE,CAAA;CACpD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,iGAAiG;AACjG,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAgJnC;AAqBD,2FAA2F;AAC3F,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GACtF,OAAO,CAAC,OAAO,CAAC,CAkBlB"}