@steve31415/baselib 3.47.1 → 3.48.1

package/README.md

@@ -6,8 +6,9 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `~/migration/research/base-services-design.md`.
 
 Server subpath exports: `config`, `log`, `auth`, `oauth-resource`, `connector`, `s2s`, `db`, `http`, `sync`,
-`app-update`, `llm`, `email`, `twitter`, and `hub` (the connection hub's server core and app notifier). Browser exports: `log-browser`, `rum`,
-`slow-fetch`, `sync-browser`, and `app-update-browser`.
+`app-update`, `llm`, `email`, `twitter`, `hub` (the connection hub's server core and app notifier), `code-manifest` and
+`client-version`. Browser exports: `log-browser`, `rum`, `slow-fetch`, `sync-browser`, `app-update-browser`, and
+`extension-self-update`.
 
 `sync` provides the Postgres event-log and server protocol primitives;
 `sync-browser` provides the IndexedDB outbox and offline-first client.
@@ -36,6 +37,15 @@ app's hooks module (`DeployHooks` in `src/deploy/types.ts`) extends both,
 first step of any production investigation (same doc, "Investigating
 production state").
 
+Mac-run code (`~/plasticine-way/mac/sync/DESIGN.md`): `code-manifest` and the
+`pw-code-manifest` bin write and check a directory's `mac-code.json` (its
+tracked files' sha256 and one id); `extension-self-update` reloads an unpacked
+extension into code that verifies on disk and that its server says it
+deployed; `client-version` counts how long a Mac-run client has stayed behind
+while reporting continuously, for the "stayed behind" WARN. `pw-deploy` marks
+a running deploy in the git common dir (`pw-deploy.lock`) so the Mac's sync
+job does not fast-forward the checkout under the build.
+
 `twitter` provides Mirror-first tweet lookup, TwitterAPI.io batch/search/
 article calls, and thread assembly through direct reply edges. It includes
 one level of quotes, article bodies and URL expansions. Use one shared

package/dist/bin/pw-code-manifest.d.ts

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

package/dist/bin/pw-code-manifest.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// `pw-code-manifest` — write or check a directory's mac-code.json (../code-manifest.ts;
+// plasticine-way mac/sync/DESIGN.md §3.3).
+//
+//   pw-code-manifest write <dir> [--exclude <pattern>]...   regenerate it
+//   pw-code-manifest check <dir> [--exclude <pattern>]...   exit 1 when it is stale (run by verify)
+//   pw-code-manifest id <dir>    [--exclude <pattern>]...   print the id of the files as they are now
+import { runCodeManifestCli } from '../code-manifest.js';
+process.exitCode = await runCodeManifestCli(process.argv.slice(2), process.cwd());

package/dist/client-version.d.ts

@@ -0,0 +1,52 @@
+/** Behind for this long, counted as above, before the first WARN. Expected is under 15 minutes. */
+export declare const BEHIND_WARN_MS: number;
+/** Further counted time before the WARN repeats. */
+export declare const BEHIND_REWARN_MS: number;
+export interface BehindState {
+    /** Counted time behind in this episode. */
+    behindMs: number;
+    /** Server time of the last report in this episode. */
+    lastAt: number;
+    /** behindMs at the last WARN in this episode, or null before the first. */
+    warnedAtMs: number | null;
+}
+export type BehindCause = 'switch_not_taken' | 'checkout_not_current';
+/**
+ * Why a client is behind, or null when it is not. `loaded`: the code the client
+ * runs (null or absent when it does not report one, e.g. a version from before
+ * code reports, which counts as behind). `disk`: the verified code on the Mac's
+ * disk (null when it does not verify). `shipped`: the code this server deployed.
+ */
+export declare function behindCause(report: {
+    loaded: string | null | undefined;
+    disk: string | null | undefined;
+    shipped: string;
+}): BehindCause | null;
+/** The gap cap for a client that reports every `intervalMs`. */
+export declare function gapCapFor(intervalMs: number): number;
+/** Fold one report into the episode. Returns null when the client is not behind (the episode ends). */
+export declare function accrueBehind(prev: BehindState | null, report: {
+    behind: boolean;
+    now: number;
+    gapCapMs: number;
+}): BehindState | null;
+/** Whether this state warrants a WARN now; when it does, the returned state records it. */
+export declare function shouldWarn(state: BehindState, limits?: {
+    thresholdMs?: number;
+    rewarnMs?: number;
+}): {
+    warn: boolean;
+    state: BehindState;
+};
+/** accrueBehind then shouldWarn: the one call an app makes per report. */
+export declare function recordBehind(prev: BehindState | null, report: {
+    behind: boolean;
+    now: number;
+    intervalMs: number;
+}, limits?: {
+    thresholdMs?: number;
+    rewarnMs?: number;
+}): {
+    state: BehindState | null;
+    warn: boolean;
+};

package/dist/client-version.js

@@ -0,0 +1,54 @@
+// "Stayed behind" accounting for code that runs on Steve's Mac (plasticine-way
+// mac/sync/DESIGN.md §3.6). Pure: each app persists the state per device and
+// calls this from the request that carries the device's report.
+//
+// A client is behind when the code it runs is not the code the server
+// deployed. The time that counts is time the client spent behind while
+// REPORTING CONTINUOUSLY: a report adds the gap since the previous one only
+// when that gap is at most `gapCapMs` (1.5 x the client's report interval).
+// A laptop asleep, offline or travelling contributes nothing, however long
+// (Steve, 2026-11-01: the laptop can easily be offline for 12 hours or more).
+// All times are the server's clock.
+/** Behind for this long, counted as above, before the first WARN. Expected is under 15 minutes. */
+export const BEHIND_WARN_MS = 4 * 60 * 60 * 1000;
+/** Further counted time before the WARN repeats. */
+export const BEHIND_REWARN_MS = 24 * 60 * 60 * 1000;
+/**
+ * Why a client is behind, or null when it is not. `loaded`: the code the client
+ * runs (null or absent when it does not report one, e.g. a version from before
+ * code reports, which counts as behind). `disk`: the verified code on the Mac's
+ * disk (null when it does not verify). `shipped`: the code this server deployed.
+ */
+export function behindCause(report) {
+    if (report.loaded === report.shipped)
+        return null;
+    return report.disk === report.shipped ? 'switch_not_taken' : 'checkout_not_current';
+}
+/** The gap cap for a client that reports every `intervalMs`. */
+export function gapCapFor(intervalMs) {
+    return Math.round(intervalMs * 1.5);
+}
+/** Fold one report into the episode. Returns null when the client is not behind (the episode ends). */
+export function accrueBehind(prev, report) {
+    if (!report.behind)
+        return null;
+    if (!prev)
+        return { behindMs: 0, lastAt: report.now, warnedAtMs: null };
+    const gap = report.now - prev.lastAt;
+    const counted = gap > 0 && gap <= report.gapCapMs ? gap : 0;
+    return { behindMs: prev.behindMs + counted, lastAt: Math.max(prev.lastAt, report.now), warnedAtMs: prev.warnedAtMs };
+}
+/** Whether this state warrants a WARN now; when it does, the returned state records it. */
+export function shouldWarn(state, limits = {}) {
+    const threshold = limits.thresholdMs ?? BEHIND_WARN_MS;
+    const rewarn = limits.rewarnMs ?? BEHIND_REWARN_MS;
+    const due = state.warnedAtMs === null ? state.behindMs >= threshold : state.behindMs - state.warnedAtMs >= rewarn;
+    return due ? { warn: true, state: { ...state, warnedAtMs: state.behindMs } } : { warn: false, state };
+}
+/** accrueBehind then shouldWarn: the one call an app makes per report. */
+export function recordBehind(prev, report, limits = {}) {
+    const state = accrueBehind(prev, { behind: report.behind, now: report.now, gapCapMs: gapCapFor(report.intervalMs) });
+    if (!state)
+        return { state: null, warn: false };
+    return shouldWarn(state, limits);
+}

package/dist/code-manifest.d.ts

@@ -0,0 +1,37 @@
+export declare const CODE_MANIFEST_FILE = "mac-code.json";
+export interface CodeManifest {
+    id: string;
+    files: Record<string, string>;
+}
+export interface CodeManifestOptions {
+    /** Paths to leave out, relative to the directory: `dir/` (a prefix), or a
+     *  glob where `*` matches within one path segment and `**` across segments. */
+    exclude?: string[];
+}
+/** The id over a file list (the browser twin is in extension-self-update). */
+export declare function codeIdOf(files: Record<string, string>): string;
+export declare function isExcluded(path: string, exclude?: string[]): boolean;
+/** Build the manifest for `dir` from git's tracked files as they are in the work tree. */
+export declare function buildCodeManifest(dir: string, options?: CodeManifestOptions): Promise<CodeManifest>;
+export declare function serializeCodeManifest(manifest: CodeManifest): string;
+export declare function writeCodeManifest(dir: string, options?: CodeManifestOptions): Promise<CodeManifest>;
+export interface CodeManifestCheck {
+    ok: boolean;
+    /** Paths added, removed or changed since the committed manifest was written. */
+    changed: string[];
+    committedId: string | null;
+    currentId: string;
+}
+/** Is the committed manifest current? (Run by each repo's verify.) */
+export declare function checkCodeManifest(dir: string, options?: CodeManifestOptions): Promise<CodeManifestCheck>;
+/** The committed manifest in `dir`, or null when absent or malformed. */
+export declare function readCodeManifest(dir: string): Promise<CodeManifest | null>;
+/**
+ * For a Node consumer reading its own directory (no git needed): the
+ * manifest's id when every listed file is present and matches and the id is
+ * the id of the list; null otherwise (a checkout in progress, a local edit, a
+ * missing or hand-edited manifest).
+ */
+export declare function verifyCodeManifestOnDisk(dir: string): Promise<string | null>;
+/** The `pw-code-manifest` command (src/bin/pw-code-manifest.ts). Returns the exit code. */
+export declare function runCodeManifestCli(argv: string[], cwd: string, out?: (line: string) => void, err?: (line: string) => void): Promise<number>;

package/dist/code-manifest.js

@@ -0,0 +1,176 @@
+// Code manifests: a committed list of a directory's files and their sha256, with
+// one id over the list (plasticine-way mac/sync/DESIGN.md §3.3).
+//
+// Steve's Mac runs extensions and daemons straight from git checkouts. Each of
+// those consumers switches to new code only when the code on disk verifies
+// against `mac-code.json` AND its id is the one the app's server says it
+// deployed. So the id must be computable three ways that agree: here (the
+// generator, the verify-time check, and server builds), in the browser
+// (`extension-self-update`), and in a Node consumer reading its own files
+// (`verifyCodeManifestOnDisk`).
+//
+// The id is sha256 over the sorted lines `<path>\0<sha256>\n`, first 16 hex
+// characters. Paths are relative to the directory, `/`-separated, and are
+// git's tracked files only, so untracked leftovers (.DS_Store, *.orig) never
+// change it. The manifest file itself is never listed.
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const CODE_MANIFEST_FILE = 'mac-code.json';
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** The id over a file list (the browser twin is in extension-self-update). */
+export function codeIdOf(files) {
+    const lines = Object.keys(files)
+        .sort()
+        .map((path) => `${path}\0${files[path]}\n`)
+        .join('');
+    return sha256Hex(lines).slice(0, 16);
+}
+function globToRegExp(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*' && glob[i + 1] === '*') {
+            out += '.*';
+            i++;
+            if (glob[i + 1] === '/')
+                i++;
+        }
+        else if (c === '*') {
+            out += '[^/]*';
+        }
+        else {
+            out += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+export function isExcluded(path, exclude = []) {
+    return exclude.some((pattern) => pattern.endsWith('/') ? path.startsWith(pattern) : globToRegExp(pattern).test(path));
+}
+function gitLsFiles(dir) {
+    return new Promise((resolve, reject) => {
+        execFile('git', ['ls-files', '-z', '--', '.'], { cwd: dir, maxBuffer: 64 * 1024 * 1024 }, (error, stdout) => {
+            if (error)
+                reject(new Error(`git ls-files failed in ${dir}: ${error.message}`));
+            else
+                resolve(stdout.split('\0').filter((p) => p !== ''));
+        });
+    });
+}
+/** Build the manifest for `dir` from git's tracked files as they are in the work tree. */
+export async function buildCodeManifest(dir, options = {}) {
+    const paths = (await gitLsFiles(dir))
+        .filter((path) => path !== CODE_MANIFEST_FILE && !isExcluded(path, options.exclude))
+        .sort();
+    const files = {};
+    for (const path of paths)
+        files[path] = sha256Hex(await readFile(join(dir, path)));
+    return { id: codeIdOf(files), files };
+}
+export function serializeCodeManifest(manifest) {
+    return `${JSON.stringify({ id: manifest.id, files: manifest.files }, null, 2)}\n`;
+}
+export async function writeCodeManifest(dir, options = {}) {
+    const manifest = await buildCodeManifest(dir, options);
+    const target = join(dir, CODE_MANIFEST_FILE);
+    await writeFile(`${target}.tmp`, serializeCodeManifest(manifest));
+    await rename(`${target}.tmp`, target);
+    return manifest;
+}
+/** Is the committed manifest current? (Run by each repo's verify.) */
+export async function checkCodeManifest(dir, options = {}) {
+    const current = await buildCodeManifest(dir, options);
+    const committed = await readCodeManifest(dir);
+    const before = committed?.files ?? {};
+    const changed = [...new Set([...Object.keys(before), ...Object.keys(current.files)])]
+        .filter((path) => before[path] !== current.files[path])
+        .sort();
+    return { ok: committed !== null && changed.length === 0 && committed.id === current.id, changed, committedId: committed?.id ?? null, currentId: current.id };
+}
+/** The committed manifest in `dir`, or null when absent or malformed. */
+export async function readCodeManifest(dir) {
+    let raw;
+    try {
+        raw = await readFile(join(dir, CODE_MANIFEST_FILE), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const { id, files } = parsed;
+        if (typeof id !== 'string' || !files || typeof files !== 'object')
+            return null;
+        for (const value of Object.values(files))
+            if (typeof value !== 'string')
+                return null;
+        return { id, files: files };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * For a Node consumer reading its own directory (no git needed): the
+ * manifest's id when every listed file is present and matches and the id is
+ * the id of the list; null otherwise (a checkout in progress, a local edit, a
+ * missing or hand-edited manifest).
+ */
+export async function verifyCodeManifestOnDisk(dir) {
+    const manifest = await readCodeManifest(dir);
+    if (!manifest || codeIdOf(manifest.files) !== manifest.id)
+        return null;
+    for (const [path, expected] of Object.entries(manifest.files)) {
+        let bytes;
+        try {
+            bytes = await readFile(join(dir, path));
+        }
+        catch {
+            return null;
+        }
+        if (sha256Hex(bytes) !== expected)
+            return null;
+    }
+    return manifest.id;
+}
+/** The `pw-code-manifest` command (src/bin/pw-code-manifest.ts). Returns the exit code. */
+export async function runCodeManifestCli(argv, cwd, out = (line) => console.log(line), err = (line) => console.error(line)) {
+    const [command, dirArg, ...rest] = argv;
+    const exclude = [];
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--exclude' && rest[i + 1] !== undefined)
+            exclude.push(rest[++i]);
+        else {
+            err(`pw-code-manifest: unexpected argument ${rest[i]}`);
+            return 2;
+        }
+    }
+    if (!dirArg || !['write', 'check', 'id'].includes(command ?? '')) {
+        err('usage: pw-code-manifest write|check|id <dir> [--exclude <pattern>]...');
+        return 2;
+    }
+    const dir = join(cwd, dirArg);
+    if (command === 'write') {
+        const manifest = await writeCodeManifest(dir, { exclude });
+        out(`${join(dirArg, CODE_MANIFEST_FILE)}: ${manifest.id} (${Object.keys(manifest.files).length} files)`);
+        return 0;
+    }
+    if (command === 'id') {
+        out((await buildCodeManifest(dir, { exclude })).id);
+        return 0;
+    }
+    const check = await checkCodeManifest(dir, { exclude });
+    if (check.ok) {
+        out(`${join(dirArg, CODE_MANIFEST_FILE)} is current (${check.currentId})`);
+        return 0;
+    }
+    err(`${join(dirArg, CODE_MANIFEST_FILE)} is stale${check.committedId ? '' : ' or missing'}: ${check.changed.slice(0, 20).join(', ') || '(id mismatch)'}`);
+    err(`Regenerate it: npx pw-code-manifest write ${dirArg}${exclude.map((p) => ` --exclude '${p}'`).join('')}`);
+    return 1;
+}

package/dist/deploy/deploy-marker.d.ts

@@ -0,0 +1,5 @@
+export declare const DEPLOY_MARKER_FILE = "pw-deploy.lock";
+/** The git common dir of `repoRoot`, without running git; null outside a checkout. */
+export declare function gitCommonDir(repoRoot: string): Promise<string | null>;
+/** Write the marker; returns a remover (a no-op outside a git checkout). Never throws. */
+export declare function writeDeployMarker(repoRoot: string, now?: Date): Promise<() => Promise<void>>;

package/dist/deploy/deploy-marker.js

@@ -0,0 +1,63 @@
+// The "a deploy is running from this checkout" marker (plasticine-way
+// mac/sync/DESIGN.md §3.2).
+//
+// pw-deploy checks the tree once at preflight and then builds from the live
+// work tree for minutes. On Steve's Mac a LaunchAgent fast-forwards the main
+// checkouts of Mac-run repos (the containers' ~ is that folder), which could
+// change files under a running build. So pw-deploy writes this marker into the
+// git common dir — shared by the Mac's git and the containers', never part of
+// the work tree — and removes it when the deploy ends; the job skips a repo
+// whose marker is younger than 2 hours.
+import { readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+export const DEPLOY_MARKER_FILE = 'pw-deploy.lock';
+/** The git common dir of `repoRoot`, without running git; null outside a checkout. */
+export async function gitCommonDir(repoRoot) {
+    const dotGit = join(repoRoot, '.git');
+    let info;
+    try {
+        info = await stat(dotGit);
+    }
+    catch {
+        return null;
+    }
+    if (info.isDirectory())
+        return dotGit;
+    // A worktree: `.git` is a file "gitdir: <path>", and that dir names the common dir in `commondir`.
+    const pointer = (await readFile(dotGit, 'utf8')).match(/^gitdir:\s*(.+)\s*$/m)?.[1];
+    if (!pointer)
+        return null;
+    const gitDir = isAbsolute(pointer) ? pointer : resolve(repoRoot, pointer);
+    try {
+        const common = (await readFile(join(gitDir, 'commondir'), 'utf8')).trim();
+        return isAbsolute(common) ? common : resolve(gitDir, common);
+    }
+    catch {
+        return dirname(dirname(gitDir));
+    }
+}
+/** Write the marker; returns a remover (a no-op outside a git checkout). Never throws. */
+export async function writeDeployMarker(repoRoot, now = new Date()) {
+    const dir = await gitCommonDir(repoRoot).catch(() => null);
+    if (!dir)
+        return async () => { };
+    const path = join(dir, DEPLOY_MARKER_FILE);
+    const body = `${JSON.stringify({ pid: process.pid, host: hostname(), repo: repoRoot, startedAt: now.toISOString() })}\n`;
+    try {
+        await writeFile(path, body);
+    }
+    catch {
+        return async () => { };
+    }
+    return async () => {
+        // Remove only our own marker: a second deploy may have replaced it.
+        try {
+            if ((await readFile(path, 'utf8')) === body)
+                await rm(path, { force: true });
+        }
+        catch {
+            // already gone
+        }
+    };
+}

package/dist/deploy/deploy.js

@@ -13,6 +13,7 @@ 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, readServingState, SHA40 } from './plan.js';
+import { writeDeployMarker } from './deploy-marker.js';
 const RELEASE_DEADLINE_MS = 25 * 60_000;
 const IMAGE_DIGEST = /@sha256:[0-9a-f]{64}$/;
 const MAX_DIRTY_PATHS = 20;
@@ -40,6 +41,8 @@ export async function runDeploy(options) {
     let trafficMoved = false;
     let evidenceDir = '';
     let lock = null;
+    // Tells the Mac's checkout-sync job not to fast-forward this checkout under the build (deploy-marker.ts).
+    const removeDeployMarker = await writeDeployMarker(options.repoRoot);
     try {
         // ---- preflight ----
         const config = await loadConfig(options.repoRoot);
@@ -440,5 +443,6 @@ export async function runDeploy(options) {
     finally {
         if (lock)
             await releaseLock(runner, lock);
+        await removeDeployMarker();
     }
 }

package/dist/extension-self-update.d.ts

@@ -0,0 +1,75 @@
+export declare const STABLE_MS: number;
+export declare const RETRY_MS: number;
+/**
+ * How long one renewal keeps the extension busy. Renewals come every ~10 s from
+ * an open overlay, but Chrome's intensive throttling slows a page's chained
+ * timers to one wake-up a minute once its tab has been hidden 5 minutes, so the
+ * lease must outlast a 60 s gap with room to spare (an overlay left open in a
+ * background tab must still hold off a reload).
+ */
+export declare const BUSY_LEASE_MS: number;
+export declare const CODE_MANIFEST_FILE = "mac-code.json";
+/** chrome.storage.session: { code, since } — the shipped code first seen verified on disk. */
+export declare const SEEN_KEY = "selfUpdateSeen";
+/** chrome.storage.local: { code, at } — the last reload this extension asked for. */
+export declare const ATTEMPT_KEY = "selfUpdateAttempt";
+/** chrome.storage.local: { code, version } — the code Chrome loaded (written when it loads). */
+export declare const LOADED_KEY = "selfUpdateLoaded";
+/** chrome.storage.session: epoch ms until which the extension is busy (an open overlay renews it). */
+export declare const BUSY_LEASE_KEY = "selfUpdateBusyUntil";
+interface Seen {
+    code: string;
+    since: number;
+}
+interface Attempt {
+    code: string;
+    at: number;
+}
+export declare function sha256Hex(data: ArrayBuffer | string): Promise<string>;
+/** The id over a file list; the same algorithm as baselib code-manifest's codeIdOf. */
+export declare function codeIdOf(files: Record<string, string>): Promise<string>;
+/**
+ * The code on disk now: the manifest's id when every listed file is present and
+ * matches and the id is the id of the list; null otherwise (a merge in
+ * progress, a local edit, no manifest). An extension URL reads the folder as
+ * it is now (measured 2026-10-31).
+ */
+export declare function diskCode(): Promise<string | null>;
+/**
+ * Record the code Chrome just loaded. Call from runtime.onInstalled and
+ * runtime.onStartup — the moments Chrome reads the extension from disk — and
+ * nowhere else: a worker restarting after eviction runs the code loaded
+ * earlier, whatever the disk holds now.
+ */
+export declare function recordLoadedCode(): Promise<string>;
+/** The code this extension runs: the record from its last load (re-taken when the record predates this manifest). */
+export declare function loadedCode(): Promise<string>;
+/** Mark the extension busy for BUSY_LEASE_MS (an open overlay calls this through the worker every ~10 s). */
+export declare function extendBusyLease(now?: number): Promise<void>;
+export declare function busyLeaseActive(now?: number): Promise<boolean>;
+/** Is one of the extension's own pages open in a tab (an options or approval page a reload would close)? */
+export declare function extensionPageOpen(): Promise<boolean>;
+export type UpdateAction = 'none' | 'wait' | 'reload';
+/** The pure decision. `seen` and `attempt` are the stored records (or undefined). */
+export declare function decideUpdate(input: {
+    loaded: string;
+    disk: string | null;
+    shipped: string | null | undefined;
+    seen: Seen | undefined;
+    attempt: Attempt | undefined;
+    now: number;
+}): {
+    action: UpdateAction;
+    seen: Seen | null;
+};
+/**
+ * Check and reload when the rules allow. `shipped`: the code the server last
+ * said it deployed (null when unknown). `busy`: the extension's own work in
+ * flight; the busy lease and open extension pages are checked here too.
+ */
+export declare function maybeSelfUpdate(options: {
+    busy: boolean;
+    shipped: string | null | undefined;
+    log?: (message: string) => void;
+}): Promise<UpdateAction | 'busy'>;
+export {};

package/dist/extension-self-update.js

@@ -0,0 +1,178 @@
+// Self-update for an unpacked Chrome extension that Steve's Mac loads from a
+// git checkout (plasticine-way mac/sync/DESIGN.md §3.4). Generalised from
+// Reader's extension/self-update.js (1.3.7, 2026-10-31).
+//
+// The Mac job keeps the checkout at origin/main; Chrome reads an unpacked
+// extension's code only when it loads it, so the worker must reload itself.
+// It does so only into code that (1) verifies file by file against the
+// committed `mac-code.json` on disk, (2) is the code the app's server says it
+// deployed (`shipped`, from the server's answer to the extension's report),
+// and (3) differs from the code this worker loaded. Then: only once that code
+// has been on disk STABLE_MS, never while busy, and at most once per code per
+// RETRY_MS so a reload that does not take cannot loop. chrome.runtime.reload()
+// reloads from the folder and keeps chrome.storage; Chrome honours it only
+// with Developer mode on, which Load unpacked needs anyway.
+//
+// Plain browser ESM with no imports: Lurch bundles it; Reader and Snip (no
+// build step) commit a byte-identical copy of the compiled file, checked by a
+// test in each repo.
+export const STABLE_MS = 60 * 1000;
+export const RETRY_MS = 6 * 60 * 60 * 1000;
+/**
+ * How long one renewal keeps the extension busy. Renewals come every ~10 s from
+ * an open overlay, but Chrome's intensive throttling slows a page's chained
+ * timers to one wake-up a minute once its tab has been hidden 5 minutes, so the
+ * lease must outlast a 60 s gap with room to spare (an overlay left open in a
+ * background tab must still hold off a reload).
+ */
+export const BUSY_LEASE_MS = 150 * 1000;
+export const CODE_MANIFEST_FILE = 'mac-code.json';
+/** chrome.storage.session: { code, since } — the shipped code first seen verified on disk. */
+export const SEEN_KEY = 'selfUpdateSeen';
+/** chrome.storage.local: { code, at } — the last reload this extension asked for. */
+export const ATTEMPT_KEY = 'selfUpdateAttempt';
+/** chrome.storage.local: { code, version } — the code Chrome loaded (written when it loads). */
+export const LOADED_KEY = 'selfUpdateLoaded';
+/** chrome.storage.session: epoch ms until which the extension is busy (an open overlay renews it). */
+export const BUSY_LEASE_KEY = 'selfUpdateBusyUntil';
+function hex(bytes) {
+    return Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export async function sha256Hex(data) {
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    return hex(await crypto.subtle.digest('SHA-256', bytes));
+}
+/** The id over a file list; the same algorithm as baselib code-manifest's codeIdOf. */
+export async function codeIdOf(files) {
+    const lines = Object.keys(files)
+        .sort()
+        .map((path) => `${path}\0${files[path]}\n`)
+        .join('');
+    return (await sha256Hex(lines)).slice(0, 16);
+}
+async function readFile(path) {
+    try {
+        const res = await fetch(chrome.runtime.getURL(path), { cache: 'no-store' });
+        if (!res.ok)
+            return null;
+        return await res.arrayBuffer();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The code on disk now: the manifest's id when every listed file is present and
+ * matches and the id is the id of the list; null otherwise (a merge in
+ * progress, a local edit, no manifest). An extension URL reads the folder as
+ * it is now (measured 2026-10-31).
+ */
+export async function diskCode() {
+    const raw = await readFile(CODE_MANIFEST_FILE);
+    if (!raw)
+        return null;
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder().decode(raw));
+    }
+    catch {
+        return null;
+    }
+    const { id, files } = manifest;
+    if (typeof id !== 'string' || !files || typeof files !== 'object')
+        return null;
+    const list = files;
+    for (const value of Object.values(list))
+        if (typeof value !== 'string')
+            return null;
+    if ((await codeIdOf(list)) !== id)
+        return null;
+    for (const [path, expected] of Object.entries(list)) {
+        const bytes = await readFile(path);
+        if (!bytes || (await sha256Hex(bytes)) !== expected)
+            return null;
+    }
+    return id;
+}
+/**
+ * Record the code Chrome just loaded. Call from runtime.onInstalled and
+ * runtime.onStartup — the moments Chrome reads the extension from disk — and
+ * nowhere else: a worker restarting after eviction runs the code loaded
+ * earlier, whatever the disk holds now.
+ */
+export async function recordLoadedCode() {
+    const code = (await diskCode()) ?? 'unverified';
+    const record = { code, version: chrome.runtime.getManifest().version };
+    await chrome.storage.local.set({ [LOADED_KEY]: record });
+    return code;
+}
+/** The code this extension runs: the record from its last load (re-taken when the record predates this manifest). */
+export async function loadedCode() {
+    const { [LOADED_KEY]: stored } = await chrome.storage.local.get(LOADED_KEY);
+    const record = stored;
+    if (record && typeof record.code === 'string' && record.version === chrome.runtime.getManifest().version)
+        return record.code;
+    return recordLoadedCode();
+}
+/** Mark the extension busy for BUSY_LEASE_MS (an open overlay calls this through the worker every ~10 s). */
+export async function extendBusyLease(now = Date.now()) {
+    await chrome.storage.session.set({ [BUSY_LEASE_KEY]: now + BUSY_LEASE_MS });
+}
+export async function busyLeaseActive(now = Date.now()) {
+    const { [BUSY_LEASE_KEY]: until } = await chrome.storage.session.get(BUSY_LEASE_KEY);
+    return typeof until === 'number' && until > now;
+}
+/** Is one of the extension's own pages open in a tab (an options or approval page a reload would close)? */
+export async function extensionPageOpen() {
+    if (!chrome.runtime.getContexts)
+        return false;
+    try {
+        return (await chrome.runtime.getContexts({ contextTypes: ['TAB'] })).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** The pure decision. `seen` and `attempt` are the stored records (or undefined). */
+export function decideUpdate(input) {
+    const { loaded, disk, shipped, seen, attempt, now } = input;
+    if (!shipped || !disk || disk !== shipped || disk === loaded)
+        return { action: 'none', seen: null };
+    const since = seen && seen.code === disk ? seen.since : now;
+    const record = { code: disk, since };
+    if (now - since < STABLE_MS)
+        return { action: 'wait', seen: record };
+    if (attempt && attempt.code === disk && now - attempt.at < RETRY_MS)
+        return { action: 'none', seen: record };
+    return { action: 'reload', seen: record };
+}
+/**
+ * Check and reload when the rules allow. `shipped`: the code the server last
+ * said it deployed (null when unknown). `busy`: the extension's own work in
+ * flight; the busy lease and open extension pages are checked here too.
+ */
+export async function maybeSelfUpdate(options) {
+    const loaded = await loadedCode();
+    const disk = await diskCode();
+    const { [SEEN_KEY]: seen } = await chrome.storage.session.get(SEEN_KEY);
+    const { [ATTEMPT_KEY]: attempt } = await chrome.storage.local.get(ATTEMPT_KEY);
+    const now = Date.now();
+    const decision = decideUpdate({ loaded, disk, shipped: options.shipped, seen: seen, attempt: attempt, now });
+    const prior = seen;
+    if (decision.seen) {
+        if (!prior || prior.code !== decision.seen.code)
+            await chrome.storage.session.set({ [SEEN_KEY]: decision.seen });
+    }
+    else if (prior) {
+        await chrome.storage.session.remove(SEEN_KEY);
+    }
+    if (decision.action !== 'reload' || !decision.seen)
+        return decision.action;
+    const target = decision.seen.code;
+    if (options.busy || (await busyLeaseActive(now)) || (await extensionPageOpen()))
+        return 'busy';
+    options.log?.(`code ${target} is deployed and on disk (running ${loaded}): reloading.`);
+    await chrome.storage.local.set({ [ATTEMPT_KEY]: { code: target, at: now } });
+    chrome.runtime.reload();
+    return 'reload';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.47.1",
+  "version": "3.48.1",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -88,6 +88,18 @@
     "./connector": {
       "types": "./dist/connector.d.ts",
       "default": "./dist/connector.js"
+    },
+    "./code-manifest": {
+      "types": "./dist/code-manifest.d.ts",
+      "default": "./dist/code-manifest.js"
+    },
+    "./client-version": {
+      "types": "./dist/client-version.d.ts",
+      "default": "./dist/client-version.js"
+    },
+    "./extension-self-update": {
+      "types": "./dist/extension-self-update.d.ts",
+      "default": "./dist/extension-self-update.js"
     }
   },
   "bin": {
@@ -95,7 +107,8 @@
     "pw-deploy": "./dist/bin/pw-deploy.js",
     "pw-logs": "./dist/bin/pw-logs.js",
     "pw-rollback": "./dist/bin/pw-rollback.js",
-    "pw-sql": "./dist/bin/pw-sql.js"
+    "pw-sql": "./dist/bin/pw-sql.js",
+    "pw-code-manifest": "./dist/bin/pw-code-manifest.js"
   },
   "engines": {
     "node": "22.x"