deepspace 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,251 @@
 # deepspace
 
+## 0.18.0
+
+### Minor Changes
+
+- **Deploy no longer reads `.dev.vars`. The secret store is the only source.**
+
+  Deploy used to compare hand-edited `.dev.vars` keys against the store and
+  refuse (`secrets_not_uploaded`) or warn when they differed — a guard that
+  inferred intent from a local file. It also broke its own escape hatch: the
+  refusal pointed at `secrets upload .dev.vars` while that same deploy had
+  already written the SDK-managed block into that file, whose keys the upload
+  then rejected, with no code and no action to recover from. An agent that hit
+  it had no way forward.
+
+  `.dev.vars` keeps its real job — deploy WRITES it so `deepspace dev` sees the
+  same values — and is never read back to decide anything.
+
+  **Removed:** the `--allow-missing-secrets` flag and the `secrets_not_uploaded`
+  refusal code, which only existed to escape that guard.
+
+  Deploy now distinguishes a missing config from an explicitly created empty
+  config. A missing config regenerates the local cache without app secrets and
+  refuses before build, Git push, or upload, with an executable
+  `secrets configs create` action. An existing empty config is explicit
+  delete-all intent. The deploy server independently preserves live bindings
+  when an older client omits secret authority, making the rollout safe in both
+  directions.
+
+  Authoritative deletion is part of release finalization, not a best-effort log.
+  The server retries Cloudflare reconciliation three times and retains the
+  per-app release fence on failure. Replaying the exact deploy retries deletion
+  without issuing a second Worker activation; a release is recorded only after
+  stale bindings, including `ALLOW_DEBUG_ROUTES`, are gone.
+
+  If the original CLI process exits after that partial result, a fresh deploy key
+  can resume only when the complete Worker, secret, attribution, and source
+  lineage hash matches the live operation. The server first proves that exact
+  operation is live at Cloudflare; different input stays fenced. Malformed
+  successful Cloudflare secret-list envelopes also fail closed.
+
+  The per-app release transaction is now reserved before route registration,
+  binding auto-provisioning, or rate-limit allocation. Losing concurrent deploys
+  therefore return without renaming the production app or creating provider
+  resources. An incomplete reservation cannot activate; an exact retry may
+  atomically take ownership and finish its resolved rollback metadata. Durable
+  key aliases keep displaced processes from reclaiming the operation and replay
+  the successor after finalization; a safe pre-activation abort removes the
+  aliases with the fence. A compare-and-set transition grants exactly one request
+  permission to issue the Worker PUT. That winner is bound to a request-scoped
+  claim nonce: it can clear its own committed-but-lost claim response before the
+  PUT begins, while an uncertain concurrent request cannot clear the winner's
+  activation fence.
+
+- **`.dev.vars` is now fully generated. Hand edits do not survive.**
+
+  The file used to be three zones — an SDK section, a hand-edited section
+  preserved across runs, and a store cache — which required a divider grammar, a
+  dotenv parser to read the file back, and reconciliation between the two
+  sources. That made `.dev.vars` a second source of truth, and historically a
+  de-facto deploy input (docs/proposals/secrets-source-of-truth.md).
+
+  Now it is a materialization: rewritten whole on every `dev`, `test`, `deploy`,
+  and `secrets pull` run from platform values plus the app's secret store, with
+  a header saying so. Nothing reads it back.
+
+  **If you hand-edited `.dev.vars`, put required values in the store before
+  updating** (`deepspace secrets set KEY=value`). The next dev/test/pull run
+  overwrites the file. There is no legacy import or compatibility path; beta
+  consumers must update their configuration.
+
+  All Wrangler environments now share the one generated `.dev.vars`. Missing
+  configs materialize as empty, so a successful refresh cannot leave stale local
+  values behind.
+
+  Also removed: `secrets upload` no longer strips a generated block (there is no
+  block to strip — uploading the generated file is not a flow; use
+  `secrets download` for backups).
+
+### Patch Changes
+
+- Remove stale lint suppressions from the Messaging and Documents feature
+  sources so an app containing every public feature builds without unused-rule
+  warnings.
+- Support the maintained Node 22 (22.15+), 24, and 26 release lines. Reject
+  end-of-life odd-numbered releases explicitly instead of allowing installs that
+  can fail inside their frozen npm dependency resolver.
+
+  Because npm treats `engines` as a warning by default, `create-deepspace` also
+  checks the runtime before prompts, file copies, identity minting, or Git
+  initialization. Help and version remain available for diagnosis.
+
+- `deepspace pull` no longer traps an agent when local work is simply unpushed.
+
+  Local-ahead — the ordinary state after `commit` — was classified as divergence.
+  `pull` exited 2 with `actionRequired: true` and handed back
+  `git merge refs/remotes/space/<branch>`, which answers "Already up to date" and
+  changes nothing. An agent honouring the exit-2 contract re-ran `pull` forever;
+  only `push` clears the state, and `push` was not the pinned action.
+
+  It is now `status: "local_ahead"` on a successful (exit 0) pull. Human output
+  names `deepspace push`, and JSON carries that same targeted push as its
+  executable success action. `deepspace status` has always classified this
+  correctly — the two now agree.
+
+- Typo'd flags are now refused instead of silently ignored.
+
+  citty hardcodes its parser to `strict: false`, so an unknown flag was never
+  rejected — it was dropped and the command ran with the caller's intent
+  discarded. `deepspace releases --limitt 1` swallowed the flag _and_ its value
+  and returned every release with exit 0; `--jsonn` printed human prose to stdout
+  while the caller waited for JSON. Unknown subcommands and bad flag _values_
+  were already rejected; only flag names went unchecked.
+
+  One check at the shared command boundary now rejects them with
+  `code: "unknown_option"` before any side effect, naming the options that verb
+  accepts. Aliases, hyphenated names, and `--no-<flag>` are unaffected.
+
+- Collaborative apps no longer show stale data as live when the connection dies
+  quietly.
+
+  A peer that stops answering without closing leaves the socket ESTABLISHED — no
+  packets are lost, so nothing retransmits, so no close event ever arrives.
+  Measured against a peer frozen mid-conversation, an unprobed connection stayed
+  open indefinitely. That is a hung Durable Object, a broken relay, or a
+  blackholed path; the browser's `offline` event fires for none of them, because
+  the machine's own network is fine.
+
+  Everything downstream already handled this correctly and was simply never
+  called: `useRecordContext().status` flips to `'disconnected'`, every live query
+  resets to loading while keeping its records on screen, and the socket
+  reconnects with backoff. The client now probes a connection once it has gone
+  quiet and closes it after 45s of silence, so those run when they should.
+
+  The probe costs nothing on the server: `BaseRoom` already registers a
+  `WebSocketRequestResponsePair('ping','pong')`, so the Cloudflare runtime
+  answers it while the Durable Object stays hibernated. An app already receiving
+  updates is never probed. Liveness is probe-based: a quiet socket sends a ping
+  after 15 seconds and closes only when that outstanding probe receives no
+  inbound answer for a further 30 seconds. A backgrounded timer's first resumed
+  callback therefore probes instead of falsely disconnecting a healthy socket.
+  If suspension occurs after a ping was sent, the first delayed callback also
+  discards that pre-suspension judgment and sends a fresh probe before applying
+  the normal deadline.
+
+## 0.17.0
+
+### Minor Changes
+
+- **`deepspace deploy --claim-released` lets a platform admin take a name still inside its 30-day cooldown.** Undeploying releases a hostname into a hold reserved for its previous owner, and `released_by` records the app's **owner** — not whoever ran the undeploy. So an admin taking down an abandoned or abusive app could not then put anything on that name for a month: the reservation belongs to the absent owner, and the admin's own app matches neither the releasing-owner nor the releasing-app leg that normally allows a reclaim. The name was stranded by the mechanism meant to protect it.
+
+  The flag is explicit rather than an implicit admin bypass. The override is absolute — it beats a release made seconds ago and permanently discards the reservation rather than pausing it — so a routine admin deploy must not be able to seize a held name by accident. This is the same reasoning that makes a rename require `--rename`. Non-admin accounts are refused with `admin_required`, and because the tier lookup fails closed, a billing outage refuses rather than grants.
+
+  Two records are written, because neither side knows the whole story: the deploy worker logs the acting admin (it cannot name the displaced owner, since only released rows carry `released_by` and no by-host lookup returns them), and the registry logs the displaced owner and the app that lost the name at the moment the row is replaced.
+
+- **Removed: GameRoom, document mode, and the identity-migration wire.** These
+  landed in #240 and #241 without a changeset, so this declares them rather than
+  letting a release drop public exports silently.
+
+  Gone from the public surface:
+  - `useGameRoom`, and the `GameRoom` durable object with `GameRoomConfig`,
+    `GamePlayer`, `UseGameRoomResult`, `Player`, and `GameInput`. No in-repo app
+    used it, and it failed the authorization, hibernation, and scheduling
+    invariants every other room holds. Use `RecordRoom` for shared state.
+  - `CANONICAL_APP_IDENTITY_MIGRATION_ID` and the `MSG.GAME_*` protocol
+    constants, which had no producer or consumer once the room went.
+  - The RecordRoom document-mode migrations, verified unused across every repo
+    in the org before deletion.
+
+  An app that imported any of these will fail to build. Nothing in the templates
+  or the feature catalog referenced them.
+
+### Patch Changes
+
+- Fix a set of version-control lifecycle and honesty defects found by
+  black-box agent live-testing of multi-checkout collaboration — cases where
+  a verb prescribed recovery that deterministically failed, reported work it
+  did not do, or handed out a command that could not run where it pointed.
+  - **Recovery actions execute verbatim.** Every `action.argv` that re-invokes
+    this CLI is pinned to the running interpreter and entry (resolved through
+    the `node_modules/.bin` symlink) instead of the bare word `deepspace`,
+    which is not on PATH in a linked worktree, a bare clone, or an `npx`
+    invocation. One door (`executableAction`) applies it to refusal actions,
+    success-path actions, the unknown-command suggestion, and `deploy`'s own
+    exit envelope; consumers must not assume `argv[0] === 'deepspace'`.
+  - **A checkout can follow its own advice.** `deepspace clone`, `workspace
+new`, `workspace attach`, `workspace sync`, and `workspace land` fill
+    whichever half of the checkout's repo-local git identity is missing from
+    the session token — previously the `git pull` a divergence refusal handed
+    back (and any first commit) died on `unable to auto-detect email address`
+    in a container with no global git config, or with a half-configured one.
+    The divergence recovery also pins `git pull --no-rebase` (a fresh clone
+    has no reconcile config) and exits 2 from workspace publishes exactly as
+    it does from `push`.
+  - **A second checkout of a landed workspace is no longer a dead end.**
+    `workspace drop` cleans up the stale local worktree and branch of a
+    workspace another clone landed or dropped — proving publication against a
+    freshly fetched trunk tip when the landed ref is gone — and reports
+    whether the remote drop actually happened (`json.remoteDropped`) instead
+    of claiming a fresh drop on a replay. `workspace status` states the right
+    fact per state (landed/dropped → drop cleans up; behind → fast-forward;
+    diverged → integrate first) instead of prescribing a `workspace sync` that
+    would refuse, and `--json` gains `syncRelation` so machine callers see the
+    same distinction. `workspace land` and `workspace sync` on a finished
+    workspace report `workspace_not_active` (with the `workspace drop` cleanup
+    action) ahead of a checkout mismatch whose attach advice could not
+    succeed; drop's own unsynced refusal stops prescribing the publish path
+    once the workspace is finished — nothing can publish those commits, and
+    the message says so. The server returns `workspace_not_active` (over the
+    generic `conflict`) for sync/land/drop against a finished workspace — a
+    worker-side change that reaches existing CLIs on deploy; no released CLI
+    branches on the old slug, and this CLI tolerates both.
+  - **`workspace attach` is idempotent.** Attaching an already-attached
+    workspace points at the existing worktree instead of refusing
+    `branch_exists` — reporting the LOCAL tip and, when it differs from the
+    published tip, the recovery that relation actually admits (`workspace
+sync` when ahead; `git pull --no-rebase` first when behind or diverged,
+    since sync would refuse) — and re-materializes a worktree that `git
+worktree remove` or a failed cleanup deleted.
+  - **Land refusals carry their resume action, and a recorded merge is never
+    reported as a bare failure.** `merge_conflict`, `conflict_markers` (now
+    naming the offending files), `validation_failed`, and
+    `validation_mutated_tree` carry the exact re-run action; when the trunk
+    push succeeded and only recording the land failed, `land_unrecorded`
+    states that the merge IS on trunk and resumes by re-running instead of
+    implying nothing happened. When a concurrent land or drop finished the
+    workspace mid-merge, land answers `workspace_not_active` at exit 2 with
+    `pushed: true` and the `workspace drop` cleanup action — the merge is on
+    trunk, and re-running could never record it.
+  - **`status` stops labeling a feature branch's sync line "Trunk".** A
+    non-default branch renders as `Branch sync`, and `json.trunk` gains
+    `branch`/`isTrunk` (`isTrunk: null` when the default branch is unknown —
+    GitHub-owned source or an unborn cloud repo — never a guess), so
+    `trunk.state: "in_sync"` on a feature branch can no longer read as "local
+    trunk matches cloud trunk". `activity` (CLI and dashboard) stops printing
+    a fabricated "(0 files vs base)" changed-file count on workspace syncs —
+    the event never carried one.
+
+- `deepspace workspace drop` and `land` no longer treat the generic `conflict`
+  error as "already finished".
+
+  The server refuses a finished workspace with `workspace_not_active`; `conflict`
+  was the pre-rename slug, and the CLI accepted both. Platform workers deploy
+  ahead of the CLI release, so nothing still answers with the old slug — and
+  `conflict` remains live for workspace-id clashes, which were being re-read as
+  "already finished" instead of surfacing. An id clash now raises immediately.
+
 ## 0.16.0
 
 ### Minor Changes
@@ -20,7 +266,7 @@
 
 ### Minor Changes
 
-- **`deepspace app migrate` is removed**, replaced by `deepspace app update` (below). It existed for one historical cutover — moving an app from a name-shaped id to a canonical one — and the platform endpoints behind it are unchanged, so an app still on a legacy id migrates with `npx deepspace@0.13.0 app migrate` and then upgrades normally.
+- **`deepspace app migrate` is removed**, replaced by `deepspace app update` (below). It existed for one historical cutover — moving an app from a name-shaped id to a canonical one. The platform migration endpoints were subsequently removed too; an unexpected legacy-id app now requires operator-owned recovery. Do not downgrade to run the old command.
 
   A file that no longer exists now answers `404`, not the app's HTML. Deploys configured the asset layer with `not_found_handling: "single-page-application"`, so it answered EVERY unmatched path with `index.html` at 200 — correct for a client route, wrong for a file. A deploy replaces the hashed build chunks, so a tab still holding the previous `index.html` requested one and got HTML where JavaScript belonged: the script tag parsed it, failed, and the page went white with no error in any log, monitor, or network panel. The same answer went to agents probing `/llms.txt` and `/.well-known/mcp`, telling them the app publishes a manifest it does not have.
 

package/README.md

@@ -6,7 +6,8 @@
 
 The DeepSpace SDK — build real-time collaborative apps on Cloudflare Workers.
 Bundles auth, real-time data subscriptions, RBAC, messaging, file storage,
-collaborative editing (Yjs), and zero-config deployment behind four imports.
+collaborative editing (Yjs), and zero-config deployment through focused public
+entry points.
 
 The fastest way to start is to scaffold a full app rather than wire the SDK up
 by hand:
@@ -27,15 +28,18 @@ npm install deepspace
 
 ## Entry points
 
-The package has four supported import paths:
+The package has seven supported import paths:
 
 - **`deepspace`** — the React client SDK (hooks, providers, auth, storage,
   messaging, theme). Runs in the browser.
+- **`deepspace/schema`** — schema builders and shared schema types.
 - **`deepspace/worker`** — the Cloudflare Worker runtime (`RecordRoom`, schemas,
   JWT verification, HMAC auth). Runs in your app's Worker.
 - **`deepspace/server`** — app-server helpers for actions, billing, and room
   handlers.
 - **`deepspace/testing`** — Playwright fixtures for multi-user tests.
+- **`deepspace/documentation`** — documentation compiler and runtime helpers.
+- **`deepspace/documentation/react`** — documentation React components.
 
 ## Minimal usage
 
@@ -89,11 +93,10 @@ npx deepspace dev start  # run locally
 npx deepspace deploy     # deploy to *.app.space
 ```
 
-The [normative CLI hierarchy](../../docs/platform/cli-contract.md#public-command-hierarchy)
-keeps durable app lifecycle and version migrations under `deepspace app`,
-while checkout-oriented Git, workspace, release, and deploy operations stay
-top-level. In particular, app migration is
-`deepspace app migrate`; there is no top-level `deepspace migrate` alias.
+The hierarchy shown by `deepspace --help` keeps durable app lifecycle under
+`deepspace app`, while checkout-oriented Git, workspace, release, and deploy
+operations stay top-level. The historical `deepspace app migrate` command was
+removed in 0.15.0; it is not an upgrade or recovery path.
 
 Every app has one authoritative Git repository. DeepSpace source is the packaged
 default: the first normal deploy claims it and publishes automatically.
@@ -114,40 +117,14 @@ DeepSpace verifies GitHub but never writes it. Inspect or transfer authority wit
 `deepspace app source`, `deepspace app source github`, or
 `deepspace app source deepspace`. Transfers mirror branches and tags before one
 atomic authority change; switching back uses the same commands. Commands support
-`--json` for agents. See the
-[repository guide](https://github.com/deepdotspace/deepspace/blob/main/docs/platform/repo-store-git.md)
-for workspaces, releases, and rollback.
-
-`deepspace app migrate` is the permanent upgrade runner for breaking app
-changes. It contains an ordered set of structural, idempotent migrations, so
-agents and developers keep using the same command across releases:
-
-```bash
-npx deepspace app migrate --dry-run
-npx deepspace app migrate
-```
-
-The dry-run lists pending source migrations without changing files. For a
-legacy GitHub app whose `DEEPSPACE_APP_ID` is still name-shaped, it also lists
-the exact registry rows that will be re-keyed and the physical stores that
-remain at the existing resource id. The command applies only transformations
-it recognizes safely, pauses for normal commit/push, and finishes with one
-deploy. Applied steps live in the checked-in `deepspace.migrations.json`
-manifest. Normal deploy bundles record that manifest in the release, so the
-next run can determine whether the migration is live without depending on Git
-commit lineage. Rerun after each returned action; when nothing is pending it
-reports `up_to_date`. This is the same workflow for GitHub and DeepSpace
-source; only their normal push behavior differs. `APP_NAME`-based
-legacy room and storage addresses are retained; canonical `DEEPSPACE_APP_ID`
-is used only for logical identity and platform authentication.
-
-Keep deploy, release rollback, and undeploy idle from the mutating command until
-that returned deploy begins; normal app traffic continues throughout.
-Before the registry cutover commits, `--cancel` reverses a prepared migration
-after the restored legacy configuration is committed and pushed. After the
-cutover, recovery is deliberately forward-only: deploy the canonical app and
-rerun `deepspace app migrate` to verify the live release. DeepSpace never
-writes the GitHub repository.
+`--json` for agents. Use `deepspace --help`, command-specific `--help`, and the
+[public manual](https://documentation.deep.space) for workspaces, releases, and
+rollback.
+
+Use the current command-specific release notes for supported upgrade steps. If
+an app or checkout still carries a name-shaped legacy id, stop and contact the
+DeepSpace operator; do not downgrade the SDK or run migration commands copied
+from historical changelogs and proposals.
 
 ## Debugging