@factory/cli 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# Factory CLI - Demo Edit
+
+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
+
+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`.
+
+### 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/factory.js`. |
+| **Publish** | `npm publish` (bundled in `prepare`) | Users install `factory` binary from npm.         |
+
+During CI the `prepare` script produces the bundle automatically.
+
+---
+
+## 5 · Examples
+
+### Headless examples
+
+```bash
+# Show authentication status
+factory headless status
+
+# Authenticate (opens browser)
+factory headless login
+
+# Talk to Droid
+factory headless droid "Hello" --session-id dOLpXUI8ux6YdZrg3kCs
+```
+
+### Interactive example
+
+```bash
+# Simply run with no args
+factory
+```
+
+---
+
+## 6 · Testing the Production **`factory`** 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 `factory` is on your PATH
+npm link
+
+# 3. Use it anywhere
+factory --help
+factory headless status
+factory 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>` |
+
+ℹ️ _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 `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.                                          |
+
+---
+
+## 9 · Contributing
+
+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 🚀