@zerotal/arch 1.7.0

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * `@zerotal/arch` — the agent surface.
+ *
+ * A coding agent working in a Zerotal app should not have to recall an API, or
+ * guess a route name, or say "looks fine to me". The framework already produces
+ * the answers mechanically: `api-surface.md` records every export's exact
+ * signature, `runDoctor()` returns structured findings with a fix beside each,
+ * the router knows its routes and the ORM knows its columns. This package hands
+ * all of it over as MCP tools.
+ *
+ * Install it into a project with `bun zt arch:install`. The server itself is a
+ * bin — `node_modules/@zerotal/arch/src/bin/mcp.ts` — and deliberately never
+ * boots the application; see that file for the reasoning.
+ */
+
+// The provider, which registers `arch:install`, `arch:update` and `arch:probe`.
+export { ArchProvider } from "./provider/ArchProvider.ts";
+
+// Config factory + its shape.
+export { ArchConfig } from "./config.ts";
+export type { ArchConfigShape } from "./config.ts";
+
+// Typed error vocabulary.
+export * from "./errors.ts";
+
+// The tools, and the context they are built from. Exported so a project can
+// serve a subset, or add its own alongside them.
+export { archTools, vendoredDocsDir } from "./tools/index.ts";
+export type { ToolContext } from "./tools/index.ts";
+export { findApp, spawnProbe } from "./tools/_probe.ts";
+export type { ProbeResult, ProbeRunner, SpawnProbeOptions } from "./tools/_probe.ts";
+
+// The in-app reads, for anyone wanting them without the subprocess.
+export { PROBE_TOPICS, isProbeTopic, probe } from "./probe/topics.ts";
+export type {
+  AppInfo,
+  DoctorFinding,
+  DoctorReport,
+  InstalledPackage,
+  ProbeTopic,
+  RouteEntry,
+  RouteReport,
+  SchemaColumn,
+  SchemaModel,
+  SchemaReport,
+} from "./probe/topics.ts";
+
+// The install writers, so a project can generate the same files its own way.
+export { detectAgents } from "./install/detect.ts";
+export type { Detected, McpTarget } from "./install/detect.ts";
+export { applyMcpConfig, serverEntry, SERVER_ENTRY_PATH } from "./install/mcpConfig.ts";
+export type { ConfigOutcome } from "./install/mcpConfig.ts";
+export { applyBlock, fence, BLOCK_END, BLOCK_START } from "./install/markers.ts";
+export type { BlockOutcome } from "./install/markers.ts";
+export { agentsPreamble, buildGuidelines, claudeShim } from "./install/guidelines.ts";
+export type { GuidelineOptions } from "./install/guidelines.ts";

package/src/install/ArchInstallCommand.ts

@@ -0,0 +1,189 @@
+/**
+ * `bun zt arch:install` — register the MCP server and write the agent
+ * instructions. Also registered as `arch:update`, because re-running it *is* the
+ * update: every write is a merge into a fenced region, so the second run and the
+ * fiftieth do the same thing.
+ *
+ * That idempotence is the contract, not a nicety. This command runs again on
+ * every framework upgrade, against files a developer is invited to edit. A run
+ * that clobbered a hand-written paragraph would be discovered once and never
+ * trusted again — so anything it cannot merge cleanly it reports and leaves
+ * alone.
+ */
+import { dirname, join } from "node:path";
+import { Command } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { ArchConfig } from "../config.ts";
+import type { ArchConfigShape } from "../config.ts";
+import { NoProjectRootError } from "../errors.ts";
+import { installedPackages } from "../probe/topics.ts";
+import { detectAgents } from "./detect.ts";
+import { agentsPreamble, buildGuidelines, claudeShim } from "./guidelines.ts";
+import { applyBlock } from "./markers.ts";
+import { applyMcpConfig } from "./mcpConfig.ts";
+
+/** One file the run touched, and what happened to it. */
+interface Change {
+  path: string;
+  status: "created" | "updated" | "unchanged" | "conflict";
+  detail?: string;
+  text?: string;
+}
+
+export class ArchInstallCommand extends Command {
+  static override commandName = "arch:install";
+  static override description =
+    "Register the Zerotal MCP server and write agent instructions (alias: arch:update)";
+  static override needsApp = true;
+  static override args = [];
+  static override flags = [
+    {
+      name: "dry",
+      type: "boolean" as const,
+      description: "Show what would change without writing anything",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const dry = this.flags["dry"] === true;
+    const root = await findProjectRoot(process.cwd());
+    const config = this._config();
+
+    const detected = await detectAgents(root);
+    const packages = (await installedPackages(root)).map((pkg) => pkg.name);
+
+    const changes: Change[] = [
+      ...(config.mcpConfig ? await this._mcpChanges(root, config, detected.targets) : []),
+      ...(config.agentsFile ? [await this._agentsChange(root, config, packages)] : []),
+      ...(config.claudeFile ? [await this._claudeChange(root)] : []),
+    ];
+
+    this.section(dry ? "arch:install — dry run" : "arch:install");
+    if (detected.agents.length > 0) {
+      this.dim(`  detected: ${detected.agents.join(", ")}`);
+    } else {
+      this.dim("  no agent tooling detected — writing the portable defaults");
+    }
+    this.newLine();
+
+    let wrote = 0;
+    let conflicts = 0;
+
+    for (const change of changes) {
+      if (change.status === "conflict") {
+        conflicts++;
+        this.error(`  ✗ ${change.path} — ${change.detail ?? "left untouched"}`);
+        continue;
+      }
+      if (change.status === "unchanged") {
+        this.dim(`  · ${change.path} — already up to date`);
+        continue;
+      }
+      if (!dry && change.text !== undefined) {
+        await Bun.write(join(root, change.path), change.text);
+      }
+      wrote++;
+      this.info(
+        `  ${dry ? "would " : ""}${change.status === "created" ? "create" : "update"} ${change.path}`,
+      );
+    }
+
+    this.newLine();
+    if (conflicts > 0) {
+      this.warn(
+        `${conflicts} file(s) could not be merged and were left as they are. ` +
+          `Fix the markers or the JSON and run this again.`,
+      );
+    }
+    if (dry) {
+      this.line(`${wrote} file(s) would change. Run without --dry to apply.`);
+      return;
+    }
+    if (wrote === 0) {
+      this.line("Everything is already in place.");
+      return;
+    }
+    this.line("Restart your agent so it picks up the MCP server.");
+  }
+
+  /** The `arch` config namespace, or the defaults when the app declares none. */
+  private _config(): ArchConfigShape {
+    const app = this.app as Application | undefined;
+    try {
+      const store = app?.container.makeSync("config") as
+        { get(key: string, fallback?: unknown): unknown } | undefined;
+      const declared = store?.get("arch", {});
+      return ArchConfig((declared ?? {}) as Partial<ArchConfigShape>);
+    } catch {
+      return ArchConfig();
+    }
+  }
+
+  private async _mcpChanges(
+    root: string,
+    config: ArchConfigShape,
+    detected: Awaited<ReturnType<typeof detectAgents>>["targets"],
+  ): Promise<Change[]> {
+    // The configured path always gets written; the detected ones are extra.
+    const targets = detected.some((target) => target.path === config.mcpConfigPath)
+      ? detected
+      : [
+          { path: config.mcpConfigPath, key: "mcpServers" as const, client: "MCP client" },
+          ...detected,
+        ];
+
+    const changes: Change[] = [];
+    for (const target of targets) {
+      const outcome = applyMcpConfig(
+        await readIfPresent(join(root, target.path)),
+        config.serverName,
+        target,
+      );
+      changes.push(
+        outcome.status === "conflict"
+          ? { path: target.path, status: "conflict", detail: outcome.reason }
+          : { path: target.path, status: outcome.status, text: outcome.text },
+      );
+    }
+    return changes;
+  }
+
+  private async _agentsChange(
+    root: string,
+    config: ArchConfigShape,
+    packages: string[],
+  ): Promise<Change> {
+    const outcome = applyBlock(
+      await readIfPresent(join(root, "AGENTS.md")),
+      buildGuidelines({ packages, serverName: config.serverName }),
+      agentsPreamble(),
+    );
+    return outcome.status === "conflict"
+      ? { path: "AGENTS.md", status: "conflict", detail: outcome.reason }
+      : { path: "AGENTS.md", status: outcome.status, text: outcome.text };
+  }
+
+  private async _claudeChange(root: string): Promise<Change> {
+    const outcome = applyBlock(await readIfPresent(join(root, "CLAUDE.md")), claudeShim());
+    return outcome.status === "conflict"
+      ? { path: "CLAUDE.md", status: "conflict", detail: outcome.reason }
+      : { path: "CLAUDE.md", status: outcome.status, text: outcome.text };
+  }
+}
+
+async function readIfPresent(path: string): Promise<string | undefined> {
+  const file = Bun.file(path);
+  return (await file.exists()) ? file.text() : undefined;
+}
+
+/** The nearest ancestor with a `package.json`. */
+async function findProjectRoot(start: string): Promise<string> {
+  let dir = start;
+  for (;;) {
+    if (await Bun.file(join(dir, "package.json")).exists()) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) throw new NoProjectRootError(start);
+    dir = parent;
+  }
+}

package/src/install/detect.ts

@@ -0,0 +1,98 @@
+/**
+ * Which coding agents this project is already set up for.
+ *
+ * Detection is by the directories and files an agent leaves behind, not by
+ * asking. A project with `.cursor/` gets a Cursor MCP config; one without does
+ * not get a directory it never wanted. The one exception is `.mcp.json` at the
+ * root, which is written unconditionally: it is the widely-read project-scoped
+ * location, and a project with no agent configured yet is exactly the project
+ * about to configure one.
+ */
+import { join } from "node:path";
+
+/** Where an MCP client keeps its server list, and under which key. */
+export interface McpTarget {
+  /** Path relative to the project root. */
+  path: string;
+  /**
+   * The object servers are listed under.
+   *
+   * Most clients use `mcpServers`; VS Code's own file uses `servers`. Writing
+   * the wrong one produces a config that parses and does nothing.
+   */
+  key: "mcpServers" | "servers";
+  /** What reads this file, for the report. */
+  client: string;
+}
+
+export interface Detected {
+  /** Agent tooling found in the project, by name. */
+  agents: string[];
+  /** MCP config files worth writing here. */
+  targets: McpTarget[];
+}
+
+interface Probe {
+  agent: string;
+  /** A path whose existence means this agent is in use. */
+  marker: string;
+  target?: McpTarget;
+}
+
+const PROBES: Probe[] = [
+  {
+    agent: "Claude Code",
+    marker: ".claude",
+    target: { path: ".mcp.json", key: "mcpServers", client: "Claude Code" },
+  },
+  {
+    agent: "Cursor",
+    marker: ".cursor",
+    target: { path: ".cursor/mcp.json", key: "mcpServers", client: "Cursor" },
+  },
+  {
+    agent: "VS Code / Copilot",
+    marker: ".vscode",
+    target: { path: ".vscode/mcp.json", key: "servers", client: "VS Code" },
+  },
+  { agent: "GitHub Copilot", marker: ".github/copilot-instructions.md" },
+  { agent: "Gemini CLI", marker: ".gemini" },
+  { agent: "Codex", marker: ".codex" },
+  { agent: "Windsurf", marker: ".windsurf" },
+];
+
+/** The config every project gets, whatever it already has. */
+const DEFAULT_TARGET: McpTarget = {
+  path: ".mcp.json",
+  key: "mcpServers",
+  client: "Claude Code and other clients reading .mcp.json",
+};
+
+export async function detectAgents(root: string): Promise<Detected> {
+  const agents: string[] = [];
+  const targets = new Map<string, McpTarget>([[DEFAULT_TARGET.path, DEFAULT_TARGET]]);
+
+  for (const probe of PROBES) {
+    if (!(await exists(join(root, probe.marker)))) continue;
+    agents.push(probe.agent);
+    if (probe.target) targets.set(probe.target.path, probe.target);
+  }
+
+  return { agents, targets: [...targets.values()] };
+}
+
+/**
+ * Whether a path exists, directory or file.
+ *
+ * `Bun.file(dir).exists()` answers `false` for a directory, so the markers here
+ * — most of which are directories — need the stat.
+ */
+async function exists(path: string): Promise<boolean> {
+  try {
+    const { stat } = await import("node:fs/promises");
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/install/guidelines.ts

@@ -0,0 +1,290 @@
+/**
+ * The instructions written into `AGENTS.md`.
+ *
+ * Composed from what the project actually has: an app without `@zerotal/admin`
+ * never reads a line about admin resources. Every prompt this file lands in pays
+ * for its whole length, so each block earns its place or is not emitted.
+ *
+ * The content deliberately points rather than teaches. There is a `search_docs`
+ * tool and an `api_surface` tool three lines above; a paraphrase of the routing
+ * guide here would be a second copy to drift, and a worse one — the pages it
+ * would summarise are the ones those tools return in full.
+ */
+
+/** A block contributed by one installed package. */
+interface PackageBlock {
+  /** The package that triggers it. */
+  pkg: string;
+  lines: string[];
+}
+
+/**
+ * Per-package guidance, at the level of "this exists, here is what owns it".
+ *
+ * Kept to a few lines each on purpose: the point is to stop an agent inventing
+ * an API when the framework already has one, not to replace the documentation
+ * it can now search.
+ */
+const PACKAGE_BLOCKS: PackageBlock[] = [
+  {
+    pkg: "@zerotal/orm",
+    lines: [
+      "**Data.** Models are Active Record classes in `app/models/`, declared with `@table` and " +
+        "`@column` decorators; `DB` from `@zerotal/orm` is the query builder. Migrations live in " +
+        "`database/migrations/` — generate with `bun zt make:migration`, never hand-edit an " +
+        "applied one. Call `schema` before writing a query or a factory.",
+    ],
+  },
+  {
+    pkg: "@zerotal/auth",
+    lines: [
+      "**Auth.** `Auth` from `@zerotal/auth` for the current user; policies go in `app/policies/` " +
+        "and are discovered automatically. Do not hand-roll password hashing or session handling.",
+    ],
+  },
+  {
+    pkg: "@zerotal/validator",
+    lines: [
+      "**Validation.** `FormRequest` subclasses in `app/requests/`, or `validate()` inline. " +
+        "Rules are built with `RuleBuilder`, so a typo is a compile error rather than a runtime one.",
+    ],
+  },
+  {
+    pkg: "@zerotal/flow",
+    lines: [
+      "**Flow components.** Server-rendered interactive components: a class with state fields and " +
+        "actions, rendered as JSX. Every component is an island and is fully interactive — there " +
+        "is no separate hydration step to write. `bun zt make:flow` scaffolds one.",
+    ],
+  },
+  {
+    pkg: "@zerotal/flow-ui",
+    lines: [
+      "**UI kit.** `@zerotal/flow-ui` ships the component set. Check it before writing a button, " +
+        "modal, table or form field from scratch.",
+    ],
+  },
+  {
+    pkg: "@zerotal/inertia",
+    lines: [
+      "**Inertia.** Pages are React/Vue components under `resources/`; controllers return " +
+        "`Inertia.render(...)`. Props are serialised — do not pass class instances.",
+    ],
+  },
+  {
+    pkg: "@zerotal/admin",
+    lines: [
+      "**Admin.** Resources in `app/admin/` describe tables, forms and infolists declaratively. " +
+        "`bun zt make:admin-resource` scaffolds one; prefer extending a resource over writing a " +
+        "bespoke page.",
+    ],
+  },
+  {
+    pkg: "@zerotal/queue",
+    lines: [
+      "**Background work.** Jobs in `app/jobs/`, dispatched with `.dispatch()`. Anything slower " +
+        "than a request belongs in one. `bun zt queue:work` runs the worker; `bun zt dev` runs it " +
+        "for you.",
+    ],
+  },
+  {
+    pkg: "@zerotal/cache",
+    lines: ["**Cache.** `Cache` from `@zerotal/cache`. Never cache a request-scoped value."],
+  },
+  {
+    pkg: "@zerotal/scheduler",
+    lines: [
+      "**Scheduling.** Schedules in `app/schedules/`, discovered at boot. They need " +
+        "`SchedulerProvider` registered — `doctor` will say so if it is missing.",
+    ],
+  },
+  {
+    pkg: "@zerotal/notifications",
+    lines: [
+      "**Notifications.** Notification classes in `app/notifications/`, one `via()` per channel.",
+    ],
+  },
+  {
+    pkg: "@zerotal/media",
+    lines: ["**Media.** `@zerotal/media` owns uploads, conversions and the media library."],
+  },
+  {
+    pkg: "@zerotal/broadcasting",
+    lines: [
+      "**Realtime.** Channels are declared in the app and authorised server-side. " +
+        "`bun zt make:channel` scaffolds one.",
+    ],
+  },
+  {
+    pkg: "@zerotal/i18n",
+    lines: ["**Translations.** `@zerotal/i18n`; message files live under `resources/lang/`."],
+  },
+  {
+    pkg: "@zerotal/tenancy",
+    lines: [
+      "**Multi-tenancy.** Tenant resolution is middleware-driven. Anything tenant-scoped must go " +
+        "through it rather than reading an id from the request.",
+    ],
+  },
+  {
+    pkg: "@zerotal/testing",
+    lines: [
+      "**Tests.** `createTestApp()` from `@zerotal/testing` boots a real app; factories and fakes " +
+        "come from the same package. Tests run on `bun test` via `bun zt test`.",
+    ],
+  },
+];
+
+export interface GuidelineOptions {
+  /** Installed `@zerotal/*` package names, as reported by `app_info`. */
+  packages: string[];
+  /** The key the MCP server is registered under, so the text names it correctly. */
+  serverName: string;
+}
+
+/**
+ * The preamble written above the managed block when the file is created.
+ *
+ * Once written it is never touched again — it exists to tell whoever opens the
+ * file that the fenced part is generated and the rest is theirs.
+ */
+export function agentsPreamble(): string {
+  return [
+    "# Agent instructions",
+    "",
+    "Guidance for coding agents working in this repository.",
+    "",
+    "Everything between the `zerotal:arch` markers below is generated by",
+    "`bun zt arch:update` and will be replaced on the next framework upgrade.",
+    "Write your own project-specific instructions outside that block — they are",
+    "preserved.",
+  ].join("\n");
+}
+
+/** Build the managed block for `AGENTS.md`. */
+export function buildGuidelines(options: GuidelineOptions): string {
+  const installed = new Set(options.packages);
+  const sections: string[] = [
+    "## Zerotal",
+    "",
+    "This is a Zerotal app: a Bun-native, full-stack TypeScript framework. Bun executes",
+    "`.ts` directly — there is no build step, and what you write is what runs.",
+    "",
+    toolSection(options.serverName),
+    "",
+    conventionSection(),
+    "",
+    commandSection(),
+  ];
+
+  const blocks = PACKAGE_BLOCKS.filter((block) => installed.has(block.pkg));
+  if (blocks.length > 0) {
+    sections.push(
+      "",
+      "### What this app has",
+      "",
+      ...blocks.flatMap((block) => [...block.lines, ""]),
+    );
+  }
+
+  sections.push(rulesSection());
+
+  return sections
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function toolSection(serverName: string): string {
+  return [
+    `### Use the \`${serverName}\` MCP tools`,
+    "",
+    "This project exposes the framework's machine-readable truth as MCP tools. Prefer them",
+    "over recalling an API from memory — they describe the versions installed here.",
+    "",
+    "- `app_info` — versions, providers and package maturity. Worth one call at the start.",
+    "- `api_surface` — the exact signature of every export in a package.",
+    "- `search_docs` — the framework documentation for this installed version.",
+    "- `routes` — the routes actually registered, with their names.",
+    "- `schema` — what the models declare: tables, columns, indexes.",
+    "- `logs` / `last_error` — what the app actually did.",
+    "- `baselines` — the quality ratchets and the commands that check them.",
+    "- `doctor` — run it before calling any task done.",
+  ].join("\n");
+}
+
+function conventionSection(): string {
+  return [
+    "### Conventions",
+    "",
+    "Classes are discovered by directory. Put a file in the right place and it registers",
+    "itself; no manifest to update.",
+    "",
+    "```text",
+    "app/controllers/   app/models/      app/middleware/   app/policies/",
+    "app/jobs/          app/events/      app/listeners/    app/observers/",
+    "app/commands/      app/schedules/   app/requests/     app/notifications/",
+    "routes/            config/          database/migrations/   tests/",
+    "```",
+    "",
+    "Imports follow one rule: the kernel comes from `zerotal` (and `zerotal/routes`,",
+    "`zerotal/http`, …), everything else from its own package.",
+    "",
+    "```ts",
+    'import type { HttpContext } from "zerotal";',
+    'import { route } from "zerotal/routes";',
+    'import { DB } from "@zerotal/orm";',
+    "```",
+  ].join("\n");
+}
+
+function commandSection(): string {
+  return [
+    "### Commands",
+    "",
+    "```bash",
+    "bun zt dev             # server plus every companion process, in one deck",
+    "bun zt list            # every command this app has, including package ones",
+    "bun zt make:<thing>    # scaffold — prefer it over writing boilerplate by hand",
+    "bun zt route:list      # registered routes",
+    "bun zt route:types     # regenerate typed route names after changing routes",
+    "bun zt test            # tests, with the app booted",
+    "bun zt doctor          # health checks, with a fix beside each finding",
+    "```",
+  ].join("\n");
+}
+
+function rulesSection(): string {
+  return [
+    "",
+    "### Rules",
+    "",
+    "1. **The types are the guidance.** If a call type-checks it is almost certainly the",
+    "   intended one. Read the signature with `api_surface` rather than guessing and",
+    "   correcting.",
+    "2. **Scaffold before you write.** `bun zt make:*` produces the shape the framework",
+    "   expects, including the parts that are easy to forget.",
+    "3. **Regenerate route types** with `bun zt route:types` whenever routes change —",
+    "   `route()` is checked against the generated names.",
+    "4. **Finish with `doctor`.** A task with a failing check is not done. Warnings are",
+    "   worth reading; failures are work.",
+    "5. **Do not add dependencies** without being asked. The framework covers most of",
+    "   what an app needs, and `search_docs` will say where.",
+  ].join("\n");
+}
+
+/**
+ * The `CLAUDE.md` shim.
+ *
+ * An import line rather than a copy: Claude Code does not read `AGENTS.md`
+ * natively, and two files of guidance that start identical do not stay that way.
+ */
+export function claudeShim(): string {
+  return [
+    "@AGENTS.md",
+    "",
+    "The instructions for this project live in `AGENTS.md` — the cross-tool standard, read",
+    "natively by most other agents. The line above imports it. Add anything Claude-specific",
+    "below, outside the generated block.",
+  ].join("\n");
+}