@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 +20 -9
- package/package.json +1 -1
- package/scripts/build-shardfiles.mjs +1 -1
- package/scripts/shard-build-pool.mjs +1 -1
- package/scripts/wildshard.mjs +3 -1
- package/skills/wildshard-upgrade/SKILL.md +11 -4
- package/src/sharddev/agentFiles.ts +3 -2
- package/src/sharddev/updatePins.ts +144 -40
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
|
|
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.
|
|
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:
|
|
936
|
-
`@wildshard/
|
|
937
|
-
|
|
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).
|
|
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.
|
|
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 = '';
|
package/scripts/wildshard.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
|
21
|
-
|
|
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
|
|
19
|
-
|
|
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)
|
|
75
|
-
*
|
|
76
|
-
|
|
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 (
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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(
|
|
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
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
|
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
|
|
212
|
-
|
|
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)
|
|
220
|
-
? `
|
|
221
|
-
|
|
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,
|
|
230
|
-
if (installed !== release.version) throw new Error(`update --pins: pnpm installed
|
|
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
|
|
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
|
|
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
|
-
|
|
250
|
-
|
|
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`);
|