@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 CHANGED
@@ -34,8 +34,25 @@ pnpm add -D @atheory-ai/skillex
34
34
  yarn add -D @atheory-ai/skillex
35
35
  ```
36
36
 
37
- The wrapper package installs the correct native binary for your platform through
38
- npm `optionalDependencies`.
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, configuration, or installed dependencies
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
- // This script is the platform selector shim for @atheory-ai/skillex.
5
- //
6
- // npm installs only the optionalDependency that matches the current
7
- // platform (via the "os" and "cpu" fields in each platform package).
8
- // This script resolves which platform package was installed, locates
9
- // its binary, and exec's it — passing all arguments through.
10
-
11
- const { execFileSync } = require("child_process");
12
- const path = require("path");
13
-
14
- // Maps process.platform + process.arch to the npm package name.
15
- const PLATFORM_PACKAGES = {
16
- "darwin-arm64": "@atheory-ai/skillex-darwin-arm64",
17
- "darwin-x64": "@atheory-ai/skillex-darwin-x64",
18
- "linux-x64": "@atheory-ai/skillex-linux-x64",
19
- "linux-arm64": "@atheory-ai/skillex-linux-arm64",
20
- "win32-x64": "@atheory-ai/skillex-win32-x64",
21
- };
22
-
23
- function getBinaryPath() {
24
- const key = `${process.platform}-${process.arch}`;
25
- const packageName = PLATFORM_PACKAGES[key];
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
- } catch (err) {
68
- // execFileSync throws when the child exits non-zero.
69
- // The child already printed its own output; we just mirror the exit code.
70
- process.exit(err.status ?? 1);
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.9.1",
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
- "optionalDependencies": {
32
- "@atheory-ai/skillex-darwin-arm64": "0.9.1",
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