@akta/dao-cli 0.1.0

package/src/tui/app.ts

@@ -0,0 +1,366 @@
+import type { AkitaNetwork } from "@akta/sdk";
+import { createDAO } from "../sdk";
+import { jsonReplacer } from "../output";
+import { enterRawMode, exitRawMode, writeFrame, getTermSize, onResize } from "./terminal";
+import { startKeyListener } from "./input";
+import { renderFrame } from "./renderer";
+import type { AppState, KeyAction, LoadResult, View, ViewContext, ViewId } from "./types";
+import { TABS } from "./types";
+
+// ── Views ───────────────────────────────────────────────────────
+
+import { daoView } from "./views/dao";
+import { feesView } from "./views/fees";
+import { walletView, cycleWalletAccount, getSelectedAccountLine, invalidateWalletCache } from "./views/wallet";
+import { proposalsListView, cycleProposalCursor, getProposalCursor, invalidateProposalsCache } from "./views/proposals-list";
+
+// ── View cache ──────────────────────────────────────────────────
+
+interface CacheEntry {
+  lines: string[];
+  fixedRight?: string[];
+  ts: number;
+}
+
+const CACHE_TTL = 30_000; // 30 seconds
+
+// ── Main TUI ────────────────────────────────────────────────────
+
+export async function startTUI(network: AkitaNetwork): Promise<void> {
+  const dao = createDAO(network);
+
+  const state: AppState = {
+    tab: "dao",
+    walletAccountIdx: 0,
+    scrollOffset: 0,
+    cursor: 0,
+    viewStack: [],
+    jsonMode: false,
+  };
+
+  const cache = new Map<string, CacheEntry>();
+  let currentLines: string[] = [];
+  let currentFixedRight: string[] | undefined;
+  let loading = false;
+  let loadGeneration = 0; // guards against stale async renders
+  let stopKeyListener: (() => void) | null = null;
+  let removeResizeListener: (() => void) | null = null;
+  let pendingScrollTo: (() => number) | null = null;
+
+  // ── Helpers ─────────────────────────────────────────────────
+
+  function viewKey(vid: ViewId): string {
+    return vid.tab;
+  }
+
+  function currentViewId(): ViewId {
+    if (state.viewStack.length > 0) {
+      return state.viewStack[state.viewStack.length - 1];
+    }
+    return { tab: state.tab } as ViewId;
+  }
+
+  function getView(vid: ViewId): View {
+    switch (vid.tab) {
+      case "dao": return daoView;
+      case "fees": return feesView;
+      case "wallet": return walletView;
+      case "proposals": return proposalsListView;
+    }
+  }
+
+  function viewportHeight(): number {
+    return getTermSize().rows - 3;
+  }
+
+  function clampScroll(): void {
+    const totalLines = Math.max(currentLines.length, currentFixedRight?.length ?? 0);
+    const maxScroll = Math.max(0, totalLines - viewportHeight());
+    state.scrollOffset = Math.max(0, Math.min(state.scrollOffset, maxScroll));
+  }
+
+  /** Ensure the selected proposal row is visible in the viewport. */
+  function scrollToProposalCursor(): void {
+    // Left panel structure: "" + panel-border + header-row + data-rows + border
+    // The cursor item is at line 3 + cursorIndex
+    const line = 3 + getProposalCursor();
+    ensureLineVisible(line);
+  }
+
+  function ensureLineVisible(line: number): void {
+    const vh = viewportHeight();
+    if (line < state.scrollOffset) {
+      state.scrollOffset = line;
+    } else if (line >= state.scrollOffset + vh) {
+      state.scrollOffset = line - vh + 1;
+    }
+  }
+
+  // ── Render cycle ────────────────────────────────────────────
+
+  function render(): void {
+    const { rows, cols } = getTermSize();
+    const frame = renderFrame(state, currentLines, rows, cols, loading, currentFixedRight);
+    writeFrame(frame);
+  }
+
+  async function loadAndRender(forceRefresh = false): Promise<void> {
+    const vid = currentViewId();
+    const key = viewKey(vid);
+    const { cols } = getTermSize();
+
+    // Check cache
+    if (!forceRefresh && !state.jsonMode) {
+      const cached = cache.get(key);
+      if (cached && Date.now() - cached.ts < CACHE_TTL) {
+        currentLines = cached.lines;
+        currentFixedRight = cached.fixedRight;
+        clampScroll();
+        render();
+        return;
+      }
+    }
+
+    // Show loading state
+    const gen = ++loadGeneration;
+    loading = true;
+    render();
+
+    try {
+      const view = getView(vid);
+      const ctx: ViewContext = {
+        width: cols,
+        height: viewportHeight(),
+        network,
+        dao,
+        navigate: (target: ViewId) => {
+          state.viewStack.push(target);
+          state.scrollOffset = 0;
+          state.cursor = 0;
+          loadAndRender();
+        },
+        refresh: () => loadAndRender(true),
+      };
+
+      const result = await view.load(ctx);
+
+      // Discard result if user navigated away during the async load
+      if (gen !== loadGeneration) return;
+
+      // Normalize result — views can return string[] or LoadResult
+      let lines: string[];
+      let fixedRight: string[] | undefined;
+      if (Array.isArray(result)) {
+        lines = result;
+      } else {
+        lines = result.lines;
+        fixedRight = result.fixedRight;
+      }
+
+      // JSON mode: re-render as JSON (flatten both panels)
+      if (state.jsonMode) {
+        const jsonStr = JSON.stringify(lines, jsonReplacer, 2);
+        lines = jsonStr.split("\n");
+        fixedRight = undefined;
+      }
+
+      // Update cache (not for JSON mode)
+      if (!state.jsonMode) {
+        cache.set(key, { lines, fixedRight, ts: Date.now() });
+      }
+
+      currentLines = lines;
+      currentFixedRight = fixedRight;
+    } catch (err: any) {
+      // Discard error if user navigated away
+      if (gen !== loadGeneration) return;
+
+      currentLines = [
+        "",
+        `  Error: ${err.message ?? err}`,
+        "",
+        "  Press 'r' to retry.",
+      ];
+      currentFixedRight = undefined;
+    }
+
+    loading = false;
+
+    // Apply pending scroll-to (set before loadAndRender, resolved after load)
+    if (pendingScrollTo) {
+      ensureLineVisible(pendingScrollTo());
+      pendingScrollTo = null;
+    }
+
+    clampScroll();
+    render();
+  }
+
+  // ── Input handling ──────────────────────────────────────────
+
+  function handleKey(action: KeyAction): void {
+    switch (action.type) {
+      case "quit":
+        cleanup();
+        process.exit(0);
+        break;
+
+      case "tab-next": {
+        if (state.viewStack.length > 0) {
+          state.viewStack = [];
+        }
+        const tabIdx = TABS.indexOf(state.tab);
+        state.tab = TABS[(tabIdx + 1) % TABS.length];
+        state.scrollOffset = 0;
+        state.cursor = 0;
+        loadAndRender();
+        break;
+      }
+
+      case "tab-prev": {
+        if (state.viewStack.length > 0) {
+          state.viewStack = [];
+        }
+        const tabIdx = TABS.indexOf(state.tab);
+        state.tab = TABS[(tabIdx - 1 + TABS.length) % TABS.length];
+        state.scrollOffset = 0;
+        state.cursor = 0;
+        loadAndRender();
+        break;
+      }
+
+      case "sub-next": {
+        if (state.tab === "wallet") {
+          cycleWalletAccount(1);
+          cache.delete("wallet");
+          pendingScrollTo = () => getSelectedAccountLine() + 1;
+          loadAndRender();
+        } else if (state.tab === "proposals" && state.viewStack.length === 0) {
+          cycleProposalCursor(1);
+          cache.delete("proposals");
+          scrollToProposalCursor();
+          loadAndRender();
+        } else {
+          handleKey({ type: "tab-next" });
+        }
+        break;
+      }
+
+      case "sub-prev": {
+        if (state.tab === "wallet") {
+          cycleWalletAccount(-1);
+          cache.delete("wallet");
+          pendingScrollTo = () => getSelectedAccountLine() + 1;
+          loadAndRender();
+        } else if (state.tab === "proposals" && state.viewStack.length === 0) {
+          cycleProposalCursor(-1);
+          cache.delete("proposals");
+          scrollToProposalCursor();
+          loadAndRender();
+        } else {
+          handleKey({ type: "tab-prev" });
+        }
+        break;
+      }
+
+      case "up":
+        if (state.scrollOffset > 0) {
+          state.scrollOffset--;
+          render();
+        }
+        break;
+
+      case "down": {
+        const totalLines = Math.max(currentLines.length, currentFixedRight?.length ?? 0);
+        const maxScroll = Math.max(0, totalLines - viewportHeight());
+        if (state.scrollOffset < maxScroll) {
+          state.scrollOffset++;
+          render();
+        }
+        break;
+      }
+
+      case "page-up":
+        state.scrollOffset = Math.max(0, state.scrollOffset - 10);
+        render();
+        break;
+
+      case "page-down": {
+        const totalLines = Math.max(currentLines.length, currentFixedRight?.length ?? 0);
+        const maxScroll = Math.max(0, totalLines - viewportHeight());
+        state.scrollOffset = Math.min(maxScroll, state.scrollOffset + 10);
+        render();
+        break;
+      }
+
+      case "top":
+        state.scrollOffset = 0;
+        render();
+        break;
+
+      case "bottom": {
+        const totalLines = Math.max(currentLines.length, currentFixedRight?.length ?? 0);
+        const maxScroll = Math.max(0, totalLines - viewportHeight());
+        state.scrollOffset = maxScroll;
+        render();
+        break;
+      }
+
+      case "back":
+        if (state.viewStack.length > 0) {
+          state.viewStack.pop();
+          state.scrollOffset = 0;
+          state.cursor = 0;
+          loadAndRender();
+        }
+        break;
+
+      case "refresh":
+        // Invalidate cache for current view
+        cache.delete(viewKey(currentViewId()));
+        if (state.tab === "wallet") {
+          invalidateWalletCache();
+        } else if (state.tab === "proposals") {
+          invalidateProposalsCache();
+        }
+        loadAndRender(true);
+        break;
+
+      case "json":
+        state.jsonMode = !state.jsonMode;
+        state.scrollOffset = 0;
+        loadAndRender();
+        break;
+    }
+  }
+
+  // ── Cleanup ─────────────────────────────────────────────────
+
+  function cleanup(): void {
+    if (stopKeyListener) stopKeyListener();
+    if (removeResizeListener) removeResizeListener();
+    exitRawMode();
+  }
+
+  // ── Startup ─────────────────────────────────────────────────
+
+  // Graceful exit handlers
+  process.on("SIGINT", () => { cleanup(); process.exit(0); });
+  process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+  process.on("uncaughtException", (err) => {
+    cleanup();
+    console.error("Uncaught exception:", err);
+    process.exit(1);
+  });
+
+  enterRawMode();
+  stopKeyListener = startKeyListener(handleKey);
+  removeResizeListener = onResize(() => {
+    // Invalidate all cache (widths changed)
+    cache.clear();
+    loadAndRender();
+  });
+
+  // Initial load
+  await loadAndRender();
+}

package/src/tui/input.ts

@@ -0,0 +1,85 @@
+import type { KeyAction } from "./types";
+
+type KeyHandler = (action: KeyAction) => void;
+
+/**
+ * Start listening for keypresses on stdin (must be in raw mode).
+ * Returns a cleanup function to stop listening.
+ */
+export function startKeyListener(handler: KeyHandler): () => void {
+  let escTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function onData(buf: Buffer) {
+    const seq = buf.toString("utf8");
+
+    // Ctrl+C
+    if (seq === "\x03") return handler({ type: "quit" });
+
+    // Escape sequences (arrows, page up/down, etc.)
+    if (seq.startsWith("\x1b")) {
+      // Clear any pending standalone Esc
+      if (escTimer) {
+        clearTimeout(escTimer);
+        escTimer = null;
+      }
+
+      // Known escape sequences
+      const mapped = mapEscapeSequence(seq);
+      if (mapped) return handler(mapped);
+
+      // Could be standalone Esc — wait 50ms to distinguish
+      if (seq === "\x1b") {
+        escTimer = setTimeout(() => {
+          escTimer = null;
+          handler({ type: "back" });
+        }, 50);
+        return;
+      }
+
+      // Unknown escape sequence, ignore
+      return;
+    }
+
+    // Single character keys
+    const action = mapCharKey(seq);
+    if (action) handler(action);
+  }
+
+  process.stdin.on("data", onData);
+
+  return () => {
+    process.stdin.off("data", onData);
+    if (escTimer) {
+      clearTimeout(escTimer);
+      escTimer = null;
+    }
+  };
+}
+
+function mapEscapeSequence(seq: string): KeyAction | null {
+  switch (seq) {
+    case "\x1b[A": return { type: "up" };
+    case "\x1b[B": return { type: "down" };
+    case "\x1b[5~": return { type: "page-up" };
+    case "\x1b[6~": return { type: "page-down" };
+    case "\x1b[Z": return { type: "tab-prev" }; // Shift+Tab
+    default: return null;
+  }
+}
+
+function mapCharKey(seq: string): KeyAction | null {
+  switch (seq) {
+    case "q": return { type: "quit" };
+    case "\t": return { type: "tab-next" };
+    case "[": return { type: "sub-prev" };
+    case "]": return { type: "sub-next" };
+    case "k": return { type: "up" };
+    case "j": return { type: "json" };
+    case "g": return { type: "top" };
+    case "G": return { type: "bottom" };
+    case "\r": return { type: "enter" };
+    case "\x7f": return { type: "back" }; // Backspace
+    case "r": return { type: "refresh" };
+    default: return null;
+  }
+}

package/src/tui/panels.ts

@@ -0,0 +1,133 @@
+import { visibleLength, padEndVisible, truncateAnsi } from "../output";
+import theme from "../theme";
+
+// ── Types ──────────────────────────────────────────────────────
+
+export interface PanelOptions {
+  title?: string;
+  width: number;
+  padding?: number;
+}
+
+// ── Panel rendering ────────────────────────────────────────────
+
+/**
+ * Wrap content lines in box-drawing borders.
+ *
+ *   ┌─ Title ─────┐
+ *   │  content     │
+ *   └─────────────┘
+ */
+export function renderPanel(content: string[], opts: PanelOptions): string[] {
+  const { width, title, padding = 1 } = opts;
+  if (width < 4) return content;
+
+  const innerWidth = width - 2; // subtract left + right border chars
+  const padStr = " ".repeat(padding);
+  const contentWidth = innerWidth - padding * 2;
+
+  // Top border
+  let top: string;
+  if (title) {
+    const titleText = ` ${title} `;
+    const ruleAfter = innerWidth - 1 - visibleLength(titleText); // 1 for the leading ─
+    top =
+      theme.border("┌─") +
+      theme.panelTitle(titleText) +
+      theme.border("─".repeat(Math.max(0, ruleAfter)) + "┐");
+  } else {
+    top = theme.border("┌" + "─".repeat(innerWidth) + "┐");
+  }
+
+  // Bottom border
+  const bottom = theme.border("└" + "─".repeat(innerWidth) + "┘");
+
+  // Content lines — truncate/pad to fit
+  const border = theme.border("│");
+  const lines: string[] = [top];
+
+  for (const line of content) {
+    const vLen = visibleLength(line);
+    let fitted: string;
+    if (vLen > contentWidth) {
+      fitted = truncateAnsi(line, contentWidth);
+    } else {
+      fitted = padEndVisible(line, contentWidth);
+    }
+    lines.push(border + padStr + fitted + padStr + border);
+  }
+
+  lines.push(bottom);
+  return lines;
+}
+
+/**
+ * Place rendered panels side-by-side, padding shorter panels to match the tallest.
+ */
+export function renderPanelRow(panels: string[][], gap = 2): string[] {
+  if (panels.length === 0) return [];
+  if (panels.length === 1) return panels[0];
+
+  const maxHeight = Math.max(...panels.map((p) => p.length));
+  const gapStr = " ".repeat(gap);
+  const lines: string[] = [];
+
+  // Measure each panel's visible width from its first line
+  const panelWidths = panels.map((p) => (p.length > 0 ? visibleLength(p[0]) : 0));
+
+  for (let i = 0; i < maxHeight; i++) {
+    const parts: string[] = [];
+    for (let p = 0; p < panels.length; p++) {
+      const line = panels[p][i];
+      if (line !== undefined) {
+        // Pad to panel width for alignment
+        parts.push(padEndVisible(line, panelWidths[p]));
+      } else {
+        parts.push(" ".repeat(panelWidths[p]));
+      }
+    }
+    lines.push(parts.join(gapStr));
+  }
+
+  return lines;
+}
+
+/**
+ * Stack panel-rows vertically with optional gaps.
+ */
+export function renderPanelGrid(
+  rows: string[][][],
+  opts?: { rowGap?: number; colGap?: number },
+): string[] {
+  const { rowGap = 0, colGap = 2 } = opts ?? {};
+  const lines: string[] = [];
+
+  for (let r = 0; r < rows.length; r++) {
+    if (r > 0 && rowGap > 0) {
+      for (let g = 0; g < rowGap; g++) lines.push("");
+    }
+    lines.push(...renderPanelRow(rows[r], colGap));
+  }
+
+  return lines;
+}
+
+/**
+ * Divide total width among N panels accounting for gaps between them.
+ * Returns an array of widths. Any remainder pixels go to earlier panels.
+ */
+export function splitWidth(totalWidth: number, count: number, gap = 2): number[] {
+  if (count <= 0) return [];
+  if (count === 1) return [totalWidth];
+
+  const totalGap = gap * (count - 1);
+  const available = totalWidth - totalGap;
+  const base = Math.floor(available / count);
+  const remainder = available - base * count;
+
+  const widths: number[] = [];
+  for (let i = 0; i < count; i++) {
+    widths.push(base + (i < remainder ? 1 : 0));
+  }
+  return widths;
+}

package/src/tui/renderer.ts

@@ -0,0 +1,126 @@
+import type { AppState, TabId } from "./types";
+import { TABS, TAB_LABELS } from "./types";
+import { visibleLength, padEndVisible, truncateAnsi } from "../output";
+import theme from "../theme";
+
+// ── Tab bar ─────────────────────────────────────────────────────
+
+function renderTabBar(activeTab: TabId, width: number): string {
+  const prefix = theme.appName(" Akita DAO") + "   ";
+  const tabs = TABS.map((t) => {
+    const label = TAB_LABELS[t];
+    return t === activeTab
+      ? theme.activeTab(` ${label} `)
+      : theme.inactiveTab(` ${label} `);
+  }).join(theme.tabSeparator("│"));
+
+  return padEndVisible(prefix + tabs, width);
+}
+
+// ── Separator line ──────────────────────────────────────────────
+
+function renderSeparator(width: number): string {
+  return theme.separator("─".repeat(width));
+}
+
+// ── Status bar ──────────────────────────────────────────────────
+
+function renderStatusBar(
+  state: AppState,
+  totalLines: number,
+  viewportHeight: number,
+  width: number,
+  loading: boolean,
+): string {
+  const hints: string[] = [
+    "q:quit",
+    "Tab:nav",
+    "↑↓:scroll",
+    "r:refresh",
+    "j:json",
+  ];
+
+  if (state.tab === "wallet") {
+    hints.splice(2, 0, "[]:acct");
+  } else if (state.tab === "proposals") {
+    hints.splice(2, 0, "[]:select");
+  }
+
+  const left = " " + hints.join("  ");
+
+  let right: string;
+  if (loading) {
+    right = "loading... ";
+  } else if (totalLines <= viewportHeight) {
+    right = `${totalLines} ln `;
+  } else {
+    const pct = totalLines > 0
+      ? Math.round(((state.scrollOffset + viewportHeight) / totalLines) * 100)
+      : 100;
+    right = `${Math.min(pct, 100)}% (${totalLines} ln) `;
+  }
+
+  const middle = width - visibleLength(left) - visibleLength(right);
+  const pad = middle > 0 ? " ".repeat(middle) : " ";
+
+  return theme.statusBar(left + pad + right);
+}
+
+// ── Full frame compositor ───────────────────────────────────────
+
+export function renderFrame(
+  state: AppState,
+  contentLines: string[],
+  termRows: number,
+  termCols: number,
+  loading: boolean,
+  fixedRight?: string[],
+): string[] {
+  const lines: string[] = [];
+
+  // Line 1: Tab bar
+  lines.push(renderTabBar(state.tab, termCols));
+
+  // Line 2: Separator
+  lines.push(renderSeparator(termCols));
+
+  // Lines 3..N-1: Scrollable viewport
+  const viewportHeight = termRows - 3; // tab bar + separator + status bar
+  const start = state.scrollOffset;
+
+  if (fixedRight && fixedRight.length > 0) {
+    // Two-panel mode: both panels scroll together
+    const rightWidth = Math.max(...fixedRight.map((l) => visibleLength(l)));
+    const leftWidth = termCols - rightWidth - 1;
+
+    for (let i = 0; i < viewportHeight; i++) {
+      const idx = start + i;
+      const leftLine = idx < contentLines.length ? contentLines[idx] : "";
+      const rightLine = idx < fixedRight.length ? fixedRight[idx] : "";
+
+      const left = padEndVisible(truncateAnsi(leftLine, leftWidth), leftWidth);
+      lines.push(left + " " + rightLine);
+    }
+  } else {
+    // Normal mode: everything scrolls together
+    const end = start + viewportHeight;
+    for (let i = start; i < end; i++) {
+      if (i < contentLines.length) {
+        const line = contentLines[i];
+        if (visibleLength(line) > termCols) {
+          lines.push(truncateAnsi(line, termCols));
+        } else {
+          lines.push(line);
+        }
+      } else {
+        lines.push("");
+      }
+    }
+  }
+
+  // Last line: Status bar
+  const totalLineCount = fixedRight ? Math.max(contentLines.length, fixedRight.length) : contentLines.length;
+  lines.push(renderStatusBar(state, totalLineCount, viewportHeight, termCols, loading));
+
+  return lines;
+}