hammoc 1.5.0 → 1.7.0

package/packages/server/dist/services/cliSessionPool.js

@@ -0,0 +1,278 @@
+/**
+ * CLI Session Pool (Epic 32 — Story 32.4)
+ *
+ * Owns the PTY processes for the CLI conversation engine (`CliChatEngine`), one
+ * per in-flight turn. This pool is **deliberately a separate module singleton
+ * from `ptyService`** (the web terminal pool): the dashboard's "active terminals"
+ * count is derived from `ptyService`'s session map, so routing CLI-engine PTYs
+ * through `ptyService` would pollute that count (Sprint Change Proposal §9.2 #3,
+ * spike §9-3). Keeping a distinct instance guarantees the CLI engine's PTYs never
+ * leak into the terminal count — isolation by construction.
+ *
+ * The Windows PATH normalization and binary-discovery patterns are *borrowed*
+ * from `ptyService` (which stays unmodified). They are duplicated here on purpose
+ * for file independence and isolation — the same convention `chatService.ts` and
+ * `streamHandler.ts` already use for `extractContextWindow`.
+ */
+import * as pty from 'node-pty';
+import { randomUUID } from 'crypto';
+import { execSync } from 'child_process';
+import os from 'os';
+import path from 'path';
+import { existsSync, statSync, accessSync, constants as fsConstants } from 'fs';
+import { createLogger } from '../utils/logger.js';
+import { resolveBundledBinaryPath } from '../utils/bundledBinaryModelSupport.js';
+const log = createLogger('cliSessionPool');
+/**
+ * "I am running inside claude" environment signals. Stripped before spawning a
+ * fresh interactive claude so it starts a clean session rather than trying to
+ * attach to the host Hammoc process (spike §2).
+ *
+ * CHILD_SESSION / SESSION_ID matter when Hammoc itself is launched FROM INSIDE a claude session:
+ * the spawned CLI claude would inherit "I am a child session" and then NOT write its own session
+ * JSONL transcript — which the engine drains for chat content, so every turn would look empty
+ * (verified 2026-06-15: a probe that spawned claude under these inherited vars produced no
+ * transcript until they were stripped). Production Hammoc is not nested so it never hits this, but
+ * stripping them is the correct defensive posture for in-session launches.
+ */
+const CLAUDE_ENV_SIGNALS = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_SSE_PORT',
+    'CLAUDE_CODE_CHILD_SESSION',
+    'CLAUDE_CODE_SESSION_ID',
+];
+class CliSessionPool {
+    sessions = new Map();
+    // On Windows the server may be started from bash/MINGW with an incomplete PATH.
+    // Read the real Windows system PATH once via PowerShell+registry so spawned
+    // claude sessions inherit a complete environment regardless of launch shell.
+    // (Pattern borrowed from ptyService — kept private here for isolation.)
+    windowsSystemPath = (() => {
+        if (process.platform !== 'win32')
+            return null;
+        try {
+            const sysRoot = process.env.SystemRoot || 'C:\\Windows';
+            const ps = `${sysRoot}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+            const cmd = `[System.Environment]::GetEnvironmentVariable('Path','Machine')+';'+[System.Environment]::GetEnvironmentVariable('Path','User')`;
+            return execSync(`"${ps}" -NoProfile -Command "${cmd}"`, { encoding: 'utf8' }).trim();
+        }
+        catch {
+            return null;
+        }
+    })();
+    /**
+     * Convert MINGW64 Unix-style PATH entries to Windows format and merge in the
+     * real Windows system PATH. (Borrowed verbatim in spirit from ptyService.)
+     */
+    normalizePathForWindows(env) {
+        if (process.platform !== 'win32')
+            return env;
+        const pathKeys = Object.keys(env).filter((k) => k.toUpperCase() === 'PATH');
+        const parts = pathKeys.map((k) => env[k]).filter(Boolean);
+        if (this.windowsSystemPath)
+            parts.push(this.windowsSystemPath);
+        if (parts.length === 0)
+            return env;
+        const merged = parts.join(';');
+        if (!merged)
+            return env;
+        const normalized = { ...env };
+        for (const k of pathKeys) {
+            delete normalized[k];
+        }
+        const entries = [];
+        for (const rawSegment of merged.split(';')) {
+            const segment = rawSegment.trim().replace(/^"|"$/g, '');
+            if (!segment)
+                continue;
+            const segParts = segment.split(':');
+            let i = 0;
+            while (i < segParts.length) {
+                const part = segParts[i];
+                if (part.length === 1 && /^[a-zA-Z]$/.test(part) && i + 1 < segParts.length && /^[/\\]/.test(segParts[i + 1])) {
+                    entries.push(`${part}:${segParts[i + 1]}`);
+                    i += 2;
+                }
+                else if (part) {
+                    entries.push(part);
+                    i++;
+                }
+                else {
+                    i++;
+                }
+            }
+        }
+        const windowsEntries = entries.map((p) => {
+            const match = p.match(/^\/([a-zA-Z])\/(.*)/);
+            if (match) {
+                return `${match[1].toUpperCase()}:\\${match[2].replace(/\//g, '\\')}`;
+            }
+            return p;
+        });
+        normalized['Path'] = windowsEntries.join(';');
+        return normalized;
+    }
+    /**
+     * Build the spawn environment: process.env minus undefined values and minus
+     * the "inside claude" signal vars, with Windows PATH normalized.
+     */
+    buildEnv() {
+        const base = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] != null));
+        for (const signal of CLAUDE_ENV_SIGNALS) {
+            delete base[signal];
+        }
+        return this.normalizePathForWindows(base);
+    }
+    /**
+     * Best-effort sanity check for a user-supplied binary override (Story 33.3): exists,
+     * is a regular file, and (POSIX only) is executable by this process. Windows has no
+     * comparable execute bit, so `.exe`/file existence is sufficient there. Intentionally
+     * shallow — no signature / "is this really claude" inspection (out of scope).
+     */
+    isValidBinaryOverride(candidate) {
+        try {
+            if (!statSync(candidate).isFile())
+                return false;
+            if (process.platform !== 'win32') {
+                accessSync(candidate, fsConstants.X_OK);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Resolve an executable path for `claude`. PATH lookup can fail in the server's
+     * child process (spike §9-5: `where claude` failed; the fallback resolved it),
+     * so known install locations are tried first, then a PATH probe with the
+     * corrected env, then a bare name as a last resort (pty resolves via env PATH).
+     *
+     * Story 33.3: when a non-empty `override` is supplied it is checked first and used
+     * if valid. An *invalid* override never hard-fails the turn — it logs a warning and
+     * falls through to the normal chain (auto-detect is the better UX than blocking CLI
+     * mode over a bad path). Empty / undefined skips the override entirely.
+     */
+    resolveClaudeBinary(env, override) {
+        const trimmedOverride = override?.trim();
+        if (trimmedOverride) {
+            if (this.isValidBinaryOverride(trimmedOverride))
+                return trimmedOverride;
+            log.warn(`Configured claude binary path is invalid (missing / not a file / not executable): "${trimmedOverride}" — falling back to auto-detect.`);
+        }
+        // Prefer the bundled engine binary shipped inside @anthropic-ai/claude-agent-sdk: it is the
+        // SAME Claude Code CLI as a system install (interactive by default) but version-pinned by
+        // Hammoc's package.json, so CLI mode and SDK mode run the identical engine — both recognize
+        // newly-released models (e.g. Fable 5). Auth/session are unaffected: the spawn inherits the
+        // same env, hence the same ~/.claude. A valid user override above still takes precedence.
+        const bundled = resolveBundledBinaryPath();
+        if (bundled && existsSync(bundled))
+            return bundled;
+        const home = os.homedir();
+        const isWin = process.platform === 'win32';
+        const candidates = isWin
+            ? [path.join(home, '.local', 'bin', 'claude.exe'), path.join(home, '.local', 'bin', 'claude')]
+            : [path.join(home, '.local', 'bin', 'claude')];
+        for (const candidate of candidates) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+        try {
+            const probe = isWin ? 'where claude' : 'command -v claude';
+            const resolved = execSync(probe, { env, encoding: 'utf8' })
+                .split(/\r?\n/)
+                .map((s) => s.trim())
+                .find((s) => s && existsSync(s));
+            if (resolved)
+                return resolved;
+        }
+        catch {
+            // Not resolvable via PATH — fall through to bare name.
+        }
+        return isWin ? 'claude.exe' : 'claude';
+    }
+    /**
+     * Spawn an interactive claude TUI in a PTY and register it in the pool.
+     * The caller drives stdin (prompt injection), wires `pty.onData`, and attaches
+     * a watcher disposer via `registerDisposer`.
+     */
+    spawnClaude(opts) {
+        const env = this.buildEnv();
+        const bin = this.resolveClaudeBinary(env, opts.binaryPathOverride);
+        const handle = randomUUID();
+        const ptyProcess = pty.spawn(bin, opts.args, {
+            name: 'xterm-256color',
+            cols: opts.cols ?? 120,
+            rows: opts.rows ?? 40,
+            cwd: opts.cwd,
+            env,
+        });
+        this.sessions.set(handle, { pty: ptyProcess, handle, createdAt: Date.now() });
+        log.info(`CLI PTY spawned: handle=${handle} bin=${bin} args=[${opts.args.join(' ')}] cwd=${opts.cwd ?? '(inherit)'}`);
+        return { handle, pty: ptyProcess };
+    }
+    /** Attach the watcher teardown so dispose() tears down PTY + watcher together. */
+    registerDisposer(handle, dispose) {
+        const entry = this.sessions.get(handle);
+        if (entry)
+            entry.dispose = dispose;
+    }
+    /** Send Ctrl+C (interrupt) to the PTY without killing it. */
+    interrupt(handle) {
+        const entry = this.sessions.get(handle);
+        if (!entry)
+            return;
+        try {
+            entry.pty.write('\x03');
+        }
+        catch {
+            // PTY may already be gone.
+        }
+    }
+    /**
+     * Tear down a CLI PTY: run the watcher disposer, kill the process, remove from
+     * the pool. Removal happens first so any onExit listener's dispose is a no-op.
+     * The kill is wrapped in try/catch to absorb Windows ConPTY shutdown noise
+     * (`AttachConsole failed`, spike §9-6 — `ptyService.killSession` pattern).
+     */
+    dispose(handle) {
+        const entry = this.sessions.get(handle);
+        if (!entry)
+            return;
+        this.sessions.delete(handle);
+        try {
+            entry.dispose?.();
+        }
+        catch {
+            // Watcher teardown best-effort.
+        }
+        try {
+            entry.pty.kill();
+        }
+        catch {
+            // PTY may already be dead / ConPTY shutdown noise — ignore.
+        }
+        log.debug(`CLI PTY disposed: handle=${handle}`);
+    }
+    /** Destroy every CLI PTY (server shutdown). Symmetric with ptyService.destroyAll. */
+    destroyAll() {
+        if (this.sessions.size > 0) {
+            log.info(`Destroying all CLI PTYs (${this.sessions.size} active)`);
+        }
+        for (const handle of [...this.sessions.keys()]) {
+            this.dispose(handle);
+        }
+    }
+    /** Number of live CLI PTYs (for tests / introspection). */
+    get size() {
+        return this.sessions.size;
+    }
+    /** Whether a handle is still live in the pool. */
+    has(handle) {
+        return this.sessions.has(handle);
+    }
+}
+/** Module singleton — isolated from the web terminal pool (`ptyService`). */
+export const cliSessionPool = new CliSessionPool();
+//# sourceMappingURL=cliSessionPool.js.map

package/packages/server/dist/services/cliSessionPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliSessionPool.js","sourceRoot":"","sources":["../../src/services/cliSessionPool.ts"],"names":[],"mappings":"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"}

package/packages/server/dist/services/cliSpinnerProgress.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CLI spinner-progress grid reader (Epic 37 — Story 37.2)
+ *
+ * Reads the generation "↓ N tokens" counter (and the optional leading "(Ns ·" elapsed
+ * clock) from a *settled screen grid* produced by the headless screen model (Story
+ * 37.1). This is the token data source that replaces the linear ANSI-stripped buffer
+ * scan: claude overwrites the spinner counter **in place** (the same screen cell), so a
+ * settled grid carries one final value per row — the "365" + "366" → "365366" fusion
+ * the linear path suffered is **structurally impossible**, and the old fusion-defense
+ * guards (digit cap, malformed-grouping, implausible-jump) are no longer needed.
+ *
+ * Pure — input is the grid rows, output is the parsed progress or null. The CLI engine
+ * schedules a `flush()` and then calls this on the settled grid; the callback contract
+ * (`{ tokens, elapsedSeconds }`, emit-on-change) is unchanged.
+ *
+ * @see docs/stories/37.2.story.md
+ * [Source: docs/prd/epic-37-cli-terminal-emulation.md#story-372]
+ */
+export interface SpinnerProgress {
+    tokens: number;
+    elapsedSeconds: number;
+    /**
+     * True only when this spinner frame is in the THINKING phase (status segment reads
+     * "… · [still ]thinking …" after the token counter). Additive/optional — ABSENT means
+     * "not a recognized thinking phase" (generic generation), so existing callers/tests that
+     * read just `{ tokens, elapsedSeconds }` are unaffected. The client uses it to label the
+     * live progress indicator "Thinking…" (Story 37.11 AC1, achievable tier). See THINKING_PHASE_RE.
+     */
+    thinking?: boolean;
+}
+/**
+ * Read the freshest spinner counter from a settled screen grid. Returns null when no
+ * counter row is present (e.g. a thinking-phase spinner with no "↓ N tokens") — the
+ * caller treats null as "no emit", preserving the false-0 guard.
+ *
+ * Since claude overwrites the same cell, a settled grid has at most one counter row; if
+ * more than one matches, the BOTTOM-most (freshest rendered) row wins. Rows are never
+ * merged or concatenated — a single row already holds the whole current value.
+ */
+export declare function readSpinnerProgress(grid: string[]): SpinnerProgress | null;
+//# sourceMappingURL=cliSpinnerProgress.d.ts.map

package/packages/server/dist/services/cliSpinnerProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliSpinnerProgress.d.ts","sourceRoot":"","sources":["../../src/services/cliSpinnerProgress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAqEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,GAAG,IAAI,CAoC1E"}

package/packages/server/dist/services/cliSpinnerProgress.js

@@ -0,0 +1,131 @@
+/**
+ * CLI spinner-progress grid reader (Epic 37 — Story 37.2)
+ *
+ * Reads the generation "↓ N tokens" counter (and the optional leading "(Ns ·" elapsed
+ * clock) from a *settled screen grid* produced by the headless screen model (Story
+ * 37.1). This is the token data source that replaces the linear ANSI-stripped buffer
+ * scan: claude overwrites the spinner counter **in place** (the same screen cell), so a
+ * settled grid carries one final value per row — the "365" + "366" → "365366" fusion
+ * the linear path suffered is **structurally impossible**, and the old fusion-defense
+ * guards (digit cap, malformed-grouping, implausible-jump) are no longer needed.
+ *
+ * Pure — input is the grid rows, output is the parsed progress or null. The CLI engine
+ * schedules a `flush()` and then calls this on the settled grid; the callback contract
+ * (`{ tokens, elapsedSeconds }`, emit-on-change) is unchanged.
+ *
+ * @see docs/stories/37.2.story.md
+ * [Source: docs/prd/epic-37-cli-terminal-emulation.md#story-372]
+ */
+import { liveFooterRows } from './cliGridRegion.js';
+/**
+ * The spinner counter as RENDERED in the grid. Captures both the raw ("↓ 108 tokens")
+ * and abbreviated ("↓ 1.4k tokens") shapes claude paints — matching the Story 37.1
+ * realframes counter regex `↓ ?[\d.,]+k? tokens`. The old linear CLI_PROGRESS_RE used
+ * `[\d,]+`, which breaks at `.`/`k` and so MISSED the abbreviated form entirely; reading
+ * the grid lets us capture it. The rotating glyph word (Flowing…/Crunched/Brewed/
+ * Moseying…) is deliberately NOT part of the match — it is version-fragile, so the row
+ * is identified by the counter alone.
+ *
+ * Both arrow directions are accepted (`[↑↓]`): claude renders the counter as "↓ N tokens"
+ * for some phases and "↑ N tokens" for others (실측 2026-06-14 — a long step showed
+ * "↑ 95.6k tokens"). The ↓-only regex MISSED the ↑ form, so a long ↑-phase emitted no
+ * progress at all and the UI looked frozen ("멈춤 vs 느림" 구분 불가). The arrow is required
+ * (not optional) so a bare "N tokens" in prose can't flash a phantom counter.
+ */
+const GRID_COUNTER_RE = /[↑↓]\s*([\d.,]+k?)\s*tokens/i;
+/**
+ * The leading elapsed clock, paren-anchored (Story 37.3 — "Xm Ys" summation). claude
+ * renders the clock as the FIRST thing after the spinner's "(" — either bare seconds
+ * "(9s ·" or a minute form "(1m 36s ·". Both the minute and second segments are optional
+ * and captured separately; an absent segment counts as 0, so bare seconds preserve their
+ * old value ("9s" → 9) and a missing clock yields 0. The "(" anchor is load-bearing: the
+ * time is always rendered right after the opening paren, so anchoring keeps a counter or
+ * prose number ("↓ 365 tokens", "thinking") from being mistaken for the clock.
+ */
+const GRID_ELAPSED_RE = /\((?:(\d+)m\s*)?(?:(\d+)s\b)?/;
+/**
+ * The THINKING-phase status segment claude renders INSIDE the spinner's paren group, AFTER the
+ * token counter: "↓ 143 tokens · thinking with high effort)" / "· still thinking with high effort)"
+ * (실측 2026-06-16, verbose:on AND verbose:off real PTY — `cli-verbose-on/off-long-thinking` fixtures).
+ *
+ * Why a *phase* flag and not a body thinking card: in verbose:true mode (Hammoc's spawn) claude paints
+ * NO live thinking *content* into the screen body — only this bottom spinner advances (elapsed clock +
+ * token counter + this phrase); the reasoning block lands WHOLE at completion. So the only live
+ * "Claude is thinking" signal is this spinner segment. Surfacing it lets the client LABEL the
+ * already-live generation-progress indicator as "Thinking…" (vs generic generation) WITHOUT inventing
+ * a card from the version-fragile, region-EXCLUDED footer spinner (which `scrollbackBodyRows` drops to
+ * avoid resume-repaint poisoning).
+ *
+ * Anchored `tokens … thinking` WITHIN the paren (`[^)]*`, no `)` crossing) so a rotating gerund word
+ * BEFORE the counter (a hypothetical "Thinking…" spinner glyph) can't false-positive — only the
+ * post-counter phase label counts. Effort-suffix agnostic ("with high effort" optional). A
+ * response-phase row ("↓ 1.3k tokens)") carries no such segment → not thinking.
+ */
+const THINKING_PHASE_RE = /\btokens\b[^)]*\bthinking\b/i;
+/**
+ * Sum the paren-anchored elapsed clock on a spinner row to integer seconds. Pure — input
+ * is the rendered row, output is `minutes * 60 + seconds`. A minute form "(1m 36s ·" → 96,
+ * bare seconds "(9s ·" → 9 (minutes default to 0), and a row with no clock segment → 0
+ * (Story 37.3 AC3). Hour ("Xh") forms are unobserved and out of scope; if claude ever
+ * renders them, the same anchored-sum pattern extends. The grid overwrites the spinner
+ * cell in place, so an in-place "(1m 36s" → "(1m 37s" redraw reads as the latest value
+ * (97), never a fused "136137" — fusion is structurally impossible here too.
+ */
+function sumElapsedSeconds(row) {
+    const m = GRID_ELAPSED_RE.exec(row);
+    if (!m)
+        return 0;
+    const minutes = m[1] ? parseInt(m[1], 10) : 0;
+    const seconds = m[2] ? parseInt(m[2], 10) : 0;
+    return minutes * 60 + seconds;
+}
+/**
+ * Read the freshest spinner counter from a settled screen grid. Returns null when no
+ * counter row is present (e.g. a thinking-phase spinner with no "↓ N tokens") — the
+ * caller treats null as "no emit", preserving the false-0 guard.
+ *
+ * Since claude overwrites the same cell, a settled grid has at most one counter row; if
+ * more than one matches, the BOTTOM-most (freshest rendered) row wins. Rows are never
+ * merged or concatenated — a single row already holds the whole current value.
+ */
+export function readSpinnerProgress(grid) {
+    // Live region only: the spinner counter renders at the bottom of the screen, so a "↓ N tokens"
+    // value QUOTED in resume-repaint scrollback can't flash a phantom counter during the pre-generation
+    // thinking phase (no live counter row yet). Bottom-most (freshest) within the region wins.
+    const region = liveFooterRows(grid);
+    for (let y = region.length - 1; y >= 0; y--) {
+        const counter = GRID_COUNTER_RE.exec(region[y]);
+        if (!counter)
+            continue;
+        const raw = counter[1];
+        // Normalize to an integer token count: strip thousands separators, then expand a
+        // "k" suffix ("1.4k" → 1400). The grid never fuses values, so this is plain parsing.
+        const tokens = /k$/i.test(raw)
+            ? Math.round(parseFloat(raw.slice(0, -1).replace(/,/g, '')) * 1000)
+            : parseInt(raw.replace(/,/g, ''), 10);
+        if (!Number.isFinite(tokens))
+            return null;
+        // Phase label rides the SAME counter row we already matched (no extra scan, same region —
+        // so no new resume-poisoning surface). Set only when true to keep the shape additive.
+        const thinking = THINKING_PHASE_RE.test(region[y]);
+        return { tokens, elapsedSeconds: sumElapsedSeconds(region[y]), ...(thinking ? { thinking: true } : {}) };
+    }
+    // Fallback: no token counter yet, but an elapsed clock is on screen → emit time-only (tokens 0). claude
+    // paints "(Ns ·" the moment generation starts, BEFORE the first "↓ N tokens" counter appears — without
+    // this the live timer stays frozen until tokens show up (the token-less "(12s" the user saw not parsed).
+    // Require a real minute/second digit (GRID_ELAPSED_RE leaves both groups undefined for a bare "("), so a
+    // stray paren in prose can't flash a phantom. Bottom-most (freshest) within the live region wins.
+    for (let y = region.length - 1; y >= 0; y--) {
+        // A counter ARROW on the row means a counter is mid-write ("↓ 36" before "tokens" settles, split across
+        // PTY chunks) — wait for it to settle rather than flashing a time-only reading. Fall back ONLY when the
+        // row carries no counter glyph at all (the genuine pre-counter "(12s" before any counter appears).
+        if (/[↑↓]/.test(region[y]))
+            continue;
+        const m = GRID_ELAPSED_RE.exec(region[y]);
+        if (m && (m[1] !== undefined || m[2] !== undefined)) {
+            return { tokens: 0, elapsedSeconds: sumElapsedSeconds(region[y]) };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=cliSpinnerProgress.js.map

package/packages/server/dist/services/cliSpinnerProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliSpinnerProgress.js","sourceRoot":"","sources":["../../src/services/cliSpinnerProgress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,eAAe,GAAG,8BAA8B,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,+BAA+B,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,iBAAiB,GAAG,8BAA8B,CAAC;AAEzD;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,OAAO,OAAO,GAAG,EAAE,GAAG,OAAO,CAAC;AAChC,CAAC;AAeD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAChD,+FAA+F;IAC/F,oGAAoG;IACpG,2FAA2F;IAC3F,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACvB,iFAAiF;QACjF,qFAAqF;QACrF,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;YAC5B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;YACnE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,0FAA0F;QAC1F,sFAAsF;QACtF,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC3G,CAAC;IACD,wGAAwG;IACxG,uGAAuG;IACvG,yGAAyG;IACzG,yGAAyG;IACzG,kGAAkG;IAClG,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,wGAAwG;QACxG,wGAAwG;QACxG,mGAAmG;QACnG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QACrC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;YACpD,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/packages/server/dist/services/contextBuilderScriptTemplate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Story 31.2 (Task A.3): generator for the standalone SessionStart hook script
+ * `<projectRoot>/.hammoc/hooks/context-builder.mjs`.
+ *
+ * The generated `.mjs` runs independently of the Hammoc server at every session
+ * start. It is REGENERATED on every manifest save, so the declared file list /
+ * variable toggles / acknowledged commands are baked in as a CONFIG literal,
+ * while the actual VALUES (file contents, git output, today's date, active BMad
+ * story, command stdout) are computed FRESH at runtime (AC2.b/2.c — never
+ * snapshotted at generation time).
+ *
+ * Implementation note — the script body is a `String.raw` template so the regex
+ * backslashes (`\s`, `\r`, `\n`) survive into the emitted file verbatim. The two
+ * injected values are spliced in via function-replacement (not `${}`
+ * interpolation) so a `$` inside a path or command cannot trigger a replacement
+ * pattern, and so the body can stay free of `${` entirely.
+ */
+import type { ContextBuilderManifest } from '@hammoc/shared';
+/**
+ * Build the `.mjs` script text for the given project root + manifest. Only
+ * acknowledged custom commands are baked in (AC5.b).
+ */
+export declare function buildContextBuilderScript(projectRoot: string, manifest: ContextBuilderManifest): string;
+//# sourceMappingURL=contextBuilderScriptTemplate.d.ts.map

package/packages/server/dist/services/contextBuilderScriptTemplate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextBuilderScriptTemplate.d.ts","sourceRoot":"","sources":["../../src/services/contextBuilderScriptTemplate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AA0J7D;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,sBAAsB,GAC/B,MAAM,CAkBR"}