@devdogsuga/devtools 0.1.0

package/dist/bws/retry.js

@@ -0,0 +1,39 @@
+/**
+ * Retrying exactly one failure class: HTTP 429, rate limiting.
+ *
+ * A 429 is the server saying "correct request, wrong minute", the only error
+ * where trying the same thing again IS the fix. Everything else (bad token,
+ * missing project, malformed input) re-throws untouched on the first attempt,
+ * because retrying those just triples the time to the real message.
+ *
+ * Written for the Secrets Manager calls, where the minute matters: a push is
+ * ~45 sequential writes plus a login, several targets get pushed back-to-back,
+ * and Bitwarden's identity endpoint rate-limits repeated access-token logins
+ * aggressively. The login half is also fixed at the source, since the client
+ * now caches its login in a state file, so the retry is the belt on that
+ * suspender.
+ */
+import { log } from "@clack/prompts";
+export function isRateLimited(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /\b429\b|too many requests|rate.?limit/i.test(message);
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function withRateLimitRetry(op, { retries = 3, baseMs = 5_000, sleep = wait, doing }) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            if (!isRateLimited(err) || attempt >= retries)
+                throw err;
+            const ms = baseMs * 2 ** attempt;
+            // A silent 20-second stall reads as a hang, and a command that appears
+            // hung gets Ctrl-C'd, turning a wait the server asked for into a
+            // half-finished push.
+            log.warn(`Bitwarden rate-limited ${doing} (HTTP 429). Waiting ${ms / 1000}s ` +
+                `and retrying (${attempt + 1}/${retries})…`);
+            await sleep(ms);
+        }
+    }
+}

package/dist/bws/store.d.ts

@@ -0,0 +1 @@
+export declare function saveToDevEnv(key: string, value: string): Promise<void>;

package/dist/bws/store.js

@@ -0,0 +1,32 @@
+/**
+ * Saving a prompted value into the developer's own `.env`.
+ *
+ * The development file only, by construction: the path is fixed to
+ * `fileFor("development")`, so no caller can point this at a vault target's
+ * file. Those are what `env push` uploads, and the values saved here
+ * (`BWS_ACCESS_TOKEN`, `BWS_ORG_ID`) exist so they never ride a push. The
+ * token is refused there by name anyway; this keeps the write from ever being
+ * the thing that needs refusing.
+ *
+ * `EnvDocument.set` revives the commented line the rendered file already
+ * carries (never-store keys ship as `# KEY=""` with their documentation), so a
+ * saved value lands under its own doc comment rather than appended bare.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { EnvDocument } from "../env/document.js";
+import { findRepoRoot } from "../repo/root.js";
+import { loadEnv } from "../repo/peers.js";
+export async function saveToDevEnv(key, value) {
+    const { fileFor } = await loadEnv();
+    const path = resolve(findRepoRoot(), fileFor("development"));
+    let doc;
+    try {
+        doc = EnvDocument.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        doc = EnvDocument.empty();
+    }
+    doc.set(key, value);
+    await writeFile(path, doc.toString());
+}

package/dist/bws/token.d.ts

@@ -0,0 +1,31 @@
+export declare class NoAccessTokenError extends Error {
+}
+export interface TokenSources {
+    /** From `--access-token`. */
+    explicit?: string;
+    /** From `process.env.BWS_ACCESS_TOKEN`. */
+    env?: string;
+    /** `undefined` for every reason the vault might not have it. */
+    fromVault: () => Promise<string | undefined>;
+    /** `undefined` when there is nobody to ask. */
+    prompt: () => Promise<string | undefined>;
+    /** Asked only after a successful prompt. */
+    offerSave: () => Promise<boolean>;
+    save: (token: string) => Promise<void>;
+    /** Where the token came from, for the caller to report. */
+    onSource?: (source: TokenSource) => void;
+}
+export type TokenSource = "flag" | "environment" | "vault" | "prompt";
+export declare function resolveToken(sources: TokenSources): Promise<string>;
+/**
+ * A weak shape check, to turn a paste error into a sentence rather than a 401.
+ *
+ * Machine account tokens are `0.<uuid>.<secret>:<secret>`. This checks the
+ * leading version segment only, and **warns rather than refuses**: the format
+ * is Bitwarden's to change, and a tool that rejects a valid token because its
+ * prefix moved is worse than one that passes a bad token to `bws` and lets the
+ * real error surface.
+ */
+export declare function looksLikeAccessToken(value: string): boolean;
+/** The interactive half. Masked, and never echoed back. */
+export declare function promptForToken(): Promise<string | undefined>;

package/dist/bws/token.js

@@ -0,0 +1,88 @@
+/**
+ * Finding the Secrets Manager access token, in four places, in order.
+ *
+ *   1. `--access-token`   explicit, and explicit beats ambient
+ *   2. `BWS_ACCESS_TOKEN` the environment, which includes your `.env`,
+ *                         since `with-env` loads it for every command
+ *   3. the Bitwarden Password Manager vault, via the bundled `bw`
+ *   4. ask, and offer to save it to `.env` (the default) or the vault, so
+ *      this is the last time
+ *
+ * The ordering logic is separated from the four implementations because it is
+ * the part that can be wrong invisibly. A chain that silently prefers a stale
+ * environment variable over a rotated vault entry authenticates as the wrong
+ * account and reports nothing, so the order is asserted rather than assumed.
+ */
+import { log, password } from "@clack/prompts";
+import { unwrap } from "../ui.js";
+export class NoAccessTokenError extends Error {
+}
+export async function resolveToken(sources) {
+    const announce = sources.onSource ?? (() => { });
+    // Explicit beats ambient. Someone who passes the flag while an environment
+    // variable is set is overriding on purpose, and silently ignoring them would
+    // point the command at the account they were trying to avoid.
+    if (sources.explicit) {
+        announce("flag");
+        return sources.explicit;
+    }
+    if (sources.env) {
+        announce("environment");
+        return sources.env;
+    }
+    const stored = await sources.fromVault();
+    if (stored) {
+        announce("vault");
+        return stored;
+    }
+    const typed = await sources.prompt();
+    if (!typed) {
+        throw new NoAccessTokenError("No access token. Put BWS_ACCESS_TOKEN in your .env (an interactive " +
+            "run offers to do this for you), pass --access-token, or store one " +
+            "in your Bitwarden vault. See docs/toolkit/guides/env/commands.md.");
+    }
+    announce("prompt");
+    // Offered only for a token that was just typed. Saving one that came from a
+    // flag or the environment would copy a credential into a vault nobody asked
+    // to put it in.
+    if (await sources.offerSave()) {
+        // A failed vault write must not lose the token. Somebody just pasted a live
+        // credential; making them do it again because a write failed is the worst
+        // moment to be strict, and the command itself is unaffected.
+        try {
+            await sources.save(typed);
+        }
+        catch (err) {
+            log.warn(`Could not save to your vault: ${err instanceof Error ? err.message : String(err)}. ` +
+                "Continuing with the token you typed.");
+        }
+    }
+    return typed;
+}
+/**
+ * A weak shape check, to turn a paste error into a sentence rather than a 401.
+ *
+ * Machine account tokens are `0.<uuid>.<secret>:<secret>`. This checks the
+ * leading version segment only, and **warns rather than refuses**: the format
+ * is Bitwarden's to change, and a tool that rejects a valid token because its
+ * prefix moved is worse than one that passes a bad token to `bws` and lets the
+ * real error surface.
+ */
+export function looksLikeAccessToken(value) {
+    return /^\d+\.[0-9a-f-]{36}\./i.test(value.trim());
+}
+/** The interactive half. Masked, and never echoed back. */
+export async function promptForToken() {
+    if (!process.stdin.isTTY)
+        return undefined;
+    const typed = unwrap(await password({
+        message: "Paste the Secrets Manager access token for the `admin` account",
+        mask: "•",
+        validate: (v) => (v ?? "").trim() === "" ? "An access token is required." : undefined,
+    })).trim();
+    if (!looksLikeAccessToken(typed)) {
+        log.warn("That does not look like a machine account access token (they start " +
+            "`0.<uuid>.`). Continuing anyway — if it is wrong, Bitwarden will say so.");
+    }
+    return typed;
+}

package/dist/bws/vault.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export declare const VAULT_ITEM_NAME = "DevDogs Secrets Manager access token (admin)";
+export type VaultStatus = "unavailable" | "unauthenticated" | "locked" | "unlocked";
+/** `bw status`, or `unavailable` when the CLI is not installed. */
+export declare function vaultStatus(): Promise<VaultStatus>;
+/**
+ * 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.
+ */
+export declare function readTokenFromVault(): Promise<string | undefined>;
+/**
+ * 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.
+ */
+export declare function saveTokenToVault(token: string): Promise<boolean>;
+/** Why the vault could not be used, phrased as something to do about it. */
+export declare function explainVault(status: VaultStatus): string | undefined;

package/dist/bws/vault.js

@@ -0,0 +1,200 @@
+/**
+ * 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.
+ */
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { confirm, log, spinner } from "@clack/prompts";
+import { unwrap } from "../ui.js";
+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.
+ */
+export const VAULT_ITEM_NAME = "DevDogs Secrets Manager access token (admin)";
+/** `bw status`, or `unavailable` when the CLI is not installed. */
+export async function vaultStatus() {
+    try {
+        const { stdout } = await run("bw", bwArgs(["status", "--response"]), {
+            shell: false,
+        });
+        // `--response` wraps the payload; the bare form is also accepted, so read
+        // whichever shape came back rather than depending on one.
+        const parsed = JSON.parse(stdout);
+        const status = ("status" in parsed && parsed.status) ||
+            ("data" in parsed && parsed.data?.template?.status) ||
+            undefined;
+        if (status === "unlocked")
+            return "unlocked";
+        if (status === "locked")
+            return "locked";
+        return "unauthenticated";
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "unavailable";
+        return "unauthenticated";
+    }
+}
+/**
+ * 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.
+ */
+async function session(status) {
+    if (process.env.BW_SESSION)
+        return process.env.BW_SESSION;
+    if (status !== "locked")
+        return undefined;
+    if (!process.stdin.isTTY)
+        return undefined;
+    const ok = unwrap(await confirm({
+        message: "Your Bitwarden vault is locked. Unlock it to look for the access token?",
+        initialValue: true,
+    }));
+    if (!ok)
+        return undefined;
+    return new Promise((resolve) => {
+        // stdin inherited so the master password goes to `bw` and not through here;
+        // stdout piped so the session key can be captured rather than printed.
+        const child = spawn("bw", ["unlock", "--raw"], {
+            stdio: ["inherit", "pipe", "inherit"],
+            shell: false,
+        });
+        let out = "";
+        child.stdout.on("data", (c) => (out += c.toString()));
+        child.on("error", () => resolve(undefined));
+        child.on("close", (code) => resolve(code === 0 && out.trim() !== "" ? out.trim() : undefined));
+    });
+}
+/**
+ * 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.
+ */
+export async function readTokenFromVault() {
+    const status = await vaultStatus();
+    if (status === "unavailable" || status === "unauthenticated") {
+        // Said out loud, and only here. By the time this runs the chain has already
+        // found nothing in the flag or the environment, so the person is about to
+        // be asked to paste a token. That is when knowing the vault could have
+        // answered instead is worth something.
+        log.info(explainVault(status));
+        return undefined;
+    }
+    const key = await session(status);
+    if (status === "locked" && !key)
+        return undefined;
+    const s = spinner();
+    s.start("Looking in your Bitwarden vault");
+    try {
+        const { stdout } = await run("bw", bwArgs(["get", "password", VAULT_ITEM_NAME, "--raw"], key), { shell: false });
+        const token = stdout.trim();
+        if (token === "") {
+            s.stop("Nothing stored in the vault yet");
+            return undefined;
+        }
+        s.stop(`Read the access token from your vault ("${VAULT_ITEM_NAME}")`);
+        return token;
+    }
+    catch {
+        // "not found" and "more than one match" both land here, and both mean the
+        // same thing to the caller: ask instead.
+        s.stop("No single matching item in your vault");
+        return undefined;
+    }
+}
+/**
+ * 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.
+ */
+export async function saveTokenToVault(token) {
+    const status = await vaultStatus();
+    if (status === "unavailable" || status === "unauthenticated")
+        return false;
+    const key = await session(status);
+    if (status === "locked" && !key)
+        return false;
+    const item = {
+        organizationId: null,
+        collectionIds: null,
+        folderId: null,
+        type: 1, // login, so `bw get password` can retrieve it in one call
+        name: VAULT_ITEM_NAME,
+        notes: "Bitwarden Secrets Manager access token for the `admin` machine account, " +
+            "read/write on preflight, staging and production.\n\n" +
+            "Read automatically by `pnpm devtools 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("bw", 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. */
+export function explainVault(status) {
+    if (status === "unavailable") {
+        return ("The `bw` CLI is not installed, so the vault could not be checked. " +
+            "`pnpm devtools bw login` — the CLI is a devtools dependency, nothing to install.");
+    }
+    if (status === "unauthenticated") {
+        return "The `bw` CLI is not signed in. Run `bw login`.";
+    }
+    return undefined;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What can be reported on this instance, and for what reasons?
+ *
+ * Neither half of that question had an answer in the CLI before. `doctor` comes
+ * closest, but it runs `conformance_check()` for a single app and reports
+ * pass/fail per content type, a diagnostic rather than a listing, and it says
+ * nothing about reasons at all.
+ *
+ * It matters more now than it used to, because both halves stopped being
+ * editable at runtime. Content types are derived from each app's own schema and
+ * report reasons are a platform-owned enum, so there is no configuration page
+ * to open and look at. The database is the only source of truth, and this is
+ * how a contributor reads it. `docs/platform/reporting-and-feedback.md` carries
+ * a copy of the reason list for people who are not at a terminal, but that copy
+ * is maintained by hand and says so. This is what settles a disagreement.
+ *
+ * Both calls run as the seeded moderator rather than through an admin client.
+ * `list_content_types` is `security definer` behind a `canModerate` check, so
+ * an anonymous or ordinary client sees nothing, and `list_report_reasons` is
+ * `security invoker` and subject to RLS. Using a persona means what prints here
+ * is what a moderator would actually see, rather than what a superuser can.
+ */
+import { type Instance } from "./instance.js";
+export interface CatalogReason {
+    reason: string;
+    title: string;
+    description: string | null;
+}
+export interface CatalogContentType {
+    appSlug: string;
+    contentType: string;
+    label: string;
+    tableName: string;
+    schemaName: string;
+    visibility: string;
+    /** Null when the table carries no foreign key to reportResolutions. */
+    quarantineColumn: string | null;
+    /** Null when no single-column primary key could be derived. */
+    refColumn: string | null;
+    authorColumn: string | null;
+}
+export interface Catalog {
+    reasons: CatalogReason[];
+    contentTypes: CatalogContentType[];
+}
+export declare function readCatalog(instance: Instance): Promise<Catalog>;
+/**
+ * Formats the catalog for `note()`.
+ *
+ * Content types are grouped by app, because a contributor asks "what does *my*
+ * app expose?". A type that cannot be quarantined or cannot be addressed is
+ * called out inline rather than left to be inferred from a blank column. Those
+ * are the two states that look like working configuration and are not.
+ */
+export declare function renderCatalog(catalog: Catalog): string;

package/dist/catalog.js

@@ -0,0 +1,81 @@
+/**
+ * What can be reported on this instance, and for what reasons?
+ *
+ * Neither half of that question had an answer in the CLI before. `doctor` comes
+ * closest, but it runs `conformance_check()` for a single app and reports
+ * pass/fail per content type, a diagnostic rather than a listing, and it says
+ * nothing about reasons at all.
+ *
+ * It matters more now than it used to, because both halves stopped being
+ * editable at runtime. Content types are derived from each app's own schema and
+ * report reasons are a platform-owned enum, so there is no configuration page
+ * to open and look at. The database is the only source of truth, and this is
+ * how a contributor reads it. `docs/platform/reporting-and-feedback.md` carries
+ * a copy of the reason list for people who are not at a terminal, but that copy
+ * is maintained by hand and says so. This is what settles a disagreement.
+ *
+ * Both calls run as the seeded moderator rather than through an admin client.
+ * `list_content_types` is `security definer` behind a `canModerate` check, so
+ * an anonymous or ordinary client sees nothing, and `list_report_reasons` is
+ * `security invoker` and subject to RLS. Using a persona means what prints here
+ * is what a moderator would actually see, rather than what a superuser can.
+ */
+import { personaClient, PERSONAS } from "./instance.js";
+export async function readCatalog(instance) {
+    const client = await personaClient(instance, PERSONAS.moderator);
+    const [reasons, contentTypes] = await Promise.all([
+        client.rpc("list_report_reasons"),
+        client.rpc("list_content_types"),
+    ]);
+    if (reasons.error)
+        throw new Error(reasons.error.message);
+    if (contentTypes.error)
+        throw new Error(contentTypes.error.message);
+    return {
+        reasons: (reasons.data ?? []),
+        contentTypes: (contentTypes.data ?? []),
+    };
+}
+/**
+ * Formats the catalog for `note()`.
+ *
+ * Content types are grouped by app, because a contributor asks "what does *my*
+ * app expose?". A type that cannot be quarantined or cannot be addressed is
+ * called out inline rather than left to be inferred from a blank column. Those
+ * are the two states that look like working configuration and are not.
+ */
+export function renderCatalog(catalog) {
+    const lines = [];
+    lines.push("Report reasons — one global list, every app, every content type");
+    for (const r of catalog.reasons) {
+        lines.push(`  ${r.reason.padEnd(16)} ${r.title}`);
+    }
+    if (catalog.reasons.length === 0) {
+        lines.push("  (none — the presentation table is empty, which is a bug)");
+    }
+    lines.push("");
+    lines.push("Content types — derived from each app's schema, not configured");
+    const byApp = new Map();
+    for (const t of catalog.contentTypes) {
+        byApp.set(t.appSlug, [...(byApp.get(t.appSlug) ?? []), t]);
+    }
+    if (byApp.size === 0) {
+        lines.push("  (none — no registered app declares any moderatable content)");
+    }
+    for (const [app, types] of [...byApp].sort()) {
+        lines.push(`  ${app}`);
+        for (const t of types) {
+            const notes = [];
+            if (!t.quarantineColumn)
+                notes.push("no quarantine column");
+            if (!t.refColumn)
+                notes.push("NOT ADDRESSABLE: no single-column key");
+            if (!t.authorColumn)
+                notes.push("no author column derived");
+            const suffix = notes.length > 0 ? `  (${notes.join("; ")})` : "";
+            lines.push(`    ${t.contentType.padEnd(14)} ${t.schemaName}.${t.tableName}` +
+                `  [${t.visibility}]${suffix}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/cf/commands.d.ts

@@ -0,0 +1 @@
+export declare function runCf(argv: readonly string[]): Promise<number>;