deepspace

DeepSpace

DeepSpace は、Cloudflare Workers 上でリアルタイムの共同作業アプリを構築するためのパッケージです。認証、RBAC、同期されたレコード、メッセージング、インテグレーション、決済を提供し、<name>.app.space にデプロイします。

このスキルでは、始め方、操作方法、ドキュメントの参照方法を説明します。その他のすべてについては、https://docs.deep.space のドキュメントが基準です。独自の推奨方針に基づいて書かれているため、アプローチが推奨されている場合は、多くの選択肢のうちの一つではなく、デフォルトとして扱ってください。

唯一のソース管理元

各アプリが持つ Git のソース管理元は、DeepSpace ソース（パッケージ化され、コミットを優先）か GitHub ソース（手動。ローカルの作業ツリーからデプロイされ、未コミットの変更も含む）のどちらか一つだけです。新しいアプリは未確定の状態で始まり、最初にソースを作成する操作によって、ソース管理元が一度だけ、永久に確定します。選択済みの GitHub リモートを含むチェックアウトからデプロイすると、そのリポジトリがソース管理元になり、最初の deepspace push または GitHub リモートなしでのデプロイでは、DeepSpace がソース管理元になります。手動で宣言したり、後から移行したりすることはできません。ユーザーが DeepSpace ソースを選択していない限り、最初の GitHub デプロイ前に deepspace push を実行しないでください。GitHub がソース管理元に確定した後は、DeepSpace のソース関連コマンドはすべて source_managed_by_github を返して拒否されます。deepspace app source は読み取り専用です（以前の設定コマンドは source_inferred を返して拒否されます）。ソース管理元を二つ持たないでください。また、ソース、push、pull、clone に関する操作を行う前に、ソース管理とワークスペースのドキュメントを読んでください。各コマンドがそれぞれのソース管理元でどう動作するかを定めているのは、このスキルではなくドキュメントです。

アプリの共有と引き継ぎ

共同作業者の設定と所有権の移行（deepspace app collaborators …、deepspace app transfer …）によって、デプロイ、シークレットの読み取り、アプリの所有が可能なユーザーが変わります。どちらを行う場合も、先にアプリ ID ガイドを読んでください。各権限付与で何が可能になるか、また移行によって何が失われるかが正確に記載されています。どちらも、何気なく実行する手順ではなく、ユーザーに確認する判断事項として扱ってください。

ドキュメントの読み方

問題が起きてからではなく、その領域の開発を始める前にドキュメントを確認してください。 手順は次のとおりです。

1. タスク領域ごとにインデックスを一度取得します： https://docs.deep.space/llms.txt — デプロイのたびにドキュメントから生成されるため、古くなることはありません — 各ページの概要が1行で記載されています。
2. インデックスから1〜2ページを選び、ページ URL の末尾に .md を追加して Markdown として取得します（https://docs.deep.space/guides/authentication.md）。 選んだページに答えがない場合は、関連するページを次々と確認せず、手順3に進んでください。
3. トピックが存在するかどうかを確認するには、 https://docs.deep.space/llms-full.txt を一度取得して（コーパス全体を1つのファイルにまとめたものです。各ページの末尾には Source: /route.md とあります）、grep で検索します。 該当する内容がないことが確認できた場合、ドキュメントが実装に追いついていないということです。インストール済みの .d.ts または CLI 自体の --help を確認してください。
4. ポイントを絞った検索には、ツールがすでに利用可能な場合に MCP を使用します： https://docs.deep.space/mcp では documentation_search と documentation_read が利用できます。これらのツールが利用できないか、失敗する場合は、上記の Markdown URL を使い、ハーネスに既存の取得ツールまたは範囲を限定した HTTP リクエスト（例：curl -fsSL --max-time 20 <url>）で取得してください。アプリの開発に MCP の登録は必要ありません。ユーザーがその設定を求めた場合に限りドキュメントサーバーを設定し、依存関係のインストール復旧とは分けてください。検索だけではトピックが存在しないことを証明できません。確認には手順3を使用してください。
5. 型シグネチャを正確に確認するには、インストール済みパッケージを読みます。 — ls node_modules/deepspace/dist/*.d.ts（SDK モノレポ自体では packages/deepspace/dist/）— インストール済みバージョンよりドキュメントが遅れている場合は、こちらが正式な情報源です。

ページをすばやく選べるよう、ドキュメントの構成を示します。/get-started/* はセットアップとプロジェクト構成、/concepts/* はランタイムモデルです。worker.ts、スキーマ、または同期の動作を変更する前に確認してください。/guides/* はページごとに1つの機能またはライフサイクル領域、/design/* はビジュアルデザイン、/sdk-reference/* はモジュールごとの正確なエクスポート、/cli-reference/* は CLI（終了コードと、機械実行可能な action コントラクトを含む）を扱います。カタログはページではなく、CLI のライブ呼び出しです：npx deepspace integrations list / integrations info <integration>/<endpoint> および npx deepspace add --list。

操作手順

1. アプリのコマンドを実行する前に認証します。

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

   ログインするとブラウザーで OAuth が開き、最大 10 分間ポーリングします。フォアグラウンドのままにして、ユーザーが完了するまで待ちます。パスワードを要求、捏造、または取り扱ってはいけません。コンテナーや CI シェルにはブラウザーがありません。auth login --help を実行し、そこに記載されたオペレーター提供の環境変数の認証情報を使用してください。どの変数を使うかは、そのヘルプを基準にしてください。また、コマンドラインにパスワードを指定してはいけません。

2. ランタイムを手作業で組み立てるのではなく、スキャフォールドを作成します。

   インストールのドキュメントに記載されたサポート対象の Node バージョンを使い、npm ベースのスキャフォールドには npm 11.6 以降を使用してください。まず node --version と npm --version を確認してください。Node がサポート対象でも、npm 10 のピア依存関係リゾルバーがテンプレートの Vitest 依存関係でクラッシュすることがあります。インストールに失敗した場合は、原因を診断したり復旧方法を選んだりする前に、実際のエラーとランタイムのバージョンを保持してください。アプリで選択したパッケージマネージャーとロックファイルの整合性を保ってください。

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

   アプリ ID は登録時にサーバーによって発行されます。また、アプリは初回使用時に登録されます。ID を必要とする最初の動詞（deploy、dev start、test run、push、secrets の書き込み）を実行すると、そのシェルが使用しているログインとプレーンのもとで ID が発行され、アカウントのメールアドレスを示すメッセージが stderr に出力されます。登録が意図したアカウントで行われるよう、最初の動詞を実行する前に auth whoami を確認してください。シェルのログインユーザーが意図した所有者でない場合は、破棄することになる ID を発行するのではなく、先に所有者としてログインするか、所有者として npx deepspace app init を実行してください。サインアウトした状態でスキャフォールドを作成しても問題ありません。誰かがログインすれば、同じ方法で登録されます。app_not_registered または app_not_initialized の拒否は、文字どおりその状態を意味し、それ以外の意味はありません。

3. 機能を手作業で構築する前にカタログを調べます。 名前だけでは適合性を十分に確認できません。

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

4. スキャフォールドを拡張します。 スキーマは src/schemas.ts と src/schemas/ に、ルートは src/pages/ に、アプリのプロバイダーは src/pages/(app)/_layout.tsx に、Durable Object の配線は worker.ts に配置してください。src/constants.ts には、表示名の APP_NAME、変更不可の APP_ID、プライマリの SCOPE_ID = app:${APP_ID} が定義されています。

5. ランタイムの変更をテストしてから、デプロイします。

   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
   

   複数ユーザーの動作には、2 ユーザーでのテストが必要です。並行してアプリやワークツリーを使用する場合は、別々のポートを使ってください。別セッションのサーバーを終了してはいけません。

共有エージェントツール

src/ai/tools.ts の buildTools を唯一のツール定義として維持し、worker.ts で registerAgent(app, { tools: buildTools }) を使って一度だけ登録してください。ツールを重複定義したり、REST ルートを独自にマウントしたりしないでください。ウェブサイトとローカルエージェントはどちらもデフォルトで有効です。一方のサーフェスだけを無効にするには、local: false または inApp: false を使ってください。

アクセスがアプリのポリシーに依存する場合は、開発者が管理する authorize({ userId, claims, request, env }) コールバックを registerAgent に渡してください。このコールバックは、サブスクリプション、チーム、ロール、またはアプリデータの確認に対し、真偽値（またはプロミス）を返します。本人確認とメンバーシップ確認の後に両方のサーフェスへ適用され、アプリの既存の RBAC で許可される範囲を狭めることしかできません。

ローカルエージェントは、呼び出す前にツールを検出します。

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

返されたツールだけを使用し、その説明と入力スキーマに従ってください。これらのステートレスコマンドでは選択済みの CLI セッションを再利用します。接続や個別の同意手順はありません。ただし、CLI へのログインで証明されるのは本人確認であり、アプリのメンバーシップではありません。生の REST ではなく CLI を使用し、拒否された場合は以下の説明に従ってください。

コマンドが拒否された場合

拒否にはそれぞれ、固定の code、終了コード、そして最大 1 つの実行可能な action があります。文章ではなく、これらに基づいて分岐してください。

• 終了コード 1 は、示された原因を修正してください。変更せずに再試行しても解決しません。 終了コード 2 は、コマンドで可能な処理は実行されており、ローカルでの手順または 判断が 1 つ残っています。
• action が提供されている場合は実行してください — 指定された argv を、 指定された cwd で実行します。提供されていない場合は、解決策を推測しないでください。 意図的に提供されていません。拒否メッセージは、ユーザーが選択すべき選択肢（フォークするか復元するか、 完了するか中止するか、スロットを空けるかアップグレードするか）を示しているか、 確認すべき事実を示しています。メッセージを読み、選択肢を提示してください。
• 拒否メッセージ自体に、エージェントが誤診していた 2 つの状態が明記されるようになりました。1 つは 誤ったプレーン（not_authenticated は、コマンドが選択したプレーン、 セッションがあるプレーン、解除すべき変数を示します。「再度ログイン」しないでください）。 もう 1 つは 不正なアプリ ID（wrangler.toml 内の DEEPSPACE_APP_ID が有効なアプリ ID ではない場合の invalid_app_id です。 アプリが孤立するため、app init --new-id を実行しないでください。不正な ID があると、通常の app init は拒否されます）。--app を使う場合、コードは異なります。不正な app_… 値には invalid_app が返されます。app_ で始まらない文字列はサブドメイン NAME として扱われます。 有効な名前ではないもの（大文字、ドット、長さが不適切など）には、検索を行わずに invalid_app が返されます。有効な名前に一致するアプリがない場合は、 app_not_found が返されます。これは ID が不正だという意味ではなく、 app list でスペルを確認してください。（例外は transfer accept で、 生の app_… ID のみを受け付け、名前にはすべて invalid_app を返します。）

CLI の概要（/cli-reference/overview）が仕様です — 終了コード、 action のルール、コマンドごとのコード一覧が記載されています。別のプローブで 前提条件を事前に確認しないでください。操作を実行し、拒否メッセージを読んでください。

デプロイしたものを実際に動かす

serving: confirmed と報告されたデプロイは、アプリのライフサイクルの始まりであり、 タスクの終わりではありません。完了と宣言する前に、実行中の様子を確認してください。

npx deepspace logs --follow --json   # what the worker actually did
npx deepspace activity                # pushes, workspaces, releases
npx deepspace releases                # the ledger, and what is rollback-able
npx deepspace app usage               # credits, quota, per-integration spend

ドキュメントで説明されていることのうち、推測してはいけない点が 2 つあります。スケジュールは アプリへの最初のリクエストで有効になります（デプロイ時にリクエストが 1 回送信されます。 送信されなかった場合の確認方法は、スケジュール済みジョブのガイドに記載されています）。 また、捕捉されたエラーは exception ではなく log の行です — logs リファレンスで outcome と eventType の読み方を確認してから、アクションの失敗または成功を判断してください。

初回のデプロイ後

上記の一連の手順は deploy で終わりではありません。アプリはその後も運用されるため、操作する前に、それぞれについて記載された手順を確認してください。

• 新しい SDK への移行には、手動で package.json を編集するのではなく、deepspace app update を使います。まず最新の CLI を実行します — npx deepspace@latest app update --json — その後、steps に従ってください。これは読み取り専用のガイドであり、アプリを書き換えることはありません。更新ガイド (/guides/updating) に手順が記載されており、CLI リファレンスでは各フィールドの意味を説明しています。サーバー発行 ID より古いスキャフォールドでは、どの操作でも app_not_registered が返されます。解決策は npx deepspace@latest app init --new-id のみです。詳しくはガイドを確認してください。
• アクティブなアプリは、プランのクォータ枠を消費します。 それだけが理由でデプロイや新規登録が拒否されることもあります。その場合の解決策は、枠を空けるかアップグレードするかの選択です。そのため、拒否時には実行可能なアクションは提示されません。ユーザーに状況を伝え、代わりに選択しないでください。
• すでに所有しているドメインの接続は、ドメインの購入とは異なります。どちらを行う場合も、まずカスタムドメインのガイドを確認してください。外部登録済みのドメインはそのレジストラで管理し、サポートされている外部ドメインの接続・検証フローを使い、返された DNS レコードに従ってください。ルーティングを設定する前に所有権を証明してください。場当たり的なリバースプロキシや内部レジストリへの書き込みで代用しないでください。証明書の更新に必要な検証レコードは維持し、カスタムホスト名で HTTPS 経由のアプリ接続を確認してから、接続完了としてください。
• **ネイティブクライアント（iPhone、iPad、Mac）**には、deepspace/native 上の mobile/ に Expo アプリを作成する npx deepspace add mobile を使います。作成する前に Expo ガイド (/guides/mobile-apps) を確認してください。SDK にはすでに、キーボードショートカット、コンテキストメニュー、Web 上でも同じアプリを使える機能 (expoWeb)、再接続後も保持される書き込み、アカウントごとに 1 つのプライベートストア (accountStores)、TestFlight 用の npx deepspace testflight <signed.ipa> が用意されています。アプリ内に独自実装するのではなく、これらを使ってください。
• アプリの停止には deepspace app undeploy を使います。これはアプリ関連のコマンドで最も破壊的なものであり、削除されるものと残るものはドキュメントに正確に記載されています。実行前にアプリ ID のガイドを確認し、ユーザーから依頼されていないのに「後片付け」として実行しないでください。

高くつくミスを防ぐルール

• レコードはエンベロープとして扱います。フィールドは record.data の下にあり、put(id, patch) はサーバー側で部分的な値をマージします。
• useMutations().ready になるまで書き込みコントロールを無効にしてください。ナビゲーション、アクセス権の変更、または成功メッセージが処理の受理に依存する場合は、確認付きのミューテーションを使ってください。
• データフックと認証フックには (app)/ プロバイダー境界が必要です。トップレベルのページは静的であり、これらを呼び出してはいけません。
• スキャフォールドに必須の users スキーマは維持してください。拡張はできますが、名前を変更しないでください。
• アプリのシークレットは deepspace secrets で管理し、手動で編集した .dev.vars、シェルの環境変数プレフィックス、ログ、コミット、スクリーンショットには決して含めないでください。
• 呼び出し元の ID は、検証済み JWT からのみ取得してください。ID を WebSocket URL やクライアントが制御する内部ヘッダーで送信しないでください。
• users コレクションを読み取るツールやサーバーアクションは、クライアント名簿と同じものではありません。また、両者が同じ人に同じフィールドを公開するわけでもありません。モデル、クライアント、ログに公開する前に、その経路から何が誰に返されるかを権限ドキュメントで確認してください。「users を読み取る」だけでは説明になりません。
• ローカルの ToastProvider と UI プリミティブは SDK ではなく、src/components/ui にあります。
• スキャフォールドのテーマとスターターのホーム画面はプレースホルダーとして扱ってください。リリースするアプリには独自のデザインを用意してください。
• アプリはサポート対象の Node 系統で実行してください。サポート対象の系統については、インストールガイド (/get-started/installation) を参照してください。