@voidlabs.gg/voidshift 0.0.0-stage → 0.4.0

package/dist/loader.js

@@ -0,0 +1,51 @@
+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;
+};
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+// Inside the monorepo, tools load straight from source. Installed copies
+// live under <configDir>/tools, one npm prefix shared by every tool.
+function sourcePath(entry) {
+    return fileURLToPath(new URL(`../../../tools/${entry.name}/src/index.ts`, import.meta.url));
+}
+function installedPath(entry, configDir) {
+    return join(configDir, 'tools', 'node_modules', entry.pkg, 'dist', 'index.js');
+}
+export function locate(entry, configDir) {
+    for (const p of [sourcePath(entry), installedPath(entry, configDir)])
+        if (existsSync(p))
+            return p;
+    return null;
+}
+// npm runs with its output captured so it stays off the screen; on failure
+// the last lines of it are shown.
+export function npm(args) {
+    const r = spawnSync('npm', args, { stdio: 'pipe', encoding: 'utf8' });
+    if (r.status === 0)
+        return true;
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}${r.error ? r.error.message : ''}`.trim();
+    if (out)
+        console.error(out.split('\n').slice(-20).join('\n'));
+    return false;
+}
+export function fetchTool(entry, configDir) {
+    if (locate(entry, configDir))
+        return true;
+    return npm(['install', '--silent', '--no-audit', '--no-fund', '--prefix', join(configDir, 'tools'), entry.pkg]) && locate(entry, configDir) !== null;
+}
+// Tools added elsewhere (or before an update) may not be downloaded on this
+// install yet, so fetch on first use rather than failing.
+export async function loadTool(entry, configDir) {
+    const path = locate(entry, configDir) ?? (fetchTool(entry, configDir) ? locate(entry, configDir) : null);
+    if (!path)
+        throw new Error(`could not download ${entry.pkg}. Check your connection and run vsf setup again.`);
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+    return mod.default;
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { readConfig } from "./config.js";
+import { config } from "./commands/config.js";
+import { doctor } from "./commands/doctor.js";
+import { help, mainHelp, usages } from "./commands/help.js";
+import { setup, setupCommand } from "./commands/setup.js";
+import { status } from "./commands/status.js";
+import { update } from "./commands/update.js";
+import { cliVersion } from "./version.js";
+import { wantsHelp } from "./commands/args.js";
+import { addTool, listTools, removeTool, runToolCommand } from "./commands/tools.js";
+import { findTool } from "./registry.js";
+import { Cancelled } from "./ui.js";
+// Ink and React load only here, so plain commands never pay for them.
+async function openDashboard() {
+    return (await import("./tui/run.js")).runDashboard();
+}
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    // Umbrella commands answer --help themselves; tools handle their own.
+    if (cmd && Object.hasOwn(usages, cmd) && wantsHelp(rest)) {
+        console.log(usages[cmd]);
+        return 0;
+    }
+    switch (cmd) {
+        case undefined:
+        case '--defaults':
+            if (cmd === '--defaults')
+                return setup(true);
+            if (process.stdin.isTTY && process.stdout.isTTY) {
+                if (readConfig().tools.length === 0)
+                    return setup(false);
+                return openDashboard();
+            }
+            console.log(mainHelp());
+            return 0;
+        case 'ui':
+            if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+                console.error('vsf ui needs a terminal. Use vsf status for plain output.');
+                return 2;
+            }
+            return openDashboard();
+        case 'setup':
+            return setupCommand(rest);
+        case 'status':
+            return status(rest);
+        case 'doctor':
+            return doctor(rest);
+        case 'config':
+            return config(rest);
+        case 'tools':
+            return listTools();
+        case 'add':
+            return addTool(rest[0]);
+        case 'remove':
+            return removeTool(rest[0]);
+        case 'update':
+            return update();
+        case '-v':
+        case '--version':
+            console.log(cliVersion());
+            return 0;
+        case '-h':
+        case '--help':
+            console.log(mainHelp());
+            return 0;
+        case 'help':
+            return help(rest);
+    }
+    const tool = findTool(cmd);
+    if (tool)
+        return runToolCommand(tool, rest);
+    console.error(`unknown command: ${cmd}. Run vsf help.`);
+    return 2;
+}
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (err) {
+    const e = err;
+    if (err instanceof Cancelled)
+        process.exitCode = 1;
+    else if (typeof e.code === 'string' && e.code.startsWith('ERR_PARSE_ARGS')) {
+        console.error(`vsf: ${e.message.replace(/\.$/, '')}. Run vsf help.`);
+        process.exitCode = 2;
+    }
+    else {
+        console.error(`vsf: ${e.message}`);
+        if (process.env.VSF_DEBUG === '1' && e.stack)
+            console.error(e.stack);
+        process.exitCode = 1;
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,8 @@
+export interface ToolEntry {
+    name: string;
+    summary: string;
+    pkg: string;
+    status: 'planned' | 'available';
+}
+export declare const registry: ToolEntry[];
+export declare function findTool(name: string): ToolEntry | undefined;

package/dist/registry.js

@@ -0,0 +1,26 @@
+// Tools the CLI knows about. Each ships as its own npm package and is
+// installed on `vsf add <name>`. Status flips to 'available' once the
+// package is published.
+export const registry = [
+    {
+        name: 'awake',
+        summary: 'Keep the Mac running on battery with the lid closed, with guardrails',
+        pkg: '@voidlabs.gg/voidshift-awake',
+        status: 'available',
+    },
+    {
+        name: 'agents',
+        summary: 'Agents for Claude Code and Codex that plan, build and QA Linear cards',
+        pkg: '@voidlabs.gg/voidshift-agents',
+        status: 'available',
+    },
+    {
+        name: 'memory',
+        summary: 'Markdown memory vault recalled into Claude Code and Codex',
+        pkg: '@voidlabs.gg/voidshift-memory',
+        status: 'available',
+    },
+];
+export function findTool(name) {
+    return registry.find((t) => t.name === name);
+}

package/dist/tool.d.ts

@@ -0,0 +1,51 @@
+export type CheckStatus = 'ok' | 'warn' | 'fail';
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+    fix?: string;
+}
+export interface Choice<T extends string> {
+    value: T;
+    label: string;
+    hint?: string;
+}
+export interface Ui {
+    info(line: string): void;
+    warn(line: string): void;
+    text(message: string, o?: {
+        initial?: string;
+        placeholder?: string;
+        validate?: (v: string) => string | undefined;
+    }): Promise<string>;
+    secret(message: string, validate?: (v: string) => string | undefined): Promise<string>;
+    confirm(message: string, initial?: boolean): Promise<boolean>;
+    select<T extends string>(message: string, choices: Choice<T>[], initial?: T): Promise<T>;
+    multiselect<T extends string>(message: string, choices: Choice<T>[], initial?: T[]): Promise<T[]>;
+    search<T extends string>(message: string, choices: Choice<T>[], placeholder?: string, initial?: T): Promise<T>;
+    path(message: string, o?: {
+        initial?: string;
+        validate?: (v: string) => string | undefined;
+    }): Promise<string>;
+}
+export interface ToolContext {
+    defaults: boolean;
+    home: string;
+    configDir: string;
+    selfCommand: string[];
+    log: (line: string) => void;
+    ui: Ui;
+}
+export type ToolCommand = (args: string[], ctx: ToolContext) => Promise<number>;
+export interface Tool {
+    name: string;
+    summary: string;
+    install(ctx: ToolContext): Promise<void>;
+    uninstall(ctx: ToolContext): Promise<void>;
+    checks(ctx: ToolContext): Promise<Check[]>;
+    commands?: Record<string, ToolCommand>;
+    config?: {
+        read(configDir: string): Record<string, unknown>;
+        write(configDir: string, value: Record<string, unknown>): string[];
+    };
+}

package/dist/tool.js

@@ -0,0 +1,4 @@
+// The contract every voidshift tool implements. The CLI owns discovery,
+// install and reporting; a tool only knows how to set itself up, take
+// itself down, say whether it is healthy, and run its own subcommands.
+export {};

package/dist/tui/actions.d.ts

@@ -0,0 +1,17 @@
+export interface ActionResult {
+    code: number;
+    output: string;
+}
+export declare function selfCommand(): string[];
+export declare function commandLine(args: string[]): string;
+export declare function runAction(args: string[], opts?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<ActionResult>;
+export declare function spawnDetached(args: string[], logFile: string): {
+    pid: number | undefined;
+};
+export declare function runInTerminal(args: string[]): number;
+export declare function needsTerminal(args: string[]): boolean;
+export declare const firstLine: (text: string) => string;
+export declare const lastLine: (text: string) => string;

package/dist/tui/actions.js

@@ -0,0 +1,99 @@
+// Everything the dashboard does, it does by running a real vsf command as a
+// child process (the same selfCommand the CLI hands to launchd). The dashboard
+// can therefore never do something a command cannot. Reads may happen
+// in-process (see data.ts); writes and anything that can block or exit the
+// process (agents run, tick, cancel, stop, restart, start) come through here.
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, mkdirSync, openSync, realpathSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+// How to start this CLI again: node plus the real path of the entry file.
+export function selfCommand() {
+    return [process.execPath, realpathSync(process.argv[1] ?? '')];
+}
+// "vsf agents cancel ENG-12", for the footer and for confirm dialogs.
+export function commandLine(args) {
+    const quote = (a) => (/^[\w@%+=:,./~-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`);
+    return ['vsf', ...args.map(quote)].join(' ');
+}
+// Runs `vsf <args>` with stdin ignored and stdout and stderr captured.
+export function runAction(args, opts = {}) {
+    return new Promise((resolve) => {
+        const [cmd, ...pre] = selfCommand();
+        let output = '';
+        let child;
+        try {
+            child = spawn(cmd, [...pre, ...args], { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, ...opts.env } });
+        }
+        catch (err) {
+            resolve({ code: 1, output: err.message });
+            return;
+        }
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                output += '\nTimed out.';
+                child.kill('SIGTERM');
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.on('data', (d) => (output += d.toString()));
+        child.stderr.on('data', (d) => (output += d.toString()));
+        child.on('error', (err) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code: 1, output: output + err.message });
+        });
+        child.on('close', (code) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code: code ?? 1, output: output.replace(/\u001b\[[0-9;]*[A-Za-z]/g, '').trim() });
+        });
+    });
+}
+// Starts a long run that outlives the keypress: output is appended to
+// logFile and the dashboard goes on, following the run from run.json.
+export function spawnDetached(args, logFile) {
+    mkdirSync(dirname(logFile), { recursive: true });
+    const fd = openSync(logFile, 'a');
+    try {
+        writeSync(fd, `\n--- ${new Date().toISOString()} ${commandLine(args)}\n`);
+        const [cmd, ...pre] = selfCommand();
+        const child = spawn(cmd, [...pre, ...args], { detached: true, stdio: ['ignore', fd, fd] });
+        child.on('error', () => { });
+        child.unref();
+        return { pid: child.pid };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// Runs a command that needs the real terminal (prompts, an editor, a long
+// foreground run) with stdio inherited. Call it only while Ink has released
+// the terminal (useApp().suspendTerminal).
+export function runInTerminal(args) {
+    const [cmd, ...pre] = selfCommand();
+    return spawnSync(cmd, [...pre, ...args], { stdio: 'inherit' }).status ?? 1;
+}
+// Commands that prompt, open an editor or run in the foreground. The
+// dashboard hands them the terminal instead of capturing their output.
+export function needsTerminal(args) {
+    const [a, b, c] = args;
+    if (a === 'setup' || a === 'add' || a === 'remove')
+        return true;
+    if (a === 'config' && b === 'edit')
+        return true;
+    if (a === 'agents') {
+        if (b === 'run' || b === 'key')
+            return true;
+        if (b === 'logs' && args.some((x) => x === '-f' || x === '--follow'))
+            return true;
+        if ((b === 'workflow' || b === 'project') && (c === 'add' || c === 'edit') && !args.includes('--yes'))
+            return true;
+        if ((b === 'workflow' || b === 'project') && c === 'rm' && !args.includes('--yes') && !args.includes('-y'))
+            return true;
+    }
+    if (a === 'awake' && b === 'logs' && args.some((x) => x === '-f' || x === '--follow'))
+        return true;
+    return false;
+}
+// First and last non-empty lines, for toasts.
+export const firstLine = (text) => text.split('\n').find((l) => l.trim())?.trim() ?? '';
+export const lastLine = (text) => [...text.split('\n')].reverse().find((l) => l.trim())?.trim() ?? '';

package/dist/tui/app.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { type Poller } from './data.ts';
+export declare function App(props: {
+    poller?: Poller;
+}): React.ReactElement;
+export declare function Shell(): React.ReactElement;

package/dist/tui/app.js

@@ -0,0 +1,246 @@
+// The shell: a stack of screens, the header, the footer of key hints, a toast
+// line, the confirm dialog, the key help and the command palette.
+import React, { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import { Box, Text, useApp, useInput, useWindowSize } from 'ink';
+import { commandLine, firstLine, lastLine, runAction, runInTerminal, spawnDetached } from "./actions.js";
+import { usages } from "../commands/help.js";
+import { ScreenCtx, } from "./context.js";
+import { DataProvider, updateNotice, useData } from "./data.js";
+import { useKeyBatching } from "./keys.js";
+import { breadcrumb, HOME, initialStack, navReducer } from "./nav.js";
+import { Palette, parseUsages } from "./palette.js";
+import { crumbsOf, hintsOf, screens } from "./screens.js";
+import { theme } from "./theme.js";
+import { Confirm, KeyHints, Panel } from "./widgets.js";
+const h = React.createElement;
+const toastColour = (k) => (k === 'ok' ? theme.green : k === 'error' ? theme.red : theme.accent);
+const toastMark = (k) => (k === 'ok' ? '✓' : k === 'error' ? '✗' : '·');
+export function App(props) {
+    return h(DataProvider, { poller: props.poller }, h(Shell));
+}
+export function Shell() {
+    const { exit, suspendTerminal } = useApp();
+    const data = useData();
+    const { columns, rows } = useWindowSize();
+    const [stack, dispatch] = useReducer(navReducer, undefined, initialStack);
+    const [overlay, setOverlay] = useState(null);
+    const [toast, setToast] = useState(null);
+    const [meta, setMeta] = useState({});
+    const [, bump] = useState(0);
+    const captures = useRef({});
+    const guards = useRef({});
+    const toastId = useRef(0);
+    const umbrella = useMemo(() => parseUsages(usages), []);
+    const top = stack.length - 1;
+    const route = stack[top];
+    const showToast = useCallback((text, kind = 'info') => {
+        const id = ++toastId.current;
+        setToast({ id, text, kind });
+        if (kind !== 'info')
+            setTimeout(() => setToast((t) => (t && t.id === id ? null : t)), 5000);
+    }, []);
+    const confirm = useCallback((options, command) => new Promise((resolve) => {
+        setOverlay({
+            type: 'confirm',
+            options,
+            command,
+            resolve: (ok) => {
+                setOverlay(null);
+                resolve(ok);
+            },
+        });
+    }), []);
+    const terminal = useCallback(async (args) => {
+        let code = 1;
+        await suspendTerminal(async () => {
+            process.stdout.write(`\n$ ${commandLine(args)}\n\n`);
+            code = runInTerminal(args);
+            process.stdout.write(`\n${code === 0 ? 'Done.' : `Exited with code ${code}.`} Press Enter to return to vsf. `);
+            await new Promise((resolve) => {
+                const onData = () => {
+                    process.stdin.off('data', onData);
+                    process.stdin.pause();
+                    resolve();
+                };
+                process.stdin.on('data', onData);
+                process.stdin.resume();
+            });
+        });
+        data.refresh();
+        return code;
+    }, [suspendTerminal, data.refresh]);
+    const actions = useMemo(() => ({
+        confirm: (options) => confirm(options),
+        terminal,
+        detach(args, logFile, text) {
+            try {
+                spawnDetached(args, logFile);
+                showToast(text ?? `Started ${commandLine(args)}`, 'ok');
+                setTimeout(data.refresh, 1500);
+            }
+            catch (err) {
+                showToast(err.message, 'error');
+            }
+        },
+        async run(spec) {
+            if (!spec.noConfirm) {
+                const ok = await confirm({ title: spec.title, body: spec.body, confirmLabel: spec.confirmLabel, cancelLabel: spec.cancelLabel }, spec.args);
+                if (!ok)
+                    return null;
+            }
+            showToast(`Running ${commandLine(spec.args)}`, 'info');
+            const result = await runAction(spec.args, { timeoutMs: spec.timeoutMs });
+            data.refresh();
+            if (result.code === 0) {
+                showToast(spec.done ?? (firstLine(result.output) || 'Done'), 'ok');
+                spec.after?.(result);
+            }
+            else {
+                showToast(lastLine(result.output) || `${commandLine(spec.args)} failed (exit code ${result.code})`, 'error');
+            }
+            return result;
+        },
+    }), [confirm, terminal, showToast, data.refresh]);
+    const patchMeta = useCallback((index, patch) => setMeta((m) => ({ ...m, [index]: { ...m[index], ...patch } })), []);
+    // One context per stacked screen, so a hidden screen cannot change the footer.
+    const contexts = useMemo(() => stack.map((r, index) => {
+        const isTop = index === top;
+        return {
+            id: r.id,
+            params: r.params,
+            nav: {
+                push: (id, params) => dispatch({ type: 'push', id, params }),
+                pop: () => dispatch({ type: 'pop' }),
+                replace: (id, params) => dispatch({ type: 'replace', id, params }),
+                depth: stack.length,
+            },
+            actions,
+            toast: showToast,
+            setHints: (hints) => patchMeta(index, { hints }),
+            setCommand: (args) => patchMeta(index, { command: args }),
+            setHeaderRight: (text, colour) => patchMeta(index, { right: text ? { text, colour } : null }),
+            capture: () => {
+                captures.current[index] = (captures.current[index] ?? 0) + 1;
+                bump((n) => n + 1);
+                return () => {
+                    captures.current[index] = Math.max(0, (captures.current[index] ?? 1) - 1);
+                    bump((n) => n + 1);
+                };
+            },
+            capturing: isTop && (captures.current[index] ?? 0) > 0,
+            setBackGuard: (fn) => {
+                guards.current[index] = fn;
+            },
+            modalOpen: overlay !== null || !isTop,
+            columns,
+            rows,
+        };
+    }), [stack, top, overlay, actions, showToast, patchMeta, columns, rows, captures.current[top]]);
+    // Hints and the equivalent command belong to the entry they were set on.
+    useEffect(() => {
+        setMeta((m) => Object.fromEntries(Object.entries(m).filter(([i]) => Number(i) <= top)));
+    }, [top]);
+    const topCapturing = (captures.current[top] ?? 0) > 0;
+    // Several keys in one chunk are handled one by one, except into a text field.
+    useKeyBatching(() => topCapturing || overlay?.type === 'palette');
+    useInput((input, key) => {
+        if (overlay || topCapturing)
+            return;
+        if (key.escape) {
+            if (guards.current[top]?.())
+                return;
+            dispatch({ type: 'pop' });
+        }
+        else if (input === 'q')
+            exit();
+        else if (input === ':')
+            setOverlay({ type: 'palette' });
+        else if (input === '?')
+            setOverlay({ type: 'help' });
+    }, { isActive: true });
+    // ---- render ----
+    const crumbs = breadcrumb(stack, (r) => crumbsOf(r.id, r.params));
+    const notice = updateNotice(data.state.update);
+    const right = meta[top]?.right;
+    const header = h(Box, { paddingX: 1, flexShrink: 0 }, h(Box, { flexGrow: 1 }, route.id === HOME
+        ? h(Text, null, h(Text, { bold: true, color: theme.bold }, 'VoidShift'), h(Text, { color: theme.dim }, ` ${data.state.version}`))
+        : h(Text, null, ...crumbs.flatMap((c, i) => [
+            i > 0 ? h(Text, { key: `s${i}`, color: theme.dim }, ' › ') : null,
+            h(Text, { key: `c${i}`, bold: i === 0, color: i === 0 ? theme.bold : undefined }, c),
+        ]))), right
+        ? h(Text, { color: right.colour ?? theme.dim }, right.text)
+        : notice
+            ? h(Text, { color: theme.yellow }, route.id === HOME ? `${notice} is out · u updates` : `${notice} is out`)
+            : null);
+    const body = h(Box, { flexDirection: 'column', flexGrow: 1, overflow: 'hidden' }, ...stack.map((r, index) => {
+        const screen = screens[r.id];
+        const visible = index === top && overlay === null;
+        return h(Box, { key: `${index}:${r.id}`, display: visible ? 'flex' : 'none', flexDirection: 'column' }, h(ScreenCtx.Provider, { value: contexts[index] }, screen ? h(screen.component, { params: r.params }) : h(Text, { color: theme.red }, `Unknown screen ${r.id}`)));
+    }), overlay ? renderOverlay(overlay, { umbrella, setOverlay, data, terminal, hints: footerHints(route, meta[top]) }) : null);
+    const toastLine = h(Box, { paddingX: 1, flexShrink: 0, height: 1 }, toast ? h(Text, { color: toastColour(toast.kind), wrap: 'truncate-end' }, `${toastMark(toast.kind)} ${toast.text}`) : h(Text, null, ' '));
+    let hints = footerHints(route, meta[top]);
+    let command = meta[top]?.command ?? null;
+    if (overlay?.type === 'confirm') {
+        hints = [
+            { key: '←→', label: 'choose' },
+            { key: 'enter', label: 'confirm' },
+            { key: 'esc', label: 'cancel' },
+        ];
+        command = overlay.command ?? null;
+    }
+    else if (overlay?.type === 'palette') {
+        hints = [
+            { key: 'enter', label: 'run' },
+            { key: 'tab', label: 'complete' },
+            { key: '↑↓', label: 'pick' },
+            { key: 'esc', label: 'close' },
+        ];
+        command = null;
+    }
+    else if (overlay?.type === 'help') {
+        hints = [{ key: 'esc', label: 'close' }];
+        command = null;
+    }
+    const footer = h(Box, { flexShrink: 0 }, h(KeyHints, { hints, width: columns, right: command ? `= ${commandLine(command)}` : undefined }));
+    return h(Box, { flexDirection: 'column', height: rows, width: columns }, header, body, toastLine, footer);
+}
+function footerHints(route, meta) {
+    return meta?.hints ?? hintsOf(route.id, route.params);
+}
+function renderOverlay(overlay, env) {
+    if (overlay.type === 'confirm') {
+        return h(Confirm, {
+            title: overlay.options.title,
+            body: overlay.options.body,
+            confirmLabel: overlay.options.confirmLabel,
+            cancelLabel: overlay.options.cancelLabel,
+            onConfirm: () => overlay.resolve(true),
+            onCancel: () => overlay.resolve(false),
+        });
+    }
+    if (overlay.type === 'palette') {
+        return h(Palette, {
+            umbrella: env.umbrella,
+            onClose: () => env.setOverlay(null),
+            onRun: async (args) => {
+                const r = await runAction(args);
+                env.data.refresh();
+                return r;
+            },
+            onTerminal: (args) => void env.terminal(args),
+        });
+    }
+    return h(HelpOverlay, { hints: env.hints, onClose: () => env.setOverlay(null) });
+}
+const GLOBAL_KEYS = [
+    { key: 'esc', label: 'go back' },
+    { key: ':', label: 'command palette: every vsf command' },
+    { key: '?', label: 'this list' },
+    { key: 'q', label: 'quit' },
+    { key: 'ctrl+c', label: 'quit from anywhere' },
+];
+function HelpOverlay(props) {
+    useInput(() => props.onClose());
+    const line = (hint, i, tag = '') => h(Text, { key: `${tag}${i}` }, h(Text, { color: theme.accent }, hint.key.padEnd(8)), h(Text, null, hint.label));
+    return h(Panel, { title: 'Keys', focused: true }, h(Text, { color: theme.dim }, 'On this screen'), ...props.hints.map((hint, i) => line(hint, i, 's')), h(Text, null, ' '), h(Text, { color: theme.dim }, 'Everywhere'), ...GLOBAL_KEYS.map((hint, i) => line(hint, i, 'g')));
+}

package/dist/tui/context.d.ts

@@ -0,0 +1,62 @@
+import { type Key } from 'ink';
+import type { ActionResult } from './actions.ts';
+import type { Params } from './nav.ts';
+export interface Hint {
+    key: string;
+    label: string;
+}
+export type ToastKind = 'ok' | 'error' | 'info';
+export interface ActionSpec {
+    args: string[];
+    title: string;
+    body?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    noConfirm?: boolean;
+    done?: string;
+    after?: (result: ActionResult) => void;
+    timeoutMs?: number;
+}
+export interface ConfirmOptions {
+    title: string;
+    body?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+}
+export interface Actions {
+    run(spec: ActionSpec): Promise<ActionResult | null>;
+    confirm(options: ConfirmOptions): Promise<boolean>;
+    detach(args: string[], logFile: string, toast?: string): void;
+    terminal(args: string[]): Promise<number>;
+}
+export interface Nav {
+    push(id: string, params?: Params): void;
+    pop(): void;
+    replace(id: string, params?: Params): void;
+    depth: number;
+}
+export interface ScreenContext {
+    id: string;
+    params: Params;
+    nav: Nav;
+    actions: Actions;
+    toast(text: string, kind?: ToastKind): void;
+    setHints(hints: Hint[] | null): void;
+    setCommand(args: string[] | null): void;
+    setHeaderRight(text: string | null, colour?: string): void;
+    capture(): () => void;
+    capturing: boolean;
+    setBackGuard(fn: (() => boolean) | null): void;
+    modalOpen: boolean;
+    columns: number;
+    rows: number;
+}
+export declare const ScreenCtx: import("react").Context<ScreenContext | null>;
+export declare function useScreen(): ScreenContext;
+export declare function useKeys(handler: (input: string, key: Key) => void, opts?: {
+    whileCapturing?: boolean;
+}): void;
+export declare function useHints(hints: Hint[] | null): void;
+export declare function useEquivalent(args: string[] | null): void;
+export declare function useCapture(active: boolean): void;
+export declare function useBackGuard(fn: (() => boolean) | null): void;