@wildshard/sdk 0.2.5 → 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.
@@ -5,6 +5,7 @@ import { existsSync } from 'node:fs';
5
5
  import { buildProject, readProjectAssets, validateProject } from './project';
6
6
  import { ShardfileSchema, type Shardfile } from '@wildshard/format/shardSchema';
7
7
  import { devProject } from './dev';
8
+ import { devClient } from './devClient';
8
9
  import { proveAuthorSimulation, measureSimulation, validateSimulation } from '@wildshard/engine/host/headless';
9
10
  import { performanceReport, performanceReportLines, type PerformanceObservations } from './reportCard';
10
11
  import { projectPerformancePolicy } from './performancePolicy';
@@ -71,13 +72,16 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
71
72
  }
72
73
  if (command === 'check') {
73
74
  const rest = args.slice(1), json = rest.includes('--json'), positional = rest.filter(value => !value.startsWith('--'));
74
- if (positional.length === 0 || positional.length > 2 || rest.some(value => value.startsWith('--') && value !== '--json') || rest.filter(value => value === '--json').length > 1) throw new Error('usage: wildshard check <source> [folder] [--json]');
75
+ // TS21: --output=<slug> checks one declared output of the folder (scripts/wildshard.mjs composes its manifest and, with
76
+ // no --output on a folder that declares outputs, checks each in turn).
77
+ const outputs = rest.filter(value => value.startsWith('--output=')), selected = outputs[0]?.slice('--output='.length);
78
+ if (positional.length === 0 || positional.length > 2 || rest.some(value => value.startsWith('--') && value !== '--json' && !value.startsWith('--output=')) || rest.filter(value => value === '--json').length > 1 || outputs.length > 1 || selected === '') throw new Error('usage: wildshard check <source> [folder] [--json] [--output=<slug>]');
75
79
  // --json: stdout carries the verdict document alone; everything the steps print goes to stderr.
76
80
  // (scripts/wildshard.mjs moves log and debug for the whole run; the steps here log with info and warn.)
77
81
  const saved = { info: console.info, warn: console.warn }, toError = console.error.bind(console);
78
82
  if (json) Object.assign(console, { info: toError, warn: toError });
79
83
  let result;
80
- try { result = await checkProject(findShardSource(positional[0] ?? ''), positional[1], options); } finally { Object.assign(console, saved); }
84
+ try { result = await checkProject(findShardSource(positional[0] ?? ''), positional[1], selected === undefined ? options : { ...options, output: selected }); } finally { Object.assign(console, saved); }
81
85
  process.stdout.write(json ? `${JSON.stringify(result, null, 2)}\n` : `${checkLines(result).join('\n')}\n`);
82
86
  if (result.verdict === 'fail') process.exitCode = 1;
83
87
  return;
@@ -123,9 +127,22 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
123
127
  if (command === 'dev') {
124
128
  const port = output === undefined ? 0 : Number(output);
125
129
  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('dev port must be 0..65535');
126
- const server = await devProject(resolve(input), { port, ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }) });
127
- const close = (): void => { void server.close(); }; process.once('SIGINT', close); process.once('SIGTERM', close);
128
- console.info(`wildshard dev: ${server.url}`); return;
130
+ const server = await devProject(resolve(input), { port, client: await devClient(), ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }) });
131
+ // SD-6: a signal handler replaces Node's default exit, so the handler ends the process itself: free the port and the
132
+ // build products, then exit 0 (exit drops the watchers and any rebuild still running). A second signal exits at once.
133
+ let stopping = false;
134
+ const stop = async (): Promise<void> => {
135
+ // oxlint-disable-next-line unicorn/no-process-exit -- a second Ctrl-C ends `dev` without waiting for the first.
136
+ if (stopping) process.exit(0);
137
+ stopping = true;
138
+ try { await server.close({ exiting: true }); } catch (error) { console.error(`wildshard dev: ${error instanceof Error ? error.message : String(error)}`); }
139
+ // oxlint-disable-next-line unicorn/no-process-exit -- the signal handler replaced Node's default exit; ending is its job.
140
+ process.exit(0);
141
+ };
142
+ const onSignal = (): void => { void stop(); };
143
+ process.on('SIGINT', onSignal); process.on('SIGTERM', onSignal);
144
+ // SA15: `?skipintro` walks straight into the shard; the bare page sits on the game's title over it
145
+ console.info(`wildshard dev: ${server.url}?skipintro`); return;
129
146
  }
130
147
  if (command === 'build') {
131
148
  if (output === '--behaviour-only' && (buildFlag === undefined || buildFlag === '--check')) {
@@ -0,0 +1,19 @@
1
+ /** The client page a build or `wildshard dev` serves: engine's built `index.html` with this shard's descriptor added.
2
+ * A draft (never prepared) has no recorded entry programs, so the bank says so and the page skips the read that would
3
+ * 404 (engine `spawnDownload.ts` `shardPackBase`: `entryPrograms[slug] === false` means the cook published none). */
4
+ const BACKSLASH = String.fromCodePoint(92);
5
+
6
+ export function clientPage(html: string, descriptorJson: string, slug: string, recordedPrograms: boolean): string {
7
+ // A function replacement: a `$&` or `$'` in the shard's own text stays literal.
8
+ const page = html.replace('</head>', () => `<script id="ws-shardfile" type="application/json">${descriptorJson}</script></head>`);
9
+ if (recordedPrograms) return page;
10
+ const expression = /(<script type="application\/json" id="boot-module-files">)([^<]+)(<\/script>)/u, match = expression.exec(page);
11
+ if (match?.[2] === undefined) return page;
12
+ const bank: unknown = JSON.parse(match[2]);
13
+ if (typeof bank !== 'object' || bank === null || Array.isArray(bank)) return page;
14
+ const recorded: unknown = 'entryPrograms' in bank ? bank.entryPrograms : undefined;
15
+ const entryPrograms = typeof recorded === 'object' && recorded !== null && !Array.isArray(recorded) ? { ...recorded, [slug]: false } : { [slug]: false };
16
+ // `<` as its JSON escape, as project.ts writes the descriptor: the bank sits inside a <script>.
17
+ const json = JSON.stringify({ ...bank, entryPrograms }).replaceAll('<', `${BACKSLASH}u003c`);
18
+ return page.replace(expression, (_whole, open: string, _bank: string, close: string) => `${open}${json}${close}`);
19
+ }
@@ -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);
@@ -8,15 +8,21 @@ import { basename, resolve } from 'node:path';
8
8
  import { pathToFileURL } from 'node:url';
9
9
  // oxlint-disable-next-line import/no-nodejs-modules -- The new sdk's CLI runs under this same Node.
10
10
  import process from 'node:process';
11
- import { assertShardRepo } from './agentFiles';
11
+ import { assertShardRepo, updateShardRepo } from './agentFiles';
12
12
 
13
13
  // SHARD-AUTHORING SA18 (J314 Q7, Q27; J317 Q16): `wildshard update --pins[=<version>] [dir]`. Move the repo's pins to one
14
14
  // sdk release (the sdk, and the shard-format, engine and three specs that release pins), install with pnpm, apply the
15
15
  // release's codemods, rewrite GUIDE.md and the skills with the new sdk's own `update` (SA28), then run its `check`. It
16
16
  // starts only from a committed git tree (assertCommitted), so the author can tell its edits from their own.
17
17
 
18
- /** The pins a shard repo may list; each moves to what the release names. `@wildshard/sdk` moves to the release itself. */
19
- export const PINNED = ['@wildshard/sdk', '@wildshard/engine', '@wildshard/format', 'three'] as const;
18
+ /** The names a shard repo lists the sdk under. `new` writes `@wildshard/sdk`; the org's shard repos list it as
19
+ * `@wildshard/sharddev`, which their source imports, as a GitHub pin or NPM-PUBLISH NP8's `npm:@wildshard/sdk@<v>`
20
+ * alias. The move keeps the name the repo has. */
21
+ export const SDK_NAMES = ['@wildshard/sdk', '@wildshard/sharddev'] as const;
22
+ /** The pins a shard repo may list; each moves to what the release names. The sdk moves to the release itself. */
23
+ export const PINNED = ['@wildshard/sdk', '@wildshard/sharddev', '@wildshard/engine', '@wildshard/format', 'three'] as const;
24
+ const isSdkName = (name: string): boolean => (SDK_NAMES as readonly string[]).includes(name);
25
+ const isPinned = (name: string): boolean => (PINNED as readonly string[]).includes(name);
20
26
  const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies'] as const;
21
27
 
22
28
  /** One sdk release, as the registry describes it: its version, the exact specs it pins (dependencies win over peers)
@@ -27,6 +33,8 @@ export interface SdkRelease { readonly version: string; readonly pins: Readonly<
27
33
  export interface PinsRunner {
28
34
  /** The release `@wildshard/sdk@<spec>` names (`latest`, or a version). */
29
35
  readonly view: (spec: string, cwd: string) => SdkRelease;
36
+ /** The tags of the GitHub repo `owner/name`, each to the commit it names (`git ls-remote --tags`). */
37
+ readonly tags: (repo: string, cwd: string) => ReadonlyMap<string, string>;
30
38
  /** Run a command in `cwd` with its output shown; throw when it exits non-zero. */
31
39
  readonly run: (command: string, args: readonly string[], cwd: string) => void;
32
40
  readonly log: (line: string) => void;
@@ -67,27 +75,49 @@ const readJson = (file: string): Json => {
67
75
  };
68
76
  const stringAt = (record: Json, key: string): string | undefined => typeof record[key] === 'string' ? record[key] : undefined;
69
77
 
70
- /** One pin `movePins` changed (or left: the release no longer pins a package the repo lists). */
78
+ /** One pin `movePins` changed (or left: the release no longer pins a package the repo lists). An override's name is
79
+ * its key in `pnpm.overrides`. */
71
80
  export interface PinMove { readonly name: string; readonly field: string; readonly from: string; readonly to: string | undefined }
72
81
 
82
+ const SDK_ALIAS = /^npm:@wildshard\/sdk@(.+)$/u;
83
+ const GITHUB_PIN = /^github:([\w.-]+\/[\w.-]+)#(.+)$/u;
84
+ /** The package a `pnpm.overrides` key overrides: the last `parent>` step, without its `@<range>` selector (which may
85
+ * hold a `>` of its own, as in `three@>=0.180`). */
86
+ const overriddenPackage = (key: string): string => (key.split(/>(?=[@A-Za-z])/u).at(-1) ?? key).replace(/(?<=.)@[^@/]*$/u, '');
87
+
73
88
  /** The repo's package.json text with every listed pin moved to `release`; each pin keeps its field (a blender repo's
74
- * sdk stays a dev dependency). `engines.node` moves too, when the repo lists it, since `new` writes it and `.npmrc`
75
- * makes it strict. Nothing else in the file changes, and its indent is kept. */
76
- export function movePins(text: string, release: SdkRelease): { readonly text: string; readonly moves: readonly PinMove[] } {
89
+ * sdk stays a dev dependency) and the sdk keeps its name and form: an exact version moves to the release, an
90
+ * `npm:@wildshard/sdk@<v>` alias to the release's alias, and a GitHub pin to `sdkSpec`, which `updatePins` resolves
91
+ * (the release tag's commit); any other form (`link:`, a `$` reference, a GitHub pin with no `sdkSpec`) is left, and
92
+ * reported as a move to nothing. `pnpm.overrides` of a moved package move with it, whatever their key's form, since an
93
+ * override wins over the pin. `engines.node` moves too, when the repo lists it, since `new` writes it and `.npmrc` makes
94
+ * it strict. Nothing else in the file changes, and its indent is kept. */
95
+ export function movePins(text: string, release: SdkRelease, sdkSpec?: string): { readonly text: string; readonly moves: readonly PinMove[] } {
77
96
  const parsed: unknown = JSON.parse(text);
78
97
  if (!isRecord(parsed)) throw new Error('update --pins: package.json is not a JSON object');
79
98
  const moves: PinMove[] = [];
99
+ const target = (name: string, from: string): string | undefined => {
100
+ if (!isSdkName(name)) return release.pins[name];
101
+ if (SDK_ALIAS.test(from)) return `npm:@wildshard/sdk@${release.version}`;
102
+ if (GITHUB_PIN.test(from)) return sdkSpec;
103
+ return SEMVER.test(from) ? release.version : undefined;
104
+ };
105
+ const move = (record: Json, key: string, name: string, field: string): void => {
106
+ const from = stringAt(record, key);
107
+ if (from === undefined) return;
108
+ const to = target(name, from);
109
+ if (to === from) return;
110
+ moves.push({ name: key, field, from, to });
111
+ if (to !== undefined) record[key] = to;
112
+ };
80
113
  for (const field of DEPENDENCY_FIELDS) {
81
114
  const listed = parsed[field];
82
- if (!isRecord(listed)) continue;
83
- for (const name of PINNED) {
84
- const from = stringAt(listed, name);
85
- if (from === undefined) continue;
86
- const to = name === '@wildshard/sdk' ? release.version : release.pins[name];
87
- if (to === from) continue;
88
- moves.push({ name, field, from, to });
89
- if (to !== undefined) listed[name] = to;
90
- }
115
+ if (isRecord(listed)) for (const name of PINNED) move(listed, name, name, field);
116
+ }
117
+ const pnpm = parsed['pnpm'], overrides = isRecord(pnpm) ? pnpm['overrides'] : undefined;
118
+ if (isRecord(overrides)) for (const key of Object.keys(overrides)) {
119
+ const name = overriddenPackage(key);
120
+ if (isPinned(name)) move(overrides, key, name, 'pnpm.overrides');
91
121
  }
92
122
  const engines = parsed['engines'], node = isRecord(engines) ? stringAt(engines, 'node') : undefined;
93
123
  if (isRecord(engines) && node !== undefined && release.node !== undefined && node !== release.node) {
@@ -95,7 +125,7 @@ export function movePins(text: string, release: SdkRelease): { readonly text: st
95
125
  engines['node'] = release.node;
96
126
  }
97
127
  const indent = /^\{\r?\n([ \t]+)"/u.exec(text)?.[1] ?? 2;
98
- return { text: moves.some(move => move.to !== undefined) ? `${JSON.stringify(parsed, null, indent)}\n` : text, moves };
128
+ return { text: moves.some(moved => moved.to !== undefined) ? `${JSON.stringify(parsed, null, indent)}\n` : text, moves };
99
129
  }
100
130
 
101
131
  /** Whether package.json lists `three` itself (a `--template sdk` repo does; a blender one does not). */
@@ -107,14 +137,49 @@ function installedVersion(project: string, name: string): string | undefined {
107
137
  return existsSync(file) ? stringAt(readJson(file), 'version') : undefined;
108
138
  }
109
139
 
110
- /** The sdk version the repo is on now: its exact `@wildshard/sdk` pin, which must match what is installed. */
111
- function currentSdk(project: string, listed: Json): string {
112
- const pin = DEPENDENCY_FIELDS.map(field => listed[field]).map(pins => isRecord(pins) ? stringAt(pins, '@wildshard/sdk') : undefined)
113
- .find(found => found !== undefined);
114
- if (pin === undefined || !SEMVER.test(pin)) throw new Error(`update --pins: cannot tell which sdk ${project} is on: pin @wildshard/sdk to a version (not ${pin ?? 'nothing'})`);
115
- const installed = installedVersion(project, '@wildshard/sdk');
116
- if (installed !== undefined && installed !== pin) throw new Error(`update --pins: ${project} pins @wildshard/sdk ${pin} but has ${installed} installed: run pnpm install, then wildshard check ., then update --pins again`);
117
- return pin;
140
+ /** The sdk dependency a repo lists: its name, its spec, and the GitHub repo and ref when it is a GitHub pin. */
141
+ interface SdkPin { readonly name: string; readonly spec: string; readonly github?: { readonly repo: string; readonly ref: string } }
142
+
143
+ /** The repo's sdk pin: an exact version, an `npm:@wildshard/sdk@<version>` alias, or a GitHub pin (`github:<owner>/<repo>#<ref>`,
144
+ * at a commit or a tag), under either name. Anything else (`link:`, a range) names no one release. */
145
+ function sdkPin(project: string, listed: Json): SdkPin {
146
+ for (const field of DEPENDENCY_FIELDS) for (const name of SDK_NAMES) {
147
+ const pins = listed[field], spec = isRecord(pins) ? stringAt(pins, name) : undefined;
148
+ if (spec === undefined) continue;
149
+ const alias = SDK_ALIAS.exec(spec)?.[1], github = GITHUB_PIN.exec(spec);
150
+ if (SEMVER.test(spec) || (alias !== undefined && SEMVER.test(alias))) return { name, spec };
151
+ if (github !== null) return { name, spec, github: { repo: github[1] ?? '', ref: github[2] ?? '' } };
152
+ throw new Error(`update --pins: cannot tell which sdk ${project} is on: pin ${name} to a version, an npm:@wildshard/sdk@<version> alias or a github: commit (not ${spec})`);
153
+ }
154
+ throw new Error(`update --pins: cannot tell which sdk ${project} is on: its package.json lists no ${SDK_NAMES.join(' or ')}`);
155
+ }
156
+
157
+ /** The release a `v<version>` tag names, newest first when one commit has several. */
158
+ function taggedVersion(tags: ReadonlyMap<string, string>, ref: string): string | undefined {
159
+ if (/^v\d/u.test(ref)) return SEMVER.test(ref.slice(1)) ? ref.slice(1) : undefined;
160
+ if (!/^[0-9a-f]{7,40}$/u.test(ref)) return undefined;
161
+ return [...tags].filter(([tag, commit]) => commit.startsWith(ref) && /^v\d/u.test(tag) && SEMVER.test(tag.slice(1)))
162
+ .map(([tag]) => tag.slice(1)).sort(compareVersions).at(-1);
163
+ }
164
+
165
+ /** The sdk version the repo is on now. A version or alias pin says it, and must match what is installed; a GitHub pin
166
+ * says it by its tag, or by the release tag at its commit; a commit no release tag names is whatever is installed. */
167
+ function currentSdk(project: string, pin: SdkPin, tags: () => ReadonlyMap<string, string>): string {
168
+ const pinned = pin.github === undefined ? SDK_ALIAS.exec(pin.spec)?.[1] ?? pin.spec : taggedVersion(tags(), pin.github.ref);
169
+ const installed = installedVersion(project, pin.name);
170
+ if (pinned !== undefined && installed !== undefined && installed !== pinned) throw new Error(`update --pins: ${project} pins ${pin.name} ${pinned} but has ${installed} installed: run pnpm install, then wildshard check ., then update --pins again`);
171
+ const from = pinned ?? installed;
172
+ if (from === undefined) throw new Error(`update --pins: cannot tell which sdk ${project} is on: ${pin.name} ${pin.spec} is no release tag's commit and no sdk is installed: run pnpm install, then update --pins again`);
173
+ return from;
174
+ }
175
+
176
+ /** Where a GitHub sdk pin moves for `version`: a tag pin to that release's tag, a commit pin to the commit the release's
177
+ * `v<version>` tag names, so the repo's pin style stays as it was. */
178
+ function githubTarget(pin: SdkPin & { readonly github: NonNullable<SdkPin['github']> }, version: string, tags: ReadonlyMap<string, string>): { readonly spec: string; readonly why: string } {
179
+ const tag = `v${version}`, commit = tags.get(tag);
180
+ if (commit === undefined) throw new Error(`update --pins: ${pin.github.repo} has no tag ${tag}, so ${pin.name} ${pin.spec} has no release commit to move to; pin ${pin.name} to npm:@wildshard/sdk@${version} instead`);
181
+ if (/^v\d/u.test(pin.github.ref)) return { spec: `github:${pin.github.repo}#${tag}`, why: `kept as a GitHub tag pin: ${tag}` };
182
+ return { spec: `github:${pin.github.repo}#${commit}`, why: `kept as a GitHub commit pin: the ${tag} tag's commit` };
118
183
  }
119
184
 
120
185
  /** A release's codemods: `codemods/<version>.mjs` in the installed sdk, each default-exporting
@@ -173,6 +238,25 @@ export function assertCommitted(project: string): void {
173
238
  }
174
239
  }
175
240
 
241
+ /** git ls-remote: a GitHub repo's tags, each to its commit (an annotated tag's peeled `^{}` line wins). */
242
+ function gitTags(repo: string, cwd: string): ReadonlyMap<string, string> {
243
+ let out: string;
244
+ // GIT_TERMINAL_PROMPT=0: a private or misspelt repo fails instead of asking for a username on the terminal.
245
+ try { out = execFileSync('git', ['ls-remote', '--tags', `https://github.com/${repo}.git`], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } }); }
246
+ catch (error) { throw new Error(`update --pins: git ls-remote --tags on github.com/${repo} failed: ${error instanceof Error ? error.message.split('\n')[0] ?? '' : String(error)}`, { cause: error }); }
247
+ const tags = new Map<string, string>();
248
+ for (const [commit, ref] of out.split('\n').map(line => line.split('\t'))) {
249
+ const tag = ref?.replace(/^refs\/tags\//u, '');
250
+ if (commit === undefined || tag === undefined || tag === ref) continue;
251
+ if (tag.endsWith('^{}')) tags.set(tag.slice(0, -3), commit);
252
+ else if (!tags.has(tag)) tags.set(tag, commit);
253
+ }
254
+ return tags;
255
+ }
256
+
257
+ /** The newest sdk whose `wildshard update` refuses a repo that lists it as `@wildshard/sharddev`. */
258
+ const LAST_UPDATE_WITHOUT_SHARDDEV = '0.2.5';
259
+
176
260
  /** pnpm view: the release a spec names, with the specs it pins. */
177
261
  function pnpmView(spec: string, cwd: string): SdkRelease {
178
262
  let out: string;
@@ -197,7 +281,7 @@ function runInherited(command: string, args: readonly string[], cwd: string): vo
197
281
  execFileSync(command, args, { cwd, stdio: 'inherit' });
198
282
  }
199
283
 
200
- export const PNPM_RUNNER: PinsRunner = { view: pnpmView, run: runInherited, log: line => { console.info(line); } };
284
+ export const PNPM_RUNNER: PinsRunner = { view: pnpmView, tags: gitTags, run: runInherited, log: line => { console.info(line); } };
201
285
 
202
286
  /** `wildshard update --pins[=<version>] [dir]`: move the repo at `project` to the sdk release `spec` names. */
203
287
  export async function updatePins(project: string, spec = 'latest', runner: PinsRunner = PNPM_RUNNER): Promise<void> {
@@ -205,20 +289,33 @@ export async function updatePins(project: string, spec = 'latest', runner: PinsR
205
289
  const packageFile = resolve(project, 'package.json'), listed = readJson(packageFile);
206
290
  const manager = stringAt(listed, 'packageManager');
207
291
  if (manager !== undefined && !manager.startsWith('pnpm@')) throw new Error(`update --pins: ${project} names ${manager} as its package manager; update --pins installs with pnpm`);
208
- const from = currentSdk(project, listed);
292
+ const pin = sdkPin(project, listed);
209
293
  assertCommitted(project);
294
+ let tagsRead: ReadonlyMap<string, string> | undefined;
295
+ const tags = (): ReadonlyMap<string, string> => {
296
+ tagsRead ??= runner.tags(pin.github?.repo ?? '', project);
297
+ return tagsRead;
298
+ };
299
+ const from = currentSdk(project, pin, tags);
210
300
  const release = runner.view(spec, project);
211
- if (compareVersions(release.version, from) < 0) throw new Error(`update --pins: ${project} is on @wildshard/sdk ${from}, newer than ${release.version}; update --pins moves forward only`);
212
- runner.log(`wildshard update --pins: @wildshard/sdk ${from} -> ${release.version}`);
301
+ if (compareVersions(release.version, from) < 0) throw new Error(`update --pins: ${project} is on ${pin.name} ${from}, newer than ${release.version}; update --pins moves forward only`);
302
+ const github = pin.github === undefined || release.version === from ? undefined : githubTarget({ ...pin, github: pin.github }, release.version, tags());
303
+ // A GitHub pin that is not moving stays as it is, and so does an sdk-named GitHub override.
304
+ const sdkSpec = github?.spec ?? (pin.github === undefined ? undefined : pin.spec);
305
+ runner.log(`wildshard update --pins: ${pin.name} ${from} -> ${release.version}`);
213
306
 
214
307
  // 1. Move the pins. Until the codemods are done, a failure puts package.json and the lock file back and installs the
215
308
  // old sdk again, so a second run starts from the same sdk and applies every codemod.
216
309
  const lockFile = resolve(project, 'pnpm-lock.yaml'), oldText = readFileSync(packageFile, 'utf8');
217
310
  const oldLock = existsSync(lockFile) ? readFileSync(lockFile) : undefined;
218
- const moved = movePins(oldText, release);
219
- for (const move of moved.moves) runner.log(move.to === undefined
220
- ? ` left ${move.name} ${move.from}: sdk ${release.version} no longer pins it`
221
- : ` ${move.name} ${move.from} -> ${move.to}`);
311
+ const moved = movePins(oldText, release, sdkSpec);
312
+ for (const move of moved.moves) {
313
+ const what = move.field === 'pnpm.overrides' ? `pnpm.overrides ${move.name}` : move.name;
314
+ const left = isSdkName(move.field === 'pnpm.overrides' ? overriddenPackage(move.name) : move.name)
315
+ ? 'update --pins cannot move this form of the sdk pin; move it by hand' : `sdk ${release.version} no longer pins it`;
316
+ runner.log(move.to === undefined ? ` left ${what} ${move.from}: ${left}` : ` ${what} ${move.from} -> ${move.to}`);
317
+ if (move.name === pin.name && move.field !== 'pnpm.overrides' && github !== undefined) runner.log(` ${github.why}`);
318
+ }
222
319
  if (moved.moves.length === 0) runner.log(' pins already match');
223
320
  writeFileSync(packageFile, moved.text);
224
321
  let sdkRoot: string;
@@ -226,28 +323,35 @@ export async function updatePins(project: string, spec = 'latest', runner: PinsR
226
323
  // 2. Install, then confirm pnpm installed what the pins say.
227
324
  try { runner.run('pnpm', ['install'], project); }
228
325
  catch (error) { throw new Error(`update --pins: pnpm install failed on @wildshard/sdk ${release.version}`, { cause: error }); }
229
- const installed = installedVersion(project, '@wildshard/sdk');
230
- if (installed !== release.version) throw new Error(`update --pins: pnpm installed @wildshard/sdk ${installed ?? 'nothing'}, not ${release.version}`);
326
+ const installed = installedVersion(project, pin.name);
327
+ if (installed !== release.version) throw new Error(`update --pins: pnpm installed ${pin.name} ${installed ?? 'nothing'}, not ${release.version}`);
231
328
  // A repo that lists three (not a blender one) must get the exact three the release pins.
232
329
  const threePin = release.pins['three'], three = installedVersion(project, 'three');
233
330
  if (threePin !== undefined && SEMVER.test(threePin) && listsThree(listed) && three !== threePin) throw new Error(`update --pins: sdk ${release.version} pins three ${threePin}, but ${three ?? 'none'} is installed`);
234
- sdkRoot = realpathSync(resolve(project, 'node_modules/@wildshard/sdk'));
331
+ sdkRoot = realpathSync(resolve(project, 'node_modules', pin.name));
235
332
  // 3. The release's codemods, read from the installed sdk.
236
333
  const codemods = await applyCodemods(project, sdkRoot, from, release.version);
237
334
  runner.log(codemods.length === 0 ? ` no codemods between ${from} and ${release.version}` : codemods.join('\n'));
238
335
  } catch (error) {
239
336
  writeFileSync(packageFile, oldText);
240
337
  if (oldLock !== undefined) writeFileSync(lockFile, oldLock);
241
- let back = `package.json and pnpm-lock.yaml are back on @wildshard/sdk ${from}`;
338
+ let back = `package.json and pnpm-lock.yaml are back on ${pin.name} ${from}`;
242
339
  try { runner.run('pnpm', ['install'], project); } catch { back += ', but pnpm install failed: run it again'; }
243
340
  const message = error instanceof Error ? error.message : String(error);
244
341
  throw new Error(`${message}\n ${back}; a codemod may have edited src/ before it failed: git diff shows it`, { cause: error });
245
342
  }
246
343
 
247
- // 4. GUIDE.md and the skills, by the new sdk's own `update` (SA28); 5. its `check`.
344
+ // 4. GUIDE.md and the skills, by the new sdk's own `update` (SA28); 5. its `check`. An sdk up to 0.2.5 has an `update`
345
+ // that refuses a repo listing it as @wildshard/sharddev, so for those this CLI syncs that sdk's guide and skills itself.
248
346
  const cli = resolve(sdkRoot, 'bin/wildshard.mjs');
249
- try { runner.run(process.execPath, [cli, 'update', project], project); }
250
- catch (error) { throw new Error(`update --pins: the pins moved to @wildshard/sdk ${release.version}, but its wildshard update failed: run pnpm exec wildshard update`, { cause: error }); }
347
+ if (pin.name === '@wildshard/sdk' || compareVersions(release.version, LAST_UPDATE_WITHOUT_SHARDDEV) > 0) {
348
+ try { runner.run(process.execPath, [cli, 'update', project], project); }
349
+ catch (error) { throw new Error(`update --pins: the pins moved to @wildshard/sdk ${release.version}, but its wildshard update failed: run pnpm exec wildshard update`, { cause: error }); }
350
+ } else {
351
+ runner.log(` sdk ${release.version}'s own update does not know ${pin.name}, so this CLI writes its GUIDE.md and skills`);
352
+ try { for (const line of updateShardRepo(project, sdkRoot)) runner.log(line); }
353
+ catch (error) { throw new Error(`update --pins: the pins moved to @wildshard/sdk ${release.version}, but writing its GUIDE.md and skills failed (${error instanceof Error ? error.message : String(error)}): run pnpm --package=@wildshard/sdk@latest dlx wildshard update`, { cause: error }); }
354
+ }
251
355
  try { runner.run(process.execPath, [cli, 'check', '.'], project); }
252
356
  catch (error) { throw new Error(`update --pins: the pins moved to @wildshard/sdk ${release.version}, but check failed: fix each refusal above, then run wildshard check .`, { cause: error }); }
253
357
  runner.log(`wildshard update --pins: on @wildshard/sdk ${release.version}, check pass`);