@devdogsuga/backstage 0.1.3 → 0.1.5

package/dist/commands-BMQ1OZIr.js

@@ -0,0 +1,1157 @@
+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 { resolve } from "node:path";
+import { confirm, log, multiselect, note, password, select, text } from "@clack/prompts";
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import postgres from "postgres";
+//#region src/creds/secrets.ts
+/**
+* The secret values this process has seen, so nothing it prints can carry one.
+*
+* `creds` holds live passwords in memory: it reads them from Bitwarden items
+* and writes them into Send bodies. They must never reach stdout, stderr, the
+* failure log, Sentry or an error message. The code never prints one on
+* purpose, but `bw` writes its own errors, and an error message that quotes its
+* input is one refactor away. So every value is registered the moment it is
+* read, and every string that leaves through an error passes {@link scrub}.
+*
+* Masking in the preview is a separate thing: it never has the value to begin
+* with (see `item.ts`'s `MASK`).
+*/
+const seen = /* @__PURE__ */ new Set();
+/**
+* Values shorter than this are not registered. Scrubbing a two-character
+* password out of every message would shred the messages and protect nothing
+* a two-character password had left to protect.
+*/
+const MIN_LENGTH = 4;
+/** Records a value that must never be printed. */
+function registerSecret(value) {
+	if (value && value.length >= MIN_LENGTH) seen.add(value);
+}
+const REDACTED = "<redacted>";
+/** `text` with every registered value replaced. Longest first, so a value that contains another is removed whole. */
+function scrub(text) {
+	let out = text;
+	for (const value of [...seen].sort((a, b) => b.length - a.length)) out = out.split(value).join(REDACTED);
+	return out;
+}
+/** An error whose message has already been scrubbed. Safe to print and report. */
+var CredsError = class extends Error {
+	name = "CredsError";
+	constructor(message) {
+		super(scrub(message));
+	}
+};
+//#endregion
+//#region src/creds/item.ts
+/**
+* A shared account as `creds` sees it: a login or secure note in the DevDogs
+* Bitwarden organization, plus the custom fields that record who has it.
+*
+* Those fields are the only access record. The Send, the Linear report and
+* every "who has Canva?" answer are generated from them, so they are plain
+* text fields anyone with the item can read and correct in Bitwarden
+* itself:
+*
+*   Recipients    comma-separated UGA emails, the Send's `--emails` list
+*   Owner         the officer responsible for the account
+*   Send ID       the Send's id, for `bw send edit`
+*   Send link     its access URL, for the report (Sends belong to whoever
+*                 created them, so another officer cannot look it up)
+*   Send expires  its deletion date, ISO 8601, for the report and `renew`
+*   Send account  the Bitwarden account that owns the Send
+*
+* The password, the TOTP seed and the notes of a secure note are registered
+* as secrets the moment an item is parsed (see `secrets.ts`).
+*/
+const FIELD = {
+	recipients: "Recipients",
+	owner: "Owner",
+	sendId: "Send ID",
+	sendLink: "Send link",
+	sendExpires: "Send expires",
+	sendAccount: "Send account"
+};
+/** Bitwarden's item types, as `bw` numbers them. */
+const ITEM_TYPE = {
+	login: 1,
+	secureNote: 2
+};
+/** What the preview shows for a password: fixed, so not even its length leaks. */
+const MASK = "••••••••";
+/** `value`, trimmed, or `undefined` when there is nothing in it. */
+function present(value) {
+	const trimmed = value?.trim();
+	return trimmed === void 0 || trimmed === "" ? void 0 : trimmed;
+}
+function field(raw, name) {
+	return present(raw.fields?.find((f) => f.name === name)?.value);
+}
+function splitEmails(value) {
+	return [...new Set((value ?? "").split(/[,\s]+/).map((e) => e.trim().toLowerCase()).filter(Boolean))];
+}
+/** Reads an item, registering its secret values first. */
+function parseItem(raw) {
+	registerSecret(raw.login?.password);
+	registerSecret(raw.login?.totp);
+	if (raw.type === ITEM_TYPE.secureNote) registerSecret(raw.notes);
+	for (const f of raw.fields ?? []) if (f.type === 1) registerSecret(f.value);
+	const sendId = field(raw, FIELD.sendId);
+	const expiresText = field(raw, FIELD.sendExpires);
+	const expires = expiresText ? new Date(expiresText) : void 0;
+	return {
+		raw,
+		id: raw.id,
+		name: raw.name,
+		username: present(raw.login?.username),
+		url: raw.login?.uris?.map((u) => present(u.uri)).find((u) => u !== void 0),
+		recipients: splitEmails(field(raw, FIELD.recipients)),
+		owner: field(raw, FIELD.owner),
+		send: sendId ? {
+			id: sendId,
+			link: field(raw, FIELD.sendLink),
+			expires: expires && !Number.isNaN(expires.getTime()) ? expires : void 0,
+			account: field(raw, FIELD.sendAccount)
+		} : void 0
+	};
+}
+/**
+* `raw` with the named text fields set (or removed, for `undefined`), every
+* other field and property left exactly as it was. Our fields are always
+* plain text: none of them is secret, and a hidden field would hide the
+* access record from the people meant to read it.
+*/
+function withFields(raw, updates) {
+	let fields = [...raw.fields ?? []];
+	for (const [key, value] of Object.entries(updates)) {
+		const name = FIELD[key];
+		const index = fields.findIndex((f) => f.name === name);
+		if (value === void 0 || value === "") {
+			if (index >= 0) fields = fields.filter((_, i) => i !== index);
+		} else if (index >= 0) fields[index] = {
+			...fields[index],
+			value,
+			type: 0
+		};
+		else fields.push({
+			name,
+			value,
+			type: 0
+		});
+	}
+	return {
+		...raw,
+		fields
+	};
+}
+/** What the recipient reads once Bitwarden has verified their email. Holds the password. */
+function sendBody(item) {
+	return body(item, item.raw.login?.password ?? void 0, item.raw.notes);
+}
+/**
+* {@link sendBody} with the password replaced by {@link MASK} and the notes by
+* a line count. Built from the item, never from the body, so there is no
+* string here that ever held the value.
+*/
+function previewBody(item) {
+	const notes = item.raw.notes?.trim();
+	const lines = notes ? notes.split("\n").length : 0;
+	return body(item, item.raw.login?.password ? MASK : void 0, notes ? `(notes: ${lines} line${lines === 1 ? "" : "s"}, not shown)` : null);
+}
+function body(item, password, notes) {
+	const lines = [item.name];
+	if (item.url) lines.push(`Login: ${item.url}`);
+	if (item.username) lines.push(`Username: ${item.username}`);
+	if (password) lines.push(`Password: ${password}`);
+	if (notes?.trim()) lines.push("", notes.trim());
+	lines.push("", "Shared by DevDogs officers. Please don't forward this link or the password; ask an officer to add you instead.");
+	return lines.join("\n");
+}
+const DAY = 864e5;
+function sendStatus(item, now) {
+	if (!item.send) return "No Send";
+	if (!item.send.expires) return "Active";
+	const left = item.send.expires.getTime() - now.getTime();
+	if (left <= 0) return "Expired";
+	return left <= 7 * DAY ? "Expires Soon" : "Active";
+}
+/** Whole days until the Send is deleted, rounded down; negative once it has been. */
+function daysLeft(item, now) {
+	const expires = item.send?.expires;
+	if (!expires) return void 0;
+	return Math.floor((expires.getTime() - now.getTime()) / DAY);
+}
+/** `YYYY-MM-DD`. */
+function isoDay(date) {
+	return date ? date.toISOString().slice(0, 10) : "—";
+}
+//#endregion
+//#region src/creds/bitwarden.ts
+/**
+* The DevDogs Bitwarden organization's items and the Sends made from them,
+* through the bundled `bw` on the officer's personal session (`bws/vault.ts`).
+*
+* Sends belong to the account that creates them, not to the organization, so
+* this always runs as a person and never on CI.
+*
+* ## Secret handling
+*
+* * Every value travels to `bw` on **stdin**, base64 JSON as `bw create`,
+*   `bw edit` and `bw send create|edit` document. argv carries only ids and
+*   the session key `bwArgs` already passes.
+* * `bw`'s stdout is parsed and never printed: an item or a Send read back
+*   holds the password.
+* * `bw`'s stderr is only shown through `CredsError`, which scrubs every value
+*   registered so far.
+*
+* ## The organization fence
+*
+* `creds` reads and writes the logins and secure notes of ONE organization,
+* found by name. Anything else the account can see (a personal login, another
+* organization's item) is never listed, never edited and never sent;
+* `updateItem` re-checks before every write. Production secrets are not
+* vault items at all: they live in Secrets Manager, which `bw` cannot read.
+*/
+/** Matched case-insensitively against the organizations the account belongs to. */
+const ORGANIZATION_NAME = "DevDogs";
+function encode(value) {
+	return Buffer.from(JSON.stringify(value)).toString("base64");
+}
+/** The real runner: the bundled `bw`, every stream piped, stdin always closed. */
+function spawnRunner(key) {
+	return (args, stdin) => new Promise((resolve) => {
+		const child = spawn(...bwCommand(bwArgs(args, key)), {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			shell: false
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (c) => stdout += c.toString());
+		child.stderr.on("data", (c) => stderr += c.toString());
+		child.on("error", (err) => resolve({
+			code: null,
+			stdout: "",
+			stderr: err.message
+		}));
+		child.on("close", (code) => resolve({
+			code,
+			stdout,
+			stderr
+		}));
+		child.stdin.end(stdin ?? "");
+	});
+}
+let runnerOverride;
+/** Opens the vault (asking first) and finds the DevDogs organization in it. */
+async function connectSharedVault() {
+	let runner = runnerOverride;
+	if (!runner) {
+		const vault = await openVault("share DevDogs logins");
+		if (!vault) throw new CredsError("Could not use your Bitwarden vault. `creds` needs your own session: run it at a terminal so it can sign in and unlock, or export BW_SESSION.");
+		runner = spawnRunner(vault.key);
+	}
+	const shared = new SharedVault(runner);
+	await shared.sync();
+	await shared.organization();
+	return shared;
+}
+var SharedVault = class {
+	run;
+	found;
+	constructor(run) {
+		this.run = run;
+	}
+	/** `bw <args>`, parsed as JSON, or a scrubbed `CredsError`. */
+	async json(args, stdin) {
+		const result = await this.run(args, stdin);
+		const label = `bw ${args.slice(0, args[0] === "send" ? 2 : 1).join(" ")}`;
+		if (result.code !== 0) throw new CredsError(`${label} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+		try {
+			return JSON.parse(result.stdout);
+		} catch {
+			throw new CredsError(`${label} printed something that is not JSON.`);
+		}
+	}
+	async sync() {
+		const result = await this.run(["sync"]);
+		if (result.code !== 0) throw new CredsError(`bw sync failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+	}
+	/** The signed-in account's email, recorded as the Send's owner. */
+	async account() {
+		return (await this.json(["status"])).userEmail ?? "unknown";
+	}
+	/** The one organization named like {@link ORGANIZATION_NAME} this account belongs to. */
+	async organization() {
+		if (this.found) return this.found;
+		const matches = (await this.json(["list", "organizations"])).filter((o) => o.name.toLowerCase().includes(ORGANIZATION_NAME.toLowerCase()));
+		if (matches.length !== 1) throw new CredsError(matches.length === 0 ? `Your Bitwarden account is not in the ${ORGANIZATION_NAME} organization. Ask an organization admin to invite you.` : `Your Bitwarden account is in ${matches.length} organizations named like "${ORGANIZATION_NAME}" (${matches.map((o) => o.name).join(", ")}); creds cannot tell which one to use.`);
+		this.found = matches[0];
+		return this.found;
+	}
+	shareable(raw, org) {
+		return raw.organizationId === org.id && (raw.type === ITEM_TYPE.login || raw.type === ITEM_TYPE.secureNote);
+	}
+	/** Every login and secure note in the organization, by name. */
+	async listItems() {
+		const org = await this.organization();
+		return (await this.json([
+			"list",
+			"items",
+			"--organizationid",
+			org.id
+		])).filter((item) => this.shareable(item, org)).map(parseItem).sort((a, b) => a.name.localeCompare(b.name));
+	}
+	/** The organization's collections this account can see, by name. */
+	async collections() {
+		const org = await this.organization();
+		return (await this.json([
+			"list",
+			"collections",
+			"--organizationid",
+			org.id
+		])).filter((c) => c.organizationId === org.id).sort((a, b) => a.name.localeCompare(b.name));
+	}
+	/** A new login, owned by the organization and placed in `collection`. */
+	async createLogin(input) {
+		registerSecret(input.password);
+		const org = await this.organization();
+		if (input.collection.organizationId !== org.id) throw new CredsError(`The "${input.collection.name}" collection is not in the ${org.name} organization.`);
+		const item = {
+			organizationId: org.id,
+			collectionIds: [input.collection.id],
+			folderId: null,
+			type: 1,
+			name: input.name,
+			notes: input.notes ?? null,
+			favorite: false,
+			reprompt: 0,
+			fields: input.owner ? [{
+				name: FIELD.owner,
+				value: input.owner,
+				type: 0
+			}] : [],
+			login: {
+				username: input.username ?? null,
+				password: input.password,
+				totp: null,
+				uris: input.url ? [{
+					match: null,
+					uri: input.url
+				}] : []
+			}
+		};
+		return parseItem(await this.json(["create", "item"], encode(item)));
+	}
+	/** Saves `raw`, which must still be a login or secure note of the organization. */
+	async updateItem(raw) {
+		const org = await this.organization();
+		if (!this.shareable(raw, org)) throw new CredsError(`"${raw.name}" is not a login or secure note of the ${org.name} organization; creds will not change it.`);
+		return parseItem(await this.json([
+			"edit",
+			"item",
+			raw.id
+		], encode(raw)));
+	}
+	/** The Send, if this account owns one with that id. Others' Sends are invisible to it. */
+	async getSend(id) {
+		const result = await this.run([
+			"send",
+			"get",
+			id
+		]);
+		if (result.code !== 0) {
+			if (/not found/i.test(result.stderr)) return void 0;
+			throw new CredsError(`bw send get failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+		}
+		try {
+			const send = JSON.parse(result.stdout);
+			registerSecret(send.text?.text);
+			return send;
+		} catch {
+			throw new CredsError("bw send get printed something that is not JSON.");
+		}
+	}
+	/** A new email-verified text Send for `item`. */
+	async createSend(item, body, emails, now) {
+		registerSecret(body);
+		const send = {
+			object: "send",
+			name: sendName(item),
+			notes: sendNotes(item),
+			type: 0,
+			text: {
+				text: body,
+				hidden: true
+			},
+			file: null,
+			maxAccessCount: null,
+			deletionDate: deletionDate(now),
+			expirationDate: null,
+			password: null,
+			emails: [...emails],
+			disabled: false,
+			hideEmail: false
+		};
+		return this.json(["send", "create"], encode(send));
+	}
+	/**
+	* Extends `existing` in place, so its link never changes, and brings its
+	* body and recipients up to date with the item.
+	*/
+	async editSend(existing, item, body, emails, now) {
+		registerSecret(body);
+		const send = {
+			...existing,
+			name: sendName(item),
+			notes: sendNotes(item),
+			text: {
+				text: body,
+				hidden: true
+			},
+			deletionDate: deletionDate(now),
+			expirationDate: null,
+			maxAccessCount: null,
+			password: null,
+			emails: [...emails],
+			disabled: false,
+			hideEmail: false
+		};
+		return this.json(["send", "edit"], encode(send));
+	}
+};
+function sendName(item) {
+	return `DevDogs: ${item.name}`;
+}
+/** Private to the sender: how to find the item this Send came from. */
+function sendNotes(item) {
+	return `Made by backstage creds from the ${ORGANIZATION_NAME} item "${item.name}" (${item.id}).`;
+}
+function deletionDate(now) {
+	return new Date(now.getTime() + 2592e6).toISOString();
+}
+//#endregion
+//#region src/creds/clipboard.ts
+/**
+* Puts a Send link on the clipboard. Only ever a link: the one thing `creds`
+* hands the officer to paste into a message.
+*
+* Best effort. No clipboard tool is a missing convenience, not a failure, and
+* the link is printed anyway.
+*/
+function candidates() {
+	if (process.platform === "darwin") return [["pbcopy", []]];
+	if (process.platform === "win32") return [["clip", []]];
+	return [
+		...process.env.WSL_DISTRO_NAME ? [["clip.exe", []]] : [],
+		["wl-copy", []],
+		["xclip", ["-selection", "clipboard"]],
+		["xsel", ["--clipboard", "--input"]]
+	];
+}
+function tryCopy(command, args, text) {
+	return new Promise((resolve) => {
+		const child = spawn(command, args, {
+			stdio: [
+				"pipe",
+				"ignore",
+				"ignore"
+			],
+			shell: false
+		});
+		child.on("error", () => resolve(false));
+		child.on("close", (code) => resolve(code === 0));
+		child.stdin.on("error", () => void 0);
+		child.stdin.end(text);
+	});
+}
+async function copyLink(link) {
+	for (const [command, args] of candidates()) if (await tryCopy(command, args, link)) return true;
+	return false;
+}
+//#endregion
+//#region src/creds/roster.ts
+/**
+* The officer roster: who a shared login may be sent to.
+*
+* Read live from production every run, never cached and never committed: the
+* club's roles change at elections and mid-semester handoffs, and a stale list
+* is how a Send ends up with somebody who has left. An officer is anyone
+* holding a role other than the default `Member` one, addressed by their UGA
+* MyID email, the address Bitwarden verifies before it opens a Send.
+*
+* Picking is by person or by role, and choosing a role chooses everyone in
+* it. An email that is not on the roster is refused unless `--allow-email` is
+* passed, which is for the rare account shared outside the officer team.
+*/
+/**
+* Everyone holding a non-default role, one row per person.
+*
+* The UGA address comes from the profile first: an officer may sign in with a
+* personal address, and the seeds record the MyID one as `ugaEmail`. The
+* sign-in address is the fallback, used only when it is itself a UGA one.
+*/
+const ROSTER_QUERY = `
+select
+  ur."userId" as "userId",
+  coalesce(
+    nullif(p."preferredName", ''),
+    nullif(concat_ws(' ', p."legalFirstName", p."legalLastName"), '')
+  ) as "name",
+  p."ugaEmail" as "ugaEmail",
+  u."email" as "authEmail",
+  array_agg(r."title" order by r."rank" nulls last, r."title") as "roles",
+  array_agg(r."rank" order by r."rank" nulls last, r."title") as "ranks"
+from "platform"."userRoles" ur
+join "platform"."roles" r on r."id" = ur."roleId"
+join "auth"."users" u on u."id" = ur."userId"
+left join "platform"."profile" p on p."userId" = ur."userId"
+where r."roleType" <> 'default'
+group by ur."userId", p."preferredName", p."legalFirstName", p."legalLastName", p."ugaEmail", u."email"
+`;
+function isUgaEmail(email) {
+	return /@uga\.edu$/i.test(email);
+}
+/**
+* Builds the roster from query rows. People with no UGA address cannot be
+* sent to (Bitwarden would verify the wrong inbox), so they are set aside
+* and named in `skipped` for the caller to mention.
+*/
+function rosterFromRows(rows) {
+	const officers = [];
+	const skipped = [];
+	const rank = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const email = [row.ugaEmail, row.authEmail].map((e) => e?.trim().toLowerCase()).find((e) => !!e && isUgaEmail(e));
+		const name = [row.name?.trim(), row.authEmail].find((v) => !!v) ?? row.userId;
+		if (!email) {
+			skipped.push(name);
+			continue;
+		}
+		officers.push({
+			name,
+			email,
+			roles: [...row.roles]
+		});
+		row.roles.forEach((title, i) => {
+			const r = row.ranks[i] ?? Number.MAX_SAFE_INTEGER;
+			rank.set(title, Math.min(rank.get(title) ?? r, r));
+		});
+	}
+	officers.sort((a, b) => a.name.localeCompare(b.name));
+	return {
+		roster: {
+			officers,
+			roles: [...rank.keys()].sort((a, b) => rank.get(a) - rank.get(b) || a.localeCompare(b)).map((title) => ({
+				title,
+				emails: officers.filter((o) => o.roles.includes(title)).map((o) => o.email)
+			}))
+		},
+		skipped
+	};
+}
+async function loadRoster(query) {
+	return rosterFromRows(await query());
+}
+/**
+* The role a typed name means: an exact title, else the one title it is a
+* prefix of, case-insensitively (`devops` is `DevOps Director`). Ambiguous or
+* unknown names throw, listing what there is.
+*/
+function findRole(roster, typed) {
+	const needle = typed.trim().toLowerCase();
+	const exact = roster.roles.find((r) => r.title.toLowerCase() === needle);
+	if (exact) return exact;
+	const prefixed = roster.roles.filter((r) => r.title.toLowerCase().startsWith(needle));
+	if (prefixed.length === 1) return prefixed[0];
+	const titles = roster.roles.map((r) => r.title).join(", ");
+	throw new CredsError(prefixed.length === 0 ? `No officer role called "${typed}". Roles: ${titles}.` : `"${typed}" could be ${prefixed.map((r) => r.title).join(" or ")}.`);
+}
+/** Everyone in the named roles, once each, in roster order. */
+function emailsForRoles(roster, typed) {
+	const wanted = new Set(typed.flatMap((t) => findRole(roster, t).emails));
+	return roster.officers.map((o) => o.email).filter((e) => wanted.has(e));
+}
+/**
+* Splits `emails` into the ones on the roster and the ones that are not.
+* With `allowEmail`, nothing is refused; addresses are lowercased either way,
+* because Bitwarden compares them and a capital letter is a different person
+* to a string comparison.
+*/
+function checkRecipients(emails, roster, allowEmail) {
+	const known = new Set(roster.officers.map((o) => o.email));
+	const accepted = [];
+	const refused = [];
+	for (const raw of emails) {
+		const email = raw.trim().toLowerCase();
+		if (!email || accepted.includes(email)) continue;
+		if (allowEmail || known.has(email)) accepted.push(email);
+		else refused.push(email);
+	}
+	return {
+		accepted,
+		refused
+	};
+}
+/** "Name <email>" for an address on the roster, the bare address otherwise. */
+function describeRecipient(roster, email) {
+	const officer = roster?.officers.find((o) => o.email === email);
+	return officer ? `${officer.name} <${email}>` : email;
+}
+/**
+* The production project in Secrets Manager. The same name the target table in
+* `@devdogsuga/env` gives it, spelled out here because `creds` runs with no
+* checkout, where that package is not installed.
+*/
+const PRODUCTION_PROJECT = "production";
+/** `--db-url`, else the checkout's `.env.production`, else Secrets Manager. */
+async function resolveRosterDbUrl(sources = {}) {
+	const url = nonEmpty(sources.explicit) ?? await (sources.fromCheckout ?? readCheckoutDbUrl)() ?? await (sources.fromSecretsManager ?? readSecretsManagerDbUrl)();
+	registerSecret(url);
+	if (!url) throw new CredsError("Could not find the production DB_URL to read the officer roster. Pass --db-url, or run `backstage env pull --target production` in a checkout.");
+	return url;
+}
+async function readCheckoutDbUrl() {
+	const root = discoverRepoRoot();
+	if (!root) return void 0;
+	try {
+		const text = await readFile(resolve(root, ".env.production"), "utf8");
+		return nonEmpty(EnvDocument.parse(text).get("DB_URL"));
+	} catch {
+		return;
+	}
+}
+async function readSecretsManagerDbUrl() {
+	const { listSecrets, projectIdFor } = await import("./client-DzXQHd58.js");
+	const secrets = await listSecrets(await projectIdFor(PRODUCTION_PROJECT));
+	return nonEmpty(secrets.find((s) => s.key === "DB_URL")?.value);
+}
+/** {@link ROSTER_QUERY} against `url`, on one short-lived connection. */
+function rosterQueryFor(url) {
+	return async () => {
+		const sql = postgres(url, {
+			max: 1,
+			prepare: false,
+			connect_timeout: 15
+		});
+		try {
+			return (await sql.unsafe(ROSTER_QUERY)).map((row) => ({
+				userId: String(row.userId),
+				name: row.name ?? null,
+				ugaEmail: row.ugaEmail ?? null,
+				authEmail: row.authEmail ?? null,
+				roles: row.roles,
+				ranks: row.ranks
+			}));
+		} catch (err) {
+			throw new CredsError(`Could not read the officer roster from production: ${err.code ?? "connection failed"}.`);
+		} finally {
+			await sql.end({ timeout: 5 });
+		}
+	};
+}
+const LINEAR_VAULT_ITEM = "DevDogs Linear API key (backstage)";
+const LINEAR_API = "https://api.linear.app/graphql";
+function cell(text) {
+	return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+/** The document's markdown. Pure: `now` decides the statuses. */
+function renderReport(items, now, roster) {
+	const lines = [
+		"> Generated by `backstage creds` from the DevDogs Bitwarden organization: every item shared as a Send. Manual edits are overwritten on the next run; change the item's fields in Bitwarden, or run `backstage creds send`.",
+		"",
+		`Last generated ${now.toISOString().slice(0, 16).replace("T", " ")} UTC. Sends are deleted 30 days after they were last renewed; **Expires Soon** means within 7 days, so run \`backstage creds renew\`.`,
+		""
+	];
+	const shared = items.filter((i) => i.recipients.length > 0 || i.send !== void 0);
+	if (shared.length === 0) {
+		lines.push("Nothing has been shared yet.");
+		return `${lines.join("\n")}\n`;
+	}
+	lines.push("| Credential | Account | Recipients | Owner | Status | Expires | Send |", "| --- | --- | --- | --- | --- | --- | --- |");
+	for (const item of shared) {
+		const recipients = item.recipients.length > 0 ? item.recipients.map((e) => describeRecipient(roster, e)).join(", ") : "—";
+		const link = item.send?.link ? `[Open](${item.send.link})` : "—";
+		lines.push(`| ${[
+			cell(item.name),
+			cell(item.username ?? "—"),
+			cell(recipients),
+			cell(item.owner ?? "—"),
+			sendStatus(item, now),
+			isoDay(item.send?.expires),
+			link
+		].join(" | ")} |`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/**
+* `--linear-token`, then `LINEAR_API_KEY`, then the vault item, then a prompt.
+* Never saved anywhere: the vault is where it lives.
+*/
+async function resolveLinearToken(sources) {
+	const token = nonEmpty(sources.explicit) ?? nonEmpty(sources.env) ?? await (sources.fromVault ?? readLinearTokenFromVault)() ?? await (sources.prompt ?? promptForLinearToken)();
+	if (!token) throw new CredsError(`No Linear API key. Set LINEAR_API_KEY, or store one in your vault as "${LINEAR_VAULT_ITEM}".`);
+	registerSecret(token);
+	return token;
+}
+function readLinearTokenFromVault() {
+	return readPasswordFromVault(LINEAR_VAULT_ITEM, "the Linear API key", "read the Linear API key", "LINEAR_API_KEY");
+}
+async function promptForLinearToken() {
+	if (!process.stdin.isTTY) return void 0;
+	const value = unwrap(await password({ message: "Linear API key? (Settings → Security & access → API keys)" }));
+	return nonEmpty(value.trim());
+}
+/** Replaces the document's content. Returns its URL. */
+async function writeReport(token, documentId, content, fetchImpl = fetch) {
+	let response;
+	try {
+		response = await fetchImpl(LINEAR_API, {
+			method: "POST",
+			headers: {
+				Authorization: token,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				query: "mutation($id: String!, $input: DocumentUpdateInput!) { documentUpdate(id: $id, input: $input) { success document { url } } }",
+				variables: {
+					id: documentId,
+					input: { content }
+				}
+			})
+		});
+	} catch (err) {
+		throw new CredsError(`Could not reach Linear: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const payload = await response.json().catch(() => ({}));
+	const result = payload.data?.documentUpdate;
+	if (!response.ok || !result?.success) throw new CredsError(`Linear refused the Shared Accounts update: ${payload.errors?.map((e) => e.message).join("; ") ?? `HTTP ${response.status}`}`);
+	return result.document?.url ?? documentId;
+}
+//#endregion
+//#region src/creds/commands.ts
+/**
+* `backstage creds <send|add|renew|list|report>`: the club's shared logins,
+* shared as Bitwarden Sends that only the officers they name can open.
+*
+*   send    pick shared accounts and officers; create or update one Send each
+*   add     save a new login to the DevDogs organization, then send it
+*   renew   push every Send's deletion 30 days out and re-sync its recipients
+*   list    what is shared with whom, until when
+*   report  regenerate the Shared Accounts Linear document
+*
+* Bare `creds` at a terminal opens this group's menu.
+*
+* ## Where things live
+*
+* The values live only in the DevDogs Bitwarden organization: any login or
+* secure note in it can be shared. Each item's custom fields record its recipients and its
+* Send (`item.ts`); the Linear document is generated from them (`report.ts`);
+* the roster of who may receive one is read live from production
+* (`roster.ts`).
+*
+* ## One Send per account
+*
+* Restricted by email verification to the item's recipients, deleted 30 days
+* out, extended in place so the link never changes. Revoking someone is
+* removing their address. A Send belongs to the officer who made it, so when
+* another officer renews it they get a new one (and a new link) under their
+* own account, and the item records that.
+*
+* ## Secrets
+*
+* No secret value reaches stdout, stderr, the failure log, Sentry, an error
+* message or argv. The preview masks the password as a fixed `••••••••` and
+* never shows the notes; values go to `bw` on stdin; errors are scrubbed
+* (`secrets.ts`); the clipboard only ever gets a link. `commands.test.ts`
+* runs every path with a sentinel password and looks for it everywhere.
+*/
+const SUBCOMMANDS = [
+	"send",
+	"add",
+	"renew",
+	"list",
+	"report"
+];
+function parse(argv) {
+	const [sub, ...rest] = argv;
+	if (!sub || !SUBCOMMANDS.includes(sub)) throw new UsageError(sub ? `Unknown creds command "${sub}". Try ${SUBCOMMANDS.join(", ")}.` : `Name what to do: ${SUBCOMMANDS.join(", ")}.`);
+	try {
+		const { values } = parseArgs({
+			args: rest,
+			options: {
+				item: {
+					type: "string",
+					multiple: true
+				},
+				to: { type: "string" },
+				role: { type: "string" },
+				"allow-email": { type: "boolean" },
+				"db-url": { type: "string" },
+				"linear-token": { type: "string" },
+				"no-report": { type: "boolean" },
+				yes: { type: "boolean" },
+				json: { type: "boolean" },
+				name: { type: "string" },
+				url: { type: "string" },
+				username: { type: "string" },
+				owner: { type: "string" },
+				collection: { type: "string" },
+				"password-stdin": { type: "boolean" },
+				document: { type: "string" },
+				"dry-run": { type: "boolean" }
+			},
+			allowPositionals: false,
+			strict: true
+		});
+		if (values["db-url"]) registerSecret(values["db-url"]);
+		if (values["linear-token"]) registerSecret(values["linear-token"]);
+		return {
+			sub,
+			values
+		};
+	} catch (err) {
+		throw new UsageError(scrub(errorMessage(err)));
+	}
+}
+/** Progress for a person; plain stderr lines when nobody is watching a terminal. */
+function say(message, level = "info") {
+	if (isNonInteractive()) process.stderr.write(`${message}\n`);
+	else log[level](message);
+}
+function interactive() {
+	return !isNonInteractive() && process.stdin.isTTY === true;
+}
+async function confirmOrRefuse(message, yes) {
+	if (yes) return true;
+	if (!interactive()) throw new UsageError(`${message} Pass --yes to answer yes without a terminal.`);
+	return unwrap(await confirm({
+		message,
+		initialValue: true
+	}));
+}
+function findItem(items, typed) {
+	const needle = typed.trim().toLowerCase();
+	const match = items.find((i) => i.id === typed.trim()) ?? items.find((i) => i.name.toLowerCase() === needle);
+	if (!match) throw new UsageError(`No shared account called "${typed}". There are: ${items.map((i) => i.name).join(", ") || "none yet (try creds add)"}.`);
+	return match;
+}
+async function pickItems(items, typed, message) {
+	if (typed && typed.length > 0) return typed.map((t) => findItem(items, t));
+	if (items.length === 0) throw new UsageError("The DevDogs organization has no logins you can see. Add one with `backstage creds add`.");
+	if (!interactive()) throw new UsageError("Name the accounts with --item <name>.");
+	const ids = unwrap(await multiselect({
+		message,
+		options: items.map((i) => ({
+			value: i.id,
+			label: i.name,
+			hint: i.recipients.length > 0 ? `${i.recipients.length} recipient${i.recipients.length === 1 ? "" : "s"}` : "not shared yet"
+		})),
+		required: true
+	}));
+	return items.filter((i) => ids.includes(i.id));
+}
+let rosterCache;
+async function roster(values, deps) {
+	rosterCache ??= (async () => {
+		const { roster: loaded, skipped } = await loadRoster(deps.rosterQuery ?? rosterQueryFor(await resolveRosterDbUrl({ explicit: values["db-url"] })));
+		if (skipped.length > 0) say(`Left off the roster for having no UGA address on record: ${skipped.join(", ")}.`, "warn");
+		return loaded;
+	})();
+	try {
+		return await rosterCache;
+	} catch (err) {
+		rosterCache = void 0;
+		throw err;
+	}
+}
+/**
+* The recipients for one item: `--to` and `--role` when given, else a
+* multiselect at a terminal (people and roles, the current list preselected),
+* else the item's current list. Addresses off the roster need --allow-email,
+* except ones the item already has.
+*/
+async function pickRecipients(item, values, deps) {
+	const typed = splitEmails(values.to);
+	const roles = (values.role ?? "").split(",").map((r) => r.trim()).filter(Boolean);
+	let chosen;
+	if (typed.length > 0 || roles.length > 0) {
+		const r = roles.length > 0 ? await roster(values, deps) : void 0;
+		chosen = [...typed, ...r ? emailsForRoles(r, roles) : []];
+	} else if (interactive()) {
+		const r = await roster(values, deps);
+		const offRoster = item.recipients.filter((e) => !r.officers.some((o) => o.email === e));
+		chosen = unwrap(await multiselect({
+			message: `Who should be able to open ${item.name}? (roles select everyone in them)`,
+			options: [
+				...r.roles.map((role) => ({
+					value: `role:${role.title}`,
+					label: `Everyone: ${role.title}`,
+					hint: `${role.emails.length}`
+				})),
+				...r.officers.map((o) => ({
+					value: `email:${o.email}`,
+					label: o.name,
+					hint: `${o.email} · ${o.roles.join(", ")}`
+				})),
+				...offRoster.map((e) => ({
+					value: `email:${e}`,
+					label: e,
+					hint: "not on the officer roster"
+				}))
+			],
+			initialValues: item.recipients.map((e) => `email:${e}`),
+			required: true
+		})).flatMap((value) => value.startsWith("role:") ? emailsForRoles(r, [value.slice(5)]) : [value.slice(6)]);
+		if (values["allow-email"]) {
+			const extra = unwrap(await text({
+				message: "Anyone else? (comma-separated addresses, blank for nobody)",
+				placeholder: ""
+			}));
+			chosen.push(...splitEmails(extra));
+		}
+	} else chosen = item.recipients;
+	const unique = [...new Set(chosen.map((e) => e.toLowerCase()))];
+	const added = unique.filter((e) => !item.recipients.includes(e));
+	if (added.length > 0 && !values["allow-email"]) {
+		const { refused } = checkRecipients(added, await roster(values, deps), false);
+		if (refused.length > 0) throw new UsageError(`Not on the officer roster: ${refused.join(", ")}. Check the address, or pass --allow-email to share outside the officer team.`);
+	}
+	return unique;
+}
+async function plan(vault, item, recipients) {
+	if (recipients.length === 0) throw new CredsError(`${item.name} has no recipients. A Send needs at least one address.`);
+	return {
+		item,
+		recipients,
+		existing: item.send ? await vault.getSend(item.send.id) : void 0
+	};
+}
+/** The confirmation text for a plan: the masked body, the recipients, and what happens to the link. */
+function describePlan(p, rosterForNames) {
+	const added = p.recipients.filter((e) => !p.item.recipients.includes(e));
+	const removed = p.item.recipients.filter((e) => !p.recipients.includes(e));
+	const lines = [
+		previewBody(p.item),
+		"",
+		"Recipients (Bitwarden verifies each address before showing anything):",
+		...p.recipients.map((e) => `  ${describeRecipient(rosterForNames, e)}`)
+	];
+	if (added.length > 0) lines.push(`Adding: ${added.join(", ")}`);
+	if (removed.length > 0) lines.push(`Removing: ${removed.join(", ")}`);
+	if (p.existing) lines.push("", "Updates the existing Send in place: the link stays the same.");
+	else if (p.item.send) lines.push("", `The recorded Send belongs to ${p.item.send.account ?? "another account"} or was deleted, so this makes a new one under your account. The link changes; the Linear document carries the new one.`);
+	else lines.push("", "Makes a new Send.");
+	return lines.join("\n");
+}
+async function apply(vault, p, account, now) {
+	const body = sendBody(p.item);
+	const send = p.existing ? await vault.editSend(p.existing, p.item, body, p.recipients, now) : await vault.createSend(p.item, body, p.recipients, now);
+	return vault.updateItem(withFields(p.item.raw, {
+		recipients: p.recipients.join(", "),
+		sendId: send.id,
+		sendLink: send.accessUrl,
+		sendExpires: new Date(send.deletionDate).toISOString(),
+		sendAccount: account
+	}));
+}
+async function sendAll(vault, plans, values, deps, rosterForNames) {
+	const now = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+	const account = await vault.account();
+	const done = [];
+	for (const p of plans) {
+		if (interactive()) note(describePlan(p, rosterForNames), p.item.name);
+		else process.stderr.write(`${p.item.name}\n${describePlan(p, rosterForNames)}\n\n`);
+		if (!await confirmOrRefuse(`Share ${p.item.name} with ${p.recipients.length} recipient${p.recipients.length === 1 ? "" : "s"}?`, values.yes === true)) {
+			say(`Skipped ${p.item.name}.`, "warn");
+			continue;
+		}
+		const saved = await apply(vault, p, account, now);
+		done.push(saved);
+		say(`${saved.name}: ${saved.send?.link ?? "(no link)"} (until ${isoDay(saved.send?.expires)})`, "success");
+	}
+	if (done.length === 1 && done[0].send?.link) {
+		if (await (deps.copy ?? copyLink)(done[0].send.link)) say("Copied the link to your clipboard.");
+	}
+	return done;
+}
+async function report(vault, values, deps, rosterForNames) {
+	const token = await resolveLinearToken({
+		explicit: values["linear-token"],
+		env: process.env.LINEAR_API_KEY
+	});
+	const items = await vault.listItems();
+	const now = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+	say(`Updated the Shared Accounts document: ${await writeReport(token, values.document ?? "209799db-5981-4796-a41e-2bb433020d06", renderReport(items, now, rosterForNames), deps.fetch)}`, "success");
+}
+/** The report after a change. A failure here leaves the Sends done, so it warns rather than fails. */
+async function reportAfter(vault, values, deps, rosterForNames) {
+	if (values["no-report"]) return;
+	try {
+		await report(vault, values, deps, rosterForNames);
+	} catch (err) {
+		say(`The Sends are done, but the Linear document was not updated: ${scrub(errorMessage(err))} Run \`backstage creds report\` to retry.`, "warn");
+	}
+}
+async function runSend(vault, values, deps) {
+	await sendItems(vault, await pickItems(await vault.listItems(), values.item, "Which shared accounts?"), values, deps);
+}
+async function sendItems(vault, items, values, deps) {
+	const plans = [];
+	for (const item of items) plans.push(await plan(vault, item, await pickRecipients(item, values, deps)));
+	const names = rosterCache ? await rosterCache.catch(() => void 0) : void 0;
+	if ((await sendAll(vault, plans, values, deps, names)).length > 0) await reportAfter(vault, values, deps, names);
+}
+async function readPassword(values, deps) {
+	if (values["password-stdin"]) {
+		const value = (await (deps.readStdin ?? readAllStdin)()).replace(/\r?\n$/, "");
+		if (!value) throw new UsageError("--password-stdin read nothing.");
+		return value;
+	}
+	if (!interactive()) throw new UsageError("Pass the password on stdin with --password-stdin; it never goes in argv.");
+	return unwrap(await password({
+		message: "Password? (hidden; never printed)",
+		validate: (v) => v ? void 0 : "A shared login needs a password."
+	}));
+}
+async function readAllStdin() {
+	let data = "";
+	for await (const chunk of process.stdin) data += String(chunk);
+	return data;
+}
+async function ask(given, message, required) {
+	if (given !== void 0) return given.trim() || void 0;
+	if (!interactive()) {
+		if (required) throw new UsageError(`Missing ${message}`);
+		return;
+	}
+	return unwrap(await text({
+		message,
+		validate: required ? (v) => v?.trim() ? void 0 : "Required." : void 0
+	}))?.trim() || void 0;
+}
+/** `--collection`, the only one there is, or a choice. Every organization item needs one. */
+async function pickCollection(vault, typed) {
+	const all = await vault.collections();
+	if (typed !== void 0) {
+		const needle = typed.trim().toLowerCase();
+		const match = all.find((c) => c.name.toLowerCase() === needle);
+		if (!match) throw new UsageError(`No collection called "${typed}" that you can see. There are: ${all.map((c) => c.name).join(", ") || "none"}.`);
+		return match;
+	}
+	if (all.length === 0) throw new UsageError("You cannot see any collection in the DevDogs organization to save to. Ask an organization admin for access to one.");
+	if (all.length === 1) return all[0];
+	if (!interactive()) throw new UsageError(`Name the collection with --collection: ${all.map((c) => c.name).join(", ")}.`);
+	const id = unwrap(await select({
+		message: "Which collection?",
+		options: all.map((c) => ({
+			value: c.id,
+			label: c.name
+		}))
+	}));
+	return all.find((c) => c.id === id);
+}
+async function runAdd(vault, values, deps) {
+	const existing = await vault.listItems();
+	const name = await ask(values.name, "Name? (e.g. Instagram)", true);
+	if (existing.some((i) => i.name.toLowerCase() === name.toLowerCase())) throw new UsageError(`"${name}" is already in the organization. Use \`backstage creds send --item "${name}"\`.`);
+	const url = await ask(values.url, "Login page URL? (optional)", false);
+	const username = await ask(values.username, "Username or email? (optional)", false);
+	const password = await readPassword(values, deps);
+	registerSecret(password);
+	const notes = interactive() ? await ask(void 0, "Notes for recipients? (optional, never printed)", false) : void 0;
+	const owner = await ask(values.owner, "Owner? (the officer responsible)", false);
+	const collection = await pickCollection(vault, values.collection);
+	const item = await vault.createLogin({
+		collection,
+		name,
+		url,
+		username,
+		password,
+		notes,
+		owner
+	});
+	say(`Saved ${item.name} to the ${collection.name} collection.`, "success");
+	await sendItems(vault, [item], values, deps);
+}
+async function runRenew(vault, values, deps) {
+	const now = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+	const all = await vault.listItems();
+	const ready = (values.item && values.item.length > 0 ? values.item.map((t) => findItem(all, t)) : all.filter((i) => i.send !== void 0 || i.recipients.length > 0)).filter((i) => {
+		if (i.recipients.length > 0) return true;
+		say(`${i.name} has no recipients; share it with \`creds send\` first.`, "warn");
+		return false;
+	});
+	const early = ready.filter((i) => (daysLeft(i, now) ?? 0) > 7);
+	let renew = ready;
+	if (early.length > 0) {
+		if (!await confirmOrRefuse(`More than 7 days left on: ${early.map((i) => `${i.name} (${daysLeft(i, now)} days left)`).join(", ")}. Renew ${early.length === 1 ? "it" : "them"} anyway?`, values.yes === true)) renew = ready.filter((i) => !early.includes(i));
+	}
+	if (renew.length === 0) {
+		say("Nothing to renew.");
+		return;
+	}
+	const plans = [];
+	for (const item of renew) plans.push(await plan(vault, item, item.recipients));
+	if ((await sendAll(vault, plans, {
+		...values,
+		yes: true
+	}, deps, void 0)).length > 0) await reportAfter(vault, values, deps, void 0);
+}
+async function runList(vault, values, deps) {
+	const now = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+	const rows = (await vault.listItems()).map((i) => ({
+		name: i.name,
+		account: i.username ?? null,
+		url: i.url ?? null,
+		recipients: i.recipients,
+		owner: i.owner ?? null,
+		status: sendStatus(i, now),
+		expires: i.send?.expires?.toISOString() ?? null,
+		sendLink: i.send?.link ?? null
+	}));
+	if (values.json) {
+		process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+		return;
+	}
+	if (rows.length === 0) {
+		process.stdout.write("No shared accounts yet. Add one with `backstage creds add`.\n");
+		return;
+	}
+	for (const r of rows) process.stdout.write(`${r.name}${r.account ? ` (${r.account})` : ""}: ${r.status}, until ${isoDay(r.expires ? new Date(r.expires) : void 0)}\n  owner: ${r.owner ?? "—"}\n  recipients: ${r.recipients.join(", ") || "—"}\n`);
+}
+async function runCreds(argv, deps = {}) {
+	try {
+		const { sub, values } = parse(argv);
+		const vault = await (deps.vault ?? connectSharedVault)();
+		if (sub === "send") await runSend(vault, values, deps);
+		else if (sub === "add") await runAdd(vault, values, deps);
+		else if (sub === "renew") await runRenew(vault, values, deps);
+		else if (sub === "list") await runList(vault, values, deps);
+		else await report(vault, values, deps, void 0);
+	} catch (err) {
+		process.exitCode = 1;
+		if (err instanceof UsageError || err instanceof CredsError) {
+			explain(scrub(err.message), "");
+			return;
+		}
+		const safe = new Error(scrub(errorMessage(err)));
+		safe.stack = scrub(err?.stack ?? safe.message);
+		explainError("creds failed.", safe);
+	}
+}
+const handleCreds = async (rest) => {
+	await runCreds(rest);
+	return process.exitCode ? null : DONE;
+};
+//#endregion
+export { handleCreds };