@wildshard/dev 0.0.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/bin/wildshard.mjs +75 -0
  2. package/lint/host-callbacks.d.mts +6 -0
  3. package/lint/host-callbacks.mjs +123 -0
  4. package/lint/ratchet.json +3 -0
  5. package/package.json +95 -4
  6. package/scripts/audit-assets.d.mts +10 -0
  7. package/scripts/audit-assets.mjs +151 -0
  8. package/scripts/bake/coatFiles.d.mts +6 -0
  9. package/scripts/bake/coatFiles.mjs +37 -0
  10. package/scripts/bake/navmeshGround.ts +22 -0
  11. package/scripts/bake/near-placeholder.mjs +331 -0
  12. package/scripts/bake/viewmodelBytes.ts +26 -0
  13. package/scripts/bake/viewmodelPage.ts +11 -0
  14. package/scripts/bake-catalogue.mjs +44 -0
  15. package/scripts/bake-check.mjs +54 -0
  16. package/scripts/bake-chunk.mjs +124 -0
  17. package/scripts/bake-cloud-field.mjs +24 -0
  18. package/scripts/bake-coats.mjs +110 -0
  19. package/scripts/bake-data-maps.d.mts +24 -0
  20. package/scripts/bake-data-maps.mjs +78 -0
  21. package/scripts/bake-entry-programs.mjs +126 -0
  22. package/scripts/bake-geometry.mjs +106 -0
  23. package/scripts/bake-ktx2.mjs +477 -0
  24. package/scripts/bake-map-glb.mjs +127 -0
  25. package/scripts/bake-map-rest.d.mts +7 -0
  26. package/scripts/bake-map-rest.mjs +50 -0
  27. package/scripts/bake-maps.mjs +200 -0
  28. package/scripts/bake-navmesh.mjs +259 -0
  29. package/scripts/bake-packs.mjs +129 -0
  30. package/scripts/bake-pickups.mjs +102 -0
  31. package/scripts/bake-query-terrain.mjs +64 -0
  32. package/scripts/bake-textures.mjs +80 -0
  33. package/scripts/bake-viewmodel-sets.mjs +137 -0
  34. package/scripts/bake-voxel-ao.mjs +119 -0
  35. package/scripts/bake-water-ripples.mjs +25 -0
  36. package/scripts/browser-imports.d.mts +2 -0
  37. package/scripts/browser-imports.mjs +40 -0
  38. package/scripts/browser-machine-loader-proof.mjs +39 -0
  39. package/scripts/browser-machine-loader.d.mts +8 -0
  40. package/scripts/browser-machine-loader.mjs +87 -0
  41. package/scripts/browser-playwright.d.mts +10 -0
  42. package/scripts/browser-playwright.mjs +5 -0
  43. package/scripts/browser-test.d.mts +4 -0
  44. package/scripts/browser-test.mjs +18 -0
  45. package/scripts/build-sdk.mjs +95 -0
  46. package/scripts/build-shardfiles.d.mts +7 -0
  47. package/scripts/build-shardfiles.mjs +230 -0
  48. package/scripts/capture-hero.mjs +211 -0
  49. package/scripts/chromium-keychain.d.mts +1 -0
  50. package/scripts/chromium-keychain.mjs +7 -0
  51. package/scripts/entry-reads/crawl.ts +152 -0
  52. package/scripts/gen-host-catalogue.d.mts +14 -0
  53. package/scripts/gen-host-catalogue.mjs +108 -0
  54. package/scripts/gen-shards.d.mts +17 -0
  55. package/scripts/gen-shards.mjs +311 -0
  56. package/scripts/goldens/plot-inputs.d.mts +12 -0
  57. package/scripts/goldens/plot-inputs.mjs +46 -0
  58. package/scripts/gpu-texmem.mjs +98 -0
  59. package/scripts/ktx2-ab.mjs +111 -0
  60. package/scripts/map-bake-frames.d.mts +4 -0
  61. package/scripts/map-bake-frames.mjs +23 -0
  62. package/scripts/map-world.mjs +162 -0
  63. package/scripts/memory-product.mjs +62 -0
  64. package/scripts/music/export-midi.mjs +69 -0
  65. package/scripts/named-blob-output.d.mts +8 -0
  66. package/scripts/named-blob-output.mjs +48 -0
  67. package/scripts/practice/verify_unimate_skin.mjs +356 -0
  68. package/scripts/preparation-browser.mjs +25 -0
  69. package/scripts/preparation-seed.mjs +15 -0
  70. package/scripts/prepare-product.d.mts +14 -0
  71. package/scripts/prepare-product.mjs +133 -0
  72. package/scripts/prove-walk.mjs +83 -0
  73. package/scripts/push-tables.d.mts +1 -0
  74. package/scripts/push-tables.mjs +28 -0
  75. package/scripts/record-shard-mounts.mjs +133 -0
  76. package/scripts/section-inventory.ts +209 -0
  77. package/scripts/shard-build-pool.d.mts +4 -0
  78. package/scripts/shard-build-pool.mjs +53 -0
  79. package/scripts/shard-milestones.d.mts +15 -0
  80. package/scripts/shard-milestones.mjs +105 -0
  81. package/scripts/shard-progress.mjs +212 -0
  82. package/scripts/shardfile-cold-boot.mjs +79 -0
  83. package/scripts/shardfile-rolldown.d.mts +2 -0
  84. package/scripts/shardfile-rolldown.mjs +32 -0
  85. package/scripts/shardfile-vite.d.mts +4 -0
  86. package/scripts/shardfile-vite.mjs +20 -0
  87. package/scripts/site-facts.mjs +88 -0
  88. package/scripts/test-template-gate.mjs +44 -0
  89. package/scripts/tex-tiers.mjs +240 -0
  90. package/scripts/unused-assets.mjs +173 -0
  91. package/scripts/wildshard.d.mts +4 -0
  92. package/scripts/wildshard.mjs +146 -0
  93. package/scripts/witness-generation.d.mts +10 -0
  94. package/scripts/witness-generation.mjs +45 -0
  95. package/src/.oxlintrc.json +12 -0
  96. package/src/cli/bin.mjs +8 -0
  97. package/src/cli/content-command.ts +44 -0
  98. package/src/cli/content.ts +287 -0
  99. package/src/cli/grid/command.ts +48 -0
  100. package/src/cli/grid/grid.ts +155 -0
  101. package/src/cli/help.ts +262 -0
  102. package/src/cli/hero/adopt.ts +109 -0
  103. package/src/cli/install-home.ts +40 -0
  104. package/src/cli/main.ts +142 -0
  105. package/src/cli/version.ts +63 -0
  106. package/src/server/app.ts +19 -0
  107. package/src/server/serve.ts +49 -0
  108. package/src/sharddev/bake/json.mjs +84 -0
  109. package/src/sharddev/bake/mapRest.ts +57 -0
  110. package/src/sharddev/bake/nativeRaster.ts +106 -0
  111. package/src/sharddev/bake/source-loader.mjs +55 -0
  112. package/src/sharddev/bake/splatLayers.ts +29 -0
  113. package/src/sharddev/bootInventory.ts +132 -0
  114. package/src/sharddev/check.ts +125 -0
  115. package/src/sharddev/checkProject.ts +134 -0
  116. package/src/sharddev/cli.ts +207 -0
  117. package/src/sharddev/dev.ts +150 -0
  118. package/src/sharddev/devClient.ts +120 -0
  119. package/src/sharddev/devRoot.ts +6 -0
  120. package/src/sharddev/engineMusic.ts +23 -0
  121. package/src/sharddev/projectEntryProof.ts +32 -0
  122. package/src/sharddev/test/diskScriptScenario.ts +88 -0
  123. package/src/sharddev/test/scriptScenario.ts +254 -0
  124. package/src/sharddev/tsconfig.json +3 -0
  125. package/src/sharddev/watch/page.ts +288 -0
  126. package/src/sharddev/watch/pageEntry.ts +44 -0
  127. package/src/sharddev/watch/parity-baseline.json +22 -0
  128. package/src/sharddev/watch/parity.mjs +194 -0
  129. package/src/sharddev/watch/proof.mjs +199 -0
  130. package/src/sharddev/watch/socket.ts +57 -0
  131. package/src/sharddev/watch/watch.ts +382 -0
  132. package/src/shared/health.ts +10 -0
  133. package/src/tools/build-web.ts +59 -0
  134. package/src/web/app.tsx +53 -0
  135. package/src/web/index.html +12 -0
  136. package/src/web/main.tsx +10 -0
  137. package/tsconfig.author.json +25 -0
  138. package/tsconfig.json +47 -0
  139. package/README.md +0 -3
@@ -0,0 +1,262 @@
1
+ import { DEFAULT_BROTLI_LEVEL } from '@wildshard/upload/cli/upload/compress.ts'
2
+
3
+ // SHARD-AUTHORING SA2 (J317): every verb's help in the glossary's words (meta
4
+ // docs/architecture/README.md § Glossary): shard source, shard file, build
5
+ // (which bakes), check, hero, prepare, upload, channel, flip. Never product,
6
+ // publish (for an upload), promote, cook, head or tarball; `pack` only as the
7
+ // deprecated alias below. Flag names stay as they are, retired word or not:
8
+ // renaming one breaks scripts. help.test.ts greps every verb's help for the
9
+ // retired words. bin/wildshard.mjs prints `wildshard <verb> --help` from here.
10
+
11
+ const LEVEL = String(DEFAULT_BROTLI_LEVEL)
12
+
13
+ /** The deprecated alias's whole entry: the one place help may say pack. */
14
+ const PACK_ALIAS = `pack <folder> [--out <file>]
15
+ Deprecated alias: wildshard build <folder> [file]`
16
+
17
+ /** Each verb's entry: its usage lines, then what it does, indented. */
18
+ const VERBS: Readonly<Record<string, string>> = {
19
+ new: `new <dir> [slug] [--template sdk|scene] [--empty]
20
+ Start a shard repo in <dir>, a folder that does not
21
+ exist yet, with its shard source at src/ (slug: the
22
+ folder's name unless given). It copies the reference
23
+ world (--template sdk), or Mossgate Hollow as one
24
+ three.js scene module (--template scene; blender is
25
+ retired: Blender makes models, code makes the
26
+ shard). --empty writes a
27
+ bare shard source instead`,
28
+ update: `update [dir] [--pins[=<version>]]
29
+ Rewrite GUIDE.md and the four wildshard skills in
30
+ .claude/skills/ from the installed sdk (dir: the
31
+ shard repo, default the current folder). Adds the
32
+ .agents/skills links, AGENTS.md and CLAUDE.md if
33
+ missing; touches nothing else, and leaves an
34
+ AGENTS.md you changed (it says so). --pins first
35
+ moves the repo to a newer sdk (npm's latest, or
36
+ --pins=<version>): moves the pins, runs pnpm
37
+ install, applies the release's codemods, then
38
+ runs the new sdk's update and check`,
39
+ dev: `dev <source> [port]
40
+ Serve the shard source on localhost (port 0, the
41
+ default, picks a free one) and build it again on
42
+ every edit`,
43
+ watch: `watch <source> [port]
44
+ For a shard written as a three.js scene
45
+ (defineShard from @wildshard/sdk/scene/shard; GUIDE
46
+ section 2b): serve it, then swap each edited part
47
+ into the running page, no reload`,
48
+ check: `check <source> [folder] [--json]
49
+ Lint, build, validate, prove (with the shard
50
+ source's proof.json) and read the report card, then
51
+ give one verdict. --json prints only the verdict
52
+ document: { version, verdict, project, output, ms,
53
+ steps: [{ name, status, ms, note? }], refusals:
54
+ [{ step, rule, message, fix, guide, file? }],
55
+ warnings: [the same] }. Every refusal names its
56
+ rule, a fix and its GUIDE.md section. A warning (an
57
+ unprepared draft) does not fail the verdict. Exits 1
58
+ on fail`,
59
+ hero: `hero <source> --base <served-build-url>
60
+ Capture the shard's hero (thumb, portrait,
61
+ landscape) in headless Chromium from a served build
62
+ of this candidate (the URL \`wildshard dev .\` prints),
63
+ and stamp hero.json with its content
64
+ hero <source> --stamp-existing
65
+ No capture: stamp the hero images already in the
66
+ shard source as current. WARNING: use it ONLY when
67
+ those images show the current content; a wrong
68
+ stamp hides a stale hero from the cut`,
69
+ upload: `upload <file> --channel staging|prod [--server <url>]
70
+ [--level <n>] [--version <X.Y.Z>] [--commit <sha>] [--no-place] [--no-wait]
71
+ Check a shard file (an unprepared draft, sdk 0.2,
72
+ is refused before anything is sent), compress it
73
+ (Brotli level <n>, default ${LEVEL}) and upload it
74
+ with your account credential. The channel
75
+ is required: staging flips the preview and staging
76
+ pointers, prod flips all three (production too).
77
+ Sends the shard source version (default: the shard
78
+ source's package.json version), the shard source
79
+ commit (default: the checked-out commit of a clean
80
+ tree) and the sdk, engine and shard-format releases
81
+ it was built with. Refuses a hero unchanged since
82
+ the shard's newest upload (run hero first). Prints
83
+ the API's version, format version and migrations,
84
+ then the grid: the shard's cell ("placed at (0,3)
85
+ on preview, staging"), "grid full, not placed",
86
+ "not placed (--no-place)", or "no new cell" while
87
+ the API's placement is off or past the shard's
88
+ first upload; then the /slug/<slug> link on each
89
+ channel the upload moved (that page is not built
90
+ yet). --no-place takes no grid cell, for a proof
91
+ upload. Only a shard's first upload takes a cell,
92
+ so one uploaded with --no-place never gets one; on
93
+ a later upload --no-place leaves the grid as it
94
+ was, so a prod upload adds no production cell.
95
+ Async uploads show progress until live.
96
+ A refusal prints the full validation report and
97
+ exits non-zero; a stall or 20-minute timeout also
98
+ exits non-zero. --no-wait prints the upload id
99
+ immediately. Read it later without uploading:
100
+ upload status <id> [--server <url>].
101
+ Sends your account key (WILDSHARD_API_KEY, else
102
+ the file wildshard account saved; with neither it
103
+ refuses before anything is sent). Reads
104
+ WILDSHARD_API_URL when --server is absent,
105
+ optionally signs with WILDSHARD_CREATOR_PRIVATE_KEY,
106
+ and reads
107
+ VERCEL_AUTOMATION_BYPASS_SECRET for a protected
108
+ preview`,
109
+ account: `account <email> [--server <url>] [--force]
110
+ Make your Wildshard account (no mail is sent) and
111
+ save its key to ~/.config/wildshard/sharddev-key
112
+ (mode 600) for upload to send. The API shows a key
113
+ once: an email that has an account is refused, and
114
+ a lost key needs an operator reset. A saved key is
115
+ never replaced without --force. Reads
116
+ WILDSHARD_API_URL when --server is absent`,
117
+ whoami: `whoami [--server <url>]
118
+ Print where upload's account key comes from
119
+ (WILDSHARD_API_KEY, else the key file) and its
120
+ first characters, never the whole key, then the
121
+ key's account: its email and how many slugs it
122
+ owns. Reads WILDSHARD_API_URL when --server is
123
+ absent`,
124
+ grid: `grid [--channel staging|prod|preview] [--server <url>]
125
+ Print the world grid on a channel (default
126
+ staging): each taken cell (x,z) and its shard, then
127
+ the free cells. Reads the public
128
+ GET /api/catalogue.json?channel=<channel> (prod is
129
+ production); no key. Reads WILDSHARD_API_URL when
130
+ --server is absent, else https://api.wildshard.io`,
131
+ delete: `delete <slug> [--yes] [--server <url>]
132
+ Delete your shard: it leaves the catalogue, every
133
+ channel and the grid at once. Prints what it would
134
+ delete (its versions, the channels pointing at it,
135
+ and whether a signed release still plays it until
136
+ its next release), then asks you to type the slug;
137
+ anything else deletes nothing. The confirmation
138
+ lasts 10 minutes. --yes skips typing, for scripts.
139
+ Sends your account key, as upload does; only the
140
+ key that uploaded the shard deletes it. Reads
141
+ WILDSHARD_API_URL when --server is absent`,
142
+ build: `build <source> [folder] [--shardfile-only | --folder-only]
143
+ [--no-placeholders] [--output=<slug>]
144
+ Build the shard source: bake it into a shard file
145
+ folder (default <source>/public/shardfiles/<slug>),
146
+ then write the shard file <slug>.shardfile beside
147
+ it and run shard-format's checks on it. Refuses a
148
+ shard whose captured hero is older than its content
149
+ (hero.json) and prints the audio rules. What it
150
+ writes is a draft (sdk 0.2): it warns that the API
151
+ and upload refuse a draft until prepare makes it
152
+ sdk 0.3. --shardfile-only skips the web client;
153
+ --folder-only also skips the shard file
154
+ build <folder> [file]
155
+ Write the shard file of a built shard file folder
156
+ (default <slug>.shardfile beside it), with the same
157
+ checks
158
+ build <source> --behaviour-only [--check]
159
+ Build only the shard source's native behaviour
160
+ outputs; --check refuses stale ones and writes
161
+ nothing`,
162
+ memory: `memory <folder> [--out=<report.json>]
163
+ Boot the built shard on the installed engine's
164
+ phone-tier preparation client. Print the measured
165
+ peak and fail above the 1.5 GB phone line.`,
166
+ prepare: `prepare <folder> [--base <exact-preview-url>]
167
+ Record the shard file folder in phone WebKit against
168
+ engine's preparation client and write its author
169
+ preparation (the fence, the fence policy and the
170
+ recorded programs): the draft becomes sdk 0.3, the
171
+ only kind upload sends. Then write its shard file
172
+ with build <folder>. The client is fetched once from
173
+ engine's release at this package's pin; --base
174
+ records against an exact engine preview instead`,
175
+ validate: `validate <source | folder | shard.json>
176
+ Validate a shard source, or a built shard file
177
+ folder with shard-format's checks and its static
178
+ budgets (check runs it headlessly)`,
179
+ prove: `prove <source | folder | shard.json> <proof.json>
180
+ Play the proof tape headlessly and print what
181
+ happened as JSON. check plays src/proof.json the
182
+ same way. A tape is
183
+ { "version": 1,
184
+ "tape": [[tick 0's commands], [tick 1's], ...],
185
+ "checkpointTick": 60,
186
+ "requiredFacts": ["<a quest's onComplete.fact>"] }
187
+ 60 ticks a second, up to 4096 ticks. A command is
188
+ { "kind": "player", "moveX": 0, "moveZ": -1,
189
+ "yaw": 0 } (the stick from -1 to 1, the facing in
190
+ radians; add "jump": true, "dodge": true or
191
+ "attack": { "targetId": "<id>" } for a press), or
192
+ { "kind": "interact", "id": "<interaction id>" }.
193
+ At checkpointTick prove saves, unloads and reloads
194
+ the cell; every required fact must be filed by the
195
+ end. GUIDE.md "Proof tapes" has the rest.
196
+ prove <source> <walk.mjs> --base <dev url>
197
+ Play a walk proof on a \`wildshard dev\` page in
198
+ headless Chromium: its default export gets talk,
199
+ choose, walkTo, fight, expectFlags, expectQuest
200
+ and state, and plays the shard by name (walk to an
201
+ NPC, answer it by choice id or words). Prints a
202
+ JSON report; GUIDE.md "Walk proofs" has the rest`,
203
+ synth: `synth <source>
204
+ Run shard.config.ts's scene and identity exports
205
+ (export const scene, a three.js Scene, and export
206
+ const identity) in Node and write the scene they
207
+ describe as data. A defineShard shard
208
+ (@wildshard/sdk/scene/shard) needs no synth: check
209
+ builds it and watch shows it`,
210
+ schema: `schema [list|shardfile|<root>] [JSON-pointer]
211
+ Print the JSON Schema of shard.json (\`shardfile\`) or
212
+ of one section (<root>), or of the part at a JSON
213
+ pointer; list names every root`,
214
+ serve: `serve [--port <n>] Start the sharddev server on localhost`,
215
+ 'build-shards': `build-shards [--shard=<slug>[,<slug>]] [--reuse]
216
+ Build every shard source under src/shards into its
217
+ shard file folders (one per output) under out/.
218
+ --shard builds only those outputs; --reuse keeps a
219
+ folder whose inputs are unchanged`,
220
+ content: `content <built-shard-dir> [--bar templates]
221
+ Count player-facing content in a built shard's sections.
222
+ --bar templates checks the template content minimums
223
+ and names every short line`,
224
+ pack: PACK_ALIAS,
225
+ }
226
+
227
+ /** Indent every line of a verb's entry for the full help. */
228
+ function indented(entry: string): string {
229
+ return entry
230
+ .split('\n')
231
+ .map((line: string): string => (line.startsWith(' ') ? line : ` ${line}`))
232
+ .join('\n')
233
+ }
234
+
235
+ const USAGE = `Usage: wildshard <command> [options]
236
+
237
+ The loop: new, dev, check, hero, upload. A shard source builds a shard file;
238
+ upload sends it to the API for a channel.
239
+
240
+ Commands:
241
+ ${Object.values(VERBS)
242
+ .map((entry: string): string => indented(entry))
243
+ .join('\n')}
244
+
245
+ Options:
246
+ --version Print the sdk, engine, shard-format and three
247
+ versions (after upload: the shard source version)
248
+ --help Print this help (after a command: that command's)
249
+
250
+ Also installed as \`sharddev\`. wildshard help <command> prints one command.
251
+ `
252
+
253
+ /** The verbs help knows, in the order the full help lists them. */
254
+ const HELP_VERBS: readonly string[] = Object.keys(VERBS)
255
+
256
+ /** One verb's help, or undefined for a verb help does not know. */
257
+ function verbHelp(verb: string): string | undefined {
258
+ const entry = Object.hasOwn(VERBS, verb) ? VERBS[verb] : undefined
259
+ return entry === undefined ? undefined : `Usage: wildshard ${entry}\n`
260
+ }
261
+
262
+ export { HELP_VERBS, PACK_ALIAS, USAGE, verbHelp }
@@ -0,0 +1,109 @@
1
+ import { access } from 'node:fs/promises'
2
+ import path from 'node:path'
3
+
4
+ import {
5
+ MANIFEST,
6
+ NONE,
7
+ STAMP,
8
+ heroSlotFiles,
9
+ heroState,
10
+ isMissing,
11
+ readJson,
12
+ writeHeroStamp,
13
+ } from '@wildshard/upload/cli/hero/stamp.ts'
14
+
15
+ // `wildshard hero <shard> --stamp-existing`: a shard repo gains the hero check
16
+ // (stamp.ts) when it bumps its sharddev pin, with curated heroes and no stamp.
17
+ // Recapturing from the spawn view would put a plain shot over good art, so
18
+ // this stamps the files already there, with no capture. Only right when those
19
+ // images show the current content. A stamp whose content no longer matches is
20
+ // refused: there the world has moved past the picture, and only a capture fixes
21
+ // it.
22
+
23
+ const ADOPTED =
24
+ 'stamp-existing: the hero files already in the shard, adopted without a capture'
25
+
26
+ interface Adopted {
27
+ /** False when the stamp was already current and nothing was written. */
28
+ readonly written: boolean
29
+ readonly content: string
30
+ }
31
+
32
+ async function exists(file: string): Promise<boolean> {
33
+ try {
34
+ await access(file)
35
+ return true
36
+ } catch (error: unknown) {
37
+ if (isMissing(error)) {
38
+ return false
39
+ }
40
+ throw error
41
+ }
42
+ }
43
+
44
+ /** Refuse a generated card or a card file that is not on disk. */
45
+ async function assertCardFiles(shard: string): Promise<void> {
46
+ const files = Object.entries(await heroSlotFiles(shard))
47
+ if (files.length === NONE) {
48
+ throw new Error(
49
+ `${path.join(shard, MANIFEST)}: the card is generated (data: urls), so there are no hero files to stamp`,
50
+ )
51
+ }
52
+ const present = await Promise.all(
53
+ files.map(
54
+ async ([, file]: readonly [string, string]): Promise<boolean> =>
55
+ await exists(file),
56
+ ),
57
+ )
58
+ const gone = files.filter(
59
+ (_entry: unknown, at: number): boolean => present[at] !== true,
60
+ )
61
+ if (gone.length > NONE) {
62
+ const named = gone.map(
63
+ ([slot, file]: readonly [string, string]): string =>
64
+ `card.${slot} (${path.relative(shard, file).split(path.sep).join('/')})`,
65
+ )
66
+ throw new Error(`${named.join(', ')} not there; nothing stamped`)
67
+ }
68
+ }
69
+
70
+ /** Refuse a hero.json that does not parse: it may declare a camera. */
71
+ async function assertStampReadable(shard: string): Promise<void> {
72
+ try {
73
+ await readJson(path.join(shard, STAMP))
74
+ } catch (error: unknown) {
75
+ throw new Error(
76
+ `${path.join(shard, STAMP)} does not parse; fix it by hand, nothing stamped`,
77
+ { cause: error },
78
+ )
79
+ }
80
+ }
81
+
82
+ /**
83
+ * Stamp the hero files on disk as showing the content now, keeping a
84
+ * declared camera. Only an unstamped hero, or hand-swapped hero files over
85
+ * unchanged content, is stamped; a current stamp is left alone.
86
+ */
87
+ async function stampExistingHero(shard: string): Promise<Adopted> {
88
+ await assertCardFiles(shard)
89
+ await assertStampReadable(shard)
90
+ const hero = await heroState(shard)
91
+ if (hero.state === 'fresh') {
92
+ return { written: false, content: hero.content }
93
+ }
94
+ // A curated hero (hero.json "curated": true) is hand-picked art that no
95
+ // spawn-view capture should replace: it is re-stamped over new content.
96
+ if (
97
+ hero.curated !== true &&
98
+ hero.stamped !== undefined &&
99
+ hero.stamped !== hero.content
100
+ ) {
101
+ throw new Error(
102
+ `the hero of ${path.basename(shard)} was stamped for other content (captured ${hero.captured ?? 'at an unknown time'}); the world has changed since, so only a capture fixes it, nothing stamped`,
103
+ )
104
+ }
105
+ const stamp = await writeHeroStamp(shard, { base: ADOPTED })
106
+ return { written: true, content: stamp.content }
107
+ }
108
+
109
+ export { stampExistingHero }
@@ -0,0 +1,40 @@
1
+ import path from 'node:path'
2
+
3
+ // SDK-SPLIT SP-NE1 (NEW-SHARD-E2E F1): in a folder with no package.json,
4
+ // `npm install @wildshard/sdk` installs into the nearest folder above that
5
+ // has one, often the home folder, so the intended folder stays empty and
6
+ // `npx wildshard` quietly runs the home folder's copy. The GUIDE says to run
7
+ // `npm init -y` first; this is the CLI saying it at the moment it matters.
8
+
9
+ interface Install {
10
+ /** The running sdk's package folder (bin's parent). */
11
+ readonly sdk: string
12
+ readonly cwd: string
13
+ readonly home: string
14
+ }
15
+
16
+ /** The folder whose node_modules holds the sdk, through pnpm's store paths. */
17
+ function installingFolder(sdk: string): string | undefined {
18
+ const normal = path.normalize(sdk)
19
+ const marker = `${path.sep}node_modules${path.sep}`
20
+ const [folder] = normal.split(marker)
21
+ return normal.includes(marker) ? folder : undefined
22
+ }
23
+
24
+ /** Why `wildshard` running from the home folder's install is likely a mistake, or undefined. */
25
+ export function homeInstallWarning(install: Install): string | undefined {
26
+ const home = path.normalize(install.home)
27
+ const cwd = path.normalize(install.cwd)
28
+ if (installingFolder(install.sdk) !== home || cwd === home) {
29
+ return undefined
30
+ }
31
+ if (!cwd.startsWith(`${home}${path.sep}`)) {
32
+ return undefined
33
+ }
34
+ return (
35
+ 'wildshard: this sdk is installed in your home folder, not in this one ' +
36
+ '(npm installs into the nearest folder above that has a package.json). ' +
37
+ 'Run `npm init -y` here, then install @wildshard/sdk again (GUIDE.md, ' +
38
+ '"Running wildshard today").\n'
39
+ )
40
+ }
@@ -0,0 +1,142 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { fileURLToPath } from 'node:url'
4
+
5
+ import {
6
+ runAccount,
7
+ runDelete,
8
+ runWhoami,
9
+ } from '@wildshard/upload/cli/account/command.ts'
10
+ import { parseCliArgs } from '@wildshard/upload/cli/args.ts'
11
+ import {
12
+ runPack,
13
+ runShardfile,
14
+ } from '@wildshard/upload/cli/shardfile/command.ts'
15
+ import { runUpload } from '@wildshard/upload/cli/upload/command.ts'
16
+
17
+ import { serve } from '../server/serve.ts'
18
+ import { USAGE, verbHelp } from './help.ts'
19
+ import { readVersion, readVersionChain } from './version.ts'
20
+
21
+ import type { CliArgs } from '@wildshard/upload/cli/args.ts'
22
+
23
+ /** The sdk package's folder: the engine and shard-format resolve from here when the shard has none (SP2b). */
24
+ const SDK_DIR = fileURLToPath(new URL('../..', import.meta.url))
25
+
26
+ const EXIT_OK = 0
27
+ const EXIT_USAGE = 1
28
+ const EXIT_CRASH = 2
29
+
30
+ // Arguments start after [node, script] in process.argv.
31
+ const FIRST_CLI_ARG = 2
32
+
33
+ const DEFAULT_PORT = 4403
34
+ const MIN_PORT = 0
35
+ const MAX_PORT = 65_535
36
+
37
+ // The CLI is the one place that reads the environment; it hands it on.
38
+ // oxlint-disable-next-line node/no-process-env -- the CLI is the env boundary
39
+ const ENV: Readonly<Record<string, string | undefined>> = process.env
40
+
41
+ function parsePort(raw: string | undefined): number | undefined {
42
+ if (raw === undefined) {
43
+ return DEFAULT_PORT
44
+ }
45
+ const port = Number(raw)
46
+ return Number.isInteger(port) && port >= MIN_PORT && port <= MAX_PORT
47
+ ? port
48
+ : undefined
49
+ }
50
+
51
+ async function runServe(rawPort: string | undefined): Promise<number> {
52
+ const port = parsePort(rawPort)
53
+ if (port === undefined) {
54
+ process.stderr.write(`sharddev: invalid --port ${String(rawPort)}\n`)
55
+ return EXIT_USAGE
56
+ }
57
+ const server = await serve({ port, version: await readVersion() })
58
+ process.stdout.write(`sharddev serving on ${server.url}\n`)
59
+ return EXIT_OK
60
+ }
61
+
62
+ function serverOf(args: CliArgs): string {
63
+ return args.server ?? ENV['WILDSHARD_API_URL'] ?? ''
64
+ }
65
+
66
+ async function printVersion(): Promise<number> {
67
+ const chain = await readVersionChain()
68
+ process.stdout.write(`${chain.join('\n')}\n`)
69
+ return EXIT_OK
70
+ }
71
+
72
+ function printUsage(code: number): number {
73
+ process.stdout.write(USAGE)
74
+ return code
75
+ }
76
+
77
+ /** `--help`: the command's own help, or all of it. */
78
+ function printHelp(command: string | undefined): number {
79
+ process.stdout.write(
80
+ (command === undefined ? undefined : verbHelp(command)) ?? USAGE,
81
+ )
82
+ return EXIT_OK
83
+ }
84
+
85
+ /** The commands this program runs; the author commands run in src/sharddev/cli.ts. */
86
+ const COMMANDS: Readonly<Record<string, (args: CliArgs) => Promise<number>>> = {
87
+ serve: async (args: CliArgs): Promise<number> => await runServe(args.port),
88
+ // SA3: a built shard file folder; bin/wildshard.mjs sends a project to the author CLI.
89
+ build: async (args: CliArgs): Promise<number> =>
90
+ await runShardfile('build', args.operand, args.target ?? args.out),
91
+ pack: async (args: CliArgs): Promise<number> =>
92
+ await runPack(args.operand, args.out ?? args.target),
93
+ upload: async (args: CliArgs): Promise<number> =>
94
+ await runUpload(args, ENV, {
95
+ version: await readVersion(),
96
+ installDir: SDK_DIR,
97
+ }),
98
+ // Meta SHARD-DELETE DEL6: the account key upload sends.
99
+ account: async (args: CliArgs): Promise<number> =>
100
+ await runAccount(args, serverOf(args)),
101
+ whoami: async (args: CliArgs): Promise<number> =>
102
+ await runWhoami(ENV['WILDSHARD_API_KEY'], serverOf(args)),
103
+ // Meta SHARD-DELETE DEL10: the owner deletes with the same key.
104
+ delete: async (args: CliArgs): Promise<number> =>
105
+ await runDelete({
106
+ args,
107
+ server: serverOf(args),
108
+ fromEnv: ENV['WILDSHARD_API_KEY'],
109
+ }),
110
+ }
111
+
112
+ async function runCommand(args: CliArgs): Promise<number> {
113
+ if (args.command === undefined) {
114
+ return printUsage(EXIT_USAGE)
115
+ }
116
+ const run = Object.hasOwn(COMMANDS, args.command)
117
+ ? COMMANDS[args.command]
118
+ : undefined
119
+ if (run !== undefined) {
120
+ return await run(args)
121
+ }
122
+ process.stderr.write(`sharddev: unknown command ${args.command}\n\n${USAGE}`)
123
+ return EXIT_USAGE
124
+ }
125
+
126
+ async function main(argv: readonly string[]): Promise<number> {
127
+ const args = parseCliArgs(argv)
128
+ if (args.version) {
129
+ return await printVersion()
130
+ }
131
+ if (args.help) {
132
+ return printHelp(args.command)
133
+ }
134
+ return await runCommand(args)
135
+ }
136
+
137
+ try {
138
+ process.exitCode = await main(process.argv.slice(FIRST_CLI_ARG))
139
+ } catch (error: unknown) {
140
+ process.stderr.write(`sharddev: ${String(error)}\n`)
141
+ process.exitCode = EXIT_CRASH
142
+ }
@@ -0,0 +1,63 @@
1
+ import { access, readFile } from 'node:fs/promises'
2
+ import { createRequire } from 'node:module'
3
+ import path from 'node:path'
4
+ import { fileURLToPath } from 'node:url'
5
+
6
+ import { object, parse, string } from 'valibot'
7
+
8
+ const PackageJsonSchema = object({ version: string() })
9
+
10
+ // The package root is the repo root: package.json beside src/.
11
+ const PACKAGE_JSON = fileURLToPath(
12
+ new URL('../../package.json', import.meta.url),
13
+ )
14
+
15
+ /** The packages `--version` names, in the order they build on each other (SA4). */
16
+ const CHAIN = ['@wildshard/engine', '@wildshard/format', 'three'] as const
17
+
18
+ async function versionAt(file: string): Promise<string> {
19
+ const raw: unknown = JSON.parse(await readFile(file, 'utf8'))
20
+ return parse(PackageJsonSchema, raw).version
21
+ }
22
+
23
+ async function readVersion(): Promise<string> {
24
+ return await versionAt(PACKAGE_JSON)
25
+ }
26
+
27
+ async function exists(file: string): Promise<boolean> {
28
+ try {
29
+ await access(file)
30
+ return true
31
+ } catch {
32
+ return false
33
+ }
34
+ }
35
+
36
+ /** Not every package exports ./package.json: walk node's own lookup dirs. */
37
+ async function manifestOf(name: string): Promise<string> {
38
+ const dirs = createRequire(PACKAGE_JSON).resolve.paths(name) ?? []
39
+ for (const dir of dirs) {
40
+ const file = path.join(dir, name, 'package.json')
41
+ // oxlint-disable-next-line no-await-in-loop -- the first hit wins, in order
42
+ if (await exists(file)) {
43
+ return file
44
+ }
45
+ }
46
+ throw new Error(`cannot find ${name}`)
47
+ }
48
+
49
+ /**
50
+ * The sdk, engine, shard-format and `three` chain this installed sdk
51
+ * resolves, one `<name> <version>` line each (meta SHARD-AUTHORING SA4).
52
+ */
53
+ async function readVersionChain(): Promise<string[]> {
54
+ const rows = await Promise.all(
55
+ CHAIN.map(
56
+ async (name: string): Promise<string> =>
57
+ `${name} ${await versionAt(await manifestOf(name))}`,
58
+ ),
59
+ )
60
+ return [`@wildshard/sdk ${await readVersion()}`, ...rows]
61
+ }
62
+
63
+ export { readVersion, readVersionChain }
@@ -0,0 +1,19 @@
1
+ import { Hono } from 'hono'
2
+
3
+ import type { Health } from '../shared/health.ts'
4
+ import type { Context } from 'hono'
5
+
6
+ interface AppOptions {
7
+ readonly version: string
8
+ }
9
+
10
+ export function createApp(options: AppOptions): Hono {
11
+ const app = new Hono()
12
+
13
+ app.get('/api/health', (context: Context): Response => {
14
+ const body: Health = { ok: true, version: options.version }
15
+ return context.json(body)
16
+ })
17
+
18
+ return app
19
+ }