release-skill 0.1.1

package/src/artifacts/inventory.mjs

@@ -0,0 +1,192 @@
+/**
+ * Closed-world artifact inventory builder.
+ *
+ * Enumerates every file that belongs to the artifact world:
+ * 1. Git-tracked files (`git ls-files -z`)
+ * 2. Relevant untracked files (`git ls-files -o --exclude-standard -z`)
+ * 3. Tombstone entries from a previous lock (paths removed since last accept)
+ *
+ * Protocol-reserved directories (`.git/`, `.release-skill/runs/`,
+ * `transactions/`, `resolution-worktree/`, `objects/`) are excluded from
+ * enumeration. Policy, lock, and project config files inside `.release-skill/`
+ * are NOT excluded — they are explicit closed-world entries.
+ *
+ * Each enumerated path is validated through `readEntry` which rejects
+ * symlinks, hardlinks, and other dangerous filesystem types with PATH_UNSAFE.
+ *
+ * @module artifacts/inventory
+ */
+
+import { promisify } from 'node:util';
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { readEntry, digestEntryManifest } from './entry.mjs';
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Protocol-reserved directory prefixes (excluded from inventory)
+// ---------------------------------------------------------------------------
+
+/**
+ * Paths starting with any of these prefixes are protocol-reserved and
+ * excluded from the closed-world inventory.
+ *
+ * Note: `.release-skill/` itself is NOT reserved — only its `runs/`
+ * subdirectory. Policy, lock, and project config files inside
+ * `.release-skill/` remain inventory entries.
+ */
+const RESERVED_PREFIXES = Object.freeze([
+  '.git/',
+  '.release-skill/runs/',
+  'transactions/',
+  'resolution-worktree/',
+  'objects/',
+]);
+
+/**
+ * Check whether a relative path is inside a protocol-reserved directory.
+ *
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+function isReservedPath(relPath) {
+  // Exact match for directory names (without trailing slash)
+  if (relPath === '.git' || relPath === 'transactions' || relPath === 'objects') {
+    return true;
+  }
+  return RESERVED_PREFIXES.some((prefix) => relPath.startsWith(prefix));
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a git command and return NUL-delimited output as an array of strings.
+ *
+ * @param {string} cwd - Working directory (repo root).
+ * @param {string[]} args - Git arguments (must include -z or -rz).
+ * @returns {Promise<string[]>} Split paths (empty strings filtered out).
+ */
+async function gitLsFilesRaw(cwd, args) {
+  const { stdout } = await execFileAsync('git', ['ls-files', ...args], {
+    cwd,
+    shell: false,
+    maxBuffer: 50 * 1024 * 1024,
+  });
+  // NUL-delimited; filter empty strings from trailing NUL
+  return stdout.split('\0').filter((s) => s.length > 0);
+}
+
+/**
+ * Check if a path exists on disk (file, directory, or symlink).
+ *
+ * @param {string} absPath
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(absPath) {
+  try {
+    await access(absPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a closed-world inventory for a repository.
+ *
+ * The inventory captures every artifact entry that belongs to the current
+ * release scope:
+ * - Git-tracked files
+ * - Relevant untracked files (not in .gitignore, not in reserved dirs)
+ * - Tombstone entries for paths removed since the previous lock
+ *
+ * Each entry is read through `readEntry` which rejects symlinks and
+ * hardlinks with PATH_UNSAFE.
+ *
+ * @param {object} options
+ * @param {string} options.root - Repository root (absolute).
+ * @param {object} options.policy - Validated artifact policy (must have `repository.id`).
+ * @param {object} [options.previousLock] - Previous artifact-lock for tombstone recovery.
+ * @param {string} [options.gitRef] - Git ref for base state (reserved for Task 4).
+ * @returns {Promise<Inventory>}
+ */
+export async function buildInventory({ root, policy, previousLock, gitRef } = {}) {
+  const repositoryId = policy.repository.id;
+
+  // 1. Enumerate git-tracked files
+  const tracked = await gitLsFilesRaw(root, ['-z']);
+
+  // 2. Enumerate relevant untracked files (not in .gitignore, not tracked)
+  const untracked = await gitLsFilesRaw(root, ['-o', '--exclude-standard', '-z']);
+
+  // 3. Merge and deduplicate, filtering reserved paths
+  const allPaths = new Set();
+  for (const p of [...tracked, ...untracked]) {
+    if (!isReservedPath(p)) {
+      allPaths.add(p);
+    }
+  }
+
+  // 4. Add tombstone entries from previous lock (paths that were accepted
+  //    before but are no longer present on disk or in git)
+  const tombstoneEntries = [];
+  if (previousLock && Array.isArray(previousLock.entries)) {
+    for (const lockEntry of previousLock.entries) {
+      if (lockEntry.path && !allPaths.has(lockEntry.path)) {
+        const absPath = `${root}/${lockEntry.path}`;
+        const exists = await pathExists(absPath);
+        if (!exists) {
+          tombstoneEntries.push(
+            Object.freeze({
+              kind: 'absent',
+              path: lockEntry.path,
+            }),
+          );
+          allPaths.add(lockEntry.path);
+        }
+      }
+    }
+  }
+
+  // 5. Read each enumerated path through readEntry (validates filesystem type)
+  const fileEntries = [];
+  for (const p of tracked) {
+    if (!isReservedPath(p)) {
+      fileEntries.push(await readEntry({ root, path: p, source: 'worktree' }));
+    }
+  }
+  for (const p of untracked) {
+    if (!isReservedPath(p)) {
+      fileEntries.push(await readEntry({ root, path: p, source: 'worktree' }));
+    }
+  }
+
+  // 6. Merge file entries with tombstone entries
+  const entries = [...fileEntries, ...tombstoneEntries];
+
+  // 7. Compute sorted paths and manifest digest
+  const paths = Object.freeze([...allPaths].sort());
+
+  return Object.freeze({
+    repositoryId,
+    entries: Object.freeze(entries),
+    paths,
+    manifestDigest: digestEntryManifest(
+      entries.map((e) => ({
+        path: e.path ?? '',
+        type: e.type ?? (e.kind === 'absent' ? 'absent' : ''),
+        mode: e.mode ?? '',
+        sha256: e.sha256 ?? '',
+        size: e.size ?? 0,
+      })),
+    ),
+  });
+}

package/src/artifacts/merge/binary.mjs

@@ -0,0 +1,77 @@
+/**
+ * Binary artifact three-way merge.
+ *
+ * Binary entries can only be fast-forwarded: exactly one side may differ
+ * from the base.  Divergent two-side changes are always CONFLICT.
+ *
+ * @module artifacts/merge/binary
+ */
+
+import { sha256Hex } from '../../core/digest.mjs';
+
+/**
+ * Merge two binary modifications of the same base content.
+ *
+ * Accepts the changed side when only one side differs from the base.
+ * Returns CONFLICT when both sides changed to different content.
+ *
+ * @param {object} options
+ * @param {Buffer} options.base      - Base (accepted) content.
+ * @param {Buffer} options.current   - Current (human) content.
+ * @param {Buffer} options.generated - Generated (producer) content.
+ * @returns {{ status: 'MERGEABLE'|'CONFLICT', bytes?: Buffer, conflicts: object[] }}
+ */
+export function mergeBinary({ base, current, generated }) {
+  const baseHash = sha256Hex(base);
+  const currentHash = sha256Hex(current);
+  const generatedHash = sha256Hex(generated);
+
+  const currentChanged = baseHash !== currentHash;
+  const generatedChanged = baseHash !== generatedHash;
+
+  // Both unchanged — MERGEABLE with base content
+  if (!currentChanged && !generatedChanged) {
+    return Object.freeze({
+      status: 'MERGEABLE',
+      bytes: base,
+      conflicts: Object.freeze([]),
+    });
+  }
+
+  // Only one side changed — accept that side
+  if (currentChanged && !generatedChanged) {
+    return Object.freeze({
+      status: 'MERGEABLE',
+      bytes: current,
+      conflicts: Object.freeze([]),
+    });
+  }
+
+  if (!currentChanged && generatedChanged) {
+    return Object.freeze({
+      status: 'MERGEABLE',
+      bytes: generated,
+      conflicts: Object.freeze([]),
+    });
+  }
+
+  // Both sides changed
+  if (currentHash === generatedHash) {
+    // Same change — accept
+    return Object.freeze({
+      status: 'MERGEABLE',
+      bytes: current,
+      conflicts: Object.freeze([]),
+    });
+  }
+
+  // Divergent — CONFLICT
+  return Object.freeze({
+    status: 'CONFLICT',
+    conflicts: Object.freeze([Object.freeze({
+      reason: 'binary divergent change',
+      currentHash,
+      generatedHash,
+    })]),
+  });
+}

package/src/artifacts/merge/entry-merge.mjs

@@ -0,0 +1,228 @@
+/**
+ * Three-way artifact entry merge dispatcher.
+ *
+ * Classifies the existence/state of (base, current, generated) and
+ * delegates content merge to the appropriate driver (text, binary, tree).
+ *
+ * The existence table (design §10.1) is implemented here; content-level
+ * merge logic lives in the driver modules.
+ *
+ * Real artifact targets are never written by this module — results are
+ * returned as in-memory candidates.
+ *
+ * @module artifacts/merge/entry-merge
+ */
+
+import { sha256Hex } from '../../core/digest.mjs';
+import { mergeText } from './text.mjs';
+import { mergeBinary } from './binary.mjs';
+import { mergeTree } from './tree.mjs';
+import { mergeMarkdown } from './markdown.mjs';
+import { mergeJson } from './json.mjs';
+import { mergeYaml } from './yaml.mjs';
+
+// Re-export sub-module APIs for convenience
+export { mergeText } from './text.mjs';
+export { mergeBinary } from './binary.mjs';
+export { mergeTree } from './tree.mjs';
+export { mergeMarkdown } from './markdown.mjs';
+export { mergeJson } from './json.mjs';
+export { mergeYaml } from './yaml.mjs';
+
+/**
+ * Merge two modifications of the same base artifact entry.
+ *
+ * Dispatches to the appropriate driver after applying the existence table
+ * (absent/present combinations).
+ *
+ * @param {object} options
+ * @param {object|null} options.base      - Base entry ({ kind: 'absent' } or entry object).
+ * @param {object|null} options.current   - Current entry.
+ * @param {object|null} options.generated - Generated entry.
+ * @param {'text'|'binary'|'tree'} [options.driver='text'] - Merge driver.
+ * @param {object} [options.options]      - Driver-specific options (renameMap for tree).
+ * @returns {{ status: 'MERGEABLE'|'CONFLICT', candidate?: object }}
+ */
+export function mergeEntry({ base, current, generated, driver = 'text', options } = {}) {
+  const hasBase      = base      && base.kind      !== 'absent';
+  const hasCurrent   = current   && current.kind   !== 'absent';
+  const hasGenerated = generated && generated.kind !== 'absent';
+
+  // -------------------------------------------------------------------
+  // Existence table — base absent
+  // -------------------------------------------------------------------
+  if (!hasBase) {
+    if (!hasCurrent && !hasGenerated) {
+      return Object.freeze({ status: 'MERGEABLE', candidate: Object.freeze({ kind: 'absent' }) });
+    }
+    if (hasCurrent && !hasGenerated) {
+      return Object.freeze({ status: 'MERGEABLE', candidate: current });
+    }
+    if (!hasCurrent && hasGenerated) {
+      return Object.freeze({ status: 'MERGEABLE', candidate: generated });
+    }
+    // Both present and differ → CONFLICT
+    if (!entriesEqual(current, generated)) {
+      return Object.freeze({ status: 'CONFLICT', candidate: undefined });
+    }
+    // Both present and equal → MERGEABLE
+    return Object.freeze({ status: 'MERGEABLE', candidate: current });
+  }
+
+  // -------------------------------------------------------------------
+  // Existence table — base present
+  // -------------------------------------------------------------------
+  if (!hasCurrent && !hasGenerated) {
+    return Object.freeze({ status: 'MERGEABLE', candidate: Object.freeze({ kind: 'absent' }) });
+  }
+
+  if (hasCurrent && !hasGenerated) {
+    // Producer deleted, human kept → accept producer delete
+    if (entriesEqual(base, current)) {
+      return Object.freeze({ status: 'MERGEABLE', candidate: Object.freeze({ kind: 'absent' }) });
+    }
+    // Human modified, producer deleted → CONFLICT
+    return Object.freeze({ status: 'CONFLICT', candidate: undefined });
+  }
+
+  if (!hasCurrent && hasGenerated) {
+    // Human deleted, producer kept → accept human delete
+    if (entriesEqual(base, generated)) {
+      return Object.freeze({ status: 'MERGEABLE', candidate: Object.freeze({ kind: 'absent' }) });
+    }
+    // Producer modified, human deleted → CONFLICT
+    return Object.freeze({ status: 'CONFLICT', candidate: undefined });
+  }
+
+  // Both present — check type compatibility
+  if (current.kind === 'tree' || generated.kind === 'tree') {
+    if (current.kind !== generated.kind) {
+      return Object.freeze({ status: 'CONFLICT', candidate: undefined });
+    }
+    // Both trees — merge as tree regardless of driver
+    const result = mergeTree({ base, current, generated, ...options });
+    return Object.freeze({ status: result.status, candidate: result.candidate });
+  }
+
+  // Both regular files — type/mode conflict check
+  if (current.type !== generated.type || current.mode !== generated.mode) {
+    return Object.freeze({ status: 'CONFLICT', candidate: undefined });
+  }
+
+  // Content identical → MERGEABLE with current
+  if (current.sha256 === generated.sha256) {
+    return Object.freeze({ status: 'MERGEABLE', candidate: current });
+  }
+
+  // Dispatch to driver
+  if (driver === 'tree') {
+    const result = mergeTree({ base, current, generated, ...options });
+    return Object.freeze({ status: result.status, candidate: result.candidate });
+  }
+
+  if (driver === 'binary') {
+    const result = mergeBinary({ base: base.bytes, current: current.bytes, generated: generated.bytes });
+    if (result.status === 'CONFLICT') {
+      return Object.freeze({ status: 'CONFLICT', candidate: undefined });
+    }
+    return Object.freeze({
+      status: 'MERGEABLE',
+      candidate: Object.freeze({
+        ...current,
+        bytes: result.bytes,
+        sha256: sha256Hex(result.bytes),
+        size: result.bytes.length,
+      }),
+    });
+  }
+
+  if (driver === 'markdown') {
+    const result = mergeMarkdown({
+      base: base.bytes, current: current.bytes, generated: generated.bytes, ...options,
+    });
+    if (result.status === 'CONFLICT' || result.status === 'STRUCTURE_INVALID') {
+      return Object.freeze({ status: result.status, candidate: undefined });
+    }
+    return Object.freeze({
+      status: 'MERGEABLE',
+      candidate: Object.freeze({
+        ...current,
+        bytes: result.bytes,
+        sha256: sha256Hex(result.bytes),
+        size: result.bytes.length,
+      }),
+    });
+  }
+
+  if (driver === 'json') {
+    const result = mergeJson({
+      base: base.bytes, current: current.bytes, generated: generated.bytes, ...options,
+    });
+    if (result.status === 'CONFLICT' || result.status === 'STRUCTURE_INVALID') {
+      return Object.freeze({ status: result.status, candidate: undefined });
+    }
+    return Object.freeze({
+      status: 'MERGEABLE',
+      candidate: Object.freeze({
+        ...current,
+        bytes: result.bytes,
+        sha256: sha256Hex(result.bytes),
+        size: result.bytes.length,
+      }),
+    });
+  }
+
+  if (driver === 'yaml') {
+    const result = mergeYaml({
+      base: base.bytes, current: current.bytes, generated: generated.bytes, ...options,
+    });
+    if (result.status === 'CONFLICT' || result.status === 'STRUCTURE_INVALID') {
+      return Object.freeze({ status: result.status, candidate: undefined });
+    }
+    return Object.freeze({
+      status: 'MERGEABLE',
+      candidate: Object.freeze({
+        ...current,
+        bytes: result.bytes,
+        sha256: sha256Hex(result.bytes),
+        size: result.bytes.length,
+      }),
+    });
+  }
+
+  // Default: text driver
+  const result = mergeText({ base: base.bytes, current: current.bytes, generated: generated.bytes });
+  if (result.status === 'CONFLICT') {
+    return Object.freeze({ status: 'CONFLICT', candidate: undefined });
+  }
+  return Object.freeze({
+    status: 'MERGEABLE',
+    candidate: Object.freeze({
+      ...current,
+      bytes: result.bytes,
+      sha256: sha256Hex(result.bytes),
+      size: result.bytes.length,
+    }),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if two entries are equal across all content dimensions.
+ *
+ * @param {object} a
+ * @param {object} b
+ * @returns {boolean}
+ */
+function entriesEqual(a, b) {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  if (a.type !== b.type) return false;
+  if (a.mode !== b.mode) return false;
+  if (a.sha256 !== b.sha256) return false;
+  if (a.manifestDigest !== b.manifestDigest) return false;
+  return true;
+}