@mostra/runtime 0.14.0 → 0.15.1

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 (61) hide show
  1. package/dist/bin.js +1 -1
  2. package/dist/child-protocol-CPXR6pMu.js +13 -0
  3. package/dist/child-protocol-CPXR6pMu.js.map +1 -0
  4. package/dist/index.d.ts.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/{instance-CFTw3g-c.js → instance-Bw1BxctF.js} +2581 -189
  7. package/dist/instance-Bw1BxctF.js.map +1 -0
  8. package/dist/plugins/child/host.d.ts +1 -0
  9. package/dist/plugins/child/host.js +165 -0
  10. package/dist/plugins/child/host.js.map +1 -0
  11. package/dist/reference/cli.md +147 -5
  12. package/dist/reference/diagnostics.json +234 -0
  13. package/dist/reference/errors/MOSTRA_LICENSE_ACCEPT_INVALID.md +23 -0
  14. package/dist/reference/errors/MOSTRA_LICENSE_MISMATCH.md +23 -0
  15. package/dist/reference/errors/MOSTRA_LICENSE_UNACCEPTED.md +23 -0
  16. package/dist/reference/errors/MOSTRA_LICENSE_UNDECLARED.md +23 -0
  17. package/dist/reference/errors/MOSTRA_PACK_ADDRESS_INVALID.md +23 -0
  18. package/dist/reference/errors/MOSTRA_PACK_CSS_UNIMPORTED.md +23 -0
  19. package/dist/reference/errors/MOSTRA_PACK_FETCH_FAILED.md +23 -0
  20. package/dist/reference/errors/MOSTRA_PACK_FILE_EXISTS.md +23 -0
  21. package/dist/reference/errors/MOSTRA_PACK_ITEM_INVALID.md +23 -0
  22. package/dist/reference/errors/MOSTRA_PACK_ITEM_NOT_FOUND.md +23 -0
  23. package/dist/reference/errors/MOSTRA_PACK_NOT_APPLIED.md +23 -0
  24. package/dist/reference/errors/MOSTRA_PACK_OFFLINE.md +23 -0
  25. package/dist/reference/errors/MOSTRA_PACK_TARGET_INVALID.md +23 -0
  26. package/dist/reference/errors/MOSTRA_PLUGIN_CONFLICT.md +23 -0
  27. package/dist/reference/errors/MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED.md +23 -0
  28. package/dist/reference/errors/MOSTRA_PLUGIN_ENTRY_INVALID.md +23 -0
  29. package/dist/reference/errors/MOSTRA_PLUGIN_EXPORTER_UNKNOWN.md +23 -0
  30. package/dist/reference/errors/MOSTRA_PLUGIN_FAILED.md +23 -0
  31. package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_INVALID.md +23 -0
  32. package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_WARNING.md +23 -0
  33. package/dist/reference/errors/MOSTRA_PLUGIN_NOT_A_PLUGIN.md +23 -0
  34. package/dist/reference/errors/MOSTRA_PLUGIN_NOT_INSTALLED.md +23 -0
  35. package/dist/reference/errors/MOSTRA_PLUGIN_OPTIONS_INVALID.md +23 -0
  36. package/dist/reference/errors/MOSTRA_PLUGIN_PLATFORM_UNSUPPORTED.md +23 -0
  37. package/dist/reference/errors/MOSTRA_PLUGIN_SCOPE_INVALID.md +23 -0
  38. package/dist/reference/errors/MOSTRA_PLUGIN_SHADOWED.md +23 -0
  39. package/dist/skill/SKILL.md +4 -2
  40. package/dist/skill/references/mcp.md +2 -2
  41. package/dist/skill/references/plugins.md +51 -0
  42. package/package.json +10 -7
  43. package/src/deps/index.ts +407 -90
  44. package/src/deps/installer.ts +53 -10
  45. package/src/deps/lock.ts +74 -2
  46. package/src/home/settings.ts +3 -0
  47. package/src/instance/index.ts +57 -0
  48. package/src/packs/index.ts +7 -0
  49. package/src/packs/methods.ts +49 -0
  50. package/src/packs/packs.ts +706 -0
  51. package/src/packs/read.ts +759 -0
  52. package/src/platform/index.ts +1 -0
  53. package/src/platform/shell.ts +14 -0
  54. package/src/plugins/child/host.ts +231 -0
  55. package/src/plugins/child-protocol.ts +68 -0
  56. package/src/plugins/index.ts +7 -0
  57. package/src/plugins/location.ts +109 -0
  58. package/src/plugins/methods.ts +269 -0
  59. package/src/plugins/plugins.ts +1396 -0
  60. package/src/publish/publisher.ts +71 -3
  61. package/dist/instance-CFTw3g-c.js.map +0 -1
@@ -0,0 +1 @@
1
+ export {}
@@ -0,0 +1,165 @@
1
+ import { t as connectToSupervisor } from "../../child-BmNZ4a70.js";
2
+ import "../../child-protocol-CPXR6pMu.js";
3
+ import { isAbsolute, join, relative, sep } from "node:path";
4
+ import { pathToFileURL } from "node:url";
5
+ import { checkArtifactPath } from "@mostra/protocol";
6
+ import { readFile, readdir, realpath } from "node:fs/promises";
7
+ import { stampServed } from "@mostra/protocol/plugin";
8
+ import * as z from "zod";
9
+ //#region src/plugins/child/host.ts
10
+ /**
11
+ * The plugin child's entry (`dist/plugins/child/host.js`, D30): the process that loads a plugin's
12
+ * Node.js modules, so the supervisor never runs plugin code (RT-02). The supervisor starts one per
13
+ * task through the process manager, in the plugin's package directory with the artifact
14
+ * environment, and stops it after the answer. It exits with its supervisor.
15
+ *
16
+ * - `plugin/inspect` loads entries and answers what each exports: the stamp `define*` put on it,
17
+ * and its ID, so the supervisor checks contracts without trusting the manifest alone.
18
+ * - `plugin/export` loads an exporter, checks it is one this runtime serves and that the options
19
+ * fit its schema, then runs it on a version's files and answers the files it returned.
20
+ */
21
+ /** A module's export, by name (`default` for the default export). */
22
+ async function load(file, name) {
23
+ return (await import(pathToFileURL(file).href))[name];
24
+ }
25
+ async function inspect(request) {
26
+ const answers = [];
27
+ for (const entry of request.entries) try {
28
+ const value = await load(entry.file, entry.export);
29
+ if (typeof value !== "object" || value === null) {
30
+ answers.push({
31
+ ok: false,
32
+ error: `exports ${entry.export === "default" ? "no default" : `no ${entry.export}`} definition (found ${value === null ? "null" : typeof value})`
33
+ });
34
+ continue;
35
+ }
36
+ const record = value;
37
+ answers.push({
38
+ ok: true,
39
+ stamp: record["contract"] ?? null,
40
+ ...typeof record["id"] === "string" ? { id: record["id"] } : {},
41
+ ...Array.isArray(record["path"]) ? { path: record["path"].map((word) => String(word)) } : {},
42
+ functions: Object.keys(record).filter((key) => typeof record[key] === "function")
43
+ });
44
+ } catch (error) {
45
+ answers.push({
46
+ ok: false,
47
+ error: error instanceof Error ? error.message : String(error)
48
+ });
49
+ }
50
+ return answers;
51
+ }
52
+ /** `inner` is `outer` or inside it (both real paths), judged by whole segments. */
53
+ function isInside(outer, inner) {
54
+ const from = relative(outer, inner);
55
+ return from === "" || from !== ".." && !from.startsWith(`..${sep}`) && !isAbsolute(from);
56
+ }
57
+ /** Whether a path inside the version names its server code (case-folded: some systems fold). */
58
+ const isServer = (relativePath) => (relativePath.split(/[/\\]/)[0] ?? "").toLowerCase() === "server";
59
+ /**
60
+ * A version's files, read-only, as the exporter contract's `FileTree`: every file but its server
61
+ * code. A path is judged after it is normalized and its links resolved, so `./server/x`,
62
+ * `client/../server/x` and `SERVER/x` name server code too.
63
+ */
64
+ function tree(root) {
65
+ const file = async (path) => {
66
+ const check = checkArtifactPath(path);
67
+ if (!check.ok) throw new Error(`${path} isn't a file of the version.`);
68
+ if (isServer(check.path)) throw new Error("Server code isn't part of an export's input.");
69
+ const realRoot = await realpath(root);
70
+ const full = await realpath(join(root, ...check.path.split("/")));
71
+ if (!isInside(realRoot, full)) throw new Error(`${path} isn't a file of the version.`);
72
+ if (isServer(relative(realRoot, full))) throw new Error("Server code isn't part of an export's input.");
73
+ return full;
74
+ };
75
+ const walk = async (dir, prefix) => {
76
+ const found = [];
77
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
78
+ const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
79
+ if (prefix === "" && isServer(entry.name)) continue;
80
+ if (entry.isDirectory()) found.push(...await walk(join(dir, entry.name), path));
81
+ else if (entry.isFile()) found.push(path);
82
+ }
83
+ return found;
84
+ };
85
+ return {
86
+ list: async () => (await walk(root, "")).sort(),
87
+ read: async (path) => new Uint8Array(await readFile(await file(path))),
88
+ readText: async (path) => readFile(await file(path), "utf8")
89
+ };
90
+ }
91
+ /** Why an options schema refuses `options`, in one line. */
92
+ function optionProblems(schema, options) {
93
+ const parsed = z.fromJSONSchema(schema).safeParse(options);
94
+ if (parsed.success) return "";
95
+ return parsed.error.issues.slice(0, 10).map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "options"}: ${issue.message}`).join("; ");
96
+ }
97
+ async function runExport(request) {
98
+ const value = await load(request.file, request.export);
99
+ const refuse = (code, message) => ({ refused: {
100
+ code,
101
+ message
102
+ } });
103
+ if (typeof value !== "object" || value === null) return refuse("MOSTRA_PLUGIN_ENTRY_INVALID", "its entry exports no exporter definition");
104
+ const exporter = value;
105
+ const stamp = exporter.contract;
106
+ if (stamp?.name !== "exporter" || typeof exporter.export !== "function") return refuse("MOSTRA_PLUGIN_ENTRY_INVALID", "its entry exports no stamped exporter definition");
107
+ if (!stampServed(stamp, "exporter", request.implemented)) return refuse("MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED", `it was built with @mostra/contract-exporter ${String(stamp.version)}; this Mostra serves ${request.implemented.join(", ")}`);
108
+ if (exporter.id !== request.id) return refuse("MOSTRA_PLUGIN_ENTRY_INVALID", `its definition is "${String(exporter.id)}", not "${request.id}" as the manifest says`);
109
+ const layout = exporter.output?.layout === "file" ? "file" : "directory";
110
+ const extension = typeof exporter.output?.extension === "string" ? exporter.output.extension : void 0;
111
+ if (exporter.options === void 0) {
112
+ if (Object.keys(request.options).length > 0) return refuse("MOSTRA_PLUGIN_OPTIONS_INVALID", `it takes no options, and was given ${Object.keys(request.options).join(", ")}`);
113
+ } else {
114
+ let problems;
115
+ try {
116
+ problems = optionProblems(exporter.options, request.options);
117
+ } catch (error) {
118
+ return refuse("MOSTRA_PLUGIN_ENTRY_INVALID", `its options aren't a JSON Schema Mostra reads (${error instanceof Error ? error.message : String(error)})`);
119
+ }
120
+ if (problems !== "") return refuse("MOSTRA_PLUGIN_OPTIONS_INVALID", problems);
121
+ }
122
+ const controller = new AbortController();
123
+ const lines = [];
124
+ const result = await exporter.export.call(exporter, {
125
+ version: request.version,
126
+ files: tree(request.versionDir),
127
+ options: request.options
128
+ }, {
129
+ signal: controller.signal,
130
+ log: (message) => {
131
+ if (lines.length < 1e3) lines.push(String(message).slice(0, 4e3));
132
+ },
133
+ mostraVersion: request.mostraVersion
134
+ });
135
+ return {
136
+ files: (result?.files ?? []).map((file) => {
137
+ if (typeof file.path !== "string") throw new Error("An exported file has no path.");
138
+ if (typeof file.content === "string") return {
139
+ path: file.path,
140
+ text: file.content
141
+ };
142
+ if (file.content instanceof Uint8Array) return {
143
+ path: file.path,
144
+ base64: Buffer.from(file.content).toString("base64")
145
+ };
146
+ throw new Error(`${file.path}'s content is neither text nor bytes.`);
147
+ }),
148
+ ...typeof result?.entry === "string" ? { entry: result.entry } : {},
149
+ output: {
150
+ layout,
151
+ ...extension !== void 0 ? { extension } : {}
152
+ },
153
+ findings: Array.isArray(result?.findings) ? result.findings : [],
154
+ log: lines
155
+ };
156
+ }
157
+ connectToSupervisor({ onRequest: async (method, params) => {
158
+ if (method === "plugin/inspect") return inspect(params);
159
+ if (method === "plugin/export") return runExport(params);
160
+ throw new Error(`The plugin child doesn't serve ${method}.`);
161
+ } });
162
+ //#endregion
163
+ export {};
164
+
165
+ //# sourceMappingURL=host.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host.js","names":[],"sources":["../../../src/plugins/child/host.ts"],"sourcesContent":["/**\n * The plugin child's entry (`dist/plugins/child/host.js`, D30): the process that loads a plugin's\n * Node.js modules, so the supervisor never runs plugin code (RT-02). The supervisor starts one per\n * task through the process manager, in the plugin's package directory with the artifact\n * environment, and stops it after the answer. It exits with its supervisor.\n *\n * - `plugin/inspect` loads entries and answers what each exports: the stamp `define*` put on it,\n * and its ID, so the supervisor checks contracts without trusting the manifest alone.\n * - `plugin/export` loads an exporter, checks it is one this runtime serves and that the options\n * fit its schema, then runs it on a version's files and answers the files it returned.\n */\nimport { readdir, readFile, realpath } from \"node:fs/promises\";\nimport { isAbsolute, join, relative, sep } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { checkArtifactPath } from \"@mostra/protocol\";\nimport { stampServed } from \"@mostra/protocol/plugin\";\nimport * as z from \"zod\";\nimport { connectToSupervisor } from \"../../processes/index.ts\";\nimport {\n EXPORT_METHOD,\n type ExportRequest,\n type ExportResponse,\n INSPECT_METHOD,\n type InspectedEntry,\n type InspectRequest,\n} from \"../child-protocol.ts\";\n\n/** A module's export, by name (`default` for the default export). */\nasync function load(file: string, name: string): Promise<unknown> {\n const module = (await import(pathToFileURL(file).href)) as Record<string, unknown>;\n return module[name];\n}\n\nasync function inspect(request: InspectRequest): Promise<InspectedEntry[]> {\n const answers: InspectedEntry[] = [];\n for (const entry of request.entries) {\n try {\n const value = await load(entry.file, entry.export);\n if (typeof value !== \"object\" || value === null) {\n answers.push({\n ok: false,\n error: `exports ${entry.export === \"default\" ? \"no default\" : `no ${entry.export}`} definition (found ${value === null ? \"null\" : typeof value})`,\n });\n continue;\n }\n const record = value as Record<string, unknown>;\n answers.push({\n ok: true,\n stamp: record[\"contract\"] ?? null,\n ...(typeof record[\"id\"] === \"string\" ? { id: record[\"id\"] } : {}),\n ...(Array.isArray(record[\"path\"])\n ? { path: (record[\"path\"] as unknown[]).map((word) => String(word)) }\n : {}),\n functions: Object.keys(record).filter((key) => typeof record[key] === \"function\"),\n });\n } catch (error) {\n answers.push({ ok: false, error: error instanceof Error ? error.message : String(error) });\n }\n }\n return answers;\n}\n\n/** `inner` is `outer` or inside it (both real paths), judged by whole segments. */\nfunction isInside(outer: string, inner: string): boolean {\n const from = relative(outer, inner);\n return from === \"\" || (from !== \"..\" && !from.startsWith(`..${sep}`) && !isAbsolute(from));\n}\n\n/** Whether a path inside the version names its server code (case-folded: some systems fold). */\nconst isServer = (relativePath: string): boolean =>\n (relativePath.split(/[/\\\\]/)[0] ?? \"\").toLowerCase() === \"server\";\n\n/**\n * A version's files, read-only, as the exporter contract's `FileTree`: every file but its server\n * code. A path is judged after it is normalized and its links resolved, so `./server/x`,\n * `client/../server/x` and `SERVER/x` name server code too.\n */\nfunction tree(root: string) {\n const file = async (path: string): Promise<string> => {\n const check = checkArtifactPath(path);\n if (!check.ok) throw new Error(`${path} isn't a file of the version.`);\n if (isServer(check.path)) throw new Error(\"Server code isn't part of an export's input.\");\n const realRoot = await realpath(root);\n const full = await realpath(join(root, ...check.path.split(\"/\")));\n if (!isInside(realRoot, full)) throw new Error(`${path} isn't a file of the version.`);\n if (isServer(relative(realRoot, full))) {\n throw new Error(\"Server code isn't part of an export's input.\");\n }\n return full;\n };\n const walk = async (dir: string, prefix: string): Promise<string[]> => {\n const found: string[] = [];\n for (const entry of await readdir(dir, { withFileTypes: true })) {\n const path = prefix === \"\" ? entry.name : `${prefix}/${entry.name}`;\n if (prefix === \"\" && isServer(entry.name)) continue;\n if (entry.isDirectory()) found.push(...(await walk(join(dir, entry.name), path)));\n else if (entry.isFile()) found.push(path);\n }\n return found;\n };\n return {\n list: async () => (await walk(root, \"\")).sort(),\n read: async (path: string) => new Uint8Array(await readFile(await file(path))),\n readText: async (path: string) => readFile(await file(path), \"utf8\"),\n };\n}\n\n/** Why an options schema refuses `options`, in one line. */\nfunction optionProblems(schema: unknown, options: Readonly<Record<string, unknown>>): string {\n const parsed = z\n .fromJSONSchema(schema as Parameters<typeof z.fromJSONSchema>[0])\n .safeParse(options);\n if (parsed.success) return \"\";\n return parsed.error.issues\n .slice(0, 10)\n .map((issue) => `${issue.path.length > 0 ? issue.path.join(\".\") : \"options\"}: ${issue.message}`)\n .join(\"; \");\n}\n\nasync function runExport(request: ExportRequest): Promise<ExportResponse> {\n const value = await load(request.file, request.export);\n const refuse = (\n code:\n | \"MOSTRA_PLUGIN_ENTRY_INVALID\"\n | \"MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED\"\n | \"MOSTRA_PLUGIN_OPTIONS_INVALID\",\n message: string,\n ): ExportResponse => ({ refused: { code, message } });\n if (typeof value !== \"object\" || value === null) {\n return refuse(\"MOSTRA_PLUGIN_ENTRY_INVALID\", \"its entry exports no exporter definition\");\n }\n const exporter = value as {\n contract?: unknown;\n id?: unknown;\n output?: { layout?: unknown; extension?: unknown };\n options?: unknown;\n export?: unknown;\n };\n const stamp = exporter.contract as { name?: unknown; version?: unknown } | undefined;\n if (stamp?.name !== \"exporter\" || typeof exporter.export !== \"function\") {\n return refuse(\n \"MOSTRA_PLUGIN_ENTRY_INVALID\",\n \"its entry exports no stamped exporter definition\",\n );\n }\n if (!stampServed(stamp, \"exporter\", request.implemented)) {\n return refuse(\n \"MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED\",\n `it was built with @mostra/contract-exporter ${String(stamp.version)}; this Mostra serves ${request.implemented.join(\", \")}`,\n );\n }\n if (exporter.id !== request.id) {\n return refuse(\n \"MOSTRA_PLUGIN_ENTRY_INVALID\",\n `its definition is \"${String(exporter.id)}\", not \"${request.id}\" as the manifest says`,\n );\n }\n const layout = exporter.output?.layout === \"file\" ? \"file\" : \"directory\";\n const extension =\n typeof exporter.output?.extension === \"string\" ? exporter.output.extension : undefined;\n if (exporter.options === undefined) {\n if (Object.keys(request.options).length > 0) {\n return refuse(\n \"MOSTRA_PLUGIN_OPTIONS_INVALID\",\n `it takes no options, and was given ${Object.keys(request.options).join(\", \")}`,\n );\n }\n } else {\n let problems: string;\n try {\n problems = optionProblems(exporter.options, request.options);\n } catch (error) {\n return refuse(\n \"MOSTRA_PLUGIN_ENTRY_INVALID\",\n `its options aren't a JSON Schema Mostra reads (${error instanceof Error ? error.message : String(error)})`,\n );\n }\n if (problems !== \"\") return refuse(\"MOSTRA_PLUGIN_OPTIONS_INVALID\", problems);\n }\n const controller = new AbortController();\n const lines: string[] = [];\n const result = (await (\n exporter.export as (\n input: unknown,\n context: unknown,\n ) => Promise<{\n files?: readonly { path: unknown; content: unknown }[];\n entry?: unknown;\n findings?: unknown;\n }>\n ).call(\n exporter,\n { version: request.version, files: tree(request.versionDir), options: request.options },\n {\n signal: controller.signal,\n log: (message: string) => {\n if (lines.length < 1000) lines.push(String(message).slice(0, 4000));\n },\n mostraVersion: request.mostraVersion,\n },\n )) as\n | {\n files?: readonly { path: unknown; content: unknown }[];\n entry?: unknown;\n findings?: unknown;\n }\n | undefined;\n const files = (result?.files ?? []).map((file) => {\n if (typeof file.path !== \"string\") throw new Error(\"An exported file has no path.\");\n if (typeof file.content === \"string\") return { path: file.path, text: file.content };\n if (file.content instanceof Uint8Array) {\n return { path: file.path, base64: Buffer.from(file.content).toString(\"base64\") };\n }\n throw new Error(`${file.path}'s content is neither text nor bytes.`);\n });\n return {\n files,\n ...(typeof result?.entry === \"string\" ? { entry: result.entry } : {}),\n output: { layout, ...(extension !== undefined ? { extension } : {}) },\n findings: Array.isArray(result?.findings) ? (result.findings as unknown[]) : [],\n log: lines,\n };\n}\n\nconnectToSupervisor({\n onRequest: async (method, params) => {\n if (method === INSPECT_METHOD) return inspect(params as unknown as InspectRequest);\n if (method === EXPORT_METHOD) return runExport(params as unknown as ExportRequest);\n throw new Error(`The plugin child doesn't serve ${method}.`);\n },\n});\n"],"mappings":"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"}
@@ -4,7 +4,7 @@
4
4
 
5
5
  Every command takes `--json`, which prints one envelope on stdout: `{ "ok": true, "result", "instance", "warnings" }` or `{ "ok": false, "error", "warnings" }`. Streaming commands print one envelope per line, the last one carrying `result` or `error`. Logs and progress go to stderr. Without a terminal, or with `--json`, no command asks a question.
6
6
 
7
- Commands: `add`, `daemon`, `dev`, `docs`, `doctor`, `export`, `gc`, `host`, `list`, `login`, `logout`, `mcp`, `new`, `open`, `pause`, `publish`, `push`, `results`, `resume`, `roster`, `run`, `secret`, `share`, `state`, `status`, `telemetry`, `verify`, `wait`.
7
+ Commands: `add`, `daemon`, `dev`, `docs`, `doctor`, `export`, `gc`, `host`, `list`, `login`, `logout`, `mcp`, `new`, `open`, `pause`, `plugin`, `publish`, `push`, `results`, `resume`, `roster`, `run`, `secret`, `share`, `state`, `status`, `telemetry`, `verify`, `wait`.
8
8
 
9
9
  ## mostra new
10
10
 
@@ -764,16 +764,18 @@ Example:
764
764
  ## mostra add
765
765
 
766
766
  ```text
767
- Add npm packages to an artifact's lockfile at exact versions, installing them into the home's store.
767
+ Add npm packages to an artifact's lockfile, or copy source-pack items (shadcn registry items) into it.
768
768
 
769
769
  Usage:
770
770
  mostra add <package…> [flags]
771
771
 
772
772
  Arguments:
773
- <package> npm specs: name, name@version, name@range or name@tag.
773
+ <package> npm specs (name, name@version, name@range, name@tag), or items: a URL, a local .json, owner/repo/item on GitHub, @namespace/item, plugin:<package>/<item>.
774
774
 
775
775
  Flags:
776
776
  --artifact <path|id> The artifact. Default: the one in the current directory.
777
+ --overwrite Replace files of the artifact that an item writes with other content.
778
+ --accept-license <id> Acknowledge a license the items' packages bring (LicenseRef-…), recorded in the lockfile.
777
779
  --request-id <id> Make a retry return the first attempt's result.
778
780
 
779
781
  Global flags:
@@ -783,7 +785,7 @@ Global flags:
783
785
  --timeout <d> Give up on the instance after this long (exit 4), such as 30s or 5m.
784
786
  --help Show this command's help; with --json, its definition.
785
787
 
786
- Output: DepsAddResult (mostra docs cli)
788
+ Output: DepsAddResult | PackAddResult (mostra docs cli)
787
789
 
788
790
  Exit codes:
789
791
  0 success
@@ -796,6 +798,145 @@ Example:
796
798
  mostra add recharts@3 --artifact ./dashboard
797
799
  ```
798
800
 
801
+ ## mostra plugin add
802
+
803
+ ```text
804
+ Install plugins for an artifact or the home, checking their contracts, conflicts and licenses first.
805
+
806
+ Usage:
807
+ mostra plugin add <package…> [flags]
808
+
809
+ Arguments:
810
+ <package> npm specs of the plugins: name, name@version or name@range.
811
+
812
+ Flags:
813
+ --artifact <path|id> The artifact whose lockfile records the plugins. Default: the one in the current directory.
814
+ --global The home's own plugins instead, for every artifact of the home (exporters and CLI commands only).
815
+ --accept-license <id> Acknowledge a license the install brings (LicenseRef-Remotion), recorded in the lockfile. Repeat or comma-separate.
816
+ --request-id <id> Make a retry return the first attempt's result.
817
+
818
+ Global flags:
819
+ --json Print one JSON envelope on stdout (NDJSON for streams).
820
+ --home <dir> Use this Mostra home instead of MOSTRA_HOME or the default.
821
+ --cwd <dir> Resolve relative paths from this directory.
822
+ --timeout <d> Give up on the instance after this long (exit 4), such as 30s or 5m.
823
+ --help Show this command's help; with --json, its definition.
824
+
825
+ Output: PluginAddResult (mostra docs cli)
826
+
827
+ Exit codes:
828
+ 0 success
829
+ 1 artifact failure (verify failed, publish refused, the artifact's state refused the request)
830
+ 2 usage error
831
+ 3 environment error (no runtime, browser or socket; the home; an unsupported platform)
832
+ 4 timeout (--timeout passed)
833
+
834
+ Example:
835
+ mostra plugin add mostra-plugin-pdf --artifact ./report
836
+ ```
837
+
838
+ ## mostra plugin list
839
+
840
+ ```text
841
+ List an artifact's plugins, or the home's, in load order, as verify and publish load them now.
842
+
843
+ Usage:
844
+ mostra plugin list [flags]
845
+
846
+ Flags:
847
+ --artifact <path|id> The artifact whose lockfile records the plugins. Default: the one in the current directory.
848
+ --global The home's own plugins instead, for every artifact of the home (exporters and CLI commands only).
849
+
850
+ Global flags:
851
+ --json Print one JSON envelope on stdout (NDJSON for streams).
852
+ --home <dir> Use this Mostra home instead of MOSTRA_HOME or the default.
853
+ --cwd <dir> Resolve relative paths from this directory.
854
+ --timeout <d> Give up on the instance after this long (exit 4), such as 30s or 5m.
855
+ --help Show this command's help; with --json, its definition.
856
+
857
+ Output: PluginListResult (mostra docs cli)
858
+
859
+ Exit codes:
860
+ 0 success
861
+ 1 artifact failure (verify failed, publish refused, the artifact's state refused the request)
862
+ 2 usage error
863
+ 3 environment error (no runtime, browser or socket; the home; an unsupported platform)
864
+ 4 timeout (--timeout passed)
865
+
866
+ Example:
867
+ mostra plugin list --artifact ./report
868
+ ```
869
+
870
+ ## mostra plugin remove
871
+
872
+ ```text
873
+ Take plugins out of an artifact's lockfile, or the home's.
874
+
875
+ Usage:
876
+ mostra plugin remove <package…> [flags]
877
+
878
+ Arguments:
879
+ <package> The plugins' package names.
880
+
881
+ Flags:
882
+ --artifact <path|id> The artifact whose lockfile records the plugins. Default: the one in the current directory.
883
+ --global The home's own plugins instead, for every artifact of the home (exporters and CLI commands only).
884
+ --request-id <id> Make a retry return the first attempt's result.
885
+
886
+ Global flags:
887
+ --json Print one JSON envelope on stdout (NDJSON for streams).
888
+ --home <dir> Use this Mostra home instead of MOSTRA_HOME or the default.
889
+ --cwd <dir> Resolve relative paths from this directory.
890
+ --timeout <d> Give up on the instance after this long (exit 4), such as 30s or 5m.
891
+ --help Show this command's help; with --json, its definition.
892
+
893
+ Output: PluginRemoveResult (mostra docs cli)
894
+
895
+ Exit codes:
896
+ 0 success
897
+ 1 artifact failure (verify failed, publish refused, the artifact's state refused the request)
898
+ 2 usage error
899
+ 3 environment error (no runtime, browser or socket; the home; an unsupported platform)
900
+ 4 timeout (--timeout passed)
901
+
902
+ Example:
903
+ mostra plugin remove mostra-plugin-pdf --artifact ./report
904
+ ```
905
+
906
+ ## mostra plugin validate
907
+
908
+ ```text
909
+ Check a plugin package as Mostra would load it: its manifest, contract ranges, entries and licenses.
910
+
911
+ Usage:
912
+ mostra plugin validate [<dir>] [flags]
913
+
914
+ Arguments:
915
+ <dir> The plugin's package directory. Default: the current directory.
916
+
917
+ Flags:
918
+ --accept-license <id> Acknowledge a license the install brings (LicenseRef-Remotion), recorded in the lockfile. Repeat or comma-separate.
919
+
920
+ Global flags:
921
+ --json Print one JSON envelope on stdout (NDJSON for streams).
922
+ --home <dir> Use this Mostra home instead of MOSTRA_HOME or the default.
923
+ --cwd <dir> Resolve relative paths from this directory.
924
+ --timeout <d> Give up on the instance after this long (exit 4), such as 30s or 5m.
925
+ --help Show this command's help; with --json, its definition.
926
+
927
+ Output: PluginValidateResult (mostra docs cli)
928
+
929
+ Exit codes:
930
+ 0 success
931
+ 1 artifact failure (verify failed, publish refused, the artifact's state refused the request)
932
+ 2 usage error
933
+ 3 environment error (no runtime, browser or socket; the home; an unsupported platform)
934
+ 4 timeout (--timeout passed)
935
+
936
+ Example:
937
+ mostra plugin validate ./my-plugin
938
+ ```
939
+
799
940
  ## mostra export
800
941
 
801
942
  ```text
@@ -808,7 +949,8 @@ Arguments:
808
949
  <artifact> The artifact: its source path or its ID.
809
950
 
810
951
  Flags:
811
- --as <class> What to write: `bundle`, the version's builds, manifest, lockfile and source. (bundle) Default: bundle.
952
+ --as <exporter> What to write: `bundle`, the version's builds, manifest, lockfile and source; or the ID of an exporter a plugin of the artifact or the home contributes. Default: bundle.
953
+ --option <name=value> An option for a plugin's exporter; its value is read as JSON when it parses.
812
954
  --out <path> Where: a new directory, or one archive when it ends in .tar.zst.
813
955
  --version <number|id> The version. Default: the latest.
814
956