@haposoft/cafekit 0.14.2 → 0.15.0

package/src/codex/hooks/lib/inspect-paths.cjs

@@ -0,0 +1,199 @@
+'use strict';
+
+const BLOCKED_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.next', '.nuxt', '.output',
+  '__pycache__', '.venv', 'venv', 'vendor', 'target',
+  '.git', 'coverage', '.nyc_output'
+]);
+const BROAD_GLOBS = [/^\*\*\/\*$/, /^\*\*\.\w+$/, /^\*\*\/\*\.\w+$/];
+const PATH_KEYS = new RegExp(
+  '^(?:file_?paths?|paths?|search_?paths?|'
+  + '(?:source|target|destination)_?paths?|dirs?|director(?:y|ies)|'
+  + 'folders?|cwd|root|locations?|uris?)$',
+  'i'
+);
+const GLOB_KEYS = /(?:^|_)(?:glob|globs|pattern|patterns)$/i;
+function clean(value) {
+  return String(value || '').trim().replace(/^['"`]+|['"`,:]+$/g, '');
+}
+function blockedSegment(value) {
+  return clean(value)
+    .replace(/\\/g, '/')
+    .split('/')
+    .find((segment) => BLOCKED_DIRS.has(segment));
+}
+function isBroadGlob(value) {
+  const candidate = clean(value);
+  return BROAD_GLOBS.some((rule) => rule.test(candidate));
+}
+function collectStructured(value, key, paths, globs) {
+  if (typeof value === 'string') {
+    if (PATH_KEYS.test(key)) paths.push(value);
+    if (GLOB_KEYS.test(key)) globs.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (PATH_KEYS.test(key)) paths.push(...value.filter((item) => typeof item === 'string'));
+    if (GLOB_KEYS.test(key)) globs.push(...value.filter((item) => typeof item === 'string'));
+    for (const item of value) collectStructured(item, '', paths, globs);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [childKey, child] of Object.entries(value)) {
+    collectStructured(child, childKey, paths, globs);
+  }
+}
+function shellTokens(command) {
+  const tokens = [];
+  let token = '';
+  let quote = '';
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (quote) {
+      if (char === quote) quote = '';
+      else if (char === '\\' && quote === '"' && index + 1 < command.length) {
+        token += command[index += 1];
+      } else token += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === '\n') {
+      if (token) tokens.push(token);
+      token = '';
+      tokens.push('|');
+    } else if (/\s/.test(char)) {
+      if (token) tokens.push(token);
+      token = '';
+    } else if (';&|'.includes(char)) {
+      if (token) tokens.push(token);
+      token = '';
+      const pair = command.slice(index, index + 2);
+      if (pair === '&&' || pair === '||') index += 1;
+      tokens.push('|');
+    } else {
+      token += char;
+    }
+  }
+  if (token) tokens.push(token);
+  return tokens;
+}
+function commandGroups(command) {
+  const groups = [[]];
+  for (const token of shellTokens(command)) {
+    if (token === '|') groups.push([]);
+    else groups[groups.length - 1].push(clean(token));
+  }
+  return groups.filter((group) => group.length);
+}
+
+function positional(tokens, optionsWithValue = new Set()) {
+  const out = [];
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (optionsWithValue.has(token)) index += 1;
+    else if (!token.startsWith('-') || token === '-') out.push(token);
+  }
+  return out;
+}
+
+function readerOptionPaths(name, tokens) {
+  if (!['rg', 'grep', 'sed'].includes(name)) return [];
+  const paths = [];
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '-f' || token === '--file') {
+      if (tokens[index + 1]) paths.push(tokens[index + 1]);
+      index += 1;
+    } else if (token.startsWith('--file=')) {
+      paths.push(token.slice('--file='.length));
+    }
+  }
+  return paths;
+}
+
+function findRoots(tokens) {
+  const roots = [];
+  let index = 1;
+  while (['-H', '-L', '-P'].includes(tokens[index]) || /^-O\d+$/.test(tokens[index] || '')) {
+    index += 1;
+  }
+  if (tokens[index] === '-D') index += 2;
+  if (tokens[index] === '--') index += 1;
+  for (; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.startsWith('-') || ['!', '(', ')'].includes(token)) break;
+    roots.push(token);
+  }
+  return roots;
+}
+
+function commandPaths(group, globs) {
+  const commandIndex = group.findIndex((token) => (
+    token && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)
+  ));
+  if (commandIndex < 0) return [];
+  const tokens = group.slice(commandIndex);
+  while (['sudo', 'env', 'time', 'command'].includes(tokens[0])) tokens.shift();
+  if (!tokens.length) return [];
+  const name = tokens[0].replace(/\\/g, '/').split('/').pop();
+  const optionPaths = readerOptionPaths(name, tokens);
+
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '-g' || token === '--glob' || token === '--iglob') {
+      if (tokens[index + 1]) globs.push(tokens[index + 1]);
+    } else if (/^--(?:i?glob)=/.test(token)) {
+      globs.push(token.slice(token.indexOf('=') + 1));
+    }
+  }
+
+  if (name === 'rg' || name === 'grep') {
+    const values = positional(tokens, new Set([
+      '-e', '--regexp', '-f', '--file', '-g', '--glob', '--iglob',
+      '-t', '--type', '-T', '--type-not'
+    ]));
+    const explicitPattern = tokens.some((token) => token === '-e' || token === '--regexp');
+    const fileMode = tokens.includes('--files');
+    return [...optionPaths, ...(explicitPattern || fileMode ? values : values.slice(1))];
+  }
+  if (name === 'sed') {
+    const values = positional(tokens, new Set(['-e', '--expression', '-f', '--file']));
+    const explicitScript = tokens.some((token) => (
+      ['-e', '--expression', '-f', '--file'].includes(token)
+    ));
+    return [...optionPaths, ...(explicitScript ? values : values.slice(1))];
+  }
+  if (name === 'find') return findRoots(tokens);
+  if (['cat', 'head', 'tail', 'ls', 'wc', 'du', 'tree', 'file', 'stat', 'cd', 'pushd', 'source', '.'].includes(name)) {
+    return positional(tokens, new Set(['-n', '--lines', '-c', '--bytes']));
+  }
+  return tokens.filter((token) => (
+    /^(?:\.{0,2}[\\/]|~[\\/])/.test(token)
+    || (token.includes('/') && blockedSegment(token))
+  ));
+}
+
+function inspectInput(input) {
+  const paths = [];
+  const globs = [];
+  collectStructured(input, '', paths, globs);
+  const command = typeof input?.command === 'string'
+    ? input.command
+    : typeof input?.cmd === 'string' ? input.cmd : '';
+  for (const group of commandGroups(command)) {
+    paths.push(...commandPaths(group, globs));
+  }
+  return {
+    broadGlob: globs.find(isBroadGlob),
+    blockedPath: paths.map((requested) => ({
+      requested,
+      blocked: blockedSegment(requested)
+    })).find((result) => result.blocked)
+  };
+}
+
+module.exports = {
+  BLOCKED_DIRS,
+  inspectInput
+};

package/src/codex/hooks/lib/privacy-state.cjs

@@ -0,0 +1,199 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const TTL_MS = 5 * 60 * 1000;
+const APPROVAL_PREFIX = 'APPROVE CAFEKIT PRIVACY ';
+function stateDir(projectRoot) {
+  return path.join(projectRoot, '.codex', 'hooks', '.privacy');
+}
+function hash(value) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}
+function pathKey(filePath, sessionCwd) {
+  const requested = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(sessionCwd, filePath);
+  let target = requested;
+  try {
+    target = fs.realpathSync(requested);
+  } catch {
+    // Missing or virtual paths are still bound to their normalized request path.
+  }
+  return hash(path.normalize(target));
+}
+function requestPaths(filePaths, filePath) {
+  const values = Array.isArray(filePaths) ? filePaths : [filePath];
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.trim()))];
+}
+function requestPathKeys(filePaths, sessionCwd) {
+  return [...new Set(filePaths.map((filePath) => pathKey(filePath, sessionCwd)))].sort();
+}
+function samePathKeys(left, right) {
+  return Array.isArray(left)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+function displayNames(filePaths) {
+  const names = [...new Set(filePaths.map((filePath) => path.basename(filePath)))].sort();
+  return names.length <= 3
+    ? names.join(', ')
+    : `${names.slice(0, 3).join(', ')} (+${names.length - 3} more)`;
+}
+
+function atomicWrite(file, payload) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const temp = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(payload)}\n`, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function cleanup(projectRoot, now = Date.now()) {
+  const dir = stateDir(projectRoot);
+  if (!fs.existsSync(dir)) return;
+  for (const name of fs.readdirSync(dir)) {
+    if (!/^(pending|token)-[a-f0-9]+\.json$/.test(name)) continue;
+    const file = path.join(dir, name);
+    const record = readJson(file);
+    if (!record || Number(record.expiresAt) <= now) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // Another hook may have consumed it.
+      }
+    }
+  }
+}
+
+function clearState(projectRoot) {
+  const dir = stateDir(projectRoot);
+  try {
+    if (!fs.existsSync(dir)) return;
+    for (const name of fs.readdirSync(dir)) {
+      if (/^(pending|token)-[a-f0-9]+\.json$/.test(name)) {
+        try { fs.unlinkSync(path.join(dir, name)); } catch { /* concurrently consumed */ }
+      }
+    }
+  } catch {
+    // Session boundaries invalidate best-effort state without blocking startup.
+  }
+}
+
+function createPending({
+  projectRoot,
+  sessionCwd,
+  sessionId,
+  filePaths,
+  filePath,
+  toolName
+}) {
+  cleanup(projectRoot);
+  if (!sessionId) throw new Error('A Codex session ID is required');
+  const paths = requestPaths(filePaths, filePath);
+  if (paths.length === 0) throw new Error('At least one sensitive path is required');
+  const requestId = crypto.randomBytes(12).toString('hex');
+  const record = {
+    version: 2,
+    requestId,
+    sessionId: String(sessionId || ''),
+    pathKeys: requestPathKeys(paths, sessionCwd),
+    displayName: displayNames(paths),
+    toolName: String(toolName || ''),
+    expiresAt: Date.now() + TTL_MS
+  };
+  atomicWrite(path.join(stateDir(projectRoot), `pending-${requestId}.json`), record);
+  return record;
+}
+
+function approvePending({ projectRoot, sessionId, requestId }) {
+  cleanup(projectRoot);
+  if (!sessionId) return { ok: false, reason: 'session' };
+  if (!/^[a-f0-9]{24}$/.test(requestId)) return { ok: false, reason: 'invalid' };
+
+  const pendingFile = path.join(stateDir(projectRoot), `pending-${requestId}.json`);
+  const record = readJson(pendingFile);
+  if (!record) return { ok: false, reason: 'missing' };
+  if (record.sessionId !== String(sessionId || '')) return { ok: false, reason: 'session' };
+  if (Number(record.expiresAt) <= Date.now()) return { ok: false, reason: 'expired' };
+
+  try {
+    fs.unlinkSync(pendingFile);
+  } catch {
+    return { ok: false, reason: 'consumed' };
+  }
+
+  atomicWrite(path.join(stateDir(projectRoot), `token-${requestId}.json`), {
+    version: 2,
+    requestId,
+    sessionId: record.sessionId,
+    pathKeys: record.pathKeys,
+    toolName: record.toolName,
+    expiresAt: Math.min(record.expiresAt, Date.now() + TTL_MS)
+  });
+  return { ok: true, displayName: record.displayName };
+}
+
+function consumeToken({
+  projectRoot,
+  sessionCwd,
+  sessionId,
+  filePaths,
+  filePath,
+  toolName
+}) {
+  cleanup(projectRoot);
+  if (!sessionId) return false;
+  const dir = stateDir(projectRoot);
+  if (!fs.existsSync(dir)) return false;
+  const paths = requestPaths(filePaths, filePath);
+  if (paths.length === 0) return false;
+  const expectedPaths = requestPathKeys(paths, sessionCwd);
+
+  for (const name of fs.readdirSync(dir)) {
+    if (!/^token-[a-f0-9]{24}\.json$/.test(name)) continue;
+    const tokenFile = path.join(dir, name);
+    const token = readJson(tokenFile);
+    if (
+      !token ||
+      token.sessionId !== String(sessionId || '') ||
+      !samePathKeys(token.pathKeys, expectedPaths) ||
+      token.toolName !== String(toolName || '') ||
+      Number(token.expiresAt) <= Date.now()
+    ) {
+      continue;
+    }
+
+    const claimed = `${tokenFile}.claimed-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+    try {
+      fs.renameSync(tokenFile, claimed);
+      fs.unlinkSync(claimed);
+      return true;
+    } catch {
+      // Only one concurrent tool invocation can rename and consume this token.
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  APPROVAL_PREFIX,
+  TTL_MS,
+  pathKey,
+  createPending,
+  approvePending,
+  consumeToken,
+  cleanup,
+  clearState
+};

package/src/codex/hooks/lib/spec-receipt.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const EVIDENCE_NAMES = [
+  'Evidence',
+  'Task Test Plan & Verification Evidence',
+  'Verification & Evidence'
+];
+const PASS_MARKER = /^\s*Verification:\s*PASS\s*$/m;
+const LEGACY_SUCCESS = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
+const EXPLICIT_FAILURE = /\bFAIL(?:ED|URE|URES|ING)?\b|tests?\s+failed|exit\s+code\s*[:=]?\s*[1-9]\d*|\b0\s+tests?\b/i;
+
+function evidenceBody(text) {
+  const lines = text.split('\n');
+  let start = -1;
+  let level = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^(#{2,3})\s+(.+?)\s*$/);
+    if (match && EVIDENCE_NAMES.includes(match[2])) {
+      start = index + 1;
+      level = match[1].length;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let index = start; index < lines.length; index += 1) {
+    const heading = lines[index].match(/^(#{1,6})\s+/);
+    if (heading && heading[1].length <= level) {
+      end = index;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n');
+}
+
+function safeTaskFile(featureDir, taskPath) {
+  const target = path.resolve(featureDir, taskPath);
+  const relative = path.relative(featureDir, target);
+  return !relative.startsWith('..') && !path.isAbsolute(relative)
+    ? target
+    : null;
+}
+
+function checkReceipt(featureDir, taskPath, task) {
+  const failures = [];
+  const file = safeTaskFile(featureDir, taskPath);
+  if (!file || !fs.existsSync(file)) return ['a'];
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return ['a']; }
+
+  const status = text.split('\n')
+    .find((line) => /^\s*(?:\*\*)?Status(?:\*\*)?\s*:/i.test(line));
+  if (!status || !/\bdone\b/i.test(status)) failures.push('a');
+
+  const body = evidenceBody(text);
+  if (body === null) {
+    failures.push('b');
+  } else if (
+    /\{\{[^}]+\}\}/.test(body)
+    || EXPLICIT_FAILURE.test(body)
+    || !(PASS_MARKER.test(body) || LEGACY_SUCCESS.test(body))
+  ) {
+    failures.push('c');
+  }
+
+  const completedAt = task?.completed_at;
+  if (
+    typeof completedAt !== 'string'
+    || !/^\d{4}-\d{2}-\d{2}T/.test(completedAt)
+    || Number.isNaN(Date.parse(completedAt))
+  ) failures.push('d');
+  return failures;
+}
+
+module.exports = { checkReceipt };

package/src/codex/hooks/lib/spec-utils.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectPath } = require('./hook-context.cjs');
+
+function specsDirectory(projectRoot, runtime) {
+  return resolveProjectPath(
+    projectRoot,
+    runtime.paths?.specs,
+    'specs'
+  );
+}
+
+function findActiveSpec(projectRoot, runtime) {
+  const specsDir = specsDirectory(projectRoot, runtime);
+  if (!fs.existsSync(specsDir)) return null;
+  const entries = fs.readdirSync(specsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
+    const file = path.join(specsDir, entry.name, 'spec.json');
+    if (!fs.existsSync(file)) continue;
+    try {
+      const spec = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (spec.status === 'in_progress' || spec.status === 'in-progress') {
+        return { featureName: entry.name, spec, specsDir };
+      }
+    } catch {
+      // Ignore an unrelated malformed spec and continue discovery.
+    }
+  }
+  return null;
+}
+
+function taskStatusMap(spec) {
+  return Object.fromEntries(
+    Object.entries(spec.task_registry || {}).map(([taskPath, task]) => [
+      taskPath,
+      task?.status || 'pending'
+    ])
+  );
+}
+
+module.exports = {
+  findActiveSpec,
+  specsDirectory,
+  taskStatusMap
+};

package/src/codex/hooks/lib/state-store.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { atomicWrite } = require('./hook-context.cjs');
+
+const MAX_ARCHIVES = 5;
+const MAX_AGENTS = 3;
+const MAX_FILES = 5;
+const WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+
+function sessionKey(sessionId) {
+  if (typeof sessionId !== 'string' || !sessionId.trim()) return null;
+  return crypto.createHash('sha256').update(sessionId).digest('hex');
+}
+
+function stateDir(projectRoot, sessionId) {
+  const key = sessionKey(sessionId);
+  return key
+    ? path.join(projectRoot, '.codex', 'session-state', key)
+    : null;
+}
+
+function acquireLock(dir) {
+  const lock = path.join(dir, '.write-lock');
+  fs.mkdirSync(dir, { recursive: true });
+  const deadline = Date.now() + 3000;
+
+  while (Date.now() < deadline) {
+    try {
+      fs.mkdirSync(lock);
+      return () => {
+        try { fs.rmdirSync(lock); } catch { /* already released */ }
+      };
+    } catch (error) {
+      if (error.code !== 'EEXIST') return null;
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > 15000) {
+          fs.rmSync(lock, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      Atomics.wait(WAIT_BUFFER, 0, 0, 20);
+    }
+  }
+  return null;
+}
+
+function withStateLock(projectRoot, sessionId, callback) {
+  const dir = stateDir(projectRoot, sessionId);
+  if (!dir) return false;
+  const release = acquireLock(dir);
+  if (!release) return false;
+  try {
+    callback(dir);
+    return true;
+  } finally {
+    release();
+  }
+}
+
+function readData(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'data.json'), 'utf8'));
+  } catch {
+    return { todos: [], agentResults: [] };
+  }
+}
+
+function runGit(projectRoot, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function refreshGit(data, projectRoot) {
+  data.branch = runGit(projectRoot, ['branch', '--show-current'])
+    || runGit(projectRoot, ['rev-parse', '--short', 'HEAD']);
+  const changed = runGit(projectRoot, ['diff', '--name-only', 'HEAD'])
+    || runGit(projectRoot, ['diff', '--name-only']);
+  const untracked = runGit(projectRoot, ['ls-files', '--others', '--exclude-standard']);
+  data.modifiedFiles = [...new Set(
+    `${changed}\n${untracked}`.split('\n').map((item) => item.trim()).filter(Boolean)
+  )].slice(0, MAX_FILES);
+  data.timestamp = new Date().toISOString();
+  return data;
+}
+
+function markdown(data) {
+  const todos = Array.isArray(data.todos) ? data.todos : [];
+  const done = todos.filter((todo) => ['completed', 'done'].includes(todo.status));
+  const pending = todos.filter((todo) => !['completed', 'done'].includes(todo.status));
+  const agents = (data.agentResults || []).slice(-MAX_AGENTS);
+  const files = data.modifiedFiles || [];
+  const lines = [
+    '# Session State',
+    `<!-- Generated: ${data.timestamp || new Date().toISOString()} -->`,
+    `<!-- Branch: ${data.branch || 'unknown'} -->`,
+    '',
+    '## What Worked (Verified)',
+    ...(done.length ? done.map((todo) => `- ${todo.content}`) : ['- (No completed tasks recorded)']),
+    '',
+    "## What's Left",
+    ...(pending.length ? pending.map((todo) => `- [ ] ${todo.content}`) : ['- (No pending tasks recorded)']),
+    ''
+  ];
+
+  if (data.lastToolEvent) {
+    lines.push('## Latest Tracked Tool', `- ${data.lastToolEvent}`, '');
+  }
+  if (data.lastAssistant) {
+    lines.push('## Latest Assistant Message', data.lastAssistant, '');
+  }
+  for (const agent of agents) {
+    lines.push(
+      `## Agent Result: ${agent.type || 'unknown'} (${agent.id || 'unknown'})`,
+      agent.message || '- Completed without a result message.',
+      ''
+    );
+  }
+  lines.push(
+    '## Key Files Modified',
+    ...(files.length ? files.map((file) => `- ${file}`) : ['- (No file changes detected)']),
+    ''
+  );
+  return lines.join('\n');
+}
+
+function writeData(dir, data) {
+  data.agentResults = (data.agentResults || []).slice(-MAX_AGENTS);
+  atomicWrite(path.join(dir, 'data.json'), `${JSON.stringify(data, null, 2)}\n`);
+  atomicWrite(path.join(dir, 'latest.md'), markdown(data));
+}
+
+function archive(dir) {
+  const latest = path.join(dir, 'latest.md');
+  if (!fs.existsSync(latest)) return;
+  const archiveDir = path.join(dir, 'archive');
+  fs.mkdirSync(archiveDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/\D/g, '').slice(0, 14);
+  fs.copyFileSync(latest, path.join(archiveDir, `${stamp}-${process.pid}.md`));
+  const files = fs.readdirSync(archiveDir).filter((name) => name.endsWith('.md')).sort();
+  while (files.length > MAX_ARCHIVES) {
+    fs.unlinkSync(path.join(archiveDir, files.shift()));
+  }
+}
+
+module.exports = {
+  archive,
+  readData,
+  refreshGit,
+  stateDir,
+  withStateLock,
+  writeData
+};