traintrack 2.0.0

package/dist/setup/prompt.js

@@ -0,0 +1,218 @@
+// Dependency-free interactive prompts. A real terminal gets a proper keyboard
+// navigable checkbox selector (↑/↓ move, space toggle, a all/none, enter
+// confirm, esc cancel) via raw-mode keypress events. Non-TTY input (pipes,
+// tests, CI) falls back to a simple line-based reader. Streams are injectable.
+import { createInterface, emitKeypressEvents } from 'node:readline';
+function resolveIo(io) {
+    return {
+        input: io?.input ?? process.stdin,
+        output: io?.output ?? process.stdout,
+    };
+}
+const DIM = '\x1b[2m';
+const CYAN = '\x1b[36m';
+const RST = '\x1b[0m';
+export function keyToAction(key) {
+    if (!key)
+        return 'ignore';
+    if (key.ctrl && key.name === 'c')
+        return 'cancel';
+    switch (key.name) {
+        case 'up':
+        case 'k':
+            return 'up';
+        case 'down':
+        case 'j':
+            return 'down';
+        case 'space':
+            return 'toggle';
+        case 'a':
+            return 'all';
+        case 'return':
+        case 'enter':
+            return 'confirm';
+        case 'escape':
+            return 'cancel';
+        default:
+            return 'ignore';
+    }
+}
+/** Pure state transition for the selector. `selected` is mutated in place and
+ *  the new cursor is returned. Tested directly. */
+export function applySelect(action, cursor, selected) {
+    const n = selected.length;
+    switch (action) {
+        case 'up':
+            return (cursor - 1 + n) % n;
+        case 'down':
+            return (cursor + 1) % n;
+        case 'toggle':
+            selected[cursor] = !selected[cursor];
+            return cursor;
+        case 'all': {
+            const allOn = selected.every(Boolean);
+            for (let i = 0; i < n; i++)
+                selected[i] = !allOn;
+            return cursor;
+        }
+        default:
+            return cursor;
+    }
+}
+/** Raw-mode checkbox selector for real terminals. All items start selected. */
+function rawModeSelect(title, items, res) {
+    const input = res.input;
+    const out = res.output;
+    return new Promise((resolve) => {
+        let cursor = 0;
+        const selected = items.map(() => true);
+        emitKeypressEvents(input);
+        const wasRaw = Boolean(input.isRaw);
+        input.setRawMode?.(true);
+        input.resume?.();
+        let prevLines = 0;
+        const draw = (final) => {
+            if (prevLines > 0)
+                out.write(`\x1b[${prevLines}A\x1b[0J`);
+            const rows = [title];
+            items.forEach((it, i) => {
+                const here = i === cursor && !final;
+                const pointer = here ? `${CYAN}›${RST}` : ' ';
+                const box = selected[i] ? `${CYAN}◉${RST}` : '◯';
+                const label = here ? `${CYAN}${it.label}${RST}` : it.label;
+                rows.push(`  ${pointer} ${box} ${label} ${DIM}${it.hint}${RST}`);
+            });
+            if (!final) {
+                rows.push(`${DIM}  ↑/↓ move · space toggle · a all/none · enter confirm · esc cancel${RST}`);
+            }
+            out.write(rows.join('\n') + '\n');
+            prevLines = rows.length;
+        };
+        const finish = (result) => {
+            draw(true);
+            input.off('keypress', onKey);
+            input.setRawMode?.(wasRaw);
+            input.pause?.();
+            resolve(result);
+        };
+        const chosen = () => items.filter((_, i) => selected[i]).map((it) => it.id);
+        const onKey = (_s, key) => {
+            const action = keyToAction(key);
+            if (action === 'confirm')
+                return finish(chosen());
+            if (action === 'cancel')
+                return finish([]);
+            if (action === 'ignore')
+                return;
+            cursor = applySelect(action, cursor, selected);
+            draw(false);
+        };
+        input.on('keypress', onKey);
+        out.write('\n');
+        draw(false);
+    });
+}
+/** A line reader backed by ONE readline interface over the input stream. Used
+ *  for the non-TTY fallback and for confirm(). Buffers early lines. */
+class LineReader {
+    rl;
+    buffered = [];
+    waiters = [];
+    closed = false;
+    constructor(input) {
+        this.rl = createInterface({ input });
+        this.rl.on('line', (line) => {
+            const waiter = this.waiters.shift();
+            if (waiter)
+                waiter(line);
+            else
+                this.buffered.push(line);
+        });
+        this.rl.on('close', () => {
+            this.closed = true;
+            while (this.waiters.length > 0) {
+                const waiter = this.waiters.shift();
+                waiter('');
+            }
+        });
+    }
+    next() {
+        const queued = this.buffered.shift();
+        if (queued !== undefined)
+            return Promise.resolve(queued);
+        if (this.closed)
+            return Promise.resolve('');
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    close() {
+        this.rl.close();
+    }
+}
+/** Non-TTY fallback: numbered list, type number(s) to toggle, blank to confirm. */
+async function lineModeSelect(title, items, res) {
+    const reader = new LineReader(res.input);
+    const selected = new Set();
+    const render = () => {
+        res.output.write(`\n${title}\n`);
+        items.forEach((it, i) => {
+            res.output.write(`  ${selected.has(i) ? '[x]' : '[ ]'} ${i + 1}) ${it.label}  (${it.hint})\n`);
+        });
+        res.output.write('Type number(s) to toggle (e.g. "1 3"), or "all" / "none". Press Enter to confirm.\n> ');
+    };
+    try {
+        for (;;) {
+            render();
+            const line = (await reader.next()).trim();
+            if (line === '')
+                break;
+            const lower = line.toLowerCase();
+            if (lower === 'all') {
+                items.forEach((_, i) => selected.add(i));
+                continue;
+            }
+            if (lower === 'none') {
+                selected.clear();
+                continue;
+            }
+            for (const tok of line.split(/[\s,]+/).filter((t) => t.length > 0)) {
+                const n = Number.parseInt(tok, 10);
+                if (Number.isInteger(n) && n >= 1 && n <= items.length) {
+                    const idx = n - 1;
+                    if (selected.has(idx))
+                        selected.delete(idx);
+                    else
+                        selected.add(idx);
+                }
+            }
+        }
+    }
+    finally {
+        reader.close();
+    }
+    return items.filter((_, i) => selected.has(i)).map((it) => it.id);
+}
+/** Multi-select. Real terminals get an arrow-key checkbox UI; non-TTY input
+ *  (pipes, tests) gets the line-based fallback. Returns the chosen ids. */
+export async function multiSelect(title, items, io) {
+    const res = resolveIo(io);
+    if (items.length === 0)
+        return [];
+    const input = res.input;
+    if (input.isTTY && typeof input.setRawMode === 'function') {
+        return rawModeSelect(title, items, res);
+    }
+    return lineModeSelect(title, items, res);
+}
+/** Yes/no confirm. Empty input → defaults to false. */
+export async function confirm(question, io) {
+    const res = resolveIo(io);
+    const reader = new LineReader(res.input);
+    res.output.write(`${question} [y/N] `);
+    try {
+        const line = (await reader.next()).trim().toLowerCase();
+        return line === 'y' || line === 'yes';
+    }
+    finally {
+        reader.close();
+    }
+}

package/dist/setup/setup.js

@@ -0,0 +1,106 @@
+// runSetup / runUninstall orchestrators: detect harnesses, let the user choose
+// (or --all), configure (or --uninstall) each, and print a summary. Never throws
+// on a single harness failing — that harness becomes an 'error' outcome.
+import { homedir } from 'node:os';
+import { resolveServerPath } from './types.js';
+import { detectHarnesses, defaultOnPath } from './detect.js';
+import { configureHarness, unconfigureHarness } from './configure.js';
+import { multiSelect, confirm } from './prompt.js';
+/** Resolve the output sink — defaults to process.stdout. */
+function out(opts) {
+    return opts.io?.output ?? process.stdout;
+}
+/** Run one harness through configure/unconfigure, capturing any throw as an
+ *  'error' outcome so a single bad harness never aborts the whole run. */
+function applyOne(spec, ctx, uninstall) {
+    try {
+        return uninstall ? unconfigureHarness(spec, ctx) : configureHarness(spec, ctx);
+    }
+    catch (err) {
+        return {
+            harness: spec.id,
+            mcp: 'error',
+            awareness: 'error',
+            files: [],
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** Print a per-harness summary table plus a closing note. */
+function printSummary(io, outcomes, ctx, uninstall) {
+    io.write('\n');
+    for (const o of outcomes) {
+        io.write(`  ${o.harness.padEnd(8)} mcp:${o.mcp.padEnd(10)} awareness:${o.awareness}\n`);
+        if (o.detail)
+            io.write(`    ${o.detail}\n`);
+        for (const f of o.files)
+            io.write(`    → ${f}\n`);
+    }
+    io.write('\n');
+    if (ctx.dryRun) {
+        io.write('Dry run — no files were written.\n');
+        return;
+    }
+    if (uninstall) {
+        io.write('Removed traintrack from the selected tools.\n');
+        return;
+    }
+    const names = outcomes.map((o) => o.harness).join(', ');
+    io.write(`Done. Open ${names} and ask it to spawn a worker — e.g. "spawn a codex worker to write tests".\n`);
+}
+/**
+ * Detect installed harnesses, choose targets (interactively unless --all),
+ * and configure (or uninstall) traintrack for each. Returns the outcomes.
+ */
+export async function runSetup(opts) {
+    const io = out(opts);
+    const ctx = {
+        home: opts.home ?? homedir(),
+        serverPath: resolveServerPath(import.meta.url),
+        nodePath: process.execPath,
+        dryRun: opts.dryRun ?? false,
+        injectAwareness: !opts.toolsOnly,
+    };
+    const detected = detectHarnesses({ home: ctx.home, onPath: opts.onPath ?? defaultOnPath });
+    const present = detected.filter((d) => d.present);
+    if (present.length === 0) {
+        io.write('No supported agent CLIs detected (Claude Code, Codex, Cursor, OpenCode).\n' +
+            'Install one and re-run `traintrack setup`.\n');
+        return [];
+    }
+    // Choose targets.
+    let chosen;
+    if (opts.all) {
+        chosen = present.map((d) => d.spec.id);
+    }
+    else {
+        const promptIo = { input: opts.io?.input, output: io };
+        const verb = opts.uninstall ? 'remove traintrack from' : 'wire traintrack into';
+        const ids = await multiSelect(`Which tools should we ${verb}?`, present.map((d) => ({ id: d.spec.id, label: d.spec.displayName, hint: d.reason })), promptIo);
+        chosen = ids;
+        if (chosen.length === 0) {
+            io.write('Nothing selected — exiting.\n');
+            return [];
+        }
+        if (!opts.yes) {
+            const ok = await confirm(`${opts.uninstall ? 'Remove from' : 'Configure'} ${chosen.join(', ')}?`, promptIo);
+            if (!ok) {
+                io.write('Cancelled.\n');
+                return [];
+            }
+        }
+    }
+    const chosenSpecs = present
+        .filter((d) => chosen.includes(d.spec.id))
+        .map((d) => d.spec);
+    const outcomes = [];
+    for (const spec of chosenSpecs) {
+        outcomes.push(applyOne(spec, ctx, opts.uninstall ?? false));
+    }
+    printSummary(io, outcomes, ctx, opts.uninstall ?? false);
+    return outcomes;
+}
+/** Convenience wrapper for the uninstall path. */
+export async function runUninstall(opts) {
+    return runSetup({ ...opts, uninstall: true });
+}

package/dist/setup/types.js

@@ -0,0 +1,9 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+/** Resolve the abs path to this package's dist/mcp-server.js from the module's
+ *  own location (works for a global npm install). Exported for setup.ts.
+ *  The module lives at dist/setup/types.js, so up two to package root, then
+ *  dist/mcp-server.js. */
+export function resolveServerPath(fromUrl) {
+    return resolve(join(dirname(fileURLToPath(fromUrl)), '..', '..', 'dist', 'mcp-server.js'));
+}

package/dist/spawn/spawn.js

@@ -0,0 +1,90 @@
+import { execFile as nodeExecFile, spawn as nodeSpawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// ── helpers ───────────────────────────────────────────────────────────────────
+/**
+ * Resolve the CLI path. Prefer the TRAINTRACK_CLI env var; otherwise resolve
+ * relative to this module file so it works both in-repo and when installed.
+ */
+function resolveCliPath() {
+    if (process.env.TRAINTRACK_CLI) {
+        return process.env.TRAINTRACK_CLI;
+    }
+    // __dirname equivalent for ESM: resolve from this file up two levels then into dist/cli.js
+    const thisFile = fileURLToPath(import.meta.url);
+    return resolve(thisFile, '../../..', 'dist/cli.js');
+}
+// ── public API ────────────────────────────────────────────────────────────────
+/**
+ * Build the command + args needed to launch a worker process.
+ * Uses `process.execPath` (node binary) so the worker runs under the same
+ * Node version as the current process.
+ */
+export function buildWorkerCommand(opts) {
+    const { agent, role, handle, channel } = opts;
+    const cliPath = resolveCliPath();
+    return {
+        command: process.execPath,
+        args: [cliPath, 'worker', '--agent', agent, '--role', role, '--handle', handle, '--channel', channel],
+    };
+}
+/**
+ * Spawn a worker in a fresh git worktree.
+ *
+ * Steps:
+ * 1. Validate that repoRoot is a git repo (has .git).
+ * 2. Mint a unique handle.
+ * 3. Create a git worktree at <repoRoot>/.traintrack/worktrees/<handle> on branch traintrack/<handle>.
+ * 4. Register the worker as a channel member.
+ * 5. Send the seed task message to the worker handle.
+ * 6. Spawn the worker process in the worktree directory (detached, unreffed).
+ * 7. Return { handle }.
+ */
+export async function spawnWorker(opts) {
+    const { channel, repoRoot, agent, role, task, leadHandle, execFileImpl = (cmd, args, optsCb, cb) => nodeExecFile(cmd, args, optsCb, (err) => cb(err)), spawnImpl = (command, args, spawnOpts) => nodeSpawn(command, args, spawnOpts), } = opts;
+    // Guard: ensure repoRoot is a git repository
+    if (!existsSync(join(repoRoot, '.git'))) {
+        throw new Error(`spawnWorker: ${repoRoot} is not a git repo (no .git found)`);
+    }
+    // Mint a unique worker handle
+    const handle = `worker_${crypto.randomUUID().slice(0, 8)}`;
+    // Determine worktree path
+    const worktreePath = join(repoRoot, '.traintrack', 'worktrees', handle);
+    // Create the git worktree
+    await new Promise((resolveP, rejectP) => {
+        execFileImpl('git', ['worktree', 'add', worktreePath, '-b', `traintrack/${handle}`], { cwd: repoRoot }, (err) => {
+            if (err) {
+                rejectP(err);
+            }
+            else {
+                resolveP();
+            }
+        });
+    });
+    // Register the member in the channel
+    channel.addMember({
+        handle,
+        agent,
+        role,
+        kind: 'headless',
+        status: 'active',
+        worktree: worktreePath,
+    });
+    // Send the seed task message
+    channel.insertMessage({
+        from: leadHandle ?? 'lead',
+        to: handle,
+        body: task,
+        type: 'task',
+    });
+    // Build and launch the worker command (detached, unreffed — runs in background)
+    const { command, args } = buildWorkerCommand({ agent, role, handle, channel: channel.dbPath });
+    const child = spawnImpl(command, args, {
+        cwd: worktreePath,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: true,
+    });
+    child.unref();
+    return { handle };
+}

package/dist/ui/banner.js

@@ -0,0 +1,76 @@
+// A dependency-free branded banner for the traintrack CLI: a block-letter
+// wordmark with a horizontal truecolor gradient (blue → purple → pink), plus a
+// dim tagline. Color is applied only when the caller says the terminal supports
+// it; without color the same ASCII renders plain (pipes, NO_COLOR, non-TTY).
+/** 5-row block glyphs for the letters in "TRAINTRACK". Each glyph's rows share
+ *  a fixed width so the composed rows line up. */
+const GLYPHS = {
+    T: ['█████', '  █  ', '  █  ', '  █  ', '  █  '],
+    R: ['████ ', '█   █', '████ ', '█  █ ', '█   █'],
+    A: [' ███ ', '█   █', '█████', '█   █', '█   █'],
+    I: ['███', ' █ ', ' █ ', ' █ ', '███'],
+    N: ['█   █', '██  █', '█ █ █', '█  ██', '█   █'],
+    C: [' ████', '█    ', '█    ', '█    ', ' ████'],
+    K: ['█   █', '█  █ ', '███  ', '█  █ ', '█   █'],
+};
+const BLANK = ['   ', '   ', '   ', '   ', '   '];
+// Gradient stops, Gemini-ish: blue → purple → pink.
+const STOPS = [
+    [79, 140, 255],
+    [160, 108, 255],
+    [255, 95, 158],
+];
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+function lerp(a, b, t) {
+    return Math.round(a + (b - a) * t);
+}
+/** Color at position t∈[0,1] across the two-segment gradient. */
+function gradientAt(t) {
+    const seg = t < 0.5 ? 0 : 1;
+    const lt = t < 0.5 ? t / 0.5 : (t - 0.5) / 0.5;
+    const c0 = STOPS[seg];
+    const c1 = STOPS[seg + 1];
+    return [lerp(c0[0], c1[0], lt), lerp(c0[1], c1[1], lt), lerp(c0[2], c1[2], lt)];
+}
+function fg([r, g, b]) {
+    return `\x1b[38;2;${r};${g};${b}m`;
+}
+/** Render a block-letter wordmark, optionally with the horizontal gradient. */
+export function renderWordmark(word, color) {
+    const letters = word.toUpperCase().split('');
+    const rows = [];
+    for (let r = 0; r < 5; r++) {
+        rows.push(letters.map((ch) => (GLYPHS[ch] ?? BLANK)[r]).join(' '));
+    }
+    if (!color)
+        return rows.join('\n');
+    const width = rows[0].length;
+    return rows
+        .map((row) => {
+        let out = '';
+        for (let i = 0; i < row.length; i++) {
+            const ch = row[i];
+            if (ch === ' ') {
+                out += ' ';
+                continue;
+            }
+            out += fg(gradientAt(width > 1 ? i / (width - 1) : 0)) + ch;
+        }
+        return out + RESET;
+    })
+        .join('\n');
+}
+/** The full banner: a blank line, the gradient wordmark, and a dim tagline with
+ *  the version. Returns a ready-to-write string (trailing blank line included). */
+export function renderBanner(opts) {
+    const art = renderWordmark(opts.word ?? 'TRAINTRACK', opts.color);
+    const sub = opts.subtitle ?? 'multi-agent coordination for your coding agents';
+    const dim = opts.color ? DIM : '';
+    const reset = opts.color ? RESET : '';
+    return `\n${art}\n\n  ${dim}${sub} · v${opts.version}${reset}\n\n`;
+}
+/** Whether to colorize: a real terminal and NO_COLOR not set. */
+export function bannerColorEnabled(stream) {
+    return Boolean(stream.isTTY) && process.env['NO_COLOR'] == null;
+}