@wildshard/sdk 0.3.2 → 0.3.3

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 (79) hide show
  1. package/GUIDE.md +19 -6
  2. package/bin/wildshard.mjs +4 -0
  3. package/docs/api/EXPORT-TIERS.md +3 -2
  4. package/lint/export-tiers.json +1 -0
  5. package/lint/sdk-plugin.d.mts +2 -0
  6. package/lint/sdk-plugin.mjs +39 -1
  7. package/package.json +10 -9
  8. package/scripts/capture-hero.mjs +48 -18
  9. package/scripts/ci21-sdk-tail-lint.mjs +95 -0
  10. package/scripts/keep-copy.mjs +172 -0
  11. package/scripts/land.mjs +34 -4
  12. package/scripts/lane-live.mjs +136 -0
  13. package/scripts/leftovers-report.mjs +47 -0
  14. package/scripts/lint-dispatch.mjs +5 -0
  15. package/scripts/music/export-midi.mjs +3 -2
  16. package/scripts/prepare-product.mjs +3 -2
  17. package/scripts/scratch-dir.d.mts +3 -0
  18. package/scripts/scratch-dir.mjs +33 -14
  19. package/scripts/scratch-sweep.mjs +15 -23
  20. package/scripts/typecheck.mjs +15 -0
  21. package/scripts/worktree-reap.mjs +46 -104
  22. package/scripts/worktree.mjs +35 -13
  23. package/skills/wildshard/SKILL.md +3 -1
  24. package/src/cli/content-command.ts +44 -0
  25. package/src/cli/content.ts +287 -0
  26. package/src/cli/help.ts +7 -2
  27. package/src/cli/hero/hero.ts +6 -1
  28. package/src/cli/hero/scene-card.ts +46 -0
  29. package/src/cli/hero/stamp.ts +5 -3
  30. package/src/sharddev/authorManifest.ts +20 -2
  31. package/src/sharddev/cli.ts +1 -1
  32. package/src/sharddev/dev.ts +23 -4
  33. package/src/sharddev/newProject.ts +27 -8
  34. package/src/sharddev/project.ts +2 -2
  35. package/src/sharddev/refusals.ts +1 -0
  36. package/src/sharddev/scene/author.ts +22 -1
  37. package/src/sharddev/scene/budget.ts +87 -0
  38. package/src/sharddev/scene/creature.ts +171 -0
  39. package/src/sharddev/scene/description.ts +41 -0
  40. package/src/sharddev/scene/lower.ts +127 -3
  41. package/src/sharddev/scene/shardfile.ts +196 -14
  42. package/src/sharddev/shardSource.ts +2 -2
  43. package/src/sharddev/test/diskScriptScenario.ts +4 -2
  44. package/src/sharddev/test/ownedScratch.ts +14 -0
  45. package/src/sharddev/test/scriptScenario.ts +18 -13
  46. package/src/sharddev/tsconfig.json +3 -0
  47. package/src/sharddev/watch/pageEntry.ts +1 -19
  48. package/src/sharddev/watch/parity-baseline.json +6 -6
  49. package/src/sharddev/watch/parity.mjs +24 -0
  50. package/src/sharddev/watch/watch.ts +10 -2
  51. package/src/shards/_template/behaviour/boss.as +13 -4
  52. package/src/shards/_template/behaviour/door.as +8 -3
  53. package/src/shards/_template/behaviour/hooks.json +35 -0
  54. package/src/shards/_template/card/landscape.jpg +0 -0
  55. package/src/shards/_template/card/portrait.jpg +0 -0
  56. package/src/shards/_template/card/thumb.jpg +0 -0
  57. package/src/shards/_template/data/bossDecision.json +11 -1
  58. package/src/shards/_template/data/card.json +49 -1
  59. package/src/shards/_template/data/clientScripts.json +411 -0
  60. package/src/shards/_template/data/creatures.json +280 -2
  61. package/src/shards/_template/data/items.json +1 -1
  62. package/src/shards/_template/data/layout.json +32 -1
  63. package/src/shards/_template/data/ledger.json +45 -0
  64. package/src/shards/_template/data/npcs/hermit.json +72 -0
  65. package/src/shards/_template/data/quests.json +297 -11
  66. package/src/shards/_template/data/rows.json +154 -0
  67. package/src/shards/_template/data/skins.json +14 -0
  68. package/src/shards/_template/data/targets.json +47 -0
  69. package/src/shards/_template/data/text.json +4 -1
  70. package/src/shards/_template/generators/lift.ts +71 -0
  71. package/src/shards/_template/generators/product.ts +19 -5
  72. package/src/shards/_template/generators/templatePropsSource.ts +5 -4
  73. package/src/shards/_template/generators/terrain.ts +10 -2
  74. package/src/shards/_template/generators/world.ts +42 -7
  75. package/src/shards/_template/hero.json +6 -6
  76. package/src/shards/_template/manifest.json +49 -1
  77. package/src/shards/authoring-slice/generators/shard.ts +2 -1
  78. package/src/shards/authoring-slice/generators/world.ts +8 -1
  79. package/tsconfig.author.json +24 -0
package/GUIDE.md CHANGED
@@ -54,11 +54,12 @@ with `rule`, `fix` and `guide`) for agents and scripts.
54
54
 
55
55
  | Verb | What it is for |
56
56
  |---|---|
57
- | `wildshard new <dir> [slug] [--template sdk] [--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. It copies the reference world (`--template sdk`, the only template); any other template refuses before writing, and `--template blender` is retired (below). `--empty` writes a bare shard source instead of the reference world |
57
+ | `wildshard new <dir> [slug] [--template sdk\|scene] [--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. It copies the reference world (`--template sdk`), or Mossgate Hollow as one three.js scene module (`--template scene`: `src/generators/world.ts` is the whole world, and `wildshard watch .` shows each save); any other template refuses before writing, and `--template blender` is retired (below). `--empty` writes a bare shard source instead of the reference world |
58
58
  | `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) |
59
59
  | `wildshard dev <source>` | Serve the shard source on localhost and rebuild on every save (section 4). The first run fetches engine's dev client once ("Walking your shard") |
60
- | `wildshard watch <source>` | For a shard written as a three.js scene (`@wildshard/sdk/scene/shard`): serve it once, then swap each edited part into the running page in about a second, no reload. A look, ground or spawn edit still reloads |
60
+ | `wildshard watch <source>` | For a shard written as a three.js scene (`@wildshard/sdk/scene/shard`): serve it once, then swap each edited part into the running page in about a second, no reload. A look, ground or spawn edit still reloads. A repo `new --template scene` made runs it as `pnpm watch` |
61
61
  | `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
62
+ | `wildshard content <folder> [--bar templates]` | Count the content in a built shard; the template bar lists every shortfall. `--bar=templates` also works |
62
63
  | `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 |
63
64
  | `wildshard upload <file> --channel staging\|prod` | Send a prepared shard file to the API (section 5) |
64
65
  | `wildshard account <email>` | Make your account once and save its key, which upload sends (see "Uploading", step 5) |
@@ -99,9 +100,14 @@ hero:
99
100
  2. Run `wildshard hero . --base <url>` with the URL `dev` printed. It opens that page in headless Chromium, enters your
100
101
  shard, shoots the view `hero.json`'s `camera` names (or the spawn view), writes the three files and stamps
101
102
  `hero.json` with a hash of your content. A `data:` card becomes `card/thumb.jpg`, `card/portrait.jpg` and
102
- `card/landscape.jpg`, named in both `manifest.json` and `data/card.json`.
103
+ `card/landscape.jpg`, named in both `manifest.json` and `data/card.json`. A scene shard (a `shard.config.ts` and no
104
+ `manifest.json`) gets the same three files; its next build's card wears them.
103
105
  3. Look at the three images, then stop `dev` with Ctrl-C.
104
106
 
107
+ A refusal is one line that starts with its rule, `[hero-<rule>]`, never a stack: `hero-no-source` (no shard here),
108
+ `hero-no-name` (a scene shard with no build, captured from a served build that isn't `dev`), `hero-no-card`,
109
+ `hero-card-file`, `hero-curated`, `hero-size` and `hero-page-error`.
110
+
105
111
  Build then refuses a shard file whose content changed after the hero was stamped (`hero-stale`), and upload refuses a
106
112
  new version whose hero is the same as the previous version's (`hero-unchanged`). Section 6 has every hero refusal.
107
113
 
@@ -344,9 +350,10 @@ an existing folder.
344
350
 
345
351
  #### new-template
346
352
 
347
- `--template` names `sdk` (the reference world, the default and only template). Any other name refuses before `new`
348
- writes anything. `--template blender` is retired (J341): a shard is TypeScript three.js scene source, and Blender
349
- makes the `.glb` models it loads (section 2). Leave the flag out or pass `--template sdk`.
353
+ `--template` names `sdk` (the reference world, the default) or `scene` (Mossgate Hollow as one three.js scene module:
354
+ `src/generators/world.ts` builds the whole world, and `wildshard watch .` draws each save in a running page). Any other
355
+ name refuses before `new` writes anything. `--template blender` is retired (J341): a shard is TypeScript three.js scene
356
+ source, and Blender makes the `.glb` models it loads (section 2). Leave the flag out or pass `--template sdk` or `scene`.
350
357
 
351
358
  #### new-refused
352
359
 
@@ -755,6 +762,12 @@ An import the rule denies. In `generators/` any npm package, valibot, shard-form
755
762
  rule denies engine, sdk paths outside its exports, another shard's source and a second copy of `three`. In `data/` and
756
763
  `shard.config.ts` only `three`, valibot, shard-format, the sdk and Node built-ins are allowed.
757
764
 
765
+ #### lint-no-hand-graph
766
+
767
+ A hand-written graph: a `*.graph.json` or `*.post.json` import, or an object with `version`, `kind` and `nodes`. Write
768
+ the graph in TSL with `graph()` from `@wildshard/sdk/materials` (`new GraphMaterial(graph({ model, surface, lighting
769
+ }))`); the sdk compiles it to the same graph IR (SHARD-SOURCE AP39).
770
+
758
771
  #### lint-engine-internal
759
772
 
760
773
  Shard code imports a game-only engine export; use the sdk's shard-facing one.
package/bin/wildshard.mjs CHANGED
@@ -36,4 +36,8 @@ if (verbHelp) {
36
36
  const script = resolve(import.meta.dirname, '../scripts/build-shardfiles.mjs');
37
37
  process.argv.splice(1, 2, script);
38
38
  await import(pathToFileURL(script).href);
39
+ } else if (command === 'content') {
40
+ const script = resolve(import.meta.dirname, '../src/cli/content-command.ts');
41
+ process.argv.splice(1, 2, script);
42
+ await import(pathToFileURL(script).href);
39
43
  } else await import('../src/cli/main.ts');
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- generated by scripts/export-tiers.mjs from package.json exports and lint/export-tiers.json: do not edit -->
4
4
 
5
- 176 exports. A shard project imports from contract, rows, scripts and the bake kit; internal may change in any release. A new export needs a row in `lint/export-tiers.json` (`test/export-tiers.test.ts` fails without one); then run `node scripts/export-tiers.mjs`.
5
+ 177 exports. A shard project imports from contract, rows, scripts and the bake kit; internal may change in any release. A new export needs a row in `lint/export-tiers.json` (`test/export-tiers.test.ts` fails without one); then run `node scripts/export-tiers.mjs`.
6
6
 
7
7
  ## contract (28)
8
8
 
@@ -106,7 +106,7 @@ Scripts: the decision and client script compilers, their AssemblyScript helpers
106
106
  | `@wildshard/sdk/directorAbi` | scripts | `./src/sharddev/directorAbi.ts` |
107
107
  | `@wildshard/sdk/returnProjectionV2` | scripts | `./src/sharddev/returnProjectionV2.ts` |
108
108
 
109
- ## bake kit (86)
109
+ ## bake kit (87)
110
110
 
111
111
  The bake kit: build-time geometry, texture, map and commons helpers; nothing here runs in the game.
112
112
 
@@ -193,6 +193,7 @@ The bake kit: build-time geometry, texture, map and commons helpers; nothing her
193
193
  | `@wildshard/sdk/random` | bake kit | `./src/sharddev/random.ts` |
194
194
  | `@wildshard/sdk/scene/author` | bake kit | `./src/sharddev/scene/author.ts` |
195
195
  | `@wildshard/sdk/scene/canvas` | bake kit | `./src/sharddev/scene/canvas.ts` |
196
+ | `@wildshard/sdk/scene/creature` | bake kit | `./src/sharddev/scene/creature.ts` |
196
197
  | `@wildshard/sdk/scene/description` | bake kit | `./src/sharddev/scene/description.ts` |
197
198
  | `@wildshard/sdk/scene/lower` | bake kit | `./src/sharddev/scene/lower.ts` |
198
199
  | `@wildshard/sdk/scene/shard` | bake kit | `./src/sharddev/scene/shard.ts` |
@@ -17,6 +17,7 @@
17
17
  "./scene/lower": "bake kit",
18
18
  "./scene/description": "bake kit",
19
19
  "./scene/shardfile": "bake kit",
20
+ "./scene/creature": "bake kit",
20
21
  "./watch/watch": "internal",
21
22
  "./watch/protocol": "bake kit",
22
23
  "./watch/page": "internal",
@@ -2,3 +2,5 @@
2
2
  export function generatorImportViolation(filename: string, source: string | null, required?: boolean): string | null;
3
3
  declare const plugin: { readonly meta: { readonly name: string }; readonly rules: Readonly<Record<string, object>> };
4
4
  export default plugin;
5
+ /** SHARD-SOURCE AP39: why importing `source` from `filename` is a hand-written graph, or null when it is not (or `allow` names the file). */
6
+ export function handGraphImport(filename: string, source: string | null, allow?: readonly string[]): string | null;
@@ -164,5 +164,43 @@ const generatorImports = {
164
164
  },
165
165
  };
166
166
 
167
- const plugin = { meta: { name: 'wildshard-sdk' }, rules: { 'generator-imports': generatorImports } };
167
+ // SHARD-SOURCE AP39: graphs are written in TSL (`graph()` from @wildshard/sdk/materials, AP13), which compiles to the graph
168
+ // IR; a hand-written IR (a `*.graph.json` or `*.post.json` file, or an object literal with `version`, `kind` and `nodes`)
169
+ // is refused in shard source. `allow` names the fixtures that still import one (path suffixes), none new.
170
+ const HAND_GRAPH = 'no-hand-graph';
171
+ const GRAPH_FILE = /\.(?:graph|post)\.json(?:[?#].*)?$/u;
172
+ const handGraphMessage = (what) => `${HAND_GRAPH}: ${what} is a hand-written graph; write it in TSL with graph() from `
173
+ + '@wildshard/sdk/materials, which compiles to the same graph IR (new GraphMaterial(graph({ ... })))';
174
+ const keyName = (property) => property.type === 'Property' && !property.computed
175
+ ? (property.key.type === 'Identifier' ? property.key.name : property.key.type === 'Literal' ? String(property.key.value) : null) : null;
176
+ export function handGraphImport(filename, source, allow = []) {
177
+ const path = resolve(filename).replaceAll('\\', '/');
178
+ if (shardFile(path) === null || typeof source !== 'string' || !GRAPH_FILE.test(source)) return null;
179
+ if (allow.some((suffix) => path.endsWith(suffix))) return null;
180
+ return handGraphMessage(`the import ${source}`);
181
+ }
182
+ const noHandGraph = {
183
+ meta: { type: 'problem', docs: { description: 'Graphs are TSL source, not hand-written graph IR (SHARD-SOURCE AP39)' },
184
+ schema: [{ type: 'object', properties: { allow: { type: 'array', items: { type: 'string' } } }, additionalProperties: false }] },
185
+ create(context) {
186
+ const allow = context.options[0]?.allow ?? [];
187
+ const path = resolve(context.filename).replaceAll('\\', '/');
188
+ if (shardFile(path) === null || allow.some((suffix) => path.endsWith(suffix))) return {};
189
+ const check = (node, specifier) => {
190
+ const source = importPrefix(specifier), reason = handGraphImport(context.filename, source, allow);
191
+ if (reason !== null) context.report({ node, message: reason });
192
+ };
193
+ return {
194
+ ImportDeclaration(node) { check(node, node.source); },
195
+ ImportExpression(node) { check(node, node.source); },
196
+ ObjectExpression(node) {
197
+ const keys = new Set(node.properties.map(keyName));
198
+ const nodes = node.properties.find((property) => keyName(property) === 'nodes');
199
+ if (keys.has('version') && keys.has('kind') && nodes?.value?.type === 'ObjectExpression') context.report({ node, message: handGraphMessage('this object') });
200
+ },
201
+ };
202
+ },
203
+ };
204
+
205
+ const plugin = { meta: { name: 'wildshard-sdk' }, rules: { 'generator-imports': generatorImports, [HAND_GRAPH]: noHandGraph } };
168
206
  export default plugin; // oxlint loads a JS plugin from its default export
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.3.2",
3
+ "version": "0.3.3",
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": {
@@ -46,8 +46,8 @@
46
46
  "drafts:build": "vite build --config drafts/vite.config.ts",
47
47
  "drafts:deploy": "bash drafts/tools/deploy.sh",
48
48
  "drafts:test": "tsc -p drafts/tsconfig.json && tsc -p drafts/tools/tsconfig.json && vitest run drafts/test && node drafts/tools/atlas.ts --check",
49
- "typecheck": "pnpm typecheck:kit && pnpm typecheck:author",
50
- "lint": "node scripts/lint-dispatch.mjs --ignore-pattern 'scripts/chromium-keychain*' --ignore-pattern 'test/tooling/chrome-keychain.test.mjs'",
49
+ "typecheck": "node scripts/typecheck.mjs",
50
+ "lint": "node scripts/lint-dispatch.mjs",
51
51
  "lint:kit": "node kit/scripts/lint.mjs --type-aware --deny-warnings --ignore-pattern '.githooks/**' --ignore-pattern '.agents/**' --ignore-pattern 'tmp/**' --ignore-pattern 'vitest.config.ts' --ignore-pattern 'src/sharddev/**' --ignore-pattern 'src/commons/**' --ignore-pattern 'src/shards/**' --ignore-pattern 'public/**' --ignore-pattern 'scripts/**' --ignore-pattern 'test/**' --ignore-pattern 'drafts/**' --ignore-pattern 'lint/**' --ignore-pattern 'vite/**' --ignore-pattern 'bin/**' --no-error-on-unmatched-pattern",
52
52
  "lint:fix": "node kit/scripts/lint.mjs --type-aware --fix --ignore-pattern '.githooks/**' --ignore-pattern '.agents/**' --ignore-pattern 'scripts/agent-parity.mjs' --ignore-pattern 'scripts/agent-sync.mjs' --ignore-pattern 'tmp/**' --ignore-pattern 'vitest.config.ts' --ignore-pattern 'src/sharddev/**' --ignore-pattern 'src/commons/**' --ignore-pattern 'src/shards/**' --ignore-pattern 'public/**' --ignore-pattern 'scripts/**' --ignore-pattern 'test/**' --ignore-pattern 'drafts/**' --ignore-pattern 'lint/**' --ignore-pattern 'vite/**' --ignore-pattern 'bin/**'",
53
53
  "format": "oxfmt -c kit/.oxfmtrc.json kit src",
@@ -63,7 +63,7 @@
63
63
  "agents:sync": "node scripts/agent-sync.mjs",
64
64
  "md:wrap": "node kit/scripts/md-wrap.mjs",
65
65
  "test:hooks": "node --test '.githooks/*.test.mjs'",
66
- "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm test && pnpm check:watch-build && pnpm check:asks && pnpm check:agents && pnpm check:agent-sync && pnpm test:agent-hooks && pnpm check:parity && node --check scripts/chromium-keychain-check.mjs && node --test test/tooling/chrome-keychain.test.mjs test/tooling/worktree-guard.test.mjs",
66
+ "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm test && pnpm check:watch-build && pnpm check:asks && pnpm check:agents && pnpm check:agent-sync && pnpm test:agent-hooks && pnpm check:parity && node --check scripts/chromium-keychain-check.mjs && node --test test/tooling/chrome-keychain.test.mjs test/tooling/worktree-guard.test.mjs test/tooling/disk-land.test.mjs test/tooling/lane-live.test.mjs test/tooling/keep-copy.test.mjs test/tooling/leftovers-report.test.mjs test/tooling/reap-report.test.mjs",
67
67
  "check:watch-build": "node src/sharddev/watch/parity.mjs --check",
68
68
  "typecheck:kit": "tsc -p src/tsconfig.json && tsc -p src/web/tsconfig.json",
69
69
  "typecheck:author": "tsc -p tsconfig.author.json",
@@ -71,7 +71,8 @@
71
71
  "test:kit": "node --test 'src/cli/**/*.test.ts' 'src/server/*.test.ts' 'src/test/**/*.test.ts'",
72
72
  "test:author": "vitest run",
73
73
  "build:shards": "node scripts/publish-public.mjs && node bin/wildshard.mjs build-shards",
74
- "pack:shards": "node scripts/pack-all.mjs"
74
+ "pack:shards": "node scripts/pack-all.mjs",
75
+ "lint:ci21": "node scripts/ci21-sdk-tail-lint.mjs"
75
76
  },
76
77
  "dependencies": {
77
78
  "@dimforge/rapier3d-simd": "0.21.0",
@@ -84,8 +85,8 @@
84
85
  "@types/three": "0.186.0",
85
86
  "@typescript/typescript6": "6.0.2",
86
87
  "@valibot/to-json-schema": "1.8.0",
87
- "@wildshard/engine": "0.1.21",
88
- "@wildshard/format": "npm:@wildshard/shard-format@0.5.7",
88
+ "@wildshard/engine": "0.1.24",
89
+ "@wildshard/format": "npm:@wildshard/shard-format@0.7.0",
89
90
  "ajv": "6.15.0",
90
91
  "assemblyscript": "0.28.20",
91
92
  "binaryen": "132.0.0",
@@ -185,7 +186,6 @@
185
186
  "@typescript/typescript-freebsd-arm64",
186
187
  "@typescript/typescript-freebsd-x64",
187
188
  "@typescript/typescript-linux-arm",
188
- "@typescript/typescript-linux-arm64",
189
189
  "@typescript/typescript-linux-loong64",
190
190
  "@typescript/typescript-linux-mips64el",
191
191
  "@typescript/typescript-linux-ppc64",
@@ -202,7 +202,7 @@
202
202
  "overrides": {
203
203
  "binaryen": "npm:@pre-bundled/binaryen@132.0.0-patch-1",
204
204
  "assemblyscript>binaryen": "npm:@pre-bundled/binaryen@131.0.0-nightly.20260721-patch-1",
205
- "@wildshard/format": "npm:@wildshard/shard-format@0.5.7"
205
+ "@wildshard/format": "npm:@wildshard/shard-format@0.7.0"
206
206
  }
207
207
  },
208
208
  "exports": {
@@ -310,6 +310,7 @@
310
310
  "./scene/lower": "./src/sharddev/scene/lower.ts",
311
311
  "./scene/description": "./src/sharddev/scene/description.ts",
312
312
  "./scene/shardfile": "./src/sharddev/scene/shardfile.ts",
313
+ "./scene/creature": "./src/sharddev/scene/creature.ts",
313
314
  "./watch/watch": "./src/sharddev/watch/watch.ts",
314
315
  "./watch/protocol": "./src/sharddev/watch/protocol.ts",
315
316
  "./watch/page": "./src/sharddev/watch/page.ts",
@@ -10,6 +10,10 @@
10
10
  // ({ pos: [x,y,z], look: [x,y,z], fov, center }, engine scripts/hero-shots.mjs's view shape) when the shard declares
11
11
  // one, else the player's own spawn view. Sizes: thumb 640x360, portrait 804x1626, landscape 1600x900.
12
12
  //
13
+ // A scene shard (a `shard.config.ts` and no manifest.json, meta NEW-SHARD-E2E F28) wears a generated card: its hero goes
14
+ // to `card/<slot>.jpg`, which its generated discovery card names from the next build on. Every refusal is one line with a
15
+ // rule id (`[hero-<rule>] ...`), never a stack.
16
+ //
13
17
  // `wildshard hero <shard-dir> --stamp-existing` captures nothing: it stamps the hero files already there as showing
14
18
  // the content now. It exists for a shard repo that gains this check with curated heroes and no stamp. WARNING: use it
15
19
  // only when those images match the current content; a wrong stamp hides a stale hero until the next content change.
@@ -34,11 +38,24 @@ function jpegSize(bytes) {
34
38
  throw new Error('No JPEG frame header');
35
39
  }
36
40
 
41
+ /** A refusal the CLI prints as one line, `[hero-<rule>] <message>`, never a stack. */
42
+ export class HeroRefusal extends Error {
43
+ constructor(rule, message) { super(`[hero-${rule}] ${message}`); this.name = 'HeroRefusal'; this.rule = rule; }
44
+ }
45
+
46
+ /** The shard's manifest, or null for a scene shard (its discovery is generated; F28). */
47
+ function manifestOf(shard) {
48
+ const file = join(shard, 'manifest.json');
49
+ return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null;
50
+ }
51
+
37
52
  /** The name SHARD SELECT shows this shard under: its built product's, else the manifest's. */
38
53
  export function servedName(shard) {
39
54
  const product = resolve(shardRepoRoot(shard), 'out', shardFolderName(shard), 'shard.json');
40
55
  if (existsSync(product)) return JSON.parse(readFileSync(product, 'utf8')).identity.name;
41
- return String(JSON.parse(readFileSync(join(shard, 'manifest.json'), 'utf8')).name);
56
+ const manifest = manifestOf(shard);
57
+ if (manifest === null) throw new HeroRefusal('no-name', `${shard} is a scene shard with no built product, so its SHARD SELECT name is unknown; capture from \`wildshard dev .\` (pass the URL it prints as --base), or build it first`);
58
+ return String(manifest.name);
42
59
  }
43
60
 
44
61
  /** The served root, so the URL `wildshard dev` prints (`…/?skipintro`) works as `--base` as well as a bare origin. */
@@ -58,8 +75,10 @@ async function isDevServer(base) {
58
75
 
59
76
  /** Enter the shard the way a player does: SHARD SELECT, its card, ENTER WORLD (hidden shards are Developer cards).
60
77
  * A `wildshard dev` page serves this shard alone and enters it by `?skipintro`; its SHARD SELECT lists engine's. */
61
- async function enter(page, base, name, log) {
78
+ async function enter(page, base, named, log) {
62
79
  const dev = await isDevServer(base);
80
+ // a dev page serves this shard alone: no card to pick, so no name is needed (a scene shard may have none yet)
81
+ const name = dev ? '' : named();
63
82
  const url = `${base.replace(/\/+$/u, '')}/?${dev ? 'skipintro&' : ''}mute=1&sw=0&tier=desktop&nolock=1&perf=0`;
64
83
  log(dev ? `hero: loading ${url} (wildshard dev)` : `hero: loading ${url}, card "${name}"`);
65
84
  await page.goto(url, { waitUntil: 'load' });
@@ -74,17 +93,17 @@ async function selectCard(page, base, name) {
74
93
  await page.locator('.ws-menu-card').first().waitFor({ timeout: 60000 });
75
94
  const names = await page.evaluate(() => [...document.querySelectorAll('.ws-menu-card')].map(card => card.querySelector('b')?.textContent?.trim() ?? ''));
76
95
  const at = names.indexOf(name);
77
- if (at < 0) throw new Error(`no SHARD SELECT card named "${name}" on ${base} (cards: ${names.join(', ')}); serve a build that carries this candidate`);
96
+ if (at < 0) throw new HeroRefusal('no-card', `no SHARD SELECT card named "${name}" on ${base} (cards: ${names.join(', ')}); serve a build that carries this candidate`);
78
97
  await page.evaluate(index => document.querySelector(`.ws-menu-dots i[data-i="${index}"]`)?.click(), at);
79
98
  await sleep(1000);
80
99
  await page.locator('.ws-menu-play').click();
81
100
  }
82
101
 
83
- export async function captureHero(shard, given, { name = servedName(shard), log = console.info } = {}) {
102
+ export async function captureHero(shard, given, { name, log = console.info } = {}) {
84
103
  // A curated card (hero.json "curated": true) is hand-picked art: a capture would put the spawn view over it.
85
104
  const stampPath = join(shard, 'hero.json');
86
105
  if (existsSync(stampPath) && JSON.parse(readFileSync(stampPath, 'utf8')).curated === true) {
87
- throw new Error(`${stampPath}: this hero is curated ("curated": true), hand-picked art that is never recaptured; re-stamp it for new content with \`wildshard hero <source> --stamp-existing\`, or remove "curated" to capture this view`);
106
+ throw new HeroRefusal('curated', `${stampPath}: this hero is curated ("curated": true), hand-picked art that is never recaptured; re-stamp it for new content with \`wildshard hero <source> --stamp-existing\`, or remove "curated" to capture this view`);
88
107
  }
89
108
  const base = servedRoot(given);
90
109
  // Loaded here, so --stamp-existing needs no browser or engine to resolve.
@@ -92,10 +111,11 @@ export async function captureHero(shard, given, { name = servedName(shard), log
92
111
  import('playwright'), import('@wildshard/engine/scripts/debug-settings.mjs'), import('./chromium-keychain.mjs')]);
93
112
  // A `data:` slot (new's generated card) is captured to card/<slot>.jpg and named in both card files after; any other
94
113
  // slot must already name a file in the shard folder.
95
- const files = { ...(await heroSlotFiles(shard)) }, card = JSON.parse(readFileSync(join(shard, 'manifest.json'), 'utf8')).card ?? {};
96
- const missing = Object.keys(VIEWS).filter(slot => files[slot] === undefined && String(card[slot]).startsWith('data:'));
114
+ // F28: a scene shard (no manifest) wears a generated card, so every slot it has not captured yet is a new card/<slot>.jpg
115
+ const manifest = manifestOf(shard), files = { ...(await heroSlotFiles(shard)) }, card = manifest?.card ?? {};
116
+ const missing = Object.keys(VIEWS).filter(slot => files[slot] === undefined && (manifest === null || String(card[slot]).startsWith('data:')));
97
117
  const unnamed = Object.keys(VIEWS).filter(slot => files[slot] === undefined && !missing.includes(slot));
98
- if (unnamed.length > 0) throw new Error(`${join(shard, 'manifest.json')}: card.${unnamed.join(', card.')} must name a file in the shard folder (e.g. card/${unnamed[0]}.jpg)`);
118
+ if (unnamed.length > 0) throw new HeroRefusal('card-file', `${join(shard, 'manifest.json')}: card.${unnamed.join(', card.')} must name a file in the shard folder (e.g. card/${unnamed[0]}.jpg)`);
99
119
  for (const slot of missing) files[slot] = join(shard, 'card', `${slot}.jpg`);
100
120
  const stampFile = join(shard, 'hero.json');
101
121
  const camera = existsSync(stampFile) ? JSON.parse(readFileSync(stampFile, 'utf8')).camera : undefined;
@@ -108,7 +128,7 @@ export async function captureHero(shard, given, { name = servedName(shard), log
108
128
  await saveFixture(context, NAME_ASKED);
109
129
  const page = await context.newPage();
110
130
  page.on('pageerror', error => errors.push(error.message.slice(0, 200)));
111
- await enter(page, base, name, log);
131
+ await enter(page, base, () => name ?? servedName(shard), log);
112
132
  await page.evaluate(view => {
113
133
  const world = window.__wildshard.world, cam = world.game.camera;
114
134
  try { world.animals.calm = true; } catch { /* a shard without animals */ }
@@ -135,12 +155,12 @@ export async function captureHero(shard, given, { name = servedName(shard), log
135
155
  await sleep(3000);
136
156
  shots[slot] = await page.screenshot({ type: 'jpeg', quality: QUALITY });
137
157
  const [width, height] = jpegSize(shots[slot]);
138
- if (width !== viewport.width * SCALE || height !== viewport.height * SCALE) throw new Error(`${slot} came out ${width}x${height}`);
158
+ if (width !== viewport.width * SCALE || height !== viewport.height * SCALE) throw new HeroRefusal('size', `${slot} came out ${width}x${height}`);
139
159
  log(`hero: ${slot} ${width}x${height}`);
140
160
  }
141
161
  await context.close();
142
162
  } finally { await browser.close(); }
143
- if (errors.length > 0) throw new Error(`page errors during capture, nothing written: ${errors.slice(0, 3).join(' | ')}`);
163
+ if (errors.length > 0) throw new HeroRefusal('page-error', `page errors during capture, nothing written: ${errors.slice(0, 3).join(' | ')}`);
144
164
  // Write every file, then the stamp, so a failed capture leaves the old hero and its old stamp.
145
165
  if (missing.length > 0) mkdirSync(join(shard, 'card'), { recursive: true });
146
166
  for (const [slot, bytes] of Object.entries(shots)) {
@@ -171,11 +191,21 @@ if (process.argv[1] !== undefined && resolve(process.argv[1]) === resolve(import
171
191
  console.error(' Use it ONLY when you have looked at those images and they show the current content; a wrong stamp hides a stale hero.');
172
192
  process.exit(2);
173
193
  }
174
- // SA16 (J317): a repo path names its shard source at src/ or its one src/shards/<slug>/, as the other verbs do.
175
- const shard = findShardSource(dir);
176
- if (!existsSync(join(shard, 'manifest.json'))) throw new Error(`${shard}: no manifest.json`);
177
- if (adopt) console.warn('hero: --stamp-existing: NO capture. Stamping the images already there as showing this content. Only right if they do.');
178
- const stamp = adopt ? await stampExistingHero(shard) : { written: true, ...(await captureHero(shard, base)) };
179
- const file = join(dirname(shard), basename(shard), 'hero.json');
180
- console.info(stamp.written ? `hero: stamped ${file} (content ${stamp.content.slice(0, 12)})` : `hero: ${file} is already current; nothing stamped`);
194
+ try {
195
+ // SA16 (J317): a repo path names its shard source at src/ or its one src/shards/<slug>/, as the other verbs do.
196
+ let shard;
197
+ try { shard = findShardSource(dir); } catch (error) { throw new HeroRefusal('no-source', error instanceof Error ? error.message : String(error)); }
198
+ // F28: a shard source is a manifest.json (a reference shard) or a shard.config.ts (a scene shard, generated card)
199
+ if (!existsSync(join(shard, 'manifest.json')) && !existsSync(join(shard, 'shard.config.ts'))) throw new HeroRefusal('no-source', `${shard} has neither a manifest.json nor a shard.config.ts; run it from the shard project root`);
200
+ if (adopt) console.warn('hero: --stamp-existing: NO capture. Stamping the images already there as showing this content. Only right if they do.');
201
+ const stamp = adopt ? await stampExistingHero(shard) : { written: true, ...(await captureHero(shard, base)) };
202
+ const file = join(dirname(shard), basename(shard), 'hero.json');
203
+ console.info(stamp.written ? `hero: stamped ${file} (content ${stamp.content.slice(0, 12)})` : `hero: ${file} is already current; nothing stamped`);
204
+ if (stamp.written && !existsSync(join(shard, 'manifest.json'))) console.info('hero: a scene shard\'s card is card/*.jpg; build again so its card wears the capture');
205
+ } catch (error) {
206
+ // one line, never a stack: a refusal names its rule; anything else is [hero-failed] with its message
207
+ const message = error instanceof HeroRefusal ? error.message : `[hero-failed] ${error instanceof Error ? error.message : String(error)}`;
208
+ console.error(message);
209
+ process.exitCode = 1;
210
+ }
181
211
  }
@@ -0,0 +1,95 @@
1
+ #!/usr/bin/env node
2
+ // CI21's imported tests participate in the normal typed lint and compiler gates.
3
+ import { readFileSync } from 'node:fs';
4
+ import { createHash } from 'node:crypto';
5
+ import { spawnSync } from 'node:child_process';
6
+ import ts from '@typescript/typescript6';
7
+
8
+ const manifest = JSON.parse(readFileSync(new URL('../test/ci21-sdk-tail.json', import.meta.url), 'utf8'));
9
+ const compiler = JSON.parse(readFileSync(new URL('../tsconfig.author.json', import.meta.url), 'utf8'));
10
+ const targets = manifest.files.map(file => file.targetPath);
11
+ const pending = JSON.parse(readFileSync(new URL('../test/lift-pending.json', import.meta.url), 'utf8'));
12
+ for (const target of targets) if (pending.includes(target)) throw new Error(`CI21 destination is excluded from the default suite: ${target}`);
13
+ const admitted = [...targets, ...manifest.supportPaths];
14
+ if (JSON.stringify([...compiler.files].sort()) !== JSON.stringify([...admitted].sort())) throw new Error('CI21 compiler paths differ from the recorded test/support destinations');
15
+
16
+ /** Find real test declarations, including each/template titles, without reading comments as tests. */
17
+ function testRoot(expression) {
18
+ if (ts.isIdentifier(expression)) return ['test', 'it', 'describe'].includes(expression.text) ? expression.text : null;
19
+ if (ts.isPropertyAccessExpression(expression)) {
20
+ const root = testRoot(expression.expression);
21
+ if (root !== null && expression.name.text !== 'each') throw new Error('CI21 ports must run in the default blocking suite');
22
+ return root;
23
+ }
24
+ return ts.isCallExpression(expression) ? testRoot(expression.expression) : null;
25
+ }
26
+ function titles(path) {
27
+ const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true), found = [];
28
+ const imported = new Set();
29
+ for (const statement of source.statements) if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === 'vitest') {
30
+ const bindings = statement.importClause?.namedBindings;
31
+ if (bindings !== undefined && ts.isNamedImports(bindings)) for (const element of bindings.elements) {
32
+ const original = element.propertyName?.text ?? element.name.text;
33
+ if (['test', 'it', 'describe'].includes(original)) {
34
+ if (original !== element.name.text) throw new Error(`CI21 test aliases need explicit admission: ${path}`);
35
+ imported.add(original);
36
+ }
37
+ }
38
+ }
39
+ const visit = node => {
40
+ if (ts.isVariableDeclaration(node) && node.initializer !== undefined && testRoot(node.initializer) !== null) throw new Error(`CI21 test aliases need explicit admission: ${path}`);
41
+ if (ts.isCallExpression(node) && testRoot(node.expression) !== null) {
42
+ const root = testRoot(node.expression);
43
+ if (root === 'describe' || !imported.has(root)) throw new Error(`CI21 cases must be direct named Vitest imports: ${path}`);
44
+ const title = node.arguments[0];
45
+ if (title !== undefined && (ts.isStringLiteralLike(title) || ts.isTemplateExpression(title))) {
46
+ if (![node.arguments[1], node.arguments[2]].some(body => body !== undefined && (ts.isArrowFunction(body) || ts.isFunctionExpression(body)))) throw new Error(`CI21 case has no executable body: ${path}`);
47
+ }
48
+ if (title !== undefined && ts.isStringLiteralLike(title)) found.push(title.text);
49
+ else if (title !== undefined && ts.isTemplateExpression(title)) found.push(title.getText(source));
50
+ }
51
+ ts.forEachChild(node, visit);
52
+ };
53
+ visit(source);
54
+ return found;
55
+ }
56
+ for (const file of manifest.files) {
57
+ if (file.wireSplit !== undefined && file.caseSplit === true) throw new Error(`CI21 split modes are mutually exclusive: ${file.targetPath}`);
58
+ for (const row of file.assertionCompanions ?? []) {
59
+ if (!/^[a-f0-9]{40}$/u.test(row.revision ?? '') || !/^[a-f0-9]{40}$/u.test(row.targetBlob ?? '') || row.targetPath !== file.sourcePath || !['project-wildshard/engine','project-wildshard/shard-nalati'].includes(row.repository) || !Array.isArray(row.originalTests) || row.originalTests.length === 0 || row.originalTests.some(title => !file.originalTests.includes(title))) throw new Error(`CI21 companion must pin its revision, blob and original cases: ${file.targetPath}`);
60
+ }
61
+ if (file.targetTests !== undefined) {
62
+ if (file.wireSplit !== undefined) {
63
+ const split = file.wireSplit, companions = file.wireCompanions ?? [];
64
+ const targets = file.originalTests.filter(title => title !== split.originalTest);
65
+ if (!file.originalTests.includes(split.originalTest) || JSON.stringify(targets) !== JSON.stringify(file.targetTests) || !/^[a-f0-9]{40}$/u.test(split.fixtureBlob ?? '') || !Array.isArray(split.requiredKeys) || split.requiredKeys.length === 0 || new Set(split.requiredKeys).size !== split.requiredKeys.length) throw new Error(`CI21 wire split must retain exact source cases and fixture: ${file.targetPath}`);
66
+ if (!/^test\/fixtures\/[a-z-]+\.json$/u.test(split.fixtureSourcePath ?? '')) throw new Error(`CI21 original wire fixture path differs: ${file.targetPath}`);
67
+ const fixtureBytes = readFileSync(new URL(`../${split.fixtureSourcePath}`, import.meta.url));
68
+ const fixtureBlob = createHash('sha1').update(`blob ${fixtureBytes.length}\0`).update(fixtureBytes).digest('hex');
69
+ const fixture = JSON.parse(fixtureBytes.toString('utf8'));
70
+ if (fixtureBlob !== split.fixtureBlob || !Array.isArray(fixture) || fixture.some(row => typeof row.name !== 'string' || !Number.isSafeInteger(row.bytes) || !/^[a-f0-9]{64}$/u.test(row.hash ?? '')) || JSON.stringify(fixture.map(row => row.name).sort()) !== JSON.stringify([...split.requiredKeys].sort())) throw new Error(`CI21 wire keys must match the unchanged original fixture: ${file.targetPath}`);
71
+ if (companions.length < 2 || companions.some(row => !/^project-wildshard\/shard-(?:nalati|driftwood|dunes)$/u.test(row.repository ?? '') || !/^test\/[a-z-]+\.test\.ts$/u.test(row.targetPath ?? '') || !/^[a-f0-9]{40}$/u.test(row.revision ?? '') || !/^[a-f0-9]{40}$/u.test(row.targetBlob ?? '') || row.fixtureBlob !== split.fixtureBlob || row.fixturePath !== split.fixtureSourcePath || JSON.stringify(row.originalTests) !== JSON.stringify([split.originalTest]) || !Array.isArray(row.wireKeys) || row.wireKeys.length === 0)) throw new Error(`CI21 wire split requires pinned shard cases and original fixture: ${file.targetPath}`);
72
+ const keys = companions.flatMap(row => row.wireKeys);
73
+ if (new Set(keys).size !== keys.length || JSON.stringify([...keys].sort()) !== JSON.stringify([...split.requiredKeys].sort())) throw new Error(`CI21 wire split must cover every key exactly once: ${file.targetPath}`);
74
+ process.stdout.write(`CI21 wire split: ${targets.length} SDK cases + ${companions.length} shard cases, ${keys.length} original wires (${file.targetPath})\n`);
75
+ } else if (file.caseSplit === true) {
76
+ const companions = file.assertionCompanions ?? [];
77
+ if (companions.length === 0 || companions.some(row => !/^[a-f0-9]{40}$/u.test(row.revision ?? '') || row.targetPath !== file.sourcePath || !['project-wildshard/engine','project-wildshard/shard-nalati'].includes(row.repository) || !Array.isArray(row.originalTests) || row.originalTests.length === 0)) throw new Error(`CI21 split requires pinned native companions: ${file.targetPath}`);
78
+ const covered = [...file.targetTests, ...companions.flatMap(row => row.originalTests)];
79
+ if (new Set(covered).size !== covered.length || covered.length !== file.originalTests.length || covered.some(title => !file.originalTests.includes(title))) throw new Error(`CI21 split must partition every original case exactly once: ${file.targetPath}`);
80
+ process.stdout.write(`CI21 split: ${file.targetTests.length} SDK + ${covered.length - file.targetTests.length} owner declarations (${file.targetPath})\n`);
81
+ } else if (file.targetTests.length !== file.originalTests.length) throw new Error(`CI21 renamed case count differs: ${file.targetPath}`);
82
+ for (const [index, title] of file.targetTests.entries()) if (file.caseSplit !== true && file.wireSplit === undefined && title !== file.originalTests[index]) process.stdout.write(`CI21 rename: ${file.originalTests[index]} -> ${title} (${file.targetPath})\n`);
83
+ }
84
+ if (JSON.stringify(titles(file.targetPath)) !== JSON.stringify(file.targetTests ?? file.originalTests)) throw new Error(`CI21 test declarations differ from their source record: ${file.targetPath}`);
85
+ }
86
+ const selected = process.argv.slice(2);
87
+ if (selected.some(file => !admitted.includes(file))) throw new Error('CI21 lint accepts only recorded test/support paths');
88
+ const paths = selected.length === 0 ? admitted : selected;
89
+ process.stdout.write(`CI21 typed lint: ${targets.length} recorded tests, ${manifest.supportPaths.length} support files; linting ${paths.length} paths\n`);
90
+ // Explicit admission includes only the recorded boundary helpers, alongside the port tests.
91
+ const run = spawnSync('node_modules/.bin/oxlint', ['--type-aware', '--tsconfig', 'tsconfig.author.json', '-c', '.oxlintrc.author.json', '--deny-warnings', ...paths], {
92
+ stdio: 'inherit', env: { ...process.env, WILDSHARD_RATCHET_FILE: 'lint/ratchet.json' },
93
+ });
94
+ if (run.error !== undefined) throw run.error;
95
+ process.exitCode = run.status ?? 1;