@graypark/loophaus 3.4.0 → 3.5.0

package/dist/commands/loop-plan.md

@@ -0,0 +1,257 @@
+---
+description: "Plan and start loop via interactive interview — auto-parallelizes across worktrees"
+argument-hint: "TASK_DESCRIPTION"
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "Agent", "Skill"]
+---
+
+# /loop-plan — Plan, Parallelize, Execute, Merge
+
+End-to-end workflow: interview → PRD → parallel distribution → loop execution → merge.
+The user runs `/loop-plan` once and gets a single merged branch with all work done.
+
+---
+
+## Phase 1: Discovery Interview
+
+Ask 3-5 focused questions about $ARGUMENTS:
+
+| Category | What to confirm |
+|----------|----------------|
+| Scope | Single feature? Multi-file? Full refactor? |
+| Success criteria | What counts as "done"? |
+| Verification | `npm test`, `npx tsc`, lint commands? |
+| References | Existing code, patterns to follow? |
+| Parallelism | Multiple services? Independent file groups? |
+| Constraints | Must not break existing tests? Library restrictions? |
+
+One round of questions only. Skip questions already answered in $ARGUMENTS.
+
+## Phase 2: PRD Generation
+
+Generate `prd.json`:
+
+```json
+{
+  "title": "<project title>",
+  "description": "<1-2 sentence summary>",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "<story title>",
+      "description": "<what to implement>",
+      "acceptanceCriteria": ["<criterion 1>", "<criterion 2>"],
+      "priority": 1,
+      "passes": false,
+      "group": "<ownership group — e.g., frontend, backend, auth, database>",
+      "testCommand": "<optional: npm test -- US-001>"
+    }
+  ]
+}
+```
+
+Rules:
+- Right-size stories: each completable in 1-2 iterations
+- Assign `group` to each story for parallel distribution
+- Order by `priority` (dependencies first)
+- Include `testCommand` when verification is possible
+
+Present PRD to user for approval before proceeding.
+
+## Phase 3: Parallelism Assessment
+
+Score the task for parallel execution:
+
+| Factor | Score |
+|--------|-------|
+| Stories span 3+ directories | +2 |
+| Stories are independent (no shared state) | +2 |
+| Multiple services (frontend/backend/auth) | +3 |
+| 6+ stories total | +1 |
+| Stories need full codebase context | -2 |
+| Strict ordering required | -3 |
+| Cross-file understanding needed | -1 |
+
+**Decision:**
+- Score >= 3 → **Parallel mode** (distribute across worktrees by `group`)
+- Score < 3 → **Sequential mode** (single loop, stories in order)
+
+Display the score and recommendation to the user. Proceed with the recommended mode unless the user overrides.
+
+## Phase 4A: Parallel Execution (score >= 3)
+
+### Step 1: Distribute stories by group
+
+Group stories by their `group` field. Each group becomes a worktree.
+
+```bash
+# Create the current branch as base for worktrees
+BASE_BRANCH=$(git branch --show-current)
+```
+
+### Step 2: Create worktrees and distribute PRDs
+
+For each group, use the Agent tool to spawn a subagent in an isolated worktree:
+
+```
+Agent(
+  prompt: "Implement the following stories from prd.json in this worktree.
+           Work on one story at a time. For each story:
+           1. Read prd.json and pick the next story where passes=false
+           2. Implement the story
+           3. Verify with the test command if provided
+           4. Set passes=true in prd.json
+           5. Commit: git add -A && git commit -m 'feat: <story-id> <title>'
+
+           When ALL stories pass, output <promise>TASK COMPLETE</promise>.
+
+           Stories assigned to you:
+           <filtered stories for this group>",
+  isolation: "worktree",
+  run_in_background: true,
+  name: "<group-name>"
+)
+```
+
+Launch ALL group agents in a single message (parallel execution).
+
+### Step 3: Wait and collect results
+
+Monitor agent completion. When all agents finish:
+
+1. List completed worktrees and their branches
+2. For each worktree branch, check if all assigned stories passed
+
+### Step 4: Merge results
+
+Merge all worktree branches back to the base branch using squash strategy:
+
+```bash
+git checkout $BASE_BRANCH
+
+# For each completed worktree branch:
+git merge --squash loophaus/<group-name>
+git commit -m "feat: merge <group-name> stories"
+```
+
+If merge conflicts occur:
+1. Report the conflict to the user
+2. Suggest manual resolution
+3. Do NOT force-resolve
+
+### Step 5: Cleanup
+
+```bash
+# Remove worktrees
+git worktree list | grep .loophaus/worktrees | awk '{print $1}' | xargs -I {} git worktree remove {} --force
+# Remove branches
+git branch | grep loophaus/ | xargs git branch -D
+```
+
+### Step 6: Final verification
+
+Run the full test/verification command on the merged result.
+Update the main `prd.json` with all stories marked as `passes: true`.
+
+## Phase 4B: Sequential Execution (score < 3)
+
+Single loop, no worktrees:
+
+1. Create `.loophaus/state.json`:
+```json
+{
+  "active": true,
+  "prompt": "Read prd.json. Pick next story where passes=false. Implement, verify, commit. Update progress.txt.",
+  "completionPromise": "TASK COMPLETE",
+  "maxIterations": <stories * 2 + 3>,
+  "currentIteration": 0,
+  "sessionId": ""
+}
+```
+
+2. Start working on US-001 immediately.
+3. Each iteration: implement one story, verify, commit, update prd.json.
+4. Output `<promise>TASK COMPLETE</promise>` when ALL stories pass.
+
+## Phase 5: Evaluate
+
+After all stories are implemented (parallel or sequential), evaluate each:
+
+For each story in prd.json:
+1. Run testCommand if defined
+2. Run typecheck if project has tsconfig.json: `npx tsc --noEmit`
+3. Run lint if project has eslint config: `npx eslint . --quiet`
+4. Check .loophaus/verify.sh if exists
+5. Analyze git diff size
+
+Score each story 0-100. Record in `.loophaus/results.tsv`.
+
+Display quality dashboard:
+```
+Quality Evaluation
+──────────────────
+  US-001  Add login API        score: 65  (D) <- needs refinement
+  US-002  Add auth middleware   score: 92  (A) ✓
+  US-003  Add login UI         score: 45  (F) <- needs refinement
+
+Overall: 67/100 — threshold: 80
+Stories needing refinement: 2
+```
+
+## Phase 6: Refine Loop (autoresearch pattern)
+
+For each story below the quality threshold (default: 80):
+
+LOOP (max 3 attempts per story):
+  1. Git checkpoint: `git add -A && git commit -m "checkpoint: <story-id> attempt <N>"`
+  2. Read the quality feedback (which criteria failed, error messages)
+  3. Re-implement with a different approach, focusing on weak areas
+  4. Re-evaluate (same criteria as Phase 5)
+  5. If score improved -> KEEP (advance the commit)
+     If score same or worse -> DISCARD (git reset --hard to checkpoint)
+  6. Record attempt in .loophaus/results.tsv
+  7. If score >= threshold -> DONE with this story
+     If max attempts reached -> move on (best-effort)
+
+After all refinements:
+```
+Refinement Complete
+───────────────────
+  US-001  65 -> 82 (B) ✓  (2 attempts)
+  US-003  45 -> 78 (C)    (3 attempts, best effort)
+
+Overall: 84/100 — PASS
+```
+
+CRITICAL: The refine loop uses git reset --hard to discard bad attempts. This is the autoresearch pattern — safe because we always checkpoint first.
+
+## Phase 7: Summary Report
+
+After completion (parallel or sequential), output:
+
+```
+Loop Plan Complete
+══════════════════
+
+Mode:       parallel (3 worktrees) | sequential
+Stories:    7/7 done
+Duration:   ~15 minutes
+Iterations: 12 total (across all workers)
+
+Stories:
+  ✓ US-001  Add login API          (backend, 2 iterations)
+  ✓ US-002  Add auth middleware     (backend, 1 iteration)
+  ✓ US-003  Add login UI           (frontend, 3 iterations)
+  ...
+
+Branch:     feature/auth-system (all work merged)
+Verify:     npm test ✓
+```
+
+## Rules
+
+- ALWAYS present PRD for user approval before execution
+- ALWAYS show parallelism score and recommendation
+- If parallel: launch ALL agents simultaneously (single message with multiple Agent calls)
+- If merge conflict: STOP and report. Do not auto-resolve.
+- Use `<promise>TASK COMPLETE</promise>` ONLY when genuinely complete
+- Update `progress.txt` with learnings after each story

package/dist/commands/loop-pulse.md

@@ -0,0 +1,38 @@
+---
+description: "Check loop status"
+allowed-tools:
+  [
+    "Read(.loophaus/state.json)",
+    "Read(.claude/ralph-loop.local.md)",
+    "Read(prd.json)",
+    "Read(progress.txt)",
+  ]
+---
+
+# /loop-pulse — Check Loop Status
+
+1. Read `.loophaus/state.json` (or legacy `.claude/ralph-loop.local.md`)
+   - If neither exists: "No active loop."
+
+2. If active, display:
+   ```
+   Loop Status
+   ───────────
+   Active:     yes
+   Iteration:  5/20
+   Promise:    TASK COMPLETE
+   ```
+
+3. If `prd.json` exists, also show:
+   ```
+   Stories
+   ───────
+   ✓ US-001  Add login API
+   ✓ US-002  Add auth middleware
+   → US-003  Add JWT refresh (in progress)
+     US-004  Add logout endpoint
+
+   Progress: 2/4 done
+   ```
+
+4. If `progress.txt` exists, show last 5 lines.

package/dist/commands/loop-stop.md

@@ -0,0 +1,29 @@
+---
+description: "Stop active loop"
+allowed-tools:
+  [
+    "Bash(test -f .loophaus/state.json:*)",
+    "Bash(rm .loophaus/state.json)",
+    "Read(.loophaus/state.json)",
+    "Bash(test -f .claude/ralph-loop.local.md:*)",
+    "Bash(rm .claude/ralph-loop.local.md)",
+    "Read(.claude/ralph-loop.local.md)",
+  ]
+---
+
+# /loop-stop — Stop Active Loop
+
+1. Check if `.loophaus/state.json` exists: `test -f .loophaus/state.json && echo "EXISTS" || echo "NOT_FOUND"`
+   - If not found, also check legacy path: `test -f .claude/ralph-loop.local.md && echo "LEGACY" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND** on both: Say "No active loop found."
+
+3. **If EXISTS** (.loophaus/state.json):
+   - Read the file to get `currentIteration`
+   - Remove it: `rm .loophaus/state.json`
+   - Report: "Stopped loop at iteration N."
+
+4. **If LEGACY** (.claude/ralph-loop.local.md):
+   - Read it to get the iteration field
+   - Remove it: `rm .claude/ralph-loop.local.md`
+   - Report: "Stopped loop at iteration N. (migrated from legacy path)"

package/dist/commands/loop.md

@@ -0,0 +1,17 @@
+---
+description: "Start iterative dev loop"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+---
+
+# /loop — Start Iterative Dev Loop
+
+Execute the setup script to initialize the loop:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Work on the task. When you try to exit, the stop hook feeds the SAME PROMPT back for the next iteration. Your previous work persists in files and git history.
+
+CRITICAL: If a completion promise is set, ONLY output it when genuinely complete. Do not output false promises to escape the loop.

package/dist/commands/ralph-loop.md

@@ -0,0 +1,18 @@
+---
+description: "Start Ralph Loop in current session"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Ralph Loop Command
+
+Execute the setup script to initialize the Ralph loop:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

package/dist/core/cost-tracker.d.ts

@@ -0,0 +1,33 @@
+interface ModelPrice {
+    input: number;
+    output: number;
+}
+interface CostBreakdown {
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+}
+interface CostRecord extends CostBreakdown {
+    label: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    ts: string;
+}
+interface TrackerSummary {
+    totalInput: number;
+    totalOutput: number;
+    totalCost: number;
+    records: number;
+}
+export interface CostTracker {
+    record(label: string, model: string, inputTokens: number, outputTokens: number): CostBreakdown;
+    summary(): TrackerSummary;
+    getRecords(): CostRecord[];
+}
+declare const MODEL_PRICES: Record<string, ModelPrice>;
+export declare function estimateCost(model: string, inputTokens: number, outputTokens: number): CostBreakdown;
+export declare function formatCost(cost: number): string;
+export declare function createTracker(): CostTracker;
+export { MODEL_PRICES };
+//# sourceMappingURL=cost-tracker.d.ts.map

package/dist/core/cost-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-tracker.d.ts","sourceRoot":"","sources":["../../core/cost-tracker.ts"],"names":[],"mappings":"AAEA,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,UAAW,SAAQ,aAAa;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,UAAU,cAAc;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC;IAC/F,OAAO,IAAI,cAAc,CAAC;IAC1B,UAAU,IAAI,UAAU,EAAE,CAAC;CAC5B;AAED,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAS5C,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,aAAa,CAKpG;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED,wBAAgB,aAAa,IAAI,WAAW,CAgB3C;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/core/cost-tracker.js

@@ -0,0 +1,41 @@
+// core/cost-tracker.ts — Token cost estimation. Prices in USD per 1M tokens.
+const MODEL_PRICES = {
+    "claude-opus-4": { input: 15, output: 75 },
+    "claude-sonnet-4": { input: 3, output: 15 },
+    "claude-haiku-4": { input: 0.8, output: 4 },
+    "gpt-4.1": { input: 2, output: 8 },
+    "gpt-4.1-mini": { input: 0.4, output: 1.6 },
+    "gpt-4o": { input: 2.5, output: 10 },
+    "o4-mini": { input: 1.1, output: 4.4 },
+    "default": { input: 3, output: 15 },
+};
+export function estimateCost(model, inputTokens, outputTokens) {
+    const prices = MODEL_PRICES[model] || MODEL_PRICES["default"];
+    const inputCost = (inputTokens / 1_000_000) * prices.input;
+    const outputCost = (outputTokens / 1_000_000) * prices.output;
+    return { inputCost, outputCost, totalCost: inputCost + outputCost };
+}
+export function formatCost(cost) {
+    if (cost < 0.01)
+        return `$${(cost * 100).toFixed(2)}¢`;
+    return `$${cost.toFixed(4)}`;
+}
+export function createTracker() {
+    const records = [];
+    return {
+        record(label, model, inputTokens, outputTokens) {
+            const cost = estimateCost(model, inputTokens, outputTokens);
+            records.push({ label, model, inputTokens, outputTokens, ...cost, ts: new Date().toISOString() });
+            return cost;
+        },
+        summary() {
+            const totalInput = records.reduce((s, r) => s + r.inputTokens, 0);
+            const totalOutput = records.reduce((s, r) => s + r.outputTokens, 0);
+            const totalCost = records.reduce((s, r) => s + r.totalCost, 0);
+            return { totalInput, totalOutput, totalCost, records: records.length };
+        },
+        getRecords() { return [...records]; },
+    };
+}
+export { MODEL_PRICES };
+//# sourceMappingURL=cost-tracker.js.map

package/dist/core/cost-tracker.js.map

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

package/dist/core/engine.d.ts

@@ -0,0 +1,4 @@
+import type { LoopState, StopHookInput, StopHookResult } from "./types.js";
+export declare function evaluateStopHook(input: StopHookInput, state: LoopState): StopHookResult;
+export declare function extractPromise(text: string, promisePhrase: string): boolean;
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../core/engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,cAAc,EAGf,MAAM,YAAY,CAAC;AAEpB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,GAAG,cAAc,CA+GvF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAG3E"}

package/dist/core/engine.js

@@ -0,0 +1,109 @@
+// Pure function: no I/O, no side effects. Returns decision + next state + events.
+export function evaluateStopHook(input, state) {
+    const events = [];
+    const nextState = { ...state };
+    if (!nextState.active) {
+        return { decision: "allow", nextState, events, output: null };
+    }
+    if (nextState.sessionId && input.session_id && nextState.sessionId !== input.session_id) {
+        return { decision: "allow", nextState, events, output: null };
+    }
+    nextState.currentIteration += 1;
+    events.push({ event: "iteration", iteration: nextState.currentIteration });
+    if (nextState.maxIterations > 0 && nextState.currentIteration > nextState.maxIterations) {
+        nextState.active = false;
+        events.push({ event: "stop", reason: "max_iterations" });
+        return {
+            decision: "allow",
+            nextState,
+            events,
+            output: null,
+            message: `Loop: max iterations (${nextState.maxIterations}) reached.`,
+        };
+    }
+    if (input.policy_result && input.policy_result.shouldStop) {
+        nextState.active = false;
+        events.push({ event: "stop", reason: "policy_violation", violations: input.policy_result.violations });
+        const reasons = input.policy_result.violations.map(v => `${v.type}: ${v.current}/${v.limit}`).join(", ");
+        return {
+            decision: "allow",
+            nextState,
+            events,
+            output: null,
+            message: `Loop: policy violation (${reasons}).`,
+        };
+    }
+    if (nextState.completionPromise && input.last_assistant_text) {
+        if (extractPromise(input.last_assistant_text, nextState.completionPromise)) {
+            nextState.active = false;
+            events.push({ event: "stop", reason: "completion_promise", promise: nextState.completionPromise });
+            return {
+                decision: "allow",
+                nextState,
+                events,
+                output: null,
+                message: `Loop: completion promise "${nextState.completionPromise}" detected.`,
+            };
+        }
+    }
+    // Check verify script result (pre-computed by caller)
+    if (nextState.verifyScript && input.verify_result) {
+        if (input.verify_result.passed) {
+            nextState.active = false;
+            events.push({ event: "stop", reason: "verify_script", script: nextState.verifyScript });
+            return {
+                decision: "allow",
+                nextState,
+                events,
+                output: null,
+                message: `Loop: verify script passed.`,
+            };
+        }
+        events.push({ event: "verify_failed", script: nextState.verifyScript, output: input.verify_result.output || "" });
+    }
+    if (input.test_results && input.test_results.length > 0) {
+        const allPassed = input.test_results.every(r => r.passed);
+        if (allPassed) {
+            events.push({ event: "test_result", status: "all_passed", results: input.test_results });
+        }
+        else {
+            const failed = input.test_results.filter(r => !r.passed);
+            events.push({ event: "test_result", status: "some_failed", failed: failed.map(f => f.storyId) });
+        }
+    }
+    if (input.stop_hook_active === true) {
+        if (!input.has_pending_stories) {
+            nextState.active = false;
+            events.push({ event: "stop", reason: "all_stories_done" });
+            return {
+                decision: "allow",
+                nextState,
+                events,
+                output: null,
+                message: "Loop: no pending stories. Allowing exit.",
+            };
+        }
+        events.push({ event: "continue", reason: "pending_stories" });
+    }
+    events.push({ event: "state_change", from: "running", to: "running" });
+    const iterInfo = nextState.maxIterations > 0
+        ? `${nextState.currentIteration}/${nextState.maxIterations}`
+        : `${nextState.currentIteration}`;
+    const reason = [nextState.prompt, "", "---", `Loop iteration ${iterInfo}. Continue working on the task above.`].join("\n");
+    const output = { decision: "block", reason };
+    if (nextState.completionPromise) {
+        output.systemMessage = `Loop iteration ${iterInfo} | To stop: output <promise>${nextState.completionPromise}</promise> (ONLY when TRUE)`;
+    }
+    else {
+        output.systemMessage = `Loop iteration ${iterInfo} | No completion promise — loop runs until max iterations`;
+    }
+    return { decision: "block", nextState, events, output };
+}
+export function extractPromise(text, promisePhrase) {
+    const regex = new RegExp(`<promise>\\s*${escapeRegex(promisePhrase)}\\s*</promise>`, "s");
+    return regex.test(text);
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=engine.js.map

package/dist/core/engine.js.map

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

package/dist/core/event-logger.d.ts

@@ -0,0 +1,5 @@
+import type { LoopEvent } from "./types.js";
+export declare function getTracePath(cwd?: string): string;
+export declare function logEvents(events: LoopEvent[], metadata?: Record<string, unknown>, cwd?: string): Promise<void>;
+export declare function readTrace(cwd?: string): Promise<Record<string, unknown>[]>;
+//# sourceMappingURL=event-logger.d.ts.map

package/dist/core/event-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-logger.d.ts","sourceRoot":"","sources":["../../core/event-logger.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAY5C,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAexH;AAED,wBAAsB,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAahF"}

package/dist/core/event-logger.js

@@ -0,0 +1,48 @@
+// Best-effort trace logger. Failures never affect stop-hook decisions.
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+const DEBUG = process.env.LOOPHAUS_DEBUG === "1";
+function debug(msg) {
+    if (DEBUG)
+        process.stderr.write(`[loophaus:debug] ${msg}\n`);
+}
+function isFileNotFound(err) {
+    return err != null && typeof err === "object" && ("code" in err) && (err.code === "ENOENT" || err.code === "ENOTDIR");
+}
+export function getTracePath(cwd) {
+    return join(cwd || process.cwd(), ".loophaus", "trace.jsonl");
+}
+export async function logEvents(events, metadata = {}, cwd) {
+    try {
+        const tracePath = getTracePath(cwd);
+        await mkdir(dirname(tracePath), { recursive: true });
+        const ts = new Date().toISOString();
+        const lines = events.map(e => JSON.stringify({ ts, ...metadata, ...e })).join("\n") + "\n";
+        await appendFile(tracePath, lines, "utf-8");
+    }
+    catch (err) {
+        debug(`logEvents failed: ${err.message}`);
+        // Best-effort: non-ENOENT errors are logged if DEBUG is on, but never thrown
+    }
+}
+export async function readTrace(cwd) {
+    const tracePath = getTracePath(cwd);
+    try {
+        const raw = await readFile(tracePath, "utf-8");
+        return raw.trim().split("\n").map(line => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        }).filter((v) => v !== null);
+    }
+    catch (err) {
+        if (!isFileNotFound(err)) {
+            debug(`readTrace failed: ${err.message}`);
+        }
+        return [];
+    }
+}
+//# sourceMappingURL=event-logger.js.map

package/dist/core/event-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-logger.js","sourceRoot":"","sources":["../../core/event-logger.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAI1C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG,CAAC;AAEjD,SAAS,KAAK,CAAC,GAAW;IACxB,IAAI,KAAK;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAClC,OAAO,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,CAAE,GAAwB,CAAC,IAAI,KAAK,QAAQ,IAAK,GAAwB,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;AACpK,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAmB,EAAE,WAAoC,EAAE,EAAE,GAAY;IACvG,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAErD,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAC3B,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,CAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAEpB,MAAM,UAAU,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACrD,6EAA6E;IAC/E,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAY;IAC1C,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;YACvC,IAAI,CAAC;gBAAC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,OAAO,IAAI,CAAC;YAAC,CAAC;QACpF,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,KAAK,CAAC,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}