deepspace 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,173 @@
 # deepspace
 
+## 0.19.0
+
+### Minor Changes
+
+- Block paid app checkout until the owner can accept charges and payouts; require
+  current app roles for direct job mutations and enabled production debug routes;
+  disconnect role-changed sockets; remove email/avatar data from ephemeral
+  presence; refresh ordered/limited live-query snapshots; and clean Yjs awareness
+  per subscribed document. Also retain the earlier claimable-ownership, room
+  identity, log-sanitization, generated-artifact, and first-run agent-DX fixes.
+
+  Existing beta apps must run `npx deepspace@latest app update` with this release
+  so the migration is run by the target CLI. It moves verified room identity from
+  URL parameters to internal headers and installs the stock job-role/debug-route
+  checks using the SDK's shared app-role lookup. Customized seams receive a
+  precise manual blocker; no legacy runtime compatibility branch is retained.
+
+  Generated apps also drop unused model-provider packages and the legacy
+  Documents editor migration. Record writes expose existing room readiness and
+  fail with a stable `not_ready` error before connection; Yjs rooms expose current
+  transport connectivity. Testing sign-in keeps safe server error codes,
+  workspace land returns the deterministic pull action when needed, and generated
+  Documents code is typechecked from the packed release artifact.
+
+## 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
@@ -122,7 +290,7 @@ worktree remove` or a failed cleanup deleted.
 
 ### 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
 
@@ -71,6 +75,12 @@ function Tasks() {
 }
 ```
 
+`useMutations(collection)` exposes the existing RecordRoom `ready` state.
+Writes attempted before it is true reject with `RecordRoomNotReadyError`
+(`code: "not_ready"`) instead of disappearing into a closed socket. For direct
+Yjs rooms, `connected` describes the current WebSocket and `synced` describes
+completion of the current connection's initial document sync.
+
 Worker — expose a `RecordRoom` Durable Object:
 
 ```ts
@@ -89,11 +99,20 @@ 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.
+When updating an existing app, run the target CLI rather than the app's old
+installed binary:
+
+```bash
+npx deepspace@latest app update
+```
+
+The target CLI owns the source migrations required by the SDK version it
+installs. Review and commit its source changes before deploying.
+
+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 +133,19 @@ 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.
+
+In a container, give Git its own credentials before a private-repository
+verification. Forward an SSH agent, or configure an ephemeral Git credential
+helper in the container. Never embed a token in the remote URL: URLs can appear
+in process listings, logs, and copied configuration.
+
+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