@mostra/cli 0.7.0 → 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 CHANGED
@@ -54,7 +54,7 @@ async function start() {
54
54
  },
55
55
  stderrTty: process.stderr.isTTY === true,
56
56
  terminal: process.stdin.isTTY === true || process.stdout.isTTY === true || process.stderr.isTTY === true
57
- }) ?? await (await import("./run-DKNRTR1j.js")).run({
57
+ }) ?? await (await import("./run-3WlZ2Jos.js")).run({
58
58
  argv: process.argv.slice(2),
59
59
  env: process.env,
60
60
  cwd: process.cwd(),
package/dist/index.js CHANGED
@@ -1,3 +1,3 @@
1
- import { a as COMMANDS, i as referenceMarkdown, n as commandDefinition, r as commandHelp, t as run } from "./run-DO9Y3Dtm.js";
1
+ import { a as COMMANDS, i as referenceMarkdown, n as commandDefinition, r as commandHelp, t as run } from "./run-CuMkFuH7.js";
2
2
  import { n as exitCodeFor, t as EXIT } from "./exit-CBIf8nAU.js";
3
3
  export { COMMANDS, EXIT, commandDefinition, commandHelp, exitCodeFor, referenceMarkdown, run };
@@ -910,7 +910,7 @@ Example:
910
910
  ## mostra docs
911
911
 
912
912
  ```text
913
- Print Mostra's reference: the CLI, telemetry, and every diagnostic code's page.
913
+ Print Mostra's reference: the guide to writing artifacts, the CLI, telemetry, and every diagnostic code's page.
914
914
 
915
915
  Usage:
916
916
  mostra docs [<topic>]
@@ -0,0 +1 @@
1
+ export { t as run } from "./run-CuMkFuH7.js";
@@ -2,7 +2,7 @@ import { a as detachedEnvironment, c as durationBucket, d as buildEndpoint, f as
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";
5
+ import { extname, isAbsolute, join, resolve, win32 } from "node:path";
6
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";
@@ -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,
@@ -4106,4 +4222,4 @@ async function runRuntime(io, args, stdio) {
4106
4222
  //#endregion
4107
4223
  export { COMMANDS as a, referenceMarkdown as i, commandDefinition as n, commandHelp as r, run as t };
4108
4224
 
4109
- //# sourceMappingURL=run-DO9Y3Dtm.js.map
4225
+ //# sourceMappingURL=run-CuMkFuH7.js.map