parallax-opencode 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Master0fFate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+[![Parallax Banner](https://capsule-render.vercel.app/api?type=waving&height=200&color=6c63ff&desc=PARALLAX%20ENGINE&descAlignY=65&fontColor=ffffff&section=header&reversal=true&textBg=false&animation=fadeIn)](https://github.com/Master0fFate/parallax-opencode)
+
+# PARALLAX ENGINE
+
+**The first AI coding assistant that shows its work.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![OpenCode](https://img.shields.io/badge/OpenCode-plugin-6c63ff)](https://opencode.ai)
+[![npm](https://img.shields.io/npm/v/parallax-opencode)](https://www.npmjs.com/package/parallax-opencode)
+[![Tests](https://img.shields.io/badge/tests-30%20passing-brightgreen)]()
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)]()
+
+---
+
+## Quick Install
+
+```bash
+# One command -- installs agent, plugin, skills, and dependencies
+npx parallax-opencode
+```
+
+After install, restart OpenCode and press **Tab** in the TUI to cycle to the Parallax agent.
+
+---
+
+## What Makes Parallax Different
+
+Every AI coding tool (Cursor, Copilot, Windsurf) gives you code. None of them show you **how they got there**.
+
+Parallax captures the complete reasoning trace of every session -- the ambiguity assessment, the invariants analysis, every verification result, every decision -- and makes it visible, exportable, and replayable.
+
+Instead of "trust me, I wrote good code," Parallax says:
+
+> "Here is my complete reasoning trace. Review it. Score it. Compare it with another approach. See for yourself."
+
+### The 4 Invariants
+
+Every action is checked against four questions:
+
+| Question | Why It Matters |
+|---|---|
+| Where does state live? | Ownership & truth, consistency, blast radius |
+| Where does feedback live? | Observability, debugging, monitoring |
+| What breaks if I delete this? | Coupling & fragility, safe refactoring |
+| When does timing matter? | Async & ordering, race conditions, correctness |
+
+### The Coherence Score
+
+After every session, Parallax computes an evidence-based quality score (0-100):
+
+- **Protocol Coverage (30%)** -- Were all 5 protocol phases completed?
+- **Verification Integrity (35%)** -- Pass rate on first attempt?
+- **Edge Case Coverage (20%)** -- How many edge categories were analyzed?
+- **Timing Discipline (15%)** -- Were phases in correct order?
+
+Track your scores over time and see improvement:
+
+```bash
+parallax trace trend
+```
+
+### The Trace Protocol
+
+Every session produces a structured JSON trace file:
+
+```bash
+parallax trace list
+parallax trace show <session-id>
+parallax trace score <session-id>
+```
+
+Traces are stored in `.parallax/traces/` and can be attached to PRs, bug reports, or shared for review.
+
+### The Friction Loop
+
+1. After every write, Parallax auto-verifies (debounced)
+2. 3 retries before blocking further writes
+3. Parses verification output and reports specific failures
+4. Only the friction loop enforces quality -- the rest is instrumentation
+
+---
+
+## Comparison
+
+| Feature | Plain OpenCode | Cursor | Copilot | Parallax |
+|---|---|---|---|---|
+| Structured reasoning trace | No | No | No | **Yes** |
+| Exportable session history | No | No | No | **Yes** |
+| Evidence-based quality score | No | No | No | **Yes** |
+| Protocol enforcement | No | No | No | **Yes** |
+| Mode switching (plan/build/debug) | No | No | No | **Yes** |
+| CLI for trace analysis | No | No | No | **Yes** |
+
+---
+
+## Architecture
+
+```
+Parallax Agent (system prompt)
+  |
+  +-- Plugin hooks
+  |     event              --> track session ID
+  |     tool.execute.before --> block writes if friction exhausted
+  |     tool.execute.after --> debounced auto-verify + trace recording
+  |     system.transform   --> inject protocol status + mode skill
+  |     session.compacting --> preserve state + export trace
+  |
+  +-- Custom tools (7)
+  |     parallax_verify          auto-verify after writes
+  |     parallax_analyze         multi-perspective analysis
+  |     parallax_checkin         mark protocol step complete
+  |     parallax_plan            switch to PLAN mode
+  |     parallax_build           switch to BUILD mode
+  |     parallax_debug           switch to DEBUG mode
+  |     parallax_trace_export    export session trace to file
+  |
+  +-- CLI (parallax)
+        init                    create .parallax/ directory
+        trace list              list all session traces
+        trace show <id>         show trace details
+        trace score <id>        show coherence score
+        trace export <id>       export trace to JSON
+        trace trend             show score trend
+```
+
+### Three Modes
+
+| Mode | Tool | When |
+|---|---|---|
+| **PLAN** | `parallax_plan` | Vague requirements, before writing code |
+| **BUILD** | `parallax_build` | Executing, writing code (default) |
+| **DEBUG** | `parallax_debug` | Post-build quality and security audit |
+
+---
+
+## Manual Install (no npm)
+
+```bash
+# Copy files directly
+cp dist-standalone/parallax-engine.js ~/.config/opencode/plugins/
+cp agents/parallax.md ~/.config/opencode/agents/
+cp -r skills/parallax       ~/.config/opencode/skills/
+cp -r skills/parallax-plan  ~/.config/opencode/skills/
+cp -r skills/parallax-debug ~/.config/opencode/skills/
+
+# Install runtime dependency
+cd ~/.config/opencode && npm init -y && npm install @opencode-ai/plugin
+```
+
+---
+
+## Project Status
+
+**Current phase: v0.2.0** -- Foundation + Trace Protocol
+
+| Phase | Status | What |
+|---|---|---|
+| 0: Honest Foundation | Complete | MIT license, TS consolidation, 30 tests |
+| 1: Trace Protocol | Complete | Trace recording, export, CLI, coherence score |
+| 2: Quality Scoring | Complete | Score formula, trend tracking |
+| 3: Git Integration | Planned | Commit trace links, PR-ready reports |
+| 4: GitHub Excellence | In progress | README, CI/CD, docs |
+
+---
+
+## Commands
+
+### Plugin Tools (in OpenCode)
+
+```
+parallax_verify              Run project verification
+parallax_analyze {topic}     Structured multi-perspective analysis
+parallax_checkin {step}      Mark protocol step complete
+parallax_plan                Switch to PLAN mode
+parallax_build               Switch to BUILD mode
+parallax_debug               Switch to DEBUG mode
+parallax_trace_export        Export session trace to JSON
+```
+
+### CLI (terminal)
+
+```
+parallax init                    Create .parallax/ directory
+parallax trace list              List all traces
+parallax trace show <id>         Show trace details
+parallax trace score <id>        Show coherence score breakdown
+parallax trace export <id>       Export trace as pretty JSON
+parallax trace trend             Show score trend over time
+```
+
+---
+
+## Files
+
+```
+parallax_plugin/
+  agents/parallax.md            # Primary agent definition
+  src/plugin.ts                 # Canonical plugin (TypeScript)
+  src/types.ts                  # Shared type definitions
+  src/detect.ts                 # Project detection
+  src/trace.ts                  # Trace recording and export
+  src/score.ts                  # Coherence score computation
+  src/cli.ts                    # CLI entry point
+  src/tests/                    # 30 tests across 5 files
+  dist/                         # Compiled output
+  dist-standalone/              # Standalone plugin file
+  skills/                       # Protocol skills
+  scripts/                      # Install and publish scripts
+  package.json                  # npm package metadata
+  LICENSE                       # MIT
+```
+
+---
+
+## License
+
+MIT &copy; [@Master0fFate](https://github.com/Master0fFate)

package/agents/parallax.md

@@ -0,0 +1,100 @@
+---
+name: Parallax
+description: "PARALLAX ENGINE: Multi-perspective AI coding agent with friction-loop verification, the 4 invariants framework, and parallax planning protocol. Views every problem from every angle before acting. Best for complex engineering work requiring depth and correctness."
+mode: primary
+color: "#6c63ff"
+permission:
+  edit: allow
+  bash: ask
+  read: allow
+  grep: allow
+  glob: allow
+  list: allow
+  webfetch: allow
+  todowrite: allow
+---
+
+You are PARALLAX -- a systems thinking partner for experienced developers.
+
+## CORE DIRECTIVE
+
+YOU MUST follow the Parallax Engine protocol for EVERY task in order. The plugin tracks compliance and will block writes if critical steps are skipped.
+
+## MANDATORY PROTOCOL -- Follow in order for EVERY task
+
+### STEP 1: AMBIGUITY CHECK [REQUIRED - FIRST THING]
+Output your ambiguity assessment BEFORE anything else:
+- HIGH (vague/conceptual): User MUST ask 3+ clarifying questions. Do NOT proceed until ambiguity resolved.
+- MEDIUM (some gaps): Ask targeted questions. If you must assume an unstated pattern, it's MEDIUM.
+- LOW (clear/specific): Verify quickly and proceed. Trivial changes skip to Step 4.
+
+CONSEQUENCE: Plugin will block writes if this step is skipped.
+
+### STEP 2: 4 INVARIANTS [REQUIRED - BEFORE ANY CODE]
+State each answer explicitly:
+| Question | Your answer |
+|---|---|
+| Where does state live? | ownership & truth |
+| Where does feedback live? | observability |
+| What breaks if I delete this? | coupling & fragility |
+| When does timing matter? | async & correctness |
+
+### STEP 3: VERIFICATION GATE [REQUIRED - BEFORE FIRST WRITE]
+Check every box. Flag any "no" as a risk:
+- [ ] State ownership and consistency clear?
+- [ ] Feedback / observability in place?
+- [ ] Blast radius understood?
+- [ ] Timing & ordering safe?
+- [ ] Follows existing patterns (or intentionally breaks them)?
+- [ ] Security / obvious risks addressed?
+
+### STEP 4: EXECUTE
+Write code. Use parallax_verify after writes. Fix failures. Do NOT work around the plugin.
+
+### STEP 5: COMMIT DECISION [REQUIRED]
+State one:
+- Full Coherence -- Ship complete solution
+- Pragmatic Partial -- Ship core + flag deferred items
+- Hold + Clarify -- Critical gaps remain
+- User Override -- "Ship it" = proceed with risks flagged
+
+### STEP 6: SUMMARIZE [REQUIRED]
+After finishing, output:
+- What was built
+- Edge cases handled
+- Verification passed?
+- Remaining concerns
+
+## MODES
+
+Use these tools to load specialized skills for each phase:
+
+| Mode | Tool | Phase | Loads |
+|---|---|---|---|
+| PLAN | parallax_plan | Steps 1-3 | Precision Architect |
+| BUILD | parallax_build | Step 4 | Standard protocol (default) |
+| DEBUG | parallax_debug | Step 6 | Universal Auditor |
+
+## TOOLS
+
+- parallax_verify -- Run project verification (use instead of bash)
+- parallax_analyze -- Structured multi-perspective analysis
+- parallax_plan -- Switch to PLAN mode
+- parallax_build -- Switch to BUILD mode
+- parallax_debug -- Switch to DEBUG mode
+- parallax_checkin -- Mark a protocol step complete (plugin tracks this)
+- parallax_trace_export -- Export session trace to JSON file (includes coherence score)
+
+## RED LINES (Stop Immediately)
+
+- Unclear state ownership
+- Unknown blast radius
+- Timing / race condition hazards
+- Security issues
+- Creating significant complexity debt
+- Unknown unknowns on non-trivial changes
+
+## OUTPUT RULES
+
+- Terminal environment. No markdown rendering. No emojis. Plain ASCII.
+- ALL CAPS for emphasis, [brackets] for labels, indentation for structure.

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * PARALLAX ENGINE -- CLI Entry Point
+ *
+ * Provides the `parallax` CLI command for trace management, scoring,
+ * and project initialization.
+ *
+ * Commands:
+ *   parallax init              - Create .parallax/ config directory
+ *   parallax trace list        - List all traces
+ *   parallax trace show <id>   - Show a trace
+ *   parallax trace score <id>  - Show coherence score breakdown
+ *   parallax trace export <id> - Export trace to JSON
+ *   parallax trace trend       - Show score trend
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+export declare function main(): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * PARALLAX ENGINE -- CLI Entry Point
+ *
+ * Provides the `parallax` CLI command for trace management, scoring,
+ * and project initialization.
+ *
+ * Commands:
+ *   parallax init              - Create .parallax/ config directory
+ *   parallax trace list        - List all traces
+ *   parallax trace show <id>   - Show a trace
+ *   parallax trace score <id>  - Show coherence score breakdown
+ *   parallax trace export <id> - Export trace to JSON
+ *   parallax trace trend       - Show score trend
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { listTraceFiles, loadTrace, exportTrace, } from "./trace";
+import { computeCoherenceScore, formatScoreBreakdown, readScoreHistory, sparkline, scoreToGrade, recordScore, } from "./score";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const PARALLAX_DIR = ".parallax";
+// ---------------------------------------------------------------------------
+// Help & version
+// ---------------------------------------------------------------------------
+function showHelp() {
+    console.log(`Parallax Engine CLI v0.2.0`);
+    console.log(``);
+    console.log(`Usage: parallax <command> [options]`);
+    console.log(``);
+    console.log(`Commands:`);
+    console.log(`  init                  Create .parallax/ directory with defaults`);
+    console.log(`  trace list            List all traces`);
+    console.log(`  trace show <id>       Show full trace`);
+    console.log(`  trace score <id>      Show coherence score`);
+    console.log(`  trace export <id>     Export trace to JSON file`);
+    console.log(`  trace trend           Show score trend over time`);
+    console.log(`  help                  Show this help`);
+}
+function showVersion() {
+    console.log("0.2.0");
+}
+// ---------------------------------------------------------------------------
+// Command implementations
+// ---------------------------------------------------------------------------
+async function cmdInit() {
+    const dir = join(process.cwd(), PARALLAX_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        console.log(`Created ${PARALLAX_DIR}/`);
+    }
+    else {
+        console.log(`${PARALLAX_DIR}/ already exists`);
+    }
+    const gitignorePath = join(dir, ".gitignore");
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, "*\n", "utf8");
+        console.log(`Created ${PARALLAX_DIR}/.gitignore`);
+    }
+    // Create traces subdirectory
+    const tracesDir = join(dir, "traces");
+    if (!existsSync(tracesDir)) {
+        mkdirSync(tracesDir, { recursive: true });
+        console.log(`Created ${PARALLAX_DIR}/traces/`);
+    }
+    console.log(`\nParallax initialized. Traces will be stored in ${PARALLAX_DIR}/traces/`);
+    return 0;
+}
+async function cmdTraceList() {
+    const files = listTraceFiles();
+    if (files.length === 0) {
+        console.log("No traces found.");
+        return 0;
+    }
+    console.log(`Found ${files.length} trace(s):\n`);
+    for (const f of files) {
+        const trace = loadTrace(f.sessionId);
+        const score = trace ? computeCoherenceScore(trace) : null;
+        const phases = trace ? trace.phases.length : 0;
+        const writes = trace ? trace.writes.length : 0;
+        const scoreStr = score ? `${score.total}/100 (${scoreToGrade(score.total)})` : "N/A";
+        console.log(`  ${f.sessionId.padEnd(20)}  ` +
+            `${writes} writes, ${phases} phases  ` +
+            `Score: ${scoreStr}`);
+    }
+    return 0;
+}
+async function cmdTraceShow(id) {
+    const trace = loadTrace(id);
+    if (!trace) {
+        console.error(`Trace not found: ${id}`);
+        return 1;
+    }
+    console.log(`Session: ${trace.session.id}`);
+    console.log(`Started: ${trace.session.startedAt}`);
+    console.log(`Ended:   ${trace.session.endedAt || "in progress"}`);
+    console.log(`Project: ${trace.session.project || "unknown"}`);
+    console.log(`Type:    ${trace.session.projectType || "unknown"}`);
+    console.log(``);
+    console.log(`Phases (${trace.phases.length}):`);
+    for (const p of trace.phases) {
+        console.log(`  [${p.phase}] ${p.timestamp}`);
+        if (Object.keys(p.data).length > 0) {
+            console.log(`    Data: ${JSON.stringify(p.data)}`);
+        }
+    }
+    console.log(``);
+    console.log(`Writes (${trace.writes.length}):`);
+    for (const w of trace.writes) {
+        const status = w.verification === "pass" ? "OK" : w.verification === "fail" ? "FAIL" : w.verification;
+        console.log(`  [${status}] ${w.file} (retries: ${3 - w.frictionRetriesLeft})`);
+    }
+    return 0;
+}
+async function cmdTraceScore(id) {
+    const trace = loadTrace(id);
+    if (!trace) {
+        console.error(`Trace not found: ${id}`);
+        return 1;
+    }
+    const breakdown = computeCoherenceScore(trace);
+    console.log(formatScoreBreakdown(breakdown));
+    // Optionally record the score
+    const entry = {
+        sessionId: id,
+        date: new Date().toISOString(),
+        score: breakdown.total,
+        project: trace.session.project,
+    };
+    recordScore(entry);
+    return 0;
+}
+async function cmdTraceExport(id) {
+    const trace = loadTrace(id);
+    if (!trace) {
+        console.error(`Trace not found: ${id}`);
+        return 1;
+    }
+    const filePath = exportTrace(id, true);
+    console.log(`Trace exported to: ${filePath}`);
+    return 0;
+}
+async function cmdTraceTrend() {
+    const history = readScoreHistory();
+    if (history.length === 0) {
+        console.log("No score history found.");
+        return 0;
+    }
+    const scores = history.map((e) => e.score);
+    const line = sparkline(scores);
+    const avg = Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+    console.log(`Score trend (${history.length} entries, avg: ${avg}/100):`);
+    console.log(`  ${line}`);
+    console.log(``);
+    for (const entry of history) {
+        const date = entry.date.slice(0, 10);
+        console.log(`  ${date}  ${entry.score}/100  [${entry.sessionId.slice(0, 8)}]  ${entry.project || ""}`);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Command routing
+// ---------------------------------------------------------------------------
+export async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        showHelp();
+        return 0;
+    }
+    const cmd = args[0];
+    switch (cmd) {
+        case "help":
+            showHelp();
+            return 0;
+        case "version":
+        case "--version":
+        case "-v":
+            showVersion();
+            return 0;
+        case "init":
+            return cmdInit();
+        case "trace": {
+            const sub = args[1];
+            switch (sub) {
+                case "list":
+                    return cmdTraceList();
+                case "show":
+                    if (!args[2]) {
+                        console.error("Usage: parallax trace show <session-id>");
+                        return 1;
+                    }
+                    return cmdTraceShow(args[2]);
+                case "score":
+                    if (!args[2]) {
+                        console.error("Usage: parallax trace score <session-id>");
+                        return 1;
+                    }
+                    return cmdTraceScore(args[2]);
+                case "export":
+                    if (!args[2]) {
+                        console.error("Usage: parallax trace export <session-id>");
+                        return 1;
+                    }
+                    return cmdTraceExport(args[2]);
+                case "trend":
+                    return cmdTraceTrend();
+                default:
+                    console.error(`Unknown trace command: ${sub}`);
+                    console.error("Usage: parallax trace <list|show|score|export|trend>");
+                    return 1;
+            }
+        }
+        default:
+            console.error(`Unknown command: ${cmd}`);
+            console.error("Run 'parallax help' for usage.");
+            return 1;
+    }
+}
+// Run the CLI if this is the entry point
+// Detected by checking if process.argv[1] ends with cli.ts or cli.js
+const isMain = process.argv[1]?.endsWith("cli.ts") ||
+    process.argv[1]?.endsWith("cli.js") ||
+    process.argv[1]?.endsWith("parallax-engine") ||
+    process.argv[1]?.endsWith("parallax-engine.js");
+if (isMain) {
+    main()
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/detect.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PARALLAX ENGINE -- Project Detection
+ *
+ * Detects the project type in the current working directory and returns
+ * the appropriate verification command.
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+import type { ProjectType, VerifyResult } from "./types";
+/**
+ * Detect the project type based on files present in the current directory.
+ */
+export declare function detectProject(): ProjectType;
+/**
+ * Get the shell command string for verification based on project type.
+ */
+export declare function getVerifyCommand(): string | null;
+/**
+ * Run the verification command synchronously using Bun.spawnSync.
+ * Returns null if no known project type is detected.
+ */
+export declare function runVerify(): VerifyResult | null;

package/dist/detect.js

@@ -0,0 +1,65 @@
+/**
+ * PARALLAX ENGINE -- Project Detection
+ *
+ * Detects the project type in the current working directory and returns
+ * the appropriate verification command.
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+import { existsSync, statSync } from "fs";
+/**
+ * Detect the project type based on files present in the current directory.
+ */
+export function detectProject() {
+    try {
+        if (existsSync("Cargo.toml"))
+            return "cargo";
+        if (existsSync("package.json")) {
+            if (existsSync("node_modules") && statSync("node_modules").isDirectory()) {
+                if (existsSync("tsconfig.json"))
+                    return "tsc";
+                return "lint";
+            }
+        }
+        if (existsSync("pyproject.toml") || existsSync("requirements.txt"))
+            return "python";
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the shell command string for verification based on project type.
+ */
+export function getVerifyCommand() {
+    switch (detectProject()) {
+        case "cargo": return "cargo check --color=never --all-targets --all-features 2>&1";
+        case "tsc": return "npx tsc --noEmit 2>&1";
+        case "lint": return "npm run lint 2>&1";
+        case "python": return "python -m compileall -q . 2>&1";
+        default: return null;
+    }
+}
+/**
+ * Run the verification command synchronously using Bun.spawnSync.
+ * Returns null if no known project type is detected.
+ */
+export function runVerify() {
+    try {
+        const cmd = getVerifyCommand();
+        if (!cmd)
+            return null;
+        const shell = process.platform === "win32" ? "cmd" : "sh";
+        const flag = process.platform === "win32" ? "/C" : "-c";
+        const proc = Bun.spawnSync([shell, flag, cmd], { cwd: process.cwd() });
+        const stdout = proc.stdout.toString();
+        const stderr = proc.stderr.toString();
+        const combined = stderr ? `${stdout}\n${stderr}` : stdout;
+        return { exitCode: proc.exitCode, stdout, stderr, combined };
+    }
+    catch (e) {
+        return { exitCode: -1, stdout: "", stderr: String(e), combined: String(e) };
+    }
+}