@ikon85/agent-workflow-kit 0.18.0 → 0.20.0

package/scripts/memory-lifecycle/index.mjs

@@ -0,0 +1,247 @@
+import {
+  constants,
+  copyFile,
+  lstat,
+  mkdir,
+  readFile,
+  writeFile,
+} from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+async function exists(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function resolveCandidate(root, candidate) {
+  if (isAbsolute(candidate)) return null;
+  const normalized = normalize(candidate);
+  if (normalized === '..' || normalized.startsWith(`..${sep}`)) return null;
+  const absolute = resolve(root, normalized);
+  const boundary = `${resolve(root)}${sep}`;
+  return absolute.startsWith(boundary) ? absolute : null;
+}
+
+async function pathHasSymlink(root, candidatePath) {
+  const rootStat = await exists(root);
+  if (rootStat?.isSymbolicLink()) return true;
+
+  const relativePath = relative(resolve(root), candidatePath);
+  let current = resolve(root);
+  for (const segment of relativePath.split(sep).filter(Boolean)) {
+    current = resolve(current, segment);
+    const stat = await exists(current);
+    if (stat?.isSymbolicLink()) return true;
+  }
+  return false;
+}
+
+async function sha256(path) {
+  return createHash('sha256').update(await readFile(path)).digest('hex');
+}
+
+export async function planMemoryLifecycle({
+  activeRoot,
+  archiveRoot,
+  candidates,
+  approved = false,
+}) {
+  const actions = [];
+  const seen = new Set();
+
+  for (const candidateInput of candidates) {
+    const candidate = typeof candidateInput === 'string'
+      ? { path: candidateInput, enabled: true }
+      : { enabled: true, ...candidateInput };
+    if (seen.has(candidate.path)) continue;
+    seen.add(candidate.path);
+
+    if (!candidate.enabled) {
+      actions.push({
+        path: candidate.path,
+        action: 'skip',
+        reason: 'candidate is disabled by consumer policy',
+      });
+      continue;
+    }
+
+    const activePath = resolveCandidate(activeRoot, candidate.path);
+    const archivePath = resolveCandidate(archiveRoot, candidate.path);
+    let action = 'refuse';
+    let reason = 'outside configured roots';
+
+    if (
+      activePath
+      && archivePath
+      && !(await pathHasSymlink(activeRoot, activePath))
+      && !(await pathHasSymlink(archiveRoot, archivePath))
+    ) {
+      const active = await exists(activePath);
+      const archived = await exists(archivePath);
+      if (active && archived) {
+        const identical = active.isFile() && archived.isFile()
+          && (await sha256(activePath)) === (await sha256(archivePath));
+        action = identical ? 'preserve' : 'refuse';
+        reason = identical
+          ? 'active and archived memory already match'
+          : 'active and archived memory collide';
+      } else if (active) {
+        action = 'preserve';
+        reason = 'active memory already exists';
+      } else if (archived && approved) {
+        action = 'restore';
+        reason = 'approved archived memory is available';
+      } else if (archived) {
+        action = 'refuse';
+        reason = 'restore approval is required';
+      } else {
+        action = 'create';
+        reason = 'memory does not exist';
+      }
+    } else if (activePath && archivePath) {
+      reason = `symlink escape below ${dirname(activePath)}`;
+    }
+
+    actions.push({ path: candidate.path, action, reason });
+  }
+
+  return { dryRun: true, actions };
+}
+
+async function writeReceipt(receiptRoot, receipt) {
+  await mkdir(receiptRoot, { recursive: true });
+  const name = `memory-restore-${Date.now()}-${randomUUID()}.json`;
+  const path = resolve(receiptRoot, name);
+  await writeFile(path, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+  return path;
+}
+
+export async function executeMemoryLifecycle(options) {
+  const plan = await planMemoryLifecycle(options);
+  const verdicts = [];
+
+  for (const item of plan.actions) {
+    if (item.action !== 'restore') {
+      verdicts.push({
+        path: item.path,
+        verdict: item.action === 'refuse' ? 'refused' : 'skipped',
+        reason: item.reason,
+      });
+      continue;
+    }
+
+    const activePath = resolveCandidate(options.activeRoot, item.path);
+    const archivePath = resolveCandidate(options.archiveRoot, item.path);
+    const hash = await sha256(archivePath);
+    await mkdir(dirname(activePath), { recursive: true });
+    try {
+      await copyFile(archivePath, activePath, constants.COPYFILE_EXCL);
+      verdicts.push({ path: item.path, verdict: 'restored', sha256: hash });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      verdicts.push({
+        path: item.path,
+        verdict: 'refused',
+        reason: 'active memory appeared before restore',
+        sha256: hash,
+      });
+    }
+  }
+
+  const restored = verdicts.some(({ verdict }) => verdict === 'restored');
+  const receiptPath = restored
+    ? await writeReceipt(options.receiptRoot, {
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        source: options.source,
+        verdicts,
+      })
+    : null;
+
+  return { verdicts, receiptPath };
+}
+
+async function readJsonIfPresent(path) {
+  try {
+    const raw = await readFile(path, 'utf8');
+    return { raw, value: JSON.parse(raw) };
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function runMemoryLifecycle({
+  projectRoot = process.cwd(),
+  profilePath = 'docs/agents/workflow-capabilities.json',
+  apply = false,
+} = {}) {
+  const absoluteProfile = resolveCandidate(projectRoot, profilePath);
+  if (!absoluteProfile || await pathHasSymlink(projectRoot, absoluteProfile)) {
+    return {
+      state: 'refused',
+      dryRun: !apply,
+      actions: [{ path: profilePath, action: 'refuse', reason: 'unsafe profile path' }],
+    };
+  }
+
+  const profileDocument = await readJsonIfPresent(absoluteProfile);
+  const capability = profileDocument?.value?.memoryLifecycle;
+  if (!capability?.enabled) {
+    return { state: 'disabled', dryRun: true, actions: [] };
+  }
+
+  const activeRoot = resolveCandidate(projectRoot, capability.activeRoot);
+  const archiveRoot = resolveCandidate(projectRoot, capability.archiveRoot);
+  const receiptRoot = resolveCandidate(projectRoot, capability.receiptRoot);
+  if (!activeRoot || !archiveRoot || !receiptRoot) {
+    return {
+      state: 'refused',
+      dryRun: !apply,
+      actions: [{ path: 'memoryLifecycle', action: 'refuse', reason: 'configured root escapes project' }],
+    };
+  }
+
+  const consumerManifest = await readJsonIfPresent(
+    resolve(projectRoot, 'agent-workflow-kit.json'),
+  );
+  const source = {
+    kitVersion: consumerManifest?.value?.kitVersion ?? 'unknown',
+    bundleVersion: consumerManifest
+      ? `sha256:${createHash('sha256').update(consumerManifest.raw).digest('hex')}`
+      : 'unknown',
+  };
+  const options = {
+    activeRoot,
+    archiveRoot,
+    receiptRoot,
+    candidates: capability.memories ?? [],
+    approved: capability.approvals?.restore === true,
+    source,
+  };
+  if (apply) {
+    return { state: 'applied', dryRun: false, ...await executeMemoryLifecycle(options) };
+  }
+  return { state: 'planned', ...await planMemoryLifecycle(options) };
+}
+
+async function main(argv) {
+  const apply = argv.includes('--apply');
+  const profileFlag = argv.indexOf('--profile');
+  const profilePath = profileFlag >= 0 ? argv[profileFlag + 1] : undefined;
+  const result = await runMemoryLifecycle({ apply, profilePath });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/memory-lifecycle/memory-lifecycle.test.mjs

@@ -0,0 +1,170 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, readdir, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  executeMemoryLifecycle,
+  planMemoryLifecycle,
+  runMemoryLifecycle,
+} from './index.mjs';
+
+test('dry-run classifies each candidate once without writing', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(archiveRoot, 'returning.md'), 'archived memory\n');
+
+  const plan = await planMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    candidates: ['new.md', 'returning.md'],
+    approved: true,
+  });
+
+  assert.deepEqual(plan.actions.map(({ path, action }) => [path, action]), [
+    ['new.md', 'create'],
+    ['returning.md', 'restore'],
+  ]);
+  await assert.rejects(readFile(join(activeRoot, 'new.md'), 'utf8'), { code: 'ENOENT' });
+  await assert.rejects(readFile(join(activeRoot, 'returning.md'), 'utf8'), { code: 'ENOENT' });
+});
+
+test('dry-run refuses unsafe roots, collisions, outside paths, and unapproved restores', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  await mkdir(activeRoot, { recursive: true });
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(activeRoot, 'collision.md'), 'active\n');
+  await writeFile(join(archiveRoot, 'collision.md'), 'different archive\n');
+  await writeFile(join(archiveRoot, 'approval.md'), 'archived\n');
+
+  const plan = await planMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    candidates: ['../foreign.md', 'collision.md', 'approval.md'],
+  });
+  assert.deepEqual(plan.actions.map(({ action }) => action), ['refuse', 'refuse', 'refuse']);
+
+  const linkedActive = join(root, 'linked-active');
+  await symlink(activeRoot, linkedActive, 'dir');
+  const symlinkPlan = await planMemoryLifecycle({
+    activeRoot: linkedActive,
+    archiveRoot,
+    candidates: ['safe.md'],
+    approved: true,
+  });
+  assert.equal(symlinkPlan.actions[0].action, 'refuse');
+});
+
+test('execute restores without removing the archive and writes a content-free receipt', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  const receiptRoot = join(root, 'receipts');
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(archiveRoot, 'returning.md'), 'private memory contents\n');
+
+  const result = await executeMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    receiptRoot,
+    candidates: ['returning.md'],
+    approved: true,
+    source: { kitVersion: '1.2.3', bundleVersion: 'bundle-abc' },
+  });
+
+  assert.equal(await readFile(join(activeRoot, 'returning.md'), 'utf8'), 'private memory contents\n');
+  assert.equal(await readFile(join(archiveRoot, 'returning.md'), 'utf8'), 'private memory contents\n');
+  assert.equal(result.verdicts[0].verdict, 'restored');
+  const [receiptName] = await readdir(receiptRoot);
+  const receiptText = await readFile(join(receiptRoot, receiptName), 'utf8');
+  const receipt = JSON.parse(receiptText);
+  assert.equal(receipt.schemaVersion, 1);
+  assert.deepEqual(receipt.source, { kitVersion: '1.2.3', bundleVersion: 'bundle-abc' });
+  assert.match(receipt.verdicts[0].sha256, /^[a-f0-9]{64}$/);
+  assert.ok(!receiptText.includes('private memory contents'));
+});
+
+test('rerun preserves restored memory and never overwrites or duplicates its receipt', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  const receiptRoot = join(root, 'receipts');
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(archiveRoot, 'stable.md'), 'stable\n');
+  const options = {
+    activeRoot,
+    archiveRoot,
+    receiptRoot,
+    candidates: ['stable.md'],
+    approved: true,
+    source: { kitVersion: '1.2.3', bundleVersion: 'bundle-abc' },
+  };
+
+  const first = await executeMemoryLifecycle(options);
+  const receiptBefore = await readFile(first.receiptPath, 'utf8');
+  const second = await executeMemoryLifecycle(options);
+
+  assert.equal(second.verdicts[0].verdict, 'skipped');
+  assert.equal(second.receiptPath, null);
+  assert.deepEqual(await readdir(receiptRoot), [first.receiptPath.split('/').at(-1)]);
+  assert.equal(await readFile(first.receiptPath, 'utf8'), receiptBefore);
+});
+
+test('disabled and duplicate candidates produce one explicit skip verdict per path', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const plan = await planMemoryLifecycle({
+    activeRoot: join(root, 'active'),
+    archiveRoot: join(root, 'archive'),
+    candidates: [
+      { path: 'later.md', enabled: false },
+      { path: 'later.md', enabled: false },
+    ],
+    approved: true,
+  });
+
+  assert.deepEqual(plan.actions, [{
+    path: 'later.md',
+    action: 'skip',
+    reason: 'candidate is disabled by consumer policy',
+  }]);
+});
+
+test('missing or disabled consumer profile is a no-write disabled result', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+
+  assert.deepEqual(await runMemoryLifecycle({ projectRoot: root }), {
+    state: 'disabled',
+    dryRun: true,
+    actions: [],
+  });
+  await assert.rejects(readFile(join(root, '.memory'), 'utf8'), { code: 'ENOENT' });
+});
+
+test('frozen Testreporter parity profile classifies all three native memory rows', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const fixture = JSON.parse(await readFile(new URL(
+    '../../test/fixtures/memory-lifecycle/testreporter-parity.json',
+    import.meta.url,
+  )));
+  const activeRoot = join(root, fixture.activeRoot);
+  const archiveRoot = join(root, fixture.archiveRoot);
+  await mkdir(archiveRoot, { recursive: true });
+  for (const { path } of fixture.memories) {
+    await writeFile(join(archiveRoot, path), `${path}\n`);
+  }
+
+  const plan = await planMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    candidates: fixture.memories,
+    approved: fixture.approvals.restore,
+  });
+
+  assert.equal(plan.actions.length, 3);
+  assert.deepEqual(plan.actions.map(({ action }) => action), ['restore', 'restore', 'restore']);
+});

package/scripts/worktree-lifecycle/README.md

@@ -0,0 +1,37 @@
+# Worktree Lifecycle contract
+
+The consumer-owned `docs/agents/workflow-capabilities.json` profile activates
+one Worktree Lifecycle. `profile.py` loads that policy. `core.py` is the only
+place that derives repository facts and decides whether an event emits, allows,
+or blocks. Surface adapters translate hook payloads and render the decision;
+they do not carry a second branch regex, worktree traversal, or failure policy.
+
+## Profile
+
+`worktreeLifecycle` supports:
+
+- `enabled`: explicit activation gate.
+- `worktreeRoot`, `branchTemplate`, `pathTemplate`, and `branchRegex`: consumer
+  naming and location policy.
+- `mainBranches` and `protectedBranches`: branches guarded in the main checkout.
+- `setupEntry` and ordered `setupSteps`: the portable setup command and project
+  setup sequence.
+- `riskyCommandPatterns`: commands that must target the active linked worktree.
+
+Unknown or malformed events fail open without changing repository state.
+Security-sensitive, profile-matched edits and commands fail closed only when
+the core proves the target is unsafe.
+
+## Adapters
+
+| Adapter | Event | Outcome |
+|---|---|---|
+| `branch-context.py` | SessionStart | emits branch, issue, status, and active-worktree facts |
+| `branch-watch.py` | PostToolUse | emits the same facts after a branch-changing command |
+| `enforce-worktree.py` | PreToolUse | blocks tracked main-checkout edits and cross-worktree leaks |
+| `enforce-worktree-cwd.py` | PreToolUse | blocks verification or Git mutation in the wrong checkout |
+| `enforce-worktree-discipline.py` | PreToolUse | routes issue-branch creation through the configured setup entry |
+
+Claude hook wiring and any Codex adaptation consume this same profile and core.
+An adapter may change only the surface event envelope; it must preserve the
+core verdict and message.