@rafter-security/cli 0.7.0 → 0.7.2

package/dist/commands/skill/registry.js

@@ -0,0 +1,273 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+import { ConfigManager } from "../../core/config-manager.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Rafter-authored skills that ship inside this package. Lifecycle commands
+ * (`rafter skill list/install/uninstall`) only operate on names in this list —
+ * the intent is to manage first-party skills, not arbitrary third-party files.
+ */
+export const KNOWN_SKILL_NAMES = [
+    "rafter",
+    "rafter-agent-security",
+    "rafter-secure-design",
+    "rafter-code-review",
+    "rafter-skill-review",
+];
+export const SKILL_PLATFORMS = [
+    "claude-code",
+    "codex",
+    "openclaw",
+    "cursor",
+];
+function skillsResourcesRoot() {
+    return path.join(__dirname, "..", "..", "..", "resources", "skills");
+}
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const out = {};
+    for (const line of match[1].split("\n")) {
+        const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!m)
+            continue;
+        let val = m[2].trim();
+        if (val.startsWith('"') && val.endsWith('"'))
+            val = val.slice(1, -1);
+        else if (val.startsWith("'") && val.endsWith("'"))
+            val = val.slice(1, -1);
+        out[m[1]] = val;
+    }
+    return out;
+}
+/** Read frontmatter from a SKILL.md file on disk. Returns {} on any failure. */
+export function readSkillFrontmatter(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return parseFrontmatter(content);
+    }
+    catch {
+        return {};
+    }
+}
+/** Enumerate bundled rafter-authored skills present in this installation. */
+export function listBundledSkills() {
+    const root = skillsResourcesRoot();
+    const skills = [];
+    for (const name of KNOWN_SKILL_NAMES) {
+        const sourcePath = path.join(root, name, "SKILL.md");
+        if (!fs.existsSync(sourcePath))
+            continue;
+        const fm = readSkillFrontmatter(sourcePath);
+        skills.push({
+            name,
+            version: fm.version ?? "unknown",
+            description: fm.description ?? "",
+            sourcePath,
+        });
+    }
+    return skills;
+}
+export function resolveSkill(name) {
+    const normalized = name.trim();
+    return listBundledSkills().find((s) => s.name === normalized);
+}
+export function skillDetectDir(platform) {
+    const home = os.homedir();
+    switch (platform) {
+        case "claude-code":
+            return path.join(home, ".claude");
+        case "codex":
+            return path.join(home, ".codex");
+        case "openclaw":
+            return path.join(home, ".openclaw");
+        case "cursor":
+            return path.join(home, ".cursor");
+    }
+}
+/**
+ * Base directory where a platform stores INSTALLED skill files. Used by
+ * `rafter skill review --installed` to walk every skill on this machine.
+ *
+ * Shape per platform (see `skillDestPath` for where we *write* skills):
+ *   claude-code → ~/.claude/skills/<name>/SKILL.md
+ *   codex       → ~/.agents/skills/<name>/SKILL.md
+ *   openclaw    → ~/.openclaw/skills/<name>.md
+ *   cursor      → ~/.cursor/rules/<name>.mdc
+ */
+export function skillBaseDir(platform) {
+    const home = os.homedir();
+    switch (platform) {
+        case "claude-code":
+            return path.join(home, ".claude", "skills");
+        case "codex":
+            return path.join(home, ".agents", "skills");
+        case "openclaw":
+            return path.join(home, ".openclaw", "skills");
+        case "cursor":
+            return path.join(home, ".cursor", "rules");
+    }
+}
+/**
+ * Walk every known platform's skill base directory and return one entry per
+ * installed skill file. Platform layout determines whether skills are per-dir
+ * (claude-code, codex) or flat files (openclaw, cursor). Missing base dirs are
+ * silently skipped. Unreadable entries are silently skipped (permission denied
+ * on a single subdir never aborts the whole walk).
+ */
+export function discoverInstalledSkills(platform) {
+    const targets = platform ? [platform] : SKILL_PLATFORMS;
+    const out = [];
+    for (const p of targets) {
+        const base = skillBaseDir(p);
+        let entries;
+        try {
+            entries = fs.readdirSync(base, { withFileTypes: true });
+        }
+        catch {
+            continue; // missing or unreadable → nothing to audit here
+        }
+        for (const entry of entries) {
+            const full = path.join(base, entry.name);
+            if (p === "claude-code" || p === "codex") {
+                if (!entry.isDirectory())
+                    continue;
+                const skillFile = path.join(full, "SKILL.md");
+                try {
+                    if (!fs.statSync(skillFile).isFile())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                out.push({ platform: p, name: entry.name, path: skillFile });
+            }
+            else if (p === "openclaw") {
+                if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md"))
+                    continue;
+                out.push({
+                    platform: p,
+                    name: entry.name.replace(/\.md$/i, ""),
+                    path: full,
+                });
+            }
+            else if (p === "cursor") {
+                if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".mdc"))
+                    continue;
+                out.push({
+                    platform: p,
+                    name: entry.name.replace(/\.mdc$/i, ""),
+                    path: full,
+                });
+            }
+        }
+    }
+    // Deterministic ordering — tests golden-file against this.
+    out.sort((a, b) => {
+        if (a.platform !== b.platform)
+            return a.platform.localeCompare(b.platform);
+        return a.name.localeCompare(b.name);
+    });
+    return out;
+}
+/** Destination file path for a skill on a given platform. */
+export function skillDestPath(platform, skillName) {
+    const home = os.homedir();
+    switch (platform) {
+        case "claude-code":
+            return path.join(home, ".claude", "skills", skillName, "SKILL.md");
+        case "codex":
+            return path.join(home, ".agents", "skills", skillName, "SKILL.md");
+        case "openclaw":
+            return path.join(home, ".openclaw", "skills", `${skillName}.md`);
+        case "cursor":
+            return path.join(home, ".cursor", "rules", `${skillName}.mdc`);
+    }
+}
+/** Resolve a --to argument to a concrete file path for a skill.
+ *
+ * Rules:
+ *  - If `dest` ends in `.md` / `.mdc`, it's taken as the literal file path.
+ *  - Otherwise `dest` is treated as a skills *base* directory, and the skill
+ *    is written to `<dest>/<skill>/SKILL.md` (matches claude-code / codex layout).
+ */
+export function resolveExplicitDest(dest, skillName) {
+    const lower = dest.toLowerCase();
+    if (lower.endsWith(".md") || lower.endsWith(".mdc"))
+        return dest;
+    return path.join(dest, skillName, "SKILL.md");
+}
+function ensureParent(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+/** Write a skill's SKILL.md to `destPath`. Creates parent directories as needed. */
+export function writeSkillTo(skill, destPath) {
+    ensureParent(destPath);
+    fs.copyFileSync(skill.sourcePath, destPath);
+}
+/** Delete a skill file at `destPath`; prune the immediate parent dir if empty. */
+export function deleteSkillAt(destPath) {
+    if (!fs.existsSync(destPath))
+        return false;
+    fs.rmSync(destPath, { force: true });
+    const parent = path.dirname(destPath);
+    try {
+        if (fs.existsSync(parent) && fs.readdirSync(parent).length === 0) {
+            fs.rmdirSync(parent);
+        }
+    }
+    catch {
+        // non-empty or races — leave it
+    }
+    return true;
+}
+/** Snapshot of every (platform, skill) pair's install state on disk. */
+export function snapshotSkills() {
+    const bundled = listBundledSkills();
+    const rows = [];
+    for (const skill of bundled) {
+        for (const platform of SKILL_PLATFORMS) {
+            const destPath = skillDestPath(platform, skill.name);
+            const detected = fs.existsSync(skillDetectDir(platform));
+            const installed = fs.existsSync(destPath);
+            let version = null;
+            if (installed) {
+                const fm = readSkillFrontmatter(destPath);
+                version = fm.version ?? null;
+            }
+            rows.push({
+                name: skill.name,
+                platform,
+                detected,
+                installed,
+                path: destPath,
+                version,
+            });
+        }
+    }
+    return rows;
+}
+/**
+ * Record a skill's install/uninstall state in ~/.rafter/config.json under
+ * `skills.<platform>.<name>`. Writes the whole `skills` map in one shot to
+ * avoid splitting the skill name (which can contain hyphens but not dots) —
+ * unlike component IDs, there's no dot-key hazard here, but we keep one
+ * serialization path for consistency.
+ */
+export function recordSkillState(platform, name, enabled, version) {
+    const cm = new ConfigManager();
+    const existing = (cm.get("skillInstallations") ?? {});
+    existing[platform] ?? (existing[platform] = {});
+    existing[platform][name] = {
+        enabled,
+        version: version ?? undefined,
+        updatedAt: new Date().toISOString(),
+    };
+    cm.set("skillInstallations", existing);
+}

package/dist/commands/skill/remote.js

@@ -0,0 +1,333 @@
+// Remote source resolution and persistent cache for `rafter skill review`.
+//
+// Accepts three shorthands and a persistent cache, in addition to the local
+// path / raw git URL forms already handled by review.ts:
+//
+//   github:owner/repo[/subpath]
+//   gitlab:owner/repo[/subpath]
+//   npm:<pkg>[@<version>]
+//
+// Cache layout under ~/.rafter/skill-cache/:
+//
+//   resolutions/<sha256(shorthand)>.json   — {shorthand, sha|version, resolvedAt}
+//   content/<key>/                         — extracted working tree
+//     meta.json                            — {source, key, sha|version, fetchedAt}
+//
+// The resolution cache memoizes "what SHA is github:foo/bar@HEAD right now?"
+// The content cache memoizes "what does that SHA look like on disk?"
+// Both expire on --cache-ttl (default 24h).
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import zlib from "zlib";
+import { spawnSync } from "child_process";
+// tar@7 is dual CJS/ESM. We use its sync API (`tar.x({ sync, file, cwd, strip })`)
+// so the rest of the reviewer stays synchronous.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+import * as tarModule from "tar";
+export function isShorthand(input) {
+    return /^(github|gitlab|npm):/.test(input);
+}
+/**
+ * Parse a shorthand source spec. Throws on malformed input.
+ */
+export function parseShorthand(input) {
+    const m = input.match(/^(github|gitlab|npm):(.+)$/);
+    if (!m)
+        throw new Error(`Not a shorthand: ${input}`);
+    const kind = m[1];
+    const tail = m[2];
+    if (kind === "npm") {
+        // Forms: pkg | pkg@version | @scope/pkg | @scope/pkg@version
+        let pkg = tail;
+        let version = "latest";
+        if (tail.startsWith("@")) {
+            // Scoped: locate the second '@' (after the scope)
+            const secondAt = tail.indexOf("@", 1);
+            if (secondAt !== -1) {
+                pkg = tail.slice(0, secondAt);
+                version = tail.slice(secondAt + 1) || "latest";
+            }
+        }
+        else {
+            const at = tail.indexOf("@");
+            if (at !== -1) {
+                pkg = tail.slice(0, at);
+                version = tail.slice(at + 1) || "latest";
+            }
+        }
+        if (!pkg)
+            throw new Error(`Invalid npm shorthand: ${input}`);
+        return { kind, raw: input, pkg, version };
+    }
+    // git-based: owner/repo[/subpath]
+    const parts = tail.split("/").filter(Boolean);
+    if (parts.length < 2) {
+        throw new Error(`Invalid ${kind} shorthand: expected ${kind}:owner/repo[/subpath], got ${input}`);
+    }
+    const owner = parts[0];
+    const repo = parts[1];
+    const subpath = parts.slice(2).join("/");
+    const host = kind === "github" ? "github.com" : "gitlab.com";
+    const gitUrl = `https://${host}/${owner}/${repo}.git`;
+    return { kind, raw: input, host, owner, repo, subpath, gitUrl };
+}
+// ── Cache layout ───────────────────────────────────────────────────
+export const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+export function defaultCacheRoot() {
+    // Honor RAFTER_SKILL_CACHE_DIR for tests.
+    if (process.env.RAFTER_SKILL_CACHE_DIR) {
+        return process.env.RAFTER_SKILL_CACHE_DIR;
+    }
+    return path.join(os.homedir(), ".rafter", "skill-cache");
+}
+export function resolutionPath(cacheRoot, shorthand) {
+    const hash = crypto.createHash("sha256").update(shorthand).digest("hex").slice(0, 40);
+    return path.join(cacheRoot, "resolutions", `${hash}.json`);
+}
+export function contentDir(cacheRoot, key) {
+    return path.join(cacheRoot, "content", key);
+}
+function safeSlug(input) {
+    return input.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 80);
+}
+export function contentKeyGit(parsed, sha) {
+    const owner = safeSlug(parsed.owner ?? "unknown");
+    const repo = safeSlug(parsed.repo ?? "unknown");
+    return `git-${parsed.kind}-${owner}-${repo}-${sha.slice(0, 40)}`;
+}
+export function contentKeyNpm(pkg, version) {
+    return `npm-${safeSlug(pkg)}-${safeSlug(version)}`;
+}
+export function readResolution(cacheRoot, shorthand) {
+    const fpath = resolutionPath(cacheRoot, shorthand);
+    if (!fs.existsSync(fpath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(fpath, "utf-8"));
+        if (typeof raw !== "object" ||
+            raw === null ||
+            typeof raw.shorthand !== "string" ||
+            typeof raw.resolvedAt !== "number") {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeResolution(cacheRoot, res) {
+    const fpath = resolutionPath(cacheRoot, res.shorthand);
+    fs.mkdirSync(path.dirname(fpath), { recursive: true });
+    fs.writeFileSync(fpath, JSON.stringify(res, null, 2));
+}
+export function resolutionIsFresh(r, ttlMs) {
+    return Date.now() - r.resolvedAt < ttlMs;
+}
+export function readContentMeta(cacheRoot, key) {
+    const dir = contentDir(cacheRoot, key);
+    const meta = path.join(dir, "meta.json");
+    if (!fs.existsSync(meta))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(meta, "utf-8"));
+        if (typeof raw !== "object" ||
+            raw === null ||
+            typeof raw.source !== "string" ||
+            typeof raw.key !== "string" ||
+            typeof raw.fetchedAt !== "number") {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function contentWorkingTree(cacheRoot, key) {
+    return path.join(contentDir(cacheRoot, key), "content");
+}
+export function contentIsUsable(cacheRoot, key) {
+    const meta = readContentMeta(cacheRoot, key);
+    if (!meta)
+        return false;
+    const tree = contentWorkingTree(cacheRoot, key);
+    if (!fs.existsSync(tree))
+        return false;
+    try {
+        const entries = fs.readdirSync(tree);
+        // Empty directory counts as corrupt — a real clone/extract leaves something.
+        if (entries.length === 0)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+export function dropCacheEntry(cacheRoot, key) {
+    const dir = contentDir(cacheRoot, key);
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // ignore
+    }
+}
+export const defaultRemoteOps = {
+    gitLsRemoteHead(url) {
+        const r = spawnSync("git", ["ls-remote", url, "HEAD"], {
+            encoding: "utf-8",
+            timeout: 30000,
+        });
+        if (r.status !== 0) {
+            const err = (r.stderr ?? "").toString().trim() || "git ls-remote failed";
+            throw new Error(`ls-remote ${url}: ${err}`);
+        }
+        const line = (r.stdout ?? "").split("\n")[0] ?? "";
+        const sha = line.split(/\s+/)[0];
+        if (!/^[0-9a-f]{40}$/i.test(sha)) {
+            throw new Error(`ls-remote ${url}: could not parse SHA from "${line}"`);
+        }
+        return sha.toLowerCase();
+    },
+    gitCloneAtSha(url, sha, destDir) {
+        // Shallow clone then checkout the pinned SHA. We do a --depth 1 of default
+        // branch first (fastest common case) and only fall back to a full fetch if
+        // the target SHA isn't HEAD.
+        fs.mkdirSync(destDir, { recursive: true });
+        const r = spawnSync("git", ["clone", "--depth", "1", "--quiet", url, destDir], { encoding: "utf-8", timeout: 120000 });
+        if (r.status !== 0) {
+            const err = (r.stderr ?? "").toString().trim() || "git clone failed";
+            throw new Error(`clone ${url}: ${err}`);
+        }
+        // Best-effort: check that the resulting HEAD matches the expected SHA.
+        // If not, fetch that specific SHA explicitly.
+        const headR = spawnSync("git", ["rev-parse", "HEAD"], {
+            cwd: destDir,
+            encoding: "utf-8",
+        });
+        const head = (headR.stdout ?? "").trim().toLowerCase();
+        if (head !== sha) {
+            const fetchR = spawnSync("git", ["fetch", "--depth", "1", "origin", sha], { cwd: destDir, encoding: "utf-8", timeout: 120000 });
+            if (fetchR.status === 0) {
+                spawnSync("git", ["checkout", "--quiet", sha], {
+                    cwd: destDir,
+                    encoding: "utf-8",
+                });
+            }
+            // If the fetch failed we keep whatever HEAD we have — audit still works,
+            // we just mismatched the resolved SHA. Record that in meta.
+        }
+    },
+    npmFetchMetadata(pkg) {
+        const encoded = pkg.startsWith("@")
+            ? `@${encodeURIComponent(pkg.slice(1))}`
+            : encodeURIComponent(pkg);
+        const url = `https://registry.npmjs.org/${encoded}`;
+        return syncHttpJson(url);
+    },
+    npmFetchTarball(tarballUrl, destFile) {
+        fs.mkdirSync(path.dirname(destFile), { recursive: true });
+        // Spawn a short-lived node subprocess that awaits fetch() and streams the
+        // tarball to destFile. Keeps the caller synchronous.
+        const script = `
+      (async () => {
+        const fs = require('fs');
+        const r = await fetch(${JSON.stringify(tarballUrl)});
+        if (!r.ok) { process.stderr.write('HTTP ' + r.status); process.exit(2); }
+        const buf = Buffer.from(await r.arrayBuffer());
+        fs.writeFileSync(${JSON.stringify(destFile)}, buf);
+      })().catch((e) => { process.stderr.write(String(e?.message || e)); process.exit(1); });
+    `;
+        const r = spawnSync(process.execPath, ["-e", script], {
+            encoding: "utf-8",
+            timeout: 120000,
+        });
+        if (r.status !== 0) {
+            throw new Error(`fetch ${tarballUrl}: ${(r.stderr ?? "").toString().trim() || "failed"}`);
+        }
+    },
+};
+// Tiny blocking HTTP-GET-JSON helper. npm registry endpoints are small,
+// latency-insensitive, and called at most once per audit — we do this inline
+// rather than bolting an async path through the whole reviewer.
+function syncHttpJson(url) {
+    // Node 18+ has global fetch, but it's async. For synchronous behavior we
+    // spawn a short-lived node subprocess. This keeps review.ts synchronous.
+    const script = `
+    (async () => {
+      const r = await fetch(${JSON.stringify(url)});
+      if (!r.ok) { process.stderr.write("HTTP " + r.status); process.exit(2); }
+      const txt = await r.text();
+      process.stdout.write(txt);
+    })().catch((e) => { process.stderr.write(String(e?.message || e)); process.exit(1); });
+  `;
+    const r = spawnSync(process.execPath, ["-e", script], {
+        encoding: "utf-8",
+        timeout: 30000,
+    });
+    if (r.status !== 0) {
+        throw new Error(`GET ${url}: ${(r.stderr ?? "").toString().trim() || "failed"}`);
+    }
+    try {
+        return JSON.parse(r.stdout ?? "");
+    }
+    catch (e) {
+        throw new Error(`GET ${url}: invalid JSON (${e.message})`);
+    }
+}
+// ── Extraction helpers ─────────────────────────────────────────────
+export function extractNpmTarball(tgzFile, destDir) {
+    fs.mkdirSync(destDir, { recursive: true });
+    // npm tarballs have a leading "package/" directory; strip it.
+    // tar@7 exposes a sync option that writes everything before returning.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tarModule.x({ sync: true, file: tgzFile, cwd: destDir, strip: 1 });
+}
+/** Gunzip a .tgz file synchronously to a .tar, for fixture generation in tests. */
+export function gunzipFile(src, dest) {
+    const zipped = fs.readFileSync(src);
+    fs.writeFileSync(dest, zlib.gunzipSync(zipped));
+}
+const SKILL_WALK_SKIP = new Set([".git", "node_modules", ".venv", "__pycache__"]);
+const SKILL_WALK_MAX_FILES = 5000;
+/** Depth-first walk looking for every SKILL.md file. Deterministic order. */
+export function findSkillFiles(root) {
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory())
+        return [];
+    const out = [];
+    const stack = [root];
+    let visited = 0;
+    while (stack.length && visited < SKILL_WALK_MAX_FILES) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        // Sort for determinism (stack order reverses; pre-sort so pops ordered).
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of [...entries].reverse()) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKILL_WALK_SKIP.has(entry.name))
+                    continue;
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                visited += 1;
+                if (entry.name.toLowerCase() === "skill.md") {
+                    const rel = path.relative(root, dir) || ".";
+                    out.push({ file: full, dir, relDir: rel });
+                }
+            }
+        }
+    }
+    out.sort((a, b) => a.relDir.localeCompare(b.relDir));
+    return out;
+}