@devdogsuga/devtools 0.1.25 → 0.1.27

package/dist/env/discovery.js

@@ -1,239 +0,0 @@
-/**
- * Fills the `@devdogsuga/env` registry by importing every manifest.
- *
- * The registry populates as a SIDE EFFECT of importing each manifest module.
- * `declare()` runs at import time, so a process that never imports them sees an
- * empty registry and every derived selector returns nothing. That is the
- * fail-open shape this module closes: anything that routes secrets calls
- * `loadRegistry()` first, and `assertRegistryLoaded()` is the guard the
- * selectors' consumers use to refuse an empty answer.
- *
- * Discovery is by filename, per the model doc: `src/env.ts`, then `env.ts`, per
- * workspace package. Both present is a hard error, because two manifests in one
- * package means two places for the next declaration to land and no rule saying
- * which. No `package.json` pointer: every other tool in this repo is found by
- * filename (`tsconfig.json`, `wrangler.jsonc`, `supadart.yaml`), and a pointer
- * would be the only one of its kind.
- *
- * One special case: `supabase/env.ts` sits at the repo root, OUTSIDE the
- * workspace globs. Its variables belong to `config.toml` and the Supabase
- * CLI, not to any package, so it lives next to the config that reads them.
- *
- * `@devdogsuga/env` itself (the package that exports `define()`/`declare()`)
- * no longer needs a special-case exclusion here: since the Backstage
- * cutover it is an installed npm dependency, not a workspace package under
- * `packages/`, so this scan never sees it at all.
- *
- * devtools' OWN operator manifest (this package's root `env.ts` — the keys
- * no app reads at all: `BWS_ACCESS_TOKEN`, `CLOUDFLARE_API_TOKEN`, and
- * friends) has the same problem in reverse: since the Backstage cutover
- * devtools is no longer one of the TARGET repo's workspace packages either,
- * so the scan below would never see it. It is loaded unconditionally,
- * always, regardless of which repo devtools is running against — see
- * `ownManifestPath()`'s own comment for how it stays resolvable both from a
- * workspace checkout and from an installed `pnpm dlx`/`node_modules` copy,
- * and for why loading it through the same `importRepoTs()` tsx path as
- * every other manifest (rather than a plain static `import`) is what keeps
- * its `declare()`/`define()` calls landing in the SAME `@devdogsuga/env`
- * registry instance the target repo's manifests populate (module identity —
- * see `repo/peers.ts`'s header and the devtools-dlx prototype's
- * FINDINGS.md experiment 3). Its bare `@devdogsuga/env` import is
- * redirected to the copy `loadEnv()` resolved through the repo, because
- * from a `pnpm dlx` copy the specifier does not resolve at all: devtools
- * ships no copy of its own (`@devdogsuga/env` is only ever an optional
- * peer), and nothing installs one next to it. See `repo/peer-redirect.ts`.
- *
- * Most workspace packages declare nothing, so "no env.ts found" means
- * not-a-manifest rather than an error.
- *
- * ⚠️ `apps/sandbox` was once listed here as having no manifest ON PURPOSE, on
- * the grounds that a Worker reads bindings that arrive as a function argument
- * rather than `process.env`. That premise is still true and the conclusion
- * drawn from it was still wrong: a manifest is also the only thing that routes
- * a credential to a deployed environment and the only thing that tells
- * `env audit` a Worker secret is supposed to be there. Without one,
- * `SANDBOX_PROXY_TOKEN`, minted at deploy time and therefore in no Bitwarden
- * project by design, was reported as an orphan, i.e. as safe for the §3.6 prune
- * path to delete. `apps/sandbox/env.ts` exists now, and states that reasoning
- * at length.
- */
-import { existsSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { redirectPeer } from "../repo/peer-redirect.js";
-import { getEnvSync, loadEnv, repoPeerUrl } from "../repo/peers.js";
-import { findRepoRoot } from "../repo/root.js";
-import { importRepoTs } from "../repo/tsx-loader.js";
-/**
- * The single in-flight (or settled) load.
- *
- * Node's module cache already makes a second `import()` of the same manifest a
- * no-op, but memoizing the whole pass is asserted here rather than inherited: a
- * future bundler or test runner that re-evaluates modules would duplicate every
- * declaration, and duplicated declarations are what the completeness test
- * treats as a bug. A failed load stays failed. Every later call gets the same
- * rejection, because retrying into a half-populated registry would hide the
- * manifest that broke.
- */
-let loaded;
-/**
- * Imports every manifest so the registry populates. Idempotent; concurrent
- * callers share one pass. Await this before touching any derived selector.
- */
-export function loadRegistry() {
-    loaded ??= importManifests();
-    return loaded;
-}
-/**
- * Refuses to proceed on an empty registry.
- *
- * For SYNC consumers of the derived selectors (`selectForPush`, `routeTo`),
- * which cannot await the load themselves. An empty registry makes every
- * selector return `[]`, and `[]` fails open in the worst direction: nothing is
- * never-store, so `BWS_ACCESS_TOKEN` would upload. Better a crash naming the
- * missing call than a push that quietly stores the unstorable.
- */
-export function assertRegistryLoaded() {
-    if (getEnvSync().variables().size === 0) {
-        throw new Error("The env registry is empty — no manifest has been imported, so the " +
-            "derived key sets would all be []. Await loadRegistry() (from " +
-            "devtools' env/discovery.ts) before routing or selecting secrets.");
-    }
-}
-async function importManifests() {
-    // Warms `repo/peers.ts`'s sync cache before any manifest imports: each
-    // manifest's own `declare()`/`define()` calls run against the SAME
-    // `@devdogsuga/env` module instance this line resolves (module identity —
-    // see `repo/peers.ts`'s header), and `assertRegistryLoaded()` /
-    // `gh/environments.ts`'s getters read it back synchronously afterward.
-    await loadEnv();
-    // devtools' own manifest imports `@devdogsuga/env` by bare specifier, which
-    // does not resolve at all from a `pnpm dlx` copy. Point it at the copy
-    // `loadEnv()` just resolved through the repo. See `repo/peer-redirect.ts`.
-    const envUrl = repoPeerUrl("@devdogsuga/env");
-    if (envUrl) {
-        redirectPeer({
-            parentURL: pathToFileURL(ownManifestPath()).href,
-            specifier: "@devdogsuga/env",
-            url: envUrl,
-        });
-    }
-    // The Next apps' manifests run `createEnv` at import time. Without this flag
-    // they would validate the AMBIENT environment, a devtools process rather than
-    // an app build, and throw on whatever is missing. The manifests already
-    // short-circuit their `resolveEnvironment()` call under the flag, so setting
-    // it here is the supported "read the declarations, skip the values" mode.
-    // Restored afterward so a long-lived process (tests) does not keep validation
-    // off for whatever runs next.
-    const previous = process.env.SKIP_ENV_VALIDATION;
-    process.env.SKIP_ENV_VALIDATION = "1";
-    try {
-        for (const path of manifestPaths()) {
-            try {
-                await importRepoTs(path);
-            }
-            catch (cause) {
-                throw new Error(`The env manifest at ${path} failed to import.`, {
-                    cause,
-                });
-            }
-        }
-    }
-    finally {
-        if (previous === undefined)
-            delete process.env.SKIP_ENV_VALIDATION;
-        else
-            process.env.SKIP_ENV_VALIDATION = previous;
-    }
-}
-/**
- * Every manifest file, in a stable order.
- *
- * The workspace members are enumerated by scanning `apps/*` and `packages/*`
- * plus the literal `docs`, a deliberately boring mirror of the three globs in
- * `pnpm-workspace.yaml` rather than a YAML parse: the globs have not changed
- * since the workspace existed, devtools carries no YAML dependency, and a new
- * top-level glob would already mean editing more interesting files than this
- * one.
- */
-function manifestPaths() {
-    const paths = [];
-    for (const dir of workspaceDirs()) {
-        const manifest = manifestIn(dir);
-        if (manifest)
-            paths.push(manifest);
-    }
-    // The repo-root special case: not a workspace package, see the header.
-    const supabase = manifestIn(join(findRepoRoot(), "supabase"));
-    if (supabase)
-        paths.push(supabase);
-    // devtools' own operator manifest — always included, regardless of the
-    // target repo. Last, matching where it sat back when devtools itself was
-    // `packages/devtools` (alphabetically last of the packages this repo
-    // ever had). `SECTION_ORDER` in `env/example.ts` fixes the RENDERED
-    // section order independently of this insertion order, so this position
-    // is cosmetic for `.env.example`; it still matters for which source
-    // "wins" a shared key's declaration-order tie-break.
-    paths.push(ownManifestPath());
-    return paths;
-}
-/**
- * The absolute path to devtools' own `env.ts`, resolved relative to THIS
- * module's own file rather than the target repo — it ships alongside
- * `dist/` (see `package.json`'s `files`), not inside the target repo's
- * workspace, so `findRepoRoot()`/`workspaceDirs()` can never find it.
- *
- * `import.meta.url` here is `dist/env/discovery.js` (this file's build
- * output — `tsconfig.json`'s `rootDir: "src"` / `outDir: "dist"` mirrors
- * `src/env/discovery.ts`'s own location one level down), so two `..` reach
- * the package root: `dist/env/discovery.js` -> `dist/env` -> `dist` ->
- * package root, where `env.ts` sits (deliberately outside `src/`, per that
- * file's own header — `tsconfig.typecheck.json` includes it as a sibling
- * of `src` for exactly that reason). Same file, same relative shape, in
- * both a workspace checkout (`packages/devtools/env.ts`) and an installed
- * copy (`node_modules/@devdogsuga/devtools/env.ts`).
- */
-function ownManifestPath() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    return join(here, "..", "..", "env.ts");
-}
-function workspaceDirs() {
-    const dirs = [];
-    const repoRoot = findRepoRoot();
-    for (const parent of ["apps", "packages"]) {
-        const names = [];
-        for (const entry of readdirSync(join(repoRoot, parent), {
-            withFileTypes: true,
-        })) {
-            // node_modules and dotfiles are not packages.
-            if (!entry.isDirectory())
-                continue;
-            if (entry.name === "node_modules" || entry.name.startsWith("."))
-                continue;
-            names.push(entry.name);
-        }
-        // Sorted, because readdir order is whatever the filesystem feels like and
-        // registry insertion order is now OBSERVABLE: `env example` renders
-        // keys in declaration order and CI byte-compares the result, so two
-        // machines walking the same tree must import the same manifests in the
-        // same sequence.
-        names.sort();
-        for (const name of names)
-            dirs.push(join(repoRoot, parent, name));
-    }
-    dirs.push(join(repoRoot, "docs"));
-    return dirs;
-}
-/** `src/env.ts`, then `env.ts`; both present in one package is a hard error. */
-function manifestIn(dir) {
-    const inSrc = join(dir, "src", "env.ts");
-    const atRoot = join(dir, "env.ts");
-    const hasSrc = existsSync(inSrc);
-    const hasRoot = existsSync(atRoot);
-    if (hasSrc && hasRoot) {
-        throw new Error(`${dir} has BOTH src/env.ts and env.ts. One package gets one manifest — ` +
-            "two of them means two places for the next declaration to land, and " +
-            "no rule saying which. Merge them.");
-    }
-    return hasSrc ? inSrc : hasRoot ? atRoot : null;
-}

package/dist/env/document.d.ts

@@ -1,119 +0,0 @@
-/**
- * An editable `.env` that survives being edited.
- *
- * The root `.env` is not a data file. It is 150 lines of hard-won commentary
- * about which value breaks the Supabase CLI when empty, which one must stay
- * commented out, and why. A writer that parses to a Map and serializes back
- * destroys all of it on the first save.
- *
- * So this keeps the file as **lines** and edits in place. An untouched line is
- * returned byte-for-byte, including its spacing, quoting style and trailing
- * comment. Only the lines actually being changed are rewritten.
- *
- * Nothing is ever deleted. Removing a key comments it out, so the value stays
- * recoverable from the file itself, and re-adding it later uncomments that line
- * rather than appending a duplicate.
- */
-export interface EnvLine {
-    raw: string;
-    key?: string;
-    /** Parsed value, when this line is an assignment. */
-    value?: string;
-    commented?: boolean;
-}
-/**
- * Reads the value half of an assignment.
- *
- * Deliberately NOT a general dotenv parser: it does not expand `$VAR`, because
- * a stored value that means one thing in the file and another in the process
- * cannot be rotated with confidence.
- */
-export declare function parseValue(rest: string): string;
-/**
- * Splits everything after `=` into its value and its trailing comment.
- *
- * Quote-aware, because the naive "cut at the first `#`" truncates a generated
- * password into something that still looks like one. A `#` inside quotes is
- * part of the value; outside them it starts a comment only when whitespace
- * precedes it.
- */
-export declare function splitComment(rest: string): {
-    comment: string;
-};
-/**
- * Where a value came from and when, written on the same line as the value.
- *
- * It answers "is this still what production has?" without running anything. A
- * `.env` that has been sitting for three weeks says so rather than looking
- * exactly like one pulled this morning.
- */
-export interface Stamp {
-    environment: string;
-    action: "pushed" | "pulled";
-    /** ISO date. Passed in rather than read from the clock, so this is testable. */
-    date: string;
-}
-export declare function isStamp(comment: string): boolean;
-/** Always double-quoted, so a multi-line value round-trips through one line. */
-export declare function quote(value: string): string;
-export declare class EnvDocument {
-    private lines;
-    /** Whether this session has already appended, so it separates only once. */
-    private appended;
-    private constructor();
-    static parse(text: string): EnvDocument;
-    static empty(): EnvDocument;
-    private find;
-    /** The active value, or undefined when absent or commented out. */
-    get(key: string): string | undefined;
-    /** Present and active. */
-    has(key: string): boolean;
-    /** Present, but commented out. */
-    isCommented(key: string): boolean;
-    /** Every active assignment, in file order. */
-    entries(): [string, string][];
-    keys(): string[];
-    /**
-     * Sets a value, preferring to revive a commented line over appending.
-     *
-     * Appending when a commented form already exists is how a file ends up with
-     * the same key twice: one stale, both plausible, and which one looks
-     * authoritative depends on where the reader scrolled to.
-     */
-    set(key: string, value: string, stamp?: Stamp): void;
-    /** Index of the first line mentioning a key, active or commented. */
-    private first;
-    /**
-     * Moves every line for a key next to that key's first appearance.
-     *
-     * Files drift: a key gets commented out near the bottom, re-added at the top
-     * six weeks later, and now two lines claim the same name a hundred lines
-     * apart. Whichever one a reader scrolls to first looks authoritative.
-     *
-     * The FIRST occurrence keeps its position, so the standalone comment block
-     * documenting a key stays attached to it. Everything else moves up to join
-     * it, in the order it already had.
-     */
-    group(): boolean;
-    /**
-     * Blanks every active value without losing one.
-     *
-     * Each becomes a commented line holding what it was, plus an empty active
-     * line under it. The file still declares every key it needs, which is what
-     * makes it a usable checklist, while holding nothing.
-     *
-     * Already-empty keys are skipped. Commenting out `FOO=""` to write `FOO=""`
-     * underneath is churn that makes the next diff harder to read.
-     */
-    reset(): string[];
-    /**
-     * Comments a key out rather than deleting it.
-     *
-     * A no-op when it is already commented or absent, so running a sync twice
-     * cannot produce `## KEY=`.
-     */
-    comment(key: string): boolean;
-    /** Restores a commented assignment. Returns its value, or undefined. */
-    uncomment(key: string): string | undefined;
-    toString(): string;
-}

package/dist/env/document.js

@@ -1,323 +0,0 @@
-/**
- * An editable `.env` that survives being edited.
- *
- * The root `.env` is not a data file. It is 150 lines of hard-won commentary
- * about which value breaks the Supabase CLI when empty, which one must stay
- * commented out, and why. A writer that parses to a Map and serializes back
- * destroys all of it on the first save.
- *
- * So this keeps the file as **lines** and edits in place. An untouched line is
- * returned byte-for-byte, including its spacing, quoting style and trailing
- * comment. Only the lines actually being changed are rewritten.
- *
- * Nothing is ever deleted. Removing a key comments it out, so the value stays
- * recoverable from the file itself, and re-adding it later uncomments that line
- * rather than appending a duplicate.
- */
-/**
- * `KEY=value`, active. Groups: indent, `export ` prefix, key, value.
- *
- * The prefix is CAPTURED rather than skipped so an update can put it back.
- * Dropping it turns `export FOO=` into `FOO=`, which still parses here and
- * stops being exported to child processes. That shows up as a missing variable
- * three tools downstream.
- */
-const ACTIVE = /^(\s*)((?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
-/** `# KEY=value`, the commented form this tool writes and reads back. */
-const COMMENTED = /^(\s*)#\s?((?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
-/**
- * Reads the value half of an assignment.
- *
- * Deliberately NOT a general dotenv parser: it does not expand `$VAR`, because
- * a stored value that means one thing in the file and another in the process
- * cannot be rotated with confidence.
- */
-export function parseValue(rest) {
-    const text = rest.trim();
-    if (text.startsWith('"')) {
-        const end = findClosing(text, '"');
-        if (end === -1)
-            return unescape(text.slice(1));
-        return unescape(text.slice(1, end));
-    }
-    if (text.startsWith("'")) {
-        const end = findClosing(text, "'");
-        if (end === -1)
-            return text.slice(1);
-        // Single quotes are literal, the only way to store a backslash sequence
-        // verbatim.
-        return text.slice(1, end);
-    }
-    // Unquoted. A `#` only starts a comment when whitespace precedes it: `#` is
-    // an ordinary character in a generated password, and stripping from the first
-    // one truncates the credential into something that still looks like one.
-    const hash = text.search(/\s#/);
-    return (hash === -1 ? text : text.slice(0, hash)).trim();
-}
-function findClosing(text, quote) {
-    for (let i = 1; i < text.length; i += 1) {
-        if (text[i] === "\\") {
-            i += 1;
-            continue;
-        }
-        if (text[i] === quote)
-            return i;
-    }
-    return -1;
-}
-function unescape(text) {
-    return text.replace(/\\([nrt\\"'])/g, (_, c) => c === "n" ? "\n" : c === "r" ? "\r" : c === "t" ? "\t" : c);
-}
-/**
- * Splits everything after `=` into its value and its trailing comment.
- *
- * Quote-aware, because the naive "cut at the first `#`" truncates a generated
- * password into something that still looks like one. A `#` inside quotes is
- * part of the value; outside them it starts a comment only when whitespace
- * precedes it.
- */
-export function splitComment(rest) {
-    const text = rest.trimStart();
-    let after;
-    if (text.startsWith('"') || text.startsWith("'")) {
-        const end = findClosing(text, text[0]);
-        after = end === -1 ? text.length : end + 1;
-    }
-    else {
-        const hash = text.search(/\s#/);
-        after = hash === -1 ? text.length : hash;
-    }
-    const tail = text.slice(after);
-    const hash = tail.indexOf("#");
-    return { comment: hash === -1 ? "" : tail.slice(hash).trimEnd() };
-}
-/**
- * Recognises a stamp this tool wrote, so it is replaced rather than duplicated.
- *
- * Deliberately narrow: it matches the exact bracketed shape below and nothing
- * else, because the cost of a false positive is deleting somebody's own note.
- */
-const STAMP = /\s*#\s*\[[a-z][a-z0-9-]* (?:pushed|pulled) \d{4}-\d{2}-\d{2}\]\s*$/;
-function stampText(stamp) {
-    return `# [${stamp.environment} ${stamp.action} ${stamp.date}]`;
-}
-export function isStamp(comment) {
-    return STAMP.test(comment);
-}
-/** Always double-quoted, so a multi-line value round-trips through one line. */
-export function quote(value) {
-    return `"${value
-        .replace(/\\/g, "\\\\")
-        .replace(/"/g, '\\"')
-        .replace(/\n/g, "\\n")
-        .replace(/\r/g, "\\r")
-        .replace(/\t/g, "\\t")}"`;
-}
-export class EnvDocument {
-    lines;
-    /** Whether this session has already appended, so it separates only once. */
-    appended = false;
-    constructor(lines) {
-        this.lines = lines;
-    }
-    static parse(text) {
-        const lines = text.split("\n").map((raw) => {
-            const active = ACTIVE.exec(raw);
-            if (active) {
-                return { raw, key: active[3], value: parseValue(active[4]) };
-            }
-            const commented = COMMENTED.exec(raw);
-            if (commented) {
-                return {
-                    raw,
-                    key: commented[3],
-                    value: parseValue(commented[4]),
-                    commented: true,
-                };
-            }
-            return { raw };
-        });
-        return new EnvDocument(lines);
-    }
-    static empty() {
-        return new EnvDocument([]);
-    }
-    find(key, commented) {
-        return this.lines.findIndex((l) => l.key === key && Boolean(l.commented) === commented);
-    }
-    /** The active value, or undefined when absent or commented out. */
-    get(key) {
-        const i = this.find(key, false);
-        return i === -1 ? undefined : this.lines[i].value;
-    }
-    /** Present and active. */
-    has(key) {
-        return this.find(key, false) !== -1;
-    }
-    /** Present, but commented out. */
-    isCommented(key) {
-        return this.find(key, false) === -1 && this.find(key, true) !== -1;
-    }
-    /** Every active assignment, in file order. */
-    entries() {
-        return this.lines
-            .filter((l) => l.key !== undefined && !l.commented)
-            .map((l) => [l.key, l.value]);
-    }
-    keys() {
-        return this.entries().map(([k]) => k);
-    }
-    /**
-     * Sets a value, preferring to revive a commented line over appending.
-     *
-     * Appending when a commented form already exists is how a file ends up with
-     * the same key twice: one stale, both plausible, and which one looks
-     * authoritative depends on where the reader scrolled to.
-     */
-    set(key, value, stamp) {
-        const active = this.find(key, false);
-        if (active !== -1) {
-            const line = this.lines[active];
-            const match = ACTIVE.exec(line.raw);
-            const existing = splitComment(match[4]).comment;
-            // Somebody's own note gets moved out of the way rather than overwritten.
-            // It was written about this key, so it belongs above the whole group:
-            // the commented-out history sits between the note and the key.
-            if (stamp && existing !== "" && !isStamp(existing)) {
-                this.lines.splice(this.first(key), 0, { raw: existing });
-            }
-            const trailing = stamp
-                ? ` ${stampText(stamp)}`
-                : existing === ""
-                    ? ""
-                    : ` ${existing}`;
-            // Re-find: the splice above may have shifted this line down.
-            const at = this.find(key, false);
-            const target = this.lines[at];
-            target.raw = `${match[1]}${match[2]}${key}=${quote(value)}${trailing}`;
-            target.value = value;
-            return;
-        }
-        const commented = this.find(key, true);
-        if (commented !== -1) {
-            const line = this.lines[commented];
-            line.raw = `${key}=${quote(value)}${stamp ? ` ${stampText(stamp)}` : ""}`;
-            line.value = value;
-            line.commented = false;
-            return;
-        }
-        // One blank line between the file's own contents and anything appended,
-        // and only one: a separator per appended key would grow a gap every time a
-        // sync adds a batch.
-        if (!this.appended &&
-            this.lines.length > 0 &&
-            this.lines.at(-1).raw !== "") {
-            this.lines.push({ raw: "" });
-        }
-        this.appended = true;
-        this.lines.push({
-            raw: `${key}=${quote(value)}${stamp ? ` ${stampText(stamp)}` : ""}`,
-            key,
-            value,
-        });
-    }
-    /** Index of the first line mentioning a key, active or commented. */
-    first(key) {
-        return this.lines.findIndex((l) => l.key === key);
-    }
-    /**
-     * Moves every line for a key next to that key's first appearance.
-     *
-     * Files drift: a key gets commented out near the bottom, re-added at the top
-     * six weeks later, and now two lines claim the same name a hundred lines
-     * apart. Whichever one a reader scrolls to first looks authoritative.
-     *
-     * The FIRST occurrence keeps its position, so the standalone comment block
-     * documenting a key stays attached to it. Everything else moves up to join
-     * it, in the order it already had.
-     */
-    group() {
-        const out = [];
-        const taken = new Set();
-        let moved = false;
-        for (let i = 0; i < this.lines.length; i += 1) {
-            if (taken.has(i))
-                continue;
-            const line = this.lines[i];
-            out.push(line);
-            taken.add(i);
-            if (line.key === undefined)
-                continue;
-            for (let j = i + 1; j < this.lines.length; j += 1) {
-                if (taken.has(j) || this.lines[j].key !== line.key)
-                    continue;
-                if (j !== i + 1 || taken.has(i + 1))
-                    moved = true;
-                out.push(this.lines[j]);
-                taken.add(j);
-            }
-        }
-        this.lines = out;
-        return moved;
-    }
-    /**
-     * Blanks every active value without losing one.
-     *
-     * Each becomes a commented line holding what it was, plus an empty active
-     * line under it. The file still declares every key it needs, which is what
-     * makes it a usable checklist, while holding nothing.
-     *
-     * Already-empty keys are skipped. Commenting out `FOO=""` to write `FOO=""`
-     * underneath is churn that makes the next diff harder to read.
-     */
-    reset() {
-        const out = [];
-        const cleared = [];
-        for (const line of this.lines) {
-            if (line.key === undefined || line.commented || line.value === "") {
-                out.push(line);
-                continue;
-            }
-            const exported = ACTIVE.exec(line.raw)?.[2] ?? "";
-            line.raw = `# ${line.raw.trimStart()}`;
-            line.commented = true;
-            out.push(line);
-            out.push({
-                raw: `${exported}${line.key}=""`,
-                key: line.key,
-                value: "",
-            });
-            cleared.push(line.key);
-        }
-        this.lines = out;
-        return cleared;
-    }
-    /**
-     * Comments a key out rather than deleting it.
-     *
-     * A no-op when it is already commented or absent, so running a sync twice
-     * cannot produce `## KEY=`.
-     */
-    comment(key) {
-        const i = this.find(key, false);
-        if (i === -1)
-            return false;
-        const line = this.lines[i];
-        line.raw = `# ${line.raw.trimStart()}`;
-        line.commented = true;
-        return true;
-    }
-    /** Restores a commented assignment. Returns its value, or undefined. */
-    uncomment(key) {
-        const i = this.find(key, true);
-        if (i === -1)
-            return undefined;
-        const line = this.lines[i];
-        line.raw = line.raw.replace(/^(\s*)#\s?/, "$1");
-        line.commented = false;
-        return line.value;
-    }
-    toString() {
-        return this.lines.map((l) => l.raw).join("\n");
-    }
-}