@ashley-shrok/viewmodel-shell 0.4.2 → 0.4.3

package/README.md

@@ -2,7 +2,7 @@
 
 A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime.
 
-The server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. The browser never owns application state — every interaction dispatches a semantic action to a single POST endpoint and the server returns the next state plus a fresh view.
+The server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to the DOM (or, with the same wire, a terminal). The browser never owns application state — every interaction dispatches a semantic action to a single POST endpoint and the server returns the next state plus a fresh view.
 
 The frontend is backend-agnostic: it speaks a small JSON contract over a single POST endpoint that takes `multipart/form-data` (with `_action` and `_state` fields). A .NET reference backend ships in the repo, but any language can produce the same contract.
 
@@ -33,6 +33,31 @@ If your backend is .NET: copy `demo/Tasks/AspNetCore/ViewModels.cs` from the [Gi
 
 For other backends, implement the same JSON shape: a `GET` returning `{ vm, state }`, and a `POST` that takes `multipart/form-data` with `_action` and `_state` form fields and returns the next `{ vm, state }`. See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md) for the full wire format.
 
+## Terminal (TUI)
+
+The same backend renders in a terminal — same wire, no backend change. Point the CLI at any ViewModel Shell endpoint:
+
+```bash
+npx vms-tui https://your-app.example/api/tasks
+```
+
+The action endpoint is derived by convention (`<endpoint>/action`). Or wire it programmatically, exactly like `BrowserAdapter`:
+
+```ts
+import { ViewModelShell } from "@ashley-shrok/viewmodel-shell";
+import { TuiAdapter } from "@ashley-shrok/viewmodel-shell/tui";
+
+const shell = new ViewModelShell({
+  endpoint:       "/api/tasks",
+  actionEndpoint: "/api/tasks/action",
+  adapter:        new TuiAdapter(),
+});
+
+shell.load();
+```
+
+The TUI is built on [Ink](https://github.com/vadimdemedes/ink), declared as an **optional** dependency: CLI/`npx` use installs it automatically, while web and server consumers are unaffected — it is never imported by the browser, server, or core entrypoints. See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md) for what the terminal renders.
+
 ## Themes
 
 The base stylesheet ships a **light** default (purple accent). To use a different look — including the prior dark-purple default — import a theme file on top:

package/dist/tui-cli.d.ts

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

package/dist/tui-cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// vms-tui — drive any ViewModel Shell backend from a terminal.
+//
+//   vms-tui <endpoint-url>
+//   e.g.  vms-tui http://localhost:3000/api/tasks
+//
+// Convention: actions POST to `<endpoint>/action` (matches the demos:
+// GET /api/tasks  +  POST /api/tasks/action). A future flag can override it.
+//
+// Pure entrypoint — never imported as a library (the importable surface is
+// TuiAdapter via the "./tui" export), so no import.meta.main guard is needed.
+import { ViewModelShell } from "./index.js";
+const USAGE = "Usage: vms-tui <endpoint-url>\n" +
+    "  e.g.  vms-tui http://localhost:3000/api/tasks\n" +
+    "  Actions POST to <endpoint>/action.";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function main() {
+    const arg = process.argv[2];
+    if (!arg || arg === "-h" || arg === "--help") {
+        process.stderr.write(USAGE + "\n");
+        process.exitCode = arg ? 0 : 2;
+        return;
+    }
+    try {
+        // Validate; rejects garbage early instead of failing deep in fetch.
+        void new URL(arg);
+    }
+    catch {
+        process.stderr.write(`vms-tui: invalid URL: ${arg}\n${USAGE}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const endpoint = arg;
+    // Guarded dynamic import: if the optional `ink`/`react` deps are absent,
+    // fail loud with an install hint instead of an ESM resolution stack trace.
+    let TuiAdapter;
+    let openExternal;
+    let classify;
+    try {
+        ({ TuiAdapter, openExternal, classify } = await import("./tui.js"));
+    }
+    catch (err) {
+        process.stderr.write("vms-tui requires the optional 'ink' and 'react' packages.\n" +
+            "Install them:  npm i ink react\n" +
+            `(load error: ${err.message})\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const adapter = new TuiAdapter();
+    let loadFailed = false;
+    let exiting = false;
+    // Single, idempotent teardown owned by the CLI.
+    //
+    // Ink registers `signal-exit` and resolving its waitUntilExit() promise
+    // (which adapter.dispose() → Ink unmount does) lets main()'s tail resume.
+    // Without the `exiting` guard that tail would set process.exitCode = 0 and
+    // race the real signal code away (observed: SIGINT exited 0, not 130).
+    // So: set the code FIRST, restore the terminal, then exit — and let the
+    // first caller win; any later caller (incl. the resumed await-tail) no-ops.
+    const shutdown = (code) => {
+        if (exiting)
+            return;
+        exiting = true;
+        process.exitCode = code;
+        try {
+            adapter.dispose(); // Ink unmount → cursor/raw-mode restored
+        }
+        catch {
+            /* best-effort, idempotent */
+        }
+        process.exit(code);
+    };
+    process.once("SIGINT", () => shutdown(130));
+    process.once("SIGTERM", () => shutdown(143));
+    process.once("uncaughtException", (err) => {
+        try {
+            adapter.dispose(); // restore BEFORE printing so the message is readable
+        }
+        catch {
+            /* idempotent */
+        }
+        process.stderr.write(`vms-tui: ${err?.stack ?? String(err)}\n`);
+        shutdown(1);
+    });
+    process.once("unhandledRejection", (reason) => {
+        try {
+            adapter.dispose();
+        }
+        catch {
+            /* idempotent */
+        }
+        process.stderr.write(`vms-tui: ${String(reason)}\n`);
+        shutdown(1);
+    });
+    // Final safety net: any other exit path still restores the terminal.
+    process.once("exit", () => {
+        try {
+            adapter.dispose();
+        }
+        catch {
+            /* idempotent */
+        }
+    });
+    // Phase 2: the adapter now uses Ink input hooks → Ink puts stdin in raw
+    // mode, which clears ISIG, so a *keyboard* Ctrl-C is delivered as input
+    // byte 0x03 and never raises SIGINT (the process.once("SIGINT") above only
+    // fires for a *programmatic* kill -INT). Route that keyboard Ctrl-C, caught
+    // in the adapter's input handler, into this same idempotent shutdown so the
+    // terminal is always restored. SIGTERM and programmatic SIGINT are
+    // unaffected by raw mode and keep working via the handlers above. (The
+    // keep-alive below is now redundant on the TTY path — Ink's resumed raw
+    // stdin holds the loop — but is harmless and kept as belt-and-suspenders.)
+    adapter.setRequestExit((code) => shutdown(code));
+    // Phase 4: server-initiated redirects via the existing core onRedirect seam
+    // (no new wire). A ViewModelShell's endpoint is immutable and load() takes
+    // no URL, so a same-origin redirect is followed by building a FRESH shell
+    // that reuses the SAME single adapter (Ink rerenders in place — no remount,
+    // teardown topology unchanged). connect()'s options carry this same
+    // onRedirect, so redirects chain.
+    let redirectFailed = false;
+    let currentShell;
+    const handleRedirect = (url, fromEndpoint) => {
+        const c = classify(url, fromEndpoint);
+        if (c.kind === "same-origin") {
+            currentShell.stopPolling(); // no timer armed today; defends a future one
+            currentShell = connect(c.endpoint);
+            void currentShell.load(); // failures flow through the shared onError
+            return;
+        }
+        if (!process.stdout.isTTY) {
+            // Non-TTY: never spawn a browser; loud stderr + nonzero exit via the
+            // SINGLE shutdown funnel (redirectFailed is read at the exit site).
+            process.stderr.write(`vms-tui: cannot follow redirect (${c.kind}): ${url}\n`);
+            redirectFailed = true;
+            return;
+        }
+        if (c.kind === "different-origin") {
+            const detail = `This app asked to open an external URL:\n\n  ${c.url}`;
+            const fb = () => adapter.showInterstitial(`${detail}\n\n(no browser could be launched — open it manually)`);
+            if (openExternal(c.url, fb)) {
+                adapter.showInterstitial(`${detail}\n\n(opening in your browser…)`);
+            }
+            else {
+                fb();
+            }
+        }
+        else {
+            adapter.showInterstitial(`This app returned an invalid redirect:\n\n  ${JSON.stringify(url)}`);
+        }
+    };
+    const connect = (ep) => new ViewModelShell({
+        endpoint: ep,
+        actionEndpoint: `${ep.replace(/\/+$/, "")}/action`,
+        adapter,
+        onError: (err) => {
+            loadFailed = true;
+            // A stderr line guarantees visibility even before the first render.
+            process.stderr.write(`vms-tui: ${err.message}\n`);
+        },
+        onRedirect: (url) => handleRedirect(url, ep),
+    });
+    currentShell = connect(endpoint);
+    try {
+        await currentShell.load();
+    }
+    catch (err) {
+        loadFailed = true;
+        process.stderr.write(`vms-tui: ${err.message}\n`);
+    }
+    if (!process.stdout.isTTY) {
+        // Non-TTY (piped / CI): nothing to interact with — emit one static frame
+        // and exit instead of hanging on a Ctrl-C that can never come. The delay
+        // lets Ink flush its throttled render. (Redirects can't fire here: load()
+        // ignores response.redirect and non-TTY performs no dispatch — so
+        // redirectFailed stays false unless a future code path dispatches.)
+        await delay(80);
+        return shutdown(loadFailed || redirectFailed ? 1 : 0);
+    }
+    // Load/connection failure → nothing rendered; exit now rather than wait for
+    // a Ctrl-C the user has no reason to send.
+    if (loadFailed) {
+        return shutdown(1);
+    }
+    // TTY + rendered: keep the frame up until the user quits (Ctrl-C). Ink's
+    // resumed raw stdin holds the loop (Phase 2+), but the no-op timer is kept
+    // as belt-and-suspenders; the SIGINT/SIGTERM handlers own exit + restore.
+    // (waitUntilExit() wins the race if Ink unmounts for another reason.)
+    const keepAlive = setInterval(() => { }, 1 << 30);
+    await adapter.waitUntilExit();
+    clearInterval(keepAlive);
+    shutdown(0);
+}
+void main();

package/dist/tui.d.ts

@@ -0,0 +1,134 @@
+import type { ReactElement } from "react";
+import type { Adapter, ActionEvent, ViewNode } from "./index.js";
+/** OSC 52 clipboard write — the terminal-native analog of the clipboard API.
+ *  Works over SSH (no local clipboard dependency). Exported for a direct,
+ *  deterministic unit test of the byte format. */
+export declare function osc52(text: string): string;
+/** Hand a URL to a real browser — the terminal analog of a redirect. Zero-dep
+ *  (node:child_process). Opener order: $BROWSER → platform default. Detached +
+ *  unref so a launched browser can never hold or block the Node event loop
+ *  (teardown discipline). Returns false only if spawn threw *synchronously*
+ *  (no opener attempted); an async spawn failure (e.g. ENOENT — no xdg-open)
+ *  invokes `onSpawnError`. Callers map BOTH false and onSpawnError to the loud
+ *  interstitial, so a redirect is never silently lost. Exported so a unit test
+ *  can drive it with a stubbed node:child_process. */
+export declare function openExternal(url: string, onSpawnError?: () => void): boolean;
+/** How the vms-tui CLI's default onRedirect classifies a server redirect.
+ *  No new wire — pure URL/origin analysis against the current endpoint. A
+ *  relative path resolves against the endpoint ⇒ same-origin by construction;
+ *  an absolute URL is same-origin iff its `origin` matches (origin compare,
+ *  never a string prefix — `http://evil/?x=http://good` must NOT pass). */
+export type RedirectKind = {
+    kind: "same-origin";
+    endpoint: string;
+} | {
+    kind: "different-origin";
+    url: string;
+} | {
+    kind: "invalid";
+    url: string;
+};
+export declare function classify(url: string, fromEndpoint: string): RedirectKind;
+/**
+ * Phase 5b terminal adapter — single-line + multi-line editors + selects.
+ *
+ * Every node renders byte-identically to Phase 1/2 when UNFOCUSED and on the
+ * pure `renderTree`/non-TTY path (NO_CTX → interactive:false → no editor). On
+ * a TTY the shell's view is interactive: a self-managed focus ring
+ * (Tab/Shift-Tab/arrows), Enter/Space dispatch, focus continuity; button /
+ * checkbox (`{checked}`) / tabs (`{value}`) / link / copy-button (OSC 52) /
+ * form-submit. The focused single-line `field` is an editable
+ * `ink-text-input`; the focused `textarea`/`code` field is the contained
+ * `MultilineEditor` (Enter→newline; submit via the ring's submit button;
+ * `code` adds a dim language label, no literal-tab). The focused `select` is
+ * an `ink-select-input` list; the focused `select-multiple` is the contained
+ * `MultiSelectInput` (Space toggles; comma-joined wire value; submit via the
+ * ring's submit button). Typed drafts survive poll/dispatch re-renders unless
+ * the field disappears or the server changes its value — mirroring
+ * BrowserAdapter; selects are additionally server-authoritative on ANY server
+ * re-render (excluded from draft preservation); password is masked;
+ * form-`checkbox` toggles on Space. The still-deferred tier (`file`/`modal`/
+ * `table`) arrives in later phases and still renders a visible fail-loud
+ * placeholder — never blank, never silent.
+ *
+ * LEAF MODULE: never imported by src/index.ts / src/browser.ts /
+ * src/server.ts, so `ink`/`react` never enter the web or server dependency
+ * graph (a unit test asserts this).
+ */
+export declare class TuiAdapter implements Adapter {
+    private instance;
+    private disposed;
+    /** Injected by tui-cli.ts: lets a keyboard Ctrl-C (which, under Ink's raw
+     *  mode, is delivered as input 0x03 and never raises SIGINT) reach the
+     *  CLI's single idempotent shutdown. A TUI-internal seam between our two
+     *  leaf files — NOT part of the core Adapter interface. */
+    private requestExit;
+    /** session storage — in-memory, process lifetime (browser sessionStorage
+     *  analog for a single-process CLI). Write-only per the wire contract. */
+    private sessionStore;
+    /** When non-null, App renders the loud Interstitial instead of the vm. */
+    private interstitial;
+    /** Last rendered vm/onAction — so showInterstitial can rerender through the
+     *  SAME single Ink instance (never a 2nd inkRender). */
+    private lastVm;
+    private lastOnAction;
+    setRequestExit(fn: (code: number) => void): void;
+    render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
+    /** The interactive element used by render() and by interaction unit tests. */
+    createApp(vm: ViewNode, onAction: (a: ActionEvent) => void, opts?: {
+        requestExit?: (code: number) => void;
+    }): ReactElement;
+    /** Render a full-screen loud notice through the SINGLE existing Ink instance
+     *  (never a 2nd inkRender, never a raw stdout write that would corrupt Ink's
+     *  diff / the ESC[?25h restore). No-op once disposed — closes the
+     *  redirect-during-teardown rerender-after-unmount race. Process stays
+     *  alive; the CLI owns exit (Ctrl-C via App's existing useInput → shutdown).
+     *  Mounts the instance if a notice somehow precedes the first render (that
+     *  is still the FIRST inkRender, not a second). */
+    showInterstitial(msg: string): void;
+    /** Standalone redirect fallback. Only reached when a consumer wires
+     *  TuiAdapter WITHOUT ShellOptions.onRedirect — core precedence means the
+     *  vms-tui CLI's onRedirect suppresses this (proven by adapter-seam C/F).
+     *  Origin-blind (the adapter has no shell/endpoint ref): hand off to a
+     *  browser, else the loud interstitial. Never silent, never throws into
+     *  core. No-op once disposed. */
+    navigate(url: string): void;
+    /** Write-only client storage. `session` → in-memory (process lifetime).
+     *  `local` → a SYNCHRONOUS XDG state-file write — synchronous is mandatory:
+     *  the core applies side-effects before the redirect branch (adapter-seam
+     *  Case E), so the token must land before navigation. Fail-loud, never
+     *  swallow, never re-throw into core (push() has no try/catch): an I/O error
+     *  or an unparseable EXISTING store surfaces the loud interstitial + a
+     *  stderr line and does NOT clobber a possibly-unrelated user file. */
+    storage(scope: "local" | "session", key: string, value: string): void;
+    /** Test-only: read back a session value. The wire contract has no storage
+     *  read; this exists solely so a unit test can prove the write landed
+     *  (same rationale as exporting osc52 for a deterministic test). */
+    _peekSession(key: string): string | undefined;
+    /** Pure ViewNode → Ink element, UNFOCUSED (NO_CTX). Used by static unit
+     *  tests; byte-identical to Phase 1 output. */
+    renderTree(vm: ViewNode): ReactElement;
+    /** Spacing rhythm. compact collapses gaps/padding (mirrors .vms--compact). */
+    private spacing;
+    /**
+     * React key: the roadmap's identity heuristic — explicit id/name where
+     * present, else positional index. Render-only; never a wire field.
+     */
+    private keyOf;
+    /** Fail-loud placeholder — single source of the phase string. */
+    private unsupported;
+    /** Focused-node affordance. Unfocused → returns the element unchanged, so
+     *  the static path stays byte-identical to Phase 1. Focused → a leading
+     *  cyan caret (deterministic + information-honest; ▸ U+25B8 is distinct
+     *  from the list-item markers › / ·). */
+    private focusWrap;
+    /** Shipped list-item variant → marker + child tint (fail-soft: unknown ok). */
+    private listItemStyle;
+    /** page & section share the 4 layout presets. Information-honest, not pixel. */
+    private layoutContainer;
+    private renderNode;
+    /** Resolves when the Ink app unmounts; immediate if nothing was rendered. */
+    waitUntilExit(): Promise<void>;
+    /** Idempotent terminal restore — unmount restores cursor/raw mode. */
+    dispose(): void;
+}