@bookedsolid/rea 0.1.0 → 0.2.1

package/dist/cli/install/claude-md.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Write or update a managed fragment inside the consumer's `CLAUDE.md`.
+ *
+ * The fragment is delimited by HTML-style comment markers so it's invisible in
+ * rendered Markdown but machine-parseable:
+ *
+ *   <!-- rea:managed:start v=1 -->
+ *   ...
+ *   <!-- rea:managed:end -->
+ *
+ * On first install the block is appended at the end of `CLAUDE.md` (or the file
+ * is created). On subsequent runs, everything between the markers is replaced.
+ * Content outside the markers is NEVER touched — the consumer owns the rest
+ * of `CLAUDE.md`.
+ *
+ * Fragment content:
+ *   - Policy path
+ *   - Active profile
+ *   - Autonomy level and ceiling
+ *   - Blocked-paths count (not the paths themselves — those are in the YAML)
+ *   - A reminder that `/codex-review` is required on protected-path changes
+ */
+export interface ClaudeMdFragmentInput {
+    policyPath: string;
+    profile: string;
+    autonomyLevel: string;
+    maxAutonomyLevel: string;
+    blockedPathsCount: number;
+    blockAiAttribution: boolean;
+}
+export declare const START_MARKER = "<!-- rea:managed:start v=1 -->";
+export declare const END_MARKER = "<!-- rea:managed:end -->";
+/**
+ * Return the current managed-fragment substring (from START_MARKER to
+ * END_MARKER inclusive) if present in `content`, else `null`. Shared with
+ * `rea upgrade` so both sides use identical boundary semantics.
+ */
+export declare function extractFragment(content: string): string | null;
+export declare function buildFragment(input: ClaudeMdFragmentInput): string;
+/**
+ * Write or replace the managed fragment inside `${targetDir}/CLAUDE.md`.
+ * Returns the absolute path written and whether the file existed before.
+ */
+export declare function writeClaudeMdFragment(targetDir: string, input: ClaudeMdFragmentInput): Promise<{
+    path: string;
+    existed: boolean;
+    replaced: boolean;
+}>;

package/dist/cli/install/claude-md.js

@@ -0,0 +1,93 @@
+/**
+ * Write or update a managed fragment inside the consumer's `CLAUDE.md`.
+ *
+ * The fragment is delimited by HTML-style comment markers so it's invisible in
+ * rendered Markdown but machine-parseable:
+ *
+ *   <!-- rea:managed:start v=1 -->
+ *   ...
+ *   <!-- rea:managed:end -->
+ *
+ * On first install the block is appended at the end of `CLAUDE.md` (or the file
+ * is created). On subsequent runs, everything between the markers is replaced.
+ * Content outside the markers is NEVER touched — the consumer owns the rest
+ * of `CLAUDE.md`.
+ *
+ * Fragment content:
+ *   - Policy path
+ *   - Active profile
+ *   - Autonomy level and ceiling
+ *   - Blocked-paths count (not the paths themselves — those are in the YAML)
+ *   - A reminder that `/codex-review` is required on protected-path changes
+ */
+import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+export const START_MARKER = '<!-- rea:managed:start v=1 -->';
+export const END_MARKER = '<!-- rea:managed:end -->';
+/**
+ * Return the current managed-fragment substring (from START_MARKER to
+ * END_MARKER inclusive) if present in `content`, else `null`. Shared with
+ * `rea upgrade` so both sides use identical boundary semantics.
+ */
+export function extractFragment(content) {
+    const s = content.indexOf(START_MARKER);
+    const e = content.indexOf(END_MARKER);
+    if (s === -1 || e === -1 || e < s)
+        return null;
+    return content.slice(s, e + END_MARKER.length);
+}
+export function buildFragment(input) {
+    const lines = [
+        START_MARKER,
+        '',
+        '## REA Governance (managed — do not edit this block)',
+        '',
+        `- **Policy**: \`${input.policyPath}\` — profile \`${input.profile}\``,
+        `- **Autonomy**: \`${input.autonomyLevel}\` (ceiling \`${input.maxAutonomyLevel}\`)`,
+        `- **Blocked paths**: ${input.blockedPathsCount} entries — see the policy file`,
+        `- **block_ai_attribution**: \`${input.blockAiAttribution}\` (enforced by commit-msg hook)`,
+        '',
+        'Protected-path changes (`src/gateway/middleware/`, `hooks/`, `src/policy/`,',
+        '`.github/workflows/`) require a `/codex-review` audit entry before push.',
+        '',
+        'Run `rea doctor` to verify the install. Run `rea check` to inspect state.',
+        '',
+        END_MARKER,
+    ];
+    return lines.join('\n');
+}
+/**
+ * Write or replace the managed fragment inside `${targetDir}/CLAUDE.md`.
+ * Returns the absolute path written and whether the file existed before.
+ */
+export async function writeClaudeMdFragment(targetDir, input) {
+    const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
+    const fragment = buildFragment(input);
+    if (!fs.existsSync(claudeMdPath)) {
+        const seed = [
+            `# CLAUDE.md — ${path.basename(targetDir)}`,
+            '',
+            'Project-level instructions for AI agents in this repository.',
+            '',
+            fragment,
+            '',
+        ].join('\n');
+        await fsPromises.writeFile(claudeMdPath, seed, 'utf8');
+        return { path: claudeMdPath, existed: false, replaced: false };
+    }
+    const existing = await fsPromises.readFile(claudeMdPath, 'utf8');
+    const startIdx = existing.indexOf(START_MARKER);
+    const endIdx = existing.indexOf(END_MARKER);
+    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+        // No markers — append the fragment to the end, preserving existing content.
+        const trailer = existing.endsWith('\n') ? '' : '\n';
+        const next = `${existing}${trailer}\n${fragment}\n`;
+        await fsPromises.writeFile(claudeMdPath, next, 'utf8');
+        return { path: claudeMdPath, existed: true, replaced: false };
+    }
+    const endLineIdx = endIdx + END_MARKER.length;
+    const next = existing.slice(0, startIdx) + fragment + existing.slice(endLineIdx);
+    await fsPromises.writeFile(claudeMdPath, next, 'utf8');
+    return { path: claudeMdPath, existed: true, replaced: true };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Install the commit-msg hook that enforces `block_ai_attribution`.
+ *
+ * Strategy: belt-and-suspenders.
+ *
+ *   1. Always write `.git/hooks/commit-msg` (the "belt") — every git commit
+ *      in this repo will hit it, no matter what frontend the consumer uses.
+ *   2. If `.husky/` exists (husky is installed), also write `.husky/commit-msg`
+ *      (the "suspenders") — this is what husky-based projects see in their
+ *      source tree and will share with collaborators.
+ *
+ * The hook itself is sourced from the packaged `.husky/commit-msg` so there is
+ * exactly one version of truth. `package.json#files[]` includes `.husky/` so
+ * the file ships to npm.
+ *
+ * The hook is a no-op when `block_ai_attribution` is not set to `true` in
+ * `.rea/policy.yaml`, so it is safe to install unconditionally — see the
+ * header of `.husky/commit-msg` for the opt-in check.
+ */
+export interface CommitMsgInstallResult {
+    gitHook?: string;
+    huskyHook?: string;
+    warnings: string[];
+}
+/**
+ * Install the commit-msg hook into the consumer project at `targetDir`.
+ * Requires `targetDir/.git` to exist (not a bare clone). The husky copy is
+ * best-effort and only runs if `.husky/` is already a directory.
+ */
+export declare function installCommitMsgHook(targetDir: string): Promise<CommitMsgInstallResult>;

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

@@ -0,0 +1,102 @@
+/**
+ * Install the commit-msg hook that enforces `block_ai_attribution`.
+ *
+ * Strategy: belt-and-suspenders.
+ *
+ *   1. Always write `.git/hooks/commit-msg` (the "belt") — every git commit
+ *      in this repo will hit it, no matter what frontend the consumer uses.
+ *   2. If `.husky/` exists (husky is installed), also write `.husky/commit-msg`
+ *      (the "suspenders") — this is what husky-based projects see in their
+ *      source tree and will share with collaborators.
+ *
+ * The hook itself is sourced from the packaged `.husky/commit-msg` so there is
+ * exactly one version of truth. `package.json#files[]` includes `.husky/` so
+ * the file ships to npm.
+ *
+ * The hook is a no-op when `block_ai_attribution` is not set to `true` in
+ * `.rea/policy.yaml`, so it is safe to install unconditionally — see the
+ * header of `.husky/commit-msg` for the opt-in check.
+ */
+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';
+const execFileAsync = promisify(execFile);
+/**
+ * Read `core.hooksPath` via `git config --get`. This is the only correct way
+ * to consult git config: regex-matching `.git/config` (finding #9) is
+ * section-blind and matches `hooksPath = …` inside `[worktree]`, `[alias]`,
+ * `[includeIf]`, or conditional include files — any of which would aim the
+ * installer at the wrong directory.
+ *
+ * We use `execFile` (not `exec`) so there is no shell interpolation of the
+ * target directory. Returns `null` if the key is unset (git exits non-zero),
+ * or if git itself isn't on PATH.
+ */
+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 {
+        // Non-zero exit (key not set) or git missing from PATH. Either way we fall
+        // back to the default `.git/hooks/`.
+        return null;
+    }
+}
+function sourceHookPath() {
+    return path.join(PKG_ROOT, '.husky', '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 commit-msg hook into the consumer project at `targetDir`.
+ * Requires `targetDir/.git` to exist (not a bare clone). The husky copy is
+ * best-effort and only runs if `.husky/` is already a directory.
+ */
+export async function installCommitMsgHook(targetDir) {
+    const result = { warnings: [] };
+    const src = sourceHookPath();
+    if (!fs.existsSync(src)) {
+        result.warnings.push(`packaged 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 commit-msg install (not a git repo?)');
+        return result;
+    }
+    // Determine the true hooks directory; respect core.hooksPath when set.
+    // We defer to `git config --get` rather than regex-matching `.git/config`
+    // so that section-scoped keys (`[worktree]`, `[alias]`, `[includeIf]`,
+    // `[include]` files) are resolved the way git itself resolves them. Any
+    // other approach (finding #9) is section-blind.
+    let hooksDir = path.join(gitDir, 'hooks');
+    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 to ${hooksDir}`);
+    }
+    const gitHookPath = path.join(hooksDir, 'commit-msg');
+    await writeExecutable(src, gitHookPath);
+    result.gitHook = gitHookPath;
+    const huskyDir = path.join(targetDir, '.husky');
+    if (fs.existsSync(huskyDir)) {
+        const huskyHookPath = path.join(huskyDir, 'commit-msg');
+        await writeExecutable(src, huskyHookPath);
+        result.huskyHook = huskyHookPath;
+    }
+    else {
+        // Not a warning — husky is optional. Just note the state for logging.
+        warn('no .husky/ directory — skipped husky commit-msg copy (git-hooks copy is sufficient)');
+    }
+    return result;
+}

package/dist/cli/install/copy.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Copy hooks, commands, and agents from the installed package into a consumer's
+ * `.claude/` directory. This is the core of what makes `rea init` a real
+ * installer rather than a policy-file writer.
+ *
+ * Conflict policy:
+ *
+ *   - `--force` (boolean): overwrite unconditionally. Reserved for power users
+ *     who have intentionally modified their local `.claude/` and know they want
+ *     fresh-from-package versions back.
+ *   - `--yes` (boolean): non-interactive. Skips existing files — NEVER silently
+ *     replaces a consumer-modified hook. This is the safe default for CI.
+ *   - Default (interactive): prompts per conflict via `@clack/prompts`.
+ *
+ * Hook scripts are chmod'd to 0o755 so the shell hooks the harness fires can
+ * actually execute on a fresh clone.
+ *
+ * ## Symlink safety (finding #5)
+ *
+ * A prior malicious PR could leave a symlink at a destination path (e.g.
+ * `.claude/hooks/secret-scanner.sh` → `/etc/shadow`). Node's `copyFile` and
+ * `chmod` follow symlinks, so a subsequent `rea init --force` would overwrite
+ * the link target and chmod it 0o755. We defend in multiple layers:
+ *
+ *   1. Resolve the install root with `realpath` once per run.
+ *   2. Before any write, `lstat` the destination and REFUSE (hard error, named
+ *      file + link target) if it is a symlink. The presence of a symlink is a
+ *      signal worth surfacing to the operator — we do not silently rewrite it.
+ *   3. For every destination path, resolve it and assert containment within the
+ *      resolved root. Anything escaping the root is refused.
+ *
+ * On overwrite we use `openSync(O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW)` and
+ * write the bytes ourselves — `O_EXCL` makes the create race-safe, and
+ * `O_NOFOLLOW` refuses any symlink that sneaks in between the lstat and the
+ * write. On fresh creates we use the same flags for the same reason.
+ *
+ * ## Parent-directory TOCTOU (finding R2-4)
+ *
+ * `assertSafeDirectory` validates a path *string*. A concurrent attacker with
+ * write access under the install tree could swap `.claude/hooks` for a symlink
+ * in the window between validation and the subsequent `copyFile`/`unlink`. To
+ * close this window:
+ *
+ *   1. After validating the install root, snapshot the realpath of every
+ *      ancestor directory between the destination and the root.
+ *   2. Immediately before every mutation (`unlink`, then the file write), we
+ *      re-realpath the same ancestors and refuse if any changed. This closes
+ *      the practical exploit window to sub-millisecond.
+ *   3. `O_NOFOLLOW` on the write call catches a symlink that slips in at the
+ *      leaf between the re-check and the `open` syscall.
+ *
+ * Residual risk: a race that wins between the re-realpath loop and the `open`
+ * syscall on the leaf still exists, but the `O_NOFOLLOW | O_EXCL` open will
+ * refuse any symlink that lands in that micro-window. Fully closing the
+ * ancestor-swap race would require dirfd-relative APIs (`openat`) which Node's
+ * core `fs` module does not expose. Documented; not a code-execution primitive.
+ *
+ * ## Ancestor baseline integrity (finding R3-1)
+ *
+ * `O_NOFOLLOW` only protects the leaf component of the open syscall — an
+ * attacker who swaps an intermediate directory for a symlink pointing outside
+ * the install root between `assertSafeDirectory` and the per-file `copyOne`
+ * call would otherwise get the snapshot to record the attacker's state as
+ * baseline. `verifyAncestorsUnchanged` would then pass (the symlink is
+ * stable) and the write would land wherever the symlink points.
+ *
+ * `snapshotAncestors` closes that primitive by (a) refusing any ancestor that
+ * is itself a symlink (`lstat`), (b) re-asserting containment via `realpath`
+ * at every level, and (c) requiring the walk to terminate at `resolvedRoot`.
+ * Those checks run before any write-side syscall; an escape attempt surfaces
+ * as `UnsafeInstallPathError` with `kind: 'symlink'` or `'escape'`.
+ */
+export interface CopyOptions {
+    force: boolean;
+    yes: boolean;
+}
+export interface CopyResult {
+    copied: string[];
+    skipped: string[];
+    overwritten: string[];
+}
+/**
+ * Thrown when a destination path is a symlink, escapes the install root, or a
+ * previously-validated ancestor directory changed shape between validation and
+ * the write (finding R2-4). Kept as a named class so callers (and tests) can
+ * match the shape without scraping the message.
+ */
+export declare class UnsafeInstallPathError extends Error {
+    readonly kind: 'symlink' | 'escape' | 'ancestor-changed';
+    readonly targetPath: string;
+    readonly linkTarget?: string;
+    constructor(kind: 'symlink' | 'escape' | 'ancestor-changed', targetPath: string, linkTarget: string | undefined, message: string);
+}
+/**
+ * Snapshot the realpath of every ancestor directory between `dstPath` and
+ * `resolvedRoot` (inclusive of the root, exclusive of the leaf). The resulting
+ * map — `absolute ancestor path → realpath at snapshot time` — is later
+ * re-validated by {@link verifyAncestorsUnchanged} immediately before each
+ * mutation. If any entry has changed, the tree was swapped and we refuse.
+ *
+ * We deliberately skip the leaf: the leaf's safety is handled by the
+ * `lstat` check in `assertSafeDestination` and by `O_NOFOLLOW` on the open.
+ *
+ * ## Defense against ancestor escape (finding R3-1)
+ *
+ * The snapshot itself must not be allowed to record an attacker-controlled
+ * baseline. Without the checks below, an attacker who swaps an intermediate
+ * directory for a symlink to `/tmp/decoy` between `assertSafeDirectory` and
+ * `copyOne` could get the snapshot to record `.claude/hooks → /tmp/decoy` as
+ * the trusted state — {@link verifyAncestorsUnchanged} would then pass, and
+ * `writeFileExclusiveNoFollow` would land the payload outside the install
+ * root (O_NOFOLLOW only guards the leaf, not ancestor components).
+ *
+ * To close that primitive, for every ancestor we:
+ *
+ *   1. `lstat` the component. If it is a symbolic link, refuse — ancestor
+ *      symlinks inside the install tree are never legitimate for us to walk
+ *      through, regardless of where they point.
+ *   2. `realpath` the component and assert containment within `resolvedRoot`.
+ *      Anything pointing outside is an attempted escape.
+ *   3. Require the walk to terminate at `resolvedRoot`. If the cursor reaches
+ *      the filesystem root without passing through `resolvedRoot`, the
+ *      destination was never under the install root to begin with — that
+ *      means `assertSafeDestination` was bypassed and we refuse loudly.
+ */
+declare function snapshotAncestors(resolvedRoot: string, dstPath: string): Promise<Map<string, string>>;
+/**
+ * Re-realpath every ancestor captured in `snapshot` and throw
+ * {@link UnsafeInstallPathError} if any resolution has changed (an intermediate
+ * directory was replaced with a symlink, renamed, etc.) or disappeared.
+ */
+declare function verifyAncestorsUnchanged(snapshot: Map<string, string>): Promise<void>;
+/**
+ * Write `srcPath`'s bytes to `dstPath` using `openSync(O_WRONLY | O_CREAT |
+ * O_EXCL | O_NOFOLLOW)`. This is the race-safe replacement for `copyFile` —
+ *
+ *   - `O_EXCL`: the open fails with EEXIST if anything appears at the leaf
+ *     between our pre-check and this call, including a symlink or regular file.
+ *   - `O_NOFOLLOW`: the open fails with ELOOP if the leaf itself is a symlink
+ *     that somehow bypassed EXCL (belt-and-suspenders; on most platforms EXCL
+ *     alone is sufficient).
+ *
+ * Reads the source via the fs/promises API so we inherit standard error shapes.
+ * Source-side read follows symlinks, which is fine: `srcPath` is inside PKG_ROOT
+ * and the source tree is trusted.
+ */
+declare function writeFileExclusiveNoFollow(srcPath: string, dstPath: string): Promise<void>;
+/**
+ * Copy hooks/commands/agents from the package root into `${targetDir}/.claude/`.
+ *
+ * Caller is responsible for ensuring `targetDir` is a real directory — this
+ * function creates `.claude/` and the three subdirectories if missing.
+ *
+ * Throws {@link UnsafeInstallPathError} if any destination is a symlink or
+ * would escape the resolved install root. The caller should surface this as a
+ * named failure and exit non-zero; do not wrap-and-swallow.
+ */
+export declare function copyArtifacts(targetDir: string, options: CopyOptions): Promise<CopyResult>;
+/**
+ * Internal helpers exposed for unit tests only. Not part of the public API —
+ * do not import from outside `./copy.test.ts`. Grouped under `__internal` so
+ * consumers can grep and stay away.
+ */
+export declare const __internal: {
+    readonly snapshotAncestors: typeof snapshotAncestors;
+    readonly verifyAncestorsUnchanged: typeof verifyAncestorsUnchanged;
+    readonly writeFileExclusiveNoFollow: typeof writeFileExclusiveNoFollow;
+};
+export {};