@zerotal/arch 1.7.0 → 1.7.3

package/docs/routing.md

@@ -486,11 +486,25 @@ the checked signature above decorative.
 Typed names flow through the helpers built on `route()` too — `redirect().to()`,
 `Url.route()`, `Uri.route()`, and Flow's `redirectRoute()`.
 
+The types that checking is built from are exported from `zerotal/routes`, for
+when you write a helper that forwards to `route()` rather than calling it
+directly:
+
+| Type               | What it holds                                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `RouteTarget`      | The name a checked helper accepts: `RouteName` once the registry is generated, plain `string` before it.          |
+| `RouteArgs<N>`     | Everything `route()` takes after the name — params required only when the pattern has one, query always optional. |
+| `RouteParamValues` | The loose param bag the unchecked overload accepts.                                                               |
+| `RouteQuery`       | Query values. `null` and `undefined` entries drop out, and an array repeats the key.                              |
+
 ### route() in the browser
 
-The server's `route()` reads the live router, which only exists in the server
-process. In a browser bundle, import it from `zerotal/routes` instead and
-hand it the generated table once, at your entry point:
+`route()` works on the server with no setup: the application installs the table
+during boot, from the routes it just registered. That covers every URL your
+server renders — a `view` build's `href` attributes and form actions included.
+
+A browser bundle is a different process with no router to read, so there it needs
+the table handed to it once, at your entry point:
 
 ```typescript
 // resources/js/app.js
@@ -503,8 +517,6 @@ defineRoutes(ROUTES);
 From there the call is the one you already know:
 
 ```typescript
-import { route } from "zerotal/routes";
-
 route("posts.show", { slug }); // → '/posts/hello'
 route("posts.index", {}, { page: 2 }); // → '/posts?page=2'
 ```
@@ -515,10 +527,35 @@ server and the same call made in a component cannot disagree about encoding —
 because `types/routes.generated.ts` augments the one registry, a name that
 type-checks in a controller type-checks in a component.
 
+### route() needs no import
+
+`defineRoutes()` also puts `route()` on `globalThis`, so a page, a component or a
+controller calls it with nothing at the top of the file:
+
+```tsx
+// no import line
+<a href={route("posts.show", { slug })}>{post.title}</a>
+```
+
+It is installed from `defineRoutes()` because that is the one function both
+processes already call — the server during boot, a browser entry beside its
+generated `ROUTES` — which means neither has to remember a second setup step. The
+table is installed before the global, so `route()` never exists in a state where
+calling it reports a missing table.
+
+The global is typed by an ambient declaration in `@zerotal/core/routes`, as the
+same `RouteBuilder` the named export is: an unknown route name or a missing
+`:param` still fails the build.
+
+> **Note** — `route` remains a named export. Importing it explicitly keeps
+> working, and is worth doing in a library that cannot assume an application has
+> booted.
+
 `defineRoutes()` takes the generated `ROUTES` object or any `RouteTable`
 (a name → pattern map). Calling it again replaces the table, which is what makes
-hot reload work. `resetRoutes()` clears it again, for tests that assert on the
-unconfigured error.
+hot reload work — and what lets a browser entry install its own copy without
+disturbing the server's. `resetRoutes()` clears it again, for tests that assert
+on the unconfigured error.
 
 If your app renders through SSR, call `defineRoutes()` in the SSR entry too — the
 page components run in both processes.
@@ -543,6 +580,51 @@ helper to Alpine expressions as `$route`:
 
 Nothing to install, and the names are the same ones the server rendered with.
 
+### Submitting to a route with action()
+
+`route()` gives you a URL. A form needs two things — where to send the request
+and how — and a URL alone leaves the second one to be typed out beside it:
+
+```typescript
+// The URL is generated; the verb is a guess that happens to be right today.
+form.post(route("posts.comments.store", { post: id }));
+```
+
+`bun zt route:types` also writes a `METHODS` table, so the verb can come from
+the same place the URL does. `action()` returns both:
+
+```typescript
+// resources/js/app.js
+import { defineRouteMethods, defineRoutes } from "zerotal/routes";
+import { METHODS, ROUTES } from "../../types/routes.generated";
+
+defineRoutes(ROUTES);
+defineRouteMethods(METHODS);
+```
+
+```typescript
+import { action } from "zerotal/routes";
+
+const endpoint = action("posts.comments.store", { post: id });
+// → { url: '/posts/42/comments', method: 'POST' }
+
+form.submit(endpoint.method.toLowerCase(), endpoint.url);
+```
+
+`action()` takes the same names and params as `route()` and reports the same
+compile errors, so switching a call over costs nothing. What it buys is that a
+route which changes verb changes every submission with it — the failure it
+prevents is a 405 on submit, which looks nothing like its cause when the URL in
+front of you is plainly correct.
+
+Two tables rather than one map of `{ url, method }` objects, for two reasons: it
+leaves `ROUTES` alone, so a generated file from an earlier version still works;
+and a bundle that only renders links never pulls the verbs in.
+
+`defineRouteMethods()` is optional. Without it `action()` still resolves the URL
+and reports `GET`, which is the right answer for a link-only bundle and a better
+one than throwing.
+
 ## File-based routing
 
 Map a directory tree to routes: each file under the routes directory becomes an

package/docs/seeding.md

@@ -76,6 +76,13 @@ Create a `DatabaseSeeder` that coordinates all other seeders. Use `this.call()`
 to run child seeders — they execute in order inside a single transaction, so if
 any fails, every change rolls back atomically.
 
+`bun zt db:seed` wraps the whole run in a transaction too, so a seeder that does
+its work inline rather than delegating to `call()` is just as atomic. Nesting is
+fine: `call()` inside the outer transaction becomes a savepoint, and an inner
+failure still rolls back independently. Where there is no database connection
+bound at all — a seeder that writes fixtures to disk, say — the run is left
+alone rather than failing for want of a transaction it never needed.
+
 ```ts
 // database/seeders/DatabaseSeeder.ts
 import { Seeder, DB } from "@zerotal/orm";

package/docs/support-policy.md

@@ -49,11 +49,11 @@ course?", so this is it:
 
 ## Databases
 
-| Database   | Status                                                                                                                                                                                           |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| SQLite     | Supported. The default; the full test suite runs against it on every merge.                                                                                                                      |
-| PostgreSQL | Supported, hardening. The ORM suite runs against a real Postgres in CI; remaining dialect gaps are being driven to zero before the job blocks merges.                                            |
-| MySQL      | Experimental. The ORM ships a MySQL dialect and the scaffolder can configure it, but no CI suite runs against a real MySQL server yet — treat it as unverified until it joins the tested matrix. |
+| Database   | Status                                                                                                                                                                                                                                                                                                                                 |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite     | Supported. The default; the full test suite runs against it on every merge.                                                                                                                                                                                                                                                            |
+| PostgreSQL | Supported. A smoke suite runs against a real PostgreSQL 16 on every merge — schema DDL, identity columns, CRUD, type round-trips, row locks and transaction rollback — and the job blocks a merge when it fails. The bulk of the ORM suite still runs on SQLite, so coverage of the Postgres path is narrower than of the default one. |
+| MySQL      | Experimental. The ORM ships a MySQL dialect and the scaffolder can configure it, but no CI suite runs against a real MySQL server yet — treat it as unverified until it joins the tested matrix.                                                                                                                                       |
 
 Redis-backed drivers (cache, session, queue, broadcasting) build on
 `Bun.RedisClient` and are tested against the protocol surface it provides.
@@ -67,6 +67,14 @@ dependency order, from CI. Never mix versions across packages.
 - **Semantic versioning:** patch for fixes, minor for compatible features, major
   for breaking changes. The [Upgrade Guide](/docs/upgrade) describes the upgrade
   procedure; the [Release Notes](/docs/changelog) list what changed.
+- **One exception, while the 1.x line is young:** a breaking change may land in a
+  minor or a patch when leaving it in place would cost more than the migration
+  does. It is called out in the release notes as **BREAKING**, with the reason and
+  the migration steps, and it is never silent. Two have shipped so far — the
+  `ComponentWith` / `BaseModelWith` removal in 1.3.0 and Flow's `socket:` listener
+  prefix in 1.7.2. This carve-out is a consequence of the project's age, not a
+  standing policy; it will be withdrawn, with a version named here, once adoption
+  makes the cost of a break real.
 - **Provenance:** packages are published with npm provenance, so you can verify
   a tarball was built by this repository's release workflow rather than someone's
   laptop.

package/docs/upgrade.md

@@ -18,6 +18,8 @@ version line:
 - **Major** (`X.y.z`) — breaking changes; read the version's section in the
   [Release Notes](/docs/changelog) before upgrading.
 
+> **Warning** — while the 1.x line is young, a breaking change may also land in a minor or a patch. It is always labelled **BREAKING** in the [Release Notes](/docs/changelog) with migration steps, and two have shipped so far (1.3.0 and 1.7.2). Read the notes for every version you cross, not only the majors. See [Releases and versioning](/docs/support-policy#releases-and-versioning) for when this carve-out ends.
+
 > **Warning** — always upgrade the `@zerotal/*` packages together. Mixing versions across core, ORM, and feature packages leads to type and runtime mismatches.
 
 ## Upgrade steps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "license": "MIT",
   "maturity": "beta",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.0"
+    "@zerotal/core": "1.7.3"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.7.0"
+    "@zerotal/orm": "1.7.3"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [

package/src/install/guidelines.ts

@@ -117,7 +117,11 @@ const PACKAGE_BLOCKS: PackageBlock[] = [
   },
   {
     pkg: "@zerotal/i18n",
-    lines: ["**Translations.** `@zerotal/i18n`; message files live under `resources/lang/`."],
+    lines: [
+      "**Translations.** `@zerotal/i18n`; message files live under `resources/lang/`. " +
+        'Translate with `__("English sentence")` — the source string is the key, so there ' +
+        "is no catalog for the source language and no key to invent.",
+    ],
   },
   {
     pkg: "@zerotal/tenancy",

package/src/install/markers.ts

@@ -25,9 +25,18 @@ export type BlockOutcome =
   /** The markers are damaged; nothing was written. */
   | { status: "conflict"; reason: string };
 
-/** Wrap generated content in its markers. */
+/**
+ * Wrap generated content in its markers.
+ *
+ * The blank lines either side are not cosmetic. In Markdown, text on the line
+ * immediately after an HTML comment is parsed as part of that raw-HTML block, so
+ * `@AGENTS.md` pressed against the opening marker stops being a paragraph — and
+ * every formatter, including the `prettier --check` a Zerotal project already
+ * runs, inserts them. A generator whose output fails the project's own format
+ * gate is a generator nobody can run twice.
+ */
 export function fence(content: string): string {
-  return `${BLOCK_START}\n${content.trim()}\n${BLOCK_END}`;
+  return `${BLOCK_START}\n\n${content.trim()}\n\n${BLOCK_END}`;
 }
 
 /**

package/src/install/mcpConfig.ts

@@ -70,10 +70,22 @@ export function applyMcpConfig(
       : {};
 
   servers[name] = serverEntry();
-  const text = JSON.stringify({ ...document, [target.key]: servers }, null, 2) + "\n";
+  const next = { ...document, [target.key]: servers };
+  const text = JSON.stringify(next, null, 2) + "\n";
 
   if (isNew) return { status: "created", text };
-  return text === existing ? { status: "unchanged", text } : { status: "updated", text };
+
+  // Compared as data, not as text. `JSON.stringify(…, 2)` expands a one-element
+  // array across three lines where a formatter collapses it, and a project's
+  // formatter settings are its own business — so a textual comparison made
+  // `arch:update` rewrite a file it had no change to make to, and the next
+  // `prettier --write` put it back. That ping-pong shows up as a dirty working
+  // tree after running two commands that both claim to be no-ops.
+  //
+  // Semantic equality ends it: when the config already says what it should, the
+  // file is returned exactly as it was found, in whatever shape its owner keeps it.
+  if (Bun.deepEquals(document, next)) return { status: "unchanged", text: existing };
+  return { status: "updated", text };
 }
 
 function describe(error: unknown): string {

package/src/probe/topics.ts

@@ -262,12 +262,27 @@ function readConfig(app: Application, key: string): unknown {
  * heard of.
  */
 export async function installedPackages(root = process.cwd()): Promise<InstalledPackage[]> {
-  const found: InstalledPackage[] = [];
-  const glob = new Bun.Glob("node_modules/{zerotal,@zerotal/*}/package.json");
+  const { readdir } = await import("node:fs/promises");
+
+  // Listed with `readdir`, not matched with a glob. In a workspace — this
+  // monorepo, `bun link`, any app developed against a checkout — every
+  // `node_modules/@zerotal/*` is a symlink to the package directory, and glob
+  // traversal does not descend into one even with `followSymlinks`. It returned
+  // zero packages for `apps/docs`, which has seventeen. `readdir` lists the link
+  // itself and `Bun.file` follows it, so both layouts read the same.
+  const candidates = [`${root}/node_modules/zerotal`];
+  try {
+    for (const name of await readdir(`${root}/node_modules/@zerotal`)) {
+      candidates.push(`${root}/node_modules/@zerotal/${name}`);
+    }
+  } catch {
+    /* no scoped packages installed here */
+  }
 
-  for await (const file of glob.scan({ cwd: root, onlyFiles: true })) {
+  const found: InstalledPackage[] = [];
+  for (const dir of candidates) {
     try {
-      const manifest = (await Bun.file(`${root}/${file}`).json()) as Record<string, unknown>;
+      const manifest = (await Bun.file(`${dir}/package.json`).json()) as Record<string, unknown>;
       const name = manifest["name"];
       const version = manifest["version"];
       if (typeof name !== "string" || typeof version !== "string") continue;

package/src/tools/apiSurface.ts

@@ -106,23 +106,46 @@ export async function findSurfaceFile(
   return undefined;
 }
 
-/** Every package whose snapshot this project can serve, for the "did you mean" list. */
+/**
+ * Every package whose snapshot this project can serve, for the "did you mean" list.
+ *
+ * `node_modules` is listed rather than globbed: in a workspace each
+ * `@zerotal/*` entry is a symlink to the package directory, and glob traversal
+ * does not descend into one — so the suggestion list came back empty in exactly
+ * the layout a framework contributor works in. `packages/` is a real tree and is
+ * globbed as before.
+ */
 async function availablePackages(root: string): Promise<string[]> {
+  const { readdir } = await import("node:fs/promises");
   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 */
+
+  const linked = [`${root}/node_modules/zerotal`];
+  try {
+    for (const name of await readdir(`${root}/node_modules/@zerotal`)) {
+      linked.push(`${root}/node_modules/@zerotal/${name}`);
     }
+  } catch {
+    /* nothing installed under the scope */
+  }
+  for (const dir of linked) {
+    if (!(await Bun.file(`${dir}/api-surface.md`).exists())) continue;
+    const base = dir.split(/[\\/]/).pop() ?? "";
+    names.add(base === "zerotal" ? "zerotal" : `@zerotal/${base}`);
   }
+
+  try {
+    for await (const file of new Bun.Glob("packages/*/api-surface.md").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();
 }
 
@@ -134,13 +157,16 @@ export function apiSurfaceTool(ctx: ToolContext): ArchTool {
       "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.",
+      "prefer it over recalling an API from memory. Pass `symbol` alone to find an export " +
+      "when you do not know which package owns it; add `package` to narrow.",
     inputSchema: {
       type: "object",
       properties: {
         package: {
           type: "string",
-          description: 'Package name, with or without the scope — "core" or "@zerotal/core".',
+          description:
+            'Package name, with or without the scope — "core" or "@zerotal/core". ' +
+            "Omit to search every installed package.",
         },
         symbol: {
           type: "string",
@@ -148,7 +174,6 @@ export function apiSurfaceTool(ctx: ToolContext): ArchTool {
             "Only return exports whose name contains this, case-insensitively. Omit for all.",
         },
       },
-      required: ["package"],
       additionalProperties: false,
     },
     outputSchema: {
@@ -175,9 +200,23 @@ export function apiSurfaceTool(ctx: ToolContext): ArchTool {
     },
 
     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 requested = typeof args["package"] === "string" ? args["package"].trim() : "";
+      const filter = typeof args["symbol"] === "string" ? args["symbol"].toLowerCase() : undefined;
+
+      // No package named: search them all for the symbol.
+      //
+      // Requiring one assumed the caller already knew where an export lived,
+      // which is the opposite of the situation that sends someone here — you
+      // reach for this tool *because* you are unsure, and being made to guess a
+      // package first is how you end up guessing the signature instead.
+      if (requested.length === 0) {
+        if (filter === undefined || filter.length === 0) {
+          return {
+            text: "Pass `symbol` to search every package, or `package` to list one.",
+            failed: true,
+          };
+        }
+        return searchEverywhere(ctx.root, args["symbol"] as string, filter);
       }
 
       const found = await findSurfaceFile(ctx.root, requested);
@@ -192,7 +231,6 @@ export function apiSurfaceTool(ctx: ToolContext): ArchTool {
       }
 
       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
@@ -239,3 +277,60 @@ function render(pkg: string, entries: SurfaceEntry[], total: number): string {
 
   return `${header}\n\n${sections.join("\n\n")}`;
 }
+
+/**
+ * Find a symbol without being told which package it lives in.
+ *
+ * The narrow form answers "what is the signature of X in package Y". This one
+ * answers "where is X, and what is its signature" — the question you actually
+ * have when an API you half-remember turns out not to exist. Matches are
+ * grouped by package so an ambiguous name shows every owner rather than the
+ * first.
+ */
+async function searchEverywhere(
+  root: string,
+  symbol: string,
+  filter: string,
+): Promise<ToolOutcome> {
+  const packages = await availablePackages(root);
+  const hits: { package: string; entries: SurfaceEntry[] }[] = [];
+
+  for (const name of packages) {
+    const found = await findSurfaceFile(root, name);
+    if (!found) continue;
+
+    // Signature as well as name. An export's name is the class — `Auth` — while
+    // the thing someone looks up is usually a member of it: `userOrNull`,
+    // `salutation`, `assertInvalid`. Matching names alone answers "is there an
+    // export called X", which is rarely the question; the question is "where is
+    // this method and what does it take".
+    const matched = parseSurface(await Bun.file(found.path).text()).filter(
+      (entry) =>
+        entry.name.toLowerCase().includes(filter) || entry.signature.toLowerCase().includes(filter),
+    );
+    if (matched.length > 0) hits.push({ package: found.scoped, entries: matched });
+  }
+
+  if (hits.length === 0) {
+    return {
+      text:
+        `No export matching "${symbol}" in any installed package.\n\n` +
+        `Searched: ${packages.join(", ")}`,
+      data: { package: "", total: 0, matched: 0, entries: [] },
+      failed: true,
+    };
+  }
+
+  const total = hits.reduce((n, hit) => n + hit.entries.length, 0);
+  const text = hits.map((hit) => render(hit.package, hit.entries, hit.entries.length)).join("\n\n");
+
+  return {
+    text: `${total} export(s) matching "${symbol}" across ${hits.length} package(s).\n\n${text}`,
+    data: {
+      package: hits.map((hit) => hit.package).join(", "),
+      total,
+      matched: total,
+      entries: hits.flatMap((hit) => hit.entries),
+    },
+  };
+}

package/src/tools/baselines.ts

@@ -58,6 +58,15 @@ export interface BaselineReading {
   total: number;
   /** Per-package or per-file detail, when the baseline records it. */
   breakdown?: Record<string, number>;
+  /**
+   * What the number does not cover, when the baseline exempts something.
+   *
+   * The cast baseline ratchets per file but exempts designated boundary
+   * modules, so its ceiling is smaller than the count `cast:check` prints — and
+   * a reader who saw only the ceiling would take the command's larger number for
+   * a regression it is not.
+   */
+  note?: string;
   updatedAt?: string;
 }
 
@@ -95,6 +104,24 @@ function readBreakdown(document: Record<string, unknown>): Record<string, number
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
+/**
+ * What a baseline's ceiling leaves out.
+ *
+ * The cast baseline lists `boundaries` — files exempt from the per-file ratchet
+ * — so its recorded ceiling is smaller than the count `cast:check` reports.
+ * Without saying so, a reader comparing the two numbers sees a regression that
+ * is not there.
+ */
+function exemptionNote(document: Record<string, unknown>): string | undefined {
+  const boundaries = document["boundaries"];
+  if (!Array.isArray(boundaries) || boundaries.length === 0) return undefined;
+  const count = boundaries.length;
+  return (
+    `Excludes ${count} boundary module${count === 1 ? "" : "s"} exempt from the ratchet, so ` +
+    `the command reports a larger total: ${boundaries.join(", ")}.`
+  );
+}
+
 async function readBaselines(root: string): Promise<BaselineReading[]> {
   const readings: BaselineReading[] = [];
 
@@ -107,12 +134,14 @@ async function readBaselines(root: string): Promise<BaselineReading[]> {
       if (total === undefined) continue;
       const breakdown = readBreakdown(document);
       const updatedAt = document["updatedAt"];
+      const note = exemptionNote(document);
       readings.push({
         name: ratchet.name,
         file: ratchet.file,
         command: ratchet.command,
         total,
         ...(breakdown !== undefined ? { breakdown } : {}),
+        ...(note !== undefined ? { note } : {}),
         ...(typeof updatedAt === "string" ? { updatedAt } : {}),
       });
     } catch {
@@ -189,10 +218,10 @@ export function baselinesTool(ctx: ToolContext): ArchTool {
       const sections: string[] = [];
 
       if (baselines.length > 0) {
-        const rows = baselines.map(
-          (reading) =>
-            `  ${reading.name.padEnd(18)}${String(reading.total).padStart(6)}   ${reading.command}`,
-        );
+        const rows = baselines.flatMap((reading) => {
+          const row = `  ${reading.name.padEnd(18)}${String(reading.total).padStart(6)}   ${reading.command}`;
+          return reading.note ? [row, `      note: ${reading.note}`] : [row];
+        });
         sections.push(`Ratchets — these numbers may go down, never up:\n\n${rows.join("\n")}`);
       } else {
         sections.push("This project records no baselines.");