@zyaiting/keelson 0.4.0 → 0.5.0

package/src/platforms/integration.js

@@ -3,7 +3,7 @@ import crypto from 'node:crypto';
 import path from 'node:path';
 import { exists, read, readJson, readOr, rmrf, write, writeJson } from '../lib/fs.js';
 import { installTargets, PLATFORMS } from './registry.js';
-import { managedSkillShimMatches, residentBlock } from './runtime.js';
+import { captureRuntimeOwnership, managedSkillShimMatches, residentBlock } from './runtime.js';
 
 export const MANAGED_STATE = path.join('.keelson', 'manifest.json');
 export const LEGACY_MANAGED_STATE = path.join('.keelson', '.managed.json');
@@ -100,7 +100,7 @@ export function managedStateMatches(root, targets) {
 }
 
 export function writeManagedState(root, targets, packageVersion, { vendor = false } = {}) {
-  writeJson(path.join(root, MANAGED_STATE), { schema: 1, packageVersion, vendor: Boolean(vendor), targets: targets.map(managedTarget) });
+  writeJson(path.join(root, MANAGED_STATE), { schema: 1, packageVersion, vendor: Boolean(vendor), targets: targets.map(managedTarget), runtime: captureRuntimeOwnership(root, targets, vendor) });
   if (exists(path.join(root, LEGACY_MANAGED_STATE))) rmrf(path.join(root, LEGACY_MANAGED_STATE));
   return MANAGED_STATE;
 }
@@ -173,11 +173,11 @@ const LEGACY_CLAUDE_HOOK_COMMANDS = new Set([
   'node "$CLAUDE_PROJECT_DIR/.keelson/hooks/session-start.mjs"',
   'node "$CLAUDE_PROJECT_DIR/.keelson/hooks/prompt-state.mjs"',
 ]);
-const CLAUDE_HOOK_COMMANDS = new Set(['keelson hook session-start', 'keelson hook prompt-state', ...LEGACY_CLAUDE_HOOK_COMMANDS]);
+const CLAUDE_HOOK_COMMANDS = new Set(['keelson hook session-start', 'keelson hook prompt-state', 'keelson hook workflow-guard', ...LEGACY_CLAUDE_HOOK_COMMANDS]);
 const isClaudeHook = (hook) => hook?.type === 'command' && CLAUDE_HOOK_COMMANDS.has(String(hook.command));
 
 export function installHooks(root) {
-  removeHooks(root, { legacyOnly: true });
+  removeHooks(root);
   const settingsPath = path.join(root, '.claude', 'settings.json');
   const settings = readJson(settingsPath, {}) ?? {};
   settings.hooks ??= {};
@@ -192,6 +192,8 @@ export function installHooks(root) {
   };
   ensure('SessionStart', 'startup|resume|clear|compact', 'session-start.mjs');
   ensure('UserPromptSubmit', null, 'prompt-state.mjs');
+  ensure('PreToolUse', 'Edit|Write|MultiEdit|NotebookEdit|Agent|Task', 'workflow-guard.mjs');
+  ensure('SubagentStart', null, 'workflow-guard.mjs');
   writeJson(settingsPath, settings);
   return ['.claude/settings.json'];
 }
@@ -216,78 +218,41 @@ export function removeHooks(root, { legacyOnly = false } = {}) {
   writeJson(settingsPath, settings);
 }
 
-const CODEBUDDY_SESSION_COMMAND = 'keelson hook codebuddy-session';
 const LEGACY_CODEBUDDY_SESSION_COMMAND = 'node "$CODEBUDDY_PROJECT_DIR/.keelson/hooks/codebuddy-session.mjs"';
-const isCodeBuddyHook = (hook) => hook?.type === 'command' && hook.command === CODEBUDDY_SESSION_COMMAND;
-
-function ensureCodeBuddyHook(settings, event, matcher = null) {
-  settings.hooks ??= {};
-  settings.hooks[event] ??= [];
-  const found = settings.hooks[event].find((g) =>
-    (g.hooks ?? []).some(isCodeBuddyHook),
-  );
-  if (found) {
-    if (matcher && found.matcher !== matcher) found.matcher = matcher;
-    else if (!matcher && 'matcher' in found) delete found.matcher;
-    return;
-  }
-  const group = {
-    hooks: [{
-      type: 'command',
-      command: CODEBUDDY_SESSION_COMMAND,
-      timeout: 10,
-    }],
-  };
-  if (matcher) group.matcher = matcher;
-  settings.hooks[event].push(group);
-}
-
-export function installSessionAdapter(root, target) {
-  const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return [];
-
-  if (p.sessionAdapter === 'codebuddy-hooks') {
-    removeCodeBuddyHooks(root, { legacyOnly: true });
-    const settingsPath = path.join(root, '.codebuddy', 'settings.json');
-    const settings = readJson(settingsPath, {}) ?? {};
-    ensureCodeBuddyHook(settings, 'SessionStart');
-    ensureCodeBuddyHook(settings, 'UserPromptSubmit');
-    ensureCodeBuddyHook(settings, 'PreToolUse', 'Bash|PowerShell');
-    writeJson(settingsPath, settings);
-    return [path.relative(root, settingsPath)];
-  }
-
-  return [];
-}
-
-export function plannedSessionAdapterFiles(root, target) {
-  const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  const rows = [];
-  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return rows;
-
-  if (p.sessionAdapter === 'codebuddy-hooks') {
-    const settings = readJson(path.join(root, '.codebuddy', 'settings.json'), {}) ?? {};
-    const has = (event, matcher = null) => (settings.hooks?.[event] ?? []).some((g) =>
-      (matcher === null || g.matcher === matcher) &&
-      (g.hooks ?? []).some(isCodeBuddyHook),
-    );
-    const ready = has('SessionStart') && has('UserPromptSubmit') && has('PreToolUse', 'Bash|PowerShell');
-    rows.push({ path: '.codebuddy/settings.json (Keelson session hooks)', status: ready ? 'unchanged' : exists(path.join(root, '.codebuddy', 'settings.json')) ? 'update' : 'create' });
-  }
-
-  return rows;
-}
-
-function removeCodeBuddyHooks(root, { legacyOnly = false } = {}) {
-  const settingsPath = path.join(root, '.codebuddy', 'settings.json');
+const HOST_HOOKS = {
+  'codebuddy-hooks': {
+    file: '.codebuddy/settings.json',
+    registrations: [
+      ['SessionStart', null, 'codebuddy-session'],
+      ['UserPromptSubmit', null, 'codebuddy-session'],
+      ['PreToolUse', 'Bash|PowerShell', 'codebuddy-session'],
+      ['PreToolUse', '^(Edit|Write|MultiEdit|NotebookEdit|NotebookWrite|Agent|Task)$', 'codebuddy-workflow'],
+    ],
+  },
+  'codex-thread-env': {
+    file: '.codex/hooks.json',
+    registrations: [
+      ['SessionStart', null, 'codex-session'],
+      ['UserPromptSubmit', null, 'codex-session'],
+      ['PreToolUse', '^(apply_patch|Edit|Write|Agent|spawn_agent)$', 'codex-workflow'],
+      ['SubagentStart', null, 'codex-workflow'],
+    ],
+  },
+};
+const adapterFor = (target) => HOST_HOOKS[target?.sessionAdapter];
+const isAdapterHook = (h, adapter) => h?.type === 'command' && adapter.registrations.some(([, , name]) => h.command === `keelson hook ${name}`);
+const hasRegistration = (settings, [event, matcher, name]) => (settings.hooks?.[event] ?? []).some((g) =>
+  (g.matcher ?? null) === matcher && (g.hooks ?? []).some((h) => h.type === 'command' && h.command === `keelson hook ${name}`));
+
+function removeAdapterHooks(root, adapter) {
+  const settingsPath = path.join(root, adapter.file);
   const settings = readJson(settingsPath, null);
   if (!settings?.hooks) return false;
   let changed = false;
   for (const event of Object.keys(settings.hooks)) {
     settings.hooks[event] = settings.hooks[event].map((g) => {
-      const hooks = (g.hooks ?? []).filter((h) =>
-        !(h?.type === 'command' && h.command === LEGACY_CODEBUDDY_SESSION_COMMAND) && (legacyOnly || !isCodeBuddyHook(h)),
-      );
+      const hooks = (g.hooks ?? []).filter((h) => !isAdapterHook(h, adapter) &&
+        !(adapter.file.startsWith('.codebuddy/') && h?.type === 'command' && h.command === LEGACY_CODEBUDDY_SESSION_COMMAND));
       if (hooks.length === (g.hooks ?? []).length) return g;
       changed = true;
       return hooks.length ? { ...g, hooks } : null;
@@ -301,32 +266,49 @@ function removeCodeBuddyHooks(root, { legacyOnly = false } = {}) {
   return true;
 }
 
-export function removeSessionAdapter(root, target, keep = new Set()) {
+export function installSessionAdapter(root, target) {
   const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  const removed = [];
-  if (p?.sessionAdapter === 'codebuddy-hooks') {
-    if (removeCodeBuddyHooks(root)) removed.push('.codebuddy/settings.json (Keelson hooks)');
+  const adapter = adapterFor(p);
+  if (!adapter) return [];
+  // Split owned hooks out of mixed groups; never change a user's matcher.
+  removeAdapterHooks(root, adapter);
+  const settingsPath = path.join(root, adapter.file);
+  const settings = readJson(settingsPath, {}) ?? {};
+  settings.hooks ??= {};
+  for (const [event, matcher, name] of adapter.registrations) {
+    settings.hooks[event] ??= [];
+    settings.hooks[event].push({
+      ...(matcher ? { matcher } : {}),
+      hooks: [{ type: 'command', command: `keelson hook ${name}`, timeout: 10 }],
+    });
   }
-  return removed;
+  writeJson(settingsPath, settings);
+  return [adapter.file];
 }
 
-export function sessionAdapterProblems(root, target) {
+export function plannedSessionAdapterFiles(root, target) {
   const p = typeof target === 'string' ? PLATFORMS[target] : target;
-  const problems = [];
-  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return problems;
+  const adapter = adapterFor(p);
+  if (!adapter) return [];
+  const file = path.join(root, adapter.file);
+  const settings = readJson(file, {}) ?? {};
+  const ready = adapter.registrations.every((registration) => hasRegistration(settings, registration));
+  return [{ path: `${adapter.file} (Keelson workflow hooks)`, status: ready ? 'unchanged' : exists(file) ? 'update' : 'create' }];
+}
 
-  if (p.sessionAdapter === 'codebuddy-hooks') {
-    const settings = readJson(path.join(root, '.codebuddy', 'settings.json'), {}) ?? {};
-    const has = (event, matcher = null) => (settings.hooks?.[event] ?? []).some((g) =>
-      (matcher === null || g.matcher === matcher) &&
-      (g.hooks ?? []).some(isCodeBuddyHook),
-    );
-    if (!has('SessionStart')) problems.push(`${p.label}: SessionStart session hook not registered`);
-    if (!has('UserPromptSubmit')) problems.push(`${p.label}: UserPromptSubmit session hook not registered`);
-    if (!has('PreToolUse', 'Bash|PowerShell')) problems.push(`${p.label}: Bash|PowerShell PreToolUse session hook not registered`);
-  }
+export function removeSessionAdapter(root, target, keep = new Set()) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const adapter = adapterFor(p);
+  return adapter && removeAdapterHooks(root, adapter) ? [`${adapter.file} (Keelson hooks)`] : [];
+}
 
-  return problems;
+export function sessionAdapterProblems(root, target) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const adapter = adapterFor(p);
+  if (!adapter) return [];
+  const settings = readJson(path.join(root, adapter.file), {}) ?? {};
+  return adapter.registrations.filter((r) => !hasRegistration(settings, r))
+    .map(([event, matcher, name]) => `${p.label}: ${event}${matcher ? ` (${matcher})` : ''} hook ${name} not registered`);
 }
 
 function removeTargetSurfaces(root, p, keep = new Set()) {
@@ -334,7 +316,7 @@ function removeTargetSurfaces(root, p, keep = new Set()) {
   const skillRel = path.join(p.skillsDir, 'keelson');
   const skill = path.join(root, skillRel);
   const managed = readManagedState(root);
-  if (!keep.has(skillRel) && exists(skill) && managedSkillShimMatches(root, p, managed?.packageVersion)) {
+  if (!keep.has(skillRel) && exists(skill) && managedSkillShimMatches(root, p, managed?.packageVersion, managed)) {
     rmrf(skill);
     removed.push(path.relative(root, skill));
   }
@@ -348,7 +330,7 @@ function removeTargetSurfaces(root, p, keep = new Set()) {
     rmrf(path.join(root, p.rulesFile));
     removed.push(p.rulesFile);
   }
-  if (p.hooks && !keep.has('.claude/settings.json')) removeHooks(root);
+  if (p.hooks && p.id === 'claude' && !keep.has('.claude/settings.json')) removeHooks(root);
   removed.push(...removeSessionAdapter(root, p, keep));
   return removed;
 }
@@ -357,13 +339,13 @@ export function reconcileManagedTargets(root, targets) {
   const removed = [];
   const stale = staleManagedTargets(root, targets);
   const keep = new Set(targets.flatMap(managedSurfacePaths));
-  if (targets.some((p) => p.hooks)) keep.add('.claude/settings.json');
+  if (targets.some((p) => p.hooks && p.id === 'claude')) keep.add('.claude/settings.json');
   for (const p of stale) removed.push(...removeTargetSurfaces(root, p, keep));
   for (const rel of legacyManagedRemovals(root, targets)) {
     rmrf(path.join(root, rel));
     removed.push(rel);
   }
-  if (stale.some((p) => p.hooks) && !targets.some((p) => p.hooks)) {
+  if (stale.some((p) => p.hooks && p.id === 'claude') && !targets.some((p) => p.hooks && p.id === 'claude')) {
     removeHooks(root);
   }
   return [...new Set(removed)];

package/src/platforms/runtime.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import crypto from 'node:crypto';
 import path from 'node:path';
 import { PKG_ROOT } from '../lib/paths.js';
-import { exists, read, walk, write, rmrf, replaceDirSafe, withLock } from '../lib/fs.js';
+import { exists, read, readJson, walk, write, rmrf, replaceDirSafe, withLock } from '../lib/fs.js';
 import { PLATFORMS } from './registry.js';
 
 export const CANONICAL_SKILL_DIR = path.join('.keelson', 'skill');
@@ -124,6 +124,42 @@ function treeHash(dir) {
   } catch { return null; }
 }
 
+// Before 0.5.0, manifests carried a version but no content digest. Bootstrap
+// only from exact published output; future releases use the installed digest.
+const HISTORICAL_RUNTIME = readJson(path.join(PKG_ROOT, 'registry', 'runtime-hashes.json'), {}).versions ?? {};
+
+function runtimeDigest(root, rel, kind) {
+  const target = path.join(root, rel);
+  if (kind !== 'workflows') return treeHash(target);
+  try { return fs.lstatSync(target).isFile() ? fileHash(read(target)) : null; } catch { return null; }
+}
+
+function previousRuntimeMatches(root, rel, kind, previousState) {
+  if (!previousState) return false;
+  const owned = kind === 'shims'
+    ? previousState.targets?.some((t) => t.skillsDir && path.join(t.skillsDir, 'keelson') === rel)
+    : previousState.vendor === true;
+  if (!owned) return false;
+  const actual = runtimeDigest(root, rel, kind);
+  if (!actual) return false;
+  const recorded = previousState.runtime?.[rel];
+  if (recorded) return actual === recorded;
+  return (HISTORICAL_RUNTIME[previousState.packageVersion]?.[kind] ?? []).includes(actual);
+}
+
+export function captureRuntimeOwnership(root, targets, vendor) {
+  const runtime = {};
+  for (const target of targets) {
+    const rel = path.join(target.skillsDir, 'keelson');
+    runtime[rel] = runtimeDigest(root, rel, 'shims');
+  }
+  if (vendor) {
+    runtime[CANONICAL_SKILL_DIR] = runtimeDigest(root, CANONICAL_SKILL_DIR, 'skills');
+    runtime[CANONICAL_WORKFLOW] = runtimeDigest(root, CANONICAL_WORKFLOW, 'workflows');
+  }
+  return runtime;
+}
+
 function canonicalSkillMatches(root, { lang, profile, version }) {
   const dest = path.join(root, CANONICAL_SKILL_DIR);
   const files = renderSkillFiles(lang, profile, version);
@@ -132,12 +168,19 @@ function canonicalSkillMatches(root, { lang, profile, version }) {
   return version === '0.3.0' && treeHash(dest) === LEGACY_V03_SKILL_TREE_HASHES.get(`${lang}/${profile}`);
 }
 
-export function installCanonicalSkill(root, { lang, profile, version, force = false }) {
+export function assertCanonicalSkillInstallable(root, { lang, profile, version, previousState, force = false }) {
   const dest = path.join(root, CANONICAL_SKILL_DIR);
-  const files = renderSkillFiles(lang, profile, version);
-  if (fs.lstatSync(dest, { throwIfNoEntry: false }) && !canonicalSkillMatches(root, { lang, profile, version }) && !force) {
+  if (fs.lstatSync(dest, { throwIfNoEntry: false }) && !canonicalSkillMatches(root, { lang, profile, version }) &&
+    !previousRuntimeMatches(root, CANONICAL_SKILL_DIR, 'skills', previousState) &&
+    !(previousState?.packageVersion === '0.3.0' && canonicalSkillMatches(root, { lang, profile, version: '0.3.0' })) && !force) {
     throw new Error('vendored skill differs from this CLI output; Keelson left it unchanged. Review it, then pass --force only if replacing the whole directory is intended.');
   }
+}
+
+export function installCanonicalSkill(root, options) {
+  assertCanonicalSkillInstallable(root, options);
+  const dest = path.join(root, CANONICAL_SKILL_DIR);
+  const files = renderSkillFiles(options.lang, options.profile, options.version);
   withLock(dest, () => {
     replaceDirSafe(dest, (tmp) => {
       for (const f of files) write(path.join(tmp, f.rel), f.content);
@@ -157,10 +200,10 @@ function skillShimMatches(dest, content, legacyVersion) {
     (normalize(read(skill)) === content || legacyV03SkillShimMatches(dest, legacyVersion));
 }
 
-function assertSkillInstallable(root, target, { lang, version, legacyVersion, previousVersion, force }) {
+function assertSkillInstallable(root, target, { lang, version, legacyVersion, previousVersion, previousState, force }) {
   const p = typeof target === 'string' ? PLATFORMS[target] : target;
   const dest = path.join(root, p.skillsDir, 'keelson');
-  const priorOutput = previousVersion && managedSkillShimMatches(root, p, previousVersion);
+  const priorOutput = previousVersion && managedSkillShimMatches(root, p, previousVersion, previousState);
   if (fs.lstatSync(dest, { throwIfNoEntry: false }) && !skillShimMatches(dest, renderSkillShim(lang, version), legacyVersion) && !priorOutput && !force) {
     throw new Error('discovery shim differs from this CLI output; Keelson left it unchanged. Review it, then pass --force only if replacing the whole directory is intended.');
   }
@@ -177,18 +220,19 @@ export function assertSkillsInstallable(root, targets, options) {
   }
 }
 
-/** True only for a complete current shim or the byte-exact v0.3 shim. */
-export function managedSkillShimMatches(root, target, version) {
+/** True only for a complete generated shim or its recorded/published digest. */
+export function managedSkillShimMatches(root, target, version, previousState) {
   const p = typeof target === 'string' ? PLATFORMS[target] : target;
   const dest = path.join(root, p.skillsDir, 'keelson');
-  return ['en', 'zh'].some((lang) => skillShimMatches(dest, renderSkillShim(lang, version), version));
+  return previousRuntimeMatches(root, path.join(p.skillsDir, 'keelson'), 'shims', previousState) ||
+    ['en', 'zh'].some((lang) => skillShimMatches(dest, renderSkillShim(lang, version), version));
 }
 
-export function installSkill(root, target, { lang, version, legacyVersion = null, previousVersion = null, force = false }) {
+export function installSkill(root, target, { lang, version, legacyVersion = null, previousVersion = null, previousState, force = false }) {
   const p = typeof target === 'string' ? PLATFORMS[target] : target;
   const dest = path.join(root, p.skillsDir, 'keelson');
   const content = renderSkillShim(lang, version);
-  assertSkillInstallable(root, p, { lang, version, legacyVersion, previousVersion, force });
+  assertSkillInstallable(root, p, { lang, version, legacyVersion, previousVersion, previousState, force });
   withLock(dest, () => replaceDirSafe(dest, (tmp) => write(path.join(tmp, 'SKILL.md'), content)));
   return path.relative(root, dest);
 }
@@ -210,14 +254,21 @@ export function plannedWorkflowFile(root, { lang, guide = false }) {
   return { path: path.relative(root, target), status };
 }
 
-export function installWorkflow(root, { lang, guide = false, force = false }) {
+export function assertWorkflowInstallable(root, { lang, guide = false, previousState, force = false }) {
   const target = path.join(root, CANONICAL_WORKFLOW);
   const content = workflowContent(lang, guide);
   const stat = fs.lstatSync(target, { throwIfNoEntry: false });
-  if (stat && (stat.isSymbolicLink() || normalize(read(target)) !== content) && !force) {
+  if (stat && (!stat.isFile() || normalize(read(target)) !== content) &&
+    !previousRuntimeMatches(root, CANONICAL_WORKFLOW, 'workflows', previousState) &&
+    !(previousState?.packageVersion === '0.3.0' && stat.isFile() && LEGACY_V03_WORKFLOW_HASHES.has(fileHash(read(target)))) && !force) {
     throw new Error('vendored workflow differs from this CLI output; Keelson left it unchanged. Review it, then pass --force only if replacing it is intended.');
   }
-  write(target, content);
+}
+
+export function installWorkflow(root, options) {
+  assertWorkflowInstallable(root, options);
+  const target = path.join(root, CANONICAL_WORKFLOW);
+  write(target, workflowContent(options.lang, options.guide));
   return path.relative(root, target);
 }
 
@@ -225,12 +276,12 @@ export function residentBlock(lang) {
   return read(path.join(skillSource(lang), 'templates', 'resident-block.md'));
 }
 
-export function removeCanonicalRuntime(root, { lang, profile, version, guide = false } = {}) {
+export function removeCanonicalRuntime(root, { lang, profile, version, guide = false, previousState } = {}) {
   const removed = [];
   const preserved = [];
   const skill = path.join(root, CANONICAL_SKILL_DIR);
   if (exists(skill)) {
-    if (canonicalSkillMatches(root, { lang, profile, version })) {
+    if (canonicalSkillMatches(root, { lang, profile, version }) || previousRuntimeMatches(root, CANONICAL_SKILL_DIR, 'skills', previousState)) {
       rmrf(skill);
       removed.push(CANONICAL_SKILL_DIR);
     } else preserved.push(CANONICAL_SKILL_DIR);
@@ -240,7 +291,7 @@ export function removeCanonicalRuntime(root, { lang, profile, version, guide = f
     preserved.push(CANONICAL_WORKFLOW);
   } else if (exists(workflow)) {
     const legacyWorkflow = version === '0.3.0' && LEGACY_V03_WORKFLOW_HASHES.has(fileHash(read(workflow)));
-    if (normalize(read(workflow)) === workflowContent(lang, guide) || legacyWorkflow) {
+    if (normalize(read(workflow)) === workflowContent(lang, guide) || legacyWorkflow || previousRuntimeMatches(root, CANONICAL_WORKFLOW, 'workflows', previousState)) {
       rmrf(workflow);
       removed.push(CANONICAL_WORKFLOW);
     } else preserved.push(CANONICAL_WORKFLOW);