@wildshard/sdk 0.2.5 → 0.2.6

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
@@ -340,8 +340,8 @@ other name refuses before `new` writes anything. Leave the flag out or pass `--t
340
340
 
341
341
  #### update-target
342
342
 
343
- `update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it. Run it in
344
- that folder, or name it: `wildshard update my-shard`.
343
+ `update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it, or
344
+ `@wildshard/sharddev`. Run it in that folder, or name it: `wildshard update my-shard`.
345
345
 
346
346
  #### update-pins-no-git
347
347
 
@@ -928,13 +928,26 @@ keep your own notes for agents in `AGENTS.md`, never in this guide or a skill: `
928
928
  prints `already up to date` or the files it wrote, and `git status` shows only `GUIDE.md`, `.claude/skills/` and any
929
929
  agent file it added.
930
930
 
931
+ To move to a newer sdk, run the newest CLI once, whatever sdk the repo is on now:
932
+
933
+ ```sh
934
+ pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins
935
+ ```
936
+
937
+ An older installed CLI cannot do the move: 0.2.4 and earlier refuse the flag, and 0.2.5 refuses a repo that lists
938
+ the sdk as `@wildshard/sharddev` or by a GitHub pin. Once the repo is on the newest sdk, `pnpm exec wildshard
939
+ update --pins` works too.
940
+
931
941
  `wildshard update --pins` moves the repo to a newer sdk release first: npm's latest, or the one you name with
932
- `--pins=<version>` (`--pins=0.2.4`). In order, it:
942
+ `--pins=<version>` (`--pins=0.2.5`). In order, it:
933
943
 
934
944
  1. reads the release from npm (`pnpm view`) and refuses one older than the repo's sdk;
935
- 2. moves every pin `package.json` lists to what that release names: `@wildshard/sdk` to the release,
936
- `@wildshard/format`, `@wildshard/engine` and `three` to the exact specs it pins, and `engines.node` to the Node it
937
- needs. It changes nothing else in the file and prints each move;
945
+ 2. moves every pin `package.json` lists to what that release names: the sdk to the release, `@wildshard/format`,
946
+ `@wildshard/engine` and `three` to the exact specs it pins, each `pnpm.overrides` entry for one of those packages
947
+ with it, and `engines.node` to the Node it needs. The sdk keeps the name and form the repo lists it with:
948
+ `@wildshard/sdk` or `@wildshard/sharddev`; an exact version, an `npm:@wildshard/sdk@<version>` alias, or a GitHub
949
+ pin, which moves to the commit the release's `v<version>` tag names (or to that tag, if it named a tag). It changes
950
+ nothing else in the file and prints each move;
938
951
  3. runs `pnpm install`, and refuses if pnpm did not install that sdk and, when the repo lists `three`, that `three`;
939
952
  4. applies the release's codemods: each `codemods/<version>.mjs` the new sdk ships, for every version above the old
940
953
  sdk and up to the new one, oldest first. A codemod edits your shard source for a change that would otherwise
@@ -945,6 +958,4 @@ agent file it added.
945
958
  If step 3 or 4 fails, it puts `package.json` and `pnpm-lock.yaml` back and installs the old sdk again. It refuses to
946
959
  start unless `git status` is clean (`update-pins-dirty`, `update-pins-no-git`): a codemod edits your files. Done when
947
960
  its last line reads `on @wildshard/sdk <version>, check pass`. Commit `package.json`, `pnpm-lock.yaml`, the guide,
948
- the skills and any codemod edit together. A refusal is `update-pins` (section 6). An sdk older than the one
949
- that built `--pins` refuses the flag; run the newest CLI once instead:
950
- `pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins`.
961
+ the skills and any codemod edit together. A refusal is `update-pins` (section 6).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.2.5",
3
+ "version": "0.2.6",
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": {
@@ -195,7 +195,7 @@ export async function buildShardfiles(root,options={}) {
195
195
  const counters=createBuildCacheCounters(),stop=observeBuildCache(counters);
196
196
  let complete=false;
197
197
  try {const result=await buildShardfilesWork(root,options,counters);complete=true;return result;}
198
- finally {stop();console.info(formatBuildCacheReport(counters.snapshot(complete)));}
198
+ finally {stop();if(process.env.WILDSHARD_CACHE_REPORT==='1')console.info(formatBuildCacheReport(counters.snapshot(complete)));}
199
199
  }
200
200
 
201
201
  if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
@@ -30,7 +30,7 @@ export async function runShardBuildPool(items, work, prepare) {
30
30
  export function runShardBuild(args, signal, cacheReport) {
31
31
  return new Promise((resolve, reject) => {
32
32
  const child = spawn(process.execPath, ['--import', fileURLToPath(import.meta.resolve('@wildshard/engine/scripts/shardfile-inputs.mjs')), resolvePath(import.meta.dirname, 'wildshard.mjs'), ...args], {
33
- cwd: process.cwd(), env: {...process.env,WILDSHARD_WORLD_TEXTURE_CACHE:process.env.WILDSHARD_WORLD_TEXTURE_CACHE??resolvePath(shardfileCacheRoot(),'.world-textures-v1')}, signal, stdio: ['ignore', 'inherit', 'pipe'],
33
+ cwd: process.cwd(), env: {...process.env,...(cacheReport===undefined?{}:{WILDSHARD_CACHE_REPORT:'1'}),WILDSHARD_WORLD_TEXTURE_CACHE:process.env.WILDSHARD_WORLD_TEXTURE_CACHE??resolvePath(shardfileCacheRoot(),'.world-textures-v1')}, signal, stdio: ['ignore', 'inherit', 'pipe'],
34
34
  });
35
35
  // Forward all diagnostics, retaining only a bounded tail for the pool's error.
36
36
  let stderrTail = '';
@@ -107,5 +107,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1]
107
107
  complete=true;
108
108
  }
109
109
  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
110
- finally {stop();console.error(`\n${formatBuildCacheReport(counters.snapshot(complete))}`);}
110
+ // The counters line is for the build pool, which sets WILDSHARD_CACHE_REPORT=1 for the children whose report it reads,
111
+ // and for debugging a build's cache; an author's run, refusals included, does not print it.
112
+ finally {stop();if(process.env.WILDSHARD_CACHE_REPORT==='1')console.error(`\n${formatBuildCacheReport(counters.snapshot(complete))}`);}
111
113
  }
@@ -10,16 +10,23 @@ blender` repo pins only the first two, as dev dependencies (`GUIDE.md#2-the-shar
10
10
  moves every pin together, then the shard source must build again on them. `GUIDE.md` at the repo root holds the
11
11
  facts; a pointer `GUIDE.md#<anchor>` is the guide heading with that anchor.
12
12
 
13
+ Run the newest CLI once to move, whatever sdk the repo is on now:
14
+
15
+ ```sh
16
+ pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins
17
+ ```
18
+
13
19
  `wildshard update --pins` does the move in one command (`GUIDE.md#7-wildshard-update`): it moves every pin to the
14
- release, runs `pnpm install`, applies the release's codemods, rewrites the guide and skills, and runs check.
20
+ release, runs `pnpm install`, applies the release's codemods, rewrites the guide and skills, and runs check. An
21
+ installed 0.2.4 or older refuses the flag, and 0.2.5 refuses a repo that lists the sdk as `@wildshard/sharddev` or by
22
+ a GitHub pin, so start from the line above.
15
23
 
16
24
  ## The steps, in order
17
25
 
18
26
  1. **Start clean.** Commit your own changes, then `wildshard check .` on the old pins; if it fails, fix that first.
19
27
  Done when `git status` is clean and check passes, so any later refusal is the upgrade's.
20
- 2. **Move:** `pnpm exec wildshard update --pins` for npm's latest sdk, or `--pins=<version>` for one release. If the
21
- installed CLI refuses the flag (an sdk older than `--pins`), run the newest once:
22
- `pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins`. Done when it prints a line per pin it moved.
28
+ 2. **Move:** `pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins` for npm's latest sdk, or
29
+ `--pins=<version>` in place of `--pins` for one release. Done when it prints a line per pin it moved.
23
30
  3. **Read its last line.** `on @wildshard/sdk <version>, check pass` means the move is done: go to step 5. A line
24
31
  ending `[update-pins] fix: ...` is a refusal: read `GUIDE.md#update-pins` in the guide now in the repo;
25
32
  `[update-pins-dirty]` (`GUIDE.md#update-pins-dirty`) means go back to step 1.
@@ -101,7 +101,8 @@ function sdkVersion(root: string): string {
101
101
  return typeof parsed === 'object' && parsed !== null && 'version' in parsed && typeof parsed.version === 'string' ? parsed.version : 'unknown';
102
102
  }
103
103
 
104
- /** A shard repo is a folder whose package.json lists `@wildshard/sdk` (`new` writes it; a blender repo as a dev dependency). */
104
+ /** A shard repo is a folder whose package.json lists `@wildshard/sdk` (`new` writes it; a blender repo as a dev dependency)
105
+ * or `@wildshard/sharddev`, the name the org's shard repos list it under (a GitHub pin, or an `npm:@wildshard/sdk` alias). */
105
106
  export function assertShardRepo(project: string): void {
106
107
  const file = resolve(project, 'package.json');
107
108
  let parsed: unknown;
@@ -109,7 +110,7 @@ export function assertShardRepo(project: string): void {
109
110
  catch (error) { throw new Error(`update: ${project} is not a shard repo: its package.json is not valid JSON (${error instanceof Error ? error.message : String(error)})`, { cause: error }); }
110
111
  const fields: unknown[] = typeof parsed === 'object' && parsed !== null
111
112
  ? [Reflect.get(parsed, 'dependencies'), Reflect.get(parsed, 'devDependencies')] : [];
112
- if (!fields.some(field => typeof field === 'object' && field !== null && Object.hasOwn(field, '@wildshard/sdk'))) throw new Error(`update: ${project} is not a shard repo: its package.json does not list @wildshard/sdk (or it has none)`);
113
+ if (!fields.some(field => typeof field === 'object' && field !== null && (Object.hasOwn(field, '@wildshard/sdk') || Object.hasOwn(field, '@wildshard/sharddev')))) throw new Error(`update: ${project} is not a shard repo: its package.json does not list @wildshard/sdk or @wildshard/sharddev (or it has none)`);
113
114
  }
114
115
 
115
116
  /** `wildshard update [dir]`: sync the agent files of the shard repo at `project`, and say what changed, one line each. */
@@ -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`);