@toolmesh/agent-deck 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +433 -2
- package/bin/agent-deck.js +2 -0
- package/package.json +42 -4
- package/src/agents.mjs +87 -0
- package/src/cli.mjs +484 -0
- package/src/gitignore.mjs +109 -0
- package/src/hosts/claude-native.mjs +113 -0
- package/src/hosts/copy.mjs +279 -0
- package/src/init.mjs +65 -0
- package/src/install.mjs +395 -0
- package/src/lockfile.mjs +133 -0
- package/src/materialize.mjs +184 -0
- package/src/outdated.mjs +91 -0
- package/src/paths.mjs +63 -0
- package/src/plugins.mjs +158 -0
- package/src/profiles.mjs +80 -0
- package/src/project.mjs +110 -0
- package/src/sources/fetch.mjs +250 -0
- package/src/sources/locate.mjs +396 -0
- package/src/sources/spec.mjs +254 -0
- package/src/state.mjs +41 -0
- package/src/status.mjs +137 -0
- package/src/worktree.mjs +52 -0
package/src/install.mjs
ADDED
|
@@ -0,0 +1,395 @@
|
|
|
1
|
+
import { rewriteAgentsMd } from "./agents.mjs";
|
|
2
|
+
import { copiesToIgnore, writeGitignoreBlock } from "./gitignore.mjs";
|
|
3
|
+
import fs from "node:fs";
|
|
4
|
+
import os from "node:os";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { claudeBin, isEnabled, nativeInstall, nativeUninstall, releaseMarketplace } from "./hosts/claude-native.mjs";
|
|
7
|
+
import { copyInstall, removeInstalledFiles } from "./hosts/copy.mjs";
|
|
8
|
+
import { emptyLockfile, removeLockEntry, upsertLockEntry, writeLockfile } from "./lockfile.mjs";
|
|
9
|
+
import { materialize, pluginName, removeMaterialized, treeIntegrity, writeMarketplace } from "./materialize.mjs";
|
|
10
|
+
import { PLUGINS_FILE, pluginRel } from "./paths.mjs";
|
|
11
|
+
import { readPlugins } from "./plugins.mjs";
|
|
12
|
+
import { loadProject } from "./project.mjs";
|
|
13
|
+
import { fetchSource, pinDescriptor } from "./sources/fetch.mjs";
|
|
14
|
+
import { locatePlugin } from "./sources/locate.mjs";
|
|
15
|
+
import { descriptorFor, normalizeRequest, sameRequest } from "./sources/spec.mjs";
|
|
16
|
+
import { readState, writeState } from "./state.mjs";
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* One request → fetched, located, normalized under .ai/installed/plugins/<id>, and
|
|
20
|
+
* activated for each host. The lock pins what was resolved; the state records
|
|
21
|
+
* what was written on this machine.
|
|
22
|
+
*
|
|
23
|
+
* @typedef {import("./sources/spec.mjs").Request & { linked?: boolean }} Requested
|
|
24
|
+
* @typedef {import("./lockfile.mjs").LockEntry} LockEntry
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/** Claude loads `.ai/installed/` natively; cursor-agent ignores plugin paths from hooks, so Cursor copies. */
|
|
28
|
+
const DEFAULT_HOSTS = { claude: "native", cursor: "copy" };
|
|
29
|
+
|
|
30
|
+
export function hostModes(doc) {
|
|
31
|
+
return { ...DEFAULT_HOSTS, ...(doc?.hosts ?? {}) };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function cleanRequest(request) {
|
|
35
|
+
const { linked, ...rest } = request;
|
|
36
|
+
return normalizeRequest(rest);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The lock entry that still pins this request, if the request did not change. */
|
|
40
|
+
function pinFor(lock, request, update) {
|
|
41
|
+
if (update) return null;
|
|
42
|
+
const entry = lock?.plugins.find((p) => p.id === request.id);
|
|
43
|
+
if (!entry || request.linked) return null;
|
|
44
|
+
return sameRequest(entry.request, cleanRequest(request)) ? entry : null;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* @param {string} projectRoot
|
|
49
|
+
* @param {Requested} request
|
|
50
|
+
* @param {{ pin?: LockEntry | null, frozen?: boolean, fetch?: typeof fetchSource }} [options]
|
|
51
|
+
*/
|
|
52
|
+
export async function resolveRequest(projectRoot, request, options = {}) {
|
|
53
|
+
const fetch = options.fetch ?? fetchSource;
|
|
54
|
+
const pin = options.pin ?? null;
|
|
55
|
+
let descriptor = descriptorFor(request);
|
|
56
|
+
// `path:` is read from the real project. lockOnly and materialize build into a scratch dir.
|
|
57
|
+
if (descriptor.type === "path") descriptor = { ...descriptor, base: options.base ?? projectRoot };
|
|
58
|
+
if (pin) descriptor = pinDescriptor(descriptor, pin.resolved);
|
|
59
|
+
const fetched = await fetch(descriptor);
|
|
60
|
+
const located = await locatePlugin(fetched.root, request, { nested: pin?.nested ?? null, fetch });
|
|
61
|
+
const built = materialize(projectRoot, request.id, located, {
|
|
62
|
+
fallbackVersion: fallbackVersion(located.nested ?? fetched.resolved),
|
|
63
|
+
});
|
|
64
|
+
if (options.frozen && pin?.integrity && pin.integrity !== built.integrity) {
|
|
65
|
+
throw new Error(
|
|
66
|
+
`${request.id}: content does not match the lock (expected ${pin.integrity}, got ${built.integrity}). Run agent-deck update ${request.id} if the change is intended.`,
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
/** @type {LockEntry} */
|
|
70
|
+
const entry = {
|
|
71
|
+
id: request.id,
|
|
72
|
+
request: cleanRequest(request),
|
|
73
|
+
resolved: fetched.resolved,
|
|
74
|
+
...(located.nested ? { nested: located.nested } : {}),
|
|
75
|
+
integrity: built.integrity,
|
|
76
|
+
components: built.components,
|
|
77
|
+
agentsSnippets: built.agentsSnippets,
|
|
78
|
+
};
|
|
79
|
+
return { entry, built };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** A stable semver for a plugin that declares no version: the resolved revision. */
|
|
83
|
+
export function fallbackVersion(resolved) {
|
|
84
|
+
const tag = resolved.sha ?? resolved.sha256 ?? resolved.version ?? "unknown";
|
|
85
|
+
return `0.0.0-deck.${String(tag).replace(/[^0-9A-Za-z-]/g, "").slice(0, 12)}`;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** Host modes that can actually run here, with a warning for each fallback. */
|
|
89
|
+
function effectiveModes(modes) {
|
|
90
|
+
const effective = { ...modes };
|
|
91
|
+
const warnings = [];
|
|
92
|
+
let bin = null;
|
|
93
|
+
if (effective.claude === "native") {
|
|
94
|
+
bin = claudeBin();
|
|
95
|
+
if (!bin) {
|
|
96
|
+
effective.claude = "copy";
|
|
97
|
+
warnings.push("claude: `claude` CLI not found, using copy mode");
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
if (effective.cursor === "native") {
|
|
101
|
+
effective.cursor = "copy";
|
|
102
|
+
warnings.push("cursor: cursor-agent cannot load plugins natively, using copy mode");
|
|
103
|
+
}
|
|
104
|
+
return { effective, warnings, bin };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** One string per host mode, recorded in the state to notice a mode change. */
|
|
108
|
+
function modesKey(effective) {
|
|
109
|
+
return Object.keys(effective)
|
|
110
|
+
.sort()
|
|
111
|
+
.map((host) => `${host}:${effective[host]}`)
|
|
112
|
+
.join(",");
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Nothing to do for this plugin: the lock still pins it, and this machine
|
|
117
|
+
* already has that exact tree, activated the same way, with every file in place.
|
|
118
|
+
* Checked without fetching anything and without calling the claude CLI.
|
|
119
|
+
*/
|
|
120
|
+
function upToDate(projectRoot, request, pin, state, modes) {
|
|
121
|
+
if (!pin?.integrity || request.linked) return false;
|
|
122
|
+
const installed = state.plugins[request.id];
|
|
123
|
+
if (!installed || installed.integrity !== pin.integrity) return false;
|
|
124
|
+
if (installed.modes !== modesKey(effectiveModes(modes).effective)) return false;
|
|
125
|
+
if (!installed.paths.every((rel) => fs.existsSync(path.join(projectRoot, rel)))) return false;
|
|
126
|
+
if (installed.native?.includes("claude") && !isEnabled(projectRoot, pluginName(request.id))) return false;
|
|
127
|
+
const dir = path.join(projectRoot, pluginRel(request.id));
|
|
128
|
+
return fs.existsSync(dir) && treeIntegrity(dir) === pin.integrity;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** Activate a normalized plugin for every host, natively or by copy. */
|
|
132
|
+
function activate(projectRoot, id, pluginDir, modes, state, force, integrity) {
|
|
133
|
+
const { effective, warnings, bin } = effectiveModes(modes);
|
|
134
|
+
const previous = state.plugins[id];
|
|
135
|
+
if (previous) {
|
|
136
|
+
removeInstalledFiles(projectRoot, previous);
|
|
137
|
+
if (previous.native?.includes("claude") && effective.claude !== "native") {
|
|
138
|
+
const current = claudeBin();
|
|
139
|
+
if (current) nativeUninstall(current, projectRoot, pluginName(id));
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
const copyHosts = Object.entries(effective)
|
|
143
|
+
.filter(([, mode]) => mode === "copy")
|
|
144
|
+
.map(([host]) => host);
|
|
145
|
+
const result = copyInstall(projectRoot, id, pluginDir, { hosts: copyHosts, state, previous, force });
|
|
146
|
+
const entry = { paths: result.paths, mcpKeys: result.mcpKeys, integrity, modes: modesKey(effective) };
|
|
147
|
+
if (effective.claude === "native") {
|
|
148
|
+
writeMarketplace(projectRoot, new Set([...Object.keys(state.plugins), id]));
|
|
149
|
+
nativeInstall(bin, projectRoot, pluginName(id));
|
|
150
|
+
entry.native = ["claude"];
|
|
151
|
+
}
|
|
152
|
+
state.plugins[id] = entry;
|
|
153
|
+
const hookWarnings = result.warnings;
|
|
154
|
+
return [...warnings, ...hookWarnings];
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function deactivate(projectRoot, id, state) {
|
|
158
|
+
const previous = state.plugins[id];
|
|
159
|
+
if (previous) {
|
|
160
|
+
removeInstalledFiles(projectRoot, previous);
|
|
161
|
+
if (previous.native?.includes("claude")) {
|
|
162
|
+
const bin = claudeBin();
|
|
163
|
+
if (bin) nativeUninstall(bin, projectRoot, pluginName(id));
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
delete state.plugins[id];
|
|
167
|
+
removeMaterialized(projectRoot, id);
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* The copies agent-deck's .gitignore block lists (see `copiesToIgnore`), unless
|
|
172
|
+
* ai-plugin.json says `"gitignoreCopies": false` (the project commits them).
|
|
173
|
+
*/
|
|
174
|
+
function gitignoredCopies(projectRoot, state) {
|
|
175
|
+
let doc = null;
|
|
176
|
+
try {
|
|
177
|
+
doc = readPlugins(projectRoot);
|
|
178
|
+
} catch {}
|
|
179
|
+
return copiesToIgnore(projectRoot, state, doc, hostModes(doc));
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Rewrite agent-deck's .gitignore block from the locks on disk: after a profile that
|
|
184
|
+
* is not active gained or lost a pin, which installs nothing.
|
|
185
|
+
*/
|
|
186
|
+
export function refreshGitignore(projectRoot) {
|
|
187
|
+
writeGitignoreBlock(projectRoot, { copies: gitignoredCopies(projectRoot, readState(projectRoot)) });
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Write the lock, the state, and the agent-deck marketplace. `saveLock` lets a caller
|
|
192
|
+
* split one in-memory lock across files (the base and the active profile).
|
|
193
|
+
*/
|
|
194
|
+
function persist(projectRoot, lock, state, saveLock) {
|
|
195
|
+
const anyNative = Object.values(state.plugins).some((entry) => entry.native?.includes("claude"));
|
|
196
|
+
if (!anyNative) releaseMarketplace(projectRoot);
|
|
197
|
+
if (saveLock) saveLock(lock);
|
|
198
|
+
else writeLockfile(projectRoot, lock);
|
|
199
|
+
writeState(projectRoot, state);
|
|
200
|
+
writeMarketplace(projectRoot, Object.keys(state.plugins));
|
|
201
|
+
writeGitignoreBlock(projectRoot, { copies: gitignoredCopies(projectRoot, state) });
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Install one request (add, link, unlink-restore).
|
|
206
|
+
* @returns {Promise<{ entry: LockEntry, built: object, warnings: string[] }>}
|
|
207
|
+
*/
|
|
208
|
+
export async function installOne(projectRoot, doc, request, lock, options = {}) {
|
|
209
|
+
const state = readState(projectRoot);
|
|
210
|
+
let current = lock ?? emptyLockfile();
|
|
211
|
+
const pin = pinFor(current, request, options.update);
|
|
212
|
+
let resolved;
|
|
213
|
+
let warnings;
|
|
214
|
+
try {
|
|
215
|
+
resolved = await resolveRequest(projectRoot, request, { pin, fetch: options.fetch });
|
|
216
|
+
warnings = activate(
|
|
217
|
+
projectRoot,
|
|
218
|
+
request.id,
|
|
219
|
+
resolved.built.dir,
|
|
220
|
+
hostModes(doc),
|
|
221
|
+
state,
|
|
222
|
+
options.force,
|
|
223
|
+
resolved.built.integrity,
|
|
224
|
+
);
|
|
225
|
+
} catch (err) {
|
|
226
|
+
// A failed first install leaves nothing behind; a failed reinstall keeps the previous one.
|
|
227
|
+
if (!state.plugins[request.id]) removeMaterialized(projectRoot, request.id);
|
|
228
|
+
throw err;
|
|
229
|
+
}
|
|
230
|
+
const { entry, built } = resolved;
|
|
231
|
+
if (!request.linked) current = upsertLockEntry(current, entry);
|
|
232
|
+
persist(projectRoot, current, state, options.saveLock);
|
|
233
|
+
// AGENTS.md shows a linked plugin's snippets even though the lock does not hold it.
|
|
234
|
+
rewriteAgentsMd(projectRoot, request.linked ? upsertLockEntry(current, entry) : current);
|
|
235
|
+
return { entry, built, warnings, lock: current };
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* Remove a plugin's files, normalized tree, lock entry, and state.
|
|
240
|
+
*/
|
|
241
|
+
export function uninstallOne(projectRoot, id, lock, { keepFiles = false, saveLock } = {}) {
|
|
242
|
+
const state = readState(projectRoot);
|
|
243
|
+
if (keepFiles) {
|
|
244
|
+
delete state.plugins[id];
|
|
245
|
+
removeMaterialized(projectRoot, id);
|
|
246
|
+
} else {
|
|
247
|
+
deactivate(projectRoot, id, state);
|
|
248
|
+
}
|
|
249
|
+
const next = removeLockEntry(lock ?? emptyLockfile(), id);
|
|
250
|
+
persist(projectRoot, next, state, saveLock);
|
|
251
|
+
rewriteAgentsMd(projectRoot, next);
|
|
252
|
+
return next;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* Make the project match ai-plugin.json (+ local links), pinned by the lock.
|
|
257
|
+
* frozen: refuse any request the lock does not pin, and any drift.
|
|
258
|
+
* update: ignore pins (all, or the ids given) and resolve again.
|
|
259
|
+
*/
|
|
260
|
+
export async function installAll(projectRoot, doc, lock, options = {}) {
|
|
261
|
+
const state = readState(projectRoot);
|
|
262
|
+
let current = lock ? { ...lock, plugins: [...lock.plugins] } : emptyLockfile();
|
|
263
|
+
const wanted = new Set(doc.plugins.map((p) => p.id));
|
|
264
|
+
const updateIds = options.update === true ? null : new Set(options.update ?? []);
|
|
265
|
+
const isUpdate = (id) => options.update === true || updateIds?.has(id);
|
|
266
|
+
|
|
267
|
+
if (options.frozen) {
|
|
268
|
+
const unpinned = doc.plugins.filter((r) => !r.linked && !pinFor(current, r, false));
|
|
269
|
+
if (unpinned.length > 0) {
|
|
270
|
+
throw new Error(
|
|
271
|
+
`--frozen: ${unpinned.map((r) => r.id).join(", ")} not pinned by the lock. Run agent-deck install without --frozen.`,
|
|
272
|
+
);
|
|
273
|
+
}
|
|
274
|
+
const extra = current.plugins.filter((p) => !wanted.has(p.id));
|
|
275
|
+
if (extra.length > 0) {
|
|
276
|
+
throw new Error(`--frozen: the lock has ${extra.map((p) => p.id).join(", ")}, which ai-plugin.json no longer requests.`);
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
const removed = [];
|
|
281
|
+
for (const id of new Set([...Object.keys(state.plugins), ...current.plugins.map((p) => p.id)])) {
|
|
282
|
+
if (wanted.has(id)) continue;
|
|
283
|
+
deactivate(projectRoot, id, state);
|
|
284
|
+
current = removeLockEntry(current, id);
|
|
285
|
+
removed.push(id);
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
const results = [];
|
|
289
|
+
const linkedEntries = [];
|
|
290
|
+
for (const request of doc.plugins) {
|
|
291
|
+
const pin = pinFor(current, request, isUpdate(request.id));
|
|
292
|
+
const isPath = descriptorFor(request).type === "path";
|
|
293
|
+
// A directory in the project is re-read every install. Git pins can skip the fetch.
|
|
294
|
+
if (!isPath && upToDate(projectRoot, request, pin, state, hostModes(doc))) {
|
|
295
|
+
results.push({ entry: pin, warnings: [], pinned: true, linked: false, skipped: true });
|
|
296
|
+
continue;
|
|
297
|
+
}
|
|
298
|
+
const { entry, built } = await resolveRequest(projectRoot, request, {
|
|
299
|
+
pin,
|
|
300
|
+
frozen: options.frozen,
|
|
301
|
+
fetch: options.fetch,
|
|
302
|
+
});
|
|
303
|
+
if (isPath && pin?.integrity === built.integrity && upToDate(projectRoot, request, pin, state, hostModes(doc))) {
|
|
304
|
+
results.push({ entry: pin, warnings: [], pinned: true, linked: false, skipped: true });
|
|
305
|
+
continue;
|
|
306
|
+
}
|
|
307
|
+
const warnings = activate(projectRoot, request.id, built.dir, hostModes(doc), state, options.force, built.integrity);
|
|
308
|
+
if (request.linked) linkedEntries.push(entry);
|
|
309
|
+
else current = upsertLockEntry(current, entry);
|
|
310
|
+
persist(projectRoot, current, state, options.saveLock);
|
|
311
|
+
results.push({ entry, built, warnings, pinned: Boolean(pin), linked: Boolean(request.linked) });
|
|
312
|
+
}
|
|
313
|
+
persist(projectRoot, current, state, options.saveLock);
|
|
314
|
+
rewriteAgentsMd(projectRoot, linkedEntries.reduce(upsertLockEntry, current));
|
|
315
|
+
return { results, removed, lock: current };
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* Resolve and pin a request without installing it anywhere: for a profile that
|
|
320
|
+
* is not active. The normalized tree is built in a scratch folder, then dropped.
|
|
321
|
+
* @returns {Promise<LockEntry>}
|
|
322
|
+
*/
|
|
323
|
+
export async function lockOnly(request, pin, options = {}) {
|
|
324
|
+
const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "deck-lock-"));
|
|
325
|
+
try {
|
|
326
|
+
const { entry } = await resolveRequest(scratch, request, { pin, fetch: options.fetch, base: options.base });
|
|
327
|
+
return entry;
|
|
328
|
+
} finally {
|
|
329
|
+
fs.rmSync(scratch, { recursive: true, force: true });
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
export { pinFor };
|
|
334
|
+
|
|
335
|
+
/**
|
|
336
|
+
* Build the base and one profile, as pinned by their locks, into `out/<id>/`,
|
|
337
|
+
* without touching the project: no host activation, no lock, state, .gitignore,
|
|
338
|
+
* or AGENTS.md. Local links are ignored: the output is what is committed.
|
|
339
|
+
* A plugin already in `out` with the locked integrity is kept as is; folders of
|
|
340
|
+
* plugins no longer requested are removed.
|
|
341
|
+
*
|
|
342
|
+
* @param {string} projectRoot
|
|
343
|
+
* @param {{ out: string, profile?: string | null, fetch?: typeof fetchSource }} options
|
|
344
|
+
*/
|
|
345
|
+
export async function materializeTo(projectRoot, options) {
|
|
346
|
+
const out = path.resolve(options.out);
|
|
347
|
+
const project = loadProject(projectRoot, { profile: options.profile ?? null });
|
|
348
|
+
if (!project.exists) throw new Error(`No ${PLUGINS_FILE}. Run agent-deck add <source>.`);
|
|
349
|
+
// Links are local: the committed requests are what is built, even when a link overrides one.
|
|
350
|
+
const committed = [...project.base.plugins, ...(project.prof?.plugins ?? [])];
|
|
351
|
+
const unpinned = committed.filter((r) => !pinFor(project.lock, r, false)?.integrity);
|
|
352
|
+
if (unpinned.length > 0) {
|
|
353
|
+
throw new Error(`${unpinned.map((r) => r.id).join(", ")} not pinned by a lock. Run agent-deck install (or agent-deck add) first.`);
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
fs.mkdirSync(out, { recursive: true });
|
|
357
|
+
const wanted = new Set(committed.map((r) => r.id));
|
|
358
|
+
for (const entry of fs.readdirSync(out, { withFileTypes: true })) {
|
|
359
|
+
const dir = path.join(out, entry.name);
|
|
360
|
+
const isPlugin = fs.existsSync(path.join(dir, ".claude-plugin")) || fs.existsSync(path.join(dir, ".cursor-plugin"));
|
|
361
|
+
if (entry.isDirectory() && isPlugin && !wanted.has(entry.name)) fs.rmSync(dir, { recursive: true, force: true });
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "deck-materialize-"));
|
|
365
|
+
const plugins = [];
|
|
366
|
+
try {
|
|
367
|
+
for (const request of committed) {
|
|
368
|
+
const pin = pinFor(project.lock, request, false);
|
|
369
|
+
const dest = path.join(out, request.id);
|
|
370
|
+
let skipped = false;
|
|
371
|
+
if (fs.existsSync(dest) && treeIntegrity(dest) === pin.integrity) {
|
|
372
|
+
skipped = true;
|
|
373
|
+
} else {
|
|
374
|
+
const { built } = await resolveRequest(scratch, request, {
|
|
375
|
+
pin,
|
|
376
|
+
frozen: true,
|
|
377
|
+
fetch: options.fetch,
|
|
378
|
+
base: projectRoot,
|
|
379
|
+
});
|
|
380
|
+
fs.rmSync(dest, { recursive: true, force: true });
|
|
381
|
+
fs.cpSync(built.dir, dest, { recursive: true });
|
|
382
|
+
}
|
|
383
|
+
plugins.push({ id: request.id, path: dest, integrity: pin.integrity, components: pin.components, skipped });
|
|
384
|
+
}
|
|
385
|
+
} finally {
|
|
386
|
+
fs.rmSync(scratch, { recursive: true, force: true });
|
|
387
|
+
}
|
|
388
|
+
const prompt = project.profileRoot ? path.join(project.profileRoot, "prompt.md") : null;
|
|
389
|
+
return {
|
|
390
|
+
profile: project.profile,
|
|
391
|
+
prompt: prompt && fs.existsSync(prompt) ? prompt : null,
|
|
392
|
+
out,
|
|
393
|
+
plugins,
|
|
394
|
+
};
|
|
395
|
+
}
|
package/src/lockfile.mjs
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import { LOCK_FILE, lockPath } from "./paths.mjs";
|
|
3
|
+
import { normalizeRequest } from "./sources/spec.mjs";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* ai-plugin.lock.json — committed, like package-lock.json.
|
|
7
|
+
*
|
|
8
|
+
* Each entry pins what a request resolved to (commit SHA, npm version, archive
|
|
9
|
+
* digest), the integrity of the normalized plugin tree, and its components.
|
|
10
|
+
* Nothing machine-specific: what agent-deck wrote on disk lives in .ai/installed/state.json.
|
|
11
|
+
*
|
|
12
|
+
* @typedef {{ skill: string, body: string }} AgentsSnippet
|
|
13
|
+
* @typedef {import("./sources/fetch.mjs").Resolved} Resolved
|
|
14
|
+
* @typedef {{ skills: string[], agents: string[], commands: string[], rules: string[], hooks: boolean, mcp: string[] }} ComponentSummary
|
|
15
|
+
* @typedef {{ id: string, request: import("./sources/spec.mjs").Request, resolved: Resolved, nested?: Resolved, integrity?: string, components: ComponentSummary, agentsSnippets: AgentsSnippet[] }} LockEntry
|
|
16
|
+
* @typedef {{ lockfileVersion: number, writeAgentsMd: boolean, plugins: LockEntry[] }} Lockfile
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
export const LOCKFILE_FORMAT = 1;
|
|
20
|
+
|
|
21
|
+
export function emptyLockfile() {
|
|
22
|
+
return { lockfileVersion: LOCKFILE_FORMAT, writeAgentsMd: true, plugins: [] };
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const EMPTY_COMPONENTS = { skills: [], agents: [], commands: [], rules: [], hooks: false, mcp: [] };
|
|
26
|
+
|
|
27
|
+
function normalizeSnippets(list, where) {
|
|
28
|
+
if (list == null) return [];
|
|
29
|
+
if (!Array.isArray(list)) throw new Error(`${where}.agentsSnippets must be an array`);
|
|
30
|
+
return list.map((snippet, i) => {
|
|
31
|
+
if (!snippet?.skill || typeof snippet.body !== "string") {
|
|
32
|
+
throw new Error(`${where}.agentsSnippets[${i}] requires skill and body`);
|
|
33
|
+
}
|
|
34
|
+
return { skill: snippet.skill, body: snippet.body };
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function normalizeResolved(resolved, where) {
|
|
39
|
+
if (!resolved || typeof resolved !== "object" || !resolved.type) {
|
|
40
|
+
throw new Error(`${where}.resolved must say what was fetched`);
|
|
41
|
+
}
|
|
42
|
+
switch (resolved.type) {
|
|
43
|
+
case "git":
|
|
44
|
+
case "local":
|
|
45
|
+
if (!resolved.sha) throw new Error(`${where}.resolved needs a commit sha`);
|
|
46
|
+
break;
|
|
47
|
+
case "path":
|
|
48
|
+
if (!resolved.path || resolved.path.startsWith("/") || resolved.path.split("/").includes("..")) {
|
|
49
|
+
throw new Error(`${where}.resolved.path must stay inside the project`);
|
|
50
|
+
}
|
|
51
|
+
break;
|
|
52
|
+
case "npm":
|
|
53
|
+
if (!resolved.package || !resolved.version) throw new Error(`${where}.resolved needs package and version`);
|
|
54
|
+
break;
|
|
55
|
+
case "archive":
|
|
56
|
+
if (!resolved.url || !resolved.sha256) throw new Error(`${where}.resolved needs url and sha256`);
|
|
57
|
+
break;
|
|
58
|
+
default:
|
|
59
|
+
throw new Error(`${where}.resolved has unknown type "${resolved.type}"`);
|
|
60
|
+
}
|
|
61
|
+
return { ...resolved };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function normalizeEntry(plugin, index) {
|
|
65
|
+
const where = `${LOCK_FILE} plugins[${index}]`;
|
|
66
|
+
if (!plugin || typeof plugin !== "object") throw new Error(`${where} is not an object`);
|
|
67
|
+
const request = normalizeRequest(plugin.request, `${where}.request`);
|
|
68
|
+
if (plugin.id !== request.id) throw new Error(`${where}: id and request.id differ`);
|
|
69
|
+
return {
|
|
70
|
+
id: request.id,
|
|
71
|
+
request,
|
|
72
|
+
resolved: normalizeResolved(plugin.resolved, where),
|
|
73
|
+
...(plugin.nested ? { nested: normalizeResolved(plugin.nested, `${where}.nested`) } : {}),
|
|
74
|
+
...(typeof plugin.integrity === "string" && plugin.integrity ? { integrity: plugin.integrity } : {}),
|
|
75
|
+
components: { ...EMPTY_COMPONENTS, ...(plugin.components ?? {}) },
|
|
76
|
+
agentsSnippets: normalizeSnippets(plugin.agentsSnippets, where),
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Normalize and validate a parsed lockfile.
|
|
82
|
+
* @returns {Lockfile}
|
|
83
|
+
*/
|
|
84
|
+
export function normalizeLockfile(raw) {
|
|
85
|
+
if (!raw || typeof raw !== "object" || !Array.isArray(raw.plugins)) {
|
|
86
|
+
throw new Error(`Invalid lockfile at ${LOCK_FILE}`);
|
|
87
|
+
}
|
|
88
|
+
if (typeof raw.lockfileVersion !== "number") {
|
|
89
|
+
throw new Error(`${LOCK_FILE} is missing lockfileVersion (expected ${LOCKFILE_FORMAT})`);
|
|
90
|
+
}
|
|
91
|
+
if (raw.lockfileVersion !== LOCKFILE_FORMAT) {
|
|
92
|
+
throw new Error(
|
|
93
|
+
`${LOCK_FILE} has lockfileVersion ${raw.lockfileVersion}; this CLI supports ${LOCKFILE_FORMAT}`,
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
return {
|
|
97
|
+
lockfileVersion: LOCKFILE_FORMAT,
|
|
98
|
+
writeAgentsMd: raw.writeAgentsMd !== false,
|
|
99
|
+
plugins: raw.plugins.map(normalizeEntry),
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
export function readLockfile(projectRoot) {
|
|
104
|
+
const file = lockPath(projectRoot);
|
|
105
|
+
if (!fs.existsSync(file)) return null;
|
|
106
|
+
return normalizeLockfile(JSON.parse(fs.readFileSync(file, "utf8")));
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export function writeLockfile(projectRoot, lock) {
|
|
110
|
+
const file = lockPath(projectRoot);
|
|
111
|
+
const normalized = normalizeLockfile({
|
|
112
|
+
lockfileVersion: LOCKFILE_FORMAT,
|
|
113
|
+
writeAgentsMd: lock.writeAgentsMd !== false,
|
|
114
|
+
plugins: lock.plugins,
|
|
115
|
+
});
|
|
116
|
+
normalized.plugins.sort((a, b) => a.id.localeCompare(b.id));
|
|
117
|
+
fs.writeFileSync(file, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
|
|
118
|
+
return file;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export function setWriteAgentsMd(lock, writeAgentsMd) {
|
|
122
|
+
return { ...lock, writeAgentsMd: writeAgentsMd !== false };
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export function upsertLockEntry(lock, record) {
|
|
126
|
+
const plugins = lock.plugins.filter((plugin) => plugin.id !== record.id);
|
|
127
|
+
plugins.push(record);
|
|
128
|
+
return { ...lock, plugins };
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export function removeLockEntry(lock, id) {
|
|
132
|
+
return { ...lock, plugins: lock.plugins.filter((plugin) => plugin.id !== id) };
|
|
133
|
+
}
|