@runeditrun/rer 0.2.33 → 0.2.35

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/README.md CHANGED
@@ -6,14 +6,25 @@ checkout always gets the behaviour it was built and tested with.
6
6
 
7
7
  ## Install
8
8
 
9
- Start a seed from an empty folder with one command:
9
+ Start a seed from an empty folder, with or without Node:
10
+
11
+ ```sh
12
+ curl -fsSL https://runeditrun.com/install.sh | sh
13
+ rer dev just-every/run-inkwell
14
+ ```
15
+
16
+ The installer needs no Node: without Node 22 or later on PATH it installs a
17
+ private one for `rer` (see below). It edits no shell profile, so when
18
+ `~/.local/bin` is not on PATH, run the `export PATH=…` line it prints before
19
+ `rer dev`. Its last line names that next command. The same start also fits on
20
+ one line:
10
21
 
11
22
  ```sh
12
- npx -y @runeditrun/rer dev just-every/run-inkwell
13
23
  curl -fsSL https://runeditrun.com/install.sh | sh -s -- dev just-every/run-inkwell
24
+ npx -y @runeditrun/rer dev just-every/run-inkwell # only with Node 22 or later on PATH
14
25
  ```
15
26
 
16
- Both install the user CLI, clone into `./run-inkwell`, install dependencies, set
27
+ Each of these installs the user CLI, clones into `./run-inkwell`, install dependencies, set
17
28
  up a local owner and start the app. Open the printed `RER_OPEN` link to sign in.
18
29
  Use `setup <repo>` to stop after setup, or `install <repo>` to stop after
19
30
  dependency installation; each prints the next command. The repo can be
@@ -27,9 +38,9 @@ leaves the app running. The restart command includes `cd` into the checkout.
27
38
  Install `rer` with one of these commands:
28
39
 
29
40
  ```sh
30
- npx -y @runeditrun/rer cli install # user install in ~/.local/share/rer, launcher ~/.local/bin/rer
31
- curl -fsSL https://runeditrun.com/install.sh | sh # the same user install, without npm
32
- npm install -g @runeditrun/rer # npm's own global layout
41
+ curl -fsSL https://runeditrun.com/install.sh | sh # user install in ~/.local/share/rer, launcher ~/.local/bin/rer; no Node needed
42
+ npx -y @runeditrun/rer cli install # the same user install, with Node 22 or later on PATH
43
+ npm install -g @runeditrun/rer # npm's own global layout, with Node 22 or later on PATH
33
44
  ```
34
45
 
35
46
  `install.sh` is the file at the root of this package. It reads the version, the
@@ -44,7 +55,10 @@ With no Node 22 or later on PATH, the script installs Node 22.20.0 from
44
55
  `nodejs.org` into `~/.local/share/rer/runtimes` (under `XDG_DATA_HOME` when set),
45
56
  verifies the tarball against that release's published `SHASUMS256.txt`, and
46
57
  prints its location. The launcher uses this private runtime on later runs.
47
- System Node and other PATH directories are left alone.
58
+ System Node and other PATH directories are left alone: the private runtime's
59
+ `node`, `npm` and `npx` are not put on PATH, because `rer` is the one command
60
+ the installer provides. With no arguments the script ends by naming the next
61
+ command, `rer dev <owner>/<repo>`.
48
62
 
49
63
  No installer edits shell profiles. The canonical launcher is `~/.local/bin/rer`.
50
64
  Installation creates that directory if needed and never writes into another
package/cli/bounded.mjs CHANGED
@@ -68,7 +68,7 @@ export async function boundedCommand(project,options,argv,out){
68
68
  }else if(finalEvent&&finalEvent.exitCode===exitCode){
69
69
  if(errorEvent){
70
70
  let deployment={};
71
- try{deployment=JSON.parse(store.redact(JSON.stringify({environment:errorEvent.environment,availableDeployments:errorEvent.availableDeployments})));}catch{}
71
+ try{deployment=JSON.parse(store.redact(JSON.stringify({environment:errorEvent.environment,availableDeployments:errorEvent.availableDeployments,step:errorEvent.step})));}catch{}
72
72
  out.error(new RerError(errorEvent.code,store.redact(errorEvent.message),exitCode,deployment));
73
73
  }
74
74
  const {version,verb,event,ok,exitCode:childExit,...details}=finalEvent;
@@ -3,7 +3,7 @@
3
3
  // launches a browser or downloads anything.
4
4
  import { access, constants } from 'node:fs/promises';
5
5
  import { createRequire } from 'node:module';
6
- import { dirname, join } from 'node:path';
6
+ import { dirname, join, relative } from 'node:path';
7
7
  import { RerError } from './errors.mjs';
8
8
  import { shared } from './shared.mjs';
9
9
 
@@ -59,7 +59,7 @@ export async function ensureChromium(root, store, signal, { required = true } =
59
59
  const { dependencyEnvironment } = await shared('dependency-environment.mjs');
60
60
  const env = dependencyEnvironment();
61
61
  if (process.env.PLAYWRIGHT_BROWSERS_PATH !== undefined) env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH;
62
- await store.run('Installing Chromium and its headless shell from the checkout’s Playwright', 'pnpm', ['exec', 'node', cli, 'install', 'chromium'], { cwd: root, signal, env });
62
+ await store.run('Installing Chromium and its headless shell from the checkout’s Playwright', 'pnpm', ['exec', 'node', cli, 'install', 'chromium'], { cwd: root, signal, env, display: `pnpm exec node ${relative(root, cli)} install chromium` });
63
63
  const after = await browserDoctor(root);
64
64
  if (!after.ok) throw new RerError('browser_install_incomplete', after.issue, 3);
65
65
  }
@@ -1,10 +1,11 @@
1
- import { spawn } from 'node:child_process';
2
1
  import { readFile } from 'node:fs/promises';
3
2
  import { join } from 'node:path';
4
3
  import { fileURLToPath } from 'node:url';
5
4
  import { shared } from './shared.mjs';
6
5
 
7
- export async function demoBundle(project, operation, declaration, output) {
6
+ // The build runs as a captured command: its output, including the reason it
7
+ // failed, reaches the terminal and the capture log, and a failure says so.
8
+ export async function demoBundle(project, operation, declaration, output, store, label, signal) {
8
9
  const { root } = project;
9
10
  const { withoutLocalVariables } = await shared('local/build.mjs');
10
11
  const { buildEnvironment } = await shared('local/environment.mjs');
@@ -12,12 +13,8 @@ export async function demoBundle(project, operation, declaration, output) {
12
13
  const declared = Array.isArray(seed.env) ? seed.env.map(item => item.name) : Object.keys(seed.env ?? {});
13
14
  await withoutLocalVariables(root, async () => {
14
15
  const builder = fileURLToPath(new URL('../modules/demo-host/build.mjs', import.meta.url));
15
- const child = spawn(process.execPath, [builder, root, output, JSON.stringify(declaration)], {
16
- cwd: root, stdio: 'inherit', env: buildEnvironment([...declared, ...(declaration.secrets ?? []).flatMap(item => [item.binding, item.environment])]),
16
+ await store.run(label, process.execPath, [builder, root, output, JSON.stringify(declaration)], {
17
+ cwd: root, signal, phase: 'build', env: buildEnvironment([...declared, ...(declaration.secrets ?? []).flatMap(item => [item.binding, item.environment])]),
17
18
  });
18
- const abort = () => child.kill('SIGTERM');
19
- process.once('SIGTERM', abort); process.once('SIGINT', abort);
20
- try { await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', code => code === 0 ? resolve() : reject(new Error('Demo build failed'))); }); }
21
- finally { process.off('SIGTERM', abort); process.off('SIGINT', abort); if (child.exitCode === null && child.signalCode === null) child.kill('SIGTERM'); }
22
19
  }, { nested: operation.token, settings: [...(project.adapter?.settings ?? []), ...(project.privateInputs ?? [])] });
23
20
  }
@@ -4,7 +4,7 @@ import { createRequire } from 'node:module';
4
4
  import { randomBytes } from 'node:crypto';
5
5
  import { demoBundle } from './demo-build.mjs';
6
6
  import { upgradeDemo } from '../modules/demo-host/upgrade.mjs';
7
- import { missing, invalid } from './errors.mjs';
7
+ import { missing, invalid, RerError } from './errors.mjs';
8
8
  import { DEMO_FILES } from '../modules/demo-host/plan.mjs';
9
9
  import { cloudflare } from '../modules/deploy-kit/provider.mjs';
10
10
  import { demoBucketName, prepareBucket } from '../modules/demo-host/native/deploy-r2.mjs';
@@ -17,15 +17,23 @@ export async function nativeDemoCommand(project, options, store, signal, out, op
17
17
  const folder = join(project.root, '.rer/demo-host');
18
18
  await rm(folder, { recursive: true, force: true });
19
19
  await mkdir(join(folder, 'modules/demo-host/native'), { recursive: true, mode: 0o700 });
20
- await store.step('Building the native demo Worker bundle and static assets');
21
- await demoBundle(project, operation, app, join(folder, 'bundle'));
20
+ const label = 'Building the native demo Worker bundle and static assets';
21
+ await store.step(label);
22
+ await demoBundle(project, operation, app, join(folder, 'bundle'), store, label, signal);
22
23
  for (const file of DEMO_FILES) await cp(new URL(`../modules/demo-host/${file}`, import.meta.url), join(folder, 'modules/demo-host', file));
23
24
  for (const file of RUNTIME_FILES) await cp(new URL(`../modules/demo-host/native/${file}.mjs`, import.meta.url), join(folder, `modules/demo-host/native/${file}.mjs`));
24
25
  for (const directory of ['deploy-kit']) await cp(new URL(`../modules/${directory}/`, import.meta.url), join(folder, 'modules', directory), { recursive: true });
25
26
  await mkdir(join(folder, 'modules/container'), { recursive: true });
26
27
  for (const file of ['migrations.mjs', 'demo-egress.mjs']) await cp(new URL(`../modules/container/${file}`, import.meta.url), join(folder, 'modules/container', file));
27
28
  // Runtime imports use the same module topology as the maintained source.
28
- const bundle = await prepareNative(folder);
29
+ let bundle;
30
+ try { bundle = await prepareNative(folder); }
31
+ catch (error) {
32
+ // The reason (a refused module names its file) goes to the output and the capture log.
33
+ const reason = store.redact(`${label} failed: ${error.message}`);
34
+ store.report(reason);
35
+ throw new RerError('command_failed', reason, 1);
36
+ }
29
37
  const config = { ...plan.wrangler, main: 'modules/demo-host/native/worker.mjs', compatibility_flags: ['nodejs_compat'],
30
38
  assets: { directory: './assets', binding: 'ASSETS', run_worker_first: true }, worker_loaders: [{ binding: 'LOADER' }],
31
39
  };
@@ -17,6 +17,7 @@ import { localOnlyBinding, ownerWorkerName } from '../modules/deploy-kit/owner.m
17
17
  import { refuseLocalModels } from '../modules/deploy-kit/local-only.mjs';
18
18
  import { migrationFailure, providerFailure, assetFailure } from '../modules/deploy-kit/diagnostics.mjs';
19
19
  import { shared } from './shared.mjs';
20
+ import { deployGuide, neededForRealDeploy, reportNeeded } from './deploy-needs.mjs';
20
21
 
21
22
  export function validateDeployOptions(options) {
22
23
  const changes = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret'].filter(Boolean);
@@ -59,11 +60,20 @@ export async function deployCommand(context) {
59
60
  }
60
61
  const local = localOnlyBinding(declaration, localOnlyKeys);
61
62
  if (local) throw refuse(`${path} names the local-only key ${local} as a deploy binding or secret. Remove it; local dev keys never reach a deployment.`);
63
+ deployGuide(declaration);
64
+ const settings = adapter.hooks?.secrets ?? adapter.settings;
65
+ // What a dry run went ahead without, listed when it completes.
66
+ const dryRun = async result => {
67
+ const production = await deployEnvironment({ root, options, declaration, setupManifest, settings, localOnlyKeys });
68
+ const { signIn } = await requireProductionAuth({ root, declaration, env: production.env, setupManifest, setupSeed: context.setupSeed, adapter, declarationPath: path, options }) ?? {};
69
+ const needed = neededForRealDeploy({ declaration, env: production.env, signIn });
70
+ reportNeeded(store, needed);
71
+ return needed.length && result && typeof result === 'object' ? { ...result, neededForRealDeploy: needed } : result;
72
+ };
62
73
  // Custom hooks historically ignored these flags. Only the ownership controller
63
74
  // may perform them; neither a build nor a custom upload runs here.
64
75
  if (options.remove || options.setSecret || options.unsetSecret) return ownerDeploy(path, adapter)(context);
65
- if (adapter.deploy.managesHostedOwner) return adapter.deploy(context);
66
- const settings = adapter.hooks?.secrets ?? adapter.settings;
76
+ if (adapter.deploy.managesHostedOwner) { const result = await adapter.deploy(context); return options.dryRun ? dryRun(result) : result; }
67
77
  const production = await deployEnvironment({ root, options, declaration, setupManifest, settings, localOnlyKeys });
68
78
  await requireProductionAuth({ root, declaration, env: production.env, setupManifest, setupSeed: context.setupSeed, adapter, declarationPath: path, options });
69
79
  const sourceSha = options.dryRun ? undefined : committedSource(root, options);
@@ -99,7 +109,7 @@ export async function deployCommand(context) {
99
109
  Object.assign(process.env, saved);
100
110
  }
101
111
  hookReturned = true;
102
- if (options.dryRun) return deployed;
112
+ if (options.dryRun) return dryRun(deployed);
103
113
  await rememberHookState(root, environment, deployed?.state);
104
114
  hookRecord = await hookState(root, environment);
105
115
  const origin = hookOrigin(deployed, deployAgain(options));
@@ -0,0 +1,59 @@
1
+ import { invalid } from './errors.mjs';
2
+
3
+ export const cloudflareCredentials = ['CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN'];
4
+ const tokenPage = 'https://dash.cloudflare.com/profile/api-tokens';
5
+ // The account permissions the deploy kit's requests need, by what the declaration uses.
6
+ const permissions = [
7
+ ['Workers Scripts: Edit', () => true],
8
+ ['D1: Edit', declaration => declaration.d1?.length],
9
+ ['Workers R2 Storage: Edit', declaration => declaration.r2?.length],
10
+ ['Workers KV Storage: Edit', declaration => declaration.kv?.length],
11
+ ['Queues: Edit', declaration => declaration.queues?.length],
12
+ ];
13
+
14
+ // A project may name its own deploy guide in deploy.json: an https page a stranger can open.
15
+ export function deployGuide(declaration) {
16
+ const value = declaration?.deployGuide;
17
+ if (value === undefined) return undefined;
18
+ let url;
19
+ try { url = new URL(value); } catch {}
20
+ if (typeof value !== 'string' || url?.protocol !== 'https:' || url.username || url.password) throw invalid('deploy.json deployGuide must be an https URL of the project\'s deploy guide, without credentials.');
21
+ return value;
22
+ }
23
+
24
+ // Where a person gets the Cloudflare values: the project's guide, else the token page and the permissions.
25
+ function credentialHelp(declaration) {
26
+ const guide = deployGuide(declaration);
27
+ if (guide) return [`Follow this project's deploy guide: ${guide}`];
28
+ const needed = permissions.filter(([, used]) => used(declaration)).map(([name]) => name);
29
+ return [`Create an account API token at ${tokenPage} with these account permissions: ${needed.join(', ')}. Copy your account ID from the Cloudflare dashboard.`];
30
+ }
31
+
32
+ export function missingCredentialsMessage(declaration, env) {
33
+ const absent = cloudflareCredentials.filter(name => !env[name]?.trim());
34
+ return [`${absent.join(' and ')} ${absent.length > 1 ? 'are' : 'is'} required to deploy to your Cloudflare account. Nothing was deployed.`,
35
+ ...credentialHelp(declaration),
36
+ 'Set them in your environment or an owned 0600 --env-file, then run the same deploy command again.'].join('\n');
37
+ }
38
+
39
+ // What a dry run went ahead without: the Cloudflare values, each required
40
+ // declared secret not supplied, and production sign-in's missing mail inputs.
41
+ export function neededForRealDeploy({ declaration, env, signIn }) {
42
+ const declared = (Array.isArray(declaration.secrets) ? declaration.secrets : []).filter(item => item?.environment);
43
+ // Sign-in names its inputs by binding; a person sets the environment name the declaration maps to it.
44
+ const mail = signIn && declared.reduce((text, item) => item.binding === item.environment ? text : text.replace(new RegExp(`\\b${item.binding}\\b`, 'g'), item.environment), signIn);
45
+ const listed = name => cloudflareCredentials.includes(name) || mail && new RegExp(`\\b${name}\\b`).test(mail);
46
+ const secrets = [...new Set(declared.filter(item => !item.optional && !env[item.environment]?.trim()).map(item => item.environment))].filter(name => !listed(name));
47
+ const credentials = cloudflareCredentials.filter(name => !env[name]?.trim());
48
+ return [
49
+ ...(credentials.length ? [`${credentials.join(' and ')} (${credentialHelp(declaration).join(' ')})`] : []),
50
+ ...secrets,
51
+ ...(mail ? [`production sign-in mail: ${mail}`] : []),
52
+ ];
53
+ }
54
+
55
+ export function reportNeeded(store, needed) {
56
+ if (!needed.length) return;
57
+ store.report('Needed for a real deploy (this dry run went ahead without them):');
58
+ for (const item of needed) store.report(` - ${item}`);
59
+ }
package/cli/deploy.mjs CHANGED
@@ -14,6 +14,7 @@ import { mutationReadinessFailure } from './deploy-readiness.mjs';
14
14
  import { committedSource } from './deploy-source.mjs';
15
15
  import { hookState, forgetHookState } from './deploy-hook-record.mjs';
16
16
  import { deploymentRecord } from './deployment-record.mjs';
17
+ import { cloudflareCredentials, missingCredentialsMessage } from './deploy-needs.mjs';
17
18
 
18
19
  export function ownerDeploy(declarationPath, lifecycle) {
19
20
  // rer verify serves the build with this declaration's vars and secrets.
@@ -47,12 +48,13 @@ export function ownerDeploy(declarationPath, lifecycle) {
47
48
  const worker = ownerWorkerName(declaration.project, environment);
48
49
  const artifact = await packageBuild({ root, source: { sha: '0'.repeat(40), tree: '0'.repeat(40) }, runIdentity: { id: '0', attempt: '1' }, productDirectory: '' });
49
50
  ownerPlan({ project: declaration.project, environment, worker, origin: `https://${worker}.example.invalid` }, declaration, artifact, { localOnlyKeys, env: production.env });
51
+ const optional = (Array.isArray(declaration.secrets) ? declaration.secrets : []).filter(item => item?.optional && !production.env[item.environment]?.trim()).map(item => item.binding);
52
+ if (optional.length) store.report(`deploy: optional secrets not supplied: ${optional.join(', ')}. A Worker that does not hold one deploys without it.`);
50
53
  store.report('deploy: dry run complete; no deployment occurred and no provider request was made.');
51
54
  return { dryRun: true, deployed: false };
52
55
  }
53
56
  const { env, supplied } = await deployEnvironment({ root, options, declaration, setupManifest, settings: lifecycle.settings, localOnlyKeys });
54
- const names = ['CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN'];
55
- if (names.some(name => !env[name]?.trim())) throw missing('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required. See the deploy-kit owner-account instructions.');
57
+ if (cloudflareCredentials.some(name => !env[name]?.trim())) throw missing(missingCredentialsMessage(declaration, env));
56
58
  const { main } = await import('../modules/deploy-kit/owner-cli.mjs');
57
59
  const { createRedaction, credentialValues } = await shared('redaction.mjs');
58
60
  const redaction = createRedaction();
@@ -84,6 +86,7 @@ export function ownerDeploy(declarationPath, lifecycle) {
84
86
  deployed = await owner('deploy', [], env, { notice: line => store.report(line), onCreated: resource => created.push(redaction.redact(resource)) });
85
87
  const sent = supplied.filter(name => deployed.sentSecrets.includes(name));
86
88
  if (sent.length) store.report(`rer supplied ${sent.join(', ')} from the local setup owner and fresh generated values.`);
89
+ if (deployed.optionalUnset) store.report(`Optional secrets not set: ${deployed.optionalUnset.join(', ')}. The application runs without them; set one later with ${again} --set-secret NAME.`);
87
90
  step = 'health';
88
91
  await owner('health', [], env, {propagation:deployed.propagation});
89
92
  step = 'claim owner';
@@ -0,0 +1,15 @@
1
+ // The one line a finished export ends with: the archive, its size and what it holds.
2
+ export function exportSummary({ output, bytes, tables } = {}) {
3
+ if (typeof output !== 'string' || !Number.isSafeInteger(bytes) || !Array.isArray(tables)) return undefined;
4
+ const rows = tables.reduce((sum, table) => sum + (Number.isSafeInteger(table?.count) ? table.count : 0), 0);
5
+ return `Exported ${output} (${size(bytes)}): ${counted(tables.length, 'table')}, ${counted(rows, 'row')}`;
6
+ }
7
+
8
+ const counted = (value, noun) => `${value.toLocaleString('en-US')} ${noun}${value === 1 ? '' : 's'}`;
9
+
10
+ function size(bytes) {
11
+ const units = ['B', 'KB', 'MB', 'GB', 'TB'];
12
+ let value = bytes, unit = 0;
13
+ while (value >= 1000 && unit < units.length - 1) { value /= 1000; unit++; }
14
+ return `${unit && value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
15
+ }
package/cli/lifecycle.mjs CHANGED
@@ -89,9 +89,13 @@ async function runLifecycle(project, options, out, deployRedaction) {
89
89
  // The hosted demo: a native Worker Loader host on demo.<domain>.
90
90
  if (options.verb === 'deploy' && options.demo) return await (await import('./demo-host.mjs')).demoHostCommand(project, options, store, signal, out, operation);
91
91
  if (options.verb === 'install') {
92
- const { dependencyEnvironment } = await shared('dependency-environment.mjs');
93
- await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...dependencyEnvironment(), CI: 'true' } });
94
- await ensureChromium(project.root, store, signal, { required: false }); return {};
92
+ try {
93
+ const { dependencyEnvironment } = await shared('dependency-environment.mjs');
94
+ await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...dependencyEnvironment(), CI: 'true' }, display: 'pnpm install --frozen-lockfile' });
95
+ // Inspecting the checkout's Playwright is its own step, before any download command.
96
+ state.step = 'Checking the checkout’s Playwright browsers';
97
+ await ensureChromium(project.root, store, signal, { required: false }); return {};
98
+ } catch (error) { if (signal.aborted) throw error; throw await installStepError(error, store, project.root); }
95
99
  }
96
100
  if (options.verb === 'verify') {
97
101
  const target = adapter.verify;
@@ -157,6 +161,17 @@ async function runLifecycle(project, options, out, deployRedaction) {
157
161
  }
158
162
  }
159
163
 
164
+ // A failed install step names itself: its command, exit code, last output and
165
+ // full log. A step that stopped outside a command still names the step and log.
166
+ async function installStepError(error, store, root) {
167
+ const { approvedFailure } = await shared('failures.mjs');
168
+ const { checkoutPath, stepDiagnostic, stepFailureText } = await shared('step-failure.mjs');
169
+ const step = approvedFailure(error)?.step ?? stepDiagnostic({ name: store.state.step, output: store.state.logs, log: store.redact(checkoutPath(root, store.logPath)) });
170
+ // Only a RerError's message or a symbolic error code is safe to show; a native message can hold private data.
171
+ const cause = error instanceof RerError ? `\n${error.message}` : /^[A-Z][A-Z0-9_]{1,63}$/.test(error?.code ?? '') ? `\nCause: ${error.code}` : '';
172
+ return new RerError(error instanceof RerError ? error.code : 'install_step_failed', `${stepFailureText(step)}${cause}`, error instanceof RerError ? error.exitCode : 1, { step, ...(Number.isInteger(step.exitCode) ? { childExitCode: step.exitCode, signal: step.signal } : {}) });
173
+ }
174
+
160
175
  // Under the local operation, before the app starts: the zero-setup owner's
161
176
  // row and saved owner setting become the real owner's, and one line says so.
162
177
  async function replaceOwner(project, options, out) {
package/cli/output.mjs CHANGED
@@ -1,4 +1,5 @@
1
1
  import { handleBrokenPipes } from './stdio.mjs';
2
+ import { exportSummary } from './export-summary.mjs';
2
3
  export function output(options) {
3
4
  handleBrokenPipes();
4
5
  let finished = false;
@@ -16,10 +17,12 @@ export function output(options) {
16
17
  result(ok, exitCode, details = {}) {
17
18
  if (finished) throw Error('Duplicate CLI result'); finished = true;
18
19
  if (structuredResult) this.event('result', { ok, exitCode, ...details });
20
+ // A finished export ends with one line naming its archive; the receipt is --json data.
21
+ else if (ok && options.verb === 'export' && exportSummary(details)) this.human(exportSummary(details));
19
22
  else if (!['describe', 'check', 'dev', 'preview', 'setup'].includes(options.verb) || !ok) this.human(`${options.verb}: ${ok ? 'complete' : 'failed'} (exit ${exitCode})`);
20
23
  },
21
24
  error(error) {
22
- if (structuredResult) this.event('error', { code: error.code, message: error.message, exitCode: error.exitCode, ...(error.availableDeployments ? { environment: error.environment, availableDeployments: error.availableDeployments } : {}) });
25
+ if (structuredResult) this.event('error', { code: error.code, message: error.message, exitCode: error.exitCode, ...(error.availableDeployments ? { environment: error.environment, availableDeployments: error.availableDeployments } : {}), ...(error.step ? { step: error.step } : {}) });
23
26
  else write(2, error.message + '\n');
24
27
  },
25
28
  };
@@ -6,7 +6,7 @@ import { legacyTargetState, requireLegacyEmpty } from '../modules/portability/le
6
6
  import { migrationReplay } from '../modules/portability/migration-history.mjs';
7
7
  import { appliedMigrations as appliedMigrationNames } from '../modules/portability/bridge.mjs';
8
8
  import { join } from 'node:path';
9
- import { readFile } from 'node:fs/promises';
9
+ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
10
10
  import { createRequire } from 'node:module';
11
11
  import { createPortability, PortabilityError, readArchive } from '../modules/portability/index.mjs';
12
12
  import { parseJsonc } from './jsonc.mjs';
@@ -21,6 +21,17 @@ async function appliedMigrations(root, db, binding, split) {
21
21
  return Promise.all(names.map(async name => ({ name, statements: split(await readFile(join(directory, name), 'utf8')) })));
22
22
  }
23
23
 
24
+ // Transfers read only the D1 database and R2 buckets. A configuration with just
25
+ // those keeps the app's other bindings out of the proxy: a Durable Object class
26
+ // it cannot export otherwise makes workerd print a warning on every transfer.
27
+ async function dataConfiguration(root) {
28
+ const config = parseJsonc(await readFile(join(root, 'wrangler.jsonc'), 'utf8'));
29
+ const directory = join(root, '.wrangler'), path = join(directory, `rer-portability-${process.pid}.json`);
30
+ await mkdir(directory, { recursive: true });
31
+ await writeFile(path, JSON.stringify(Object.fromEntries(['name', 'compatibility_date', 'compatibility_flags', 'd1_databases', 'r2_buckets'].filter(key => config[key] !== undefined).map(key => [key, config[key]]))), { mode: 0o600 });
32
+ return path;
33
+ }
34
+
24
35
  async function run(direction, { root, path, journal, binding, buckets, policy, policyModule, transient, legacyRecovery }) {
25
36
  // Validate all inputs before opening bindings or acquiring a restore lock.
26
37
  if (direction === 'import') {
@@ -32,8 +43,10 @@ async function run(direction, { root, path, journal, binding, buckets, policy, p
32
43
  const { getPlatformProxy, unstable_splitSqlQuery } = createRequire(join(root, 'package.json'))('wrangler');
33
44
 
34
45
  // Unlike Wrangler's --persist-to base, the API takes the versioned directory.
35
- const proxy = await getPlatformProxy({ configPath: join(root, 'wrangler.jsonc'), persist: { path: join(root, '.wrangler/state/v3') }, remoteBindings: false });
46
+ const configPath = await dataConfiguration(root);
47
+ let proxy;
36
48
  try {
49
+ proxy = await getPlatformProxy({ configPath, persist: { path: join(root, '.wrangler/state/v3') }, remoteBindings: false });
37
50
  const migrations=async()=>migrationReplay(await appliedMigrations(root,proxy.env[binding],binding,unstable_splitSqlQuery),policy);
38
51
  const options={ db: proxy.env[binding], buckets: Object.fromEntries(Object.entries(buckets).map(([name, binding]) => [name, proxy.env[binding]])), policy, migrations };
39
52
  if(direction==='legacy-preflight') {
@@ -44,10 +57,12 @@ async function run(direction, { root, path, journal, binding, buckets, policy, p
44
57
  if(legacyRecovery)return await recoverLegacyArchive(options,path,legacyRecovery.output,transient,legacyRecovery.acknowledged);
45
58
  const service = await createPortability(options);
46
59
  return await (direction === 'export' ? exportArchive(service,path,transient) : importArchive(service,path,transient,journal));
47
- } finally { await proxy.dispose(); }
60
+ } finally { await proxy?.dispose(); await rm(configPath, { force: true }); }
48
61
  }
49
62
 
50
- try { console.log(JSON.stringify({ ok: true, ...await run(process.argv[2], JSON.parse(process.argv[3])) })); }
63
+ // The receipt goes to the CLI over IPC: nothing it holds reaches the terminal.
64
+ const reply = message => new Promise(resolve => process.send(message, () => { process.disconnect(); resolve(); }));
65
+ try { await reply({ ok: true, ...await run(process.argv[2], JSON.parse(process.argv[3])) }); }
51
66
  catch (error) {
52
67
  // Erasure-fence refusals name the fence: an older archive is refused, not a failed transfer.
53
68
  const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal', 'staged_validation'].includes(error.code.split(':')[0]));
@@ -56,5 +71,6 @@ catch (error) {
56
71
  const reason = error instanceof PortabilityError ? error.code.split(':')[0] : /^[A-Z_]+$/.test(error.code ?? '') ? error.code : error.message === 'archive_json' ? 'archive_json' : 'native_error';
57
72
  // A later migration that changes restorable data is named: it is a file of this installation.
58
73
  const migration = error instanceof PortabilityError && error.code.startsWith('schema_mismatch:migration_data:') ? error.code.slice('schema_mismatch:migration_data:'.length) : undefined;
59
- console.log(JSON.stringify({ ok: false, code: exitCode === 2 ? 'invalid_archive' : exitCode === 4 ? 'restore_refused' : 'transfer_failed', reason, ...(migration ? { migration } : {}), exitCode })); process.exitCode = exitCode;
74
+ process.exitCode = exitCode;
75
+ await reply({ ok: false, code: exitCode === 2 ? 'invalid_archive' : exitCode === 4 ? 'restore_refused' : 'transfer_failed', reason, ...(migration ? { migration } : {}), exitCode });
60
76
  }
@@ -68,14 +68,14 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
68
68
  async function nativeWorker(store,direction,input,signal) {
69
69
  const worker = fileURLToPath(new URL('./portability-worker.mjs', import.meta.url));
70
70
  const child = store.spawn(`${direction === 'policy-preflight' ? 'Checking archive policy' : direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
71
- [worker, direction, JSON.stringify(input)], { cwd: input.root, signal, env: { ...process.env, WRANGLER_SEND_METRICS: 'false' } });
72
- let output = '';
73
- child.stdout.on('data', chunk => { output += chunk; });
71
+ [worker, direction, JSON.stringify(input)], { cwd: input.root, signal, env: { ...process.env, WRANGLER_SEND_METRICS: 'false' }, stdio: ['ignore', 'pipe', 'pipe', 'ipc'] });
72
+ let receipt;
73
+ child.once('message', message => { receipt = message; });
74
74
  const closed = new Promise(resolve => child.once('close', (code, signal) => resolve({ code, signal })));
75
75
  await new Promise(resolve => { child.once('exit', resolve); child.once('error', resolve); });
76
76
  await store.stop(child);
77
77
  const status = await closed;
78
- let receipt; try { receipt = JSON.parse(output.trim().split('\n').at(-1)); } catch { throw new RerError('transfer_failed', 'Local portability did not return a complete receipt.', 1); }
78
+ if (!receipt || typeof receipt !== 'object') throw new RerError('transfer_failed', 'Local portability did not return a complete receipt.', 1);
79
79
  if (status.code !== 0 || !receipt.ok) throw new RerError(receipt.code ?? 'transfer_failed', receipt.reason==='legacy_restored_export_failed'
80
80
  ? 'Legacy data was restored and audited, but its v2 export failed. Preserve this installation, resolve the output problem, then run rer export --output FILE. Do not reset it to retry recovery.'
81
81
  : receipt.migration ? `Restore refused (schema_mismatch:migration_data): migration ${receipt.migration} changed data after this archive was made, so its rows would skip that change. Restore an archive made after it.`
@@ -28,5 +28,7 @@ export async function requireProductionAuth({ root, declaration, env, setupManif
28
28
  if (dependencies.some(item => {
29
29
  try { const value = answers?.[item.address] ?? bindings[item.address], issuer = new URL(value); return issuer.protocol === 'https:' && issuer.origin === value && !issuer.username && !issuer.password; } catch { return false; }
30
30
  })) return;
31
+ // A dry run goes ahead without the mail inputs and lists them as needed for a real deploy.
32
+ if (options.dryRun) return { signIn: `${mail.missing}${dependencies.length ? ', or an approved Auth SSO install' : ''}` };
31
33
  throw refuse(`Production sign-in is not configured. Configure outbound email; missing or invalid: ${mail.missing}. Or select and approve an Auth SSO install through the declared oidc-provider@1 setup dependency. Local dev and demo use automatic RER_OPEN sign-in. Nothing was built or uploaded.`);
32
34
  }
package/cli/transfers.mjs CHANGED
@@ -1,3 +1,5 @@
1
+ import { stat } from 'node:fs/promises';
2
+ import { relative } from 'node:path';
1
3
  import {localDependencyLinks} from './dependency-doctor.mjs';
2
4
  import { contained } from './project.mjs';
3
5
  import { missing, refuse } from './errors.mjs';
@@ -26,6 +28,8 @@ export async function transfer(project, options, signal, custody) {
26
28
  // Only now can the seed's Vite configuration load in a checkout that never built.
27
29
  await located.unserved(); await legacyOutput?.unserved();
28
30
  const result=await api[direction]({ root: project.root, target, path, journal, origin: options.origin, sessionFile, signal, platform:options.platform, legacyRecovery, ...custody });
31
+ // The archive's size, for the line a finished export ends with.
32
+ if(direction==='export')return {...result,output:result.output??relative(project.root,path),bytes:(await stat(path)).size};
29
33
  if(direction==='import' && target==='local' && (await localDependencyLinks(project.root)).some(link=>link.needs_relink)) {
30
34
  custody.store.report('Imported provider links need fresh approval. Run rer setup with RER_LINK_TOKEN_FILE to re-link this installation.');
31
35
  return {...result,needsRelink:true,nextCommand:'rer setup'};
@@ -1,5 +1,31 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.35
4
+
5
+ - **The Run page starts a seed without Node.** The shared /run page has two steps. Step 1 is `curl -fsSL https://runeditrun.com/install.sh | sh`, which brings its own Node and changes no shell settings. Step 2 is `rer dev <owner>/<repo>`, with `cd <folder> && rer dev` to start it again later. `npx -y @runeditrun/rer dev <owner>/<repo>` remains only as the alternative under "Already have Node 22 or later?". Before this, a newcomer without Node got `sh: npx: command not found` at step 2, because the installer keeps its Node private. Step 2 is built from Run data's existing `clone` line, so seeds need no edits. RUN-LOCALLY, HOMEPAGE-VARIANTS, SEED-COMMAND-CONTRACT and the READMEs describe the two steps, and the default and foundation Run requirements no longer say "Needs Node 22".
6
+ - **install.sh names the next step.** Run with no arguments, `install.sh` now ends with `Next, start a seed: rer dev <owner>/<repo>`. It still puts no `node`, `npm` or `npx` on PATH.
7
+
8
+ ### Upgrade notes
9
+
10
+ - A seed refreshes its copy of the /run page and docs from Base to get the two steps.
11
+ - The installer served at runeditrun.com takes its text from the published package, so the Next line arrives with this release.
12
+
13
+ ## 0.2.34
14
+
15
+ - **Optional deploy secrets.** A deploy declaration's secret entry may add `"optional": true` for an integration's credential (Pier, Stripe). When neither the Worker nor the deploy inputs hold it, the first deploy succeeds without binding it and reports `Optional secrets not set: NAME`, and a dry run names optional secrets that were not supplied. Health waits only for required secrets, and a missing required secret still refuses before any write. `rer deploy --set-secret NAME` and `--unset-secret NAME` record the Worker version they make, so the next deploy accepts that Worker and an unchanged repeat writes nothing. A declaration without `optional` plans and fingerprints exactly as before.
16
+ - **A redeploy waits out a version-readback 404 and resumes on its own fingerprint.** After an upload, a 404 with Cloudflare code 100146 on the read of the version just uploaded is waited out within the existing 90 s readiness window; any other error still fails. If an earlier run lost that readback, the next deploy accepts the live version when it carries the pending upload's fingerprint as both its `RER_DEPLOY_FINGERPRINT` binding and its `rer-deploy:<fingerprint>` annotation, records its ids, and continues, with or without a receipt. Any other live version is still refused. New state files no longer save the pending build hash, and older ones that have it still load.
17
+ - **The Run page leads with the one-line start.** The shared /run page, SEED-COMMAND-CONTRACT, RUN-LOCALLY and HOMEPAGE-VARIANTS lead with `npx -y @runeditrun/rer dev <owner>/<repo>`, then `cd <folder> && rer dev` to start again; the curl and npm global installs stay as the alternative. `foundation initialize` and the template write that line into `run.json`.
18
+ - **Install, export and deploy tell a stranger what happened or is needed.** A failed install step prints `Install step failed: <step>`, its command, exit code, the last 20 lines of output and the checkout path of its full log (`--json`: `error.step`). This covers a pinned `@runeditrun/rer` install, the frozen dependency install and the Playwright browser download. `rer export` no longer prints Durable Object warnings and ends with `Exported <path> (<size>): <n> tables, <rows> rows`; the receipt is the `--json` result. Without Cloudflare values, deploy names deploy.json's new optional `deployGuide` (an https URL), or else the API token page and the account permissions the declaration needs. `--dry-run` goes ahead without mail inputs and OWNER_EMAIL, and lists them under "Needed for a real deploy" (`--json`: `neededForRealDeploy`).
19
+ - **Native demos load WebAssembly and data modules.** A native hosted demo now carries every Worker build module that deploy-kit uploads: `.js`/`.mjs` as JS, `.txt`/`.html`/`.sql` as text, `.wasm` as WebAssembly and `.bin` as data. A type with no Loader kind is refused at `rer deploy --demo`, and the message names the type and the file. A failed demo build prints its reason (the build's exit, its last 40 lines of output and the log path, or the bundle-preparation error naming the file) in the output and in the capture log.
20
+
21
+ ### Upgrade notes
22
+
23
+ - Update the exact rer package pin, or refresh vendored operating commands, to receive these changes.
24
+ - A seed whose integration works without its credential (Barrow and Stall without Pier or Stripe) marks that secret `"optional": true` in its deploy declaration.
25
+ - A project with its own deploy instructions can add `"deployGuide": "https://…"` to deploy.json.
26
+ - A seed refreshes its copy of the /run page and docs from Base to get the one-line start.
27
+ - A hosted demo that kept WebAssembly or data modules out of its Worker build can put them back; they ship on the next `rer deploy --demo`.
28
+
3
29
  ## 0.2.33
4
30
 
5
31
  - **CodeQL-clean mail and logout copies.** mail's `parseAddress`, `parseHeaders` and `messageIds` now parse in linear time, without backtracking regular expressions. Results and error codes are unchanged, and U+2028/U+2029 in a display name or header line is still refused. In dependencies' back-channel logout, the session fence is read from the exact `events` key with `Object.hasOwn`. Seeds that patched these files in their recorded Base copies can now refresh to Base's bytes.
package/global/README.md CHANGED
@@ -6,14 +6,25 @@ checkout always gets the behaviour it was built and tested with.
6
6
 
7
7
  ## Install
8
8
 
9
- Start a seed from an empty folder with one command:
9
+ Start a seed from an empty folder, with or without Node:
10
+
11
+ ```sh
12
+ curl -fsSL https://runeditrun.com/install.sh | sh
13
+ rer dev just-every/run-inkwell
14
+ ```
15
+
16
+ The installer needs no Node: without Node 22 or later on PATH it installs a
17
+ private one for `rer` (see below). It edits no shell profile, so when
18
+ `~/.local/bin` is not on PATH, run the `export PATH=…` line it prints before
19
+ `rer dev`. Its last line names that next command. The same start also fits on
20
+ one line:
10
21
 
11
22
  ```sh
12
- npx -y @runeditrun/rer dev just-every/run-inkwell
13
23
  curl -fsSL https://runeditrun.com/install.sh | sh -s -- dev just-every/run-inkwell
24
+ npx -y @runeditrun/rer dev just-every/run-inkwell # only with Node 22 or later on PATH
14
25
  ```
15
26
 
16
- Both install the user CLI, clone into `./run-inkwell`, install dependencies, set
27
+ Each of these installs the user CLI, clones into `./run-inkwell`, install dependencies, set
17
28
  up a local owner and start the app. Open the printed `RER_OPEN` link to sign in.
18
29
  Use `setup <repo>` to stop after setup, or `install <repo>` to stop after
19
30
  dependency installation; each prints the next command. The repo can be
@@ -27,9 +38,9 @@ leaves the app running. The restart command includes `cd` into the checkout.
27
38
  Install `rer` with one of these commands:
28
39
 
29
40
  ```sh
30
- npx -y @runeditrun/rer cli install # user install in ~/.local/share/rer, launcher ~/.local/bin/rer
31
- curl -fsSL https://runeditrun.com/install.sh | sh # the same user install, without npm
32
- npm install -g @runeditrun/rer # npm's own global layout
41
+ curl -fsSL https://runeditrun.com/install.sh | sh # user install in ~/.local/share/rer, launcher ~/.local/bin/rer; no Node needed
42
+ npx -y @runeditrun/rer cli install # the same user install, with Node 22 or later on PATH
43
+ npm install -g @runeditrun/rer # npm's own global layout, with Node 22 or later on PATH
33
44
  ```
34
45
 
35
46
  `install.sh` is the file at the root of this package. It reads the version, the
@@ -44,7 +55,10 @@ With no Node 22 or later on PATH, the script installs Node 22.20.0 from
44
55
  `nodejs.org` into `~/.local/share/rer/runtimes` (under `XDG_DATA_HOME` when set),
45
56
  verifies the tarball against that release's published `SHASUMS256.txt`, and
46
57
  prints its location. The launcher uses this private runtime on later runs.
47
- System Node and other PATH directories are left alone.
58
+ System Node and other PATH directories are left alone: the private runtime's
59
+ `node`, `npm` and `npx` are not put on PATH, because `rer` is the one command
60
+ the installer provides. With no arguments the script ends by naming the next
61
+ command, `rer dev <owner>/<repo>`.
48
62
 
49
63
  No installer edits shell profiles. The canonical launcher is `~/.local/bin/rer`.
50
64
  Installation creates that directory if needed and never writes into another
@@ -1,8 +1,5 @@
1
1
  // An older checkout pin still runs its own verbs. The installed launcher
2
2
  // supplies the browser prerequisite those pins did not yet provision.
3
- import { mkdtemp, rm } from 'node:fs/promises';
4
- import { tmpdir } from 'node:os';
5
- import { join } from 'node:path';
6
3
  import { browserDoctor, ensureChromium } from '../cli/browser-runtime.mjs';
7
4
  import { output } from '../cli/output.mjs';
8
5
  import { RerError } from '../cli/errors.mjs';
@@ -18,28 +15,37 @@ export async function browserPreflight(root, argv) {
18
15
  out.result(false, 3, { diagnostics });
19
16
  return 3;
20
17
  }
18
+ // Installed browsers need no download, and no log.
19
+ if ((await browserDoctor(root).catch(() => ({ ok: false }))).ok) return;
21
20
  const cancellation = new AbortController();
22
- let directory, store, termination;
21
+ const state = { logs: [], step: 'Checking the checkout’s Playwright browsers' };
22
+ let store, termination;
23
23
  const handlers = new Map(['SIGINT', 'SIGTERM'].map(name => [name, () => { termination ??= name; cancellation.abort(name); }]));
24
24
  for (const [name, handler] of handlers) process.on(name, handler);
25
25
  try {
26
- directory = await mkdtemp(join(tmpdir(), 'rer-browser-'));
26
+ // The browser download's full output stays in the checkout's private installer log.
27
+ const { privateDirectory } = await shared('private-files.mjs');
27
28
  const { createCommands } = await shared('commands.mjs');
28
- store = await createCommands(directory, { logs: [] }, { terminal: text => out.progress(text) });
29
+ store = await createCommands(await privateDirectory(root, ['.seed', 'installer', `browser-${process.pid}`]), state, { terminal: text => out.progress(text) });
29
30
  store.setCommandSignal(cancellation.signal);
30
31
  // A fresh vendored pin installs its own dependencies; verify will acquire
31
32
  // their browser on first need. Package pins have already been bootstrapped.
32
33
  await ensureChromium(root, store, cancellation.signal, { required: verb === 'verify' });
33
34
  } catch (error) {
34
- const failure = error instanceof RerError ? error : new RerError('browser_install_failed', `The checkout's Chromium installation failed. Run rer install to retry; inspect the browser download progress for the cause.`, 1);
35
- if (termination) { failure.exitCode = termination === 'SIGINT' ? 130 : 143; failure.message = `Stopped by ${termination} after owned children were stopped.`; }
35
+ const failure = termination ? new RerError('cancelled', `Stopped by ${termination} after owned children were stopped.`, termination === 'SIGINT' ? 130 : 143) : await browserStepError(error, store, state, root);
36
36
  out.error(failure); out.result(false, failure.exitCode);
37
37
  return failure.exitCode;
38
38
  } finally {
39
39
  try { await store?.closeCommands(); }
40
- finally {
41
- if (directory) await rm(directory, { recursive: true, force: true });
42
- for (const [name, handler] of handlers) process.removeListener(name, handler);
43
- }
40
+ finally { for (const [name, handler] of handlers) process.removeListener(name, handler); }
44
41
  }
45
42
  }
43
+
44
+ // The failed browser step names itself, its command, exit code, last output and log.
45
+ async function browserStepError(error, store, state, root) {
46
+ const { approvedFailure } = await shared('failures.mjs');
47
+ const { checkoutPath, stepDiagnostic, stepFailureText } = await shared('step-failure.mjs');
48
+ const step = approvedFailure(error)?.step ?? stepDiagnostic({ name: state.step, output: state.logs, log: store ? store.redact(checkoutPath(root, store.logPath)) : null });
49
+ const cause = error instanceof RerError ? `\n${error.message}` : /^[A-Z][A-Z0-9_]{1,63}$/.test(error?.code ?? '') ? `\nCause: ${error.code}` : '';
50
+ return new RerError(error instanceof RerError ? error.code : 'browser_install_failed', `${stepFailureText(step)}${cause}\nRun rer install to retry.`, error instanceof RerError ? error.exitCode : 1, { step });
51
+ }
@@ -7,7 +7,10 @@
7
7
  // installs only if the pin is still missing once it holds it.
8
8
  import { spawn } from 'node:child_process';
9
9
  import { realpath } from 'node:fs/promises';
10
+ import { join } from 'node:path';
10
11
  import { dependencyEnvironment } from '../../onboarding/dependency-environment.mjs';
12
+ import { openPrivateLog, privateDirectory } from '../../onboarding/private-files.mjs';
13
+ import { checkoutPath, stepDiagnostic, stepFailureText } from '../../onboarding/step-failure.mjs';
11
14
  import { pinnedPackage } from '../checkout.mjs';
12
15
  import { packageName } from '../package-info.mjs';
13
16
  import { ensureProjectPnpm } from '../../cli/project-pnpm.mjs';
@@ -34,17 +37,26 @@ export async function settledPin(root, { env = process.env, output = text => pro
34
37
  await settledPinInstall(await realpath(root), { env, signal, onWait: waiting(root, output) });
35
38
  }
36
39
 
40
+ const installStep = `Installing the pinned ${packageName} and the checkout's frozen dependencies`;
41
+
37
42
  async function install(root, { env, output, children, signal }) {
38
43
  try { await ensureProjectPnpm(root, { env, signal, report: text => output(text + '\n') }); }
39
44
  catch (error) { if (error instanceof RerError) throw new LaunchFailure(error.exitCode, error.message); throw error; }
45
+ // The install keeps its full output in the checkout's private installer log.
46
+ const logPath = join(await privateDirectory(root, ['.seed', 'installer']), 'pin-install.log'), log = await openPrivateLog(logPath);
47
+ output(`${installStep}\n`);
40
48
  const child = spawn('pnpm', ['install', '--frozen-lockfile'], { cwd: root, env: { ...dependencyEnvironment(env), CI: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
41
49
  children?.add(child);
42
50
  if (signal?.aborted) child.kill('SIGTERM');
43
51
  let tail = '';
44
- for (const stream of [child.stdout, child.stderr]) stream.on('data', data => { tail = (tail + data).slice(-4096); output(String(data)); });
45
- const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('close', (exit, name) => resolve(exit ?? (name ? 128 : 1))); });
52
+ for (const stream of [child.stdout, child.stderr]) stream.on('data', data => { tail = (tail + data).slice(-16384); log.write(String(data)); output(String(data)); });
53
+ const { code, name } = await new Promise((resolve, reject) => { child.once('error', reject); child.once('close', (exit, name) => resolve({ code: exit ?? (name ? 128 : 1), name })); }).finally(() => log.close());
46
54
  children?.delete(child);
47
- if (code !== 0) throw new LaunchFailure(code, `pnpm install --frozen-lockfile failed in ${root} (exit ${code}):\n${tail.trim().split('\n').slice(-8).join('\n')}`);
55
+ if (code !== 0) {
56
+ const step = stepDiagnostic({ name: installStep, command: 'pnpm install --frozen-lockfile', exitCode: code, signal: name, output: tail.split('\n'), log: checkoutPath(root, logPath) });
57
+ const message = stepFailureText(step);
58
+ throw new LaunchFailure(code, message, { version: 1, event: 'error', code: 'install_step_failed', message, exitCode: code, step });
59
+ }
48
60
  const pinned = pinnedPackage(root);
49
61
  if (!pinned?.ready) throw new LaunchFailure(3, `${root} pins ${packageName} ${pinned?.declared}, but after pnpm install node_modules holds ${pinned?.installed ?? 'no copy of it'}. Correct the pin or the lockfile (pnpm install), then run rer again.`);
50
62
  }
package/global/main.mjs CHANGED
@@ -126,7 +126,13 @@ export async function main(argv) {
126
126
  if (pinned && !pinned.ready && !argv.includes('--help') && installsFirst.has(verb)) {
127
127
  const { installPinned } = await import('./launch/install-pinned.mjs'), { LaunchFailure } = await import('./launch/failure.mjs');
128
128
  try { await installPinned(target.root); }
129
- catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; process.stderr.write(failure.message + '\n'); return failure.exitCode; }
129
+ catch (failure) {
130
+ if (!(failure instanceof LaunchFailure)) throw failure;
131
+ // A --json caller gets the failed step as data, as the checkout's own verbs report it.
132
+ if (failure.event && target.args.includes('--json')) for (const event of [{ ...failure.event, verb }, { version: 1, verb, event: 'result', ok: false, exitCode: failure.exitCode }]) process.stdout.write(JSON.stringify(event) + '\n');
133
+ else process.stderr.write(failure.message + '\n');
134
+ return failure.exitCode;
135
+ }
130
136
  }
131
137
  if (mode === 'package' && installsFirst.has(verb)) await (await import('./launch/install-pinned.mjs')).settledPin(target.root);
132
138
  if (verb === 'describe' && !argv.includes('--help')) return (await import('./cli/describe.mjs')).describeCommand(target);
package/install.sh CHANGED
@@ -141,11 +141,14 @@ NODE
141
141
  tar -xzf "$work/rer.tgz" -C "$work/stage" || fail "could not unpack rer $version; nothing was installed."
142
142
  RER_INSTALL_CHANNEL=script node "$work/stage/package/global/rer.mjs" cli install </dev/null \
143
143
  || fail "rer cli install failed; any previous install is still selected."
144
- if [ "$#" -gt 0 ]; then
145
- PATH="$HOME/.local/bin:$PATH"
146
- export PATH
147
- "$HOME/.local/bin/rer" "$@"
144
+ if [ "$#" -eq 0 ]; then
145
+ # The same next step a Run page gives; no npx, since Node may be rer's own.
146
+ printf 'Next, start a seed: rer dev <owner>/<repo>\n'
147
+ return
148
148
  fi
149
+ PATH="$HOME/.local/bin:$PATH"
150
+ export PATH
151
+ "$HOME/.local/bin/rer" "$@"
149
152
  }
150
153
 
151
154
  install_node() {
@@ -2,10 +2,15 @@ import { WorkerEntrypoint } from 'cloudflare:workers';
2
2
  import demoEgress from '../../container/demo-egress.mjs';
3
3
  import bundle from './bundle.mjs';
4
4
 
5
+ // wasm and data modules arrive as base64; the Loader takes their bytes.
6
+ const bytes = text => Uint8Array.from(atob(text), char => char.charCodeAt(0)).buffer;
7
+ const modules = Object.fromEntries(Object.entries(bundle.modules).map(([name, module]) =>
8
+ [name, 'wasm' in module ? { wasm: bytes(module.wasm) } : 'data' in module ? { data: bytes(module.data) } : module]));
9
+
5
10
  export function loaded(env, ctx, id, runtime) {
6
11
  return env.LOADER.get(`${bundle.digest}:${id}`, () => ({
7
12
  compatibilityDate: bundle.compatibilityDate, compatibilityFlags: bundle.compatibilityFlags,
8
- mainModule: '_rer/isolate.js', modules: bundle.modules,
13
+ mainModule: '_rer/isolate.js', modules,
9
14
  globalOutbound: ctx.exports.DemoEgress({ props: { id } }),
10
15
  env: { ...runtime, RER_NATIVE_CONFIG: bundle.bindings, RER_NATIVE_HOST: ctx.exports.HostBridge({ props: { id, key: runtime.RER_NATIVE_KEY } }), [bundle.bindings.assets]: ctx.exports.DemoAssets({}) },
11
16
  }));
@@ -2,9 +2,19 @@ import { readFile, writeFile, cp } from 'node:fs/promises';
2
2
  import { resolve, join, relative } from 'node:path';
3
3
  import { createHash } from 'node:crypto';
4
4
  import { collectBuildModules } from '../../deploy-kit/build-modules.mjs';
5
- import { collectFiles } from '../../deploy-kit/artifact.mjs';
5
+ import { collectFiles, moduleType } from '../../deploy-kit/artifact.mjs';
6
6
  import { nativeBindings, ISOLATE_FILES, objectExports } from './config.mjs';
7
7
 
8
+ // The Worker Loader module kind for each upload type deploy-kit gives a build
9
+ // module, so a demo carries what a normal deploy uploads. Binary kinds travel
10
+ // as base64 in the bundle; loader.mjs hands the Loader their bytes.
11
+ const LOADER_KINDS = { 'application/javascript+module': 'js', 'text/plain': 'text', 'application/wasm': 'wasm', 'application/octet-stream': 'data' };
12
+ export function loaderModule(path, bytes) {
13
+ const type = moduleType(path), kind = LOADER_KINDS[type];
14
+ if (!kind) throw new Error(`Loader demo cannot load ${type ?? 'unknown'} module type: ${path}`);
15
+ return { [kind]: ['js', 'text'].includes(kind) ? bytes.toString('utf8') : bytes.toString('base64') };
16
+ }
17
+
8
18
  // Reuse the normal production build and its migration inventory, without
9
19
  // building or running a container. The bundle is stored once in the front.
10
20
  export async function prepareNative(folder) {
@@ -14,12 +24,7 @@ export async function prepareNative(folder) {
14
24
  const bindings = nativeBindings(config);
15
25
  const main = relative(root, resolve(root, config.main));
16
26
  const modules = {};
17
- for (const file of await collectBuildModules(root, config, main)) {
18
- const source = Buffer.from(file.base64, 'base64');
19
- if (/\.(m?js)$/.test(file.path)) modules[`app/${file.path}`] = { js: source.toString('utf8') };
20
- else if (/\.(txt|html|sql)$/.test(file.path)) modules[`app/${file.path}`] = { text: source.toString('utf8') };
21
- else throw new Error(`Loader demo does not implement module type: ${file.path}`);
22
- }
27
+ for (const file of await collectBuildModules(root, config, main)) modules[`app/${file.path}`] = loaderModule(file.path, Buffer.from(file.base64, 'base64'));
23
28
  const entry = `../app/${main}`;
24
29
  modules['_rer/isolate.js'] = { js: (await readFile(new URL('./isolate.mjs', import.meta.url), 'utf8')).replace('__RER_APP_ENTRY__', entry)
25
30
  + objectExports(bindings) };
@@ -100,8 +100,8 @@ Ownership lives in a state file, by default `.rer/deploy/<environment>.json` und
100
100
 
101
101
  - **Find or create.** Before any write, the kit lists every declared kind and checks the Worker. A name it created is reused. An absent name is created. A same-named resource it did not create is refused with `resource-name-collision` and the resource name; it is never adopted. Ownership collisions, missing first-deploy secrets and existing Cron drift fail before the first provider write. Provider failures may interrupt later writes; see partial failure and resume below.
102
102
  - **Re-run.** The same build writes nothing: no create, upload, migration, trigger or secret write, and the state file stays byte-identical. A later release that declares a new resource creates only that resource.
103
- - **Partial failure and resume.** The kit records each create as `pending` before the request and `created` with the provider id after it. A failed create leaves `pending`. On the next run an absent pending name is created again, and a present one is refused as `uncertain-resource-create`, because a lost response cannot prove who created it. Inspect it: if it is the empty resource from the interrupted run, delete it and re-run. A Worker upload is recorded as created when the upload succeeds, so a failure after it resumes with one fresh upload. If the response to the very first upload is lost, the Worker exists but is still `pending`. The kit records the build and its fingerprint before sending an upload. With no prior receipt, the same build may recover its pending Worker only when the live fingerprint matches that intent, then resume with one fresh upload. A different build or fingerprint is refused as `uncertain-resource-create`; recover with the original build first. If the uncertain Worker cannot be authenticated, inspect it and delete it only after confirming that it is the kit-created Worker and that its Durable Object data is disposable. Back up any needed data before deleting it. Migration claims keep the rules under Migration safety.
104
- - **Drift.** A created resource that has gone is refused as `owned-resource-missing`; one replaced under the same name is refused as `owned-resource-replaced`. The kit never deletes or recreates them. This covers D1, KV, Queues and R2 (a bucket is identified by its creation date; a state file written before that was recorded keeps working and is not checked for that bucket). For the Worker, the live deployment (version id, deployment id and etag) must be the last receipt's before any write; someone else's upload under the same name is refused as `owned-resource-replaced` and never overwritten. Immediately before the Worker PUT, the kit rechecks every saved resource identity, including resources omitted from the current plan, then the Worker identity. A replacement during provisioning or asset upload is refused before the upload intent or receipt is saved. An interrupted successful upload may resume only when the live version id, deployment id and etag match the identity saved immediately after that upload. A historical fingerprint alone never overrides a receipt mismatch.
103
+ - **Partial failure and resume.** The kit records each create as `pending` before the request and `created` with the provider id after it. A failed create leaves `pending`. On the next run an absent pending name is created again, and a present one is refused as `uncertain-resource-create`, because a lost response cannot prove who created it. Inspect it: if it is the empty resource from the interrupted run, delete it and re-run. A Worker upload is recorded as created when the upload succeeds, so a failure after it resumes with one fresh upload. If the response to the very first upload is lost, the Worker exists but is still `pending`. The kit records the upload's fingerprint before sending it. When an upload's response or its readback is lost (a first upload or a redeploy), the next run accepts the live version as this deploy's own only when it carries that fingerprint both as its `RER_DEPLOY_FINGERPRINT` binding and as its `rer-deploy:<fingerprint>` annotation: it records the live version id, deployment id and etag, then resumes with one fresh upload. Any other live version is refused, as `uncertain-resource-create` with no prior receipt and as `owned-resource-replaced` with one. If the uncertain Worker cannot be authenticated, inspect it and delete it only after confirming that it is the kit-created Worker and that its Durable Object data is disposable. Back up any needed data before deleting it. Migration claims keep the rules under Migration safety.
104
+ - **Drift.** A created resource that has gone is refused as `owned-resource-missing`; one replaced under the same name is refused as `owned-resource-replaced`. The kit never deletes or recreates them. This covers D1, KV, Queues and R2 (a bucket is identified by its creation date; a state file written before that was recorded keeps working and is not checked for that bucket). For the Worker, the live deployment (version id, deployment id and etag) must be the last receipt's before any write; someone else's upload under the same name is refused as `owned-resource-replaced` and never overwritten. Immediately before the Worker PUT, the kit rechecks every saved resource identity, including resources omitted from the current plan, then the Worker identity. A replacement during provisioning or asset upload is refused before the upload intent or receipt is saved. An interrupted successful upload may resume only when the live version id, deployment id and etag match the identity saved immediately after that upload, or, when its readback was lost before that identity was saved, when the live version carries the fingerprint saved immediately before that upload (binding and annotation). A receipt's historical fingerprint never overrides a receipt mismatch.
105
105
  - **Lost upgrade response.** If an upgrade response is lost and the live identity no longer matches the receipt, the kit refuses rather than guessing ownership. A [Cloudflare rollback](https://developers.cloudflare.com/workers/versions-and-deployments/rollbacks/) creates a new deployment, so it does not restore the recorded identity. Recover with a new environment and a fresh state path, or back up the state and any needed data, confirm ownership, and follow the cleanup under "If the state file is lost" with a fresh `--state` path.
106
106
  - **Settling listings.** Right after a create or delete, an account listing can briefly disagree with its own page counts (`provider-partial-list`: on 13 October 2026 D1's `total_count` lagged its rows by about 7 seconds after a create). Owner-mode deploy, health and removal discard such a snapshot and list again from the start for up to 30 seconds with a short backoff; a partial listing is never accepted.
107
107
  - **One run at a time.** A deploy takes an exclusive lock file, `<state file>.lock`, for the whole run and removes it at the end, even after a failure. A second run on the same state file is refused as `owner-state-locked` before any provider request. If a run was killed (power loss, `kill -9`) and no deploy is running, delete the lock file by hand.
@@ -115,7 +115,7 @@ A transport failure carries `providerTransport`: the operation, sanitized endpoi
115
115
 
116
116
  `rer deploy` runs these steps for a seed whose adapter uses `ownerDeploy` from `cli/deploy.mjs`.
117
117
 
118
- - **Inputs.** Declared secrets come from the environment, then `--env-file FILE` (an owned 0600 file of `KEY=VALUE` lines), which wins. For a secret the Worker does not hold yet, rer supplies the setup manifest's owner email (`emailField`) from the local setup's private settings, and a fresh random value for each secret field the manifest generates (`generate`), such as the session secret and the setup token; a value the Worker already holds is kept. A still-missing secret stops the run before any write with a message that names it.
118
+ - **Inputs.** Declared secrets come from the environment, then `--env-file FILE` (an owned 0600 file of `KEY=VALUE` lines), which wins. For a secret the Worker does not hold yet, rer supplies the setup manifest's owner email (`emailField`) from the local setup's private settings, and a fresh random value for each secret field the manifest generates (`generate`), such as the session secret and the setup token; a value the Worker already holds is kept. A still-missing secret stops the run before any write with a message that names it, unless its declaration says `"optional": true`: then the deploy binds nothing for it and reports it as not set, and `--set-secret` adds it later.
119
119
  - **Hosted owner.** After deploy and health pass, rer claims the setup owner on the hosted app: it POSTs the setup token to the seed's standard owner step (`hooks.owner`, by default `/auth/bootstrap`). 303 means claimed; `409 already_initialized` means an owner was already claimed and is kept. Then rer deletes the token secret from the Worker, records the new Worker version in the state file, and lists the token in `retiredSecrets`, so later plans no longer declare it. The build fingerprint still names it, and the recorded claim stays as recorded, so an untouched repeat deploy writes nothing. A Worker that still holds a token rer did not upload in this run (an older deploy) first gets a fresh token through the same recorded secret change. Dependency approvals that need the token run before the claim. A seed with an owner step function, an identity-provider claim, or no declared token secret claims its owner its own way.
120
120
  - **Secret changes.** `rer deploy --set-secret NAME` (value from the environment or `--env-file`, under the declaration's environment name) and `--unset-secret NAME` change one declared secret of the recorded Worker without a build. Before writing, rer records the starting version and the exact live names of all other secrets, never their values. Accepted or ambiguous writes retain that intent until readback confirms the change; explicit refusals clear it. An ambiguous failure, or a later command's preflight, can clear an unapplied intent only when the live deployment still matches the receipt and the newest listed version matches it too. A surviving intent blocks further mutations until consistency returns; retry the same command then. Recovery requires the recorded immediate successor (or the recorded confirming rotation's successor), the receipt's script etag and fingerprint, the intended binding's presence, and an unchanged set of other secret names. Ambiguous rotations require a confirming PUT before reporting success. Older intents without names may recover only from the exact starting version's historical bindings, with its id, etag and fingerprint verified; unavailable or malformed historical bindings refuse adoption. Each historical binding must have an exact provider type supported by this kit; unrecognized types cannot prove that a name was not a secret. Added, removed or renamed other secrets refuse deploy and removal before writes. Values remain opaque: these checks cannot distinguish an otherwise identical outside change to the pending binding.
121
121
  - **Removal.** `rer deploy --remove --yes` deletes what the state file says rer created for this environment: the Worker (schedules first; its Durable Objects go with it) and each D1, R2, KV and queue that is still the one rer created, after checking all of them before the first delete. A replaced or uncertain resource refuses the whole removal, except a D1 or KV whose create answer was lost: under this environment's derived name it is deleted once confirmed empty (a D1 with no tables, a KV namespace with no keys); one holding data is refused as `uncertain-resource-not-empty`, and an uncertain queue, whose backlog rer cannot read, as `uncertain-resource-unverifiable` (delete it by hand if it is the empty one from the interrupted run).
@@ -292,7 +292,9 @@ budget, and no request starts at the deadline. An unchanged repeat uses the
292
292
  existing library window and does not record first-upload readiness attempts.
293
293
  The standalone CLI `health` command sends a single request; only an answer from
294
294
  another Worker version (an edge still converging after a secret change) is asked
295
- again, within 30 seconds. Immediate post-upload readback also waits through an
295
+ again, within 30 seconds. Immediate post-upload readback waits, within the same upload
296
+ window, while Cloudflare's read of the just-uploaded version answers 404 (code
297
+ 100146); any other readback error fails. It also waits through an
296
298
  HTTPS workers.dev 404 whose complete body is `error code: 1042`, including after
297
299
  a changed-source redeploy, within the original upload deadline and the health
298
300
  command's 30-second bound. This does not grant first-creation setup-token replay
@@ -72,7 +72,7 @@ export async function verifyHealth({api,plan,receipt,fetch:request=globalThis.fe
72
72
  assert(!readiness?.window || readiness.window.remaining() > 0, 'missing-deployed-secret');
73
73
  const secrets = await api.request(`/workers/scripts/${plan.worker}/secrets`);
74
74
  assert(Array.isArray(secrets) && secrets.every(row => typeof row?.name === 'string' && row.type === 'secret_text'), 'invalid-secret-list');
75
- if (plan.secrets.every(x => secrets.some(y => y.name === x.binding && y.type === 'secret_text'))) break;
75
+ if (plan.secrets.every(x => x.optional || secrets.some(y => y.name === x.binding && y.type === 'secret_text'))) break;
76
76
  assert(readiness?.freshUpload && readiness.window?.remaining() > 0, 'missing-deployed-secret');
77
77
  await readiness.window.pause();
78
78
  }
@@ -110,11 +110,13 @@ export async function main(argv = process.argv.slice(2), env = process.env, {fet
110
110
  const declaredSecrets = current === declaration ? plan.secrets : ownerPlan(target,declaration,artifact,{localOnlyKeys,env}).secrets;
111
111
  const window = readinessWindow({...(healthOptions?.now ? {clock:healthOptions.now} : {}), ...(healthOptions?.sleep ? {sleep:healthOptions.sleep} : {}), ...healthOptions?.readiness});
112
112
  requestWindow = window;
113
- const {receipt,created,sentSecrets,freshUpload} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions,readiness:{...healthOptions?.readiness,window},settle,declaredSecrets}).catch(error => {
113
+ const {receipt,created,sentSecrets,unsetSecrets,freshUpload} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions,readiness:{...healthOptions?.readiness,window},settle,declaredSecrets}).catch(error => {
114
114
  api.annotateFailure(error,error.message.startsWith('missing-secret-') ? 'secrets' : undefined);
115
115
  throw error;
116
116
  });
117
- const result = {ok:true,changed:receipt.changed,worker:target.worker,origin:receipt.origin,versionId:receipt.provider.versionId,created,sentSecrets,retiredSecrets,...(state.ownerClaim ? {ownerClaim:state.ownerClaim} : {}),state:statePath};
117
+ // Optional secrets the Worker does not hold: never supplied, or removed with --unset.
118
+ const optionalUnset = declaredSecrets.filter(item => item?.optional && (unsetSecrets.includes(item.binding) || retiredSecrets.includes(item.binding))).map(item => item.binding);
119
+ const result = {ok:true,changed:receipt.changed,worker:target.worker,origin:receipt.origin,versionId:receipt.provider.versionId,created,sentSecrets,...(optionalUnset.length ? {optionalUnset} : {}),retiredSecrets,...(state.ownerClaim ? {ownerClaim:state.ownerClaim} : {}),state:statePath};
118
120
  const sentTokens = new Map(sentSecrets.map(binding => [binding,env[declaration.secrets.find(item => item.binding === binding)?.environment]]));
119
121
  Object.defineProperty(result, 'propagation', {value: {window,uploaded:receipt.changed,freshUpload,sentSecrets,versionId:receipt.provider.versionId,
120
122
  matchesToken:(binding,token) => sentTokens.has(binding) && sentTokens.get(binding) === token}});
@@ -22,8 +22,8 @@ import { publicOrigin } from './public-origin.mjs';
22
22
  const segment = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
23
23
  const STATE_KIND = 'rer-deploy-owner-state';
24
24
  export const KINDS = ['d1','r2','kv','queues'];
25
- const DECLARATION_KEYS = ['version','project','compatibilityDate','compatibilityFlags','d1','r2','kv','queues','durableObjects','secrets','crons','vars','originVar','publicOriginSetting','services','workersDev','platforms','container'];
26
- const ENTRY_KEYS = {d1:['binding'],r2:['binding','locationHint'],kv:['binding'],queues:['binding','consumer','deadLetterQueue'],durableObjects:['binding','className','storage'],secrets:['binding','environment','verifyStandIn'],services:['binding','project','entrypoint','allowedHosts','grant']};
25
+ const DECLARATION_KEYS = ['version','project','compatibilityDate','compatibilityFlags','d1','r2','kv','queues','durableObjects','secrets','crons','vars','originVar','publicOriginSetting','services','workersDev','platforms','container','deployGuide'];
26
+ const ENTRY_KEYS = {d1:['binding'],r2:['binding','locationHint'],kv:['binding'],queues:['binding','consumer','deadLetterQueue'],durableObjects:['binding','className','storage'],secrets:['binding','environment','verifyStandIn','optional'],services:['binding','project','entrypoint','allowedHosts','grant']};
27
27
 
28
28
  export function refuse(code, kind, name) { const error = new Error(code); error.resource = `${kind}:${name}`; return error; }
29
29
 
@@ -149,6 +149,7 @@ export function ownerPlan(target, declaration, artifact, { localOnlyKeys = [], e
149
149
  queues:queues.map(item => ({...item,name:name(item.binding),...(item.deadLetterQueue === undefined ? {} : {deadLetterQueue:name(item.deadLetterQueue)})})),
150
150
  durableObjects:entries(declaration,'durableObjects').map(item => ({...item})),
151
151
  // verifyStandIn is only `rer verify`'s hosted-check value: never planned, sent or stored.
152
+ // An optional secret (`"optional": true`, an integration's credential) may stay unset: it is bound only once supplied.
152
153
  secrets:entries(declaration,'secrets').map(({verifyStandIn,...item}) => { assert(verifyStandIn === undefined || typeof verifyStandIn === 'string' && verifyStandIn.length > 0 && verifyStandIn.length <= 1024, 'invalid-verify-stand-in'); return item; }),
153
154
  crons:[...(declaration.crons ?? [])],vars,
154
155
  // Only declarations using these add the keys, so earlier plans and fingerprints are unchanged.
@@ -171,7 +172,7 @@ export async function readOwnerState(path, target) {
171
172
  assert(state?.version === 1 && state.kind === STATE_KIND && state.owned && typeof state.owned === 'object'
172
173
  && (state.owned.worker === null || ['pending','created'].includes(state.owned.worker?.status))
173
174
  && KINDS.every(kind => state.owned[kind] && typeof state.owned[kind] === 'object' && Object.values(state.owned[kind]).every(entry => ['pending','created'].includes(entry?.status))), 'invalid-owner-state');
174
- assert(state.pendingUpload === undefined || typeof state.pendingUpload?.fingerprint === 'string' && typeof state.pendingUpload?.build === 'string', 'invalid-owner-state');
175
+ assert(state.pendingUpload === undefined || typeof state.pendingUpload?.fingerprint === 'string', 'invalid-owner-state');
175
176
  // Declared secrets rer removed on purpose (the spent setup token): later plans omit them.
176
177
  assert(state.pendingSecret === undefined || identifier(state.pendingSecret?.binding) && typeof state.pendingSecret?.present === 'boolean'
177
178
  && (state.pendingSecret.versionId === undefined || uuid(state.pendingSecret.versionId))
@@ -302,28 +303,32 @@ export async function settleOwnerState({api: provider, target, statePath}) {
302
303
  }
303
304
  export const sameDeployment = (a, b) => a?.versionId === b?.versionId && a?.deploymentId === b?.deploymentId && a?.etag === b?.etag;
304
305
 
306
+ /** Both marks rer's upload puts on a version: the build binding and the version annotation. */
307
+ const carriesUpload = (live, fingerprint) => deployedFingerprint(live?.settings) === fingerprint && live.version?.annotations?.['workers/message'] === `rer-deploy:${fingerprint}`;
305
308
  /** A completed receipt or the exact identity of an interrupted successful upload proves ownership.
306
- * Only the first upload, with no receipt, may recover a lost response by its pending build. */
307
- async function checkWorkerIdentity(api, plan, artifact, state) {
309
+ * An upload whose response or readback was lost is this deploy's own when the live version carries
310
+ * the fingerprint saved just before its PUT: rer records its ids, as a completed readback would. */
311
+ async function checkWorkerIdentity(api, plan, state, save) {
308
312
  const live = await activeWorker(api, plan.worker);
309
313
  const pending = state.pendingUpload;
310
- const expected = pending?.provider ?? state.receipt?.provider;
311
- if (expected) {
312
- if (!sameDeployment(live, expected)) throw refuse('owned-resource-replaced','worker',plan.worker);
313
- } else {
314
- const mine = state.owned.worker?.status === 'pending' && pending?.build === hash({plan,artifact}) && pending.fingerprint === deployedFingerprint(live?.settings);
315
- if (!mine) throw refuse('uncertain-resource-create','worker',plan.worker);
314
+ if (pending && !pending.provider && carriesUpload(live, pending.fingerprint)) {
315
+ pending.provider = {versionId:live.versionId,deploymentId:live.deploymentId,etag:live.etag};
316
+ state.owned.worker = {status:'created'}; await save();
317
+ return live;
316
318
  }
319
+ const expected = pending?.provider ?? state.receipt?.provider;
320
+ if (!expected) throw refuse('uncertain-resource-create','worker',plan.worker);
321
+ if (!sameDeployment(live, expected)) throw refuse('owned-resource-replaced','worker',plan.worker);
317
322
  return live;
318
323
  }
319
- async function checkOwnedWorker(api, plan, artifact, state) {
324
+ async function checkOwnedWorker(api, plan, state, save) {
320
325
  const settings = await workerSettings(api, plan.worker);
321
326
  if (settings === null) {
322
327
  if (state.owned.worker?.status === 'created') throw refuse('owned-resource-missing','worker',plan.worker);
323
328
  return null;
324
329
  }
325
330
  if (!state.owned.worker) throw refuse('resource-name-collision','worker',plan.worker);
326
- return checkWorkerIdentity(api, plan, artifact, state);
331
+ return checkWorkerIdentity(api, plan, state, save);
327
332
  }
328
333
 
329
334
  /** One deploy at a time per state file: an exclusive lock file for the whole run. */
@@ -355,13 +360,13 @@ async function deployLocked({api, target, plan, artifact, statePath, env, fetch,
355
360
  const save = () => writeOwnerState(statePath, state);
356
361
  if (await settlePendingSecret(api, target.worker, state, {preflight:true})) await save();
357
362
  await checkServiceWorkers(api, plan);
358
- const priorWorker = await checkOwnedWorker(api, plan, artifact, state);
363
+ const priorWorker = await checkOwnedWorker(api, plan, state, save);
359
364
  assert(!state.pendingSecret, 'secret-change-unsettled');
360
365
  const exists = priorWorker !== null;
361
366
  const create = await ownedResourcesToCreate(api, plan, state);
362
367
  if (exists) await checkCronOwnership(api, plan);
363
368
  // The declared secrets this run uploads; every other one is inherited unchanged.
364
- const {missing:sentSecrets} = await secretBindings(api, plan.worker, plan, env, exists);
369
+ const {missing:sentSecrets,unset:unsetSecrets} = await secretBindings(api, plan.worker, plan, env, exists);
365
370
  // Record intent before each create. A failed or lost response leaves it pending:
366
371
  // absent on resume means create again; present means an uncertain outcome to inspect.
367
372
  for (const {kind,item} of create) {
@@ -384,9 +389,9 @@ async function deployLocked({api, target, plan, artifact, statePath, env, fetch,
384
389
  const sending = path === upload && options?.method === 'PUT';
385
390
  if (sending) {
386
391
  await checkSavedResourceIdentities(api, state);
387
- const current = await checkOwnedWorker(api, plan, artifact, state);
392
+ const current = await checkOwnedWorker(api, plan, state, save);
388
393
  if (!sameDeployment(priorWorker,current)) throw refuse('owned-resource-replaced','worker',plan.worker);
389
- state.pendingUpload = {fingerprint:await uploadFingerprint(options.body),build:hash({plan,artifact})}; await save();
394
+ state.pendingUpload = {fingerprint:await uploadFingerprint(options.body)}; await save();
390
395
  }
391
396
  const result = await api.request(path, options);
392
397
  if (sending) {
@@ -404,7 +409,7 @@ async function deployLocked({api, target, plan, artifact, statePath, env, fetch,
404
409
  onReceipt: async candidate => { if (candidate.changed || !state.receipt) { state.receipt = candidate; delete state.pendingUpload; delete state.pendingSecret; await save(); } },
405
410
  // Keep each first-health attempt beside the identity it belongs to.
406
411
  onHealth: async candidate => { if (candidate.changed) { state.receipt = candidate; await save(); } }});
407
- return {receipt, created:create.map(({kind,item}) => `${kind}:${item.name}`), sentSecrets, freshUpload:!exists && receipt.changed};
412
+ return {receipt, created:create.map(({kind,item}) => `${kind}:${item.name}`), sentSecrets, unsetSecrets, freshUpload:!exists && receipt.changed};
408
413
  }
409
414
 
410
415
  /** Independent read-only health of the last owner deployment recorded in the state file. */
@@ -12,13 +12,24 @@ export function uploadVersionId(upload) {
12
12
  return versionId;
13
13
  }
14
14
 
15
+ // Cloudflare can serve the uploaded version before its own version read finds it
16
+ // (404, code 100146). Only that read of that version waits; other errors fail.
17
+ const versionNotYetReadable = (error, worker, versionId) => error.status === 404
18
+ && error.providerCall?.operation === `GET /workers/scripts/${worker}/versions/${versionId}`
19
+ && error.providerRefusal?.errors?.some(item => item.code === 100146);
20
+
15
21
  // Poll only the missing fresh Worker or the exact pre-upload version. A new
16
22
  // unrelated version is drift, even during propagation; provider errors fail.
17
23
  export async function uploadedWorker({ api, worker, upload, previous, fingerprint, window }) {
18
24
  const versionId = uploadVersionId(upload);
19
25
  const bounded = readinessAPI(api, window, 'uploaded-worker-timeout');
20
26
  while (window.remaining() > 0) {
21
- const current = await activeWorker(bounded, worker);
27
+ let current;
28
+ try { current = await activeWorker(bounded, worker); }
29
+ catch (error) {
30
+ if (!versionId || !versionNotYetReadable(error, worker, versionId)) throw error;
31
+ await window.pause(); continue;
32
+ }
22
33
  if (current && (!versionId || current.versionId === versionId) && deployedFingerprint(current.settings) === fingerprint) return current;
23
34
  const prior = previous && current?.versionId === previous.versionId && current.deploymentId === previous.deploymentId && current.etag === previous.etag;
24
35
  assert(!current || prior || current.versionId === versionId, 'uploaded-worker-drift');
@@ -31,6 +31,7 @@ export function validatePlan(plan) {
31
31
  for (const entry of plan.d1) assert(Array.isArray(entry.migrations), 'invalid-migrations');
32
32
  for (const entry of plan.durableObjects) assert(identifier(entry.className) && ['sqlite','classic'].includes(entry.storage), 'invalid-durable-object');
33
33
  for (const secret of plan.secrets) assert(identifier(secret.environment), 'invalid-secret-environment');
34
+ for (const secret of plan.secrets) assert(secret.optional === undefined || secret.optional === true, 'invalid-optional-secret');
34
35
  for (const item of plan.services ?? []) assert(Object.keys(item).every(k => ['binding','service','entrypoint','props','grant'].includes(k)) && resourceName(item.service) && item.service !== plan.worker
35
36
  && (item.entrypoint === undefined || identifier(item.entrypoint))
36
37
  && (item.props === undefined || Object.keys(item.props).join() === 'allowedHosts' && Array.isArray(item.props.allowedHosts)
@@ -46,14 +46,17 @@ export async function secretBindings(api, worker, plan, env, exists) {
46
46
  const present = exists ? await api.request(`/workers/scripts/${worker}/secrets`) : [];
47
47
  assert(Array.isArray(present) && present.every(x => typeof x.name === 'string' && x.type === 'secret_text'),'invalid-secret-list');
48
48
  const bindings = []; const names = present.map(x => x.name);
49
+ const supplied = item => typeof env[item.environment] === 'string' && env[item.environment].trim();
50
+ // An optional secret neither held nor supplied stays unbound; the app treats it as not connected.
51
+ const unset = plan.secrets.filter(item => item.optional && !names.includes(item.binding) && !supplied(item)).map(item => item.binding);
49
52
  for (const item of plan.secrets) {
50
53
  if (names.includes(item.binding)) bindings.push({type:'inherit',name:item.binding});
51
- else {
52
- assert(typeof env[item.environment] === 'string' && env[item.environment].trim(), `missing-secret-${item.environment}`);
54
+ else if (!unset.includes(item.binding)) {
55
+ assert(supplied(item), `missing-secret-${item.environment}`);
53
56
  bindings.push({type:'secret_text',name:item.binding,text:env[item.environment]});
54
57
  }
55
58
  }
56
- return {bindings,names,missing:plan.secrets.filter(x => !names.includes(x.binding)).map(x => x.binding)};
59
+ return {bindings,names,unset,missing:plan.secrets.filter(x => !names.includes(x.binding) && !unset.includes(x.binding)).map(x => x.binding)};
57
60
  }
58
61
  export async function uploadAssets(api, worker, files) {
59
62
  const manifest = {}; const byHash = new Map();
@@ -5,6 +5,7 @@ import { join } from 'node:path';
5
5
  import { createRedaction, credentialValues } from './redaction.mjs';
6
6
  import { openPrivateLog } from './private-files.mjs';
7
7
  import { commandFailure } from './failures.mjs';
8
+ import { checkoutPath, stepDiagnostic } from './step-failure.mjs';
8
9
  import { waitForReadiness } from './readiness.mjs';
9
10
  import { commandCustody } from './command-custody.mjs';
10
11
  import { createProcessBaseline, createProcessScope, inheritedScopeTokens, processScopeEnvironment } from './process-scope.mjs';
@@ -48,7 +49,9 @@ export async function createCommands(directory,state,{terminal=text=>writeSync(1
48
49
  const outcome=`exit ${detail.code??'none'}, signal ${detail.signal??'none'}`;
49
50
  const status=detail.reason==='cancel'?`cancelled (${outcome})`:detail.reason==='deadline'?`readiness deadline exceeded (${outcome})`:detail.error?`could not start${detail.errorCode?` (${detail.errorCode})`:''} (${outcome})`:outcome;
50
51
  const lines=(capture?.snapshot()||'').split('\n');if(lines.at(-1)==='')lines.pop();
51
- return Object.assign(commandFailure(`${redaction.redact(String(label))}: ${status}.${detail.lastHealth?` Last health: ${redaction.redact(String(detail.lastHealth))}.`:''}\nLast output (up to 40 lines):\n${lines.length?lines.slice(-40).join('\n'):'(no output)'}\nLog: ${redaction.redact(logPath)}`,{childExitCode:detail.code,signal:detail.signal}),{childExitCode:detail.code,signal:detail.signal});
52
+ // The step, its command, exit code, last output and log, for callers that name a failed step.
53
+ const step=stepDiagnostic({name:redaction.redact(String(label)),command:capture?.display,exitCode:detail.code,signal:detail.signal,output:lines,log:redaction.redact(checkoutPath(capture?.cwd,logPath))});
54
+ return Object.assign(commandFailure(`${redaction.redact(String(label))}: ${status}.${detail.lastHealth?` Last health: ${redaction.redact(String(detail.lastHealth))}.`:''}\nLast output (up to 40 lines):\n${lines.length?lines.slice(-40).join('\n'):'(no output)'}\nLog: ${redaction.redact(logPath)}`,{childExitCode:detail.code,signal:detail.signal,step}),{childExitCode:detail.code,signal:detail.signal});
52
55
  };
53
56
  const track=(label,child,ownershipScope)=>{
54
57
  if(captures.has(child))return child;
@@ -116,7 +119,8 @@ export async function createCommands(directory,state,{terminal=text=>writeSync(1
116
119
  // label must not show that label twice.
117
120
  const announced=redaction.redact(String(label)),repeated=state.step===announced;
118
121
  state.step=announced;if(!repeated)report(label);
119
- const {signal:providedSignal,afterCommand,onChild,heavy,phase,...native}=options;
122
+ // display: the command line a caller names in its failure; argv itself is never shown.
123
+ const {signal:providedSignal,afterCommand,onChild,heavy,phase,display,...native}=options;
120
124
  const commandSignal=signal&&providedSignal?AbortSignal.any([signal,providedSignal]):providedSignal||signal;
121
125
  if(commandSignal?.aborted)throw failure(label,{reason:'cancel'});
122
126
  const ownershipScope=createProcessScope(custodyBaseline);redaction.addSecrets([ownershipScope.token,...inheritedScopeTokens(process.env),...inheritedScopeTokens(native.env)]);
@@ -124,6 +128,7 @@ export async function createCommands(directory,state,{terminal=text=>writeSync(1
124
128
  onChild?.(child);
125
129
  ownershipRecords.set(child,{pid:child.pid,token:ownershipScope.token});
126
130
  track(label,child,ownershipScope);
131
+ Object.assign(captures.get(child),{cwd:native.cwd??process.cwd(),display:display===undefined?undefined:redaction.redact(String(display))});
127
132
  const cancel=()=>{void stopCommand(child);};
128
133
  commandSignal?.addEventListener('abort',cancel,{once:true});if(commandSignal?.aborted)cancel();
129
134
  const capture=captures.get(child);capture.removeCancellation=()=>commandSignal?.removeEventListener('abort',cancel);
@@ -144,7 +149,7 @@ export async function createCommands(directory,state,{terminal=text=>writeSync(1
144
149
  const commandSignal=signal&&options.signal?AbortSignal.any([signal,options.signal]):options.signal||signal;
145
150
  const result = await queuedCommand(command,args,{...options,verb:queuePolicy.verb,signal:commandSignal,originalCI:policy.ci,
146
151
  label:await queueLabel(options.cwd??process.cwd(),queuePolicy.verb,options.phase??'command'),report,onWaiting,
147
- spawn:(program,argv,native)=>(queuedChild=spawnCommand(label,program,argv,{...native,onChild:options.onChild})),cleanup:async(child,result)=>{await stopCommand(child);await options.afterCommand?.(result);}});
152
+ spawn:(program,argv,native)=>(queuedChild=spawnCommand(label,program,argv,{...native,onChild:options.onChild,display:options.display})),cleanup:async(child,result)=>{await stopCommand(child);await options.afterCommand?.(result);}});
148
153
  if(result){if(result.code!==0)throw failure(label,result,captures.get(queuedChild));return result;}
149
154
  }
150
155
  let child;try{child=spawnCommand(label,command,args,options);}catch{throw failure(label,options.signal?.aborted||signal?.aborted?{reason:'cancel'}:{error:true});}
@@ -0,0 +1,30 @@
1
+ import { isAbsolute, relative, sep } from 'node:path';
2
+
3
+ // How a failed install step names itself, in a terminal and in --json: the
4
+ // step, its command, exit code, the last lines it printed and its full log.
5
+ export const STEP_OUTPUT_LINES = 20;
6
+
7
+ // A path inside the checkout is shown from the checkout root: an absolute
8
+ // prefix can be masked when the shell's PWD is credential-classified.
9
+ export function checkoutPath(root, path) {
10
+ if (!root || !path || !isAbsolute(path)) return path;
11
+ const inside = relative(root, path);
12
+ return inside && !inside.startsWith(`..${sep}`) && inside !== '..' && !isAbsolute(inside) ? inside : path;
13
+ }
14
+
15
+ export function stepDiagnostic({ name, command, exitCode, signal, output, log }) {
16
+ const lines = (Array.isArray(output) ? output : String(output ?? '').split('\n')).map(String);
17
+ while (lines.length && !lines.at(-1).trim()) lines.pop();
18
+ return { name: String(name ?? 'Installing'), command: command ?? null, exitCode: Number.isInteger(exitCode) ? exitCode : null, signal: signal ?? null, output: lines.slice(-STEP_OUTPUT_LINES), log: log ?? null };
19
+ }
20
+
21
+ export function stepFailureText(step) {
22
+ return [
23
+ `Install step failed: ${step.name}`,
24
+ `Command: ${step.command ?? '(none: the step failed inside rer)'}`,
25
+ `Exit code: ${step.exitCode ?? 'none'}${step.signal ? ` (signal ${step.signal})` : ''}`,
26
+ `Last ${STEP_OUTPUT_LINES} lines of output:`,
27
+ ...(step.output.length ? step.output : ['(no output)']),
28
+ `Full log: ${step.log ?? '(none)'}`,
29
+ ].join('\n');
30
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runeditrun/rer",
3
- "version": "0.2.33",
3
+ "version": "0.2.35",
4
4
  "description": "The rer command: install, set up, run and launch Run Edit Run checkouts.",
5
5
  "license": "MIT",
6
6
  "type": "module",