@factory/cli 0.1.2-dev.7 → 0.56.0

package/README.md

@@ -1,278 +1,47 @@
-# Factory CLI - Demo Edit
+# @factory/cli
 
-A hybrid command-line interface that runs **either**:
+> The power of [Factory](https://factory.ai) in your terminal
 
-1. **Interactive TUI** – a full-screen React/Ink terminal app
-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.
-
----
-
-## 1. Overview of the Hybrid Architecture
-
-```
-src/
-├── index.ts          # Hybrid entry – mode detection
-│
-├── app.tsx           # React/Ink TUI (interactive mode)
-│
-└── commands/         # Commander commands (headless mode)
-    ├── droid.ts
-    └── login.ts
-```
-
-• **No positional args** ➜ Interactive TUI  
-• **`headless` subcommand** ➜ Headless mode
-
----
-
-## 2 · Local Development
-
-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`     |
-
-The `start`/`debug` scripts use **tsx** so you can edit TypeScript and restart instantly.
-
----
-
-## 3 · Testing Both Modes Locally
-
-### Interactive TUI
-
-```
-# Launch interactive UI
-npm start
-```
-
-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
-
-```
-# Show global help
-npm start -- --help
-
-# Show headless subcommands
-npm start -- headless --help
-
-# Run login interactively (headless)
-npm start -- headless login
-
-# Send message to a droid
-npm start -- headless droid "Hello, Droid!" --session-id <sessionId>
-```
-
-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/droid.js`. |
-| **Publish** | `npm publish` (bundled in `prepare`) | Users install `droid` binary from npm.         |
-
-During CI the `prepare` script produces the bundle automatically.
-
----
-
-## 5 · Examples
-
-### Headless examples
+## Installation
 
 ```bash
-# Show authentication status
-droid headless status
-
-# Authenticate (opens browser)
-droid headless login
-
-# Talk to Droid
-droid headless droid "Hello" --session-id dOLpXUI8ux6YdZrg3kCs
+npm install -g @factory/cli
 ```
 
-### Interactive example
+Then navigate to your project and start the droid CLI:
 
 ```bash
-# Simply run with no args
+cd /path/to/your/project
 droid
 ```
 
----
-
-## 6 · Testing the Production **`droid`** Command
-
-Sometimes you need to test the **exact binary** users will get from `npm
-install -g factory-cli`.  
-Follow this workflow:
-
-```bash
-# 1. Build optimised bundle (also compiles TS → JS)
-npm run bundle
-
-# 2. Link globally so `droid` is on your PATH
-npm link
-
-# 3. Use it anywhere
-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 `droid headless <args>` |
-
-ℹ️ _Tip:_ The extra `--` after `npm start` or `npm run debug` passes the
-remaining flags **directly to the CLI**.
-
----
-
-## 7 · ESM & Imports
-
-The package is `"type": "module"`; all runtime imports use `.js` extensions even though the source is TypeScript. The build pipeline rewrites them automatically.
-
----
-
-## 8 · Troubleshooting
-
-| 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
-```
+You're now connected to Factory's development agent from your terminal.
 
-**Headless Mode Logs:**
+> **Quick tip:** Press `!` to toggle bash mode and run shell commands directly without AI interpretation. Press `Esc` to return to normal mode.
 
-```bash
-# Logs appear directly in terminal output
-droid headless droid "test message" --session-id abc123
+## What droid brings to your workflow
 
-# Redirect to file if needed
-droid headless droid "test" --session-id abc123 2>&1 | tee my-session.log
-```
+- **End-to-end feature development**: From planning to implementation to testing - droid handles the complete development lifecycle while keeping you in control through transparent review workflows.
+- **Deep codebase understanding**: Leverages your organization's shared knowledge across repositories, documentation, and issue tracking to provide contextually aware assistance that improves over time.
+- **Engineering system integration**: Connects directly to your existing tools — with native integrations to Jira, Notion, Slack, and many more tools — so development work stays synchronized with your team's processes.
+- **Production-ready automation**: Deploy the same workflows locally during development or in CI/CD pipelines, with enterprise security and compliance built-in from day one.
 
-### 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();
-```
+## Why teams choose Factory
 
-### 🛠 How to Add New Tools
+- **Built for enterprise**: On-premise deployment options, SOC-2 compliance, and air-gapped environments.
+- **Your tools, enhanced**: Works within your existing terminal, IDE, and development environment.
+- **Transparent and controllable**: Every decision droid makes is visible and reviewable. You maintain full oversight of code changes with our native diff viewer and approval workflows.
+- **Model flexibility**: Not locked into a single AI provider. Factory allows you to route tasks to the best model for each job while maintaining consistent behavior and memory across your organization.
 
-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`
+## Documentation
 
----
+- [Quickstart Guide](https://docs.factory.ai/cli/getting-started/quickstart)
+- [Common Use Cases](https://docs.factory.ai/cli/getting-started/common-use-cases)
+- [IDE Integration](https://docs.factory.ai/cli/configuration/ide-integrations)
+- [Configuration](https://docs.factory.ai/cli/configuration/settings)
+- [AGENTS.md Guide](https://docs.factory.ai/cli/configuration/agents-md)
+- [CLI Reference](https://docs.factory.ai/reference/cli-reference)
 
-## 11 · Contributing
+## Full Documentation Index
 
-1. `pnpm install` (or `npm install`) at repo root
-2. `cd apps/factory-cli`
-3. Implement feature / fix
-4. Ensure `npm run lint && npm run typecheck && npm test` pass
-5. Commit & open PR 🚀
+Fetch the complete documentation index at: https://docs.factory.ai/llms.txt

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);
+}