@mostra/protocol 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/actions.d.ts CHANGED
@@ -139,6 +139,13 @@ export interface LiveState {
139
139
  }[];
140
140
  /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */
141
141
  readonly error?: WireError;
142
+ /**
143
+ * `true` while the source has no value and no failure and the artifact's latest version has a
144
+ * producer whose first `load` is on its way: the page shows it loading, and verify waits for it.
145
+ * Absent for a key nothing produces (one only `mostra push` writes) and for a source that only
146
+ * streams, whose first value may never come (WP-14's Opus review).
147
+ */
148
+ readonly awaiting?: boolean;
142
149
  }
143
150
  /** One live update on the event stream: never stored as an event (D63, LL-04). */
144
151
  export interface LiveUpdate {
@@ -152,6 +159,11 @@ export interface LiveUpdate {
152
159
  readonly value?: Batches;
153
160
  /** What went wrong. */
154
161
  readonly error?: WireError;
162
+ /**
163
+ * `false` when a source read as {@link LiveState.awaiting} turned out to have no first `load`
164
+ * (its producer only streams): the page stops waiting for a first value.
165
+ */
166
+ readonly awaiting?: boolean;
155
167
  }
156
168
  /**
157
169
  * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an
@@ -1 +1 @@
1
- {"version":3,"file":"actions.d.ts","names":[],"sources":["../src/actions.ts"],"mappings":";;;;YAgBY,6BAA6B;;;;;qBAM5B,SAAS,EAAE,QAAQ;;iBASf,oBAAoB;;WAE1B;;;qBAIE,aAAa,EAAE,QAAQ;;qBAYvB;;qBAGA;;qBAGA;;qBAGA;;qBAGA;;;;;;;YAQD;;qBAGC,uBAAuB;;wBAUpB,iBAAiB,QAAQ;;;;;;;YAU7B;;iBAGK;;WAEN;;WAEA;;;qBAIE,aAAa,EAAE,QAAQ;;;;;iBAcnB;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA,SAAS;;WAET,QAAQ;;WAER;;WAEA;;WAEA;;;;;WAKA;;WAEA;;;qBAIE,UAAU,EAAE,QAAQ;;;;;;iBA2BhB;;WAEN;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA;;WAEA;;WAEA,SAAS;;WAET,QAAQ;;WAER;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;;;;WAKR;aACE;aACA;aACA,OAAO;;;WAGT,QAAQ;;;iBAIF;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,QAAQ;;;;;;;YAQP;WACG;WAAsB,KAAK;;WAC3B;WAAuB,MAAM;;;iBAG3B;;WAEN;;WAEA,MAAM;;;qBAIJ,aAAa,EAAE,QAAQ;;;;YAUxB;WACG,gBAAgB;;WAChB;aAAgB;;;WAChB;aAAgB;aAA2B,OAAO;;;;iBAGhD;;WAEN;;WAEA;;WAEA,MAAM;;WAEN;;WAEA;;;qBAIE,YAAY,EAAE,QAAQ;;;;;iBAiBlB;;WAEN;;WAEA;;WAEA;aAA4B;aAAuB;;;;;;;WAMnD;aACE;aACA;aACA;;;;qBAKA,kBAAkB,EAAE,QAAQ;;iBA6BxB;;WAEN;;;qBAIE,kBAAkB,EAAE,QAAQ;;qBAK5B,kBAAkB;;qBAGlB;;qBAGA;;qBAGA;;;;;iBAMI;;WAEN;;;;;WAKA;aACE;aACA;aACA;;;;qBAKA,aAAa,EAAE,QAAQ;;qBAoBvB,qBAAqB;;qBAGrB"}
1
+ {"version":3,"file":"actions.d.ts","names":[],"sources":["../src/actions.ts"],"mappings":";;;;YAgBY,6BAA6B;;;;;qBAM5B,SAAS,EAAE,QAAQ;;iBASf,oBAAoB;;WAE1B;;;qBAIE,aAAa,EAAE,QAAQ;;qBAYvB;;qBAGA;;qBAGA;;qBAGA;;qBAGA;;;;;;;YAQD;;qBAGC,uBAAuB;;wBAUpB,iBAAiB,QAAQ;;;;;;;YAU7B;;iBAGK;;WAEN;;WAEA;;;qBAIE,aAAa,EAAE,QAAQ;;;;;iBAcnB;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA,SAAS;;WAET,QAAQ;;WAER;;WAEA;;WAEA;;;;;WAKA;;WAEA;;;qBAIE,UAAU,EAAE,QAAQ;;;;;;iBA2BhB;;WAEN;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA;;WAEA;;WAEA,SAAS;;WAET,QAAQ;;WAER;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;;;;WAKR;aACE;aACA;aACA,OAAO;;;WAGT,QAAQ;;;;;;;WAOR;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,QAAQ;;;;;WAKR;;;;;;;YAQC;WACG;WAAsB,KAAK;;WAC3B;WAAuB,MAAM;;;iBAG3B;;WAEN;;WAEA,MAAM;;;qBAIJ,aAAa,EAAE,QAAQ;;;;YAUxB;WACG,gBAAgB;;WAChB;aAAgB;;;WAChB;aAAgB;aAA2B,OAAO;;;;iBAGhD;;WAEN;;WAEA;;WAEA,MAAM;;WAEN;;WAEA;;;qBAIE,YAAY,EAAE,QAAQ;;;;;iBAiBlB;;WAEN;;WAEA;;WAEA;aAA4B;aAAuB;;;;;;;WAMnD;aACE;aACA;aACA;;;;qBAKA,kBAAkB,EAAE,QAAQ;;iBA6BxB;;WAEN;;;qBAIE,kBAAkB,EAAE,QAAQ;;qBAK5B,kBAAkB;;qBAGlB;;qBAGA;;qBAGA;;;;;iBAMI;;WAEN;;;;;WAKA;aACE;aACA;aACA;;;;qBAKA,aAAa,EAAE,QAAQ;;qBAoBvB,qBAAqB;;qBAGrB"}
@@ -1 +1 @@
1
- {"version":3,"file":"actions.js","names":[],"sources":["../src/actions.ts"],"sourcesContent":["/**\n * Actions, live data and secrets (INTERFACES §2.4, §4, §6; D24, D44, D54, D56): the shapes the\n * browser protocol, the host protocol and the worker channel share. Server-function arguments and\n * results travel as the serializer's batches (`Batches`).\n *\n * ```ts\n * const run: RunState = await post(\"runs\", { viewId, fnId: \"actions.ts#sendReply\", args, clientKey });\n * if (run.status === \"succeeded\") show(await deserializeAll(run.batches));\n * ```\n */\nimport * as z from \"zod\";\nimport { ViewId } from \"./ids.ts\";\nimport type { Frame, WireError } from \"./serializer.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** A value written by the serializer: its batches, in order (`serializeAll`). */\nexport type Batches = readonly (readonly Frame[])[];\n\n/**\n * The Zod schema of the `Batches` type: a list of batches, each a list of frames. The frames\n * themselves are checked by the reader (`ValueReader`), which refuses anything malformed.\n */\nexport const Batches: z.ZodType<Batches> = z\n .array(z.array(z.record(z.string(), z.unknown())).readonly())\n .readonly()\n .register(wireRegistry, {\n id: \"Batches\",\n description: \"A serialized server-function value: its batches of frames, in order.\",\n }) as unknown as z.ZodType<Batches>;\n\n/** An error as runs, calls and live sources report it. */\nexport interface ActionError extends WireError {\n /** The stack of the thrown error, kept in the run log and never sent to a page. */\n readonly stack?: string;\n}\n\n/** The Zod schema of the `ActionError` type. */\nexport const ActionError: z.ZodType<ActionError> = z\n .object({\n message: z.string(),\n code: z.string().exactOptional(),\n stack: z.string().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"ActionError\",\n description: \"An error from server code: its message and diagnostic code.\",\n });\n\n/** The largest serialized arguments a call or run takes, in characters of JSON. */\nexport const ACTION_ARGS_MAX: number = 16 * 1024 * 1024;\n\n/** The largest serialized result a run keeps, in characters of JSON (larger fails the run). */\nexport const ACTION_RESULT_MAX: number = 16 * 1024 * 1024;\n\n/** The cap of a run's log, in UTF-16 code units of its lines (D47's 1 MB). */\nexport const RUN_LOG_MAX: number = 1024 * 1024;\n\n/** The line a capped log ends with. */\nexport const RUN_LOG_TRUNCATED = \"[log truncated at 1 MB]\";\n\n/** The longest run key, in characters. */\nexport const RUN_KEY_MAX = 256;\n\n/**\n * A run's state (D24, ARCHITECTURE §7). `queued`: recorded, not yet started in a worker.\n * `running`: started. `waiting` is reserved for a remote server's run that waits for its owner's\n * instance (WP-28, D117); a page that doesn't know it treats it like `queued`. The others are\n * final.\n */\nexport type RunStatus = \"queued\" | \"running\" | \"waiting\" | \"succeeded\" | \"failed\" | \"cancelled\";\n\n/** Every run status. */\nexport const RUN_STATUSES: readonly RunStatus[] = [\n \"queued\",\n \"running\",\n \"waiting\",\n \"succeeded\",\n \"failed\",\n \"cancelled\",\n];\n\n/** Whether a run in `status` has ended. */\nexport function isFinalRunStatus(status: RunStatus): boolean {\n return status === \"succeeded\" || status === \"failed\" || status === \"cancelled\";\n}\n\n/**\n * Why a run ended the way it did, beside its status: `interrupted` (its worker or the instance\n * stopped while it ran, D24), `threw` (the action threw), `unserializable` (its result is outside\n * the type set), `too-large`, `parked` (its artifact's worker keeps crashing), `cancelled` (by a\n * viewer), `unknown-function`. Later releases add reasons.\n */\nexport type RunReason = string;\n\n/** A run's progress, as the action last reported it. */\nexport interface RunProgress {\n /** From 0 to 1. */\n readonly fraction?: number;\n /** One short line for people. */\n readonly message?: string;\n}\n\n/** The Zod schema of the `RunProgress` type. */\nexport const RunProgress: z.ZodType<RunProgress> = z\n .object({\n fraction: z.number().min(0).max(1).exactOptional(),\n message: z.string().max(1000).exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunProgress\",\n description: \"A run's progress: fraction and message.\",\n });\n\n/**\n * One action run as a page reads it (D54): its state, progress, log and the result written so far.\n * A result that is an async iterable grows item by item while the run is `running`.\n */\nexport interface RunState {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The server function it runs: `<module path>#<export>`. */\n readonly fnId: string;\n /** The idempotency key it was started with, if any. */\n readonly key?: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The log lines, capped at 1 MB with a marker line. */\n readonly log: readonly string[];\n /** The result's batches so far. */\n readonly batches: Batches;\n /** For `failed`: what went wrong, without the stack. */\n readonly error?: WireError;\n /** When it was recorded. */\n readonly startedAt: string;\n /** When it ended. */\n readonly finishedAt?: string;\n /** Whether this request joined a run that already existed (a key or a retried `clientKey`). */\n readonly joined?: boolean;\n /**\n * The index of the first line in `log`, when the request said which lines the page holds\n * (`RunAttachRequest.held`); absent: 0, the whole log.\n */\n readonly logFrom?: number;\n /** The index of the first batch in `batches`, as `logFrom`; absent: 0. */\n readonly batchFrom?: number;\n}\n\n/** The Zod schema of the `RunState` type. */\nexport const RunState: z.ZodType<RunState> = z\n .object({\n runId: z.string(),\n fnId: z.string(),\n key: z.string().exactOptional(),\n status: z.enum(RUN_STATUSES as [RunStatus, ...RunStatus[]]),\n reason: z.string().exactOptional(),\n progress: RunProgress.exactOptional(),\n log: z.array(z.string()).readonly(),\n batches: Batches,\n error: z.object({ message: z.string(), code: z.string().exactOptional() }).exactOptional(),\n startedAt: z.string(),\n finishedAt: z.string().exactOptional(),\n joined: z.boolean().exactOptional(),\n logFrom: z.number().int().nonnegative().exactOptional(),\n batchFrom: z.number().int().nonnegative().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunState\",\n description: \"An action run: status, progress, log and the result written so far.\",\n });\n\n/**\n * What changed in a run since a page last heard: a lossy notification on the event stream. Lines\n * start at `logFrom` and batches at `batchFrom`; a page that holds fewer reads the run again\n * (`runs/attach`).\n */\nexport interface RunDelta {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended so, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The index of the first line in `log`. */\n readonly logFrom: number;\n /** Log lines, starting at `logFrom`. */\n readonly log: readonly string[];\n /** The index of the first batch in `batches`. */\n readonly batchFrom: number;\n /** Result batches, starting at `batchFrom`. */\n readonly batches: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n /** When it ended. */\n readonly finishedAt?: string;\n}\n\n/** A live source's value as a page reads it (D56). */\nexport interface LiveState {\n /** The idempotency key it was started with, if any. */\n readonly key: string;\n /** The value's revision, a decimal string that only grows; absent before any value. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The latest value, serialized. */\n readonly value?: Batches;\n /**\n * Append mode (`useLive(key, { mode: \"append\" })`): the values kept in the source's ring, oldest\n * first, at most the window the page asked for.\n */\n readonly ring?: readonly {\n readonly revision: string;\n readonly at: string;\n readonly value: Batches;\n }[];\n /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */\n readonly error?: WireError;\n}\n\n/** One live update on the event stream: never stored as an event (D63, LL-04). */\nexport interface LiveUpdate {\n /** The live source's key. */\n readonly key: string;\n /** The value's revision. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The value, serialized. */\n readonly value?: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n}\n\n/**\n * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an\n * `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`: lossy, coalesced, and\n * never stored as an event.\n */\nexport type EphemeralMessage =\n | { readonly kind: \"run\"; readonly run: RunDelta }\n | { readonly kind: \"live\"; readonly live: LiveUpdate };\n\n/** `POST …/call/{fnId}`: a plain server-function call, no durable record (D54). */\nexport interface CallRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n}\n\n/** The Zod schema of the `CallRequest` type. */\nexport const CallRequest: z.ZodType<CallRequest> = z\n .object({ viewId: ViewId.schema, args: Batches })\n .register(wireRegistry, {\n id: \"CallRequest\",\n description: \"A plain server-function call: the view and the serialized arguments.\",\n });\n\n/**\n * One line of a plain call's answer (`application/x-ndjson`): a batch of the result, then the end.\n */\nexport type CallLine =\n | { readonly batch: readonly Frame[] }\n | { readonly end: { readonly status: \"succeeded\" } }\n | { readonly end: { readonly status: \"failed\"; readonly error: WireError } };\n\n/** `POST …/runs`: start a durable action run, or join one (D54, AC-02, AC-03). */\nexport interface RunRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** `<module path>#<export>`. */\n readonly fnId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n /** The author's idempotency key: one run per artifact, function and key, ever. */\n readonly key?: string;\n /** A fresh ID per invocation, so a retried request joins the run it already started. */\n readonly clientKey: string;\n}\n\n/** The Zod schema of the `RunRequest` type. */\nexport const RunRequest: z.ZodType<RunRequest> = z\n .object({\n viewId: ViewId.schema,\n fnId: z.string().min(3).max(1024),\n args: Batches,\n key: z.string().min(1).max(RUN_KEY_MAX).exactOptional(),\n clientKey: z.string().min(8).max(64),\n })\n .register(wireRegistry, {\n id: \"RunRequest\",\n description: \"Start or join an action run: the function, its arguments and keys.\",\n });\n\n/**\n * `POST …/runs/attach`: read runs and hear their changes on the event stream for the next minute\n * (re-attach after a reload, AC-02). By ID, or by function and key.\n */\nexport interface RunAttachRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** Runs by ID. */\n readonly runIds?: readonly string[];\n /** Runs by function and key. */\n readonly keyed?: readonly { readonly fnId: string; readonly key: string }[];\n /**\n * What the page already holds of runs it names by ID: so many log lines and batches. Each such\n * run's answer starts there (`RunState.logFrom`, `batchFrom`), so a page renewing its interest\n * doesn't read the whole run again (Opus review 14).\n */\n readonly held?: readonly {\n readonly runId: string;\n readonly log: number;\n readonly batches: number;\n }[];\n}\n\n/** The Zod schema of the `RunAttachRequest` type. */\nexport const RunAttachRequest: z.ZodType<RunAttachRequest> = z\n .object({\n viewId: ViewId.schema,\n runIds: z.array(z.string().max(64)).max(100).readonly().exactOptional(),\n keyed: z\n .array(\n z.object({ fnId: z.string().min(3).max(1024), key: z.string().min(1).max(RUN_KEY_MAX) }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n held: z\n .array(\n z.object({\n runId: z.string().max(64),\n log: z.number().int().nonnegative(),\n batches: z.number().int().nonnegative(),\n }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunAttachRequest\",\n description: \"Runs a page reads and follows: by ID, or by function and key.\",\n });\n\n/** `POST …/runs/{id}/cancel`. */\nexport interface RunCancelRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n}\n\n/** The Zod schema of the `RunCancelRequest` type. */\nexport const RunCancelRequest: z.ZodType<RunCancelRequest> = z\n .object({ viewId: ViewId.schema })\n .register(wireRegistry, { id: \"RunCancelRequest\", description: \"Cancel a run, from a view.\" });\n\n/** The keys of live sources: like JavaScript export names, which is what `live.ts` declares. */\nexport const LIVE_KEY_PATTERN: RegExp = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;\n\n/** The largest live value, in characters of serialized JSON (DATA_MODEL §5's 4 MiB). */\nexport const LIVE_VALUE_MAX: number = 4 * 1024 * 1024;\n\n/** The ring size of a pushed source in append mode that no `defineLive` sized. */\nexport const LIVE_RING_DEFAULT = 1024;\n\n/** The largest ring a source may keep. */\nexport const LIVE_RING_MAX = 100_000;\n\n/**\n * `POST …/live`: read live sources and keep their producers running for this view for the next\n * minute (D56, LL-04); a page asks again while it shows them.\n */\nexport interface LiveRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /**\n * The sources, each with its append window; `refresh` asks the source's producer to load again\n * now (`useLive`'s `refresh()`).\n */\n readonly keys: readonly {\n readonly key: string;\n readonly window?: number;\n readonly refresh?: boolean;\n }[];\n}\n\n/** The Zod schema of the `LiveRequest` type. */\nexport const LiveRequest: z.ZodType<LiveRequest> = z\n .object({\n viewId: ViewId.schema,\n keys: z\n .array(\n z.object({\n key: z.string().regex(LIVE_KEY_PATTERN),\n window: z.int().min(1).max(LIVE_RING_MAX).exactOptional(),\n refresh: z.boolean().exactOptional(),\n }),\n )\n .max(256)\n .readonly(),\n })\n .register(wireRegistry, {\n id: \"LiveRequest\",\n description: \"Live sources a page reads and keeps running: keys and append windows.\",\n });\n\n/** Secret names: letters, digits, `_`, `.` and `-`, starting with a letter or `_` (D44). */\nexport const SECRET_NAME_PATTERN: RegExp = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;\n\n/** The largest secret value, in UTF-8 bytes. */\nexport const SECRET_VALUE_MAX: number = 64 * 1024;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAsBA,MAAa,UAA8B,EACxC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAC5D,SAAS,CAAC,CACV,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AASH,MAAa,cAAsC,EAChD,OAAO;CACN,SAAS,EAAE,OAAO;CAClB,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,cAAc;AAClC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,kBAA0B;;AAGvC,MAAa,oBAA4B;;AAGzC,MAAa,cAAsB;;AAGnC,MAAa,oBAAoB;;AAGjC,MAAa,cAAc;;AAW3B,MAAa,eAAqC;CAChD;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,SAAgB,iBAAiB,QAA4B;CAC3D,OAAO,WAAW,eAAe,WAAW,YAAY,WAAW;AACrE;;AAmBA,MAAa,cAAsC,EAChD,OAAO;CACN,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;CACjD,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,GAAI,CAAC,CAAC,cAAc;AAC9C,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAyCH,MAAa,WAAgC,EAC1C,OAAO;CACN,OAAO,EAAE,OAAO;CAChB,MAAM,EAAE,OAAO;CACf,KAAK,EAAE,OAAO,CAAC,CAAC,cAAc;CAC9B,QAAQ,EAAE,KAAK,YAA2C;CAC1D,QAAQ,EAAE,OAAO,CAAC,CAAC,cAAc;CACjC,UAAU,YAAY,cAAc;CACpC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS;CAClC,SAAS;CACT,OAAO,EAAE,OAAO;EAAE,SAAS,EAAE,OAAO;EAAG,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAAE,CAAC,CAAC,CAAC,cAAc;CACzF,WAAW,EAAE,OAAO;CACpB,YAAY,EAAE,OAAO,CAAC,CAAC,cAAc;CACrC,QAAQ,EAAE,QAAQ,CAAC,CAAC,cAAc;CAClC,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc;CACtD,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc;AAC1D,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAqFH,MAAa,cAAsC,EAChD,OAAO;CAAE,QAAQ,OAAO;CAAQ,MAAM;AAAQ,CAAC,CAAC,CAChD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAyBH,MAAa,aAAoC,EAC9C,OAAO;CACN,QAAQ,OAAO;CACf,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;CAChC,MAAM;CACN,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,GAAe,CAAC,CAAC,cAAc;CACtD,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE;AACrC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AA0BH,MAAa,mBAAgD,EAC1D,OAAO;CACN,QAAQ,OAAO;CACf,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc;CACtE,OAAO,EACJ,MACC,EAAE,OAAO;EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;EAAG,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,GAAe;CAAE,CAAC,CACzF,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,cAAc;CACjB,MAAM,EACH,MACC,EAAE,OAAO;EACP,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE;EACxB,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY;EAClC,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY;CACxC,CAAC,CACH,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,cAAc;AACnB,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AASH,MAAa,mBAAgD,EAC1D,OAAO,EAAE,QAAQ,OAAO,OAAO,CAAC,CAAC,CACjC,SAAS,cAAc;CAAE,IAAI;CAAoB,aAAa;AAA6B,CAAC;;AAG/F,MAAa,mBAA2B;;AAGxC,MAAa,iBAAyB;;AAGtC,MAAa,oBAAoB;;AAGjC,MAAa,gBAAgB;;AAqB7B,MAAa,cAAsC,EAChD,OAAO;CACN,QAAQ,OAAO;CACf,MAAM,EACH,MACC,EAAE,OAAO;EACP,KAAK,EAAE,OAAO,CAAC,CAAC,MAAM,gBAAgB;EACtC,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,cAAc;EACxD,SAAS,EAAE,QAAQ,CAAC,CAAC,cAAc;CACrC,CAAC,CACH,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS;AACd,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,sBAA8B;;AAG3C,MAAa,mBAA2B"}
1
+ {"version":3,"file":"actions.js","names":[],"sources":["../src/actions.ts"],"sourcesContent":["/**\n * Actions, live data and secrets (INTERFACES §2.4, §4, §6; D24, D44, D54, D56): the shapes the\n * browser protocol, the host protocol and the worker channel share. Server-function arguments and\n * results travel as the serializer's batches (`Batches`).\n *\n * ```ts\n * const run: RunState = await post(\"runs\", { viewId, fnId: \"actions.ts#sendReply\", args, clientKey });\n * if (run.status === \"succeeded\") show(await deserializeAll(run.batches));\n * ```\n */\nimport * as z from \"zod\";\nimport { ViewId } from \"./ids.ts\";\nimport type { Frame, WireError } from \"./serializer.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** A value written by the serializer: its batches, in order (`serializeAll`). */\nexport type Batches = readonly (readonly Frame[])[];\n\n/**\n * The Zod schema of the `Batches` type: a list of batches, each a list of frames. The frames\n * themselves are checked by the reader (`ValueReader`), which refuses anything malformed.\n */\nexport const Batches: z.ZodType<Batches> = z\n .array(z.array(z.record(z.string(), z.unknown())).readonly())\n .readonly()\n .register(wireRegistry, {\n id: \"Batches\",\n description: \"A serialized server-function value: its batches of frames, in order.\",\n }) as unknown as z.ZodType<Batches>;\n\n/** An error as runs, calls and live sources report it. */\nexport interface ActionError extends WireError {\n /** The stack of the thrown error, kept in the run log and never sent to a page. */\n readonly stack?: string;\n}\n\n/** The Zod schema of the `ActionError` type. */\nexport const ActionError: z.ZodType<ActionError> = z\n .object({\n message: z.string(),\n code: z.string().exactOptional(),\n stack: z.string().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"ActionError\",\n description: \"An error from server code: its message and diagnostic code.\",\n });\n\n/** The largest serialized arguments a call or run takes, in characters of JSON. */\nexport const ACTION_ARGS_MAX: number = 16 * 1024 * 1024;\n\n/** The largest serialized result a run keeps, in characters of JSON (larger fails the run). */\nexport const ACTION_RESULT_MAX: number = 16 * 1024 * 1024;\n\n/** The cap of a run's log, in UTF-16 code units of its lines (D47's 1 MB). */\nexport const RUN_LOG_MAX: number = 1024 * 1024;\n\n/** The line a capped log ends with. */\nexport const RUN_LOG_TRUNCATED = \"[log truncated at 1 MB]\";\n\n/** The longest run key, in characters. */\nexport const RUN_KEY_MAX = 256;\n\n/**\n * A run's state (D24, ARCHITECTURE §7). `queued`: recorded, not yet started in a worker.\n * `running`: started. `waiting` is reserved for a remote server's run that waits for its owner's\n * instance (WP-28, D117); a page that doesn't know it treats it like `queued`. The others are\n * final.\n */\nexport type RunStatus = \"queued\" | \"running\" | \"waiting\" | \"succeeded\" | \"failed\" | \"cancelled\";\n\n/** Every run status. */\nexport const RUN_STATUSES: readonly RunStatus[] = [\n \"queued\",\n \"running\",\n \"waiting\",\n \"succeeded\",\n \"failed\",\n \"cancelled\",\n];\n\n/** Whether a run in `status` has ended. */\nexport function isFinalRunStatus(status: RunStatus): boolean {\n return status === \"succeeded\" || status === \"failed\" || status === \"cancelled\";\n}\n\n/**\n * Why a run ended the way it did, beside its status: `interrupted` (its worker or the instance\n * stopped while it ran, D24), `threw` (the action threw), `unserializable` (its result is outside\n * the type set), `too-large`, `parked` (its artifact's worker keeps crashing), `cancelled` (by a\n * viewer), `unknown-function`. Later releases add reasons.\n */\nexport type RunReason = string;\n\n/** A run's progress, as the action last reported it. */\nexport interface RunProgress {\n /** From 0 to 1. */\n readonly fraction?: number;\n /** One short line for people. */\n readonly message?: string;\n}\n\n/** The Zod schema of the `RunProgress` type. */\nexport const RunProgress: z.ZodType<RunProgress> = z\n .object({\n fraction: z.number().min(0).max(1).exactOptional(),\n message: z.string().max(1000).exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunProgress\",\n description: \"A run's progress: fraction and message.\",\n });\n\n/**\n * One action run as a page reads it (D54): its state, progress, log and the result written so far.\n * A result that is an async iterable grows item by item while the run is `running`.\n */\nexport interface RunState {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The server function it runs: `<module path>#<export>`. */\n readonly fnId: string;\n /** The idempotency key it was started with, if any. */\n readonly key?: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The log lines, capped at 1 MB with a marker line. */\n readonly log: readonly string[];\n /** The result's batches so far. */\n readonly batches: Batches;\n /** For `failed`: what went wrong, without the stack. */\n readonly error?: WireError;\n /** When it was recorded. */\n readonly startedAt: string;\n /** When it ended. */\n readonly finishedAt?: string;\n /** Whether this request joined a run that already existed (a key or a retried `clientKey`). */\n readonly joined?: boolean;\n /**\n * The index of the first line in `log`, when the request said which lines the page holds\n * (`RunAttachRequest.held`); absent: 0, the whole log.\n */\n readonly logFrom?: number;\n /** The index of the first batch in `batches`, as `logFrom`; absent: 0. */\n readonly batchFrom?: number;\n}\n\n/** The Zod schema of the `RunState` type. */\nexport const RunState: z.ZodType<RunState> = z\n .object({\n runId: z.string(),\n fnId: z.string(),\n key: z.string().exactOptional(),\n status: z.enum(RUN_STATUSES as [RunStatus, ...RunStatus[]]),\n reason: z.string().exactOptional(),\n progress: RunProgress.exactOptional(),\n log: z.array(z.string()).readonly(),\n batches: Batches,\n error: z.object({ message: z.string(), code: z.string().exactOptional() }).exactOptional(),\n startedAt: z.string(),\n finishedAt: z.string().exactOptional(),\n joined: z.boolean().exactOptional(),\n logFrom: z.number().int().nonnegative().exactOptional(),\n batchFrom: z.number().int().nonnegative().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunState\",\n description: \"An action run: status, progress, log and the result written so far.\",\n });\n\n/**\n * What changed in a run since a page last heard: a lossy notification on the event stream. Lines\n * start at `logFrom` and batches at `batchFrom`; a page that holds fewer reads the run again\n * (`runs/attach`).\n */\nexport interface RunDelta {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended so, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The index of the first line in `log`. */\n readonly logFrom: number;\n /** Log lines, starting at `logFrom`. */\n readonly log: readonly string[];\n /** The index of the first batch in `batches`. */\n readonly batchFrom: number;\n /** Result batches, starting at `batchFrom`. */\n readonly batches: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n /** When it ended. */\n readonly finishedAt?: string;\n}\n\n/** A live source's value as a page reads it (D56). */\nexport interface LiveState {\n /** The idempotency key it was started with, if any. */\n readonly key: string;\n /** The value's revision, a decimal string that only grows; absent before any value. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The latest value, serialized. */\n readonly value?: Batches;\n /**\n * Append mode (`useLive(key, { mode: \"append\" })`): the values kept in the source's ring, oldest\n * first, at most the window the page asked for.\n */\n readonly ring?: readonly {\n readonly revision: string;\n readonly at: string;\n readonly value: Batches;\n }[];\n /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */\n readonly error?: WireError;\n /**\n * `true` while the source has no value and no failure and the artifact's latest version has a\n * producer whose first `load` is on its way: the page shows it loading, and verify waits for it.\n * Absent for a key nothing produces (one only `mostra push` writes) and for a source that only\n * streams, whose first value may never come (WP-14's Opus review).\n */\n readonly awaiting?: boolean;\n}\n\n/** One live update on the event stream: never stored as an event (D63, LL-04). */\nexport interface LiveUpdate {\n /** The live source's key. */\n readonly key: string;\n /** The value's revision. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The value, serialized. */\n readonly value?: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n /**\n * `false` when a source read as {@link LiveState.awaiting} turned out to have no first `load`\n * (its producer only streams): the page stops waiting for a first value.\n */\n readonly awaiting?: boolean;\n}\n\n/**\n * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an\n * `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`: lossy, coalesced, and\n * never stored as an event.\n */\nexport type EphemeralMessage =\n | { readonly kind: \"run\"; readonly run: RunDelta }\n | { readonly kind: \"live\"; readonly live: LiveUpdate };\n\n/** `POST …/call/{fnId}`: a plain server-function call, no durable record (D54). */\nexport interface CallRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n}\n\n/** The Zod schema of the `CallRequest` type. */\nexport const CallRequest: z.ZodType<CallRequest> = z\n .object({ viewId: ViewId.schema, args: Batches })\n .register(wireRegistry, {\n id: \"CallRequest\",\n description: \"A plain server-function call: the view and the serialized arguments.\",\n });\n\n/**\n * One line of a plain call's answer (`application/x-ndjson`): a batch of the result, then the end.\n */\nexport type CallLine =\n | { readonly batch: readonly Frame[] }\n | { readonly end: { readonly status: \"succeeded\" } }\n | { readonly end: { readonly status: \"failed\"; readonly error: WireError } };\n\n/** `POST …/runs`: start a durable action run, or join one (D54, AC-02, AC-03). */\nexport interface RunRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** `<module path>#<export>`. */\n readonly fnId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n /** The author's idempotency key: one run per artifact, function and key, ever. */\n readonly key?: string;\n /** A fresh ID per invocation, so a retried request joins the run it already started. */\n readonly clientKey: string;\n}\n\n/** The Zod schema of the `RunRequest` type. */\nexport const RunRequest: z.ZodType<RunRequest> = z\n .object({\n viewId: ViewId.schema,\n fnId: z.string().min(3).max(1024),\n args: Batches,\n key: z.string().min(1).max(RUN_KEY_MAX).exactOptional(),\n clientKey: z.string().min(8).max(64),\n })\n .register(wireRegistry, {\n id: \"RunRequest\",\n description: \"Start or join an action run: the function, its arguments and keys.\",\n });\n\n/**\n * `POST …/runs/attach`: read runs and hear their changes on the event stream for the next minute\n * (re-attach after a reload, AC-02). By ID, or by function and key.\n */\nexport interface RunAttachRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** Runs by ID. */\n readonly runIds?: readonly string[];\n /** Runs by function and key. */\n readonly keyed?: readonly { readonly fnId: string; readonly key: string }[];\n /**\n * What the page already holds of runs it names by ID: so many log lines and batches. Each such\n * run's answer starts there (`RunState.logFrom`, `batchFrom`), so a page renewing its interest\n * doesn't read the whole run again (Opus review 14).\n */\n readonly held?: readonly {\n readonly runId: string;\n readonly log: number;\n readonly batches: number;\n }[];\n}\n\n/** The Zod schema of the `RunAttachRequest` type. */\nexport const RunAttachRequest: z.ZodType<RunAttachRequest> = z\n .object({\n viewId: ViewId.schema,\n runIds: z.array(z.string().max(64)).max(100).readonly().exactOptional(),\n keyed: z\n .array(\n z.object({ fnId: z.string().min(3).max(1024), key: z.string().min(1).max(RUN_KEY_MAX) }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n held: z\n .array(\n z.object({\n runId: z.string().max(64),\n log: z.number().int().nonnegative(),\n batches: z.number().int().nonnegative(),\n }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunAttachRequest\",\n description: \"Runs a page reads and follows: by ID, or by function and key.\",\n });\n\n/** `POST …/runs/{id}/cancel`. */\nexport interface RunCancelRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n}\n\n/** The Zod schema of the `RunCancelRequest` type. */\nexport const RunCancelRequest: z.ZodType<RunCancelRequest> = z\n .object({ viewId: ViewId.schema })\n .register(wireRegistry, { id: \"RunCancelRequest\", description: \"Cancel a run, from a view.\" });\n\n/** The keys of live sources: like JavaScript export names, which is what `live.ts` declares. */\nexport const LIVE_KEY_PATTERN: RegExp = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;\n\n/** The largest live value, in characters of serialized JSON (DATA_MODEL §5's 4 MiB). */\nexport const LIVE_VALUE_MAX: number = 4 * 1024 * 1024;\n\n/** The ring size of a pushed source in append mode that no `defineLive` sized. */\nexport const LIVE_RING_DEFAULT = 1024;\n\n/** The largest ring a source may keep. */\nexport const LIVE_RING_MAX = 100_000;\n\n/**\n * `POST …/live`: read live sources and keep their producers running for this view for the next\n * minute (D56, LL-04); a page asks again while it shows them.\n */\nexport interface LiveRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /**\n * The sources, each with its append window; `refresh` asks the source's producer to load again\n * now (`useLive`'s `refresh()`).\n */\n readonly keys: readonly {\n readonly key: string;\n readonly window?: number;\n readonly refresh?: boolean;\n }[];\n}\n\n/** The Zod schema of the `LiveRequest` type. */\nexport const LiveRequest: z.ZodType<LiveRequest> = z\n .object({\n viewId: ViewId.schema,\n keys: z\n .array(\n z.object({\n key: z.string().regex(LIVE_KEY_PATTERN),\n window: z.int().min(1).max(LIVE_RING_MAX).exactOptional(),\n refresh: z.boolean().exactOptional(),\n }),\n )\n .max(256)\n .readonly(),\n })\n .register(wireRegistry, {\n id: \"LiveRequest\",\n description: \"Live sources a page reads and keeps running: keys and append windows.\",\n });\n\n/** Secret names: letters, digits, `_`, `.` and `-`, starting with a letter or `_` (D44). */\nexport const SECRET_NAME_PATTERN: RegExp = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;\n\n/** The largest secret value, in UTF-8 bytes. */\nexport const SECRET_VALUE_MAX: number = 64 * 1024;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAsBA,MAAa,UAA8B,EACxC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAC5D,SAAS,CAAC,CACV,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AASH,MAAa,cAAsC,EAChD,OAAO;CACN,SAAS,EAAE,OAAO;CAClB,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,cAAc;AAClC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,kBAA0B;;AAGvC,MAAa,oBAA4B;;AAGzC,MAAa,cAAsB;;AAGnC,MAAa,oBAAoB;;AAGjC,MAAa,cAAc;;AAW3B,MAAa,eAAqC;CAChD;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,SAAgB,iBAAiB,QAA4B;CAC3D,OAAO,WAAW,eAAe,WAAW,YAAY,WAAW;AACrE;;AAmBA,MAAa,cAAsC,EAChD,OAAO;CACN,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;CACjD,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,GAAI,CAAC,CAAC,cAAc;AAC9C,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAyCH,MAAa,WAAgC,EAC1C,OAAO;CACN,OAAO,EAAE,OAAO;CAChB,MAAM,EAAE,OAAO;CACf,KAAK,EAAE,OAAO,CAAC,CAAC,cAAc;CAC9B,QAAQ,EAAE,KAAK,YAA2C;CAC1D,QAAQ,EAAE,OAAO,CAAC,CAAC,cAAc;CACjC,UAAU,YAAY,cAAc;CACpC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS;CAClC,SAAS;CACT,OAAO,EAAE,OAAO;EAAE,SAAS,EAAE,OAAO;EAAG,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAAE,CAAC,CAAC,CAAC,cAAc;CACzF,WAAW,EAAE,OAAO;CACpB,YAAY,EAAE,OAAO,CAAC,CAAC,cAAc;CACrC,QAAQ,EAAE,QAAQ,CAAC,CAAC,cAAc;CAClC,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc;CACtD,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc;AAC1D,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAiGH,MAAa,cAAsC,EAChD,OAAO;CAAE,QAAQ,OAAO;CAAQ,MAAM;AAAQ,CAAC,CAAC,CAChD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAyBH,MAAa,aAAoC,EAC9C,OAAO;CACN,QAAQ,OAAO;CACf,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;CAChC,MAAM;CACN,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,GAAe,CAAC,CAAC,cAAc;CACtD,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE;AACrC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AA0BH,MAAa,mBAAgD,EAC1D,OAAO;CACN,QAAQ,OAAO;CACf,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc;CACtE,OAAO,EACJ,MACC,EAAE,OAAO;EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;EAAG,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,GAAe;CAAE,CAAC,CACzF,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,cAAc;CACjB,MAAM,EACH,MACC,EAAE,OAAO;EACP,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE;EACxB,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY;EAClC,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY;CACxC,CAAC,CACH,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,cAAc;AACnB,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AASH,MAAa,mBAAgD,EAC1D,OAAO,EAAE,QAAQ,OAAO,OAAO,CAAC,CAAC,CACjC,SAAS,cAAc;CAAE,IAAI;CAAoB,aAAa;AAA6B,CAAC;;AAG/F,MAAa,mBAA2B;;AAGxC,MAAa,iBAAyB;;AAGtC,MAAa,oBAAoB;;AAGjC,MAAa,gBAAgB;;AAqB7B,MAAa,cAAsC,EAChD,OAAO;CACN,QAAQ,OAAO;CACf,MAAM,EACH,MACC,EAAE,OAAO;EACP,KAAK,EAAE,OAAO,CAAC,CAAC,MAAM,gBAAgB;EACtC,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,cAAc;EACxD,SAAS,EAAE,QAAQ,CAAC,CAAC,cAAc;CACrC,CAAC,CACH,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS;AACd,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,sBAA8B;;AAG3C,MAAa,mBAA2B"}
@@ -1,7 +1,7 @@
1
1
  import "../spec.js";
2
2
  //#region src/diagnostics/codes/artifact.d.ts
3
3
  /** The codes of the ARTIFACT area, in the order they were added. */
4
- export declare const artifactDiagnosticCodes: readonly ["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"];
4
+ export declare const artifactDiagnosticCodes: readonly ["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", "MOSTRA_ARTIFACT_PATH_INVALID", "MOSTRA_ARTIFACT_PATCH_REJECTED", "MOSTRA_ARTIFACT_ID_DROPPED"];
5
5
  /** The codes of the ARTIFACT area. */
6
6
  export type ArtifactDiagnosticCode = (typeof artifactDiagnosticCodes)[number];
7
7
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"artifact.d.ts","names":[],"sources":["../../../src/diagnostics/codes/artifact.ts"],"mappings":";;;qBAMa;;YAeD,iCAAiC"}
1
+ {"version":3,"file":"artifact.d.ts","names":[],"sources":["../../../src/diagnostics/codes/artifact.ts"],"mappings":";;;qBAMa;;YAkBD,iCAAiC"}
@@ -10,7 +10,10 @@ const artifactDiagnosticCodes = [
10
10
  "MOSTRA_ARTIFACT_DIR_NOT_EMPTY",
11
11
  "MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN",
12
12
  "MOSTRA_ARTIFACT_VERSION_NOT_FOUND",
13
- "MOSTRA_ARTIFACT_VERSION_COLLECTED"
13
+ "MOSTRA_ARTIFACT_VERSION_COLLECTED",
14
+ "MOSTRA_ARTIFACT_PATH_INVALID",
15
+ "MOSTRA_ARTIFACT_PATCH_REJECTED",
16
+ "MOSTRA_ARTIFACT_ID_DROPPED"
14
17
  ];
15
18
  /** The ARTIFACT area's catalog entries. */
16
19
  const artifactDiagnostics = {
@@ -113,6 +116,36 @@ const artifactDiagnostics = {
113
116
  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.",
114
117
  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."
115
118
  }
119
+ },
120
+ MOSTRA_ARTIFACT_PATH_INVALID: {
121
+ severity: "error",
122
+ phase: "host",
123
+ title: "File path outside the artifact",
124
+ hint: "Name the file by a relative path inside the artifact's directory, such as `index.tsx` or `components/chart.tsx`.",
125
+ docs: {
126
+ explanation: "`artifact_write` and `artifact_patch` change an artifact's own files, which live in its directory. A path that is absolute, climbs out with `..`, names the directory itself or passes through a link to somewhere else names no file of the artifact, so nothing is written.",
127
+ fix: "Give each file's path relative to the artifact's directory, with `/` between folders. To write elsewhere, use your own file tools."
128
+ }
129
+ },
130
+ MOSTRA_ARTIFACT_PATCH_REJECTED: {
131
+ severity: "error",
132
+ phase: "host",
133
+ title: "Patch doesn't apply",
134
+ hint: "Read the file again and send edits whose `old` text appears in it exactly once, or a diff made against its current content.",
135
+ docs: {
136
+ explanation: "An `artifact_patch` changes a file only when every edit applies: each `old` text must appear exactly once in the file as it is now, and each hunk of a unified diff must match its lines. When one doesn't, nothing is written, and the message lists each edit or hunk that didn't apply and why (not found, found more than once, the file is missing).",
137
+ fix: "Use a longer `old` text that appears only once, fix the hunk's context lines, or write the whole file with `artifact_write`."
138
+ }
139
+ },
140
+ MOSTRA_ARTIFACT_ID_DROPPED: {
141
+ severity: "warning",
142
+ phase: "host",
143
+ title: "Manifest id removed",
144
+ hint: "Put the `id: \"art_…\"` line back into the entry's `defineArtifact` (or its frontmatter), or the next publish gives the artifact a new ID.",
145
+ docs: {
146
+ explanation: "A write replaced the artifact's entry (`index.tsx`, `index.jsx` or `index.mdx`) with text that no longer names the artifact ID its manifest held. Mostra wrote it as asked. An artifact without an `id` is bound to its source path at its first publish, so a page that was never published gets a new ID there, and one that was published keeps its ID only while its path stays the same: links, waits and results named by the old ID then don't find it.",
147
+ fix: "Add the `id` back, exactly as it was (`id: \"art_01…\"` in `defineArtifact`, or `id:` in the MDX frontmatter), with `artifact_patch` or `artifact_write`."
148
+ }
116
149
  }
117
150
  };
118
151
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"artifact.js","names":[],"sources":["../../../src/diagnostics/codes/artifact.ts"],"sourcesContent":["/**\n * Diagnostic codes of the ARTIFACT area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the ARTIFACT area, in the order they were added. */\nexport const artifactDiagnosticCodes = [\n \"MOSTRA_ARTIFACT_NOT_FOUND\",\n \"MOSTRA_ARTIFACT_SOURCE_MISSING\",\n \"MOSTRA_ARTIFACT_SOURCE_UNREADABLE\",\n \"MOSTRA_ARTIFACT_NO_ENTRY\",\n \"MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS\",\n \"MOSTRA_ARTIFACT_NO_PAGE\",\n \"MOSTRA_ARTIFACT_DIR_NOT_EMPTY\",\n \"MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN\",\n \"MOSTRA_ARTIFACT_VERSION_NOT_FOUND\",\n \"MOSTRA_ARTIFACT_VERSION_COLLECTED\",\n // gen:codes\n] as const;\n\n/** The codes of the ARTIFACT area. */\nexport type ArtifactDiagnosticCode = (typeof artifactDiagnosticCodes)[number];\n\n/** The ARTIFACT area's catalog entries. */\nexport const artifactDiagnostics: AreaCatalog<ArtifactDiagnosticCode> = {\n MOSTRA_ARTIFACT_NOT_FOUND: {\n severity: \"error\",\n phase: \"host\",\n title: \"Artifact not found\",\n hint: \"Check the artifact ID or source path, or list the home's artifacts with `mostra list`.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_ARTIFACT_SOURCE_MISSING: {\n severity: \"error\",\n phase: \"publish\",\n title: \"Artifact source missing\",\n hint: \"Publish from the artifact's source path, or restore the directory the message names.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Pass the path where the source lives now. Its manifest `id`, if it has one, keeps the artifact identity at the new path.\",\n },\n },\n MOSTRA_ARTIFACT_SOURCE_UNREADABLE: {\n severity: \"error\",\n phase: \"publish\",\n title: \"Artifact source can't be read\",\n hint: \"Fix the file or directory the message names so your user can read it, then publish again.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Make the named file readable, rename one of two clashing names, or exclude the file with `.mostraignore` in the artifact's root.\",\n },\n },\n MOSTRA_ARTIFACT_NO_ENTRY: {\n severity: \"error\",\n phase: \"manifest\",\n title: \"No entry file\",\n hint: \"Add `index.tsx` or `index.mdx` to the directory, or publish a single `.tsx` or `.mdx` file.\",\n docs: {\n explanation:\n \"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.\",\n 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.',\n },\n },\n MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS: {\n severity: \"error\",\n phase: \"manifest\",\n title: \"More than one entry file\",\n hint: \"Keep one entry file in the directory and rename or remove the others.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Keep the entry you mean and rename the others, for example into `components/`.\",\n },\n },\n MOSTRA_ARTIFACT_NO_PAGE: {\n severity: \"error\",\n phase: \"manifest\",\n title: \"Entry has no page\",\n hint: \"Export the page component as the entry's default export, or add a `pages/` folder.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Add `export default function Page() { ... }` to the entry, or move pages into `pages/index.tsx`, `pages/settings.tsx` and so on.\",\n },\n },\n MOSTRA_ARTIFACT_DIR_NOT_EMPTY: {\n severity: \"error\",\n phase: \"host\",\n title: \"Directory isn't empty\",\n hint: \"Choose a new or empty directory for the artifact.\",\n docs: {\n explanation:\n \"Creating an artifact writes its entry into a directory, and the directory given already has files. Mostra never overwrites them.\",\n 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.\",\n },\n },\n MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN: {\n severity: \"error\",\n phase: \"host\",\n title: \"Unknown template\",\n hint: \"Create the artifact without a template, or use a template this Mostra release provides.\",\n docs: {\n explanation:\n \"The template named isn't one this runtime provides. Without a template, Mostra writes a minimal entry with a generated artifact ID.\",\n fix: \"Leave out the template, or use one of the templates of this release.\",\n },\n },\n MOSTRA_ARTIFACT_VERSION_NOT_FOUND: {\n severity: \"error\",\n phase: \"host\",\n title: \"No such version\",\n hint: \"Name a version the artifact has (`artifact/get` lists them), or leave the version out for the latest.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_ARTIFACT_VERSION_COLLECTED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Version collected\",\n hint: \"Open the artifact's latest version, or publish this version's source again to restore its files.\",\n docs: {\n explanation:\n \"`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.\",\n 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.\",\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,0BAA0B;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,sBAA2D;CACtE,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,gCAAgC;EAC9B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,iCAAiC;EAC/B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,+BAA+B;EAC7B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,kCAAkC;EAChC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
1
+ {"version":3,"file":"artifact.js","names":[],"sources":["../../../src/diagnostics/codes/artifact.ts"],"sourcesContent":["/**\n * Diagnostic codes of the ARTIFACT area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the ARTIFACT area, in the order they were added. */\nexport const artifactDiagnosticCodes = [\n \"MOSTRA_ARTIFACT_NOT_FOUND\",\n \"MOSTRA_ARTIFACT_SOURCE_MISSING\",\n \"MOSTRA_ARTIFACT_SOURCE_UNREADABLE\",\n \"MOSTRA_ARTIFACT_NO_ENTRY\",\n \"MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS\",\n \"MOSTRA_ARTIFACT_NO_PAGE\",\n \"MOSTRA_ARTIFACT_DIR_NOT_EMPTY\",\n \"MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN\",\n \"MOSTRA_ARTIFACT_VERSION_NOT_FOUND\",\n \"MOSTRA_ARTIFACT_VERSION_COLLECTED\",\n \"MOSTRA_ARTIFACT_PATH_INVALID\",\n \"MOSTRA_ARTIFACT_PATCH_REJECTED\",\n \"MOSTRA_ARTIFACT_ID_DROPPED\",\n // gen:codes\n] as const;\n\n/** The codes of the ARTIFACT area. */\nexport type ArtifactDiagnosticCode = (typeof artifactDiagnosticCodes)[number];\n\n/** The ARTIFACT area's catalog entries. */\nexport const artifactDiagnostics: AreaCatalog<ArtifactDiagnosticCode> = {\n MOSTRA_ARTIFACT_NOT_FOUND: {\n severity: \"error\",\n phase: \"host\",\n title: \"Artifact not found\",\n hint: \"Check the artifact ID or source path, or list the home's artifacts with `mostra list`.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_ARTIFACT_SOURCE_MISSING: {\n severity: \"error\",\n phase: \"publish\",\n title: \"Artifact source missing\",\n hint: \"Publish from the artifact's source path, or restore the directory the message names.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Pass the path where the source lives now. Its manifest `id`, if it has one, keeps the artifact identity at the new path.\",\n },\n },\n MOSTRA_ARTIFACT_SOURCE_UNREADABLE: {\n severity: \"error\",\n phase: \"publish\",\n title: \"Artifact source can't be read\",\n hint: \"Fix the file or directory the message names so your user can read it, then publish again.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Make the named file readable, rename one of two clashing names, or exclude the file with `.mostraignore` in the artifact's root.\",\n },\n },\n MOSTRA_ARTIFACT_NO_ENTRY: {\n severity: \"error\",\n phase: \"manifest\",\n title: \"No entry file\",\n hint: \"Add `index.tsx` or `index.mdx` to the directory, or publish a single `.tsx` or `.mdx` file.\",\n docs: {\n explanation:\n \"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.\",\n 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.',\n },\n },\n MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS: {\n severity: \"error\",\n phase: \"manifest\",\n title: \"More than one entry file\",\n hint: \"Keep one entry file in the directory and rename or remove the others.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Keep the entry you mean and rename the others, for example into `components/`.\",\n },\n },\n MOSTRA_ARTIFACT_NO_PAGE: {\n severity: \"error\",\n phase: \"manifest\",\n title: \"Entry has no page\",\n hint: \"Export the page component as the entry's default export, or add a `pages/` folder.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Add `export default function Page() { ... }` to the entry, or move pages into `pages/index.tsx`, `pages/settings.tsx` and so on.\",\n },\n },\n MOSTRA_ARTIFACT_DIR_NOT_EMPTY: {\n severity: \"error\",\n phase: \"host\",\n title: \"Directory isn't empty\",\n hint: \"Choose a new or empty directory for the artifact.\",\n docs: {\n explanation:\n \"Creating an artifact writes its entry into a directory, and the directory given already has files. Mostra never overwrites them.\",\n 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.\",\n },\n },\n MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN: {\n severity: \"error\",\n phase: \"host\",\n title: \"Unknown template\",\n hint: \"Create the artifact without a template, or use a template this Mostra release provides.\",\n docs: {\n explanation:\n \"The template named isn't one this runtime provides. Without a template, Mostra writes a minimal entry with a generated artifact ID.\",\n fix: \"Leave out the template, or use one of the templates of this release.\",\n },\n },\n MOSTRA_ARTIFACT_VERSION_NOT_FOUND: {\n severity: \"error\",\n phase: \"host\",\n title: \"No such version\",\n hint: \"Name a version the artifact has (`artifact/get` lists them), or leave the version out for the latest.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_ARTIFACT_VERSION_COLLECTED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Version collected\",\n hint: \"Open the artifact's latest version, or publish this version's source again to restore its files.\",\n docs: {\n explanation:\n \"`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.\",\n 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.\",\n },\n },\n MOSTRA_ARTIFACT_PATH_INVALID: {\n severity: \"error\",\n phase: \"host\",\n title: \"File path outside the artifact\",\n hint: \"Name the file by a relative path inside the artifact's directory, such as `index.tsx` or `components/chart.tsx`.\",\n docs: {\n explanation:\n \"`artifact_write` and `artifact_patch` change an artifact's own files, which live in its directory. A path that is absolute, climbs out with `..`, names the directory itself or passes through a link to somewhere else names no file of the artifact, so nothing is written.\",\n fix: \"Give each file's path relative to the artifact's directory, with `/` between folders. To write elsewhere, use your own file tools.\",\n },\n },\n MOSTRA_ARTIFACT_PATCH_REJECTED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Patch doesn't apply\",\n hint: \"Read the file again and send edits whose `old` text appears in it exactly once, or a diff made against its current content.\",\n docs: {\n explanation:\n \"An `artifact_patch` changes a file only when every edit applies: each `old` text must appear exactly once in the file as it is now, and each hunk of a unified diff must match its lines. When one doesn't, nothing is written, and the message lists each edit or hunk that didn't apply and why (not found, found more than once, the file is missing).\",\n fix: \"Use a longer `old` text that appears only once, fix the hunk's context lines, or write the whole file with `artifact_write`.\",\n },\n },\n MOSTRA_ARTIFACT_ID_DROPPED: {\n severity: \"warning\",\n phase: \"host\",\n title: \"Manifest id removed\",\n hint: 'Put the `id: \"art_…\"` line back into the entry\\'s `defineArtifact` (or its frontmatter), or the next publish gives the artifact a new ID.',\n docs: {\n explanation:\n \"A write replaced the artifact's entry (`index.tsx`, `index.jsx` or `index.mdx`) with text that no longer names the artifact ID its manifest held. Mostra wrote it as asked. An artifact without an `id` is bound to its source path at its first publish, so a page that was never published gets a new ID there, and one that was published keeps its ID only while its path stays the same: links, waits and results named by the old ID then don't find it.\",\n fix: 'Add the `id` back, exactly as it was (`id: \"art_01…\"` in `defineArtifact`, or `id:` in the MDX frontmatter), with `artifact_patch` or `artifact_write`.',\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,0BAA0B;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,sBAA2D;CACtE,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,gCAAgC;EAC9B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,iCAAiC;EAC/B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,+BAA+B;EAC7B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,kCAAkC;EAChC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,gCAAgC;EAC9B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
@@ -1,7 +1,7 @@
1
1
  import "../spec.js";
2
2
  //#region src/diagnostics/codes/env.d.ts
3
3
  /** The codes of the ENV area, in the order they were added. */
4
- export declare const envDiagnosticCodes: readonly ["MOSTRA_ENV_WARM_MISSING", "MOSTRA_ENV_PORT_TAKEN", "MOSTRA_ENV_BIND_FAILED", "MOSTRA_ENV_SHELL_MISSING", "MOSTRA_ENV_SERVICE_FAILED", "MOSTRA_ENV_BROWSER_MISSING", "MOSTRA_ENV_RUNTIME_MISSING", "MOSTRA_ENV_BUNDLE_INVALID", "MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", "MOSTRA_ENV_BUNDLE_UNAVAILABLE", "MOSTRA_ENV_NODE_UNSUPPORTED", "MOSTRA_ENV_HELPER_MISSING"];
4
+ export declare const envDiagnosticCodes: readonly ["MOSTRA_ENV_WARM_MISSING", "MOSTRA_ENV_PORT_TAKEN", "MOSTRA_ENV_BIND_FAILED", "MOSTRA_ENV_SHELL_MISSING", "MOSTRA_ENV_SERVICE_FAILED", "MOSTRA_ENV_BROWSER_MISSING", "MOSTRA_ENV_RUNTIME_MISSING", "MOSTRA_ENV_BUNDLE_INVALID", "MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", "MOSTRA_ENV_BUNDLE_UNAVAILABLE", "MOSTRA_ENV_NODE_UNSUPPORTED", "MOSTRA_ENV_HELPER_MISSING", "MOSTRA_ENV_RUNTIME_INSTALLING"];
5
5
  /** The codes of the ENV area. */
6
6
  export type EnvDiagnosticCode = (typeof envDiagnosticCodes)[number];
7
7
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"env.d.ts","names":[],"sources":["../../../src/diagnostics/codes/env.ts"],"mappings":";;;qBAMa;;YAiBD,4BAA4B"}
1
+ {"version":3,"file":"env.d.ts","names":[],"sources":["../../../src/diagnostics/codes/env.ts"],"mappings":";;;qBAMa;;YAkBD,4BAA4B"}
@@ -12,7 +12,8 @@ const envDiagnosticCodes = [
12
12
  "MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED",
13
13
  "MOSTRA_ENV_BUNDLE_UNAVAILABLE",
14
14
  "MOSTRA_ENV_NODE_UNSUPPORTED",
15
- "MOSTRA_ENV_HELPER_MISSING"
15
+ "MOSTRA_ENV_HELPER_MISSING",
16
+ "MOSTRA_ENV_RUNTIME_INSTALLING"
16
17
  ];
17
18
  /** The ENV area's catalog entries. */
18
19
  const envDiagnostics = {
@@ -135,6 +136,16 @@ const envDiagnostics = {
135
136
  explanation: "On Windows the runtime runs `mostra-win.exe`, a helper that ships with it, for what Node.js can't do there: owner-only access to the home, the home's control pipe, and every child process in a Job Object. The runtime looked for it at `MOSTRA_WIN_HELPER`, in its runtime bundle, and in a development checkout's Cargo build, and found none, so it stopped before touching the home.",
136
137
  fix: "Reinstall Mostra so the runtime bundle is complete. In a development checkout, build the helper with `cargo build -p mostra-win`. A custom layout can point the runtime at the helper with `MOSTRA_WIN_HELPER`."
137
138
  }
139
+ },
140
+ MOSTRA_ENV_RUNTIME_INSTALLING: {
141
+ severity: "error",
142
+ phase: "host",
143
+ title: "Runtime still installing",
144
+ hint: "Call the tool again in a minute: Mostra keeps installing its runtime meanwhile.",
145
+ docs: {
146
+ explanation: "`mostra mcp` installed from npm answers its client at once and installs its release's runtime bundle in the background on its first start (about 200 MB, D164 item 7), so a client's startup timeout never waits for the download. A tool that needs the instance waits for that install, up to 45 seconds per call; this call's time ran out first. The install goes on, and the message says how far it is. Tools that need no instance (`docs_search`, `artifact_write`, `artifact_patch`) work during it.",
147
+ fix: "Call the tool again once the install has had time to finish. When it fails instead, the next call says why (`MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`, `MOSTRA_ENV_BUNDLE_UNAVAILABLE` offline) and starts it again."
148
+ }
138
149
  }
139
150
  };
140
151
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"env.js","names":[],"sources":["../../../src/diagnostics/codes/env.ts"],"sourcesContent":["/**\n * Diagnostic codes of the ENV area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the ENV area, in the order they were added. */\nexport const envDiagnosticCodes = [\n \"MOSTRA_ENV_WARM_MISSING\",\n \"MOSTRA_ENV_PORT_TAKEN\",\n \"MOSTRA_ENV_BIND_FAILED\",\n \"MOSTRA_ENV_SHELL_MISSING\",\n \"MOSTRA_ENV_SERVICE_FAILED\",\n \"MOSTRA_ENV_BROWSER_MISSING\",\n \"MOSTRA_ENV_RUNTIME_MISSING\",\n \"MOSTRA_ENV_BUNDLE_INVALID\",\n \"MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED\",\n \"MOSTRA_ENV_BUNDLE_UNAVAILABLE\",\n \"MOSTRA_ENV_NODE_UNSUPPORTED\",\n \"MOSTRA_ENV_HELPER_MISSING\",\n // gen:codes\n] as const;\n\n/** The codes of the ENV area. */\nexport type EnvDiagnosticCode = (typeof envDiagnosticCodes)[number];\n\n/** The ENV area's catalog entries. */\nexport const envDiagnostics: AreaCatalog<EnvDiagnosticCode> = {\n MOSTRA_ENV_WARM_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Warm package set missing\",\n hint: \"Reinstall the Mostra runtime, or set `MOSTRA_WARM_DIR` to its warm package set.\",\n docs: {\n explanation:\n \"Builds resolve React, Tailwind and Mostra's own client packages from the warm package set that ships with the runtime. The runtime couldn't find it, which means the runtime installation is incomplete.\",\n fix: \"Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the warm set's directory with `MOSTRA_WARM_DIR`.\",\n },\n },\n MOSTRA_ENV_PORT_TAKEN: {\n severity: \"warning\",\n phase: \"host\",\n title: \"Leased port taken\",\n hint: \"Open the artifact through a new link: `view/url` or `mostra open` mints one on the new port.\",\n docs: {\n explanation:\n \"The shell's port or an artifact's port is leased per home and reused across restarts, so links keep working (D62, D99). At start-up another program held the leased port, so Mostra leased a new one. Links that named the old port stop working; the shell's port changing affects every link of the home.\",\n fix: \"Mint new links with `view/url` (the publish receipt of the next publish carries the new default link too). Stop the program that took the port if you want the old links back; `mostra doctor` names it where it can.\",\n },\n },\n MOSTRA_ENV_BIND_FAILED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Gateway can't bind\",\n hint: \"Start Mostra with an address this machine has, or without `--bind` to use the loopback address.\",\n docs: {\n explanation:\n \"The gateway couldn't listen on the address it was given: `--bind` named an address no interface has, a wildcard bind came without `--url-host`, or the operating system refused the address. Mostra doesn't start rather than serve on an address nobody asked for.\",\n fix: \"Omit `--bind` to serve on `127.0.0.1` only (the default). For a wider bind, pass an address of one of this machine's interfaces, and with `0.0.0.0` or `::` also `--url-host <name>`, the name viewers use to reach it.\",\n },\n },\n MOSTRA_ENV_SHELL_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Shell app missing\",\n hint: \"Reinstall the Mostra runtime, or set `MOSTRA_SHELL_DIR` to its built shell.\",\n docs: {\n explanation:\n \"Viewers open artifacts inside the shell, Mostra's trusted page, which ships with the runtime as built files. The runtime couldn't find them, which means the runtime installation is incomplete. Artifact frames are still served.\",\n fix: \"Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the shell's built directory with `MOSTRA_SHELL_DIR`.\",\n },\n },\n MOSTRA_ENV_SERVICE_FAILED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Login service could not be installed\",\n hint: \"Read the message, fix what it names, and run the install again.\",\n docs: {\n explanation:\n \"`mostra daemon install` couldn't register the home's daemon as a login service: writing the launchd agent, systemd user unit or Task Scheduler task failed, or `launchctl`, `systemctl --user` or `schtasks` refused it.\",\n fix: \"Check the named file's directory permissions; on Linux, that a systemd user session is running (`systemctl --user status`); on Windows, that Task Scheduler runs and your account may create tasks (`schtasks /Query`). On a machine without one, start the daemon from your own login scripts with `mostra daemon start`.\",\n },\n },\n MOSTRA_ENV_BROWSER_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Browser for verify missing\",\n hint: \"Run the runtime bundle's `bin/mostra-setup` (with network access) to fetch the browser verify uses, then verify again.\",\n docs: {\n explanation:\n \"Verify renders pages in the Chromium headless shell its Playwright release pins. The runtime bundle fetches that browser when it is set up and checks every file of it (D142). It wasn't there, so verify ran only the stages that need no browser (type check, build and the field-ID scan) and reported this error. Publishing needs `--force` until it is installed.\",\n fix: \"Run `bin/mostra-setup` in the runtime bundle's directory (the message names it) with network access; it fetches and checks the pinned browser. Outside a bundle, in a development checkout, run `npx playwright-core install chromium-headless-shell`. Then verify again.\",\n },\n },\n MOSTRA_ENV_RUNTIME_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Runtime not found\",\n hint: \"Reinstall Mostra, or set `MOSTRA_RUNTIME_BIN` to the runtime's `mostra-runtime` entry.\",\n docs: {\n explanation:\n \"The CLI starts and attaches to the home's instance through the runtime binary (`mostra-runtime`, D85). It looked, in order, for `MOSTRA_BUNDLE`, `MOSTRA_RUNTIME_BIN`, the runtime bundle it runs from, its release's pinned bundle and a development checkout's built runtime (D142), and found nothing it could run: here, `MOSTRA_RUNTIME_BIN` names a file that doesn't exist, or the runtime couldn't be started.\",\n fix: \"Unset `MOSTRA_RUNTIME_BIN` or point it at a `mostra-runtime` entry (its `dist/bin.js`), or reinstall Mostra so the CLI and its runtime are complete.\",\n },\n },\n MOSTRA_ENV_BUNDLE_INVALID: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Runtime bundle failed verification\",\n hint: \"Nothing was installed; install Mostra again, and if it fails the same way, report it with the message.\",\n docs: {\n explanation:\n \"Mostra checks every runtime bundle before it runs anything from it: the archive against the SHA-256 the installing package pins, then each extracted file against the bundle's own file list, and the verify browser against the bundle's browser pin. One of them differed, so the download was corrupted, changed on the way or replaced, and Mostra refused it. A bundle already installed that fails a later check (`mostra doctor --deep`) is refused the same way.\",\n fix: \"Run the install again (`npm create mostra`, or the command that started it), which downloads a fresh copy. When a mirror is configured (`MOSTRA_BUNDLE_MIRROR`), check that it serves the release's files unchanged. Check a file you downloaded yourself against the release's `SHA256SUMS`, or with `gh attestation verify <file> --repo mostra-dev/mostra`.\",\n },\n },\n MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Runtime bundle download failed\",\n hint: \"Check the network or proxy (`HTTPS_PROXY`), then run the command again: a retry starts the download over.\",\n docs: {\n explanation:\n \"The runtime bundle for this release and platform isn't in the local cache yet, and fetching it failed: the network or a proxy refused it, the server answered with an error, the connection stalled for 60 seconds, or the disk ran out of space while it was written. Nothing partial is kept.\",\n fix: \"Check the connection, and set `HTTPS_PROXY` (and `NO_PROXY`) when the network needs a proxy. Behind a firewall that blocks GitHub, host the release's files on a reachable server and set `MOSTRA_BUNDLE_MIRROR` to its base URL (a `file:` URL works for a local directory). Free space in the cache directory (`MOSTRA_CACHE_DIR`) if the message says the disk is full.\",\n },\n },\n MOSTRA_ENV_BUNDLE_UNAVAILABLE: {\n severity: \"error\",\n phase: \"platform\",\n title: \"No runtime bundle available\",\n hint: \"Run this once with network access, or point `MOSTRA_BUNDLE` at an extracted bundle.\",\n docs: {\n explanation:\n \"Mostra runs on its own runtime bundle, found in the local cache, beside the installed package or at `MOSTRA_BUNDLE`. None was there, and no download could start: Mostra is offline (`MOSTRA_OFFLINE`), this build of the package pins no bundle for this platform, or the platform has none.\",\n fix: \"Run the command once with network access and without `MOSTRA_OFFLINE`, so the pinned bundle is fetched and cached; later runs work offline. On a machine without network access, extract the release's archive for the platform and set `MOSTRA_BUNDLE` to its directory. A development checkout uses its own built runtime instead.\",\n },\n },\n MOSTRA_ENV_NODE_UNSUPPORTED: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Node.js too old to start Mostra\",\n hint: \"Run `mostra` with Node.js 22.19 or later, or run the runtime bundle's own `bin/mostra`, which needs no Node.js.\",\n docs: {\n explanation:\n \"A `mostra` (or `npm create mostra`) installed from npm starts on the machine's Node.js only long enough to find its runtime bundle, then every Mostra process runs on the bundle's own Node.js (RT-01, D142). That start needs Node.js 22.19 or later, and this one is older, so Mostra stopped before loading anything.\",\n fix: \"Upgrade the machine's Node.js to 22.19 or later, or run Mostra without npm: download the runtime bundle for your platform from the GitHub release, check it against `SHA256SUMS`, extract it, run its `bin/mostra-setup` once, then use its `bin/mostra`.\",\n },\n },\n MOSTRA_ENV_HELPER_MISSING: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Windows helper missing\",\n hint: \"Reinstall Mostra, or set `MOSTRA_WIN_HELPER` to its `mostra-win.exe`.\",\n docs: {\n explanation:\n \"On Windows the runtime runs `mostra-win.exe`, a helper that ships with it, for what Node.js can't do there: owner-only access to the home, the home's control pipe, and every child process in a Job Object. The runtime looked for it at `MOSTRA_WIN_HELPER`, in its runtime bundle, and in a development checkout's Cargo build, and found none, so it stopped before touching the home.\",\n fix: \"Reinstall Mostra so the runtime bundle is complete. In a development checkout, build the helper with `cargo build -p mostra-win`. A custom layout can point the runtime at the helper with `MOSTRA_WIN_HELPER`.\",\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,qBAAqB;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,iBAAiD;CAC5D,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,wBAAwB;EACtB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,+BAA+B;EAC7B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,6BAA6B;EAC3B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
1
+ {"version":3,"file":"env.js","names":[],"sources":["../../../src/diagnostics/codes/env.ts"],"sourcesContent":["/**\n * Diagnostic codes of the ENV area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the ENV area, in the order they were added. */\nexport const envDiagnosticCodes = [\n \"MOSTRA_ENV_WARM_MISSING\",\n \"MOSTRA_ENV_PORT_TAKEN\",\n \"MOSTRA_ENV_BIND_FAILED\",\n \"MOSTRA_ENV_SHELL_MISSING\",\n \"MOSTRA_ENV_SERVICE_FAILED\",\n \"MOSTRA_ENV_BROWSER_MISSING\",\n \"MOSTRA_ENV_RUNTIME_MISSING\",\n \"MOSTRA_ENV_BUNDLE_INVALID\",\n \"MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED\",\n \"MOSTRA_ENV_BUNDLE_UNAVAILABLE\",\n \"MOSTRA_ENV_NODE_UNSUPPORTED\",\n \"MOSTRA_ENV_HELPER_MISSING\",\n \"MOSTRA_ENV_RUNTIME_INSTALLING\",\n // gen:codes\n] as const;\n\n/** The codes of the ENV area. */\nexport type EnvDiagnosticCode = (typeof envDiagnosticCodes)[number];\n\n/** The ENV area's catalog entries. */\nexport const envDiagnostics: AreaCatalog<EnvDiagnosticCode> = {\n MOSTRA_ENV_WARM_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Warm package set missing\",\n hint: \"Reinstall the Mostra runtime, or set `MOSTRA_WARM_DIR` to its warm package set.\",\n docs: {\n explanation:\n \"Builds resolve React, Tailwind and Mostra's own client packages from the warm package set that ships with the runtime. The runtime couldn't find it, which means the runtime installation is incomplete.\",\n fix: \"Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the warm set's directory with `MOSTRA_WARM_DIR`.\",\n },\n },\n MOSTRA_ENV_PORT_TAKEN: {\n severity: \"warning\",\n phase: \"host\",\n title: \"Leased port taken\",\n hint: \"Open the artifact through a new link: `view/url` or `mostra open` mints one on the new port.\",\n docs: {\n explanation:\n \"The shell's port or an artifact's port is leased per home and reused across restarts, so links keep working (D62, D99). At start-up another program held the leased port, so Mostra leased a new one. Links that named the old port stop working; the shell's port changing affects every link of the home.\",\n fix: \"Mint new links with `view/url` (the publish receipt of the next publish carries the new default link too). Stop the program that took the port if you want the old links back; `mostra doctor` names it where it can.\",\n },\n },\n MOSTRA_ENV_BIND_FAILED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Gateway can't bind\",\n hint: \"Start Mostra with an address this machine has, or without `--bind` to use the loopback address.\",\n docs: {\n explanation:\n \"The gateway couldn't listen on the address it was given: `--bind` named an address no interface has, a wildcard bind came without `--url-host`, or the operating system refused the address. Mostra doesn't start rather than serve on an address nobody asked for.\",\n fix: \"Omit `--bind` to serve on `127.0.0.1` only (the default). For a wider bind, pass an address of one of this machine's interfaces, and with `0.0.0.0` or `::` also `--url-host <name>`, the name viewers use to reach it.\",\n },\n },\n MOSTRA_ENV_SHELL_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Shell app missing\",\n hint: \"Reinstall the Mostra runtime, or set `MOSTRA_SHELL_DIR` to its built shell.\",\n docs: {\n explanation:\n \"Viewers open artifacts inside the shell, Mostra's trusted page, which ships with the runtime as built files. The runtime couldn't find them, which means the runtime installation is incomplete. Artifact frames are still served.\",\n fix: \"Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the shell's built directory with `MOSTRA_SHELL_DIR`.\",\n },\n },\n MOSTRA_ENV_SERVICE_FAILED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Login service could not be installed\",\n hint: \"Read the message, fix what it names, and run the install again.\",\n docs: {\n explanation:\n \"`mostra daemon install` couldn't register the home's daemon as a login service: writing the launchd agent, systemd user unit or Task Scheduler task failed, or `launchctl`, `systemctl --user` or `schtasks` refused it.\",\n fix: \"Check the named file's directory permissions; on Linux, that a systemd user session is running (`systemctl --user status`); on Windows, that Task Scheduler runs and your account may create tasks (`schtasks /Query`). On a machine without one, start the daemon from your own login scripts with `mostra daemon start`.\",\n },\n },\n MOSTRA_ENV_BROWSER_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Browser for verify missing\",\n hint: \"Run the runtime bundle's `bin/mostra-setup` (with network access) to fetch the browser verify uses, then verify again.\",\n docs: {\n explanation:\n \"Verify renders pages in the Chromium headless shell its Playwright release pins. The runtime bundle fetches that browser when it is set up and checks every file of it (D142). It wasn't there, so verify ran only the stages that need no browser (type check, build and the field-ID scan) and reported this error. Publishing needs `--force` until it is installed.\",\n fix: \"Run `bin/mostra-setup` in the runtime bundle's directory (the message names it) with network access; it fetches and checks the pinned browser. Outside a bundle, in a development checkout, run `npx playwright-core install chromium-headless-shell`. Then verify again.\",\n },\n },\n MOSTRA_ENV_RUNTIME_MISSING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Runtime not found\",\n hint: \"Reinstall Mostra, or set `MOSTRA_RUNTIME_BIN` to the runtime's `mostra-runtime` entry.\",\n docs: {\n explanation:\n \"The CLI starts and attaches to the home's instance through the runtime binary (`mostra-runtime`, D85). It looked, in order, for `MOSTRA_BUNDLE`, `MOSTRA_RUNTIME_BIN`, the runtime bundle it runs from, its release's pinned bundle and a development checkout's built runtime (D142), and found nothing it could run: here, `MOSTRA_RUNTIME_BIN` names a file that doesn't exist, or the runtime couldn't be started.\",\n fix: \"Unset `MOSTRA_RUNTIME_BIN` or point it at a `mostra-runtime` entry (its `dist/bin.js`), or reinstall Mostra so the CLI and its runtime are complete.\",\n },\n },\n MOSTRA_ENV_BUNDLE_INVALID: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Runtime bundle failed verification\",\n hint: \"Nothing was installed; install Mostra again, and if it fails the same way, report it with the message.\",\n docs: {\n explanation:\n \"Mostra checks every runtime bundle before it runs anything from it: the archive against the SHA-256 the installing package pins, then each extracted file against the bundle's own file list, and the verify browser against the bundle's browser pin. One of them differed, so the download was corrupted, changed on the way or replaced, and Mostra refused it. A bundle already installed that fails a later check (`mostra doctor --deep`) is refused the same way.\",\n fix: \"Run the install again (`npm create mostra`, or the command that started it), which downloads a fresh copy. When a mirror is configured (`MOSTRA_BUNDLE_MIRROR`), check that it serves the release's files unchanged. Check a file you downloaded yourself against the release's `SHA256SUMS`, or with `gh attestation verify <file> --repo mostra-dev/mostra`.\",\n },\n },\n MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Runtime bundle download failed\",\n hint: \"Check the network or proxy (`HTTPS_PROXY`), then run the command again: a retry starts the download over.\",\n docs: {\n explanation:\n \"The runtime bundle for this release and platform isn't in the local cache yet, and fetching it failed: the network or a proxy refused it, the server answered with an error, the connection stalled for 60 seconds, or the disk ran out of space while it was written. Nothing partial is kept.\",\n fix: \"Check the connection, and set `HTTPS_PROXY` (and `NO_PROXY`) when the network needs a proxy. Behind a firewall that blocks GitHub, host the release's files on a reachable server and set `MOSTRA_BUNDLE_MIRROR` to its base URL (a `file:` URL works for a local directory). Free space in the cache directory (`MOSTRA_CACHE_DIR`) if the message says the disk is full.\",\n },\n },\n MOSTRA_ENV_BUNDLE_UNAVAILABLE: {\n severity: \"error\",\n phase: \"platform\",\n title: \"No runtime bundle available\",\n hint: \"Run this once with network access, or point `MOSTRA_BUNDLE` at an extracted bundle.\",\n docs: {\n explanation:\n \"Mostra runs on its own runtime bundle, found in the local cache, beside the installed package or at `MOSTRA_BUNDLE`. None was there, and no download could start: Mostra is offline (`MOSTRA_OFFLINE`), this build of the package pins no bundle for this platform, or the platform has none.\",\n fix: \"Run the command once with network access and without `MOSTRA_OFFLINE`, so the pinned bundle is fetched and cached; later runs work offline. On a machine without network access, extract the release's archive for the platform and set `MOSTRA_BUNDLE` to its directory. A development checkout uses its own built runtime instead.\",\n },\n },\n MOSTRA_ENV_NODE_UNSUPPORTED: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Node.js too old to start Mostra\",\n hint: \"Run `mostra` with Node.js 22.19 or later, or run the runtime bundle's own `bin/mostra`, which needs no Node.js.\",\n docs: {\n explanation:\n \"A `mostra` (or `npm create mostra`) installed from npm starts on the machine's Node.js only long enough to find its runtime bundle, then every Mostra process runs on the bundle's own Node.js (RT-01, D142). That start needs Node.js 22.19 or later, and this one is older, so Mostra stopped before loading anything.\",\n fix: \"Upgrade the machine's Node.js to 22.19 or later, or run Mostra without npm: download the runtime bundle for your platform from the GitHub release, check it against `SHA256SUMS`, extract it, run its `bin/mostra-setup` once, then use its `bin/mostra`.\",\n },\n },\n MOSTRA_ENV_HELPER_MISSING: {\n severity: \"error\",\n phase: \"platform\",\n title: \"Windows helper missing\",\n hint: \"Reinstall Mostra, or set `MOSTRA_WIN_HELPER` to its `mostra-win.exe`.\",\n docs: {\n explanation:\n \"On Windows the runtime runs `mostra-win.exe`, a helper that ships with it, for what Node.js can't do there: owner-only access to the home, the home's control pipe, and every child process in a Job Object. The runtime looked for it at `MOSTRA_WIN_HELPER`, in its runtime bundle, and in a development checkout's Cargo build, and found none, so it stopped before touching the home.\",\n fix: \"Reinstall Mostra so the runtime bundle is complete. In a development checkout, build the helper with `cargo build -p mostra-win`. A custom layout can point the runtime at the helper with `MOSTRA_WIN_HELPER`.\",\n },\n },\n MOSTRA_ENV_RUNTIME_INSTALLING: {\n severity: \"error\",\n phase: \"host\",\n title: \"Runtime still installing\",\n hint: \"Call the tool again in a minute: Mostra keeps installing its runtime meanwhile.\",\n docs: {\n explanation:\n \"`mostra mcp` installed from npm answers its client at once and installs its release's runtime bundle in the background on its first start (about 200 MB, D164 item 7), so a client's startup timeout never waits for the download. A tool that needs the instance waits for that install, up to 45 seconds per call; this call's time ran out first. The install goes on, and the message says how far it is. Tools that need no instance (`docs_search`, `artifact_write`, `artifact_patch`) work during it.\",\n fix: \"Call the tool again once the install has had time to finish. When it fails instead, the next call says why (`MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`, `MOSTRA_ENV_BUNDLE_UNAVAILABLE` offline) and starts it again.\",\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,qBAAqB;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,iBAAiD;CAC5D,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,wBAAwB;EACtB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,+BAA+B;EAC7B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,6BAA6B;EAC3B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,+BAA+B;EAC7B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
@@ -46,10 +46,10 @@ const submitDiagnostics = {
46
46
  severity: "error",
47
47
  phase: "runtime",
48
48
  title: "No such submission",
49
- hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.",
49
+ hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or, when the message says the policy is none, read `mostra state get <artifact>` or wait for a signal with `--until signal:<name>`.",
50
50
  docs: {
51
- 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).",
52
- 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."
51
+ 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). An artifact whose submission policy is `none` never has one, and the message says so: its viewers' work is in its shared state, its signals and its action runs.",
52
+ 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. Under policy `none`, read the shared state with `mostra state get <artifact>`, or wait for a signal the page raises with `mostra wait <artifact> --until signal:<name>`: its event carries the signal's payload."
53
53
  }
54
54
  },
55
55
  MOSTRA_SUBMIT_VIEW_INVALID: {
@@ -1 +1 @@
1
- {"version":3,"file":"submit.js","names":[],"sources":["../../../src/diagnostics/codes/submit.ts"],"sourcesContent":["/**\n * Diagnostic codes of the SUBMIT area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the SUBMIT area, in the order they were added. */\nexport const submitDiagnosticCodes = [\n \"MOSTRA_SUBMIT_ALREADY\",\n \"MOSTRA_SUBMIT_REVISION_MOVED\",\n \"MOSTRA_SUBMIT_POLICY_NONE\",\n \"MOSTRA_SUBMIT_NOT_FOUND\",\n \"MOSTRA_SUBMIT_VIEW_INVALID\",\n \"MOSTRA_SUBMIT_SIGNAL_INVALID\",\n \"MOSTRA_SUBMIT_CHANNEL_DENIED\",\n \"MOSTRA_SUBMIT_BLOCKED\",\n // gen:codes\n] as const;\n\n/** The codes of the SUBMIT area. */\nexport type SubmitDiagnosticCode = (typeof submitDiagnosticCodes)[number];\n\n/** The SUBMIT area's catalog entries. */\nexport const submitDiagnostics: AreaCatalog<SubmitDiagnosticCode> = {\n MOSTRA_SUBMIT_ALREADY: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Already submitted\",\n hint: \"This artifact takes one submission, and it was made; read it with `mostra results`.\",\n docs: {\n explanation:\n \"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.\",\n 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.',\n },\n },\n MOSTRA_SUBMIT_REVISION_MOVED: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Draft changed before submit\",\n hint: \"Reload the draft, check what changed, and submit again with its current revision.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_SUBMIT_POLICY_NONE: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Artifact takes no submissions\",\n hint: \"Exchange data through artifact state, actions and signals; this artifact has no submissions.\",\n docs: {\n explanation:\n \"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.\",\n 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`.\",\n },\n },\n MOSTRA_SUBMIT_NOT_FOUND: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"No such submission\",\n hint: \"Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.\",\n docs: {\n explanation:\n \"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).\",\n 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.\",\n },\n },\n MOSTRA_SUBMIT_VIEW_INVALID: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Unknown view\",\n hint: \"Send the view ID this page was opened with.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Use the `viewId` the shell handed this frame. A page opened outside Mostra's shell has no view and can't submit.\",\n },\n },\n MOSTRA_SUBMIT_SIGNAL_INVALID: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Invalid signal\",\n hint: \"Name signals with letters, digits, `.`, `_` and `-`, and keep their payload under 64 KiB of JSON.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Rename the signal or shrink its payload; put large data into a field or artifact state and send its ID in the payload.\",\n },\n },\n MOSTRA_SUBMIT_CHANNEL_DENIED: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Submit channel not allowed\",\n hint: \"Let the viewer submit with the shell's trusted Submit; this host doesn't take submissions from artifact code.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_SUBMIT_BLOCKED: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Answers missing before submit\",\n hint: \"Fill in the fields this diagnostic lists, fix their errors or resolve their conflicts, then submit again.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,oBAAuD;CAClE,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
1
+ {"version":3,"file":"submit.js","names":[],"sources":["../../../src/diagnostics/codes/submit.ts"],"sourcesContent":["/**\n * Diagnostic codes of the SUBMIT area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the SUBMIT area, in the order they were added. */\nexport const submitDiagnosticCodes = [\n \"MOSTRA_SUBMIT_ALREADY\",\n \"MOSTRA_SUBMIT_REVISION_MOVED\",\n \"MOSTRA_SUBMIT_POLICY_NONE\",\n \"MOSTRA_SUBMIT_NOT_FOUND\",\n \"MOSTRA_SUBMIT_VIEW_INVALID\",\n \"MOSTRA_SUBMIT_SIGNAL_INVALID\",\n \"MOSTRA_SUBMIT_CHANNEL_DENIED\",\n \"MOSTRA_SUBMIT_BLOCKED\",\n // gen:codes\n] as const;\n\n/** The codes of the SUBMIT area. */\nexport type SubmitDiagnosticCode = (typeof submitDiagnosticCodes)[number];\n\n/** The SUBMIT area's catalog entries. */\nexport const submitDiagnostics: AreaCatalog<SubmitDiagnosticCode> = {\n MOSTRA_SUBMIT_ALREADY: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Already submitted\",\n hint: \"This artifact takes one submission, and it was made; read it with `mostra results`.\",\n docs: {\n explanation:\n \"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.\",\n 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.',\n },\n },\n MOSTRA_SUBMIT_REVISION_MOVED: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Draft changed before submit\",\n hint: \"Reload the draft, check what changed, and submit again with its current revision.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_SUBMIT_POLICY_NONE: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Artifact takes no submissions\",\n hint: \"Exchange data through artifact state, actions and signals; this artifact has no submissions.\",\n docs: {\n explanation:\n \"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.\",\n 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`.\",\n },\n },\n MOSTRA_SUBMIT_NOT_FOUND: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"No such submission\",\n hint: \"Wait for a submission with `mostra wait <artifact> --until submitted`, or, when the message says the policy is none, read `mostra state get <artifact>` or wait for a signal with `--until signal:<name>`.\",\n docs: {\n explanation:\n \"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). An artifact whose submission policy is `none` never has one, and the message says so: its viewers' work is in its shared state, its signals and its action runs.\",\n 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. Under policy `none`, read the shared state with `mostra state get <artifact>`, or wait for a signal the page raises with `mostra wait <artifact> --until signal:<name>`: its event carries the signal's payload.\",\n },\n },\n MOSTRA_SUBMIT_VIEW_INVALID: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Unknown view\",\n hint: \"Send the view ID this page was opened with.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Use the `viewId` the shell handed this frame. A page opened outside Mostra's shell has no view and can't submit.\",\n },\n },\n MOSTRA_SUBMIT_SIGNAL_INVALID: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Invalid signal\",\n hint: \"Name signals with letters, digits, `.`, `_` and `-`, and keep their payload under 64 KiB of JSON.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Rename the signal or shrink its payload; put large data into a field or artifact state and send its ID in the payload.\",\n },\n },\n MOSTRA_SUBMIT_CHANNEL_DENIED: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Submit channel not allowed\",\n hint: \"Let the viewer submit with the shell's trusted Submit; this host doesn't take submissions from artifact code.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_SUBMIT_BLOCKED: {\n severity: \"error\",\n phase: \"runtime\",\n title: \"Answers missing before submit\",\n hint: \"Fill in the fields this diagnostic lists, fix their errors or resolve their conflicts, then submit again.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,oBAAuD;CAClE,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
package/dist/hygiene.d.ts CHANGED
@@ -17,8 +17,11 @@ export interface RequestPolicy {
17
17
  * `Origin` and a JSON content type, but no CSRF token yet.
18
18
  * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF
19
19
  * token in `X-Mostra-CSRF`.
20
+ * - `rpc`: a JSON-RPC POST from a program that holds a bearer token (`mostra mcp --http`, D164): a
21
+ * foreign `Origin` is refused and none is fine, since browsers send one on every POST; a JSON
22
+ * content type. The endpoint checks the token itself, as it checks a session.
20
23
  */
21
- export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation";
24
+ export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation" | "rpc";
22
25
  /** One request as the transport received it. */
23
26
  export interface RequestFacts {
24
27
  /** The method, as sent. */
@@ -1 +1 @@
1
- {"version":3,"file":"hygiene.d.ts","names":[],"sources":["../src/hygiene.ts"],"mappings":";;;;iBAoBiB;;WAEN;;WAEA;;;;;;;;;;;;YAaC;;iBAGK;;WAEN;;WAEA;;WAEA;;WAEA,SAAS;;WAET;;;iBAIM;;WAEN;;WAEA,YAAY;;;qBAIV;;wBAoBG,QAAQ,MAAM,uBAAuB,iBAAiB,kBAAkB;;wBAexE,UAAU,WAAW;;;;;;wBAcrB,SAAS;;wBAiBT,YACd,iDACA;;wBAOc,kBAAkB;;;;;;;wBAWlB,aAAa,QAAQ,eAAe,SAAS,eAAe"}
1
+ {"version":3,"file":"hygiene.d.ts","names":[],"sources":["../src/hygiene.ts"],"mappings":";;;;iBAoBiB;;WAEN;;WAEA;;;;;;;;;;;;;;;YAgBC;;iBAGK;;WAEN;;WAEA;;WAEA;;WAEA,SAAS;;WAET;;;iBAIM;;WAEN;;WAEA,YAAY;;;qBAIV;;wBAoBG,QAAQ,MAAM,uBAAuB,iBAAiB,kBAAkB;;wBAexE,UAAU,WAAW;;;;;;wBAcrB,SAAS;;wBAiBT,YACd,iDACA;;wBAOc,kBAAkB;;;;;;;wBAWlB,aAAa,QAAQ,eAAe,SAAS,eAAe"}
package/dist/hygiene.js CHANGED
@@ -112,6 +112,10 @@ function checkRequest(policy, request) {
112
112
  case "read":
113
113
  if (origin !== void 0 && origin !== policy.origin) return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
114
114
  return;
115
+ case "rpc":
116
+ if (origin !== void 0 && origin !== policy.origin) return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
117
+ if (!isJsonContentType(headerValue(request.headers, "content-type"))) return refusal("MOSTRA_HYGIENE_CONTENT_TYPE", "The request's body isn't declared as JSON.");
118
+ return;
115
119
  case "stream": {
116
120
  const site = headerValue(request.headers, "sec-fetch-site");
117
121
  return (origin === void 0 ? site === "same-origin" : origin === policy.origin) ? void 0 : refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "A stream must be opened by its own origin.");
@@ -1 +1 @@
1
- {"version":3,"file":"hygiene.js","names":[],"sources":["../src/hygiene.ts"],"sourcesContent":["/**\n * Request hygiene (D06, ARCHITECTURE §10, HY-01): the checks every Mostra HTTP endpoint applies\n * before it acts on a request, as pure functions with no I/O. The gateway runs them on every\n * request, and `mostra mcp --http` (WP-15) runs the same code (D96), so a request a stranger's\n * page could send is refused the same way everywhere. None of them limits what an artifact, an\n * agent or a viewer may do; they only make sure a request comes from the page it claims to.\n *\n * ```ts\n * const refusal = checkRequest(\n * { origin: \"http://127.0.0.1:23456\", hosts: [\"127.0.0.1:23456\"] },\n * { method: \"POST\", target: \"/a/art_…/_mostra/ticket\", headers, intent: \"mutation\", csrf },\n * );\n * if (refusal) return respond(refusal.status, refusal.diagnostic);\n * ```\n */\nimport { type HygieneDiagnosticCode, hygieneDiagnostics } from \"./diagnostics/codes/hygiene.ts\";\nimport type { Diagnostic } from \"./diagnostics/diagnostic.ts\";\nimport { buildDiagnostic } from \"./diagnostics/spec.ts\";\n\n/** What one listener serves: its own origin and the exact `Host` values it accepts. */\nexport interface RequestPolicy {\n /** The listener's origin, such as `http://127.0.0.1:23456`; `Origin` headers must equal it. */\n readonly origin: string;\n /** Every `host:port` this listener answers to (lowercase): its URL host, plus registered tunnels. */\n readonly hosts: readonly string[];\n}\n\n/**\n * What a request is for, which decides the checks beyond the envelope:\n * - `read`: a GET or HEAD of a page or file; a foreign `Origin` is refused, none is fine.\n * - `stream`: an event stream (GET); same-origin only, by `Origin` or `Sec-Fetch-Site`.\n * - `upgrade`: a WebSocket upgrade; `Origin` must be present and equal.\n * - `exchange`: a mutation that starts a session (a capability token or ticket in the body):\n * `Origin` and a JSON content type, but no CSRF token yet.\n * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF\n * token in `X-Mostra-CSRF`.\n */\nexport type RequestIntent = \"read\" | \"stream\" | \"upgrade\" | \"exchange\" | \"mutation\";\n\n/** One request as the transport received it. */\nexport interface RequestFacts {\n /** The method, as sent. */\n readonly method: string;\n /** The request target exactly as sent: an origin-form path with its query. */\n readonly target: string;\n /** Every header as `[name, value]` in arrival order, so repeated headers are visible. */\n readonly headers: readonly (readonly [string, string])[];\n /** The intent the matched route declared; omit to check only the envelope. */\n readonly intent?: RequestIntent;\n /** The session's CSRF token, for `mutation` requests. */\n readonly csrf?: string;\n}\n\n/** A refused request: the HTTP status to answer with and the diagnostic for its body. */\nexport interface Refusal {\n /** The HTTP status: 400, 401, 403, 404, 410, 415, 421 or 429. */\n readonly status: number;\n /** What was refused and why, for the response body and the log. */\n readonly diagnostic: Diagnostic;\n}\n\n/** The header that carries a session's CSRF token on every mutation (D98). */\nexport const CSRF_HEADER = \"x-mostra-csrf\";\n\nconst STATUS: Readonly<Record<HygieneDiagnosticCode, number>> = {\n MOSTRA_HYGIENE_HOST_REFUSED: 421,\n MOSTRA_HYGIENE_ORIGIN_REFUSED: 403,\n MOSTRA_HYGIENE_CSRF_MISSING: 403,\n MOSTRA_HYGIENE_CONTENT_TYPE: 415,\n MOSTRA_HYGIENE_REQUEST_MALFORMED: 400,\n MOSTRA_HYGIENE_SESSION_MISSING: 401,\n MOSTRA_HYGIENE_TOKEN_INVALID: 401,\n MOSTRA_HYGIENE_TOKEN_REVOKED: 410,\n MOSTRA_HYGIENE_SCOPE_DENIED: 403,\n MOSTRA_HYGIENE_RATE_LIMITED: 429,\n MOSTRA_HYGIENE_NOT_SERVED: 404,\n MOSTRA_HYGIENE_SESSION_CONFLICT: 409,\n MOSTRA_HYGIENE_HEADERS_TOO_LARGE: 431,\n MOSTRA_HYGIENE_FRAME_SESSION: 403,\n};\n\n/** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */\nexport function refusal(code: HygieneDiagnosticCode, message: string, status?: number): Refusal {\n return {\n status: status ?? STATUS[code],\n diagnostic: buildDiagnostic(code, hygieneDiagnostics[code], { message }),\n };\n}\n\n/** Headers that must appear at most once: a second copy could mean two different things. */\nconst SINGLE = new Set([\"host\", \"origin\", \"content-type\", \"content-length\", CSRF_HEADER, \"cookie\"]);\n\n/** Characters no header value or path may carry: controls other than tab, and DEL. */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point.\nconst CONTROL = /[\\u0000-\\u0008\\u000a-\\u001f\\u007f]/;\n\n/** Constant-time comparison of two strings, so timing reveals nothing about a secret. */\nexport function safeEqual(a: string, b: string): boolean {\n let difference = a.length ^ b.length;\n const length = Math.max(a.length, b.length);\n for (let index = 0; index < length; index++) {\n difference |= (a.charCodeAt(index) | 0) ^ (b.charCodeAt(index) | 0);\n }\n return difference === 0;\n}\n\n/**\n * The path a request target names, decoded, or `undefined` when it isn't a safe origin-form path:\n * absolute and authority forms, `*`, encoded `/` or `\\`, `.` or `..` segments (encoded or not),\n * NUL and other controls, and invalid percent-encoding are all refused.\n */\nexport function safePath(target: string): string | undefined {\n if (!target.startsWith(\"/\") || target.startsWith(\"//\")) return undefined;\n const end = target.search(/[?#]/);\n const raw = end < 0 ? target : target.slice(0, end);\n if (/%(2f|5c)/i.test(raw) || raw.includes(\"\\\\\")) return undefined;\n let path: string;\n try {\n path = decodeURIComponent(raw);\n } catch {\n return undefined;\n }\n if (CONTROL.test(path) || path.includes(\"\\u0000\")) return undefined;\n if (path.split(\"/\").some((segment) => segment === \".\" || segment === \"..\")) return undefined;\n return path;\n}\n\n/** The value of a header (case-insensitive name), or `undefined`. */\nexport function headerValue(\n headers: readonly (readonly [string, string])[],\n name: string,\n): string | undefined {\n const lower = name.toLowerCase();\n return headers.find(([key]) => key.toLowerCase() === lower)?.[1];\n}\n\n/** Whether a `Content-Type` value is JSON (`application/json`, any parameters). */\nexport function isJsonContentType(value: string | undefined): boolean {\n if (value === undefined) return false;\n return value.split(\";\")[0]?.trim().toLowerCase() === \"application/json\";\n}\n\n/**\n * Checks a request's envelope (the `Host` allowlist, the request target, repeated and malformed\n * headers) and, when `intent` is given, what that intent needs: `Origin`, the JSON content type\n * and the CSRF token. Returns the first refusal, or `undefined` when the request may proceed.\n * Session, token and scope checks follow in the endpoint, which knows its session.\n */\nexport function checkRequest(policy: RequestPolicy, request: RequestFacts): Refusal | undefined {\n const counts = new Map<string, number>();\n for (const [name, value] of request.headers) {\n const lower = name.toLowerCase();\n counts.set(lower, (counts.get(lower) ?? 0) + 1);\n if (CONTROL.test(value)) {\n return refusal(\n \"MOSTRA_HYGIENE_REQUEST_MALFORMED\",\n `The ${lower} header has control characters.`,\n );\n }\n }\n for (const name of SINGLE) {\n if ((counts.get(name) ?? 0) > 1) {\n return refusal(\"MOSTRA_HYGIENE_REQUEST_MALFORMED\", `The request repeats the ${name} header.`);\n }\n }\n const host = headerValue(request.headers, \"host\")?.toLowerCase();\n if (host === undefined || !policy.hosts.includes(host)) {\n return refusal(\n \"MOSTRA_HYGIENE_HOST_REFUSED\",\n host === undefined\n ? \"The request has no Host header.\"\n : \"The request's Host isn't one this listener serves.\",\n );\n }\n if (safePath(request.target) === undefined) {\n return refusal(\n \"MOSTRA_HYGIENE_REQUEST_MALFORMED\",\n \"The request target isn't a plain path inside the served tree.\",\n );\n }\n if (request.intent === undefined) return undefined;\n\n const origin = headerValue(request.headers, \"origin\");\n switch (request.intent) {\n case \"read\":\n if (origin !== undefined && origin !== policy.origin) {\n return refusal(\"MOSTRA_HYGIENE_ORIGIN_REFUSED\", \"The request came from another origin.\");\n }\n return undefined;\n case \"stream\": {\n const site = headerValue(request.headers, \"sec-fetch-site\");\n const sameOrigin = origin === undefined ? site === \"same-origin\" : origin === policy.origin;\n return sameOrigin\n ? undefined\n : refusal(\"MOSTRA_HYGIENE_ORIGIN_REFUSED\", \"A stream must be opened by its own origin.\");\n }\n case \"upgrade\":\n case \"exchange\":\n case \"mutation\": {\n if (origin !== policy.origin) {\n return refusal(\n \"MOSTRA_HYGIENE_ORIGIN_REFUSED\",\n origin === undefined\n ? \"The request has no Origin header.\"\n : \"The request came from another origin.\",\n );\n }\n if (request.intent === \"upgrade\") return undefined;\n if (!isJsonContentType(headerValue(request.headers, \"content-type\"))) {\n return refusal(\"MOSTRA_HYGIENE_CONTENT_TYPE\", \"The request's body isn't declared as JSON.\");\n }\n if (request.intent === \"exchange\") return undefined;\n const sent = headerValue(request.headers, CSRF_HEADER);\n if (request.csrf === undefined || sent === undefined || !safeEqual(sent, request.csrf)) {\n return refusal(\n \"MOSTRA_HYGIENE_CSRF_MISSING\",\n sent === undefined\n ? `The request has no ${CSRF_HEADER} header.`\n : `The request's ${CSRF_HEADER} header doesn't match its session.`,\n );\n }\n return undefined;\n }\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA8DA,MAAa,cAAc;AAE3B,MAAM,SAA0D;CAC9D,6BAA6B;CAC7B,+BAA+B;CAC/B,6BAA6B;CAC7B,6BAA6B;CAC7B,kCAAkC;CAClC,gCAAgC;CAChC,8BAA8B;CAC9B,8BAA8B;CAC9B,6BAA6B;CAC7B,6BAA6B;CAC7B,2BAA2B;CAC3B,iCAAiC;CACjC,kCAAkC;CAClC,8BAA8B;AAChC;;AAGA,SAAgB,QAAQ,MAA6B,SAAiB,QAA0B;CAC9F,OAAO;EACL,QAAQ,UAAU,OAAO;EACzB,YAAY,gBAAgB,MAAM,mBAAmB,OAAO,EAAE,QAAQ,CAAC;CACzE;AACF;;AAGA,MAAM,yBAAS,IAAI,IAAI;CAAC;CAAQ;CAAU;CAAgB;CAAkB;CAAa;AAAQ,CAAC;;AAIlG,MAAM,UAAU;;AAGhB,SAAgB,UAAU,GAAW,GAAoB;CACvD,IAAI,aAAa,EAAE,SAAS,EAAE;CAC9B,MAAM,SAAS,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM;CAC1C,KAAK,IAAI,QAAQ,GAAG,QAAQ,QAAQ,SAClC,eAAe,EAAE,WAAW,KAAK,IAAI,MAAM,EAAE,WAAW,KAAK,IAAI;CAEnE,OAAO,eAAe;AACxB;;;;;;AAOA,SAAgB,SAAS,QAAoC;CAC3D,IAAI,CAAC,OAAO,WAAW,GAAG,KAAK,OAAO,WAAW,IAAI,GAAG,OAAO,KAAA;CAC/D,MAAM,MAAM,OAAO,OAAO,MAAM;CAChC,MAAM,MAAM,MAAM,IAAI,SAAS,OAAO,MAAM,GAAG,GAAG;CAClD,IAAI,YAAY,KAAK,GAAG,KAAK,IAAI,SAAS,IAAI,GAAG,OAAO,KAAA;CACxD,IAAI;CACJ,IAAI;EACF,OAAO,mBAAmB,GAAG;CAC/B,QAAQ;EACN;CACF;CACA,IAAI,QAAQ,KAAK,IAAI,KAAK,KAAK,SAAS,IAAQ,GAAG,OAAO,KAAA;CAC1D,IAAI,KAAK,MAAM,GAAG,CAAC,CAAC,MAAM,YAAY,YAAY,OAAO,YAAY,IAAI,GAAG,OAAO,KAAA;CACnF,OAAO;AACT;;AAGA,SAAgB,YACd,SACA,MACoB;CACpB,MAAM,QAAQ,KAAK,YAAY;CAC/B,OAAO,QAAQ,MAAM,CAAC,SAAS,IAAI,YAAY,MAAM,KAAK,CAAC,GAAG;AAChE;;AAGA,SAAgB,kBAAkB,OAAoC;CACpE,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,YAAY,MAAM;AACvD;;;;;;;AAQA,SAAgB,aAAa,QAAuB,SAA4C;CAC9F,MAAM,yBAAS,IAAI,IAAoB;CACvC,KAAK,MAAM,CAAC,MAAM,UAAU,QAAQ,SAAS;EAC3C,MAAM,QAAQ,KAAK,YAAY;EAC/B,OAAO,IAAI,QAAQ,OAAO,IAAI,KAAK,KAAK,KAAK,CAAC;EAC9C,IAAI,QAAQ,KAAK,KAAK,GACpB,OAAO,QACL,oCACA,OAAO,MAAM,gCACf;CAEJ;CACA,KAAK,MAAM,QAAQ,QACjB,KAAK,OAAO,IAAI,IAAI,KAAK,KAAK,GAC5B,OAAO,QAAQ,oCAAoC,2BAA2B,KAAK,SAAS;CAGhG,MAAM,OAAO,YAAY,QAAQ,SAAS,MAAM,CAAC,EAAE,YAAY;CAC/D,IAAI,SAAS,KAAA,KAAa,CAAC,OAAO,MAAM,SAAS,IAAI,GACnD,OAAO,QACL,+BACA,SAAS,KAAA,IACL,oCACA,oDACN;CAEF,IAAI,SAAS,QAAQ,MAAM,MAAM,KAAA,GAC/B,OAAO,QACL,oCACA,+DACF;CAEF,IAAI,QAAQ,WAAW,KAAA,GAAW,OAAO,KAAA;CAEzC,MAAM,SAAS,YAAY,QAAQ,SAAS,QAAQ;CACpD,QAAQ,QAAQ,QAAhB;EACE,KAAK;GACH,IAAI,WAAW,KAAA,KAAa,WAAW,OAAO,QAC5C,OAAO,QAAQ,iCAAiC,uCAAuC;GAEzF;EACF,KAAK,UAAU;GACb,MAAM,OAAO,YAAY,QAAQ,SAAS,gBAAgB;GAE1D,QADmB,WAAW,KAAA,IAAY,SAAS,gBAAgB,WAAW,OAAO,UAEjF,KAAA,IACA,QAAQ,iCAAiC,4CAA4C;EAC3F;EACA,KAAK;EACL,KAAK;EACL,KAAK,YAAY;GACf,IAAI,WAAW,OAAO,QACpB,OAAO,QACL,iCACA,WAAW,KAAA,IACP,sCACA,uCACN;GAEF,IAAI,QAAQ,WAAW,WAAW,OAAO,KAAA;GACzC,IAAI,CAAC,kBAAkB,YAAY,QAAQ,SAAS,cAAc,CAAC,GACjE,OAAO,QAAQ,+BAA+B,4CAA4C;GAE5F,IAAI,QAAQ,WAAW,YAAY,OAAO,KAAA;GAC1C,MAAM,OAAO,YAAY,QAAQ,SAAS,WAAW;GACrD,IAAI,QAAQ,SAAS,KAAA,KAAa,SAAS,KAAA,KAAa,CAAC,UAAU,MAAM,QAAQ,IAAI,GACnF,OAAO,QACL,+BACA,SAAS,KAAA,IACL,sBAAsB,YAAY,YAClC,iBAAiB,YAAY,mCACnC;GAEF;EACF;CACF;AACF"}
1
+ {"version":3,"file":"hygiene.js","names":[],"sources":["../src/hygiene.ts"],"sourcesContent":["/**\n * Request hygiene (D06, ARCHITECTURE §10, HY-01): the checks every Mostra HTTP endpoint applies\n * before it acts on a request, as pure functions with no I/O. The gateway runs them on every\n * request, and `mostra mcp --http` (WP-15) runs the same code (D96), so a request a stranger's\n * page could send is refused the same way everywhere. None of them limits what an artifact, an\n * agent or a viewer may do; they only make sure a request comes from the page it claims to.\n *\n * ```ts\n * const refusal = checkRequest(\n * { origin: \"http://127.0.0.1:23456\", hosts: [\"127.0.0.1:23456\"] },\n * { method: \"POST\", target: \"/a/art_…/_mostra/ticket\", headers, intent: \"mutation\", csrf },\n * );\n * if (refusal) return respond(refusal.status, refusal.diagnostic);\n * ```\n */\nimport { type HygieneDiagnosticCode, hygieneDiagnostics } from \"./diagnostics/codes/hygiene.ts\";\nimport type { Diagnostic } from \"./diagnostics/diagnostic.ts\";\nimport { buildDiagnostic } from \"./diagnostics/spec.ts\";\n\n/** What one listener serves: its own origin and the exact `Host` values it accepts. */\nexport interface RequestPolicy {\n /** The listener's origin, such as `http://127.0.0.1:23456`; `Origin` headers must equal it. */\n readonly origin: string;\n /** Every `host:port` this listener answers to (lowercase): its URL host, plus registered tunnels. */\n readonly hosts: readonly string[];\n}\n\n/**\n * What a request is for, which decides the checks beyond the envelope:\n * - `read`: a GET or HEAD of a page or file; a foreign `Origin` is refused, none is fine.\n * - `stream`: an event stream (GET); same-origin only, by `Origin` or `Sec-Fetch-Site`.\n * - `upgrade`: a WebSocket upgrade; `Origin` must be present and equal.\n * - `exchange`: a mutation that starts a session (a capability token or ticket in the body):\n * `Origin` and a JSON content type, but no CSRF token yet.\n * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF\n * token in `X-Mostra-CSRF`.\n * - `rpc`: a JSON-RPC POST from a program that holds a bearer token (`mostra mcp --http`, D164): a\n * foreign `Origin` is refused and none is fine, since browsers send one on every POST; a JSON\n * content type. The endpoint checks the token itself, as it checks a session.\n */\nexport type RequestIntent = \"read\" | \"stream\" | \"upgrade\" | \"exchange\" | \"mutation\" | \"rpc\";\n\n/** One request as the transport received it. */\nexport interface RequestFacts {\n /** The method, as sent. */\n readonly method: string;\n /** The request target exactly as sent: an origin-form path with its query. */\n readonly target: string;\n /** Every header as `[name, value]` in arrival order, so repeated headers are visible. */\n readonly headers: readonly (readonly [string, string])[];\n /** The intent the matched route declared; omit to check only the envelope. */\n readonly intent?: RequestIntent;\n /** The session's CSRF token, for `mutation` requests. */\n readonly csrf?: string;\n}\n\n/** A refused request: the HTTP status to answer with and the diagnostic for its body. */\nexport interface Refusal {\n /** The HTTP status: 400, 401, 403, 404, 410, 415, 421 or 429. */\n readonly status: number;\n /** What was refused and why, for the response body and the log. */\n readonly diagnostic: Diagnostic;\n}\n\n/** The header that carries a session's CSRF token on every mutation (D98). */\nexport const CSRF_HEADER = \"x-mostra-csrf\";\n\nconst STATUS: Readonly<Record<HygieneDiagnosticCode, number>> = {\n MOSTRA_HYGIENE_HOST_REFUSED: 421,\n MOSTRA_HYGIENE_ORIGIN_REFUSED: 403,\n MOSTRA_HYGIENE_CSRF_MISSING: 403,\n MOSTRA_HYGIENE_CONTENT_TYPE: 415,\n MOSTRA_HYGIENE_REQUEST_MALFORMED: 400,\n MOSTRA_HYGIENE_SESSION_MISSING: 401,\n MOSTRA_HYGIENE_TOKEN_INVALID: 401,\n MOSTRA_HYGIENE_TOKEN_REVOKED: 410,\n MOSTRA_HYGIENE_SCOPE_DENIED: 403,\n MOSTRA_HYGIENE_RATE_LIMITED: 429,\n MOSTRA_HYGIENE_NOT_SERVED: 404,\n MOSTRA_HYGIENE_SESSION_CONFLICT: 409,\n MOSTRA_HYGIENE_HEADERS_TOO_LARGE: 431,\n MOSTRA_HYGIENE_FRAME_SESSION: 403,\n};\n\n/** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */\nexport function refusal(code: HygieneDiagnosticCode, message: string, status?: number): Refusal {\n return {\n status: status ?? STATUS[code],\n diagnostic: buildDiagnostic(code, hygieneDiagnostics[code], { message }),\n };\n}\n\n/** Headers that must appear at most once: a second copy could mean two different things. */\nconst SINGLE = new Set([\"host\", \"origin\", \"content-type\", \"content-length\", CSRF_HEADER, \"cookie\"]);\n\n/** Characters no header value or path may carry: controls other than tab, and DEL. */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point.\nconst CONTROL = /[\\u0000-\\u0008\\u000a-\\u001f\\u007f]/;\n\n/** Constant-time comparison of two strings, so timing reveals nothing about a secret. */\nexport function safeEqual(a: string, b: string): boolean {\n let difference = a.length ^ b.length;\n const length = Math.max(a.length, b.length);\n for (let index = 0; index < length; index++) {\n difference |= (a.charCodeAt(index) | 0) ^ (b.charCodeAt(index) | 0);\n }\n return difference === 0;\n}\n\n/**\n * The path a request target names, decoded, or `undefined` when it isn't a safe origin-form path:\n * absolute and authority forms, `*`, encoded `/` or `\\`, `.` or `..` segments (encoded or not),\n * NUL and other controls, and invalid percent-encoding are all refused.\n */\nexport function safePath(target: string): string | undefined {\n if (!target.startsWith(\"/\") || target.startsWith(\"//\")) return undefined;\n const end = target.search(/[?#]/);\n const raw = end < 0 ? target : target.slice(0, end);\n if (/%(2f|5c)/i.test(raw) || raw.includes(\"\\\\\")) return undefined;\n let path: string;\n try {\n path = decodeURIComponent(raw);\n } catch {\n return undefined;\n }\n if (CONTROL.test(path) || path.includes(\"\\u0000\")) return undefined;\n if (path.split(\"/\").some((segment) => segment === \".\" || segment === \"..\")) return undefined;\n return path;\n}\n\n/** The value of a header (case-insensitive name), or `undefined`. */\nexport function headerValue(\n headers: readonly (readonly [string, string])[],\n name: string,\n): string | undefined {\n const lower = name.toLowerCase();\n return headers.find(([key]) => key.toLowerCase() === lower)?.[1];\n}\n\n/** Whether a `Content-Type` value is JSON (`application/json`, any parameters). */\nexport function isJsonContentType(value: string | undefined): boolean {\n if (value === undefined) return false;\n return value.split(\";\")[0]?.trim().toLowerCase() === \"application/json\";\n}\n\n/**\n * Checks a request's envelope (the `Host` allowlist, the request target, repeated and malformed\n * headers) and, when `intent` is given, what that intent needs: `Origin`, the JSON content type\n * and the CSRF token. Returns the first refusal, or `undefined` when the request may proceed.\n * Session, token and scope checks follow in the endpoint, which knows its session.\n */\nexport function checkRequest(policy: RequestPolicy, request: RequestFacts): Refusal | undefined {\n const counts = new Map<string, number>();\n for (const [name, value] of request.headers) {\n const lower = name.toLowerCase();\n counts.set(lower, (counts.get(lower) ?? 0) + 1);\n if (CONTROL.test(value)) {\n return refusal(\n \"MOSTRA_HYGIENE_REQUEST_MALFORMED\",\n `The ${lower} header has control characters.`,\n );\n }\n }\n for (const name of SINGLE) {\n if ((counts.get(name) ?? 0) > 1) {\n return refusal(\"MOSTRA_HYGIENE_REQUEST_MALFORMED\", `The request repeats the ${name} header.`);\n }\n }\n const host = headerValue(request.headers, \"host\")?.toLowerCase();\n if (host === undefined || !policy.hosts.includes(host)) {\n return refusal(\n \"MOSTRA_HYGIENE_HOST_REFUSED\",\n host === undefined\n ? \"The request has no Host header.\"\n : \"The request's Host isn't one this listener serves.\",\n );\n }\n if (safePath(request.target) === undefined) {\n return refusal(\n \"MOSTRA_HYGIENE_REQUEST_MALFORMED\",\n \"The request target isn't a plain path inside the served tree.\",\n );\n }\n if (request.intent === undefined) return undefined;\n\n const origin = headerValue(request.headers, \"origin\");\n switch (request.intent) {\n case \"read\":\n if (origin !== undefined && origin !== policy.origin) {\n return refusal(\"MOSTRA_HYGIENE_ORIGIN_REFUSED\", \"The request came from another origin.\");\n }\n return undefined;\n case \"rpc\":\n if (origin !== undefined && origin !== policy.origin) {\n return refusal(\"MOSTRA_HYGIENE_ORIGIN_REFUSED\", \"The request came from another origin.\");\n }\n if (!isJsonContentType(headerValue(request.headers, \"content-type\"))) {\n return refusal(\"MOSTRA_HYGIENE_CONTENT_TYPE\", \"The request's body isn't declared as JSON.\");\n }\n return undefined;\n case \"stream\": {\n const site = headerValue(request.headers, \"sec-fetch-site\");\n const sameOrigin = origin === undefined ? site === \"same-origin\" : origin === policy.origin;\n return sameOrigin\n ? undefined\n : refusal(\"MOSTRA_HYGIENE_ORIGIN_REFUSED\", \"A stream must be opened by its own origin.\");\n }\n case \"upgrade\":\n case \"exchange\":\n case \"mutation\": {\n if (origin !== policy.origin) {\n return refusal(\n \"MOSTRA_HYGIENE_ORIGIN_REFUSED\",\n origin === undefined\n ? \"The request has no Origin header.\"\n : \"The request came from another origin.\",\n );\n }\n if (request.intent === \"upgrade\") return undefined;\n if (!isJsonContentType(headerValue(request.headers, \"content-type\"))) {\n return refusal(\"MOSTRA_HYGIENE_CONTENT_TYPE\", \"The request's body isn't declared as JSON.\");\n }\n if (request.intent === \"exchange\") return undefined;\n const sent = headerValue(request.headers, CSRF_HEADER);\n if (request.csrf === undefined || sent === undefined || !safeEqual(sent, request.csrf)) {\n return refusal(\n \"MOSTRA_HYGIENE_CSRF_MISSING\",\n sent === undefined\n ? `The request has no ${CSRF_HEADER} header.`\n : `The request's ${CSRF_HEADER} header doesn't match its session.`,\n );\n }\n return undefined;\n }\n }\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mostra/protocol",
3
- "version": "0.7.0",
3
+ "version": "0.9.0",
4
4
  "description": "Mostra's shared protocol vocabulary: IDs, dated revisions and diagnostics, with Zod schemas and generated JSON Schema.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "The Mostra Authors",
@@ -66,7 +66,7 @@
66
66
  "ignore": [
67
67
  "zod"
68
68
  ],
69
- "limit": "52 kB"
69
+ "limit": "54 kB"
70
70
  },
71
71
  {
72
72
  "name": "@mostra/protocol JSON-RPC core (D83, zod excluded)",
package/src/actions.ts CHANGED
@@ -221,6 +221,13 @@ export interface LiveState {
221
221
  }[];
222
222
  /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */
223
223
  readonly error?: WireError;
224
+ /**
225
+ * `true` while the source has no value and no failure and the artifact's latest version has a
226
+ * producer whose first `load` is on its way: the page shows it loading, and verify waits for it.
227
+ * Absent for a key nothing produces (one only `mostra push` writes) and for a source that only
228
+ * streams, whose first value may never come (WP-14's Opus review).
229
+ */
230
+ readonly awaiting?: boolean;
224
231
  }
225
232
 
226
233
  /** One live update on the event stream: never stored as an event (D63, LL-04). */
@@ -235,6 +242,11 @@ export interface LiveUpdate {
235
242
  readonly value?: Batches;
236
243
  /** What went wrong. */
237
244
  readonly error?: WireError;
245
+ /**
246
+ * `false` when a source read as {@link LiveState.awaiting} turned out to have no first `load`
247
+ * (its producer only streams): the page stops waiting for a first value.
248
+ */
249
+ readonly awaiting?: boolean;
238
250
  }
239
251
 
240
252
  /**
@@ -15,6 +15,9 @@ export const artifactDiagnosticCodes = [
15
15
  "MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN",
16
16
  "MOSTRA_ARTIFACT_VERSION_NOT_FOUND",
17
17
  "MOSTRA_ARTIFACT_VERSION_COLLECTED",
18
+ "MOSTRA_ARTIFACT_PATH_INVALID",
19
+ "MOSTRA_ARTIFACT_PATCH_REJECTED",
20
+ "MOSTRA_ARTIFACT_ID_DROPPED",
18
21
  // gen:codes
19
22
  ] as const;
20
23
 
@@ -133,5 +136,38 @@ export const artifactDiagnostics: AreaCatalog<ArtifactDiagnosticCode> = {
133
136
  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.",
134
137
  },
135
138
  },
139
+ MOSTRA_ARTIFACT_PATH_INVALID: {
140
+ severity: "error",
141
+ phase: "host",
142
+ title: "File path outside the artifact",
143
+ hint: "Name the file by a relative path inside the artifact's directory, such as `index.tsx` or `components/chart.tsx`.",
144
+ docs: {
145
+ explanation:
146
+ "`artifact_write` and `artifact_patch` change an artifact's own files, which live in its directory. A path that is absolute, climbs out with `..`, names the directory itself or passes through a link to somewhere else names no file of the artifact, so nothing is written.",
147
+ fix: "Give each file's path relative to the artifact's directory, with `/` between folders. To write elsewhere, use your own file tools.",
148
+ },
149
+ },
150
+ MOSTRA_ARTIFACT_PATCH_REJECTED: {
151
+ severity: "error",
152
+ phase: "host",
153
+ title: "Patch doesn't apply",
154
+ hint: "Read the file again and send edits whose `old` text appears in it exactly once, or a diff made against its current content.",
155
+ docs: {
156
+ explanation:
157
+ "An `artifact_patch` changes a file only when every edit applies: each `old` text must appear exactly once in the file as it is now, and each hunk of a unified diff must match its lines. When one doesn't, nothing is written, and the message lists each edit or hunk that didn't apply and why (not found, found more than once, the file is missing).",
158
+ fix: "Use a longer `old` text that appears only once, fix the hunk's context lines, or write the whole file with `artifact_write`.",
159
+ },
160
+ },
161
+ MOSTRA_ARTIFACT_ID_DROPPED: {
162
+ severity: "warning",
163
+ phase: "host",
164
+ title: "Manifest id removed",
165
+ hint: 'Put the `id: "art_…"` line back into the entry\'s `defineArtifact` (or its frontmatter), or the next publish gives the artifact a new ID.',
166
+ docs: {
167
+ explanation:
168
+ "A write replaced the artifact's entry (`index.tsx`, `index.jsx` or `index.mdx`) with text that no longer names the artifact ID its manifest held. Mostra wrote it as asked. An artifact without an `id` is bound to its source path at its first publish, so a page that was never published gets a new ID there, and one that was published keeps its ID only while its path stays the same: links, waits and results named by the old ID then don't find it.",
169
+ fix: 'Add the `id` back, exactly as it was (`id: "art_01…"` in `defineArtifact`, or `id:` in the MDX frontmatter), with `artifact_patch` or `artifact_write`.',
170
+ },
171
+ },
136
172
  // gen:entries
137
173
  };
@@ -17,6 +17,7 @@ export const envDiagnosticCodes = [
17
17
  "MOSTRA_ENV_BUNDLE_UNAVAILABLE",
18
18
  "MOSTRA_ENV_NODE_UNSUPPORTED",
19
19
  "MOSTRA_ENV_HELPER_MISSING",
20
+ "MOSTRA_ENV_RUNTIME_INSTALLING",
20
21
  // gen:codes
21
22
  ] as const;
22
23
 
@@ -157,5 +158,16 @@ export const envDiagnostics: AreaCatalog<EnvDiagnosticCode> = {
157
158
  fix: "Reinstall Mostra so the runtime bundle is complete. In a development checkout, build the helper with `cargo build -p mostra-win`. A custom layout can point the runtime at the helper with `MOSTRA_WIN_HELPER`.",
158
159
  },
159
160
  },
161
+ MOSTRA_ENV_RUNTIME_INSTALLING: {
162
+ severity: "error",
163
+ phase: "host",
164
+ title: "Runtime still installing",
165
+ hint: "Call the tool again in a minute: Mostra keeps installing its runtime meanwhile.",
166
+ docs: {
167
+ explanation:
168
+ "`mostra mcp` installed from npm answers its client at once and installs its release's runtime bundle in the background on its first start (about 200 MB, D164 item 7), so a client's startup timeout never waits for the download. A tool that needs the instance waits for that install, up to 45 seconds per call; this call's time ran out first. The install goes on, and the message says how far it is. Tools that need no instance (`docs_search`, `artifact_write`, `artifact_patch`) work during it.",
169
+ fix: "Call the tool again once the install has had time to finish. When it fails instead, the next call says why (`MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`, `MOSTRA_ENV_BUNDLE_UNAVAILABLE` offline) and starts it again.",
170
+ },
171
+ },
160
172
  // gen:entries
161
173
  };
@@ -58,11 +58,11 @@ export const submitDiagnostics: AreaCatalog<SubmitDiagnosticCode> = {
58
58
  severity: "error",
59
59
  phase: "runtime",
60
60
  title: "No such submission",
61
- hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.",
61
+ hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or, when the message says the policy is none, read `mostra state get <artifact>` or wait for a signal with `--until signal:<name>`.",
62
62
  docs: {
63
63
  explanation:
64
- "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).",
65
- 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.",
64
+ "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). An artifact whose submission policy is `none` never has one, and the message says so: its viewers' work is in its shared state, its signals and its action runs.",
65
+ 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. Under policy `none`, read the shared state with `mostra state get <artifact>`, or wait for a signal the page raises with `mostra wait <artifact> --until signal:<name>`: its event carries the signal's payload.",
66
66
  },
67
67
  },
68
68
  MOSTRA_SUBMIT_VIEW_INVALID: {
package/src/hygiene.ts CHANGED
@@ -34,8 +34,11 @@ export interface RequestPolicy {
34
34
  * `Origin` and a JSON content type, but no CSRF token yet.
35
35
  * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF
36
36
  * token in `X-Mostra-CSRF`.
37
+ * - `rpc`: a JSON-RPC POST from a program that holds a bearer token (`mostra mcp --http`, D164): a
38
+ * foreign `Origin` is refused and none is fine, since browsers send one on every POST; a JSON
39
+ * content type. The endpoint checks the token itself, as it checks a session.
37
40
  */
38
- export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation";
41
+ export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation" | "rpc";
39
42
 
40
43
  /** One request as the transport received it. */
41
44
  export interface RequestFacts {
@@ -187,6 +190,14 @@ export function checkRequest(policy: RequestPolicy, request: RequestFacts): Refu
187
190
  return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
188
191
  }
189
192
  return undefined;
193
+ case "rpc":
194
+ if (origin !== undefined && origin !== policy.origin) {
195
+ return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
196
+ }
197
+ if (!isJsonContentType(headerValue(request.headers, "content-type"))) {
198
+ return refusal("MOSTRA_HYGIENE_CONTENT_TYPE", "The request's body isn't declared as JSON.");
199
+ }
200
+ return undefined;
190
201
  case "stream": {
191
202
  const site = headerValue(request.headers, "sec-fetch-site");
192
203
  const sameOrigin = origin === undefined ? site === "same-origin" : origin === policy.origin;