@devdogsuga/devtools 0.1.0

package/dist/oauth/device.js

@@ -0,0 +1,190 @@
+export class DeviceError extends Error {
+    kind;
+    retryAfterSeconds;
+    constructor(kind, message, retryAfterSeconds) {
+        super(message);
+        this.kind = kind;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "DeviceError";
+    }
+}
+export class PollError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "PollError";
+    }
+}
+function deviceCodeUrl(platformUrl) {
+    return `${platformUrl.replace(/\/+$/, "")}/tools/oauth/device/code`;
+}
+function deviceTokenUrl(platformUrl) {
+    return `${platformUrl.replace(/\/+$/, "")}/tools/oauth/device/token`;
+}
+function retryAfterSecondsFrom(response) {
+    const header = response.headers.get("retry-after");
+    const seconds = header ? Number(header) : undefined;
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
+/**
+ * Requests a device code. Mirrors `exchange.ts`'s `exchangeCode` in shape:
+ * every failure is a distinct `DeviceError` kind, a 429 carries
+ * `Retry-After` when the platform sent one, and a 200 whose body is not
+ * valid JSON or is missing a required field is `malformed` rather than
+ * handing the caller `undefined` fields.
+ */
+export async function requestDeviceCode({ platformUrl, label, callbackUri, fetchImpl = fetch, }) {
+    const url = deviceCodeUrl(platformUrl);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ label, callback_uri: callbackUri }),
+        });
+    }
+    catch (err) {
+        throw new DeviceError("network", `Could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (response.status === 429) {
+        const retryAfterSeconds = retryAfterSecondsFrom(response);
+        throw new DeviceError("rate_limited", `${url} is rate-limited` +
+            (retryAfterSeconds !== undefined ? ` — retry after ${retryAfterSeconds}s.` : "."), retryAfterSeconds);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        throw new DeviceError("malformed", `${url} did not return valid JSON (status ${response.status}).`);
+    }
+    if (!response.ok) {
+        const errBody = (body ?? {});
+        const description = typeof errBody.error_description === "string" ? errBody.error_description : undefined;
+        const code = typeof errBody.error === "string" ? errBody.error : `HTTP ${response.status}`;
+        throw new DeviceError("invalid_request", description ? `${code}: ${description}` : code);
+    }
+    const result = (body ?? {});
+    if (typeof result.device_code !== "string" ||
+        typeof result.user_code !== "string" ||
+        typeof result.verification_uri !== "string" ||
+        typeof result.verification_uri_complete !== "string" ||
+        typeof result.expires_in !== "number" ||
+        typeof result.interval !== "number") {
+        throw new DeviceError("malformed", `${url} returned 200 but was missing a required device-code field.`);
+    }
+    return {
+        deviceCode: result.device_code,
+        userCode: result.user_code,
+        verificationUri: result.verification_uri,
+        verificationUriComplete: result.verification_uri_complete,
+        expiresIn: result.expires_in,
+        interval: result.interval,
+    };
+}
+/** Network failures while polling get this many retries before `pollForToken` gives up. */
+const MAX_NETWORK_RETRIES = 3;
+/** Exponential backoff for a network retry, capped well under the poll interval's own cadence. */
+function networkBackoffSeconds(attempt) {
+    return Math.min(2 ** attempt, 30);
+}
+/**
+ * Polls `.../tools/oauth/device/token` on the server's cadence until the
+ * user approves (or denies) the request in their browser, the device code
+ * expires, or the server rejects it outright.
+ *
+ * `authorization_pending` keeps polling at the current interval;
+ * `slow_down` adds 5 seconds to it and keeps polling (per the wire
+ * contract); a 429 waits out `Retry-After` (or the current interval, if the
+ * platform sent none) and keeps polling; every other error is terminal.
+ * Local expiry (`now() - start >= expiresInSeconds`) is reported the same
+ * way as the server's own `expired_token` — the caller does not need to
+ * tell the two apart.
+ *
+ * A network failure while polling retries with backoff up to
+ * `MAX_NETWORK_RETRIES` times before it is reported as `PollError("network")`.
+ */
+export async function pollForToken({ platformUrl, deviceCode, intervalSeconds, expiresInSeconds, fetchImpl = fetch, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now(), }) {
+    const url = deviceTokenUrl(platformUrl);
+    const deadline = now() + expiresInSeconds * 1000;
+    let interval = intervalSeconds;
+    let networkFailures = 0;
+    // Set only by a branch that already slept its own wait (a network retry's
+    // backoff, or a 429's Retry-After) — skips the ordinary top-of-loop
+    // interval sleep so those waits are not doubled up with it.
+    let skipIntervalSleep = false;
+    while (true) {
+        if (now() >= deadline) {
+            throw new PollError("expired_token", "The device code expired before it was approved. Run the command again.");
+        }
+        if (!skipIntervalSleep)
+            await sleep(interval * 1000);
+        skipIntervalSleep = false;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ device_code: deviceCode }),
+            });
+        }
+        catch (err) {
+            networkFailures += 1;
+            if (networkFailures > MAX_NETWORK_RETRIES) {
+                throw new PollError("network", `Could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            await sleep(networkBackoffSeconds(networkFailures) * 1000);
+            skipIntervalSleep = true;
+            continue;
+        }
+        networkFailures = 0;
+        if (response.status === 429) {
+            const retryAfterSeconds = retryAfterSecondsFrom(response);
+            await sleep((retryAfterSeconds ?? interval) * 1000);
+            skipIntervalSleep = true;
+            continue;
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            throw new PollError("malformed", `${url} did not return valid JSON (status ${response.status}).`);
+        }
+        if (response.ok) {
+            const result = (body ?? {});
+            if (typeof result.client_id !== "string" ||
+                typeof result.client_secret !== "string" ||
+                typeof result.issuer !== "string") {
+                throw new PollError("malformed", `${url} returned 200 but was missing client_id, client_secret, or issuer.`);
+            }
+            return {
+                clientId: result.client_id,
+                clientSecret: result.client_secret,
+                issuer: result.issuer,
+            };
+        }
+        const errBody = (body ?? {});
+        const errorCode = typeof errBody.error === "string" ? errBody.error : undefined;
+        const description = typeof errBody.error_description === "string" ? errBody.error_description : undefined;
+        switch (errorCode) {
+            case "authorization_pending":
+                continue;
+            case "slow_down":
+                interval += 5;
+                continue;
+            case "access_denied":
+                throw new PollError("access_denied", description ?? "Connection declined in the browser.");
+            case "expired_token":
+                throw new PollError("expired_token", description ?? "The device code expired. Run the command again.");
+            case "invalid_grant":
+                throw new PollError("invalid_grant", description ?? "invalid_grant");
+            case "invalid_request":
+            default: {
+                const code = errorCode ?? `HTTP ${response.status}`;
+                throw new PollError("invalid_request", description ? `${code}: ${description}` : code);
+            }
+        }
+    }
+}

package/dist/oauth/discovery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OIDC discovery for the DevDogs OAuth server.
+ *
+ * The wizard used to build the issuer it registered with Supabase as
+ * `${baseUrl}/auth/v1` — an assumption, not a fact. Supabase Auth's own
+ * discovery document at that same base advertises a DIFFERENT issuer (its
+ * project ref host, e.g. `https://<ref>.supabase.co/auth/v1`, rather than
+ * the custom domain a caller reaches it through), and Supabase's OIDC
+ * provider refuses to register a custom provider whose declared issuer
+ * disagrees with what discovery reports for it. Reading the issuer FROM
+ * discovery, rather than constructing it, keeps this correct regardless of
+ * which host the platform's own discovery document happens to advertise —
+ * including once the platform starts advertising its custom domain instead
+ * of the underlying project host.
+ */
+/** Thrown when discovery cannot be fetched or does not shape up as expected. */
+export declare class DiscoveryError extends Error {
+}
+/**
+ * Fetches `${baseUrl}/auth/v1/.well-known/openid-configuration` and returns
+ * the `issuer` it advertises.
+ *
+ * Every failure names the discovery URL it was trying to reach — a network
+ * failure, a non-2xx response, unparsable JSON, and a missing/non-string
+ * `issuer` field are each reported distinctly, so the wizard can print
+ * something more useful than "fetch failed".
+ */
+export declare function fetchIssuer(baseUrl: string): Promise<string>;

package/dist/oauth/discovery.js

@@ -0,0 +1,54 @@
+/**
+ * OIDC discovery for the DevDogs OAuth server.
+ *
+ * The wizard used to build the issuer it registered with Supabase as
+ * `${baseUrl}/auth/v1` — an assumption, not a fact. Supabase Auth's own
+ * discovery document at that same base advertises a DIFFERENT issuer (its
+ * project ref host, e.g. `https://<ref>.supabase.co/auth/v1`, rather than
+ * the custom domain a caller reaches it through), and Supabase's OIDC
+ * provider refuses to register a custom provider whose declared issuer
+ * disagrees with what discovery reports for it. Reading the issuer FROM
+ * discovery, rather than constructing it, keeps this correct regardless of
+ * which host the platform's own discovery document happens to advertise —
+ * including once the platform starts advertising its custom domain instead
+ * of the underlying project host.
+ */
+/** Thrown when discovery cannot be fetched or does not shape up as expected. */
+export class DiscoveryError extends Error {
+}
+/**
+ * Fetches `${baseUrl}/auth/v1/.well-known/openid-configuration` and returns
+ * the `issuer` it advertises.
+ *
+ * Every failure names the discovery URL it was trying to reach — a network
+ * failure, a non-2xx response, unparsable JSON, and a missing/non-string
+ * `issuer` field are each reported distinctly, so the wizard can print
+ * something more useful than "fetch failed".
+ */
+export async function fetchIssuer(baseUrl) {
+    const discoveryUrl = `${baseUrl}/auth/v1/.well-known/openid-configuration`;
+    let response;
+    try {
+        response = await fetch(discoveryUrl);
+    }
+    catch (err) {
+        throw new DiscoveryError(`Could not reach ${discoveryUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!response.ok) {
+        throw new DiscoveryError(`${discoveryUrl} returned ${response.status} ${response.statusText}`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        throw new DiscoveryError(`${discoveryUrl} did not return valid JSON`);
+    }
+    const issuer = body && typeof body === "object"
+        ? body.issuer
+        : undefined;
+    if (typeof issuer !== "string" || issuer.length === 0) {
+        throw new DiscoveryError(`${discoveryUrl} response had no "issuer" field`);
+    }
+    return issuer;
+}

package/dist/oauth/env-file.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Writes `values` into `.env.local` in `cwd`, updating any existing
+ * `KEY=...` lines in place and appending keys that aren't present yet.
+ * Leaves all other lines (comments, unrelated vars) untouched.
+ */
+export declare function upsertEnvLocal(cwd: string, values: Record<string, string>): void;

package/dist/oauth/env-file.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Writes `values` into `.env.local` in `cwd`, updating any existing
+ * `KEY=...` lines in place and appending keys that aren't present yet.
+ * Leaves all other lines (comments, unrelated vars) untouched.
+ */
+export function upsertEnvLocal(cwd, values) {
+    const path = join(cwd, ".env.local");
+    const existing = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    const lines = existing.length > 0 ? existing.split("\n") : [];
+    const remaining = new Map(Object.entries(values));
+    const updated = lines.map((line) => {
+        const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(line);
+        if (!match)
+            return line;
+        // The regex has exactly one capture group, so a match always fills it;
+        // noUncheckedIndexedAccess can't see that, hence the explicit guard.
+        const key = match[1];
+        if (key === undefined)
+            return line;
+        const value = remaining.get(key);
+        if (value === undefined)
+            return line;
+        remaining.delete(key);
+        return `${key}=${formatValue(value)}`;
+    });
+    for (const [key, value] of remaining) {
+        updated.push(`${key}=${formatValue(value)}`);
+    }
+    writeFileSync(path, `${updated.join("\n").replace(/\n*$/, "")}\n`);
+}
+function formatValue(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}

package/dist/oauth/exchange.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The token exchange half of the one-click connect flow: trades the
+ * authorization `code` the loopback listener caught, plus the PKCE
+ * verifier that matches the challenge sent up front, for the OAuth client
+ * credentials the platform minted — see `commands.ts`'s `oauth` node and
+ * this repo's launch instructions for the full wire contract this speaks:
+ *
+ *   POST <platform>/tools/oauth/connect/exchange
+ *   { "code", "code_verifier" }
+ *
+ *   200 { "client_id", "client_secret", "issuer" }
+ *   400 { "error": "invalid_request" | "invalid_grant", "error_description" }
+ *   429 { "error": "rate_limited" }  (+ Retry-After header)
+ */
+export type ExchangeErrorKind = "invalid_request" | "invalid_grant" | "rate_limited" | "network" | "malformed";
+export declare class ExchangeError extends Error {
+    readonly kind: ExchangeErrorKind;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(kind: ExchangeErrorKind, message: string, retryAfterSeconds?: number | undefined);
+}
+export interface ExchangeResult {
+    clientId: string;
+    clientSecret: string;
+    issuer: string;
+}
+/**
+ * Exchanges `code` + `codeVerifier` for OAuth client credentials.
+ *
+ * Every failure is a distinct `ExchangeError` kind so the caller (the
+ * wizard) can print something specific rather than a bare "request
+ * failed": a network failure names the URL and underlying error, a 429
+ * carries `Retry-After` when the platform sent one, a 400 distinguishes
+ * `invalid_grant` (the code was wrong, expired, or already used — the
+ * ordinary "try the flow again" case) from any other `invalid_request`, and
+ * a 200 with a body that is not valid JSON or is missing a required field
+ * is reported as `malformed` rather than silently returning `undefined`
+ * fields to the caller.
+ */
+export declare function exchangeCode({ platformUrl, code, codeVerifier, }: {
+    platformUrl: string;
+    code: string;
+    codeVerifier: string;
+}): Promise<ExchangeResult>;

package/dist/oauth/exchange.js

@@ -0,0 +1,87 @@
+/**
+ * The token exchange half of the one-click connect flow: trades the
+ * authorization `code` the loopback listener caught, plus the PKCE
+ * verifier that matches the challenge sent up front, for the OAuth client
+ * credentials the platform minted — see `commands.ts`'s `oauth` node and
+ * this repo's launch instructions for the full wire contract this speaks:
+ *
+ *   POST <platform>/tools/oauth/connect/exchange
+ *   { "code", "code_verifier" }
+ *
+ *   200 { "client_id", "client_secret", "issuer" }
+ *   400 { "error": "invalid_request" | "invalid_grant", "error_description" }
+ *   429 { "error": "rate_limited" }  (+ Retry-After header)
+ */
+export class ExchangeError extends Error {
+    kind;
+    retryAfterSeconds;
+    constructor(kind, message, retryAfterSeconds) {
+        super(message);
+        this.kind = kind;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "ExchangeError";
+    }
+}
+function exchangeUrl(platformUrl) {
+    return `${platformUrl.replace(/\/+$/, "")}/tools/oauth/connect/exchange`;
+}
+/**
+ * Exchanges `code` + `codeVerifier` for OAuth client credentials.
+ *
+ * Every failure is a distinct `ExchangeError` kind so the caller (the
+ * wizard) can print something specific rather than a bare "request
+ * failed": a network failure names the URL and underlying error, a 429
+ * carries `Retry-After` when the platform sent one, a 400 distinguishes
+ * `invalid_grant` (the code was wrong, expired, or already used — the
+ * ordinary "try the flow again" case) from any other `invalid_request`, and
+ * a 200 with a body that is not valid JSON or is missing a required field
+ * is reported as `malformed` rather than silently returning `undefined`
+ * fields to the caller.
+ */
+export async function exchangeCode({ platformUrl, code, codeVerifier, }) {
+    const url = exchangeUrl(platformUrl);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ code, code_verifier: codeVerifier }),
+        });
+    }
+    catch (err) {
+        throw new ExchangeError("network", `Could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (response.status === 429) {
+        const retryAfterHeader = response.headers.get("retry-after");
+        const retryAfterSeconds = retryAfterHeader ? Number(retryAfterHeader) : undefined;
+        throw new ExchangeError("rate_limited", `${url} is rate-limited` +
+            (Number.isFinite(retryAfterSeconds)
+                ? ` — retry after ${retryAfterSeconds}s.`
+                : "."), Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        throw new ExchangeError("malformed", `${url} did not return valid JSON (status ${response.status}).`);
+    }
+    if (!response.ok) {
+        const errBody = (body ?? {});
+        const kind = errBody.error === "invalid_grant" ? "invalid_grant" : "invalid_request";
+        const description = typeof errBody.error_description === "string" ? errBody.error_description : undefined;
+        const code = typeof errBody.error === "string" ? errBody.error : `HTTP ${response.status}`;
+        throw new ExchangeError(kind, description ? `${code}: ${description}` : code);
+    }
+    const result = (body ?? {});
+    if (typeof result.client_id !== "string" ||
+        typeof result.client_secret !== "string" ||
+        typeof result.issuer !== "string") {
+        throw new ExchangeError("malformed", `${url} returned 200 but was missing client_id, client_secret, or issuer.`);
+    }
+    return {
+        clientId: result.client_id,
+        clientSecret: result.client_secret,
+        issuer: result.issuer,
+    };
+}

package/dist/oauth/label.d.ts

@@ -0,0 +1 @@
+export declare function defaultLabel(cwd: string): string;

package/dist/oauth/label.js

@@ -0,0 +1,25 @@
+/**
+ * The connect flow's default `label` — what a contributor sees on the
+ * platform's approval page naming which project is asking to connect.
+ * `package.json`'s own `name` wins when present (it is the more deliberate
+ * answer — someone typed it into a manifest); the working directory's own
+ * name is the fallback for a project with no `package.json` at all, or one
+ * that failed to parse.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+export function defaultLabel(cwd) {
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.name === "string" && pkg.name.trim() !== "") {
+                return pkg.name.trim();
+            }
+        }
+        catch {
+            // Falls through to the directory name below.
+        }
+    }
+    return basename(cwd);
+}

package/dist/oauth/loopback.d.ts

@@ -0,0 +1,52 @@
+/** Default: as long as this repo's OAuth wizard reasonably keeps a browser tab open unattended. */
+export declare const DEFAULT_CALLBACK_TIMEOUT_MS: number;
+/** A successful `?code=...&state=...` callback. */
+export interface CallbackSuccess {
+    code: string;
+    state: string;
+}
+/** The platform denied the request, or reported some other OAuth `error=`. */
+export declare class CallbackDeniedError extends Error {
+    readonly errorCode: string;
+    readonly state: string | undefined;
+    constructor(errorCode: string, state: string | undefined, description?: string);
+}
+/** No callback arrived within the timeout — the browser was never opened, or the tab was abandoned. */
+export declare class CallbackTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/** The callback hit `/callback` but had neither `code` nor `error` — not a shape this flow expects. */
+export declare class CallbackMalformedError extends Error {
+    constructor();
+}
+/**
+ * The callback's `state` did not match the one this run generated (see
+ * `pkce.ts`'s `generateState`) — the defining CSRF defense of this whole
+ * flow. Any mismatch is treated the same regardless of cause (a stale tab
+ * from a previous run, a forged callback, or a bug): refuse and say so,
+ * never silently proceed with the wrong request.
+ */
+export declare class StateMismatchError extends Error {
+    constructor();
+}
+/** Throws `StateMismatchError` unless `callback.state` matches `expected`; returns `callback` unchanged otherwise. */
+export declare function verifyState(expected: string, callback: CallbackSuccess): CallbackSuccess;
+export interface LoopbackListener {
+    /** The port `listen(0, ...)` picked. */
+    port: number;
+    /** `http://127.0.0.1:<port>/callback` — pass this as the connect URL's `redirect_uri`. */
+    redirectUri: string;
+    /** Resolves on a successful callback; rejects on denial, malformed callback, or timeout. Always settles exactly once. */
+    result: Promise<CallbackSuccess>;
+    /** Closes the listener immediately. Safe to call more than once, and safe to call after `result` has already settled. */
+    close: () => void;
+}
+/**
+ * Starts the listener and resolves once it is actually accepting
+ * connections (i.e. once the real port is known). `result` is the separate
+ * promise that settles once a callback (or the timeout) has been handled —
+ * most callers `await start(...)` once, then `await listener.result`.
+ */
+export declare function start(opts?: {
+    timeoutMs?: number;
+}): Promise<LoopbackListener>;