@devdogsuga/devtools 0.1.0

package/dist/images/select.js

@@ -0,0 +1,96 @@
+import { loadOpenGraph } from "../repo/source.js";
+/**
+ * Resolves graphic patterns.
+ *
+ * Every graphic is `group/name`, and three shapes of pattern read against
+ * that: a lone star (or a star over a star) is everything, `group/` plus a star
+ * is a whole group, and anything else is an exact name. Deliberately not a
+ * general glob — `event/2026-` plus a star looks like it should work and would
+ * be one more thing to specify, and the picker covers the case where somebody
+ * does not know the exact name.
+ *
+ * A bare group is accepted as shorthand for `group/*`, because `images icons`
+ * is what people type and refusing it teaches nothing.
+ */
+export function matchGraphics(patterns, graphics) {
+    const matched = new Map();
+    const unmatched = [];
+    const groups = new Set(graphics.map((graphic) => graphic.group));
+    for (const pattern of patterns) {
+        const hits = graphics.filter((graphic) => {
+            if (pattern === "*" || pattern === "*/*")
+                return true;
+            if (pattern.endsWith("/*"))
+                return graphic.group === pattern.slice(0, -2);
+            if (groups.has(pattern))
+                return graphic.group === pattern;
+            return graphic.name === pattern;
+        });
+        if (hits.length === 0) {
+            unmatched.push(pattern);
+            continue;
+        }
+        for (const hit of hits)
+            matched.set(hit.name, hit);
+    }
+    return { matched: [...matched.values()], unmatched };
+}
+/**
+ * Pairs each graphic with each requested format it actually supports.
+ *
+ * The matrix is sparse, and silently dropping a pair is the wrong answer in one
+ * direction only: asking for `*` at every format should quietly skip the
+ * combinations that do not exist, while asking for one graphic at one format it
+ * cannot do should say so. The caller decides which case it is; this reports
+ * both halves.
+ */
+export async function pair(graphics, formats) {
+    const { FORMATS } = await loadOpenGraph();
+    const selections = [];
+    const unsupported = [];
+    for (const graphic of graphics) {
+        for (const name of formats) {
+            const format = FORMATS[name];
+            if (!format)
+                continue;
+            if (graphic.formats.includes(name)) {
+                selections.push({ graphic, format });
+            }
+            else {
+                unsupported.push({ graphic: graphic.name, format: name });
+            }
+        }
+    }
+    return { selections, unsupported };
+}
+/** Every format any of these graphics can be drawn at, in registry order. */
+export async function formatsFor(graphics) {
+    const { FORMATS } = await loadOpenGraph();
+    const names = new Set(graphics.flatMap((graphic) => graphic.formats));
+    return Object.values(FORMATS).filter((format) => names.has(format.name));
+}
+/**
+ * Splits `--flag=value` into two tokens.
+ *
+ * The rest of this CLI reads flags as `--flag value`, and `positionals()`
+ * depends on that to tell a flag's value from a subcommand. `--format=a,b`
+ * arrives as one token, so it would be read as a positional — that is, as a
+ * graphic name — and `images --format=og` would try to render a graphic called
+ * `--format=og` and report nothing matched. Normalising here lets both spellings
+ * work without teaching the shared parser about either.
+ */
+export function normalizeArgv(argv) {
+    return argv.flatMap((token) => {
+        if (!token.startsWith("--"))
+            return [token];
+        const eq = token.indexOf("=");
+        return eq === -1 ? [token] : [token.slice(0, eq), token.slice(eq + 1)];
+    });
+}
+/** A comma-separated flag value, trimmed and emptied of blanks. */
+export function commaList(value) {
+    return (value ?? "")
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+}

package/dist/instance.d.ts

@@ -0,0 +1,67 @@
+import { findRepoRoot } from "./repo/root.js";
+/**
+ * The repo root, which is where `supabase/config.toml` lives.
+ *
+ * The Supabase CLI walks up from its working directory looking for that file,
+ * and falls back to `basename(cwd)` as the project name when it finds none, so
+ * running it from the wrong place fails with "No such container:
+ * supabase_db_<whatever directory you were in>". Resolved via `findRepoRoot()`
+ * (walking up from `process.cwd()`, not this source file — see `repo/root.ts`)
+ * so it does not matter where the contributor invoked the tool from.
+ */
+export { findRepoRoot };
+/**
+ * Every client here goes through this one factory so they all share a type.
+ *
+ * supabase-js encodes the default schema in the client's type, so a `schema`
+ * parameter of type `string` produces a client that will not unify with a
+ * hand-written `SupabaseClient` annotation. Deriving `DevtoolsClient` from the
+ * factory sidesteps that.
+ */
+declare function makeClient(url: string, key: string, schema: string): import("@supabase/supabase-js").SupabaseClient<any, "public", string, any, any>;
+export type DevtoolsClient = ReturnType<typeof makeClient>;
+export interface Instance {
+    apiUrl: string;
+    publishableKey: string;
+    secretKey: string;
+}
+/** The seeded personas, from `supabase/seed/development/02_moderation.sql`. */
+export declare const PERSONAS: {
+    readonly member: "member@devdogs.test";
+    readonly author: "author@devdogs.test";
+    readonly moderator: "moderator@devdogs.test";
+};
+/** The built-in Root role, from `supabase/seed/production/01_roles.sql`. */
+export declare const ROOT_ROLE_ID = "00000000-0000-0000-0000-000000000002";
+export declare const PERSONA_PASSWORD = "password";
+/**
+ * Reads the local stack's credentials from the Supabase CLI.
+ *
+ * `-o env` rather than parsing the human-readable table: the table's labels
+ * have changed between CLI versions, the env output has not.
+ */
+export declare function detectLocalInstance(cwd?: string): Instance;
+/**
+ * Confirms the instance has actually been migrated.
+ *
+ * This used to be `assertNotProduction()`, which read a tier out of a singleton
+ * `platform."instance"` table and refused anything reporting itself as
+ * production. That table is gone, and the tier column was guarding a door that
+ * was already walled up: `detectLocalInstance()` above reads `supabase status`,
+ * which only ever describes the Docker stack on this machine, so a remote
+ * project cannot reach these commands in the first place.
+ *
+ * What was useful was its error message, because "have you run migrations?" is
+ * the failure a contributor actually hits. That is all this does now.
+ */
+export declare function assertMigrated(instance: Instance): Promise<void>;
+/** A service-role client. Bypasses RLS, so setup and teardown only. */
+export declare function adminClient(instance: Instance, schema?: string): DevtoolsClient;
+/**
+ * A client signed in as a seeded persona, subject to RLS.
+ *
+ * Signs in for real rather than hand-signing a JWT, so the token path exercised
+ * is the one production uses, with whatever claims Supabase Auth actually puts
+ * in a token rather than the ones we assume.
+ */
+export declare function personaClient(instance: Instance, email: string, schema?: string): Promise<DevtoolsClient>;

package/dist/instance.js

@@ -0,0 +1,129 @@
+/**
+ * Finding the instance to work against, and signing in to it.
+ *
+ * Detection is automatic where possible: `supabase status -o env` already
+ * prints everything needed, so nobody has to copy a URL and a key from one
+ * terminal into another.
+ */
+import { execFileSync } from "node:child_process";
+import { createClient } from "@supabase/supabase-js";
+import { findRepoRoot } from "./repo/root.js";
+/**
+ * The repo root, which is where `supabase/config.toml` lives.
+ *
+ * The Supabase CLI walks up from its working directory looking for that file,
+ * and falls back to `basename(cwd)` as the project name when it finds none, so
+ * running it from the wrong place fails with "No such container:
+ * supabase_db_<whatever directory you were in>". Resolved via `findRepoRoot()`
+ * (walking up from `process.cwd()`, not this source file — see `repo/root.ts`)
+ * so it does not matter where the contributor invoked the tool from.
+ */
+export { findRepoRoot };
+/**
+ * Every client here goes through this one factory so they all share a type.
+ *
+ * supabase-js encodes the default schema in the client's type, so a `schema`
+ * parameter of type `string` produces a client that will not unify with a
+ * hand-written `SupabaseClient` annotation. Deriving `DevtoolsClient` from the
+ * factory sidesteps that.
+ */
+function makeClient(url, key, schema) {
+    return createClient(url, key, {
+        db: { schema },
+        auth: { autoRefreshToken: false, persistSession: false },
+    });
+}
+/** The seeded personas, from `supabase/seed/development/02_moderation.sql`. */
+export const PERSONAS = {
+    member: "member@devdogs.test",
+    author: "author@devdogs.test",
+    moderator: "moderator@devdogs.test",
+};
+/** The built-in Root role, from `supabase/seed/production/01_roles.sql`. */
+export const ROOT_ROLE_ID = "00000000-0000-0000-0000-000000000002";
+export const PERSONA_PASSWORD = "password";
+/**
+ * Reads the local stack's credentials from the Supabase CLI.
+ *
+ * `-o env` rather than parsing the human-readable table: the table's labels
+ * have changed between CLI versions, the env output has not.
+ */
+export function detectLocalInstance(cwd = findRepoRoot()) {
+    let output;
+    try {
+        // Through `pnpm exec` because the Supabase CLI is a workspace devDependency
+        // rather than a global install. Invoking `supabase` directly works only on
+        // machines that happen to have it on PATH.
+        output = execFileSync("pnpm", ["exec", "supabase", "status", "-o", "env"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not read the local Supabase stack.\n${err instanceof Error ? err.message : String(err)}`);
+    }
+    // The CLI prefixes the block with a "Stopped services: [...]" line whenever
+    // any optional service is down, which is the normal state here. Lines that do
+    // not parse as KEY="value" are skipped rather than treated as an error.
+    const values = new Map();
+    for (const line of output.split("\n")) {
+        const match = /^([A-Z0-9_]+)="?([^"]*)"?$/.exec(line.trim());
+        if (match?.[1])
+            values.set(match[1], match[2] ?? "");
+    }
+    const apiUrl = values.get("API_URL");
+    // Newer CLI versions print PUBLISHABLE_KEY/SECRET_KEY; older ones print the
+    // ANON_KEY/SERVICE_ROLE_KEY names. Both are accepted so the tool does not
+    // break on whichever the contributor happens to have installed.
+    const publishableKey = values.get("PUBLISHABLE_KEY") ?? values.get("ANON_KEY");
+    const secretKey = values.get("SECRET_KEY") ?? values.get("SERVICE_ROLE_KEY");
+    if (!apiUrl || !publishableKey || !secretKey) {
+        throw new Error("`supabase status` did not report an API URL and keys. Is the stack running?");
+    }
+    return { apiUrl, publishableKey, secretKey };
+}
+/**
+ * Confirms the instance has actually been migrated.
+ *
+ * This used to be `assertNotProduction()`, which read a tier out of a singleton
+ * `platform."instance"` table and refused anything reporting itself as
+ * production. That table is gone, and the tier column was guarding a door that
+ * was already walled up: `detectLocalInstance()` above reads `supabase status`,
+ * which only ever describes the Docker stack on this machine, so a remote
+ * project cannot reach these commands in the first place.
+ *
+ * What was useful was its error message, because "have you run migrations?" is
+ * the failure a contributor actually hits. That is all this does now.
+ */
+export async function assertMigrated(instance) {
+    const client = makeClient(instance.apiUrl, instance.secretKey, "platform");
+    const { error } = await client.from("apps").select("slug").limit(1);
+    if (error) {
+        throw new Error(`Could not read platform."apps": ${error.message}. ` +
+            "Have migrations been applied? `pnpm devtools db reset` rebuilds from scratch.");
+    }
+}
+/** A service-role client. Bypasses RLS, so setup and teardown only. */
+export function adminClient(instance, schema = "platform") {
+    return makeClient(instance.apiUrl, instance.secretKey, schema);
+}
+/**
+ * A client signed in as a seeded persona, subject to RLS.
+ *
+ * Signs in for real rather than hand-signing a JWT, so the token path exercised
+ * is the one production uses, with whatever claims Supabase Auth actually puts
+ * in a token rather than the ones we assume.
+ */
+export async function personaClient(instance, email, schema = "platform") {
+    const client = makeClient(instance.apiUrl, instance.publishableKey, schema);
+    const { error } = await client.auth.signInWithPassword({
+        email,
+        password: PERSONA_PASSWORD,
+    });
+    if (error) {
+        throw new Error(`Could not sign in as ${email}: ${error.message}. ` +
+            "Seeded personas come from `pnpm devtools` → Reset database.");
+    }
+    return client;
+}

package/dist/invocation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Records the fully-resolved argv of the command being run, so the CLI can
+ * close by printing a copy-pasteable line — the same command with every prompt
+ * already answered — for anyone who reached it through the wizard or let a
+ * missing flag fall to a prompt.
+ *
+ * ## Why a module-level recorder rather than a return value
+ *
+ * A command's inputs arrive from two places that never meet: the wizard walks
+ * `commands.ts` and gathers the *declared* options into the argv it dispatches
+ * (see `menu.ts`), while a runner resolves anything it prompts for *itself* —
+ * `workflows run` picking a tier, `env init` picking projects — deep inside its
+ * own call stack, where the dispatched argv is long out of reach. Threading a
+ * return value back up through every runner would touch each one's signature;
+ * a recorder every layer can reach touches only the layers that actually
+ * prompt.
+ *
+ * The rule for a runner: whenever a prompt (not a flag the caller already
+ * passed) decides a value, `recordResolved` the flag form of that decision. A
+ * value that came in as a flag is already in the base argv, so recording it
+ * again would double it — only the prompt branch records.
+ */
+/**
+ * Start recording for one invocation.
+ *
+ * `base` is what the dispatcher received: the wizard's built argv, or the argv
+ * the user typed. `fromMenu` marks the wizard path, where every step was a
+ * prompt, so the rerun line is worth printing even if no runner records a
+ * thing. A typed command starts non-interactive and only earns the line if a
+ * runner resolves a missing flag from a prompt.
+ */
+export declare function beginInvocation(base: readonly string[], fromMenu: boolean): void;
+/**
+ * Record the deploy tier the wizard entered up front, so the rerun line carries
+ * it. development is the ambient default, so a prefix for it would be noise and
+ * is dropped.
+ */
+export declare function recordEnteredTier(tier: string): void;
+/**
+ * Append the flag form of a value a prompt just resolved, e.g.
+ * `recordResolved("--tier", "development")`.
+ */
+export declare function recordResolved(...fragment: string[]): void;
+/**
+ * The command to print, or `null` when there is nothing worth printing —
+ * either no invocation ran, or the user typed a complete command and answered
+ * no prompts, so echoing it back would be noise.
+ */
+export declare function reproducibleCommand(): string | null;

package/dist/invocation.js

@@ -0,0 +1,78 @@
+/**
+ * Records the fully-resolved argv of the command being run, so the CLI can
+ * close by printing a copy-pasteable line — the same command with every prompt
+ * already answered — for anyone who reached it through the wizard or let a
+ * missing flag fall to a prompt.
+ *
+ * ## Why a module-level recorder rather than a return value
+ *
+ * A command's inputs arrive from two places that never meet: the wizard walks
+ * `commands.ts` and gathers the *declared* options into the argv it dispatches
+ * (see `menu.ts`), while a runner resolves anything it prompts for *itself* —
+ * `workflows run` picking a tier, `env init` picking projects — deep inside its
+ * own call stack, where the dispatched argv is long out of reach. Threading a
+ * return value back up through every runner would touch each one's signature;
+ * a recorder every layer can reach touches only the layers that actually
+ * prompt.
+ *
+ * The rule for a runner: whenever a prompt (not a flag the caller already
+ * passed) decides a value, `recordResolved` the flag form of that decision. A
+ * value that came in as a flag is already in the base argv, so recording it
+ * again would double it — only the prompt branch records.
+ */
+/** The base argv plus whatever prompts resolved; `null` until an invocation begins. */
+let argv = null;
+/** Did the wizard, or an in-command prompt, actually decide anything here? */
+let interactive = false;
+/**
+ * The deploy tier `src/launch.ts` resolved and entered for this session, or
+ * `null` for the development default. Reproduced as a leading `--tier <tier>`
+ * flag, the same global flag `launch.ts` strips off ANY invocation before
+ * `cli.ts` ever runs — see its header — so this reproduces the tier for
+ * EVERY command, `db` and `env` included, exactly as typing `--tier <tier>`
+ * up front would.
+ */
+let enteredTier = null;
+/**
+ * Start recording for one invocation.
+ *
+ * `base` is what the dispatcher received: the wizard's built argv, or the argv
+ * the user typed. `fromMenu` marks the wizard path, where every step was a
+ * prompt, so the rerun line is worth printing even if no runner records a
+ * thing. A typed command starts non-interactive and only earns the line if a
+ * runner resolves a missing flag from a prompt.
+ */
+export function beginInvocation(base, fromMenu) {
+    argv = [...base];
+    interactive = fromMenu;
+    enteredTier = null;
+}
+/**
+ * Record the deploy tier the wizard entered up front, so the rerun line carries
+ * it. development is the ambient default, so a prefix for it would be noise and
+ * is dropped.
+ */
+export function recordEnteredTier(tier) {
+    enteredTier = tier === "development" ? null : tier;
+}
+/**
+ * Append the flag form of a value a prompt just resolved, e.g.
+ * `recordResolved("--tier", "development")`.
+ */
+export function recordResolved(...fragment) {
+    if (argv === null || fragment.length === 0)
+        return;
+    argv.push(...fragment);
+    interactive = true;
+}
+/**
+ * The command to print, or `null` when there is nothing worth printing —
+ * either no invocation ran, or the user typed a complete command and answered
+ * no prompts, so echoing it back would be noise.
+ */
+export function reproducibleCommand() {
+    if (argv === null || !interactive || argv.length === 0)
+        return null;
+    const tierFlag = enteredTier ? ["--tier", enteredTier] : [];
+    return `pnpm devtools ${[...tierFlag, ...argv].join(" ")}`;
+}

package/dist/launch-ci.d.ts

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

package/dist/launch-ci.js

@@ -0,0 +1,86 @@
+/**
+ * `devtools-ci`'s entry point, in the same shape as `src/launch.ts` (read
+ * that file's header first) — resolve the session's deploy tier and enter its
+ * environment BEFORE `ci.ts` is imported — but with one deliberate
+ * difference: this NEVER prompts.
+ *
+ * CI is never interactive — `process.stdin.isTTY` is `undefined` in every job
+ * this runs in — so `resolveSessionTier` would already refuse to prompt on
+ * its own `isTTY` check. No `prompt` function is injected anyway, making that
+ * doubly true rather than relying on the ambient TTY guess: a CI job that
+ * somehow got attached to a terminal must still refuse ambiguity outright
+ * instead of hanging on a question nobody in a workflow can answer.
+ *
+ * ## Which `devtools-ci` invocations reach this file at all
+ *
+ * Only `run ci:env` does. The bare `run ci` package script — used for
+ * `deploy write-env`, which CREATES the env file this module would otherwise
+ * insist on reading, and for the handful of steps that hold one narrow
+ * credential and compose no env file at all — still runs `ci.ts` directly
+ * through `tsx`, deliberately bypassing tier resolution entirely. See
+ * `.github/workflows/deploy.yaml`'s own header for the two entry points and
+ * why each step picked the one it did.
+ *
+ * A `deploy <app> --tier <t>` invocation's `--tier` is a command flag `ci.ts`
+ * parses for itself (see its `runDeployCommand`), not this module's global
+ * `--tier` — but they resolve to the same tier here: `stripTierFlag` pulls it
+ * off before `ci.ts` sees argv, `resolveSessionTier` resolves the identical
+ * value as `explicit`, and `ci.ts`'s own parse then falls back to
+ * `process.env.DEPLOY_ENV`, which `enterEnvironment` just set to it.
+ */
+import { findRepoRoot } from "./repo/root.js";
+import { loadEnvLoad, loadEnvSession } from "./repo/peers.js";
+import { stripTierFlag } from "./launch.js";
+export async function launchCi(argv) {
+    const { explicit, rest } = stripTierFlag(argv);
+    const envLoad = await loadEnvLoad();
+    const envSession = await loadEnvSession();
+    const resolution = await envSession.resolveSessionTier({
+        explicit,
+        deployEnv: process.env.DEPLOY_ENV,
+        available: await envSession.availableTiers(findRepoRoot()),
+        isTTY: false,
+        // No `prompt` — see this file's header. Ambiguity is always a refusal.
+    });
+    if (!resolution.ok) {
+        process.stderr.write(`devtools-ci: ${resolution.reason}\n`);
+        process.exit(1);
+    }
+    const tier = resolution.tier;
+    try {
+        const entered = await envSession.enterEnvironment(tier, { override: false });
+        for (const warning of entered.warnings) {
+            process.stderr.write(`devtools-ci: ${warning}\n`);
+        }
+        process.stderr.write(`devtools-ci: loaded ${entered.files.length > 0 ? entered.files.join(", ") : "no env files"} (${tier})\n`);
+    }
+    catch (err) {
+        if (!(err instanceof envLoad.MissingEnvFileError))
+            throw err;
+        // A CI job that reaches `run ci:env` at all has already run `deploy
+        // write-env` (see this file's header), so a missing file here — for
+        // ANY tier, `development` included — is never a first-run story the way
+        // it is for a contributor's own machine. Always fatal.
+        process.stderr.write(`devtools-ci: ${err.message}\n`);
+        process.exit(1);
+    }
+    const { main } = await import("./ci.js");
+    try {
+        await main(rest);
+    }
+    catch (err) {
+        process.stderr.write(`devtools-ci: ${err instanceof Error ? err.message : String(err)}\n`);
+        // Report BEFORE exiting — see `captureDevtoolsError`'s header. `ci.ts`'s
+        // own `main()` already initialized telemetry (it does so at its own
+        // bootstrap, before this throw could happen), so this call only needs to
+        // capture and flush.
+        const { captureDevtoolsError } = await import("./telemetry.js");
+        await captureDevtoolsError(err);
+        process.exit(1);
+    }
+}
+// See `launch.ts`'s matching guard for why this checks `process.argv[1]`
+// rather than self-invoking unconditionally.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    await launchCi(process.argv.slice(2));
+}

package/dist/launch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pulls the two preflight-only boolean flags out of `argv`, wherever they
+ * sit, the same way `stripTierFlag` does for `--tier` below. Neither takes
+ * a value. `DEVTOOLS_SKIP_PREFLIGHT=1` is the env-var spelling of
+ * `--skip-preflight`, for shells/CI wrappers that would rather set an env
+ * var once than remember a flag on every invocation.
+ */
+export declare function stripPreflightFlags(argv: readonly string[]): {
+    skipPreflight: boolean;
+    refresh: boolean;
+    rest: string[];
+};
+/**
+ * Pulls a global `--tier <t>` out of `argv`, wherever it sits, leaving every
+ * other argument untouched and in its original order. Exported for its own
+ * unit tests; `launch()` below is the only real caller.
+ */
+export declare function stripTierFlag(argv: readonly string[]): {
+    explicit: string | undefined;
+    rest: string[];
+};
+/**
+ * Resolves the session's deploy tier, enters it, and hands off to `cli.ts`.
+ *
+ * Exits the process directly on a refusal from `resolveSessionTier` — there
+ * is no command dispatched yet for a caller to fall back to, so there is
+ * nothing this function could return that would mean anything.
+ */
+export declare function launch(argv: readonly string[]): Promise<void>;