@mostra/runtime 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.
- package/dist/bin.js +1 -1
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/{instance-DpD340-W.js → instance-BRfg27Rg.js} +2784 -598
- package/dist/instance-BRfg27Rg.js.map +1 -0
- package/package.json +5 -5
- package/src/addressing/index.ts +85 -31
- package/src/gateway/browser.ts +3 -1
- package/src/gateway/capabilities.ts +227 -18
- package/src/gateway/http.ts +12 -2
- package/src/gateway/identity.ts +75 -0
- package/src/gateway/index.ts +1254 -437
- package/src/gateway/routes.ts +52 -7
- package/src/gateway/worker.ts +204 -0
- package/src/instance/index.ts +72 -0
- package/src/interaction/index.ts +8 -0
- package/src/interaction/viewers.ts +21 -2
- package/src/ledger/migrations.ts +61 -0
- package/src/live/index.ts +14 -1
- package/src/platform/index.ts +1 -0
- package/src/platform/tools.ts +145 -0
- package/src/processes/manager.ts +10 -2
- package/src/protocol-server/index.ts +4 -0
- package/src/publish/methods.ts +6 -2
- package/src/publish/publisher.ts +77 -44
- package/src/publish/scaffold.ts +82 -0
- package/src/share/cloudflare.ts +136 -0
- package/src/share/index.ts +823 -0
- package/src/share/tailscale.ts +217 -0
- package/src/share/tunnel.ts +186 -0
- package/dist/instance-DpD340-W.js.map +0 -1
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where this system keeps the tunnel tools a share drives (D158 item 4): `tailscale` and
|
|
3
|
+
* `cloudflared`, which Mostra never bundles or downloads. A daemon started by a login service may
|
|
4
|
+
* run with a short `PATH`, so the tools' usual install locations are searched after it, and an
|
|
5
|
+
* environment variable names one outright. How to install each is said here too, per system.
|
|
6
|
+
*/
|
|
7
|
+
import { accessSync, constants, statSync } from "node:fs";
|
|
8
|
+
import { delimiter, join } from "node:path";
|
|
9
|
+
import { OS, WINDOWS } from "./directories.ts";
|
|
10
|
+
|
|
11
|
+
/** A tunnel tool. */
|
|
12
|
+
export type TunnelTool = "tailscale" | "cloudflared";
|
|
13
|
+
|
|
14
|
+
/** The variable that names a tool's executable outright. */
|
|
15
|
+
const TOOL_VARIABLES: Readonly<Record<TunnelTool, string>> = {
|
|
16
|
+
tailscale: "MOSTRA_TAILSCALE",
|
|
17
|
+
cloudflared: "MOSTRA_CLOUDFLARED",
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
/** The usual install locations of each tool, per system, after `PATH`. */
|
|
21
|
+
export function usualLocations(
|
|
22
|
+
tool: TunnelTool,
|
|
23
|
+
env: Readonly<Record<string, string | undefined>>,
|
|
24
|
+
): string[] {
|
|
25
|
+
if (WINDOWS) {
|
|
26
|
+
const programs = env["ProgramFiles"] ?? "C:\\Program Files";
|
|
27
|
+
const programs86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
|
|
28
|
+
return tool === "tailscale"
|
|
29
|
+
? [join(programs, "Tailscale", "tailscale.exe")]
|
|
30
|
+
: [
|
|
31
|
+
join(programs86, "cloudflared", "cloudflared.exe"),
|
|
32
|
+
join(programs, "cloudflared", "cloudflared.exe"),
|
|
33
|
+
];
|
|
34
|
+
}
|
|
35
|
+
if (OS === "darwin") {
|
|
36
|
+
return tool === "tailscale"
|
|
37
|
+
? [
|
|
38
|
+
"/opt/homebrew/bin/tailscale",
|
|
39
|
+
"/usr/local/bin/tailscale",
|
|
40
|
+
// Homebrew's formula left unlinked (beside the Mac app, which owns the name), as found on
|
|
41
|
+
// a real Mac in WP-13: its prefix keeps the command line all the same.
|
|
42
|
+
"/opt/homebrew/opt/tailscale/bin/tailscale",
|
|
43
|
+
"/usr/local/opt/tailscale/bin/tailscale",
|
|
44
|
+
// The Mac app's own executable is its command line too.
|
|
45
|
+
"/Applications/Tailscale.app/Contents/MacOS/Tailscale",
|
|
46
|
+
]
|
|
47
|
+
: [
|
|
48
|
+
"/opt/homebrew/bin/cloudflared",
|
|
49
|
+
"/usr/local/bin/cloudflared",
|
|
50
|
+
"/opt/homebrew/opt/cloudflared/bin/cloudflared",
|
|
51
|
+
"/usr/local/opt/cloudflared/bin/cloudflared",
|
|
52
|
+
];
|
|
53
|
+
}
|
|
54
|
+
return tool === "tailscale"
|
|
55
|
+
? ["/usr/bin/tailscale", "/usr/local/bin/tailscale", "/usr/sbin/tailscale"]
|
|
56
|
+
: ["/usr/bin/cloudflared", "/usr/local/bin/cloudflared"];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function executable(path: string): boolean {
|
|
60
|
+
try {
|
|
61
|
+
if (!statSync(path).isFile()) return false;
|
|
62
|
+
if (!WINDOWS) accessSync(path, constants.X_OK);
|
|
63
|
+
return true;
|
|
64
|
+
} catch {
|
|
65
|
+
return false;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* The tool's executable: the variable's (which must exist), else the first on `PATH`, else the
|
|
71
|
+
* first usual location that exists; `undefined` when there is none.
|
|
72
|
+
*/
|
|
73
|
+
function findTool(
|
|
74
|
+
tool: TunnelTool,
|
|
75
|
+
env: Readonly<Record<string, string | undefined>>,
|
|
76
|
+
): string | undefined {
|
|
77
|
+
const named = env[TOOL_VARIABLES[tool]];
|
|
78
|
+
if (named !== undefined && named !== "") return executable(named) ? named : undefined;
|
|
79
|
+
const names = WINDOWS ? [`${tool}.exe`] : [tool];
|
|
80
|
+
const path = (WINDOWS ? (env["Path"] ?? env["PATH"]) : env["PATH"]) ?? "";
|
|
81
|
+
for (const dir of path.split(delimiter)) {
|
|
82
|
+
if (dir === "") continue;
|
|
83
|
+
for (const name of names) {
|
|
84
|
+
const candidate = join(dir, name);
|
|
85
|
+
if (executable(candidate)) return candidate;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return usualLocations(tool, env).find(executable);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** How a tool runs: its executable and the arguments before the tool's own. */
|
|
92
|
+
export interface ToolCommand {
|
|
93
|
+
readonly command: string;
|
|
94
|
+
readonly args: readonly string[];
|
|
95
|
+
/** Run by `MOSTRA_TEST_TUNNELS`: a local fake that forwards plain HTTP on loopback. */
|
|
96
|
+
readonly fake: boolean;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* The variable that replaces both tools with local fakes for tests (`<dir>/tailscale.mjs` and
|
|
101
|
+
* `<dir>/cloudflared.mjs`, run on this Node.js): the conformance kit's and the suites' own, which
|
|
102
|
+
* forward on loopback as the real tools forward from their networks (STANDARDS: real side effects
|
|
103
|
+
* in tests go to local fakes).
|
|
104
|
+
*/
|
|
105
|
+
const TEST_TUNNELS_VARIABLE = "MOSTRA_TEST_TUNNELS";
|
|
106
|
+
|
|
107
|
+
/** How to run a tool: {@link findTool}'s executable, or the test fake; `undefined` when missing. */
|
|
108
|
+
export function toolCommand(
|
|
109
|
+
tool: TunnelTool,
|
|
110
|
+
env: Readonly<Record<string, string | undefined>>,
|
|
111
|
+
): ToolCommand | undefined {
|
|
112
|
+
const fakes = env[TEST_TUNNELS_VARIABLE];
|
|
113
|
+
if (fakes !== undefined && fakes !== "") {
|
|
114
|
+
const script = join(fakes, `${tool}.mjs`);
|
|
115
|
+
return regularFile(script)
|
|
116
|
+
? { command: process.execPath, args: [script], fake: true }
|
|
117
|
+
: undefined;
|
|
118
|
+
}
|
|
119
|
+
const found = findTool(tool, env);
|
|
120
|
+
return found === undefined ? undefined : { command: found, args: [], fake: false };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
function regularFile(path: string): boolean {
|
|
124
|
+
try {
|
|
125
|
+
return statSync(path).isFile();
|
|
126
|
+
} catch {
|
|
127
|
+
return false;
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** How to install a tool on this system, as one sentence. */
|
|
132
|
+
export function installHint(tool: TunnelTool): string {
|
|
133
|
+
if (tool === "tailscale") {
|
|
134
|
+
if (WINDOWS)
|
|
135
|
+
return "Install Tailscale from https://tailscale.com/download/windows (or `winget install tailscale.tailscale`) and sign in.";
|
|
136
|
+
if (OS === "darwin")
|
|
137
|
+
return "Install Tailscale from https://tailscale.com/download/mac (or `brew install tailscale`) and sign in.";
|
|
138
|
+
return "Install Tailscale with `curl -fsSL https://tailscale.com/install.sh | sh` (https://tailscale.com/download/linux), then run `sudo tailscale up`.";
|
|
139
|
+
}
|
|
140
|
+
if (WINDOWS)
|
|
141
|
+
return "Install cloudflared with `winget install --id Cloudflare.cloudflared` (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).";
|
|
142
|
+
if (OS === "darwin")
|
|
143
|
+
return "Install cloudflared with `brew install cloudflared` (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).";
|
|
144
|
+
return "Install cloudflared from your distribution's Cloudflare package repository or https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/.";
|
|
145
|
+
}
|
package/src/processes/manager.ts
CHANGED
|
@@ -54,6 +54,12 @@ export interface SpawnSpec {
|
|
|
54
54
|
* `exited` resolves.
|
|
55
55
|
*/
|
|
56
56
|
readonly onStdout?: (line: string) => void;
|
|
57
|
+
/**
|
|
58
|
+
* Receives each line the child writes to stderr, redacted, instead of the log (the exit's
|
|
59
|
+
* `stderrTail` keeps the last ones as always): for a tool that reports its state there, such as
|
|
60
|
+
* `cloudflared`'s tunnel address (D158).
|
|
61
|
+
*/
|
|
62
|
+
readonly onStderr?: (line: string) => void;
|
|
57
63
|
/**
|
|
58
64
|
* Opens a JSON-RPC channel over Node IPC; the command must then be a Node.js executable. The
|
|
59
65
|
* handlers answer the child's requests besides the built-in `child/adopt` and `child/release`.
|
|
@@ -270,9 +276,11 @@ function createManager({
|
|
|
270
276
|
drained.push(new Promise((resolve) => lines.once("close", resolve)));
|
|
271
277
|
lines.on("line", (line) => {
|
|
272
278
|
// The log redacts what it writes; the tail feeds diagnostics, so it is redacted here.
|
|
273
|
-
|
|
279
|
+
const redacted = redactor.redact(line);
|
|
280
|
+
stderrTail.push(redacted);
|
|
274
281
|
if (stderrTail.length > STDERR_TAIL) stderrTail.shift();
|
|
275
|
-
|
|
282
|
+
if (spec.onStderr) spec.onStderr(redacted);
|
|
283
|
+
else log.info("process.stderr", { kind: spec.kind, pid, line });
|
|
276
284
|
});
|
|
277
285
|
}
|
|
278
286
|
|
|
@@ -14,6 +14,7 @@ import {
|
|
|
14
14
|
instanceStatusMethod,
|
|
15
15
|
mostraShutdownMethod,
|
|
16
16
|
RpcError,
|
|
17
|
+
type Share,
|
|
17
18
|
type WorkerStatus,
|
|
18
19
|
} from "@mostra/protocol";
|
|
19
20
|
import { handler, type MethodHandler } from "./server.ts";
|
|
@@ -37,6 +38,8 @@ export interface SessionMethodsOptions {
|
|
|
37
38
|
workers?(): readonly WorkerStatus[];
|
|
38
39
|
/** When an idle daemon exits (WP-08); `undefined` while busy or for an instance that never does. */
|
|
39
40
|
idleExitAt?(): string | undefined;
|
|
41
|
+
/** The active shares (WP-13, D158). */
|
|
42
|
+
shares?(): readonly Share[];
|
|
40
43
|
/**
|
|
41
44
|
* The supervisor's own checks of its home (`instance/check`, D140 item 18), in order; `deep`
|
|
42
45
|
* also hashes every version against its output digest.
|
|
@@ -62,6 +65,7 @@ export function sessionMethods(options: SessionMethodsOptions): MethodHandler[]
|
|
|
62
65
|
...(gateway ? { gateway } : {}),
|
|
63
66
|
...(options.deliveries ? { deliveries: [...options.deliveries()] } : {}),
|
|
64
67
|
...(options.workers ? { workers: [...options.workers()] } : {}),
|
|
68
|
+
...(options.shares ? { shares: [...options.shares()] } : {}),
|
|
65
69
|
...(() => {
|
|
66
70
|
const at = options.idleExitAt?.();
|
|
67
71
|
return at === undefined ? {} : { idleExitAt: at };
|
package/src/publish/methods.ts
CHANGED
|
@@ -54,7 +54,11 @@ export function artifactMethods(options: {
|
|
|
54
54
|
* The artifact's default capability link (D90, D97 item 3), added to every receipt, replays
|
|
55
55
|
* included. Recorded receipts never hold it: the ledger keeps no link's secret.
|
|
56
56
|
*/
|
|
57
|
-
readonly link?: (
|
|
57
|
+
readonly link?: (
|
|
58
|
+
artifactId: string,
|
|
59
|
+
) =>
|
|
60
|
+
| { readonly url: string; readonly tokenId: string }
|
|
61
|
+
| Promise<{ readonly url: string; readonly tokenId: string }>;
|
|
58
62
|
/**
|
|
59
63
|
* Hears every publish that succeeded, a reused version too: a publish clears the artifact's
|
|
60
64
|
* parked workers (FAILURE_MODEL §2).
|
|
@@ -71,7 +75,7 @@ export function artifactMethods(options: {
|
|
|
71
75
|
handler(artifactPublishMethod, async (params) => {
|
|
72
76
|
const receipt = await options.publisher().publish(params);
|
|
73
77
|
options.published?.(receipt.artifactId);
|
|
74
|
-
return options.link ? { ...receipt, ...options.link(receipt.artifactId) } : receipt;
|
|
78
|
+
return options.link ? { ...receipt, ...(await options.link(receipt.artifactId)) } : receipt;
|
|
75
79
|
}),
|
|
76
80
|
handler(depsAddMethod, async (params) => {
|
|
77
81
|
const added = await options.publisher().addDependencies(params);
|
package/src/publish/publisher.ts
CHANGED
|
@@ -82,6 +82,7 @@ import {
|
|
|
82
82
|
versionIdFor,
|
|
83
83
|
} from "./digest.ts";
|
|
84
84
|
import { extractManifest } from "./manifest.ts";
|
|
85
|
+
import { SCAFFOLD_PATHS, type ScaffoldInput, scaffoldFiles } from "./scaffold.ts";
|
|
85
86
|
import {
|
|
86
87
|
copySnapshot,
|
|
87
88
|
listSource,
|
|
@@ -249,47 +250,55 @@ async function archiveSnapshot(
|
|
|
249
250
|
return true;
|
|
250
251
|
}
|
|
251
252
|
|
|
252
|
-
/**
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
253
|
+
/**
|
|
254
|
+
* What `artifact/create` records for its `requestId`: its result, and the exact text of each file
|
|
255
|
+
* it writes, so a retry, by this runtime or a newer one, completes exactly the bytes the first
|
|
256
|
+
* attempt began (WP-14's GPT and Opus reviews).
|
|
257
|
+
*/
|
|
258
|
+
interface CreateRecord {
|
|
259
|
+
readonly result: ArtifactCreateResult;
|
|
260
|
+
readonly scaffold: { readonly files: Readonly<Record<string, string>> };
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/** The text of each of `paths` (of {@link scaffoldFiles}) for `input`. */
|
|
264
|
+
function scaffoldText(paths: readonly string[], input: ScaffoldInput): Record<string, string> {
|
|
265
|
+
const all = scaffoldFiles(input);
|
|
266
|
+
return Object.fromEntries(
|
|
267
|
+
paths.flatMap((path) => {
|
|
268
|
+
const text = all.get(path);
|
|
269
|
+
return text === undefined ? [] : [[path, text]];
|
|
270
|
+
}),
|
|
271
|
+
);
|
|
271
272
|
}
|
|
272
273
|
|
|
273
274
|
/**
|
|
274
|
-
* Writes `artifact/create`'s
|
|
275
|
-
*
|
|
276
|
-
*
|
|
275
|
+
* Writes `artifact/create`'s files (`files`, path to text) into `dir`, completing an interrupted
|
|
276
|
+
* write: an existing file whose bytes are the expected text's or a prefix of them (a write cut
|
|
277
|
+
* short, even inside a character) ends as the expected text, and anything else the author has
|
|
278
|
+
* written since is left alone.
|
|
277
279
|
*/
|
|
278
|
-
async function writeScaffold(dir: string,
|
|
279
|
-
const expected = scaffold(artifactId, title);
|
|
280
|
-
const file = join(dir, "index.tsx");
|
|
280
|
+
async function writeScaffold(dir: string, files: Readonly<Record<string, string>>): Promise<void> {
|
|
281
281
|
await mkdir(dir, { recursive: true });
|
|
282
|
-
let
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
current
|
|
282
|
+
let wrote = false;
|
|
283
|
+
for (const [path, text] of Object.entries(files)) {
|
|
284
|
+
const expected = Buffer.from(text, "utf8");
|
|
285
|
+
const file = join(dir, path);
|
|
286
|
+
let current: Buffer | undefined;
|
|
287
|
+
try {
|
|
288
|
+
current = await readFile(file);
|
|
289
|
+
} catch {
|
|
290
|
+
current = undefined;
|
|
291
|
+
}
|
|
292
|
+
if (current !== undefined) {
|
|
293
|
+
const prefix =
|
|
294
|
+
current.length <= expected.length && expected.subarray(0, current.length).equals(current);
|
|
295
|
+
if (!prefix || current.length === expected.length) continue;
|
|
296
|
+
}
|
|
297
|
+
await writeFile(file, expected);
|
|
298
|
+
fsyncPath(file);
|
|
299
|
+
wrote = true;
|
|
287
300
|
}
|
|
288
|
-
if (
|
|
289
|
-
if (current === expected) return;
|
|
290
|
-
await writeFile(file, expected);
|
|
291
|
-
fsyncPath(file);
|
|
292
|
-
fsyncPath(dir, true);
|
|
301
|
+
if (wrote) fsyncPath(dir, true);
|
|
293
302
|
}
|
|
294
303
|
|
|
295
304
|
/**
|
|
@@ -878,14 +887,32 @@ export function createPublisher(options: PublisherOptions): Publisher {
|
|
|
878
887
|
}
|
|
879
888
|
|
|
880
889
|
async function create(params: ArtifactCreateParams): Promise<ArtifactCreateResult> {
|
|
881
|
-
// A retried request completes what the first attempt recorded (H-03): the
|
|
882
|
-
// only after the result is durable, so a crash in between leaves something to finish.
|
|
890
|
+
// A retried request completes what the first attempt recorded (H-03): the files are written
|
|
891
|
+
// only after the result is durable, so a crash in between leaves something to finish. The
|
|
892
|
+
// record also keeps the files' exact text, so a retry by a newer runtime completes exactly
|
|
893
|
+
// what the first attempt began (WP-14's GPT and Opus reviews); the client gets the result
|
|
894
|
+
// alone.
|
|
883
895
|
const key = requestKey("artifact/create", params);
|
|
884
896
|
if (key !== undefined) {
|
|
885
|
-
const
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
897
|
+
const recorded = ledger.read((db) =>
|
|
898
|
+
recordedResult<CreateRecord | ArtifactCreateResult>(db, key),
|
|
899
|
+
);
|
|
900
|
+
if (recorded !== undefined) {
|
|
901
|
+
if ("result" in recorded) {
|
|
902
|
+
await writeScaffold(recorded.result.dir, recorded.scaffold.files);
|
|
903
|
+
return recorded.result;
|
|
904
|
+
}
|
|
905
|
+
// A record from before WP-14 is the result itself, whose one file, the entry, names no
|
|
906
|
+
// release: it is written as this runtime writes it.
|
|
907
|
+
await writeScaffold(
|
|
908
|
+
recorded.dir,
|
|
909
|
+
scaffoldText(recorded.files, {
|
|
910
|
+
artifactId: recorded.artifactId,
|
|
911
|
+
title: params.title ?? basename(recorded.dir),
|
|
912
|
+
version: options.runtimeVersion,
|
|
913
|
+
}),
|
|
914
|
+
);
|
|
915
|
+
return recorded;
|
|
889
916
|
}
|
|
890
917
|
}
|
|
891
918
|
if (params.template !== undefined) {
|
|
@@ -910,11 +937,17 @@ export function createPublisher(options: PublisherOptions): Publisher {
|
|
|
910
937
|
const result: ArtifactCreateResult = {
|
|
911
938
|
artifactId: ArtifactId.create(),
|
|
912
939
|
dir,
|
|
913
|
-
files: [
|
|
940
|
+
files: [...SCAFFOLD_PATHS],
|
|
914
941
|
};
|
|
915
|
-
|
|
942
|
+
const files = scaffoldText(result.files, {
|
|
943
|
+
artifactId: result.artifactId,
|
|
944
|
+
title: params.title ?? basename(dir),
|
|
945
|
+
version: options.runtimeVersion,
|
|
946
|
+
});
|
|
947
|
+
const recordedCreate: CreateRecord = { result, scaffold: { files } };
|
|
948
|
+
record(key, recordedCreate);
|
|
916
949
|
faults.at("create:after-record");
|
|
917
|
-
await writeScaffold(dir,
|
|
950
|
+
await writeScaffold(dir, files);
|
|
918
951
|
return result;
|
|
919
952
|
}
|
|
920
953
|
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What `artifact/create` (`mostra new`) writes into an empty directory: the entry with the
|
|
3
|
+
* artifact's generated `id`, an `AGENTS.md` for the agent that edits it next (AX-06, WP-14), and a
|
|
4
|
+
* `CLAUDE.md` that imports it, since Claude Code loads a subdirectory's `CLAUDE.md` when it works
|
|
5
|
+
* there but not its `AGENTS.md`. Every file is source like any other: it is in the version's
|
|
6
|
+
* snapshot and its digest.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** What a new artifact's files are made from. */
|
|
10
|
+
export interface ScaffoldInput {
|
|
11
|
+
readonly artifactId: string;
|
|
12
|
+
readonly title: string;
|
|
13
|
+
/** This runtime's release, which `npx -y @mostra/cli@<version>` pins. */
|
|
14
|
+
readonly version: string;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** The files a new artifact gets, in the order `artifact/create` reports them. */
|
|
18
|
+
export const SCAFFOLD_PATHS: readonly string[] = ["index.tsx", "AGENTS.md", "CLAUDE.md"];
|
|
19
|
+
|
|
20
|
+
function entry({ artifactId, title }: ScaffoldInput): string {
|
|
21
|
+
return [
|
|
22
|
+
'import { defineArtifact } from "@mostra/react";',
|
|
23
|
+
"",
|
|
24
|
+
"export const artifact = defineArtifact({",
|
|
25
|
+
` id: ${JSON.stringify(artifactId)},`,
|
|
26
|
+
` title: ${JSON.stringify(title)},`,
|
|
27
|
+
"});",
|
|
28
|
+
"",
|
|
29
|
+
"export default function Page() {",
|
|
30
|
+
" return (",
|
|
31
|
+
' <main className="mx-auto max-w-2xl p-8">',
|
|
32
|
+
' <h1 className="text-2xl font-semibold">{artifact.title}</h1>',
|
|
33
|
+
" </main>",
|
|
34
|
+
" );",
|
|
35
|
+
"}",
|
|
36
|
+
"",
|
|
37
|
+
].join("\n");
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** A Markdown heading's text: one line, nothing that reads as Markdown syntax at its start. */
|
|
41
|
+
function headingText(title: string): string {
|
|
42
|
+
const line = title.replace(/\s+/g, " ").trim();
|
|
43
|
+
return line === "" ? "Mostra artifact" : line;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function agents({ title, version }: ScaffoldInput): string {
|
|
47
|
+
return [
|
|
48
|
+
`# ${headingText(title)}`,
|
|
49
|
+
"",
|
|
50
|
+
"This directory is a Mostra artifact: a page people open from a private link, read, answer and act on. Their answers come back to you as results.",
|
|
51
|
+
"",
|
|
52
|
+
"## Work on it",
|
|
53
|
+
"",
|
|
54
|
+
"1. Edit `index.tsx`: ordinary React 19 and TypeScript with Tailwind CSS 4, with no `package.json` or build configuration.",
|
|
55
|
+
"2. Run `mostra verify .` until it reports `pass`, and look at both screenshots it lists (`--screenshots always` lists them every time).",
|
|
56
|
+
"3. Run `mostra publish .`. It prints the private link: whoever holds it can use the page.",
|
|
57
|
+
"4. Give the link to the person, saying who is asking and why. Then run `mostra wait . --until submitted` and `mostra results .`.",
|
|
58
|
+
"",
|
|
59
|
+
`Where \`mostra\` isn't installed, run \`npx -y @mostra/cli@${version}\` in its place.`,
|
|
60
|
+
"",
|
|
61
|
+
"## Keep in mind",
|
|
62
|
+
"",
|
|
63
|
+
'- Every answer is a field with an ID that stays the same on every render and in every version: `useField("budget", 0, { label: "Budget" })`, or a template on your data\'s own ID for a list. Answers carry over to a new version by ID.',
|
|
64
|
+
"- Keep the `id` in `defineArtifact`: it is this artifact's identity. Manifest values are literals.",
|
|
65
|
+
'- Code that must run on this machine (send, save, call an API) goes in a module that starts with `"use server"`; live data in `live.ts`; static files in `public/`.',
|
|
66
|
+
"- Imports stay inside this directory, or name an npm package.",
|
|
67
|
+
"",
|
|
68
|
+
"## More",
|
|
69
|
+
"",
|
|
70
|
+
"`mostra docs guide` is the full guide to writing artifacts, and `mostra docs <CODE>` explains any diagnostic. The same guide is the Mostra Agent Skill: `npx skills add mostra-dev/mostra`.",
|
|
71
|
+
"",
|
|
72
|
+
].join("\n");
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** The files of a new artifact, by path. */
|
|
76
|
+
export function scaffoldFiles(input: ScaffoldInput): Map<string, string> {
|
|
77
|
+
return new Map([
|
|
78
|
+
["index.tsx", entry(input)],
|
|
79
|
+
["AGENTS.md", agents(input)],
|
|
80
|
+
["CLAUDE.md", "@AGENTS.md\n"],
|
|
81
|
+
]);
|
|
82
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Cloudflare driver (D158 item 4): a Cloudflare quick tunnel per face, `cloudflared tunnel
|
|
3
|
+
* --url http://127.0.0.1:<port>`, which needs no account and gets a random `trycloudflare.com`
|
|
4
|
+
* hostname. Each hostname is its own site (`trycloudflare.com` is a public suffix), so a share's
|
|
5
|
+
* shell and artifact are cross-site and its frames use worker mode (D70). Quick tunnels hold every
|
|
6
|
+
* response back until it ends, so pages long-poll (VERIFIED_FACTS, WP-13). A quick tunnel's
|
|
7
|
+
* hostname dies with its process, so a Cloudflare share ends with its tunnel.
|
|
8
|
+
*/
|
|
9
|
+
import { Resolver } from "node:dns/promises";
|
|
10
|
+
import { mkdirSync, writeFileSync } from "node:fs";
|
|
11
|
+
import { join } from "node:path";
|
|
12
|
+
import { createDiagnostic, RpcError } from "@mostra/protocol";
|
|
13
|
+
import type { Log } from "../log.ts";
|
|
14
|
+
import { installHint, type ToolCommand, toolCommand } from "../platform/index.ts";
|
|
15
|
+
import type { ProcessManager } from "../processes/index.ts";
|
|
16
|
+
import { type LineVerdict, runTunnel, type Tunnel } from "./tunnel.ts";
|
|
17
|
+
|
|
18
|
+
/** How long a quick tunnel may take to serve: registering and the hostname's first answer. */
|
|
19
|
+
const QUICK_TUNNEL_TIMEOUT_MS = 60_000;
|
|
20
|
+
|
|
21
|
+
/** What the driver needs. */
|
|
22
|
+
export interface CloudflareContext {
|
|
23
|
+
readonly processes: ProcessManager;
|
|
24
|
+
readonly log: Log;
|
|
25
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
26
|
+
/** A directory of the home's cache for the tunnel's empty configuration file. */
|
|
27
|
+
readonly cacheDir: string;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** How `cloudflared` runs, or `MOSTRA_SHARE_TOOL_MISSING`. */
|
|
31
|
+
export function cloudflared(context: CloudflareContext): ToolCommand {
|
|
32
|
+
const tool = toolCommand("cloudflared", context.env);
|
|
33
|
+
if (!tool) {
|
|
34
|
+
throw new RpcError(
|
|
35
|
+
createDiagnostic("MOSTRA_SHARE_TOOL_MISSING", {
|
|
36
|
+
message: `cloudflared isn't installed on this machine. ${installHint("cloudflared")}`,
|
|
37
|
+
}),
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
return tool;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Reads `cloudflared`'s log: it names the quick tunnel's address in a banner, and serves once a
|
|
45
|
+
* connection to Cloudflare's edge is registered.
|
|
46
|
+
*/
|
|
47
|
+
function quickTunnelReader(fake: boolean): (line: string) => LineVerdict {
|
|
48
|
+
return (line) => {
|
|
49
|
+
// The test fake's tunnels are sites of their own on loopback, as quick tunnels are.
|
|
50
|
+
const local = fake ? /\b(http:\/\/[a-z0-9-]+\.localhost:\d+)\b/.exec(line) : null;
|
|
51
|
+
if (local) return { kind: "origin", origin: (local[1] as string).toLowerCase() };
|
|
52
|
+
const address = /https:\/\/([a-z0-9-]+\.trycloudflare\.com)\b/i.exec(line);
|
|
53
|
+
if (address)
|
|
54
|
+
return { kind: "origin", origin: `https://${(address[1] as string).toLowerCase()}` };
|
|
55
|
+
if (/Registered tunnel connection/i.test(line)) return { kind: "serving" };
|
|
56
|
+
if (
|
|
57
|
+
/failed to (request|create) quick tunnel|error unmarshaling QuickTunnel|429 Too Many Requests/i.test(
|
|
58
|
+
line,
|
|
59
|
+
)
|
|
60
|
+
) {
|
|
61
|
+
return {
|
|
62
|
+
kind: "failed",
|
|
63
|
+
diagnostic: createDiagnostic("MOSTRA_SHARE_TUNNEL_FAILED", {
|
|
64
|
+
message: `Cloudflare didn't open a quick tunnel: ${line.trim().slice(0, 300)}`,
|
|
65
|
+
}),
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
return undefined;
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Opens a quick tunnel to `local`. It never reads the user's own `cloudflared` configuration (a
|
|
74
|
+
* file with ingress rules would turn the quick tunnel off): it runs with an empty one of its own.
|
|
75
|
+
*/
|
|
76
|
+
export function quickTunnel(
|
|
77
|
+
context: CloudflareContext,
|
|
78
|
+
input: { readonly local: string; readonly ownerRef: string },
|
|
79
|
+
): Promise<Tunnel> {
|
|
80
|
+
const tool = cloudflared(context);
|
|
81
|
+
mkdirSync(context.cacheDir, { recursive: true, mode: 0o700 });
|
|
82
|
+
const config = join(context.cacheDir, "cloudflared.yml");
|
|
83
|
+
writeFileSync(
|
|
84
|
+
config,
|
|
85
|
+
"# Mostra's quick tunnels read no other configuration.\nno-autoupdate: true\n",
|
|
86
|
+
{ mode: 0o600 },
|
|
87
|
+
);
|
|
88
|
+
return runTunnel({
|
|
89
|
+
processes: context.processes,
|
|
90
|
+
log: context.log,
|
|
91
|
+
kind: "tunnel-cloudflare",
|
|
92
|
+
ownerRef: input.ownerRef,
|
|
93
|
+
command: tool.command,
|
|
94
|
+
args: [
|
|
95
|
+
...tool.args,
|
|
96
|
+
"tunnel",
|
|
97
|
+
"--config",
|
|
98
|
+
config,
|
|
99
|
+
"--no-autoupdate",
|
|
100
|
+
"--metrics",
|
|
101
|
+
"127.0.0.1:0",
|
|
102
|
+
"--management-diagnostics=false",
|
|
103
|
+
"--url",
|
|
104
|
+
input.local,
|
|
105
|
+
],
|
|
106
|
+
env: context.env,
|
|
107
|
+
read: quickTunnelReader(tool.fake),
|
|
108
|
+
timeoutMs: QUICK_TUNNEL_TIMEOUT_MS,
|
|
109
|
+
label: "A Cloudflare quick tunnel",
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Waits until a quick tunnel's hostname resolves at Cloudflare's own resolvers (1.1.1.1 and
|
|
115
|
+
* 1.0.0.1), asked directly, past this machine's cache. A new `trycloudflare.com` name takes a few
|
|
116
|
+
* seconds to appear, and a resolver that is asked too early caches the miss for many minutes
|
|
117
|
+
* (observed: the link never opened on this machine after an early probe, WP-13), so neither this
|
|
118
|
+
* machine nor a viewer's phone may ask before the name exists. Resolves `false` when the budget
|
|
119
|
+
* runs out (a network that blocks outside resolvers): the share goes on, since a viewer's
|
|
120
|
+
* resolver may still answer.
|
|
121
|
+
*/
|
|
122
|
+
export async function hostnameResolves(hostname: string, budgetMs: number): Promise<boolean> {
|
|
123
|
+
const resolver = new Resolver({ timeout: 2_000, tries: 1 });
|
|
124
|
+
resolver.setServers(["1.1.1.1", "1.0.0.1"]);
|
|
125
|
+
const until = Date.now() + budgetMs;
|
|
126
|
+
while (Date.now() < until) {
|
|
127
|
+
try {
|
|
128
|
+
const addresses = await resolver.resolve4(hostname);
|
|
129
|
+
if (addresses.length > 0) return true;
|
|
130
|
+
} catch {
|
|
131
|
+
// Not there yet, or the resolvers can't be reached: ask again shortly.
|
|
132
|
+
}
|
|
133
|
+
await new Promise((resolve) => setTimeout(resolve, 1_000));
|
|
134
|
+
}
|
|
135
|
+
return false;
|
|
136
|
+
}
|