@bookedsolid/rea 0.28.2 → 0.30.0

package/dist/cli/install/prepare-commit-msg.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Install the husky `prepare-commit-msg` hook that drives the 0.30.0
+ * attribution augmenter.
+ *
+ * The hook itself is a stable POSIX-sh body sourced from the package's
+ * own `.husky/prepare-commit-msg`. `rea init` and `rea upgrade` copy it
+ * into `.husky/` and (when `core.hooksPath` is not configured at
+ * `.husky`) `.git/hooks/` as the belt-and-suspenders pair — mirroring
+ * the `installCommitMsgHook` strategy in `commit-msg.ts`.
+ *
+ * Foreign-hook conflict pattern: the 0.13.2 prepush prior art applies.
+ * If a foreign `prepare-commit-msg` exists (no rea marker, not the husky
+ * 9 indirection stub), we REFUSE to overwrite, surface the conflict via
+ * `rea doctor`, and recommend the `.husky/prepare-commit-msg.d/<NN>-name`
+ * extension-fragment migration path (TODO: wire fragment chaining if
+ * consumers demand it; not in 0.30.0 scope).
+ *
+ * Idempotency: the canonical body carries the `# rea:prepare-commit-msg v1`
+ * marker on line 2 and `# rea:augment-body-v1` on line 3. Re-running rea
+ * init / upgrade refreshes the file in-place whenever the marker matches;
+ * foreign hooks are left alone.
+ */
+/**
+ * Marker baked into every rea-installed prepare-commit-msg hook.
+ * Anchored on line 2 (immediately after the shebang) for classification.
+ * Bump the version suffix whenever the body semantics change so
+ * upgrades migrate cleanly.
+ *
+ * v1 — 0.30.0: first version of the augmenter hook.
+ */
+export declare const PREPARE_COMMIT_MSG_MARKER = "# rea:prepare-commit-msg v1";
+/**
+ * Body marker anchored on line 3. A foreign hook that carries the
+ * header marker as a comment but has an empty body (stubbed by a
+ * consumer) will NOT be classified as rea-managed because the body
+ * marker won't be on line 3. Both markers together close the
+ * classification question.
+ */
+export declare const PREPARE_COMMIT_MSG_BODY_MARKER = "# rea:augment-body-v1";
+export type PrepareCommitMsgClassification = {
+    kind: 'absent';
+} | {
+    kind: 'rea-managed';
+    version: string;
+} | {
+    kind: 'foreign';
+    reason: string;
+};
+/**
+ * Inspect `hookPath` and decide whether it is rea-authored or foreign.
+ * Strict: BOTH markers must appear on lines 2 + 3 in order. Substring
+ * matches deliberately rejected so a comment quoting the marker doesn't
+ * fool the classifier.
+ */
+export declare function classifyPrepareCommitMsgHook(hookPath: string): Promise<PrepareCommitMsgClassification>;
+export interface PrepareCommitMsgInstallResult {
+    gitHook?: string;
+    huskyHook?: string;
+    warnings: string[];
+    /**
+     * When the install is a refresh of an existing rea-managed body, this
+     * is true. Useful for upgrade messaging.
+     */
+    refreshed?: boolean;
+    /**
+     * When the install was skipped because a foreign hook is present.
+     * Surfaced separately so `rea doctor` can render the migration path.
+     */
+    skippedForeign?: boolean;
+}
+/**
+ * Install the prepare-commit-msg hook into the consumer project at
+ * `targetDir`. Refuses to stomp foreign hooks; refreshes rea-managed
+ * hooks in place. Best-effort: a missing `.husky/` directory simply
+ * skips the husky copy (git-hooks copy is sufficient for vanilla git).
+ *
+ * Foreign-hook conflict (the 0.13.2 pre-push prior art): we never
+ * overwrite a non-rea body. The caller surfaces the conflict to the
+ * operator; `rea doctor` flags the gap so the operator can decide
+ * whether to relocate their existing hook into a fragment, replace it
+ * with rea's body, or set `attribution.co_author.enabled: false`.
+ */
+export declare function installPrepareCommitMsgHook(targetDir: string): Promise<PrepareCommitMsgInstallResult>;

package/dist/cli/install/prepare-commit-msg.js

@@ -0,0 +1,208 @@
+/**
+ * Install the husky `prepare-commit-msg` hook that drives the 0.30.0
+ * attribution augmenter.
+ *
+ * The hook itself is a stable POSIX-sh body sourced from the package's
+ * own `.husky/prepare-commit-msg`. `rea init` and `rea upgrade` copy it
+ * into `.husky/` and (when `core.hooksPath` is not configured at
+ * `.husky`) `.git/hooks/` as the belt-and-suspenders pair — mirroring
+ * the `installCommitMsgHook` strategy in `commit-msg.ts`.
+ *
+ * Foreign-hook conflict pattern: the 0.13.2 prepush prior art applies.
+ * If a foreign `prepare-commit-msg` exists (no rea marker, not the husky
+ * 9 indirection stub), we REFUSE to overwrite, surface the conflict via
+ * `rea doctor`, and recommend the `.husky/prepare-commit-msg.d/<NN>-name`
+ * extension-fragment migration path (TODO: wire fragment chaining if
+ * consumers demand it; not in 0.30.0 scope).
+ *
+ * Idempotency: the canonical body carries the `# rea:prepare-commit-msg v1`
+ * marker on line 2 and `# rea:augment-body-v1` on line 3. Re-running rea
+ * init / upgrade refreshes the file in-place whenever the marker matches;
+ * foreign hooks are left alone.
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { PKG_ROOT, warn } from '../utils.js';
+import { isHusky9Stub, resolveHusky9StubTarget } from './pre-push.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Marker baked into every rea-installed prepare-commit-msg hook.
+ * Anchored on line 2 (immediately after the shebang) for classification.
+ * Bump the version suffix whenever the body semantics change so
+ * upgrades migrate cleanly.
+ *
+ * v1 — 0.30.0: first version of the augmenter hook.
+ */
+export const PREPARE_COMMIT_MSG_MARKER = '# rea:prepare-commit-msg v1';
+/**
+ * Body marker anchored on line 3. A foreign hook that carries the
+ * header marker as a comment but has an empty body (stubbed by a
+ * consumer) will NOT be classified as rea-managed because the body
+ * marker won't be on line 3. Both markers together close the
+ * classification question.
+ */
+export const PREPARE_COMMIT_MSG_BODY_MARKER = '# rea:augment-body-v1';
+/**
+ * Inspect `hookPath` and decide whether it is rea-authored or foreign.
+ * Strict: BOTH markers must appear on lines 2 + 3 in order. Substring
+ * matches deliberately rejected so a comment quoting the marker doesn't
+ * fool the classifier.
+ */
+export async function classifyPrepareCommitMsgHook(hookPath) {
+    let stat;
+    try {
+        stat = await fsPromises.lstat(hookPath);
+    }
+    catch {
+        return { kind: 'absent' };
+    }
+    if (stat.isDirectory())
+        return { kind: 'foreign', reason: 'is-directory' };
+    if (stat.isSymbolicLink())
+        return { kind: 'foreign', reason: 'is-symlink' };
+    if (!stat.isFile())
+        return { kind: 'foreign', reason: 'not-regular-file' };
+    let content;
+    try {
+        content = await fsPromises.readFile(hookPath, 'utf8');
+    }
+    catch (e) {
+        return {
+            kind: 'foreign',
+            reason: `read-error: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    // Codex round 2 P2: Husky 9 layout (`core.hooksPath=.husky/_`) auto-
+    // generates a stub like `#!/usr/bin/env sh\n. "${0%/*}/h"` at the
+    // active hooks path. Git dispatches through that stub to `.husky/
+    // prepare-commit-msg` (the canonical body, which IS rea-managed).
+    // Treat the stub as a managed pointer — follow the indirection and
+    // re-classify against the canonical target. Same pattern as
+    // pre-push.ts's husky 9 handling.
+    if (isHusky9Stub(content)) {
+        const target = resolveHusky9StubTarget(hookPath);
+        if (target !== null && target !== hookPath) {
+            return classifyPrepareCommitMsgHook(target);
+        }
+    }
+    if (!content.startsWith('#!/bin/sh\n')) {
+        return { kind: 'foreign', reason: 'no-marker' };
+    }
+    const lines = content.split('\n');
+    if (lines[1] !== PREPARE_COMMIT_MSG_MARKER || lines[2] !== PREPARE_COMMIT_MSG_BODY_MARKER) {
+        return { kind: 'foreign', reason: 'no-marker' };
+    }
+    return { kind: 'rea-managed', version: 'v1' };
+}
+/**
+ * Read `core.hooksPath` via `git config --get`. Returns `null` when the
+ * key is unset. Same execFile (not exec) discipline as the other
+ * installers so the target directory cannot interpolate through a
+ * shell.
+ */
+async function readHooksPathFromGit(targetDir) {
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', targetDir, 'config', '--get', 'core.hooksPath'], { encoding: 'utf8' });
+        const trimmed = stdout.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sourceHookPath() {
+    return path.join(PKG_ROOT, '.husky', 'prepare-commit-msg');
+}
+async function writeExecutable(src, dst) {
+    await fsPromises.mkdir(path.dirname(dst), { recursive: true });
+    await fsPromises.copyFile(src, dst);
+    await fsPromises.chmod(dst, 0o755);
+}
+/**
+ * Install the prepare-commit-msg hook into the consumer project at
+ * `targetDir`. Refuses to stomp foreign hooks; refreshes rea-managed
+ * hooks in place. Best-effort: a missing `.husky/` directory simply
+ * skips the husky copy (git-hooks copy is sufficient for vanilla git).
+ *
+ * Foreign-hook conflict (the 0.13.2 pre-push prior art): we never
+ * overwrite a non-rea body. The caller surfaces the conflict to the
+ * operator; `rea doctor` flags the gap so the operator can decide
+ * whether to relocate their existing hook into a fragment, replace it
+ * with rea's body, or set `attribution.co_author.enabled: false`.
+ */
+export async function installPrepareCommitMsgHook(targetDir) {
+    const result = { warnings: [] };
+    const src = sourceHookPath();
+    if (!fs.existsSync(src)) {
+        result.warnings.push(`packaged prepare-commit-msg hook missing at ${src}`);
+        return result;
+    }
+    const gitDir = path.join(targetDir, '.git');
+    if (!fs.existsSync(gitDir)) {
+        result.warnings.push('.git/ not found — skipping prepare-commit-msg install (not a git repo?)');
+        return result;
+    }
+    // Codex round 4 P2: `.git` may be a FILE (linked worktrees, submodules)
+    // rather than a directory. `path.join(targetDir, '.git', 'hooks')` then
+    // points into a non-existent location and the writeExecutable mkdir
+    // throws ENOTDIR. Use `git rev-parse --git-path hooks` to resolve
+    // the actual hooks dir regardless of worktree/submodule indirection.
+    let hooksDir;
+    const configuredHooksPath = await readHooksPathFromGit(targetDir);
+    if (configuredHooksPath !== null) {
+        hooksDir = path.isAbsolute(configuredHooksPath)
+            ? configuredHooksPath
+            : path.join(targetDir, configuredHooksPath);
+        result.warnings.push(`git core.hooksPath is set — installing prepare-commit-msg to ${hooksDir}`);
+    }
+    else {
+        try {
+            const { stdout } = await execFileAsync('git', ['-C', targetDir, 'rev-parse', '--git-path', 'hooks'], { encoding: 'utf8' });
+            const resolved = stdout.trim();
+            hooksDir = path.isAbsolute(resolved) ? resolved : path.join(targetDir, resolved);
+        }
+        catch {
+            hooksDir = path.join(gitDir, 'hooks');
+        }
+    }
+    const gitHookPath = path.join(hooksDir, 'prepare-commit-msg');
+    const gitClassification = await classifyPrepareCommitMsgHook(gitHookPath);
+    if (gitClassification.kind === 'foreign') {
+        result.warnings.push(`foreign prepare-commit-msg at ${gitHookPath} (${gitClassification.reason}) — ` +
+            `leaving alone. Either remove it and re-run rea init, or migrate to a ` +
+            `fragment under .husky/prepare-commit-msg.d/ (not yet supported in 0.30.0).`);
+        result.skippedForeign = true;
+    }
+    else {
+        await writeExecutable(src, gitHookPath);
+        result.gitHook = gitHookPath;
+        if (gitClassification.kind === 'rea-managed') {
+            result.refreshed = true;
+        }
+    }
+    const huskyDir = path.join(targetDir, '.husky');
+    if (fs.existsSync(huskyDir)) {
+        const huskyHookPath = path.join(huskyDir, 'prepare-commit-msg');
+        const huskyClassification = await classifyPrepareCommitMsgHook(huskyHookPath);
+        if (huskyClassification.kind === 'foreign') {
+            result.warnings.push(`foreign .husky/prepare-commit-msg at ${huskyHookPath} ` +
+                `(${huskyClassification.reason}) — leaving alone.`);
+            result.skippedForeign = true;
+        }
+        else {
+            await writeExecutable(src, huskyHookPath);
+            result.huskyHook = huskyHookPath;
+            if (huskyClassification.kind === 'rea-managed' && result.refreshed !== true) {
+                result.refreshed = true;
+            }
+        }
+    }
+    else {
+        warn('no .husky/ directory — skipped husky prepare-commit-msg copy ' +
+            '(git-hooks copy is sufficient)');
+    }
+    return result;
+}

package/dist/cli/install/settings-merge.js

@@ -318,6 +318,26 @@ export function defaultDesiredHooks() {
                 },
             ],
         },
+        {
+            // 0.29.0 delegation-telemetry MVP. The matcher is `Agent|Skill` —
+            // the two delegation tools in current Claude Code. NOT `Task|Skill`:
+            // `TaskCreate`/`TaskList`/`TaskUpdate` are unrelated todo-list tools
+            // and MUST NOT match. The hook is observational; its only effect is
+            // to append a `rea.delegation_signal` audit record. Worst-case
+            // latency budget is 50ms even under audit-chain contention (the
+            // signal is backgrounded and the CLI uses a 2s lock-acquisition
+            // fallback that exits 0 on timeout).
+            event: 'PreToolUse',
+            matcher: 'Agent|Skill',
+            hooks: [
+                {
+                    type: 'command',
+                    command: `${base}/delegation-capture.sh`,
+                    timeout: 5000,
+                    statusMessage: 'Recording delegation signal...',
+                },
+            ],
+        },
         {
             event: 'PreToolUse',
             matcher: 'Write|Edit|MultiEdit|NotebookEdit',

package/dist/cli/upgrade.js

@@ -45,7 +45,9 @@ import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFile
 import { buildFragment, extractFragment } from './install/claude-md.js';
 import { atomicReplaceFile, safeDeleteFile, safeInstallFile, safeReadFile, } from './install/fs-safe.js';
 import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, pruneHookCommands, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
+import { validateSettings } from '../config/settings-schema.js';
 import { ensureReaGitignore } from './install/gitignore.js';
+import { installPrepareCommitMsgHook } from './install/prepare-commit-msg.js';
 import { manifestExists, readManifest, writeManifestAtomic } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
 import { err, getPkgVersion, log, warn } from './utils.js';
@@ -408,6 +410,17 @@ async function upgradeSettings(baseDir, opts) {
     // pointless work. Pruning first means the merge sees a clean baseline.
     const pruned = pruneHookCommands(settings, STALE_HOOK_COMMAND_TOKENS);
     const mergeResult = mergeSettings(pruned.merged, desired);
+    // 0.30.0 Class M — validate the merged result with the non-strict
+    // schema before writing. If the merged output would fail zod parse,
+    // refuse the write and leave the consumer settings untouched. This
+    // matches the 0.21.1 idempotency contract: rea never produces a
+    // broken settings.json — when in doubt, do nothing.
+    const validation = validateSettings(mergeResult.merged);
+    if (!validation.parsed) {
+        throw new Error(`rea upgrade: refusing to write .claude/settings.json because the merged result ` +
+            `fails schema validation. This is a safety guardrail — your existing file ` +
+            `is unchanged. zod errors: ${validation.errors.join('; ')}`);
+    }
     if (opts.dryRun !== true) {
         await writeSettingsAtomic(settingsPath, mergeResult.merged);
     }
@@ -605,6 +618,27 @@ export async function runUpgrade(options = {}) {
             source: 'claude-md',
         });
     }
+    // 0.30.0 — install the prepare-commit-msg augmenter on upgrade too
+    // (codex round 1 P1: consumers upgrading from 0.29.x to 0.30.0 would
+    // not get the new husky hook unless they re-ran `rea init`). The
+    // hook is a no-op when policy.attribution.co_author.enabled !== true,
+    // so installing unconditionally is safe; consumers opt in by editing
+    // .rea/policy.yaml. The installer's marker-classification path
+    // refuses to overwrite foreign hooks — same shape as 0.13.2
+    // pre-push foreign-hook handling.
+    if (!dryRun) {
+        const pcmResult = await installPrepareCommitMsgHook(resolvedRoot);
+        if (pcmResult.skippedForeign) {
+            warn(`  · .husky/prepare-commit-msg (kept; foreign hook detected — see MIGRATING.md)`);
+        }
+        else if (pcmResult.huskyHook ?? pcmResult.gitHook) {
+            const target = pcmResult.huskyHook ?? pcmResult.gitHook;
+            const marker = pcmResult.refreshed ? '~' : '+';
+            console.log(`  ${marker} ${target} (attribution augmenter)`);
+        }
+        for (const w of pcmResult.warnings)
+            warn(w);
+    }
     // BUG-010 — ensure `.gitignore` carries every runtime artifact entry. This
     // backfills older installs that predate the scaffolding in `rea init`. A
     // consumer who upgraded from 0.3.x/0.4.0 was previously seeing