@luckypiggy/zhihu-ai-cli 0.1.0-test.1

package/dist/install.js

@@ -0,0 +1,435 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stderr as output } from "node:process";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { lstatSync } from "node:fs";
+import { ConfigError, DEFAULT_PROFILE, captureProfileInstallSnapshot, normalizeProfileName, guardProfileConnectionChange, readProfileRaw, ProfileConnectionGuardError, restoreProfileInstallSnapshot, validateProfile, writeProfileInstallConfig, } from "./config.js";
+import { ProfileLock, ProfileLockError, withProfileLock } from "./profile-lock.js";
+import { IntegrationHttpClient, HttpError, validateIntegrationInfo, } from "./http.js";
+import { AuthService } from "./auth-service.js";
+import { SecureCredentialStore } from "./credentials.js";
+import { installCodexSkill, resolveCodexSkillTarget, CodexSkillError, CODEX_SKILL_NAME, } from "./codex-skill.js";
+import { CliAuthError, mapFailure } from "./token-manager.js";
+const MAX_CA_BUNDLE_BYTES = 4 * 1024 * 1024;
+const CONTROL_PATTERN = /[\u0000-\u001f\u007f]/;
+export class InstallError extends Error {
+    code;
+    retryable;
+    exitCode;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "InstallError";
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.exitCode = options.exitCode ?? 2;
+    }
+}
+function fail(code, message, exitCode = 2) {
+    throw new InstallError(code, message, { exitCode });
+}
+function normalizeLanguage(value) {
+    if (value === undefined)
+        return DEFAULT_PROFILE.language;
+    if (value === "zh-CN" || value === "zh")
+        return "zh";
+    if (value === "en")
+        return "en";
+    fail("INVALID_ARGUMENT", "--language must be zh-CN or en");
+}
+function normalizeTimeout(value) {
+    if (value === undefined)
+        return DEFAULT_PROFILE.timeout_seconds;
+    if (!/^\d+$/.test(value))
+        fail("INVALID_ARGUMENT", "--timeout must be an integer between 1 and 300 seconds");
+    const timeout = Number(value);
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 300) {
+        fail("INVALID_ARGUMENT", "--timeout must be an integer between 1 and 300 seconds");
+    }
+    return timeout;
+}
+function normalizeAuthMode(value) {
+    if (value === undefined || value === "")
+        return "browser";
+    if (value !== "browser") {
+        fail("INVALID_ARGUMENT", "ZHIHU_AUTH_MODE/--auth-mode must be browser");
+    }
+    return "browser";
+}
+/**
+ * Environment configuration is deliberately limited to non-sensitive values.
+ * Empty (or whitespace-only) values are treated as unset so an interactive
+ * prompt/default can still be used.  Do not add token/username/password
+ * fallbacks here: browser OAuth is the only supported authentication path.
+ */
+function nonEmptyEnvironmentValue(environment, name) {
+    const value = environment[name];
+    if (typeof value !== "string" || value.trim() === "")
+        return undefined;
+    return value.trim();
+}
+/** Resolve the default target without consulting an existing Profile. */
+function defaultCodexSkillTarget(environment) {
+    const home = resolve(environment.HOME?.trim() || homedir());
+    const codexHome = resolve(environment.CODEX_HOME?.trim() || join(home, ".codex"));
+    return join(codexHome, "skills", CODEX_SKILL_NAME);
+}
+function validateText(value, label, maxLength) {
+    if (value.length === 0 || value.length > maxLength || CONTROL_PATTERN.test(value)) {
+        fail("INVALID_ARGUMENT", `${label} is invalid`);
+    }
+    return value;
+}
+function validateCaFile(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    validateText(value, "--ca-file", 4096);
+    if (!isAbsolute(value))
+        fail("CONFIG_INVALID", "--ca-file must be an absolute regular file");
+    try {
+        const stat = lstatSync(value);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.size <= 0 || stat.size > MAX_CA_BUNDLE_BYTES) {
+            fail("CONFIG_INVALID", "--ca-file must be a non-empty regular file no larger than 4 MiB");
+        }
+    }
+    catch (error) {
+        if (error instanceof InstallError)
+            throw error;
+        fail("CONFIG_INVALID", "--ca-file must be a readable regular file");
+    }
+    return value;
+}
+function interactiveEnabled(inputValue, inputStream, outputStream) {
+    if (inputValue.json)
+        return false;
+    if (inputValue.interactive !== undefined)
+        return inputValue.interactive;
+    return Boolean(inputStream.isTTY
+        && outputStream.isTTY);
+}
+async function promptValue(rl, label, defaultValue, required = false, outputStream = output) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        let answer;
+        try {
+            answer = (await rl.question(`${label}${defaultValue === undefined ? "" : ` [${defaultValue}]`}: `)).trim();
+        }
+        catch {
+            fail("USER_CANCELLED", "Installation was cancelled");
+        }
+        if (!answer && defaultValue !== undefined)
+            answer = defaultValue;
+        if (!answer && required) {
+            outputStream.write("A value is required. Please try again.\n");
+            continue;
+        }
+        if (answer.length <= 4096 && !CONTROL_PATTERN.test(answer))
+            return answer;
+        outputStream.write("Input is too long or contains control characters. Please try again.\n");
+    }
+    fail("INVALID_ARGUMENT", "Too many invalid interactive inputs");
+}
+async function confirmOverwrite(rl, outputStream) {
+    const answer = await promptValue(rl, "Overwrite the existing profile? (y/N)", "N", false, outputStream);
+    return /^(?:y|yes)$/i.test(answer);
+}
+function existingProfile(profile, environment) {
+    try {
+        return captureProfileInstallSnapshot(profile, environment).profile.exists;
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            throw error;
+        fail("CONFIG_INVALID", "Existing profile cannot be inspected");
+    }
+}
+function stableServiceInfo(info) {
+    return {
+        status: info.status,
+        protocol_version: info.protocol_version,
+        minimum_cli_version: info.minimum_cli_version,
+        capabilities: [...(info.capabilities ?? [])],
+    };
+}
+async function rollbackProfile(snapshot, profile, environment, options = {}) {
+    if (!snapshot)
+        return;
+    try {
+        const restore = async () => {
+            await withProfileLock(profile, async () => restoreProfileInstallSnapshot(snapshot), { environment });
+        };
+        // The install path holds install-root from the initial snapshot through
+        // success/rollback.  Standalone recovery still acquires it in the same
+        // fixed order.
+        if (options.rootLockHeld)
+            await restore();
+        else
+            await withProfileLock("install-root", restore, { environment });
+    }
+    catch {
+        throw new InstallError("CONFIG_INVALID", "Installation failed and local configuration could not be restored", { exitCode: 6 });
+    }
+}
+export async function installWizard(inputValue) {
+    const environment = inputValue.environment ?? process.env;
+    const inputStream = inputValue.input ?? input;
+    const outputStream = inputValue.output ?? output;
+    const interactive = interactiveEnabled(inputValue, inputStream, outputStream);
+    const rl = interactive ? createInterface({ input: inputStream, output: outputStream }) : undefined;
+    let profileName = inputValue.profile;
+    let baseUrl = inputValue.baseUrl;
+    let authMode = inputValue.authMode;
+    let timeout = inputValue.timeout;
+    let language = inputValue.language;
+    try {
+        // Stage 6B1 deliberately installs/ confirms the bundled Skill before it
+        // reads customer configuration.  This makes `npx ... install` useful as a
+        // one-line Codex bootstrap and ensures Skill failures cannot trigger
+        // network access, prompts, or Profile writes.
+        let codex;
+        if (!inputValue.skipCodex) {
+            try {
+                // Do not pass `profile`: a Skill target is independent of a Profile and
+                // must be installable before the customer has configured an origin.
+                const skillTarget = inputValue.codexSkillDir ?? defaultCodexSkillTarget(environment);
+                resolveCodexSkillTarget({ codexSkillDir: skillTarget, environment });
+                const codexOptions = {
+                    codexSkillDir: skillTarget,
+                    force: inputValue.force,
+                    environment,
+                };
+                codex = inputValue.codexInstaller
+                    ? await inputValue.codexInstaller(codexOptions)
+                    : installCodexSkill(codexOptions);
+            }
+            catch (error) {
+                if (error instanceof CodexSkillError) {
+                    throw new InstallError(error.code, error.message, { exitCode: error.exitCode });
+                }
+                throw error;
+            }
+            if (interactive && !inputValue.json) {
+                outputStream.write("Skill installed, configure environment. Run zhihu install again to retry.\n");
+            }
+        }
+        // CLI/input values win over non-empty environment values; empty values are
+        // intentionally ignored so users can fall back to a prompt/default.
+        if (profileName === undefined)
+            profileName = nonEmptyEnvironmentValue(environment, "ZHIHU_PROFILE");
+        if (baseUrl === undefined)
+            baseUrl = nonEmptyEnvironmentValue(environment, "ZHIHU_BASE_URL");
+        if (authMode === undefined)
+            authMode = nonEmptyEnvironmentValue(environment, "ZHIHU_AUTH_MODE");
+        if (inputValue.caFile === undefined) {
+            const environmentCa = nonEmptyEnvironmentValue(environment, "ZHIHU_CA_BUNDLE");
+            if (environmentCa !== undefined)
+                inputValue = { ...inputValue, caFile: environmentCa };
+        }
+        if (timeout === undefined)
+            timeout = nonEmptyEnvironmentValue(environment, "ZHIHU_TIMEOUT");
+        if (profileName === undefined && interactive)
+            profileName = await promptValue(rl, "Profile name (ZHIHU_PROFILE)", "production", false, outputStream);
+        if (profileName === undefined)
+            profileName = "production";
+        if (baseUrl === undefined && interactive)
+            baseUrl = await promptValue(rl, "Zhihu Pilot base URL (ZHIHU_BASE_URL)", undefined, true, outputStream);
+        if (baseUrl === undefined)
+            fail("INVALID_ARGUMENT", "--base-url or ZHIHU_BASE_URL is required when input is not interactive");
+        if (authMode === undefined && interactive)
+            authMode = await promptValue(rl, "Authentication mode (ZHIHU_AUTH_MODE)", "browser", false, outputStream);
+        if (inputValue.caFile === undefined && interactive) {
+            const caAnswer = await promptValue(rl, "CA bundle path (ZHIHU_CA_BUNDLE; optional)", "", false, outputStream);
+            inputValue = { ...inputValue, caFile: caAnswer };
+        }
+        if (timeout === undefined && interactive)
+            timeout = await promptValue(rl, "Request timeout in seconds (ZHIHU_TIMEOUT)", "30", false, outputStream);
+        // Existing language flag/prompt remains compatible; it is intentionally
+        // after the Stage 6B1 environment set so the documented env order stays
+        // profile → base URL → auth mode → CA → timeout.
+        language = language === undefined && interactive
+            ? await promptValue(rl, "Language (zh-CN/en)", "en", false, outputStream)
+            : language;
+        profileName = normalizeProfileName(profileName);
+        baseUrl = validateText(baseUrl, "--base-url", 2048);
+        normalizeAuthMode(authMode);
+        const caFile = validateCaFile(inputValue.caFile);
+        if (!interactive && !inputValue.skipLogin) {
+            fail("INVALID_ARGUMENT", "--skip-login is required when input is not interactive or --json is used");
+        }
+        let profile;
+        try {
+            profile = validateProfile({
+                ...DEFAULT_PROFILE,
+                base_url: baseUrl,
+                timeout_seconds: normalizeTimeout(timeout),
+                language: normalizeLanguage(language),
+                ...(caFile ? { ca_bundle: caFile } : {}),
+                ...(inputValue.codexSkillDir !== undefined ? { codex_skill_dir: inputValue.codexSkillDir } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                fail(error.code, error.message);
+            throw error;
+        }
+        // Constructing the client applies the HTTPS/loopback and URL-userinfo
+        // policy before any persistent write.  The strict info call is the only
+        // server-side preflight and does not carry credentials.
+        let client;
+        try {
+            const validatedClient = new IntegrationHttpClient(profile);
+            client = inputValue.clientFactory
+                ? inputValue.clientFactory(profile)
+                : validatedClient;
+        }
+        catch (error) {
+            if (error instanceof HttpError) {
+                const mapped = mapFailure(error);
+                throw new InstallError(mapped.code, mapped.message, { retryable: mapped.retryable, exitCode: mapped.exitCode });
+            }
+            throw error;
+        }
+        let info;
+        try {
+            // Keep the strict validator at the install boundary even when a test or
+            // host adapter supplies an IntegrationHttpClient-compatible object.
+            info = validateIntegrationInfo(await client.info(), true);
+        }
+        catch (error) {
+            if (error instanceof HttpError) {
+                const mapped = mapFailure(error);
+                throw new InstallError(mapped.code, mapped.message, { retryable: mapped.retryable, exitCode: mapped.exitCode });
+            }
+            throw error;
+        }
+        let snapshot;
+        let loggedIn = false;
+        const credentials = new SecureCredentialStore(profileName);
+        const credentialProbeFactory = inputValue.credentialStoreFactory
+            ?? ((name) => new SecureCredentialStore(name));
+        let replacingExisting = inputValue.force === true;
+        let releaseRootLock;
+        try {
+            // Hold the root lock until the complete install succeeds or rollback
+            // finishes.  Otherwise a concurrent install can update current_profile
+            // after our snapshot and a later rollback would overwrite its result.
+            const rootLock = new ProfileLock("install-root", { environment });
+            releaseRootLock = await rootLock.acquire();
+            if (existingProfile(profileName, environment) && !inputValue.force) {
+                if (!interactive)
+                    fail("CONFIG_EXISTS", `Profile ${profileName} already exists; use --force to replace it`);
+                if (!(await confirmOverwrite(rl, outputStream))) {
+                    fail("USER_CANCELLED", "Existing profile was not changed");
+                }
+                replacingExisting = true;
+            }
+            // Read and validate the existing profile, check origin changes, and
+            // write the config pair under the target lock.  The root lock above is
+            // held for the whole transaction, so the guard cannot race another
+            // profile manager or observe a half-written pair.
+            snapshot = await withProfileLock(profileName, async () => {
+                const previousRaw = readProfileRaw(profileName, environment);
+                if (previousRaw !== undefined && replacingExisting) {
+                    let previous;
+                    try {
+                        previous = validateProfile(previousRaw);
+                    }
+                    catch (error) {
+                        if (error instanceof ConfigError)
+                            throw error;
+                        throw new ConfigError("Existing profile cannot be validated");
+                    }
+                    await guardProfileConnectionChange(profileName, previous, profile, credentialProbeFactory);
+                }
+                return writeProfileInstallConfig(profileName, profile, environment);
+            }, { environment });
+            if (!inputValue.skipLogin) {
+                const auth = new AuthService(client, credentials, profileName, {
+                    onBrowserFailure: (authorizationUrl) => outputStream.write(`Browser launch failed. Open this URL manually: ${authorizationUrl}\n`),
+                });
+                await auth.login();
+                loggedIn = true;
+            }
+            let doctor;
+            if (inputValue.doctor) {
+                try {
+                    doctor = await inputValue.doctor(environment, profileName, profile);
+                }
+                catch {
+                    doctor = { status: "unavailable" };
+                }
+            }
+            return {
+                action: "install",
+                profile: profileName,
+                base_url: profile.base_url,
+                status: "installed",
+                service: stableServiceInfo(info),
+                login: { status: loggedIn ? "logged_in" : "skipped" },
+                codex: inputValue.skipCodex
+                    ? { status: "skipped" }
+                    : { status: codex?.status === "updated" ? "updated" : codex?.status === "unchanged" ? "unchanged" : "installed", target: codex?.target },
+                ...(doctor === undefined ? {} : { doctor }),
+            };
+        }
+        catch (error) {
+            let cleanupFailure;
+            if (loggedIn) {
+                try {
+                    await new AuthService(client, credentials, profileName).logout();
+                }
+                catch {
+                    cleanupFailure = "the remote login session could not be revoked";
+                }
+                try {
+                    await credentials.delete();
+                }
+                catch {
+                    cleanupFailure = cleanupFailure
+                        ? `${cleanupFailure} and local credentials could not be removed`
+                        : "local credentials could not be removed";
+                }
+            }
+            let rollbackFailure;
+            try {
+                await rollbackProfile(snapshot, profileName, environment, { rootLockHeld: true });
+            }
+            catch (rollbackError) {
+                rollbackFailure = rollbackError instanceof InstallError
+                    ? rollbackError
+                    : new InstallError("CONFIG_INVALID", "Installation failed and local configuration could not be restored", { exitCode: 6 });
+            }
+            if (rollbackFailure)
+                throw rollbackFailure;
+            if (cleanupFailure) {
+                throw new InstallError("AUTH_RELOGIN_REQUIRED", `Installation failed; ${cleanupFailure}. Run zhihu auth logout or login again before retrying.`, { exitCode: 3 });
+            }
+            if (error instanceof InstallError)
+                throw error;
+            if (error instanceof ProfileConnectionGuardError) {
+                throw new InstallError(error.code, error.message, { exitCode: error.exitCode });
+            }
+            if (error instanceof ConfigError)
+                fail(error.code, error.message);
+            if (error instanceof CodexSkillError) {
+                throw new InstallError(error.code, error.message, { exitCode: error.exitCode });
+            }
+            if (error instanceof CliAuthError) {
+                throw new InstallError(error.code, error.message, { retryable: error.retryable, exitCode: error.exitCode });
+            }
+            if (error instanceof ProfileLockError) {
+                const mapped = mapFailure(error);
+                throw new InstallError(mapped.code, mapped.message, { retryable: mapped.retryable, exitCode: mapped.exitCode });
+            }
+            if (error instanceof HttpError) {
+                const mapped = mapFailure(error);
+                throw new InstallError(mapped.code, mapped.message, { retryable: mapped.retryable, exitCode: mapped.exitCode });
+            }
+            throw new InstallError("PROTOCOL_ERROR", "Installation failed; no local changes were kept", { exitCode: 8 });
+        }
+        finally {
+            releaseRootLock?.();
+        }
+    }
+    finally {
+        rl?.close();
+    }
+}

package/dist/logger.js

@@ -0,0 +1,28 @@
+import { redactString, redactValue } from "./redaction.js";
+function formatPart(part) {
+    if (typeof part === "string")
+        return redactString(part);
+    try {
+        return JSON.stringify(redactValue(part));
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+/**
+ * Create a stderr-only logger. It is disabled by default so JSON stdout stays
+ * a single document; every enabled message is redacted before being emitted.
+ */
+export function createLogger(enabled = false, sink = (line) => process.stderr.write(`${line}\n`)) {
+    const write = (level, parts) => {
+        if (!enabled)
+            return;
+        sink(`[${level}] ${parts.map(formatPart).join(" ")}`);
+    };
+    return {
+        debug: (...parts) => write("debug", parts),
+        info: (...parts) => write("info", parts),
+        warn: (...parts) => write("warn", parts),
+        error: (...parts) => write("error", parts),
+    };
+}

package/dist/output.js

@@ -0,0 +1,48 @@
+import { OUTPUT_SCHEMA_VERSION, } from "./contracts.js";
+import { redactErrorMessage, redactValue } from "./redaction.js";
+function jsonLine(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function humanValue(value) {
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(value, null, 2);
+}
+export function emitSuccess(context, data) {
+    const envelope = {
+        ok: true,
+        data: redactValue(data),
+        meta: {
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            command: context.command,
+            generated_at: new Date().toISOString(),
+        },
+    };
+    if (context.json) {
+        jsonLine(envelope);
+        return;
+    }
+    process.stdout.write(`${humanValue(envelope.data)}\n`);
+}
+export function emitError(context, error) {
+    const safeError = {
+        code: error.code,
+        message: redactErrorMessage(error.message),
+        retryable: error.retryable,
+    };
+    const envelope = {
+        ok: false,
+        error: safeError,
+        meta: {
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            command: context.command,
+        },
+    };
+    if (context.json) {
+        jsonLine(envelope);
+    }
+    else {
+        process.stderr.write(`${safeError.code}: ${safeError.message}\n`);
+    }
+    return error.exit_code;
+}

package/dist/pkce.js

@@ -0,0 +1,15 @@
+import { createHash, randomBytes } from "node:crypto";
+const VERIFIER_PATTERN = /^[A-Za-z0-9._~-]{43,128}$/;
+function base64Url(value) {
+    return value.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+/** Generate RFC 7636 S256 material without retaining it outside the caller. */
+export function createPkcePair() {
+    const verifier = base64Url(randomBytes(32));
+    const challenge = base64Url(createHash("sha256").update(verifier, "ascii").digest());
+    return Object.freeze({ verifier, challenge, method: "S256" });
+}
+export function isValidCodeVerifier(value) {
+    return typeof value === "string" && VERIFIER_PATTERN.test(value);
+}
+export const generatePkce = createPkcePair;

package/dist/profile-lock.js

@@ -0,0 +1,126 @@
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { configRoot, normalizeProfileName } from "./config.js";
+export class ProfileLockError extends Error {
+    code = "AUTH_LOCK_TIMEOUT";
+    constructor(message = "Another process is refreshing this profile") {
+        super(message);
+        this.name = "ProfileLockError";
+    }
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+export function profileLockPath(profile, environment = process.env) {
+    const name = normalizeProfileName(profile);
+    return join(configRoot(environment), "locks", `${name}.lock`);
+}
+export class ProfileLock {
+    path;
+    options;
+    nonce = randomBytes(12).toString("hex");
+    held = false;
+    constructor(profile, options = {}) {
+        this.path = profileLockPath(profile, options.environment);
+        this.options = {
+            timeoutMs: options.timeoutMs ?? 15000,
+            staleMs: options.staleMs ?? 120000,
+            retryMs: options.retryMs ?? 40,
+        };
+        if (!Number.isFinite(this.options.timeoutMs) || this.options.timeoutMs < 1)
+            throw new ProfileLockError("Profile lock timeout is invalid");
+        if (!Number.isFinite(this.options.staleMs) || this.options.staleMs < 1)
+            throw new ProfileLockError("Profile lock stale timeout is invalid");
+    }
+    async acquire() {
+        const started = Date.now();
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        while (Date.now() - started <= this.options.timeoutMs) {
+            try {
+                const descriptor = openSync(this.path, "wx", 0o600);
+                try {
+                    writeFileSync(descriptor, JSON.stringify({ pid: process.pid, created_at: Date.now(), nonce: this.nonce }));
+                }
+                finally {
+                    closeSync(descriptor);
+                }
+                this.held = true;
+                return () => this.release();
+            }
+            catch (error) {
+                if (!(error && typeof error === "object" && "code" in error && error.code === "EEXIST")) {
+                    throw new ProfileLockError("Unable to create profile refresh lock");
+                }
+                if (this.removeIfStale())
+                    continue;
+                await sleep(this.options.retryMs);
+            }
+        }
+        throw new ProfileLockError();
+    }
+    release() {
+        if (!this.held)
+            return;
+        this.held = false;
+        try {
+            const raw = JSON.parse(readFileSync(this.path, "utf8"));
+            if (raw.nonce !== this.nonce)
+                return;
+        }
+        catch {
+            // A crashed/recovered lock is already no longer owned by this instance.
+            return;
+        }
+        try {
+            unlinkSync(this.path);
+        }
+        catch {
+            // Release is best effort; a missing lock is already released.
+        }
+    }
+    removeIfStale() {
+        try {
+            const metadata = statSync(this.path);
+            const age = Date.now() - metadata.mtimeMs;
+            if (age < this.options.staleMs)
+                return false;
+            let pid;
+            try {
+                const raw = JSON.parse(readFileSync(this.path, "utf8"));
+                if (typeof raw.pid === "number" && Number.isInteger(raw.pid) && raw.pid > 0)
+                    pid = raw.pid;
+            }
+            catch {
+                // Invalid metadata can be recovered only after the stale threshold.
+            }
+            if (pid !== undefined) {
+                try {
+                    process.kill(pid, 0);
+                    return false;
+                }
+                catch (error) {
+                    if (error && typeof error === "object" && "code" in error && error.code === "EPERM")
+                        return false;
+                    if (!(error && typeof error === "object" && "code" in error && error.code === "ESRCH"))
+                        return false;
+                }
+            }
+            unlinkSync(this.path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export async function withProfileLock(profile, operation, options = {}) {
+    const lock = new ProfileLock(profile, options);
+    const release = await lock.acquire();
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+    }
+}