@rafter-security/cli 0.7.0 → 0.7.2

package/dist/commands/agent/list.js

@@ -0,0 +1,72 @@
+import { Command } from "commander";
+import { snapshotComponents } from "./components.js";
+import { fmt } from "../../utils/formatter.js";
+/**
+ * `rafter agent list` — machine-readable inventory of everything rafter has touched
+ * (or could touch) on this machine. One row per (platform, component).
+ *
+ * Exit codes: 0 on success.
+ */
+export function createListCommand() {
+    return new Command("list")
+        .description("List agent integration components and their state")
+        .option("--json", "Output machine-readable JSON")
+        .option("--installed", "Only show components that are currently installed")
+        .option("--detected", "Only show components whose platform is detected")
+        .action((opts) => {
+        let rows = snapshotComponents();
+        if (opts.installed)
+            rows = rows.filter((r) => r.installed);
+        if (opts.detected)
+            rows = rows.filter((r) => r.detected);
+        if (opts.json) {
+            const payload = {
+                components: rows.map((r) => ({
+                    id: r.id,
+                    platform: r.platform,
+                    kind: r.kind,
+                    description: r.description,
+                    path: r.path,
+                    state: r.state,
+                    installed: r.installed,
+                    detected: r.detected,
+                    configEnabled: r.configEnabled,
+                })),
+            };
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        const byPlatform = new Map();
+        for (const r of rows) {
+            const arr = byPlatform.get(r.platform) ?? [];
+            arr.push(r);
+            byPlatform.set(r.platform, arr);
+        }
+        console.log(fmt.header("Rafter agent components"));
+        console.log(fmt.divider());
+        for (const [platform, list] of byPlatform) {
+            const detected = list[0]?.detected ?? false;
+            const suffix = detected ? "" : " (not detected)";
+            console.log(`\n${platform}${suffix}`);
+            for (const r of list) {
+                const label = r.id.padEnd(28);
+                let marker;
+                switch (r.state) {
+                    case "installed":
+                        marker = "● installed";
+                        break;
+                    case "not-installed":
+                        marker = "○ not installed";
+                        break;
+                    case "not-detected":
+                    default:
+                        marker = "· platform not detected";
+                        break;
+                }
+                console.log(`  ${label} ${marker}`);
+            }
+        }
+        console.log();
+        console.log(fmt.info("Use `rafter agent enable <id>` or `rafter agent disable <id>` to toggle individual components."));
+    });
+}

package/dist/commands/brief.js

@@ -9,6 +9,16 @@ function loadSkill(name) {
     // Strip YAML frontmatter
     return raw.replace(/^---[\s\S]*?---\n*/, "").trim();
 }
+function loadSkillDoc(skill, doc) {
+    return readFileSync(join(RESOURCES_DIR, skill, "docs", `${doc}.md`), "utf-8").trim();
+}
+const RAFTER_SUBDOCS = [
+    { slug: "cli-reference", desc: "Full rafter CLI tree by category" },
+    { slug: "guardrails", desc: "PreToolUse hooks, risk tiers, overrides" },
+    { slug: "backend", desc: "Remote fast vs plus, setup, cost/latency" },
+    { slug: "shift-left", desc: "Pointers to secure-design & code-review skills" },
+    { slug: "finding-triage", desc: "How to read a finding and decide next steps" },
+];
 function extractSections(content, headings) {
     const lines = content.split("\n");
     const sections = [];
@@ -165,6 +175,13 @@ function buildTopics() {
                 "the tools developers use every day.",
             ].join("\n"),
         },
+        ...Object.fromEntries(RAFTER_SUBDOCS.map(({ slug, desc }) => [
+            slug,
+            {
+                description: desc,
+                render: () => loadSkillDoc("rafter", slug),
+            },
+        ])),
         all: {
             description: "Everything — full security + scanning + setup briefing",
             render: () => {
@@ -503,6 +520,9 @@ function renderTopicList(topics) {
     lines.push("  rafter brief commands          # full command reference");
     lines.push("  rafter brief setup/claude-code # Claude Code setup guide");
     lines.push("  rafter brief setup/generic     # setup for any agent");
+    lines.push("  rafter brief cli-reference     # full CLI tree");
+    lines.push("  rafter brief guardrails        # hooks + risk tiers");
+    lines.push("  rafter brief finding-triage    # interpret findings");
     lines.push("  rafter brief all               # everything");
     return lines.join("\n");
 }

package/dist/commands/docs/index.js

@@ -0,0 +1,18 @@
+import { Command } from "commander";
+import { createDocsListCommand } from "./list.js";
+import { createDocsShowCommand } from "./show.js";
+export function createDocsCommand() {
+    const docs = new Command("docs")
+        .description("Repo-specific security docs declared in .rafter.yml")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  $ rafter docs list",
+        "  $ rafter docs list --tag owasp",
+        "  $ rafter docs show secure-coding",
+        "  $ rafter docs show secure-coding --refresh",
+    ].join("\n"));
+    docs.addCommand(createDocsListCommand());
+    docs.addCommand(createDocsShowCommand());
+    return docs;
+}

package/dist/commands/docs/list.js

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import { listDocs } from "../../core/docs-loader.js";
+export function createDocsListCommand() {
+    return new Command("list")
+        .description("List security docs declared in .rafter.yml")
+        .option("--tag <tag>", "Filter to docs matching this tag")
+        .option("--json", "Output as JSON")
+        .action((opts) => {
+        const entries = listDocs().filter(d => !opts.tag || (Array.isArray(d.tags) && d.tags.includes(opts.tag)));
+        if (entries.length === 0) {
+            if (opts.json) {
+                process.stdout.write("[]\n");
+            }
+            else {
+                process.stderr.write("No docs configured in .rafter.yml\n");
+            }
+            process.exit(3);
+        }
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(entries.map(e => ({
+                id: e.id,
+                source: e.source,
+                source_kind: e.sourceKind,
+                description: e.description || "",
+                tags: e.tags || [],
+                cache_status: e.cacheStatus,
+            })), null, 2) + "\n");
+            return;
+        }
+        for (const e of entries) {
+            const tags = (e.tags && e.tags.length) ? ` [${e.tags.join(", ")}]` : "";
+            const cache = e.sourceKind === "url" ? ` (${e.cacheStatus})` : "";
+            const desc = e.description ? ` — ${e.description}` : "";
+            process.stdout.write(`${e.id}  ${e.source}${cache}${tags}${desc}\n`);
+        }
+    });
+}

package/dist/commands/docs/show.js

@@ -0,0 +1,64 @@
+import { Command } from "commander";
+import { resolveDocSelector, fetchDoc } from "../../core/docs-loader.js";
+export function createDocsShowCommand() {
+    return new Command("show")
+        .description("Print the content of a doc by id or tag")
+        .argument("<id-or-tag>", "Doc id or tag selector")
+        .option("--refresh", "Force re-fetch for URL-backed docs (bypass cache)")
+        .option("--json", "Output as JSON (array of { id, source, content })")
+        .action(async (selector, opts) => {
+        const entries = resolveDocSelector(selector);
+        if (entries.length === 0) {
+            const { loadPolicy } = await import("../../core/policy-loader.js");
+            const policy = loadPolicy();
+            if (!policy || !policy.docs || policy.docs.length === 0) {
+                process.stderr.write("No docs configured in .rafter.yml\n");
+                process.exit(3);
+            }
+            process.stderr.write(`No doc matched id or tag: ${selector}\n`);
+            process.exit(2);
+        }
+        const results = [];
+        let anyError = false;
+        for (const entry of entries) {
+            try {
+                const fetched = await fetchDoc(entry, { refresh: opts.refresh });
+                results.push({
+                    id: entry.id,
+                    source: fetched.source,
+                    source_kind: fetched.sourceKind,
+                    stale: fetched.stale,
+                    content: fetched.content,
+                });
+                if (fetched.stale) {
+                    process.stderr.write(`Warning: ${entry.id} served from stale cache (fetch failed)\n`);
+                }
+            }
+            catch (err) {
+                anyError = true;
+                process.stderr.write(`Error: failed to fetch ${entry.id}: ${err.message || err}\n`);
+            }
+        }
+        if (results.length === 0) {
+            process.exit(1);
+        }
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+        }
+        else if (results.length === 1) {
+            process.stdout.write(results[0].content);
+            if (!results[0].content.endsWith("\n"))
+                process.stdout.write("\n");
+        }
+        else {
+            for (const r of results) {
+                process.stdout.write(`\n===== ${r.id} (${r.source}) =====\n`);
+                process.stdout.write(r.content);
+                if (!r.content.endsWith("\n"))
+                    process.stdout.write("\n");
+            }
+        }
+        if (anyError)
+            process.exit(1);
+    });
+}

package/dist/commands/mcp/server.js

@@ -7,6 +7,7 @@ import { GitleaksScanner } from "../../scanners/gitleaks.js";
 import { CommandInterceptor } from "../../core/command-interceptor.js";
 import { AuditLogger } from "../../core/audit-logger.js";
 import { ConfigManager } from "../../core/config-manager.js";
+import { listDocs, resolveDocSelector, fetchDoc } from "../../core/docs-loader.js";
 import { createRequire } from "module";
 const _require = createRequire(import.meta.url);
 const { version: CLI_VERSION } = _require("../../../package.json");
@@ -87,6 +88,28 @@ export function createServer() {
                     },
                 },
             },
+            {
+                name: "list_docs",
+                description: "List repo-specific security docs declared in .rafter.yml. Call this early in any security-relevant task to discover project-specific rules, threat models, or compliance policies the user expects agents to follow.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        tag: { type: "string", description: "Filter to docs whose tags include this value" },
+                    },
+                },
+            },
+            {
+                name: "get_doc",
+                description: "Return the content of a repo-specific security doc by id or tag. Use after list_docs to read a specific document.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id_or_tag: { type: "string", description: "Doc id or tag selector" },
+                        refresh: { type: "boolean", description: "Force re-fetch for URL-backed docs (bypass cache)" },
+                    },
+                    required: ["id_or_tag"],
+                },
+            },
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -149,6 +172,44 @@ export function createServer() {
                 const value = key ? manager.get(key) : manager.load();
                 return textResult(value);
             }
+            case "list_docs": {
+                const tag = args?.tag;
+                const entries = listDocs().filter(d => !tag || (Array.isArray(d.tags) && d.tags.includes(tag)));
+                return textResult(entries.map(e => ({
+                    id: e.id,
+                    source: e.source,
+                    source_kind: e.sourceKind,
+                    description: e.description || "",
+                    tags: e.tags || [],
+                    cache_status: e.cacheStatus,
+                })));
+            }
+            case "get_doc": {
+                const selector = args?.id_or_tag;
+                if (!selector)
+                    return errorResult("id_or_tag is required");
+                const matches = resolveDocSelector(selector);
+                if (matches.length === 0)
+                    return errorResult(`No doc matched id or tag: ${selector}`);
+                const refresh = Boolean(args?.refresh);
+                const results = [];
+                for (const entry of matches) {
+                    try {
+                        const fetched = await fetchDoc(entry, { refresh });
+                        results.push({
+                            id: entry.id,
+                            source: fetched.source,
+                            source_kind: fetched.sourceKind,
+                            stale: fetched.stale,
+                            content: fetched.content,
+                        });
+                    }
+                    catch (err) {
+                        return errorResult(`Failed to fetch ${entry.id}: ${err.message || err}`);
+                    }
+                }
+                return textResult(results);
+            }
             default:
                 return errorResult(`Unknown tool: ${name}`);
         }
@@ -168,6 +229,12 @@ export function createServer() {
                 description: "Active security policy (merged .rafter.yml + config)",
                 mimeType: "application/json",
             },
+            {
+                uri: "rafter://docs",
+                name: "Rafter Docs",
+                description: "Repo-specific security docs declared in .rafter.yml (metadata only, no content)",
+                mimeType: "application/json",
+            },
         ],
     }));
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
@@ -190,6 +257,23 @@ export function createServer() {
                             text: JSON.stringify(manager.loadWithPolicy(), null, 2),
                         }],
                 };
+            case "rafter://docs": {
+                const entries = listDocs().map(e => ({
+                    id: e.id,
+                    source: e.source,
+                    source_kind: e.sourceKind,
+                    description: e.description || "",
+                    tags: e.tags || [],
+                    cache_status: e.cacheStatus,
+                }));
+                return {
+                    contents: [{
+                            uri: "rafter://docs",
+                            mimeType: "application/json",
+                            text: JSON.stringify(entries, null, 2),
+                        }],
+                };
+            }
             default:
                 throw new Error(`Unknown resource: ${uri}`);
         }

package/dist/commands/skill/index.js

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+import { createListCommand } from "./list.js";
+import { createInstallCommand } from "./install.js";
+import { createUninstallCommand } from "./uninstall.js";
+import { createReviewCommand } from "./review.js";
+export function createSkillCommand() {
+    const skill = new Command("skill")
+        .description("Manage rafter-authored skills (list / install / uninstall / review)");
+    skill.addCommand(createListCommand());
+    skill.addCommand(createInstallCommand());
+    skill.addCommand(createUninstallCommand());
+    skill.addCommand(createReviewCommand());
+    return skill;
+}

package/dist/commands/skill/install.js

@@ -0,0 +1,89 @@
+import { Command } from "commander";
+import fs from "fs";
+import { resolveSkill, listBundledSkills, skillDestPath, skillDetectDir, resolveExplicitDest, writeSkillTo, recordSkillState, SKILL_PLATFORMS, } from "./registry.js";
+import { fmt } from "../../utils/formatter.js";
+/**
+ * `rafter skill install <name>` — install a rafter-authored skill to one or
+ * more platforms (or an explicit --to path).
+ *
+ * Exit codes:
+ *   0 — installed successfully (or already installed — copy is idempotent)
+ *   1 — unknown skill, unknown platform, or install failure
+ *   2 — no detected platform found and --force was not passed
+ */
+export function createInstallCommand() {
+    return new Command("install")
+        .description("Install a rafter-authored skill to detected platform(s) or an explicit path")
+        .argument("<name>", "Skill name (e.g. rafter, rafter-secure-design)")
+        .option("--platform <platform...>", `Target platform(s). One or more of: ${SKILL_PLATFORMS.join(", ")}. Default: all detected.`)
+        .option("--to <path>", "Explicit destination. If it ends in .md/.mdc, used as-is; otherwise treated as a skills-base directory.")
+        .option("--force", "Install even if no target platform is detected")
+        .action((name, opts) => {
+        const skill = resolveSkill(name);
+        if (!skill) {
+            console.error(fmt.error(`Unknown skill: ${name}`));
+            console.error(fmt.info(`Available: ${listBundledSkills().map((s) => s.name).join(", ") || "(none)"}`));
+            process.exit(1);
+        }
+        // --to overrides platform-based resolution.
+        if (opts.to) {
+            const destPath = resolveExplicitDest(opts.to, skill.name);
+            try {
+                writeSkillTo(skill, destPath);
+                console.log(fmt.success(`Installed ${skill.name} v${skill.version} → ${destPath}`));
+                process.exit(0);
+            }
+            catch (e) {
+                console.error(fmt.error(`Failed to install ${skill.name} to ${destPath}: ${e}`));
+                process.exit(1);
+            }
+        }
+        // Resolve target platforms: either explicit --platform list, or "all detected".
+        let targets;
+        if (Array.isArray(opts.platform) && opts.platform.length > 0) {
+            targets = [];
+            for (const raw of opts.platform) {
+                const p = raw.trim();
+                if (!SKILL_PLATFORMS.includes(p)) {
+                    console.error(fmt.error(`Unknown platform: ${raw}. Known: ${SKILL_PLATFORMS.join(", ")}`));
+                    process.exit(1);
+                }
+                targets.push(p);
+            }
+        }
+        else {
+            targets = SKILL_PLATFORMS.filter((p) => fs.existsSync(skillDetectDir(p)));
+            if (targets.length === 0) {
+                if (!opts.force) {
+                    console.error(fmt.warning(`No supported platform detected. Re-run with --platform <name> or --force to install to all known platforms.`));
+                    process.exit(2);
+                }
+                targets = [...SKILL_PLATFORMS];
+            }
+        }
+        let exitCode = 0;
+        for (const platform of targets) {
+            const detected = fs.existsSync(skillDetectDir(platform));
+            if (!detected && !opts.force && !(Array.isArray(opts.platform) && opts.platform.length > 0)) {
+                // Shouldn't hit this — we pre-filtered to detected — but defensive.
+                continue;
+            }
+            if (!detected && !opts.force && Array.isArray(opts.platform) && opts.platform.length > 0) {
+                console.error(fmt.warning(`${platform}: not detected (${skillDetectDir(platform)}). Re-run with --force to install anyway.`));
+                exitCode = exitCode || 2;
+                continue;
+            }
+            const destPath = skillDestPath(platform, skill.name);
+            try {
+                writeSkillTo(skill, destPath);
+                recordSkillState(platform, skill.name, true, skill.version);
+                console.log(fmt.success(`Installed ${skill.name} v${skill.version} → ${destPath} (${platform})`));
+            }
+            catch (e) {
+                console.error(fmt.error(`Failed to install ${skill.name} for ${platform}: ${e}`));
+                exitCode = 1;
+            }
+        }
+        process.exit(exitCode);
+    });
+}

package/dist/commands/skill/list.js

@@ -0,0 +1,79 @@
+import { Command } from "commander";
+import { listBundledSkills, snapshotSkills, SKILL_PLATFORMS, } from "./registry.js";
+import { fmt } from "../../utils/formatter.js";
+/**
+ * `rafter skill list` — show rafter-authored skills available in this CLI and
+ * whether each is installed for each supported platform (claude-code, codex,
+ * openclaw, cursor).
+ *
+ * Exit code: 0 on success.
+ */
+export function createListCommand() {
+    return new Command("list")
+        .description("List rafter-authored skills and their install state per platform")
+        .option("--json", "Output machine-readable JSON")
+        .option("--installed", "Only show (skill, platform) pairs where the skill is installed")
+        .option("--platform <platform>", "Limit to one platform")
+        .action((opts) => {
+        const bundled = listBundledSkills();
+        let rows = snapshotSkills();
+        const platformFilter = opts.platform;
+        if (platformFilter) {
+            if (!SKILL_PLATFORMS.includes(platformFilter)) {
+                console.error(fmt.error(`Unknown platform: ${platformFilter}. Known: ${SKILL_PLATFORMS.join(", ")}`));
+                process.exit(1);
+            }
+            rows = rows.filter((r) => r.platform === platformFilter);
+        }
+        if (opts.installed)
+            rows = rows.filter((r) => r.installed);
+        if (opts.json) {
+            const payload = {
+                skills: bundled.map((s) => ({
+                    name: s.name,
+                    version: s.version,
+                    description: s.description,
+                })),
+                installations: rows.map((r) => ({
+                    name: r.name,
+                    platform: r.platform,
+                    path: r.path,
+                    detected: r.detected,
+                    installed: r.installed,
+                    version: r.version,
+                })),
+            };
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        console.log(fmt.header("Rafter-authored skills"));
+        for (const s of bundled) {
+            console.log(`  ${s.name.padEnd(24)} v${s.version}`);
+        }
+        console.log();
+        console.log(fmt.header("Installations by platform"));
+        const byPlatform = new Map();
+        for (const r of rows) {
+            const arr = byPlatform.get(r.platform) ?? [];
+            arr.push(r);
+            byPlatform.set(r.platform, arr);
+        }
+        for (const [platform, list] of byPlatform) {
+            const detected = list[0]?.detected ?? false;
+            const suffix = detected ? "" : " (not detected)";
+            console.log(`\n${platform}${suffix}`);
+            for (const r of list) {
+                const label = r.name.padEnd(24);
+                if (r.installed) {
+                    const ver = r.version ? ` v${r.version}` : "";
+                    console.log(`  ${label} ● installed${ver}  (${r.path})`);
+                }
+                else {
+                    console.log(`  ${label} ○ not installed`);
+                }
+            }
+        }
+        console.log();
+        console.log(fmt.info("Use `rafter skill install <name>` / `rafter skill uninstall <name>` to toggle skills."));
+    });
+}