@securityreviewai/securityreview-kit 0.1.11

package/src/generators/rules/ctm_sync.md

@@ -0,0 +1,33 @@
+---
+name: ctm_sync
+description: Command/workflow triggered whenever a threat model is generated or updated. Builds and uploads CTM sync details through security-review-mcp.
+---
+
+# CTM Sync Workflow
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+When invoked:
+
+0. Verify `create_ai_ide_event` tool exists in `security-review-mcp`
+1. Read the parent agent context and extract the latest threat model details.
+2. Build a JSON payload with these exact keys:
+   - `workflow_id`
+   - `title`
+   - `summary`
+   - `developer_name` = fetch from git config unless explicity specified by user
+   - `developer_email` = fetch from git config unless explicity specified by user
+   - `threats_mitigated`
+   - `best_practises_achieved`
+   - `secure_code_snippets`
+3. Resolve the configured SRAI project:
+   - Call `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"`.
+   - If missing, call `list_projects`, then `create_project` if needed.
+4. Upload the payload using `security-review-mcp`:
+   - Use the tool `create_ai_ide_event`
+
+## Output Contract
+
+- Never skip upload when a threat model exists.
+- Never invent missing values; use empty strings/arrays if data is unavailable.
+- Return a compact confirmation after upload.

package/src/generators/rules/ctm_sync_rule.md

@@ -0,0 +1,78 @@
+---
+description: ctm_sync agent trigger rule
+alwaysApply: true
+---
+# Continuous Threat Modeling Sync (`ctm_sync`)
+
+**Always synchronize threat models after they are (re)generated.**
+
+Any time an AI agent:
+- generates a **new threat model**, or  
+- **updates** an existing threat model, or  
+- performs a **non-trivial extension** of an existing threat model (e.g., adds new threat scenarios, countermeasures, data flows, or components),
+
+it **must immediately call** the `ctm_sync` agent to synchronize the latest threat modeling state.
+
+This rule applies regardless of:
+- which methodology is used (PWNISMS, STRIDE, OWASP, etc.),
+- which skill or MCP was used to produce the threat model, and
+- whether the threat model is partial, incremental, or “draft” form.
+
+If in doubt — **assume this rule applies**.
+
+---
+
+## When this rule applies
+
+This rule is **triggered** whenever the assistant:
+
+- **Produces a threat model** in any form, such as:
+  - Threat scenarios (even a short list)
+  - Data flow diagrams or component diagrams described in text
+  - Security objectives or misuse cases
+  - Attack trees or abuse cases
+  - Structured PWNISMS analysis
+- **Extends or refines** an earlier threat model, e.g.:
+  - “Add more threats for the Payments service”
+  - “Update the data flow for the auth system”
+  - “Refine the mitigations for threat X”
+
+This includes both:
+- Threat modeling done **directly in this conversation**, and  
+- Threat modeling done by calling **MCP tools or skills** that output threat scenarios, countermeasures, data dictionaries, or other CTM artifacts.
+
+---
+
+## Required behavior
+
+**After completing any threat modeling step that produces or modifies threat content, the assistant must:**
+
+1. **Ensure threat modeling output is finalized for this step**
+
+   - The assistant should finish producing the current threat modeling content (threat scenarios, components, data dictionaries, etc.) in the user-visible message or via tools.
+   - The assistant should not call `ctm_sync` *before* the threat model content exists; it must be called **after** threat data for this step is available.
+
+2. **Immediately call the `ctm_sync` agent**
+
+   - Use the `Task` tool (or equivalent agent launcher) with `subagent_type="ctm_sync"`.
+   - Provide a clear, concise description in the `description`/`prompt` fields explaining:
+     - What system or component the threat model covers
+     - Whether this is a new threat model or an update
+     - Where the latest threat content can be found (e.g., “from this conversation” or “from the last threat modeling step”)
+
+   **Example invocation (conceptual, not literal code):**
+
+   Use Task tool with:
+   - subagent_type: "ctm_sync"
+   - description: "Sync latest threat model for <system/component>"
+   - prompt: Brief summary of what was threat-modeled, what artifacts were produced (threat scenarios, countermeasures, components, data dictionary, etc.), and that the agent should upload/update CTM data accordingly.
+   - readonly: false (it must be allowed to write/update CTM data)
+
+3. Let `ctm_sync` complete its work
+    The assistant should wait for the ctm_sync agent to complete (or reach a healthy steady state) before declaring the threat-modeling step fully done.
+    If ctm_sync returns errors that can be reasonably fixed (e.g., missing project name), the assistant should fix the issue and retry once, if possible.
+
+Acknowledge completion to the user
+After ctm_sync completes, the assistant should briefly tell the user that:
+Threat modeling is finished for this step, and
+The results have been synchronized via ctm_sync (without leaking internal tooling details beyond what is appropriate for the user’s context).

package/src/generators/rules/cursor.js

@@ -0,0 +1,84 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeText } from '../../utils/fs-helpers.js';
+import {
+    getRuleContent,
+    getProfileCommandContent,
+    getCtmSyncWorkflowContent,
+    getCtmSyncTriggerRuleContent,
+    getCreateIdeWorkflowCommandContent,
+    getThreatModellingSkillContent,
+    getHooksContent,
+} from './content.js';
+
+function writeCursorRule(filePath, description, content) {
+    const action = existsSync(filePath) ? 'updated' : 'created';
+    const mdc = `---
+description: ${description}
+alwaysApply: true
+---
+
+${content}
+`;
+
+    writeText(filePath, mdc);
+    return { filePath, action };
+}
+
+function writeCursorCommand(filePath, content) {
+    const action = existsSync(filePath) ? 'updated' : 'created';
+    writeText(filePath, content);
+    return { filePath, action };
+}
+
+/**
+ * Generate Cursor workspace rules at .cursor/rules/*.mdc
+ * Cursor uses .mdc format with YAML front matter.
+ */
+export function generate(cwd, options = {}) {
+    const baseRulePath = join(cwd, '.cursor', 'rules', 'srai-security-review.mdc');
+    const ctmSyncTriggerRulePath = join(cwd, '.cursor', 'rules', 'ctm_sync_rule.mdc');
+    const ctmSyncWorkflowPath = join(cwd, '.cursor', 'commands', 'ctm_sync.md');
+    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 skillPath = join(cwd, '.cursor', 'skills', 'threat-modelling', 'SKILL.md');
+    const hooksPath = join(cwd, '.cursor', 'hooks.json');
+
+    const baseRuleContent = getRuleContent(options);
+    const ctmSyncTriggerRuleContent = getCtmSyncTriggerRuleContent(options);
+    const ctmSyncWorkflowContent = getCtmSyncWorkflowContent(options);
+    const createIdeWorkflowCommandContent = getCreateIdeWorkflowCommandContent(options);
+    const profileCommandContent = getProfileCommandContent(options);
+    const skillContent = getThreatModellingSkillContent(options);
+
+    const baseRule = writeCursorRule(
+        baseRulePath,
+        'SRAI Security Review gate — consult security-review-mcp before security-relevant code changes',
+        baseRuleContent,
+    );
+
+    const ctmSyncTriggerRule = writeCursorCommand(ctmSyncTriggerRulePath, ctmSyncTriggerRuleContent);
+    const ctmSyncWorkflow = writeCursorCommand(ctmSyncWorkflowPath, ctmSyncWorkflowContent);
+    const ctmSyncAgent = writeCursorCommand(ctmSyncAgentPath, ctmSyncWorkflowContent);
+    const createIdeWorkflowCommand = writeCursorCommand(createIdeWorkflowCommandPath, createIdeWorkflowCommandContent);
+
+    const profileCommand = writeCursorCommand(profileCommandPath, profileCommandContent);
+    const skillAction = existsSync(skillPath) ? 'updated' : 'created';
+    writeText(skillPath, skillContent);
+
+    const hooksContent = getHooksContent();
+    const hooksAction = existsSync(hooksPath) ? 'updated' : 'created';
+    writeText(hooksPath, hooksContent);
+
+    return [
+        { ...baseRule, kind: 'rule' },
+        { ...ctmSyncTriggerRule, kind: 'rule' },
+        { ...ctmSyncWorkflow, kind: 'command' },
+        { ...ctmSyncAgent, kind: 'agent' },
+        { ...createIdeWorkflowCommand, kind: 'command' },
+        { ...profileCommand, kind: 'command' },
+        { filePath: skillPath, action: skillAction, kind: 'skill' },
+        { filePath: hooksPath, action: hooksAction, kind: 'hooks' },
+    ];
+}

package/src/generators/rules/gemini.js

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+import { upsertSentinelBlock } from '../../utils/fs-helpers.js';
+import { getRuleContent } from './content.js';
+
+/**
+ * Generate Gemini CLI / Antigravity workspace rule — appends to GEMINI.md
+ */
+export function generate(cwd, options = {}) {
+    const filePath = join(cwd, 'GEMINI.md');
+    const content = getRuleContent(options);
+    const action = upsertSentinelBlock(filePath, content);
+    return { filePath, action };
+}

package/src/generators/rules/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "printf '%s\\n' '{\"additional_context\":\"## MANDATORY SECURITY GATE (Session Policy)\\n\\nFor ANY user request that has security impact (auth, crypto, input handling, secrets, network, data storage, dependencies, new APIs/endpoints, or any code handling untrusted data):\\n\\n**Plan order:**\\n1. **PWNISMS threat modeling (first)** - Run threat modeling as a guide before writing code. Use .cursor/skills/threat-modelling/SKILL.md. Document findings to inform secure implementation.\\n2. **Implement secure code** - Use the threat model findings as a guide to create secure code.\\n3. **ctm_sync (last)** - Push payload to SRAI only after implementation is done. Invoke ctm_sync agent (Task tool, subagent_type=ctm_sync) as the final step. See .cursor/commands/ctm_sync.md and .cursor/rules/ctm-trigger-rule.mdc.\\n\\nNo blocking. No deferral. Threat modeling guides the code; ctm_sync runs last to push to SRAI. the ctm_sync is mandatory , should be a part of your to-do.\"}'",
+        "timeout": 5
+      }
+    ]
+  }
+}

package/src/generators/rules/skill.md

@@ -0,0 +1,161 @@
+---
+name: PWNISMS Threat Modelling
+description: Lightweight, security-first threat modelling workflow for code and architecture tasks. Use it to walk all 7 PWNISMS categories, identify plausible threats, prioritize top risks, and propose concrete mitigations before and during implementation.
+---
+
+# PWNISMS — On-the-Go Threat Modelling
+
+For EVERY security-relevant task (feature, bug fix, refactor, infra change, architecture design), run a lightweight threat model with PWNISMS.
+
+- Walk through all 7 categories explicitly.
+- If a category is not applicable, state it briefly and move on.
+- Anchor analysis to linked files, diffs, PRs, API specs, and diagrams whenever available.
+- Focus on realistic threats for the current context, not exhaustive attack catalogs.
+
+---
+
+## Inputs to Gather First
+
+Collect these quickly before deep analysis:
+
+- **Scope**: What is changing (feature, component, service, migration, PR)?
+- **Assets**: What must be protected (PII, credentials, tokens, configs, accounts, workflows)?
+- **Entry points**: How data enters/leaves (HTTP, queues, schedulers, CLI, webhooks, integrations)?
+- **Trust boundaries**: Where data crosses users/services/networks/privilege levels?
+
+If the user provided specific code, diffs, or architecture artifacts, prioritize those as primary evidence.
+
+---
+
+## Lightweight Workflow (PWNISMS)
+
+1. **Clarify scope and assumptions**
+   - Define the exact unit of analysis.
+   - State assumptions explicitly (auth model, deployment boundary, tenant model, etc.).
+2. **Map assets and flows**
+   - List high-value assets and critical data paths.
+   - List entry points and exits across trust boundaries.
+3. **Walk all 7 PWNISMS categories**
+   - Identify plausible threats for each category.
+   - Keep findings concrete and contextual.
+4. **Prioritize**
+   - Select the top 3-7 risks by impact and likelihood.
+5. **Mitigate**
+   - Propose concrete, implementable controls for each prioritized risk.
+6. **Summarize residual risk**
+   - Call out remaining risk, trade-offs, and follow-up actions.
+   - Call out unknowns instead of silently guessing.
+
+---
+
+## The 7 Categories (What to Check)
+
+### P — Product
+
+Application and business-logic threats:
+
+- Input validation, injection, insecure deserialization.
+- Authorization gaps, privilege escalation, IDOR/BOLA.
+- Business logic abuse, replay/race conditions, unsafe redirects.
+- Error handling that leaks internals.
+
+### W — Workload
+
+Compute and infrastructure threats:
+
+- Insecure container/runtime posture, over-privileged workload identity.
+- Weak host/orchestrator controls and segmentation.
+- Insecure data storage/backups and DB configuration.
+- Queue/broker abuse and poison-message handling gaps.
+
+### N — Network
+
+Network and transport threats:
+
+- Missing/weak TLS, insecure service-to-service communication.
+- Exposed ports/endpoints and permissive ingress/egress.
+- Weak segmentation or lateral movement paths.
+- API-layer abuse controls missing (rate limits, request limits, CORS hardening).
+
+### I — IAM (Identity & Access Management)
+
+Identity and authorization threats:
+
+- Broken authentication controls and token validation.
+- Missing least-privilege RBAC/ABAC.
+- Service-to-service auth gaps.
+- Escalation paths across users, roles, or services.
+
+### S — Secrets
+
+Credential and key management threats:
+
+- Secrets in code, images, logs, CI output, or defaults.
+- Weak rotation, revocation, or token lifetime policies.
+- Over-shared secrets across components.
+- Missing secret manager/KMS controls.
+
+### M — Monitoring (Logging & Observability)
+
+Detection and auditability threats:
+
+- Missing logs for auth, authorization, admin/data access events.
+- Sensitive data leakage in logs.
+- Missing alerts for abuse indicators.
+- Incomplete audit trails or weak log integrity.
+
+### S — Supply Chain
+
+Dependency and delivery threats:
+
+- Unpinned/unverified dependencies and vulnerable packages.
+- Third-party integration trust and scope overreach.
+- CI/CD pipeline leakage or unreviewed build scripts.
+- Unsigned/unprovenanced artifacts, missing SBOM.
+- Treat AI-generated code as untrusted until validated.
+
+---
+
+## Tailor for Architecture / Design Tasks
+
+When discussing designs before code exists:
+
+- Sketch a mental data flow: actors, data sent/received, storage, processing points.
+- Mark trust boundaries explicitly (client-backend, backend-DB, service-service, cloud-third party).
+- Identify where strong authentication/authorization is mandatory.
+- Identify where encryption in transit and at rest is mandatory.
+- Recommend concrete security patterns:
+  - Parameterized queries / ORM for DB access.
+  - Centralized authn/authz and role checks.
+  - Secrets manager / KMS for credentials and keys.
+  - mTLS or signed requests for service-to-service calls.
+
+---
+
+## Security-First Code Generation Rules
+
+When implementing code, enforce these baseline controls:
+
+1. Validate and constrain all untrusted input.
+2. Parameterize all queries and command-like invocations.
+3. Enforce least privilege for users, services, and workloads.
+4. Never hardcode secrets; use managed secret stores.
+5. Encrypt sensitive data in transit and at rest.
+6. Log security-relevant actions without leaking secrets/PII.
+7. Pin and verify dependencies and build artifacts.
+8. Return safe user errors; keep sensitive diagnostics internal.
+9. Add abuse protections (rate limits, lockouts, throttling) on exposed interfaces.
+
+---
+
+## Post-Generation Checklist
+
+Before finalizing output, confirm:
+
+- [ ] Scope, assumptions, and trust boundaries were explicit.
+- [ ] All 7 PWNISMS categories were checked (or marked N/A explicitly).
+- [ ] Top risks were prioritized by impact and likelihood.
+- [ ] Mitigations are concrete and actionable.
+- [ ] Residual risk and follow-up actions are stated.
+
+If ANY box cannot be checked, you MUST flag the gap to the user with a specific remediation recommendation before finalizing the code.

package/src/generators/rules/srai-profile.md

@@ -0,0 +1,32 @@
+---
+name: srai-profile
+description: Create and upload a SecurityReviewAI code profile using security-review-mcp
+---
+
+# SRAI Profile Uploader
+
+Create a code profile from the current request and upload it to SRAI using `security-review-mcp`.
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+## Steps
+
+1. Determine scope from the user prompt.
+   - If the request is about a specific capability/module/endpoint, produce a **Feature Code Profile**.
+   - If the request is broad, exploratory, or architecture-level, produce a **Codebase Code Profile**.
+2. Build detailed profile content before any upload call.
+   - Include purpose, boundaries, entry points, sensitive data, trust boundaries, integrations, threats, controls, and open risks.
+3. Resolve the SRAI project.
+   - Use the configured project name by default; if it is missing or ambiguous, ask the user to confirm it.
+   - Call `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"`.
+   - If missing, call `list_projects`; if still missing, call `create_project` with `name="<SRAI_PROJECT_NAME>"`.
+4. Upload generated markdown content with tool 11: `upload_document`.
+   - Use this for raw markdown/text generated in the chat.
+   - Use a clear document name such as `feature-code-profile-<feature>.md` or `codebase-code-profile-<repo>.md`.
+5. Upload files/diagrams with tool 10: `upload_document` when needed.
+   - Provide base64 file content and file name.
+   - Set `document_type` to `Component Diagram` for architecture diagrams.
+   - Set `document_type` to `Uploaded Knowledgebase doc` for other document uploads.
+6. Confirm the result.
+   - Report project name, upload tool used, document name, and that processing is asynchronous.
+   - If upload fails, return exact error details and next retry step.

package/src/generators/rules/vscode.js

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+import { upsertSentinelBlock } from '../../utils/fs-helpers.js';
+import { getRuleContent } from './content.js';
+
+/**
+ * Generate VS Code Copilot instructions — appends to .github/copilot-instructions.md
+ */
+export function generate(cwd, options = {}) {
+    const filePath = join(cwd, '.github', 'copilot-instructions.md');
+    const content = getRuleContent(options);
+    const action = upsertSentinelBlock(filePath, content);
+    return { filePath, action };
+}

package/src/generators/rules/windsurf.js

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+import { writeText } from '../../utils/fs-helpers.js';
+import { getRuleContent } from './content.js';
+
+/**
+ * Generate Windsurf workspace rule at .windsurf/rules/srai-security-review.md
+ */
+export function generate(cwd, options = {}) {
+    const filePath = join(cwd, '.windsurf', 'rules', 'srai-security-review.md');
+    const content = getRuleContent(options);
+    writeText(filePath, content + '\n');
+    return filePath;
+}

package/src/utils/constants.js

@@ -0,0 +1,63 @@
+// Shared constants for securityreview-kit
+
+export const MCP_SERVER_PACKAGE = 'security-review-mcp';
+export const MCP_SERVER_NAME = 'security-review-mcp';
+
+export const ENV_VARS = {
+    apiUrl: 'SECURITY_REVIEW_API_URL',
+    apiToken: 'SECURITY_REVIEW_API_TOKEN',
+};
+
+export const TARGETS = {
+    cursor: {
+        name: 'Cursor',
+        mcpConfigPath: '.cursor/mcp.json',
+        rulePath: '.cursor/rules/srai-security-review.mdc',
+        detectDirs: ['.cursor'],
+    },
+    claude: {
+        name: 'Claude Code',
+        mcpConfigPath: '.claude/settings.json',
+        rulePath: 'CLAUDE.md',
+        ruleMode: 'append',
+        detectDirs: ['.claude'],
+    },
+    vscode: {
+        name: 'VS Code Copilot',
+        mcpConfigPath: '.vscode/mcp.json',
+        rulePath: '.github/copilot-instructions.md',
+        ruleMode: 'append',
+        detectDirs: ['.vscode'],
+    },
+    windsurf: {
+        name: 'Windsurf',
+        mcpConfigPath: '.windsurf/mcp_config.json',
+        rulePath: '.windsurf/rules/srai-security-review.md',
+        detectDirs: ['.windsurf'],
+    },
+    codex: {
+        name: 'Codex',
+        mcpConfigPath: '.codex/config.toml',
+        rulePath: 'AGENTS.md',
+        ruleMode: 'append',
+        detectDirs: ['.codex'],
+    },
+    gemini: {
+        name: 'Gemini CLI',
+        mcpConfigPath: '.gemini/settings.json',
+        rulePath: 'GEMINI.md',
+        ruleMode: 'append',
+        detectDirs: ['.gemini'],
+    },
+    antigravity: {
+        name: 'Antigravity',
+        mcpConfigPath: '.gemini/settings.json',
+        rulePath: '.agent/rules/srai-security-review.md',
+        detectDirs: ['.agent'],
+    },
+};
+
+export const TARGET_NAMES = Object.keys(TARGETS);
+
+export const SENTINEL_START = '<!-- securityreview-kit:start -->';
+export const SENTINEL_END = '<!-- securityreview-kit:end -->';

package/src/utils/detect.js

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { TARGETS, TARGET_NAMES } from './constants.js';
+
+/**
+ * Auto-detect which IDE/CLI targets are configured in the given directory
+ * by checking for known directories.
+ * @param {string} cwd - The directory to scan
+ * @returns {string[]} - List of detected target keys
+ */
+export function detectTargets(cwd) {
+    const detected = [];
+    const seen = new Set();
+
+    for (const key of TARGET_NAMES) {
+        const target = TARGETS[key];
+        for (const dir of target.detectDirs) {
+            const fullPath = join(cwd, dir);
+            if (existsSync(fullPath) && !seen.has(key)) {
+                detected.push(key);
+                seen.add(key);
+            }
+        }
+    }
+
+    return detected;
+}

package/src/utils/fs-helpers.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { SENTINEL_START, SENTINEL_END } from './constants.js';
+
+/**
+ * Ensure a directory exists, creating parent dirs as needed.
+ */
+export function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+}
+
+/**
+ * Read a JSON file, returning null if it doesn't exist or is invalid.
+ */
+export function readJson(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Write an object as pretty-printed JSON.
+ */
+export function writeJson(filePath, data) {
+    ensureDir(dirname(filePath));
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Read a text file, returning empty string if it doesn't exist.
+ */
+export function readText(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    } catch {
+        return '';
+    }
+}
+
+/**
+ * Write raw text to a file, ensuring parent dirs exist.
+ */
+export function writeText(filePath, content) {
+    ensureDir(dirname(filePath));
+    writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Append or replace a sentinel-guarded block in a file.
+ * If the file exists and already has the block, it replaces it.
+ * If the file exists but doesn't have the block, it appends.
+ * If the file doesn't exist, it creates it with just the block.
+ */
+export function upsertSentinelBlock(filePath, content) {
+    const block = `${SENTINEL_START}\n${content}\n${SENTINEL_END}`;
+    const existing = readText(filePath);
+
+    if (!existing) {
+        writeText(filePath, block + '\n');
+        return 'created';
+    }
+
+    const startIdx = existing.indexOf(SENTINEL_START);
+    const endIdx = existing.indexOf(SENTINEL_END);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+        const before = existing.substring(0, startIdx);
+        const after = existing.substring(endIdx + SENTINEL_END.length);
+        writeText(filePath, before + block + after);
+        return 'updated';
+    }
+
+    // Append with a blank line separator
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    writeText(filePath, existing + separator + block + '\n');
+    return 'appended';
+}