@wildshard/sdk 0.2.6 → 0.2.7

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.
@@ -35,26 +35,28 @@ export function projectSourceStamp(source: string): string {
35
35
  }
36
36
  return rows.sort().join('\n');
37
37
  }
38
- /** A rebuilt static author client. Closing it releases its watcher, socket and private build products. */
39
- export interface DevProject { url: string; close: () => Promise<void> }
38
+ /** A rebuilt static author client. Closing it releases its socket, private build products and watchers; `exiting` neither
39
+ * waits for a running rebuild nor closes the watchers, which the process's exit drops (SD-6: closing a recursive watch
40
+ * on macOS blocks the event loop for seconds). */
41
+ export interface DevProject { url: string; close: (options?: { exiting?: boolean }) => Promise<void> }
40
42
  /** Only the author command chooses DEVSERVER; requests, cookies and URL switches cannot enable it. */
41
43
  export async function devProject(project: string, options: { decisionLegacyLines?: number; port?: number; client?: string } = {}): Promise<DevProject> {
42
44
  const source = resolve(project), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'wildshard-dev-')));
43
- let revision = 0, error: string | null = null, current = '', previous = '', stopped = false;
45
+ let revision = 0, error: string | null = null, current = '', previous = '', stopped = false, shardRoot = '';
44
46
  const scope = new Scope('sdk.dev');
45
47
  let debounce: Scope | undefined, work = Promise.resolve();
46
48
  const rebuild = async (): Promise<void> => {
47
49
  if (stopped) return;
48
50
  const target = join(scratch, `build-${revision + 1}`);
49
51
  try {
50
- await buildProject(source, target, { devserver: true, ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }), ...(options.client === undefined ? {} : { client: options.client }) });
52
+ const built = await buildProject(source, target, { devserver: true, ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }), ...(options.client === undefined ? {} : { client: options.client }) });
51
53
  const page = join(target, 'index.html');
52
54
  if (!existsSync(page)) throw new Error('wildshard dev requires the SDK devserver client; build/pack the SDK first');
53
55
  const flags: unknown = JSON.parse(readFileSync(join(target, 'build-flags.json'), 'utf8'));
54
56
  if (typeof flags !== 'object' || flags === null || !('devserver' in flags) || flags.devserver !== true) throw new Error('wildshard dev requires a client compiled in devserver mode');
55
57
  writeFileSync(page, readFileSync(page, 'utf8').replace('</body>', `${POLL.replace('WS_REVISION', String(revision + 1))}</body>`));
56
58
  if (previous !== '') rmSync(previous, { recursive: true, force: true });
57
- previous = current; current = target; revision++; error = null;
59
+ previous = current; current = target; shardRoot = `/shardfiles/${built.identity.slug}/`; revision++; error = null;
58
60
  } catch (cause) {
59
61
  rmSync(target, { recursive: true, force: true }); error = cause instanceof Error ? cause.message : String(cause);
60
62
  if (current === '') throw cause;
@@ -70,7 +72,10 @@ export async function devProject(project: string, options: { decisionLegacyLines
70
72
  response.setHeader('Content-Type', 'application/json'); response.end(JSON.stringify({ revision, error })); return;
71
73
  }
72
74
  if (request.method !== 'GET' && request.method !== 'HEAD') { response.writeHead(405); response.end(); return; }
73
- const local = path === '/' ? 'index.html' : path.slice(1);
75
+ // SD-2: the page's in-page server reads the shard where a release serves it, `/shardfiles/<slug>/`; here that is
76
+ // the product's own root.
77
+ const served = shardRoot !== '' && path.startsWith(shardRoot) ? path.slice(shardRoot.length - 1) : path;
78
+ const local = served === '/' ? 'index.html' : served.slice(1);
74
79
  const file = [current, previous].filter((dir) => dir !== '').map((dir) => ({ dir, file: resolve(dir, local) }))
75
80
  .find(({ dir, file: candidate }) => candidate.startsWith(`${dir}${sep}`) && existsSync(candidate) && statSync(candidate).isFile() && realpathSync(candidate).startsWith(`${dir}${sep}`));
76
81
  if (file === undefined) { response.writeHead(404); response.end(); return; }
@@ -83,6 +88,7 @@ export async function devProject(project: string, options: { decisionLegacyLines
83
88
  } catch (cause) { rmSync(scratch, { recursive: true, force: true }); throw cause; }
84
89
  let observed = projectSourceStamp(source);
85
90
  const reconcile = (): void => {
91
+ if (stopped) return;
86
92
  const next = projectSourceStamp(source);
87
93
  if (next === observed) return;
88
94
  observed = next;
@@ -102,12 +108,15 @@ export async function devProject(project: string, options: { decisionLegacyLines
102
108
  // Capture before returning the ready server; polling covers native-event gaps without rebuilding unchanged input.
103
109
  scope.interval(250, reconcile);
104
110
  const address = server.address(); if (address === null || typeof address === 'string') throw new Error('No author server address');
105
- return { url: `http://127.0.0.1:${address.port}/`, close: async () => {
111
+ return { url: `http://127.0.0.1:${address.port}/`, close: async (closing = {}) => {
106
112
  if (stopped) return;
107
- stopped = true; for (const watcher of watchers) watcher.close(); scope.dispose();
108
- await new Promise<void>((_resolve) => { server.close(() => { _resolve(); }); server.closeAllConnections(); });
109
- // A build already running owns its directory until its promise finishes.
110
- await work;
111
- rmSync(scratch, { recursive: true, force: true });
113
+ // The port goes first: closing the watchers can block for seconds (SD-6), and `wildshard dev` frees it within 2 s.
114
+ stopped = true; scope.dispose();
115
+ try {
116
+ await new Promise<void>((_resolve) => { server.close(() => { _resolve(); }); server.closeAllConnections(); });
117
+ // A build already running owns its directory until its promise finishes; on the way out it is dropped with it.
118
+ if (closing.exiting !== true) await work;
119
+ rmSync(scratch, { recursive: true, force: true });
120
+ } finally { if (closing.exiting !== true) for (const watcher of watchers) watcher.close(); }
112
121
  } };
113
122
  }
@@ -0,0 +1,81 @@
1
+ // SD-2 (meta HOW-WE-BUILD-PLAN, SHARD-AUTHORING SA15, J314): an installed `wildshard dev` serves engine's devserver client,
2
+ // the normal game page compiled in devserver mode. The package can't build it (it is engine's whole app build), so engine
3
+ // publishes it on the GitHub release of every tag (ENG-16: `scripts/devserver-client.mjs`, server-release.yml) and this
4
+ // fetches it once per engine pin into the user's cache.
5
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author tool downloads and unpacks one archive into its cache.
6
+ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
7
+ // oxlint-disable-next-line import/no-nodejs-modules -- `tar` unpacks the archive, as on every author machine.
8
+ import { execFileSync } from 'node:child_process';
9
+ // oxlint-disable-next-line import/no-nodejs-modules -- The default cache is under the user's home.
10
+ import { homedir } from 'node:os';
11
+ // oxlint-disable-next-line import/no-nodejs-modules -- Cache paths.
12
+ import { join, resolve } from 'node:path';
13
+
14
+ /** The release asset engine's `scripts/devserver-client.mjs` writes. */
15
+ export const DEV_CLIENT_ASSET = 'devserver-client.tar.gz';
16
+ const RELEASES = 'https://github.com/project-wildshard/engine/releases/download';
17
+
18
+ /** The engine release that holds the client for this package's engine pin: a commit pin (a green main build) is its
19
+ * `server-staging-<sha>` release, a version pin is its `v<version>` tag. */
20
+ export function devClientTag(pin: string): string {
21
+ const commit = /#([0-9a-f]{40})$/u.exec(pin)?.[1];
22
+ if (commit !== undefined) return `server-staging-${commit}`;
23
+ const version = /^[~^]?(\d+\.\d+\.\d+)$/u.exec(pin)?.[1];
24
+ 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)`);
26
+ }
27
+
28
+ /** This package's engine pin, from its own package.json. */
29
+ export function enginePin(): string {
30
+ const manifest: unknown = JSON.parse(readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8'));
31
+ const pin: unknown = typeof manifest === 'object' && manifest !== null && 'dependencies' in manifest && typeof manifest.dependencies === 'object' && manifest.dependencies !== null
32
+ ? (manifest.dependencies as Record<string, unknown>)['@wildshard/engine'] : undefined;
33
+ if (typeof pin !== 'string') throw new Error('wildshard dev: this package names no @wildshard/engine dependency');
34
+ return pin;
35
+ }
36
+
37
+ /** `$WILDSHARD_DEV_CLIENT_CACHE`, else `$XDG_CACHE_HOME/wildshard/dev-client`, else `~/.cache/wildshard/dev-client`. */
38
+ export function devClientCache(): string {
39
+ const env = process.env['WILDSHARD_DEV_CLIENT_CACHE'];
40
+ if (env !== undefined && env !== '') return env;
41
+ const xdg = process.env['XDG_CACHE_HOME'];
42
+ return join(xdg !== undefined && xdg !== '' ? xdg : join(homedir(), '.cache'), 'wildshard', 'dev-client');
43
+ }
44
+
45
+ function assertDevserver(folder: string): void {
46
+ if (!existsSync(join(folder, 'index.html'))) throw new Error(`wildshard dev: the dev client has no index.html (${folder})`);
47
+ const flags: unknown = JSON.parse(readFileSync(join(folder, 'build-flags.json'), 'utf8'));
48
+ if (typeof flags !== 'object' || flags === null || !('devserver' in flags) || flags.devserver !== true) throw new Error('wildshard dev: the dev client was not compiled in devserver mode');
49
+ }
50
+
51
+ /** The client `wildshard dev` serves: `$WILDSHARD_DEV_CLIENT` (a folder, such as an engine checkout's devserver build), a
52
+ * client packed into this package (`client-devserver` beside the author tools), else engine's release at the pin. */
53
+ export function devClient(): Promise<string> {
54
+ const named = process.env['WILDSHARD_DEV_CLIENT'];
55
+ if (named !== undefined && named !== '') { const folder = resolve(named); assertDevserver(folder); return Promise.resolve(folder); }
56
+ const packed = [resolve(import.meta.dirname, 'client-devserver'), resolve(import.meta.dirname, 'dist', 'client-devserver')].find((path) => existsSync(join(path, 'index.html')));
57
+ return packed === undefined ? fetchDevClient() : Promise.resolve(packed);
58
+ }
59
+
60
+ /** The unpacked client folder for `pin`, fetched on first use. `url` replaces the GitHub download (tests, mirrors:
61
+ * `$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);
64
+ 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}`);
67
+ 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)})`);
69
+ const bytes = Buffer.from(await response.arrayBuffer());
70
+ mkdirSync(cache, { recursive: true });
71
+ const part = join(cache, `${tag}.part-${String(process.pid)}`), archive = `${part}.tar.gz`;
72
+ rmSync(part, { recursive: true, force: true }); mkdirSync(part);
73
+ try {
74
+ writeFileSync(archive, bytes);
75
+ execFileSync('tar', ['-xzf', archive, '-C', part]);
76
+ assertDevserver(part);
77
+ if (!existsSync(join(folder, 'index.html'))) { rmSync(folder, { recursive: true, force: true }); renameSync(part, folder); }
78
+ } 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`);
80
+ return folder;
81
+ }
@@ -137,12 +137,10 @@ proof tape (\`wildshard-goldens\`) and move to a newer sdk
137
137
 
138
138
  \`\`\`sh
139
139
  pnpm install
140
+ pnpm exec wildshard dev .
140
141
  pnpm exec wildshard check .
141
142
  \`\`\`
142
143
 
143
- Until \`@wildshard/sdk\` is on npm, \`pnpm install\` cannot fetch it: run the CLI
144
- from a sharddev checkout instead (\`GUIDE.md\`, "Running \`wildshard\` today").
145
-
146
144
  ${layout}
147
145
  - \`public/shardfiles/\` is build output. Never edit or commit it.
148
146
  `;
@@ -3,7 +3,8 @@ 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 { shardOutputRoot } from './shardSource';
6
+ import { shardFolderName, shardOutputRoot } from './shardSource';
7
+ import { clientPage } from './clientPage';
7
8
  import { assertConfigBoundary } from './configBoundary';
8
9
  import { createProjectGeneration, finishProjectGeneration, isProjectGenerator, type ProjectGenerationContext, type ProjectGenerationInputRoot } from './projectGeneration';
9
10
  // oxlint-disable-next-line import/no-nodejs-modules -- The author CLI verifies and writes local build products.
@@ -291,8 +292,8 @@ export async function buildProject(project: string, output?: string, options: {
291
292
  if (client !== undefined) {
292
293
  cpSync(client, destination, { recursive: true });
293
294
  const json = canonicalJson(descriptor).replaceAll('<', String.raw`\u003c`);
294
- const html = readFileSync(resolve(destination, 'index.html'), 'utf8').replace('</head>', `<script id="ws-shardfile" type="application/json">${json}</script></head>`);
295
- writeFileSync(resolve(destination, 'index.html'), html);
295
+ const recorded = existsSync(resolve(destination, 'programs', `${shard.identity.slug}.json`));
296
+ writeFileSync(resolve(destination, 'index.html'), clientPage(readFileSync(resolve(destination, 'index.html'), 'utf8'), json, shard.identity.slug, recorded));
296
297
  }
297
298
  return shard;
298
299
  }
@@ -319,7 +320,9 @@ async function withDiscovery(project: string, manifest: unknown, values: Discove
319
320
  const mounts = new Map<string, Uint8Array>(), art = new Map<string, number>();
320
321
  const packed = JSON.stringify(document).replaceAll(/"\/(src\/shards\/[^"]+(\.[a-z]+))"/gu, (row: string, path: string, extension: string) => {
321
322
  if (!/^\.(?:jpe?g|png|webp|svg|hdr)$/u.test(extension)) return row;
322
- const bytes = readFileSync(resolve(project, '../../..', path)), hash = hashAssetBytes(bytes), held = assets.has(hash);
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
+ 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);
323
326
  const url = `/shardfiles/${folder}/blobs/image/${hash}${extension}`;
324
327
  if (!held) mounts.set(url, bytes);
325
328
  art.set(url, bytes.length);