@omega.js/manager 0.1.0

package/dist/lib/scaffold.js

@@ -0,0 +1,427 @@
+/**
+ * Brand-monorepo scaffolding — the file plan the onboard wizard writes.
+ *
+ * buildScaffoldPlan() turns the wizard's answers into the plan-§0 skeleton:
+ * config/omega.json5, root package.json (targets/* workspaces), .gitignore, the
+ * .env credential stub, README.md, and a minimal package.json per enabled
+ * target's own dir. applyScaffoldPlan() writes it with fill-missing
+ * semantics: existing files are NEVER touched, so onboarding is idempotent
+ * and re-running it into a partial brand only fills the gaps.
+ *
+ * Target package.jsons carry their framework dep, so install → setup works
+ * without hand-editing; each framework's own setup still owns the consumer
+ * INTERIOR (scripts, config, scaffolded files). The backend's framework is a
+ * RUNTIME dependency (it rides the staged dist/package.json — src/dist
+ * pillar); every other target declares its framework as a devDependency
+ * (build-time only).
+ *
+ * Every `@omega.js/*` spec is an EXACT PIN at the manager's own version
+ * (#794): the family ships lockstep, one number for the whole set, so a
+ * brand can never install a backend from one release beside a client from
+ * another. A caret (or the old `*`) let one target float ahead alone on an
+ * `npm update`; pinned, only `omega update --apply` at the brand root moves it,
+ * and it moves every target together. The local era is untouched — an
+ * existing `file:` spec is never rewritten, because applyScaffoldPlan()
+ * leaves every file that already exists exactly as it is.
+ */
+
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+
+const { TARGET_DIRS, TARGET_FRAMEWORKS } = require('../config.js');
+// The environment vocabulary is @omega.js/config's — the same three names the
+// overlay files are suffixed with and every runtime's environment() answers
+const { ENV_ENVIRONMENTS } = require('../vendor/config/index.js');
+// The canonical group list + renderer live in env-order.js (the ordering
+// SSOT, cp137) — the stub is just a canonical render with generated Omega
+// keys, so a scaffolded .env and a reordered one have the same shape.
+const { renderCanonicalEnv, envLine } = require('./env-order.js');
+// What gets generated (the env schema's `generated` entries) — with
+// env-order.js's serializer above, the same two SSOTs writeEnvValue rides.
+const { generatedEnvKeys } = require('../vendor/config/index.js');
+// The heal's value is the SSOT for the manage script — a scaffolded brand
+// must never be born needing the migration the heal just learned (#229)
+const { MANAGE_SCRIPT } = require('./package-scripts.js');
+
+// The backend framework is a Cloud Functions RUNTIME dependency — the stage
+// step derives dist/package.json from the target manifest's `dependencies`
+// (src/dist pillar). Every other target's framework is build-time only.
+const RUNTIME_DEP_TARGETS = ['backend'];
+
+// The pin every scaffolded @omega.js/* spec carries — the manager's OWN
+// version, read at run time (#794). The family releases lockstep, so the
+// manager's number IS the family's number; nothing here keeps a copy of it.
+const FAMILY_VERSION = require('../../package.json').version;
+
+/**
+ * Render the brand-level config/omega.json5 (fresh brands only — an existing
+ * config is never regenerated). String values go through JSON.stringify, so
+ * user input can't break the file.
+ */
+function renderOmegaConfig(answers) {
+  const lines = [
+    `// ${answers.name} — brand-level omega.json5: the shared config layer every target`,
+    '// under targets/ inherits. Local files override any key per-surface; key presence',
+    '// under `targets` = this brand supports that target. Secrets NEVER live here —',
+    '// they go in the gitignored .env (the loader hard-fails on secret-shaped keys).',
+    '{',
+    '  brand: {',
+    `    id: ${JSON.stringify(answers.id)},`,
+    `    name: ${JSON.stringify(answers.name)},`,
+  ];
+
+  if (answers.description) {
+    lines.push(`    description: ${JSON.stringify(answers.description)},`);
+  }
+  if (answers.tagline) {
+    lines.push(`    tagline: ${JSON.stringify(answers.tagline)},`);
+  }
+
+  lines.push(
+    `    url: ${JSON.stringify(answers.url)},`,
+    '    contact: {',
+    `      email: ${JSON.stringify(answers.email)},`,
+  );
+
+  // The human who signs the personal sends (welcome, nudge, checkup) — asked
+  // for at onboarding, never derived, so an unanswered person writes no key
+  // at all instead of a placeholder identity (#770).
+  if (answers.person) {
+    lines.push('      person: {');
+    for (const [key, value] of Object.entries(answers.person)) {
+      lines.push(`        ${key}: ${JSON.stringify(value)},`);
+    }
+    lines.push('      },');
+  }
+
+  lines.push(
+    '    },',
+    '  },',
+    '',
+    '  // Social handles (platform: "handle") — each entry lights its footer icon, its JSON-LD sameAs entry, and a /<platform> shortlink.',
+    '  socials: {},',
+    '',
+    '  // Project-owned theme — seeded at onboarding, yours to change.',
+    '  theme: {',
+    '    id: "classy",',
+    '    appearance: "system", // "system" | "light" | "dark"',
+    '  },',
+    '',
+    '  // AI translation (web /{lang}/ pages, extension _locales). Provider',
+    '  // "claude" (default) rides the local Claude Code install — no API key;',
+    '  // "chatgpt" needs OPENAI_API_KEY in .env. Uncomment to enable:',
+    '  // translation: {',
+    '  //   languages: ["es", "fr", "de"],',
+    '  // },',
+    '',
+  );
+
+  // Only a CUSTOMIZED admin list lands here — an inherited one (company
+  // config or the built-in support@{domain} default) stays unwritten so the
+  // source layer keeps owning it.
+  if (answers.accountAdmins) {
+    lines.push(
+      '  // Managed Firebase Auth accounts (account service). Passwords never live',
+      '  // here — OMEGA_ACCOUNT_PASSWORD__* env vars, config/hooks/account/password.js,',
+      '  // or the generated ACCOUNT_PASSWORD_SEED.',
+      '  account: {',
+      '    admins: [',
+    );
+    for (const entry of answers.accountAdmins) {
+      lines.push(`      { email: ${JSON.stringify(entry.email)}, account: ${!!entry.account}, marketing: ${!!entry.marketing} },`);
+    }
+    lines.push('    ],', '  },', '');
+  }
+
+  // Backend brands get a bootable cloud project out of the box: demo-* ids
+  // are the emulator-only convention (never touch live Firebase), so the
+  // emulator boots before any real project exists (dogfood friction #3).
+  if (answers.targets.includes('backend')) {
+    lines.push(
+      '  // Cloud project (backend target). demo-* ids are EMULATOR-ONLY — the',
+      '  // emulators boot against this immediately; swap in a real Firebase project',
+      '  // id at launch (the cloud service can create one).',
+      '  cloud: {',
+      '    provider: "firebase",',
+      '    config: {',
+      `      projectId: ${JSON.stringify(`demo-${answers.id}`)},`,
+      '    },',
+      '  },',
+      '',
+    );
+  }
+
+  lines.push(
+    '  // Payment catalog — pricing pages render THESE products (no products =',
+    '  // honest empty state). Uncomment + edit to start selling; ids are',
+    '  // permanent once live. Provider id fields (stripe/paypal/chargebee) are',
+    '  // filled by the payment service — leave them null. Presentation fields',
+    '  // (tagline, popular, features) are optional card garnish.',
+    '  // payment: {',
+    '  //   products: [',
+    '  //     {',
+    '  //       id: "premium",',
+    '  //       name: "Premium",',
+    '  //       type: "subscription",',
+    '  //       tagline: "best for teams",',
+    '  //       popular: true,',
+    '  //       prices: { monthly: 9.99, annually: 99.99 },',
+    '  //       trial: { days: 14 },',
+    '  //       limits: { requests: 10000 },',
+    '  //       features: [{ id: "requests", name: "Requests", icon: "sparkles" }],',
+    '  //     },',
+    '  //     { id: "launch-kit", name: "Launch Kit", type: "one-time", prices: { once: 49.99 } },',
+    '  //   ],',
+    '  // },',
+    '',
+  );
+
+  // App-signing brands get their reverse-DNS bundle prefix derived at
+  // onboarding (parent company's domain when one exists, else the brand's)
+  if (answers.targets.includes('desktop') && answers.bundleIdPrefix) {
+    lines.push(
+      '  // Apple signing (certificates service): reverse-DNS prefix derived from',
+      '  // the company/brand domain at onboarding. Bundle IDs mint as',
+      '  // <prefix>.<brand id with dashes as dots>.',
+      '  certificates: {',
+      '    providers: {',
+      '      apple: {',
+      `        bundleIdPrefix: ${JSON.stringify(answers.bundleIdPrefix)},`,
+      '      },',
+      '    },',
+      '  },',
+      '',
+    );
+  }
+
+  lines.push(
+    '  // Key presence = target enabled; the value is that target\'s type-wide',
+    '  // config (any shared key inside overrides it for that surface).',
+    '  targets: {',
+  );
+
+  for (const target of answers.targets) {
+    lines.push(`    ${target}: {},`);
+  }
+
+  lines.push('  },', '}');
+
+  return `${lines.join('\n')}\n`;
+}
+
+function renderRootPackageJson(answers) {
+  return `${JSON.stringify({
+    name: answers.id,
+    private: true,
+    ...(answers.description ? { description: answers.description } : {}),
+    workspaces: ['targets/*'],
+    // npm scripts put node_modules/.bin on PATH, so plain `omega` (the
+    // context-aware dispatcher) resolves — never the retired omega-manager name
+    // `npm start` boots the dev stack (`dev` stays as its alias); the bare
+    // manage cycle is `npm run manage`
+    scripts: {
+      start: 'omega dev',
+      dev: 'omega dev',
+      manage: MANAGE_SCRIPT,
+      deploy: 'omega deploy',
+    },
+    // Brand-level verbs (`omega dev`, manage, the `start` script above) resolve
+    // @omega.js/manager FROM THE BRAND ROOT (omega-bin dispatch) — without this
+    // declaration nothing installs it outside the monorepo and every brand-root
+    // command dies (cp195 journey catch). Pinned exactly: the root and every
+    // target ride ONE family version (#794).
+    devDependencies: {
+      '@omega.js/manager': FAMILY_VERSION,
+    },
+  }, null, 2)}\n`;
+}
+
+function renderGitignore() {
+  return [
+    '# Dependencies',
+    'node_modules/',
+    '',
+    '# Build output',
+    'dist/',
+    '',
+    '# OMEGA manager state (derived data — never committed)',
+    '.omega/',
+    '',
+    '# Run logs (truncated on every launch — never committed)',
+    'logs/',
+    '',
+    '# Secrets',
+    '.env',
+    '.env.*',
+    '',
+    '# OS',
+    '.DS_Store',
+    '',
+  ].join('\n');
+}
+
+function renderEnvStub(answers) {
+  return renderCanonicalEnv({
+    header: [
+      `# ${answers.name} — brand secrets (gitignored; loaded before every omega run).`,
+      '# Uncomment and fill what this brand uses. Services without their credentials',
+      '# skip cleanly, so add these as the brand adopts each service.',
+    ],
+    // The generated keys and their line form come from the SSOTs the
+    // manage-time mint uses too (#569), so a brand born here and a brand
+    // healed by the env-keys op carry byte-identical shapes.
+    entries: new Map(Object.entries(generatedEnvKeys()).map(([key, generate]) => [key, { raw: envLine(key, generate()) }])),
+  });
+}
+
+/**
+ * An environment overlay stub — a header comment and NOTHING else
+ * ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)). The base `.env`
+ * stays the one file that documents every key (it carries the canonical
+ * placeholder list); an overlay only ever holds the handful a brand wants
+ * different for one environment, so pre-listing anything here would be a second
+ * inventory to drift.
+ *
+ * @param {string} environment - `development` | `testing` | `production`.
+ * @returns {string} The file contents.
+ */
+function renderEnvOverlayStub(environment) {
+  return [
+    `# .env.${environment} — overlays .env when this brand runs in ${environment} (gitignored).`,
+    '# Only the keys that differ — anything not set here falls through to .env.',
+    '',
+  ].join('\n');
+}
+
+function renderReadme(answers) {
+  const targetList = answers.targets
+    .map((target) => {
+      const dir = TARGET_DIRS[target] || target;
+      const framework = TARGET_FRAMEWORKS[target];
+      return `- \`targets/${dir}/\` — the ${target} target${framework ? ` (framework: \`${framework}\`)` : ''}`;
+    })
+    .join('\n');
+
+  return `# ${answers.name}
+
+${answers.description || 'An OMEGA brand monorepo.'}
+
+One repo, every surface of the brand. \`config/omega.json5\` is the single
+source of user choices; \`omega\` reconciles every external service
+to it, idempotently.
+
+## Structure
+
+- \`config/omega.json5\` — brand-level shared config (targets inherit + override)
+${targetList}
+- \`.env\` — credentials (gitignored; see the stub for every service's keys)
+- \`.env.<environment>\` — the per-environment overlay (\`development\`, \`testing\`, \`production\`): only the keys that differ there
+- \`.omega/\` — manager state + run output (gitignored, machine-owned)
+
+## Next steps
+
+1. \`npm install\` — each target declares its framework (workspace link in a
+   monorepo; standalone pre-publish: \`npx mgr i local\` inside each target).
+2. Fill in \`.env\` as the brand adopts external services.
+3. \`npm run manage\` — reconcile everything; rerun any time.
+4. \`npm start\` (\`npx omega dev\`) — boot the local stack; each target's verbs
+   scaffold its consumer interior on first run.
+`;
+}
+
+function renderTargetPackageJson(answers, target, dir) {
+  const framework = TARGET_FRAMEWORKS[target];
+  // The exact family pin (#794): satisfied by a workspace link in-monorepo,
+  // `mgr i local` pre-publish (which flips the spec to `file:`), and the npm
+  // registry once @omega.js/* publish — where the pin is what keeps every
+  // target on ONE framework version.
+  const depKey = RUNTIME_DEP_TARGETS.includes(target) ? 'dependencies' : 'devDependencies';
+
+  // version + author: electron-builder hard-requires version and warns on
+  // author (the cp142 rehearsal catch) — every target gets both, they're healthy
+  return `${JSON.stringify({
+    name: `${answers.id}-${dir}`,
+    version: '0.0.1',
+    author: answers.name,
+    private: true,
+    description: `${answers.name} ${target} target`,
+    ...(framework ? { [depKey]: { [framework]: FAMILY_VERSION } } : {}),
+  }, null, 2)}\n`;
+}
+
+/**
+ * Build the scaffold plan for a brand.
+ *
+ * @param {Object} answers - { id, name, description, tagline, url, email, person, targets }
+ * @returns {Array<{ path: string, contents: string }>} - Brand-root-relative file plan
+ */
+function buildScaffoldPlan(answers) {
+  const plan = [
+    { path: 'config/omega.json5', contents: renderOmegaConfig(answers) },
+    { path: 'package.json', contents: renderRootPackageJson(answers) },
+    { path: '.gitignore', contents: renderGitignore() },
+    { path: '.env', contents: renderEnvStub(answers) },
+    ...ENV_ENVIRONMENTS.map((environment) => ({ path: `.env.${environment}`, contents: renderEnvOverlayStub(environment) })),
+    { path: 'README.md', contents: renderReadme(answers) },
+  ];
+
+  for (const target of answers.targets) {
+    const dir = TARGET_DIRS[target] || target;
+    plan.push({ path: `targets/${dir}/package.json`, contents: renderTargetPackageJson(answers, target, dir) });
+  }
+
+  return plan;
+}
+
+/**
+ * Write a scaffold plan with fill-missing semantics: files that already
+ * exist are never touched (rerunning onboard converges instead of clobbering).
+ *
+ * @param {string} brandRoot - Absolute brand root to scaffold into
+ * @param {Array<{ path, contents }>} plan - From buildScaffoldPlan()
+ * @param {Object} [options] - { dryRun } — plan only, zero writes
+ * @returns {{ created: string[], kept: string[], planned: string[] }}
+ */
+function applyScaffoldPlan(brandRoot, plan, { dryRun = false } = {}) {
+  const created = [];
+  const kept = [];
+  const planned = [];
+
+  for (const file of plan) {
+    const destination = path.join(brandRoot, file.path);
+
+    if (jetpack.exists(destination)) {
+      kept.push(file.path);
+      continue;
+    }
+
+    if (dryRun) {
+      planned.push(file.path);
+      continue;
+    }
+
+    jetpack.write(destination, file.contents);
+    created.push(file.path);
+  }
+
+  return { created, kept, planned };
+}
+
+/**
+ * Print what a plan did — the one rendering of created/kept/planned, shared
+ * by every scaffolding verb (onboard's brand plan, company init's).
+ */
+function printPlanResults({ created, kept, planned }) {
+  for (const file of planned) {
+    console.log(`  ${chalk.dim('⊘')} would create ${chalk.cyan(file)}`);
+  }
+  for (const file of created) {
+    console.log(`  ${chalk.green('✓')} created ${chalk.cyan(file)}`);
+  }
+  for (const file of kept) {
+    console.log(`  ${chalk.dim('•')} kept ${chalk.dim(file)} ${chalk.dim('(exists)')}`);
+  }
+}
+
+module.exports = { buildScaffoldPlan, applyScaffoldPlan, printPlanResults };

package/dist/lib/service-input.js

@@ -0,0 +1,207 @@
+/**
+ * The ONE setup contract every service asks its inputs through (#608, Ian
+ * 2026-08-25) — the env-side twin of config-flow's resolveConfigValue, and the
+ * successor to cp114's two-outcome ensureEnvSecrets.
+ *
+ * When a service runs and an input it needs is missing, it asks RIGHT THEN,
+ * with the same three outcomes everywhere:
+ *
+ *   Provide             — the Enter-gated open of the exact page that mints
+ *                         the value, a masked paste, persisted to the brand
+ *                         .env (lib/env-secret.js) and exported for THIS run,
+ *                         so a fresh brand configures itself mid-walk.
+ *   Skip for now        — this run steps aside; the next one asks again.
+ *   Disable permanently — `<service>.enabled: false` lands in omega.json5
+ *                         (the tri-state opt-out, #33) and nothing ever asks
+ *                         again until the line is deleted.
+ *
+ * Non-interactive runs (CI, a piped `omega dev` boot, `--dry-run`) NEVER
+ * prompt: the missing keys print as a loud skip line and ride back as the
+ * machine-readable `missingEnv` list the run summary's 🔑 section aggregates.
+ *
+ * One class of input is never PASTED: a key OMEGA mints for ITSELF (the env
+ * schema's `generated:` set) has nobody to ask, so it is minted in place and
+ * never appears in `missingEnv` (#635). When it is the only thing missing no
+ * gate opens at all, headless runs included; when a pasted key is missing
+ * beside it the gate runs FIRST and the mint happens only past it, so
+ * "Disable permanently" never leaves a minted secret behind.
+ *
+ * WHAT each service needs is the REQUIRES registry's to say (src/config.js —
+ * one home, checked up front by lib/preflight.js and asked for here through
+ * `serviceInputSpec(name)`); the env schema (@omega.js/config, #581) is what
+ * says which of those keys OMEGA mints for itself and which a human acquires,
+ * and the sweep test holds the registry to it.
+ *
+ * Values are never printed — names, labels and mint URLs only.
+ */
+const chalk = require('chalk').default;
+
+const { generatedEnvKeys } = require('../vendor/config/index.js');
+const { canPrompt, dryRunPlan } = require('./run-gates.js');
+const { writeEnvValue, mintGeneratedKey } = require('./env-secret.js');
+const { confirmSetup, readTriState } = require('./config-flow.js');
+
+/**
+ * Ask for a service's missing inputs, with the three-outcome gate.
+ *
+ * @param {object} context - Service context ({ brandRoot, brandConfig, brandId, options }).
+ * @param {object} spec - The input spec (serviceInputSpec(name) builds one from
+ *   the REQUIRES registry):
+ *   @param {string} spec.service - Service name (names the rerun hint).
+ *   @param {string} spec.label - Human name the gate opens with ("Cloudflare").
+ *   @param {string} spec.disablePath - Where "Disable permanently" writes `false`.
+ *   @param {string[]} [spec.instructions] - Guidance lines shown before the gate.
+ *   @param {boolean} [spec.gate] - false = the caller already ran the gate.
+ *   @param {Array<{ name, label?, url?, hint?, when? }>} spec.inputs - The env
+ *     vars the service needs; `when(brandConfig)` drops the ones this brand
+ *     doesn't, `url` is the page that mints one, `hint` says what to make there.
+ * @param {object} [deps] - Test seam: { prompt } overrides devkit/prompt members.
+ * @returns {Promise<object|null>} null to proceed, or the setup skip shape
+ *   ({ skip, reason, missingEnv, disabled? }).
+ */
+async function requestServiceInput(context, spec, deps = {}) {
+  const { brandConfig = {}, options = {} } = context;
+
+  const wanted = spec.inputs.filter((input) => !input.when || input.when(brandConfig));
+  const missing = wanted.filter((input) => !process.env[input.name]);
+  if (missing.length === 0) {
+    return null;
+  }
+
+  // Already opted out (#33): the value — or any ancestor section — is `false`.
+  // Every service gates on its own key too; this is the backstop that keeps a
+  // disabled service from ever reaching a prompt.
+  if (readTriState(brandConfig, spec.disablePath).optedOut) {
+    return {
+      skip: true,
+      reason: `${spec.disablePath} is disabled — delete the line in omega.json5 to be asked again`,
+      missingEnv: missing.map((input) => input.name),
+      disabled: true,
+    };
+  }
+
+  // A key OMEGA mints for itself (the env schema's `generated:` set, #581) is
+  // MINTED, not pasted: there is nobody to ask for it, so it never joins the
+  // 🔑 "add these to your .env" list — the two kinds of missing input split
+  // here and are handled apart (#635).
+  const generated = generatedEnvKeys();
+  const mintable = missing.filter((input) => generated[input.name]);
+  const pending = missing.filter((input) => !generated[input.name]);
+
+  const mintAll = () => {
+    for (const input of mintable) {
+      mintGeneratedKey(context.brandRoot, input.name, { indent: '    ' });
+    }
+  };
+
+  // A dry run says what a real run would mint and writes nothing, exactly as
+  // the workspace env-keys op does.
+  if (options.dryRun) {
+    for (const input of mintable) {
+      dryRunPlan(`mint ${input.name} into the brand .env`);
+    }
+  }
+
+  // Nothing a human could supply is missing: mint and proceed, no gate, on a
+  // headless run too.
+  if (pending.length === 0) {
+    if (options.dryRun) {
+      // Named, but NOT as missingEnv — telling someone to paste a key only
+      // OMEGA can produce would be a lie the 🔑 section then repeats.
+      return {
+        skip: true,
+        reason: `${mintable.map((input) => input.name).join(', ')} will be minted on a real run`,
+        missingEnv: [],
+      };
+    }
+
+    mintAll();
+    return null;
+  }
+
+  const names = pending.map((input) => input.name);
+
+  if (!canPrompt(options)) {
+    // Loud: a run that cannot ask still says exactly which keys it wants and
+    // where they go, instead of a bare "skipped".
+    console.log(`    ${chalk.yellow('🔑')} ${spec.label} needs ${chalk.bold(names.join(', '))} ${chalk.dim('— not in the brand .env')}`);
+    for (const input of pending) {
+      if (input.url) {
+        console.log(`      ${chalk.dim(`→ ${input.name}: mint it at ${input.url}`)}`);
+      }
+    }
+
+    return {
+      skip: true,
+      reason: `missing ${names.join(', ')} — add to the brand .env, or rerun interactively to paste`,
+      missingEnv: names,
+    };
+  }
+
+  // The uniform gate — its wording lives once, in config-flow's confirmSetup,
+  // and its Disable lands the tri-state `false` for us. `gate: false` is the
+  // chained ask (resolveConfigValue's convention): the caller already opened
+  // this flow's gate, so asking twice would be the same question.
+  const action = spec.gate === false
+    ? 'yes'
+    : await confirmSetup(context, {
+      label: spec.label,
+      instructions: spec.instructions,
+      disablePath: spec.disablePath,
+    });
+
+  if (action === 'disable') {
+    return {
+      skip: true,
+      reason: `${spec.disablePath} disabled in omega.json5 — delete the line to be asked again`,
+      missingEnv: names,
+      disabled: true,
+    };
+  }
+
+  if (action !== 'yes') {
+    return {
+      skip: true,
+      reason: `skipped this run — ${spec.service} still needs ${names.join(', ')}`,
+      missingEnv: names,
+    };
+  }
+
+  // Past the gate: only NOW are OMEGA's own keys minted, so a "Disable
+  // permanently" never leaves a freshly minted secret in a brand that just
+  // said it wants none of this.
+  mintAll();
+
+  const prompt = { ...require('../vendor/devkit/prompt.js'), ...deps.prompt };
+
+  for (const input of pending) {
+    const label = input.label || input.name;
+    if (input.hint) {
+      console.log(`      ${chalk.dim(input.hint)}`);
+    }
+
+    // The exact-page guide: Enter opens the page that mints the value
+    // (pressEnterToOpen always prints the URL, so it stays clickable when the
+    // user would rather not open a browser).
+    if (input.url) {
+      await prompt.pressEnterToOpen(input.url, `the ${label} page`);
+    }
+
+    const value = (await prompt.password({ message: `Paste ${input.name}:` }) || '').trim();
+    if (!value) {
+      return {
+        skip: true,
+        reason: `nothing entered for ${input.name} — ${spec.service} still needs ${names.join(', ')}`,
+        missingEnv: names,
+      };
+    }
+
+    writeEnvValue(context.brandRoot, input.name, value);
+    process.env[input.name] = value;
+    console.log(`    ${chalk.green('✓')} ${input.name} saved to the brand .env`);
+  }
+
+  return null;
+}
+
+module.exports = { requestServiceInput };