@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/adapters/claude/index.js

@@ -0,0 +1,548 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Claude native adapter.  It owns only Claude path/format decisions; selection and
+// ownership journalling remain lifecycle concerns. Its MCP entries live in ./mcp.ts.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { mergeMarkedSection, removeMarkedSection, MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
+const { selectMcpServers } = require('../../registry/index.js');
+const { GLOBAL_HOOK_PREFIX, PROJECT_HOOK_PREFIX } = require('../../helper/settings-scope.js');
+const { mergeSettings, settingsContains, settingsContainsAny, stripManagedSettings } = require('../../helper/settings-merge.js');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, resolveTransform } = require('../copy-tree.js');
+const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { discoverMcp, planMcp, writeMcp, verifyMcp } = require('./mcp.js');
+
+const INSTRUCTION_RENDERER = 'claude-instructions';
+const SETTINGS_RENDERER = 'claude-settings';
+/**
+ * Logic residue (content substitution + source anchoring, not install destinations):
+ *  - the second settings file this asset projects; its destination IS declared (paths.keybindings),
+ *    what stays here is the per-file dispatch between the two declared surfaces;
+ *  - the hook-command prefixes rewritten INTO the authored settings content — `~/.claude/hooks/`
+ *    becomes Claude Code's documented ${CLAUDE_PROJECT_DIR}/.claude/hooks/ placeholder at project
+ *    scope (code.claude.com/docs/en/hooks). That placeholder is Claude-native payload syntax, not a
+ *    filesystem join, so it cannot be declared;
+ *  - `doflow-statusline.sh` names the projected script for the SOURCE read and the ledger identity;
+ *    its install destination is declared (paths.statuslineScript).
+ */
+const SETTINGS_FILES = ['settings.json', 'keybindings.json'];
+
+function sha256(value     ) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function sourcePath(asset     , context      = {}) {
+  if (!asset || typeof asset.source !== 'string') throw new Error('Claude asset requires a source path');
+  const repoRoot = context.repoRoot ? path.resolve(context.repoRoot) : process.cwd();
+  const source = path.resolve(repoRoot, asset.source);
+  if (!source.startsWith(`${repoRoot}${path.sep}`) || !fs.existsSync(source)) {
+    throw new Error(`Claude asset source is unavailable: ${asset.source}`);
+  }
+  return source;
+}
+
+function markerState(file     ) {
+  if (!fs.existsSync(file)) return { exists: false, managed: false, malformed: false };
+  const text = fs.readFileSync(file, 'utf8');
+  const starts = text.split(MARKER_START).length - 1;
+  const ends = text.split(MARKER_END).length - 1;
+  return { exists: true, managed: starts === 1 && ends === 1, malformed: starts !== ends || starts > 1 };
+}
+
+/** Single serialization form for every settings write, so repeated runs are byte-stable. */
+const serializeSettings = (value     ) => `${JSON.stringify(value, null, 2)}\n`;
+const settingsChangeExtras = (fileName     ) => ({ kind: 'settings-file', identity: fileName });
+
+/**
+ * Native path facts live in core/registry/harnesses.json under this harness's "paths" section and
+ * resolve through the shared harness-paths resolver; nothing below hardcodes them.
+ * createClaudeAdapter({ declaredPaths }) is the injection point buildAdapterRegistry() uses;
+ * module-level exports delegate to a default-configured instance so direct callers keep their
+ * historical shape.
+ */
+function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } = {}) {
+  // Parity note: Claude's historical nativePaths() resolved BOTH scopes' root from scopeRoot (the
+  // CLI passes $HOME there for -g installs) and never consulted homeDir — so the resolver is fed
+  // no homeDir and "root" keeps resolving exactly as before.
+  function nativePaths({ scope, scopeRoot }      = {}) {
+    return resolveHarnessPaths(declaredPaths, { scope, scopeRoot });
+  }
+
+  function discover({ scope, scopeRoot, mcp = [], mcpAdoptable = [], ledger, registry, homeDir, context = {} }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    return {
+      paths,
+      instructions: markerState(paths.instructions),
+      settingsExists: fs.existsSync(paths.settings),
+      mcpExists: fs.existsSync(paths.mcp),
+      knownMcpServers: registry ? selectMcpServers(registry).map((server     ) => server.id) : [],
+      ...discoverMcp({ paths, mcp, mcpAdoptable, ledger, scope, scopeRoot, homeDir: context.homeDir || homeDir || undefined }),
+    };
+  }
+
+  // ---- copy-tree assets (rules, skills, agents, templates, scripts, modes, references, hooks) ----
+
+  /** Every asset materialised through the copy-tree engine, whatever its declared renderer:
+   * verbatim mirrors declare 'copy-tree', transformed projections (output styles) declare their
+   * own name so the registry can tell the shapes apart. Routing is on `kind`, which both share. */
+  function claudeTreeAssets(assets     ) {
+    return [...copyTreeAssets(assets), ...(assets || []).filter((asset     ) => asset.renderer === 'claude-output-styles')];
+  }
+
+  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const changes = [];
+    const conflicts = [];
+    const treeResults = [];
+    const notices = [];
+    for (const asset of claudeTreeAssets(assets)) {
+      const destDir = copyTreeDestDir(paths.configDir, asset);
+      const sourceDir = sourcePath(asset, context);
+      const previousResources = ledgerFileResources(ledger?.resources, 'claude', asset.id);
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, 'claude'), operation: removing ? 'remove' : 'apply', layout: asset.layout, transform: asset.transform, keepModified: !removing,
+        // Forwarded so the CLI's --force reaches planTree's conflict check; omitting it let
+        // planTree's own `force = false` default stand in silently. Gated on `!removing` for the
+        // reason codex/index.ts states in full: force heals drift on apply, but a hand-edited file
+        // is never deleted on removal, forced or not.
+        force: !removing && context?.force === true, });
+      treeResults.push(result);
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
+      // A hand-edited file at a path DoFlow no longer writes is the user's: it stays, only its
+      // ownership row is released.
+      notices.push(...result.kept.map((item     ) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
+      for (const change of result.changes) {
+        changes.push({
+          assetId: asset.id, target: change.target, source: change.source, operation: change.operation,
+          ownershipIdentity: `doflow:claude:copy-tree:${asset.id}:${change.relPath}`,
+          kind: 'copy-tree-file', identity: change.relPath,
+          afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: 'registry-v1',
+          transformName: asset.transform || null,
+          ...(change.kept ? { retained: true, retainedFor: [] } : {}),
+          projection: { renderer: 'copy-tree' },
+        });
+      }
+    }
+    return { changes, conflicts, notices: [...siblingReplacedNotices(treeResults), ...notices] };
+  }
+
+  function applyCopyTreeAssets(changes     ) {
+    let applied = 0;
+    const grouped = new Map();
+    for (const change of changes) {
+      if (change.kind !== 'copy-tree-file' || change.operation === 'remove') continue;
+      const key = change.transformName || null;
+      if (!grouped.has(key)) grouped.set(key, []);
+      grouped.get(key).push({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint });
+    }
+    for (const [transformName, treeChanges] of grouped) {
+      applied += applyTree({ changes: treeChanges, transform: resolveTransform(transformName) }).applied;
+    }
+    return applied;
+  }
+
+  function removeCopyTreeAssets(changes     ) {
+    const treeChanges = changes.filter((change     ) => change.kind === 'copy-tree-file' && change.operation === 'remove' && !change.retained)
+      .map((change     ) => ({ relPath: change.identity, target: change.target, operation: 'remove', fingerprint: change.fingerprint, pruneGuard: change.pruneGuard }));
+    return removeTree({ changes: treeChanges }).removed;
+  }
+
+  function verifyCopyTreeAssets({ assets, scope, scopeRoot, context }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const statuses = [];
+    const resources = [];
+    const conflicts = [];
+    for (const asset of claudeTreeAssets(assets)) {
+      const destDir = copyTreeDestDir(paths.configDir, asset);
+      const sourceDir = sourcePath(asset, context);
+      const result = verifyTree({ sourceDir, destDir, layout: asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
+      for (const resource of result.resources) {
+        resources.push({
+          assetId: asset.id, target: resource.target, ownershipIdentity: `doflow:claude:copy-tree:${asset.id}:${resource.relPath}`,
+          kind: 'copy-tree-file', identity: resource.relPath,
+          fingerprint: resource.fingerprint, sourceVersion: 'registry-v1',
+          projection: { renderer: 'copy-tree' },
+        });
+      }
+      statuses.push({ assetId: asset.id, capability: asset.capability, status: result.ok ? 'managed' : 'conflict', target: destDir });
+    }
+    return { statuses, resources, conflicts };
+  }
+
+  // ---- claude-settings asset (settings.json + keybindings.json) ----
+
+  function settingsAsset(assets     ) { return (assets || []).find((asset     ) => asset?.renderer === SETTINGS_RENDERER); }
+  function settingsTarget(fileName     , paths     ) {
+    // Per-file dispatch across the two DECLARED settings surfaces (paths.settings / paths.keybindings):
+    // residue because the authored file list is content-shaped, not a single declarable destination.
+    return fileName === 'settings.json' ? paths.settings : paths.keybindings;
+  }
+  function settingsContent(fileName     , raw     , scope     ) {
+    return fileName === 'settings.json' && scope !== 'global' ? raw.split(GLOBAL_HOOK_PREFIX).join(PROJECT_HOOK_PREFIX) : raw;
+  }
+  function settingsLedgerResources(ledger     , assetId     ) {
+    const byFile = new Map();
+    for (const resource of ledger?.resources || []) {
+      if (resource.harness === 'claude' && resource.assetId === assetId && resource.kind === 'settings-file') byFile.set(resource.identity, resource);
+    }
+    return byFile;
+  }
+  const statuslineScriptName = 'doflow-statusline.sh';
+
+  /** Inject (or leave untouched) the statusLine key pointing at the projected script. Refuses to
+   * overwrite a user's existing custom status line unless forced: their script is theirs. */
+  function withStatusLineKey(rawSettingsJson     , scriptPath     , force     ) {
+    let parsed;
+    try {
+      parsed = JSON.parse(rawSettingsJson);
+    } catch {
+      return rawSettingsJson; // malformed authored settings are another guard's problem
+    }
+    const existing = parsed.statusLine?.command;
+    if (existing && existing !== scriptPath && !force) return rawSettingsJson;
+    parsed.statusLine = { type: 'command', command: scriptPath };
+    return serializeSettings(parsed);
+  }
+
+  function planSettingsAsset({ assets, scope, scopeRoot, context, ledger, removing }     ) {
+    const asset = settingsAsset(assets);
+    const changes        = [];
+    const conflicts        = [];
+    if (!asset) return { changes, conflicts };
+    const paths = nativePaths({ scope, scopeRoot });
+    const sourceDir = sourcePath(asset, context);
+    const previous = settingsLedgerResources(ledger, asset.id);
+    if (removing) {
+      for (const fileName of SETTINGS_FILES) {
+        const prev = previous.get(fileName);
+        if (!prev) continue;
+        const target = settingsTarget(fileName, paths);
+        if (!fs.existsSync(target)) continue;
+        const sourceAbs = path.join(sourceDir, fileName);
+        if (!fs.existsSync(sourceAbs)) continue;
+        // No fingerprint gate on removal any more: a shared file is *expected* to have drifted
+        // (the user edited it, another tool registered a hook). removeSettingsAsset subtracts only our own
+        // entries, so a drifted file is safe to process rather than a reason to refuse.
+        changes.push({ assetId: asset.id, target, operation: 'remove', ownershipIdentity: `doflow:claude:settings:${fileName}`,
+          ...settingsChangeExtras(fileName), fingerprint: prev.fingerprint,
+          managed: settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope),
+          projection: { renderer: SETTINGS_RENDERER } });
+      }
+      if (previous.get(statuslineScriptName)) {
+        changes.push({ assetId: asset.id, target: paths.statuslineScript,
+          operation: 'remove', ownershipIdentity: 'doflow:claude:statusline',
+          ...settingsChangeExtras(statuslineScriptName), fingerprint: previous.get(statuslineScriptName).fingerprint,
+          managed: null, projection: { renderer: SETTINGS_RENDERER } });
+      }
+      return { changes, conflicts };
+    }
+    for (const fileName of SETTINGS_FILES) {
+      const sourceAbs = path.join(sourceDir, fileName);
+      if (!fs.existsSync(sourceAbs)) continue;
+      let managedRaw = settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope);
+      if (fileName === 'settings.json' && context.statusline && !removing) {
+        // --statusline: point Claude Code's statusLine key at the projected script. It rides the
+        // same managed settings write as everything else this asset owns — one serialization, one
+        // fingerprint, one ownership row.
+        managedRaw = withStatusLineKey(managedRaw, paths.statuslineScript, Boolean(context.force));
+      }
+      const target = settingsTarget(fileName, paths);
+      const prev = previous.get(fileName);
+      // Both the fresh-install and merge paths emit re-serialized JSON so the on-disk bytes are
+      // identical either way. Writing raw source bytes on create and re-serialized bytes on every
+      // later run would make each update look like a change and break idempotency.
+      let content;
+      try { content = serializeSettings(JSON.parse(managedRaw)); }
+      catch { conflicts.push(`${fileName} source is not valid JSON`); continue; }
+      let operation = prev ? 'update' : 'create';
+
+      if (fs.existsSync(target)) {
+        // settings.json is shared with the user and with third-party installers, so "the file
+        // differs from our source" is the normal steady state, not drift. Merge our keys in and
+        // leave everything else alone; only genuinely unreadable JSON is a conflict now. The old
+        // byte-identity check made a first install impossible on any already-configured machine.
+        const currentRaw = fs.readFileSync(target, 'utf8');
+        let merged;
+        try {
+          merged = mergeSettings(JSON.parse(currentRaw), JSON.parse(managedRaw));
+        } catch {
+          conflicts.push(`${fileName} is not valid JSON and cannot be merged`);
+          continue;
+        }
+        content = serializeSettings(merged);
+        if (sha256(currentRaw) === sha256(content)) continue;   // already contains our keys verbatim
+        // 'merge' is the same operation the marker-merged instructions file reports — it is the
+        // lifecycle's existing vocabulary for "fold our content into a file we do not own".
+        operation = 'merge';
+      }
+
+      const fingerprint = sha256(content);
+      changes.push({ assetId: asset.id, target, source: sourceAbs, content, operation,
+        ownershipIdentity: `doflow:claude:settings:${fileName}`, ...settingsChangeExtras(fileName),
+        afterFingerprint: fingerprint, fingerprint, sourceVersion: 'registry-v1',
+        projection: { renderer: SETTINGS_RENDERER } });
+    }
+
+    if (context.statusline) {
+      const scriptSource = path.join(path.dirname(sourceDir), 'statusline', statuslineScriptName);
+      if (fs.existsSync(scriptSource)) {
+        const target = paths.statuslineScript;
+        const content = fs.readFileSync(scriptSource, 'utf8');
+        const fingerprint = sha256(content);
+        const prev = previous.get(statuslineScriptName);
+        const operation = !prev ? 'create' : (fs.existsSync(target) && sha256(fs.readFileSync(target, 'utf8')) === fingerprint ? null : 'update');
+        // A byte-identical script is a no-op — but the settings key above still needed its merge
+        // pass, so only the file write is skipped, never the change record's bookkeeping.
+        if (operation) {
+          changes.push({ assetId: asset.id, target, source: scriptSource, content, operation,
+            ownershipIdentity: 'doflow:claude:statusline', ...settingsChangeExtras(statuslineScriptName),
+            afterFingerprint: fingerprint, fingerprint, sourceVersion: 'registry-v1',
+            projection: { renderer: SETTINGS_RENDERER } });
+        }
+      }
+    }
+    return { changes, conflicts };
+  }
+
+  // Sets the destination's mtime to match its source file's, not the write time, mirroring every
+  // other copy-tree/settings write in this codebase — planSettingsAsset's own change detection is
+  // fingerprint(sha256)-based, not mtime-based, so this is a consistency convention, not a
+  // correctness requirement.
+  function applySettingsAsset(changes     ) {
+    let applied = 0;
+    for (const change of changes) {
+      if (change.projection?.renderer !== SETTINGS_RENDERER || change.operation === 'remove') continue;
+      fs.mkdirSync(path.dirname(change.target), { recursive: true });
+      fs.writeFileSync(change.target, change.content);
+      const sourceStat = fs.statSync(change.source);
+      fs.utimesSync(change.target, Math.floor(sourceStat.atimeMs / 1000), Math.floor(sourceStat.mtimeMs / 1000));
+      applied += 1;
+    }
+    return applied;
+  }
+
+  // Strips only DoFlow's own hook entries and leaves the rest of a shared file standing. The file
+  // is deleted outright only when nothing but schema pointers remains — i.e. DoFlow created it.
+  // Previously this rmSync'd unconditionally, which on a user-maintained settings.json would have
+  // destroyed their model, permissions, env, and every foreign tool's hooks along with ours.
+  function removeSettingsAsset(changes     ) {
+    let removed = 0;
+    for (const change of changes) {
+      if (change.projection?.renderer !== SETTINGS_RENDERER || change.operation !== 'remove') continue;
+      if (!fs.existsSync(change.target)) continue;
+      let remaining = null;
+      if (change.managed) {
+        try {
+          remaining = stripManagedSettings(JSON.parse(fs.readFileSync(change.target, 'utf8')), JSON.parse(change.managed));
+        } catch { remaining = undefined; }        // unreadable -> leave the file untouched
+      }
+      if (remaining === undefined) continue;
+      if (remaining === null) fs.rmSync(change.target, { force: true });
+      else fs.writeFileSync(change.target, serializeSettings(remaining));
+      removed += 1;
+    }
+    return removed;
+  }
+
+  function verifySettingsAsset({ assets, scope, scopeRoot, context }     ) {
+    const asset = settingsAsset(assets);
+    const statuses        = [];
+    const resources        = [];
+    const conflicts        = [];
+    if (!asset) return { statuses, resources, conflicts };
+    const paths = nativePaths({ scope, scopeRoot });
+    const sourceDir = sourcePath(asset, context);
+    for (const fileName of SETTINGS_FILES) {
+      const sourceAbs = path.join(sourceDir, fileName);
+      if (!fs.existsSync(sourceAbs)) continue;
+      const fingerprint = sha256(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope));
+      const target = settingsTarget(fileName, paths);
+      // 'absent' (not 'missing') matches the same convention the instructions asset already uses
+      // for "no file here" — 'missing' is reserved by the lifecycle layer's removal reconciliation
+      // as a hard-failure status, which would make every successful remove look like a verification
+      // failure (nothing to overwrite it back to 'removed', since this is a per-file, not a
+      // Codex-style shared-container-with-ownershipIdentity-matched status).
+      if (!fs.existsSync(target)) { statuses.push({ assetId: asset.id, capability: 'settings', status: 'absent', target }); continue; }
+      // Containment, not equality: a shared file legitimately holds the user's own keys and other
+      // tools' hook entries. Verification asks only "are DoFlow's keys still here and intact?" —
+      // byte-equality would report every user edit as a conflict forever.
+      let current;
+      let managed;
+      try {
+        current = JSON.parse(fs.readFileSync(target, 'utf8'));
+        managed = JSON.parse(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope));
+      } catch {
+        conflicts.push(`${fileName} is not valid JSON`);
+        statuses.push({ assetId: asset.id, capability: 'settings', status: 'conflict', target });
+        continue;
+      }
+      if (!settingsContains(current, managed)) {
+        // None of our hook entries left -> this is a removed/never-installed file that legitimately
+        // still holds the user's own content, not damage. Only a partial presence is a conflict.
+        if (!settingsContainsAny(current, managed)) {
+          statuses.push({ assetId: asset.id, capability: 'settings', status: 'absent', target });
+          continue;
+        }
+        conflicts.push(`${fileName} is missing DoFlow-managed settings`);
+        statuses.push({ assetId: asset.id, capability: 'settings', status: 'conflict', target });
+        continue;
+      }
+      statuses.push({ assetId: asset.id, capability: 'settings', status: 'managed', target });
+      resources.push({ assetId: asset.id, target, ownershipIdentity: `doflow:claude:settings:${fileName}`,
+        ...settingsChangeExtras(fileName), fingerprint, sourceVersion: 'registry-v1', projection: { renderer: SETTINGS_RENDERER } });
+    }
+    if (context.statusline) {
+      const target = paths.statuslineScript;
+      const scriptSource = path.join(path.dirname(sourceDir), 'statusline', statuslineScriptName);
+      if (!fs.existsSync(scriptSource)) {
+        conflicts.push('doflow-statusline.sh source is missing from this checkout');
+        statuses.push({ assetId: asset.id, capability: 'settings', status: 'conflict', target });
+      } else {
+        const expected = sha256(fs.readFileSync(scriptSource, 'utf8'));
+        const current = fs.existsSync(target) ? sha256(fs.readFileSync(target, 'utf8')) : null;
+        if (current === null || (current !== expected && !(context.operation === 'remove'))) {
+          statuses.push({ assetId: asset.id, capability: 'settings', status: current === null ? 'absent' : 'missing',
+            ownershipIdentity: 'doflow:claude:statusline', target });
+        } else {
+          statuses.push({ assetId: asset.id, capability: 'settings', status: current === expected ? 'managed' : 'absent',
+            ownershipIdentity: 'doflow:claude:statusline', target });
+          if (current === expected) {
+            resources.push({ assetId: asset.id, target, ownershipIdentity: 'doflow:claude:statusline',
+              ...settingsChangeExtras(statuslineScriptName), fingerprint: expected,
+              sourceVersion: 'registry-v1', projection: { renderer: SETTINGS_RENDERER } });
+          }
+        }
+      }
+    }
+    return { statuses, resources, conflicts };
+  }
+
+  // ---- shared adapter contract ----
+
+  /** Render native Claude input without writing it.
+   * `asset` is the lifecycle-projected shape (flat `renderer`/`capability` fields — see
+   * src/adapters/index.js#projectAdapterInput), not the raw registry asset's nested
+   * `asset.projection.claude`. Every adapter method below shares that same expectation. */
+  function render({ asset, scope, scopeRoot, context = {} }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    if (asset?.renderer === INSTRUCTION_RENDERER) {
+      const source = sourcePath(asset, context);
+      const content = fs.readFileSync(source, 'utf8');
+      return { type: 'managed-section', assetId: asset.id, source, target: paths.instructions, content, fingerprint: sha256(content) };
+    }
+    if (asset?.renderer === 'copy-tree') {
+      const sourceDir = sourcePath(asset, context);
+      return { type: 'copy-tree', assetId: asset.id, sourceDir, destDir: copyTreeDestDir(paths.configDir, asset) };
+    }
+    if (asset?.renderer === SETTINGS_RENDERER) {
+      const sourceDir = sourcePath(asset, context);
+      return { type: 'settings-tree', assetId: asset.id, sourceDir, files: SETTINGS_FILES, targets: SETTINGS_FILES.map((fileName) => settingsTarget(fileName, paths)) };
+    }
+    return { type: 'unsupported', assetId: asset?.id, renderer: asset?.renderer ?? null };
+  }
+
+  function plan({ assets, scope, scopeRoot, mcp = [], mcpAdoptable = [], discovery, context = {}, ledger }     ) {
+    const changes = [];
+    const conflicts = [];
+    const paths = nativePaths({ scope, scopeRoot });
+    const removing = context.operation === 'remove';
+    for (const asset of assets) {
+      if (asset?.renderer !== INSTRUCTION_RENDERER) continue;
+      if (discovery?.instructions?.malformed) {
+        conflicts.push(`Claude instructions contain malformed DoFlow markers: ${paths.instructions}`);
+        continue;
+      }
+      const rendered = render({ asset, scope, scopeRoot, context });
+      // Outside of removal, only report a change when the merge would actually alter the file —
+      // otherwise every install/update run would report a pending Claude change even when nothing
+      // changed, breaking the idempotent "already up to date" convergence every other mapping gets.
+      if (!removing && !mergeMarkedSection(rendered.source, rendered.target, { dryRun: true }).changed) continue;
+      changes.push({
+        assetId: asset.id,
+        target: rendered.target,
+        source: rendered.source,
+        operation: removing ? 'remove' : (discovery?.instructions?.managed ? 'merge' : 'create'),
+        ownershipIdentity: 'doflow:claude:instructions:managed-section',
+        afterFingerprint: rendered.fingerprint,
+        sourceVersion: 'registry-v1',
+        projection: { renderer: INSTRUCTION_RENDERER, target: 'CLAUDE.md' },
+      });
+    }
+    const copyTree = planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing });
+    changes.push(...copyTree.changes); conflicts.push(...copyTree.conflicts);
+    const settings = planSettingsAsset({ assets, scope, scopeRoot, context, ledger, removing });
+    changes.push(...settings.changes); conflicts.push(...settings.conflicts);
+    const mcpPlan = planMcp({ paths, mcp, mcpAdoptable, ledger, snapshot: discovery?.mcpSnapshot, removing });
+    changes.push(...mcpPlan.changes); conflicts.push(...mcpPlan.conflicts);
+    return { changes, conflicts, prerequisites: [], notices: [...copyTree.notices, ...mcpPlan.notices] };
+  }
+
+  function apply({ changes, scope, scopeRoot, context = {} }     ) {
+    for (const change of changes) {
+      if (change.projection?.renderer !== INSTRUCTION_RENDERER) continue;
+      // A plan records the resolved source. This keeps apply self-contained when
+      // the lifecycle supplies normalized changes rather than the original asset
+      // array, while still avoiding any implicit source discovery at write time.
+      const source = change.source ?? sourcePath((context.assets || []).find((item     ) => item.id === change.assetId), context);
+      mergeMarkedSection(source, change.target ?? nativePaths({ scope, scopeRoot }).instructions);
+    }
+    applyCopyTreeAssets(changes);
+    // An update that no longer ships a copy-tree file carries its rows as removals inside the
+    // apply batch; the lifecycle calls remove() only for `doflow remove`.
+    removeCopyTreeAssets(changes);
+    applySettingsAsset(changes);
+    writeMcp(changes);
+    return { applied: changes.length };
+  }
+
+  function remove({ changes }     ) {
+    let removed = 0;
+    for (const change of changes) {
+      if (change.projection?.renderer === INSTRUCTION_RENDERER && removeMarkedSection(change.target)) removed += 1;
+    }
+    removed += removeCopyTreeAssets(changes);
+    removed += removeSettingsAsset(changes);
+    removed += writeMcp(changes);
+    return { removed };
+  }
+
+  function verify({ assets, scope, scopeRoot, mcp = [], mcpAdoptable = [], discovery, ledger, operation, context = {} }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const statuses = [];
+    const resources = [];
+    const instruction = assets.find((asset     ) => asset?.renderer === INSTRUCTION_RENDERER);
+    const state = markerState(paths.instructions);
+    if (instruction) {
+      statuses.push({ assetId: instruction.id, status: state.managed ? 'managed' : 'absent', target: paths.instructions });
+      if (state.managed) {
+        const rendered = render({ asset: instruction, scope, scopeRoot, context });
+        resources.push({ assetId: instruction.id, target: paths.instructions, ownershipIdentity: 'doflow:claude:instructions:managed-section', fingerprint: rendered.fingerprint, sourceVersion: 'registry-v1', projection: { renderer: INSTRUCTION_RENDERER } });
+      }
+    }
+    const copyTree = verifyCopyTreeAssets({ assets, scope, scopeRoot, context });
+    statuses.push(...copyTree.statuses); resources.push(...copyTree.resources);
+    const settings = verifySettingsAsset({ assets, scope, scopeRoot, context });
+    statuses.push(...settings.statuses); resources.push(...settings.resources);
+    const mcpResult = verifyMcp({ paths, mcp, mcpAdoptable, ledger, snapshot: discovery?.mcpSnapshot,
+      removing: (operation ?? context.operation) === 'remove', sourceVersion: context.sourceVersion ?? 'unknown' });
+    statuses.push(...mcpResult.statuses); resources.push(...mcpResult.resources);
+    const conflicts = [
+      ...(state.malformed ? [`Claude instructions contain malformed DoFlow markers: ${paths.instructions}`] : []),
+      ...copyTree.conflicts, ...settings.conflicts, ...mcpResult.conflicts,
+    ];
+    return { ok: conflicts.length === 0, statuses, resources, conflicts };
+  }
+
+  return { nativePaths, discover, render, plan, apply, remove, verify };
+}
+
+const singleton = createClaudeAdapter();
+
+module.exports = {
+  nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
+  plan: singleton.plan, apply: singleton.apply, remove: singleton.remove, verify: singleton.verify,
+  createClaudeAdapter,
+};

package/src/adapters/claude/mcp.js

@@ -0,0 +1,94 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Claude's MCP component: DoFlow's servers as entries of `mcpServers` in `~/.claude.json` (user
+// scope) or `<project>/.mcp.json` (project scope), the locations Claude Code actually reads. Both
+// files are shared — `~/.claude.json` also holds Claude Code's own state, and a project `.mcp.json`
+// can be read and written by other tools — so DoFlow owns its servers one entry at a time through
+// ../mcp-entries.ts and never rewrites another key or another entry's value.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { nativeMcpCatalog } = require('../../registry/index.js');
+const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
+
+const HARNESS = 'claude';
+const MCP_CONTAINER = 'mcpServers';
+const MCP_RENDERER = 'claude-mcp';
+// Claude's MCP entries have no asset of their own; they ride the guidance asset every Claude
+// install carries.
+const MCP_ASSET_ID = 'guidance.core';
+
+function ownershipIdentity(id     ) { return `doflow:${HARNESS}:mcp-server:${id}`; }
+
+/** Claude Code's own per-server shape, the one the registry's native catalog renders. */
+function rendered(servers     ) {
+  const { serverDefs } = nativeMcpCatalog(servers);
+  return servers.map((server     ) => ({ id: server.id, entry: serverDefs[server.id] }));
+}
+
+/** Everything the shared entry-ownership rules need from this adapter. */
+function mcpEntriesInput({ paths, mcp = [], mcpAdoptable = [], ledger }     ) {
+  const rows = (ledger?.resources || []).filter((row     ) => row.kind === 'mcp-server');
+  return {
+    file: paths.mcp, selected: rendered(mcp), adoptable: rendered(mcpAdoptable),
+    ownRows: rows.filter((row     ) => row.harness === HARNESS).map((row     ) => ({
+      identity: row.identity, target: row.target, fingerprint: row.fingerprint ?? null, ownershipIdentity: row.ownershipIdentity, legacy: false,
+    })),
+    foreignRows: rows.filter((row     ) => row.harness !== HARNESS).map((row     ) => ({ harness: row.harness, identity: row.identity, target: row.target })),
+    identityFor: ownershipIdentity, assetId: MCP_ASSET_ID, renderer: MCP_RENDERER, label: 'Claude MCP',
+  };
+}
+
+function readFiles(entries     , fsImpl     ) {
+  return readMcpFiles({ file: entries.file, ownRows: entries.ownRows, container: MCP_CONTAINER, fsImpl });
+}
+
+/** Server names Claude Code merges into a project from `~/.claude.json` beside the project's own
+ * `.mcp.json`: the local scope (`projects[<root>].mcpServers`) and the user scope (`mcpServers`).
+ * Read-only and for reach alone; a file that cannot be read contributes nothing (null). */
+function claudeJsonNames({ scopeRoot, homeDir, fsImpl }     ) {
+  let doc;
+  try { doc = JSON.parse(fsImpl.readFileSync(path.join(homeDir, '.claude.json'), 'utf8')); } catch { return null; }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return null;
+  const names = (servers     ) => (servers && typeof servers === 'object' && !Array.isArray(servers) ? Object.keys(servers) : []);
+  const projects = doc.projects && typeof doc.projects === 'object' ? doc.projects : {};
+  let real = scopeRoot;
+  try { real = fsImpl.realpathSync(scopeRoot); } catch { /* the path as given */ }
+  return [...names(doc.mcpServers), ...[...new Set([scopeRoot, real])].flatMap((key) => names(projects[key]?.mcpServers))];
+}
+
+/** The MCP files as plan read them (`mcpSnapshot`, which verify compares against), the servers
+ * DoFlow owns in them now (`mcpOwned`) and every server name DoFlow can see for the scope
+ * (`mcpConfigured`): the scope's file, plus at project scope the local- and user-scope entries in
+ * `~/.claude.json`. Claude Code also loads plugin, managed and connector servers DoFlow does not
+ * read, so the view is never complete (`mcpComplete: false`) and absence is never proof. */
+function discoverMcp({ paths, mcp, mcpAdoptable, ledger, scope, scopeRoot, homeDir = os.homedir(), fsImpl = fs }     ) {
+  const entries = mcpEntriesInput({ paths, mcp, mcpAdoptable, ledger });
+  const mcpSnapshot = readFiles(entries, fsImpl);
+  // `null` while nothing could be read; every name otherwise, whoever wrote it.
+  const read = mcpSnapshot[entries.file];
+  const own = read?.ok && read.servers ? Object.keys(read.servers) : null;
+  const merged = scope === 'project' && scopeRoot ? claudeJsonNames({ scopeRoot, homeDir, fsImpl }) : null;
+  const mcpConfigured = own || merged ? [...new Set([...(own || []), ...(merged || [])])].sort() : null;
+  return { mcpSnapshot, mcpOwned: ownedMcpIds({ ...entries, files: mcpSnapshot }), mcpConfigured, mcpComplete: false };
+}
+
+function planMcp({ paths, mcp, mcpAdoptable, ledger, snapshot, removing, fsImpl = fs }     ) {
+  const entries = mcpEntriesInput({ paths, mcp, mcpAdoptable, ledger });
+  return planMcpEntries({ ...entries, files: snapshot ?? readFiles(entries, fsImpl), removing });
+}
+
+/** An emptied `mcpServers` stays as `{}`, as Claude Code itself leaves it. */
+function writeMcp(changes     , { fsImpl = fs } = {}) {
+  return writeMcpEntries(changes, { container: MCP_CONTAINER, keepEmptyContainer: true, fsImpl });
+}
+
+function verifyMcp({ paths, mcp, mcpAdoptable, ledger, snapshot, removing, sourceVersion, fsImpl = fs }     ) {
+  const entries = mcpEntriesInput({ paths, mcp, mcpAdoptable, ledger });
+  const files = readFiles(entries, fsImpl);
+  return verifyMcpEntries({ ...entries, files, snapshot: snapshot ?? files, removing, harness: HARNESS, sourceVersion });
+}
+
+module.exports = { discoverMcp, planMcp, writeMcp, verifyMcp };