rush-ai 0.9.1 → 0.10.0-rc.2

package/README.md

@@ -152,7 +152,7 @@ so the IDE's own `/plugin list` / `/plugin uninstall` still work.
 | `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 push` | - | Sync a local Rush project's commits to its pod (git push + pod sync/pull). Does NOT create projects. |
 | `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) |
@@ -225,6 +225,72 @@ rush-ai task messages <task-id> --json
 rush-ai task list -l 10 -s completed
 ```
 
+### Setting up a full-stack local project
+
+> ⚠️ **`task link` is currently blocked by [#1147](https://github.com/kanyun-inc/rush-app/issues/1147).** The finalize step 502s because the target GitLab instance rejects the `write_repository` deploy-token scope. Until that's fixed, the recommended path for "set up a full-stack project on Rush" is `task create -a web-builder` — describe what you want (or attach files) and let the web-builder agent build it inside a fresh Rush pod. The documentation below is retained for reference; do **not** run `task link` against rush-test today, it will error at the provisioning step.
+>
+> This blocker is **specific to `task link`**. `task push` (sync-only, #1149) is unaffected — if you already have a Rush project checked out locally, `rush-ai task push` continues to work normally.
+
+Got a local Next.js / Vite project that needs a database + file uploads on Rush?
+`task link` provisions a pod + Supabase DB + Rush-proxied object storage, then
+writes credentials to `.rush/env.md` and a machine-readable checklist at
+`.rush/agent-handoff.md` telling your IDE agent exactly which local files to edit.
+
+```bash
+# From your local project directory:
+cd my-app
+
+# Detect, confirm, and provision. Flags:
+#   --db        create a Supabase database
+#   --oss       record Rush-proxied storage endpoint (no per-project token)
+#   --name      project slug (defaults to directory name)
+#   -y          skip interactive prompts after detection
+rush-ai task link --db --oss -y
+
+# You now have .rush/env.md:
+#   PROJECT_ID=<id>
+#   PREVIEW_URL=https://<id>-preview.rush.zhenguanyu.com
+#   DATABASE_URL=postgres://...
+#   SUPABASE_URL=https://...
+#   SUPABASE_ANON_KEY=...
+#   STORAGE_API_BASE=https://rush.zhenguanyu.com/api/tasks/<id>/storage
+#   STATE=complete
+
+# Your IDE agent reads .rush/agent-handoff.md and rewrites .env.local / upload code.
+# When you're ready:
+rush-ai task push  # reuses PROJECT_ID from .rush/env.md
+```
+
+**Storage API**: uploads go through Rush proxy (not direct OSS) to avoid exposing
+AccessKeys. Server-side code in your app uses `$RUSH_PLATFORM_TOKEN` (already in
+your environment via `rush-ai auth login`) to upload:
+
+```ts
+// apps/your-app/app/api/upload/route.ts — Next.js server route
+export async function POST(req: Request) {
+  const fd = await req.formData();
+  const res = await fetch(`${process.env.STORAGE_API_BASE}/upload`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${process.env.RUSH_PLATFORM_TOKEN}` },
+    body: fd,
+  });
+  return Response.json(await res.json());
+}
+```
+
+Then your browser uploads to `/api/upload` (your own app's server route),
+**never** directly to the storage API with a bearer token. The `task link`
+handoff enforces this two-hop proxy pattern.
+
+Constraints:
+- `.rush/env.md` is auto-gitignored — never commit it
+- Single file ≤ 30 MB (larger streaming planned for Phase 2)
+- Each task has a 5 GB soft storage quota
+- `task link` projects have `template = null` and can't flow through `task deploy` — use `task push` for iterative updates
+- `task link` is compensating, not atomic: if it fails mid-way, just re-run it; it resumes from the last checkpoint in `.rush/env.md`
+
+Full design contract: `specs/rush-v2/cli/task-storage-api.spec.md` (v1.0).
+
 ### Deploying a web-builder task
 
 Once a `web-builder` task has built at least one version (you've sent it a