@cursor/bdk 0.2.9 → 0.2.10

package/docs/reference/cli.md

@@ -34,6 +34,7 @@ provide their own `help` subcommands.
 | [`docs`](#docs) | Serve the documentation bundled with `@cursor/bdk` |
 | [`init`](#init) | Scaffold a BDK project |
 | [`convert-automation`](#convert-automation) | Export a Cursor Automation into a project |
+| [`migrate`](#migrate) | Move an early-alpha project to architecture v2 through a pull request |
 | [`install-skills`](#install-skills) | Refresh the bundled coding-agent skills |
 | [`info`](#info) | Print the discovered project surface |
 | [`validate`](#validate) | Check project diagnostics and set the exit status |
@@ -470,6 +471,35 @@ authentication, export, and file-write failures exit nonzero.
 See [Convert a Cursor Automation](../guides/convert-automation.md) for the
 generated project and features that need manual review.
 
+### Migrate an early-alpha project {#migrate}
+
+```text
+bdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]
+  [--path <agent-path>] [--no-wait] [--json] [--api-key <key>]
+```
+
+`migrate` applies only to projects deployed on architecture v1 during the BDK
+early alpha. It reads a pushed Git ref, starts a Cursor cloud agent with the
+bundled `bdk-migrate-v2` skill, and opens a pull request with the source
+changes. The command waits for the pull request by default and never deploys
+the project or changes deployment secrets.
+
+| Option | Contract |
+| --- | --- |
+| `--dir <path>` | Select the local BDK project. The default is the current directory. |
+| `--repo <https-url>` | Select the source repository. The CLI infers the current checkout's origin when possible. |
+| `--ref <git-ref>` | Select the pushed ref for the cloud agent. The CLI infers the current branch when possible. |
+| `--path <agent-path>` | Select the project path relative to the repository root. The CLI infers it from `--dir` when possible. |
+| `--no-wait` | Print the cloud agent URL and return after the agent starts. |
+| `--json` | Print a report with `ok`, `status`, `agentId`, and the cloud agent `url`. A completed migration adds `prUrl`; a blocked or failed migration adds its explanation. |
+| `--api-key <key>` | Override the Cursor credential. |
+
+Credential resolution follows the normal order: `--api-key`,
+`CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then
+the stored `bdk login` credential. See
+[Migrate an early-alpha project](../guides/migrate.md) for detection, pull
+request review, and deployment cutover.
+
 ### Install coding-agent skills {#install-skills}
 
 ```text
@@ -504,6 +534,13 @@ bdk validate [--dir <path>]
 when any diagnostic has error severity. Use it instead of `info --json` when a
 script needs validation status.
 
+Hosting checks run here too. On architecture v2 (the default), a
+`githubChannel` credential or a GitLab or Bitbucket `webhookSecret` written
+as a literal or a `() => process.env.NAME` getter is an error whose message
+quotes the `{ secretName: "NAME" }` form to use instead. A project that still
+sets `architecture: "v1"` gets the same finding as a warning, so run
+`validate` before removing the pin to list what the migration must rename.
+
 ### Print a deployment manifest {#manifest}
 
 ```text
@@ -904,6 +941,7 @@ Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
 | `chat`, `session` | Exit `2` for documented option conflicts or missing required input. |
 | `validate` | Exit `1` when any project diagnostic has error severity. |
 | `convert-automation` | Exit `1` for invalid input, authentication, export, or file-write failure. Warnings and dependency-install failure don't change a successful conversion exit. |
+| `migrate` | Exit `0` after starting with `--no-wait` or after the agent opens a pull request. Exit `1` for invalid input, authentication or agent failure, or a completed run without a pull request. |
 | Other commands | Exit nonzero when validation, authentication, a request, or the requested operation fails. |
 
 ## Related
@@ -913,3 +951,4 @@ Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
 - [Evals](./evals.md)
 - [HTTP API](./http-api.md)
 - [Deployment](../deployment.md)
+- [Early-alpha migration](../guides/migrate.md)

package/docs/troubleshooting.md

@@ -57,6 +57,7 @@ Match the visible symptom below.
 
 | What you see | What to do |
 | --- | --- |
+| `validate` or `deploy` reports `architecture "v2" requires a named secret` | A `githubChannel` credential or a GitLab or Bitbucket `webhookSecret` is a literal or a getter. Replace it with the quoted `{ secretName: "NAME" }` and set the value with `bdk secrets set <slug> NAME`. See [Other hosts](./guides/github.md#other-hosts). |
 | Local changes do not appear after deploy | `deploy` reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again. |
 | The deployment never becomes running | Run `bdk deployment <slug>`, then act on the reported build or startup error. |
 | A secret or egress change has no effect | Confirm the name with `secrets list`, verify the `hosting` block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/skills/debug/SKILL.md

@@ -36,6 +36,7 @@ Local `bdk serve`. Hosted start or health failures:
 | Slack `channel idle … missing credentials` | Expected. `slack doctor --prefix <PREFIX>`. |
 | Immediate API-key error | Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `bdk login`). |
 | `validate` clean, CI typecheck fails | tsx skipped types. JSON-shaped returns; `type` not `interface`. |
+| `validate`: `architecture "v2" requires a named secret` | Getter or literal SCM credential. Use the quoted `{ secretName: "NAME" }`; `secrets set <slug> NAME` after deploy. |
 
 Count `action.result` by `toolName` before blaming latency.
 `turn.failed` + `"turn interrupted"` is a follow-up or stop, not a

package/skills/github/SKILL.md

@@ -71,6 +71,29 @@ Without `cursorAccount`, outbound calls prefer App installation
 tokens (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY`). Local tests
 can use `GITHUB_TOKEN` / `gh auth login`.
 
+## Credentials
+
+Name secrets; never read them. Each `credentials` field
+(`webhookSecret`, `token`, `installationToken`, `appId`,
+`privateKey`) takes `{ secretName: "NAME" }`: the env var locally,
+the deployment secret of that name on Cursor hosting. The platform
+verifies `X-Hub-Signature-256` against the named secret before any
+compute starts and `deploy` warns when a named secret is unset.
+
+```ts
+credentials: {
+  webhookSecret: { secretName: "GITHUB_WEBHOOK_SECRET" },
+  appId: { secretName: "GITHUB_APP_ID" },
+  privateKey: { secretName: "GITHUB_APP_PRIVATE_KEY" },
+},
+```
+
+A literal or `() => process.env.X` getter fails `bdk validate` on
+architecture v2 (the default) with `requires a named secret`; the
+message quotes the `{ secretName }` to use. Omit a field to keep its
+default name; a numeric `appId` is allowed. Only `architecture: "v1"`
+still accepts getters, and `validate` warns there.
+
 The Cursor stream is metadata, not full webhook bodies. Re-read
 the PR from GitHub.
 

package/skills/migrate-v2/SKILL.md

@@ -36,6 +36,12 @@ ends. That model changes code in three places:
   between events. Keep durable state in `ctx.host.kv` or `ctx.host.files`.
 - Secrets arrive per request, after modules load. Read `process.env`
   inside the handler, tool, or callback that needs the value.
+- SCM webhook channels name their secrets instead of reading them.
+  `githubChannel({ credentials })` fields and the `gitlabChannel` /
+  `bitbucketChannel` `webhookSecret` take `{ secretName: "NAME" }`, so
+  the platform can verify the provider signature at ingestion and flag
+  an unset deployment secret before the first API call. A literal or a
+  `() => process.env.X` getter is a validation error on v2.
 - The deployment URL serves only routes your channels declare. It
   answers `202` at once and runs the handler afterwards, so a route
   cannot send a response body back to its caller.
@@ -45,8 +51,8 @@ ends. That model changes code in three places:
 | Capability | On v2 |
 | --- | --- |
 | Slack mentions, DMs, and channel posts | Supported. Provision a new Slack app after the first v2 deploy. |
-| GitHub channels, including `cursorAccount` | Supported |
-| GitLab and Bitbucket channels on Cursor hosting | Rolling out. Trial under a new slug first. |
+| GitHub channels, including `cursorAccount` | Supported. Every `credentials` field must be `{ secretName }`. |
+| GitLab and Bitbucket channels on Cursor hosting | Rolling out. Trial under a new slug first. `webhookSecret` must be `{ secretName }`. |
 | Custom HTTP channel routes | Supported. The caller gets `202`, not the handler's response. |
 | Tools, skills, subagents, MCP connections | Supported |
 | `ctx.host.kv`, `ctx.host.files`, artifacts | Supported, in platform-selected storage |
@@ -63,11 +69,11 @@ ends. That model changes code in three places:
 | `--prod` with `chat`, `resume`, `call`, `sessions`, `cost`, or `mcp` | Not supported. Use `run --prod`, `session --prod`, and `logs --prod`. |
 | v1 sessions, KV, and files | Not carried over. v2 starts empty, and deleting v1 deletes them. |
 
-The steps below rewrite `defineStorage`, inline reminders, and secret
-reads. Stop and ask before migrating an agent that depends on cron
-schedules, Slack tool-approval buttons, `mcp oauth --store`, or an HTTP
-route whose caller reads the response body. Name the row and the
-file that uses it.
+The steps below rewrite `defineStorage`, inline reminders, SCM channel
+credentials, and secret reads. Stop and ask before migrating an agent
+that depends on cron schedules, Slack tool-approval buttons,
+`mcp oauth --store`, or an HTTP route whose caller reads the response
+body. Name the row and the file that uses it.
 
 ## Update the project
 
@@ -136,11 +142,44 @@ still loads.
    Slack threads, and deployment events still continue one session per
    PR, thread, or deployment.
 
-6. **Move secret reads.** Replace module-scope `process.env.NAME` reads
+6. **Name SCM channel credentials.** Replace every literal and
+   `() => process.env.NAME` getter in `githubChannel({ credentials })`
+   with `{ secretName: "NAME" }`, and do the same for the `webhookSecret`
+   of `gitlabChannel` and `bitbucketChannel`. Keep the name the getter
+   read; the channel reads that environment variable locally and the
+   deployment secret of that name on Cursor hosting. A field you omit
+   keeps its default name (`GITHUB_WEBHOOK_SECRET`, `GITHUB_TOKEN`,
+   `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`), a numeric `appId` stays a
+   number, and `cursorAccount` needs no credentials.
+
+   ```ts
+   // before (v1)
+   credentials: {
+     webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
+     appId: () => process.env.GITHUB_APP_ID,
+     privateKey: () => process.env.GITHUB_APP_PRIVATE_KEY,
+   },
+
+   // after (v2)
+   credentials: {
+     webhookSecret: { secretName: "GITHUB_WEBHOOK_SECRET" },
+     appId: { secretName: "GITHUB_APP_ID" },
+     privateKey: { secretName: "GITHUB_APP_PRIVATE_KEY" },
+   },
+   ```
+
+   `bdk validate` lists each field still in the old shape. While
+   `architecture: "v1"` is set the finding is a warning, so you can run
+   it before step 2 to see the full list; after step 2 the same finding
+   is an error and blocks `deploy`. Do not set the values: a same-slug
+   deploy copies the v1 secrets, and a new slug takes
+   `bdk secrets set <new-slug> NAME` after the deploy.
+
+7. **Move secret reads.** Replace module-scope `process.env.NAME` reads
    with reads inside the function that uses them. Give MCP connections a
    `${NAME}` header or env template instead.
 
-7. **Stop answering from HTTP routes.** A custom route that returned
+8. **Stop answering from HTTP routes.** A custom route that returned
    computed data must deliver it another way, such as a callback URL or a
    tool the turn calls.
 
@@ -157,7 +196,9 @@ bdk eval --dir .
 ```
 
 Fix every validation error, but never change `runtime` to pass
-validation; stop and report instead. `run` and `eval` need a Cursor
+validation; stop and report instead. An error ending in `requires a
+named secret` names a channel credential step 6 missed; it quotes the
+`{ secretName }` value to use. `run` and `eval` need a Cursor
 credential. When none is set, skip them and say so in the pull request.
 Run the project's own typecheck and tests.