neonctl 2.37.1 → 2.38.1

package/dist/utils/inspect_db.js

@@ -1,153 +0,0 @@
-import { parseConnectionUri } from "../psql/index.js";
-import { PgConnection } from "../psql/wire/connection.js";
-import { EndpointType } from "./api_enums.js";
-import { branchIdFromProps } from "./enrichers.js";
-import { parsePITBranch } from "./point_in_time.js";
-export const SSL_MODES = [
-    "require",
-    "verify-ca",
-    "verify-full",
-    "omit",
-];
-/**
- * Resolve a branch's live Postgres connection details via the Neon API
- * (endpoint → role → password → database → URL, honoring point-in-time,
- * pooling, prisma tuning, and SSL mode). Mirrors how `connection-string`
- * resolves a branch so `inspect db` connects the same way.
- */
-export const resolveConnectionUri = async (props) => {
-    const projectId = props.projectId;
-    const parsedPIT = props.branch
-        ? parsePITBranch(props.branch)
-        : { tag: "head", branch: "" };
-    if (props.branch) {
-        props.branch = parsedPIT.branch;
-    }
-    const branchId = await branchIdFromProps(props);
-    const { data: { endpoints }, } = await props.apiClient.listProjectBranchEndpoints(projectId, branchId);
-    const matchEndpointType = props.endpointType ?? EndpointType.ReadWrite;
-    let endpoint = endpoints.find((e) => e.type === matchEndpointType);
-    if (!endpoint && props.endpointType == null) {
-        endpoint = endpoints[0];
-    }
-    if (!endpoint) {
-        throw new Error(`No ${props.endpointType ?? ""} endpoint found for the branch: ${branchId}`);
-    }
-    const role = props.roleName ||
-        (await props.apiClient
-            .listProjectBranchRoles(projectId, branchId)
-            .then(({ data }) => {
-            if (data.roles.length === 0) {
-                throw new Error(`No roles found for the branch: ${branchId}`);
-            }
-            if (data.roles.length === 1) {
-                return data.roles[0].name;
-            }
-            throw new Error(`Multiple roles found for the branch, please provide one with the --role-name option: ${data.roles
-                .map((r) => r.name)
-                .join(", ")}`);
-        }));
-    const { data: { databases: branchDatabases }, } = await props.apiClient.listProjectBranchDatabases(projectId, branchId);
-    const database = props.databaseName ||
-        (() => {
-            if (branchDatabases.length === 0) {
-                throw new Error(`No databases found for the branch: ${branchId}`);
-            }
-            if (branchDatabases.length === 1) {
-                return branchDatabases[0].name;
-            }
-            throw new Error(`Multiple databases found for the branch, please provide one with the --database-name option: ${branchDatabases
-                .map((d) => d.name)
-                .join(", ")}`);
-        })();
-    if (!branchDatabases.find((d) => d.name === database)) {
-        throw new Error(`Database not found: ${database}`);
-    }
-    const { data: { password }, } = await props.apiClient.getProjectBranchRolePassword(props.projectId, endpoint.branch_id, role);
-    let host = props.pooled
-        ? endpoint.host.replace(endpoint.id, `${endpoint.id}-pooler`)
-        : endpoint.host;
-    if (parsedPIT.tag !== "head") {
-        host = endpoint.host.replace(endpoint.id, endpoint.branch_id);
-    }
-    const connectionString = new URL(`postgresql://${host}`);
-    connectionString.pathname = database;
-    connectionString.username = role;
-    connectionString.password = password;
-    if (props.prisma) {
-        connectionString.searchParams.set("connect_timeout", "30");
-        if (props.pooled) {
-            connectionString.searchParams.set("pool_timeout", "30");
-            connectionString.searchParams.set("pgbouncer", "true");
-        }
-    }
-    const ssl = props.ssl ?? "require";
-    if (ssl !== "omit") {
-        connectionString.searchParams.set("sslmode", ssl);
-        connectionString.searchParams.set("channel_binding", "require");
-    }
-    if (parsedPIT.tag === "lsn") {
-        connectionString.searchParams.set("options", `neon_lsn:${parsedPIT.lsn}`);
-    }
-    else if (parsedPIT.tag === "timestamp") {
-        connectionString.searchParams.set("options", `neon_timestamp:${parsedPIT.timestamp}`);
-    }
-    return {
-        connectionUri: connectionString.toString(),
-        host,
-        role,
-        password,
-        database,
-        options: connectionString.searchParams.toString(),
-    };
-};
-const rowsFrom = (result) => {
-    const names = result.fields.map((f) => f.name);
-    return result.rows.map((row) => {
-        const obj = {};
-        names.forEach((name, i) => {
-            obj[name] = row[i];
-        });
-        return obj;
-    });
-};
-/**
- * Connect to `connectionUri` with the embedded wire client, run a single
- * read-only `sql`, and return the rows as objects keyed by column name (so the
- * shared `writer` can render them by field). The connection is always closed,
- * even on error.
- */
-export const runInspectQuery = async (connectionUri, sql, options = {}) => {
-    const opts = parseConnectionUri(connectionUri);
-    let connection;
-    try {
-        connection = await PgConnection.connect(opts);
-    }
-    catch (err) {
-        // Give the failure a Postgres-specific message. The raw socket error
-        // (e.g. ECONNREFUSED) would otherwise be mislabeled by the top-level
-        // `isNetworkError` handler as a "Could not reach the Neon API" hint —
-        // misleading for `inspect db`, which talks to Postgres, not the API.
-        // We intentionally do not chain `cause` so that classifier can't match
-        // the socket `code`; the underlying reason is preserved in the message.
-        const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`Could not connect to Postgres at ${opts.host}:${opts.port}: ${reason}`);
-    }
-    try {
-        const ext = options.requiresExtension;
-        if (ext) {
-            // `ext` is an internal constant from INSPECT_QUERIES, never user input,
-            // so interpolating it into the literal is safe.
-            const check = await connection.query(`SELECT 1 FROM pg_extension WHERE extname = '${ext}';`);
-            if (check.rows.length === 0) {
-                throw new Error(`This query needs the "${ext}" extension, which is not installed. ` +
-                    `Enable it with: CREATE EXTENSION ${ext};`);
-            }
-        }
-        const result = await connection.query(sql);
-        return rowsFrom(result);
-    }
-    finally {
-        await connection.close();
-    }
-};

package/dist/utils/inspect_queries.js

@@ -1,372 +0,0 @@
-/**
- * Diagnostic SQL for `neon inspect db`. Each entry is a read-only query against
- * Postgres' own statistics/catalog views plus the output columns (in display
- * order) the table/json/yaml formatter should show.
- *
- * Most queries need no extra extension. The few that do (currently `outliers`
- * and `calls`, which read `pg_stat_statements`) declare it via
- * `requiresExtension`; the runner checks for it and fails with an actionable
- * hint when it's missing.
- */
-export const INSPECT_QUERIES = {
-    "table-sizes": {
-        describe: "Size of each table (including TOAST), largest first (pg_table_size)",
-        fields: ["schema", "name", "size"],
-        emptyMessage: "No user tables found.",
-        sql: /* sql */ `
-			SELECT
-				n.nspname AS schema,
-				c.relname AS name,
-				pg_size_pretty(pg_table_size(c.oid)) AS size
-			FROM pg_class c
-			LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
-			WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
-				AND n.nspname !~ '^pg_toast'
-				AND c.relkind = 'r'
-			ORDER BY pg_table_size(c.oid) DESC;
-		`,
-    },
-    "index-sizes": {
-        describe: "Size of each index, largest first (pg_relation_size)",
-        fields: ["schema", "name", "size"],
-        emptyMessage: "No indexes found.",
-        sql: /* sql */ `
-			SELECT
-				n.nspname AS schema,
-				c.relname AS name,
-				pg_size_pretty(pg_relation_size(c.oid)) AS size
-			FROM pg_class c
-			LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
-			WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
-				AND n.nspname !~ '^pg_toast'
-				AND c.relkind = 'i'
-			ORDER BY pg_relation_size(c.oid) DESC;
-		`,
-    },
-    "unused-indexes": {
-        describe: "Non-unique indexes with few scans — candidates for removal (pg_stat_user_indexes)",
-        fields: ["table", "index", "index_size", "index_scans"],
-        emptyMessage: "No unused indexes detected.",
-        sql: /* sql */ `
-			SELECT
-				s.schemaname || '.' || s.relname AS "table",
-				s.indexrelname AS index,
-				pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size,
-				s.idx_scan AS index_scans
-			FROM pg_stat_user_indexes s
-			JOIN pg_index i ON i.indexrelid = s.indexrelid
-			WHERE NOT i.indisunique
-				AND NOT i.indisprimary
-				AND s.idx_scan < 50
-			ORDER BY pg_relation_size(s.indexrelid) DESC, s.idx_scan ASC;
-		`,
-    },
-    "seq-scans": {
-        describe: "Number of sequential scans recorded against each table (pg_stat_user_tables)",
-        fields: ["schema", "name", "count"],
-        emptyMessage: "No user tables found.",
-        sql: /* sql */ `
-			SELECT
-				schemaname AS schema,
-				relname AS name,
-				seq_scan AS count
-			FROM pg_stat_user_tables
-			ORDER BY seq_scan DESC;
-		`,
-    },
-    "long-running-queries": {
-        describe: "Queries running longer than 5 minutes (pg_stat_activity)",
-        fields: ["pid", "duration", "state", "query"],
-        emptyMessage: "No long-running queries.",
-        sql: /* sql */ `
-			SELECT
-				pid,
-				(now() - query_start)::text AS duration,
-				state,
-				query
-			FROM pg_stat_activity
-			WHERE state <> 'idle'
-				AND query NOT ILIKE '%pg_stat_activity%'
-				AND now() - query_start > interval '5 minutes'
-			ORDER BY now() - query_start DESC;
-		`,
-    },
-    locks: {
-        describe: "Locks held with the acquiring query and its age (pg_locks + pg_stat_activity)",
-        fields: [
-            "pid",
-            "relname",
-            "mode",
-            "locktype",
-            "granted",
-            "age",
-            "query",
-        ],
-        emptyMessage: "No locks held.",
-        sql: /* sql */ `
-			SELECT
-				a.pid,
-				c.relname,
-				l.mode,
-				l.locktype,
-				l.granted,
-				(now() - a.query_start)::text AS age,
-				a.query
-			FROM pg_locks l
-			JOIN pg_stat_activity a ON a.pid = l.pid
-			LEFT JOIN pg_class c ON c.oid = l.relation
-			WHERE a.query <> '<insufficient privilege>'
-				AND l.pid <> pg_backend_pid()
-			ORDER BY a.query_start;
-		`,
-    },
-    outliers: {
-        describe: "Queries taking the most cumulative execution time (needs pg_stat_statements)",
-        fields: ["total_exec_time", "prop_exec_time", "ncalls", "query"],
-        emptyMessage: "No statements recorded yet.",
-        requiresExtension: "pg_stat_statements",
-        sql: /* sql */ `
-			SELECT
-				(interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
-				to_char(
-					(total_exec_time / nullif(sum(total_exec_time) OVER (), 0)) * 100,
-					'FM990D0'
-				) || '%' AS prop_exec_time,
-				calls AS ncalls,
-				query
-			FROM pg_stat_statements s
-			JOIN pg_database d ON d.oid = s.dbid
-			WHERE d.datname = current_database()
-			ORDER BY total_exec_time DESC
-			LIMIT 25;
-		`,
-    },
-    calls: {
-        describe: "Most frequently called queries (needs pg_stat_statements)",
-        fields: ["ncalls", "total_exec_time", "prop_exec_time", "query"],
-        emptyMessage: "No statements recorded yet.",
-        requiresExtension: "pg_stat_statements",
-        sql: /* sql */ `
-			SELECT
-				calls AS ncalls,
-				(interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
-				to_char(
-					(calls / nullif(sum(calls) OVER (), 0)::float) * 100,
-					'FM990D0'
-				) || '%' AS prop_exec_time,
-				query
-			FROM pg_stat_statements s
-			JOIN pg_database d ON d.oid = s.dbid
-			WHERE d.datname = current_database()
-			ORDER BY calls DESC
-			LIMIT 25;
-		`,
-    },
-    "lfc-hit-rate": {
-        describe: "Local File Cache hit rate (needs neon extension)",
-        fields: ["name", "ratio"],
-        emptyMessage: "No LFC stats available.",
-        requiresExtension: "neon",
-        // Read the hit/miss counters from neon_get_lfc_stats() rather than the
-        // neon_lfc_stats / neon_stat_file_cache views: those views are owned by
-        // cloud_admin and are not always readable by end-user roles, whereas the
-        // function is EXECUTE-able by the default role.
-        sql: /* sql */ `
-			WITH lfc AS (
-				SELECT lfc_key AS k, lfc_value AS v
-				FROM neon_get_lfc_stats() t(lfc_key text, lfc_value bigint)
-			)
-			SELECT
-				'lfc hit rate' AS name,
-				max(v) FILTER (WHERE k = 'file_cache_hits')::float
-					/ nullif(
-						max(v) FILTER (WHERE k = 'file_cache_hits')
-						+ max(v) FILTER (WHERE k = 'file_cache_misses'),
-						0
-					) AS ratio
-			FROM lfc;
-		`,
-    },
-    "working-set": {
-        describe: "Estimated working set vs LFC size (needs neon extension)",
-        fields: ["window", "working_set", "lfc_size", "exceeds_lfc"],
-        emptyMessage: "No working-set estimate available.",
-        requiresExtension: "neon",
-        sql: /* sql */ `
-			SELECT
-				w.window,
-				pg_size_pretty(w.working_set_bytes) AS working_set,
-				pg_size_pretty(pg_size_bytes(current_setting('neon.file_cache_size_limit'))) AS lfc_size,
-				CASE
-					WHEN w.working_set_bytes
-						> pg_size_bytes(current_setting('neon.file_cache_size_limit'))
-					THEN 'yes' ELSE 'no'
-				END AS exceeds_lfc
-			FROM (
-				SELECT
-					x AS window,
-					approximate_working_set_size_seconds(
-						extract('epoch' from x::interval)::int
-					)::bigint * 8192 AS working_set_bytes
-				FROM (VALUES ('1m'), ('5m'), ('15m'), ('1h')) AS t(x)
-			) w
-			ORDER BY working_set_bytes;
-		`,
-    },
-    "vacuum-stats": {
-        describe: "Autovacuum status per table: last (auto)vacuum, dead tuples, threshold",
-        fields: [
-            "schema",
-            "table",
-            "last_vacuum",
-            "last_autovacuum",
-            "rowcount",
-            "dead_rowcount",
-            "expect_autovacuum",
-        ],
-        emptyMessage: "No user tables found.",
-        sql: /* sql */ `
-			SELECT
-				n.nspname AS schema,
-				c.relname AS "table",
-				to_char(psut.last_vacuum, 'YYYY-MM-DD HH24:MI') AS last_vacuum,
-				to_char(psut.last_autovacuum, 'YYYY-MM-DD HH24:MI') AS last_autovacuum,
-				c.reltuples::bigint AS rowcount,
-				psut.n_dead_tup AS dead_rowcount,
-				CASE
-					WHEN current_setting('autovacuum_vacuum_threshold')::bigint
-						+ current_setting('autovacuum_vacuum_scale_factor')::numeric
-							* c.reltuples
-						< psut.n_dead_tup
-					THEN 'yes'
-					ELSE 'no'
-				END AS expect_autovacuum
-			FROM pg_stat_user_tables psut
-			JOIN pg_class c ON psut.relid = c.oid
-			JOIN pg_namespace n ON c.relnamespace = n.oid
-			ORDER BY psut.n_dead_tup DESC;
-		`,
-    },
-    bloat: {
-        describe: "Estimated table/index bloat (statistical estimate, no extension needed)",
-        fields: ["type", "schema", "object_name", "bloat", "waste"],
-        emptyMessage: "No bloat estimate available.",
-        sql: /* sql */ `
-			WITH constants AS (
-				SELECT current_setting('block_size')::numeric AS bs, 23 AS hdr, 8 AS ma
-			),
-			bloat_info AS (
-				SELECT
-					ma, bs, schemaname, tablename,
-					(datawidth + (hdr + ma - (CASE WHEN hdr % ma = 0 THEN ma ELSE hdr % ma END)))::numeric AS datahdr,
-					(maxfracsum * (nullhdr + ma - (CASE WHEN nullhdr % ma = 0 THEN ma ELSE nullhdr % ma END))) AS nullhdr2
-				FROM (
-					SELECT
-						schemaname, tablename, hdr, ma, bs,
-						SUM((1 - null_frac) * avg_width) AS datawidth,
-						MAX(null_frac) AS maxfracsum,
-						hdr + (
-							SELECT 1 + count(*) / 8
-							FROM pg_stats s2
-							WHERE null_frac <> 0
-								AND s2.schemaname = s.schemaname
-								AND s2.tablename = s.tablename
-						) AS nullhdr
-					FROM pg_stats s, constants
-					GROUP BY 1, 2, 3, 4, 5
-				) AS foo
-			),
-			table_bloat AS (
-				SELECT
-					schemaname, tablename, cc.relpages, bs,
-					CEIL((cc.reltuples * ((datahdr + ma
-						- (CASE WHEN datahdr % ma = 0 THEN ma ELSE datahdr % ma END))
-						+ nullhdr2 + 4)) / (bs - 20::float)) AS otta
-				FROM bloat_info
-				JOIN pg_class cc ON cc.relname = bloat_info.tablename
-				JOIN pg_namespace nn ON cc.relnamespace = nn.oid
-					AND nn.nspname = bloat_info.schemaname
-					AND nn.nspname NOT IN ('information_schema', 'pg_catalog')
-				WHERE cc.relkind = 'r'
-			)
-			SELECT
-				'table' AS type,
-				schemaname AS schema,
-				tablename AS object_name,
-				round(CASE WHEN otta = 0 THEN 0.0 ELSE relpages::numeric / otta::numeric END, 1) AS bloat,
-				pg_size_pretty(
-					(CASE WHEN relpages < otta THEN 0 ELSE (bs * (relpages - otta))::bigint END)
-				) AS waste
-			FROM table_bloat
-			ORDER BY (CASE WHEN relpages < otta THEN 0 ELSE bs * (relpages - otta) END) DESC
-			LIMIT 25;
-		`,
-    },
-    "replication-slots": {
-        describe: "Replication slots: kind, status, client, restart/confirmed-flush LSNs, and lag (pg_replication_slots + pg_stat_replication)",
-        fields: [
-            "slot_name",
-            "slot_type",
-            "slot_kind",
-            "status",
-            "client_addr",
-            "restart_lsn",
-            "confirmed_flush_lsn",
-            "replication_lag",
-        ],
-        emptyMessage: "No replication slots found.",
-        sql: /* sql */ `
-			SELECT
-				s.slot_name,
-				s.slot_type,
-				CASE
-					WHEN s.slot_type = 'physical' THEN 'physical'
-					WHEN s.slot_name LIKE 'pg_%_sync_%' THEN 'initial-sync (tablesync)'
-					WHEN s.slot_type = 'logical' THEN 'CDC (apply)'
-					ELSE 'other'
-				END AS slot_kind,
-				CASE
-					WHEN r.state IS NOT NULL THEN r.state
-					WHEN s.active THEN 'active (no walsender)'
-					ELSE 'inactive'
-				END AS status,
-				r.client_addr,
-				s.restart_lsn,
-				s.confirmed_flush_lsn,
-				pg_size_pretty(
-					pg_wal_lsn_diff(
-						CASE
-							WHEN pg_is_in_recovery() THEN pg_last_wal_receive_lsn()
-							ELSE pg_current_wal_lsn()
-						END,
-						COALESCE(s.confirmed_flush_lsn, s.restart_lsn)
-					)
-				) AS replication_lag
-			FROM pg_replication_slots s
-			LEFT JOIN pg_stat_replication r ON r.pid = s.active_pid
-			ORDER BY s.slot_name;
-		`,
-    },
-    subscriptions: {
-        describe: "Per-table logical replication progress on this subscriber (pg_subscription_rel)",
-        fields: ["subscription", "table_name", "status", "lsn"],
-        emptyMessage: "No subscriptions found on this database.",
-        sql: /* sql */ `
-			SELECT
-				sub.subname AS subscription,
-				sr.srrelid::regclass::text AS table_name,
-				CASE sr.srsubstate
-					WHEN 'i' THEN 'initialize'
-					WHEN 'd' THEN 'data being copied'
-					WHEN 'f' THEN 'finished table copy'
-					WHEN 's' THEN 'synchronized'
-					WHEN 'r' THEN 'ready'
-					ELSE sr.srsubstate::text
-				END AS status,
-				sr.srsublsn AS lsn
-			FROM pg_subscription_rel sr
-			JOIN pg_subscription sub ON sub.oid = sr.srsubid
-			ORDER BY sub.subname, table_name;
-		`,
-    },
-};

package/dist/utils/middlewares.js

@@ -1,20 +0,0 @@
-/**
- * This middleware is needed to fill in the args for nested objects,
- * so that required arguments would work
- * otherwise yargs just throws an error
- */
-export const fillInArgs = (args, currentArgs = args, acc = []) => {
-    Object.entries(currentArgs).forEach(([k, v]) => {
-        if (k === "_" || k === "--") {
-            return;
-        }
-        // check if the value is an Object
-        if (typeof v === "object" && v !== null) {
-            fillInArgs(args, v, [...acc, k]);
-        }
-        else if (acc.length > 0) {
-            // if it's not an object, and we have a path, fill it in
-            args[acc.join(".") + "." + k] = v;
-        }
-    });
-};

package/dist/utils/openapi.js

@@ -1,114 +0,0 @@
-// Lightweight loader for the Neon OpenAPI spec, used by `neon api --list` to
-// enumerate the available routes. The `neon api <path>` request path does NOT
-// depend on this module — it is a pure passthrough — so a stale or unreachable
-// spec never blocks a real API call. Listing degrades gracefully: fresh cache →
-// live fetch → stale cache → clear error.
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { log } from "../log.js";
-/** Public URL of the released Neon OpenAPI v2 spec. */
-export const DEFAULT_SPEC_URL = "https://neon.com/api_spec/release/v2.json";
-const CACHE_FILE = "openapi-spec.json";
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-const FETCH_TIMEOUT_MS = 10000;
-const HTTP_METHODS = new Set([
-    "get",
-    "post",
-    "put",
-    "patch",
-    "delete",
-    "head",
-    "options",
-]);
-async function fetchSpec(url) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => {
-        controller.abort();
-    }, FETCH_TIMEOUT_MS);
-    try {
-        const res = await fetch(url, {
-            signal: controller.signal,
-            headers: { Accept: "application/json" },
-        });
-        if (!res.ok) {
-            throw new Error(`Failed to fetch OpenAPI spec (${res.status} ${res.statusText})`);
-        }
-        return (await res.json());
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-function readCache(cachePath) {
-    try {
-        return JSON.parse(readFileSync(cachePath, "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
-function writeCache(cachePath, data) {
-    try {
-        mkdirSync(dirname(cachePath), { recursive: true });
-        writeFileSync(cachePath, JSON.stringify(data));
-    }
-    catch (err) {
-        log.debug("Failed to cache OpenAPI spec: %s", err);
-    }
-}
-/**
- * Load the Neon OpenAPI spec, preferring a fresh on-disk cache, then a live
- * fetch (which refreshes the cache), then a stale cache as a last resort.
- * Returns `null` when no spec can be obtained.
- */
-export async function loadSpec(opts) {
-    const { configDir, specUrl, refresh } = opts;
-    const cachePath = join(configDir, CACHE_FILE);
-    if (!refresh) {
-        const cached = readCache(cachePath);
-        if (cached &&
-            cached.specUrl === specUrl &&
-            Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-            log.debug("Using cached OpenAPI spec from %s", cachePath);
-            return cached.spec;
-        }
-    }
-    try {
-        log.debug("Fetching OpenAPI spec from %s", specUrl);
-        const spec = await fetchSpec(specUrl);
-        writeCache(cachePath, { fetchedAt: Date.now(), specUrl, spec });
-        return spec;
-    }
-    catch (err) {
-        log.debug("Failed to fetch OpenAPI spec: %s", err);
-        const stale = readCache(cachePath);
-        if (stale && stale.specUrl === specUrl) {
-            log.debug("Falling back to stale cached OpenAPI spec");
-            return stale.spec;
-        }
-        return null;
-    }
-}
-/** Flatten a spec into a sorted list of routes (by path, then method). */
-export function getEndpoints(spec) {
-    const endpoints = [];
-    for (const [path, item] of Object.entries(spec.paths ?? {})) {
-        for (const [method, op] of Object.entries(item)) {
-            if (!HTTP_METHODS.has(method.toLowerCase())) {
-                continue;
-            }
-            const operation = (op ?? {});
-            endpoints.push({
-                method: method.toUpperCase(),
-                path,
-                summary: operation.summary,
-                operationId: operation.operationId,
-                tags: operation.tags ?? [],
-            });
-        }
-    }
-    endpoints.sort((a, b) => a.path === b.path
-        ? a.method.localeCompare(b.method)
-        : a.path.localeCompare(b.path));
-    return endpoints;
-}