@pasko70/pibo 1.9.9 → 1.9.10

package/dist/compute/resource-health.js

@@ -0,0 +1,334 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { readResourceReaperTimerStatus } from "../resources/reaper-state.js";
+import { createEmptyBrowserPoolState, normalizeBrowserPoolState } from "../tools/browser-pool.js";
+import { getComputeDiskDiagnostics, listWorkers } from "./docker.js";
+const execFileAsync = promisify(execFile);
+const DOCKER_DISK_PRESSURE_BYTES = 5_000_000_000;
+export function parseProcessList(output) {
+    const processes = [];
+    for (const line of output.split("\n")) {
+        if (!line.trim())
+            continue;
+        const withElapsed = line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s*(.*)$/);
+        const legacy = withElapsed ? undefined : line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s*(.*)$/);
+        const match = withElapsed ?? legacy;
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        const ppid = Number(match[2]);
+        const pgid = Number(match[3]);
+        if (!Number.isInteger(pid) || !Number.isInteger(ppid) || !Number.isInteger(pgid))
+            continue;
+        const elapsedSeconds = withElapsed ? Number(match[4]) : undefined;
+        const commandName = withElapsed ? match[5] ?? "" : match[4] ?? "";
+        const args = withElapsed ? match[6] ?? "" : match[5] ?? "";
+        const isChromium = isChromiumCommand(commandName, args);
+        processes.push({ pid, ppid, pgid, elapsedSeconds, commandName, args, isChromium, isMainProcess: isChromium && !/\s--type=/.test(` ${args}`) });
+    }
+    return processes;
+}
+export function buildComputeResourceHealth(options = {}) {
+    const now = options.now ?? new Date();
+    const workers = options.workers ?? [];
+    const processes = options.processes ?? [];
+    const processListAvailable = !options.processListError;
+    const browserPools = options.browserPools ?? [];
+    const staleCdpFiles = options.staleCdpFiles ?? { pidFiles: 0, portFiles: 0, details: [] };
+    const reaperTimers = options.reaperTimers ?? { status: "missing", details: "No automatic resource reaper timer status was found.", nextCommands: ["pibo compute health --json", "pibo tools browser-use pool reap --json", "pibo compute reap --dry-run --json"] };
+    const disk = options.disk;
+    const checks = [];
+    const mainProcesses = processes.filter((process) => process.isChromium && process.isMainProcess);
+    const perWorker = browserPools.map(({ state, statePath }) => {
+        const activeLeaseCount = state.activeLeaseId ? Math.max(1, state.activeLeaseCount ?? 1) : state.activeLeaseCount ?? 0;
+        const matched = mainProcesses.filter((process) => browserProcessMatchesPool(process, state));
+        const recordedPidAlive = state.pid ? processes.some((process) => process.pid === state.pid) : false;
+        const leaked = matched.length > state.maxBrowserProcesses;
+        const severity = state.state === "dirty" || leaked ? "warning" : "ok";
+        return {
+            workerId: state.workerId,
+            poolId: state.poolId,
+            state: state.state,
+            pid: state.pid,
+            processGroupId: state.processGroupId,
+            cdpUrl: state.cdpUrl,
+            userDataDir: state.userDataDir,
+            activeLeaseId: state.activeLeaseId,
+            activeLeaseCount,
+            maxBrowserProcesses: state.maxBrowserProcesses,
+            recordedPidAlive,
+            browserMainProcessCount: matched.length,
+            severity,
+            statePath,
+            lastError: state.lastError,
+        };
+    });
+    const assignedMainPids = new Set();
+    for (const pool of browserPools) {
+        for (const process of mainProcesses)
+            if (browserProcessMatchesPool(process, pool.state))
+                assignedMainPids.add(process.pid);
+    }
+    const unassignedMainProcessDetails = mainProcesses
+        .filter((process) => !assignedMainPids.has(process.pid))
+        .map((process) => describeUnassignedBrowserProcess(process, workers));
+    const unassignedChromiumMainProcesses = unassignedMainProcessDetails.length;
+    const activePoolIds = perWorker.filter((pool) => pool.activeLeaseCount > 0).map((pool) => `${pool.workerId}/${pool.poolId}`);
+    const dirtyWorkers = workers.filter((worker) => worker.cleanupState === "dirty" || Boolean(worker.dirtyReason)).map((worker) => worker.name);
+    const oomKilledWorkers = workers.filter((worker) => worker.oomKilled === true).map((worker) => worker.name);
+    const cleanupEligible = workers.filter((worker) => worker.cleanupEligibility.eligible).length;
+    const diskPressure = Boolean(disk?.dockerAvailable && ((disk.totals.reclaimableBytes ?? 0) >= DOCKER_DISK_PRESSURE_BYTES || (disk.usage.buildCache?.sizeBytes ?? 0) >= DOCKER_DISK_PRESSURE_BYTES));
+    if (!processListAvailable)
+        checks.push({ id: "process-list", severity: "warning", message: `Process list unavailable: ${options.processListError}`, nextCommands: ["ps -eo pid,ppid,pgid,comm,args"] });
+    if (perWorker.some((pool) => pool.browserMainProcessCount > pool.maxBrowserProcesses) || unassignedChromiumMainProcesses > 0)
+        checks.push({ id: "browser-leak", severity: "warning", message: browserLeakMessage(unassignedChromiumMainProcesses), nextCommands: ["pibo compute health --json", "pibo tools browser-use pool status --json", "pibo tools browser-use pool reap --json", "pibo compute reap --dry-run --include-dev"] });
+    else
+        checks.push({ id: "browser-processes", severity: "ok", message: "Browser process counts are within managed pool expectations.", nextCommands: ["pibo tools browser-use pool status --json"] });
+    if (activePoolIds.length > 0)
+        checks.push({ id: "browser-leases", severity: "warning", message: `${activePoolIds.length} active browser pool lease(s) found.`, nextCommands: ["pibo ralph runs --json", "pibo tools browser-use pool status --json"] });
+    if (staleCdpFiles.pidFiles > 0 || staleCdpFiles.portFiles > 0)
+        checks.push({ id: "stale-cdp-files", severity: "warning", message: `${staleCdpFiles.pidFiles} stale pid file(s), ${staleCdpFiles.portFiles} orphan port file(s).`, nextCommands: ["pibo tools browser-use lease reap-stale", "pibo tools browser-use pool reap --json"] });
+    if (dirtyWorkers.length > 0)
+        checks.push({ id: "dirty-workers", severity: "warning", message: `${dirtyWorkers.length} dirty compute worker(s): ${dirtyWorkers.join(", ")}`, nextCommands: ["pibo compute list --all --json", "pibo compute reap --dry-run --include-dev"] });
+    if (oomKilledWorkers.length > 0)
+        checks.push({ id: "oom-containers", severity: "critical", message: `${oomKilledWorkers.length} OOM-killed compute container(s): ${oomKilledWorkers.join(", ")}`, nextCommands: ["pibo compute list --all --json", "pibo compute reap --dry-run --include-dev"] });
+    if (options.workerListError)
+        checks.push({ id: "compute-list", severity: "warning", message: `Docker worker list unavailable: ${options.workerListError}`, nextCommands: ["pibo compute list --all --json"] });
+    if (diskPressure)
+        checks.push({ id: "docker-disk-pressure", severity: "warning", message: "Docker reclaimable or BuildKit cache bytes exceed the resource-health warning threshold.", nextCommands: ["pibo compute diagnostics --json", "docker builder du", "docker builder prune"] });
+    if (disk && !disk.dockerAvailable)
+        checks.push({ id: "docker-disk", severity: "warning", message: `Docker disk diagnostics unavailable: ${disk.dockerError ?? "unknown error"}`, nextCommands: ["pibo compute diagnostics --json"] });
+    if (reaperTimers.status !== "configured")
+        checks.push({ id: "reaper-timer", severity: "warning", message: reaperTimers.details ?? "Automatic reaper timer status is not configured.", nextCommands: reaperTimers.nextCommands });
+    const severity = maxSeverity(checks.map((check) => check.severity));
+    const nextCommands = uniqueStrings(checks.flatMap((check) => check.nextCommands).concat(["pibo compute health --json", "pibo compute reap --dry-run --json", "pibo compute diagnostics --json"]));
+    return {
+        generatedAt: now.toISOString(),
+        readOnly: true,
+        severity,
+        checks,
+        browserProcesses: {
+            processListAvailable,
+            processListError: options.processListError,
+            totalChromiumProcesses: processes.filter((process) => process.isChromium).length,
+            totalChromiumMainProcesses: mainProcesses.length,
+            unassignedChromiumMainProcesses,
+            unassignedMainProcessDetails,
+            perWorker,
+        },
+        browserLeases: { active: activePoolIds.length, activePoolIds, staleCdpFiles },
+        computeWorkers: {
+            dockerAvailable: !options.workerListError,
+            dockerError: options.workerListError,
+            total: workers.length,
+            dirty: dirtyWorkers.length,
+            oomKilled: oomKilledWorkers.length,
+            cleanupEligible,
+            dirtyWorkers,
+            oomKilledWorkers,
+        },
+        dockerDisk: {
+            dockerAvailable: disk?.dockerAvailable ?? false,
+            dockerError: disk?.dockerError,
+            sizeBytes: disk?.totals.sizeBytes,
+            reclaimableBytes: disk?.totals.reclaimableBytes,
+            buildCacheBytes: disk?.usage.buildCache?.sizeBytes,
+            pressure: diskPressure,
+        },
+        reaperTimers,
+        nextCommands,
+    };
+}
+function browserLeakMessage(unassignedCount) {
+    if (unassignedCount > 0)
+        return `${unassignedCount} unmanaged Chromium main process(es) are not associated with a managed browser pool.`;
+    return "Chromium main-process count exceeds managed pool expectations.";
+}
+function describeUnassignedBrowserProcess(process, workers) {
+    const worker = workers.find((candidate) => candidate.hostPid !== undefined && candidate.hostPid > 0 && candidate.hostPid === process.ppid);
+    const userDataDir = readChromeArg(process.args, "user-data-dir");
+    const cdpPortValue = readChromeArg(process.args, "remote-debugging-port");
+    const cdpPort = cdpPortValue && /^\d+$/.test(cdpPortValue) ? Number(cdpPortValue) : undefined;
+    const nextCommands = worker
+        ? [`docker top ${worker.name} -eo pid,ppid,pgid,comm,args`, `pibo compute list --all --json`]
+        : ["ps -eo pid,ppid,pgid,comm,args | grep -Ei 'chrome|chromium'", "pibo compute list --all --json"];
+    return {
+        pid: process.pid,
+        ppid: process.ppid,
+        pgid: process.pgid,
+        commandName: process.commandName,
+        workerName: worker?.name,
+        userDataDir,
+        cdpPort,
+        elapsedSeconds: process.elapsedSeconds,
+        argsPreview: sanitizeArgsPreview(process.args),
+        nextCommands,
+    };
+}
+function readChromeArg(args, name) {
+    const pattern = new RegExp(`(?:^|\\s)--${name}=([^\\s]+)`);
+    return args.match(pattern)?.[1];
+}
+function sanitizeArgsPreview(args) {
+    const redacted = args
+        .replace(/(token|access_token|refresh_token|password|passwd|cookie|secret)=([^\s]+)/gi, "$1=<redacted>")
+        .replace(/(--(?:token|password|cookie|secret))\s+([^\s]+)/gi, "$1 <redacted>");
+    return redacted.length > 220 ? `${redacted.slice(0, 217)}...` : redacted;
+}
+export async function getComputeResourceHealth(options = {}) {
+    const browserPoolRoot = options.browserPoolRoot ?? defaultBrowserPoolRoot();
+    const browserUseHome = options.browserUseHome ?? defaultBrowserUseHome();
+    const [workerResult, disk, processResult, browserPools, staleCdpFiles] = await Promise.all([
+        collectWorkers(),
+        getComputeDiskDiagnostics({ now: options.now }),
+        collectProcesses(),
+        collectBrowserPoolStates(browserPoolRoot),
+        collectStaleCdpFiles(browserUseHome),
+    ]);
+    return buildComputeResourceHealth({
+        now: options.now,
+        workers: workerResult.workers,
+        workerListError: workerResult.error,
+        disk,
+        processes: processResult.processes,
+        processListError: processResult.error,
+        browserPools,
+        staleCdpFiles,
+        reaperTimers: detectReaperTimerStatus(),
+    });
+}
+export function defaultBrowserUseHome() {
+    return process.env.BROWSER_USE_HOME || join(homedir(), ".pibo", "tools", "browser-use", "home");
+}
+export function defaultBrowserPoolRoot() {
+    return process.env.PIBO_BROWSER_POOL_ROOT || join(defaultBrowserUseHome(), "pibo-browser-pool");
+}
+export async function collectStaleCdpFiles(browserUseHome) {
+    const stateDir = join(browserUseHome, "pibo-cdp");
+    const result = { pidFiles: 0, portFiles: 0, details: [] };
+    let files;
+    try {
+        files = await readdir(stateDir);
+    }
+    catch {
+        return result;
+    }
+    for (const file of files) {
+        if (file.endsWith(".pid")) {
+            const pidPath = join(stateDir, file);
+            const text = await readFile(pidPath, "utf8").catch(() => "");
+            const pid = Number.parseInt(text.trim(), 10);
+            if (!Number.isFinite(pid) || pid <= 0 || !isPidAlive(pid)) {
+                result.pidFiles += 1;
+                result.details.push(`stale pid file: ${file}`);
+            }
+        }
+        else if (file.endsWith(".port")) {
+            const pidPath = join(stateDir, `${file.slice(0, -5)}.pid`);
+            if (!existsSync(pidPath)) {
+                result.portFiles += 1;
+                result.details.push(`orphan port file: ${file}`);
+            }
+        }
+    }
+    return result;
+}
+async function collectWorkers() {
+    try {
+        return { workers: await listWorkers({ all: true }) };
+    }
+    catch (error) {
+        return { workers: [], error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function collectProcesses() {
+    try {
+        const { stdout } = await execFileAsync("ps", ["-eo", "pid=,ppid=,pgid=,etimes=,comm=,args="], { maxBuffer: 10 * 1024 * 1024 });
+        return { processes: parseProcessList(stdout) };
+    }
+    catch (error) {
+        return { processes: [], error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function collectBrowserPoolStates(rootDir) {
+    const statePaths = await findStateJsonFiles(rootDir);
+    const states = [];
+    for (const statePath of statePaths) {
+        try {
+            const raw = await readFile(statePath, "utf8");
+            const parsed = JSON.parse(raw);
+            const identity = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? { workerId: String(parsed.workerId ?? "unknown"), poolId: String(parsed.poolId ?? "default"), maxBrowserProcesses: 1 }
+                : { workerId: "unknown", poolId: "default", maxBrowserProcesses: 1 };
+            states.push({ state: normalizeBrowserPoolState(parsed, identity), statePath });
+        }
+        catch {
+            states.push({ state: { ...createEmptyBrowserPoolState({ workerId: "unknown", poolId: "default" }), state: "dirty", lastError: `Could not read browser pool state ${statePath}` }, statePath });
+        }
+    }
+    return states;
+}
+async function findStateJsonFiles(rootDir) {
+    const found = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(fullPath);
+            else if (entry.isFile() && entry.name === "state.json")
+                found.push(fullPath);
+        }
+    }
+    await walk(rootDir);
+    return found;
+}
+function detectReaperTimerStatus() {
+    if (process.env.PIBO_RESOURCE_REAPER_TIMER_STATUS === "configured") {
+        return { status: "configured", details: "Resource reaper timer is marked configured by PIBO_RESOURCE_REAPER_TIMER_STATUS.", nextCommands: ["pibo resources status --json"] };
+    }
+    return readResourceReaperTimerStatus();
+}
+function browserProcessMatchesPool(process, state) {
+    if (state.pid && process.pid === state.pid)
+        return true;
+    if (state.processGroupId && process.pgid === state.processGroupId)
+        return true;
+    if (state.userDataDir && process.args.includes(`--user-data-dir=${state.userDataDir}`))
+        return true;
+    return false;
+}
+function isChromiumCommand(commandName, args) {
+    const commandBase = basename(commandName).toLowerCase();
+    const firstArg = basename(args.trim().split(/\s+/, 1)[0] ?? "").toLowerCase();
+    return [commandBase, firstArg].some((value) => value === "chrome" || value === "google-chrome" || value === "chromium" || value === "chromium-browser");
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}
+function maxSeverity(values) {
+    if (values.includes("critical"))
+        return "critical";
+    if (values.includes("warning"))
+        return "warning";
+    return "ok";
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}

package/dist/compute/resource-policy.js

@@ -0,0 +1,98 @@
+export const DEFAULT_COMPUTE_RESOURCE_POLICY = Object.freeze({
+    memory: "2g",
+    memorySwap: "2g",
+    pidsLimit: 512,
+    shmSize: "512m",
+    init: true,
+    restart: "no",
+    logDriver: "json-file",
+    logMaxSize: "10m",
+    logMaxFile: 3,
+});
+export const COMPUTE_RESOURCE_POLICY_ENV = Object.freeze({
+    memory: "PIBO_COMPUTE_MEMORY",
+    memorySwap: "PIBO_COMPUTE_MEMORY_SWAP",
+    pidsLimit: "PIBO_COMPUTE_PIDS_LIMIT",
+    shmSize: "PIBO_COMPUTE_SHM_SIZE",
+    init: "PIBO_COMPUTE_INIT",
+    logMaxSize: "PIBO_COMPUTE_LOG_MAX_SIZE",
+    logMaxFile: "PIBO_COMPUTE_LOG_MAX_FILE",
+});
+export const COMPUTE_RESOURCE_POLICY_LABELS = Object.freeze({
+    memory: "pibo.compute.resource.memory",
+    memorySwap: "pibo.compute.resource.memorySwap",
+    pidsLimit: "pibo.compute.resource.pidsLimit",
+    shmSize: "pibo.compute.resource.shmSize",
+    init: "pibo.compute.resource.init",
+    restart: "pibo.compute.resource.restart",
+    logDriver: "pibo.compute.resource.logDriver",
+    logMaxSize: "pibo.compute.resource.logMaxSize",
+    logMaxFile: "pibo.compute.resource.logMaxFile",
+});
+export function resolveComputeResourcePolicy(env = process.env) {
+    return {
+        memory: nonEmpty(env[COMPUTE_RESOURCE_POLICY_ENV.memory], DEFAULT_COMPUTE_RESOURCE_POLICY.memory),
+        memorySwap: nonEmpty(env[COMPUTE_RESOURCE_POLICY_ENV.memorySwap], DEFAULT_COMPUTE_RESOURCE_POLICY.memorySwap),
+        pidsLimit: positiveInteger(env[COMPUTE_RESOURCE_POLICY_ENV.pidsLimit], DEFAULT_COMPUTE_RESOURCE_POLICY.pidsLimit),
+        shmSize: nonEmpty(env[COMPUTE_RESOURCE_POLICY_ENV.shmSize], DEFAULT_COMPUTE_RESOURCE_POLICY.shmSize),
+        init: booleanValue(env[COMPUTE_RESOURCE_POLICY_ENV.init], DEFAULT_COMPUTE_RESOURCE_POLICY.init),
+        restart: DEFAULT_COMPUTE_RESOURCE_POLICY.restart,
+        logDriver: DEFAULT_COMPUTE_RESOURCE_POLICY.logDriver,
+        logMaxSize: nonEmpty(env[COMPUTE_RESOURCE_POLICY_ENV.logMaxSize], DEFAULT_COMPUTE_RESOURCE_POLICY.logMaxSize),
+        logMaxFile: positiveInteger(env[COMPUTE_RESOURCE_POLICY_ENV.logMaxFile], DEFAULT_COMPUTE_RESOURCE_POLICY.logMaxFile),
+    };
+}
+export function buildDockerResourcePolicyArgs(policy = resolveComputeResourcePolicy()) {
+    return [
+        "--memory",
+        policy.memory,
+        "--memory-swap",
+        policy.memorySwap,
+        "--pids-limit",
+        String(policy.pidsLimit),
+        "--shm-size",
+        policy.shmSize,
+        ...(policy.init ? ["--init"] : []),
+        "--restart",
+        policy.restart,
+        "--log-driver",
+        policy.logDriver,
+        "--log-opt",
+        `max-size=${policy.logMaxSize}`,
+        "--log-opt",
+        `max-file=${policy.logMaxFile}`,
+    ];
+}
+export function buildComputeResourcePolicyLabels(policy = resolveComputeResourcePolicy()) {
+    return [
+        `${COMPUTE_RESOURCE_POLICY_LABELS.memory}=${policy.memory}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.memorySwap}=${policy.memorySwap}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.pidsLimit}=${policy.pidsLimit}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.shmSize}=${policy.shmSize}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.init}=${policy.init}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.restart}=${policy.restart}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.logDriver}=${policy.logDriver}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.logMaxSize}=${policy.logMaxSize}`,
+        `${COMPUTE_RESOURCE_POLICY_LABELS.logMaxFile}=${policy.logMaxFile}`,
+    ];
+}
+function nonEmpty(value, fallback) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : fallback;
+}
+function positiveInteger(value, fallback) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function booleanValue(value, fallback) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return fallback;
+}

package/dist/config/config.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { piboHomePath } from "../core/pibo-home.js";
+export const DEFAULT_PIBO_CONFIG_PATH = "config.json";
+export function getDefaultPiboConfigPath() {
+    return piboHomePath(DEFAULT_PIBO_CONFIG_PATH);
+}
+export const PIBO_CONFIG_KEYS = [
+    {
+        key: "auth.baseURL",
+        type: "string",
+        description: "Better Auth base URL, for example http://localhost:4788.",
+    },
+    {
+        key: "auth.secret",
+        type: "string",
+        secret: true,
+        description: "Better Auth secret. Must be at least 32 characters.",
+    },
+    {
+        key: "auth.googleClientId",
+        type: "string",
+        description: "Google OAuth client id.",
+    },
+    {
+        key: "auth.googleClientSecret",
+        type: "string",
+        secret: true,
+        description: "Google OAuth client secret.",
+    },
+    {
+        key: "auth.allowedEmails",
+        type: "string[]",
+        description: "Allowed Google account emails. Use comma-separated values.",
+    },
+    {
+        key: "auth.trustedOrigins",
+        type: "string[]",
+        description: "Additional trusted Better Auth origins. Use comma-separated values.",
+    },
+    {
+        key: "auth.databasePath",
+        type: "string",
+        description: "SQLite path for Better Auth data.",
+    },
+    {
+        key: "auth.mode",
+        type: "string",
+        description: "Auth service mode. Use 'local' to skip Google OAuth on a loopback bind. Default 'better-auth'.",
+        values: ["better-auth", "local"],
+    },
+];
+function getKeyDefinition(key) {
+    const definition = PIBO_CONFIG_KEYS.find((candidate) => candidate.key === key);
+    if (!definition)
+        throw new Error(`Unknown config key "${key}"`);
+    return definition;
+}
+function findKeyDefinition(key) {
+    return PIBO_CONFIG_KEYS.find((candidate) => candidate.key === key);
+}
+function maskSecretValue(value) {
+    if (value.length <= 8)
+        return "********";
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+function parseListValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("[")) {
+        const parsed = JSON.parse(trimmed);
+        if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
+            throw new Error("Expected a JSON string array");
+        }
+        return parsed.map((item) => item.trim()).filter(Boolean);
+    }
+    return trimmed
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function parseConfigValue(definition, value) {
+    if (definition.type === "string[]")
+        return parseListValue(value);
+    if (definition.key === "auth.secret" && value.length < 32) {
+        throw new Error("auth.secret must be at least 32 characters");
+    }
+    if (definition.values && !definition.values.includes(value)) {
+        throw new Error(`${definition.key} must be one of: ${definition.values.join(", ")}`);
+    }
+    return value;
+}
+function assertObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Pibo config must be a JSON object");
+    }
+    return value;
+}
+export function loadPiboConfig(path) {
+    const resolvedPath = resolve(path ?? getDefaultPiboConfigPath());
+    if (!existsSync(resolvedPath))
+        return {};
+    const parsed = JSON.parse(readFileSync(resolvedPath, "utf-8"));
+    return assertObject(parsed);
+}
+export function savePiboConfig(config, path) {
+    const resolvedPath = resolve(path ?? getDefaultPiboConfigPath());
+    mkdirSync(dirname(resolvedPath), { recursive: true });
+    writeFileSync(resolvedPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+export function getPiboConfigValue(config, key) {
+    getKeyDefinition(key);
+    const segments = key.split(".");
+    let current = config;
+    for (const segment of segments) {
+        if (!current || typeof current !== "object" || Array.isArray(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+export function getDisplayPiboConfigValue(config, key) {
+    const definition = getKeyDefinition(key);
+    const value = getPiboConfigValue(config, key);
+    if (definition.secret && typeof value === "string")
+        return maskSecretValue(value);
+    return value;
+}
+export function redactPiboConfig(config) {
+    const redacted = structuredClone(config);
+    for (const definition of PIBO_CONFIG_KEYS) {
+        if (!definition.secret)
+            continue;
+        const value = getPiboConfigValue(config, definition.key);
+        if (typeof value !== "string")
+            continue;
+        const segments = definition.key.split(".");
+        let current = redacted;
+        for (const segment of segments.slice(0, -1)) {
+            const next = current[segment];
+            if (!next || typeof next !== "object" || Array.isArray(next)) {
+                current = {};
+                break;
+            }
+            current = next;
+        }
+        current[segments[segments.length - 1]] = maskSecretValue(value);
+    }
+    return redacted;
+}
+export function setPiboConfigValue(config, key, rawValue) {
+    const definition = getKeyDefinition(key);
+    const value = parseConfigValue(definition, rawValue);
+    const [section, name] = key.split(".");
+    if (section !== "auth" || !name)
+        throw new Error(`Unsupported config key "${key}"`);
+    return {
+        ...config,
+        auth: {
+            ...config.auth,
+            [name]: value,
+        },
+    };
+}
+export function isPiboConfigKeySecret(key) {
+    return findKeyDefinition(key)?.secret === true;
+}
+export function deletePiboConfigValue(config, key) {
+    getKeyDefinition(key);
+    const [section, name] = key.split(".");
+    if (section !== "auth" || !name)
+        throw new Error(`Unsupported config key "${key}"`);
+    if (!config.auth || !(name in config.auth))
+        return config;
+    const auth = { ...config.auth };
+    delete auth[name];
+    return {
+        ...config,
+        auth: Object.keys(auth).length > 0 ? auth : undefined,
+    };
+}