@valyrianjs/terminal 0.2.0 → 0.2.2

package/examples/docs/module-api-dashboard.tsx

@@ -0,0 +1,307 @@
+import { QueryClient } from "valyrian.js/query";
+import { request } from "valyrian.js/request";
+import { Task } from "valyrian.js/tasks";
+import { Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ServiceStatus {
+  service: string;
+  queue: number;
+  version: string;
+}
+
+interface ApiDashboardState {
+  errorMode: boolean;
+  service: string;
+  queryStatus: string;
+  apiMessage: string;
+  invalidated: boolean;
+  taskStatus: string;
+  taskResult: string;
+  taskError: string;
+  taskJob: string;
+  running: boolean;
+}
+
+interface ModuleApiDashboardDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#0f172a", padding: { left: 1, right: 1 } };
+const API_STYLE = { color: "#ffffff", background: "#164e63", padding: { left: 1, right: 1 } };
+const TASK_STYLE = { color: "#ffffff", background: "#312e81", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+const ERROR_STYLE = { color: "#ffffff", background: "#7f1d1d" };
+const SUCCESS_STYLE = { color: "#ffffff", background: "#14532d" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createState(): ApiDashboardState {
+  return {
+    errorMode: false,
+    service: "idle",
+    queryStatus: "idle",
+    apiMessage: "No request yet",
+    invalidated: false,
+    taskStatus: "idle",
+    taskResult: "Result: none",
+    taskError: "Error: none",
+    taskJob: "none",
+    running: true
+  };
+}
+
+async function withFakeFetch<T>(state: ApiDashboardState, run: () => Promise<T>) {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL) => {
+    const url = String(input);
+    if (state.errorMode || url.endsWith("/failure")) {
+      return Promise.resolve(new Response(JSON.stringify({ message: "controlled request failure" }), { status: 503 }));
+    }
+    return Promise.resolve(new Response(JSON.stringify({ service: "healthy", queue: 3, version: "local-1" }), { status: 200 }));
+  }) as typeof fetch;
+
+  try {
+    return await run();
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+}
+
+function waitForTask(signal: AbortSignal) {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, 20);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+
+function syncTaskState(state: ApiDashboardState, task: Task<string, string>) {
+  const snapshot = task.state;
+  state.taskStatus = snapshot.status;
+  state.taskResult = snapshot.result ? `Result: ${snapshot.result}` : "Result: none";
+  state.taskError = snapshot.error instanceof Error ? `Error: ${snapshot.error.message}` : "Error: none";
+}
+
+export function App({ state }: { state: ApiDashboardState }) {
+  return (
+    <Screen title="API Operations Dashboard">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Valyrian.js modules in terminal apps: API dashboard</Text>
+      <Split direction="row" gap={1} sizes={["1fr", "1fr"]}>
+        <Pane style={API_STYLE}>
+          <Text>API Operations Dashboard</Text>
+          <Text>{`Mode: ${state.errorMode ? "forced error" : "success"}`}</Text>
+          <Text state={state.queryStatus === "error" ? "error" : "success"} styles={{ error: ERROR_STYLE, success: SUCCESS_STYLE }}>{state.apiMessage}</Text>
+          <Text>{`Query: ${state.queryStatus}`}</Text>
+          <Text>{`Invalidated: ${state.invalidated ? "yes" : "no"}`}</Text>
+          <Text>{`Service: ${state.service}`}</Text>
+        </Pane>
+        <Pane style={TASK_STYLE}>
+          <Text>Maintenance task</Text>
+          <Text>{`Task: ${state.taskStatus}`}</Text>
+          <Text>{`Job: ${state.taskJob}`}</Text>
+          <Text>{state.taskResult}</Text>
+          <Text>{state.taskError}</Text>
+          <Text>Request and query use a local fake fetch, so this example never calls the network.</Text>
+        </Pane>
+      </Split>
+      <Pane style={PANEL_STYLE}>
+        <Text>R: refresh   E: force error   I: invalidate   T: start task   C: cancel   Ctrl+C: quit</Text>
+        <Text style={FOOTER_STYLE}>See the Valyrian.js documentation for request, query, and tasks.</Text>
+      </Pane>
+    </Screen>
+  );
+}
+
+export function createModuleApiDashboardDemo(options: TerminalMountOptions = {}): ModuleApiDashboardDemo {
+  const state = createState();
+  const client = new QueryClient({ staleTime: 0, cacheTime: 1000 });
+  const api = request.new("http://terminal.local", { allowedMethods: ["get"] });
+  const serviceQuery = client.query({
+    key: ["terminal", "service-status"],
+    fetcher: () => api.get("/health")
+  });
+  const maintenanceTask = new Task<string, string>(async (label, { signal }) => {
+    if (label === "scan") {
+      await waitForTask(signal);
+      if (signal.aborted) return "Cancelled stale scan";
+    }
+    if (label === "fail") throw new Error("controlled task failure");
+    return `Completed ${label}`;
+  }, { strategy: "restartable" });
+  let session: TerminalSession;
+  const offTaskState = maintenanceTask.on("state", () => {
+    syncTaskState(state, maintenanceTask);
+    session?.update();
+  });
+
+  function quit() {
+    state.running = false;
+    offTaskState();
+    client.clear();
+    maintenanceTask.reset();
+    session.destroy();
+  }
+
+  async function refresh() {
+    if (state.queryStatus === "loading") {
+      state.apiMessage = "Refresh already in progress";
+      session.update();
+      return;
+    }
+
+    state.queryStatus = "loading";
+    state.apiMessage = state.errorMode ? "Loading forced error" : "Loading service status";
+    session.update();
+    try {
+      const data = (await withFakeFetch(state, () => serviceQuery.fetch())) as ServiceStatus;
+      state.service = data.service;
+      state.queryStatus = serviceQuery.state.status;
+      state.apiMessage = `Service: ${data.service}  Queue: ${data.queue}  Version: ${data.version}`;
+      state.invalidated = false;
+    } catch {
+      state.service = "unavailable";
+      state.queryStatus = serviceQuery.state.status;
+      state.apiMessage = "API error: controlled request failure";
+    }
+    session.update();
+  }
+
+  function invalidate() {
+    serviceQuery.invalidate();
+    state.queryStatus = serviceQuery.state.status;
+    state.invalidated = true;
+    state.apiMessage = "Cache invalidated; refresh will fetch again";
+    session.update();
+  }
+
+  async function runMaintenance(label: string, job: string) {
+    state.taskJob = job;
+    syncTaskState(state, maintenanceTask);
+    session.update();
+    try {
+      await maintenanceTask.run(label);
+    } catch {
+      // Task state stores the controlled error for the UI.
+    }
+    syncTaskState(state, maintenanceTask);
+    session.update();
+  }
+
+  function cancelMaintenance() {
+    state.taskJob = "stale scan";
+    void maintenanceTask.run("scan");
+    syncTaskState(state, maintenanceTask);
+    maintenanceTask.cancel();
+    syncTaskState(state, maintenanceTask);
+    session.update();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 96,
+    rows: options.rows ?? 22,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "r", command: { id: "api.refresh" }, scope: "global" },
+        { key: "R", command: { id: "api.refresh" }, scope: "global" },
+        { key: "e", command: { id: "api.error" }, scope: "global" },
+        { key: "E", command: { id: "api.error" }, scope: "global" },
+        { key: "i", command: { id: "api.invalidate" }, scope: "global" },
+        { key: "I", command: { id: "api.invalidate" }, scope: "global" },
+        { key: "t", command: { id: "task.run" }, scope: "global" },
+        { key: "T", command: { id: "task.run" }, scope: "global" },
+        { key: "c", command: { id: "task.cancel" }, scope: "global" },
+        { key: "C", command: { id: "task.cancel" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "api.refresh") {
+          void refresh();
+          return true;
+        }
+        if (command.id === "api.error") {
+          state.errorMode = true;
+          state.apiMessage = "Next refresh will use controlled error";
+          session.update();
+          return true;
+        }
+        if (command.id === "api.invalidate") {
+          invalidate();
+          return true;
+        }
+        if (command.id === "task.run") {
+          void runMaintenance("maintenance", "maintenance");
+          return true;
+        }
+        if (command.id === "task.cancel") {
+          cancelMaintenance();
+          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;
+      offTaskState();
+      client.clear();
+      maintenanceTask.reset();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleApiDashboardDemo({ runtime: "headless", cols: 96, rows: 22 });
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("I");
+    demo.dispatchKey("E");
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("T");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("C");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleApiDashboardDemo();
+  }
+}

package/examples/docs/module-flux-store.tsx

@@ -0,0 +1,181 @@
+import { FluxStore } from "valyrian.js/flux-store";
+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;
+}
+
+type JobStatus = "queued" | "running" | "done" | "blocked";
+type Job = { name: string; status: JobStatus };
+type QueueState = { selected: number; jobs: Job[] };
+
+type QueueGetters = { doneCount: number; activeJob: string };
+type QueueStore = FluxStore & { state: QueueState; getters: QueueGetters };
+
+const INITIAL_JOBS: Job[] = [
+  { name: "Sync warehouse feed", status: "queued" },
+  { name: "Package release", status: "queued" },
+  { name: "Review failed payouts", status: "blocked" }
+];
+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 createQueueStore(): QueueStore {
+  return new FluxStore({
+    state: { selected: 0, jobs: INITIAL_JOBS.map((job) => ({ ...job })) },
+    mutations: {
+      SELECT_NEXT(state) {
+        const queueState = state as QueueState;
+        queueState.selected = (queueState.selected + 1) % queueState.jobs.length;
+      },
+      SELECT_PREVIOUS(state) {
+        const queueState = state as QueueState;
+        queueState.selected = (queueState.selected - 1 + queueState.jobs.length) % queueState.jobs.length;
+      },
+      SET_STATUS(state, status: JobStatus) {
+        const queueState = state as QueueState;
+        queueState.jobs = queueState.jobs.map((job, index) => (index === queueState.selected ? { ...job, status } : job));
+      },
+      RESET(state) {
+        const queueState = state as QueueState;
+        queueState.selected = 0;
+        queueState.jobs = INITIAL_JOBS.map((job) => ({ ...job }));
+      }
+    },
+    getters: {
+      doneCount(state) {
+        const queueState = state as QueueState;
+        return queueState.jobs.filter((job) => job.status === "done").length;
+      },
+      activeJob(state) {
+        const queueState = state as QueueState;
+        return queueState.jobs[queueState.selected].name;
+      }
+    }
+  }) as QueueStore;
+}
+
+export function App({ store }: { store: QueueStore }) {
+  return (
+    <Screen title="Operations Queue Manager">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Operations Queue Manager</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Queue Manager</Text>
+        {store.state.jobs.map((job, index) => (
+          <Text>{`${index === store.state.selected ? ">" : " "} ${job.name} — ${job.status}`}</Text>
+        ))}
+        <Text>{`Selected: ${store.getters.activeJob}`}</Text>
+        <Text>{`Done jobs: ${store.getters.doneCount}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K select   S start   D mark done   B block   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleFluxStoreDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const store = createQueueStore();
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App store={store} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "queue.next" }, scope: "global" },
+        { key: "J", command: { id: "queue.next" }, scope: "global" },
+        { key: "k", command: { id: "queue.previous" }, scope: "global" },
+        { key: "K", command: { id: "queue.previous" }, scope: "global" },
+        { key: "s", command: { id: "queue.start" }, scope: "global" },
+        { key: "S", command: { id: "queue.start" }, scope: "global" },
+        { key: "d", command: { id: "queue.done" }, scope: "global" },
+        { key: "D", command: { id: "queue.done" }, scope: "global" },
+        { key: "b", command: { id: "queue.block" }, scope: "global" },
+        { key: "B", command: { id: "queue.block" }, scope: "global" },
+        { key: "r", command: { id: "queue.reset" }, scope: "global" },
+        { key: "R", command: { id: "queue.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "queue.next") {
+          store.commit("SELECT_NEXT");
+          return true;
+        }
+        if (command.id === "queue.previous") {
+          store.commit("SELECT_PREVIOUS");
+          return true;
+        }
+        if (command.id === "queue.start") {
+          store.commit("SET_STATUS", "running");
+          return true;
+        }
+        if (command.id === "queue.done") {
+          store.commit("SET_STATUS", "done");
+          return true;
+        }
+        if (command.id === "queue.block") {
+          store.commit("SET_STATUS", "blocked");
+          return true;
+        }
+        if (command.id === "queue.reset") {
+          store.commit("RESET");
+          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 = createModuleFluxStoreDemo({ runtime: "headless", cols: 92, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleFluxStoreDemo();
+  }
+}