@devdogsuga/devtools 0.1.25 → 0.1.27

package/dist/env/example.d.ts

@@ -1,68 +0,0 @@
-import type { EnvTarget } from "@devdogsuga/env";
-/**
- * The sections a development init may narrow to: the four apps.
- *
- * Order is the PICKER's order, not the file's (that is `SECTION_ORDER`, fixed
- * so `.env.example` stays byte-stable). The two projects most contributors
- * join come first; `platform` follows as the shared auth infrastructure you
- * depend on but rarely edit, and `sandbox` last as the dormant one almost
- * nobody touches.
- *
- * `supabase` is NOT here and NOT optional. It is the shared database and auth
- * layer every app runs against, so any selection implies it (the caller adds
- * it). `devtools` is not here either, deliberately: it is a ROLE, not a
- * project. A contributor picks what they are building; whether they also
- * operate deploys is a separate question the picker asks separately.
- */
-export declare const APP_SECTIONS: readonly ["schedule-builder", "study-group-finder", "platform", "sandbox"];
-/**
- * Every declared key belonging to one of the chosen sections.
- *
- * `some` over a key's declaring sources, so a key SHARED between a chosen and
- * an unchosen app (API_URL, the whole connection block) is included by
- * whichever side was picked. A narrowed file must never lose the
- * infrastructure a chosen app boots on just because another app shares it.
- */
-export declare function keysForSections(chosen: ReadonlySet<string>): Set<string>;
-/** The committed `.env.example`: generated header + rendered registry. */
-export declare function renderExample(): string;
-/**
- * A fresh env file for `env init`.
- *
- * Two renderings, not one with a different first line. See the module header.
- * `development` wants every declared key with its `example` as written, which
- * is also what `.env.example` wants; a vault target wants what a push for that
- * target routes, blank unless the registry can derive it.
- */
-export declare function renderInit(target: EnvTarget, date: string, 
-/**
- * Development only: the sections to render, from the project picker.
- * Callers pass the CHOSEN set plus `supabase` (the shared stack is implied
- * by any choice); absent means everything, which is what the vault targets
- * and every pre-picker caller get.
- */
-sections?: ReadonlySet<string>): string;
-export declare function runEnvExample(options: {
-    check?: boolean;
-}): Promise<void>;
-/**
- * The development sections to render: `--apps`, else the picker, else all.
- *
- * `undefined` means "everything", which covers three callers at once: a script
- * with no flag, a pipe with no terminal (the picker refuses to prompt where
- * nobody can answer, like every other picker here), and the vault targets,
- * which never narrow.
- */
-export declare function resolveSections(apps?: string): Promise<Set<string> | undefined>;
-export declare function runEnvInit(target: EnvTarget, apps?: string): Promise<void>;
-/**
- * Add newly declared keys to an existing target file without rewriting it.
- *
- * Vault-target derivations are evaluated against the complete routed key set,
- * not merely the missing subset. Otherwise appending NEXT_PUBLIC_SUPABASE_URL
- * to a file that already contains API_URL would incorrectly render a blank.
- */
-export declare function renderInitAddition(target: EnvTarget, date: string, existing: string, sections?: ReadonlySet<string>): {
-    text: string;
-    count: number;
-} | null;

package/dist/env/example.js

@@ -1,605 +0,0 @@
-/**
- * `pnpm devtools env example [--check]` and `pnpm devtools env init`.
- *
- * `.env.example` is OUTPUT, not a file anyone edits. The registry the
- * manifests populate is the single source, this module renders it, and CI's
- * `--check` fails on drift the same way it does for `database.types.ts`. A
- * wrong line is fixed in the owning manifest's `doc`/`example`/`commented`
- * metadata.
- *
- * ⚠️ Registry-only, on purpose. Nothing here touches Bitwarden, GitHub, the
- * network, or the ambient environment, and `cli.ts` dispatches these two
- * subcommands before any token lookup or environment prompt. The CI job that
- * runs `--check` is deliberately credential-free, and a generator that needed
- * a secret to describe the secrets would not be allowed there.
- *
- * `env init` is the same renderer pointed at a real env file. It takes any
- * `--target` and writes THAT target's file (`.env`, `.env.preflight`,
- * `.env.staging`, `.env.production`) from the one target table that `pull`,
- * `push` and `audit` default their file from. When `init` mapped target to
- * file and `push` did not, `init --env staging` created `.env.staging` and
- * `push --env staging` uploaded `.env`.
- *
- * ⚠️ A VAULT TARGET'S FILE IS NOT THE DEVELOPMENT ONE WITH A DIFFERENT NAME.
- * Rendering it as though it were produced a file worse than useless: fill in
- * its blanks, push it, and localhost URLs and a placeholder GitHub App private
- * key went to production, after which `env audit` reported NO DRIFT, because
- * the stored values matched the file they came from. Two differences, both
- * mechanical:
- *
- *   * **Which keys.** `keysRoutedTo()`, what a push for that target would
- *     actually carry somewhere. Not the committed `scope: "default"`
- *     constants, not one contributor's `scope: "developer"` values, and not
- *     the apply-tier credentials outside production, all three of which used
- *     to ship in all three files because all three files were byte-identical
- *     but for the header. `preflight` is narrower again: a target no app boots
- *     from carries only the keys declared `narrowed`, so its file is one line
- *     long today rather than 45.
- *   * **Which values.** Blank, unless `getEnvSync().derivationOf()` says the `example` is a
- *     derivation AND every variable it expands from is in the same file. A
- *     development default and a placeholder are both non-empty, and every
- *     consumer downstream skips only EMPTY values.
- *
- * Nothing is commented out in one either, `commented: true` included. The flag
- * encodes a real distinction: an EMPTY value for an enabled OAuth provider
- * makes the Supabase CLI fail with `ProjectConfigParseError`, so "unset" and
- * "empty" differ. `push` cannot act on it. It skips an empty value and never
- * sees a commented line at all, so a value typed on a commented line is
- * silently NOT pushed. That made the flag a trap here: `SUPABASE_DB_PASSWORD`,
- * `SUPABASE_JWT_SIGNING_KEY`, `CLOUDFLARE_API_TOKEN` and all four OAuth client
- * secrets shipped commented, so the must-fill keys were the ones that could
- * not be filled. They ship uncommented here; the flag still governs
- * `.env.example` and the development `.env`, where the CLI reads the file and
- * nothing pushes it.
- *
- * Re-running it is ADDITIVE: it appends only newly declared keys that the
- * target routes and leaves every existing line byte-for-byte. There is no
- * `--force` path that replaces a whole file with blanks: `env reset` blanks
- * values recoverably, and `env pull` updates stored values in place.
- */
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { log, multiselect, note } from "@clack/prompts";
-import { EnvDocument } from "./document.js";
-import { unwrap } from "../ui.js";
-import { assertRegistryLoaded } from "./discovery.js";
-import { getEnvSync } from "../repo/peers.js";
-import { recordResolved } from "../invocation.js";
-import { keysRoutedTo } from "./selection.js";
-import { findRepoRoot } from "../repo/root.js";
-import { explain } from "../ui.js";
-/**
- * Section order is FIXED here rather than inherited from manifest import
- * order, and a key declared by several manifests renders once, under the
- * earliest of its sources in this list. Both choices keep the output a pure
- * function of the declarations, so `--check` compares content rather than
- * filesystem enumeration accidents.
- */
-const SECTION_ORDER = [
-    "platform",
-    "schedule-builder",
-    "study-group-finder",
-    "sandbox",
-    "supabase",
-    "devtools",
-];
-const SECTION_LABELS = {
-    platform: "platform (apps/platform/src/env.ts)",
-    "schedule-builder": "schedule-builder (apps/schedule-builder/src/env.ts)",
-    "study-group-finder": "study-group-finder (apps/study-group-finder/env.ts)",
-    sandbox: "sandbox — a dormant Worker's bindings; nothing provisions or deploys " +
-        "it from the platform side any more (apps/sandbox/env.ts)",
-    supabase: "supabase — read by config.toml and the Supabase CLI (supabase/env.ts)",
-    devtools: "devtools — operator tooling, no app reads these (@devdogsuga/devtools)",
-};
-/** `study-group-finder:tooling` and friends fold into their app's section. */
-function sectionOf(source) {
-    return source.split(":")[0];
-}
-/**
- * The sections a development init may narrow to: the four apps.
- *
- * Order is the PICKER's order, not the file's (that is `SECTION_ORDER`, fixed
- * so `.env.example` stays byte-stable). The two projects most contributors
- * join come first; `platform` follows as the shared auth infrastructure you
- * depend on but rarely edit, and `sandbox` last as the dormant one almost
- * nobody touches.
- *
- * `supabase` is NOT here and NOT optional. It is the shared database and auth
- * layer every app runs against, so any selection implies it (the caller adds
- * it). `devtools` is not here either, deliberately: it is a ROLE, not a
- * project. A contributor picks what they are building; whether they also
- * operate deploys is a separate question the picker asks separately.
- */
-export const APP_SECTIONS = [
-    "schedule-builder",
-    "study-group-finder",
-    "platform",
-    "sandbox",
-];
-/**
- * Every declared key belonging to one of the chosen sections.
- *
- * `some` over a key's declaring sources, so a key SHARED between a chosen and
- * an unchosen app (API_URL, the whole connection block) is included by
- * whichever side was picked. A narrowed file must never lose the
- * infrastructure a chosen app boots on just because another app shares it.
- */
-export function keysForSections(chosen) {
-    assertRegistryLoaded();
-    const keys = new Set();
-    for (const [key, entries] of getEnvSync().variables()) {
-        if (entries.some((entry) => chosen.has(sectionOf(entry.source)))) {
-            keys.add(key);
-        }
-    }
-    return keys;
-}
-function sectionRank(source) {
-    const index = SECTION_ORDER.indexOf(sectionOf(source));
-    return index === -1 ? SECTION_ORDER.length : index;
-}
-/** Greedy wrap into `# `-prefixed lines that stay under 80 columns. */
-function comment(text, width = 77) {
-    const lines = [];
-    let line = "";
-    for (const word of text.split(/\s+/)) {
-        if (line !== "" && line.length + 1 + word.length > width) {
-            lines.push(`# ${line}`);
-            line = word;
-        }
-        else {
-            line = line === "" ? word : `${line} ${word}`;
-        }
-    }
-    if (line !== "")
-        lines.push(`# ${line}`);
-    return lines;
-}
-const RULE = `# ${"-".repeat(75)}`;
-/** One block per key, grouped by owning section, in declaration order. */
-function sections() {
-    assertRegistryLoaded();
-    const bySection = new Map();
-    for (const entries of getEnvSync().variables().values()) {
-        // The stable sort keeps declaration order among same-section duplicates,
-        // so the owner is the canonical section's own declaration.
-        const owner = [...entries].sort((a, b) => sectionRank(a.source) - sectionRank(b.source))[0];
-        const own = sectionOf(owner.source);
-        const sharedWith = [
-            ...new Set(entries.map((e) => sectionOf(e.source)).filter((s) => s !== own)),
-        ];
-        const blocks = bySection.get(own) ?? [];
-        blocks.push({ entry: owner, sharedWith });
-        bySection.set(own, blocks);
-    }
-    return [...bySection.entries()]
-        .sort(([a], [b]) => sectionRank(a) - sectionRank(b) || a.localeCompare(b))
-        .map(([name, blocks]) => ({ name, blocks }));
-}
-/**
- * The value a vault target's file carries for a key: a derivation, or nothing.
- *
- * `routed` is the rest of the file, and passing it is the whole check. A
- * formula is only a value if the file can expand it. `$BASE_URL/auth/callback`
- * with no `BASE_URL` line above it is not "structure worth keeping", it is a
- * literal dollar sign about to be pushed to Bitwarden, stored, synced to
- * GitHub, and written into a deployed environment verbatim.
- */
-function derivedValue(meta, routed) {
-    const derivation = getEnvSync().derivationOf(meta);
-    if (derivation === null)
-        return "";
-    return getEnvSync()
-        .envReferences(derivation)
-        .every((ref) => routed.has(ref))
-        ? derivation
-        : "";
-}
-/**
- * `routed` is absent for `.env.example` and the development `.env`, the two
- * renderings that want every declared key with its `example` as written. It is
- * present for a vault target, where it is both the filter and the set a
- * derivation's references have to resolve within.
- */
-function renderBlock({ entry, sharedWith }, routed) {
-    const { key, meta } = entry;
-    const lines = comment(meta.doc);
-    // Development-only, and actively misleading in a deployed file: staging has
-    // no local stack to supply anything, which is why the five keys carrying
-    // this flag are still in `variableKeys()` and still land here.
-    if (meta.localStack && routed === undefined) {
-        lines.push("# (the running local Supabase stack supplies this via .env.generated)");
-    }
-    if (sharedWith.length > 0) {
-        lines.push(`# (shared with ${sharedWith.join(", ")})`);
-    }
-    // A never-store credential ships COMMENTED. "Never store" is about REMOTE
-    // stores: push refuses these by name, pull will not write them back, and
-    // audit errors on any remote copy. The operator's own gitignored .env may
-    // hold one (since 2026-08-19, by decision), and the BWS prompts offer to
-    // save there. The commented line is the documented home that offer revives.
-    // A vault target's file never renders these at all, because
-    // `keysRoutedTo()` refuses them.
-    if (meta.secrecy === "never-store") {
-        return [...lines, `# ${key}=""`];
-    }
-    // A minted credential gets the same treatment, for a different reason. There
-    // is no value to write: it is signed at deploy time and lives only on the
-    // deploy target. A blank `SANDBOX_PROXY_TOKEN=` line would read as a field
-    // awaiting a paste, and the paste would be a hand-made token that never
-    // rotates, the exact failure minting exists to remove.
-    if (meta.minted) {
-        return [
-            `# ${key}:`,
-            ...lines,
-            ...comment(`(no ${key}= line on purpose — this one is minted at deploy time, so ` +
-                "there is no value to fill in and a hand-pasted one would never " +
-                "rotate)"),
-        ];
-    }
-    // A vault target's file: a derivation or a blank, always assignable. See the
-    // module header for why `commented` stops applying here and why every other
-    // `example` is dropped rather than carried across.
-    if (routed !== undefined) {
-        lines.push(`${key}="${derivedValue(meta, routed)}"`);
-        return lines;
-    }
-    const value = `${key}="${meta.example ?? ""}"`;
-    // `developer` keys are always commented: they are one contributor's own
-    // values, and an uncommented empty line reads as a blank everybody fills in.
-    const commented = meta.commented === true || meta.scope === "developer";
-    lines.push(commented ? `# ${value}` : value);
-    return lines;
-}
-/**
- * `routed` absent renders every declared key; present renders that set only.
- *
- * A section whose keys are all filtered out is dropped with them. A heading
- * over nothing reads as "this app needs nothing here", a different and false
- * claim.
- */
-function renderBody(routed, derivationScope = routed) {
-    const lines = [];
-    for (const { name, blocks } of sections()) {
-        const included = routed === undefined
-            ? blocks
-            : blocks.filter(({ entry }) => routed.has(entry.key));
-        if (included.length === 0)
-            continue;
-        lines.push("", RULE, `# ${SECTION_LABELS[name] ?? name}`, RULE);
-        for (const block of included) {
-            lines.push("", ...renderBlock(block, derivationScope));
-        }
-    }
-    return lines;
-}
-/** The committed `.env.example`: generated header + rendered registry. */
-export function renderExample() {
-    const header = [
-        "# .env.example — every declared environment variable, with its documentation.",
-        "#",
-        "# GENERATED by `pnpm devtools env example`. Do not edit this file: edit",
-        "# the owning manifest (src/env.ts, env.ts, supabase/env.ts) and regenerate.",
-        "# CI runs `env example --check` and fails on drift, the same pattern as",
-        "# database.types.ts.",
-        "#",
-        "# One env file per target, each standalone — no shared base, so a key",
-        "# missing from a deployed file is a loud validation error rather than a",
-        "# silent fallthrough to a development value:",
-        "#",
-        "#   .env             IS development (the unsuffixed file, read by default)",
-        "#   .env.preflight   `pnpm devtools env pull --target preflight`",
-        "#   .env.staging     `pnpm devtools env pull --target staging`",
-        "#   .env.production  `pnpm devtools env pull --target production`",
-        "#",
-        "# .env.preflight is a staging area for pushing credentials, never a file an",
-        "# app boots from: DEPLOY_ENV=preflight is refused on purpose.",
-        "#",
-        "# `pnpm devtools setup` (or `pnpm devtools env init`) materialises a",
-        "# fresh .env from the same registry that generated this file. The local",
-        "# Docker stack is detected by a port probe, not a flag: while it is running,",
-        "# .env.generated (written by start-local-stack) overlays the connection",
-        "# block — in development only. `supabase stop` is the toggle back.",
-        "#",
-        "# SECTIONS ARE GROUPED BY WHO READS THE VARIABLE, and two of the readers",
-        "# are not apps — that is deliberate, not clutter. The four app sections",
-        "# come first. Then `supabase`: values config.toml and the Supabase CLI",
-        "# read (the shared auth server serves every app, so no one app can own",
-        "# them). Then `devtools`: operator credentials no app reads at all. They",
-        "# cannot be moved into an app's manifest, because an app's manifest is",
-        "# what `deploy secrets-file` uploads to that app's Worker — filing",
-        "# CLOUDFLARE_API_TOKEN or an OAuth client secret under an app would put",
-        "# it on an internet-facing Worker that never asked for it. A key an app",
-        "# only needs at dev/build time uses the `<app>:tooling` suffix instead,",
-        "# which keeps the app grouping without the upload.",
-    ];
-    return [...header, ...renderBody(), ""].join("\n");
-}
-/** The prose above a vault target's blanks, explaining why they are blank. */
-function targetHeader(target, count) {
-    return [
-        "#",
-        ...comment(`The ${count} key${count === 1 ? "" : "s"} a ` +
-            `\`pnpm devtools env push --target ${target}\` ` +
-            "routes, and nothing else. The committed defaults and the " +
-            "per-developer values go nowhere, and a minted credential is signed " +
-            "at deploy time rather than stored, so none of the three has a line " +
-            "here to fill in."),
-        "#",
-        ...comment(target === "production"
-            ? "The apply-tier credential IS here — SUPABASE_ACCESS_TOKEN reaches " +
-                "the production-apply GitHub environment, and no other target " +
-                "carries it."
-            : "The apply-tier credential is NOT here. It exists to reshape " +
-                `production, so a copy in ${target} would be a second ` +
-                "write-capable token to rotate for no benefit — and `env push` " +
-                "skips it outside production anyway."),
-        "#",
-        ...comment("Fill the values in, or run " +
-            `\`pnpm devtools env pull --target ${target}\` to fetch what ` +
-            "Bitwarden already holds. Nothing is commented out: push reads " +
-            "assignments, and a commented line is not one — a value typed on it " +
-            "would be silently skipped."),
-        "#",
-        ...comment("The blanks are blank ON PURPOSE. A key's `example` metadata is a " +
-            "development default (`http://localhost:3000`) or an .env.example " +
-            "placeholder (`000000`, a fake private key), and every consumer " +
-            "downstream skips only EMPTY values — so a prefilled one would push " +
-            "cleanly and then be reported as no drift, because the stored value " +
-            "would match this file. The `$VAR` lines that DID survive are " +
-            "derivations: how the value is built, from another line in this same " +
-            "file. Leave them alone unless the target genuinely differs."),
-        ...(target === "preflight"
-            ? [
-                "#",
-                ...comment("⚠️ PREFLIGHT IS DELIBERATELY TINY, and a short file here is the " +
-                    "correct output rather than a truncated one. Nothing boots from " +
-                    "this target: it exists to feed CI's migration DRY RUN, which " +
-                    "reads and changes nothing, so it carries only the keys whose " +
-                    "declaration opts in with `narrowed` — today, a Postgres role " +
-                    "that sees only the migrations table and nothing wider. Every " +
-                    "other key is absent ON PURPOSE: this project's GitHub " +
-                    "environment is reachable from `main`, and listing every " +
-                    "routable key there, the JWT signing key included, would " +
-                    "defeat the point of a narrowed preflight role."),
-            ]
-            : []),
-    ];
-}
-/**
- * A fresh env file for `env init`.
- *
- * Two renderings, not one with a different first line. See the module header.
- * `development` wants every declared key with its `example` as written, which
- * is also what `.env.example` wants; a vault target wants what a push for that
- * target routes, blank unless the registry can derive it.
- */
-export function renderInit(target, date, 
-/**
- * Development only: the sections to render, from the project picker.
- * Callers pass the CHOSEN set plus `supabase` (the shared stack is implied
- * by any choice); absent means everything, which is what the vault targets
- * and every pre-picker caller get.
- */
-sections) {
-    const file = getEnvSync().fileFor(target);
-    const stamp = `# ${file} (${target}) — created by \`pnpm devtools env init\` on ${date}.`;
-    if (getEnvSync().isVaultTarget(target)) {
-        const routed = keysRoutedTo(target);
-        return [
-            stamp,
-            ...targetHeader(target, routed.size),
-            ...renderBody(routed),
-            "",
-        ].join("\n");
-    }
-    const narrowed = sections &&
-        SECTION_ORDER.some((s) => !sections.has(s));
-    return [
-        stamp,
-        ...(narrowed
-            ? [
-                `# Narrowed to: ${[...sections].sort().join(", ")} — the projects picked at`,
-                "# init. Nothing else is missing by accident: re-run",
-                "# `pnpm devtools env init --target development` any time to add the",
-                "# sections for another project (or the operator tooling), appended",
-                "# without touching a value you have already filled in.",
-            ]
-            : []),
-        "# Fill in the values below. The local Supabase stack supplies the whole",
-        "# connection block: `pnpm devtools db start` starts it and writes",
-        "# .env.generated, which overlays this file while the stack is running.",
-        ...renderBody(sections ? keysForSections(sections) : undefined),
-        "",
-    ].join("\n");
-}
-// ── commands ─────────────────────────────────────────────────────────────────
-const EXAMPLE_PATH = ".env.example";
-/** `KEY=`, `# KEY=`: the assignable (or deliberately commented) lines. */
-const ASSIGNMENT = /^(#\s?)?([A-Z][A-Z0-9_]*)=.*$/;
-/** key → full line, for the key-level diff summary. */
-function assignments(text) {
-    const map = new Map();
-    for (const line of text.split("\n")) {
-        const match = ASSIGNMENT.exec(line);
-        if (match && !map.has(match[2]))
-            map.set(match[2], line);
-    }
-    return map;
-}
-export async function runEnvExample(options) {
-    const path = resolve(findRepoRoot(), EXAMPLE_PATH);
-    const generated = renderExample();
-    if (!options.check) {
-        await writeFile(path, generated);
-        log.success(`Wrote ${EXAMPLE_PATH} from the registry ` +
-            `(${assignments(generated).size} assignable keys).`);
-        return;
-    }
-    const committed = await readFile(path, "utf8").catch(() => null);
-    if (committed === generated) {
-        log.success(`${EXAMPLE_PATH} matches the env manifests.`);
-        return;
-    }
-    // Key-level, not a full diff: the file is mostly prose, and the useful
-    // answer is WHICH declarations moved, not a wall of comment churn.
-    const ours = assignments(generated);
-    const theirs = committed === null ? new Map() : assignments(committed);
-    const drift = [];
-    for (const key of ours.keys()) {
-        if (!theirs.has(key))
-            drift.push(`+ ${key}  declared, missing from ${EXAMPLE_PATH}`);
-        else if (theirs.get(key) !== ours.get(key))
-            drift.push(`~ ${key}  line differs`);
-    }
-    for (const key of theirs.keys()) {
-        if (!ours.has(key))
-            drift.push(`- ${key}  in ${EXAMPLE_PATH}, no longer generated`);
-    }
-    if (drift.length === 0) {
-        drift.push("(no key drifted — the header or a doc comment changed)");
-    }
-    note(drift.join("\n"), `${EXAMPLE_PATH} is out of date`);
-    explain(`${EXAMPLE_PATH} does not match the env manifests.`, "", [
-        "Regenerate it with `pnpm devtools env example` and commit the result.",
-        "The manifests are the source of truth; never edit the file by hand.",
-    ]);
-    process.exitCode = 1;
-}
-/**
- * The development sections to render: `--apps`, else the picker, else all.
- *
- * `undefined` means "everything", which covers three callers at once: a script
- * with no flag, a pipe with no terminal (the picker refuses to prompt where
- * nobody can answer, like every other picker here), and the vault targets,
- * which never narrow.
- */
-export async function resolveSections(apps) {
-    if (apps !== undefined) {
-        const chosen = apps
-            .split(",")
-            .map((name) => name.trim())
-            .filter((name) => name !== "");
-        const valid = [...APP_SECTIONS, "devtools"];
-        for (const name of chosen) {
-            if (!valid.includes(name)) {
-                throw new Error(`--apps: "${name}" is not a section. Apps: ${APP_SECTIONS.join(", ")}; ` +
-                    "plus `devtools` for the operator tooling. `supabase` is implied " +
-                    "by any choice and is not an option.");
-            }
-        }
-        if (chosen.length === 0)
-            return undefined;
-        return new Set([...chosen, "supabase"]);
-    }
-    if (!process.stdin.isTTY)
-        return undefined;
-    // The platform hint frames it as shared infrastructure: keep it in reach
-    // (running the local auth server yourself needs its keys), but say plainly
-    // that most contributors are not editing it. Sandbox gets the opposite
-    // framing: it is dormant, kept in the registry only so its own bindings
-    // stay visible, not because anyone is likely to run it.
-    const APP_HINTS = {
-        "schedule-builder": "the DogDays course-schedule planner (Next.js)",
-        "study-group-finder": "the Dog Pack study-group app (Flutter)",
-        platform: "shared auth server — needed only if you run it locally for sign-in; usually you don't edit it",
-        sandbox: "dormant Worker — no platform integration left; almost never touched",
-    };
-    const chosen = unwrap(await multiselect({
-        message: "Which projects are you working on? (The shared Supabase stack is " +
-            "always included; re-run init later to add more.)",
-        options: [
-            ...APP_SECTIONS.map((app) => ({
-                value: app,
-                label: app,
-                hint: APP_HINTS[app],
-            })),
-            {
-                value: "devtools",
-                label: "deploy & officer tooling",
-                hint: "a role, not an app — operator credentials, all commented out; most contributors never need these",
-            },
-        ],
-        initialValues: [...APP_SECTIONS],
-        required: true,
-    }));
-    return new Set([...chosen, "supabase"]);
-}
-export async function runEnvInit(target, apps) {
-    const file = getEnvSync().fileFor(target);
-    const path = resolve(findRepoRoot(), file);
-    const date = new Date().toISOString().slice(0, 10);
-    const sections = target === "development" ? await resolveSections(apps) : undefined;
-    // When the projects came from the picker rather than `--apps`, record them
-    // so the rerun line can reproduce the selection without prompting. `supabase`
-    // is always implied, never an `--apps` value, so it is dropped here.
-    if (apps === undefined && sections !== undefined) {
-        const picked = [...sections].filter((s) => s !== "supabase").sort();
-        if (picked.length > 0)
-            recordResolved("--apps", picked.join(","));
-    }
-    try {
-        // `wx` makes the existence check and the write one atomic operation, so
-        // two concurrent inits cannot both pass a stat and then clobber.
-        await writeFile(path, renderInit(target, date, sections), { flag: "wx" });
-    }
-    catch (err) {
-        if (err.code === "EEXIST") {
-            // A re-run is ADDITIVE for every target. Only keys the file does not
-            // mention at all are appended. An active line holds somebody's value
-            // and a commented one holds their decision; both survive byte-for-byte.
-            const existing = await readFile(path, "utf8");
-            const addition = renderInitAddition(target, date, existing, sections);
-            if (addition === null) {
-                log.info(`${file} already covers that target — nothing to add.`);
-                return;
-            }
-            await writeFile(path, addition.text);
-            log.success(`Appended ${addition.count} key${addition.count === 1 ? "" : "s"} to ${file}; existing lines untouched.`);
-            return;
-        }
-        throw err;
-    }
-    log.success(`Created ${file} (${target}).`);
-    log.info(target === "development"
-        ? "Fill in the values, or run `pnpm devtools db start` to start the local " +
-            "stack — it supplies the whole connection block via .env.generated."
-        : "Every value is blank but the `$VAR` derivations, which are how those " +
-            "values are built rather than a guess at them. " +
-            `\`pnpm devtools env pull --target ${target}\` fills the rest from ` +
-            "Bitwarden.");
-}
-/**
- * Add newly declared keys to an existing target file without rewriting it.
- *
- * Vault-target derivations are evaluated against the complete routed key set,
- * not merely the missing subset. Otherwise appending NEXT_PUBLIC_SUPABASE_URL
- * to a file that already contains API_URL would incorrectly render a blank.
- */
-export function renderInitAddition(target, date, existing, sections) {
-    const doc = EnvDocument.parse(existing);
-    const wanted = getEnvSync().isVaultTarget(target)
-        ? keysRoutedTo(target)
-        : sections
-            ? keysForSections(sections)
-            : new Set(getEnvSync().variables().keys());
-    const missing = new Set([...wanted].filter((key) => !doc.has(key) && !doc.isCommented(key)));
-    if (missing.size === 0)
-        return null;
-    const label = getEnvSync().isVaultTarget(target)
-        ? target
-        : sections
-            ? [...sections].sort().join(", ")
-            : "everything";
-    const appended = [
-        "",
-        `# --- added by \`pnpm devtools env init\` on ${date} for: ${label} ---`,
-        ...renderBody(missing, getEnvSync().isVaultTarget(target) ? wanted : undefined),
-        "",
-    ].join("\n");
-    return {
-        text: existing.replace(/\n?$/, "\n") + appended,
-        count: missing.size,
-    };
-}