handmux 0.23.0 → 0.25.0

package/dist/src/git.js

@@ -0,0 +1,284 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename, isAbsolute } from 'node:path';
+import { execFile } from 'node:child_process';
+import { isUnder } from './docPath.js';
+import { defaultExtraRoots } from './docs.js';
+// 只读子命令白名单：命令层硬过滤，杜绝任何写操作混入。
+const READONLY = new Set(['rev-parse', 'status', 'log', 'for-each-ref', 'diff', 'show', 'diff-tree']);
+const MAX_BUFFER = 8 * 1024 * 1024;
+export function createGit({ home = homedir(), extraRoots = [] } = {}) {
+    const realHomeP = fs.realpath(home);
+    // Same multi-root allow-list as createDocs: $HOME plus a few roots OUTSIDE it (/tmp, $TMPDIR) so a repo
+    // an agent is working in under /tmp is reachable from the phone. Resolved once — realpath'd, deduped,
+    // missing ones skipped, extras already inside home dropped (home covers them). Keeps git browsing in
+    // lock-step with the file/doc browser; git.js used to be home-only, which rejected legit repos under
+    // /tmp with a red "outside home".
+    const rootsP = (async () => {
+        const rh = await realHomeP;
+        const out = [rh];
+        for (const root of extraRoots) {
+            if (typeof root !== 'string' || !root)
+                continue;
+            let real;
+            try {
+                real = await fs.realpath(root);
+            }
+            catch {
+                continue;
+            } // not present on this host → skip
+            if (isUnder(real, rh) || out.includes(real))
+                continue; // already covered by home / dup
+            out.push(real);
+        }
+        return out;
+    })();
+    // The allowed root that contains `real` (longest match wins should roots ever nest), or null.
+    const rootOf = (real, roots) => {
+        let best = null;
+        for (const root of roots)
+            if (isUnder(real, root) && (!best || root.length > best.length))
+                best = root;
+        return best;
+    };
+    function git(cwd, args) {
+        const sub = args[0];
+        if (!sub || !READONLY.has(sub))
+            return Promise.reject(new Error(`blocked subcommand: ${sub}`));
+        return new Promise((resolve, reject) => {
+            execFile('git', ['-C', cwd, '-c', 'core.quotepath=false', ...args], { maxBuffer: MAX_BUFFER, encoding: 'utf8' }, (err, stdout) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(stdout);
+            });
+        });
+    }
+    async function resolveRepo(rawPath) {
+        if (typeof rawPath !== 'string' || !isAbsolute(rawPath))
+            return { error: 'not absolute', status: 400 };
+        let real;
+        try {
+            real = await fs.realpath(rawPath);
+        }
+        catch {
+            return { error: 'not found', status: 404 };
+        }
+        if (!rootOf(real, await rootsP))
+            return { error: 'outside home', status: 400 };
+        return { real };
+    }
+    async function isRepo(dir) {
+        try {
+            return (await git(dir, ['rev-parse', '--is-inside-work-tree'])).trim() === 'true';
+        }
+        catch {
+            return false;
+        }
+    }
+    async function worktree(rawDir) {
+        const r = await resolveRepo(rawDir);
+        if ('error' in r)
+            return r;
+        try {
+            const path = (await git(r.real, ['rev-parse', '--show-toplevel'])).trim();
+            return path ? { worktree: { path } } : { worktree: null };
+        }
+        catch {
+            return { worktree: null };
+        }
+    }
+    // `realDir` is used for git operations; `displayPath` is what we expose (the caller's original path,
+    // avoiding macOS /private/var vs /var confusion when the caller passed a non-realpath'd path).
+    async function repoMeta(realDir, displayPath) {
+        const p = displayPath ?? realDir;
+        let branch = 'HEAD';
+        try {
+            branch = (await git(realDir, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+        }
+        catch { /* empty repo */ }
+        let dirty = false;
+        try {
+            dirty = (await git(realDir, ['status', '--porcelain'])).trim().length > 0;
+        }
+        catch { /* ignore */ }
+        return { name: basename(p), path: p, branch, dirty };
+    }
+    async function detectRepos(rawDir) {
+        const r = await resolveRepo(rawDir);
+        if ('error' in r)
+            return r;
+        if (await isRepo(r.real))
+            return { repos: [await repoMeta(r.real, rawDir)] };
+        const repos = [];
+        let dirents = [];
+        try {
+            dirents = await fs.readdir(r.real, { withFileTypes: true });
+        }
+        catch { /* ignore */ }
+        for (const d of dirents) {
+            if (!d.isDirectory())
+                continue;
+            const child = join(r.real, d.name);
+            const childDisplay = join(rawDir, d.name);
+            if (await isRepo(child))
+                repos.push(await repoMeta(child, childDisplay));
+        }
+        repos.sort((a, b) => a.name.localeCompare(b.name));
+        return { repos };
+    }
+    async function status(rawRepo) {
+        const r = await resolveRepo(rawRepo);
+        if ('error' in r)
+            return r;
+        if (!(await isRepo(r.real)))
+            return { error: 'not a repo', status: 400 };
+        let out;
+        try {
+            out = await git(r.real, ['status', '--porcelain']);
+        }
+        catch {
+            return { error: 'git error', status: 500 };
+        }
+        const changes = out.split('\n').filter(Boolean).map((line) => {
+            const x = line[0] ?? '', y = line[1] ?? '';
+            let path = line.slice(3);
+            const arrow = path.indexOf(' -> ');
+            if (arrow >= 0)
+                path = path.slice(arrow + 4);
+            return { x: x === ' ' ? '' : x, y: y === ' ' ? '' : y, path };
+        });
+        return { changes };
+    }
+    const SEP = '\x1f';
+    // 分支 / ref 名校验:挡选项注入(开头 '-')、路径穿越('..')、NUL,并限定到安全字符子集。
+    // 只读 git log 用,失败时 git 自己会再拒一次。
+    function safeRef(ref) {
+        if (typeof ref !== 'string' || !ref)
+            return null;
+        if (ref[0] === '-' || ref.includes('..') || ref.includes('\0'))
+            return null;
+        if (!/^[A-Za-z0-9._/-]+$/.test(ref))
+            return null;
+        return ref;
+    }
+    async function log(rawRepo, limit = 50, ref) {
+        const r = await resolveRepo(rawRepo);
+        if ('error' in r)
+            return r;
+        if (!(await isRepo(r.real)))
+            return { error: 'not a repo', status: 400 };
+        const n = Math.max(1, Math.min(500, Number(limit) || 50));
+        const safeR = ref == null || ref === '' ? null : safeRef(ref);
+        if (ref && !safeR)
+            return { error: 'bad ref', status: 400 };
+        const args = ['log', `-n${n}`, `--pretty=format:%H${SEP}%h${SEP}%s${SEP}%an${SEP}%ar`];
+        if (safeR)
+            args.push(safeR); // git log <ref> …(指定分支只读看历史,不动工作树)
+        let out = '';
+        try {
+            out = await git(r.real, args);
+        }
+        catch {
+            return { commits: [] };
+        } // 空仓库(无提交)/ 无此 ref → 空列表
+        const commits = out.split('\n').filter(Boolean).map((line) => {
+            const [hash = '', short = '', subject = '', author = '', relDate = ''] = line.split(SEP);
+            return { hash, short, subject, author, relDate };
+        });
+        return { commits };
+    }
+    async function branches(rawRepo) {
+        const r = await resolveRepo(rawRepo);
+        if ('error' in r)
+            return r;
+        if (!(await isRepo(r.real)))
+            return { error: 'not a repo', status: 400 };
+        const fmt = ['%(refname:short)', '%(HEAD)', '%(upstream:short)', '%(upstream:track)'].join(SEP);
+        let out;
+        try {
+            out = await git(r.real, ['for-each-ref', `--format=${fmt}`, 'refs/heads']);
+        }
+        catch {
+            return { branches: [] };
+        }
+        const branches = out.split('\n').filter(Boolean).map((line) => {
+            const [name = '', head = '', upstream = '', track = ''] = line.split(SEP);
+            const ahead = Number((track.match(/ahead (\d+)/) || [])[1] || 0);
+            const behind = Number((track.match(/behind (\d+)/) || [])[1] || 0);
+            return { name, current: head === '*', upstream: upstream || null, ahead, behind };
+        });
+        return { branches };
+    }
+    // 文件路径校验:相对、非绝对、不以 '-' 开头(防选项注入)、无 '..' 段、无 NUL。
+    function safeRelPath(p) {
+        if (typeof p !== 'string' || !p || p[0] === '-' || isAbsolute(p))
+            return null;
+        if (p.includes('\0') || p.split('/').some((seg) => seg === '..'))
+            return null;
+        return p;
+    }
+    const MAX_DIFF_BYTES = 512 * 1024;
+    function cap(text) {
+        if (text.length <= MAX_DIFF_BYTES)
+            return { diff: text, truncated: false };
+        return { diff: text.slice(0, MAX_DIFF_BYTES), truncated: true };
+    }
+    // diff 语义:仅 path → 工作区 vs HEAD;staged → 暂存区 vs HEAD;commit → 该提交 vs 其父。
+    async function diff(rawRepo, { path, commit, staged } = {}) {
+        const r = await resolveRepo(rawRepo);
+        if ('error' in r)
+            return r;
+        if (!(await isRepo(r.real)))
+            return { error: 'not a repo', status: 400 };
+        const rel = safeRelPath(path);
+        if (!rel)
+            return { error: 'bad path', status: 400 };
+        let args;
+        if (commit) {
+            if (typeof commit !== 'string' || !/^[0-9a-fA-F]{4,40}$/.test(commit))
+                return { error: 'bad commit', status: 400 };
+            args = ['show', '--format=', commit, '--', rel];
+        }
+        else if (staged) {
+            args = ['diff', '--staged', '--', rel];
+        }
+        else {
+            args = ['diff', 'HEAD', '--', rel];
+        }
+        let out = '';
+        try {
+            out = await git(r.real, args);
+        }
+        catch (e) {
+            return { error: 'diff failed', status: 500 };
+        }
+        return cap(out);
+    }
+    async function commit(rawRepo, hash) {
+        const r = await resolveRepo(rawRepo);
+        if ('error' in r)
+            return r;
+        if (!(await isRepo(r.real)))
+            return { error: 'not a repo', status: 400 };
+        if (typeof hash !== 'string' || !/^[0-9a-fA-F]{4,40}$/.test(hash))
+            return { error: 'bad commit', status: 400 };
+        let message;
+        let ns;
+        try {
+            message = (await git(r.real, ['show', '-s', '--format=%B', hash])).trim();
+            // --root 让首次提交(无父)也能列出文件。
+            ns = await git(r.real, ['diff-tree', '--no-commit-id', '--name-status', '-r', '--root', hash]);
+        }
+        catch {
+            return { error: 'git error', status: 500 };
+        }
+        const files = ns.split('\n').filter(Boolean).map((line) => {
+            const [code = '', ...rest] = line.split('\t');
+            return { x: code[0] ?? '', y: '', path: rest[rest.length - 1] ?? '' };
+        }).filter((file) => file.path);
+        return { message, files };
+    }
+    return { resolveRepo, isRepo, worktree, detectRepos, status, log, branches, diff, commit };
+}
+export const defaultGit = createGit({ home: homedir(), extraRoots: defaultExtraRoots() });

package/dist/src/healthProtocol.js

@@ -0,0 +1,97 @@
+const SUBSYSTEM_NAMES = ['workspace', 'codex', 'browser'];
+const SUBSYSTEM_STATUSES = ['starting', 'ready', 'degraded', 'disabled'];
+const READY_STATUSES = ['starting', 'ready', 'degraded'];
+function recordOf(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function parseSubsystem(value) {
+    const record = recordOf(value);
+    if (!record || !SUBSYSTEM_STATUSES.includes(record.status)
+        || typeof record.required !== 'boolean'
+        || (record.detail !== null && (typeof record.detail !== 'string' || !record.detail)))
+        return null;
+    if (record.required && record.status === 'disabled')
+        return null;
+    return {
+        status: record.status,
+        required: record.required,
+        detail: record.detail,
+    };
+}
+export function parseHealthReadySnapshot(value) {
+    const record = recordOf(value);
+    const subsystemsValue = recordOf(record?.subsystems);
+    if (!record || !subsystemsValue || !READY_STATUSES.includes(record.status)
+        || typeof record.ready !== 'boolean' || typeof record.checkedAt !== 'number'
+        || !Number.isFinite(record.checkedAt))
+        return null;
+    const entries = SUBSYSTEM_NAMES.map((name) => [name, parseSubsystem(subsystemsValue[name])]);
+    if (entries.some(([, subsystem]) => !subsystem))
+        return null;
+    const subsystems = Object.fromEntries(entries);
+    const computedReady = Object.values(subsystems)
+        .every((subsystem) => !subsystem.required || subsystem.status === 'ready');
+    if (computedReady !== record.ready)
+        return null;
+    const requiredDegraded = Object.values(subsystems)
+        .some((subsystem) => subsystem.required && subsystem.status === 'degraded');
+    const anyDegraded = Object.values(subsystems).some((subsystem) => subsystem.status === 'degraded');
+    const computedStatus = computedReady
+        ? (anyDegraded ? 'degraded' : 'ready')
+        : (requiredDegraded ? 'degraded' : 'starting');
+    if (computedStatus !== record.status)
+        return null;
+    return {
+        status: computedStatus,
+        ready: computedReady,
+        checkedAt: record.checkedAt,
+        subsystems,
+    };
+}
+export function parseHealthLiveSnapshot(value) {
+    const record = recordOf(value);
+    return record?.status === 'live' && record.live === true
+        && typeof record.checkedAt === 'number' && Number.isFinite(record.checkedAt)
+        ? { status: 'live', live: true, checkedAt: record.checkedAt }
+        : null;
+}
+export class RuntimeHealth {
+    #subsystems;
+    #now;
+    constructor({ browserRequired = false, now = Date.now } = {}) {
+        this.#now = now;
+        this.#subsystems = {
+            workspace: { status: 'starting', required: true, detail: null },
+            codex: { status: 'starting', required: true, detail: null },
+            browser: browserRequired
+                ? { status: 'starting', required: true, detail: null }
+                : { status: 'disabled', required: false, detail: null },
+        };
+    }
+    set(name, status, detail = null) {
+        if (!SUBSYSTEM_NAMES.includes(name) || !SUBSYSTEM_STATUSES.includes(status)
+            || (detail !== null && !detail))
+            throw new Error('invalid health subsystem state');
+        const current = this.#subsystems[name];
+        if (current.required && status === 'disabled')
+            throw new Error(`${name} is required`);
+        this.#subsystems[name] = { status, required: current.required, detail };
+    }
+    live() {
+        return { status: 'live', live: true, checkedAt: this.#now() };
+    }
+    snapshot() {
+        const subsystems = structuredClone(this.#subsystems);
+        const ready = Object.values(subsystems)
+            .every((subsystem) => !subsystem.required || subsystem.status === 'ready');
+        const requiredDegraded = Object.values(subsystems)
+            .some((subsystem) => subsystem.required && subsystem.status === 'degraded');
+        const anyDegraded = Object.values(subsystems).some((subsystem) => subsystem.status === 'degraded');
+        const status = ready
+            ? (anyDegraded ? 'degraded' : 'ready')
+            : (requiredDegraded ? 'degraded' : 'starting');
+        return { status, ready, checkedAt: this.#now(), subsystems };
+    }
+}

package/dist/src/httpApi.js

@@ -0,0 +1,96 @@
+// API composition root. Applies auth + JSON parsing, then mounts the per-domain route modules under
+// /api. Each module (routes/*.js) owns one domain and receives only the deps it needs; the closure deps
+// (commands, docs, git, previews, token, home, …) pass straight through. Behaviour is unchanged from when
+// every route lived here — this file is just the wiring.
+import express from 'express';
+import { bearerFrom, expressAuth, tokenEquals } from './auth.js';
+import * as defaultCommands from './tmux/commands.js';
+import { defaultDocs, MAX_TRANSFER_BYTES } from './docs.js';
+import { defaultGit } from './git.js';
+import * as push from './push.js';
+import * as notifications from './notifications.js';
+import { createClaudeEvents } from './claudeEvents.js';
+import { homedir } from 'node:os';
+import { DEFAULT_UPLOAD_EXTS } from './uploadTypes.js';
+import { claudeStatePath } from './cli/state.js';
+import { sessionRoutes } from './routes/sessions.js';
+import { terminalRoutes } from './routes/terminal.js';
+import { gitRoutes } from './routes/git.js';
+import { fileRoutes } from './routes/files.js';
+import { pushRoutes } from './routes/push.js';
+import { systemRoutes } from './routes/system.js';
+import { previewRoutes } from './routes/previews.js';
+import { notificationRoutes } from './routes/notifications.js';
+import { DEFAULT_SHORTCUTS } from './shortcutConfig.js';
+import { workspaceRoutes } from './routes/workspace.js';
+import { browserRoutes } from './browser/routes.js';
+import { apiErrorBoundary, apiNotFound, apiRequestContext } from './apiErrors.js';
+import { agentRoutes } from './routes/agents.js';
+import { projectTaskRoutes } from './projectTask/routes.js';
+import { apiAccountRoutes } from './routes/apiAccounts.js';
+// Re-exported for tests (test/keys.test.js) and any caller that imported it by this path historically.
+export { isAllowedKey } from './routes/terminal.js';
+export function createApiRouter({ token, commands = defaultCommands, docs = defaultDocs, git = defaultGit, events, uploadExts = DEFAULT_UPLOAD_EXTS, maxUploadBytes = MAX_TRANSFER_BYTES, asrEnv = process.env, previews, shortcuts = DEFAULT_SHORTCUTS, browser, browserBootstrap, previewDomain, workspace, agentRuntime, projectTask, apiAccounts, apiErrors, agentIntegrationContext, home = homedir(), stateFile = process.env.CLAUDE_STATE_FILE || claudeStatePath(homedir()), }) {
+    const r = express.Router();
+    r.use(apiRequestContext(apiErrors));
+    // Account responses, including auth failures and malformed JSON, must never be cached. Keep the
+    // generic auth response stable for every existing route while giving this new API its coded envelope.
+    if (apiAccounts) {
+        r.use('/api-accounts', (req, res, next) => {
+            res.setHeader('Cache-Control', 'no-store');
+            const provided = bearerFrom(req.get('authorization'));
+            if (provided && tokenEquals(provided, token))
+                next();
+            else
+                res.status(401).json({
+                    error: 'unauthorized', code: 'unauthorized', requestId: res.locals.requestId,
+                });
+        });
+    }
+    r.use(expressAuth(token));
+    r.use(express.json());
+    const eventOptions = { commands, push };
+    const claudeEvents = events || createClaudeEvents(eventOptions);
+    const legacyAgentIdentity = {
+        identifyPanes: (panes) => (claudeEvents.identifyPaneAgents(panes.map((pane) => ({
+            id: pane.paneId,
+            command: pane.currentCommand,
+            tty: pane.tty ?? '',
+        })))),
+    };
+    const deps = {
+        token, commands, docs, git, push, notifications, claudeEvents,
+        agentIdentity: agentRuntime ?? legacyAgentIdentity,
+        uploadExts, maxUploadBytes, asrEnv, shortcuts, home, stateFile,
+        ...(agentRuntime !== undefined ? { agentRuntime } : {}),
+        ...(previews !== undefined ? { previews } : {}),
+        ...(workspace !== undefined ? { workspace } : {}),
+        ...(browser !== undefined ? { browser } : {}),
+        ...(browserBootstrap !== undefined ? { browserBootstrap } : {}),
+        ...(previewDomain !== undefined ? { previewDomain } : {}),
+        ...(agentIntegrationContext !== undefined ? { agentIntegrationContext } : {}),
+    };
+    r.use(sessionRoutes(deps));
+    r.use(terminalRoutes(deps));
+    r.use(gitRoutes(deps));
+    r.use(fileRoutes(deps));
+    r.use(pushRoutes(deps));
+    r.use(notificationRoutes(deps));
+    r.use(systemRoutes(deps));
+    if (apiAccounts)
+        r.use(apiAccountRoutes({ service: apiAccounts }));
+    r.use(previewRoutes(deps));
+    // In the main process browser APIs are forwarded to the isolated worker before this router. Keep
+    // preview-domain wiring out of this unused fallback route so capability reporting does not require
+    // the worker-owned bootstrap ticket store.
+    r.use('/browser-proxy', browserRoutes(browser ? deps : { ...deps, previewDomain: null }));
+    if (agentRuntime)
+        r.use(agentRoutes({ runtime: agentRuntime }));
+    if (projectTask)
+        r.use(projectTaskRoutes({ runtime: projectTask }));
+    if (workspace)
+        r.use(workspaceRoutes({ workspace }));
+    r.use(apiNotFound(apiErrors));
+    r.use(apiErrorBoundary(apiErrors));
+    return r;
+}

package/dist/src/jsonStore.js

@@ -0,0 +1,15 @@
+// Shared JSON-store persistence for small single-writer runtime registries (push subscriptions, previews,
+// and notification inboxes). The PrivateStateStore boundary supplies 0700/0600 permission migration,
+// unique sibling temporaries, fsync, and atomic rename. Callers intentionally keep best-effort semantics:
+// a failed flush is recoverable through device re-registration or lease renewal.
+import { PrivateStateStore } from './privateStateStore.js';
+export function readJsonArray(file) {
+    const value = new PrivateStateStore(file).read();
+    return Array.isArray(value) ? value : [];
+}
+export function writeJsonAtomic(file, value) {
+    try {
+        new PrivateStateStore(file).write(value);
+    }
+    catch { /* best effort — a lost flush is recoverable by the caller */ }
+}

package/{src → dist/src}/keyNames.js

@@ -3,8 +3,8 @@
 const NAMED = 'Up|Down|Left|Right|Space|Enter|Escape|Tab|BTab|BSpace|Home|End|PageUp|PageDown';
 const NAMED_KEY = new RegExp(`^(?:C-)?(?:M-)?(?:S-)?(?:${NAMED})$`);
 const CHAR_KEY = /^(?:C-)?(?:M-)?[a-z0-9]$/;
-
 export function isAllowedKey(key) {
-  if (typeof key !== 'string') return false;
-  return NAMED_KEY.test(key) || (CHAR_KEY.test(key) && key.includes('-'));
+    if (typeof key !== 'string')
+        return false;
+    return NAMED_KEY.test(key) || (CHAR_KEY.test(key) && key.includes('-'));
 }

package/dist/src/notifications.js

@@ -0,0 +1,111 @@
+// Per-device manual-push inbox: each subscribed device gets its own file `<NOTIF_DIR>/<pushKey>.json`, so a
+// `--device`/`--session`-scoped push only lands in the targeted devices' inboxes (delete/read are naturally
+// per-device too). NOTIF_DIR is injected by the CLI (~/.handmux/notifications) — NEVER the package-internal
+// default, which a global reinstall wipes. Low-frequency, so each op is a plain read-modify-write of one
+// device file (no in-memory state). The same push shares one record id across its target devices so a
+// notification tap's inboxId resolves on whichever device opens it.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import crypto from 'node:crypto';
+import { readJsonArray, writeJsonAtomic } from './jsonStore.js';
+import { sanitizeNotificationUrl } from './urlPolicy.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const DIR = process.env.NOTIF_DIR || path.resolve(here, '../data/notifications');
+const CAP = 100;
+const genId = () => crypto.randomBytes(9).toString('base64url');
+const DELIVERY_STATUSES = new Set(['pending', 'success', 'failed']);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function parseDelivery(value) {
+    if (!isRecord(value) || typeof value.status !== 'string' || !DELIVERY_STATUSES.has(value.status)) {
+        return undefined;
+    }
+    const delivery = { status: value.status };
+    if (delivery.status === 'failed' && typeof value.reason === 'string')
+        delivery.reason = value.reason;
+    return delivery;
+}
+function parseStoredNotification(value) {
+    if (!isRecord(value)
+        || typeof value.id !== 'string'
+        || typeof value.ts !== 'number'
+        || !Number.isFinite(value.ts)
+        || typeof value.title !== 'string'
+        || typeof value.body !== 'string')
+        return null;
+    const notification = {
+        id: value.id,
+        ts: value.ts,
+        title: value.title,
+        body: value.body,
+    };
+    if (typeof value.tag === 'string')
+        notification.tag = value.tag;
+    if (typeof value.url === 'string') {
+        const safeUrl = sanitizeNotificationUrl(value.url);
+        if (safeUrl)
+            notification.url = safeUrl;
+    }
+    const delivery = parseDelivery(value.delivery);
+    if (delivery)
+        notification.delivery = delivery;
+    return notification;
+}
+// pushKey is base64url already; sanitize anyway so a hostile value can't escape DIR. Empty → null (skip).
+function fileFor(key) {
+    const safe = String(key || '').replace(/[^A-Za-z0-9_-]/g, '');
+    return safe ? path.join(DIR, `${safe}.json`) : null;
+}
+const load = (file) => readJsonArray(file)
+    .map(parseStoredNotification)
+    .filter((notification) => notification !== null);
+export function record(pushKeys, input = {}) {
+    const { title, body, tag, url } = input;
+    const rec = { id: genId(), ts: Date.now(), title: String(title ?? ''), body: String(body ?? '') };
+    if (tag)
+        rec.tag = String(tag);
+    const initialDelivery = parseDelivery(input.delivery);
+    if (initialDelivery?.status === 'pending')
+        rec.delivery = { status: 'pending' };
+    const safeUrl = sanitizeNotificationUrl(url);
+    if (safeUrl)
+        rec.url = safeUrl;
+    for (const key of pushKeys || []) {
+        const file = fileFor(key);
+        if (!file)
+            continue;
+        const items = load(file);
+        items.push(rec);
+        writeJsonAtomic(file, items.length > CAP ? items.slice(items.length - CAP) : items);
+    }
+    return rec;
+}
+export function updateDelivery(pushKey, id, delivery) {
+    const file = fileFor(pushKey);
+    if (!file)
+        return false;
+    const items = load(file);
+    const item = items.find((n) => n.id === id);
+    if (!item)
+        return false;
+    const nextDelivery = parseDelivery(delivery);
+    if (!nextDelivery)
+        return false;
+    item.delivery = nextDelivery;
+    writeJsonAtomic(file, items);
+    return true;
+}
+export function list(pushKey) {
+    const file = fileFor(pushKey);
+    return file ? load(file).reverse() : [];
+}
+export function remove(pushKey, id) {
+    const file = fileFor(pushKey);
+    if (!file)
+        return false;
+    const items = load(file);
+    const kept = items.filter((n) => n.id !== id);
+    if (kept.length === items.length)
+        return false;
+    writeJsonAtomic(file, kept);
+    return true;
+}