@zerotal/arch 1.7.4 → 1.8.0

package/src/install/shape.ts

@@ -0,0 +1,177 @@
+/**
+ * What this project is configured to be, as distinct from what it has installed.
+ *
+ * The guidance in `guidelines.ts` was a function of the package list alone, and
+ * a package list cannot answer the questions that actually decide what an agent
+ * should write. The framework's contracts are not uniform: the same mixin needs a
+ * migration in one app and not in another, `route()` is checked against generated
+ * names in one and unchecked in another, and an optional property is written one
+ * way under `exactOptionalPropertyTypes` and another way without it.
+ *
+ * An agent that guesses wrong there does not get a type error. It gets a working
+ * build and a runtime failure — `no such column: email_verified_at`, hundreds of
+ * tests down at once, in an app whose schema is owned by migrations and whose
+ * `AGENTS.md` never said so.
+ *
+ * ## Read from files, not from a booted app
+ *
+ * `arch:install` runs in a project that may not boot — that is often *why*
+ * someone is installing the agent surface. Everything here comes off disk.
+ *
+ * ## What is deliberately not read
+ *
+ * `.env`, and anything else holding credentials. This output is written into a
+ * file that is committed and pasted into prompts; a detector that reads secrets
+ * is one refactor away from emitting them. Where a fact is available from both a
+ * config file and the environment, the config file is the only source used.
+ */
+import { join } from "node:path";
+
+/** How the database schema comes to exist, which decides who must write a column. */
+export type SchemaSource = "migrations" | "models" | "both" | "unknown";
+
+export interface ProjectShape {
+  schemaSource: SchemaSource;
+  /** `types/routes.generated.ts` exists, so `route()` names are checked. */
+  routeTypes: boolean;
+  /** tsconfig flags that change how correct code is written, not just how it is checked. */
+  strict: {
+    exactOptionalPropertyTypes: boolean;
+    noUncheckedIndexedAccess: boolean;
+    strict: boolean;
+  };
+  /** A `tests/` directory with something in it. */
+  hasTests: boolean;
+}
+
+/** Read `root`'s shape. Every probe fails soft: an unknown fact is simply not stated. */
+export async function detectShape(root: string): Promise<ProjectShape> {
+  const [schemaSource, routeTypes, strict, hasTests] = await Promise.all([
+    _schemaSource(root),
+    _exists(join(root, "types", "routes.generated.ts")),
+    _strictness(root),
+    _hasFiles(join(root, "tests")),
+  ]);
+  return { schemaSource, routeTypes, strict, hasTests };
+}
+
+/**
+ * Migrations, models, or both.
+ *
+ * Mirrors `zt doctor`'s `synchronize-vs-migrations` check, which decides the same
+ * question from the same two inputs — but reports it as a *problem* when both are
+ * on. Here both is a legitimate answer worth stating plainly, because an agent
+ * needs to know it is looking at an app where either route might be the intended
+ * one and it should ask rather than assume.
+ */
+async function _schemaSource(root: string): Promise<SchemaSource> {
+  const migrations = await _hasFiles(join(root, "database", "migrations"));
+  const synchronize = await _synchronizeOn(root);
+
+  if (migrations && synchronize) return "both";
+  if (migrations) return "migrations";
+  if (synchronize) return "models";
+  return "unknown";
+}
+
+/**
+ * Whether `database.synchronize` is on.
+ *
+ * Read as text rather than by importing the config, which would need the app's
+ * environment and its whole provider graph. The value is commonly an expression —
+ * `env("APP_ENV") !== "production"` — so a literal `false` is the only confident
+ * "off"; anything else is treated as "may be on", which errs toward telling the
+ * agent the arrangement is ambiguous rather than asserting the wrong half.
+ */
+async function _synchronizeOn(root: string): Promise<boolean> {
+  const source = await _read(join(root, "config", "database.ts"));
+  if (!source) return false;
+  const match = /\bsynchronize\s*:\s*([^,\n}]+)/.exec(source);
+  if (!match) return false;
+  const value = (match[1] ?? "").trim();
+  return value !== "false";
+}
+
+/**
+ * Read the strictness flags through the whole `extends` chain.
+ *
+ * Reading only the project's own `tsconfig.json` gets this wrong for most real
+ * apps, and wrong in the quiet direction: a workspace app that extends a strict
+ * base has none of these flags in its own file, so every one reads as off and the
+ * guidance says nothing. The app the framework itself ships did exactly that —
+ * detected as unstrict while compiling under a base that turns all three on.
+ *
+ * Nearest wins, as tsc resolves it: a flag set in the extending file overrides
+ * the one it inherits, including turning an inherited flag off.
+ */
+async function _strictness(root: string): Promise<ProjectShape["strict"]> {
+  const chain = await _tsconfigChain(join(root, "tsconfig.json"));
+
+  const on = (flag: string): boolean => {
+    for (const source of chain) {
+      const match = new RegExp(`"${flag}"\\s*:\\s*(true|false)`).exec(source);
+      if (match) return match[1] === "true";
+    }
+    return false;
+  };
+
+  // The two that matter here are not implied by `strict` — each has to be asked
+  // for, which is why they are worth reporting separately from it.
+  return {
+    strict: on("strict"),
+    exactOptionalPropertyTypes: on("exactOptionalPropertyTypes"),
+    noUncheckedIndexedAccess: on("noUncheckedIndexedAccess"),
+  };
+}
+
+/** A tsconfig and everything it extends, nearest first. */
+async function _tsconfigChain(path: string, depth = 0): Promise<string[]> {
+  // Bounded rather than cycle-tracked: a chain this long is already pathological,
+  // and the cost of being wrong here is a missing line of guidance.
+  if (depth > 8) return [];
+
+  const source = await _read(path);
+  if (source === undefined) return [];
+
+  const extended = /"extends"\s*:\s*"([^"]+)"/.exec(source)?.[1];
+  if (!extended) return [source];
+
+  // Only a relative path is resolvable from here. A package reference
+  // (`@tsconfig/bun`) lives in node_modules under a layout this does not chase.
+  if (!extended.startsWith(".")) return [source];
+
+  const { dirname, resolve: resolvePath } = await import("node:path");
+  const next = resolvePath(
+    dirname(path),
+    extended.endsWith(".json") ? extended : `${extended}.json`,
+  );
+  return [source, ...(await _tsconfigChain(next, depth + 1))];
+}
+
+async function _read(path: string): Promise<string | undefined> {
+  try {
+    const file = Bun.file(path);
+    return (await file.exists()) ? await file.text() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function _exists(path: string): Promise<boolean> {
+  try {
+    return await Bun.file(path).exists();
+  } catch {
+    return false;
+  }
+}
+
+/** A directory that exists and holds at least one file. */
+async function _hasFiles(dir: string): Promise<boolean> {
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(dir);
+    return entries.some((entry) => !entry.startsWith("."));
+  } catch {
+    return false;
+  }
+}

package/src/install/skills.ts

@@ -0,0 +1,271 @@
+/**
+ * Depth that costs nothing until it is needed.
+ *
+ * `guidelines.ts` opens by saying that every prompt its output lands in pays for
+ * its whole length, and that is why the block there is short and points rather
+ * than teaches. The cost is real, and so is what it buys: an agent gets a map and
+ * no detail, and the detail is where the expensive mistakes live. Knowing that
+ * migrations exist is not the same as knowing that a mixin's column needs one
+ * here and not in the app next door.
+ *
+ * A skill is the other half. It sits on disk with a one-line description, costs
+ * nothing while it is not relevant, and is loaded whole when it is — so the depth
+ * that could never be afforded upfront can be written out properly.
+ *
+ * ## What belongs here rather than in the block
+ *
+ * Anything procedural. The block says what exists and who owns it; a skill says
+ * how to do one thing correctly, including the parts that look optional and are
+ * not. If a line would only ever matter to someone already doing the task, it is
+ * a skill.
+ *
+ * ## What does not belong here at all
+ *
+ * Anything the tools answer better. `api_surface` gives exact signatures for the
+ * installed version and `search_docs` gives the pages; a skill that paraphrases
+ * either is a copy that starts wrong on the next release. These describe
+ * *sequences and traps* — what the documentation is worst at and what costs the
+ * most to learn by hitting it.
+ */
+import type { ProjectShape } from "./shape.ts";
+
+/**
+ * Marks a file as this tool's to rewrite.
+ *
+ * Placed as the first body line, after the frontmatter, because frontmatter has
+ * to open the file. A `SKILL.md` without it is somebody's own and is never
+ * touched — overriding a shipped skill should be as simple as editing it.
+ */
+export const SKILL_MARKER = "<!-- zerotal:arch:generated -->";
+
+export interface Skill {
+  /** Directory name, and the name in the frontmatter. */
+  name: string;
+  /** The one line an agent reads to decide whether to load the rest. */
+  description: string;
+  /** Packages that must be installed for this skill to apply. */
+  requires?: string[];
+  /** Body, given the project's shape. Empty means "not applicable here". */
+  body: (shape: ProjectShape | undefined) => string;
+}
+
+const SCHEMA_SKILL: Skill = {
+  name: "zerotal-schema-changes",
+  description:
+    "Add or change a database column in a Zerotal app — deciding whether a migration is " +
+    "required, writing one that is safe to re-run, and the mixin columns that need one even " +
+    "though nothing declares them.",
+  requires: ["@zerotal/orm"],
+  body: (shape) => {
+    const source = shape?.schemaSource ?? "unknown";
+
+    // Emphasis is written `_like this_`, not `*like this*`. These files land in
+    // somebody's repository and are checked by their formatter, and a generator
+    // whose output fails the project's own format check is one nobody can run in
+    // CI.
+    const owner =
+      source === "migrations"
+        ? "**Migrations own the schema in this app.**"
+        : source === "models"
+          ? "**The models own the schema in this app** (`database.synchronize` is on)."
+          : source === "both"
+            ? "**Both are in play here** — `database.synchronize` is on _and_ migrations exist. " +
+              "Run `doctor` and read the source-of-truth line before you touch anything."
+            : "**Which one owns the schema here is not obvious from the config.** Run `doctor` " +
+              "and read the source-of-truth line first.";
+
+    return `
+# Changing the schema
+
+${owner}
+
+## Decide who owns the schema before writing anything
+
+Two arrangements, and they need different work for the same change:
+
+- **Models own it** (\`database.synchronize\`). The table is built from what the models
+  declare. A \`@column\` is the whole change; there is no migration to write.
+- **Migrations own it.** The table is built from what a migration says. A \`@column\` alone
+  changes nothing on disk, and every query touching it fails at runtime.
+
+\`bun zt doctor\` reports which. Ask it rather than guessing — the failure mode for guessing
+wrong is a clean type-check and a runtime error under load.
+
+## The columns nothing declares
+
+Some mixins register a column imperatively rather than with \`@column\` — \`EmailVerification\`
+adds \`email_verified_at\`, \`Authenticatable\` adds \`remember_token\`. A boot-time concern
+adds those to their table **if the table already exists**.
+
+It never creates a table, and it never revisits one. So where migrations own the schema, a
+\`create users\` migration that does not mention \`email_verified_at\` produces a table
+without it, permanently:
+
+\`\`\`
+SQLiteError: no such column: email_verified_at
+\`\`\`
+
+Composing such a mixin in a migrations-owned app means writing the migration too.
+
+## Write the migration so it can meet a database that already has the column
+
+The concern above may already have added it — on any database that has booted the app since
+the mixin was composed. An unguarded \`ALTER TABLE\` then fails with \`duplicate column name\`,
+during the release's \`migrate\` step:
+
+\`\`\`ts
+import { Schema } from "@zerotal/orm";
+
+export default class extends Migration {
+  async up(): Promise<void> {
+    if (!(await Schema.hasColumn("users", "email_verified_at"))) {
+      await Schema.table("users", (table) => {
+        table.dateTime("email_verified_at").nullable();
+      });
+    }
+  }
+}
+\`\`\`
+
+## Sequence
+
+1. \`bun zt doctor\` — who owns the schema.
+2. \`bun zt make:migration\` if migrations do. Never hand-edit one that has run: the runner
+   records it as applied and will not run it again, so the edit reaches no database that
+   already migrated.
+3. Call the \`schema\` tool afterwards to confirm the column is really there. It reads the
+   database, not the models, which is the difference that matters here.
+4. \`bun zt test\`.
+`.trim();
+  },
+};
+
+const RELEASE_SKILL: Skill = {
+  name: "zerotal-releases",
+  description:
+    "Ship a Zerotal app — ordering the release steps, replacing built assets rather than " +
+    "merging into them, and the proxy and shell settings that fail quietly in production.",
+  body: () =>
+    `
+# Shipping a release
+
+## Name your own steps
+
+\`deploy:<env>\` runs the steps named in \`config/deploy.ts\`, defaulting to build-and-migrate.
+A preflight command of your own runs only if you name it, and nothing prompts you to:
+
+\`\`\`ts
+// config/deploy.ts
+export default {
+  targets: {
+    production: {
+      url: "https://example.com",
+      steps: ["release:check", "assets:build", "inertia:build", "migrate"],
+    },
+  },
+};
+\`\`\`
+
+Put the check first. A step that fails stops the release, and a check that runs after the
+migration has missed its moment.
+
+\`deploy:<env>\` runs **where the app runs**, with that environment's variables. It does not
+reach another machine.
+
+## Replace the asset directory, do not merge into it
+
+Each build emits a fresh set of content-hashed chunks and cleans up the set it replaced. It
+can only clean a directory it is run in. A release unpacked over the top of the running one
+— \`tar -xzf\` into the app directory, \`rsync\` without \`--delete\` — merges: files in the
+archive are written, files not in it are left exactly where they were. Nothing on that
+machine ever runs a build, so last release's bundles stay, and they stay **publicly
+fetchable at their hashed URLs**. Copy you withdrew is still readable by anyone with the
+link.
+
+\`\`\`bash
+rm -rf "$APP_DIR/public/assets"    # before extracting
+tar -xzf release.tgz -C "$APP_DIR"
+
+# or
+rsync -a --delete public/assets/ "$HOST:$APP_DIR/public/assets/"
+\`\`\`
+
+Clearing takes the running release's bundles away, so do it close to the swap, or stage into
+a new directory and move it into place.
+
+\`--clean\` on \`assets:build\` / \`inertia:build\` removes anything in the output directory the
+build did not write. It is for output some other naming produced; it does not help a
+directory nothing runs in, and it refuses \`public/\` itself.
+
+## Rate limiting counts the proxy, not the visitor
+
+Behind a proxy every request arrives from the same address, so one bucket is shared by
+everybody and a single client can lock the site out. Say how many proxies are in front:
+
+\`\`\`ts
+ThrottleMiddleware.with({ maxAttempts: 60, trustedProxies: 1 });
+\`\`\`
+
+It defaults to zero because \`X-Forwarded-For\` is client-written until something trusted
+overwrites it. Count the proxies you actually run — too many reads an entry the client
+supplied.
+
+## A pipe hides the exit status
+
+\`\`\`bash
+bun test 2>&1 | tail -3     # the status is tail's. Always 0, however the suite went.
+\`\`\`
+
+A deploy script gated that way prints \`1 fail\` and carries on to upload and restart. Use
+\`set -o pipefail\`, or capture the status. \`set -e\` alone does not cover it — the pipeline
+succeeded, as far as the shell is concerned.
+`.trim(),
+};
+
+/** Everything that could be installed, before the project narrows it. */
+export const SKILLS: Skill[] = [SCHEMA_SKILL, RELEASE_SKILL];
+
+/** The skills that apply to a project with these packages and this shape. */
+export function selectSkills(
+  packages: readonly string[],
+  shape: ProjectShape | undefined,
+  all: readonly Skill[] = SKILLS,
+): Skill[] {
+  const installed = new Set(packages);
+  return all.filter(
+    (skill) =>
+      (skill.requires ?? []).every((pkg) => installed.has(pkg)) &&
+      skill.body(shape).trim().length > 0,
+  );
+}
+
+/** One `SKILL.md`: frontmatter, the marker, then the body. */
+export function renderSkill(skill: Skill, shape: ProjectShape | undefined): string {
+  return [
+    "---",
+    `name: ${skill.name}`,
+    // Quoted: descriptions contain commas and colons, which unquoted YAML reads
+    // as structure.
+    `description: ${JSON.stringify(skill.description)}`,
+    "---",
+    "",
+    SKILL_MARKER,
+    "",
+    skill.body(shape),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Where a skill directory goes.
+ *
+ * `.agents/skills` is the cross-client path; `.claude/skills` is read by Claude
+ * Code, and some clients scan it too. Written to both when that agent is present,
+ * because a skill in the wrong directory is not a degraded skill — it is an
+ * inert file that looks installed.
+ */
+export function skillPaths(name: string, agents: readonly string[]): string[] {
+  const paths = [`.agents/skills/${name}/SKILL.md`];
+  if (agents.includes("Claude Code")) paths.push(`.claude/skills/${name}/SKILL.md`);
+  return paths;
+}

package/src/provider/ArchProvider.ts

@@ -1,5 +1,6 @@
 import { ServiceProvider } from "@zerotal/core";
 import type { AppEnvironment, DoctorCheck } from "@zerotal/core";
+import type { ProjectShape } from "../install/shape.ts";
 import { SERVER_ENTRY_PATH } from "../install/mcpConfig.ts";
 
 /**
@@ -96,6 +97,153 @@ export class ArchProvider extends ServiceProvider {
           }
         },
       },
+      {
+        id: "arch-agents-current",
+        label: "Agent instructions",
+        run: async () => agentsFileCheck(process.cwd()),
+      },
     ];
   }
 }
+
+/**
+ * Is the generated block still true?
+ *
+ * It was a description of the framework, which changed about as often as the
+ * framework did. It is now also a description of *this project* — which packages
+ * are installed, who owns the schema, which strictness flags are on — and every
+ * one of those moves without anyone thinking about `AGENTS.md`. Add a migration
+ * directory, turn `synchronize` off, install a package, upgrade the framework:
+ * the file still reads as current and is quietly describing the app you had.
+ *
+ * That is worse than having no file. Guidance nobody wrote is obviously absent;
+ * guidance that is confidently out of date gets followed.
+ *
+ * A warning rather than a failure: a stale instruction file misleads a person or
+ * an agent, and does not stop the application working. `doctor` earns the right
+ * to gate a deploy by failing only for things that would break one.
+ *
+ * Takes its root rather than reading `process.cwd()`, so it is testable without
+ * moving the process into a fixture.
+ *
+ * @internal
+ */
+export async function agentsFileCheck(
+  root: string,
+): Promise<{ status: "ok" | "warn"; message: string; fix?: string }> {
+  const file = Bun.file(`${root}/AGENTS.md`);
+  if (!(await file.exists())) {
+    return {
+      status: "warn",
+      message:
+        "No AGENTS.md, so an agent working here has no instructions and none of the " +
+        "project-specific facts the MCP tools cannot infer.",
+      fix: "bun zt arch:install",
+    };
+  }
+
+  const [{ buildGuidelines }, { detectShape }, { installedPackages }, markers] = await Promise.all([
+    import("../install/guidelines.ts"),
+    import("../install/shape.ts"),
+    import("../probe/topics.ts"),
+    import("../install/markers.ts"),
+  ]);
+
+  const current = _blockOf(await file.text(), markers.BLOCK_START, markers.BLOCK_END);
+  if (current === undefined) {
+    return {
+      status: "warn",
+      message:
+        "AGENTS.md has no generated block, so nothing here describes the framework or how " +
+        "this app is set up.",
+      fix: "bun zt arch:install",
+    };
+  }
+
+  const packages = (await installedPackages(root)).map((pkg) => pkg.name);
+  const shape = await detectShape(root);
+  const expected = buildGuidelines({
+    packages,
+    serverName: await _serverName(root),
+    shape,
+  });
+
+  if (current.trim() !== expected.trim()) {
+    return {
+      status: "warn",
+      message:
+        "AGENTS.md describes a different project than this one — its packages, its setup or " +
+        "its framework version have moved since it was written.",
+      fix: "bun zt arch:update",
+    };
+  }
+
+  // Skills rot the same way and are easier to miss: nothing reads them until an
+  // agent decides one is relevant, and by then it is being followed.
+  const stale = await _staleSkills(root, packages, shape);
+  if (stale.length > 0) {
+    return {
+      status: "warn",
+      message: `AGENTS.md is current, but ${stale.length} skill file(s) are not: ${stale.join(", ")}.`,
+      fix: "bun zt arch:update",
+    };
+  }
+
+  return { status: "ok", message: "AGENTS.md and skills match this project" };
+}
+
+/** Skill files that are missing, or generated and no longer what they would be. */
+async function _staleSkills(
+  root: string,
+  packages: string[],
+  shape: ProjectShape,
+): Promise<string[]> {
+  const { selectSkills, renderSkill, skillPaths, SKILL_MARKER } =
+    await import("../install/skills.ts");
+  const { detectAgents } = await import("../install/detect.ts");
+  const { agents } = await detectAgents(root);
+
+  const stale: string[] = [];
+  for (const skill of selectSkills(packages, shape)) {
+    for (const path of skillPaths(skill.name, agents)) {
+      const file = Bun.file(`${root}/${path}`);
+      if (!(await file.exists())) {
+        stale.push(path);
+        continue;
+      }
+      const text = await file.text();
+      // A file somebody took ownership of is theirs, current or not.
+      if (!text.includes(SKILL_MARKER)) continue;
+      if (text !== renderSkill(skill, shape)) stale.push(path);
+    }
+  }
+  return stale;
+}
+
+/** The generated body, unfenced, or `undefined` when there is no block. */
+function _blockOf(text: string, start: string, end: string): string | undefined {
+  const from = text.indexOf(start);
+  const to = text.indexOf(end);
+  if (from === -1 || to === -1 || to < from) return undefined;
+  return text.slice(from + start.length, to);
+}
+
+/**
+ * The key the server is registered under, read back from `.mcp.json`.
+ *
+ * The block names it, so comparing against a guessed name would report every
+ * project that renamed its server as permanently stale. Read rather than
+ * `require`d, which would cache the first answer and miss a rename.
+ */
+async function _serverName(root: string): Promise<string> {
+  try {
+    const document = (await Bun.file(`${root}/.mcp.json`).json()) as {
+      mcpServers?: Record<string, unknown>;
+      servers?: Record<string, unknown>;
+    };
+    const names = Object.keys(document.mcpServers ?? document.servers ?? {});
+    return names[0] ?? "zerotal";
+  } catch {
+    return "zerotal";
+  }
+}

package/src/tools/searchDocs.ts

@@ -181,6 +181,13 @@ export function parsePage(path: string, raw: string): DocPage {
   };
 
   for (const line of body.split("\n")) {
+    // A fence delimiter is markup, and its info string is metadata about the
+    // block rather than anything the page says. Indexing them put the language
+    // name into every page that shows code — a search for "typescript" matched
+    // most of the corpus on the strength of its fences — and, once documentation
+    // examples grew a `fragment` marker, that word too.
+    if (/^\s*`{3,}/.test(line)) continue;
+
     const match = /^(#{1,3})\s+(.*)$/.exec(line);
     if (match) {
       flush();