@mostra/cli 0.8.0 → 0.10.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.
Files changed (67) hide show
  1. package/dist/bin.js +2 -2
  2. package/dist/bootstrap-BStzS_41.js +1 -0
  3. package/dist/bootstrap-_iCl_HaO.js +423 -0
  4. package/dist/bootstrap-_iCl_HaO.js.map +1 -0
  5. package/dist/{flush-CBN3AU9X.js → flush-znWmNZA1.js} +34 -5
  6. package/dist/flush-znWmNZA1.js.map +1 -0
  7. package/dist/index.d.ts +14 -4
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +2 -2
  10. package/dist/reference/cli.md +177 -4
  11. package/dist/reference/diagnostics.json +129 -3
  12. package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
  13. package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
  14. package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
  15. package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
  16. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
  17. package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
  18. package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
  19. package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
  20. package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
  21. package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
  22. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
  23. package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
  24. package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
  25. package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
  26. package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +3 -3
  27. package/dist/reference/telemetry.md +5 -3
  28. package/dist/{run-CuMkFuH7.js → run-Aq4HVIY0.js} +1244 -767
  29. package/dist/run-Aq4HVIY0.js.map +1 -0
  30. package/dist/run-D1U_RFEP.js +1 -0
  31. package/dist/skill/SKILL.md +6 -3
  32. package/dist/skill/references/answers.md +37 -1
  33. package/dist/skill/references/long-lived.md +2 -2
  34. package/dist/skill/references/mcp.md +63 -0
  35. package/dist/skill/references/sharing.md +54 -4
  36. package/dist/telemetry/flush-main.js +1 -1
  37. package/package.json +10 -4
  38. package/src/bootstrap.ts +16 -3
  39. package/src/client.ts +1 -1
  40. package/src/command.ts +13 -3
  41. package/src/commands/admin.ts +11 -1
  42. package/src/commands/authoring.ts +85 -3
  43. package/src/commands/dev.ts +60 -44
  44. package/src/commands/index.ts +18 -3
  45. package/src/commands/interaction.ts +19 -1
  46. package/src/commands/mcp.ts +128 -0
  47. package/src/commands/remote.ts +113 -0
  48. package/src/commands/sharing.ts +33 -6
  49. package/src/commands/viewing.ts +20 -2
  50. package/src/detached.ts +3 -0
  51. package/src/docs.ts +14 -6
  52. package/src/exit.ts +2 -0
  53. package/src/help.ts +1 -1
  54. package/src/home.ts +5 -3
  55. package/src/mcp.ts +448 -0
  56. package/src/parse.ts +20 -6
  57. package/src/run.ts +24 -13
  58. package/src/telemetry/harness.ts +24 -0
  59. package/src/telemetry/index.ts +75 -48
  60. package/src/telemetry/store.ts +15 -4
  61. package/dist/bootstrap-DfEe_yPr.js +0 -113
  62. package/dist/bootstrap-DfEe_yPr.js.map +0 -1
  63. package/dist/exit-CBIf8nAU.js +0 -79
  64. package/dist/exit-CBIf8nAU.js.map +0 -1
  65. package/dist/flush-CBN3AU9X.js.map +0 -1
  66. package/dist/run-3WlZ2Jos.js +0 -1
  67. package/dist/run-CuMkFuH7.js.map +0 -1
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_ARTIFACT_BUNDLE_INVALID
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_ARTIFACT_BUNDLE_INVALID
10
+
11
+ Not a bundle this version can import. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ Importing a bundle checks it before it keeps anything: its `mostra-bundle.json`, that its version ID is the one its artifact ID and digests give, and that its builds and source snapshot have the digests it records. This bundle failed one of those checks, so a file was changed, lost or added after it was exported, or it isn't a bundle Mostra wrote.
16
+
17
+ ## How to fix it
18
+
19
+ Export the version again from the home that published it, and copy the bundle's directory or archive whole.
20
+
21
+ ## Hint
22
+
23
+ Export the bundle again with `mostra export <artifact> --as bundle`, and import the files it wrote unchanged.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_ARTIFACT_ID_DROPPED
3
+ severity: warning
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_ARTIFACT_ID_DROPPED
10
+
11
+ Manifest id removed. Severity: warning. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ 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`.
20
+
21
+ ## Hint
22
+
23
+ Put the `id: "art_…"` line back into the entry's `defineArtifact` (or its frontmatter), or the next publish gives the artifact a new ID.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_ARTIFACT_PATCH_REJECTED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_ARTIFACT_PATCH_REJECTED
10
+
11
+ Patch doesn't apply. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ 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).
16
+
17
+ ## How to fix it
18
+
19
+ Use a longer `old` text that appears only once, fix the hunk's context lines, or write the whole file with `artifact_write`.
20
+
21
+ ## Hint
22
+
23
+ Read the file again and send edits whose `old` text appears in it exactly once, or a diff made against its current content.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_ARTIFACT_PATH_INVALID
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_ARTIFACT_PATH_INVALID
10
+
11
+ File path outside the artifact. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ `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.
16
+
17
+ ## How to fix it
18
+
19
+ Give each file's path relative to the artifact's directory, with `/` between folders. To write elsewhere, use your own file tools.
20
+
21
+ ## Hint
22
+
23
+ Name the file by a relative path inside the artifact's directory, such as `index.tsx` or `components/chart.tsx`.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_ENV_RUNTIME_INSTALLING
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_ENV_RUNTIME_INSTALLING
10
+
11
+ Runtime still installing. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ `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.
16
+
17
+ ## How to fix it
18
+
19
+ 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.
20
+
21
+ ## Hint
22
+
23
+ Call the tool again in a minute: Mostra keeps installing its runtime meanwhile.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_HOME_NETWORK_FILESYSTEM
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_HOME_NETWORK_FILESYSTEM
10
+
11
+ Data directory on a network filesystem. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ A remote server's data directory holds its hosted homes' ledgers and locks, which need a local disk: on a network filesystem a lock can seem held by two machines at once, and SQLite's WAL can't share memory across them (D165 item 0b). The server refuses a data directory it detects on NFS, SMB, AFP, WebDAV or a FUSE mount, before it opens anything.
16
+
17
+ ## How to fix it
18
+
19
+ Pass `--data` a directory on a local disk. To keep a copy elsewhere, replicate the homes with a backup tool instead.
20
+
21
+ ## Hint
22
+
23
+ Put the server's data directory on a local disk.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_CONFIG_INVALID
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_CONFIG_INVALID
10
+
11
+ Remote server configuration can't be used. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ `mostra-runtime server` reads its configuration (the file `--config` names and `MOSTRA_SERVER_*` variables) before it serves anything, and stops when a key is missing, of the wrong type or out of range, naming the key. Nothing was served.
16
+
17
+ ## How to fix it
18
+
19
+ Correct the key the message names: `apiOrigin` must be an `https:` origin (or `http:` on loopback), and `domains.active` a host name.
20
+
21
+ ## Hint
22
+
23
+ Fix the configuration key the message names, then start mostra-runtime server again.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_LOGIN_FAILED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_LOGIN_FAILED
10
+
11
+ Signing in to a remote server failed. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ Signing this home in to a remote server didn't finish: the code expired, the person refused it, the server refused the client, or the binding's access token was refused (revoked, expired, or for another server). Nothing of the home changed; artifacts it owns on that server stay its own.
16
+
17
+ ## How to fix it
18
+
19
+ Sign in to the server again and approve the code on the page it names. A refusal you didn't expect means the sign-in was revoked on the server.
20
+
21
+ ## Hint
22
+
23
+ Run mostra login again, and approve the code on the server's page within ten minutes.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_NOT_OWNER_INSTANCE
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_NOT_OWNER_INSTANCE
10
+
11
+ Another instance owns this hosted artifact. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ A hosted artifact has one owner instance: the one that shared it. It alone receives the artifact's submissions, relayed runs and authoring, and only it pushes versions of it (D165 item 1b). Another instance of the same account reads and waits through the hosted home.
16
+
17
+ ## How to fix it
18
+
19
+ Run the command on the instance the message names. Moving an artifact to another owner instance isn't part of this release.
20
+
21
+ ## Hint
22
+
23
+ Share or push this artifact from its owner instance, named in the message.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_OWNER_OFFLINE
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_OWNER_OFFLINE
10
+
11
+ The artifact's owner instance is offline. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ A hosted page called server code its owner instance runs, and the owner instance isn't connected. A plain call isn't kept, so it is refused at once; an action run waits or fails as the artifact's `hosted.offline` says.
16
+
17
+ ## How to fix it
18
+
19
+ Start Mostra on the owner's machine (`mostra daemon start`, or `mostra daemon install` for always-on). An action that must work while the owner is away should be an action run with `hosted.offline.actions: "queue"`.
20
+
21
+ ## Hint
22
+
23
+ Start Mostra on the machine that shared the page, or try again once it is back.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_QUEUE_FULL
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_QUEUE_FULL
10
+
11
+ Too many runs wait for the owner. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The artifact's owner instance is offline and as many runs as the server allows already wait for it, so this one was refused before anything was recorded. Runs already waiting keep their place.
16
+
17
+ ## How to fix it
18
+
19
+ Bring the owner instance back online: waiting runs then go out in the order they were made. The cap is the server's `relay.waitingRunsPerArtifact` setting.
20
+
21
+ ## Hint
22
+
23
+ Wait for the owner to come back and work through its queue, then press again.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_RATE_LIMITED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_RATE_LIMITED
10
+
11
+ Too many requests on this link. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ Too many requests of this kind came through one link or one address in a short time, past the server's `rateLimits`. Nothing was recorded, and a draft stays as it was.
16
+
17
+ ## How to fix it
18
+
19
+ Wait for the `Retry-After` the answer carries and try again. The limits are the server's `rateLimits` settings.
20
+
21
+ ## Hint
22
+
23
+ Try again after the time the answer's Retry-After gives.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_SIGN_IN_REQUIRED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_SIGN_IN_REQUIRED
10
+
11
+ This action needs a signed-in viewer. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ On a hosted link, an action that runs on the owner's machine, or a submission when the artifact asks for it, needs a viewer signed in (D159, D165 item 13). Nothing was recorded.
16
+
17
+ ## How to fix it
18
+
19
+ Sign in with the page's Sign in. An owner who wants anyone with the link to run actions sets `hosted: { actions: "link" }` in the manifest (and `submissions: "link"` for answers).
20
+
21
+ ## Hint
22
+
23
+ Sign in from the page's chrome, or have the owner allow this for anyone with the link.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_UNREACHABLE
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_UNREACHABLE
10
+
11
+ The remote server can't be reached. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The owner instance couldn't reach the remote server that holds this hosted artifact, so a write that must go there (its artifact state, a live value) was refused, never applied locally alone (D165 item 1). Nothing was lost: a page's edit stays in its journal and is sent again.
16
+
17
+ ## How to fix it
18
+
19
+ Run `mostra status` to see each server's link. When the server is back the link reconnects by itself; then write again.
20
+
21
+ ## Hint
22
+
23
+ Check the network and the server's address, then try again; mostra status shows the link.
@@ -12,12 +12,12 @@ No such submission. Severity: error. Phase: runtime.
12
12
 
13
13
  ## What it means
14
14
 
15
- 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).
15
+ 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.
16
16
 
17
17
  ## How to fix it
18
18
 
19
- 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.
19
+ 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.
20
20
 
21
21
  ## Hint
22
22
 
23
- Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.
23
+ 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>`.
@@ -27,7 +27,8 @@ The collector doesn't store IP addresses.
27
27
  - `mostra telemetry off`, `MOSTRA_TELEMETRY=0` or `DO_NOT_TRACK=1`. Any of these wins over every
28
28
  setting that turns it on.
29
29
  - Embedded use never sends anything: the TypeScript SDK, the Rust crate, an instance a host starts
30
- (`mostra host`) and any home a host has configured.
30
+ (`mostra host`), any home a host has configured, and an MCP server started with
31
+ `mostra mcp --embedded`, as a harness plugin starts it.
31
32
  - A build without a telemetry endpoint sends nothing.
32
33
 
33
34
  `mostra telemetry status` shows whether telemetry is on, why, your install ID and how many
@@ -66,12 +67,13 @@ one.
66
67
  | `verify.result` | `mostra verify` finishes | `status` (`pass` or `fail`), `codes` (up to 50 diagnostic codes, never their messages), `codesTruncated` |
67
68
  | `publish.done` | A version is published | `reused`, `forced` |
68
69
  | `share.done` | A share starts | `kind`: `tailnet`, `funnel`, `cloudflare` or `remote` |
69
- | `mcp.session` | An MCP client connects to `mostra mcp` | `client` (a known agent's ID, or `other`), `clientVersion` (known agents only) |
70
+ | `mcp.session` | An MCP client first uses `mostra mcp`, once per client in each run | `client` (a known agent's ID, or `other`), `clientVersion` (known agents only) |
70
71
 
71
72
  ## How it is sent
72
73
 
73
74
  Events wait in a small queue in the config directory and are sent in the background after a
74
- command finishes, at most 100 per request. No command waits for the network, and the network
75
+ command finishes (`mostra mcp`, which runs until its client stops it, sends `mcp.session` as it
76
+ happens), at most 100 per request. No command waits for the network, and the network
75
77
  never changes a command's result. Events that can't be sent within 7 days are dropped.
76
78
 
77
79
  ## Retention and your rights