@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.
- package/GUIDE.md +29 -30
- package/docs/api/EXPORT-TIERS.md +204 -0
- package/lint/export-tiers.json +176 -0
- package/package.json +3 -2
- package/scripts/build-shardfiles.mjs +6 -5
- package/scripts/capture-hero.mjs +53 -14
- package/scripts/export-tiers.mjs +57 -0
- package/scripts/scratch-dir.mjs +95 -0
- package/scripts/wildshard.mjs +21 -0
- package/skills/wildshard/SKILL.md +2 -3
- package/skills/wildshard-goldens/SKILL.md +6 -7
- package/skills/wildshard-mockup-to-model/SKILL.md +2 -2
- package/src/cli/help.ts +2 -2
- package/src/sharddev/bake/placeholders.ts +40 -13
- package/src/sharddev/checkProject.ts +4 -1
- package/src/sharddev/cli.ts +22 -5
- package/src/sharddev/clientPage.ts +19 -0
- package/src/sharddev/dev.ts +21 -12
- package/src/sharddev/devClient.ts +81 -0
- package/src/sharddev/newProject.ts +1 -3
- package/src/sharddev/project.ts +7 -4
package/src/sharddev/dev.ts
CHANGED
|
@@ -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
|
|
39
|
-
|
|
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
|
-
|
|
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
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
`;
|
package/src/sharddev/project.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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);
|