@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/profile/catalog-store.js

@@ -0,0 +1,346 @@
+/**
+ * 已注册的数字人仓库：注册表 + 克隆缓存 + 读取。
+ *
+ * 与插件市场并列的一等分发通道。数字人不必先成为插件——它有自己的定义格式和
+ * 导入/导出原语，仓库只是把「一批定义」打包分发。
+ *
+ * 磁盘布局：
+ *   ~/.code-shell/human-repos.json        —— 注册表（owner/repo 列表）
+ *   ~/.code-shell/human-repos/<key>/      —— 各仓库的浅克隆
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { codeShellHome } from "../session/session-manager.js";
+import { acquireLockOnPath, mutateJsonFile } from "../utils/file-mutex.js";
+// gitFetchAndReset is deliberately NOT used any more: updating in place is what
+// destroyed the last-known-good tree on a bad upstream commit. Updates clone to
+// a staging dir and swap (see addHumanRepo).
+import { gitClone, githubRepoToCloneUrl } from "../plugins/gitOps.js";
+import { CATALOG_REPO_RE, readCatalogFromDir, sourceToRepoKey, } from "./catalog.js";
+const MAX_REPOS = 32;
+export function humanReposRoot() {
+    return join(codeShellHome(), "human-repos");
+}
+function registryPath() {
+    return join(codeShellHome(), "human-repos.json");
+}
+export function humanRepoDir(repo) {
+    return join(humanReposRoot(), sourceToRepoKey(repo));
+}
+export function listHumanRepos() {
+    try {
+        // Missing or corrupt registry reads as "no repos" — never fatal.
+        return parseRegistry(readFileSync(registryPath(), "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function parseRegistry(raw) {
+    if (raw === undefined)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.repos))
+            return [];
+        return parsed.repos
+            .filter((r) => !!r &&
+            typeof r === "object" &&
+            typeof r.repo === "string" &&
+            CATALOG_REPO_RE.test(r.repo))
+            .map((r) => ({ repo: r.repo, addedAt: Number(r.addedAt) || 0 }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Serialize add/update/remove of ONE repo across processes.
+ *
+ * Distinct from the registry lock inside `updateRegistry`: that one only guards
+ * the JSON file, and is held for a moment. This one spans the whole mutation —
+ * capacity check, directory swap, registry write — so two processes cannot both
+ * decide the repo is absent and clone into the same path, and cannot both slip
+ * past MAX_REPOS. Keyed per repo, so unrelated repos still install in parallel.
+ *
+ * The lock file lives next to the clones and is never the clone dir itself
+ * (proper-lockfile creates `<path>.lock`, which must not collide with a tree we
+ * rename over).
+ */
+function withHumanRepoLock(repo, run) {
+    const root = humanReposRoot();
+    mkdirSync(root, { recursive: true });
+    const lockTarget = join(root, `.${sourceToRepoKey(repo)}.repo-lock`);
+    if (!existsSync(lockTarget))
+        writeFileSync(lockTarget, "", { mode: 0o600 });
+    // Lock the marker FILE, not humanReposRoot(): a directory lock would serialize
+    // unrelated repos and deadlock against the registry lock taken below.
+    // 30s covers a swap that waits behind another process's publish step.
+    const release = acquireLockOnPath(lockTarget, 30_000);
+    try {
+        return run();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Read-modify-write the registry under a cross-process lock.
+ *
+ * add/remove used to be `listHumanRepos()` in the caller followed by a bare
+ * `writeFileSync` of the whole array. Two windows (or a window plus an agent)
+ * mutating different repos would each write back their own stale snapshot, so
+ * one of the entries silently disappeared. The single-window UI operation lock
+ * did not help, because it does not span processes.
+ */
+function updateRegistry(change) {
+    mkdirSync(codeShellHome(), { recursive: true });
+    mutateJsonFile(registryPath(), {
+        parse: parseRegistry,
+        serialize: (repos) => `${JSON.stringify({ repos }, null, 2)}\n`,
+        mutation: (current) => ({ value: change(current) }),
+        mode: 0o600,
+    });
+}
+/**
+ * 注册并克隆一个数字人仓库。已存在则拉取更新。
+ *
+ * 克隆是网络+磁盘写入操作，调用方应已取得用户确认。
+ */
+export async function addHumanRepo(repo) {
+    if (!CATALOG_REPO_RE.test(repo)) {
+        return { ok: false, error: `"${repo}" 不是合法的仓库地址（应为 owner/repo）` };
+    }
+    const dir = humanRepoDir(repo);
+    mkdirSync(humanReposRoot(), { recursive: true });
+    // Clone into a private staging dir FIRST, outside the lock — this is the slow
+    // network step and must not hold the lock for the duration. Both the add and
+    // the update path stage: cloning straight into `dir` let two processes race
+    // into the same path, and the loser's `rmSync(dir)` then deleted the winner's
+    // perfectly good clone.
+    const staging = `${dir}.staging-${process.pid}-${randomUUID()}`;
+    try {
+        const cloned = await gitClone(githubRepoToCloneUrl(repo), staging, { full: true });
+        if (!cloned.ok) {
+            // Only ever removes OUR staging dir (finally below); `dir` is untouched.
+            return { ok: false, error: explainGitFailure(cloned.error, repo) };
+        }
+        const staged = readCatalogFromDir(staging, repo);
+        if (staged.entries.length === 0 && staged.errors.length > 0) {
+            // A repo that yields nothing usable is a mistake worth surfacing now
+            // rather than leaving an empty row in the list. On update this also keeps
+            // the last known good tree in place.
+            const hadPrevious = existsSync(dir);
+            return {
+                ok: false,
+                error: hadPrevious
+                    ? `更新 ${repo} 失败，已保留上一个可用版本：${staged.errors[0]}`
+                    : staged.errors[0],
+            };
+        }
+        // Publish under the repo lock: capacity check, directory swap and registry
+        // write must be one critical section. Checking MAX_REPOS before the lock
+        // let N processes each observe 31 repos and all proceed past the cap.
+        const published = withHumanRepoLock(repo, () => {
+            const current = listHumanRepos();
+            const alreadyRegistered = current.some((r) => r.repo === repo);
+            if (current.length >= MAX_REPOS && !alreadyRegistered) {
+                return { ok: false, error: `最多只能添加 ${MAX_REPOS} 个数字人仓库` };
+            }
+            promoteStagedRepo(staging, dir);
+            updateRegistry((repos) => [
+                ...repos.filter((r) => r.repo !== repo),
+                { repo, addedAt: Date.now() },
+            ]);
+            return { ok: true };
+        });
+        if (!published.ok)
+            return published;
+        return {
+            ok: true,
+            entry: {
+                repo,
+                addedAt: Date.now(),
+                count: staged.entries.length,
+                errors: staged.errors,
+                cloned: true,
+            },
+        };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/**
+ * Swap a validated staging tree into place.
+ *
+ * Ordering matters for crash safety: promote FIRST (rename staging over a
+ * now-absent `dir`), and only retire the old tree around it. The previous
+ * `dir → retired` then `staging → dir` sequence left no tree at `dir` at all if
+ * the process died in between, and nothing scanned for `.retired-*` on startup,
+ * so the UI showed "尚未克隆" with the data still on disk under a name nobody
+ * looked for. Here the only window is one where BOTH the old tree (at `retired`)
+ * and the new tree (at `staging`) still exist, and `reclaimOrphanedTrees`
+ * cleans up whatever is left over on the next call.
+ */
+function promoteStagedRepo(staging, dir) {
+    reclaimOrphanedTrees(dir);
+    if (!existsSync(dir)) {
+        renameSync(staging, dir);
+        return;
+    }
+    const retired = `${dir}.retired-${process.pid}-${randomUUID()}`;
+    renameSync(dir, retired);
+    try {
+        renameSync(staging, dir);
+    }
+    catch (err) {
+        // Promotion failed — put the good tree back before surfacing the error.
+        try {
+            renameSync(retired, dir);
+        }
+        catch {
+            // Best effort; the retired copy is still on disk for manual recovery.
+        }
+        throw err;
+    }
+    rmSync(retired, { recursive: true, force: true });
+}
+/**
+ * Recover from a crash during a previous swap.
+ *
+ * If `dir` is missing but a `.retired-*` sibling exists, a process died between
+ * retiring the old tree and promoting the new one. Restore the newest retired
+ * tree rather than leaving the repo looking un-cloned, then drop the rest.
+ * Runs under the repo lock, so no concurrent swap can be mid-flight.
+ */
+function reclaimOrphanedTrees(dir) {
+    const parent = dirname(dir);
+    const prefix = `${basename(dir)}.retired-`;
+    let orphans;
+    try {
+        orphans = readdirSync(parent).filter((name) => name.startsWith(prefix));
+    }
+    catch {
+        return;
+    }
+    if (orphans.length === 0)
+        return;
+    orphans.sort();
+    if (!existsSync(dir)) {
+        const restore = orphans.pop();
+        try {
+            renameSync(join(parent, restore), dir);
+        }
+        catch {
+            // Fall through: leave it for manual recovery rather than deleting data.
+        }
+    }
+    for (const stale of orphans) {
+        rmSync(join(parent, stale), { recursive: true, force: true });
+    }
+}
+/**
+ * Crash-safety internals, exposed for tests only.
+ *
+ * `promoteStagedRepo`/`reclaimOrphanedTrees` implement the swap-and-recover
+ * protocol. Exercising them through `addHumanRepo` would require network git, so
+ * the recovery cases (interrupted swap, stale retired trees) are tested here
+ * directly. Not part of the package's public surface.
+ */
+export const __testables = { promoteStagedRepo, reclaimOrphanedTrees };
+/**
+ * Turn a raw git failure into something a user can act on.
+ *
+ * gitOps deliberately returns the full command line (`git clone --depth 1
+ * --filter=blob:none … exited 128: …`) because it serves low-level callers.
+ * Pasting that into an "add a repo" box tells the user nothing about the actual
+ * problem — usually just a typo in the name.
+ */
+function explainGitFailure(error, repo) {
+    if (/repository not found|could not read from remote|remote: not found/i.test(error)) {
+        return `找不到仓库 ${repo}。请检查拼写，并确认它是公开仓库。`;
+    }
+    if (/authentication failed|permission denied|terminal prompts disabled/i.test(error)) {
+        return `无权访问 ${repo}。私有仓库需要先配置 git 凭据。`;
+    }
+    if (/could not resolve host|network is unreachable|timed out|operation timed out/i.test(error)) {
+        return `无法连接 GitHub，请检查网络后重试。`;
+    }
+    if (error.startsWith("GIT_NOT_FOUND")) {
+        // Already a written, actionable message from gitOps.
+        return error;
+    }
+    // Unrecognized: keep the tail (the actual stderr) and drop the command line,
+    // so the user sees the cause rather than our argv.
+    const tail = error.includes(": ") ? error.slice(error.lastIndexOf(": ") + 2) : error;
+    return `克隆 ${repo} 失败：${tail.trim() || "未知错误"}`;
+}
+export function removeHumanRepo(repo) {
+    if (!CATALOG_REPO_RE.test(repo))
+        throw new Error("invalid digital-human repo");
+    // Same repo lock as add/update: otherwise a remove can delete the tree a
+    // concurrent add just published, leaving a registered repo with no clone.
+    withHumanRepoLock(repo, () => {
+        // Filter inside the registry lock so a concurrent add of a DIFFERENT repo
+        // is not lost.
+        updateRegistry((repos) => repos.filter((r) => r.repo !== repo));
+        const dir = humanRepoDir(repo);
+        rmSync(dir, { recursive: true, force: true });
+        // Drop any tree a crashed swap left behind, so a later re-add does not
+        // resurrect the old contents via reclaimOrphanedTrees.
+        reclaimOrphanedTrees(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+}
+/** 注册表 + 每个仓库的读取结果，供设置页展示。 */
+export function listHumanRepoDetails() {
+    return listHumanRepos().map((registered) => {
+        const dir = humanRepoDir(registered.repo);
+        if (!existsSync(dir)) {
+            return { ...registered, count: 0, errors: ["尚未克隆"], cloned: false };
+        }
+        const read = readCatalogFromDir(dir, registered.repo);
+        return { ...registered, count: read.entries.length, errors: read.errors, cloned: true };
+    });
+}
+/**
+ * 所有已注册仓库提供的数字人。
+ *
+ * 同名定义按注册顺序先到先得，并记一条冲突说明——静默覆盖会让用户以为装的是
+ * 另一个仓库的版本。
+ */
+export function readAllHumanRepoEntries() {
+    const entries = [];
+    const teams = [];
+    const errors = [];
+    const seen = new Map();
+    const seenTeams = new Map();
+    for (const { repo } of listHumanRepos()) {
+        const dir = humanRepoDir(repo);
+        if (!existsSync(dir))
+            continue;
+        const read = readCatalogFromDir(dir, repo);
+        errors.push(...read.errors);
+        for (const entry of read.entries) {
+            const owner = seen.get(entry.profile.name);
+            if (owner) {
+                errors.push(`"${entry.profile.name}" 同时存在于 ${owner} 与 ${repo}，已采用前者`);
+                continue;
+            }
+            seen.set(entry.profile.name, repo);
+            entries.push(entry);
+        }
+        for (const team of read.teams) {
+            const owner = seenTeams.get(team.id);
+            if (owner) {
+                errors.push(`团队 "${team.id}" 同时存在于 ${owner} 与 ${repo}，已采用前者`);
+                continue;
+            }
+            seenTeams.set(team.id, repo);
+            teams.push(team);
+        }
+    }
+    return { entries, teams, errors };
+}

package/dist/profile/catalog.d.ts

@@ -0,0 +1,54 @@
+import { type WorkspaceProfile } from "./types.js";
+/** `owner/repo`，与 SKILL_REPO_RE 同源，供仓库地址复用。 */
+export declare const CATALOG_REPO_RE: RegExp;
+export interface HumansManifestEntry {
+    name: string;
+    label?: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+}
+export interface HumansManifest {
+    name?: string;
+    description?: string;
+    humans: HumansManifestEntry[];
+    teams: HumansManifestTeam[];
+}
+/**
+ * A team shipped by a repo. Same shape as a locally-authored team minus `mode`
+ * (the dead enum): `lead` picks the coordinator, `playbook` is the collaboration
+ * rules injected into its opening briefing.
+ */
+export interface HumansManifestTeam {
+    id: string;
+    name: string;
+    description?: string;
+    members: string[];
+    lead?: string;
+    playbook?: string;
+}
+export interface CatalogTeam extends HumansManifestTeam {
+    sourceRepo: string;
+}
+export interface CatalogEntry {
+    profile: WorkspaceProfile;
+    /** 来源仓库 `owner/repo`，用于展示与去重。 */
+    sourceRepo: string;
+    category?: string;
+    tags: string[];
+}
+export interface CatalogReadResult {
+    entries: CatalogEntry[];
+    teams: CatalogTeam[];
+    /** 逐条目的失败原因；一个坏定义不该让整个仓库不可用。 */
+    errors: string[];
+}
+/**
+ * `owner/repo` → 一个安全的目录段。小写化保证同一仓库不同大小写写法命中同一份
+ * 缓存；斜杠换成 `-` 后仍需通过 SAFE_SEGMENT_RE，杜绝路径逃逸。
+ */
+export declare function sourceToRepoKey(repo: string): string;
+/** 解析 humans.json。缺 humans 数组按空目录处理；JSON 坏了才抛。 */
+export declare function parseHumansManifest(raw: string): HumansManifest;
+/** 读取一个已克隆的数字人仓库目录。 */
+export declare function readCatalogFromDir(dir: string, sourceRepo: string): CatalogReadResult;

package/dist/profile/catalog.js

@@ -0,0 +1,152 @@
+/**
+ * 数字人仓库（catalog）：从 git 仓库读取一批数字人定义。
+ *
+ * 与插件市场并列而非寄生：数字人有自己的一等分发原语（导入/导出 + 本仓库），
+ * 不需要先成为插件。仓库布局与 cjhyy/mimi-humans 一致：
+ *
+ *   humans.json          —— 目录清单（name/label/description/category/tags）
+ *   humans/<name>/profile.json —— WorkspaceProfile 定义（含可选 requires）
+ *
+ * 本模块只做**读取与校验**，克隆/更新由 host 驱动（涉及网络与磁盘写入）。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { WorkspaceProfileSchema } from "./types.js";
+/** `owner/repo`，与 SKILL_REPO_RE 同源，供仓库地址复用。 */
+export const CATALOG_REPO_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+/** 单个目录段的安全名，挡住 `..`、分隔符与 NUL。 */
+const SAFE_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+ * `owner/repo` → 一个安全的目录段。小写化保证同一仓库不同大小写写法命中同一份
+ * 缓存；斜杠换成 `-` 后仍需通过 SAFE_SEGMENT_RE，杜绝路径逃逸。
+ */
+export function sourceToRepoKey(repo) {
+    if (!CATALOG_REPO_RE.test(repo)) {
+        throw new Error(`invalid digital-human repo "${repo}" (expected owner/repo)`);
+    }
+    const key = repo
+        .toLowerCase()
+        .replace(/\.git$/, "")
+        .replace("/", "-");
+    if (!SAFE_SEGMENT_RE.test(key)) {
+        throw new Error(`digital-human repo "${repo}" does not map to a safe directory name`);
+    }
+    return key;
+}
+/** 解析 humans.json。缺 humans 数组按空目录处理；JSON 坏了才抛。 */
+export function parseHumansManifest(raw) {
+    const value = JSON.parse(raw);
+    const rawHumans = Array.isArray(value.humans) ? value.humans : [];
+    const humans = [];
+    for (const item of rawHumans) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const entry = item;
+        if (typeof entry.name !== "string" || !entry.name)
+            continue;
+        humans.push({
+            name: entry.name,
+            ...(typeof entry.label === "string" ? { label: entry.label } : {}),
+            ...(typeof entry.description === "string" ? { description: entry.description } : {}),
+            ...(typeof entry.category === "string" ? { category: entry.category } : {}),
+            tags: Array.isArray(entry.tags)
+                ? entry.tags.filter((t) => typeof t === "string")
+                : [],
+        });
+    }
+    const rawTeams = Array.isArray(value.teams) ? value.teams : [];
+    const teams = [];
+    for (const item of rawTeams) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const entry = item;
+        if (typeof entry.id !== "string" || !entry.id)
+            continue;
+        if (typeof entry.name !== "string" || !entry.name)
+            continue;
+        const rawMembers = Array.isArray(entry.members) ? entry.members : [];
+        const members = rawMembers.filter((m) => typeof m === "string" && m.length > 0);
+        if (members.length < 2)
+            continue;
+        teams.push({
+            id: entry.id,
+            name: entry.name,
+            ...(typeof entry.description === "string" ? { description: entry.description } : {}),
+            members,
+            ...(typeof entry.lead === "string" && entry.lead ? { lead: entry.lead } : {}),
+            ...(typeof entry.playbook === "string" && entry.playbook ? { playbook: entry.playbook } : {}),
+        });
+    }
+    return {
+        ...(typeof value.name === "string" ? { name: value.name } : {}),
+        ...(typeof value.description === "string" ? { description: value.description } : {}),
+        humans,
+        teams,
+    };
+}
+/** 读取一个已克隆的数字人仓库目录。 */
+export function readCatalogFromDir(dir, sourceRepo) {
+    const manifestPath = join(dir, "humans.json");
+    if (!existsSync(manifestPath)) {
+        return { entries: [], teams: [], errors: [`${sourceRepo}: humans.json not found`] };
+    }
+    let manifest;
+    try {
+        manifest = parseHumansManifest(readFileSync(manifestPath, "utf-8"));
+    }
+    catch (error) {
+        return {
+            entries: [],
+            teams: [],
+            errors: [`${sourceRepo}: humans.json is not valid JSON (${describe(error)})`],
+        };
+    }
+    const entries = [];
+    const errors = [];
+    for (const item of manifest.humans) {
+        // The manifest is untrusted input from a cloned repo — never join a name
+        // that could climb out of the humans/ directory.
+        if (!SAFE_SEGMENT_RE.test(item.name)) {
+            errors.push(`${sourceRepo}: entry "${item.name}" has an unsafe name`);
+            continue;
+        }
+        const profilePath = join(dir, "humans", item.name, "profile.json");
+        try {
+            const profile = WorkspaceProfileSchema.parse(JSON.parse(readFileSync(profilePath, "utf-8")));
+            entries.push({
+                profile,
+                sourceRepo,
+                ...(item.category ? { category: item.category } : {}),
+                tags: item.tags ?? [],
+            });
+        }
+        catch (error) {
+            errors.push(`${sourceRepo}: "${item.name}" is invalid (${describe(error)})`);
+        }
+    }
+    // A team is only usable if every member ships in this same repo — otherwise
+    // summoning it would create Sessions bound to digital humans that do not exist.
+    const shipped = new Set(entries.map((entry) => entry.profile.name));
+    const teams = [];
+    for (const team of manifest.teams) {
+        if (!SAFE_SEGMENT_RE.test(team.id)) {
+            errors.push(`${sourceRepo}: team "${team.id}" has an unsafe id`);
+            continue;
+        }
+        const missing = team.members.filter((member) => !shipped.has(member));
+        if (missing.length > 0) {
+            errors.push(`${sourceRepo}: team "${team.id}" references missing ${missing.join(", ")}`);
+            continue;
+        }
+        if (team.lead && !team.members.includes(team.lead)) {
+            errors.push(`${sourceRepo}: team "${team.id}" lead is not one of its members`);
+            continue;
+        }
+        teams.push({ ...team, sourceRepo });
+    }
+    return { entries, teams, errors };
+}
+function describe(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length > 200 ? `${message.slice(0, 200)}…` : message;
+}

package/dist/profile/index.d.ts

@@ -0,0 +1,7 @@
+export { SKILL_REPO_RE, WORKSPACE_PROFILE_NAME_RE, WorkspaceProfileRequirementsSchema, WorkspaceProfileSchema, type SkillRequirement, type ToolRequirement, type WorkspaceProfile, type WorkspaceProfileInput, type WorkspaceProfileRequirements, } from "./types.js";
+export { CATALOG_REPO_RE, parseHumansManifest, readCatalogFromDir, sourceToRepoKey, type CatalogEntry as DigitalHumanCatalogSourceEntry, type CatalogTeam as DigitalHumanCatalogTeam, type HumansManifestTeam, type CatalogReadResult, type HumansManifest, type HumansManifestEntry, } from "./catalog.js";
+export { addHumanRepo, humanRepoDir, humanReposRoot, listHumanRepoDetails, listHumanRepos, readAllHumanRepoEntries, removeHumanRepo, type HumanRepoListEntry, type RegisteredHumanRepo, } from "./catalog-store.js";
+export { buildSkillInstallArgs, planProfileRequirements, summarizeSkillConflicts, type KnownSkill, type MissingTool, type PlannedSkillInstall, type ProfileRequirementPlan, type SkillConflict, } from "./requirements.js";
+export { deleteWorkspaceProfile, listWorkspaceProfiles, readWorkspaceProfile, saveWorkspaceProfile, workspaceProfileDir, workspaceProfilesRoot, } from "./store.js";
+export { activateWorkspaceProfile, deactivateWorkspaceProfile, profileOverridesFromDefinition, type InstalledCapabilityNames, type WorkspaceProfileSubtree, } from "./activation.js";
+export { resolveActiveWorkspaceProfile, workspaceProfilePresetFor, type ResolveActiveWorkspaceProfileInput, } from "./resolve.js";

package/dist/profile/index.js

@@ -0,0 +1,7 @@
+export { SKILL_REPO_RE, WORKSPACE_PROFILE_NAME_RE, WorkspaceProfileRequirementsSchema, WorkspaceProfileSchema, } from "./types.js";
+export { CATALOG_REPO_RE, parseHumansManifest, readCatalogFromDir, sourceToRepoKey, } from "./catalog.js";
+export { addHumanRepo, humanRepoDir, humanReposRoot, listHumanRepoDetails, listHumanRepos, readAllHumanRepoEntries, removeHumanRepo, } from "./catalog-store.js";
+export { buildSkillInstallArgs, planProfileRequirements, summarizeSkillConflicts, } from "./requirements.js";
+export { deleteWorkspaceProfile, listWorkspaceProfiles, readWorkspaceProfile, saveWorkspaceProfile, workspaceProfileDir, workspaceProfilesRoot, } from "./store.js";
+export { activateWorkspaceProfile, deactivateWorkspaceProfile, profileOverridesFromDefinition, } from "./activation.js";
+export { resolveActiveWorkspaceProfile, workspaceProfilePresetFor, } from "./resolve.js";

package/dist/profile/requirements.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 数字人依赖：把 profile.requires 解析成「将要发生什么」的计划，供 UI 先展示、
+ * 用户确认后再执行。
+ *
+ * 为什么需要这一层：plugins/skills/mcp/agents 四个字段只是 force-enable 开关，
+ * 只能打开磁盘上已存在的能力。没有获取步骤，一个声明了 skill 的数字人在新机器上
+ * 会静默变成空壳（能力名写着，实际什么都没启用）。
+ *
+ * 安全边界：安装会克隆远程仓库并执行 `npx skills add`，属于运行远程代码。本模块
+ * 只负责**计划与校验**，从不自行执行；执行由 host 在拿到用户确认后驱动
+ * ({@link buildSkillInstallArgs} 给出确切 argv)。
+ */
+import type { SkillRequirement, WorkspaceProfileRequirements } from "./types.js";
+/** scanner 已发现的一条 skill（`plugin:skill` 形式代表插件来源）。 */
+export interface KnownSkill {
+    name: string;
+    source: "project" | "user" | "plugin" | "panel-app";
+}
+export interface SkillConflict {
+    name: string;
+    /** 已占用该名字的来源。安装到 project 根后它会被遮蔽。 */
+    existingSource: KnownSkill["source"];
+}
+export interface PlannedSkillInstall {
+    requirement: SkillRequirement;
+    /** 具名子集里确实缺失的那些；整仓安装（--all）时为 undefined。 */
+    missing?: string[];
+}
+export type MissingToolReason = "not-found" | "too-old";
+export interface MissingTool {
+    bin: string;
+    reason: MissingToolReason;
+    /** reason=too-old 时实际探到的版本。 */
+    found?: string;
+    /** reason=too-old 时 profile 要求的版本。 */
+    required?: string;
+    hint?: string;
+}
+export interface ProfileRequirementPlan {
+    skillInstalls: PlannedSkillInstall[];
+    missingTools: MissingTool[];
+    conflicts: SkillConflict[];
+    /** 是否有需要用户确认后执行的安装动作。 */
+    needsInstall: boolean;
+}
+export interface PlanRequirementsContext {
+    /** 当前 scanner 能看到的全部 skill。 */
+    installedSkills: readonly KnownSkill[];
+    /** 探测一个外部命令的版本输出；不存在返回 null。 */
+    toolProbe: (bin: string) => string | null;
+}
+/**
+ * 组装 `npx skills add` 的 argv。
+ *
+ * 两条硬约束：
+ * 1. **绝不加 `-g`** —— 全局安装落在 `~/.claude/skills`，而 scanner 只读
+ *    `<cwd>/.code-shell/skills`、`<cwd>/.agents/skills`、`~/.code-shell/skills`
+ *    三个根。装了却扫不到，就是又一个"配了等于没配"。
+ * 2. repo 与 skill 名各自占独立 argv 槽，不拼 shell 字符串；配合 schema 的
+ *    `SKILL_REPO_RE` 挡住 `--flag` / `../` / `;rm -rf` 一类注入。
+ */
+export declare function buildSkillInstallArgs(requirement: SkillRequirement): string[];
+/** 从 `--version` 输出里取第一个点分版本号。 */
+export declare function parseToolVersion(output: string): string | undefined;
+/** 按数字段比较；返回 <0 / 0 / >0。缺省段视为 0，故 "22" == "22.0.0"。 */
+export declare function compareToolVersions(a: string, b: string): number;
+/**
+ * 找出即将安装的裸名与已有 skill 的撞名。
+ *
+ * scanner 的去重是「先到先得且静默」——同名后来者直接被丢弃，不告警。所以要在
+ * 安装前把遮蔽关系摊开给用户看。插件 skill 带 `plugin:` 命名空间、走独立 dedup
+ * 集合，永远不会与裸名互相覆盖，故排除。
+ */
+export declare function summarizeSkillConflicts(incoming: readonly string[], installed: readonly KnownSkill[]): SkillConflict[];
+/** 纯函数：不碰磁盘、不起进程，全部输入经 context 注入，便于测试。 */
+export declare function planProfileRequirements(requires: WorkspaceProfileRequirements | undefined, context: PlanRequirementsContext): ProfileRequirementPlan;