@steve31415/baselib 3.4.0 → 3.5.0

package/README.md

@@ -6,8 +6,8 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `~/migration/research/base-services-design.md` (step 5).
 
 Server subpath exports: `config`, `log`, `auth`, `s2s`, `db`, `http`, `sync`,
-`app-update`, `llm`, and `email`. Browser exports: `log-browser`, `rum`, `sync-browser`, and
-`app-update-browser`.
+`app-update`, `llm`, and `email`. Browser exports: `log-browser`, `rum`,
+`slow-fetch`, `sync-browser`, and `app-update-browser`.
 
 `sync` provides the Postgres event-log and server protocol primitives;
 `sync-browser` provides the IndexedDB outbox and offline-first client.
@@ -34,4 +34,9 @@ deploy (`~/plasticine-way/docs/OPERATIONS.md`, "Deployment safety").
 first step of any production investigation (same doc, "Investigating
 production state").
 
+Releasing: bump `version`, commit, and run `npm run deploy` (Coder runs it
+automatically when integrating a baselib branch) — it pushes the `v<version>`
+tag, whose workflow gates on verify and publishes via OIDC, and waits for the
+registry (`~/plasticine-way/docs/OPERATIONS.md`, "Publishing baselib").
+
 Reflects Plasticine Way commit: see `docs/IMPL.md` footer.

package/dist/bin/release.d.ts

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

package/dist/bin/release.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// baselib's `npm run deploy` — release the checked-out version (tag push +
+// wait for the registry; the tag-triggered workflow does the actual
+// publish). All logic lives in ../release.ts.
+import { realRunner } from '../deploy/exec.js';
+import { release } from '../release.js';
+try {
+    await release(realRunner, {
+        log: (m) => console.log(m),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+}
+catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+}

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

@@ -1,4 +1,4 @@
-import { GoogleAuth, OAuth2Client } from 'google-auth-library';
+import { type AuthClient } from 'google-auth-library';
 import type { Runner } from '../deploy/types.js';
 export type GcpCredential = {
     kind: 'adc';
@@ -22,4 +22,16 @@ export interface CredentialDeps {
 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;
+/** The client the connector will mint the IAM login token from. Always a
+ *  concrete AuthClient (JWT for a service-account key, UserRefreshClient for
+ *  an authorized-user ADC file, OAuth2Client around a ready token), never a
+ *  GoogleAuth: the connector tells the two apart with `instanceof GoogleAuth`
+ *  against ITS copy of google-auth-library, and when a consumer's install
+ *  hoists a different copy than baselib's (coder2, 2026-09-04 — connector
+ *  1.12 wants ^11, baselib ^10) a GoogleAuth of ours fails that check, gets
+ *  wrapped as if it were an AuthClient, and the wrapper's getAccessToken()
+ *  reads `.token` off the bare string GoogleAuth returns: "Failed to get
+ *  access token for automatic IAM authentication". An AuthClient crosses the
+ *  package boundary by duck typing alone, so the client carries both Cloud
+ *  SQL scopes itself rather than relying on the wrapper's. */
+export declare function authClientFor(cred: GcpCredential): Promise<AuthClient>;

package/dist/ops/gcp-auth.js

@@ -54,11 +54,23 @@ export function describeCredential(cred) {
             return `gcloud access token for ${cred.account}`;
     }
 }
-export function authClientFor(cred) {
+/** The client the connector will mint the IAM login token from. Always a
+ *  concrete AuthClient (JWT for a service-account key, UserRefreshClient for
+ *  an authorized-user ADC file, OAuth2Client around a ready token), never a
+ *  GoogleAuth: the connector tells the two apart with `instanceof GoogleAuth`
+ *  against ITS copy of google-auth-library, and when a consumer's install
+ *  hoists a different copy than baselib's (coder2, 2026-09-04 — connector
+ *  1.12 wants ^11, baselib ^10) a GoogleAuth of ours fails that check, gets
+ *  wrapped as if it were an AuthClient, and the wrapper's getAccessToken()
+ *  reads `.token` off the bare string GoogleAuth returns: "Failed to get
+ *  access token for automatic IAM authentication". An AuthClient crosses the
+ *  package boundary by duck typing alone, so the client carries both Cloud
+ *  SQL scopes itself rather than relying on the wrapper's. */
+export async 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 });
+    return new GoogleAuth({ keyFilename: cred.path, scopes: CLOUD_SQL_SCOPES }).getClient();
 }

package/dist/ops/sql.js

@@ -104,7 +104,7 @@ function outputTypes() {
 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 { options: connection, connector } = await cloudSqlClientOptions(target.instance, await authClientFor(cred));
     const client = new pg.Client({
         ...connection,
         user: target.user,

package/dist/release.d.ts

@@ -0,0 +1,15 @@
+import type { Runner } from './deploy/types.js';
+export declare const PUBLISH_POLL_MS = 20000;
+export declare const PUBLISH_TIMEOUT_MS: number;
+export interface ReleaseIo {
+    log: (message: string) => void;
+    sleep: (ms: number) => Promise<void>;
+}
+export interface ReleaseOptions {
+    cwd?: string;
+    pollMs?: number;
+    timeoutMs?: number;
+}
+/** Release the checked-out version; throws (with a pointer to the publish
+ *  workflow) on drift or when the registry never serves it. */
+export declare function release(runner: Runner, io: ReleaseIo, opts?: ReleaseOptions): Promise<void>;

package/dist/release.js

@@ -0,0 +1,81 @@
+// baselib's own `npm run deploy`: release the version in package.json by
+// pushing the `v<version>` tag and waiting for the registry to serve it.
+// The actual publish stays where it is — the tag triggers
+// .github/workflows/publish.yml, which gates on `npm run verify` and
+// publishes via npm Trusted Publishing (OIDC) — so this script adds no
+// publish authority; it only automates the tag push that used to be
+// Steve's manual step (decision 2026-09-06). Giving baselib a `deploy`
+// script also slots releases into Coder's ordered per-project deploys:
+// a task can bump baselib and, once it serves, deploy consumers after it.
+//
+// Idempotent and drift-guarded:
+// - version already on the registry, no source drift since its tag → no-op
+//   (docs-only changes release nothing);
+// - version already on the registry but src/ or package.json changed since
+//   its tag → FAIL loudly ("bump the version") instead of silently shipping
+//   nothing;
+// - tag already pushed but not yet on the registry (a publish in flight, or
+//   a rerun after a workflow failure) → skip the push, wait for the registry.
+import { readFileSync } from 'node:fs';
+import { must } from './deploy/exec.js';
+const PACKAGE = '@steve31415/baselib';
+const ACTIONS_URL = 'https://github.com/plasticine-apps/baselib/actions';
+export const PUBLISH_POLL_MS = 20_000;
+export const PUBLISH_TIMEOUT_MS = 15 * 60_000;
+// Files whose change must not go unreleased. docs/, test/, and workflow
+// changes ride along with the next real release.
+const RELEASED_PATHS = ['src', 'package.json', 'package-lock.json'];
+/** The version on the registry for `spec`, or null when absent. */
+async function publishedVersion(runner, version, cwd) {
+    const r = await runner('npm', ['view', `${PACKAGE}@${version}`, 'version'], { cwd });
+    const out = r.stdout.trim();
+    return r.code === 0 && out === version ? version : null;
+}
+async function tagOnOrigin(runner, tag, cwd) {
+    const r = await must(runner, 'git', ['ls-remote', 'origin', `refs/tags/${tag}`], { cwd });
+    return r.stdout.trim().length > 0;
+}
+/** Release the checked-out version; throws (with a pointer to the publish
+ *  workflow) on drift or when the registry never serves it. */
+export async function release(runner, io, opts = {}) {
+    const cwd = opts.cwd;
+    const pkg = JSON.parse(readFileSync(`${cwd ?? '.'}/package.json`, 'utf8'));
+    if (!pkg.version)
+        throw new Error('package.json has no version');
+    const version = pkg.version;
+    const tag = `v${version}`;
+    if (await publishedVersion(runner, version, cwd)) {
+        // Already released. Guard the footgun: released paths changed since the
+        // tag means someone forgot the bump — fail rather than silently ship
+        // nothing. (Ensure the tag exists locally first; a fresh clone may not
+        // have fetched it.)
+        const local = await runner('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], { cwd });
+        if (local.code !== 0)
+            await must(runner, 'git', ['fetch', 'origin', 'tag', tag], { cwd });
+        const drift = await runner('git', ['diff', '--quiet', tag, 'HEAD', '--', ...RELEASED_PATHS], { cwd });
+        if (drift.code !== 0) {
+            throw new Error(`${RELEASED_PATHS.join('/')} changed since ${tag} was released — bump the version in package.json to release the change`);
+        }
+        io.log(`${PACKAGE}@${version} is already on the registry and matches ${tag}; nothing to release`);
+        return;
+    }
+    if (await tagOnOrigin(runner, tag, cwd)) {
+        io.log(`tag ${tag} is already on origin (publish in flight or previously failed); waiting for the registry`);
+    }
+    else {
+        await must(runner, 'git', ['tag', tag], { cwd });
+        await must(runner, 'git', ['push', 'origin', tag], { cwd });
+        io.log(`pushed ${tag}; the publish workflow (verify gate + OIDC publish) is running`);
+    }
+    const timeoutMs = opts.timeoutMs ?? PUBLISH_TIMEOUT_MS;
+    const pollMs = opts.pollMs ?? PUBLISH_POLL_MS;
+    for (let waited = 0; waited < timeoutMs; waited += pollMs) {
+        await io.sleep(pollMs);
+        if (await publishedVersion(runner, version, cwd)) {
+            io.log(`${PACKAGE}@${version} is live on the registry`);
+            return;
+        }
+        io.log(`waiting for ${PACKAGE}@${version} on the registry (${Math.round((waited + pollMs) / 1000)}s)`);
+    }
+    throw new Error(`${PACKAGE}@${version} did not appear on the registry within ${Math.round(timeoutMs / 60_000)} min — check the publish workflow: ${ACTIONS_URL}`);
+}

package/dist/slow-fetch.d.ts

@@ -0,0 +1,21 @@
+import { type Logger } from './log-core.js';
+export declare const DEFAULT_SLOW_FETCH_MS = 2000;
+export declare const DEFAULT_MAX_REPORTS_PER_PAGE = 20;
+export interface SlowFetchOptions {
+    /** Successful fetches at or above this many ms are logged (default 2000). */
+    slowMs?: number;
+    /** Ceiling on reports per page life, slow and failed combined (default 20). */
+    maxReportsPerPage?: number;
+}
+/** Wire the reporter once at startup; until then reportFetchOutcome no-ops
+ *  (so unit tests exercising the fetch wrapper stay silent). Also widens the
+ *  resource-timing buffer and clears it when full: a polling app fills the
+ *  default 250-entry buffer within minutes, after which timing lookups come
+ *  back empty for the rest of the tab's life. Nothing else reads resource
+ *  entries; if a consumer does, it should own the buffer instead. */
+export declare function initSlowFetchLogging(l: Logger, opts?: SlowFetchOptions): void;
+/** Call on every fetch settle from the app's fetch wrapper. Logs the slow
+ *  successes and the failures; fast successes and deliberate aborts are
+ *  silent. `status` is the HTTP status on success, null on rejection;
+ *  `error` is the thrown value on rejection, omitted on success. */
+export declare function reportFetchOutcome(path: string, method: string, startedMs: number, status: number | null, error?: unknown): void;

package/dist/slow-fetch.js

@@ -0,0 +1,87 @@
+// Diagnostic timing for slow or failed browser fetches. A request can stall
+// entirely client-side — dead connection reuse after an idle gap, QUIC→TCP
+// fallback, DNS — where server logs show nothing: a coder2 enqueue on
+// 2026-09-06 took ~10 s at the browser against 0.94 s on the server, and no
+// log could attribute the gap. An app wires reportFetchOutcome into its own
+// fetch wrapper (the one place all API traffic settles); any fetch slower
+// than the threshold, or one that rejects, ships a browser log carrying the
+// Resource Timing milestones — connection setup vs first-byte wait vs
+// download, plus the negotiated protocol (h2 vs h3) — which is exactly the
+// split those incidents need.
+//
+// Browser-only module — do not import server-side.
+import { serializeError } from './log-core.js';
+export const DEFAULT_SLOW_FETCH_MS = 2000;
+// A broken network could make every poll slow: cap the reports per page life.
+export const DEFAULT_MAX_REPORTS_PER_PAGE = 20;
+let logger = null;
+let slowMs = DEFAULT_SLOW_FETCH_MS;
+let maxReports = DEFAULT_MAX_REPORTS_PER_PAGE;
+let reported = 0;
+/** Wire the reporter once at startup; until then reportFetchOutcome no-ops
+ *  (so unit tests exercising the fetch wrapper stay silent). Also widens the
+ *  resource-timing buffer and clears it when full: a polling app fills the
+ *  default 250-entry buffer within minutes, after which timing lookups come
+ *  back empty for the rest of the tab's life. Nothing else reads resource
+ *  entries; if a consumer does, it should own the buffer instead. */
+export function initSlowFetchLogging(l, opts = {}) {
+    logger = l;
+    slowMs = opts.slowMs ?? DEFAULT_SLOW_FETCH_MS;
+    maxReports = opts.maxReportsPerPage ?? DEFAULT_MAX_REPORTS_PER_PAGE;
+    reported = 0;
+    performance.setResourceTimingBufferSize?.(1000);
+    performance.addEventListener?.('resourcetimingbufferfull', () => performance.clearResourceTimings());
+}
+/** The fetch's Resource Timing milestones, ms relative to its start; null
+ *  when the entry is gone (a failed request records none, or the buffer was
+ *  cleared) or the environment lacks the API. A milestone of null means the
+ *  phase was absent — e.g. no connect_* on a reused connection. */
+function timingFor(url, startedMs, endedMs) {
+    if (typeof performance.getEntriesByName !== 'function')
+        return null;
+    const entries = performance.getEntriesByName(url, 'resource');
+    // Polls reuse URLs: take the last entry that started in this fetch's window.
+    const entry = entries.filter((e) => e.startTime >= startedMs - 50 && e.startTime <= endedMs).at(-1);
+    if (!entry)
+        return null;
+    const rel = (t) => (t === 0 ? null : Math.round(t - entry.startTime));
+    return {
+        protocol: entry.nextHopProtocol || null,
+        fetch_start_ms: rel(entry.fetchStart),
+        domain_lookup_start_ms: rel(entry.domainLookupStart),
+        connect_start_ms: rel(entry.connectStart),
+        secure_connection_start_ms: rel(entry.secureConnectionStart),
+        connect_end_ms: rel(entry.connectEnd),
+        request_start_ms: rel(entry.requestStart),
+        response_start_ms: rel(entry.responseStart),
+        response_end_ms: rel(entry.responseEnd),
+        transfer_size: entry.transferSize,
+    };
+}
+/** Call on every fetch settle from the app's fetch wrapper. Logs the slow
+ *  successes and the failures; fast successes and deliberate aborts are
+ *  silent. `status` is the HTTP status on success, null on rejection;
+ *  `error` is the thrown value on rejection, omitted on success. */
+export function reportFetchOutcome(path, method, startedMs, status, error) {
+    if (!logger || reported >= maxReports)
+        return;
+    // Deliberate aborts (a page navigation cancelling its poll) are not failures.
+    if (error instanceof DOMException && error.name === 'AbortError')
+        return;
+    const endedMs = performance.now();
+    const durationMs = Math.round(endedMs - startedMs);
+    const failed = error !== undefined;
+    if (!failed && durationMs < slowMs)
+        return;
+    reported += 1;
+    logger.warn(failed ? 'fetch_failed' : 'slow_fetch', {
+        path,
+        method,
+        status,
+        duration_ms: durationMs,
+        online: navigator.onLine,
+        visibility: document.visibilityState,
+        ...(failed ? { error: serializeError(error) } : {}),
+        timing: timingFor(new URL(path, location.href).href, startedMs, endedMs),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,10 @@
       "types": "./dist/rum.d.ts",
       "default": "./dist/rum.js"
     },
+    "./slow-fetch": {
+      "types": "./dist/slow-fetch.d.ts",
+      "default": "./dist/slow-fetch.js"
+    },
     "./sync": {
       "types": "./dist/sync/index.d.ts",
       "default": "./dist/sync/index.js"
@@ -82,6 +86,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "deploy": "tsx src/bin/release.ts",
     "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",