@mostra/cli 0.9.0 → 0.11.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 (57) hide show
  1. package/dist/bin.js +2 -2
  2. package/dist/bootstrap-BStzS_41.js +1 -0
  3. package/dist/{bootstrap-Dc-SQHRF.js → bootstrap-_iCl_HaO.js} +3 -2
  4. package/dist/bootstrap-_iCl_HaO.js.map +1 -0
  5. package/dist/{flush-C16w3JL8.js → flush-D648gCYs.js} +12 -3
  6. package/dist/flush-D648gCYs.js.map +1 -0
  7. package/dist/index.d.ts +1 -1
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +2 -2
  10. package/dist/reference/cli.md +210 -4
  11. package/dist/reference/diagnostics.json +171 -0
  12. package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
  13. package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
  14. package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
  15. package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
  16. package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
  17. package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
  18. package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.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_NO_INSTANCE.md +23 -0
  22. package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
  23. package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
  24. package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
  25. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
  26. package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
  27. package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
  28. package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
  29. package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
  30. package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
  31. package/dist/reference/self-hosting.md +130 -0
  32. package/dist/run-Bpg_ZRY8.js +1 -0
  33. package/dist/{run-DdYT3iHQ.js → run-BxYL-DaX.js} +333 -225
  34. package/dist/run-BxYL-DaX.js.map +1 -0
  35. package/dist/skill/SKILL.md +5 -3
  36. package/dist/skill/references/answers.md +36 -0
  37. package/dist/skill/references/mcp.md +9 -4
  38. package/dist/skill/references/sharing.md +55 -4
  39. package/dist/telemetry/flush-main.js +1 -1
  40. package/package.json +5 -5
  41. package/src/client.ts +1 -1
  42. package/src/commands/admin.ts +13 -3
  43. package/src/commands/authoring.ts +85 -3
  44. package/src/commands/index.ts +18 -3
  45. package/src/commands/remote.ts +209 -0
  46. package/src/commands/sharing.ts +33 -6
  47. package/src/commands/viewing.ts +20 -2
  48. package/src/detached.ts +3 -0
  49. package/src/docs.ts +12 -217
  50. package/src/exit.ts +2 -0
  51. package/src/mcp.ts +3 -21
  52. package/src/telemetry/store.ts +15 -4
  53. package/dist/bootstrap-Dc-SQHRF.js.map +0 -1
  54. package/dist/bootstrap-aaE5wFo9.js +0 -1
  55. package/dist/flush-C16w3JL8.js.map +0 -1
  56. package/dist/run-Bw4_6kcW.js +0 -1
  57. package/dist/run-DdYT3iHQ.js.map +0 -1
@@ -1,13 +1,13 @@
1
- import { a as GLOBAL_FLAGS, c as parseCommandLine, d as EXIT, f as exitCodeFor, l as topWords, m as defineCommand, o as durationMs, p as commandName, r as progressReporter, s as globalFlags, u as usage } from "./bootstrap-Dc-SQHRF.js";
2
- import { _ as packageRoot, a as detachedEnvironment, c as durationBucket, d as mcpSessionFields, f as buildEndpoint, g as fromSource, h as cliVersion, i as detachedDirectory, l as minute, m as truthy, n as startFlusher, o as TelemetryEvent, p as decide, r as TelemetryStore, s as catalogCodes, u as detectHarness } from "./flush-C16w3JL8.js";
1
+ import { a as GLOBAL_FLAGS, c as parseCommandLine, d as EXIT, f as exitCodeFor, l as topWords, m as defineCommand, o as durationMs, p as commandName, r as progressReporter, s as globalFlags, u as usage } from "./bootstrap-_iCl_HaO.js";
2
+ import { _ as packageRoot, a as detachedEnvironment, c as durationBucket, d as mcpSessionFields, f as buildEndpoint, g as fromSource, h as cliVersion, i as detachedDirectory, l as minute, m as truthy, n as startFlusher, o as TelemetryEvent, p as decide, r as TelemetryStore, s as catalogCodes, u as detectHarness } from "./flush-D648gCYs.js";
3
3
  import { spawn } from "node:child_process";
4
4
  import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, writeFileSync } from "node:fs";
5
- import { extname, isAbsolute, join, resolve, win32 } from "node:path";
6
- import { ARTIFACT_PROGRESS, CLI_CLIENT_NAME, DEFAULT_DOCS_BASE, DEV_NOTIFY, FieldOp, HOST_PROTOCOL_REVISIONS, LineSplitter, MutationId, RpcError, RpcPeer, artifactCreateMethod, artifactGetMethod, artifactListMethod, artifactPublishMethod, artifactVerifyMethod, createDiagnostic, depsAddMethod, devStartMethod, devStopMethod, diagnosticCatalog, encodeLine, gcRunMethod, instanceCheckMethod, instanceStatusMethod, livePushMethod, mostraInitializeMethod, mostraShutdownMethod, resultsGetMethod, secretDeleteMethod, secretListMethod, secretSetMethod, shareListMethod, shareStartMethod, shareStopMethod, stateGetMethod, statePatchMethod, viewDefaultMethod, viewLaunchMethod, viewRevokeMethod, viewRotateMethod, viewUrlMethod, waitMethod } from "@mostra/protocol";
5
+ import { isAbsolute, join, resolve, win32 } from "node:path";
6
+ import { ARTIFACT_PROGRESS, CLI_CLIENT_NAME, DEFAULT_DOCS_BASE, DEV_NOTIFY, FieldOp, HOST_PROTOCOL_REVISIONS, LineSplitter, MutationId, RpcError, RpcPeer, artifactCreateMethod, artifactExportMethod, artifactGetMethod, artifactImportMethod, artifactListMethod, artifactPauseMethod, artifactPublishMethod, artifactVerifyMethod, createDiagnostic, depsAddMethod, devStartMethod, devStopMethod, diagnosticCatalog, encodeLine, gcRunMethod, instanceCheckMethod, instanceStatusMethod, livePushMethod, mostraInitializeMethod, mostraShutdownMethod, remoteLinkMethod, remoteLoginMethod, remoteLoginWaitMethod, remoteLogoutMethod, resultsGetMethod, secretDeleteMethod, secretListMethod, secretSetMethod, shareListMethod, shareStartMethod, shareStopMethod, stateGetMethod, statePatchMethod, viewDefaultMethod, viewLaunchMethod, viewRevokeMethod, viewRotateMethod, viewUrlMethod, waitMethod } from "@mostra/protocol";
7
7
  import { checkBrowser, checkFiles, connectControl, enclosingBundle, readBundle, readSetup, resolveRuntime } from "@mostra/sdk";
8
+ import { MCP_GUIDE_LINKS, MCP_PATH, createHttpEndpoint, createMcpServerFactory, defaultWorkspaceRoot, docsIndex, fileDocs, indexMarkdown, localWorkspace, nearestTopics, topicMarkdown } from "@mostra/mcp";
8
9
  import { homedir, tmpdir } from "node:os";
9
10
  import { randomBytes, randomUUID } from "node:crypto";
10
- import { MCP_PATH, createHttpEndpoint, createMcpServerFactory, defaultWorkspaceRoot, localWorkspace } from "@mostra/mcp";
11
11
  import { isIP } from "node:net";
12
12
  import { serve } from "@hono/node-server";
13
13
  import { serveStdio } from "@modelcontextprotocol/server/stdio";
@@ -30,190 +30,9 @@ function skillDir() {
30
30
  const bundled = join(packageRoot(), "dist", "skill");
31
31
  return !fromSource() && existsSync(bundled) ? bundled : join(packageRoot(), "..", "..", "skills", "mostra");
32
32
  }
33
- function titleOf(file) {
34
- const first = readFileSync(file, "utf8").split("\n").find((line) => line.startsWith("# "));
35
- return first ? first.slice(2).trim() : "";
36
- }
37
- /** Every topic, the pages first and then the codes, sorted. */
38
- function docsIndex(dir = referenceDir()) {
39
- const base = DEFAULT_DOCS_BASE.replace(/\/+$/, "");
40
- const pages = [];
41
- for (const topic of ["cli", "telemetry"]) {
42
- const file = join(dir, `${topic}.md`);
43
- if (existsSync(file)) pages.push({
44
- topic,
45
- title: titleOf(file),
46
- url: `${base}/${topic}`,
47
- file
48
- });
49
- }
50
- const errorsDir = join(dir, "errors");
51
- const errors = (existsSync(errorsDir) ? readdirSync(errorsDir).filter((name) => /^MOSTRA_[A-Z0-9_]+\.md$/.test(name)).sort() : []).map((name) => {
52
- const code = name.slice(0, -3);
53
- const file = join(errorsDir, name);
54
- return {
55
- topic: code,
56
- title: titleOf(file),
57
- url: `${base}/errors/${code}`,
58
- file
59
- };
60
- });
61
- return [
62
- ...pages,
63
- ...guideTopics(skillDir(), base),
64
- ...errors
65
- ];
66
- }
67
- const byName = (a, b) => a.name < b.name ? -1 : 1;
68
- /** Every file below `root`'s `prefix`, relative to `root`, sorted. */
69
- function filesBelow(root, prefix) {
70
- return readdirSync(join(root, prefix), { withFileTypes: true }).sort(byName).flatMap((entry) => {
71
- const path = `${prefix}/${entry.name}`;
72
- return entry.isDirectory() ? filesBelow(root, path) : [path];
73
- });
74
- }
75
- /**
76
- * The Skill as topics: `guide` (its SKILL.md), `guide/<name>` for each reference,
77
- * `guide/<file>` for each asset (the baseline stylesheet), and `guide/examples/<name>` for each
78
- * example, every file of it.
79
- */
80
- function guideTopics(dir, base) {
81
- const skill = join(dir, "SKILL.md");
82
- if (!existsSync(skill)) return [];
83
- const topics = [{
84
- topic: "guide",
85
- title: "Using Mostra",
86
- url: `${base}/guide`,
87
- file: skill
88
- }];
89
- const references = join(dir, "references");
90
- if (existsSync(references)) for (const name of readdirSync(references).filter((entry) => entry.endsWith(".md")).sort()) {
91
- const file = join(references, name);
92
- const slug = name.slice(0, -3);
93
- topics.push({
94
- topic: `guide/${slug}`,
95
- title: titleOf(file),
96
- url: `${base}/guide/${slug}`,
97
- file
98
- });
99
- }
100
- const assets = join(dir, "assets");
101
- if (!existsSync(assets)) return topics;
102
- for (const entry of readdirSync(assets, { withFileTypes: true }).sort(byName)) {
103
- if (!entry.isFile()) continue;
104
- topics.push({
105
- topic: `guide/${entry.name}`,
106
- title: entry.name,
107
- url: `${base}/guide/${entry.name}`,
108
- file: join(assets, entry.name),
109
- files: [entry.name]
110
- });
111
- }
112
- const examples = join(assets, "examples");
113
- if (!existsSync(examples)) return topics;
114
- for (const entry of readdirSync(examples, { withFileTypes: true }).sort(byName)) {
115
- if (!entry.isDirectory()) continue;
116
- const files = filesBelow(assets, `examples/${entry.name}`);
117
- if (files.length === 0) continue;
118
- topics.push({
119
- topic: `guide/examples/${entry.name}`,
120
- title: `Example: ${entry.name}`,
121
- url: `${base}/guide/examples/${entry.name}`,
122
- file: join(assets, files[0]),
123
- files
124
- });
125
- }
126
- return topics;
127
- }
128
- const FENCE_LANGUAGES = {
129
- ".css": "css",
130
- ".json": "json",
131
- ".md": "md",
132
- ".mdx": "mdx",
133
- ".ts": "ts",
134
- ".tsx": "tsx"
135
- };
136
- /** How the guide's relative links read through the CLI, before each of its pages. */
137
- const GUIDE_LINKS = "> Read through `mostra docs`: a link to `references/<name>.md` is `mostra docs guide/<name>`, `assets/<file>` is `mostra docs guide/<file>`, and `assets/examples/<name>/` is `mostra docs guide/examples/<name>`.";
138
- /** The same for the guide read through `mostra mcp` (D164): topics of `docs_search`, or resources. */
139
- const MCP_GUIDE_LINKS = "> Read through Mostra's MCP server: a link to `references/<name>.md` is the topic `guide/<name>`, `assets/<file>` is `guide/<file>`, and `assets/examples/<name>/` is `guide/examples/<name>`; read one with docs_search (`topic`) or the resource `mostra://docs/<topic>`. Where the guide runs a `mostra` command, use the tool of the same step (artifact_verify for `mostra verify`, artifact_wait for `mostra wait`).";
140
- /**
141
- * A topic's Markdown. A guide page loses its frontmatter and says how its links read (through the
142
- * CLI by default, or `links`); a guide topic made of files shows each one as code under its path.
143
- */
144
- function topicMarkdown(topic, dir = skillDir(), links = GUIDE_LINKS) {
145
- if (topic.files !== void 0) {
146
- const parts = topic.files.map((path) => {
147
- const text = readFileSync(join(dir, "assets", path), "utf8");
148
- const fence = text.includes("```") ? "````" : "```";
149
- const body = text.endsWith("\n") ? text : `${text}\n`;
150
- return `## \`${path}\`\n\n${fence}${FENCE_LANGUAGES[extname(path)] ?? ""}\n${body}${fence}\n`;
151
- });
152
- return [
153
- `# ${topic.title}`,
154
- "",
155
- links,
156
- "",
157
- ...parts
158
- ].join("\n");
159
- }
160
- const text = readFileSync(topic.file, "utf8");
161
- if (topic.topic !== "guide" && !topic.topic.startsWith("guide/")) return text;
162
- return [
163
- links,
164
- "",
165
- text.replace(/^---\n[\s\S]*?\n---\n+/, "")
166
- ].join("\n");
167
- }
168
- /** The index as Markdown: what `mostra docs` prints without a topic. */
169
- function indexMarkdown(topics) {
170
- const pages = topics.filter((topic) => !topic.topic.startsWith("MOSTRA_") && !topic.topic.startsWith("guide"));
171
- const guide = topics.filter((topic) => topic.topic === "guide" || topic.topic.startsWith("guide/"));
172
- const codes = topics.filter((topic) => topic.topic.startsWith("MOSTRA_"));
173
- return [
174
- "# Mostra reference",
175
- "",
176
- "Run `mostra docs <topic>` to read one. Diagnostic codes are topics too.",
177
- "",
178
- ...pages.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
179
- "",
180
- ...guide.length > 0 ? [
181
- "## Writing artifacts",
182
- "",
183
- ...guide.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
184
- ""
185
- ] : [],
186
- "## Diagnostic codes",
187
- "",
188
- ...codes.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
189
- ""
190
- ].join("\n");
191
- }
192
- /** The topics nearest an unknown one, for its usage error. */
193
- function nearestTopics(wanted, topics, count = 3) {
194
- const target = wanted.toUpperCase();
195
- return topics.map((topic) => {
196
- const name = topic.topic.toUpperCase();
197
- const contains = name.includes(target) || target.includes(name) ? 0 : 1;
198
- return {
199
- topic: topic.topic,
200
- score: contains * 100 + distance(name, target)
201
- };
202
- }).sort((a, b) => a.score - b.score || (a.topic < b.topic ? -1 : 1)).slice(0, count).map((item) => item.topic);
203
- }
204
- /** Levenshtein distance. */
205
- function distance(a, b) {
206
- const row = Array.from({ length: b.length + 1 }, (_, index) => index);
207
- for (let i = 1; i <= a.length; i += 1) {
208
- let previous = row[0];
209
- row[0] = i;
210
- for (let j = 1; j <= b.length; j += 1) {
211
- const current = row[j];
212
- row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
213
- previous = current;
214
- }
215
- }
216
- return row[b.length];
33
+ /** Every topic of the reference this CLI ships, the pages first and then the codes, sorted. */
34
+ function docsIndex$1(dir = referenceDir()) {
35
+ return docsIndex(dir, skillDir());
217
36
  }
218
37
  //#endregion
219
38
  //#region src/home.ts
@@ -1561,9 +1380,10 @@ const statusCommand = defineCommand({
1561
1380
  };
1562
1381
  }
1563
1382
  const status = await context.call(instanceStatusMethod, {});
1383
+ const links = (status.links ?? []).map((link) => `${link.server} ${link.state}${link.default ? " default" : ""}${link.pendingPushes > 0 ? ` ${link.pendingPushes} pushes waiting` : ""}${link.lastError ? ` (${link.lastError})` : ""}\n`).join("");
1564
1384
  return {
1565
1385
  result: status,
1566
- human: pretty(status)
1386
+ human: `${pretty(status)}${links ? `\nRemote servers:\n${links}` : ""}`
1567
1387
  };
1568
1388
  }
1569
1389
  });
@@ -2059,7 +1879,7 @@ const docsCommand = defineCommand({
2059
1879
  local: true,
2060
1880
  quiet: true,
2061
1881
  async run(context) {
2062
- const topics = docsIndex();
1882
+ const topics = docsIndex$1();
2063
1883
  const wanted = context.args["topic"];
2064
1884
  if (typeof wanted !== "string") {
2065
1885
  const markdown = indexMarkdown(topics);
@@ -2079,7 +1899,7 @@ const docsCommand = defineCommand({
2079
1899
  }
2080
1900
  const found = topics.find((topic) => topic.topic === wanted || topic.topic === wanted.toUpperCase());
2081
1901
  if (!found) throw usage(`No topic "${wanted}". The nearest: ${nearestTopics(wanted, topics).join(", ")}. Run "mostra docs" for the index.`);
2082
- const markdown = topicMarkdown(found);
1902
+ const markdown = topicMarkdown(found, skillDir());
2083
1903
  return {
2084
1904
  result: {
2085
1905
  topic: found.topic,
@@ -2191,8 +2011,9 @@ const telemetryOffCommand = defineCommand({
2191
2011
  //#endregion
2192
2012
  //#region src/commands/authoring.ts
2193
2013
  /**
2194
- * Authoring: `new`, `verify`, `publish` and `add`, thin clients of `artifact/create`,
2195
- * `artifact/verify`, `artifact/publish` and `deps/add` (INTERFACES §6).
2014
+ * Authoring: `new`, `verify`, `publish`, `export`, `run` and `add`, thin clients of
2015
+ * `artifact/create`, `artifact/verify`, `artifact/publish`, `artifact/export`, `artifact/import`
2016
+ * and `deps/add` (INTERFACES §6, §15).
2196
2017
  */
2197
2018
  /** `mostra new <dir>`. */
2198
2019
  const newCommand = defineCommand({
@@ -2379,6 +2200,90 @@ const publishCommand = defineCommand({
2379
2200
  };
2380
2201
  }
2381
2202
  });
2203
+ /** `mostra export <artifact> --as bundle --out <path>`. */
2204
+ const exportCommand = defineCommand({
2205
+ path: ["export"],
2206
+ summary: "Write a published version out of the home, as a portable bundle another home can run.",
2207
+ args: [{
2208
+ name: "artifact",
2209
+ summary: "The artifact: its source path or its ID."
2210
+ }],
2211
+ flags: [
2212
+ {
2213
+ name: "as",
2214
+ kind: "string",
2215
+ value: "<class>",
2216
+ choices: ["bundle"],
2217
+ default: "bundle",
2218
+ summary: "What to write: `bundle`, the version's builds, manifest, lockfile and source."
2219
+ },
2220
+ {
2221
+ name: "out",
2222
+ kind: "string",
2223
+ value: "<path>",
2224
+ summary: "Where: a new directory, or one archive when it ends in .tar.zst."
2225
+ },
2226
+ {
2227
+ name: "version",
2228
+ kind: "string",
2229
+ value: "<number|id>",
2230
+ summary: "The version. Default: the latest."
2231
+ }
2232
+ ],
2233
+ output: {
2234
+ type: "ArtifactExportResult",
2235
+ topic: "cli"
2236
+ },
2237
+ exits: [EXIT.failure],
2238
+ example: "export ./sidebar-review --out ./sidebar-review.tar.zst",
2239
+ async run(context) {
2240
+ const out = flag(context, "out");
2241
+ if (out === void 0) throw usage("\"mostra export\" needs --out <path>.");
2242
+ const version = flag(context, "version");
2243
+ const result = await context.call(artifactExportMethod, {
2244
+ artifact: artifactRef(arg(context, "artifact"), context.cwd),
2245
+ as: "bundle",
2246
+ out: resolve(context.cwd, out),
2247
+ ...version !== void 0 ? { version: /^\d+$/.test(version) ? Number(version) : version } : {}
2248
+ });
2249
+ return {
2250
+ result,
2251
+ human: `Exported ${result.versionId} to ${result.files.join(", ")}\n`
2252
+ };
2253
+ }
2254
+ });
2255
+ /** `mostra run <bundle>`. */
2256
+ const runCommand = defineCommand({
2257
+ path: ["run"],
2258
+ summary: "Make a bundle `mostra export` wrote a version of this home, with the same IDs, and print its link.",
2259
+ args: [{
2260
+ name: "bundle",
2261
+ summary: "The bundle: its directory or its .tar.zst archive."
2262
+ }],
2263
+ flags: [{
2264
+ name: "request-id",
2265
+ kind: "string",
2266
+ value: "<id>",
2267
+ summary: "Make a retry return the first attempt's receipt."
2268
+ }],
2269
+ output: {
2270
+ type: "PublishReceipt",
2271
+ topic: "cli"
2272
+ },
2273
+ exits: [EXIT.failure],
2274
+ example: "run ./sidebar-review.tar.zst",
2275
+ async run(context) {
2276
+ const requestId = flag(context, "request-id");
2277
+ const receipt = await context.call(artifactImportMethod, {
2278
+ bundle: resolve(context.cwd, arg(context, "bundle")),
2279
+ ...requestId !== void 0 ? { requestId } : {}
2280
+ });
2281
+ return {
2282
+ result: receipt,
2283
+ human: `${receipt.reused ? "Already here" : "Imported"}: version ${receipt.version} (${receipt.versionId}) of ${receipt.artifactId}\n${receipt.url ?? ""}\n`
2284
+ };
2285
+ }
2286
+ });
2382
2287
  /** `mostra add <package…>`. */
2383
2288
  const addCommand = defineCommand({
2384
2289
  path: ["add"],
@@ -3386,28 +3291,11 @@ function daemonInstance(options) {
3386
3291
  }
3387
3292
  /** The bundled reference (`mostra docs`), read as the MCP server's docs. */
3388
3293
  function bundledDocs() {
3389
- let topics;
3390
- const all = () => {
3391
- topics ??= docsIndex();
3392
- return topics;
3393
- };
3394
- const cache = /* @__PURE__ */ new Map();
3395
- return {
3396
- topics: () => all().map((topic) => ({
3397
- topic: topic.topic,
3398
- title: topic.title,
3399
- url: topic.url
3400
- })),
3401
- read(topic) {
3402
- const cached = cache.get(topic);
3403
- if (cached !== void 0) return cached;
3404
- const found = all().find((entry) => entry.topic === topic);
3405
- if (found === void 0) return void 0;
3406
- const markdown = topicMarkdown(found, skillDir(), MCP_GUIDE_LINKS);
3407
- cache.set(topic, markdown);
3408
- return markdown;
3409
- }
3410
- };
3294
+ return fileDocs({
3295
+ referenceDir: referenceDir(),
3296
+ skillDir: skillDir(),
3297
+ links: MCP_GUIDE_LINKS
3298
+ });
3411
3299
  }
3412
3300
  /** The daemon instance, with the runtime's install started at once (D164 item 7). */
3413
3301
  function startInstance(options) {
@@ -3666,12 +3554,193 @@ const mcpCommand = defineCommand({
3666
3554
  }
3667
3555
  });
3668
3556
  //#endregion
3557
+ //#region src/commands/remote.ts
3558
+ /**
3559
+ * `mostra login` and `mostra logout` (INTERFACES §18.7, D165 items 2, 15): this home signs in to a
3560
+ * remote server by the OAuth device authorization grant, so `mostra share --cloud` can host its
3561
+ * artifacts there, and signs out again. The instance keeps the refresh token in the home,
3562
+ * owner-only; signing out keeps its instance link, so the artifacts it shared stay its own at the
3563
+ * next sign-in, unless `--forget`. With `--key-file`, a machine links with a key the server's
3564
+ * operator issued instead (`remote/link`, D167). Clients of `remote/login`, `remote/login.wait`,
3565
+ * `remote/link` and `remote/logout`.
3566
+ */
3567
+ /** How long `mostra login` waits for the person to approve, in all (the code lives 10 minutes). */
3568
+ const LOGIN_WAIT_MS = 6e5;
3569
+ /** Each wait asks the instance for this long, so a slow approval never meets a request timeout. */
3570
+ const LOGIN_STEP_MS = 3e4;
3571
+ /** `mostra login [<server>] [--default]`. */
3572
+ const loginCommand = defineCommand({
3573
+ path: ["login"],
3574
+ summary: "Sign this machine's Mostra in to a remote server, so mostra share --cloud can host pages there.",
3575
+ args: [{
3576
+ name: "server",
3577
+ summary: "The server's address, such as https://api.example.com. Default: the server signed in to last.",
3578
+ optional: true
3579
+ }],
3580
+ flags: [{
3581
+ name: "default",
3582
+ kind: "boolean",
3583
+ summary: "Make this machine the account's default, the one chat apps create pages on. Default: the first machine linked."
3584
+ }, {
3585
+ name: "key-file",
3586
+ kind: "string",
3587
+ summary: "Link with a key the server's operator issued for an account, read from this file, instead of a person's sign-in (for an always-on machine)."
3588
+ }],
3589
+ output: {
3590
+ type: "RemoteLoginWaitResult",
3591
+ topic: "cli"
3592
+ },
3593
+ exits: [EXIT.failure, EXIT.environment],
3594
+ example: "login https://api.example.com",
3595
+ async run(context) {
3596
+ const server = context.args["server"];
3597
+ const keyFile = flag(context, "key-file");
3598
+ if (keyFile !== void 0) {
3599
+ if (typeof server !== "string") throw usage("Name the server the key is for: mostra login <server> --key-file <file>.");
3600
+ let key;
3601
+ try {
3602
+ key = readFileSync(resolve(context.cwd, keyFile), "utf8").trim();
3603
+ } catch (error) {
3604
+ throw usage(`--key-file ${keyFile} can't be read (${error.code ?? "error"}).`);
3605
+ }
3606
+ const linked = await context.call(remoteLinkMethod, {
3607
+ server: server.replace(/\/+$/, ""),
3608
+ key,
3609
+ ...context.flags["default"] === true ? { default: true } : {}
3610
+ });
3611
+ return {
3612
+ result: {
3613
+ status: "signed-in",
3614
+ ...linked
3615
+ },
3616
+ human: `Linked to ${linked.server} for ${linked.account.name ?? linked.account.id} with the operator's key. This machine is ${linked.instanceId}.\n`
3617
+ };
3618
+ }
3619
+ const started = await context.call(remoteLoginMethod, {
3620
+ ...typeof server === "string" ? { server: server.replace(/\/+$/, "") } : {},
3621
+ ...context.flags["default"] === true ? { default: true } : {}
3622
+ });
3623
+ const where = started.verificationUriComplete ?? started.verificationUri;
3624
+ context.emit({
3625
+ kind: "code",
3626
+ ...started
3627
+ }, `Open ${where} and check that it shows the code ${started.userCode}, then approve.\nWaiting for you to approve…`);
3628
+ const deadline = Date.now() + LOGIN_WAIT_MS;
3629
+ for (;;) {
3630
+ const waited = await context.call(remoteLoginWaitMethod, {
3631
+ loginId: started.loginId,
3632
+ timeoutMs: Math.max(0, Math.min(LOGIN_STEP_MS, deadline - Date.now()))
3633
+ });
3634
+ if (waited.status === "signed-in") return {
3635
+ result: waited,
3636
+ human: `Signed in to ${waited.server} as ${waited.account.name ?? waited.account.id}. This machine is ${waited.instanceId}.\n`
3637
+ };
3638
+ if (Date.now() >= deadline) return {
3639
+ result: waited,
3640
+ human: "The code wasn't approved in time. Run mostra login again for a new one.\n",
3641
+ exit: EXIT.timeout
3642
+ };
3643
+ }
3644
+ }
3645
+ });
3646
+ /** `mostra logout [<server>] [--forget]`. */
3647
+ const logoutCommand = defineCommand({
3648
+ path: ["logout"],
3649
+ summary: "Sign this machine's Mostra out of a remote server; its hosted pages keep working, and their answers wait for the next sign-in.",
3650
+ args: [{
3651
+ name: "server",
3652
+ summary: "The server's address. Default: the server signed in to last.",
3653
+ optional: true
3654
+ }],
3655
+ flags: [{
3656
+ name: "forget",
3657
+ kind: "boolean",
3658
+ summary: "Also forget this machine's link to the server: the pages it shared there are no longer its own."
3659
+ }],
3660
+ output: {
3661
+ type: "RemoteLogoutResult",
3662
+ topic: "cli"
3663
+ },
3664
+ exits: [EXIT.failure, EXIT.environment],
3665
+ example: "logout",
3666
+ async run(context) {
3667
+ const server = context.args["server"];
3668
+ const result = await context.call(remoteLogoutMethod, {
3669
+ ...typeof server === "string" ? { server: server.replace(/\/+$/, "") } : {},
3670
+ ...context.flags["forget"] === true ? { forget: true } : {}
3671
+ });
3672
+ return {
3673
+ result,
3674
+ human: result.servers.length === 0 ? "This machine wasn't signed in to a server.\n" : `Signed out of ${result.servers.join(", ")}.\n`
3675
+ };
3676
+ }
3677
+ });
3678
+ /** `mostra pause <artifact> [--reason <text>]` (D165 item 14). */
3679
+ const pauseCommand = defineCommand({
3680
+ path: ["pause"],
3681
+ summary: "Pause an artifact: its pages stay viewable and its links valid, but it takes no answers and runs no actions until resumed.",
3682
+ args: [{
3683
+ name: "artifact",
3684
+ summary: "The artifact: its source path or its ID."
3685
+ }],
3686
+ flags: [{
3687
+ name: "reason",
3688
+ kind: "string",
3689
+ summary: "Why, shown to the page's viewers beside the paused notice."
3690
+ }],
3691
+ output: {
3692
+ type: "ArtifactPauseResult",
3693
+ topic: "cli"
3694
+ },
3695
+ exits: [EXIT.failure, EXIT.environment],
3696
+ example: "pause ./survey --reason \"Closed for review until Monday\"",
3697
+ async run(context) {
3698
+ const reason = flag(context, "reason");
3699
+ const result = await context.call(artifactPauseMethod, {
3700
+ artifact: artifactRef(arg(context, "artifact"), context.cwd),
3701
+ paused: true,
3702
+ ...reason !== void 0 ? { reason } : {}
3703
+ });
3704
+ return {
3705
+ result,
3706
+ human: result.by === "operator" ? "Paused. The server's operator paused it too, and only the operator resumes that.\n" : "Paused. Pages stay viewable; answers and actions wait until mostra resume.\n"
3707
+ };
3708
+ }
3709
+ });
3710
+ /** `mostra resume <artifact>` (D165 item 14). */
3711
+ const resumeCommand = defineCommand({
3712
+ path: ["resume"],
3713
+ summary: "Resume a paused artifact: it takes answers and runs actions again.",
3714
+ args: [{
3715
+ name: "artifact",
3716
+ summary: "The artifact: its source path or its ID."
3717
+ }],
3718
+ output: {
3719
+ type: "ArtifactPauseResult",
3720
+ topic: "cli"
3721
+ },
3722
+ exits: [EXIT.failure, EXIT.environment],
3723
+ example: "resume ./survey",
3724
+ async run(context) {
3725
+ const result = await context.call(artifactPauseMethod, {
3726
+ artifact: artifactRef(arg(context, "artifact"), context.cwd),
3727
+ paused: false
3728
+ });
3729
+ return {
3730
+ result,
3731
+ human: result.paused ? "Still paused: the server's operator paused it, and only the operator resumes that.\n" : "Resumed. The artifact takes answers and runs actions again.\n",
3732
+ ...result.paused ? { exit: EXIT.failure } : {}
3733
+ };
3734
+ }
3735
+ });
3736
+ //#endregion
3669
3737
  //#region src/commands/sharing.ts
3670
3738
  /**
3671
3739
  * `mostra share`: an artifact opened to people beyond this machine through a tunnel the daemon
3672
3740
  * runs (D47, D158): `--tailnet` (Tailscale Serve, inside your tailnet, with each person's
3673
3741
  * identity) or `--public` (a Cloudflare quick tunnel by default, or Tailscale Funnel with `--via
3674
- * funnel`), whose link expires (1 hour by default, 7 days at most). The share lives in the
3742
+ * funnel`), whose link expires (1 hour by default, 7 days at most); or `--cloud` (D165 item 15),
3743
+ * hosted on a remote server this home signed in to, so the link works while this machine sleeps. The share lives in the
3675
3744
  * daemon, so the command returns at once with the link; `share stop` ends it and `share list`
3676
3745
  * shows what is shared. A client of `share/start`, `share/stop` and `share/list`.
3677
3746
  */
@@ -3680,7 +3749,8 @@ const SHARE_ID = /^shr_[0-9A-HJKMNP-TV-Z]{26}$/;
3680
3749
  const THROUGH = {
3681
3750
  tailnet: "Tailscale Serve, inside your tailnet",
3682
3751
  funnel: "Tailscale Funnel, public",
3683
- cloudflare: "a Cloudflare quick tunnel, public"
3752
+ cloudflare: "a Cloudflare quick tunnel, public",
3753
+ remote: "a remote server, hosted"
3684
3754
  };
3685
3755
  /**
3686
3756
  * What a tailnet viewer's device needs, found on a real tailnet in WP-13: the tailnet's access
@@ -3701,12 +3771,21 @@ function line(share) {
3701
3771
  /** `mostra share <artifact> --tailnet | --public`. */
3702
3772
  const shareCommand = defineCommand({
3703
3773
  path: ["share"],
3704
- summary: "Open an artifact to people beyond this machine: inside your tailnet, or publicly with a link that expires.",
3774
+ summary: "Open an artifact to people beyond this machine: inside your tailnet, publicly with a link that expires, or hosted on a server.",
3705
3775
  args: [{
3706
3776
  name: "artifact",
3707
3777
  summary: "The artifact: its source path or its ID."
3778
+ }, {
3779
+ name: "server",
3780
+ summary: "With --cloud: the server's address. Default: the server signed in to last.",
3781
+ optional: true
3708
3782
  }],
3709
3783
  flags: [
3784
+ {
3785
+ name: "cloud",
3786
+ kind: "boolean",
3787
+ summary: "Host it on a remote server you signed in to with mostra login: the link keeps working while this machine sleeps."
3788
+ },
3710
3789
  {
3711
3790
  name: "tailnet",
3712
3791
  kind: "boolean",
@@ -3761,15 +3840,22 @@ const shareCommand = defineCommand({
3761
3840
  topic: "cli"
3762
3841
  },
3763
3842
  exits: [EXIT.failure, EXIT.environment],
3764
- example: "share ./sidebar-review --public --ttl 2h",
3843
+ example: "share ./sidebar-review --cloud",
3765
3844
  async run(context) {
3766
3845
  const artifact = artifactRef(arg(context, "artifact"), context.cwd);
3767
3846
  const tailnet = context.flags["tailnet"] === true;
3768
3847
  const publicly = context.flags["public"] === true;
3769
- if (tailnet === publicly) throw usage("Give --tailnet or --public.");
3848
+ const cloud = context.flags["cloud"] === true;
3849
+ if ([
3850
+ tailnet,
3851
+ publicly,
3852
+ cloud
3853
+ ].filter(Boolean).length !== 1) throw usage("Give one of --tailnet, --public or --cloud.");
3770
3854
  const viaFlag = flag(context, "via");
3771
3855
  if (viaFlag !== void 0 && !publicly) throw usage("--via chooses a public tunnel: add --public.");
3772
- const via = tailnet ? "tailnet" : viaFlag === "funnel" ? "funnel" : "cloudflare";
3856
+ const server = context.args["server"];
3857
+ if (server !== void 0 && !cloud) throw usage("A server names where --cloud hosts it.");
3858
+ const via = cloud ? "remote" : tailnet ? "tailnet" : viaFlag === "funnel" ? "funnel" : "cloudflare";
3773
3859
  const ttl = flag(context, "ttl");
3774
3860
  const scopes = context.flags["scope"];
3775
3861
  const viewerRef = flag(context, "viewer");
@@ -3779,6 +3865,7 @@ const shareCommand = defineCommand({
3779
3865
  const share = await context.call(shareStartMethod, {
3780
3866
  artifact,
3781
3867
  via,
3868
+ ...typeof server === "string" ? { server: server.replace(/\/+$/, "") } : {},
3782
3869
  ...ttl !== void 0 ? { ttl } : {},
3783
3870
  ...scopes !== void 0 ? { scopes } : {},
3784
3871
  ...viewerRef !== void 0 ? { viewer: {
@@ -3877,10 +3964,25 @@ function wantsBrowser(context) {
3877
3964
  if (context.flags["browser"] === true) return true;
3878
3965
  return context.tty.stdout && !context.json && hasDisplay(context.env);
3879
3966
  }
3880
- /** The link, opened in a browser when wanted. */
3967
+ /**
3968
+ * Why no browser was opened, for stderr (#114): an agent's shell isn't a terminal, so without a
3969
+ * word it would tell its person the page is open when it isn't.
3970
+ */
3971
+ function notOpenedReason(context, tried) {
3972
+ if (context.flags["no-browser"] === true) return void 0;
3973
+ if (tried) return "No browser opened: none could be started here. Give the person the link.";
3974
+ if (!hasDisplay(context.env)) return "No browser opened: this session has no display. Give the person the link.";
3975
+ return "No browser opened: this isn't a terminal. Pass --browser to open it here, or give the person the link.";
3976
+ }
3977
+ /** The link, opened in a browser when wanted; why not on stderr when it wasn't. */
3881
3978
  async function show(context, link) {
3882
3979
  let opened = false;
3883
- if (wantsBrowser(context)) opened = await openInBrowser((await context.call(viewLaunchMethod, { tokenId: link.tokenId })).url, context.env);
3980
+ const tried = wantsBrowser(context);
3981
+ if (tried) opened = await openInBrowser((await context.call(viewLaunchMethod, { tokenId: link.tokenId })).url, context.env);
3982
+ if (!opened) {
3983
+ const reason = notOpenedReason(context, tried);
3984
+ if (reason !== void 0) context.log(reason);
3985
+ }
3884
3986
  return {
3885
3987
  result: {
3886
3988
  ...link,
@@ -4015,6 +4117,10 @@ const COMMANDS = [
4015
4117
  shareCommand,
4016
4118
  shareStopCommand,
4017
4119
  shareListCommand,
4120
+ loginCommand,
4121
+ logoutCommand,
4122
+ pauseCommand,
4123
+ resumeCommand,
4018
4124
  waitCommand,
4019
4125
  resultsCommand,
4020
4126
  stateGetCommand,
@@ -4022,6 +4128,8 @@ const COMMANDS = [
4022
4128
  statePatchCommand,
4023
4129
  pushCommand,
4024
4130
  addCommand,
4131
+ exportCommand,
4132
+ runCommand,
4025
4133
  secretSetCommand,
4026
4134
  secretListCommand,
4027
4135
  secretRmCommand,
@@ -4480,4 +4588,4 @@ async function runRuntime(io, args, stdio) {
4480
4588
  //#endregion
4481
4589
  export { COMMANDS as a, referenceMarkdown as i, commandDefinition as n, commandHelp as r, run as t };
4482
4590
 
4483
- //# sourceMappingURL=run-DdYT3iHQ.js.map
4591
+ //# sourceMappingURL=run-BxYL-DaX.js.map