@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
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { spawnSync } from "node:child_process";
|
|
3
|
+
import fs from "node:fs";
|
|
4
|
+
import os from "node:os";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { copyWorkingTree } from "../worktree.mjs";
|
|
7
|
+
import { safeSegment } from "../paths.mjs";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Fetch a descriptor into the agent-deck cache and say exactly what was fetched.
|
|
11
|
+
* @typedef {import("./spec.mjs").Descriptor} Descriptor
|
|
12
|
+
* @typedef {{ type: "git", url: string, sha: string }
|
|
13
|
+
* | { type: "npm", package: string, version: string, integrity?: string }
|
|
14
|
+
* | { type: "archive", url: string, sha256: string }
|
|
15
|
+
* | { type: "path", path: string }
|
|
16
|
+
* | { type: "local", path: string, sha: string }} Resolved
|
|
17
|
+
* @returns {Promise<{ root: string, resolved: Resolved }>}
|
|
18
|
+
*/
|
|
19
|
+
export async function fetchSource(descriptor) {
|
|
20
|
+
switch (descriptor.type) {
|
|
21
|
+
case "git":
|
|
22
|
+
return fetchGit(descriptor);
|
|
23
|
+
case "npm":
|
|
24
|
+
return fetchNpm(descriptor);
|
|
25
|
+
case "archive":
|
|
26
|
+
return fetchArchive(descriptor);
|
|
27
|
+
case "path": {
|
|
28
|
+
const abs = resolveProjectPath(descriptor.base, descriptor.path);
|
|
29
|
+
const { root } = copyWorkingTree(abs);
|
|
30
|
+
return { root, resolved: { type: "path", path: descriptor.path } };
|
|
31
|
+
}
|
|
32
|
+
case "local": {
|
|
33
|
+
const { root, resolved } = copyWorkingTree(descriptor.path);
|
|
34
|
+
return { root, resolved: { type: "local", path: path.resolve(descriptor.path), sha: resolved } };
|
|
35
|
+
}
|
|
36
|
+
default:
|
|
37
|
+
throw new Error(`Cannot fetch source type "${descriptor.type}"`);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export function cacheRoot() {
|
|
42
|
+
return process.env.AGENT_DECK_CACHE || path.join(os.homedir(), ".cache", "agent-deck");
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function run(cmd, args, opts = {}) {
|
|
46
|
+
const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...opts });
|
|
47
|
+
if (r.error) throw new Error(`${cmd}: ${r.error.message}`);
|
|
48
|
+
if (r.status !== 0) {
|
|
49
|
+
throw new Error((r.stderr || r.stdout || "").trim() || `${cmd} ${args.join(" ")} failed`);
|
|
50
|
+
}
|
|
51
|
+
return r.stdout;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function tryRun(cmd, args, opts = {}) {
|
|
55
|
+
const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...opts });
|
|
56
|
+
return r.status === 0;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const SHA = /^[0-9a-f]{40}$/;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* `AGENT_DECK_LOCAL_owner__repo` points a GitHub repository at a local checkout.
|
|
63
|
+
* The current branch and `HEAD` read the working tree, including uncommitted
|
|
64
|
+
* files; any other ref is checked out from a local clone.
|
|
65
|
+
*/
|
|
66
|
+
function localCheckout(repo) {
|
|
67
|
+
if (!repo) return null;
|
|
68
|
+
const key = `AGENT_DECK_LOCAL_${repo.replaceAll("/", "__")}`;
|
|
69
|
+
const value = process.env[key];
|
|
70
|
+
if (!value) return null;
|
|
71
|
+
if (!fs.existsSync(path.join(value, ".git"))) {
|
|
72
|
+
throw new Error(`${key} does not point at a git checkout: ${value}`);
|
|
73
|
+
}
|
|
74
|
+
return value;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function headCommit(dir) {
|
|
78
|
+
return run("git", ["-C", dir, "rev-parse", "HEAD"]).trim();
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Shallow fetch of one ref or commit. A commit already checked out is not
|
|
83
|
+
* fetched again: a SHA never moves.
|
|
84
|
+
*/
|
|
85
|
+
async function fetchGit(descriptor) {
|
|
86
|
+
const want = descriptor.sha || descriptor.ref || "HEAD";
|
|
87
|
+
const local = localCheckout(descriptor.repo);
|
|
88
|
+
if (local) {
|
|
89
|
+
const branch = run("git", ["-C", local, "rev-parse", "--abbrev-ref", "HEAD"]).trim();
|
|
90
|
+
if (!descriptor.sha && (want === "HEAD" || want === branch)) {
|
|
91
|
+
const { root, resolved } = copyWorkingTree(local);
|
|
92
|
+
return { root, resolved: { type: "git", url: descriptor.url, sha: resolved } };
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const dest = path.join(cacheRoot(), "git", safeSegment(descriptor.url), safeSegment(want));
|
|
97
|
+
if (fs.existsSync(path.join(dest, ".git")) && SHA.test(want) && headCommit(dest) === want) {
|
|
98
|
+
return { root: dest, resolved: { type: "git", url: descriptor.url, sha: want } };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
fs.rmSync(dest, { recursive: true, force: true });
|
|
102
|
+
fs.mkdirSync(dest, { recursive: true });
|
|
103
|
+
const origin = local ?? descriptor.url;
|
|
104
|
+
run("git", ["-C", dest, "init", "-q"]);
|
|
105
|
+
run("git", ["-C", dest, "remote", "add", "origin", origin]);
|
|
106
|
+
const shallow = tryRun("git", ["-C", dest, "fetch", "-q", "--depth", "1", "origin", want]);
|
|
107
|
+
if (shallow) {
|
|
108
|
+
run("git", ["-C", dest, "checkout", "-q", "--force", "FETCH_HEAD"]);
|
|
109
|
+
} else {
|
|
110
|
+
// Servers that refuse a fetch by SHA, or a ref that is neither branch nor tag.
|
|
111
|
+
run("git", ["-C", dest, "fetch", "-q", "--tags", "origin"]);
|
|
112
|
+
run("git", ["-C", dest, "checkout", "-q", "--force", want]);
|
|
113
|
+
}
|
|
114
|
+
const sha = headCommit(dest);
|
|
115
|
+
if (descriptor.sha && sha !== descriptor.sha) {
|
|
116
|
+
throw new Error(`${descriptor.url}: expected commit ${descriptor.sha}, got ${sha}`);
|
|
117
|
+
}
|
|
118
|
+
return { root: dest, resolved: { type: "git", url: descriptor.url, sha } };
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
|
|
122
|
+
|
|
123
|
+
function npmCacheDir(name, version) {
|
|
124
|
+
return path.join(cacheRoot(), "npm", safeSegment(`${name}@${version}`));
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* `npm pack` never runs the package's scripts; the tarball is unpacked as is.
|
|
129
|
+
* An exact version already unpacked is reused without asking the registry.
|
|
130
|
+
*/
|
|
131
|
+
async function fetchNpm(descriptor) {
|
|
132
|
+
if (descriptor.version && EXACT_VERSION.test(descriptor.version)) {
|
|
133
|
+
const cached = npmCacheDir(descriptor.package, descriptor.version);
|
|
134
|
+
const record = path.join(cached, "resolved.json");
|
|
135
|
+
if (fs.existsSync(record)) {
|
|
136
|
+
const root = path.join(cached, "package");
|
|
137
|
+
return { root: fs.existsSync(root) ? root : cached, resolved: JSON.parse(fs.readFileSync(record, "utf8")) };
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
const spec = descriptor.version ? `${descriptor.package}@${descriptor.version}` : descriptor.package;
|
|
141
|
+
const work = fs.mkdtempSync(path.join(os.tmpdir(), "deck-npm-"));
|
|
142
|
+
try {
|
|
143
|
+
const args = ["pack", spec, "--json", "--ignore-scripts", "--pack-destination", work];
|
|
144
|
+
if (descriptor.registry) args.push("--registry", descriptor.registry);
|
|
145
|
+
const out = JSON.parse(run("npm", args, { cwd: work }));
|
|
146
|
+
const info = Array.isArray(out) ? out[0] : out;
|
|
147
|
+
const dest = npmCacheDir(info.name, info.version);
|
|
148
|
+
fs.rmSync(dest, { recursive: true, force: true });
|
|
149
|
+
fs.mkdirSync(dest, { recursive: true });
|
|
150
|
+
run("tar", ["-xzf", path.join(work, info.filename), "-C", dest]);
|
|
151
|
+
const root = path.join(dest, "package");
|
|
152
|
+
const resolved = {
|
|
153
|
+
type: "npm",
|
|
154
|
+
package: info.name,
|
|
155
|
+
version: info.version,
|
|
156
|
+
...(info.integrity ? { integrity: info.integrity } : {}),
|
|
157
|
+
};
|
|
158
|
+
fs.writeFileSync(path.join(dest, "resolved.json"), `${JSON.stringify(resolved)}\n`);
|
|
159
|
+
return { root: fs.existsSync(root) ? root : dest, resolved };
|
|
160
|
+
} finally {
|
|
161
|
+
fs.rmSync(work, { recursive: true, force: true });
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
async function fetchArchive(descriptor) {
|
|
166
|
+
// A pinned digest already unpacked is reused without downloading.
|
|
167
|
+
if (descriptor.sha256) {
|
|
168
|
+
const pinned = path.join(cacheRoot(), "archive", descriptor.sha256.toLowerCase());
|
|
169
|
+
if (fs.existsSync(pinned)) {
|
|
170
|
+
return {
|
|
171
|
+
root: archiveRoot(pinned),
|
|
172
|
+
resolved: { type: "archive", url: descriptor.url, sha256: descriptor.sha256.toLowerCase() },
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
const response = await fetch(descriptor.url, { redirect: "follow" });
|
|
177
|
+
if (!response.ok) {
|
|
178
|
+
throw new Error(`${descriptor.url}: HTTP ${response.status}`);
|
|
179
|
+
}
|
|
180
|
+
const bytes = Buffer.from(await response.arrayBuffer());
|
|
181
|
+
const sha256 = createHash("sha256").update(bytes).digest("hex");
|
|
182
|
+
if (descriptor.sha256 && descriptor.sha256.toLowerCase() !== sha256) {
|
|
183
|
+
throw new Error(`${descriptor.url}: sha256 is ${sha256}, expected ${descriptor.sha256}`);
|
|
184
|
+
}
|
|
185
|
+
const dest = path.join(cacheRoot(), "archive", sha256);
|
|
186
|
+
if (!fs.existsSync(dest)) {
|
|
187
|
+
const work = fs.mkdtempSync(path.join(os.tmpdir(), "deck-archive-"));
|
|
188
|
+
try {
|
|
189
|
+
const isZip = bytes[0] === 0x50 && bytes[1] === 0x4b;
|
|
190
|
+
const file = path.join(work, isZip ? "a.zip" : "a.tgz");
|
|
191
|
+
fs.writeFileSync(file, bytes);
|
|
192
|
+
const out = path.join(work, "out");
|
|
193
|
+
fs.mkdirSync(out);
|
|
194
|
+
if (isZip) run("unzip", ["-q", file, "-d", out]);
|
|
195
|
+
else run("tar", ["-xzf", file, "-C", out]);
|
|
196
|
+
fs.mkdirSync(path.dirname(dest), { recursive: true });
|
|
197
|
+
fs.renameSync(out, dest);
|
|
198
|
+
} finally {
|
|
199
|
+
fs.rmSync(work, { recursive: true, force: true });
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
return { root: archiveRoot(dest), resolved: { type: "archive", url: descriptor.url, sha256 } };
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/** The plugin may sit at the top of the archive or one directory down. */
|
|
206
|
+
/** Absolute directory for a `path:` source. A symlink that leaves the project is refused. */
|
|
207
|
+
function resolveProjectPath(base, relative) {
|
|
208
|
+
if (!base) throw new Error(`path:${relative} needs the project root`);
|
|
209
|
+
let root;
|
|
210
|
+
try {
|
|
211
|
+
root = fs.realpathSync(base);
|
|
212
|
+
} catch {
|
|
213
|
+
throw new Error(`path:${relative} needs the project root`);
|
|
214
|
+
}
|
|
215
|
+
const abs = path.resolve(root, relative);
|
|
216
|
+
if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
|
|
217
|
+
throw new Error(`path:${relative} is not a directory in the project`);
|
|
218
|
+
}
|
|
219
|
+
const real = fs.realpathSync(abs);
|
|
220
|
+
const rel = path.relative(root, real);
|
|
221
|
+
if (rel.startsWith("..") || path.isAbsolute(rel)) {
|
|
222
|
+
throw new Error(`path:${relative} points outside the project`);
|
|
223
|
+
}
|
|
224
|
+
return real;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
function archiveRoot(dir) {
|
|
228
|
+
const entries = fs.readdirSync(dir).filter((name) => name !== "__MACOSX" && !name.startsWith("."));
|
|
229
|
+
if (entries.length === 1 && fs.statSync(path.join(dir, entries[0])).isDirectory()) {
|
|
230
|
+
return path.join(dir, entries[0]);
|
|
231
|
+
}
|
|
232
|
+
return dir;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** Pin a descriptor to what a previous fetch resolved, for a reproducible install. */
|
|
236
|
+
export function pinDescriptor(descriptor, resolved) {
|
|
237
|
+
if (!resolved || resolved.type !== descriptor.type) return descriptor;
|
|
238
|
+
switch (descriptor.type) {
|
|
239
|
+
case "git":
|
|
240
|
+
return { ...descriptor, sha: resolved.sha };
|
|
241
|
+
case "npm":
|
|
242
|
+
return { ...descriptor, package: resolved.package, version: resolved.version };
|
|
243
|
+
case "archive":
|
|
244
|
+
return { ...descriptor, sha256: resolved.sha256 };
|
|
245
|
+
case "path":
|
|
246
|
+
return { ...descriptor, path: resolved.path || descriptor.path };
|
|
247
|
+
default:
|
|
248
|
+
return descriptor;
|
|
249
|
+
}
|
|
250
|
+
}
|
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { fetchSource, pinDescriptor } from "./fetch.mjs";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Find the plugin a request names inside a fetched tree, and list its
|
|
7
|
+
* components the way Claude Code and Cursor would load them.
|
|
8
|
+
*
|
|
9
|
+
* @typedef {{ name: string, dir: string }} SkillRef
|
|
10
|
+
* @typedef {{ rel: string, file: string }} FileRef
|
|
11
|
+
* @typedef {{
|
|
12
|
+
* skills: SkillRef[], agents: FileRef[], commands: FileRef[], rules: FileRef[],
|
|
13
|
+
* hooks: { file?: string, inline?: object } | null,
|
|
14
|
+
* mcpServers: Record<string, object> | null,
|
|
15
|
+
* }} Components
|
|
16
|
+
* @typedef {{ name?: string, version?: string, description?: string, author?: object }} Meta
|
|
17
|
+
* @typedef {{ dir: string, meta: Meta, components: Components, nested: import("./fetch.mjs").Resolved | null }} Located
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
const MARKETPLACES = [".claude-plugin/marketplace.json", ".cursor-plugin/marketplace.json"];
|
|
21
|
+
const MANIFESTS = [".claude-plugin/plugin.json", ".cursor-plugin/plugin.json"];
|
|
22
|
+
const PATH_FIELDS = ["skills", "agents", "commands", "rules"];
|
|
23
|
+
const EXT = {
|
|
24
|
+
agents: [".md", ".mdc", ".markdown"],
|
|
25
|
+
commands: [".md", ".mdc", ".markdown", ".txt"],
|
|
26
|
+
rules: [".md", ".mdc", ".markdown"],
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* @param {string} root fetched source root
|
|
31
|
+
* @param {import("./spec.mjs").Request} request
|
|
32
|
+
* @param {{ nested?: import("./fetch.mjs").Resolved | null, fetch?: typeof fetchSource }} [options]
|
|
33
|
+
* @returns {Promise<Located>}
|
|
34
|
+
*/
|
|
35
|
+
export async function locatePlugin(root, request, options = {}) {
|
|
36
|
+
const fetch = options.fetch ?? fetchSource;
|
|
37
|
+
const base = request.path ? insideOrThrow(root, request.path, "path") : root;
|
|
38
|
+
if (!fs.existsSync(base)) {
|
|
39
|
+
throw new Error(`${request.id}: path "${request.path}" does not exist in the source`);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
const market = readMarketplace(base);
|
|
43
|
+
let entry = null;
|
|
44
|
+
if (market && market.plugins.length > 0) {
|
|
45
|
+
if (request.plugin) {
|
|
46
|
+
entry = market.plugins.find((p) => p.name === request.plugin) ?? null;
|
|
47
|
+
if (!entry && !fs.existsSync(path.join(base, "plugins", request.plugin))) {
|
|
48
|
+
throw new Error(
|
|
49
|
+
`${request.id}: no plugin "${request.plugin}" in ${market.file}. Available: ${market.plugins.map((p) => p.name).join(", ")}`,
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
} else if (market.plugins.length === 1) {
|
|
53
|
+
entry = market.plugins[0];
|
|
54
|
+
} else if (!(request.skills && hasSkills(base))) {
|
|
55
|
+
throw new Error(
|
|
56
|
+
`${request.id}: ${market.file} lists several plugins; pick one with @<plugin> or --plugin. Available: ${market.plugins.map((p) => p.name).join(", ")}`,
|
|
57
|
+
);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
let dir = base;
|
|
62
|
+
let nested = null;
|
|
63
|
+
if (entry) {
|
|
64
|
+
const target = await resolveEntrySource(base, market, entry, options.nested, fetch);
|
|
65
|
+
dir = target.dir;
|
|
66
|
+
nested = target.nested;
|
|
67
|
+
} else if (request.plugin && fs.existsSync(path.join(base, "plugins", request.plugin))) {
|
|
68
|
+
dir = path.join(base, "plugins", request.plugin);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const manifests = readManifests(dir);
|
|
72
|
+
const declared = declaredComponents(manifests, entry, request.id);
|
|
73
|
+
const components = collectComponents(dir, declared);
|
|
74
|
+
|
|
75
|
+
if (request.skills) {
|
|
76
|
+
const byName = new Map(components.skills.map((s) => [s.name, s]));
|
|
77
|
+
const missing = request.skills.filter((name) => !byName.has(name));
|
|
78
|
+
if (missing.length > 0) {
|
|
79
|
+
throw new Error(
|
|
80
|
+
`${request.id}: skill(s) ${missing.join(", ")} not found. Available: ${[...byName.keys()].join(", ") || "none"}`,
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
components.skills = request.skills.map((name) => byName.get(name));
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
if (isEmpty(components)) {
|
|
87
|
+
throw new Error(`${request.id}: nothing to install in ${dir} (no skills, agents, commands, rules, hooks, or MCP servers)`);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const meta = {
|
|
91
|
+
...pick(entry ?? {}, ["version", "description", "author"]),
|
|
92
|
+
...pick(manifests.claude ?? manifests.cursor ?? {}, ["name", "version", "description", "author"]),
|
|
93
|
+
};
|
|
94
|
+
return { dir, meta, components, nested };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function readJson(file) {
|
|
98
|
+
try {
|
|
99
|
+
return JSON.parse(fs.readFileSync(file, "utf8"));
|
|
100
|
+
} catch (err) {
|
|
101
|
+
throw new Error(`Invalid JSON in ${file}: ${err.message}`);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function readMarketplace(root) {
|
|
106
|
+
for (const rel of MARKETPLACES) {
|
|
107
|
+
const file = path.join(root, rel);
|
|
108
|
+
if (!fs.existsSync(file)) continue;
|
|
109
|
+
const doc = readJson(file);
|
|
110
|
+
return {
|
|
111
|
+
file: rel,
|
|
112
|
+
plugins: Array.isArray(doc.plugins) ? doc.plugins.filter((p) => p && p.name) : [],
|
|
113
|
+
pluginRoot: doc.metadata?.pluginRoot ?? doc.pluginRoot ?? null,
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
return null;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
function readManifests(dir) {
|
|
120
|
+
const [claude, cursor] = MANIFESTS.map((rel) => {
|
|
121
|
+
const file = path.join(dir, rel);
|
|
122
|
+
return fs.existsSync(file) ? readJson(file) : null;
|
|
123
|
+
});
|
|
124
|
+
return { claude, cursor };
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function insideOrThrow(root, rel, what) {
|
|
128
|
+
const abs = path.resolve(root, rel);
|
|
129
|
+
const back = path.relative(root, abs);
|
|
130
|
+
if (back.startsWith("..") || path.isAbsolute(back)) {
|
|
131
|
+
throw new Error(`${what} "${rel}" leaves the source directory`);
|
|
132
|
+
}
|
|
133
|
+
return abs;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** An entry source: a path inside the marketplace, or an object naming another place. */
|
|
137
|
+
async function resolveEntrySource(base, market, entry, pinned, fetch) {
|
|
138
|
+
const source = entry.source ?? "./";
|
|
139
|
+
if (typeof source === "string") {
|
|
140
|
+
const rel =
|
|
141
|
+
source.startsWith("./") || source === "." || source.startsWith("../")
|
|
142
|
+
? source
|
|
143
|
+
: path.posix.join(market.pluginRoot ?? ".", source);
|
|
144
|
+
const dir = insideOrThrow(base, rel, `plugin "${entry.name}" source`);
|
|
145
|
+
if (!fs.existsSync(dir)) {
|
|
146
|
+
throw new Error(`Plugin "${entry.name}" source "${source}" is missing in the marketplace`);
|
|
147
|
+
}
|
|
148
|
+
return { dir, nested: null };
|
|
149
|
+
}
|
|
150
|
+
if (!source || typeof source !== "object") {
|
|
151
|
+
throw new Error(`Plugin "${entry.name}" has an unreadable source`);
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
const { descriptor, subdir } = entryDescriptor(entry.name, source);
|
|
155
|
+
const fetched = await fetch(pinDescriptor(descriptor, pinned));
|
|
156
|
+
const dir = subdir ? insideOrThrow(fetched.root, subdir, `plugin "${entry.name}" path`) : fetched.root;
|
|
157
|
+
if (!fs.existsSync(dir)) {
|
|
158
|
+
throw new Error(`Plugin "${entry.name}": path "${subdir}" is missing in ${descriptor.url ?? descriptor.package}`);
|
|
159
|
+
}
|
|
160
|
+
return { dir, nested: fetched.resolved };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function githubUrl(value) {
|
|
164
|
+
return /^[\w.-]+\/[\w.-]+$/.test(value) ? `https://github.com/${value}.git` : value;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** Map a Claude Code marketplace source object to a fetch descriptor. */
|
|
168
|
+
export function entryDescriptor(name, source) {
|
|
169
|
+
const pinned = {
|
|
170
|
+
...(source.ref ? { ref: source.ref } : {}),
|
|
171
|
+
...(source.sha ? { sha: source.sha } : {}),
|
|
172
|
+
};
|
|
173
|
+
switch (source.source) {
|
|
174
|
+
case "github":
|
|
175
|
+
if (!source.repo) throw new Error(`Plugin "${name}": github source needs repo`);
|
|
176
|
+
return {
|
|
177
|
+
descriptor: { type: "git", url: githubUrl(source.repo), repo: source.repo, ...pinned },
|
|
178
|
+
subdir: source.path ?? null,
|
|
179
|
+
};
|
|
180
|
+
case "url":
|
|
181
|
+
case "git":
|
|
182
|
+
if (!source.url) throw new Error(`Plugin "${name}": ${source.source} source needs url`);
|
|
183
|
+
return { descriptor: { type: "git", url: source.url, ...pinned }, subdir: source.path ?? null };
|
|
184
|
+
case "git-subdir":
|
|
185
|
+
if (!source.url || !source.path) {
|
|
186
|
+
throw new Error(`Plugin "${name}": git-subdir source needs url and path`);
|
|
187
|
+
}
|
|
188
|
+
return {
|
|
189
|
+
descriptor: {
|
|
190
|
+
type: "git",
|
|
191
|
+
url: githubUrl(source.url),
|
|
192
|
+
...(/^[\w.-]+\/[\w.-]+$/.test(source.url) ? { repo: source.url } : {}),
|
|
193
|
+
...pinned,
|
|
194
|
+
},
|
|
195
|
+
subdir: source.path,
|
|
196
|
+
};
|
|
197
|
+
case "npm":
|
|
198
|
+
if (!source.package) throw new Error(`Plugin "${name}": npm source needs package`);
|
|
199
|
+
return {
|
|
200
|
+
descriptor: {
|
|
201
|
+
type: "npm",
|
|
202
|
+
package: source.package,
|
|
203
|
+
...(source.version ? { version: source.version } : {}),
|
|
204
|
+
...(source.registry ? { registry: source.registry } : {}),
|
|
205
|
+
},
|
|
206
|
+
subdir: null,
|
|
207
|
+
};
|
|
208
|
+
case "archive":
|
|
209
|
+
if (!source.url) throw new Error(`Plugin "${name}": archive source needs url`);
|
|
210
|
+
return {
|
|
211
|
+
descriptor: { type: "archive", url: source.url, ...(source.sha256 ? { sha256: source.sha256 } : {}) },
|
|
212
|
+
subdir: null,
|
|
213
|
+
};
|
|
214
|
+
default:
|
|
215
|
+
throw new Error(
|
|
216
|
+
`Plugin "${name}": source type "${source.source}" is not supported by agent-deck (supported: path, github, url, git-subdir, npm, archive)`,
|
|
217
|
+
);
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* Component declarations from plugin.json (Claude first, Cursor for what Claude
|
|
223
|
+
* does not say) and from the marketplace entry, with Claude Code's strict rules:
|
|
224
|
+
* no plugin.json → the entry is the manifest
|
|
225
|
+
* strict (default) → entry component paths are added to plugin.json's
|
|
226
|
+
* strict: false → an entry that declares components is a conflict
|
|
227
|
+
*/
|
|
228
|
+
function declaredComponents(manifests, entry, id) {
|
|
229
|
+
const declared = {};
|
|
230
|
+
for (const manifest of [manifests.claude, manifests.cursor]) {
|
|
231
|
+
if (!manifest) continue;
|
|
232
|
+
for (const field of [...PATH_FIELDS, "hooks", "mcpServers"]) {
|
|
233
|
+
if (manifest[field] != null && declared[field] == null) declared[field] = manifest[field];
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
if (!entry) return declared;
|
|
237
|
+
|
|
238
|
+
const hasManifest = Boolean(manifests.claude || manifests.cursor);
|
|
239
|
+
const entryFields = [...PATH_FIELDS, "hooks", "mcpServers"].filter((f) => entry[f] != null);
|
|
240
|
+
if (entryFields.length === 0) return declared;
|
|
241
|
+
if (hasManifest && entry.strict === false) {
|
|
242
|
+
throw new Error(
|
|
243
|
+
`${id}: plugin "${entry.name}" has conflicting manifests: both plugin.json and its strict:false marketplace entry declare components`,
|
|
244
|
+
);
|
|
245
|
+
}
|
|
246
|
+
for (const field of entryFields) {
|
|
247
|
+
if (!hasManifest || declared[field] == null) {
|
|
248
|
+
declared[field] = entry[field];
|
|
249
|
+
} else if (PATH_FIELDS.includes(field)) {
|
|
250
|
+
declared[field] = [...asList(declared[field]), ...asList(entry[field])];
|
|
251
|
+
} else if (field === "hooks") {
|
|
252
|
+
declared.hooks = entry.hooks;
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
return declared;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
function asList(value) {
|
|
259
|
+
return Array.isArray(value) ? value : [value];
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
function collectComponents(dir, declared) {
|
|
263
|
+
return {
|
|
264
|
+
skills: collectSkills(dir, declared.skills),
|
|
265
|
+
agents: collectFiles(dir, "agents", declared.agents),
|
|
266
|
+
commands: collectFiles(dir, "commands", declared.commands),
|
|
267
|
+
rules: collectFiles(dir, "rules", declared.rules),
|
|
268
|
+
hooks: collectHooks(dir, declared.hooks),
|
|
269
|
+
mcpServers: collectMcp(dir, declared.mcpServers),
|
|
270
|
+
};
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
function hasSkills(dir) {
|
|
274
|
+
return collectSkills(dir, undefined).length > 0;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** A declared path is a skill directory, or a directory of skill directories. */
|
|
278
|
+
function collectSkills(dir, declared) {
|
|
279
|
+
const found = new Map();
|
|
280
|
+
const add = (skillDir) => {
|
|
281
|
+
const name = skillName(skillDir);
|
|
282
|
+
if (!found.has(name)) found.set(name, { name, dir: skillDir });
|
|
283
|
+
};
|
|
284
|
+
const scan = (abs) => {
|
|
285
|
+
if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return;
|
|
286
|
+
if (fs.existsSync(path.join(abs, "SKILL.md"))) {
|
|
287
|
+
add(abs);
|
|
288
|
+
return;
|
|
289
|
+
}
|
|
290
|
+
for (const child of fs.readdirSync(abs, { withFileTypes: true })) {
|
|
291
|
+
if (child.isDirectory() && fs.existsSync(path.join(abs, child.name, "SKILL.md"))) {
|
|
292
|
+
add(path.join(abs, child.name));
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
};
|
|
296
|
+
|
|
297
|
+
if (declared != null) {
|
|
298
|
+
for (const rel of asList(declared)) {
|
|
299
|
+
if (typeof rel === "string") scan(insideOrThrow(dir, rel, "skills path"));
|
|
300
|
+
}
|
|
301
|
+
} else if (fs.existsSync(path.join(dir, "skills"))) {
|
|
302
|
+
scan(path.join(dir, "skills"));
|
|
303
|
+
} else if (fs.existsSync(path.join(dir, "SKILL.md"))) {
|
|
304
|
+
add(dir);
|
|
305
|
+
}
|
|
306
|
+
return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
/** `name:` from the SKILL.md front matter, else the directory name. */
|
|
310
|
+
export function skillName(skillDir) {
|
|
311
|
+
const text = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8");
|
|
312
|
+
const front = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
|
|
313
|
+
const name = front?.[1].match(/^name:\s*["']?([^"'\r\n]+?)["']?\s*$/m)?.[1];
|
|
314
|
+
return (name || path.basename(skillDir)).trim();
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
function walk(dir) {
|
|
318
|
+
const out = [];
|
|
319
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
320
|
+
const abs = path.join(dir, entry.name);
|
|
321
|
+
if (entry.isDirectory()) out.push(...walk(abs));
|
|
322
|
+
else out.push(abs);
|
|
323
|
+
}
|
|
324
|
+
return out;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
function collectFiles(dir, kind, declared) {
|
|
328
|
+
const roots = declared != null
|
|
329
|
+
? asList(declared).filter((rel) => typeof rel === "string").map((rel) => insideOrThrow(dir, rel, `${kind} path`))
|
|
330
|
+
: [path.join(dir, kind)];
|
|
331
|
+
const files = [];
|
|
332
|
+
for (const abs of roots) {
|
|
333
|
+
if (!fs.existsSync(abs)) continue;
|
|
334
|
+
if (fs.statSync(abs).isFile()) {
|
|
335
|
+
files.push({ rel: path.basename(abs), file: abs });
|
|
336
|
+
continue;
|
|
337
|
+
}
|
|
338
|
+
for (const file of walk(abs)) {
|
|
339
|
+
if (!EXT[kind].some((ext) => file.endsWith(ext))) continue;
|
|
340
|
+
if (path.basename(file).toLowerCase() === "readme.md") continue;
|
|
341
|
+
files.push({ rel: path.relative(abs, file), file });
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
return files.sort((a, b) => a.rel.localeCompare(b.rel));
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
function collectHooks(dir, declared) {
|
|
348
|
+
if (declared && typeof declared === "object" && !Array.isArray(declared)) {
|
|
349
|
+
return { inline: declared };
|
|
350
|
+
}
|
|
351
|
+
const rel = typeof declared === "string" ? declared : "hooks/hooks.json";
|
|
352
|
+
const file = insideOrThrow(dir, rel, "hooks path");
|
|
353
|
+
return fs.existsSync(file) ? { file } : null;
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
function mcpFromFile(file) {
|
|
357
|
+
const raw = readJson(file);
|
|
358
|
+
if (raw?.mcpServers && typeof raw.mcpServers === "object") return raw.mcpServers;
|
|
359
|
+
return raw && typeof raw === "object" ? raw : null;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
function collectMcp(dir, declared) {
|
|
363
|
+
if (declared != null) {
|
|
364
|
+
const merged = {};
|
|
365
|
+
for (const item of asList(declared)) {
|
|
366
|
+
if (typeof item === "string") Object.assign(merged, mcpFromFile(insideOrThrow(dir, item, "mcpServers path")) ?? {});
|
|
367
|
+
else if (item && typeof item === "object") Object.assign(merged, item);
|
|
368
|
+
}
|
|
369
|
+
return Object.keys(merged).length > 0 ? merged : null;
|
|
370
|
+
}
|
|
371
|
+
for (const rel of ["mcp.json", ".mcp.json"]) {
|
|
372
|
+
const file = path.join(dir, rel);
|
|
373
|
+
if (fs.existsSync(file)) {
|
|
374
|
+
const servers = mcpFromFile(file);
|
|
375
|
+
if (servers && Object.keys(servers).length > 0) return servers;
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
return null;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
function isEmpty(c) {
|
|
382
|
+
return (
|
|
383
|
+
c.skills.length === 0 &&
|
|
384
|
+
c.agents.length === 0 &&
|
|
385
|
+
c.commands.length === 0 &&
|
|
386
|
+
c.rules.length === 0 &&
|
|
387
|
+
!c.hooks &&
|
|
388
|
+
!c.mcpServers
|
|
389
|
+
);
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
function pick(obj, keys) {
|
|
393
|
+
const out = {};
|
|
394
|
+
for (const key of keys) if (obj[key] != null) out[key] = obj[key];
|
|
395
|
+
return out;
|
|
396
|
+
}
|