Deepspace

DeepSpace

DeepSpace is one package for real-time collaborative apps on Cloudflare Workers. It provides auth, RBAC, synchronized records, messaging, integrations, payments, and deploys to <name>.app.space.

This skill is the bootstrap: how to start, how to operate, and how to consult the documentation. The documentation at <https://docs.deep.space> is the authority for everything else — it is written to be opinionated, so when it recommends an approach, take that as the default rather than one option among many.

One source authority

Every app has exactly one Git authority — DeepSpace source (packaged, commit-first) or GitHub source (manual; deploys ship the local working tree, dirty bytes included). A new app starts unclaimed, then its first source-producing action latches one authority once, permanently: a deploy from a checkout with a selected GitHub remote claims that repository, while the first deepspace push or a deploy without a GitHub remote claims DeepSpace. There is no manual declaration or later transfer. Never run deepspace push before the first GitHub deploy unless the user has chosen DeepSpace source; after a GitHub claim, all DeepSpace source verbs refuse with source_managed_by_github. deepspace app source is read-only (the old setter refuses source_inferred). Never maintain two sources of truth, and read the source-control and workspaces docs before any source, push, pull, or clone operation — the docs, not this skill, state what each verb does under each authority.

Sharing and handing over an app

Collaborators and ownership transfer (deepspace app collaborators …, deepspace app transfer …) change who can deploy, read secrets, and own the app. Read the app-identity guide before either — it states exactly what each grant confers and what a transfer takes away — and treat both as decisions to surface to the user, not steps to run in passing.

How to read the documentation

Consult the docs BEFORE building in an area, not after something breaks. The reading procedure:

1. Fetch the index once per task area: <https://docs.deep.space/llms.txt> — generated from the docs on every deploy, so it is never stale — lists every page with a one-line summary.
2. Pick 1–2 pages from it and fetch each as Markdown by appending .md to the page URL (https://docs.deep.space/guides/authentication.md). If the page you picked lacks the answer, do not wander adjacent pages — go to step 3.
3. To prove whether a topic exists at all, fetch <https://docs.deep.space/llms-full.txt> once (the whole corpus in one file; each page ends with Source: /route.md) and grep it. A confirmed absence means the docs lag the build — fall back to the installed .d.ts or the CLI's own --help.
4. Use MCP for point lookups when its tools are already available: https://docs.deep.space/mcp exposes documentation_search and documentation_read. If those tools are unavailable or fail, use the Markdown URLs above with the harness's existing fetch tool or a bounded HTTP request (for example, curl -fsSL --max-time 20 <url>). Building an app does not require MCP registration: configure a docs server only when the user asks for that setup, and keep it separate from dependency-install recovery. Search cannot prove a topic is absent — use step 3 for that.
5. For exact type signatures, read the installed package — ls node_modules/deepspace/dist/*.d.ts (in the SDK monorepo itself: packages/deepspace/dist/) — authoritative when any doc lags the installed version.

The docs' shape, so you pick pages fast: /get-started/* is setup and project layout; /concepts/* is the runtime model — read it before touching worker.ts, schemas, or sync behavior; /guides/* is one feature or lifecycle area per page; /design/* is visual design; /sdk-reference/* is exact exports per module; /cli-reference/* is the CLI, including its exit codes and machine-executable action contract. The catalogs are live CLI calls, not pages: npx deepspace integrations list / integrations info <integration>/<endpoint> and npx deepspace add --list.

Operating sequence

1. Authenticate before running app commands.

   npx deepspace auth whoami --json
   npx deepspace auth login # only when signed out

Login opens browser OAuth and polls for up to ten minutes. Leave it in the foreground and let the user finish it; never request, invent, or handle a password. A container or CI shell has no browser: run auth login --help and use the operator-supplied env credentials it names — that help is the authority on which variables they are — and never put a password on a command line.

1. Scaffold instead of assembling the runtime by hand.

Use a supported Node version from the installation docs and npm 11.6+ for npm-based scaffolds. Check node --version and npm --version first: npm 10's peer resolver can crash on the template's Vitest dependency even when Node is supported. If installation fails, retain the actual error and runtime versions before diagnosing it or choosing a recovery; keep the app's selected package manager and lockfile consistent.

   npm create deepspace@latest <app-name>
   cd <app-name>
   npx deepspace dev start

App ids are server-minted at registration, and apps register on first use: the first id-needing verb (deploy, dev start, test run, push, a secrets write) mints the id under whichever login and plane the shell holds, announced on stderr naming the account email. Check auth whoami BEFORE that first verb so the registration lands on the intended account; when the shell's login is not the intended owner, log in as the owner first (or run npx deepspace app init as them) rather than minting an id you then have to throw away. A scaffold made while signed out is fine — it registers the same way once someone logs in. Any app_not_registered or app_not_initialized refusal means exactly that and nothing else.

1. Inspect catalogs before hand-building a feature. Names alone are not a sufficient fit check.

   npx deepspace add --list
   npx deepspace add --info <feature>
   npx deepspace integrations list
   npx deepspace integrations info <integration>/<endpoint>

1. Extend the scaffold. Keep schemas in src/schemas.ts and src/schemas/, routes in src/pages/, app providers in src/pages/(app)/_layout.tsx, and Durable Object wiring in worker.ts. src/constants.ts exposes the display APP_NAME, immutable APP_ID, and primary SCOPE_ID = app:${APP_ID}.

1. Test runtime changes, then deploy.

   npx deepspace test run        # the quick default; it names what it skipped
   npx deepspace test run all    # every spec, including ones you added
   npx deepspace deploy

Multi-user behavior needs a two-user test. Use a distinct port for parallel apps or worktrees. Never kill a sibling session's server.

Shared agent tools

Keep buildTools in src/ai/tools.ts as the single tool definition and register it once in worker.ts with registerAgent(app, { tools: buildTools }); do not duplicate tools or mount the REST routes yourself. Both the website and local agent are enabled by default; use local: false or inApp: false for only one surface.

When access depends on app policy, pass a developer-owned authorize({ userId, claims, request, env }) callback to registerAgent. It returns a boolean (or promise) for subscription, team, role, or app-data checks, applies to both surfaces after identity and membership verification, and can only narrow the app's existing RBAC.

A local agent discovers before invoking:

npx deepspace agent tools <app> --json
npx deepspace agent invoke <app> <tool> --input-file tool-input.json --json