@vertaaux/cli 0.4.0 → 0.5.1

package/dist/app/interactive-app.js

@@ -0,0 +1,328 @@
+/**
+ * InteractiveApp — Persistent 3-section interactive CLI shell.
+ *
+ * Manages a fixed layout:
+ *   [Header]   — sticky banner at top (buildFrame3)
+ *   [Canvas]   — active view content, fixed height
+ *   [Footer]   — status left, keyboard shortcuts right
+ *
+ * Uses alternate screen buffer (CSI ?1049h/l) so the layout is scroll-proof.
+ * Each frame redraw uses cursor.home + screen.clear — no cursor arithmetic needed.
+ *
+ * All writes go to the injected output stream (defaults to process.stderr).
+ * stdout is reserved for --format json output.
+ */
+import { cursor, screen, getTerminalWidth, getTerminalHeight, isTTY, FRAME_INTERVAL, } from "@vertaaux/tui";
+import { renderHeader } from "./layout/header.js";
+import { renderFooter } from "./layout/footer.js";
+import { renderCanvas } from "./layout/canvas.js";
+import { getVersion } from "../ui/banner.js";
+import { HelpOverlayView } from "./views/help-overlay.js";
+// Default keyboard shortcuts shown in the footer when no view is active
+const DEFAULT_SHORTCUTS = ["↑↓ navigate", "↵ select", "F1 help", "^C quit"];
+// Shortcuts shown when a command view is active
+const COMMAND_SHORTCUTS = ["Esc back", "F1 help", "^C quit"];
+/**
+ * InteractiveApp provides the persistent 3-section layout for the
+ * `vertaa` (no-args) interactive mode.
+ *
+ * Usage:
+ *   const app = new InteractiveApp();
+ *   await app.run(); // blocks until Ctrl+C or app.dispose()
+ */
+export class InteractiveApp {
+    /** @internal — exposed for testing via private access */
+    _state = {
+        screen: "menu",
+        statusText: "Ready",
+        activeView: null,
+    };
+    /**
+     * Whether the app is currently on the alternate screen.
+     * @internal — exposed for testing
+     */
+    entered = false;
+    /** @internal — exposed for testing */
+    _suspended = false;
+    output;
+    tickTimer = null;
+    resizeTimer = null;
+    frameIndex = 0;
+    version;
+    resolveRun = null;
+    /** Saved menu view so we can restore it after help overlay */
+    savedMenuView = null;
+    constructor(output = process.stderr) {
+        this.output = output;
+        this.version = getVersion();
+        process.stderr.on("resize", this.onResize);
+    }
+    // ── Public API ─────────────────────────────────────────────────
+    /**
+     * Start the interactive app.
+     *
+     * Enters alternate screen buffer, configures stdin for raw keyboard input,
+     * renders the initial frame, and returns a Promise that resolves when
+     * dispose() is called.
+     */
+    async run() {
+        // Enter alternate screen and hide cursor
+        this.output.write(screen.altEnter + cursor.hide);
+        this.entered = true;
+        if (isTTY()) {
+            try {
+                process.stdin.setRawMode(true);
+            }
+            catch {
+                // Non-TTY stdin or test environment — ignore
+            }
+            process.stdin.resume();
+            process.stdin.on("data", this.onKeyData);
+        }
+        this.redraw();
+        this.startTick();
+        return new Promise((resolve) => {
+            this.resolveRun = resolve;
+        });
+    }
+    /**
+     * Build the complete frame string for the current state.
+     *
+     * Frame = header + canvas + footer, sized to terminal dimensions.
+     */
+    buildFrame() {
+        const width = getTerminalWidth();
+        const height = getTerminalHeight();
+        const header = renderHeader(this.version, width);
+        const headerLines = header.split("\n").length;
+        // Footer is 2 lines (separator + status) + 1 empty line above it for spacing
+        const footerLines = 3;
+        const canvasHeight = Math.max(1, height - headerLines - footerLines);
+        const viewContent = this._state.activeView
+            ? this._state.activeView.render()
+            : "";
+        const canvas = renderCanvas(viewContent, canvasHeight, width);
+        const shortcuts = this._state.screen === "command" ? COMMAND_SHORTCUTS : DEFAULT_SHORTCUTS;
+        const footer = renderFooter({
+            statusText: this._state.statusText,
+            shortcuts,
+            width,
+        });
+        // Assemble: header ends with \n\n, canvas has no trailing \n, empty line before footer
+        return header + canvas + "\n\n" + footer;
+    }
+    /**
+     * Redraw the terminal using home+clear on the alternate screen.
+     *
+     * Guarded by `if (!this.entered) return` — prevents double-redraw race
+     * when setView() calls this.redraw() after onMount() completes while
+     * the app is suspended (entered === false).
+     */
+    redraw() {
+        if (!this.entered)
+            return;
+        const frame = this.buildFrame();
+        this.output.write(cursor.home + screen.clear + frame);
+    }
+    /**
+     * Set the active view, calling lifecycle hooks.
+     *
+     * Unmounts any existing view, mounts the new one, switches to command
+     * screen, and triggers an immediate redraw.
+     *
+     * NOTE: When the app is suspended (entered === false), the post-onMount
+     * redraw() call is a safe no-op — guarded by the `!this.entered` check.
+     */
+    async setView(view) {
+        if (this._state.activeView?.onUnmount) {
+            await this._state.activeView.onUnmount();
+        }
+        this._state.activeView = view;
+        this._state.screen = "command";
+        if (view.onMount) {
+            await view.onMount();
+        }
+        this.redraw();
+    }
+    /**
+     * Unmount the active view and return to the menu screen.
+     */
+    async clearView() {
+        if (this._state.activeView?.onUnmount) {
+            await this._state.activeView.onUnmount();
+        }
+        this._state.activeView = null;
+        this._state.screen = "menu";
+        this._state.statusText = "Ready";
+        this.redraw();
+    }
+    /**
+     * Suspend the app — exit alternate screen and stop the tick loop.
+     *
+     * Call before launching @inquirer/prompts or running a command handler
+     * to hand control back to the normal terminal.
+     */
+    suspend() {
+        this._suspended = true;
+        this.stopTick();
+        // Release stdin so command handlers and @inquirer/prompts can use it
+        try {
+            process.stdin.removeListener("data", this.onKeyData);
+            if (isTTY()) {
+                try {
+                    process.stdin.setRawMode(false);
+                }
+                catch {
+                    // Ignore in non-TTY environments
+                }
+            }
+        }
+        catch {
+            // Ignore listener removal errors
+        }
+        this.output.write(cursor.show + screen.altExit);
+        this.entered = false;
+    }
+    /**
+     * Resume the app — re-enter alternate screen and restart the tick loop.
+     *
+     * Call after a command handler completes to restore the interactive layout.
+     */
+    resume() {
+        this._suspended = false;
+        // Reclaim stdin for interactive app key handling
+        if (isTTY()) {
+            try {
+                process.stdin.setRawMode(true);
+            }
+            catch {
+                // Ignore in non-TTY environments
+            }
+            process.stdin.resume();
+            process.stdin.on("data", this.onKeyData);
+        }
+        this.output.write(screen.altEnter + cursor.hide);
+        this.entered = true;
+        this.redraw();
+        this.startTick();
+    }
+    /**
+     * Tear down the app — exits alternate screen, stops tick, removes listeners.
+     */
+    dispose() {
+        this.stopTick();
+        if (this.resizeTimer !== null) {
+            clearTimeout(this.resizeTimer);
+            this.resizeTimer = null;
+        }
+        process.stderr.removeListener("resize", this.onResize);
+        try {
+            process.stdin.removeListener("data", this.onKeyData);
+            if (isTTY()) {
+                try {
+                    process.stdin.setRawMode(false);
+                }
+                catch {
+                    // Ignore in non-TTY test environments
+                }
+                process.stdin.pause();
+            }
+        }
+        catch {
+            // Ignore listener removal errors in test environments
+        }
+        // Exit alternate screen and show cursor
+        this.output.write(cursor.show + screen.altExit);
+        this.entered = false;
+        if (this.resolveRun) {
+            this.resolveRun();
+            this.resolveRun = null;
+        }
+    }
+    /** Get the current animation frame index (for spinner rendering in views). */
+    getFrameIndex() {
+        return this.frameIndex;
+    }
+    // ── Private helpers ─────────────────────────────────────────────
+    startTick() {
+        if (this.tickTimer !== null || this._suspended)
+            return;
+        this.tickTimer = setInterval(() => {
+            this.frameIndex++;
+            if (!this._suspended) {
+                this.redraw();
+            }
+        }, FRAME_INTERVAL);
+    }
+    stopTick() {
+        if (this.tickTimer !== null) {
+            clearInterval(this.tickTimer);
+            this.tickTimer = null;
+        }
+    }
+    onResize = () => {
+        if (this.resizeTimer !== null) {
+            clearTimeout(this.resizeTimer);
+        }
+        this.resizeTimer = setTimeout(() => {
+            this.resizeTimer = null;
+            // Alternate screen doesn't need cursor math reset — just redraw
+            if (!this._suspended) {
+                this.redraw();
+            }
+        }, 100);
+    };
+    onKeyData = (data) => {
+        const key = data.toString();
+        const ctrl = key.length === 1 && data[0] < 32 && data[0] !== 27;
+        const meta = key.startsWith("\x1b") && key.length > 1;
+        // F1 is always handled at app level (before view delegation)
+        if (key === "\x1bOP" || key === "\x1b[11~") {
+            if (this._state.screen === "help") {
+                // Restore saved view
+                this._state.activeView = this.savedMenuView;
+                this.savedMenuView = null;
+                this._state.screen = "menu";
+            }
+            else {
+                // Save current view and show help overlay
+                this.savedMenuView = this._state.activeView;
+                this._state.activeView = new HelpOverlayView(() => {
+                    this._state.activeView = this.savedMenuView;
+                    this.savedMenuView = null;
+                    this._state.screen = "menu";
+                    this.redraw();
+                });
+                this._state.screen = "help";
+            }
+            this.redraw();
+            return;
+        }
+        // Delegate to active view
+        if (this._state.activeView?.handleKey) {
+            const consumed = this._state.activeView.handleKey(key, ctrl, meta);
+            if (consumed)
+                return;
+        }
+        // App-level key handling
+        if (ctrl && key === "\x03") {
+            // Ctrl+C — unmount active view before exiting
+            if (this._state.activeView?.onUnmount) {
+                void this._state.activeView.onUnmount().finally(() => {
+                    this.dispose();
+                    process.exit(0);
+                });
+            }
+            else {
+                this.dispose();
+                process.exit(0);
+            }
+        }
+        else if (key === "\x1b" || key === "\x1b[") {
+            // Escape or Escape sequence
+            if (this._state.screen === "command" || this._state.screen === "help") {
+                void this.clearView();
+            }
+        }
+    };
+}

package/dist/app/layout/canvas.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Canvas section renderer for the InteractiveApp shell.
+ *
+ * The canvas is the middle section between header and footer. It receives
+ * the active view's rendered string and enforces a fixed height so that
+ * cursor arithmetic remains stable across frames.
+ *
+ * Rules:
+ *  - Returns exactly `availableHeight` lines always
+ *  - If content is shorter: pad with empty lines
+ *  - If content is longer: truncate (the view owns internal scrolling)
+ *  - Each line is truncated to `width` visible characters
+ */
+/**
+ * Render the canvas section with a fixed height.
+ *
+ * @param content - Output from the active CommandView's render()
+ * @param availableHeight - Exact number of lines to occupy (terminalHeight - headerHeight - footerHeight)
+ * @param width - Terminal width in columns for line truncation
+ * @returns String of exactly `availableHeight` lines joined by "\n" (no trailing newline)
+ */
+export declare function renderCanvas(content: string, availableHeight: number, width: number): string;
+//# sourceMappingURL=canvas.d.ts.map

package/dist/app/layout/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../../src/app/layout/canvas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,MAAM,GACZ,MAAM,CAgBR"}

package/dist/app/layout/canvas.js

@@ -0,0 +1,36 @@
+/**
+ * Canvas section renderer for the InteractiveApp shell.
+ *
+ * The canvas is the middle section between header and footer. It receives
+ * the active view's rendered string and enforces a fixed height so that
+ * cursor arithmetic remains stable across frames.
+ *
+ * Rules:
+ *  - Returns exactly `availableHeight` lines always
+ *  - If content is shorter: pad with empty lines
+ *  - If content is longer: truncate (the view owns internal scrolling)
+ *  - Each line is truncated to `width` visible characters
+ */
+import { truncate } from "@vertaaux/tui";
+/**
+ * Render the canvas section with a fixed height.
+ *
+ * @param content - Output from the active CommandView's render()
+ * @param availableHeight - Exact number of lines to occupy (terminalHeight - headerHeight - footerHeight)
+ * @param width - Terminal width in columns for line truncation
+ * @returns String of exactly `availableHeight` lines joined by "\n" (no trailing newline)
+ */
+export function renderCanvas(content, availableHeight, width) {
+    if (availableHeight <= 0)
+        return "";
+    const lines = content === "" ? [] : content.split("\n");
+    // Truncate each line to terminal width
+    const truncated = lines.map((line) => truncate(line, width));
+    if (truncated.length >= availableHeight) {
+        // Trim to fit — the view owns internal scrolling, we just enforce the boundary
+        return truncated.slice(0, availableHeight).join("\n");
+    }
+    // Pad with empty lines to maintain fixed height for cursor arithmetic
+    const padding = Array(availableHeight - truncated.length).fill("");
+    return [...truncated, ...padding].join("\n");
+}

package/dist/app/layout/footer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Footer section renderer for the InteractiveApp shell.
+ *
+ * Renders a 2-line sticky footer:
+ *   Line 1: thin separator (dim horizontal rule)
+ *   Line 2: status text left, keyboard shortcuts right
+ *
+ * All ANSI-aware padding uses visibleLength() to avoid width drift from
+ * escape codes.
+ */
+/** Options for renderFooter */
+export interface FooterOptions {
+    /** Status message shown on the left (e.g. "Ready", "Running audit...") */
+    statusText: string;
+    /** Keyboard shortcuts shown on the right (e.g. ["↑↓ navigate", "↵ select", "H help", "^C quit"]) */
+    shortcuts: string[];
+    /** Terminal width in columns */
+    width: number;
+}
+/**
+ * Render the footer section.
+ *
+ * Returns exactly 2 lines:
+ *  - A dim separator spanning the full width
+ *  - Status text aligned left, shortcuts joined right
+ *
+ * @param opts - Footer options
+ * @returns 2-line string (no trailing newline)
+ */
+export declare function renderFooter(opts: FooterOptions): string;
+//# sourceMappingURL=footer.d.ts.map

package/dist/app/layout/footer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"footer.d.ts","sourceRoot":"","sources":["../../../src/app/layout/footer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAsBxD"}

package/dist/app/layout/footer.js

@@ -0,0 +1,41 @@
+/**
+ * Footer section renderer for the InteractiveApp shell.
+ *
+ * Renders a 2-line sticky footer:
+ *   Line 1: thin separator (dim horizontal rule)
+ *   Line 2: status text left, keyboard shortcuts right
+ *
+ * All ANSI-aware padding uses visibleLength() to avoid width drift from
+ * escape codes.
+ */
+import { dim, bold, visibleLength, padEnd } from "@vertaaux/tui";
+/**
+ * Render the footer section.
+ *
+ * Returns exactly 2 lines:
+ *  - A dim separator spanning the full width
+ *  - Status text aligned left, shortcuts joined right
+ *
+ * @param opts - Footer options
+ * @returns 2-line string (no trailing newline)
+ */
+export function renderFooter(opts) {
+    const { statusText, shortcuts, width } = opts;
+    // Line 1: thin separator
+    const separator = dim("─".repeat(Math.max(0, width)));
+    // Line 2: status left, shortcuts right
+    const shortcutStr = shortcuts.map((s) => bold(s)).join(dim("  "));
+    const shortcutLen = visibleLength(shortcutStr);
+    const statusLen = visibleLength(statusText);
+    const gap = width - statusLen - shortcutLen;
+    let statusLine;
+    if (gap > 0) {
+        // Pad status text to push shortcuts to the right
+        statusLine = padEnd(statusText, width - shortcutLen) + shortcutStr;
+    }
+    else {
+        // Not enough space — just show status, truncate if needed
+        statusLine = statusText.slice(0, Math.max(0, width));
+    }
+    return separator + "\n" + statusLine;
+}

package/dist/app/layout/header.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Header section renderer for the InteractiveApp shell.
+ *
+ * Renders the static banner (Frame 3 — full lime→cyan gradient) as the
+ * persistent top section. No animation in interactive mode since the
+ * app is already running.
+ */
+/**
+ * Render the header section.
+ *
+ * Returns the full gradient banner (Frame 3) with lines truncated
+ * to the terminal width. The banner provides visual identity and
+ * occupies the sticky top of the 3-section layout.
+ *
+ * @param version - CLI version string (e.g. "1.2.3")
+ * @param width - Terminal width in columns
+ * @returns Multi-line string ready to write to stderr
+ */
+export declare function renderHeader(version: string, width: number): string;
+//# sourceMappingURL=header.d.ts.map

package/dist/app/layout/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../src/app/layout/header.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnE"}

package/dist/app/layout/header.js

@@ -0,0 +1,27 @@
+/**
+ * Header section renderer for the InteractiveApp shell.
+ *
+ * Renders the static banner (Frame 3 — full lime→cyan gradient) as the
+ * persistent top section. No animation in interactive mode since the
+ * app is already running.
+ */
+import { truncate } from "@vertaaux/tui";
+import { buildFrame3 } from "../../ui/banner.js";
+/**
+ * Render the header section.
+ *
+ * Returns the full gradient banner (Frame 3) with lines truncated
+ * to the terminal width. The banner provides visual identity and
+ * occupies the sticky top of the 3-section layout.
+ *
+ * @param version - CLI version string (e.g. "1.2.3")
+ * @param width - Terminal width in columns
+ * @returns Multi-line string ready to write to stderr
+ */
+export function renderHeader(version, width) {
+    const frame = buildFrame3(version, process.cwd());
+    // Trim the trailing double newline so the caller controls spacing
+    const trimmed = frame.replace(/\n+$/, "");
+    const lines = trimmed.split("\n");
+    return lines.map((line) => truncate(line, width)).join("\n") + "\n\n";
+}

package/dist/app/menu/categories.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Command category definitions for the interactive menu.
+ *
+ * 6 groups of 23 interactive-safe commands matching the TUI runner.
+ * Each MenuItem.value must exactly match the Commander command name.
+ */
+import type { CommandCategory, MenuItem } from "../types.js";
+/**
+ * All interactive-safe commands organized into 6 semantic groups.
+ *
+ * Groups follow a natural user workflow:
+ *   Audit → Results → Fixes → Reports → Project → Account
+ */
+export declare const COMMAND_CATEGORIES: CommandCategory[];
+/**
+ * Returns a flat list of all MenuItem entries across all categories.
+ * Useful for quick lookups by command value.
+ */
+export declare function allMenuItems(): MenuItem[];
+//# sourceMappingURL=categories.d.ts.map

package/dist/app/menu/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../../src/app/menu/categories.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAAe,EAkJ/C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,IAAI,QAAQ,EAAE,CAEzC"}