quacktionable 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+
+![quacktionable banner](assets/quack.png)
+
+`quacktionable` is a playful terminal tool that helps you explain a bug, survive cross-examination by judge ducks, and get a voted root-cause verdict.
+
+It is built around **GitHub Copilot CLI** as the reasoning engine.
+
+## Why this is useful
+
+Most debugging stalls because we lock onto our first theory too early.
+
+`quacktionable` forces structured skepticism:
+- take your bug narrative,
+- challenge it from multiple technical personas,
+- and produce a final, confidence-scored quackdict.
+
+## Features
+
+- Interactive intake mode with branded splash UI: `quack report`
+- Fast sample run: `quack analyze --example`
+- Flexible inputs: inline text, bug file, logs, and code paths
+- Live terminal progress animation while the tribunal is thinking
+- Terminal-friendly and JSON output modes
+- Copilot CLI health check with `quack doctor`
+
+## Requirements
+
+- Node.js `>=18.18`
+- GitHub Copilot CLI installed and authenticated
+
+## Install
+
+```bash
+npm install -g quacktionable
+```
+
+If you prefer `npx` (no global install):
+
+```bash
+npx quacktionable doctor
+```
+
+## Quick start
+
+```bash
+quack doctor
+quack report
+```
+
+Or run a one-command demo:
+
+```bash
+quack analyze --example
+```
+
+## Local development
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+## Command reference
+
+- `quack doctor` — verifies Copilot CLI availability and prompt roundtrip
+- `quack report` — interactive guided bug intake + analysis
+- `quack analyze --example` — run with built-in sample bug/logs
+- `quack analyze --bug "..." --log ... --path "a.ts,b.ts"` — explicit inputs
+- `quack analyze --bug-file bug.txt --log app.log` — file-first workflow
+- `quack analyze --json` — JSON output for scripts/automation
+
+### Analyze flags
+
+- `--example`: auto-loads `examples/bug.txt` and `examples/logs.txt`
+- `--bug`: bug narrative text
+- `--bug-file`: path to bug narrative file
+- `--log`: raw log text or a log file path
+- `--paths` / `--path`: comma-separated code paths for extra context
+- `--rounds`: tribunal rounds per duck (1-5, default 2)
+- `--json`: emit machine-readable JSON only
+
+## What users see in terminal
+
+```text
+🦆⚖️ Rubber Duck Tribunal (Court is now in session)
+🎭 Opening statement: no bug survives cross-examination.
+🆔 Session: 5a077c56-b0fe-4f18-a26e-1a7408d56273
+🤖 Engine: gpt-5
+
+📝 Bug Tale
+- 🐛 Users intermittently get a 500 error...
+
+🗳️ Judge Duck Votes
+- 🦆 Detective Quackson: ...
+
+🏛️ Final Quackdict
+- 🎯 root cause: ...
+- 🔥 confidence: 92%
+```
+
+## Architecture
+
+- Input parsing (`--bug`, `--bug-file`, stdin, `--log`, `--path[s]`)
+- Evidence bundling + signal extraction from logs
+- Copilot CLI cross-exam prompt + per-duck judgment prompts
+- Vote aggregation and confidence scoring
+- Pretty terminal renderer + JSON renderer
+
+## Development
+
+```bash
+npm run lint
+npm run build
+npm run test
+```

package/bin/quack

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli.js');

package/bin/quacktionable

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli.js');

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_process_1 = __importDefault(require("node:process"));
+const promises_2 = require("node:readline/promises");
+const gradient_string_1 = __importDefault(require("gradient-string"));
+const errors_1 = require("./core/errors");
+const copilotCli_1 = require("./copilot/copilotCli");
+const parsePrompt_1 = require("./input/parsePrompt");
+const collectRepoContext_1 = require("./input/collectRepoContext");
+const jsonRenderer_1 = require("./output/jsonRenderer");
+const terminalRenderer_1 = require("./output/terminalRenderer");
+const defaultDucks_1 = require("./tribunal/defaultDucks");
+const runTribunal_1 = require("./tribunal/runTribunal");
+const DEFAULT_BUG_FILE = 'examples/bug.txt';
+const DEFAULT_LOG_FILE = 'examples/logs.txt';
+const DEFAULT_EXAMPLE_PATHS = ['src/cli.ts', 'src/tribunal/runTribunal.ts'];
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const hasFlag = (args, flag) => {
+    return args.includes(flag);
+};
+const getFlagValue = (args, flag) => {
+    const index = args.indexOf(flag);
+    if (index === -1 || index + 1 >= args.length) {
+        return undefined;
+    }
+    return args[index + 1];
+};
+const parsePaths = (raw) => {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+};
+const readTextFileIfExists = async (path) => {
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return undefined;
+    }
+    return (0, promises_1.readFile)(path, 'utf8');
+};
+const readLogInput = async (raw) => {
+    if (!raw) {
+        return undefined;
+    }
+    if ((0, node_fs_1.existsSync)(raw)) {
+        return (0, promises_1.readFile)(raw, 'utf8');
+    }
+    return raw;
+};
+const readStdinText = async () => {
+    if (node_process_1.default.stdin.isTTY) {
+        return undefined;
+    }
+    const chunks = [];
+    for await (const chunk of node_process_1.default.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    const text = Buffer.concat(chunks).toString('utf8').trim();
+    return text.length > 0 ? text : undefined;
+};
+const usage = () => {
+    return [
+        'Usage:',
+        '  quack doctor',
+        '  quack report',
+        '  quack analyze --example',
+        '  quack analyze --bug "..." [--log "..."] [--paths "a.ts,b.ts"] [--json] [--rounds 2]',
+        '  quack analyze --bug-file notes.txt [--log examples/logs.txt]',
+        '',
+        'Notes:',
+        '  quack report starts an interactive guided bug intake.',
+        '  --example auto-loads examples/bug.txt and examples/logs.txt.',
+        '  If --bug is omitted and examples/bug.txt exists, it is used automatically.',
+        '  --bug-file reads bug narrative from a file.',
+        '  --log accepts raw text or a file path.',
+        '  --paths accepts comma-separated file paths.',
+        '  Copilot CLI is required at runtime.',
+        '  Keep calm and let the ducks do the judging.',
+    ].join('\n');
+};
+const parseAnalyzeInput = async (args) => {
+    const useExample = hasFlag(args, '--example');
+    const bugFilePath = getFlagValue(args, '--bug-file');
+    const bugFromFlag = getFlagValue(args, '--bug');
+    const bugFromFile = bugFilePath ? await readTextFileIfExists(bugFilePath) : undefined;
+    const bugFromExample = useExample ? await readTextFileIfExists(DEFAULT_BUG_FILE) : undefined;
+    const bugFromDefault = bugFromFlag || bugFromFile || bugFromExample ? undefined : await readTextFileIfExists(DEFAULT_BUG_FILE);
+    const bugFromStdin = await readStdinText();
+    const bug = bugFromFlag ?? bugFromFile ?? bugFromStdin ?? bugFromExample ?? bugFromDefault;
+    if (!bug) {
+        throw new errors_1.QuacktionableError('Missing bug description. Use --bug, --bug-file, --example, or pipe text via stdin.');
+    }
+    const roundsRaw = getFlagValue(args, '--rounds') ?? '2';
+    const rounds = Number(roundsRaw);
+    if (!Number.isInteger(rounds) || rounds < 1 || rounds > 5) {
+        throw new errors_1.QuacktionableError('--rounds must be an integer between 1 and 5.');
+    }
+    const logFromFlag = getFlagValue(args, '--log');
+    const pathsRaw = getFlagValue(args, '--paths') ?? getFlagValue(args, '--path');
+    const parsedPaths = parsePaths(pathsRaw);
+    const logFromExample = useExample && !logFromFlag ? await readTextFileIfExists(DEFAULT_LOG_FILE) : undefined;
+    const defaultPaths = useExample ? DEFAULT_EXAMPLE_PATHS : [];
+    return {
+        bug,
+        logText: (await readLogInput(logFromFlag)) ?? logFromExample,
+        paths: parsedPaths.length > 0 ? parsedPaths : defaultPaths,
+        jsonOutput: hasFlag(args, '--json'),
+        rounds,
+    };
+};
+const normalizeYes = (value) => {
+    return /^(y|yes|true|1)$/i.test(value.trim());
+};
+const ansi = {
+    reset: '\u001b[0m',
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    cyan: '\u001b[36m',
+    magenta: '\u001b[35m',
+    yellow: '\u001b[33m',
+    green: '\u001b[32m',
+};
+const colorize = (text, color, weight = '') => {
+    return `${weight}${color}${text}${ansi.reset}`;
+};
+const quackGradient = (0, gradient_string_1.default)(['#22d3ee', '#8b5cf6', '#f472b6']);
+const renderInteractiveSplash = () => {
+    const logoRaw = [
+        ' ██████╗ ██╗   ██╗ █████╗  ██████╗██╗  ██╗',
+        '██╔═══██╗██║   ██║██╔══██╗██╔════╝██║ ██╔╝',
+        '██║   ██║██║   ██║███████║██║     █████╔╝ ',
+        '██║▄▄ ██║██║   ██║██╔══██║██║     ██╔═██╗ ',
+        '╚██████╔╝╚██████╔╝██║  ██║╚██████╗██║  ██╗',
+        ' ╚══▀▀═╝  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝',
+    ].join('\n');
+    const logo = quackGradient.multiline(logoRaw);
+    const subtitleBox = [
+        '┌───────────────────────────────────────────────────────────────┐',
+        '│ 🦆 Rubber Duck Tribunal · Interactive Intake Console          │',
+        '│ Explain the bug. The duck bench handles the drama.           │',
+        '└───────────────────────────────────────────────────────────────┘',
+    ].join('\n');
+    const statusLines = [
+        `${colorize('⚖️  Court mode', ansi.magenta, ansi.bold)}: ${colorize('ENABLED', ansi.green, ansi.bold)}`,
+        `${colorize('🔍 Evidence mode', ansi.magenta, ansi.bold)}: ${colorize('TRACKING', ansi.green, ansi.bold)}`,
+        `${colorize('🎭 Vibes', ansi.magenta, ansi.bold)}: ${colorize('dramatic, but factual', ansi.yellow)}`,
+    ].join('\n');
+    return [
+        '',
+        logo,
+        '',
+        subtitleBox,
+        '',
+        statusLines,
+        '',
+    ].join('\n');
+};
+const createProgressReporter = (enabled) => {
+    if (!enabled) {
+        return {
+            update: () => undefined,
+            success: () => undefined,
+            fail: () => undefined,
+        };
+    }
+    if (!node_process_1.default.stderr.isTTY) {
+        return {
+            update: (message) => {
+                node_process_1.default.stderr.write(`⏳ ${message}\n`);
+            },
+            success: (message) => {
+                node_process_1.default.stderr.write(`✅ ${message}\n`);
+            },
+            fail: (message) => {
+                node_process_1.default.stderr.write(`❌ ${message}\n`);
+            },
+        };
+    }
+    let active = false;
+    let frameIndex = 0;
+    let currentMessage = 'Warming up the duck bench...';
+    let intervalId;
+    const render = () => {
+        const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
+        frameIndex += 1;
+        node_process_1.default.stderr.write(`\r${frame} ${currentMessage}   `);
+    };
+    const start = () => {
+        if (active) {
+            return;
+        }
+        active = true;
+        render();
+        intervalId = setInterval(render, 80);
+    };
+    const stop = (icon, message) => {
+        if (intervalId) {
+            clearInterval(intervalId);
+            intervalId = undefined;
+        }
+        if (active) {
+            node_process_1.default.stderr.write(`\r${icon} ${message}   \n`);
+            active = false;
+            return;
+        }
+        node_process_1.default.stderr.write(`${icon} ${message}\n`);
+    };
+    return {
+        update: (message) => {
+            currentMessage = message;
+            start();
+        },
+        success: (message) => {
+            stop('✅', message);
+        },
+        fail: (message) => {
+            stop('❌', message);
+        },
+    };
+};
+const runAnalyzeWithInput = async (input) => {
+    const showProgress = !input.jsonOutput;
+    const reporter = createProgressReporter(showProgress);
+    const progress = reporter.update;
+    try {
+        progress('Gathering bug clues...');
+        const repoContext = await (0, collectRepoContext_1.collectRepoContext)(input.paths);
+        const report = {
+            summary: input.bug,
+            logs: input.logText,
+            filePaths: input.paths,
+            repoContext,
+        };
+        progress('Bundling evidence for the duck tribunal...');
+        const evidence = (0, parsePrompt_1.buildEvidenceBundle)(report);
+        const session = await (0, runTribunal_1.runTribunal)(evidence, report, {
+            ducks: defaultDucks_1.DEFAULT_DUCKS,
+            rounds: input.rounds,
+            requireCopilotCli: true,
+            onProgress: progress,
+        });
+        progress('Printing final quackdict...');
+        const output = input.jsonOutput ? (0, jsonRenderer_1.renderJson)(session) : (0, terminalRenderer_1.renderTerminal)(session);
+        node_process_1.default.stdout.write(`${output}\n`);
+        reporter.success('Tribunal complete. Verdict delivered.');
+    }
+    catch (error) {
+        reporter.fail('Tribunal interrupted before final verdict.');
+        throw error;
+    }
+};
+const runAnalyze = async (args) => {
+    const input = await parseAnalyzeInput(args);
+    await runAnalyzeWithInput(input);
+};
+const runReport = async () => {
+    const rl = (0, promises_2.createInterface)({
+        input: node_process_1.default.stdin,
+        output: node_process_1.default.stdout,
+    });
+    node_process_1.default.stdout.write(`${renderInteractiveSplash()}\n\n`);
+    node_process_1.default.stdout.write('🦆 Welcome, debugger. Let us file this bug with dramatic flair and technical rigor.\n\n');
+    try {
+        let bug = '';
+        while (!bug.trim()) {
+            bug = await rl.question('1) 📝 Describe the bug in plain language: ');
+            if (!bug.trim()) {
+                node_process_1.default.stdout.write('   🕵️ The ducks need at least one clue. Please add a short description.\n');
+            }
+        }
+        const logInput = await rl.question('2) 📜 Optional log path or raw log line (enter to skip): ');
+        const pathsInput = await rl.question('3) 📂 Optional code paths (comma-separated, enter to skip): ');
+        const roundsInput = await rl.question('4) 🔁 Cross-exam rounds per duck [2]: ');
+        const jsonInput = await rl.question('5) 🧾 Output JSON only? [y/N]: ');
+        const roundsRaw = roundsInput.trim() || '2';
+        const rounds = Number(roundsRaw);
+        if (!Number.isInteger(rounds) || rounds < 1 || rounds > 5) {
+            throw new errors_1.QuacktionableError('Rounds must be an integer between 1 and 5.');
+        }
+        const input = {
+            bug: bug.trim(),
+            logText: await readLogInput(logInput.trim() || undefined),
+            paths: parsePaths(pathsInput.trim() || undefined),
+            jsonOutput: normalizeYes(jsonInput),
+            rounds,
+        };
+        node_process_1.default.stdout.write('\n🚀 Launching tribunal proceedings...\n\n');
+        await runAnalyzeWithInput(input);
+    }
+    finally {
+        rl.close();
+    }
+};
+const runDoctor = async () => {
+    const result = await (0, copilotCli_1.runCopilotDoctor)();
+    node_process_1.default.stdout.write('quack doctor 🩺🦆\n');
+    node_process_1.default.stdout.write(`- cliAvailable: ${result.cliAvailable}\n`);
+    node_process_1.default.stdout.write(`- promptRoundTripOk: ${result.promptRoundTripOk}\n`);
+    node_process_1.default.stdout.write(`- details: ${result.details}\n`);
+};
+const main = async () => {
+    const [, , command, ...args] = node_process_1.default.argv;
+    if (!command || command === '--help' || command === '-h') {
+        node_process_1.default.stdout.write(`${usage()}\n`);
+        return;
+    }
+    if (command === 'doctor') {
+        await runDoctor();
+        return;
+    }
+    if (command === 'report') {
+        await runReport();
+        return;
+    }
+    if (command !== 'analyze') {
+        throw new errors_1.QuacktionableError(`Unknown command: ${command}`);
+    }
+    await runAnalyze(args);
+};
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    node_process_1.default.stderr.write(`quacktionable error: ${message}\n`);
+    node_process_1.default.exitCode = 1;
+});

package/dist/copilot/copilotCli.d.ts

@@ -0,0 +1,11 @@
+import type { EvidenceBundle } from '../core/types';
+export declare const assertCopilotCliAvailable: () => void;
+export declare const runCopilotCrossExam: (evidence: EvidenceBundle) => Promise<string>;
+export declare const runCopilotDuckJudgment: (prompt: string) => Promise<string>;
+export interface CopilotDoctorResult {
+    cliAvailable: boolean;
+    promptRoundTripOk: boolean;
+    details: string;
+}
+export declare const runCopilotDoctor: () => Promise<CopilotDoctorResult>;
+export declare const resolveCopilotModelLabel: () => Promise<string>;

package/dist/copilot/copilotCli.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCopilotModelLabel = exports.runCopilotDoctor = exports.runCopilotDuckJudgment = exports.runCopilotCrossExam = exports.assertCopilotCliAvailable = void 0;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const errors_1 = require("../core/errors");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const getCopilotCommand = () => {
+    return process.env.COPILOT_CLI_COMMAND ?? 'copilot';
+};
+const assertCopilotCliAvailable = () => {
+    const command = getCopilotCommand();
+    const check = (0, node_child_process_1.spawnSync)(command, ['--version'], { stdio: 'ignore' });
+    if (check.status !== 0) {
+        throw new errors_1.MissingDependencyError('GitHub Copilot CLI', `Install it and ensure '${command}' is available on PATH.`);
+    }
+};
+exports.assertCopilotCliAvailable = assertCopilotCliAvailable;
+const runCopilotPrompt = async (prompt) => {
+    const command = getCopilotCommand();
+    try {
+        const { stdout } = await execFileAsync(command, ['-p', prompt], {
+            maxBuffer: 1024 * 1024,
+        });
+        const text = stdout.trim();
+        return text || 'No output returned by Copilot CLI.';
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new errors_1.QuacktionableError(`Copilot CLI execution failed: ${message}`);
+    }
+};
+const runCopilotCrossExam = async (evidence) => {
+    const prompt = [
+        'You are an external tribunal observer with sharp wit and sharp debugging instincts.',
+        'Given bug evidence, provide up to 5 high-impact cross-exam questions and likely weak assumptions.',
+        'Format as concise bullet points with light humor, but keep technical accuracy strict.',
+        '',
+        `Narrative: ${evidence.narrative || '<none>'}`,
+        `Logs: ${evidence.logs || '<none>'}`,
+        `Repo context: ${evidence.repoContext || '<none>'}`,
+    ].join('\n');
+    return runCopilotPrompt(prompt);
+};
+exports.runCopilotCrossExam = runCopilotCrossExam;
+const runCopilotDuckJudgment = async (prompt) => {
+    return runCopilotPrompt(prompt);
+};
+exports.runCopilotDuckJudgment = runCopilotDuckJudgment;
+const runCopilotDoctor = async () => {
+    (0, exports.assertCopilotCliAvailable)();
+    const probePrompt = [
+        'Health-check probe.',
+        'Reply with exactly one word: QUACK_OK',
+    ].join('\n');
+    const output = await runCopilotPrompt(probePrompt);
+    const roundTripOk = /\bQUACK_OK\b/i.test(output);
+    if (!roundTripOk) {
+        throw new errors_1.QuacktionableError(`Copilot CLI responded, but health probe token was missing. Received: ${output.slice(0, 120)}`);
+    }
+    return {
+        cliAvailable: true,
+        promptRoundTripOk: true,
+        details: 'Copilot CLI is online and beak-to-beak communication is healthy.',
+    };
+};
+exports.runCopilotDoctor = runCopilotDoctor;
+const readCopilotConfig = async () => {
+    const configDir = process.env.COPILOT_CONFIG_DIR ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.copilot');
+    const configPath = (0, node_path_1.join)(configDir, 'config.json');
+    try {
+        const raw = await (0, promises_1.readFile)(configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+};
+const resolveCopilotModelLabel = async () => {
+    if (process.env.QUACK_MODEL_LABEL) {
+        return process.env.QUACK_MODEL_LABEL;
+    }
+    const config = await readCopilotConfig();
+    if (config?.model) {
+        return config.model;
+    }
+    return 'default (configured by GitHub Copilot CLI)';
+};
+exports.resolveCopilotModelLabel = resolveCopilotModelLabel;

package/dist/core/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class QuacktionableError extends Error {
+    constructor(message: string);
+}
+export declare class MissingDependencyError extends QuacktionableError {
+    constructor(dependencyName: string, hint: string);
+}
+export declare class InvalidModelOutputError extends QuacktionableError {
+    constructor(message: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidModelOutputError = exports.MissingDependencyError = exports.QuacktionableError = void 0;
+class QuacktionableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'QuacktionableError';
+    }
+}
+exports.QuacktionableError = QuacktionableError;
+class MissingDependencyError extends QuacktionableError {
+    constructor(dependencyName, hint) {
+        super(`${dependencyName} is required: ${hint}`);
+        this.name = 'MissingDependencyError';
+    }
+}
+exports.MissingDependencyError = MissingDependencyError;
+class InvalidModelOutputError extends QuacktionableError {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidModelOutputError';
+    }
+}
+exports.InvalidModelOutputError = InvalidModelOutputError;

package/dist/core/types.d.ts

@@ -0,0 +1,63 @@
+export interface BugReport {
+    summary: string;
+    logs?: string;
+    filePaths: string[];
+    repoContext?: string;
+}
+export interface EvidenceBundle {
+    narrative: string;
+    logs: string;
+    repoContext: string;
+    extractedSignals: string[];
+}
+export interface DuckPersona {
+    id: string;
+    name: string;
+    style: string;
+    focus: string;
+}
+export interface CrossExamRound {
+    round: number;
+    question: string;
+    answer: string;
+    concern: string;
+}
+export interface Vote {
+    duckId: string;
+    duckName: string;
+    rootCause: string;
+    rationale: string;
+    confidence: number;
+    evidenceRefs: string[];
+}
+export interface Verdict {
+    rootCause: string;
+    confidence: number;
+    dissentingCauses: string[];
+    voteBreakdown: Vote[];
+    summary: string;
+    insufficientEvidence?: boolean;
+}
+export interface TribunalSession {
+    id: string;
+    createdAt: string;
+    model: string;
+    bugReport: BugReport;
+    evidence: EvidenceBundle;
+    roundsByDuck: Record<string, CrossExamRound[]>;
+    votes: Vote[];
+    verdict: Verdict;
+}
+export interface TribunalOptions {
+    ducks: DuckPersona[];
+    rounds: number;
+    requireCopilotCli: boolean;
+    onProgress?: (message: string) => void;
+}
+export interface AnalyzeInput {
+    bug: string;
+    logText?: string;
+    paths: string[];
+    jsonOutput: boolean;
+    rounds: number;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/input/collectRepoContext.d.ts

@@ -0,0 +1 @@
+export declare function collectRepoContext(paths: string[]): Promise<string>;

package/dist/input/collectRepoContext.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectRepoContext = collectRepoContext;
+const promises_1 = require("node:fs/promises");
+const MAX_FILE_CHARS = 8_000;
+async function collectRepoContext(paths) {
+    if (paths.length === 0) {
+        return '';
+    }
+    const chunks = [];
+    for (const path of paths) {
+        try {
+            const content = await (0, promises_1.readFile)(path, 'utf8');
+            const trimmed = content.length > MAX_FILE_CHARS ? `${content.slice(0, MAX_FILE_CHARS)}\n...<truncated>` : content;
+            chunks.push(`### File: ${path}\n${trimmed}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            chunks.push(`### File: ${path}\n<unreadable: ${message}>`);
+        }
+    }
+    return chunks.join('\n\n');
+}

package/dist/input/parseLogs.d.ts

@@ -0,0 +1,4 @@
+export declare const parseLogs: (logText?: string) => {
+    cleaned: string;
+    signals: string[];
+};

package/dist/input/parseLogs.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLogs = void 0;
+const parseLogs = (logText) => {
+    if (!logText) {
+        return { cleaned: '', signals: [] };
+    }
+    const cleaned = logText.trim();
+    const lines = cleaned.split(/\r?\n/);
+    const signals = lines
+        .filter((line) => /(error|exception|trace|failed|timeout|refused)/i.test(line))
+        .slice(0, 12)
+        .map((line) => line.trim());
+    return { cleaned, signals };
+};
+exports.parseLogs = parseLogs;

package/dist/input/parsePrompt.d.ts

@@ -0,0 +1,2 @@
+import type { BugReport, EvidenceBundle } from '../core/types';
+export declare const buildEvidenceBundle: (report: BugReport) => EvidenceBundle;

package/dist/input/parsePrompt.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEvidenceBundle = void 0;
+const parseLogs_1 = require("./parseLogs");
+const buildEvidenceBundle = (report) => {
+    const { cleaned, signals } = (0, parseLogs_1.parseLogs)(report.logs);
+    return {
+        narrative: report.summary.trim(),
+        logs: cleaned,
+        repoContext: report.repoContext ?? '',
+        extractedSignals: signals,
+    };
+};
+exports.buildEvidenceBundle = buildEvidenceBundle;

package/dist/llm/ollamaClient.d.ts

@@ -0,0 +1 @@
+export declare function runOllamaChat(prompt: string, model: string): Promise<string>;

package/dist/llm/ollamaClient.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runOllamaChat = runOllamaChat;
+const errors_1 = require("../core/errors");
+async function runOllamaChat(prompt, model) {
+    const baseUrl = process.env.OLLAMA_BASE_URL ?? 'http://127.0.0.1:11434';
+    const response = await fetch(`${baseUrl}/api/chat`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            model,
+            stream: false,
+            messages: [
+                {
+                    role: 'user',
+                    content: prompt,
+                },
+            ],
+            options: {
+                temperature: 0.2,
+            },
+        }),
+    });
+    if (!response.ok) {
+        throw new errors_1.QuacktionableError(`Ollama request failed (${response.status}). Ensure Ollama is running and model '${model}' is pulled.`);
+    }
+    const json = (await response.json());
+    const content = json.message?.content;
+    if (!content) {
+        throw new errors_1.QuacktionableError('Ollama returned an empty response.');
+    }
+    return content;
+}

package/dist/llm/prompts.d.ts

@@ -0,0 +1,15 @@
+import type { DuckPersona, EvidenceBundle } from '../core/types';
+export interface DuckModelResponse {
+    rounds: Array<{
+        question: string;
+        answer: string;
+        concern: string;
+    }>;
+    vote: {
+        rootCause: string;
+        rationale: string;
+        confidence: number;
+        evidenceRefs: string[];
+    };
+}
+export declare const buildDuckPrompt: (persona: DuckPersona, evidence: EvidenceBundle, rounds: number) => string;

package/dist/llm/prompts.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDuckPrompt = void 0;
+const buildDuckPrompt = (persona, evidence, rounds) => {
+    return [
+        'You are a judge duck in a debugging tribunal: witty but ruthlessly accurate.',
+        `Duck persona: ${persona.name}`,
+        `Style: ${persona.style}`,
+        `Focus: ${persona.focus}`,
+        '',
+        'Task:',
+        `- Generate exactly ${rounds} cross-examination rounds.`,
+        '- Then cast one vote for the most likely root cause.',
+        '- Keep confidence as a number from 0 to 100.',
+        '- Use concrete evidence references from narrative, logs, or repo context.',
+        '- Light humor is welcome; hallucinations are not.',
+        '',
+        'Respond ONLY in JSON with this shape:',
+        '{"rounds":[{"question":"","answer":"","concern":""}],"vote":{"rootCause":"","rationale":"","confidence":0,"evidenceRefs":[""]}}',
+        '',
+        'Evidence narrative:',
+        evidence.narrative || '<none>',
+        '',
+        'Evidence logs:',
+        evidence.logs || '<none>',
+        '',
+        'Evidence repo context:',
+        evidence.repoContext || '<none>',
+    ].join('\n');
+};
+exports.buildDuckPrompt = buildDuckPrompt;

package/dist/llm/validateModelOutput.d.ts

@@ -0,0 +1,2 @@
+import type { DuckModelResponse } from './prompts';
+export declare const parseDuckModelOutput: (raw: string, expectedRounds: number) => DuckModelResponse;

package/dist/llm/validateModelOutput.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDuckModelOutput = void 0;
+const errors_1 = require("../core/errors");
+const parseDuckModelOutput = (raw, expectedRounds) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new errors_1.InvalidModelOutputError('Model response was not valid JSON.');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new errors_1.InvalidModelOutputError('Model response was not an object.');
+    }
+    const candidate = parsed;
+    if (!Array.isArray(candidate.rounds) || candidate.rounds.length !== expectedRounds) {
+        throw new errors_1.InvalidModelOutputError(`Model response must contain exactly ${expectedRounds} rounds.`);
+    }
+    for (const round of candidate.rounds) {
+        if (!round || typeof round.question !== 'string' || typeof round.answer !== 'string' || typeof round.concern !== 'string') {
+            throw new errors_1.InvalidModelOutputError('Each round must include question, answer, and concern strings.');
+        }
+    }
+    if (!candidate.vote || typeof candidate.vote !== 'object') {
+        throw new errors_1.InvalidModelOutputError('Model response must include a vote object.');
+    }
+    if (typeof candidate.vote.rootCause !== 'string' || typeof candidate.vote.rationale !== 'string') {
+        throw new errors_1.InvalidModelOutputError('Vote must include rootCause and rationale strings.');
+    }
+    if (typeof candidate.vote.confidence !== 'number' || Number.isNaN(candidate.vote.confidence)) {
+        throw new errors_1.InvalidModelOutputError('Vote confidence must be a number.');
+    }
+    if (!Array.isArray(candidate.vote.evidenceRefs) || !candidate.vote.evidenceRefs.every((item) => typeof item === 'string')) {
+        throw new errors_1.InvalidModelOutputError('Vote evidenceRefs must be an array of strings.');
+    }
+    return candidate;
+};
+exports.parseDuckModelOutput = parseDuckModelOutput;

package/dist/output/jsonRenderer.d.ts

@@ -0,0 +1,2 @@
+import type { TribunalSession } from '../core/types';
+export declare const renderJson: (session: TribunalSession) => string;

package/dist/output/jsonRenderer.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderJson = void 0;
+const schema_1 = require("./schema");
+const renderJson = (session) => {
+    return JSON.stringify((0, schema_1.toJsonOutput)(session), null, 2);
+};
+exports.renderJson = renderJson;

package/dist/output/schema.d.ts

@@ -0,0 +1,7 @@
+import type { TribunalSession } from '../core/types';
+export declare const OUTPUT_SCHEMA_VERSION = "1.0.0";
+export interface QuacktionableJsonOutput {
+    schemaVersion: string;
+    session: TribunalSession;
+}
+export declare const toJsonOutput: (session: TribunalSession) => QuacktionableJsonOutput;

package/dist/output/schema.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJsonOutput = exports.OUTPUT_SCHEMA_VERSION = void 0;
+exports.OUTPUT_SCHEMA_VERSION = '1.0.0';
+const toJsonOutput = (session) => {
+    return {
+        schemaVersion: exports.OUTPUT_SCHEMA_VERSION,
+        session,
+    };
+};
+exports.toJsonOutput = toJsonOutput;

package/dist/output/terminalRenderer.d.ts

@@ -0,0 +1,2 @@
+import type { TribunalSession } from '../core/types';
+export declare const renderTerminal: (session: TribunalSession) => string;

package/dist/output/terminalRenderer.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTerminal = void 0;
+const renderTerminal = (session) => {
+    const lines = [];
+    const confidenceEmoji = session.verdict.confidence >= 80 ? '🔥' : session.verdict.confidence >= 50 ? '🧠' : '🤔';
+    lines.push('🦆⚖️ Rubber Duck Tribunal (Court is now in session)');
+    lines.push('🎭 Opening statement: no bug survives cross-examination.');
+    lines.push(`🆔 Session: ${session.id}`);
+    lines.push(`🤖 Engine: ${session.model}`);
+    lines.push('');
+    lines.push('📝 Bug Tale');
+    lines.push(`- 🐛 ${session.bugReport.summary}`);
+    if (session.evidence.extractedSignals.length > 0) {
+        lines.push('');
+        lines.push('🚨 Suspicious Signals');
+        for (const signal of session.evidence.extractedSignals) {
+            lines.push(`- 📍 ${signal}`);
+        }
+    }
+    lines.push('');
+    lines.push('🗳️ Judge Duck Votes');
+    for (const vote of session.votes) {
+        lines.push(`- 🦆 ${vote.duckName}: ${vote.rootCause} (${vote.confidence}%)`);
+        lines.push(`  💬 rationale: ${vote.rationale}`);
+    }
+    lines.push('');
+    lines.push('🏛️ Final Quackdict');
+    lines.push(`- 🎯 root cause: ${session.verdict.rootCause}`);
+    lines.push(`- ${confidenceEmoji} confidence: ${session.verdict.confidence}%`);
+    if (session.verdict.dissentingCauses.length > 0) {
+        lines.push(`- 🙋 dissent: ${session.verdict.dissentingCauses.join(', ')}`);
+    }
+    lines.push(`- 🧾 summary: ${session.verdict.summary}`);
+    lines.push('🧃 Court snack break: hydrate, patch, and redeploy responsibly.');
+    return lines.join('\n');
+};
+exports.renderTerminal = renderTerminal;

package/dist/tribunal/aggregateVotes.d.ts

@@ -0,0 +1,2 @@
+import type { Verdict, Vote } from '../core/types';
+export declare const aggregateVotes: (votes: Vote[]) => Verdict;

package/dist/tribunal/aggregateVotes.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateVotes = void 0;
+const confidence_1 = require("./confidence");
+const scoring_1 = require("./scoring");
+const aggregateVotes = (votes) => {
+    if (votes.length === 0) {
+        return {
+            rootCause: 'insufficient evidence',
+            confidence: 0,
+            dissentingCauses: [],
+            voteBreakdown: [],
+            summary: 'No valid votes were produced by the duck bench. The court requests more breadcrumbs.',
+            insufficientEvidence: true,
+        };
+    }
+    const totals = (0, scoring_1.scoreVotes)(votes);
+    const sorted = Object.entries(totals).sort((a, b) => b[1] - a[1]);
+    const [topCause] = sorted[0];
+    const topCauseVotes = votes.filter((vote) => (0, scoring_1.normalizeCause)(vote.rootCause) === topCause);
+    const confidence = (0, confidence_1.calibrateConfidence)(topCauseVotes, votes);
+    return {
+        rootCause: topCause,
+        confidence,
+        dissentingCauses: sorted.slice(1, 4).map(([cause]) => cause),
+        voteBreakdown: votes,
+        summary: confidence < 35
+            ? 'The ducks are unconvinced. Bring juicier logs and code clues before shipping a fix.'
+            : `The duck bench quacks in favor of '${topCause}' as the likely root cause.`,
+        insufficientEvidence: confidence < 25,
+    };
+};
+exports.aggregateVotes = aggregateVotes;

package/dist/tribunal/confidence.d.ts

@@ -0,0 +1,2 @@
+import type { Vote } from '../core/types';
+export declare const calibrateConfidence: (topCauseVotes: Vote[], allVotes: Vote[]) => number;

package/dist/tribunal/confidence.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calibrateConfidence = void 0;
+const calibrateConfidence = (topCauseVotes, allVotes) => {
+    if (allVotes.length === 0) {
+        return 0;
+    }
+    const topShare = topCauseVotes.length / allVotes.length;
+    const avgTopConfidence = topCauseVotes.reduce((sum, vote) => sum + vote.confidence, 0) / Math.max(topCauseVotes.length, 1);
+    const calibrated = topShare * 70 + (avgTopConfidence / 100) * 30;
+    return Math.round(Math.max(0, Math.min(100, calibrated * 100)));
+};
+exports.calibrateConfidence = calibrateConfidence;

package/dist/tribunal/defaultDucks.d.ts

@@ -0,0 +1,2 @@
+import type { DuckPersona } from '../core/types';
+export declare const DEFAULT_DUCKS: DuckPersona[];

package/dist/tribunal/defaultDucks.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DUCKS = void 0;
+exports.DEFAULT_DUCKS = [
+    {
+        id: 'duck-1',
+        name: 'Detective Quackson',
+        style: 'Methodical, skeptical, and mildly dramatic',
+        focus: 'Correlate logs with claim consistency and missing evidence',
+    },
+    {
+        id: 'duck-2',
+        name: 'Captain Crashbeard',
+        style: 'Pragmatic production engineer with chaos stories',
+        focus: 'Failure modes, environment drift, and configuration mismatches',
+    },
+    {
+        id: 'duck-3',
+        name: 'Null Pointer Patty',
+        style: 'Static-analysis minded and delightfully sarcastic',
+        focus: 'Control flow, nullability, race conditions, and edge paths',
+    },
+];

package/dist/tribunal/runTribunal.d.ts

@@ -0,0 +1,2 @@
+import type { TribunalSession, TribunalOptions } from '../core/types';
+export declare const runTribunal: (evidence: TribunalSession["evidence"], bugReport: TribunalSession["bugReport"], options: TribunalOptions) => Promise<TribunalSession>;

package/dist/tribunal/runTribunal.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTribunal = void 0;
+const node_crypto_1 = require("node:crypto");
+const copilotCli_1 = require("../copilot/copilotCli");
+const prompts_1 = require("../llm/prompts");
+const validateModelOutput_1 = require("../llm/validateModelOutput");
+const aggregateVotes_1 = require("./aggregateVotes");
+const stripFences = (text) => {
+    const trimmed = text.trim();
+    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+    return fenced ? fenced[1].trim() : trimmed;
+};
+const runTribunal = async (evidence, bugReport, options) => {
+    const modelLabel = await (0, copilotCli_1.resolveCopilotModelLabel)();
+    options.onProgress?.('Checking if Copilot CLI is awake...');
+    if (options.requireCopilotCli) {
+        (0, copilotCli_1.assertCopilotCliAvailable)();
+    }
+    options.onProgress?.('Asking Copilot for spicy cross-exam ammo...');
+    const copilotNotes = options.requireCopilotCli ? await (0, copilotCli_1.runCopilotCrossExam)(evidence) : '';
+    const enrichedEvidence = {
+        ...evidence,
+        narrative: `${evidence.narrative}\n\nCopilot external cross-exam notes:\n${copilotNotes}`,
+    };
+    options.onProgress?.('Calling the duck judges to the bench...');
+    const results = await Promise.all(options.ducks.map(async (duck) => {
+        options.onProgress?.(`🦆 ${duck.name} is cross-examining your theory...`);
+        const prompt = (0, prompts_1.buildDuckPrompt)(duck, enrichedEvidence, options.rounds);
+        const raw = await (0, copilotCli_1.runCopilotDuckJudgment)(prompt);
+        const parsed = (0, validateModelOutput_1.parseDuckModelOutput)(stripFences(raw), options.rounds);
+        const rounds = parsed.rounds.map((round, index) => ({
+            round: index + 1,
+            question: round.question,
+            answer: round.answer,
+            concern: round.concern,
+        }));
+        const vote = {
+            duckId: duck.id,
+            duckName: duck.name,
+            rootCause: parsed.vote.rootCause,
+            rationale: parsed.vote.rationale,
+            confidence: Math.max(0, Math.min(100, Math.round(parsed.vote.confidence))),
+            evidenceRefs: parsed.vote.evidenceRefs,
+        };
+        options.onProgress?.(`✅ ${duck.name} submitted a vote.`);
+        return { duckId: duck.id, rounds, vote };
+    }));
+    const roundsByDuck = {};
+    const votes = [];
+    for (const result of results) {
+        roundsByDuck[result.duckId] = result.rounds;
+        votes.push(result.vote);
+    }
+    options.onProgress?.('Counting quacks and tallying votes...');
+    const verdict = (0, aggregateVotes_1.aggregateVotes)(votes);
+    options.onProgress?.('Final quackdict ready. Court adjourned.');
+    return {
+        id: (0, node_crypto_1.randomUUID)(),
+        createdAt: new Date().toISOString(),
+        model: modelLabel,
+        bugReport,
+        evidence,
+        roundsByDuck,
+        votes,
+        verdict,
+    };
+};
+exports.runTribunal = runTribunal;

package/dist/tribunal/scoring.d.ts

@@ -0,0 +1,3 @@
+import type { Vote } from '../core/types';
+export declare const scoreVotes: (votes: Vote[]) => Record<string, number>;
+export declare const normalizeCause: (cause: string) => string;

package/dist/tribunal/scoring.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCause = exports.scoreVotes = void 0;
+const scoreVote = (vote) => {
+    const evidenceBonus = Math.min(vote.evidenceRefs.length * 3, 12);
+    return Math.max(0, Math.min(100, vote.confidence + evidenceBonus));
+};
+const scoreVotes = (votes) => {
+    const totals = {};
+    for (const vote of votes) {
+        const cause = (0, exports.normalizeCause)(vote.rootCause);
+        const value = scoreVote(vote);
+        totals[cause] = (totals[cause] ?? 0) + value;
+    }
+    return totals;
+};
+exports.scoreVotes = scoreVotes;
+const normalizeCause = (cause) => {
+    return cause.trim().toLowerCase().replace(/\s+/g, ' ');
+};
+exports.normalizeCause = normalizeCause;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "quacktionable",
+  "version": "0.1.0",
+  "description": "Rubber Duck Tribunal: cross-examine bugs and vote on root cause.",
+  "main": "dist/cli.js",
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "quack": "bin/quack",
+    "quacktionable": "bin/quacktionable"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seshxn/quacktionable.git"
+  },
+  "homepage": "https://github.com/seshxn/quacktionable#readme",
+  "bugs": {
+    "url": "https://github.com/seshxn/quacktionable/issues"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "dev": "tsx src/cli.ts",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "cli",
+    "debugging",
+    "rubber-duck",
+    "root-cause-analysis",
+    "copilot"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  },
+  "dependencies": {
+    "gradient-string": "^3.0.0"
+  }
+}