@devdogsuga/backstage 0.1.5 → 0.1.6

package/dist/commands-CLSxKz-l.js

@@ -0,0 +1,352 @@
+import { n as isDryRun } from "./dry-run-3IxPmCtW.js";
+import { r as errorMessage, t as UsageError } from "./ui-CdKo8mLw.js";
+import { t as DONE } from "./dispatch-D048O65I.js";
+import { a as reportFailure, d as withConnection, i as readInputFile, n as confirmWrite, o as say, r as plural, t as canPrompt, u as requireProductionKey } from "./cli-Do2nWD7W.js";
+import { a as createAccounts, i as createAccountFor, n as accountFinder, o as readAccounts, t as parseCsv } from "./read-B-aJJewb.js";
+import { parseArgs } from "node:util";
+//#region src/involvement/csv.ts
+/**
+* Reading the UGA Involvement Network's "Organization Roster" export.
+*
+* The export is not a plain CSV. It opens with a title line, a blank line and
+* an `Organization,date` line before the header, hides most columns as
+* `(Hidden)`, and lists a person once per position they hold, so an officer
+* appears as both `Member` and `President`. The header is found rather than
+* assumed to be the first line, which is what broke the platform's upload: it
+* took `Organization Roster` for the header and found no rows.
+*/
+var RosterFormatError = class extends Error {
+	name = "RosterFormatError";
+};
+/** Header names for each field, the first one present wins. */
+const COLUMNS = {
+	firstName: ["first name"],
+	lastName: ["last name"],
+	email: ["campus email", "email"],
+	organization: ["organization name"],
+	position: ["position name"]
+};
+function columnIndex(header, names) {
+	const normalized = header.map((h) => h.trim().toLowerCase());
+	for (const name of names) {
+		const i = normalized.indexOf(name);
+		if (i >= 0) return i;
+	}
+	return -1;
+}
+function clean(value) {
+	const v = (value ?? "").trim();
+	return v === "(Hidden)" ? "" : v;
+}
+function parseRoster(text) {
+	const rows = parseCsv(text);
+	const headerAt = rows.findIndex((r) => columnIndex(r, COLUMNS.firstName) >= 0 && columnIndex(r, COLUMNS.lastName) >= 0 && columnIndex(r, COLUMNS.email) >= 0);
+	if (headerAt < 0) throw new RosterFormatError("No header row with \"First Name\", \"Last Name\" and \"Campus Email\". Export the roster from the Involvement Network's Roster page (Export → Organization Roster) and pass that file.");
+	const header = rows[headerAt];
+	const at = {
+		firstName: columnIndex(header, COLUMNS.firstName),
+		lastName: columnIndex(header, COLUMNS.lastName),
+		email: columnIndex(header, COLUMNS.email),
+		organization: columnIndex(header, COLUMNS.organization),
+		position: columnIndex(header, COLUMNS.position)
+	};
+	const byEmail = /* @__PURE__ */ new Map();
+	const organizations = /* @__PURE__ */ new Set();
+	const skippedLines = [];
+	const conflicting = /* @__PURE__ */ new Set();
+	rows.slice(headerAt + 1).forEach((row, i) => {
+		if (row.every((cell) => cell.trim() === "")) return;
+		const email = clean(row[at.email]).toLowerCase();
+		const firstName = clean(row[at.firstName]);
+		const lastName = clean(row[at.lastName]);
+		if (!email.includes("@") || !firstName || !lastName) {
+			skippedLines.push(headerAt + i + 2);
+			return;
+		}
+		if (at.organization >= 0) {
+			const org = clean(row[at.organization]);
+			if (org) organizations.add(org);
+		}
+		const position = at.position >= 0 ? clean(row[at.position]) : "";
+		const existing = byEmail.get(email);
+		if (existing) {
+			if (existing.firstName !== firstName || existing.lastName !== lastName) conflicting.add(email);
+			if (position && !existing.positions.includes(position)) existing.positions.push(position);
+			return;
+		}
+		byEmail.set(email, {
+			email,
+			firstName,
+			lastName,
+			positions: position ? [position] : []
+		});
+	});
+	return {
+		members: [...byEmail.values()],
+		organizations: [...organizations],
+		skippedLines,
+		conflictingNames: [...conflicting]
+	};
+}
+//#endregion
+//#region src/involvement/plan.ts
+/**
+* What an import would do, worked out before anything is written.
+*
+* The roster is the whole truth about who is involved: everyone on it is
+* verified, and everyone verified who is not on it loses that status. So the
+* plan is four lists, and the preview prints them before the confirmation.
+*
+* Preferred names are never changed: the roster's spelling may not be the
+* name a member goes by, and the preferred name is what the site shows. A
+* difference is listed for an officer to follow up on.
+*
+* A roster email finds its account the way `production/accounts.ts` says:
+* the profile's `ugaEmail` first, then the sign-in address.
+*/
+function nonBlank(value) {
+	const v = value?.trim();
+	if (!v) return void 0;
+	return v;
+}
+function planImport(members, accounts) {
+	const find = accountFinder(accounts);
+	const plan = {
+		create: [],
+		verify: [],
+		keep: [],
+		drop: [],
+		sharedAccounts: [],
+		nameDiffers: []
+	};
+	const claimed = /* @__PURE__ */ new Set();
+	for (const member of members) {
+		const account = find(member.email);
+		if (!account) {
+			plan.create.push(member);
+			continue;
+		}
+		if (claimed.has(account.userId)) {
+			plan.sharedAccounts.push({
+				email: member.email,
+				userId: account.userId
+			});
+			continue;
+		}
+		claimed.add(account.userId);
+		const match = {
+			member,
+			userId: account.userId,
+			hasProfile: account.hasProfile,
+			preferredName: account.preferredName
+		};
+		const rosterName = `${member.firstName} ${member.lastName}`.toLowerCase();
+		if (account.hasProfile && account.preferredName?.trim().toLowerCase() !== rosterName) plan.nameDiffers.push(match);
+		if (account.involvementFirstName != null) plan.keep.push(match);
+		else plan.verify.push(match);
+	}
+	for (const account of accounts) {
+		if (account.involvementFirstName == null || claimed.has(account.userId)) continue;
+		plan.drop.push({
+			userId: account.userId,
+			name: nonBlank(account.preferredName) ?? `${account.involvementFirstName} ${account.involvementLastName ?? ""}`.trim()
+		});
+	}
+	plan.drop.sort((a, b) => a.name.localeCompare(b.name));
+	return plan;
+}
+/** Everyone the import writes a profile for, created accounts excluded. */
+function matches(plan) {
+	return [...plan.verify, ...plan.keep];
+}
+//#endregion
+//#region src/involvement/store.ts
+/**
+* The write half of `import involvement`, after `plan.ts` has matched the
+* roster against production's accounts (`production/accounts.ts`) and any
+* missing accounts have been created.
+*
+* Accounts are created before this transaction, because Auth is a separate
+* service. If the transaction then fails, those accounts exist without
+* profiles; the next run finds them by sign-in address and inserts the
+* profiles, so a rerun is the recovery.
+*/
+/**
+* Upserts every roster member's profile, then clears involvement from every
+* profile not among them, in one transaction.
+*
+* A new profile takes the roster's name as its preferred name; an existing
+* one keeps its own (see `plan.ts`). The durable identity columns (`ugaEmail`, `legal*`,
+* `identitySourcedAt`) are written for everyone on the roster and never
+* cleared, so missing one export does not erase who someone is.
+*/
+const APPLY_UPSERT = `
+insert into "platform"."profile" as p (
+  "userId", "preferredName",
+  "involvementFirstName", "involvementLastName", "involvementImportedAt",
+  "ugaEmail", "legalFirstName", "legalLastName", "identitySourcedAt"
+)
+select t.u, t.f || ' ' || t.l, t.f, t.l, now(), t.e, t.f, t.l, now()
+from unnest($1::uuid[], $2::text[], $3::text[], $4::text[]) as t(u, f, l, e)
+on conflict ("userId") do update set
+  "involvementFirstName" = excluded."involvementFirstName",
+  "involvementLastName" = excluded."involvementLastName",
+  "involvementImportedAt" = excluded."involvementImportedAt",
+  "ugaEmail" = excluded."ugaEmail",
+  "legalFirstName" = excluded."legalFirstName",
+  "legalLastName" = excluded."legalLastName",
+  "identitySourcedAt" = excluded."identitySourcedAt"
+`;
+const APPLY_CLEAR = `
+update "platform"."profile"
+set "involvementFirstName" = null,
+    "involvementLastName" = null,
+    "involvementImportedAt" = null
+where not ("userId" = any($1::uuid[]))
+  and ("involvementFirstName" is not null or "involvementImportedAt" is not null)
+`;
+function applyImportFor(url) {
+	return (writes) => {
+		const ids = writes.map((w) => w.userId);
+		return withConnection(url, "The import was rolled back", (sql) => sql.begin(async (tx) => {
+			const upserted = await tx.unsafe(APPLY_UPSERT, [
+				ids,
+				writes.map((w) => w.firstName),
+				writes.map((w) => w.lastName),
+				writes.map((w) => w.email)
+			]);
+			const cleared = await tx.unsafe(APPLY_CLEAR, [ids]);
+			return {
+				written: upserted.count,
+				cleared: cleared.count
+			};
+		}));
+	};
+}
+//#endregion
+//#region src/involvement/commands.ts
+/**
+* `backstage import involvement --file <OrganizationRoster.csv>`: verify the
+* members on the UGA Involvement Network roster.
+*
+* Replaces the platform's /console/verification upload. Officers export the
+* roster from the Involvement Network (Roster → Export → Organization Roster)
+* and run this against production:
+*
+* 1. read and check the export (`csv.ts`): its organization must be DevDogs;
+* 2. read every account and plan the import (`plan.ts`);
+* 3. print who is newly verified, who loses verification, and how many
+*    accounts would be created, then ask;
+* 4. create the missing accounts and write the profiles (`store.ts`).
+*
+* `--dry-run` stops after the preview. Production's `DB_URL`, `API_URL` and
+* `SECRET_KEY` come from the checkout's `.env.production`, else Secrets
+* Manager, so it runs under `pnpm dlx` with no checkout.
+*
+* Preferred names are never changed, so the homepage's officer board (which
+* caches them) needs no invalidation.
+*/
+/** The organization a roster must be for. Compared case-insensitively. */
+const ORGANIZATION = "DevDogs";
+function parse(argv) {
+	try {
+		return parseArgs({
+			args: [...argv],
+			options: {
+				file: { type: "string" },
+				yes: { type: "boolean" },
+				"dry-run": { type: "boolean" }
+			},
+			allowPositionals: false,
+			strict: true
+		}).values;
+	} catch (err) {
+		throw new UsageError(errorMessage(err));
+	}
+}
+/** The preview: what changes, by whom. Never lists every kept member. */
+function describePlan(plan, members) {
+	const lines = [
+		`${plural(members, "member")} on the roster:`,
+		`  ${plan.keep.length} already verified`,
+		`  ${plan.verify.length} newly verified (have an account)`,
+		`  ${plan.create.length} without an account, to be created and verified`,
+		`  ${plan.drop.length} verified now but not on the roster, to lose verification`
+	];
+	if (plan.verify.length > 0) lines.push("", "Newly verified:", ...plan.verify.map((m) => `  ${m.member.firstName} ${m.member.lastName} <${m.member.email}>`));
+	if (plan.drop.length > 0) lines.push("", "Losing verification:", ...plan.drop.map((d) => `  ${d.name}`));
+	if (plan.nameDiffers.length > 0) lines.push("", "Preferred name differs from the roster (left as is):", ...plan.nameDiffers.map((m) => `  ${m.preferredName ?? "(none)"}: roster says ${m.member.firstName} ${m.member.lastName}`));
+	if (plan.sharedAccounts.length > 0) lines.push("", "Skipped, their account already matched another roster email:", ...plan.sharedAccounts.map((s) => `  ${s.email}`));
+	return lines.join("\n");
+}
+async function runInvolvement(argv, deps = {}) {
+	const interactive = deps.interactive ?? canPrompt();
+	try {
+		const values = parse(argv);
+		const dryRun = values["dry-run"] === true || isDryRun();
+		const roster = parseRoster(await readInputFile(values.file, {
+			interactive,
+			message: "Path to the Involvement Network roster export",
+			placeholder: "OrganizationRoster.csv",
+			read: deps.readFile
+		}));
+		const wrongOrg = roster.organizations.filter((o) => o.toLowerCase() !== ORGANIZATION.toLowerCase());
+		if (wrongOrg.length > 0) throw new UsageError(`This roster is for ${wrongOrg.join(", ")}, not ${ORGANIZATION}.`);
+		if (roster.members.length === 0) throw new UsageError("The roster has no members with a name and email.");
+		if (roster.skippedLines.length > 0) say(`Skipped ${plural(roster.skippedLines.length, "row")} missing a name or email (lines ${roster.skippedLines.join(", ")}).`, "warn");
+		if (roster.conflictingNames.length > 0) say(`Listed under two names, kept the first: ${roster.conflictingNames.join(", ")}.`, "warn");
+		const dbUrl = deps.accounts ? void 0 : await requireProductionKey("DB_URL");
+		const accounts = await (deps.accounts ?? (() => readAccounts(dbUrl)))();
+		const plan = planImport(roster.members, accounts);
+		process.stderr.write(`${describePlan(plan, roster.members.length)}\n`);
+		if (dryRun) {
+			say("Dry run: nothing written.");
+			return;
+		}
+		if (plan.create.length === 0 && plan.verify.length === 0 && plan.drop.length === 0 && plan.keep.length === 0) {
+			say("Nothing to import.");
+			return;
+		}
+		const question = `Import into production: create ${plural(plan.create.length, "account")}, verify ${plan.verify.length}, unverify ${plan.drop.length}?`;
+		if (!await confirmWrite(question, {
+			yes: values.yes === true,
+			interactive
+		})) {
+			say("Nothing written.");
+			return;
+		}
+		let create = deps.createAccount;
+		if (!create && plan.create.length > 0) create = createAccountFor(await requireProductionKey("API_URL"), await requireProductionKey("SECRET_KEY"));
+		const { created: createdIds, failed } = create ? await createAccounts(plan.create.map((m) => m.email), create) : {
+			created: /* @__PURE__ */ new Map(),
+			failed: []
+		};
+		const created = plan.create.flatMap((m) => {
+			const userId = createdIds.get(m.email);
+			return userId ? [{
+				userId,
+				email: m.email,
+				firstName: m.firstName,
+				lastName: m.lastName
+			}] : [];
+		});
+		if (failed.length > 0) say(`Could not create ${plural(failed.length, "account")}; they stay unverified until the next import:\n${failed.map((f) => `  ${f.email}: ${f.reason}`).join("\n")}`, "warn");
+		const writes = [...matches(plan).map((m) => ({
+			userId: m.userId,
+			email: m.member.email,
+			firstName: m.member.firstName,
+			lastName: m.member.lastName
+		})), ...created];
+		const { written, cleared } = await (deps.apply ?? applyImportFor(dbUrl))(writes);
+		say(`Imported: ${plural(written, "profile")} verified (${plural(created.length, "new account")}), ${cleared} unverified.`, "success");
+		if (failed.length > 0) process.exitCode = 1;
+	} catch (err) {
+		reportFailure("import involvement", err, [RosterFormatError]);
+	}
+}
+const handleInvolvement = async (rest) => {
+	await runInvolvement(rest);
+	return process.exitCode ? null : DONE;
+};
+//#endregion
+export { handleInvolvement };

package/dist/commands-DzALVX5g.js

@@ -0,0 +1,12 @@
+import { i as explain } from "./ui-CdKo8mLw.js";
+//#region src/import/commands.ts
+const handleImport = async (rest) => {
+	const [what, ...args] = rest;
+	if (what === "involvement") return (await import("./commands-CLSxKz-l.js")).handleInvolvement(args);
+	if (what === "attendance") return (await import("./commands-BQ2NIqub.js")).handleAttendance(args);
+	explain(what ? `Unknown import "${what}". Try involvement or attendance.` : "Name the import: involvement or attendance.", "");
+	process.exitCode = 1;
+	return null;
+};
+//#endregion
+export { handleImport };

package/dist/{commands-Bk7IbhPD.js → commands-Sx1fDNNn.js}

@@ -1,6 +1,7 @@
 import { p as isNonInteractive } from "./telemetry-Bjoz29Hl.js";
-import { i as qrParseOptions, n as QR_FLAGS, o as isDryRun, t as QR_EXTRA_FLAGS } from "./options-BTjOf5KP.js";
+import { n as isDryRun } from "./dry-run-3IxPmCtW.js";
 import { a as explainError, o as unwrap, t as UsageError } from "./ui-CdKo8mLw.js";
+import { i as qrParseOptions, n as QR_FLAGS, t as QR_EXTRA_FLAGS } from "./options-DCaqm8BI.js";
 import { t as DONE } from "./dispatch-D048O65I.js";
 import { dirname, extname, relative, resolve } from "node:path";
 import { log, text } from "@clack/prompts";

package/dist/{commands-BMQ1OZIr.js → commands-zPSnOGzH.js}

@@ -1,8 +1,9 @@
 import { C as discoverRepoRoot, p as isNonInteractive } from "./telemetry-Bjoz29Hl.js";
 import { t as nonEmpty } from "./connection-D3XsOE3S.js";
 import { a as explainError, i as explain, o as unwrap, r as errorMessage, t as UsageError } from "./ui-CdKo8mLw.js";
-import { c as EnvDocument, i as readPasswordFromVault, n as bwArgs, r as openVault, s as bwCommand } from "./vault-C8LYJFOQ.js";
 import { t as DONE } from "./dispatch-D048O65I.js";
+import { t as EnvDocument } from "./document-DumoZXoO.js";
+import { i as readPasswordFromVault, n as bwArgs, r as openVault, s as bwCommand } from "./vault-CsBC-1Mq.js";
 import { resolve } from "node:path";
 import { confirm, log, multiselect, note, password, select, text } from "@clack/prompts";
 import { readFile } from "node:fs/promises";
@@ -631,7 +632,7 @@ async function readCheckoutDbUrl() {
 	}
 }
 async function readSecretsManagerDbUrl() {
-	const { listSecrets, projectIdFor } = await import("./client-DzXQHd58.js");
+	const { listSecrets, projectIdFor } = await import("./client-DwDGjalU.js");
 	const secrets = await listSecrets(await projectIdFor(PRODUCTION_PROJECT));
 	return nonEmpty(secrets.find((s) => s.key === "DB_URL")?.value);
 }

package/dist/document-DumoZXoO.js

@@ -0,0 +1,287 @@
+//#region ../cli-core/src/env/document.ts
+/**
+* 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.
+*/
+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);
+		return text.slice(1, end);
+	}
+	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" ? "	" : 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.
+*/
+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}]`;
+}
+function isStamp(comment) {
+	return STAMP.test(comment);
+}
+/** Always double-quoted, so a multi-line value round-trips through one line. */
+function quote(value) {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+}
+var EnvDocument = 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 ? void 0 : 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 !== void 0 && !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;
+			if (stamp && existing !== "" && !isStamp(existing)) this.lines.splice(this.first(key), 0, { raw: existing });
+			const trailing = stamp ? ` ${stampText(stamp)}` : existing === "" ? "" : ` ${existing}`;
+			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;
+		}
+		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 = /* @__PURE__ */ 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 === void 0) 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 === void 0 || 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 void 0;
+		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");
+	}
+};
+//#endregion
+export { EnvDocument as t };