@xtframe/skills 0.0.0-stage → 0.19.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.
Files changed (36) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
  20. package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
  26. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
  27. package/src/agents.mjs +73 -0
  28. package/src/bin.mjs +4 -0
  29. package/src/cli.mjs +286 -0
  30. package/src/converter.mjs +73 -0
  31. package/src/fsutil.mjs +76 -0
  32. package/src/install.mjs +154 -0
  33. package/src/packs.mjs +150 -0
  34. package/src/plugins.mjs +109 -0
  35. package/src/proc.mjs +66 -0
  36. package/src/tar.mjs +103 -0
package/src/cli.mjs ADDED
@@ -0,0 +1,286 @@
1
+ #!/usr/bin/env node
2
+ // xtframe-skills: search for XTFrame skill packs and install them, with the converter, into every
3
+ // coding agent on this machine (docs/00-design.md §0.7).
4
+ import fs from 'node:fs';
5
+ import os from 'node:os';
6
+ import path from 'node:path';
7
+
8
+ import { isDetected, knownAgents, skillsDir } from './agents.mjs';
9
+ import { ensureConverter, probeTools, removeConverter, globalVersion } from './converter.mjs';
10
+ import { hashDir, replaceDir } from './fsutil.mjs';
11
+ import { entryState, installSkills, readLock, removeSkills, writeLock } from './install.mjs';
12
+ import { builtinPack, fetchPack, ownPackage, registryVersion, searchPacks } from './packs.mjs';
13
+ import { installPlugin } from './plugins.mjs';
14
+
15
+ const HELP = `xtframe-skills <command> [options]
16
+
17
+ Commands:
18
+ search [words] list skill packs (npm keyword xtframe-skill-pack) and their skills
19
+ install [skill...] install skills (default: all) into every detected agent, plus the converter
20
+ list show what this tool installed, and whether it was edited since
21
+ update bring every installed skill, plugin and the converter to the newest version
22
+ remove [skill...] remove what this tool installed (default: everything)
23
+ agents list known agents, which are detected and where they read skills
24
+ doctor check the converter on PATH, versions and the lock file
25
+
26
+ Options:
27
+ --agent <ids> comma list of agent ids, or 'all' (default: every detected agent)
28
+ --project use the project skill directories under the current directory
29
+ --plugin install as a plugin where the agent supports it (Claude Code, Copilot CLI)
30
+ --pack <spec> use a pack from npm (name[@version|tag]) instead of the one bundled here
31
+ --tag <tag> update: follow this npm dist-tag (latest | next)
32
+ --no-converter install/update: leave the converter alone
33
+ --force replace folders this tool did not install, or that were edited
34
+ --offline search/update: do not contact the npm registry
35
+ --dry-run print what would happen, change nothing
36
+ -v, --version print the version
37
+ `;
38
+
39
+ export function parseArgs(argv) {
40
+ const o = { _: [], converter: true };
41
+ const takes = new Set(['--agent', '--pack', '--tag', '--home']);
42
+ for (let i = 0; i < argv.length; ++i) {
43
+ const a = argv[i];
44
+ if (takes.has(a)) {
45
+ if (i + 1 >= argv.length) throw new Error(`${a} needs a value`);
46
+ o[a === '--agent' ? 'agents' : a.slice(2)] = argv[++i];
47
+ } else if (a === '--project') o.project = true;
48
+ else if (a === '--plugin') o.plugin = true;
49
+ else if (a === '--no-converter') o.converter = false;
50
+ else if (a === '--force') o.force = true;
51
+ else if (a === '--offline') o.offline = true;
52
+ else if (a === '--dry-run') o.dryRun = true;
53
+ else if (a === '-h' || a === '--help') o.help = true;
54
+ else if (a === '-v' || a === '--version') o.version = true;
55
+ else if (a.startsWith('-')) throw new Error(`unknown option ${a}`);
56
+ else o._.push(a);
57
+ }
58
+ return o;
59
+ }
60
+
61
+ function makeCtx(o) {
62
+ const home = o.home || process.env.XTFRAME_SKILLS_HOME || os.homedir();
63
+ const xtHome = path.join(home, '.xtframe');
64
+ if (!o.dryRun) fs.mkdirSync(xtHome, { recursive: true });
65
+ return { home, xtHome, cwd: process.cwd(), dryRun: !!o.dryRun };
66
+ }
67
+
68
+ function table(rows, cols) {
69
+ if (!rows.length) return;
70
+ const w = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
71
+ console.log(cols.map((c, i) => c.padEnd(w[i])).join(' '));
72
+ for (const r of rows) console.log(cols.map((c, i) => String(r[c] ?? '').padEnd(w[i])).join(' ').trimEnd());
73
+ }
74
+
75
+ function printSkipped(skipped) {
76
+ for (const s of skipped) console.log(` skipped ${s.agent}: ${s.reason}`);
77
+ }
78
+
79
+ function cmdSearch(ctx, o) {
80
+ const { packs, registryError } = searchPacks(ctx, o._.join(' '), { offline: o.offline });
81
+ if (registryError) console.log(`(npm registry not searched: ${registryError})`);
82
+ for (const p of packs) {
83
+ const extra = p.registryVersion && p.registryVersion !== p.version ? ` (registry has ${p.registryVersion})` : '';
84
+ console.log(`${p.name}@${p.version}${p.installedWithCli ? ' [bundled with this CLI]' : ''}${extra}`);
85
+ if (p.description) console.log(` ${p.description}`);
86
+ for (const s of p.skills) console.log(` - ${s.name}: ${s.description.length > 160 ? `${s.description.slice(0, 157)}...` : s.description}`);
87
+ }
88
+ if (!packs.length) console.log('no matching skill packs');
89
+ }
90
+
91
+ function resolvePack(ctx, o) {
92
+ return o.pack ? fetchPack(ctx, o.pack) : builtinPack();
93
+ }
94
+
95
+ function cmdInstall(ctx, o) {
96
+ const pack = resolvePack(ctx, o);
97
+ console.log(`pack ${pack.name}@${pack.version}${ctx.dryRun ? ' (dry run)' : ''}`);
98
+ const { rows, skipped } = installSkills(ctx, pack, o._, o);
99
+ table(rows, ['action', 'skill', 'agent', 'path']);
100
+ printSkipped(skipped);
101
+ if (o.converter) {
102
+ const lock = readLock(ctx);
103
+ const c = ensureConverter(ctx, pack, lock);
104
+ writeLock(ctx, lock);
105
+ console.log(`converter: ${c.action} ${c.detail}`);
106
+ }
107
+ if (rows.length && !ctx.dryRun) console.log('Start a new agent session to pick up the skills.');
108
+ }
109
+
110
+ function cmdList(ctx) {
111
+ const lock = readLock(ctx);
112
+ if (!lock.entries.length) console.log('nothing installed by xtframe-skills');
113
+ table(lock.entries.map((e) => ({
114
+ state: entryState(e),
115
+ skill: e.kind === 'plugin' ? `${e.plugin} (plugin: ${e.skills.join(', ')})` : e.skill,
116
+ version: e.version,
117
+ agent: e.kind === 'plugin' ? e.agent : e.agents.join(','),
118
+ path: e.kind === 'plugin' ? e.marketplaceDir : e.path,
119
+ })), ['state', 'skill', 'version', 'agent', 'path']);
120
+ if (lock.converter) console.log(`converter: ${lock.converter.name}@${lock.converter.version} (${lock.converter.installedBy === 'xtframe-skills' ? 'installed by xtframe-skills' : 'found installed'})`);
121
+ }
122
+
123
+ /** The newest pack for `name`: the bundled one when it is current, else fetched from npm. */
124
+ function newestPack(ctx, name, o) {
125
+ const own = ownPackage();
126
+ if (name === own.name && o.offline) return builtinPack();
127
+ const v = o.offline ? null : registryVersion(ctx, name, o.tag || 'latest');
128
+ if (!v) {
129
+ if (name === own.name) {
130
+ console.log(`(registry not reachable or no '${o.tag || 'latest'}' tag; using the bundled ${own.version})`);
131
+ return builtinPack();
132
+ }
133
+ return null;
134
+ }
135
+ if (name === own.name && v === own.version) return builtinPack();
136
+ return fetchPack(ctx, `${name}@${v}`);
137
+ }
138
+
139
+ function cmdUpdate(ctx, o) {
140
+ const lock = readLock(ctx);
141
+ const packs = new Map();
142
+ const rows = [];
143
+ for (const e of lock.entries) {
144
+ if (!packs.has(e.pack)) packs.set(e.pack, newestPack(ctx, e.pack, o));
145
+ const pack = packs.get(e.pack);
146
+ const name = e.kind === 'plugin' ? `${e.plugin} (plugin)` : e.skill;
147
+ if (!pack) {
148
+ rows.push({ action: 'skipped (pack not on registry)', skill: name, version: e.version });
149
+ continue;
150
+ }
151
+ if (e.version === pack.version && entryState(e) === 'ok' && !o.force) {
152
+ rows.push({ action: 'up to date', skill: name, version: e.version });
153
+ continue;
154
+ }
155
+ if (e.kind === 'plugin') {
156
+ const agent = knownAgents(ctx).find((a) => a.id === e.agent);
157
+ Object.assign(e, installPlugin(ctx, agent, pack, e.scope));
158
+ rows.push({ action: ctx.dryRun ? 'would update' : 'updated', skill: name, version: pack.version });
159
+ continue;
160
+ }
161
+ const state = entryState(e);
162
+ if (state === 'modified' && !o.force) {
163
+ rows.push({ action: 'kept (edited; --force replaces it)', skill: name, version: e.version });
164
+ continue;
165
+ }
166
+ const src = path.join(pack.skillsDir, e.skill);
167
+ if (!fs.existsSync(src)) {
168
+ rows.push({ action: `skipped (not in ${pack.name}@${pack.version})`, skill: name, version: e.version });
169
+ continue;
170
+ }
171
+ if (!ctx.dryRun) replaceDir(src, e.path);
172
+ rows.push({ action: ctx.dryRun ? 'would update' : `updated ${e.version} ->`, skill: name, version: pack.version, path: e.path });
173
+ e.version = pack.version;
174
+ e.sha256 = hashDir(src);
175
+ e.installedAt = new Date().toISOString();
176
+ }
177
+ table(rows, ['action', 'skill', 'version', 'path']);
178
+ if (o.converter && lock.converter) {
179
+ const own = packs.get(ownPackage().name) || newestPack(ctx, ownPackage().name, o);
180
+ const c = ensureConverter(ctx, own, lock);
181
+ console.log(`converter: ${c.action} ${c.detail}`);
182
+ }
183
+ writeLock(ctx, lock);
184
+ if (!lock.entries.length) console.log('nothing installed by xtframe-skills; run `xtframe-skills install`');
185
+ }
186
+
187
+ function cmdRemove(ctx, o) {
188
+ const rows = removeSkills(ctx, o._, o);
189
+ table(rows, ['action', 'skill', 'agent', 'path']);
190
+ if (!o._.length && o.converter) {
191
+ const lock = readLock(ctx);
192
+ const c = removeConverter(ctx, lock);
193
+ writeLock(ctx, lock);
194
+ if (c) console.log(`converter: ${ctx.dryRun ? 'would remove' : 'removed'} ${c.name}@${c.version}`);
195
+ }
196
+ if (!rows.length) console.log('nothing matched');
197
+ }
198
+
199
+ function cmdAgents(ctx) {
200
+ table(knownAgents(ctx).map((a) => ({
201
+ id: a.id,
202
+ name: a.name,
203
+ detected: isDetected(a, ctx) ? 'yes' : '',
204
+ plugin: a.plugin || '',
205
+ global: skillsDir(a, 'global', ctx) || '',
206
+ project: a.project || '',
207
+ })), ['id', 'name', 'detected', 'plugin', 'global', 'project']);
208
+ }
209
+
210
+ function cmdDoctor(ctx) {
211
+ let problems = 0;
212
+ const own = ownPackage();
213
+ console.log(`xtframe-skills ${own.version}, node ${process.version}, ${process.platform}-${process.arch}`);
214
+ const lock = readLock(ctx);
215
+ for (const t of probeTools()) {
216
+ console.log(`${t.tool}: ${t.path || 'NOT on PATH'}${t.version ? ` (${t.version})` : ''}`);
217
+ if (!t.path) problems++;
218
+ }
219
+ if (lock.converter) {
220
+ const v = globalVersion(lock.converter.name);
221
+ const skillVersions = new Set(lock.entries.map((e) => e.version));
222
+ console.log(`converter package: ${lock.converter.name}@${v || 'missing'}`);
223
+ if (!v) problems++;
224
+ else if (skillVersions.size && !skillVersions.has(v)) {
225
+ console.log(` converter ${v} differs from installed skills (${[...skillVersions].join(', ')}): run 'xtframe-skills update'`);
226
+ problems++;
227
+ }
228
+ }
229
+ for (const e of lock.entries) {
230
+ const s = entryState(e);
231
+ if (s === 'missing' || s === 'modified') {
232
+ console.log(`${s}: ${e.path} (${e.skill})`);
233
+ problems++;
234
+ }
235
+ }
236
+ // Same skill name visible twice to one agent (e.g. a plugin plus a loose folder).
237
+ const plugins = lock.entries.filter((e) => e.kind === 'plugin' && e.agent === 'claude-code');
238
+ for (const p of plugins) {
239
+ for (const s of p.skills) {
240
+ const loose = path.join(ctx.home, '.claude', 'skills', s);
241
+ if (fs.existsSync(loose)) {
242
+ console.log(`duplicate: Claude Code sees ${s} from the ${p.plugin} plugin and from ${loose}`);
243
+ problems++;
244
+ }
245
+ }
246
+ }
247
+ console.log(problems ? `${problems} problem(s)` : 'no problems found');
248
+ return problems ? 1 : 0;
249
+ }
250
+
251
+ export function main(argv) {
252
+ let o;
253
+ try {
254
+ o = parseArgs(argv);
255
+ } catch (err) {
256
+ console.error(`xtframe-skills: ${err.message}`);
257
+ return 2;
258
+ }
259
+ if (o.version) {
260
+ console.log(ownPackage().version);
261
+ return 0;
262
+ }
263
+ const cmd = o._.shift();
264
+ if (o.help || !cmd) {
265
+ console.log(HELP);
266
+ return o.help ? 0 : 2;
267
+ }
268
+ const ctx = makeCtx(o);
269
+ try {
270
+ switch (cmd) {
271
+ case 'search': cmdSearch(ctx, o); return 0;
272
+ case 'install': case 'add': cmdInstall(ctx, o); return 0;
273
+ case 'list': case 'ls': cmdList(ctx); return 0;
274
+ case 'update': case 'upgrade': cmdUpdate(ctx, o); return 0;
275
+ case 'remove': case 'rm': case 'uninstall': cmdRemove(ctx, o); return 0;
276
+ case 'agents': cmdAgents(ctx); return 0;
277
+ case 'doctor': return cmdDoctor(ctx);
278
+ default:
279
+ console.error(`xtframe-skills: unknown command '${cmd}'\n\n${HELP}`);
280
+ return 2;
281
+ }
282
+ } catch (err) {
283
+ console.error(`xtframe-skills: ${err.message}`);
284
+ return 1;
285
+ }
286
+ }
@@ -0,0 +1,73 @@
1
+ // The converter (xtframe-import, xtframe-compile, xtframe-view) installed globally with npm, at
2
+ // exactly the pack's version, so every agent's shell finds the tools the skills call.
3
+ import { checkSpec, npm, runTool, which } from './proc.mjs';
4
+
5
+ export const SUPPORTED_PLATFORMS = ['win32-x64'];
6
+ // npm package name of the kit repository's root package.json.
7
+ export const KIT_PACKAGE = 'xtframe-kit';
8
+
9
+ export function platformKey() {
10
+ return `${process.platform}-${process.arch}`;
11
+ }
12
+
13
+ /** Globally installed version of `name`, or null. */
14
+ export function globalVersion(name) {
15
+ const r = npm(['ls', '-g', checkSpec(name), '--json', '--depth=0']);
16
+ try {
17
+ return JSON.parse(r.stdout || '{}').dependencies?.[name]?.version || null;
18
+ } catch {
19
+ return null;
20
+ }
21
+ }
22
+
23
+ /**
24
+ * Make the global converter equal the pack's version. Returns { action, detail } for the report.
25
+ * Never throws for an unsupported platform: the skills fall back to building from a checkout.
26
+ */
27
+ export function ensureConverter(ctx, pack, lock) {
28
+ if (!pack.converter) return { action: 'none', detail: `pack ${pack.name} names no converter` };
29
+ if (!SUPPORTED_PLATFORMS.includes(platformKey())) {
30
+ return { action: 'skipped', detail: `no prebuilt converter for ${platformKey()}; the skills build it from an XTFrame checkout` };
31
+ }
32
+ // From the kit (docs/00-design.md §0.11) the converter is the kit itself: the spec already
33
+ // names the version (#vX.Y.Z) and npm lists the install under the kit's package name.
34
+ const fromGit = pack.converter.startsWith('github:');
35
+ const name = fromGit ? KIT_PACKAGE : pack.converter;
36
+ const spec = checkSpec(fromGit ? pack.converter : `${pack.converter}@${pack.version}`);
37
+ const have = globalVersion(name);
38
+ if (have === pack.version) {
39
+ lock.converter = lock.converter || { name, version: have, installedBy: 'other' };
40
+ return { action: 'ok', detail: `${name}@${have} already installed` };
41
+ }
42
+ if (ctx.dryRun) return { action: 'would install', detail: `npm install -g ${spec}${have ? ` (have ${have})` : ''}` };
43
+ const r = npm(['install', '-g', spec], { stdio: 'inherit' });
44
+ if (r.status !== 0) throw new Error(`npm install -g ${spec} failed (exit ${r.status})`);
45
+ lock.converter = { name, version: pack.version, installedBy: 'xtframe-skills' };
46
+ return { action: have ? `updated ${have} ->` : 'installed', detail: spec };
47
+ }
48
+
49
+ export function removeConverter(ctx, lock) {
50
+ const c = lock.converter;
51
+ if (!c || c.installedBy !== 'xtframe-skills') return null;
52
+ if (!ctx.dryRun) {
53
+ const r = npm(['uninstall', '-g', checkSpec(c.name)], { stdio: 'inherit' });
54
+ if (r.status !== 0) throw new Error(`npm uninstall -g ${c.name} failed`);
55
+ }
56
+ delete lock.converter;
57
+ return c;
58
+ }
59
+
60
+ /** What the agents' shells will find: path and a version line per tool. */
61
+ export function probeTools() {
62
+ return ['xtframe-import', 'xtframe-compile', 'xtframe-view'].map((tool) => {
63
+ const where = which(tool);
64
+ let version = null;
65
+ if (where) {
66
+ // Builds before T-479 answer `xtframe-import --version` with usage: no version then.
67
+ const r = runTool(tool, ['--version'], { timeout: 20000 });
68
+ const first = (r.stdout || '').split(/\r?\n/)[0].trim();
69
+ if (new RegExp(`^${tool} \\d+\\.\\d+\\.\\d+`).test(first)) version = first;
70
+ }
71
+ return { tool, path: where, version };
72
+ });
73
+ }
package/src/fsutil.mjs ADDED
@@ -0,0 +1,76 @@
1
+ // File helpers shared by the CLI and the repository tools.
2
+ import crypto from 'node:crypto';
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+
6
+ /** Every file under `dir`, as sorted forward-slash relative paths. */
7
+ export function listFiles(dir) {
8
+ const out = [];
9
+ const walk = (abs, rel) => {
10
+ for (const ent of fs.readdirSync(abs, { withFileTypes: true })) {
11
+ const a = path.join(abs, ent.name);
12
+ const r = rel ? `${rel}/${ent.name}` : ent.name;
13
+ if (ent.isDirectory()) walk(a, r);
14
+ else if (ent.isFile()) out.push(r);
15
+ }
16
+ };
17
+ if (fs.existsSync(dir)) walk(dir, '');
18
+ return out.sort();
19
+ }
20
+
21
+ export function sha256(data) {
22
+ return crypto.createHash('sha256').update(data).digest('hex');
23
+ }
24
+
25
+ /** Per-file hashes of a directory: { relPath: sha256 }. */
26
+ export function hashFiles(dir) {
27
+ const out = {};
28
+ for (const rel of listFiles(dir)) out[rel] = sha256(fs.readFileSync(path.join(dir, rel)));
29
+ return out;
30
+ }
31
+
32
+ /** One hash for a whole directory tree (paths and contents). Missing directory -> null. */
33
+ export function hashDir(dir) {
34
+ if (!fs.existsSync(dir)) return null;
35
+ const h = crypto.createHash('sha256');
36
+ for (const [rel, digest] of Object.entries(hashFiles(dir))) h.update(`${rel}\0${digest}\n`);
37
+ return h.digest('hex');
38
+ }
39
+
40
+ export function removeDir(dir) {
41
+ fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
42
+ }
43
+
44
+ /** Replace `dest` with a byte copy of `src`. */
45
+ export function replaceDir(src, dest) {
46
+ removeDir(dest);
47
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
48
+ fs.cpSync(src, dest, { recursive: true });
49
+ }
50
+
51
+ export function readJson(file, fallback = undefined) {
52
+ try {
53
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
54
+ } catch (err) {
55
+ if (fallback !== undefined && err.code === 'ENOENT') return fallback;
56
+ throw err;
57
+ }
58
+ }
59
+
60
+ export function writeJson(file, value) {
61
+ fs.mkdirSync(path.dirname(file), { recursive: true });
62
+ fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
63
+ }
64
+
65
+ /** Two directory trees differ: list of 'added x' / 'removed x' / 'changed x'. */
66
+ export function diffTrees(a, b) {
67
+ const ha = hashFiles(a);
68
+ const hb = hashFiles(b);
69
+ const out = [];
70
+ for (const k of Object.keys(ha)) {
71
+ if (!(k in hb)) out.push(`removed ${k}`);
72
+ else if (ha[k] !== hb[k]) out.push(`changed ${k}`);
73
+ }
74
+ for (const k of Object.keys(hb)) if (!(k in ha)) out.push(`added ${k}`);
75
+ return out;
76
+ }
@@ -0,0 +1,154 @@
1
+ // Installing skills into agent skill directories, with a lock file so that update and remove
2
+ // touch only what this CLI wrote (docs/00-design.md §0.7).
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+
6
+ import { selectAgents, skillsDir } from './agents.mjs';
7
+ import { hashDir, readJson, removeDir, replaceDir, writeJson } from './fsutil.mjs';
8
+ import { installPlugin, pluginRouteAvailable, pruneMarketplace, removePlugin } from './plugins.mjs';
9
+
10
+ export function lockPath(ctx) {
11
+ return path.join(ctx.xtHome, 'skills-lock.json');
12
+ }
13
+
14
+ export function readLock(ctx) {
15
+ const lock = readJson(lockPath(ctx), { version: 1, entries: [] });
16
+ if (!Array.isArray(lock.entries)) lock.entries = [];
17
+ return lock;
18
+ }
19
+
20
+ export function writeLock(ctx, lock) {
21
+ if (!ctx.dryRun) writeJson(lockPath(ctx), lock);
22
+ }
23
+
24
+ const samePath = (a, b) => path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
25
+
26
+ /** 'ok' | 'modified' | 'missing' for a skills-directory lock entry. */
27
+ export function entryState(entry) {
28
+ if (entry.kind === 'plugin') return 'plugin';
29
+ const h = hashDir(entry.path);
30
+ if (h === null) return 'missing';
31
+ return h === entry.sha256 ? 'ok' : 'modified';
32
+ }
33
+
34
+ /**
35
+ * Plan and run an install of `skillNames` (default: every skill in the pack) from `pack`.
36
+ * Returns { rows, skipped } for the report. Throws when no agent is selected.
37
+ */
38
+ export function installSkills(ctx, pack, skillNames, opts) {
39
+ const wanted = skillNames.length ? skillNames : pack.catalog.map((s) => s.name);
40
+ for (const s of wanted) {
41
+ if (!pack.catalog.some((c) => c.name === s)) {
42
+ throw new Error(`pack ${pack.name} has no skill '${s}' (has: ${pack.catalog.map((c) => c.name).join(', ')})`);
43
+ }
44
+ }
45
+ const agents = selectAgents(ctx, opts.agents);
46
+ if (!agents.length) {
47
+ throw new Error('no coding agent detected; name one with --agent <id> (see `xtframe-skills agents`) or --agent all');
48
+ }
49
+ const scope = opts.project ? 'project' : 'global';
50
+ const lock = readLock(ctx);
51
+ const rows = [];
52
+ const skipped = [];
53
+
54
+ // Plugin route first: those agents get the pack's plugin instead of loose skill folders.
55
+ const dirAgents = [];
56
+ for (const agent of agents) {
57
+ if (opts.plugin && agent.plugin && pack.pluginDir) {
58
+ const avail = pluginRouteAvailable(agent);
59
+ if (avail.ok) {
60
+ const entry = installPlugin(ctx, agent, pack, scope);
61
+ lock.entries = lock.entries.filter((e) => !(e.kind === 'plugin' && e.agent === agent.id && e.plugin === entry.plugin));
62
+ lock.entries.push(entry);
63
+ rows.push({ agent: agent.id, skill: `${entry.plugin} (plugin)`, path: entry.marketplaceDir, action: ctx.dryRun ? 'would install' : 'installed' });
64
+ continue;
65
+ }
66
+ skipped.push({ agent: agent.id, reason: `plugin route unavailable (${avail.reason}); installing skill folders instead` });
67
+ }
68
+ dirAgents.push(agent);
69
+ }
70
+
71
+ // Group agents that share a skills directory (several read ~/.agents/skills or .agents/skills).
72
+ const groups = new Map();
73
+ for (const agent of dirAgents) {
74
+ const dir = skillsDir(agent, scope, ctx);
75
+ if (!dir) {
76
+ skipped.push({ agent: agent.id, reason: `no ${scope} skills directory` });
77
+ continue;
78
+ }
79
+ const key = path.resolve(dir).toLowerCase();
80
+ if (!groups.has(key)) groups.set(key, { dir, agents: [] });
81
+ groups.get(key).agents.push(agent.id);
82
+ }
83
+
84
+ for (const { dir, agents: ids } of groups.values()) {
85
+ for (const skill of wanted) {
86
+ const dest = path.join(dir, skill);
87
+ const prev = lock.entries.find((e) => e.kind !== 'plugin' && samePath(e.path, dest));
88
+ const exists = fs.existsSync(dest);
89
+ if (exists && !opts.force) {
90
+ if (!prev) {
91
+ skipped.push({ agent: ids.join(','), reason: `${dest} exists and was not installed by xtframe-skills (use --force to replace)` });
92
+ continue;
93
+ }
94
+ if (entryState(prev) === 'modified') {
95
+ skipped.push({ agent: ids.join(','), reason: `${dest} was edited after install (use --force to replace)` });
96
+ continue;
97
+ }
98
+ }
99
+ const src = path.join(pack.skillsDir, skill);
100
+ if (!ctx.dryRun) replaceDir(src, dest);
101
+ const entry = {
102
+ kind: 'skill',
103
+ skill,
104
+ path: dest,
105
+ scope,
106
+ agents: [...new Set([...(prev?.agents || []), ...ids])],
107
+ pack: pack.name,
108
+ version: pack.version,
109
+ sha256: hashDir(src),
110
+ installedAt: new Date().toISOString(),
111
+ };
112
+ lock.entries = lock.entries.filter((e) => e !== prev);
113
+ lock.entries.push(entry);
114
+ const action = ctx.dryRun ? 'would install' : prev ? (prev.version === pack.version ? 'reinstalled' : `updated ${prev.version} ->`) : 'installed';
115
+ rows.push({ agent: ids.join(','), skill, path: dest, action, version: pack.version });
116
+ }
117
+ }
118
+ writeLock(ctx, lock);
119
+ return { rows, skipped };
120
+ }
121
+
122
+ /** Remove lock entries matching `skillNames` (all when empty) and `agentIds` (all when empty). */
123
+ export function removeSkills(ctx, skillNames, opts) {
124
+ const lock = readLock(ctx);
125
+ const agentIds = opts.agents ? opts.agents.split(',').map((s) => s.trim()) : null;
126
+ const rows = [];
127
+ const keep = [];
128
+ for (const e of lock.entries) {
129
+ const name = e.kind === 'plugin' ? e.plugin : e.skill;
130
+ const nameHit = !skillNames.length || skillNames.includes(name) || (e.kind === 'plugin' && e.skills?.some((s) => skillNames.includes(s)));
131
+ const agentHit = !agentIds || (e.kind === 'plugin' ? agentIds.includes(e.agent) : e.agents.some((a) => agentIds.includes(a)));
132
+ if (!nameHit || !agentHit) {
133
+ keep.push(e);
134
+ continue;
135
+ }
136
+ if (e.kind === 'plugin') {
137
+ removePlugin(ctx, e);
138
+ rows.push({ agent: e.agent, skill: `${e.plugin} (plugin)`, path: e.marketplaceDir, action: ctx.dryRun ? 'would remove' : 'removed' });
139
+ continue;
140
+ }
141
+ const state = entryState(e);
142
+ if (state === 'modified' && !opts.force) {
143
+ keep.push(e);
144
+ rows.push({ agent: e.agents.join(','), skill: e.skill, path: e.path, action: 'kept (edited; --force removes it)' });
145
+ continue;
146
+ }
147
+ if (!ctx.dryRun && state !== 'missing') removeDir(e.path);
148
+ rows.push({ agent: e.agents.join(','), skill: e.skill, path: e.path, action: ctx.dryRun ? 'would remove' : state === 'missing' ? 'forgot (already gone)' : 'removed' });
149
+ }
150
+ lock.entries = keep;
151
+ pruneMarketplace(ctx, keep);
152
+ writeLock(ctx, lock);
153
+ return rows;
154
+ }