@zerotal/arch 1.7.0

package/src/mcp/stdio.ts

@@ -0,0 +1,111 @@
+/**
+ * The stdio binding: read newline-delimited JSON-RPC from stdin, write replies
+ * to stdout.
+ *
+ * ## Two rules this file exists to keep
+ *
+ * **Nothing but MCP frames reaches stdout.** The spec states it as a MUST NOT,
+ * and the failure mode is not a warning — a stray banner on stdout desyncs the
+ * client's line parser and every frame after it is garbage. Diagnostics go to
+ * stderr, which the spec explicitly allows and clients are told not to read as
+ * failure.
+ *
+ * **Requests are dispatched concurrently, not in lockstep.** Awaiting each
+ * request before reading the next would make `notifications/cancelled`
+ * unreachable: the cancellation for a running tool is by definition sent while
+ * that tool is still running. Each frame is written in a single call, so replies
+ * may interleave in time but never within a message.
+ *
+ * The loop ends when stdin reaches EOF. That is the only portable shutdown
+ * signal — the spec names closing stdin as the primary one, and on Windows
+ * there is no POSIX signal to fall back to.
+ */
+import { decodeFrame, encodeFrame } from "./jsonrpc.ts";
+import type { McpServer } from "./server.ts";
+import type { JsonRpcResponse } from "./types.ts";
+
+export interface StdioOptions {
+  server: McpServer;
+  /** Byte source. Defaults to this process's stdin. */
+  input?: ReadableStream<Uint8Array>;
+  /** Frame sink. Defaults to this process's stdout. Injected in tests. */
+  write?: (frame: string) => void;
+  /** Diagnostics sink. Defaults to stderr — never stdout. */
+  log?: (message: string) => void;
+}
+
+/**
+ * Serve MCP over a byte stream until it ends.
+ *
+ * Resolves once the input is exhausted *and* every request still in flight has
+ * been answered, so a caller can exit the process knowing nothing is pending.
+ */
+export async function serveStdio(options: StdioOptions): Promise<void> {
+  const { server } = options;
+  const input = options.input ?? Bun.stdin.stream();
+  const write = options.write ?? ((frame: string) => void process.stdout.write(frame));
+  const log = options.log ?? ((message: string) => void process.stderr.write(message + "\n"));
+
+  const decoder = new TextDecoder();
+  const pending = new Set<Promise<void>>();
+  let buffer = "";
+
+  const dispatch = (line: string): void => {
+    const decoded = decodeFrame(line);
+    if (decoded === undefined) return;
+    if (!decoded.ok) {
+      send(decoded.failure);
+      return;
+    }
+
+    const task = server
+      .handle(decoded.request)
+      .then((response) => {
+        if (response !== undefined) send(response);
+      })
+      .catch((error: unknown) => {
+        // Reaching here means the dispatcher itself failed, not a tool — tools
+        // have their own catch. There is no useful reply to send for it, so the
+        // honest thing is to say so on stderr and keep serving.
+        log(`[arch] dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+      })
+      .finally(() => {
+        pending.delete(task);
+      });
+
+    pending.add(task);
+  };
+
+  const send = (response: JsonRpcResponse): void => {
+    try {
+      write(encodeFrame(response));
+    } catch (error) {
+      log(`[arch] could not encode a reply: ${error instanceof Error ? error.message : error}`);
+    }
+  };
+
+  // Read through the reader rather than `for await`: Bun's streams are async
+  // iterable at runtime, but the DOM `ReadableStream` type this repo compiles
+  // against does not declare it, and the alternative is a cast in the one file
+  // whose whole job is to be trustworthy.
+  const reader = input.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+
+    let newline = buffer.indexOf("\n");
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      dispatch(line);
+      newline = buffer.indexOf("\n");
+    }
+  }
+
+  // A final line with no trailing newline is still a message. Clients should not
+  // send one, but a shell heredoc or a hand-written fixture will.
+  if (buffer.trim().length > 0) dispatch(buffer);
+
+  while (pending.size > 0) await Promise.all([...pending]);
+}

package/src/mcp/types.ts

@@ -0,0 +1,146 @@
+/**
+ * The vocabulary shared by the transport and the tools — and the seam between
+ * them.
+ *
+ * A tool is a plain object: a name, a description, a JSON Schema, and a `run`.
+ * It knows nothing about JSON-RPC, and nothing in `mcp/` knows what a Zerotal
+ * app is. That separation is what lets every tool be tested with no transport
+ * and the transport be tested with no app, and it is what leaves room for a
+ * second transport later without touching a single tool.
+ */
+
+// ── The tool contract ─────────────────────────────────────────────────────────
+
+/**
+ * A JSON Schema document, kept deliberately loose.
+ *
+ * The 2026-07-28 revision widened `inputSchema` to allow any JSON Schema
+ * 2020-12 keyword, so a narrow hand-written type here would reject valid
+ * schemas rather than catch mistakes.
+ */
+export type JsonSchema = Record<string, unknown>;
+
+/** What a tool returns. Rendered into MCP content blocks by the server. */
+export interface ToolOutcome {
+  /** Prose for the model. Always present, even when `data` carries the detail. */
+  text: string;
+  /**
+   * The machine-readable payload, matching the tool's `outputSchema`.
+   * Serialised into `structuredContent`.
+   */
+  data?: unknown;
+  /**
+   * The tool ran and could not do what was asked — a missing file, an app that
+   * would not boot, a package that is not installed.
+   *
+   * Reported as `isError: true` on an otherwise ordinary result, never as a
+   * JSON-RPC error: the spec is explicit that execution errors are the ones a
+   * model can read and self-correct from, while protocol errors are not.
+   */
+  failed?: boolean;
+}
+
+/** One tool the server exposes. */
+export interface ArchTool {
+  /** Wire name. Lowercase with underscores, to match the rest of the ecosystem. */
+  name: string;
+  /** Human-readable name for display. */
+  title: string;
+  /**
+   * What the tool does, written for a model deciding whether to call it.
+   *
+   * This is the single most load-bearing string in the package: a tool the
+   * agent never reaches for is a tool that does not exist.
+   */
+  description: string;
+  /** JSON Schema for `arguments`. Use `{type: "object", additionalProperties: false}` for none. */
+  inputSchema: JsonSchema;
+  /** JSON Schema for `data`. Present on every tool here — the shape is the point. */
+  outputSchema: JsonSchema;
+  run(args: Record<string, unknown>, signal: AbortSignal): Promise<ToolOutcome>;
+}
+
+// ── JSON-RPC 2.0 ──────────────────────────────────────────────────────────────
+
+/** A JSON-RPC id. `null` is reserved for replies to unparseable input. */
+export type JsonRpcId = string | number;
+
+/** An inbound message. A request has an `id`; a notification does not. */
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: JsonRpcId;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcSuccess {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  result: Record<string, unknown>;
+}
+
+export interface JsonRpcFailure {
+  jsonrpc: "2.0";
+  id: JsonRpcId | null;
+  error: { code: number; message: string; data?: unknown };
+}
+
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+
+/**
+ * JSON-RPC error codes, plus the one MCP allocates.
+ *
+ * The 2026-07-28 revision partitioned the server-error range: `-32000`…`-32019`
+ * stays implementation-defined and `-32020`…`-32099` is reserved for the spec,
+ * which is why `UNSUPPORTED_PROTOCOL_VERSION` is `-32022` and not the `-32004`
+ * an earlier draft used.
+ */
+export const RpcError = {
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603,
+  UNSUPPORTED_PROTOCOL_VERSION: -32022,
+} as const;
+
+// ── Protocol versions ─────────────────────────────────────────────────────────
+
+/**
+ * The revision that made MCP stateless: no `initialize`, per-request `_meta`,
+ * a mandatory `server/discover`.
+ */
+export const MODERN_VERSION = "2026-07-28";
+
+/**
+ * Handshake-based revisions, newest first.
+ *
+ * These are still what shipping clients open with — the modern revision was
+ * published on 28 July 2026 — so serving them is not a courtesy, it is the
+ * only way the server is usable today. The list is the negotiation preference
+ * order for `initialize`.
+ */
+export const LEGACY_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"] as const;
+
+/** Everything this server speaks, newest first. Advertised by `server/discover`. */
+export const SUPPORTED_VERSIONS = [MODERN_VERSION, ...LEGACY_VERSIONS] as const;
+
+/**
+ * `_meta` keys the modern revision defines. Prefixed, per the naming rules.
+ */
+export const Meta = {
+  PROTOCOL_VERSION: "io.modelcontextprotocol/protocolVersion",
+  CLIENT_INFO: "io.modelcontextprotocol/clientInfo",
+  CLIENT_CAPABILITIES: "io.modelcontextprotocol/clientCapabilities",
+  SERVER_INFO: "io.modelcontextprotocol/serverInfo",
+} as const;
+
+/** Which era a request is speaking. Selected per request, not per connection. */
+export type Era = "modern" | "legacy";
+
+/** Identity this server reports in `serverInfo`. */
+export interface ServerIdentity {
+  name: string;
+  title: string;
+  version: string;
+}

package/src/probe/ArchProbeCommand.ts

@@ -0,0 +1,48 @@
+/**
+ * `bun zt arch:probe <topic>` — the one place the agent surface crosses into a
+ * booted application.
+ *
+ * The MCP server never boots an app itself: it must keep stdout clean for the
+ * protocol, and more importantly its answers have to reflect the code as it is
+ * *now*, because the caller is an agent that edits that code between calls. A
+ * long-lived booted app would answer `routes` from the state it booted with,
+ * which is the same class of mistake as running code that is not the code on
+ * disk.
+ *
+ * So each tool spawns this command, it boots like any other `zt` command, prints
+ * one JSON document, and exits. One command rather than a `--json` flag on
+ * `doctor`, `route:list` and the rest: it leaves those untouched, keeps every
+ * app-shaped read in {@link probe}, and gives the subprocess boundary exactly
+ * one shape to test.
+ */
+import { Command } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { PROBE_SENTINEL } from "./sentinel.ts";
+import { PROBE_TOPICS, isProbeTopic, probe } from "./topics.ts";
+
+export class ArchProbeCommand extends Command {
+  static override commandName = "arch:probe";
+  static override description = "Print a JSON report about this app for the agent surface";
+  static override needsApp = true;
+  static override args = [{ name: "topic", required: true }];
+  static override flags = [];
+
+  async run(): Promise<void> {
+    const topic = this.args["topic"] ?? "";
+    if (!isProbeTopic(topic)) {
+      throw new Error(
+        `Unknown probe topic "${topic}". Expected one of: ${PROBE_TOPICS.join(", ")}`,
+      );
+    }
+
+    const app = this.app as Application | undefined;
+    if (!app) throw new Error("arch:probe needs a booted application.");
+
+    const payload = await probe(topic, app);
+
+    // Written raw, through `write` rather than the colouring helpers: the reader
+    // parses this and an escape sequence in the middle of it is not JSON.
+    this.write(`\n${PROBE_SENTINEL}\n`);
+    this.write(JSON.stringify(payload) + "\n");
+  }
+}

package/src/probe/sentinel.ts

@@ -0,0 +1,13 @@
+/**
+ * The marker that separates a probe's answer from everything else on stdout.
+ *
+ * `bun zt arch:probe` boots the whole application, and a booted application
+ * prints — dev banners, provider notices, a warning from a package that noticed
+ * something. None of that is knowable in advance, so the reader does not try to
+ * suppress it: the command emits this line, then one line of JSON, and the
+ * reader takes the last occurrence and parses what follows.
+ *
+ * Shared by the writer and the reader so the two can never disagree, and long
+ * and specific enough that no plausible log line collides with it.
+ */
+export const PROBE_SENTINEL = "<<<zerotal:arch:probe:json>>>";

package/src/probe/topics.ts

@@ -0,0 +1,291 @@
+/**
+ * The four reads that need a booted application, and the only code in this
+ * package that runs inside one.
+ *
+ * Everything here answers from the framework's own structured sources rather
+ * than by parsing a printed table: `runDoctor()` already returns
+ * `{status, message, fix}` per check, `Router.routes` is a map of route
+ * definitions, and the ORM's `ModelInspector` reads decorator metadata. There is
+ * no scraping anywhere in this file, and there should never be — the moment a
+ * topic starts parsing human output it will disagree with the framework the
+ * first time a column is widened.
+ *
+ * Each topic's return value is the tool's `structuredContent`, so its shape is a
+ * published contract: change one and the matching `outputSchema` in `tools/`
+ * changes with it.
+ */
+import { Router, deployEnv, runDoctor } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+
+/** The topics `zt arch:probe` can be asked for. */
+export const PROBE_TOPICS = ["doctor", "routes", "schema", "app-info"] as const;
+
+export type ProbeTopic = (typeof PROBE_TOPICS)[number];
+
+export function isProbeTopic(value: string): value is ProbeTopic {
+  return (PROBE_TOPICS as readonly string[]).includes(value);
+}
+
+// ── Shapes ────────────────────────────────────────────────────────────────────
+
+export interface DoctorFinding {
+  id: string;
+  label: string;
+  status: "ok" | "warn" | "fail";
+  message: string;
+  /** The command or edit that resolves it. Absent when the finding is `ok`. */
+  fix?: string;
+}
+
+export interface DoctorReport {
+  findings: DoctorFinding[];
+  counts: { ok: number; warn: number; fail: number; total: number };
+  /** True when nothing is broken outright. Warnings do not clear this. */
+  healthy: boolean;
+}
+
+export interface RouteEntry {
+  method: string;
+  path: string;
+  controller: string;
+  action: string;
+  /** The name `route()` takes, when the route has one. */
+  name?: string;
+  middleware: string[];
+  domain?: string;
+}
+
+export interface RouteReport {
+  routes: RouteEntry[];
+  total: number;
+}
+
+export interface SchemaColumn {
+  name: string;
+  type: string;
+  nullable: boolean;
+  primary: boolean;
+  unique: boolean;
+  indexed: boolean;
+}
+
+export interface SchemaModel {
+  table: string;
+  primaryKey: string;
+  timestamps: boolean;
+  softDeletes: boolean;
+  columns: SchemaColumn[];
+}
+
+export interface SchemaReport {
+  models: SchemaModel[];
+  total: number;
+  /** Why the list is empty, when it is — an app with no ORM is not an error. */
+  note?: string;
+}
+
+export interface InstalledPackage {
+  name: string;
+  version: string;
+  /** The package's compatibility promise: `stable`, `beta` or `experimental`. */
+  maturity?: string;
+}
+
+export interface AppInfo {
+  bun: string;
+  environment: string;
+  appEnv: string;
+  url?: string;
+  providers: string[];
+  packages: InstalledPackage[];
+  webSocketPaths: string[];
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+/** Run one topic against a booted app and return its report. */
+export async function probe(topic: ProbeTopic, app: Application): Promise<unknown> {
+  switch (topic) {
+    case "doctor":
+      return doctorReport(app);
+    case "routes":
+      return routeReport();
+    case "schema":
+      return schemaReport();
+    case "app-info":
+      return appInfo(app);
+  }
+}
+
+// ── Topics ────────────────────────────────────────────────────────────────────
+
+/**
+ * Every check the app and its providers contribute, with the fix beside each.
+ *
+ * This is the tool an agent is meant to end a task with, which is why `healthy`
+ * is computed here rather than left to the caller: "3 warnings, 0 failures" is a
+ * judgement, and it should be the same judgement every time.
+ */
+export async function doctorReport(app: Application): Promise<DoctorReport> {
+  const entries = await runDoctor(app);
+  const findings: DoctorFinding[] = entries.map(({ check, result }) => ({
+    id: check.id,
+    label: check.label,
+    status: result.status,
+    message: result.message,
+    ...(result.fix !== undefined ? { fix: result.fix } : {}),
+  }));
+
+  const counts = {
+    ok: findings.filter((f) => f.status === "ok").length,
+    warn: findings.filter((f) => f.status === "warn").length,
+    fail: findings.filter((f) => f.status === "fail").length,
+    total: findings.length,
+  };
+
+  return { findings, counts, healthy: counts.fail === 0 };
+}
+
+/**
+ * The routes the app actually registered.
+ *
+ * Read after boot, so routes a provider added programmatically are here
+ * alongside the ones in `routes/` — which is the difference between this and
+ * reading the route files.
+ */
+export function routeReport(): RouteReport {
+  const nameByPath = new Map<string, string>();
+  for (const [name, path] of Router.namedRoutes) nameByPath.set(path, name);
+
+  const routes: RouteEntry[] = [...Router.routes.values()]
+    .map((route) => {
+      const name = route.name ?? nameByPath.get(route.path);
+      return {
+        method: route.method,
+        path: route.path,
+        controller: controllerLabel(route.controller.name),
+        action: route.action,
+        ...(name !== undefined ? { name } : {}),
+        middleware: route.middleware.map((m) => m.name).filter((n) => n.length > 0),
+        ...(route.domain !== undefined ? { domain: route.domain } : {}),
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+
+  return { routes, total: routes.length };
+}
+
+/**
+ * Model schemas as the ORM understands them.
+ *
+ * `@zerotal/orm` is imported dynamically because an app is not required to have
+ * one. A missing ORM is a report with a note, not a failure — the alternative is
+ * a hard dependency that every API-only app pays for.
+ */
+export async function schemaReport(): Promise<SchemaReport> {
+  let inspector: typeof import("@zerotal/orm").ModelInspector;
+  try {
+    ({ ModelInspector: inspector } = await import("@zerotal/orm"));
+  } catch {
+    return { models: [], total: 0, note: "@zerotal/orm is not installed in this app." };
+  }
+
+  const models: SchemaModel[] = inspector
+    .all()
+    .map((schema) => ({
+      table: schema.table,
+      primaryKey: schema.primaryKey,
+      timestamps: schema.timestamps,
+      softDeletes: schema.softDeletes,
+      columns: schema.columns.map((column) => ({
+        name: column.name,
+        // `@column()` with no `type` means `string` — that is the documented
+        // default and what `autoMigrate` generates. Reporting the raw absence
+        // would tell a reader the column has no type when it has the commonest
+        // one, and this is read by something about to write a migration.
+        type: column.type ?? "string",
+        nullable: column.nullable,
+        primary: column.primary,
+        unique: column.unique === true,
+        indexed: column.index === true,
+      })),
+    }))
+    .sort((a, b) => a.table.localeCompare(b.table));
+
+  if (models.length === 0) {
+    return {
+      models: [],
+      total: 0,
+      note:
+        "No models are registered. Models self-register when their file is imported, which the " +
+        "`models` convention does at boot — check app/models/ exists and conventions are enabled.",
+    };
+  }
+  return { models, total: models.length };
+}
+
+/** What this app is: runtime, environment, providers, and the packages behind them. */
+export async function appInfo(app: Application): Promise<AppInfo> {
+  const url = readConfig(app, "app.url");
+  return {
+    bun: Bun.version,
+    // Two different things that both get called "environment", reported apart:
+    // `_env` is the runtime mode this process booted as (console, here, since a
+    // probe runs under the CLI), while `deployEnv()` is the deployment name —
+    // local, staging, production. `Bun.env.APP_ENV` is not the second one: the
+    // CLI overwrites it with the runtime mode before the app is imported.
+    environment: String(app._env),
+    appEnv: String(readConfig(app, "app.env") ?? deployEnv()),
+    ...(typeof url === "string" ? { url } : {}),
+    providers: (app._activeProviders ?? []).map((provider) => provider.constructor.name).sort(),
+    packages: await installedPackages(),
+    webSocketPaths: app.webSocketPaths(),
+  };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function readConfig(app: Application, key: string): unknown {
+  try {
+    const config = app.container.makeSync("config") as { get(k: string): unknown };
+    return config.get(key);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The installed `@zerotal/*` packages and their maturity.
+ *
+ * Read from disk rather than from a hard-coded list: the point is to report the
+ * versions this app is actually running, including ones this package has never
+ * heard of.
+ */
+export async function installedPackages(root = process.cwd()): Promise<InstalledPackage[]> {
+  const found: InstalledPackage[] = [];
+  const glob = new Bun.Glob("node_modules/{zerotal,@zerotal/*}/package.json");
+
+  for await (const file of glob.scan({ cwd: root, onlyFiles: true })) {
+    try {
+      const manifest = (await Bun.file(`${root}/${file}`).json()) as Record<string, unknown>;
+      const name = manifest["name"];
+      const version = manifest["version"];
+      if (typeof name !== "string" || typeof version !== "string") continue;
+      const maturity = manifest["maturity"];
+      found.push({
+        name,
+        version,
+        ...(typeof maturity === "string" ? { maturity } : {}),
+      });
+    } catch {
+      /* an unreadable manifest is one package missing from a report, not a failure */
+    }
+  }
+
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** File-based route controllers are named `FileRoute<METHOD /path>` — say "file" instead. */
+function controllerLabel(rawName: string): string {
+  return rawName.startsWith("FileRoute<") ? "file" : rawName;
+}