draftgo-cli 1.0.4

package/src/worktree/index.js

@@ -0,0 +1,751 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { loadProjectConfig } = require('../projectConfig');
+const { DraftGoMcpClient } = require('../mcp/client');
+const backendDefaults = require('./backend');
+const { WorktreeError, isVersionConflict } = require('./errors');
+const {
+  RESOURCE_TYPES,
+  canonicalResourceType,
+  entryKey,
+  mediaType,
+  resourceFileName,
+  safeIdSegment,
+} = require('./types');
+const {
+  streamToFiles,
+  hashFile,
+  copyFileAtomic,
+  writeJsonAtomic,
+  normalizeSha256,
+  tempPathFor,
+} = require('./streams');
+const {
+  loadManifest,
+  getEntry,
+  relativePath,
+  absolutePath,
+  saveManifest,
+} = require('./manifest');
+const { validateContentFile } = require('./validate');
+const { inspectEntry, openMetadataSession, sameVersion } = require('./status');
+
+const { withResourceLocks } = require('./locks');
+const { mapBounded } = require('../mcp/parallel');
+const CONFLICT_SCHEMA_VERSION = 1;
+
+function backendFor(options) {
+  return { ...backendDefaults, ...(options.backend || {}) };
+}
+
+function worktreePaths(projectDir, resourceType, resourceId, extension) {
+  const canonical = canonicalResourceType(resourceType);
+  const directory = RESOURCE_TYPES[canonical].directory;
+  const fileName = resourceFileName(canonical, resourceId, extension);
+  return {
+    local: path.join(projectDir, '.draftgo', 'worktree', directory, fileName),
+    base: path.join(projectDir, '.draftgo', 'worktree', '.base', directory, fileName),
+  };
+}
+
+function conflictPaths(projectDir, resourceType, resourceId, extension) {
+  const canonical = canonicalResourceType(resourceType);
+  const directory = RESOURCE_TYPES[canonical].directory;
+  const root = path.join(projectDir, '.draftgo', 'conflicts', directory, safeIdSegment(resourceId));
+  return {
+    root,
+    manifest: path.join(root, 'conflict.json'),
+    base: path.join(root, `base${extension}`),
+    local: path.join(root, `local${extension}`),
+    remote: path.join(root, `remote${extension}`),
+  };
+}
+
+async function createSession(config, options) {
+  if (options.session) return options.session;
+  if (options.backend && typeof options.backend.resolveMetadata === 'function') return {};
+  const client = options.client || new DraftGoMcpClient(config);
+  await client.initialize(options);
+  const tools = await client.listAllTools(options);
+  return { client, tools };
+}
+
+function ensureIds(resourceIds) {
+  const seen = new Set();
+  const ids = resourceIds.map((value) => String(value).trim()).filter((value) => {
+    if (!value || seen.has(value)) return false;
+    seen.add(value);
+    return true;
+  });
+  if (!ids.length) throw new WorktreeError('INVALID_RESOURCE_ID', 'At least one resource id is required.');
+  return ids;
+}
+
+function responseContentType(response) {
+  return mediaType(response && response.headers && response.headers.get('content-type'));
+}
+
+function assertMetadataIdentity(metadata, resourceType, resourceId) {
+  if (metadata.resource_type !== resourceType || String(metadata.resource_id) !== String(resourceId)) {
+    throw new WorktreeError('METADATA_RESOURCE_MISMATCH',
+      'DraftGo returned metadata for a different resource.');
+  }
+}
+
+async function checkoutResourcesUnlocked(projectDir, resourceType, resourceIds, options = {}) {
+  const canonical = canonicalResourceType(resourceType);
+  const ids = ensureIds(resourceIds);
+  const config = options.config || loadProjectConfig(projectDir);
+  const backend = backendFor(options);
+  const session = await createSession(config, options);
+  const manifest = loadManifest(projectDir);
+  const settled = await mapBounded(ids, async (resourceId) => {
+    const metadata = await backend.resolveMetadata(config, canonical, resourceId, {
+      ...options,
+      ...session,
+      projectDir,
+      clientInitialized: true,
+    });
+    assertMetadataIdentity(metadata, canonical, resourceId);
+
+    const existing = getEntry(manifest, canonical, resourceId);
+    if (existing) {
+      const existingLocal = absolutePath(projectDir, existing.local_path);
+      if (fs.existsSync(existingLocal)) {
+        const current = await hashFile(existingLocal);
+        if (current.hash !== existing.base_hash && !options.force) {
+          throw new WorktreeError(
+            'LOCAL_CHANGES_PRESENT',
+            `Refusing to replace locally modified ${canonical} ${resourceId}; commit it or use checkout --force explicitly.`,
+          );
+        }
+      }
+    }
+
+    const paths = worktreePaths(projectDir, canonical, resourceId, metadata.file_extension);
+    const response = await backend.download(config, metadata, options);
+    const actualType = responseContentType(response);
+    if (actualType && actualType !== mediaType(metadata.content_type)) {
+      throw new WorktreeError('CONTENT_TYPE_MISMATCH', 'Downloaded content type differs from checkout metadata.', {
+        expected: metadata.content_type,
+        actual: response.headers.get('content-type'),
+      });
+    }
+    const downloaded = await streamToFiles(response.body, [paths.local, paths.base], {
+      expectedHash: metadata.content_hash,
+      expectedSize: metadata.content_size,
+    });
+
+    const entry = {
+      server: config.server,
+      resource_type: canonical,
+      resource_id: resourceId,
+      title: metadata.title,
+      route: metadata.route,
+      code: metadata.code,
+      slug: metadata.slug,
+      local_path: relativePath(projectDir, paths.local),
+      content_type: metadata.content_type,
+      file_extension: metadata.file_extension,
+      content_size: downloaded.size,
+      base_path: relativePath(projectDir, paths.base),
+      base_version: metadata.base_version,
+      base_revision: metadata.base_revision,
+      base_etag: metadata.etag,
+      base_hash: downloaded.hash,
+      checked_out_at: new Date().toISOString(),
+      updated_at: metadata.updated_at,
+      updated_by: metadata.updated_by,
+    };
+    return entry;
+  }, { ...options, settled: true });
+  const results = settled.filter((item) => item.status === 'fulfilled').map((item) => item.value);
+  for (const entry of results) manifest.entries[entryKey(canonical, entry.resource_id)] = entry;
+  if (results.length) await saveManifest(projectDir, manifest);
+  const failures = settled.filter((item) => item.status === 'rejected');
+  if (failures.length) {
+    const first = failures[0].reason;
+    first.details = {
+      ...(first.details || {}),
+      batch: {
+        completed: results.map((entry) => ({
+          resource_type: entry.resource_type, resource_id: entry.resource_id,
+          status: 'checked_out', local_path: entry.local_path,
+        })),
+        failed: failures.map((item) => ({
+          status: 'failed', code: item.reason.code || 'CHECKOUT_FAILED', message: item.reason.message,
+        })),
+        not_started: [],
+      },
+    };
+    throw first;
+  }
+  return results;
+}
+
+function normalizeCommitPayload(value) {
+  if (!value || typeof value !== 'object') return {};
+  if (value.data && typeof value.data === 'object') return normalizeCommitPayload(value.data);
+  if (value.metadata && typeof value.metadata === 'object') return normalizeCommitPayload(value.metadata);
+  if (value.resource && typeof value.resource === 'object') return normalizeCommitPayload(value.resource);
+  return value;
+}
+
+function commitVersion(payload) {
+  return {
+    version: payload.base_version !== undefined ? payload.base_version
+      : (payload.version !== undefined ? payload.version : null),
+    revision: payload.base_revision !== undefined ? payload.base_revision
+      : (payload.revision !== undefined ? payload.revision : null),
+    etag: payload.etag || payload.e_tag || null,
+    hash: normalizeSha256(payload.content_hash || payload.hash || payload.sha256),
+    updated_at: payload.updated_at || null,
+    updated_by: payload.updated_by || null,
+  };
+}
+
+async function writeConflict(projectDir, entry, error, config, backend, options, session) {
+  const localPath = absolutePath(projectDir, entry.local_path);
+  const basePath = absolutePath(projectDir, entry.base_path);
+  const paths = conflictPaths(projectDir, entry.resource_type, entry.resource_id, entry.file_extension);
+  const remoteMetadata = await backend.resolveMetadata(config, entry.resource_type, entry.resource_id, {
+    ...options,
+    ...session,
+    projectDir,
+    clientInitialized: true,
+  });
+  assertMetadataIdentity(remoteMetadata, entry.resource_type, entry.resource_id);
+  const response = await backend.download(config, remoteMetadata, options);
+
+  await copyFileAtomic(basePath, paths.base, { expectedHash: entry.base_hash });
+  const local = await copyFileAtomic(localPath, paths.local);
+  const remote = await streamToFiles(response.body, [paths.remote], {
+    expectedHash: remoteMetadata.content_hash,
+    expectedSize: remoteMetadata.content_size,
+  });
+
+  const record = {
+    schema_version: CONFLICT_SCHEMA_VERSION,
+    status: 'unresolved',
+    code: 'RESOURCE_VERSION_CONFLICT',
+    server: config.server,
+    resource_type: entry.resource_type,
+    resource_id: entry.resource_id,
+    title: entry.title,
+    content_type: entry.content_type,
+    base_path: relativePath(projectDir, paths.base),
+    local_path: relativePath(projectDir, paths.local),
+    remote_path: relativePath(projectDir, paths.remote),
+    worktree_local_path: entry.local_path,
+    expected_version: entry.base_version != null ? entry.base_version : entry.base_revision,
+    actual_version: remoteMetadata.base_version != null
+      ? remoteMetadata.base_version : remoteMetadata.base_revision,
+    expected_hash: entry.base_hash,
+    local_hash: local.hash,
+    actual_hash: remote.hash,
+    actual_base_version: remoteMetadata.base_version,
+    actual_base_revision: remoteMetadata.base_revision,
+    actual_etag: remoteMetadata.etag,
+    updated_at: remoteMetadata.updated_at,
+    updated_by: remoteMetadata.updated_by,
+    backend_error: {
+      status: error.status || null,
+      code: error.code || 'RESOURCE_VERSION_CONFLICT',
+    },
+    created_at: new Date().toISOString(),
+  };
+  await writeJsonAtomic(paths.manifest, record);
+  return { ...record, manifest_path: relativePath(projectDir, paths.manifest) };
+}
+
+function unresolvedConflict(projectDir, resourceType, resourceId) {
+  const entry = loadManifest(projectDir).entries[entryKey(resourceType, resourceId)];
+  const extension = entry && entry.file_extension || '.bin';
+  const file = conflictPaths(projectDir, resourceType, resourceId, extension).manifest;
+  if (!fs.existsSync(file)) return null;
+  try {
+    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return record.status === 'unresolved' ? record : null;
+  } catch (error) {
+    throw new WorktreeError('INVALID_CONFLICT_MANIFEST', `Invalid conflict manifest: ${error.message}`);
+  }
+}
+
+async function commitBatchUnlocked(projectDir, targets, options = {}) {
+  const config = options.config || loadProjectConfig(projectDir);
+  const backend = backendFor(options);
+  const session = await createSession(config, options);
+  const manifest = loadManifest(projectDir);
+  const results = [];
+  const plans = [];
+  const preflightFailures = [];
+
+  const report = (result) => {
+    results.push(result);
+    if (typeof options.onStatus === 'function') options.onStatus(result);
+  };
+
+  // Resolve and validate every target before the first remote write. Different
+  // resources are independent; bound concurrency to avoid exhausting connections.
+  const preflight = await mapBounded(targets, async ({ resource_type: canonical, resource_id: resourceId }) => {
+    try {
+      const entry = getEntry(manifest, canonical, resourceId);
+      if (!entry) {
+        throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `${canonical} ${resourceId} is not checked out.`);
+      }
+      if (entry.server !== config.server) {
+        throw new WorktreeError('CHECKOUT_SERVER_MISMATCH', 'Checkout belongs to a different DraftGo server.');
+      }
+      if (unresolvedConflict(projectDir, canonical, resourceId)) {
+        throw new WorktreeError(
+          'UNRESOLVED_CONFLICT',
+          `${canonical} ${resourceId} has an unresolved conflict; resolve it before committing.`,
+        );
+      }
+
+      const localPath = absolutePath(projectDir, entry.local_path);
+      const current = await hashFile(localPath);
+      const basePath = absolutePath(projectDir, entry.base_path);
+      const base = await hashFile(basePath);
+      if (base.hash !== entry.base_hash) {
+        throw new WorktreeError(
+          'BASE_HASH_MISMATCH',
+          `${canonical} ${resourceId} base hash differs from its manifest; run draftgo check --remote.`,
+          { manifest_hash: entry.base_hash, base_hash: base.hash },
+        );
+      }
+      if (current.hash !== entry.base_hash) validateContentFile(localPath, entry.content_type);
+
+      const fresh = await backend.resolveMetadata(config, canonical, resourceId, {
+        ...options,
+        ...session,
+        projectDir,
+        clientInitialized: true,
+      });
+      assertMetadataIdentity(fresh, canonical, resourceId);
+      const remoteMatchesBase = fresh.content_hash === entry.base_hash && sameVersion(entry, fresh);
+      if (!remoteMatchesBase) {
+        const state = await inspectEntry(projectDir, entry, fresh);
+        throw new WorktreeError(
+          state.local_matches_remote ? 'COMMITTED_UNRECORDED' : 'REMOTE_VERSION_CHANGED',
+          state.local_matches_remote
+            ? `${canonical} ${resourceId} already equals remote; run ${state.recommendation}.`
+            : `${canonical} ${resourceId} changed remotely; inspect with draftgo check --remote before committing.`,
+          state,
+        );
+      }
+      return { plan: { resourceId, entry, localPath, current, fresh } };
+    } catch (error) {
+      if (error.code === 'REMOTE_VERSION_CHANGED') {
+        const entry = getEntry(manifest, canonical, resourceId);
+        try {
+          const conflict = await writeConflict(projectDir, entry, error, config, backend, options, session);
+          error = new WorktreeError(
+            'RESOURCE_VERSION_CONFLICT',
+            `${canonical} ${resourceId} changed remotely; conflict materials were preserved during preflight.`,
+            conflict,
+          );
+        } catch (conflictError) {
+          error = conflictError;
+        }
+      }
+      return { failure: {
+        resource_type: canonical,
+        resource_id: resourceId,
+        status: 'failed',
+        phase: 'preflight',
+        code: error.code || 'PREFLIGHT_FAILED',
+        message: error.message,
+        details: error.details || {},
+      } };
+    }
+  }, options);
+  for (const item of preflight) {
+    if (item.plan) plans.push(item.plan);
+    else preflightFailures.push(item.failure);
+  }
+
+  if (preflightFailures.length) {
+    const failedIds = new Set(preflightFailures.map((item) => entryKey(item.resource_type, item.resource_id)));
+    const notStarted = targets.filter((item) => !failedIds.has(entryKey(item.resource_type, item.resource_id))).map((item) => ({
+      ...item,
+      status: 'not_started',
+      phase: 'preflight',
+    }));
+    for (const result of [...preflightFailures, ...notStarted]) report(result);
+    if (targets.length === 1 && preflightFailures.length === 1) {
+      const original = new WorktreeError(
+        preflightFailures[0].code,
+        preflightFailures[0].message,
+        preflightFailures[0].details,
+      );
+      throw original;
+    }
+    throw new WorktreeError(
+      'BATCH_PREFLIGHT_FAILED',
+      `Commit preflight failed for ${preflightFailures.length} resource(s); no remote content was changed.`,
+      { completed: [], failed: preflightFailures, not_started: notStarted },
+    );
+  }
+
+  async function commitPlan(plan) {
+    const { resourceId, entry, localPath, current, fresh } = plan;
+    const canonical = entry.resource_type;
+    if (current.hash === entry.base_hash) {
+      return { resource_type: canonical, resource_id: resourceId, status: 'unchanged', hash: current.hash };
+    }
+    const commitMetadata = {
+      ...fresh,
+      content_type: entry.content_type,
+      base_version: entry.base_version,
+      base_revision: entry.base_revision,
+      etag: entry.base_etag,
+    };
+
+    let responsePayload;
+    try {
+      responsePayload = await backend.commit(config, commitMetadata, localPath, current, options);
+    } catch (error) {
+      let failure = error;
+      const versionConflict = isVersionConflict(error);
+      if (versionConflict) {
+        const conflict = await writeConflict(projectDir, entry, error, config, backend, options, session);
+        failure = new WorktreeError(
+          'RESOURCE_VERSION_CONFLICT',
+          `${canonical} ${resourceId} changed remotely; conflict materials were preserved.`,
+          conflict,
+        );
+      }
+      failure.batchResult = {
+        resource_type: canonical, resource_id: resourceId, status: 'failed', phase: 'upload',
+        code: failure.code || 'COMMIT_FAILED', message: failure.message,
+        remote_change_possible: !versionConflict,
+      };
+      throw failure;
+    }
+
+    try {
+      let committed = commitVersion(normalizeCommitPayload(responsePayload));
+      if (!committed.hash || (committed.version == null && committed.revision == null)) {
+        const confirmed = await backend.resolveMetadata(config, canonical, resourceId, {
+          ...options,
+          ...session,
+          projectDir,
+          clientInitialized: true,
+        });
+        assertMetadataIdentity(confirmed, canonical, resourceId);
+        committed = {
+          version: confirmed.base_version,
+          revision: confirmed.base_revision,
+          etag: confirmed.etag,
+          hash: confirmed.content_hash,
+          updated_at: confirmed.updated_at,
+          updated_by: confirmed.updated_by,
+        };
+      }
+      if (committed.hash && committed.hash !== current.hash) {
+        throw new WorktreeError(
+          'HASH_MISMATCH',
+          'DraftGo commit response hash differs from the uploaded raw bytes; manifest was not advanced.',
+          { local_hash: current.hash, remote_hash: committed.hash },
+        );
+      }
+
+      await copyFileAtomic(localPath, absolutePath(projectDir, entry.base_path), { expectedHash: current.hash });
+      entry.base_hash = current.hash;
+      entry.content_size = current.size;
+      entry.base_version = committed.version;
+      entry.base_revision = committed.revision;
+      entry.base_etag = committed.etag;
+      entry.updated_at = committed.updated_at;
+      entry.updated_by = committed.updated_by;
+      entry.committed_at = new Date().toISOString();
+      return {
+        resource_type: canonical,
+        resource_id: resourceId,
+        status: 'committed',
+        hash: current.hash,
+        base_version: entry.base_version,
+        base_revision: entry.base_revision,
+      };
+    } catch (error) {
+      error.batchResult = {
+        resource_type: canonical, resource_id: resourceId, status: 'failed', phase: 'upload',
+        code: error.code || 'COMMIT_FAILED', message: error.message, remote_change_possible: true,
+      };
+      throw error;
+    }
+  }
+
+  const settled = await mapBounded(plans, async (plan) => {
+    try {
+      const result = await commitPlan(plan);
+      report(result);
+      return result;
+    } catch (error) {
+      report(error.batchResult);
+      throw error;
+    }
+  }, { ...options, settled: true });
+  const committed = results.filter((item) => item.status === 'committed');
+  if (committed.length) await saveManifest(projectDir, manifest);
+  const failures = settled.filter((item) => item.status === 'rejected');
+  if (failures.length) {
+    const first = failures[0].reason;
+    const inputOrder = new Map(targets.map((item, index) => [entryKey(item.resource_type, item.resource_id), index]));
+    const ordered = (items) => [...items].sort((left, right) => (
+      (inputOrder.get(entryKey(left.resource_type, left.resource_id)) ?? Number.MAX_SAFE_INTEGER)
+      - (inputOrder.get(entryKey(right.resource_type, right.resource_id)) ?? Number.MAX_SAFE_INTEGER)
+    ));
+    first.details = {
+      ...(first.details || {}),
+      batch: {
+        completed: ordered(results.filter((item) => ['committed', 'unchanged'].includes(item.status))),
+        failed: ordered(results.filter((item) => item.status === 'failed')),
+        not_started: [],
+      },
+    };
+    throw first;
+  }
+  return results;
+}
+
+async function reconcileResourcesUnlocked(projectDir, resourceType, resourceIds, options = {}) {
+  const canonical = canonicalResourceType(resourceType);
+  const ids = ensureIds(resourceIds);
+  const config = options.config || loadProjectConfig(projectDir);
+  const backend = backendFor(options);
+  const manifest = loadManifest(projectDir);
+  const session = options.backend && typeof options.backend.resolveMetadata === 'function'
+    ? { client: options.client || {}, tools: options.tools || [] }
+    : await openMetadataSession(config, options);
+  const results = [];
+
+  for (const resourceId of ids) {
+    const entry = getEntry(manifest, canonical, resourceId);
+    if (!entry) throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `${canonical} ${resourceId} is not checked out.`);
+    if (entry.server !== config.server) {
+      throw new WorktreeError('CHECKOUT_SERVER_MISMATCH', 'Checkout belongs to a different DraftGo server.');
+    }
+    if (unresolvedConflict(projectDir, canonical, resourceId)) {
+      throw new WorktreeError(
+        'UNRESOLVED_CONFLICT',
+        `${canonical} ${resourceId} has an unresolved conflict; use conflict resolve instead of reconcile.`,
+      );
+    }
+    const remote = await backend.resolveMetadata(config, canonical, resourceId, {
+      ...options, ...session, projectDir, clientInitialized: true,
+    });
+    assertMetadataIdentity(remote, canonical, resourceId);
+    const status = await inspectEntry(projectDir, entry, remote);
+    if (!status.local_matches_remote) {
+      throw new WorktreeError(
+        'RECONCILE_UNSAFE',
+        `${canonical} ${resourceId} local content does not equal remote; refusing to advance metadata.`,
+        status,
+      );
+    }
+    if (entry.content_type !== remote.content_type || entry.file_extension !== remote.file_extension) {
+      throw new WorktreeError(
+        'RECONCILE_FORMAT_CHANGED',
+        `${canonical} ${resourceId} remote content format changed; use checkout after preserving local work.`,
+      );
+    }
+
+    const response = await backend.download(config, remote, options);
+    const basePath = absolutePath(projectDir, entry.base_path);
+    const verifiedRemote = tempPathFor(basePath);
+    let verified;
+    try {
+      verified = await streamToFiles(response.body, [verifiedRemote], {
+        expectedHash: remote.content_hash,
+        expectedSize: remote.content_size,
+      });
+      const localAfterDownload = await hashFile(absolutePath(projectDir, entry.local_path));
+      if (localAfterDownload.hash !== verified.hash) {
+        throw new WorktreeError(
+          'RECONCILE_LOCAL_CHANGED',
+          `${canonical} ${resourceId} local content changed during reconcile; manifest was not advanced.`,
+          { local_hash: localAfterDownload.hash, remote_hash: verified.hash },
+        );
+      }
+      await copyFileAtomic(verifiedRemote, basePath, { expectedHash: verified.hash });
+    } finally {
+      await fs.promises.rm(verifiedRemote, { force: true }).catch(() => {});
+    }
+    entry.base_hash = verified.hash;
+    entry.content_size = verified.size;
+    entry.base_version = remote.base_version;
+    entry.base_revision = remote.base_revision;
+    entry.base_etag = remote.etag;
+    entry.updated_at = remote.updated_at;
+    entry.updated_by = remote.updated_by;
+    entry.reconciled_at = new Date().toISOString();
+    await saveManifest(projectDir, manifest);
+    results.push({
+      resource_type: canonical,
+      resource_id: resourceId,
+      status: 'reconciled',
+      hash: verified.hash,
+      base_version: entry.base_version,
+      base_revision: entry.base_revision,
+    });
+  }
+  return results;
+}
+
+function diffResource(projectDir, resourceType, resourceId, options = {}) {
+  const entry = getEntry(loadManifest(projectDir), resourceType, resourceId);
+  if (!entry) throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `${resourceType} ${resourceId} is not checked out.`);
+  const base = absolutePath(projectDir, entry.base_path);
+  const local = absolutePath(projectDir, entry.local_path);
+  const result = spawnSync('git', [
+    'diff', '--no-index', '--no-color', '--', base, local,
+  ], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    shell: false,
+    maxBuffer: options.maxBuffer || 64 * 1024 * 1024,
+  });
+  if (result.error) throw new WorktreeError('DIFF_UNAVAILABLE', `Unable to run git diff: ${result.error.message}`);
+  if (![0, 1].includes(result.status)) {
+    throw new WorktreeError('DIFF_FAILED', result.stderr || `git diff exited with ${result.status}.`);
+  }
+  return { entry, changed: result.status === 1, output: result.stdout || '' };
+}
+
+function readConflictFile(file) {
+  try {
+    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!record || record.schema_version !== CONFLICT_SCHEMA_VERSION) {
+      throw new Error('unsupported schema');
+    }
+    return record;
+  } catch (error) {
+    throw new WorktreeError('INVALID_CONFLICT_MANIFEST', `Invalid conflict manifest ${file}: ${error.message}`);
+  }
+}
+
+function listConflicts(projectDir, options = {}) {
+  const root = path.join(projectDir, '.draftgo', 'conflicts');
+  if (!fs.existsSync(root)) return [];
+  const records = [];
+  const visit = (directory) => {
+    for (const item of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, item.name);
+      if (item.isDirectory()) visit(absolute);
+      else if (item.isFile() && item.name === 'conflict.json') {
+        const record = readConflictFile(absolute);
+        if (options.all || record.status === 'unresolved') {
+          records.push({ ...record, manifest_path: relativePath(projectDir, absolute) });
+        }
+      }
+    }
+  };
+  visit(root);
+  return records.sort((left, right) => `${left.resource_type}:${left.resource_id}`
+    .localeCompare(`${right.resource_type}:${right.resource_id}`));
+}
+
+function showConflict(projectDir, resourceType, resourceId) {
+  const canonical = canonicalResourceType(resourceType);
+  const match = listConflicts(projectDir, { all: true }).find((record) =>
+    record.resource_type === canonical && String(record.resource_id) === String(resourceId));
+  if (!match) throw new WorktreeError('CONFLICT_NOT_FOUND', `No conflict found for ${canonical} ${resourceId}.`);
+  return match;
+}
+
+async function resolveConflictUnlocked(projectDir, resourceType, resourceId) {
+  const canonical = canonicalResourceType(resourceType);
+  const manifest = loadManifest(projectDir);
+  const entry = getEntry(manifest, canonical, resourceId);
+  if (!entry) throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `${canonical} ${resourceId} is not checked out.`);
+  const conflict = showConflict(projectDir, canonical, resourceId);
+  if (conflict.status !== 'unresolved') {
+    throw new WorktreeError('CONFLICT_ALREADY_RESOLVED', `${canonical} ${resourceId} is already resolved.`);
+  }
+
+  const localPath = absolutePath(projectDir, entry.local_path);
+  validateContentFile(localPath, entry.content_type);
+  const local = await hashFile(localPath);
+  const remotePath = absolutePath(projectDir, conflict.remote_path);
+  const remote = await hashFile(remotePath);
+  if (remote.hash !== conflict.actual_hash) {
+    throw new WorktreeError('HASH_MISMATCH', 'Preserved remote conflict content no longer matches its manifest.');
+  }
+
+  await copyFileAtomic(remotePath, absolutePath(projectDir, entry.base_path), { expectedHash: remote.hash });
+  entry.base_hash = remote.hash;
+  entry.base_version = conflict.actual_base_version;
+  entry.base_revision = conflict.actual_base_revision;
+  entry.base_etag = conflict.actual_etag;
+  entry.updated_at = conflict.updated_at;
+  entry.updated_by = conflict.updated_by;
+  entry.conflict_resolved_at = new Date().toISOString();
+  await saveManifest(projectDir, manifest);
+
+  const manifestFile = absolutePath(projectDir, conflict.manifest_path);
+  const resolved = {
+    ...conflict,
+    status: 'resolved',
+    resolution_local_hash: local.hash,
+    resolved_at: new Date().toISOString(),
+  };
+  delete resolved.manifest_path;
+  await writeJsonAtomic(manifestFile, resolved);
+  return { ...resolved, manifest_path: relativePath(projectDir, manifestFile) };
+}
+
+function normalizedTargets(targets) {
+  const unique = new Map();
+  for (const target of targets) {
+    const resource_type = canonicalResourceType(target.resource_type);
+    const resource_id = ensureIds([target.resource_id])[0];
+    unique.set(entryKey(resource_type, resource_id), { resource_type, resource_id });
+  }
+  if (!unique.size) throw new WorktreeError('INVALID_RESOURCE_ID', 'At least one resource is required.');
+  return [...unique.values()];
+}
+
+function commitBatch(projectDir, targets, options = {}) {
+  const normalized = normalizedTargets(targets);
+  return withResourceLocks(projectDir, normalized.map((item) => entryKey(item.resource_type, item.resource_id)),
+    () => commitBatchUnlocked(projectDir, normalized, options));
+}
+function commitResources(projectDir, resourceType, resourceIds, options = {}) {
+  return commitBatch(projectDir, ensureIds(resourceIds).map((resource_id) => ({ resource_type: resourceType, resource_id })), options);
+}
+function checkoutResources(projectDir, resourceType, resourceIds, options = {}) {
+  const type = canonicalResourceType(resourceType);
+  const ids = ensureIds(resourceIds);
+  return withResourceLocks(projectDir, ids.map((id) => entryKey(type, id)),
+    () => checkoutResourcesUnlocked(projectDir, type, ids, options));
+}
+function reconcileResources(projectDir, resourceType, resourceIds, options = {}) {
+  const type = canonicalResourceType(resourceType);
+  const ids = ensureIds(resourceIds);
+  return withResourceLocks(projectDir, ids.map((id) => entryKey(type, id)),
+    () => reconcileResourcesUnlocked(projectDir, type, ids, options));
+}
+function resolveConflict(projectDir, resourceType, resourceId) {
+  const type = canonicalResourceType(resourceType);
+  return withResourceLocks(projectDir, [entryKey(type, resourceId)],
+    () => resolveConflictUnlocked(projectDir, type, resourceId));
+}
+
+module.exports = {
+  commitBatch,
+  CONFLICT_SCHEMA_VERSION,
+  worktreePaths,
+  conflictPaths,
+  checkoutResources,
+  commitResources,
+  reconcileResources,
+  diffResource,
+  listConflicts,
+  showConflict,
+  resolveConflict,
+};