@wildshard/dev 0.0.0-stage → 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.
- package/bin/wildshard.mjs +75 -0
- package/lint/host-callbacks.d.mts +6 -0
- package/lint/host-callbacks.mjs +123 -0
- package/lint/ratchet.json +3 -0
- package/package.json +101 -3
- package/scripts/audit-assets.d.mts +10 -0
- package/scripts/audit-assets.mjs +151 -0
- package/scripts/bake/coatFiles.d.mts +6 -0
- package/scripts/bake/coatFiles.mjs +37 -0
- package/scripts/bake/navmeshGround.ts +22 -0
- package/scripts/bake/near-placeholder.mjs +331 -0
- package/scripts/bake/viewmodelBytes.ts +26 -0
- package/scripts/bake/viewmodelPage.ts +11 -0
- package/scripts/bake-catalogue.mjs +44 -0
- package/scripts/bake-check.mjs +54 -0
- package/scripts/bake-chunk.mjs +124 -0
- package/scripts/bake-cloud-field.mjs +24 -0
- package/scripts/bake-coats.mjs +110 -0
- package/scripts/bake-data-maps.d.mts +24 -0
- package/scripts/bake-data-maps.mjs +78 -0
- package/scripts/bake-entry-programs.mjs +126 -0
- package/scripts/bake-geometry.mjs +106 -0
- package/scripts/bake-ktx2.mjs +477 -0
- package/scripts/bake-map-glb.mjs +127 -0
- package/scripts/bake-map-rest.d.mts +7 -0
- package/scripts/bake-map-rest.mjs +50 -0
- package/scripts/bake-maps.mjs +200 -0
- package/scripts/bake-navmesh.mjs +259 -0
- package/scripts/bake-packs.mjs +129 -0
- package/scripts/bake-pickups.mjs +102 -0
- package/scripts/bake-query-terrain.mjs +64 -0
- package/scripts/bake-textures.mjs +80 -0
- package/scripts/bake-viewmodel-sets.mjs +137 -0
- package/scripts/bake-voxel-ao.mjs +119 -0
- package/scripts/bake-water-ripples.mjs +25 -0
- package/scripts/browser-imports.d.mts +2 -0
- package/scripts/browser-imports.mjs +40 -0
- package/scripts/browser-machine-loader-proof.mjs +39 -0
- package/scripts/browser-machine-loader.d.mts +8 -0
- package/scripts/browser-machine-loader.mjs +87 -0
- package/scripts/browser-playwright.d.mts +10 -0
- package/scripts/browser-playwright.mjs +5 -0
- package/scripts/browser-test.d.mts +4 -0
- package/scripts/browser-test.mjs +18 -0
- package/scripts/build-sdk.mjs +95 -0
- package/scripts/build-shardfiles.d.mts +7 -0
- package/scripts/build-shardfiles.mjs +230 -0
- package/scripts/capture-hero.mjs +211 -0
- package/scripts/chromium-keychain.d.mts +1 -0
- package/scripts/chromium-keychain.mjs +7 -0
- package/scripts/entry-reads/crawl.ts +152 -0
- package/scripts/gen-host-catalogue.d.mts +14 -0
- package/scripts/gen-host-catalogue.mjs +108 -0
- package/scripts/gen-shards.d.mts +17 -0
- package/scripts/gen-shards.mjs +311 -0
- package/scripts/goldens/plot-inputs.d.mts +12 -0
- package/scripts/goldens/plot-inputs.mjs +46 -0
- package/scripts/gpu-texmem.mjs +98 -0
- package/scripts/ktx2-ab.mjs +111 -0
- package/scripts/map-bake-frames.d.mts +4 -0
- package/scripts/map-bake-frames.mjs +23 -0
- package/scripts/map-world.mjs +162 -0
- package/scripts/memory-product.mjs +62 -0
- package/scripts/music/export-midi.mjs +69 -0
- package/scripts/named-blob-output.d.mts +8 -0
- package/scripts/named-blob-output.mjs +48 -0
- package/scripts/practice/verify_unimate_skin.mjs +356 -0
- package/scripts/preparation-browser.mjs +25 -0
- package/scripts/preparation-seed.mjs +15 -0
- package/scripts/prepare-product.d.mts +14 -0
- package/scripts/prepare-product.mjs +133 -0
- package/scripts/prove-walk.mjs +83 -0
- package/scripts/push-tables.d.mts +1 -0
- package/scripts/push-tables.mjs +28 -0
- package/scripts/record-shard-mounts.mjs +133 -0
- package/scripts/section-inventory.ts +209 -0
- package/scripts/shard-build-pool.d.mts +4 -0
- package/scripts/shard-build-pool.mjs +53 -0
- package/scripts/shard-milestones.d.mts +15 -0
- package/scripts/shard-milestones.mjs +105 -0
- package/scripts/shard-progress.mjs +212 -0
- package/scripts/shardfile-cold-boot.mjs +79 -0
- package/scripts/shardfile-rolldown.d.mts +2 -0
- package/scripts/shardfile-rolldown.mjs +32 -0
- package/scripts/shardfile-vite.d.mts +4 -0
- package/scripts/shardfile-vite.mjs +20 -0
- package/scripts/site-facts.mjs +88 -0
- package/scripts/test-template-gate.mjs +44 -0
- package/scripts/tex-tiers.mjs +240 -0
- package/scripts/unused-assets.mjs +173 -0
- package/scripts/wildshard.d.mts +4 -0
- package/scripts/wildshard.mjs +146 -0
- package/scripts/witness-generation.d.mts +10 -0
- package/scripts/witness-generation.mjs +45 -0
- package/src/.oxlintrc.json +12 -0
- package/src/cli/bin.mjs +8 -0
- package/src/cli/content-command.ts +44 -0
- package/src/cli/content.ts +287 -0
- package/src/cli/grid/command.ts +48 -0
- package/src/cli/grid/grid.ts +155 -0
- package/src/cli/help.ts +262 -0
- package/src/cli/hero/adopt.ts +109 -0
- package/src/cli/install-home.ts +40 -0
- package/src/cli/main.ts +142 -0
- package/src/cli/version.ts +63 -0
- package/src/server/app.ts +19 -0
- package/src/server/serve.ts +49 -0
- package/src/sharddev/bake/json.mjs +84 -0
- package/src/sharddev/bake/mapRest.ts +57 -0
- package/src/sharddev/bake/nativeRaster.ts +106 -0
- package/src/sharddev/bake/source-loader.mjs +55 -0
- package/src/sharddev/bake/splatLayers.ts +29 -0
- package/src/sharddev/bootInventory.ts +132 -0
- package/src/sharddev/check.ts +125 -0
- package/src/sharddev/checkProject.ts +134 -0
- package/src/sharddev/cli.ts +207 -0
- package/src/sharddev/dev.ts +150 -0
- package/src/sharddev/devClient.ts +120 -0
- package/src/sharddev/devRoot.ts +6 -0
- package/src/sharddev/engineMusic.ts +23 -0
- package/src/sharddev/projectEntryProof.ts +32 -0
- package/src/sharddev/test/diskScriptScenario.ts +88 -0
- package/src/sharddev/test/scriptScenario.ts +254 -0
- package/src/sharddev/tsconfig.json +3 -0
- package/src/sharddev/watch/page.ts +288 -0
- package/src/sharddev/watch/pageEntry.ts +44 -0
- package/src/sharddev/watch/parity-baseline.json +22 -0
- package/src/sharddev/watch/parity.mjs +194 -0
- package/src/sharddev/watch/proof.mjs +199 -0
- package/src/sharddev/watch/socket.ts +57 -0
- package/src/sharddev/watch/watch.ts +382 -0
- package/src/shared/health.ts +10 -0
- package/src/tools/build-web.ts +59 -0
- package/src/web/app.tsx +53 -0
- package/src/web/index.html +12 -0
- package/src/web/main.tsx +10 -0
- package/tsconfig.author.json +25 -0
- package/tsconfig.json +47 -0
- package/README.md +0 -3
package/src/cli/help.ts
ADDED
|
@@ -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
|
+
}
|
package/src/cli/main.ts
ADDED
|
@@ -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
|
+
}
|