@runeditrun/rer 0.0.0-stage → 0.1.1

package/onboarding/README.md

@@ -0,0 +1,163 @@
+# Shared local setup lifecycle
+
+First-party seeds expose public operations through the RER dispatcher. From a
+runnable seed checkout, the supported local sequence begins with
+`rer install`, `rer setup` and
+`rer dev`; owner sign-in uses the printed local outbox. The
+command contract and flags are documented in the runnable checkout's root
+`RUN-LOCALLY.md`.
+
+This directory contains the shared lifecycle and adapter helpers used by a
+seed's RER setup and runtime commands. It centralizes manifest validation,
+private settings, captured child commands, owner bootstrap, sign-in, local
+state safety, readiness and cleanup. A seed declares its actual product inputs
+and effects; the shared lifecycle does not create a product fallback or
+provider behavior.
+
+## Adapter contract
+
+A first-party adapter in `scripts/installer/local.mjs` exports `commandAdapter`
+and its setup hooks. The command adapter selects one root `rer-setup.json`
+manifest and declares real targets and policy for dependencies, build,
+migrations, development, preview, verification, deployment and portability.
+Package scripts for public verbs run the vendored `scripts/rer.mjs` with the verb;
+internal targets use different names so the CLI cannot call its own alias
+recursively.
+
+The shared setup lifecycle supports these hooks: `node`, `tools`, `prepare`,
+`prepareData`, `dependencies`, `origin`, `secrets`, `build`, `migrate`, `start`, `health`,
+`owner`, `signIn`, `hosting`, `guard`, `failure`, `features` and
+`sessionSecretKey` (the setting that holds the application's session secret,
+default `SESSION_SECRET`; a seed whose settings call it `AUTH_SECRET` declares
+that). `prepareData` runs before `rer export` and `rer import`: declare it when those commands read
+files the seed generates (a generated Worker config, for one) so a copy that never ran
+setup or build still completes. It takes no input and must be safe to repeat. Setup also stops, before any request, when the process listening on the
+expected port is not the one it started. A hook can
+declare an argv command or use its provided context and command store. The
+adapter owns real migrations, resource names, auth hooks, settings names, data
+policy and deployment effects. The CLI owns parsing, public flags, pins,
+containment, locking, capture, cancellation, output, exit mapping and
+sequencing.
+
+For `rer setup`, `dev` and `preview`, a custom `start` hook must bind its app
+to `127.0.0.1:context.runtimePort`. rer's traffic proxy owns the port in
+`context.origin`; use `context.origin` for public URLs and cookies, rather
+than as the app's listening address.
+
+A seed that declares `devIdentity` on its command adapter gets the key-gated way
+in from the installer without declaring anything more: before setup the installer
+creates the checkout's dev key (as `rer setup` does) and passes it to the hooks as
+`context.devKey`. The `start` hook must give it to the temporary app (an
+`RER_DEV_KEY` binding), because the `signIn` request reaches the key-gated outbox
+with it. When setup completes, the installer page offers the outbox through the
+key exchange (`RER_OPEN`); the key never enters saved state or logs. A seed
+without `devIdentity` gets no key and its installer is unchanged.
+
+`rer-setup.json` is the only setup schema. Its fields, groups, defaults,
+conditional requirements and ordered steps define which answers are accepted.
+Secrets are read privately from declared inputs, generated only where the
+manifest specifies a generation method, and never accepted as CLI values.
+`--owner-email` maps to the manifest's owner-claim field. A non-interactive
+setup must supply every required answer; it never silently adopts the git
+identity. Conflicting flag and answer-file values fail before effects.
+
+## Seed theme
+
+A seed dresses Base's installer and its shared sign-in and first-run frames in
+its own look by declaring one theme: a plain CSS file at the root of the
+directory its app serves as `/`, conventionally `public/rer-theme.css`. The file
+holds only a `:root { }` block of `--rer-*` tokens and `@font-face` rules for
+font files the app already serves; anything else is refused.
+
+| Token | Value | Used for |
+| --- | --- | --- |
+| `--rer-page`, `--rer-surface` | `#rgb`/`#rrggbb` | page backdrop; cards and panels |
+| `--rer-text`, `--rer-muted` | colour | body text; secondary text |
+| `--rer-border` | colour | input and control boundaries |
+| `--rer-focus` | colour | focus outlines |
+| `--rer-accent`, `--rer-accent-text` | colour, declared together (optional) | primary buttons |
+| `--rer-link` | colour (optional, defaults to text) | links and edit actions |
+| `--rer-font-body`, `--rer-font-heading` | font stack (optional) | text; headings and product name |
+| `--rer-radius` | `px` or `rem` length (optional) | cards, inputs, buttons |
+| `--rer-logo` | `url("/path")` to an svg, png or webp the app serves (optional) | mark beside the product name |
+
+Contrast is checked against the declared colours before the installer starts:
+text on page and surface, muted text on page and surface, links on surface and
+accent text on accent need 4.5:1; focus on page and surface and borders on
+surface need 3:1. A failing pair is named with its ratio. Every `url()` must
+name a same-origin file under the served directory.
+
+The app must serve the file at `/rer-theme.css` with its fonts and logo; a
+Worker that runs first and admits only listed static paths lists it too. If the
+file cannot load, the frames fall back to readable neutrals.
+
+Declare the theme in two places that name the same file:
+
+- the installer seed descriptor (`scripts/installer/seed.mjs`) returns
+  `theme: 'public/rer-theme.css'`, a root-relative path. The installer then
+  links it, serves exactly the files it names, and loads its own token skin
+  (`ui/theme.css`); the product name stays the descriptor's
+  `branding.name`/`product`, and with no `--rer-accent` the buttons keep
+  `branding.accent`.
+- the Worker passes the served path to Base's frames: operator-auth
+  `branding: { productName, theme: '/rer-theme.css' }` for sign-in confirmation,
+  and `firstRunResponse(request, bindings, auth, { theme: { href:
+  '/rer-theme.css', productName, accentColor? } })` from `src/base/setup` for
+  `/setup`; the foundation sign-in uses `themeFrame` from
+  `src/base/theme-frame` the same way, and the development outbox takes
+  `createDevelopmentOutboxHandler({ ..., theme: '/rer-theme.css' })`.
+  `accentColor` colours buttons when the theme declares no accent. A seed's own
+  pages may read the same tokens by linking the file.
+
+Without a theme every page is unchanged. `default-seed/public/rer-theme.css`
+and the foundation template's `public/rer-theme.css` are worked examples.
+
+## Setup behavior and custody
+
+Setup validates answers before effects, then uses the declared lifecycle to
+prepare local state, private settings, build and migrations, start the real
+application briefly, prepare the first owner and verify ordinary sign-in via
+the loopback development outbox. It stops the temporary app before returning.
+Reruns preserve an existing owner, data and exact settings bytes; setup does
+not create a second owner or rotate secrets. Dev and preview use the saved
+owner and canonical durable state. A normal sign-in uses the same local
+outbox; no external email is sent by local commands.
+
+Adapters use the shared captured command store for child work. It redacts
+registered credential values from terminal output and private logs, records
+child outcomes, and stops owned descendants on failure or cancellation.
+Readiness checks the application's real health endpoint and obeys cancellation
+and deadlines. Builds temporarily remove declared private files from the build
+environment and restore their exact bytes and permissions afterward. Do not
+pass secrets in argv, print credentials, or substitute mocks for app behavior.
+
+Canonical local durable data is `.wrangler/state`; CLI bookkeeping is
+`.rer/local`; setup drafts and logs are under `.seed/installer`. Private
+settings use mode 0600 and secret-bearing directories use mode 0700. State
+selection rejects unsafe symlinks, traversal and overlap with source, exports,
+dependencies or build outputs. Ambiguous existing state is preserved for
+explicit recovery rather than adopted, moved or deleted silently. Reset uses
+the adapter's declared removal inventory and preserves source, dependencies,
+exports and deployment receipts.
+
+## Data, deployment and verification
+
+Each first-party adapter declares which resources local export/import supports.
+Every first-party seed verifies a complete local export/import/export round
+trip across those resources. Archives are private and integrity-checked;
+owner/auth, outbox, private settings and transient runtime state remain
+excluded. Import validates and restores atomically into an empty destination.
+Remote transfer is supported only when every required resource has a complete
+adapter implementation; unsupported targets fail visibly.
+
+Deployment uses each seed's actual owner-account declaration, resource policy,
+migrations and health check. Dry run validates and builds locally without
+provider requests. Local tests and structural checks do not establish hosted
+acceptance or external mail delivery.
+
+Keep server authorization in every private handler, including direct server
+function transports, and keep server-only code and secrets out of browser
+bundles. Preserve applied migration history and use verified forward
+migrations for schema changes. Keep files focused and choose shared source
+placement for maintainability; a seed may adapt its stack and integration to
+its real product requirements.

package/onboarding/activity.mjs

@@ -0,0 +1,31 @@
+// Activity is session-only: a restarted process must not imply work is still running.
+const topics = Object.freeze({workspace:'workspace details',owner:'owner details',hosting:'hosting details',email:'email setup',setup:'setup details'});
+const phases = Object.freeze({checking:'Checking',needs_input:'Needs your input for',complete:'Finished checking'});
+export function validateAgentActivity(input) {
+ if(!input||typeof input!=='object'||Array.isArray(input)||Object.keys(input).some(key=>!['phase','topic'].includes(key))||!Object.hasOwn(phases,input.phase)||!Object.hasOwn(topics,input.topic))throw Error('Choose a supported activity phase and topic.');
+ return {phase:input.phase,topic:input.topic};
+}
+export function createActivity(state,allowedFields=Object.keys(state.draft??{})) {
+ const accepted=new Set(allowedFields);
+ state.activity=[];state.agent={mode:'manual',attached:false,attachedAt:null,lastSeenAt:null};let sequence=0;
+ const attach=()=>{const at=new Date().toISOString();state.agent={mode:'connected',attached:true,attachedAt:state.agent.attachedAt||at,lastSeenAt:at};};
+ const append=(source,phase,topic,message,keys)=>{
+  const previous=state.activity.at(-1);
+  if(previous?.source===source&&previous.phase===phase&&previous.topic===topic&&previous.message===message&&JSON.stringify(previous.keys)===JSON.stringify(keys))return previous;
+  const entry={id:++sequence,at:new Date().toISOString(),source,phase,topic,message,...(keys?{keys}: {})};
+  state.activity.push(entry);state.activity=state.activity.slice(-24);return entry;
+ };
+ return {
+  agent(input){const {phase,topic}=validateAgentActivity(input);attach();return append('agent',phase,topic,`${phases[phase]} ${topics[topic]}.`);},
+  filled(keys){const safe=keys.filter(key=>accepted.has(key));if(safe.length){attach();return append('agent','filled','setup',`Updated ${safe.length} setup ${safe.length===1?'field':'fields'}.`,safe);}},
+  secrets(){attach();return append('agent','filled','credentials','Supplied credentials securely for the current setup details.');},
+  provider(provider,status){
+   if(!['cloudflare','github'].includes(provider))return;
+   const name=provider==='cloudflare'?'Cloudflare':'GitHub';
+   const states={starting:['checking',`Starting ${name} sign-in.`],awaiting_browser:['needs_input',`Complete ${name} sign-in in your browser.`],refreshing:['checking',`Checking ${name} connection.`],connected:['complete',`${name} connection confirmed.`],auth_required:['needs_input',`${name} sign-in is required.`],not_installed:['needs_input',`${name} command-line tool is required.`],failed:['failed',`${name} connection was not confirmed.`],cancelled:['failed',`${name} sign-in was cancelled.`]};
+   const entry=states[status];if(entry)return append('provider',entry[0],provider,entry[1]);
+  },
+  step(message){return append('installer','checking','installation',message);},
+  phase(phase){if(phase==='complete')return append('installer','complete','installation','Installation completed.');if(phase==='failed')return append('installer','failed','installation','Installation stopped. Review the installation details.');},
+ };
+}

package/onboarding/adapter-auth.mjs

@@ -0,0 +1,88 @@
+import { approveSetupDependencies } from './dependency-approval.mjs';
+import { createHmac } from 'node:crypto';
+import {commandFailure,installationFailure} from './failures.mjs';
+import { labels } from './adapter-labels.mjs';
+const outboxPath = '/__dev/outbox'; // modules/mail/src/development default path
+
+// The CLI's own requests to its loopback server prove they come from the
+// installation's owner-side tooling (modules/operator-auth/local-cli.mjs), so
+// setup and dev restarts do not spend the owner's sign-in rate limit. A server
+// that is not in local mode ignores the header. The proof comes from the
+// setting the seed's adapter declares as its session secret (sessionSecretKey,
+// default SESSION_SECRET).
+const localCliProof = secret => createHmac('sha256', secret).update('local-cli\0sign-in').digest('hex');
+const post = (context, path, body) => {
+ const secret = context.vars[context.sessionSecretKey ?? 'SESSION_SECRET'];
+ return fetch(new URL(path, context.origin), {
+  method: 'POST', redirect: 'manual', signal: context.signal,
+  headers: { Origin: context.origin, 'Content-Type': 'application/json', ...(typeof secret === 'string' && secret ? { 'x-rer-local-cli': localCliProof(secret) } : {}) }, body: JSON.stringify(body),
+ });
+};
+const errorCode = async response => { try { const code = (await response.json())?.error; return typeof code === 'string' && /^[a-z_]{1,64}$/.test(code) ? code : 'no code'; } catch { return 'no code'; } };
+
+// Claim the first owner through Base operator-auth POST /auth/bootstrap with
+// the private setup token, or run the seed's own documented bootstrap. An
+// already claimed installation keeps its owner.
+export async function owner(context, hook) {
+ const { store } = context;
+ await store.step(labels.owner);
+ await approveSetupDependencies(context, post, outboxMessages);
+ if(context.ownerClaim?.mode==='idp'){context.ownerClaimed='pending-idp';await store.step('The linked provider must grant the designated installation owner');return;}
+ const { path = '/auth/bootstrap', tokenKey = context.ownerClaim?.tokenField ?? 'SETUP_TOKEN', displayName = input => input.displayName || input.name || 'Owner', returnTo = '/' } = hook;
+ const token = context.vars[tokenKey];
+ if (!token && hook.existingOwnerViaSignIn) { await store.step('Checking the existing owner through ordinary sign-in'); return; }
+ if (!token) {
+  throw authFailure(context,labels.owner,`${tokenKey} is missing from the private settings.`);
+ }
+ let response;
+ try { response = await post(context, path, { token, displayName: displayName(context.input), returnTo }); } catch (error) {
+  if (context.signal?.aborted) throw error;
+  throw authFailure(context,labels.owner,'the application did not answer.');
+ }
+ if (response.status === 303) { await response.body?.cancel(); context.ownerClaimed = 'claimed'; await store.step('First owner claimed'); return; }
+ const code = await errorCode(response);
+ if (response.status === 409 && code === 'already_initialized') { context.ownerClaimed = 'kept'; await store.step('An owner is already claimed; the existing owner was kept'); return; }
+ throw authFailure(context,labels.owner,`HTTP ${response.status} (${code}).`);
+}
+
+// Request a sign-in link for the owner, then find it in the Base development
+// outbox. The installer finishes on that captured message, so a local trial
+// needs no mail provider and no email is sent.
+export async function signIn(context, hook) {
+ const { store } = context;
+ if(context.ownerClaim?.mode==='idp' && context.ownerClaimed==='pending-idp')return;
+ await store.step(labels.signIn);
+ if (typeof hook === 'function') { context.appUrl = await hook(context); return; }
+ const { magicLink = '/auth/magic-link', outbox = outboxPath, email = input => context.ownerClaim ? (context.vars[context.ownerClaim.emailField] ?? input[context.ownerClaim.emailField]) : input.email ?? input.ownerEmail, emailKey, returnTo = '/', attempts = 50 } = hook;
+ const address = context.signInEmail ?? (emailKey ? context.vars[emailKey] : email(context.input));
+ if (typeof address !== 'string' || !address.includes('@')) { throw authFailure(context,labels.signIn,'no owner email.'); }
+ const before = new Set(await outboxMessages(context, outbox, address, true));
+ let response;
+ try { response = await post(context, magicLink, { email: address, returnTo }); } catch (error) {
+  if (context.signal?.aborted) throw error;
+  throw authFailure(context,labels.signIn,'the application did not answer.');
+ }
+ if (response.status !== 202) { throw authFailure(context,labels.signIn,`HTTP ${response.status} (${await errorCode(response)}).`); }
+ await response.body?.cancel();
+ for (let attempt = 0; attempt < attempts; attempt++) {
+  const id = (await outboxMessages(context, outbox, address)).find(message => !before.has(message));
+  if (id) { context.appUrl = new URL(`${outbox}?message=${encodeURIComponent(id)}`, context.origin).href; await store.step('Your sign-in link is waiting in the development outbox'); return; }
+  await new Promise(resolve => setTimeout(resolve, 200));
+ }
+ throw authFailure(context,labels.signIn,'no message reached the development outbox. Check that the retained database owner matches the private owner settings; preserve data or run rer reset --yes.');
+}
+
+async function outboxMessages(context, path, address, required = false) {
+ let response;
+ // A dev-identity seed gates its outbox with the checkout's key; present it.
+ try { response = await fetch(new URL(path, context.origin), { signal: context.signal, headers: context.devKey ? { 'x-rer-dev-key': context.devKey } : {} }); } catch (error) {
+  if (context.signal?.aborted) throw error;
+  if(required){context.store.report?.('Local development outbox is unavailable. Run rer setup before requesting sign-in.');throw context.fail('setup');}
+  return [];
+ }
+ if (!response.ok) { await response.body?.cancel();if(required){context.store.report?.('Local development outbox is unavailable. Run rer setup before requesting sign-in.');throw context.fail('setup');}return []; }
+ const html = await response.text(), wanted = `To: ${address.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))}</p>`;
+ return html.split('<article>').slice(1).filter(article => article.toLowerCase().includes(wanted.toLowerCase())).map(article => /\?message=([^"&]+)"/.exec(article)?.[1]).filter(Boolean).map(decodeURIComponent);
+}
+
+function authFailure(context,label,reason){const message=context.store.redact?.(`${label}: ${reason}`)??`${label}: ${reason}`;context.store.report?.(message);return installationFailure('command_failed',{step:'setup',diagnostic:commandFailure(message)});}

package/onboarding/adapter-hosting.mjs

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { labels } from './adapter-labels.mjs';
+
+// The optional hosting hook: deploy to the owner's own Cloudflare account with
+// Base deploy-kit owner-account mode (modules/deploy-kit/owner-cli.mjs, copied
+// by the seed), then check the deployed /health. It runs only when the owner
+// chose the remote target in the shared hosting group, with the account id and
+// API token from that group; `secrets(context)` adds the first-deploy secrets
+// the declaration names. The token and those secrets reach only the deploy
+// command's environment and are registered for redaction first.
+export function ownerAccountHosting({ cli, declaration = 'deploy.json', environment = 'production', product, state, secrets, when = input => input.target === 'remote' } = {}) {
+ if (typeof cli !== 'string' || !cli) throw new TypeError('Name the seed\'s copy of deploy-kit owner-cli.mjs.');
+ return async context => {
+  const { input, store, root } = context;
+  if (!when(input)) { await store.step('Hosting was not requested; the application runs on this computer'); return; }
+  const { accountId, apiToken } = input;
+  if (!/^[a-f0-9]{32}$/i.test(accountId ?? '') || typeof apiToken !== 'string' || !apiToken || /[\r\n]/.test(apiToken)) {
+   store.report?.(`${labels.hosting}: choose a Cloudflare account and supply its API token.`);
+   throw context.fail('deploy');
+  }
+  const extra = typeof secrets === 'function' ? await secrets(context) : secrets ?? {};
+  store.addSecrets?.([apiToken, ...Object.values(extra).filter(value => typeof value === 'string')]);
+  const env = { ...process.env, ...extra, CLOUDFLARE_ACCOUNT_ID: accountId, CLOUDFLARE_API_TOKEN: apiToken };
+  const args = ['--declaration', declaration, '--environment', environment, ...(product ? ['--product', product] : []), ...(state ? ['--state', state] : [])];
+  await context.run(labels.hosting, process.execPath, [cli, 'deploy', ...args], { step: 'deploy', env });
+  await context.run('Checking the deployed application', process.execPath, [cli, 'health', ...args], { step: 'deploy', env });
+  let receipt;
+  try { receipt = JSON.parse(await readFile(resolve(root, state ?? join('.rer', 'deploy', `${environment}.json`)), 'utf8')).receipt; } catch {}
+  const origin = typeof receipt?.origin === 'string' && /^https:\/\/[^\s/]+$/.test(receipt.origin) ? receipt.origin : undefined;
+  if (origin) context.hostedUrl = origin;
+  await store.step(origin ? `Deployed to ${origin}` : 'Deployed to your Cloudflare account');
+ };
+}
+

package/onboarding/adapter-labels.mjs

@@ -0,0 +1,13 @@
+export const labels = Object.freeze({
+ prepareData: 'Preparing generated files (prepareData)',
+ dependencies: 'Installing locked dependencies',
+ secrets: 'Saving private local settings',
+ build: 'Building your application',
+ migrate: 'Applying database migrations',
+ start: 'Starting your application on this computer',
+ owner: 'Claiming the first owner',
+ signIn: 'Opening sign-in through the development outbox',
+ hosting: 'Deploying to your Cloudflare account',
+ complete: 'Your application is running locally',
+});
+

package/onboarding/adapter-settings.mjs

@@ -0,0 +1,129 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { labels } from './adapter-labels.mjs';
+import { credentialValues } from './redaction.mjs';
+import { privateDirectory, readPrivateFile, writePrivateFile } from './private-files.mjs';
+import { localVariables } from './local/environment.mjs';
+import { assertRegular, inspect } from './local/files.mjs';
+import { localOperation } from './local/operation.mjs';
+import { recoverInterrupted } from './local/recovery.mjs';
+
+async function freePort() {
+ const socket = createServer();
+ await new Promise((resolve, reject) => { socket.once('error', reject); socket.listen(0, '127.0.0.1', resolve); });
+ const { port } = socket.address();
+ await new Promise(resolve => socket.close(resolve));
+ return port;
+}
+
+// A rerun keeps the loopback origin already saved in the seed's settings, so
+// sessions, links and the owner's bookmarks stay valid.
+async function chooseOrigin(context, hooks) {
+ if (context.selectedOrigin) return context.selectedOrigin;
+ if (typeof hooks.origin === 'function') return hooks.origin(context);
+ const key = hooks.secrets?.originKey;
+ if (key) {
+  const saved = (await readSettings(context.root, hooks.secrets)).values[key];
+  try { const url = new URL(saved); if (url.protocol === 'http:' && url.hostname === '127.0.0.1' && url.port && url.origin === saved) return saved; } catch {}
+ }
+ return `http://127.0.0.1:${await freePort()}`;
+}
+
+async function readSettings(root, { file = '.dev.vars', format = 'dotenv' }) {
+ const path = resolve(root, file);
+ const within = relative(root, path);
+ if (!within || within === '..' || within.startsWith('..' + sep) || isAbsolute(within)) throw new Error('Installer settings must stay inside the checkout.');
+ await privateDirectory(root, within.split(sep).slice(0, -1));
+ const status = await inspect(path);
+ assertRegular(status);
+ if (!status) return { path, values: {}, text: undefined };
+ const text = await readPrivateFile(path);
+ if (format === 'json') {
+  let values;
+  try { values = JSON.parse(text); } catch { throw new Error(`${file} is not valid JSON; restore it before installing.`); }
+  if (!values || typeof values !== 'object' || Array.isArray(values)) throw new Error(`${file} must hold a JSON object.`);
+  return { path, values, text };
+ }
+ return { path, values: localVariables(text), text };
+}
+
+const dotenvValue = value => /^[A-Za-z0-9._@:/+=,-]*$/.test(value) ? value : JSON.stringify(value);
+
+// A kept settings file gains only the managed generated secrets a newer
+// manifest declares and the file lacks (an install from before them). Saved
+// values and bytes are untouched, and an owner-visible token the owner removed
+// stays removed. A file is kept only when it holds an earlier setup's owner
+// (`context.ownerKey`, where the caller names it); one that holds only other
+// keys gains this setup's settings beside them.
+async function keepSettings(current, { manifest, store }, { format = 'dotenv' }) {
+ const added = Object.fromEntries((manifest?.fields ?? []).filter(field => field.kind === 'secret' && field.input === 'managed' && field.generate && !Object.hasOwn(current.values, field.name))
+  .map(field => [field.name, randomBytes(32).toString(field.generate)]));
+ if (!Object.keys(added).length) return current.values;
+ store.addSecrets?.(Object.values(added));
+ const merged = { ...current.values, ...added };
+ await writePrivateFile(current.path, format === 'json' ? JSON.stringify(merged, null, 1) + '\n'
+  : current.text.replace(/\n*$/, '\n').replace(/^\n$/, '') + Object.entries(added).map(([key, value]) => `${key}=${dotenvValue(value)}`).join('\n') + '\n');
+ return merged;
+}
+
+// Generate and store private settings. Approved public/entered answers win;
+// existing generated values and untouched rerun bytes are preserved. Credential
+// values are registered for redaction before any later command can print them.
+// The file is owner-only (0600); both formats are written under the local
+// operation lock after interrupted builds are recovered.
+async function writeSecrets(context, options) {
+ const { root, store } = context;
+ const { generate = [], encoding = 'hex', values, format = 'dotenv' } = options;
+ await store.step(labels.secrets);
+ {
+  const current = await readSettings(root, options);
+  if (options.keepExisting && current.text !== undefined && (!context.ownerKey || current.values[context.ownerKey])) { store.addSecrets?.(credentialValues(current.values, context.manifest?.fields.filter(field => field.kind === 'secret').map(field => field.name))); return keepSettings(current, context, options); }
+  const wanted = { ...(typeof values === 'function' ? await values(context) : values ?? {}) };
+  const manifest=context.manifest;
+  const generated=manifest?manifest.fields.filter(field=>field.kind==='secret'&&field.generate):generate.map(name=>({name,generate:encoding}));
+  if(manifest){
+   for(const field of manifest.fields)if(typeof context.input[field.name]==='string')wanted[field.name]=context.input[field.name];
+  }
+  for (const field of generated)if(!Object.hasOwn(current.values,field.name))wanted[field.name] = randomBytes(32).toString(field.generate);
+  for(const field of manifest?.fields??[])if(field.kind==='secret'&&field.input!=='entered'&&!field.generate&&(field.required||field.presentations?.some(item=>item.required))&&!(current.values[field.name]||wanted[field.name]))throw Error(`Required supplied secret ${field.name} is missing.`);
+  const approved = new Set((manifest?.fields ?? []).filter(field => field.kind !== 'secret' || field.input === 'entered').map(field => field.name));
+  const updates = Object.fromEntries(Object.entries(wanted).filter(([key, value]) => typeof value === 'string' &&
+   (!Object.hasOwn(current.values, key) || (approved.has(key) && current.values[key] !== value))));
+  for (const [key, value] of Object.entries(updates)) if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || /[\r\n\0]/.test(value)) throw new TypeError(`Unsupported local setting ${key}.`);
+  store.addSecrets?.((manifest?.fields??[]).filter(field=>field.kind==='secret').flatMap(field=>[current.values[field.name],wanted[field.name]]).filter(Boolean));
+  const merged = { ...current.values, ...updates };
+  store.addSecrets?.([...generated.map(field => merged[field.name]).filter(Boolean), ...(manifest?.fields??[]).filter(field=>field.kind==='secret').map(field=>merged[field.name]).filter(Boolean), ...credentialValues(merged)]);
+  if (Object.keys(updates).length) {
+   const replacing = Object.keys(updates).some(key => Object.hasOwn(current.values, key));
+   const text = format === 'json'
+    ? JSON.stringify(merged, null, 1) + '\n'
+    : (replacing ? '' : (current.text === undefined ? '' : current.text.replace(/\n*$/, '\n').replace(/^\n$/, ''))) + Object.entries(replacing ? merged : updates).map(([key, value]) => `${key}=${dotenvValue(value)}`).join('\n') + '\n';
+   await writePrivateFile(current.path, text);
+  }
+  return merged;
+ }
+}
+
+// Setup on another port moves the checkout: only the saved origin changes.
+// The key is the one the CLI reads (the declared originKey, else AUTH_ORIGIN).
+async function moveSavedOrigin(context, options, values) {
+ const key = options.originKey ?? 'AUTH_ORIGIN', origin = context.selectedOrigin;
+ if (!origin || values[key] === undefined || values[key] === origin) return values;
+ const current = await readSettings(context.root, options), format = options.format ?? 'dotenv', merged = { ...values, [key]: origin };
+ const text = format === 'json' ? JSON.stringify(merged, null, 1) + '\n' : current.text.replace(new RegExp(`^${key}=.*$`, 'm'), `${key}=${dotenvValue(origin)}`);
+ if (format !== 'json' && localVariables(text)[key] !== origin) throw new Error(`Could not move ${key} in ${options.file ?? '.dev.vars'}; put ${key}=${origin} on its own line.`);
+ await writePrivateFile(current.path, text);
+ return merged;
+}
+
+// Select the origin only after recovery, under the same lock as publication.
+export async function prepareSettings(context, hooks) {
+ const operation = context.operationToken ? await localOperation(context.root, context.operationToken) : await recoverInterrupted(context.root) ?? await localOperation(context.root);
+ try {
+  context.origin = await chooseOrigin(context, hooks);
+  context.vars = await moveSavedOrigin(context, hooks.secrets, await writeSecrets(context, hooks.secrets));
+ } finally { await operation.release(); }
+}
+
+export { freePort, chooseOrigin, readSettings };