@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.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- package/src/tar.mjs +103 -0
package/src/packs.mjs
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
// Skill packs: an npm package (or this one) that carries skills, optionally a plugin directory
|
|
2
|
+
// and the name of its converter package. A pack declares itself in package.json:
|
|
3
|
+
// "keywords": ["xtframe-skill-pack"],
|
|
4
|
+
// "xtframe": { "skills": "<dir of skill folders>", "plugin": "<plugin dir>", "converter": "<pkg>" }
|
|
5
|
+
import fs from 'node:fs';
|
|
6
|
+
import path from 'node:path';
|
|
7
|
+
import { fileURLToPath } from 'node:url';
|
|
8
|
+
|
|
9
|
+
import { readJson, removeDir } from './fsutil.mjs';
|
|
10
|
+
import { checkSpec, npm } from './proc.mjs';
|
|
11
|
+
import { extractEntries, readTar } from './tar.mjs';
|
|
12
|
+
|
|
13
|
+
export const PACK_KEYWORD = 'xtframe-skill-pack';
|
|
14
|
+
const OWN_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
15
|
+
|
|
16
|
+
/** name and description from a SKILL.md frontmatter block (single-line values). */
|
|
17
|
+
export function readFrontmatter(file) {
|
|
18
|
+
const text = fs.readFileSync(file, 'utf8');
|
|
19
|
+
const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
|
|
20
|
+
const out = {};
|
|
21
|
+
if (!m) return out;
|
|
22
|
+
for (const line of m[1].split(/\r?\n/)) {
|
|
23
|
+
const kv = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
|
|
24
|
+
if (kv) out[kv[1]] = kv[2].replace(/^(["'])(.*)\1$/, '$2');
|
|
25
|
+
}
|
|
26
|
+
return out;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The skills repository of the workshop checkout `dir` sits in (docs/00-design.md §0.13): the
|
|
31
|
+
* nearest xtframe-skills.config.json above it names skillsRepoDir relative to its own directory;
|
|
32
|
+
* XTFRAME_SKILLS_REPO_DIR overrides it. Null outside a workshop checkout.
|
|
33
|
+
*/
|
|
34
|
+
function devSkillsRepo(dir) {
|
|
35
|
+
for (let d = path.resolve(dir); ; d = path.dirname(d)) {
|
|
36
|
+
const file = path.join(d, 'xtframe-skills.config.json');
|
|
37
|
+
if (fs.existsSync(file)) {
|
|
38
|
+
if (process.env.XTFRAME_SKILLS_REPO_DIR) return path.resolve(process.env.XTFRAME_SKILLS_REPO_DIR);
|
|
39
|
+
const rel = readJson(file, {}).skillsRepoDir;
|
|
40
|
+
return rel ? path.resolve(d, rel) : null;
|
|
41
|
+
}
|
|
42
|
+
if (path.dirname(d) === d) return null;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function packFromDir(root, pkg, builtin) {
|
|
47
|
+
const x = pkg.xtframe || {};
|
|
48
|
+
let skillsDir = x.skills ? path.join(root, x.skills) : null;
|
|
49
|
+
let pluginDir = x.plugin ? path.join(root, x.plugin) : null;
|
|
50
|
+
if (builtin && (!skillsDir || !fs.existsSync(skillsDir))) {
|
|
51
|
+
// Running from the workshop repository: payload/ is made only when packing, so read the
|
|
52
|
+
// skills repository its config names.
|
|
53
|
+
const skillsRepo = devSkillsRepo(root);
|
|
54
|
+
if (skillsRepo) {
|
|
55
|
+
pluginDir = path.join(skillsRepo, 'plugins', 'xtframe');
|
|
56
|
+
skillsDir = path.join(pluginDir, 'skills');
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
if (!skillsDir || !fs.existsSync(skillsDir)) throw new Error(`pack ${pkg.name}@${pkg.version} has no skills directory`);
|
|
60
|
+
const catalog = fs.readdirSync(skillsDir, { withFileTypes: true })
|
|
61
|
+
.filter((d) => d.isDirectory() && fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md')))
|
|
62
|
+
.map((d) => {
|
|
63
|
+
const fm = readFrontmatter(path.join(skillsDir, d.name, 'SKILL.md'));
|
|
64
|
+
return { name: d.name, description: fm.description || '' };
|
|
65
|
+
});
|
|
66
|
+
return {
|
|
67
|
+
name: pkg.name,
|
|
68
|
+
version: pkg.version,
|
|
69
|
+
root,
|
|
70
|
+
skillsDir,
|
|
71
|
+
pluginDir: pluginDir && fs.existsSync(pluginDir) ? pluginDir : null,
|
|
72
|
+
converter: x.converter || null,
|
|
73
|
+
catalog,
|
|
74
|
+
builtin,
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** The pack this CLI ships with. */
|
|
79
|
+
export function builtinPack() {
|
|
80
|
+
return packFromDir(OWN_DIR, readJson(path.join(OWN_DIR, 'package.json')), true);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export function ownPackage() {
|
|
84
|
+
return readJson(path.join(OWN_DIR, 'package.json'));
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Download `spec` from the npm registry into ~/.xtframe/store/ (no install scripts run). */
|
|
88
|
+
export function fetchPack(ctx, spec) {
|
|
89
|
+
checkSpec(spec);
|
|
90
|
+
const own = ownPackage();
|
|
91
|
+
const view = npm(['view', spec, 'name', 'version', '--json'], { cwd: ctx.xtHome });
|
|
92
|
+
if (view.status !== 0) throw new Error(`npm view ${spec} failed: ${(view.stderr || '').trim().split('\n').pop()}`);
|
|
93
|
+
let info = JSON.parse(view.stdout);
|
|
94
|
+
if (Array.isArray(info)) info = info[info.length - 1];
|
|
95
|
+
if (info.name === own.name && info.version === own.version) return builtinPack();
|
|
96
|
+
const store = path.join(ctx.xtHome, 'store', `${info.name.replace('/', '+')}@${info.version}`);
|
|
97
|
+
if (!fs.existsSync(path.join(store, 'package.json'))) {
|
|
98
|
+
const tmp = path.join(ctx.xtHome, 'tmp');
|
|
99
|
+
fs.mkdirSync(tmp, { recursive: true });
|
|
100
|
+
const r = npm(['pack', `${info.name}@${info.version}`, '--json', '--pack-destination', tmp], { cwd: tmp });
|
|
101
|
+
if (r.status !== 0) throw new Error(`npm pack ${info.name}@${info.version} failed: ${(r.stderr || '').trim()}`);
|
|
102
|
+
const file = path.join(tmp, JSON.parse(r.stdout)[0].filename);
|
|
103
|
+
removeDir(store);
|
|
104
|
+
extractEntries(readTar(fs.readFileSync(file)), store, { strip: 1 });
|
|
105
|
+
fs.rmSync(file, { force: true });
|
|
106
|
+
}
|
|
107
|
+
const pack = packFromDir(store, readJson(path.join(store, 'package.json')), false);
|
|
108
|
+
pack.spec = spec;
|
|
109
|
+
return pack;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Version of `name` under dist-tag `tag`, or null when the registry cannot be reached. */
|
|
113
|
+
export function registryVersion(ctx, name, tag = 'latest') {
|
|
114
|
+
const r = npm(['view', `${checkSpec(name)}@${tag}`, 'version', '--json'], { cwd: ctx.xtHome });
|
|
115
|
+
if (r.status !== 0 || !r.stdout.trim()) return null;
|
|
116
|
+
const v = JSON.parse(r.stdout);
|
|
117
|
+
return Array.isArray(v) ? v[v.length - 1] : v;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Packs on the npm registry with the pack keyword, filtered by `query` (matched against pack
|
|
122
|
+
* and skill names and descriptions). The built-in pack is always listed first; `offline` skips
|
|
123
|
+
* the registry.
|
|
124
|
+
*/
|
|
125
|
+
export function searchPacks(ctx, query, { offline = false } = {}) {
|
|
126
|
+
const own = builtinPack();
|
|
127
|
+
const results = [{ name: own.name, version: own.version, description: ownPackage().description, skills: own.catalog, installedWithCli: true }];
|
|
128
|
+
let registryError = null;
|
|
129
|
+
if (!offline) {
|
|
130
|
+
const r = npm(['search', `keywords:${PACK_KEYWORD}`, '--json', '--searchlimit', '100'], { cwd: ctx.xtHome });
|
|
131
|
+
if (r.status !== 0) {
|
|
132
|
+
registryError = (r.stderr || '').trim().split('\n').pop() || 'npm search failed';
|
|
133
|
+
} else {
|
|
134
|
+
for (const hit of JSON.parse(r.stdout || '[]')) {
|
|
135
|
+
if (hit.name === own.name) {
|
|
136
|
+
results[0].registryVersion = hit.version;
|
|
137
|
+
continue;
|
|
138
|
+
}
|
|
139
|
+
let skills = [];
|
|
140
|
+
const v = npm(['view', `${hit.name}@${hit.version}`, 'xtframe', '--json'], { cwd: ctx.xtHome });
|
|
141
|
+
if (v.status === 0 && v.stdout.trim()) skills = JSON.parse(v.stdout).catalog || [];
|
|
142
|
+
results.push({ name: hit.name, version: hit.version, description: hit.description || '', skills });
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
const q = (query || '').toLowerCase();
|
|
147
|
+
const match = (p) => !q || [p.name, p.description, ...p.skills.flatMap((s) => [s.name, s.description])]
|
|
148
|
+
.some((t) => (t || '').toLowerCase().includes(q));
|
|
149
|
+
return { packs: results.filter(match), registryError };
|
|
150
|
+
}
|
package/src/plugins.mjs
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
// The plugin route (`install --plugin`): agents with a plugin system get the pack's plugin
|
|
2
|
+
// directory through a local marketplace (~/.xtframe/marketplace, name `xtframe-local`), so
|
|
3
|
+
// Claude Code loads it in place and namespaces its skills (/xtframe:xtui). Copilot CLI reads the
|
|
4
|
+
// same .claude-plugin/marketplace.json (docs/01-research.md §1.3).
|
|
5
|
+
import fs from 'node:fs';
|
|
6
|
+
import path from 'node:path';
|
|
7
|
+
|
|
8
|
+
import { readJson, replaceDir, writeJson } from './fsutil.mjs';
|
|
9
|
+
import { hasCommand, runTool } from './proc.mjs';
|
|
10
|
+
|
|
11
|
+
export const LOCAL_MARKETPLACE = 'xtframe-local';
|
|
12
|
+
|
|
13
|
+
function agentCli(agent) {
|
|
14
|
+
if (agent.plugin === 'claude') return process.env.XTFRAME_SKILLS_CLAUDE || 'claude';
|
|
15
|
+
if (agent.plugin === 'copilot') return process.env.XTFRAME_SKILLS_COPILOT || 'copilot';
|
|
16
|
+
return null;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export function pluginRouteAvailable(agent) {
|
|
20
|
+
const cli = agentCli(agent);
|
|
21
|
+
if (!cli) return { ok: false, reason: 'no plugin system' };
|
|
22
|
+
return hasCommand(cli) ? { ok: true } : { ok: false, reason: `'${cli}' is not on PATH` };
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function marketplaceDir(ctx) {
|
|
26
|
+
return path.join(ctx.xtHome, 'marketplace');
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** Copy the pack's plugin into the local marketplace and (re)write its catalog. */
|
|
30
|
+
function stagePlugin(ctx, pack) {
|
|
31
|
+
const manifest = readJson(path.join(pack.pluginDir, '.claude-plugin', 'plugin.json'));
|
|
32
|
+
const dir = marketplaceDir(ctx);
|
|
33
|
+
const catalogFile = path.join(dir, '.claude-plugin', 'marketplace.json');
|
|
34
|
+
const catalog = readJson(catalogFile, { name: LOCAL_MARKETPLACE, owner: { name: 'xtframe-skills' }, plugins: [] });
|
|
35
|
+
catalog.description = 'Plugins installed by xtframe-skills from npm packs';
|
|
36
|
+
catalog.plugins = catalog.plugins.filter((p) => p.name !== manifest.name);
|
|
37
|
+
catalog.plugins.push({ name: manifest.name, source: `./plugins/${manifest.name}`, description: manifest.description || '', version: manifest.version });
|
|
38
|
+
if (!ctx.dryRun) {
|
|
39
|
+
replaceDir(pack.pluginDir, path.join(dir, 'plugins', manifest.name));
|
|
40
|
+
writeJson(catalogFile, catalog);
|
|
41
|
+
}
|
|
42
|
+
return { dir, plugin: manifest.name, version: manifest.version };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function must(r, what) {
|
|
46
|
+
if (r.error || r.status !== 0) {
|
|
47
|
+
throw new Error(`${what} failed: ${(r.stderr || r.stdout || r.error?.message || '').trim().split('\n').slice(-3).join(' | ')}`);
|
|
48
|
+
}
|
|
49
|
+
return r;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export function installPlugin(ctx, agent, pack, scope) {
|
|
53
|
+
const staged = stagePlugin(ctx, pack);
|
|
54
|
+
const cli = agentCli(agent);
|
|
55
|
+
const id = `${staged.plugin}@${LOCAL_MARKETPLACE}`;
|
|
56
|
+
if (!ctx.dryRun) {
|
|
57
|
+
const add = runTool(cli, ['plugin', 'marketplace', 'add', staged.dir]);
|
|
58
|
+
if (add.status !== 0) {
|
|
59
|
+
// Already registered: refresh it instead.
|
|
60
|
+
const text = `${add.stdout}\n${add.stderr}`;
|
|
61
|
+
if (!/already/i.test(text)) must(add, `${cli} plugin marketplace add`);
|
|
62
|
+
if (agent.plugin === 'claude') runTool(cli, ['plugin', 'marketplace', 'update', LOCAL_MARKETPLACE]);
|
|
63
|
+
}
|
|
64
|
+
const args = ['plugin', 'install', id];
|
|
65
|
+
if (agent.plugin === 'claude') args.push('--scope', scope === 'project' ? 'project' : 'user');
|
|
66
|
+
const cwd = scope === 'project' ? { cwd: ctx.cwd } : {};
|
|
67
|
+
const inst = runTool(cli, args, cwd);
|
|
68
|
+
if (inst.status !== 0 && /already/i.test(`${inst.stdout}\n${inst.stderr}`)) {
|
|
69
|
+
must(runTool(cli, ['plugin', 'update', id], cwd), `${cli} plugin update ${id}`);
|
|
70
|
+
} else {
|
|
71
|
+
must(inst, `${cli} plugin install ${id}`);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
return {
|
|
75
|
+
kind: 'plugin',
|
|
76
|
+
agent: agent.id,
|
|
77
|
+
plugin: staged.plugin,
|
|
78
|
+
marketplace: LOCAL_MARKETPLACE,
|
|
79
|
+
marketplaceDir: staged.dir,
|
|
80
|
+
scope,
|
|
81
|
+
pack: pack.name,
|
|
82
|
+
version: pack.version,
|
|
83
|
+
skills: pack.catalog.map((s) => s.name),
|
|
84
|
+
installedAt: new Date().toISOString(),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export function removePlugin(ctx, entry) {
|
|
89
|
+
if (ctx.dryRun) return;
|
|
90
|
+
const cli = agentCli({ plugin: entry.agent === 'github-copilot' ? 'copilot' : 'claude' });
|
|
91
|
+
const args = ['plugin', 'uninstall', `${entry.plugin}@${entry.marketplace}`];
|
|
92
|
+
if (entry.agent === 'claude-code') args.push('--scope', entry.scope === 'project' ? 'project' : 'user');
|
|
93
|
+
const r = runTool(cli, args, entry.scope === 'project' ? { cwd: ctx.cwd } : {});
|
|
94
|
+
if (r.status !== 0 && !/not installed|not found/i.test(`${r.stdout}${r.stderr}`)) must(r, `${cli} plugin uninstall`);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** Drop plugin folders of the local marketplace that no remaining lock entry uses. */
|
|
98
|
+
export function pruneMarketplace(ctx, remaining) {
|
|
99
|
+
const dir = marketplaceDir(ctx);
|
|
100
|
+
const catalogFile = path.join(dir, '.claude-plugin', 'marketplace.json');
|
|
101
|
+
if (ctx.dryRun || !fs.existsSync(catalogFile)) return;
|
|
102
|
+
const used = new Set(remaining.filter((e) => e.kind === 'plugin').map((e) => e.plugin));
|
|
103
|
+
const catalog = readJson(catalogFile);
|
|
104
|
+
for (const p of catalog.plugins.filter((x) => !used.has(x.name))) {
|
|
105
|
+
fs.rmSync(path.join(dir, 'plugins', p.name), { recursive: true, force: true });
|
|
106
|
+
}
|
|
107
|
+
catalog.plugins = catalog.plugins.filter((x) => used.has(x.name));
|
|
108
|
+
writeJson(catalogFile, catalog);
|
|
109
|
+
}
|
package/src/proc.mjs
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
// Running npm and agent CLIs without a shell where possible (Node refuses to spawn .cmd files
|
|
2
|
+
// without one on Windows, and a shell would re-parse paths with spaces).
|
|
3
|
+
import { spawnSync } from 'node:child_process';
|
|
4
|
+
import fs from 'node:fs';
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
|
|
7
|
+
const SPEC = /^(@[a-z0-9~][a-z0-9._~-]*\/)?[a-z0-9~][a-z0-9._~-]*(@[a-z0-9.+-]+)?$/i;
|
|
8
|
+
|
|
9
|
+
// A release tag of a GitHub repository, such as the kit (docs/00-design.md §0.11).
|
|
10
|
+
const GITHUB_SPEC = /^github:[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+#v\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* npm package spec `name[@version|tag]` or `github:<owner>/<repo>#v<semver>`, checked before it
|
|
14
|
+
* reaches a command line.
|
|
15
|
+
*/
|
|
16
|
+
export function checkSpec(spec) {
|
|
17
|
+
if (!SPEC.test(spec) && !GITHUB_SPEC.test(spec)) throw new Error(`not a package spec: ${spec}`);
|
|
18
|
+
return spec;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function npmCli() {
|
|
22
|
+
const cands = [];
|
|
23
|
+
if (process.env.npm_execpath && /npm-cli\.js$/.test(process.env.npm_execpath)) cands.push(process.env.npm_execpath);
|
|
24
|
+
const nodeDir = path.dirname(process.execPath);
|
|
25
|
+
cands.push(path.join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
|
|
26
|
+
cands.push(path.join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'));
|
|
27
|
+
return cands.find((c) => fs.existsSync(c)) || null;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function quote(a) {
|
|
31
|
+
return /^[\w@%+=:,./\\-]+$/.test(a) ? a : `"${a.replace(/"/g, '\\"')}"`;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Run `cmd args`; on Windows retry through the shell for .cmd shims. Returns spawnSync result. */
|
|
35
|
+
export function runTool(cmd, args, opts = {}) {
|
|
36
|
+
const base = { encoding: 'utf8', windowsHide: true, maxBuffer: 256 * 1024 * 1024, ...opts };
|
|
37
|
+
let r = spawnSync(cmd, args, base);
|
|
38
|
+
if (r.error && process.platform === 'win32' && (r.error.code === 'ENOENT' || r.error.code === 'EINVAL')) {
|
|
39
|
+
r = spawnSync([cmd, ...args].map(quote).join(' '), { ...base, shell: true });
|
|
40
|
+
// The shell reports a missing command as exit 1 with a message on stderr, not ENOENT.
|
|
41
|
+
if (r.status !== 0 && /is not recognized|not found/i.test(r.stderr || '')) {
|
|
42
|
+
r.error = Object.assign(new Error(`${cmd} not found`), { code: 'ENOENT' });
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
return r;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Run npm with `args`; returns spawnSync result (stdout as string). */
|
|
49
|
+
export function npm(args, opts = {}) {
|
|
50
|
+
const cli = npmCli();
|
|
51
|
+
if (cli) return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8', windowsHide: true, maxBuffer: 256 * 1024 * 1024, ...opts });
|
|
52
|
+
return runTool('npm', args, opts);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** True when `cmd` can be started (used to detect agent CLIs such as `claude`). */
|
|
56
|
+
export function hasCommand(cmd) {
|
|
57
|
+
const r = runTool(cmd, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'], timeout: 20000 });
|
|
58
|
+
return !r.error && r.status === 0;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Absolute path of `cmd` on PATH, or null. */
|
|
62
|
+
export function which(cmd) {
|
|
63
|
+
const r = process.platform === 'win32' ? runTool('where', [cmd]) : runTool('which', [cmd]);
|
|
64
|
+
if (r.error || r.status !== 0) return null;
|
|
65
|
+
return r.stdout.split(/\r?\n/).find(Boolean) || null;
|
|
66
|
+
}
|
package/src/tar.mjs
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
// Minimal tar reader (ustar + pax), enough for `git archive` output and npm tarballs.
|
|
2
|
+
// Zero dependencies on purpose: the CLI must run from `npx` with nothing else installed, and the
|
|
3
|
+
// system `tar` differs between Windows (bsdtar), Git Bash (GNU tar, which reads `C:` as a host)
|
|
4
|
+
// and macOS.
|
|
5
|
+
import fs from 'node:fs';
|
|
6
|
+
import path from 'node:path';
|
|
7
|
+
import zlib from 'node:zlib';
|
|
8
|
+
|
|
9
|
+
function cstr(buf, start, len) {
|
|
10
|
+
const end = buf.indexOf(0, start);
|
|
11
|
+
return buf.toString('utf8', start, end < 0 || end > start + len ? start + len : end);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
function octal(buf, start, len) {
|
|
15
|
+
const s = cstr(buf, start, len).trim();
|
|
16
|
+
return s ? parseInt(s, 8) : 0;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function parsePax(data) {
|
|
20
|
+
const out = {};
|
|
21
|
+
let i = 0;
|
|
22
|
+
while (i < data.length) {
|
|
23
|
+
const sp = data.indexOf(0x20, i);
|
|
24
|
+
if (sp < 0) break;
|
|
25
|
+
const len = parseInt(data.toString('utf8', i, sp), 10);
|
|
26
|
+
if (!len) break;
|
|
27
|
+
const rec = data.toString('utf8', sp + 1, i + len - 1);
|
|
28
|
+
const eq = rec.indexOf('=');
|
|
29
|
+
if (eq > 0) out[rec.slice(0, eq)] = rec.slice(eq + 1);
|
|
30
|
+
i += len;
|
|
31
|
+
}
|
|
32
|
+
return out;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Parse a tar (or .tgz when gzip magic is present) buffer into entries. */
|
|
36
|
+
export function readTar(input) {
|
|
37
|
+
let buf = input;
|
|
38
|
+
if (buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b) buf = zlib.gunzipSync(buf);
|
|
39
|
+
const entries = [];
|
|
40
|
+
let pax = {};
|
|
41
|
+
let longName = null;
|
|
42
|
+
let off = 0;
|
|
43
|
+
while (off + 512 <= buf.length) {
|
|
44
|
+
const header = buf.subarray(off, off + 512);
|
|
45
|
+
if (header.every((b) => b === 0)) break;
|
|
46
|
+
const size = octal(header, 124, 12);
|
|
47
|
+
const type = String.fromCharCode(header[156] || 0x30);
|
|
48
|
+
const dataStart = off + 512;
|
|
49
|
+
const data = buf.subarray(dataStart, dataStart + size);
|
|
50
|
+
off = dataStart + Math.ceil(size / 512) * 512;
|
|
51
|
+
if (type === 'x') {
|
|
52
|
+
pax = { ...pax, ...parsePax(data) };
|
|
53
|
+
continue;
|
|
54
|
+
}
|
|
55
|
+
if (type === 'g') continue; // global header (git archive puts the commit id here)
|
|
56
|
+
if (type === 'L') {
|
|
57
|
+
longName = cstr(data, 0, data.length);
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
let name = cstr(header, 0, 100);
|
|
61
|
+
const prefix = cstr(header, 345, 155);
|
|
62
|
+
if (prefix) name = `${prefix}/${name}`;
|
|
63
|
+
if (longName) name = longName;
|
|
64
|
+
if (pax.path) name = pax.path;
|
|
65
|
+
entries.push({
|
|
66
|
+
path: name,
|
|
67
|
+
type: type === '5' ? 'dir' : type === '0' || type === '\0' || type === '7' ? 'file' : 'other',
|
|
68
|
+
mode: octal(header, 100, 8),
|
|
69
|
+
data: Buffer.from(data),
|
|
70
|
+
});
|
|
71
|
+
pax = {};
|
|
72
|
+
longName = null;
|
|
73
|
+
}
|
|
74
|
+
return entries;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Write entries under `dest`. `strip` drops leading path segments; `filter(relPath)` keeps an
|
|
79
|
+
* entry when it returns true. Paths that would leave `dest` throw.
|
|
80
|
+
*/
|
|
81
|
+
export function extractEntries(entries, dest, { strip = 0, filter = () => true } = {}) {
|
|
82
|
+
const root = path.resolve(dest);
|
|
83
|
+
const written = [];
|
|
84
|
+
for (const e of entries) {
|
|
85
|
+
if (e.type === 'other') continue;
|
|
86
|
+
const parts = e.path.split('/').filter((p) => p && p !== '.');
|
|
87
|
+
if (parts.length <= strip) continue;
|
|
88
|
+
const rel = parts.slice(strip).join('/');
|
|
89
|
+
if (!filter(rel)) continue;
|
|
90
|
+
const target = path.resolve(root, rel);
|
|
91
|
+
if (target !== root && !target.startsWith(root + path.sep)) {
|
|
92
|
+
throw new Error(`tar entry escapes the destination: ${e.path}`);
|
|
93
|
+
}
|
|
94
|
+
if (e.type === 'dir') {
|
|
95
|
+
fs.mkdirSync(target, { recursive: true });
|
|
96
|
+
} else {
|
|
97
|
+
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
98
|
+
fs.writeFileSync(target, e.data);
|
|
99
|
+
written.push(rel);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return written;
|
|
103
|
+
}
|