@nifrajs/cli 0.1.0-alpha.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,99 @@
+# @nifrajs/cli
+
+The `nifra` CLI — zero-config dev/build/start for a nifra app, plus the agent surfaces (`nifra context`,
+`nifra mcp`). Run from your project root (it reads `nifra.config.ts`/`framework.ts`, `backend.ts`, and
+`routes/`).
+
+```
+nifra dev     [--port <n>] [--poll]       True-HMR dev server (Vite + nifra SSR).
+nifra build   [--out <dir>]               Content-hashed client bundle + manifest.json.
+nifra start   [--port <n>] [--out <dir>]  Serve the built app (client + SSR) on Bun.
+nifra context                             Print this project's API + page routes + conventions.
+nifra mcp                                 MCP server (stdio) exposing this project to a coding agent.
+nifra check   [--json]                    Gate: typecheck + lints; --json includes fixes/suggestions.
+nifra doctor  [--json] [--auto-fix]       Catch undeclared imported packages; auto-fix safe local versions.
+```
+
+## `nifra check` — the drift gate (run as "done")
+
+`nifra check` makes nifra's anti-drift guarantees actually fire instead of relying on the agent to
+remember them. It does three things and exits non-zero if any fails:
+
+1. **Typecheck** (`tsc --noEmit`, using the project's own TypeScript) — the frontend↔backend contract is
+   compiler-enforced. `client<typeof app>` derives request inputs **and** `res.data` from your routes, so
+   a screen that expects the wrong shape is a type error. Running the typecheck is what turns that latent
+   guarantee into an enforced one.
+2. **Typed-client lint** — flags any hand-rolled `fetch()` to your own API (a relative URL like
+   `fetch("/users")`), which bypasses the typed client so the compiler can't see the drift. External
+   absolute-URL fetches are not flagged.
+3. **Server-only-import lint** — flags a top-level import of server-only code (a DB driver, `node:`/`bun:`
+   builtins, the `./db` module) into a `routes/` page module. Those modules are bundled for the browser,
+   so the import ships server code to the client. Reach it via `c.db` / `ctx.api` inside a loader instead.
+
+Pass **`--json`** for a machine-readable result (`{ ok, typecheck, diagnostics[] }`) — what the
+`nifra_check` MCP tool returns, so an agent acts on diagnostics instead of scraping output. Each diagnostic
+has a short `fix` string and, when safe, a structured `suggestion`: an exact one-line diff, an argv command
+array (for example `["bun","add","react"]`), or concrete manual steps. Tell a coding agent to run
+`nifra check` as its definition of done (the scaffolded `AGENTS.md` already does), and wire it into CI — a
+green check means the frontend and backend can't have silently diverged.
+
+For hand-rolled own-API `fetch()` calls, `nifra check` stays conservative: simple string-literal calls
+that match a statically visible Nifra route get an exact typed-client rewrite diff; dynamic URLs, custom
+headers, bodies, query strings, or ambiguous routes fall back to manual steps.
+
+## For AI coding agents
+
+**`nifra context`** prints this project's actual surface — API routes (from `backend.routes()`), page
+routes (from `routes/`), and the framework conventions — as Markdown. Pipe it into a prompt:
+
+```sh
+nifra context | pbcopy        # or: nifra context > .agent-context.md
+```
+
+**`nifra mcp`** runs a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, so
+an agent can act on the project, not just read about it. Core tools:
+
+- **`nifra_context`** — the same project surface as above.
+- **`nifra_routes`** / **`nifra_openapi`** — structured API route contracts and an OpenAPI 3.1 document.
+- **`nifra_docs`** / **`nifra_example`** — token-efficient docs slices and verified code snippets.
+- **`nifra_scaffold`** — map a URL to the correct `routes/` file; optionally write safe JSX stubs.
+- **`nifra_run`** — run HTTP requests through this project's backend and get structured results
+  (status, headers, parsed body, and any thrown error). The backend is re-loaded in a fresh process
+  each call by default, so it reflects the agent's latest edits — the write → run → see-the-failure
+  → fix loop. Pass `warm:true` to reuse a hot worker while source files are unchanged.
+- **`nifra_render`** — SSR a page route and return rendered HTML for quick page verification.
+- **`nifra_ws`** — verify a WebSocket route with a real Bun WebSocket round-trip and structured output.
+- **`nifra_test`** — run bounded `bun test` with structured output.
+- **`nifra_check`** — run the drift gate and get the structured `{ ok, typecheck, diagnostics[] }`
+  result with suggestions, so the agent verifies its own work and fixes each diagnostic before finishing.
+- **`nifra_doctor`** — catch imported packages missing from `package.json`; with `autoFix:true`, write
+  safe dependency entries when a version can be inferred locally and return exact `bun add` commands
+  for anything that needs a package-manager decision.
+
+The MCP server also exposes compact resources (`nifra://routes`, `nifra://openapi`, `nifra://package-json`,
+`nifra://agents-md`) and prompt templates for common tasks.
+
+For long-running stdio tool calls, nifra follows MCP's standard `_meta.progressToken` progress
+notifications and `notifications/cancelled` request cancellation. `nifra_run`, `nifra_render`,
+`nifra_test`, and full `nifra_check` calls stop their subprocess work when cancelled.
+For token-sensitive clients, `tools/list` also accepts the opt-in extension `{ "compact": true }`;
+call `tools/describe` with a tool name when you need the full schema and description.
+
+Wire it into a client. Claude Desktop / Cursor (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "nifra": { "command": "nifra", "args": ["mcp"] }
+  }
+}
+```
+
+Claude Code:
+
+```sh
+claude mcp add nifra -- nifra mcp
+```
+
+Run the client from (or point it at) your project root. The protocol is hand-rolled
+(newline-delimited JSON-RPC 2.0) — no SDK dependency.

package/dist/check.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `nifra check` — the agent's (and CI's) definition of done. It makes the guarantees that keep a nifra
+ * app drift-proof actually *fire*, instead of relying on the agent to remember them:
+ *
+ *   1. **typecheck** (`tsc --noEmit`) — the frontend↔backend contract is compiler-enforced. The typed
+ *      client derives request + response types from the routes, so a shape mismatch is a type error.
+ *   2. **typed-client lint** — flags hand-rolled `fetch()` to this app's *own* API (a relative URL),
+ *      which bypasses `client<typeof app>` so the compiler can't see the drift.
+ *   3. **server-only-import lint** — flags a top-level import of server-only code (a DB driver, `node:`/
+ *      `bun:` builtins, the `./db` module) into a `routes/` page module. Those modules are bundled for
+ *      the browser too, so the import ships server code to the client and breaks the build — the #1
+ *      full-stack footgun. Reach server resources via `c.db` / `ctx.api`, never a top-level import.
+ *
+ * `collectCheckResult` returns a structured, machine-readable result (consumed by `--json` and the
+ * `nifra_check` MCP tool, so an agent acts on diagnostics instead of scraping prose). Exits non-zero if
+ * anything fails. Pure scanners (`scanFetchText`, `scanServerOnlyImports`) are unit-tested.
+ */
+export interface SourceFinding {
+    readonly file: string;
+    readonly line: number;
+    readonly snippet: string;
+}
+/** @deprecated kept for back-compat with existing tests; prefer {@link SourceFinding}. */
+export type FetchFinding = SourceFinding;
+export interface StaticRouteFinding extends SourceFinding {
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * Blank, with spaces (newlines preserved, so every byte offset — and line number — is unchanged):
+ *   - `//` line comments and block comments;
+ *   - the CONTENTS of backtick template literals — code-as-text (doc `CodeBlock` examples, code
+ *     generators), never a real statement to lint.
+ * Single/double-quoted strings are KEPT (a real import/Response specifier lives in one). A small
+ * char-state machine, not a full lexer: it doesn't model regex literals, so a regex containing a quote
+ * could mis-skip — in practice the constructs these scanners look for sit before any such regex.
+ * Shared by the source scanners here and by `nifra doctor` ({@link ./doctor.ts}).
+ */
+export declare function stripComments(src: string): string;
+/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. */
+export declare function scanFetchText(file: string, content: string): SourceFinding[];
+/** Statically collect simple Nifra route registrations from source, without importing app code. */
+export declare function scanStaticRouteText(file: string, content: string): StaticRouteFinding[];
+/** Scan one file's text for untyped `client("…")` calls. Pure + line-accurate. */
+export declare function scanUntypedClient(file: string, content: string): SourceFinding[];
+/** Scan a route module for top-level server-only imports. Returns `[]` for non-route files (only
+ * `routes/` modules are browser-bundled, so a server-only import elsewhere is fine). Pure. */
+export declare function scanServerOnlyImports(file: string, content: string): SourceFinding[];
+/** Scan a backend module (one that calls `server(`) for handlers returning a raw `Response`, which collapses
+ * the typed client's `data` to `never`. Pure + line-accurate; returns `[]` for files with no `server(` call. */
+export declare function scanResponseRoutes(file: string, content: string): SourceFinding[];
+/** Walk the project's `.ts`/`.tsx` source (skipping deps/build/tests), calling `visit` per file.
+ * Exported so `nifra doctor` ({@link ./doctor.ts}) scans the same source surface as `nifra check`. */
+export declare function walkSource(cwd: string, visit: (rel: string, content: string) => void): Promise<void>;
+/** Collect own-API `fetch()` findings across the project (kept for back-compat + reuse). */
+export declare function scanProject(cwd: string): Promise<SourceFinding[]>;
+/** A single machine-readable check failure — the unit an agent (or CI) acts on. */
+export interface CheckDiagnostic {
+    readonly rule: "typecheck" | "typed-client" | "untyped-client" | "server-only-import" | "response-route" | "undeclared-dependency";
+    /** `error` fails the gate (a real contract break); `warning` is advisory — surfaced to the agent but
+     * does NOT fail `nifra check`, for patterns that are sometimes intentional (a route returning a raw
+     * `Response`, which silently drops the typed client to `data: never` but is valid for files/redirects). */
+    readonly severity: "error" | "warning";
+    readonly file?: string;
+    readonly line?: number;
+    readonly message: string;
+    /** The canonical, rule-level fix — clean of the per-occurrence snippet, so an agent can apply it
+     * directly. Set for the lint rules (they have one correct fix); omitted for `typecheck` (the fix is
+     * specific to each type error). */
+    readonly fix?: string;
+    /** A richer, agent-oriented fix hint. Diffs are only emitted when the edit is mechanical and local;
+     * ambiguous cases give concrete steps instead of pretending the checker can safely rewrite code. */
+    readonly suggestion?: CheckSuggestion;
+}
+export interface CheckSuggestion {
+    readonly kind: "edit" | "command" | "manual";
+    readonly title: string;
+    readonly diff?: string;
+    /** argv array, not a shell string, so MCP clients can run it without quoting hazards. */
+    readonly command?: readonly string[];
+    readonly steps?: readonly string[];
+}
+/** The structured result of a full check — what `--json` prints and the `nifra_check` MCP tool returns. */
+export interface CheckResult {
+    readonly ok: boolean;
+    readonly typecheck: "pass" | "fail" | "skipped";
+    readonly diagnostics: readonly CheckDiagnostic[];
+}
+/** Run the three checks and assemble a structured, machine-readable result. The single source the CLI
+ * report, `--json`, and the MCP tool all render from. */
+export declare function collectCheckResult(cwd: string, opts?: {
+    readonly lintsOnly?: boolean;
+    readonly signal?: AbortSignal;
+}): Promise<CheckResult>;
+/** Run the full check; print a report (`--json` for machine output) and return whether it passed. */
+export declare function runCheck(cwd: string, opts?: {
+    readonly json?: boolean;
+    readonly lintsOnly?: boolean;
+}): Promise<boolean>;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

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