zerg-ztc 0.1.0

package/README.md

@@ -0,0 +1,361 @@
+# ZTC - Zerg Terminal Client
+
+A full-screen terminal-based AI agent interface for interacting with the Zerg continual AI system and managing local development tasks.
+
+```
+◆ Zerg Terminal Client ◆  v0.1.0                    Ctrl+C exit • /help
+────────────────────────────────────────────────────────────────────────
+● System • 14:23
+  Welcome to ZTC - Zerg Terminal Client.
+  Type a message to begin, or /help for commands.
+
+❯ You • 14:24
+  Can you read the package.json and summarize it?
+
+◆ Zerg • 14:24
+  I'll read that file for you.
+  ⚙ read_file (a3f8b2c1) [0.2s]
+    path: package.json
+    → {"name":"ztc","version":"0.1.0"...
+
+  This is ZTC v0.1.0, a Node.js CLI application using Ink for the
+  terminal UI and React 18. It has 5 tools available for file
+  operations, shell commands, and Zerg queries.
+
+❯ _
+
+● Ready                                    ◉ ZTC v0.1.0 • a3f8b2c1
+```
+
+## Features
+
+- **Full-screen terminal UI** - Built with [Ink](https://github.com/vadimdemedes/ink) (React for CLIs)
+- **Agentic tool use** - File I/O, shell commands, directory listing, Zerg integration
+- **Streaming responses** - Real-time output with status indicators
+- **Session management** - Unique session IDs, message history
+- **In-app configuration** - Set API keys and model preferences without restarting
+- **Persistent config** - Settings saved to `~/.ztc/config.json`
+- **Debug mode** - Toggle layout borders for development
+- **Web UI** - Browser-based interface for easier debugging
+
+## Installation
+
+```bash
+# Clone or create the project
+mkdir ztc && cd ztc
+
+# Copy all source files to their respective locations (see Project Structure)
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+```
+
+### Requirements
+
+- Node.js >= 18
+- npm or yarn
+- Anthropic API key (can be configured in-app)
+
+## Usage
+
+### Terminal UI
+
+```bash
+# Development (with hot reload via tsx)
+npm run dev
+
+# Production
+npm run build
+npm start
+
+# Or install globally
+npm link
+ztc
+```
+
+### Web UI (for debugging)
+
+```bash
+npm run web
+# Opens at http://localhost:3000
+```
+
+The web UI provides the same interface in a browser, making it easier to debug layouts and inspect state.
+
+## Configuration
+
+ZTC stores configuration in `~/.ztc/config.json`. You can manage it via commands:
+
+```bash
+/config show              # View current configuration
+/config key sk-ant-...    # Set Anthropic API key
+/config model claude-opus-4-20250514  # Change model
+```
+
+Or set via environment variable:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-your-key-here
+npm run dev
+```
+
+### Config Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `apiKey` | Anthropic API key | `$ANTHROPIC_API_KEY` |
+| `model` | Claude model to use | `claude-sonnet-4-20250514` |
+| `maxTokens` | Max response tokens | `4096` |
+| `zergEndpoint` | Zerg API endpoint | `undefined` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/config <show\|key\|model> [value]` | Manage configuration |
+| `/status` | Show current status |
+| `/clear` | Clear message history |
+| `/debug <on\|off>` | Toggle layout debug borders |
+| `/exit` | Exit ZTC |
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Enter` | Submit message |
+| `Ctrl+C` | Exit |
+| `Ctrl+L` | Clear screen |
+| `↑ / ↓` | Navigate command history |
+| `← / →` | Move cursor |
+| `Ctrl+← / Ctrl+→` | Move by word |
+| `Ctrl+A` | Move to start of line |
+| `Ctrl+E` | Move to end of line |
+| `Ctrl+U` | Clear input line |
+| `Ctrl+W` | Delete word before cursor |
+
+## Available Tools
+
+The agent has access to these tools:
+
+### `read_file`
+Read contents of a file.
+```
+Arguments:
+  path: string (required) - File path to read
+  encoding: string - File encoding (default: utf-8)
+```
+
+### `write_file`
+Write content to a file, creating directories if needed.
+```
+Arguments:
+  path: string (required) - File path to write
+  content: string (required) - Content to write
+  append: "true" | "false" - Append instead of overwrite
+```
+
+### `list_directory`
+List contents of a directory.
+```
+Arguments:
+  path: string (required) - Directory path
+  recursive: "true" | "false" - List recursively (max 3 levels)
+```
+
+### `run_command`
+Execute a shell command.
+```
+Arguments:
+  command: string (required) - Shell command to execute
+  cwd: string - Working directory
+  timeout: string - Timeout in ms (default: 30000)
+```
+
+### `zerg_query`
+Query the Zerg continual AI system.
+```
+Arguments:
+  query: string (required) - Query for Zerg
+  context: string - Additional context
+  project: string - Project identifier
+  wait: "true" | "false" - Wait for completion
+```
+
+## Project Structure
+
+```
+ztc/
+├── package.json              # Dependencies and scripts
+├── tsconfig.json             # TypeScript configuration
+├── README.md
+└── src/
+    ├── cli.tsx               # CLI entry point
+    ├── App.tsx               # Main application component
+    ├── types.ts              # TypeScript type definitions
+    ├── config.ts             # Configuration store (sync file I/O)
+    │
+    ├── components/
+    │   ├── index.ts          # Barrel export
+    │   ├── Header.tsx        # Top header bar
+    │   ├── MessageList.tsx   # Scrolling message area
+    │   ├── InputArea.tsx     # Text input with cursor handling
+    │   └── StatusBar.tsx     # Bottom status bar with spinner
+    │
+    ├── agent/
+    │   ├── index.ts          # Barrel export
+    │   ├── agent.ts          # Agent loop, API calls, event emitter
+    │   └── tools.ts          # Tool definitions and executors
+    │
+    └── web/
+        └── index.html        # Standalone browser UI for debugging
+```
+
+## Architecture
+
+### Terminal Rendering
+
+ZTC uses **Ink** which leverages **Yoga** (the same Flexbox layout engine used by React Native) to render React components to the terminal. This provides:
+
+- Familiar React component model
+- Flexbox-based layouts
+- Hooks for input handling
+- Efficient differential updates
+
+### Agent Loop
+
+```
+User Input → Agent.run() → API Call → Tool Use? → Execute Tools → Continue
+                ↑                         │              │
+                └─────────────────────────┴──────────────┘
+```
+
+The agent implements a standard ReAct-style loop:
+1. Send conversation to Claude API
+2. If response contains tool calls, execute them
+3. Append results and continue until no more tools
+4. Return final response to UI
+
+### Event System
+
+The agent emits events for UI updates:
+- `thinking_start` / `thinking_end`
+- `tool_start` / `tool_end` / `tool_error`
+- `stream_start` / `stream_delta` / `stream_end`
+- `error`
+
+### Avoiding Flicker
+
+Terminal UIs can flicker during re-renders. ZTC prevents this by:
+1. Loading config **synchronously** at startup
+2. Capturing terminal dimensions **once** at module load
+3. Avoiding hooks that cause re-renders (`useStdout`)
+4. Using `useMemo` for computed values
+
+## Development
+
+### Adding a New Tool
+
+1. Define the tool in `src/agent/tools.ts`:
+
+```typescript
+export const myTool: Tool = {
+  definition: {
+    name: 'my_tool',
+    description: 'Does something useful',
+    parameters: {
+      type: 'object',
+      properties: {
+        arg1: { type: 'string', description: 'First argument' }
+      },
+      required: ['arg1']
+    }
+  },
+  execute: async (args) => {
+    // Implementation
+    return JSON.stringify({ result: 'done' });
+  }
+};
+```
+
+2. Add to `defaultTools` array in the same file.
+
+### Adding a New Command
+
+Add to the `commands` array in `src/App.tsx`:
+
+```typescript
+{
+  name: 'mycommand',
+  description: 'Does something',
+  usage: '<arg>',
+  handler: (args, ctx) => {
+    ctx.addMessage({
+      role: 'system',
+      content: `You said: ${args.join(' ')}`
+    });
+  }
+}
+```
+
+### Building
+
+```bash
+npm run build    # Compile TypeScript to dist/
+npm run clean    # Remove dist/
+```
+
+## Roadmap
+
+- [ ] **Streaming responses** - Token-by-token output
+- [ ] **Session persistence** - Save/load conversation history
+- [ ] **Multi-line input** - Support for longer prompts
+- [ ] **Zerg integration** - Connect to actual Zerg backend
+- [ ] **Git tools** - Commit, diff, branch operations
+- [ ] **Search tools** - Web search, codebase search
+- [ ] **Shared state module** - Extract core logic for terminal + web UIs
+- [ ] **Plugin system** - Dynamic tool loading
+
+## Troubleshooting
+
+### "No API key configured"
+
+Set your key with:
+```
+/config key sk-ant-your-key-here
+```
+
+Or via environment:
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### "Authentication failed"
+
+Your API key may be invalid or expired. Update it with `/config key <new-key>`.
+
+### Flickering display
+
+This shouldn't happen with current code. If it does:
+1. Ensure you're using the latest source
+2. Check terminal compatibility (works best with modern terminals)
+3. Try the web UI for debugging: `npm run web`
+
+### TypeScript errors
+
+```bash
+npm run build
+```
+
+If you see type errors, ensure all files match the artifacts exactly.
+
+## License
+
+MIT
+
+---
+
+Built for the Zerg continual AI system.

package/dist/App.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+export declare const App: React.FC;
+export default App;
+//# sourceMappingURL=App.d.ts.map

package/dist/App.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../src/App.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAiD,MAAM,OAAO,CAAC;AA0DtE,eAAO,MAAM,GAAG,EAAE,KAAK,CAAC,EAmgBvB,CAAC;AAEF,eAAe,GAAG,CAAC"}