@runeditrun/rer 0.2.42 → 0.2.43

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
@@ -14,10 +14,10 @@ rer dev just-every/run-inkwell
14
14
  ```
15
15
 
16
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:
17
+ private one for `rer` (see below). It edits no shell profile: it names the next
18
+ command, `rer dev <owner>/<repo>`, and when `~/.local/bin` is not on PATH for new
19
+ terminals its last line is the one to run first, which adds it for your shell.
20
+ The same start also fits on one line:
21
21
 
22
22
  ```sh
23
23
  curl -fsSL https://runeditrun.com/install.sh | sh -s -- dev just-every/run-inkwell
@@ -57,16 +57,19 @@ verifies the tarball against that release's published `SHASUMS256.txt`, and
57
57
  prints its location. The launcher uses this private runtime on later runs.
58
58
  System Node and other PATH directories are left alone: the private runtime's
59
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>`.
60
+ the installer provides. With no arguments the script names the next command,
61
+ `rer dev <owner>/<repo>`, and ends with the PATH line below when one is needed.
62
62
 
63
63
  No installer edits shell profiles. The canonical launcher is `~/.local/bin/rer`.
64
64
  Installation creates that directory if needed and never writes into another
65
65
  PATH directory. It names any existing `rer` elsewhere on PATH and leaves it
66
- unchanged. If `~/.local/bin` is absent from PATH or another command shadows it,
67
- it prints one activation line to run in the current shell:
68
- `export PATH="$HOME/.local/bin:$PATH"` (with fish syntax for fish). Without a
69
- private runtime, the launcher uses `node` from PATH. A re-run with the same build changes
66
+ unchanged. If `~/.local/bin` is absent from PATH, another command shadows it,
67
+ or no startup file of your shell adds it for new terminals, its last line is
68
+ one command to run: it appends `export PATH="$HOME/.local/bin:$PATH"` to that
69
+ startup file (`~/.zshrc` for zsh; `~/.bash_profile` for bash on macOS and
70
+ `~/.bashrc` elsewhere; `~/.profile` otherwise) and runs it in the current shell.
71
+ For fish it is `fish_add_path ~/.local/bin`. Without a private runtime, the
72
+ launcher uses `node` from PATH. A re-run with the same build changes
70
73
  nothing; a different build is installed beside the current one, the previous one
71
74
  is kept and older ones are removed. It refuses to replace a `~/.local/bin/rer`
72
75
  that it did not write.
@@ -88,11 +91,14 @@ install in place.
88
91
  - For `install.sh`: `curl`, `tar`, and `shasum` or `sha256sum` when it installs
89
92
  Node. macOS includes these tools.
90
93
  - For the npm/npx install alternatives: Node 22 or later on PATH.
91
- - Checkout commands acquire the checkout's pinned Node and pnpm when needed.
92
- `rer install` also downloads the checkout's Playwright Chromium and headless
93
- shell for verification; `rer verify` installs missing browser files on first
94
- need. Downloads print progress. `rer doctor` reports a missing browser and
95
- directs you to `rer install`, without downloading anything itself.
94
+ - Checkout commands acquire the checkout's pinned Node and pnpm when needed,
95
+ in rer's own cache: neither goes on PATH. `rer run SCRIPT [ARGS]` runs a
96
+ package.json script with them, so a project's `pnpm run X -- ARGS` is
97
+ `rer run X -- ARGS`. `rer install` downloads no browser: the checkout's
98
+ Playwright Chromium and headless shell download the first time a command needs
99
+ them (`rer verify`, or `rer run` of a script that runs Playwright). Downloads
100
+ print progress. `rer doctor` lists browsers not downloaded yet, without
101
+ counting them as a problem or downloading anything itself.
96
102
 
97
103
  Not supported: native Windows (`install.sh` and `rer` say to use WSL2), and
98
104
  `OPERATIONS.json` version 1 projects.
@@ -1,6 +1,8 @@
1
1
  // Browser prerequisites come from the checkout's Playwright, including its
2
2
  // platform/revision and PLAYWRIGHT_BROWSERS_PATH handling. Inspection never
3
- // launches a browser or downloads anything.
3
+ // launches a browser or downloads anything. The browser itself downloads on
4
+ // the first command that needs it (rer verify, or rer run of a Playwright
5
+ // script), never during rer install: a deploy-only owner never fetches it.
4
6
  import { access, constants } from 'node:fs/promises';
5
7
  import { createRequire } from 'node:module';
6
8
  import { dirname, join, relative } from 'node:path';
@@ -8,6 +10,7 @@ import { RerError } from './errors.mjs';
8
10
  import { shared } from './shared.mjs';
9
11
 
10
12
  export const browserRepair = 'rer install';
13
+ export const browserDownload = 'rer verify downloads them the first time it runs';
11
14
 
12
15
  export function checkoutPlaywright(root, { required = true } = {}) {
13
16
  const require = createRequire(join(root, 'package.json'));
@@ -44,22 +47,28 @@ export async function browserDoctor(root) {
44
47
  if (path) try { await access(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK); ok = true; } catch {}
45
48
  executables.push({ name, ...(path ? { path } : {}), ok });
46
49
  }
50
+ // Not yet downloaded is the normal state until a command needs the browser.
47
51
  const missing = executables.filter(executable => !executable.ok).map(executable => executable.name);
48
- return { ok: !missing.length, package: resolved.name, executables, ...(missing.length ? { issue: `Playwright browser executables are missing: ${missing.join(', ')}. Run ${browserRepair}.`, fix: browserRepair } : {}) };
52
+ return { ok: true, package: resolved.name, executables, ...(missing.length ? { note: `Playwright browsers not downloaded yet: ${missing.join(', ')}; ${browserDownload}.` } : {}) };
49
53
  }
50
54
 
51
55
  export async function ensureChromium(root, store, signal, { required = true } = {}) {
52
- // Installing a first-party adapter without browser dependencies remains valid.
53
- // Verification requires Playwright; installation provisions it when declared.
56
+ // A first-party adapter without browser dependencies remains valid.
57
+ // Verification requires Playwright; rer run provisions it when declared.
54
58
  const resolved = checkoutPlaywright(root, { required });
55
59
  if (!resolved) return;
56
- const before = await browserDoctor(root);
57
- if (before.ok) return;
60
+ if (await browsersPresent(root)) return;
58
61
  const { cli } = resolved;
59
62
  const { dependencyEnvironment } = await shared('dependency-environment.mjs');
60
63
  const env = dependencyEnvironment();
61
64
  if (process.env.PLAYWRIGHT_BROWSERS_PATH !== undefined) env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH;
62
65
  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
- const after = await browserDoctor(root);
64
- if (!after.ok) throw new RerError('browser_install_incomplete', after.issue, 3);
66
+ const absent = (await browserDoctor(root)).executables.filter(executable => !executable.ok).map(executable => executable.name);
67
+ if (absent.length) throw new RerError('browser_install_incomplete', `The checkout's Playwright did not install every browser it pins (missing: ${absent.join(', ')}). Run the same command again; it retries the download.`, 3);
68
+ }
69
+
70
+ // Whether every browser the checkout's Playwright pins is on disk.
71
+ export async function browsersPresent(root) {
72
+ const browser = await browserDoctor(root).catch(() => undefined);
73
+ return Boolean(browser?.ok && !browser.note);
65
74
  }
@@ -44,6 +44,18 @@ export async function declarationFor(root, adapter) {
44
44
  return matches[0];
45
45
  }
46
46
 
47
+ // What a real deploy of this checkout still needs from its owner, read from its
48
+ // deploy declaration as a dry run reads it. Local setup lists it when it ends.
49
+ export async function hostedDeployNeeds(project) {
50
+ const { adapter, root, setupManifest, setupSeed } = project;
51
+ if (typeof adapter?.deploy !== 'function') return [];
52
+ const { path, value: declaration } = await declarationFor(root, adapter);
53
+ const options = { dryRun: true }, settings = adapter.hooks?.secrets ?? adapter.settings;
54
+ const { env } = await deployEnvironment({ root, options, declaration, setupManifest, settings, localOnlyKeys: adapter.localOnlyKeys ?? [] });
55
+ const { signIn } = await requireProductionAuth({ root, declaration, env, setupManifest, setupSeed, adapter, declarationPath: path, options }) ?? {};
56
+ return neededForRealDeploy({ declaration, env, signIn });
57
+ }
58
+
47
59
  export async function deployCommand(context) {
48
60
  const { adapter, root, options, store, setupManifest, linkDependencies, localOnlyKeys = [] } = context;
49
61
  validateDeployOptions(options);
@@ -1,7 +1,7 @@
1
1
  // Chromium from the seed's own Playwright, the two ways of serving pages to it
2
2
  // (the production build as rer deploy hosts it, or a running origin), and one
3
3
  // load: scripts held until the probe releases them, every external request aborted.
4
- import { checkoutPlaywright, browserRepair } from '../browser-runtime.mjs';
4
+ import { checkoutPlaywright } from '../browser-runtime.mjs';
5
5
  import { RerError } from '../errors.mjs';
6
6
  import { serveHosted } from '../hosted-output.mjs';
7
7
  import { probe } from './probe.mjs';
@@ -12,7 +12,7 @@ export async function launchChromium(root) {
12
12
  // Pages fulfilled by the check would otherwise count as public, and Chromium would
13
13
  // refuse a dev server's loopback HMR socket from them.
14
14
  try { return await playwright.chromium.launch({ args: ['--disable-features=LocalNetworkAccessChecks'] }); }
15
- catch (error) { throw new RerError('hydration_browser_missing', `The hydration check could not start Chromium from the seed's ${name}: ${String(error.message).split('\n').find(line => line.trim()) ?? error}. Install the browser it pins with ${browserRepair}.`, 1); }
15
+ catch (error) { throw new RerError('hydration_browser_missing', `The hydration check could not start Chromium from the seed's ${name}: ${String(error.message).split('\n').find(line => line.trim()) ?? error}. Run rer verify, which downloads the browser it pins first.`, 1); }
16
16
  }
17
17
 
18
18
  const strip = new Set(['content-encoding', 'content-length', 'transfer-encoding', 'connection']);
package/cli/lifecycle.mjs CHANGED
@@ -2,6 +2,7 @@ import { ensureChromium } from './browser-runtime.mjs';
2
2
  import { dependencyInputs } from './dependency-input.mjs';
3
3
  import { linkDependencies } from './dependencies.mjs';
4
4
  import { savedSetupAnswers } from './setup-answers.mjs';
5
+ import { localDefaultsVariable } from './setup-input.mjs';
5
6
  import { mkdtemp, rm } from 'node:fs/promises';
6
7
  import { tmpdir } from 'node:os';
7
8
  import { join } from 'node:path';
@@ -93,9 +94,10 @@ async function runLifecycle(project, options, out, deployRedaction) {
93
94
  try {
94
95
  const { dependencyEnvironment } = await shared('dependency-environment.mjs');
95
96
  await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...dependencyEnvironment(), CI: 'true' }, display: 'pnpm install --frozen-lockfile' });
96
- // Inspecting the checkout's Playwright is its own step, before any download command.
97
- state.step = 'Checking the checkout’s Playwright browsers';
98
- await ensureChromium(project.root, store, signal, { required: false }); return {};
97
+ // The test browser downloads on first need (verify), not here. Package
98
+ // scripts run with the pinned pnpm through rer run, which keeps pnpm off PATH.
99
+ if (!options.json) store.report('Run this project\'s package scripts with rer run SCRIPT (it uses the pnpm this project pins).');
100
+ return {};
99
101
  } catch (error) { if (signal.aborted) throw error; throw await installStepError(error, store, project.root); }
100
102
  }
101
103
  if (options.verb === 'verify') {
@@ -144,8 +146,12 @@ async function runLifecycle(project, options, out, deployRedaction) {
144
146
  }
145
147
  await store.stop(app);
146
148
  await rememberSetupAnswers(project, input);
147
- if (options.json) out.event('setup-ready', { url, setupUrl: url+'/setup' });
148
- else { out.human(`RER_SETUP_READY ${url}`); out.human(`Next: rer dev opens ${url} signed in as the owner; first-run setup finishes at ${url}/setup.`); }
149
+ const deployNeeds = await hostedNeeds(project);
150
+ if (options.json) out.event('setup-ready', { url, setupUrl: url+'/setup', ...(deployNeeds.length ? { neededForDeploy: deployNeeds } : {}) });
151
+ else {
152
+ out.human(`RER_SETUP_READY ${url}`); out.human(`Next: rer dev opens ${url} signed in as the owner; first-run setup finishes at ${url}/setup.`);
153
+ if (deployNeeds.length) out.human(['To host it on your own Cloudflare account later, rer deploy needs:', ...deployNeeds.map(item => ` - ${item}`), 'Set them in your environment or a private (mode 0600) file passed with --env-file, then check with rer deploy --dry-run.'].join('\n'));
154
+ }
149
155
  } else if (options.verb !== 'build') throw refuse('The requested first-party capability is unavailable.');
150
156
  return {};
151
157
  } catch (error) {
@@ -167,6 +173,13 @@ async function runLifecycle(project, options, out, deployRedaction) {
167
173
  }
168
174
  }
169
175
 
176
+ // An explicit rer setup lists what hosting this checkout will need; the setup
177
+ // a zero-setup rer dev runs does not. The list is advice: it never fails setup.
178
+ async function hostedNeeds(project) {
179
+ if (process.env[localDefaultsVariable] === '1') return [];
180
+ try { return await (await import('./deploy-command.mjs')).hostedDeployNeeds(project); } catch { return []; }
181
+ }
182
+
170
183
  // A failed install step names itself: its command, exit code, last output and
171
184
  // full log. A step that stopped outside a command still names the step and log.
172
185
  async function installStepError(error, store, root) {
package/cli/main.mjs CHANGED
@@ -1,3 +1,4 @@
1
+ import './sqlite-notice.mjs';
1
2
  import { parse, help } from './parse.mjs';
2
3
  import { output } from './output.mjs';
3
4
  import { invalid, RerError } from './errors.mjs';
package/cli/port.mjs CHANGED
@@ -11,11 +11,11 @@ export const defaultPort = 8787;
11
11
  // this host can bind. Another checkout's server may listen on every address,
12
12
  // which a bind to 127.0.0.1 alone does not notice.
13
13
  export async function firstFreePort(host, from = defaultPort, context) {
14
- const { inspectionContext } = await shared('process-diagnostics.mjs');
14
+ const { searchContext } = await shared('process-diagnostics.mjs');
15
15
  const { probePort } = await shared('port-probe.mjs');
16
- context ??= inspectionContext({verb:'setup'});
16
+ context ??= searchContext({verb:'setup'});
17
17
  for (let port = from; port <= 65535; port++) {
18
- if ((await probePort(host, port, { context, anyAddress: true })).available) return port;
18
+ if ((await probePort(host, port, { context, anyAddress: true, searching: true })).available) return port;
19
19
  if (performance.now() >= context.deadline) throw Error('Could not find a free port in time (system busy). Run rer setup again.');
20
20
  }
21
21
  throw Error(`No free port from ${from} upward.`);
@@ -71,6 +71,8 @@ catch (error) {
71
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';
72
72
  // A later migration that changes restorable data is named: it is a file of this installation.
73
73
  const migration = error instanceof PortabilityError && error.code.startsWith('schema_mismatch:migration_data:') ? error.code.slice('schema_mismatch:migration_data:'.length) : undefined;
74
+ // A populated destination names its table or bucket: schema names, never row data.
75
+ const occupied = error instanceof PortabilityError && /^(target|bucket)_not_empty:/.test(error.code) ? error.code.slice(error.code.indexOf(':') + 1) : undefined;
74
76
  process.exitCode = exitCode;
75
- await reply({ ok: false, code: exitCode === 2 ? 'invalid_archive' : exitCode === 4 ? 'restore_refused' : 'transfer_failed', reason, ...(migration ? { migration } : {}), exitCode });
77
+ await reply({ ok: false, code: exitCode === 2 ? 'invalid_archive' : exitCode === 4 ? 'restore_refused' : 'transfer_failed', reason, ...(migration ? { migration } : {}), ...(occupied ? { occupied } : {}), exitCode });
76
78
  }
@@ -54,9 +54,11 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
54
54
  // Check real existing bindings first; finalize repeats this under the lock.
55
55
  if(legacyRecovery)await nativeWorker(store,'legacy-preflight',input,signal);
56
56
  // Local migrations need no provider account: wrangler runs without credentials.
57
+ // Its info lines (the local location and "Use --remote if you want to access
58
+ // the remote instance") only confuse a local backup; warnings and errors print.
57
59
  const { dependencyEnvironment } = await shared('dependency-environment.mjs');
58
60
  await store.run('Applying local data migrations', 'pnpm', ['exec', 'wrangler', 'd1', 'migrations', 'apply', database, '--local', '--persist-to', '.wrangler/state', '--config', 'wrangler.jsonc'], {
59
- cwd: root, signal, env: { ...dependencyEnvironment(), RER_LOCAL_OPERATION: operationToken, WRANGLER_SEND_METRICS: 'false' },
61
+ cwd: root, signal, env: { ...dependencyEnvironment(), RER_LOCAL_OPERATION: operationToken, WRANGLER_SEND_METRICS: 'false', WRANGLER_LOG: 'warn' },
60
62
  });
61
63
  const receipt=await nativeWorker(store,direction,input,signal);
62
64
  if(legacyRecovery)receipt.output=relative(root,legacyRecovery.output);
@@ -66,9 +68,10 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
66
68
  }
67
69
 
68
70
  async function nativeWorker(store,direction,input,signal) {
69
- const worker = fileURLToPath(new URL('./portability-worker.mjs', import.meta.url));
71
+ // The notice filter loads before the worker links its static node:sqlite import.
72
+ const worker = fileURLToPath(new URL('./portability-worker.mjs', import.meta.url)), notice = new URL('./sqlite-notice.mjs', import.meta.url).href;
70
73
  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' }, stdio: ['ignore', 'pipe', 'pipe', 'ipc'] });
74
+ ['--import', notice, worker, direction, JSON.stringify(input)], { cwd: input.root, signal, env: { ...process.env, WRANGLER_SEND_METRICS: 'false' }, stdio: ['ignore', 'pipe', 'pipe', 'ipc'] });
72
75
  let receipt;
73
76
  child.once('message', message => { receipt = message; });
74
77
  const closed = new Promise(resolve => child.once('close', (code, signal) => resolve({ code, signal })));
@@ -79,6 +82,7 @@ async function nativeWorker(store,direction,input,signal) {
79
82
  if (status.code !== 0 || !receipt.ok) throw new RerError(receipt.code ?? 'transfer_failed', receipt.reason==='legacy_restored_export_failed'
80
83
  ? '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
84
  : 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.`
85
+ : receipt.occupied ? `Restore refused (${receipt.reason}): ${receipt.reason === 'bucket_not_empty' ? `storage bucket ${receipt.occupied} in this installation already holds files` : `table ${receipt.occupied} in this installation already holds rows its migrations did not insert`}, and a restore only goes into an empty installation. To replace this installation's data with the archive, keep a copy with rer export --output exports/before-restore.rer, then run rer reset --yes and rer import --input ${relative(input.root, input.path)} --yes again.`
82
86
  : `The portability module refused or failed the archive operation (${receipt.reason ?? 'incomplete'}).`, receipt.exitCode ?? 1);
83
87
  delete receipt.ok;
84
88
  return receipt;
@@ -0,0 +1,11 @@
1
+ // Node 22 marks node:sqlite experimental and prints a warning when it loads.
2
+ // rer reads local SQLite on purpose (reset, export, import), so that one notice
3
+ // is dropped; every other warning still prints. Import it before node:sqlite
4
+ // loads: a static import of node:sqlite warns while its module graph links, so
5
+ // a process whose entry imports it statically preloads this with --import.
6
+ const emitWarning = process.emitWarning;
7
+ process.emitWarning = function (warning, ...rest) {
8
+ const type = typeof rest[0] === 'string' ? rest[0] : rest[0]?.type;
9
+ if (type === 'ExperimentalWarning' && /^SQLite is an experimental feature/.test(String(warning?.message ?? warning))) return;
10
+ return emitWarning.call(process, warning, ...rest);
11
+ };
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.43
4
+
5
+ - **The installer ends with the line that puts `rer` on PATH.** `install.sh` and `rer cli install` end with `Next, start an app: rer dev <owner>/<repo>`. When new terminals will not find `rer`, the last line is the one command that adds `~/.local/bin` for your shell, for example `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && export PATH="$HOME/.local/bin:$PATH"` (bash: `~/.bash_profile` on macOS and `~/.bashrc` elsewhere; fish: `fish_add_path ~/.local/bin`; otherwise `~/.profile`). Once a startup file already adds it, no line is printed. The installer still never edits a shell profile itself (#190).
6
+ - **`rer run SCRIPT` runs a project's scripts without pnpm on PATH.** `rer run X -- ARGS` is `pnpm run X -- ARGS` with the pnpm and Node the checkout pins, taken from rer's own cache. `rer run` alone lists the scripts. Where a seed's docs say `pnpm run …`, a newcomer without pnpm can now run them (#190).
7
+ - **`rer install` no longer downloads a browser.** The Playwright browser a seed's tests use (about 99 MiB) downloads the first time a command needs it: `rer verify`, or `rer run` of a script that runs Playwright. An owner who only deploys never fetches it. `rer doctor` lists a browser not yet downloaded as a note, not a failure (#190).
8
+ - **`rer dev <owner>/<repo>` clones every release tag.** The clone uses `--filter=blob:none` instead of `--depth 1`: it has every commit and tag, and file contents arrive as a checkout needs them, so `git checkout <tag>` adopts an older release (#190).
9
+ - **`rer setup` says what a hosted deploy still needs.** An explicit `rer setup` ends with what `rer deploy` will need, read from the deploy declaration: the Cloudflare account ID and API token, each required secret not yet set, and production sign-in's mail inputs. With `--json`, the `setup-ready` event carries `neededForDeploy` (#190).
10
+ - **A busy computer no longer fails the first `rer dev` on the port search.** The search moves past a port in use as soon as it cannot bind it, and its time allowance grows with the load per CPU (15 seconds, up to 60). Before, every busy port ran a slow ownership check inside one 15-second budget (#190).
11
+ - **Plainer wording, less noise.** The installer says "start an app", not "start a seed". `rer export`, `rer reset` and `rer import` no longer print Node's "SQLite is an experimental feature" notice or wrangler's "Use --remote if you want to access the remote instance"; warnings and errors still print (#190).
12
+ - **A restore into a fresh install accepts the rows the seed's own migrations insert.** `rer import` into a fresh or reset install used to refuse any seed whose migrations insert rows, such as default settings, with only "(target_not_empty)". Now a table that holds exactly the rows a replay of the applied migrations leaves counts as empty, and the archive's rows replace them. Any other row still refuses, and the message names the table and the next step: keep a copy with `rer export`, then `rer reset --yes` and `rer import --input <file> --yes`. A non-empty bucket is named the same way. This covers local and Node runners; a hosted (Worker) import still needs `replaceableTables` (#193).
13
+ - **The owner can change their display name.** `/setup` shows "Your name" as an editable field, saved on Finish setup. `POST /auth/display-name` changes it later, and the reference app's Operator access panel has a "Your name" form (#193).
14
+
3
15
  ## 0.2.42
4
16
 
5
17
  - **`rer export` never exports the local copy under a hosted address.** `rer export --origin <hosted address>` used to ignore the address and export this computer's books, so an owner who believed the hosted books were saved could take them down and lose them. Now `--origin` or `--target remote` stops before anything runs (exit 2) and saves nothing. The message says this exports only the local copy and to keep the hosted install until its data is saved. It also names the command that exports each hosted database the checkout deployed, run with the Cloudflare credentials that deployed it: `npx wrangler d1 export <database> --remote --output exports/<database>.sql`. It lists the R2 buckets that command does not cover. A finished export's last line names the copy: "Exported the local copy to exports/x.rer (…)". RUN-LOCALLY.md now says to save the hosted data this way before `rer deploy --remove --yes` (#194).
package/global/README.md CHANGED
@@ -14,10 +14,10 @@ rer dev just-every/run-inkwell
14
14
  ```
15
15
 
16
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:
17
+ private one for `rer` (see below). It edits no shell profile: it names the next
18
+ command, `rer dev <owner>/<repo>`, and when `~/.local/bin` is not on PATH for new
19
+ terminals its last line is the one to run first, which adds it for your shell.
20
+ The same start also fits on one line:
21
21
 
22
22
  ```sh
23
23
  curl -fsSL https://runeditrun.com/install.sh | sh -s -- dev just-every/run-inkwell
@@ -57,16 +57,19 @@ verifies the tarball against that release's published `SHASUMS256.txt`, and
57
57
  prints its location. The launcher uses this private runtime on later runs.
58
58
  System Node and other PATH directories are left alone: the private runtime's
59
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>`.
60
+ the installer provides. With no arguments the script names the next command,
61
+ `rer dev <owner>/<repo>`, and ends with the PATH line below when one is needed.
62
62
 
63
63
  No installer edits shell profiles. The canonical launcher is `~/.local/bin/rer`.
64
64
  Installation creates that directory if needed and never writes into another
65
65
  PATH directory. It names any existing `rer` elsewhere on PATH and leaves it
66
- unchanged. If `~/.local/bin` is absent from PATH or another command shadows it,
67
- it prints one activation line to run in the current shell:
68
- `export PATH="$HOME/.local/bin:$PATH"` (with fish syntax for fish). Without a
69
- private runtime, the launcher uses `node` from PATH. A re-run with the same build changes
66
+ unchanged. If `~/.local/bin` is absent from PATH, another command shadows it,
67
+ or no startup file of your shell adds it for new terminals, its last line is
68
+ one command to run: it appends `export PATH="$HOME/.local/bin:$PATH"` to that
69
+ startup file (`~/.zshrc` for zsh; `~/.bash_profile` for bash on macOS and
70
+ `~/.bashrc` elsewhere; `~/.profile` otherwise) and runs it in the current shell.
71
+ For fish it is `fish_add_path ~/.local/bin`. Without a private runtime, the
72
+ launcher uses `node` from PATH. A re-run with the same build changes
70
73
  nothing; a different build is installed beside the current one, the previous one
71
74
  is kept and older ones are removed. It refuses to replace a `~/.local/bin/rer`
72
75
  that it did not write.
@@ -88,11 +91,14 @@ install in place.
88
91
  - For `install.sh`: `curl`, `tar`, and `shasum` or `sha256sum` when it installs
89
92
  Node. macOS includes these tools.
90
93
  - For the npm/npx install alternatives: Node 22 or later on PATH.
91
- - Checkout commands acquire the checkout's pinned Node and pnpm when needed.
92
- `rer install` also downloads the checkout's Playwright Chromium and headless
93
- shell for verification; `rer verify` installs missing browser files on first
94
- need. Downloads print progress. `rer doctor` reports a missing browser and
95
- directs you to `rer install`, without downloading anything itself.
94
+ - Checkout commands acquire the checkout's pinned Node and pnpm when needed,
95
+ in rer's own cache: neither goes on PATH. `rer run SCRIPT [ARGS]` runs a
96
+ package.json script with them, so a project's `pnpm run X -- ARGS` is
97
+ `rer run X -- ARGS`. `rer install` downloads no browser: the checkout's
98
+ Playwright Chromium and headless shell download the first time a command needs
99
+ them (`rer verify`, or `rer run` of a script that runs Playwright). Downloads
100
+ print progress. `rer doctor` lists browsers not downloaded yet, without
101
+ counting them as a problem or downloading anything itself.
96
102
 
97
103
  Not supported: native Windows (`install.sh` and `rer` say to use WSL2), and
98
104
  `OPERATIONS.json` version 1 projects.
@@ -39,6 +39,13 @@ async function writeLauncher(paths) {
39
39
  await rename(temporary, paths.launcher);
40
40
  }
41
41
 
42
+ // The next step, then (when needed) the exact line that puts rer on PATH, last.
43
+ // install.sh running a command itself, and rer update, set RER_INSTALL_NO_NEXT.
44
+ async function closing(paths) {
45
+ const advice = await pathAdvice(paths);
46
+ return `${process.env.RER_INSTALL_NO_NEXT ? '' : 'Next, start an app: rer dev <owner>/<repo>\n'}${advice ? advice + '\n' : ''}`;
47
+ }
48
+
42
49
  export async function install({ quiet = false } = {}) {
43
50
  const paths = layout(), manifest = ownManifest(), digest = await packageDigest(ownRoot);
44
51
  const name = `${manifest.version}-${digest.slice(0, 8)}`, channel = process.env.RER_INSTALL_CHANNEL === 'script' ? 'script' : 'npx';
@@ -52,8 +59,7 @@ export async function install({ quiet = false } = {}) {
52
59
  let present = false;
53
60
  try { present = await packageDigest(join(paths.versions, name)) === digest; } catch (error) { if (error.code !== 'ENOENT') throw error; }
54
61
  if (present && current === join('versions', name) && launcher.text === script && record?.channel === channel) {
55
- const advice = await pathAdvice(paths);
56
- if (!quiet) process.stdout.write(`rer ${manifest.version} is already current (${join(paths.versions, name)}). Nothing changed.\n${advice ? advice + '\n' : ''}`);
62
+ if (!quiet) process.stdout.write(`rer ${manifest.version} is already current (${join(paths.versions, name)}). Nothing changed.\n${await closing(paths)}`);
57
63
  return 0;
58
64
  }
59
65
  if (!present) { await rm(join(paths.versions, name), { recursive: true, force: true }); await copyVersion(paths, name); }
@@ -66,7 +72,6 @@ export async function install({ quiet = false } = {}) {
66
72
  for (const entry of await readdir(paths.versions)) if (!keep.has(entry) && !entry.startsWith('.staging-')) await rm(join(paths.versions, entry), { recursive: true, force: true });
67
73
  await writeFile(paths.record, JSON.stringify({ channel, links: record?.links ?? [], previous: previousName && keep.has(previousName) ? previousName : null }, null, 2) + '\n', { mode: 0o644 });
68
74
  if (launcher.text !== script) await writeLauncher(paths);
69
- const advice = await pathAdvice(paths);
70
- if (!quiet) process.stdout.write(`Installed rer ${manifest.version} in ${join(paths.versions, name)}.\n${paths.launcher} runs it.${previousName ? ` The previous version (${previousName}) is kept.` : ''}\n${advice ? advice + '\n' : ''}`);
75
+ if (!quiet) process.stdout.write(`Installed rer ${manifest.version} in ${join(paths.versions, name)}.\n${paths.launcher} runs it.${previousName ? ` The previous version (${previousName}) is kept.` : ''}\n${await closing(paths)}`);
71
76
  return 0;
72
77
  }
@@ -1,8 +1,7 @@
1
1
  // Installation writes only the canonical launcher in ~/.local/bin.
2
2
  // Other PATH commands are reported, never replaced or linked alongside.
3
- import { access, constants, lstat, readlink, stat } from 'node:fs/promises';
3
+ import { access, constants, lstat, readFile, readlink, stat } from 'node:fs/promises';
4
4
  import { basename, delimiter, join, resolve } from 'node:path';
5
- import { shellQuote } from '../../cli/node-runtime-cache.mjs';
6
5
 
7
6
  // Older installs recorded extra PATH links; uninstall can still remove those.
8
7
  export async function ownedPathLink(path, launcher) {
@@ -10,8 +9,43 @@ export async function ownedPathLink(path, launcher) {
10
9
  catch (error) { if (error.code === 'ENOENT' || error.code === 'EINVAL') return false; throw error; }
11
10
  }
12
11
 
12
+ const exists = path => access(path).then(() => true, () => false);
13
+
14
+ // The files a new terminal of this shell reads, and the one line that puts
15
+ // ~/.local/bin on PATH in this terminal and, through the startup file, in new
16
+ // ones. rer never runs it: the person does.
17
+ export async function shellStartup(home, env = process.env, platform = process.platform) {
18
+ const shell = basename(env.SHELL ?? ''), add = 'export PATH="$HOME/.local/bin:$PATH"';
19
+ if (shell === 'fish') return { files: ['.config/fish/config.fish', '.config/fish/fish_variables'].map(file => join(home, file)), line: 'fish_add_path ~/.local/bin' };
20
+ if (shell === 'zsh') {
21
+ const directory = env.ZDOTDIR || home;
22
+ return { files: ['.zshenv', '.zprofile', '.zshrc', '.zlogin'].map(file => join(directory, file)), line: `echo '${add}' >> ${env.ZDOTDIR ? '"$ZDOTDIR/.zshrc"' : '~/.zshrc'} && ${add}` };
23
+ }
24
+ const files = shell === 'bash' ? ['.bash_profile', '.bash_login', '.profile', '.bashrc'] : ['.profile'];
25
+ // macOS terminals start bash as a login shell, which reads only the first of
26
+ // its profiles that exists; elsewhere a terminal's bash reads ~/.bashrc.
27
+ let file = '.profile';
28
+ if (shell === 'bash' && platform !== 'darwin') file = '.bashrc';
29
+ else if (shell === 'bash') {
30
+ file = '.bash_profile';
31
+ for (const candidate of files.slice(0, 3)) if (await exists(join(home, candidate))) { file = candidate; break; }
32
+ }
33
+ return { files: files.map(name => join(home, name)), line: `echo '${add}' >> ~/${file} && ${add}` };
34
+ }
35
+
36
+ // Whether a startup file already puts ~/.local/bin on PATH for new terminals.
37
+ async function persistent(files) {
38
+ for (const file of files) {
39
+ try { if ((await readFile(file, 'utf8')).includes('.local/bin')) return true; }
40
+ catch (error) { if (!['ENOENT', 'EISDIR', 'EACCES'].includes(error.code)) throw error; }
41
+ }
42
+ return false;
43
+ }
44
+
45
+ // Empty when `rer` already runs this launcher in this terminal and new ones.
46
+ // Otherwise the advice ends with the exact line to run.
13
47
  export async function pathAdvice(paths, env = process.env) {
14
- const entries = [...new Set((env.PATH ?? '').split(delimiter).map(entry => resolve(entry)))];
48
+ const entries = [...new Set((env.PATH ?? '').split(delimiter).filter(Boolean).map(entry => resolve(entry)))];
15
49
  const bin = resolve(paths.bin), lines = [];
16
50
  let firstCommand;
17
51
  for (const directory of entries) {
@@ -24,11 +58,10 @@ export async function pathAdvice(paths, env = process.env) {
24
58
  lines.push(`Left existing rer at ${candidate} unchanged.`);
25
59
  } catch (error) { if (!['ENOENT', 'EACCES', 'ENOTDIR'].includes(error.code)) throw error; }
26
60
  }
27
- if (!entries.includes(bin) || firstCommand !== paths.launcher) {
28
- const command = basename(env.SHELL ?? '') === 'fish'
29
- ? `set -gx PATH ${shellQuote(paths.bin)} $PATH`
30
- : `export PATH=${shellQuote(paths.bin)}:"$PATH"`;
31
- lines.push(`Add ~/.local/bin to PATH in this shell: ${command}`);
32
- }
61
+ const startup = await shellStartup(paths.home, env);
62
+ const first = entries.includes(bin) && firstCommand === paths.launcher;
63
+ if (first && await persistent(startup.files)) return lines.join('\n');
64
+ const why = first ? 'New terminals will not find rer yet.' : firstCommand ? `Another rer (${firstCommand}) comes first on your PATH.` : 'rer is not on your PATH yet.';
65
+ lines.push(`${why} Run this line; it puts ~/.local/bin first on PATH in this terminal and in new ones:`, ` ${startup.line}`);
33
66
  return lines.join('\n');
34
67
  }
@@ -64,7 +64,10 @@ export async function checkoutRepository({ url, root, directory }) {
64
64
  }
65
65
  }
66
66
  await mkdir(resolve(root, '..'), { recursive: true });
67
- const code = await runCommand('git', ['clone', '--depth', '1', '--', url, root]);
67
+ // Every commit and release tag, so `git checkout <tag>` adopts an older
68
+ // release; file contents arrive when a checkout needs them (a host without
69
+ // partial clone sends them all).
70
+ const code = await runCommand('git', ['clone', '--filter=blob:none', '--', url, root]);
68
71
  if (code !== 0) throw refuse(`Could not clone into ${directory}. Check the git URL and access, then rerun the command.`);
69
72
  }
70
73
 
@@ -3,7 +3,7 @@ import { execFile } from 'node:child_process';
3
3
  import { stat } from 'node:fs/promises';
4
4
  import { join } from 'node:path';
5
5
  import { promisify } from 'node:util';
6
- import { inspectionContext } from '../../onboarding/process-diagnostics.mjs';
6
+ import { searchContext } from '../../onboarding/process-diagnostics.mjs';
7
7
  import { probePort } from '../../onboarding/port-probe.mjs';
8
8
  import { LaunchFailure } from './failure.mjs';
9
9
 
@@ -77,10 +77,10 @@ export async function portTaken(port) {
77
77
  export async function freePort(ports, claim, env = process.env) {
78
78
  const from = Number(env.RER_DEV_PORT_FROM ?? 8787);
79
79
  if (!Number.isInteger(from) || from < 1 || from > 65535) throw new LaunchFailure(2, 'RER_DEV_PORT_FROM must be a port number.');
80
- const held = new Set(ports.filter(Boolean)), context = inspectionContext();
80
+ const held = new Set(ports.filter(Boolean)), context = searchContext();
81
81
  for (let port = from; port <= 65535; port++) {
82
82
  if (held.has(port)) continue;
83
- const result = await probePort('127.0.0.1', port, { context, hosts: ['127.0.0.1', '::1'], anyAddress: true });
83
+ const result = await probePort('127.0.0.1', port, { context, hosts: ['127.0.0.1', '::1'], anyAddress: true, searching: true });
84
84
  if (!result.available) {
85
85
  if (performance.now() >= context.deadline) throw new LaunchFailure(4, `Could not find a free port from ${from} in time (system busy). Run rer dev again or pass rer dev --port PORT with a free port.`);
86
86
  continue;
package/global/main.mjs CHANGED
@@ -22,6 +22,9 @@ pins (installed first by any verb when node_modules holds another), else its ven
22
22
  RER_READY and a sign-in link. Without a terminal it returns once the app is
23
23
  ready and leaves it running (--detach and --foreground override); allow up
24
24
  to 10 minutes on a first launch, or rerun it to reattach. rer dev --stop stops it.
25
+ rer run SCRIPT [ARGS]
26
+ Run a package.json script with the pnpm and Node the checkout pins (rer keeps
27
+ them off PATH): where a project's docs say pnpm run X, run rer run X.
25
28
  rer list [DIR] The checkouts in DIR (default: here), newest first, with whether rer dev can
26
29
  launch them, whether they are set up, and their running URL. --json for data.
27
30
  rer business ... Pair a Business device, store local vendor keys, inspect tasks and disconnect.
@@ -66,6 +69,7 @@ export async function main(argv) {
66
69
  if (verb === 'cli') return (await import('./cli/command.mjs')).cliCommand(argv.slice(1));
67
70
  if (verb === 'list') return (await import('./list.mjs')).listCommand(argv.slice(1));
68
71
  if (verb === 'door') return (await import('./door/command.mjs')).doorCommand(argv.slice(1));
72
+ if (verb === 'run') return (await import('./run.mjs')).runScript(argv.slice(1));
69
73
  if (repositoryCommands[verb] && argv.includes('--help')) {
70
74
  const { help } = await import('../cli/parse.mjs');
71
75
  process.stdout.write(`${help(verb)}\n${repositoryCommands[verb].usage}\n${repositoryCommands[verb].effects}\n${repositoryHelp}`);
@@ -136,7 +140,7 @@ export async function main(argv) {
136
140
  }
137
141
  if (mode === 'package' && installsFirst.has(verb)) await (await import('./launch/install-pinned.mjs')).settledPin(target.root);
138
142
  if (verb === 'describe' && !argv.includes('--help')) return (await import('./cli/describe.mjs')).describeCommand(target);
139
- if (first && dispatcher(target.root).mode !== 'bundled' && ['install', 'verify'].includes(verb) && !argv.includes('--help') && !argv.includes('--site')) {
143
+ if (first && dispatcher(target.root).mode !== 'bundled' && verb === 'verify' && !argv.includes('--help') && !argv.includes('--site')) {
140
144
  const code = await (await import('./browser-runtime.mjs')).browserPreflight(target.root, target.args);
141
145
  if (code !== undefined) return code;
142
146
  }
package/global/rer.mjs CHANGED
@@ -26,7 +26,7 @@ if (process.platform === 'win32') {
26
26
  process.stderr.write('rer needs Node ' + minimum + ' or later; this is Node ' + process.versions.node + '. Install a newer Node, then run rer again.\n');
27
27
  process.exitCode = 1;
28
28
  } else {
29
- import('./main.mjs').then(function (module) { return module.main(process.argv.slice(2)); }).then(function (code) {
29
+ import('../cli/sqlite-notice.mjs').then(function () { return import('./main.mjs'); }).then(function (module) { return module.main(process.argv.slice(2)); }).then(function (code) {
30
30
  if (code !== undefined) process.exitCode = code;
31
31
  });
32
32
  }
package/global/run.mjs ADDED
@@ -0,0 +1,64 @@
1
+ // rer run SCRIPT [ARGS]: `pnpm run SCRIPT ARGS` in a checkout, with the pnpm
2
+ // and Node it pins. rer keeps both in its own cache, off PATH, so a project's
3
+ // documented `pnpm run ...` works as `rer run ...` right after rer install.
4
+ // A script that runs Playwright gets the checkout's browser first, on first need.
5
+ import { spawn } from 'node:child_process';
6
+ import { readFile } from 'node:fs/promises';
7
+ import { constants } from 'node:os';
8
+ import { delimiter, dirname, join } from 'node:path';
9
+ import { locate } from './checkout.mjs';
10
+
11
+ export const runUsage = `Usage: rer run [--cwd DIR] [SCRIPT [ARGS...]]
12
+ Runs a package.json script of this checkout as pnpm run SCRIPT ARGS would, with the
13
+ pnpm and Node the checkout pins (rer keeps them off PATH). Without SCRIPT it lists
14
+ the scripts. Where a project's docs say pnpm run X -- ARGS, run rer run X -- ARGS.
15
+ `;
16
+
17
+ // The checkout's pinned Node, when it differs from this one (RER_NODE_AUTO=0 keeps this one).
18
+ async function projectNode(root, env) {
19
+ const { projectNodePin, installedRuntime } = await import('../cli/node-runtime-discovery.mjs');
20
+ const version = await projectNodePin(root);
21
+ if (!version || version === process.versions.node || env.RER_NODE_AUTO === '0') return;
22
+ const { downloadRuntime } = await import('../cli/node-runtime-download.mjs');
23
+ const { missing, RerError } = await import('../cli/errors.mjs');
24
+ let binary = await installedRuntime(version);
25
+ try { binary ??= await downloadRuntime(version); }
26
+ catch (error) { if (error instanceof RerError) throw error; throw missing(`This project pins Node ${version}, which could not be fetched (${error.message}). Retry with a working connection, or set RER_NODE_AUTO=0 to use Node ${process.versions.node}.`); }
27
+ env.PATH = [dirname(binary), env.PATH].filter(Boolean).join(delimiter);
28
+ }
29
+
30
+ export async function runScript(args) {
31
+ let cwd;
32
+ if (['--help', '-h'].includes(args[0])) { process.stdout.write(runUsage); return 0; }
33
+ if (args[0] === '--cwd') {
34
+ cwd = args[1];
35
+ if (!cwd?.trim() || cwd.startsWith('-')) { process.stderr.write(`A folder is required for --cwd.\n${runUsage}`); return 2; }
36
+ args = args.slice(2);
37
+ }
38
+ const target = locate(cwd ? ['run', '--cwd', cwd] : ['run']);
39
+ if (!target.root || !['first-party', 'independent'].includes(target.profile)) {
40
+ process.stderr.write(`rer run runs inside a checkout: a folder with OPERATIONS.json at or above this one, or --cwd DIR.\n`);
41
+ return 2;
42
+ }
43
+ const { ensureProjectPnpm } = await import('../cli/project-pnpm.mjs');
44
+ const { RerError } = await import('../cli/errors.mjs');
45
+ try {
46
+ await ensureProjectPnpm(target.root, { report: text => process.stderr.write(text + '\n') });
47
+ await projectNode(target.root, process.env);
48
+ } catch (error) { if (!(error instanceof RerError)) throw error; process.stderr.write(error.message + '\n'); return error.exitCode; }
49
+ let scripts = {};
50
+ try { scripts = JSON.parse(await readFile(join(target.root, 'package.json'), 'utf8')).scripts ?? {}; } catch {}
51
+ if (args[0] && /\bplaywright\b/.test(scripts[args[0]] ?? '')) {
52
+ const code = await (await import('./browser-runtime.mjs')).browserPreflight(target.root, ['run']);
53
+ if (code !== undefined) return code;
54
+ }
55
+ const child = spawn('pnpm', ['run', ...args], { cwd: target.root, env: process.env, stdio: 'inherit' });
56
+ const forward = new Map(['SIGINT', 'SIGTERM', 'SIGHUP'].map(signal => [signal, () => child.kill(signal)]));
57
+ for (const [signal, handler] of forward) process.on(signal, handler);
58
+ try {
59
+ return await new Promise((resolve, reject) => {
60
+ child.once('error', reject);
61
+ child.once('exit', (code, signal) => resolve(code ?? 128 + (constants.signals[signal] ?? 0)));
62
+ });
63
+ } finally { for (const [signal, handler] of forward) process.off(signal, handler); }
64
+ }
@@ -82,7 +82,7 @@ export async function update(args) {
82
82
  }
83
83
  }
84
84
  if (channel === 'npm-global') return await npmGlobal(release.version);
85
- return await run(process.execPath, [join(work, 'package/global/rer.mjs'), 'cli', 'install'], { ...process.env, RER_INSTALL_CHANNEL: channel });
85
+ return await run(process.execPath, [join(work, 'package/global/rer.mjs'), 'cli', 'install'], { ...process.env, RER_INSTALL_CHANNEL: channel, RER_INSTALL_NO_NEXT: '1' });
86
86
  } catch (error) {
87
87
  if (!(error instanceof UpdateFailure)) throw error;
88
88
  process.stderr.write(`rer update: ${error.message} rer ${current} is still selected.\n`);
package/install.sh CHANGED
@@ -11,7 +11,8 @@
11
11
  # differently from this script's own check), and installs through the
12
12
  # package's own `rer cli install`: the same layout as
13
13
  # `npx -y @runeditrun/rer cli install`. A failure leaves any previous install
14
- # selected and working. It never edits shell profiles.
14
+ # selected and working. It never edits shell profiles: when ~/.local/bin is not
15
+ # on PATH for new terminals, its last line is the one to run that adds it.
15
16
  #
16
17
  # Needs curl and tar. If Node 22 or later is absent, installs the pinned official
17
18
  # Node release in rer's own data directory. macOS/Linux x64/arm64; Windows: WSL2.
@@ -139,13 +140,13 @@ if (process.argv[5] !== '' && Number(process.argv[5]) !== total) stop('the archi
139
140
  NODE
140
141
  mkdir "$work/stage"
141
142
  tar -xzf "$work/rer.tgz" -C "$work/stage" || fail "could not unpack rer $version; nothing was installed."
142
- RER_INSTALL_CHANNEL=script node "$work/stage/package/global/rer.mjs" cli install </dev/null \
143
+ # It ends with the next step and, when rer is not on PATH in new terminals,
144
+ # the exact line that puts it there (no npx: Node may be rer's own).
145
+ no_next=
146
+ if [ "$#" -gt 0 ]; then no_next=1; fi
147
+ RER_INSTALL_CHANNEL=script RER_INSTALL_NO_NEXT=$no_next node "$work/stage/package/global/rer.mjs" cli install </dev/null \
143
148
  || fail "rer cli install failed; any previous install is still selected."
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
- fi
149
+ if [ "$#" -eq 0 ]; then return; fi
149
150
  PATH="$HOME/.local/bin:$PATH"
150
151
  export PATH
151
152
  "$HOME/.local/bin/rer" "$@"
@@ -133,6 +133,7 @@ version), domain rules in `oa_domain_rules`. `auth.accounts` exposes it and
133
133
  | `/auth/owner-signin?token=…` | GET/HEAD | 200 owner sign-in confirmation for a live `rer signin` link, or 400 invalid/used/expired; **no writes** |
134
134
  | `/auth/owner-signin` | POST | token; consume once for the active owner it names, 303 with cookie; see "Owner sign-in without mail" |
135
135
  | `/auth/email` | POST | email; the signed-in operator's own sign-in email; fresh step-up proof; 409 `email_in_use` |
136
+ | `/auth/display-name` | POST | displayName; the signed-in operator's own name (1-120 characters); no step-up |
136
137
 
137
138
  Unknown `/auth/*` paths return 404. Unsupported methods return 405. Except for invalid/expired confirmation GET/HEAD documents, known public
138
139
  errors are JSON `{error:code}`: invalid input 400, unauthenticated 401, policy/host/
@@ -476,6 +477,10 @@ link). It revokes unused links sent to the old address and keeps sessions and
476
477
  provider bindings. An address another operator holds is refused with
477
478
  `email_in_use`. `STEP_UP_ACTIONS` gains `email:change`.
478
479
 
480
+ A name is corrected the same way, without a step-up: `POST /auth/display-name
481
+ {displayName}`. First-run `/setup` shows the owner's name as an editable field
482
+ that saves through it. Native accounts do not mount this route.
483
+
479
484
  ## Local dev identity and the key gate
480
485
 
481
486
  `dev-gate.mjs` (exported as `devGate`, production-safe) is the per-checkout key
@@ -0,0 +1,23 @@
1
+ // A signed-in operator corrects the name shown for them: at first-run setup
2
+ // (/setup) and later from the app's settings. It is not a credential, so no
3
+ // fresh proof is needed; the change is fenced to this session and operator version.
4
+ import { deny } from '../errors.mjs';
5
+ import { requirePost } from '../http.mjs';
6
+ import { displayName } from './admin.mjs';
7
+
8
+ export function displayNameChange({ config, store, clock, authenticate }) {
9
+ return {
10
+ async changeDisplayName(request, input) {
11
+ requirePost(request, config);
12
+ const actor = await authenticate(request);
13
+ if (!actor) deny('unauthenticated', 401);
14
+ const name = displayName(input?.displayName);
15
+ if (name !== actor.operator.displayName) {
16
+ const fence = store.actorFence(actor, clock());
17
+ const [changed] = await store.batch([[`UPDATE oa_operators SET display_name=? WHERE id=? AND version=? AND ${fence.sql} RETURNING id`, [name, actor.operator.id, actor.operator.version, ...fence.args]]]);
18
+ if (!changed.results.some(row => row.id === actor.operator.id)) deny('authority_changed', 409);
19
+ }
20
+ return store.operator(actor.operator.id);
21
+ },
22
+ };
23
+ }
@@ -196,6 +196,8 @@ export interface OperatorAuth<R extends string = Role> {
196
196
  confirmOwnerSignIn?(request: Request, input: { token: string }): Promise<CompletedSession<R>>;
197
197
  /** The signed-in operator's own sign-in email; needs a fresh step-up proof. */
198
198
  changeEmail?(request: Request, input: { email: string }): Promise<Operator<R>>;
199
+ /** The signed-in operator's own display name (1-120 characters, trimmed). Absent with native accounts. */
200
+ changeDisplayName?(request: Request, input: { displayName: string }): Promise<Operator<R>>;
199
201
  listDomainRules(request: Request): Promise<DomainRule[]>;
200
202
  /** provider null lifts the rule. Needs a fresh step-up proof. */
201
203
  setDomainRule(request: Request, input: { domain: string; provider: string | null }): Promise<DomainRule[]>;
@@ -41,8 +41,8 @@ export function createAuthHandler(auth) {
41
41
  const preview = await auth.previewLink(request, token);
42
42
  return await confirmationResponse({ branding: auth.presentation, preview, token, method: request.method });
43
43
  }
44
- // Composition without the owner link or email change (native accounts) does not own these paths.
45
- if ((path === OWNER_SIGNIN_PATH && !auth.confirmOwnerSignIn) || (path === '/auth/email' && !auth.changeEmail)) return json({ error: 'not_found' }, 404);
44
+ // Composition without the owner link, email or name change (native accounts) does not own these paths.
45
+ if ((path === OWNER_SIGNIN_PATH && !auth.confirmOwnerSignIn) || (path === '/auth/email' && !auth.changeEmail) || (path === '/auth/display-name' && !auth.changeDisplayName)) return json({ error: 'not_found' }, 404);
46
46
  if (path === OWNER_SIGNIN_PATH && ['GET', 'HEAD'].includes(request.method)) {
47
47
  const token = readParameters(url.searchParams).token ?? null;
48
48
  const preview = await auth.previewOwnerSignIn(request, token);
@@ -65,7 +65,7 @@ export function createAuthHandler(auth) {
65
65
  if (path === '/auth/settings/identity' && request.method === 'GET') {const value=await auth.identitySettings(request);return /text\/html/.test(request.headers.get('accept')??'')?await identitySettingsPage(value,auth.presentation):json(value);}
66
66
  if (path === '/auth/providers' && request.method === 'GET') return json(await auth.listProviders(request));
67
67
  const posts = new Set(['/auth/bootstrap', '/auth/magic-link', '/auth/confirm', '/auth/signout', '/auth/invite', '/auth/invite/cancel', '/auth/review-session',
68
- '/auth/operator/status', '/auth/operator/role', '/auth/session/revoke', '/auth/step-up', '/auth/domain-rules', '/auth/providers/unlink', '/auth/providers/relink', '/auth/settings/identity', '/auth/setup-complete', OWNER_SIGNIN_PATH, '/auth/email']);
68
+ '/auth/operator/status', '/auth/operator/role', '/auth/session/revoke', '/auth/step-up', '/auth/domain-rules', '/auth/providers/unlink', '/auth/providers/relink', '/auth/settings/identity', '/auth/setup-complete', OWNER_SIGNIN_PATH, '/auth/email', '/auth/display-name']);
69
69
  if (!posts.has(path)) return json({ error: 'not_found' }, 404);
70
70
  if (request.method !== 'POST') return json({ error: 'method_not_allowed' }, 405);
71
71
  const query = readParameters(url.searchParams);
@@ -93,6 +93,7 @@ export function createAuthHandler(auth) {
93
93
  case '/auth/confirm': { const value = await auth.confirmLink(request, input); return seeOther(value.returnTo, value.cookie); }
94
94
  case OWNER_SIGNIN_PATH: { const value = await auth.confirmOwnerSignIn(request, input); return seeOther(value.returnTo, value.cookie); }
95
95
  case '/auth/email': return json(await auth.changeEmail(request, input));
96
+ case '/auth/display-name': return json(await auth.changeDisplayName(request, input));
96
97
  case '/auth/review-session': { const value = await auth.issueReviewSession(request, input); return seeOther(value.returnTo, value.cookie); }
97
98
  case '/auth/step-up': {
98
99
  const result = await auth.requestStepUp(request, input);
@@ -18,6 +18,7 @@ import { createAdmission, legacyAdmission } from './identity/admission.mjs';
18
18
  import { createOidcProviders } from './identity/oidc/index.mjs';
19
19
  import { ownerSignIn } from './accounts/owner-signin.mjs';
20
20
  import { emailChange } from './accounts/email-change.mjs';
21
+ import { displayNameChange } from './accounts/display-name.mjs';
21
22
  import { isLocalCli } from './local-cli.mjs';
22
23
  import { devAdmitted } from './dev-admission.mjs';
23
24
  import { oneClickAccounts } from './accounts/one-click.mjs';
@@ -79,6 +80,7 @@ export function createOperatorAuth(options) {
79
80
  ...fencedCredentials({store,authenticate,requireFreshProof,config,clock,hash}),
80
81
  ...ownerSignIn({ config, store, clock, sessions, limit }),
81
82
  ...emailChange({ config, store, clock, authenticate, requireFreshProof }),
83
+ ...displayNameChange({ config, store, clock, authenticate }),
82
84
  presentation: config.branding,
83
85
  oneClick: oneClickAccounts({ config, store, clock, sessions, authorizedLink, requireRoute, afterConfirm: admission.afterConfirm }),
84
86
  emailSignInAvailable: Boolean(mailSender),
@@ -24,7 +24,7 @@ schema at construction. Apply the bookkeeping migration first. Policy fields:
24
24
  | `derivedTables` | Virtual/FTS tables to regenerate; their shadow tables are excluded. |
25
25
  | `secretColumns` | Per-table nullable base columns omitted at export and written as NULL. Primary keys and generated columns cannot be secret. |
26
26
  | `exportRow(table,row)` | Pure, synchronous, idempotent transformation of encoded base cells. Restore writes its result verbatim; SQLite recomputes generated cells. |
27
- | `replaceableTables` | Bootstrap or migration-seeded rows replaced in the atomic restore batch. Populated excluded dependents reachable through modifying FK actions refuse replacement. |
27
+ | `replaceableTables` | Bootstrap rows replaced in the atomic restore batch. Rows the destination's own migrations insert need no entry where the runner passes `migrations` (see "Migration-seeded rows"). Populated excluded dependents reachable through modifying FK actions refuse replacement. |
28
28
  | `requiredConfiguration` | Setting names returned after restore for the owner to re-enter. |
29
29
  | `validateStaged({db,tables,read,manifest})` | Read-only product validation before any object write; false or a thrown error refuses restore. `tables` names the staging tables for bounded SQL queries; `read` is a convenience for small tables. |
30
30
  | `acceptedSchemas` | Map from an earlier full schema hash to `{upgradeRow(table,row)}`. Upgrade functions are pure and synchronous. No older schema is accepted by default. |
@@ -315,6 +315,18 @@ journal adoption and completion. FK cycles and self-references restore together.
315
315
  An unsuccessful commit removes only owned objects. A lost commit acknowledgement
316
316
  is resolved by reading durable completion before any cleanup.
317
317
 
318
+ ### Migration-seeded rows
319
+
320
+ A fresh destination already holds the rows its own migrations insert, such as a
321
+ seed's default settings. When the runner passes `migrations` (Node runners: a
322
+ scratch replay of the destination's applied migrations), finalize treats a target
323
+ table holding exactly those rows as empty: the archive's rows replace them in the
324
+ restore batch, or they stay when the archive predates the table (an additive
325
+ bridge). The batch repeats the check. Any other row refuses with
326
+ `target_not_empty:<table>`, which the CLI reports with the table's name and the
327
+ export, reset and import commands to run. A Worker import has no replay, so a
328
+ hosted restore still needs such tables in `replaceableTables`.
329
+
318
330
  An empty destination must be reserved for restore: pause destination writers and
319
331
  serialize finalize/abort calls. Product writes to source tables can continue.
320
332
  R2 has no compare-and-swap transaction covering bucket emptiness and writes.
@@ -8,7 +8,7 @@ import { checkManifest, checkPart, ContentVerifier, ArchiveVerifier } from './fo
8
8
  import { fence, mergeJournal, tombstone } from './journal.mjs';
9
9
  import { writeObject } from './payloads.mjs';
10
10
  import { createCopy,sidecar,readCopy,restoreCopy } from './copies.mjs';
11
- import { excludedDependentGuards } from './restore-safety.mjs';
11
+ import { excludedDependentGuards, migrationSeeded, seededCondition } from './restore-safety.mjs';
12
12
  import { additiveBridge, sameSchemaMigrations, appliedMigrations } from './bridge.mjs';
13
13
  import { legacyEmptyGuards, legacyAuditStatements, requireLegacyEmpty } from './legacy-safety.mjs';
14
14
  export async function createImport(context,manifest,actor='direct',legacyRecovery) {
@@ -105,8 +105,20 @@ async function bucketsEmpty(context,row) {
105
105
  }while(cursor);
106
106
  }
107
107
  }
108
- function emptyGuards(context,row) {
109
- return row.metadata.targets.filter(t=>!context.config.replaceableTables.includes(t.name)).map(t=>guard(context.db,`NOT EXISTS(SELECT 1 FROM ${quote(t.name)})`));
108
+ function emptyGuards(context,row,seeded) {
109
+ return row.metadata.targets.filter(t=>!context.config.replaceableTables.includes(t.name) && !seeded.some(s=>s.name===t.name)).map(t=>guard(context.db,`NOT EXISTS(SELECT 1 FROM ${quote(t.name)})`));
110
+ }
111
+ // A fresh installation already holds the rows its own migrations insert (settings and
112
+ // other seeded rows). A table holding exactly those, as a node runner's replay of the
113
+ // applied migrations shows, does not make it non-empty: the archive's rows replace
114
+ // them, or they stay when the archive predates the table. Any other row refuses.
115
+ async function destinationState(context,row) {
116
+ const {db,config}=context,filled=[];
117
+ for(const table of row.metadata.targets) if(!config.replaceableTables.includes(table.name) && await statement(db,`SELECT 1 FROM ${quote(table.name)} LIMIT 1`).first())filled.push(table.name);
118
+ const seeded=await migrationSeeded(db,filled,context.migrations);
119
+ for(const name of filled)insist(seeded.some(s=>s.name===name),'target_not_empty:'+name,409);
120
+ const archived=seeded.filter(s=>row.metadata.manifest.tables.some(t=>t.name===s.name)).map(s=>s.name);
121
+ return {seeded,replaced:[...config.replaceableTables,...archived]};
110
122
  }
111
123
  async function removeOwned(context,id) {
112
124
  const owned=await all(context.db,'SELECT bucket,key FROM rer_portability_owned WHERE job=?',id);
@@ -137,8 +149,8 @@ export async function finalizeImport(context,id,{contentHash,archiveHash,laterJo
137
149
  insist(archiveHash===archive.digest(),'archive_checksum',409);
138
150
  const checked=await fence(db,manifest,row.metadata.copies,laterJournal);
139
151
  if(row.metadata.legacyRecovery)await requireLegacyEmpty(context,row.metadata.legacyRecovery);
140
- for(const table of row.metadata.targets) if(!config.replaceableTables.includes(table.name))insist(!(await statement(db,`SELECT 1 FROM ${quote(table.name)} LIMIT 1`).first()),'target_not_empty:'+table.name,409);
141
- const dependentGuards=await excludedDependentGuards(db,row.metadata.targets,config.replaceableTables);
152
+ const {seeded,replaced}=await destinationState(context,row);
153
+ const dependentGuards=await excludedDependentGuards(db,row.metadata.targets,replaced);
142
154
  await bucketsEmpty(context,row);
143
155
  await refuseDevData(db,row.metadata.copies,row.metadata.targets);
144
156
  await refuseProviderData(db,row.metadata.copies,row.metadata.targets);
@@ -160,11 +172,11 @@ export async function finalizeImport(context,id,{contentHash,archiveHash,laterJo
160
172
  }
161
173
  for(const payload of manifest.payloads)await config.extraPayloads[payload.name].consume(binaryStream(context,id,payload,binaryIndexes),payload);
162
174
  row.phase='complete';row.metadata.contentHash=digest;
163
- await db.batch([db.prepare('PRAGMA defer_foreign_keys=ON'),...emptyGuards(context,row),...dependentGuards,...legacyEmptyGuards(db,row),
175
+ await db.batch([db.prepare('PRAGMA defer_foreign_keys=ON'),...emptyGuards(context,row,seeded),...seeded.map(t=>guard(db,...seededCondition(t))),...dependentGuards,...legacyEmptyGuards(db,row),
164
176
  guard(db,'NOT EXISTS(SELECT 1 FROM rer_portability_epochs WHERE source=? AND epoch>?) AND NOT EXISTS(SELECT 1 FROM rer_portability_state WHERE source_identity=? AND epoch>?)',manifest.sourceIdentity,checked.epoch,manifest.sourceIdentity,checked.epoch),
165
177
  ...row.metadata.targets.map(t=>guard(db,`NOT EXISTS(SELECT 1 FROM ${quote(sidecar(row.metadata.copies[t.name]))} s JOIN rer_portability_journal j ON j.source=? AND j.tombstone=s.rer_portability_tombstone)`,manifest.sourceIdentity)),
166
178
  ...row.metadata.triggers.map(t=>db.prepare(`DROP TRIGGER ${quote(t.name)}`)),
167
- ...config.replaceableTables.map(t=>db.prepare(`DELETE FROM ${quote(t)}`)),
179
+ ...replaced.map(t=>db.prepare(`DELETE FROM ${quote(t)}`)),
168
180
  ...row.metadata.targets.flatMap(t=>restoreCopy(db,t,row.metadata.copies[t.name])),
169
181
  ...row.metadata.triggers.map(t=>db.prepare(t.sql)),...mergeJournal(db,manifest,checked),...legacyAuditStatements(db,row),save(db,row),
170
182
  db.prepare('UPDATE rer_portability_state SET import_job=NULL,applying=0 WHERE id=1'),db.prepare('DELETE FROM rer_portability_guard')]);
@@ -1,5 +1,6 @@
1
1
  import { all, statement, guard, quote, insist } from './storage.mjs';
2
2
  import { canonicalJson } from './hash.mjs';
3
+ import { migrationSeeded, seededCondition } from './restore-safety.mjs';
3
4
 
4
5
  // Recovery requires a new installation, including excluded identity tables and
5
6
  // normally replaceable product rows. Only SQLite/migration/transfer bookkeeping,
@@ -18,34 +19,17 @@ function shadowTables(tables) {
18
19
  }
19
20
  return shadows;
20
21
  }
21
- const imageSql=(table,columns)=>`SELECT json_array(${columns.map(c=>`quote(${quote(c)})`).join(',')}) AS image FROM ${quote(table)}`;
22
- const MAX_SEED_ROWS=10000;
23
-
24
22
  /** What the destination must still hold when the restore commits: `emptyTables` stay empty and
25
- * each of `seededTables` keeps exactly the rows its migrations put there. A table with rows the
26
- * replay of the destination's applied migrations (migrations(), a node runner's scratch database)
27
- * does not produce is listed as to-be-empty, so the preflight refuses it. */
23
+ * each of `seededTables` keeps exactly the rows its migrations put there. A table with other rows
24
+ * is listed as to-be-empty, so the preflight refuses it. */
28
25
  export async function legacyTargetState(db,migrations) {
29
26
  const tables=await all(db,"SELECT name,sql FROM sqlite_master WHERE type='table' AND sql IS NOT NULL ORDER BY name"),shadows=shadowTables(tables);
30
27
  const names=tables.map(t=>t.name).filter(name=>!bookkeeping(name) && !shadows.has(name.toLowerCase()));
31
28
  const filled=[];
32
29
  for(const name of names)if(await statement(db,`SELECT 1 FROM ${quote(name)} LIMIT 1`).first())filled.push(name);
33
- const seeded=[];
34
- if(filled.length && migrations) {
35
- const requests=[];
36
- for(const name of filled)requests.push({name,columns:(await all(db,`SELECT name FROM pragma_table_info(?)`,name)).map(c=>c.name)});
37
- // Without a usable replay no seed is vouched for, so those rows count as the installation's own.
38
- const expected=await migrations().then(replay=>replay.rowImages(requests,MAX_SEED_ROWS),()=>new Map());
39
- for(const {name,columns} of requests) {
40
- const want=expected.get(name);
41
- if(!want || (await statement(db,`SELECT count(*) AS n FROM ${quote(name)}`).first()).n!==want.length)continue;
42
- const found=(await all(db,imageSql(name,columns))).map(r=>r.image).sort();
43
- if(canonicalJson(found)===canonicalJson(want))seeded.push({name,columns,images:found});
44
- }
45
- }
30
+ const seeded=await migrationSeeded(db,filled,migrations);
46
31
  return {emptyTables:names.filter(name=>!seeded.some(s=>s.name===name)),seededTables:seeded};
47
32
  }
48
- const seededCondition=table=>[`(SELECT count(*) FROM ${quote(table.name)})=? AND NOT EXISTS(SELECT 1 FROM (${imageSql(table.name,table.columns)}) WHERE image NOT IN (SELECT value FROM json_each(?)))`,table.images.length,JSON.stringify(table.images)];
49
33
  export async function requireLegacyEmpty({db,buckets},{emptyTables,seededTables=[]}) {
50
34
  for(const table of emptyTables)insist(!(await statement(db,`SELECT 1 FROM ${quote(table)} LIMIT 1`).first()),'legacy_target_not_empty:'+table,409);
51
35
  for(const table of seededTables){const [condition,...values]=seededCondition(table);insist((await statement(db,`SELECT CASE WHEN (${condition}) THEN 1 ELSE 0 END AS ok`,...values).first()).ok===1,'legacy_target_not_empty:'+table.name,409);}
@@ -1,4 +1,5 @@
1
1
  import { all,statement,guard,quote,insist } from './storage.mjs';
2
+ import { canonicalJson } from './hash.mjs';
2
3
  const identifier=value=>value.replace(/[A-Z]/g,c=>c.toLowerCase());
3
4
 
4
5
  export async function excludedDependentGuards(db,targets,replaceable) {
@@ -28,3 +29,25 @@ export async function excludedDependentGuards(db,targets,replaceable) {
28
29
  }
29
30
  return guards;
30
31
  }
32
+ const imageSql=(table,columns)=>`SELECT json_array(${columns.map(c=>`quote(${quote(c)})`).join(',')}) AS image FROM ${quote(table)}`;
33
+ const MAX_SEED_ROWS=10000;
34
+
35
+ /** Of the filled tables `names`, those holding exactly the rows the replay of the destination's
36
+ * applied migrations (migrations(), a node runner's scratch database) leaves there: the settings
37
+ * and other rows a fresh installation's own migrations seed. Without a usable replay none is. */
38
+ export async function migrationSeeded(db,names,migrations) {
39
+ if(!names.length || !migrations)return [];
40
+ const requests=[];
41
+ for(const name of names)requests.push({name,columns:(await all(db,`SELECT name FROM pragma_table_info(?)`,name)).map(c=>c.name)});
42
+ // Without a usable replay no seed is vouched for, so those rows count as the installation's own.
43
+ const expected=await migrations().then(replay=>replay.rowImages(requests,MAX_SEED_ROWS),()=>new Map()),seeded=[];
44
+ for(const {name,columns} of requests) {
45
+ const want=expected.get(name);
46
+ if(!want || (await statement(db,`SELECT count(*) AS n FROM ${quote(name)}`).first()).n!==want.length)continue;
47
+ const found=(await all(db,imageSql(name,columns))).map(r=>r.image).sort();
48
+ if(canonicalJson(found)===canonicalJson(want))seeded.push({name,columns,images:found});
49
+ }
50
+ return seeded;
51
+ }
52
+ /** The SQL condition (with its values) that `table` still holds exactly its seeded rows. */
53
+ export const seededCondition=table=>[`(SELECT count(*) FROM ${quote(table.name)})=? AND NOT EXISTS(SELECT 1 FROM (${imageSql(table.name,table.columns)}) WHERE image NOT IN (SELECT value FROM json_each(?)))`,table.images.length,JSON.stringify(table.images)];
@@ -16,13 +16,15 @@ async function bind(host, port) {
16
16
  // A failed diagnostic is unknown, never evidence of a foreign owner. A real
17
17
  // bind can still prove availability. If a bind loses a race but inspection
18
18
  // finds no listener, retry the bind within the same inspection deadline.
19
- export async function probePort(host, port, { context = inspectionContext({ port }), hosts = [host], anyAddress = false } = {}) {
19
+ // A free-port search (`searching`) only needs to move on from a port in use:
20
+ // it skips one on the failed bind alone, without the slow ownership check.
21
+ export async function probePort(host, port, { context = inspectionContext({ port }), hosts = [host], anyAddress = false, searching = false } = {}) {
20
22
  const bindings = async () => {
21
23
  for (const address of hosts) { const result = await bind(address, port); if (!result.available) return result; }
22
24
  return { available: true };
23
25
  };
24
26
  let bound = await bindings(), listener, unchecked;
25
- if (!bound.available && bound.code !== 'EADDRINUSE') return bound;
27
+ if (!bound.available && (bound.code !== 'EADDRINUSE' || searching)) return bound;
26
28
  try { listener = await portListener(port, anyAddress ? undefined : host, context); }
27
29
  catch (error) { if (!uncheckedInspection(error)) throw error; unchecked = error; }
28
30
  if (listener) return { available: false, listener };
@@ -2,7 +2,7 @@ import {execFile} from 'node:child_process';
2
2
  import {promisify} from 'node:util';
3
3
  import {lstat,realpath,readFile,readdir,readlink} from 'node:fs/promises';
4
4
  import {basename,join} from 'node:path';
5
- import {homedir} from 'node:os';
5
+ import {availableParallelism,homedir,loadavg} from 'node:os';
6
6
  import {isIP} from 'node:net';
7
7
  import {setTimeout as delay} from 'node:timers/promises';
8
8
  import {commandFailure,approvedFailure} from './failures.mjs';
@@ -13,6 +13,9 @@ const exec=promisify(execFile);
13
13
  const lsof=process.platform==='darwin'?'/usr/sbin/lsof':'lsof';
14
14
  // One monotonic budget covers every command in an ownership decision.
15
15
  export const inspectionContext=({budgetMs=15000,...details}={})=>({deadline:performance.now()+budgetMs,budgetMs,...details});
16
+ // A free-port search on a busy computer gets longer, still bounded: the budget
17
+ // grows with the 1-minute load per CPU, up to four times.
18
+ export const searchContext=(details={})=>inspectionContext({budgetMs:Math.round(15000*Math.min(4,Math.max(1,loadavg()[0]/availableParallelism()))),...details});
16
19
  export const uncheckedInspection=error=>approvedFailure(error)?.ownershipUnchecked===true;
17
20
  const run=async(command,args,context=inspectionContext(),{maxBuffer=1024*1024,noMatch=false,positiveResult}={})=>{
18
21
  const invocation=[command,...args].join(' ').replaceAll(homedir(),'~');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runeditrun/rer",
3
- "version": "0.2.42",
3
+ "version": "0.2.43",
4
4
  "description": "The rer command: install, set up, run and launch Run Edit Run checkouts.",
5
5
  "license": "MIT",
6
6
  "type": "module",