@lovrozagar/grunt 0.3.8 → 0.3.10

package/README.md

@@ -1,68 +1,329 @@
-# GRUNT
+# Grunt
 
-Building Grunt - a multi agent orchestrator workflow
+Multi-agent orchestrator SoT — deep-merge rulesync trees product scripts and generate pipeline into a consumer repo
 
-# Install
+OSS drop-in; merges existing configs; switches default provider flow to Grunt.
 
-Node.js 22+.
+- [Install](#install)
+- [Usage](#usage)
+- [CLI](#cli)
+- [Init](#init)
+- [Version bump](#version-bump)
+- [Agents](#agents)
+- [Skills](#skills)
+- [Generate](#generate)
+- [Config](#config)
+- [Architecture](#architecture)
+- [Layout](#layout)
+- [Develop](#develop)
+- [Examples](#examples)
+- [License](#license)
+
+## Install
+
+- Node.js 22+
+- Consumer:
 
 ```
 npm i -D @lovrozagar/grunt
 npx @lovrozagar/grunt
 ```
 
-Same as `npx @lovrozagar/grunt init`. Merge SoT, `npm install`, `rulesync:generate`, `sync:globals:apply`, `rulesync:check`. Do not `npm test` as a consumer.
+- Same as `npx @lovrozagar/grunt init` when no command
+- Do not `npm test` as a consumer
+- Package: `@lovrozagar/grunt` `0.3.9` MIT · https://github.com/lovrozagar/grunt
+
+## Usage
+
+- TTY no command → menu (init default; generate check sync-globals purge-mcps doctor help quit)
+- Piped / CI / `--yes` / `-y` / `--non-interactive` no command → still `init`
+- Bin: `grunt` → `./bin/grunt.js` (`type: module`)
+
+## CLI
+
+### Commands
+
+- `init` → `init()` — merge SoT, `npm install`, `rulesync:generate`, `sync:globals:apply`, `rulesync:check`
+- `generate` → `npm run rulesync:generate`
+- `check` → `npm run rulesync:check`
+- `sync-globals` → `npm run sync:globals` (dry-run); `--apply` → `sync:globals:apply`
+- `purge-mcps` → `npm run purge:global-mcps` (dry-run); `--apply` → `purge:global-mcps:apply`
+- `doctor` → `npm run rulesync:doctor`
+- `help`
+- `version`
+
+### Flags
+
+- `--skip-globals` — skip `sync:globals:apply` on init
+- `--yes` / `-y` / `--non-interactive` — no TTY menu; default command still `init`. Not `--apply`
+- `--apply` — write for `sync-globals` / `purge-mcps`
+- `--host <id>` — `sync-globals --host <id>`
 
-`--skip-globals` skips `sync:globals:apply`. Re-init auto-skips globals when `<!-- grunt:begin -->` is in AGENTS.md/CLAUDE.md or `scripts/telemetry.mjs` exists. First init (no sentinel, no telemetry) still applies globals unless flagged.
+## Init
 
-Contributors to this repo only: local `npm i && npm test`.
+- Merge SoT `npm install` `rulesync:generate` `sync:globals:apply` `rulesync:check`
+- `--skip-globals` skips apply
+- Re-init auto-skips globals when `<!-- grunt:begin -->` in `AGENTS.md`/`CLAUDE.md` **or** `scripts/telemetry.mjs` exists
+- First init (no sentinel no telemetry) applies globals unless flagged
+- Owned trees/scripts refresh; extra `.rulesync` files kept; patches to grunt-owned files lost
 
-# Version bump
+## Version bump
 
 ```
 npm i -D @lovrozagar/grunt@latest && npx @lovrozagar/grunt init
 ```
 
-Owned trees/scripts refresh. Extra `.rulesync` files kept. Patches to grunt-owned files lost. Globals: first init applies; re-init auto-skips (or pass `--skip-globals`).
-
-# GOAL
-
-- synced configs across all 4/5 major cli providers (grok build, claude code, codex, gemini cli, antigravity)! Emit matrix: grok/claude/codex/antigravity (`rulesync generate`) then `emit-mcp-policy` + `emit-gemini` (`GEMINI.md`, `.gemini/agents/{id}/agent.md`; MCP `.gemini/settings.json`) + `emit-agent-shell-tools` (Claude grunt body `Bash`; other hosts `run_terminal_command`). No `-t geminicli`.
-- max situational speed relative to task intensity
-- max free token savings:
-    maximally superterse without loosing value - sacrifice grammar for sake of concision
-    compression - RTK AI
-    subagent re-prompt scrub - script
-    cache
-    context engineering
-- max reasoning and effort where needed and minimal reasoning and effort where not needed
-- agents:
-    - orchestrator (low model, low effort) -> always spawn+prompt; never user-facing tokens except `[orchestrator]:` (or child role tag) echo. `/parent` one-turn only; `/handoff` writes `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md` and hands the session to a fresh one.
-- subagents:
-    - grunt (low model, low effort) -> tools. facts/search/exec/git/web/test/low-reason mechanical write. never feature solution. never spawn.
-    - implementer (medium model, medium effort) -> write already-defined solution. does not plan or invent design. never spawn.
-    - thinker (high model, high effort) -> plan/deep reason. flags edge cases/pitfalls. read-only. never spawn. no bash.
-
-# Examples
-
-1. User - "Create me a react weather app"
-    Orchestrator spawns and prompts thinker
-    Thinker outputs plan to Orchestrator
-    Orchestrator spawns and prompts implementer
-    Implementer writes to disk, implements the app & outputs to orchestrator
-    Orchestrator outputs to user
-
-2. User - "What is 2+2"
-    Orchestrator spawns and prompts Grunt
-    Grunt outputs 4
-    Orchestrator echoes `[grunt]:` to user
-
-3. User - "What is the next movie Marvel cinematic universe will release to theaters"
-    Orchestrator spawns and prompts Grunt
-    Grunt runs a web search & outputs to orchestrator
-    Orchestrator outputs to user
-
-4. User - "In .logs folder find the log or logs on 3/6/2021 with tag 'framework bug'"
-    Orchestrator spawns and prompts Grunt
-    Grunt searches local folder & outputs to orchestrator
-    Orchestrator outputs to user
+- Same re-init / globals rules as Init
+
+## Agents
+
+SoT: `.rulesync/subagents/{orchestrator grunt implementer thinker}.md`
+
+Emit: `.claude/` `.grok/` `.agents/` `.gemini/`
+
+- **orchestrator** (parent) — always spawn+prompt; user-facing only `[orchestrator]:` (or child role tag) one-line echo. `/parent` one-turn; `/handoff` writes `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`. Small/low router. First token spawn. No parent Read/Bash/Grep. Does not implement, plan, or fetch world facts
+- **grunt** — tools: facts/search/exec/git/web/test/low-reason mechanical write. Isolation `verdict:`. Never feature solution. Never spawn. World fact: `job: web`
+- **implementer** — write already-defined solution on allowlisted paths. TDD when spec/plan says tests. Validate + sim after write. Fat dumps via `need:`. Never spawn. Never plan. Id is **implementer** (not Implementor)
+- **thinker** — plan/deep reason; edge cases. Read-only named-file Read of prompt SSOT; trees/search/exec/web/test → `need:`. Never spawn. No bash. Never implement
+
+Children never spawn. Spawn only grunt|implementer|thinker. Omit model on spawn; frontmatter on agent files picks haiku/sonnet/opus vs grok-4.5 / grok-4.6 / other hosts. Voice: `.rulesync/reference/output.md`. Protocol: `.rulesync/reference/cascade.md`. `AGENTS.md`/`CLAUDE.md` spawn-first. `GEMINI.md` → `@AGENTS.md`. Goals: synced configs across grok build claude code codex gemini cli antigravity; max situational speed; superterse token savings; max/min reasoning by role.
+
+## Skills
+
+Present under `.claude` / `.rulesync` / `.agents`:
+
+- `cascade` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `parent` `solo`
+- Grok-only: `write-plan` `implement-plan` (`/write-plan` plan-only → `next: /implement-plan`)
+
+## Generate
+
+Pipeline (no `-t geminicli`):
+
+1. `rulesync generate` — emit grok / claude / codex / antigravity
+2. `emit-mcp-policy.mjs`
+3. `emit-gemini.mjs` — `GEMINI.md` `.gemini/agents/{id}/agent.md` MCP `.gemini/settings.json`
+4. `emit-agent-shell-tools` — Claude grunt body `Bash`; other hosts `run_terminal_command` (hooks-union)
+
+`check` / `doctor` = rulesync check / doctor.
+
+Emit writes other-CLI trees from `.rulesync` for the **next** process of that CLI. Not a live hop into another host.
+
+## Config
+
+- SoT merge into consumer repo; existing configs kept where not grunt-owned
+- Globals: first init apply; re-init auto-skip (sentinel / telemetry) or `--skip-globals`
+- `sync-globals` / `purge-mcps`: dry-run default; `--apply` writes
+- Hosts: grok claude codex gemini antigravity
+
+## Architecture
+
+Protocol picture: one CLI host process, parent-only orchestrator in that session, three sibling spawn types (`grunt` | `implementer` | `thinker`), local workspace tools with RTK on Bash stdout only, one vendor Model API outside the host bubble. Not a product walkthrough. `@lovrozagar/grunt` = protocol SoT + CLI (init/generate/check); not a model runtime. Do not paste `.rulesync/reference/cascade.md` here — boxes and edges only.
+
+### Containment
+
+Draw **one** CLI host bubble. That bubble is **this** session’s CLI: Grok Build, Claude Code, Codex, Gemini CLI, or Antigravity. The CLI **is** the host — not a peer router beside another CLI. Parent lives **inside** that host session. Children spawn **inside the same process**. Other CLIs = emit/config on disk only; no runtime hop; no shared spawn/peek line.
+
+User-visible conversation attaches only to the parent. Children never talk to the user. Children never spawn.
+
+### Nested diagram
+
+Same topology as the session recap; every legal edge labeled.
+
+```
+ USER
+  │
+  │  session in/out  (parent only; tagged one-line recap)
+  │  TUI local; completion tokens from Model API (mixed)
+  ▼
+┌──────────────────────── CLI HOST (this process) ────────────────────────┐
+│  TUI · hooks · emit/generate · RTK PreToolUse · fs workspace            │
+│                                                                         │
+│  Parent orchestrator  (only spawner; spawn-first; no parent Read/Bash)  │
+│    legal spawn types: grunt | implementer | thinker                     │
+│    omit model on spawn; FM on agent files picks haiku/sonnet/opus       │
+│    vs grok-4.5 / grok-4.6 / etc.                                        │
+│                                                                         │
+│         spawn / peek / resume_from                                      │
+│                    │                                                    │
+│                    ▼                                                    │
+│         siblings (never spawn; no child→child)                          │
+│    ┌───────────┬───────────────┬──────────────┐                         │
+│    │   grunt   │  implementer  │   thinker    │                         │
+│    │ facts/    │ specified     │ plan/deep    │                         │
+│    │ tools     │ writes + TDD  │ reason       │                         │
+│    │ Bash+fs   │ Write/Bash/   │ Read / need: │                         │
+│    │ web/test  │ fs            │ no Bash      │                         │
+│    └─────┬─────┴───────┬───────┴───────┬──────┘                         │
+│          │             │               │                                │
+│          └──────── tool call ──────────┘                                │
+│                        │                                                │
+│                        ▼                                                │
+│          host tools (same process)                                      │
+│            fs: Read / Grep / Glob / Write                               │
+│            Bash / run_terminal_command                                  │
+│                 │                                                       │
+│                 └──RTK (PreToolUse; Bash/shell stdout only)──► compress │
+│                                                                         │
+│          local (not Model API):                                         │
+│            spawn_subagent / Agent · peek                                │
+│            workspace tools · RTK                                        │
+│            scrub-spawn-prompt · parse-need · grunt-job                  │
+│            emit / generate                                              │
+│                                                                         │
+│          WebSearch / web_fetch = remote-not-LLM (not a second model)    │
+│          MCP = denied in-tree; do not draw as a main path               │
+│                                                                         │
+│          parent + children  ──completion─────────────────────────────┐  │
+└──────────────────────────────────────────────────────────────────────┼──┘
+                                                                       │
+                                                                       ▼
+                                                         Model API
+                                                         (this host’s SDK
+                                                         only; one box)
+                                                                       ..
+                                                         emit/config
+                                                         (no runtime line)
+                                                                       ..
+                                                         other CLIs
+                                                         Gemini spawn/peek
+                                                         = GAP
+                                                         (no fake peeks)
+```
+
+### `need:` / `resume_from`
+
+Implementer or thinker that still needs a fat dump **stops** on a `need:` JSON line. Parent fans those jobs as **parallel grunt** siblings, then one `resume_from` with **new** `verdict:` blobs only. Max **3** `resume_from` per child id. Thinker has no Bash; facts go through this loop. Grunt does not emit `need:` for its own tool use.
+
+```
+ implementer | thinker
+      │
+      │  stop on JSON only (≤4 jobs/batch)
+      ▼
+ need: [{"job":"search|exec|web|test","query":"..."}]
+      │
+      │  parent parse-need  (or SubagentStop intercept
+      │  when every job is search|exec)
+      ▼
+ parallel grunt spawns  (same host; not a new CLI)
+      │
+      │  isolation
+      ▼
+ verdict: ok|fail|empty
+      │
+      │  one resume_from:<child id>  + new verdicts only
+      │  do not re-send original task; max 3
+      ▼
+ same child continues  (transcript already on resume_from)
+```
+
+### Node table
+
+| node | inside host? | local vs AI-server | notes |
+| --- | --- | --- | --- |
+| User | no | mixed | Speaks only to parent session. Never a child edge. |
+| Session in/out / TUI | yes | mixed | TUI is local; recap tokens come from the model. Legal `[role]:` one-line echo only. |
+| CLI host process | yes (is the box) | local process | Grok Build / Claude Code / Codex / Gemini / Antigravity. Not a peer of another CLI. |
+| Parent orchestrator | yes | AI-server **turn** | Spawn-first low router. No parent Read/Bash/Grep. Lives in this session, not a sidecar. |
+| `grunt` sibling | yes | AI-server **turn** | Facts/tools/mechanical write. Never spawn. Never feature solution. |
+| `implementer` sibling | yes | AI-server **turn** | Specified writes + TDD when tests are in the spec. Agent id is **implementer**. Never spawn. |
+| `thinker` sibling | yes | AI-server **turn** | Plan/deep reason. Read-only. Named-file Read of prompt SSOT; investigate → `need:`. No Bash. Never spawn. |
+| Host spawn / peek / `resume_from` | yes | **local** | `spawn_subagent` / `Agent` and host peek tools. Gemini spawn/peek = GAP; block on return, classify `done`; no fake peeks. |
+| Workspace fs tools | yes | **local** | Read/Grep/Glob/Write (and host aliases). Parent is denied these except documented persist paths / `/solo`. |
+| Bash / `run_terminal_command` | yes | **local** | RTK wraps stdout on PreToolUse. Thinker has no Bash. |
+| RTK | yes | **local** | Bash/shell stdout compression only. Not Read/Grep/Glob/prompts/images. |
+| `scrub-spawn-prompt` / `parse-need` / `grunt-job` | yes | **local** | Hooks and scripts. Isolation `verdict:` is grunt output, not a model hop. |
+| emit / generate / init | yes (this repo / install) | **local** | Writes other-CLI configs. Not a runtime line to those CLIs. |
+| WebSearch / web_fetch | tool from host | **remote-not-LLM** | Network search/fetch. Not a second Model API box. World facts: grunt `job: web`. |
+| MCP | policy deny | n/a | Denied by policy in-tree. Do not draw as a main path. |
+| Model API | **no** (one box outside) | AI-server | This host’s vendor SDK only. Parent and child **turns** complete here. Spawn omits model; frontmatter on `.rulesync/subagents/*.md` picks the model. |
+| Other CLIs | no (not this process) | emit/config only | Same protocol files emitted elsewhere. No hop, no shared peek. |
+| `@lovrozagar/grunt` | package / CLI | local install | Protocol SoT + CLI. Not a model runtime. |
+
+### Edge labels
+
+Use these labels. Do not revive “prompt input” or “agent to use”.
+
+| edge | meaning |
+| --- | --- |
+| **session in/out** | User ↔ parent only. Children have no user edge. |
+| **spawn** | Parent → `grunt` \| `implementer` \| `thinker`. First sentence: `You are {agent} subagent.` Omit model. |
+| **peek** | Parent reads host status on the child id. Real host fields. `timeout_ms=60000`. GAP hosts: no fake peeks; block on spawn return = `done`. |
+| **resume_from** | Parent continues the **same** child id with new `verdict:` blobs only. Max 3. Not a fresh spawn. |
+| **need:** | Child stop line: fat dump jobs for parent to fan as grunt. Cap 4 jobs per batch. |
+| **verdict:** | Grunt isolation result back onto `resume_from`. `ok\|fail\|empty`. Short facts, not dumps. |
+| **tool call** | Child (or, illegally if parent, denied) → host tools. |
+| **RTK** | PreToolUse Bash/shell → compressed stdout. No other tools. |
+| **completion** | Parent and children → **one** Model API (this host’s SDK). |
+| **emit/config** | Disk write to other CLI trees. Drawn with a broken line or footnote, **not** a session arrow. |
+
+### What not to draw
+
+- A **CLI Provider** box as a peer of the host, or a router that hops between CLIs at runtime
+- **Thinker ↔ CLI** as a special extra channel — thinker is a sibling; tools/`need:` like the protocol
+- The spelling **Implementor** — id is **implementer**
+- **Per-agent Model API** boxes — one Model API outside the host, this SDK only
+- **Child → child spawn** — isolation is parent fan-out of grunt siblings (or in-hook grunt-job for interceptable `search|exec` batches)
+- **MCP** as a happy-path tool rail
+- **RTK** on Read/Grep/Glob/prompts/images
+- **User** arrows into grunt/implementer/thinker
+- Gemini **fake peek** loops. GAP: no invented status API; block on return
+
+### Emit footnote and Gemini GAP
+
+**Emit.** `rulesync generate` plus in-tree emit scripts write Claude/Codex/Antigravity/Gemini/Grok trees from `.rulesync`. Config on disk for the **next** process of that CLI. Not a live message into another host. Multi-CLI in a diagram = footnote or a second, disconnected host bubble — never an arrow from this session.
+
+**Gemini GAP.** Gemini is not emitted as a spawn/peek host in the cascade table. Do not invent peek or kill APIs. If a Gemini session is the host, treat spawn/peek as GAP: no fake peeks, no auto-kill; block on the host call returning and classify `done`. Other GAP rows (cascade host mapping): Claude Code unless an in-tree schema names a status/output tool; Codex peek/kill; Antigravity peek/kill.
+
+### Protocol pointers
+
+Repo-relative (repository root):
+
+- `.rulesync/reference/cascade.md` — parent-only spawn, peek/kill table, `need:` / `resume_from`, isolation `verdict:`
+- `.rulesync/reference/rtk.md` — Bash/shell stdout compression
+- `.rulesync/reference/map.md` — cheap outline of protocol, scripts, generated trees
+- `.rulesync/subagents/orchestrator.md`
+- `.rulesync/subagents/grunt.md`
+- `.rulesync/subagents/implementer.md`
+- `.rulesync/subagents/thinker.md`
+
+## Layout
+
+Published (`package.json` `files`): `bin/grunt.js` `cli` `scripts/check-globals.mjs` `scripts/emit-agent-shell-tools.mjs` `scripts/emit-gemini.mjs` `scripts/emit-mcp-policy.mjs` `scripts/gate-fat-tools.mjs` `scripts/hooks-union.mjs` `scripts/grunt-job.mjs` `scripts/parse-need.mjs` `scripts/persist-handoff.mjs` `scripts/persist-plan.mjs` `scripts/purge-global-mcps.mjs` `scripts/scrub-spawn-prompt.mjs` `scripts/scrub-text-lib.mjs` `scripts/sync-global-settings.mjs` `scripts/telemetry.mjs` `scripts/scrub-text` `.rulesync` `.grok` `.codex` `.claude` `.agents` `AGENTS.md` `CLAUDE.md` `.mcp.json` `README.md` `LICENSE`
+
+No `scripts/*.test.ts` `scripts/fixtures/` `docs/` `coverage/` `vitest.config.ts` in `files`.
+
+Repo root (also): `coverage/` `.gemini/` — no `src/` no `CONTRIBUTING` no `docs/`
+
+- `bin/grunt.js` — CLI bin
+- `cli/grunt.mjs` — commands
+- `scripts/` — generate emits `telemetry.mjs` (re-init sentinel) `scrub-text`
+- `.rulesync/` — SoT (subagents skills reference)
+- `.claude/` `.grok/` `.codex/` `.agents/` `.gemini/` — host emit
+- `coverage/` — vitest local not published
+
+## Develop
+
+Contributors to this repo only:
+
+```
+npm i && npm test
+```
+
+- Test: `vitest run --coverage`
+- Test include: `scripts/**/*.test.ts` `cli/**/*.test.ts`
+- Coverage include: `cli/**`
+- Coverage thresholds: 100% lines / functions / branches / statements
+- Dev deps include rulesync vitest typescript
+
+## Examples
+
+Keep these four flows only:
+
+1. “Create me a react weather app” → thinker plan → implementer write → orchestrator recap
+2. “What is 2+2” → grunt → `[grunt]:` echo
+3. Marvel theatrical next → grunt `job:web` → recap
+4. `.logs` 3/6/2021 tag `framework bug` → grunt local search → recap
+
+## License
+
+MIT © 2026 lovrozagar

package/bin/grunt.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
 import { start } from "../cli/grunt.mjs"
 
-start()
+start().catch(() => {
+  process.exit(1)
+})

package/cli/grunt.mjs

@@ -2,38 +2,134 @@ import { execFileSync } from "node:child_process"
 import { readFileSync } from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
-import { init } from "./init.mjs"
+import { destAlreadyInited, init, shouldAutoSkipGlobals } from "./init.mjs"
+import { confirm, isInteractive, select, spinner } from "./prompt.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 
 const USAGE = `Usage: grunt [command]
 
-Default (no command): init — full setup
+Default (no command): TTY menu; else init — full setup
 
 Commands:
-  init       Full setup: merge SoT, npm install, rulesync:generate, sync:globals:apply, rulesync:check
-  generate   npm run rulesync:generate
-  check      npm run rulesync:check
-  help       Show this help
-  version    Print package version
+  init          Full setup: merge SoT, npm install, rulesync:generate, sync:globals:apply, rulesync:check
+  generate      npm run rulesync:generate
+  check         npm run rulesync:check
+  sync-globals  npm run sync:globals (dry-run; --apply to write)
+  purge-mcps    npm run purge:global-mcps (dry-run; --apply to write)
+  doctor        npm run rulesync:doctor
+  help          Show this help
+  version       Print package version
 
 Flags:
-  --skip-globals  Skip sync:globals:apply (auto-skipped when already initialized)
+  --skip-globals     Skip sync:globals:apply (auto-skipped when already initialized)
+  --yes, -y          Non-interactive (not --apply)
+  --non-interactive  Same as --yes
+  --apply            Write for sync-globals / purge-mcps
+  --host <id>        sync-globals host
 `
 
+const MENU_OPTIONS = [
+  { value: "init", label: "init" },
+  { value: "generate", label: "generate" },
+  { value: "check", label: "check" },
+  { value: "sync-globals", label: "sync-globals" },
+  { value: "purge-mcps", label: "purge-mcps" },
+  { value: "doctor", label: "doctor" },
+  { value: "help", label: "help" },
+  { value: "quit", label: "quit" },
+]
+
+const YES_FLAGS = new Set(["--yes", "-y", "--non-interactive"])
+
 function pkgVersion() {
   const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"))
   return pkg.version
 }
 
-function npmRun(script) {
-  execFileSync("npm", ["run", script], { cwd: process.cwd(), stdio: "inherit" })
+function npmRun(script, extra = []) {
+  const args = extra.length ? ["run", script, "--", ...extra] : ["run", script]
+  execFileSync("npm", args, { cwd: process.cwd(), stdio: "inherit" })
+}
+
+function hostValueOk(v) {
+  return v != null && v !== "" && !String(v).startsWith("-")
 }
 
-export function start() {
-  const args = process.argv.slice(2)
-  const skipGlobals = args.includes("--skip-globals")
-  const [cmd] = args.filter((a) => a !== "--skip-globals")
+export function parseArgv(argv) {
+  let skipGlobals = false
+  let apply = false
+  let host
+  let hostError = false
+  const positionals = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "--skip-globals") {
+      skipGlobals = true
+      continue
+    }
+    if (YES_FLAGS.has(a)) continue
+    if (a === "--apply") {
+      apply = true
+      continue
+    }
+    if (a === "--host") {
+      const v = argv[i + 1]
+      if (!hostValueOk(v)) {
+        hostError = true
+        continue
+      }
+      host = v
+      i += 1
+      continue
+    }
+    if (typeof a === "string" && a.startsWith("--host=")) {
+      host = a.slice("--host=".length)
+      if (!hostValueOk(host)) hostError = true
+      continue
+    }
+    positionals.push(a)
+  }
+  return { cmd: positionals[0], skipGlobals, apply, host, hostError }
+}
+
+function hostExtra(host) {
+  return host ? ["--host", host] : []
+}
+
+function bindSpinner() {
+  const spin = spinner()
+  return (name, action) => {
+    if (action === "start") spin.start(name)
+    else if (action === "stop") spin.stop()
+  }
+}
+
+async function runInit(cwd, { skipGlobals, interactive }) {
+  if (!interactive) {
+    init(cwd, { skipGlobals })
+    return
+  }
+  if (destAlreadyInited(cwd)) {
+    const again = await confirm({
+      message: "Re-init?",
+      initialValue: true,
+    })
+    if (!again) return
+  }
+  const autoSkip = skipGlobals || shouldAutoSkipGlobals(cwd)
+  const applyGlobals = await confirm({
+    message: "Apply globals?",
+    initialValue: !autoSkip,
+  })
+  init(cwd, {
+    skipGlobals: !applyGlobals,
+    applyGlobals,
+    onPhase: bindSpinner(),
+  })
+}
+
+async function dispatch(cmd, flags, interactive) {
   if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     process.stdout.write(USAGE)
     return
@@ -43,7 +139,10 @@ export function start() {
     return
   }
   if (!cmd || cmd === "init") {
-    init(process.cwd(), { skipGlobals })
+    await runInit(process.cwd(), {
+      skipGlobals: flags.skipGlobals,
+      interactive: interactive && (!cmd || cmd === "init"),
+    })
     return
   }
   if (cmd === "generate") {
@@ -54,6 +153,40 @@ export function start() {
     npmRun("rulesync:check")
     return
   }
+  if (cmd === "sync-globals") {
+    const script = flags.apply ? "sync:globals:apply" : "sync:globals"
+    npmRun(script, hostExtra(flags.host))
+    return
+  }
+  if (cmd === "purge-mcps") {
+    npmRun(flags.apply ? "purge:global-mcps:apply" : "purge:global-mcps")
+    return
+  }
+  if (cmd === "doctor") {
+    npmRun("rulesync:doctor")
+    return
+  }
   process.stdout.write(USAGE)
   process.exitCode = 1
 }
+
+export async function start() {
+  const flags = parseArgv(process.argv.slice(2))
+  if (flags.hostError) {
+    process.stdout.write(USAGE)
+    process.exitCode = 1
+    return
+  }
+  const interactive = isInteractive()
+  let cmd = flags.cmd
+  if (!cmd && interactive) {
+    const choice = await select({
+      message: "Command",
+      options: MENU_OPTIONS,
+      initialValue: "init",
+    })
+    if (choice === "quit") return
+    cmd = choice
+  }
+  await dispatch(cmd, flags, interactive)
+}