@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.
Files changed (43) hide show
  1. package/GUIDE.md +178 -18
  2. package/bin/wildshard.mjs +1 -1
  3. package/codemods/0.2.5.mjs +12 -0
  4. package/lint/ratchet.json +1 -9
  5. package/lint/sdk-plugin.mjs +24 -2
  6. package/package.json +4 -3
  7. package/scripts/gen-format-schema.mjs +1 -1
  8. package/scripts/wildshard.mjs +8 -2
  9. package/skills/wildshard-upgrade/SKILL.md +15 -22
  10. package/src/cli/audio/audio.ts +17 -2
  11. package/src/cli/help.ts +11 -0
  12. package/src/cli/main.ts +1 -2
  13. package/src/cli/report.ts +8 -4
  14. package/src/cli/shardfile/command.ts +1 -2
  15. package/src/sharddev/agentFiles.ts +127 -0
  16. package/src/sharddev/author.ts +16 -3
  17. package/src/sharddev/bake/authoredWorld.ts +1 -1
  18. package/src/sharddev/bake/specimenCatalogue.ts +1 -1
  19. package/src/sharddev/bake/staticMaterials.ts +1 -1
  20. package/src/sharddev/check.ts +7 -6
  21. package/src/sharddev/checkProject.ts +4 -3
  22. package/src/sharddev/cli.ts +18 -5
  23. package/src/sharddev/formatJsonSchema.ts +1117 -3
  24. package/src/sharddev/kit/bakedGeometry.ts +58 -12
  25. package/src/sharddev/nativePopulationRows.ts +1 -1
  26. package/src/sharddev/newProject.ts +4 -25
  27. package/src/sharddev/performancePolicy.ts +16 -5
  28. package/src/sharddev/phasedBoss.ts +212 -34
  29. package/src/sharddev/project.ts +1 -1
  30. package/src/sharddev/projectEntryProof.ts +1 -1
  31. package/src/sharddev/projectGeneration.ts +1 -1
  32. package/src/sharddev/projectOutput.ts +1 -1
  33. package/src/sharddev/projectSections.ts +1 -1
  34. package/src/sharddev/refusals.ts +92 -18
  35. package/src/sharddev/reportCard.ts +1 -1
  36. package/src/sharddev/sections.ts +1 -1
  37. package/src/sharddev/species/clips.ts +64 -24
  38. package/src/sharddev/speciesBrains.ts +98 -15
  39. package/src/sharddev/updatePins.ts +254 -0
  40. package/src/sharddev/weapons/bowProfile.ts +3 -3
  41. package/src/sharddev/weapons/meleeProfile.ts +48 -4
  42. package/src/sharddev/worldScenes.ts +1 -1
  43. 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 and the four `wildshard` skills |
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 `build <folder>` wrote, unedited.
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
- **Not built yet (SA28).** `new` writes the four `wildshard` skills (SA14, SA27) but no `AGENTS.md` yet (SA28). `wildshard update` will rewrite this guide and the four `wildshard` skills in `.claude/skills/` from the
784
- installed sdk, and touch nothing else; it will leave an `AGENTS.md` you changed and say so. `wildshard update --pins` (SA18, after the sdk is on npm)
785
- will also move the sdk, shard-format and `three` versions, install, apply the release's code changes and run the
786
- build.
787
-
788
- Until then: after you move to a newer sdk, copy `GUIDE.md` from the sdk (the sharddev checkout's root, or
789
- `node_modules/@wildshard/sdk/GUIDE.md` once installed from npm) over this one, and each of the sdk's
790
- `skills/wildshard*/SKILL.md` over `.claude/skills/<same name>/SKILL.md`. The `wildshard-upgrade` skill walks it.
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
  }
@@ -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
- const source = rawSource.startsWith('file:') ? fileURLToPath(rawSource) : rawSource;
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",
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.6",
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.6"
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/engine/host/formatJsonSchema';
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
@@ -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
- return authorBundleCached(root,[shardfileValidationRevision(root),policy],async()=>{
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
- **`wildshard update --pins` is not built yet (SA18).** It will move the pins, install, apply the release's code
14
- changes, rewrite the guide and skills, and run the build (`GUIDE.md#7-wildshard-update`). Until it is built, do the
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. **Read the new pins** from the newer sdk's own `package.json`: its `version` is the `@wildshard/sdk` pin, and its
22
- `dependencies` hold the `@wildshard/engine`, `@wildshard/format` and `three` specs (engine and format are
23
- `github:` specs, not numbers). Today the sdk runs from a sharddev checkout, not npm (the guide's opening "Running
24
- `wildshard` today", `GUIDE.md#the-shard-authors-guide`). Done when you have each spec, copied verbatim.
25
- 3. **Edit the pins** in this repo's `package.json` to those exact specs: no `^`, no `~`. Done when every pin matches.
26
- 4. **Install:** `pnpm install`. A dependency's install script runs only if `pnpm-workspace.yaml` lists it
27
- (`GUIDE.md#2-the-shard-source`). Done when install exits 0 and `pnpm-lock.yaml` changed.
28
- 5. **Refresh the guide and skills.** Copy the sdk's `GUIDE.md` over this repo's, and each of the sdk's
29
- `skills/wildshard*/SKILL.md` to `.claude/skills/<same name>/SKILL.md`, adding any this repo lacks
30
- (`GUIDE.md#7-wildshard-update`). Then reread this skill: the new copy may differ. Done when `git diff` shows only
31
- those files and the step 3 and 4 files.
32
- 6. **Build** with the new sdk's CLI (point the `wildshard` alias at the newer checkout): `wildshard check .`
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.
@@ -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 pack prints it: totals, then one AMBER line per finding. */
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
- return audioReportLines(report)
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
- const reason = error instanceof Error ? error.message : String(error)
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
- function refuse(step: RefusalStep, prefix: string, reason: string): void {
12
- const hint = refusalHint(refusalNote(step, reason))
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
- const reason = error instanceof Error ? error.message : String(error)
36
- refuse(STEP, `${step} failed: `, reason)
35
+ refuse(STEP, `${step} failed: `, error)
37
36
  return EXIT_FAILED
38
37
  }
39
38
  }