@mostra/cli 0.13.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.
- 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/reference/self-hosting.md +1 -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/assets/examples/dashboard/styles.css +27 -9
- package/dist/skill/assets/examples/decision/styles.css +27 -9
- package/dist/skill/assets/examples/inbox/styles.css +27 -9
- package/dist/skill/assets/studio.css +27 -9
- 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
|
@@ -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. */
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Commands plugins contribute (`@mostra/contract-cli-command`, D30): when a command line names
|
|
3
|
+
* none of `mostra`'s own commands, the runner asks the instance which commands the home's plugins
|
|
4
|
+
* and the current artifact's contribute (`plugin/commands`), and runs the longest one the words
|
|
5
|
+
* name in this process, as git runs a subcommand: its `call` goes over the CLI's own session, to
|
|
6
|
+
* the methods of the host protocol only, each checked against its schema.
|
|
7
|
+
*/
|
|
8
|
+
import { pathToFileURL } from "node:url";
|
|
9
|
+
import {
|
|
10
|
+
createDiagnostic,
|
|
11
|
+
hostMethods,
|
|
12
|
+
type MethodDefinition,
|
|
13
|
+
type PluginCommandInfo,
|
|
14
|
+
RpcError,
|
|
15
|
+
} from "@mostra/protocol";
|
|
16
|
+
import { stampServed } from "@mostra/protocol/plugin";
|
|
17
|
+
import { type ArgDef, type CommandDef, defineCommand, type FlagDef } from "./command.ts";
|
|
18
|
+
import { EXIT } from "./exit.ts";
|
|
19
|
+
import { cliVersion } from "./version.ts";
|
|
20
|
+
|
|
21
|
+
/** A plugin command's definition as its module exports it (the contract's `CliCommand`). */
|
|
22
|
+
interface PluginDefinition {
|
|
23
|
+
readonly contract: unknown;
|
|
24
|
+
readonly path: readonly string[];
|
|
25
|
+
readonly summary: string;
|
|
26
|
+
readonly args?: readonly ArgDef[];
|
|
27
|
+
readonly flags?: readonly FlagDef[];
|
|
28
|
+
readonly example?: string;
|
|
29
|
+
run(
|
|
30
|
+
input: {
|
|
31
|
+
readonly args: Readonly<Record<string, string | readonly string[] | undefined>>;
|
|
32
|
+
readonly flags: Readonly<
|
|
33
|
+
Record<string, string | number | boolean | readonly string[] | undefined>
|
|
34
|
+
>;
|
|
35
|
+
readonly cwd: string;
|
|
36
|
+
readonly json: boolean;
|
|
37
|
+
},
|
|
38
|
+
context: {
|
|
39
|
+
readonly signal: AbortSignal;
|
|
40
|
+
log(message: string): void;
|
|
41
|
+
readonly mostraVersion: string;
|
|
42
|
+
call(method: string, params: Record<string, unknown>): Promise<unknown>;
|
|
43
|
+
progress(line: string): void;
|
|
44
|
+
},
|
|
45
|
+
): Promise<{ readonly result: unknown; readonly human?: string; readonly exit?: number }>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const failed = (message: string): RpcError =>
|
|
49
|
+
new RpcError(createDiagnostic("MOSTRA_PLUGIN_FAILED", { message }));
|
|
50
|
+
|
|
51
|
+
/** The plugin command `words` start with (the longest), or `undefined`. */
|
|
52
|
+
export function matchCommand(
|
|
53
|
+
commands: readonly PluginCommandInfo[],
|
|
54
|
+
words: readonly string[],
|
|
55
|
+
): PluginCommandInfo | undefined {
|
|
56
|
+
let best: PluginCommandInfo | undefined;
|
|
57
|
+
for (const command of commands) {
|
|
58
|
+
const path = command.command.split(" ");
|
|
59
|
+
if (path.length > words.length) continue;
|
|
60
|
+
if (!path.every((word, index) => words[index] === word)) continue;
|
|
61
|
+
if (best === undefined || path.length > best.command.split(" ").length) best = command;
|
|
62
|
+
}
|
|
63
|
+
return best;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Loads a plugin command and turns it into a command of `mostra`: its definition is checked
|
|
68
|
+
* (its stamp is one this release serves, its words are the manifest's), and its `run` gets a
|
|
69
|
+
* context whose `call` reaches the host protocol through the CLI's session.
|
|
70
|
+
*/
|
|
71
|
+
export async function loadPluginCommand(info: PluginCommandInfo): Promise<CommandDef> {
|
|
72
|
+
let value: unknown;
|
|
73
|
+
try {
|
|
74
|
+
const module = (await import(pathToFileURL(info.file).href)) as Record<string, unknown>;
|
|
75
|
+
value = module[info.export];
|
|
76
|
+
} catch (error) {
|
|
77
|
+
throw failed(
|
|
78
|
+
`The plugin ${info.package} couldn't load its command "${info.command}": ${error instanceof Error ? error.message : String(error)}`,
|
|
79
|
+
);
|
|
80
|
+
}
|
|
81
|
+
const definition = value as PluginDefinition | undefined;
|
|
82
|
+
if (
|
|
83
|
+
definition === undefined ||
|
|
84
|
+
typeof definition !== "object" ||
|
|
85
|
+
typeof definition.run !== "function"
|
|
86
|
+
) {
|
|
87
|
+
throw failed(`The plugin ${info.package} exports no command definition for "${info.command}".`);
|
|
88
|
+
}
|
|
89
|
+
if (!stampServed(definition.contract, "cli-command")) {
|
|
90
|
+
throw new RpcError(
|
|
91
|
+
createDiagnostic("MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED", {
|
|
92
|
+
message: `The plugin ${info.package}@${info.version}'s command "${info.command}" was built for a cli-command contract this release doesn't serve.`,
|
|
93
|
+
}),
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
if (!Array.isArray(definition.path) || definition.path.join(" ") !== info.command) {
|
|
97
|
+
throw failed(
|
|
98
|
+
`The plugin ${info.package}'s command is "${String(definition.path)}", not "${info.command}" as its manifest says.`,
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
return defineCommand({
|
|
102
|
+
path: [...definition.path],
|
|
103
|
+
summary: typeof definition.summary === "string" ? definition.summary : info.command,
|
|
104
|
+
...(definition.args !== undefined ? { args: definition.args } : {}),
|
|
105
|
+
...(definition.flags !== undefined ? { flags: definition.flags } : {}),
|
|
106
|
+
output: { type: `the result of ${info.package}'s command`, topic: "cli" },
|
|
107
|
+
exits: [EXIT.failure],
|
|
108
|
+
example: definition.example ?? info.command,
|
|
109
|
+
// Telemetry never learns a plugin's command (D140 item 8): it records `plugin`.
|
|
110
|
+
telemetryName: "plugin",
|
|
111
|
+
async run(context) {
|
|
112
|
+
const controller = new AbortController();
|
|
113
|
+
const outcome = await runCommand(info, () =>
|
|
114
|
+
definition.run(
|
|
115
|
+
{ args: context.args, flags: context.flags, cwd: context.cwd, json: context.json },
|
|
116
|
+
{
|
|
117
|
+
signal: controller.signal,
|
|
118
|
+
log: (message) => context.log(String(message)),
|
|
119
|
+
progress: (line) => context.log(String(line)),
|
|
120
|
+
mostraVersion: cliVersion(),
|
|
121
|
+
call: (method, params) => {
|
|
122
|
+
const known = hostMethods.find((candidate) => candidate.method === method);
|
|
123
|
+
if (known === undefined || known.direction !== "client-to-instance") {
|
|
124
|
+
throw new RpcError(
|
|
125
|
+
createDiagnostic("MOSTRA_HOST_METHOD_UNKNOWN", {
|
|
126
|
+
message: `${method} isn't a method of the host protocol a client calls.`,
|
|
127
|
+
}),
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
return context.call(
|
|
131
|
+
known as MethodDefinition<unknown, unknown>,
|
|
132
|
+
known.params.parse(params),
|
|
133
|
+
);
|
|
134
|
+
},
|
|
135
|
+
},
|
|
136
|
+
),
|
|
137
|
+
);
|
|
138
|
+
if (typeof outcome !== "object" || outcome === null || !("result" in outcome)) {
|
|
139
|
+
throw failed(`The plugin ${info.package}'s command "${info.command}" returned no result.`);
|
|
140
|
+
}
|
|
141
|
+
const exit =
|
|
142
|
+
typeof outcome.exit === "number" &&
|
|
143
|
+
Number.isInteger(outcome.exit) &&
|
|
144
|
+
outcome.exit >= 0 &&
|
|
145
|
+
outcome.exit <= 255
|
|
146
|
+
? outcome.exit
|
|
147
|
+
: undefined;
|
|
148
|
+
return {
|
|
149
|
+
result: outcome.result,
|
|
150
|
+
...(typeof outcome.human === "string" ? { human: outcome.human } : {}),
|
|
151
|
+
...(exit !== undefined && exit !== 0 ? { exit } : {}),
|
|
152
|
+
};
|
|
153
|
+
},
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Runs a plugin's command: a diagnostic it throws (its own, or one a protocol call answered)
|
|
159
|
+
* stays as it is; anything else it throws is the plugin's failure, never Mostra's crash.
|
|
160
|
+
*/
|
|
161
|
+
async function runCommand<T>(info: PluginCommandInfo, run: () => Promise<T>): Promise<T> {
|
|
162
|
+
try {
|
|
163
|
+
return await run();
|
|
164
|
+
} catch (error) {
|
|
165
|
+
if (error instanceof RpcError) throw error;
|
|
166
|
+
throw failed(
|
|
167
|
+
`The plugin ${info.package}'s command "${info.command}" failed: ${error instanceof Error ? error.message : String(error)}`,
|
|
168
|
+
);
|
|
169
|
+
}
|
|
170
|
+
}
|