@dashclaw/cli 0.2.0 → 0.3.2

package/lib/api.js

@@ -0,0 +1,64 @@
+/**
+ * Tiny direct-API helper for the DashClaw CLI.
+ *
+ * The CLI imports `DashClaw` from the PUBLISHED npm package, whose installed
+ * version can LAG this repo and lack newly-added SDK methods. Commands that
+ * call brand-new endpoints therefore go through this helper instead — a clean
+ * `fetch` with the `x-api-key` header against the already-resolved
+ * baseUrl/apiKey. No dependency on unreleased SDK methods.
+ *
+ * Error semantics mirror sdk/dashclaw.js `_request`: parse JSON defensively
+ * (fall back to {} on a non-JSON gateway/error body so the real status isn't
+ * lost), and throw a status-bearing Error on a non-ok response.
+ *
+ * Node 20 global `fetch` — no imports needed.
+ *
+ * @param {{ baseUrl: string, apiKey: string }} config
+ * @param {string} method
+ * @param {string} path
+ * @param {{ body?: any, query?: Record<string, any> }} [opts]
+ * @returns {Promise<any>}
+ */
+export async function apiRequest({ baseUrl, apiKey }, method, path, { body, query } = {}) {
+  let url = `${baseUrl}${path}`;
+  if (query) {
+    // Skip undefined/null values. Passing them straight into URLSearchParams
+    // serializes the literal strings "undefined"/"null", which routes treat as
+    // real filter values and match zero rows. Falsy-but-valid values (0, false,
+    // '') are preserved.
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) qs.append(key, String(value));
+    }
+    const s = qs.toString();
+    if (s) url += `?${s}`;
+  }
+
+  const res = await fetch(url, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  // Parse the body defensively. A non-JSON error body (a Vercel 502/504/413
+  // gateway page, a 429 rate-limit page) makes res.json() reject with a
+  // SyntaxError, which would propagate instead of the status-bearing error
+  // below and lose res.status. Fall back to {} so the real status is thrown.
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    data = {};
+  }
+
+  if (!res.ok) {
+    const err = new Error(data.error || `Request failed with status ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+
+  return data;
+}

package/lib/claude/install.js

@@ -0,0 +1,386 @@
+// cli/lib/claude/install.js
+//
+// `dashclaw install claude [--trial]` — provisions DashClaw governance into
+// Claude Code without cloning the repo.
+//
+// Flow (ordering matters — nothing is written until the preflight passes, so
+// a failed install never leaves a half-written config):
+//   1. Resolve endpoint + API key: flags → env → (--trial: open the hosted
+//      signup page in a browser and accept the pasted key — Turnstile cannot
+//      be driven headlessly) → interactive prompts.
+//   2. Preflight: GET /api/health (reachability) and an authenticated read
+//      (key validity). Failure exits non-zero with an actionable message.
+//   3. Acquire the hook scripts: copied from a repo checkout when the CLI is
+//      running inside one, otherwise downloaded from the instance's own
+//      /downloads/dashclaw-claude-code-hooks.zip bundle (version-matched).
+//   4. Resolve the Python command (python3, then python) and write the hook
+//      entries into ~/.claude/settings.json (managed entries, replaced on
+//      re-install; backup created once).
+//   5. Write hook credentials to <hooksDir>/.env (mode 600 — the hooks load
+//      .env beside the script, so no secret lands in ~/.claude/settings.json)
+//      with HOOK_MODE=observe by default, and save ~/.dashclaw/config.json
+//      for the CLI itself.
+//   6. Print next steps (flip to enforce, dashboard URL).
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  copyFileSync,
+  readdirSync,
+  statSync,
+  rmSync,
+  cpSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { readConfigFile, writeConfigFile } from '../config.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const HOOK_FILES = [
+  'dashclaw_pretool.py',
+  'dashclaw_posttool.py',
+  'dashclaw_stop.py',
+  'dashclaw_code_session_reporter.py',
+];
+const HOOK_INTEL_DIR = 'dashclaw_agent_intel';
+const HOOKS_BUNDLE_PATH = '/downloads/dashclaw-claude-code-hooks.zip';
+
+export const DEFAULT_AGENT_ID = 'claude-code';
+
+// ---------------------------------------------------------------------------
+// Python resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a working Python command: python3 first, then python. The Windows
+ * Store `python3` alias exits non-zero without running anything, so we
+ * require a successful `--version`, not just spawnability.
+ * @param {(cmd: string, args: string[]) => {error?: Error, status?: number}} probe
+ */
+export function resolvePythonCommand(probe = (cmd, args) => spawnSync(cmd, args, { stdio: 'ignore' })) {
+  for (const cmd of ['python3', 'python']) {
+    const result = probe(cmd, ['--version']);
+    if (!result.error && result.status === 0) return cmd;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Preflight
+// ---------------------------------------------------------------------------
+
+export async function preflight(endpoint, apiKey, { fetchImpl = fetch } = {}) {
+  let health;
+  try {
+    health = await fetchImpl(`${endpoint}/api/health`, { signal: AbortSignal.timeout(8000) });
+  } catch (err) {
+    throw new Error(
+      `Could not reach ${endpoint}/api/health (${err.cause?.code || err.name}). ` +
+      'Check the URL, that the instance is running, and your network.',
+    );
+  }
+  if (!health.ok) {
+    throw new Error(`${endpoint}/api/health returned HTTP ${health.status} — the instance is unhealthy.`);
+  }
+
+  const authed = await fetchImpl(`${endpoint}/api/actions?limit=1`, {
+    headers: { 'x-api-key': apiKey },
+    signal: AbortSignal.timeout(8000),
+  }).catch((err) => {
+    throw new Error(`Authenticated preflight to ${endpoint} failed (${err.name}).`);
+  });
+  if (authed.status === 401 || authed.status === 403) {
+    throw new Error('API key was rejected (401/403). Paste the key exactly as issued (oc_live_...).');
+  }
+  if (!authed.ok) {
+    throw new Error(`Authenticated preflight returned HTTP ${authed.status} — expected 200.`);
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Hook acquisition
+// ---------------------------------------------------------------------------
+
+/** Repo checkout containing hooks/, when the CLI runs from inside one. */
+export function findRepoHooksDir() {
+  const candidate = resolve(__dirname, '..', '..', '..', 'hooks');
+  return existsSync(join(candidate, 'dashclaw_pretool.py')) ? candidate : null;
+}
+
+function copyDirRecursive(src, dst) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === '__pycache__') continue;
+    const sp = join(src, entry.name);
+    const dp = join(dst, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(sp, dp);
+    else if (entry.isFile()) copyFileSync(sp, dp);
+  }
+}
+
+function copyHooksFromRepo(hooksSrc, hooksDst) {
+  mkdirSync(hooksDst, { recursive: true });
+  for (const name of [...HOOK_FILES, 'run_hook.cjs']) {
+    const sp = join(hooksSrc, name);
+    if (!existsSync(sp)) throw new Error(`Required hook script missing: ${sp}`);
+    copyFileSync(sp, join(hooksDst, name));
+  }
+  const intelSrc = join(hooksSrc, HOOK_INTEL_DIR);
+  if (!existsSync(intelSrc) || !statSync(intelSrc).isDirectory()) {
+    throw new Error(`Required intel module missing: ${intelSrc}`);
+  }
+  copyDirRecursive(intelSrc, join(hooksDst, HOOK_INTEL_DIR));
+}
+
+function extractZip(zipPath, destDir) {
+  // tar on Windows 10+ and macOS is bsdtar (handles zip); GNU tar on most
+  // Linux does not, so try unzip there first. Whatever works first wins.
+  const attempts = process.platform === 'linux'
+    ? [['unzip', ['-o', zipPath, '-d', destDir]], ['tar', ['-xf', zipPath, '-C', destDir]]]
+    : [['tar', ['-xf', zipPath, '-C', destDir]], ['unzip', ['-o', zipPath, '-d', destDir]]];
+  for (const [cmd, args] of attempts) {
+    const result = spawnSync(cmd, args, { stdio: 'ignore' });
+    if (!result.error && result.status === 0) return true;
+  }
+  throw new Error(
+    'Could not extract the hooks bundle (need `tar` with zip support or `unzip` on PATH). ' +
+    'Alternative: clone https://github.com/ucsandman/DashClaw and re-run from the checkout.',
+  );
+}
+
+async function downloadHooksBundle(endpoint, hooksDst, { fetchImpl = fetch } = {}) {
+  const res = await fetchImpl(`${endpoint}${HOOKS_BUNDLE_PATH}`, { signal: AbortSignal.timeout(30_000) });
+  if (!res.ok) {
+    throw new Error(`Hook bundle download failed (HTTP ${res.status} from ${HOOKS_BUNDLE_PATH}).`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const workDir = join(tmpdir(), `dashclaw-hooks-${Date.now()}`);
+  mkdirSync(workDir, { recursive: true });
+  try {
+    const zipPath = join(workDir, 'hooks.zip');
+    writeFileSync(zipPath, buf);
+    extractZip(zipPath, workDir);
+    const extracted = join(workDir, 'hooks');
+    if (!existsSync(join(extracted, 'dashclaw_pretool.py'))) {
+      throw new Error('Hook bundle had an unexpected layout (no hooks/dashclaw_pretool.py).');
+    }
+    mkdirSync(hooksDst, { recursive: true });
+    cpSync(extracted, hooksDst, { recursive: true });
+  } finally {
+    rmSync(workDir, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code settings.json merge
+// ---------------------------------------------------------------------------
+
+const HOOK_EVENTS = {
+  PreToolUse: { matcher: 'Agent|Task|Bash|Edit|Write|MultiEdit|Skill|mcp__.*', script: 'dashclaw_pretool.py', timeout: 3600000 },
+  PostToolUse: { matcher: 'Agent|Task|Bash|Edit|Write|MultiEdit|mcp__.*', script: 'dashclaw_posttool.py' },
+  Stop: { script: 'dashclaw_stop.py' },
+};
+
+export function isManagedHookEntry(entry) {
+  return (entry?.hooks || []).some((h) => typeof h?.command === 'string' && h.command.includes('dashclaw_'));
+}
+
+/** Build the managed hook entries pointing at <hooksDir> via <python>. */
+export function buildHookEntries(hooksDir, python) {
+  const entries = {};
+  for (const [event, spec] of Object.entries(HOOK_EVENTS)) {
+    const hook = {
+      type: 'command',
+      command: `${python} "${join(hooksDir, spec.script)}"`,
+      ...(spec.timeout ? { timeout: spec.timeout } : {}),
+    };
+    entries[event] = [{ ...(spec.matcher ? { matcher: spec.matcher } : {}), hooks: [hook] }];
+  }
+  return entries;
+}
+
+/**
+ * Merge the managed hook entries into a Claude Code settings.json file:
+ * previous dashclaw-managed entries are replaced, everything else preserved.
+ */
+export function mergeClaudeSettings(settingsPath, hooksDir, python) {
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch {
+      throw new Error(`${settingsPath} is not valid JSON — fix or remove it, then re-run.`);
+    }
+    const bak = settingsPath + '.dashclaw-bak';
+    if (!existsSync(bak)) copyFileSync(settingsPath, bak);
+  }
+  settings.hooks = settings.hooks || {};
+  const managed = buildHookEntries(hooksDir, python);
+  for (const [event, entries] of Object.entries(managed)) {
+    const existing = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    settings.hooks[event] = [...existing.filter((e) => !isManagedHookEntry(e)), ...entries];
+  }
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return settings;
+}
+
+// ---------------------------------------------------------------------------
+// Hook credentials (.env beside the scripts — never in settings.json)
+// ---------------------------------------------------------------------------
+
+export function buildHookEnv({ endpoint, apiKey, agentId, hookMode = 'observe' }) {
+  return [
+    '# Written by `dashclaw install claude` — credentials for the governance hooks.',
+    '# The hooks load this file from beside their scripts; env vars override it.',
+    `DASHCLAW_BASE_URL=${endpoint}`,
+    `DASHCLAW_API_KEY=${apiKey}`,
+    `DASHCLAW_AGENT_ID=${agentId}`,
+    `DASHCLAW_HOOK_MODE=${hookMode}`,
+    '',
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Top-level install
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.endpoint]  Instance URL (flag/env resolved by caller)
+ * @param {string} [opts.apiKey]
+ * @param {string} [opts.agentId]
+ * @param {boolean} [opts.trial]
+ * @param {string} [opts.homeDir]   Injectable for tests
+ * @param {Function} [opts.fetchImpl]
+ * @param {Function} [opts.pythonProbe]   Injected probe for resolvePythonCommand
+ * @param {Function} [opts.prompt]        (question) => Promise<string>
+ * @param {Function} [opts.promptSecret]  (question) => Promise<string>
+ * @param {Function} [opts.openUrl]       Best-effort browser open
+ * @param {object} [opts.logger]
+ */
+export async function installClaude({
+  endpoint,
+  apiKey,
+  agentId = DEFAULT_AGENT_ID,
+  trial = false,
+  homeDir = homedir(),
+  env = process.env,
+  fetchImpl = fetch,
+  pythonProbe,
+  prompt,
+  promptSecret,
+  openUrl = defaultOpenUrl,
+  logger = console,
+} = {}) {
+  // 1. Resolve endpoint + key -------------------------------------------------
+  endpoint = (endpoint || env.DASHCLAW_BASE_URL || '').replace(/\/+$/, '');
+  apiKey = apiKey || env.DASHCLAW_API_KEY || '';
+
+  if (trial && !apiKey) {
+    const hostedBase = (endpoint || env.DASHCLAW_HOSTED_URL || '').replace(/\/+$/, '')
+      || (await mustPrompt(prompt, 'Hosted DashClaw URL (where you signed up / will sign up): '));
+    const signupUrl = `${hostedBase.replace(/\/+$/, '')}/connect`;
+    logger.log('');
+    logger.log(`  Opening the trial signup page: ${signupUrl}`);
+    logger.log('  Sign in there, copy your trial API key, and paste it below.');
+    openUrl(signupUrl);
+    endpoint = endpoint || hostedBase.replace(/\/+$/, '');
+    apiKey = await mustPrompt(promptSecret || prompt, 'Paste your trial API key (oc_live_...): ');
+  }
+
+  if (!endpoint) endpoint = await mustPrompt(prompt, 'DashClaw instance URL (e.g. https://your-dashclaw.vercel.app): ');
+  endpoint = endpoint.replace(/\/+$/, '');
+  if (!apiKey) apiKey = await mustPrompt(promptSecret || prompt, 'API key (oc_live_...): ');
+
+  // 2. Preflight (nothing is written before this passes) ----------------------
+  logger.log(`  Preflight: ${endpoint}/api/health ...`);
+  await preflight(endpoint, apiKey, { fetchImpl });
+  logger.log('  Preflight OK — instance reachable, key accepted.');
+
+  // 3. Hooks ------------------------------------------------------------------
+  const hooksDir = join(homeDir, '.dashclaw', 'claude-hooks');
+  const repoHooks = findRepoHooksDir();
+  if (repoHooks) {
+    logger.log(`  Installing hooks from repo checkout → ${hooksDir}`);
+    copyHooksFromRepo(repoHooks, hooksDir);
+  } else {
+    logger.log(`  Downloading hooks bundle from ${endpoint} → ${hooksDir}`);
+    await downloadHooksBundle(endpoint, hooksDir, { fetchImpl });
+  }
+
+  // 4. Python + Claude Code settings -------------------------------------------
+  const python = resolvePythonCommand(pythonProbe);
+  if (!python) {
+    throw new Error('No python3 or python found on PATH. Install Python 3.10+ and re-run.');
+  }
+  const settingsPath = join(homeDir, '.claude', 'settings.json');
+  logger.log(`  Wiring hooks into ${settingsPath} (python: ${python})`);
+  mergeClaudeSettings(settingsPath, hooksDir, python);
+
+  // 5. Credentials -------------------------------------------------------------
+  const hookEnvPath = join(hooksDir, '.env');
+  writeFileSync(hookEnvPath, buildHookEnv({ endpoint, apiKey, agentId }), { mode: 0o600 });
+  const existing = readConfigForHome(homeDir);
+  writeConfigForHome(homeDir, { ...existing, baseUrl: endpoint, apiKey, agentId });
+
+  // 6. Next steps ---------------------------------------------------------------
+  logger.log('');
+  logger.log('  Done. Claude Code is governed by DashClaw (observe mode).');
+  logger.log(`  Hooks:     ${hooksDir}`);
+  logger.log(`  Settings:  ${settingsPath}`);
+  logger.log(`  Config:    ${join(homeDir, '.dashclaw', 'config.json')}`);
+  logger.log('');
+  logger.log('  Next steps:');
+  logger.log('  1. Restart Claude Code (hooks load at session start).');
+  logger.log('  2. Run any tool call and watch it appear in your dashboard:');
+  logger.log(`     ${endpoint}/mission-control`);
+  logger.log(`  3. Observe mode logs decisions without blocking. To enforce, set`);
+  logger.log(`     DASHCLAW_HOOK_MODE=enforce in ${hookEnvPath}`);
+
+  return { hooksDir, settingsPath, hookEnvPath, python, endpoint, agentId, hookMode: 'observe' };
+}
+
+async function mustPrompt(promptFn, question) {
+  if (!promptFn) {
+    throw new Error(`Missing required value (${question.trim()}) and no interactive prompt available.`);
+  }
+  const answer = (await promptFn(question)).trim();
+  if (!answer) throw new Error('Aborted — a value is required.');
+  return answer;
+}
+
+function defaultOpenUrl(url) {
+  try {
+    if (process.platform === 'win32') spawnSync('cmd', ['/c', 'start', '', url], { stdio: 'ignore' });
+    else if (process.platform === 'darwin') spawnSync('open', [url], { stdio: 'ignore' });
+    else spawnSync('xdg-open', [url], { stdio: 'ignore' });
+  } catch {
+    // best-effort — the URL is printed either way
+  }
+}
+
+// config.js hardcodes homedir(); these wrappers honor the injectable homeDir
+// (tests) while production passes the real one and shares the same file.
+function readConfigForHome(homeDir) {
+  const path = join(homeDir, '.dashclaw', 'config.json');
+  if (homeDir === homedir()) return readConfigFile();
+  if (!existsSync(path)) return {};
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; }
+}
+
+function writeConfigForHome(homeDir, config) {
+  if (homeDir === homedir()) {
+    writeConfigFile(config);
+    return;
+  }
+  const dir = join(homeDir, '.dashclaw');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'config.json'), JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}

package/lib/code/apply.js

@@ -0,0 +1,164 @@
+// `dashclaw code apply <manifestId>` — fetch a write plan from the server
+// and apply it locally. The server emits the manifest (Phase 6) with a
+// 24h TTL. This module is the only place the CLI writes to disk for the
+// Optimal Files feature.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { _ensureInsideProject, applyMerge } from './vendored.js';
+
+const SECRET_PATTERNS = [
+  { name: 'stripe_test', re: /sk_test_[A-Za-z0-9]{8,}/g },
+  { name: 'stripe_live', re: /sk_live_[A-Za-z0-9]{8,}/g },
+  { name: 'stripe_webhook', re: /whsec_[A-Za-z0-9]{8,}/g },
+  { name: 'openai_key', re: /sk-[A-Za-z0-9]{20,}/g },
+  { name: 'anthropic_key', re: /sk-ant-[A-Za-z0-9_\-]{20,}/g },
+  { name: 'github_pat', re: /(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g },
+  { name: 'aws_access', re: /AKIA[0-9A-Z]{16}/g },
+  { name: 'jwt', re: /eyJ[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}/g },
+  { name: 'private_key', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g },
+  { name: 'env_assign', re: /\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASS|PWD|CRED|AUTH))\s*=\s*['"]?[^\s'"\n]+/g },
+];
+
+function scanForSecrets(content) {
+  let redactions = 0;
+  let out = String(content == null ? '' : content);
+  for (const p of SECRET_PATTERNS) {
+    out = out.replace(p.re, (_match, captured) => {
+      redactions++;
+      if (p.name === 'env_assign' && captured) return `${captured}=<REDACTED:${p.name}>`;
+      return `<REDACTED:${p.name}>`;
+    });
+  }
+  return { status: redactions === 0 ? 'passed' : 'redacted', redactions, redacted: out };
+}
+
+async function fetchManifest(baseUrl, apiKey, manifestId, { fetchImpl = fetch }) {
+  const url = baseUrl.replace(/\/+$/, '') + '/api/code-sessions/manifests/' + encodeURIComponent(manifestId);
+  const res = await fetchImpl(url, {
+    headers: { 'x-api-key': apiKey },
+  });
+  let body = null;
+  try { body = await res.json(); } catch { /* null */ }
+  return { status: res.status, ok: res.ok, body };
+}
+
+export async function runApply({
+  baseUrl,
+  apiKey,
+  manifestId,
+  dest,
+  yes = false,
+  allowRedactions = false,
+  allowOverwriteSideBySide = false,
+  fetchImpl = fetch,
+  logger = console,
+}) {
+  if (!manifestId) throw new Error('runApply: manifestId is required');
+  if (!dest) throw new Error('runApply: --dest=<dir> is required');
+  if (!baseUrl || !apiKey) throw new Error('runApply: baseUrl and apiKey are required');
+
+  const destAbs = path.resolve(dest);
+  try { fs.mkdirSync(destAbs, { recursive: true }); }
+  catch (err) { throw new Error('Could not create destination ' + destAbs + ': ' + err.message); }
+
+  const { status, ok, body } = await fetchManifest(baseUrl, apiKey, manifestId, { fetchImpl });
+  if (!ok) throw new Error('Failed to load manifest: HTTP ' + status + (body?.error ? ' — ' + body.error : ''));
+  const plan = Array.isArray(body?.plan) ? body.plan : Array.isArray(body?.plan?.results) ? body.plan.results : null;
+  if (!plan) throw new Error('Manifest payload missing plan');
+
+  const results = [];
+  for (const entry of plan) {
+    const target = entry.path;
+    if (!target) {
+      results.push({ path: '(unknown)', status: 'invalid_entry' });
+      continue;
+    }
+    const abs = _ensureInsideProject(destAbs, target);
+    if (!abs) {
+      results.push({ path: target, status: 'unsafe_path' });
+      logger.warn(`  ${target} -> unsafe_path (refused)`);
+      continue;
+    }
+    const content = entry.content;
+    if (typeof content !== 'string') {
+      results.push({ path: target, status: 'no_content' });
+      continue;
+    }
+    const scan = scanForSecrets(content);
+    if (scan.status === 'redacted' && !allowRedactions) {
+      results.push({ path: target, status: 'redacted', redactions: scan.redactions });
+      logger.warn(`  ${target} -> ${scan.redactions} secret pattern(s) detected, refused (use --allow-redactions)`);
+      continue;
+    }
+    const mode = entry.mode || 'create';
+
+    try {
+      if (mode === 'merge') {
+        if (!fs.existsSync(abs)) {
+          fs.mkdirSync(path.dirname(abs), { recursive: true });
+          fs.writeFileSync(abs, scan.redacted, 'utf8');
+          results.push({ path: target, status: 'created', bytes: Buffer.byteLength(scan.redacted, 'utf8') });
+          logger.info(`  ${target} -> created`);
+          continue;
+        }
+        const existing = fs.readFileSync(abs, 'utf8');
+        const merged = applyMerge(existing, scan.redacted, {
+          acceptedHeadings: entry.acceptedHeadings || [],
+          acceptedBullets: entry.acceptedBullets || [],
+        });
+        fs.writeFileSync(abs, merged.merged, 'utf8');
+        results.push({ path: target, status: 'merged', additions: merged.additions });
+        logger.info(`  ${target} -> merged`);
+      } else if (mode === 'side_by_side') {
+        const sideAbs = entry.absolutePath
+          ? path.resolve(entry.absolutePath)
+          : sideBySidePath(abs);
+        const guardedSide = _ensureInsideProject(destAbs, path.relative(destAbs, sideAbs));
+        if (!guardedSide) {
+          results.push({ path: target, status: 'unsafe_path' });
+          continue;
+        }
+        fs.mkdirSync(path.dirname(guardedSide), { recursive: true });
+        if (fs.existsSync(guardedSide) && !allowOverwriteSideBySide) {
+          results.push({ path: target, status: 'side_by_side_conflict' });
+          logger.warn(`  ${target} -> side_by_side_conflict (pass --overwrite to replace)`);
+          continue;
+        }
+        fs.writeFileSync(guardedSide, scan.redacted, 'utf8');
+        results.push({ path: target, status: 'side_by_side', bytes: Buffer.byteLength(scan.redacted, 'utf8') });
+        logger.info(`  ${target} -> side_by_side`);
+      } else if (mode === 'skip') {
+        results.push({ path: target, status: 'skipped' });
+      } else {
+        // 'create' or 'overwrite'
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        const existed = fs.existsSync(abs);
+        if (existed && mode !== 'overwrite' && !yes) {
+          results.push({ path: target, status: 'refused_overwrite_without_yes' });
+          logger.warn(`  ${target} -> exists; pass --yes or rebuild manifest with mode='overwrite'`);
+          continue;
+        }
+        fs.writeFileSync(abs, scan.redacted, 'utf8');
+        results.push({ path: target, status: existed ? 'overwritten' : 'created' });
+        logger.info(`  ${target} -> ${existed ? 'overwritten' : 'created'}`);
+      }
+    } catch (err) {
+      results.push({ path: target, status: 'error', error: err.message });
+      logger.warn(`  ${target} -> error: ${err.message}`);
+    }
+  }
+  return results;
+}
+
+function sideBySidePath(abs) {
+  const dir = path.dirname(abs);
+  const base = path.basename(abs);
+  const ext = path.extname(base);
+  if (!ext) return path.join(dir, base + '.NEW');
+  return path.join(dir, base.slice(0, -ext.length) + '.NEW' + ext);
+}
+
+// Exported for the sync script + tests that want to assert the scan layer
+// stays in lock-step with app/lib/claude-code/optimal-files/secret-scan.js.
+export { scanForSecrets };