@voidlabs.gg/voidshift 0.0.0-stage → 0.4.1

package/dist/tui/context.js

@@ -0,0 +1,48 @@
+// What every screen receives. See the contract at the top of screens.ts.
+import { createContext, useContext, useEffect } from 'react';
+import { useInput } from 'ink';
+export const ScreenCtx = createContext(null);
+export function useScreen() {
+    const ctx = useContext(ScreenCtx);
+    if (!ctx)
+        throw new Error('useScreen needs a screen');
+    return ctx;
+}
+// Key handler for screens. Silent while a dialog is open and, unless
+// `whileCapturing`, while a text field has focus.
+export function useKeys(handler, opts = {}) {
+    const ctx = useScreen();
+    useInput(handler, { isActive: !ctx.modalOpen && (opts.whileCapturing === true || !ctx.capturing) });
+}
+// Dynamic footer hints for a screen, for when its static Screen.hints is not enough.
+export function useHints(hints) {
+    const ctx = useScreen();
+    const key = JSON.stringify(hints);
+    useEffect(() => {
+        ctx.setHints(hints);
+        return () => ctx.setHints(null);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+}
+// The command a form or action equals, shown bottom right: "= vsf agents cancel ENG-12".
+export function useEquivalent(args) {
+    const ctx = useScreen();
+    const key = JSON.stringify(args);
+    useEffect(() => {
+        ctx.setCommand(args);
+        return () => ctx.setCommand(null);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+}
+// Turns global keys off while a field is focused.
+export function useCapture(active) {
+    const ctx = useScreen();
+    useEffect(() => (active ? ctx.capture() : undefined), [active]);
+}
+export function useBackGuard(fn) {
+    const ctx = useScreen();
+    useEffect(() => {
+        ctx.setBackGuard(fn);
+        return () => ctx.setBackGuard(null);
+    });
+}

package/dist/tui/data.d.ts

@@ -0,0 +1,196 @@
+import React from 'react';
+import type { Check, Tool, ToolContext } from '../tool.ts';
+export declare const POLL_MS = 2000;
+export declare const CHECKS_MS = 30000;
+export interface AgentsCurrent {
+    pid: number;
+    card?: string;
+    title?: string;
+    workflow?: string;
+    step?: string;
+    round?: number;
+    startedAt?: string;
+    runDir?: string;
+    checking?: boolean;
+    elapsedMinutes?: number;
+}
+export interface AgentsStatus {
+    engine?: string;
+    runner: 'running' | 'paused' | 'stopped';
+    lastTick: {
+        at: string;
+        line: string;
+    } | null;
+    current: AgentsCurrent | null;
+    parked: {
+        card: string;
+        reason?: string;
+    }[];
+    interrupted: string[];
+    workflows: number;
+    projects: number;
+}
+export interface StepRecord {
+    step: string;
+    label: string;
+    startedAt: string;
+    endedAt?: string;
+    result?: string;
+    summary?: string;
+    log?: string;
+}
+export interface RunRecord {
+    card: string;
+    title: string;
+    url?: string;
+    workflow: string;
+    trigger?: string;
+    steps: StepRecord[];
+    outcome: 'running' | 'verified' | 'changes' | 'parked' | 'cancelled';
+    reason?: string;
+    prUrl?: string;
+    startedAt: string;
+    endedAt?: string;
+}
+export interface RunItem {
+    card: string;
+    stamp: string;
+    dir: string;
+    logs: string[];
+    record?: RunRecord;
+}
+export interface WorkflowItem {
+    name: string;
+    triggers: {
+        source: string;
+        team: string;
+        label: string;
+    }[];
+    steps: string[];
+    maxRounds: number;
+    project: string;
+}
+export interface ProjectItem {
+    name: string;
+    path: string;
+    base?: string;
+    usedBy?: string[];
+}
+export interface HomeItem {
+    [key: string]: unknown;
+}
+export interface AwakeStatus {
+    on: boolean;
+    sleepDisabledByOther: boolean;
+    since: string | null;
+    until: string | null;
+    minutesLeft: number | null;
+    batteryFloor: number;
+    floorApplies: boolean;
+    power: {
+        onBattery: boolean;
+        percent: number | null;
+    };
+    watchdog: boolean;
+    lastReason: string | null;
+}
+export interface MemoryStatus {
+    vault: string;
+    isVault: boolean;
+    notes: number;
+    indexed: number;
+    unindexed: {
+        count: number;
+        names: string[];
+    };
+    lastUpdated: string | null;
+    homes: {
+        kind: 'claude' | 'codex';
+        dir: string;
+        recall: string;
+        skill: string;
+    }[];
+}
+export interface StepsCatalog {
+    steps: {
+        id: string;
+        name: string;
+        label: string;
+        hint: string;
+        output: string;
+    }[];
+    templates: Record<string, {
+        steps: string[];
+        maxRounds: number;
+    }>;
+}
+export interface UpdateInfo {
+    current: string;
+    latest: string | null;
+    checked: boolean;
+}
+export interface DataState {
+    version: string;
+    tools: string[];
+    agents: AgentsStatus | null;
+    awake: AwakeStatus | null;
+    memory: MemoryStatus | null;
+    runs: RunItem[];
+    workflows: WorkflowItem[];
+    projects: ProjectItem[];
+    homes: HomeItem[];
+    agentsConfig: Record<string, unknown> | null;
+    steps: StepsCatalog | null;
+    checks: Check[] | null;
+    checksAt: number | null;
+    update: UpdateInfo;
+    errors: Record<string, string>;
+    loaded: boolean;
+    at: number;
+}
+export interface Data {
+    state: DataState;
+    refresh(): void;
+    refreshChecks(): void;
+    readConfig(tool: string): Record<string, unknown> | null;
+    help(tool: string): Promise<string>;
+}
+export declare function emptyState(tools?: string[]): DataState;
+export declare function captureJson(tool: Pick<Tool, 'commands'>, command: string, args: string[], base: ToolContext): Promise<unknown>;
+export declare function captureText(tool: Pick<Tool, 'commands'>, command: string, args: string[], base: ToolContext): Promise<string>;
+export declare const messageOf: (err: unknown) => string;
+export declare function runsThisWeek(runs: RunItem[], nowMs: number): number;
+export declare function updateNotice(update: UpdateInfo): string | null;
+export declare class Poller {
+    state: DataState;
+    private listeners;
+    private tools;
+    private timer;
+    private busy;
+    private again;
+    private checking;
+    private stopped;
+    private lastChecks;
+    private base;
+    subscribe: (fn: () => void) => (() => void);
+    private set;
+    start(): void;
+    stop(): void;
+    refresh: () => void;
+    refreshChecks: () => void;
+    readToolConfig: (name: string) => Record<string, unknown> | null;
+    helpText: (name: string) => Promise<string>;
+    private cancelUpdate;
+    private checkUpdate;
+    private load;
+    private poll;
+    private keepCheckError;
+    private pollAgents;
+    private runChecks;
+}
+export declare const DataContext: React.Context<Data | null>;
+export declare function useData(): Data;
+export declare function DataProvider(props: {
+    poller?: Poller;
+    children?: React.ReactNode;
+}): React.ReactElement;

package/dist/tui/data.js

@@ -0,0 +1,302 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// The dashboard's store. While the dashboard is open it polls every 2 seconds:
+// each added tool's `status --json` (and for agents also runs, workflows,
+// projects and homes), runs the doctor-style checks every 30 seconds, and asks
+// npm once for a newer vsf. Everything is read in-process with a capturing
+// ctx.log, so nothing ever prints to the real stdout while Ink is mounted.
+// A failing source becomes a string in `errors[source]`; it never throws.
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
+import { execFile } from 'node:child_process';
+import { baseChecks, run } from "../checks.js";
+import { configDir, context, readConfig } from "../config.js";
+import { locate } from "../loader.js";
+import { findTool } from "../registry.js";
+import { CLI_PKG, cliVersion, isNewer } from "../version.js";
+const h = React.createElement;
+export const POLL_MS = 2000;
+export const CHECKS_MS = 30_000;
+export function emptyState(tools = []) {
+    return {
+        version: cliVersion(),
+        tools,
+        agents: null,
+        awake: null,
+        memory: null,
+        runs: [],
+        workflows: [],
+        projects: [],
+        homes: [],
+        agentsConfig: null,
+        steps: null,
+        checks: null,
+        checksAt: null,
+        update: { current: cliVersion(), latest: null, checked: false },
+        errors: {},
+        loaded: false,
+        at: 0,
+    };
+}
+// ---- pure helpers --------------------------------------------------------
+// Runs a tool command with a capturing log and parses its JSON output.
+export async function captureJson(tool, command, args, base) {
+    const fn = tool.commands?.[command];
+    if (!fn)
+        throw new Error(`no ${command} command`);
+    let out = '';
+    const code = await fn(args, { ...base, log: (line) => (out += line + '\n') });
+    if (code !== 0)
+        throw new Error(out.trim().split('\n')[0] || `${command} exited ${code}`);
+    return JSON.parse(out);
+}
+// Captures a tool command's text output (for the palette's command list).
+export async function captureText(tool, command, args, base) {
+    const fn = tool.commands?.[command];
+    if (!fn)
+        return '';
+    let out = '';
+    await fn(args, { ...base, log: (line) => (out += line + '\n') });
+    return out;
+}
+export const messageOf = (err) => (err instanceof Error ? err.message : String(err)).split('\n')[0].slice(0, 200);
+// Runs of the last 7 days.
+export function runsThisWeek(runs, nowMs) {
+    const since = nowMs - 7 * 24 * 3600 * 1000;
+    return runs.filter((r) => {
+        const t = Date.parse(r.record?.startedAt ?? '');
+        return !Number.isNaN(t) && t >= since;
+    }).length;
+}
+// The newer version to announce, or null.
+export function updateNotice(update) {
+    return update.latest && isNewer(update.latest, update.current) ? update.latest : null;
+}
+// ---- the poller ----------------------------------------------------------
+// Asks npm for the latest version. Resolves null on any failure or timeout.
+function latestAsync(pkg, timeout) {
+    let child;
+    const result = new Promise((resolve) => {
+        child = execFile('npm', ['view', '--prefer-online', pkg, 'version'], { timeout, encoding: 'utf8' }, (err, stdout) => resolve(err ? null : String(stdout).trim() || null));
+    });
+    return { result, cancel: () => child?.kill() };
+}
+export class Poller {
+    state = emptyState();
+    listeners = new Set();
+    tools = new Map();
+    timer = null;
+    busy = false;
+    again = false;
+    checking = false;
+    stopped = false;
+    lastChecks = 0;
+    base = context();
+    subscribe = (fn) => {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    };
+    set(patch) {
+        this.state = { ...this.state, ...patch };
+        for (const fn of this.listeners)
+            fn();
+    }
+    start() {
+        void this.poll();
+        void this.checkUpdate();
+        this.timer = setInterval(() => void this.poll(), POLL_MS);
+    }
+    stop() {
+        this.stopped = true;
+        this.cancelUpdate?.();
+        if (this.timer)
+            clearInterval(this.timer);
+        this.listeners.clear();
+    }
+    refresh = () => {
+        void this.poll();
+    };
+    refreshChecks = () => {
+        this.lastChecks = 0;
+        void this.poll();
+    };
+    readToolConfig = (name) => {
+        const tool = this.tools.get(name);
+        try {
+            return tool?.config ? tool.config.read(this.base.configDir) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    helpText = async (name) => {
+        try {
+            return await captureText(await this.load(name), 'help', [], this.base);
+        }
+        catch {
+            return '';
+        }
+    };
+    cancelUpdate = null;
+    async checkUpdate() {
+        const ask = latestAsync(CLI_PKG, 3000);
+        this.cancelUpdate = ask.cancel;
+        const latest = await ask.result;
+        if (!this.stopped)
+            this.set({ update: { current: cliVersion(), latest, checked: true } });
+    }
+    // Tools are loaded from disk only: loadTool would run npm to fetch a
+    // missing one, and that must never block the screen.
+    async load(name) {
+        const cached = this.tools.get(name);
+        if (cached)
+            return cached;
+        const entry = findTool(name);
+        if (!entry)
+            throw new Error(`unknown tool ${name}`);
+        const path = locate(entry, configDir());
+        if (!path)
+            throw new Error('not downloaded. Run vsf update');
+        const { pathToFileURL } = await import('node:url');
+        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+        this.tools.set(name, mod.default);
+        return mod.default;
+    }
+    async poll() {
+        if (this.busy) {
+            this.again = true;
+            return;
+        }
+        this.busy = true;
+        try {
+            let names = [];
+            const errors = {};
+            try {
+                names = readConfig().tools.filter((n) => !!findTool(n));
+            }
+            catch (err) {
+                errors.config = messageOf(err);
+            }
+            const patch = { tools: names };
+            await Promise.all(names.map(async (name) => {
+                try {
+                    const tool = await this.load(name);
+                    const status = (await captureJson(tool, 'status', ['--json'], this.base));
+                    if (name === 'agents')
+                        patch.agents = status;
+                    if (name === 'awake')
+                        patch.awake = status;
+                    if (name === 'memory')
+                        patch.memory = status;
+                    if (name === 'agents')
+                        await this.pollAgents(tool, patch, errors);
+                }
+                catch (err) {
+                    errors[name] = messageOf(err);
+                }
+            }));
+            if (!names.includes('agents'))
+                Object.assign(patch, { agents: null, runs: [], workflows: [], projects: [], homes: [], agentsConfig: null });
+            if (!names.includes('awake'))
+                patch.awake = null;
+            if (!names.includes('memory'))
+                patch.memory = null;
+            this.set({ ...patch, errors: { ...errors, ...this.keepCheckError() }, loaded: true, at: Date.now() });
+            if (Date.now() - this.lastChecks >= CHECKS_MS)
+                void this.runChecks(names);
+        }
+        finally {
+            this.busy = false;
+            if (this.again && !this.stopped) {
+                this.again = false;
+                void this.poll();
+            }
+        }
+    }
+    keepCheckError() {
+        const e = this.state.errors.checks;
+        return e ? { checks: e } : {};
+    }
+    async pollAgents(tool, patch, errors) {
+        const get = async (key, command, args, into) => {
+            try {
+                into((await captureJson(tool, command, args, this.base)));
+            }
+            catch (err) {
+                errors[`agents.${key}`] = messageOf(err);
+            }
+        };
+        await Promise.all([
+            get('runs', 'runs', ['--json', '--limit', '60'], (v) => (patch.runs = v)),
+            get('workflows', 'workflows', ['--json'], (v) => (patch.workflows = v)),
+            get('projects', 'projects', ['--json'], (v) => (patch.projects = v)),
+            get('homes', 'homes', ['--json'], (v) => (patch.homes = v)),
+            // The step catalog never changes while the dashboard is open.
+            this.state.steps ? Promise.resolve() : get('steps', 'steps', [], (v) => (patch.steps = v)),
+        ]);
+        patch.agentsConfig = this.readToolConfig('agents');
+    }
+    // Doctor-style checks: base checks plus each added tool's own, in-process.
+    async runChecks(names) {
+        if (this.checking || this.stopped)
+            return;
+        this.checking = true;
+        this.lastChecks = Date.now();
+        try {
+            if (process.env.VSF_TUI_SKIP_CHECKS === '1') {
+                this.set({ checks: [], checksAt: Date.now() });
+                return;
+            }
+            const checks = baseChecks(process.platform, process.version, run);
+            for (const name of names) {
+                try {
+                    const tool = await this.load(name);
+                    checks.push(...(await tool.checks({ ...this.base, log: () => { } })));
+                }
+                catch (err) {
+                    checks.push({ name, status: 'fail', detail: messageOf(err) });
+                }
+            }
+            if (!this.stopped) {
+                const { checks: _gone, ...errors } = this.state.errors;
+                this.set({ checks, checksAt: Date.now(), errors });
+            }
+        }
+        catch (err) {
+            this.set({ errors: { ...this.state.errors, checks: messageOf(err) } });
+        }
+        finally {
+            this.checking = false;
+        }
+    }
+}
+// ---- React glue ----------------------------------------------------------
+export const DataContext = createContext(null);
+export function useData() {
+    const data = useContext(DataContext);
+    if (!data)
+        throw new Error('useData needs a DataProvider');
+    return data;
+}
+export function DataProvider(props) {
+    const ref = useRef(null);
+    if (!ref.current)
+        ref.current = props.poller ?? new Poller();
+    const poller = ref.current;
+    const [state, setState] = useState(poller.state);
+    useEffect(() => {
+        const off = poller.subscribe(() => setState(poller.state));
+        poller.start();
+        return () => {
+            off();
+            poller.stop();
+        };
+    }, [poller]);
+    const value = { state, refresh: poller.refresh, refreshChecks: poller.refreshChecks, readConfig: poller.readToolConfig, help: poller.helpText };
+    return h(DataContext.Provider, { value }, props.children);
+}

package/dist/tui/format.d.ts

@@ -0,0 +1,11 @@
+export declare const clock: (d: Date) => string;
+export declare const stamp: (d: Date) => string;
+export declare function stampDate(folder: string): Date;
+export declare function folderStamp(folder: string): string;
+export declare function clockOrStamp(d: Date, now?: Date): string;
+export declare function duration(ms: number): string;
+export declare function minutesText(min: number): string;
+export declare const plural: (n: number, word: string) => string;
+export declare function truncate(text: string, max: number): string;
+export declare function tilde(path: string, home?: string | undefined): string;
+export declare function secondsToNextCheck(lastAt: string | undefined, nowMs: number, everySec?: number): number | null;

package/dist/tui/format.js

@@ -0,0 +1,54 @@
+// Small pure formatters shared by the dashboard screens.
+const pad2 = (n) => String(n).padStart(2, '0');
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+// "14:03" in local time.
+export const clock = (d) => `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+// "Oct 20 13:51" in local time.
+export const stamp = (d) => `${MONTHS[d.getMonth()]} ${d.getDate()} ${clock(d)}`;
+// A run folder name like "2026-10-21T03-31-12-345Z" (ISO with ':' and '.' turned
+// into '-') as a Date. Anything else is handed to Date as is.
+export function stampDate(folder) {
+    const m = /^(\d{4}-\d\d-\d\d)T(\d\d)-(\d\d)-(\d\d)-(\d+)Z$/.exec(folder);
+    return new Date(m ? `${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z` : folder);
+}
+// A run folder name as local "Oct 20 21:31", or "?" when it is not a date.
+export function folderStamp(folder) {
+    const d = stampDate(folder);
+    return Number.isNaN(d.getTime()) ? '?' : stamp(d);
+}
+// Clock time for today, date and time for any other day.
+export function clockOrStamp(d, now = new Date()) {
+    return d.toDateString() === now.toDateString() ? clock(d) : stamp(d);
+}
+// "<1m", "12m", "1h 4m".
+export function duration(ms) {
+    const min = Math.round(ms / 60_000);
+    if (min < 1)
+        return '<1m';
+    return min < 60 ? `${min}m` : `${Math.floor(min / 60)}h${min % 60 ? ` ${min % 60}m` : ''}`;
+}
+// "8h 50m" from whole minutes.
+export function minutesText(min) {
+    if (min < 60)
+        return `${Math.max(0, Math.round(min))}m`;
+    return `${Math.floor(min / 60)}h ${Math.round(min % 60)}m`;
+}
+export const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+// Cuts to max characters, ending in an ellipsis when it had to cut.
+export function truncate(text, max) {
+    const t = text.replace(/\s+/g, ' ').trim();
+    return t.length > max ? t.slice(0, Math.max(0, max - 1)) + '…' : t;
+}
+// Replaces the home folder with ~.
+export function tilde(path, home = process.env.HOME) {
+    return home && path.startsWith(home) ? '~' + path.slice(home.length) : path;
+}
+// Seconds until the next runner check, given the last one. null when unknown.
+export function secondsToNextCheck(lastAt, nowMs, everySec = 60) {
+    if (!lastAt)
+        return null;
+    const t = Date.parse(lastAt);
+    if (Number.isNaN(t))
+        return null;
+    return Math.max(0, Math.round((t + everySec * 1000 - nowMs) / 1000));
+}

package/dist/tui/home.d.ts

@@ -0,0 +1,51 @@
+import React from 'react';
+import { type AgentsStatus, type AwakeStatus, type DataState, type MemoryStatus, type RunItem } from './data.ts';
+import { type Hint } from './context.ts';
+import { type Line, type StepProgress } from './widgets.ts';
+import type { Check } from '../tool.ts';
+import type { Screen } from './screens.ts';
+export type SectionId = 'agents' | 'awake' | 'memory' | 'checks';
+export declare function sectionsFor(tools: string[]): SectionId[];
+export declare function nextSection(sections: SectionId[], current: SectionId, dir: 1 | -1): SectionId;
+export declare const clampFocus: (sections: SectionId[], current: SectionId) => SectionId;
+export interface LiveCard {
+    card: string;
+    title: string;
+    workflow: string;
+    step: string;
+    minutes: number;
+    round: number;
+    maxRounds: number | null;
+    steps: StepProgress[];
+}
+export declare function liveCard(state: Pick<DataState, 'agents' | 'runs' | 'workflows' | 'steps' | 'agentsConfig'>, nowMs: number): LiveCard | null;
+export declare function runnerLines(agents: AgentsStatus, nowMs: number): {
+    left: Line;
+    right: Line;
+};
+export interface ParkedRow {
+    card: string;
+    kind: 'parked' | 'interrupted';
+    text: string;
+}
+export declare function parkedRows(agents: AgentsStatus): ParkedRow[];
+export declare function countsLine(agents: AgentsStatus, runs: RunItem[], nowMs: number): string;
+export declare function awakeLines(a: AwakeStatus): Line[];
+export declare function memoryLines(m: MemoryStatus, now?: Date): Line[];
+export interface ChecksView {
+    ok: number;
+    warn: number;
+    fail: number;
+    problems: Check[];
+}
+export declare function checksView(checks: Check[]): ChecksView;
+export declare function checksLines(checks: Check[]): {
+    left: Line;
+    right: Line;
+}[];
+export declare function homeHints(opts: {
+    runner?: AgentsStatus['runner'];
+    hasAwake: boolean;
+}): Hint[];
+export declare const homeScreen: Screen;
+export declare function Home(): React.ReactElement;