devflow-kit 1.8.2 → 2.0.0

package/dist/cli/agents-view/state.js

@@ -0,0 +1,423 @@
+/**
+ * Pure keypress reducer for the devflow agents TUI.
+ *
+ * applies ADR-013: CLI-layer view module; consumes src/core/ imports only.
+ * avoids PF-014: pure functions only — no process.exit(), no I/O.
+ *
+ * Model cycle (proxy ON):  default → haiku → sonnet → opus → fable →
+ *                          <picker names in registry order> → default
+ *                          Picker names: all aliases for each model; canonical id iff
+ *                          the model has no aliases (zero-maintenance, catalog-driven).
+ * Model cycle (proxy OFF): default → haiku → sonnet → opus → fable → default
+ * Effort cycle:            default → low → medium → high → xhigh → max → default
+ *
+ * Dormancy semantics (plan D5 / Phase 1):
+ *   When proxy is off and a row's saved model is a GPT model, configuredModel
+ *   starts as 'default' and the saved GPT name is kept in dormantModel for
+ *   display annotation and untouched-preservation on save.
+ *
+ * Off-cycle pin semantics (Phase D):
+ *   When proxy is on and a row's saved model is absent from the discovered
+ *   selectableNames (retired model), offCyclePin holds the saved model.
+ *   The per-row effective cycle is [...modelCycle, offCyclePin], so the
+ *   pin is always reachable after a full cycle without pressing 'd'.
+ *
+ * Dirty detection: current !== original (touch-then-revert → not dirty).
+ *
+ * Performance (AC-P6): modelCycle is built ONCE in buildTuiState and stored
+ * on the state — never reallocated per keypress. The reducer receives it as
+ * state.modelCycle and threads it through without reconstructing.
+ */
+import { EFFORT_LEVELS } from '../../core/agent-models.js';
+import { CLAUDE_MODEL_ALIASES, isDormantExternalModel, } from '../../core/external-models.js';
+import { classifyAgentState, } from '../../core/agent-state.js';
+// ---------------------------------------------------------------------------
+// Cycle builders (pure)
+// ---------------------------------------------------------------------------
+/**
+ * The picker names for a single model: all aliases when the model has any,
+ * or the canonical id when it has none. This is the single alias-selection
+ * site — both `pickerNames` (cycle builder) and `buildPickerNameMap` (id→alias
+ * normaliser) call it so the two can never drift.
+ *
+ * Module-private: callers consume the public wrappers below.
+ * Pure function, no I/O.
+ */
+function pickerNamesFor(model) {
+    return model.aliases.length > 0 ? model.aliases : [model.id];
+}
+/**
+ * Extract the picker name list from a model list.
+ *
+ * Zero-maintenance rule (Fix 1):
+ *   - For each model IN REGISTRY ORDER: contribute ALL of its aliases.
+ *   - Contribute the canonical ID if and only if the model has NO aliases.
+ *
+ * This means:
+ *   gpt-5.6-sol  [aliases: ['sol']]   → 'sol'
+ *   gpt-5.5      [aliases: []]        → 'gpt-5.5'
+ *   gpt-x        [aliases: ['a','b']] → 'a', 'b'
+ *
+ * When a currently-alias-less model gains an alias in a future subswitch
+ * release, it automatically renders as that alias with no code change.
+ *
+ * NOTE: catalog.selectableNames is NOT used here — it doubles as the --set
+ * validation allowlist (includes both aliases and canonical ids). Narrowing
+ * it would reject `devflow agents --set coder --model gpt-5.6-sol`.
+ *
+ * Pure function, no I/O.
+ */
+export function pickerNames(models) {
+    return models.flatMap(pickerNamesFor);
+}
+/**
+ * Build a map from every stored identifier (alias or canonical id) to the
+ * picker name that represents it in the TUI cycle.
+ *
+ * Used by buildRow to normalize a stored canonical id to its alias on read,
+ * e.g. 'gpt-5.6-sol' → 'sol', so the value stays in-cycle and does not
+ * appear as an off-cycle pin. NEVER rewrites the value on disk — only for
+ * display.
+ *
+ * Returns an empty map when the catalog is unknown.
+ *
+ * Pure function, no I/O.
+ */
+export function buildPickerNameMap(catalog) {
+    if (!catalog.known)
+        return new Map();
+    const map = new Map();
+    for (const model of catalog.models) {
+        const names = pickerNamesFor(model);
+        const [representative] = names;
+        // Canonical id → first picker name (first alias if any, else canonical id)
+        map.set(model.id, representative);
+        // Each picker name → itself (identity, already a picker name)
+        for (const name of names) {
+            map.set(name, name);
+        }
+    }
+    return map;
+}
+/**
+ * Build the model cycle from a discovered catalog.
+ * Exported so agents.ts can call it once and store the result in state.
+ *
+ * Cycle order (catalog known):
+ *   default → haiku → sonnet → opus → fable →
+ *   <picker names in registry order> → (wraps)
+ *
+ * Picker names are alias-only (canonical id only when no aliases exist),
+ * produced by pickerNames(). catalog.selectableNames is NOT used here —
+ * it is the --set validation allowlist, not the TUI picker subset.
+ *
+ * Cycle order (catalog unknown):
+ *   default → haiku → sonnet → opus → fable → (wraps)
+ *
+ * Dormancy (proxy off + GPT model saved) does not shrink the cycle — external
+ * models remain selectable so users can inspect and change dormant mappings.
+ * The catalog itself controls what is in the cycle; see selectCatalog() in
+ * agents.ts for how the proxy-off path supplies the cache-based catalog.
+ */
+export function buildModelCycle(catalog) {
+    const base = ['default', ...CLAUDE_MODEL_ALIASES];
+    if (!catalog.known)
+        return base;
+    return [...base, ...pickerNames(catalog.models)];
+}
+const EFFORT_CYCLE = ['default', ...EFFORT_LEVELS];
+function cycleNext(cycle, current) {
+    const idx = cycle.indexOf(current);
+    if (idx === -1)
+        return cycle[0];
+    return cycle[(idx + 1) % cycle.length];
+}
+function cyclePrev(cycle, current) {
+    const idx = cycle.indexOf(current);
+    if (idx === -1)
+        return cycle[cycle.length - 1];
+    return cycle[(idx - 1 + cycle.length) % cycle.length];
+}
+/**
+ * True when `model` is not present in `cycle`.
+ * Named predicate for intent visibility at every call site.
+ */
+export function isOffCycle(cycle, model) {
+    return !cycle.includes(model);
+}
+// ---------------------------------------------------------------------------
+// Dirty helpers (pure, exported for render and tests)
+// ---------------------------------------------------------------------------
+export function isDirtyModel(row) {
+    // Suppress dirty when the selected model matches the saved dormant GPT model —
+    // cycling back to that value is not a change from the persisted mapping entry.
+    if (row.dormantModel !== null && row.configuredModel === row.dormantModel)
+        return false;
+    return row.configuredModel !== row.originalModel;
+}
+export function isDirtyEffort(row) {
+    return row.configuredEffort !== row.originalEffort;
+}
+/**
+ * The model value that will be persisted to disk for this row.
+ *
+ * For a dirty row: the in-session selection (configuredModel).
+ * For an untouched dormant row: the saved GPT model (dormantModel), which
+ * preserves the mapping entry byte-identical even though configuredModel
+ * shows 'default' while the proxy is off.
+ * For all other untouched rows: configuredModel (which equals originalModel).
+ *
+ * Used by both rowState (STATE column display) and mergeTuiRowsIntoMapping
+ * (save merge) so the two surfaces share a single persisted-value predicate.
+ */
+export function persistedModelFor(row) {
+    return isDirtyModel(row) ? row.configuredModel : (row.dormantModel ?? row.configuredModel);
+}
+/**
+ * The effort value that will be persisted to disk for this row.
+ *
+ * For a dirty row: the in-session selection (configuredEffort).
+ * For an untouched row: the original effort (originalEffort).
+ *
+ * Used by both rowState (STATE column display) and mergeTuiRowsIntoMapping
+ * (save merge) so the two surfaces share a single persisted-value predicate.
+ */
+export function persistedEffortFor(row) {
+    return isDirtyEffort(row) ? row.configuredEffort : row.originalEffort;
+}
+/** Count of rows with any dirty field (model OR effort). */
+export function unsavedCount(rows) {
+    let count = 0;
+    for (const row of rows) {
+        if (isDirtyModel(row) || isDirtyEffort(row))
+            count++;
+    }
+    return count;
+}
+/**
+ * Classify the live state of a TUI row for display in the STATE column.
+ *
+ * Single source of truth — delegates to classifyAgentState, so the TUI STATE
+ * column and `--list`'s STATE column share one vocabulary and cannot drift.
+ *
+ * The classified value is the model this row WILL persist, which is what makes
+ * the dormancy marker track the KEYPRESS rather than the last save:
+ *   - dirty row      → configuredModel (the in-session selection)
+ *   - untouched row  → dormantModel when set, else configuredModel
+ *
+ * The untouched branch exists because mergeTuiRowsIntoMapping writes nothing
+ * for a clean row: its persisted value survives as-is, and for a dormant row
+ * that value lives in dormantModel (configuredModel falls back to 'default'
+ * while the proxy is off). Keying on dormantModel unconditionally would pin
+ * the marker to the pre-edit value — cycling a dormant row onto a live Claude
+ * model would keep showing 'saved-inactive' even though 'opus' is what gets
+ * written. Mirroring the merge rule keeps display and persistence in lockstep.
+ *
+ * Pure function, no I/O.
+ */
+export function rowState(row, proxyEnabled) {
+    return classifyAgentState({
+        configured: persistedModelFor(row),
+        proxyEnabled,
+        installed: row.installed,
+        inRegistry: row.inRegistry,
+    });
+}
+// ---------------------------------------------------------------------------
+// Row and field helpers (pure) — single-row update and cycle direction
+// ---------------------------------------------------------------------------
+/**
+ * Return a new rows array with the row at `cursor` replaced by `newRow`.
+ * All other rows are returned by reference (no unnecessary copies).
+ */
+function replaceRow(rows, cursor, newRow) {
+    return rows.map((r, i) => (i === cursor ? newRow : r));
+}
+/**
+ * Return a new AgentRow with the named field cycled one step in the given direction.
+ *
+ * Model cycle uses the prebuilt state.modelCycle (no allocation per call for normal
+ * rows). Off-cycle pin recovery: if row.offCyclePin is non-null, the effective cycle
+ * for this row is [...modelCycle, offCyclePin], keeping the retired model reachable
+ * after a full forward+backward navigation (AC-F4).
+ *
+ * Pure: no I/O, no side effects.
+ */
+function cycleField(row, field, dir, modelCycle) {
+    if (field === 'model') {
+        // Build effective cycle: splice off-cycle pin at the end if present.
+        // This is the ≤ 1 array allocation case (AC-P6): only allocates when offCyclePin != null.
+        const effectiveCycle = row.offCyclePin !== null && isOffCycle(modelCycle, row.offCyclePin)
+            ? [...modelCycle, row.offCyclePin]
+            : modelCycle;
+        // cycleNext/cyclePrev handle the case where configuredModel is not in effectiveCycle
+        // by falling back to cycle[0] / cycle[last]. This is correct for the off-cycle case
+        // where configuredModel IS in effectiveCycle (we splice it in above).
+        const next = dir === 'forward'
+            ? cycleNext(effectiveCycle, row.configuredModel)
+            : cyclePrev(effectiveCycle, row.configuredModel);
+        return { ...row, configuredModel: next };
+    }
+    else {
+        const next = dir === 'forward'
+            ? cycleNext(EFFORT_CYCLE, row.configuredEffort)
+            : cyclePrev(EFFORT_CYCLE, row.configuredEffort);
+        // Sound narrowing: EFFORT_CYCLE is ['default', ...EFFORT_LEVELS], so next
+        // is always EffortLevel | 'default'. cycleNext/cyclePrev return string
+        // because their signature is intentionally generic (also used for model cycles).
+        return { ...row, configuredEffort: next };
+    }
+}
+// ---------------------------------------------------------------------------
+// Viewport adjustment (pure)
+// ---------------------------------------------------------------------------
+function adjustViewport(cursor, viewportOffset, viewportHeight, rowCount) {
+    if (viewportHeight <= 0 || rowCount === 0)
+        return 0;
+    let offset = viewportOffset;
+    if (cursor < offset)
+        offset = cursor;
+    if (cursor >= offset + viewportHeight)
+        offset = cursor - viewportHeight + 1;
+    const maxOffset = Math.max(0, rowCount - viewportHeight);
+    return Math.max(0, Math.min(offset, maxOffset));
+}
+/**
+ * Build an AgentRow from initial mapping state.
+ *
+ * Handles dormancy: if savedModel is an external model and proxy is off,
+ * configuredModel starts as 'default' and dormantModel holds the saved model.
+ *
+ * Handles off-cycle pin: if proxy is on, savedModel is configured, but is
+ * absent from modelCycle (retired/unavailable model), offCyclePin is set so
+ * the model remains reachable in the per-row effective cycle.
+ */
+export function buildRow(input) {
+    const dormant = isDormantExternalModel(input.savedModel, input.proxyEnabled);
+    const cycle = input.modelCycle ?? [];
+    // Normalize stored canonical id to picker name (Fix 1: in-memory only, never
+    // written back to disk). E.g. 'gpt-5.6-sol' → 'sol' when pickerNameMap is known.
+    // This keeps the value in-cycle so it does not become a spurious off-cycle pin.
+    const normalizedSavedModel = input.savedModel !== undefined && input.pickerNameMap !== undefined
+        ? (input.pickerNameMap.get(input.savedModel) ?? input.savedModel)
+        : input.savedModel;
+    const configuredModel = dormant ? 'default' : (normalizedSavedModel ?? 'default');
+    const configuredEffort = input.savedEffort ?? 'default';
+    // Off-cycle pin detection: proxy on, model configured but absent from cycle.
+    // Use the normalized model for cycle lookup — the saved model (pre-norm) for
+    // the pin value so the original identifier is preserved on display.
+    const offCyclePin = !dormant &&
+        normalizedSavedModel !== undefined &&
+        normalizedSavedModel !== 'default' &&
+        cycle.length > 0 &&
+        isOffCycle(cycle, normalizedSavedModel)
+        ? normalizedSavedModel
+        : null;
+    return {
+        name: input.name,
+        shippedDefault: input.shippedDefault,
+        configuredModel,
+        originalModel: configuredModel,
+        configuredEffort,
+        originalEffort: configuredEffort,
+        dormantModel: dormant ? (input.savedModel ?? null) : null,
+        offCyclePin,
+        installed: input.installed,
+        inRegistry: input.inRegistry,
+    };
+}
+// ---------------------------------------------------------------------------
+// reduce
+// ---------------------------------------------------------------------------
+/**
+ * Pure keypress reducer.
+ *
+ * Recognized key strings (normalized by terminal.ts):
+ *   'up', 'down', 'left', 'right', 'k', 'j', 'tab', 'space',
+ *   'd', 'enter', 'escape', 'q', 'ctrl-c'
+ *
+ * Unknown keys → intent 'none', state unchanged (same reference).
+ *
+ * Performance: modelCycle is read from state (prebuilt, startup-constant);
+ * the modelCycle reference is threaded unchanged through every
+ * non-cycle reduce path (AC-P6: Object.is(s1.modelCycle, s2.modelCycle)).
+ */
+export function reduce(state, key) {
+    const { rows, cursor, activeField, viewportOffset, viewportHeight, modelCycle } = state;
+    const n = rows.length;
+    switch (key) {
+        case 'up':
+        case 'k': {
+            if (n === 0)
+                return { state, intent: 'none' };
+            const newCursor = Math.max(0, cursor - 1);
+            const newOffset = adjustViewport(newCursor, viewportOffset, viewportHeight, n);
+            if (newCursor === cursor && newOffset === viewportOffset)
+                return { state, intent: 'none' };
+            return {
+                state: { ...state, cursor: newCursor, viewportOffset: newOffset },
+                intent: 'none',
+            };
+        }
+        case 'down':
+        case 'j': {
+            if (n === 0)
+                return { state, intent: 'none' };
+            const newCursor = Math.min(n - 1, cursor + 1);
+            const newOffset = adjustViewport(newCursor, viewportOffset, viewportHeight, n);
+            if (newCursor === cursor && newOffset === viewportOffset)
+                return { state, intent: 'none' };
+            return {
+                state: { ...state, cursor: newCursor, viewportOffset: newOffset },
+                intent: 'none',
+            };
+        }
+        case 'tab': {
+            const newField = activeField === 'model' ? 'effort' : 'model';
+            return { state: { ...state, activeField: newField }, intent: 'none' };
+        }
+        case 'right':
+        case 'space': {
+            if (n === 0)
+                return { state, intent: 'none' };
+            const newRow = cycleField(rows[cursor], activeField, 'forward', modelCycle);
+            return {
+                state: { ...state, rows: replaceRow(rows, cursor, newRow) },
+                intent: 'none',
+            };
+        }
+        case 'left': {
+            if (n === 0)
+                return { state, intent: 'none' };
+            const newRow = cycleField(rows[cursor], activeField, 'backward', modelCycle);
+            return {
+                state: { ...state, rows: replaceRow(rows, cursor, newRow) },
+                intent: 'none',
+            };
+        }
+        case 'd': {
+            if (n === 0)
+                return { state, intent: 'none' };
+            const row = rows[cursor];
+            const newRow = activeField === 'model'
+                ? { ...row, configuredModel: 'default' }
+                : { ...row, configuredEffort: 'default' };
+            return {
+                state: { ...state, rows: replaceRow(rows, cursor, newRow) },
+                intent: 'none',
+            };
+        }
+        case 'enter': {
+            return { state, intent: 'save' };
+        }
+        case 'escape':
+        case 'q':
+        case 'ctrl-c': {
+            return { state, intent: 'cancel' };
+        }
+        default: {
+            return { state, intent: 'none' };
+        }
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/cli/agents-view/terminal.js

@@ -0,0 +1,179 @@
+/**
+ * Thin impure shell for the devflow agents TUI.
+ *
+ * applies ADR-013: impure I/O shell in CLI layer; pure logic lives in state.ts/render.ts.
+ * avoids PF-014: all cleanup wired via Promise resolve — never process.exit() inside
+ *   a finally-guarded scope. Cleanup is idempotent and runs on save, cancel,
+ *   SIGINT, SIGTERM, and keypress limit exhaustion.
+ *
+ * Bounded: MAX_KEYPRESSES = 50_000 hard limit (reliability rule — every loop bounded).
+ *
+ * Returns a Promise resolving to { action: 'save'|'cancel', state } on any
+ * terminal event that terminates the TUI.
+ */
+import * as readline from 'readline';
+import { reduce } from './state.js';
+import { renderFrame, computeViewportHeight } from './render.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Hard upper bound on keypress events — resolves with 'cancel' on exhaustion. */
+export const MAX_KEYPRESSES = 50_000;
+// ---------------------------------------------------------------------------
+// Terminal escape sequences
+// ---------------------------------------------------------------------------
+const ESC = '\x1b';
+const ENTER_ALT = `${ESC}[?1049h`;
+const LEAVE_ALT = `${ESC}[?1049l`;
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+/** Move cursor to top-left without clearing (less flicker than full clear). */
+const HOME = `${ESC}[H`;
+/** Erase from cursor to end of line. */
+const ERASE_EOL = `${ESC}[K`;
+function normalizeKey(str, key) {
+    if (key?.ctrl && key.name === 'c')
+        return 'ctrl-c';
+    const name = key?.name ?? '';
+    switch (name) {
+        case 'up': return 'up';
+        case 'down': return 'down';
+        case 'left': return 'left';
+        case 'right': return 'right';
+        case 'tab': return 'tab';
+        case 'return': return 'enter';
+        case 'escape': return 'escape';
+        case 'space': return 'space';
+        default:
+            return str ?? name;
+    }
+}
+// ---------------------------------------------------------------------------
+// Dims / viewport
+// ---------------------------------------------------------------------------
+function getDims(stdout) {
+    return {
+        rows: stdout.rows ?? 24,
+        cols: stdout.columns ?? 80,
+    };
+}
+// ---------------------------------------------------------------------------
+// Redraw
+// ---------------------------------------------------------------------------
+function redraw(state, stdout) {
+    const dims = getDims(stdout);
+    const lines = renderFrame(state, dims);
+    let out = HOME;
+    for (const line of lines) {
+        out += line + ERASE_EOL + '\n';
+    }
+    stdout.write(out);
+}
+// ---------------------------------------------------------------------------
+// runAgentsTui
+// ---------------------------------------------------------------------------
+/**
+ * Launch the interactive agents TUI.
+ *
+ * @param initialState - Initial state built by the agents command.
+ * @param io - Optional I/O override (defaults to process.stdin/stdout). Pass fake
+ *   streams in tests to drive the TUI without a real TTY.
+ * @returns Promise resolving to { action, state } when the user saves or cancels.
+ */
+export async function runAgentsTui(initialState, io) {
+    // D-SEAM: default to process.stdin/stdout; callers (tests) may inject fakes.
+    const stdin = (io?.stdin ?? process.stdin);
+    const stdout = (io?.stdout ?? process.stdout);
+    // ── Enable readline keypress events ─────────────────────────────────────
+    // TuiIO.stdin is NodeJS.ReadableStream, which readline.emitKeypressEvents expects
+    // directly. PassThrough (tests) and process.stdin (production) both satisfy it.
+    readline.emitKeypressEvents(stdin);
+    // ── Enter alt-screen, hide cursor ───────────────────────────────────────
+    stdout.write(ENTER_ALT + HIDE_CURSOR);
+    // ── Raw mode ─────────────────────────────────────────────────────────────
+    if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(true);
+    }
+    stdin.resume();
+    return new Promise((resolve) => {
+        let state = initialState;
+        let cleaned = false;
+        let keypressCount = 0;
+        // Initial viewport size
+        const dims = getDims(stdout);
+        state = { ...state, viewportHeight: computeViewportHeight(dims.rows) };
+        redraw(state, stdout);
+        // ── Cleanup (idempotent) ───────────────────────────────────────────────
+        function cleanup() {
+            if (cleaned)
+                return;
+            cleaned = true;
+            stdin.removeListener('keypress', onKeypress);
+            process.removeListener('SIGINT', onSigint);
+            process.removeListener('SIGTERM', onSigterm);
+            stdout.removeListener('resize', onResize);
+            if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+                try {
+                    stdin.setRawMode(false);
+                }
+                catch { /* ignore */ }
+            }
+            // Pause stdin to release the ref'd TTY handle — mirrors the stdin.resume()
+            // at startup. Without this the resumed stdin keeps the event loop alive and
+            // the CLI (which has no forced process.exit) hangs after the TUI resolves.
+            stdin.pause();
+            stdout.write(LEAVE_ALT + SHOW_CURSOR);
+        }
+        function settle(result) {
+            cleanup();
+            resolve(result);
+        }
+        // ── Resize handler ─────────────────────────────────────────────────────
+        function onResize() {
+            const d = getDims(stdout);
+            state = { ...state, viewportHeight: computeViewportHeight(d.rows) };
+            redraw(state, stdout);
+        }
+        // ── Keypress handler ───────────────────────────────────────────────────
+        function onKeypress(str, key) {
+            keypressCount++;
+            if (keypressCount > MAX_KEYPRESSES) {
+                // Hard safety bound — cancel on exhaustion (avoids unbounded event loop)
+                settle({ action: 'cancel', state });
+                return;
+            }
+            const normalized = normalizeKey(str, key);
+            const { state: next, intent } = reduce(state, normalized);
+            state = next;
+            switch (intent) {
+                case 'save':
+                    settle({ action: 'save', state });
+                    return;
+                case 'cancel':
+                    settle({ action: 'cancel', state });
+                    return;
+                case 'none':
+                    redraw(state, stdout);
+                    return;
+                default: {
+                    const _ = intent;
+                    void _;
+                    redraw(state, stdout);
+                }
+            }
+        }
+        // ── Signal handlers ────────────────────────────────────────────────────
+        function onSigint() {
+            settle({ action: 'cancel', state });
+        }
+        function onSigterm() {
+            settle({ action: 'cancel', state });
+        }
+        // Register all listeners
+        stdin.on('keypress', onKeypress);
+        process.on('SIGINT', onSigint);
+        process.on('SIGTERM', onSigterm);
+        stdout.on('resize', onResize);
+    });
+}
+//# sourceMappingURL=terminal.js.map