@mostra/cli 0.14.0 → 0.15.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.
Files changed (53) hide show
  1. package/dist/bin.js +2 -2
  2. package/dist/{bootstrap-3_Tdfdg7.js → bootstrap-CYgyuZFk.js} +8 -4
  3. package/dist/bootstrap-CYgyuZFk.js.map +1 -0
  4. package/dist/bootstrap-DHnt5zU_.js +1 -0
  5. package/dist/index.d.ts +2 -0
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +2 -2
  8. package/dist/reference/cli.md +147 -5
  9. package/dist/reference/diagnostics.json +234 -0
  10. package/dist/reference/errors/MOSTRA_LICENSE_ACCEPT_INVALID.md +23 -0
  11. package/dist/reference/errors/MOSTRA_LICENSE_MISMATCH.md +23 -0
  12. package/dist/reference/errors/MOSTRA_LICENSE_UNACCEPTED.md +23 -0
  13. package/dist/reference/errors/MOSTRA_LICENSE_UNDECLARED.md +23 -0
  14. package/dist/reference/errors/MOSTRA_PACK_ADDRESS_INVALID.md +23 -0
  15. package/dist/reference/errors/MOSTRA_PACK_CSS_UNIMPORTED.md +23 -0
  16. package/dist/reference/errors/MOSTRA_PACK_FETCH_FAILED.md +23 -0
  17. package/dist/reference/errors/MOSTRA_PACK_FILE_EXISTS.md +23 -0
  18. package/dist/reference/errors/MOSTRA_PACK_ITEM_INVALID.md +23 -0
  19. package/dist/reference/errors/MOSTRA_PACK_ITEM_NOT_FOUND.md +23 -0
  20. package/dist/reference/errors/MOSTRA_PACK_NOT_APPLIED.md +23 -0
  21. package/dist/reference/errors/MOSTRA_PACK_OFFLINE.md +23 -0
  22. package/dist/reference/errors/MOSTRA_PACK_TARGET_INVALID.md +23 -0
  23. package/dist/reference/errors/MOSTRA_PLUGIN_CONFLICT.md +23 -0
  24. package/dist/reference/errors/MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED.md +23 -0
  25. package/dist/reference/errors/MOSTRA_PLUGIN_ENTRY_INVALID.md +23 -0
  26. package/dist/reference/errors/MOSTRA_PLUGIN_EXPORTER_UNKNOWN.md +23 -0
  27. package/dist/reference/errors/MOSTRA_PLUGIN_FAILED.md +23 -0
  28. package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_INVALID.md +23 -0
  29. package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_WARNING.md +23 -0
  30. package/dist/reference/errors/MOSTRA_PLUGIN_NOT_A_PLUGIN.md +23 -0
  31. package/dist/reference/errors/MOSTRA_PLUGIN_NOT_INSTALLED.md +23 -0
  32. package/dist/reference/errors/MOSTRA_PLUGIN_OPTIONS_INVALID.md +23 -0
  33. package/dist/reference/errors/MOSTRA_PLUGIN_PLATFORM_UNSUPPORTED.md +23 -0
  34. package/dist/reference/errors/MOSTRA_PLUGIN_SCOPE_INVALID.md +23 -0
  35. package/dist/reference/errors/MOSTRA_PLUGIN_SHADOWED.md +23 -0
  36. package/dist/{run-CtR0PFMj.js → run-BsUzIBQj.js} +437 -29
  37. package/dist/run-BsUzIBQj.js.map +1 -0
  38. package/dist/run-c8U3GkBy.js +1 -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 +7 -5
  43. package/src/command.ts +2 -0
  44. package/src/commands/authoring.ts +129 -18
  45. package/src/commands/index.ts +14 -3
  46. package/src/commands/plugins.ts +219 -0
  47. package/src/exit.ts +7 -0
  48. package/src/plugin-commands.ts +170 -0
  49. package/src/run.ts +64 -4
  50. package/dist/bootstrap-3_Tdfdg7.js.map +0 -1
  51. package/dist/bootstrap-C9a2gSWf.js +0 -1
  52. package/dist/run-CtR0PFMj.js.map +0 -1
  53. package/dist/run-NWeQcyh9.js +0 -1
@@ -0,0 +1 @@
1
+ export { t as run } from "./run-BsUzIBQj.js";
@@ -4,7 +4,7 @@ description: Communicate visually with the user through Mostra. Use whenever sho
4
4
  license: Apache-2.0
5
5
  compatibility: Needs a shell that runs `mostra` (or `npx` with Node.js 22.19 or later) on macOS, Linux or Windows, x64 or arm64.
6
6
  metadata:
7
- version: "0.14.0"
7
+ version: "0.15.0"
8
8
  ---
9
9
 
10
10
  # Mostra
@@ -13,7 +13,7 @@ Mostra turns a React page you write into an **artifact**: a web page a person op
13
13
 
14
14
  ## Running Mostra
15
15
 
16
- Run `mostra <command>`. When `mostra` isn't on the `PATH`, run `npx -y @mostra/cli@0.14.0 <command>` everywhere this Skill says `mostra`; the first run downloads Mostra's own runtime (no global Node.js needed beyond `npx`). Every command takes `--json` (one JSON envelope on stdout, logs on stderr) and `--help`. `mostra docs <topic>` prints the reference, including every diagnostic code's page (`mostra docs MOSTRA_FIELD_DUPLICATE_ID`). `mostra list` lists the artifacts you've published, and `mostra status` shows the running instance.
16
+ Run `mostra <command>`. When `mostra` isn't on the `PATH`, run `npx -y @mostra/cli@0.15.0 <command>` everywhere this Skill says `mostra`; the first run downloads Mostra's own runtime (no global Node.js needed beyond `npx`). Every command takes `--json` (one JSON envelope on stdout, logs on stderr) and `--help`. `mostra docs <topic>` prints the reference, including every diagnostic code's page (`mostra docs MOSTRA_FIELD_DUPLICATE_ID`). `mostra list` lists the artifacts you've published, and `mostra status` shows the running instance.
17
17
 
18
18
  When Mostra's tools are in your tool list (`artifact_create`, `artifact_verify` and the rest), use them instead: each step below has its tool, and everything else here holds unchanged. See [references/mcp.md](references/mcp.md).
19
19
 
@@ -79,6 +79,7 @@ Each step ends when its check holds. Don't hand a link out before step 4 passes.
79
79
  | Show who answered, who is here, who changed what | `useRespondents()`, `usePresence({ cursor })`, a shared field's `meta.updatedBy` | [teams.md](references/teams.md) |
80
80
  | Several pages, packages, MDX, images | `pages/`, any npm import, `index.mdx`, `public/` | [page.md](references/page.md) |
81
81
  | Charts, tables, animation, UI primitives | the preinstalled libraries | [libraries.md](references/libraries.md) |
82
+ | Someone else's component, exporter or command | `mostra add <item>` (shadcn registry items), `mostra plugin add <package>` | [plugins.md](references/plugins.md) |
82
83
 
83
84
  ## Rules verify enforces
84
85
 
@@ -119,6 +120,7 @@ Read the one you need when you need it.
119
120
  | [references/sharing.md](references/sharing.md) | Someone other than the person at this machine opens it, or on another device |
120
121
  | [references/teams.md](references/teams.md) | Several people answer it or work on it together: personal links, waiting for everyone, who is here |
121
122
  | [references/libraries.md](references/libraries.md) | Using charts, tables, motion or UI primitives, or an import fails |
123
+ | [references/plugins.md](references/plugins.md) | Adding a shadcn registry item or a plugin, a license asks for an acknowledgment, or you write a plugin |
122
124
  | [references/mcp.md](references/mcp.md) | You work through Mostra's tools (`artifact_create` and the rest) instead of the `mostra` command |
123
125
 
124
126
  Three complete artifacts that pass verify, to copy from: [assets/examples/decision/](assets/examples/decision/) (a choice with a reason), [assets/examples/inbox/](assets/examples/inbox/) (drafted replies with real Send actions) and [assets/examples/dashboard/](assets/examples/dashboard/) (live data and a shared list). The same guide is `mostra docs guide`, and each reference `mostra docs guide/<name>`.
@@ -59,10 +59,10 @@ A chat app's connector reaches the person's own computer through their Mostra se
59
59
 
60
60
  ## Adding the server to a client
61
61
 
62
- A client starts the server as `mostra mcp` over stdio, or `npx -y @mostra/cli@0.14.0 mcp` where `mostra` isn't installed. Its configuration names that command, for example:
62
+ A client starts the server as `mostra mcp` over stdio, or `npx -y @mostra/cli@0.15.0 mcp` where `mostra` isn't installed. Its configuration names that command, for example:
63
63
 
64
64
  ```json
65
- { "mcpServers": { "mostra": { "command": "npx", "args": ["-y", "@mostra/cli@0.14.0", "mcp"] } } }
65
+ { "mcpServers": { "mostra": { "command": "npx", "args": ["-y", "@mostra/cli@0.15.0", "mcp"] } } }
66
66
  ```
67
67
 
68
68
  For a client that speaks only HTTP, `mostra mcp --http` serves Streamable HTTP on `127.0.0.1` and prints its URL and a token on stderr; every request sends `Authorization: Bearer <token>` (set `MOSTRA_MCP_TOKEN` to choose it). `--workspace <dir>` chooses where new artifacts go.
@@ -0,0 +1,51 @@
1
+ # Plugins and packs: other people's components, exporters and commands
2
+
3
+ Two kinds of extension reach an artifact. A **pack** is source you copy in: a shadcn registry item (a component, a block, a hook), whose files become the artifact's own and are yours to edit. A **plugin** is an npm package with a `"mostra"` manifest that Mostra loads: an exporter, a CLI command, an engine a component mounts, a verify check. Both install into one artifact and are recorded in its lockfile, so its versions carry them.
4
+
5
+ ## Contents
6
+
7
+ - Copy an item in: `mostra add`
8
+ - Install a plugin: `mostra plugin add`
9
+ - Licenses that need an acknowledgment
10
+ - Use what a plugin contributes
11
+ - Write a plugin
12
+
13
+ ## Copy an item in: `mostra add`
14
+
15
+ `mostra add` takes shadcn's addresses as well as npm packages, and installs any shadcn registry item as shadcn would:
16
+
17
+ | Address | Example |
18
+ |---|---|
19
+ | An item's URL | `mostra add https://ui.shadcn.com/r/styles/new-york-v4/login-01.json --artifact <dir>` |
20
+ | A GitHub repository's registry | `mostra add acme/ui/date-field#v1.2.0 --artifact <dir>` |
21
+ | A namespace `components.json` registers | `mostra add @acme/date-field --artifact <dir>` |
22
+ | A local item | `mostra add ./items/date-field.json --artifact <dir>` |
23
+ | A pack an installed plugin carries | `mostra add plugin:mostra-pack-acme/date-field --artifact <dir>` |
24
+
25
+ The item's registry dependencies come with it, its files land where shadcn puts them (`components/ui/`, `components/`, `lib/`, `hooks/`, or its `target`), its npm packages join the lockfile, and its CSS joins the stylesheet your entry imports. Nothing is written until every file is checked. A file you already have with other content stops the install: add `--overwrite` to replace it. A page item (`registry:page`) lands in `pages/` when the artifact has one. *Done when* the files are listed in the output and `mostra verify <dir>` passes with them imported.
26
+
27
+ Read the notes `mostra add` prints. An item's environment variables become secrets (`mostra secret set NAME --artifact <dir>`), and a stylesheet your entry doesn't import yet needs its `import "./styles.css";`.
28
+
29
+ ## Install a plugin: `mostra plugin add`
30
+
31
+ ```sh
32
+ mostra plugin add mostra-plugin-pdf --artifact <dir>
33
+ mostra plugin list --artifact <dir>
34
+ mostra plugin remove mostra-plugin-pdf --artifact <dir>
35
+ ```
36
+
37
+ Mostra checks each plugin before it records anything: the contract versions it needs are ones this release implements, no other plugin of the artifact contributes the same ID, every entry exports a definition stamped with its contract, and every license it brings is disclosed. `verify` and `publish` check the artifact's plugins again, so a plugin this release can't load is reported before a version is made. A plugin of only exporters and CLI commands may be installed for every artifact of the home with `--global` in place of `--artifact`.
38
+
39
+ ## Licenses that need an acknowledgment
40
+
41
+ An install that brings a source-available or proprietary license, or one Mostra can't read, stops with `MOSTRA_LICENSE_UNACCEPTED`, naming each license, its class and the packages under it. That is disclosure, not a refusal: tell the person what the license asks (its summary and link are in the message) and, once they agree, repeat the command the diagnostic's fix gives, with `--accept-license <id>` for each license. The acknowledgment is recorded in the artifact's lockfile and needs no repeat. A `mostra add <package>` that upgrades a plugin, or changes what one depends on, is checked the same way and takes the same flag. A host may accept licenses for its home, in which case none of this stops you. OSI-approved, public-domain and other free licenses need nothing.
42
+
43
+ ## Use what a plugin contributes
44
+
45
+ - An exporter: `mostra export <dir> --as <id> --out <path>`, with `--option name=value` for each option its schema takes (a value is read as JSON when it parses).
46
+ - A CLI command: run `mostra` followed by its words, from the artifact's directory (or anywhere, for the home's plugins). `mostra plugin list` names each one.
47
+ - An engine, an anchor provider or a connector: import the plugin's package in the page or in `live.ts`, as its README shows.
48
+
49
+ ## Write a plugin
50
+
51
+ A plugin is an npm package whose `package.json` has a `"mostra"` manifest and whose entries export what one of the contract packages' `define*` functions returns: `@mostra/contract-exporter`, `-cli-command`, `-connector`, `-embed-engine`, `-anchor-provider` or `-verify-check`. Each package's README has a complete example. `mostra plugin validate <dir>` reports every problem with its place in `package.json`. *Done when* it says `valid`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mostra/cli",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "description": "The mostra command: author, verify, publish, share and wait on agent artifacts, as a thin client of the Mostra host protocol.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "The Mostra Authors",
@@ -36,16 +36,18 @@
36
36
  "dependencies": {
37
37
  "@hono/node-server": "2.1.5",
38
38
  "@modelcontextprotocol/server": "2.4.0",
39
- "@mostra/mcp": "0.14.0",
40
- "@mostra/protocol": "0.14.0",
41
- "@mostra/sdk": "0.14.0",
39
+ "@mostra/mcp": "0.15.0",
40
+ "@mostra/protocol": "0.15.0",
41
+ "@mostra/sdk": "0.15.0",
42
42
  "zod": "4.6.7"
43
43
  },
44
44
  "devDependencies": {
45
45
  "@modelcontextprotocol/client": "2.4.0",
46
46
  "@modelcontextprotocol/conformance": "0.1.16",
47
47
  "@modelcontextprotocol/conformance-next": "npm:@modelcontextprotocol/conformance@0.2.0-alpha.12",
48
- "@mostra/runtime": "0.14.0",
48
+ "@mostra/contract-cli-command": "0.1.0",
49
+ "@mostra/contract-exporter": "0.1.0",
50
+ "@mostra/runtime": "0.15.0",
49
51
  "@mostra/tools": "0.0.0",
50
52
  "@types/node": "24.19.2",
51
53
  "tsdown": "0.23.1",
package/src/command.ts CHANGED
@@ -142,6 +142,8 @@ export interface CommandDef {
142
142
  * function of its flags, when it runs on someone's behalf (`mcp --embedded`, D148).
143
143
  */
144
144
  readonly quiet?: boolean | ((flags: CommandContext["flags"]) => boolean);
145
+ /** The name telemetry records for it, when not its words: `plugin` for a plugin's command. */
146
+ readonly telemetryName?: string;
145
147
  /** Does the command's work. */
146
148
  run(context: CommandContext): Promise<CommandOutcome>;
147
149
  }
@@ -4,7 +4,8 @@
4
4
  * and `deps/add` (INTERFACES §6, §15).
5
5
  */
6
6
  import { randomUUID } from "node:crypto";
7
- import { resolve } from "node:path";
7
+ import { readFile } from "node:fs/promises";
8
+ import { join, resolve } from "node:path";
8
9
  import {
9
10
  ARTIFACT_PROGRESS,
10
11
  artifactCreateMethod,
@@ -13,10 +14,18 @@ import {
13
14
  artifactPublishMethod,
14
15
  artifactVerifyMethod,
15
16
  depsAddMethod,
17
+ packAddMethod,
18
+ pluginExportMethod,
16
19
  type SubmissionPolicy,
17
20
  type VerifyVerdict,
18
21
  } from "@mostra/protocol";
19
- import { type CommandDef, defineCommand } from "../command.ts";
22
+ import { packVariables, parsePackAddress } from "@mostra/protocol/plugin";
23
+ import {
24
+ type CommandContext,
25
+ type CommandDef,
26
+ type CommandOutcome,
27
+ defineCommand,
28
+ } from "../command.ts";
20
29
  import { EXIT } from "../exit.ts";
21
30
  import { usage } from "../parse.ts";
22
31
  import { arg, artifactRef, flag, sourceRef } from "./shared.ts";
@@ -209,10 +218,16 @@ export const exportCommand: CommandDef = defineCommand({
209
218
  {
210
219
  name: "as",
211
220
  kind: "string",
212
- value: "<class>",
213
- choices: ["bundle"],
221
+ value: "<exporter>",
214
222
  default: "bundle",
215
- summary: "What to write: `bundle`, the version's builds, manifest, lockfile and source.",
223
+ summary:
224
+ "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.",
225
+ },
226
+ {
227
+ name: "option",
228
+ kind: "list",
229
+ value: "<name=value>",
230
+ summary: "An option for a plugin's exporter; its value is read as JSON when it parses.",
216
231
  },
217
232
  {
218
233
  name: "out",
@@ -234,6 +249,8 @@ export const exportCommand: CommandDef = defineCommand({
234
249
  const out = flag(context, "out");
235
250
  if (out === undefined) throw usage('"mostra export" needs --out <path>.');
236
251
  const version = flag(context, "version");
252
+ const as = flag(context, "as") ?? "bundle";
253
+ if (as !== "bundle") return exportWithPlugin(context, as, out, version);
237
254
  const result = await context.call(artifactExportMethod, {
238
255
  artifact: artifactRef(arg(context, "artifact"), context.cwd),
239
256
  as: "bundle",
@@ -249,6 +266,43 @@ export const exportCommand: CommandDef = defineCommand({
249
266
  },
250
267
  });
251
268
 
269
+ /** `export --as <id>` with an exporter a plugin contributes (`plugin/export`). */
270
+ async function exportWithPlugin(
271
+ context: CommandContext,
272
+ exporter: string,
273
+ out: string,
274
+ version: string | undefined,
275
+ ): Promise<CommandOutcome> {
276
+ const options: Record<string, unknown> = {};
277
+ for (const pair of Array.isArray(context.flags["option"]) ? context.flags["option"] : []) {
278
+ const at = pair.indexOf("=");
279
+ if (at <= 0) throw usage(`--option ${pair} needs the form name=value.`);
280
+ const raw = pair.slice(at + 1);
281
+ let value: unknown = raw;
282
+ try {
283
+ value = JSON.parse(raw);
284
+ } catch {
285
+ // A plain string.
286
+ }
287
+ options[pair.slice(0, at)] = value;
288
+ }
289
+ const result = await context.call(pluginExportMethod, {
290
+ artifact: artifactRef(arg(context, "artifact"), context.cwd),
291
+ exporter,
292
+ out: resolve(context.cwd, out),
293
+ ...(Object.keys(options).length > 0 ? { options } : {}),
294
+ ...(version !== undefined
295
+ ? { version: /^\d+$/.test(version) ? Number(version) : version }
296
+ : {}),
297
+ });
298
+ const lines = [
299
+ `Exported ${result.versionId} with ${result.exporter.id} (${result.exporter.package}):`,
300
+ ...result.files.map((file) => ` ${file}`),
301
+ ...result.findings.map((finding) => `${finding.severity} ${finding.code}: ${finding.message}`),
302
+ ];
303
+ return { result, human: `${lines.join("\n")}\n` };
304
+ }
305
+
252
306
  /** `mostra run <bundle>`. */
253
307
  export const runCommand: CommandDef = defineCommand({
254
308
  path: ["run"],
@@ -279,15 +333,16 @@ export const runCommand: CommandDef = defineCommand({
279
333
  },
280
334
  });
281
335
 
282
- /** `mostra add <package…>`. */
336
+ /** `mostra add <package|item…>`. */
283
337
  export const addCommand: CommandDef = defineCommand({
284
338
  path: ["add"],
285
339
  summary:
286
- "Add npm packages to an artifact's lockfile at exact versions, installing them into the home's store.",
340
+ "Add npm packages to an artifact's lockfile, or copy source-pack items (shadcn registry items) into it.",
287
341
  args: [
288
342
  {
289
343
  name: "package",
290
- summary: "npm specs: name, name@version, name@range or name@tag.",
344
+ summary:
345
+ "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>.",
291
346
  variadic: true,
292
347
  },
293
348
  ],
@@ -298,6 +353,18 @@ export const addCommand: CommandDef = defineCommand({
298
353
  value: "<path|id>",
299
354
  summary: "The artifact. Default: the one in the current directory.",
300
355
  },
356
+ {
357
+ name: "overwrite",
358
+ kind: "boolean",
359
+ summary: "Replace files of the artifact that an item writes with other content.",
360
+ },
361
+ {
362
+ name: "accept-license",
363
+ kind: "list",
364
+ value: "<id>",
365
+ summary:
366
+ "Acknowledge a license the items' packages bring (LicenseRef-…), recorded in the lockfile.",
367
+ },
301
368
  {
302
369
  name: "request-id",
303
370
  kind: "string",
@@ -305,7 +372,7 @@ export const addCommand: CommandDef = defineCommand({
305
372
  summary: "Make a retry return the first attempt's result.",
306
373
  },
307
374
  ],
308
- output: { type: "DepsAddResult", topic: "cli" },
375
+ output: { type: "DepsAddResult | PackAddResult", topic: "cli" },
309
376
  exits: [EXIT.failure],
310
377
  example: "add recharts@3 --artifact ./dashboard",
311
378
  async run(context) {
@@ -313,16 +380,60 @@ export const addCommand: CommandDef = defineCommand({
313
380
  if (!Array.isArray(packages) || packages.length === 0)
314
381
  throw usage('"mostra add" needs <package…>.');
315
382
  const requestId = flag(context, "request-id");
316
- const result = await context.call(depsAddMethod, {
317
- artifact: sourceRef(flag(context, "artifact") ?? ".", context.cwd),
318
- packages: packages as string[],
383
+ const artifact = sourceRef(flag(context, "artifact") ?? ".", context.cwd);
384
+ // A local item is named from where the command runs.
385
+ const specs = (packages as string[]).map((spec) => {
386
+ const address = parsePackAddress(spec);
387
+ return address?.kind === "file" ? resolve(context.cwd, address.path) : spec;
388
+ });
389
+ if (!specs.some((spec) => parsePackAddress(spec) !== undefined)) {
390
+ // Only npm packages: `deps/add`, as before packs existed.
391
+ const accept = context.flags["accept-license"];
392
+ const result = await context.call(depsAddMethod, {
393
+ artifact,
394
+ packages: specs,
395
+ ...(Array.isArray(accept) && accept.length > 0 ? { acceptLicenses: [...accept] } : {}),
396
+ ...(requestId !== undefined ? { requestId } : {}),
397
+ });
398
+ return {
399
+ result,
400
+ human: result.packages
401
+ .map((added) => `${added.name}@${added.version}${added.warm ? " (warm set)" : ""}\n`)
402
+ .join(""),
403
+ };
404
+ }
405
+ const accept = context.flags["accept-license"];
406
+ // The items are read with this shell's variables, not only the daemon's (which may have
407
+ // started before a token was set): those the artifact's components.json names, GitHub's
408
+ // tokens, shadcn's registry and the proxies (`packVariables`).
409
+ const components =
410
+ "path" in artifact
411
+ ? await readFile(join(artifact.path, "components.json"), "utf8").catch(() => undefined)
412
+ : undefined;
413
+ const environment = Object.fromEntries(
414
+ packVariables(components).flatMap((name) => {
415
+ const value = context.env[name];
416
+ return value !== undefined ? [[name, value]] : [];
417
+ }),
418
+ );
419
+ const result = await context.call(packAddMethod, {
420
+ artifact,
421
+ specs,
422
+ ...(context.flags["overwrite"] === true ? { overwrite: true } : {}),
423
+ ...(Array.isArray(accept) && accept.length > 0 ? { acceptLicenses: [...accept] } : {}),
424
+ ...(Object.keys(environment).length > 0 ? { environment } : {}),
319
425
  ...(requestId !== undefined ? { requestId } : {}),
320
426
  });
321
- return {
322
- result,
323
- human: result.packages
324
- .map((added) => `${added.name}@${added.version}${added.warm ? " (warm set)" : ""}\n`)
325
- .join(""),
326
- };
427
+ for (const note of result.notes) context.warn(note);
428
+ const lines = [
429
+ ...result.items.map(
430
+ (item) => `${item.name} (${item.type})${item.requiredBy ? `, for ${item.requiredBy}` : ""}`,
431
+ ),
432
+ ...result.files.map((file) => ` ${file.action} ${file.path}`),
433
+ ...result.packages.map(
434
+ (added) => `${added.name}@${added.version}${added.warm ? " (warm set)" : ""}`,
435
+ ),
436
+ ];
437
+ return { result, human: lines.map((line) => `${line}\n`).join("") };
327
438
  },
328
439
  });
@@ -1,8 +1,9 @@
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`, `plugin`, `term`) join this list with their
4
- * packages, never as placeholders; `share` joined with WP-13, `mcp` with WP-15, and `export` (its `bundle` class) and `run`
5
- * with WP-29.
3
+ * packages own (`review export`, `term`) join this list with their packages, never as
4
+ * placeholders; `share` joined with WP-13, `mcp` with WP-15, `export` (its `bundle` class) and
5
+ * `run` with WP-29, and `plugin` with WP-16. A command a plugin contributes is no entry here: the
6
+ * runner finds it among the plugins (`plugin/commands`) when a command line names none of these.
6
7
  */
7
8
  import type { CommandDef } from "../command.ts";
8
9
  import {
@@ -43,6 +44,12 @@ import {
43
44
  waitCommand,
44
45
  } from "./interaction.ts";
45
46
  import { mcpCommand } from "./mcp.ts";
47
+ import {
48
+ pluginAddCommand,
49
+ pluginListCommand,
50
+ pluginRemoveCommand,
51
+ pluginValidateCommand,
52
+ } from "./plugins.ts";
46
53
  import { loginCommand, logoutCommand, pauseCommand, resumeCommand } from "./remote.ts";
47
54
  import { shareCommand, shareListCommand, shareStopCommand } from "./sharing.ts";
48
55
  import { rosterAddCommand, rosterGetCommand, rosterRemoveCommand } from "./team.ts";
@@ -72,6 +79,10 @@ export const COMMANDS: readonly CommandDef[] = [
72
79
  statePatchCommand,
73
80
  pushCommand,
74
81
  addCommand,
82
+ pluginAddCommand,
83
+ pluginListCommand,
84
+ pluginRemoveCommand,
85
+ pluginValidateCommand,
75
86
  exportCommand,
76
87
  runCommand,
77
88
  secretSetCommand,
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Plugins and packs (D30, D31, INTERFACES §14): `plugin validate|add|list|remove`, thin clients of
3
+ * `plugin/*`. `add` (in `authoring.ts`) installs packs through `pack/add`, and `export --as` runs a
4
+ * plugin's exporter through `plugin/export`.
5
+ */
6
+ import { resolve } from "node:path";
7
+ import {
8
+ type LicenseDisclosure,
9
+ type PluginSummary,
10
+ pluginAddMethod,
11
+ pluginListMethod,
12
+ pluginRemoveMethod,
13
+ pluginValidateMethod,
14
+ type SourceRef,
15
+ } from "@mostra/protocol";
16
+ import { type CommandContext, type CommandDef, defineCommand, type FlagDef } from "../command.ts";
17
+ import { EXIT } from "../exit.ts";
18
+ import { usage } from "../parse.ts";
19
+ import { flag, sourceRef } from "./shared.ts";
20
+
21
+ /** `--artifact` and `--global`: where a plugin is installed (`--home` names the home itself). */
22
+ const SCOPE_FLAGS: readonly FlagDef[] = [
23
+ {
24
+ name: "artifact",
25
+ kind: "string",
26
+ value: "<path|id>",
27
+ summary:
28
+ "The artifact whose lockfile records the plugins. Default: the one in the current directory.",
29
+ },
30
+ {
31
+ name: "global",
32
+ kind: "boolean",
33
+ summary:
34
+ "The home's own plugins instead, for every artifact of the home (exporters and CLI commands only).",
35
+ },
36
+ ];
37
+
38
+ const ACCEPT_FLAG: FlagDef = {
39
+ name: "accept-license",
40
+ kind: "list",
41
+ value: "<id>",
42
+ summary:
43
+ "Acknowledge a license the install brings (LicenseRef-Remotion), recorded in the lockfile. Repeat or comma-separate.",
44
+ };
45
+
46
+ /** The scope the flags name: the home, or an artifact (the current directory's by default). */
47
+ function scope(context: CommandContext): { artifact: SourceRef } | { home: true } {
48
+ if (context.flags["global"] === true) {
49
+ if (flag(context, "artifact") !== undefined)
50
+ throw usage("Give --artifact or --global, not both.");
51
+ return { home: true };
52
+ }
53
+ return { artifact: sourceRef(flag(context, "artifact") ?? ".", context.cwd) };
54
+ }
55
+
56
+ /** The list of a `list` flag. */
57
+ function list(context: CommandContext, name: string): string[] {
58
+ const value = context.flags[name];
59
+ return Array.isArray(value) ? [...value] : [];
60
+ }
61
+
62
+ /** People's view of plugins: one line each, then what loading them found. */
63
+ function describePlugins(plugins: readonly PluginSummary[]): string {
64
+ if (plugins.length === 0) return "No plugins.\n";
65
+ return plugins
66
+ .map((plugin) => {
67
+ const lines = [
68
+ `${plugin.package}@${plugin.version} (${plugin.name}, ${plugin.scope}): ${plugin.contributions.map((item) => `${item.contract} ${item.id}`).join(", ") || "packs only"}${plugin.status === "error" ? " [doesn't load]" : ""}`,
69
+ ];
70
+ for (const diagnostic of plugin.diagnostics) {
71
+ lines.push(` ${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}`);
72
+ }
73
+ return lines.join("\n");
74
+ })
75
+ .join("\n")
76
+ .concat("\n");
77
+ }
78
+
79
+ /** People's view of licenses: each with its class and where its acknowledgment stands. */
80
+ function describeLicenses(licenses: readonly LicenseDisclosure[]): string {
81
+ if (licenses.length === 0) return "";
82
+ return `Licenses:\n${licenses
83
+ .map(
84
+ (license) =>
85
+ ` ${license.id} (${license.class}, ${license.acknowledgment}): ${license.packages.map((pkg) => (pkg.version !== undefined ? `${pkg.name}@${pkg.version}` : `item ${pkg.name}`)).join(", ")}`,
86
+ )
87
+ .join("\n")}\n`;
88
+ }
89
+
90
+ /** `mostra plugin validate [dir]`. */
91
+ export const pluginValidateCommand: CommandDef = defineCommand({
92
+ path: ["plugin", "validate"],
93
+ summary:
94
+ "Check a plugin package as Mostra would load it: its manifest, contract ranges, entries and licenses.",
95
+ args: [
96
+ {
97
+ name: "dir",
98
+ summary: "The plugin's package directory. Default: the current directory.",
99
+ optional: true,
100
+ },
101
+ ],
102
+ flags: [ACCEPT_FLAG],
103
+ output: { type: "PluginValidateResult", topic: "cli" },
104
+ exits: [EXIT.failure],
105
+ example: "plugin validate ./my-plugin",
106
+ async run(context) {
107
+ const dir = typeof context.args["dir"] === "string" ? context.args["dir"] : ".";
108
+ const accept = context.flags["accept-license"];
109
+ const result = await context.call(pluginValidateMethod, {
110
+ path: resolve(context.cwd, dir),
111
+ ...(Array.isArray(accept) && accept.length > 0 ? { acceptLicenses: [...accept] } : {}),
112
+ });
113
+ const lines = result.diagnostics.map(
114
+ (diagnostic) =>
115
+ `${diagnostic.severity} ${diagnostic.code}${diagnostic.location && "file" in diagnostic.location ? ` (${diagnostic.location.file}:${diagnostic.location.line}:${diagnostic.location.column})` : ""}: ${diagnostic.message}`,
116
+ );
117
+ return {
118
+ result,
119
+ human: `${result.valid ? "valid" : "invalid"}${result.plugin ? `: ${result.plugin.package}@${result.plugin.version} (${result.plugin.name})` : ""}\n${lines.join("\n")}${lines.length > 0 ? "\n" : ""}`,
120
+ ...(result.valid ? {} : { exit: EXIT.failure }),
121
+ };
122
+ },
123
+ });
124
+
125
+ /** `mostra plugin add <package…>`. */
126
+ export const pluginAddCommand: CommandDef = defineCommand({
127
+ path: ["plugin", "add"],
128
+ summary:
129
+ "Install plugins for an artifact or the home, checking their contracts, conflicts and licenses first.",
130
+ args: [
131
+ {
132
+ name: "package",
133
+ summary: "npm specs of the plugins: name, name@version or name@range.",
134
+ variadic: true,
135
+ },
136
+ ],
137
+ flags: [
138
+ ...SCOPE_FLAGS,
139
+ ACCEPT_FLAG,
140
+ {
141
+ name: "request-id",
142
+ kind: "string",
143
+ value: "<id>",
144
+ summary: "Make a retry return the first attempt's result.",
145
+ },
146
+ ],
147
+ output: { type: "PluginAddResult", topic: "cli" },
148
+ exits: [EXIT.failure],
149
+ example: "plugin add mostra-plugin-pdf --artifact ./report",
150
+ async run(context) {
151
+ const packages = context.args["package"];
152
+ if (!Array.isArray(packages) || packages.length === 0)
153
+ throw usage('"mostra plugin add" needs <package…>.');
154
+ const accept = list(context, "accept-license");
155
+ const requestId = flag(context, "request-id");
156
+ const result = await context.call(pluginAddMethod, {
157
+ ...scope(context),
158
+ packages: packages as string[],
159
+ ...(accept.length > 0 ? { acceptLicenses: accept } : {}),
160
+ ...(requestId !== undefined ? { requestId } : {}),
161
+ });
162
+ return {
163
+ result,
164
+ human: `${describePlugins(result.plugins)}${describeLicenses(result.licenses)}`,
165
+ };
166
+ },
167
+ });
168
+
169
+ /** `mostra plugin list`. */
170
+ export const pluginListCommand: CommandDef = defineCommand({
171
+ path: ["plugin", "list"],
172
+ summary:
173
+ "List an artifact's plugins, or the home's, in load order, as verify and publish load them now.",
174
+ flags: [...SCOPE_FLAGS],
175
+ output: { type: "PluginListResult", topic: "cli" },
176
+ exits: [EXIT.failure],
177
+ example: "plugin list --artifact ./report",
178
+ async run(context) {
179
+ const result = await context.call(pluginListMethod, scope(context));
180
+ return {
181
+ result,
182
+ human: `${describePlugins(result.plugins)}${describeLicenses(result.licenses)}`,
183
+ };
184
+ },
185
+ });
186
+
187
+ /** `mostra plugin remove <package…>`. */
188
+ export const pluginRemoveCommand: CommandDef = defineCommand({
189
+ path: ["plugin", "remove"],
190
+ summary: "Take plugins out of an artifact's lockfile, or the home's.",
191
+ args: [{ name: "package", summary: "The plugins' package names.", variadic: true }],
192
+ flags: [
193
+ ...SCOPE_FLAGS,
194
+ {
195
+ name: "request-id",
196
+ kind: "string",
197
+ value: "<id>",
198
+ summary: "Make a retry return the first attempt's result.",
199
+ },
200
+ ],
201
+ output: { type: "PluginRemoveResult", topic: "cli" },
202
+ exits: [EXIT.failure],
203
+ example: "plugin remove mostra-plugin-pdf --artifact ./report",
204
+ async run(context) {
205
+ const packages = context.args["package"];
206
+ if (!Array.isArray(packages) || packages.length === 0)
207
+ throw usage('"mostra plugin remove" needs <package…>.');
208
+ const requestId = flag(context, "request-id");
209
+ const result = await context.call(pluginRemoveMethod, {
210
+ ...scope(context),
211
+ packages: packages as string[],
212
+ ...(requestId !== undefined ? { requestId } : {}),
213
+ });
214
+ return {
215
+ result,
216
+ human: `Removed ${result.removed.join(", ")}.\n${describePlugins(result.plugins)}`,
217
+ };
218
+ },
219
+ });
package/src/exit.ts CHANGED
@@ -63,6 +63,11 @@ const BY_AREA: Readonly<Record<DiagnosticArea, ExitCode>> = {
63
63
  REMOTE: EXIT.environment,
64
64
  // A roster or a team wait the artifact can't take (D168): the artifact's, like a refused submit.
65
65
  TEAM: EXIT.failure,
66
+ // A plugin, a source pack or a license an install brings (D30, D31): the artifact's, like a
67
+ // package `mostra add` can't add.
68
+ PLUGIN: EXIT.failure,
69
+ PACK: EXIT.failure,
70
+ LICENSE: EXIT.failure,
66
71
  };
67
72
 
68
73
  /** Codes whose exit code isn't their area's. */
@@ -82,6 +87,8 @@ const BY_CODE: Readonly<Record<string, ExitCode>> = {
82
87
  MOSTRA_HOME_INTEGRITY: EXIT.failure,
83
88
  MOSTRA_HOME_NOT_ALWAYS_ON: EXIT.ok,
84
89
  MOSTRA_VERIFY_CRASHED: EXIT.environment,
90
+ // `--accept-license` given something that isn't a license: the command line.
91
+ MOSTRA_LICENSE_ACCEPT_INVALID: EXIT.usage,
85
92
  };
86
93
 
87
94
  /** The exit code a diagnostic ends a command with. An unknown area is an environment error. */