@securityreviewai/securityreview-kit 0.1.22 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securityreviewai/securityreview-kit",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Bootstrap security-review-mcp for AI IDEs and CLI tools",
   "author": "Debarshi Das <debarshi.das@we45.com>",
   "license": "UNLICENSED",

package/src/cli.js

@@ -26,6 +26,9 @@ export function run() {
         .option('--switch-project', 'Fetch projects and only update mapped workspace rules')
         .option('--skip-mcp', 'Skip MCP server config installation')
         .option('--skip-rules', 'Skip workspace rule installation')
+        .option('--skip-ide-cli-install', 'Do not install Cursor / Claude Code / Codex CLIs when those targets are selected')
+        .option('--profile-repo', 'After init, run the guardrails profiler agent (non-interactive; needs cursor, claude, or codex target)')
+        .option('--no-profile-repo', 'Skip the optional profiler agent step after init')
         .action(async (options) => {
             try {
                 if (options.switchProject) {

package/src/commands/init.js

@@ -2,6 +2,9 @@ import chalk from 'chalk';
 import { input, checkbox, confirm, select } from '@inquirer/prompts';
 import { TARGETS, TARGET_NAMES } from '../utils/constants.js';
 import { detectTargets } from '../utils/detect.js';
+import { ensureIdeClisForTargets } from '../utils/ide-cli-install.js';
+import { writeGuardrailsProfilerBundle } from '../utils/guardrails-profiler-bundle.js';
+import { pickProfilerAgentTarget, runProfilerAgent } from '../utils/profiler-agent.js';
 import { fetchVibeReviewProjectNames, getStoredCredentials, normalizeApiUrl } from '../utils/srai.js';
 
 // Dynamic imports for generators (avoids loading all at startup)
@@ -220,18 +223,34 @@ export async function initCommand(options) {
     }
 
     // Step 1: Resolve targets
-    console.log(chalk.bold.white('  Step 1 of 4: Select Targets'));
+    console.log(chalk.bold.white('  Step 1 of 5: Select Targets'));
     console.log(chalk.dim('  ─────────────────────────────────'));
     const targets = await resolveTargets(options, interactive, cwd);
     console.log(chalk.green(`  ✓ Targets: ${targets.map((t) => TARGETS[t].name).join(', ')}`));
     console.log('');
+    console.log(chalk.bold.white('  Step 1b: IDE / agent CLIs'));
+    console.log(chalk.dim('  ─────────────────────────────────'));
+    const cliResults = ensureIdeClisForTargets(targets, { skipInstall: options.skipIdeCliInstall });
+    for (const r of cliResults) {
+        if (r.skipped) continue;
+        const label = TARGETS[r.target]?.name || r.target;
+        if (r.already) {
+            console.log(chalk.dim(`  • ${label} CLI already available`));
+        } else if (r.ok) {
+            console.log(chalk.green(`  \u2713 ${label} CLI install attempted`));
+        } else {
+            console.log(chalk.yellow(`  \u26a0  ${label} CLI: ${r.message || 'install skipped or failed'}`));
+        }
+    }
+    console.log('');
+
 
     // Step 2: What to install (rules question first, then MCP)
     let installMcp = !options.skipMcp;
     let installRules = !options.skipRules;
 
     if (interactive) {
-        console.log(chalk.bold.white('  Step 2 of 4: Installation Options'));
+        console.log(chalk.bold.white('  Step 2 of 5: Installation Options'));
         console.log(chalk.dim('  ─────────────────────────────────'));
         installRules = await confirm({
             message: '📋 Install workspace security rules?',
@@ -252,19 +271,19 @@ export async function initCommand(options) {
     // Step 3: Resolve credentials (only needed when MCP is being installed)
     let envVars = { apiUrl: '', apiToken: '' };
     if (installMcp) {
-        console.log(chalk.bold.white('  Step 3 of 4: SRAI Credentials'));
+        console.log(chalk.bold.white('  Step 3 of 5: SRAI Credentials'));
         console.log(chalk.dim('  ─────────────────────────────────'));
         envVars = await resolveEnvVars(options, interactive, cwd);
         console.log(chalk.green('  ✓ Credentials configured'));
     } else {
-        console.log(chalk.dim('  Step 3 of 4: Skipping SRAI credentials (MCP not selected).'));
+        console.log(chalk.dim('  Step 3 of 5: Skipping SRAI credentials (MCP not selected).'));
     }
     console.log('');
 
     // Step 4: Resolve project name (only needed when MCP is being installed)
     let projectName = options.projectName || process.env.SECURITY_REVIEW_PROJECT_NAME || '';
     if (installMcp) {
-        console.log(chalk.bold.white('  Step 4 of 4: SRAI Project Mapping'));
+        console.log(chalk.bold.white('  Step 4 of 5: SRAI Project Mapping'));
         console.log(chalk.dim('  ─────────────────────────────────'));
         projectName = await resolveProjectName(options, interactive, envVars.apiUrl, envVars.apiToken);
         if (projectName) {
@@ -273,11 +292,14 @@ export async function initCommand(options) {
             console.log(chalk.dim('  No project name provided. Rules will use a generic project lookup instruction.'));
         }
     } else {
-        console.log(chalk.dim('  Step 4 of 4: Skipping SRAI project mapping (MCP not selected).'));
+        console.log(chalk.dim('  Step 4 of 5: Skipping SRAI project mapping (MCP not selected).'));
     }
     console.log('');
 
-    console.log(chalk.bold.white('  Installing...'));
+    const projectNameForSkill =
+        (projectName || options.projectName || process.env.SECURITY_REVIEW_PROJECT_NAME || '').trim();
+
+    console.log(chalk.bold.white('  Step 5 of 5: Installing workspace files'));
     console.log(chalk.dim('  ─────────────────────────────────'));
 
     const results = [];
@@ -322,6 +344,17 @@ export async function initCommand(options) {
         }
     }
 
+    if (installRules) {
+        try {
+            const bundlePath = writeGuardrailsProfilerBundle(cwd, { projectName: projectNameForSkill });
+            console.log(chalk.green(`    \u2713 Guardrails profiler bundle → ${bundlePath}`));
+            results.push({ target: 'kit', type: 'bundle', status: 'ok', path: bundlePath });
+        } catch (err) {
+            console.log(chalk.red(`    \u2717 Guardrails profiler bundle failed: ${err.message}`));
+            results.push({ target: 'kit', type: 'bundle', status: 'error', error: err.message });
+        }
+    }
+
     // Summary
     const ok = results.filter((r) => r.status === 'ok').length;
     const errors = results.filter((r) => r.status === 'error').length;
@@ -335,6 +368,52 @@ export async function initCommand(options) {
             chalk.bold.yellow(`  ⚠  Done with ${errors} error(s). ${ok} configuration(s) installed.`),
         );
     }
+    console.log('');
+
+    const profilerEligible =
+        installMcp && installRules && projectNameForSkill && options.profileRepo !== false;
+
+    let shouldProfile = false;
+    if (profilerEligible) {
+        if (interactive) {
+            shouldProfile = await confirm({
+                message:
+                    'Profile this repository and push the default guardrail pack to SecurityReview.ai (runs your IDE agent CLI)?',
+                default: true,
+            });
+        } else {
+            shouldProfile = Boolean(options.profileRepo);
+        }
+    }
+
+    if (shouldProfile) {
+        const agentTarget = pickProfilerAgentTarget(targets);
+        if (!agentTarget) {
+            console.log(
+                chalk.yellow(
+                    '  \u26a0  Profiling needs Cursor, Claude Code, or Codex in your targets. Add one and re-run, or run the guardrails-init-profile command in your IDE.',
+                ),
+            );
+        } else {
+            console.log('');
+            console.log(chalk.bold.white(`  Starting profiler via ${TARGETS[agentTarget].name} CLI…`));
+            console.log(chalk.dim('  (Sign-in or approvals may be required in your terminal.)\n'));
+            const pr = runProfilerAgent(cwd, { target: agentTarget, projectName: projectNameForSkill });
+            if (pr.ok) {
+                console.log(chalk.green('  \u2713 Profiler agent finished.'));
+            } else {
+                const detail =
+                    pr.message ||
+                    (typeof pr.status === 'number' ? `exit status ${pr.status}` : 'unknown error');
+                console.log(
+                    chalk.yellow(
+                        `  \u26a0  Profiler agent exited with an error: ${detail}. You can run the guardrails-init-profile workflow manually.`,
+                    ),
+                );
+            }
+        }
+    }
+
     console.log('');
     console.log(chalk.dim('  Run `securityreview-kit status` to verify your setup.'));
     console.log('');

package/src/generators/rules/claude.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
-import { upsertSentinelBlock } from '../../utils/fs-helpers.js';
-import { getRuleContent } from './content.js';
+import { upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
+import { getRuleContent, getGuardrailsInitProfileContent } from './content.js';
 
 /**
  * Generate Claude Code workspace rule — appends to CLAUDE.md
@@ -9,5 +9,13 @@ export function generate(cwd, options = {}) {
     const filePath = join(cwd, 'CLAUDE.md');
     const content = getRuleContent(options);
     const action = upsertSentinelBlock(filePath, content);
-    return { filePath, action };
+
+    const guardrailsInitPath = join(cwd, '.claude', 'commands', 'guardrails-init-profile.md');
+    const guardrailsInitContent = getGuardrailsInitProfileContent(options);
+    writeText(guardrailsInitPath, guardrailsInitContent);
+
+    return [
+        { filePath, action, kind: 'rule' },
+        { filePath: guardrailsInitPath, action: 'created', kind: 'command' },
+    ];
 }

package/src/generators/rules/codex.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
-import { upsertSentinelBlock } from '../../utils/fs-helpers.js';
-import { getRuleContent } from './content.js';
+import { upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
+import { getRuleContent, getGuardrailsInitProfileContent } from './content.js';
 
 /**
  * Generate Codex workspace rule — appends to AGENTS.md
@@ -9,5 +9,13 @@ export function generate(cwd, options = {}) {
     const filePath = join(cwd, 'AGENTS.md');
     const content = getRuleContent(options);
     const action = upsertSentinelBlock(filePath, content);
-    return { filePath, action };
+
+    const guardrailsInitPath = join(cwd, '.codex', 'commands', 'guardrails-init-profile.md');
+    const guardrailsInitContent = getGuardrailsInitProfileContent(options);
+    writeText(guardrailsInitPath, guardrailsInitContent);
+
+    return [
+        { filePath, action, kind: 'rule' },
+        { filePath: guardrailsInitPath, action: 'created', kind: 'command' },
+    ];
 }

package/src/generators/rules/content.js

@@ -71,6 +71,13 @@ export function getGuardrailsRuleContent(options = {}) {
     return readTemplate('guardrails_rule.md', options);
 }
 
+/**
+ * Guardrails init profile command (repo scan + profile.json + SRAI upload).
+ */
+export function getGuardrailsInitProfileContent(options = {}) {
+    return readTemplate('guardrails-init-profile.md', options);
+}
+
 /**
  * Returns the hooks.json content for Cursor session hooks.
  */

package/src/generators/rules/content.md

@@ -119,4 +119,4 @@ When running `ctm_sync` (dedicated agent/command where available, or the same st
 | **Analysis** | `get_threat_scenarios`, `get_countermeasures`, `get_components`, `get_data_dictionaries`, `get_security_objectives`, `get_findings`, `get_security_test_cases` |
 | **Integrations** | `fetch_jira_issue`, `fetch_confluence_page`, `search_confluence_pages`, `fetch_and_link_to_srai` |
 | **AI IDE CTM** | `create_ai_ide_workflow`, `create_ai_ide_event` (and any `list_*` AI IDE workflow tools exposed by the server) |
-| **Profile Update** | `update_vibe_project_profile` |
+| **Vibe profile & default packs** | `update_vibe_profile`, `write_default_pack` (used by the guardrails profiler / init flow — not part of `ctm_sync`) |

package/src/generators/rules/ctm_sync.md

@@ -34,14 +34,7 @@ When invoked:
 6. **Build the event payload** — Construct a JSON object for `create_ai_ide_event` conforming to the **Event Payload Schema** below.
 7. **Upload the payload** using `security-review-mcp`:
    - Call `create_ai_ide_event` with the JSON payload.
-8. **Push a project profile update** — After the event is created, derive project profile data from the current threat model context and call `update_vibe_project_profile` with `project_id` and the following fields:
-   - `description`: a concise summary of the system/project derived from the threat model context (what it does, what data it handles, its overall purpose)
-   - `architecture_notes`: a list of architecture observations extracted from the threat model — deployment topology, trust boundaries, data flows, integration points
-   - `tech_categories`: a list of technology category labels identified during threat modeling (e.g. `"backend"`, `"frontend"`, `"database"`, `"cloud"`, `"mobile"`)
-   - `user_groups`: a list of user roles and groups surfaced in the threat model (e.g. `"admin"`, `"end user"`, `"service account"`)
-   - `compliance_requirements`: a list of compliance requirements or standards referenced in the threat model or conversation (e.g. `"PCI-DSS"`, `"HIPAA"`, `"SOC 2"`)
-   - `language_stacks`: a list of programming languages, runtimes, and major frameworks identified in the codebase or threat model context (e.g. `"Python/FastAPI"`, `"TypeScript/React"`, `"Java/Spring"`)
-   - Omit any field for which no data is available in context — do **not** invent values. Pass an empty list `[]` only if the field is reasonably expected but simply unpopulated.
+   - **Stop here.** Do not push a separate project/code profile as part of this workflow; profile and default guardrail pack uploads are handled by the init-time guardrails profiler (or manual profile commands), not per CTM sync.
 
 ---
 
@@ -155,8 +148,6 @@ Use the following IDs and names exactly when populating `owasp_top_10_2025_mappi
 - Never skip upload when a threat model exists.
 - Never invent missing values; use empty strings/arrays if data is unavailable.
 - Never omit `chat_session_id` from the payload.
-- Never skip the `update_vibe_project_profile` call when profile-relevant data (architecture, tech, users, compliance, languages, or description) can be derived from context.
 - Return a compact confirmation after upload including:
   - Whether an existing workflow was reused or a new named workflow was created
-  - Confirmation that the project profile was updated
   - Count of guardrails applied (existing vs IDE-generated)

package/src/generators/rules/cursor.js

@@ -9,6 +9,7 @@ import {
     getCreateIdeWorkflowCommandContent,
     getThreatModellingSkillContent,
     getGuardrailsRuleContent,
+    getGuardrailsInitProfileContent,
     getHooksContent,
 } from './content.js';
 
@@ -44,6 +45,7 @@ export function generate(cwd, options = {}) {
     const ctmSyncAgentPath = join(cwd, '.cursor', 'agents', 'ctm_sync.md');
     const createIdeWorkflowCommandPath = join(cwd, '.cursor', 'commands', 'create-ide-workflow.md');
     const profileCommandPath = join(cwd, '.cursor', 'commands', 'srai-profile.md');
+    const guardrailsInitProfileCommandPath = join(cwd, '.cursor', 'commands', 'guardrails-init-profile.md');
     const skillPath = join(cwd, '.cursor', 'skills', 'threat-modelling', 'SKILL.md');
     const hooksPath = join(cwd, '.cursor', 'hooks.json');
 
@@ -53,6 +55,7 @@ export function generate(cwd, options = {}) {
     const ctmSyncWorkflowContent = getCtmSyncWorkflowContent(options);
     const createIdeWorkflowCommandContent = getCreateIdeWorkflowCommandContent(options);
     const profileCommandContent = getProfileCommandContent(options);
+    const guardrailsInitProfileCommandContent = getGuardrailsInitProfileContent(options);
     const skillContent = getThreatModellingSkillContent(options);
 
     const baseRule = writeCursorRule(
@@ -72,6 +75,10 @@ export function generate(cwd, options = {}) {
     const createIdeWorkflowCommand = writeCursorCommand(createIdeWorkflowCommandPath, createIdeWorkflowCommandContent);
 
     const profileCommand = writeCursorCommand(profileCommandPath, profileCommandContent);
+    const guardrailsInitProfileCommand = writeCursorCommand(
+        guardrailsInitProfileCommandPath,
+        guardrailsInitProfileCommandContent,
+    );
     const skillAction = existsSync(skillPath) ? 'updated' : 'created';
     writeText(skillPath, skillContent);
 
@@ -87,6 +94,7 @@ export function generate(cwd, options = {}) {
         { ...ctmSyncAgent, kind: 'agent' },
         { ...createIdeWorkflowCommand, kind: 'command' },
         { ...profileCommand, kind: 'command' },
+        { ...guardrailsInitProfileCommand, kind: 'command' },
         { filePath: skillPath, action: skillAction, kind: 'skill' },
         { filePath: hooksPath, action: hooksAction, kind: 'hooks' },
     ];

package/src/generators/rules/guardrails-init-profile.md

@@ -0,0 +1,18 @@
+---
+name: guardrails-init-profile
+description: Run the Security Review Kit guardrails profiler — scan the repo, write profile.json, push profile and default guardrail pack to SecurityReview.ai via MCP.
+---
+
+# Guardrails init profile
+
+Execute the workflow defined in **`.securityreview-kit/guardrails-profiler/SKILL.md`** end-to-end in this workspace.
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+**You must:**
+
+1. Read `.securityreview-kit/guardrails-profiler/SKILL.md` and follow every step (use the signal registry at `.securityreview-kit/guardrails-profiler/references/signal-registry.json`).
+2. Write `.guardrails/profile.json` and **`profile.json`** at the project root as specified.
+3. Call **`update_vibe_profile`** and **`write_default_pack`** on `security-review-mcp` after resolving `project_id` for `<SRAI_PROJECT_NAME>`.
+
+Do not skip MCP upload when credentials and MCP are available.

package/src/generators/rules/guardrails-profiler/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: guardrails-profiler
+description: Profile a codebase to detect its technology stack and generate a guardrails profile for security-aware AI code generation, then publish the profile and default guardrail pack to SecurityReview.ai via security-review-mcp. Use when Security Review Kit init runs profiling, when `.guardrails/profile.json` is missing, or when the developer asks to profile or re-profile the project.
+---
+
+# Guardrails Profiler
+
+Profile a codebase's technology stack, write `.guardrails/profile.json`, write a combined **`profile.json` in the project root**, and upload to SRAI using `update_vibe_profile` and `write_default_pack`.
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+## Canonical paths
+
+- **Signal registry (read-only):** `.securityreview-kit/guardrails-profiler/references/signal-registry.json`
+- **Local guardrails file:** `.guardrails/profile.json`
+- **Combined manifest (project root):** `profile.json` — includes guardrails profile, vibe profile fields for MCP, and default pack payload
+
+## When This Runs
+
+1. **Kit init**: User opted in to profile the repo and push the default pack.
+2. **First-run / missing profile**: No `.guardrails/profile.json` and guardrails are needed before threat modeling.
+3. **Explicit re-profile**: Developer asks to refresh the profile.
+
+## Quick Check: Should I Profile?
+
+Before profiling, check if a profile already exists:
+
+- If `.guardrails/profile.json` exists and has a valid `schema_version`: **SKIP** unless the developer asked to re-profile.
+- If missing: **PROCEED**.
+
+## Profiling Procedure
+
+Follow these steps in order.
+
+### Step 1: Locate the Project Root
+
+The project root is the current working directory. Confirm with markers such as `.git/`, `package.json`, `go.mod`, etc.
+
+### Step 2: Read the Signal Registry
+
+Read `.securityreview-kit/guardrails-profiler/references/signal-registry.json`. Use its categories (`universal`, `languages`, `frameworks`, `auth_identity`, `ai_agent`, `infrastructure`, `ci_cd`, `cloud_compute`, `databases`, `messaging`, `api_protocols`, etc.) to map detected signals to guardrail pack IDs.
+
+### Step 3: Scan for Signals
+
+Same methodology as the upstream guardrails-profiler skill:
+
+#### 3a. Manifest and Config File Detection
+
+List files in the project root (1–2 levels deep). Detect manifests (`package.json`, `pyproject.toml`, `go.mod`, `pom.xml`, `Dockerfile`, `.github/workflows/`, `next.config.*`, etc.) per the registry.
+
+#### 3b. Dependency Parsing
+
+For each manifest found, read dependencies and match names against `dependency_signals` in the registry. Prefer manifests over extension-only guesses.
+
+#### 3c. Content Signals (targeted only)
+
+When needed, grep specific files (e.g. Terraform providers, K8s `apiVersion`, CloudFormation) — do not read the entire repository.
+
+#### 3d. File Extension Fallback
+
+If no manifest exists for a language, use dominant extensions as a last resort.
+
+### Step 4: Assemble the Guardrails Profile Object
+
+Build the object for `.guardrails/profile.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "project_name": "<directory name>",
+  "profiled_at": "<ISO 8601 timestamp>",
+  "profiled_by": "<ide or cli id, e.g. cursor-agent, claude, codex>",
+  "detection_summary": {
+    "languages": [],
+    "frameworks": [],
+    "infrastructure": [],
+    "databases": [],
+    "auth": [],
+    "ai_agent": [],
+    "ci_cd": [],
+    "cloud_compute": [],
+    "messaging": [],
+    "api_protocols": [],
+    "mobile": false
+  },
+  "guardrail_packs": [],
+  "pack_count": 0
+}
+```
+
+Rules for `guardrail_packs`:
+
+1. Always include `owasp-asvs`.
+2. Include `owasp-masvs` if mobile stacks are detected (flutter, react-native, swift, objective-c, kotlin per registry).
+3. Add language, framework, auth, AI, infra, CI/CD, cloud, DB, messaging, and API packs per registry matches.
+4. Deduplicate and set `pack_count`.
+
+Do **not** invent packs or signals; if the repo is empty, use universal baseline only and empty category arrays where appropriate.
+
+### Step 5: Write `.guardrails/profile.json`
+
+Create `.guardrails/` if needed and write the profile file.
+
+### Step 6: Build `profile.json` (project root)
+
+Write **`profile.json`** at the project root with this structure (all parts required; use empty strings or `[]` when unknown — never fabricate compliance or user groups):
+
+```json
+{
+  "schema_version": "2.0",
+  "srai_project_name": "<SRAI_PROJECT_NAME>",
+  "guardrails_profile": {},
+  "vibe_profile": {
+    "description": "<short summary of what the repo appears to be, from detected stack only>",
+    "architecture_notes": [],
+    "tech_categories": [],
+    "user_groups": [],
+    "compliance_requirements": [],
+    "language_stacks": []
+  },
+  "default_guardrail_pack": {
+    "guardrail_packs": [],
+    "pack_count": 0
+  }
+}
+```
+
+Populate `guardrails_profile` with the **same object** written to `.guardrails/profile.json`.
+
+Populate `default_guardrail_pack.guardrail_packs` with the deduplicated pack id list (same as `guardrails_profile.guardrail_packs`) and `pack_count`.
+
+Derive `vibe_profile` fields **only** from what you observed:
+
+- `tech_categories`: e.g. `backend`, `frontend`, `database`, `cloud`, `mobile` when supported by files/deps.
+- `language_stacks`: strings like `TypeScript/Node`, `Python/FastAPI` from detection.
+- `architecture_notes`: short bullets (e.g. "Dockerfile present", "GitHub Actions CI") — not speculative threat narratives.
+- `user_groups` / `compliance_requirements`: only if explicit in repo (e.g. compliance docs); else `[]`.
+
+### Step 7: Upload to SecurityReview.ai (security-review-mcp)
+
+1. Resolve `project_id`: `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"`. If missing, follow existing kit rules (`list_projects`, `create_project`).
+
+2. Call **`update_vibe_profile`** with `project_id` and the fields from `profile.json.vibe_profile` (map parameter names to the MCP tool’s expected shape; pass only fields the tool accepts).
+
+3. Call **`write_default_pack`** with `project_id` and the default pack payload from `profile.json.default_guardrail_pack` (match the MCP tool’s schema — typically the pack id list and metadata the server expects).
+
+4. Confirm success to the user: paths written (`profile.json`, `.guardrails/profile.json`) and that both MCP calls completed or the exact error.
+
+### Step 8: Report
+
+Give a concise summary of detected stack, pack count, and upload status.
+
+## Empty / New Repository Handling
+
+If there are no signals:
+
+1. Optionally read `.git/config` for hints.
+2. Emit minimal profile: `owasp-asvs` only, empty summaries where appropriate.
+3. Still write `profile.json` and attempt MCP calls with honest minimal `vibe_profile` data.
+
+## IDE-Specific Notes
+
+When run from Cursor Agent CLI, Claude Code, or Codex CLI, set `profiled_by` to a stable id (`cursor-agent`, `claude`, `codex`).

package/src/generators/rules/guardrails-profiler/references/signal-registry.json

@@ -0,0 +1,514 @@
+{
+  "_doc": "Maps filesystem signals to guardrail pack IDs. Each entry defines what to look for and which pack to activate.",
+
+  "universal": {
+    "_doc": "Always included regardless of detection",
+    "packs": ["owasp-asvs"]
+  },
+
+  "mobile_universal": {
+    "_doc": "Included when any mobile platform is detected",
+    "trigger_packs": ["flutter", "react-native", "swift", "objective-c", "kotlin"],
+    "packs": ["owasp-masvs"]
+  },
+
+  "languages": {
+    "typescript": {
+      "manifest_files": ["tsconfig.json", "tsconfig.base.json"],
+      "file_extensions": [".ts", ".tsx"],
+      "pack": "typescript"
+    },
+    "nodejs": {
+      "manifest_files": ["package.json"],
+      "file_extensions": [".js", ".mjs", ".cjs"],
+      "pack": "nodejs"
+    },
+    "python": {
+      "manifest_files": ["requirements.txt", "pyproject.toml", "setup.py", "setup.cfg", "Pipfile", "poetry.lock"],
+      "file_extensions": [".py"],
+      "pack": null,
+      "_note": "Python has no standalone pack; frameworks (django, flask, fastapi) cover it"
+    },
+    "go": {
+      "manifest_files": ["go.mod", "go.sum"],
+      "file_extensions": [".go"],
+      "pack": "go"
+    },
+    "java": {
+      "manifest_files": ["pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts"],
+      "file_extensions": [".java"],
+      "pack": null,
+      "_note": "Java framework packs (spring-boot, java-ee) are more specific"
+    },
+    "kotlin": {
+      "manifest_files": ["build.gradle.kts"],
+      "file_extensions": [".kt", ".kts"],
+      "dependency_signals": { "build.gradle.kts": ["kotlin"] },
+      "pack": "kotlin"
+    },
+    "php": {
+      "manifest_files": ["composer.json", "composer.lock"],
+      "file_extensions": [".php"],
+      "pack": "php"
+    },
+    "ruby": {
+      "manifest_files": ["Gemfile", "Gemfile.lock"],
+      "file_extensions": [".rb"],
+      "pack": null,
+      "_note": "Ruby framework pack (ruby-on-rails) is more specific"
+    },
+    "rust": {
+      "manifest_files": ["Cargo.toml", "Cargo.lock"],
+      "file_extensions": [".rs"],
+      "pack": "rust"
+    },
+    "c": {
+      "file_extensions": [".c", ".h"],
+      "manifest_files": ["CMakeLists.txt", "Makefile"],
+      "pack": "c"
+    },
+    "cpp": {
+      "file_extensions": [".cpp", ".cxx", ".cc", ".hpp", ".hxx"],
+      "manifest_files": ["CMakeLists.txt"],
+      "pack": "cpp"
+    },
+    "swift": {
+      "manifest_files": ["Package.swift"],
+      "file_extensions": [".swift"],
+      "config_files": ["*.xcodeproj", "*.xcworkspace"],
+      "pack": "swift"
+    },
+    "objective-c": {
+      "file_extensions": [".m", ".mm"],
+      "pack": "objective-c"
+    },
+    "groovy": {
+      "file_extensions": [".groovy"],
+      "pack": "groovy"
+    },
+    "csharp": {
+      "manifest_files": ["*.csproj", "*.sln"],
+      "file_extensions": [".cs"],
+      "pack": null,
+      "_note": "C# framework pack (dotnet-aspnet-core) is more specific"
+    }
+  },
+
+  "frameworks": {
+    "express": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["express"] },
+      "pack": "express"
+    },
+    "fastify": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["fastify"] },
+      "pack": "fastify"
+    },
+    "honojs": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["hono"] },
+      "pack": "honojs"
+    },
+    "nestjs": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["@nestjs/core"] },
+      "config_files": ["nest-cli.json"],
+      "pack": "nestjs"
+    },
+    "nextjs": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["next"] },
+      "config_files": ["next.config.js", "next.config.mjs", "next.config.ts"],
+      "pack": "nextjs"
+    },
+    "react": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["react", "react-dom"] },
+      "pack": "react"
+    },
+    "angular": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["@angular/core"] },
+      "config_files": ["angular.json"],
+      "pack": "angular"
+    },
+    "vuejs": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["vue"] },
+      "config_files": ["vue.config.js", "vite.config.ts", "nuxt.config.ts"],
+      "pack": "vuejs"
+    },
+    "electron": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["electron"] },
+      "pack": "electron"
+    },
+    "react-native": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["react-native"] },
+      "pack": "react-native"
+    },
+    "django": {
+      "ecosystem": "python",
+      "dependency_signals": {
+        "requirements.txt": ["django", "Django"],
+        "pyproject.toml": ["django", "Django"],
+        "Pipfile": ["django", "Django"]
+      },
+      "config_files": ["manage.py"],
+      "directory_signals": ["*/settings.py", "*/wsgi.py"],
+      "pack": "django"
+    },
+    "flask": {
+      "ecosystem": "python",
+      "dependency_signals": {
+        "requirements.txt": ["flask", "Flask"],
+        "pyproject.toml": ["flask", "Flask"]
+      },
+      "pack": "flask"
+    },
+    "fastapi": {
+      "ecosystem": "python",
+      "dependency_signals": {
+        "requirements.txt": ["fastapi"],
+        "pyproject.toml": ["fastapi"]
+      },
+      "pack": "fastapi"
+    },
+    "java-spring-boot": {
+      "ecosystem": "java",
+      "dependency_signals": {
+        "pom.xml": ["spring-boot-starter"],
+        "build.gradle": ["org.springframework.boot"]
+      },
+      "pack": "java-spring-boot"
+    },
+    "spring-security": {
+      "ecosystem": "java",
+      "dependency_signals": {
+        "pom.xml": ["spring-boot-starter-security", "spring-security"],
+        "build.gradle": ["spring-boot-starter-security", "spring-security"]
+      },
+      "pack": "spring-security"
+    },
+    "java-ee": {
+      "ecosystem": "java",
+      "dependency_signals": {
+        "pom.xml": ["javax.servlet", "jakarta.servlet", "javax.enterprise", "jakarta.enterprise"],
+        "build.gradle": ["javax.servlet", "jakarta.servlet"]
+      },
+      "config_files": ["web.xml"],
+      "pack": "java-ee"
+    },
+    "ruby-on-rails": {
+      "ecosystem": "ruby",
+      "dependency_signals": { "Gemfile": ["rails"] },
+      "config_files": ["config/routes.rb", "config/application.rb"],
+      "pack": "ruby-on-rails"
+    },
+    "laravel": {
+      "ecosystem": "php",
+      "dependency_signals": { "composer.json": ["laravel/framework"] },
+      "config_files": ["artisan"],
+      "directory_signals": ["app/Http/Controllers"],
+      "pack": "laravel"
+    },
+    "symfony": {
+      "ecosystem": "php",
+      "dependency_signals": { "composer.json": ["symfony/framework-bundle"] },
+      "config_files": ["config/bundles.php", "symfony.lock"],
+      "pack": "symfony"
+    },
+    "dotnet-aspnet-core": {
+      "ecosystem": "csharp",
+      "dependency_signals": { "*.csproj": ["Microsoft.AspNetCore"] },
+      "config_files": ["Program.cs", "Startup.cs", "appsettings.json"],
+      "pack": "dotnet-aspnet-core"
+    },
+    "flutter": {
+      "ecosystem": "dart",
+      "manifest_files": ["pubspec.yaml"],
+      "dependency_signals": { "pubspec.yaml": ["flutter"] },
+      "pack": "flutter"
+    },
+    "apollo-graphql": {
+      "ecosystem": "nodejs",
+      "dependency_signals": { "package.json": ["@apollo/server", "apollo-server", "apollo-server-express"] },
+      "pack": "apollo-graphql"
+    }
+  },
+
+  "auth_identity": {
+    "jwt": {
+      "dependency_signals": {
+        "package.json": ["jsonwebtoken", "jose", "@auth/core"],
+        "requirements.txt": ["pyjwt", "python-jose"],
+        "pyproject.toml": ["pyjwt", "python-jose"],
+        "Gemfile": ["jwt"],
+        "pom.xml": ["jjwt", "nimbus-jose-jwt"]
+      },
+      "pack": "jwt"
+    },
+    "oauth-oidc": {
+      "dependency_signals": {
+        "package.json": ["openid-client", "passport-oauth2", "oauth4webapi"],
+        "requirements.txt": ["authlib", "oauthlib"],
+        "pyproject.toml": ["authlib", "oauthlib"]
+      },
+      "pack": "oauth-oidc"
+    },
+    "auth0": {
+      "dependency_signals": {
+        "package.json": ["@auth0/nextjs-auth0", "auth0", "express-openid-connect"],
+        "requirements.txt": ["auth0-python"],
+        "pyproject.toml": ["auth0-python"]
+      },
+      "pack": "auth0"
+    },
+    "okta": {
+      "dependency_signals": {
+        "package.json": ["@okta/okta-sdk-nodejs", "@okta/oidc-middleware"],
+        "pom.xml": ["okta-spring-boot-starter"]
+      },
+      "pack": "okta"
+    },
+    "keycloak": {
+      "dependency_signals": {
+        "package.json": ["keycloak-connect", "keycloak-js"],
+        "pom.xml": ["keycloak-spring-boot-starter"]
+      },
+      "config_files": ["keycloak.json"],
+      "pack": "keycloak"
+    }
+  },
+
+  "ai_agent": {
+    "langchain": {
+      "dependency_signals": {
+        "requirements.txt": ["langchain"],
+        "pyproject.toml": ["langchain"],
+        "package.json": ["langchain"]
+      },
+      "pack": "langchain"
+    },
+    "langgraph": {
+      "dependency_signals": {
+        "requirements.txt": ["langgraph"],
+        "pyproject.toml": ["langgraph"]
+      },
+      "pack": "langgraph"
+    },
+    "llamaindex": {
+      "dependency_signals": {
+        "requirements.txt": ["llama-index", "llama_index"],
+        "pyproject.toml": ["llama-index", "llama_index"]
+      },
+      "pack": "llamaindex"
+    },
+    "crewai": {
+      "dependency_signals": {
+        "requirements.txt": ["crewai"],
+        "pyproject.toml": ["crewai"]
+      },
+      "pack": "crewai"
+    },
+    "mastra": {
+      "dependency_signals": {
+        "package.json": ["@mastra/core", "mastra"]
+      },
+      "pack": "mastra"
+    },
+    "ai-sdk": {
+      "dependency_signals": {
+        "package.json": ["ai", "@ai-sdk/openai", "@ai-sdk/anthropic"]
+      },
+      "pack": "ai-sdk"
+    },
+    "claude-agent-sdk": {
+      "dependency_signals": {
+        "package.json": ["@anthropic-ai/sdk"],
+        "requirements.txt": ["anthropic"],
+        "pyproject.toml": ["anthropic"]
+      },
+      "pack": "claude-agent-sdk"
+    },
+    "openai-agents-sdk": {
+      "dependency_signals": {
+        "package.json": ["openai"],
+        "requirements.txt": ["openai"],
+        "pyproject.toml": ["openai"]
+      },
+      "pack": "openai-agents-sdk"
+    },
+    "mcp": {
+      "dependency_signals": {
+        "package.json": ["@modelcontextprotocol/sdk"],
+        "requirements.txt": ["mcp"],
+        "pyproject.toml": ["mcp"]
+      },
+      "pack": "mcp"
+    }
+  },
+
+  "infrastructure": {
+    "docker": {
+      "config_files": ["Dockerfile", "docker-compose.yml", "docker-compose.yaml", ".dockerignore"],
+      "pack": "docker"
+    },
+    "kubernetes": {
+      "config_files": ["helmfile.yaml", "Chart.yaml", "kustomization.yaml"],
+      "directory_signals": ["k8s/", "kubernetes/", "helm/"],
+      "content_signals": { "*.yaml": ["apiVersion", "kind: Deployment", "kind: Service", "kind: Pod"] },
+      "pack": "kubernetes"
+    },
+    "terraform-aws": {
+      "file_extensions": [".tf"],
+      "content_signals": { "*.tf": ["provider \"aws\"", "aws_"] },
+      "pack": "terraform-aws"
+    },
+    "terraform-azure": {
+      "file_extensions": [".tf"],
+      "content_signals": { "*.tf": ["provider \"azurerm\"", "azurerm_"] },
+      "pack": "terraform-azure"
+    },
+    "terraform-gcp": {
+      "file_extensions": [".tf"],
+      "content_signals": { "*.tf": ["provider \"google\"", "google_"] },
+      "pack": "terraform-gcp"
+    },
+    "cloudformation": {
+      "content_signals": { "*.yaml": ["AWSTemplateFormatVersion"], "*.json": ["AWSTemplateFormatVersion"] },
+      "config_files": ["template.yaml", "template.json", "samconfig.toml"],
+      "pack": "cloudformation"
+    },
+    "nginx": {
+      "config_files": ["nginx.conf"],
+      "directory_signals": ["nginx/"],
+      "pack": "nginx"
+    }
+  },
+
+  "ci_cd": {
+    "github-actions": {
+      "directory_signals": [".github/workflows/"],
+      "pack": "github-actions"
+    },
+    "jenkins-pipeline": {
+      "config_files": ["Jenkinsfile"],
+      "pack": "jenkins-pipeline"
+    },
+    "argocd": {
+      "config_files": ["argocd-cm.yaml"],
+      "content_signals": { "*.yaml": ["argoproj.io"] },
+      "pack": "argocd"
+    }
+  },
+
+  "cloud_compute": {
+    "aws-lambda": {
+      "config_files": ["serverless.yml", "serverless.yaml", "serverless.ts", "sam.yaml", "samconfig.toml"],
+      "content_signals": {
+        "serverless.yml": ["provider:", "aws"],
+        "template.yaml": ["AWS::Serverless::Function", "AWS::Lambda::Function"]
+      },
+      "pack": "aws-lambda"
+    },
+    "azure-functions": {
+      "config_files": ["host.json", "local.settings.json"],
+      "directory_signals": ["function_app.py"],
+      "pack": "azure-functions"
+    },
+    "gcp-cloud-run": {
+      "config_files": ["app.yaml", "cloudbuild.yaml"],
+      "content_signals": { "*.yaml": ["gcr.io", "run.googleapis.com"] },
+      "pack": "gcp-cloud-run"
+    }
+  },
+
+  "databases": {
+    "mongodb": {
+      "dependency_signals": {
+        "package.json": ["mongoose", "mongodb"],
+        "requirements.txt": ["pymongo", "motor", "mongoengine"],
+        "pyproject.toml": ["pymongo", "motor"],
+        "Gemfile": ["mongoid"]
+      },
+      "pack": "mongodb"
+    },
+    "postgresql": {
+      "dependency_signals": {
+        "package.json": ["pg", "knex", "prisma", "typeorm", "sequelize"],
+        "requirements.txt": ["psycopg2", "asyncpg", "sqlalchemy"],
+        "pyproject.toml": ["psycopg2", "asyncpg", "sqlalchemy"],
+        "Gemfile": ["pg"],
+        "pom.xml": ["postgresql"]
+      },
+      "pack": "postgresql"
+    },
+    "mysql-mariadb": {
+      "dependency_signals": {
+        "package.json": ["mysql2", "mysql"],
+        "requirements.txt": ["mysqlclient", "pymysql", "aiomysql"],
+        "pyproject.toml": ["mysqlclient", "pymysql"],
+        "pom.xml": ["mysql-connector-java"]
+      },
+      "pack": "mysql-mariadb"
+    },
+    "redis": {
+      "dependency_signals": {
+        "package.json": ["redis", "ioredis"],
+        "requirements.txt": ["redis", "aioredis"],
+        "pyproject.toml": ["redis"],
+        "Gemfile": ["redis"]
+      },
+      "pack": "redis"
+    }
+  },
+
+  "messaging": {
+    "kafka": {
+      "dependency_signals": {
+        "package.json": ["kafkajs"],
+        "requirements.txt": ["confluent-kafka", "aiokafka"],
+        "pyproject.toml": ["confluent-kafka"],
+        "pom.xml": ["kafka-clients", "spring-kafka"]
+      },
+      "pack": "kafka"
+    },
+    "rabbitmq": {
+      "dependency_signals": {
+        "package.json": ["amqplib"],
+        "requirements.txt": ["pika", "aio-pika"],
+        "pyproject.toml": ["pika"],
+        "pom.xml": ["spring-boot-starter-amqp"]
+      },
+      "pack": "rabbitmq"
+    }
+  },
+
+  "api_protocols": {
+    "grpc": {
+      "dependency_signals": {
+        "package.json": ["@grpc/grpc-js"],
+        "requirements.txt": ["grpcio"],
+        "pyproject.toml": ["grpcio"],
+        "pom.xml": ["grpc-netty"]
+      },
+      "file_extensions": [".proto"],
+      "pack": "grpc"
+    },
+    "websockets": {
+      "dependency_signals": {
+        "package.json": ["ws", "socket.io"],
+        "requirements.txt": ["websockets"],
+        "pyproject.toml": ["websockets"]
+      },
+      "pack": "websockets"
+    },
+    "openapi-rest-api": {
+      "config_files": ["openapi.yaml", "openapi.json", "swagger.yaml", "swagger.json"],
+      "pack": "openapi-rest-api"
+    }
+  }
+}

package/src/utils/guardrails-profiler-bundle.js

@@ -0,0 +1,33 @@
+import { copyFileSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureDir, writeText } from './fs-helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function sanitizeProjectName(value) {
+    return String(value || '').replace(/[\r\n`]/g, ' ').trim();
+}
+
+function injectProjectName(content, projectName) {
+    const resolved = sanitizeProjectName(projectName) || '<SRAI_PROJECT_NAME>';
+    return content.replaceAll('{{SRAI_PROJECT_NAME}}', resolved).replaceAll('<SRAI_PROJECT_NAME>', resolved);
+}
+
+const BUNDLE_ROOT = join(__dirname, '..', 'generators', 'rules', 'guardrails-profiler');
+
+/**
+ * Writes `.securityreview-kit/guardrails-profiler/` (SKILL + signal registry) into the target workspace.
+ */
+export function writeGuardrailsProfilerBundle(cwd, options = {}) {
+    const destBase = join(cwd, '.securityreview-kit', 'guardrails-profiler');
+    const destRefs = join(destBase, 'references');
+    ensureDir(destRefs);
+
+    const skillTemplate = readFileSync(join(BUNDLE_ROOT, 'SKILL.md'), 'utf-8');
+    writeText(join(destBase, 'SKILL.md'), injectProjectName(skillTemplate, options.projectName));
+
+    copyFileSync(join(BUNDLE_ROOT, 'references', 'signal-registry.json'), join(destRefs, 'signal-registry.json'));
+
+    return destBase;
+}

package/src/utils/ide-cli-install.js

@@ -0,0 +1,82 @@
+import { spawnSync } from 'node:child_process';
+
+const AGENT_CLI_TARGETS = new Set(['cursor', 'claude', 'codex']);
+
+function commandOk(cmd, args = ['--version']) {
+    const r = spawnSync(cmd, args, { stdio: 'ignore' });
+    return r.status === 0;
+}
+
+function runShell(script) {
+    return spawnSync(script, { shell: true, stdio: 'inherit' });
+}
+
+/**
+ * Ensure Cursor / Claude Code / Codex CLIs are present when those targets are selected.
+ * Installation uses vendor scripts or npm where appropriate.
+ */
+export function ensureIdeCliForTarget(target, options = {}) {
+    const { skipInstall = false } = options;
+
+    if (!AGENT_CLI_TARGETS.has(target)) {
+        return { target, ok: true, skipped: true };
+    }
+
+    if (target === 'cursor') {
+        if (commandOk('cursor-agent', ['--version'])) {
+            return { target, ok: true, already: true };
+        }
+        if (skipInstall) {
+            return { target, ok: false, message: 'cursor-agent not found on PATH' };
+        }
+        if (process.platform === 'win32') {
+            return {
+                target,
+                ok: false,
+                message: 'Install Cursor CLI manually: https://cursor.com/cli',
+            };
+        }
+        const r = runShell('curl -fsSL https://cursor.com/install | bash');
+        return r.status === 0
+            ? { target, ok: true }
+            : { target, ok: false, message: 'Cursor CLI install script failed' };
+    }
+
+    if (target === 'claude') {
+        if (commandOk('claude', ['--version'])) {
+            return { target, ok: true, already: true };
+        }
+        if (skipInstall) {
+            return { target, ok: false, message: 'claude not found on PATH' };
+        }
+        if (process.platform === 'win32') {
+            const r = runShell('powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://claude.ai/install.ps1 | iex"');
+            return r.status === 0
+                ? { target, ok: true }
+                : { target, ok: false, message: 'Claude Code install failed' };
+        }
+        const r = runShell('curl -fsSL https://claude.ai/install.sh | bash');
+        return r.status === 0
+            ? { target, ok: true }
+            : { target, ok: false, message: 'Claude Code install failed' };
+    }
+
+    if (target === 'codex') {
+        if (commandOk('codex', ['--version'])) {
+            return { target, ok: true, already: true };
+        }
+        if (skipInstall) {
+            return { target, ok: false, message: 'codex not found on PATH' };
+        }
+        const r = runShell('npm install -g @openai/codex');
+        return r.status === 0
+            ? { target, ok: true }
+            : { target, ok: false, message: 'Codex CLI npm install failed' };
+    }
+
+    return { target, ok: true, skipped: true };
+}
+
+export function ensureIdeClisForTargets(targets, options = {}) {
+    return targets.map((t) => ensureIdeCliForTarget(t, options));
+}

package/src/utils/profiler-agent.js

@@ -0,0 +1,64 @@
+import { spawnSync } from 'node:child_process';
+
+const PREFERRED_ORDER = ['cursor', 'claude', 'codex'];
+
+function commandOk(cmd, args = ['--version']) {
+    const r = spawnSync(cmd, args, { stdio: 'ignore' });
+    return r.status === 0;
+}
+
+export function buildProfilerAgentPrompt(projectName) {
+    const p = String(projectName || '').trim() || '<SRAI_PROJECT_NAME>';
+    return [
+        'Security Review Kit: run guardrails initialization profiling for this workspace.',
+        `SRAI project name: "${p}".`,
+        'Open and follow every step in .securityreview-kit/guardrails-profiler/SKILL.md.',
+        'Use .securityreview-kit/guardrails-profiler/references/signal-registry.json as the signal registry.',
+        'Write .guardrails/profile.json and profile.json at the repository root as defined in the skill.',
+        `Resolve project_id with find_project_by_name for "${p}", then call update_vibe_profile and write_default_pack via security-review-mcp.`,
+        'Do not invent stack details, compliance, or user groups; ground everything in the repository.',
+    ].join('\n');
+}
+
+export function pickProfilerAgentTarget(targets) {
+    for (const t of PREFERRED_ORDER) {
+        if (targets.includes(t)) {
+            return t;
+        }
+    }
+    return null;
+}
+
+/**
+ * Spawn the IDE agent CLI to execute the profiler skill (user must be logged in where required).
+ */
+export function runProfilerAgent(cwd, { target, projectName }) {
+    const prompt = buildProfilerAgentPrompt(projectName);
+    const opts = { cwd, stdio: 'inherit', env: { ...process.env } };
+
+    if (target === 'cursor') {
+        if (!commandOk('cursor-agent', ['--version'])) {
+            return { ok: false, message: 'cursor-agent not on PATH' };
+        }
+        const r = spawnSync('cursor-agent', ['-p', prompt], opts);
+        return { ok: r.status === 0, status: r.status };
+    }
+
+    if (target === 'claude') {
+        if (!commandOk('claude', ['--version'])) {
+            return { ok: false, message: 'claude not on PATH' };
+        }
+        const r = spawnSync('claude', ['-p', prompt], opts);
+        return { ok: r.status === 0, status: r.status };
+    }
+
+    if (target === 'codex') {
+        if (!commandOk('codex', ['--version'])) {
+            return { ok: false, message: 'codex not on PATH' };
+        }
+        const r = spawnSync('codex', ['exec', prompt], opts);
+        return { ok: r.status === 0, status: r.status };
+    }
+
+    return { ok: false, message: 'unsupported agent target' };
+}