@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/helper/harness-paths.ts

@@ -0,0 +1,140 @@
+'use strict';
+
+// harness-paths.js — the one validator and resolver for the native path facts DoFlow declares in
+// core/registry/harnesses.json under each harness's "paths" section (Stage 3 of the structure
+// refactor). Adapters consume these declarations through resolveHarnessPaths() instead of
+// hardcoding directory joins; whatever cannot be expressed here without branching (env-var
+// overrides, conditional user directories, content-embedded placeholders) stays in its adapter
+// behind an inline justification comment naming why it cannot be declared.
+//
+// The schema is deliberately minimal — no template engine, no expression language, no string
+// interpolation beyond plain segment joins:
+//
+//   "paths": {
+//     "<surface>": <rule>                                    — same rule for both scopes
+//                 | { "project": <rule>, "user": <rule> }    — per-scope rules; an omitted scope
+//                                                              resolves to null (the surface
+//                                                              genuinely does not exist there)
+//   }
+//
+//   <rule> ::= { "base": "root" | "home", "segments": ["<segment>", ...] }
+//
+// "root" is the scope's install root: the project directory at project scope, the home directory
+// at user scope (adapters historically name that same value scopeRoot at user scope). "home" is
+// always the home directory. Segments are plain single path segments — no separators, no "..".
+// XDG-style directories (~/.config/opencode) are just home-rooted segment joins: no adapter in
+// this repository consults $XDG_* today, so the schema carries no xdg base rather than declaring
+// vocabulary nothing reads.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../helper/harness-paths.ts')` keeps working while the tree is still `.js`. The
+// `./repo-root` require stays bare while repo-root is still `.js`.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('./repo-root.ts');
+
+const PATH_BASES = new Set(['root', 'home']);
+const SURFACE_NAME = /^[a-z][a-zA-Z0-9]*$/;
+const SEGMENT = /^(?!\.\.$)[^\\/]+$/;
+const SCOPES = ['project', 'user'];
+
+interface PathRule {
+  base?: string;
+  segments?: string[];
+}
+
+interface ResolveInputs {
+  scope?: string;
+  scopeRoot?: string;
+  homeDir?: string;
+}
+
+function issue(errors: string[], location: string, message: string): void { errors.push(`${location}: ${message}`); }
+
+/** Validate one {base, segments} rule. Returns errors via the pushed array. */
+function validateRule(rule: any, location: string, errors: string[]): void {
+  if (!rule || typeof rule !== 'object' || Array.isArray(rule)) {
+    issue(errors, location, 'must be an object'); return;
+  }
+  for (const key of Object.keys(rule)) {
+    if (!['base', 'segments'].includes(key)) issue(errors, location, `unsupported key '${key}'`);
+  }
+  if (!PATH_BASES.has(rule.base)) issue(errors, location, `base must be one of ${[...PATH_BASES].join(', ')}`);
+  const segments = rule.segments;
+  if (!Array.isArray(segments) || segments.some((segment: any) => typeof segment !== 'string' || !SEGMENT.test(segment))) {
+    issue(errors, location, "segments must be an array of plain single path segments (no '/', no '\\', no '..')");
+  }
+}
+
+/** Validate one harness's whole paths section. Unknown keys and malformed rules are rejected
+ * loudly: a typo'd declaration must fail the registry load, not silently fall back to whatever
+ * the adapter used to hardcode. Returns an array of error messages (empty when valid). */
+function validatePathsSection(section: any, location: string): string[] {
+  const errors: string[] = [];
+  if (!section || typeof section !== 'object' || Array.isArray(section)) {
+    return [`${location}: must be an object`];
+  }
+  for (const [name, value] of Object.entries<any>(section)) {
+    const at = `${location}.${name}`;
+    if (!SURFACE_NAME.test(name)) { issue(errors, at, `surface name '${name}' must be camelCase`); continue; }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) { issue(errors, at, 'must be an object'); continue; }
+    const hasBase = value.base !== undefined || value.segments !== undefined;
+    const scopedKeys = SCOPES.filter((scope) => value[scope] !== undefined);
+    const knownKeys = [...SCOPES, 'base', 'segments'];
+    for (const key of Object.keys(value)) {
+      if (!knownKeys.includes(key)) issue(errors, at, `unsupported key '${key}'`);
+    }
+    if (hasBase && scopedKeys.length) {
+      issue(errors, at, 'must be either a single {base, segments} rule or per-scope {project, user} rules, not both');
+      continue;
+    }
+    if (hasBase) { validateRule(value, at, errors); continue; }
+    if (!scopedKeys.length) { issue(errors, at, `requires a rule or at least one of ${SCOPES.join('/')}`); continue; }
+    for (const scope of scopedKeys) validateRule(value[scope], `${at}.${scope}`, errors);
+  }
+  return errors;
+}
+
+/** Resolve one rule to an absolute path. */
+function resolveRule(rule: PathRule, { root, home }: { root: string; home: string }): string {
+  const base = rule.base === 'home' ? home : root;
+  return path.join(base, ...(rule.segments || []));
+}
+
+/**
+ * Resolve a harness's declared paths section against runtime scope inputs.
+ * `scope` accepts the adapters' historical spellings ('global' == 'user').
+ * Returns { <surface>: absolutePath | null } — null when the scope has no rule for a surface —
+ * plus `root`, the scope's install root itself (an input, not a declaration).
+ */
+function resolveHarnessPaths(section: any, { scope, scopeRoot, homeDir }: ResolveInputs = {}): Record<string, string | null> {
+  const userScope = scope === 'user' || scope === 'global';
+  const home = path.resolve(homeDir || scopeRoot);
+  const root = userScope ? home : path.resolve(scopeRoot);
+  const resolved: Record<string, string | null> = { root };
+  for (const [name, value] of Object.entries<any>(section || {})) {
+    const rule = (value.base !== undefined || value.segments !== undefined)
+      ? value
+      : (value[userScope ? 'user' : 'project'] ?? null);
+    resolved[name] = rule ? resolveRule(rule, { root, home }) : null;
+  }
+  return resolved;
+}
+
+let declaredCache: { repoRoot: string; paths: Record<string, any> } | undefined;
+/** Every harness's declared paths section, keyed by harness id, read straight from
+ * core/registry/harnesses.json (memoized per process — the file ships inside the package).
+ * Adapters default their factories to this, so a factory called with no arguments and the CLI
+ * wiring in src/cli/shared.js#buildAdapterRegistry consume byte-identical declarations. */
+function declaredHarnessPaths(repoRoot: string = REPO_ROOT): Record<string, any> {
+  if (declaredCache && declaredCache.repoRoot === path.resolve(repoRoot)) return declaredCache.paths;
+  const file = path.join(path.resolve(repoRoot), 'core', 'registry', 'harnesses.json');
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const paths = Object.fromEntries((parsed.harnesses || []).map((harness: any) => [harness.id, harness.paths ?? {}]));
+  declaredCache = { repoRoot: path.resolve(repoRoot), paths };
+  return paths;
+}
+
+module.exports = { PATH_BASES, validatePathsSection, resolveHarnessPaths, declaredHarnessPaths };

package/src/helper/marker-merge.ts

@@ -0,0 +1,116 @@
+'use strict';
+// marker-merge.js — marker-delimited merge so a target project's own CLAUDE.md
+// content survives repeated doflow install/update runs; only the span between the
+// markers is ever regenerated.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../helper/marker-merge.ts')` keeps working while the tree is still `.js`.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MARKER_START =
+  '<!-- doflow:start — content below is managed by doflow install/update; edits here are overwritten on the next run -->';
+const MARKER_END = '<!-- doflow:end -->';
+
+/**
+ * Merge `srcAbs`'s content into `dstAbs` inside a doflow-owned marker span,
+ * preserving any of `dstAbs`'s own content outside that span byte-for-byte.
+ */
+function mergeMarkedSection(srcAbs: string, dstAbs: string, { dryRun = false }: { dryRun?: boolean } = {}): { changed: boolean } {
+  const srcContent = fs.readFileSync(srcAbs, 'utf8').replace(/\s+$/, '');
+  const section = `${MARKER_START}\n${srcContent}\n${MARKER_END}\n`;
+
+  // Read once, reused both for parsing and for the final no-op comparison below.
+  const existing = fs.existsSync(dstAbs) ? fs.readFileSync(dstAbs, 'utf8') : null;
+
+  let newContent: string;
+  if (existing === null) {
+    newContent = section;
+  } else {
+    const startIdx = existing.indexOf(MARKER_START);
+    if (startIdx === -1) {
+      // Foreign file with no doflow span yet — append without touching existing's own bytes.
+      // A file ending in a newline (or empty) always gets exactly one '\n', so removeMarkedSection
+      // can strip exactly one and hand the user's bytes back unchanged; one with no final newline
+      // gets a blank line, and comes back from removal with a final newline added.
+      const separator = existing === '' || existing.endsWith('\n') ? '\n' : '\n\n';
+      newContent = existing + separator + section;
+    } else {
+      const endIdx = existing.indexOf(MARKER_END, startIdx + MARKER_START.length);
+      if (endIdx === -1) {
+        throw new Error(
+          `Malformed doflow markers in ${dstAbs}: found MARKER_START with no matching MARKER_END — fix or remove the markers manually before retrying.`
+        );
+      }
+      // Search for a duplicate START only *after* the span closes, not from inside it — the
+      // previous version of this function searched from startIdx + MARKER_START.length, which
+      // is *inside* the span, and false-positived whenever the span's own content happened to
+      // contain the marker text (e.g. srcContent documenting this exact mechanism). Searching
+      // from after the real end only flags a genuine second, structurally separate span.
+      //
+      // Residual limitation: endIdx above is still the *first* MARKER_END found after startIdx,
+      // so srcContent containing the literal MARKER_END text (not just MARKER_START) could still
+      // truncate the span early. Fixing that by taking the *last* MARKER_END in the file instead
+      // was tried and reverted — it silently defeated this exact duplicate-span detection (two
+      // complete, genuinely separate spans collapse into one under lastIndexOf). Between "rare,
+      // avoidable corruption if source content literally quotes MARKER_END" and "silently losing
+      // detection of real duplicate spans," the latter is worse, so this trade-off is intentional
+      // pending a more precise fix.
+      const dupIdx = existing.indexOf(MARKER_START, endIdx + MARKER_END.length);
+      if (dupIdx !== -1) {
+        throw new Error(
+          `Malformed doflow markers in ${dstAbs}: found a duplicate doflow:start marker — fix or remove the markers manually before retrying.`
+        );
+      }
+      // section always supplies its own trailing "\n" after MARKER_END, so the
+      // original file's matching trailing "\n" (if present) must be consumed here —
+      // otherwise a replace with no real change grows the file by one newline
+      // every time it runs (breaks idempotency).
+      let afterEnd = endIdx + MARKER_END.length;
+      if (existing[afterEnd] === '\n') afterEnd += 1;
+      newContent = existing.slice(0, startIdx) + section + existing.slice(afterEnd);
+    }
+  }
+
+  if (existing === newContent) return { changed: false };
+  if (dryRun) return { changed: true };
+
+  fs.mkdirSync(path.dirname(dstAbs), { recursive: true });
+  fs.writeFileSync(dstAbs, newContent);
+  return { changed: true };
+}
+
+/**
+ * Strip only the doflow-managed span from `file`, leaving any surrounding content (before/after
+ * the markers) byte-for-byte untouched. Companion to `mergeMarkedSection` — shared by the Claude
+ * and Codex adapters' `remove()`, which had each carried an identical private copy of this.
+ * A file that held nothing but the span is DoFlow's own and is deleted; any other file is written
+ * back, even when only whitespace remains.
+ * @returns whether a managed span was found and stripped (false if the file doesn't
+ *          exist or has no doflow markers — both are no-ops, not errors)
+ */
+function removeMarkedSection(file: string): boolean {
+  if (!fs.existsSync(file)) return false;
+  const existing = fs.readFileSync(file, 'utf8');
+  const start = existing.indexOf(MARKER_START);
+  if (start === -1) return false;
+  const end = existing.indexOf(MARKER_END, start + MARKER_START.length);
+  if (end === -1 || existing.indexOf(MARKER_START, end + MARKER_END.length) !== -1) {
+    throw new Error(`Refusing to remove malformed DoFlow markers in ${file}`);
+  }
+  let after = end + MARKER_END.length;
+  if (existing[after] === '\n') after += 1;
+  const before = existing.slice(0, start);
+  const rest = existing.slice(after);
+  if (before === '' && rest === '') {
+    fs.unlinkSync(file);
+    return true;
+  }
+  // Do not alter user content; only remove the one '\n' mergeMarkedSection put before an
+  // appended span.
+  fs.writeFileSync(file, (rest === '' && before.endsWith('\n') ? before.slice(0, -1) : before) + rest);
+  return true;
+}
+
+module.exports = { mergeMarkedSection, removeMarkedSection, MARKER_START, MARKER_END };

package/src/helper/prompt.ts

@@ -0,0 +1,61 @@
+'use strict';
+// prompt.js — port of sync.sh's confirm(): y/N prompt, auto-confirmed under --force.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../helper/prompt.ts')` keeps working while the rest of the tree is still `.js`.
+const fs = require('node:fs');
+
+/**
+ * fs.readSync(0, ...) is documented as blocking, but that only holds if fd 0's O_NONBLOCK flag is
+ * clear. On a real TTY that flag can end up set (observed after raw-mode use elsewhere in the
+ * process, e.g. mcp.js's checkbox prompt) — a read attempted before the user has typed anything
+ * then throws EAGAIN instead of waiting for a keypress. That's "not ready yet", not "no stdin
+ * available": retry after a brief synchronous sleep rather than failing the prompt closed. Only
+ * done when stdin is actually a TTY (a human might still type) and bounded by a deadline (a fd
+ * that will genuinely never produce data must still fail closed, not hang forever).
+ */
+function readSyncBlocking(fd: number, buf: Buffer): number {
+  const deadline = Date.now() + 5 * 60 * 1000;
+  for (;;) {
+    try {
+      return fs.readSync(fd, buf, 0, buf.length, null);
+    } catch (e: any) {
+      if (!process.stdin.isTTY || e.code !== 'EAGAIN' || Date.now() > deadline) throw e;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+}
+
+/** true if confirmed (via --force or an explicit y/Y reply) */
+function confirm(message: string, force: boolean): boolean {
+  if (force) {
+    console.error(`[INFO]  ${message} [auto-confirmed via --force]`);
+    return true;
+  }
+  process.stdout.write(`${message} [y/N] `);
+  const buf = Buffer.alloc(256);
+  let bytesRead = 0;
+  try {
+    bytesRead = readSyncBlocking(0, buf);
+  } catch {
+    return false; // no stdin available (e.g. piped/non-interactive) — matches bash `read` failing closed
+  }
+  const reply = buf.toString('utf8', 0, bytesRead).trim();
+  return /^[Yy]$/.test(reply);
+}
+
+/** Free-text stdin read (e.g. "which backup id?"), matching sync.sh's `read -r reply`. */
+function promptLine(message: string): string {
+  process.stdout.write(message);
+  const buf = Buffer.alloc(1024);
+  let bytesRead = 0;
+  try {
+    bytesRead = readSyncBlocking(0, buf);
+  } catch {
+    return '';
+  }
+  return buf.toString('utf8', 0, bytesRead).trim();
+}
+
+module.exports = { confirm, promptLine, readSyncBlocking };

package/src/helper/repo-root.ts

@@ -0,0 +1,29 @@
+'use strict';
+
+const path = require('node:path');
+
+/**
+ * The package root, resolved once from this file's own location.
+ *
+ * Eighteen modules used to compute this themselves as `REPO_ROOT`, which
+ * silently encodes how deep the computing file sits. Grouping the scaffold, trace and verification
+ * modules into directories moved three of them one level down and turned that uniform duplication
+ * into two different forms of the same expression — so a later move has to pick the right one, with
+ * nothing checking the choice. Every wrong pick resolves to a real directory (`<repo>/src`), so it
+ * fails by reading the wrong tree rather than by throwing.
+ *
+ * Homed in `src/helper/` because the root is not a runtime, install or harness concern: it is the
+ * one fact all three layers share. `src/adapters/`, `src/install/` and `src/lifecycle/` already
+ * depend on this directory.
+ *
+ * A constant rather than a function: it cannot vary within a process, and a function invites a
+ * caller to pass an argument that would make it vary.
+ *
+ * TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+ * native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+ * caller's `require('../helper/repo-root.ts')` keeps working while the rest of the tree is still
+ * `.js`. As the highest-fan-out helper, this is the last T1 leaf converted.
+ */
+const REPO_ROOT: string = path.resolve(__dirname, '..', '..');
+
+module.exports = { REPO_ROOT };

package/src/helper/settings-merge.ts

@@ -0,0 +1,151 @@
+'use strict';
+
+// settings.json and keybindings.json are SHARED files: the user hand-maintains them, DoFlow adds
+// its hooks, and third-party tools (other installers, command proxies) add their own entries.
+// That makes
+// whole-file SHA-256 ownership — correct for copy-tree assets DoFlow owns outright — the wrong
+// model here. It can only ever hold on a machine DoFlow provisioned from empty, so on any real
+// machine a first install saw "target != source" and refused, aborting the entire lifecycle
+// before a single file landed.
+//
+// These helpers give the settings renderer the same posture marker-merge already gives
+// CLAUDE.md: DoFlow guarantees ITS keys are present and correct, and treats everything else in
+// the file as none of its business — preserved on write, ignored on verify, left behind on
+// remove.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../helper/settings-merge.ts')` keeps working while the tree is still `.js`.
+
+interface HookCommand { command?: unknown }
+interface HookEntry { matcher?: unknown; hooks?: HookCommand[] }
+type Settings = Record<string, any>;
+
+/** A hook entry's identity is its (matcher, commands) pair — NOT the commands alone. One script is
+ * legitimately registered under several matchers for the same event (post-edit-lint.sh runs on
+ * both `Edit` and `Write`), so comparing commands only makes those entries indistinguishable and
+ * silently collapses them to one during a merge. Position is not usable: it is not stable across
+ * a re-render. */
+function hookCommands(entry: HookEntry | null | undefined): string[] {
+  return (entry?.hooks || []).map((hook) => hook?.command).filter((command): command is string => typeof command === 'string');
+}
+
+function sameHookEntry(a: HookEntry | null | undefined, b: HookEntry | null | undefined): boolean {
+  if ((a?.matcher ?? null) !== (b?.matcher ?? null)) return false;
+  const left = hookCommands(a);
+  const right = hookCommands(b);
+  return left.length === right.length && left.every((command, index) => command === right[index]);
+}
+
+function isPlainObject(value: any): value is Record<string, any> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Union of managed hook entries into whatever is already registered for an event. Foreign
+ * entries keep their relative order and stay first, so a third-party guard that was already
+ * intercepting a tool keeps intercepting it. */
+function mergeHookEvent(existing: HookEntry[] | undefined, managed: HookEntry[] | undefined): HookEntry[] {
+  const result = Array.isArray(existing) ? existing.slice() : [];
+  for (const entry of managed || []) {
+    if (!result.some((present) => sameHookEntry(present, entry))) result.push(entry);
+  }
+  return result;
+}
+
+function mergeHooks(existing: any, managed: any): Record<string, HookEntry[]> {
+  const result = isPlainObject(existing) ? { ...existing } : {};
+  for (const [event, entries] of Object.entries<any>(managed || {})) {
+    result[event] = mergeHookEvent(result[event], entries);
+  }
+  return result;
+}
+
+/** Merge DoFlow's managed settings into an existing file.
+ *
+ * Precedence is deliberate and asymmetric:
+ *   - `hooks` — managed entries are ADDED (union). DoFlow's guardrails must actually be present,
+ *     and foreign entries must survive.
+ *   - everything else — the EXISTING value wins. DoFlow ships opinionated defaults (`model`,
+ *     `permissions`, `outputStyle`), and silently overriding a user's explicit choice during an
+ *     install is exactly the surprise this module exists to prevent. Managed keys the file does
+ *     not have yet are still added, so a fresh install is unchanged.
+ */
+function mergeSettings(existing: any, managed: any): Settings {
+  if (!isPlainObject(existing)) return managed;
+  const result: Settings = { ...existing };
+  for (const [key, value] of Object.entries<any>(managed || {})) {
+    if (key === 'hooks') { result.hooks = mergeHooks(existing.hooks, value); continue; }
+    if (!Object.hasOwn(result, key)) { result[key] = value; continue; }
+    if (isPlainObject(result[key]) && isPlainObject(value)) result[key] = mergeSettings(result[key], value);
+    // else: existing scalar/array wins — user intent is preserved.
+  }
+  return result;
+}
+
+/** Verification predicate replacing byte-equality: DoFlow's own keys must be present, and every
+ * managed hook entry must still be registered. A foreign key, a user-tuned `model`, or an extra
+ * hook entry are all legitimate and must NOT read as drift. */
+function settingsContains(current: any, managed: any): boolean {
+  if (!isPlainObject(current)) return false;
+  for (const [key, value] of Object.entries<any>(managed || {})) {
+    if (key === 'hooks') {
+      for (const [event, entries] of Object.entries<any>(value || {})) {
+        const present = current.hooks?.[event];
+        if (!Array.isArray(present)) return false;
+        for (const entry of entries || []) {
+          if (!present.some((candidate: HookEntry) => sameHookEntry(candidate, entry))) return false;
+        }
+      }
+      continue;
+    }
+    if (!Object.hasOwn(current, key)) return false;
+    if (isPlainObject(value) && isPlainObject(current[key]) && !settingsContains(current[key], value)) return false;
+  }
+  return true;
+}
+
+/** Remove DoFlow's hook entries and leave everything else standing. `doflow remove` previously
+ * rmSync'd the whole file, which on a shared settings.json would delete the user's entire
+ * own configuration along with DoFlow's contribution. Returns null only when nothing
+ * meaningful remains, letting the caller delete a file DoFlow genuinely created. */
+function stripManagedSettings(current: any, managed: any): Settings | null {
+  if (!isPlainObject(current)) return null;
+  const result: Settings = { ...current };
+  const managedHooks = managed?.hooks;
+  if (isPlainObject(result.hooks) && isPlainObject(managedHooks)) {
+    const hooks: Record<string, HookEntry[]> = {};
+    for (const [event, entries] of Object.entries<any>(result.hooks)) {
+      const remaining = (entries || []).filter(
+        (entry: HookEntry) => !(managedHooks[event] || []).some((owned: HookEntry) => sameHookEntry(owned, entry)),
+      );
+      if (remaining.length) hooks[event] = remaining;
+    }
+    if (Object.keys(hooks).length) result.hooks = hooks; else delete result.hooks;
+  }
+  // Beyond hooks, drop any key still holding exactly the value DoFlow wrote — we put it there and
+  // nothing has touched it since. A key the user changed no longer matches and is left alone.
+  // Without this, a file DoFlow created outright (keybindings.json, which has no hooks at all)
+  // would survive `remove` fully intact and read as a resource that refused to go away.
+  for (const [key, value] of Object.entries<any>(managed || {})) {
+    if (key === 'hooks') continue;
+    if (Object.hasOwn(result, key) && JSON.stringify(result[key]) === JSON.stringify(value)) delete result[key];
+  }
+  const meaningful = Object.keys(result).filter((key) => !key.startsWith('$'));
+  return meaningful.length ? result : null;
+}
+
+/** True when at least one managed hook entry is still registered. Only hook entries count:
+ * non-hook managed keys are ordinary settings that survive a remove and are indistinguishable
+ * from the user's own, so they cannot signal DoFlow's presence. Lets verification tell "removed"
+ * (none of ours left) apart from "damaged" (some of ours left, some missing). */
+function settingsContainsAny(current: any, managed: any): boolean {
+  if (!isPlainObject(current)) return false;
+  for (const [event, entries] of Object.entries<any>(managed?.hooks || {})) {
+    const present = current.hooks?.[event];
+    if (!Array.isArray(present)) continue;
+    if ((entries || []).some((entry: HookEntry) => present.some((candidate: HookEntry) => sameHookEntry(candidate, entry)))) return true;
+  }
+  return false;
+}
+
+module.exports = { mergeSettings, mergeHooks, settingsContains, settingsContainsAny, stripManagedSettings, sameHookEntry };

package/src/helper/settings-scope.ts

@@ -0,0 +1,33 @@
+'use strict';
+// settings-scope.js — GLOBAL_HOOK_PREFIX/PROJECT_HOOK_PREFIX are the shared constants the Claude
+// adapter's settings-asset renderer (src/adapters/claude/index.ts#settingsContent) uses to rewrite
+// a project-scoped settings.json's hook `command` paths from the global-only `~/.claude/hooks/`
+// form to Claude Code's documented ${CLAUDE_PROJECT_DIR}/.claude/hooks/ placeholder — see
+// https://code.claude.com/docs/en/hooks. chmodHooksExecutable is a defensive final pass: an
+// npm-packaged tarball does not reliably preserve the executable bit on arbitrary files (unlike a
+// git checkout, which usually does), so this unconditionally re-adds +x after hook scripts are
+// deployed, regardless of what bit the source file happened to carry on this machine.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../helper/settings-scope.ts')` keeps working while the tree is still `.js`.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const GLOBAL_HOOK_PREFIX = '~/.claude/hooks/';
+const PROJECT_HOOK_PREFIX = '${CLAUDE_PROJECT_DIR}/.claude/hooks/';
+
+/** Adds ugo+x (relative — preserves existing bits), not an absolute mode — a hook file copied in
+ * at 664/775 must stay that way, only gaining +x. */
+function chmodHooksExecutable(claudeDir: string): void {
+  const hooksDir = path.join(claudeDir, 'hooks');
+  if (!fs.existsSync(hooksDir)) return;
+  for (const f of fs.readdirSync(hooksDir)) {
+    if (!f.endsWith('.sh')) continue;
+    const p = path.join(hooksDir, f);
+    const currentMode = fs.statSync(p).mode & 0o777;
+    fs.chmodSync(p, currentMode | 0o111);
+  }
+}
+
+module.exports = { GLOBAL_HOOK_PREFIX, PROJECT_HOOK_PREFIX, chmodHooksExecutable };