@steve31415/baselib 3.3.0 → 3.4.0

package/dist/ops/logs.d.ts

@@ -0,0 +1,95 @@
+import type { Runner } from '../deploy/types.js';
+import { type CliIo } from './cli.js';
+export declare const AXIOM_QUERY_URL = "https://api.axiom.co/v1/datasets/_apl?format=legacy";
+export declare const QUERY_TOKEN_SECRET = "shared--axiom-query-token";
+export declare const USAGE = "usage: pw-logs [options] [APL tail]\nQuery the fleet's Axiom logs (query-only token from Secret Manager).\n\n  -d, --dataset <name>  apps (default) | platform | rum\n  -a, --app <name>      app filter; default: the enclosing repo's deploy.config.json; \"all\" for none\n  -l, --level <level>   debug | info | warn | error; add \"+\" for that level and above (warn+)\n  -s, --since <when>    window start: duration back from now (30m, 6h, 3d) or timestamp (default 1h)\n  -u, --until <when>    window end, same forms (default now)\n  -n, --limit <n>       rows to return (default 200); events are the newest, printed oldest first\n      --json            print events (or aggregation rows) as a JSON array\n      --all             text mode: show every field (batch ids, full build_id)\n      --apl             print the query that would run and exit\n  -h, --help\n\nThe tail is appended to the generated pipeline. The newest-first ordering\nis added only when the tail just filters or reshapes events (where, extend,\nproject-away/keep/rename, mv-expand, parse); a summarize, project, order or\ntake stage of your own decides the order. The limit always applies.\nExamples:\n  pw-logs -l error -s 6h\n  pw-logs -a chime \"where meta.user == 'x' | where message has 'sync'\"\n  pw-logs -a all -l warn+ -s 24h \"summarize n=count() by app, message\"\n  pw-logs -d platform -s 3d \"where severity != 'INFO'\"\nFields: apps = app, level, message, source, build_id, meta.* (a map: query\nsub-keys with dot notation, cast for summarize by \u2014 tostring(meta.user));\nplatform = service, severity, text, revision; rum = app, metric, value,\nrating, path, build_id.";
+type Fields = Record<string, unknown>;
+interface DatasetSpec {
+    appField: string;
+    levelField: string;
+    /** Ascending severity order; --level maps onto it. */
+    levels: readonly string[];
+    levelFor: Record<string, string>;
+    /** The fixed-position part of an event's text line, from these fields. */
+    headline: string[];
+    line?: (f: Fields) => string;
+    /** Present on every event of the dataset; rows without it (a summarize
+     *  followed by more stages comes back as rows, not buckets) are tabled. */
+    marker?: string;
+    /** Fields hidden in text mode unless --all. */
+    quiet: string[];
+}
+export declare const DATASETS: Record<string, DatasetSpec>;
+export declare function datasetSpec(name: string): DatasetSpec;
+export interface LogsQuery {
+    dataset: string;
+    app?: string;
+    level?: string;
+    tail: string;
+    limit: number;
+}
+export declare function tailKeepsEvents(tail: string): boolean;
+export declare function levelFilter(spec: DatasetSpec, level: string): string;
+export declare function buildApl(q: LogsQuery): {
+    apl: string;
+    autoOrdered: boolean;
+};
+interface LegacyMatch {
+    _time: string;
+    data: Fields;
+}
+interface LegacyGroup {
+    group: Fields;
+    aggregations: {
+        op: string;
+        value: unknown;
+    }[];
+}
+interface LegacyResponse {
+    status?: {
+        isPartial?: boolean;
+        rowsMatched?: number;
+        elapsedTime?: number;
+    };
+    matches?: LegacyMatch[];
+    buckets?: {
+        series?: {
+            startTime: string;
+            endTime: string;
+            groups: LegacyGroup[] | null;
+        }[];
+        totals?: LegacyGroup[];
+    };
+    request?: {
+        aggregations?: {
+            op: string;
+            field: string;
+            alias: string;
+        }[] | null;
+    };
+}
+/** Events as flat records: `_time` first, nulls gone. */
+export declare function eventRecords(matches: LegacyMatch[]): Fields[];
+/** One greppable line per event: the dataset's headline, then the rest as k=v. */
+export declare function renderEvents(dataset: string, records: Fields[], all: boolean): string;
+/** Aggregation rows: group keys then aggregation aliases; a bucket time
+ *  column when the query binned by time. min/max of _time come back as
+ *  epoch nanoseconds and are shown as timestamps. */
+export declare function aggregationRecords(response: LegacyResponse): Fields[];
+export declare function renderTable(records: Fields[]): string;
+export interface LogsOptions extends Partial<CliIo> {
+    argv: string[];
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+    fetchFn?: typeof fetch;
+    runner?: Runner;
+}
+export declare function queryToken(env: NodeJS.ProcessEnv, runner: Runner, project: string): Promise<string>;
+export declare function queryAxiom(fetchFn: typeof fetch, token: string, body: {
+    apl: string;
+    startTime: string;
+    endTime: string;
+}): Promise<LegacyResponse>;
+export declare function runLogs(options: LogsOptions): Promise<number>;
+export {};

package/dist/ops/logs.js

@@ -0,0 +1,302 @@
+// `pw-logs` — an APL query against the fleet's Axiom datasets with the
+// query-only token from Secret Manager. Bakes in the dataset conventions
+// (OPERATIONS.md "Logging"): `apps` rows carry app / level / message /
+// source / build_id and structured data under the `meta` map; `platform`
+// rows are GCP platform events keyed by service / severity / text; `rum`
+// rows are web-vitals keyed by app / metric / value / rating / path.
+//
+// The only request ever made is a POST to the query endpoint; the token is
+// query-only and is never printed.
+import { DEFAULT_PROJECT, NAME } from '../deploy/config.js';
+import { must, realRunner } from '../deploy/exec.js';
+import { LOG_LEVELS } from '../log-core.js';
+import { findAppConfig } from './app.js';
+import { cliIo, parseCli } from './cli.js';
+import { flatten, formatRecords, pairs, parseTimeFlag, pruneNulls, scalarText } from './format.js';
+export const AXIOM_QUERY_URL = 'https://api.axiom.co/v1/datasets/_apl?format=legacy';
+export const QUERY_TOKEN_SECRET = 'shared--axiom-query-token';
+const DEFAULT_LIMIT = 200;
+const DEFAULT_SINCE = '1h';
+const REQUEST_TIMEOUT_MS = 60_000;
+const DATASET_NAME = /^[a-z][a-z0-9_-]*$/;
+export const USAGE = `usage: pw-logs [options] [APL tail]
+Query the fleet's Axiom logs (query-only token from Secret Manager).
+
+  -d, --dataset <name>  apps (default) | platform | rum
+  -a, --app <name>      app filter; default: the enclosing repo's deploy.config.json; "all" for none
+  -l, --level <level>   debug | info | warn | error; add "+" for that level and above (warn+)
+  -s, --since <when>    window start: duration back from now (30m, 6h, 3d) or timestamp (default ${DEFAULT_SINCE})
+  -u, --until <when>    window end, same forms (default now)
+  -n, --limit <n>       rows to return (default ${DEFAULT_LIMIT}); events are the newest, printed oldest first
+      --json            print events (or aggregation rows) as a JSON array
+      --all             text mode: show every field (batch ids, full build_id)
+      --apl             print the query that would run and exit
+  -h, --help
+
+The tail is appended to the generated pipeline. The newest-first ordering
+is added only when the tail just filters or reshapes events (where, extend,
+project-away/keep/rename, mv-expand, parse); a summarize, project, order or
+take stage of your own decides the order. The limit always applies.
+Examples:
+  pw-logs -l error -s 6h
+  pw-logs -a chime "where meta.user == 'x' | where message has 'sync'"
+  pw-logs -a all -l warn+ -s 24h "summarize n=count() by app, message"
+  pw-logs -d platform -s 3d "where severity != 'INFO'"
+Fields: apps = app, level, message, source, build_id, meta.* (a map: query
+sub-keys with dot notation, cast for summarize by — tostring(meta.user));
+platform = service, severity, text, revision; rum = app, metric, value,
+rating, path, build_id.`;
+const APP_LEVEL_FOR = { debug: 'debug', info: 'info', warn: 'warn', error: 'error' };
+// batch_id/batch_seq are minted by the shipper and severity mirrors level
+// (log-core buildEvent/formBatch): noise when reading, kept for --json/--all.
+const NOISE = ['batch_id', 'batch_seq', 'severity'];
+const text = (v) => scalarText(v);
+export const DATASETS = {
+    apps: {
+        appField: 'app',
+        levelField: 'level',
+        levels: LOG_LEVELS,
+        levelFor: APP_LEVEL_FOR,
+        headline: ['app', 'level', 'message', 'source'],
+        line: (f) => `${text(f.level).toUpperCase().padEnd(5)} ${text(f.app)}${f.source === 'browser' ? '/browser' : ''}  ${text(f.message)}`,
+        marker: 'message',
+        quiet: NOISE,
+    },
+    platform: {
+        appField: 'service',
+        levelField: 'severity',
+        levels: ['DEBUG', 'INFO', 'NOTICE', 'WARNING', 'ERROR', 'CRITICAL', 'ALERT', 'EMERGENCY'],
+        levelFor: { debug: 'DEBUG', info: 'INFO', warn: 'WARNING', error: 'ERROR' },
+        headline: ['service', 'severity', 'text', 'revision'],
+        line: (f) => `${text(f.severity).padEnd(7)} ${text(f.service)}${f.revision ? `@${text(f.revision)}` : ''}  ${text(f.text)}`,
+        marker: 'text',
+        quiet: ['batch_id', 'batch_seq', 'insert_id'],
+    },
+    rum: {
+        appField: 'app',
+        levelField: 'level',
+        levels: LOG_LEVELS,
+        levelFor: APP_LEVEL_FOR,
+        headline: ['app', 'metric', 'value', 'rating', 'path'],
+        line: (f) => `${text(f.app)} ${text(f.metric)}=${text(f.value)} ${text(f.rating)} ${text(f.path)}`,
+        marker: 'metric',
+        quiet: [...NOISE, 'message', 'level', 'source'],
+    },
+};
+const GENERIC = { appField: 'app', levelField: 'level', levels: LOG_LEVELS, levelFor: APP_LEVEL_FOR, headline: [], quiet: [] };
+export function datasetSpec(name) {
+    return DATASETS[name] ?? GENERIC;
+}
+const quote = (s) => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+// Stages that keep one row per event (and its _time), so the default
+// newest-first ordering still means something after them. Anything else —
+// summarize, project, order, take, an operator not listed — decides its own
+// shape and order. Splitting on `|` misreads a pipe inside a string literal,
+// which only costs the default ordering, never a broken query.
+const KEEPS_EVENTS = new Set(['where', 'extend', 'project-away', 'project-keep', 'project-rename', 'mv-expand', 'parse']);
+export function tailKeepsEvents(tail) {
+    return tail.split('|').every((stage) => {
+        const word = stage.trim().split(/\s+/)[0].toLowerCase();
+        return word === '' || KEEPS_EVENTS.has(word);
+    });
+}
+export function levelFilter(spec, level) {
+    const plus = level.endsWith('+');
+    const word = (plus ? level.slice(0, -1) : level).toLowerCase();
+    const value = spec.levelFor[word];
+    if (!value)
+        throw new Error(`unknown level ${level}: use debug, info, warn or error (optionally with +)`);
+    if (!plus)
+        return `${spec.levelField} == ${quote(value)}`;
+    const from = spec.levels.indexOf(value);
+    return `${spec.levelField} in (${spec.levels.slice(from).map(quote).join(', ')})`;
+}
+export function buildApl(q) {
+    const spec = datasetSpec(q.dataset);
+    const stages = [`['${q.dataset}']`];
+    if (q.app)
+        stages.push(`where ${spec.appField} == ${quote(q.app)}`);
+    if (q.level)
+        stages.push(`where ${levelFilter(spec, q.level)}`);
+    const tail = q.tail.replace(/^\s*\|/, '').trim();
+    if (tail)
+        stages.push(tail);
+    const autoOrdered = tailKeepsEvents(tail);
+    if (autoOrdered)
+        stages.push('order by _time desc');
+    stages.push(`take ${q.limit}`);
+    return { apl: stages.join(' | '), autoOrdered };
+}
+const isoTime = (t) => {
+    const d = new Date(t);
+    return isNaN(d.getTime()) ? t : d.toISOString();
+};
+/** Events as flat records: `_time` first, nulls gone. */
+export function eventRecords(matches) {
+    return matches.map((m) => ({ _time: isoTime(m._time), ...pruneNulls(m.data) }));
+}
+/** One greppable line per event: the dataset's headline, then the rest as k=v. */
+export function renderEvents(dataset, records, all) {
+    const spec = datasetSpec(dataset);
+    return records
+        .map((record) => {
+        const { _time, ...fields } = record;
+        const rest = {};
+        for (const [k, v] of Object.entries(fields)) {
+            if (spec.headline.includes(k))
+                continue;
+            if (!all && spec.quiet.includes(k))
+                continue;
+            rest[k] = !all && k === 'build_id' && typeof v === 'string' ? v.slice(0, 7) : v;
+        }
+        return [text(_time), spec.line?.(fields) ?? '', pairs(flatten(rest))].filter((s) => s !== '').join('  ');
+    })
+        .join('\n');
+}
+/** Aggregation rows: group keys then aggregation aliases; a bucket time
+ *  column when the query binned by time. min/max of _time come back as
+ *  epoch nanoseconds and are shown as timestamps. */
+export function aggregationRecords(response) {
+    const series = (response.buckets?.series ?? []).filter((s) => s.groups && s.groups.length > 0);
+    const binned = series.length > 1 || !series[0]?.startTime.startsWith('1970-');
+    const timeAggs = new Set((response.request?.aggregations ?? [])
+        .filter((a) => a.field === '_time' && (a.op === 'min' || a.op === 'max'))
+        .map((a) => a.alias));
+    return series.flatMap((s) => (s.groups ?? []).map((g) => {
+        const row = binned ? { _time: isoTime(s.startTime) } : {};
+        Object.assign(row, g.group);
+        for (const a of g.aggregations) {
+            row[a.op] =
+                timeAggs.has(a.op) && typeof a.value === 'number' ? new Date(Math.round(a.value / 1e6)).toISOString() : a.value;
+        }
+        return row;
+    }));
+}
+export function renderTable(records) {
+    const columns = [];
+    for (const r of records)
+        for (const k of Object.keys(r))
+            if (!columns.includes(k))
+                columns.push(k);
+    return formatRecords(columns, records);
+}
+export async function queryToken(env, runner, project) {
+    if (env.AXIOM_QUERY_TOKEN)
+        return env.AXIOM_QUERY_TOKEN;
+    const result = await must(runner, 'gcloud', [
+        'secrets', 'versions', 'access', 'latest', '--secret', QUERY_TOKEN_SECRET, '--project', project,
+    ]);
+    const token = result.stdout.trim();
+    if (!token)
+        throw new Error(`secret ${QUERY_TOKEN_SECRET} is empty`);
+    return token;
+}
+export async function queryAxiom(fetchFn, token, body) {
+    const response = await fetchFn(AXIOM_QUERY_URL, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        let detail = raw;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.message)
+                detail = parsed.message;
+        }
+        catch {
+            // not JSON; report the raw body
+        }
+        throw new Error(`Axiom HTTP ${response.status}: ${detail}`);
+    }
+    return JSON.parse(raw);
+}
+const FLAGS = {
+    dataset: { type: 'string', short: 'd', default: 'apps' },
+    app: { type: 'string', short: 'a' },
+    level: { type: 'string', short: 'l' },
+    since: { type: 'string', short: 's', default: DEFAULT_SINCE },
+    until: { type: 'string', short: 'u' },
+    limit: { type: 'string', short: 'n', default: String(DEFAULT_LIMIT) },
+    json: { type: 'boolean', default: false },
+    all: { type: 'boolean', default: false },
+    apl: { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h', default: false },
+};
+export async function runLogs(options) {
+    const io = cliIo('pw-logs', options);
+    const parsed = parseCli(options.argv, FLAGS, USAGE, io);
+    if ('code' in parsed)
+        return parsed.code;
+    const { values: v, positionals } = parsed;
+    const env = options.env ?? process.env;
+    const now = (options.now ?? (() => new Date()))();
+    const appConfig = await findAppConfig(options.cwd);
+    let query;
+    let apl;
+    let autoOrdered;
+    let startTime;
+    let endTime;
+    try {
+        if (!DATASET_NAME.test(v.dataset))
+            throw new Error(`invalid dataset name: ${v.dataset}`);
+        const limit = Number(v.limit);
+        if (!Number.isInteger(limit) || limit < 1)
+            throw new Error(`--limit must be a positive integer, got ${v.limit}`);
+        let app = v.app ?? appConfig?.app;
+        if (app === 'all')
+            app = undefined;
+        if (app !== undefined && !NAME.test(app))
+            throw new Error(`invalid app name: ${app}`);
+        query = { dataset: v.dataset, app, level: v.level, tail: positionals.join(' '), limit };
+        ({ apl, autoOrdered } = buildApl(query));
+        startTime = parseTimeFlag(v.since, now);
+        endTime = v.until === undefined ? now : parseTimeFlag(v.until, now);
+        if (endTime <= startTime)
+            throw new Error(`empty window: ${startTime.toISOString()} .. ${endTime.toISOString()}`);
+    }
+    catch (err) {
+        io.log(err.message);
+        return 2;
+    }
+    const body = { apl, startTime: startTime.toISOString(), endTime: endTime.toISOString() };
+    if (v.apl) {
+        io.stdout(`${apl}\n-- ${body.startTime} .. ${body.endTime}`);
+        return 0;
+    }
+    let response;
+    try {
+        const token = await queryToken(env, options.runner ?? realRunner, appConfig?.project ?? DEFAULT_PROJECT);
+        response = await queryAxiom(options.fetchFn ?? fetch, token, body);
+    }
+    catch (err) {
+        io.log(`query failed: ${err.message}\n${apl}`);
+        return 1;
+    }
+    const matches = response.matches ?? [];
+    const window = `${body.startTime} .. ${body.endTime}`;
+    const marker = datasetSpec(query.dataset).marker;
+    const events = matches.length > 0 && (marker === undefined || matches[0].data[marker] != null);
+    if (events) {
+        // Newest-first from the server; print oldest first so the log reads down.
+        const records = eventRecords(autoOrdered ? [...matches].reverse() : matches);
+        io.stdout(v.json ? JSON.stringify(records, null, 2) : renderEvents(query.dataset, records, v.all));
+        const matched = response.status?.rowsMatched;
+        const of = matched !== undefined && matched > records.length ? ` of ${matched} matching` : '';
+        io.log(`${records.length} event${records.length === 1 ? '' : 's'}${of}, ${window}`);
+    }
+    else {
+        const rows = matches.length > 0 ? eventRecords(matches) : aggregationRecords(response);
+        if (v.json)
+            io.stdout(JSON.stringify(rows, null, 2));
+        else
+            io.stdout(rows.length === 0 ? '(no results)' : renderTable(rows));
+        const noun = rows.length === 0 && autoOrdered ? 'events' : `row${rows.length === 1 ? '' : 's'}`;
+        io.log(`${rows.length} ${noun}, ${window}`);
+    }
+    if (response.status?.isPartial)
+        io.log('warning: Axiom reported a partial result');
+    return 0;
+}

package/dist/ops/sql.d.ts

@@ -0,0 +1,42 @@
+import pg from 'pg';
+import type { Runner } from '../deploy/types.js';
+import { type CliIo } from './cli.js';
+export declare const DEFAULT_INSTANCE = "plasticine-prod:us-west1:plasticine-pg";
+export declare const DEFAULT_DB_USER: string;
+export interface SqlTarget {
+    instance: string;
+    user: string;
+    database: string;
+}
+export interface SqlResult {
+    command: string;
+    fields: string[];
+    rows: Record<string, unknown>[];
+    rowCount: number | null;
+}
+export interface SqlClient {
+    query(text: string): Promise<pg.QueryResult | pg.QueryResult[]>;
+    end(): Promise<void>;
+}
+export interface SqlOptions extends Partial<CliIo> {
+    argv: string[];
+    cwd: string;
+    /** Reads the whole of stdin (the SQL when no positional was given). */
+    stdin?: () => Promise<string>;
+    stdinIsTty?: boolean;
+    /** Test seam: replaces the Cloud SQL connector. */
+    connect?: (target: SqlTarget, log: (m: string) => void) => Promise<SqlClient>;
+    runner?: Runner;
+}
+export declare const USAGE: string;
+/** Text the tool will not send at all: anything that could turn the session
+ *  read-write, end the guarding transaction, or act on other backends. A
+ *  false positive (the word "commit" in a string literal) is the acceptable
+ *  cost; the message names the pattern so the query can be rephrased. */
+export declare function refuseUnsafeSql(sql: string): string | null;
+/** Run `sql` inside a read-only transaction that is always rolled back.
+ *  The lock-in query both verifies the mode and pins it: after a snapshot has
+ *  been taken Postgres refuses `set transaction read write`. */
+export declare function executeReadOnly(client: SqlClient, sql: string, timeoutMs: number): Promise<SqlResult[]>;
+export declare function connectCloudSql(target: SqlTarget, log: (m: string) => void, runner?: Runner): Promise<SqlClient>;
+export declare function runSql(options: SqlOptions): Promise<number>;

package/dist/ops/sql.js

@@ -0,0 +1,219 @@
+// `pw-sql` — a read-only SQL query against a production database on the
+// fleet's Cloud SQL instance, with IAM authentication as the coding agent.
+//
+// Read-only is enforced three ways, each sufficient on its own:
+//   1. the session starts with default_transaction_read_only=on (a startup
+//      parameter, so it holds before any statement runs);
+//   2. the query runs inside `begin read only`, after a lock-in query — Postgres
+//      refuses a switch to read-write once a transaction has taken a snapshot —
+//      and is always rolled back;
+//   3. SQL that could change those settings or end the transaction is refused
+//      before it is sent (refuseUnsafeSql).
+// The agent's Postgres role has write privileges on every app database, so
+// the tool, not the grants, is the safeguard.
+import pg from 'pg';
+import { cloudSqlClientOptions, dateAsText } from '../db.js';
+import { DEFAULT_ACCOUNT, DEFAULT_PROJECT } from '../deploy/config.js';
+import { findAppConfig } from './app.js';
+import { cliIo, parseCli } from './cli.js';
+import { formatRecords } from './format.js';
+import { authClientFor, describeCredential, resolveGcpCredential } from './gcp-auth.js';
+const INSTANCE_NAME = 'plasticine-pg';
+export const DEFAULT_INSTANCE = `${DEFAULT_PROJECT}:us-west1:${INSTANCE_NAME}`;
+export const DEFAULT_DB_USER = DEFAULT_ACCOUNT.replace(/\.gserviceaccount\.com$/, '');
+const DEFAULT_TIMEOUT_S = 60;
+const CONNECT_TIMEOUT_MS = 20_000;
+export const USAGE = `usage: pw-sql [options] [SQL...]
+Read-only query against a production database (Cloud SQL, IAM auth).
+SQL comes from the arguments (joined by spaces) or from stdin.
+
+  --db <name>         database; default: the app of the enclosing repo's deploy.config.json
+  --json              print rows as a JSON array (one array per statement) instead of a table
+  --timeout <s>       statement timeout in seconds (default ${DEFAULT_TIMEOUT_S})
+  --instance <conn>   Cloud SQL connection name (default ${DEFAULT_INSTANCE})
+  --user <iam-user>   IAM database user (default ${DEFAULT_DB_USER})
+  -h, --help
+
+Examples:
+  pw-sql "select count(*) from items"
+  pw-sql --db chime --json "select * from reminders order by id desc limit 5"
+  echo "select now()" | pw-sql --db auth
+Every session is read-only: writes, DDL, temp tables and sequence advances fail.`;
+/** Text the tool will not send at all: anything that could turn the session
+ *  read-write, end the guarding transaction, or act on other backends. A
+ *  false positive (the word "commit" in a string literal) is the acceptable
+ *  cost; the message names the pattern so the query can be rephrased. */
+export function refuseUnsafeSql(sql) {
+    const checks = [
+        [/transaction_read_only/i, 'references transaction_read_only'],
+        [/\bread\s+write\b/i, 'sets read-write mode'],
+        [/\bset_config\s*\(/i, 'calls set_config()'],
+        [/\b(commit|prepare\s+transaction)\b/i, 'contains transaction control (commit/prepare transaction)'],
+        [
+            /\bpg_(terminate_backend|cancel_backend|reload_conf|switch_wal|create_restore_point|create_physical_replication_slot|create_logical_replication_slot|drop_replication_slot|promote)\b/i,
+            'calls an administrative function with side effects',
+        ],
+    ];
+    for (const [pattern, reason] of checks) {
+        if (pattern.test(sql))
+            return `refusing SQL that ${reason} (pw-sql is read-only)`;
+    }
+    return null;
+}
+/** Run `sql` inside a read-only transaction that is always rolled back.
+ *  The lock-in query both verifies the mode and pins it: after a snapshot has
+ *  been taken Postgres refuses `set transaction read write`. */
+export async function executeReadOnly(client, sql, timeoutMs) {
+    await client.query('begin read only');
+    try {
+        await client.query(`set local statement_timeout = ${Math.max(1, Math.floor(timeoutMs))}`);
+        const mode = (await client.query("select current_setting('transaction_read_only') as ro"));
+        if (mode.rows[0]?.ro !== 'on')
+            throw new Error('session is not read-only; refusing to run the query');
+        const raw = await client.query(sql);
+        return (Array.isArray(raw) ? raw : [raw]).map((r) => ({
+            command: r.command,
+            fields: r.fields.map((f) => f.name),
+            rows: r.rows,
+            rowCount: r.rowCount,
+        }));
+    }
+    finally {
+        await client.query('rollback').catch(() => { });
+    }
+}
+// Value parsing for output: int8 as a number when exact; dates and
+// zone-less timestamps as the server's text (db.ts's DATE policy — a Date
+// would smear them across zones); everything else pg's default, so
+// timestamptz becomes a Date and prints as UTC ISO.
+function outputTypes() {
+    const { builtins } = pg.types;
+    const overrides = {
+        [builtins.INT8]: (v) => (Number.isSafeInteger(Number(v)) ? Number(v) : v),
+        [builtins.DATE]: dateAsText,
+        [builtins.TIMESTAMP]: dateAsText,
+    };
+    return {
+        getTypeParser: (oid, format) => {
+            if (format !== 'binary' && overrides[oid])
+                return overrides[oid];
+            return pg.types.getTypeParser(oid, format);
+        },
+    };
+}
+export async function connectCloudSql(target, log, runner) {
+    const cred = await resolveGcpCredential({ runner });
+    log(`connecting to ${target.instance} db=${target.database} as ${target.user} via ${describeCredential(cred)}`);
+    const { options: connection, connector } = await cloudSqlClientOptions(target.instance, authClientFor(cred));
+    const client = new pg.Client({
+        ...connection,
+        user: target.user,
+        database: target.database,
+        options: '-c default_transaction_read_only=on',
+        connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
+        types: outputTypes(),
+    });
+    try {
+        await client.connect();
+    }
+    catch (err) {
+        connector.close();
+        throw err;
+    }
+    return {
+        query: (text) => client.query(text),
+        end: async () => {
+            await client.end();
+            connector.close();
+        },
+    };
+}
+function renderResults(results, json) {
+    if (json)
+        return results.map((r) => JSON.stringify(r.rows, null, 2)).join('\n');
+    return results
+        .map((r) => {
+        if (r.fields.length === 0)
+            return `${r.command}${r.rowCount === null ? '' : ` ${r.rowCount}`}`;
+        return `${formatRecords(r.fields, r.rows)}\n(${r.rows.length} row${r.rows.length === 1 ? '' : 's'})`;
+    })
+        .join('\n\n');
+}
+const FLAGS = {
+    db: { type: 'string' },
+    json: { type: 'boolean', default: false },
+    timeout: { type: 'string' },
+    instance: { type: 'string' },
+    user: { type: 'string' },
+    help: { type: 'boolean', short: 'h', default: false },
+};
+export async function runSql(options) {
+    const io = cliIo('pw-sql', options);
+    const parsed = parseCli(options.argv, FLAGS, USAGE, io);
+    if ('code' in parsed)
+        return parsed.code;
+    const { values, positionals } = parsed;
+    const timeoutS = values.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(values.timeout);
+    if (!(timeoutS > 0)) {
+        io.log(`--timeout must be a positive number of seconds, got ${values.timeout}`);
+        return 2;
+    }
+    let sql = positionals.join(' ').trim();
+    if (!sql) {
+        if (options.stdinIsTty ?? process.stdin.isTTY) {
+            io.stdout(USAGE);
+            return 2;
+        }
+        sql = (await (options.stdin ?? readStdin)()).trim();
+        if (!sql) {
+            io.log('no SQL given (arguments or stdin)');
+            return 2;
+        }
+    }
+    const refusal = refuseUnsafeSql(sql);
+    if (refusal) {
+        io.log(refusal);
+        return 2;
+    }
+    const app = await findAppConfig(options.cwd);
+    const database = values.db ?? app?.app;
+    if (!database) {
+        io.log('no database: pass --db <name> or run inside an app repo (deploy.config.json)');
+        return 2;
+    }
+    const target = {
+        instance: values.instance ?? (app ? `${app.project}:${app.region}:${INSTANCE_NAME}` : DEFAULT_INSTANCE),
+        user: values.user ?? DEFAULT_DB_USER,
+        database,
+    };
+    const connect = options.connect ?? ((t, l) => connectCloudSql(t, l, options.runner));
+    let client;
+    try {
+        client = await connect(target, io.log);
+    }
+    catch (err) {
+        io.log(`connection failed: ${err.message}`);
+        return 1;
+    }
+    try {
+        const started = Date.now();
+        const results = await executeReadOnly(client, sql, timeoutS * 1000);
+        io.stdout(renderResults(results, values.json));
+        io.log(`${results.reduce((n, r) => n + r.rows.length, 0)} rows in ${Date.now() - started} ms`);
+        return 0;
+    }
+    catch (err) {
+        const e = err;
+        io.log(`query failed: ${e.message}${e.position ? ` (at character ${e.position})` : ''}${e.hint ? `\nhint: ${e.hint}` : ''}`);
+        return 1;
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -73,7 +73,9 @@
   "bin": {
     "check-test-owners": "./dist/bin/check-test-owners.js",
     "pw-deploy": "./dist/bin/pw-deploy.js",
-    "pw-rollback": "./dist/bin/pw-rollback.js"
+    "pw-logs": "./dist/bin/pw-logs.js",
+    "pw-rollback": "./dist/bin/pw-rollback.js",
+    "pw-sql": "./dist/bin/pw-sql.js"
   },
   "engines": {
     "node": "22.x"