@factory/cli 0.1.2-dev.5 → 0.55.2

package/README.md

@@ -31,19 +31,57 @@ src/
 
 All dev tasks are exposed as **npm scripts** – never run compiled `.js` files directly.
 
-| Purpose                   | Command             |
-| ------------------------- | ------------------- |
-| Start CLI (auto mode)     | `npm start`         |
-| Start with Node inspector | `npm run debug`     |
-| Lint source               | `npm run lint`      |
-| Type-check                | `npm run typecheck` |
-| Run tests                 | `npm test`          |
-| Build JS into `dist/`     | `npm run build`     |
-| Produce executable bundle | `npm run bundle`    |
-| Clean build artifacts     | `npm run clean`     |
+| Purpose                          | Command               |
+| -------------------------------- | --------------------- |
+| Start CLI (auto mode)            | `npm start`           |
+| Start with Node inspector        | `npm run debug`       |
+| Set up shell alias for local dev | `npm run setup:alias` |
+| Build SEA for current platform   | `npm run build`       |
+| Build and run the binary         | `npm run build:run`   |
+| Lint source                      | `npm run lint`        |
+| Type-check                       | `npm run typecheck`   |
+| Run tests                        | `npm test`            |
+| Produce executable bundle        | `npm run bundle`      |
+| Clean build artifacts            | `npm run clean`       |
 
 The `start`/`debug` scripts use **tsx** so you can edit TypeScript and restart instantly.
 
+### Shell Alias Setup
+
+For easier local development, you can set up a `droid` alias that runs the CLI from your current directory:
+
+```bash
+# Add alias to ~/.zshrc (checks if already exists)
+npm run setup:alias
+
+# Start a new terminal or source the file
+source ~/.zshrc
+
+# Now you can run 'droid' from anywhere
+droid
+```
+
+### Building Standalone Executables (SEA)
+
+The CLI can be compiled into Single Executable Applications (SEA) for different platforms:
+
+```bash
+# Build for your current platform automatically
+npm run build
+
+# Build and immediately run the binary
+npm run build:run
+
+# Build for specific platforms
+npm run build:sea:mac:arm64      # macOS Apple Silicon
+npm run build:sea:mac:x64        # macOS Intel
+npm run build:sea:linux:arm64    # Linux ARM64
+npm run build:sea:linux:x64      # Linux x64
+npm run build:sea:windows:x64    # Windows x64
+```
+
+The `build` script automatically detects your OS and architecture, then builds the appropriate binary to `dist/{platform}/{arch}/droid` (or `droid.exe` on Windows).
+
 ---
 
 ## 3 · Testing Both Modes Locally
@@ -90,7 +128,6 @@ The extra `--` after `npm start` passes subsequent flags to the CLI.
 | Phase       | Command(s)                           | Result                                         |
 | ----------- | ------------------------------------ | ---------------------------------------------- |
 | **Dev**     | `npm start` / `npm run debug`        | Runs from TS sources with tsx, fast reload.    |
-| **Build**   | `npm run build`                      | Compiles TS → `dist/`.                         |
 | **Bundle**  | `npm run bundle` (calls `build`)     | Generates single executable `bundle/droid.js`. |
 | **Publish** | `npm publish` (bundled in `prepare`) | Users install `droid` binary from npm.         |
 
@@ -110,9 +147,59 @@ droid headless status
 droid headless login
 
 # Talk to Droid
-droid headless droid "Hello" --session-id dOLpXUI8ux6YdZrg3kCs
+droid headless "Hello" --session-id dOLpXUI8ux6YdZrg3kCs
+
+# Streaming input mode
+# Send multiple messages over stdin, maintaining conversation state
+echo '{"role":"user","content":"hello"}' | droid exec --input-format stream-json --output-format stream-json
 ```
 
+### Streaming Input Mode (Droid Manager Integration)
+
+The CLI supports a **streaming input mode** designed for Droid Manager integration, allowing a single process to handle multiple user messages while maintaining conversation state.
+
+**Usage Pattern:**
+
+```javascript
+// Spawn process once
+const droid = spawn('droid', [
+  'exec',
+  '--input-format',
+  'stream-json',
+  '--output-format',
+  'stream-json',
+  '--auto',
+  'low',
+]);
+
+// Send messages over time (JSONL format via stdin)
+droid.stdin.write('{"role":"user","content":"hello"}\n');
+
+// Read events from stdout (JSONL format)
+droid.stdout.on('data', (chunk) => {
+  const events = chunk.toString().split('\n').filter(Boolean);
+  events.forEach((line) => {
+    const event = JSON.parse(line);
+    // Handle: user messages, assistant responses, tool calls, etc.
+  });
+});
+
+// Send another message later
+droid.stdin.write('{"role":"user","content":"what can you do?"}\n');
+
+// Close stdin when done to trigger graceful shutdown
+droid.stdin.end();
+```
+
+**Key Points:**
+
+- **Input**: JSONL (newline-delimited JSON) via stdin, each line is `Anthropic.MessageParam` with `role: "user"`
+- **Output**: JSONL events via stdout (same format as `--output-format stream-json`)
+- **stdin stays open** until explicitly closed by the caller
+- **Messages processed sequentially** - one at a time
+- **Session persists** across all messages in the process lifetime
+- **Graceful shutdown** when stdin closes
+
 ### Interactive example
 
 ```bash
@@ -138,7 +225,7 @@ npm link
 # 3. Use it anywhere
 droid --help
 droid headless status
-droid headless droid "Hello" --session-id <sessionId>
+droid headless "Hello" --session-id <sessionId>
 
 # 4. (Optional) Un-link when finished
 npm unlink -g factory-cli
@@ -224,10 +311,10 @@ cat ~/.factory/logs/droid-log-2025-01-15T10-30-45-123Z.log
 
 ```bash
 # Logs appear directly in terminal output
-droid headless droid "test message" --session-id abc123
+droid headless "test message" --session-id abc123
 
 # Redirect to file if needed
-droid headless droid "test" --session-id abc123 2>&1 | tee my-session.log
+droid headless "test" --session-id abc123 2>&1 | tee my-session.log
 ```
 
 ### Log Cleanup
@@ -269,10 +356,137 @@ const toolMapping = buildToolMapping();
 
 ---
 
-## 11 · Contributing
+## 11 · E2E Testing of the TUI
+
+The Factory CLI includes end-to-end tests for the terminal UI using Microsoft's `@microsoft/tui-test`.
+
+### Testing Framework
+
+- Framework: `@microsoft/tui-test`
+- Shell: bash
+- Config: `apps/cli/tui-test.config.ts`
+
+### Prerequisites
+
+The E2E tests require a valid `FACTORY_API_KEY` environment variable to authenticate with Factory services. You can generate an API key from [https://dev.app.factory.ai/settings/api-keys](https://dev.app.factory.ai/settings/api-keys).
+
+```bash
+export FACTORY_API_KEY="your-api-key-here"
+npm run test:e2e
+```
+
+The tests launch the CLI via a wrapper script that configures the environment:
+
+- program: `./e2e-tests/test-workspace/run-droid.sh`
+- The wrapper exports all required env vars (e.g., `FACTORY_HOME_OVERRIDE`) and ensures correct execution context for tests.
+- rows/columns: 30x80
+
+### Test Layout
+
+```
+apps/cli/
+├── e2e-tests/
+│   ├── chat-input.test.ts        # Text entry, deletion, Ctrl+C, file suggestions, cursor nav
+│   ├── settings.template.json    # Copied to each test's .factory-dev
+│   ├── templates/                # Blueprint copied to each test workspace
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── src/
+│   └── test-workspace/           # Contains wrapper scripts only
+│       ├── run-droid.sh          # Creates unique workspace per invocation
+│       ├── run-droid.ps1         # Windows version
+│       └── run-droid.cmd         # Windows CMD wrapper
+└── tui-test.config.ts            # TUI test config using the wrapper
+```
+
+### Running Tests
+
+```bash
+# From apps/cli
+npm run test:e2e                 # bundles CLI then runs all e2e tests
+
+# Run a specific test file (or append :line)
+npm run test:e2e e2e-tests/chat-input.test.ts
+
+# Tests automatically create isolated workspaces - no setup needed!
+# Each test invocation gets its own /tmp/droid-test-* directory
+```
+
+### Debugging
+
+At any point of time, you can access the serialized terminal view using:
+
+```typescript
+const terminalView = terminal.serialize().view;
+```
+
+Tracing is enabled in config (`trace: true`). Traces are saved under `tui-traces/`.
+
+```bash
+# Replay a trace
+npm run show-trace tui-traces/<trace-file>
+# Or directly
+npx @microsoft/tui-test show-trace tui-traces/<trace-file>
+```
+
+### Test Environment Isolation
+
+Each test case runs in **complete isolation** with its own workspace and `.factory-dev` directory:
+
+- **Per-test workspaces**: The wrapper scripts (`run-droid.sh`, `run-droid.ps1`) automatically create a unique temporary workspace for each test invocation
+- **Unique identifiers**: Workspaces are named with PID and timestamp: `/tmp/droid-test-{pid}-{timestamp}-XXXXXX`
+- **Template copying**: Files from `e2e-tests/templates/` (package.json, tsconfig.json, src/) are copied to each test workspace
+- **Automatic cleanup**: Temporary workspaces are cleaned up when tests complete (via trap on Unix, try/finally on Windows)
+- **Parallel execution**: Tests can run in parallel without state interference since each has its own `.factory-dev`
+
+Settings template (copied to each test's `.factory-dev/settings.json`):
+
+```json
+{
+  "model": "claude-sonnet-4-20250514",
+  "cloudSessionSync": false,
+  "diffMode": "github"
+}
+```
+
+### What’s Covered
+
+Current suite validates:
+
+- Text entry visibility
+- Backspace/Delete behavior (including forward delete)
+- Ctrl+C warning and double Ctrl+C exit
+- File suggestions via @: show, filter, navigate, select, dismiss
+- Cursor navigation and in-line editing
+
+### Writing New Tests
+
+Global config already provides the program and env. You can optionally tweak terminal size per test file:
+
+```ts
+import { test, expect } from '@microsoft/tui-test';
+
+test.use({ rows: 24, columns: 100 });
+
+test('example', async ({ terminal }) => {
+  await expect(
+    terminal.getByText('standing in an open terminal', {
+      full: false,
+      strict: false,
+    })
+  ).toBeVisible({ timeout: 10000 });
+  terminal.write('Hello');
+  await expect(terminal.getByText('Hello')).toBeVisible();
+});
+```
+
+---
+
+## 12 · Contributing
 
 1. `pnpm install` (or `npm install`) at repo root
-2. `cd apps/factory-cli`
+2. `cd apps/cli`
 3. Implement feature / fix
 4. Ensure `npm run lint && npm run typecheck && npm test` pass
-5. Commit & open PR 🚀
+5. Run E2E tests with `npm run test:e2e`
+6. Commit & open PR 🚀

package/bin/droid

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * JavaScript shim for the droid command.
+ *
+ * This shim finds and executes the appropriate platform-specific binary.
+ * For x64 platforms, it detects AVX2 support and selects the appropriate
+ * binary (regular or baseline for older CPUs).
+ *
+ * In optimized installations, this file is replaced with a hard link to
+ * the actual binary, avoiding Node.js startup overhead.
+ *
+ * Based on esbuild's approach: https://github.com/evanw/esbuild/pull/1621
+ */
+
+const fs = require('fs');
+const path = require('path');
+const child_process = require('child_process');
+
+const {
+  PLATFORM_PACKAGES,
+  getPlatformKey,
+  getBinaryName,
+  getBinaryPathWithInfo,
+  resolveBinaryPath,
+} = require('../platform.js');
+
+function runBinary(binaryPath, args) {
+  const result = child_process.spawnSync(binaryPath, args, {
+    stdio: 'inherit',
+    windowsHide: true,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return result;
+}
+
+function getBinaryPath() {
+  const platformKey = getPlatformKey();
+  const packages = PLATFORM_PACKAGES[platformKey];
+
+  if (!packages) {
+    console.error(`Error: Unsupported platform: ${platformKey}`);
+    console.error(
+      `Supported platforms: ${Object.keys(PLATFORM_PACKAGES).join(', ')}`
+    );
+    process.exit(1);
+  }
+
+  // Try to get binary from optionalDependencies
+  const result = getBinaryPathWithInfo();
+  if (result) {
+    return result;
+  }
+
+  // Fallback: check if binary exists alongside this script (for development)
+  const localBinary = path.join(
+    __dirname,
+    '..',
+    'dist',
+    process.platform,
+    process.arch,
+    getBinaryName()
+  );
+  if (fs.existsSync(localBinary)) {
+    return {
+      path: localBinary,
+      pkg: 'local',
+      hasBaseline: !!packages.baseline,
+    };
+  }
+
+  console.error(
+    `Error: Could not find the droid binary for ${platformKey}.\n\n` +
+      `This usually means the optional dependency "${packages.regular}" was not installed.\n` +
+      `Try running: npm install\n\n` +
+      `If you're using npm with --ignore-scripts, the binary may not have been set up correctly.`
+  );
+  process.exit(1);
+}
+
+// Get the binary path and execute
+const { path: binPath, pkg, hasBaseline } = getBinaryPath();
+const args = process.argv.slice(2);
+
+try {
+  const result = runBinary(binPath, args);
+
+  // Check for illegal instruction error (CPU doesn't support AVX2)
+  // This can happen on Windows where we couldn't detect AVX2 upfront
+  if (result.signal === 'SIGILL' && hasBaseline && !pkg.includes('baseline')) {
+    console.error(
+      `\nNote: Your CPU doesn't support AVX2 instructions. Trying baseline build...`
+    );
+    // Try baseline
+    const baselinePath = resolveBinaryPath(
+      PLATFORM_PACKAGES[getPlatformKey()].baseline
+    );
+    if (baselinePath) {
+      const baselineResult = runBinary(baselinePath, args);
+      process.exit(baselineResult.status ?? 0);
+    }
+  }
+
+  process.exit(result.status ?? 0);
+} catch (e) {
+  console.error(`Error executing droid: ${e.message}`);
+  process.exit(1);
+}