Skip to content

Commit 51f9fec

Browse files
Brooooooklynclaude
andcommitted
fix(cloudflare): stop on unsupported runtimes and keep deploy failures readable and safe
`bunx void deploy` in the generated Bun workflow ran the CLI on the runner's Node 22. The helper child that reads the Cloudflare credential failed to load there (`node:http` has no `setGlobalProxyFromEnv`), the reason was dropped, and the upload stopped with "Cloudflare session has no bearer". A later trigger-sync failure then switched traffic back to an empty previous version. - Check the runtime before loading the CLI: `void` and `create-void` stop on Node outside ^24.22.0 || >=26.12.0, or Bun below 1.4.0, with a clear message. The bin entry imports only the check, then loads the CLI. - `void init --github` adds actions/setup-node to Bun workflows and sets check-latest on setup-node. - Child failures keep their exit code, signal and a scrubbed stderr tail. Credentials are removed by exact value before truncation. Each Cloudflare child step writes a debug `cloudflare_op` record, and failures write `deploy_end`. - Read the credential before upload when Worker settings will be published, so a missing credential leaves traffic unchanged. - When trigger sync fails after activation, keep the new version live if the previous one is an empty draft, a placeholder, or has no Void trigger snapshot. `activeVersionId` now always names the live version, and new `triggersRestored`/`restoreSkipped` fields drive a "Live now: <id>" message. - `keep_vars` no longer narrows the kept bindings to drop secret types. - Deploy log writes are synchronous so records survive process.exit. Fixes #627 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 8fe70d1 commit 51f9fec

36 files changed

Lines changed: 3696 additions & 675 deletions

‎docs/guide/quickstart.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ yarn void init
2828
```
2929

3030
```sh [bun]
31+
# bunx runs Void with the `node` on your PATH: use Node.js 24.22+ or 26.12+
3132
bun add -D void
3233
bunx void init
3334
```

‎docs/integrations/cloudflare.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ Set production server values with `void secret put <NAME>`. Void preserves exist
174174

175175
### Readiness and rollback
176176

177-
Void normally verifies an uploaded version before sending it traffic. If readiness or trigger updates fail, it restores the previous deployment. Finish or cancel any gradual rollout in Cloudflare before deploying through Void.
177+
Void normally verifies an uploaded version before sending it traffic. If readiness or trigger updates fail, it restores the previous deployment. If trigger updates fail and Void cannot restore the previous version's triggers, for example because another tool deployed it or it is an empty draft, the new version stays live and the error says which version is serving traffic. Finish or cancel any gradual rollout in Cloudflare before deploying through Void.
178178

179179
For an existing Durable Object Worker that Cloudflare cannot stage, review the changes and use:
180180

‎docs/reference/cli.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ Use this page as a command reference. If you are setting up a project for the fi
8282

8383
The docs use `void` for brevity. Outside package scripts, run it with your package manager: `npx void`, `pnpm void`, `yarn void`, `bunx void`, or `vpx void`.
8484

85+
The CLI needs Node.js 24.22+ or 26.12+. `npx`, `bunx` and package scripts use the `node` on your `PATH`; `vpx` uses the version in `.node-version`.
86+
8587
Alternatively, you can add `./node_modules/.bin` to your `PATH` so that you can invoke `void` directly when you are in the root directory of your app.
8688

8789
:::warning ⚠️ Prefer local install

‎packages/create-void/src/index.ts‎

Lines changed: 14 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,17 @@
11
#!/usr/bin/env node
22

3-
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
4-
import * as p from '@voidzero-dev/vite-plus-prompts';
5-
import { resolve } from 'pathslash';
6-
import pc from 'picocolors';
7-
import { parseCreateArgs, validateProjectName } from './args.ts';
8-
import { detectPM, pmExec, pmInstall, run, writePnpmBuildPolicy } from './pm.ts';
9-
10-
const pm = detectPM();
11-
12-
async function main() {
13-
console.log();
14-
15-
const createArgs = parseCreateArgs(process.argv.slice(2));
16-
let appName = createArgs.appName;
17-
18-
if (!appName && !process.stdin.isTTY) {
19-
p.log.error('create-void: Pass a project name when running without an interactive terminal.');
20-
process.exit(1);
21-
}
22-
23-
if (!appName) {
24-
const name = await p.text({
25-
message: 'Project name:',
26-
defaultValue: 'my-app',
27-
placeholder: 'my-app',
28-
validate: validateProjectName,
29-
});
30-
if (p.isCancel(name) || typeof name !== 'string') {
31-
p.cancel('Cancelled.');
32-
process.exit(0);
33-
}
34-
appName = name;
35-
}
36-
37-
const targetDir = resolve(appName);
38-
39-
if (existsSync(targetDir)) {
40-
const entries = readdirSync(targetDir);
41-
if (entries.length > 0) {
42-
p.log.error(`create-void: Directory '${pc.bold(appName)}' is not empty.`);
43-
process.exit(1);
44-
}
45-
}
46-
47-
// The release publishes the scaffolder and CLI at the same version. Preserve
48-
// that exact version, including prereleases, instead of switching to latest.
49-
const { version: voidVersion } = JSON.parse(
50-
readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
51-
) as { version: string };
52-
53-
mkdirSync(targetDir, { recursive: true });
54-
55-
const pkg = {
56-
name: appName,
57-
private: true,
58-
type: 'module',
59-
devDependencies: {
60-
void: voidVersion,
61-
},
62-
};
63-
64-
writeFileSync(resolve(targetDir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
65-
// pnpm 12 fails the first install when a dependency has an unapproved build
66-
// script. Write Void's narrow policy before installing the CLI so a fresh
67-
// project can bootstrap without disabling pnpm's build-script protection.
68-
writePnpmBuildPolicy(targetDir, pm);
69-
70-
p.log.step('Installing Void...');
71-
await run(pmInstall(pm), targetDir);
72-
73-
p.log.step('Scaffolding starter...');
74-
await run([...pmExec(pm), 'void', 'init', ...createArgs.initArgs], targetDir);
75-
76-
p.log.step('Installing starter dependencies...');
77-
await run(pmInstall(pm), targetDir);
78-
79-
p.outro(`\n${pc.green(`✓ Created ${appName}`)}`, { withGuide: false });
80-
p.outro(`cd ${appName} && ${pm === 'npm' ? 'npm run' : pm} dev`);
3+
// The bin entry. It imports only the dependency-free runtime check, so an
4+
// unsupported Node or Bun gets a clear message instead of a link-time
5+
// SyntaxError from a newer API in the bundled prompts. `void init` stops on an
6+
// unsupported runtime too, so checking first keeps a failed run from leaving a
7+
// half-created folder that blocks the next attempt.
8+
import { unsupportedRuntimeMessage } from './runtime-support.ts';
9+
10+
const message = unsupportedRuntimeMessage(process.versions, process.execPath, 'create-void');
11+
if (message) {
12+
process.stderr.write(`${message}\n`);
13+
// exitCode instead of exit() so the message is flushed when stderr is a pipe.
14+
process.exitCode = 1;
15+
} else {
16+
await import('./main.ts');
8117
}
82-
83-
main().catch((err) => {
84-
p.log.error(err.message);
85-
process.exit(1);
86-
});

‎packages/create-void/src/main.ts‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
2+
import * as p from '@voidzero-dev/vite-plus-prompts';
3+
import { resolve } from 'pathslash';
4+
import pc from 'picocolors';
5+
import { parseCreateArgs, validateProjectName } from './args.ts';
6+
import { detectPM, pmExec, pmInstall, run, writePnpmBuildPolicy } from './pm.ts';
7+
8+
const pm = detectPM();
9+
10+
async function main() {
11+
console.log();
12+
13+
const createArgs = parseCreateArgs(process.argv.slice(2));
14+
let appName = createArgs.appName;
15+
16+
if (!appName && !process.stdin.isTTY) {
17+
p.log.error('create-void: Pass a project name when running without an interactive terminal.');
18+
process.exit(1);
19+
}
20+
21+
if (!appName) {
22+
const name = await p.text({
23+
message: 'Project name:',
24+
defaultValue: 'my-app',
25+
placeholder: 'my-app',
26+
validate: validateProjectName,
27+
});
28+
if (p.isCancel(name) || typeof name !== 'string') {
29+
p.cancel('Cancelled.');
30+
process.exit(0);
31+
}
32+
appName = name;
33+
}
34+
35+
const targetDir = resolve(appName);
36+
37+
if (existsSync(targetDir)) {
38+
const entries = readdirSync(targetDir);
39+
if (entries.length > 0) {
40+
p.log.error(`create-void: Directory '${pc.bold(appName)}' is not empty.`);
41+
process.exit(1);
42+
}
43+
}
44+
45+
// The release publishes the scaffolder and CLI at the same version. Preserve
46+
// that exact version, including prereleases, instead of switching to latest.
47+
const { version: voidVersion } = JSON.parse(
48+
readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
49+
) as { version: string };
50+
51+
mkdirSync(targetDir, { recursive: true });
52+
53+
const pkg = {
54+
name: appName,
55+
private: true,
56+
type: 'module',
57+
devDependencies: {
58+
void: voidVersion,
59+
},
60+
};
61+
62+
writeFileSync(resolve(targetDir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
63+
// pnpm 12 fails the first install when a dependency has an unapproved build
64+
// script. Write Void's narrow policy before installing the CLI so a fresh
65+
// project can bootstrap without disabling pnpm's build-script protection.
66+
writePnpmBuildPolicy(targetDir, pm);
67+
68+
p.log.step('Installing Void...');
69+
await run(pmInstall(pm), targetDir);
70+
71+
p.log.step('Scaffolding starter...');
72+
await run([...pmExec(pm), 'void', 'init', ...createArgs.initArgs], targetDir);
73+
74+
p.log.step('Installing starter dependencies...');
75+
await run(pmInstall(pm), targetDir);
76+
77+
p.outro(`\n${pc.green(`✓ Created ${appName}`)}`, { withGuide: false });
78+
p.outro(`cd ${appName} && ${pm === 'npm' ? 'npm run' : pm} dev`);
79+
}
80+
81+
main().catch((err) => {
82+
p.log.error(err.message);
83+
process.exit(1);
84+
});
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
// Checks the runtime before the CLI loads. On an older Node, a static import of a
2+
// newer API (such as `setGlobalProxyFromEnv` from `node:http`) fails at link time
3+
// with a SyntaxError before any code can run, and child processes reuse
4+
// `process.execPath`, so a deploy would stop halfway. This file must therefore
5+
// load on any Node or Bun release: it has no imports and uses no new APIs.
6+
//
7+
// packages/void/src/cli/runtime-support.ts and packages/create-void/src/runtime-support.ts
8+
// are byte-identical copies, because create-void runs before `void` is installed.
9+
// A unit test keeps the two files and both `engines.node` fields equal.
10+
11+
/** Must equal `engines.node` in packages/void and packages/create-void. */
12+
export const NODE_ENGINES = '^24.22.0 || >=26.12.0';
13+
14+
/**
15+
* Bun is not a documented runtime, but `bunx --bun` and Bun-only images (where
16+
* `node` is Bun) run the CLI on it. Bun reports a Node version below 26.12, so
17+
* it gets its own floor: 1.4.0 is the first release where Void's Cloudflare
18+
* helper process loads. This lets working setups keep working.
19+
*/
20+
export const BUN_MINIMUM = '1.4.0';
21+
22+
type Version = [major: number, minor: number, patch: number];
23+
24+
export type RuntimeVersions = { readonly node?: string; readonly bun?: string };
25+
26+
function isDigits(text: string): boolean {
27+
if (text.length === 0) {
28+
return false;
29+
}
30+
for (let i = 0; i < text.length; i++) {
31+
const code = text.charCodeAt(i);
32+
if (code < 48 || code > 57) {
33+
return false;
34+
}
35+
}
36+
return true;
37+
}
38+
39+
/**
40+
* Parses `1.2.3`, with an optional leading `v`. A pre-release or build tag
41+
* (`27.0.0-nightly2026...`, `1.4.0+abc`) is ignored, so a nightly counts as its
42+
* release line.
43+
*/
44+
export function parseVersion(text: string): Version | null {
45+
let core = text.trim();
46+
if (core.startsWith('v')) {
47+
core = core.slice(1);
48+
}
49+
for (const separator of ['-', '+']) {
50+
const index = core.indexOf(separator);
51+
if (index !== -1) {
52+
core = core.slice(0, index);
53+
}
54+
}
55+
const parts = core.split('.');
56+
if (parts.length !== 3 || !parts.every(isDigits)) {
57+
return null;
58+
}
59+
return [Number(parts[0]), Number(parts[1]), Number(parts[2])];
60+
}
61+
62+
function compareVersions(a: Version, b: Version): number {
63+
return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
64+
}
65+
66+
type Clause = { caret: boolean; version: Version };
67+
68+
/** Supports only the forms used in `engines.node`: `^x.y.z` and `>=x.y.z`, joined by `||`. */
69+
function parseRange(range: string): Array<Clause> {
70+
return range.split('||').map((raw) => {
71+
const clause = raw.trim();
72+
const caret = clause.startsWith('^');
73+
const prefix = caret ? '^' : clause.startsWith('>=') ? '>=' : null;
74+
const version = prefix === null ? null : parseVersion(clause.slice(prefix.length));
75+
if (!version) {
76+
throw new Error(`runtime-support: unsupported range clause '${clause}'`);
77+
}
78+
return { caret, version };
79+
});
80+
}
81+
82+
export function satisfiesRange(version: Version, range: string): boolean {
83+
return parseRange(range).some(
84+
({ caret, version: floor }) =>
85+
compareVersions(version, floor) >= 0 && (!caret || version[0] === floor[0]),
86+
);
87+
}
88+
89+
/** `^24.22.0 || >=26.12.0` -> `24.22+ or 26.12+`. */
90+
function describeRange(range: string): string {
91+
return parseRange(range)
92+
.map(({ version: [major, minor, patch] }) =>
93+
patch === 0 ? `${major}.${minor}+` : `${major}.${minor}.${patch}+`,
94+
)
95+
.join(' or ');
96+
}
97+
98+
/**
99+
* Returns the error to print when this runtime cannot run the CLI, or `null`.
100+
* The text names only the runtime version and executable path, never env or argv.
101+
*/
102+
export function unsupportedRuntimeMessage(
103+
versions: RuntimeVersions,
104+
execPath: string,
105+
command = 'void',
106+
): string | null {
107+
const nodeRange = describeRange(NODE_ENGINES);
108+
if (versions.bun !== undefined) {
109+
const bun = parseVersion(versions.bun);
110+
const minimum = parseVersion(BUN_MINIMUM);
111+
if (bun && minimum && compareVersions(bun, minimum) >= 0) {
112+
return null;
113+
}
114+
return (
115+
`${command}: Bun ${BUN_MINIMUM} or later is required. Found Bun ${versions.bun} (${execPath}).\n` +
116+
`Update Bun, or run ${command} on Node.js ${nodeRange}.`
117+
);
118+
}
119+
const node = versions.node === undefined ? null : parseVersion(versions.node);
120+
if (node && satisfiesRange(node, NODE_ENGINES)) {
121+
return null;
122+
}
123+
const found = versions.node === undefined ? 'an unknown version' : `v${versions.node}`;
124+
return (
125+
`${command}: Node.js ${nodeRange} is required. Found Node.js ${found} (${execPath}).\n` +
126+
'bunx, npx and package scripts use the `node` on PATH; vp/vpx use .node-version.\n' +
127+
'Update .node-version or the node on PATH. In GitHub Actions add actions/setup-node\n' +
128+
'with `node-version: lts/*` and `check-latest: true` before this step.'
129+
);
130+
}
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import { spawnSync } from 'node:child_process';
2+
import { mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
3+
import { tmpdir } from 'node:os';
4+
import { join } from 'node:path';
5+
import { pathToFileURL } from 'node:url';
6+
import { afterAll, beforeAll, describe, expect, it } from 'vite-plus/test';
7+
8+
const ENTRY = join(import.meta.dirname, '..', '..', 'src', 'index.ts');
9+
10+
let root: string;
11+
12+
beforeAll(() => {
13+
root = mkdtempSync(join(tmpdir(), 'create-void-entry-'));
14+
});
15+
16+
afterAll(() => {
17+
rmSync(root, { recursive: true, force: true });
18+
});
19+
20+
describe('create-void entry', () => {
21+
it('prints the runtime message before any other module links', () => {
22+
// An old Node fails to link a module that imports a newer API (for example `styleText`
23+
// from node:util in the bundled prompts). The hook makes every module other than the
24+
// entry and the runtime check fail the same way, so the message must come first.
25+
const preload = join(root, 'old-node.mjs');
26+
writeFileSync(
27+
preload,
28+
`import { registerHooks } from 'node:module';
29+
Object.defineProperty(process, 'versions', { value: { ...process.versions, node: '18.20.8' } });
30+
const allowed = [${JSON.stringify(pathToFileURL(ENTRY).href)}, ${JSON.stringify(
31+
pathToFileURL(join(ENTRY, '..', 'runtime-support.ts')).href,
32+
)}];
33+
registerHooks({
34+
resolve(specifier, context, next) {
35+
const result = next(specifier, context);
36+
if (!allowed.includes(result.url)) {
37+
throw new SyntaxError('cannot link ' + result.url);
38+
}
39+
return result;
40+
},
41+
});
42+
`,
43+
);
44+
const result = spawnSync(
45+
process.execPath,
46+
['--import', pathToFileURL(preload).href, ENTRY, 'my-app'],
47+
{ cwd: root, encoding: 'utf8', env: { PATH: process.env.PATH } },
48+
);
49+
50+
expect(result.status).toBe(1);
51+
expect(result.stderr.split('\n')[0]).toBe(
52+
`create-void: Node.js 24.22+ or 26.12+ is required. Found Node.js v18.20.8 (${process.execPath}).`,
53+
);
54+
expect(readdirSync(root)).not.toContain('my-app');
55+
});
56+
});

0 commit comments

Comments
 (0)