@zerotal/arch 1.7.0

package/src/provider/ArchProvider.ts

@@ -0,0 +1,101 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment, DoctorCheck } from "@zerotal/core";
+import { SERVER_ENTRY_PATH } from "../install/mcpConfig.ts";
+
+/**
+ * Registers the agent-surface commands.
+ *
+ * Binds nothing. The MCP server is a separate process that never boots an
+ * application — see `src/bin/mcp.ts` for why — so there is no manager to put in
+ * the container and no request-time behaviour to add. What this provider is for
+ * is the three commands, and the check that says whether the server has actually
+ * been wired up.
+ *
+ * `console` only. Every command here is a developer tool, and a web process has
+ * no reason to carry them.
+ *
+ * Register in `bootstrap/providers.ts`:
+ *
+ * ```typescript
+ * import { ArchProvider } from "@zerotal/arch";
+ *
+ * Application.create()
+ *   .register([DatabaseProvider, ArchProvider])
+ * ```
+ */
+export class ArchProvider extends ServiceProvider {
+  static override provides = [] as const;
+  static override environments: AppEnvironment[] = ["console"];
+
+  override async onBooted(): Promise<void> {
+    const runner = this.app.container.tryMake("commands");
+    if (!runner) return;
+
+    runner.registerLazy(
+      "arch:install",
+      () => import("../install/ArchInstallCommand.ts").then((m) => m.ArchInstallCommand),
+      ["arch:update"],
+    );
+    runner.registerLazy("arch:probe", () =>
+      import("../probe/ArchProbeCommand.ts").then((m) => m.ArchProbeCommand),
+    );
+  }
+
+  /**
+   * One check: is the MCP server registered where an agent will find it?
+   *
+   * A project that installed this package and never ran `arch:install` has an
+   * agent surface that exists and is not connected to anything — which looks
+   * exactly like it working until someone notices no tool was ever called.
+   */
+  override doctorChecks(): DoctorCheck[] {
+    return [
+      {
+        id: "arch-mcp-config",
+        label: "Agent surface",
+        run: async () => {
+          const entry = Bun.file(`${process.cwd()}/${SERVER_ENTRY_PATH}`);
+          if (!(await entry.exists())) {
+            return {
+              status: "warn" as const,
+              message:
+                "@zerotal/arch is registered but its server entry is missing from node_modules.",
+              fix: "bun install",
+            };
+          }
+
+          const config = Bun.file(`${process.cwd()}/.mcp.json`);
+          if (!(await config.exists())) {
+            return {
+              status: "warn" as const,
+              message:
+                "No .mcp.json, so no agent is connected to this app's MCP server — the tools " +
+                "exist but nothing can call them.",
+              fix: "bun zt arch:install",
+            };
+          }
+
+          try {
+            const document = (await config.json()) as Record<string, unknown>;
+            const servers = document["mcpServers"];
+            const names =
+              typeof servers === "object" && servers !== null ? Object.keys(servers) : [];
+            return names.length > 0
+              ? { status: "ok" as const, message: `.mcp.json registers ${names.join(", ")}` }
+              : {
+                  status: "warn" as const,
+                  message: ".mcp.json declares no MCP servers.",
+                  fix: "bun zt arch:install",
+                };
+          } catch {
+            return {
+              status: "warn" as const,
+              message: ".mcp.json is not valid JSON, so no agent can read it.",
+              fix: "Fix the JSON, then run bun zt arch:install.",
+            };
+          }
+        },
+      },
+    ];
+  }
+}

package/src/tools/_probe.ts

@@ -0,0 +1,164 @@
+/**
+ * The one place a tool reaches into a booted application.
+ *
+ * Spawns `bun zt.ts arch:probe <topic>` in the project, reads the JSON the
+ * command frames with {@link PROBE_SENTINEL}, and hands it back. Everything the
+ * subprocess printed before the sentinel — banners, provider notices, a warning
+ * from a package — is discarded; only stderr is kept, and only to explain a
+ * failure.
+ *
+ * ## There is deliberately no cache
+ *
+ * Booting the app costs a second or so, and a burst of tool calls in one agent
+ * turn pays it each time. That is the trade being made on purpose: the caller is
+ * an agent that edits routes and models between calls, and an answer cached even
+ * for a few seconds can describe code that no longer exists. A slow correct
+ * answer is recoverable; a fast wrong one is what sends an agent down a path
+ * nothing will contradict.
+ */
+import { dirname, join } from "node:path";
+import { PROBE_SENTINEL } from "../probe/sentinel.ts";
+import type { ProbeTopic } from "../probe/topics.ts";
+
+/** How long a probe may run before it is killed. Boot plus a wide margin. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/** Entry filenames an app may use, in the order `bun zt` would find them. */
+const ENTRY_NAMES = ["zt.ts", "zt.js"] as const;
+
+export type ProbeResult = { ok: true; data: unknown } | { ok: false; message: string };
+
+/** The seam tools depend on, so a tool's own tests never boot an application. */
+export interface ProbeRunner {
+  run(topic: ProbeTopic, signal: AbortSignal): Promise<ProbeResult>;
+}
+
+export interface SpawnProbeOptions {
+  /** Where to start looking for the app. Defaults to the server's working directory. */
+  cwd?: string;
+  timeoutMs?: number;
+}
+
+/**
+ * Find the Zerotal app enclosing `start` — the nearest ancestor holding both a
+ * `package.json` and a `zt` entry point.
+ *
+ * Walks upward rather than trusting the working directory outright: an editor or
+ * an MCP client may launch the server from a subdirectory, and failing with
+ * "no app here" when the app is two levels up is a bad first impression.
+ */
+export async function findApp(start: string): Promise<{ root: string; entry: string } | undefined> {
+  let dir = start;
+  for (;;) {
+    if (await Bun.file(join(dir, "package.json")).exists()) {
+      for (const name of ENTRY_NAMES) {
+        if (await Bun.file(join(dir, name)).exists()) return { root: dir, entry: name };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * Take the JSON a probe framed, ignoring whatever the app printed around it.
+ *
+ * The *last* sentinel wins: a log line quoting an earlier one cannot displace
+ * the real answer, because the real answer is always written last.
+ */
+export function extractPayload(stdout: string): ProbeResult {
+  const marker = stdout.lastIndexOf(PROBE_SENTINEL);
+  if (marker === -1) {
+    return {
+      ok: false,
+      message: "The probe produced no report — the app printed nothing this tool could read.",
+    };
+  }
+
+  const body = stdout.slice(marker + PROBE_SENTINEL.length).trim();
+  if (body.length === 0) {
+    return { ok: false, message: "The probe framed an empty report." };
+  }
+
+  try {
+    return { ok: true, data: JSON.parse(body) as unknown };
+  } catch (error) {
+    return {
+      ok: false,
+      message: `The probe's report was not valid JSON: ${describe(error)}`,
+    };
+  }
+}
+
+/** The real runner: spawns the app's CLI and reads one topic out of it. */
+export function spawnProbe(options: SpawnProbeOptions = {}): ProbeRunner {
+  const startDir = options.cwd ?? process.cwd();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return {
+    async run(topic, signal) {
+      const app = await findApp(startDir);
+      if (!app) {
+        return {
+          ok: false,
+          message:
+            `No Zerotal app found at or above ${startDir} — looked for a package.json beside ` +
+            `${ENTRY_NAMES.join(" or ")}. Run this server from the project root.`,
+        };
+      }
+
+      // `process.execPath` rather than "bun": the app must run on the same
+      // runtime as this server, and a PATH lookup can find a different one.
+      const child = Bun.spawn([process.execPath, app.entry, "arch:probe", topic], {
+        cwd: app.root,
+        stdout: "pipe",
+        stderr: "pipe",
+        // The probe reads config and the filesystem; it must not inherit a
+        // terminal it could block on.
+        stdin: "ignore",
+      });
+
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill();
+      }, timeoutMs);
+      const abort = (): void => void child.kill();
+      signal.addEventListener("abort", abort, { once: true });
+
+      try {
+        const [stdout, stderr, code] = await Promise.all([
+          new Response(child.stdout).text(),
+          new Response(child.stderr).text(),
+          child.exited,
+        ]);
+
+        if (timedOut) {
+          return { ok: false, message: `The app did not boot within ${timeoutMs / 1000}s.` };
+        }
+        if (signal.aborted) return { ok: false, message: "Cancelled." };
+
+        const payload = extractPayload(stdout);
+        if (payload.ok) return payload;
+
+        // The app failed to boot, or the topic threw. Its stderr is the only
+        // thing that explains why, and it is exactly what the caller needs.
+        const detail = stderr.trim() || stdout.trim();
+        return {
+          ok: false,
+          message:
+            `\`bun ${app.entry} arch:probe ${topic}\` exited ${code}.` +
+            (detail ? `\n\n${detail}` : ` ${payload.message}`),
+        };
+      } finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+      }
+    },
+  };
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/tools/apiSurface.ts

@@ -0,0 +1,241 @@
+/**
+ * `api_surface` — hand over the signature, not a description of it.
+ *
+ * Every `@zerotal/*` package commits an `api-surface.md`: the name, kind and
+ * full type of every public export, extracted by the TypeScript checker and
+ * diffed by CI on every change. It is the asset this whole package is built
+ * around. A docs search can tell an agent that a fluent builder exists; this
+ * tells it the exact call it must write for `tsc` to accept it.
+ *
+ * The file is read from the *installed* package — `node_modules/@zerotal/<pkg>`
+ * — so the answer describes the version this app actually runs. Inside the
+ * framework's own monorepo it falls back to `packages/<pkg>`, which is the same
+ * file by another path.
+ */
+import { join } from "node:path";
+import type { ArchTool, ToolOutcome } from "../mcp/types.ts";
+import type { ToolContext } from "./context.ts";
+
+/** One exported symbol, as recorded in the snapshot. */
+export interface SurfaceEntry {
+  /** The subpath it is exported from, e.g. `.` or `./config`. */
+  subpath: string;
+  /** `class` | `interface` | `type` | `function` | `const` | `enum` | `namespace` | `value`. */
+  kind: string;
+  name: string;
+  /** The full rendered signature, class bodies included. */
+  signature: string;
+}
+
+/** A line that opens an entry: `class Foo = {`, `function bar = (…) => …`. */
+const ENTRY_START = /^(class|interface|type|enum|function|namespace|const|value) (\S+) = ?(.*)$/;
+/** A section heading: `## ./config  \`(src/config/index.ts)\`` */
+const SECTION_START = /^## (\S+)/;
+
+/**
+ * Parse a committed `api-surface.md` into its entries.
+ *
+ * Line-driven rather than split-on-blank-line: a rendered class body is
+ * multi-line, and a signature that happened to contain a blank line would
+ * silently truncate the export it belongs to.
+ */
+export function parseSurface(markdown: string): SurfaceEntry[] {
+  const entries: SurfaceEntry[] = [];
+  let subpath = ".";
+  let current: SurfaceEntry | undefined;
+  let body: string[] = [];
+
+  const flush = (): void => {
+    if (!current) return;
+    // Trailing blank lines are separators between entries, not part of one.
+    while (body.length > 0 && body[body.length - 1]!.trim() === "") body.pop();
+    entries.push({ ...current, signature: [current.signature, ...body].join("\n").trim() });
+    current = undefined;
+    body = [];
+  };
+
+  for (const line of markdown.split("\n")) {
+    const section = SECTION_START.exec(line);
+    if (section) {
+      flush();
+      subpath = section[1]!;
+      continue;
+    }
+
+    const start = ENTRY_START.exec(line);
+    if (start) {
+      flush();
+      current = { subpath, kind: start[1]!, name: start[2]!, signature: start[3] ?? "" };
+      continue;
+    }
+
+    if (current) body.push(line);
+  }
+  flush();
+
+  return entries;
+}
+
+/** Accept `core`, `@zerotal/core`, or the meta-package `zerotal`. */
+export function normalisePackageName(raw: string): { scoped: string; dir: string } {
+  const trimmed = raw.trim().replace(/^@zerotal\//, "");
+  if (trimmed === "zerotal") return { scoped: "zerotal", dir: "zerotal" };
+  return { scoped: `@zerotal/${trimmed}`, dir: trimmed };
+}
+
+/**
+ * Where this project's copy of a package's snapshot lives.
+ *
+ * `node_modules` first: that is the version the app is running, and the only
+ * one whose signatures are the truth for the code being written. The workspace
+ * path is the fallback for the framework's own repo, where there is no install
+ * to read.
+ */
+export async function findSurfaceFile(
+  root: string,
+  raw: string,
+): Promise<{ path: string; scoped: string } | undefined> {
+  const { scoped, dir } = normalisePackageName(raw);
+  const candidates = [
+    join(root, "node_modules", scoped, "api-surface.md"),
+    join(root, "packages", dir, "api-surface.md"),
+  ];
+  for (const path of candidates) {
+    if (await Bun.file(path).exists()) return { path, scoped };
+  }
+  return undefined;
+}
+
+/** Every package whose snapshot this project can serve, for the "did you mean" list. */
+async function availablePackages(root: string): Promise<string[]> {
+  const names = new Set<string>();
+  for (const pattern of [
+    "node_modules/{zerotal,@zerotal/*}/api-surface.md",
+    "packages/*/api-surface.md",
+  ]) {
+    try {
+      for await (const file of new Bun.Glob(pattern).scan({ cwd: root, onlyFiles: true })) {
+        const parts = file.split(/[\\/]/);
+        const dir = parts[parts.length - 2] ?? "";
+        names.add(dir === "zerotal" ? "zerotal" : `@zerotal/${dir}`);
+      }
+    } catch {
+      /* a pattern that matches nothing contributes nothing */
+    }
+  }
+  return [...names].sort();
+}
+
+export function apiSurfaceTool(ctx: ToolContext): ArchTool {
+  return {
+    name: "api_surface",
+    title: "API surface",
+    description:
+      "The exact public API of a Zerotal package: every export with its full TypeScript " +
+      "signature, including class members and static properties. This is the mechanical " +
+      "record CI diffs on every change, read from the version installed in this project — " +
+      "prefer it over recalling an API from memory. Pass `symbol` to narrow to one export.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        package: {
+          type: "string",
+          description: 'Package name, with or without the scope — "core" or "@zerotal/core".',
+        },
+        symbol: {
+          type: "string",
+          description:
+            "Only return exports whose name contains this, case-insensitively. Omit for all.",
+        },
+      },
+      required: ["package"],
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        package: { type: "string" },
+        total: { type: "number" },
+        matched: { type: "number" },
+        entries: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              subpath: { type: "string" },
+              kind: { type: "string" },
+              name: { type: "string" },
+              signature: { type: "string" },
+            },
+            required: ["subpath", "kind", "name", "signature"],
+          },
+        },
+      },
+      required: ["package", "total", "matched", "entries"],
+    },
+
+    async run(args): Promise<ToolOutcome> {
+      const requested = typeof args["package"] === "string" ? args["package"] : "";
+      if (requested.trim().length === 0) {
+        return { text: "`package` is required.", failed: true };
+      }
+
+      const found = await findSurfaceFile(ctx.root, requested);
+      if (!found) {
+        const available = await availablePackages(ctx.root);
+        return {
+          text:
+            `No API surface for "${requested}" in this project.` +
+            (available.length > 0 ? `\n\nAvailable: ${available.join(", ")}` : ""),
+          failed: true,
+        };
+      }
+
+      const all = parseSurface(await Bun.file(found.path).text());
+      const filter = typeof args["symbol"] === "string" ? args["symbol"].toLowerCase() : undefined;
+      const entries =
+        filter === undefined || filter.length === 0
+          ? all
+          : all.filter((entry) => entry.name.toLowerCase().includes(filter));
+
+      if (entries.length === 0) {
+        return {
+          text: `${found.scoped} exports nothing matching "${args["symbol"] as string}".`,
+          data: { package: found.scoped, total: all.length, matched: 0, entries: [] },
+        };
+      }
+
+      return {
+        text: render(found.scoped, entries, all.length),
+        data: {
+          package: found.scoped,
+          total: all.length,
+          matched: entries.length,
+          entries,
+        },
+      };
+    },
+  };
+}
+
+function render(pkg: string, entries: SurfaceEntry[], total: number): string {
+  const bySubpath = new Map<string, SurfaceEntry[]>();
+  for (const entry of entries) {
+    const list = bySubpath.get(entry.subpath) ?? [];
+    list.push(entry);
+    bySubpath.set(entry.subpath, list);
+  }
+
+  const header =
+    entries.length === total
+      ? `${pkg} — ${total} public export${total === 1 ? "" : "s"}`
+      : `${pkg} — ${entries.length} of ${total} exports`;
+
+  const sections = [...bySubpath].map(([subpath, list]) => {
+    const importPath = subpath === "." ? pkg : `${pkg}${subpath.slice(1)}`;
+    const body = list.map((entry) => `${entry.kind} ${entry.name} = ${entry.signature}`);
+    return `## import from "${importPath}"\n\n${body.join("\n\n")}`;
+  });
+
+  return `${header}\n\n${sections.join("\n\n")}`;
+}

package/src/tools/appInfo.ts

@@ -0,0 +1,88 @@
+/**
+ * `app_info` — what this app is, before an agent assumes.
+ *
+ * The version and maturity of every installed `@zerotal/*` package matter more
+ * than they look. Zerotal ships source, so the installed version *is* the API,
+ * and `maturity` is the package's own statement about how much of it is
+ * promised. An agent that knows a package is `beta` writes different code from
+ * one that assumes everything is settled.
+ *
+ * The provider list is the other half: half the silent failures in a Zerotal app
+ * are a feature whose provider was never registered, and that is visible here
+ * before it is visible anywhere else.
+ */
+import type { ArchTool, ToolOutcome } from "../mcp/types.ts";
+import type { AppInfo } from "../probe/topics.ts";
+import type { ToolContext } from "./context.ts";
+
+export function appInfoTool(ctx: ToolContext): ArchTool {
+  return {
+    name: "app_info",
+    title: "App info",
+    description:
+      "What this Zerotal app is: the Bun version, the environment it boots as, its configured " +
+      "URL, every registered service provider, the WebSocket paths it serves, and the version " +
+      "and maturity of every installed @zerotal package. Call it once at the start of a task — " +
+      "the installed versions decide which APIs exist, and the provider list decides which " +
+      "features are actually wired up.",
+    inputSchema: { type: "object", additionalProperties: false },
+    outputSchema: {
+      type: "object",
+      properties: {
+        bun: { type: "string" },
+        environment: {
+          type: "string",
+          description: "The boot mode: web, console, worker, test or repl.",
+        },
+        appEnv: { type: "string", description: "The deployment environment from config." },
+        url: { type: "string" },
+        providers: { type: "array", items: { type: "string" } },
+        webSocketPaths: { type: "array", items: { type: "string" } },
+        packages: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              version: { type: "string" },
+              maturity: { type: "string", enum: ["stable", "beta", "experimental"] },
+            },
+            required: ["name", "version"],
+          },
+        },
+      },
+      required: ["bun", "environment", "appEnv", "providers", "packages", "webSocketPaths"],
+    },
+
+    async run(_args, signal): Promise<ToolOutcome> {
+      const result = await ctx.probe.run("app-info", signal);
+      if (!result.ok) return { text: result.message, failed: true };
+
+      const info = result.data as AppInfo;
+      return { text: render(info), data: info };
+    },
+  };
+}
+
+function render(info: AppInfo): string {
+  const lines: string[] = [
+    `Bun ${info.bun} · boots as ${info.environment} · APP_ENV ${info.appEnv}`,
+  ];
+  if (info.url) lines.push(`URL: ${info.url}`);
+
+  lines.push("", `Providers (${info.providers.length}):`, `  ${info.providers.join(", ")}`);
+
+  if (info.webSocketPaths.length > 0) {
+    lines.push("", `WebSocket paths: ${info.webSocketPaths.join(", ")}`);
+  }
+
+  lines.push("", `Installed packages (${info.packages.length}):`);
+  for (const pkg of info.packages) {
+    // Maturity is only worth the reader's attention when it is not `stable` —
+    // everything else is the promise they already assume.
+    const caveat = pkg.maturity && pkg.maturity !== "stable" ? `  [${pkg.maturity}]` : "";
+    lines.push(`  ${pkg.name}@${pkg.version}${caveat}`);
+  }
+
+  return lines.join("\n");
+}