@yijiancaotang/cli 0.0.0-stage → 1.1.0

package/dist/installation.js

@@ -0,0 +1,761 @@
+import { constants, lstatSync, fstatSync, openSync, closeSync, readSync, writeFileSync, fsyncSync, fchmodSync, ftruncateSync, mkdirSync, readdirSync, rmdirSync } from "node:fs";
+import { access, lstat, stat, realpath, open, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { CliError, asRecord } from "./errors.js";
+import { PLATFORM_IDS, isPlatformId, platformSupported } from "./local-types.js";
+import { bindSkillAgent, completeSkillInventory } from "./skill-assets.js";
+import { acquireLocalLock } from "./local-lock.js";
+import { LEGACY_MANAGED_SKILLS } from "./managed-skill-baseline.js";
+import { REVIEWED_MANAGED_BUNDLE_1_1_0 } from "./reviewed-managed-bundle-baseline.js";
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const missing = (error) => asRecord(error)?.code === "ENOENT";
+const unsafe = () => new CliError("installation_unsafe", "本地安装位置未通过安全检查。", "请人工检查属主、权限、符号链接与目标目录；不要自动删除、覆盖或修改凭据。");
+const permissionDenied = (path) => new CliError("installation_permission_denied", "没有权限访问本地安装目标目录。", "请由本人核对详情中目标目录的访问权限；不要自动提权或放宽权限。", 4, { target_directory: path });
+const conflict = () => new CliError("installation_conflict", "已有命令行文件与当前候选不一致。", "保留已有文件，先人工核对安装来源；不要强制覆盖或删除。");
+const skillConflict = () => new CliError("skill_conflict", "已有同名技能与当前候选不一致。", "保留原技能，人工核对冲突；不要覆盖个人修改。");
+const sourceInvalid = () => new CliError("installation_source_invalid", "当前命令行构建或技能资源不完整。", "使用维护者提供的完整且已审核的构建，不要运行不明安装脚本。", 7);
+const packageRoot = () => fileURLToPath(new URL("../", import.meta.url));
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const unchanged = (a, b) => same(a, b) && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+// No await or user callback while cwd is pinned: relative operations use the checked directory inode.
+function pinned(directory, action, failure = unsafe) {
+    const original = process.cwd();
+    try {
+        process.chdir(directory.path);
+        const current = lstatSync(".");
+        if (!current.isDirectory() || !same(current, directory.identity) || current.uid !== directory.identity.uid || (current.mode & 0o7777) !== (directory.identity.mode & 0o7777))
+            throw failure();
+        return action();
+    }
+    finally {
+        process.chdir(original);
+    }
+}
+function readDescriptor(fd, max) {
+    const bytes = Buffer.alloc(max + 1);
+    let length = 0;
+    while (length < bytes.length) {
+        const read = readSync(fd, bytes, length, bytes.length - length, length);
+        if (!read)
+            break;
+        length += read;
+    }
+    return bytes.subarray(0, length);
+}
+export class OwnedTree {
+    home;
+    uid;
+    constructor(home) { if (!isAbsolute(home) || typeof process.getuid !== "function")
+        throw unsafe(); this.home = resolve(home); this.uid = process.getuid(); }
+    within(path) {
+        const absolute = resolve(path), rel = relative(this.home, absolute);
+        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+            throw unsafe();
+        return absolute;
+    }
+    checkDirectory(info, path) {
+        if (!info.isDirectory() || info.uid !== this.uid || (info.mode & 0o022) !== 0)
+            throw unsafe();
+        const rel = relative(this.home, path);
+        if ((rel === ".caotang" || rel.startsWith(`.caotang${sep}`)) && (info.mode & 0o7777) !== 0o700)
+            throw unsafe();
+    }
+    async verify(directories) {
+        for (const directory of directories) {
+            const info = await lstat(directory.path);
+            this.checkDirectory(info, directory.path);
+            if (!same(info, directory.identity) || !same(await directory.handle.stat(), directory.identity))
+                throw unsafe();
+        }
+    }
+    async directory(path, create, action) {
+        const absolute = this.within(path), rel = relative(this.home, absolute), directories = [];
+        try {
+            let current = this.home;
+            for (const part of [null, ...(rel ? rel.split(sep) : [])]) {
+                if (part !== null)
+                    current = join(current, part);
+                let info;
+                try {
+                    info = await lstat(current);
+                }
+                catch (error) {
+                    if (!missing(error))
+                        throw error;
+                    if (current === this.home)
+                        throw unsafe();
+                    if (!create)
+                        return null;
+                    await this.verify(directories);
+                    const parent = directories.at(-1);
+                    if (!parent)
+                        throw unsafe();
+                    pinned(parent, () => {
+                        try {
+                            mkdirSync(part, { mode: 0o700 });
+                        }
+                        catch (created) {
+                            if (asRecord(created)?.code !== "EEXIST")
+                                throw created;
+                        }
+                    });
+                    info = await lstat(current);
+                }
+                this.checkDirectory(info, current);
+                if (await realpath(current) !== current)
+                    throw unsafe();
+                const handle = await open(current, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+                directories.push({ path: current, handle, identity: info });
+                if (!same(info, await handle.stat()))
+                    throw unsafe();
+            }
+            await this.verify(directories);
+            const value = await action(directories);
+            await this.verify(directories);
+            return value;
+        }
+        catch (error) {
+            if (!(error instanceof CliError) && ["EACCES", "EPERM"].includes(String(asRecord(error)?.code)))
+                throw permissionDenied(absolute);
+            throw error;
+        }
+        finally {
+            for (const directory of directories.reverse())
+                await directory.handle.close();
+        }
+    }
+    checkFile(info, max) {
+        if (!info.isFile() || info.uid !== this.uid || info.nlink !== 1 || (info.mode & 0o022) !== 0 || info.size > max)
+            throw unsafe();
+    }
+    readFile(name, max, executable = false, mode) {
+        const check = (info) => { this.checkFile(info, max); if (executable && (info.mode & 0o100) === 0 || mode !== undefined && (info.mode & 0o7777) !== mode)
+            throw unsafe(); };
+        let before;
+        try {
+            before = lstatSync(name);
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+        check(before);
+        const fd = openSync(name, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const opened = fstatSync(fd);
+            check(opened);
+            if (!unchanged(before, opened))
+                throw unsafe();
+            const bytes = readDescriptor(fd, max), after = fstatSync(fd), current = lstatSync(name);
+            check(after);
+            check(current);
+            if (bytes.length !== opened.size || !unchanged(opened, after) || !unchanged(after, current))
+                throw unsafe();
+            return bytes;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    async read(path, max = 1048576, mode) {
+        return this.directory(dirname(path), false, async (directories) => {
+            return pinned(directories.at(-1), () => this.readFile(basename(path), max, false, mode));
+        });
+    }
+    async list(path) {
+        return this.directory(path, false, async (directories) => pinned(directories.at(-1), () => readdirSync(".").sort()));
+    }
+    async createDirectory(path) {
+        return this.directory(dirname(path), true, async (directories) => {
+            await this.verify(directories);
+            return pinned(directories.at(-1), () => {
+                try {
+                    mkdirSync(basename(path), { mode: 0o700 });
+                }
+                catch (error) {
+                    if (asRecord(error)?.code === "EEXIST")
+                        return null;
+                    throw error;
+                }
+                const result = lstatSync(basename(path));
+                this.checkDirectory(result, path);
+                return result;
+            });
+        });
+    }
+    async writeNew(path, bytes, mode) {
+        const result = await this.directory(dirname(path), true, async (directories) => {
+            return pinned(directories.at(-1), () => {
+                const name = basename(path);
+                let fd;
+                try {
+                    fd = openSync(name, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0);
+                }
+                catch (error) {
+                    if (asRecord(error)?.code !== "EEXIST")
+                        throw error;
+                    if (!this.readFile(name, 1048576, (mode & 0o100) !== 0)?.equals(bytes))
+                        throw conflict();
+                    return false;
+                }
+                try {
+                    const initial = fstatSync(fd);
+                    this.checkFile(initial, bytes.length);
+                    if (initial.size !== 0 || (initial.mode & 0o7777) !== 0)
+                        throw unsafe();
+                    writeFileSync(fd, bytes);
+                    fsyncSync(fd);
+                    const written = fstatSync(fd), current = lstatSync(name);
+                    this.checkFile(written, bytes.length);
+                    this.checkFile(current, bytes.length);
+                    if (!same(initial, written) || !unchanged(written, current) || written.size !== bytes.length || !readDescriptor(fd, bytes.length).equals(bytes))
+                        throw unsafe();
+                    fchmodSync(fd, mode);
+                    fsyncSync(fd);
+                    const final = fstatSync(fd), published = lstatSync(name);
+                    this.checkFile(final, bytes.length);
+                    this.checkFile(published, bytes.length);
+                    if (!same(initial, final) || !unchanged(final, published) || (final.mode & 0o7777) !== mode || final.size !== bytes.length || final.mtimeMs !== written.mtimeMs
+                        || !readDescriptor(fd, bytes.length).equals(bytes) || !unchanged(final, fstatSync(fd)) || !unchanged(final, lstatSync(name)))
+                        throw unsafe();
+                    return true;
+                }
+                catch (error) {
+                    // Only this newly-created inode may be demoted; the pathname may now name somebody else's file.
+                    try {
+                        fchmodSync(fd, 0);
+                        fsyncSync(fd);
+                    }
+                    catch { /* Filesystem failure can prevent rollback; keep the installation failed. */ }
+                    throw error;
+                }
+                finally {
+                    closeSync(fd);
+                }
+            });
+        });
+        return result === true;
+    }
+    // Never truncate on open. Only an exact, single-link managed inode may change;
+    // the caller durably preserves its public before/after bytes before calling.
+    async replaceManaged(entry, rollback = false) {
+        const result = await this.directory(dirname(entry.path), false, async (directories) => pinned(directories.at(-1), () => {
+            const name = basename(entry.path), before = lstatSync(name);
+            const check = (info) => { this.checkFile(info, 1048576); if ((info.mode & 0o7777) !== entry.mode)
+                throw unsafe(); };
+            check(before);
+            const fd = openSync(name, constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const opened = fstatSync(fd);
+                check(opened);
+                if (!unchanged(before, opened) || rollback && (!entry.identity || !same(entry.identity, opened)))
+                    throw unsafe();
+                const expected = rollback ? entry.after : entry.before, next = rollback ? entry.before : entry.after;
+                if (!readDescriptor(fd, 1048576).equals(expected) || !unchanged(opened, fstatSync(fd)) || !unchanged(opened, lstatSync(name)))
+                    throw unsafe();
+                if (!rollback)
+                    entry.identity = opened;
+                writeFileSync(fd, next);
+                ftruncateSync(fd, next.length);
+                fsyncSync(fd);
+                const written = fstatSync(fd), named = lstatSync(name);
+                check(written);
+                check(named);
+                if (!same(opened, written) || !unchanged(written, named) || written.size !== next.length || !readDescriptor(fd, 1048576).equals(next)
+                    || !unchanged(written, fstatSync(fd)) || !unchanged(written, lstatSync(name)))
+                    throw unsafe();
+                return true;
+            }
+            finally {
+                closeSync(fd);
+            }
+        }));
+        if (result !== true)
+            throw unsafe();
+    }
+    async removeDirectory(path, expected) {
+        await this.directory(dirname(path), false, async (directories) => {
+            pinned(directories.at(-1), () => {
+                const info = lstatSync(basename(path));
+                this.checkDirectory(info, path);
+                if (!same(info, expected))
+                    throw unsafe();
+                rmdirSync(basename(path));
+            });
+        });
+    }
+}
+async function readSource(path, max = 1048576) {
+    try {
+        const parent = dirname(path), identity = await lstat(parent);
+        if (!identity.isDirectory() || await realpath(parent) !== parent)
+            throw sourceInvalid();
+        return pinned({ path: parent, identity }, () => {
+            const valid = (info) => { if (!info.isFile() || info.nlink !== 1 || info.size < 1 || info.size > max)
+                throw sourceInvalid(); };
+            const name = basename(path), before = lstatSync(name);
+            valid(before);
+            const fd = openSync(name, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const opened = fstatSync(fd);
+                valid(opened);
+                if (!unchanged(before, opened))
+                    throw sourceInvalid();
+                const bytes = readDescriptor(fd, max), after = fstatSync(fd), current = lstatSync(name);
+                valid(after);
+                valid(current);
+                if (bytes.length !== opened.size || !unchanged(opened, after) || !unchanged(after, current))
+                    throw sourceInvalid();
+                return bytes;
+            }
+            finally {
+                closeSync(fd);
+            }
+        }, sourceInvalid);
+    }
+    catch {
+        throw sourceInvalid();
+    }
+}
+function managedShim(directory) {
+    return Buffer.from(`#!/usr/bin/env node\n// caotang managed command v1\nimport(${JSON.stringify(pathToFileURL(join(directory, "bin", "caotang.cjs")).href)}).catch(()=>{process.stderr.write(JSON.stringify({code:"cli_unavailable",message:"本地命令行暂不可用。",next_action:"请人工核对本地安装，不要重复业务写入。"})+"\\n");process.exitCode=7;});\n`);
+}
+async function bundle(ctx, tree) {
+    if (!completeSkillInventory(ctx.assets.map(asset => asset.name)) || ctx.assets.some(asset => hash(asset.content) !== asset.sha256 || !asset.content || Buffer.byteLength(asset.content) > 65536))
+        throw sourceInvalid();
+    const source = resolve(ctx.packageRoot ?? packageRoot());
+    if (await realpath(source) !== source)
+        throw sourceInvalid();
+    const info = asRecord(JSON.parse((await readSource(join(source, "package.json"), 32768)).toString("utf8")));
+    if (!info || info.name !== "@yijiancaotang/cli" || (info.private !== true && asRecord(info.publishConfig)?.access !== "public") || typeof info.version !== "string" || !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i.test(info.version))
+        throw sourceInvalid();
+    const runtimeManifest = { name: info.name, version: info.version, private: true, type: "module", engines: { node: ">=20" }, bin: { caotang: "bin/caotang.cjs" } };
+    const files = [{ path: "package.json", bytes: Buffer.from(JSON.stringify(runtimeManifest)), mode: 0o600 }, { path: "bin/caotang.cjs", bytes: await readSource(join(source, "bin", "caotang.cjs")), mode: 0o700 }];
+    const dist = join(source, "dist");
+    if (!(await lstat(dist)).isDirectory() || await realpath(dist) !== dist)
+        throw sourceInvalid();
+    const modules = (await readdir(dist)).filter(name => name.endsWith(".js")).sort();
+    // The shipped runtime has one nested generated dependency. Keep the 64-file
+    // JS limit across both categories; do not recursively trust dist subtrees.
+    if (!modules.includes("cli.js") || modules.length + 1 > 64)
+        throw sourceInvalid();
+    for (const name of modules) {
+        if (!/^[a-z][a-z0-9-]*\.js$/.test(name))
+            throw sourceInvalid();
+        files.push({ path: `dist/${name}`, bytes: await readSource(join(dist, name)), mode: 0o600 });
+    }
+    files.push({ path: "dist/generated/knowledge-growth.js", bytes: await readSource(join(dist, "generated", "knowledge-growth.js")), mode: 0o600 });
+    files.push({ path: "skills/manifest.json", bytes: Buffer.from(JSON.stringify({ formatVersion: 1, skills: ctx.assets.map(({ name, description }) => ({ name, description })) })), mode: 0o600 });
+    for (const asset of ctx.assets)
+        files.push({ path: `skills/${asset.name}/SKILL.md`, bytes: Buffer.from(asset.content), mode: 0o600 });
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    if (files.reduce((total, file) => total + file.bytes.length, 0) > 5242880)
+        throw sourceInvalid();
+    const digest = createHash("sha256");
+    for (const file of files)
+        digest.update(`${file.path}\0${file.mode}\0${file.bytes.length}\0`).update(file.bytes);
+    const sha = digest.digest("hex"), directory = join(tree.home, ".caotang", "cli", "releases", sha), command = join(tree.home, ".local", "bin", "caotang");
+    const shim = managedShim(directory);
+    return { files, sha, directory, command, shim, version: info.version };
+}
+function validateTargets(ctx, tree) {
+    if (ctx.targets.length > PLATFORM_IDS.length || new Set(ctx.targets.map(target => target.id)).size !== ctx.targets.length)
+        throw unsafe();
+    for (const target of ctx.targets) {
+        if (!isPlatformId(target.id) || !platformSupported(target.id, ctx.operatingSystem) || !isAbsolute(target.skillDirectory) || tree.within(target.skillDirectory) === tree.home)
+            throw unsafe();
+    }
+}
+async function skillState(tree, target, asset) {
+    const dir = join(target.skillDirectory, asset.name), entries = await tree.list(dir);
+    if (entries === null || entries.length === 0)
+        return "missing";
+    if (entries.length !== 1 || entries[0] !== "SKILL.md")
+        return "modified";
+    const bytes = await tree.read(join(dir, "SKILL.md"), 65536);
+    return bytes && hash(bytes) === asset.sha256 ? "installed" : "modified";
+}
+async function bundleState(tree, value) {
+    if (await tree.list(value.directory) === null)
+        return "missing";
+    const expected = new Set(value.files.map(file => file.path));
+    async function walk(dir, prefix = "") {
+        const entries = await tree.list(dir);
+        if (!entries)
+            return false;
+        for (const name of entries) {
+            const path = prefix + name;
+            if (value.files.some(file => file.path.startsWith(path + "/"))) {
+                if (!await walk(join(dir, name), path + "/"))
+                    return false;
+            }
+            else if (!expected.has(path))
+                return false;
+        }
+        return true;
+    }
+    if (!await walk(value.directory))
+        return "modified";
+    for (const file of value.files) {
+        const bytes = await tree.read(join(value.directory, file.path));
+        if (!bytes?.equals(file.bytes))
+            return "modified";
+    }
+    return "installed";
+}
+async function onPath(command, env) {
+    for (const entry of (env.PATH ?? "").split(delimiter)) {
+        if (!isAbsolute(entry))
+            continue;
+        try {
+            if (await realpath(join(entry, "caotang")) === command && ((await stat(command)).mode & 0o100) !== 0) {
+                await access(command, constants.X_OK);
+                return true;
+            }
+        }
+        catch { }
+    }
+    return false;
+}
+// The fixed 1.1.0 baseline is admitted only after its complete public runtime
+// inventory verifies. Never infer provenance from a version or receipt.
+async function reviewedV110Bundle(tree, value) {
+    const pin = REVIEWED_MANAGED_BUNDLE_1_1_0, directory = join(tree.home, ".caotang", "cli", "releases", pin.sha);
+    const children = new Map([["", new Set()]]);
+    for (const file of pin.files) {
+        const parts = file.path.split("/");
+        let parent = "";
+        for (const [index, part] of parts.entries()) {
+            children.get(parent).add(part);
+            if (index < parts.length - 1) {
+                parent = parent ? `${parent}/${part}` : part;
+                if (!children.has(parent))
+                    children.set(parent, new Set());
+            }
+        }
+    }
+    const verifyInventory = async () => {
+        for (const [path, expected] of children)
+            if ((await tree.list(join(directory, path)))?.join(",") !== [...expected].sort().join(","))
+                throw conflict();
+    };
+    await verifyInventory();
+    const files = [], digest = createHash("sha256");
+    for (const file of pin.files) {
+        const bytes = await tree.read(join(directory, file.path), file.bytes, file.mode);
+        if (!bytes || bytes.length !== file.bytes || hash(bytes) !== file.sha256)
+            throw conflict();
+        files.push({ path: file.path, bytes, mode: file.mode });
+        digest.update(`${file.path}\0${file.mode}\0${bytes.length}\0`).update(bytes);
+    }
+    if (digest.digest("hex") !== pin.sha)
+        throw conflict();
+    await verifyInventory();
+    const manifest = JSON.parse(files.find(file => file.path === "skills/manifest.json").bytes.toString("utf8"));
+    if (!completeSkillInventory(manifest.skills.map(item => item.name)))
+        throw conflict();
+    const assets = manifest.skills.map(item => { const bytes = files.find(file => file.path === `skills/${item.name}/SKILL.md`).bytes; return { ...item, content: bytes.toString("utf8"), sha256: hash(bytes) }; });
+    return { bundle: { files, sha: pin.sha, version: pin.version, directory, command: value.command, shim: managedShim(directory) }, assets };
+}
+// Keep the reviewed 1.0.0 six-skill baseline unchanged. A directory digest alone
+// cannot authorize replacing somebody's same-name skill.
+async function legacyBundles(ctx, tree, value) {
+    if (!["1.0.1", "1.1.0"].includes(value.version) || ctx.agentName === undefined)
+        return [];
+    const releases = join(tree.home, ".caotang", "cli", "releases"), entries = await tree.list(releases) ?? [];
+    if (entries.length > 128)
+        throw unsafe();
+    const found = [];
+    const runtime = Buffer.from(JSON.stringify({ name: "@yijiancaotang/cli", version: "1.0.0", private: true, type: "module", engines: { node: ">=20" }, bin: { caotang: "bin/caotang.cjs" } }));
+    const manifest = Buffer.from(JSON.stringify({ formatVersion: 1, skills: LEGACY_MANAGED_SKILLS.map(({ name, description }) => ({ name, description })) }));
+    for (const sha of entries) {
+        if (!/^[a-f0-9]{64}$/.test(sha) || sha === value.sha)
+            continue;
+        const directory = join(releases, sha), packageBytes = await tree.read(join(directory, "package.json"), 32768, 0o600);
+        if (!packageBytes?.equals(runtime))
+            continue;
+        const root = await tree.list(directory), bin = await tree.list(join(directory, "bin")), dist = await tree.list(join(directory, "dist"));
+        const skills = await tree.list(join(directory, "skills")), generated = await tree.list(join(directory, "dist/generated"));
+        if (root?.join(",") !== "bin,dist,package.json,skills" || bin?.join(",") !== "caotang.cjs" || generated?.join(",") !== "knowledge-growth.js"
+            || !dist || dist.length > 64 || !dist.includes("cli.js") || !dist.includes("generated") || dist.some(name => name !== "generated" && !/^[a-z][a-z0-9-]*\.js$/.test(name))
+            || skills?.join(",") !== [...LEGACY_MANAGED_SKILLS.map(item => item.name), "manifest.json"].sort().join(","))
+            throw conflict();
+        if (!(await tree.read(join(directory, "skills/manifest.json"), 16384, 0o600))?.equals(manifest))
+            throw conflict();
+        const files = [{ path: "package.json", bytes: runtime, mode: 0o600 }, { path: "skills/manifest.json", bytes: manifest, mode: 0o600 }];
+        const assets = [];
+        for (const item of LEGACY_MANAGED_SKILLS) {
+            if ((await tree.list(join(directory, "skills", item.name)))?.join(",") !== "SKILL.md")
+                throw conflict();
+            const bytes = await tree.read(join(directory, "skills", item.name, "SKILL.md"), 65536, 0o600);
+            if (!bytes || hash(bytes) !== item.sha256)
+                throw conflict();
+            assets.push({ ...item, content: bytes.toString("utf8") });
+            files.push({ path: `skills/${item.name}/SKILL.md`, bytes, mode: 0o600 });
+        }
+        for (const path of ["bin/caotang.cjs", ...dist.filter(name => name !== "generated").map(name => `dist/${name}`), "dist/generated/knowledge-growth.js"]) {
+            const mode = path === "bin/caotang.cjs" ? 0o700 : 0o600, bytes = await tree.read(join(directory, path), 1048576, mode);
+            if (!bytes?.length)
+                throw conflict();
+            files.push({ path, bytes, mode });
+        }
+        files.sort((a, b) => a.path.localeCompare(b.path));
+        if (files.reduce((total, file) => total + file.bytes.length, 0) > 5242880)
+            throw conflict();
+        const digest = createHash("sha256");
+        for (const file of files)
+            digest.update(`${file.path}\0${file.mode}\0${file.bytes.length}\0`).update(file.bytes);
+        if (digest.digest("hex") !== sha)
+            throw conflict();
+        found.push({ bundle: { files, sha, version: "1.0.0", directory, command: value.command, shim: managedShim(directory) }, assets });
+    }
+    if (value.version === "1.1.0" && value.sha !== REVIEWED_MANAGED_BUNDLE_1_1_0.sha && entries.includes(REVIEWED_MANAGED_BUNDLE_1_1_0.sha))
+        found.push(await reviewedV110Bundle(tree, value));
+    return found;
+}
+async function installPlan(ctx, tree, value) {
+    const missing = [], modified = [];
+    const newlyInstalledPlatforms = [], upgradedPlatforms = [], replacements = [];
+    for (const target of ctx.targets) {
+        let absent = 0;
+        for (const raw of ctx.assets) {
+            const asset = bindSkillAgent(raw, ctx.agentName), dir = join(target.skillDirectory, asset.name), entries = await tree.list(dir);
+            if (entries === null || entries.length === 0) {
+                missing.push({ target, asset });
+                absent++;
+                continue;
+            }
+            if (entries.length !== 1 || entries[0] !== "SKILL.md")
+                throw skillConflict();
+            const bytes = await tree.read(join(dir, "SKILL.md"), 65536);
+            if (!bytes)
+                throw skillConflict();
+            if (!bytes.equals(Buffer.from(asset.content)))
+                modified.push({ target, asset, bytes });
+        }
+        if (absent === ctx.assets.length)
+            newlyInstalledPlatforms.push(target.id);
+    }
+    const command = await tree.read(value.command);
+    if (command && ((await lstat(value.command)).mode & 0o100) === 0)
+        throw unsafe();
+    const legacy = modified.length || command && !command.equals(value.shim) ? await legacyBundles(ctx, tree, value) : [];
+    for (const item of modified) {
+        const known = legacy.some(source => source.assets.some(asset => asset.name === item.asset.name && Buffer.from(bindSkillAgent(asset, ctx.agentName).content).equals(item.bytes)));
+        if (!known)
+            throw skillConflict();
+        const path = join(item.target.skillDirectory, item.asset.name, "SKILL.md");
+        if (!(await tree.read(path, 65536, 0o600))?.equals(item.bytes))
+            throw unsafe();
+        replacements.push({ path, before: item.bytes, after: Buffer.from(item.asset.content), mode: 0o600, label: `${item.target.id}:${item.asset.name}` });
+        if (!upgradedPlatforms.includes(item.target.id))
+            upgradedPlatforms.push(item.target.id);
+    }
+    if (command && !command.equals(value.shim)) {
+        if (!legacy.some(source => source.bundle.shim.equals(command)))
+            throw conflict();
+        if (!(await tree.read(value.command, 1048576, 0o700))?.equals(command))
+            throw unsafe();
+        // Always switch the shared stable command after every selected skill succeeds.
+        replacements.push({ path: value.command, before: command, after: value.shim, mode: 0o700, label: "command" });
+    }
+    return { missing, replacements, newlyInstalledPlatforms, upgradedPlatforms };
+}
+export async function installLocal(ctx) {
+    const tree = new OwnedTree(ctx.homeDir), changed = [];
+    let changesPossible = false;
+    try {
+        validateTargets(ctx, tree);
+        if (!ctx.targets.length && !ctx.agentName)
+            throw new CliError("no_supported_platform", "未识别到支持的AI客户端。", "核对Claude Code、Codex、OpenClaw，或macOS上的Kimi Code、Kimi工作模式、WorkBuddy后再接入；不会自动安装客户端。");
+        const value = await bundle(ctx, tree);
+        await tree.directory(tree.home, false, async () => { });
+        await installPlan(ctx, tree, value);
+        if (await bundleState(tree, value) === "modified")
+            throw conflict();
+        const lockPath = join(tree.home, ".caotang", ".setup.lock");
+        changesPossible = true;
+        const release = await tree.directory(dirname(lockPath), true, async (directories) => acquireLocalLock(lockPath, directories.at(-1), {
+            unsafe,
+            busy: () => new CliError("installation_busy", "另一项本地安装正在进行或锁状态无法确认。", "等待本地安装结束；状态不明时保留锁，由你人工核查，不自动删除。"),
+        }));
+        if (!release)
+            throw unsafe();
+        try {
+            const state = await bundleState(tree, value);
+            if (state === "modified")
+                throw conflict();
+            const originalPlan = await installPlan(ctx, tree, value);
+            if (state === "missing") {
+                const created = await tree.createDirectory(value.directory);
+                if (!created)
+                    throw conflict();
+                changed.push("bundle");
+                for (const file of value.files)
+                    await tree.writeNew(join(value.directory, file.path), file.bytes, file.mode);
+                if (await bundleState(tree, value) !== "installed")
+                    throw conflict();
+            }
+            for (const { target, asset } of originalPlan.missing) {
+                const dir = join(target.skillDirectory, asset.name), created = await tree.createDirectory(dir);
+                if (!created && (await tree.list(dir))?.length !== 0)
+                    throw skillConflict();
+                changed.push(`${target.id}:${asset.name}`);
+                await tree.writeNew(join(dir, "SKILL.md"), Buffer.from(asset.content), 0o600);
+                if (await skillState(tree, target, asset) !== "installed")
+                    throw skillConflict();
+            }
+            const plan = await installPlan(ctx, tree, value), attempted = [];
+            let recoveryJournal;
+            if (plan.replacements.length) {
+                const snapshot = Buffer.from(JSON.stringify({ formatVersion: 1, targetBundleSha: value.sha, files: plan.replacements.map(entry => ({ path: relative(tree.home, entry.path), mode: entry.mode, before: entry.before.toString("base64"), after: entry.after.toString("base64") })) }));
+                if (snapshot.length > 1048576)
+                    throw unsafe();
+                recoveryJournal = join(tree.home, ".caotang", "cli", "upgrades", hash(snapshot) + ".json");
+                await tree.writeNew(recoveryJournal, snapshot, 0o600);
+                if (!(await tree.read(recoveryJournal, 1048576, 0o600))?.equals(snapshot))
+                    throw unsafe();
+                await tree.directory(dirname(recoveryJournal), false, async (directories) => {
+                    for (const directory of directories)
+                        await directory.handle.sync();
+                });
+            }
+            try {
+                for (const entry of plan.replacements) {
+                    attempted.push(entry);
+                    changed.push(entry.label);
+                    await tree.replaceManaged(entry);
+                }
+                if (await tree.writeNew(value.command, value.shim, 0o700))
+                    changed.push("command");
+                if (!(await tree.read(value.command))?.equals(value.shim) || ((await lstat(value.command)).mode & 0o100) === 0 || await bundleState(tree, value) !== "installed")
+                    throw conflict();
+                for (const target of ctx.targets)
+                    for (const asset of ctx.assets)
+                        if (await skillState(tree, target, bindSkillAgent(asset, ctx.agentName)) !== "installed")
+                            throw skillConflict();
+            }
+            catch (error) {
+                if (!recoveryJournal)
+                    throw error;
+                let restored = true;
+                for (const entry of attempted.reverse()) {
+                    try {
+                        const current = await tree.read(entry.path, 1048576, entry.mode);
+                        if (!current?.equals(entry.before)) {
+                            if (!entry.identity) {
+                                restored = false;
+                                continue;
+                            }
+                            await tree.replaceManaged(entry, true);
+                        }
+                        if (!(await tree.read(entry.path, 1048576, entry.mode))?.equals(entry.before)
+                            || entry.identity && !same(await lstat(entry.path), entry.identity))
+                            restored = false;
+                    }
+                    catch {
+                        restored = false;
+                    }
+                }
+                const recovery = { upgrade_status: restored ? "rolled_back" : "unknown", recovery_journal: recoveryJournal };
+                if (restored && error instanceof CliError && error.code === "installation_permission_denied") {
+                    Object.assign(error.details, recovery);
+                    throw error;
+                }
+                throw new CliError(restored ? "installation_upgrade_failed" : "installation_upgrade_unknown", restored ? "本地升级未完成，已核对并恢复本轮改动的原文件。" : "无法确认本地升级结果，部分受管文件可能尚未恢复。", "保留旧版本与恢复原件，请本人核对 recovery_journal；不要强制覆盖、删除、重新授权或重复业务写入。", 7, recovery);
+            }
+            return { changed, bundleSha: value.sha, bundleDirectory: value.directory, newlyInstalledPlatforms: originalPlan.newlyInstalledPlatforms, upgradedPlatforms: originalPlan.upgradedPlatforms };
+        }
+        finally {
+            release();
+        }
+    }
+    catch (error) {
+        const safe = error instanceof CliError ? error
+            : ["EPERM", "EACCES"].includes(String(asRecord(error)?.code)) ? permissionDenied(join(tree.home, ".caotang")) : unsafe();
+        throw new CliError(safe.code, safe.message, safe.nextAction, safe.exitCode, { ...safe.details, local_changes_possible: changesPossible, local_changes: changed });
+    }
+}
+export async function inspectLocalInstallation(ctx) {
+    const tree = new OwnedTree(ctx.homeDir);
+    validateTargets(ctx, tree);
+    const value = await bundle(ctx, tree), issues = [];
+    const issue = (code, message, next_action) => issues.push({ code, message, next_action });
+    let installed = false;
+    const current = await tree.read(value.command);
+    if (!current)
+        issue("command_not_installed", "稳定命令行尚未安装。", "运行 setup 完成本地安装。");
+    else if (!current.equals(value.shim) || await bundleState(tree, value) !== "installed" || ((await lstat(value.command)).mode & 0o100) === 0)
+        issue("command_modified", "已有命令行与当前候选不一致。", "保留现有文件并人工核对，不自动覆盖。");
+    else
+        installed = true;
+    const on_path = installed && await onPath(value.command, ctx.env);
+    if (!ctx.targets.some(target => target.detected))
+        issue("no_supported_platform", "尚未识别到支持的AI客户端。", "核对Claude Code、Codex、OpenClaw，或macOS上的Kimi Code、Kimi工作模式、WorkBuddy程序入口，再运行doctor。");
+    const platforms = [];
+    for (const target of ctx.targets) {
+        const skills = [];
+        for (const asset of ctx.assets) {
+            let status;
+            try {
+                status = await skillState(tree, target, bindSkillAgent(asset, ctx.agentName));
+            }
+            catch {
+                status = "unsafe";
+            }
+            skills.push({ name: asset.name, status });
+            if (target.detected && status !== "installed")
+                issue(status === "missing" ? "skill_missing" : status === "modified" ? "skill_modified" : "skill_unsafe", "本地技能缺失、已修改或不满足安全要求。", status === "missing" ? `运行 setup --platform ${target.id} 安装缺失技能。` : "保留现有技能并人工核对，不自动覆盖或修复。");
+        }
+        platforms.push({ id: target.id, detected: target.detected, skill_directory: target.skillDirectory, skills });
+    }
+    return { command: { installed, on_path, version: value.version, ...(installed ? { executable_path: value.command } : {}) }, platforms, issues };
+}
+// Read-only evidence for known platform paths, never an installation/overwrite
+// permit. Only the current name's exact public templates count as its skills.
+export async function inspectManagedOrigins(ctx) {
+    if (ctx.agentName === undefined)
+        throw new CliError("agent_name_required", "请用你自己的名字再运行 setup --agent <你的名字>。", "之后每条命令都带同一个 --agent <你的名字>；不会借用其他 AI 的连接。");
+    const tree = new OwnedTree(ctx.homeDir);
+    validateTargets(ctx, tree);
+    const value = await bundle(ctx, tree), assets = ctx.assets.map(asset => bindSkillAgent(asset, ctx.agentName));
+    let legacy = [];
+    try {
+        legacy = await legacyBundles(ctx, tree, value);
+    }
+    catch { /* Unverified old files provide no evidence; never promote them. */ }
+    const platforms = [];
+    for (const target of ctx.targets) {
+        const skills = [];
+        for (const asset of assets) {
+            let status;
+            try {
+                status = await skillState(tree, target, asset);
+                if (status === "modified") {
+                    const dir = join(target.skillDirectory, asset.name), entries = await tree.list(dir);
+                    if (entries?.join(",") === "SKILL.md") {
+                        const bytes = await tree.read(join(dir, "SKILL.md"), 65536, 0o600);
+                        if (bytes && legacy.some(source => source.assets.some(old => old.name === asset.name && Buffer.from(bindSkillAgent(old, ctx.agentName).content).equals(bytes))))
+                            status = "outdated";
+                    }
+                }
+            }
+            catch {
+                status = "unsafe";
+            }
+            skills.push({ name: asset.name, status });
+        }
+        platforms.push({ id: target.id, skill_directory: target.skillDirectory, ownKnownCount: skills.filter(skill => skill.status === "installed" || skill.status === "outdated").length, skills });
+    }
+    let command = { legacyManaged: false, on_path: false };
+    try {
+        const bytes = await tree.read(value.command, 1048576, 0o700), old = legacy.find(source => bytes?.equals(source.bundle.shim));
+        if (old)
+            command = { legacyManaged: true, on_path: await onPath(value.command, ctx.env), version: old.bundle.version, executable_path: value.command };
+    }
+    catch { /* An unsafe command must not be called a verified old command. */ }
+    return { platforms, command };
+}