@wildshard/sdk 0.0.1 → 0.2.3

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 (687) hide show
  1. package/GUIDE.md +790 -0
  2. package/README.md +13 -5
  3. package/bin/wildshard.mjs +38 -0
  4. package/lint/declaration-config.d.mts +2 -0
  5. package/lint/declaration-config.mjs +19 -0
  6. package/lint/engine-plugin.d.mts +2 -0
  7. package/lint/engine-plugin.mjs +40 -0
  8. package/lint/host-callbacks.d.mts +6 -0
  9. package/lint/host-callbacks.mjs +123 -0
  10. package/lint/host-files.d.mts +1 -0
  11. package/lint/host-files.mjs +7 -0
  12. package/lint/layer-exports.d.mts +2 -0
  13. package/lint/layer-exports.mjs +21 -0
  14. package/lint/legacy-line-basis.json +995 -0
  15. package/lint/nine-tiling-baseline.json +35 -0
  16. package/lint/ratchet.json +11 -0
  17. package/lint/runtime-files.d.mts +12 -0
  18. package/lint/runtime-files.json +16 -0
  19. package/lint/runtime-files.mjs +69 -0
  20. package/lint/runtime-performance.d.mts +6 -0
  21. package/lint/runtime-performance.mjs +184 -0
  22. package/lint/sdk-plugin.d.mts +4 -0
  23. package/lint/sdk-plugin.mjs +134 -0
  24. package/lint/shardfile-boundaries.d.mts +10 -0
  25. package/lint/shardfile-boundaries.mjs +122 -0
  26. package/lint/tile-bake-debt.json +556 -0
  27. package/package.json +365 -3
  28. package/scripts/agent-parity.mjs +1524 -0
  29. package/scripts/agent-sync.mjs +518 -0
  30. package/scripts/apfs-clone.mjs +67 -0
  31. package/scripts/assert-store-layout.mjs +23 -0
  32. package/scripts/astc6-phone-cap.d.mts +3 -0
  33. package/scripts/astc6-phone-cap.mjs +137 -0
  34. package/scripts/audit-assets.d.mts +10 -0
  35. package/scripts/audit-assets.mjs +151 -0
  36. package/scripts/bake/coatFiles.d.mts +6 -0
  37. package/scripts/bake/coatFiles.mjs +37 -0
  38. package/scripts/bake/environment.d.mts +2 -0
  39. package/scripts/bake/environment.mjs +58 -0
  40. package/scripts/bake/far-proxies.mjs +45 -0
  41. package/scripts/bake/keyed-sky.d.mts +4 -0
  42. package/scripts/bake/keyed-sky.mjs +34 -0
  43. package/scripts/bake/movers.mjs +56 -0
  44. package/scripts/bake/nativeWorld.d.mts +6 -0
  45. package/scripts/bake/nativeWorld.mjs +43 -0
  46. package/scripts/bake/navmeshGround.ts +22 -0
  47. package/scripts/bake/near-placeholder.mjs +331 -0
  48. package/scripts/bake/placeholderShards.mjs +41 -0
  49. package/scripts/bake/skins.mjs +15 -0
  50. package/scripts/bake/template-skins.mjs +33 -0
  51. package/scripts/bake/viewmodelBytes.ts +26 -0
  52. package/scripts/bake/viewmodelPage.ts +11 -0
  53. package/scripts/bake/worldHost.d.mts +35 -0
  54. package/scripts/bake/worldHost.mjs +110 -0
  55. package/scripts/bake-astc6.cache.json +80 -0
  56. package/scripts/bake-astc6.far-reach.cache.json +23 -0
  57. package/scripts/bake-astc6.list.json +111 -0
  58. package/scripts/bake-astc6.mjs +279 -0
  59. package/scripts/bake-astc6.nalati-grasslands.cache.json +42 -0
  60. package/scripts/bake-catalogue.mjs +44 -0
  61. package/scripts/bake-check.mjs +54 -0
  62. package/scripts/bake-chunk.mjs +124 -0
  63. package/scripts/bake-cloud-field.mjs +24 -0
  64. package/scripts/bake-coats.mjs +110 -0
  65. package/scripts/bake-data-maps.d.mts +24 -0
  66. package/scripts/bake-data-maps.mjs +72 -0
  67. package/scripts/bake-entry-programs.mjs +117 -0
  68. package/scripts/bake-geometry.mjs +106 -0
  69. package/scripts/bake-hybrid-tiles.mjs +28 -0
  70. package/scripts/bake-ktx2.cache.json +276 -0
  71. package/scripts/bake-ktx2.list.json +365 -0
  72. package/scripts/bake-ktx2.mjs +477 -0
  73. package/scripts/bake-map-glb.mjs +127 -0
  74. package/scripts/bake-map-rest.d.mts +7 -0
  75. package/scripts/bake-map-rest.mjs +50 -0
  76. package/scripts/bake-maps.mjs +200 -0
  77. package/scripts/bake-navmesh.mjs +259 -0
  78. package/scripts/bake-packs.mjs +129 -0
  79. package/scripts/bake-pickups.mjs +102 -0
  80. package/scripts/bake-query-terrain.mjs +64 -0
  81. package/scripts/bake-recurve-pool.mjs +16 -0
  82. package/scripts/bake-section-schemas.d.mts +3 -0
  83. package/scripts/bake-template-shardfile.mjs +32 -0
  84. package/scripts/bake-textures.mjs +80 -0
  85. package/scripts/bake-viewmodel-sets.json +45 -0
  86. package/scripts/bake-viewmodel-sets.mjs +137 -0
  87. package/scripts/bake-voxel-ao.mjs +119 -0
  88. package/scripts/bake-water-ripples.mjs +25 -0
  89. package/scripts/blender/README.md +129 -0
  90. package/scripts/blender/build.sh +166 -0
  91. package/scripts/blender/lib/export-scene.mjs +129 -0
  92. package/scripts/blender/lib/glb-digest.mjs +188 -0
  93. package/scripts/blender/lib/glb.py +68 -0
  94. package/scripts/blender/lib/save_blend.py +17 -0
  95. package/scripts/blender/lib/world_fixture.py +55 -0
  96. package/scripts/blender/targets.json +591 -0
  97. package/scripts/build-sdk.mjs +95 -0
  98. package/scripts/build-shardfiles.d.mts +7 -0
  99. package/scripts/build-shardfiles.mjs +206 -0
  100. package/scripts/capture-hero.mjs +137 -0
  101. package/scripts/check-lift-review.mjs +23 -0
  102. package/scripts/chromium-keychain-check.mjs +139 -0
  103. package/scripts/chromium-keychain.d.mts +1 -0
  104. package/scripts/chromium-keychain.mjs +5 -0
  105. package/scripts/compile-script.d.mts +3 -0
  106. package/scripts/compile-script.mjs +8 -0
  107. package/scripts/creature-color.mjs +255 -0
  108. package/scripts/decide/calibrate.py +127 -0
  109. package/scripts/decide/calibration/2026-10-03/labels-s1.tsv +281 -0
  110. package/scripts/decide/calibration/2026-10-03/labels-s2.tsv +97 -0
  111. package/scripts/decide/calibration/2026-10-03/labels-s3.tsv +48 -0
  112. package/scripts/decide/calibration/2026-10-03/labels-s3b.tsv +26 -0
  113. package/scripts/decide/calibration/2026-10-03/res-capture-status-v1.jsonl +376 -0
  114. package/scripts/decide/calibration/2026-10-03/res-text-garbled-strings.jsonl +48 -0
  115. package/scripts/decide/calibration/2026-10-03/res-text-garbled-v1.jsonl +73 -0
  116. package/scripts/decide/decide.py +262 -0
  117. package/scripts/decide/decide.sh +50 -0
  118. package/scripts/decide/layer-purity-pilot.mjs +41 -0
  119. package/scripts/decide/sets/capture-status.json +46 -0
  120. package/scripts/decide/sets/layer-purity.json +28 -0
  121. package/scripts/decide/sets/text-garbled.json +17 -0
  122. package/scripts/decide/test_decide.py +37 -0
  123. package/scripts/docs.mjs +15 -0
  124. package/scripts/entry-reads/crawl.ts +152 -0
  125. package/scripts/entry-reads/tsconfig.json +25 -0
  126. package/scripts/gen-format-schema.d.mts +2 -0
  127. package/scripts/gen-format-schema.mjs +21 -0
  128. package/scripts/gen-host-catalogue.d.mts +14 -0
  129. package/scripts/gen-host-catalogue.mjs +108 -0
  130. package/scripts/gen-shard-layout-doc.d.mts +4 -0
  131. package/scripts/gen-shard-layout-doc.mjs +55 -0
  132. package/scripts/gen-shards.d.mts +17 -0
  133. package/scripts/gen-shards.mjs +311 -0
  134. package/scripts/goldens/capture-inputs.d.mts +4 -0
  135. package/scripts/goldens/capture-inputs.mjs +34 -0
  136. package/scripts/goldens/colour_shift.py +27 -0
  137. package/scripts/goldens/native-residency.d.mts +10 -0
  138. package/scripts/goldens/native-residency.mjs +104 -0
  139. package/scripts/goldens/plot-inputs.d.mts +12 -0
  140. package/scripts/goldens/plot-inputs.mjs +46 -0
  141. package/scripts/gpu-texmem.mjs +98 -0
  142. package/scripts/horizon-matte/config.py +24 -0
  143. package/scripts/horizon-matte/encode.py +91 -0
  144. package/scripts/horizon-matte/key.py +141 -0
  145. package/scripts/horizon-matte/mkjobs.py +33 -0
  146. package/scripts/horizon-matte/mkjobs_day2.py +11 -0
  147. package/scripts/horizon-matte/overlap.py +80 -0
  148. package/scripts/horizon-matte/run_codex.py +57 -0
  149. package/scripts/horizon-matte/stitch.py +133 -0
  150. package/scripts/img2mesh/CC0.md +105 -0
  151. package/scripts/img2mesh/README.md +209 -0
  152. package/scripts/img2mesh/ab_board.py +102 -0
  153. package/scripts/img2mesh/birds/birds.json +255 -0
  154. package/scripts/img2mesh/birds/birds_atlas.py +150 -0
  155. package/scripts/img2mesh/birds/birds_fix_preview.mjs +103 -0
  156. package/scripts/img2mesh/birds/birds_fix_render.py +75 -0
  157. package/scripts/img2mesh/birds/birds_pack.py +110 -0
  158. package/scripts/img2mesh/birds/birds_phone_b.py +112 -0
  159. package/scripts/img2mesh/birds/birds_post.py +550 -0
  160. package/scripts/img2mesh/birds/birds_render.py +125 -0
  161. package/scripts/img2mesh/birds/birds_sheet.py +33 -0
  162. package/scripts/img2mesh/birds/birds_view.py +60 -0
  163. package/scripts/img2mesh/board.py +100 -0
  164. package/scripts/img2mesh/build_cc0.sh +52 -0
  165. package/scripts/img2mesh/build_driftwood.sh +12 -0
  166. package/scripts/img2mesh/build_faces.sh +53 -0
  167. package/scripts/img2mesh/build_props.py +81 -0
  168. package/scripts/img2mesh/cc0_export.py +186 -0
  169. package/scripts/img2mesh/driftwood_post.py +571 -0
  170. package/scripts/img2mesh/e304_faces.sh +67 -0
  171. package/scripts/img2mesh/face_remaster.py +911 -0
  172. package/scripts/img2mesh/face_views.py +95 -0
  173. package/scripts/img2mesh/faces-e304.json +9 -0
  174. package/scripts/img2mesh/faces.json +30 -0
  175. package/scripts/img2mesh/head_cut.py +100 -0
  176. package/scripts/img2mesh/hi3d_paint.py +94 -0
  177. package/scripts/img2mesh/hi3d_refine.py +161 -0
  178. package/scripts/img2mesh/hunyuan_cpu_rasterizer.sh +42 -0
  179. package/scripts/img2mesh/pine_hollow_phone.sh +13 -0
  180. package/scripts/img2mesh/props/coral-arch.json +32 -0
  181. package/scripts/img2mesh/props/ember-furnace.json +30 -0
  182. package/scripts/img2mesh/props/night-market-gate.json +10 -0
  183. package/scripts/img2mesh/render_still.py +86 -0
  184. package/scripts/img2mesh/rig_strip.mjs +46 -0
  185. package/scripts/img2mesh/rig_transfer.mjs +104 -0
  186. package/scripts/img2mesh/split_sheet.py +48 -0
  187. package/scripts/img2mesh/trellis_batch.py +110 -0
  188. package/scripts/img2mesh/versus_board.py +114 -0
  189. package/scripts/import-bundle.d.mts +2 -0
  190. package/scripts/import-bundle.mjs +20 -0
  191. package/scripts/ktx2-ab-board.py +133 -0
  192. package/scripts/ktx2-ab.mjs +111 -0
  193. package/scripts/ktx2-settings.mjs +18 -0
  194. package/scripts/land.d.mts +14 -0
  195. package/scripts/land.mjs +809 -0
  196. package/scripts/lint-dispatch.mjs +14 -0
  197. package/scripts/map-bake-frames.d.mts +4 -0
  198. package/scripts/map-bake-frames.mjs +23 -0
  199. package/scripts/map-geometry.d.mts +9 -0
  200. package/scripts/map-geometry.mjs +29 -0
  201. package/scripts/map-world.mjs +162 -0
  202. package/scripts/mockup-local.sh +46 -0
  203. package/scripts/music/export-midi.mjs +68 -0
  204. package/scripts/music/gen/analyze.py +308 -0
  205. package/scripts/music/gen/audio_jobs.py +46 -0
  206. package/scripts/music/gen/briefs.json +51 -0
  207. package/scripts/music/gen/build_page.py +334 -0
  208. package/scripts/music/gen/folk.json +3187 -0
  209. package/scripts/music/gen/gen_ace_step.py +156 -0
  210. package/scripts/music/gen/gen_heartmula.py +187 -0
  211. package/scripts/music/gen/gen_minimax.py +143 -0
  212. package/scripts/music/gen/gen_sao.py +122 -0
  213. package/scripts/music/gen/gen_sao_small.py +104 -0
  214. package/scripts/music/gen/gen_sfx.py +98 -0
  215. package/scripts/music/gen/gen_sfx_ezaudio.py +112 -0
  216. package/scripts/music/gen/gen_sfx_moss.py +112 -0
  217. package/scripts/music/gen/models.json +61 -0
  218. package/scripts/music/gen/nalati-jobs.json +104 -0
  219. package/scripts/music/gen/nalati-score-build.json +119 -0
  220. package/scripts/music/gen/nalati-score.json +3448 -0
  221. package/scripts/music/gen/ob7-fit-decisions.json +38 -0
  222. package/scripts/music/gen/ob7-score-jobs.json +152 -0
  223. package/scripts/music/gen/ob7-sfx-jobs.json +897 -0
  224. package/scripts/music/gen/ob7_build.py +469 -0
  225. package/scripts/music/gen/ob7_generate.py +67 -0
  226. package/scripts/music/gen/ob7_run.sh +42 -0
  227. package/scripts/music/gen/orchestral.json +3187 -0
  228. package/scripts/music/gen/own_score.py +486 -0
  229. package/scripts/music/gen/ph-jobs.json +27 -0
  230. package/scripts/music/gen/ph_page.py +222 -0
  231. package/scripts/music/gen/piano.json +3175 -0
  232. package/scripts/music/gen/rank_v3.py +248 -0
  233. package/scripts/music/gen/sfx-best.json +2486 -0
  234. package/scripts/music/gen/sfx-ezaudio.json +4082 -0
  235. package/scripts/music/gen/sfx-jobs.json +57 -0
  236. package/scripts/music/gen/sfx-minimax-jobs.json +16 -0
  237. package/scripts/music/gen/sfx-minimax.json +289 -0
  238. package/scripts/music/gen/sfx-moss.json +4082 -0
  239. package/scripts/music/gen/sfx-nalati-b3-jobs.json +17 -0
  240. package/scripts/music/gen/sfx-nalati-jobs.json +338 -0
  241. package/scripts/music/gen/sfx-nalati.json +11202 -0
  242. package/scripts/music/gen/sfx-nd-jobs.json +57 -0
  243. package/scripts/music/gen/sfx-nd-moss.json +2097 -0
  244. package/scripts/music/gen/sfx-nd-sa3-medium.json +2097 -0
  245. package/scripts/music/gen/sfx-nd-summary.json +38 -0
  246. package/scripts/music/gen/sfx-peaks.json +7 -0
  247. package/scripts/music/gen/sfx-ph-jobs.json +169 -0
  248. package/scripts/music/gen/sfx-ph-moss.json +6564 -0
  249. package/scripts/music/gen/sfx-ph-sa3-medium.json +7239 -0
  250. package/scripts/music/gen/sfx-ph-summary.json +63 -0
  251. package/scripts/music/gen/sfx-sa3-medium.json +4082 -0
  252. package/scripts/music/gen/sfx-sa3.json +4082 -0
  253. package/scripts/music/gen/sfx-summary.json +107 -0
  254. package/scripts/music/gen/sfx_build.py +332 -0
  255. package/scripts/music/gen/sfx_merge.py +255 -0
  256. package/scripts/music/gen/sfx_minimax.py +61 -0
  257. package/scripts/music/gen/sfx_nalati.py +331 -0
  258. package/scripts/music/gen/sfx_sprite.py +424 -0
  259. package/scripts/music/gen/stems.py +539 -0
  260. package/scripts/music/gen/test_loop_meter.py +29 -0
  261. package/scripts/music/gen/test_ob7_provenance.py +77 -0
  262. package/scripts/music/gen/v3-folk-build.json +148 -0
  263. package/scripts/music/gen/v3-folk.json +1818 -0
  264. package/scripts/music/gen/v3-jobs.json +145 -0
  265. package/scripts/music/gen/v3-orchestral-build.json +148 -0
  266. package/scripts/music/gen/v3-orchestral.json +1813 -0
  267. package/scripts/music/gen/v3-ph-folk-build.json +94 -0
  268. package/scripts/music/gen/v3-ph-folk.json +1806 -0
  269. package/scripts/music/gen/v3-ph-orchestral-build.json +94 -0
  270. package/scripts/music/gen/v3-ph-orchestral.json +1824 -0
  271. package/scripts/music/gen/v3-ph-piano-build.json +94 -0
  272. package/scripts/music/gen/v3-ph-piano.json +1818 -0
  273. package/scripts/music/gen/v3-piano-build.json +148 -0
  274. package/scripts/music/gen/v3-piano.json +1813 -0
  275. package/scripts/music/wildshard-theme.mid +0 -0
  276. package/scripts/music/wildshard-trailer30.mid +0 -0
  277. package/scripts/named-blob-output.d.mts +8 -0
  278. package/scripts/named-blob-output.mjs +48 -0
  279. package/scripts/pack-all.mjs +15 -0
  280. package/scripts/pid-lock.d.mts +1 -0
  281. package/scripts/pid-lock.mjs +63 -0
  282. package/scripts/practice/bake_dummy.py +53 -0
  283. package/scripts/practice/build_dummies.sh +43 -0
  284. package/scripts/practice/dummy_parts.py +568 -0
  285. package/scripts/practice/dummy_rig_gate.py +139 -0
  286. package/scripts/practice/gate_sheet.py +36 -0
  287. package/scripts/practice/generate_dummy_unimate.py +132 -0
  288. package/scripts/practice/pack_dummy.mjs +59 -0
  289. package/scripts/practice/repair_dummy_weights.mjs +68 -0
  290. package/scripts/practice/rig_dummy.py +828 -0
  291. package/scripts/practice/verify_unimate_skin.mjs +356 -0
  292. package/scripts/preparation-seed.mjs +15 -0
  293. package/scripts/prepare-basis-tool.mjs +6 -0
  294. package/scripts/prepare-product.d.mts +14 -0
  295. package/scripts/prepare-product.mjs +101 -0
  296. package/scripts/product-build-tools.d.mts +3 -0
  297. package/scripts/product-build-tools.json +3 -0
  298. package/scripts/product-build-tools.mjs +31 -0
  299. package/scripts/publish-public.mjs +7 -0
  300. package/scripts/push-tables.d.mts +1 -0
  301. package/scripts/push-tables.mjs +28 -0
  302. package/scripts/record-shard-mounts.mjs +133 -0
  303. package/scripts/sdk-externals.d.mts +2 -0
  304. package/scripts/sdk-externals.mjs +2 -0
  305. package/scripts/section-inventory.ts +209 -0
  306. package/scripts/select-candidate.mjs +15 -0
  307. package/scripts/shard-build-pool.d.mts +4 -0
  308. package/scripts/shard-build-pool.mjs +53 -0
  309. package/scripts/shard-line-baseline.json +17 -0
  310. package/scripts/shard-milestones.d.mts +15 -0
  311. package/scripts/shard-milestones.mjs +105 -0
  312. package/scripts/shard-output-report.d.mts +9 -0
  313. package/scripts/shard-output-report.mjs +85 -0
  314. package/scripts/shard-platform-cli.mjs +93 -0
  315. package/scripts/shard-progress.mjs +212 -0
  316. package/scripts/shard-timelapse.py +102 -0
  317. package/scripts/shardfile-cold-boot.mjs +79 -0
  318. package/scripts/shardfile-vite.d.mts +4 -0
  319. package/scripts/shardfile-vite.mjs +20 -0
  320. package/scripts/simplify-models.mjs +24 -0
  321. package/scripts/site-facts.mjs +88 -0
  322. package/scripts/test-template-gate.mjs +44 -0
  323. package/scripts/test_golden_compare.py +68 -0
  324. package/scripts/tex-tiers.cache.json +181 -0
  325. package/scripts/tex-tiers.mjs +240 -0
  326. package/scripts/texmem-probe.mjs +184 -0
  327. package/scripts/unused-assets.mjs +173 -0
  328. package/scripts/vite-tmp.d.mts +23 -0
  329. package/scripts/vite-tmp.mjs +157 -0
  330. package/scripts/wave-line-baselines.json +32 -0
  331. package/scripts/wildshard.d.mts +4 -0
  332. package/scripts/wildshard.mjs +105 -0
  333. package/scripts/witness-checkpoints.d.mts +10 -0
  334. package/scripts/witness-checkpoints.mjs +84 -0
  335. package/scripts/witness-generation.d.mts +10 -0
  336. package/scripts/witness-generation.mjs +45 -0
  337. package/scripts/witness-manifests.d.mts +8 -0
  338. package/scripts/witness-manifests.mjs +157 -0
  339. package/scripts/worktree-ignore.d.mts +4 -0
  340. package/scripts/worktree-ignore.mjs +36 -0
  341. package/scripts/worktree-reap.mjs +214 -0
  342. package/scripts/worktree.mjs +396 -0
  343. package/scripts/worldclaw/capture-front.sh +28 -0
  344. package/scripts/worldclaw/design-template.md +62 -0
  345. package/scripts/worldclaw/spec-map.py +92 -0
  346. package/scripts/worldclaw/spec.ts +96 -0
  347. package/skills/wildshard/SKILL.md +50 -0
  348. package/skills/wildshard-goldens/SKILL.md +54 -0
  349. package/skills/wildshard-mockup-to-model/SKILL.md +56 -0
  350. package/skills/wildshard-upgrade/SKILL.md +46 -0
  351. package/src/.oxfmtrc.json +50 -0
  352. package/src/.oxlintrc.json +173 -0
  353. package/src/cli/account/account.ts +199 -0
  354. package/src/cli/account/command.ts +193 -0
  355. package/src/cli/account/key.ts +154 -0
  356. package/src/cli/args.ts +97 -0
  357. package/src/cli/audio/audio.ts +24 -0
  358. package/src/cli/bin.mjs +8 -0
  359. package/src/cli/delete/delete.ts +258 -0
  360. package/src/cli/help.ts +196 -0
  361. package/src/cli/hero/adopt.ts +103 -0
  362. package/src/cli/hero/hero.ts +112 -0
  363. package/src/cli/hero/stamp.ts +298 -0
  364. package/src/cli/main.ts +292 -0
  365. package/src/cli/report.ts +16 -0
  366. package/src/cli/shardfile/command.ts +50 -0
  367. package/src/cli/shardfile/shardfile.ts +192 -0
  368. package/src/cli/upload/api.ts +246 -0
  369. package/src/cli/upload/compress.ts +55 -0
  370. package/src/cli/upload/hero.ts +62 -0
  371. package/src/cli/upload/placement.ts +115 -0
  372. package/src/cli/upload/provenance.ts +192 -0
  373. package/src/cli/upload/signature.ts +30 -0
  374. package/src/cli/upload/upload.ts +269 -0
  375. package/src/cli/upload/validate.ts +74 -0
  376. package/src/cli/upload/wire.ts +147 -0
  377. package/src/cli/version.ts +63 -0
  378. package/src/commons/bake/portableMath.ts +187 -0
  379. package/src/commons/catalogue.ts +10 -0
  380. package/src/commons/courseProgram.ts +32 -0
  381. package/src/commons/practiceCourse.ts +16 -0
  382. package/src/commons/scripts/abi.as +14 -0
  383. package/src/commons/scripts/bridge.as +14 -0
  384. package/src/commons/scripts/course.as +63 -0
  385. package/src/scripts/ask-new.sh +29 -0
  386. package/src/scripts/asks.mjs +141 -0
  387. package/src/scripts/herdr-prompt.sh +34 -0
  388. package/src/scripts/herdr-question-open.sh +67 -0
  389. package/src/scripts/md-wrap.mjs +229 -0
  390. package/src/server/app.ts +19 -0
  391. package/src/server/serve.ts +49 -0
  392. package/src/sharddev/admission.ts +7 -0
  393. package/src/sharddev/arenaView.ts +15 -0
  394. package/src/sharddev/as/groupBankV2.ts +36 -0
  395. package/src/sharddev/as/groupStepV2.ts +13 -0
  396. package/src/sharddev/as/ws.ts +30 -0
  397. package/src/sharddev/as/wsV2.ts +180 -0
  398. package/src/sharddev/assemblyscriptCompiler.d.mts +5 -0
  399. package/src/sharddev/assemblyscriptCompiler.mjs +14 -0
  400. package/src/sharddev/assetHandle.ts +84 -0
  401. package/src/sharddev/assetOwner.ts +70 -0
  402. package/src/sharddev/assetScope.ts +30 -0
  403. package/src/sharddev/assets.ts +21 -0
  404. package/src/sharddev/audio.ts +9 -0
  405. package/src/sharddev/audioEncode.ts +211 -0
  406. package/src/sharddev/author.ts +3 -0
  407. package/src/sharddev/authorError.ts +28 -0
  408. package/src/sharddev/authorManifest.ts +39 -0
  409. package/src/sharddev/bake/annulus.ts +19 -0
  410. package/src/sharddev/bake/assemblyscriptMemo.ts +76 -0
  411. package/src/sharddev/bake/assemblyscriptMemoPort.ts +4 -0
  412. package/src/sharddev/bake/authoredWorld.ts +201 -0
  413. package/src/sharddev/bake/basisEncoder.ts +95 -0
  414. package/src/sharddev/bake/basisGlb.ts +85 -0
  415. package/src/sharddev/bake/basisTool.ts +74 -0
  416. package/src/sharddev/bake/basisToolInputs.ts +476 -0
  417. package/src/sharddev/bake/byteCodec.ts +33 -0
  418. package/src/sharddev/bake/canvasAtlas.ts +406 -0
  419. package/src/sharddev/bake/coarseCopy.ts +59 -0
  420. package/src/sharddev/bake/colliders.ts +87 -0
  421. package/src/sharddev/bake/compactGlb.ts +224 -0
  422. package/src/sharddev/bake/compileScript.ts +119 -0
  423. package/src/sharddev/bake/compileScriptV2.ts +75 -0
  424. package/src/sharddev/bake/contactRows.ts +84 -0
  425. package/src/sharddev/bake/creaturePlacement.ts +117 -0
  426. package/src/sharddev/bake/export.ts +67 -0
  427. package/src/sharddev/bake/facetedGeometry.ts +379 -0
  428. package/src/sharddev/bake/farImpostor.ts +120 -0
  429. package/src/sharddev/bake/forest.ts +100 -0
  430. package/src/sharddev/bake/format-hook.mjs +2 -0
  431. package/src/sharddev/bake/generatorGlb.ts +23 -0
  432. package/src/sharddev/bake/geometryBounds.ts +77 -0
  433. package/src/sharddev/bake/geometryError.ts +48 -0
  434. package/src/sharddev/bake/glb.ts +355 -0
  435. package/src/sharddev/bake/glbCompression.ts +143 -0
  436. package/src/sharddev/bake/gltfSource.ts +59 -0
  437. package/src/sharddev/bake/groundMap.ts +142 -0
  438. package/src/sharddev/bake/image.ts +20 -0
  439. package/src/sharddev/bake/isleMap.ts +64 -0
  440. package/src/sharddev/bake/json.mjs +84 -0
  441. package/src/sharddev/bake/keyedSky.ts +47 -0
  442. package/src/sharddev/bake/keyedSkyMemo.ts +39 -0
  443. package/src/sharddev/bake/kinds.ts +137 -0
  444. package/src/sharddev/bake/lightSources.ts +31 -0
  445. package/src/sharddev/bake/mapAssembly.ts +84 -0
  446. package/src/sharddev/bake/mapRaster.ts +173 -0
  447. package/src/sharddev/bake/mapRest.ts +57 -0
  448. package/src/sharddev/bake/mapScenes.ts +234 -0
  449. package/src/sharddev/bake/materialGraph.ts +32 -0
  450. package/src/sharddev/bake/meadow.ts +27 -0
  451. package/src/sharddev/bake/meshoptChoiceMemo.ts +34 -0
  452. package/src/sharddev/bake/nativeInteractionFacts.ts +5 -0
  453. package/src/sharddev/bake/nativeLattice.ts +178 -0
  454. package/src/sharddev/bake/nativeRaster.ts +106 -0
  455. package/src/sharddev/bake/nativeTerrainField.ts +11 -0
  456. package/src/sharddev/bake/navigation-json.mjs +38 -0
  457. package/src/sharddev/bake/navigation.ts +113 -0
  458. package/src/sharddev/bake/navigationAsset.ts +18 -0
  459. package/src/sharddev/bake/nearPlaceholder.ts +206 -0
  460. package/src/sharddev/bake/normalizeRig.ts +80 -0
  461. package/src/sharddev/bake/phoneAstc.ts +93 -0
  462. package/src/sharddev/bake/placeholders.ts +581 -0
  463. package/src/sharddev/bake/placement.ts +80 -0
  464. package/src/sharddev/bake/portableBytes.ts +18 -0
  465. package/src/sharddev/bake/portableBytesMemo.ts +50 -0
  466. package/src/sharddev/bake/practiceCourse.ts +49 -0
  467. package/src/sharddev/bake/primitives.ts +96 -0
  468. package/src/sharddev/bake/props.ts +443 -0
  469. package/src/sharddev/bake/questPlacement.ts +98 -0
  470. package/src/sharddev/bake/rawTexture.ts +26 -0
  471. package/src/sharddev/bake/riderArms.ts +97 -0
  472. package/src/sharddev/bake/rig.ts +95 -0
  473. package/src/sharddev/bake/riggedHullRecipes.ts +40 -0
  474. package/src/sharddev/bake/signPlacements.ts +25 -0
  475. package/src/sharddev/bake/simplifier.ts +52 -0
  476. package/src/sharddev/bake/skinned.ts +312 -0
  477. package/src/sharddev/bake/slabChunks.ts +149 -0
  478. package/src/sharddev/bake/slabs.ts +263 -0
  479. package/src/sharddev/bake/source-loader.mjs +55 -0
  480. package/src/sharddev/bake/sourceMetadata.ts +54 -0
  481. package/src/sharddev/bake/species.ts +368 -0
  482. package/src/sharddev/bake/specimenCatalogue.ts +47 -0
  483. package/src/sharddev/bake/splatGround.ts +141 -0
  484. package/src/sharddev/bake/staticMaterials.ts +171 -0
  485. package/src/sharddev/bake/terrain.ts +195 -0
  486. package/src/sharddev/bake/texture.ts +33 -0
  487. package/src/sharddev/bake/textureWasm.ts +81 -0
  488. package/src/sharddev/bake/tileEncoder.ts +11 -0
  489. package/src/sharddev/bake/tileGrid.ts +62 -0
  490. package/src/sharddev/bake/v2Finite.ts +160 -0
  491. package/src/sharddev/bake/v2Fuel.ts +71 -0
  492. package/src/sharddev/bake/wholePartition.ts +74 -0
  493. package/src/sharddev/bake/wholePieceJoin.ts +147 -0
  494. package/src/sharddev/bake/world.ts +173 -0
  495. package/src/sharddev/bake/worldCollision.ts +128 -0
  496. package/src/sharddev/bake/worldGeometry.ts +237 -0
  497. package/src/sharddev/bake/worldGlb.ts +123 -0
  498. package/src/sharddev/bake/worldImage.ts +12 -0
  499. package/src/sharddev/bake/worldLod.ts +128 -0
  500. package/src/sharddev/bake/worldRows.ts +102 -0
  501. package/src/sharddev/bake/worldTextureMemo.ts +63 -0
  502. package/src/sharddev/bake/zstdBytesMemo.ts +52 -0
  503. package/src/sharddev/bake.ts +193 -0
  504. package/src/sharddev/bakePublication.ts +31 -0
  505. package/src/sharddev/behaviourSource.ts +94 -0
  506. package/src/sharddev/bin/wildshard.mjs +7 -0
  507. package/src/sharddev/blobBytes.ts +65 -0
  508. package/src/sharddev/blobs.ts +138 -0
  509. package/src/sharddev/bootInventory.ts +129 -0
  510. package/src/sharddev/bossProfiles.ts +18 -0
  511. package/src/sharddev/buildBehaviour.ts +77 -0
  512. package/src/sharddev/buildCacheMetrics.ts +17 -0
  513. package/src/sharddev/buildDecisionScripts.ts +122 -0
  514. package/src/sharddev/check.ts +117 -0
  515. package/src/sharddev/checkProject.ts +126 -0
  516. package/src/sharddev/cli.ts +191 -0
  517. package/src/sharddev/clientChannels.ts +169 -0
  518. package/src/sharddev/clientScripts.ts +10 -0
  519. package/src/sharddev/commons.ts +77 -0
  520. package/src/sharddev/commonsCosts.ts +11 -0
  521. package/src/sharddev/compileMovers.ts +11 -0
  522. package/src/sharddev/configBoundary.ts +6 -0
  523. package/src/sharddev/cookInput.ts +40 -0
  524. package/src/sharddev/crowds.ts +6 -0
  525. package/src/sharddev/decisionBindingMap.ts +11 -0
  526. package/src/sharddev/decisionScriptBindings.ts +117 -0
  527. package/src/sharddev/decisionScripts.ts +28 -0
  528. package/src/sharddev/decisionSource.ts +51 -0
  529. package/src/sharddev/dev.ts +113 -0
  530. package/src/sharddev/director.ts +26 -0
  531. package/src/sharddev/directorAbi.ts +77 -0
  532. package/src/sharddev/discoveryDocument.ts +97 -0
  533. package/src/sharddev/draft.ts +11 -0
  534. package/src/sharddev/eliteEntryRows.ts +29 -0
  535. package/src/sharddev/entries.ts +76 -0
  536. package/src/sharddev/entryReads.ts +73 -0
  537. package/src/sharddev/executeBundle.ts +55 -0
  538. package/src/sharddev/finds.ts +5 -0
  539. package/src/sharddev/formatJsonSchema.ts +3 -0
  540. package/src/sharddev/generationCache.ts +257 -0
  541. package/src/sharddev/generationRecipe.ts +94 -0
  542. package/src/sharddev/handwritten.ts +110 -0
  543. package/src/sharddev/immutable.ts +14 -0
  544. package/src/sharddev/interactions.ts +38 -0
  545. package/src/sharddev/kit/bakedGeometry.ts +16 -0
  546. package/src/sharddev/kit/geometryPack.ts +110 -0
  547. package/src/sharddev/ledger.ts +13 -0
  548. package/src/sharddev/looks/tileField.ts +67 -0
  549. package/src/sharddev/materialGraphFiles.ts +57 -0
  550. package/src/sharddev/materials.ts +574 -0
  551. package/src/sharddev/measure.ts +18 -0
  552. package/src/sharddev/modes.ts +115 -0
  553. package/src/sharddev/moverPrograms.ts +213 -0
  554. package/src/sharddev/movers.ts +75 -0
  555. package/src/sharddev/nativePopulationRows.ts +46 -0
  556. package/src/sharddev/newProject.ts +247 -0
  557. package/src/sharddev/noise.ts +54 -0
  558. package/src/sharddev/outputProduct.ts +188 -0
  559. package/src/sharddev/outputRuntime.ts +66 -0
  560. package/src/sharddev/performancePolicy.ts +18 -0
  561. package/src/sharddev/phasedBoss.ts +34 -0
  562. package/src/sharddev/physics.ts +194 -0
  563. package/src/sharddev/platformSections.ts +42 -0
  564. package/src/sharddev/plumbing.ts +8 -0
  565. package/src/sharddev/productOutput.ts +128 -0
  566. package/src/sharddev/project.ts +337 -0
  567. package/src/sharddev/projectCompilerIdentity.ts +94 -0
  568. package/src/sharddev/projectDecisions.ts +66 -0
  569. package/src/sharddev/projectEntryProof.ts +32 -0
  570. package/src/sharddev/projectGeneration.ts +219 -0
  571. package/src/sharddev/projectInputFiles.ts +47 -0
  572. package/src/sharddev/projectManifest.ts +108 -0
  573. package/src/sharddev/projectMap.ts +35 -0
  574. package/src/sharddev/projectOutput.ts +242 -0
  575. package/src/sharddev/projectPolicy.ts +17 -0
  576. package/src/sharddev/projectSections.ts +27 -0
  577. package/src/sharddev/questGraph.ts +25 -0
  578. package/src/sharddev/quests.ts +65 -0
  579. package/src/sharddev/random.ts +61 -0
  580. package/src/sharddev/refusals.ts +234 -0
  581. package/src/sharddev/reportCard.ts +13 -0
  582. package/src/sharddev/returnProjectionV2.ts +81 -0
  583. package/src/sharddev/rows.ts +192 -0
  584. package/src/sharddev/runtimeImports.ts +38 -0
  585. package/src/sharddev/runtimeMirrors.ts +39 -0
  586. package/src/sharddev/runtimePerformance.ts +38 -0
  587. package/src/sharddev/scene.ts +321 -0
  588. package/src/sharddev/sceneAnimation.ts +54 -0
  589. package/src/sharddev/sceneAudio.ts +64 -0
  590. package/src/sharddev/sceneDeclarations.ts +100 -0
  591. package/src/sharddev/sceneGraph.ts +139 -0
  592. package/src/sharddev/sceneTransform.ts +12 -0
  593. package/src/sharddev/schemaValidation.ts +61 -0
  594. package/src/sharddev/sections.ts +47 -0
  595. package/src/sharddev/shardSource.ts +59 -0
  596. package/src/sharddev/sourceReader.ts +26 -0
  597. package/src/sharddev/spawns.ts +38 -0
  598. package/src/sharddev/species/clips.ts +24 -0
  599. package/src/sharddev/species.ts +29 -0
  600. package/src/sharddev/speciesBrains.ts +19 -0
  601. package/src/sharddev/synth.ts +66 -0
  602. package/src/sharddev/test/compileDualScriptV2.ts +71 -0
  603. package/src/sharddev/test/compileSimV2.ts +21 -0
  604. package/src/sharddev/test/diskScriptScenario.ts +86 -0
  605. package/src/sharddev/test/scriptScenario.ts +249 -0
  606. package/src/sharddev/test/scriptSource.ts +12 -0
  607. package/src/sharddev/version.ts +4 -0
  608. package/src/sharddev/weapons/bowProfile.ts +20 -0
  609. package/src/sharddev/weapons/firearmRows.ts +11 -0
  610. package/src/sharddev/weapons/meleeProfile.ts +71 -0
  611. package/src/sharddev/weapons/thrownProfile.ts +10 -0
  612. package/src/sharddev/worldScenes.ts +308 -0
  613. package/src/sharddev/worldSource.ts +82 -0
  614. package/src/shards/_template/README.md +78 -0
  615. package/src/shards/_template/assets/2bf489fdb15f1734ddb4c4f32d500ec6da85c765ec7a4eb28dc6781160e7ec8c +0 -0
  616. package/src/shards/_template/assets/97ec4d8f75f5fa6239ee919444d6dc19fd35896bb305930c1f050ac6e0e0e6a6 +1 -0
  617. package/src/shards/_template/assets/a6a587a31327f936b1b04c05ade818c73fc8964260918662db43539465e27586 +0 -0
  618. package/src/shards/_template/assets/b4fbde0422e125b498c3dc8b9a5cc2516c8598f09e9d0e5f6b639b32f98179e6 +0 -0
  619. package/src/shards/_template/assets/bfa4dfc9c18979f904557ee8deab0058b8a399be10266f5fb1578b403f482fd4 +1 -0
  620. package/src/shards/_template/assets/ef3b7ff4fd22715771cb7d68a3977a903c5e7c3dc293542687d04b3ef3ace2cb +0 -0
  621. package/src/shards/_template/assets/f2db05998615ce1cb79ea96be32c168842eb6a2b34ec01feb86d36404603ee54 +0 -0
  622. package/src/shards/_template/assets/fef98ebb7fce6f66b26e78ac699e5c90f9bdcfaf8cabeb2b58125347eea8b4ab +0 -0
  623. package/src/shards/_template/behaviour/boss.as +39 -0
  624. package/src/shards/_template/behaviour/door.as +32 -0
  625. package/src/shards/_template/behaviour/hooks.json +129 -0
  626. package/src/shards/_template/behaviour/idle.as +75 -0
  627. package/src/shards/_template/behaviour/items.as +22 -0
  628. package/src/shards/_template/card/landscape.jpg +0 -0
  629. package/src/shards/_template/card/portrait.jpg +0 -0
  630. package/src/shards/_template/card/thumb.jpg +0 -0
  631. package/src/shards/_template/data/audio.json +45 -0
  632. package/src/shards/_template/data/bossDecision.json +83 -0
  633. package/src/shards/_template/data/budgets.json +70 -0
  634. package/src/shards/_template/data/card.json +281 -0
  635. package/src/shards/_template/data/clientScripts.json +987 -0
  636. package/src/shards/_template/data/creatures.json +65 -0
  637. package/src/shards/_template/data/director.json +39 -0
  638. package/src/shards/_template/data/encounters.json +96 -0
  639. package/src/shards/_template/data/items.json +172 -0
  640. package/src/shards/_template/data/layout.json +66 -0
  641. package/src/shards/_template/data/ledger.json +32 -0
  642. package/src/shards/_template/data/look.json +521 -0
  643. package/src/shards/_template/data/map.json +64 -0
  644. package/src/shards/_template/data/moves.json +16 -0
  645. package/src/shards/_template/data/placeholder.json +8 -0
  646. package/src/shards/_template/data/plumbing.json +32 -0
  647. package/src/shards/_template/data/quests.json +223 -0
  648. package/src/shards/_template/data/rows.json +423 -0
  649. package/src/shards/_template/data/skins.json +66 -0
  650. package/src/shards/_template/data/spawn.json +6 -0
  651. package/src/shards/_template/data/targets.json +150 -0
  652. package/src/shards/_template/data/text.json +12 -0
  653. package/src/shards/_template/data/ui.json +33 -0
  654. package/src/shards/_template/data/water.json +13 -0
  655. package/src/shards/_template/generators/behaviour.ts +34 -0
  656. package/src/shards/_template/generators/boss.ts +29 -0
  657. package/src/shards/_template/generators/buildOptions.ts +2 -0
  658. package/src/shards/_template/generators/cell.ts +224 -0
  659. package/src/shards/_template/generators/districts.ts +215 -0
  660. package/src/shards/_template/generators/farLook.ts +15 -0
  661. package/src/shards/_template/generators/generate.ts +27 -0
  662. package/src/shards/_template/generators/ground.ts +15 -0
  663. package/src/shards/_template/generators/kit.ts +69 -0
  664. package/src/shards/_template/generators/landscape.ts +59 -0
  665. package/src/shards/_template/generators/landscapeNoise.ts +62 -0
  666. package/src/shards/_template/generators/mapInputs.ts +10 -0
  667. package/src/shards/_template/generators/product.ts +100 -0
  668. package/src/shards/_template/generators/productOutput.ts +18 -0
  669. package/src/shards/_template/generators/props.ts +9 -0
  670. package/src/shards/_template/generators/templatePropsSource.ts +58 -0
  671. package/src/shards/_template/generators/terrain.ts +17 -0
  672. package/src/shards/_template/generators/world.ts +630 -0
  673. package/src/shards/_template/hero.json +10 -0
  674. package/src/shards/_template/look/entry-reads.json +20 -0
  675. package/src/shards/_template/manifest.json +281 -0
  676. package/src/shards/_template/shard.config.ts +10 -0
  677. package/src/shared/health.ts +10 -0
  678. package/src/tools/build-web.ts +59 -0
  679. package/src/tsconfig.json +30 -0
  680. package/src/web/app.tsx +53 -0
  681. package/src/web/index.html +12 -0
  682. package/src/web/main.tsx +10 -0
  683. package/src/web/tsconfig.json +13 -0
  684. package/tsconfig.author.json +23 -0
  685. package/tsconfig.commons.json +21 -0
  686. package/tsconfig.json +47 -0
  687. package/tsconfig.sharddev.json +20 -0
@@ -0,0 +1,298 @@
1
+ import { createHash, randomUUID } from 'node:crypto'
2
+ import { readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
3
+ import path from 'node:path'
4
+
5
+ import { shardFolderName } from '../../sharddev/shardSource.ts'
6
+
7
+ // A shard's hero (its SHARD SELECT card: thumb, portrait and landscape) is a
8
+ // picture of its world, so it goes stale when the world changes (Jake,
9
+ // 2026-11-12 17:14 Cancún: "you have to update the hero images for the
10
+ // templates"). Rendering it needs a real GPU and a served build of the exact
11
+ // candidate, which no cut step or CI runner has, so the cut refuses instead:
12
+ // `hero.json` beside `manifest.json` records the hash of the shard's content
13
+ // when the hero was captured, and `wildshard build` refuses a product whose
14
+ // source hashes differently now, whose hero files are not the ones stamped,
15
+ // or which does not carry the stamped hero files as blobs (built before the
16
+ // capture). `wildshard hero` captures and re-stamps.
17
+
18
+ const STAMP = 'hero.json'
19
+ const MANIFEST = 'manifest.json'
20
+ const SLOTS = ['thumb', 'portrait', 'landscape'] as const
21
+ // Generated, ignored, test or prose files are not the world a hero shows.
22
+ // The directories are skipped at the shard folder's top level only.
23
+ const SKIPPED_DIRECTORIES = new Set([
24
+ '.cache',
25
+ '.git',
26
+ '.worktrees',
27
+ 'dist',
28
+ 'node_modules',
29
+ 'public',
30
+ 'tmp',
31
+ ])
32
+ const SKIPPED_SUFFIXES = [
33
+ '.generated.ts',
34
+ '.test.ts',
35
+ '.test.mjs',
36
+ '.md',
37
+ '.DS_Store',
38
+ ]
39
+ const NOT_FOUND = 'ENOENT'
40
+ const VALUE = 1
41
+ const NONE = 0
42
+ const INDENT = 2
43
+ const UNKNOWN_TIME = 'at an unknown time'
44
+
45
+ type HeroCondition = 'fresh' | 'generated' | 'stale' | 'unstamped'
46
+
47
+ interface HeroState {
48
+ readonly state: HeroCondition
49
+ /** The content hash now. */
50
+ readonly content: string
51
+ /** What the stamp recorded, if there is one. */
52
+ readonly stamped?: string | undefined
53
+ /** When the stamp says the hero was captured. */
54
+ readonly captured?: string | undefined
55
+ }
56
+
57
+ interface HeroStamp {
58
+ readonly content: string
59
+ readonly captured: string
60
+ readonly base: string
61
+ readonly card: Readonly<Record<string, string>>
62
+ readonly camera?: unknown
63
+ }
64
+
65
+ function sha256(bytes: Readonly<Uint8Array> | string): string {
66
+ return createHash('sha256').update(bytes).digest('hex')
67
+ }
68
+
69
+ function isMissing(error: unknown): boolean {
70
+ return error instanceof Error && 'code' in error && error.code === NOT_FOUND
71
+ }
72
+
73
+ async function readJson(file: string): Promise<unknown> {
74
+ try {
75
+ return JSON.parse(await readFile(file, 'utf8')) as unknown
76
+ } catch (error: unknown) {
77
+ if (isMissing(error)) {
78
+ return undefined
79
+ }
80
+ throw error
81
+ }
82
+ }
83
+
84
+ /** The stamp, or undefined when it is missing or unreadable (unstamped). */
85
+ async function readStamp(shard: string): Promise<unknown> {
86
+ try {
87
+ return await readJson(path.join(shard, STAMP))
88
+ } catch (error: unknown) {
89
+ if (error instanceof SyntaxError) {
90
+ return undefined
91
+ }
92
+ throw error
93
+ }
94
+ }
95
+
96
+ function field(value: unknown, key: string): unknown {
97
+ if (typeof value !== 'object' || value === null) {
98
+ return undefined
99
+ }
100
+ return Object.entries(value).find(
101
+ ([name]: readonly [string, unknown]): boolean => name === key,
102
+ )?.[VALUE]
103
+ }
104
+
105
+ /** The manifest's card urls, by slot. */
106
+ async function cardUrls(
107
+ shard: string,
108
+ ): Promise<Readonly<Record<string, string>>> {
109
+ const card = field(await readJson(path.join(shard, MANIFEST)), 'card')
110
+ const urls: Record<string, string> = {}
111
+ for (const slot of SLOTS) {
112
+ const url = field(card, slot)
113
+ if (typeof url === 'string') {
114
+ urls[slot] = url
115
+ }
116
+ }
117
+ return urls
118
+ }
119
+
120
+ /**
121
+ * The files a card url names inside this shard folder: `/src/shards/<folder>/x`
122
+ * or a path relative to the folder. A `data:` card names none.
123
+ */
124
+ function cardFile(shard: string, url: string): string | undefined {
125
+ if (url.startsWith('data:') || url.includes('://')) {
126
+ return undefined
127
+ }
128
+ // A src/ shard source (J317) is named by its manifest slug, as the build's image root is (scripts/wildshard.mjs).
129
+ const prefix = `/src/shards/${shardFolderName(shard)}/`
130
+ const relative = url.startsWith(prefix) ? url.slice(prefix.length) : url
131
+ const file = path.resolve(shard, relative.replace(/^\/+/u, ''))
132
+ return file.startsWith(`${path.resolve(shard)}${path.sep}`) ? file : undefined
133
+ }
134
+
135
+ /** The hero file each card slot names; a `data:` slot names none. */
136
+ async function heroSlotFiles(
137
+ shard: string,
138
+ ): Promise<Readonly<Record<string, string>>> {
139
+ const files: Record<string, string> = {}
140
+ for (const [slot, url] of Object.entries(await cardUrls(shard))) {
141
+ const file = cardFile(path.resolve(shard), url)
142
+ if (file !== undefined) {
143
+ files[slot] = file
144
+ }
145
+ }
146
+ return files
147
+ }
148
+
149
+ async function heroFiles(shard: string): Promise<ReadonlySet<string>> {
150
+ return new Set(Object.values(await heroSlotFiles(shard)))
151
+ }
152
+
153
+ async function contentFiles(
154
+ directory: string,
155
+ skip: ReadonlySet<string>,
156
+ top = true,
157
+ ): Promise<readonly string[]> {
158
+ const entries = await readdir(directory, { withFileTypes: true })
159
+ const nested = await Promise.all(
160
+ entries.map(
161
+ async (
162
+ entry: Readonly<{
163
+ name: string
164
+ isDirectory: () => boolean
165
+ isFile: () => boolean
166
+ }>,
167
+ ): Promise<readonly string[]> => {
168
+ const file = path.join(directory, entry.name)
169
+ if (entry.isDirectory()) {
170
+ return top && SKIPPED_DIRECTORIES.has(entry.name)
171
+ ? []
172
+ : await contentFiles(file, skip, false)
173
+ }
174
+ const ignored =
175
+ !entry.isFile() ||
176
+ skip.has(file) ||
177
+ SKIPPED_SUFFIXES.some((suffix: string): boolean =>
178
+ entry.name.endsWith(suffix),
179
+ )
180
+ return ignored ? [] : [file]
181
+ },
182
+ ),
183
+ )
184
+ return nested.flat()
185
+ }
186
+
187
+ /**
188
+ * One hash over every content file's folder-relative path and bytes: the
189
+ * shard as a hero would show it. The hero files and the stamp are left out,
190
+ * so a capture never makes its own hero stale.
191
+ */
192
+ async function heroContentHash(shard: string): Promise<string> {
193
+ const root = path.resolve(shard)
194
+ const skip = new Set([...(await heroFiles(root)), path.join(root, STAMP)])
195
+ const found = await contentFiles(root, skip)
196
+ const rows = await Promise.all(
197
+ found.map(async (file: string): Promise<string> => {
198
+ const relative = path.relative(root, file).split(path.sep).join('/')
199
+ return `${relative}\0${sha256(await readFile(file))}\n`
200
+ }),
201
+ )
202
+ return sha256(rows.toSorted().join(''))
203
+ }
204
+
205
+ function textOf(value: unknown): string | undefined {
206
+ return typeof value === 'string' ? value : undefined
207
+ }
208
+
209
+ /** Each hero file's folder-relative path and hash, for the stamp. */
210
+ async function cardHashes(
211
+ shard: string,
212
+ ): Promise<Readonly<Record<string, string>>> {
213
+ const files = [...(await heroFiles(shard))]
214
+ const rows = await Promise.all(
215
+ files.map(async (file: string): Promise<readonly [string, string]> => [
216
+ path.relative(shard, file).split(path.sep).join('/'),
217
+ sha256(await readFile(file)),
218
+ ]),
219
+ )
220
+ return Object.fromEntries(rows)
221
+ }
222
+
223
+ /** Whether the stamped hero files are the ones on disk now. */
224
+ function sameCard(
225
+ stamped: unknown,
226
+ current: Readonly<Record<string, string>>,
227
+ ): boolean {
228
+ const names = Object.keys(current)
229
+ return (
230
+ names.length === Object.keys(stamped ?? {}).length &&
231
+ names.every(
232
+ (name: string): boolean => field(stamped, name) === current[name],
233
+ )
234
+ )
235
+ }
236
+
237
+ /** Whether the shard's captured hero is as new as its content. */
238
+ async function heroState(shard: string): Promise<HeroState> {
239
+ const content = await heroContentHash(shard)
240
+ const files = await heroFiles(shard)
241
+ if (files.size === NONE) {
242
+ return { state: 'generated', content }
243
+ }
244
+ const stamp = await readStamp(shard)
245
+ const stamped = field(stamp, 'content')
246
+ if (typeof stamped !== 'string') {
247
+ return { state: 'unstamped', content }
248
+ }
249
+ const same = sameCard(field(stamp, 'card'), await cardHashes(shard))
250
+ return {
251
+ state: stamped === content && same ? 'fresh' : 'stale',
252
+ content,
253
+ stamped,
254
+ captured: textOf(field(stamp, 'captured')),
255
+ }
256
+ }
257
+
258
+ /** Record that the hero files now show this content (`wildshard hero`). */
259
+ async function writeHeroStamp(
260
+ shard: string,
261
+ options: Readonly<{ base: string; captured?: string; camera?: unknown }>,
262
+ ): Promise<HeroStamp> {
263
+ const previous = await readStamp(shard)
264
+ const camera = options.camera ?? field(previous, 'camera')
265
+ const stamp: HeroStamp = {
266
+ content: await heroContentHash(shard),
267
+ captured: options.captured ?? new Date().toISOString(),
268
+ base: options.base,
269
+ card: await cardHashes(shard),
270
+ ...(camera === undefined ? {} : { camera }),
271
+ }
272
+ const partial = path.join(shard, `${STAMP}.${randomUUID()}.partial`)
273
+ try {
274
+ await writeFile(partial, `${JSON.stringify(stamp, undefined, INDENT)}\n`)
275
+ await rename(partial, path.join(shard, STAMP))
276
+ } finally {
277
+ await rm(partial, { force: true })
278
+ }
279
+ return stamp
280
+ }
281
+
282
+ export {
283
+ type HeroState,
284
+ type HeroStamp,
285
+ MANIFEST,
286
+ STAMP,
287
+ NONE,
288
+ UNKNOWN_TIME,
289
+ cardHashes,
290
+ field,
291
+ heroContentHash,
292
+ heroFiles,
293
+ heroSlotFiles,
294
+ heroState,
295
+ isMissing,
296
+ readJson,
297
+ writeHeroStamp,
298
+ }
@@ -0,0 +1,292 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { serve } from '../server/serve.ts'
4
+ import {
5
+ apiKeyOf,
6
+ runAccount,
7
+ runDelete,
8
+ runWhoami,
9
+ uploadKeyRefusal,
10
+ } from './account/command.ts'
11
+ import { parseCliArgs } from './args.ts'
12
+ import { USAGE, verbHelp } from './help.ts'
13
+ import { refuse, reportLine } from './report.ts'
14
+ import { runPack, runShardfile } from './shardfile/command.ts'
15
+ import {
16
+ DEFAULT_BROTLI_LEVEL,
17
+ MAX_BROTLI_LEVEL,
18
+ MIN_BROTLI_LEVEL,
19
+ } from './upload/compress.ts'
20
+ import { resolveProvenance } from './upload/provenance.ts'
21
+ import { uploadShardfile } from './upload/upload.ts'
22
+ import { readVersion, readVersionChain } from './version.ts'
23
+
24
+ import type { CliArgs } from './args.ts'
25
+ import type { Provenance } from './upload/provenance.ts'
26
+ import type { UploadOptions } from './upload/upload.ts'
27
+
28
+ const EXIT_OK = 0
29
+ const EXIT_USAGE = 1
30
+ const EXIT_CRASH = 2
31
+ const EXIT_FAILED = 3
32
+
33
+ // Arguments start after [node, script] in process.argv.
34
+ const FIRST_CLI_ARG = 2
35
+
36
+ const DEFAULT_PORT = 4403
37
+ const MIN_PORT = 0
38
+ const MAX_PORT = 65_535
39
+
40
+ // The CLI is the one place that reads the environment; it hands it on.
41
+ // oxlint-disable-next-line node/no-process-env -- the CLI is the env boundary
42
+ const ENV: Readonly<Record<string, string | undefined>> = process.env
43
+
44
+ function parsePort(raw: string | undefined): number | undefined {
45
+ if (raw === undefined) {
46
+ return DEFAULT_PORT
47
+ }
48
+ const port = Number(raw)
49
+ return Number.isInteger(port) && port >= MIN_PORT && port <= MAX_PORT
50
+ ? port
51
+ : undefined
52
+ }
53
+
54
+ function parseLevel(raw: string | undefined): number | undefined {
55
+ if (raw === undefined) {
56
+ return DEFAULT_BROTLI_LEVEL
57
+ }
58
+ const level = Number(raw)
59
+ return Number.isInteger(level) &&
60
+ level >= MIN_BROTLI_LEVEL &&
61
+ level <= MAX_BROTLI_LEVEL
62
+ ? level
63
+ : undefined
64
+ }
65
+
66
+ async function runServe(rawPort: string | undefined): Promise<number> {
67
+ const port = parsePort(rawPort)
68
+ if (port === undefined) {
69
+ process.stderr.write(`sharddev: invalid --port ${String(rawPort)}\n`)
70
+ return EXIT_USAGE
71
+ }
72
+ const server = await serve({ port, version: await readVersion() })
73
+ process.stdout.write(`sharddev serving on ${server.url}\n`)
74
+ return EXIT_OK
75
+ }
76
+
77
+ function bypassOption(): { readonly bypassSecret?: string } {
78
+ const bypassSecret = ENV['VERCEL_AUTOMATION_BYPASS_SECRET'] ?? ''
79
+ return bypassSecret === '' ? {} : { bypassSecret }
80
+ }
81
+
82
+ /** The shard version and commit to send, or what is wrong (AC16). */
83
+ async function provenanceOf(args: CliArgs): Promise<Provenance | string> {
84
+ try {
85
+ const provenance = await resolveProvenance({
86
+ cwd: process.cwd(),
87
+ version: args.shardVersion,
88
+ commit: args.commit,
89
+ })
90
+ reportLine(
91
+ `shard source version ${provenance.version}, commit ${provenance.commit}`,
92
+ )
93
+ return provenance
94
+ } catch (error: unknown) {
95
+ return error instanceof Error ? error.message : String(error)
96
+ }
97
+ }
98
+
99
+ /** `--channel`'s wire name (J301): `prod` is the channel `production`. */
100
+ type Channel = UploadOptions['channel']
101
+
102
+ const CHANNELS: Readonly<Record<string, Channel>> = {
103
+ staging: 'staging',
104
+ prod: 'production',
105
+ }
106
+
107
+ /** The upload's channel by its wire name, if `--channel` names one. */
108
+ function channelOf(raw: string | undefined): Channel | undefined {
109
+ return raw !== undefined && Object.hasOwn(CHANNELS, raw)
110
+ ? CHANNELS[raw]
111
+ : undefined
112
+ }
113
+
114
+ function channelRefusal(raw: string | undefined): string {
115
+ const given = raw === undefined ? '' : `, not --channel ${raw}`
116
+ return `upload needs --channel staging or --channel prod${given}`
117
+ }
118
+
119
+ type Connection = Omit<
120
+ UploadOptions,
121
+ keyof Provenance | 'file' | 'channel' | 'place'
122
+ >
123
+
124
+ /** `--server`, else WILDSHARD_API_URL, else empty. */
125
+ function serverOf(args: CliArgs): string {
126
+ return args.server ?? ENV['WILDSHARD_API_URL'] ?? ''
127
+ }
128
+
129
+ /** What stops upload before any request: the server, or either key. */
130
+ function credentialsRefusal(
131
+ server: string,
132
+ privateKey: string,
133
+ apiKey: string | undefined,
134
+ ): string | undefined {
135
+ if (server === '' || privateKey === '') {
136
+ return 'upload needs --server (or WILDSHARD_API_URL) and WILDSHARD_CREATOR_PRIVATE_KEY'
137
+ }
138
+ return uploadKeyRefusal(server, apiKey)
139
+ }
140
+
141
+ /**
142
+ * The level, server and keys, or what is wrong. No account key refuses
143
+ * here, before any request (meta SHARD-DELETE DEL6): api-server answers a
144
+ * keyless ticket 401 since DEL5.
145
+ */
146
+ function connectionOf(
147
+ args: CliArgs,
148
+ apiKey: string | undefined,
149
+ ): Connection | string {
150
+ const level = parseLevel(args.level)
151
+ const server = serverOf(args)
152
+ const privateKey = ENV['WILDSHARD_CREATOR_PRIVATE_KEY'] ?? ''
153
+ if (level === undefined) {
154
+ return `invalid --level ${String(args.level)}`
155
+ }
156
+ const refusal = credentialsRefusal(server, privateKey, apiKey)
157
+ if (refusal !== undefined || apiKey === undefined) {
158
+ return refusal ?? ''
159
+ }
160
+ return {
161
+ server,
162
+ apiKey,
163
+ privateKey,
164
+ level,
165
+ report: reportLine,
166
+ ...bypassOption(),
167
+ }
168
+ }
169
+
170
+ /** Everything but the provenance, or what is wrong. */
171
+ function uploadSettings(
172
+ args: CliArgs,
173
+ apiKey: string | undefined,
174
+ ): Omit<UploadOptions, keyof Provenance> | string {
175
+ const channel = channelOf(args.channel)
176
+ if (args.operand === undefined) {
177
+ return 'upload needs a shard file'
178
+ }
179
+ if (channel === undefined) {
180
+ return channelRefusal(args.channel)
181
+ }
182
+ const connection = connectionOf(args, apiKey)
183
+ return typeof connection === 'string'
184
+ ? connection
185
+ : { file: args.operand, channel, place: !args.noPlace, ...connection }
186
+ }
187
+
188
+ /** The upload's settings from flags and environment, or what is wrong. */
189
+ async function uploadOptions(args: CliArgs): Promise<UploadOptions | string> {
190
+ const apiKey = await apiKeyOf(ENV['WILDSHARD_API_KEY'])
191
+ if (apiKey instanceof Error) {
192
+ return apiKey.message
193
+ }
194
+ const settings = uploadSettings(args, apiKey)
195
+ if (typeof settings === 'string') {
196
+ return settings
197
+ }
198
+ const provenance = await provenanceOf(args)
199
+ return typeof provenance === 'string'
200
+ ? provenance
201
+ : { ...settings, ...provenance }
202
+ }
203
+
204
+ async function runUpload(args: CliArgs): Promise<number> {
205
+ const options = await uploadOptions(args)
206
+ if (typeof options === 'string') {
207
+ refuse('upload', '', options)
208
+ return EXIT_USAGE
209
+ }
210
+ try {
211
+ await uploadShardfile(options)
212
+ return EXIT_OK
213
+ } catch (error: unknown) {
214
+ const reason = error instanceof Error ? error.message : String(error)
215
+ refuse('upload', 'upload failed: ', reason)
216
+ return EXIT_FAILED
217
+ }
218
+ }
219
+
220
+ async function printVersion(): Promise<number> {
221
+ const chain = await readVersionChain()
222
+ process.stdout.write(`${chain.join('\n')}\n`)
223
+ return EXIT_OK
224
+ }
225
+
226
+ function printUsage(code: number): number {
227
+ process.stdout.write(USAGE)
228
+ return code
229
+ }
230
+
231
+ /** `--help`: the command's own help, or all of it. */
232
+ function printHelp(command: string | undefined): number {
233
+ process.stdout.write(
234
+ (command === undefined ? undefined : verbHelp(command)) ?? USAGE,
235
+ )
236
+ return EXIT_OK
237
+ }
238
+
239
+ /** The commands this program runs; the author commands run in src/sharddev/cli.ts. */
240
+ const COMMANDS: Readonly<Record<string, (args: CliArgs) => Promise<number>>> = {
241
+ serve: async (args: CliArgs): Promise<number> => await runServe(args.port),
242
+ // SA3: a built shard file folder; bin/wildshard.mjs sends a project to the author CLI.
243
+ build: async (args: CliArgs): Promise<number> =>
244
+ await runShardfile('build', args.operand, args.target ?? args.out),
245
+ pack: async (args: CliArgs): Promise<number> =>
246
+ await runPack(args.operand, args.out ?? args.target),
247
+ upload: runUpload,
248
+ // Meta SHARD-DELETE DEL6: the account key upload sends.
249
+ account: async (args: CliArgs): Promise<number> =>
250
+ await runAccount(args, serverOf(args)),
251
+ whoami: async (args: CliArgs): Promise<number> =>
252
+ await runWhoami(ENV['WILDSHARD_API_KEY'], serverOf(args)),
253
+ // Meta SHARD-DELETE DEL10: the owner deletes with the same key.
254
+ delete: async (args: CliArgs): Promise<number> =>
255
+ await runDelete({
256
+ args,
257
+ server: serverOf(args),
258
+ fromEnv: ENV['WILDSHARD_API_KEY'],
259
+ }),
260
+ }
261
+
262
+ async function runCommand(args: CliArgs): Promise<number> {
263
+ if (args.command === undefined) {
264
+ return printUsage(EXIT_USAGE)
265
+ }
266
+ const run = Object.hasOwn(COMMANDS, args.command)
267
+ ? COMMANDS[args.command]
268
+ : undefined
269
+ if (run !== undefined) {
270
+ return await run(args)
271
+ }
272
+ process.stderr.write(`sharddev: unknown command ${args.command}\n\n${USAGE}`)
273
+ return EXIT_USAGE
274
+ }
275
+
276
+ async function main(argv: readonly string[]): Promise<number> {
277
+ const args = parseCliArgs(argv)
278
+ if (args.version) {
279
+ return await printVersion()
280
+ }
281
+ if (args.help) {
282
+ return printHelp(args.command)
283
+ }
284
+ return await runCommand(args)
285
+ }
286
+
287
+ try {
288
+ process.exitCode = await main(process.argv.slice(FIRST_CLI_ARG))
289
+ } catch (error: unknown) {
290
+ process.stderr.write(`sharddev: ${String(error)}\n`)
291
+ process.exitCode = EXIT_CRASH
292
+ }
@@ -0,0 +1,16 @@
1
+ import { refusalHint, refusalNote } from '../sharddev/refusals.ts'
2
+
3
+ import type { RefusalStep } from '../sharddev/refusals.ts'
4
+
5
+ /** One line of a command's report on stdout. */
6
+ function reportLine(line: string): void {
7
+ process.stdout.write(`${line}\n`)
8
+ }
9
+
10
+ /** A refusal on stderr, then its rule, fix and GUIDE.md link (SA21). */
11
+ function refuse(step: RefusalStep, prefix: string, reason: string): void {
12
+ const hint = refusalHint(refusalNote(step, reason))
13
+ process.stderr.write(`sharddev: ${prefix}${reason}\n ${hint}\n`)
14
+ }
15
+
16
+ export { refuse, reportLine }
@@ -0,0 +1,50 @@
1
+ import { refuse, reportLine } from '../report.ts'
2
+ import { writeShardfile } from './shardfile.ts'
3
+
4
+ // `wildshard build <folder> [file]` and `wildshard pack`, its deprecated
5
+ // alias (SHARD-AUTHORING SA3, J170): an author build writes its shard file
6
+ // itself; these write the shard file of a folder already built.
7
+
8
+ const EXIT_OK = 0
9
+ const EXIT_USAGE = 1
10
+ const EXIT_FAILED = 3
11
+ // Refusals name the shard file step's rules, whichever verb ran it.
12
+ const STEP = 'shardfile'
13
+
14
+ const PACK_DEPRECATED =
15
+ 'sharddev: pack is deprecated: `wildshard build` writes the shard file (`wildshard build <folder> [file]` for a built folder)\n'
16
+
17
+ /** Write a built folder's shard file, to `out` or beside the folder. */
18
+ async function runShardfile(
19
+ step: 'build' | 'pack',
20
+ dir: string | undefined,
21
+ out: string | undefined,
22
+ ): Promise<number> {
23
+ if (dir === undefined) {
24
+ refuse(STEP, '', `${step} needs a shard file folder`)
25
+ return EXIT_USAGE
26
+ }
27
+ try {
28
+ await writeShardfile({
29
+ dir,
30
+ report: reportLine,
31
+ ...(out === undefined ? {} : { out }),
32
+ })
33
+ return EXIT_OK
34
+ } catch (error: unknown) {
35
+ const reason = error instanceof Error ? error.message : String(error)
36
+ refuse(STEP, `${step} failed: `, reason)
37
+ return EXIT_FAILED
38
+ }
39
+ }
40
+
41
+ /** `pack <folder> [--out <file>]`: one line naming `build`, then the same step. */
42
+ async function runPack(
43
+ dir: string | undefined,
44
+ out: string | undefined,
45
+ ): Promise<number> {
46
+ process.stderr.write(PACK_DEPRECATED)
47
+ return await runShardfile('pack', dir, out)
48
+ }
49
+
50
+ export { runPack, runShardfile }