@valyrianjs/terminal 0.2.1 → 0.2.3

package/examples/docs/module-query.tsx

@@ -0,0 +1,209 @@
+import { QueryClient } from "valyrian.js/query";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+interface InventoryItem {
+  sku: string;
+  name: string;
+  category: string;
+  stock: number;
+}
+
+interface InventoryResult {
+  readLabel: string;
+  items: InventoryItem[];
+}
+
+interface QueryState {
+  value: string;
+  status: string;
+  invalidated: boolean;
+  fetchCount: number;
+  selectedIndex: number;
+  items: InventoryItem[];
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+const INVENTORY: InventoryItem[] = [
+  { sku: "OPS-100", name: "Battery pack", category: "Operations", stock: 12 },
+  { sku: "NET-210", name: "Switch kit", category: "Network", stock: 4 },
+  { sku: "SEC-404", name: "Seal tags", category: "Security", stock: 30 }
+];
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function selectedItem(state: QueryState) {
+  return state.items[state.selectedIndex] || null;
+}
+
+export function App({ state }: { state: QueryState }) {
+  const item = selectedItem(state);
+  return (
+    <Screen title="Cached Inventory Browser">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Cached Inventory Browser</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Inventory Browser: fetches local stock data through a Valyrian query cache.</Text>
+        <Text>{`Query status: ${state.status}`}</Text>
+        <Text>{`Cached value: ${state.value}`}</Text>
+        <Text>{`Invalidated: ${state.invalidated ? "yes" : "no"}`}</Text>
+        <Text>{`Fetcher calls: ${state.fetchCount}`}</Text>
+        <Text>{`Selected item: ${item ? `${item.name} (${item.sku})` : "none"}`}</Text>
+        <Text>{`Category: ${item ? item.category : "none"}`}</Text>
+        <Text>{`Stock on hand: ${item ? item.stock : 0}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>F: fetch inventory   I: invalidate cache   J/K: select item   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleQueryDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: QueryState = {
+    value: "none",
+    status: "idle",
+    invalidated: false,
+    fetchCount: 0,
+    selectedIndex: 0,
+    items: [],
+    running: true
+  };
+  const client = new QueryClient({ staleTime: 30000, cacheTime: 1000 });
+  const query = client.query({
+    key: ["docs", "inventory"],
+    fetcher: (): InventoryResult => {
+      state.fetchCount += 1;
+      return {
+        readLabel: `terminal read #${state.fetchCount}`,
+        items: INVENTORY.map((item) => ({ ...item }))
+      };
+    }
+  });
+  let session: TerminalSession;
+
+  async function fetchInventory() {
+    state.status = "loading";
+    session.update();
+    const data = await query.fetch();
+    state.value = data?.readLabel || "none";
+    state.items = data?.items || [];
+    state.selectedIndex = Math.min(state.selectedIndex, Math.max(state.items.length - 1, 0));
+    state.status = query.state.status;
+    session.update();
+  }
+
+  function invalidateInventory() {
+    query.invalidate();
+    state.status = query.state.status;
+    state.invalidated = true;
+    session.update();
+  }
+
+  function moveSelection(delta: number) {
+    if (state.items.length === 0) {
+      return;
+    }
+    state.selectedIndex = (state.selectedIndex + delta + state.items.length) % state.items.length;
+    session.update();
+  }
+
+  function quit() {
+    state.running = false;
+    client.clear();
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "f", command: { id: "query.fetch" }, scope: "global" },
+        { key: "F", command: { id: "query.fetch" }, scope: "global" },
+        { key: "i", command: { id: "query.invalidate" }, scope: "global" },
+        { key: "I", command: { id: "query.invalidate" }, scope: "global" },
+        { key: "j", command: { id: "inventory.next" }, scope: "global" },
+        { key: "J", command: { id: "inventory.next" }, scope: "global" },
+        { key: "k", command: { id: "inventory.previous" }, scope: "global" },
+        { key: "K", command: { id: "inventory.previous" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "query.fetch") {
+          void fetchInventory();
+          return true;
+        }
+        if (command.id === "query.invalidate") {
+          invalidateInventory();
+          return true;
+        }
+        if (command.id === "inventory.next") {
+          moveSelection(1);
+          return true;
+        }
+        if (command.id === "inventory.previous") {
+          moveSelection(-1);
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      client.clear();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleQueryDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("F");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("J");
+    demo.dispatchKey("I");
+    demo.dispatchKey("F");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleQueryDemo();
+  }
+}

package/examples/docs/module-request.tsx

@@ -0,0 +1,194 @@
+import { request } from "valyrian.js/request";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+interface RequestState {
+  status: "idle" | "loading" | "success" | "error";
+  message: string;
+  fetchedPath: string;
+  lastError: string;
+  failNext: boolean;
+  history: Array<"success" | "error">;
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createState(): RequestState {
+  return {
+    status: "idle",
+    message: "Ready to check the service status",
+    fetchedPath: "none",
+    lastError: "none",
+    failNext: false,
+    history: [],
+    running: true
+  };
+}
+
+function historySummary(history: RequestState["history"]) {
+  return history.length === 0 ? "none" : history.join(" -> ");
+}
+
+const api = request.new("http://terminal.local", { allowedMethods: ["get"] });
+
+async function withFakeFetch<T>(shouldFail: boolean, run: () => Promise<T>) {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL) => {
+    const url = new URL(String(input));
+    if (shouldFail) {
+      return Promise.resolve(
+        new Response(JSON.stringify({ message: "controlled local failure" }), { status: 503 })
+      );
+    }
+    return Promise.resolve(
+      new Response(JSON.stringify({ status: "ok", path: `${url.pathname}${url.search}` }), { status: 200 })
+    );
+  }) as typeof fetch;
+
+  try {
+    return await run();
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+}
+
+export function App({ state }: { state: RequestState }) {
+  return (
+    <Screen title="Service Status Client">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Service Status Client</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Status Client: checks a local service endpoint without using the network.</Text>
+        <Text>{`Request status: ${state.status}`}</Text>
+        <Text>{state.message}</Text>
+        <Text>{`Fetched: ${state.fetchedPath}`}</Text>
+        <Text>{`Last error: ${state.lastError}`}</Text>
+        <Text>{`Next request: ${state.failNext ? "controlled error" : "success"}`}</Text>
+        <Text>{`History: ${historySummary(state.history)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>R: refresh status   E: force next error   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleRequestDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state = createState();
+  let session: TerminalSession;
+
+  async function loadStatus() {
+    if (state.status === "loading") {
+      state.message = "Refresh already in progress";
+      session.update();
+      return;
+    }
+
+    state.status = "loading";
+    state.message = "Loading local service status";
+    session.update();
+    try {
+      const shouldFail = state.failNext;
+      state.failNext = false;
+      const body = (await withFakeFetch(shouldFail, () => api.get("/status", { page: 1 }))) as { status: string; path: string };
+      state.status = "success";
+      state.history.push("success");
+      state.message = state.lastError === "none" ? `HTTP status: ${body.status}` : `Retry result: ${body.status}`;
+      state.fetchedPath = body.path;
+    } catch (error) {
+      state.status = "error";
+      state.history.push("error");
+      state.message = error instanceof Error ? error.message : "Request failed";
+      state.lastError = state.message;
+      state.fetchedPath = "/status?page=1";
+    }
+    session.update();
+  }
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "r", command: { id: "request.load" }, scope: "global" },
+        { key: "R", command: { id: "request.load" }, scope: "global" },
+        { key: "e", command: { id: "request.failNext" }, scope: "global" },
+        { key: "E", command: { id: "request.failNext" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "request.load") {
+          void loadStatus();
+          return true;
+        }
+        if (command.id === "request.failNext") {
+          state.failNext = true;
+          state.message = "Next refresh will use the controlled error path";
+          session.update();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleRequestDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("E");
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleRequestDemo();
+  }
+}

package/examples/docs/module-state-workbench.tsx

@@ -0,0 +1,283 @@
+import { v } from "valyrian.js";
+import { createPulse, createPulseStore } from "valyrian.js/pulses";
+import { FluxStore } from "valyrian.js/flux-store";
+import { Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+type JobStatus = "queued" | "running" | "done" | "blocked";
+type OperationAction = "dispatch" | "done" | "block" | "reset";
+
+interface Job {
+  id: string;
+  label: string;
+  owner: string;
+  status: JobStatus;
+}
+
+interface OperationEvent {
+  action: OperationAction;
+  job: string;
+  note: string;
+}
+
+interface ModuleStateWorkbenchDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const INITIAL_JOBS: Job[] = [
+  { id: "docs", label: "Docs refresh", owner: "Mina", status: "running" },
+  { id: "release", label: "Package release", owner: "Omar", status: "queued" },
+  { id: "support", label: "Support sweep", owner: "Iris", status: "blocked" }
+];
+
+function createWorkbenchStores() {
+  const jobsStore = createPulseStore(
+    {
+      selectedIndex: 0,
+      jobs: INITIAL_JOBS.map((job) => ({ ...job }))
+    },
+    {
+      selectNext(state) {
+        state.selectedIndex = (state.selectedIndex + 1) % state.jobs.length;
+      },
+      selectPrevious(state) {
+        state.selectedIndex = (state.selectedIndex - 1 + state.jobs.length) % state.jobs.length;
+      },
+      updateSelectedStatus(state, status: JobStatus) {
+        state.jobs[state.selectedIndex].status = status;
+      },
+      reset(state) {
+        state.selectedIndex = 0;
+        state.jobs = INITIAL_JOBS.map((job) => ({ ...job }));
+      }
+    }
+  );
+
+  const [pulseRevision, setPulseRevision] = createPulse(1);
+
+  const operations = new FluxStore({
+    state: {
+      done: 0,
+      blocked: 1,
+      dispatched: 0,
+      timeline: ["Bootstrapped queue", "Loaded terminal session"] as string[],
+      lastAction: "dispatch" as OperationAction
+    },
+    mutations: {
+      SET_METRICS(state, jobs: Job[]) {
+        state.done = jobs.filter((job) => job.status === "done").length;
+        state.blocked = jobs.filter((job) => job.status === "blocked").length;
+      },
+      RECORD_EVENT(state, event: OperationEvent) {
+        state.lastAction = event.action;
+        state.dispatched += event.action === "dispatch" ? 1 : 0;
+        state.timeline.push(`${event.action}: ${event.job} — ${event.note}`);
+        state.timeline = state.timeline.slice(-5);
+      },
+      RESET(state) {
+        state.done = 0;
+        state.blocked = 1;
+        state.dispatched = 0;
+        state.lastAction = "reset";
+        state.timeline = ["reset: queue — restored baseline"];
+      }
+    },
+    actions: {
+      async dispatchSelected(store, job: Job) {
+        jobsStore.updateSelectedStatus("running");
+        store.commit("SET_METRICS", jobsStore.state.jobs);
+        store.commit("RECORD_EVENT", { action: "dispatch", job: job.label, note: "operator started work" });
+      },
+      async markDone(store, job: Job) {
+        jobsStore.updateSelectedStatus("done");
+        store.commit("SET_METRICS", jobsStore.state.jobs);
+        store.commit("RECORD_EVENT", { action: "done", job: job.label, note: "closed cleanly" });
+      },
+      async blockSelected(store, job: Job) {
+        jobsStore.updateSelectedStatus("blocked");
+        store.commit("SET_METRICS", jobsStore.state.jobs);
+        store.commit("RECORD_EVENT", { action: "block", job: job.label, note: "needs review" });
+      }
+    }
+  });
+
+  return { jobsStore, operations, pulseRevision, setPulseRevision };
+}
+
+type WorkbenchStores = ReturnType<typeof createWorkbenchStores>;
+
+const SURFACE_STYLE = { color: "#f5f5f5", background: "#111827", padding: { left: 1, right: 1 } };
+const DETAIL_STYLE = { color: "#f8fafc", background: "#172554", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#d1d5db", background: "#1f2937" };
+const CURRENT_STYLE = { color: "#ffffff", background: "#14532d" };
+const MUTED_STYLE = { color: "#9ca3af" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function selectedJob(stores: WorkbenchStores) {
+  return stores.jobsStore.state.jobs[stores.jobsStore.state.selectedIndex];
+}
+
+function resetStores(stores: WorkbenchStores) {
+  stores.jobsStore.reset();
+  stores.operations.commit("RESET");
+  stores.setPulseRevision(1);
+}
+
+function bumpRevision(stores: WorkbenchStores) {
+  stores.setPulseRevision((value) => value + 1);
+}
+
+export function App({ stores }: { stores: WorkbenchStores }) {
+  const selected = selectedJob(stores);
+  const manualVNode = v(Text, { style: MUTED_STYLE }, `Tracked jobs: ${stores.jobsStore.state.jobs.length}`);
+
+  return (
+    <Screen title="Operations Workbench">
+      <Text style={{ color: "#ffffff", background: "#0f172a" }}>Valyrian.js modules in terminal apps: state workbench</Text>
+      <Split direction="row" gap={1} sizes={["2fr", "1fr"]}>
+        <Pane style={SURFACE_STYLE}>
+          <Text>Operations Workbench</Text>
+          <Text>{`Pulse revision: ${stores.pulseRevision()}  Done jobs: ${stores.operations.state.done}  Blocked jobs: ${stores.operations.state.blocked}`}</Text>
+          <Text>{`Dispatches: ${stores.operations.state.dispatched}  Last action: ${stores.operations.state.lastAction}`}</Text>
+          {stores.jobsStore.state.jobs.map((job, index) => (
+            <Text state={index === stores.jobsStore.state.selectedIndex ? "current" : undefined} style={index === stores.jobsStore.state.selectedIndex ? undefined : MUTED_STYLE} styles={{ current: CURRENT_STYLE }}>{`${index === stores.jobsStore.state.selectedIndex ? ">" : " "} ${job.label} — ${job.owner} — ${job.status}`}</Text>
+          ))}
+        </Pane>
+        <Pane style={DETAIL_STYLE}>
+          <Text>{`Selected: ${selected.label}`}</Text>
+          <Text>{`Owner: ${selected.owner}`}</Text>
+          <Text>{`Status: ${selected.status}`}</Text>
+          {manualVNode}
+          <Text>FluxStore dispatch coordinates operation actions.</Text>
+          <Text>{`Timeline: ${stores.operations.state.timeline.slice(-3).join(" | ")}`}</Text>
+        </Pane>
+      </Split>
+      <Text style={FOOTER_STYLE}>J/K: select   Enter: dispatch   D: done   B: block   R: reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleStateWorkbenchDemo(options: TerminalMountOptions = {}): ModuleStateWorkbenchDemo {
+  const stores = createWorkbenchStores();
+  resetStores(stores);
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function updateAfterOperation() {
+    bumpRevision(stores);
+    session.update();
+  }
+
+  function runSelected(action: "dispatchSelected" | "markDone" | "blockSelected") {
+    const job = selectedJob(stores);
+    void stores.operations.dispatch(action, job).then(updateAfterOperation);
+    updateAfterOperation();
+  }
+
+  session = mountTerminal(<App stores={stores} />, {
+    ...options,
+    cols: options.cols ?? 100,
+    rows: options.rows ?? 24,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "jobs.next" }, scope: "global" },
+        { key: "J", command: { id: "jobs.next" }, scope: "global" },
+        { key: "k", command: { id: "jobs.previous" }, scope: "global" },
+        { key: "K", command: { id: "jobs.previous" }, scope: "global" },
+        { key: "ENTER", command: { id: "jobs.dispatch" }, scope: "global" },
+        { key: "d", command: { id: "jobs.done" }, scope: "global" },
+        { key: "D", command: { id: "jobs.done" }, scope: "global" },
+        { key: "b", command: { id: "jobs.block" }, scope: "global" },
+        { key: "B", command: { id: "jobs.block" }, scope: "global" },
+        { key: "r", command: { id: "jobs.reset" }, scope: "global" },
+        { key: "R", command: { id: "jobs.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "jobs.next") {
+          stores.jobsStore.selectNext();
+          session.update();
+          return true;
+        }
+        if (command.id === "jobs.previous") {
+          stores.jobsStore.selectPrevious();
+          session.update();
+          return true;
+        }
+        if (command.id === "jobs.dispatch") {
+          runSelected("dispatchSelected");
+          return true;
+        }
+        if (command.id === "jobs.done") {
+          runSelected("markDone");
+          return true;
+        }
+        if (command.id === "jobs.block") {
+          runSelected("blockSelected");
+          return true;
+        }
+        if (command.id === "jobs.reset") {
+          resetStores(stores);
+          session.update();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleStateWorkbenchDemo({ runtime: "headless", cols: 100, rows: 24 });
+    demo.dispatchKey("J");
+    demo.dispatchKey("ENTER");
+    demo.dispatchKey("D");
+    demo.dispatchKey("K");
+    demo.dispatchKey("B");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleStateWorkbenchDemo();
+  }
+}