@steve31415/baselib 3.3.0 → 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/deploy/deploy.js

@@ -12,7 +12,7 @@ import { DEFAULT_ACCOUNT, loadConfig, loadHooks } from './config.js';
 import { must, mustJson } from './exec.js';
 import { openEvidence, PhaseTimer } from './evidence.js';
 import { acquireLock, clearHold, publishRetainedAssets, readHold, readReleaseRecord, releaseLock, verifyLock, writeReleaseRecord, } from './gcs.js';
-import { consistentBaseSha, servingStateOf, SHA40 } from './plan.js';
+import { consistentBaseSha, readServingState, SHA40 } from './plan.js';
 const RELEASE_DEADLINE_MS = 25 * 60_000;
 const IMAGE_DIGEST = /@sha256:[0-9a-f]{64}$/;
 export async function runDeploy(options) {
@@ -87,12 +87,9 @@ export async function runDeploy(options) {
         }
         const serving = [];
         for (const service of config.services) {
-            const described = await mustJson(runner, 'gcloud', [
-                'run', 'services', 'describe', service.name,
-                ...gcloudBase, '--region', config.region, '--format=json',
-            ]);
+            const { described, state } = await readServingState(runner, gcloudBase, config.region, service.name);
             await evidence.save(`${service.name}-before.json`, JSON.stringify(described, null, 2));
-            serving.push(servingStateOf(service.name, described));
+            serving.push(state);
         }
         const base = consistentBaseSha(serving, sha);
         if (!base.ok)

package/dist/deploy/plan.d.ts

@@ -1,4 +1,4 @@
-import type { ServingState } from './types.js';
+import type { Runner, ServingState } from './types.js';
 export declare const SHA40: RegExp;
 /** Lock staleness is judged from the GCS object's server-side timeCreated,
  *  never from anything the lock writer wrote (its clock may be wrong). */
@@ -41,8 +41,32 @@ export declare function pickRevisionForSha(revisions: unknown[], targetSha: stri
     revision: string;
     imageDigest: string;
 } | null;
-/** Extract serving state from a `gcloud run services describe --format=json`. */
-export declare function servingStateOf(service: string, described: unknown): ServingState;
+/** The one revision carrying 100% of traffic in a `gcloud run services
+ *  describe --format=json`, from *observed* traffic (`status.traffic`, never
+ *  `spec.traffic`, which is only the desired state). */
+export declare function servingRevisionName(service: string, described: unknown): string;
+/**
+ * Extract serving state from a `gcloud run services describe --format=json`.
+ *
+ * The serving revision's BUILD_ID and image are read from the service
+ * template only when that revision IS the latest created one. When it is
+ * not — a previous release created a revision that never took traffic (a
+ * failed secret-access check, a crashed startup, an aborted deploy) — the
+ * template describes the *wrong* revision, so the caller must pass that
+ * revision's own `gcloud run revisions describe --format=json` as
+ * `servingRevision` (readServingState does). Lesson 2026-09-04, watchdog2:
+ * a re-run after a failed traffic switch read the new SHA out of the
+ * template, logged "already serving", wrote the release record, and left
+ * the old revision serving.
+ */
+export declare function servingStateOf(service: string, described: unknown, servingRevision?: unknown): ServingState;
+/** Describe a service and resolve its serving state, describing the serving
+ *  revision too whenever the template no longer belongs to it. Returns the
+ *  raw service description as well, for evidence. */
+export declare function readServingState(runner: Runner, gcloudBase: string[], region: string, service: string): Promise<{
+    described: unknown;
+    state: ServingState;
+}>;
 export declare function contentTypeFor(path: string): string;
 /** Parse release-record listing rows into {sha, at} entries. */
 export declare function releaseEntriesFrom(rows: {

package/dist/deploy/plan.js

@@ -1,6 +1,7 @@
 // Pure decision logic for pw-deploy/pw-rollback: everything here is
 // side-effect-free so the concurrency-sensitive choices (lock staleness,
 // rollback targeting, serving-state consistency) are unit-tested directly.
+import { mustJson } from './exec.js';
 export const SHA40 = /^[0-9a-f]{40}$/;
 /** Lock staleness is judged from the GCS object's server-side timeCreated,
  *  never from anything the lock writer wrote (its clock may be wrong). */
@@ -101,22 +102,71 @@ export function pickRevisionForSha(revisions, targetSha) {
     matches.sort((a, b) => b.created - a.created);
     return matches[0] ? { revision: matches[0].revision, imageDigest: matches[0].imageDigest } : null;
 }
-/** Extract serving state from a `gcloud run services describe --format=json`. */
-export function servingStateOf(service, described) {
+/** The one revision carrying 100% of traffic in a `gcloud run services
+ *  describe --format=json`, from *observed* traffic (`status.traffic`, never
+ *  `spec.traffic`, which is only the desired state). */
+export function servingRevisionName(service, described) {
     const d = described;
     const active = (d.status?.traffic ?? []).filter((t) => (t.percent ?? 0) === 100);
     if (active.length !== 1 || !active[0].revisionName) {
         throw new Error(`${service}: expected exactly one 100% traffic target`);
     }
-    const env = d.spec?.template?.spec?.containers?.[0]?.env ?? [];
+    return active[0].revisionName;
+}
+/**
+ * Extract serving state from a `gcloud run services describe --format=json`.
+ *
+ * The serving revision's BUILD_ID and image are read from the service
+ * template only when that revision IS the latest created one. When it is
+ * not — a previous release created a revision that never took traffic (a
+ * failed secret-access check, a crashed startup, an aborted deploy) — the
+ * template describes the *wrong* revision, so the caller must pass that
+ * revision's own `gcloud run revisions describe --format=json` as
+ * `servingRevision` (readServingState does). Lesson 2026-09-04, watchdog2:
+ * a re-run after a failed traffic switch read the new SHA out of the
+ * template, logged "already serving", wrote the release record, and left
+ * the old revision serving.
+ */
+export function servingStateOf(service, described, servingRevision) {
+    const d = described;
+    const revision = servingRevisionName(service, described);
+    const latest = d.status?.latestCreatedRevisionName;
+    let container;
+    if (latest === undefined || latest === revision) {
+        container = d.spec?.template?.spec?.containers?.[0];
+    }
+    else if (servingRevision !== undefined) {
+        container = servingRevision.spec?.containers?.[0];
+    }
+    else {
+        throw new Error(`${service}: traffic serves ${revision} but the latest revision is ${latest}; ` +
+            'the serving revision must be described separately');
+    }
+    const env = container?.env ?? [];
     const buildSha = env.find((e) => e.name === 'BUILD_ID')?.value ?? null;
     return {
         service,
-        revision: active[0].revisionName,
+        revision,
         buildSha: buildSha !== null && SHA40.test(buildSha) ? buildSha : null,
-        imageDigest: d.spec?.template?.spec?.containers?.[0]?.image ?? null,
+        imageDigest: container?.image ?? null,
     };
 }
+/** Describe a service and resolve its serving state, describing the serving
+ *  revision too whenever the template no longer belongs to it. Returns the
+ *  raw service description as well, for evidence. */
+export async function readServingState(runner, gcloudBase, region, service) {
+    const described = await mustJson(runner, 'gcloud', [
+        'run', 'services', 'describe', service, ...gcloudBase, '--region', region, '--format=json',
+    ]);
+    const revision = servingRevisionName(service, described);
+    const latest = described.status?.latestCreatedRevisionName;
+    const servingRevision = latest !== undefined && latest !== revision
+        ? await mustJson(runner, 'gcloud', [
+            'run', 'revisions', 'describe', revision, ...gcloudBase, '--region', region, '--format=json',
+        ])
+        : undefined;
+    return { described, state: servingStateOf(service, described, servingRevision) };
+}
 const CONTENT_TYPES = {
     '.js': 'text/javascript',
     '.mjs': 'text/javascript',

package/dist/deploy/rollback.js

@@ -8,7 +8,7 @@ import { must, mustJson } from './exec.js';
 import { openEvidence, PhaseTimer } from './evidence.js';
 import { acquireLock, listReleaseRecords, placeHold, releaseLock } from './gcs.js';
 import { DEFAULT_ACCOUNT, loadConfig } from './config.js';
-import { pickRevisionForSha, releaseEntriesFrom, selectRollbackTarget, servingStateOf, SHA40, } from './plan.js';
+import { pickRevisionForSha, releaseEntriesFrom, selectRollbackTarget, readServingState, SHA40, } from './plan.js';
 export async function runRollback(options) {
     const log = options.log ?? ((m) => console.error(`[pw-rollback] ${m}`));
     const runner = options.runner;
@@ -39,11 +39,8 @@ export async function runRollback(options) {
         timer.enter('target');
         const serving = [];
         for (const service of config.services) {
-            const described = await mustJson(runner, 'gcloud', [
-                'run', 'services', 'describe', service.name,
-                ...gcloudBase, '--region', config.region, '--format=json',
-            ]);
-            serving.push(servingStateOf(service.name, described));
+            const { state } = await readServingState(runner, gcloudBase, config.region, service.name);
+            serving.push(state);
         }
         const evidence = await openEvidence(config.app, requested ?? serving[0].buildSha ?? 'rollback');
         evidenceDir = evidence.dir;

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 });
+}