@zerotal/arch 1.7.0

package/src/install/markers.ts

@@ -0,0 +1,77 @@
+/**
+ * Managed blocks: how a generated file stays generated without eating what
+ * someone wrote around it.
+ *
+ * `arch:update` runs on every framework upgrade, and the file it rewrites is one
+ * a developer is invited to edit — that is the point of `AGENTS.md`. So the
+ * generated region is fenced, and only the region is ever replaced. Text above
+ * it, below it, and any second block someone added by hand all survive.
+ *
+ * A file whose markers are damaged is left completely alone and reported as a
+ * conflict. Guessing where the block was meant to end is how a tool deletes a
+ * paragraph nobody backed up.
+ */
+
+export const BLOCK_START = "<!-- zerotal:arch:start -->";
+export const BLOCK_END = "<!-- zerotal:arch:end -->";
+
+export type BlockOutcome =
+  /** The file did not exist, or had no block: one was added. */
+  | { status: "created"; text: string }
+  /** The block was there and its contents changed. */
+  | { status: "updated"; text: string }
+  /** The block was there and already said this. */
+  | { status: "unchanged"; text: string }
+  /** The markers are damaged; nothing was written. */
+  | { status: "conflict"; reason: string };
+
+/** Wrap generated content in its markers. */
+export function fence(content: string): string {
+  return `${BLOCK_START}\n${content.trim()}\n${BLOCK_END}`;
+}
+
+/**
+ * Put `content` into `existing`'s managed block.
+ *
+ * @param existing - The file's current text, or `undefined` when there is none.
+ * @param content - The generated body, unfenced.
+ * @param preamble - Written above the block, once, only when creating the file.
+ *   Never rewritten afterwards — it is the developer's from that moment on.
+ */
+export function applyBlock(
+  existing: string | undefined,
+  content: string,
+  preamble = "",
+): BlockOutcome {
+  const block = fence(content);
+
+  if (existing === undefined || existing.trim().length === 0) {
+    const head = preamble.trim().length > 0 ? `${preamble.trim()}\n\n` : "";
+    return { status: "created", text: `${head}${block}\n` };
+  }
+
+  const start = existing.indexOf(BLOCK_START);
+  const end = existing.indexOf(BLOCK_END);
+
+  if (start === -1 && end === -1) {
+    // A file that predates this tool. Append rather than prepend: whatever is
+    // already at the top is what its author chose to say first.
+    return { status: "created", text: `${existing.trimEnd()}\n\n${block}\n` };
+  }
+
+  if (start === -1 || end === -1 || end < start) {
+    return {
+      status: "conflict",
+      reason:
+        start === -1
+          ? `found ${BLOCK_END} with no opening marker`
+          : end === -1
+            ? `found ${BLOCK_START} with no closing marker`
+            : "the closing marker comes before the opening one",
+    };
+  }
+
+  const text = existing.slice(0, start) + block + existing.slice(end + BLOCK_END.length);
+
+  return text === existing ? { status: "unchanged", text } : { status: "updated", text };
+}

package/src/install/mcpConfig.ts

@@ -0,0 +1,81 @@
+/**
+ * Registering this server in an MCP client's config.
+ *
+ * The file belongs to the project, not to us: it may already list three other
+ * servers, and it may have been hand-edited. So the write is a merge of one key
+ * into whatever is there, and every other key comes through byte-for-byte
+ * intact — including ones no schema this package knows about.
+ *
+ * A file that is not valid JSON is reported, not overwritten. There is no
+ * version of "I could not read your config so I replaced it" that is the right
+ * thing to do.
+ */
+import type { McpTarget } from "./detect.ts";
+
+/** Where the server lives, relative to the project root. */
+export const SERVER_ENTRY_PATH = "node_modules/@zerotal/arch/src/bin/mcp.ts";
+
+export type ConfigOutcome =
+  | { status: "created" | "updated" | "unchanged"; text: string }
+  | { status: "conflict"; reason: string };
+
+/** The server entry an MCP client is given. */
+export function serverEntry(): Record<string, unknown> {
+  return {
+    // `bun`, not `bunx`: the app runs on Bun and so must its agent surface,
+    // and a bare command resolves through PATH to whatever is first.
+    command: "bun",
+    args: [SERVER_ENTRY_PATH],
+  };
+}
+
+/**
+ * Merge this server into an MCP config document.
+ *
+ * @param existing - The file's current text, or `undefined` when there is none.
+ * @param name - The key to register under.
+ * @param target - Which client's file this is; decides the container key.
+ */
+export function applyMcpConfig(
+  existing: string | undefined,
+  name: string,
+  target: McpTarget,
+): ConfigOutcome {
+  let document: Record<string, unknown> = {};
+  const isNew = existing === undefined || existing.trim().length === 0;
+
+  if (!isNew) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(existing);
+    } catch (error) {
+      return {
+        status: "conflict",
+        reason: `${target.path} is not valid JSON (${describe(error)}) — left untouched.`,
+      };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return {
+        status: "conflict",
+        reason: `${target.path} is not a JSON object — left untouched.`,
+      };
+    }
+    document = parsed as Record<string, unknown>;
+  }
+
+  const container = document[target.key];
+  const servers: Record<string, unknown> =
+    typeof container === "object" && container !== null && !Array.isArray(container)
+      ? { ...(container as Record<string, unknown>) }
+      : {};
+
+  servers[name] = serverEntry();
+  const text = JSON.stringify({ ...document, [target.key]: servers }, null, 2) + "\n";
+
+  if (isNew) return { status: "created", text };
+  return text === existing ? { status: "unchanged", text } : { status: "updated", text };
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/mcp/index.ts

@@ -0,0 +1,27 @@
+/**
+ * The transport half of `@zerotal/arch`, exported on its own subpath.
+ *
+ * Nothing here knows what a Zerotal app is. It is published separately from the
+ * root barrel so a package can build its own MCP server over these pieces —
+ * hand {@link McpServer} an array of {@link ArchTool} and serve it — without
+ * pulling in the tools, the probe command, or the vendored docs.
+ */
+export { McpServer } from "./server.ts";
+export type { McpServerOptions } from "./server.ts";
+export { serveStdio } from "./stdio.ts";
+export type { StdioOptions } from "./stdio.ts";
+export { decodeFrame, encodeFrame, failure, success } from "./jsonrpc.ts";
+export type { DecodedFrame } from "./jsonrpc.ts";
+export { LEGACY_VERSIONS, Meta, MODERN_VERSION, RpcError, SUPPORTED_VERSIONS } from "./types.ts";
+export type {
+  ArchTool,
+  Era,
+  JsonRpcFailure,
+  JsonRpcId,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcSuccess,
+  JsonSchema,
+  ServerIdentity,
+  ToolOutcome,
+} from "./types.ts";

package/src/mcp/jsonrpc.ts

@@ -0,0 +1,133 @@
+/**
+ * JSON-RPC 2.0 framing for the stdio binding.
+ *
+ * The wire format is one JSON message per line, and the spec states the
+ * constraint as a hard MUST NOT: a message may not contain an embedded newline.
+ * `JSON.stringify` already escapes newlines inside strings, so the rule holds by
+ * construction — {@link encodeFrame} asserts it anyway, because the one thing
+ * that must never happen here is a half-message splitting a client's parser and
+ * desynchronising every frame after it.
+ *
+ * Decoding never throws. A line that is not JSON, or is JSON but not a request,
+ * comes back as a ready-to-send failure rather than an exception — a malformed
+ * frame is a thing to answer, not a reason for the server to stop reading.
+ */
+import { RpcError } from "./types.ts";
+import type { JsonRpcFailure, JsonRpcId, JsonRpcRequest, JsonRpcResponse } from "./types.ts";
+
+/** The result of reading one line: either a request to dispatch, or a reply to send. */
+export type DecodedFrame =
+  { ok: true; request: JsonRpcRequest } | { ok: false; failure: JsonRpcFailure };
+
+/** Build a JSON-RPC success reply. */
+export function success(id: JsonRpcId, result: Record<string, unknown>): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, result };
+}
+
+/**
+ * Build a JSON-RPC error reply.
+ *
+ * `id` is `null` only when the inbound frame was too broken to carry one — that
+ * is the one case JSON-RPC allows it, and conflating it with a real id would
+ * make a client correlate the failure to the wrong request.
+ */
+export function failure(
+  id: JsonRpcId | null,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcFailure {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: { code, message, ...(data !== undefined ? { data } : {}) },
+  };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** An id is usable if JSON-RPC allows it there: a string or a number, never anything else. */
+function readId(value: unknown): JsonRpcId | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return undefined;
+}
+
+/**
+ * Turn one line of input into a request, or into the failure to answer it with.
+ *
+ * Blank lines return `undefined` — clients and shells both emit them, and
+ * answering a blank line with a parse error would be noise rather than help.
+ */
+export function decodeFrame(line: string): DecodedFrame | undefined {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return undefined;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return { ok: false, failure: failure(null, RpcError.PARSE, "Invalid JSON.") };
+  }
+
+  // Batches were never part of the stdio binding's message rules — one message
+  // per line — and the modern revision does not reinstate them.
+  if (Array.isArray(parsed)) {
+    return {
+      ok: false,
+      failure: failure(null, RpcError.INVALID_REQUEST, "Batched requests are not supported."),
+    };
+  }
+  if (!isPlainObject(parsed)) {
+    return {
+      ok: false,
+      failure: failure(null, RpcError.INVALID_REQUEST, "A message must be a JSON object."),
+    };
+  }
+
+  const id = readId(parsed["id"]);
+  if (parsed["jsonrpc"] !== "2.0") {
+    return {
+      ok: false,
+      failure: failure(id ?? null, RpcError.INVALID_REQUEST, 'Expected "jsonrpc": "2.0".'),
+    };
+  }
+
+  const method = parsed["method"];
+  if (typeof method !== "string" || method.length === 0) {
+    return {
+      ok: false,
+      failure: failure(id ?? null, RpcError.INVALID_REQUEST, "Missing method."),
+    };
+  }
+
+  const rawParams = parsed["params"];
+  const params = isPlainObject(rawParams) ? rawParams : undefined;
+
+  return {
+    ok: true,
+    request: {
+      jsonrpc: "2.0",
+      method,
+      ...(id !== undefined ? { id } : {}),
+      ...(params !== undefined ? { params } : {}),
+    },
+  };
+}
+
+/**
+ * Serialise one message to its wire line, newline included.
+ *
+ * @throws If the encoded form contains a raw newline. Unreachable through
+ *   `JSON.stringify`, and asserted rather than trusted because a frame that
+ *   splits across two lines corrupts the stream from that point on.
+ */
+export function encodeFrame(message: JsonRpcResponse): string {
+  const encoded = JSON.stringify(message);
+  if (encoded.includes("\n") || encoded.includes("\r")) {
+    throw new Error("Encoded JSON-RPC frame contains a newline.");
+  }
+  return encoded + "\n";
+}

package/src/mcp/server.ts

@@ -0,0 +1,307 @@
+/**
+ * Method dispatch and protocol-era negotiation.
+ *
+ * ## Why this speaks two protocols
+ *
+ * The 2026-07-28 revision made MCP stateless: it removed the
+ * `initialize`/`notifications/initialized` handshake, moved the protocol
+ * version into every request's `_meta`, and made `server/discover` mandatory.
+ * That revision was published on 28 July 2026, and the clients in the field
+ * still open with `initialize`.
+ *
+ * The spec's own compatibility matrix has exactly one row that works against
+ * both kinds of client, and it is the dual-era server. So this one selects its
+ * behaviour from how the caller opens — modern `_meta` on the request, or an
+ * `initialize` handshake — and answers each request in the era it arrived in.
+ *
+ * `server/discover` carries a second job on stdio: it is the probe a dual-era
+ * *client* sends to work out which kind of server it is talking to. Answering it
+ * is what stops a modern client falling back to `initialize` against a server
+ * that never needed it.
+ *
+ * ## What this file does not know
+ *
+ * Anything about Zerotal. It is handed an array of {@link ArchTool} and calls
+ * them; every tool here would work unchanged behind a different transport.
+ */
+import { failure, success } from "./jsonrpc.ts";
+import { LEGACY_VERSIONS, Meta, MODERN_VERSION, RpcError, SUPPORTED_VERSIONS } from "./types.ts";
+import type {
+  ArchTool,
+  Era,
+  JsonRpcId,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  ServerIdentity,
+  ToolOutcome,
+} from "./types.ts";
+
+/** How long a client may cache `tools/list`. The set is fixed at build time. */
+const LIST_TTL_MS = 3_600_000;
+
+export interface McpServerOptions {
+  identity: ServerIdentity;
+  /**
+   * The tools to expose, in the order they should be listed.
+   *
+   * Order is preserved rather than sorted: the spec asks for a deterministic
+   * order so clients can cache and prompt caches can hit, and the registry's
+   * own order is already deliberate — most useful first.
+   */
+  tools: readonly ArchTool[];
+}
+
+/** A request that is in flight, and the handle that cancels it. */
+interface InFlight {
+  controller: AbortController;
+  cancelled: boolean;
+}
+
+export class McpServer {
+  private readonly _identity: ServerIdentity;
+  private readonly _tools: readonly ArchTool[];
+  private readonly _byName: Map<string, ArchTool>;
+  private readonly _inFlight = new Map<JsonRpcId, InFlight>();
+
+  /**
+   * The era the client established, once it has.
+   *
+   * Requests carrying modern `_meta` are self-describing and never need this;
+   * it exists for the legacy era, where `initialize` sets the terms for every
+   * request that follows.
+   */
+  private _negotiated: { era: Era; version: string } | undefined;
+
+  constructor(options: McpServerOptions) {
+    this._identity = options.identity;
+    this._tools = options.tools;
+    this._byName = new Map(options.tools.map((tool) => [tool.name, tool]));
+  }
+
+  /**
+   * Handle one request.
+   *
+   * Returns the reply to write, or `undefined` when there is nothing to say —
+   * a notification, or a request that was cancelled while it ran. The spec is
+   * strict about the second case: after `notifications/cancelled`, the server
+   * MUST NOT send anything further for that id.
+   */
+  async handle(request: JsonRpcRequest): Promise<JsonRpcResponse | undefined> {
+    // Notifications carry no id and are never answered.
+    if (request.id === undefined) {
+      this._handleNotification(request);
+      return undefined;
+    }
+    const id = request.id;
+
+    const era = this._eraFor(request);
+    if (era === "unsupported") {
+      const requested = readProtocolVersion(request);
+      return failure(id, RpcError.UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", {
+        supported: [...SUPPORTED_VERSIONS],
+        requested,
+      });
+    }
+
+    switch (request.method) {
+      case "server/discover":
+        return success(id, this._discover());
+      case "initialize":
+        return success(id, this._initialize(request));
+      case "ping":
+        // Removed in the modern revision, but legacy clients send it as a
+        // liveness check and expect an empty result. Cheaper to answer than to
+        // explain.
+        return success(id, this._decorate({}, era));
+      case "tools/list":
+        return success(id, this._listTools(era));
+      case "tools/call":
+        return this._callTool(id, request, era);
+      default:
+        return failure(id, RpcError.METHOD_NOT_FOUND, `Unknown method: ${request.method}`);
+    }
+  }
+
+  // ── Era ─────────────────────────────────────────────────────────────────────
+
+  /**
+   * Which era this request is speaking, or `"unsupported"` when it names a
+   * version this server does not implement.
+   *
+   * A request that carries `_meta` protocol version is self-describing and is
+   * answered in the modern era whatever came before it — the spec treats the
+   * version as a per-request property, not a connection-wide one. Everything
+   * else falls back to what `initialize` negotiated, and then to legacy: a
+   * client that sends `tools/list` cold is not a modern one, because a modern
+   * client always states its version.
+   */
+  private _eraFor(request: JsonRpcRequest): Era | "unsupported" {
+    // `initialize` and `server/discover` carry their own version negotiation and
+    // must never be rejected before it happens — that would leave a client with
+    // no way to find out what this server speaks.
+    if (request.method === "initialize" || request.method === "server/discover") {
+      return request.method === "initialize" ? "legacy" : "modern";
+    }
+
+    const declared = readProtocolVersion(request);
+    if (declared !== undefined) {
+      if (!(SUPPORTED_VERSIONS as readonly string[]).includes(declared)) return "unsupported";
+      return declared === MODERN_VERSION ? "modern" : "legacy";
+    }
+
+    return this._negotiated?.era ?? "legacy";
+  }
+
+  // ── Methods ─────────────────────────────────────────────────────────────────
+
+  /**
+   * `server/discover` — what this server is and what it speaks.
+   *
+   * Mandatory in the modern revision, and doubly useful on stdio: it is also the
+   * backward-compatibility probe, so answering it correctly is what tells a
+   * dual-era client it need not fall back.
+   */
+  private _discover(): Record<string, unknown> {
+    return {
+      resultType: "complete",
+      supportedVersions: [...SUPPORTED_VERSIONS],
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { ...this._identity },
+      _meta: { [Meta.SERVER_INFO]: { ...this._identity } },
+    };
+  }
+
+  /** The legacy handshake. Echoes a version both ends know. */
+  private _initialize(request: JsonRpcRequest): Record<string, unknown> {
+    const requested = request.params?.["protocolVersion"];
+    const version =
+      typeof requested === "string" && (LEGACY_VERSIONS as readonly string[]).includes(requested)
+        ? requested
+        : LEGACY_VERSIONS[0];
+
+    this._negotiated = { era: "legacy", version };
+
+    return {
+      protocolVersion: version,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { ...this._identity },
+    };
+  }
+
+  private _listTools(era: Era): Record<string, unknown> {
+    const tools = this._tools.map((tool) => ({
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      outputSchema: tool.outputSchema,
+    }));
+
+    if (era === "legacy") return { tools };
+
+    // `ttlMs` and `cacheScope` are required on a modern list result. `private`
+    // because the answer is specific to this project's checkout — nothing about
+    // it is safe for a shared intermediary to serve to someone else.
+    return this._decorate({ tools, ttlMs: LIST_TTL_MS, cacheScope: "private" }, era);
+  }
+
+  private async _callTool(
+    id: JsonRpcId,
+    request: JsonRpcRequest,
+    era: Era,
+  ): Promise<JsonRpcResponse | undefined> {
+    const name = request.params?.["name"];
+    if (typeof name !== "string") {
+      return failure(id, RpcError.INVALID_PARAMS, "tools/call requires a string `name`.");
+    }
+    const tool = this._byName.get(name);
+    if (!tool) {
+      return failure(id, RpcError.INVALID_PARAMS, `Unknown tool: ${name}`);
+    }
+
+    const rawArgs = request.params?.["arguments"];
+    const args =
+      typeof rawArgs === "object" && rawArgs !== null && !Array.isArray(rawArgs)
+        ? (rawArgs as Record<string, unknown>)
+        : {};
+
+    const entry: InFlight = { controller: new AbortController(), cancelled: false };
+    this._inFlight.set(id, entry);
+
+    let outcome: ToolOutcome;
+    try {
+      outcome = await tool.run(args, entry.controller.signal);
+    } catch (error) {
+      // A tool that throws has still *run*. Reporting that as a protocol error
+      // would hide it from the model, which is the one party able to correct it.
+      outcome = { text: describe(error), failed: true };
+    } finally {
+      this._inFlight.delete(id);
+    }
+
+    if (entry.cancelled) return undefined;
+    return success(id, this._renderOutcome(outcome, era));
+  }
+
+  /**
+   * A tool outcome as MCP content.
+   *
+   * The spec suggests a tool returning structured content also repeat it as
+   * serialised JSON in a text block, for clients that do not read
+   * `structuredContent`. That is skipped deliberately here: every tool in this
+   * package renders its full answer into `text` already, so the extra block
+   * would be the same information twice in a model's context window rather than
+   * a fallback for anything it would otherwise miss.
+   */
+  private _renderOutcome(outcome: ToolOutcome, era: Era): Record<string, unknown> {
+    const result: Record<string, unknown> = {
+      content: [{ type: "text", text: outcome.text }],
+      isError: outcome.failed === true,
+    };
+    if (outcome.data !== undefined) result["structuredContent"] = outcome.data;
+    return this._decorate(result, era);
+  }
+
+  /** Add the fields a modern result carries and a legacy one does not. */
+  private _decorate(result: Record<string, unknown>, era: Era): Record<string, unknown> {
+    if (era === "legacy") return result;
+    return {
+      resultType: "complete",
+      ...result,
+      _meta: { [Meta.SERVER_INFO]: { ...this._identity } },
+    };
+  }
+
+  // ── Notifications ───────────────────────────────────────────────────────────
+
+  private _handleNotification(request: JsonRpcRequest): void {
+    if (request.method === "notifications/cancelled") {
+      const target = request.params?.["requestId"];
+      if (typeof target === "string" || typeof target === "number") {
+        const entry = this._inFlight.get(target);
+        if (entry) {
+          entry.cancelled = true;
+          entry.controller.abort();
+        }
+      }
+      return;
+    }
+    // `notifications/initialized` closes the legacy handshake and needs nothing
+    // done. Anything else is a notification this server has no interest in, and
+    // notifications are by definition not answered — including with an error.
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** The protocol version a modern request declares in `_meta`, if it declares one. */
+function readProtocolVersion(request: JsonRpcRequest): string | undefined {
+  const meta = request.params?.["_meta"];
+  if (typeof meta !== "object" || meta === null) return undefined;
+  const version = (meta as Record<string, unknown>)[Meta.PROTOCOL_VERSION];
+  return typeof version === "string" ? version : undefined;
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}