@ikon85/agent-workflow-kit 0.34.4 → 0.34.6

package/src/lib/verifyUpdateCandidateArtifacts.mjs

@@ -0,0 +1,78 @@
+import { execFile } from 'node:child_process';
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import {
+  candidateInputPaths, declaredCandidateRunbookPaths, validateCandidateManifestPath,
+} from './updateCandidate.mjs';
+
+const run = promisify(execFile);
+
+export async function verifyCandidateMembership(candidateRoot, context) {
+  const manifests = [
+    context.priorReadinessManifest, context.nextReadinessManifest,
+  ];
+  const allowed = new Set(candidateInputPaths({ pkg: context.pkg, manifests }));
+  for (const path of await declaredCandidateRunbookPaths({ candidateRoot, manifests })) {
+    allowed.add(path);
+  }
+  for (const path of context.preview?.generated ?? []) allowed.add(path);
+  for (const { path } of context.preview?.migrations ?? []) allowed.add(path);
+  for (const path of await regularCandidateFiles(candidateRoot)) {
+    if (!allowed.has(path)) {
+      throw new Error(`candidate invariant artifact: extra ${path}`);
+    }
+  }
+}
+
+export async function verifyChangedSyntax(candidateRoot, preview) {
+  const changed = new Set([
+    ...(preview?.added ?? []),
+    ...(preview?.updated ?? []),
+    ...(preview?.generated ?? []),
+    ...(preview?.migrations ?? []).map(({ path }) => path),
+  ]);
+  for (const path of [...changed].sort()) {
+    const absolute = join(candidateRoot, path);
+    let command;
+    if (/\.(?:mjs|cjs|js)$/.test(path)) {
+      command = [process.execPath, ['--check', absolute], 'Node'];
+    } else if (path.endsWith('.py')) {
+      command = [
+        'python3',
+        [
+          '-c',
+          'import ast,pathlib,sys; ast.parse(pathlib.Path(sys.argv[1]).read_bytes())',
+          absolute,
+        ],
+        'Python',
+      ];
+    } else if (path.endsWith('.sh')) {
+      command = ['bash', ['-n', absolute], 'shell'];
+    } else {
+      continue;
+    }
+    try {
+      await run(command[0], command[1]);
+    } catch {
+      throw new Error(`candidate invariant syntax: ${command[2]} parse failed ${path}`);
+    }
+  }
+}
+
+async function regularCandidateFiles(root, relative = '') {
+  const files = [];
+  for (const entry of await readdir(join(root, relative), { withFileTypes: true })) {
+    const path = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...await regularCandidateFiles(root, path));
+      continue;
+    }
+    const state = await lstat(join(root, path));
+    if (!state.isFile()) {
+      throw new Error(`candidate invariant artifact: not a regular file ${path}`);
+    }
+    files.push(path);
+  }
+  return files;
+}

package/src/lib/verifyUpdateCandidateProtocol.mjs

@@ -0,0 +1,221 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, filesForInstallRole } from './manifest.mjs';
+import { validateCandidateManifestPath } from './updateCandidate.mjs';
+
+const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
+const SURFACE_ROOT = {
+  claude: '.claude/skills/',
+  codex: '.agents/skills/',
+};
+
+export async function verifyCandidateProtocol(candidateRoot, pkg, installed) {
+  if (!filesForInstallRole(pkg).some(({ path }) => path === READINESS_MANIFEST_PATH)) return;
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(join(candidateRoot, READINESS_MANIFEST_PATH), 'utf8'));
+  } catch {
+    throw new Error('candidate invariant schema: readiness manifest is invalid JSON');
+  }
+  validateReadinessManifest(manifest);
+  validateSkillArtifactReferences(manifest, pkg);
+  for (const [name, declaration] of Object.entries(manifest.skills)) {
+    if (!declaration.publish
+        || (declaration.installRole ?? CONSUMER_INSTALL_ROLE) !== CONSUMER_INSTALL_ROLE
+        || !declaration.surfaces.includes('claude')
+        || !declaration.surfaces.includes('codex')) continue;
+    await verifyMirrorGroup(candidateRoot, pkg, installed, name, declaration.class);
+  }
+}
+
+function validateReadinessManifest(manifest) {
+  if (!manifest || manifest.schema_version !== 1
+      || !isRecord(manifest.skills)
+      || !isRecord(manifest.readiness)
+      || !Number.isInteger(manifest.readiness.contractVersion)
+      || !isRecord(manifest.readiness.capabilities)) {
+    throw new Error('candidate invariant schema: readiness manifest identity is invalid');
+  }
+  const capabilities = manifest.readiness.capabilities;
+  for (const [name, capability] of Object.entries(capabilities)) {
+    const evidence = capability?.evidence;
+    if (!isRecord(evidence) || typeof evidence.type !== 'string'
+        || !Array.isArray(evidence.paths) || !evidence.paths.length) {
+      throw new Error(`candidate invariant schema: invalid capability evidence ${name}`);
+    }
+    for (const path of evidence.paths) {
+      try {
+        validateCandidateManifestPath(path);
+      } catch {
+        throw new Error(`candidate invariant schema: unsafe capability path ${name}`);
+      }
+    }
+  }
+  for (const [name, skill] of Object.entries(manifest.skills)) {
+    const readiness = skill?.readiness ?? {};
+    if (!isRecord(skill) || typeof skill.publish !== 'boolean'
+        || !['generic', 'vendored', 'adapter'].includes(skill.class)
+        || ![CONSUMER_INSTALL_ROLE, 'maintainer'].includes(
+          skill.installRole ?? CONSUMER_INSTALL_ROLE,
+        )
+        || !Array.isArray(skill.surfaces)
+        || (skill.publish && !skill.surfaces.length)
+        || skill.surfaces.some((surface) => !SURFACE_ROOT[surface])
+        || new Set(skill.surfaces).size !== skill.surfaces.length
+        || !isRecord(readiness)
+        || !Array.isArray(readiness.required ?? [])
+        || !isRecord(readiness.optionalBlocks ?? {})
+        || [...(readiness.required ?? []), ...Object.values(readiness.optionalBlocks ?? {})]
+          .some((capability) => typeof capability !== 'string' || !capability)) {
+      throw new Error(`candidate invariant schema: invalid skill declaration ${name}`);
+    }
+    for (const capability of [
+      ...(readiness.required ?? []),
+      ...Object.values(readiness.optionalBlocks ?? {}),
+    ]) {
+      if (!capabilities[capability]) {
+        throw new Error(`candidate invariant schema: unknown readiness reference ${name}.${capability}`);
+      }
+    }
+  }
+}
+
+function validateSkillArtifactReferences(manifest, pkg) {
+  const installable = filesForInstallRole(pkg);
+  for (const entry of installable.filter(({ kind }) => kind === 'skill')) {
+    const name = entry.ownerSkill ?? skillNameFromPath(entry.path);
+    const surface = entry.surface ?? skillSurfaceFromPath(entry.path);
+    const declaration = manifest.skills[name];
+    if (!declaration?.publish || !declaration.surfaces.includes(surface)) {
+      throw new Error(`candidate invariant schema: undeclared skill artifact ${entry.path}`);
+    }
+  }
+  for (const [name, declaration] of Object.entries(manifest.skills)) {
+    if (!declaration.publish
+        || (declaration.installRole ?? CONSUMER_INSTALL_ROLE) !== CONSUMER_INSTALL_ROLE) continue;
+    for (const surface of declaration.surfaces) {
+      const path = `${SURFACE_ROOT[surface]}${name}/SKILL.md`;
+      if (!installable.some((entry) => entry.path === path)) {
+        throw new Error(`candidate invariant schema: missing skill entrypoint ${path}`);
+      }
+    }
+  }
+}
+
+async function verifyMirrorGroup(candidateRoot, pkg, installed, name, skillClass) {
+  const relativeBySurface = {};
+  for (const [surface, root] of Object.entries(SURFACE_ROOT)) {
+    const prefix = `${root}${name}/`;
+    relativeBySurface[surface] = new Map(filesForInstallRole(pkg)
+      .filter(({ path }) => path.startsWith(prefix))
+      .map((entry) => [entry.path.slice(prefix.length), entry.path]));
+  }
+  const claude = relativeBySurface.claude;
+  const codex = relativeBySurface.codex;
+  const union = new Set([...claude.keys(), ...codex.keys()]);
+  for (const relative of union) {
+    const sourcePath = claude.get(relative);
+    const mirrorPath = codex.get(relative);
+    if (!sourcePath || !mirrorPath) {
+      throw new Error(`candidate invariant protocol: mirror file-set mismatch ${name}/${relative}`);
+    }
+    if (installed.get(sourcePath)?.origin === CONSUMER_ORIGIN
+        || installed.get(mirrorPath)?.origin === CONSUMER_ORIGIN) continue;
+    const source = await readFile(join(candidateRoot, sourcePath));
+    const mirror = await readFile(join(candidateRoot, mirrorPath));
+    if (relative.endsWith('.md') && ['generic', 'vendored'].includes(skillClass)) {
+      const left = normalizedMirrorMarkdown(source.toString('utf8'));
+      const right = normalizedMirrorMarkdown(mirror.toString('utf8'));
+      if (left.sequence.join('\0') !== right.sequence.join('\0')
+          || left.body !== right.body) {
+        throw new Error(`candidate invariant protocol: mirror content mismatch ${name}/${relative}`);
+      }
+    } else if (!source.equals(mirror)) {
+      throw new Error(`candidate invariant protocol: mirror content mismatch ${name}/${relative}`);
+    }
+  }
+}
+
+function normalizedMirrorMarkdown(text) {
+  const lines = text.split(/\r?\n/);
+  let body = lines;
+  let frontmatter = [];
+  if (lines[0] === '---') {
+    const end = lines.indexOf('---', 1);
+    if (end < 0) throw new Error('candidate invariant schema: unterminated skill frontmatter');
+    frontmatter = normalizedFrontmatter(lines.slice(1, end));
+    body = lines.slice(end + 1);
+  }
+  const kept = [];
+  const sequence = [];
+  let inTransform = false;
+  for (const line of body) {
+    const start = /^\s*<!--\s*mirror-xform:start(?:\s+([^>]*?))?\s*-->\s*$/.exec(line);
+    if (start) {
+      if (inTransform) throw new Error('candidate invariant protocol: nested mirror transform');
+      inTransform = true;
+      sequence.push((start[1] ?? '').trim());
+      continue;
+    }
+    if (/^\s*<!--\s*mirror-xform:end\s*-->\s*$/.test(line)) {
+      if (!inTransform) throw new Error('candidate invariant protocol: unmatched mirror transform');
+      inTransform = false;
+      continue;
+    }
+    if (!inTransform) kept.push(line.trimEnd());
+  }
+  if (inTransform) throw new Error('candidate invariant protocol: unterminated mirror transform');
+  return { body: [...frontmatter, ...kept].join('\n').trim(), sequence };
+}
+
+function normalizedFrontmatter(lines) {
+  const fields = new Map();
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = /^(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+)):\s*(.*)$/.exec(
+      lines[index].trimEnd(),
+    );
+    if (!match) throw new Error('candidate invariant schema: invalid skill frontmatter');
+    const key = match[1] ?? match[2] ?? match[3];
+    if (fields.has(key)) throw new Error(`candidate invariant schema: duplicate frontmatter key ${key}`);
+    let value = match[4];
+    if (/^[>|]-?$/.test(value)) {
+      const folded = value.startsWith('>');
+      const continuation = [];
+      while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+        index += 1;
+        continuation.push(lines[index].trim());
+      }
+      value = continuation.join(folded ? ' ' : '\n');
+    } else if (value.startsWith('"') && value.endsWith('"')) {
+      try { value = JSON.parse(value); } catch {
+        throw new Error(`candidate invariant schema: invalid frontmatter value ${key}`);
+      }
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1).replaceAll("''", "'");
+    } else if (/^(?:true|false|null|-?\d+(?:\.\d+)?)$/.test(value)) {
+      value = JSON.parse(value);
+    }
+    fields.set(key, value);
+  }
+  return [
+    '---',
+    ...[...fields].filter(([key]) => key !== 'description')
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, value]) => `${key}: ${JSON.stringify(value)}`),
+    '---',
+  ];
+}
+
+function skillNameFromPath(path) {
+  return path.split('/')[2];
+}
+
+function skillSurfaceFromPath(path) {
+  if (path.startsWith(SURFACE_ROOT.claude)) return 'claude';
+  if (path.startsWith(SURFACE_ROOT.codex)) return 'codex';
+  return null;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/src/lib/verifyUpdateCandidateTransaction.mjs

@@ -0,0 +1,152 @@
+import { join } from 'node:path';
+import { sha256File } from './hash.mjs';
+import { CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, KIT_ORIGIN } from './manifest.mjs';
+import { validateCandidateManifestPath } from './updateCandidate.mjs';
+
+const HASH = /^[a-f0-9]{64}$/;
+
+export function verifyDeletionState(installed, pkg, installable, preview) {
+  const installablePaths = new Set(installable.map(({ path }) => path));
+  const packageEntries = new Map(pkg.files.map((entry) => [entry.path, entry]));
+  const deleted = new Set(preview?.deleted ?? []);
+  const preserved = new Set(preview?.keptDeleted ?? []);
+  for (const [path, tracked] of installed) {
+    if (installablePaths.has(path)) continue;
+    if (deleted.has(path) && tracked.origin === KIT_ORIGIN) {
+      throw new Error(`candidate invariant deletion: stale Kit ledger path ${path}`);
+    }
+    if (tracked.origin === CONSUMER_ORIGIN) continue;
+    if (!preserved.has(path)) {
+      throw new Error(`candidate invariant deletion: undeclared legacy Kit path ${path}`);
+    }
+    const packaged = packageEntries.get(path);
+    const expectedRole = packaged?.installRole ?? tracked.installRole ?? CONSUMER_INSTALL_ROLE;
+    if ((tracked.installRole ?? CONSUMER_INSTALL_ROLE) !== expectedRole) {
+      throw new Error(`candidate invariant deletion: role mismatch ${path}`);
+    }
+  }
+  for (const path of deleted) {
+    if (installed.has(path)) {
+      throw new Error(`candidate invariant deletion: stale Kit ledger path ${path}`);
+    }
+  }
+  for (const path of preserved) {
+    if (!installed.has(path)) {
+      throw new Error(`candidate invariant deletion: missing preserved ledger path ${path}`);
+    }
+  }
+}
+
+export function verifyTransactionPreview(preview, installable, installed) {
+  if (!preview || typeof preview !== 'object') {
+    throw new Error('candidate invariant transaction: preview is required');
+  }
+  const installablePaths = new Set(installable.map(({ path }) => path));
+  const owners = new Map();
+  const actionSets = new Map();
+  for (const key of ['added', 'updated', 'deleted', 'generated', 'keptDeleted']) {
+    if (!Array.isArray(preview[key] ?? [])) {
+      throw new Error(`candidate invariant transaction: ${key} must be an array`);
+    }
+    const local = new Set();
+    for (const path of preview[key] ?? []) {
+      claimTransactionPath(path, key, local, owners);
+      if (['added', 'updated'].includes(key) && !installablePaths.has(path)) {
+        throw new Error(`candidate invariant transaction: unmanaged ${key} path ${path}`);
+      }
+      if (key === 'deleted' && installablePaths.has(path)) {
+        throw new Error(`candidate invariant transaction: deletes current package path ${path}`);
+      }
+    }
+    actionSets.set(key, local);
+  }
+  if (!Array.isArray(preview.migrations ?? [])) {
+    throw new Error('candidate invariant transaction: migrations must be an array');
+  }
+  const migrationPaths = new Set();
+  for (const migration of preview.migrations ?? []) {
+    claimTransactionPath(migration?.path, 'migrations', migrationPaths, owners);
+  }
+  verifyCollisionRecords(preview, installablePaths, installed, actionSets, owners);
+}
+
+export async function verifyDerivedArtifacts(candidateRoot, installed, preview) {
+  for (const path of preview.generated ?? []) {
+    const tracked = installed.get(path);
+    if (!tracked || tracked.origin !== CONSUMER_ORIGIN
+        || !HASH.test(tracked.installedSha256 ?? '')) {
+      throw new Error(`candidate invariant transaction: invalid generated ledger ${path}`);
+    }
+    if (await transactionHash(candidateRoot, path) !== tracked.installedSha256) {
+      throw new Error(`candidate invariant transaction: generated hash mismatch ${path}`);
+    }
+  }
+  const migrations = new Set();
+  for (const migration of preview.migrations ?? []) {
+    const path = migration?.path;
+    claimTransactionPath(path, 'migration', migrations);
+    if (!(migration.beforeSha256 === null || HASH.test(migration.beforeSha256 ?? ''))
+        || !HASH.test(migration.afterSha256 ?? '')
+        || await transactionHash(candidateRoot, path) !== migration.afterSha256) {
+      throw new Error(`candidate invariant transaction: migration hash mismatch ${path}`);
+    }
+  }
+}
+
+function verifyCollisionRecords(preview, installablePaths, installed, actionSets, owners) {
+  if (!Array.isArray(preview.collisions ?? [])
+      || !Array.isArray(preview.collisionResolutions ?? [])) {
+    throw new Error('candidate invariant transaction: collision records must be arrays');
+  }
+  const unresolved = new Set();
+  for (const path of preview.collisions ?? []) {
+    claimTransactionPath(path, 'collisions', unresolved);
+  }
+  if (unresolved.size) {
+    throw new Error('candidate invariant transaction: unresolved collision');
+  }
+  const resolutions = new Set();
+  for (const resolution of preview.collisionResolutions ?? []) {
+    const path = resolution?.path;
+    claimTransactionPath(path, 'collision resolution', resolutions);
+    if (!installablePaths.has(path)
+        || !['keep-as-owned', 'replace'].includes(resolution?.outcome)
+        || !HASH.test(resolution?.destinationSha256 ?? '')) {
+      throw new Error(`candidate invariant transaction: invalid collision resolution ${path}`);
+    }
+    const expectedOrigin = resolution.outcome === 'keep-as-owned' ? CONSUMER_ORIGIN : KIT_ORIGIN;
+    if (installed.get(path)?.origin !== expectedOrigin
+        || (resolution.outcome === 'replace' && !actionSets.get('added').has(path))
+        || (resolution.outcome === 'keep-as-owned' && owners.has(path))) {
+      throw new Error(`candidate invariant transaction: incoherent collision resolution ${path}`);
+    }
+  }
+}
+
+function claimTransactionPath(path, key, local, owners = null) {
+  try {
+    validateCandidateManifestPath(path);
+  } catch {
+    throw new Error(`candidate invariant transaction: unsafe ${key} path ${path}`);
+  }
+  if (local.has(path)) {
+    throw new Error(`candidate invariant transaction: duplicate ${key} path ${path}`);
+  }
+  local.add(path);
+  const owner = owners?.get(path);
+  if (owner && owner !== key) {
+    throw new Error(`candidate invariant transaction: overlapping action ${path}`);
+  }
+  owners?.set(path, key);
+}
+
+async function transactionHash(candidateRoot, path) {
+  try {
+    return await sha256File(join(candidateRoot, path));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`candidate invariant transaction: missing derived artifact ${path}`);
+    }
+    throw error;
+  }
+}