@devdogsuga/devtools 0.1.26 → 0.1.28

package/dist/emails/commands.js

@@ -1,130 +0,0 @@
-/** `pnpm devtools emails [template…] [--format html,text] [--out dir]`. */
-import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
-import { isTTY, log, multiselect, note, text as askText } from "@clack/prompts";
-import { positionals } from "../args.js";
-import { explain, explainError, unwrap, UsageError } from "../ui.js";
-import { EMAIL_FIXTURES } from "./fixtures.js";
-import { loadEmail } from "../repo/source.js";
-export const EMAIL_FORMATS = ["html", "text"];
-export const EMAIL_NAMES = Object.keys(EMAIL_FIXTURES);
-function flagValue(argv, flag) {
-    const index = argv.indexOf(flag);
-    if (index === -1)
-        return undefined;
-    const value = argv[index + 1];
-    return value && !value.startsWith("--") ? value : undefined;
-}
-function expandHome(value) {
-    return value === "~" || value.startsWith("~/")
-        ? resolve(homedir(), value.slice(2))
-        : value;
-}
-export function parseEmailArgs(argv, cwd) {
-    const requested = positionals(argv);
-    const unknown = requested.filter((name) => name !== "*" && !EMAIL_NAMES.includes(name));
-    if (unknown.length) {
-        return new Error(`No email template called ${unknown.join(", ")}. Try ${EMAIL_NAMES.join(", ")}, or *.`);
-    }
-    const rawFormats = (flagValue(argv, "--format") ?? "html")
-        .split(",")
-        .map((value) => value.trim())
-        .filter(Boolean);
-    const badFormats = rawFormats.filter((value) => !EMAIL_FORMATS.includes(value));
-    if (badFormats.length)
-        return new Error(`Unknown format ${badFormats.join(", ")}. Try html or text.`);
-    const names = requested.includes("*")
-        ? [...EMAIL_NAMES]
-        : requested;
-    return {
-        names,
-        formats: [...new Set(rawFormats)],
-        out: resolve(cwd, expandHome(flagValue(argv, "--out") ?? "email-previews")),
-        noOutput: argv.includes("--dry-run") || argv.includes("--no-output"),
-    };
-}
-async function interactive(options) {
-    if (options.names.length)
-        return options;
-    if (!isTTY(process.stdout)) {
-        throw new UsageError("No terminal to choose templates. Name one, or pass * for all.");
-    }
-    const names = unwrap(await multiselect({
-        message: "Which emails?",
-        options: EMAIL_NAMES.map((name) => ({ value: name, label: name })),
-        initialValues: [...EMAIL_NAMES],
-        required: true,
-    }));
-    const formats = unwrap(await multiselect({
-        message: "Which formats?",
-        options: [
-            { value: "html", label: "HTML", hint: "open in a browser" },
-            { value: "text", label: "Plain text", hint: "the email alternative" },
-        ],
-        initialValues: ["html"],
-        required: true,
-    }));
-    const entered = unwrap(await askText({
-        message: "Where should these go?",
-        placeholder: "./email-previews",
-        defaultValue: "./email-previews",
-    })).trim();
-    return {
-        ...options,
-        names,
-        formats,
-        out: resolve(process.cwd(), expandHome(entered || "email-previews")),
-    };
-}
-export function destination(out, name, format) {
-    return resolve(out, `${name}.${format === "text" ? "txt" : "html"}`);
-}
-export async function generateEmails(options) {
-    // Dynamic so every unrelated devtools command can still run before the
-    // generated email package has been built on a fresh checkout.
-    const { render } = await loadEmail();
-    const written = [];
-    for (const name of options.names) {
-        const email = render(name, EMAIL_FIXTURES[name]);
-        for (const format of options.formats) {
-            const file = destination(options.out, name, format);
-            await mkdir(dirname(file), { recursive: true });
-            await writeFile(file, format === "html" ? email.html : email.text);
-            written.push(file);
-        }
-    }
-    return written;
-}
-export async function runEmails(argv) {
-    const parsed = parseEmailArgs(argv, process.cwd());
-    if (parsed instanceof Error) {
-        explain("Could not read that.", parsed.message, [
-            "pnpm devtools emails",
-            "pnpm devtools emails '*' --format html,text --out ~/emails",
-        ]);
-        process.exitCode = 1;
-        return;
-    }
-    try {
-        const options = await interactive(parsed);
-        if (options.noOutput) {
-            const { render } = await loadEmail();
-            note(options.names
-                .map((name) => `${name}\n  ${render(name, EMAIL_FIXTURES[name]).subject}\n  ${options.formats.map((f) => destination(options.out, name, f)).join("\n  ")}`)
-                .join("\n"), `${options.names.length} email template${options.names.length === 1 ? "" : "s"}`);
-            return;
-        }
-        const written = await generateEmails(options);
-        for (const file of written)
-            log.success(file);
-        log.info(`${written.length} preview file${written.length === 1 ? "" : "s"} written.`);
-    }
-    catch (err) {
-        explainError("Could not render those emails.", err, [
-            "Build the email package with `pnpm --filter @devdogsuga/email build`.",
-            "Then try `pnpm devtools emails '*' --out ~/emails`.",
-        ]);
-        process.exitCode = 1;
-    }
-}

package/dist/emails/email-types.d.ts

@@ -1,13 +0,0 @@
-/**
- * Type-only stand-in for `@devdogsuga/email`'s generated `Templates` map.
- *
- * `@devdogsuga/email` is `"private": true` and never published — it stays
- * in DevDogsUGA and devtools resolves it FROM the repo at runtime
- * (`repo/source.ts`'s `loadEmail()`). Backstage has no copy to pull the
- * real generated type from, so `fixtures.ts`'s `satisfies` check is
- * loosened to "every template's fixture is a flat string-prop object"
- * instead of the real per-template exact prop shape. A prop typo here is
- * caught at runtime (the real `render()` throws on a missing required
- * prop), not at Backstage's typecheck time.
- */
-export type EmailTemplates = Record<string, Record<string, string>>;

package/dist/emails/email-types.js

@@ -1 +0,0 @@
-export {};

package/dist/emails/fixtures.d.ts

@@ -1,20 +0,0 @@
-/**
- * Credible, non-sensitive values for local previews.
- *
- * `satisfies` is the maintenance mechanism: a new template or prop cannot be
- * shipped without deciding what its preview should say.
- */
-export declare const EMAIL_FIXTURES: {
-    JoinRequest: {
-        leadName: string;
-        applicantName: string;
-        teamName: string;
-        reviewUrl: string;
-    };
-    TeamInvite: {
-        inviteeName: string;
-        teamName: string;
-        leadName: string;
-        acceptUrl: string;
-    };
-};

package/dist/emails/fixtures.js

@@ -1,20 +0,0 @@
-/**
- * Credible, non-sensitive values for local previews.
- *
- * `satisfies` is the maintenance mechanism: a new template or prop cannot be
- * shipped without deciding what its preview should say.
- */
-export const EMAIL_FIXTURES = {
-    JoinRequest: {
-        leadName: "Jordan",
-        applicantName: "Avery",
-        teamName: "Byte Bulldogs",
-        reviewUrl: "https://devdogsuga.org/teams/requests",
-    },
-    TeamInvite: {
-        inviteeName: "Avery",
-        teamName: "Byte Bulldogs",
-        leadName: "Jordan",
-        acceptUrl: "https://devdogsuga.org/teams/requests",
-    },
-};

package/dist/env/audit.d.ts

@@ -1,206 +0,0 @@
-/**
- * Four-way drift detection: local `.env`, Bitwarden, GitHub, Cloudflare.
- *
- * Each store answers a different question, and only one of them answers it
- * completely:
- *
- *   | Store              | Exposes           | So it can be checked for |
- *   |--------------------|-------------------|--------------------------|
- *   | local .env         | names AND values  | value drift              |
- *   | Bitwarden          | names AND values  | value drift (the truth)  |
- *   | GitHub *secrets*   | names + updatedAt | presence, staleness      |
- *   | GitHub *variables* | names AND values  | value drift              |
- *   | Cloudflare         | names only        | presence, orphans        |
- *
- * That asymmetry is the whole design. A GitHub *secret* is write-only, so a
- * clean audit of one does not mean "the values match". It means "nothing
- * detectable is wrong", and the report says which is which rather than implying
- * the stronger claim.
- *
- * Timestamps are what rescue that row from being presence-only. Bitwarden
- * reports a `revisionDate` per secret and `gh secret list` reports `updatedAt`,
- * so "was GitHub updated after Bitwarden last changed?" IS answerable. That is
- * the failure this design actually has: a credential rotated in Bitwarden and
- * never propagated, which a name-only check calls healthy right up until the old
- * one is revoked.
- *
- * ⚠️ GitHub *variables* are the one downstream store that needs none of that
- * reasoning: `gh variable list` returns the value, so the public per-environment
- * keys are compared exactly the way the local file is. Staleness is deliberately
- * NOT applied to them: a timestamp is a proxy for a comparison that could not
- * be made, and using the proxy where the real answer is available would report a
- * variable re-pushed with an identical value as drift. The security plan's §3.6
- * limitation ("names only… a changed value is undetectable") now holds for the
- * secret row alone.
- *
- * ⚠️ One scope sits outside that table altogether: the repository's OWN
- * variables. Push writes environment-scoped values only, and an environment
- * variable SHADOWS a repository one of the same name, so a repository-level
- * copy of a managed key is read by nothing, drifts forever, and becomes the
- * live value on the day somebody deletes the environment copy. It is checked
- * here for the same reason §3.6's orphans are: nothing manages it, so nothing
- * else in this system would ever mention it.
- */
-export type Severity = "error" | "warning" | "info";
-export interface Finding {
-    key: string;
-    severity: Severity;
-    /** Where the problem is, for grouping. */
-    store: "local" | "github" | "cloudflare";
-    summary: string;
-}
-export interface BwsEntry {
-    value: string;
-    /** ISO 8601. Absent when the CLI did not report one. */
-    revisionDate?: string;
-}
-export interface GithubEntry {
-    /** Which GitHub environment this copy sits in. */
-    environment: string;
-    name: string;
-    /** ISO 8601. */
-    updatedAt?: string;
-}
-/**
- * A GitHub environment *variable*: the same shape plus the thing that makes
- * variables worth having, a readable value.
- */
-export interface GithubVariableEntry extends GithubEntry {
-    value: string;
-}
-export interface AuditInput {
-    /** Active assignments in the local `.env`. */
-    local: Map<string, string>;
-    /** Keys present in the local `.env` but commented out. */
-    localCommented?: Set<string>;
-    /** The source of truth. */
-    bws: Map<string, BwsEntry>;
-    /**
-     * Every GitHub copy found, across every environment this project feeds.
-     *
-     * A list rather than a map keyed by name, because one Bitwarden project can
-     * feed two GitHub environments and the interesting case is a key appearing in
-     * BOTH, which a name-keyed map would quietly collapse to one.
-     */
-    github: GithubEntry[];
-    /**
-     * Every GitHub environment *variable* found, across the same environments.
-     *
-     * Separate from `github` rather than merged with a discriminator, because
-     * GitHub genuinely allows one name to exist as both a secret and a variable
-     * in one environment and resolves the ambiguity by never telling you. See
-     * `deploy/write-env.ts`, which refuses that case outright. Two lists can
-     * represent it; one list keyed by name cannot, and would silently pick a
-     * winner.
-     */
-    githubVariables?: GithubVariableEntry[];
-    /**
-     * Keys that belong in the variable store rather than the secret store, from
-     * `variableKeys()` in the registry.
-     *
-     * Drives two things at once: which store a key is compared against, and the
-     * pair of misplacement errors. Absent, every key is treated as a secret,
-     * which is the pre-variables behaviour.
-     */
-    variables?: ReadonlySet<string>;
-    /**
-     * Where a key is supposed to live: the PRIMARY environment, the one whose
-     * absence is an error. `null` means "nowhere in this environment", which is
-     * ordinary rather than wrong.
-     */
-    route: (key: string) => string | null;
-    /**
-     * Whether a copy found in some OTHER environment is legitimate.
-     *
-     * Separate from `route` because the two questions stopped having the same
-     * answer when `production-apply` became a superset of `production`: an
-     * ordinary production key is now pushed to both, so "not where `route` says"
-     * no longer means "misplaced". Folding them back together reports every
-     * correctly-pushed copy as a stray to delete, and a reviewer who deletes 46
-     * of those learns to skim the stray finding, which is the one finding that
-     * catches an apply-tier credential sitting in the unreviewed environment.
-     *
-     * Defaults to the old behaviour (`only where route says`), so a caller that
-     * has not thought about fan-out gets the strict answer rather than a
-     * permissive one.
-     */
-    accepted?: (key: string, environment: string) => boolean;
-    /** Worker name → secret names on it. Values are unreadable. */
-    cloudflare?: Map<string, Set<string>>;
-    /** Keys that legitimately live outside Bitwarden: the non-secrets. */
-    ignore?: ReadonlySet<string>;
-    /**
-     * Credentials that must never be stored remotely at all.
-     *
-     * Distinct from `ignore`, and the opposite of it: an ignored key is expected
-     * somewhere else, whereas one of these appearing in ANY remote store is a
-     * finding. Being in the local `.env` and nowhere else is the correct state,
-     * so the ordinary "not in Bitwarden" warning must not fire for them.
-     */
-    neverStore?: ReadonlySet<string>;
-    /**
-     * Credentials signed at deploy time, whose only copy is on the deploy target.
-     *
-     * The third category, and it sits between the other two rather than beside
-     * them: unlike `ignore` it is a secret, and unlike `neverStore` there is one
-     * remote store it BELONGS in. A key like this is signed at deploy time and
-     * written straight to the Worker, so being on Cloudflare and nowhere else is
-     * exactly right. `SANDBOX_PROXY_TOKEN` is still declared this way in
-     * `apps/sandbox/env.ts` — nothing mints it any more, since the deploy that
-     * did was removed with the sandbox integration it authenticated, but the
-     * declaration is what keeps this category from reading "on production-
-     * sandbox, not in Bitwarden" the day someone does fill it in by hand.
-     *
-     * Without this set the Cloudflare pass below reports a key like that as an
-     * orphan, which the plan doc's §3.6 prune path then offers to delete.
-     * Marking it the other obvious way, as `never-store`, inverts the error into
-     * "must NEVER be a Worker secret" and is just as wrong in the opposite
-     * direction.
-     */
-    minted?: ReadonlySet<string>;
-    /**
-     * Every key the registry knows. When provided, a local key outside it is
-     * reported as UNDECLARED: its own category, not folded into drift, because
-     * the fix is different: drift wants a push or a pull, an undeclared key
-     * wants a `define()` in the owning manifest (or the line removed). It is
-     * also why `env push` skipped it, and the audit should say so rather
-     * than let "not in Bitwarden" imply pushing would help.
-     */
-    declared?: ReadonlySet<string>;
-    /**
-     * The repository's OWN variables, the scope with no environment, or the fact
-     * that they could not be listed.
-     *
-     * A union rather than a list, because three states have to stay apart and a
-     * list can only hold two of them: nobody looked (absent: the pre-existing
-     * behaviour, no claim either way), looked and saw these names
-     * (`readable`), and TRIED TO LOOK AND COULD NOT (`readable: false`). Listing
-     * repository variables can fail where listing environment ones succeeds, so
-     * the third state is ordinary rather than exotic, and collapsing it into an
-     * empty list is precisely the bug this check was added to catch, one scope
-     * up: a report that says "checked, nothing found" about a check that never
-     * ran.
-     *
-     * Names only. See `GhRepositoryVariable` for why the value is deliberately
-     * not fetched.
-     */
-    repositoryVariables?: RepositoryVariableScan;
-}
-/**
- * What `gh variable list` (no `--env`) returned, or why it returned nothing.
- *
- * `reason` is carried rather than dropped because the two failures need
- * different next steps and look identical from a finding that omits it: a
- * missing permission is fixed by an admin, an unauthenticated CLI by the person
- * reading the report.
- */
-export type RepositoryVariableScan = {
-    readable: true;
-    names: readonly string[];
-} | {
-    readable: false;
-    reason: string;
-};
-export declare function audit(input: AuditInput): Finding[];
-export declare function hasErrors(findings: Finding[]): boolean;
-export declare function renderFindings(findings: Finding[]): string;