@ikon85/agent-workflow-kit 0.36.4 → 0.37.0

package/src/lib/manifest.mjs

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { basename, join, posix } from 'node:path';
 import { writeAtomic } from './atomicWrite.mjs';
 
 // Two manifests (Codex R1#9 / R3#1):
@@ -20,6 +20,16 @@ export const READINESS_CONTRACT_VERSION = 1;
 export const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
 export { PROJECT_SKILL_REGISTRY_PATH } from './skillRegistry.mjs';
 
+const HASH = /^[a-f0-9]{64}$/;
+const KINDS = new Set(['skill', 'script', 'hook', 'template', 'doc']);
+const SURFACES = new Set(['claude', 'codex']);
+const INSTALL_ROLES = new Set([CONSUMER_INSTALL_ROLE, 'maintainer']);
+const ORIGINS = new Set([KIT_ORIGIN, CONSUMER_ORIGIN]);
+const OWNERSHIP_STATES = new Set([
+  'project-extension', 'contribution-bridge', 'explicit-fork',
+]);
+const READINESS_DECISIONS = new Set(['pending', 'not-applicable']);
+
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
  * (invalid JSON — e.g. from an aborted write before writeManifest went atomic)
@@ -35,8 +45,9 @@ export async function readManifest(path) {
     if (err.code === 'ENOENT') return null;
     throw err;
   }
+  let manifest;
   try {
-    return JSON.parse(raw);
+    manifest = JSON.parse(raw);
   } catch (err) {
     throw new Error(
       `${path} is corrupt (invalid JSON) and can't be read. ` +
@@ -44,6 +55,162 @@ export async function readManifest(path) {
       { cause: err }
     );
   }
+  const name = basename(path);
+  if (name === PACKAGE_MANIFEST_NAME) {
+    return validateManifest(manifest, { kind: 'package', path });
+  }
+  if (name === CONSUMER_MANIFEST_NAME) {
+    return validateManifest(manifest, { kind: 'consumer', path });
+  }
+  return manifest;
+}
+
+/**
+ * Validate the two persisted lifecycle manifests before their entries are
+ * indexed or trusted. Unknown extension keys remain untouched; known fields
+ * are deliberately strict. Compatibility is explicit:
+ * - package manifests before role-aware installs may omit `installRole`;
+ * - consumer ledgers before role-aware installs may omit `installRole`;
+ * - readiness fields introduced after the first consumer ledger are optional.
+ */
+export function validateManifest(manifest, { kind, path }) {
+  if (kind !== 'package' && kind !== 'consumer') {
+    throw new Error(`unknown manifest class: ${kind}`);
+  }
+  const recovery = kind === 'package'
+    ? 'Reinstall the Kit or regenerate its package manifest from a trusted checkout.'
+    : 'Restore the consumer manifest from its ".bak" backup, or delete it and re-run `init`.';
+  const fail = (detail) => {
+    throw new Error(`${path} is an invalid ${kind} manifest: ${detail} ${recovery}`);
+  };
+  if (!plainObject(manifest)) fail('the root must be a JSON object.');
+  if (typeof manifest.kitVersion !== 'string' || manifest.kitVersion.length === 0) {
+    fail('kitVersion must be a non-empty string.');
+  }
+  const key = kind === 'package' ? 'files' : 'installed';
+  if (!Array.isArray(manifest[key])) fail(`${key} must be an array.`);
+  if (kind === 'consumer') validateConsumerRoot(manifest, fail);
+
+  const seen = new Set();
+  for (const [offset, entry] of manifest[key].entries()) {
+    const ordinal = `entry #${offset + 1}`;
+    if (!plainObject(entry)) fail(`${ordinal} must be a JSON object.`);
+    if (!safeManifestPath(entry.path)) {
+      fail(`${ordinal} has an unsafe consumer path (${display(entry.path)}); use a relative POSIX path without "." or ".." segments.`);
+    }
+    const label = `${ordinal} (${entry.path})`;
+    if (seen.has(entry.path)) fail(`${label} duplicates path ${entry.path}.`);
+    seen.add(entry.path);
+    validateEnum(entry, 'kind', KINDS, label, fail, true);
+    validateOptionalString(entry, 'ownerSkill', label, fail);
+    validateEnum(entry, 'surface', SURFACES, label, fail);
+    validateEnum(entry, 'installRole', INSTALL_ROLES, label, fail);
+    validateEnum(entry, 'origin', ORIGINS, label, fail, true);
+    if (kind === 'package') {
+      validateHash(entry.sha256, `${label} sha256`, fail);
+      if (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777) {
+        fail(`${label} mode must be an integer from 0 through 511.`);
+      }
+      if (entry.origin !== KIT_ORIGIN) fail(`${label} origin must be "kit".`);
+    } else {
+      validateHash(entry.installedSha256, `${label} installedSha256`, fail);
+      if ('sha256' in entry) validateHash(entry.sha256, `${label} sha256`, fail);
+      if ('mode' in entry
+          && (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777)) {
+        fail(`${label} mode must be an integer from 0 through 511.`);
+      }
+      validateConsumerEntry(entry, label, fail);
+    }
+  }
+  return manifest;
+}
+
+function validateConsumerRoot(manifest, fail) {
+  if ('installRole' in manifest && manifest.installRole !== CONSUMER_INSTALL_ROLE) {
+    fail('installRole must be "consumer".');
+  }
+  if ('readinessContractVersion' in manifest
+      && (!Number.isInteger(manifest.readinessContractVersion)
+        || manifest.readinessContractVersion < 1)) {
+    fail('readinessContractVersion must be a positive integer.');
+  }
+  if ('readinessDecisions' in manifest) {
+    if (!plainObject(manifest.readinessDecisions)) {
+      fail('readinessDecisions must be a JSON object.');
+    }
+    for (const [capability, decision] of Object.entries(manifest.readinessDecisions)) {
+      if (!capability || !READINESS_DECISIONS.has(decision)) {
+        fail(`readinessDecisions.${capability || '<empty>'} has unsupported value ${display(decision)}.`);
+      }
+    }
+  }
+}
+
+function validateConsumerEntry(entry, label, fail) {
+  if ('orphanedByUninstall' in entry && typeof entry.orphanedByUninstall !== 'boolean') {
+    fail(`${label} orphanedByUninstall must be a boolean.`);
+  }
+  validateEnum(entry, 'ownershipState', OWNERSHIP_STATES, label, fail);
+  if ('ownershipState' in entry && entry.origin !== CONSUMER_ORIGIN) {
+    fail(`${label} ownershipState requires origin "consumer".`);
+  }
+  if (!('contributionBridge' in entry)) return;
+  const bridge = entry.contributionBridge;
+  if (!plainObject(bridge)
+      || bridge.schemaVersion !== 1
+      || typeof bridge.baseKitVersion !== 'string'
+      || bridge.baseKitVersion.length === 0) {
+    fail(`${label} contributionBridge must be a schemaVersion 1 object with baseKitVersion.`);
+  }
+  validateHash(bridge.baseSha256, `${label} contributionBridge.baseSha256`, fail);
+  validateHash(bridge.localSha256, `${label} contributionBridge.localSha256`, fail);
+  if (entry.origin !== CONSUMER_ORIGIN
+      || entry.ownershipState !== 'contribution-bridge'
+      || entry.installedSha256 !== bridge.localSha256) {
+    fail(`${label} contributionBridge must match consumer ownership and installedSha256.`);
+  }
+}
+
+function validateEnum(entry, field, values, label, fail, required = false) {
+  if (!(field in entry)) {
+    if (required) fail(`${label} ${field} is required.`);
+    return;
+  }
+  if (typeof entry[field] !== 'string' || !values.has(entry[field])) {
+    fail(`${label} ${field} has unsupported value ${display(entry[field])}.`);
+  }
+}
+
+function validateOptionalString(entry, field, label, fail) {
+  if (field in entry && (typeof entry[field] !== 'string' || entry[field].length === 0)) {
+    fail(`${label} ${field} must be a non-empty string when present.`);
+  }
+}
+
+function validateHash(value, field, fail) {
+  if (typeof value !== 'string' || !HASH.test(value)) {
+    fail(`${field} must be a lowercase 64-hex SHA-256.`);
+  }
+}
+
+function safeManifestPath(path) {
+  return typeof path === 'string'
+    && path.length > 0
+    && path !== '.'
+    && !path.includes('\\')
+    && !path.includes('//')
+    && !path.split('/').some((part) => part === '' || part === '.' || part === '..')
+    && !posix.isAbsolute(path)
+    && !/^[a-zA-Z]:/.test(path)
+    && posix.normalize(path) === path;
+}
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function display(value) {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
 }
 
 /**
@@ -90,7 +257,10 @@ export function filesForInstallRole(manifest, installRole = CONSUMER_INSTALL_ROL
 /** Map a manifest's file list (under `key`) by `path` for quick lookup. */
 export function indexByPath(manifest, key) {
   const idx = new Map();
-  for (const entry of (manifest?.[key] ?? [])) idx.set(entry.path, entry);
+  for (const entry of (manifest?.[key] ?? [])) {
+    if (idx.has(entry.path)) throw new Error(`duplicate manifest path: ${entry.path}`);
+    idx.set(entry.path, entry);
+  }
   return idx;
 }
 

package/src/lib/projectSkillExtension.mjs

@@ -6,6 +6,70 @@ const SKILL_NAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 const MARKER_PREFIX = '<!-- agent-workflow-kit: project-extension/';
 const MARKER = /^<!-- agent-workflow-kit: project-extension\/([^;]+); skill=([a-z0-9-]+) -->$/;
 
+function meaningfulSectionBody(lines) {
+  const body = lines.join('\n').replace(/<!--[\s\S]*?-->/g, '');
+  const content = [];
+  let fence = null;
+  for (const rawLine of body.split('\n')) {
+    const line = rawLine.trim();
+    const delimiter = /^(`{3,}|~{3,})/.exec(line)?.[1];
+    if (delimiter && !fence) {
+      fence = { character: delimiter[0], length: delimiter.length };
+      continue;
+    }
+    if (fence && new RegExp(`^\\${fence.character}{${fence.length},}\\s*$`).test(line)) {
+      fence = null;
+      continue;
+    }
+    if (line && !/^#{1,6}\s+/.test(line)) content.push(line);
+  }
+  const meaningful = content
+    .filter((line) =>
+      !/^(?:(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?)?(?:TODO|TBD)(?:[.!:]*)$/i.test(line)
+      && !/^<\/?[^>\n]+>$/.test(line)
+      && !/^<(?:placeholder|fill|configure|add)(?:\s+[^>]*)?>[.!:]*$/i.test(line)
+      && !/^(?:Run|Use|Configure|Add|Replace)\s+`?<[^>]+>`?[.!:]*$/i.test(line))
+    .join('\n');
+  return meaningful.trim();
+}
+
+function sectionBodies(body, path) {
+  const sections = new Map();
+  let current = null;
+  for (const line of body.split('\n')) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      if (sections.has(heading[1])) {
+        throw new Error(`Project extension has duplicate section ${heading[1]} at ${path}`);
+      }
+      current = [];
+      sections.set(heading[1], current);
+    } else if (current) {
+      current.push(line);
+    }
+  }
+  return sections;
+}
+
+export function validateProjectSkillActivation(activation, path) {
+  if (activation === undefined) return null;
+  if (!activation || typeof activation !== 'object' || Array.isArray(activation)
+      || activation.mode !== 'all-sections-filled'
+      || !Array.isArray(activation.sections) || !activation.sections.length
+      || activation.sections.some((section) =>
+        typeof section !== 'string' || !section.trim())
+      || new Set(activation.sections).size !== activation.sections.length) {
+    throw new Error(`Project extension activation policy is invalid at ${path}`);
+  }
+  return activation.sections;
+}
+
+function unfilledSections(body, requiredSections, path) {
+  const sections = sectionBodies(body, path);
+  return requiredSections.filter((name) =>
+    !sections.has(name) || !meaningfulSectionBody(sections.get(name)));
+}
+
 export function projectSkillExtensionPath(skill) {
   if (typeof skill !== 'string' || !SKILL_NAME.test(skill)) {
     throw new Error(`invalid Project extension skill identity: ${skill}`);
@@ -13,8 +77,9 @@ export function projectSkillExtensionPath(skill) {
   return `docs/agents/skills/${skill}.md`;
 }
 
-export async function inspectProjectSkillExtension({ root, skill }) {
+export async function inspectProjectSkillExtension({ root, skill, activation }) {
   const path = projectSkillExtensionPath(skill);
+  const requiredSections = validateProjectSkillActivation(activation, path);
   const absolute = join(root, path);
   let state;
   try {
@@ -50,6 +115,18 @@ export async function inspectProjectSkillExtension({ root, skill }) {
       `found skill=${match[2]}`,
     );
   }
+  if (requiredSections) {
+    const missingSections = unfilledSections(body, requiredSections, path);
+    if (missingSections.length) {
+      return {
+        state: 'inactive',
+        reason: 'sections-unfilled',
+        schemaVersion: 1,
+        path,
+        missingSections,
+      };
+    }
+  }
   const content = lines.filter(
     (line) => line && line !== markerLine && !line.startsWith('<!-- setup-workflow:'),
   );

package/src/lib/updateCandidate.mjs

@@ -13,7 +13,7 @@ import { stubSentinel } from './sentinel.mjs';
 import { STUB_TARGETS } from './bundle.mjs';
 import {
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
-  filesForInstallRole, indexByPath, readManifest, writeManifest,
+  filesForInstallRole, indexByPath, readManifest, validateManifest, writeManifest,
 } from './manifest.mjs';
 import {
   PROJECT_SKILL_REGISTRY_PATH, emptyProjectSkillRegistry, migrateLegacySkillRegistry,
@@ -38,6 +38,7 @@ export async function materializeUpdateCandidate({
   consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
   afterInputValidation = async () => {},
 }) {
+  validateManifest(pkg, { kind: 'package', path: 'update package manifest' });
   const candidateRoot = await mkdtemp(join(tmpdir(), 'agent-workflow-kit-stage-'));
   try {
     const paths = candidateInputPaths({
@@ -208,6 +209,7 @@ export async function activateCandidate({
   afterSnapshot = async () => {}, afterGenerated = async () => {},
   beforeTargetRevalidation = async () => {},
 }) {
+  validateManifest(pkg, { kind: 'package', path: 'update package manifest' });
   const changed = [...preview.added, ...preview.updated];
   const generated = preview.generated ?? [];
   const migrations = preview.migrations ?? [];
@@ -351,6 +353,14 @@ async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
       throw new Error(`consumer changed during verification: ${path}`);
     }
   }
+  for (const snapshot of preview.userModifiedSnapshots ?? []) {
+    const target = join(consumerRoot, snapshot.path);
+    const current = await exists(target) ? await sha256File(target) : null;
+    const mode = current === null ? null : (await lstat(target)).mode & 0o777;
+    if (current !== snapshot.sha256 || mode !== snapshot.mode) {
+      throw new Error(`consumer changed during verification: ${snapshot.path}`);
+    }
+  }
 }
 
 /** Seed only newly declared, decision-free project-layer stubs in a staged candidate. */

package/src/lib/updateDecisions.mjs

@@ -1,5 +1,5 @@
-export function nonInteractiveUpdateDecision(action) {
-  if (action === 'delete') return true;
+export function nonInteractiveUpdateDecision(action, choices = {}) {
+  if (action === 'delete') return choices.deleted !== 'restore';
   if (action === 'collision') return undefined;
   throw new Error(`unknown update decision action: ${action}`);
 }

package/src/lib/updateReconcile.mjs

@@ -156,6 +156,11 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     } else if (userEdited) {
       nextInstalled.push(withInstallRole(prior));
       result.userModified.push(file.path);
+      result.userModifiedSnapshots.push({
+        path: file.path,
+        sha256: current,
+        mode: currentMode,
+      });
     } else {
       nextInstalled.push(withInstallRole(prior));
       result.unchanged.push(file.path);
@@ -202,6 +207,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 function emptyResult() {
   return {
     unchanged: [], updated: [], conflicts: [], collisions: [], collisionResolutions: [], userModified: [],
+    userModifiedSnapshots: [],
     ownershipStates: [],
     bridgeRetired: [],
     added: [], deleted: [], keptDeleted: [], consumerOwned: [], manifestChanged: false,

package/src/lib/verifyUpdateCandidate.mjs

@@ -61,11 +61,14 @@ export async function verifyCandidateMetadata(candidateRoot, context) {
     if (!state.isFile()) {
       throw new Error(`candidate invariant artifact: not a regular file ${entry.path}`);
     }
-    if (tracked.origin === KIT_ORIGIN && (state.mode & 0o777) !== entry.mode) {
+    const localSnapshot = (context.preview.userModifiedSnapshots ?? [])
+      .find(({ path }) => path === entry.path);
+    const expectedMode = localSnapshot?.mode ?? entry.mode;
+    if (tracked.origin === KIT_ORIGIN && (state.mode & 0o777) !== expectedMode) {
       throw new Error(`candidate invariant artifact: mode mismatch ${entry.path}`);
     }
-    const expectedHash = tracked.origin === CONSUMER_ORIGIN
-      ? tracked.installedSha256 : entry.sha256;
+    const expectedHash = localSnapshot?.sha256 ?? (tracked.origin === CONSUMER_ORIGIN
+      ? tracked.installedSha256 : entry.sha256);
     if (await sha256File(join(candidateRoot, entry.path)) !== expectedHash) {
       throw new Error(`candidate invariant artifact: hash mismatch ${entry.path}`);
     }

package/src/lib/verifyUpdateCandidateProtocol.mjs

@@ -2,6 +2,10 @@ 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';
+import {
+  projectSkillExtensionPath,
+  validateProjectSkillActivation,
+} from './projectSkillExtension.mjs';
 import { readComposedSkillRegistry } from './skillRegistry.mjs';
 
 const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
@@ -52,6 +56,17 @@ function validateReadinessManifest(manifest) {
         throw new Error(`candidate invariant schema: unsafe capability path ${name}`);
       }
     }
+    if (evidence.type === 'project-extension') {
+      try {
+        const expected = projectSkillExtensionPath(evidence.skill);
+        if (evidence.paths.length !== 1 || evidence.paths[0] !== expected) {
+          throw new Error('path mismatch');
+        }
+        validateProjectSkillActivation(evidence.activation, expected);
+      } catch {
+        throw new Error(`candidate invariant schema: invalid capability evidence ${name}`);
+      }
+    }
   }
   for (const [name, skill] of Object.entries(manifest.skills)) {
     const readiness = skill?.readiness ?? {};

package/src/lib/verifyUpdateCandidateTransaction.mjs

@@ -44,7 +44,7 @@ export function verifyTransactionPreview(preview, installable, installed) {
   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']) {
+  for (const key of ['added', 'updated', 'deleted', 'generated', 'keptDeleted', 'userModified']) {
     if (!Array.isArray(preview[key] ?? [])) {
       throw new Error(`candidate invariant transaction: ${key} must be an array`);
     }
@@ -54,12 +54,34 @@ export function verifyTransactionPreview(preview, installable, installed) {
       if (['added', 'updated'].includes(key) && !installablePaths.has(path)) {
         throw new Error(`candidate invariant transaction: unmanaged ${key} path ${path}`);
       }
+      if (key === 'userModified' && !installablePaths.has(path)) {
+        throw new Error(`candidate invariant transaction: unmanaged userModified 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.userModifiedSnapshots ?? [])) {
+    throw new Error('candidate invariant transaction: userModifiedSnapshots must be an array');
+  }
+  const modified = actionSets.get('userModified');
+  const snapshots = new Set();
+  for (const snapshot of preview.userModifiedSnapshots ?? []) {
+    const path = snapshot?.path;
+    claimTransactionPath(path, 'userModifiedSnapshots', snapshots);
+    if (!modified.has(path)
+        || !HASH.test(snapshot.sha256 ?? '')
+        || !Number.isInteger(snapshot.mode)
+        || snapshot.mode < 0
+        || snapshot.mode > 0o777) {
+      throw new Error(`candidate invariant transaction: invalid local snapshot ${path}`);
+    }
+  }
+  if (snapshots.size !== modified.size) {
+    throw new Error('candidate invariant transaction: missing local snapshot');
+  }
   if (!Array.isArray(preview.bridgeRetired ?? [])) {
     throw new Error('candidate invariant transaction: bridgeRetired must be an array');
   }