@devdogsuga/backstage 0.1.3 → 0.1.4

package/dist/vault-C8LYJFOQ.js

@@ -0,0 +1,563 @@
+import { o as unwrap } from "./ui-CdKo8mLw.js";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { confirm, log, spinner } from "@clack/prompts";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+//#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
+//#region src/bws/bw.ts
+/**
+* Where the bundled Bitwarden CLI (`bw`) is, for the vault code that signs in
+* and reads the Secrets Manager token (`vault.ts`).
+*
+* There is no `bw` command of ours: `env` runs `bw login` and `bw unlock`
+* itself when it needs the token. The binary is still resolved from
+* `@bitwarden/cli`, never looked up on PATH. A dependency's bin is only linked
+* into the `node_modules/.bin` of the package that depends on it, so under
+* `pnpm dlx` nothing puts `bw` on PATH and a bare `spawn("bw")` is ENOENT.
+*/
+/**
+* The `[command, args]` pair that runs the bundled Bitwarden CLI.
+*
+* Runs `build/bw.js` under this Node rather than through a shim, so it works
+* the same wherever backstage is installed. Falls back to `bw` on PATH when the
+* package cannot be resolved, which keeps a missing install surfacing as the
+* ENOENT every caller already handles.
+*/
+function bwCommand(args) {
+	try {
+		const require_ = createRequire(import.meta.url);
+		const pkgPath = require_.resolve("@bitwarden/cli/package.json");
+		const pkg = require_(pkgPath);
+		return [process.execPath, [join(dirname(pkgPath), pkg.bin.bw), ...args]];
+	} catch {
+		return ["bw", args];
+	}
+}
+//#endregion
+//#region src/bws/vault.ts
+/**
+* The Bitwarden **Password Manager** vault, via the `bw` CLI.
+*
+* A different product from Secrets Manager and a different CLI, which is the
+* point: `bws` has no user authentication at all, so the access token it needs
+* has to be held somewhere a person can log in to. That somewhere is the
+* Password Manager vault, and this module reads it back rather than making
+* somebody paste a token every session.
+*
+* Everything here degrades to `undefined`. A missing `bw`, a locked vault, a
+* declined unlock, a missing item: none of them are errors, because each has a
+* good fallback, which is to ask. Throwing would turn a convenience into a
+* prerequisite.
+*
+* ⚠️ The token never passes through argv in either direction. Reads use
+* `bw get password <search>`, which puts only the item NAME on the command
+* line, and writes pipe base64 JSON through **stdin**, which `bw create item`
+* documents as an accepted input.
+*/
+const run = promisify(execFile);
+/**
+* The item this looks for, and creates.
+*
+* Named for what it unlocks rather than for this tool, because whoever finds it
+* in the vault six months from now needs to know what it is, not which script
+* wrote it.
+*/
+const VAULT_ITEM_NAME = "DevDogs Secrets Manager access token (admin)";
+/** `bw status`, or `unavailable` when the CLI is not installed. */
+async function vaultStatus() {
+	try {
+		const { stdout } = await run(...bwCommand(bwArgs(["status", "--response"])), { shell: false });
+		const parsed = JSON.parse(stdout);
+		const status = ("status" in parsed ? parsed.status : void 0) ?? ("data" in parsed ? parsed.data?.template?.status : void 0);
+		if (status === "unlocked") return "unlocked";
+		if (status === "locked") return "locked";
+		return "unauthenticated";
+	} catch (err) {
+		if (err.code === "ENOENT") return "unavailable";
+		return "unauthenticated";
+	}
+}
+/**
+* Offers to sign in to the vault when it is not, and does it with the bundled
+* `bw` (`bw login`, interactive). There is no `bw` command of ours to run by
+* hand any more: `env` signs in and unlocks for itself, at the moment it needs
+* the Secrets Manager token. Returns the status afterwards.
+*
+* Asks first, like the unlock below: a master-password prompt that appears
+* unannounced is shaped exactly like the thing people are told never to type
+* their master password into. Without a terminal there is nobody to sign in,
+* so the status comes back unchanged.
+*/
+async function signInIfNeeded(status, purpose) {
+	if (status !== "unauthenticated" || !process.stdin.isTTY) return status;
+	if (!unwrap(await confirm({
+		message: `You are not signed in to Bitwarden. Sign in now to ${purpose}?`,
+		initialValue: true
+	}))) return status;
+	if (await new Promise((resolve) => {
+		const child = spawn(...bwCommand(["login"]), {
+			stdio: "inherit",
+			shell: false
+		});
+		child.on("error", () => resolve(null));
+		child.on("close", (exit) => resolve(exit));
+	}) !== 0) return status;
+	return vaultStatus();
+}
+/**
+* A usable session key, unlocking if the person agrees.
+*
+* `BW_SESSION` is preferred and silent. Otherwise this ASKS before unlocking:
+* a tool that pops a master-password prompt unannounced is shaped exactly like
+* the thing people are told never to type their master password into.
+*
+* The password is typed straight into `bw`. stdin is inherited, so it never
+* passes through this process.
+*
+* The key is kept for the rest of the process once unlocked: `creds` makes a
+* dozen `bw` calls in one run, and asking for the master password before each
+* would be both tiresome and a reason to stop reading the prompt.
+*/
+let unlockedKey;
+async function session(status, purpose) {
+	if (process.env.BW_SESSION) return process.env.BW_SESSION;
+	if (unlockedKey) return unlockedKey;
+	if (status !== "locked") return void 0;
+	if (!process.stdin.isTTY) return void 0;
+	if (!unwrap(await confirm({
+		message: `Your Bitwarden vault is locked. Unlock it to ${purpose}?`,
+		initialValue: true
+	}))) return void 0;
+	unlockedKey = await new Promise((resolve) => {
+		const child = spawn(...bwCommand(["unlock", "--raw"]), {
+			stdio: [
+				"inherit",
+				"pipe",
+				"inherit"
+			],
+			shell: false
+		});
+		let out = "";
+		child.stdout.on("data", (c) => out += c.toString());
+		child.on("error", () => resolve(void 0));
+		child.on("close", (code) => resolve(code === 0 && out.trim() !== "" ? out.trim() : void 0));
+	});
+	return unlockedKey;
+}
+/**
+* A vault ready for `bw` calls, signing in and unlocking (after asking) as
+* needed, or `undefined` when it cannot be used. `key` is the session to pass
+* to {@link bwArgs}; it is absent only when `bw` itself reports the vault
+* unlocked without one.
+*
+* `purpose` finishes the questions: "Unlock it to <purpose>?".
+*/
+async function openVault(purpose) {
+	const status = await signInIfNeeded(await vaultStatus(), purpose);
+	if (status === "unavailable" || status === "unauthenticated") return;
+	const key = await session(status, purpose);
+	if (status === "locked" && !key) return void 0;
+	return { key };
+}
+/**
+* Adds the session key, and `--nointeraction` always.
+*
+* The second one is not belt-and-braces. `bw` prompts for a master password on
+* stdin whenever the vault is locked, as `bw get template item` does against a
+* locked vault, and this module runs `bw` with piped stdio, where that prompt
+* has nobody to answer it and hangs until something gives up. `--nointeraction`
+* turns that into an immediate non-zero exit, which every caller here already
+* treats as "not available, ask instead".
+*/
+function bwArgs(args, key) {
+	const withNoInteraction = [...args, "--nointeraction"];
+	return key ? [
+		...withNoInteraction,
+		"--session",
+		key
+	] : withNoInteraction;
+}
+/**
+* The stored token, or `undefined` for every reason it might not be there.
+*
+* `bw get password` takes a search term and fails when it matches more than one
+* item, which is the behaviour worth having: two items called something like
+* this means somebody should look, not that this should guess.
+*/
+async function readTokenFromVault() {
+	return readPasswordFromVault(VAULT_ITEM_NAME, "the access token", "look for the access token", "BWS_ACCESS_TOKEN");
+}
+/**
+* The password of the one vault item named `itemName`, or `undefined` for
+* every reason it might not be there. `what` names it in the spinner; `purpose`
+* finishes the sign-in and unlock questions.
+*/
+async function readPasswordFromVault(itemName, what, purpose, envVar) {
+	const status = await signInIfNeeded(await vaultStatus(), purpose);
+	if (status === "unavailable" || status === "unauthenticated") {
+		log.info(explainVault(status, envVar));
+		return;
+	}
+	const key = await session(status, purpose);
+	if (status === "locked" && !key) return void 0;
+	const s = spinner();
+	s.start("Looking in your Bitwarden vault");
+	try {
+		const { stdout } = await run(...bwCommand(bwArgs([
+			"get",
+			"password",
+			itemName,
+			"--raw"
+		], key)), { shell: false });
+		const token = stdout.trim();
+		if (token === "") {
+			s.stop("Nothing stored in the vault yet");
+			return;
+		}
+		s.stop(`Read ${what} from your vault ("${itemName}")`);
+		return token;
+	} catch {
+		s.stop("No single matching item in your vault");
+		return;
+	}
+}
+/**
+* Creates the item, with the token arriving on **stdin** as base64 JSON.
+*
+* `bw create item` documents an encoded-JSON positional AND stdin. Using stdin
+* is the difference between a live credential that is invisible and one that
+* sits in `ps` output for the length of the call.
+*/
+async function saveTokenToVault(token) {
+	const purpose = "save the access token";
+	const status = await signInIfNeeded(await vaultStatus(), purpose);
+	if (status === "unavailable" || status === "unauthenticated") return false;
+	const key = await session(status, purpose);
+	if (status === "locked" && !key) return false;
+	const item = {
+		organizationId: null,
+		collectionIds: null,
+		folderId: null,
+		type: 1,
+		name: VAULT_ITEM_NAME,
+		notes: "Bitwarden Secrets Manager access token for the `admin` machine account, read/write on preflight, staging and production.\n\nRead automatically by `backstage env`. Never put this in a .env file: it unlocks all three projects, and the tool refuses to upload it.",
+		favorite: false,
+		reprompt: 0,
+		login: {
+			username: null,
+			password: token,
+			totp: null
+		}
+	};
+	return new Promise((resolve) => {
+		const child = spawn(...bwCommand(bwArgs(["create", "item"], key)), {
+			stdio: [
+				"pipe",
+				"ignore",
+				"pipe"
+			],
+			shell: false
+		});
+		let stderr = "";
+		child.stderr.on("data", (c) => stderr += c.toString());
+		child.on("error", () => resolve(false));
+		child.on("close", (code) => {
+			if (code !== 0 && stderr.trim() !== "") log.warn(stderr.trim());
+			resolve(code === 0);
+		});
+		child.stdin.end(Buffer.from(JSON.stringify(item)).toString("base64"));
+	});
+}
+/** Why the vault could not be used, phrased as something to do about it. */
+function explainVault(status, envVar = "BWS_ACCESS_TOKEN") {
+	if (status === "unavailable") return "The `bw` CLI is not installed, so the vault could not be checked. It ships with backstage, so reinstall it.";
+	if (status === "unauthenticated") return `You are not signed in to Bitwarden, and with no terminal there is nobody to sign in. Set ${envVar} instead.`;
+}
+//#endregion
+export { readTokenFromVault as a, EnvDocument as c, readPasswordFromVault as i, bwArgs as n, saveTokenToVault as o, openVault as r, bwCommand as s, VAULT_ITEM_NAME as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devdogsuga/backstage",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Officer and production CLI for DevDogsUGA: deploys, env sync with Bitwarden and GitHub, the migration planner role, club graphics and QR codes, GitHub rulesets and settings, and the newsletter. Ships built JS; run it anywhere with `pnpm dlx @devdogsuga/backstage` (no checkout needed to start; commands that read a checkout say so).",
@@ -40,9 +40,9 @@
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "zod": "4.4.3",
+    "@devdogsuga/telemetry": "0.1.3",
     "@devdogsuga/brand": "0.1.5",
     "@devdogsuga/events": "0.1.5",
-    "@devdogsuga/telemetry": "0.1.3",
     "@devdogsuga/newsletter": "0.1.9"
   },
   "peerDependencies": {
@@ -65,8 +65,8 @@
     "tsdown": "^0.23.0",
     "vitest": "^4.1.11",
     "@devdogsuga/cli-core": "0.0.0",
-    "@devdogsuga/config": "0.1.2",
     "@devdogsuga/db": "0.1.3",
+    "@devdogsuga/config": "0.1.2",
     "@devdogsuga/env": "0.1.5"
   },
   "scripts": {