rush-ai 0.6.0 → 0.9.0

package/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md — for AI agents using rush-ai
+
+If you are an AI agent (Cursor, Claude Code, or another IDE-resident assistant) and you landed in this package, read this file first.
+
+## What rush-ai is for
+
+`rush-ai` is how a local agent hands off work to the Rush platform — without asking the user to re-state anything. Two situations you'll use it in:
+
+1. **Hand-off** — the conversation you're in produces work that belongs on Rush (a live website, a task for a specialist). Relay the context you already have. → read [`skills/hand-off.md`](./skills/hand-off.md).
+2. **Sub-agent in your workflow** — you're composing a multi-step plan and a step needs a specialist from Rush's agent shelf. → read [`skills/agent-shelf.md`](./skills/agent-shelf.md).
+
+## Getting usage on demand
+
+From inside any shell (the one you already have a Bash tool for), these three commands give you everything you need:
+
+```bash
+npx rush-ai skill                   # prints the index — start here
+npx rush-ai skill hand-off          # full hand-off playbook
+npx rush-ai skill agent-shelf       # full agent-shelf playbook
+npx rush-ai agent list              # see the live list of available agents
+```
+
+Every command also supports `--help` with a "When to use" section and example flows.
+
+## Defaults that save you a round-trip
+
+- Recommended invocation: **`npx rush-ai`** (always latest, zero install).
+- Default agent: **`rush`** — `-a` defaults to `rush` when omitted. Pass `-a web-builder` for site-building tasks.
+- Always pass **`--json`** when the result will be parsed.
+- Iterate with **`task send <id>`**, not a new `task create`.
+
+## What NOT to do
+
+- Don't ask the user to summarize requirements they already told you — relay them.
+- Don't invent agent names; always confirm via `agent list`.
+- Don't run `npx rush-ai auth login` for the user (it's interactive / opens a browser). Ask them to.
+- Don't silently retry a failed task. Surface the error and ask what to do.

package/README.md

@@ -2,7 +2,9 @@
 
 # rush-ai
 
-**Call Rush agents from your terminal — relay the context, not the prompt.**
+**一条命令，装一次，Claude Code / Codex / Cursor 三家都能用。**
+
+_Install once. Run anywhere. Hand off your context, not your prompt._
 
 [![npm version](https://img.shields.io/npm/v/rush-ai.svg)](https://www.npmjs.com/package/rush-ai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -13,6 +15,24 @@
 
 ## Why rush-ai
 
+### One command, three agents — `rush-ai plugin install`
+
+`rush-ai plugin install <name>` is a **CLI equivalent** of each IDE's built-in
+`/plugin install`. It writes plugin files (commands / skills / rules / hooks /
+MCP servers) straight to each agent's on-disk layout:
+
+- **Claude Code** — native plugin at `~/.claude/plugins/cache/<mkt>/<name>/<ver>/`,
+  registered in `installed_plugins.json` + `settings.json.enabledPlugins`.
+  Claude Code's own `/plugin list` sees it, `/plugin uninstall` can remove it.
+- **Codex** — native plugin at `~/.codex/plugins/cache/<mkt>/<name>/<ver>/` with
+  `.codex-plugin/plugin.json` + external `.mcp.json`, registered in
+  `~/.codex/config.toml`.
+- **Cursor** — attached via the conventional layout (`~/.cursor/skills/` +
+  bridge `.mdc` rules in `~/.cursor/rules/` + `~/.cursor/mcp.json`).
+
+Because we write the files each IDE already reads, no daemons, no background
+watchers — once written, plugins load the same way as if the IDE installed them.
+
 ### Hand off your context, not your prompt
 
 You're already deep in a conversation with your local agent — Cursor, Claude Code, or your own. It knows the codebase, the constraints, what you've already tried. When part of that work belongs on the Rush platform (building a site, asking a specialist agent), you don't want to summarize everything again.
@@ -52,16 +72,28 @@ npx rush-ai task status lodig8oknq0r
 ## Quick Start
 
 ```bash
-npx rush-ai auth login
-npx rush-ai agent list
-npx rush-ai task create -a rush -p "Add a contact form to the homepage"
-npx rush-ai task watch <task-id>
+# 1. Install the CLI
+npm install -g rush-ai
+
+# 2. Install Rush plugin to every agent you have
+rush-ai marketplace add github:kanyun-inc/rush-marketplace
+rush-ai plugin install rush
+
+# 3. Use Rush as a task executor
+rush-ai auth login
+rush-ai agent list
+rush-ai task create -a rush -p "Add a contact form to the homepage"
+rush-ai task watch <task-id>
 ```
 
 `rush` is the default general-purpose agent. Swap `-a` for any agent from `agent list` to call a specialist instead.
 
 ## Features
 
+- **Plugin installer** — `rush-ai plugin install <name>` writes plugin files to
+  Claude Code, Codex, and Cursor in one shot; auto-detects which IDEs you have
+- **Marketplace management** — Register `directory:` or `github:` marketplaces,
+  cache under `~/.rush/marketplaces/`, resolve plugin references
 - **Task lifecycle** — Create, watch (SSE streaming), send follow-ups, cancel, and download artifacts
 - **Agent shelf** — Browse agents, inspect skills and MCP servers, plug any agent into your own workflow as a sub-agent
 - **MCP integration** — Discover MCP servers, list tools, run as an MCP stdio server
@@ -83,6 +115,27 @@ npm install -g rush-ai
 
 ## Commands
 
+### Plugin distribution
+
+The `marketplace` and `plugin` command groups are the CLI equivalent of each
+IDE's built-in `/plugin` command — they write the exact same on-disk layout,
+so the IDE's own `/plugin list` / `/plugin uninstall` still work.
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `marketplace add <source>` | - | Register a marketplace (`github:owner/repo`, `directory:/abs/path`); `--as <name>` to override auto-derived name |
+| `marketplace remove <name>` | - | Remove a marketplace from the local cache |
+| `marketplace list` | `marketplace ls` | List cached marketplaces and their plugins |
+| `marketplace update [<name>]` | - | Pull latest for `github:` sources (`directory:` is a no-op) |
+| `plugin install <ref>` | - | Install to Claude Code + Codex + Cursor (filter with `--target`); `--force`, `--dry-run` |
+| `plugin uninstall <ref>` | `plugin remove` | Symmetric cleanup across the same targets |
+| `plugin list` | `plugin ls` | List installed plugins; `--available` lists plugins in cached marketplaces |
+| `plugin update [<name>]` | - | Bump installed plugins to the latest marketplace version |
+
+`<ref>` form: `<name>` or `<name>@<marketplace>` (e.g. `rush@rush-marketplace`).
+
+### Everything else
+
 | Command | Alias | Description |
 |---------|-------|-------------|
 | `auth login` | - | Log in via browser (PKCE) or API key |
@@ -99,6 +152,10 @@ npm install -g rush-ai
 | `task list` | `task ls` | List tasks |
 | `task watch <id>` | - | Stream task execution in real-time (SSE) |
 | `task cancel <id>` | - | Cancel a running task |
+| `task push` | - | Push a local project to the Rush platform (previously `task deploy` with no id) |
+| `task deploy <id>` | - | Deploy a built web-builder task (default `--env production`; `--env test` allowed for non-Next.js templates); `--version`, `--domain`, `--yes` |
+| `task versions <id>` | - | List buildable versions for a web-builder task (shows ✓ for versions already deployed to test / production) |
+| `task domain check <prefix>` | - | Validate a custom domain prefix and check availability (`--task <id>` required) |
 | `mcp serve` | - | Start MCP stdio server |
 | `mcp list` | `mcp ls` | List available MCP servers |
 | `mcp list-tools <id>` | - | List tools provided by an MCP server |
@@ -168,6 +225,105 @@ rush-ai task messages <task-id> --json
 rush-ai task list -l 10 -s completed
 ```
 
+### Deploying a web-builder task
+
+Once a `web-builder` task has built at least one version (you've sent it a
+message and it produced a commit), the CLI can take that version from the
+preview URL to a real production deploy — mirroring the Web UI's **Deploy**
+button, entirely in the terminal.
+
+```bash
+# 1. See which versions are buildable and which are already deployed
+rush-ai task versions <task-id>
+#   # Version Commit   Created              Test  Production
+#   1 1       abc12345 2026-05-01 14:20      ✓
+#   2 2       def67890 2026-05-03 11:05            ✓
+
+# 2. (Optional) Check a custom domain prefix for availability before deploying
+#    This does NOT reserve the prefix — a TOCTOU-safe reservation only happens
+#    inside `task deploy`.
+rush-ai task domain check my-app --task <task-id>
+# Success! Prefix available: https://my-app.<suffix>
+
+# 3. Deploy — picks the latest buildable version by default
+rush-ai task deploy <task-id> --domain my-app --yes
+# Success! Deployed!
+#   URL:     https://my-app.rush.zhenguanyu.com
+#   Version: abc12345
+#   Env:     production
+#   Domain:  my-app
+
+# 4. Pin a specific commit instead of `--version latest`
+rush-ai task deploy <task-id> --version def67890 --domain my-app --yes
+
+# 5. Non-prod environment (non-Next.js templates only — Next.js is prod-only)
+rush-ai task deploy <task-id> --env test --yes
+
+# 6. CI / scripted use
+RUSH_API_KEY=$KEY rush-ai task deploy <task-id> --domain my-app --ci
+```
+
+Notes:
+- `task deploy <id>` only works for tasks whose agent is `web-builder` and
+  whose template is non-empty; everything else errors out early (before any
+  publish side effect).
+- The Next.js template (`nextjs-fullstack`) deploys to a pod and streams
+  progress via SSE; the static template deploys to OSS and writes a
+  best-effort DB record afterward.
+- Domain prefixes must match `^[a-z0-9][a-z0-9-]{0,28}[a-z0-9]$|^[a-z0-9]$`
+  — the CLI validates the prefix locally before hitting the API.
+
+#### Migrating from `task deploy` (≤ 0.8.x)
+
+In 0.8.x and earlier, `rush-ai task deploy` with **no id** was "push the
+current directory to Rush and create a new task." That behaviour is now
+`rush-ai task push`. The `task deploy` name has been reassigned to the new
+production-deploy flow described above (it requires a task id).
+
+| Old CLI (≤ 0.8.x) | New CLI (0.9+) |
+|---|---|
+| `rush-ai task deploy -n my-app` | `rush-ai task push -n my-app` |
+| `rush-ai task deploy -p ./site` | `rush-ai task push -p ./site` |
+| _(not supported)_ | `rush-ai task deploy <id> --domain my-app` |
+
+The legacy `task deploy` (no id) invocation still works for one more minor
+release — it prints a deprecation warning and forwards to `task push`. Plan
+to update scripts and CI pipelines before the shim is removed.
+
+### Managing plugins
+
+```bash
+# Register a marketplace (GitHub repo or a local directory)
+rush-ai marketplace add github:kanyun-inc/rush-marketplace
+rush-ai marketplace add directory:/path/to/local-marketplace --as my-mkt
+
+# Install a plugin to every detected IDE
+rush-ai plugin install rush
+# ✓ Installed to Claude Code  (commands + skills + rules + MCP)
+# ✓ Installed to Codex         (skills + MCP)                 [commands/rules/hooks 跳过: Codex 不支持]
+# ✓ Installed to Cursor        (skills + rules + MCP)         [commands/hooks 跳过: Cursor 不支持]
+
+# Target a single IDE
+rush-ai plugin install rush --target claude-code
+
+# Preview without touching disk
+rush-ai plugin install rush --dry-run
+
+# List installed plugins across all targets
+rush-ai plugin list
+
+# Update installed plugins to the latest marketplace version
+rush-ai plugin update
+
+# Remove a plugin (symmetric across all targets)
+rush-ai plugin uninstall rush
+```
+
+Capability-level skips (commands/rules/hooks on an IDE that doesn't support
+them) do **not** downgrade the line-level status — the row stays `✓` and the
+trailing bracket simply lists the skipped capabilities. A `✗` only appears
+when an installer genuinely failed (and rolled back its own writes).
+
 ### Discovering Agents and MCP Servers
 
 ```bash
@@ -205,6 +361,44 @@ rush-ai task status <id> --json | jq '.status'
 rush-ai task result <id> --json | jq -r '.result'
 ```
 
+## How plugin install works
+
+`rush-ai plugin install <name>` is **not** a daemon or a runtime shim — it is
+the CLI equivalent of each IDE's built-in `/plugin install`. Writing the
+plugin files to disk is exactly what the IDE would do internally, so loading
+behaviour is identical.
+
+| IDE | Layout written | Registered in |
+|-----|----------------|---------------|
+| Claude Code | `~/.claude/plugins/cache/<mkt>/<name>/<ver>/` (commands / skills / rules / hooks / `.claude-plugin/plugin.json` with embedded `mcpServers`) | `~/.claude/plugins/known_marketplaces.json`, `installed_plugins.json`, `settings.json.enabledPlugins` |
+| Codex | `~/.codex/plugins/cache/<mkt>/<name>/<ver>/` (`.codex-plugin/plugin.json` with `"skills": "./skills/"` + external `.mcp.json`) | `~/.codex/config.toml` `[marketplaces.*]` + `[plugins.*]` (original backed up to `config.toml.bak.<ts>`) |
+| Cursor | `~/.cursor/skills/<name>/` **and** `~/.cursor/rules/<name>.mdc` (bridge rule with `@file` reference) + `~/.cursor/mcp.json` merge | n/a (rush-ai registry tracks it) |
+
+Every rush-ai-generated rule/bridge carries a `<!-- rush-ai:auto-generated -->`
+marker so uninstall can safely remove only files rush-ai created.
+
+rush-ai keeps its own ledger in `~/.rush/plugins/registry.json` — `targets.<ide>.{status, files, mcpKeys, skipped}` per IDE, plus a `migrations` section for legacy cleanup — so uninstall is byte-accurate regardless of future IDE schema changes.
+
+## Upgrading from 0.7.x (Breaking)
+
+**0.8.0 changes what `rush-ai plugin install` writes to disk.** If you used
+0.7.x in the past, `rush-ai` will migrate your install on the next
+`plugin install` call, following a strict **install-new → verify → cleanup-old**
+order (your old install keeps working until the new one is verified):
+
+1. Installs the new native-format plugin into `~/.claude/plugins/cache/`, updates
+   `installed_plugins.json` / `settings.json.enabledPlugins`.
+2. Verifies the new install (reads the manifest back, checks the cache dir).
+3. On success: removes the legacy `~/.rush/plugins/claude-code/` asset tree,
+   unlinks `~/.claude/skills/rush-task`, removes `mcpServers.rush` from
+   `~/.claude/settings.json`.
+4. On verification failure: leaves both installs in place, appends to
+   `~/.rush/plugins/migration-failed.log`, exits 0 so your install still
+   succeeds.
+
+Opt out by setting `RUSH_SKIP_MIGRATION=1` — useful if you want to hold your
+legacy install for an extra release cycle or audit the new format first.
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -212,6 +406,7 @@ rush-ai task result <id> --json | jq -r '.result'
 | `RUSH_API_KEY` | API key for non-interactive auth (skips browser login) | - |
 | `RUSH_API_URL` | API base URL override | `https://rush.zhenguanyu.com` |
 | `RUSH_PROFILE` | Override active profile | - |
+| `RUSH_SKIP_MIGRATION` | Skip 0.7.x legacy plugin migration on `plugin install` | - |
 | `NO_COLOR` | Disable colored output | - |
 | `DEBUG` | Enable debug logging | - |
 
@@ -221,8 +416,12 @@ Config files are stored in `~/.rush/`:
 
 ```
 ~/.rush/
-├── auth.json             # Credentials (token, refresh token, expiry)
-└── config.json           # Global settings (profiles, metrics, team)
+├── auth.json                    # Credentials (token, refresh token, expiry)
+├── config.json                  # Global settings (profiles, metrics, team)
+├── marketplaces/                # Local cache of registered marketplaces
+│   └── <mkt-name>/              #   directory: points here directly; github: shallow-cloned
+└── plugins/
+    └── registry.json            # Installed-plugin ledger (per-IDE files + mcpKeys + migrations)
 ```
 
 ## Development