@ikon85/agent-workflow-kit 0.32.0 → 0.33.0

package/src/lib/updateCandidate.mjs

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { access, cp, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { access, cp, lstat, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { promisify } from 'node:util';
@@ -12,10 +12,15 @@ import {
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
   indexByPath, readManifest, writeManifest,
 } from './manifest.mjs';
-import { checkSkill, evaluateCapability } from '../../scripts/readiness.mjs';
+import { checkSkill, evaluateCapability, inspectProdSections } from '../../scripts/readiness.mjs';
 
 const run = promisify(execFile);
 const exists = (path) => access(path).then(() => true, () => false);
+const pathEntryExists = (path) => lstat(path).then(() => true, (error) => {
+  if (error.code === 'ENOENT') return false;
+  throw error;
+});
+const MIGRATABLE_INSTRUCTION_PATHS = new Set(['CLAUDE.md', 'AGENTS.md']);
 
 /** Copy a verification candidate without duplicating git metadata or dependencies. */
 export async function stageConsumer(consumerRoot) {
@@ -40,7 +45,11 @@ export async function activateCandidate({
 }) {
   const changed = [...preview.added, ...preview.updated];
   const generated = preview.generated ?? [];
-  const touched = [...changed, ...generated, ...preview.deleted, CONSUMER_MANIFEST_NAME];
+  const migrations = preview.migrations ?? [];
+  const touched = [
+    ...changed, ...generated, ...migrations.map(({ path }) => path),
+    ...preview.deleted, CONSUMER_MANIFEST_NAME,
+  ];
   const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!currentManifest.equals(consumerManifestBefore)) {
     throw new Error('consumer manifest changed during verification');
@@ -58,6 +67,11 @@ export async function activateCandidate({
       throw new Error(`generated candidate hash mismatch: ${path}`);
     }
   }
+  for (const migration of migrations) {
+    if (await sha256File(join(candidateRoot, migration.path)) !== migration.afterSha256) {
+      throw new Error(`migrated candidate hash mismatch: ${migration.path}`);
+    }
+  }
   await assertConsumerStillMatchesPreview(consumerRoot, preview);
   const rollback = new Map();
   for (const path of touched) rollback.set(path, await snapshot(join(consumerRoot, path)));
@@ -68,6 +82,9 @@ export async function activateCandidate({
     for (const path of generated) {
       await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
     }
+    for (const { path } of migrations) {
+      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
+    }
     await afterGenerated();
     for (const path of preview.deleted) await rm(join(consumerRoot, path), { force: true });
     await writeAtomic(
@@ -105,6 +122,17 @@ async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
       throw new Error(`consumer changed during verification: ${path}`);
     }
   }
+  for (const migration of preview.migrations ?? []) {
+    const present = await pathEntryExists(join(consumerRoot, migration.path));
+    if (present) await validateConsumerFile(consumerRoot, migration.path);
+    else if (!MIGRATABLE_INSTRUCTION_PATHS.has(migration.path)) {
+      throw new Error(`unsafe consumer path: ${migration.path}`);
+    }
+    const current = present ? await sha256File(join(consumerRoot, migration.path)) : null;
+    if (current !== migration.beforeSha256) {
+      throw new Error(`consumer changed during verification: ${migration.path}`);
+    }
+  }
   for (const path of [...preview.updated, ...preview.deleted]) {
     const prior = installed.get(path);
     const current = await exists(join(consumerRoot, path))
@@ -144,6 +172,9 @@ export async function adoptReadinessCandidate({ candidateRoot, consumerRoot, pri
     }
     await writeManifest(manifestPath, { ...manifest, installed });
   }
+  const { migrations, migrationConflicts } = await migrateProdSections({
+    candidateRoot, consumerRoot, nextManifest,
+  });
   const before = await readinessSnapshot(consumerRoot, priorManifest);
   const after = await readinessSnapshot(candidateRoot, nextManifest);
   const incompatible = Object.entries(after.skills)
@@ -151,7 +182,50 @@ export async function adoptReadinessCandidate({ candidateRoot, consumerRoot, pri
       && before.skills[skill] && current.verdict === 'blocked')
     .map(([skill]) => skill)
     .sort();
-  return { generated, availability: readinessDiff(before, after), incompatible };
+  return {
+    generated,
+    migrations,
+    migrated: migrations.map(({ path }) => path),
+    migrationConflicts,
+    availability: readinessDiff(before, after),
+    incompatible,
+  };
+}
+
+async function migrateProdSections({ candidateRoot, consumerRoot, nextManifest }) {
+  const paths = [...new Set(Object.values(nextManifest?.readiness?.capabilities ?? {})
+    .flatMap(({ evidence }) => evidence?.type === 'prod-section' ? evidence.paths ?? [] : []))];
+  if (paths.length < 2) return { migrations: [], migrationConflicts: [] };
+  if (paths.some((path) => !MIGRATABLE_INSTRUCTION_PATHS.has(path))) {
+    return { migrations: [], migrationConflicts: paths };
+  }
+  const sections = await inspectProdSections(candidateRoot, paths);
+  const invalid = sections.filter(({ state }) => state === 'invalid');
+  const validBodies = [...new Set(
+    sections.filter(({ state }) => state === 'valid').map(({ body }) => body),
+  )];
+  if (invalid.length || validBodies.length > 1) {
+    return { migrations: [], migrationConflicts: paths };
+  }
+  if (validBodies.length !== 1) return { migrations: [], migrationConflicts: [] };
+
+  const body = validBodies[0];
+  const migrations = [];
+  for (const entry of sections.filter(({ state }) => state === 'missing')) {
+    const candidatePath = join(candidateRoot, entry.path);
+    const present = await pathEntryExists(candidatePath);
+    if (present) await validateConsumerFile(candidateRoot, entry.path);
+    const before = present ? await readFile(candidatePath, 'utf8') : '';
+    const separator = before && !before.endsWith('\n') ? '\n\n' : (before ? '\n' : '');
+    await writeAtomic(candidatePath, `${before}${separator}## Prod\n\n${body}\n`);
+    migrations.push({
+      path: entry.path,
+      beforeSha256: await exists(join(consumerRoot, entry.path))
+        ? await sha256File(join(consumerRoot, entry.path)) : null,
+      afterSha256: await sha256File(candidatePath),
+    });
+  }
+  return { migrations, migrationConflicts: [] };
 }
 
 function readinessStubPaths(manifest) {

package/src/lib/waveClaim.mjs

@@ -0,0 +1,134 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+const CONTRACT_VERSION = 1;
+
+async function git(repoRoot, args, options = {}) {
+  return exec('git', args, { cwd: repoRoot, encoding: 'utf8', ...options });
+}
+
+// execFile has no `input` option — the child's stdin would stay open and a
+// stdin-reading plumbing command (`git mktag`) would block forever. Spawn and
+// close stdin explicitly instead.
+function gitWithInput(repoRoot, args, input) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd: repoRoot });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(new Error(`git ${args.join(' ')} failed (${code}): ${stderr.trim()}`));
+    });
+    child.stdin.end(input);
+  });
+}
+
+function claimRef(anchor) {
+  if (typeof anchor !== 'string' || !/^[1-9][0-9]*$/.test(anchor)) {
+    throw new TypeError('anchor must be a positive issue number string');
+  }
+  return `refs/tags/wave-active/${anchor}`;
+}
+
+function validateOwner(owner) {
+  if (typeof owner !== 'string' || owner.trim() === '') {
+    throw new TypeError('owner must be a non-empty string');
+  }
+}
+
+async function resolveRef(repoRoot, ref) {
+  try {
+    const { stdout } = await git(repoRoot, ['rev-parse', '--verify', ref]);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+async function readClaimAt(repoRoot, ref, tagOid) {
+  const { stdout: type } = await git(repoRoot, ['cat-file', '-t', tagOid]);
+  if (type.trim() !== 'tag') throw new Error(`${ref} is not an annotated wave claim`);
+  const { stdout } = await git(repoRoot, ['cat-file', '-p', tagOid]);
+  const separator = stdout.indexOf('\n\n');
+  if (separator < 0) throw new Error(`${ref} has no ownership payload`);
+  let claim;
+  try {
+    claim = JSON.parse(stdout.slice(separator + 2).trim());
+  } catch (error) {
+    throw new Error(`${ref} has an invalid ownership payload`, { cause: error });
+  }
+  if (claim?.contractVersion !== CONTRACT_VERSION || typeof claim.owner !== 'string') {
+    throw new Error(`${ref} has an unsupported ownership payload`);
+  }
+  return claim;
+}
+
+export async function readWaveClaim({ repoRoot, anchor }) {
+  const ref = claimRef(anchor);
+  const tagOid = await resolveRef(repoRoot, ref);
+  return tagOid ? readClaimAt(repoRoot, ref, tagOid) : null;
+}
+
+async function createTagObject(repoRoot, anchor, claim) {
+  const ref = claimRef(anchor);
+  const [{ stdout: head }, { stdout: objectFormat }] = await Promise.all([
+    git(repoRoot, ['rev-parse', '--verify', 'HEAD^{commit}']),
+    git(repoRoot, ['rev-parse', '--show-object-format']),
+  ]);
+  const epoch = Math.floor(Date.parse(claim.createdAt) / 1000);
+  const content = [
+    `object ${head.trim()}`,
+    'type commit',
+    `tag ${ref.slice('refs/tags/'.length)}`,
+    `tagger agent-workflow-kit waveClaim <wave-claim@localhost> ${epoch} +0000`,
+    '',
+    JSON.stringify(claim),
+    '',
+  ].join('\n');
+  const { stdout: tagOid } = await gitWithInput(repoRoot, ['mktag'], content);
+  const zeroOid = '0'.repeat(objectFormat.trim() === 'sha256' ? 64 : 40);
+  return { ref, tagOid: tagOid.trim(), zeroOid };
+}
+
+/** Atomically acquire a local annotated-tag claim and read back its owner. */
+export async function claimWave({ repoRoot, anchor, owner, sliceBranches = [], now = new Date() }) {
+  validateOwner(owner);
+  if (!Array.isArray(sliceBranches) || !sliceBranches.every((branch) => typeof branch === 'string')) {
+    throw new TypeError('sliceBranches must be an array of strings');
+  }
+  const createdAt = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
+  const proposed = { contractVersion: CONTRACT_VERSION, anchor, owner, createdAt, sliceBranches };
+  const { ref, tagOid, zeroOid } = await createTagObject(repoRoot, anchor, proposed);
+  let acquired = true;
+  try {
+    await git(repoRoot, ['update-ref', ref, tagOid, zeroOid]);
+  } catch {
+    acquired = false;
+  }
+  const currentOid = await resolveRef(repoRoot, ref);
+  if (!currentOid) throw new Error(`wave claim ${ref} was not readable after creation`);
+  const claim = await readClaimAt(repoRoot, ref, currentOid);
+  return { acquired: acquired && currentOid === tagOid && claim.owner === owner, claim };
+}
+
+/** Remove a claim only while the annotated payload and ref still belong to owner. */
+export async function releaseWaveClaim({ repoRoot, anchor, owner }) {
+  validateOwner(owner);
+  const ref = claimRef(anchor);
+  const tagOid = await resolveRef(repoRoot, ref);
+  if (!tagOid) return false;
+  const claim = await readClaimAt(repoRoot, ref, tagOid);
+  if (claim.owner !== owner) return false;
+  try {
+    await git(repoRoot, ['update-ref', '-d', ref, tagOid]);
+  } catch {
+    return false;
+  }
+  return await resolveRef(repoRoot, ref) === null;
+}