@zerotal/arch 1.7.3 → 1.7.5

package/docs/validator.md

@@ -89,7 +89,7 @@ export class StorePostRequest extends FormRequest {
 Call `validate()` as a static method on the class. It reads `HttpContext` from
 `AsyncLocalStorage` — no arguments needed.
 
-```typescript
+```typescript fragment
 // in a controller
 const data = await StorePostRequest.validate();
 
@@ -116,7 +116,7 @@ never need to catch them yourself.
 `authorize()` runs **before** validation. Returning `false` throws a
 `ForbiddenError` (403) without touching the request body.
 
-```typescript
+```typescript fragment
 // in a FormRequest subclass
 
 // Check the current user's role:
@@ -141,7 +141,7 @@ async authorize(): Promise<boolean> {
 Because `rules()` is an instance method, you have full access to `this.context`
 for rules that depend on the current user, route params, or session state:
 
-```typescript
+```typescript fragment
 // in a FormRequest subclass
 rules(r: RuleBuilder) {
   const userId = this.context.user?.id;
@@ -157,7 +157,7 @@ rules(r: RuleBuilder) {
 
 For simple one-off validation without a dedicated class:
 
-```typescript
+```typescript fragment
 // in a controller
 import { validate } from "@zerotal/validator";
 
@@ -180,7 +180,7 @@ For CLI commands, services, or background jobs — where there is no request to
 redirect and no response to throw — use the `Validator` facade. It returns a
 `{ success, data, errors }` outcome and never throws.
 
-```typescript
+```typescript fragment
 // in a command or service
 import { Validator } from "@zerotal/validator";
 
@@ -200,7 +200,7 @@ if (!result.success) {
 
 Start every rule chain with a type method on `RuleBuilder`:
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 const r = new RuleBuilder(); // or the `r` param in rules()
 
@@ -247,7 +247,7 @@ These are available on **every** rule type:
 
 ### Custom validator
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 username: r.string().custom(async (value) => {
   const taken = await User.findBy("username", value as string);
@@ -257,7 +257,7 @@ username: r.string().custom(async (value) => {
 
 ## String rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.string()
   .min(3) // minimum character length
@@ -292,7 +292,7 @@ r.string()
 
 ## Number rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.number()
   .min(0) // minimum value (inclusive)
@@ -305,7 +305,7 @@ r.number()
 
 ## Boolean rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.boolean()
   .accepted() // truthy — for "agree to terms" checkboxes
@@ -314,7 +314,7 @@ r.boolean()
 
 ## Date rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.date()
   .after("2026-01-01") // strictly after date
@@ -325,7 +325,7 @@ r.date()
 
 ## Array rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.array(r.string()) // array of strings
   .min(1) // minimum item count
@@ -340,7 +340,7 @@ r.array(r.object({ name: r.string(), age: r.number() }));
 
 ## Object rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.object({
   street: r.string(),
@@ -357,7 +357,7 @@ r.object({
 
 Validates `File` objects from `multipart/form-data` uploads:
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 avatar: r.file()
   .mimes(["jpg", "jpeg", "png", "webp"]) // allowed extensions
@@ -368,7 +368,7 @@ avatar: r.file()
 
 ## Password rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.password()
   .min(8) // minimum length (default: 8)
@@ -390,7 +390,7 @@ The third argument ignores a record on update — pass the current record's ID,
 a `UniqueOptions` object (`{ ignoreId }`) for clarity. A fourth argument
 overrides the error message.
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 email: r.string().email().unique("users", "email");
 
@@ -403,7 +403,7 @@ email: r.string().email().unique("users", "email", { ignoreId: userId });
 
 ### exists — value must exist in the DB
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 userId: r.number().exists("users", "id");
 roleSlug: r.string().exists("roles", "slug");
@@ -450,7 +450,7 @@ back to the previous page.
 Errors and old input are stored in the [session](/docs/session) under the keys
 `'errors'` and `'old'`. Read them on the next request:
 
-```typescript
+```typescript fragment
 // in a controller
 const errors = ctx.flashed<Record<string, string[]>>("errors");
 const old = ctx.flashed<Record<string, unknown>>("old");
@@ -500,7 +500,7 @@ would not.
 **A `FormRequest` fails the HTTP request**, so test it through the route it
 guards. The status tells you which failure mode you got:
 
-```typescript
+```typescript fragment
 // tests/http/register.test.ts
 const res = await app.post("/register", { email: "not-an-email" });
 

package/docs/view.md

@@ -67,7 +67,7 @@ use the [`safe()` helper or `Raw` component](#embedding-raw-html).
 
 The runtime renders attributes from props with a few rules:
 
-```tsx
+```tsx fragment
 // in a component
 <input type="text" value={name} disabled={isLocked} required={false} data-id={42} />
 // → <input type="text" value="…" disabled data-id="42">
@@ -97,7 +97,7 @@ Children are rendered by type, which is the engine's security boundary:
 
 Two consequences worth remembering:
 
-```tsx
+```tsx fragment
 // in a component
 {
   user && <Welcome name={user.name} />;
@@ -123,7 +123,7 @@ Call `view()` from a controller action to set the response. It accepts any value
 whose `.toString()` returns HTML — a `SafeHtml` instance from JSX is the normal
 case:
 
-```tsx
+```tsx fragment
 // app/controllers/PostController.tsx
 import { view } from "zerotal";
 import type { HttpContext } from "zerotal";
@@ -159,7 +159,7 @@ export default function Welcome(ctx: HttpContext, { title }: { title: string })
 }
 ```
 
-```ts
+```ts fragment
 // routes/index.ts — the HttpContext is injected; you only pass the extra props
 import { Router } from "zerotal";
 import Welcome from "../resources/views/Welcome.tsx";
@@ -213,7 +213,7 @@ export function AppLayout({ title, children }: AppLayoutProps) {
 }
 ```
 
-```tsx
+```tsx fragment
 // resources/views/About.tsx
 import { defineLayout } from "zerotal/view";
 import { AppLayout } from "./layouts/AppLayout.tsx";
@@ -229,7 +229,7 @@ export const AboutPage = wrap<{ heading: string }>(({ heading }) => (
 ));
 ```
 
-```ts
+```ts fragment
 // routes/index.ts
 import { Router } from "zerotal";
 import { AboutPage } from "../resources/views/About.tsx";
@@ -246,7 +246,7 @@ directly with `Router.view()`. The third argument is the props — a **static
 object**, or a **per-request factory** that receives the `HttpContext` and may be
 async:
 
-```ts
+```ts fragment
 // routes/index.ts
 // Static props — evaluated once at registration (marketing / info pages):
 Router.view("/about", AboutPage, { title: "About Us" });
@@ -263,7 +263,7 @@ Router.view("/privacy", PrivacyPage);
 
 The returned registration is chainable:
 
-```ts
+```ts fragment
 // routes/index.ts
 Router.view("/terms", TermsPage)
   .name("terms") // name the route for url() generation
@@ -276,7 +276,7 @@ Under [file-based routing](/docs/routing), a page file's **default export**
 becomes a `GET` route automatically. The page is a function of `(http, params)`
 and may be async:
 
-```tsx
+```tsx fragment
 // app/views/posts/[slug].tsx  →  GET /posts/:slug
 import type { HttpContext } from "zerotal";
 import { Post } from "../../models/Post.ts";
@@ -311,7 +311,7 @@ export default definePage((http, params) => `<h1>Hello ${params.name}</h1>`);
 When you have pre-rendered markup (e.g. from a Markdown renderer) use `safe()` or
 `<Raw>` to bypass escaping:
 
-```tsx
+```tsx fragment
 // in a component
 import { safe, Raw } from "zerotal/view";
 
@@ -335,7 +335,7 @@ import { safe, Raw } from "zerotal/view";
 `esc()` escapes a value for use in raw string templates, where automatic JSX
 escaping isn't available:
 
-```ts
+```ts fragment
 // in a helper
 import { esc } from "zerotal/view";
 
@@ -367,7 +367,7 @@ function returning a node that stringifies, so most of it tests without a server
 **Render the component and assert on the string.** No request, no router, no
 browser:
 
-```typescript
+```typescript fragment
 // tests/views/PostCard.test.ts
 import { test, expect } from "bun:test";
 import { PostCard } from "../../resources/views/PostCard.tsx";
@@ -383,7 +383,7 @@ test("renders the title and author", () => {
 **Escaping is the test that matters.** Every view that renders user input has one
 job beyond looking right, and it is the job that becomes a security incident:
 
-```typescript
+```typescript fragment
 // tests/views/PostCard.test.ts
 test("escapes markup in user-supplied text", () => {
   const html = String(PostCard({ post: { title: "<script>alert(1)</script>" } }));
@@ -400,7 +400,7 @@ fails if someone later routes user input into it.
 **Through a route, assert the rendered text** rather than the markup around it.
 `assertSee` survives a class rename; a full-HTML comparison does not:
 
-```typescript
+```typescript fragment
 // tests/http/posts.test.ts
 const res = await app.get("/posts");
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "license": "MIT",
-  "maturity": "beta",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.3"
+    "@zerotal/core": "1.7.5"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.7.3"
+    "@zerotal/orm": "1.7.5"
   },
   "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/index.ts

@@ -27,7 +27,15 @@ export * from "./errors.ts";
 // serve a subset, or add its own alongside them.
 export { archTools, vendoredDocsDir } from "./tools/index.ts";
 export type { ToolContext } from "./tools/index.ts";
+// Subprocess plumbing, not API. `_probe.ts` carries the underscore this repo uses
+// for a module nobody outside its package should reach for, nothing in the tree
+// imports these from here, and the export block above says why the tools and the
+// probe topics are public without ever saying why these are. Marked before the
+// stable promise attaches, because withdrawing them afterwards is a breaking
+// change made on behalf of a caller that does not exist.
+/** @internal */
 export { findApp, spawnProbe } from "./tools/_probe.ts";
+/** @internal */
 export type { ProbeResult, ProbeRunner, SpawnProbeOptions } from "./tools/_probe.ts";
 
 // The in-app reads, for anyone wanting them without the subprocess.
@@ -45,12 +53,28 @@ export type {
   SchemaReport,
 } from "./probe/topics.ts";
 
-// The install writers, so a project can generate the same files its own way.
+// The writers behind `arch:install`. Exported for the command and its tests to
+// reach, not as API.
+//
+// They were public on the reasoning that "a project can generate the same files
+// its own way" — a use nobody has, and a promise about the shape of `.mcp.json`
+// writing, agent detection and marker fencing that would hold for the rest of
+// the 1.x line. `ArchInstallCommand` is the only caller in the tree. Under `beta`
+// that was a cheap bet; the stable label is what makes it expensive, so they are
+// marked now rather than withdrawn later on behalf of a caller who never arrived.
+/** @internal */
 export { detectAgents } from "./install/detect.ts";
+/** @internal */
 export type { Detected, McpTarget } from "./install/detect.ts";
+/** @internal */
 export { applyMcpConfig, serverEntry, SERVER_ENTRY_PATH } from "./install/mcpConfig.ts";
+/** @internal */
 export type { ConfigOutcome } from "./install/mcpConfig.ts";
+/** @internal */
 export { applyBlock, fence, BLOCK_END, BLOCK_START } from "./install/markers.ts";
+/** @internal */
 export type { BlockOutcome } from "./install/markers.ts";
+/** @internal */
 export { agentsPreamble, buildGuidelines, claudeShim } from "./install/guidelines.ts";
+/** @internal */
 export type { GuidelineOptions } from "./install/guidelines.ts";

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();

package/docs/client/auth.md

@@ -1,113 +0,0 @@
----
-title: Client Authentication
-description: Bearer tokens, CSRF, and refreshing credentials on a 401.
----
-
-# Authentication & CSRF
-
-The client supports the two ways a browser app proves who it is, and the choice is
-usually made for you by where the API lives:
-
-- **Bearer tokens** suit APIs on another origin, mobile clients, and anything where
-  the caller holds a credential it can attach itself.
-- **Session cookies** suit an API served from your own domain, where the browser
-  already carries the session and CSRF protection is the concern instead.
-
-## Bearer tokens
-
-Attach a bearer token (string or a resolver, sync or async) without writing an interceptor —
-update it at runtime with `setToken()`:
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  token: () => authStore.accessToken, // re-read on every request
-});
-api.setToken(freshToken); // or update imperatively
-```
-
-Prefer the resolver form. A plain string is captured once at construction, so a
-token refreshed later never reaches the client; a function is consulted on every
-request and always sees the current value.
-
-Calling `setToken()` with no argument clears the token, which is what a logout
-should do — otherwise the next request still carries the credential of the user who
-just signed out.
-
-> **Note** — The `token` is only applied when no `Authorization` header is already
-> present on the request, so a per-request override always wins.
-
-## Session cookies and CSRF
-
-For session/cookie (SPA) auth, set `withCredentials` to send cookies, which also turns on CSRF:
-the client reads the `XSRF-TOKEN` cookie and sends it as `X-XSRF-TOKEN` on mutating requests
-(matching the session/CSRF middleware). Customize the names with `csrf`:
-
-```ts
-// app/api/client.ts
-createApiClient<Routes>({
-  withCredentials: true, // credentials: 'include' + CSRF on
-  csrf: { cookie: "XSRF-TOKEN", header: "X-XSRF-TOKEN" }, // defaults shown
-});
-```
-
-Enabling `withCredentials` turns CSRF on by default, so the two travel together and
-neither needs configuring in the common case. Set `csrf: false` to opt out, or pass
-an object to rename the cookie and header to match a server that uses different
-ones.
-
-The token is attached only to mutating requests — `POST`, `PUT`, `PATCH`, `DELETE`.
-A `GET` is exempt because it should not change state, so it needs no protection
-from being triggered cross-site. If a `GET` in your API does change something, that
-is the thing to fix; adding a CSRF header to it would only hide the problem.
-
-The header is skipped when the request already carries one, so a caller that sets
-its own value keeps it.
-
-## 401 / token refresh
-
-`onUnauthorized` is called when any request receives a 401 response. It receives
-the error and a `retry` function. Call `retry()` — optionally with header overrides
-— to re-execute the failed request. The retry is limited to **one attempt**.
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-
-  onUnauthorized: async (err, retry) => {
-    const newToken = await authStore.refresh();
-    return retry({ Authorization: `Bearer ${newToken}` });
-  },
-});
-```
-
-If `onUnauthorized` is not provided or does not call `retry`, the 401 error is
-thrown normally.
-
-The single-attempt limit is deliberate: a refresh that itself returns 401 would
-otherwise retry forever, turning an expired session into an endless loop of
-requests. When the retry also fails, the error is thrown and the app can send the
-user to the login screen.
-
-One case the hook does not solve on its own is a page that fires several requests
-at once. Each 401 calls `onUnauthorized` separately, so a naive handler triggers
-several concurrent refreshes and the losers of that race may invalidate the winner's
-token. Have the refresh itself de-duplicate — cache the in-flight promise in your
-auth store and hand the same one to every caller until it settles:
-
-```ts
-// app/api/authStore.ts
-let inflight: Promise<string> | null = null;
-
-export function refresh(): Promise<string> {
-  inflight ??= requestNewToken().finally(() => (inflight = null));
-  return inflight;
-}
-```
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Error handling](/docs/client/errors) — the errors a rejected request throws.
-- [CSRF protection](/docs/csrf) — the server side of the cookie and header pair.

package/docs/client/errors.md

@@ -1,139 +0,0 @@
----
-title: Client Error Handling
-description: What a failed request throws, and how to tell the failure modes apart.
----
-
-# Error handling
-
-Non-2xx responses throw `ApiClientError`:
-
-```ts
-// in any frontend module
-import { ApiClientError } from "@zerotal/client";
-
-try {
-  await api.post("/api/users", { name: "", email: "bad" });
-} catch (err) {
-  if (err instanceof ApiClientError) {
-    console.log(err.status); // 422
-    console.log(err.statusText); // 'Unprocessable Entity'
-    console.log(err.body); // raw response text (the error message truncates it to 200 chars)
-  }
-}
-```
-
-## Telling the failure modes apart
-
-Two very different things can go wrong, and only one of them produces an
-`ApiClientError`:
-
-| What happened                    | What is thrown                      |
-| -------------------------------- | ----------------------------------- |
-| The server answered with non-2xx | `ApiClientError`                    |
-| A 422 in the validator's shape   | `ValidationError`                   |
-| The circuit breaker is open      | `CircuitBreakerOpenError`           |
-| No answer at all                 | The platform's own error, unwrapped |
-
-That last row is the one worth internalising. A DNS failure, a dropped connection,
-a CORS rejection, or an aborted request never reaches the point where a status
-exists, so `fetch` rejects with its own error and the client passes it through
-untouched. An `instanceof ApiClientError` check therefore does _not_ catch an
-offline user — and a `catch` block that assumes `err.status` exists throws a second
-error while handling the first.
-
-```ts
-try {
-  await api.get("/api/users");
-} catch (err) {
-  if (err instanceof ValidationError) showFieldErrors(err.errors);
-  else if (err instanceof ApiClientError) showStatus(err.status);
-  else showOffline(); // no response: network, CORS, timeout, or abort
-}
-```
-
-Timeouts and cancellations land in that final branch too, since both abort the
-request rather than producing a response.
-
-## Reading response headers
-
-`ApiClientError` carries the response headers when there were any, which is where
-rate limiters and throttles put the information you need to react well:
-
-```ts
-// in any frontend module
-if (err instanceof ApiClientError && err.status === 429) {
-  const waitMs = err.retryAfterMs; // parsed Retry-After, or null
-  if (waitMs !== null) scheduleRetry(waitMs);
-  console.log(err.headers?.get("X-RateLimit-Remaining"));
-}
-```
-
-`retryAfterMs` handles both forms the header takes — a delta in seconds and an
-HTTP-date — and returns milliseconds, or `null` when the header is absent or
-cannot be parsed.
-
-## Global handlers
-
-The `onError` callback fires for every non-2xx response before the error is thrown.
-Use it for global side-effects (toasts, logging) without needing try/catch at every
-call site:
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-  onError: (err) => {
-    toast.error(`${err.status}: ${err.statusText}`);
-    logger.error("api_error", { status: err.status, body: err.body });
-  },
-});
-```
-
-> **Warning** — `onError` fires for every non-2xx error including 401, even when `onUnauthorized` is also configured. To suppress the global error callback for 401 during token refresh, guard by status inside `onError`.
-
-Because `onError` only ever sees responses, it does not report the network failures
-described above. Reporting that should also cover "the request never arrived"
-belongs in the caller, or in a wrapper around it.
-
-### Typed validation errors
-
-A `422` response whose body matches the framework's validation shape (`{ message, errors }`,
-as produced by [`@zerotal/validator`](/docs/validator)) throws a `ValidationError` — an
-`ApiClientError` subclass with the field errors already parsed:
-
-```ts
-// in any frontend module
-import { ValidationError } from "@zerotal/client";
-
-try {
-  await api.post("/api/users", form);
-} catch (err) {
-  if (err instanceof ValidationError) {
-    setFieldErrors(err.errors); // { email: ["…"], password: ["…"] }
-    err.has("email"); // boolean
-    err.first("email"); // first message, or undefined
-    err.fields(); // ["email", "password"]
-    err.validationMessage; // "The given data was invalid."
-  }
-}
-```
-
-Check for `ValidationError` before `ApiClientError`. It is a subclass, so the
-broader check also matches it and would swallow the parsed field errors.
-
-A 422 whose body does not match that shape stays a plain `ApiClientError`, so an
-endpoint returning its own error format still surfaces as an ordinary failure
-rather than quietly producing an empty `errors` object.
-
-`onForbidden` is the 403 counterpart of `onUnauthorized`:
-
-```ts
-// app/api/client.ts
-createApiClient<Routes>({ onForbidden: () => router.push("/403") });
-```
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Resilience](/docs/client/resilience) — retries, timeouts, and the circuit breaker.
-- [Authentication](/docs/client/auth) — the 401 refresh hook.