@wildshard/sdk 0.2.3 → 0.2.5
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/GUIDE.md +178 -18
- package/bin/wildshard.mjs +1 -1
- package/codemods/0.2.5.mjs +12 -0
- package/lint/ratchet.json +1 -9
- package/lint/sdk-plugin.mjs +24 -2
- package/package.json +4 -3
- package/scripts/gen-format-schema.mjs +1 -1
- package/scripts/wildshard.mjs +8 -2
- package/skills/wildshard-upgrade/SKILL.md +15 -22
- package/src/cli/audio/audio.ts +17 -2
- package/src/cli/help.ts +11 -0
- package/src/cli/main.ts +1 -2
- package/src/cli/report.ts +8 -4
- package/src/cli/shardfile/command.ts +1 -2
- package/src/sharddev/agentFiles.ts +127 -0
- package/src/sharddev/author.ts +16 -3
- package/src/sharddev/bake/authoredWorld.ts +1 -1
- package/src/sharddev/bake/specimenCatalogue.ts +1 -1
- package/src/sharddev/bake/staticMaterials.ts +1 -1
- package/src/sharddev/check.ts +7 -6
- package/src/sharddev/checkProject.ts +4 -3
- package/src/sharddev/cli.ts +18 -5
- package/src/sharddev/formatJsonSchema.ts +1117 -3
- package/src/sharddev/kit/bakedGeometry.ts +58 -12
- package/src/sharddev/nativePopulationRows.ts +1 -1
- package/src/sharddev/newProject.ts +4 -25
- package/src/sharddev/performancePolicy.ts +16 -5
- package/src/sharddev/phasedBoss.ts +212 -34
- package/src/sharddev/project.ts +1 -1
- package/src/sharddev/projectEntryProof.ts +1 -1
- package/src/sharddev/projectGeneration.ts +1 -1
- package/src/sharddev/projectOutput.ts +1 -1
- package/src/sharddev/projectSections.ts +1 -1
- package/src/sharddev/refusals.ts +92 -18
- package/src/sharddev/reportCard.ts +1 -1
- package/src/sharddev/sections.ts +1 -1
- package/src/sharddev/species/clips.ts +64 -24
- package/src/sharddev/speciesBrains.ts +98 -15
- package/src/sharddev/updatePins.ts +254 -0
- package/src/sharddev/weapons/bowProfile.ts +3 -3
- package/src/sharddev/weapons/meleeProfile.ts +48 -4
- package/src/sharddev/worldScenes.ts +1 -1
- package/tsconfig.author.json +1 -0
package/GUIDE.md
CHANGED
|
@@ -34,7 +34,7 @@ repo's one `src/shards/<slug>/`).
|
|
|
34
34
|
|
|
35
35
|
| # | Step | Command | Today |
|
|
36
36
|
|---|---|---|---|
|
|
37
|
-
| 1 | Start | `wildshard new my-shard` | Works. Writes a shard repo in `my-shard/`: the reference world (Template 1, Mossgate) as its shard source at `src/`, plus `package.json`, `tsconfig.json`, `.gitignore`, `.npmrc`, a README, this guide
|
|
37
|
+
| 1 | Start | `wildshard new my-shard` | Works. Writes a shard repo in `my-shard/`: the reference world (Template 1, Mossgate) as its shard source at `src/`, plus `package.json`, `tsconfig.json`, `.gitignore`, `.npmrc`, a README, this guide, the four `wildshard` skills and the agent files (`AGENTS.md`, `CLAUDE.md`, `.agents/skills/`) |
|
|
38
38
|
| 2 | Walk it | `wildshard dev .` | **Not built yet (SA15).** See "Walking your shard" below |
|
|
39
39
|
| 3 | Check | `wildshard check .` | Works: lint, build, validate, prove and the report card, one verdict |
|
|
40
40
|
| 4 | Hero | `wildshard hero . --base <url>` | Works only with an engine checkout: it needs your shard in a served engine build. See "The hero" below |
|
|
@@ -53,6 +53,7 @@ with `rule`, `fix` and `guide`) for agents and scripts.
|
|
|
53
53
|
| Verb | What it is for |
|
|
54
54
|
|---|---|
|
|
55
55
|
| `wildshard new <dir> [slug] [--template sdk\|blender] [--empty]` | Start a shard repo in a folder that does not exist yet, its shard source at `src/`. The slug is the folder's name unless you give one. `--template sdk` (the default) copies the reference world; `--template blender` copies the hand-written Blender template (below); any other template refuses before writing. `--empty` writes a bare shard source instead of the reference world |
|
|
56
|
+
| `wildshard update [dir] [--pins[=<version>]]` | Rewrite this guide and the four `wildshard` skills from the installed sdk. `--pins` first moves the repo to a newer sdk release (npm's latest, or `--pins=<version>`), installs it and applies its codemods, and runs `check` after (section 7) |
|
|
56
57
|
| `wildshard dev <source>` | Serve the shard source on localhost and rebuild on every save (section 4). **Not built yet** for an installed sdk (SA15) |
|
|
57
58
|
| `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
|
|
58
59
|
| `wildshard hero <source> --base <url>` | Capture the hero from a served build and stamp `hero.json`. `--stamp-existing` marks the images already there as current: only when you have looked at them and they show the current world |
|
|
@@ -179,7 +180,9 @@ At the repo root, around `src/`:
|
|
|
179
180
|
| `tsconfig.json`, `.npmrc`, `.gitignore` | TypeScript settings for `src/`; exact versions for `pnpm add`; what git leaves out (build output, `node_modules/`) | No |
|
|
180
181
|
| `README.md`, `GUIDE.md` | This repo's README, and this guide | No |
|
|
181
182
|
| `pnpm-workspace.yaml` | pnpm's install-script allowlist (SA39): a dependency's install script runs only if listed | No |
|
|
182
|
-
| `.claude/skills/wildshard*/SKILL.md` | The `wildshard` skill (SA14): the loop's order for Claude Code, pointing into this guide; and its siblings (SA27): `wildshard-mockup-to-model` (a picture to a model), `wildshard-goldens` (refresh the hero and proof tape), `wildshard-upgrade` (move to a newer sdk) | No |
|
|
183
|
+
| `.claude/skills/wildshard*/SKILL.md` | The `wildshard` skill (SA14): the loop's order for Claude Code, pointing into this guide; and its siblings (SA27): `wildshard-mockup-to-model` (a picture to a model), `wildshard-goldens` (refresh the hero and proof tape), `wildshard-upgrade` (move to a newer sdk). `wildshard update` rewrites them: never edit them | No |
|
|
184
|
+
| `.agents/skills/wildshard*` | Links to the four `.claude/skills/` folders, so Codex lists the same skills | No |
|
|
185
|
+
| `AGENTS.md`, `CLAUDE.md` | For agents: read this guide first; the skills are in `.claude/skills/`. `CLAUDE.md` is `@AGENTS.md`, so Claude Code reads the same file. Yours to change: `update` keeps your edits | No |
|
|
183
186
|
| `public/shardfiles/` | Build output: the built folder and `<slug>.shardfile`. Never edit; never commit | It is the shard file |
|
|
184
187
|
|
|
185
188
|
**Two files to change together.** `src/manifest.json` and `src/data/card.json` hold the same card: `new` writes
|
|
@@ -308,7 +311,8 @@ Every refusal prints the refusing code's own words, then one line:
|
|
|
308
311
|
`wildshard check . --json` carries the same `rule`, `fix` and `guide` on each refusal. The headings below are those
|
|
309
312
|
links, one per rule. The printed `fix` is the short answer; each heading adds why. Shard-format's own refusals also
|
|
310
313
|
carry a stable code, listed in
|
|
311
|
-
[`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md)
|
|
314
|
+
[`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md);
|
|
315
|
+
the rule is chosen by that code, and each heading below that one names lists its codes.
|
|
312
316
|
|
|
313
317
|
### Any command
|
|
314
318
|
|
|
@@ -332,6 +336,55 @@ other name refuses before `new` writes anything. Leave the flag out or pass `--t
|
|
|
332
336
|
|
|
333
337
|
`new` could not copy the reference world shipped with the sdk. Reinstall the sdk.
|
|
334
338
|
|
|
339
|
+
### Update
|
|
340
|
+
|
|
341
|
+
#### update-target
|
|
342
|
+
|
|
343
|
+
`update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it. Run it in
|
|
344
|
+
that folder, or name it: `wildshard update my-shard`.
|
|
345
|
+
|
|
346
|
+
#### update-pins-no-git
|
|
347
|
+
|
|
348
|
+
`wildshard update --pins` edits `package.json`, `pnpm-lock.yaml` and, through its codemods, your shard source, so it
|
|
349
|
+
runs only in a git repo whose `package.json` is committed: `git diff` afterwards is how you see what it changed. It
|
|
350
|
+
refused before it changed anything. Put the shard repo in git and commit it (`git init`, `git add .`, `git commit`),
|
|
351
|
+
then run `wildshard update --pins` again.
|
|
352
|
+
|
|
353
|
+
#### update-pins-dirty
|
|
354
|
+
|
|
355
|
+
The shard repo has uncommitted or untracked changes (the refusal names the first few). `update --pins` refuses them so
|
|
356
|
+
its edits never mix with yours. It refused before it changed anything. Commit or stash your changes (`git stash -u`),
|
|
357
|
+
then run `wildshard update --pins` again. Ignored files, such as `node_modules/` and build output, do not count.
|
|
358
|
+
|
|
359
|
+
#### update-pins
|
|
360
|
+
|
|
361
|
+
`wildshard update --pins` stopped. The line above says why. If it stopped before its codemods were done, it has
|
|
362
|
+
already put `package.json` and `pnpm-lock.yaml` back and installed the old sdk again (it says `back on
|
|
363
|
+
@wildshard/sdk <old>`), so after the fix run `wildshard update --pins` again; `git diff` shows any edit a codemod made
|
|
364
|
+
before it stopped.
|
|
365
|
+
|
|
366
|
+
- `npm has no @wildshard/sdk@<version>`, `npm gave no version` or `pnpm view ... failed`: name a version npm lists
|
|
367
|
+
(`pnpm view @wildshard/sdk versions`), or check your network.
|
|
368
|
+
- `moves forward only`: the repo is already on a newer sdk than the one you named. To go back, edit the pins in
|
|
369
|
+
`package.json` by hand and run `pnpm install`.
|
|
370
|
+
- `names <manager> as its package manager`: `--pins` installs with pnpm; set `packageManager` to the
|
|
371
|
+
`pnpm@...` that `new` writes, or move the pins by hand as the `wildshard-upgrade` skill says.
|
|
372
|
+
- `git not found`: `--pins` reads `git status` before it starts; install git.
|
|
373
|
+
- `cannot tell which sdk ... is on`: pin `@wildshard/sdk` to a version, not `link:` or `file:`.
|
|
374
|
+
- `pins @wildshard/sdk <a> but has <b> installed`: run `pnpm install` and `wildshard check .` on the pins you have,
|
|
375
|
+
then `--pins` again.
|
|
376
|
+
- `pnpm install failed`, `pnpm installed ...` or `pins three ...`: the install did not give the versions the release
|
|
377
|
+
names. Read pnpm's output above it.
|
|
378
|
+
- `codemod <version>.mjs failed`: the release's codemod could not change your shard source. Report the message with
|
|
379
|
+
the sdk versions; stay on the old pins until a fixed release.
|
|
380
|
+
- `its wildshard update failed`: the pins moved; run `pnpm exec wildshard update`, then `wildshard check .`.
|
|
381
|
+
- `check failed`: the pins moved and the install worked, but the shard source does not pass on the new sdk. Fix each
|
|
382
|
+
refusal check printed above it, then run `wildshard check .` again.
|
|
383
|
+
|
|
384
|
+
#### update-refused
|
|
385
|
+
|
|
386
|
+
`update` could not copy this guide or a skill from the installed sdk. Reinstall the sdk (`pnpm install`).
|
|
387
|
+
|
|
335
388
|
### Build
|
|
336
389
|
|
|
337
390
|
#### source-file-missing
|
|
@@ -398,31 +451,38 @@ the limit.
|
|
|
398
451
|
|
|
399
452
|
#### budget-unmeasured
|
|
400
453
|
|
|
401
|
-
A cost could not be measured: too few headless ticks for scripts, or native gameplay that needs a browser run.
|
|
454
|
+
A cost could not be measured: too few headless ticks for scripts, or native gameplay that needs a browser run. Codes
|
|
455
|
+
`perf-native-view-unmeasured`, `perf-native-resident-unmeasured`, `perf-script-sample-invalid`,
|
|
456
|
+
`perf-script-samples-missing`.
|
|
402
457
|
|
|
403
458
|
#### budget-download
|
|
404
459
|
|
|
405
460
|
Too many bytes to download, before play (critical) or in all (library). Shrink or drop assets, or load them later.
|
|
461
|
+
Codes `perf-library-download-budget`, `perf-critical-download-budget`, `perf-library-download`,
|
|
462
|
+
`perf-critical-download`, `perf-tile-download`, `perf-far-download`.
|
|
406
463
|
|
|
407
464
|
#### budget-draws
|
|
408
465
|
|
|
409
|
-
Too many draw calls in a view. Merge meshes that share a material, or show fewer objects from that view.
|
|
466
|
+
Too many draw calls in a view. Merge meshes that share a material, or show fewer objects from that view. Codes
|
|
467
|
+
`perf-tile-draws`, `perf-far-draws`.
|
|
410
468
|
|
|
411
469
|
#### budget-triangles
|
|
412
470
|
|
|
413
|
-
Too many triangles in a view. Use lower-detail meshes or fewer props there.
|
|
471
|
+
Too many triangles in a view. Use lower-detail meshes or fewer props there. Codes `perf-tile-triangles`,
|
|
472
|
+
`perf-far-triangles`.
|
|
414
473
|
|
|
415
474
|
#### budget-memory
|
|
416
475
|
|
|
417
|
-
A memory total is over its line. Smaller or fewer textures and meshes. Memory reports only, for now.
|
|
476
|
+
A memory total is over its line. Smaller or fewer textures and meshes. Memory reports only, for now. Codes
|
|
477
|
+
`perf-memory-target`, `perf-playing-memory`, `perf-loading-memory`.
|
|
418
478
|
|
|
419
479
|
#### budget-script-cpu
|
|
420
480
|
|
|
421
|
-
Behaviour scripts take too long per tick. Spread work over ticks, or run it on events.
|
|
481
|
+
Behaviour scripts take too long per tick. Spread work over ticks, or run it on events. Code `perf-script-cpu`.
|
|
422
482
|
|
|
423
483
|
#### budget-script-fuel
|
|
424
484
|
|
|
425
|
-
Behaviour scripts run too many instructions per tick. Shorten the hottest loops.
|
|
485
|
+
Behaviour scripts run too many instructions per tick. Shorten the hottest loops. Code `perf-script-fuel`.
|
|
426
486
|
|
|
427
487
|
#### budget-over
|
|
428
488
|
|
|
@@ -431,6 +491,7 @@ A budget not named above is over its limit. The message names it; `wildshard che
|
|
|
431
491
|
#### budget-refused
|
|
432
492
|
|
|
433
493
|
Build or validate refused the whole report card. Run `wildshard check .`: its report step names each budget over.
|
|
494
|
+
Codes `declared-costs`, `performance-targets` (shard-format checking the costs the shard file declares).
|
|
434
495
|
|
|
435
496
|
### The shard file and the hero
|
|
436
497
|
|
|
@@ -454,6 +515,46 @@ Capture a new hero, build, prepare and upload again.
|
|
|
454
515
|
|
|
455
516
|
The audio rules found a red problem: a recording that will not play, runs too long, or a shard over 10 MB of its own
|
|
456
517
|
audio. Fix each red finding, or add a dated waiver in `audio-waiver.json`. Shard-format `docs/audio.md` explains each.
|
|
518
|
+
Code `audio-refused`. Build prints every finding with one of the rules below under it; only upload refuses a red one.
|
|
519
|
+
|
|
520
|
+
#### audio-unreadable
|
|
521
|
+
|
|
522
|
+
Red. The recording does not read as AAC-LC at 48 kHz, mono or stereo. Export it again as AAC-LC at 48 kHz in an
|
|
523
|
+
`.m4a` file. Code `audio-unreadable`.
|
|
524
|
+
|
|
525
|
+
#### audio-container
|
|
526
|
+
|
|
527
|
+
Red. The recording's bytes are FLAC, AIFF, Ogg, MP3, WebM, CAF or no container the game knows; it still counts toward
|
|
528
|
+
the audio budget. Export it again as AAC-LC at 48 kHz in an `.m4a` file, not as WAV: a WAV file is `audio-wav`, amber.
|
|
529
|
+
With ffmpeg on your PATH, `build` re-encodes a `.wav`, `.flac`, `.aif` or `.aiff` file under `/assets/music/` or
|
|
530
|
+
`/assets/sfx/` to that form itself, so you see this rule for MP3, Ogg, WebM or CAF, for a file outside those folders or
|
|
531
|
+
named otherwise, or when ffmpeg is missing. Code `audio-container`.
|
|
532
|
+
|
|
533
|
+
#### audio-encoding
|
|
534
|
+
|
|
535
|
+
Amber. The recording plays, but it is PCM WAV, AAC at a sample rate other than 48 kHz, or AAC outside the strict
|
|
536
|
+
playback index. Encode it again with ffmpeg as AAC-LC at 48 kHz in an `.m4a` file, or let `build` do it (it needs
|
|
537
|
+
ffmpeg on your PATH). Codes `audio-wav`, `audio-sample-rate`, `audio-strict-index`.
|
|
538
|
+
|
|
539
|
+
#### audio-duration
|
|
540
|
+
|
|
541
|
+
Red. The recording runs longer than the maximum the message gives. Cut it, or split it in two. Code `audio-duration`.
|
|
542
|
+
|
|
543
|
+
#### audio-bitrate
|
|
544
|
+
|
|
545
|
+
Amber. The recording's bitrate is over the cap for its role (music or sound effect) and channels. Encode it lower.
|
|
546
|
+
Code `audio-bitrate`.
|
|
547
|
+
|
|
548
|
+
#### audio-budget
|
|
549
|
+
|
|
550
|
+
The shard's own audio is over the amber line (amber), over the red line (red), or over the red line with a dated
|
|
551
|
+
waiver that holds (amber). Cut, shorten or re-encode recordings, or add a waiver in `audio-waiver.json`. Codes
|
|
552
|
+
`audio-budget-amber`, `audio-budget-red`, `audio-budget-waived`.
|
|
553
|
+
|
|
554
|
+
#### audio-waiver
|
|
555
|
+
|
|
556
|
+
Amber. `audio-waiver.json` names another shard, has expired, or covers fewer bytes than the shard holds, so it does
|
|
557
|
+
not hold; the budget finding after it says what that leaves. Code `audio-waiver-invalid`.
|
|
457
558
|
|
|
458
559
|
#### shardfile-draft
|
|
459
560
|
|
|
@@ -471,7 +572,45 @@ There is no built folder to write a shard file from. Run `wildshard check .` (or
|
|
|
471
572
|
|
|
472
573
|
#### shardfile-invalid
|
|
473
574
|
|
|
474
|
-
The shard file breaks a format check. Upload the shard file `prepare` and
|
|
575
|
+
The shard file breaks a format check: it is not a tarball shard-format can read. Upload the shard file `prepare` and
|
|
576
|
+
`build <folder>` wrote, unedited. Code `archive-invalid`.
|
|
577
|
+
|
|
578
|
+
#### shardfile-index
|
|
579
|
+
|
|
580
|
+
`shard.json` is missing, too large, not canonical JSON, or does not fit the index schema. Build again so it is written
|
|
581
|
+
for you; a hand-written shard file's `shard.json` must parse and fit. Code `index-invalid`.
|
|
582
|
+
|
|
583
|
+
#### shardfile-files
|
|
584
|
+
|
|
585
|
+
The files in the folder differ from the ones `shard.json` lists: one is missing, changed or a link, one is not listed,
|
|
586
|
+
a pack lacks a member, or the sections differ from the source hash. Something edited the built folder: build again.
|
|
587
|
+
Codes `file-mismatch`, `unlisted-file`, `source-hash`, `pack-invalid`.
|
|
588
|
+
|
|
589
|
+
#### shardfile-section
|
|
590
|
+
|
|
591
|
+
A section, or the whole shard file the sections make, does not fit its schema. The message gives the path;
|
|
592
|
+
`wildshard schema shardfile <pointer>` prints the expected shape. Codes `section-invalid`, `shard-schema`.
|
|
593
|
+
|
|
594
|
+
#### shardfile-assets
|
|
595
|
+
|
|
596
|
+
An asset's bytes do not match what the shard file declares (its kind, extension, schema, size or costs), or fail
|
|
597
|
+
the asset checks, or a mount or runtime file is wrong. Export the named asset again and build. Codes `blob-invalid`,
|
|
598
|
+
`server-file-invalid`, `ktx2-costs`, `asset-admission`, `cook-invalid`, `runtime-files`.
|
|
599
|
+
|
|
600
|
+
#### shardfile-scripts
|
|
601
|
+
|
|
602
|
+
A behaviour script runs on a side (client or server) its declaration does not allow, or the script rows are
|
|
603
|
+
invalid. Fix the declaration or move the script, then build again. Codes `script-side`, `script-admission`.
|
|
604
|
+
|
|
605
|
+
#### shardfile-targets
|
|
606
|
+
|
|
607
|
+
The world targets name an item or quest the shard does not declare. Declare it, or take it out. Code `world-targets`.
|
|
608
|
+
|
|
609
|
+
#### shardfile-stream
|
|
610
|
+
|
|
611
|
+
Upload's streaming check refused: a file, pack or the placed assets are over the streaming cap, or the stored file
|
|
612
|
+
changed while it was read. Shrink what the message names; if it changed mid-read, upload again. Codes `stream-cap`,
|
|
613
|
+
`stream-miss`, `stream-changed`.
|
|
475
614
|
|
|
476
615
|
#### shardfile-refused
|
|
477
616
|
|
|
@@ -780,11 +919,32 @@ Code the headless simulation imports must not render.
|
|
|
780
919
|
|
|
781
920
|
## 7. `wildshard update`
|
|
782
921
|
|
|
783
|
-
|
|
784
|
-
installed sdk, and
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
`
|
|
790
|
-
|
|
922
|
+
`wildshard update` (or `wildshard update <dir>`) rewrites this guide and the four `wildshard` skills in
|
|
923
|
+
`.claude/skills/` from the installed sdk, and prints each file it wrote. Run it after you move to a newer sdk; the
|
|
924
|
+
`wildshard-upgrade` skill walks the whole move. It touches nothing else: your shard source, `package.json`, README and
|
|
925
|
+
every other file stay as they are. It adds the `.agents/skills/` links, `AGENTS.md` and `CLAUDE.md` only if one is
|
|
926
|
+
missing, and it leaves an `AGENTS.md` or `CLAUDE.md` you changed and says so (`left AGENTS.md: you changed it`). So
|
|
927
|
+
keep your own notes for agents in `AGENTS.md`, never in this guide or a skill: `update` rewrites those. Done when it
|
|
928
|
+
prints `already up to date` or the files it wrote, and `git status` shows only `GUIDE.md`, `.claude/skills/` and any
|
|
929
|
+
agent file it added.
|
|
930
|
+
|
|
931
|
+
`wildshard update --pins` moves the repo to a newer sdk release first: npm's latest, or the one you name with
|
|
932
|
+
`--pins=<version>` (`--pins=0.2.4`). In order, it:
|
|
933
|
+
|
|
934
|
+
1. reads the release from npm (`pnpm view`) and refuses one older than the repo's sdk;
|
|
935
|
+
2. moves every pin `package.json` lists to what that release names: `@wildshard/sdk` to the release,
|
|
936
|
+
`@wildshard/format`, `@wildshard/engine` and `three` to the exact specs it pins, and `engines.node` to the Node it
|
|
937
|
+
needs. It changes nothing else in the file and prints each move;
|
|
938
|
+
3. runs `pnpm install`, and refuses if pnpm did not install that sdk and, when the repo lists `three`, that `three`;
|
|
939
|
+
4. applies the release's codemods: each `codemods/<version>.mjs` the new sdk ships, for every version above the old
|
|
940
|
+
sdk and up to the new one, oldest first. A codemod edits your shard source for a change that would otherwise
|
|
941
|
+
break it, and prints what it changed;
|
|
942
|
+
5. runs the new sdk's own `wildshard update`, which rewrites this guide and the skills as above;
|
|
943
|
+
6. runs the new sdk's `wildshard check .`.
|
|
944
|
+
|
|
945
|
+
If step 3 or 4 fails, it puts `package.json` and `pnpm-lock.yaml` back and installs the old sdk again. It refuses to
|
|
946
|
+
start unless `git status` is clean (`update-pins-dirty`, `update-pins-no-git`): a codemod edits your files. Done when
|
|
947
|
+
its last line reads `on @wildshard/sdk <version>, check pass`. Commit `package.json`, `pnpm-lock.yaml`, the guide,
|
|
948
|
+
the skills and any codemod edit together. A refusal is `update-pins` (section 6). An sdk older than the one
|
|
949
|
+
that built `--pins` refuses the flag; run the newest CLI once instead:
|
|
950
|
+
`pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins`.
|
package/bin/wildshard.mjs
CHANGED
|
@@ -7,7 +7,7 @@ import { resolve } from 'node:path';
|
|
|
7
7
|
import { existsSync } from 'node:fs';
|
|
8
8
|
import '../src/sharddev/bake/format-hook.mjs';
|
|
9
9
|
|
|
10
|
-
const AUTHOR = new Set(['new', 'check', 'synth', 'build', 'validate', 'prove', 'dev', 'schema', '--prepare-compiler']);
|
|
10
|
+
const AUTHOR = new Set(['new', 'update', 'check', 'synth', 'build', 'validate', 'prove', 'dev', 'schema', '--prepare-compiler']);
|
|
11
11
|
const [command, operand] = process.argv.slice(2);
|
|
12
12
|
// SA2: `wildshard <verb> --help` and `wildshard help [verb]` print help (src/cli/help.ts) before any verb runs.
|
|
13
13
|
const verbHelp = command === 'help' || (command !== undefined && !command.startsWith('-') && process.argv.slice(3).some(arg => arg === '--help' || arg === '-h'));
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// SHARD-AUTHORING SA18: the codemod for the sdk release named by this file (`codemods/<version>.mjs`).
|
|
2
|
+
// `wildshard update --pins` runs every codemod whose version v is above the repo's old sdk and at most the new one
|
|
3
|
+
// (old < v <= new), oldest first, after `pnpm install` and before `wildshard update` rewrites GUIDE.md and the skills.
|
|
4
|
+
// A codemod edits the shard repo at `project` for the release's breaking changes and returns one line per change.
|
|
5
|
+
// This release changes nothing in a shard repo, so it is a no-op that keeps the hook's shape on file.
|
|
6
|
+
|
|
7
|
+
/** @param {Readonly<{ project: string, from: string, to: string }>} move @returns {string[]} */
|
|
8
|
+
// oxlint-disable-next-line import/no-default-export -- `update --pins` loads each codemod by its default export.
|
|
9
|
+
export default function codemod(move) {
|
|
10
|
+
void move;
|
|
11
|
+
return [];
|
|
12
|
+
}
|
package/lint/ratchet.json
CHANGED
|
@@ -1,11 +1,3 @@
|
|
|
1
1
|
{
|
|
2
|
-
"budgets": {}
|
|
3
|
-
"wildshard/sdk-no-facade": {
|
|
4
|
-
"src/sharddev/kit/bakedGeometry.ts": 7,
|
|
5
|
-
"src/sharddev/phasedBoss.ts": 9,
|
|
6
|
-
"src/sharddev/species/clips.ts": 11,
|
|
7
|
-
"src/sharddev/speciesBrains.ts": 3,
|
|
8
|
-
"src/sharddev/weapons/bowProfile.ts": 1,
|
|
9
|
-
"src/sharddev/weapons/meleeProfile.ts": 2
|
|
10
|
-
}
|
|
2
|
+
"budgets": {}
|
|
11
3
|
}
|
package/lint/sdk-plugin.mjs
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
import { readFileSync } from 'node:fs';
|
|
10
10
|
import { isBuiltin } from 'node:module';
|
|
11
11
|
import { dirname, isAbsolute, resolve } from 'node:path';
|
|
12
|
-
import { fileURLToPath } from 'node:url';
|
|
12
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
13
13
|
|
|
14
14
|
const RULE = 'generator-imports';
|
|
15
15
|
// Not visible to a lint, left for later: `#` subpath imports and tsconfig `paths` aliases (they name no package), and
|
|
@@ -68,16 +68,38 @@ function cheat(source, local, required) {
|
|
|
68
68
|
return null;
|
|
69
69
|
}
|
|
70
70
|
|
|
71
|
+
const plainly = (source) => `${RULE}: ${JSON.stringify(source)} names one file to Node (a URL) and another to Vite; `
|
|
72
|
+
+ 'no percent-escape, backslash, tab, newline or edge space in an import path, write the path plainly';
|
|
73
|
+
/** The file Node loads for relative `source` (a URL resolve), without a trailing slash; null when it cannot. */
|
|
74
|
+
const nodePath = (filename, source) => {
|
|
75
|
+
try {
|
|
76
|
+
return fileURLToPath(new URL(source, pathToFileURL(resolve(filename)))).replaceAll('\\', '/').replace(/(?<=.)\/$/u, '');
|
|
77
|
+
} catch { return null; }
|
|
78
|
+
};
|
|
79
|
+
|
|
71
80
|
/** Why `source` may not be imported from `filename` under a shard's author folders, or null when it may. */
|
|
72
81
|
export function generatorImportViolation(filename, rawSource, required = false) {
|
|
73
82
|
// The last src/shards/ in the path names the shard, so a checkout under some other src/shards/ still matches.
|
|
74
83
|
const path = resolve(filename).replaceAll('\\', '/'), match = /^.*\/src\/shards\/([^/]+)\/(.+)$/u.exec(path);
|
|
75
84
|
if (match === null || !(/^(?:generators|data|quests)\//u.test(match[2]) || match[2] === 'shard.config.ts')) return null;
|
|
76
85
|
if (typeof rawSource !== 'string') return null;
|
|
77
|
-
|
|
86
|
+
// Vite resolves the path before the first `?` or `#` through the package exports and keeps the rest (`?raw`, `?url`,
|
|
87
|
+
// `?worker&inline`) as a postfix, as engine's import rules read it; a leading `#` is a subpath import, not a postfix.
|
|
88
|
+
// Node keeps a bare specifier's `?` in the subpath, so there the stripped path is only ever the stricter read.
|
|
89
|
+
const postfix = rawSource.slice(1).search(/[?#]/u) + 1;
|
|
90
|
+
const bare = postfix > 0 ? rawSource.slice(0, postfix) : rawSource;
|
|
91
|
+
// Node resolves a relative path as a URL (`./%2e%2e/` is `..`, `\\` is `/`, tabs and newlines drop out, `%2f` is
|
|
92
|
+
// refused) and Vite decodes nothing, while path.resolve keeps them all as folder names: the lint and build disagree.
|
|
93
|
+
if (/%[0-9a-f]{2}|[\\\t\n\r]/iu.test(bare)) return plainly(bare);
|
|
94
|
+
let source = bare;
|
|
95
|
+
if (bare.startsWith('file:')) {
|
|
96
|
+
try { source = fileURLToPath(bare); } catch { return `${RULE}: ${bare} is not a local file: URL; import a relative path`; }
|
|
97
|
+
}
|
|
78
98
|
if (source === '<computed>') return `${RULE}: author imports require a literal module path; write the path as a string`;
|
|
79
99
|
const root = path.slice(0, path.length - match[2].length);
|
|
80
100
|
const local = source.startsWith('.') || isAbsolute(source) ? resolve(dirname(filename), source).replaceAll('\\', '/') : '';
|
|
101
|
+
// The catch-all for a rewrite not listed above: the path must name the same file as a URL (how Node loads it).
|
|
102
|
+
if (local !== '' && source.startsWith('.') && nodePath(filename, source) !== local) return plainly(bare);
|
|
81
103
|
const denied = cheat(source, local, required);
|
|
82
104
|
if (denied !== null) return denied;
|
|
83
105
|
const own = local !== '' && local.startsWith(root);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wildshard/sdk",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.5",
|
|
4
4
|
"description": "The author's toolbox: the `wildshard` CLI that bakes shard source into a shardfile, the author SDK, the local dev server (engine client against engine server), the explorers, arena and drafts tool.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"repository": {
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
"files": [
|
|
14
14
|
"GUIDE.md",
|
|
15
15
|
"skills",
|
|
16
|
+
"codemods",
|
|
16
17
|
"bin",
|
|
17
18
|
"src",
|
|
18
19
|
"!src/**/*.test.*",
|
|
@@ -82,7 +83,7 @@
|
|
|
82
83
|
"@typescript/typescript6": "6.0.2",
|
|
83
84
|
"@valibot/to-json-schema": "1.8.0",
|
|
84
85
|
"@wildshard/engine": "github:project-wildshard/engine#867f3b968429d8b90ae33b363dae3f15f16f6b84",
|
|
85
|
-
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.
|
|
86
|
+
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.9",
|
|
86
87
|
"ajv": "6.15.0",
|
|
87
88
|
"assemblyscript": "0.28.20",
|
|
88
89
|
"binaryen": "132.0.0",
|
|
@@ -196,7 +197,7 @@
|
|
|
196
197
|
"overrides": {
|
|
197
198
|
"binaryen": "npm:@pre-bundled/binaryen@132.0.0-patch-1",
|
|
198
199
|
"assemblyscript>binaryen": "npm:@pre-bundled/binaryen@131.0.0-nightly.20260721-patch-1",
|
|
199
|
-
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.
|
|
200
|
+
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.9"
|
|
200
201
|
}
|
|
201
202
|
},
|
|
202
203
|
"exports": {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { mkdirSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { resolve } from 'node:path';
|
|
3
3
|
import { pathToFileURL } from 'node:url';
|
|
4
|
-
import { formatJsonSchemas, namedFormatJsonSchemas } from '@wildshard/
|
|
4
|
+
import { formatJsonSchemas, namedFormatJsonSchemas } from '@wildshard/sdk/formatJsonSchema';
|
|
5
5
|
|
|
6
6
|
/** Build the migrated format documents into an ignored authoring-output folder, never into committed source.
|
|
7
7
|
* @param {string} root
|
package/scripts/wildshard.mjs
CHANGED
|
@@ -4,7 +4,7 @@ import { build } from 'vite';
|
|
|
4
4
|
import { createBuildCacheCounters, observeBuildCache, formatBuildCacheReport } from '@wildshard/engine/scripts/build-cache-report.mjs';
|
|
5
5
|
import { captureProductInputs, recordBundle, inputRecorderPlugin } from '@wildshard/engine/scripts/shardfile-inputs.mjs';
|
|
6
6
|
import { basename, resolve } from 'node:path';
|
|
7
|
-
import { existsSync, readFileSync } from 'node:fs';
|
|
7
|
+
import { existsSync, readFileSync, realpathSync } from 'node:fs';
|
|
8
8
|
import { createHash } from 'node:crypto';
|
|
9
9
|
import { pathToFileURL } from 'node:url';
|
|
10
10
|
import { createRequire } from 'node:module';
|
|
@@ -38,7 +38,13 @@ export function prepareWildshard() {
|
|
|
38
38
|
// Resolver policy is executable compiler input too: a source-only cache hit
|
|
39
39
|
// must not replay a bundle built before an externalization change.
|
|
40
40
|
const policy = createHash('sha256').update(readFileSync(import.meta.filename)).digest('hex');
|
|
41
|
-
|
|
41
|
+
// SA18: which installed sdk is compiling is an input too. Receipts skip node_modules and paths outside the repo, and
|
|
42
|
+
// this file is byte-identical across releases, so without its root and version a repo that moved to a newer sdk with
|
|
43
|
+
// the same shard-format replayed the old sdk's bundle. (A sharddev checkout run from another folder is still keyed
|
|
44
|
+
// only by its path: edits to it outside that folder are not seen.)
|
|
45
|
+
const sdkRoot = realpathSync(resolve(import.meta.dirname, '..'));
|
|
46
|
+
const sdk = `${sdkRoot}@${JSON.parse(readFileSync(resolve(sdkRoot, 'package.json'), 'utf8')).version}`;
|
|
47
|
+
return authorBundleCached(root,[shardfileValidationRevision(root),policy,sdk],async()=>{
|
|
42
48
|
const result = await build({ configFile: false, publicDir: false, resolve: { alias: rapierAlias }, logLevel: 'silent', define: { __SHARDFILE_VALIDATOR__: JSON.stringify(shardfileValidationRevision()), 'import.meta.dirname': JSON.stringify(resolve(import.meta.dirname, '../src/sharddev')) }, plugins: [inputRecorderPlugin({execution:true}), { name: 'author-node-vite', enforce: 'pre', resolveId(id) {
|
|
43
49
|
if (id === 'vite') return { id: pathToFileURL(resolve(import.meta.dirname,'shardfile-vite.mjs')).href, external: true };
|
|
44
50
|
if (id === 'sharp' || id === 'binaryen' || id === '@typescript/typescript6' || /^assemblyscript(?:\/|$)/u.test(id)) return { id: pathToFileURL(authorRequire.resolve(id)).href, external: true };
|
|
@@ -10,37 +10,30 @@ blender` repo pins only the first two, as dev dependencies (`GUIDE.md#2-the-shar
|
|
|
10
10
|
moves every pin together, then the shard source must build again on them. `GUIDE.md` at the repo root holds the
|
|
11
11
|
facts; a pointer `GUIDE.md#<anchor>` is the guide heading with that anchor.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
steps below by hand.
|
|
13
|
+
`wildshard update --pins` does the move in one command (`GUIDE.md#7-wildshard-update`): it moves every pin to the
|
|
14
|
+
release, runs `pnpm install`, applies the release's codemods, rewrites the guide and skills, and runs check.
|
|
16
15
|
|
|
17
16
|
## The steps, in order
|
|
18
17
|
|
|
19
18
|
1. **Start clean.** Commit your own changes, then `wildshard check .` on the old pins; if it fails, fix that first.
|
|
20
19
|
Done when `git status` is clean and check passes, so any later refusal is the upgrade's.
|
|
21
|
-
2. **
|
|
22
|
-
|
|
23
|
-
`
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
`
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
(`GUIDE.md#1-the-loop`). Done when `wildshard --version` prints the new sdk version and the last line reads
|
|
34
|
-
`check pass`.
|
|
35
|
-
7. **Read each refusal.** It ends `[<rule>] fix: ... (GUIDE.md#<anchor>)`: read that heading under
|
|
36
|
-
`GUIDE.md#6-refusals-and-their-fixes`, in the guide you copied in step 5, make the fix, and run check again. A
|
|
37
|
-
budget can tighten between releases (`GUIDE.md#3-budgets`); a lint rule can be new. Done at `check pass`.
|
|
38
|
-
8. **Commit** the pins, the lock file, the guide, the skills and your fixes together. Done when `git status` is clean.
|
|
20
|
+
2. **Move:** `pnpm exec wildshard update --pins` for npm's latest sdk, or `--pins=<version>` for one release. If the
|
|
21
|
+
installed CLI refuses the flag (an sdk older than `--pins`), run the newest once:
|
|
22
|
+
`pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins`. Done when it prints a line per pin it moved.
|
|
23
|
+
3. **Read its last line.** `on @wildshard/sdk <version>, check pass` means the move is done: go to step 5. A line
|
|
24
|
+
ending `[update-pins] fix: ...` is a refusal: read `GUIDE.md#update-pins` in the guide now in the repo;
|
|
25
|
+
`[update-pins-dirty]` (`GUIDE.md#update-pins-dirty`) means go back to step 1.
|
|
26
|
+
4. **Fix each refusal check printed.** It ends `[<rule>] fix: ... (GUIDE.md#<anchor>)`: read that heading under
|
|
27
|
+
`GUIDE.md#6-refusals-and-their-fixes`, make the fix, and run `wildshard check .` again. A budget can tighten
|
|
28
|
+
between releases (`GUIDE.md#3-budgets`); a lint rule can be new. Done at `check pass`.
|
|
29
|
+
5. **Reread this skill:** step 2 rewrote it, and the new copy may differ. Done when you have read the new copy.
|
|
30
|
+
6. **Commit** `package.json`, `pnpm-lock.yaml`, the guide, the skills, any agent file update added, any codemod edit
|
|
31
|
+
and your fixes together. Done when `git status` is clean.
|
|
39
32
|
A new sdk can change what the shard looks like, so before the next upload follow the `wildshard-goldens` skill.
|
|
40
33
|
|
|
41
34
|
## Rules
|
|
42
35
|
|
|
43
|
-
- Move the pins together, never one alone: the sdk is built and tested against the others it names.
|
|
36
|
+
- Move the pins together, never one alone: the sdk is built and tested against the others it names. `--pins` does.
|
|
44
37
|
- Fix the shard source to the new rules; do not pin an older piece to dodge a refusal.
|
|
45
38
|
- If check fails on a shard source you did not change and the refusal's fix does not apply, go back to the old pins
|
|
46
39
|
and report the message.
|
package/src/cli/audio/audio.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { installFormatHook } from '@wildshard/format/formatHook'
|
|
2
2
|
|
|
3
|
+
import { refusalHint, refusalNote } from '../../sharddev/refusals.ts'
|
|
4
|
+
|
|
3
5
|
import type { AudioReport } from '@wildshard/format/audioRules'
|
|
4
6
|
|
|
5
7
|
// AUDIO AU5 (meta docs/plans/AUDIO-PLAN.md, J299): format owns the audio
|
|
@@ -7,11 +9,24 @@ import type { AudioReport } from '@wildshard/format/audioRules'
|
|
|
7
9
|
// refuses a red before it spends the upload, as api-server's admission
|
|
8
10
|
// will. A waiver lives in the shard source (`audio-waiver.json`).
|
|
9
11
|
|
|
10
|
-
/** The report as
|
|
12
|
+
/** The report as build prints it: totals, then one AMBER line per finding,
|
|
13
|
+
* each followed by its rule, fix and GUIDE.md link, named by its code (SA41). */
|
|
11
14
|
async function audioLines(report: Readonly<AudioReport>): Promise<string[]> {
|
|
12
15
|
installFormatHook()
|
|
13
16
|
const { audioReportLines } = await import('@wildshard/format/audioRules')
|
|
14
|
-
|
|
17
|
+
const [totals = '', ...findings] = audioReportLines(report)
|
|
18
|
+
return [
|
|
19
|
+
totals,
|
|
20
|
+
...findings.flatMap((line: string, at: number): string[] => {
|
|
21
|
+
const finding = report.findings[at]
|
|
22
|
+
return finding === undefined
|
|
23
|
+
? [line]
|
|
24
|
+
: [
|
|
25
|
+
line,
|
|
26
|
+
` ${refusalHint(refusalNote('shardfile', finding.message, { code: finding.code }))}`,
|
|
27
|
+
]
|
|
28
|
+
}),
|
|
29
|
+
]
|
|
15
30
|
}
|
|
16
31
|
|
|
17
32
|
/** Refuse a red report, with format's reason. */
|
package/src/cli/help.ts
CHANGED
|
@@ -24,6 +24,17 @@ const VERBS: Readonly<Record<string, string>> = {
|
|
|
24
24
|
blender copies the hand-written Blender template
|
|
25
25
|
(a shard file folder, no code). --empty writes a
|
|
26
26
|
bare shard source instead`,
|
|
27
|
+
update: `update [dir] [--pins[=<version>]]
|
|
28
|
+
Rewrite GUIDE.md and the four wildshard skills in
|
|
29
|
+
.claude/skills/ from the installed sdk (dir: the
|
|
30
|
+
shard repo, default the current folder). Adds the
|
|
31
|
+
.agents/skills links, AGENTS.md and CLAUDE.md if
|
|
32
|
+
missing; touches nothing else, and leaves an
|
|
33
|
+
AGENTS.md you changed (it says so). --pins first
|
|
34
|
+
moves the repo to a newer sdk (npm's latest, or
|
|
35
|
+
--pins=<version>): moves the pins, runs pnpm
|
|
36
|
+
install, applies the release's codemods, then
|
|
37
|
+
runs the new sdk's update and check`,
|
|
27
38
|
dev: `dev <source> [port]
|
|
28
39
|
Serve the shard source on localhost (port 0, the
|
|
29
40
|
default, picks a free one) and build it again on
|
package/src/cli/main.ts
CHANGED
|
@@ -211,8 +211,7 @@ async function runUpload(args: CliArgs): Promise<number> {
|
|
|
211
211
|
await uploadShardfile(options)
|
|
212
212
|
return EXIT_OK
|
|
213
213
|
} catch (error: unknown) {
|
|
214
|
-
|
|
215
|
-
refuse('upload', 'upload failed: ', reason)
|
|
214
|
+
refuse('upload', 'upload failed: ', error)
|
|
216
215
|
return EXIT_FAILED
|
|
217
216
|
}
|
|
218
217
|
}
|
package/src/cli/report.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { refusalHint, refusalNote } from '../sharddev/refusals.ts'
|
|
1
|
+
import { refusalCode, refusalHint, refusalNote } from '../sharddev/refusals.ts'
|
|
2
2
|
|
|
3
3
|
import type { RefusalStep } from '../sharddev/refusals.ts'
|
|
4
4
|
|
|
@@ -7,9 +7,13 @@ function reportLine(line: string): void {
|
|
|
7
7
|
process.stdout.write(`${line}\n`)
|
|
8
8
|
}
|
|
9
9
|
|
|
10
|
-
/** A refusal on stderr, then its rule, fix and GUIDE.md link (SA21).
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
/** A refusal on stderr, then its rule, fix and GUIDE.md link (SA21). `refusal` is the words, or the error: its message,
|
|
11
|
+
* and its shard-format code names the rule when it has one (SA41). */
|
|
12
|
+
function refuse(step: RefusalStep, prefix: string, refusal: unknown): void {
|
|
13
|
+
const reason = refusal instanceof Error ? refusal.message : String(refusal)
|
|
14
|
+
const hint = refusalHint(
|
|
15
|
+
refusalNote(step, reason, { code: refusalCode(refusal) }),
|
|
16
|
+
)
|
|
13
17
|
process.stderr.write(`sharddev: ${prefix}${reason}\n ${hint}\n`)
|
|
14
18
|
}
|
|
15
19
|
|
|
@@ -32,8 +32,7 @@ async function runShardfile(
|
|
|
32
32
|
})
|
|
33
33
|
return EXIT_OK
|
|
34
34
|
} catch (error: unknown) {
|
|
35
|
-
|
|
36
|
-
refuse(STEP, `${step} failed: `, reason)
|
|
35
|
+
refuse(STEP, `${step} failed: `, error)
|
|
37
36
|
return EXIT_FAILED
|
|
38
37
|
}
|
|
39
38
|
}
|