@mostra/cli 0.6.2 → 0.8.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 (50) hide show
  1. package/dist/bin.js +1 -1
  2. package/dist/{flush-CFJkvi2R.js → flush-CBN3AU9X.js} +90 -30
  3. package/dist/flush-CBN3AU9X.js.map +1 -0
  4. package/dist/index.d.ts +1 -1
  5. package/dist/index.d.ts.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/reference/cli.md +108 -2
  8. package/dist/reference/diagnostics.json +72 -0
  9. package/dist/reference/errors/MOSTRA_HYGIENE_FRAME_SESSION.md +23 -0
  10. package/dist/reference/errors/MOSTRA_SHARE_NOT_ENABLED.md +23 -0
  11. package/dist/reference/errors/MOSTRA_SHARE_NOT_FOUND.md +23 -0
  12. package/dist/reference/errors/MOSTRA_SHARE_PORTS_EXHAUSTED.md +23 -0
  13. package/dist/reference/errors/MOSTRA_SHARE_TOOL_MISSING.md +23 -0
  14. package/dist/reference/errors/MOSTRA_SHARE_TOOL_NOT_READY.md +23 -0
  15. package/dist/reference/errors/MOSTRA_SHARE_TTL_INVALID.md +23 -0
  16. package/dist/reference/errors/MOSTRA_SHARE_TUNNEL_FAILED.md +23 -0
  17. package/dist/run-3WlZ2Jos.js +1 -0
  18. package/dist/{run-3QZacDLc.js → run-CuMkFuH7.js} +320 -12
  19. package/dist/run-CuMkFuH7.js.map +1 -0
  20. package/dist/skill/SKILL.md +117 -0
  21. package/dist/skill/assets/examples/dashboard/index.tsx +161 -0
  22. package/dist/skill/assets/examples/dashboard/live.ts +25 -0
  23. package/dist/skill/assets/examples/dashboard/styles.css +125 -0
  24. package/dist/skill/assets/examples/decision/index.tsx +95 -0
  25. package/dist/skill/assets/examples/decision/styles.css +125 -0
  26. package/dist/skill/assets/examples/inbox/actions.ts +23 -0
  27. package/dist/skill/assets/examples/inbox/index.tsx +109 -0
  28. package/dist/skill/assets/examples/inbox/styles.css +125 -0
  29. package/dist/skill/assets/studio.css +125 -0
  30. package/dist/skill/references/answers.md +181 -0
  31. package/dist/skill/references/design.md +154 -0
  32. package/dist/skill/references/libraries.md +167 -0
  33. package/dist/skill/references/long-lived.md +148 -0
  34. package/dist/skill/references/page.md +131 -0
  35. package/dist/skill/references/server.md +146 -0
  36. package/dist/skill/references/sharing.md +72 -0
  37. package/dist/skill/references/verify.md +71 -0
  38. package/dist/telemetry/flush-main.js +1 -1
  39. package/package.json +6 -5
  40. package/src/command.ts +1 -1
  41. package/src/commands/admin.ts +5 -4
  42. package/src/commands/index.ts +6 -2
  43. package/src/commands/sharing.ts +209 -0
  44. package/src/detached.ts +3 -0
  45. package/src/docs.ts +133 -7
  46. package/src/telemetry/index.ts +3 -3
  47. package/src/telemetry/store.ts +95 -30
  48. package/dist/flush-CFJkvi2R.js.map +0 -1
  49. package/dist/run-3QZacDLc.js.map +0 -1
  50. package/dist/run-K42fyQo0.js +0 -1
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_SHARE_NOT_FOUND
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_SHARE_NOT_FOUND
10
+
11
+ Unknown share. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ No share of this home has the ID given, or the artifact has no share.
16
+
17
+ ## How to fix it
18
+
19
+ Use a share ID from `mostra share list`.
20
+
21
+ ## Hint
22
+
23
+ List the home's shares with `mostra share list` and name one of them.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_SHARE_PORTS_EXHAUSTED
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_SHARE_PORTS_EXHAUSTED
10
+
11
+ No tunnel port free. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ Tailscale Funnel listens only on ports 443, 8443 and 10000 of a device: Mostra gives 443 to the shell and the other two to one artifact each, so at most two artifacts are shared through Funnel at once. A port is also unavailable when this device's own Serve or Funnel configuration already uses it.
16
+
17
+ ## How to fix it
18
+
19
+ Stop one of the Funnel shares, free the port in Tailscale's own configuration, or share this artifact through a Cloudflare quick tunnel.
20
+
21
+ ## Hint
22
+
23
+ Stop a share you no longer need (`mostra share list`, then `mostra share stop <share>`), or share through a Cloudflare quick tunnel.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_SHARE_TOOL_MISSING
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_SHARE_TOOL_MISSING
10
+
11
+ Sharing tool not installed. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ A share drives a tunnel tool installed on this machine: `tailscale` for tailnet and Funnel shares, `cloudflared` for Cloudflare quick tunnels. Mostra never bundles or downloads them; it found none where it looks (`PATH`, the tool's usual install locations, or `MOSTRA_TAILSCALE` and `MOSTRA_CLOUDFLARED`). The message says how to install it on this system.
16
+
17
+ ## How to fix it
18
+
19
+ Install the tool (Tailscale from tailscale.com/download, `cloudflared` from Cloudflare's downloads or a package manager), or point `MOSTRA_TAILSCALE` or `MOSTRA_CLOUDFLARED` at it, then share again.
20
+
21
+ ## Hint
22
+
23
+ Install the tool the message names, then run the share again.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_SHARE_TOOL_NOT_READY
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_SHARE_TOOL_NOT_READY
10
+
11
+ Sharing tool not ready. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The tunnel tool is installed but can't serve yet: Tailscale isn't running or isn't signed in to a tailnet, or `cloudflared` exited before it opened a tunnel. The message quotes what the tool reported.
16
+
17
+ ## How to fix it
18
+
19
+ Start Tailscale and sign in (`tailscale up`), or check that `cloudflared` runs and this machine reaches Cloudflare, then share again.
20
+
21
+ ## Hint
22
+
23
+ Do what the message says to the tool, then run the share again.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_SHARE_TTL_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_SHARE_TTL_INVALID
10
+
11
+ Share lifetime refused. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ A public share (Funnel or Cloudflare) admits anyone holding its link, so it lasts 1 hour unless `ttl` says otherwise, and at most 7 days. Tailnet shares have no limit.
16
+
17
+ ## How to fix it
18
+
19
+ Use a `ttl` of 7 days or less, and share again when it ends, or share inside the tailnet.
20
+
21
+ ## Hint
22
+
23
+ Give a public share a lifetime of at most 7 days, such as `--ttl 24h`.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_SHARE_TUNNEL_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_SHARE_TUNNEL_FAILED
10
+
11
+ Tunnel failed. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The tunnel tool started but didn't serve within its time, or stopped: the message quotes what it reported. A share whose tunnel ends and can't be set up again stops, and `mostra share list` shows why; a Cloudflare quick tunnel can't keep its address, so its share ends with it.
16
+
17
+ ## How to fix it
18
+
19
+ Share again for a new link. A tailnet or Funnel share keeps its address across restarts of its tunnel; a Cloudflare quick tunnel gets a new one each time.
20
+
21
+ ## Hint
22
+
23
+ Run the share again; if it fails the same way, check the tool's message and this machine's network.
@@ -0,0 +1 @@
1
+ export { t as run } from "./run-CuMkFuH7.js";
@@ -1,9 +1,9 @@
1
- import { a as detachedEnvironment, c as durationBucket, d as buildEndpoint, f as decide, g as packageRoot, h as fromSource, i as detachedDirectory, l as minute, m as cliVersion, n as startFlusher, o as TelemetryEvent, p as truthy, r as TelemetryStore, s as catalogCodes, u as detectHarness } from "./flush-CFJkvi2R.js";
1
+ import { a as detachedEnvironment, c as durationBucket, d as buildEndpoint, f as decide, g as packageRoot, h as fromSource, i as detachedDirectory, l as minute, m as cliVersion, n as startFlusher, o as TelemetryEvent, p as truthy, r as TelemetryStore, s as catalogCodes, u as detectHarness } from "./flush-CBN3AU9X.js";
2
2
  import { n as exitCodeFor, t as EXIT } from "./exit-CBIf8nAU.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 { 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, stateGetMethod, statePatchMethod, viewDefaultMethod, viewLaunchMethod, viewRevokeMethod, viewRotateMethod, viewUrlMethod, waitMethod } from "@mostra/protocol";
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";
7
7
  import { checkBrowser, checkFiles, connectControl, enclosingBundle, readBundle, readSetup, resolveRuntime } from "@mostra/sdk";
8
8
  import { homedir, tmpdir } from "node:os";
9
9
  import { parseArgs } from "node:util";
@@ -23,14 +23,20 @@ function commandName(command) {
23
23
  /**
24
24
  * `mostra docs` (D140 item 17): the reference that ships with the CLI, by stable slug. The
25
25
  * diagnostic pages are keyed by code (`mostra docs MOSTRA_DEP_MISSING`, as hints say), beside the
26
- * CLI reference and the telemetry page. This index is the one source WP-15's `docs_search` and
27
- * WP-26's site read.
26
+ * CLI reference and the telemetry page. The Agent Skill (`skills/mostra/`, WP-14) is in it too, as
27
+ * `guide` and `guide/<name>`, so an agent whose harness has no Skill reads the same text through
28
+ * the CLI. This index is the one source WP-15's `docs_search` and WP-26's site read.
28
29
  */
29
30
  /** Where the reference is: bundled in the build (`dist/reference`), or the repository's. */
30
31
  function referenceDir() {
31
32
  const bundled = join(packageRoot(), "dist", "reference");
32
33
  return !fromSource() && existsSync(bundled) ? bundled : join(packageRoot(), "..", "..", "docs", "reference");
33
34
  }
35
+ /** Where the Agent Skill is: bundled in the build (`dist/skill`), or the repository's. */
36
+ function skillDir() {
37
+ const bundled = join(packageRoot(), "dist", "skill");
38
+ return !fromSource() && existsSync(bundled) ? bundled : join(packageRoot(), "..", "..", "skills", "mostra");
39
+ }
34
40
  function titleOf(file) {
35
41
  const first = readFileSync(file, "utf8").split("\n").find((line) => line.startsWith("# "));
36
42
  return first ? first.slice(2).trim() : "";
@@ -59,11 +65,115 @@ function docsIndex(dir = referenceDir()) {
59
65
  file
60
66
  };
61
67
  });
62
- return [...pages, ...errors];
68
+ return [
69
+ ...pages,
70
+ ...guideTopics(skillDir(), base),
71
+ ...errors
72
+ ];
73
+ }
74
+ const byName = (a, b) => a.name < b.name ? -1 : 1;
75
+ /** Every file below `root`'s `prefix`, relative to `root`, sorted. */
76
+ function filesBelow(root, prefix) {
77
+ return readdirSync(join(root, prefix), { withFileTypes: true }).sort(byName).flatMap((entry) => {
78
+ const path = `${prefix}/${entry.name}`;
79
+ return entry.isDirectory() ? filesBelow(root, path) : [path];
80
+ });
81
+ }
82
+ /**
83
+ * The Skill as topics: `guide` (its SKILL.md), `guide/<name>` for each reference,
84
+ * `guide/<file>` for each asset (the baseline stylesheet), and `guide/examples/<name>` for each
85
+ * example, every file of it.
86
+ */
87
+ function guideTopics(dir, base) {
88
+ const skill = join(dir, "SKILL.md");
89
+ if (!existsSync(skill)) return [];
90
+ const topics = [{
91
+ topic: "guide",
92
+ title: "Using Mostra",
93
+ url: `${base}/guide`,
94
+ file: skill
95
+ }];
96
+ const references = join(dir, "references");
97
+ if (existsSync(references)) for (const name of readdirSync(references).filter((entry) => entry.endsWith(".md")).sort()) {
98
+ const file = join(references, name);
99
+ const slug = name.slice(0, -3);
100
+ topics.push({
101
+ topic: `guide/${slug}`,
102
+ title: titleOf(file),
103
+ url: `${base}/guide/${slug}`,
104
+ file
105
+ });
106
+ }
107
+ const assets = join(dir, "assets");
108
+ if (!existsSync(assets)) return topics;
109
+ for (const entry of readdirSync(assets, { withFileTypes: true }).sort(byName)) {
110
+ if (!entry.isFile()) continue;
111
+ topics.push({
112
+ topic: `guide/${entry.name}`,
113
+ title: entry.name,
114
+ url: `${base}/guide/${entry.name}`,
115
+ file: join(assets, entry.name),
116
+ files: [entry.name]
117
+ });
118
+ }
119
+ const examples = join(assets, "examples");
120
+ if (!existsSync(examples)) return topics;
121
+ for (const entry of readdirSync(examples, { withFileTypes: true }).sort(byName)) {
122
+ if (!entry.isDirectory()) continue;
123
+ const files = filesBelow(assets, `examples/${entry.name}`);
124
+ if (files.length === 0) continue;
125
+ topics.push({
126
+ topic: `guide/examples/${entry.name}`,
127
+ title: `Example: ${entry.name}`,
128
+ url: `${base}/guide/examples/${entry.name}`,
129
+ file: join(assets, files[0]),
130
+ files
131
+ });
132
+ }
133
+ return topics;
134
+ }
135
+ const FENCE_LANGUAGES = {
136
+ ".css": "css",
137
+ ".json": "json",
138
+ ".md": "md",
139
+ ".mdx": "mdx",
140
+ ".ts": "ts",
141
+ ".tsx": "tsx"
142
+ };
143
+ /** How the guide's relative links read through the CLI, before each of its pages. */
144
+ 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>`.";
145
+ /**
146
+ * A topic's Markdown. A guide page loses its frontmatter and says how its links read through the
147
+ * CLI; a guide topic made of files shows each one as code under its path.
148
+ */
149
+ function topicMarkdown(topic, dir = skillDir()) {
150
+ if (topic.files !== void 0) {
151
+ const parts = topic.files.map((path) => {
152
+ const text = readFileSync(join(dir, "assets", path), "utf8");
153
+ const fence = text.includes("```") ? "````" : "```";
154
+ const body = text.endsWith("\n") ? text : `${text}\n`;
155
+ return `## \`${path}\`\n\n${fence}${FENCE_LANGUAGES[extname(path)] ?? ""}\n${body}${fence}\n`;
156
+ });
157
+ return [
158
+ `# ${topic.title}`,
159
+ "",
160
+ GUIDE_LINKS,
161
+ "",
162
+ ...parts
163
+ ].join("\n");
164
+ }
165
+ const text = readFileSync(topic.file, "utf8");
166
+ if (topic.topic !== "guide" && !topic.topic.startsWith("guide/")) return text;
167
+ return [
168
+ GUIDE_LINKS,
169
+ "",
170
+ text.replace(/^---\n[\s\S]*?\n---\n+/, "")
171
+ ].join("\n");
63
172
  }
64
173
  /** The index as Markdown: what `mostra docs` prints without a topic. */
65
174
  function indexMarkdown(topics) {
66
- const pages = topics.filter((topic) => !topic.topic.startsWith("MOSTRA_"));
175
+ const pages = topics.filter((topic) => !topic.topic.startsWith("MOSTRA_") && !topic.topic.startsWith("guide"));
176
+ const guide = topics.filter((topic) => topic.topic === "guide" || topic.topic.startsWith("guide/"));
67
177
  const codes = topics.filter((topic) => topic.topic.startsWith("MOSTRA_"));
68
178
  return [
69
179
  "# Mostra reference",
@@ -72,6 +182,12 @@ function indexMarkdown(topics) {
72
182
  "",
73
183
  ...pages.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
74
184
  "",
185
+ ...guide.length > 0 ? [
186
+ "## Writing artifacts",
187
+ "",
188
+ ...guide.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
189
+ ""
190
+ ] : [],
75
191
  "## Diagnostic codes",
76
192
  "",
77
193
  ...codes.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
@@ -2116,7 +2232,7 @@ async function alwaysOnCheck(context) {
2116
2232
  /** `mostra docs [topic]`. */
2117
2233
  const docsCommand = defineCommand({
2118
2234
  path: ["docs"],
2119
- summary: "Print Mostra's reference: the CLI, telemetry, and every diagnostic code's page.",
2235
+ summary: "Print Mostra's reference: the guide to writing artifacts, the CLI, telemetry, and every diagnostic code's page.",
2120
2236
  args: [{
2121
2237
  name: "topic",
2122
2238
  summary: "A topic or a diagnostic code. Default: the index.",
@@ -2151,7 +2267,7 @@ const docsCommand = defineCommand({
2151
2267
  }
2152
2268
  const found = topics.find((topic) => topic.topic === wanted || topic.topic === wanted.toUpperCase());
2153
2269
  if (!found) throw usage(`No topic "${wanted}". The nearest: ${nearestTopics(wanted, topics).join(", ")}. Run "mostra docs" for the index.`);
2154
- const markdown = readFileSync(found.file, "utf8");
2270
+ const markdown = topicMarkdown(found);
2155
2271
  return {
2156
2272
  result: {
2157
2273
  topic: found.topic,
@@ -2501,7 +2617,7 @@ const addCommand = defineCommand({
2501
2617
  * envelopes with `--json`, lines otherwise. Viewers never reach a preview; it isn't a version.
2502
2618
  */
2503
2619
  /** One event's line without `--json`. */
2504
- function line(event) {
2620
+ function line$1(event) {
2505
2621
  const files = event.files && event.files.length > 0 ? `: ${event.files.join(", ")}` : "";
2506
2622
  switch (event.kind) {
2507
2623
  case "built": return `Updated${files}\n`;
@@ -2537,7 +2653,7 @@ const devCommand = defineCommand({
2537
2653
  const early = [];
2538
2654
  const show = (event) => {
2539
2655
  if (event.kind === "diagnostics") for (const diagnostic of event.diagnostics ?? []) context.warn(diagnostic);
2540
- context.emit(event, line(event));
2656
+ context.emit(event, line$1(event));
2541
2657
  };
2542
2658
  connection?.onNotification(DEV_NOTIFY, (params) => {
2543
2659
  const event = params;
@@ -2911,6 +3027,195 @@ const statePatchCommand = defineCommand({
2911
3027
  }
2912
3028
  });
2913
3029
  //#endregion
3030
+ //#region src/commands/sharing.ts
3031
+ /**
3032
+ * `mostra share`: an artifact opened to people beyond this machine through a tunnel the daemon
3033
+ * runs (D47, D158): `--tailnet` (Tailscale Serve, inside your tailnet, with each person's
3034
+ * identity) or `--public` (a Cloudflare quick tunnel by default, or Tailscale Funnel with `--via
3035
+ * funnel`), whose link expires (1 hour by default, 7 days at most). The share lives in the
3036
+ * daemon, so the command returns at once with the link; `share stop` ends it and `share list`
3037
+ * shows what is shared. A client of `share/start`, `share/stop` and `share/list`.
3038
+ */
3039
+ const SHARE_ID = /^shr_[0-9A-HJKMNP-TV-Z]{26}$/;
3040
+ /** How each tunnel is named in human output. */
3041
+ const THROUGH = {
3042
+ tailnet: "Tailscale Serve, inside your tailnet",
3043
+ funnel: "Tailscale Funnel, public",
3044
+ cloudflare: "a Cloudflare quick tunnel, public"
3045
+ };
3046
+ /**
3047
+ * What a tailnet viewer's device needs, found on a real tailnet in WP-13: the tailnet's access
3048
+ * policy must let them reach the share's two ports of this device, and their browser's traffic
3049
+ * must go through Tailscale (no private or secure DNS of its own, no split tunneling that leaves
3050
+ * the browser out).
3051
+ */
3052
+ function tailnetReach(share) {
3053
+ const port = (origin) => origin === void 0 ? void 0 : new URL(origin).port || "443";
3054
+ const ports = [port(share.url), port(share.artifactOrigin)].filter((value) => value !== void 0);
3055
+ return `Viewers need this device's port${ports.length === 1 ? "" : "s"} ${ports.join(" and ")} allowed by the tailnet's access policy, and their browser's traffic sent through Tailscale.\n`;
3056
+ }
3057
+ /** One share as a line of human output. */
3058
+ function line(share) {
3059
+ const until = share.state === "stopped" ? `stopped${share.stopReason ? ` (${share.stopReason})` : ""}` : share.expiresAt ? `until ${share.expiresAt}` : "no expiry";
3060
+ return `${share.shareId} ${share.via} ${share.hostname} ${until}`;
3061
+ }
3062
+ /** `mostra share <artifact> --tailnet | --public`. */
3063
+ const shareCommand = defineCommand({
3064
+ path: ["share"],
3065
+ summary: "Open an artifact to people beyond this machine: inside your tailnet, or publicly with a link that expires.",
3066
+ args: [{
3067
+ name: "artifact",
3068
+ summary: "The artifact: its source path or its ID."
3069
+ }],
3070
+ flags: [
3071
+ {
3072
+ name: "tailnet",
3073
+ kind: "boolean",
3074
+ summary: "Share inside your tailnet through Tailscale Serve; each viewer is their tailnet identity."
3075
+ },
3076
+ {
3077
+ name: "public",
3078
+ kind: "boolean",
3079
+ summary: "Share publicly: anyone with the link can open it until it expires."
3080
+ },
3081
+ {
3082
+ name: "via",
3083
+ kind: "string",
3084
+ value: "<tunnel>",
3085
+ choices: ["cloudflare", "funnel"],
3086
+ default: "cloudflare",
3087
+ summary: "The public tunnel: a Cloudflare quick tunnel (no account), or Tailscale Funnel (shows your device's tailnet name)."
3088
+ },
3089
+ {
3090
+ name: "ttl",
3091
+ kind: "duration",
3092
+ value: "<d>",
3093
+ summary: "How long the link works, such as 30m or 24h. Public: 1h by default, 7d at most."
3094
+ },
3095
+ {
3096
+ name: "scope",
3097
+ kind: "list",
3098
+ value: "<a,b>",
3099
+ summary: "The link's scopes: view, draft, submit, review, signal, action:*. Default: all."
3100
+ },
3101
+ {
3102
+ name: "viewer",
3103
+ kind: "string",
3104
+ value: "<ref>",
3105
+ summary: "The person the link is for, by your own stable key for them; without it, each link is a viewer of its own."
3106
+ },
3107
+ {
3108
+ name: "viewer-name",
3109
+ kind: "string",
3110
+ value: "<name>",
3111
+ summary: "The display name of --viewer."
3112
+ },
3113
+ {
3114
+ name: "request-id",
3115
+ kind: "string",
3116
+ value: "<id>",
3117
+ summary: "Make a retried share return the same share instead of opening another."
3118
+ }
3119
+ ],
3120
+ output: {
3121
+ type: "ShareStartResult",
3122
+ topic: "cli"
3123
+ },
3124
+ exits: [EXIT.failure, EXIT.environment],
3125
+ example: "share ./sidebar-review --public --ttl 2h",
3126
+ async run(context) {
3127
+ const artifact = artifactRef(arg(context, "artifact"), context.cwd);
3128
+ const tailnet = context.flags["tailnet"] === true;
3129
+ const publicly = context.flags["public"] === true;
3130
+ if (tailnet === publicly) throw usage("Give --tailnet or --public.");
3131
+ const viaFlag = flag(context, "via");
3132
+ if (viaFlag !== void 0 && !publicly) throw usage("--via chooses a public tunnel: add --public.");
3133
+ const via = tailnet ? "tailnet" : viaFlag === "funnel" ? "funnel" : "cloudflare";
3134
+ const ttl = flag(context, "ttl");
3135
+ const scopes = context.flags["scope"];
3136
+ const viewerRef = flag(context, "viewer");
3137
+ const viewerName = flag(context, "viewer-name");
3138
+ const requestId = flag(context, "request-id");
3139
+ if (viewerName !== void 0 && viewerRef === void 0) throw usage("--viewer-name needs --viewer.");
3140
+ const share = await context.call(shareStartMethod, {
3141
+ artifact,
3142
+ via,
3143
+ ...ttl !== void 0 ? { ttl } : {},
3144
+ ...scopes !== void 0 ? { scopes } : {},
3145
+ ...viewerRef !== void 0 ? { viewer: {
3146
+ ref: viewerRef,
3147
+ ...viewerName !== void 0 ? { name: viewerName } : {}
3148
+ } } : {},
3149
+ ...requestId !== void 0 ? { requestId } : {}
3150
+ });
3151
+ context.record({
3152
+ event: "share.done",
3153
+ fields: { kind: via }
3154
+ });
3155
+ const until = share.expiresAt ? `until ${share.expiresAt}` : "until you stop it";
3156
+ return {
3157
+ result: share,
3158
+ human: `${share.url}\nShared through ${THROUGH[via]}, ${until}.\n${via === "tailnet" ? tailnetReach(share) : ""}Stop it with: mostra share stop ${share.shareId}\n`
3159
+ };
3160
+ }
3161
+ });
3162
+ /** `mostra share stop <artifact|shareId>`. */
3163
+ const shareStopCommand = defineCommand({
3164
+ path: ["share", "stop"],
3165
+ summary: "Stop a share, or every share of an artifact: its link stops working and its tunnel closes.",
3166
+ args: [{
3167
+ name: "target",
3168
+ summary: "A share's ID (shr_…), or an artifact's source path or ID."
3169
+ }],
3170
+ flags: [],
3171
+ output: {
3172
+ type: "ShareStopResult",
3173
+ topic: "cli"
3174
+ },
3175
+ exits: [EXIT.failure, EXIT.environment],
3176
+ example: "share stop ./sidebar-review",
3177
+ async run(context) {
3178
+ const target = arg(context, "target");
3179
+ const result = await context.call(shareStopMethod, SHARE_ID.test(target) ? { shareId: target } : { artifact: artifactRef(target, context.cwd) });
3180
+ return {
3181
+ result,
3182
+ human: result.stopped.length === 0 ? "Nothing was shared.\n" : result.stopped.map((share) => `Stopped ${share.shareId}\n`).join("")
3183
+ };
3184
+ }
3185
+ });
3186
+ /** `mostra share list [artifact] [--all]`. */
3187
+ const shareListCommand = defineCommand({
3188
+ path: ["share", "list"],
3189
+ summary: "List the active shares, of every artifact or of one; --all adds the ones that ended.",
3190
+ args: [{
3191
+ name: "artifact",
3192
+ summary: "Only this artifact's shares: its source path or ID.",
3193
+ optional: true
3194
+ }],
3195
+ flags: [{
3196
+ name: "all",
3197
+ kind: "boolean",
3198
+ summary: "Also list shares that ended, and why."
3199
+ }],
3200
+ output: {
3201
+ type: "ShareListResult",
3202
+ topic: "cli"
3203
+ },
3204
+ exits: [EXIT.failure],
3205
+ example: "share list --all",
3206
+ async run(context) {
3207
+ const given = context.args["artifact"];
3208
+ const result = await context.call(shareListMethod, {
3209
+ ...typeof given === "string" ? { artifact: artifactRef(given, context.cwd) } : {},
3210
+ ...context.flags["all"] === true ? { all: true } : {}
3211
+ });
3212
+ return {
3213
+ result,
3214
+ human: result.shares.length === 0 ? "Nothing is shared.\n" : `${result.shares.map((share) => line(share)).join("\n")}\n`
3215
+ };
3216
+ }
3217
+ });
3218
+ //#endregion
2914
3219
  //#region src/browser.ts
2915
3220
  /**
2916
3221
  * Opening a browser on a launch URL without putting it on a command line (D140 item 15, Opus
@@ -3277,6 +3582,9 @@ const COMMANDS = [
3277
3582
  }));
3278
3583
  }
3279
3584
  }),
3585
+ shareCommand,
3586
+ shareStopCommand,
3587
+ shareListCommand,
3280
3588
  waitCommand,
3281
3589
  resultsCommand,
3282
3590
  stateGetCommand,
@@ -3914,4 +4222,4 @@ async function runRuntime(io, args, stdio) {
3914
4222
  //#endregion
3915
4223
  export { COMMANDS as a, referenceMarkdown as i, commandDefinition as n, commandHelp as r, run as t };
3916
4224
 
3917
- //# sourceMappingURL=run-3QZacDLc.js.map
4225
+ //# sourceMappingURL=run-CuMkFuH7.js.map