peaks-cli 1.3.3 → 1.3.5

package/dist/src/cli/commands/progress-start-spawn.js

@@ -1,140 +0,0 @@
-/**
- * Pure platform-specific spawn-args construction for
- * `peaks progress start`. Extracted out of the commander
- * action handler so the three platform branches (darwin /
- * linux / win32) can be unit-tested without spawning real
- * terminals.
- *
- * The CLI action calls `buildStartSpawn` once per start
- * attempt and feeds the returned `{ command, args }` pair to
- * `child_process.spawn(..., { detached: true, stdio: 'ignore' })`.
- *
- * Cross-platform strategy (see progress-commands.ts for the
- * full design notes):
- *
- *   - macOS:  `osascript -e 'tell application "Terminal" to
- *              do script "<shell>"'`. The shell command sets
- *              the title via the OSC 0 escape (printf), runs
- *              the brand banner, then exec's the watch.
- *   - Linux:  First existing terminal emulator in
- *              { gnome-terminal, konsole, xfce4-terminal,
- *              tilix, alacritty, kitty }, with per-emulator
- *              flag translation. The shell inside also sets
- *              the title via OSC 0 (emulator --title is
- *              best-effort only — the shell overrides it).
- *   - Win32:  `cmd /c start "<title>" cmd /k <shell>`. The
- *              shell uses the `title` builtin (cmd.exe
- *              builtin) to re-anchor the title before the
- *              watch runs, because cmd.exe overrides the
- *              start-title with the running command name.
- *
- * The function never throws on unsupported platforms; it
- * returns a discriminated `unsupported` result so the caller
- * can surface a clean error envelope.
- */
-import { existsSync } from 'node:fs';
-/** Brand banner the user sees in the spawned shell. */
-const BANNER = 'echo "peaks-cli — sub-agent progress"';
-/**
- * Build the POSIX OSC 0 title escape. The single-quote
- * escape is bash's `'\''` for embedding a single quote in a
- * single-quoted string; we need it because windowTitle may
- * contain user-provided text (the `--reason` argument).
- */
-function buildPosixTitleCmd(windowTitle) {
-    const escaped = windowTitle.replaceAll("'", "'\\''");
-    return `printf '\\033]0;${escaped}\\007'`;
-}
-/**
- * cmd.exe `title` builtin call. Quoting is REQUIRED: cmd /k parses the
- * subsequent tokens as a command line, and a `:` in the unquoted title (the
- * canonical peaks windowTitle starts with `peaks-cli:`) gets mis-read as a
- * drive-letter prefix, triggering Windows' "找不到文件 'sub-agent'" dialog.
- *
- * The double-quote wrap makes the whole title one parameter to `title`.
- * Defensive guard: reject embedded `"`, `\n`, or `\r` (the `cmd /k` parser
- * will not survive a literal newline or an un-escaped quote in the title).
- * Callers (progress-commands.ts:267) compose the title from CLI args; if
- * the user passed a `--reason` containing one of these characters, the
- * spawn attempt is abandoned with a tagged result so the CLI can surface
- * a clear error envelope.
- */
-function buildWinTitleCmd(windowTitle) {
-    if (windowTitle.includes('"') || windowTitle.includes('\n') || windowTitle.includes('\r')) {
-        return { ok: false, unsupported: true };
-    }
-    return { ok: true, cmd: `title "${windowTitle}"` };
-}
-/** Shared helper: the shell command that runs the watch. */
-function buildWatchCommand(peaksBin, projectRoot) {
-    return `${peaksBin} progress watch --project "${projectRoot}"`;
-}
-export function buildStartSpawn(options) {
-    const { peaksBin, projectRoot, windowTitle, platform: currentPlatform } = options;
-    const watchCommand = buildWatchCommand(peaksBin, projectRoot);
-    const posixTitleCmd = buildPosixTitleCmd(windowTitle);
-    const winTitleCmd = buildWinTitleCmd(windowTitle);
-    if (currentPlatform === 'darwin') {
-        const innerShell = `${posixTitleCmd}; ${BANNER}; ${watchCommand}`;
-        const escapedInner = innerShell.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
-        return {
-            ok: true,
-            command: 'osascript',
-            args: [
-                '-e',
-                `tell application "Terminal" to do script "${escapedInner}"`,
-                '-e',
-                'tell application "Terminal" to activate'
-            ]
-        };
-    }
-    if (currentPlatform === 'linux') {
-        const exists = options.linuxTerminalExists ?? ((name) => existsSync(`/usr/bin/${name}`));
-        const candidates = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'tilix', 'alacritty', 'kitty'];
-        const terminal = candidates.find((c) => exists(c)) ?? candidates[0];
-        const titleArg = ['--title', windowTitle];
-        const bannerShell = `bash -c '${posixTitleCmd}; ${BANNER}; exec ${watchCommand}'`;
-        if (terminal === 'alacritty' || terminal === 'kitty') {
-            return {
-                ok: true,
-                command: terminal,
-                args: ['--class', 'peaks-cli-progress', ...titleArg, '-e', bannerShell]
-            };
-        }
-        if (terminal === 'gnome-terminal' || terminal === 'tilix' || terminal === 'xfce4-terminal') {
-            return {
-                ok: true,
-                command: terminal,
-                args: [...titleArg, '--', '/bin/bash', '-lc', bannerShell]
-            };
-        }
-        if (terminal === 'konsole') {
-            return {
-                ok: true,
-                command: terminal,
-                args: ['--title', windowTitle, '--p', 'tabtitle', windowTitle, '-e', bannerShell]
-            };
-        }
-        // xterm / fallback: no --title support; bannerShell only.
-        return { ok: true, command: terminal, args: ['-e', bannerShell] };
-    }
-    if (currentPlatform === 'win32') {
-        if (!winTitleCmd.ok) {
-            return { ok: false, unsupported: true };
-        }
-        const bannerCmd = `${winTitleCmd.cmd} && echo peaks-cli --- sub-agent progress && ${watchCommand}`;
-        return {
-            ok: true,
-            command: 'cmd',
-            // Wrap bannerCmd in an EXTRA pair of outer quotes so the OUTER
-            // `cmd /c`'s script parser sees the banner as a single arg
-            // (not a `&&`-chained script). The INNER `cmd /k` in the new
-            // window strips the extra outer quotes and parses the banner
-            // as a normal script. windowTitle is left unquoted: Node's
-            // spawn applies the correct Windows escaping naturally,
-            // which is more robust than pre-quoting.
-            args: ['/c', 'start', windowTitle, 'cmd', '/k', `"${bannerCmd}"`]
-        };
-    }
-    return { ok: false, unsupported: true };
-}

package/dist/src/cli/commands/progress-watch-render.d.ts

@@ -1,80 +0,0 @@
-/**
- * In-place progress renderer for `peaks progress watch`.
- *
- * Goals (in order of importance):
- *   1. **In-place overwrite.** Every tick the dynamic rows
- *      (status line + progress bar) get rewritten, NOT
- *      appended. We bypass `io.stdout` (which is
- *      `console.log` and adds a trailing `\n` per call) and
- *      write directly to `process.stdout`. The cursor-up
- *      and erase-line escapes are the same ones terminal-kit
- *      emits; we do not need a terminal-kit dependency for
- *      them.
- *   2. **Clear PEAKS-CLI branding.** A static 3-line header
- *      with the brand bar, the project root, and the
- *      progress-file path is painted once. The user always
- *      sees what they are looking at, even after the
- *      watch loop has overwritten the dynamic rows a
- *      thousand times.
- *   3. **Graceful degrade.** When stdout is not a TTY
- *      (CI / pipe / `--json`), we fall back to a single
- *      static snapshot per tick (no cursor moves, no
- *      SGR colour) and a single newline. This keeps the
- *      tool scriptable without dropping into a wall of
- *      escape codes.
- *
- * Token-cost note: this module is rendered to the user's
- * terminal, never into LLM context. The watch side has
- * zero token cost.
- */
-import type { SubAgentProgress } from '../../services/progress/progress-service.js';
-export type WatchRendererOptions = {
-    projectRoot: string;
-    progressFilePath: string;
-};
-export declare class WatchRenderer {
-    private readonly projectRoot;
-    private readonly progressFilePath;
-    private readonly width;
-    private readonly isTty;
-    private hasRenderedDynamic;
-    constructor(options: WatchRendererOptions);
-    /**
-     * Paint the static header once at the top of the watch
-     * (the PEAKS-CLI wordmark, separator, project, path). Then
-     * paint the dynamic rows for the first tick. From here on
-     * the dynamic rows are the only thing we touch.
-     */
-    start(): void;
-    /**
-     * Repaint the 2 dynamic rows in place. First call moves
-     * the cursor up N rows from the bottom of the previously
-     * painted block; subsequent calls do the same.
-     */
-    tick(data: SubAgentProgress | null, tickCount: number): void;
-    private paintDynamicOnce;
-    /**
-     * Paint a final 2-line verdict + a farewell line below the
-     * dashboard, then return. The cursor stays at the bottom
-     * of the farewell so the user's shell prompt lands on the
-     * next row.
-     */
-    finalize(data: SubAgentProgress): void;
-    /**
-     * Force a non-ANSI snapshot of the current state, used by
-     * the `--once` mode and for fallback when stdout is not a
-     * TTY. Does NOT touch the cursor state — safe to call from
-     * any context.
-     */
-    static snapshot(data: SubAgentProgress | null): {
-        status: string;
-        bar: string;
-    };
-}
-/**
- * Strip ANSI escapes from a string. Used for visible-length
- * accounting; not for re-painting.
- */
-export declare function stripAnsi(input: string): string;
-/** Reset terminal SGR — used on early-return error paths. */
-export declare function resetTerminal(): void;

package/dist/src/cli/commands/progress-watch-render.js

@@ -1,308 +0,0 @@
-/**
- * In-place progress renderer for `peaks progress watch`.
- *
- * Goals (in order of importance):
- *   1. **In-place overwrite.** Every tick the dynamic rows
- *      (status line + progress bar) get rewritten, NOT
- *      appended. We bypass `io.stdout` (which is
- *      `console.log` and adds a trailing `\n` per call) and
- *      write directly to `process.stdout`. The cursor-up
- *      and erase-line escapes are the same ones terminal-kit
- *      emits; we do not need a terminal-kit dependency for
- *      them.
- *   2. **Clear PEAKS-CLI branding.** A static 3-line header
- *      with the brand bar, the project root, and the
- *      progress-file path is painted once. The user always
- *      sees what they are looking at, even after the
- *      watch loop has overwritten the dynamic rows a
- *      thousand times.
- *   3. **Graceful degrade.** When stdout is not a TTY
- *      (CI / pipe / `--json`), we fall back to a single
- *      static snapshot per tick (no cursor moves, no
- *      SGR colour) and a single newline. This keeps the
- *      tool scriptable without dropping into a wall of
- *      escape codes.
- *
- * Token-cost note: this module is rendered to the user's
- * terminal, never into LLM context. The watch side has
- * zero token cost.
- */
-import chalk from 'chalk';
-// ─────────────────────────────────────────────────────────────────────
-// Raw byte writes. We do NOT go through `io.stdout` because the
-// default `io.stdout` is `console.log` and appends a trailing
-// newline, which would defeat in-place overwrite.
-// ─────────────────────────────────────────────────────────────────────
-function rawWrite(text) {
-    process.stdout.write(text);
-}
-/**
- * Number of lines that the dynamic dashboard occupies. We
- * rewrite exactly this many rows per tick via cursor-up +
- * erase-line, so the static header above and the
- * `press Ctrl-C` footer below stay put.
- */
-const DYNAMIC_LINES = 2;
-/** ANSI: cursor up N rows. */
-const CURSOR_UP_N = (n) => `\x1b[${n}A`;
-/** ANSI: erase the current row from cursor to end-of-line. */
-const ERASE_LINE = '\x1b[2K';
-/** ANSI: reset all SGR attributes. */
-const RESET = '\x1b[0m';
-const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const PHASE_LABEL = {
-    starting: 'starting',
-    running: 'running',
-    verifying: 'verifying',
-    completing: 'completing',
-    finished: 'finished',
-    failed: 'failed',
-    idle: 'idle'
-};
-const PHASE_COLOR = {
-    starting: chalk.cyan,
-    running: chalk.cyan,
-    verifying: chalk.cyan,
-    completing: chalk.cyan,
-    finished: chalk.green,
-    failed: chalk.red,
-    idle: chalk.gray
-};
-function pickSpinnerFrame(tick) {
-    return SPINNER_FRAMES[Math.abs(tick) % SPINNER_FRAMES.length];
-}
-function formatElapsed(ms) {
-    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
-    const hours = Math.floor(totalSeconds / 3600);
-    const minutes = Math.floor((totalSeconds % 3600) / 60);
-    const seconds = totalSeconds % 60;
-    if (hours > 0) {
-        return `${hours}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
-    }
-    return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
-}
-/**
- * `elapsedMs` based fake progress, 0..1, capped at 1 after
- * 10 minutes. Visual cue that the watch is alive; NOT a real
- * percent-complete.
- */
-function computeFakeProgress(data) {
-    if (data === null)
-        return 0;
-    const startedAtMs = new Date(data.current.startedAt).getTime();
-    if (Number.isNaN(startedAtMs))
-        return 0;
-    const elapsedMs = Math.max(0, Date.now() - startedAtMs);
-    const upperBoundMs = 10 * 60 * 1000;
-    return Math.min(1, elapsedMs / upperBoundMs);
-}
-// ─────────────────────────────────────────────────────────────────────
-// ASCII art for the PEAKS-CLI brand bar. Kept in code (not a
-// dependency) so the user sees the brand even when terminal-kit
-// is unavailable.
-// ─────────────────────────────────────────────────────────────────────
-/**
- * Three-row ASCII wordmark for PEAKS-CLI. Each letter is 5
- * columns wide; P-E-A-K-S take 5 letters (25 cols), the
- * dash takes 9 cols (with surrounding space), C-L-I take 3
- * letters (15 cols). Total ≈ 49 cols, fits in 80-col
- * terminals without wrapping.
- *
- * The block-character density (full blocks on the
- * prominent rows) makes the brand visually dominant
- * against the gray "sub-agent progress watch" tagline
- * that sits below — so the user always knows whose
- * dashboard they are looking at, even when the title
- * bar is hidden.
- */
-const PEAKS_CLI_ASCII = [
-    '█████  █████  █████  ██  ██  ██████         █████  ██      ███',
-    '█   █  █   █  █   █ ██  ██    ██             ██    ██      ██ ',
-    '█████  █████  █████  ██████    ██             ████  █████   ███'
-];
-/**
- * Render the static header: the three-line big PEAKS-CLI
- * wordmark, a separator, a small "sub-agent progress watch"
- * tagline, and the project / file path. Painted ONCE at the
- * top of the watch, then never touched again.
- *
- * Visual hierarchy (per user feedback):
- *   1. PEAKS-CLI — 3-line big block art, bold cyan
- *   2. separator
- *   3. sub-agent progress watch — 1 line, smaller, gray
- *   4. project / path — 1 line each, gray
- */
-function renderHeader(projectRoot, progressFilePath, isTty) {
-    if (!isTty) {
-        // Non-TTY: emit a single header line, no colour. The
-        // dashboard still emits 2 dynamic lines per tick, so
-        // consumers that need to parse the output can rely on
-        // a known line count.
-        return [
-            `PEAKS-CLI · sub-agent progress watch · project=${projectRoot}`,
-            `path: ${progressFilePath}`
-        ].join('\n') + '\n';
-    }
-    // PEAKS-CLI block-art rows in bold cyan (the "big" brand).
-    const brandLines = PEAKS_CLI_ASCII.map((row) => chalk.bold.cyan(`  ${row}`));
-    // The tagline below the brand — small, gray, no big
-    // chrome. The user sees the brand first, the
-    // descriptor second.
-    const tagline = chalk.gray('  sub-agent progress watch');
-    const projLine = chalk.gray(`  project: ${projectRoot}`);
-    const pathLine = chalk.gray(`  path:    ${progressFilePath}`);
-    const separator = chalk.gray('  ' + '─'.repeat(60));
-    return [
-        brandLines[0] ?? '',
-        brandLines[1] ?? '',
-        brandLines[2] ?? '',
-        separator,
-        tagline,
-        projLine,
-        pathLine,
-        ''
-    ].join('\n');
-}
-/**
- * Render the 2-line dynamic dashboard. Status row on top
- * (spinner + phase + elapsed + step), progress bar on the
- * bottom. When `data` is null (no progress file yet), we
- * still show a live spinner + a "waiting…" message so the
- * user knows the watch is alive.
- */
-function renderDynamicRows(data, tick, width, isTty) {
-    const progressFraction = computeFakeProgress(data);
-    if (data === null) {
-        return {
-            status: isTty
-                ? `  ${chalk.gray(pickSpinnerFrame(tick))}  ${chalk.gray('idle')}    ${chalk.gray('(no progress file yet — sub-agent has not started)')}`
-                : `idle (no progress file yet)`,
-            bar: isTty ? renderBar(0, width, isTty) : ''
-        };
-    }
-    const startedAtMs = new Date(data.current.startedAt).getTime();
-    const elapsedMs = Number.isNaN(startedAtMs) ? 0 : Math.max(0, Date.now() - startedAtMs);
-    const phase = PHASE_LABEL[data.current.phase];
-    const step = data.current.step.length > 60 ? data.current.step.slice(0, 57) + '...' : data.current.step;
-    const verdict = data.current.verdict ? `  verdict=${data.current.verdict}` : '';
-    const role = data.role ? `  role=${data.role}` : '';
-    const spinner = pickSpinnerFrame(tick);
-    if (!isTty) {
-        return {
-            status: `${spinner} ${phase} ${formatElapsed(elapsedMs)} ${step}${role}${verdict}`,
-            bar: ''
-        };
-    }
-    const colorize = PHASE_COLOR[data.current.phase] ?? chalk.cyan;
-    const spinnerColor = phase === 'failed' ? chalk.red
-        : phase === 'finished' ? chalk.green
-            : chalk.cyan;
-    const statusLine = `  ${spinnerColor(spinner)}  ${colorize(phase.padEnd(11))}  ${chalk.yellow(formatElapsed(elapsedMs))}  ${step}${chalk.gray(role)}${verdict ? chalk.gray(verdict) : ''}`;
-    return {
-        status: statusLine,
-        bar: renderBar(progressFraction, width, isTty)
-    };
-}
-function renderBar(fraction, width, isTty) {
-    if (!isTty)
-        return '';
-    // 8ths-of-cell block characters: ░ (empty) U+2591, full blocks
-    // U+2588..U+258F for the partial last cell.
-    const barCells = Math.max(10, Math.min(50, Math.floor(width * 0.4)));
-    const filled = Math.round(barCells * Math.max(0, Math.min(1, fraction)) * 8);
-    const fullBlocks = Math.floor(filled / 8);
-    const fracBlock = filled % 8;
-    const emptyCells = barCells * 8 - filled;
-    const fullStr = '█'.repeat(fullBlocks);
-    const fracStr = fracBlock > 0 ? String.fromCharCode(0x2588 + (8 - fracBlock)) : '';
-    const emptyStr = '░'.repeat(Math.floor(emptyCells / 8));
-    const percent = String(Math.round(fraction * 100)).padStart(3, ' ');
-    return `  ${chalk.green(fullStr + fracStr + emptyStr)}  ${chalk.gray(`${percent}%`)}`;
-}
-export class WatchRenderer {
-    projectRoot;
-    progressFilePath;
-    width;
-    isTty;
-    hasRenderedDynamic = false;
-    constructor(options) {
-        this.projectRoot = options.projectRoot;
-        this.progressFilePath = options.progressFilePath;
-        this.width = (process.stdout.columns ?? 120) - 1;
-        this.isTty = process.stdout.isTTY === true;
-    }
-    /**
-     * Paint the static header once at the top of the watch
-     * (the PEAKS-CLI wordmark, separator, project, path). Then
-     * paint the dynamic rows for the first tick. From here on
-     * the dynamic rows are the only thing we touch.
-     */
-    start() {
-        rawWrite(renderHeader(this.projectRoot, this.progressFilePath, this.isTty));
-        this.paintDynamicOnce(null, 0);
-    }
-    /**
-     * Repaint the 2 dynamic rows in place. First call moves
-     * the cursor up N rows from the bottom of the previously
-     * painted block; subsequent calls do the same.
-     */
-    tick(data, tickCount) {
-        if (this.hasRenderedDynamic) {
-            // Move cursor up to the top of the previously-painted
-            // dynamic block.
-            rawWrite(CURSOR_UP_N(DYNAMIC_LINES));
-        }
-        this.paintDynamicOnce(data, tickCount);
-    }
-    paintDynamicOnce(data, tick) {
-        const { status, bar } = renderDynamicRows(data, tick, this.width, this.isTty);
-        // Erase-then-rewrite the status row.
-        rawWrite(ERASE_LINE + status + '\n');
-        // Erase-then-rewrite the bar row. (In non-TTY mode the
-        // bar is empty; we still emit a newline so the line
-        // count stays consistent.)
-        rawWrite(ERASE_LINE + bar + '\n');
-        this.hasRenderedDynamic = true;
-    }
-    /**
-     * Paint a final 2-line verdict + a farewell line below the
-     * dashboard, then return. The cursor stays at the bottom
-     * of the farewell so the user's shell prompt lands on the
-     * next row.
-     */
-    finalize(data) {
-        // Rewrite the dynamic block one last time so the user can
-        // read the verdict.
-        if (this.hasRenderedDynamic) {
-            rawWrite(CURSOR_UP_N(DYNAMIC_LINES));
-        }
-        this.paintDynamicOnce(data, Number.MAX_SAFE_INTEGER);
-        // Then emit the farewell BELOW the dashboard, in green.
-        const verdictSuffix = data.current.verdict !== undefined ? ` (verdict=${data.current.verdict})` : '';
-        const farewell = this.isTty
-            ? chalk.green(`✔ peaks progress watch: sub-agent reached phase=${data.current.phase}${verdictSuffix} at ${new Date().toISOString()}. Auto-closing watch window.`)
-            : `peaks progress watch: sub-agent reached phase=${data.current.phase}${verdictSuffix} at ${new Date().toISOString()}. Auto-closing watch window.`;
-        rawWrite(ERASE_LINE + farewell + '\n');
-    }
-    /**
-     * Force a non-ANSI snapshot of the current state, used by
-     * the `--once` mode and for fallback when stdout is not a
-     * TTY. Does NOT touch the cursor state — safe to call from
-     * any context.
-     */
-    static snapshot(data) {
-        return renderDynamicRows(data, 0, 80, false);
-    }
-}
-/**
- * Strip ANSI escapes from a string. Used for visible-length
- * accounting; not for re-painting.
- */
-export function stripAnsi(input) {
-    // eslint-disable-next-line no-control-regex
-    return input.replace(/\x1b\[[0-9;]*m/g, '');
-}
-/** Reset terminal SGR — used on early-return error paths. */
-export function resetTerminal() {
-    rawWrite(RESET);
-}