@sabaiway/agent-workflow-kit 14.31.0 → 14.33.0

package/tools/apply-danger-check.mjs

@@ -12,7 +12,8 @@ import {
   writeAutonomyProfile, writeVelocityProfile,
 } from './velocity-profile.mjs';
 import { KIT_GROUNDING_TOOL, bundledSandboxRecipe, usedBridges } from './bridge-sandbox-recipe.mjs';
-import { mergeAllowWrite, stateDirsOf } from './bridge-state-dirs.mjs';
+import { homeRelative, mergeAllowWrite, stateDirsOf } from './bridge-state-dirs.mjs';
+import { nearestExistingDir, worktreesGrantDir, worktreesGrantHoldsHome } from './worktrees.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { HOOK_FILE_REL, HOOKS_DIR, buildHookSettingsEntry, mergeHookEntry, writeGateHook } from './gate-hook.mjs';
 import { STATE_BLOCK_HOOK_FILE_REL, buildStopHookEntry, mergeStopEntry, writeStateBlockHook } from './state-block-hook.mjs';
@@ -23,6 +24,7 @@ import { planFor } from './jev-skill.mjs';
 import { SKILL_FILES, claudeDirOf, skillTargets } from './jev-facts.mjs';
 import { findOnPath } from './detect-backends.mjs';
 import { consoleArgv } from './write-lanes.mjs';
+import { BUNDLED_SCRIPT_NAMES, INSTALLER_REL, SCRIPTS_REL, formatPlan, planGitHooks } from './git-hooks.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { dirCovers as covers } from './declared-paths.mjs';
 
@@ -34,8 +36,10 @@ const HOOK_VARIANTS = ['gate-hook', 'read-lane.missing', ...RESEED_VARIANTS];
 const STOP = 'state-block';
 const MCP_VARIANTS = ['mcp-channel', 'mcp-channel.differing'];
 const AGENT_VARIANTS = ['agents', 'executor-vehicle'];
+const GIT_VARIANTS = ['enforcement', 'commit-guard'];
+const WORKTREES = 'worktrees-dir';
 const VARIANTS = [...VELOCITY_VARIANTS, 'autonomy-render', ...HOOK_VARIANTS, STOP, ...MCP_VARIANTS, ...AGENT_VARIANTS,
-  ...SKILL_VARIANTS];
+  ...SKILL_VARIANTS, ...GIT_VARIANTS, WORKTREES];
 const HOOK_KEYS = ['hooks.PreToolUse', 'hooks.Stop'];
 const CREDENTIALS = 'sandbox.credentials.envVars';
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -179,7 +183,12 @@ export const scopeOf = (variant, facts, deps = {}) => {
     set('permissions.ask', RENDER_OWNED_REDLINE_RULES);
     set('permissions.deny', RENDER_OWNED_REDLINE_RULES);
     allowed[CREDENTIALS] = (value) => value.mode === 'deny';
-  } else if (HOOK_VARIANTS.includes(variant)) set('hooks.PreToolUse', [buildHookSettingsEntry()]);
+  }
+  const grantDir = variant === WORKTREES ? worktreesGrantDir(facts.root, facts) : null;
+  if (grantDir !== null && !worktreesGrantHoldsHome(grantDir, facts.home, facts)) {
+    set('sandbox.filesystem.allowWrite', [homeRelative(grantDir, facts.home)]);
+  }
+  if (HOOK_VARIANTS.includes(variant)) set('hooks.PreToolUse', [buildHookSettingsEntry()]);
   else if (variant === STOP) set('hooks.Stop', [buildStopHookEntry()]);
   else if (MCP_VARIANTS.includes(variant)) {
     set(`${SERVERS_KEY}.${SERVER_NAME}`, [buildServerEntry(join(facts.toolsDir, 'mcp-server.mjs'))]);
@@ -193,14 +202,25 @@ export const scopeOf = (variant, facts, deps = {}) => {
   const directories = SKILL_VARIANTS.includes(variant) ? [] : [join(facts.root, CLAUDE_DIR)];
   if (HOOK_VARIANTS.includes(variant) || variant === STOP) directories.push(join(facts.root, HOOKS_DIR));
   if (AGENT_VARIANTS.includes(variant)) directories.push(join(facts.root, AGENTS_DIR));
+  const existingAncestor = grantDir === null ? null : nearestExistingDir(grantDir, facts);
+  for (let at = grantDir; at !== existingAncestor; at = dirname(at)) directories.push(at);
   for (const target of targets) {
     for (let at = target.root; at !== target.base && covers(target.base, at); at = dirname(at)) directories.push(at);
     filePaths.push(target.path);
   }
+  const scripts = join(facts.root, SCRIPTS_REL);
+  if (GIT_VARIANTS.includes(variant)) {
+    directories.splice(0, directories.length, scripts);
+    filePaths.push(...BUNDLED_SCRIPT_NAMES.map((name) => join(scripts, name)));
+  }
+  const runs = GIT_VARIANTS.includes(variant) ? ['node', INSTALLER_REL,
+    ...(variant === 'commit-guard' ? ['--commit-guard', join(facts.toolsDir, 'commit-guard.mjs')] : [])] : null;
   return {
+    admitsRun: (argv) => runs !== null && equal(argv, runs),
     admits: ({ path, key, change, value }) => {
-      const correctFile = key.startsWith(`${SERVERS_KEY}.`) ? path === MCP_JSON_REL : path === SETTINGS_FILE;
-      const gains = variant === 'bridge-tier' || HOOK_KEYS.includes(key) || key === ENABLED_KEY || key === CREDENTIALS
+      const correctFile = key.startsWith(`${SERVERS_KEY}.`) ? path === MCP_JSON_REL
+        : path === (variant === WORKTREES ? SETTINGS_LOCAL_FILE : SETTINGS_FILE);
+      const gains = variant === 'bridge-tier' || variant === WORKTREES || HOOK_KEYS.includes(key) || key === ENABLED_KEY || key === CREDENTIALS
         || (VELOCITY_VARIANTS.includes(variant) && key === 'permissions.ask');
       return correctFile && (!gains || change === 'added') && Boolean(allowed[key]?.(value));
     },
@@ -213,7 +233,7 @@ const jsonAt = (path) => existsSync(path) ? JSON.parse(readFileSync(path, 'utf8'
 const halted = (lines) => Object.assign(new Error(lines.join('\n')), { code: 'CHECK_HALTED', lines });
 const maskedFiles = (variant, facts) => {
   const paths = VELOCITY_VARIANTS.includes(variant) || variant === 'autonomy-render' || HOOK_VARIANTS.includes(variant)
-    || variant === STOP ? [SETTINGS_FILE, SETTINGS_LOCAL_FILE] : MCP_VARIANTS.includes(variant) ? [MCP_JSON_REL, SETTINGS_FILE] : [];
+    || variant === STOP || variant === WORKTREES ? [SETTINGS_FILE, SETTINGS_LOCAL_FILE] : MCP_VARIANTS.includes(variant) ? [MCP_JSON_REL, SETTINGS_FILE] : [];
   return paths.flatMap((path) => lstatSync(join(facts.root, path), { throwIfNoEntry: false })?.isCharacterDevice()
     ? [`masked: ${path}`] : []);
 };
@@ -221,6 +241,8 @@ export const plannedChange = (variant, facts, deps = {}) => {
   const files = [];
   const writes = [];
   const temporaries = [];
+  const created = [];
+  let runs = null;
   const writerDeps = writerFacts(facts, deps);
   const addFile = (path, before, after) => {
     files.push({ path, before: before ?? null, after });
@@ -280,6 +302,15 @@ export const plannedChange = (variant, facts, deps = {}) => {
         temporaries.push(`temporary: ${dirname(target.root)}/.${stem}.kit-tmp-*`);
         if (target.action === 'replace') temporaries.push(`temporary: ${dirname(target.root)}/.${stem}.kit-old-*`);
       }
+    } else if (GIT_VARIANTS.includes(variant)) {
+      const plan = (deps.planGitHooks ?? planGitHooks)({ root: facts.root, variant, toolsDir: facts.toolsDir });
+      for (const copy of plan.copies.filter(({ action }) => action === 'created')) writes.push({ path: copy.path, bytes: copy.bytes });
+      runs = { argv: plan.runs.shown, line: formatPlan(plan).at(-1) };
+    } else if (variant === WORKTREES) {
+      const plan = writeVelocityProfile({ cwd: facts.root, dryRun: true, worktrees: true }, writerDeps);
+      const before = plan.localSettings.data ?? null;
+      addFile(SETTINGS_LOCAL_FILE, before, mergeAllowWrite(before ?? {}, plan.worktreesDirToAdd));
+      created.push(...plan.worktreesDirsToCreate);
     } else throw new Error(`unsupported variant: ${variant}`);
   } catch (error) {
     throw error.code === 'CHECK_HALTED' ? error : halted([error.message]);
@@ -289,7 +320,8 @@ export const plannedChange = (variant, facts, deps = {}) => {
   for (const path of [...changedFiles.map(({ path }) => join(facts.root, path)), ...writes.map(({ path }) => path)]) {
     for (let parent = dirname(path); !existsSync(parent); parent = dirname(parent)) directories.add(parent);
   }
-  return { files, writes, temporaries, directories: [...directories] };
+  for (const path of created) directories.add(path);
+  return { files, writes, temporaries, directories: [...directories], runs };
 };
 
 export const checkApply = (variant, facts, deps = {}) => {
@@ -318,6 +350,10 @@ export const checkApply = (variant, facts, deps = {}) => {
   }
   for (const path of plan.directories) pathLine(path, true, `writes: ${display(path)}/ created`);
   lines.push(...plan.temporaries);
+  if (plan.runs) {
+    lines.push(plan.runs.line);
+    if (!scope.admitsRun(plan.runs.argv)) refused.push({ path: 'runs:', key: plan.runs.argv.join(' '), reason: `beyond the declared scope of ${variant}` });
+  }
   if (refused.length) {
     for (const entry of refused) lines.push(`refused: ${entry.path} ${entry.key} — ${entry.reason}`);
     lines.push('nothing written');
@@ -369,7 +405,7 @@ export const main = (argv, io = {}) => {
     platform: resolved.platform, claudeDir: args['claude-dir'] };
   let result;
   try {
-    result = checkApply(args.variant, facts, { detect: resolved.detect });
+    result = checkApply(args.variant, facts, { detect: resolved.detect, planGitHooks: resolved.planGitHooks });
   } catch (error) {
     for (const line of error.lines ?? [error.message]) resolved.log(line);
     return 3;

package/tools/git-hooks.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// git-hooks.mjs — the thin writer of the two git-hook items (`enforcement`, `commit-guard`): it copies
+// the bundled scripts create-only and spawns the project's own scripts/install-git-hooks.mjs, which
+// decides the hook at the write. The leaf decides nothing about the hook: the danger check binds the
+// copies and the installer bytes this dry run answers, never git's hooks dir.
+import { lstatSync, readFileSync, readdirSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeProjectFileCreateOnly } from './atomic-write.mjs';
+import { NODE_EVIDENCE_SCRIPTS } from './node-evidence.mjs';
+import { shellQuoteArg } from './repo-lex.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const TOOLS = dirname(fileURLToPath(import.meta.url));
+export const SCRIPTS_REL = 'scripts';
+export const INSTALLER_REL = 'scripts/install-git-hooks.mjs';
+const bundleDir = (toolsDir) => join(toolsDir, '..', 'references', 'scripts');
+export const BUNDLED_SCRIPT_NAMES = Object.freeze(readdirSync(bundleDir(TOOLS)).filter((name) => name.endsWith('.mjs')).sort());
+
+const EXIT_OK = 0;
+const EXIT_INCOMPLETE = 1;
+const EXIT_USAGE = 2;
+const EXIT_REFUSED = 3;
+const USAGE = 'usage: git-hooks (--enforcement | --commit-guard) [--cwd <root>] [--apply]';
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const usageError = (message) => Object.assign(new Error(message), { exitCode: EXIT_USAGE });
+const refusal = (message) => Object.assign(new Error(message), { exitCode: EXIT_REFUSED });
+
+const nodeAt = (path, lstat) => {
+  try {
+    return lstat(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+};
+const isPlainDir = (node) => node !== null && node.isDirectory() && !node.isSymbolicLink();
+const isFile = (node) => node !== null && node.isFile() && !node.isSymbolicLink();
+
+// The dry run: what the apply copies and the installer it runs, with the bytes of each.
+export const planGitHooks = ({ root, variant, toolsDir = TOOLS, lstat = lstatSync, readFile = readFileSync }) => {
+  const scripts = join(root, SCRIPTS_REL);
+  const scriptsNode = nodeAt(scripts, lstat);
+  if (scriptsNode !== null && !isPlainDir(scriptsNode)) throw refusal(`${scripts} is not a plain directory`);
+  const kinds = new Map();
+  const names = variant === 'enforcement' ? BUNDLED_SCRIPT_NAMES : [INSTALLER_REL.slice(SCRIPTS_REL.length + 1)];
+  for (const name of scriptsNode === null ? [] : names) {
+    const path = join(scripts, name);
+    const node = nodeAt(path, lstat);
+    if (node !== null && !isFile(node)) throw refusal(`${path} is not a regular file`);
+    kinds.set(name, node === null ? 'absent' : 'file');
+  }
+  const installer = join(root, INSTALLER_REL);
+  const deployed = NODE_EVIDENCE_SCRIPTS.some((name) => kinds.get(name) === 'file');
+  const copies = variant === 'enforcement' && !deployed ? BUNDLED_SCRIPT_NAMES.map((name) => {
+    if (kinds.get(name) === 'file') return { name, path: join(scripts, name), action: 'kept' };
+    return { name, path: join(scripts, name), action: 'created', bytes: readFile(join(bundleDir(toolsDir), name)) };
+  }) : [];
+  const placed = copies.find(({ path, action }) => path === installer && action === 'created');
+  if (!placed && !isFile(nodeAt(installer, lstat))) throw refusal(`${installer} is absent — nothing here places the hook installer`);
+  const guard = variant === 'commit-guard' ? ['--commit-guard', join(toolsDir, 'commit-guard.mjs')] : [];
+  return {
+    root,
+    variant,
+    scriptsCreated: scriptsNode === null,
+    copies,
+    runs: { argv: ['node', installer, ...guard], shown: ['node', INSTALLER_REL, ...guard], bytes: placed ? placed.bytes : readFile(installer) },
+  };
+};
+
+export const formatPlan = (plan) => [
+  ...plan.copies.map(({ name, action, bytes }) => `copy: ${SCRIPTS_REL}/${name} ${action}${action === 'created' ? ` sha256:${sha(bytes)}` : ''}`),
+  `runs: ${plan.runs.shown.map(shellQuoteArg).join(' ')} sha256:${sha(plan.runs.bytes)}`,
+];
+
+// Removes exactly the files this run created, then scripts/ when this run created it and it is empty;
+// every path it cannot remove is answered for the caller to name.
+const rollBack = (plan, created, io) => {
+  const scripts = join(plan.root, SCRIPTS_REL);
+  const left = [];
+  const dirNow = () => nodeAt(scripts, io.lstat);
+  for (const path of created) {
+    const dir = dirNow();
+    const node = nodeAt(path, io.lstat);
+    if (!isPlainDir(dir) || dir.ino !== created.dirIno || !isFile(node)) {
+      left.push(path);
+      continue;
+    }
+    try {
+      io.unlink(path);
+    } catch {
+      left.push(path);
+    }
+  }
+  if (plan.scriptsCreated && created.dirIno !== undefined) {
+    const dir = dirNow();
+    let empty = false;
+    try {
+      empty = isPlainDir(dir) && dir.ino === created.dirIno && io.readdir(scripts).length === 0;
+    } catch {
+      empty = false;
+    }
+    if (empty) {
+      try {
+        io.rmdir(scripts);
+      } catch {
+        left.push(scripts);
+      }
+    } else if (!isPlainDir(dir) || dir.ino !== created.dirIno) left.push(scripts);
+  }
+  return left;
+};
+
+export const applyGitHooks = (plan, io = {}) => {
+  const resolved = { lstat: lstatSync, unlink: unlinkSync, rmdir: rmdirSync, readdir: readdirSync, env: process.env,
+    log: console.log, error: console.error, writeFile: writeProjectFileCreateOnly,
+    spawn: (argv, options) => spawnSync(argv[0], argv.slice(1), options), ...io };
+  const created = [];
+  const leftovers = [];
+  const fail = (lines) => {
+    for (const line of lines) resolved.error(line);
+    for (const path of [...rollBack(plan, created, resolved), ...leftovers]) resolved.error(`not removed: ${path}`);
+    return EXIT_INCOMPLETE;
+  };
+  const scripts = join(plan.root, SCRIPTS_REL);
+  const noteDir = () => {
+    const dir = nodeAt(scripts, resolved.lstat);
+    if (created.dirIno === undefined && isPlainDir(dir)) created.dirIno = dir.ino;
+  };
+  for (const copy of plan.copies.filter(({ action }) => action === 'created')) {
+    let result;
+    try {
+      result = resolved.writeFile(plan.root, `${SCRIPTS_REL}/${copy.name}`, copy.bytes);
+    } catch (error) {
+      noteDir();
+      return fail([error?.message ?? String(error)]);
+    }
+    noteDir();
+    if (result.tmpLeftBehind) leftovers.push(result.tmpLeftBehind);
+    if (!result.created) return fail([`${copy.path} appeared after the check — the file found there stands`]);
+    created.push(copy.path);
+  }
+  const child = resolved.spawn(plan.runs.argv, { cwd: plan.root, env: resolved.env, stdio: 'inherit' });
+  if (child.status !== 0) return fail([`installer exited ${child.status ?? child.signal ?? child.error?.code}`]);
+  for (const path of leftovers) resolved.error(`not removed: ${path}`);
+  return EXIT_OK;
+};
+
+export const parseArgs = (argv) => {
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) return { help: true };
+  const args = { apply: false, cwd: undefined, variants: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === '--apply') args.apply = true;
+    else if (flag === '--enforcement' || flag === '--commit-guard') args.variants.push(flag.slice(2));
+    else if (flag === '--cwd') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) throw usageError('--cwd takes a value');
+      args.cwd = value;
+      index += 1;
+    } else throw usageError(`unknown argument: ${flag}`);
+  }
+  if (args.variants.length !== 1) throw usageError('pass exactly one of --enforcement and --commit-guard');
+  return { help: false, apply: args.apply, cwd: args.cwd, variant: args.variants[0] };
+};
+
+export const main = (argv, io = {}) => {
+  const resolved = { log: console.log, error: console.error, cwd: process.cwd(), toolsDir: TOOLS, ...io };
+  let args;
+  try {
+    args = parseArgs(argv);
+    if (args.help) {
+      resolved.log(USAGE);
+      return EXIT_OK;
+    }
+    args.root = resolve(resolved.cwd, args.cwd ?? '.');
+    if (!statSync(args.root, { throwIfNoEntry: false })?.isDirectory()) throw usageError(`--cwd is not a directory: ${args.root}`);
+  } catch (error) {
+    resolved.error(error.message);
+    resolved.error(USAGE);
+    return EXIT_USAGE;
+  }
+  let plan;
+  try {
+    plan = planGitHooks({ root: args.root, variant: args.variant, toolsDir: resolved.toolsDir });
+  } catch (error) {
+    resolved.error(error.message);
+    return EXIT_REFUSED;
+  }
+  if (!args.apply) {
+    for (const line of formatPlan(plan)) resolved.log(line);
+    return EXIT_OK;
+  }
+  return applyGitHooks(plan, resolved);
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/init-project.mjs

@@ -13,7 +13,7 @@ import { preflightInit } from './init-preflight.mjs';
 import { buildRecommendations, hostFacts } from './recommendations.mjs';
 import { compareSemver } from './semver-lite.mjs';
 import { EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
-import { LANE_HARNESS, VARIANT_LANES, consoleArgv, isEnvDependent, isProtectedPath, laneOf, writesOf } from './write-lanes.mjs';
+import { LANE_HARNESS, VARIANT_LANES, consoleArgv, isEnvDependent, isProtectedPath, isRejudged, laneOf, writesOf } from './write-lanes.mjs';
 
 const INSIDE_LINE = 'you are inside an agent; run this in your own terminal';
 const APPLY_PROMPT = 'apply? y/N: ';
@@ -217,17 +217,20 @@ const previewQueue = async (context, queue) => {
     context.print(result.stdout);
     const tuple = result.stdout.match(/--apply\s+(\S+)/)?.[1];
     const facts = { ...context.facts, tuple };
+    let checkDigest = null;
     if (laneOf(item.variant) === LANE_HARNESS) {
       try {
-        const { lines, refused } = context.checkApply(item.variant, facts, {});
+        const { lines, refused, digest } = context.checkApply(item.variant, facts, {});
         for (const line of lines) context.print(line);
         if (refused.length > 0) throw new Error(refused.map(({ key }) => key).join(', '));
+        checkDigest = digest;
       } catch (error) {
         context.print(`not applied: ${item.variant} — the danger check refused: ${error.message}`);
         continue;
       }
     }
-    batch.push({ ...item, applyArgv: consoleArgv(item.variant, facts).apply, writes: writesOf(item.variant, facts) });
+    batch.push({ ...item, checkFacts: facts, checkDigest, applyArgv: consoleArgv(item.variant, facts).apply,
+      writes: writesOf(item.variant, facts) });
     printNote(context, item.key);
   }
   for (const item of queue.filter(({ variant }) => consoleArgv(variant, context.facts) === null)) {
@@ -254,11 +257,24 @@ const takeRecord = (context, queue) => {
   }
 };
 
+// A rejudged item applies only while its check, run again now, answers the digest its preview showed; else the reason.
+const rejudgeFailure = (context, item) => {
+  try {
+    const { refused, digest } = context.checkApply(item.variant, item.checkFacts, {});
+    if (refused.length > 0) return `it refuses ${refused.map(({ key }) => key).join(', ')}`;
+    return digest === item.checkDigest ? null : 'its digest moved';
+  } catch (error) {
+    return String(error?.message || error);
+  }
+};
+
 const runPass = async (context, queue) => {
   const record = takeRecord(context, queue);
   if (record === null) return { code: 1, successes: 0, variants: [] };
-  const batch = await previewQueue(context, queue);
-  if (batch.length === 0) return { code: 0, successes: 0, variants: [] };
+  const previewed = await previewQueue(context, queue);
+  if (previewed.length === 0) return { code: 0, successes: 0, variants: [] };
+  // Rejudged items go first: an earlier writer of the batch (one creating .claude/) would move their check.
+  const batch = [...previewed.filter(({ variant }) => isRejudged(variant)), ...previewed.filter(({ variant }) => !isRejudged(variant))];
   const before = new Map(record);
   const outcome = { code: 0, successes: 0, variants: batch.map((item) => item.variant) };
   context.print(RUN_NONE);
@@ -271,6 +287,15 @@ const runPass = async (context, queue) => {
       outcome.code = 1;
       break;
     }
+    const failure = isRejudged(item.variant) ? rejudgeFailure(context, item) : null;
+    if (failure !== null) {
+      context.print(`not applied: ${item.variant} — its danger check no longer answers the previewed result: ${failure}`);
+      for (const later of batch.slice(index + 1)) {
+        context.print(`not applied: ${later.variant} — an earlier item's danger check no longer answers the previewed result`);
+      }
+      outcome.code = 1;
+      break;
+    }
     const result = await launch(context, item.applyArgv, ['inherit', 'pipe', 'inherit']);
     if (result.stdout) context.print(result.stdout);
     const success = result.valid && (result.status === 0 || (result.status === 5 && result.stdout.includes('install completed')));