@mostra/cli 0.7.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin.js +2 -2
- package/dist/bootstrap-Dc-SQHRF.js +422 -0
- package/dist/bootstrap-Dc-SQHRF.js.map +1 -0
- package/dist/bootstrap-aaE5wFo9.js +1 -0
- package/dist/{flush-CBN3AU9X.js → flush-C16w3JL8.js} +24 -3
- package/dist/flush-C16w3JL8.js.map +1 -0
- package/dist/index.d.ts +13 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/reference/cli.md +35 -2
- package/dist/reference/diagnostics.json +39 -3
- package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +3 -3
- package/dist/reference/telemetry.md +5 -3
- package/dist/run-Bw4_6kcW.js +1 -0
- package/dist/{run-DO9Y3Dtm.js → run-DdYT3iHQ.js} +1137 -763
- package/dist/run-DdYT3iHQ.js.map +1 -0
- package/dist/skill/SKILL.md +120 -0
- package/dist/skill/assets/examples/dashboard/index.tsx +161 -0
- package/dist/skill/assets/examples/dashboard/live.ts +25 -0
- package/dist/skill/assets/examples/dashboard/styles.css +125 -0
- package/dist/skill/assets/examples/decision/index.tsx +95 -0
- package/dist/skill/assets/examples/decision/styles.css +125 -0
- package/dist/skill/assets/examples/inbox/actions.ts +23 -0
- package/dist/skill/assets/examples/inbox/index.tsx +109 -0
- package/dist/skill/assets/examples/inbox/styles.css +125 -0
- package/dist/skill/assets/studio.css +125 -0
- package/dist/skill/references/answers.md +181 -0
- package/dist/skill/references/design.md +154 -0
- package/dist/skill/references/libraries.md +167 -0
- package/dist/skill/references/long-lived.md +148 -0
- package/dist/skill/references/mcp.md +63 -0
- package/dist/skill/references/page.md +131 -0
- package/dist/skill/references/server.md +146 -0
- package/dist/skill/references/sharing.md +72 -0
- package/dist/skill/references/verify.md +71 -0
- package/dist/telemetry/flush-main.js +1 -1
- package/package.json +12 -5
- package/src/bootstrap.ts +16 -3
- package/src/command.ts +13 -3
- package/src/commands/admin.ts +5 -4
- package/src/commands/dev.ts +60 -44
- package/src/commands/index.ts +4 -2
- package/src/commands/interaction.ts +19 -1
- package/src/commands/mcp.ts +128 -0
- package/src/detached.ts +1 -0
- package/src/docs.ts +141 -7
- package/src/help.ts +1 -1
- package/src/home.ts +5 -3
- package/src/mcp.ts +448 -0
- package/src/parse.ts +20 -6
- package/src/run.ts +24 -13
- package/src/telemetry/harness.ts +24 -0
- package/src/telemetry/index.ts +75 -48
- package/dist/bootstrap-DfEe_yPr.js +0 -113
- package/dist/bootstrap-DfEe_yPr.js.map +0 -1
- package/dist/exit-CBIf8nAU.js +0 -79
- package/dist/exit-CBIf8nAU.js.map +0 -1
- package/dist/flush-CBN3AU9X.js.map +0 -1
- package/dist/run-DKNRTR1j.js +0 -1
- package/dist/run-DO9Y3Dtm.js.map +0 -1
package/src/commands/dev.ts
CHANGED
|
@@ -54,53 +54,69 @@ export const devCommand: CommandDef = defineCommand({
|
|
|
54
54
|
example: "dev ./sidebar-review",
|
|
55
55
|
streams: true,
|
|
56
56
|
async run(context) {
|
|
57
|
-
const connection = await context.connection();
|
|
58
|
-
let sessionId: string | undefined;
|
|
59
|
-
const early: DevNotifyParams[] = [];
|
|
60
|
-
const show = (event: DevNotifyParams): void => {
|
|
61
|
-
if (event.kind === "diagnostics") {
|
|
62
|
-
for (const diagnostic of event.diagnostics ?? []) context.warn(diagnostic);
|
|
63
|
-
}
|
|
64
|
-
context.emit(event, line(event));
|
|
65
|
-
};
|
|
66
|
-
connection?.onNotification(DEV_NOTIFY, (params) => {
|
|
67
|
-
const event = params as DevNotifyParams;
|
|
68
|
-
if (sessionId === undefined) early.push(event);
|
|
69
|
-
else if (event.sessionId === sessionId) show(event);
|
|
70
|
-
});
|
|
71
|
-
const portFlag = context.flags["port"];
|
|
72
|
-
const started = await context.call(devStartMethod, {
|
|
73
|
-
source: sourceRef(arg(context, "path"), context.cwd),
|
|
74
|
-
...(typeof portFlag === "number" ? { port: portFlag } : {}),
|
|
75
|
-
});
|
|
76
|
-
sessionId = started.sessionId;
|
|
77
|
-
context.emit(
|
|
78
|
-
{ kind: "started", ...started },
|
|
79
|
-
`Development preview, not published: ${started.url}\nPress Ctrl-C to stop.\n`,
|
|
80
|
-
);
|
|
81
|
-
for (const event of early.splice(0)) if (event.sessionId === sessionId) show(event);
|
|
82
57
|
// The session lasts until Ctrl-C (or SIGTERM; Ctrl+Break on Windows), or until the instance
|
|
83
|
-
// ends it.
|
|
84
|
-
|
|
58
|
+
// ends it. The handlers are in place before anything starts or is printed: a Ctrl-C between
|
|
59
|
+
// "started" and a later handler met Node's default action and ended the process without
|
|
60
|
+
// stopping the session or printing its result (#110's CI).
|
|
85
61
|
const signals = ["SIGINT", "SIGTERM", "SIGBREAK"] as const;
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
for (const signal of signals) process.
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
62
|
+
let interrupted = false;
|
|
63
|
+
let stop: () => void = () => {
|
|
64
|
+
interrupted = true;
|
|
65
|
+
};
|
|
66
|
+
const onSignal = (): void => stop();
|
|
67
|
+
for (const signal of signals) process.once(signal, onSignal);
|
|
68
|
+
const release = (): void => {
|
|
69
|
+
for (const signal of signals) process.off(signal, onSignal);
|
|
70
|
+
};
|
|
71
|
+
try {
|
|
72
|
+
const connection = await context.connection();
|
|
73
|
+
let sessionId: string | undefined;
|
|
74
|
+
const early: DevNotifyParams[] = [];
|
|
75
|
+
const show = (event: DevNotifyParams): void => {
|
|
76
|
+
if (event.kind === "diagnostics") {
|
|
77
|
+
for (const diagnostic of event.diagnostics ?? []) context.warn(diagnostic);
|
|
78
|
+
}
|
|
79
|
+
context.emit(event, line(event));
|
|
80
|
+
};
|
|
81
|
+
connection?.onNotification(DEV_NOTIFY, (params) => {
|
|
82
|
+
const event = params as DevNotifyParams;
|
|
83
|
+
if (sessionId === undefined) early.push(event);
|
|
84
|
+
else if (event.sessionId === sessionId) show(event);
|
|
85
|
+
});
|
|
86
|
+
const portFlag = context.flags["port"];
|
|
87
|
+
const started = await context.call(devStartMethod, {
|
|
88
|
+
source: sourceRef(arg(context, "path"), context.cwd),
|
|
89
|
+
...(typeof portFlag === "number" ? { port: portFlag } : {}),
|
|
90
|
+
});
|
|
91
|
+
sessionId = started.sessionId;
|
|
92
|
+
context.emit(
|
|
93
|
+
{ kind: "started", ...started },
|
|
94
|
+
`Development preview, not published: ${started.url}\nPress Ctrl-C to stop.\n`,
|
|
98
95
|
);
|
|
96
|
+
for (const event of early.splice(0)) if (event.sessionId === sessionId) show(event);
|
|
97
|
+
const ended = interrupted
|
|
98
|
+
? "signal"
|
|
99
|
+
: await new Promise<"signal" | "closed">((done) => {
|
|
100
|
+
stop = (): void => done("signal");
|
|
101
|
+
void connection?.closed.then(() => done("closed"));
|
|
102
|
+
});
|
|
103
|
+
// A second Ctrl-C from here on ends the process, as before.
|
|
104
|
+
release();
|
|
105
|
+
if (ended === "closed") {
|
|
106
|
+
throw new RpcError(
|
|
107
|
+
createDiagnostic("MOSTRA_HOST_CONNECTION_CLOSED", {
|
|
108
|
+
message: "The instance ended the development preview (it stopped or restarted).",
|
|
109
|
+
hint: "Run mostra dev again.",
|
|
110
|
+
}),
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
await context.call(devStopMethod, { sessionId }).catch(() => undefined);
|
|
114
|
+
return {
|
|
115
|
+
result: { sessionId, stopped: "signal" },
|
|
116
|
+
human: "Stopped.\n",
|
|
117
|
+
};
|
|
118
|
+
} finally {
|
|
119
|
+
release();
|
|
99
120
|
}
|
|
100
|
-
await context.call(devStopMethod, { sessionId }).catch(() => undefined);
|
|
101
|
-
return {
|
|
102
|
-
result: { sessionId, stopped: "signal" },
|
|
103
|
-
human: "Stopped.\n",
|
|
104
|
-
};
|
|
105
121
|
},
|
|
106
122
|
});
|
package/src/commands/index.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Every command of `mostra` (D60, D140 item 13), in the order help lists them. Commands later
|
|
3
|
-
* packages own (`review export`, `export`, `
|
|
4
|
-
*
|
|
3
|
+
* packages own (`review export`, `export`, `plugin`, `term`, `run`) join this list with their
|
|
4
|
+
* packages, never as placeholders; `share` joined with WP-13 and `mcp` with WP-15.
|
|
5
5
|
*/
|
|
6
6
|
import type { CommandDef } from "../command.ts";
|
|
7
7
|
import {
|
|
@@ -34,6 +34,7 @@ import {
|
|
|
34
34
|
stateSetCommand,
|
|
35
35
|
waitCommand,
|
|
36
36
|
} from "./interaction.ts";
|
|
37
|
+
import { mcpCommand } from "./mcp.ts";
|
|
37
38
|
import { shareCommand, shareListCommand, shareStopCommand } from "./sharing.ts";
|
|
38
39
|
import { openCommand } from "./viewing.ts";
|
|
39
40
|
|
|
@@ -66,6 +67,7 @@ export const COMMANDS: readonly CommandDef[] = [
|
|
|
66
67
|
daemonInstallCommand,
|
|
67
68
|
daemonUninstallCommand,
|
|
68
69
|
hostCommand,
|
|
70
|
+
mcpCommand,
|
|
69
71
|
docsCommand,
|
|
70
72
|
doctorCommand,
|
|
71
73
|
gcCommand,
|
|
@@ -22,6 +22,24 @@ import { arg, artifactRef, flag, jsonInput, parseJson, pretty } from "./shared.t
|
|
|
22
22
|
/** The longest one `wait` request may ask for (INTERFACES §6: 2^31 − 1 ms). */
|
|
23
23
|
const MAX_WAIT_MS = 2 ** 31 - 1;
|
|
24
24
|
|
|
25
|
+
/**
|
|
26
|
+
* What `wait` prints when its condition held: the event and cursor, and for a signal its name and
|
|
27
|
+
* the payload the page or action sent (#115), which is otherwise only in `--json`.
|
|
28
|
+
*/
|
|
29
|
+
export function satisfiedLine(
|
|
30
|
+
event: { readonly type: string; readonly payload?: Readonly<Record<string, unknown>> },
|
|
31
|
+
cursor: string,
|
|
32
|
+
): string {
|
|
33
|
+
const line = `${event.type} at cursor ${cursor}`;
|
|
34
|
+
if (event.type !== "signal.raised") return `${line}\n`;
|
|
35
|
+
const name = typeof event.payload?.["name"] === "string" ? ` ${event.payload["name"]}` : "";
|
|
36
|
+
const payload =
|
|
37
|
+
event.payload !== undefined && Object.hasOwn(event.payload, "payload")
|
|
38
|
+
? `\npayload: ${JSON.stringify(event.payload["payload"])}`
|
|
39
|
+
: "";
|
|
40
|
+
return `${event.type}${name} at cursor ${cursor}${payload}\n`;
|
|
41
|
+
}
|
|
42
|
+
|
|
25
43
|
/** `mostra wait <artifact>`. */
|
|
26
44
|
export const waitCommand: CommandDef = defineCommand({
|
|
27
45
|
path: ["wait"],
|
|
@@ -67,7 +85,7 @@ export const waitCommand: CommandDef = defineCommand({
|
|
|
67
85
|
...(after !== undefined ? { after } : {}),
|
|
68
86
|
});
|
|
69
87
|
if (result.status === "satisfied") {
|
|
70
|
-
return { result, human:
|
|
88
|
+
return { result, human: satisfiedLine(result.event, result.cursor) };
|
|
71
89
|
}
|
|
72
90
|
// Waiting again is for still_waiting alone: an answer a newer instance gives that this CLI
|
|
73
91
|
// doesn't know ends the wait as a failure, so it is neither looped on nor taken for a
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `mostra mcp` (INTERFACES §12, D164): Mostra's MCP server, for any MCP client. Over stdio by
|
|
3
|
+
* default (a client starts it), or Streamable HTTP with `--http`. Its tools are `@mostra/mcp`'s;
|
|
4
|
+
* this command gives them the home's daemon, the workspace and the reference, and counts each
|
|
5
|
+
* MCP client in telemetry unless `--embedded` says a host or harness plugin started it (D148).
|
|
6
|
+
*/
|
|
7
|
+
import { resolve } from "node:path";
|
|
8
|
+
import type { McpClientInfo } from "@mostra/mcp";
|
|
9
|
+
import { defaultWorkspaceRoot } from "@mostra/mcp";
|
|
10
|
+
import { type CommandDef, defineCommand } from "../command.ts";
|
|
11
|
+
import { embeddedHome, readHomeMarks } from "../home.ts";
|
|
12
|
+
import { type DaemonInstance, serveOverHttp, serveOverStdio } from "../mcp.ts";
|
|
13
|
+
import { usage } from "../parse.ts";
|
|
14
|
+
import { mcpSessionFields } from "../telemetry/harness.ts";
|
|
15
|
+
import { cliVersion } from "../version.ts";
|
|
16
|
+
import { flag } from "./shared.ts";
|
|
17
|
+
|
|
18
|
+
/** `mostra mcp`. */
|
|
19
|
+
export const mcpCommand: CommandDef = defineCommand({
|
|
20
|
+
path: ["mcp"],
|
|
21
|
+
summary:
|
|
22
|
+
"Run Mostra's MCP server, so an MCP client can create, verify and publish artifacts, wait for answers and read results.",
|
|
23
|
+
flags: [
|
|
24
|
+
{
|
|
25
|
+
name: "http",
|
|
26
|
+
kind: "boolean",
|
|
27
|
+
summary:
|
|
28
|
+
"Serve Streamable HTTP at /mcp instead of stdio; every request needs Authorization: Bearer <token>.",
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
name: "port",
|
|
32
|
+
kind: "number",
|
|
33
|
+
value: "<port>",
|
|
34
|
+
summary: "With --http, the port; default one the system picks.",
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
name: "bind",
|
|
38
|
+
kind: "string",
|
|
39
|
+
value: "<address>",
|
|
40
|
+
summary: "With --http, listen on this address instead of 127.0.0.1.",
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
name: "url-host",
|
|
44
|
+
kind: "string",
|
|
45
|
+
value: "<name>",
|
|
46
|
+
summary: "With --http, the host name clients use; a wildcard --bind needs it.",
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
name: "workspace",
|
|
50
|
+
kind: "string",
|
|
51
|
+
value: "<dir>",
|
|
52
|
+
summary:
|
|
53
|
+
"Where relative artifact directories and new artifacts go. Default: MOSTRA_MCP_WORKSPACE, else ~/mostra-artifacts.",
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
name: "embedded",
|
|
57
|
+
kind: "boolean",
|
|
58
|
+
summary:
|
|
59
|
+
"This server runs on someone's behalf (a harness plugin or another host started it), so it sends no telemetry.",
|
|
60
|
+
},
|
|
61
|
+
],
|
|
62
|
+
output: { type: "the MCP protocol on stdin and stdout, or over HTTP", topic: "cli" },
|
|
63
|
+
exits: [],
|
|
64
|
+
example: "mcp",
|
|
65
|
+
readsStdin: (flags) => flags["http"] !== true,
|
|
66
|
+
quiet: (flags) => flags["embedded"] === true,
|
|
67
|
+
async run(context) {
|
|
68
|
+
const http = context.flags["http"] === true;
|
|
69
|
+
const port = context.flags["port"];
|
|
70
|
+
const bind = flag(context, "bind");
|
|
71
|
+
const urlHost = flag(context, "url-host");
|
|
72
|
+
if (!http && (port !== undefined || bind !== undefined || urlHost !== undefined)) {
|
|
73
|
+
throw usage("--port, --bind and --url-host go with --http.");
|
|
74
|
+
}
|
|
75
|
+
if (typeof port === "number" && (!Number.isInteger(port) || port < 0 || port > 65_535)) {
|
|
76
|
+
throw usage("--port takes a port number from 0 to 65535.");
|
|
77
|
+
}
|
|
78
|
+
const given = flag(context, "workspace") ?? context.env["MOSTRA_MCP_WORKSPACE"];
|
|
79
|
+
const workspace =
|
|
80
|
+
given !== undefined && given !== "" ? resolve(context.cwd, given) : defaultWorkspaceRoot();
|
|
81
|
+
const counted = new Set<string>();
|
|
82
|
+
let reached: DaemonInstance | undefined;
|
|
83
|
+
const options = {
|
|
84
|
+
home: context.home,
|
|
85
|
+
env: context.env,
|
|
86
|
+
workspace,
|
|
87
|
+
version: cliVersion(),
|
|
88
|
+
log: context.log,
|
|
89
|
+
onClient(client: McpClientInfo, instance: DaemonInstance) {
|
|
90
|
+
// Each client once per process (D140 item 8), and queued at once, since a harness stops
|
|
91
|
+
// its server within a second, before any end of the command (D164 item 4). Connecting
|
|
92
|
+
// starts nothing: a host-spawned instance always marks its home (D140 item 4), which
|
|
93
|
+
// the mark read now tells, as does a session a call already opened.
|
|
94
|
+
reached = instance;
|
|
95
|
+
const fields = mcpSessionFields(client);
|
|
96
|
+
const key = `${fields.client}@${fields.clientVersion ?? ""}`;
|
|
97
|
+
if (counted.has(key)) return;
|
|
98
|
+
counted.add(key);
|
|
99
|
+
context.record({ event: "mcp.session", fields });
|
|
100
|
+
context.checkpoint(instance.hostInstance() || embeddedHome(readHomeMarks(context.home)));
|
|
101
|
+
},
|
|
102
|
+
};
|
|
103
|
+
const done = { result: undefined, raw: true as const };
|
|
104
|
+
if (!http) {
|
|
105
|
+
await serveOverStdio(options);
|
|
106
|
+
return { ...done, hostInstance: reached?.hostInstance() === true };
|
|
107
|
+
}
|
|
108
|
+
await serveOverHttp({
|
|
109
|
+
...options,
|
|
110
|
+
port: typeof port === "number" ? port : 0,
|
|
111
|
+
...(bind !== undefined ? { bind } : {}),
|
|
112
|
+
...(urlHost !== undefined ? { urlHost } : {}),
|
|
113
|
+
onListening({ url, token, generated }) {
|
|
114
|
+
// The token is a secret: it goes to stderr once, never to stdout, which a supervisor
|
|
115
|
+
// may keep in a log (D164 item 3, Opus review of WP-15, finding 8). A program that needs
|
|
116
|
+
// the token sets MOSTRA_MCP_TOKEN; `listening` gives it the URL.
|
|
117
|
+
if (context.json) context.emit({ kind: "listening", url });
|
|
118
|
+
else context.stderr(`Mostra's MCP server is listening at ${url}\n`);
|
|
119
|
+
context.stderr(
|
|
120
|
+
generated
|
|
121
|
+
? `Send Authorization: Bearer ${token} with every request (set MOSTRA_MCP_TOKEN to choose the token).\n`
|
|
122
|
+
: "Send Authorization: Bearer <MOSTRA_MCP_TOKEN> with every request.\n",
|
|
123
|
+
);
|
|
124
|
+
},
|
|
125
|
+
});
|
|
126
|
+
return { ...done, hostInstance: reached?.hostInstance() === true };
|
|
127
|
+
},
|
|
128
|
+
});
|
package/src/detached.ts
CHANGED
package/src/docs.ts
CHANGED
|
@@ -1,24 +1,30 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* `mostra docs` (D140 item 17): the reference that ships with the CLI, by stable slug. The
|
|
3
3
|
* diagnostic pages are keyed by code (`mostra docs MOSTRA_DEP_MISSING`, as hints say), beside the
|
|
4
|
-
* CLI reference and the telemetry page.
|
|
5
|
-
*
|
|
4
|
+
* CLI reference and the telemetry page. The Agent Skill (`skills/mostra/`, WP-14) is in it too, as
|
|
5
|
+
* `guide` and `guide/<name>`, so an agent whose harness has no Skill reads the same text through
|
|
6
|
+
* the CLI. This index is the one source WP-15's `docs_search` and WP-26's site read.
|
|
6
7
|
*/
|
|
7
8
|
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
8
|
-
import { join } from "node:path";
|
|
9
|
+
import { extname, join } from "node:path";
|
|
9
10
|
import { DEFAULT_DOCS_BASE } from "@mostra/protocol";
|
|
10
11
|
import { fromSource, packageRoot } from "./version.ts";
|
|
11
12
|
|
|
12
13
|
/** One topic of the reference. */
|
|
13
14
|
export interface DocsTopic {
|
|
14
|
-
/** Its stable slug: `cli`, `telemetry`,
|
|
15
|
+
/** Its stable slug: `cli`, `telemetry`, a diagnostic code, `guide` or `guide/<name>`. */
|
|
15
16
|
readonly topic: string;
|
|
16
17
|
/** Its title, from the page's first heading. */
|
|
17
18
|
readonly title: string;
|
|
18
19
|
/** Where the docs site serves it. */
|
|
19
20
|
readonly url: string;
|
|
20
|
-
/** Its Markdown file. */
|
|
21
|
+
/** Its Markdown file, or a guide topic's first file. */
|
|
21
22
|
readonly file: string;
|
|
23
|
+
/**
|
|
24
|
+
* A guide topic that isn't one Markdown page (a stylesheet, an example): its files, relative to
|
|
25
|
+
* the Skill's `assets/`, each shown as code.
|
|
26
|
+
*/
|
|
27
|
+
readonly files?: readonly string[];
|
|
22
28
|
}
|
|
23
29
|
|
|
24
30
|
/** Where the reference is: bundled in the build (`dist/reference`), or the repository's. */
|
|
@@ -29,6 +35,14 @@ export function referenceDir(): string {
|
|
|
29
35
|
: join(packageRoot(), "..", "..", "docs", "reference");
|
|
30
36
|
}
|
|
31
37
|
|
|
38
|
+
/** Where the Agent Skill is: bundled in the build (`dist/skill`), or the repository's. */
|
|
39
|
+
export function skillDir(): string {
|
|
40
|
+
const bundled = join(packageRoot(), "dist", "skill");
|
|
41
|
+
return !fromSource() && existsSync(bundled)
|
|
42
|
+
? bundled
|
|
43
|
+
: join(packageRoot(), "..", "..", "skills", "mostra");
|
|
44
|
+
}
|
|
45
|
+
|
|
32
46
|
function titleOf(file: string): string {
|
|
33
47
|
const first = readFileSync(file, "utf8")
|
|
34
48
|
.split("\n")
|
|
@@ -56,12 +70,124 @@ export function docsIndex(dir: string = referenceDir()): DocsTopic[] {
|
|
|
56
70
|
const file = join(errorsDir, name);
|
|
57
71
|
return { topic: code, title: titleOf(file), url: `${base}/errors/${code}`, file };
|
|
58
72
|
});
|
|
59
|
-
return [...pages, ...errors];
|
|
73
|
+
return [...pages, ...guideTopics(skillDir(), base), ...errors];
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const byName = (a: { name: string }, b: { name: string }): number => (a.name < b.name ? -1 : 1);
|
|
77
|
+
|
|
78
|
+
/** Every file below `root`'s `prefix`, relative to `root`, sorted. */
|
|
79
|
+
function filesBelow(root: string, prefix: string): string[] {
|
|
80
|
+
return readdirSync(join(root, prefix), { withFileTypes: true })
|
|
81
|
+
.sort(byName)
|
|
82
|
+
.flatMap((entry) => {
|
|
83
|
+
const path = `${prefix}/${entry.name}`;
|
|
84
|
+
return entry.isDirectory() ? filesBelow(root, path) : [path];
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* The Skill as topics: `guide` (its SKILL.md), `guide/<name>` for each reference,
|
|
90
|
+
* `guide/<file>` for each asset (the baseline stylesheet), and `guide/examples/<name>` for each
|
|
91
|
+
* example, every file of it.
|
|
92
|
+
*/
|
|
93
|
+
export function guideTopics(dir: string, base: string): DocsTopic[] {
|
|
94
|
+
const skill = join(dir, "SKILL.md");
|
|
95
|
+
if (!existsSync(skill)) return [];
|
|
96
|
+
const topics: DocsTopic[] = [
|
|
97
|
+
{ topic: "guide", title: "Using Mostra", url: `${base}/guide`, file: skill },
|
|
98
|
+
];
|
|
99
|
+
const references = join(dir, "references");
|
|
100
|
+
if (existsSync(references)) {
|
|
101
|
+
for (const name of readdirSync(references)
|
|
102
|
+
.filter((entry) => entry.endsWith(".md"))
|
|
103
|
+
.sort()) {
|
|
104
|
+
const file = join(references, name);
|
|
105
|
+
const slug = name.slice(0, -3);
|
|
106
|
+
topics.push({
|
|
107
|
+
topic: `guide/${slug}`,
|
|
108
|
+
title: titleOf(file),
|
|
109
|
+
url: `${base}/guide/${slug}`,
|
|
110
|
+
file,
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
const assets = join(dir, "assets");
|
|
115
|
+
if (!existsSync(assets)) return topics;
|
|
116
|
+
for (const entry of readdirSync(assets, { withFileTypes: true }).sort(byName)) {
|
|
117
|
+
if (!entry.isFile()) continue;
|
|
118
|
+
topics.push({
|
|
119
|
+
topic: `guide/${entry.name}`,
|
|
120
|
+
title: entry.name,
|
|
121
|
+
url: `${base}/guide/${entry.name}`,
|
|
122
|
+
file: join(assets, entry.name),
|
|
123
|
+
files: [entry.name],
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
const examples = join(assets, "examples");
|
|
127
|
+
if (!existsSync(examples)) return topics;
|
|
128
|
+
for (const entry of readdirSync(examples, { withFileTypes: true }).sort(byName)) {
|
|
129
|
+
if (!entry.isDirectory()) continue;
|
|
130
|
+
const files = filesBelow(assets, `examples/${entry.name}`);
|
|
131
|
+
if (files.length === 0) continue;
|
|
132
|
+
topics.push({
|
|
133
|
+
topic: `guide/examples/${entry.name}`,
|
|
134
|
+
title: `Example: ${entry.name}`,
|
|
135
|
+
url: `${base}/guide/examples/${entry.name}`,
|
|
136
|
+
file: join(assets, files[0] as string),
|
|
137
|
+
files,
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
return topics;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
const FENCE_LANGUAGES: Readonly<Record<string, string>> = {
|
|
144
|
+
".css": "css",
|
|
145
|
+
".json": "json",
|
|
146
|
+
".md": "md",
|
|
147
|
+
".mdx": "mdx",
|
|
148
|
+
".ts": "ts",
|
|
149
|
+
".tsx": "tsx",
|
|
150
|
+
};
|
|
151
|
+
|
|
152
|
+
/** How the guide's relative links read through the CLI, before each of its pages. */
|
|
153
|
+
export const GUIDE_LINKS: string =
|
|
154
|
+
"> 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>`.";
|
|
155
|
+
|
|
156
|
+
/** The same for the guide read through `mostra mcp` (D164): topics of `docs_search`, or resources. */
|
|
157
|
+
export const MCP_GUIDE_LINKS: string =
|
|
158
|
+
"> 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`).";
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* A topic's Markdown. A guide page loses its frontmatter and says how its links read (through the
|
|
162
|
+
* CLI by default, or `links`); a guide topic made of files shows each one as code under its path.
|
|
163
|
+
*/
|
|
164
|
+
export function topicMarkdown(
|
|
165
|
+
topic: DocsTopic,
|
|
166
|
+
dir: string = skillDir(),
|
|
167
|
+
links: string = GUIDE_LINKS,
|
|
168
|
+
): string {
|
|
169
|
+
if (topic.files !== undefined) {
|
|
170
|
+
const parts = topic.files.map((path) => {
|
|
171
|
+
const text = readFileSync(join(dir, "assets", path), "utf8");
|
|
172
|
+
const fence = text.includes("```") ? "````" : "```";
|
|
173
|
+
const body = text.endsWith("\n") ? text : `${text}\n`;
|
|
174
|
+
return `## \`${path}\`\n\n${fence}${FENCE_LANGUAGES[extname(path)] ?? ""}\n${body}${fence}\n`;
|
|
175
|
+
});
|
|
176
|
+
return [`# ${topic.title}`, "", links, "", ...parts].join("\n");
|
|
177
|
+
}
|
|
178
|
+
const text = readFileSync(topic.file, "utf8");
|
|
179
|
+
if (topic.topic !== "guide" && !topic.topic.startsWith("guide/")) return text;
|
|
180
|
+
return [links, "", text.replace(/^---\n[\s\S]*?\n---\n+/, "")].join("\n");
|
|
60
181
|
}
|
|
61
182
|
|
|
62
183
|
/** The index as Markdown: what `mostra docs` prints without a topic. */
|
|
63
184
|
export function indexMarkdown(topics: readonly DocsTopic[]): string {
|
|
64
|
-
const pages = topics.filter(
|
|
185
|
+
const pages = topics.filter(
|
|
186
|
+
(topic) => !topic.topic.startsWith("MOSTRA_") && !topic.topic.startsWith("guide"),
|
|
187
|
+
);
|
|
188
|
+
const guide = topics.filter(
|
|
189
|
+
(topic) => topic.topic === "guide" || topic.topic.startsWith("guide/"),
|
|
190
|
+
);
|
|
65
191
|
const codes = topics.filter((topic) => topic.topic.startsWith("MOSTRA_"));
|
|
66
192
|
return [
|
|
67
193
|
"# Mostra reference",
|
|
@@ -70,6 +196,14 @@ export function indexMarkdown(topics: readonly DocsTopic[]): string {
|
|
|
70
196
|
"",
|
|
71
197
|
...pages.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
|
|
72
198
|
"",
|
|
199
|
+
...(guide.length > 0
|
|
200
|
+
? [
|
|
201
|
+
"## Writing artifacts",
|
|
202
|
+
"",
|
|
203
|
+
...guide.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
|
|
204
|
+
"",
|
|
205
|
+
]
|
|
206
|
+
: []),
|
|
73
207
|
"## Diagnostic codes",
|
|
74
208
|
"",
|
|
75
209
|
...codes.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
|
package/src/help.ts
CHANGED
|
@@ -41,7 +41,7 @@ function flagLine(flag: FlagDef): string {
|
|
|
41
41
|
}
|
|
42
42
|
|
|
43
43
|
/** Commands that run until their connection or Ctrl-C ends them: `--timeout` doesn't bound them. */
|
|
44
|
-
export const UNBOUNDED: ReadonlySet<string> = new Set(["host", "dev"]);
|
|
44
|
+
export const UNBOUNDED: ReadonlySet<string> = new Set(["host", "dev", "mcp"]);
|
|
45
45
|
|
|
46
46
|
/**
|
|
47
47
|
* The global flags a command doesn't define again (`wait --timeout` is the wait's own); a command
|
package/src/home.ts
CHANGED
|
@@ -89,9 +89,11 @@ export interface RuntimeLocation {
|
|
|
89
89
|
|
|
90
90
|
/**
|
|
91
91
|
* The runtime the CLI starts (D85, RT-01), found as the SDK finds it: `MOSTRA_BUNDLE`,
|
|
92
|
-
* `MOSTRA_RUNTIME_BIN`, the runtime bundle this CLI sits in,
|
|
93
|
-
* runtime beside it. The bootstrap (`bootstrap.ts`) has already moved
|
|
94
|
-
* into its pinned bundle, so this
|
|
92
|
+
* `MOSTRA_RUNTIME_BIN`, the runtime bundle this CLI sits in, its release's pinned bundle, or a
|
|
93
|
+
* development checkout's built runtime beside it. The bootstrap (`bootstrap.ts`) has already moved
|
|
94
|
+
* a CLI installed from npm into its pinned bundle, so this downloads nothing, except under
|
|
95
|
+
* `mostra mcp`, which serves before the bundle is there and installs it itself (D164 item 7), so
|
|
96
|
+
* this finds it installed. Throws the SDK's diagnostic when there is none.
|
|
95
97
|
*/
|
|
96
98
|
export async function locateRuntime(env: Environment): Promise<RuntimeLocation> {
|
|
97
99
|
const runtime = await resolveRuntime({ env });
|