@steve31415/baselib 3.3.1 → 3.4.0

package/README.md

@@ -28,6 +28,10 @@ from a named `NAME@snewman.net` sender, no outbox — a failed send is an
 ERROR log (`~/plasticine-way/docs/SECURITY.md`, "Resend API key").
 
 Bins: `check-test-owners` — the fleet's structural test-coverage gate; every
-app runs it from `npm run verify`.
+app runs it from `npm run verify`. `pw-deploy` / `pw-rollback` — the fleet
+deploy (`~/plasticine-way/docs/OPERATIONS.md`, "Deployment safety").
+`pw-sql` / `pw-logs` — read-only production queries (database, Axiom), the
+first step of any production investigation (same doc, "Investigating
+production state").
 
 Reflects Plasticine Way commit: see `docs/IMPL.md` footer.

package/dist/bin/pw-logs.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/pw-logs.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// `pw-logs` — Axiom log query (OPERATIONS.md "Investigating production
+// state"). All logic lives in ../ops/logs.ts.
+import { runLogs } from '../ops/logs.js';
+process.exit(await runLogs({ argv: process.argv.slice(2), cwd: process.cwd() }));

package/dist/bin/pw-sql.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/pw-sql.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// `pw-sql` — read-only production SQL (OPERATIONS.md "Investigating
+// production state"). All logic lives in ../ops/sql.ts.
+import { runSql } from '../ops/sql.js';
+process.exit(await runSql({ argv: process.argv.slice(2), cwd: process.cwd() }));

package/dist/db.d.ts

@@ -1,5 +1,17 @@
+import type { ConnectorOptions } from '@google-cloud/cloud-sql-connector';
 import pg from 'pg';
 import { type Logger } from './log-core.js';
+export declare const dateAsText: (v: string) => string;
+/** Connection options for a Cloud SQL instance the fleet way: the Node
+ * connector, IAM authentication, public IP. `auth` replaces the connector's
+ * default credential resolution (the agent's tooling needs that; deployed
+ * code uses the default). The connector stays open for the connections'
+ * lifetime; close it when they are done. */
+export declare function cloudSqlClientOptions(instance: string, auth?: ConnectorOptions['auth']): Promise<{
+    options: Awaited<ReturnType<Connector['getOptions']>>;
+    connector: Connector;
+}>;
+type Connector = import('@google-cloud/cloud-sql-connector').Connector;
 export interface PoolOptions {
     /** Override the database name (default: env DB_NAME / DATABASE_URL path). */
     database?: string;
@@ -32,3 +44,4 @@ export declare function endPool(pool: pg.Pool): Promise<void>;
 export declare function migrate(pool: pg.Pool, migrationsDir: string, logger?: Logger): Promise<{
     applied: string[];
 }>;
+export {};

package/dist/db.js

@@ -13,7 +13,23 @@ import { serializeError } from './log-core.js';
 // pg instance createPool actually uses — because apps that set it on their
 // own pg copy miss this one (file:-dependency installs resolve separate pg
 // instances).
-pg.types.setTypeParser(pg.types.builtins.DATE, (v) => v);
+export const dateAsText = (v) => v;
+pg.types.setTypeParser(pg.types.builtins.DATE, dateAsText);
+/** Connection options for a Cloud SQL instance the fleet way: the Node
+ * connector, IAM authentication, public IP. `auth` replaces the connector's
+ * default credential resolution (the agent's tooling needs that; deployed
+ * code uses the default). The connector stays open for the connections'
+ * lifetime; close it when they are done. */
+export async function cloudSqlClientOptions(instance, auth) {
+    const { Connector, AuthTypes, IpAddressTypes } = await import('@google-cloud/cloud-sql-connector');
+    const connector = new Connector(auth ? { auth } : {});
+    const options = await connector.getOptions({
+        instanceConnectionName: instance,
+        ipType: IpAddressTypes.PUBLIC,
+        authType: AuthTypes.IAM,
+    });
+    return { options, connector };
+}
 /** pg-pool re-emits an idle client's socket error as its own 'error' event —
  * in production "Connection terminated unexpectedly" when Cloud SQL closes an
  * idle connection. Unhandled, that event throws and takes the process down
@@ -37,13 +53,7 @@ export async function createPool(opts = {}) {
 async function newPool(opts) {
     const instance = process.env.CLOUD_SQL_INSTANCE;
     if (instance) {
-        const { Connector, AuthTypes, IpAddressTypes } = await import('@google-cloud/cloud-sql-connector');
-        const connector = new Connector();
-        const clientOpts = await connector.getOptions({
-            instanceConnectionName: instance,
-            ipType: IpAddressTypes.PUBLIC,
-            authType: AuthTypes.IAM,
-        });
+        const { options: clientOpts } = await cloudSqlClientOptions(instance);
         return new pg.Pool({
             ...clientOpts,
             user: requireEnv('DB_IAM_USER'),

package/dist/deploy/config.d.ts

@@ -1,5 +1,8 @@
 import type { DeployConfig, DeployHooks } from './types.js';
+export declare const DEFAULT_PROJECT = "plasticine-prod";
 export declare const DEFAULT_ACCOUNT = "coding-agent@plasticine-prod.iam.gserviceaccount.com";
+/** App and service names (also the database and log `app` values). */
+export declare const NAME: RegExp;
 export declare function validateConfig(raw: unknown): DeployConfig;
 export declare function loadConfig(repoRoot: string): Promise<DeployConfig>;
 export declare function loadHooks(repoRoot: string, config: DeployConfig): Promise<DeployHooks>;

package/dist/deploy/config.js

@@ -3,8 +3,10 @@
 import { readFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import { resolve } from 'node:path';
-export const DEFAULT_ACCOUNT = 'coding-agent@plasticine-prod.iam.gserviceaccount.com';
-const NAME = /^[a-z][a-z0-9-]{1,30}$/;
+export const DEFAULT_PROJECT = 'plasticine-prod';
+export const DEFAULT_ACCOUNT = `coding-agent@${DEFAULT_PROJECT}.iam.gserviceaccount.com`;
+/** App and service names (also the database and log `app` values). */
+export const NAME = /^[a-z][a-z0-9-]{1,30}$/;
 const PREFIX = /^[a-z0-9][a-z0-9/_-]*\/$/;
 function fail(detail) {
     throw new Error(`deploy.config.json invalid: ${detail}`);

package/dist/log-core.d.ts

@@ -1,4 +1,5 @@
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
 export interface LogEvent {
     _time: string;
     app: string;

package/dist/log-core.js

@@ -9,6 +9,7 @@
 // logger turns those into stdout drop markers that watchdog2's daily
 // ship-failure check counts. makeEvent also guards the shape of `meta`: every
 // distinct key is an Axiom column (see "Key-shape guard" below).
+export const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
 export function serializeError(err) {
     if (err instanceof Error) {
         const out = { name: err.name, message: err.message, stack: err.stack };

package/dist/ops/app.d.ts

@@ -0,0 +1,4 @@
+import type { DeployConfig } from '../deploy/types.js';
+export declare function fileExists(path: string): Promise<boolean>;
+/** The deploy config of the nearest enclosing app repo, or null outside one. */
+export declare function findAppConfig(startDir: string): Promise<DeployConfig | null>;

package/dist/ops/app.js

@@ -0,0 +1,28 @@
+// Which app is this? The production query tools take their defaults (the
+// database name, the log `app` filter, the GCP project) from the
+// deploy.config.json of the app repo they are run in, found by walking up
+// from the working directory.
+import { access } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { loadConfig } from '../deploy/config.js';
+export async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The deploy config of the nearest enclosing app repo, or null outside one. */
+export async function findAppConfig(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (await fileExists(join(dir, 'deploy.config.json')))
+            return loadConfig(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/ops/cli.d.ts

@@ -0,0 +1,16 @@
+import { parseArgs, type ParseArgsConfig } from 'node:util';
+export interface CliIo {
+    stdout: (text: string) => void;
+    log: (message: string) => void;
+}
+export declare function cliIo(name: string, overrides?: Partial<CliIo>): CliIo;
+type Options = NonNullable<ParseArgsConfig['options']>;
+type Parsed<T extends Options> = ReturnType<typeof parseArgs<{
+    options: T;
+    allowPositionals: true;
+}>>;
+/** Parsed flags and positionals, or the exit code already dealt with. */
+export declare function parseCli<T extends Options>(argv: string[], options: T, usage: string, io: CliIo): Parsed<T> | {
+    code: number;
+};
+export {};

package/dist/ops/cli.js

@@ -0,0 +1,27 @@
+// Shared command-line conventions of the pw-* query tools: parseArgs with
+// positionals, usage + exit 2 on a bad flag, usage + exit 0 on --help,
+// progress on stderr under the tool's name, results on stdout.
+import { parseArgs } from 'node:util';
+export function cliIo(name, overrides = {}) {
+    return {
+        stdout: overrides.stdout ?? ((t) => process.stdout.write(`${t}\n`)),
+        log: overrides.log ?? ((m) => console.error(`[${name}] ${m}`)),
+    };
+}
+/** Parsed flags and positionals, or the exit code already dealt with. */
+export function parseCli(argv, options, usage, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options, allowPositionals: true });
+    }
+    catch (err) {
+        io.log(err.message);
+        io.stdout(usage);
+        return { code: 2 };
+    }
+    if (parsed.values.help) {
+        io.stdout(usage);
+        return { code: 0 };
+    }
+    return parsed;
+}

package/dist/ops/format.d.ts

@@ -0,0 +1,26 @@
+export declare const isRecord: (v: unknown) => v is Record<string, unknown>;
+/** Recursively drop null/undefined values and the objects left empty by
+ *  that. Axiom's legacy query format returns every field of the dataset's
+ *  union schema, almost all null; this turns a row back into what was
+ *  actually logged. Arrays are kept whole (elements pruned in place). */
+export declare function pruneNulls(value: unknown): unknown;
+/** `{ meta: { user: 'x' } }` -> `{ 'meta.user': 'x' }`. Arrays and Dates are leaves. */
+export declare function flatten(value: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+/** A value as text: strings as they are, Dates as UTC ISO, anything else as JSON. */
+export declare function scalarText(value: unknown, nullAs?: string): string;
+/** One table cell: NULL spelled out, line breaks escaped so a row stays one line. */
+export declare function cell(value: unknown): string;
+/** Aligned text table: header, rule, rows. Columns are left-aligned except
+ *  numeric ones, which are right-aligned like psql. */
+export declare function formatTable(columns: string[], rows: unknown[][]): string;
+/** formatTable over records, one column per name. */
+export declare function formatRecords(columns: string[], records: Record<string, unknown>[]): string;
+/** `k=v` pairs for the fields of a flattened record, values JSON-quoted when
+ *  they contain whitespace, quotes, or `=`. Greppable one-line form. */
+export declare function pairs(record: Record<string, unknown>): string;
+/** `30s`, `15m`, `6h`, `3d`, `1w` -> milliseconds; null when not a duration. */
+export declare function parseDuration(text: string): number | null;
+/** A time flag is either a duration counted back from `now` (`6h`) or an
+ *  absolute timestamp (`2026-09-03T21:00Z`, `2026-09-03`, parsed as UTC when
+ *  no zone is given). */
+export declare function parseTimeFlag(text: string, now: Date): Date;

package/dist/ops/format.js

@@ -0,0 +1,104 @@
+// Output helpers shared by the production query tools (pw-sql, pw-logs):
+// null pruning, key flattening, aligned tables, and the time-flag grammar.
+export const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date);
+/** Recursively drop null/undefined values and the objects left empty by
+ *  that. Axiom's legacy query format returns every field of the dataset's
+ *  union schema, almost all null; this turns a row back into what was
+ *  actually logged. Arrays are kept whole (elements pruned in place). */
+export function pruneNulls(value) {
+    if (Array.isArray(value))
+        return value.map(pruneNulls);
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const v = pruneNulls(raw);
+        if (v === null || v === undefined)
+            continue;
+        if (isRecord(v) && Object.keys(v).length === 0)
+            continue;
+        out[key] = v;
+    }
+    return out;
+}
+/** `{ meta: { user: 'x' } }` -> `{ 'meta.user': 'x' }`. Arrays and Dates are leaves. */
+export function flatten(value, prefix = '') {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (isRecord(v))
+            Object.assign(out, flatten(v, path));
+        else
+            out[path] = v;
+    }
+    return out;
+}
+/** A value as text: strings as they are, Dates as UTC ISO, anything else as JSON. */
+export function scalarText(value, nullAs = '') {
+    if (value === null || value === undefined)
+        return nullAs;
+    if (value instanceof Date)
+        return isNaN(value.getTime()) ? 'Invalid Date' : value.toISOString();
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value);
+}
+/** One table cell: NULL spelled out, line breaks escaped so a row stays one line. */
+export function cell(value) {
+    return scalarText(value, 'NULL').replace(/\r?\n/g, '\\n');
+}
+const NUMERIC = /^-?\d+(\.\d+)?$/;
+/** Aligned text table: header, rule, rows. Columns are left-aligned except
+ *  numeric ones, which are right-aligned like psql. */
+export function formatTable(columns, rows) {
+    const widths = columns.map((c) => c.length);
+    const numeric = columns.map(() => rows.length > 0);
+    const text = rows.map((row) => columns.map((_, i) => {
+        const s = cell(row[i]);
+        widths[i] = Math.max(widths[i], s.length);
+        if (s !== 'NULL' && !NUMERIC.test(s))
+            numeric[i] = false;
+        return s;
+    }));
+    const line = (cells) => cells
+        .map((c, i) => (numeric[i] ? c.padStart(widths[i]) : c.padEnd(widths[i])))
+        .join('  ')
+        .trimEnd();
+    return [line(columns), widths.map((w) => '-'.repeat(w)).join('  '), ...text.map(line)].join('\n');
+}
+/** formatTable over records, one column per name. */
+export function formatRecords(columns, records) {
+    return formatTable(columns, records.map((r) => columns.map((c) => r[c])));
+}
+/** `k=v` pairs for the fields of a flattened record, values JSON-quoted when
+ *  they contain whitespace, quotes, or `=`. Greppable one-line form. */
+export function pairs(record) {
+    return Object.entries(record)
+        .map(([k, v]) => {
+        const s = scalarText(v);
+        return `${k}=${/^[^\s"'=]+$/.test(s) ? s : JSON.stringify(s)}`;
+    })
+        .join(' ');
+}
+const DURATION = /^(\d+(?:\.\d+)?)\s*(s|m|h|d|w)$/;
+const UNIT_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+/** `30s`, `15m`, `6h`, `3d`, `1w` -> milliseconds; null when not a duration. */
+export function parseDuration(text) {
+    const m = DURATION.exec(text.trim());
+    return m ? Math.round(Number(m[1]) * UNIT_MS[m[2]]) : null;
+}
+/** A time flag is either a duration counted back from `now` (`6h`) or an
+ *  absolute timestamp (`2026-09-03T21:00Z`, `2026-09-03`, parsed as UTC when
+ *  no zone is given). */
+export function parseTimeFlag(text, now) {
+    const ms = parseDuration(text);
+    if (ms !== null)
+        return new Date(now.getTime() - ms);
+    const t = text.trim();
+    const hasZone = /(Z|[+-]\d{2}:?\d{2})$/i.test(t);
+    const parsed = new Date(/^\d{4}-\d{2}-\d{2}$/.test(t) || hasZone ? t : `${t}Z`);
+    if (isNaN(parsed.getTime())) {
+        throw new Error(`not a duration (30m, 6h, 3d) or timestamp (2026-09-03T21:00Z): ${text}`);
+    }
+    return parsed;
+}

package/dist/ops/gcp-auth.d.ts

@@ -0,0 +1,25 @@
+import { GoogleAuth, OAuth2Client } from 'google-auth-library';
+import type { Runner } from '../deploy/types.js';
+export type GcpCredential = {
+    kind: 'adc';
+    path: string;
+} | {
+    kind: 'key-file';
+    path: string;
+    account: string;
+} | {
+    kind: 'access-token';
+    token: string;
+    account: string;
+};
+/** Test seams; every field defaults to the real thing. */
+export interface CredentialDeps {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    exists?: (path: string) => Promise<boolean>;
+    runner?: Runner;
+}
+export declare function resolveGcpCredential(deps?: CredentialDeps): Promise<GcpCredential>;
+/** Short human description for the tool's progress line. */
+export declare function describeCredential(cred: GcpCredential): string;
+export declare function authClientFor(cred: GcpCredential): GoogleAuth | OAuth2Client;

package/dist/ops/gcp-auth.js

@@ -0,0 +1,64 @@
+// Google credentials for the agent's own tooling (not deployed code). The
+// containers have no application-default credentials file, only gcloud's
+// stored account keys, so the connector's default resolution fails there
+// (after probing for a metadata server); this resolves, in order: an
+// explicit or well-known ADC file, gcloud's stored key for the active
+// account, and finally a gcloud-minted access token. The result is what the
+// Cloud SQL connector accepts as `auth`.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { GoogleAuth, OAuth2Client } from 'google-auth-library';
+import { must, realRunner } from '../deploy/exec.js';
+import { fileExists } from './app.js';
+// Both halves of an IAM Cloud SQL connection: the admin API for the
+// ephemeral certificate and the login token itself.
+const CLOUD_SQL_SCOPES = [
+    'https://www.googleapis.com/auth/sqlservice.admin',
+    'https://www.googleapis.com/auth/sqlservice.login',
+];
+export async function resolveGcpCredential(deps = {}) {
+    const env = deps.env ?? process.env;
+    const exists = deps.exists ?? fileExists;
+    const runner = deps.runner ?? realRunner;
+    const explicit = env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (explicit) {
+        if (!(await exists(explicit))) {
+            throw new Error(`GOOGLE_APPLICATION_CREDENTIALS points at a missing file: ${explicit}`);
+        }
+        return { kind: 'adc', path: explicit };
+    }
+    const gcloudDir = env.CLOUDSDK_CONFIG ?? join(deps.home ?? homedir(), '.config', 'gcloud');
+    const adc = join(gcloudDir, 'application_default_credentials.json');
+    if (await exists(adc))
+        return { kind: 'adc', path: adc };
+    const account = (await runner('gcloud', ['config', 'get', 'account'])).stdout.trim();
+    if (!account) {
+        throw new Error('no Google credentials: no application-default credentials file and no active gcloud account');
+    }
+    const keyFile = join(gcloudDir, 'legacy_credentials', account, 'adc.json');
+    if (await exists(keyFile))
+        return { kind: 'key-file', path: keyFile, account };
+    const token = (await must(runner, 'gcloud', ['auth', 'print-access-token'])).stdout.trim();
+    if (!token)
+        throw new Error('gcloud auth print-access-token returned nothing');
+    return { kind: 'access-token', token, account };
+}
+/** Short human description for the tool's progress line. */
+export function describeCredential(cred) {
+    switch (cred.kind) {
+        case 'adc':
+            return `application-default credentials (${cred.path})`;
+        case 'key-file':
+            return `gcloud stored key for ${cred.account}`;
+        case 'access-token':
+            return `gcloud access token for ${cred.account}`;
+    }
+}
+export function authClientFor(cred) {
+    if (cred.kind === 'access-token') {
+        const client = new OAuth2Client();
+        client.setCredentials({ access_token: cred.token });
+        return client;
+    }
+    return new GoogleAuth({ keyFilename: cred.path, scopes: CLOUD_SQL_SCOPES });
+}

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.1",
+  "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"