arc402-cli 0.7.3 → 0.7.4

package/TUI-SPEC.md

@@ -0,0 +1,214 @@
+# ARC-402 TUI Specification — Ink-based Terminal UI
+
+**Date:** 2026-03-22
+**Status:** Ready for implementation
+**Pattern:** Fixed header/footer with scrollable viewport (split-pane TUI)
+**Library:** Ink (React for CLIs) — same architecture as Claude Code
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  HEADER (fixed, 8-10 rows)                      │
+│  ┌─────────────────────────────────────────────┐ │
+│  │ ██████╗ ██████╗  ██████╗    ...            │ │
+│  │ agent-to-agent arcing · v0.7.3             │ │
+│  │ ◈ ──────────────────────────────────────── │ │
+│  │ Network  Base Mainnet   Wallet  0xA34B..   │ │
+│  └─────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────┤
+│  VIEWPORT (scrollable, fills remaining space)    │
+│                                                  │
+│  ◈ arc402 > wallet status                        │
+│   ├ Address  0xA34B...a5dc                       │
+│   ├ ETH      0.002 ETH                           │
+│   └ Trust    100 Restricted                      │
+│                                                  │
+│  ◈ arc402 > shake send --to 0xa9e0...            │
+│   ◈ Submitting handshake...                      │
+│   ✓ Handshake sent — tx 0xabc1...                │
+│                                                  │
+│  ◈ arc402 > doctor                               │
+│   ├ Config     ✓                                 │
+│   ├ RPC        ✓ Base Mainnet                    │
+│   └ Daemon     ✗ Not running                     │
+│                                                  │
+├─────────────────────────────────────────────────┤
+│  FOOTER (fixed, 1-2 rows)                        │
+│  ◈ arc402 > _                                    │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Component Tree (Ink/React)
+
+```tsx
+<App>
+  <Box flexDirection="column" height="100%">
+    
+    {/* HEADER — fixed height, never scrolls */}
+    <Header
+      version={version}
+      network={config.network}
+      wallet={config.walletContractAddress}
+      balance={balance}
+    />
+    
+    <Box borderStyle="single" borderTop borderBottom={false} borderLeft={false} borderRight={false}>
+      <Text dimColor>─</Text>
+    </Box>
+    
+    {/* VIEWPORT — flexGrow, scrollable */}
+    <Viewport
+      lines={outputBuffer}
+      scrollOffset={scrollOffset}
+    />
+    
+    {/* FOOTER — fixed height, input pinned */}
+    <Footer>
+      <InputLine
+        value={inputValue}
+        onChange={setInputValue}
+        onSubmit={handleCommand}
+        history={history}
+      />
+    </Footer>
+    
+  </Box>
+</App>
+```
+
+---
+
+## Components
+
+### `<Header />`
+- Renders the ASCII art banner (cyan)
+- Version from package.json
+- Network, wallet (truncated), balance
+- Fixed height: exactly `bannerLines.length + 3` rows
+- Never re-renders unless config changes
+
+### `<Viewport />`
+- `flexGrow: 1` — fills all remaining terminal rows
+- Maintains an internal `outputBuffer: string[]`
+- Renders a window slice: `buffer.slice(scrollOffset, scrollOffset + viewportHeight)`
+- Scroll up/down with Page Up/Page Down or mouse wheel
+- Auto-scrolls to bottom when new output arrives (unless user scrolled up)
+- Supports ANSI colors in output lines (chalk passes through)
+
+### `<Footer />`
+- Fixed height: 1 row (or 2 with status bar)
+- Contains `<InputLine />`
+- Prompt: `◈ arc402 > ` (◈ cyan, arc402 dim, > white)
+
+### `<InputLine />`
+- Uses `ink-text-input` for text input with cursor
+- Up/down arrow: command history navigation
+- Tab: command completion
+- Enter: dispatch command
+- Ctrl+C: graceful exit
+
+---
+
+## Behavior
+
+### Command Dispatch
+1. User types command + Enter
+2. Command + output appended to `outputBuffer` as: `◈ arc402 > {command}` then output lines
+3. Commander parses and executes (stdout/stderr captured and routed to viewport)
+4. Viewport auto-scrolls to bottom
+5. Input line clears, cursor returns
+
+### Stdout/Stderr Capture
+- During command execution, monkey-patch `process.stdout.write` and `process.stderr.write`
+- Route all output to `outputBuffer` instead of raw terminal
+- Restore after command completes
+- This ensures spinners, tree output, console.log all render in the viewport
+
+### Scroll Behavior
+- **Auto-scroll:** viewport stays at bottom as new lines arrive
+- **Manual scroll:** Page Up / Page Down moves viewport
+- **Scroll indicator:** if not at bottom, show `↓ more` in bottom-right
+- **Return to bottom:** any new command output snaps back to bottom
+
+### Chat Integration
+- Non-command input detected → POST to OpenClaw gateway
+- Response streamed line-by-line into viewport
+- Prefixed with `◈ ` in dim
+
+### Resize Handling
+- Listen for `SIGWINCH`
+- Recalculate viewport height
+- Re-render (Ink handles this natively)
+
+---
+
+## Dependencies
+
+```json
+{
+  "ink": "^4.0.0",
+  "ink-text-input": "^5.0.0",
+  "react": "^18.0.0"
+}
+```
+
+~150KB total. Well-maintained. Same stack as Claude Code.
+
+---
+
+## File Structure
+
+```
+cli/src/
+  tui/
+    App.tsx          — root component
+    Header.tsx       — banner + status
+    Viewport.tsx     — scrollable output area
+    Footer.tsx       — input line wrapper
+    InputLine.tsx    — text input with history + completion
+    useCommand.ts    — hook: dispatch to commander, capture output
+    useChat.ts       — hook: OpenClaw gateway chat
+    useScroll.ts     — hook: scroll state management
+    index.tsx        — render <App /> with Ink
+  repl.ts            — KEEP as fallback for --print mode and non-TTY
+  index.ts           — route: TTY → tui/, non-TTY/--print → repl.ts
+```
+
+---
+
+## Migration Plan
+
+1. Keep existing `repl.ts` as fallback (--print mode, piped input)
+2. New `tui/` directory with Ink components
+3. `index.ts` checks: if TTY and no --print → launch Ink TUI, else → use simple REPL
+4. All existing commands unchanged — only the rendering layer changes
+5. `repl.ts` simplified back to basic readline (no ANSI tricks)
+
+---
+
+## Exit Behavior
+
+- Ctrl+C → `\x1b[?1049l` (leave alternate screen) → show goodbye → exit
+- All terminal state restored on exit (cursor visible, normal scroll, etc.)
+- Alternate screen means the TUI disappears on exit, revealing the original terminal — clean
+
+---
+
+## What This Does NOT Change
+
+- Command implementations (wallet.ts, agent.ts, etc.) — untouched
+- Config system — untouched
+- Daemon — untouched
+- SDKs — untouched
+- One-shot mode (`arc402 wallet deploy` without REPL) — untouched
+
+Only the interactive shell rendering layer changes.
+
+---
+
+*Build this exactly as specified. The spec is the contract.*

package/dist/index.js

@@ -1,5 +1,38 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const program_1 = require("./program");
 const repl_1 = require("./repl");
@@ -27,6 +60,18 @@ function checkUpgrade() {
     }
 }
 const printMode = process.argv.includes("--print");
+// Detect if a subcommand was provided (any arg after the binary that doesn't start with -)
+const knownSubcommands = (() => {
+    try {
+        const prog = (0, program_1.createProgram)();
+        return new Set(prog.commands.map((cmd) => cmd.name()));
+    }
+    catch {
+        return new Set();
+    }
+})();
+const argv = process.argv.slice(2).filter((a) => a !== "--print");
+const hasSubcommand = argv.some((a) => !a.startsWith("-") && knownSubcommands.has(a));
 if (printMode) {
     // --print mode: skip REPL entirely, suppress ANSI/spinners, run command, exit.
     // Used by OpenClaw agents running arc402 commands via ACP.
@@ -41,8 +86,17 @@ if (printMode) {
         process.exit(1);
     });
 }
+else if (process.stdout.isTTY && !hasSubcommand && process.argv.length <= 2) {
+    // TTY with no subcommand — launch Ink TUI
+    checkUpgrade();
+    void Promise.resolve().then(() => __importStar(require("./tui/index"))).then(({ launchTUI }) => launchTUI()).catch((e) => {
+        console.error("TUI failed to start:", e instanceof Error ? e.message : String(e));
+        // Fallback to REPL
+        void (0, repl_1.startREPL)();
+    });
+}
 else if (process.argv.length <= 2) {
-    // No subcommand — enter interactive REPL
+    // No subcommand, not TTY — enter basic REPL fallback
     checkUpgrade();
     void (0, repl_1.startREPL)();
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,uCAA0C;AAC1C,iCAAmC;AACnC,qCAAgE;AAEhE,+EAA+E;AAC/E,8DAA8D;AAC9D,MAAM,cAAc,GAAY,OAAO,CAAC,iBAAiB,CAAyB,CAAC,OAAO,CAAC;AAE3F,SAAS,YAAY;IACnB,IAAI,CAAC,IAAA,qBAAY,GAAE;QAAE,OAAO;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAA,mBAAU,GAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,cAAc,CAAC;QACnC,IAAI,IAAI,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;YACpC,mDAAmD;YACnD,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,MAAM,cAAc,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,MAAM,CAAC,cAAc,KAAK,cAAc,EAAE,CAAC;YAC7C,+DAA+D;YAC/D,IAAA,mBAAU,EAAC,EAAE,GAAG,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;AACH,CAAC;AAED,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAEnD,IAAI,SAAS,EAAE,CAAC;IACd,+EAA+E;IAC/E,2DAA2D;IAC3D,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAC3D,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC;IAC9B,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,GAAG,CAAC;IAClC,YAAY,EAAE,CAAC;IACf,MAAM,OAAO,GAAG,IAAA,uBAAa,GAAE,CAAC;IAChC,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;QACrF,OAAO,CAAC,KAAK,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IACpC,yCAAyC;IACzC,YAAY,EAAE,CAAC;IACf,KAAK,IAAA,gBAAS,GAAE,CAAC;AACnB,CAAC;KAAM,CAAC;IACN,4DAA4D;IAC5D,YAAY,EAAE,CAAC;IACf,MAAM,OAAO,GAAG,IAAA,uBAAa,GAAE,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/repl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../src/repl.ts"],"names":[],"mappings":"AAuwBA,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAe/C"}
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../src/repl.ts"],"names":[],"mappings":"AAiFA,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAgG/C"}