@mostra/cli 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.
- package/dist/bin.js +2 -2
- package/dist/{bootstrap-3_Tdfdg7.js → bootstrap-CYgyuZFk.js} +8 -4
- package/dist/bootstrap-CYgyuZFk.js.map +1 -0
- package/dist/bootstrap-DHnt5zU_.js +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/reference/cli.md +147 -5
- package/dist/reference/diagnostics.json +234 -0
- package/dist/reference/errors/MOSTRA_LICENSE_ACCEPT_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_LICENSE_MISMATCH.md +23 -0
- package/dist/reference/errors/MOSTRA_LICENSE_UNACCEPTED.md +23 -0
- package/dist/reference/errors/MOSTRA_LICENSE_UNDECLARED.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_ADDRESS_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_CSS_UNIMPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_FETCH_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_FILE_EXISTS.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_ITEM_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_ITEM_NOT_FOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_NOT_APPLIED.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_OFFLINE.md +23 -0
- package/dist/reference/errors/MOSTRA_PACK_TARGET_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_CONFLICT.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_ENTRY_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_EXPORTER_UNKNOWN.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_WARNING.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_NOT_A_PLUGIN.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_NOT_INSTALLED.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_OPTIONS_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_PLATFORM_UNSUPPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_SCOPE_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_PLUGIN_SHADOWED.md +23 -0
- package/dist/{run-CtR0PFMj.js → run-BsUzIBQj.js} +437 -29
- package/dist/run-BsUzIBQj.js.map +1 -0
- package/dist/run-c8U3GkBy.js +1 -0
- package/dist/skill/SKILL.md +4 -2
- package/dist/skill/references/mcp.md +2 -2
- package/dist/skill/references/plugins.md +51 -0
- package/package.json +7 -5
- package/src/command.ts +2 -0
- package/src/commands/authoring.ts +129 -18
- package/src/commands/index.ts +14 -3
- package/src/commands/plugins.ts +219 -0
- package/src/exit.ts +7 -0
- package/src/plugin-commands.ts +170 -0
- package/src/run.ts +64 -4
- package/dist/bootstrap-3_Tdfdg7.js.map +0 -1
- package/dist/bootstrap-C9a2gSWf.js +0 -1
- package/dist/run-CtR0PFMj.js.map +0 -1
- package/dist/run-NWeQcyh9.js +0 -1
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { t as run } from "./run-BsUzIBQj.js";
|
package/dist/skill/SKILL.md
CHANGED
|
@@ -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.
|
|
7
|
+
version: "0.15.1"
|
|
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.
|
|
16
|
+
Run `mostra <command>`. When `mostra` isn't on the `PATH`, run `npx -y @mostra/cli@0.15.1 <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.
|
|
62
|
+
A client starts the server as `mostra mcp` over stdio, or `npx -y @mostra/cli@0.15.1 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.
|
|
65
|
+
{ "mcpServers": { "mostra": { "command": "npx", "args": ["-y", "@mostra/cli@0.15.1", "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.
|
|
3
|
+
"version": "0.15.1",
|
|
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.
|
|
40
|
-
"@mostra/protocol": "0.
|
|
41
|
-
"@mostra/sdk": "0.
|
|
39
|
+
"@mostra/mcp": "0.15.1",
|
|
40
|
+
"@mostra/protocol": "0.15.1",
|
|
41
|
+
"@mostra/sdk": "0.15.1",
|
|
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/
|
|
48
|
+
"@mostra/contract-cli-command": "0.1.0",
|
|
49
|
+
"@mostra/contract-exporter": "0.1.0",
|
|
50
|
+
"@mostra/runtime": "0.15.1",
|
|
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 {
|
|
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 {
|
|
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: "<
|
|
213
|
-
choices: ["bundle"],
|
|
221
|
+
value: "<exporter>",
|
|
214
222
|
default: "bundle",
|
|
215
|
-
summary:
|
|
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
|
|
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:
|
|
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
|
|
317
|
-
|
|
318
|
-
|
|
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
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
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
|
});
|
package/src/commands/index.ts
CHANGED
|
@@ -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`, `
|
|
4
|
-
*
|
|
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. */
|