@devdogsuga/devtools 0.1.26 → 0.1.28

package/dist/images/select.js

@@ -1,96 +0,0 @@
-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

@@ -1,69 +0,0 @@
-import { type DbConnection } from "./db/connection.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.
- */
-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 built-in Root role, from `supabase/seed/production/01_roles.sql`. */
-export declare const ROOT_ROLE_ID = "00000000-0000-0000-0000-000000000002";
-export interface ResolvedInstance {
-    connection: DbConnection;
-    instance: Instance;
-}
-export interface ResolveInstanceOptions {
-    /** Stderr prefix, e.g. "devtools grant-root". */
-    label?: string;
-    /** Injectable for tests; defaults to `process.env`. */
-    env?: NodeJS.ProcessEnv;
-}
-/**
- * Resolves the session's database AND the Supabase client credentials for it.
- *
- * Goes through `resolveDbConnection()` first — the exact check `db
- * migrate`/`db reset` run, including the local-stack-offline and
- * inherited-development-values guards — so a caller here refuses in exactly
- * the same situations and with the same messages those commands already do.
- * What this adds is reading `API_URL`/`PUBLISHABLE_KEY`/`SECRET_KEY` out of
- * the same already-entered session env `DB_URL` came from (see this file's
- * header), rather than shelling out to `supabase status` — which is what
- * makes hosted tiers reachable here at all.
- *
- * Returns `null` after reporting the reason on stderr, same contract as
- * `resolveDbConnection` — never throws for an expected failure.
- */
-export declare function resolveInstance(opts?: ResolveInstanceOptions): Promise<ResolvedInstance | null>;
-/** A service-role client. Bypasses RLS, so setup and teardown only. */
-export declare function adminClient(instance: Instance, schema?: string): DevtoolsClient;
-/**
- * A client signed in with a real email/password, 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. Takes the password explicitly —
- * there is no fixed persona password any more (see `persona.ts` and
- * `moderation.ts`'s `withTemporaryModerator`, both of which generate a fresh
- * random one per account).
- */
-export declare function signedInClient(instance: Instance, email: string, password: string, schema?: string): Promise<DevtoolsClient>;

package/dist/instance.js

@@ -1,102 +0,0 @@
-/**
- * Finding the instance to work against, and signing in to it.
- *
- * `resolveInstance()` is the one entry point every command that needs a
- * Supabase client — `db`'s own commands excepted, which only ever need a
- * Postgres URL — should call. It goes through the SAME session
- * (`resolveDbConnection()`, `db/connection.ts`) `db migrate`/`db reset` do,
- * rather than a local-only `supabase status` probe: every session's env
- * carries `API_URL`/`PUBLISHABLE_KEY`/`SECRET_KEY` alongside `DB_URL` (see
- * `.env.example`), so whichever tier `--tier` named is exactly the instance
- * this resolves to, local Docker included.
- *
- * This replaces `detectLocalInstance()`+`assertMigrated()`, which read
- * `supabase status -o env` directly and therefore only ever found the Docker
- * stack on this machine — the reason `moderation check` and `grant-root`
- * used to be local-only long after `db reset`/`db migrate` moved onto the
- * session system.
- */
-import { createClient } from "@supabase/supabase-js";
-import { resolveDbConnection } from "./db/connection.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 built-in Root role, from `supabase/seed/production/01_roles.sql`. */
-export const ROOT_ROLE_ID = "00000000-0000-0000-0000-000000000002";
-/**
- * Resolves the session's database AND the Supabase client credentials for it.
- *
- * Goes through `resolveDbConnection()` first — the exact check `db
- * migrate`/`db reset` run, including the local-stack-offline and
- * inherited-development-values guards — so a caller here refuses in exactly
- * the same situations and with the same messages those commands already do.
- * What this adds is reading `API_URL`/`PUBLISHABLE_KEY`/`SECRET_KEY` out of
- * the same already-entered session env `DB_URL` came from (see this file's
- * header), rather than shelling out to `supabase status` — which is what
- * makes hosted tiers reachable here at all.
- *
- * Returns `null` after reporting the reason on stderr, same contract as
- * `resolveDbConnection` — never throws for an expected failure.
- */
-export async function resolveInstance(opts = {}) {
-    const label = opts.label ?? "devtools";
-    const connection = await resolveDbConnection({ label: opts.label });
-    if (!connection)
-        return null;
-    const env = opts.env ?? process.env;
-    const apiUrl = env.API_URL;
-    const publishableKey = env.PUBLISHABLE_KEY;
-    const secretKey = env.SECRET_KEY;
-    if (!apiUrl || !publishableKey || !secretKey) {
-        process.stderr.write(`${label}: this session has a DB_URL but no API_URL/PUBLISHABLE_KEY/` +
-            "SECRET_KEY — run `pnpm devtools env pull` for this tier, or " +
-            "`pnpm devtools db start` for the local stack.\n");
-        return null;
-    }
-    return { connection, instance: { apiUrl, publishableKey, secretKey } };
-}
-/** 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 with a real email/password, 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. Takes the password explicitly —
- * there is no fixed persona password any more (see `persona.ts` and
- * `moderation.ts`'s `withTemporaryModerator`, both of which generate a fresh
- * random one per account).
- */
-export async function signedInClient(instance, email, password, schema = "platform") {
-    const client = makeClient(instance.apiUrl, instance.publishableKey, schema);
-    const { error } = await client.auth.signInWithPassword({ email, password });
-    if (error) {
-        throw new Error(`Could not sign in as ${email}: ${error.message}.`);
-    }
-    return client;
-}

package/dist/invocation.d.ts

@@ -1,49 +0,0 @@
-/**
- * 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

@@ -1,78 +0,0 @@
-/**
- * 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

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

package/dist/launch-ci.js

@@ -1,90 +0,0 @@
-/**
- * `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";
-import { captureDevtoolsError, initDevtoolsTelemetry } from "./telemetry.js";
-import { ignoreClosedPipes } from "./pipes.js";
-export async function launchCi(argv) {
-    const { explicit, rest } = stripTierFlag(argv);
-    // See `launch.ts`'s matching call: early, so tier resolution and env entry
-    // are covered too. Same tag `ci.ts`'s `main()` would compute.
-    ignoreClosedPipes();
-    initDevtoolsTelemetry(rest.slice(0, 2).join(" ") || "help");
-    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.
-        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

@@ -1,18 +0,0 @@
-/**
- * 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 (or defers entry to the
- * menu — see this file's header), 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>;

package/dist/menu.d.ts

@@ -1,43 +0,0 @@
-import { type Environment } from "./environment.js";
-/**
- * The command path when argv names a group with subcommands but no subcommand
- * token — what `devtools db` and `devtools db seed` are. Returns null for a
- * leaf command, an unknown token, or a bare invocation (which the no-argument
- * wizard already covers). The caller resumes the wizard at this node when
- * stdin is a TTY; a non-TTY caller keeps the dispatcher's "which of …?" exit.
- */
-export declare function bareGroupStartPath(argv: readonly string[]): string[] | null;
-/**
- * Runs the wizard, returning the `outro()` line its command earned.
- *
- * `dispatch` is the CLI's own argv handler, injected rather than imported so
- * that `cli.ts` keeps a single definition of what each command does and the
- * tests can watch what a walk produces without running it. Its return value
- * passes straight through, the closing line or `null` for a failure already
- * explained, so a command reached from the menu signs off exactly as it does
- * from the command line.
- *
- * `options.startPath`, from `bareGroupStartPath`, skips straight to that
- * node's subcommand screen — see `walk`'s `startPath` branch.
- *
- * The deploy tier is NOT asked here any more. `src/launch.ts` resolves it
- * before `cli.ts` — and therefore this module — is even imported, and
- * exports `DEPLOY_ENV`/`DEV_DB` right away, so by the time the wizard opens
- * `process.env` already names the session exactly as if `--tier` had been
- * typed. Recording it for the "run it directly next time" line only needs to
- * read `process.env.DEPLOY_ENV` back.
- *
- * Entering that tier — loading its `.env.<tier>` file onto `process.env` —
- * is what's deferred: `launch.ts` registers a hook (`env-entry.ts`'s
- * `setMenuEnvHook`) instead of entering up front, so whatever changed while
- * the reader was still walking the menu (the local stack coming up in
- * another terminal, `.env.generated` being rewritten) is picked up rather
- * than missed. `takeMenuEnvHook()` below runs it right before the chosen
- * command dispatches — the ONE place in a menu walk an env value is ever
- * actually read. `undefined` (no hook registered — a typed command entered
- * already, or a test drives `runMenu` directly) just dispatches straight
- * through, unchanged from before this existed.
- */
-export declare function runMenu(dispatch: (argv: string[]) => Promise<string | null>, env?: Environment, options?: {
-    startPath?: string[];
-}): Promise<string | null>;