@litfamily/litopencode 1.0.0

package/dist/cli/auto-update.js

@@ -0,0 +1,604 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { defaultOpenCodeConfigRoot } from "../state.js";
+import { compareStableVersions, parseStableVersion, requestRegistryLatestVersion } from "./update-notifier.js";
+import { readPackageMetadata } from "./json.js";
+export const autoUpdatePackageName = "@litfamily/litopencode";
+export const autoUpdateTimeoutMs = 30_000;
+/** npm install, staged install, and post-install doctor each have this bound. */
+export const autoUpdateTransactionBoundMs = autoUpdateTimeoutMs * 3;
+export const autoUpdateLockTimeoutMs = 2_000;
+/** Keep a live owner protected for the whole bounded transaction plus one command window. */
+export const autoUpdateInstallLockStaleMs = autoUpdateTransactionBoundMs + autoUpdateTimeoutMs;
+export const autoUpdateRecursionEnv = "LITOPENCODE_AUTO_UPDATE_IN_PROGRESS";
+const stateRootName = ".litopencode";
+const receiptFileName = "auto-update-receipt.json";
+const journalFileName = "auto-update-journal.jsonl";
+const installLockFileName = "auto-update-install.lock";
+const maxCommandOutputBytes = 4 * 1024 * 1024;
+const execFileAsync = promisify(execFile);
+function stateRoot(homeDir) {
+    return path.join(homeDir, stateRootName);
+}
+export function autoUpdateInstallLockPath(homeDir = os.homedir()) {
+    return path.join(stateRoot(homeDir), installLockFileName);
+}
+export function autoUpdateJournalPath(homeDir = os.homedir()) {
+    return path.join(stateRoot(homeDir), journalFileName);
+}
+export function autoUpdateReceiptPath(homeDir = os.homedir()) {
+    return path.join(stateRoot(homeDir), receiptFileName);
+}
+function truthyEnvironmentValue(value) {
+    return value !== undefined;
+}
+export function isAutoUpdateDisabled(env = process.env, argv = []) {
+    return (argv.includes("--no-auto-update") ||
+        truthyEnvironmentValue(env.LITOPENCODE_NO_AUTO_UPDATE) ||
+        truthyEnvironmentValue(env.NO_UPDATE_NOTIFIER) ||
+        truthyEnvironmentValue(env.LITOPENCODE_NO_UPDATE_CHECK) ||
+        truthyEnvironmentValue(env[autoUpdateRecursionEnv]) ||
+        truthyEnvironmentValue(env.CI));
+}
+export function shouldRunInteractiveAutoUpdate(input) {
+    if (input.exitCode !== 0)
+        return false;
+    if (input.argv[0] !== "install" && input.argv[0] !== "doctor")
+        return false;
+    if (input.argv.some((arg) => arg === "--dry-run" || arg === "--json" || arg === "--help" || arg === "-h"))
+        return false;
+    if (input.stdinIsTTY !== true || input.stdoutIsTTY !== true || input.stderrIsTTY !== true)
+        return false;
+    return !isAutoUpdateDisabled(input.env, input.argv);
+}
+/**
+ * Keep npm child processes deliberately boring. In particular, npm config files,
+ * tokens, proxy credentials, and arbitrary `npm_config_*` values are not inherited.
+ */
+export function sanitizedNpmEnvironment(env = process.env) {
+    const child = {};
+    const safeKeys = [
+        "HOME",
+        "USERPROFILE",
+        "HOMEDRIVE",
+        "HOMEPATH",
+        "SystemRoot",
+        "SYSTEMROOT",
+        "PATH",
+        "TMPDIR",
+        "TMP",
+        "TEMP",
+        "XDG_CONFIG_HOME",
+        "XDG_CACHE_HOME",
+        "NODE_EXTRA_CA_CERTS",
+        "SSL_CERT_FILE",
+        "SSL_CERT_DIR"
+    ];
+    for (const key of safeKeys) {
+        if (env[key] !== undefined)
+            child[key] = env[key];
+    }
+    child[autoUpdateRecursionEnv] = "1";
+    child.LITOPENCODE_NO_AUTO_UPDATE = "1";
+    child.NO_UPDATE_NOTIFIER = "1";
+    child.LITOPENCODE_NO_UPDATE_CHECK = "1";
+    return child;
+}
+function commandFailure(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const candidate = error;
+    const stderr = typeof candidate.stderr === "string" ? candidate.stderr.trim() : "";
+    const stdout = typeof candidate.stdout === "string" ? candidate.stdout.trim() : "";
+    const code = candidate.code === undefined ? "" : String(candidate.code);
+    const signal = candidate.signal === undefined ? "" : String(candidate.signal);
+    return [stderr ? `stderr: ${stderr}` : "", stdout ? `stdout: ${stdout}` : "", code ? `code: ${code}` : "", signal ? `signal: ${signal}` : "", !stderr && !stdout && !code && !signal ? error.message : ""]
+        .filter(Boolean)
+        .join("; ");
+}
+async function defaultRunCommand(command, args, options) {
+    return await execFileAsync(command, [...args], options);
+}
+async function bounded(operation, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`automatic update command exceeded ${timeoutMs}ms`)), timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+async function ensurePrivateStateRoot(homeDir) {
+    const directory = stateRoot(homeDir);
+    try {
+        const stat = await fs.lstat(directory);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error("automatic update state root is unsafe");
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            throw new Error("automatic update state root is not user-owned");
+        if ((stat.mode & 0o077) !== 0)
+            throw new Error("automatic update state root is not private");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    }
+    return directory;
+}
+async function readLockTimestamp(lockPath) {
+    try {
+        const stat = await fs.lstat(lockPath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return undefined;
+        const parsed = JSON.parse(await fs.readFile(lockPath, "utf8"));
+        return typeof parsed.acquiredAt === "number" ? parsed.acquiredAt : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pause(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function acquireInstallLock(homeDir) {
+    await ensurePrivateStateRoot(homeDir);
+    const lockPath = autoUpdateInstallLockPath(homeDir);
+    const deadline = Date.now() + autoUpdateLockTimeoutMs;
+    while (Date.now() < deadline) {
+        const token = randomUUID();
+        try {
+            const handle = await fs.open(lockPath, "wx", 0o600);
+            await handle.writeFile(`${JSON.stringify({ token, acquiredAt: Date.now() })}\n`, "utf8");
+            await handle.close();
+            return { path: lockPath, token };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const acquiredAt = await readLockTimestamp(lockPath);
+            if (acquiredAt !== undefined && Date.now() - acquiredAt >= autoUpdateInstallLockStaleMs) {
+                await fs.rm(lockPath, { force: true });
+                continue;
+            }
+            await pause(25);
+        }
+    }
+    return undefined;
+}
+async function releaseInstallLock(lock) {
+    if ((await readLockTimestamp(lock.path)) === undefined)
+        return;
+    let ownerToken;
+    try {
+        const parsed = JSON.parse(await fs.readFile(lock.path, "utf8"));
+        ownerToken = typeof parsed.token === "string" ? parsed.token : undefined;
+    }
+    catch {
+        return;
+    }
+    if (ownerToken === lock.token)
+        await fs.rm(lock.path, { force: true });
+}
+async function appendJournal(homeDir, event, fields) {
+    const journalPath = autoUpdateJournalPath(homeDir);
+    await ensurePrivateStateRoot(homeDir);
+    try {
+        const stat = await fs.lstat(journalPath);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error("automatic update journal is unsafe");
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            throw new Error("automatic update journal is not user-owned");
+        if ((stat.mode & 0o077) !== 0)
+            throw new Error("automatic update journal is not private");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await fs.appendFile(journalPath, `${JSON.stringify({ schemaVersion: 1, event, at: Date.now(), ...fields })}\n`, {
+        encoding: "utf8",
+        mode: 0o600
+    });
+    await fs.chmod(journalPath, 0o600).catch(() => undefined);
+}
+async function tryAppendJournal(homeDir, event, fields) {
+    try {
+        await appendJournal(homeDir, event, fields);
+    }
+    catch {
+        // Journal failure must not skip the restore attempt. The receipt remains
+        // the authoritative failure surface when the journal itself is unsafe.
+    }
+}
+async function lstatKind(filePath) {
+    try {
+        const stat = await fs.lstat(filePath);
+        if (stat.isSymbolicLink())
+            throw new Error(`automatic update refuses symbolic-link backup source: ${filePath}`);
+        if (stat.isFile())
+            return "file";
+        if (stat.isDirectory())
+            return "directory";
+        throw new Error(`automatic update refuses special backup source: ${filePath}`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function captureSnapshot(configRoot, homeDir) {
+    const snapshotPath = path.join(stateRoot(homeDir), `.auto-update-backup-${randomUUID()}`);
+    await fs.mkdir(snapshotPath, { recursive: true, mode: 0o700 });
+    const entries = [];
+    for (const relativePath of ["opencode.json", "opencode.jsonc", "litopencode.json", "command", "skills"]) {
+        const source = path.join(configRoot, relativePath);
+        const kind = await lstatKind(source);
+        if (kind === undefined) {
+            entries.push({ relativePath, existed: false });
+            continue;
+        }
+        const destination = path.join(snapshotPath, relativePath);
+        await fs.cp(source, destination, { recursive: kind === "directory", force: false, errorOnExist: false, dereference: false });
+        entries.push({ relativePath, existed: true, kind });
+    }
+    await fs.writeFile(path.join(snapshotPath, "manifest.json"), `${JSON.stringify({ schemaVersion: 1, entries }, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600
+    });
+    return { path: snapshotPath, entries };
+}
+async function ensureConfigRoot(configRoot) {
+    try {
+        const stat = await fs.lstat(configRoot);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error(`automatic update config root is unsafe: ${configRoot}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        await fs.mkdir(configRoot, { recursive: true, mode: 0o700 });
+    }
+}
+async function restoreSnapshot(configRoot, snapshot) {
+    // Re-check the root immediately before restoring. The updater never writes
+    // through a root that was replaced with a symlink while the child command
+    // was running.
+    await ensureConfigRoot(configRoot);
+    for (const entry of snapshot.entries) {
+        const target = path.join(configRoot, entry.relativePath);
+        await fs.rm(target, { recursive: true, force: true });
+        if (!entry.existed)
+            continue;
+        const source = path.join(snapshot.path, entry.relativePath);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.cp(source, target, { recursive: entry.kind === "directory", force: false, errorOnExist: false, dereference: false });
+    }
+}
+async function fingerprintPath(filePath) {
+    const stat = await fs.lstat(filePath);
+    if (stat.isSymbolicLink())
+        return `link:${await fs.readlink(filePath)}`;
+    if (stat.isFile()) {
+        const hash = createHash("sha256");
+        hash.update(await fs.readFile(filePath));
+        return `file:${hash.digest("hex")}`;
+    }
+    if (stat.isDirectory()) {
+        const children = await fs.readdir(filePath);
+        children.sort();
+        const parts = [];
+        for (const child of children) {
+            parts.push(`${child}:${await fingerprintPath(path.join(filePath, child))}`);
+        }
+        return `dir:${parts.join("|")}`;
+    }
+    return `special:${stat.mode}`;
+}
+async function verifySnapshot(configRoot, snapshot) {
+    try {
+        await ensureConfigRoot(configRoot);
+        for (const entry of snapshot.entries) {
+            const target = path.join(configRoot, entry.relativePath);
+            let targetFingerprint;
+            try {
+                targetFingerprint = await fingerprintPath(target);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    return false;
+            }
+            if (!entry.existed) {
+                if (targetFingerprint !== undefined)
+                    return false;
+                continue;
+            }
+            if (targetFingerprint === undefined)
+                return false;
+            const sourceFingerprint = await fingerprintPath(path.join(snapshot.path, entry.relativePath));
+            if (targetFingerprint !== sourceFingerprint)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeReceipt(homeDir, receipt) {
+    await ensurePrivateStateRoot(homeDir);
+    const receiptPath = autoUpdateReceiptPath(homeDir);
+    const temporary = `${receiptPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await fs.rename(temporary, receiptPath);
+    await fs.chmod(receiptPath, 0o600).catch(() => undefined);
+}
+function parseDoctorOutput(output, currentVersion) {
+    try {
+        const parsed = JSON.parse(output.stdout ?? "");
+        const packageRecord = parsed.package;
+        const install = parsed.install;
+        const packageName = typeof packageRecord?.name === "string" ? packageRecord.name : undefined;
+        const version = typeof packageRecord?.version === "string" ? packageRecord.version : undefined;
+        const ok = packageName === autoUpdatePackageName && version === currentVersion && install?.ok === true;
+        return { ok, package: { name: packageName, version }, ...(ok ? {} : { error: "post-install doctor did not verify exact package identity and install surfaces" }) };
+    }
+    catch (error) {
+        return { ok: false, error: `post-install doctor returned invalid JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+async function packageEntrypoint(stageRoot, targetVersion) {
+    const packageRoot = path.join(stageRoot, "node_modules", autoUpdatePackageName);
+    const packageMetadata = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+    if (packageMetadata.name !== autoUpdatePackageName || packageMetadata.version !== targetVersion) {
+        throw new Error("npm install produced a package with an unexpected stable name or version");
+    }
+    if (parseStableVersion(packageMetadata.version) === undefined)
+        throw new Error("npm install produced a non-stable package version");
+    const entrypoint = path.join(packageRoot, "bin", "litopencode.cjs");
+    const stat = await fs.lstat(entrypoint);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error("npm install produced an unsafe CLI entrypoint");
+    return entrypoint;
+}
+async function updateTransaction(options, homeDir, currentVersion, targetVersion, runCommand) {
+    const startedAt = Date.now();
+    const spec = `${autoUpdatePackageName}@${targetVersion}`;
+    const journalPath = autoUpdateJournalPath(homeDir);
+    await ensureConfigRoot(options.configRoot);
+    const snapshot = await captureSnapshot(options.configRoot, homeDir);
+    const stageRoot = path.join(stateRoot(homeDir), `.auto-update-stage-${randomUUID()}`);
+    let doctor = { ok: false, error: "post-install doctor did not run" };
+    let rollback = { ok: true };
+    let status = "failed";
+    // A staged package is considered known while no host mutation has started.
+    // Once an installer/doctor child is in flight, a timeout or signal makes the
+    // resulting host state unknown until the snapshot is restored and verified.
+    let stagedStateKnown = true;
+    let priorStateVerified = false;
+    try {
+        await fs.mkdir(stageRoot, { recursive: true, mode: 0o700 });
+        await fs.writeFile(path.join(stageRoot, "package.json"), '{"private":true}\n', { encoding: "utf8", mode: 0o600 });
+        const npmrcPath = path.join(stageRoot, ".npmrc");
+        await fs.writeFile(npmrcPath, "# LitOpenCode automatic-update transaction\n", { encoding: "utf8", mode: 0o600 });
+        await appendJournal(homeDir, "begin", { reason: options.reason, currentVersion, targetVersion, spec, configRoot: options.configRoot });
+        const childEnv = {
+            ...sanitizedNpmEnvironment(options.env),
+            // Prevent npm from reading a user's HOME/.npmrc while retaining a
+            // deterministic, empty config for registry resolution.
+            NPM_CONFIG_USERCONFIG: npmrcPath
+        };
+        const npmArgs = [
+            "install",
+            "--prefix",
+            stageRoot,
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+            "--no-package-lock",
+            "--no-save",
+            spec
+        ];
+        await bounded(() => runCommand("npm", npmArgs, { cwd: stageRoot, env: childEnv, timeout: autoUpdateTimeoutMs, maxBuffer: maxCommandOutputBytes }), autoUpdateTimeoutMs);
+        await appendJournal(homeDir, "npm-install", { spec });
+        const entrypoint = await packageEntrypoint(stageRoot, targetVersion);
+        const installArgs = [entrypoint, "install", "--root", options.configRoot, "--no-model-prompt", "--no-permission-prompt", "--no-auto-update"];
+        stagedStateKnown = false;
+        await bounded(() => runCommand(process.execPath, installArgs, { cwd: options.configRoot, env: childEnv, timeout: autoUpdateTimeoutMs, maxBuffer: maxCommandOutputBytes }), autoUpdateTimeoutMs);
+        stagedStateKnown = true;
+        await appendJournal(homeDir, "install", { spec });
+        const doctorArgs = [entrypoint, "doctor", "--root", options.configRoot, "--json", "--no-auto-update"];
+        stagedStateKnown = false;
+        const doctorOutput = await bounded(() => runCommand(process.execPath, doctorArgs, { cwd: options.configRoot, env: childEnv, timeout: autoUpdateTimeoutMs, maxBuffer: maxCommandOutputBytes }), autoUpdateTimeoutMs);
+        doctor = parseDoctorOutput(doctorOutput, targetVersion);
+        stagedStateKnown = doctor.package?.name !== undefined && doctor.package.version !== undefined;
+        await appendJournal(homeDir, "doctor", { ok: doctor.ok, package: doctor.package, error: doctor.error });
+        if (!doctor.ok)
+            throw new Error(doctor.error ?? "post-install doctor failed");
+        status = "updated";
+        await appendJournal(homeDir, "updated", { spec });
+    }
+    catch (error) {
+        const failure = commandFailure(error);
+        await tryAppendJournal(homeDir, "failure", { error: failure });
+        try {
+            await restoreSnapshot(options.configRoot, snapshot);
+            priorStateVerified = await verifySnapshot(options.configRoot, snapshot);
+            if (!priorStateVerified)
+                throw new Error("automatic update rollback could not verify the prior config and managed surfaces");
+            rollback = { ok: true };
+            status = "rolled-back";
+            await tryAppendJournal(homeDir, "rollback", { ok: true, priorStateVerified, stagedStateKnown });
+        }
+        catch (rollbackError) {
+            rollback = { ok: false, error: commandFailure(rollbackError) };
+            status = "failed";
+            await tryAppendJournal(homeDir, "rollback", { ok: false, error: rollback.error, priorStateVerified, stagedStateKnown });
+        }
+    }
+    finally {
+        await fs.rm(stageRoot, { recursive: true, force: true });
+        if (status === "updated")
+            await fs.rm(snapshot.path, { recursive: true, force: true });
+    }
+    const receipt = {
+        schemaVersion: 1,
+        status,
+        reason: options.reason,
+        currentVersion,
+        targetVersion,
+        spec,
+        configRoot: options.configRoot,
+        startedAt,
+        finishedAt: Date.now(),
+        journalPath,
+        backupPath: snapshot.path,
+        backupRetained: status !== "updated",
+        priorStateVerified: status === "updated" ? true : priorStateVerified,
+        stagedStateKnown,
+        doctor,
+        rollback
+    };
+    await writeReceipt(homeDir, receipt);
+    return {
+        status,
+        currentVersion,
+        targetVersion,
+        spec,
+        receiptPath: autoUpdateReceiptPath(homeDir),
+        backupPath: snapshot.path,
+        priorStateVerified: receipt.priorStateVerified,
+        stagedStateKnown,
+        ...(status === "rolled-back" || status === "failed" ? { rollback } : {})
+    };
+}
+export async function runAutoUpdate(options) {
+    const env = options.env ?? process.env;
+    if (isAutoUpdateDisabled(env, options.argv))
+        return { status: "skipped", reason: "disabled" };
+    if (parseStableVersion(options.currentVersion) === undefined)
+        return { status: "skipped", reason: "invalid-current-version" };
+    const homeDir = options.homeDir ?? os.homedir();
+    const fetchLatestVersion = options.fetchLatestVersion ?? requestRegistryLatestVersion;
+    let targetVersion;
+    try {
+        targetVersion = await bounded(fetchLatestVersion, autoUpdateTimeoutMs);
+    }
+    catch {
+        return { status: "skipped", currentVersion: options.currentVersion, reason: "registry-unavailable" };
+    }
+    if (parseStableVersion(targetVersion) === undefined)
+        return { status: "skipped", currentVersion: options.currentVersion, reason: "invalid-latest-version" };
+    const comparison = compareStableVersions(targetVersion, options.currentVersion);
+    if (comparison !== 1)
+        return { status: "skipped", currentVersion: options.currentVersion, targetVersion, reason: "up-to-date" };
+    const lock = await acquireInstallLock(homeDir);
+    if (lock === undefined)
+        return { status: "skipped", currentVersion: options.currentVersion, targetVersion, reason: "install-lock-busy" };
+    try {
+        await ensurePrivateStateRoot(homeDir);
+        const runCommand = options.runCommand ?? defaultRunCommand;
+        return await updateTransaction(options, homeDir, options.currentVersion, targetVersion, runCommand);
+    }
+    finally {
+        await releaseInstallLock(lock);
+    }
+}
+/**
+ * A failed transaction is safe to leave in place only when the old managed
+ * state was restored and verified. Unknown child state or an unverified
+ * rollback must stop the host from claiming a successful install.
+ */
+export function canContinueAfterAutoUpdate(result) {
+    if (result.status === "updated" || result.status === "skipped")
+        return true;
+    return result.status === "rolled-back" && result.rollback?.ok === true && result.priorStateVerified === true && result.stagedStateKnown === true;
+}
+export function autoUpdateDiagnostic(result) {
+    const receipt = result.receiptPath ?? autoUpdateReceiptPath();
+    const backup = result.backupPath === undefined ? "" : ` Retained backup: ${result.backupPath}.`;
+    return `Automatic update stopped without claiming success (${result.status}). Inspect the receipt at ${receipt}.${backup}`;
+}
+/** Read only the bounded safety summary used by doctor; never echo command output. */
+export async function readAutoUpdateReceipt(homeDir = os.homedir()) {
+    const receiptPath = autoUpdateReceiptPath(homeDir);
+    try {
+        const stat = await fs.lstat(receiptPath);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            return { status: "unreadable" };
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            return { status: "unreadable" };
+        if ((stat.mode & 0o077) !== 0)
+            return { status: "unreadable" };
+        const parsed = JSON.parse(await fs.readFile(receiptPath, "utf8"));
+        if (parsed.schemaVersion !== 1 ||
+            (parsed.status !== "updated" && parsed.status !== "rolled-back" && parsed.status !== "failed" && parsed.status !== "skipped") ||
+            typeof parsed.backupPath !== "string" ||
+            typeof parsed.backupRetained !== "boolean" ||
+            typeof parsed.priorStateVerified !== "boolean" ||
+            typeof parsed.stagedStateKnown !== "boolean" ||
+            typeof parsed.rollback?.ok !== "boolean" ||
+            typeof parsed.finishedAt !== "number") {
+            return { status: "unreadable" };
+        }
+        return {
+            status: parsed.status,
+            backupPath: parsed.backupPath,
+            backupRetained: parsed.backupRetained,
+            priorStateVerified: parsed.priorStateVerified,
+            stagedStateKnown: parsed.stagedStateKnown,
+            rollbackOk: parsed.rollback.ok,
+            finishedAt: parsed.finishedAt
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        return { status: "unreadable" };
+    }
+}
+async function isLocalCheckout(packageRoot) {
+    try {
+        const stat = await fs.lstat(path.join(packageRoot, ".git"));
+        return stat.isDirectory() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function runPluginAutoUpdate() {
+    const metadata = await readPackageMetadata();
+    if (await isLocalCheckout(metadata.packageRoot))
+        return { status: "skipped", reason: "local-checkout" };
+    return await runAutoUpdate({
+        reason: "plugin",
+        configRoot: defaultOpenCodeConfigRoot(),
+        currentVersion: metadata.version,
+        env: process.env
+    });
+}
+export async function runInteractiveAutoUpdate(input) {
+    if (!shouldRunInteractiveAutoUpdate(input))
+        return { status: "skipped", reason: "ineligible" };
+    const metadata = await readPackageMetadata();
+    if (await isLocalCheckout(metadata.packageRoot))
+        return { status: "skipped", reason: "local-checkout" };
+    return await runAutoUpdate({
+        reason: "management",
+        configRoot: input.configRoot ?? defaultOpenCodeConfigRoot(),
+        currentVersion: metadata.version,
+        env: input.env,
+        argv: input.argv
+    });
+}

package/dist/cli/command-alias-ownership.d.ts

@@ -0,0 +1,2 @@
+export type CommandAliasOwnership = "missing" | "managed" | "preserved";
+export declare function commandAliasOwnership(root: string, id: string): Promise<CommandAliasOwnership>;

package/dist/cli/command-alias-ownership.js

@@ -0,0 +1,14 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { hasLitOpenCodeGeneratedFileMarker } from "../user-facing-markdown.js";
+export async function commandAliasOwnership(root, id) {
+    try {
+        const existing = await fs.readFile(path.join(root, "command", id + ".md"), "utf8");
+        return hasLitOpenCodeGeneratedFileMarker(existing) ? "managed" : "preserved";
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}

package/dist/cli/command-aliases.d.ts

@@ -0,0 +1,12 @@
+import type { InstallReport } from "./types.ts";
+export declare function describeCommandAliasMutation(root: string): Promise<InstallReport["commandAliases"]>;
+export declare function inspectCommandAliases(root: string): Promise<{
+    readonly path: string;
+    readonly expected: readonly string[];
+    readonly present: readonly string[];
+    readonly missing: readonly string[];
+    readonly managed: readonly string[];
+    readonly preserved: readonly string[];
+    readonly ok: boolean;
+}>;
+export declare function ensureCommandAliases(root: string): Promise<void>;