@pugi/cli 0.1.0-beta.3 → 0.1.0-beta.30

package/dist/core/hooks/registry.js

@@ -0,0 +1,213 @@
+/**
+ * Pugi hooks MVP — registry (Leak L12, first pass).
+ *
+ * Reads `<home>/hooks-mvp.json` and validates its shape with Zod. The
+ * file uses the Claude Code-style nested config:
+ *
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [{ "command": "echo session-start" }],
+ *       "PreToolUse":   [{ "matcher": "bash", "command": "echo bash-pre", "blocking": true }]
+ *     }
+ *   }
+ *
+ * Schema constraints:
+ *   - Each hook entry MUST have a `command` (non-empty string).
+ *   - `matcher` is optional. Defaults to `*` (any tool / any payload).
+ *     For tool events, `matcher` is compared against the tool name.
+ *     For non-tool events (SessionStart), `matcher` is ignored.
+ *   - `timeoutMs` is optional. Defaults to 30 000 ms (per task spec).
+ *     Capped at 60 000 ms to prevent operator-defined deadlocks.
+ *   - `blocking` is optional. When true AND the hook exits non-zero,
+ *     the registry surfaces an `anyBlocked: true` outcome so the
+ *     caller can refuse the originating action. Only honoured for
+ *     `PreToolUse` in the MVP — other events log but do not block.
+ *
+ * Failure modes:
+ *   - File missing -> the registry is `empty()`. `list()` returns []
+ *     and `fire()` is a no-op. This matches the Claude Code default
+ *     (hooks are opt-in).
+ *   - File present but invalid JSON / fails schema -> `load()` throws.
+ *     The CLI surface (`pugi hooks doctor`) reports the error
+ *     verbatim so the operator can fix the config.
+ *
+ * Brand voice: ASCII only, no emoji, no em-dashes.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { ALL_HOOK_EVENTS_V2 } from './events.js';
+/** Default per-hook timeout when the operator does not set `timeoutMs`. */
+export const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
+/** Hard upper bound on `timeoutMs`. Prevents config-defined deadlocks. */
+export const MAX_HOOK_TIMEOUT_MS = 60_000;
+const hookEntrySchema = z
+    .object({
+    /**
+     * Tool-name matcher. `*` matches any tool. Plain strings match
+     * exactly (no glob in the MVP — fast-follow widens to glob). Ignored
+     * for non-tool events such as `SessionStart`.
+     */
+    matcher: z.string().min(1).optional(),
+    /** Shell command. Spawned via `/bin/sh -c <command>`. */
+    command: z.string().min(1),
+    /** Per-hook timeout override. Defaults to 30 000 ms. */
+    timeoutMs: z.number().int().positive().max(MAX_HOOK_TIMEOUT_MS).optional(),
+    /**
+     * When true, a non-zero exit code from this hook blocks the
+     * originating action (currently `PreToolUse` only). Other events
+     * log the exit but do not block.
+     */
+    blocking: z.boolean().optional(),
+})
+    .strict();
+const hookEventEnum = z.enum([
+    'SessionStart',
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'Stop',
+    'SubagentStop',
+    'PreCompact',
+    'Notification',
+]);
+const hooksFileSchema = z
+    .object({
+    hooks: z.record(hookEventEnum, z.array(hookEntrySchema)).default({}),
+})
+    .strict();
+/** Default config file location — `~/.pugi/hooks-mvp.json`. */
+export function defaultHooksMvpPath(home) {
+    const root = home ?? process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(root, 'hooks-mvp.json');
+}
+/**
+ * In-memory snapshot of the operator's `hooks-mvp.json`. Construct
+ * via `loadHooksConfig(path)` — `new HooksConfig()` is intentionally
+ * not exported so all production code paths go through the loader.
+ */
+export class HooksConfig {
+    path;
+    entries;
+    constructor(path, entries) {
+        this.path = path;
+        this.entries = entries;
+    }
+    /** Absolute path of the config file this snapshot was loaded from. */
+    configPath() {
+        return this.path;
+    }
+    /** All hooks declared for a given event. Returns [] when none. */
+    list(event) {
+        return this.entries[event] ?? [];
+    }
+    /**
+     * Hooks that match the (event, toolName?) tuple. For tool events
+     * (`PreToolUse`), `matcher` is compared against the tool name with
+     * `*` matching any. For non-tool events, all entries are returned
+     * regardless of `matcher`.
+     */
+    listMatching(event, toolName) {
+        const all = this.list(event);
+        if (!isToolEvent(event))
+            return all;
+        return all.filter((entry) => matchesTool(entry.matcher, toolName));
+    }
+    /** Flat list of (event, entry) pairs across every configured event. */
+    flatten() {
+        const out = [];
+        for (const event of ALL_HOOK_EVENTS_V2) {
+            for (const entry of this.list(event)) {
+                out.push({ event, entry });
+            }
+        }
+        return out;
+    }
+    /** True iff at least one hook is registered for any event. */
+    isEmpty() {
+        return this.flatten().length === 0;
+    }
+    /** A no-op snapshot used when the config file is absent. */
+    static empty(path) {
+        return new HooksConfig(path, {});
+    }
+}
+/**
+ * Load + validate `hooks-mvp.json`. Returns a no-op snapshot when the
+ * file is absent. Throws on invalid JSON or schema violations — the
+ * caller is expected to surface the error to the operator via
+ * `pugi hooks doctor`.
+ *
+ * Contract (non-null invariant): this function ALWAYS returns a
+ * `HooksConfig` instance. It never returns `null` / `undefined`. When
+ * the config file is missing, callers receive `HooksConfig.empty(path)`
+ * — a truthy snapshot for which `isEmpty()` returns `true` and `list()`
+ * returns `[]`. Callers may safely chain `.isEmpty()` without a null
+ * guard. Asserted by `registry-empty.spec.ts`.
+ */
+export function loadHooksConfig(pathOverride) {
+    const path = pathOverride ?? defaultHooksMvpPath();
+    if (!existsSync(path)) {
+        return HooksConfig.empty(path);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`pugi hooks: cannot read ${path}: ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`pugi hooks: ${path} is not valid JSON: ${error.message}`);
+    }
+    const result = hooksFileSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join('.') || '<root>'} ${issue.message}`)
+            .join('; ');
+        throw new Error(`pugi hooks: ${path} failed schema validation: ${issues}`);
+    }
+    // Zod's `z.record(enum, value)` returns `Partial<Record<...>>` shape
+    // — keys that the operator did not include are `undefined`. Coerce
+    // explicitly into the same shape `HooksConfig` expects.
+    const entries = {};
+    for (const event of ALL_HOOK_EVENTS_V2) {
+        const list = result.data.hooks[event];
+        if (list && list.length > 0) {
+            entries[event] = list;
+        }
+    }
+    return new HooksConfig(path, entries);
+}
+/**
+ * `isToolEvent(event)` -> true for events where `matcher` is compared
+ * against the tool name. SessionStart / Stop / Notification / etc. do
+ * not have an associated tool so matcher is ignored.
+ */
+export function isToolEvent(event) {
+    return event === 'PreToolUse' || event === 'PostToolUse';
+}
+/**
+ * Tool-name match grammar for the MVP. Intentionally narrow:
+ *   - matcher missing or `*` -> matches any tool name (and the
+ *     `bash`/`read`/... shape).
+ *   - matcher === toolName    -> exact match.
+ *
+ * Fast-follow widens this to glob via `picomatch` so operators can
+ * write `mcp__*` patterns. Deliberately not pulling in a glob lib for
+ * the MVP — the narrow grammar is enough to land the surface and the
+ * test matrix stays small.
+ */
+export function matchesTool(matcher, toolName) {
+    if (!matcher || matcher === '*')
+        return true;
+    if (!toolName)
+        return false;
+    return matcher === toolName;
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/hooks/runner.js

@@ -0,0 +1,236 @@
+/**
+ * Pugi hooks MVP — runner (Leak L12, first pass).
+ *
+ * Spawns the shell command declared in `hooks-mvp.json`, applies the
+ * timeout watchdog, captures stdout / stderr, and surfaces a
+ * structured result. Two events are wired in the MVP (SessionStart,
+ * PreToolUse); the runner itself is event-agnostic so the fast-follow
+ * PR can attach the remaining 6 events without changing this file.
+ *
+ * Safety properties:
+ *   - 30 s default timeout (per task spec); SIGTERM then SIGKILL with
+ *     a 2 s grace window.
+ *   - 1 MiB output cap per stream — a misbehaving hook (`yes`) cannot
+ *     OOM the parent CLI by buffering unbounded data.
+ *   - Spawn failures are caught + logged; the session never crashes
+ *     because of a missing binary or a syntax error in the command.
+ *   - Hook errors are atomic-appended to `<workspaceRoot>/.pugi/logs/
+ *     hooks.log`. Multiple sessions can write concurrently without
+ *     interleaving because `appendFileSync` opens with O_APPEND.
+ *
+ * Brand voice: ASCII only.
+ */
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { DEFAULT_HOOK_TIMEOUT_MS, isToolEvent, } from './registry.js';
+const HOOK_STREAM_CAP_BYTES = 1024 * 1024;
+const SIGKILL_GRACE_MS = 2_000;
+/**
+ * Fire every matching hook for `event` sequentially. Sequential (not
+ * parallel) is the intentional default — operators frequently chain
+ * `git add` -> `eslint --fix` style hooks that would race otherwise.
+ * Returns a `HookFireOutcome` with the per-invocation results.
+ */
+export async function fireHooks(opts) {
+    const { config, event, payload, toolName, workspaceRoot, env } = opts;
+    const matching = config.listMatching(event, toolName);
+    if (matching.length === 0) {
+        return { event, results: [], anyBlocked: false };
+    }
+    const logger = workspaceRoot ? new HookLogger(workspaceRoot) : undefined;
+    const results = [];
+    let anyBlocked = false;
+    for (const entry of matching) {
+        const timeoutMs = entry.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+        const result = await executeOne(entry.command, payload, timeoutMs, env);
+        // Blocking semantics only honored for PreToolUse in the MVP.
+        // Other events can declare `blocking: true` but the runner just
+        // logs that intent — it does NOT short-circuit. The fast-follow
+        // PR threads PostToolUse + UserPromptSubmit blocking through.
+        const blockable = entry.blocking === true && event === 'PreToolUse';
+        const blocked = blockable && !result.ok;
+        if (blocked) {
+            anyBlocked = true;
+            result.blocked = true;
+            result.blockSentinel = `HOOK_BLOCKED: ${truncate(entry.command, 80)} exited ${result.exitCode}`;
+        }
+        if (logger && !result.ok) {
+            logger.recordFailure(event, entry.command, result);
+        }
+        results.push(result);
+    }
+    return { event, results, anyBlocked };
+}
+async function executeOne(command, payload, timeoutMs, env) {
+    const startedAt = Date.now();
+    return new Promise((resolvePromise) => {
+        const payloadJson = JSON.stringify(payload);
+        const childEnv = {
+            ...(env ?? process.env),
+            PUGI_HOOK_PAYLOAD: payloadJson,
+            PUGI_HOOK_EVENT: payload.event,
+            PUGI_HOOK_SESSION_ID: payload.sessionId,
+        };
+        const child = spawn('/bin/sh', ['-c', command], {
+            env: childEnv,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const state = {
+            stdout: '',
+            stderr: '',
+            killedForTimeout: false,
+            killedForStreamCap: false,
+        };
+        const escalateKill = () => {
+            if (state.sigKillTimer)
+                return;
+            state.sigKillTimer = setTimeout(() => {
+                if (!child.killed)
+                    child.kill('SIGKILL');
+            }, SIGKILL_GRACE_MS);
+            if (state.sigKillTimer.unref)
+                state.sigKillTimer.unref();
+        };
+        const enforceStreamCap = () => {
+            if (state.killedForStreamCap)
+                return;
+            if (state.stdout.length + state.stderr.length <= HOOK_STREAM_CAP_BYTES)
+                return;
+            state.killedForStreamCap = true;
+            child.kill('SIGTERM');
+            escalateKill();
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (state.killedForStreamCap)
+                return;
+            state.stdout += chunk.toString('utf8');
+            enforceStreamCap();
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (state.killedForStreamCap)
+                return;
+            state.stderr += chunk.toString('utf8');
+            enforceStreamCap();
+        });
+        // Best-effort stdin payload — hook scripts that want to read it can
+        // (e.g. `jq .`); scripts that ignore stdin will EPIPE on our write
+        // which we swallow because the env var carries the same data.
+        if (child.stdin) {
+            child.stdin.on('error', () => {
+                // EPIPE is benign — see above.
+            });
+            child.stdin.end(payloadJson);
+        }
+        const timer = setTimeout(() => {
+            state.killedForTimeout = true;
+            child.kill('SIGTERM');
+            escalateKill();
+        }, timeoutMs);
+        if (timer.unref)
+            timer.unref();
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            if (state.sigKillTimer)
+                clearTimeout(state.sigKillTimer);
+            resolvePromise({
+                command: truncate(command, 200),
+                exitCode: -1,
+                stdoutBytes: state.stdout.length,
+                stderrBytes: state.stderr.length,
+                elapsedMs: Date.now() - startedAt,
+                ok: false,
+                blocked: false,
+                timedOut: false,
+                // No blockSentinel here — spawn errors are not the same as
+                // blocking-failure semantics. The caller logs them generically.
+            });
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (state.sigKillTimer)
+                clearTimeout(state.sigKillTimer);
+            let exitCode;
+            if (code !== null) {
+                exitCode = code;
+            }
+            else if (signal === 'SIGTERM') {
+                exitCode = -15;
+            }
+            else if (signal === 'SIGKILL') {
+                exitCode = -9;
+            }
+            else {
+                exitCode = -1;
+            }
+            const ok = exitCode === 0 &&
+                !state.killedForTimeout &&
+                !state.killedForStreamCap;
+            resolvePromise({
+                command: truncate(command, 200),
+                exitCode,
+                stdoutBytes: state.stdout.length,
+                stderrBytes: state.stderr.length,
+                elapsedMs: Date.now() - startedAt,
+                ok,
+                blocked: false,
+                timedOut: state.killedForTimeout,
+            });
+        });
+    });
+}
+/**
+ * Append-only failure log at `<workspaceRoot>/.pugi/logs/hooks.log`.
+ * Each line is a JSON record so log scrapers can `jq` over it.
+ */
+class HookLogger {
+    path;
+    prepared = false;
+    constructor(workspaceRoot) {
+        this.path = resolve(workspaceRoot, '.pugi', 'logs', 'hooks.log');
+    }
+    recordFailure(event, command, result) {
+        this.prepareDir();
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            event,
+            command: truncate(command, 200),
+            exitCode: result.exitCode,
+            timedOut: result.timedOut,
+            elapsedMs: result.elapsedMs,
+            stdoutBytes: result.stdoutBytes,
+            stderrBytes: result.stderrBytes,
+            toolEvent: isToolEvent(event),
+        });
+        try {
+            appendFileSync(this.path, `${line}\n`, 'utf8');
+        }
+        catch {
+            // Logging is best-effort — the session must not crash when the
+            // disk is full or the directory is read-only. The runner has
+            // already returned the result; dropping the log line is the
+            // safe fallback.
+        }
+    }
+    prepareDir() {
+        if (this.prepared)
+            return;
+        const dir = resolve(this.path, '..');
+        if (!existsSync(dir)) {
+            try {
+                mkdirSync(dir, { recursive: true });
+            }
+            catch {
+                // ignored — appendFileSync will surface a fresh error on the
+                // write path, which we also swallow.
+            }
+        }
+        this.prepared = true;
+    }
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 3)}...`;
+}
+//# sourceMappingURL=runner.js.map

package/dist/core/init/scaffold.js

@@ -0,0 +1,195 @@
+/**
+ * Workspace scaffold — extracted from `pugi init` so the bare REPL boot
+ * can call it automatically when the operator launches `pugi` in a
+ * fresh directory (CEO directive 2026-05-26).
+ *
+ * Before this module, `pugi init` was the only path that materialised
+ * `.pugi/` + the canonical config files. Launching the REPL in an empty
+ * directory printed `workspace: (not bound - run /init OR cd into
+ * project)` and instructed the operator to Ctrl+C, run `pugi init`,
+ * relaunch. That round trip is hostile on a first-touch install — CEO
+ * escalated "auto = решение" on 2026-05-26.
+ *
+ * The module is intentionally side-effect free at import time: the
+ * scaffold runs only when `ensureWorkspaceInitialized` is called. The
+ * scaffold is also idempotent — every file write is gated by an
+ * `existsSync` check, so re-running against a workspace that already has
+ * `.pugi/settings.json` (e.g. a manual `pugi init` followed by auto-init
+ * on next REPL launch) is a no-op. The function is safe to call before
+ * any other init logic.
+ *
+ * Two CRITICAL invariants:
+ *
+ *   1. **Atomic per-file.** Every write uses `existsSync` + `writeFileSync`
+ *      against the final path. There is no read-modify-write pattern that
+ *      could lose data on a concurrent `pugi init` race. The one path
+ *      that DOES mutate an existing file — `.gitignore` (append `.pugi/`
+ *      marker) — also gates on the marker being absent before appending,
+ *      so the worst-case race is a duplicate marker line that the next
+ *      run skips.
+ *
+ *   2. **Silent by default.** When `opts.silent` is true (the REPL
+ *      auto-init path) the scaffold writes NOTHING to stderr/stdout.
+ *      The REPL bootstrap runs before Ink mounts, and a stray
+ *      stdout/stderr write at that point would land on the operator's
+ *      shell ABOVE the alt-screen entry — visible until they scroll up,
+ *      and noisy in a CI tail. The explicit `pugi init` path stays
+ *      verbose via the standalone command in `runtime/cli.ts`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { emptyIndex } from '../index-store.js';
+/**
+ * Materialise the canonical `.pugi/` workspace scaffold under `cwd`.
+ * Returns a `{created, dir, createdPaths, skippedPaths}` summary so the
+ * caller can log a one-shot "initialized" line on the first call without
+ * re-checking the filesystem.
+ *
+ * The scaffold mirrors `pugi init` minus the bundled default-skills
+ * install (that is a heavier operation gated on the `--no-defaults`
+ * flag, and the standalone `pugi init` command keeps owning it).
+ *
+ * Idempotent: every file write gates on `existsSync`, so re-running
+ * against an existing workspace is a no-op and returns
+ * `{created: false}` with every path in `skippedPaths`.
+ */
+export function ensureWorkspaceInitialized(cwd, opts = {}) {
+    const silent = opts.silent !== false;
+    const pugiDir = resolve(cwd, '.pugi');
+    // Local trackers so the existing helpers (mkdirIfMissing /
+    // writeJsonIfMissing / writeTextIfMissing) keep their (created, skipped)
+    // signature. The explicit `pugi init` command forwards these straight
+    // into its JSON payload.
+    const created = [];
+    const skipped = [];
+    mkdirIfMissing(pugiDir, created, skipped);
+    mkdirIfMissing(resolve(pugiDir, 'artifacts'), created, skipped);
+    mkdirIfMissing(resolve(pugiDir, 'sessions'), created, skipped);
+    mkdirIfMissing(resolve(pugiDir, 'skills'), created, skipped);
+    writeJsonIfMissing(resolve(pugiDir, 'settings.json'), {
+        schema: 1,
+        workflow: {
+            brand: 'pugi',
+            legacyName: 'codeforge',
+            approvals: 'auto',
+            notAutomatic: [],
+            defaultBaseBranch: 'dev',
+            branchPrefixes: ['feature', 'fix', 'refactor', 'chore'],
+            aiCoAuthorTrailers: false,
+        },
+        permissions: {
+            mode: 'auto',
+            allow: [],
+            deny: [],
+            notAutomatic: [],
+        },
+        privacy: {
+            mode: 'balanced',
+            telemetry: 'off',
+        },
+        artifacts: {
+            defaultPath: '.pugi/artifacts',
+            promoteExplicitly: true,
+        },
+    }, created, skipped);
+    writeJsonIfMissing(resolve(pugiDir, 'mcp.json'), { schema: 1, servers: [] }, created, skipped);
+    writeJsonIfMissing(resolve(pugiDir, 'index.json'), emptyIndex(), created, skipped);
+    writeTextIfMissing(resolve(pugiDir, 'PUGI.md'), [
+        '# Pugi Project Context',
+        '',
+        '## Product Workflow',
+        '',
+        '- Public product name: Pugi',
+        '- Default flow: idea -> build -> review',
+        '- Approvals are automatic by default until a repo, environment, workflow, or action is marked notAutomatic.',
+        '- Do not add AI Co-Authored-By trailers.',
+        '- Generated code, comments, commits, PR text, and technical docs default to English.',
+        '',
+        '## Project Notes',
+        '',
+        '- Add repo-specific architecture, commands, and business rules here.',
+        '- Do not store secrets, real IPs, private key paths, tokens, or credentials here.',
+        '',
+    ].join('\n'), created, skipped);
+    writeTextIfMissing(resolve(cwd, '.pugiignore'), [
+        '# Pugi ignore rules',
+        '.env',
+        '.env.*',
+        '!.env.example',
+        'node_modules/',
+        'dist/',
+        '.next/',
+        'coverage/',
+        '*.log',
+        '*.pem',
+        '*.key',
+        '*.crt',
+        '*.p12',
+        '*.sql',
+        '*.dump',
+        '',
+    ].join('\n'), created, skipped);
+    ensurePugiGitIgnore(cwd, created, skipped);
+    // `silent` is honoured implicitly — this module never writes to
+    // stdout/stderr. The flag exists so the standalone `pugi init` command
+    // can layer its own logger on top (it does, in runtime/cli.ts), while
+    // the auto-init REPL path leaves the boot stream untouched. We
+    // reference the flag here to defeat the lint "unused" warning and to
+    // document the contract in the source.
+    void silent;
+    return {
+        created: created.length > 0,
+        dir: pugiDir,
+        createdPaths: created,
+        skippedPaths: skipped,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Helpers (mirror the previous in-file implementations in cli.ts)     */
+/* ------------------------------------------------------------------ */
+function mkdirIfMissing(path, created, skipped) {
+    if (existsSync(path)) {
+        skipped.push(path);
+        return;
+    }
+    mkdirSync(path, { recursive: true });
+    created.push(path);
+}
+function writeJsonIfMissing(path, value, created, skipped) {
+    writeTextIfMissing(path, `${JSON.stringify(value, null, 2)}\n`, created, skipped);
+}
+function writeTextIfMissing(path, value, created, skipped) {
+    if (existsSync(path)) {
+        skipped.push(path);
+        return;
+    }
+    writeFileSync(path, value, { encoding: 'utf8', mode: 0o600 });
+    created.push(path);
+}
+/**
+ * Ensure the workspace `.gitignore` ignores `.pugi/`. The function is
+ * additive: it leaves an existing `.gitignore` body intact and appends
+ * the marker only when none of `.pugi/`, `/.pugi/`, or `.pugi` is
+ * already present. On a fresh repo with no `.gitignore` it creates the
+ * file with the single marker line. Mode 0o600 matches the rest of the
+ * scaffold so a paranoid CI does not surface "world-readable" warnings.
+ */
+function ensurePugiGitIgnore(cwd, created, skipped) {
+    const gitignorePath = resolve(cwd, '.gitignore');
+    const marker = '.pugi/';
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, `${marker}\n`, { encoding: 'utf8', mode: 0o600 });
+        created.push(gitignorePath);
+        return;
+    }
+    const current = readFileSync(gitignorePath, 'utf8');
+    const lines = current.split('\n').map((line) => line.trim());
+    if (lines.includes(marker) || lines.includes('/.pugi/') || lines.includes('.pugi')) {
+        skipped.push(gitignorePath);
+        return;
+    }
+    const next = current.endsWith('\n') ? `${current}${marker}\n` : `${current}\n${marker}\n`;
+    writeFileSync(gitignorePath, next, { encoding: 'utf8' });
+    created.push(`${gitignorePath} (+${marker})`);
+}
+//# sourceMappingURL=scaffold.js.map