@mostra/protocol 0.0.0-stage → 0.1.0

package/src/capability.ts

@@ -0,0 +1,92 @@
+/**
+ * Capability links (D06, D97): the scopes a capability token grants and how long it lasts. A
+ * token is the authorization: whoever holds its link may do what its scopes allow, and nothing
+ * else limits an artifact or its viewers (D05).
+ */
+import * as z from "zod";
+import { wireRegistry } from "./wire-registry.ts";
+
+/**
+ * What a capability token allows (HY-03, D97):
+ * - `view`: open the artifact; every token has it.
+ * - `draft`: save answers and other field values.
+ * - `submit`: submit.
+ * - `review`: comment and choose.
+ * - `signal`: raise a signal for the host's attention (D10), which a waiting agent may act on.
+ * - `action:*`: run every server function; `action:<export>` runs that export of any
+ *   `"use server"` module; `action:<module path>#<export>` runs one function ID.
+ */
+export type CapabilityScope =
+  | "view"
+  | "draft"
+  | "submit"
+  | "review"
+  | "signal"
+  | `action:${string}`;
+
+/** The Zod schema of the `CapabilityScope` type. */
+export const CapabilityScope: z.ZodType<CapabilityScope> = z
+  .string()
+  .regex(/^(view|draft|submit|review|signal|action:(\*|[^\s#*]+(#[^\s#*]+)?))$/)
+  .register(wireRegistry, {
+    id: "CapabilityScope",
+    description:
+      "A capability token's scope: view, draft, submit, review, signal, action:*, action:<export> or action:<module path>#<export>.",
+  }) as z.ZodType<CapabilityScope>;
+
+/** Every scope at once: what a link minted without `scopes`, and every default link, carries. */
+export const ALL_SCOPES: readonly CapabilityScope[] = [
+  "view",
+  "draft",
+  "submit",
+  "review",
+  "signal",
+  "action:*",
+];
+
+/**
+ * A duration: a positive whole number and a unit, `s`, `m`, `h` or `d` (`30m`, `24h`, `7d`), as
+ * INTERFACES §1 writes durations in flags and manifests.
+ */
+export type Duration = `${number}${"s" | "m" | "h" | "d"}`;
+
+/** The Zod schema of the `Duration` type. */
+export const Duration: z.ZodType<Duration> = z
+  .string()
+  .regex(/^[1-9][0-9]{0,8}[smhd]$/)
+  .register(wireRegistry, {
+    id: "Duration",
+    description: "A duration: a positive whole number and s, m, h or d, such as 30m, 24h or 7d.",
+  }) as z.ZodType<Duration>;
+
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
+
+/** The length of a `Duration` in milliseconds. */
+export function durationMs(duration: Duration): number {
+  const unit = duration.slice(-1) as keyof typeof UNIT_MS;
+  return Number(duration.slice(0, -1)) * UNIT_MS[unit];
+}
+
+/**
+ * The scopes a token holds after normalization: `view` added, duplicates removed, sorted, so equal
+ * grants compare equal.
+ */
+export function normalizeScopes(scopes: readonly CapabilityScope[]): CapabilityScope[] {
+  return [...new Set<CapabilityScope>(["view", ...scopes])].sort();
+}
+
+/**
+ * Whether `scopes` grant `required`. A plain scope must be held as written. An action scope
+ * `action:<module path>#<export>` is granted by `action:*`, by `action:<export>` and by itself.
+ */
+export function scopeAllows(
+  scopes: readonly CapabilityScope[],
+  required: CapabilityScope,
+): boolean {
+  if (scopes.includes(required)) return true;
+  if (!required.startsWith("action:")) return false;
+  if (scopes.includes("action:*")) return true;
+  const functionId = required.slice("action:".length);
+  const hash = functionId.lastIndexOf("#");
+  return hash >= 0 && scopes.includes(`action:${functionId.slice(hash + 1)}`);
+}

package/src/diagnostics/codes/a11y.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostic codes of the A11Y area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the A11Y area, in the order they were added. */
+export const a11yDiagnosticCodes = [
+  "MOSTRA_A11Y_SERIOUS",
+  "MOSTRA_A11Y_MINOR",
+  // gen:codes
+] as const;
+
+/** The codes of the A11Y area. */
+export type A11yDiagnosticCode = (typeof a11yDiagnosticCodes)[number];
+
+/** The A11Y area's catalog entries. */
+export const a11yDiagnostics: AreaCatalog<A11yDiagnosticCode> = {
+  MOSTRA_A11Y_SERIOUS: {
+    severity: "warning",
+    phase: "a11y",
+    title: "Serious accessibility problem",
+    hint: "Read axe's description of the rule in the message; it names the elements it found.",
+    docs: {
+      explanation:
+        "axe-core found a problem it rates critical or serious, such as a button with no accessible name or text with too little contrast. The message names axe's rule and the elements; `count` says how many.",
+      fix: "Follow the rule's advice for each element named, for example add an `aria-label` to an icon button.",
+    },
+  },
+  MOSTRA_A11Y_MINOR: {
+    severity: "hint",
+    phase: "a11y",
+    title: "Minor accessibility problem",
+    hint: "Read axe's description of the rule in the message.",
+    docs: {
+      explanation:
+        "axe-core found a problem it rates moderate or minor. The message names axe's rule and the elements.",
+      fix: "Optionally follow the rule's advice.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/action.ts

@@ -0,0 +1,125 @@
+/**
+ * Diagnostic codes of the ACTION area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the ACTION area, in the order they were added. */
+export const actionDiagnosticCodes = [
+  "MOSTRA_ACTION_EXPORT_INVALID",
+  "MOSTRA_ACTION_UNSERIALIZABLE",
+  "MOSTRA_ACTION_THREW",
+  "MOSTRA_ACTION_UNKNOWN_FUNCTION",
+  "MOSTRA_ACTION_INTERRUPTED",
+  "MOSTRA_ACTION_CANCELLED",
+  "MOSTRA_ACTION_TOO_LARGE",
+  "MOSTRA_ACTION_RUN_NOT_FOUND",
+  "MOSTRA_ACTION_EVENT_INVALID",
+  // gen:codes
+] as const;
+
+/** The codes of the ACTION area. */
+export type ActionDiagnosticCode = (typeof actionDiagnosticCodes)[number];
+
+/** The ACTION area's catalog entries. */
+export const actionDiagnostics: AreaCatalog<ActionDiagnosticCode> = {
+  MOSTRA_ACTION_EXPORT_INVALID: {
+    severity: "error",
+    phase: "compile",
+    title: "Server module exports something other than an async function",
+    hint: 'Export only async functions from a "use server" module; move other exports to an ordinary module.',
+    docs: {
+      explanation:
+        'A module that starts with `"use server"` makes every export a server function the page can call. React\'s contract allows only async functions there. Mostra reports this code for any other export (a constant, a class, a non-async function, `export *`), naming the export.',
+      fix: "Make the function `async`, or move the value to a separate module without the directive and import it from both sides.",
+    },
+  },
+  MOSTRA_ACTION_UNSERIALIZABLE: {
+    severity: "error",
+    phase: "runtime",
+    title: "Server function argument or result outside React's serializable types",
+    hint: "Pass and return only plain objects, arrays, primitives, Map, Set, Date, typed arrays, FormData and promises; convert class instances to plain objects first.",
+    docs: {
+      explanation:
+        "Server function arguments and results cross a process boundary, so Mostra accepts exactly the types React documents for Server Functions (D54): strings, numbers, bigints, booleans, `undefined`, `null`, symbols registered with `Symbol.for`, arrays, `Map`, `Set`, typed arrays, `ArrayBuffer`, `Date`, `FormData`, plain objects, other server functions and promises. A result may also be an async iterable, whose items stream to the page. Mostra reports this code for anything else (a class instance, an `Error`, a `RegExp`, an object with a null prototype, a function that isn't a server function, an unregistered symbol, JSX) and names where in the value it is, such as `Argument 2 at .items[1]`. A promise in an argument that rejects fails the call the same way.",
+      fix: "Convert the value to the supported types before the call or the return: `{ ...instance }` or a mapping for class instances, `error.message` for errors and `regexp.source` for regular expressions.",
+    },
+  },
+  MOSTRA_ACTION_THREW: {
+    severity: "error",
+    phase: "runtime",
+    title: "Server function threw",
+    hint: "Read the run's log for the stack, then fix the server function or catch the error and return a result instead.",
+    docs: {
+      explanation:
+        "A server function threw while it ran. The page gets `{ code: \"MOSTRA_ACTION_THREW\", message }` with the thrown error's message (`useAction`'s `error`, or the rejected promise of a plain call); the stack goes to the action run's log, never to the page. When the error carried a diagnostic code of its own (a `MOSTRA_SECRET_MISSING`, say), that code is reported instead.",
+      fix: "Fix the cause in the function, or catch the error inside it and return a value the page can show. Mostra never retries a run by itself (D24); retry in your own code, or call the action again with a new key.",
+    },
+  },
+  MOSTRA_ACTION_UNKNOWN_FUNCTION: {
+    severity: "error",
+    phase: "runtime",
+    title: "No such server function in this version",
+    hint: "Publish the artifact again so the page and its server code come from the same version.",
+    docs: {
+      explanation:
+        "The page called a server function ID (`<module path>#<export>`) that the version's server bundle doesn't export. Pages call only functions their own build references, so this means a page and a worker of different versions, or a request written by hand.",
+      fix: 'Republish the artifact and reload the page. Call server functions by importing them from their `"use server"` module, never by ID.',
+    },
+  },
+  MOSTRA_ACTION_INTERRUPTED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Action run interrupted",
+    hint: "Check the run's effects at their provider, then start it again with a new key if it should run again.",
+    docs: {
+      explanation:
+        "The action run's worker crashed, ran out of memory, was stopped by the event-loop watchdog, or the instance stopped while the run was running. The run ends `failed` with the reason `interrupted`, and Mostra never retries it by itself (D24): an action that had already started a side effect, such as sending an email, may or may not have finished it.",
+      fix: "Look at the effect where it happens (the mail provider's sent folder, say) before running the action again. Pass the provider's own idempotency key from the action (for example, the run's key) so a repeated request can't act twice.",
+    },
+  },
+  MOSTRA_ACTION_CANCELLED: {
+    severity: "warning",
+    phase: "runtime",
+    title: "Action run cancelled",
+    hint: "Start the action again if it should still run.",
+    docs: {
+      explanation:
+        "The action run was cancelled from a page, and its `abortSignal` fired. The run ends `cancelled` when the action stops; an action that ignores the signal ends with whatever it returns.",
+      fix: "Nothing to fix. Pass `abortSignal` from `@mostra/server` to `fetch` and other cancellable calls so cancelling stops the work.",
+    },
+  },
+  MOSTRA_ACTION_TOO_LARGE: {
+    severity: "error",
+    phase: "runtime",
+    title: "Server function arguments or result too large",
+    hint: "Return or pass less data: page through it, or write it to artifact state or a live source instead.",
+    docs: {
+      explanation:
+        "A server function's serialized arguments, or an action run's serialized result, is over 16 MiB. A plain call or run with arguments that large is refused before it starts; a run whose result grows past the limit is stopped and ends `failed`.",
+      fix: "Send identifiers rather than whole documents, return a page of results at a time, or publish large data through a live source or artifact state, which the page reads on its own.",
+    },
+  },
+  MOSTRA_ACTION_RUN_NOT_FOUND: {
+    severity: "error",
+    phase: "runtime",
+    title: "No such action run",
+    hint: "Start the action again; the run ID names no run of this artifact.",
+    docs: {
+      explanation:
+        "A page asked for or cancelled an action run that this artifact doesn't have, or one started from another artifact.",
+      fix: "Use the run IDs `useAction` reports. A page that keeps run IDs itself should drop IDs from other artifacts.",
+    },
+  },
+  MOSTRA_ACTION_EVENT_INVALID: {
+    severity: "error",
+    phase: "runtime",
+    title: "Host event type or payload invalid",
+    hint: "Name the event `host.<name>` with 1 to 64 letters, digits, `.`, `_` and `-`, and keep its payload JSON of at most 64 KiB.",
+    docs: {
+      explanation:
+        "Server code called `emit(type, payload)` from `@mostra/server` with a type that isn't `host.` followed by a name, or a payload that isn't JSON or is larger than 64 KiB. The event is not appended; `emit` throws.",
+      fix: "Use a type such as `host.reply-sent` and a small JSON payload. Put larger data in artifact state or a live source and send its key in the event.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/artifact.ts

@@ -0,0 +1,137 @@
+/**
+ * Diagnostic codes of the ARTIFACT area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the ARTIFACT area, in the order they were added. */
+export const artifactDiagnosticCodes = [
+  "MOSTRA_ARTIFACT_NOT_FOUND",
+  "MOSTRA_ARTIFACT_SOURCE_MISSING",
+  "MOSTRA_ARTIFACT_SOURCE_UNREADABLE",
+  "MOSTRA_ARTIFACT_NO_ENTRY",
+  "MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS",
+  "MOSTRA_ARTIFACT_NO_PAGE",
+  "MOSTRA_ARTIFACT_DIR_NOT_EMPTY",
+  "MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN",
+  "MOSTRA_ARTIFACT_VERSION_NOT_FOUND",
+  "MOSTRA_ARTIFACT_VERSION_COLLECTED",
+  // gen:codes
+] as const;
+
+/** The codes of the ARTIFACT area. */
+export type ArtifactDiagnosticCode = (typeof artifactDiagnosticCodes)[number];
+
+/** The ARTIFACT area's catalog entries. */
+export const artifactDiagnostics: AreaCatalog<ArtifactDiagnosticCode> = {
+  MOSTRA_ARTIFACT_NOT_FOUND: {
+    severity: "error",
+    phase: "host",
+    title: "Artifact not found",
+    hint: "Check the artifact ID or source path, or list the home's artifacts with `mostra list`.",
+    docs: {
+      explanation:
+        "The artifact named by an ID or a source path doesn't exist in this home: the ID was never published here, or the path was never published.",
+      fix: "Use an ID or path from `mostra list`. A source that was never published becomes an artifact at its first `mostra publish`. A host that uses its own home sees only the artifacts published there.",
+    },
+  },
+  MOSTRA_ARTIFACT_SOURCE_MISSING: {
+    severity: "error",
+    phase: "publish",
+    title: "Artifact source missing",
+    hint: "Publish from the artifact's source path, or restore the directory the message names.",
+    docs: {
+      explanation:
+        "Publishing needs the artifact's source files. The path given, or the path the artifact was last published from, doesn't exist. Versions already published stay readable, because Mostra keeps a snapshot of their source in the home.",
+      fix: "Pass the path where the source lives now. Its manifest `id`, if it has one, keeps the artifact identity at the new path.",
+    },
+  },
+  MOSTRA_ARTIFACT_SOURCE_UNREADABLE: {
+    severity: "error",
+    phase: "publish",
+    title: "Artifact source can't be read",
+    hint: "Fix the file or directory the message names so your user can read it, then publish again.",
+    docs: {
+      explanation:
+        "Mostra couldn't read a file of the artifact's source: permissions, a file that disappeared while it was copied, or two names that are the same after Unicode normalization. Nothing was published.",
+      fix: "Make the named file readable, rename one of two clashing names, or exclude the file with `.mostraignore` in the artifact's root.",
+    },
+  },
+  MOSTRA_ARTIFACT_NO_ENTRY: {
+    severity: "error",
+    phase: "manifest",
+    title: "No entry file",
+    hint: "Add `index.tsx` or `index.mdx` to the directory, or publish a single `.tsx` or `.mdx` file.",
+    docs: {
+      explanation:
+        "An artifact is a single `.tsx`, `.jsx` or `.mdx` file, or a directory whose entry is `index.tsx`, `index.jsx` or `index.mdx`. The source given is neither.",
+      fix: 'Create the entry: its default export is the page, and its manifest is `export const artifact = defineArtifact({ title: "..." })` (or frontmatter in MDX). For a single page, publish the file itself.',
+    },
+  },
+  MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS: {
+    severity: "error",
+    phase: "manifest",
+    title: "More than one entry file",
+    hint: "Keep one entry file in the directory and rename or remove the others.",
+    docs: {
+      explanation:
+        "A directory artifact has exactly one entry, and this directory has more than one of `index.tsx`, `index.jsx` and `index.mdx`, so Mostra can't tell which one is the page.",
+      fix: "Keep the entry you mean and rename the others, for example into `components/`.",
+    },
+  },
+  MOSTRA_ARTIFACT_NO_PAGE: {
+    severity: "error",
+    phase: "manifest",
+    title: "Entry has no page",
+    hint: "Export the page component as the entry's default export, or add a `pages/` folder.",
+    docs: {
+      explanation:
+        "The entry has no default export and the artifact has no `pages/` folder, so there is nothing to render. With `pages/`, each file there is a route and the entry's default export, when present, is the layout around them.",
+      fix: "Add `export default function Page() { ... }` to the entry, or move pages into `pages/index.tsx`, `pages/settings.tsx` and so on.",
+    },
+  },
+  MOSTRA_ARTIFACT_DIR_NOT_EMPTY: {
+    severity: "error",
+    phase: "host",
+    title: "Directory isn't empty",
+    hint: "Choose a new or empty directory for the artifact.",
+    docs: {
+      explanation:
+        "Creating an artifact writes its entry into a directory, and the directory given already has files. Mostra never overwrites them.",
+      fix: "Pass a path that doesn't exist yet or an empty directory. To make existing files an artifact, add the entry yourself and publish.",
+    },
+  },
+  MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN: {
+    severity: "error",
+    phase: "host",
+    title: "Unknown template",
+    hint: "Create the artifact without a template, or use a template this Mostra release provides.",
+    docs: {
+      explanation:
+        "The template named isn't one this runtime provides. Without a template, Mostra writes a minimal entry with a generated artifact ID.",
+      fix: "Leave out the template, or use one of the templates of this release.",
+    },
+  },
+  MOSTRA_ARTIFACT_VERSION_NOT_FOUND: {
+    severity: "error",
+    phase: "host",
+    title: "No such version",
+    hint: "Name a version the artifact has (`artifact/get` lists them), or leave the version out for the latest.",
+    docs: {
+      explanation:
+        "The request named a version number or version ID that this artifact never published in this home. Viewers only ever open published versions (D09), so there is nothing to show.",
+      fix: "List the artifact's versions with `artifact/get` and pick one, or omit the version to open the latest. A link to `/a/<artifactId>/v/<number>` needs a number from that list.",
+    },
+  },
+  MOSTRA_ARTIFACT_VERSION_COLLECTED: {
+    severity: "error",
+    phase: "host",
+    title: "Version collected",
+    hint: "Open the artifact's latest version, or publish this version's source again to restore its files.",
+    docs: {
+      explanation:
+        "`mostra gc` removed this version's files because nothing referenced it (D140). Its ID and number stay in the ledger forever, so history and events still name it, but it can't be opened or linked.",
+      fix: "Open a version that still exists (`artifact/get` marks collected ones), or publish the exact source of this version again: publish restores its files under the same ID and number.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/build.ts

@@ -0,0 +1,65 @@
+/**
+ * Diagnostic codes of the BUILD area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the BUILD area, in the order they were added. */
+export const buildDiagnosticCodes = [
+  "MOSTRA_BUILD_FAILED",
+  "MOSTRA_BUILD_UNRESOLVED",
+  "MOSTRA_BUILD_CRASHED",
+  "MOSTRA_BUILD_TIMEOUT",
+  // gen:codes
+] as const;
+
+/** The codes of the BUILD area. */
+export type BuildDiagnosticCode = (typeof buildDiagnosticCodes)[number];
+
+/** The BUILD area's catalog entries. */
+export const buildDiagnostics: AreaCatalog<BuildDiagnosticCode> = {
+  MOSTRA_BUILD_FAILED: {
+    severity: "error",
+    phase: "compile",
+    title: "Build failed",
+    hint: "Fix the error at the reported location, then publish again.",
+    docs: {
+      explanation:
+        "The builder couldn't bundle the artifact: a syntax error, an invalid JSX or MDX construct, a CSS error or another bundler error. The message carries the bundler's own explanation, and the location points at the file, line and column when the bundler reports one. Nothing was published.",
+      fix: "Open the reported file at the reported line and fix the code there. For MDX, check that JSX in the document is closed and that `{` and `<` in prose are escaped. Run `mostra verify` to see the same error with the type checker's findings.",
+    },
+  },
+  MOSTRA_BUILD_UNRESOLVED: {
+    severity: "error",
+    phase: "compile",
+    title: "Import can't be resolved",
+    hint: "Correct the import path, or import the package from the warm set or add it with `mostra add`.",
+    docs: {
+      explanation:
+        "An import in the artifact names a file or package the builder can't find. Relative imports resolve inside the artifact's own files, `@/...` resolves from the artifact's root, and package imports resolve from Mostra's warm set and the artifact's installed packages. The message names the import and the file that contains it.",
+      fix: "For a file, check the path and its extension against the artifact's files. For a package, check its name; packages outside the warm set install with `mostra add <package>`.",
+    },
+  },
+  MOSTRA_BUILD_CRASHED: {
+    severity: "error",
+    phase: "compile",
+    title: "Builder crashed",
+    hint: "Publish again; if it crashes again, report the builder's last output from the message.",
+    docs: {
+      explanation:
+        "The builder child process exited before it finished, for example after running out of memory or on a signal. The supervisor and everything else in the instance keep working, and nothing was published. The message carries the builder's last lines of error output.",
+      fix: "Run the publish again, which starts a fresh builder. A crash that repeats points at the artifact's size or at a defect in Mostra: very large inline data is better kept in `public/` or loaded through a live source.",
+    },
+  },
+  MOSTRA_BUILD_TIMEOUT: {
+    severity: "error",
+    phase: "compile",
+    title: "Build timed out",
+    hint: "Make the build smaller, for example by moving large data into `public/`, then publish again.",
+    docs: {
+      explanation:
+        "The build took longer than its limit (180 seconds) and was stopped. Nothing was published.",
+      fix: "Move large data files that are imported into code into `public/` and fetch them at run time, split very large modules, and remove unused imports of heavy libraries. Then publish again.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/cli.ts

@@ -0,0 +1,53 @@
+/**
+ * Diagnostic codes of the CLI area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the CLI area, in the order they were added. */
+export const cliDiagnosticCodes = [
+  "MOSTRA_CLI_USAGE",
+  "MOSTRA_CLI_UNKNOWN_COMMAND",
+  "MOSTRA_CLI_CONFIG_UNWRITABLE",
+  // gen:codes
+] as const;
+
+/** The codes of the CLI area. */
+export type CliDiagnosticCode = (typeof cliDiagnosticCodes)[number];
+
+/** The CLI area's catalog entries. */
+export const cliDiagnostics: AreaCatalog<CliDiagnosticCode> = {
+  MOSTRA_CLI_USAGE: {
+    severity: "error",
+    phase: "host",
+    title: "Command used wrongly",
+    hint: "Run `mostra <command> --help` for the command's arguments and flags, then run it again.",
+    docs: {
+      explanation:
+        "The command line didn't fit the command's definition: a missing or extra argument, an unknown flag, a flag without its value, or a value of the wrong form (a duration, a number, JSON). Nothing ran. In `--json` mode the error is the envelope's `error`, and the exit code is 2.",
+      fix: "Read `mostra <command> --help` (or `--help --json` for the machine-readable definition) and correct the arguments.",
+    },
+  },
+  MOSTRA_CLI_UNKNOWN_COMMAND: {
+    severity: "error",
+    phase: "host",
+    title: "Unknown command",
+    hint: "Pick one of the commands this message lists; `mostra --help` describes each.",
+    docs: {
+      explanation:
+        "The first word after `mostra` isn't a command this CLI has. The message lists the commands that exist. Commands that later releases add (sharing, export, plugins, terminals) appear only once they exist, never as placeholders.",
+      fix: "Run one of the listed commands. `mostra --help` lists every command with a one-line summary.",
+    },
+  },
+  MOSTRA_CLI_CONFIG_UNWRITABLE: {
+    severity: "error",
+    phase: "platform",
+    title: "The CLI's config directory can't be written",
+    hint: "Make the directory the message names yours and writable (or point MOSTRA_CONFIG_DIR at one that is), then run the command again; DO_NOT_TRACK=1 turns telemetry off without writing anything.",
+    docs: {
+      explanation:
+        "`mostra telemetry on` and `off` record the choice in the CLI's config directory (`MOSTRA_CONFIG_DIR`, else `${XDG_CONFIG_HOME:-~/.config}/mostra`). The directory or its `telemetry.json` can't be written (another user owns it, the disk is full, it's read-only), so the choice wasn't recorded and nothing changed. Telemetry never stops another command for this: a store that can't be written means nothing is sent.",
+      fix: "Fix the directory's owner or mode, or set `MOSTRA_CONFIG_DIR` to a directory you own, and run the command again. `DO_NOT_TRACK=1` or `MOSTRA_TELEMETRY=0` in your environment turn telemetry off without a file.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/console.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostic codes of the CONSOLE area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the CONSOLE area, in the order they were added. */
+export const consoleDiagnosticCodes = [
+  "MOSTRA_CONSOLE_ERROR",
+  "MOSTRA_CONSOLE_WARNING",
+  // gen:codes
+] as const;
+
+/** The codes of the CONSOLE area. */
+export type ConsoleDiagnosticCode = (typeof consoleDiagnosticCodes)[number];
+
+/** The CONSOLE area's catalog entries. */
+export const consoleDiagnostics: AreaCatalog<ConsoleDiagnosticCode> = {
+  MOSTRA_CONSOLE_ERROR: {
+    severity: "error",
+    phase: "console",
+    title: "Error logged to the console",
+    hint: "Fix what the logged error describes; React logs errors its boundaries catch here too.",
+    docs: {
+      explanation:
+        "The page logged an error with `console.error` while verify rendered it or used its controls. Errors caught by React error boundaries, the root's included, are logged this way. A viewer's page would log the same.",
+      fix: "Read the message and fix its cause in the artifact's code. Errors logged by a library usually name what it was given.",
+    },
+  },
+  MOSTRA_CONSOLE_WARNING: {
+    severity: "hint",
+    phase: "console",
+    title: "Warning logged to the console",
+    hint: "Read the warning; nothing is broken by it.",
+    docs: {
+      explanation:
+        "The page logged a warning with `console.warn`. Warnings are often a library's advice, so they are hints.",
+      fix: "Nothing is required.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/dep.ts

@@ -0,0 +1,101 @@
+/**
+ * Diagnostic codes of the DEP area: the packages an artifact imports (D20, D43, D95).
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the DEP area, in the order they were added. */
+export const depDiagnosticCodes = [
+  "MOSTRA_DEP_MISSING",
+  "MOSTRA_DEP_NOT_FOUND",
+  "MOSTRA_DEP_OFFLINE",
+  "MOSTRA_DEP_TIMEOUT",
+  "MOSTRA_DEP_INSTALL_FAILED",
+  "MOSTRA_DEP_WARM_CONFLICT",
+  "MOSTRA_DEP_SPEC_INVALID",
+  // gen:codes
+] as const;
+
+/** The codes of the DEP area. */
+export type DepDiagnosticCode = (typeof depDiagnosticCodes)[number];
+
+/** The DEP area's catalog entries. */
+export const depDiagnostics: AreaCatalog<DepDiagnosticCode> = {
+  MOSTRA_DEP_MISSING: {
+    severity: "error",
+    phase: "compile",
+    title: "Package not added",
+    hint: "Run the `mostra add` command in this diagnostic's fix, then publish again.",
+    docs: {
+      explanation:
+        "The artifact imports a package that is neither in Mostra's warm set nor in the artifact's lockfile, and the host has set the dependency policy to `explicit`. Under that policy a package enters an artifact's lockfile only when it is added on purpose, so Mostra installs nothing on its own. The location points at the first import of the package, and the fix carries the exact command that adds every missing package.",
+      fix: "Run the command from the fix (`mostra add <package…> --artifact <path>`, or the host protocol method `deps/add`), then publish again. To use a package from the warm set instead, change the import.",
+    },
+  },
+  MOSTRA_DEP_NOT_FOUND: {
+    severity: "error",
+    phase: "compile",
+    title: "Package not found",
+    hint: "Check the package name and version against the npm registry, then fix the import or the spec.",
+    docs: {
+      explanation:
+        "The registry has no package by that name, or no version that matches the requested one. A spec without an exact version only matches releases at least a day old, so a package whose every release is newer than that isn't found either. The message names the package and what the registry answered.",
+      fix: "Correct the package name in the import or in the `mostra add` spec. To use a release less than a day old, add it at its exact version: `mostra add <package>@<version>`.",
+    },
+  },
+  MOSTRA_DEP_OFFLINE: {
+    severity: "error",
+    phase: "compile",
+    title: "Package unavailable offline",
+    hint: "Connect to the network and publish again, or import a package the home already holds.",
+    docs: {
+      explanation:
+        "Mostra is offline (`MOSTRA_OFFLINE` is set, no network interface is up, or the registry can't be reached), and the artifact needs a package that the home's package store doesn't hold yet. Everything the store holds keeps working offline, including rebuilds of published versions. The message names the missing package.",
+      fix: "Publish again once the registry is reachable; the package then stays in the store for later offline use. Otherwise remove the import, or use a package from the warm set.",
+    },
+  },
+  MOSTRA_DEP_TIMEOUT: {
+    severity: "error",
+    phase: "compile",
+    title: "Package install timed out",
+    hint: "Check the network and the registry, then publish again.",
+    docs: {
+      explanation:
+        "Installing the artifact's packages took longer than 300 seconds and was stopped. A slow registry, a stalled download or a lifecycle script that never ends are the usual causes. Nothing was published, and packages already in the store stay there.",
+      fix: "Publish again; packages that finished downloading aren't fetched twice. When a package's install script hangs, use another version of the package or another package.",
+    },
+  },
+  MOSTRA_DEP_INSTALL_FAILED: {
+    severity: "error",
+    phase: "compile",
+    title: "Package install failed",
+    hint: "Read the installer's output in the message, then fix the package spec or choose another version.",
+    docs: {
+      explanation:
+        "The package installer failed for a reason other than a missing package or the network: most often a package's lifecycle script (`preinstall`, `install`, `postinstall`) exited with an error, or a downloaded package didn't match its integrity hash. Lifecycle scripts run in an install child in the artifact's directory with the artifact's environment. The message carries the end of the installer's output.",
+      fix: "Fix what the output names. For a failing install script, check what it needs (a compiler, a system library) or use another version of the package.",
+    },
+  },
+  MOSTRA_DEP_WARM_CONFLICT: {
+    severity: "error",
+    phase: "compile",
+    title: "Warm package version requested",
+    hint: "Add the package without a version, or with one the warm set's version satisfies.",
+    docs: {
+      explanation:
+        "The package is part of Mostra's warm set, which every artifact resolves at one fixed version so that React and the other shared packages exist exactly once. The requested version doesn't match the warm one, and an artifact can't replace a warm package.",
+      fix: "Drop the version from the spec (`mostra add react`), or request a range the warm version satisfies. The message names the warm version.",
+    },
+  },
+  MOSTRA_DEP_SPEC_INVALID: {
+    severity: "error",
+    phase: "host",
+    title: "Invalid package spec",
+    hint: "Write the spec as `name`, `name@version`, `name@range` or `name@tag`.",
+    docs: {
+      explanation:
+        "A package spec given to `mostra add` (`deps/add`) isn't an npm registry spec. Mostra adds packages from the registry by name, optionally with a version, a semver range or a dist-tag; scoped names such as `@scope/name@1.2.3` work too. Git URLs, local paths and tarball URLs aren't registry specs.",
+      fix: "Correct the spec, for example `mostra add three@0.186.1` or `mostra add @xyflow/react`.",
+    },
+  },
+  // gen:entries
+};