@zerotal/arch 1.7.0

package/src/tools/baselines.ts

@@ -0,0 +1,210 @@
+/**
+ * `baselines` — the numbers a change is not allowed to make worse, and the
+ * commands that check them.
+ *
+ * Zerotal's repo keeps four ratchets — lint, casts, test typecheck, docs
+ * coverage — each a committed JSON file recording today's debt. The rule is that
+ * they only go down. That is a rule an agent can follow only if it can see the
+ * numbers, which is what this returns.
+ *
+ * It reads and does not run. Executing a project's own scripts would make the
+ * one tool in this set that can cause an effect, for a result the caller can
+ * already get by running the command itself — so the commands are reported and
+ * running them is left to the caller.
+ *
+ * A project with no baselines is not an error: most apps keep none. In that case
+ * this reports the verification commands the project *does* have, which is the
+ * question behind the question.
+ */
+import { join } from "node:path";
+import type { ArchTool, ToolOutcome } from "../mcp/types.ts";
+import type { ToolContext } from "./context.ts";
+
+/** The four ratchets, with the command that checks each. */
+const RATCHETS = [
+  { name: "lint", file: "lint-baseline.json", command: "bun run lint:ci" },
+  { name: "casts", file: "cast-baseline.json", command: "bun run cast:check" },
+  {
+    name: "typecheck:tests",
+    file: "typecheck-tests-baseline.json",
+    command: "bun run typecheck:tests",
+  },
+  {
+    name: "docs-coverage",
+    file: "docs-coverage-baseline.json",
+    command: "bun run docs:coverage",
+  },
+] as const;
+
+/** package.json scripts worth reporting as verification commands. */
+const GATE_SCRIPTS = [
+  "test",
+  "typecheck",
+  "typecheck:tests",
+  "lint",
+  "lint:ci",
+  "lint:packages:ci",
+  "format:check",
+  "cast:check",
+  "api:surface:check",
+  "docs:coverage",
+];
+
+export interface BaselineReading {
+  name: string;
+  file: string;
+  command: string;
+  /** The recorded ceiling. */
+  total: number;
+  /** Per-package or per-file detail, when the baseline records it. */
+  breakdown?: Record<string, number>;
+  updatedAt?: string;
+}
+
+/**
+ * The recorded total.
+ *
+ * Three of the four write a `total`; the cast baseline records only its
+ * per-file map, so its total is the sum. Deriving it rather than demanding the
+ * field keeps this working if a fifth ratchet lands in either shape.
+ */
+export function readTotal(document: Record<string, unknown>): number | undefined {
+  const total = document["total"];
+  if (typeof total === "number") return total;
+
+  for (const key of ["files", "packages"]) {
+    const map = document[key];
+    if (typeof map === "object" && map !== null && !Array.isArray(map)) {
+      let sum = 0;
+      for (const value of Object.values(map as Record<string, unknown>)) {
+        if (typeof value === "number") sum += value;
+      }
+      return sum;
+    }
+  }
+  return undefined;
+}
+
+function readBreakdown(document: Record<string, unknown>): Record<string, number> | undefined {
+  const map = document["packages"];
+  if (typeof map !== "object" || map === null || Array.isArray(map)) return undefined;
+  const out: Record<string, number> = {};
+  for (const [key, value] of Object.entries(map as Record<string, unknown>)) {
+    if (typeof value === "number") out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+async function readBaselines(root: string): Promise<BaselineReading[]> {
+  const readings: BaselineReading[] = [];
+
+  for (const ratchet of RATCHETS) {
+    const path = join(root, ratchet.file);
+    if (!(await Bun.file(path).exists())) continue;
+    try {
+      const document = (await Bun.file(path).json()) as Record<string, unknown>;
+      const total = readTotal(document);
+      if (total === undefined) continue;
+      const breakdown = readBreakdown(document);
+      const updatedAt = document["updatedAt"];
+      readings.push({
+        name: ratchet.name,
+        file: ratchet.file,
+        command: ratchet.command,
+        total,
+        ...(breakdown !== undefined ? { breakdown } : {}),
+        ...(typeof updatedAt === "string" ? { updatedAt } : {}),
+      });
+    } catch {
+      /* an unreadable baseline is one row missing, not a failed tool */
+    }
+  }
+
+  return readings;
+}
+
+async function readGateScripts(root: string): Promise<Array<{ name: string; command: string }>> {
+  try {
+    const manifest = (await Bun.file(join(root, "package.json")).json()) as Record<string, unknown>;
+    const scripts = manifest["scripts"];
+    if (typeof scripts !== "object" || scripts === null) return [];
+    const declared = scripts as Record<string, unknown>;
+    return GATE_SCRIPTS.filter((name) => typeof declared[name] === "string").map((name) => ({
+      name,
+      command: `bun run ${name}`,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+export function baselinesTool(ctx: ToolContext): ArchTool {
+  return {
+    name: "baselines",
+    title: "Baselines",
+    description:
+      "The quality ratchets this project records — lint warnings, type casts, test-typecheck " +
+      "errors, documentation gaps — and the command that verifies each. The rule is that these " +
+      "numbers only go down: a change may remove debt freely but must not add to it. Also lists " +
+      "the project's own verification scripts. Read it before a change, and run the commands it " +
+      "names after one.",
+    inputSchema: { type: "object", additionalProperties: false },
+    outputSchema: {
+      type: "object",
+      properties: {
+        baselines: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              file: { type: "string" },
+              command: { type: "string" },
+              total: { type: "number" },
+              breakdown: { type: "object", additionalProperties: { type: "number" } },
+              updatedAt: { type: "string" },
+            },
+            required: ["name", "file", "command", "total"],
+          },
+        },
+        scripts: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: { name: { type: "string" }, command: { type: "string" } },
+            required: ["name", "command"],
+          },
+        },
+      },
+      required: ["baselines", "scripts"],
+    },
+
+    async run(): Promise<ToolOutcome> {
+      const [baselines, scripts] = await Promise.all([
+        readBaselines(ctx.root),
+        readGateScripts(ctx.root),
+      ]);
+      const data = { baselines, scripts };
+
+      const sections: string[] = [];
+
+      if (baselines.length > 0) {
+        const rows = baselines.map(
+          (reading) =>
+            `  ${reading.name.padEnd(18)}${String(reading.total).padStart(6)}   ${reading.command}`,
+        );
+        sections.push(`Ratchets — these numbers may go down, never up:\n\n${rows.join("\n")}`);
+      } else {
+        sections.push("This project records no baselines.");
+      }
+
+      if (scripts.length > 0) {
+        sections.push(
+          `Verification commands available here:\n${scripts.map((s) => `  ${s.command}`).join("\n")}`,
+        );
+      }
+
+      return { text: sections.join("\n\n"), data };
+    },
+  };
+}

package/src/tools/context.ts

@@ -0,0 +1,37 @@
+/**
+ * What every tool is handed: where the project is, where the corpus is, and how
+ * to reach a booted app.
+ *
+ * Passing these in rather than reading them from module scope is what makes a
+ * tool testable — a test points `root` at a fixture directory and injects a
+ * {@link ProbeRunner} that returns a canned report, and no application is ever
+ * booted.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import type { ProbeRunner } from "./_probe.ts";
+
+export interface ToolContext {
+  /** The project being served. Every relative path a tool reads hangs off this. */
+  root: string;
+  /**
+   * The documentation corpus.
+   *
+   * Defaults to the copy vendored inside this package, which is what makes
+   * `search_docs` version-matched: the docs an app searches are the ones that
+   * shipped with the `@zerotal/arch` it installed, not whatever is on main.
+   */
+  docsDir: string;
+  probe: ProbeRunner;
+}
+
+/**
+ * The docs shipped inside this package.
+ *
+ * Resolved from this module's own URL rather than the working directory,
+ * because the working directory is the *app* and the corpus lives in
+ * `node_modules`.
+ */
+export function vendoredDocsDir(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "docs");
+}

package/src/tools/doctor.ts

@@ -0,0 +1,93 @@
+/**
+ * `doctor` — the tool an agent is meant to finish a task with.
+ *
+ * `zt doctor` runs every static check the framework and the app's providers
+ * contribute, and each finding carries the edit or command that resolves it.
+ * That is the whole reason it is worth exposing: "looks fine to me" is not a
+ * result an agent can act on, and this is.
+ *
+ * A run that finds failures is still a *successful* tool call — the findings are
+ * the answer. `isError` is reserved for the case where the doctor could not be
+ * run at all, so an agent can tell "your app has three problems" apart from
+ * "I could not look".
+ */
+import type { ArchTool, ToolOutcome } from "../mcp/types.ts";
+import type { DoctorReport } from "../probe/topics.ts";
+import type { ToolContext } from "./context.ts";
+
+const MARK = { ok: "✓", warn: "!", fail: "✗" } as const;
+
+export function doctorTool(ctx: ToolContext): ArchTool {
+  return {
+    name: "doctor",
+    title: "Doctor",
+    description:
+      "Run every health check against this app and return the findings with the fix for each. " +
+      "Covers the silent misconfigurations — an unregistered provider, a schema with two sources " +
+      "of truth, allowed origins that no browser will match, a missing APP_KEY — plus whatever " +
+      "the installed packages contribute. Run this as the last step of any task that changed " +
+      "the app, and treat a `fail` as work that is not finished.",
+    inputSchema: { type: "object", additionalProperties: false },
+    outputSchema: {
+      type: "object",
+      properties: {
+        healthy: {
+          type: "boolean",
+          description: "True when nothing failed. Warnings do not clear it.",
+        },
+        counts: {
+          type: "object",
+          properties: {
+            ok: { type: "number" },
+            warn: { type: "number" },
+            fail: { type: "number" },
+            total: { type: "number" },
+          },
+          required: ["ok", "warn", "fail", "total"],
+        },
+        findings: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              label: { type: "string" },
+              status: { type: "string", enum: ["ok", "warn", "fail"] },
+              message: { type: "string" },
+              fix: { type: "string" },
+            },
+            required: ["id", "label", "status", "message"],
+          },
+        },
+      },
+      required: ["healthy", "counts", "findings"],
+    },
+
+    async run(_args, signal): Promise<ToolOutcome> {
+      const result = await ctx.probe.run("doctor", signal);
+      if (!result.ok) return { text: result.message, failed: true };
+
+      // The probe runs this package's own `topics.ts`, in the same install, so
+      // the shape is ours by construction.
+      const report = result.data as DoctorReport;
+      return { text: render(report), data: report };
+    },
+  };
+}
+
+function render(report: DoctorReport): string {
+  const lines = report.findings.map((finding) => {
+    const head = `${MARK[finding.status]} ${finding.label} — ${finding.message}`;
+    return finding.fix ? `${head}\n    fix: ${finding.fix}` : head;
+  });
+
+  const { ok, warn, fail, total } = report.counts;
+  const summary = report.healthy
+    ? warn === 0
+      ? `All ${total} checks passed.`
+      : `${warn} warning(s) across ${total} checks; nothing is broken.`
+    : `${fail} FAILING, ${warn} warning(s), ${ok} ok — of ${total} checks. ` +
+      `Address every failure before calling the task done.`;
+
+  return `${lines.join("\n")}\n\n${summary}`;
+}

package/src/tools/index.ts

@@ -0,0 +1,50 @@
+/**
+ * The tool registry.
+ *
+ * Order is the listing order and is deliberate: `tools/list` preserves it, and
+ * it is the first thing a model reads about this server. Cheap orientation
+ * first (`app_info`), then the two that answer "what exactly does this API look
+ * like" (`api_surface`, `search_docs`), then the app's own state, then the
+ * verification tools a task should end with.
+ */
+import type { ArchTool } from "../mcp/types.ts";
+import type { ToolContext } from "./context.ts";
+import { apiSurfaceTool } from "./apiSurface.ts";
+import { appInfoTool } from "./appInfo.ts";
+import { baselinesTool } from "./baselines.ts";
+import { doctorTool } from "./doctor.ts";
+import { lastErrorTool, logsTool } from "./logs.ts";
+import { routesTool } from "./routes.ts";
+import { schemaTool } from "./schema.ts";
+import { searchDocsTool } from "./searchDocs.ts";
+
+/** Every tool the agent surface exposes, in listing order. */
+export function archTools(ctx: ToolContext): ArchTool[] {
+  return [
+    appInfoTool(ctx),
+    apiSurfaceTool(ctx),
+    searchDocsTool(ctx),
+    routesTool(ctx),
+    schemaTool(ctx),
+    logsTool(ctx),
+    lastErrorTool(ctx),
+    baselinesTool(ctx),
+    doctorTool(ctx),
+  ];
+}
+
+export {
+  apiSurfaceTool,
+  appInfoTool,
+  baselinesTool,
+  doctorTool,
+  lastErrorTool,
+  logsTool,
+  routesTool,
+  schemaTool,
+  searchDocsTool,
+};
+export type { ToolContext } from "./context.ts";
+export { vendoredDocsDir } from "./context.ts";
+export { findApp, spawnProbe } from "./_probe.ts";
+export type { ProbeResult, ProbeRunner, SpawnProbeOptions } from "./_probe.ts";

package/src/tools/logs.ts

@@ -0,0 +1,265 @@
+/**
+ * `logs` and `last_error` — the app's own trail.
+ *
+ * Zerotal writes a date-rotated JSON-lines file under `storage/logs` by default,
+ * kept for fourteen days, and it is on whether or not anyone configured it. One
+ * JSON object per line means there is nothing to parse heuristically: no
+ * timestamp regex, no multi-line stack-trace reassembly, no format that changes
+ * when someone edits a log template.
+ *
+ * Both tools read the tail of the newest files rather than the whole directory —
+ * a busy app's day-file can be tens of megabytes, and the interesting entry is
+ * almost always the last one.
+ */
+import type { ArchTool, ToolOutcome } from "../mcp/types.ts";
+import type { ToolContext } from "./context.ts";
+
+const DEFAULT_LOG_DIR = "storage/logs";
+const DEFAULT_LIMIT = 30;
+const MAX_LIMIT = 200;
+/** How many day-files back to look before giving up. */
+const MAX_DAYS = 14;
+/** Bytes read from the end of a day-file. Generous, and bounded. */
+const TAIL_BYTES = 512 * 1024;
+
+const LEVELS = ["debug", "info", "warn", "error", "fatal"] as const;
+type Level = (typeof LEVELS)[number];
+
+export interface LogEntry {
+  level: string;
+  message: string;
+  timestamp: string;
+  channel?: string;
+  scope?: string;
+  context?: unknown;
+}
+
+// ── Reading ───────────────────────────────────────────────────────────────────
+
+/** Day-files newest first, `YYYY-MM-DD.log`. */
+async function dayFiles(dir: string): Promise<string[]> {
+  try {
+    const files = await Array.fromAsync(new Bun.Glob("*.log").scan({ cwd: dir, onlyFiles: true }));
+    return files.sort().reverse().slice(0, MAX_DAYS);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Parse the last `TAIL_BYTES` of a JSON-lines file, oldest first.
+ *
+ * The first line of the window is dropped when the window did not start at the
+ * beginning of the file: slicing by byte offset lands mid-line, and half an
+ * entry is not an entry.
+ */
+export async function readTail(path: string): Promise<LogEntry[]> {
+  const file = Bun.file(path);
+  const size = file.size;
+  const from = Math.max(0, size - TAIL_BYTES);
+  const text = await (from > 0 ? file.slice(from).text() : file.text());
+
+  const lines = text.split("\n");
+  if (from > 0) lines.shift();
+
+  const entries: LogEntry[] = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (typeof parsed !== "object" || parsed === null) continue;
+      const record = parsed as Record<string, unknown>;
+      if (typeof record["message"] !== "string") continue;
+      entries.push({
+        level: typeof record["level"] === "string" ? record["level"] : "info",
+        message: record["message"],
+        timestamp: typeof record["timestamp"] === "string" ? record["timestamp"] : "",
+        ...(typeof record["channel"] === "string" ? { channel: record["channel"] } : {}),
+        ...(typeof record["scope"] === "string" ? { scope: record["scope"] } : {}),
+        ...(record["context"] !== undefined ? { context: record["context"] } : {}),
+      });
+    } catch {
+      /* a truncated or hand-edited line is skipped, not fatal */
+    }
+  }
+  return entries;
+}
+
+/**
+ * Walk day-files newest-first, collecting entries that pass `keep`, until
+ * `limit` of them are found.
+ *
+ * Returned oldest-first, because that is the order a reader follows a story in.
+ */
+async function collect(
+  dir: string,
+  limit: number,
+  keep: (entry: LogEntry) => boolean,
+): Promise<{ entries: LogEntry[]; scanned: number }> {
+  const found: LogEntry[] = [];
+  const files = await dayFiles(dir);
+
+  for (const file of files) {
+    const day = (await readTail(`${dir}/${file}`)).filter(keep);
+    // Newest first across files, so take from the end of each day.
+    found.unshift(...day.slice(Math.max(0, day.length - (limit - found.length))));
+    if (found.length >= limit) break;
+  }
+
+  return { entries: found, scanned: files.length };
+}
+
+function levelFilter(raw: unknown): (entry: LogEntry) => boolean {
+  const requested = typeof raw === "string" ? raw.toLowerCase() : undefined;
+  if (requested === undefined || !(LEVELS as readonly string[]).includes(requested)) {
+    return () => true;
+  }
+  // A level is a floor, not an equality: asking for `warn` and being handed no
+  // errors would be the opposite of useful.
+  const floor = LEVELS.indexOf(requested as Level);
+  return (entry) => {
+    const at = LEVELS.indexOf(entry.level.toLowerCase() as Level);
+    return at === -1 ? true : at >= floor;
+  };
+}
+
+function clampLimit(raw: unknown): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return DEFAULT_LIMIT;
+  return Math.min(MAX_LIMIT, Math.max(1, Math.floor(raw)));
+}
+
+function renderEntry(entry: LogEntry): string {
+  const scope = entry.scope ? ` [${entry.scope}]` : "";
+  const head = `${entry.timestamp} ${entry.level.toUpperCase()}${scope} ${entry.message}`;
+  if (entry.context === undefined) return head;
+  return `${head}\n    ${JSON.stringify(entry.context)}`;
+}
+
+const noTrail = (dir: string): string =>
+  `No log trail at ${dir}. Zerotal writes one by default outside tests — an empty directory ` +
+  `usually means the app has not run yet, or logging.file is set to false in config/logging.ts.`;
+
+// ── Tools ─────────────────────────────────────────────────────────────────────
+
+export function logsTool(ctx: ToolContext): ArchTool {
+  return {
+    name: "logs",
+    title: "Logs",
+    description:
+      "Read this app's recent log entries from its on-disk trail. Each entry carries a level, " +
+      "timestamp, scope and structured context. Pass `level` to set a floor — `warn` returns " +
+      "warnings, errors and fatals. Use it to find out what an app actually did, rather than " +
+      "inferring it from the code.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        level: {
+          type: "string",
+          enum: [...LEVELS],
+          description: "Minimum level to include. Omit for everything.",
+        },
+        contains: {
+          type: "string",
+          description: "Only entries whose message contains this, case-insensitively.",
+        },
+        limit: {
+          type: "number",
+          description: `How many entries. Default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}.`,
+        },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        total: { type: "number" },
+        entries: { type: "array", items: { $ref: "#/$defs/entry" } },
+      },
+      required: ["total", "entries"],
+      $defs: { entry: entrySchema() },
+    },
+
+    async run(args): Promise<ToolOutcome> {
+      const dir = `${ctx.root}/${DEFAULT_LOG_DIR}`;
+      const byLevel = levelFilter(args["level"]);
+      const needle =
+        typeof args["contains"] === "string" ? args["contains"].toLowerCase() : undefined;
+
+      const { entries, scanned } = await collect(
+        dir,
+        clampLimit(args["limit"]),
+        (entry) =>
+          byLevel(entry) && (needle === undefined || entry.message.toLowerCase().includes(needle)),
+      );
+
+      if (scanned === 0) return { text: noTrail(dir), failed: true };
+      if (entries.length === 0) {
+        return {
+          text: `No matching entries in the last ${scanned} day-file(s).`,
+          data: { total: 0, entries: [] },
+        };
+      }
+
+      return {
+        text: entries.map(renderEntry).join("\n"),
+        data: { total: entries.length, entries },
+      };
+    },
+  };
+}
+
+export function lastErrorTool(ctx: ToolContext): ArchTool {
+  return {
+    name: "last_error",
+    title: "Last error",
+    description:
+      "The most recent error or fatal entry in this app's log trail, with its full context. " +
+      "The fastest way to find out why something failed — call it before reading code to guess.",
+    inputSchema: { type: "object", additionalProperties: false },
+    outputSchema: {
+      type: "object",
+      properties: {
+        found: { type: "boolean" },
+        entry: entrySchema(),
+      },
+      required: ["found"],
+    },
+
+    async run(): Promise<ToolOutcome> {
+      const dir = `${ctx.root}/${DEFAULT_LOG_DIR}`;
+      const isError = (entry: LogEntry): boolean => {
+        const level = entry.level.toLowerCase();
+        return level === "error" || level === "fatal";
+      };
+
+      const { entries, scanned } = await collect(dir, 1, isError);
+      if (scanned === 0) return { text: noTrail(dir), failed: true };
+
+      const entry = entries[entries.length - 1];
+      if (!entry) {
+        return {
+          text: `No error has been logged in the last ${scanned} day-file(s).`,
+          data: { found: false },
+        };
+      }
+
+      return { text: renderEntry(entry), data: { found: true, entry } };
+    },
+  };
+}
+
+function entrySchema(): Record<string, unknown> {
+  return {
+    type: "object",
+    properties: {
+      level: { type: "string" },
+      message: { type: "string" },
+      timestamp: { type: "string" },
+      channel: { type: "string" },
+      scope: { type: "string" },
+      context: {},
+    },
+    required: ["level", "message", "timestamp"],
+  };
+}