@impetik/xeer-mcp 0.2.5 → 0.2.6

package/vendor/spec/diagnostics.js

@@ -0,0 +1,500 @@
+/**
+ * The diagnostic catalogue.
+ *
+ * Xeer's primary user is a coding agent, so a diagnostic code is a stable API:
+ * an agent dispatches on `code`, not on wording. This module is the single
+ * declaration of what each code means and which edit closes it, and the agent
+ * reference shipped with the skill is rendered from it by
+ * `renderDiagnosticsReference()` rather than written by hand.
+ *
+ * `packages/spec/src/diagnostics.test.ts` scans every non-test source file in
+ * the workspace for `XE####` literals and fails when the emitted set and this
+ * catalogue disagree in either direction, so a new code cannot ship
+ * undocumented and a retired code cannot linger here.
+ */
+export const DIAGNOSTIC_FAMILIES = [
+    {
+        prefix: 'XE00',
+        title: 'CLI',
+        summary: 'The command itself failed. Not an application defect.',
+    },
+    {
+        prefix: 'XE10',
+        title: 'Manifest',
+        summary: 'xeer.app.json is missing, unparseable, or violates the application-source schema — '
+            + 'including the database schema, indexes, capabilities, and budgets it declares.',
+    },
+    {
+        prefix: 'XE11',
+        title: 'Manifest paths',
+        summary: 'A manifest path does not resolve to a file inside the project root.',
+    },
+    {
+        prefix: 'XE12',
+        title: 'Module graph and zones',
+        summary: 'The client and server graphs are walked separately. Each zone has its own package '
+            + 'allowlist, every import must be a static literal resolving inside the project, and shared '
+            + 'code lives under src/shared/. Type errors in the reachable graph land here too.',
+    },
+    {
+        prefix: 'XE13',
+        title: 'Operations',
+        summary: 'The default defineServer({...}) export is read statically, so operation and endpoint '
+            + 'registration must be a literal object with valid, unambiguous names.',
+    },
+    {
+        prefix: 'XE14',
+        title: 'Budgets and assets',
+        summary: 'A module or public asset breaks a v0 size limit, collides with generated output, or '
+            + 'claims a platform-reserved path.',
+    },
+    {
+        prefix: 'XE15',
+        title: 'Bundling',
+        summary: 'The client or server bundle failed after analysis passed.',
+    },
+    {
+        prefix: 'XE16',
+        title: 'Development loop',
+        summary: 'A watch rebuild failed. The last-good preview stays active and is rolled back to; '
+            + 'these codes arrive as compile.diagnostic events, never as a dead server.',
+    },
+    {
+        prefix: 'XE17',
+        title: 'Artifact preview',
+        summary: 'xeer preview verifies the content-addressed artifact and its blobs before booting. '
+            + 'These codes mean the build output is missing, malformed, or does not match its own identity.',
+    },
+    {
+        prefix: 'XE18',
+        title: 'Local state and state transfer',
+        summary: 'Local dev/preview/test state is leased per project and mode, destructive resets are '
+            + 'confirmed by exact application name, and `xeer export`/`xeer import` move it as a versioned '
+            + 'xeer.state-export.v0 document that must fit the schema currently in force.',
+    },
+    {
+        prefix: 'XE19',
+        title: 'Tests',
+        summary: 'xeer test builds the project, type-checks tests/**/*.test.ts against the generated '
+            + 'contract, and runs each test against a fresh isolated state. A failure carries the standard '
+            + 'Diagnostic fields plus kind, matcher, expected, and actual, so the same parser handles it.',
+    },
+    {
+        prefix: 'XE20',
+        title: 'Inspector',
+        summary: 'An inspector request failed. Locally the target is a preview URL; for a deployed app the '
+            + 'request is routed through the control plane and requires builder ownership.',
+    },
+    {
+        prefix: 'XE30',
+        title: 'Scaffold',
+        summary: 'xeer new could not create the project.',
+    },
+    {
+        prefix: 'XE31',
+        title: 'Agent setup',
+        summary: 'xeer agent setup found missing, stale, invalid, or user-owned adapter files.',
+    },
+    {
+        prefix: 'XE40',
+        title: 'Environment',
+        summary: 'xeer doctor found a broken toolchain or generated-file state. The failing check id and '
+            + 'details are in result.checks.',
+    },
+    {
+        prefix: 'XE50',
+        title: 'Builder authentication',
+        summary: 'Builder sign-in against the control plane. Sign-in is a human step; an agent reads '
+            + 'these codes and asks for it.',
+    },
+    {
+        prefix: 'XE51',
+        title: 'Deployment, project identity, environment variables, and service tokens',
+        summary: 'The deployment itself; the checked-in xeer.project.json appId that decides which hosted '
+            + 'app a checkout deploys to, where the repair is always xeer link rather than a new appId; the '
+            + 'per-project encrypted environment store behind xeer env; and the deployment history behind '
+            + 'xeer deployments; plus the hidden service-token lifecycle behind xeer token.',
+    },
+];
+// dev, build, and test all run the same compiler, so anything check reports can
+// also arrive from them. That is the property that makes check the cheap
+// pre-flight for the other three.
+const CHECKED_BY_EVERY_COMPILE = ['check', 'build', 'dev', 'test'];
+const BUILT_BY_EVERY_BUILD = ['build', 'dev', 'test'];
+function define(code, means, repair, surfaces) {
+    return { code, prefix: code.slice(0, 4), means, repair, surfaces };
+}
+export const DIAGNOSTIC_DEFINITIONS = [
+    define('XE0000', 'The CLI crashed before it could report a structured result. Written to stderr, so it '
+        + 'is the one code that can arrive outside a JSON envelope.', 'Report it: an internal error is a platform bug, not a project defect. stderr carries the stack.', ['any']),
+    define('XE0001', 'Unknown or unimplemented command.', 'Read `xeer --help` and use a documented command.', ['any']),
+    define('XE0002', 'A CLI option is unknown, lacks its required value, or assigns a value to a boolean flag.', 'Use an option shown by `xeer --help`; preview deployment is `xeer deploy --environment preview`.', ['any']),
+    define('XE1001', 'xeer.app.json was not found in the target directory.', 'Run `xeer new <directory>`, or point the command at the project root that holds the manifest.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1002', 'A manifest value is invalid: bad JSON, a failed schema rule, or an entrypoint that '
+        + 'does not exist. Also covers the declared database schema — unknown field types, an index naming '
+        + 'a field the table does not declare, reserved field names, and tables declared without the '
+        + '"database" capability — and every capability declaration: an unknown capability name, one '
+        + 'declared twice, a config block whose capability is not in `capabilities` (or the reverse), and a '
+        + 'declared limit above the platform ceiling.', 'Read the message: it names the failing manifest path (for example database.tables.notes.indexes.by_owner) '
+        + 'and the rule. Correct that one value. A capability and its config block are one declaration in two '
+        + 'halves — `"capabilities": ["storage"]` and a `"storage": {}` block — so either add the missing half '
+        + 'or remove the present one.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1003', 'The manifest carries a property the application-source schema does not define.', 'Remove the property, or fix its spelling. The manifest is closed: unknown keys are never ignored.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1101', 'An entrypoint path is absolute or escapes the project root.', 'Use a forward-slash path relative to xeer.app.json that stays inside the project.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1201', 'A source import breaks the zone boundary: it is absolute, leaves the project root, '
+        + 'reaches the opposite entrypoint, or the module is reachable from both graphs while living outside '
+        + 'src/shared/.', 'Keep imports relative and inside the project. Move genuinely shared code to src/shared/ and update '
+        + 'both importers; never import one entrypoint from the other.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1202', 'A package import is not on the allowlist for that zone.', 'The client zone may import @impetik/xeer/client, /shared, the JSX runtimes, and preact; the server '
+        + 'zone may import @impetik/xeer/server and /shared. Node builtins are never importable. Move the code '
+        + 'to the zone that owns it instead of widening the import.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1203', 'A dynamic import() specifier is not a string literal.', 'Use a literal specifier so the module graph stays statically knowable, or a static import.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1204', 'A relative source import does not resolve to a file.', 'Write the specifier without an extension, or with the file\'s real one: the resolver appends '
+        + 'candidate extensions rather than rewriting them, so ./shared/title.js does not find '
+        + 'shared/title.ts. Directory imports resolve to index.*.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1205', 'TypeScript reported an error in a file reachable from an entrypoint. The message '
+        + 'starts with the TS#### code and span points at the exact position.', 'Fix the type error. Operation input and result types come from the generated contract, so a mismatch '
+        + 'between a client call and its server handler surfaces here.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1206', 'A stylesheet is imported outside the client graph.', 'Import .css only from client modules; the server bundle has no styling stage.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1300', 'The default server export is not a statically inspectable defineServer({...}) call, '
+        + 'or an operation group is not a literal object.', 'Export `default defineServer({ queries: {...}, mutations: {...}, endpoints: {...} })` with literal '
+        + 'object members: no spreads, shorthand, computed keys, or wrappers.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1301', 'Two operations in the same group share a name.', 'Rename one of them, or delete the duplicate registration if it was a copy-paste.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1302', 'An endpoint key is not `METHOD /api/path`.', 'Use an uppercase HTTP method, one space, and a literal /api path; dynamic segments are :name.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1303', 'A query or mutation name is not namespaced.', 'Use a dotted lowercase name such as notes.list.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1304', 'Two endpoints reduce to the same route shape, so dispatch would be ambiguous.', 'Change the method or a static path segment. Parameter names do not distinguish routes: '
+        + 'GET /api/notes/:id and GET /api/notes/:slug are the same route.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1401', 'A compiled module (10 MiB) or an asset (25 MiB) exceeds the v0 limit.', 'Shrink the module or asset. There is no flag that raises a v0 limit.', BUILT_BY_EVERY_BUILD),
+    define('XE1402', 'A file in public/ collides with generated output.', 'Rename the public file; the platform generates the application document at /index.html.', BUILT_BY_EVERY_BUILD),
+    define('XE1403', 'A file in public/ claims a platform-reserved path.', 'Move it: /_xeer/*, /__xeer/* and /_xa/* belong to the platform.', BUILT_BY_EVERY_BUILD),
+    define('XE1404', 'The manifest declares a favicon the project does not ship in public/.', 'Add the file under public/, or drop app.favicon. Emitting the reference anyway would put a '
+        + 'link that 404s into every document the application serves.', BUILT_BY_EVERY_BUILD),
+    define('XE1501', 'Bundling failed after the module graph and types were accepted.', 'Read the bundler message in `message`. It usually names a syntax construct the target does not '
+        + 'support, rather than a Xeer rule.', BUILT_BY_EVERY_BUILD),
+    define('XE1602', 'A watch rebuild failed. The previously accepted generation is still serving.', 'Fix the edit named by `file`. The next quiet-window rebuild promotes automatically; no restart.', ['dev']),
+    define('XE1603', 'A rebuilt candidate compiled but failed to take over — usually a manifest or schema '
+        + 'change the running state cannot accept — and the last-good generation was restored.', 'Fix the manifest or schema change. To adopt an incompatible schema locally, stop dev and run '
+        + '`xeer state reset . --state dev --confirm <application>`.', ['dev']),
+    define('XE1604', 'The manifest could not be watched for changes, so edits to it will not rebuild the '
+        + 'preview. Everything already serving keeps serving.', 'On Linux this is normally an exhausted inotify allowance: raise `fs.inotify.max_user_watches` and '
+        + '`fs.inotify.max_user_instances`. Restart `xeer dev` afterwards.', ['dev']),
+    // `xeer build` runs the same verification `preview`, `test` and `deploy` gate on, against the
+    // artifact it has just written, so these four codes are build surfaces too: a build that cannot
+    // be previewed is reported as a failed build rather than a success (issue #56).
+    define('XE1700', 'No verifiable build artifact was found for preview.', 'Run `xeer build` first; preview never compiles.', ['build', 'preview', 'test', 'deploy', 'state']),
+    define('XE1701', 'The artifact, its latest pointer, or its server source map is malformed.', 'Rebuild with `xeer build`. Do not hand-edit anything under .xeer/build/. If a fresh build '
+        + 'reports this itself, it is a compiler defect: report it with the diagnostic.', ['build', 'preview', 'test', 'deploy', 'state']),
+    define('XE1702', 'The artifact does not match its own content-addressed identity or schema identity.', 'Rebuild. A mismatch means the output was mutated after it was written.', ['build', 'preview', 'test', 'deploy', 'state']),
+    define('XE1703', 'An artifact blob is missing, the wrong size, or hashes differently than its receipt.', 'Rebuild. The build output is incomplete or corrupted.', ['build', 'preview', 'test', 'deploy', 'state']),
+    define('XE1704', 'The artifact preview server failed to start or crashed.', 'Read `message`. Re-run `xeer build`, then preview again.', ['preview']),
+    define('XE1705', 'The latest build is stale: source files recorded in the artifact have changed on '
+        + 'disk since it was made, so running it would run code the project no longer has. Compared by '
+        + 'content hash, never by timestamp. `message` names the changed files.', 'Run `xeer build`. `xeer deploy` and `xeer test` build for you, so this means the build is older '
+        + 'than the edit — most often `xeer preview`, which runs the last verified artifact and never '
+        + 'compiles.', ['build', 'preview', 'test', 'deploy']),
+    define('XE1801', 'A state command was invoked without a valid --state selector.', 'Pass `--state dev`, `--state preview`, or `--state test`. The three modes never share a root.', ['state']),
+    define('XE1810', 'A destructive state command was invoked without --confirm.', 'Pass `--confirm <application>` using the manifest `name` exactly.', ['state']),
+    define('XE1811', 'The --confirm value does not match the application name.', 'Use the manifest `name` verbatim; the guard is exact-match by design.', ['state']),
+    define('XE1812', 'The local state lease for that project and mode could not be acquired, or is held by '
+        + 'a live process. Two concurrent `xeer test` runs in one project report this rather than racing.', 'Stop the other `xeer dev`/`xeer preview`/`xeer test` for this project and retry.', ['dev', 'preview', 'test', 'state']),
+    define('XE1813', 'The resolved state directory escapes its Xeer-owned project or local-data container, '
+        + 'or traverses a link.', 'Remove the link under .xeer/ (or the Xeer/state local-data directory on an overlong Windows path) and retry.', ['dev', 'preview', 'test', 'state']),
+    define('XE1814', 'A local state operation failed for an underlying filesystem reason.', 'Read `message`. Usually permissions or a partially removed .xeer/ directory.', ['dev', 'preview', 'test', 'state']),
+    define('XE1820', 'No `xeer dev`/`xeer preview` server owns that mode\'s state in that directory, or it '
+        + 'has not published its address yet. Local state lives in a Durable Object, so only the running '
+        + 'runtime can read or write it.', 'Start `xeer dev` (or `xeer preview`) in that directory and re-run, or pass a deployed application '
+        + 'name, appId, or URL instead.', ['export', 'import']),
+    define('XE1840', 'No `xeer dev`/`xeer preview` server is running for that directory, so its database '
+        + 'cannot be reached. The database lives inside a Durable Object; the running runtime is the only '
+        + 'thing that can read it consistently.', 'Start `xeer dev` (or `xeer preview`) in that directory and re-run.', ['db']),
+    define('XE1841', 'The running server published no admin session secret, so its database surface is '
+        + 'not reachable. The secret is minted per run and shared through the state lease.', 'Restart the server with a build that publishes one; a server older than this CLI does not.', ['db']),
+    define('XE1842', 'The server answered the database request with a protocol this CLI does not know.', 'The CLI and the running server are different versions. Restart the server from this checkout.', ['db']),
+    define('XE1821', 'The export file could not be read or written.', 'Read `message`: usually a missing path or permissions. `--out` creates parent directories.', ['export', 'import']),
+    define('XE1822', 'The document is not a usable xeer.state-export.v0 export: wrong protocol, or it '
+        + 'contradicts itself (counts, schema, or an encoded value).', 'Import the unmodified file `xeer export --out` produced. `detail.code` names the exact defect.', ['export', 'import']),
+    define('XE1823', '`xeer import` was pointed at a deployed application. It writes local dev and '
+        + 'preview state only; a deployed import needs a write-scoped grant and a pre-import snapshot.', 'Import into `xeer dev`/`xeer preview` state (`--state dev`), verify there, and `xeer deploy`.', ['import']),
+    define('XE1824', 'The runtime refused the transfer. `detail.code` is the reason: '
+        + 'state_import_schema_mismatch, state_import_application_mismatch, state_import_record_invalid, '
+        + 'or state_export_too_large.', 'For a schema mismatch, `detail.expected` and `detail.found` carry both schema identities: check '
+        + 'out the schema the export came from, import there, and let the compatible-change path carry the '
+        + 'data forward, or re-export from the current schema. There is no forced import.', ['export', 'import']),
+    define('XE1825', 'The command was invoked without a usable target, without the export file, or with a '
+        + '--state value other than dev or preview.', 'Pass `<preview-url|app>` or `--state dev|preview [directory]`; `xeer import` also needs the file.', ['export', 'import']),
+    define('XE1900', 'xeer test found no test files.', 'Create tests/<name>.test.ts importing test, as, and expect from @impetik/xeer/test. '
+        + '`xeer new` scaffolds a passing suite to copy.', ['test']),
+    define('XE1901', 'A test file could not be compiled.', 'Read `message`: it is the bundler error for that file. Test files may import '
+        + '@impetik/xeer/test, @impetik/xeer/shared, and project-relative modules.', ['test']),
+    define('XE1902', 'The test runtime failed to start.', 'Not a test failure. Run `xeer build` and `xeer doctor` — the artifact or the local workerd '
+        + 'toolchain is the problem.', ['test']),
+    define('XE1903', 'A test file threw while loading, so none of its tests ran. Other files still run.', 'Move work out of module scope and into a test body; only test registration belongs at the top level.', ['test']),
+    define('XE1904', 'An assertion failed. The failure carries `matcher`, `expected`, `actual`, and the '
+        + 'project-relative test location.', 'Decide which side is wrong. If the application is wrong, fix it and re-run; if the expectation is '
+        + 'wrong, fix the test. Never delete the assertion to go green.', ['test']),
+    define('XE1905', 'A test threw, including a call that was refused when the test did not expect it. '
+        + '`operation` names the persona, operation, status, and runtime error code.', 'When the refusal is the point, wrap the call in expectFailure(). A refused workspace-scoped call '
+        + "usually means the persona's declared membership does not contain the workspace the operation "
+        + "names: pass it with as({ name, workspaceIds }).", ['test']),
+    define('XE1906', 'A test exceeded its 20 second budget. The remaining tests still run.', 'Remove the wait: tests run against a local runtime, so a timeout means an unresolved promise or an '
+        + 'operation that never returns, not a slow machine.', ['test']),
+    define('XE2001', 'An inspector command was invoked without a target.', 'Pass the preview URL from the dev/preview `preview.ready` event, or a deployed application name, '
+        + 'appId, or URL.', ['inspect', 'state']),
+    define('XE2002', 'The inspector request itself failed: a local dev/preview inspector that answered '
+        + 'a non-2xx status or no JSON, or a control plane that refused the proxied read, in which case '
+        + 'the read never reached the application. An application that refused the read is XE2004.', 'Confirm the preview is still running and the URL matches the current `preview.ready` event. For a '
+        + 'deployed read, `message` carries the control plane\'s own refusal.', ['inspect', 'state']),
+    define('XE2003', 'No deployed application matched the inspector target for the signed-in builder.', 'Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with '
+        + '`xeer auth status` that you are signed in as its owner.', ['inspect', 'state']),
+    define('XE2004', 'The deployed application refused the read itself, and the control plane forwarded '
+        + "its answer. The application's own runtime code, its errorId, and the cause are in `message`, "
+        + 'and in `detail` as `code`, `errorId`, and `appId`.', 'Dispatch on `detail.code`, not on the wording. `state_bootstrap_failed` means the application '
+        + 'state never bootstrapped, so the read never ran: fix the cause named in `message` and redeploy. '
+        + '`state_unavailable` means the read never reached the state object at all — most often a '
+        + 'brand-new application whose state namespace is not dispatchable yet — so there is nothing to '
+        + 'fix: wait out the advertised retry and read again. '
+        + "Quote `detail.errorId` when correlating with the Worker's console output.", ['inspect', 'state', 'export']),
+    define('XE3001', 'xeer new could not scaffold the project — most often a non-empty target directory.', 'Choose an empty or non-existent directory.', ['new']),
+    define('XE3002', '`--template` named a scaffold that does not exist. Refused before the target '
+        + 'directory is read, so nothing was written.', 'Use one of the names the message lists, or omit --template for the default. `xeer --help` '
+        + 'describes each template.', ['new']),
+    define('XE3101', 'Agent setup check found one or more generated files missing or stale. No files were written.', 'Run `xeer agent setup`, then repeat `xeer agent setup --check --json`.', ['agent']),
+    define('XE3102', 'Agent setup found a path owned by the user or another tool. The entire write was refused.', 'Move, rename, or deliberately remove the conflicting path; setup never overwrites an unowned file.', ['agent']),
+    define('XE3103', '`--target` named an agent adapter that Xeer does not support.', 'Use auto, agents, claude, codex, cursor, vscode, or mcp.', ['agent']),
+    define('XE4001', 'A doctor check failed. `hint` carries the check details as JSON, and result.checks '
+        + 'lists every check with its id and status.', 'Fix the environment problem the failing check names. Doctor never edits the project.', ['doctor']),
+    define('XE5000', 'An auth subcommand was invoked with wrong arguments.', 'Use `xeer auth <login|status|logout|as|clear>`; `auth as` takes alice or bob.', ['auth']),
+    define('XE5001', 'The --control-url value is not an exact HTTP(S) origin, or is plain HTTP off localhost.', 'Pass an origin such as https://control.example.com with no path.', ['auth', 'deploy']),
+    define('XE5002', 'No valid builder credential is stored.', 'A human must run `xeer auth login` and approve the shown code. An agent cannot complete sign-in.', ['auth', 'deploy']),
+    define('XE5004', 'The control plane returned a response the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['auth']),
+    define('XE5005', 'The device authorization expired before sign-in completed.', 'Run `xeer auth login` again and approve promptly.', ['auth']),
+    define('XE5008', 'The stored CLI credential file is unreadable or invalid.', 'Run `xeer auth logout` and sign in again.', ['auth', 'deploy']),
+    define('XE5009', 'An auth command failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['auth']),
+    define('XE5101', 'The deployment Worker module could not be constructed from the artifact.', 'Re-run `xeer build` and inspect the artifact; the build output is incomplete.', ['deploy']),
+    define('XE5102', 'The control plane rejected the deployment or answered without a usable JSON envelope.', 'Read `message`: it carries the control-plane error. Check sign-in and that the project name is claimable.', ['deploy']),
+    define('XE5103', 'The deployment was accepted but the deployed runtime never became ready.', 'The upload succeeded; the runtime did not. Retry, then report it — the artifact is already recorded.', ['deploy']),
+    define('XE5104', 'The deployment serves assets but authenticated requests fail.', 'A platform identity problem, not an application one. Report it with the diagnostic message.', ['deploy']),
+    define('XE5105', 'The --environment value is not a deployable scope.', 'Pass prod, production, or preview. `dev` is a local-only scope that `xeer env pull` writes to a '
+        + 'gitignored file; no deployment ever injects it.', ['deploy']),
+    define('XE5106', 'A capability the manifest declares could not be provisioned. Either the control '
+        + 'plane could not create or adopt the backing resource (a per-app R2 bucket for "storage"), it is '
+        + 'not configured to provision at all, or it does not support that capability name. Nothing was '
+        + 'activated: the previous version is still serving.', 'Retry the deployment — provisioning is adopt-or-create, so a half-finished attempt heals on the '
+        + 'next one. A capability the control plane does not recognise is not retryable: remove it from '
+        + '`capabilities` in xeer.app.json, or deploy against a control plane that supports it. `message` '
+        + 'carries the control plane\'s own reason.', ['deploy', 'promote', 'rollback']),
+    define('XE5107', 'The build `xeer deploy` runs before uploading failed, so nothing was deployed and '
+        + 'the previously deployed version is still serving. The compiler\'s own diagnostics follow this '
+        + 'one in `diagnostics`.', 'Repair the diagnostics that follow — they are exactly what `xeer build` reports — and deploy '
+        + 'again. Deploy never falls back to the last successful build.', ['deploy']),
+    define('XE5109', 'Deployment failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['deploy']),
+    define('XE5111', 'The appId declared in xeer.project.json is owned by a different builder, so the '
+        + 'control plane refused the deployment.', 'Run `xeer link --new` to fork this checkout into a new app you own, or `xeer link` to attach it to '
+        + 'one of yours. A clone of someone else\'s project cannot silently take over their app.', ['deploy']),
+    define('XE5112', 'The builder is at their apps-per-builder quota, so the control plane refused to '
+        + 'create the app this deployment would have claimed.', 'This quota is a standing cap and does not lift on its own. Run `xeer link` to deploy into an app '
+        + 'you already own, or ask the Xeer team to raise it. `message` states the quota and your usage.', ['deploy']),
+    define('XE5113', 'The builder has spent their hourly or daily deploy quota.', 'Retry after the reset `message` states — it is the exact moment a slot frees, not a fixed backoff. '
+        + 'Failed deployments count toward the quota, so a fix-and-retry loop spends it too.', ['deploy']),
+    define('XE5120', 'xeer.project.json exists but is unusable: not JSON, not an object, the wrong '
+        + '`format`, or without a valid `appId`.', 'Run `xeer link --app <appId>` to rewrite it, or `xeer link --new` to mint a fresh identity. A '
+        + 'present-but-broken file is never repaired by guessing, because that would fork the app.', ['deploy', 'link', 'dev', 'preview', 'test', 'doctor']),
+    define('XE5121', 'The checked-in xeer.project.json and the local .xeer/project.json cache name '
+        + 'different appIds.', 'The checked-in file wins. `xeer link --app <declared appId>` re-points the cache, or '
+        + '`xeer link --new` deliberately forks this checkout.', ['deploy', 'link', 'dev', 'preview', 'test', 'doctor']),
+    define('XE5122', 'An appId is malformed, or `xeer link` was given both --app and --new.', 'Run `xeer link` with no flags to list the appIds you own, then pass exactly one of --app or --new.', ['link', 'deploy']),
+    define('XE5123', 'The signed-in builder does not own a project with that appId.', 'Run `xeer link` to list your projects, or `xeer link --new` to create a new app for this checkout.', ['link']),
+    define('XE5124', 'The control plane returned an invalid project or project list.', 'Retry; if it persists the control plane is unreachable or misconfigured. Not a project defect.', ['link']),
+    define('XE5129', 'xeer link failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['link']),
+    define('XE5130', 'An `xeer env` invocation is wrong: an unknown --environment, a missing name or '
+        + 'value, or no usable xeer.app.json in the target directory.', 'Read `message` and the usage it quotes. --environment takes prod, preview, or dev, and the command '
+        + 'must run inside a Xeer project.', ['env']),
+    define('XE5131', 'The control plane rejected the environment-variable request.', 'Read `message`: it carries the control-plane error and hint. Check sign-in and that you own the '
+        + 'project.', ['env']),
+    define('XE5132', 'The control plane returned an environment payload the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['env']),
+    define('XE5133', 'A closed-beta quota refused the environment-variable request: `xeer env set` claims '
+        + 'the project on first use, so it is capped by the same apps-per-builder quota as `xeer deploy`.', 'Set the value on an app you already own — `xeer link` lists them — or ask the Xeer team to raise the '
+        + 'quota. `message` states the quota, your usage, and any reset.', ['env']),
+    define('XE5139', 'xeer env failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['env']),
+    define('XE5140', 'An `xeer deployments` invocation is wrong: an unusable --limit, or a directory that '
+        + 'declares no app identity.', 'Read `message`. --limit takes a positive integer up to 200. In a directory with no appId, run '
+        + '`xeer deploy` or `xeer link` first, or name the app: `xeer deployments <app>`.', ['deployments']),
+    define('XE5141', 'The control plane rejected the deployment-history request.', 'Read `message`: it carries the control-plane error and hint. Check sign-in and that you own the app.', ['deployments']),
+    define('XE5142', 'The control plane returned a deployment listing the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['deployments']),
+    define('XE5143', 'No app matched the reference for the signed-in builder.', 'Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with '
+        + '`xeer auth status` that you are signed in as its owner.', ['deployments']),
+    define('XE5149', 'xeer deployments failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['deployments']),
+    define('XE5160', 'An `xeer rollback` invocation is wrong: a missing or malformed artifact id, an '
+        + 'unknown --environment, or a directory that declares no app identity.', 'An artifact id is `sha256:` followed by 64 hex characters — copy it from the ARTIFACT column of '
+        + '`xeer deployments <app>`. --environment takes prod or preview; `dev` is never deployed.', ['rollback']),
+    define('XE5161', 'The control plane refused the rollback.', 'Read `message` and `hint`: they carry the control-plane error verbatim. A rollback is a deployment, '
+        + 'so it can also be refused by the deploy quota.', ['rollback']),
+    define('XE5162', 'The control plane returned a rollback result the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['rollback']),
+    define('XE5163', 'No app matched the reference for the signed-in builder, or it has already been '
+        + 'deleted.', 'Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with '
+        + '`xeer auth status` that you are signed in as its owner.', ['rollback']),
+    define('XE5164', 'This application has no completed deployment of that artifact — it belongs to '
+        + 'another project, was never deployed here, or its deployment failed.', 'Run `xeer deployments <app>` and roll back to an artifact listed there. Only a deployment that '
+        + 'completed can be rolled back to.', ['rollback']),
+    define('XE5169', 'xeer rollback failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['rollback']),
+    define('XE5170', 'The --from-artifact value is not an artifact id.', 'An artifact id is `sha256:` followed by 64 hex characters — copy it from the ARTIFACT column of '
+        + '`xeer deployments <app>`. Omit the flag to promote whatever preview is currently serving.', ['promote']),
+    define('XE5171', 'The control plane refused the promotion.', 'Read `message` and `hint`: they carry the control-plane error verbatim. A promotion is a production '
+        + 'deployment, so it can also be refused by the deploy quota.', ['promote']),
+    define('XE5172', 'The control plane returned a promotion result the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['promote']),
+    define('XE5173', 'No app matched the reference for the signed-in builder, or it has already been '
+        + 'deleted.', 'Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with '
+        + '`xeer auth status` that you are signed in as its owner.', ['promote']),
+    define('XE5174', 'This application has no completed deployment of that artifact — it belongs to '
+        + 'another project, was never deployed here, or its deployment failed.', 'Run `xeer deployments <app>` and promote an artifact listed there. Only a deployment that '
+        + 'completed can be promoted.', ['promote']),
+    define('XE5175', 'The application has no completed preview deployment, so there is nothing to promote.', 'Run `xeer deploy --environment preview` to put a version on the preview origin first, or name the '
+        + 'version explicitly with `--from-artifact sha256:…`.', ['promote']),
+    define('XE5176', 'The --receipt value is not a complete review receipt id.', 'Run `xeer test`, deploy the unchanged project with `--environment preview`, and copy the complete '
+        + '`review_…` id printed by that deployment.', ['promote']),
+    define('XE5177', '--receipt and --from-artifact were supplied together.', 'Use --receipt for the reviewed path, or --from-artifact for the separate direct human override.', ['promote']),
+    define('XE5179', 'xeer promote failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['promote']),
+    define('XE5150', 'A lifecycle invocation is wrong: `xeer delete` without --confirm, or a directory '
+        + 'that declares no app identity.', 'Deleting an application is permanent, so it requires its exact name: `xeer delete <app> --confirm '
+        + '<app>`. In a directory with no appId, name the app instead of relying on the directory.', ['disable', 'enable', 'delete']),
+    define('XE5151', 'The control plane refused the lifecycle change — most often because --confirm does '
+        + 'not match the application name, or because it cannot delete the deployed Worker.', 'Read `message` and `hint`: they carry the control-plane error verbatim. A confirmation must equal '
+        + 'the name in xeer.app.json exactly.', ['disable', 'enable', 'delete']),
+    define('XE5152', 'The control plane returned a lifecycle result the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['disable', 'enable', 'delete']),
+    define('XE5153', 'No app matched the reference for the signed-in builder, or it has already been '
+        + 'deleted.', 'Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with '
+        + '`xeer auth status` that you are signed in as its owner. A deleted app never resolves again.', ['disable', 'enable', 'delete']),
+    define('XE5159', 'A lifecycle command failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['disable', 'enable', 'delete']),
+    // `xeer token` — service tokens (#62). Builder-facing but deliberately absent from the quickstart
+    // command list: only a service builder ever issues one.
+    define('XE5180', 'An `xeer token` invocation is wrong: an unknown action, a missing or unusable --name, '
+        + 'a token id that is not an `xstid_` value, or no interactively signed-in builder.', 'Issuing a service token requires `xeer auth login` first — the browser approval is the root of every '
+        + 'credential an account holds, so a service token cannot mint another. Take ids from `xeer token ls`; '
+        + 'the id is the `xstid_` value, never the secret.', ['token']),
+    define('XE5181', 'The control plane refused the service-token request.', 'Read `message` and `hint`: they carry the control-plane error verbatim. A service token cannot issue '
+        + 'another one, and a disabled builder is refused every credential they hold.', ['token']),
+    define('XE5182', 'The control plane returned a service-token response the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['token']),
+    define('XE5189', 'xeer token failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['token']),
+    define('XE5190', 'An `xeer domains` invocation has a missing or invalid hostname or subcommand.', 'Use `xeer domains add|ls|status|remove`. A hostname is fully qualified ASCII without a scheme, '
+        + 'port, path, or wildcard, for example `app.example.com`.', ['domains']),
+    define('XE5191', 'The control plane refused a custom-domain request.', 'Read `message` and `hint`; they carry the owner-scoped control-plane refusal.', ['domains']),
+    define('XE5192', 'The control plane returned a domains payload the CLI will not trust.', 'Retry; if it persists, the control plane and CLI versions are incompatible or the service is misconfigured.', ['domains']),
+    define('XE5193', 'No application or attached domain matched the owner-scoped reference.', 'Check the application reference and hostname, then confirm `xeer auth status` shows its owner.', ['domains']),
+    define('XE5194', 'The hostname is unavailable, reserved, at the user quota, or awaiting earlier cleanup.', 'Read `message` and `hint`. Remove an unused hostname, finish cleanup, or choose a hostname you control.', ['domains']),
+    define('XE5195', 'The application has no successful production deployment.', 'Run `xeer deploy` first. A custom hostname is never attached to an application with no production Worker.', ['domains']),
+    define('XE5196', 'Cloudflare for SaaS is unavailable or rejected the provider operation.', 'Retry. If it persists, the operator must check the SaaS zone, fallback origin, runtime token, and provider status.', ['domains']),
+    define('XE5197', 'Routing is detached, but Cloudflare hostname or certificate cleanup remains pending.', 'Run the same `xeer domains remove` command again. Reattachment stays blocked until cleanup is confirmed.', ['domains']),
+    define('XE5199', 'xeer domains failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['domains']),
+];
+function indexDefinitions(definitions) {
+    const indexed = {};
+    for (const definition of definitions) {
+        if (Object.hasOwn(indexed, definition.code)) {
+            throw new Error(`Duplicate diagnostic code: ${definition.code}`);
+        }
+        indexed[definition.code] = definition;
+    }
+    return indexed;
+}
+// Index imperatively instead of using Object.fromEntries: duplicate codes are a contract violation,
+// never a last-definition-wins overwrite. Keeping the ordered source list exported also lets the
+// conformance suite prove uniqueness before any generated reference consumes the index.
+export const DIAGNOSTICS = Object.freeze(indexDefinitions(DIAGNOSTIC_DEFINITIONS));
+/** Every documented code, ascending. */
+export const DIAGNOSTIC_CODES = Object.freeze(Object.keys(DIAGNOSTICS).sort());
+export function diagnosticDefinition(code) {
+    return DIAGNOSTICS[code];
+}
+/** The family a code belongs to, matched on its numeric prefix. */
+export function diagnosticFamily(code) {
+    return DIAGNOSTIC_FAMILIES.find((family) => code.startsWith(family.prefix));
+}
+function escapeCell(text) {
+    return text.replaceAll('|', '\\|');
+}
+/**
+ * Renders the agent-facing diagnostics reference. The checked-in copy under
+ * `.agents/skills/xeer/references/` is this function's canonical output; a test fails when
+ * the two diverge, so the reference cannot drift from the catalogue.
+ */
+export function renderDiagnosticsReference() {
+    const lines = [
+        '# Xeer diagnostic codes',
+        '',
+        '<!-- Generated from packages/spec/src/diagnostics.ts by `pnpm generate:agent-reference`. Do not edit. -->',
+        '',
+        'Codes are stable; messages are not. Dispatch on `code`, read `message` and `span` for the location,',
+        'and treat `hint` as the platform\'s own suggested edit. Every code below is emitted by the compiler or',
+        'CLI in this repository.',
+        '',
+        'A diagnostic is always:',
+        '',
+        '```ts',
+        'interface Diagnostic {',
+        '  code: string;                 // XE####, stable',
+        '  severity: \'error\' | \'warning\' | \'info\';',
+        '  message: string;              // human wording, free to change',
+        '  file?: string;                // project-relative POSIX path, never absolute',
+        '  span?: { line: number; column: number; length?: number };  // 1-based',
+        '  hint?: string;                // suggested edit',
+        '}',
+        '```',
+        '',
+        'The "Seen in" column lists the commands whose JSON can carry the code. `check` diagnostics also appear',
+        'in `build` and `dev`, because both run the same manifest and analysis stages first.',
+    ];
+    for (const family of DIAGNOSTIC_FAMILIES) {
+        const members = DIAGNOSTIC_DEFINITIONS.filter((definition) => definition.prefix === family.prefix);
+        if (!members.length)
+            continue;
+        lines.push('', `## ${family.title} (${family.prefix}xx)`, '', family.summary, '');
+        lines.push('| Code | Seen in | Means | Repair |', '| --- | --- | --- | --- |');
+        for (const member of members) {
+            lines.push(`| \`${member.code}\` | ${member.surfaces.join(', ')} `
+                + `| ${escapeCell(member.means)} | ${escapeCell(member.repair)} |`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** Markdown used by the public docs page and the installed offline docs bundle. */
+export function renderDiagnosticsDocsPage() {
+    const definitions = Object.values(DIAGNOSTICS);
+    const lines = [
+        '# Diagnostics reference',
+        '',
+        `Every diagnostic Xeer emits carries a stable \`XE####\` code. There are ${definitions.length} of them, and`,
+        'this page is generated from the same catalogue the compiler and CLI emit from, so it cannot fall behind.',
+        '',
+        '**Codes are stable; messages are not.** Dispatch on `code`, read `message` and `span` for the location,',
+        'and treat `hint` as the platform\'s own suggested edit.',
+        '',
+        '```ts',
+        'interface Diagnostic {',
+        '  code: string;                 // XE####, stable',
+        "  severity: 'error' | 'warning' | 'info';",
+        '  message: string;              // human wording, free to change',
+        '  file?: string;                // project-relative POSIX path, never absolute',
+        '  span?: { line: number; column: number; length?: number };  // 1-based',
+        '  hint?: string;                // suggested edit',
+        '}',
+        '```',
+        '',
+        'Every command prints these as JSON with `--json`; see [Building with AI agents](/guides/agents).',
+        'The "Seen in" column lists the commands whose output can carry the code. `check` diagnostics also',
+        'appear in `build` and `dev`, because both run the same manifest and analysis stages first.',
+    ];
+    const escapeCell = (text) => text.replaceAll('|', '\\|');
+    for (const family of DIAGNOSTIC_FAMILIES) {
+        const members = definitions.filter((definition) => definition.prefix === family.prefix);
+        if (members.length === 0)
+            continue;
+        lines.push('', `## ${family.title} (${family.prefix}xx)`, '', family.summary, '');
+        lines.push('| Code | Seen in | Means | Repair |', '| --- | --- | --- | --- |');
+        for (const member of members) {
+            lines.push(`| \`${member.code}\` | ${member.surfaces.join(', ')} `
+                + `| ${escapeCell(member.means)} | ${escapeCell(member.repair)} |`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}

package/vendor/spec/docs.d.ts

@@ -0,0 +1,21 @@
+export declare const XEER_DOCS_PROTOCOL: "xeer.docs.v0";
+export declare const XEER_DOCS_ORIGIN: "https://docs.xeer.run";
+export interface XeerDocsPageDefinition {
+    readonly path: string;
+    readonly source: string | null;
+    readonly generate?: 'diagnostics';
+    readonly layout?: 'home';
+    readonly title: string;
+    readonly heading?: string;
+    readonly description: string;
+}
+export interface XeerDocsSectionDefinition {
+    readonly title: string | null;
+    readonly pages: readonly XeerDocsPageDefinition[];
+}
+/** Canonical page registry shared by the site, packaged Markdown, search, and MCP resources. */
+export declare const XEER_DOCS_SECTIONS: readonly XeerDocsSectionDefinition[];
+export declare const XEER_DOCS_PAGES: XeerDocsPageDefinition[];
+export declare function xeerDocsMarkdownPath(page: Pick<XeerDocsPageDefinition, 'path'>): string;
+/** Small deterministic heading index; fenced examples never become accidental headings. */
+export declare function xeerDocsHeadings(markdown: string): string[];

package/vendor/spec/docs.js

@@ -0,0 +1,57 @@
+export const XEER_DOCS_PROTOCOL = 'xeer.docs.v0';
+export const XEER_DOCS_ORIGIN = 'https://docs.xeer.run';
+/** Canonical page registry shared by the site, packaged Markdown, search, and MCP resources. */
+export const XEER_DOCS_SECTIONS = [
+    { title: null, pages: [
+            { path: '/', source: 'index.md', layout: 'home', title: 'Xeer', heading: 'Overview',
+                description: 'Xeer is a framework for building and shipping full-stack apps. A typed server, a reactive client, a built-in test runner, and one command to deploy.' },
+        ] },
+    { title: 'Start here', pages: [
+            { path: '/quickstart', source: 'quickstart.md', title: 'Quickstart', description: 'Create, run, test, and deploy a Xeer app in five minutes.' },
+            { path: '/guides/project-structure', source: 'guides/project-structure.md', title: 'Project structure', description: 'What `xeer new` writes, and what each file is for.' },
+        ] },
+    { title: 'Guides', pages: [
+            { path: '/guides/capabilities', source: 'guides/capabilities.md', title: 'Capabilities', description: 'The powers an app declares, and why an undeclared one does not exist.' },
+            { path: '/guides/server', source: 'guides/server.md', title: 'Server functions and the database', description: 'Queries, mutations, endpoints, and the typed table API.' },
+            { path: '/guides/storage', source: 'guides/storage.md', title: 'Storage', description: 'Private file storage per app: the `ctx.storage` surface, keys, browser uploads, limits, and what happens on deploy.' },
+            { path: '/guides/client', source: 'guides/client.md', title: 'The client', description: 'Reading data with hooks, writing it with mutations, and staying in sync.' },
+            { path: '/guides/live-updates', source: 'guides/live-updates.md', title: 'Live updates', description: 'How every open client sees a change the moment it lands.' },
+            { path: '/guides/auth', source: 'guides/auth.md', title: 'Auth', description: 'Two separate identities: your builder account, and your app\'s own users.' },
+            { path: '/guides/local-development', source: 'guides/local-development.md', title: 'Local development', description: 'The dev server, local data, and the personas that make authorization exercisable offline.' },
+            { path: '/guides/testing', source: 'guides/testing.md', title: 'Testing', description: 'The built-in test runner, and asserting authorization instead of assuming it.' },
+            { path: '/guides/env', source: 'guides/env.md', title: 'Environment variables and secrets', description: 'Storing configuration per environment, and reading it from `ctx.env`.' },
+            { path: '/guides/deploy', source: 'guides/deploy.md', title: 'Deploy, preview, promote, roll back', description: 'Shipping to a real URL, and the levers for changing what is live.' },
+            { path: '/guides/custom-domains', source: 'guides/custom-domains.md', title: 'Custom domains', description: 'Attach, validate, monitor, and safely remove a customer-owned hostname.' },
+            { path: '/guides/agents', source: 'guides/agents.md', title: 'Building with AI agents', description: 'The machine-readable surface: `--json` on every command, and the MCP server.' },
+        ] },
+    { title: 'Reference', pages: [
+            { path: '/reference/cli', source: 'reference/cli.md', title: 'CLI reference', description: 'Every `xeer` command, its options, and what it does.' },
+            { path: '/reference/manifest', source: 'reference/manifest.md', title: 'Manifest reference', description: 'Every field of `xeer.app.json`, with its exact rules.' },
+            { path: '/reference/diagnostics', source: null, generate: 'diagnostics', title: 'Diagnostics reference', description: 'Every stable `XE####` code the compiler and CLI emit, what it means, and how to repair it.' },
+        ] },
+    { title: null, pages: [
+            { path: '/faq', source: 'faq.md', title: 'FAQ', description: 'Access, infrastructure, limits, and the questions that come up first.' },
+        ] },
+];
+export const XEER_DOCS_PAGES = XEER_DOCS_SECTIONS.flatMap((section) => section.pages);
+export function xeerDocsMarkdownPath(page) {
+    return page.path === '/' ? '/index.md' : `${page.path}.md`;
+}
+/** Small deterministic heading index; fenced examples never become accidental headings. */
+export function xeerDocsHeadings(markdown) {
+    const headings = [];
+    let fenced = false;
+    for (const line of markdown.split(/\r?\n/u)) {
+        if (/^\s*```/u.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        const match = /^(#{1,3})\s+(.+?)\s*#*\s*$/u.exec(line);
+        if (!match || match[1] === '#')
+            continue;
+        headings.push(match[2].replace(/[`*_]/gu, '').trim());
+    }
+    return headings;
+}

package/vendor/spec/events.d.ts

@@ -0,0 +1,8 @@
+import { type DevEvent } from './types.js';
+export declare class DevEventWriter {
+    #private;
+    private readonly writeLine;
+    private readonly now;
+    constructor(writeLine: (line: string) => void, now?: () => Date);
+    emit<T>(type: string, data: T): DevEvent<T>;
+}