@wildshard/sdk 0.2.4 → 0.2.6

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 (38) hide show
  1. package/GUIDE.md +77 -11
  2. package/codemods/0.2.5.mjs +12 -0
  3. package/lint/ratchet.json +1 -9
  4. package/lint/sdk-plugin.mjs +24 -2
  5. package/package.json +4 -3
  6. package/scripts/build-shardfiles.mjs +1 -1
  7. package/scripts/gen-format-schema.mjs +1 -1
  8. package/scripts/shard-build-pool.mjs +1 -1
  9. package/scripts/wildshard.mjs +11 -3
  10. package/skills/wildshard-upgrade/SKILL.md +22 -23
  11. package/src/cli/help.ts +6 -3
  12. package/src/sharddev/agentFiles.ts +4 -3
  13. package/src/sharddev/author.ts +16 -3
  14. package/src/sharddev/bake/authoredWorld.ts +1 -1
  15. package/src/sharddev/bake/specimenCatalogue.ts +1 -1
  16. package/src/sharddev/bake/staticMaterials.ts +1 -1
  17. package/src/sharddev/checkProject.ts +1 -1
  18. package/src/sharddev/cli.ts +11 -7
  19. package/src/sharddev/formatJsonSchema.ts +1117 -3
  20. package/src/sharddev/kit/bakedGeometry.ts +58 -12
  21. package/src/sharddev/nativePopulationRows.ts +1 -1
  22. package/src/sharddev/performancePolicy.ts +1 -1
  23. package/src/sharddev/phasedBoss.ts +212 -34
  24. package/src/sharddev/project.ts +1 -1
  25. package/src/sharddev/projectEntryProof.ts +1 -1
  26. package/src/sharddev/projectGeneration.ts +1 -1
  27. package/src/sharddev/projectOutput.ts +1 -1
  28. package/src/sharddev/projectSections.ts +1 -1
  29. package/src/sharddev/refusals.ts +9 -5
  30. package/src/sharddev/reportCard.ts +1 -1
  31. package/src/sharddev/sections.ts +1 -1
  32. package/src/sharddev/species/clips.ts +64 -24
  33. package/src/sharddev/speciesBrains.ts +98 -15
  34. package/src/sharddev/updatePins.ts +358 -0
  35. package/src/sharddev/weapons/bowProfile.ts +3 -3
  36. package/src/sharddev/weapons/meleeProfile.ts +48 -4
  37. package/src/sharddev/worldScenes.ts +1 -1
  38. package/tsconfig.author.json +1 -0
package/GUIDE.md CHANGED
@@ -53,7 +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]` | Rewrite this guide and the four `wildshard` skills from the installed sdk, after you move to a newer one (section 7) |
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) |
57
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) |
58
58
  | `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
59
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 |
@@ -340,13 +340,46 @@ other name refuses before `new` writes anything. Leave the flag out or pass `--t
340
340
 
341
341
  #### update-target
342
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`.
343
+ `update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it, or
344
+ `@wildshard/sharddev`. Run it in 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.
345
358
 
346
359
  #### update-pins
347
360
 
348
- `wildshard update --pins` (SA18) is not built yet. Move the pins by hand as the `wildshard-upgrade` skill says, then
349
- run `wildshard update` with no flag.
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.
350
383
 
351
384
  #### update-refused
352
385
 
@@ -486,18 +519,22 @@ Code `audio-refused`. Build prints every finding with one of the rules below und
486
519
 
487
520
  #### audio-unreadable
488
521
 
489
- Red. The recording does not read as AAC-LC at 48 kHz, mono or stereo. Export it again in that form. Code
490
- `audio-unreadable`.
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`.
491
524
 
492
525
  #### audio-container
493
526
 
494
527
  Red. The recording's bytes are FLAC, AIFF, Ogg, MP3, WebM, CAF or no container the game knows; it still counts toward
495
- the audio budget. Export it again as AAC (in an mp4 file) or as WAV. Code `audio-container`.
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`.
496
532
 
497
533
  #### audio-encoding
498
534
 
499
535
  Amber. The recording plays, but it is PCM WAV, AAC at a sample rate other than 48 kHz, or AAC outside the strict
500
- playback index. Encode it as AAC-LC at 48 kHz. Codes `audio-wav`, `audio-sample-rate`, `audio-strict-index`.
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`.
501
538
 
502
539
  #### audio-duration
503
540
 
@@ -891,5 +928,34 @@ keep your own notes for agents in `AGENTS.md`, never in this guide or a skill: `
891
928
  prints `already up to date` or the files it wrote, and `git status` shows only `GUIDE.md`, `.claude/skills/` and any
892
929
  agent file it added.
893
930
 
894
- `wildshard update --pins` (SA18) is not built yet: it will also move the sdk, shard-format and `three` versions,
895
- install, apply the release's code changes and run the build.
931
+ To move to a newer sdk, run the newest CLI once, whatever sdk the repo is on now:
932
+
933
+ ```sh
934
+ pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins
935
+ ```
936
+
937
+ An older installed CLI cannot do the move: 0.2.4 and earlier refuse the flag, and 0.2.5 refuses a repo that lists
938
+ the sdk as `@wildshard/sharddev` or by a GitHub pin. Once the repo is on the newest sdk, `pnpm exec wildshard
939
+ update --pins` works too.
940
+
941
+ `wildshard update --pins` moves the repo to a newer sdk release first: npm's latest, or the one you name with
942
+ `--pins=<version>` (`--pins=0.2.5`). In order, it:
943
+
944
+ 1. reads the release from npm (`pnpm view`) and refuses one older than the repo's sdk;
945
+ 2. moves every pin `package.json` lists to what that release names: the sdk to the release, `@wildshard/format`,
946
+ `@wildshard/engine` and `three` to the exact specs it pins, each `pnpm.overrides` entry for one of those packages
947
+ with it, and `engines.node` to the Node it needs. The sdk keeps the name and form the repo lists it with:
948
+ `@wildshard/sdk` or `@wildshard/sharddev`; an exact version, an `npm:@wildshard/sdk@<version>` alias, or a GitHub
949
+ pin, which moves to the commit the release's `v<version>` tag names (or to that tag, if it named a tag). It changes
950
+ nothing else in the file and prints each move;
951
+ 3. runs `pnpm install`, and refuses if pnpm did not install that sdk and, when the repo lists `three`, that `three`;
952
+ 4. applies the release's codemods: each `codemods/<version>.mjs` the new sdk ships, for every version above the old
953
+ sdk and up to the new one, oldest first. A codemod edits your shard source for a change that would otherwise
954
+ break it, and prints what it changed;
955
+ 5. runs the new sdk's own `wildshard update`, which rewrites this guide and the skills as above;
956
+ 6. runs the new sdk's `wildshard check .`.
957
+
958
+ If step 3 or 4 fails, it puts `package.json` and `pnpm-lock.yaml` back and installs the old sdk again. It refuses to
959
+ start unless `git status` is clean (`update-pins-dirty`, `update-pins-no-git`): a codemod edits your files. Done when
960
+ its last line reads `on @wildshard/sdk <version>, check pass`. Commit `package.json`, `pnpm-lock.yaml`, the guide,
961
+ the skills and any codemod edit together. A refusal is `update-pins` (section 6).
@@ -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.4",
3
+ "version": "0.2.6",
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.8",
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.8"
200
+ "@wildshard/format": "github:project-wildshard/shard-format#v0.4.9"
200
201
  }
201
202
  },
202
203
  "exports": {
@@ -195,7 +195,7 @@ export async function buildShardfiles(root,options={}) {
195
195
  const counters=createBuildCacheCounters(),stop=observeBuildCache(counters);
196
196
  let complete=false;
197
197
  try {const result=await buildShardfilesWork(root,options,counters);complete=true;return result;}
198
- finally {stop();console.info(formatBuildCacheReport(counters.snapshot(complete)));}
198
+ finally {stop();if(process.env.WILDSHARD_CACHE_REPORT==='1')console.info(formatBuildCacheReport(counters.snapshot(complete)));}
199
199
  }
200
200
 
201
201
  if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
@@ -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
@@ -30,7 +30,7 @@ export async function runShardBuildPool(items, work, prepare) {
30
30
  export function runShardBuild(args, signal, cacheReport) {
31
31
  return new Promise((resolve, reject) => {
32
32
  const child = spawn(process.execPath, ['--import', fileURLToPath(import.meta.resolve('@wildshard/engine/scripts/shardfile-inputs.mjs')), resolvePath(import.meta.dirname, 'wildshard.mjs'), ...args], {
33
- cwd: process.cwd(), env: {...process.env,WILDSHARD_WORLD_TEXTURE_CACHE:process.env.WILDSHARD_WORLD_TEXTURE_CACHE??resolvePath(shardfileCacheRoot(),'.world-textures-v1')}, signal, stdio: ['ignore', 'inherit', 'pipe'],
33
+ cwd: process.cwd(), env: {...process.env,...(cacheReport===undefined?{}:{WILDSHARD_CACHE_REPORT:'1'}),WILDSHARD_WORLD_TEXTURE_CACHE:process.env.WILDSHARD_WORLD_TEXTURE_CACHE??resolvePath(shardfileCacheRoot(),'.world-textures-v1')}, signal, stdio: ['ignore', 'inherit', 'pipe'],
34
34
  });
35
35
  // Forward all diagnostics, retaining only a bounded tail for the pool's error.
36
36
  let stderrTail = '';
@@ -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 };
@@ -101,5 +107,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1]
101
107
  complete=true;
102
108
  }
103
109
  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
104
- finally {stop();console.error(`\n${formatBuildCacheReport(counters.snapshot(complete))}`);}
110
+ // The counters line is for the build pool, which sets WILDSHARD_CACHE_REPORT=1 for the children whose report it reads,
111
+ // and for debugging a build's cache; an author's run, refusals included, does not print it.
112
+ finally {stop();if(process.env.WILDSHARD_CACHE_REPORT==='1')console.error(`\n${formatBuildCacheReport(counters.snapshot(complete))}`);}
105
113
  }
@@ -10,38 +10,37 @@ 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
+ Run the newest CLI once to move, whatever sdk the repo is on now:
14
+
15
+ ```sh
16
+ pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins
17
+ ```
18
+
19
+ `wildshard update --pins` does the move in one command (`GUIDE.md#7-wildshard-update`): it moves every pin to the
20
+ release, runs `pnpm install`, applies the release's codemods, rewrites the guide and skills, and runs check. An
21
+ installed 0.2.4 or older refuses the flag, and 0.2.5 refuses a repo that lists the sdk as `@wildshard/sharddev` or by
22
+ a GitHub pin, so start from the line above.
16
23
 
17
24
  ## The steps, in order
18
25
 
19
26
  1. **Start clean.** Commit your own changes, then `wildshard check .` on the old pins; if it fails, fix that first.
20
27
  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** with the new sdk's CLI (point the `wildshard` alias at the newer checkout, or
29
- `pnpm exec wildshard` after step 4): `wildshard update`. It rewrites `GUIDE.md` and the four skills in
30
- `.claude/skills/`, adds any agent file the repo lacks, and keeps an `AGENTS.md` you changed
31
- (`GUIDE.md#7-wildshard-update`). Then reread this skill: the new copy may differ. Done when update's first line
32
- names the new sdk version and `git status` shows only those files and the step 3 and 4 files.
33
- 6. **Build:** `wildshard check .` (`GUIDE.md#1-the-loop`). Done when `wildshard --version` prints the new sdk
34
- version and the last line reads `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 update wrote 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, any agent file update added and your fixes together.
39
- Done when `git status` is clean.
28
+ 2. **Move:** `pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins` for npm's latest sdk, or
29
+ `--pins=<version>` in place of `--pins` for one release. Done when it prints a line per pin it moved.
30
+ 3. **Read its last line.** `on @wildshard/sdk <version>, check pass` means the move is done: go to step 5. A line
31
+ ending `[update-pins] fix: ...` is a refusal: read `GUIDE.md#update-pins` in the guide now in the repo;
32
+ `[update-pins-dirty]` (`GUIDE.md#update-pins-dirty`) means go back to step 1.
33
+ 4. **Fix each refusal check printed.** It ends `[<rule>] fix: ... (GUIDE.md#<anchor>)`: read that heading under
34
+ `GUIDE.md#6-refusals-and-their-fixes`, make the fix, and run `wildshard check .` again. A budget can tighten
35
+ between releases (`GUIDE.md#3-budgets`); a lint rule can be new. Done at `check pass`.
36
+ 5. **Reread this skill:** step 2 rewrote it, and the new copy may differ. Done when you have read the new copy.
37
+ 6. **Commit** `package.json`, `pnpm-lock.yaml`, the guide, the skills, any agent file update added, any codemod edit
38
+ and your fixes together. Done when `git status` is clean.
40
39
  A new sdk can change what the shard looks like, so before the next upload follow the `wildshard-goldens` skill.
41
40
 
42
41
  ## Rules
43
42
 
44
- - Move the pins together, never one alone: the sdk is built and tested against the others it names.
43
+ - Move the pins together, never one alone: the sdk is built and tested against the others it names. `--pins` does.
45
44
  - Fix the shard source to the new rules; do not pin an older piece to dodge a refusal.
46
45
  - 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
47
46
  and report the message.
package/src/cli/help.ts CHANGED
@@ -24,14 +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]
27
+ update: `update [dir] [--pins[=<version>]]
28
28
  Rewrite GUIDE.md and the four wildshard skills in
29
29
  .claude/skills/ from the installed sdk (dir: the
30
30
  shard repo, default the current folder). Adds the
31
31
  .agents/skills links, AGENTS.md and CLAUDE.md if
32
32
  missing; touches nothing else, and leaves an
33
- AGENTS.md you changed (it says so). Run it after
34
- moving to a newer sdk. --pins is not built yet`,
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`,
35
38
  dev: `dev <source> [port]
36
39
  Serve the shard source on localhost (port 0, the
37
40
  default, picks a free one) and build it again on
@@ -101,15 +101,16 @@ function sdkVersion(root: string): string {
101
101
  return typeof parsed === 'object' && parsed !== null && 'version' in parsed && typeof parsed.version === 'string' ? parsed.version : 'unknown';
102
102
  }
103
103
 
104
- /** A shard repo is a folder whose package.json lists `@wildshard/sdk` (`new` writes it; a blender repo as a dev dependency). */
105
- function assertShardRepo(project: string): void {
104
+ /** A shard repo is a folder whose package.json lists `@wildshard/sdk` (`new` writes it; a blender repo as a dev dependency)
105
+ * or `@wildshard/sharddev`, the name the org's shard repos list it under (a GitHub pin, or an `npm:@wildshard/sdk` alias). */
106
+ export function assertShardRepo(project: string): void {
106
107
  const file = resolve(project, 'package.json');
107
108
  let parsed: unknown;
108
109
  try { parsed = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined; }
109
110
  catch (error) { throw new Error(`update: ${project} is not a shard repo: its package.json is not valid JSON (${error instanceof Error ? error.message : String(error)})`, { cause: error }); }
110
111
  const fields: unknown[] = typeof parsed === 'object' && parsed !== null
111
112
  ? [Reflect.get(parsed, 'dependencies'), Reflect.get(parsed, 'devDependencies')] : [];
112
- if (!fields.some(field => typeof field === 'object' && field !== null && Object.hasOwn(field, '@wildshard/sdk'))) throw new Error(`update: ${project} is not a shard repo: its package.json does not list @wildshard/sdk (or it has none)`);
113
+ if (!fields.some(field => typeof field === 'object' && field !== null && (Object.hasOwn(field, '@wildshard/sdk') || Object.hasOwn(field, '@wildshard/sharddev')))) throw new Error(`update: ${project} is not a shard repo: its package.json does not list @wildshard/sdk or @wildshard/sharddev (or it has none)`);
113
114
  }
114
115
 
115
116
  /** `wildshard update [dir]`: sync the agent files of the shard repo at `project`, and say what changed, one line each. */
@@ -1,3 +1,16 @@
1
- // Engine's, coverage row 6: one copy, and this repo keeps the name.
2
- // oxlint-disable-next-line wildshard/no-reexport, oxc/no-barrel-file -- Authors import this name, and engine owns the bytes.
3
- export * from '@wildshard/engine/host/author';
1
+ // The SDK's starting shardfile (SHARD-AUTHORING SA26): built here and admitted by shard-format's own parser, the one
2
+ // the client runs, so a project starts from a file the game accepts.
3
+ import { parseShardfile, type Shardfile } from '@wildshard/format/shardSchema';
4
+ import { ENTRY_WIDTH } from '@wildshard/format/contentBounds';
5
+ import { SHARDFILE_VERSION } from '@wildshard/format/version';
6
+
7
+ /** Start an author project with a valid empty world; add baked content before shipping a playable shard. */
8
+ export function emptyShardfile(identity: Shardfile['identity']): Shardfile {
9
+ const edge = { heights: Array.from({ length: 257 }, () => 0), colours: Array.from({ length: 257 }, () => [0.5, 0.5, 0.5]), roadHeight: 0 };
10
+ return parseShardfile({ version: SHARDFILE_VERSION, identity, accent: 'sand', requires: { sdk: SHARDFILE_VERSION, capabilities: [], commons: [], commonsWire: {}, commonsCosts: {} }, budgets: { library: { resident: 0, compressed: 0 }, sim: { resident: 0, compressed: 0 }, overlap: 0 },
11
+ entryways: [{ edge: 'north', at: [0, 0, 250], width: ENTRY_WIDTH }, { edge: 'east', at: [250, 0, 0], width: ENTRY_WIDTH }, { edge: 'south', at: [0, 0, -250], width: ENTRY_WIDTH }, { edge: 'west', at: [-250, 0, 0], width: ENTRY_WIDTH }],
12
+ look: { families: [], grade: { exposure: 0, saturation: 1, contrast: 1, lut: null }, clock: 'engine', dayOverride: null, keys: [] },
13
+ sim: { fixedHz: 60, scriptTickDivisor: 2, commandVersion: 0, snapshotVersion: 0, scripts: [] },
14
+ state: { version: 1, sharedOwner: 'host', playerKey: 'actorId', shared: [], player: [] }, authorCaps: { players: 32, speed: 15 },
15
+ serverBudget: { tickMicros: 1000, memory: 1_000_000, entities: 100, commandsPerTick: 32 }, edge: { north: edge, south: edge, east: edge, west: edge }, files: [], tiles: [], library: [], critical: [], far: null });
16
+ }
@@ -3,7 +3,7 @@ import * as v from 'valibot';
3
3
  import { isJsonData } from '@wildshard/format/json';
4
4
  import { FAMILY_IDS, PbrMaterialSchema } from '@wildshard/format/materialFamilies';
5
5
  import { MaterialsSchema, materialGraphIr } from '@wildshard/format/materials';
6
- import { parseShardfile, type Shardfile } from '@wildshard/engine/host/shardfile';
6
+ import { parseShardfile, type Shardfile } from '@wildshard/format/shardSchema';
7
7
  import { normalizeWorldGlb, type NormalizedWorld, type WorldPrimitive } from './world';
8
8
  import { parseWorldSource } from '../worldSource';
9
9
  import { bakeWorldTexture } from './textureWasm';
@@ -1,7 +1,7 @@
1
1
  import { parse, object, array, string, unknown } from 'valibot';
2
2
  import { PickupCatalogueSchema, SpecimenBookSchema, type PickupCatalogueRows, type SpecimenBookRows, type SpecimenModelMetadataRows } from '@wildshard/format/specimenCatalogue';
3
3
  import pickupRows from '@wildshard/engine/game/data/pickupCatalogue' with { type: 'json' };
4
- import { namedJsonSchema } from '@wildshard/engine/host/formatJsonSchema';
4
+ import { namedJsonSchema } from '../formatJsonSchema';
5
5
  import { encodeCanonicalJson } from '../immutable';
6
6
  import { nameBlob, type NamedBlob, type BlobOptions } from '../blobs';
7
7
 
@@ -1,5 +1,5 @@
1
1
  import { MeshStandardMaterial, type BufferGeometry } from 'three';
2
- import type { Shardfile } from '@wildshard/engine/host/shardfile';
2
+ import type { Shardfile } from '@wildshard/format/shardSchema';
3
3
  import { parseKtx2 } from '../assets';
4
4
  import { hashImmutableBytes } from '../immutable';
5
5
  import type { WorldMaterial, WorldTexture } from './world';
@@ -10,7 +10,7 @@ import { basename, dirname, resolve } from 'node:path';
10
10
  import * as v from 'valibot';
11
11
  import { AuthorProofPlanSchema } from '@wildshard/engine/host/tickProtocol';
12
12
  import { measureSimulation, proveAuthorSimulation } from '@wildshard/engine/host/headless';
13
- import type { Shardfile } from '@wildshard/engine/host/shardfile';
13
+ import type { Shardfile } from '@wildshard/format/shardSchema';
14
14
  import { buildProject } from './project';
15
15
  import { isHandwrittenSource, isRepoSource, shardOutputRoot } from './shardSource';
16
16
  import { handwrittenIdentity, settleHandwritten } from './handwritten';
@@ -3,7 +3,7 @@ import { basename, dirname, resolve } from 'node:path';
3
3
  // oxlint-disable-next-line import/no-nodejs-modules -- `prove` tells a project from a built product by its config file.
4
4
  import { existsSync } from 'node:fs';
5
5
  import { buildProject, readProjectAssets, validateProject } from './project';
6
- import { ShardfileSchema, type Shardfile } from '@wildshard/engine/host/shardfile';
6
+ import { ShardfileSchema, type Shardfile } from '@wildshard/format/shardSchema';
7
7
  import { devProject } from './dev';
8
8
  import { proveAuthorSimulation, measureSimulation, validateSimulation } from '@wildshard/engine/host/headless';
9
9
  import { performanceReport, performanceReportLines, type PerformanceObservations } from './reportCard';
@@ -15,13 +15,14 @@ import { assetOverdraw } from './assets';
15
15
  import process from 'node:process';
16
16
  import { buildBehaviourProject } from './buildBehaviour';
17
17
  import { synthProject } from './synth';
18
- import { formatJsonSchemas, schemaAt, schemaDeclaration } from '@wildshard/engine/host/formatJsonSchema';
18
+ import { formatJsonSchemas, schemaAt, schemaDeclaration } from './formatJsonSchema';
19
19
  import { decisionModuleContracts } from '@wildshard/format/scriptContract';
20
20
  import { outputScriptAdmissionRows, validateOutputProduct } from './outputProduct';
21
21
  import { locatedError } from './authorError';
22
22
  import type { ProjectManifestSource } from './projectManifest';
23
23
  import { templateNamed, writeShardRepo } from './newProject';
24
24
  import { updateShardRepo } from './agentFiles';
25
+ import { updatePins } from './updatePins';
25
26
  import { findShardSource, isHandwrittenSource, isRepoSource, shardOutputRoot } from './shardSource';
26
27
  import { checkProject, readProofTape } from './checkProject';
27
28
  import { checkLines } from './check';
@@ -82,11 +83,14 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
82
83
  return;
83
84
  }
84
85
  if (command === 'update') {
85
- // SA28 (J314 Q7, Q27): one verb; `update --pins` (SA18) will also move the pins, install and run the build.
86
- const rest = args.slice(1);
87
- if (rest.includes('--pins')) throw new Error('update --pins is not built yet (SA18): move the pins by hand (the wildshard-upgrade skill), then run wildshard update');
88
- if (rest.length > 1 || rest.some(value => value.startsWith('-'))) throw new Error('usage: wildshard update [dir]');
89
- for (const line of updateShardRepo(resolve(rest[0] ?? '.'))) console.info(line);
86
+ // SA28 (J314 Q7, Q27): one verb. SA18: `--pins[=<version>]` also moves the pins, installs, applies the release's
87
+ // codemods and runs check (updatePins.ts); with no version it takes npm's latest.
88
+ const rest = args.slice(1), pins = rest.filter(value => value === '--pins' || value.startsWith('--pins='));
89
+ const positional = rest.filter(value => !pins.includes(value)), version = pins[0]?.startsWith('--pins=') === true ? pins[0].slice('--pins='.length) : 'latest';
90
+ if (pins.length > 1 || version === '' || positional.length > 1 || positional.some(value => value.startsWith('-'))) throw new Error('usage: wildshard update [dir] [--pins[=<version>]]');
91
+ if (pins.length === 1 && /^\d+\.\d+\.\d+/u.test(positional[0] ?? '') && !existsSync(resolve(positional[0] ?? ''))) throw new Error(`usage: wildshard update [dir] [--pins[=<version>]]: name a version as --pins=${positional[0] ?? ''}`);
92
+ if (pins.length === 1) { await updatePins(resolve(positional[0] ?? '.'), version); return; }
93
+ for (const line of updateShardRepo(resolve(positional[0] ?? '.'))) console.info(line);
90
94
  return;
91
95
  }
92
96
  if (input === undefined) throw new Error('usage: wildshard new <dir> | check <source> [folder] [--json] | synth <source> | build <source> [folder] [--shardfile-only|--folder-only] [--no-placeholders] [--output=<slug>] | build <source> --behaviour-only | validate <source|shard.json> | dev <source> [port] (wildshard --help lists them all)');