@graychennpm/codebridge 0.0.0-stage → 0.1.0

package/node_modules/@codebridge/backends/dist/skill-control-plane.js

@@ -0,0 +1,832 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { JsonArrayStore, JsonMapStore } from "@codebridge/core";
+export const SKILL_AGENT_IDS = ["codex", "claude", "cursor", "opencode", "pi"];
+export class SkillControlPlaneError extends Error {
+    code;
+    status;
+    name = "SkillControlPlaneError";
+    constructor(code, message, status = 409) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+const TARGET_NAMES = {
+    codex: "Codex",
+    claude: "Claude Code",
+    cursor: "Cursor",
+    opencode: "OpenCode",
+    pi: "Pi",
+};
+const SOURCE_PRIORITY = {
+    shared: 4,
+    disabled: 3,
+    adopted: 2,
+    agent_native: 1,
+};
+export class SkillControlPlane {
+    homeDirectory;
+    sharedRoot;
+    disabledRoot;
+    targetRoots;
+    sources;
+    ownership;
+    assignments;
+    plans;
+    transactions;
+    constructor(options) {
+        this.homeDirectory = path.resolve(options.homeDirectory ?? os.homedir());
+        this.sharedRoot = path.resolve(options.sharedRoot ?? path.join(this.homeDirectory, ".agents", "skills"));
+        this.disabledRoot = path.resolve(options.disabledRoot ?? path.join(this.homeDirectory, ".agents", "skills-disabled"));
+        this.targetRoots = options.targetRoots ?? {
+            codex: path.join(this.homeDirectory, ".codex", "skills"),
+            claude: path.join(this.homeDirectory, ".claude", "skills"),
+            cursor: path.join(this.homeDirectory, ".cursor", "skills"),
+            opencode: path.join(this.homeDirectory, ".config", "opencode", "skills"),
+            pi: path.join(this.homeDirectory, ".pi", "agent", "skills"),
+        };
+        const stateDirectory = path.join(options.dataDir, "state", "skills");
+        const sourcesPath = path.join(stateDirectory, "sources.json");
+        migrateLegacyStateFile(path.join(options.dataDir, "skill-sources.json"), sourcesPath);
+        this.sources = new JsonArrayStore(sourcesPath);
+        this.ownership = new JsonMapStore(path.join(stateDirectory, "ownership.json"));
+        this.assignments = new JsonMapStore(path.join(stateDirectory, "assignments.json"));
+        this.plans = new JsonMapStore(path.join(stateDirectory, "plans.json"));
+        this.transactions = new JsonMapStore(path.join(stateDirectory, "transactions.json"));
+        this.recoverPendingTransactions();
+    }
+    scan() {
+        const discovered = new Map();
+        this.collectRoot(this.sharedRoot, "shared", discovered);
+        this.collectRoot(this.disabledRoot, "disabled", discovered);
+        for (const source of this.sources.read()) {
+            this.collectRoot(source, "adopted", discovered);
+        }
+        for (const agentId of SKILL_AGENT_IDS) {
+            this.collectRoot(this.targetRoots[agentId], "agent_native", discovered);
+        }
+        const grouped = new Map();
+        for (const skill of discovered.values()) {
+            const id = path.basename(skill.sourcePath);
+            grouped.set(id, [...(grouped.get(id) ?? []), skill]);
+        }
+        const skills = [...grouped.entries()]
+            .map(([id, candidates]) => this.toCatalogEntry(id, candidates))
+            .sort((left, right) => left.name.localeCompare(right.name));
+        const targets = SKILL_AGENT_IDS.map((agentId) => ({
+            agent_id: agentId,
+            display_name: TARGET_NAMES[agentId],
+            root_path: agentId === "claude" ? this.targetRoots[agentId] : this.sharedRoot,
+            delivery_mode: deliveryMode(agentId),
+        }));
+        const recoveryRequired = Object.values(this.transactions.read())
+            .filter((transaction) => transaction.status === "failed").length;
+        return {
+            skills,
+            targets,
+            summary: {
+                total: skills.length,
+                sources: new Set(skills.map((skill) => skill.source_kind)).size,
+                linked: skills.flatMap((skill) => skill.targets)
+                    .filter((target) => target.state === "linked" || target.state === "follows_global").length,
+                issues: skills.filter((skill) => !skill.can_apply).length
+                    + skills.flatMap((skill) => skill.targets)
+                        .filter((target) => target.state === "conflict" || target.state === "broken").length
+                    + recoveryRequired,
+                recovery_required: recoveryRequired,
+            },
+            scanned_at: new Date().toISOString(),
+        };
+    }
+    addSource(rawPath) {
+        if (!path.isAbsolute(rawPath)) {
+            throw new SkillControlPlaneError("skill_source_invalid", "Skill Source 必须使用绝对路径", 400);
+        }
+        let resolved;
+        try {
+            resolved = fs.realpathSync(rawPath);
+        }
+        catch {
+            throw new SkillControlPlaneError("skill_source_invalid", `Skill Source 不存在或不可访问: ${rawPath}`, 400);
+        }
+        if (!this.skillDirectories(resolved).length) {
+            throw new SkillControlPlaneError("skill_source_invalid", "所选目录自身或直接子目录中没有 SKILL.md", 400);
+        }
+        this.sources.update((current) => (current.includes(resolved) ? current : [...current, resolved]));
+        return this.scan();
+    }
+    previewAdopt(input) {
+        const skill = this.findSkill(input.skill_id);
+        this.assertPackageCanMutate(skill);
+        if (skill.ownership === "native_managed") {
+            throw new SkillControlPlaneError("skill_adopt_forbidden", `Skill 由 Agent 或系统原生管理，不能 Adopt: ${skill.id}`);
+        }
+        const alreadyShared = isPathInside(this.sharedRoot, skill.source_path)
+            || isPathInside(this.disabledRoot, skill.source_path);
+        const targetPath = alreadyShared ? skill.source_path : path.join(this.sharedRoot, skill.id);
+        const targetOccupied = !alreadyShared && pathExists(targetPath);
+        return this.createPlan({
+            actorId: input.actor_id,
+            kind: "adopt",
+            skill,
+            targetPath,
+            canApply: !targetOccupied,
+            detail: targetOccupied ? `共享目录已存在同名 Skill: ${targetPath}` : null,
+            request: {},
+            steps: alreadyShared
+                ? [{ action: "set_ownership", detail: "原地登记为 CodeBridge 受管 Skill" }]
+                : [
+                    { action: "move", source_path: skill.source_path, target_path: targetPath, detail: "移动到共享启用目录" },
+                    { action: "create_link", source_path: targetPath, target_path: skill.source_path, detail: "在原位置创建兼容软链" },
+                    { action: "set_ownership", detail: "登记 ownership 与 provenance" },
+                ],
+        });
+    }
+    previewAssignment(input) {
+        const skill = this.findSkill(input.skill_id);
+        this.assertPackageCanMutate(skill);
+        if (input.agent_id !== "claude") {
+            throw new SkillControlPlaneError("skill_target_unknown", `${TARGET_NAMES[input.agent_id] ?? input.agent_id} 直接读取共享目录，不支持独立分发开关`, 400);
+        }
+        const target = skill.targets.find((candidate) => candidate.agent_id === input.agent_id);
+        const assignment = this.assignments.read()[assignmentKey(skill.id, input.agent_id)];
+        if (!input.enabled && target.state !== "absent" && !this.ownsProjectedLink(skill, assignment)) {
+            throw new SkillControlPlaneError("skill_unlink_forbidden", `目标不是 CodeBridge 拥有的软链，禁止移除: ${target.target_path}`);
+        }
+        if (skill.ownership !== "codebridge_managed") {
+            throw new SkillControlPlaneError("skill_adopt_forbidden", `Skill 必须先 Adopt 才能分发: ${skill.id}`);
+        }
+        const canApply = input.enabled
+            ? target.state === "absent" || target.state === "linked"
+            : target.state === "absent" || target.state === "linked";
+        const steps = [];
+        if (input.enabled && skill.global_state === "enabled" && target.state === "absent") {
+            steps.push({ action: "create_link", source_path: skill.source_path, target_path: target.target_path, detail: "创建 Claude 兼容软链" });
+        }
+        if (!input.enabled && target.state === "linked") {
+            steps.push({ action: "remove_link", source_path: skill.source_path, target_path: target.target_path, detail: "移除 CodeBridge-owned Claude 软链" });
+        }
+        steps.push({ action: "set_assignment", detail: `保存期望状态: ${input.enabled ? "linked" : "absent"}` });
+        return this.createPlan({
+            actorId: input.actor_id,
+            kind: "assignment",
+            skill,
+            targetPath: target.target_path,
+            canApply,
+            detail: canApply ? null : target.detail,
+            request: { enabled: input.enabled, agent_id: input.agent_id },
+            steps,
+        });
+    }
+    previewGlobalState(input) {
+        const skill = this.findSkill(input.skill_id);
+        this.assertPackageCanMutate(skill);
+        if (skill.ownership !== "codebridge_managed") {
+            throw new SkillControlPlaneError("skill_adopt_forbidden", `Skill 必须先 Adopt 才能全局启停: ${skill.id}`);
+        }
+        const targetPath = path.join(input.enabled ? this.sharedRoot : this.disabledRoot, skill.id);
+        const alreadyDesired = input.enabled
+            ? skill.global_state === "enabled"
+            : skill.global_state === "disabled";
+        const targetOccupied = !alreadyDesired && pathExists(targetPath);
+        const steps = [];
+        if (!alreadyDesired) {
+            if (!input.enabled) {
+                steps.push({ action: "remove_link", detail: "暂停所有 CodeBridge-owned 适配软链" });
+            }
+            steps.push({ action: "move", source_path: skill.source_path, target_path: targetPath, detail: input.enabled ? "移回共享启用目录" : "移入可恢复停用目录" });
+            if (input.enabled) {
+                steps.push({ action: "create_link", detail: "恢复期望为 linked 的适配软链" });
+            }
+        }
+        return this.createPlan({
+            actorId: input.actor_id,
+            kind: "global_state",
+            skill,
+            targetPath,
+            canApply: !targetOccupied,
+            detail: targetOccupied ? `目标目录已存在: ${targetPath}` : null,
+            request: { enabled: input.enabled },
+            steps,
+        });
+    }
+    previewUnmanage(input) {
+        const skill = this.findSkill(input.skill_id);
+        this.assertPackageCanMutate(skill);
+        if (skill.ownership !== "codebridge_managed") {
+            throw new SkillControlPlaneError("skill_adopt_forbidden", `Skill 当前未由 CodeBridge 管理: ${skill.id}`);
+        }
+        return this.createPlan({
+            actorId: input.actor_id,
+            kind: "unmanage",
+            skill,
+            targetPath: skill.source_path,
+            canApply: true,
+            detail: null,
+            request: {},
+            steps: [{ action: "set_ownership", detail: "取消纳管但保留内容和现有软链" }],
+        });
+    }
+    applyPlan(input) {
+        const plan = this.plans.read()[input.plan_id];
+        if (!plan) {
+            throw new SkillControlPlaneError("skill_plan_not_found", `Skill plan 不存在: ${input.plan_id}`, 404);
+        }
+        if (plan.actor_id !== input.actor_id) {
+            throw new SkillControlPlaneError("skill_plan_actor_mismatch", "Skill plan 不属于当前 actor", 409);
+        }
+        if (Date.parse(plan.expires_at) <= Date.now()) {
+            throw new SkillControlPlaneError("skill_plan_expired", "Skill plan 已过期，请重新预览", 409);
+        }
+        if (!plan.can_apply) {
+            throw new SkillControlPlaneError("skill_target_conflict", plan.detail ?? "Skill plan 存在冲突", 409);
+        }
+        const skill = this.findSkill(plan.skill_id);
+        if (skill.package_revision !== plan.package_revision) {
+            throw new SkillControlPlaneError("skill_revision_mismatch", "Skill Package 在预览后发生变化", 409);
+        }
+        if (fingerprintPath(plan.source_path) !== plan.source_fingerprint) {
+            throw new SkillControlPlaneError("skill_revision_mismatch", "Skill Source 在预览后发生变化", 409);
+        }
+        if (fingerprintPath(plan.target_path) !== plan.target_fingerprint) {
+            throw new SkillControlPlaneError("skill_target_conflict", "Skill Target 在预览后发生变化", 409);
+        }
+        const transactionId = crypto.randomUUID();
+        const now = new Date().toISOString();
+        this.transactions.update((current) => ({
+            ...current,
+            [transactionId]: {
+                transaction_id: transactionId,
+                plan_id: plan.plan_id,
+                kind: plan.kind,
+                status: "pending",
+                stage: "planned",
+                created_at: now,
+                updated_at: now,
+            },
+        }));
+        try {
+            this.executePlan(plan, transactionId);
+            const snapshot = this.scan();
+            this.updateTransaction(transactionId, { status: "completed", stage: "committed" });
+            this.plans.update((current) => {
+                const next = { ...current };
+                delete next[plan.plan_id];
+                return next;
+            });
+            return { plan_id: plan.plan_id, transaction_id: transactionId, snapshot };
+        }
+        catch (error) {
+            this.updateTransaction(transactionId, {
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    createPlan(input) {
+        const plan = {
+            plan_id: crypto.randomUUID(),
+            actor_id: input.actorId,
+            kind: input.kind,
+            skill_id: input.skill.id,
+            package_revision: input.skill.package_revision,
+            source_path: input.skill.source_path,
+            target_path: input.targetPath,
+            source_fingerprint: fingerprintPath(input.skill.source_path),
+            target_fingerprint: fingerprintPath(input.targetPath),
+            expires_at: new Date(Date.now() + 5 * 60_000).toISOString(),
+            steps: input.steps,
+            can_apply: input.canApply,
+            detail: input.detail,
+            request: input.request,
+        };
+        this.plans.update((current) => ({ ...current, [plan.plan_id]: plan }));
+        return plan;
+    }
+    assertPackageCanMutate(skill) {
+        if (skill.global_state === "split_brain") {
+            throw new SkillControlPlaneError("skill_split_brain", `Skill 同时存在于启用和停用目录: ${skill.id}`);
+        }
+        if (skill.global_state === "invalid") {
+            const code = skill.name === skill.id ? "skill_package_invalid" : "skill_identity_mismatch";
+            throw new SkillControlPlaneError(code, `Skill Package 身份或内容无效: ${skill.id}`, 422);
+        }
+        if (!skill.can_apply) {
+            throw new SkillControlPlaneError("skill_target_conflict", `Skill 存在同名不同内容的 Source: ${skill.id}`);
+        }
+    }
+    executePlan(plan, transactionId) {
+        if (plan.kind === "adopt") {
+            this.executeAdopt(plan, transactionId);
+            return;
+        }
+        if (plan.kind === "assignment") {
+            this.executeAssignment(plan, transactionId);
+            return;
+        }
+        if (plan.kind === "global_state") {
+            this.executeGlobalState(plan, transactionId);
+            return;
+        }
+        this.ownership.update((current) => {
+            const next = { ...current };
+            delete next[plan.skill_id];
+            return next;
+        });
+        this.assignments.update((current) => {
+            const next = { ...current };
+            for (const key of Object.keys(next)) {
+                if (next[key]?.skill_id === plan.skill_id)
+                    delete next[key];
+            }
+            return next;
+        });
+        this.updateTransaction(transactionId, { stage: "verified" });
+    }
+    recoverPendingTransactions() {
+        const transactions = this.transactions.read();
+        const plans = this.plans.read();
+        for (const transaction of Object.values(transactions)) {
+            if (transaction.status !== "pending")
+                continue;
+            const plan = plans[transaction.plan_id];
+            if (!plan) {
+                this.updateTransaction(transaction.transaction_id, {
+                    status: "failed",
+                    error: "持久事务缺少原始 plan，必须人工恢复",
+                });
+                continue;
+            }
+            try {
+                this.executePlan(plan, transaction.transaction_id);
+                this.scan();
+                this.updateTransaction(transaction.transaction_id, {
+                    status: "completed",
+                    stage: "committed",
+                });
+                this.plans.update((current) => {
+                    const next = { ...current };
+                    delete next[plan.plan_id];
+                    return next;
+                });
+            }
+            catch (error) {
+                this.updateTransaction(transaction.transaction_id, {
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    executeAdopt(plan, transactionId) {
+        let managedPath = plan.source_path;
+        if (plan.source_path !== plan.target_path) {
+            fs.mkdirSync(path.dirname(plan.target_path), { recursive: true });
+            if (pathExists(plan.source_path) && !pathExistsLstat(plan.target_path)) {
+                fs.renameSync(plan.source_path, plan.target_path);
+                this.updateTransaction(transactionId, { stage: "source_switched" });
+            }
+            else if (!pathExistsLstat(plan.target_path)) {
+                throw new SkillControlPlaneError("skill_transaction_recovery_required", "Adopt Source 和 Target 都不存在");
+            }
+            if (!pathExistsLstat(plan.source_path)) {
+                fs.symlinkSync(plan.target_path, plan.source_path, "dir");
+            }
+            else if (!this.isManagedLink(plan.source_path, plan.target_path)) {
+                throw new SkillControlPlaneError("skill_transaction_recovery_required", "Adopt 原位置已被其他内容占用");
+            }
+            managedPath = plan.target_path;
+            this.updateTransaction(transactionId, { stage: "links_reconciled" });
+        }
+        const now = new Date().toISOString();
+        this.ownership.update((current) => ({
+            ...current,
+            [plan.skill_id]: {
+                ownership: "codebridge_managed",
+                source_path: managedPath,
+                adopted_at: now,
+                last_observed_revision: plan.package_revision,
+            },
+        }));
+        this.updateTransaction(transactionId, { stage: "verified" });
+    }
+    executeAssignment(plan, transactionId) {
+        const enabled = plan.request.enabled === true;
+        const agentId = plan.request.agent_id;
+        if (agentId !== "claude") {
+            throw new SkillControlPlaneError("skill_target_unknown", "只有 symlink_projection Agent 可以保存 Assignment", 400);
+        }
+        const skill = this.findSkill(plan.skill_id);
+        const key = assignmentKey(skill.id, agentId);
+        const existing = this.assignments.read()[key];
+        if (enabled && skill.global_state === "enabled" && !pathExistsLstat(plan.target_path)) {
+            fs.mkdirSync(path.dirname(plan.target_path), { recursive: true });
+            fs.symlinkSync(skill.source_path, plan.target_path, "dir");
+        }
+        else if (enabled && skill.global_state === "enabled" && !this.isManagedLink(plan.target_path, skill.source_path)) {
+            throw new SkillControlPlaneError("skill_target_conflict", `Claude Target 已被其他内容占用: ${plan.target_path}`);
+        }
+        if (!enabled && pathExistsLstat(plan.target_path)) {
+            if (!this.ownsProjectedLink(skill, existing)) {
+                throw new SkillControlPlaneError("skill_unlink_forbidden", `禁止移除非受管软链: ${plan.target_path}`);
+            }
+            fs.unlinkSync(plan.target_path);
+        }
+        const now = new Date().toISOString();
+        this.assignments.update((current) => ({
+            ...current,
+            [key]: {
+                skill_id: skill.id,
+                agent_id: agentId,
+                desired_state: enabled ? "linked" : "absent",
+                target_path: plan.target_path,
+                created_link_target: enabled ? skill.source_path : existing?.created_link_target,
+                last_applied_package_revision: skill.package_revision,
+                created_at: existing?.created_at ?? now,
+                updated_at: now,
+            },
+        }));
+        this.updateTransaction(transactionId, { stage: "links_reconciled" });
+    }
+    executeGlobalState(plan, transactionId) {
+        const enabled = plan.request.enabled === true;
+        const skill = this.findSkill(plan.skill_id);
+        const assignment = this.assignments.read()[assignmentKey(skill.id, "claude")];
+        const claudeTarget = path.join(this.targetRoots.claude, skill.id);
+        if (!enabled && assignment?.desired_state === "linked" && pathExistsLstat(claudeTarget)) {
+            if (!this.ownsProjectedLink(skill, assignment)) {
+                throw new SkillControlPlaneError("skill_unlink_forbidden", `Claude Target 已脱离 CodeBridge 管理: ${claudeTarget}`);
+            }
+            fs.unlinkSync(claudeTarget);
+            this.updateTransaction(transactionId, { stage: "links_reconciled" });
+        }
+        if (plan.source_path !== plan.target_path) {
+            fs.mkdirSync(path.dirname(plan.target_path), { recursive: true });
+            if (pathExists(plan.source_path) && !pathExistsLstat(plan.target_path)) {
+                fs.renameSync(plan.source_path, plan.target_path);
+                this.updateTransaction(transactionId, { stage: "source_switched" });
+            }
+            else if (!pathExists(plan.target_path)) {
+                throw new SkillControlPlaneError("skill_transaction_recovery_required", "全局状态 Source 和 Target 都不存在");
+            }
+        }
+        if (enabled && assignment?.desired_state === "linked") {
+            if (pathExistsLstat(claudeTarget)) {
+                throw new SkillControlPlaneError("skill_target_conflict", `Claude Target 已被占用: ${claudeTarget}`);
+            }
+            fs.mkdirSync(path.dirname(claudeTarget), { recursive: true });
+            fs.symlinkSync(plan.target_path, claudeTarget, "dir");
+            this.updateTransaction(transactionId, { stage: "links_reconciled" });
+        }
+        const ownership = this.ownership.read()[skill.id];
+        if (ownership) {
+            this.ownership.update((current) => ({
+                ...current,
+                [skill.id]: { ...ownership, source_path: plan.target_path },
+            }));
+        }
+        this.updateTransaction(transactionId, { stage: "verified" });
+    }
+    ownsProjectedLink(skill, assignment) {
+        if (!assignment || assignment.desired_state !== "linked")
+            return false;
+        return assignment.target_path === path.join(this.targetRoots[assignment.agent_id], skill.id)
+            && assignment.created_link_target === skill.source_path
+            && this.isManagedLink(assignment.target_path, skill.source_path);
+    }
+    updateTransaction(transactionId, patch) {
+        this.transactions.update((current) => {
+            const transaction = current[transactionId];
+            if (!transaction)
+                return current;
+            return {
+                ...current,
+                [transactionId]: {
+                    ...transaction,
+                    ...patch,
+                    updated_at: new Date().toISOString(),
+                },
+            };
+        });
+    }
+    findSkill(id) {
+        const skill = this.scan().skills.find((candidate) => candidate.id === id);
+        if (!skill) {
+            throw new SkillControlPlaneError("skill_not_found", `Skill 不存在: ${id}`, 404);
+        }
+        return skill;
+    }
+    collectRoot(root, sourceKind, discovered) {
+        for (const sourcePath of this.skillDirectories(root)) {
+            const current = discovered.get(sourcePath);
+            if (!current || SOURCE_PRIORITY[sourceKind] > SOURCE_PRIORITY[current.sourceKind]) {
+                discovered.set(sourcePath, { sourcePath, sourceKind });
+            }
+        }
+    }
+    skillDirectories(root) {
+        let stat;
+        try {
+            stat = fs.statSync(root);
+        }
+        catch {
+            return [];
+        }
+        if (!stat.isDirectory())
+            return [];
+        const direct = this.resolveSkillDirectory(root);
+        if (direct)
+            return [direct];
+        const result = [];
+        for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            const resolved = this.resolveSkillDirectory(path.join(root, entry.name));
+            if (resolved && !result.includes(resolved))
+                result.push(resolved);
+        }
+        return result;
+    }
+    resolveSkillDirectory(candidate) {
+        try {
+            const resolved = fs.realpathSync(candidate);
+            if (!fs.statSync(resolved).isDirectory())
+                return null;
+            if (!fs.statSync(path.join(resolved, "SKILL.md")).isFile())
+                return null;
+            return resolved;
+        }
+        catch {
+            return null;
+        }
+    }
+    toCatalogEntry(id, candidates) {
+        const sorted = [...candidates].sort((left, right) => SOURCE_PRIORITY[right.sourceKind] - SOURCE_PRIORITY[left.sourceKind]);
+        const discovered = sorted[0];
+        const skillFile = path.join(discovered.sourcePath, "SKILL.md");
+        const content = fs.readFileSync(skillFile, "utf8");
+        const metadata = parseSkillMetadata(content, id);
+        const packageFingerprint = fingerprintSkillPackage(discovered.sourcePath);
+        const candidateRevisions = new Set(candidates.map((candidate) => fingerprintSkillPackage(candidate.sourcePath).revision));
+        const hasSourceConflict = candidates.length > 1
+            && candidateRevisions.size > 1
+            && !(candidates.length === 2
+                && candidates.some((candidate) => candidate.sourceKind === "shared")
+                && candidates.some((candidate) => candidate.sourceKind === "disabled"));
+        const hasActive = candidates.some((candidate) => candidate.sourceKind === "shared");
+        const hasDisabled = candidates.some((candidate) => candidate.sourceKind === "disabled");
+        const identityValid = metadata.name === id;
+        const globalState = !identityValid || !packageFingerprint.valid
+            ? "invalid"
+            : hasActive && hasDisabled
+                ? "split_brain"
+                : hasActive
+                    ? "enabled"
+                    : hasDisabled
+                        ? "disabled"
+                        : "external";
+        const revision = packageFingerprint.revision;
+        const ownershipRecord = this.ownership.read()[id];
+        const ownership = ownershipRecord?.last_observed_revision === revision
+            || ownershipRecord?.ownership === "codebridge_managed"
+            ? ownershipRecord.ownership
+            : "external_observed";
+        return {
+            id,
+            name: metadata.name,
+            description: metadata.description,
+            source_path: discovered.sourcePath,
+            source_kind: discovered.sourceKind,
+            package_revision: revision,
+            revision,
+            global_state: globalState,
+            ownership,
+            can_apply: globalState !== "invalid" && globalState !== "split_brain" && !hasSourceConflict,
+            tags: metadata.tags,
+            updated_at: fs.statSync(skillFile).mtime.toISOString(),
+            targets: SKILL_AGENT_IDS.map((agentId) => (agentId === "claude"
+                ? this.inspectTarget(discovered.sourcePath, agentId)
+                : {
+                    agent_id: agentId,
+                    delivery_mode: "shared_native",
+                    target_path: path.join(this.sharedRoot, id),
+                    state: "follows_global",
+                    mutable: false,
+                    detail: globalState === "enabled"
+                        ? "Agent 直接读取共享启用目录"
+                        : "Agent 跟随 Skill 全局状态",
+                })),
+        };
+    }
+    inspectTarget(sourcePath, agentId) {
+        const targetPath = path.join(this.targetRoots[agentId], path.basename(sourcePath));
+        let stat;
+        try {
+            stat = fs.lstatSync(targetPath);
+        }
+        catch {
+            return {
+                agent_id: agentId,
+                delivery_mode: deliveryMode(agentId),
+                target_path: targetPath,
+                state: "absent",
+                mutable: agentId === "claude",
+                detail: null,
+            };
+        }
+        let resolvedTarget = null;
+        try {
+            resolvedTarget = fs.realpathSync(targetPath);
+        }
+        catch {
+            resolvedTarget = null;
+        }
+        if (stat.isSymbolicLink()) {
+            if (!resolvedTarget) {
+                return {
+                    agent_id: agentId,
+                    delivery_mode: deliveryMode(agentId),
+                    target_path: targetPath,
+                    state: "broken",
+                    mutable: agentId === "claude",
+                    detail: "Target 是无法解析的软链",
+                };
+            }
+            if (resolvedTarget === sourcePath && this.resolveSkillDirectory(targetPath)) {
+                return {
+                    agent_id: agentId,
+                    delivery_mode: deliveryMode(agentId),
+                    target_path: targetPath,
+                    state: "linked",
+                    mutable: agentId === "claude",
+                    detail: "目标目录可见且 SKILL.md 可读",
+                };
+            }
+            return {
+                agent_id: agentId,
+                delivery_mode: deliveryMode(agentId),
+                target_path: targetPath,
+                state: "conflict",
+                mutable: agentId === "claude",
+                detail: `Target 已指向其他 Source: ${resolvedTarget}`,
+            };
+        }
+        return {
+            agent_id: agentId,
+            delivery_mode: deliveryMode(agentId),
+            target_path: targetPath,
+            state: "conflict",
+            mutable: agentId === "claude",
+            detail: "Target 已存在且不是受管软链",
+        };
+    }
+    isManagedLink(targetPath, sourcePath) {
+        try {
+            return fs.lstatSync(targetPath).isSymbolicLink()
+                && fs.realpathSync(targetPath) === sourcePath;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+function deliveryMode(agentId) {
+    return agentId === "claude" ? "symlink_projection" : "shared_native";
+}
+function assignmentKey(skillId, agentId) {
+    return `${skillId}:${agentId}`;
+}
+function pathExists(candidate) {
+    try {
+        fs.statSync(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pathExistsLstat(candidate) {
+    try {
+        fs.lstatSync(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isPathInside(root, candidate) {
+    const normalizedRoot = canonicalPath(root);
+    const normalizedCandidate = canonicalPath(candidate);
+    const relative = path.relative(normalizedRoot, normalizedCandidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+function canonicalPath(candidate) {
+    try {
+        return fs.realpathSync(candidate);
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+function migrateLegacyStateFile(legacyPath, targetPath) {
+    if (pathExistsLstat(targetPath) || !pathExists(legacyPath))
+        return;
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.copyFileSync(legacyPath, targetPath, fs.constants.COPYFILE_EXCL);
+}
+function fingerprintPath(candidate) {
+    try {
+        const stat = fs.lstatSync(candidate);
+        if (stat.isSymbolicLink()) {
+            let resolved = "broken";
+            try {
+                resolved = fs.realpathSync(candidate);
+            }
+            catch {
+                // Broken links must still have a stable fingerprint.
+            }
+            return `symlink:${fs.readlinkSync(candidate)}:${resolved}`;
+        }
+        if (stat.isDirectory()) {
+            const packageFingerprint = fingerprintSkillPackage(candidate);
+            return `directory:${packageFingerprint.valid}:${packageFingerprint.revision}`;
+        }
+        if (stat.isFile()) {
+            return `file:${stat.mode & 0o111}:${crypto.createHash("sha256").update(fs.readFileSync(candidate)).digest("hex")}`;
+        }
+        return `special:${stat.mode}`;
+    }
+    catch {
+        return "absent";
+    }
+}
+function fingerprintSkillPackage(root) {
+    const hash = crypto.createHash("sha256");
+    let valid = true;
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })
+            .sort((left, right) => left.name.localeCompare(right.name))) {
+            const absolute = path.join(directory, entry.name);
+            const relative = path.relative(root, absolute).split(path.sep).join("/");
+            const stat = fs.lstatSync(absolute);
+            if (stat.isDirectory()) {
+                hash.update(`directory\0${relative}\0${stat.mode & 0o111}\0`);
+                visit(absolute);
+                continue;
+            }
+            if (stat.isFile()) {
+                hash.update(`file\0${relative}\0${stat.mode & 0o111}\0`);
+                hash.update(fs.readFileSync(absolute));
+                hash.update("\0");
+                continue;
+            }
+            if (stat.isSymbolicLink()) {
+                const target = fs.readlinkSync(absolute);
+                const resolved = path.resolve(path.dirname(absolute), target);
+                const relativeTarget = path.relative(root, resolved);
+                if (path.isAbsolute(target) || relativeTarget === ".." || relativeTarget.startsWith(`..${path.sep}`)) {
+                    valid = false;
+                }
+                hash.update(`symlink\0${relative}\0${target}\0`);
+                continue;
+            }
+            valid = false;
+            hash.update(`special\0${relative}\0`);
+        }
+    };
+    visit(root);
+    return { revision: hash.digest("hex"), valid };
+}
+function parseSkillMetadata(content, fallbackName) {
+    const frontmatter = content.startsWith("---\n")
+        ? content.slice(4, content.indexOf("\n---", 4) >= 0 ? content.indexOf("\n---", 4) : 4)
+        : "";
+    const fields = new Map();
+    for (const line of frontmatter.split("\n")) {
+        const match = /^([a-zA-Z_][\w-]*):\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        fields.set(match[1], unquote(match[2].trim()));
+    }
+    const rawTags = fields.get("tags") ?? "";
+    const tags = rawTags.replace(/^\[|\]$/g, "").split(",")
+        .map((tag) => unquote(tag.trim()))
+        .filter(Boolean);
+    return {
+        name: fields.get("name") || fallbackName,
+        description: fields.get("description") || null,
+        tags,
+    };
+}
+function unquote(value) {
+    if ((value.startsWith('"') && value.endsWith('"'))
+        || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+//# sourceMappingURL=skill-control-plane.js.map