@zhangheteng/skill-hub 0.0.0-stage → 0.2.0

package/apps/cli/dist/commands/init.js

@@ -0,0 +1,110 @@
+import { access, readFile, mkdir, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createEmptyCatalog, writeCatalog } from "#skill-hub/core";
+import { getDefaultHubHome, hubLayout } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runInit(options) {
+    const layout = hubLayout(getDefaultHubHome());
+    const created = [];
+    const skipped = [];
+    for (const dir of [layout.home, layout.skills, layout.index, layout.backups]) {
+        try {
+            await access(dir, fsConstants.F_OK);
+            skipped.push(dir);
+        }
+        catch {
+            await mkdir(dir, { recursive: true });
+            created.push(dir);
+        }
+    }
+    // config.yaml
+    let configAction = "skipped";
+    try {
+        await access(layout.config, fsConstants.F_OK);
+        if (options.force) {
+            await writeDefaultConfig(layout.config);
+            configAction = "overwritten";
+        }
+    }
+    catch {
+        await writeDefaultConfig(layout.config);
+        configAction = "created";
+        created.push(layout.config);
+    }
+    // catalog.json
+    let catalogAction = "skipped";
+    try {
+        await access(layout.catalog, fsConstants.F_OK);
+        if (options.force) {
+            await writeCatalog(layout.catalog, createEmptyCatalog());
+            catalogAction = "overwritten";
+        }
+    }
+    catch {
+        await writeCatalog(layout.catalog, createEmptyCatalog());
+        catalogAction = "created";
+        created.push(layout.catalog);
+    }
+    const result = {
+        ok: true,
+        home: layout.home,
+        created,
+        skipped,
+        config: { path: layout.config, action: configAction },
+        catalog: { path: layout.catalog, action: catalogAction },
+    };
+    if (options.json)
+        printJson(result);
+    else {
+        printLines([
+            `init hub → ${layout.home}`,
+            `  config:  ${configAction}`,
+            `  catalog: ${catalogAction}`,
+            `  created dirs: ${created.filter((c) => !c.endsWith(".yaml") && !c.endsWith(".json")).length}`,
+        ]);
+    }
+    return 0;
+}
+async function writeDefaultConfig(target) {
+    // 优先从仓库模板复制
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(here, "../../../../configs/agents/default.yaml"),
+        path.resolve(process.cwd(), "configs/agents/default.yaml"),
+    ];
+    for (const c of candidates) {
+        try {
+            await access(c, fsConstants.R_OK);
+            await mkdir(path.dirname(target), { recursive: true });
+            const template = await readFile(c, "utf8");
+            await writeFile(target, template.replaceAll("~/.skill-hub", getDefaultHubHome()), "utf8");
+            return;
+        }
+        catch {
+            // try next
+        }
+    }
+    const fallback = `version: 1
+canonical_dir: ~/.skill-hub/skills
+index_dir: ~/.skill-hub/index
+backup_dir: ~/.skill-hub/backups
+agents:
+  - id: workbuddy
+    skills_dir: ~/.workbuddy/skills
+    enabled: true
+sources: []
+router:
+  top_k: 5
+  engine: bm25
+sync:
+  mode: symlink
+  conflict: report
+  require_backup: true
+privacy:
+  telemetry: false
+`;
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, fallback.replaceAll("~/.skill-hub", getDefaultHubHome()), "utf8");
+}

package/apps/cli/dist/commands/inspect.js

@@ -0,0 +1,68 @@
+import { skillExplain, skillHistory, skillPaths } from "#skill-hub/router";
+import { SkillHubError } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runExplain(options) {
+    const result = await skillExplain(options);
+    if (options.json) {
+        printJson(result);
+        return 0;
+    }
+    printLines([
+        `explain ${result.name}`,
+        `  scope:      ${result.scope}`,
+        `  source:     ${result.source ?? "unknown"}`,
+        `  hash:       ${result.meta.hash}`,
+        `  revision:   ${result.revision ?? "unknown"}`,
+        `  status:     ${result.status ?? "unknown"}`,
+        `  recorded:   ${result.meta.path}`,
+        `  variants:   ${result.variants.length}`,
+        `  winner:     ${result.winner?.path ?? result.meta.path}`,
+        `  reason:     ${result.winnerReason ?? "无同名不同 hash 冲突"}`,
+        `  overlay:    ${result.overlay.overlayOf ?? "none"}`,
+        `  projections: ${result.paths.agents.filter((item) => item.status === "ok").length}/${result.paths.agents.length} healthy`,
+        `  history:    ${result.history.length} events`,
+    ]);
+    if (result.conflict) {
+        printLines([
+            "  conflict variants:",
+            ...result.conflict.variants.map((variant) => `    - ${variant.path} ${variant.hash} ${variant.agentId ?? ""}`.trim()),
+        ]);
+    }
+    return 0;
+}
+export async function runPath(options) {
+    const result = await skillPaths(options);
+    if (options.json) {
+        printJson(result);
+        return 0;
+    }
+    printLines([
+        `path ${result.name}`,
+        `  canonical: ${result.canonicalPath} (${result.canonicalExists ? "exists" : "missing"})`,
+        `  recorded:  ${result.recordedPath}`,
+        `  source:    ${result.source.path ?? result.source.ref ?? "unknown"}`,
+        "  agents:",
+        ...result.agents.map((agent) => `    - ${agent.agentId}${agent.enabled ? "" : " (disabled)"}: ${agent.status} → ${agent.target}${agent.detail ? ` (${agent.detail})` : ""}`),
+    ]);
+    return 0;
+}
+export async function runHistory(options) {
+    if (options.limit !== undefined && (!Number.isFinite(options.limit) || options.limit < 1)) {
+        throw new SkillHubError({ code: "E_CONFIG", message: "history --limit 必须是正整数" });
+    }
+    const result = await skillHistory(options);
+    if (options.json) {
+        printJson(result);
+        return 0;
+    }
+    printLines([
+        `history${result.name ? ` ${result.name}` : ""}  events=${result.entries.length}`,
+        `  file: ${result.path}`,
+        ...result.entries.map((entry) => {
+            const subject = entry.name ?? "hub";
+            const target = entry.agentId ? ` agent=${entry.agentId}` : "";
+            return `  - ${entry.at} ${entry.type}/${entry.action ?? "event"} ${subject}${target}${entry.hash ? ` hash=${entry.hash}` : ""}`;
+        }),
+    ]);
+    return 0;
+}

package/apps/cli/dist/commands/inventory.js

@@ -0,0 +1,259 @@
+import { writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { agentSkillSources, detectConflicts, effectiveSkillScope, loadHubConfig, mergeSkillMetas, resolveHubConfigPaths, scanSkills, selectPreferredSkill, sourceMappingToProvenance, } from "#skill-hub/core";
+import { expandUserPath } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runInventory(options) {
+    const config = resolveHubConfigPaths(options.configPath ? await loadHubConfig(options.configPath) : await loadHubConfig());
+    const scopeFilter = options.scopeFilter?.length ? new Set(options.scopeFilter) : null;
+    let agents = config.agents.filter((a) => a.enabled && (!scopeFilter || scopeFilter.has("user")));
+    if (options.agentFilter?.length) {
+        const set = new Set(options.agentFilter);
+        agents = agents.filter((a) => set.has(a.id));
+    }
+    const agentReports = [];
+    const sourceReports = [];
+    const all = [];
+    const sourcePresence = new Map();
+    for (const a of agents) {
+        const p = expandUserPath(a.skills_dir);
+        try {
+            const skills = await scanSkills(p, {
+                agentId: a.id,
+                source: p,
+                provenance: { scope: "user", sourceType: "local", sourceRef: p },
+                maxDepth: 4,
+            });
+            all.push(...skills);
+            agentReports.push({
+                id: a.id,
+                path: p,
+                exists: true,
+                count: skills.length,
+                skills: skills.map((s) => s.name),
+                scope: "user",
+            });
+        }
+        catch {
+            agentReports.push({
+                id: a.id,
+                path: p,
+                exists: false,
+                count: 0,
+                skills: [],
+                scope: "user",
+            });
+        }
+    }
+    let sources = agentSkillSources(config).filter((s) => s.enabled);
+    if (options.sourceFilter?.length) {
+        const wanted = new Set(options.sourceFilter);
+        sources = sources.filter((s) => wanted.has(s.id));
+    }
+    if (scopeFilter)
+        sources = sources.filter((s) => scopeFilter.has(s.scope));
+    for (const source of sources) {
+        const p = expandUserPath(source.path);
+        const provenance = sourceMappingToProvenance(source, p);
+        try {
+            const skills = await scanSkills(p, {
+                source: p,
+                provenance,
+                maxDepth: 5,
+            });
+            all.push(...skills);
+            for (const skill of skills) {
+                const set = sourcePresence.get(skill.name) ?? new Set();
+                set.add(source.id);
+                sourcePresence.set(skill.name, set);
+            }
+            sourceReports.push({
+                id: source.id,
+                path: p,
+                scope: source.scope,
+                source_type: source.source_type ?? "local",
+                source_ref: source.source_ref ?? p,
+                revision: source.revision,
+                status: source.status ?? "active",
+                overlay_of: source.overlay_of,
+                exists: true,
+                count: skills.length,
+                skills: skills.map((s) => s.name),
+            });
+        }
+        catch {
+            sourceReports.push({
+                id: source.id,
+                path: p,
+                scope: source.scope,
+                source_type: source.source_type ?? "local",
+                source_ref: source.source_ref ?? p,
+                revision: source.revision,
+                status: source.status ?? "active",
+                overlay_of: source.overlay_of,
+                exists: false,
+                count: 0,
+                skills: [],
+            });
+        }
+    }
+    const merged = mergeSkillMetas(all);
+    const conflicts = detectConflicts(all);
+    const unionNames = new Set(merged.map((s) => s.name));
+    const effective = new Map();
+    const byName = new Map();
+    for (const skill of all) {
+        const list = byName.get(skill.name) ?? [];
+        list.push(skill);
+        byName.set(skill.name, list);
+    }
+    for (const [name, list] of byName) {
+        const preferred = selectPreferredSkill(list);
+        if (preferred)
+            effective.set(name, preferred);
+    }
+    // 仅单端
+    const presence = new Map();
+    for (const s of all) {
+        const set = presence.get(s.name) ?? new Set();
+        for (const id of s.agentsPresent ?? [])
+            set.add(id);
+        // 若 scan 未标 agent，尝试从报告反推
+        presence.set(s.name, set);
+    }
+    for (const rep of agentReports) {
+        for (const name of rep.skills) {
+            const set = presence.get(name) ?? new Set();
+            set.add(rep.id);
+            presence.set(name, set);
+        }
+    }
+    const only = {};
+    for (const [name, agentsSet] of presence) {
+        if (agentsSet.size === 1) {
+            const id = [...agentsSet][0];
+            only[id] = only[id] ?? [];
+            only[id].push(name);
+        }
+    }
+    for (const k of Object.keys(only)) {
+        only[k].sort();
+    }
+    const onlySources = {};
+    for (const [name, sourceIds] of sourcePresence) {
+        if (sourceIds.size === 1) {
+            const id = [...sourceIds][0];
+            onlySources[id] = onlySources[id] ?? [];
+            onlySources[id].push(name);
+        }
+    }
+    for (const k of Object.keys(onlySources))
+        onlySources[k].sort();
+    const scopeCounts = {
+        user: 0,
+        workspace: 0,
+        project: 0,
+    };
+    for (const skill of effective.values()) {
+        scopeCounts[effectiveSkillScope(skill)] += 1;
+    }
+    // 两两交集规模
+    const overlaps = [];
+    for (let i = 0; i < agentReports.length; i += 1) {
+        for (let j = i + 1; j < agentReports.length; j += 1) {
+            const A = new Set(agentReports[i].skills);
+            const B = agentReports[j].skills;
+            let c = 0;
+            for (const n of B)
+                if (A.has(n))
+                    c += 1;
+            overlaps.push({
+                a: agentReports[i].id,
+                b: agentReports[j].id,
+                count: c,
+            });
+        }
+    }
+    const result = {
+        generatedAt: new Date().toISOString(),
+        agents: agentReports.map(({ id, path: p, exists, count }) => ({
+            id,
+            path: p,
+            exists,
+            count,
+            scope: "user",
+        })),
+        sources: sourceReports,
+        scope_filter: options.scopeFilter ?? null,
+        scope_counts: scopeCounts,
+        union_count: unionNames.size,
+        total_scanned_entries: all.length,
+        overlaps,
+        only,
+        only_sources: onlySources,
+        effective_skills: [...effective.values()]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((s) => ({
+            name: s.name,
+            path: s.path,
+            hash: s.hash,
+            scope: effectiveSkillScope(s),
+            source: s.source ?? null,
+            provenance: s.provenance ?? null,
+        })),
+        conflicts: conflicts.map((c) => ({
+            name: c.name,
+            variants: c.variants,
+            winner: c.winner ?? null,
+            winner_reason: c.winnerReason ?? null,
+        })),
+    };
+    if (options.outPath) {
+        const abs = path.resolve(options.outPath);
+        await mkdir(path.dirname(abs), { recursive: true });
+        if (abs.endsWith(".json")) {
+            await writeFile(abs, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+        }
+        else {
+            const md = [
+                `# skill-hub inventory`,
+                ``,
+                `- generatedAt: ${result.generatedAt}`,
+                `- union_count: ${result.union_count}`,
+                `- sources: ${result.sources.length}`,
+                `- conflicts: ${result.conflicts.length}`,
+                ``,
+                `## Agents`,
+                ...result.agents.map((a) => `- **${a.id}** [user]: ${a.count} @ \`${a.path}\` (${a.exists ? "ok" : "missing"})`),
+                ``,
+                `## Skill Sources`,
+                result.sources.length === 0
+                    ? `- (none configured)`
+                    : result.sources
+                        .map((s) => `- **${s.id}** [${s.scope}]: ${s.count} @ \`${s.path}\` (${s.exists ? "ok" : "missing"})`)
+                        .join("\n"),
+                ``,
+                `## Conflicts`,
+                result.conflicts.length === 0
+                    ? `- (none)`
+                    : result.conflicts
+                        .map((c) => `- ${c.name} (${c.variants.length} variants; winner=${c.winner?.path ?? "?"})\n  ${c.winner_reason ?? ""}`)
+                        .join("\n"),
+                ``,
+            ].join("\n");
+            await writeFile(abs, md, "utf8");
+        }
+    }
+    if (options.json) {
+        printJson(result);
+    }
+    else {
+        printLines([
+            `inventory  union=${result.union_count}  entries=${result.total_scanned_entries}  conflicts=${result.conflicts.length}`,
+            ...result.agents.map((a) => `  ${a.id.padEnd(12)} ${String(a.count).padStart(4)}  ${a.path}`),
+            ...result.sources.map((s) => `  source:${s.id.padEnd(8)} ${s.scope.padEnd(9)} ${String(s.count).padStart(4)}  ${s.path}`),
+            options.outPath ? `written: ${options.outPath}` : "",
+        ].filter(Boolean));
+    }
+    return 0;
+}

package/apps/cli/dist/commands/manage.js

@@ -0,0 +1,149 @@
+import { lstat, stat } from "node:fs/promises";
+import { appendHistoryBatch, createEmptyCatalog, loadHubConfig, manageSkills, readCatalog, resolveHubConfigPaths, upsertSkills, writeCatalog, } from "#skill-hub/core";
+import { SkillHubError, getDefaultHubHome, hubLayout } from "#skill-hub/shared";
+import { runIndex } from "./index-cmd.js";
+import { printJson, printLines } from "../output.js";
+export async function runManage(options) {
+    if (options.action === "check-updates" && (options.apply || options.yes)) {
+        throw new SkillHubError({
+            code: "E_CONFIG",
+            message: "check-updates 是只读检查，不接受 --apply 或 --yes",
+        });
+    }
+    const dryRun = options.dryRun || !options.apply || options.action === "list";
+    if (!dryRun && !options.yes)
+        throw new SkillHubError({
+            code: "E_CONFIG",
+            message: "写入 Hub 需要 --apply --yes；先运行默认预览",
+        });
+    const layout = hubLayout(getDefaultHubHome());
+    const config = resolveHubConfigPaths(await loadHubConfig(options.configPath));
+    // 在任何文件写入前检查 catalog；损坏文件不能被当作空库覆盖。
+    let catalog = createEmptyCatalog();
+    if (options.action !== "list" && options.action !== "check-updates") {
+        const exists = await lstat(layout.catalog).catch((err) => {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        });
+        if (exists)
+            catalog = await readCatalog(layout.catalog);
+    }
+    let overlayOf;
+    if (options.overlayOf !== undefined) {
+        overlayOf = options.overlayOf.trim();
+        if (!overlayOf) {
+            throw new SkillHubError({
+                code: "E_CONFIG",
+                message: "--overlay-of 需要 base Skill 名称",
+            });
+        }
+        if (options.action !== "install" && options.action !== "adopt") {
+            throw new SkillHubError({
+                code: "E_CONFIG",
+                message: "--overlay-of 仅适用于 install/adopt",
+            });
+        }
+        const base = catalog.skills[overlayOf];
+        if (!base) {
+            throw new SkillHubError({
+                code: "E_NOT_FOUND",
+                message: `overlay base 不在当前 catalog 中: ${overlayOf}`,
+                details: { overlayOf },
+            });
+        }
+        try {
+            if (!(await stat(base.path)).isDirectory()) {
+                throw new SkillHubError({
+                    code: "E_PATH",
+                    message: `overlay base 路径不是目录: ${overlayOf}`,
+                    details: { name: overlayOf, path: base.path },
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof SkillHubError)
+                throw err;
+            if (err.code === "ENOENT") {
+                throw new SkillHubError({
+                    code: "E_NOT_FOUND",
+                    message: `overlay base 路径不存在: ${overlayOf}`,
+                    details: { name: overlayOf, path: base.path },
+                    cause: err,
+                });
+            }
+            throw err;
+        }
+    }
+    const result = await manageSkills({
+        action: options.action,
+        source: options.source,
+        names: options.names,
+        ref: options.ref,
+        overlayOf,
+        backupPath: options.backupPath,
+        planToken: options.planToken,
+        canonicalDir: config.canonical_dir,
+        stateDir: layout.home,
+        dryRun,
+    });
+    if (!dryRun && result.skills.length) {
+        const next = upsertSkills(catalog, result.skills).catalog;
+        await writeCatalog(layout.catalog, next);
+        await appendHistoryBatch(layout.history, result.items
+            .filter((i) => i.status === "applied")
+            .map((item) => ({
+            at: new Date().toISOString(),
+            type: next.skills[item.name]?.provenance?.overlayOf
+                ? "overlay"
+                : "ingest",
+            name: item.name,
+            action: item.action,
+            source: item.source,
+            path: next.skills[item.name]?.path,
+            hash: next.skills[item.name]?.hash,
+            detail: { managed: true, backupPath: item.backupPath },
+        })));
+        await runIndex({ json: true, rebuild: false, configPath: options.configPath, quiet: true });
+    }
+    if (options.json)
+        printJson({
+            ...result,
+            indexUpdated: !dryRun && result.skills.length > 0,
+            next: options.action === "list"
+                ? null
+                : options.action === "check-updates"
+                    ? "仅检查 managed 来源锁；Hub 和 Agent 未写入。未知状态不代表已是最新。"
+                    : dryRun
+                        ? options.action === "update" || options.action === "migrate-source"
+                            ? "仅生成预览；核对差异及来源后，用 --plan-token <planToken> --apply --yes 确认同一计划。"
+                            : "仅生成预览；Hub 和 Agent 未写入。核对后才可使用 --apply --yes。"
+                        : "Hub 处理完成；Agent 可通过 MCP 按需搜索并精确读取 Skill，无需默认 sync",
+        });
+    else {
+        const descriptions = new Map(result.skills.map((skill) => [skill.name, skill.description]));
+        printLines([
+            `${options.action} ${dryRun ? "(dry-run / 只读)" : "完成"}`,
+            ...result.items.map((item) => `  ${item.action} ${item.name}${descriptions.get(item.name) ? ` — ${descriptions.get(item.name)}` : ""} [${item.status}]${item.localStatus ? ` local=${item.localStatus} upstream=${item.upstreamStatus} update=${item.updateAvailable ?? "unknown"}` : ""}${item.message ? ` ${item.message}` : ""}${item.backupPath ? ` backup=${item.backupPath}` : ""}`),
+            ...result.items.flatMap((item) => (item.changes ?? []).map((change) => `    ${change.change} ${change.path} (${change.before?.kind ?? "absent"} → ${change.after?.kind ?? "absent"})`)),
+            ...result.items.flatMap((item) => item.previousSource && item.nextSource
+                ? [
+                    `    来源迁移: ${JSON.stringify(item.previousSource)} → ${JSON.stringify(item.nextSource)}`,
+                ]
+                : []),
+            ...(result.planToken
+                ? [
+                    `更新确认指纹: ${result.planToken}`,
+                    ...(dryRun
+                        ? ["确认写入需 --plan-token <指纹> --apply --yes；token 不代替用户授权"]
+                        : []),
+                ]
+                : []),
+            ...(result.issues ?? []).map((issue) => `  issue [${issue.phase}/${issue.code}]${issue.name ? ` ${issue.name}` : ""}${issue.path ? ` ${issue.path}` : ""}: ${issue.message}${issue.hint ? `；${issue.hint}` : ""}`),
+            ...(result.complete !== undefined ? [`检查完整: ${result.complete}`] : []),
+            `来源锁: ${result.lockPath}`,
+            ...(!dryRun ? ["catalog/index 已更新；可通过 MCP 按需加载，无需默认 sync"] : []),
+        ]);
+    }
+    return result.complete === false ? 3 : 0;
+}