@rafter-security/cli 0.6.5 → 0.7.0

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 remote 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 remote code analysis requires authentication.
 
-### Backend Scanning
+### Remote 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
 
@@ -500,7 +500,7 @@ Generate CI/CD pipeline configuration for secret scanning.
 **Options:**
 - `--platform <platform>` - CI platform: `github`, `gitlab`, `circleci` (default: auto-detect)
 - `--output <path>` - Output file path (default: platform-specific)
-- `--with-backend` - Include backend security audit job (requires `RAFTER_API_KEY`)
+- `--with-remote` - Include remote security audit job (requires `RAFTER_API_KEY`)
 
 **Auto-detection:** Checks for `.github/`, `.gitlab-ci.yml`, `.circleci/` in the current directory.
 
@@ -512,8 +512,8 @@ rafter ci init
 # Generate GitHub Actions workflow
 rafter ci init --platform github
 
-# Include backend scanning job
-rafter ci init --with-backend
+# Include remote scanning job
+rafter ci init --with-remote
 
 # Custom output path
 rafter ci init --output .github/workflows/security.yml
@@ -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. Remote 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)
+- **Remote 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 remote code analysis capabilities while keeping local security features safely behind user control.
 
 ## Documentation
 

package/dist/commands/agent/audit-skill.js

@@ -4,6 +4,7 @@ import path from "path";
 import { PatternEngine } from "../../core/pattern-engine.js";
 import { DEFAULT_SECRET_PATTERNS } from "../../scanners/secret-patterns.js";
 import { SkillManager } from "../../utils/skill-manager.js";
+import { fmt } from "../../utils/formatter.js";
 export function createAuditSkillCommand() {
     return new Command("audit-skill")
         .description("Security audit of a Claude Code skill file")
@@ -17,7 +18,7 @@ export function createAuditSkillCommand() {
 async function auditSkill(skillPath, opts) {
     // Validate skill file exists
     if (!fs.existsSync(skillPath)) {
-        console.error(`Error: Skill file not found: ${skillPath}`);
+        console.error(fmt.error(`Skill file not found: ${skillPath}`));
         process.exit(2);
     }
     const absolutePath = path.resolve(skillPath);
@@ -25,8 +26,8 @@ async function auditSkill(skillPath, opts) {
     const skillName = path.basename(absolutePath);
     // Run deterministic analysis
     if (!opts.json) {
-        console.log(`\n🔍 Auditing skill: ${skillName}\n`);
-        console.log("═".repeat(60));
+        console.log(fmt.header(`Auditing skill: ${skillName}`));
+        console.log(fmt.divider());
         console.log("Running quick security scan...\n");
     }
     const quickScan = await runQuickScan(skillContent);
@@ -56,11 +57,11 @@ async function auditSkill(skillPath, opts) {
     // Check if we can use OpenClaw
     if (openClawAvailable && !opts.skipOpenclaw) {
         if (!rafterSkillInstalled) {
-            console.log("\n⚠️  Rafter Security skill not installed in OpenClaw.");
+            console.log(`\n${fmt.warning("Rafter Security skill not installed in OpenClaw.")}`);
             console.log("   Run: rafter agent init\n");
         }
         else {
-            console.log("\n🤖 For comprehensive security review:\n");
+            console.log(`\n${fmt.info("For comprehensive security review:")}\n`);
             console.log("   1. Open OpenClaw");
             console.log(`   2. Run: /rafter-audit-skill ${absolutePath}`);
             console.log("\n   The auditor will analyze:");
@@ -80,12 +81,12 @@ async function auditSkill(skillPath, opts) {
     }
     else {
         // OpenClaw not available or skipped - show manual review prompt
-        console.log("\n📋 Manual Security Review Prompt\n");
-        console.log("═".repeat(60));
+        console.log(fmt.header("Manual Security Review Prompt"));
+        console.log(fmt.divider());
         console.log("\nCopy the following to your AI assistant for review:\n");
-        console.log("─".repeat(60));
+        console.log(fmt.divider());
         console.log(generateManualReviewPrompt(skillName, absolutePath, quickScan, skillContent));
-        console.log("─".repeat(60));
+        console.log(fmt.divider());
     }
     console.log();
     if (quickScan.secrets > 0 || quickScan.highRiskCommands.length > 0) {
@@ -134,25 +135,25 @@ async function runQuickScan(content) {
     };
 }
 function displayQuickScan(scan, skillName) {
-    console.log("📊 Quick Scan Results");
-    console.log("═".repeat(60));
+    console.log(fmt.header("Quick Scan Results"));
+    console.log(fmt.divider());
     // Secrets
     if (scan.secrets === 0) {
-        console.log("✓ Secrets: None detected");
+        console.log(fmt.success("Secrets: None detected"));
     }
     else {
-        console.log(`⚠️  Secrets: ${scan.secrets} found`);
+        console.log(fmt.warning(`Secrets: ${scan.secrets} found`));
         console.log("   → API keys, tokens, or credentials detected");
         console.log("   → Run: rafter scan local <path> for details");
     }
     // URLs
     if (scan.urls.length === 0) {
-        console.log("✓ External URLs: None");
+        console.log(fmt.success("External URLs: None"));
     }
     else {
-        console.log(`⚠️  External URLs: ${scan.urls.length} found`);
+        console.log(fmt.warning(`External URLs: ${scan.urls.length} found`));
         scan.urls.slice(0, 5).forEach(url => {
-            console.log(`   • ${url}`);
+            console.log(`   - ${url}`);
         });
         if (scan.urls.length > 5) {
             console.log(`   ... and ${scan.urls.length - 5} more`);
@@ -160,12 +161,12 @@ function displayQuickScan(scan, skillName) {
     }
     // High-risk commands
     if (scan.highRiskCommands.length === 0) {
-        console.log("✓ High-risk commands: None detected");
+        console.log(fmt.success("High-risk commands: None detected"));
     }
     else {
-        console.log(`⚠️  High-risk commands: ${scan.highRiskCommands.length} found`);
+        console.log(fmt.warning(`High-risk commands: ${scan.highRiskCommands.length} found`));
         scan.highRiskCommands.slice(0, 5).forEach(cmd => {
-            console.log(`   • ${cmd.command} (line ${cmd.line})`);
+            console.log(`   - ${cmd.command} (line ${cmd.line})`);
         });
         if (scan.highRiskCommands.length > 5) {
             console.log(`   ... and ${scan.highRiskCommands.length - 5} more`);

package/dist/commands/agent/config.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { ConfigManager } from "../../core/config-manager.js";
+import { fmt } from "../../utils/formatter.js";
 export function createConfigCommand() {
     const config = new Command("config")
         .description("Manage agent configuration");
@@ -48,7 +49,7 @@ export function createConfigCommand() {
             // Use as string
         }
         manager.set(key, parsedValue);
-        console.log(`✓ Set ${key} = ${JSON.stringify(parsedValue)}`);
+        console.log(fmt.success(`Set ${key} = ${JSON.stringify(parsedValue)}`));
     });
     return config;
 }

package/dist/commands/agent/exec.js

@@ -112,6 +112,8 @@ async function promptApproval() {
         output: process.stdout
     });
     return new Promise((resolve) => {
+        // Handle EOF / non-interactive stdin (e.g. piped or closed stdin)
+        rl.on("close", () => resolve(false));
         rl.question("Approve this command? (yes/no): ", (answer) => {
             rl.close();
             const normalized = answer.trim().toLowerCase();

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();
+    });
+}