@infodb/p3 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +56 -2
  3. package/bin/p3.mjs +18 -0
  4. package/dist/web/apple-touch-icon.png +0 -0
  5. package/dist/web/assets/Outputs-Ni3pNuGU.js +1 -0
  6. package/dist/web/assets/RequestStatus-K8TZwpur.js +1 -0
  7. package/dist/web/assets/TagInput-BICKVH2x.js +1 -0
  8. package/dist/web/assets/TaskDrawer-BkDIstIN.js +3 -0
  9. package/dist/web/assets/_requestId-B5O_ytaq.js +1 -0
  10. package/dist/web/assets/_requestId-C66puEMO.js +30 -0
  11. package/dist/web/assets/action-CMjATXqv.js +1 -0
  12. package/dist/web/assets/board-CbfDjkls.js +1 -0
  13. package/dist/web/assets/copy-B1ZbihKL.js +2 -0
  14. package/dist/web/assets/done-CPQbCFHg.js +1 -0
  15. package/dist/web/assets/draft-dT3gLDIt.js +1 -0
  16. package/dist/web/assets/format-DuK6P1hb.js +1 -0
  17. package/dist/web/assets/index-BUcs2J6N.js +12 -0
  18. package/dist/web/assets/index-C3DkqwJ9.css +2 -0
  19. package/dist/web/assets/link-_s8ndNKS.js +1 -0
  20. package/dist/web/assets/new-T60RB7de.js +1 -0
  21. package/dist/web/assets/preload-helper-dXqN7N-I.js +1 -0
  22. package/dist/web/assets/release-notes-DxrPhDbt.js +3 -0
  23. package/dist/web/assets/requestData-D8ZiSZss.js +1 -0
  24. package/dist/web/assets/rolldown-runtime-hePW80VL.js +1 -0
  25. package/dist/web/assets/routes-D9ZxXoLk.js +2 -0
  26. package/dist/web/assets/search-CJ8MBKTz.js +1 -0
  27. package/dist/web/assets/settings-DsHVyqzJ.js +1 -0
  28. package/dist/web/assets/supersede-CLXlhCq0.js +1 -0
  29. package/dist/web/assets/ui-Cvke4y4X.js +1 -0
  30. package/dist/web/favicon.ico +0 -0
  31. package/dist/web/favicon.svg +12 -0
  32. package/dist/web/index.html +23 -0
  33. package/docs/architecture.md +588 -0
  34. package/docs/chatgpt-sign-in.md +163 -0
  35. package/docs/development.md +194 -0
  36. package/docs/how-to-use.md +524 -0
  37. package/docs/installation.md +275 -0
  38. package/docs/publishing.md +65 -0
  39. package/package.json +86 -3
  40. package/skills/p3/SKILL.md +95 -0
  41. package/src/cli/args.ts +179 -0
  42. package/src/cli/chatgpt.ts +74 -0
  43. package/src/cli/codex.ts +28 -0
  44. package/src/cli/format.ts +9 -0
  45. package/src/cli/help.ts +99 -0
  46. package/src/cli/main.ts +267 -0
  47. package/src/cli/output.ts +99 -0
  48. package/src/cli/preflightCommands.ts +237 -0
  49. package/src/cli/project.ts +501 -0
  50. package/src/cli/readOnly.ts +36 -0
  51. package/src/cli/releaseNotesCommands.ts +139 -0
  52. package/src/cli/render.ts +60 -0
  53. package/src/cli/requestCommands.ts +170 -0
  54. package/src/cli/showView.ts +110 -0
  55. package/src/cli/taskCommands.ts +167 -0
  56. package/src/cli/userConfig.ts +58 -0
  57. package/src/core/chatgpt.ts +33 -0
  58. package/src/core/context.ts +57 -0
  59. package/src/core/machineSettings.ts +207 -0
  60. package/src/core/machineSettingsEdit.ts +156 -0
  61. package/src/core/ops.ts +114 -0
  62. package/src/core/preflight/carryover.ts +133 -0
  63. package/src/core/preflight/codexEngine.ts +702 -0
  64. package/src/core/preflight/codexImage.ts +98 -0
  65. package/src/core/preflight/diagnose.ts +124 -0
  66. package/src/core/preflight/engine.ts +92 -0
  67. package/src/core/preflight/input.ts +65 -0
  68. package/src/core/preflight/launch.ts +86 -0
  69. package/src/core/preflight/launcher.mjs +75 -0
  70. package/src/core/preflight/mock-ui.html +24 -0
  71. package/src/core/preflight/mock-ui.png +0 -0
  72. package/src/core/preflight/mockEngine.ts +145 -0
  73. package/src/core/preflight/render-image/Dockerfile +23 -0
  74. package/src/core/preflight/render-image/render.mjs +53 -0
  75. package/src/core/preflight/render.ts +336 -0
  76. package/src/core/preflight/service.ts +690 -0
  77. package/src/core/preflight/uiMaterials.ts +272 -0
  78. package/src/core/preflight/uiRender.ts +84 -0
  79. package/src/core/preflight/wireframe.ts +69 -0
  80. package/src/core/preflight/xlsx.ts +328 -0
  81. package/src/core/redact.ts +31 -0
  82. package/src/core/releaseNotes/generate.ts +271 -0
  83. package/src/core/releaseNotes/material.ts +114 -0
  84. package/src/core/releaseNotes/mockSummarizer.ts +28 -0
  85. package/src/core/releaseNotes/service.ts +106 -0
  86. package/src/core/releaseNotes/store.ts +216 -0
  87. package/src/core/repoAdmin.ts +81 -0
  88. package/src/core/repoRefs.ts +90 -0
  89. package/src/core/requestOps.ts +140 -0
  90. package/src/core/requestStatus.ts +58 -0
  91. package/src/core/store/attachments.ts +228 -0
  92. package/src/core/store/collection.ts +282 -0
  93. package/src/core/store/frontmatter.ts +22 -0
  94. package/src/core/store/fsutil.ts +90 -0
  95. package/src/core/store/locate.ts +181 -0
  96. package/src/core/store/normalize.ts +155 -0
  97. package/src/core/store/noteStore.ts +56 -0
  98. package/src/core/store/preflightStore.ts +136 -0
  99. package/src/core/store/projectFile.ts +101 -0
  100. package/src/core/store/workspace.ts +328 -0
  101. package/src/core/supersede.ts +74 -0
  102. package/src/core/userConfig.ts +180 -0
  103. package/src/core/userTheme.ts +22 -0
  104. package/src/core/workTargets.ts +120 -0
  105. package/src/server/api/chatgptRoutes.ts +48 -0
  106. package/src/server/api/local.ts +33 -0
  107. package/src/server/api/manifest.ts +119 -0
  108. package/src/server/api/releaseNoteRoutes.ts +78 -0
  109. package/src/server/api/repoRoutes.ts +67 -0
  110. package/src/server/api/routes.ts +374 -0
  111. package/src/server/api/userThemeRoutes.ts +62 -0
  112. package/src/server/server.ts +49 -0
  113. package/src/shared/dates.ts +12 -0
  114. package/src/shared/preflightInput.ts +27 -0
  115. package/src/shared/refs.ts +55 -0
  116. package/src/shared/repos.ts +113 -0
  117. package/src/shared/scopeView.ts +48 -0
  118. package/src/shared/tags.ts +27 -0
  119. package/src/shared/types.ts +700 -0
  120. package/src/shared/workTarget.ts +44 -0
@@ -0,0 +1,163 @@
1
+ # Sign in with ChatGPT(Preflight を各自の ChatGPT プランで動かす)
2
+
3
+ 要望 261009-6ad4x の設計(T004)。Preflight の Codex を、Codex の初期設定でサインインした `auth.json` ではなく、
4
+ P3 が自分でサインインした ChatGPT アカウント(Sign in with ChatGPT のプラン利用)で動かす。
5
+ P3 自体の本人認証は足さない(ローカルの個人用ツールのまま)。
6
+
7
+ サインイン・保存・更新・解除の実装は、llmcs の chatgpt-plan-ts(npm の `@infodb/chatgpt-plan`)にある(P3 の実装を
8
+ アプリ名と保存先を引数にして切り出したもの)。P3 は `src/core/chatgpt.ts` で、アプリ名(`infodb_p3`)・保存先・
9
+ Codex に渡すトークンの長さ・CLI の案内だけを決めて使う。以下は部品と P3 の約束(部品を上げるときに確かめること)。
10
+
11
+ 公式資料(2026-10-10 に確認。以下の契約はこれに合わせる):
12
+
13
+ - 登録とサインイン: https://developers.openai.com/siwc/token-sharing-open-source/sign-in
14
+ - アカウントとセッション(更新・サインアウト): https://developers.openai.com/siwc/token-sharing-open-source/profiles-and-sessions
15
+ - Codex app-server: https://developers.openai.com/siwc/token-sharing-open-source/codex-app-server
16
+ - トークン・エラー・制限: `.../token-reference`、`.../errors-and-recovery`、`.../preview-limitations`、UI: `/siwc/ui-ux-guidelines`
17
+ - OpenID の設定: https://auth.openai.com/.well-known/openid-configuration(`jwks_uri`、`revocation_endpoint`)
18
+
19
+ ## 全体
20
+
21
+ ```
22
+ p3 chatgpt login(CLI)/ 設定画面の「Continue with ChatGPT」
23
+ └─ 127.0.0.1:1455/auth/callback で待つ → ブラウザで auth.openai.com にサインイン・同意
24
+ └─ コード交換・ID トークン検証 → ~/.config/infodb-p3/chatgpt.json(0600)
25
+ Preflight
26
+ └─ 期限が近ければ更新(排他)→ access token を子プロセスの環境変数 ACCESS_TOKEN で
27
+ docker run -e ACCESS_TOKEN … codex app-server -c model_provider=openai_chatgpt_plan …
28
+ ```
29
+
30
+ ## サインイン(@infodb/chatgpt-plan。T006)
31
+
32
+ | 項目 | 値 |
33
+ | --- | --- |
34
+ | authorize | `https://auth.openai.com/api/accounts/authorize`(`response_type=code`、PKCE S256、`state`、`nonce` は毎回新しく) |
35
+ | token | `https://auth.openai.com/api/accounts/oauth/token`(form。`authorization_code` / `refresh_token`) |
36
+ | revoke | `https://auth.openai.com/api/accounts/oauth/revoke`(`token`、`token_type_hint=refresh_token`、`client_id`) |
37
+ | JWKS | `https://auth.openai.com/.well-known/jwks.json`(ID トークンは RS256) |
38
+ | scope | `openid profile email offline_access resource.invoke chatgpt.tokens.use.direct` |
39
+ | resource | `https://api.openai.com/v1`(authorize とコード交換・更新で同じ値) |
40
+ | redirect_uri | `http://127.0.0.1:<port>/auth/callback`(既定 1455。使えなければ別のポート。`localhost` にしない、パスは変えない) |
41
+
42
+ - **登録**: 初回は `client_id=dynamic_agent_client`、`agent_name_hint=infodb_p3`、`ext_agent_host_id` で authorize する。
43
+ コールバックの `client_id`(`oaiapp_...`)が発行された client ID。別の登録窓口や client secret は無い。
44
+ - **ホスト ID**(`ext_agent_host_id`): マシンごとに1つ、`urn:uuid:<乱数>` を作って `chatgpt.json` に残し、ずっと使う。
45
+ - **再サインイン**: 保存した client ID と `id_token_hint`(あれば `login_hint`)で authorize する(`agent_name_hint` は送らない)。
46
+ 新しい ID トークンの `sub` が保存したアカウントと違えば、**保存を上書きせず失敗**にする(別のアカウントに切り替えるには、先に接続を解除する。
47
+ CLI では `p3 chatgpt logout --forget` と案内する)。
48
+ - **ID トークンの検証**: JWKS で署名(RS256)、`iss=https://auth.openai.com`、`aud` に発行された client ID、`exp`、保存した `nonce`。
49
+ 検証した `sub` をアカウントの識別に使う。
50
+ - **プラン利用の確認**: トークン応答の `scope` に `chatgpt.tokens.use.direct` が無ければ「サインインはできたがプラン利用は許可されていない」
51
+ として保存し、Preflight には使わない(同意をやり直すには、もう一度サインイン)。
52
+ - **新しい試行が終わるまで既存の接続は変えない**(コード交換と検証に成功してから、まとめて書き換える)。
53
+ - 拒否(`error=access_denied`)・取消・5分のタイムアウト・ポートが使えない・ブラウザを開けない(URL を表示して手で開く)を扱う。
54
+
55
+ ### 保存
56
+
57
+ ```
58
+ ~/.config/infodb-p3/config.yaml 個人設定(プロジェクトなど)。秘密は置かない
59
+ ~/.config/infodb-p3/chatgpt.json 接続(0600。一時ファイルも 0600 で書いて rename)
60
+ ~/.config/infodb-p3/chatgpt.lock 更新の排他(O_EXCL。古い lock は 60 秒で取り直す)
61
+ ```
62
+
63
+ `chatgpt.json`(1接続。初期は1つだけを扱う):
64
+
65
+ ```json
66
+ {
67
+ "hostId": "urn:uuid:…",
68
+ "clientId": "oaiapp_…",
69
+ "account": { "sub": "…", "email": "…" },
70
+ "tokens": {
71
+ "accessToken": "…", "refreshToken": "…", "idToken": "…",
72
+ "expiresAt": "2026-10-10T01:00:00Z", "scopes": ["…"], "savedAt": "…"
73
+ }
74
+ }
75
+ ```
76
+
77
+ - `config.yaml` とは別のファイルにするので、プロジェクトや画面の設定を保存しても接続は消えず、その逆も起きない。
78
+ - Preflight のログとエラー(`run.json`)に残す前に、トークンらしいものを伏せる(`src/core/redact.ts`)。Codex は API の認証エラーで
79
+ キーの一部(先頭 8 文字と末尾 3 文字。例 `Incorrect API key provided: eyJhbGci***xyz`)を見せるので、それと JWT・Bearer の値・
80
+ 渡したトークンそのものを `[伏せました]` にする
81
+ - CLI の `--json`、API、ログ、エラーには、トークンを出さない(状態として出すのはアカウントの email、プラン利用の可否、期限、ホスト ID・client ID の有無)。
82
+ - **接続の解除**(`p3 chatgpt logout`): refresh token を revoke してから、`tokens` を消す。ホスト ID・client ID・アカウントは残す
83
+ (次のサインインで同じ登録を使う。公式: サインアウトしても登録したクライアントは消えない)。revoke が通らなかったら
84
+ ローカルのトークンは消し、「ChatGPT の設定で接続を切ってください」と伝える。`--forget` で登録ごと消す。
85
+ - 旧来の `auth.json`(Codex の初期設定でのサインイン)は変換しない。新しくサインインしてもらう。
86
+
87
+ ### 更新
88
+
89
+ - 期限の 35 分前を過ぎていたら、使う前に更新する(Preflight の1ターンの上限 30 分 + 余裕。access token は 1 時間)。
90
+ 部品の `accessToken()` の既定は 5 分なので、P3 は Codex に渡すときに 35 分(`CODEX_TOKEN_MIN_VALID_MS`)を渡す。
91
+ - `refresh_token` グラント(発行された client ID、`resource`、`scope` は送らない)。応答の access token・期限・scope・新しい refresh token を
92
+ まとめて書き換える(refresh token は毎回入れ替わる)。
93
+ - 同じマシンの CLI・serve・並行する Preflight が同時に更新しないよう、lock を取り、取ったら読み直して、まだ必要なら更新する。
94
+ - `invalid_grant` などの更新できないエラーは、トークンを消して「サインインし直してください」。ネットワークや 5xx では消さない。
95
+
96
+ ## llmcs(@infodb/codex-workspace。T005)
97
+
98
+ 公式の Codex app-server の手順に合わせ、llmcs に足すもの(旧来の `authVolume` / `authFile` はそのまま使える):
99
+
100
+ - `dockerCommand(workspace, { accessTokenEnv: "ACCESS_TOKEN" })`: 認証のマウントをせず、`-e ACCESS_TOKEN`(**値は argv に入れない**。
101
+ 起動するプロセスの環境から引き継ぐ)と、次の `-c` を付ける:
102
+ `model_provider="openai_chatgpt_plan"`、`model_providers.openai_chatgpt_plan.name="ChatGPT plan"`、`…base_url="https://api.openai.com/v1"`、
103
+ `…env_key="ACCESS_TOKEN"`、`…wire_api="responses"`、`…requires_openai_auth=false`、`…supports_websockets=false`
104
+ - `WorkspaceSession.open(command, { env, clientInfo })`: 子プロセスに渡す環境変数(ここに ACCESS_TOKEN)と、`initialize` の
105
+ `clientInfo`(`name` は `agent_name_hint` と同じ `infodb_p3`、`title`、`version`)。
106
+ - `session.restart({ env })` と `session.resumeThread(threadId)`: 更新したトークンで起動し直し、スレッドを続ける(公式の更新手順)。
107
+ - 使用量の上限: `subscription_sharing_usage_limit_exceeded`(429)も `UsageLimitError` にする。
108
+ - `usage()`(`account/rateLimits/read`)は ChatGPT アカウントでのサインインを前提とする API なので、この方式では呼ばなくてよい
109
+ (呼ぶ側の任意。P3 は呼ばず、「利用状況は取得できません」と表示する)。
110
+
111
+ ### スレッドの続き(thread/resume)について
112
+
113
+ Codex 0.162.0 の app-server には `thread/resume` があるが、P3 は記録を残さないスレッド(`ephemeral`)を、終わると消える
114
+ コンテナ(`--rm`)で動かしている。起動し直すと元のスレッドは無いので、**P3 は実行の途中で更新しない**:
115
+ 実行を始める前に、1ターン(最長 30 分)より長く使えるトークンにしておく。新しい run はこれまでどおり新しいスレッドで始める。
116
+ llmcs の `restart` / `resumeThread` は、記録を残す使い方(`ephemeral` にしない、`CODEX_HOME` を残す)のための部品として足す。
117
+
118
+ ## Preflight(T007)
119
+
120
+ 認証の選び方(上から):
121
+
122
+ 1. `codex.auth: legacy`(`P3_CODEX_AUTH=legacy`)と `codex.authVolume` / `codex.authFile` → 旧来の `auth.json`(明示したときだけ)
123
+ 2. ChatGPT に接続していてプラン利用が許可されている → Sign in with ChatGPT
124
+ 3. 旧来の `codex.authVolume` / `codex.authFile`(`P3_CODEX_AUTH_VOLUME` / `P3_CODEX_AUTH_FILE`)だけがある → 旧来の `auth.json`(移行期間の互換)
125
+ 4. どれも無い → Codex は使えない。画面と CLI で「ChatGPT でサインインしてください」と案内する
126
+ (`preflight.engine: mock` か `P3_PREFLIGHT_ENGINE=mock` を明示したときだけ Mock。**認証の失敗を Mock の成功に見せない**)
127
+
128
+ - 状態の表示は、未接続 / プラン利用が未許可 / 期限切れで更新できない / 使用量の上限 / Docker が無い / 旧方式 / Mock を分けて、次にすることを出す。
129
+ - 接続の変化(CLI でサインインした・解除した)を、起動中の serve にもすぐ反映する(状態のキャッシュは接続のファイルの更新日時が変わったら捨てる)。
130
+ - `model/list` は手元の一覧を返すことがあるので、使えるかの判断には使わない。使えたかはターンが `completed` になったかで決まる。
131
+ - 公式の制限: Responses の `tool_search` を出す設定は失敗する。ローカルのシェルや関数ツールは使える(P3 の Preflight はこれで足りる)。
132
+
133
+ ## 画面(T008)
134
+
135
+ - 設定画面に、プロジェクトの設定とは分けた「Use your ChatGPT plan」の欄を置く。状態、ボタン「Continue with ChatGPT」(公式の表記)、
136
+ 待っている間の取消、解除、「Manage usage」(https://chatgpt.com/settings/usage)。初回の接続後に一度だけ
137
+ 「You're using your ChatGPT plan」の説明を出す。使用量の上限では「Usage limit reached」。
138
+ - サインインの待ち受けは serve のプロセスが行う(CLI と同じ部品)。同時に1つだけ。ページを読み直しても待っている試行を表示する。
139
+ - **変更の API(開始・取消・解除)を受けるのは、自分のマシンからだけ**: 接続元が 127.0.0.1 / ::1 で、`Origin` があり `Host` と同じこと。
140
+ serve は既定で 0.0.0.0 で待つので、LAN の別のマシンからサインインの開始や解除をされないようにする(`Origin` が無いだけでは通さない)。
141
+ 状態の API も同じ条件にする(アカウントの email を出すため)。
142
+
143
+ ### DevContainer
144
+
145
+ - コールバックは**ブラウザのあるマシン**の 127.0.0.1 に来る。VS Code の DevContainer で動かすときは、待ち受けたポート(1455)を
146
+ VS Code が自動で転送するので、ホストのブラウザからのコールバックがコンテナに届く(Codex の CLI のサインインと同じ形)。
147
+ - 転送されない環境(別のコンテナ・リモートの VM・SSH)では、ブラウザがコールバックの URL を開けずエラーになる。そのときは
148
+ アドレスバーの URL(`http://127.0.0.1:1455/auth/callback?code=…`)を `p3 chatgpt login --paste` に貼れば、続きを CLI で行う。
149
+ - serve の API はブラウザから見ると転送された localhost に来る。VS Code の転送の接続元はコンテナの中の 127.0.0.1 になるので、上の条件を満たす。
150
+ `docker run -p` で公開した serve は接続元がゲートウェイになるため、画面からの接続はできない(CLI を使う)。
151
+
152
+ ## 依存
153
+
154
+ - `@infodb/chatgpt-plan`(依存なし。PKCE・JWT の検証は Node の `crypto`、HTTP は `fetch`)。版と待機の決まりは
155
+ [docs/architecture.md](architecture.md) の「llmcs の部品の依存」。
156
+ - 保存の形式・ファイル・ロック(`chatgpt.json` / `chatgpt.lock`)は部品に切り替える前と同じ。切り替えの前にサインインした接続を
157
+ そのまま使える。
158
+
159
+ ## 範囲外・今後
160
+
161
+ - 複数の接続(アカウント)の切り替え。今は1つ。
162
+ - ホストごとの利用状況の表示(公式に利用状況を読む API が無い)。
163
+ - VM へのトークンの持ち出し(公式: 持ち出したセッションのホストごとの取り消しはまだできない)。
@@ -0,0 +1,194 @@
1
+ # 開発ガイド
2
+
3
+ P3 そのものを開発するときの手順と、ソースの構成。使い方は [使い方ガイド](how-to-use.md)、設計と規則は
4
+ [docs/architecture.md](architecture.md)、公開の手順は [docs/publishing.md](publishing.md)。
5
+
6
+ ## このリポジトリから動かす
7
+
8
+ 開発には Node 24 を使う(Vite 8)。使うだけなら Node 22 以上でよい。
9
+
10
+ ```bash
11
+ pnpm install
12
+ pnpm build # 画面(p3 serve で配信する dist/web)
13
+ pnpm link --global # `p3` コマンドをこのチェックアウトで使う(任意)
14
+ ```
15
+
16
+ グローバルに入れずに、P3 の場所を指定して pnpm で直接動かしてもよい。管理したいリポジトリ(やその作業ツリー)の中で:
17
+
18
+ ```bash
19
+ pnpm -s --dir /path/to/p3 p3 whoami # -s で pnpm 自身の出力を抑える(--json の出力は stdout だけに出る)
20
+ ```
21
+
22
+ pnpm はスクリプトをパッケージの場所で動かすが、P3 は呼び出し元の場所(pnpm が渡す `INIT_CWD`)に戻ってから
23
+ 対象のプロジェクト・今の要望(作業ツリーのブランチ)・git のユーザーを判定する。
24
+
25
+ ## よく使うコマンド
26
+
27
+ ```bash
28
+ pnpm dev # API サーバ(p3 serve, tsx watch)+ Vite http://localhost:5173
29
+ pnpm build && pnpm start # ビルドした画面を p3 serve から配信 http://localhost:4310
30
+ pnpm typecheck
31
+ pnpm lint # oxlint(型情報も使う。下の「lint」)
32
+ pnpm test # ユニットテスト(vitest)。pnpm test:watch で監視
33
+ pnpm check # 型検査 + lint + テスト + ビルド
34
+ pnpm demo:reset # デモデータ(.p3-demo/)を作り直す
35
+ pnpm verify:pack # 配布物を別の場所に入れて動かす(--docker で codex update と render も)
36
+ ```
37
+
38
+ - `pnpm dev` / `pnpm start` は P3 自身の開発を題材にしたデモデータ(`.p3-demo/`、git 管理外)を開く。無ければ自動で作る
39
+ (`scripts/demo.ts`。中身は `scripts/demoData.ts`)。作るときに実際に Preflight(Mock)を走らせ、タスク化・作業の進行まで
40
+ 済ませるので、各画面をそのまま確かめられる
41
+ - `.p3-demo/` が既にあると `pnpm demo` は何もしない。デモの例を増やしたら `pnpm demo:reset` で作り直す(手で直した内容も消える。
42
+ 実際のプロジェクトのデータには触れない)
43
+ - サーバと Vite は既定で `0.0.0.0` で待ち受ける(DevContainer の外から見るため)。画面に認証は無いので、信頼できない
44
+ ネットワークでは `serve.host: 127.0.0.1`(`P3_HOST=127.0.0.1`)に絞る
45
+
46
+ ## テスト
47
+
48
+ - テストは一時ディレクトリに git リポジトリと `.p3/` を作って動かす(`test/helpers.ts`)
49
+ - Codex の経路は、JSON-RPC を話す偽の app-server(`test/fixtures/fake-codex.mjs`)に差し替えて確かめる。本物の Codex が実際に
50
+ どこまで読むか、読むだけのマウントへの書き込みが拒まれることは、偽の app-server では確かめられない
51
+ - `init --agents` で置いたスキルを本物の Codex が見つけて読むかは、偽の app-server では確かめられない。置き場所
52
+ (`SKILL_TARGETS`)や Codex の版を変えたときは、手で確かめる(結果はタスクの変更の記録に残す):
53
+
54
+ ```bash
55
+ # 一時フォルダに git リポジトリを作り、個人設定も分けて置く(p3 を使わない別のリポジトリ other/ も作っておく)
56
+ XDG_CONFIG_HOME=$TMP/cfg node <このチェックアウト>/bin/p3.mjs init --yes --agents --project sample --dir $TMP/data
57
+ # ルート・サブフォルダ・other/ のそれぞれで、スキルの一覧と場所を聞く(p3 は .agents/skills/p3/SKILL.md、other/ では出ない)
58
+ codex exec --ephemeral --ignore-user-config -s read-only "List every skill available to you with its SKILL.md path. Also quote what each skill root alias (r0, r1) maps to."
59
+ # $p3 を明示して、本文だけにあること(whoami --json の via の確認・Preflight と accept は人)を引用させる
60
+ codex exec --ephemeral --ignore-user-config -s read-only '$p3 Do not run p3. Quote what the skill says to check first and who runs Preflight and accept.'
61
+ ```
62
+
63
+ 個人のスキル(`~/.agents/skills`・`/etc/codex/skills`)と `~/.codex/config.toml` の `[[skills.config]]` に p3 が無いことを先に確かめる。
64
+ Codex がスキルを探す場所は公式の文書(<https://developers.openai.com/codex/skills/> の「Where Codex loads local skills」)
65
+ - CLI のテストは別プロセスで `bin/p3.mjs` を動かし、個人設定を一時フォルダに分け、このマシンの `P3_*` の環境変数は効かないようにしている
66
+ - `test/layers.test.ts` が src の層の依存の向き、`test/package.test.ts` が配布物の中身と文書のリンクを確かめる
67
+ - 短い出力の量を測るときは:
68
+
69
+ ```bash
70
+ for t in T001 T002 T003; do p3 show <要望ID>/$t | wc -c; p3 show <要望ID>/$t --brief | wc -c; done
71
+ pnpm vitest run test/showBrief.test.ts --reporter=verbose
72
+ ```
73
+
74
+ ## lint
75
+
76
+ `pnpm lint` は [oxlint](https://oxc.rs/docs/guide/usage/linter) で、型情報を使う規則(`--type-aware`。`oxlint-tsgolint` が
77
+ TypeScript 7 の型検査器で tsconfig.json を読む)も動かす。設定は `.oxlintrc.json`。ESLint・Biome・整形の道具は入れていない
78
+ (書式はそろえて書く)。指摘は全部エラーで、警告も使われていない無効化コメントも `pnpm check` を落とす。
79
+
80
+ - **対象**: tsconfig.json の include と同じ `src`・`scripts`・`test`・`vite.config.ts`・`vitest.config.ts`。この中の `.mjs`
81
+ (起動の補助・偽の app-server など)も、TypeScript の対象ではないが型情報なしの規則で検査する。`bin/` は対象の外
82
+ - **除外**: 生成したルート一覧 `src/web/routeTree.gen.ts`。`dist/`・`node_modules/`・`.p3-demo/` は対象のフォルダの外
83
+ - **規則**: plugin は typescript・unicorn・oxc・react・import・promise・vitest。それぞれの correctness(誤りか無意味なコード)を全部
84
+ 使い、ほかのカテゴリは一括では入れず、次を選んで足す
85
+
86
+ | 足した規則 | 理由 |
87
+ | --- | --- |
88
+ | `react/rules-of-hooks` | Hooks を条件の中で呼ばない(`react/exhaustive-deps` は correctness に入っている) |
89
+ | `typescript/no-misused-promises` | Promise を返す関数を `onClick` など void を期待する所に渡さない(失敗が未処理になる。下の「待たない Promise」)。`typescript/no-floating-promises` は correctness に入っている |
90
+ | `typescript/no-unnecessary-type-assertion` | 要らない `as` / `!` を残さない(型が変わったときに隠れる) |
91
+ | `typescript/switch-exhaustiveness-check` | 状態の union の switch で漏れを出さない(`default` があればよい) |
92
+ | `typescript/only-throw-error`・`typescript/prefer-promise-reject-errors` | Error 以外を投げない・拒否しない(画面は `e.message` で知らせる) |
93
+ | `import/no-duplicates`・`import/no-cycle` | 同じモジュールの import を分けない・循環させない(層の向きは `test/layers.test.ts`) |
94
+
95
+ | 調整・外した規則 | 理由 |
96
+ | --- | --- |
97
+ | `eslint/no-unused-vars` に `ignoreRestSiblings` | `const { drafts, ...meta } = run` のように、項目を外すための分割代入を許す(使っていない変数そのものは tsc の `noUnused*` も見る) |
98
+ | `vitest/valid-expect` に `maxArgs: 2` | vitest の `expect(値, 失敗時の文言)` を許す |
99
+ | `react/refs`・`react/set-state-in-effect`(off) | React Compiler を前提にした規則。P3 は Compiler を使わず、最新の handler を ref に持つ形(`lib/live.ts`)や、外で変わった設定を編集中でなければ取り込む effect(設定の画面)を意図して書いている。直すと再取得・入力を残す約束を書き換えることになる |
100
+ | `typescript/no-base-to-string`(off) | YAML・frontmatter の読めない値を `String(v)` で文字にするところ(`core/store/normalize.ts` など)を全部指摘する。値の正規化の振る舞いは変えない |
101
+ | `vitest/no-conditional-expect`(off) | 画面をビルドしてあるときだけ確かめるなど、環境で分ける確認を意図して書いている |
102
+ | `vitest/require-mock-type-parameters`(off) | `vi.fn(async () => …)` の型は実装から推論される |
103
+
104
+ 入れなかった規則: `typescript/no-unnecessary-condition`(nursery で、まだ変わる。試すと 56 件で、`?.` の防御も指摘する)、
105
+ suspicious カテゴリの一括(JSX で要らない `react-in-jsx-scope` などが大量に出る)、`typescript/no-unsafe-*`(テストの応答の JSON
106
+ など `any` を読む所が多く、試すと合わせて 1,400 件を超える。型を付ける作業は別にする)。
107
+
108
+ 無効化のコメントは、その行で意図して違反するときだけ、規則と理由を付けて書く
109
+ (`// oxlint-disable-next-line no-control-regex -- 制御文字を外すのが目的`)。使われなくなったコメントは lint が落とす。
110
+ `eslint-disable` の形の既存のコメント(`react-hooks/exhaustive-deps`)も oxlint が読む。
111
+
112
+ **待たない Promise**: 画面の操作から非同期の処理を呼ぶときは、失敗を必ずどこかで知らせる。
113
+
114
+ - 中で try / catch して画面に知らせる関数(保存・Preflight の開始など)は `onClick={() => void save()}`。`void` は
115
+ 「待たない」の印で、失敗を隠すためには使わない
116
+ - 失敗を受け止めない処理は `runAction(処理, (文言) => …)`(`src/web/lib/action.ts`)で、失敗を画面に渡す
117
+ - 読み直し(`reload`)のように失敗を状態に入れて投げない関数は、子には `() => void reload()` を渡す
118
+
119
+ `test/lint.test.ts` が、採用した規則の代表的な違反(Hooks・待たない Promise・Promise の渡し方)で lint が失敗することと、
120
+ 対象と除外を実際に動かして確かめる。
121
+
122
+ ## 構成
123
+
124
+ ```
125
+ src/ 依存の向き: shared ← core ← server / cli、web → shared(test/layers.test.ts で確かめる)
126
+ shared/ 型定義・参照の解き方・日付・判定(core と画面の共通。I/O と node: は使わない)
127
+ cli/ p3 CLI(core でファイルを直接操作。serve でサーバも起動する)
128
+ main.ts 振り分け・プロジェクトと変更者と今の要望の決定・終了コード
129
+ taskCommands.ts / requestCommands.ts / preflightCommands.ts コマンドの種類ごと(変更は core/requestOps.ts を通す)
130
+ args.ts / output.ts / help.ts 入力の解釈・出力・p3 help
131
+ core/ CLI と serve の共通の中核(HTTP は使わない)
132
+ requestOps.ts 要望・タスクの変更の手順(CLI と API はここを呼ぶ。確かめる → 保存 → ブランチの割り当て・進行中に戻す → 変更通知)
133
+ ops.ts CLI と API で共通の読み取り(一覧・参照の解き方・進捗の集計など)
134
+ store/ 要望のフォルダとタスクのコレクション、frontmatter、Preflight の保存、監視
135
+ preflight/ エンジン(codex-workspace / mock)と実行・タスク化
136
+ chatgpt.ts ChatGPT の接続(アプリ名・保存先・トークンの長さ。サインインと保存は @infodb/chatgpt-plan)
137
+ context.ts / userConfig.ts / machineSettings*.ts プロジェクトを開く・個人設定・マシンごとの設定
138
+ server/ HTTP だけ(p3 serve)
139
+ server.ts 待ち受けと画面の配信
140
+ api/ REST + SSE(core を呼ぶ)
141
+ web/ React + TanStack Router + Tailwind(text-base 基準)
142
+ routes/ ページ(1ファイル1ページ。__root.tsx が共通の枠)
143
+ routeTree.gen.ts ルート一覧(自動生成)
144
+ components/ 部品(複数のページで使うもの。大きいページの部品は components/<ページ>/)
145
+ bin/p3.mjs CLI の起動口(tsx でソースをそのまま動かす)
146
+ skills/p3/SKILL.md AI 向けスキルの原本(p3 init --agents で各プロジェクトの .claude/skills と .agents/skills に写す)
147
+ scripts/ デモデータ・配布物の確認
148
+ docs/ 導入・使い方・開発・設計・公開の文書
149
+ test/ ユニットテスト
150
+ ```
151
+
152
+ 画面のページは TanStack Router のファイルベースのルーティングで、`src/web/routes/` にファイルを置けば足りる。
153
+ 小さいページは中身もそのファイルに書く。大きいページは、ルートのファイルを組み立て(状態と並び)だけにし、部品を
154
+ `src/web/components/<ページ>/` に分ける(要望の画面は `components/request/`)。ルート一覧 `src/web/routeTree.gen.ts` は
155
+ `pnpm dev` / `pnpm build` / `pnpm typecheck` のたびに生成される(設定は `tsr.config.json`。型検査のためにコミットしておく)。
156
+
157
+ 規則を足すときに直す場所は [docs/architecture.md](architecture.md) の「規則の置き場所」。
158
+
159
+ ## npm で配る中身
160
+
161
+ `@infodb/p3` として npm に公開する(公開そのものは人が行う。手順は [docs/publishing.md](publishing.md))。TypeScript のソースを
162
+ `tsx` でそのまま動かし、画面だけをビルドして同梱する。
163
+
164
+ | 何を | どうする |
165
+ | --- | --- |
166
+ | 同梱するもの(`files`) | `bin/`・`src/cli`・`src/core`・`src/server`・`src/shared`(実行するソース。描画のイメージの資材 `src/core/preflight/render-image/` を含む)、`dist/web`(ビルド済みの画面)、`skills/`(AI 向けスキルの原本)、`docs/`(README から辿る文書)、README・LICENSE |
167
+ | 同梱しないもの | `.env`・個人設定・デモデータ(`.p3-demo/`)・テスト・`scripts/`・画面のソース(`src/web`)・開発用のスキル(`.claude/`) |
168
+ | 実行時の依存 | `tsx`・`hono`・`@hono/node-server`・`yaml`・`zod`・`@infodb/codex-workspace`・`@infodb/chatgpt-plan`。React などの画面の部品はビルドに使うだけなので開発用 |
169
+ | Node | `>=22`(`@infodb/codex-workspace` と同じ)。開発(Vite 8)は Node 24 |
170
+ | 公開前のビルド | `prepack` で `pnpm build`。利用者が入れるときにはビルドも Docker の操作もしない |
171
+ | bin | `p3`。起動口は今いる場所の `tsconfig.json` を読まない。`INIT_CWD` に戻るのは P3 自身の `pnpm p3` スクリプトのときだけ |
172
+
173
+ ```bash
174
+ pnpm -s check # 型検査・lint・テスト・画面のビルド
175
+ pnpm verify:pack --docker # npm pack → 実行時の依存だけで別の場所に入れて動かす(scripts/verify-pack.mjs)
176
+ # DevContainer の中では、描画の出力先を Docker のホストから見えるところにする
177
+ P3_CODEX_PATH_MAP=/workspaces=/home/me/workspaces pnpm verify:pack --docker --render-dir /workspaces/tmp
178
+ ```
179
+
180
+ ## 文書を直すとき
181
+
182
+ | 文書 | 書くこと |
183
+ | --- | --- |
184
+ | [README](../README.md) | 何をするツールか・必要なもの・最短の手順・文書の案内だけ |
185
+ | [docs/installation.md](installation.md) | 導入(Docker・パスの対応・ChatGPT・Codex のイメージ・つまずいたとき・マシンごとの設定) |
186
+ | [docs/how-to-use.md](how-to-use.md) | 使い方の手順とリファレンス(操作・状態・データ・画面・CLI) |
187
+ | [docs/architecture.md](architecture.md) | 設計と規則(なぜそうするか・どこで守っているか) |
188
+ | [docs/chatgpt-sign-in.md](chatgpt-sign-in.md) | ChatGPT のサインインの設計 |
189
+ | [docs/publishing.md](publishing.md) | npm への公開のチェックリスト |
190
+ | docs/development.md(この文書) | 開発の手順と構成 |
191
+
192
+ 同じ説明を複数の文書に書かない(片方からリンクする)。確認作業の記録(どの幅・どのブラウザで確かめたか)は文書に書かず、
193
+ PR とタスクの変更の記録に残す。CLI のヘルプ(`src/cli/help.ts`)・API の説明(`src/server/api/manifest.ts`)は入口が変わったとき、
194
+ AI の手順が変わったときは `skills/p3/SKILL.md` と `src/cli/project.ts` の `AGENTS_SNIPPET` の両方を直す。