@mostra/protocol 0.0.0-stage → 0.1.0

package/src/diagnostics/codes/runtime.ts

@@ -0,0 +1,77 @@
+/**
+ * Diagnostic codes of the RUNTIME area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the RUNTIME area, in the order they were added. */
+export const runtimeDiagnosticCodes = [
+  "MOSTRA_RUNTIME_WORKER_CRASHED",
+  "MOSTRA_RUNTIME_WORKER_PARKED",
+  "MOSTRA_RUNTIME_PAGE_ERROR",
+  "MOSTRA_RUNTIME_BLANK",
+  "MOSTRA_RUNTIME_NOT_READY",
+  // gen:codes
+] as const;
+
+/** The codes of the RUNTIME area. */
+export type RuntimeDiagnosticCode = (typeof runtimeDiagnosticCodes)[number];
+
+/** The RUNTIME area's catalog entries. */
+export const runtimeDiagnostics: AreaCatalog<RuntimeDiagnosticCode> = {
+  MOSTRA_RUNTIME_WORKER_CRASHED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Artifact server code crashed",
+    hint: "Read the cause and the worker's last output, fix the server code, and publish again.",
+    docs: {
+      explanation:
+        "The artifact version's worker process exited while serving a call: it threw outside any call, ran out of its heap (1 GiB by default), or kept its event loop blocked past the watchdog (10 s by default). Other artifacts and the gateway keep working (RT-04). Mostra appends `worker.crashed` with the cause and starts the worker again on the next request, waiting longer after each crash (1 s up to 60 s). `verify` reports it too when the source's server code crashes, fails to load or hangs while the page renders, even when the page handled the failed call.",
+      fix: "Fix the crash in the server code. A long synchronous computation can raise `limits.watchdogMs` in the manifest, and a large data set `limits.heapMb`; both are stability limits, not security ones.",
+    },
+  },
+  MOSTRA_RUNTIME_WORKER_PARKED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Artifact server code keeps crashing",
+    hint: "Fix the server code and publish again, which clears the park; the message names the last crash's cause.",
+    docs: {
+      explanation:
+        "The artifact version's worker crashed more than 5 times in 10 minutes, so Mostra stopped starting it (FAILURE_MODEL \u00a72). Calls, runs and live sources of that version answer this code until the park clears, and the shell tells the viewer that the artifact's server code keeps crashing.",
+      fix: "Find the cause in the message and the worker's output, fix it, and publish again: a new publish, `verify` or a restart of the instance clears the park.",
+    },
+  },
+  MOSTRA_RUNTIME_PAGE_ERROR: {
+    severity: "error",
+    phase: "runtime",
+    title: "Uncaught error in the page",
+    hint: "Fix the error the message names; it was thrown in the page and nothing caught it.",
+    docs: {
+      explanation:
+        "The artifact's page threw an error that nothing caught, or a promise rejected with nothing handling it, while verify rendered it or while the smoke test used a control (the message says which). A viewer's page would meet the same error.",
+      fix: "Find the stack's first frame in the artifact's code and fix the error there, or catch it where the page can recover.",
+    },
+  },
+  MOSTRA_RUNTIME_BLANK: {
+    severity: "error",
+    phase: "runtime",
+    title: "Page rendered nothing",
+    hint: "Make the page render something visible; check its first render and its imports.",
+    docs: {
+      explanation:
+        "After the page reported ready, no element had a visible box (text, image, SVG, canvas or video) and the screenshot was one uniform color. Usually the page threw during its first render, rendered nothing until data arrived, or hid everything with CSS.",
+      fix: "Look at the other diagnostics for an error during the first render, and make the page show content (or a loading state) right away.",
+    },
+  },
+  MOSTRA_RUNTIME_NOT_READY: {
+    severity: "error",
+    phase: "runtime",
+    title: "Page never became ready",
+    hint: "Make sure the entry's default export renders; check the other diagnostics for an error at load.",
+    docs: {
+      explanation:
+        "The page never reported `mostra/ready`: the client runtime didn't mount it within the time verify allows, usually because the entry threw while loading or a module failed to load.",
+      fix: "Fix the load error the other diagnostics report. A page that waits for data should render a loading state first.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/secret.ts

@@ -0,0 +1,29 @@
+/**
+ * Diagnostic codes of the SECRET area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the SECRET area, in the order they were added. */
+export const secretDiagnosticCodes = [
+  "MOSTRA_SECRET_MISSING",
+  // gen:codes
+] as const;
+
+/** The codes of the SECRET area. */
+export type SecretDiagnosticCode = (typeof secretDiagnosticCodes)[number];
+
+/** The SECRET area's catalog entries. */
+export const secretDiagnostics: AreaCatalog<SecretDiagnosticCode> = {
+  MOSTRA_SECRET_MISSING: {
+    severity: "error",
+    phase: "runtime",
+    title: "Secret not set",
+    hint: "Set the secret with `mostra secret set NAME`, reading the value from stdin.",
+    docs: {
+      explanation:
+        "Server code called `secret(name)` for a secret that neither the host's `secrets` port, the artifact's own secrets nor the home's shared secrets hold (D44). The call throws, and an action run fails with this code.",
+      fix: "Set the secret for the artifact (`mostra secret set NAME --artifact <path|id>`) or for every artifact of the home (`mostra secret set NAME`), passing the value on stdin, then run the action again. Secret values never go into the artifact's source.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/smoke.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostic codes of the SMOKE area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the SMOKE area, in the order they were added. */
+export const smokeDiagnosticCodes = [
+  "MOSTRA_SMOKE_NO_EFFECT",
+  "MOSTRA_SMOKE_BUDGET",
+  // gen:codes
+] as const;
+
+/** The codes of the SMOKE area. */
+export type SmokeDiagnosticCode = (typeof smokeDiagnosticCodes)[number];
+
+/** The SMOKE area's catalog entries. */
+export const smokeDiagnostics: AreaCatalog<SmokeDiagnosticCode> = {
+  MOSTRA_SMOKE_NO_EFFECT: {
+    severity: "warning",
+    phase: "smoke",
+    title: "Control showed no effect",
+    hint: "Observed only: using this control twice changed nothing verify could see; a control that acts on something verify can't observe needs no change.",
+    docs: {
+      explanation:
+        "Verify's smoke test clicked or hovered the control the message names, once among the other controls and again after them, and saw no change either time: no change to the page, no request, no saved field, no navigation and no error. Controls that are disabled or already active (the selected tab) are skipped, and those that open on hover are hovered. A control can still be fine: it may act on something verify can't observe, such as the clipboard or a sound.",
+      fix: "Read the control's handler. If it does what it should, nothing needs to change; if it is meant to change the page, look at why it doesn't.",
+    },
+  },
+  MOSTRA_SMOKE_BUDGET: {
+    severity: "hint",
+    phase: "smoke",
+    title: "Smoke test stopped at its budget",
+    hint: "Nothing to fix: the smoke test stops after 200 interactions or 60 s.",
+    docs: {
+      explanation:
+        "The page has more controls than the smoke test uses in one run, so it stopped at its budget. The controls it used are counted in `smoke.interactions`.",
+      fix: "Nothing is required.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/submit.ts

@@ -0,0 +1,113 @@
+/**
+ * Diagnostic codes of the SUBMIT area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the SUBMIT area, in the order they were added. */
+export const submitDiagnosticCodes = [
+  "MOSTRA_SUBMIT_ALREADY",
+  "MOSTRA_SUBMIT_REVISION_MOVED",
+  "MOSTRA_SUBMIT_POLICY_NONE",
+  "MOSTRA_SUBMIT_NOT_FOUND",
+  "MOSTRA_SUBMIT_VIEW_INVALID",
+  "MOSTRA_SUBMIT_SIGNAL_INVALID",
+  "MOSTRA_SUBMIT_CHANNEL_DENIED",
+  "MOSTRA_SUBMIT_BLOCKED",
+  // gen:codes
+] as const;
+
+/** The codes of the SUBMIT area. */
+export type SubmitDiagnosticCode = (typeof submitDiagnosticCodes)[number];
+
+/** The SUBMIT area's catalog entries. */
+export const submitDiagnostics: AreaCatalog<SubmitDiagnosticCode> = {
+  MOSTRA_SUBMIT_ALREADY: {
+    severity: "error",
+    phase: "runtime",
+    title: "Already submitted",
+    hint: "This artifact takes one submission, and it was made; read it with `mostra results`.",
+    docs: {
+      explanation:
+        "The artifact's submission policy is `once`, and a submission already closed this draft: for scope `per-artifact` any viewer's submission closes every draft, for `per-viewer` the viewer's own. A submission is immutable and final, so Mostra refuses a second one and further edits to the closed draft. The refusal carries the existing submission. A repeated submit of the same view at the same draft revision is not refused: it returns the original submission.",
+      fix: 'Read the existing submission with `mostra results <artifact>`. When another round of answers is wanted, publish a new artifact linked to this one (`links: [{ rel: "round-of", artifact }]`), or have the host publish with the `epochs` policy.',
+    },
+  },
+  MOSTRA_SUBMIT_REVISION_MOVED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Draft changed before submit",
+    hint: "Reload the draft, check what changed, and submit again with its current revision.",
+    docs: {
+      explanation:
+        "A submit names the draft revision the viewer saw (`expectedRevision`), and the draft has changed since: another tab, device or writer saved an edit. Mostra never makes a submission from content the viewer didn't see (FAILURE_MODEL §4), so it refuses. The message names the draft's current revision.",
+      fix: "Let the page reload the draft so the viewer sees exactly what will be sent, then submit with the new revision. The shell and the client runtime flush pending saves before they submit, which makes this rare.",
+    },
+  },
+  MOSTRA_SUBMIT_POLICY_NONE: {
+    severity: "error",
+    phase: "runtime",
+    title: "Artifact takes no submissions",
+    hint: "Exchange data through artifact state, actions and signals; this artifact has no submissions.",
+    docs: {
+      explanation:
+        "The artifact's submission policy is `none` (D63): long-lived artifacts such as dashboards and task managers talk to agents through artifact state, actions, signals and events, and the shell shows no Submit control. Mostra refuses a submit, and a `wait --until submitted`, on such an artifact.",
+      fix: "Wait for a signal (`--until signal:<name>`), a state change (`--until state:<field>`) or an event instead, and read state with `mostra state get`. To collect submissions, publish with policy `once` or `epochs`.",
+    },
+  },
+  MOSTRA_SUBMIT_NOT_FOUND: {
+    severity: "error",
+    phase: "runtime",
+    title: "No such submission",
+    hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.",
+    docs: {
+      explanation:
+        "The artifact has no submission yet, or none with the ID asked for. Submissions are durable once made, so this means none was made (or the ID belongs to another artifact or home).",
+      fix: "Run `mostra wait <artifact> --until submitted` to block until the viewer submits, then read the results. List the artifact's submissions through `submission.created` events.",
+    },
+  },
+  MOSTRA_SUBMIT_VIEW_INVALID: {
+    severity: "error",
+    phase: "runtime",
+    title: "Unknown view",
+    hint: "Send the view ID this page was opened with.",
+    docs: {
+      explanation:
+        "Mutations and submits name the view they come from, the one the shell created when it opened this frame. The view named doesn't exist, belongs to another artifact, or belongs to another viewer. Mostra binds every submission to the exact version its view showed, so it refuses a view it can't place.",
+      fix: "Use the `viewId` the shell handed this frame. A page opened outside Mostra's shell has no view and can't submit.",
+    },
+  },
+  MOSTRA_SUBMIT_SIGNAL_INVALID: {
+    severity: "error",
+    phase: "runtime",
+    title: "Invalid signal",
+    hint: "Name signals with letters, digits, `.`, `_` and `-`, and keep their payload under 64 KiB of JSON.",
+    docs: {
+      explanation:
+        "A signal names something the artifact wants a host's attention for, such as `ping-agent`. Its name is 1 to 64 characters of letters, digits, `.`, `_` and `-`, starting with a letter or digit, and its payload is JSON of at most 64 KiB. This one broke one of those rules. The name `submit` is reserved for submissions.",
+      fix: "Rename the signal or shrink its payload; put large data into a field or artifact state and send its ID in the payload.",
+    },
+  },
+  MOSTRA_SUBMIT_CHANNEL_DENIED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Submit channel not allowed",
+    hint: "Let the viewer submit with the shell's trusted Submit; this host doesn't take submissions from artifact code.",
+    docs: {
+      explanation:
+        "A submission comes through one of two channels (D40): the shell's trusted Submit (`shell`), which only a person can press, or the artifact's own code (`artifact`, `useSubmit().submit()` and `useChoice().choose()`). The host decides which it accepts (D108): through `HomeConfig.submitChannels` for the home, or its `trustedControls` port for each artifact. This view allows only the other channel, so Mostra refused the submit or the choice. `useSubmit().allowed` is `false` in such a view.",
+      fix: "Ask the viewer to press the shell's Submit (relabel it with `useSubmitControl`), and use `useChoice(id, { candidates })` to have the shell render a trusted Choose. Check `allowed` before showing an in-page submit button.",
+    },
+  },
+  MOSTRA_SUBMIT_BLOCKED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Answers missing before submit",
+    hint: "Fill in the fields this diagnostic lists, fix their errors or resolve their conflicts, then submit again.",
+    docs: {
+      explanation:
+        "Before a submit, the shell and the client runtime check every mounted field (D106): a `required` field without a value, a value its `validate` rejects, or a conflict the viewer hasn't resolved blocks the submit. The diagnostic lists the blockers with their field IDs and labels; `useSubmit().blockers` lists them before anyone submits. Nothing was submitted.",
+      fix: "Show `useSubmit().blockers` next to your submit button, or let the shell list them by label. Answer the required fields, fix the invalid values, and keep or take the conflicting values, then submit again.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/target.ts

@@ -0,0 +1,29 @@
+/**
+ * Diagnostic codes of the TARGET area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the TARGET area, in the order they were added. */
+export const targetDiagnosticCodes = [
+  "MOSTRA_TARGET_UNAVAILABLE",
+  // gen:codes
+] as const;
+
+/** The codes of the TARGET area. */
+export type TargetDiagnosticCode = (typeof targetDiagnosticCodes)[number];
+
+/** The TARGET area's catalog entries. */
+export const targetDiagnostics: AreaCatalog<TargetDiagnosticCode> = {
+  MOSTRA_TARGET_UNAVAILABLE: {
+    severity: "error",
+    phase: "runtime",
+    title: "Not available in this delivery target",
+    hint: "Open the published version through Mostra to use this feature.",
+    docs: {
+      explanation:
+        "The page called something that needs Mostra's server, such as a server function, and this delivery target doesn't provide it: a static export, a file opened from disk, or a runtime without server support. The page keeps working without it.",
+      fix: "Open the artifact through its Mostra link, where server functions, submissions and live data are available. In a static export, handle the error so the page explains what isn't available.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/type.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostic codes of the TYPE area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the TYPE area, in the order they were added. */
+export const typeDiagnosticCodes = [
+  "MOSTRA_TYPE_ERROR",
+  "MOSTRA_TYPE_UNTYPED_PACKAGE",
+  // gen:codes
+] as const;
+
+/** The codes of the TYPE area. */
+export type TypeDiagnosticCode = (typeof typeDiagnosticCodes)[number];
+
+/** The TYPE area's catalog entries. */
+export const typeDiagnostics: AreaCatalog<TypeDiagnosticCode> = {
+  MOSTRA_TYPE_ERROR: {
+    severity: "error",
+    phase: "compile",
+    title: "Type error",
+    hint: "Fix the type error at the reported location; the message carries TypeScript's code and text.",
+    docs: {
+      explanation:
+        "TypeScript's checker (`tsc --noEmit`, TypeScript 7) found an error in the artifact's code. Verify checks with the artifact's own `tsconfig.json` when it has one, else in strict mode without the unused-variable rules, and resolves imports exactly as the build does. MDX isn't checked.",
+      fix: "Open the file at the reported line and fix the code, for example a missing property, a wrong argument type or a misspelled import.",
+    },
+  },
+  MOSTRA_TYPE_UNTYPED_PACKAGE: {
+    severity: "warning",
+    phase: "compile",
+    title: "Package without type declarations",
+    hint: "Nothing breaks: the package works without types; declare a module for it if you want them checked.",
+    docs: {
+      explanation:
+        "The artifact imports a package that ships no type declarations (TypeScript's TS7016). The package still builds and runs, so this is a warning: its values are typed `any`.",
+      fix: 'Optionally add a declaration file such as `declare module "<package>";`, or a typed wrapper, to the artifact.',
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/verify.ts

@@ -0,0 +1,113 @@
+/**
+ * Diagnostic codes of the VERIFY area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the VERIFY area, in the order they were added. */
+export const verifyDiagnosticCodes = [
+  "MOSTRA_VERIFY_ACTION_SKIPPED",
+  "MOSTRA_VERIFY_SKIP_CONSEQUENCE",
+  "MOSTRA_VERIFY_TIMEOUT",
+  "MOSTRA_VERIFY_CRASHED",
+  "MOSTRA_VERIFY_NO_BASELINE",
+  "MOSTRA_VERIFY_BASELINE_MISSING",
+  "MOSTRA_VERIFY_LIVE_FAILED",
+  "MOSTRA_VERIFY_SECRET_MISSING",
+  // gen:codes
+] as const;
+
+/** The codes of the VERIFY area. */
+export type VerifyDiagnosticCode = (typeof verifyDiagnosticCodes)[number];
+
+/** The VERIFY area's catalog entries. */
+export const verifyDiagnostics: AreaCatalog<VerifyDiagnosticCode> = {
+  MOSTRA_VERIFY_ACTION_SKIPPED: {
+    severity: "hint",
+    phase: "smoke",
+    title: "Action skipped in verify",
+    hint: "To have verify run this action, check `dryRun()` from `@mostra/server` in it and return early without its side effects when it is true.",
+    docs: {
+      explanation:
+        "Verify's smoke test never runs a server function that doesn't check `dryRun()` (D55). When the page called one, verify refused the call instead: the page's `run()` or server reference rejected with a `MostraError` carrying this code, as it would for any failed action. The verdict lists every such function in `smoke.skippedActions`. Nothing was sent, written or charged.",
+      fix: "Nothing is wrong. To have verify exercise the action, add `if (dryRun()) return <a representative result>;` before its side effects; verify then runs it with `dryRun()` true.",
+    },
+  },
+  MOSTRA_VERIFY_SKIP_CONSEQUENCE: {
+    severity: "hint",
+    phase: "smoke",
+    title: "Page reaction to a skipped action",
+    hint: "Nothing to fix: this followed from verify skipping an action, which a viewer's page never meets.",
+    docs: {
+      explanation:
+        "After verify refused a server function that doesn't check `dryRun()`, the page reported an error: an unhandled rejection, an error a boundary caught, or a console error while it settled. It follows from verify's synthetic refusal, not from a defect a viewer would meet, so it is reported as a hint naming the skipped action.",
+      fix: "Nothing is required. To let verify see the action's real result, opt it into the smoke test with `dryRun()`.",
+    },
+  },
+  MOSTRA_VERIFY_TIMEOUT: {
+    severity: "error",
+    phase: "runtime",
+    title: "Verify ran out of time",
+    hint: "Make the page render without waiting on slow work at load, then verify again.",
+    docs: {
+      explanation:
+        "Verify allows 120 s for everything after the build: booting the sandbox, rendering each viewport, the smoke test and the regression stage. This run went past it, so its verdict is partial: the message names the stage it reached. A partial run can't vouch for the page, so this is an error, and the verdict isn't cached.",
+      fix: "Look for work the page does at load that takes long (large data, long animations, requests that never answer) and defer it, then verify again. On a heavily loaded machine, verifying again may be enough.",
+    },
+  },
+  MOSTRA_VERIFY_CRASHED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Verify runner crashed",
+    hint: "Verify again; if it keeps crashing, report the message with `mostra doctor`'s output.",
+    docs: {
+      explanation:
+        "The verify runner, the child process that drives the browser, stopped before it finished (FAILURE_MODEL §2). The message carries its last lines of output. Nothing was published, and the next verify starts a fresh runner.",
+      fix: "Verify again. A crash that repeats for the same artifact can come from a page that exhausts the browser's memory; one that repeats for every artifact means the runtime's browser is damaged.",
+    },
+  },
+  MOSTRA_VERIFY_NO_BASELINE: {
+    severity: "hint",
+    phase: "regression",
+    title: "No earlier passing version",
+    hint: "Nothing to fix: the next version will be compared with this one once it is published.",
+    docs: {
+      explanation:
+        "Verify compares a source with the newest published version of its artifact whose verdict passed. This artifact has none yet (it is new, or every earlier version was published with `--force`), so no regression stage ran.",
+      fix: "Nothing is required.",
+    },
+  },
+  MOSTRA_VERIFY_BASELINE_MISSING: {
+    severity: "hint",
+    phase: "regression",
+    title: "Baseline version's build is missing",
+    hint: "Nothing to fix here; publish again to give later versions a baseline.",
+    docs: {
+      explanation:
+        "The newest version that passed verify is recorded in the ledger, but its stored build isn't in the home any more, so verify couldn't render it and ran no regression stage.",
+      fix: "Nothing is required. A version published from this source becomes the next baseline.",
+    },
+  },
+  MOSTRA_VERIFY_LIVE_FAILED: {
+    severity: "warning",
+    phase: "runtime",
+    title: "Live source failed during verify",
+    hint: "Check the live source's message: it failed while verify rendered the page, which may be the environment rather than the code.",
+    docs: {
+      explanation:
+        "A live source's producer (`live.ts`) threw or couldn't reach its data while verify rendered the page. Verify runs producers for real, since they only read, so a failure can come from the environment (no network, a service that is down) as well as from the code. The page shows `useLive`'s `error` meanwhile.",
+      fix: "Read the message. If the producer itself is wrong, fix it; if the data source was unreachable, verify again when it is back.",
+    },
+  },
+  MOSTRA_VERIFY_SECRET_MISSING: {
+    severity: "warning",
+    phase: "runtime",
+    title: "Secret missing during verify",
+    hint: "Set the secret with `mostra secret set <NAME>` if the artifact needs it; verify reports it as the environment, not the code.",
+    docs: {
+      explanation:
+        "Server code asked for a secret (`secret()`) that neither the host, the artifact's secrets nor the home's hold, while verify ran it. Secrets are part of the environment, so verify reports this as a warning rather than an error.",
+      fix: "Run `mostra secret set <NAME>` (for the artifact or the home) with the value the code needs, then verify again.",
+    },
+  },
+  // gen:entries
+};