@mostra/runtime 0.14.0 → 0.15.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin.js +1 -1
- package/dist/child-protocol-CPXR6pMu.js +13 -0
- package/dist/child-protocol-CPXR6pMu.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/{instance-CFTw3g-c.js → instance-Bw1BxctF.js} +2581 -189
- package/dist/instance-Bw1BxctF.js.map +1 -0
- package/dist/plugins/child/host.d.ts +1 -0
- package/dist/plugins/child/host.js +165 -0
- package/dist/plugins/child/host.js.map +1 -0
- 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/skill/SKILL.md +4 -2
- package/dist/skill/references/mcp.md +2 -2
- package/dist/skill/references/plugins.md +51 -0
- package/package.json +10 -7
- package/src/deps/index.ts +407 -90
- package/src/deps/installer.ts +53 -10
- package/src/deps/lock.ts +74 -2
- package/src/home/settings.ts +3 -0
- package/src/instance/index.ts +57 -0
- package/src/packs/index.ts +7 -0
- package/src/packs/methods.ts +49 -0
- package/src/packs/packs.ts +706 -0
- package/src/packs/read.ts +759 -0
- package/src/platform/index.ts +1 -0
- package/src/platform/shell.ts +14 -0
- package/src/plugins/child/host.ts +231 -0
- package/src/plugins/child-protocol.ts +68 -0
- package/src/plugins/index.ts +7 -0
- package/src/plugins/location.ts +109 -0
- package/src/plugins/methods.ts +269 -0
- package/src/plugins/plugins.ts +1396 -0
- package/src/publish/publisher.ts +71 -3
- package/dist/instance-CFTw3g-c.js.map +0 -1
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The plugin system's methods of the host protocol (INTERFACES §14): `plugin/validate`,
|
|
3
|
+
* `plugin/add`, `plugin/list`, `plugin/remove`, `plugin/export` and `plugin/commands`
|
|
4
|
+
* (`pack/add` is the packs module's). Each that names an artifact runs in its source path's queue, as its publishes and
|
|
5
|
+
* `deps/add` do, through the publisher; the home's own plugins have one queue of their own (the
|
|
6
|
+
* working lockfile `home:plugins`).
|
|
7
|
+
*/
|
|
8
|
+
import { randomBytes } from "node:crypto";
|
|
9
|
+
import { existsSync } from "node:fs";
|
|
10
|
+
import { mkdir, readdir, readFile, rmdir, stat, writeFile } from "node:fs/promises";
|
|
11
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
12
|
+
import {
|
|
13
|
+
checkArtifactPath,
|
|
14
|
+
createDiagnostic,
|
|
15
|
+
type PluginFinding,
|
|
16
|
+
pluginAddMethod,
|
|
17
|
+
pluginCommandsMethod,
|
|
18
|
+
pluginExportMethod,
|
|
19
|
+
pluginListMethod,
|
|
20
|
+
pluginRemoveMethod,
|
|
21
|
+
pluginValidateMethod,
|
|
22
|
+
RpcError,
|
|
23
|
+
type SourceRef,
|
|
24
|
+
} from "@mostra/protocol";
|
|
25
|
+
import { requestKey } from "../ledger/index.ts";
|
|
26
|
+
import type { Log } from "../log.ts";
|
|
27
|
+
import { removeTree, renamePath } from "../platform/index.ts";
|
|
28
|
+
import { handler, type MethodHandler } from "../protocol-server/index.ts";
|
|
29
|
+
import { canonicalRef, type Publisher } from "../publish/index.ts";
|
|
30
|
+
import type { Plugins, Scope } from "./plugins.ts";
|
|
31
|
+
|
|
32
|
+
const usage = (message: string): RpcError =>
|
|
33
|
+
new RpcError(createDiagnostic("MOSTRA_PLUGIN_SCOPE_INVALID", { message }));
|
|
34
|
+
|
|
35
|
+
/** The handlers of the plugin system's methods. */
|
|
36
|
+
export function pluginMethods(options: {
|
|
37
|
+
readonly plugins: () => Plugins;
|
|
38
|
+
readonly publisher: () => Publisher;
|
|
39
|
+
readonly log: Log;
|
|
40
|
+
/** An artifact's dependencies changed (a dev session reloads, D140 item 12). */
|
|
41
|
+
readonly dependenciesChanged?: (artifact: SourceRef) => void;
|
|
42
|
+
}): MethodHandler[] {
|
|
43
|
+
/** Runs `task` in the scope the params name: exactly one of `artifact` and `home`. */
|
|
44
|
+
const inScope = <T>(
|
|
45
|
+
params: { readonly artifact?: SourceRef; readonly home?: boolean },
|
|
46
|
+
task: (scope: Scope) => Promise<T>,
|
|
47
|
+
): Promise<T> => {
|
|
48
|
+
if ((params.artifact === undefined) === (params.home !== true)) {
|
|
49
|
+
throw usage("Name exactly one of an artifact (--artifact) and the home (--global).");
|
|
50
|
+
}
|
|
51
|
+
if (params.home === true) return options.publisher().withHome(() => task({ kind: "home" }));
|
|
52
|
+
return options
|
|
53
|
+
.publisher()
|
|
54
|
+
.withArtifact(params.artifact as SourceRef, ({ target }) =>
|
|
55
|
+
task({ kind: "artifact", target }),
|
|
56
|
+
);
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
return [
|
|
60
|
+
handler(pluginValidateMethod, (params) =>
|
|
61
|
+
options.plugins().validate(params.path, params.acceptLicenses ?? []),
|
|
62
|
+
),
|
|
63
|
+
|
|
64
|
+
handler(pluginAddMethod, async (params) => {
|
|
65
|
+
const result = await inScope(params, (scope) =>
|
|
66
|
+
options.plugins().add(scope, {
|
|
67
|
+
packages: params.packages,
|
|
68
|
+
accept: params.acceptLicenses ?? [],
|
|
69
|
+
request: requestKey("plugin/add", params),
|
|
70
|
+
}),
|
|
71
|
+
);
|
|
72
|
+
if (params.artifact !== undefined) options.dependenciesChanged?.(params.artifact);
|
|
73
|
+
return result;
|
|
74
|
+
}),
|
|
75
|
+
|
|
76
|
+
handler(pluginListMethod, (params) =>
|
|
77
|
+
inScope(params, (scope) => options.plugins().list(scope)),
|
|
78
|
+
),
|
|
79
|
+
|
|
80
|
+
handler(pluginRemoveMethod, async (params) => {
|
|
81
|
+
const result = await inScope(params, (scope) =>
|
|
82
|
+
options.plugins().remove(scope, {
|
|
83
|
+
packages: params.packages,
|
|
84
|
+
request: requestKey("plugin/remove", params),
|
|
85
|
+
}),
|
|
86
|
+
);
|
|
87
|
+
if (params.artifact !== undefined) options.dependenciesChanged?.(params.artifact);
|
|
88
|
+
return result;
|
|
89
|
+
}),
|
|
90
|
+
|
|
91
|
+
handler(pluginCommandsMethod, async (params) => {
|
|
92
|
+
if (params.artifact === undefined)
|
|
93
|
+
return { commands: await options.plugins().commands(undefined) };
|
|
94
|
+
return options
|
|
95
|
+
.publisher()
|
|
96
|
+
.withArtifact(params.artifact, async ({ target }) => ({
|
|
97
|
+
commands: await options.plugins().commands(target),
|
|
98
|
+
}))
|
|
99
|
+
.catch(async (error: unknown) => {
|
|
100
|
+
// A directory that isn't an artifact (the CLI asks from wherever it runs) has the
|
|
101
|
+
// home's commands only.
|
|
102
|
+
if (error instanceof RpcError && error.diagnostic.code.startsWith("MOSTRA_ARTIFACT_")) {
|
|
103
|
+
return { commands: await options.plugins().commands(undefined) };
|
|
104
|
+
}
|
|
105
|
+
throw error;
|
|
106
|
+
});
|
|
107
|
+
}),
|
|
108
|
+
|
|
109
|
+
handler(pluginExportMethod, async (params) => {
|
|
110
|
+
const { detail, summary, versionDir } = await options
|
|
111
|
+
.publisher()
|
|
112
|
+
.exportable({ ...params, artifact: canonicalRef(params.artifact) });
|
|
113
|
+
// The version's own plugins, as its lockfile froze them, and the home's (D172 item 9).
|
|
114
|
+
const exporters = await options.plugins().exporters({
|
|
115
|
+
artifactId: detail.id,
|
|
116
|
+
versionDir,
|
|
117
|
+
...(detail.source !== undefined ? { sourceDir: detail.source } : {}),
|
|
118
|
+
});
|
|
119
|
+
const exporter = exporters.find((candidate) => candidate.id === params.exporter);
|
|
120
|
+
if (exporter === undefined) {
|
|
121
|
+
throw new RpcError(
|
|
122
|
+
createDiagnostic("MOSTRA_PLUGIN_EXPORTER_UNKNOWN", {
|
|
123
|
+
message: `No plugin of ${detail.title}'s version ${summary.number} or of the home contributes the exporter "${params.exporter}"; the exporters available are bundle${exporters.map((candidate) => `, ${candidate.id}`).join("")}.`,
|
|
124
|
+
}),
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
if (!isAbsolute(params.out)) {
|
|
128
|
+
throw new RpcError(
|
|
129
|
+
createDiagnostic("MOSTRA_HOST_INVALID_PARAMS", {
|
|
130
|
+
message: "out must be an absolute path.",
|
|
131
|
+
}),
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
const existing = await stat(params.out).catch(() => undefined);
|
|
135
|
+
if (
|
|
136
|
+
existing !== undefined &&
|
|
137
|
+
(!existing.isDirectory() || (await readdir(params.out)).length > 0)
|
|
138
|
+
) {
|
|
139
|
+
throw new RpcError(
|
|
140
|
+
createDiagnostic("MOSTRA_ARTIFACT_DIR_NOT_EMPTY", {
|
|
141
|
+
message: `${params.out} already exists${existing.isDirectory() ? " and isn't empty" : ""}.`,
|
|
142
|
+
}),
|
|
143
|
+
);
|
|
144
|
+
}
|
|
145
|
+
const registry = await readFile(join(versionDir, "registry.json"), "utf8")
|
|
146
|
+
.then((text) => JSON.parse(text) as Record<string, unknown>)
|
|
147
|
+
.catch(() => ({}));
|
|
148
|
+
const answer = await options.plugins().runExport({
|
|
149
|
+
exporter,
|
|
150
|
+
versionDir,
|
|
151
|
+
version: {
|
|
152
|
+
artifactId: detail.id,
|
|
153
|
+
versionId: summary.id,
|
|
154
|
+
number: summary.number,
|
|
155
|
+
title: detail.title,
|
|
156
|
+
...(detail.description !== undefined ? { description: detail.description } : {}),
|
|
157
|
+
manifest: detail.manifest ?? {},
|
|
158
|
+
registry,
|
|
159
|
+
server: existsSync(join(versionDir, "server", "entry.mjs")),
|
|
160
|
+
publishedAt: summary.publishedAt,
|
|
161
|
+
},
|
|
162
|
+
options: params.options ?? {},
|
|
163
|
+
});
|
|
164
|
+
const fail = (reason: string): RpcError =>
|
|
165
|
+
new RpcError(
|
|
166
|
+
createDiagnostic("MOSTRA_PLUGIN_FAILED", {
|
|
167
|
+
message: `The exporter ${exporter.id} (${exporter.package}) ${reason}. Nothing was written.`,
|
|
168
|
+
}),
|
|
169
|
+
);
|
|
170
|
+
// Every file stays inside the export, with a name every system holds, and no file stands
|
|
171
|
+
// where another needs a directory; nothing is written until all of them are checked.
|
|
172
|
+
const planned: { path: string; data: Buffer | string }[] = [];
|
|
173
|
+
const seen = new Set<string>();
|
|
174
|
+
for (const file of answer.files) {
|
|
175
|
+
const check = checkArtifactPath(file.path);
|
|
176
|
+
if (!check.ok) {
|
|
177
|
+
throw fail(
|
|
178
|
+
`returned the file "${file.path.slice(0, 200)}", which isn't a path inside its output`,
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
if (seen.has(check.path.toLowerCase())) {
|
|
182
|
+
throw fail(`returned the file "${check.path}" twice`);
|
|
183
|
+
}
|
|
184
|
+
seen.add(check.path.toLowerCase());
|
|
185
|
+
planned.push({
|
|
186
|
+
path: check.path,
|
|
187
|
+
data: "text" in file ? file.text : Buffer.from(file.base64, "base64"),
|
|
188
|
+
});
|
|
189
|
+
}
|
|
190
|
+
for (const file of planned) {
|
|
191
|
+
const segments = file.path.toLowerCase().split("/");
|
|
192
|
+
for (let length = 1; length < segments.length; length += 1) {
|
|
193
|
+
if (seen.has(segments.slice(0, length).join("/"))) {
|
|
194
|
+
throw fail(
|
|
195
|
+
`returned both "${segments.slice(0, length).join("/")}" and "${file.path}", a file where a directory must be`,
|
|
196
|
+
);
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
if (answer.output.layout === "file" && planned.length !== 1) {
|
|
201
|
+
throw fail(
|
|
202
|
+
`writes one file (its output's layout is "file"), and returned ${planned.length}`,
|
|
203
|
+
);
|
|
204
|
+
}
|
|
205
|
+
// Written beside `out` and moved into place in one rename: a failure leaves nothing.
|
|
206
|
+
const scratch = `${params.out}.mostra-${randomBytes(6).toString("hex")}.tmp`;
|
|
207
|
+
const written: string[] = [];
|
|
208
|
+
try {
|
|
209
|
+
if (answer.output.layout === "file") {
|
|
210
|
+
const only = planned[0] as { path: string; data: Buffer | string };
|
|
211
|
+
await mkdir(dirname(params.out), { recursive: true });
|
|
212
|
+
await writeFile(scratch, only.data);
|
|
213
|
+
if (existing !== undefined) await rmdir(params.out);
|
|
214
|
+
await renamePath(scratch, params.out);
|
|
215
|
+
written.push(params.out);
|
|
216
|
+
} else {
|
|
217
|
+
for (const file of planned) {
|
|
218
|
+
const path = join(scratch, ...file.path.split("/"));
|
|
219
|
+
await mkdir(dirname(path), { recursive: true });
|
|
220
|
+
await writeFile(path, file.data);
|
|
221
|
+
written.push(join(params.out, ...file.path.split("/")));
|
|
222
|
+
}
|
|
223
|
+
await mkdir(dirname(params.out), { recursive: true });
|
|
224
|
+
if (existing !== undefined) await rmdir(params.out);
|
|
225
|
+
await renamePath(scratch, params.out);
|
|
226
|
+
}
|
|
227
|
+
} catch (problem) {
|
|
228
|
+
await removeTree(scratch).catch(() => undefined);
|
|
229
|
+
throw fail(
|
|
230
|
+
`couldn't be written (${problem instanceof Error ? problem.message : String(problem)})`,
|
|
231
|
+
);
|
|
232
|
+
}
|
|
233
|
+
options.log.info("plugins.exported", {
|
|
234
|
+
artifactId: detail.id,
|
|
235
|
+
versionId: summary.id,
|
|
236
|
+
exporter: exporter.id,
|
|
237
|
+
files: written.length,
|
|
238
|
+
});
|
|
239
|
+
const findings: PluginFinding[] = answer.findings.flatMap((value: unknown) => {
|
|
240
|
+
const finding = value as Partial<PluginFinding>;
|
|
241
|
+
if (typeof finding.code !== "string" || typeof finding.message !== "string") return [];
|
|
242
|
+
return [
|
|
243
|
+
{
|
|
244
|
+
code: finding.code.slice(0, 64),
|
|
245
|
+
severity:
|
|
246
|
+
finding.severity === "error" || finding.severity === "hint"
|
|
247
|
+
? finding.severity
|
|
248
|
+
: "warning",
|
|
249
|
+
message: finding.message,
|
|
250
|
+
...(typeof finding.hint === "string" ? { hint: finding.hint } : {}),
|
|
251
|
+
},
|
|
252
|
+
];
|
|
253
|
+
});
|
|
254
|
+
const entry =
|
|
255
|
+
answer.output.layout === "file"
|
|
256
|
+
? params.out
|
|
257
|
+
: answer.entry !== undefined && seen.has(answer.entry.toLowerCase())
|
|
258
|
+
? join(params.out, ...answer.entry.split("/"))
|
|
259
|
+
: undefined;
|
|
260
|
+
return {
|
|
261
|
+
files: written,
|
|
262
|
+
...(entry !== undefined ? { entry } : {}),
|
|
263
|
+
versionId: summary.id,
|
|
264
|
+
exporter: { id: exporter.id, package: exporter.package },
|
|
265
|
+
findings,
|
|
266
|
+
};
|
|
267
|
+
}),
|
|
268
|
+
];
|
|
269
|
+
}
|