@atheory-ai/skillex 0.9.1 → 0.11.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/README.md +20 -3
- package/bin/acquire.js +113 -0
- package/bin/install.js +17 -0
- package/bin/skillex.js +26 -67
- package/package.json +3 -7
- package/bin/.gitkeep +0 -0
package/README.md
CHANGED
|
@@ -34,8 +34,25 @@ pnpm add -D @atheory-ai/skillex
|
|
|
34
34
|
yarn add -D @atheory-ai/skillex
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
|
|
38
|
-
|
|
37
|
+
GitHub Releases are the canonical signed binaries. This package contains only a
|
|
38
|
+
wrapper, with no native payload or platform dependencies. Postinstall downloads
|
|
39
|
+
and SHA-256-verifies the archive from `v<package-version>`; runtime retries if
|
|
40
|
+
installation was offline or scripts were disabled, and verifies the cached archive
|
|
41
|
+
before extracting and executing a fresh binary.
|
|
42
|
+
|
|
43
|
+
Requires Node.js 18+ and `tar` (ZIP-capable `tar` is included in Windows 10+).
|
|
44
|
+
Supports macOS arm64/x64, Linux arm64/x64, and Windows x64. Downloads require HTTPS
|
|
45
|
+
access to GitHub and its asset CDN. Checksum verification does not validate cosign
|
|
46
|
+
signatures.
|
|
47
|
+
|
|
48
|
+
Set `SKILLEX_CACHE_DIR` to override the default `$XDG_CACHE_HOME/skillex` or
|
|
49
|
+
`~/.cache/skillex` archive cache. `SKILLEX_SKIP_DOWNLOAD=1` skips postinstall only;
|
|
50
|
+
first use still acquires the release. `SKILLEX_OFFLINE=1` forbids downloads and
|
|
51
|
+
requires a valid cache. Warm the cache online, or seed
|
|
52
|
+
`<cache>/<package-version>/<platform>-<arch>/` with the matching canonical archive
|
|
53
|
+
and `checksums.txt`. Missing or corrupt offline archives fail clearly. Registry
|
|
54
|
+
access alone is insufficient for a first run. Cached releases survive removal of
|
|
55
|
+
`node_modules`; remove a version directory to evict it.
|
|
39
56
|
|
|
40
57
|
## Experimental downstream MCP broker
|
|
41
58
|
|
|
@@ -92,7 +109,7 @@ but is not the recommended agent workflow.
|
|
|
92
109
|
## Example workflow
|
|
93
110
|
|
|
94
111
|
1. Add repo skills in `skills/` and configure scopes in `skillex.json`
|
|
95
|
-
2. Run `skillex refresh` after changing skills
|
|
112
|
+
2. Run `skillex refresh` after changing `skills/`, configuration, packs, or installed dependencies. A running MCP server updates project skill directories already in the index, such as `.cursor/skills`, without another refresh
|
|
96
113
|
3. Let your agent query, narrow, and read only the skills relevant to its current task
|
|
97
114
|
|
|
98
115
|
## Packs
|
package/bin/acquire.js
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const fs = require("node:fs/promises");
|
|
4
|
+
const os = require("node:os");
|
|
5
|
+
const path = require("node:path");
|
|
6
|
+
const https = require("node:https");
|
|
7
|
+
const { createHash } = require("node:crypto");
|
|
8
|
+
const { execFileSync } = require("node:child_process");
|
|
9
|
+
const { version } = require("../package.json");
|
|
10
|
+
|
|
11
|
+
const TARGETS = {
|
|
12
|
+
"darwin-arm64": ["darwin", "arm64", "tar.gz"],
|
|
13
|
+
"darwin-x64": ["darwin", "amd64", "tar.gz"],
|
|
14
|
+
"linux-arm64": ["linux", "arm64", "tar.gz"],
|
|
15
|
+
"linux-x64": ["linux", "amd64", "tar.gz"],
|
|
16
|
+
"win32-x64": ["windows", "amd64", "zip"],
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
function target(platform = process.platform, arch = process.arch) {
|
|
20
|
+
const key = `${platform}-${arch}`;
|
|
21
|
+
if (!TARGETS[key]) throw new Error(`skillex: unsupported platform "${key}". Supported platforms: ${Object.keys(TARGETS).join(", ")}`);
|
|
22
|
+
const [goos, goarch, extension] = TARGETS[key];
|
|
23
|
+
return { key, archive: `skillex_${version}_${goos}_${goarch}.${extension}`, binary: platform === "win32" ? "skillex.exe" : "skillex" };
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
// GitHub redirects release downloads to its asset CDN. Never downgrade to HTTP.
|
|
27
|
+
function download(url, redirects = 0) {
|
|
28
|
+
return new Promise((resolve, reject) => {
|
|
29
|
+
const parsed = new URL(url);
|
|
30
|
+
if (parsed.protocol !== "https:") return reject(new Error("skillex: release downloads require HTTPS"));
|
|
31
|
+
const req = https.get(parsed, { headers: { "User-Agent": `skillex-npm/${version}` } }, (res) => {
|
|
32
|
+
if ([301, 302, 303, 307, 308].includes(res.statusCode)) {
|
|
33
|
+
res.resume();
|
|
34
|
+
if (redirects >= 5 || !res.headers.location) return reject(new Error("skillex: too many release redirects"));
|
|
35
|
+
resolve(download(new URL(res.headers.location, parsed).href, redirects + 1));
|
|
36
|
+
return;
|
|
37
|
+
}
|
|
38
|
+
if (res.statusCode !== 200) {
|
|
39
|
+
res.resume();
|
|
40
|
+
return reject(new Error(`skillex: download failed (${res.statusCode}) for ${url}`));
|
|
41
|
+
}
|
|
42
|
+
const chunks = [];
|
|
43
|
+
let size = 0;
|
|
44
|
+
res.on("data", (chunk) => {
|
|
45
|
+
size += chunk.length;
|
|
46
|
+
if (size > 100 * 1024 * 1024) res.destroy(new Error("skillex: release asset exceeds 100 MiB"));
|
|
47
|
+
else chunks.push(chunk);
|
|
48
|
+
});
|
|
49
|
+
res.on("end", () => resolve(Buffer.concat(chunks)));
|
|
50
|
+
res.on("error", reject);
|
|
51
|
+
});
|
|
52
|
+
req.setTimeout(30000, () => req.destroy(new Error("skillex: release download timed out")));
|
|
53
|
+
req.on("error", reject);
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function verify(archive, checksums, filename) {
|
|
58
|
+
const rows = checksums.toString("utf8").split(/\r?\n/).map((line) => line.match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/)).filter((row) => row && row[2] === filename);
|
|
59
|
+
if (rows.length !== 1) throw new Error(`skillex: expected exactly one SHA-256 checksum for ${filename}`);
|
|
60
|
+
if (createHash("sha256").update(archive).digest("hex") !== rows[0][1].toLowerCase()) throw new Error(`skillex: SHA-256 checksum mismatch for ${filename}`);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
async function acquire(options = {}) {
|
|
64
|
+
const selected = options.target || target();
|
|
65
|
+
const cacheRoot = options.cacheRoot || process.env.SKILLEX_CACHE_DIR || path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "skillex");
|
|
66
|
+
const cache = path.join(cacheRoot, version, selected.key);
|
|
67
|
+
const offline = options.offline ?? process.env.SKILLEX_OFFLINE === "1";
|
|
68
|
+
const fetch = options.download || download;
|
|
69
|
+
let archive;
|
|
70
|
+
let checksums;
|
|
71
|
+
try {
|
|
72
|
+
[archive, checksums] = await Promise.all([fs.readFile(path.join(cache, selected.archive)), fs.readFile(path.join(cache, "checksums.txt"))]);
|
|
73
|
+
verify(archive, checksums, selected.archive);
|
|
74
|
+
} catch (error) {
|
|
75
|
+
if (offline) throw new Error(`skillex: no verified cached release for ${version}/${selected.key} in ${cache}. SKILLEX_OFFLINE=1 prevents downloads. ${error.message}`);
|
|
76
|
+
const base = `https://github.com/atheory-ai/skillex/releases/download/v${version}`;
|
|
77
|
+
[archive, checksums] = await Promise.all([fetch(`${base}/${selected.archive}`), fetch(`${base}/checksums.txt`)]);
|
|
78
|
+
verify(archive, checksums, selected.archive);
|
|
79
|
+
await fs.mkdir(cache, { recursive: true });
|
|
80
|
+
// Unique staging names avoid partial reads and collisions between npm invocations.
|
|
81
|
+
const staging = await fs.mkdtemp(path.join(cache, ".download-"));
|
|
82
|
+
try {
|
|
83
|
+
await fs.writeFile(path.join(staging, selected.archive), archive);
|
|
84
|
+
await fs.writeFile(path.join(staging, "checksums.txt"), checksums);
|
|
85
|
+
await fs.rename(path.join(staging, selected.archive), path.join(cache, selected.archive));
|
|
86
|
+
await fs.rename(path.join(staging, "checksums.txt"), path.join(cache, "checksums.txt"));
|
|
87
|
+
} finally {
|
|
88
|
+
await fs.rm(staging, { recursive: true, force: true });
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return { archive, selected };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
async function prepareBinary(options = {}) {
|
|
95
|
+
const { archive, selected } = await acquire(options);
|
|
96
|
+
const directory = await fs.mkdtemp(path.join(os.tmpdir(), "skillex-npm-"));
|
|
97
|
+
try {
|
|
98
|
+
const archivePath = path.join(directory, selected.archive);
|
|
99
|
+
await fs.writeFile(archivePath, archive);
|
|
100
|
+
// Windows 10+ includes bsdtar, which also reads ZIP. Extract only the binary.
|
|
101
|
+
execFileSync("tar", ["-xf", archivePath, "-C", directory, selected.binary], { stdio: "pipe" });
|
|
102
|
+
const binary = path.join(directory, selected.binary);
|
|
103
|
+
const stat = await fs.lstat(binary);
|
|
104
|
+
if (!stat.isFile()) throw new Error("skillex: release binary is not a regular file");
|
|
105
|
+
await fs.chmod(binary, 0o755);
|
|
106
|
+
return { binary, cleanup: () => fs.rm(directory, { recursive: true, force: true }) };
|
|
107
|
+
} catch (error) {
|
|
108
|
+
await fs.rm(directory, { recursive: true, force: true });
|
|
109
|
+
throw new Error(`skillex: cannot extract verified release (tar is required): ${error.message}`);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
module.exports = { target, verify, acquire, prepareBinary, TARGETS };
|
package/bin/install.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
|
|
4
|
+
const { target, acquire } = require("./acquire");
|
|
5
|
+
try {
|
|
6
|
+
target();
|
|
7
|
+
} catch (error) {
|
|
8
|
+
process.stderr.write(`${error.message}\n`);
|
|
9
|
+
process.exit(1);
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
if (process.env.SKILLEX_SKIP_DOWNLOAD !== "1") {
|
|
13
|
+
acquire().catch((error) => {
|
|
14
|
+
// A package install may happen offline or on a build host. Runtime retries.
|
|
15
|
+
process.stderr.write(`${error.message}\nSkillex will retry acquisition on first use. Set SKILLEX_SKIP_DOWNLOAD=1 to skip postinstall acquisition.\n`);
|
|
16
|
+
});
|
|
17
|
+
}
|
package/bin/skillex.js
CHANGED
|
@@ -1,71 +1,30 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
"use strict";
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
const
|
|
12
|
-
const
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
"
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
if (!packageName) {
|
|
28
|
-
throw new Error(
|
|
29
|
-
`skillex: unsupported platform "${key}"\n` +
|
|
30
|
-
`Supported platforms: ${Object.keys(PLATFORM_PACKAGES).join(", ")}\n` +
|
|
31
|
-
`\nPlease open an issue at https://github.com/atheory-ai/skillex/issues`
|
|
32
|
-
);
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
let packageDir;
|
|
36
|
-
try {
|
|
37
|
-
// require.resolve finds the package.json of the platform package,
|
|
38
|
-
// which npm installed (or skipped if the platform didn't match).
|
|
39
|
-
packageDir = path.dirname(require.resolve(`${packageName}/package.json`));
|
|
40
|
-
} catch {
|
|
41
|
-
throw new Error(
|
|
42
|
-
`skillex: the platform package "${packageName}" is not installed.\n` +
|
|
43
|
-
`\nThis usually happens when optional dependencies were skipped. Try:\n` +
|
|
44
|
-
` npm install --include=optional\n` +
|
|
45
|
-
` pnpm install\n` +
|
|
46
|
-
` yarn install`
|
|
47
|
-
);
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
const isWindows = process.platform === "win32";
|
|
51
|
-
return path.join(packageDir, "bin", isWindows ? "skillex.exe" : "skillex");
|
|
52
|
-
}
|
|
53
|
-
|
|
54
|
-
let binaryPath;
|
|
55
|
-
try {
|
|
56
|
-
binaryPath = getBinaryPath();
|
|
57
|
-
} catch (err) {
|
|
58
|
-
process.stderr.write(err.message + "\n");
|
|
59
|
-
process.exit(1);
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
try {
|
|
63
|
-
execFileSync(binaryPath, process.argv.slice(2), {
|
|
64
|
-
stdio: "inherit",
|
|
65
|
-
windowsHide: false,
|
|
4
|
+
const { spawn } = require("node:child_process");
|
|
5
|
+
const { prepareBinary } = require("./acquire");
|
|
6
|
+
|
|
7
|
+
(async () => {
|
|
8
|
+
const { binary, cleanup } = await prepareBinary();
|
|
9
|
+
const child = spawn(binary, process.argv.slice(2), { stdio: "inherit", windowsHide: false });
|
|
10
|
+
const forward = (signal) => () => child.kill(signal);
|
|
11
|
+
const interrupt = forward("SIGINT");
|
|
12
|
+
const terminate = forward("SIGTERM");
|
|
13
|
+
process.on("SIGINT", interrupt);
|
|
14
|
+
process.on("SIGTERM", terminate);
|
|
15
|
+
child.once("error", async (error) => {
|
|
16
|
+
await cleanup();
|
|
17
|
+
process.stderr.write(`skillex: ${error.message}\n`);
|
|
18
|
+
process.exitCode = 1;
|
|
19
|
+
});
|
|
20
|
+
child.once("exit", async (code, signal) => {
|
|
21
|
+
process.removeListener("SIGINT", interrupt);
|
|
22
|
+
process.removeListener("SIGTERM", terminate);
|
|
23
|
+
await cleanup();
|
|
24
|
+
if (signal) process.kill(process.pid, signal);
|
|
25
|
+
else process.exitCode = code ?? 1;
|
|
66
26
|
});
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
}
|
|
27
|
+
})().catch((error) => {
|
|
28
|
+
process.stderr.write(`${error.message}\n`);
|
|
29
|
+
process.exitCode = 1;
|
|
30
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atheory-ai/skillex",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Skill management for AI agents in Node.js projects",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"homepage": "https://github.com/atheory-ai/skillex#readme",
|
|
@@ -28,11 +28,7 @@
|
|
|
28
28
|
"cli",
|
|
29
29
|
"monorepo"
|
|
30
30
|
],
|
|
31
|
-
"
|
|
32
|
-
"
|
|
33
|
-
"@atheory-ai/skillex-darwin-x64": "0.9.1",
|
|
34
|
-
"@atheory-ai/skillex-linux-x64": "0.9.1",
|
|
35
|
-
"@atheory-ai/skillex-linux-arm64": "0.9.1",
|
|
36
|
-
"@atheory-ai/skillex-win32-x64": "0.9.1"
|
|
31
|
+
"scripts": {
|
|
32
|
+
"postinstall": "node bin/install.js"
|
|
37
33
|
}
|
|
38
34
|
}
|
package/bin/.gitkeep
DELETED
|
File without changes
|