@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.
- package/dist/bin.js +2 -2
- package/dist/bootstrap-BStzS_41.js +1 -0
- package/dist/bootstrap-_iCl_HaO.js +423 -0
- package/dist/bootstrap-_iCl_HaO.js.map +1 -0
- package/dist/{flush-CBN3AU9X.js → flush-znWmNZA1.js} +34 -5
- package/dist/flush-znWmNZA1.js.map +1 -0
- package/dist/index.d.ts +14 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/reference/cli.md +177 -4
- package/dist/reference/diagnostics.json +129 -3
- package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +3 -3
- package/dist/reference/telemetry.md +5 -3
- package/dist/{run-CuMkFuH7.js → run-Aq4HVIY0.js} +1244 -767
- package/dist/run-Aq4HVIY0.js.map +1 -0
- package/dist/run-D1U_RFEP.js +1 -0
- package/dist/skill/SKILL.md +6 -3
- package/dist/skill/references/answers.md +37 -1
- package/dist/skill/references/long-lived.md +2 -2
- package/dist/skill/references/mcp.md +63 -0
- package/dist/skill/references/sharing.md +54 -4
- package/dist/telemetry/flush-main.js +1 -1
- package/package.json +10 -4
- package/src/bootstrap.ts +16 -3
- package/src/client.ts +1 -1
- package/src/command.ts +13 -3
- package/src/commands/admin.ts +11 -1
- package/src/commands/authoring.ts +85 -3
- package/src/commands/dev.ts +60 -44
- package/src/commands/index.ts +18 -3
- package/src/commands/interaction.ts +19 -1
- package/src/commands/mcp.ts +128 -0
- package/src/commands/remote.ts +113 -0
- package/src/commands/sharing.ts +33 -6
- package/src/commands/viewing.ts +20 -2
- package/src/detached.ts +3 -0
- package/src/docs.ts +14 -6
- package/src/exit.ts +2 -0
- package/src/help.ts +1 -1
- package/src/home.ts +5 -3
- package/src/mcp.ts +448 -0
- package/src/parse.ts +20 -6
- package/src/run.ts +24 -13
- package/src/telemetry/harness.ts +24 -0
- package/src/telemetry/index.ts +75 -48
- package/src/telemetry/store.ts +15 -4
- package/dist/bootstrap-DfEe_yPr.js +0 -113
- package/dist/bootstrap-DfEe_yPr.js.map +0 -1
- package/dist/exit-CBIf8nAU.js +0 -79
- package/dist/exit-CBIf8nAU.js.map +0 -1
- package/dist/flush-CBN3AU9X.js.map +0 -1
- package/dist/run-3WlZ2Jos.js +0 -1
- package/dist/run-CuMkFuH7.js.map +0 -1
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { t as run } from "./run-Aq4HVIY0.js";
|
package/dist/skill/SKILL.md
CHANGED
|
@@ -4,7 +4,7 @@ description: Communicate visually with the user through Mostra. Use whenever sho
|
|
|
4
4
|
license: Apache-2.0
|
|
5
5
|
compatibility: Needs a shell that runs `mostra` (or `npx` with Node.js 22.19 or later) on macOS, Linux or Windows, x64 or arm64.
|
|
6
6
|
metadata:
|
|
7
|
-
version: "0.
|
|
7
|
+
version: "0.10.0"
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# Mostra
|
|
@@ -13,7 +13,9 @@ Mostra turns a React page you write into an **artifact**: a web page a person op
|
|
|
13
13
|
|
|
14
14
|
## Running Mostra
|
|
15
15
|
|
|
16
|
-
Run `mostra <command>`. When `mostra` isn't on the `PATH`, run `npx -y @mostra/cli@0.
|
|
16
|
+
Run `mostra <command>`. When `mostra` isn't on the `PATH`, run `npx -y @mostra/cli@0.10.0 <command>` everywhere this Skill says `mostra`; the first run downloads Mostra's own runtime (no global Node.js needed beyond `npx`). Every command takes `--json` (one JSON envelope on stdout, logs on stderr) and `--help`. `mostra docs <topic>` prints the reference, including every diagnostic code's page (`mostra docs MOSTRA_FIELD_DUPLICATE_ID`). `mostra list` lists the artifacts you've published, and `mostra status` shows the running instance.
|
|
17
|
+
|
|
18
|
+
When Mostra's tools are in your tool list (`artifact_create`, `artifact_verify` and the rest), use them instead: each step below has its tool, and everything else here holds unchanged. See [references/mcp.md](references/mcp.md).
|
|
17
19
|
|
|
18
20
|
## Words
|
|
19
21
|
|
|
@@ -55,7 +57,7 @@ Each step ends when its check holds. Don't hand a link out before step 4 passes.
|
|
|
55
57
|
Mostra draws the Submit button in its own frame around your page; `useSubmitControl` names it, and `required` fields block it until they're answered. Make it look considered: [references/design.md](references/design.md) has a baseline stylesheet and the rules for pages people answer. *Done when* every answer you need is a field with a label.
|
|
56
58
|
4. **Verify until it passes.** `mostra verify <dir> --screenshots always`. It type-checks, builds, renders the page headlessly, clicks through it, runs an accessibility check and screenshots it at 1280×800 and 390×844. Fix every error, then **open both screenshots and look at them** (about 1,300 and 450 image tokens). Warnings that start with "Observed only" describe what verify saw; judge them, and leave working code alone. *Done when* the status is `pass` and the screenshots show what you meant at both sizes. More in [references/verify.md](references/verify.md).
|
|
57
59
|
5. **Publish.** `mostra publish <dir>` prints the version and the capability URL. Publishing again after an edit makes a new version; open pages offer the person the new one, and answers carry over by field ID. *Done when* you have the link.
|
|
58
|
-
6. **Hand the link over.** Say who is asking and why, what the page is for, and roughly how long it takes.
|
|
60
|
+
6. **Hand the link over.** Say who is asking and why, what the page is for, and roughly how long it takes. For the person at this machine, `mostra open <dir> --browser` opens it in their browser, and its output says when none could be opened. For a phone or another person, see [references/sharing.md](references/sharing.md): one link is one person's draft, so give each person their own link. *Done when* the person has the link and knows what to do.
|
|
59
61
|
7. **Wait for the answer.** `mostra wait <dir> --until submitted --timeout 10m`. Exit code 0 means submitted; 5 means still waiting, with nothing lost: wait again, or continue other work and check later. *Done when* it exits 0.
|
|
60
62
|
8. **Read the results.** `mostra results <dir>` prints the submission as Markdown (`--format json` for JSON). Act on it. *Done when* you've used every answer.
|
|
61
63
|
|
|
@@ -113,5 +115,6 @@ Read the one you need when you need it.
|
|
|
113
115
|
| [references/long-lived.md](references/long-lived.md) | A page that lives for days: shared state, live data, `none` policy, always-on |
|
|
114
116
|
| [references/sharing.md](references/sharing.md) | Someone other than the person at this machine opens it, or on another device |
|
|
115
117
|
| [references/libraries.md](references/libraries.md) | Using charts, tables, motion or UI primitives, or an import fails |
|
|
118
|
+
| [references/mcp.md](references/mcp.md) | You work through Mostra's tools (`artifact_create` and the rest) instead of the `mostra` command |
|
|
116
119
|
|
|
117
120
|
Three complete artifacts that pass verify, to copy from: [assets/examples/decision/](assets/examples/decision/) (a choice with a reason), [assets/examples/inbox/](assets/examples/inbox/) (drafted replies with real Send actions) and [assets/examples/dashboard/](assets/examples/dashboard/) (live data and a shared list). The same guide is `mostra docs guide`, and each reference `mostra docs guide/<name>`.
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
- Forms with react-hook-form
|
|
7
7
|
- The trusted Submit and `useSubmit`
|
|
8
8
|
- Submission policies
|
|
9
|
+
- Counts by choice
|
|
9
10
|
- Signals
|
|
10
11
|
- Choosing between candidates
|
|
11
12
|
- Waiting
|
|
@@ -111,6 +112,41 @@ Request one in the manifest's `submission`; the host running Mostra decides (`mo
|
|
|
111
112
|
| epochs | `{ policy: "epochs" }` | Rounds: the person submits, you reply with a new version, they submit again. Each round is kept and linked |
|
|
112
113
|
| none | `{ policy: "none" }` | No Submit at all: dashboards, task lists, pages that talk through shared state, actions and signals ([long-lived.md](long-lived.md)) |
|
|
113
114
|
|
|
115
|
+
### Approvals that do something
|
|
116
|
+
|
|
117
|
+
When approving should make something happen (place the order, write the config, send the mail), keep the approval a submission: it is the durable record of who approved what, it arrives in `mostra results`, and the person presses one trusted button.
|
|
118
|
+
|
|
119
|
+
1. Use `once` and name the trusted Submit for the effect: `useSubmitControl({ label: "Approve and place the order", confirm: "Place the order for 3 laptops?" })`.
|
|
120
|
+
2. `mostra wait <dir> --until submitted`, read `mostra results <dir>`, then do the effect yourself.
|
|
121
|
+
3. Publish a new version, or set shared state, that says it's done, so the person sees the outcome.
|
|
122
|
+
|
|
123
|
+
When the effect must happen the moment they press, even while you aren't waiting, run it from the page with `useAction(fn, { key })` (a key makes it happen once, [server.md](server.md)), and still submit with the trusted Submit: `results` lists the run under `actions`. Choosing `none` with a signal instead leaves no submission and no trusted control, so nothing records the approval.
|
|
124
|
+
|
|
125
|
+
## Counts by choice
|
|
126
|
+
|
|
127
|
+
To show everyone how a fixed-choice question is going ("12 for Ship, 4 for Wait"), name the field in the manifest's `tally`. Mostra counts each submission's answer as it is accepted and sends the counts to every open page, with no server code:
|
|
128
|
+
|
|
129
|
+
```tsx
|
|
130
|
+
import { defineArtifact, useField, useLive } from "@mostra/react";
|
|
131
|
+
|
|
132
|
+
export const artifact = defineArtifact({
|
|
133
|
+
title: "Ship the redesign?",
|
|
134
|
+
submission: { policy: "once", scope: "per-viewer" },
|
|
135
|
+
tally: [{ field: "decision", choices: ["ship", "wait", "drop"], minTotal: 5 }],
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
function Decision() {
|
|
139
|
+
const [decision, setDecision] = useField("decision", "");
|
|
140
|
+
const tally = useLive("$tally/decision"); // data: { counts?: { ship, wait, drop }, total }
|
|
141
|
+
// …radio buttons for the three choices…
|
|
142
|
+
return <p>{tally.data?.counts ? `${tally.data.counts.ship} for Ship` : `${tally.data?.total ?? 0} answers so far`}</p>;
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
- Counts are of answers, never of people, and only of the listed `choices` (2 to 50): any other value counts nothing, so what someone typed never shows. Counts only grow.
|
|
147
|
+
- Below `minTotal` (default 0) a page gets only `total`, so with a handful of answers no one can tell how each person answered.
|
|
148
|
+
- The field is a viewer field (each person's own answer), and the counts come from submissions, so the policy must submit (`once` per viewer or `epochs`).
|
|
149
|
+
|
|
114
150
|
## Signals
|
|
115
151
|
|
|
116
152
|
A signal tells you something happened without submitting: "Ping the agent", "I'm stuck", "Regenerate this section".
|
|
@@ -124,7 +160,7 @@ function AskForHelp() {
|
|
|
124
160
|
}
|
|
125
161
|
```
|
|
126
162
|
|
|
127
|
-
Names are letters, digits, `.`, `_` and `-` (`submit` is taken). Payloads are JSON up to 64 KiB. Wait for one with `mostra wait <dir> --until signal:needs-help
|
|
163
|
+
Names are letters, digits, `.`, `_` and `-` (`submit` is taken). Payloads are JSON up to 64 KiB. Wait for one with `mostra wait <dir> --until signal:needs-help`, which prints the payload the page sent (with `--json`, it is `result.event.payload.payload`). A signal wakes nobody by itself: something has to wait for it.
|
|
128
164
|
|
|
129
165
|
## Choosing between candidates
|
|
130
166
|
|
|
@@ -126,10 +126,10 @@ function Builds() {
|
|
|
126
126
|
With `{ policy: "none" }` the page has no Submit. It talks to you through:
|
|
127
127
|
|
|
128
128
|
- shared fields you watch with `mostra wait <dir> --until state:<fieldId>`;
|
|
129
|
-
- signals the page sends (`useSignal`) or server code raises (`signal()`), watched with `mostra wait <dir> --until signal:<name
|
|
129
|
+
- signals the page sends (`useSignal`) or server code raises (`signal()`), watched with `mostra wait <dir> --until signal:<name>`, which prints each signal's payload;
|
|
130
130
|
- actions that do the work themselves ([server.md](server.md)).
|
|
131
131
|
|
|
132
|
-
`mostra wait <dir> --until submitted` is refused under `none` (`MOSTRA_SUBMIT_POLICY_NONE`)
|
|
132
|
+
`mostra wait <dir> --until submitted` is refused under `none` (`MOSTRA_SUBMIT_POLICY_NONE`), and `mostra results` has no submission to show: read what the page keeps with `mostra state get <dir>`.
|
|
133
133
|
|
|
134
134
|
## New versions of a page people keep open
|
|
135
135
|
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Mostra's MCP server: the same loop through tools
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- When to use the tools
|
|
6
|
+
- The loop, tool by tool
|
|
7
|
+
- Files and directories
|
|
8
|
+
- Waiting and results
|
|
9
|
+
- Links for people
|
|
10
|
+
- Long-lived pages
|
|
11
|
+
- Adding the server to a client
|
|
12
|
+
|
|
13
|
+
## When to use the tools
|
|
14
|
+
|
|
15
|
+
Use Mostra's tools when they're in your tool list (`artifact_create`, `artifact_verify` and the rest): a client starts the server for you, so nothing needs installing, and you need no shell. Each step of the loop in [SKILL.md](../SKILL.md) has its tool, and everything the Skill says about pages, fields, design and verify holds unchanged. Read any part of this guide with `docs_search` and a `topic` (`guide`, `guide/answers`, a diagnostic code), or a `query` of a few words.
|
|
16
|
+
|
|
17
|
+
## The loop, tool by tool
|
|
18
|
+
|
|
19
|
+
| Step | Command | Tool |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| Create | `mostra new <dir>` | `artifact_create` with a `title` (and a `dir`, or one is made for you) |
|
|
22
|
+
| Write | your own file tools | `artifact_write` (whole files), `artifact_patch` (exact replacements or a unified diff) |
|
|
23
|
+
| Verify | `mostra verify <dir>` | `artifact_verify`; `screenshots: "always"` returns both screenshots as images |
|
|
24
|
+
| Publish | `mostra publish <dir>` | `artifact_publish`; its `url` is the default link |
|
|
25
|
+
| Hand out the link | `mostra open <dir> --browser` | `artifact_open` |
|
|
26
|
+
| Wait | `mostra wait <dir> --until submitted` | `artifact_wait` with `until: "submitted"` |
|
|
27
|
+
| Read the answers | `mostra results <dir>` | `artifact_results` (Markdown; `format: "json"` for the full structure) |
|
|
28
|
+
|
|
29
|
+
A tool that fails returns `isError` with `{ "error": <diagnostic> }`: its `code`, `hint` and `docs` mean what the same code means anywhere in this guide. Fix what the hint says and call again.
|
|
30
|
+
|
|
31
|
+
The first time the server runs on a computer, it installs Mostra's runtime in the background (a few minutes on a slow connection). A tool called meanwhile answers `MOSTRA_ENV_RUNTIME_INSTALLING` with how far it is: write the page in the meantime (`artifact_write` and `docs_search` already work), then call the tool again.
|
|
32
|
+
|
|
33
|
+
## Files and directories
|
|
34
|
+
|
|
35
|
+
`artifact_create` returns the artifact's `dir` and its `artifactId`; pass either to the other tools. A relative `dir` is inside the server's workspace folder, which its instructions name. Paths in `artifact_write` and `artifact_patch` are relative to the artifact's directory (`index.tsx`, `components/chart.tsx`), and a tool only ever changes files inside it. Names are ones every system can hold, so the artifact moves between macOS, Linux and Windows whole: no `<>:"|?*`, no device name such as `CON` or `NUL`, no dot or space at the end, and two names that differ only in case are one file.
|
|
36
|
+
|
|
37
|
+
When you also have your own file tools on the same computer, use whichever you like for the files: verify and publish read the directory as it is.
|
|
38
|
+
|
|
39
|
+
`artifact_write` and `artifact_patch` apply all or nothing. When an `old` text appears twice, or a diff's lines don't match the file, nothing is written and `rejected` names each edit or hunk and why; read the file again and send a patch that fits.
|
|
40
|
+
|
|
41
|
+
## Waiting and results
|
|
42
|
+
|
|
43
|
+
`artifact_wait` waits at most 50 seconds per call. When it returns `still_waiting`, nothing is lost: call it again with `after` set to the `cursor` it returned, or do other work and check later. Under `once`, a wait for `submitted` returns at once when the person already submitted. `artifact_results` returns the latest submission; `MOSTRA_SUBMIT_NOT_FOUND` means nobody has submitted yet. A page with the `none` policy never has one: read its shared state with `state_get`, and wait for its signals with `until: "signal:<name>"`, whose event carries the payload the page sent (`event.payload.payload`).
|
|
44
|
+
|
|
45
|
+
## Links for people
|
|
46
|
+
|
|
47
|
+
`artifact_open` returns the artifact's default link. A link made without `viewer` is shared by everyone who holds it: they edit one draft and have one `once` submission between them. For several people, call `artifact_open` once per person with `viewer: { ref, name }` and give each their own link (with `{ policy: "once", scope: "per-viewer" }` each submits once). `ttl`, `scopes` and `version` make a new link that expires, allows less, or opens one version, as in [sharing.md](sharing.md). `open: true` also opens the link in a browser on this computer, for the person sitting at it.
|
|
48
|
+
|
|
49
|
+
Links open on this computer only. To reach someone elsewhere, share it as [sharing.md](sharing.md) shows (`mostra share`).
|
|
50
|
+
|
|
51
|
+
## Long-lived pages
|
|
52
|
+
|
|
53
|
+
`state_get` and `state_patch` read and change the artifact's shared state (fields with `scope: "artifact"`), as `mostra state` does; `live_push` pushes a value to a live source, as `mostra push` does. See [long-lived.md](long-lived.md).
|
|
54
|
+
|
|
55
|
+
## Adding the server to a client
|
|
56
|
+
|
|
57
|
+
A client starts the server as `mostra mcp` over stdio, or `npx -y @mostra/cli@0.10.0 mcp` where `mostra` isn't installed. Its configuration names that command, for example:
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{ "mcpServers": { "mostra": { "command": "npx", "args": ["-y", "@mostra/cli@0.10.0", "mcp"] } } }
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
For a client that speaks only HTTP, `mostra mcp --http` serves Streamable HTTP on `127.0.0.1` and prints its URL and a token on stderr; every request sends `Authorization: Bearer <token>` (set `MOSTRA_MCP_TOKEN` to choose it). `--workspace <dir>` chooses where new artifacts go.
|
|
@@ -4,14 +4,16 @@
|
|
|
4
4
|
|
|
5
5
|
- The link
|
|
6
6
|
- One person, one link
|
|
7
|
-
- The
|
|
7
|
+
- The four setups: local, tailnet share, public share, hosted
|
|
8
|
+
- Hosted on a server
|
|
8
9
|
- Behind a public quick tunnel
|
|
9
10
|
- Managing links and shares
|
|
11
|
+
- Moving a version to another machine
|
|
10
12
|
- Asking people well
|
|
11
13
|
|
|
12
14
|
## The link
|
|
13
15
|
|
|
14
|
-
`mostra publish` prints the artifact's **default link**; `mostra open <dir>` prints it again
|
|
16
|
+
`mostra publish` prints the artifact's **default link**; `mostra open <dir>` prints it again; `--browser` also opens it in this machine's browser (without it, only a terminal opens one), and stderr says when no browser opened. The link is a capability URL: whoever holds it can view, answer, submit and run the page's actions. The secret is after the `#`, so it never reaches a server log, but treat the whole link like a password.
|
|
15
17
|
|
|
16
18
|
The default link doesn't expire and stays the same across versions. It opens on this machine only (`http://127.0.0.1:…`).
|
|
17
19
|
|
|
@@ -28,19 +30,56 @@ mostra open ./retro --new --viewer grace@example.com --viewer-name "Grace Hopper
|
|
|
28
30
|
|
|
29
31
|
Other options of `mostra open <dir> --new`: `--ttl 24h` (the link expires), `--scope view` (look but not answer; also `draft`, `submit`, `review`, `signal`, `action:*`), `--version 3` (only that version).
|
|
30
32
|
|
|
31
|
-
## The
|
|
33
|
+
## The four setups
|
|
32
34
|
|
|
33
35
|
| Setup | Who can open it | Command |
|
|
34
36
|
|---|---|---|
|
|
35
|
-
| **Local** | Only this machine's browser | `mostra open <dir
|
|
37
|
+
| **Local** | Only this machine's browser | `mostra open <dir> --browser` |
|
|
36
38
|
| **Tailnet share** | People and devices in your Tailscale network, such as your phone | `mostra share <dir> --tailnet` |
|
|
37
39
|
| **Public share** | Anyone with the link, on any device | `mostra share <dir> --public` |
|
|
40
|
+
| **Hosted** | Anyone with the link, even while this machine sleeps | `mostra share <dir> --cloud` |
|
|
38
41
|
|
|
39
42
|
- **Tailnet share** uses Tailscale Serve. Each person is their tailnet identity, so results name them without `--viewer`. The link doesn't expire unless you give `--ttl`. The output names the two ports the tailnet's access policy must allow, and the viewer's device must run Tailscale.
|
|
40
43
|
- **Public share** uses a Cloudflare quick tunnel by default (no account needed), or Tailscale Funnel with `--via funnel` (the URL shows your device's tailnet name). The link lasts 1 hour unless `--ttl` says otherwise, 7 days at most. Each public link is a visitor of its own: their answers never mix with yours or anyone else's, and results show them as "Shared link" unless you pass `--viewer`.
|
|
41
44
|
- Both drive tools installed on this machine (`tailscale`, `cloudflared`); when one is missing or signed out, the command says how to install or enable it (`MOSTRA_SHARE_TOOL_MISSING`, `MOSTRA_SHARE_TOOL_NOT_READY`, `MOSTRA_SHARE_NOT_ENABLED`).
|
|
42
45
|
- A share keeps Mostra running while it lasts. A quick tunnel can't keep its address across a restart, so a public Cloudflare share ends when Mostra restarts; tailnet and Funnel shares come back.
|
|
43
46
|
|
|
47
|
+
## Hosted on a server
|
|
48
|
+
|
|
49
|
+
`mostra share <dir> --cloud` puts the latest version on a remote server this machine signed in to, and prints a link there. The page keeps taking answers while this machine is off: they wait on the server and reach `mostra wait` and `mostra results` here when Mostra runs again, the same as local answers. Every later `mostra publish` of the artifact goes to the server too.
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
mostra login https://api.example.com # once per machine: open the address it prints and approve the code
|
|
53
|
+
mostra share ./x --cloud # host it there; prints the hosted link
|
|
54
|
+
mostra status # the servers this machine is linked to, and whether they're connected
|
|
55
|
+
mostra logout # sign out; hosted pages keep working, answers wait for the next login
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
- The person answering sees "Your answer was sent." once the server has it, and nothing about this machine. You see the delivery states.
|
|
59
|
+
- Only the source, its versions and its secrets stay on this machine; the server holds the built page and what people enter.
|
|
60
|
+
- Several machines can sign in to one account. The one that shared a page receives its answers. `mostra login <server> --default` makes this machine the one pages created from a chat app go to.
|
|
61
|
+
- `mostra share stop` and `mostra share list` include hosted shares.
|
|
62
|
+
|
|
63
|
+
### Actions on a hosted page
|
|
64
|
+
|
|
65
|
+
A hosted page's actions run on this machine, with its secrets, while it is connected. The manifest's `hosted` key says how they behave on the server:
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
export const artifact = defineArtifact({
|
|
69
|
+
title: "Proposal",
|
|
70
|
+
hosted: {
|
|
71
|
+
actions: "link", // who may press them: "signed-in" (default) or anyone with the link
|
|
72
|
+
offline: { actions: "queue", limit: "24h" }, // while this machine is off: wait ("queue", default) or fail at once ("fail")
|
|
73
|
+
},
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- By default only people the link names (`--viewer`) or who signed in may run actions; `actions: "link"` lets anyone with the link run them.
|
|
78
|
+
- While this machine is off, a pressed action waits: `useAction`'s `status` is `"waiting"`, and it runs once, in order, when Mostra runs here again. Past `limit` (at most `7d`) a run that never started fails. Under `"fail"` it fails at once.
|
|
79
|
+
- If the connection drops while an action runs and this machine never reports how it ended within the limit, its `status` becomes `"unknown"`: it may have happened, so show that rather than "failed". `run()` rejects with `MOSTRA_REMOTE_OWNER_OFFLINE`; the real end replaces `unknown` if it arrives later.
|
|
80
|
+
- A plain server function (called directly, not through `useAction`) answers `MOSTRA_REMOTE_OWNER_OFFLINE` while this machine is off.
|
|
81
|
+
- Live values show the last value, with `ownerOffline` set, while this machine is off.
|
|
82
|
+
|
|
44
83
|
## Behind a public quick tunnel
|
|
45
84
|
|
|
46
85
|
Over a Cloudflare quick tunnel the page runs in a slightly different mode, and nothing in your code needs to change for it:
|
|
@@ -61,6 +100,17 @@ mostra open ./x --revoke <tokenId> # stop a link
|
|
|
61
100
|
|
|
62
101
|
`--json` output carries each link's `tokenId`.
|
|
63
102
|
|
|
103
|
+
## Moving a version to another machine
|
|
104
|
+
|
|
105
|
+
A published version can move whole to another Mostra home, where it is the same version with the same IDs, and its actions run there:
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
mostra export ./x --out ./x.tar.zst # the latest version; --version 2 for another
|
|
109
|
+
mostra run ./x.tar.zst # on the other machine: imports it and prints its link
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The bundle holds the version's builds, manifest, lockfile and source, never secrets: set the secrets its actions read on the other machine with `mostra secret set`. Answers stay in the home where people gave them.
|
|
113
|
+
|
|
64
114
|
## Asking people well
|
|
65
115
|
|
|
66
116
|
The link arrives as a message from you, so write it like one:
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { r as TelemetryStore, t as flush } from "../flush-
|
|
1
|
+
import { r as TelemetryStore, t as flush } from "../flush-znWmNZA1.js";
|
|
2
2
|
//#region src/telemetry/flush-main.ts
|
|
3
3
|
/**
|
|
4
4
|
* The flusher process (D140 item 6): `node flush-main.js <config dir>`, started detached by the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mostra/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"description": "The mostra command: author, verify, publish, share and wait on agent artifacts, as a thin client of the Mostra host protocol.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "The Mostra Authors",
|
|
@@ -34,12 +34,18 @@
|
|
|
34
34
|
"provenance": true
|
|
35
35
|
},
|
|
36
36
|
"dependencies": {
|
|
37
|
-
"@
|
|
38
|
-
"@
|
|
37
|
+
"@hono/node-server": "2.1.5",
|
|
38
|
+
"@modelcontextprotocol/server": "2.4.0",
|
|
39
|
+
"@mostra/mcp": "0.10.0",
|
|
40
|
+
"@mostra/protocol": "0.10.0",
|
|
41
|
+
"@mostra/sdk": "0.10.0",
|
|
39
42
|
"zod": "4.6.7"
|
|
40
43
|
},
|
|
41
44
|
"devDependencies": {
|
|
42
|
-
"@
|
|
45
|
+
"@modelcontextprotocol/client": "2.4.0",
|
|
46
|
+
"@modelcontextprotocol/conformance": "0.1.16",
|
|
47
|
+
"@modelcontextprotocol/conformance-next": "npm:@modelcontextprotocol/conformance@0.2.0-alpha.12",
|
|
48
|
+
"@mostra/runtime": "0.10.0",
|
|
43
49
|
"@mostra/tools": "0.0.0",
|
|
44
50
|
"@types/node": "24.19.2",
|
|
45
51
|
"tsdown": "0.23.1",
|
package/src/bootstrap.ts
CHANGED
|
@@ -17,6 +17,7 @@ import { createDiagnostic, type Diagnostic, RpcError } from "@mostra/protocol";
|
|
|
17
17
|
import { enclosingBundle, type InstallProgress, readPins, resolveRuntime } from "@mostra/sdk";
|
|
18
18
|
import { exitCodeFor } from "./exit.ts";
|
|
19
19
|
import type { Environment } from "./home.ts";
|
|
20
|
+
import { commandWords } from "./parse.ts";
|
|
20
21
|
|
|
21
22
|
/** How the bootstrap talks to the terminal. */
|
|
22
23
|
export interface BootstrapIo {
|
|
@@ -41,8 +42,19 @@ export function needsBootstrap(env: Environment): boolean {
|
|
|
41
42
|
return readPins(env) !== undefined;
|
|
42
43
|
}
|
|
43
44
|
|
|
45
|
+
/**
|
|
46
|
+
* Whether the command serves in this process instead of in the bundle (D164 item 7): `mostra mcp`
|
|
47
|
+
* answers its client at once and installs the bundle in the background, since a client gives a
|
|
48
|
+
* server only seconds to start (Codex 10 s) and a first install takes minutes.
|
|
49
|
+
*/
|
|
50
|
+
export function servesBeforeBundle(argv: readonly string[]): boolean {
|
|
51
|
+
return commandWords(argv)[0] === "mcp";
|
|
52
|
+
}
|
|
53
|
+
|
|
44
54
|
/** Progress lines for a person waiting on the first download. */
|
|
45
|
-
function progressReporter(
|
|
55
|
+
export function progressReporter(
|
|
56
|
+
io: Pick<BootstrapIo, "stderr" | "stderrTty">,
|
|
57
|
+
): (progress: InstallProgress) => void {
|
|
46
58
|
let lastPercent = -1;
|
|
47
59
|
let lastStep = "";
|
|
48
60
|
return (progress) => {
|
|
@@ -88,7 +100,8 @@ function failed(io: BootstrapIo, diagnostic: Diagnostic): number {
|
|
|
88
100
|
|
|
89
101
|
/**
|
|
90
102
|
* When this copy needs the bundle its release pins (`needsBootstrap`), runs the bundle's
|
|
91
|
-
* `mostra` with `io.argv` and resolves with its exit code; otherwise
|
|
103
|
+
* `mostra` with `io.argv` and resolves with its exit code; otherwise, or for `mostra mcp`, which
|
|
104
|
+
* installs the bundle itself while it serves (`servesBeforeBundle`), resolves `undefined`, and the
|
|
92
105
|
* caller runs the command itself. Any failure, deciding included, is a diagnostic (one envelope
|
|
93
106
|
* with `--json`) and its exit code. Signals this process gets are passed on to the child.
|
|
94
107
|
*/
|
|
@@ -96,7 +109,7 @@ export async function bootstrap(io: BootstrapIo): Promise<number | undefined> {
|
|
|
96
109
|
try {
|
|
97
110
|
// Deciding is inside the boundary too: pins that can't be read are a diagnostic, never a
|
|
98
111
|
// stack trace (GPT review finding 3).
|
|
99
|
-
if (!needsBootstrap(io.env)) return undefined;
|
|
112
|
+
if (!needsBootstrap(io.env) || servesBeforeBundle(io.argv)) return undefined;
|
|
100
113
|
return await runInBundle(io);
|
|
101
114
|
} catch (error) {
|
|
102
115
|
// Whatever goes wrong, `--json` still gets exactly one envelope (D140 item 16).
|
package/src/client.ts
CHANGED
|
@@ -37,7 +37,7 @@ export interface InstanceSummary {
|
|
|
37
37
|
/** Its process ID. */
|
|
38
38
|
readonly pid: number;
|
|
39
39
|
/** `daemon`, or `host` for an instance a host spawned (telemetry sends nothing then, D140). */
|
|
40
|
-
readonly mode: "host" | "daemon";
|
|
40
|
+
readonly mode: "host" | "daemon" | "hosted";
|
|
41
41
|
/** The runtime's release. */
|
|
42
42
|
readonly version: string;
|
|
43
43
|
/** Whether this command started the daemon. */
|
package/src/command.ts
CHANGED
|
@@ -70,6 +70,11 @@ export interface CommandContext {
|
|
|
70
70
|
readonly home: string;
|
|
71
71
|
/** Records a telemetry event of this command (D140 item 8), when telemetry allows it. */
|
|
72
72
|
record(event: TelemetryEventInput): void;
|
|
73
|
+
/**
|
|
74
|
+
* Queues the events recorded so far, for a command that runs until it is stopped (`mcp`);
|
|
75
|
+
* `hostInstance` says whether the instance it reached was host-spawned (then nothing is sent).
|
|
76
|
+
*/
|
|
77
|
+
checkpoint(hostInstance: boolean): void;
|
|
73
78
|
/**
|
|
74
79
|
* The session with the home's instance, starting its daemon unless `autostart` is false; then
|
|
75
80
|
* `undefined` when none runs. `call` uses the same session.
|
|
@@ -91,7 +96,7 @@ export interface CommandContext {
|
|
|
91
96
|
/** A command-specific telemetry event: its name and its own fields. */
|
|
92
97
|
export interface TelemetryEventInput {
|
|
93
98
|
/** The event's name. */
|
|
94
|
-
readonly event: "verify.result" | "publish.done" | "share.done";
|
|
99
|
+
readonly event: "verify.result" | "publish.done" | "share.done" | "mcp.session";
|
|
95
100
|
/** Its own fields; the schema keeps only the published ones. */
|
|
96
101
|
readonly fields: Readonly<Record<string, unknown>>;
|
|
97
102
|
}
|
|
@@ -106,6 +111,8 @@ export interface CommandOutcome {
|
|
|
106
111
|
readonly exit?: number;
|
|
107
112
|
/** The command wrote its own stdout (`host`): the runner prints no envelope and no text. */
|
|
108
113
|
readonly raw?: boolean;
|
|
114
|
+
/** The instance the command reached on a session of its own was host-spawned (`mcp`). */
|
|
115
|
+
readonly hostInstance?: boolean;
|
|
109
116
|
}
|
|
110
117
|
|
|
111
118
|
/** One command. */
|
|
@@ -130,8 +137,11 @@ export interface CommandDef {
|
|
|
130
137
|
readonly local?: boolean;
|
|
131
138
|
/** It writes a stream of events before its result (NDJSON in `--json` mode). */
|
|
132
139
|
readonly streams?: boolean;
|
|
133
|
-
/**
|
|
134
|
-
|
|
140
|
+
/**
|
|
141
|
+
* Telemetry and its question leave it alone (`telemetry`, `docs`, D140 item 11), or, as a
|
|
142
|
+
* function of its flags, when it runs on someone's behalf (`mcp --embedded`, D148).
|
|
143
|
+
*/
|
|
144
|
+
readonly quiet?: boolean | ((flags: CommandContext["flags"]) => boolean);
|
|
135
145
|
/** Does the command's work. */
|
|
136
146
|
run(context: CommandContext): Promise<CommandOutcome>;
|
|
137
147
|
}
|
package/src/commands/admin.ts
CHANGED
|
@@ -163,7 +163,17 @@ export const statusCommand: CommandDef = defineCommand({
|
|
|
163
163
|
return { result: detail, human: `${detail.id} ${detail.title}\n${versions}` };
|
|
164
164
|
}
|
|
165
165
|
const status = await context.call(instanceStatusMethod, {});
|
|
166
|
-
|
|
166
|
+
// Each remote server this home is linked to, by its state (INTERFACES §18.7).
|
|
167
|
+
const links = (status.links ?? [])
|
|
168
|
+
.map(
|
|
169
|
+
(link) =>
|
|
170
|
+
`${link.server} ${link.state}${link.default ? " default" : ""}${link.pendingPushes > 0 ? ` ${link.pendingPushes} pushes waiting` : ""}${link.lastError ? ` (${link.lastError})` : ""}\n`,
|
|
171
|
+
)
|
|
172
|
+
.join("");
|
|
173
|
+
return {
|
|
174
|
+
result: status,
|
|
175
|
+
human: `${pretty(status)}${links ? `\nRemote servers:\n${links}` : ""}`,
|
|
176
|
+
};
|
|
167
177
|
},
|
|
168
178
|
});
|
|
169
179
|
|
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Authoring: `new`, `verify`, `publish` and `add`, thin clients of
|
|
3
|
-
* `artifact/verify`, `artifact/publish`
|
|
2
|
+
* Authoring: `new`, `verify`, `publish`, `export`, `run` and `add`, thin clients of
|
|
3
|
+
* `artifact/create`, `artifact/verify`, `artifact/publish`, `artifact/export`, `artifact/import`
|
|
4
|
+
* and `deps/add` (INTERFACES §6, §15).
|
|
4
5
|
*/
|
|
5
6
|
import { randomUUID } from "node:crypto";
|
|
6
7
|
import { resolve } from "node:path";
|
|
7
8
|
import {
|
|
8
9
|
ARTIFACT_PROGRESS,
|
|
9
10
|
artifactCreateMethod,
|
|
11
|
+
artifactExportMethod,
|
|
12
|
+
artifactImportMethod,
|
|
10
13
|
artifactPublishMethod,
|
|
11
14
|
artifactVerifyMethod,
|
|
12
15
|
depsAddMethod,
|
|
@@ -16,7 +19,7 @@ import {
|
|
|
16
19
|
import { type CommandDef, defineCommand } from "../command.ts";
|
|
17
20
|
import { EXIT } from "../exit.ts";
|
|
18
21
|
import { usage } from "../parse.ts";
|
|
19
|
-
import { arg, flag, sourceRef } from "./shared.ts";
|
|
22
|
+
import { arg, artifactRef, flag, sourceRef } from "./shared.ts";
|
|
20
23
|
|
|
21
24
|
/** `mostra new <dir>`. */
|
|
22
25
|
export const newCommand: CommandDef = defineCommand({
|
|
@@ -197,6 +200,85 @@ export const publishCommand: CommandDef = defineCommand({
|
|
|
197
200
|
},
|
|
198
201
|
});
|
|
199
202
|
|
|
203
|
+
/** `mostra export <artifact> --as bundle --out <path>`. */
|
|
204
|
+
export const exportCommand: CommandDef = defineCommand({
|
|
205
|
+
path: ["export"],
|
|
206
|
+
summary: "Write a published version out of the home, as a portable bundle another home can run.",
|
|
207
|
+
args: [{ name: "artifact", summary: "The artifact: its source path or its ID." }],
|
|
208
|
+
flags: [
|
|
209
|
+
{
|
|
210
|
+
name: "as",
|
|
211
|
+
kind: "string",
|
|
212
|
+
value: "<class>",
|
|
213
|
+
choices: ["bundle"],
|
|
214
|
+
default: "bundle",
|
|
215
|
+
summary: "What to write: `bundle`, the version's builds, manifest, lockfile and source.",
|
|
216
|
+
},
|
|
217
|
+
{
|
|
218
|
+
name: "out",
|
|
219
|
+
kind: "string",
|
|
220
|
+
value: "<path>",
|
|
221
|
+
summary: "Where: a new directory, or one archive when it ends in .tar.zst.",
|
|
222
|
+
},
|
|
223
|
+
{
|
|
224
|
+
name: "version",
|
|
225
|
+
kind: "string",
|
|
226
|
+
value: "<number|id>",
|
|
227
|
+
summary: "The version. Default: the latest.",
|
|
228
|
+
},
|
|
229
|
+
],
|
|
230
|
+
output: { type: "ArtifactExportResult", topic: "cli" },
|
|
231
|
+
exits: [EXIT.failure],
|
|
232
|
+
example: "export ./sidebar-review --out ./sidebar-review.tar.zst",
|
|
233
|
+
async run(context) {
|
|
234
|
+
const out = flag(context, "out");
|
|
235
|
+
if (out === undefined) throw usage('"mostra export" needs --out <path>.');
|
|
236
|
+
const version = flag(context, "version");
|
|
237
|
+
const result = await context.call(artifactExportMethod, {
|
|
238
|
+
artifact: artifactRef(arg(context, "artifact"), context.cwd),
|
|
239
|
+
as: "bundle",
|
|
240
|
+
out: resolve(context.cwd, out),
|
|
241
|
+
...(version !== undefined
|
|
242
|
+
? { version: /^\d+$/.test(version) ? Number(version) : version }
|
|
243
|
+
: {}),
|
|
244
|
+
});
|
|
245
|
+
return {
|
|
246
|
+
result,
|
|
247
|
+
human: `Exported ${result.versionId} to ${result.files.join(", ")}\n`,
|
|
248
|
+
};
|
|
249
|
+
},
|
|
250
|
+
});
|
|
251
|
+
|
|
252
|
+
/** `mostra run <bundle>`. */
|
|
253
|
+
export const runCommand: CommandDef = defineCommand({
|
|
254
|
+
path: ["run"],
|
|
255
|
+
summary:
|
|
256
|
+
"Make a bundle `mostra export` wrote a version of this home, with the same IDs, and print its link.",
|
|
257
|
+
args: [{ name: "bundle", summary: "The bundle: its directory or its .tar.zst archive." }],
|
|
258
|
+
flags: [
|
|
259
|
+
{
|
|
260
|
+
name: "request-id",
|
|
261
|
+
kind: "string",
|
|
262
|
+
value: "<id>",
|
|
263
|
+
summary: "Make a retry return the first attempt's receipt.",
|
|
264
|
+
},
|
|
265
|
+
],
|
|
266
|
+
output: { type: "PublishReceipt", topic: "cli" },
|
|
267
|
+
exits: [EXIT.failure],
|
|
268
|
+
example: "run ./sidebar-review.tar.zst",
|
|
269
|
+
async run(context) {
|
|
270
|
+
const requestId = flag(context, "request-id");
|
|
271
|
+
const receipt = await context.call(artifactImportMethod, {
|
|
272
|
+
bundle: resolve(context.cwd, arg(context, "bundle")),
|
|
273
|
+
...(requestId !== undefined ? { requestId } : {}),
|
|
274
|
+
});
|
|
275
|
+
return {
|
|
276
|
+
result: receipt,
|
|
277
|
+
human: `${receipt.reused ? "Already here" : "Imported"}: version ${receipt.version} (${receipt.versionId}) of ${receipt.artifactId}\n${receipt.url ?? ""}\n`,
|
|
278
|
+
};
|
|
279
|
+
},
|
|
280
|
+
});
|
|
281
|
+
|
|
200
282
|
/** `mostra add <package…>`. */
|
|
201
283
|
export const addCommand: CommandDef = defineCommand({
|
|
202
284
|
path: ["add"],
|