@mostra/cli 0.6.1 → 0.7.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.
@@ -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-DO9Y3Dtm.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
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";
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";
@@ -2501,7 +2501,7 @@ const addCommand = defineCommand({
2501
2501
  * envelopes with `--json`, lines otherwise. Viewers never reach a preview; it isn't a version.
2502
2502
  */
2503
2503
  /** One event's line without `--json`. */
2504
- function line(event) {
2504
+ function line$1(event) {
2505
2505
  const files = event.files && event.files.length > 0 ? `: ${event.files.join(", ")}` : "";
2506
2506
  switch (event.kind) {
2507
2507
  case "built": return `Updated${files}\n`;
@@ -2537,7 +2537,7 @@ const devCommand = defineCommand({
2537
2537
  const early = [];
2538
2538
  const show = (event) => {
2539
2539
  if (event.kind === "diagnostics") for (const diagnostic of event.diagnostics ?? []) context.warn(diagnostic);
2540
- context.emit(event, line(event));
2540
+ context.emit(event, line$1(event));
2541
2541
  };
2542
2542
  connection?.onNotification(DEV_NOTIFY, (params) => {
2543
2543
  const event = params;
@@ -2911,6 +2911,195 @@ const statePatchCommand = defineCommand({
2911
2911
  }
2912
2912
  });
2913
2913
  //#endregion
2914
+ //#region src/commands/sharing.ts
2915
+ /**
2916
+ * `mostra share`: an artifact opened to people beyond this machine through a tunnel the daemon
2917
+ * runs (D47, D158): `--tailnet` (Tailscale Serve, inside your tailnet, with each person's
2918
+ * identity) or `--public` (a Cloudflare quick tunnel by default, or Tailscale Funnel with `--via
2919
+ * funnel`), whose link expires (1 hour by default, 7 days at most). The share lives in the
2920
+ * daemon, so the command returns at once with the link; `share stop` ends it and `share list`
2921
+ * shows what is shared. A client of `share/start`, `share/stop` and `share/list`.
2922
+ */
2923
+ const SHARE_ID = /^shr_[0-9A-HJKMNP-TV-Z]{26}$/;
2924
+ /** How each tunnel is named in human output. */
2925
+ const THROUGH = {
2926
+ tailnet: "Tailscale Serve, inside your tailnet",
2927
+ funnel: "Tailscale Funnel, public",
2928
+ cloudflare: "a Cloudflare quick tunnel, public"
2929
+ };
2930
+ /**
2931
+ * What a tailnet viewer's device needs, found on a real tailnet in WP-13: the tailnet's access
2932
+ * policy must let them reach the share's two ports of this device, and their browser's traffic
2933
+ * must go through Tailscale (no private or secure DNS of its own, no split tunneling that leaves
2934
+ * the browser out).
2935
+ */
2936
+ function tailnetReach(share) {
2937
+ const port = (origin) => origin === void 0 ? void 0 : new URL(origin).port || "443";
2938
+ const ports = [port(share.url), port(share.artifactOrigin)].filter((value) => value !== void 0);
2939
+ 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`;
2940
+ }
2941
+ /** One share as a line of human output. */
2942
+ function line(share) {
2943
+ const until = share.state === "stopped" ? `stopped${share.stopReason ? ` (${share.stopReason})` : ""}` : share.expiresAt ? `until ${share.expiresAt}` : "no expiry";
2944
+ return `${share.shareId} ${share.via} ${share.hostname} ${until}`;
2945
+ }
2946
+ /** `mostra share <artifact> --tailnet | --public`. */
2947
+ const shareCommand = defineCommand({
2948
+ path: ["share"],
2949
+ summary: "Open an artifact to people beyond this machine: inside your tailnet, or publicly with a link that expires.",
2950
+ args: [{
2951
+ name: "artifact",
2952
+ summary: "The artifact: its source path or its ID."
2953
+ }],
2954
+ flags: [
2955
+ {
2956
+ name: "tailnet",
2957
+ kind: "boolean",
2958
+ summary: "Share inside your tailnet through Tailscale Serve; each viewer is their tailnet identity."
2959
+ },
2960
+ {
2961
+ name: "public",
2962
+ kind: "boolean",
2963
+ summary: "Share publicly: anyone with the link can open it until it expires."
2964
+ },
2965
+ {
2966
+ name: "via",
2967
+ kind: "string",
2968
+ value: "<tunnel>",
2969
+ choices: ["cloudflare", "funnel"],
2970
+ default: "cloudflare",
2971
+ summary: "The public tunnel: a Cloudflare quick tunnel (no account), or Tailscale Funnel (shows your device's tailnet name)."
2972
+ },
2973
+ {
2974
+ name: "ttl",
2975
+ kind: "duration",
2976
+ value: "<d>",
2977
+ summary: "How long the link works, such as 30m or 24h. Public: 1h by default, 7d at most."
2978
+ },
2979
+ {
2980
+ name: "scope",
2981
+ kind: "list",
2982
+ value: "<a,b>",
2983
+ summary: "The link's scopes: view, draft, submit, review, signal, action:*. Default: all."
2984
+ },
2985
+ {
2986
+ name: "viewer",
2987
+ kind: "string",
2988
+ value: "<ref>",
2989
+ summary: "The person the link is for, by your own stable key for them; without it, each link is a viewer of its own."
2990
+ },
2991
+ {
2992
+ name: "viewer-name",
2993
+ kind: "string",
2994
+ value: "<name>",
2995
+ summary: "The display name of --viewer."
2996
+ },
2997
+ {
2998
+ name: "request-id",
2999
+ kind: "string",
3000
+ value: "<id>",
3001
+ summary: "Make a retried share return the same share instead of opening another."
3002
+ }
3003
+ ],
3004
+ output: {
3005
+ type: "ShareStartResult",
3006
+ topic: "cli"
3007
+ },
3008
+ exits: [EXIT.failure, EXIT.environment],
3009
+ example: "share ./sidebar-review --public --ttl 2h",
3010
+ async run(context) {
3011
+ const artifact = artifactRef(arg(context, "artifact"), context.cwd);
3012
+ const tailnet = context.flags["tailnet"] === true;
3013
+ const publicly = context.flags["public"] === true;
3014
+ if (tailnet === publicly) throw usage("Give --tailnet or --public.");
3015
+ const viaFlag = flag(context, "via");
3016
+ if (viaFlag !== void 0 && !publicly) throw usage("--via chooses a public tunnel: add --public.");
3017
+ const via = tailnet ? "tailnet" : viaFlag === "funnel" ? "funnel" : "cloudflare";
3018
+ const ttl = flag(context, "ttl");
3019
+ const scopes = context.flags["scope"];
3020
+ const viewerRef = flag(context, "viewer");
3021
+ const viewerName = flag(context, "viewer-name");
3022
+ const requestId = flag(context, "request-id");
3023
+ if (viewerName !== void 0 && viewerRef === void 0) throw usage("--viewer-name needs --viewer.");
3024
+ const share = await context.call(shareStartMethod, {
3025
+ artifact,
3026
+ via,
3027
+ ...ttl !== void 0 ? { ttl } : {},
3028
+ ...scopes !== void 0 ? { scopes } : {},
3029
+ ...viewerRef !== void 0 ? { viewer: {
3030
+ ref: viewerRef,
3031
+ ...viewerName !== void 0 ? { name: viewerName } : {}
3032
+ } } : {},
3033
+ ...requestId !== void 0 ? { requestId } : {}
3034
+ });
3035
+ context.record({
3036
+ event: "share.done",
3037
+ fields: { kind: via }
3038
+ });
3039
+ const until = share.expiresAt ? `until ${share.expiresAt}` : "until you stop it";
3040
+ return {
3041
+ result: share,
3042
+ human: `${share.url}\nShared through ${THROUGH[via]}, ${until}.\n${via === "tailnet" ? tailnetReach(share) : ""}Stop it with: mostra share stop ${share.shareId}\n`
3043
+ };
3044
+ }
3045
+ });
3046
+ /** `mostra share stop <artifact|shareId>`. */
3047
+ const shareStopCommand = defineCommand({
3048
+ path: ["share", "stop"],
3049
+ summary: "Stop a share, or every share of an artifact: its link stops working and its tunnel closes.",
3050
+ args: [{
3051
+ name: "target",
3052
+ summary: "A share's ID (shr_…), or an artifact's source path or ID."
3053
+ }],
3054
+ flags: [],
3055
+ output: {
3056
+ type: "ShareStopResult",
3057
+ topic: "cli"
3058
+ },
3059
+ exits: [EXIT.failure, EXIT.environment],
3060
+ example: "share stop ./sidebar-review",
3061
+ async run(context) {
3062
+ const target = arg(context, "target");
3063
+ const result = await context.call(shareStopMethod, SHARE_ID.test(target) ? { shareId: target } : { artifact: artifactRef(target, context.cwd) });
3064
+ return {
3065
+ result,
3066
+ human: result.stopped.length === 0 ? "Nothing was shared.\n" : result.stopped.map((share) => `Stopped ${share.shareId}\n`).join("")
3067
+ };
3068
+ }
3069
+ });
3070
+ /** `mostra share list [artifact] [--all]`. */
3071
+ const shareListCommand = defineCommand({
3072
+ path: ["share", "list"],
3073
+ summary: "List the active shares, of every artifact or of one; --all adds the ones that ended.",
3074
+ args: [{
3075
+ name: "artifact",
3076
+ summary: "Only this artifact's shares: its source path or ID.",
3077
+ optional: true
3078
+ }],
3079
+ flags: [{
3080
+ name: "all",
3081
+ kind: "boolean",
3082
+ summary: "Also list shares that ended, and why."
3083
+ }],
3084
+ output: {
3085
+ type: "ShareListResult",
3086
+ topic: "cli"
3087
+ },
3088
+ exits: [EXIT.failure],
3089
+ example: "share list --all",
3090
+ async run(context) {
3091
+ const given = context.args["artifact"];
3092
+ const result = await context.call(shareListMethod, {
3093
+ ...typeof given === "string" ? { artifact: artifactRef(given, context.cwd) } : {},
3094
+ ...context.flags["all"] === true ? { all: true } : {}
3095
+ });
3096
+ return {
3097
+ result,
3098
+ human: result.shares.length === 0 ? "Nothing is shared.\n" : `${result.shares.map((share) => line(share)).join("\n")}\n`
3099
+ };
3100
+ }
3101
+ });
3102
+ //#endregion
2914
3103
  //#region src/browser.ts
2915
3104
  /**
2916
3105
  * Opening a browser on a launch URL without putting it on a command line (D140 item 15, Opus
@@ -3277,6 +3466,9 @@ const COMMANDS = [
3277
3466
  }));
3278
3467
  }
3279
3468
  }),
3469
+ shareCommand,
3470
+ shareStopCommand,
3471
+ shareListCommand,
3280
3472
  waitCommand,
3281
3473
  resultsCommand,
3282
3474
  stateGetCommand,
@@ -3914,4 +4106,4 @@ async function runRuntime(io, args, stdio) {
3914
4106
  //#endregion
3915
4107
  export { COMMANDS as a, referenceMarkdown as i, commandDefinition as n, commandHelp as r, run as t };
3916
4108
 
3917
- //# sourceMappingURL=run-3QZacDLc.js.map
4109
+ //# sourceMappingURL=run-DO9Y3Dtm.js.map