@rafter-security/cli 0.6.5 → 0.6.6

package/README.md

@@ -1,10 +1,10 @@
 # @rafter-security/cli
 
-Node.js CLI for [Rafter](https://rafter.so) — zero-setup security for AI builders. This is the **full-featured package** with both backend scanning and agent security.
+Node.js CLI for [Rafter](https://rafter.so) — the security toolkit for developers. This is the **full-featured package** with both local security and remote code analysis.
 
-**Backend scanning** — Remote SAST/SCA via Rafter API. Trigger scans, retrieve structured vulnerability reports, pipe to any tool.
+**Local security toolkit** — Fast, deterministic secret scanning (21+ patterns, Gitleaks), policy enforcement with risk-tiered rules, pre-commit hooks, extension auditing, custom rule authoring, and full audit logging. Works with Claude Code, Codex CLI, OpenClaw, and 5 more platforms. No API key required. No data leaves your machine.
 
-**Agent security** — Local-first protection for autonomous AI agents. Secret scanning (21+ patterns, Gitleaks), command interception with risk-tiered approval, pre-commit hooks, skill/extension auditing, and full audit logging. Works with Claude Code, Codex CLI, and OpenClaw. No API key required.
+**Remote code analysis** — Deep security audits that combine agentic analysis with a full SAST/SCA toolchain. The engine examines your codebase the way a professional cybersecurity auditor would — tracing data flows, reasoning about business logic, and surfacing vulnerabilities that static rules alone miss — then cross-references findings with industry-standard static analysis and dependency scanning. Structured JSON reports with documented exit codes. Your code is deleted immediately after analysis completes.
 
 ## Installation
 
@@ -23,7 +23,7 @@ yarn global add @rafter-security/cli
 
 ### Getting an API Key
 
-To use backend scanning features, you'll need a Rafter API key:
+To use backend code analysis features, you'll need a Rafter API key:
 
 1. **Sign up**: Create an account at [rafter.so](https://rafter.so)
 2. **Get API key**: Navigate to Dashboard → Settings → API Keys
@@ -36,9 +36,9 @@ To use backend scanning features, you'll need a Rafter API key:
    echo "RAFTER_API_KEY=your-api-key-here" >> .env
    ```
 
-**Note**: Agent security features (secret scanning, command execution) work **without an API key**. Only backend scanning requires authentication.
+**Note**: Agent security features (secret scanning, command execution) work **without an API key**. Only backend code analysis requires authentication.
 
-### Backend Scanning
+### Backend Code Analysis
 
 ```bash
 # Set your API key (from above)
@@ -54,10 +54,10 @@ rafter get <scan-id>
 rafter usage
 ```
 
-### Agent Security
+### Local Security
 
 ```bash
-# Initialize agent security
+# Initialize local security
 rafter agent init
 
 # Scan files for secrets
@@ -77,7 +77,7 @@ rafter agent config show
 
 | Flag | Description |
 |------|-------------|
-| `-a, --agent` | Plain output for AI agents (no colors, no emoji) |
+| `-a, --agent` | Plain output (no colors, no emoji) |
 | `-V, --version` | Print version |
 | `-h, --help` | Show help |
 
@@ -92,7 +92,7 @@ Trigger a new security scan for your repository.
 - `-r, --repo <repo>` - Repository in format `org/repo` (default: auto-detected)
 - `-b, --branch <branch>` - Branch name (default: auto-detected)
 - `-k, --api-key <key>` - API key (or set `RAFTER_API_KEY` env var)
-- `-f, --format <format>` - Output format: `json` or `md` (default: `json`)
+- `-f, --format <format>` - Output format: `json` or `md` (default: `md`)
 - `--skip-interactive` - Don't wait for scan completion
 - `--quiet` - Suppress status messages
 
@@ -116,7 +116,7 @@ Retrieve results from a completed scan.
 
 **Options:**
 - `-k, --api-key <key>` - API key (or set `RAFTER_API_KEY` env var)
-- `-f, --format <format>` - Output format: `json` or `md` (default: `json`)
+- `-f, --format <format>` - Output format: `json` or `md` (default: `md`)
 - `--interactive` - Poll until scan completes
 - `--quiet` - Suppress status messages
 
@@ -143,13 +143,13 @@ rafter usage
 
 ---
 
-## Agent Security Commands
+## Local Security Commands
 
-Rafter provides local security features for autonomous agents (OpenClaw, Claude Code) to prevent secrets leakage and dangerous operations.
+Rafter is a **security primitive** that any developer or tool can call and trust. Stable exit codes, deterministic findings, and structured output mean any workflow can integrate Rafter without reading prose.
 
 ### `rafter agent init [options]`
 
-Initialize agent security system.
+Initialize local security system.
 
 **Options:**
 - `--risk-level <level>` - Set risk level: `minimal`, `moderate`, or `aggressive` (default: `moderate`)
@@ -167,7 +167,7 @@ Initialize agent security system.
 **What it does:**
 - Creates `~/.rafter/config.json` configuration
 - Initializes directory structure
-- Detects available agent environments
+- Detects installed platforms
 - Installs opted-in integrations (skills, hooks, MCP servers)
 - Sets up audit logging
 
@@ -562,9 +562,9 @@ The CLI automatically detects your repository and branch from the current Git re
 
 **Note**: The CLI only scans remote repositories, not your current local branch.
 
-### Agent Security Configuration
+### Local Security Configuration
 
-Agent security settings are stored in `~/.rafter/config.json`. Key settings:
+Security settings are stored in `~/.rafter/config.json`. Key settings:
 
 **Risk Levels:**
 - `minimal` - Basic guidance only, most commands allowed
@@ -584,7 +584,7 @@ Agent security settings are stored in `~/.rafter/config.json`. Key settings:
 
 ## OpenClaw Integration
 
-Rafter integrates seamlessly with [OpenClaw](https://openclaw.com) autonomous agents.
+Rafter integrates seamlessly with [OpenClaw](https://openclaw.com).
 
 ### Setup
 
@@ -624,7 +624,7 @@ When OpenClaw is detected, `rafter agent init` automatically installs a skill to
 
 Rafter provides TWO skills for Claude Code:
 
-### 1. Backend Scanning Skill (Core Feature)
+### 1. Backend Code Analysis Skill (Core Feature)
 
 **Automatic Integration** - Claude can proactively suggest security scans
 
@@ -650,7 +650,7 @@ Claude will automatically suggest Rafter scans when you mention security, vulner
 Can you run a Rafter security scan on this repo?
 ```
 
-### 2. Agent Security Skill
+### 2. Local Security Skill
 
 **User-Invoked** - Requires explicit commands for safety
 
@@ -680,10 +680,10 @@ Explicitly invoke commands:
 
 ### Why Two Skills?
 
-- **Backend skill** - Safe for Claude to auto-invoke (read-only API calls)
+- **Backend code analysis skill** - Safe for Claude to auto-invoke (read-only API calls)
 - **Agent security skill** - Requires user permission (local file access, command execution)
 
-This separation emphasizes Rafter's core backend scanning capabilities while keeping local security features safely behind user control.
+This separation emphasizes Rafter's core backend code analysis capabilities while keeping local security features safely behind user control.
 
 ## Documentation
 

package/dist/commands/agent/index.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { createAuditCommand } from "./audit.js";
 import { createScanCommand } from "./scan.js";
 import { createInitCommand } from "./init.js";
+import { createInitProjectCommand } from "./init-project.js";
 import { createConfigCommand } from "./config.js";
 import { createExecCommand } from "./exec.js";
 import { createAuditSkillCommand } from "./audit-skill.js";
@@ -15,6 +16,7 @@ export function createAgentCommand() {
         .description("Agent security features");
     // Add subcommands
     agent.addCommand(createInitCommand());
+    agent.addCommand(createInitProjectCommand());
     agent.addCommand(createScanCommand());
     agent.addCommand(createExecCommand());
     agent.addCommand(createConfigCommand());

package/dist/commands/agent/init-project.js

@@ -0,0 +1,164 @@
+import { Command } from "commander";
+import { injectInstructionFile } from "./instruction-block.js";
+import { fmt } from "../../utils/formatter.js";
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+/** Find the git root directory, or null if not in a git repo */
+function findGitRoot() {
+    try {
+        return execSync("git rev-parse --show-toplevel", {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * All project-level instruction file targets.
+ *
+ * These are files that AI agents read at session start when working in a project.
+ * Unlike global files (~/.claude/CLAUDE.md), these live in the repo and are
+ * committed alongside the code so every agent session sees them.
+ */
+function getProjectTargets(projectRoot) {
+    return [
+        {
+            platform: "Claude Code",
+            filePath: path.join(projectRoot, ".claude", "CLAUDE.md"),
+            description: "Claude Code project instructions",
+        },
+        {
+            platform: "Codex CLI",
+            filePath: path.join(projectRoot, "AGENTS.md"),
+            description: "Codex CLI project instructions",
+        },
+        {
+            platform: "Gemini CLI",
+            filePath: path.join(projectRoot, "GEMINI.md"),
+            description: "Gemini CLI project instructions",
+        },
+        {
+            platform: "Cursor",
+            filePath: path.join(projectRoot, ".cursor", "rules", "rafter-security.mdc"),
+            description: "Cursor project rules",
+        },
+        {
+            platform: "Windsurf",
+            filePath: path.join(projectRoot, ".windsurfrules"),
+            description: "Windsurf project rules",
+        },
+        {
+            platform: "Continue.dev",
+            filePath: path.join(projectRoot, ".continuerules"),
+            description: "Continue.dev project rules",
+        },
+        {
+            platform: "Aider",
+            filePath: path.join(projectRoot, ".aider", "conventions.md"),
+            description: "Aider project conventions",
+        },
+    ];
+}
+export function createInitProjectCommand() {
+    return new Command("init-project")
+        .description("Generate project-level instruction files so AI agents discover Rafter at session start")
+        .option("--only <platforms>", "Comma-separated list of platforms (claude-code,codex,gemini,cursor,windsurf,continue,aider)")
+        .option("--list", "List which files would be created without writing them")
+        .action(async (opts) => {
+        const gitRoot = findGitRoot();
+        if (!gitRoot) {
+            console.error(fmt.error("Not in a git repository. Run this command from inside a project."));
+            process.exit(1);
+        }
+        console.log(fmt.header("Rafter Project Setup"));
+        console.log(fmt.info(`Project root: ${gitRoot}`));
+        console.log();
+        const allTargets = getProjectTargets(gitRoot);
+        // Filter by --only if specified
+        let targets = allTargets;
+        if (opts.only) {
+            const platformMap = {
+                "claude-code": "Claude Code",
+                "claude": "Claude Code",
+                "codex": "Codex CLI",
+                "gemini": "Gemini CLI",
+                "cursor": "Cursor",
+                "windsurf": "Windsurf",
+                "continue": "Continue.dev",
+                "aider": "Aider",
+            };
+            const requested = opts.only.split(",").map((s) => s.trim().toLowerCase());
+            const platformNames = requested.map(r => platformMap[r]).filter(Boolean);
+            if (platformNames.length === 0) {
+                console.error(fmt.error(`Unknown platforms: ${opts.only}`));
+                console.error("Valid: claude-code, codex, gemini, cursor, windsurf, continue, aider");
+                process.exit(1);
+            }
+            targets = allTargets.filter(t => platformNames.includes(t.platform));
+        }
+        // --list mode: show what would be created
+        if (opts.list) {
+            for (const target of targets) {
+                const exists = fs.existsSync(target.filePath);
+                const hasMarker = exists && fs.readFileSync(target.filePath, "utf-8").includes("<!-- rafter:start -->");
+                const status = hasMarker ? "update" : exists ? "append" : "create";
+                const rel = path.relative(gitRoot, target.filePath);
+                console.log(`  [${status}]  ${rel} — ${target.description}`);
+            }
+            console.log();
+            console.log(fmt.info("Run without --list to write files."));
+            return;
+        }
+        // Write instruction files
+        let created = 0;
+        let updated = 0;
+        let failed = 0;
+        for (const target of targets) {
+            const rel = path.relative(gitRoot, target.filePath);
+            const existed = fs.existsSync(target.filePath);
+            const hadMarker = existed && fs.readFileSync(target.filePath, "utf-8").includes("<!-- rafter:start -->");
+            try {
+                injectInstructionFile(target.filePath);
+                if (hadMarker) {
+                    console.log(fmt.success(`[updated]  ${rel}`));
+                    updated++;
+                }
+                else {
+                    console.log(fmt.success(`[created]  ${rel}`));
+                    created++;
+                }
+            }
+            catch (e) {
+                console.log(fmt.error(`[failed]   ${rel} — ${e}`));
+                failed++;
+            }
+        }
+        // Check for .rafter.yml
+        const policyPath = path.join(gitRoot, ".rafter.yml");
+        if (!fs.existsSync(policyPath)) {
+            console.log(fmt.info(`[skipped]  .rafter.yml — not found (optional: create one for project-specific policy)`));
+        }
+        // Check for pre-commit hook
+        const hookPath = path.join(gitRoot, ".git", "hooks", "pre-commit");
+        const hasRafterHook = fs.existsSync(hookPath) &&
+            fs.readFileSync(hookPath, "utf-8").includes("rafter");
+        if (!hasRafterHook) {
+            console.log(fmt.info(`[hint]     Run \`rafter agent install-hook\` to add pre-commit secret scanning`));
+        }
+        console.log();
+        if (created > 0 || updated > 0) {
+            console.log(fmt.success(`Done: ${created} created, ${updated} updated${failed > 0 ? `, ${failed} failed` : ""}`));
+            console.log();
+            console.log("Agents starting sessions in this project will now see Rafter security context.");
+            console.log("Consider committing these files so all contributors benefit.");
+        }
+        else if (failed > 0) {
+            console.log(fmt.error(`All ${failed} files failed to write.`));
+        }
+        console.log();
+    });
+}