@playcraft/cli 0.1.52 → 0.1.53-beta

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 (400) hide show
  1. package/README.md +62 -3
  2. package/SKILLS_REGISTRY.md +149 -0
  3. package/dist/agent/local-backend.js +1 -1
  4. package/dist/auth/account-activation.js +157 -0
  5. package/dist/auth/messages.js +30 -0
  6. package/dist/cli-root-help.js +2 -0
  7. package/dist/commands/build-all.js +5 -19
  8. package/dist/commands/build-temp.js +26 -0
  9. package/dist/commands/build.js +15 -28
  10. package/dist/commands/create.js +26 -33
  11. package/dist/commands/login.js +84 -42
  12. package/dist/commands/platform-skills.generated.js +19 -0
  13. package/dist/commands/playable.js +53 -0
  14. package/dist/commands/preview-runtime.js +21 -0
  15. package/dist/commands/skills.js +4 -0
  16. package/dist/commands/tools-3d.js +11 -0
  17. package/dist/commands/tools-batch.js +113 -0
  18. package/dist/commands/tools-generation.js +6 -0
  19. package/dist/commands/tools.js +2 -0
  20. package/dist/commands/video.js +122 -0
  21. package/dist/commands/workspace-runtime.js +54 -0
  22. package/dist/commands/workspace.js +40 -0
  23. package/dist/config.js +59 -4
  24. package/dist/index.js +42 -3
  25. package/dist/preview-runtime/distribution.js +77 -0
  26. package/dist/project-skills/builtin-import.js +225 -0
  27. package/dist/project-skills/commands.js +77 -0
  28. package/dist/project-skills/lifecycle.js +28 -0
  29. package/dist/project-skills/local-run.js +112 -0
  30. package/dist/project-skills/local-store.js +221 -0
  31. package/dist/project-skills/messages.js +80 -0
  32. package/dist/project-skills/reconcile.js +62 -0
  33. package/dist/project-skills/remote-cache.js +51 -0
  34. package/dist/project-skills/validation.js +19 -0
  35. package/dist/recording/messages.js +40 -0
  36. package/dist/recording/project-digest.js +85 -0
  37. package/dist/recording/recorder.js +293 -0
  38. package/dist/recording/scenario.js +50 -0
  39. package/dist/remix/clone.js +2 -0
  40. package/dist/remix/init-template.js +2 -0
  41. package/dist/remix/pull.js +2 -0
  42. package/dist/remix/push.js +21 -1
  43. package/dist/skill-registry/client.js +345 -0
  44. package/dist/skill-registry/commands.js +180 -0
  45. package/dist/skill-registry/evaluation-client.js +156 -0
  46. package/dist/skill-registry/evaluation-commands.js +174 -0
  47. package/dist/skill-registry/messages.js +177 -0
  48. package/dist/skill-registry/package.js +275 -0
  49. package/dist/skill-registry/platform-package.js +100 -0
  50. package/dist/utils/agent-api-client.js +210 -30
  51. package/dist/utils/environment-endpoints.js +17 -0
  52. package/dist/utils/error-diagnostics.js +20 -0
  53. package/dist/utils/playcraft-http-client.js +6 -4
  54. package/dist/utils/tool-operation-journal.js +124 -0
  55. package/dist/utils/video-evidence-git.js +81 -0
  56. package/dist/video-replication/client.js +234 -0
  57. package/dist/video-replication/comparison-evidence.js +149 -0
  58. package/dist/video-replication/comparison-files.js +57 -0
  59. package/dist/video-replication/comparison-log.js +72 -0
  60. package/dist/video-replication/comparison-messages.js +104 -0
  61. package/dist/video-replication/comparison-output.js +63 -0
  62. package/dist/video-replication/comparison-preflight.js +66 -0
  63. package/dist/video-replication/comparison.js +230 -0
  64. package/dist/video-replication/diagnostics.js +41 -0
  65. package/dist/video-replication/evidence.js +165 -0
  66. package/dist/video-replication/media.js +112 -0
  67. package/dist/video-replication/messages.js +97 -0
  68. package/dist/workspace/messages.js +67 -0
  69. package/dist/workspace/transfer-client.js +237 -0
  70. package/dist/workspace/transfer-errors.js +48 -0
  71. package/dist/workspace-runtime/batch/content-changes.js +30 -0
  72. package/dist/workspace-runtime/batch/control.js +86 -0
  73. package/dist/workspace-runtime/batch/deliver.js +173 -0
  74. package/dist/workspace-runtime/batch/freeze.js +101 -0
  75. package/dist/workspace-runtime/batch/generate.js +249 -0
  76. package/dist/workspace-runtime/batch/git.js +40 -0
  77. package/dist/workspace-runtime/batch/occupancy.js +8 -0
  78. package/dist/workspace-runtime/batch/policy.js +70 -0
  79. package/dist/workspace-runtime/batch/prepare.js +317 -0
  80. package/dist/workspace-runtime/batch/processes.js +72 -0
  81. package/dist/workspace-runtime/batch/records.js +113 -0
  82. package/dist/workspace-runtime/batch/routes.js +61 -0
  83. package/dist/workspace-runtime/batch/source-candidate.js +86 -0
  84. package/dist/workspace-runtime/batch/source-capture.js +146 -0
  85. package/dist/workspace-runtime/batch/source-failure.js +43 -0
  86. package/dist/workspace-runtime/batch/source-publish.js +130 -0
  87. package/dist/workspace-runtime/codex/app-server.js +1065 -0
  88. package/dist/workspace-runtime/codex/compact.js +46 -0
  89. package/dist/workspace-runtime/codex/config-toml.js +107 -0
  90. package/dist/workspace-runtime/codex/delivery-tools.js +144 -0
  91. package/dist/workspace-runtime/codex/jsonrpc-stdio.js +145 -0
  92. package/dist/workspace-runtime/codex/launcher-client.js +177 -0
  93. package/dist/workspace-runtime/codex/loopback.js +146 -0
  94. package/dist/workspace-runtime/codex/mcp-config.js +39 -0
  95. package/dist/workspace-runtime/codex/model-broker.js +263 -0
  96. package/dist/workspace-runtime/codex/native-adapter.js +9 -0
  97. package/dist/workspace-runtime/codex/permissions.js +79 -0
  98. package/dist/workspace-runtime/codex/thread-image.js +38 -0
  99. package/dist/workspace-runtime/codex/tool-response.js +10 -0
  100. package/dist/workspace-runtime/codex/ui-instructions.js +4 -0
  101. package/dist/workspace-runtime/codex/ui-tools.js +203 -0
  102. package/dist/workspace-runtime/codex/work-mode.js +15 -0
  103. package/dist/workspace-runtime/main.js +10 -0
  104. package/dist/workspace-runtime/persistence/journal.js +365 -0
  105. package/dist/workspace-runtime/persistence/native-subagents.js +162 -0
  106. package/dist/workspace-runtime/persistence/sqlite-client.js +77 -0
  107. package/dist/workspace-runtime/persistence/sqlite-worker.js +1161 -0
  108. package/dist/workspace-runtime/persistence/stopped-execution.js +77 -0
  109. package/dist/workspace-runtime/previews/diagnostics.js +44 -0
  110. package/dist/workspace-runtime/previews/output.js +36 -0
  111. package/dist/workspace-runtime/previews/publish.js +283 -0
  112. package/dist/workspace-runtime/previews/runtime-preview.js +251 -0
  113. package/dist/workspace-runtime/previews/single-file.js +43 -0
  114. package/dist/workspace-runtime/processes/managed-writes.js +69 -0
  115. package/dist/workspace-runtime/serve.js +441 -0
  116. package/dist/workspace-runtime/server/accept-operation.js +61 -0
  117. package/dist/workspace-runtime/server/asset-transfers.js +63 -0
  118. package/dist/workspace-runtime/server/auth.js +21 -0
  119. package/dist/workspace-runtime/server/connectivity.js +211 -0
  120. package/dist/workspace-runtime/server/desktop-host.js +429 -0
  121. package/dist/workspace-runtime/server/desktop-preview-config.js +81 -0
  122. package/dist/workspace-runtime/server/desktop-preview-service.js +157 -0
  123. package/dist/workspace-runtime/server/desktop-preview-static.js +53 -0
  124. package/dist/workspace-runtime/server/desktop-preview.js +189 -0
  125. package/dist/workspace-runtime/server/dispatch.js +1655 -0
  126. package/dist/workspace-runtime/server/endpoints.js +21 -0
  127. package/dist/workspace-runtime/server/execution-group.js +90 -0
  128. package/dist/workspace-runtime/server/http.js +1339 -0
  129. package/dist/workspace-runtime/server/lock.js +53 -0
  130. package/dist/workspace-runtime/server/operation-record.js +33 -0
  131. package/dist/workspace-runtime/server/rfb-watch-gate.js +168 -0
  132. package/dist/workspace-runtime/server/session-restore.js +84 -0
  133. package/dist/workspace-runtime/server/source-uploader.js +138 -0
  134. package/dist/workspace-runtime/server/submit-operation.js +41 -0
  135. package/dist/workspace-runtime/server/terminal-host.js +366 -0
  136. package/dist/workspace-runtime/server/types.js +1 -0
  137. package/dist/workspace-runtime/server/workspace-transfer.js +168 -0
  138. package/dist/workspace-runtime/verify-artifact.js +59 -0
  139. package/dist/workspace-runtime/workspaces/append-only-log.js +62 -0
  140. package/dist/workspace-runtime/workspaces/archive.js +207 -0
  141. package/dist/workspace-runtime/workspaces/artifact-events.js +55 -0
  142. package/dist/workspace-runtime/workspaces/artifact-files.js +199 -0
  143. package/dist/workspace-runtime/workspaces/artifact-receipts.js +89 -0
  144. package/dist/workspace-runtime/workspaces/artifacts.js +282 -0
  145. package/dist/workspace-runtime/workspaces/asset-library-import.js +387 -0
  146. package/dist/workspace-runtime/workspaces/asset-publication-access.js +25 -0
  147. package/dist/workspace-runtime/workspaces/asset-transfer-dependencies.js +81 -0
  148. package/dist/workspace-runtime/workspaces/asset-transfer-publish.js +438 -0
  149. package/dist/workspace-runtime/workspaces/asset-transfer-storage.js +389 -0
  150. package/dist/workspace-runtime/workspaces/attachment-content.js +73 -0
  151. package/dist/workspace-runtime/workspaces/attachments.js +185 -0
  152. package/dist/workspace-runtime/workspaces/batch-commit.js +142 -0
  153. package/dist/workspace-runtime/workspaces/binary-content.js +65 -0
  154. package/dist/workspace-runtime/workspaces/binary-write.js +117 -0
  155. package/dist/workspace-runtime/workspaces/cli-context.js +23 -0
  156. package/dist/workspace-runtime/workspaces/cli-credentials.js +115 -0
  157. package/dist/workspace-runtime/workspaces/composer-context.js +147 -0
  158. package/dist/workspace-runtime/workspaces/context-error.js +2 -0
  159. package/dist/workspace-runtime/workspaces/delivery-build.js +331 -0
  160. package/dist/workspace-runtime/workspaces/delivery-store.js +168 -0
  161. package/dist/workspace-runtime/workspaces/delivery.js +64 -0
  162. package/dist/workspace-runtime/workspaces/dependencies.js +279 -0
  163. package/dist/workspace-runtime/workspaces/developer-command.js +98 -0
  164. package/dist/workspace-runtime/workspaces/directories.js +132 -0
  165. package/dist/workspace-runtime/workspaces/directory-access.js +37 -0
  166. package/dist/workspace-runtime/workspaces/directory-attachments.js +245 -0
  167. package/dist/workspace-runtime/workspaces/directory-create.js +57 -0
  168. package/dist/workspace-runtime/workspaces/directory-maintenance.js +111 -0
  169. package/dist/workspace-runtime/workspaces/directory-mutations.js +238 -0
  170. package/dist/workspace-runtime/workspaces/directory-revisions.js +56 -0
  171. package/dist/workspace-runtime/workspaces/directory-stats.js +49 -0
  172. package/dist/workspace-runtime/workspaces/disk-snapshot.js +31 -0
  173. package/dist/workspace-runtime/workspaces/empty-template.js +42 -0
  174. package/dist/workspace-runtime/workspaces/file-content.js +48 -0
  175. package/dist/workspace-runtime/workspaces/files-search.js +116 -0
  176. package/dist/workspace-runtime/workspaces/files.js +150 -0
  177. package/dist/workspace-runtime/workspaces/git-credential-broker.js +312 -0
  178. package/dist/workspace-runtime/workspaces/git-credential-helper.js +68 -0
  179. package/dist/workspace-runtime/workspaces/git-direct-store.js +155 -0
  180. package/dist/workspace-runtime/workspaces/git.js +670 -0
  181. package/dist/workspace-runtime/workspaces/instructions.js +56 -0
  182. package/dist/workspace-runtime/workspaces/json5-edit.js +313 -0
  183. package/dist/workspace-runtime/workspaces/library-attachments.js +268 -0
  184. package/dist/workspace-runtime/workspaces/operation-log.js +23 -0
  185. package/dist/workspace-runtime/workspaces/optional-platform-skills.js +14 -0
  186. package/dist/workspace-runtime/workspaces/parameter-agent-inputs.js +97 -0
  187. package/dist/workspace-runtime/workspaces/parameter-agent-protocol.js +40 -0
  188. package/dist/workspace-runtime/workspaces/parameter-agent-store.js +58 -0
  189. package/dist/workspace-runtime/workspaces/parameter-agent.js +284 -0
  190. package/dist/workspace-runtime/workspaces/parameter-assets.js +189 -0
  191. package/dist/workspace-runtime/workspaces/parameters.js +329 -0
  192. package/dist/workspace-runtime/workspaces/prepare.js +278 -0
  193. package/dist/workspace-runtime/workspaces/registry.js +251 -0
  194. package/dist/workspace-runtime/workspaces/remix-references.js +301 -0
  195. package/dist/workspace-runtime/workspaces/revisions.js +31 -0
  196. package/dist/workspace-runtime/workspaces/session-image.js +104 -0
  197. package/dist/workspace-runtime/workspaces/shared-git.js +40 -0
  198. package/dist/workspace-runtime/workspaces/skill-artifact-loader.js +95 -0
  199. package/dist/workspace-runtime/workspaces/skills.js +191 -0
  200. package/dist/workspace-runtime/workspaces/theme-asset-index.js +157 -0
  201. package/dist/workspace-runtime/workspaces/transfer-quota.js +69 -0
  202. package/dist/workspace-runtime/workspaces/transfer.js +471 -0
  203. package/dist/workspace-runtime/workspaces/turn-changes.js +75 -0
  204. package/dist/workspace-runtime/workspaces/video-attachments.js +49 -0
  205. package/package.json +15 -5
  206. package/project-template/.claude/skills/playcraft-replica-validation/SKILL.md +25 -0
  207. package/project-template/.claude/skills/playcraft-replica-validation/references/contracts.md +79 -0
  208. package/project-template/.claude/skills/playcraft-video-understanding/SKILL.md +29 -0
  209. package/project-template/.claude/skills/playcraft-video-understanding/references/contracts.md +37 -0
  210. package/project-template-v2/.claude/agents/artist.md +82 -0
  211. package/project-template-v2/.claude/agents/developer.md +153 -0
  212. package/project-template-v2/.claude/agents/game-designer.md +264 -0
  213. package/project-template-v2/.claude/agents/refs/artist-art-style-catalog.md +533 -0
  214. package/project-template-v2/.claude/agents/refs/artist-color-audio-recipes.md +153 -0
  215. package/project-template-v2/.claude/agents/refs/artist-dimension-axis.md +27 -0
  216. package/project-template-v2/.claude/agents/refs/artist-master-composite-recipes.md +208 -0
  217. package/project-template-v2/.claude/agents/refs/atom-skill-library.md +81 -0
  218. package/project-template-v2/.claude/agents/refs/developer-impl-cookbook.md +432 -0
  219. package/project-template-v2/.claude/agents/refs/framework-5-component-filter.md +252 -0
  220. package/project-template-v2/.claude/agents/refs/framework-game-feel-juice.md +266 -0
  221. package/project-template-v2/.claude/agents/refs/framework-mda.md +147 -0
  222. package/project-template-v2/.claude/agents/refs/game-designer-gameplay-sufficiency.md +123 -0
  223. package/project-template-v2/.claude/agents/refs/ta-3d-flip-recipe.md +88 -0
  224. package/project-template-v2/.claude/agents/refs/ta-atlas-deliverable-standard.md +67 -0
  225. package/project-template-v2/.claude/agents/refs/ta-batch-pipeline-recipes.md +120 -0
  226. package/project-template-v2/.claude/agents/refs/ta-image-generation-detail.md +300 -0
  227. package/project-template-v2/.claude/agents/refs/ta-image-ops-reference.md +495 -0
  228. package/project-template-v2/.claude/agents/refs/ta-pipeline-cookbook.md +1141 -0
  229. package/project-template-v2/.claude/agents/refs/ta-tools-reference.md +111 -0
  230. package/project-template-v2/.claude/agents/refs/ta-vfx-preset-catalog.md +365 -0
  231. package/project-template-v2/.claude/agents/refs/threejs-cannon-pitfalls.md +412 -0
  232. package/project-template-v2/.claude/agents/reviewer.md +75 -0
  233. package/project-template-v2/.claude/agents/technical-artist.md +86 -0
  234. package/project-template-v2/.claude/hooks/snapshot-milestone.mjs +243 -0
  235. package/project-template-v2/.claude/hooks/user-prompt.mjs +133 -0
  236. package/project-template-v2/.claude/settings.json +33 -0
  237. package/project-template-v2/.claude/skills/brainstorming/SKILL.md +161 -0
  238. package/project-template-v2/.claude/skills/brainstorming/scripts/frame-template.html +270 -0
  239. package/project-template-v2/.claude/skills/brainstorming/scripts/helper.js +177 -0
  240. package/project-template-v2/.claude/skills/brainstorming/scripts/server.cjs +354 -0
  241. package/project-template-v2/.claude/skills/brainstorming/scripts/start-server.sh +148 -0
  242. package/project-template-v2/.claude/skills/brainstorming/scripts/stop-server.sh +56 -0
  243. package/project-template-v2/.claude/skills/brainstorming/scripts/wait-for-selection.sh +62 -0
  244. package/project-template-v2/.claude/skills/brainstorming/spec-document-reviewer-prompt.md +49 -0
  245. package/project-template-v2/.claude/skills/brainstorming/visual-companion.md +309 -0
  246. package/project-template-v2/.claude/skills/playcraft-ad-psychology/SKILL.md +182 -0
  247. package/project-template-v2/.claude/skills/playcraft-art-style-guide/SKILL.md +123 -0
  248. package/project-template-v2/.claude/skills/playcraft-asset-state-sheet/SKILL.md +205 -0
  249. package/project-template-v2/.claude/skills/playcraft-audio-generation/SKILL.md +280 -0
  250. package/project-template-v2/.claude/skills/playcraft-batch-pipeline/SKILL.md +184 -0
  251. package/project-template-v2/.claude/skills/playcraft-build-optimizer/SKILL.md +306 -0
  252. package/project-template-v2/.claude/skills/playcraft-image-generation/SKILL.md +370 -0
  253. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs +123 -0
  254. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs +254 -0
  255. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs +333 -0
  256. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs +95 -0
  257. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs +118 -0
  258. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/process-batch.template.mjs +136 -0
  259. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/prompt-cookbook.md +397 -0
  260. package/project-template-v2/.claude/skills/playcraft-image-generation/reference/validate-sprite-sheet.template.mjs +296 -0
  261. package/project-template-v2/.claude/skills/playcraft-image-ops/SKILL.md +122 -0
  262. package/project-template-v2/.claude/skills/playcraft-image-processing/SKILL.md +219 -0
  263. package/project-template-v2/.claude/skills/playcraft-masking/SKILL.md +373 -0
  264. package/project-template-v2/.claude/skills/playcraft-playable-optimization/SKILL.md +161 -0
  265. package/project-template-v2/.claude/skills/playcraft-research/SKILL.md +215 -0
  266. package/project-template-v2/.claude/skills/playcraft-skill-recommender/SKILL.md +382 -0
  267. package/project-template-v2/.claude/skills/playcraft-sprite-generation/SKILL.md +423 -0
  268. package/project-template-v2/.claude/skills/playcraft-sprite-remix/SKILL.md +158 -0
  269. package/project-template-v2/.claude/skills/playcraft-sprite-sheet/SKILL.md +100 -0
  270. package/project-template-v2/.claude/skills/playcraft-storyboard/SKILL.md +167 -0
  271. package/project-template-v2/.claude/skills/playcraft-style-qa/SKILL.md +270 -0
  272. package/project-template-v2/.claude/skills/playcraft-text-rendering/SKILL.md +236 -0
  273. package/project-template-v2/.claude/skills/playcraft-vfx-animation/SKILL.md +130 -0
  274. package/project-template-v2/.claude/skills/playwright-cli/SKILL.md +390 -0
  275. package/project-template-v2/.claude/skills/playwright-cli/references/element-attributes.md +23 -0
  276. package/project-template-v2/.claude/skills/playwright-cli/references/playwright-tests.md +39 -0
  277. package/project-template-v2/.claude/skills/playwright-cli/references/request-mocking.md +87 -0
  278. package/project-template-v2/.claude/skills/playwright-cli/references/running-code.md +240 -0
  279. package/project-template-v2/.claude/skills/playwright-cli/references/session-management.md +226 -0
  280. package/project-template-v2/.claude/skills/playwright-cli/references/spec-driven-testing.md +308 -0
  281. package/project-template-v2/.claude/skills/playwright-cli/references/storage-state.md +275 -0
  282. package/project-template-v2/.claude/skills/playwright-cli/references/test-generation.md +134 -0
  283. package/project-template-v2/.claude/skills/playwright-cli/references/tracing.md +142 -0
  284. package/project-template-v2/.claude/skills/playwright-cli/references/video-recording.md +153 -0
  285. package/project-template-v2/.claude/skills/session-analyzer/SKILL.md +386 -0
  286. package/project-template-v2/.claude/skills/session-analyzer/scripts/execution-breakdown.mjs +182 -0
  287. package/project-template-v2/.claude/skills/session-analyzer/scripts/find-turns.mjs +72 -0
  288. package/project-template-v2/.claude/skills/session-analyzer/scripts/heavy-output.mjs +121 -0
  289. package/project-template-v2/.claude/skills/session-analyzer/scripts/resolve-session.mjs +102 -0
  290. package/project-template-v2/.claude/skills/session-analyzer/scripts/subagent-stats.mjs +127 -0
  291. package/project-template-v2/.claude/skills/session-analyzer/scripts/subagent-tool-timeline.mjs +106 -0
  292. package/project-template-v2/.claude/skills/session-analyzer/scripts/time-gaps.mjs +128 -0
  293. package/project-template-v2/.claude/skills/session-analyzer/scripts/turn-timeline.mjs +67 -0
  294. package/project-template-v2/.claude/snapshot.mjs +263 -0
  295. package/project-template-v2/.playcraft/skills.lock.json +152 -0
  296. package/project-template-v2/CLAUDE.md +146 -0
  297. package/project-template-v2/assets/audio/bgm/.gitkeep +0 -0
  298. package/project-template-v2/assets/audio/sfx/.gitkeep +0 -0
  299. package/project-template-v2/assets/bundles/.gitkeep +0 -0
  300. package/project-template-v2/assets/images/bg/.gitkeep +0 -0
  301. package/project-template-v2/assets/images/reference/.gitkeep +0 -0
  302. package/project-template-v2/assets/images/storyboard/.gitkeep +0 -0
  303. package/project-template-v2/assets/images/tiles/.gitkeep +0 -0
  304. package/project-template-v2/assets/images/ui/.gitkeep +0 -0
  305. package/project-template-v2/assets/images/vfx/.gitkeep +0 -0
  306. package/project-template-v2/assets/models/.gitkeep +0 -0
  307. package/project-template-v2/docs/harness/iteration-1/context-flow.md +254 -0
  308. package/project-template-v2/docs/harness/iteration-1/generate-flow.md +91 -0
  309. package/project-template-v2/docs/harness/iteration-1/ideate-flow.md +214 -0
  310. package/project-template-v2/docs/harness/iteration-1/optimize-flow.md +75 -0
  311. package/project-template-v2/docs/harness/iteration-1/wrapup-flow.md +63 -0
  312. package/project-template-v2/docs/harness/iteration-2/context-flow.md +223 -0
  313. package/project-template-v2/docs/harness/iteration-2/generate-flow.md +129 -0
  314. package/project-template-v2/docs/harness/iteration-2/ideate-flow.md +267 -0
  315. package/project-template-v2/docs/harness/iteration-2/optimize-flow.md +164 -0
  316. package/project-template-v2/docs/harness/iteration-2/wrapup-flow.md +115 -0
  317. package/project-template-v2/docs/harness/orchestrator-flow.md +364 -0
  318. package/project-template-v2/docs/project-state.json +60 -0
  319. package/project-template-v2/docs/project-state.md +72 -0
  320. package/project-template-v2/docs/standards/README.md +225 -0
  321. package/project-template-v2/docs/standards/agent-behavior-standards.md +174 -0
  322. package/project-template-v2/docs/standards/artifacts/design-brief.md +19 -0
  323. package/project-template-v2/docs/standards/artifacts/design.md +22 -0
  324. package/project-template-v2/docs/standards/artifacts/game-code.md +41 -0
  325. package/project-template-v2/docs/standards/artifacts/todo-list.md +41 -0
  326. package/project-template-v2/docs/standards/iter1-agent-behavior-standards.md +343 -0
  327. package/project-template-v2/game/index.ts +18 -0
  328. package/project-template-v2/globals.d.ts +51 -0
  329. package/project-template-v2/index.css +34 -0
  330. package/project-template-v2/index.html +18 -0
  331. package/project-template-v2/main.ts +9 -0
  332. package/project-template-v2/package.json +46 -0
  333. package/project-template-v2/skills/_shared/scripts/dispatch-clear.mjs +31 -0
  334. package/project-template-v2/skills/_shared/scripts/dispatch-set.mjs +86 -0
  335. package/project-template-v2/skills/_shared/scripts/dod-check.mjs +153 -0
  336. package/project-template-v2/skills/_shared/scripts/handoff-append.mjs +70 -0
  337. package/project-template-v2/skills/_shared/scripts/lib/validator-artifacts.mjs +91 -0
  338. package/project-template-v2/skills/_shared/scripts/pipeline/dod-config.mjs +131 -0
  339. package/project-template-v2/skills/_shared/scripts/pipeline/index.mjs +80 -0
  340. package/project-template-v2/skills/_shared/scripts/pipeline/iteration-1-core.mjs +90 -0
  341. package/project-template-v2/skills/_shared/scripts/pipeline/iteration-2-wrap.mjs +93 -0
  342. package/project-template-v2/skills/_shared/scripts/pipeline/iteration-3-visual.mjs +23 -0
  343. package/project-template-v2/skills/_shared/scripts/render-project-state.mjs +230 -0
  344. package/project-template-v2/skills/_shared/scripts/state-advance-stage.mjs +58 -0
  345. package/project-template-v2/skills/_shared/scripts/state-get.mjs +339 -0
  346. package/project-template-v2/skills/_shared/scripts/state-handoff.mjs +39 -0
  347. package/project-template-v2/skills/_shared/scripts/state-set.mjs +94 -0
  348. package/project-template-v2/skills/_shared/scripts/state-store.mjs +783 -0
  349. package/project-template-v2/skills/_shared/scripts/todo-add.mjs +88 -0
  350. package/project-template-v2/skills/_shared/scripts/todo-get.mjs +130 -0
  351. package/project-template-v2/skills/_shared/scripts/todo-remove.mjs +33 -0
  352. package/project-template-v2/skills/_shared/scripts/todo-set.mjs +47 -0
  353. package/project-template-v2/skills/_shared/scripts/verify-asset-code-sync.mjs +268 -0
  354. package/project-template-v2/skills/_shared/scripts/verify-env.mjs +285 -0
  355. package/project-template-v2/skills/_shared/scripts/verify-placeholders.mjs +161 -0
  356. package/project-template-v2/skills/playable-autoplay/SKILL.md +176 -0
  357. package/project-template-v2/skills/playable-autoplay/agents/openai.yaml +4 -0
  358. package/project-template-v2/skills/playable-debug/SKILL.md +116 -0
  359. package/project-template-v2/skills/playable-debug/agents/openai.yaml +4 -0
  360. package/project-template-v2/skills/playable-debug/references/debug-config.md +40 -0
  361. package/project-template-v2/skills/playable-record/SKILL.md +140 -0
  362. package/project-template-v2/skills/playable-record/scripts/lib/dev-server.mjs +104 -0
  363. package/project-template-v2/skills/playable-record/scripts/lib/record-audio-bridge.js +141 -0
  364. package/project-template-v2/skills/playable-record/scripts/record-playable.mjs +425 -0
  365. package/project-template-v2/skills/playable-record/scripts/verify-contract.mjs +261 -0
  366. package/project-template-v2/skills/playable-record/scripts/verify-firstwin.mjs +398 -0
  367. package/project-template-v2/skills/playable-record/scripts/verify-fusion.mjs +322 -0
  368. package/project-template-v2/skills/playable-record/scripts/verify-lifecycle.mjs +105 -0
  369. package/project-template-v2/skills/playable-record/scripts/verify-vlm-video.mjs +230 -0
  370. package/project-template-v2/skills/playable-validate/SKILL.md +61 -0
  371. package/project-template-v2/skills/playable-validate/validation-rules.md +14 -0
  372. package/project-template-v2/skills/playable-verify-ui/SKILL.md +63 -0
  373. package/project-template-v2/skills/playable-verify-ui/scripts/lib/__init__.py +1 -0
  374. package/project-template-v2/skills/playable-verify-ui/scripts/lib/config_expr.js +218 -0
  375. package/project-template-v2/skills/playable-verify-ui/scripts/lib/node_utils.js +51 -0
  376. package/project-template-v2/skills/playable-verify-ui/scripts/lib/profile_loader.py +59 -0
  377. package/project-template-v2/skills/playable-verify-ui/scripts/lib/report.py +106 -0
  378. package/project-template-v2/skills/playable-verify-ui/scripts/lib/runtime_contract.js +116 -0
  379. package/project-template-v2/skills/playable-verify-ui/scripts/verify_fetch_antipatterns.py +59 -0
  380. package/project-template-v2/skills/playable-verify-ui/scripts/verify_hardcoded_layout.js +64 -0
  381. package/project-template-v2/skills/playable-verify-ui/scripts/verify_runtime_contract.js +58 -0
  382. package/project-template-v2/skills/playable-verify-ui/scripts/verify_text_overlap.py +333 -0
  383. package/project-template-v2/ta-workspace/scripts/.gitkeep +0 -0
  384. package/project-template-v2/tsconfig.json +20 -0
  385. package/project-template-v2/vite.config.ts +27 -0
  386. package/project-templates/batch-locks/phaser.yaml +922 -0
  387. package/project-templates/batch-locks/threejs.yaml +978 -0
  388. package/project-templates/empty/AGENTS.md +41 -0
  389. package/project-templates/empty/gitignore +33 -0
  390. package/templates/preview-runtime/v1/README.md +71 -0
  391. package/templates/preview-runtime/v1/build-preview.mjs +1324 -0
  392. package/templates/preview-runtime/v1/manifest.json +17 -0
  393. package/templates/preview-runtime/v1/release-guard.mjs +87 -0
  394. package/templates/preview-runtime/v1/runtime.d.mts +3 -0
  395. package/templates/preview-runtime/v1/runtime.d.ts +3 -0
  396. package/templates/preview-runtime/v1/runtime.mjs +1121 -0
  397. package/templates/preview-runtime/v1/types/adapters.d.ts +26 -0
  398. package/templates/preview-runtime/v1/types/preview.d.ts +23 -0
  399. package/templates/preview-runtime/v1/types/protocol.d.ts +94 -0
  400. package/templates/preview-runtime/v1/types/runtime.d.ts +14 -0
@@ -0,0 +1,211 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import { z } from 'zod';
3
+ import { PLATFORM_ROUTES, modelConnectivityPath, platformEndpoint, } from '@playcraft/common/cloud-workspace/runtime';
4
+ const PROBE_TIMEOUT_MS = 4_000;
5
+ // Issuance performs current authority reads and signing, rather than an endpoint echo.
6
+ const CREDENTIAL_TIMEOUT_MS = 10_000;
7
+ const CACHE_MS = 15_000;
8
+ const CREDENTIAL_RENEW_BEFORE_MS = 30_000;
9
+ const MAX_RESPONSE_BYTES = 16 * 1024;
10
+ const credentialSchema = z.object({
11
+ token: z.string().min(1), expiresAt: z.string().datetime(),
12
+ configId: z.string().uuid(), model: z.string().min(1).max(128),
13
+ claims: z.object({
14
+ environment: z.string(), userId: z.string(), workspaceId: z.string(), runtimeId: z.string(),
15
+ generation: z.number().int(), runtimeEpoch: z.number().int(),
16
+ }),
17
+ });
18
+ const caches = new WeakMap();
19
+ const ready = () => ({ status: 'ready' });
20
+ const unavailable = (reason) => ({ status: 'unavailable', reason });
21
+ function snapshot(state, workspaceId) {
22
+ let nativeReady = false;
23
+ try {
24
+ nativeReady = Boolean(state.native?.ready());
25
+ }
26
+ catch { /* A failed adapter stays unavailable. */ }
27
+ const { publicBaseUrl, controlToken, environment, userId, runtimeId, generation } = state.config;
28
+ return { publicBaseUrl, controlToken, environment, userId, runtimeId, generation,
29
+ runtimeEpoch: state.runtimeEpoch, workspaceId, nativeReady, destroyed: state.journal.destroyed(),
30
+ registered: state.config.workspaceMode !== 'multi' || Boolean(state.journal.getWorkspace(workspaceId)) };
31
+ }
32
+ function safeEndpoint(value) {
33
+ const url = new URL(value);
34
+ if (url.username || url.password || url.search || url.hash || /[%\\]/.test(url.pathname)
35
+ || (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
36
+ throw new Error('insecure_endpoint');
37
+ }
38
+ return url;
39
+ }
40
+ async function responseJson(response) {
41
+ const reader = response.body?.getReader();
42
+ if (!reader)
43
+ throw new Error('invalid_probe_response');
44
+ const chunks = [];
45
+ let size = 0;
46
+ try {
47
+ while (true) {
48
+ const item = await reader.read();
49
+ if (item.done)
50
+ break;
51
+ size += item.value.byteLength;
52
+ if (size > MAX_RESPONSE_BYTES)
53
+ throw new Error('invalid_probe_response');
54
+ chunks.push(item.value);
55
+ }
56
+ return JSON.parse(Buffer.concat(chunks).toString('utf8'));
57
+ }
58
+ finally {
59
+ await reader.cancel().catch(() => undefined);
60
+ reader.releaseLock();
61
+ }
62
+ }
63
+ async function requestProbe(target, init, options = {}) {
64
+ const { credentials = false, serverFailureReason = 'endpoint_unreachable' } = options;
65
+ const signal = AbortSignal.timeout(credentials ? CREDENTIAL_TIMEOUT_MS : PROBE_TIMEOUT_MS);
66
+ try {
67
+ const response = await fetch(target, { ...init, redirect: 'error', signal });
68
+ if (!response.ok) {
69
+ const offline = response.headers.has('ngrok-error-code');
70
+ const rejected = response.status === 401 || response.status === 403;
71
+ let reason = rejected ? 'endpoint_rejected' : offline ? 'endpoint_offline'
72
+ : response.status >= 500 ? serverFailureReason : 'endpoint_unreachable';
73
+ if (credentials && !offline && !rejected) {
74
+ const body = await responseJson(response).catch(() => undefined);
75
+ if (signal.aborted)
76
+ return { state: unavailable('endpoint_timeout') };
77
+ if (body && typeof body === 'object' && 'reason' in body && body.reason === 'model_config_required')
78
+ reason = 'model_config_required';
79
+ }
80
+ else
81
+ await response.body?.cancel().catch(() => undefined);
82
+ return { state: unavailable(reason) };
83
+ }
84
+ let body;
85
+ try {
86
+ body = await responseJson(response);
87
+ }
88
+ catch {
89
+ return { state: unavailable(signal.aborted ? 'endpoint_timeout' : 'invalid_probe_response') };
90
+ }
91
+ return { state: ready(), body };
92
+ }
93
+ catch {
94
+ return { state: unavailable(signal.aborted ? 'endpoint_timeout' : 'endpoint_unreachable') };
95
+ }
96
+ }
97
+ function echoMatches(body, expected) {
98
+ return Boolean(body && typeof body === 'object' && !Array.isArray(body)
99
+ && Object.entries(expected).every(([key, value]) => body[key] === value));
100
+ }
101
+ function scope(config) {
102
+ return { runtimeId: config.runtimeId, environment: config.environment, workspaceId: config.workspaceId,
103
+ generation: config.generation, runtimeEpoch: config.runtimeEpoch };
104
+ }
105
+ function entrance(config, route) {
106
+ return safeEndpoint(platformEndpoint(config.publicBaseUrl, route));
107
+ }
108
+ async function callbackProbe(config) {
109
+ if (!config.publicBaseUrl)
110
+ return unavailable('endpoint_not_configured');
111
+ let endpoint;
112
+ try {
113
+ endpoint = entrance(config, PLATFORM_ROUTES.eventsProbe);
114
+ }
115
+ catch {
116
+ return unavailable('insecure_endpoint');
117
+ }
118
+ const nonce = randomUUID();
119
+ const response = await requestProbe(endpoint, {
120
+ method: 'POST', headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
121
+ body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation,
122
+ runtimeEpoch: config.runtimeEpoch, workspaceId: config.workspaceId, nonce }),
123
+ });
124
+ if (response.state.status !== 'ready')
125
+ return response.state;
126
+ return echoMatches(response.body, { service: 'playcraft-runtime', ...scope(config), nonce }) ? ready() : unavailable('invalid_probe_response');
127
+ }
128
+ async function modelProxyProbe(config, entry) {
129
+ if (!config.publicBaseUrl)
130
+ return unavailable('endpoint_not_configured');
131
+ let credentialEndpoint;
132
+ try {
133
+ credentialEndpoint = entrance(config, PLATFORM_ROUTES.modelCredentials);
134
+ entrance(config, PLATFORM_ROUTES.modelProxy);
135
+ }
136
+ catch {
137
+ return unavailable('insecure_endpoint');
138
+ }
139
+ if (entry.credential && Date.parse(entry.credential.expiresAt) <= Date.now() + CREDENTIAL_RENEW_BEFORE_MS)
140
+ entry.credential = undefined;
141
+ const reusedCredential = Boolean(entry.credential);
142
+ if (!entry.credential) {
143
+ const response = await requestProbe(credentialEndpoint, {
144
+ method: 'POST', headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
145
+ body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation, runtimeEpoch: config.runtimeEpoch, workspaceId: config.workspaceId }),
146
+ }, { credentials: true, serverFailureReason: 'model_credential_unavailable' });
147
+ if (response.state.status !== 'ready')
148
+ return response.state;
149
+ const parsed = credentialSchema.safeParse(response.body);
150
+ if (!parsed.success || !echoMatches(parsed.data.claims, { ...scope(config), userId: config.userId })
151
+ || Date.parse(parsed.data.expiresAt) <= Date.now() + 1_000)
152
+ return unavailable('invalid_probe_response');
153
+ entry.credential = parsed.data;
154
+ }
155
+ const credential = entry.credential;
156
+ const nonce = randomUUID();
157
+ const target = new URL(platformEndpoint(config.publicBaseUrl, modelConnectivityPath(credential.configId)));
158
+ target.searchParams.set('nonce', nonce);
159
+ const result = await requestProbe(target, { method: 'GET', headers: { authorization: `Bearer ${credential.token}`, 'playcraft-env': config.environment } }, { serverFailureReason: 'model_proxy_unavailable' });
160
+ if (result.state.reason === 'endpoint_rejected') {
161
+ entry.credential = undefined;
162
+ // A restore can invalidate an otherwise unexpired credential. Reissue once for this
163
+ // read-only echo; a fresh refusal remains a refusal. Model turns are never replayed here.
164
+ if (reusedCredential)
165
+ return modelProxyProbe(config, entry);
166
+ }
167
+ if (result.state.status !== 'ready')
168
+ return result.state;
169
+ return echoMatches(result.body, { service: 'playcraft-model-proxy', ...scope(config), configId: credential.configId, nonce })
170
+ ? ready() : unavailable('invalid_probe_response');
171
+ }
172
+ async function probe(config, entry) {
173
+ if (config.destroyed || !config.registered) {
174
+ const state = unavailable(config.destroyed ? 'runtime_destroyed' : 'workspace_not_registered');
175
+ return { ...scope(config), checkedAt: new Date().toISOString(), callback: state, modelProxy: state, conversation: state };
176
+ }
177
+ const [callback, modelProxy] = await Promise.all([callbackProbe(config), modelProxyProbe(config, entry)]);
178
+ const conversation = !config.nativeReady ? unavailable('adapter_not_started')
179
+ : callback.status !== 'ready' ? unavailable('callback_unavailable')
180
+ : modelProxy.status !== 'ready' ? unavailable('model_proxy_unavailable') : ready();
181
+ return { ...scope(config), checkedAt: new Date().toISOString(), callback, modelProxy, conversation };
182
+ }
183
+ /** Check the configured services without starting a thread or generating a model response. */
184
+ export function probeRuntimeConnectivity(state, workspaceId) {
185
+ const config = snapshot(state, workspaceId);
186
+ const key = JSON.stringify(config);
187
+ let cache = caches.get(state);
188
+ if (!cache) {
189
+ cache = new Map();
190
+ caches.set(state, cache);
191
+ }
192
+ const previous = cache.get(workspaceId);
193
+ if (previous?.key === key) {
194
+ if (previous.pending)
195
+ return previous.pending;
196
+ if (previous.value && previous.expiresAt > Date.now())
197
+ return Promise.resolve(previous.value);
198
+ }
199
+ const entry = previous?.key === key ? previous : { key, expiresAt: 0 };
200
+ cache.set(workspaceId, entry);
201
+ if (cache.size > 256)
202
+ cache.delete(cache.keys().next().value);
203
+ entry.pending = probe(config, entry).then((value) => {
204
+ if (JSON.stringify(snapshot(state, workspaceId)) !== key)
205
+ return probeRuntimeConnectivity(state, workspaceId);
206
+ entry.value = value;
207
+ entry.expiresAt = Date.now() + CACHE_MS;
208
+ return value;
209
+ }).finally(() => { entry.pending = undefined; });
210
+ return entry.pending;
211
+ }
@@ -0,0 +1,429 @@
1
+ import { connect as connectTcp } from 'node:net';
2
+ import { WebSocket, WebSocketServer } from 'ws';
3
+ import { desktopHealthSchema, desktopResourceName, runtimeError, } from '@playcraft/common/cloud-workspace/runtime';
4
+ import { controlTokenMatches, extractControlToken } from './auth.js';
5
+ import { createRfbWatchGate } from './rfb-watch-gate.js';
6
+ import { DesktopPreviewError, DesktopPreviewHost } from './desktop-preview.js';
7
+ import { WorkspaceContextError } from '../workspaces/context-error.js';
8
+ /**
9
+ * A takeover holds the desktop for this long, whether or not a page is watching, and ends on its
10
+ * own unless the user renews it.
11
+ */
12
+ const HOLD_MS = 20 * 60_000;
13
+ const sources = new WeakMap();
14
+ const hosts = new WeakMap();
15
+ export function setDesktopSource(state, source) {
16
+ if (source)
17
+ sources.set(state, source);
18
+ else
19
+ sources.delete(state);
20
+ hosts.get(state)?.replaceSource(source);
21
+ }
22
+ export function desktopHost(state) {
23
+ let host = hosts.get(state);
24
+ if (!host) {
25
+ host = new DesktopHost(state);
26
+ hosts.set(state, host);
27
+ }
28
+ return host;
29
+ }
30
+ export async function disposeDesktopHost(state) {
31
+ const host = hosts.get(state);
32
+ hosts.delete(state);
33
+ sources.delete(state);
34
+ await host?.dispose();
35
+ }
36
+ export class DesktopHost {
37
+ state;
38
+ generation = 0;
39
+ holder = 'none';
40
+ probed = 'display_not_started';
41
+ viewers = new Set();
42
+ sockets = new WebSocketServer({ noServer: true });
43
+ source;
44
+ upstream = loopbackUpstream(process.env.PLAYCRAFT_DESKTOP_UPSTREAM);
45
+ holdMs = holdDuration(process.env.PLAYCRAFT_DESKTOP_HOLD_MS);
46
+ holdExpiresAt;
47
+ holdTimer;
48
+ preview;
49
+ disposed = false;
50
+ constructor(state) {
51
+ this.state = state;
52
+ this.source = sources.get(state);
53
+ }
54
+ replaceSource(source) {
55
+ this.source = source;
56
+ }
57
+ snapshot() {
58
+ return desktopHealthSchema.parse({
59
+ status: this.currentStatus(),
60
+ streamGeneration: this.generation,
61
+ holder: this.holder,
62
+ agentInput: this.holder === 'human' ? 'revoked' : 'open',
63
+ ...(this.holder === 'human' && this.holdExpiresAt
64
+ ? { holdExpiresAt: new Date(this.holdExpiresAt).toISOString() }
65
+ : {}),
66
+ });
67
+ }
68
+ async refresh() {
69
+ if (!this.source && this.upstream) {
70
+ this.probed = (await probePort(this.upstream.port)) ? 'ready' : 'display_not_started';
71
+ }
72
+ return this.snapshot();
73
+ }
74
+ async handleHttp(request, response, url) {
75
+ if (this.disposed || this.state.journal.destroyed()) {
76
+ writeError(response, 'runtime_destroyed');
77
+ return;
78
+ }
79
+ if (request.method === 'GET' && url.pathname === '/runtime/desktop/health') {
80
+ writeJson(response, 200, await this.refresh());
81
+ return;
82
+ }
83
+ if (request.method === 'POST' && url.pathname === '/runtime/desktop/open') {
84
+ await this.refresh();
85
+ if (this.currentStatus() !== 'ready') {
86
+ writeError(response, this.currentStatus());
87
+ return;
88
+ }
89
+ if (this.holder === 'human') {
90
+ writeJson(response, 200, this.snapshot());
91
+ return;
92
+ }
93
+ try {
94
+ this.preview ??= new DesktopPreviewHost(this.state, {
95
+ canNavigate: () => !this.disposed && !this.state.journal.destroyed() && this.holder !== 'human',
96
+ });
97
+ await this.preview.open(url.searchParams.get('workspaceId') ?? undefined, url.searchParams.get('directoryName') ?? 'basic');
98
+ if (this.disposed || this.state.journal.destroyed()) {
99
+ writeError(response, 'runtime_destroyed');
100
+ return;
101
+ }
102
+ const health = await this.refresh();
103
+ if (this.disposed || this.state.journal.destroyed()) {
104
+ writeError(response, 'runtime_destroyed');
105
+ return;
106
+ }
107
+ if (health.status !== 'ready') {
108
+ writeError(response, health.status);
109
+ return;
110
+ }
111
+ writeJson(response, 200, health);
112
+ }
113
+ catch (error) {
114
+ const reason = error instanceof DesktopPreviewError ? error.code
115
+ : error instanceof WorkspaceContextError ? error.message : 'desktop_preview_start_failed';
116
+ writeError(response, reason);
117
+ }
118
+ return;
119
+ }
120
+ if (request.method === 'POST' && url.pathname === '/runtime/desktop/takeover') {
121
+ await this.refresh();
122
+ if (this.currentStatus() !== 'ready') {
123
+ writeError(response, this.currentStatus());
124
+ return;
125
+ }
126
+ this.holder = 'human';
127
+ this.cutViewers();
128
+ this.hold();
129
+ writeJson(response, 200, this.snapshot());
130
+ return;
131
+ }
132
+ if (request.method === 'POST' && url.pathname === '/runtime/desktop/renew') {
133
+ if (this.holder !== 'human') {
134
+ writeError(response, 'desktop_not_held');
135
+ return;
136
+ }
137
+ this.hold();
138
+ writeJson(response, 200, this.snapshot());
139
+ return;
140
+ }
141
+ if (request.method === 'DELETE' && url.pathname === '/runtime/desktop') {
142
+ this.release();
143
+ writeJson(response, 200, this.snapshot());
144
+ return;
145
+ }
146
+ if (request.method === 'GET' && url.pathname === '/runtime/desktop/connect') {
147
+ await this.refresh();
148
+ this.rejectPlainConnect(response, url);
149
+ return;
150
+ }
151
+ if (request.method === 'GET' && url.pathname.startsWith('/runtime/desktop/resources/')) {
152
+ await this.refresh();
153
+ await this.writeResource(response, url);
154
+ return;
155
+ }
156
+ writeJson(response, 404, { error: 'not_found' });
157
+ }
158
+ handleUpgrade(request, socket, head) {
159
+ const url = new URL(request.url ?? '/', 'http://127.0.0.1');
160
+ if (!controlTokenMatches(this.state.config.controlToken, extractControlToken(request.headers))) {
161
+ rejectUpgrade(socket, 401, runtimeError('unauthenticated', 'control_token_required'));
162
+ return;
163
+ }
164
+ if (this.disposed || this.state.journal.destroyed()) {
165
+ rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'runtime_destroyed'));
166
+ return;
167
+ }
168
+ if (this.currentStatus() !== 'ready') {
169
+ rejectUpgrade(socket, 409, runtimeError('capability_unavailable', this.currentStatus()));
170
+ return;
171
+ }
172
+ const generation = generationOf(url);
173
+ if (generation === undefined || generation !== this.generation) {
174
+ rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'desktop_stale'));
175
+ return;
176
+ }
177
+ this.sockets.handleUpgrade(request, socket, head, (ws) => this.attach(ws, generation));
178
+ }
179
+ async dispose() {
180
+ this.disposed = true;
181
+ this.release();
182
+ this.sockets.close();
183
+ await this.preview?.dispose();
184
+ }
185
+ release() {
186
+ this.clearHold();
187
+ this.holder = 'none';
188
+ this.cutViewers();
189
+ }
190
+ /** Starts or renews the hold; when it runs out the desktop is released as if by hand. */
191
+ hold() {
192
+ this.clearHold();
193
+ this.holdExpiresAt = Date.now() + this.holdMs;
194
+ this.holdTimer = setTimeout(() => {
195
+ this.holdTimer = undefined;
196
+ if (this.holder === 'human')
197
+ this.release();
198
+ }, this.holdMs);
199
+ this.holdTimer.unref?.();
200
+ }
201
+ clearHold() {
202
+ if (this.holdTimer)
203
+ clearTimeout(this.holdTimer);
204
+ this.holdTimer = undefined;
205
+ this.holdExpiresAt = undefined;
206
+ }
207
+ currentStatus() {
208
+ if (this.source)
209
+ return this.source.health().status;
210
+ if (this.upstream)
211
+ return this.probed;
212
+ return 'display_not_started';
213
+ }
214
+ cutViewers() {
215
+ this.generation += 1;
216
+ for (const viewer of this.viewers)
217
+ this.drop(viewer);
218
+ this.viewers.clear();
219
+ }
220
+ drop(viewer) {
221
+ viewer.detach();
222
+ viewer.upstream?.close();
223
+ if (viewer.ws.readyState === WebSocket.OPEN)
224
+ viewer.ws.close();
225
+ }
226
+ attach(ws, generation) {
227
+ const viewer = { generation, ws, detach: () => undefined };
228
+ const send = (chunk, binary = true) => {
229
+ if (this.generation !== generation || ws.readyState !== WebSocket.OPEN)
230
+ return;
231
+ ws.send(chunk, { binary });
232
+ };
233
+ if (this.source) {
234
+ viewer.detach = this.source.attach(generation, (chunk) => send(chunk));
235
+ }
236
+ else if (this.upstream) {
237
+ const upstream = new WebSocket(`ws://127.0.0.1:${this.upstream.port}/`);
238
+ const watch = createRfbWatchGate();
239
+ viewer.upstream = upstream;
240
+ viewer.detach = () => upstream.close();
241
+ upstream.on('error', () => {
242
+ if (!this.source && this.generation === generation)
243
+ this.probed = 'display_unavailable';
244
+ if (ws.readyState === WebSocket.OPEN)
245
+ ws.close(1011, 'desktop_unavailable');
246
+ });
247
+ upstream.on('message', (data, isBinary) => {
248
+ if (this.generation !== generation) {
249
+ this.drop(viewer);
250
+ return;
251
+ }
252
+ const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
253
+ watch.observeServer(chunk);
254
+ if (watch.failed) {
255
+ ws.close(1008, 'desktop_protocol_error');
256
+ upstream.close();
257
+ return;
258
+ }
259
+ send(chunk, isBinary);
260
+ });
261
+ upstream.on('close', () => {
262
+ if (ws.readyState === WebSocket.OPEN)
263
+ ws.close();
264
+ });
265
+ ws.on('message', (data, isBinary) => {
266
+ if (this.generation !== generation)
267
+ return;
268
+ const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
269
+ if (viewer.upstream?.readyState !== WebSocket.OPEN)
270
+ return;
271
+ const outgoing = watch.clientBytes(chunk, this.holder === 'human');
272
+ if (watch.failed) {
273
+ ws.close(1008, 'desktop_protocol_error');
274
+ upstream.close();
275
+ return;
276
+ }
277
+ for (const message of outgoing) {
278
+ viewer.upstream.send(message, { binary: isBinary });
279
+ }
280
+ });
281
+ }
282
+ this.viewers.add(viewer);
283
+ let closed = false;
284
+ const close = () => {
285
+ if (closed)
286
+ return;
287
+ closed = true;
288
+ this.viewers.delete(viewer);
289
+ viewer.detach();
290
+ viewer.upstream?.close();
291
+ };
292
+ ws.on('close', close);
293
+ ws.on('error', close);
294
+ }
295
+ rejectPlainConnect(response, url) {
296
+ if (this.currentStatus() !== 'ready') {
297
+ writeError(response, this.currentStatus());
298
+ return;
299
+ }
300
+ const generation = generationOf(url);
301
+ if (generation === undefined || generation !== this.generation) {
302
+ writeError(response, 'desktop_stale');
303
+ return;
304
+ }
305
+ writeError(response, 'websocket_required');
306
+ }
307
+ async writeResource(response, url) {
308
+ if (this.currentStatus() !== 'ready') {
309
+ writeError(response, this.currentStatus());
310
+ return;
311
+ }
312
+ const name = desktopResourceName(decodeURIComponent(url.pathname.slice('/runtime/desktop/resources/'.length)));
313
+ if (!name) {
314
+ writeJson(response, 400, { error: 'invalid_desktop_resource' });
315
+ return;
316
+ }
317
+ const generation = url.searchParams.get('generation');
318
+ const document = name === 'vnc.html' || name.endsWith('/vnc.html');
319
+ if (document && Number(generation) !== this.generation) {
320
+ writeError(response, 'desktop_stale');
321
+ return;
322
+ }
323
+ if (generation !== null && Number(generation) !== this.generation) {
324
+ writeError(response, 'desktop_stale');
325
+ return;
326
+ }
327
+ if (this.source) {
328
+ const file = this.source.readResource(name);
329
+ if (!file) {
330
+ writeJson(response, 404, { error: 'not_found' });
331
+ return;
332
+ }
333
+ writeBytes(response, 200, file.contentType, file.body);
334
+ return;
335
+ }
336
+ if (!this.upstream) {
337
+ writeError(response, 'display_not_started');
338
+ return;
339
+ }
340
+ const upstream = await fetch(`http://127.0.0.1:${this.upstream.port}/${name}`, {
341
+ redirect: 'error',
342
+ signal: AbortSignal.timeout(5_000),
343
+ }).catch(() => undefined);
344
+ if (!upstream) {
345
+ writeError(response, 'display_unavailable');
346
+ return;
347
+ }
348
+ const body = Buffer.from(await upstream.arrayBuffer());
349
+ if (!upstream.ok) {
350
+ writeBytes(response, upstream.status, upstream.headers.get('content-type') ?? 'application/octet-stream', body);
351
+ return;
352
+ }
353
+ writeBytes(response, 200, upstream.headers.get('content-type') ?? 'application/octet-stream', body);
354
+ }
355
+ }
356
+ export function desktopRoute(pathname) {
357
+ return (pathname === '/runtime/desktop/health' ||
358
+ pathname === '/runtime/desktop/open' ||
359
+ pathname === '/runtime/desktop/connect' ||
360
+ pathname === '/runtime/desktop/takeover' ||
361
+ pathname === '/runtime/desktop/renew' ||
362
+ pathname === '/runtime/desktop' ||
363
+ pathname.startsWith('/runtime/desktop/resources/'));
364
+ }
365
+ function generationOf(url) {
366
+ const value = url.searchParams.get('generation');
367
+ if (!value || !/^\d+$/.test(value))
368
+ return undefined;
369
+ return Number(value);
370
+ }
371
+ function loopbackUpstream(value) {
372
+ if (!value)
373
+ return undefined;
374
+ const match = /^(?:127\.0\.0\.1|localhost):(\d+)$/.exec(value.trim());
375
+ if (!match)
376
+ return undefined;
377
+ const port = Number(match[1]);
378
+ if (port < 1 || port > 65535)
379
+ return undefined;
380
+ return { port };
381
+ }
382
+ function holdDuration(value) {
383
+ const parsed = Number(value);
384
+ return Number.isInteger(parsed) && parsed > 0 ? parsed : HOLD_MS;
385
+ }
386
+ function probePort(port) {
387
+ return new Promise((resolve) => {
388
+ const socket = connectTcp({ host: '127.0.0.1', port });
389
+ const timer = setTimeout(() => {
390
+ socket.destroy();
391
+ resolve(false);
392
+ }, 200);
393
+ socket.once('connect', () => {
394
+ clearTimeout(timer);
395
+ socket.end();
396
+ resolve(true);
397
+ });
398
+ socket.once('error', () => {
399
+ clearTimeout(timer);
400
+ resolve(false);
401
+ });
402
+ });
403
+ }
404
+ function writeError(response, reason) {
405
+ writeJson(response, 409, runtimeError('capability_unavailable', reason));
406
+ }
407
+ function writeJson(response, status, body) {
408
+ const payload = JSON.stringify(body);
409
+ response.writeHead(status, {
410
+ 'content-type': 'application/json; charset=utf-8',
411
+ 'content-length': Buffer.byteLength(payload),
412
+ 'cache-control': 'no-store',
413
+ });
414
+ response.end(payload);
415
+ }
416
+ function writeBytes(response, status, contentType, body) {
417
+ response.writeHead(status, {
418
+ 'content-type': contentType,
419
+ 'content-length': body.length,
420
+ 'cache-control': 'no-store',
421
+ });
422
+ response.end(body);
423
+ }
424
+ function rejectUpgrade(socket, status, body) {
425
+ const payload = JSON.stringify(body);
426
+ const title = status === 401 ? 'Unauthorized' : 'Conflict';
427
+ socket.write(`HTTP/1.1 ${status} ${title}\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: ${Buffer.byteLength(payload)}\r\nconnection: close\r\n\r\n${payload}`);
428
+ socket.destroy();
429
+ }