@wildshard/sdk 0.2.7 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/GUIDE.md CHANGED
@@ -40,7 +40,7 @@ repo's one `src/shards/<slug>/`).
40
40
  | 2 | Walk it | `wildshard dev .` | Works. The first run fetches engine's dev client once. See "Walking your shard" below |
41
41
  | 3 | Check | `wildshard check .` | Works: lint, build, validate, prove and the report card, one verdict |
42
42
  | 4 | Hero | `wildshard hero . --base <url>` | Works, with `wildshard dev .` running: `<url>` is the one it prints. See "The hero" below |
43
- | 5 | Prepare | `wildshard prepare public/shardfiles/my-shard --base <url>`, then `wildshard build public/shardfiles/my-shard` | Works only with an engine checkout. See "Uploading" below |
43
+ | 5 | Prepare | `wildshard prepare public/shardfiles/my-shard`, then `wildshard build public/shardfiles/my-shard` | The first run fetches engine's preparation client once. See "Uploading" below |
44
44
  | 6 | Upload to staging | `wildshard upload public/shardfiles/my-shard.shardfile --channel staging --version 0.0.1` | Works only for the Wildshard team today: it needs the team's creator key. See "Uploading" below |
45
45
  | 7 | Upload to production | the same with `--channel prod` and a higher version | The same. Try staging first |
46
46
  | 8 | Share | `https://staging.wildshard.io/slug/my-shard` | **Not built yet (SA36, SA37).** See section 5 |
@@ -64,7 +64,7 @@ with `rule`, `fix` and `guide`) for agents and scripts.
64
64
  | `wildshard whoami` | Say which account key upload would send (from `WILDSHARD_API_KEY` or the key file), show its first characters, and print its account's email and how many slugs it owns (`--server` or `WILDSHARD_API_URL`) |
65
65
  | `wildshard delete <slug> [--yes]` | Delete your shard from the catalogue, every channel and the grid, after you type its slug (see "Deleting a shard") |
66
66
  | `wildshard build <source>` | Build alone: bake the shard source into `public/shardfiles/<slug>/` and write `public/shardfiles/<slug>.shardfile`. `wildshard build <folder>` writes the shard file of a built folder (after `prepare`) |
67
- | `wildshard prepare <folder> --base <url>` | Record the built folder in phone WebKit against an exact engine preview, which turns a draft into the uploadable form (see "Uploading") |
67
+ | `wildshard prepare <folder> [--base <url>]` | Record the built folder in phone WebKit against engine's preparation client (or the exact engine preview `--base` names), which turns a draft into the uploadable form (see "Uploading") |
68
68
  | `wildshard validate <source \| folder>` | Shard-format's checks and the headless budget run, alone |
69
69
  | `wildshard prove <source> <proof.json>` | Play a proof tape headlessly and print what happened |
70
70
  | `wildshard synth <source>` | Run `shard.config.ts`'s scene exports and write the scene as data |
@@ -116,11 +116,11 @@ before every upload:
116
116
  Every time: commit everything, the hero included. Done when `git status` is clean.
117
117
  3. **Check.** `wildshard check .` builds the shard file. It is a **draft** (`sdk: "0.2"`): check prints a
118
118
  `shardfile-draft` warning, and upload and the API refuse a draft. Done at `check pass`.
119
- 4. **Prepare.** `wildshard prepare public/shardfiles/<slug> --base <url>`, with the URL of an exact engine preview made
120
- for preparation, turns the draft into the uploadable form (`sdk: "0.3"`). Then `wildshard build
121
- public/shardfiles/<slug>` writes the prepared shard file. That preview comes from an engine checkout today, so an
122
- author outside the Wildshard team cannot prepare yet: the steps are not written down for authors (HOW-WE-BUILD F5);
123
- ask the Wildshard team.
119
+ 4. **Prepare.** `wildshard prepare public/shardfiles/<slug>` records the draft in phone WebKit and turns it into the
120
+ uploadable form (`sdk: "0.3"`). It serves engine's preparation client around the draft itself, fetched once from
121
+ engine's release at the SDK's engine pin (about 310 MB, kept in `~/.cache/wildshard/dev-client`), so no engine
122
+ checkout is needed. Then `wildshard build public/shardfiles/<slug>` writes the prepared shard file. Done when
123
+ prepare prints `{"slug":…,"programs":…}` and build prints the shard file line.
124
124
  5. **Keys.** Set `WILDSHARD_API_URL=https://api.wildshard.io` (or pass `--server`) and
125
125
  `WILDSHARD_CREATOR_PRIVATE_KEY`, the base64 creator key upload signs with. There is one Wildshard creator key and
126
126
  no per-author creator keys yet: ask the Wildshard team for it, and never commit it. Upload also sends your
@@ -6,9 +6,9 @@
6
6
  // SHARD-AUTHORING SA38 (J319): generators are arbitrary Node code, so in `generators/` the rule is a denylist of
7
7
  // Wildshard cheats (the engine, sdk paths outside its exports, another shard's source, a second three); any npm
8
8
  // package, valibot and node:* pass. data/, quests/ and shard.config.ts keep the authoring allowlist, minus the engine.
9
- import { readFileSync } from 'node:fs';
9
+ import { existsSync, readFileSync } from 'node:fs';
10
10
  import { isBuiltin } from 'node:module';
11
- import { dirname, isAbsolute, resolve } from 'node:path';
11
+ import { basename, dirname, isAbsolute, resolve } from 'node:path';
12
12
  import { fileURLToPath, pathToFileURL } from 'node:url';
13
13
 
14
14
  const RULE = 'generator-imports';
@@ -77,10 +77,22 @@ const nodePath = (filename, source) => {
77
77
  } catch { return null; }
78
78
  };
79
79
 
80
+ /**
81
+ * The shard source a file sits in, as [whole, slug-or-src, path within the shard], or null outside one. The nearest
82
+ * src/shards/<slug>/ above the file names the shard, so a checkout under some other src/shards/ still matches. SA44: a
83
+ * single-shard repo keeps its source at src/ (J317), marked by `src/shard.config.ts`; whichever is nearer wins.
84
+ */
85
+ const shardFile = (path) => {
86
+ for (let at = dirname(path); dirname(at) !== at; at = dirname(at)) {
87
+ const nested = basename(dirname(at)) === 'shards' && basename(dirname(dirname(at))) === 'src';
88
+ if (nested || (basename(at) === 'src' && existsSync(resolve(at, 'shard.config.ts')))) return [path, nested ? basename(at) : 'src', path.slice(at.length + 1)];
89
+ }
90
+ return null;
91
+ };
92
+
80
93
  /** Why `source` may not be imported from `filename` under a shard's author folders, or null when it may. */
81
94
  export function generatorImportViolation(filename, rawSource, required = false) {
82
- // The last src/shards/ in the path names the shard, so a checkout under some other src/shards/ still matches.
83
- const path = resolve(filename).replaceAll('\\', '/'), match = /^.*\/src\/shards\/([^/]+)\/(.+)$/u.exec(path);
95
+ const path = resolve(filename).replaceAll('\\', '/'), match = shardFile(path);
84
96
  if (match === null || !(/^(?:generators|data|quests)\//u.test(match[2]) || match[2] === 'shard.config.ts')) return null;
85
97
  if (typeof rawSource !== 'string') return null;
86
98
  // Vite resolves the path before the first `?` or `#` through the package exports and keeps the rest (`?raw`, `?url`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.2.7",
3
+ "version": "0.2.8",
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": {
@@ -2,9 +2,10 @@
2
2
  // G508: normal generation job; reads only declared JSON, terrain and GLB data.
3
3
  import { createRequire } from 'node:module';
4
4
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
5
- import { dirname, resolve, sep } from 'node:path';
5
+ import { dirname, relative, resolve, sep } from 'node:path';
6
6
  import { pathToFileURL } from 'node:url';
7
7
  import { MapRaster } from '../src/sharddev/bake/mapRaster.ts';
8
+ import { isRepoSource, shardFolderName } from '../src/sharddev/shardSource.ts';
8
9
  import { readMapGeometry, stylizeMap } from '@wildshard/engine/scripts/map-painter.mjs';
9
10
  import { MAP_METRES, mapPixelHash, mapSettingsPath, mapStampPath, mapShards, mapTilesHash } from '@wildshard/engine/scripts/map-hash.mjs';
10
11
 
@@ -19,7 +20,10 @@ export async function rasterDataMap(settings, data, { output, glbs, label = 'map
19
20
  const raster = new MapRaster(1000, settings, readMapGeometry);
20
21
  const { paintMapGeometry } = await import('../src/sharddev/bake/mapScenes.ts');
21
22
  const source = data.input;
22
- await paintMapGeometry(raster, settings, { input: source, model: url => source(`../../../public${url}`), json: data.json, bytes: data.bytes }, { output, glbs, label });
23
+ // A model URL is a file under the repo's public/. SA44: a caller that knows the shard's place passes `model`; the
24
+ // default is `src/shards/<slug>/`'s, three folders below the repo root.
25
+ const model = data.model ?? (url => source(`../../../public${url}`));
26
+ await paintMapGeometry(raster, settings, { input: source, model, json: data.json, bytes: data.bytes }, { output, glbs, label });
23
27
  const own = output === undefined ? undefined : settings.outputs?.[output];
24
28
  const style = own?.style ?? settings.style;
25
29
  const pixels = stylizeMap(raster, style);
@@ -35,7 +39,9 @@ export async function rasterDataMap(settings, data, { output, glbs, label = 'map
35
39
  /** Every repository file by its path, as a shard's pure map producer reads its inputs. @param {string} root */
36
40
  export const repoSource = root => path => new Uint8Array(readFileSync(resolve(root, path)));
37
41
  export async function paintDataMap(root, slug, { output, glbs, sources } = {}) {
38
- const dir = resolve(root, 'src/shards', slug), settings = json(mapSettingsPath(dir));
42
+ // SA44: a single-shard repo keeps its source at src/, one folder below the root, not src/shards/<slug>/.
43
+ const single = resolve(root, 'src'), dir = isRepoSource(single) && shardFolderName(single) === slug ? single : resolve(root, 'src/shards', slug);
44
+ const settings = json(mapSettingsPath(dir)), toPublic = relative(dir, resolve(root, 'public')).split(sep).join('/');
39
45
  const tilesHash = mapTilesHash(dir);
40
46
  const declared = settings.inputs.map(file => resolve(dir, file));
41
47
  const input = file => {
@@ -46,7 +52,7 @@ export async function paintDataMap(root, slug, { output, glbs, sources } = {}) {
46
52
  const source = file => sources?.get(file) ?? input(file);
47
53
  const readBytes = file => { const value = source(file); return value instanceof Uint8Array ? value : readFileSync(value); };
48
54
  const rows = file => JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(readBytes(file)));
49
- const { raster, pixels } = await rasterDataMap(settings, { input: source, json: rows, bytes: readBytes }, { output, glbs, label: slug });
55
+ const { raster, pixels } = await rasterDataMap(settings, { input: source, model: url => source(`${toPublic}${url}`), json: rows, bytes: readBytes }, { output, glbs, label: slug });
50
56
  const own = output === undefined ? undefined : settings.outputs?.[output], style = own?.style ?? settings.style, painter = settings.painter;
51
57
  const product = output ?? slug, image = resolve(root, 'public/assets', product, 'map/top.webp');
52
58
  mkdirSync(dirname(image), { recursive: true });
@@ -5,6 +5,9 @@
5
5
  // Shaders step asks for it. A stale list costs only wasted links: re-bake after a shader or material change.
6
6
  // node scripts/bake-entry-programs.mjs --base <served build URL> [--check] <slug>...
7
7
  // --check: write nothing; print how many of the build's entry programs the committed list already holds.
8
+ // --inline (SA43): the page carries the candidate inline (`wildshard prepare`'s own preview of engine's preparation
9
+ // client); it enters at `?skipintro` as `wildshard dev` does, with the page's service worker off (`sw=0`), so every read
10
+ // reaches the recorder from the network.
8
11
  // Run through scripts/browser-lane.sh.
9
12
  import {webkit,devices} from 'playwright';
10
13
  import {existsSync,readFileSync,writeFileSync} from 'node:fs';
@@ -14,7 +17,7 @@ import {loadingCardIndex} from '@wildshard/engine/scripts/loading-benchmark/cata
14
17
  import {preparationSaveSeed} from './preparation-seed.mjs';
15
18
 
16
19
  const args=process.argv.slice(2), flag=name=>{const at=args.indexOf(name);if(at===-1)return null;const [value]=args.splice(at,2).slice(1);return value;};
17
- const base=flag('--base'), output=flag('--out'), wantedHeader=flag('--header'), title=flag('--title'), check=args.includes('--check'), slugs=args.filter(arg=>!arg.startsWith('--'));
20
+ const base=flag('--base'), output=flag('--out'), wantedHeader=flag('--header'), title=flag('--title'), check=args.includes('--check'), inline=args.includes('--inline'), slugs=args.filter(arg=>!arg.startsWith('--'));
18
21
  if(base===null||slugs.length===0)throw new Error('usage: bake-entry-programs.mjs --base <url> [--check] <slug>...');
19
22
 
20
23
  /** Every program linked between the tap and control, in link order (the page's own WebGL2 calls, read in place). */
@@ -58,26 +61,31 @@ async function record(browser,slug){
58
61
  for(const file of manifest.files??[])if(typeof file.hash==='string')hashes.add(file.hash);
59
62
  }));
60
63
  });
61
- await page.goto(base,{waitUntil:'load'});
62
- await page.locator('.ws-main-select').click();
63
- const names=await page.locator('.ws-menu-card b').allTextContents();
64
- const matches=title===null?[]:names.flatMap((name,index)=>name.toLowerCase().includes(title.toLowerCase())?[index]:[]);
65
- if(matches.length>1)throw new Error(`Candidate card ambiguous: ${title}`);
66
- if(title!==null&&matches.length===0){
67
- // Grid-only products have no standalone picker card. Exercise the
68
- // existing one-shot arrival contract, as the full-catalogue boot proof.
69
- await context.addInitScript(({epoch,slug,title})=>{
70
- if(new URL(location.href).searchParams.get('chunk')!==slug)return;
71
- const prefix=epoch===0?'wildshard.save.v2.':`wildshard.save.v2@${epoch}.`;
72
- const data=JSON.stringify({slug,name:title,mode:'enter',at:Date.now()});
73
- sessionStorage.setItem(`${prefix}session`,JSON.stringify({keys:{titleArrival:{v:1,data},'travel.handoff':{v:1,data:{v:1,from:null,to:slug,mode:'enter',arrive:null,carry:[],at:Date.now()}}}}));
74
- },{epoch,slug,title});
75
- const arrival=new URL(base);arrival.searchParams.set('chunk',slug);
76
- await page.goto(arrival.href,{waitUntil:'load'});
64
+ if(inline){
65
+ const entry=new URL(base);entry.searchParams.set('skipintro','');entry.searchParams.set('sw','0');
66
+ await page.goto(entry.href,{waitUntil:'load'});
77
67
  }else{
78
- await page.locator(`.ws-menu-dots i[data-i="${title===null?loadingCardIndex(names,slug):matches[0]}"]`).click();
79
- // ENTER WORLD opens a fresh document and a fresh measured link list.
80
- await page.locator('.ws-menu-play').click();
68
+ await page.goto(base,{waitUntil:'load'});
69
+ await page.locator('.ws-main-select').click();
70
+ const names=await page.locator('.ws-menu-card b').allTextContents();
71
+ const matches=title===null?[]:names.flatMap((name,index)=>name.toLowerCase().includes(title.toLowerCase())?[index]:[]);
72
+ if(matches.length>1)throw new Error(`Candidate card ambiguous: ${title}`);
73
+ if(title!==null&&matches.length===0){
74
+ // Grid-only products have no standalone picker card. Exercise the
75
+ // existing one-shot arrival contract, as the full-catalogue boot proof.
76
+ await context.addInitScript(({epoch,slug,title})=>{
77
+ if(new URL(location.href).searchParams.get('chunk')!==slug)return;
78
+ const prefix=epoch===0?'wildshard.save.v2.':`wildshard.save.v2@${epoch}.`;
79
+ const data=JSON.stringify({slug,name:title,mode:'enter',at:Date.now()});
80
+ sessionStorage.setItem(`${prefix}session`,JSON.stringify({keys:{titleArrival:{v:1,data},'travel.handoff':{v:1,data:{v:1,from:null,to:slug,mode:'enter',arrive:null,carry:[],at:Date.now()}}}}));
81
+ },{epoch,slug,title});
82
+ const arrival=new URL(base);arrival.searchParams.set('chunk',slug);
83
+ await page.goto(arrival.href,{waitUntil:'load'});
84
+ }else{
85
+ await page.locator(`.ws-menu-dots i[data-i="${title===null?loadingCardIndex(names,slug):matches[0]}"]`).click();
86
+ // ENTER WORLD opens a fresh document and a fresh measured link list.
87
+ await page.locator('.ws-menu-play').click();
88
+ }
81
89
  }
82
90
  await page.waitForFunction(()=>window.__wildshard?.world?.hud?.entered===true&&!document.querySelector('.ws-load'),undefined,{timeout:240000});
83
91
  const version=await(await page.request.get(new URL('/version.json',base).href)).json();
@@ -17,7 +17,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
17
17
  import { basename, dirname, join, resolve } from 'node:path';
18
18
  import { heroSlotFiles, writeHeroStamp } from '../src/cli/hero/stamp.ts';
19
19
  import { stampExistingHero } from '../src/cli/hero/adopt.ts';
20
- import { findShardSource, shardFolderName } from '../src/sharddev/shardSource.ts';
20
+ import { findShardSource, shardFolderName, shardRepoRoot } from '../src/sharddev/shardSource.ts';
21
21
 
22
22
  const SCALE = 2;
23
23
  const VIEWS = { portrait: { width: 402, height: 813 }, landscape: { width: 800, height: 450 }, thumb: { width: 320, height: 180 } };
@@ -35,8 +35,8 @@ function jpegSize(bytes) {
35
35
  }
36
36
 
37
37
  /** The name SHARD SELECT shows this shard under: its built product's, else the manifest's. */
38
- function servedName(shard) {
39
- const product = resolve(shard, '../../../out', basename(shard), 'shard.json');
38
+ export function servedName(shard) {
39
+ const product = resolve(shardRepoRoot(shard), 'out', shardFolderName(shard), 'shard.json');
40
40
  if (existsSync(product)) return JSON.parse(readFileSync(product, 'utf8')).identity.name;
41
41
  return String(JSON.parse(readFileSync(join(shard, 'manifest.json'), 'utf8')).name);
42
42
  }
@@ -1,4 +1,6 @@
1
1
  // Conservative source guard for Chromium launchers, without a parser dependency.
2
+ import { KEYCHAIN_ARGS } from './chromium-keychain.mjs';
3
+
2
4
  const childMethods = ['spawn', 'spawnSync', 'execFile', 'execFileSync', 'exec', 'execSync'];
3
5
  const browserBinary = /chrom(?:e|ium)|executablePath\s*\(/iu;
4
6
 
@@ -11,7 +13,7 @@ function shellProblems(/** @type {string} */ text) {
11
13
  if (!command || command[1].startsWith('#') || command[1].includes('=')) return [];
12
14
  const program = command[1].replace(/\$\{?(\w+)\}?/gu, (_all, name) => variables.get(name) ?? name);
13
15
  if (!browserBinary.test(program)) return [];
14
- return ['--use-mock-keychain', '--password-store=basic'].every(flag => command[2].includes(flag)) ? [] : ['bare Chromium shell executable'];
16
+ return KEYCHAIN_ARGS.every(flag => command[2].includes(flag)) ? [] : ['bare Chromium shell executable'];
15
17
  });
16
18
  }
17
19
 
@@ -95,7 +97,7 @@ export function keychainProblems(/** @type {string} */ text) {
95
97
  return value;
96
98
  };
97
99
  const safe = (/** @type {string} */ value) => /\.\.\.\s*KEYCHAIN_ARGS\b/u.test(expand(value))
98
- || ['--use-mock-keychain', '--password-store=basic'].every(flag => expand(value).includes(flag));
100
+ || KEYCHAIN_ARGS.every(flag => expand(value).includes(flag));
99
101
  const names = [...childMethods];
100
102
  const namespaces = new Set([...text.matchAll(/import\s+\*\s+as\s+(\w+)\s+from\s+['"](?:node:)?child_process['"]/gu)].map(match => match[1]));
101
103
  for (const match of text.matchAll(/import\s+(\w+)\s+from\s+['"](?:node:)?child_process['"]/gu)) namespaces.add(match[1]);
@@ -2,4 +2,6 @@
2
2
  // keychain for "Chrome for Testing Safe Storage" and a dialog lands on the desktop at each launch. Playwright adds them
3
3
  // by default, but a raw `spawn` of the executable skips its defaults, so every launch site spreads them explicitly and
4
4
  // test/tooling/chrome-keychain.test.mjs refuses a launch file that does not.
5
- export const KEYCHAIN_ARGS = Object.freeze(['--use-mock-keychain', '--password-store=basic']);
5
+ // `--mute-audio` rides along (Jake, 2026-11-13: "headless chromium with volume off"), so a launch that forgets it
6
+ // still cannot play a game's sound out of Jake's speakers.
7
+ export const KEYCHAIN_ARGS = Object.freeze(['--use-mock-keychain', '--password-store=basic', '--mute-audio']);
@@ -0,0 +1,45 @@
1
+ // SHARD-AUTHORING SA43: the preview `wildshard prepare <folder>` records in when no --base is given. It serves engine's
2
+ // preparation client (a WILDSHARD_PREPARATION_ONLY production build, fetched at this package's engine pin, src/sharddev/
3
+ // devClient.ts) with the candidate's shard.json inline as `ws-shardfile`, as `wildshard dev` serves the devserver client,
4
+ // and the candidate folder beside the page (as `wildshard build` lays a client over its product) and where a release
5
+ // serves a shard, `/shardfiles/<slug>/`. No engine checkout is needed.
6
+ import {createServer} from 'node:http';
7
+ import {createReadStream,existsSync,readFileSync,realpathSync,statSync} from 'node:fs';
8
+ import {extname,resolve,sep} from 'node:path';
9
+
10
+ const MIME={'.html':'text/html','.js':'text/javascript','.css':'text/css','.json':'application/json','.wasm':'application/wasm','.svg':'image/svg+xml',
11
+ '.png':'image/png','.jpg':'image/jpeg','.webp':'image/webp','.woff2':'font/woff2','.ktx2':'image/ktx2','.m4a':'audio/mp4','.ogg':'audio/ogg','.glb':'model/gltf-binary'};
12
+
13
+ /** A file under `root` for the request path `local`, or undefined (never one outside it, symlinks included). */
14
+ function inside(root,local){
15
+ const file=resolve(root,local);
16
+ if(!file.startsWith(`${root}${sep}`)||!existsSync(file)||!statSync(file).isFile())return undefined;
17
+ return realpathSync(file).startsWith(`${root}${sep}`)?file:undefined;
18
+ }
19
+
20
+ /** Serve `client` with the candidate `dir` (a built shard file folder) inline; resolves to {url, close}. */
21
+ export async function preparationPreview(client,dir,{clientPage}){
22
+ client=realpathSync(resolve(client));dir=realpathSync(resolve(dir));
23
+ const header=readFileSync(resolve(dir,'shard.json'),'utf8'),slug=JSON.parse(header).identity.slug;
24
+ // The inline descriptor is the candidate's own index bytes, `<` escaped as `wildshard build` writes it.
25
+ const recorded=existsSync(resolve(dir,'programs',`${slug}.json`));
26
+ const page=clientPage(readFileSync(resolve(client,'index.html'),'utf8'),header.trim().replaceAll('<','\\u003c'),slug,recorded);
27
+ const shardRoot=`/shardfiles/${slug}/`;
28
+ const server=createServer((request,response)=>{
29
+ response.setHeader('Cache-Control','no-store');
30
+ try{
31
+ if(request.method!=='GET'&&request.method!=='HEAD'){response.writeHead(405);response.end();return;}
32
+ const path=decodeURIComponent(new URL(request.url??'/','http://localhost').pathname);
33
+ if(path==='/'||path==='/index.html'){response.setHeader('Content-Type','text/html');response.end(request.method==='HEAD'?undefined:page);return;}
34
+ // The inline product reads beside the page, as `wildshard build` lays the client over the product folder (the
35
+ // client's file wins); the in-page server reads where a release serves the shard.
36
+ const file=path.startsWith(shardRoot)?inside(dir,path.slice(shardRoot.length)):inside(client,path.slice(1))??inside(dir,path.slice(1));
37
+ if(file===undefined){response.writeHead(404);response.end();return;}
38
+ response.setHeader('Content-Type',MIME[extname(file)]??'application/octet-stream');
39
+ if(request.method==='HEAD')response.end();else createReadStream(file).on('error',()=>{response.destroy();}).pipe(response);
40
+ }catch{response.writeHead(400);response.end();}
41
+ });
42
+ await new Promise((done,fail)=>{server.once('error',fail);server.listen(0,'127.0.0.1',()=>{done(undefined);});});
43
+ const address=server.address();if(address===null||typeof address==='string')throw new Error('No preparation preview address');
44
+ return {url:`http://127.0.0.1:${address.port}/`,slug,close:()=>new Promise(done=>{server.close(()=>{done(undefined);});server.closeAllConnections();})};
45
+ }
@@ -2,7 +2,7 @@
2
2
  // J198: prepare an already built candidate using actual phone WebKit links.
3
3
  // Draft sdk 0.2 output is not relabelled until this exact product enters.
4
4
  import {createHash} from 'node:crypto';
5
- import {spawnSync} from 'node:child_process';
5
+ import {spawn} from 'node:child_process';
6
6
  import {readFileSync,writeFileSync,mkdirSync,mkdtempSync,rmSync,readdirSync,statSync,lstatSync} from 'node:fs';
7
7
  import {tmpdir} from 'node:os';
8
8
  import {join,resolve,dirname} from 'node:path';
@@ -80,7 +80,20 @@ export async function finishPreparation(dir,recording,originalHeader){
80
80
  return {slug:index.identity.slug,fence:fence.length,programs:programs.programs.length,renderer,document:programs.build};
81
81
  }
82
82
 
83
- export async function prepareProduct(dir,base){
83
+ /** SA43: with no --base, serve engine's preparation client (fetched at this package's engine pin) around the candidate. */
84
+ async function ownPreview(dir){
85
+ const {preparationClient}=await import('../src/sharddev/devClient.ts');
86
+ const {clientPage}=await import('../src/sharddev/clientPage.ts');
87
+ const {preparationPreview}=await import('./preparation-preview.mjs');
88
+ return preparationPreview(await preparationClient(),dir,{clientPage});
89
+ }
90
+
91
+ export async function prepareProduct(dir,base,inline=false){
92
+ if(base===undefined){
93
+ const preview=await ownPreview(dir);
94
+ console.error(`wildshard prepare: serving engine's preparation client at ${preview.url}`);
95
+ try{return await prepareProduct(dir,preview.url,true);}finally{await preview.close();}
96
+ }
84
97
  const header=readFileSync(join(dir,'shard.json')),index=parseOutputIndex(JSON.parse(header));
85
98
  const scratch=mkdtempSync(join(tmpdir(),'wildshard-prepare-'));
86
99
  try{
@@ -88,7 +101,12 @@ export async function prepareProduct(dir,base){
88
101
  const script=fileURLToPath(new URL('./bake-entry-programs.mjs',import.meta.url));
89
102
  // Like the existing recorder, the operator runs this command through the
90
103
  // engine browser-lane wrapper. Do not acquire a second nested browser slot.
91
- const run=spawnSync(process.execPath,[script,'--base',base,'--out',out,'--header',hash(header),'--title',index.identity.name,index.identity.slug],{stdio:'inherit',timeout:300000});
104
+ // Not spawnSync: with no --base this process serves the preview the recorder reads (SA43).
105
+ const run=await new Promise(done=>{
106
+ const child=spawn(process.execPath,[script,'--base',base,'--out',out,'--header',hash(header),'--title',index.identity.name,...(inline?['--inline']:[]),index.identity.slug],{stdio:'inherit',timeout:300000});
107
+ child.once('error',error=>{done({error,status:null});});
108
+ child.once('exit',status=>{done({error:undefined,status});});
109
+ });
92
110
  if(run.error!==undefined||run.status!==0)throw new Error('Phone WebKit preparation did not pass; candidate left as a draft');
93
111
  return await finishPreparation(dir,json(scratch,'recording.json'),header);
94
112
  }finally{rmSync(scratch,{recursive:true,force:true});}
@@ -96,6 +114,6 @@ export async function prepareProduct(dir,base){
96
114
 
97
115
  if(process.argv[1]!==undefined&&resolve(process.argv[1])===fileURLToPath(import.meta.url)){
98
116
  const [dir,flag,base]=process.argv.slice(2);
99
- if(dir===undefined||flag!=='--base'||base===undefined)throw new Error('usage: wildshard prepare <folder> --base <exact-preview-url>');
117
+ if(dir===undefined||(flag!==undefined&&(flag!=='--base'||base===undefined)))throw new Error('usage: wildshard prepare <folder> [--base <exact-preview-url>]');
100
118
  console.log(JSON.stringify(await prepareProduct(resolve(dir),base)));
101
119
  }
package/src/cli/help.ts CHANGED
@@ -139,13 +139,15 @@ const VERBS: Readonly<Record<string, string>> = {
139
139
  Build only the shard source's native behaviour
140
140
  outputs; --check refuses stale ones and writes
141
141
  nothing`,
142
- prepare: `prepare <folder> --base <exact-preview-url>
142
+ prepare: `prepare <folder> [--base <exact-preview-url>]
143
143
  Record the shard file folder in phone WebKit against
144
- an exact engine preview and write its author
144
+ engine's preparation client and write its author
145
145
  preparation (the fence, the fence policy and the
146
146
  recorded programs): the draft becomes sdk 0.3, the
147
147
  only kind upload sends. Then write its shard file
148
- with build <folder>`,
148
+ with build <folder>. The client is fetched once from
149
+ engine's release at this package's pin; --base
150
+ records against an exact engine preview instead`,
149
151
  validate: `validate <source | folder | shard.json>
150
152
  Validate a shard source, or a built shard file
151
153
  folder with shard-format's checks, and run it
@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
3
3
  // oxlint-disable-next-line import/no-nodejs-modules -- The author build reads the shard's folder and public/.
4
4
  import { resolve } from 'node:path';
5
5
  import * as v from 'valibot';
6
+ import { shardRepoRoot } from './shardSource';
6
7
  import { AudioWaiverSchema, type AudioWaiver } from '@wildshard/format/audioWaiver';
7
8
 
8
9
  /** C0 (J137): what a product carries so it stands alone. The list is the shard's `mounts.json`, per output
@@ -32,7 +33,7 @@ export function readCookInput(project: string, slug: string): CookInput | undefi
32
33
  const json = (name: string): unknown => { const file = resolve(project, name); return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined; };
33
34
  const list = json('mounts.json'), fence = json('fence-reads.json'), packs = json('packs-set.json'), audioWaiver = readAudioWaiver(json('audio-waiver.json'), slug);
34
35
  const urls = list === undefined ? [] : v.parse(MountsSchema, list).outputs[slug] ?? [];
35
- const publicRoot = resolve(project, '../../../public');
36
+ const publicRoot = resolve(shardRepoRoot(project), 'public');
36
37
  const mounts = urls.map(url => ({url, bytes: readFileSync(resolve(publicRoot, url.slice(1)))}));
37
38
  const set = packs === undefined ? undefined : v.parse(PacksSetSchema, packs).set;
38
39
  if (mounts.length === 0 && fence === undefined && set === undefined && audioWaiver === undefined) return undefined;
@@ -13,6 +13,9 @@ import { join, resolve } from 'node:path';
13
13
 
14
14
  /** The release asset engine's `scripts/devserver-client.mjs` writes. */
15
15
  export const DEV_CLIENT_ASSET = 'devserver-client.tar.gz';
16
+ /** SA43: the preparation client, `scripts/devserver-client.mjs --kind preparation`: engine's production build made with
17
+ * `WILDSHARD_PREPARATION_ONLY=1`, which `wildshard prepare` serves with the author's draft inline. */
18
+ export const PREPARATION_CLIENT_ASSET = 'preparation-client.tar.gz';
16
19
  const RELEASES = 'https://github.com/project-wildshard/engine/releases/download';
17
20
 
18
21
  /** The engine release that holds the client for this package's engine pin: a commit pin (a green main build) is its
@@ -22,7 +25,7 @@ export function devClientTag(pin: string): string {
22
25
  if (commit !== undefined) return `server-staging-${commit}`;
23
26
  const version = /^[~^]?(\d+\.\d+\.\d+)$/u.exec(pin)?.[1];
24
27
  if (version !== undefined) return `v${version}`;
25
- throw new Error(`wildshard dev: the engine pin ${pin} names no release (a 40-character commit or an exact version)`);
28
+ throw new Error(`wildshard: the engine pin ${pin} names no release (a 40-character commit or an exact version)`);
26
29
  }
27
30
 
28
31
  /** This package's engine pin, from its own package.json. */
@@ -57,25 +60,59 @@ export function devClient(): Promise<string> {
57
60
  return packed === undefined ? fetchDevClient() : Promise.resolve(packed);
58
61
  }
59
62
 
63
+ /** SA43: a preparation client is a production build (DEVSERVER off) whose version document says preparation-only. */
64
+ function assertPreparation(folder: string): void {
65
+ if (!existsSync(join(folder, 'index.html'))) throw new Error(`wildshard prepare: the preparation client has no index.html (${folder})`);
66
+ const read = (name: string): unknown => existsSync(join(folder, name)) ? JSON.parse(readFileSync(join(folder, name), 'utf8')) : null;
67
+ const flags = read('build-flags.json'), version = read('version.json');
68
+ if (typeof flags !== 'object' || flags === null || !('devserver' in flags) || flags.devserver !== false
69
+ || typeof version !== 'object' || version === null || !('preparationOnly' in version) || version.preparationOnly !== true) {
70
+ throw new Error('wildshard prepare: the preparation client is not a preparation-only production build');
71
+ }
72
+ }
73
+
74
+ /** The client `wildshard prepare` serves: `$WILDSHARD_PREPARATION_CLIENT` (a folder, such as an engine checkout's
75
+ * `devserver-client.mjs --kind preparation --keep <folder>`), else engine's release at this package's pin. */
76
+ export function preparationClient(): Promise<string> {
77
+ const named = process.env['WILDSHARD_PREPARATION_CLIENT'];
78
+ if (named !== undefined && named !== '') { const folder = resolve(named); assertPreparation(folder); return Promise.resolve(folder); }
79
+ return fetchPreparationClient();
80
+ }
81
+
82
+ /** The unpacked preparation client for `pin`, fetched on first use beside the dev client (`<tag>-preparation`). `url`
83
+ * replaces the GitHub download (`$WILDSHARD_PREPARATION_CLIENT_URL`). */
84
+ export function fetchPreparationClient(options: { pin?: string; cache?: string; url?: string } = {}): Promise<string> {
85
+ return fetchClient({ ...options, url: options.url ?? process.env['WILDSHARD_PREPARATION_CLIENT_URL'] }, {
86
+ asset: PREPARATION_CLIENT_ASSET, suffix: '-preparation', verb: 'prepare', label: 'preparation client', check: assertPreparation });
87
+ }
88
+
60
89
  /** The unpacked client folder for `pin`, fetched on first use. `url` replaces the GitHub download (tests, mirrors:
61
90
  * `$WILDSHARD_DEV_CLIENT_URL`). A failed or refused download keeps nothing. */
62
- export async function fetchDevClient(options: { pin?: string; cache?: string; url?: string } = {}): Promise<string> {
63
- const tag = devClientTag(options.pin ?? enginePin()), cache = options.cache ?? devClientCache(), folder = join(cache, tag);
91
+ export function fetchDevClient(options: { pin?: string; cache?: string; url?: string } = {}): Promise<string> {
92
+ return fetchClient({ ...options, url: options.url ?? process.env['WILDSHARD_DEV_CLIENT_URL'] }, {
93
+ asset: DEV_CLIENT_ASSET, suffix: '', verb: 'dev', label: 'dev client', check: assertDevserver });
94
+ }
95
+
96
+ interface ClientAsset { asset: string; suffix: string; verb: string; label: string; check: (folder: string) => void }
97
+ async function fetchClient(options: { pin?: string; cache?: string; url?: string | undefined }, kind: ClientAsset): Promise<string> {
98
+ const tag = devClientTag(options.pin ?? enginePin()), cache = options.cache ?? devClientCache(), folder = join(cache, `${tag}${kind.suffix}`);
64
99
  if (existsSync(join(folder, 'index.html'))) return folder;
65
- const url = options.url ?? process.env['WILDSHARD_DEV_CLIENT_URL'] ?? `${RELEASES}/${tag}/${DEV_CLIENT_ASSET}`;
66
- console.info(`wildshard dev: fetching engine's dev client (${tag}) once, into ${cache}`);
100
+ const url = options.url ?? `${RELEASES}/${tag}/${kind.asset}`;
101
+ // prepare prints its result as JSON on stdout, so its progress goes to stderr
102
+ const progress = kind.verb === 'prepare' ? console.error : console.info;
103
+ progress(`wildshard ${kind.verb}: fetching engine's ${kind.label} (${tag}) once, into ${cache}`);
67
104
  const response = await fetch(url);
68
- if (!response.ok) throw new Error(`wildshard dev: engine release ${tag} has no ${DEV_CLIENT_ASSET} (${url}: ${String(response.status)})`);
105
+ if (!response.ok) throw new Error(`wildshard ${kind.verb}: engine release ${tag} has no ${kind.asset} (${url}: ${String(response.status)})`);
69
106
  const bytes = Buffer.from(await response.arrayBuffer());
70
107
  mkdirSync(cache, { recursive: true });
71
- const part = join(cache, `${tag}.part-${String(process.pid)}`), archive = `${part}.tar.gz`;
108
+ const part = join(cache, `${tag}${kind.suffix}.part-${String(process.pid)}`), archive = `${part}.tar.gz`;
72
109
  rmSync(part, { recursive: true, force: true }); mkdirSync(part);
73
110
  try {
74
111
  writeFileSync(archive, bytes);
75
112
  execFileSync('tar', ['-xzf', archive, '-C', part]);
76
- assertDevserver(part);
113
+ kind.check(part);
77
114
  if (!existsSync(join(folder, 'index.html'))) { rmSync(folder, { recursive: true, force: true }); renameSync(part, folder); }
78
115
  } finally { rmSync(part, { recursive: true, force: true }); rmSync(archive, { force: true }); }
79
- console.info(`wildshard dev: engine's dev client ${tag}, ${(bytes.length / 1e6).toFixed(1)} MB`);
116
+ progress(`wildshard ${kind.verb}: engine's ${kind.label} ${tag}, ${(bytes.length / 1e6).toFixed(1)} MB`);
80
117
  return folder;
81
118
  }
@@ -3,7 +3,7 @@ import { executeBundle } from './executeBundle';
3
3
  import { generationRecipes } from './generationRecipe.ts';
4
4
  import { mergeProjectSections } from './projectSections';
5
5
  import { writeEmptyShardSource } from './newProject';
6
- import { shardFolderName, shardOutputRoot } from './shardSource';
6
+ import { shardFolderName, shardOutputRoot, shardRepoRoot } from './shardSource';
7
7
  import { clientPage } from './clientPage';
8
8
  import { assertConfigBoundary } from './configBoundary';
9
9
  import { createProjectGeneration, finishProjectGeneration, isProjectGenerator, type ProjectGenerationContext, type ProjectGenerationInputRoot } from './projectGeneration';
@@ -322,7 +322,7 @@ async function withDiscovery(project: string, manifest: unknown, values: Discove
322
322
  if (!/^\.(?:jpe?g|png|webp|svg|hdr)$/u.test(extension)) return row;
323
323
  // `/src/shards/<folder>/x` names x in this shard source, whether it sits there or at a single-shard repo's src/ (SA17).
324
324
  const own = `src/shards/${shardFolderName(project)}/`;
325
- const bytes = readFileSync(path.startsWith(own) ? resolve(project, path.slice(own.length)) : resolve(project, '../../..', path)), hash = hashAssetBytes(bytes), held = assets.has(hash);
325
+ const bytes = readFileSync(path.startsWith(own) ? resolve(project, path.slice(own.length)) : resolve(shardRepoRoot(project), path)), hash = hashAssetBytes(bytes), held = assets.has(hash);
326
326
  const url = `/shardfiles/${folder}/blobs/image/${hash}${extension}`;
327
327
  if (!held) mounts.set(url, bytes);
328
328
  art.set(url, bytes.length);
@@ -133,7 +133,7 @@ export const REFUSAL_RULES: readonly RefusalRule[] = [
133
133
  { id: 'audio-waiver', anchor: 'audio-waiver', steps: 'any', codes: ['audio-waiver-invalid'],
134
134
  fix: 'Fix audio-waiver.json: this shard\'s slug, a date not yet past, and at least the bytes its audio holds.' },
135
135
  { id: 'shardfile-draft', anchor: 'shardfile-draft', steps: ['shardfile', 'upload'], match: /is an unprepared draft \(sdk 0\.2\)/u,
136
- fix: 'Run `wildshard prepare <folder> --base <url>`, then `wildshard build <folder>`; a shard repo\'s `pack:shards` does both (WILDSHARD_PREPARATION_URL).' },
136
+ fix: 'Run `wildshard prepare <folder>`, then `wildshard build <folder>`; a shard repo\'s `pack:shards` does both (WILDSHARD_PREPARATION_URL).' },
137
137
  { id: 'shardfile-link', anchor: 'shardfile-link', steps: ['shardfile', 'pack'], match: /not a regular file|link is refused/u,
138
138
  fix: 'Replace links in the shard file folder with real files, then build again.' },
139
139
  { id: 'shardfile-folder-missing', anchor: 'shardfile-folder-missing', steps: ['shardfile', 'pack'], match: /(?:build|pack) needs a shard file folder|ENOENT/u,
@@ -33,6 +33,22 @@ export function isRepoSource(source: string): boolean {
33
33
  return basename(source) === 'src' && (existsSync(resolve(source, SHARD_CONFIG)) || isHandwrittenSource(source));
34
34
  }
35
35
 
36
+ /**
37
+ * SA44: the repo a shard source sits in, where its `public/` and `out/` are. The two layouts name it: a single-shard
38
+ * repo's `src/` is one folder below it and a multi-shard repo's `src/shards/<slug>/` three. Any other source takes the
39
+ * nearest folder above it with a `package.json` or `.git`, else its own parent. Layout comes first, so a fixture under
40
+ * some repo's `tmp/` is its own repo, as it always was.
41
+ */
42
+ export function shardRepoRoot(source: string): string {
43
+ const given = resolve(source), parent = dirname(given);
44
+ if (isRepoSource(given)) return parent;
45
+ if (basename(parent) === 'shards' && basename(dirname(parent)) === 'src') return dirname(dirname(parent));
46
+ for (let at = parent; ; at = dirname(at)) {
47
+ if (existsSync(resolve(at, 'package.json')) || existsSync(resolve(at, '.git'))) return at;
48
+ if (dirname(at) === at) return parent;
49
+ }
50
+ }
51
+
36
52
  /** Where build output lands for a shard source: the repo root for `src/`, the source folder itself otherwise. */
37
53
  export function shardOutputRoot(source: string): string {
38
54
  return isRepoSource(source) ? dirname(source) : source;