@factory/cli 0.1.0 → 0.1.2-dev.7

package/README.md

@@ -3,7 +3,7 @@
 A hybrid command-line interface that runs **either**:
 
 1. **Interactive TUI** – a full-screen React/Ink terminal app
-2. **Headless commands** – traditional `factory headless <command>` sub-commands powered by Commander
+2. **Headless commands** – traditional `droid headless <command>` sub-commands powered by Commander
 
 The entry-point (`src/index.ts`) detects how it was invoked and chooses the right mode automatically.
 
@@ -55,7 +55,15 @@ The `start`/`debug` scripts use **tsx** so you can edit TypeScript and restart i
 npm start
 ```
 
-You’ll see a colourful Ink interface; quit with `Ctrl-C`.
+You'll see a colourful Ink interface; quit with `Ctrl-C`.
+
+### Running in VSCode
+
+Factory CLI can also be run inside VSCode using the Factory extension:
+
+1. First, install the Factory VSCode extension (see [VSCode Extension README](../factory-vscode-extension/README.md) for installation instructions)
+2. Click the **Run Factory** button (🤖) in the editor toolbar to launch Factory CLI in a dedicated terminal
+3. The extension provides full VSCode context (open files, selections, diagnostics) to Factory via MCP
 
 ### Headless Commands
 
@@ -79,12 +87,12 @@ The extra `--` after `npm start` passes subsequent flags to the CLI.
 
 ## 4 · Development vs Production
 
-| 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/factory.js`. |
-| **Publish** | `npm publish` (bundled in `prepare`) | Users install `factory` binary from npm.         |
+| 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.         |
 
 During CI the `prepare` script produces the bundle automatically.
 
@@ -96,25 +104,25 @@ During CI the `prepare` script produces the bundle automatically.
 
 ```bash
 # Show authentication status
-factory headless status
+droid headless status
 
 # Authenticate (opens browser)
-factory headless login
+droid headless login
 
 # Talk to Droid
-factory headless droid "Hello" --session-id dOLpXUI8ux6YdZrg3kCs
+droid headless droid "Hello" --session-id dOLpXUI8ux6YdZrg3kCs
 ```
 
 ### Interactive example
 
 ```bash
 # Simply run with no args
-factory
+droid
 ```
 
 ---
 
-## 6 · Testing the Production **`factory`** Command
+## 6 · Testing the Production **`droid`** Command
 
 Sometimes you need to test the **exact binary** users will get from `npm
 install -g factory-cli`.  
@@ -124,23 +132,23 @@ Follow this workflow:
 # 1. Build optimised bundle (also compiles TS → JS)
 npm run bundle
 
-# 2. Link globally so `factory` is on your PATH
+# 2. Link globally so `droid` is on your PATH
 npm link
 
 # 3. Use it anywhere
-factory --help
-factory headless status
-factory headless droid "Hello" --session-id <sessionId>
+droid --help
+droid headless status
+droid headless droid "Hello" --session-id <sessionId>
 
 # 4. (Optional) Un-link when finished
 npm unlink -g factory-cli
 ```
 
-| Situation                   | Command to use                                              |
-| --------------------------- | ----------------------------------------------------------- |
-| Fast iteration / TypeScript | `npm start -- <args>`                                       |
-| Debug with inspector        | `npm run debug -- <args>`                                   |
-| Validate production bundle  | `npm run bundle && npm link` then `factory headless <args>` |
+| Situation                   | Command to use                                            |
+| --------------------------- | --------------------------------------------------------- |
+| Fast iteration / TypeScript | `npm start -- <args>`                                     |
+| Debug with inspector        | `npm run debug -- <args>`                                 |
+| Validate production bundle  | `npm run bundle && npm link` then `droid headless <args>` |
 
 ℹ️ _Tip:_ The extra `--` after `npm start` or `npm run debug` passes the
 remaining flags **directly to the CLI**.
@@ -155,15 +163,113 @@ The package is `"type": "module"`; all runtime imports use `.js` extensions even
 
 ## 8 · Troubleshooting
 
-| Problem                                 | Fix                                                                                                          |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `EACCES` when running `factory`         | Ensure the bundle is executable (`chmod +x bundle/factory.js`). `npm run bundle` handles this automatically. |
-| `module not found` after rename         | Run `npm run clean && npm run bundle` to rebuild from scratch.                                               |
-| Global command still points to old code | Run `npm unlink -g factory-cli && npm link` to refresh the symlink.                                          |
+| Problem                                 | Fix                                                                                                        |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `EACCES` when running `droid`           | Ensure the bundle is executable (`chmod +x bundle/droid.js`). `npm run bundle` handles this automatically. |
+| `module not found` after rename         | Run `npm run clean && npm run bundle` to rebuild from scratch.                                             |
+| Global command still points to old code | Run `npm unlink -g factory-cli && npm link` to refresh the symlink.                                        |
+
+---
+
+## 9 · Logging
+
+Factory CLI has two different logging behaviors depending on the execution mode:
+
+### Interactive Mode Logging
+
+When running in **interactive TUI mode** (`droid` with no arguments), all logging output is redirected to files to avoid interfering with the clean React/Ink interface:
+
+- **Log Directory**: `~/.factory/logs/`
+- **Log Files**: `droid-log-<timestamp>.log` (e.g., `droid-log-2025-01-15T10-30-45-123Z.log`)
+- **Content**: All `logInfo`, `logException`, and `logWarn` calls are written to the timestamped log file
+- **Format**: `[timestamp] LEVEL: message | Context: {...}`
+
+**Example log file location:**
+
+```bash
+~/.factory/logs/droid-log-2025-01-15T10-30-45-123Z.log
+```
+
+**Example log entry:**
+
+```
+[2025-01-15T10:30:45.123Z] INFO: User started interactive session
+[2025-01-15T10:30:47.456Z] ERROR: Failed to initialize MCP client: Connection refused | Context: {"retry": 1}
+```
+
+### Headless Mode Logging
+
+When running **headless commands** (`droid headless <command>`), logging follows standard console output patterns:
+
+- **Log Output**: Directly to stdout/stderr using the standard `@factory/logging` package
+- **Integration**: Works with existing telemetry, Sentry, and monitoring systems
+- **Format**: Standard Factory logging format with metadata support
+
+### Accessing Logs
+
+**Interactive Mode Logs:**
+
+```bash
+# View the most recent log file
+ls -la ~/.factory/logs/
+
+# Tail the logs in real-time (find the most recent file)
+tail -f ~/.factory/logs/droid-log-*.log
+
+# View logs from a specific session
+cat ~/.factory/logs/droid-log-2025-01-15T10-30-45-123Z.log
+```
+
+**Headless Mode Logs:**
+
+```bash
+# Logs appear directly in terminal output
+droid headless droid "test message" --session-id abc123
+
+# Redirect to file if needed
+droid headless droid "test" --session-id abc123 2>&1 | tee my-session.log
+```
+
+### Log Cleanup
+
+Interactive mode creates a new log file for each session. To manage disk space:
+
+```bash
+# Remove logs older than 7 days
+find ~/.factory/logs -name "droid-log-*.log" -mtime +7 -delete
+
+# View total log directory size
+du -sh ~/.factory/logs
+```
+
+---
+
+## 10 · Tool Registry & Executors Design
+
+### 🔄 What Changed
+
+**After:** Dynamic mapping automatically discovers tools from TUI registry
+
+```javascript
+// Tools are automatically discovered from TUI registry
+const toolMapping = buildToolMapping();
+```
+
+### 🛠 How to Add New Tools
+
+1. **Create executor** in `src/tools/executors/client/` (implement `ClientToolExecutor`)
+2. **Register in TUI registry** in `src/tools/tui.ts`:
+   ```javascript
+   getTUIToolRegistry().register({
+     tool: myNewCliTool, // from @factory/droid-core/tools/definitions
+     executorFactory: () => new MyNewExecutor(),
+   });
+   ```
+3. **That's it!** Tool is automatically available in `executeTool()` using its `llmId`
 
 ---
 
-## 9 · Contributing
+## 11 · Contributing
 
 1. `pnpm install` (or `npm install`) at repo root
 2. `cd apps/factory-cli`