Skip to content

Commit a2eecec

Browse files
committed
Move dependency update skill into the repository.
1 parent ee4eaa7 commit a2eecec

4 files changed

Lines changed: 322 additions & 0 deletions

File tree

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
name: void-deps-updates
3+
description: Update direct and transitive dependencies in the Void framework repository while preserving compatibility and measuring the unpacked production install of void plus dependencies. Use for Void dependency upgrades, Cloudflare toolchain alignment, and Vite+ starter updates.
4+
---
5+
6+
# Void dependency updates
7+
8+
Work in the Void maintainer checkout. Read its current `AGENTS.md`, `packages/void/AGENTS.md`, `TESTING.md`, `.node-version`, and catalogs. Follow the requested analysis/update and local/push scope; prefer local main for implementation unless instructed otherwise.
9+
10+
## Update
11+
12+
- Capture a fresh production-install baseline **before editing**. Build and pack the complete public release cohort, including the platform runtime. Use [the measurement helper](#measure).
13+
- Update direct and transitive dependencies recursively through Vite+. Preserve explicitly held TypeScript/Svelte versions and their framework-specific catalogs; inspect current compatibility constraints rather than freezing historical versions forever.
14+
- Coordinate `cf`, Cloudflare Vite plugin, Wrangler, Miniflare/workerd, and Cloudflare support packages using their actual registry ranges and dist-tags. Dated prereleases need explicit alignment; stable `latest` can be an older major than an intended beta.
15+
- Preserve compatible published ranges, `workspace:*`, strict catalogs, intentional overrides, and package extensions. Avoid unnecessary pins or forcing incompatible runtime versions. Run `vp dedupe` and inspect remaining outdated packages.
16+
- Update `void init`/Vite+ scaffold and bootstrap expectations. Match the React compiler dependency to the installed React plugin's peer range. Keep Sandbox SDK, Docker helper, and verified helper layer aligned.
17+
- Keep prerender architecture changes separate from routine dependency alignment.
18+
19+
## Verify and deliver
20+
21+
Start with exact affected tests, then `vp run test --list`, affected tests, and `vp run check`. Follow `TESTING.md` for builds, artifact validation, lint, and final full tests. Do not overlap builds with checks reading the same generated output.
22+
23+
Manifest/lockfile updates require the full npm/pnpm × React/Vue/Svelte/Solid packed matrix, plus Vite+ starters:
24+
25+
```sh
26+
vp run build
27+
VOID_PACKED_SUITE=full node .github/scripts/packed-consumer.mjs
28+
VOID_PACKED_TOOLCHAIN=vite-plus node .github/scripts/packed-consumer.mjs
29+
```
30+
31+
Repeat the fresh size measurement. Inspect installed runtime paths/versions, not just the workspace lockfile or Void's own tarball. Report file contents in MiB with hardlinks counted once; identify platform, architecture, Node, cohort, and baseline. Keep disk allocation separate. Read [measurement notes](references/measurement.md) for interpretation and a dated example.
32+
33+
When committing, use `Update deps.` unless the user specifies otherwise. Preserve unrelated work. Push only within the current task's authorization; if CI monitoring is requested, follow the exact pushed revision through relevant checks until green. Report commit, size delta, held-back versions, verification, and publishing status.
34+
35+
## Measure
36+
37+
Run from the repository root with its Node version and a **new output directory outside the checkout**:
38+
39+
```sh
40+
node .agents/skills/void-deps-updates/scripts/measure-install.mjs --repo . --out /tmp/void-deps-before
41+
# After the update/build, use a different fresh directory:
42+
node .agents/skills/void-deps-updates/scripts/measure-install.mjs --repo . --out /tmp/void-deps-after
43+
```
44+
45+
The helper uses the checkout's packed registry and `vp pm pack`, installs with npm `--omit=dev`, checks packaged platform integrity, and writes `footprint.json`. `--archives <dir>` reuses captured tarballs; external resolutions can still change unless their lockfile is preserved. It does not publish or deploy.
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: 'Void Dependency Updates'
3+
short_description: 'Update dependencies without install-size regressions'
4+
default_prompt: 'Use $void-deps-updates to update Void dependencies and compare the fresh production install size.'
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Install-size interpretation
2+
3+
Use the checkout's current package structure and policies; dated versions are evidence, not permanent pins.
4+
5+
## Comparable measurements
6+
7+
- Build and pack every public Void package as one cohort, including `@void/platform` runtime artifacts. Resolve public sibling names through `.github/scripts/packed-registry.mjs`.
8+
- Install in a fresh directory with npm `--omit=dev`, no consumer overrides/workspace links, and normal required install behavior. Compare the same Node/npm, OS, architecture, and options before/after. Keep archives, lockfile, registry/time, and footprint JSON.
9+
- The primary metric is unpacked regular-file bytes under consumer `node_modules`, counting each hardlinked inode once and not following symlinks. MiB means bytes / 1,048,576. Filesystem allocation (`du`) is separate and can vary with unpacking/storage. Neither the monorepo nor Void's own tarball represents this metric.
10+
- Enumerate actual installed Miniflare/workerd paths and versions; compatible identical copies can be deduplicated, incompatible ranges cannot. An old development runtime in the workspace lock does not establish production duplication.
11+
- A fresh install measures what published ranges resolve to now; a frozen workspace install measures the tested repository graph. Preserve historical locks because external resolutions can change even when reusing Void tarballs.
12+
13+
## Proven result: November 9, 2026
14+
15+
Commit `8b888f4d7` (`Update deps.`), baseline `11d73a6a1`, locally packed Void 1.6.2 cohort, Node 24.22.1, macOS arm64:
16+
17+
| Metric | Before | After |
18+
| ------------------------------ | -----------: | -----------: |
19+
| Unpacked regular-file contents | 563.6326 MiB | 368.8433 MiB |
20+
| Final recorded disk allocation | 601.0859 MiB | 403.0938 MiB |
21+
22+
Content reduction: 194.7894 MiB / 34.5596%. Older direct Miniflare stayed on November 1 while external ranges resolved newer tools. Alignment left one Miniflare `5.20261104.0-beta` and workerd `1.20261104.1`, alongside cf `1.0.0-beta.28`, Vite plugin `2.0.0-beta.v.12`, and Wrangler `4.158.0`. The workspace still had an old development/compatibility runtime. Christoph's earlier “v1.1.12 was about 420 MB” has unspecified units/platform and is not a controlled baseline.
23+
24+
## Update pitfalls
25+
26+
- Preserve strict catalogs when recursive updates fail on a catalog mismatch: update coherent catalog entries, then retry. Deliberately select intended beta versions rather than downgrading via stable dist-tags.
27+
- Do not substitute a prerender-engine redesign to avoid coordinating Miniflare. That architecture change was explicitly deferred.
28+
- Vite+ changes affect initializer version strings, bootstrap expectations, and generated commands. React plugin peer-range changes can require a separate compiler scaffold update.
29+
- Check package-extension version selectors after upstream upgrades. Analog Nitro once needed its H3 extension moved to the new exact plugin version.
30+
- Markdown-exit 2 required a small heading-anchor typing adapter; runtime compile/metadata tests still mattered.
31+
- Astryx moved screen-reader toast announcements separately from the visible toast; do not assume the visible surface retains `role=status`.
32+
- Real Cloudflare build/dev tests belong in forked integration processes: macOS native watcher teardown crashed a worker-thread full run. Keep module isolation and regression assertions; do not mask crashes or stale selectors with retries/timeouts.
Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
import assert from 'node:assert/strict';
2+
import { execFileSync, spawn } from 'node:child_process';
3+
import {
4+
existsSync,
5+
lstatSync,
6+
mkdirSync,
7+
readdirSync,
8+
readFileSync,
9+
realpathSync,
10+
writeFileSync,
11+
} from 'node:fs';
12+
// eslint-disable-next-line no-restricted-imports -- Containment checks require host-native filesystem paths, not Vite identifiers.
13+
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
14+
import { pathToFileURL } from 'node:url';
15+
import { parseArgs } from 'node:util';
16+
17+
const { values } = parseArgs({
18+
options: {
19+
repo: { type: 'string' },
20+
out: { type: 'string' },
21+
archives: { type: 'string' },
22+
help: { type: 'boolean', short: 'h' },
23+
},
24+
});
25+
if (values.help) {
26+
console.log(
27+
'Usage: node measure-install.mjs --repo <Void checkout> --out <new directory> [--archives <captured cohort>]',
28+
);
29+
} else {
30+
try {
31+
await measure();
32+
} catch (error) {
33+
console.error(error.message);
34+
process.exitCode = 1;
35+
}
36+
}
37+
38+
async function measure() {
39+
assert(values.repo && values.out, '--repo and --out are required; use --help.');
40+
const repository = realpathSync(resolve(values.repo));
41+
// Resolve existing ancestors too: /var and /private/var alias on macOS.
42+
let ancestor = resolve(values.out);
43+
const suffix = [];
44+
while (!existsSync(ancestor)) {
45+
suffix.unshift(basename(ancestor));
46+
const parent = dirname(ancestor);
47+
assert.notEqual(parent, ancestor, 'Cannot resolve output directory.');
48+
ancestor = parent;
49+
}
50+
const output = join(realpathSync(ancestor), ...suffix);
51+
const within = relative(repository, output);
52+
assert(
53+
within.startsWith('..' + sep) || within === '..' || isAbsolute(within),
54+
'--out must be outside the checkout.',
55+
);
56+
assert(
57+
!existsSync(output),
58+
'--out must be a new directory; existing results are never overwritten.',
59+
);
60+
const registryModule = join(repository, '.github/scripts/packed-registry.mjs');
61+
assert(existsSync(registryModule), 'Not a Void checkout: packed registry helper missing.');
62+
const { inspectPackage, startPackedRegistry } = await import(pathToFileURL(registryModule));
63+
const publicPackages = readdirSync(join(repository, 'packages'), { withFileTypes: true })
64+
.filter((entry) => entry.isDirectory())
65+
.map((entry) => ({
66+
cwd: join(repository, 'packages', entry.name),
67+
manifest: JSON.parse(
68+
readFileSync(join(repository, 'packages', entry.name, 'package.json'), 'utf8'),
69+
),
70+
}))
71+
.filter((pkg) => pkg.manifest.private !== true);
72+
const archives = values.archives
73+
? realpathSync(resolve(values.archives))
74+
: join(output, 'archives');
75+
mkdirSync(output, { recursive: true });
76+
if (!values.archives) {
77+
mkdirSync(archives);
78+
for (const { cwd, manifest } of publicPackages) {
79+
execFileSync(
80+
'vp',
81+
['pm', 'pack', '--out', join(archives, `${manifest.name.replaceAll('/', '-')}.tgz`)],
82+
{ cwd, stdio: 'pipe' },
83+
);
84+
}
85+
}
86+
const packages = readdirSync(archives)
87+
.filter((name) => name.endsWith('.tgz'))
88+
.map((name) => inspectPackage(join(archives, name)));
89+
for (const { manifest } of publicPackages) {
90+
assert(
91+
packages.some((pkg) => pkg.manifest.name === manifest.name),
92+
`Incomplete cohort: missing ${manifest.name}.`,
93+
);
94+
}
95+
const version = packages.find((pkg) => pkg.manifest.name === 'void')?.manifest.version;
96+
assert(version, 'Captured cohort must include void.');
97+
assert(
98+
packages.some((pkg) => pkg.manifest.name === '@void/platform'),
99+
'Captured cohort must include @void/platform.',
100+
);
101+
for (const pkg of packages) {
102+
if (pkg.manifest.name === 'void' || pkg.manifest.name.startsWith('@void/')) {
103+
assert.equal(
104+
pkg.manifest.version,
105+
version,
106+
`${pkg.manifest.name}: inconsistent release cohort version.`,
107+
);
108+
}
109+
}
110+
const registry = await startPackedRegistry(packages);
111+
try {
112+
const config = join(output, '.npmrc');
113+
writeFileSync(
114+
join(output, 'package.json'),
115+
JSON.stringify({ private: true, dependencies: { void: version } }, null, 2) + '\n',
116+
);
117+
writeFileSync(
118+
config,
119+
`registry=${registry.origin}\naudit=false\nfund=false\nengine-strict=true\n`,
120+
);
121+
const environment = { ...process.env };
122+
for (const key of Object.keys(environment)) {
123+
if (
124+
/^(VOID_|VP_|CLOUDFLARE_|CF_|WRANGLER_|NPM_TOKEN$|NODE_AUTH_TOKEN$|npm_config_)/i.test(key)
125+
) {
126+
delete environment[key];
127+
}
128+
}
129+
environment.npm_config_userconfig = config;
130+
console.log(`Installing captured cohort: void@${version}, npm --omit=dev`);
131+
await new Promise((done, fail) => {
132+
const child = spawn('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], {
133+
cwd: output,
134+
env: environment,
135+
stdio: 'inherit',
136+
timeout: 300_000,
137+
});
138+
child.on('error', fail);
139+
child.on('exit', (code, signal) =>
140+
code === 0 ? done() : fail(new Error(`npm install failed: ${signal ?? code}`)),
141+
);
142+
});
143+
execFileSync(
144+
process.execPath,
145+
[
146+
'--input-type=module',
147+
'-e',
148+
`
149+
import { findPackageJSON } from 'node:module';
150+
import { readFileSync } from 'node:fs';
151+
import { pathToFileURL } from 'node:url';
152+
const file = findPackageJSON('@void/platform', import.meta.resolve('void'));
153+
const entry = JSON.parse(readFileSync(file, 'utf8')).exports['./installer'].import;
154+
const { resolvePlatformRuntime } = await import(new URL(entry, pathToFileURL(file)));
155+
if (resolvePlatformRuntime().manifest.platformVersion !== ${JSON.stringify(version)}) throw new Error('Packaged runtime version mismatch.');
156+
`,
157+
],
158+
{ cwd: output, env: environment, stdio: 'inherit' },
159+
);
160+
161+
let uniqueBytes = 0;
162+
let logicalBytes = 0;
163+
const seen = new Set();
164+
const runtimes = [];
165+
const largeFiles = [];
166+
const runtimeNames = new Set([
167+
'cf',
168+
'miniflare',
169+
'workerd',
170+
'wrangler',
171+
'@cloudflare/runtime-types',
172+
'@cloudflare/vite-plugin',
173+
]);
174+
function walk(directory) {
175+
for (const entry of readdirSync(directory, { withFileTypes: true })) {
176+
const file = join(directory, entry.name);
177+
if (entry.isDirectory()) {
178+
walk(file);
179+
} else if (entry.isFile()) {
180+
const stat = lstatSync(file);
181+
const inode = `${stat.dev}:${stat.ino}`;
182+
logicalBytes += stat.size;
183+
if (!seen.has(inode)) {
184+
seen.add(inode);
185+
uniqueBytes += stat.size;
186+
}
187+
if (stat.size > 10 * 1024 * 1024) {
188+
largeFiles.push({ path: relative(output, file), bytes: stat.size, inode });
189+
}
190+
if (entry.name === 'package.json') {
191+
// Bundled fixtures can contain non-manifest package.json files.
192+
let manifest;
193+
try {
194+
manifest = JSON.parse(readFileSync(file, 'utf8'));
195+
} catch {
196+
continue;
197+
}
198+
if (runtimeNames.has(manifest.name)) {
199+
runtimes.push({
200+
name: manifest.name,
201+
version: manifest.version,
202+
path: relative(output, file),
203+
});
204+
}
205+
}
206+
}
207+
}
208+
}
209+
walk(join(output, 'node_modules'));
210+
let diskMiB = null;
211+
if (process.platform !== 'win32') {
212+
const du = execFileSync('du', ['-sk', join(output, 'node_modules')], { encoding: 'utf8' });
213+
diskMiB = Number(du.trim().split(/\s+/)[0]) / 1024;
214+
}
215+
const result = {
216+
capturedAt: new Date().toISOString(),
217+
repositoryCommit: execFileSync('git', ['rev-parse', 'HEAD'], {
218+
cwd: repository,
219+
encoding: 'utf8',
220+
}).trim(),
221+
version,
222+
node: process.version,
223+
npm: execFileSync('npm', ['--version'], { env: environment, encoding: 'utf8' }).trim(),
224+
platform: process.platform,
225+
arch: process.arch,
226+
archives,
227+
install: 'npm install --omit=dev (fresh local cohort, no consumer overrides)',
228+
uniqueBytes,
229+
uniqueMiB: uniqueBytes / 1024 / 1024,
230+
logicalBytes,
231+
logicalMiB: logicalBytes / 1024 / 1024,
232+
diskMiB,
233+
runtimes,
234+
largeFiles,
235+
};
236+
writeFileSync(join(output, 'footprint.json'), JSON.stringify(result, null, 2) + '\n');
237+
console.log(JSON.stringify(result, null, 2));
238+
} finally {
239+
await registry.close();
240+
}
241+
}

0 commit comments

Comments
 (0)