@zhangheteng/skill-hub 0.0.0-stage → 0.2.0

package/packages/router/dist/usage.js

@@ -0,0 +1,76 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { appendUsage, estimateContext, } from "#skill-hub/core";
+import { SkillHubError } from "#skill-hub/shared";
+const scope = new AsyncLocalStorage();
+function enabled() {
+    return Boolean(process.env.SKILL_HUB_USAGE_LOG) && scope.getStore()?.record !== false;
+}
+export function withUsageScope(origin, call, record = true) {
+    return scope.run({ origin, record }, call);
+}
+async function record(event) {
+    const file = process.env.SKILL_HUB_USAGE_LOG;
+    if (!file || scope.getStore()?.record === false)
+        return;
+    try {
+        await appendUsage(file, {
+            ...event,
+            version: 1,
+            at: new Date().toISOString(),
+            origin: scope.getStore()?.origin ?? "library",
+        });
+    }
+    catch {
+        // Deliberately preserve the original operation; never print the private path or error detail.
+        console.error("[skill-hub usage] E_USAGE_WRITE: 本次记录失败，请检查日志路径、格式、权限或大小；原调用结果不受影响。");
+    }
+}
+export async function observeRead(name, call) {
+    if (!enabled())
+        return call();
+    let result;
+    try {
+        result = await call();
+    }
+    catch (error) {
+        const safeName = typeof name === "string" && /^[a-zA-Z0-9._-]{1,256}$/.test(name) ? name : undefined;
+        await record({
+            operation: "read",
+            name: safeName,
+            success: false,
+            errorCode: error instanceof SkillHubError ? error.code : "E_INTERNAL",
+        });
+        throw error;
+    }
+    await record({
+        operation: "read",
+        success: true,
+        name: result.name,
+        kind: result.file.toLowerCase() === "skill.md" ? "body" : "attachment",
+        phase: result.offset === 0 ? "initial" : "continuation",
+        content: estimateContext(result.body),
+    });
+    return result;
+}
+export async function observeSearch(call) {
+    if (!enabled())
+        return call();
+    let result;
+    try {
+        result = await call();
+    }
+    catch (error) {
+        await record({
+            operation: "search",
+            success: false,
+            errorCode: error instanceof SkillHubError ? error.code : "E_INTERNAL",
+        });
+        throw error;
+    }
+    await record({
+        operation: "search",
+        success: true,
+        candidates: result.results.map((r) => r.name),
+    });
+    return result;
+}

package/packages/shared/dist/constants.js

@@ -0,0 +1,14 @@
+/** skill-hub 库/CLI 版本号（与根 package.json 对齐，发版时同步）。 */
+export const SKILL_HUB_VERSION = "0.2.0";
+/** 默认用户运行时目录名（位于 `$HOME` 下）。 */
+export const DEFAULT_HUB_DIRNAME = ".skill-hub";
+/** 环境变量：覆盖 hub 根目录。 */
+export const ENV_HUB_HOME = "SKILL_HUB_HOME";
+/** 环境变量：覆盖配置文件路径。 */
+export const ENV_HUB_CONFIG = "SKILL_HUB_CONFIG";
+/** 环境变量：日志级别。 */
+export const ENV_LOG_LEVEL = "SKILL_HUB_LOG_LEVEL";
+/** 默认 catalog 文件名。 */
+export const CATALOG_FILENAME = "catalog.json";
+/** 默认配置文件名。 */
+export const CONFIG_FILENAME = "config.yaml";

package/packages/shared/dist/errors.js

@@ -0,0 +1,90 @@
+/**
+ * 统一错误码与 SkillHubError。
+ * 对齐 `docs/architecture/API.md` §5。
+ */
+/** API 约定的错误码集合。 */
+export const ERROR_CODES = [
+    "E_CONFIG",
+    "E_PATH",
+    "E_PARSE",
+    "E_CONFLICT",
+    "E_INDEX",
+    "E_SYNC",
+    "E_BACKUP",
+    "E_NOT_FOUND",
+    "E_INTERNAL",
+];
+const EXIT_BY_CODE = {
+    E_CONFIG: 3,
+    E_PATH: 3,
+    E_PARSE: 1,
+    E_CONFLICT: 2,
+    E_INDEX: 1,
+    E_SYNC: 1,
+    E_BACKUP: 1,
+    E_NOT_FOUND: 1,
+    E_INTERNAL: 1,
+};
+/**
+ * 可分类业务错误：禁止静默吞掉，CLI/MCP 应打印 `code` + 可操作信息。
+ */
+export class SkillHubError extends Error {
+    code;
+    details;
+    exitCode;
+    cause;
+    constructor(options) {
+        super(options.message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "SkillHubError";
+        this.code = options.code;
+        this.details = options.details;
+        this.exitCode = options.exitCode ?? EXIT_BY_CODE[options.code];
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /** 人类可读：一行摘要。 */
+    toDisplayString() {
+        const detail = this.details && Object.keys(this.details).length > 0
+            ? ` ${JSON.stringify(this.details)}`
+            : "";
+        return `[${this.code}] ${this.message}${detail}`;
+    }
+    /** 结构化序列化，便于 `--json`。 */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            exitCode: this.exitCode,
+            details: this.details ?? null,
+        };
+    }
+}
+/** 按错误码创建错误的快捷工厂。 */
+export function createError(code, message, details, cause) {
+    return new SkillHubError({ code, message, details, cause });
+}
+/** 将任意抛出值规范为 SkillHubError（未知错误 → E_INTERNAL）。 */
+export function toSkillHubError(err, fallbackMessage = "内部错误") {
+    if (err instanceof SkillHubError) {
+        return err;
+    }
+    if (err instanceof Error) {
+        return new SkillHubError({
+            code: "E_INTERNAL",
+            message: err.message || fallbackMessage,
+            cause: err,
+        });
+    }
+    return new SkillHubError({
+        code: "E_INTERNAL",
+        message: fallbackMessage,
+        details: { value: String(err) },
+    });
+}
+/** 错误码 → CLI 退出码。 */
+export function exitCodeFor(code) {
+    return EXIT_BY_CODE[code];
+}
+export function isErrorCode(value) {
+    return ERROR_CODES.includes(value);
+}

package/packages/shared/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @skill-hub/shared — 公共常量、错误码、路径、日志与共享类型。
+ */
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./paths.js";
+export * from "./logger.js";
+export * from "./types.js";
+/**
+ * @deprecated 脚手架占位，保留以免破坏早期烟雾引用；新代码请勿依赖。
+ */
+export function sharedPlaceholder() {
+    return "skill-hub/shared";
+}

package/packages/shared/dist/logger.js

@@ -0,0 +1,95 @@
+/**
+ * 轻量日志：人类可读 + 可选 JSON 行。
+ * 级别可由 `SKILL_HUB_LOG_LEVEL` 或构造参数控制。
+ */
+import { ENV_LOG_LEVEL } from "./constants.js";
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function parseLogLevel(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const v = raw.trim().toLowerCase();
+    if (v === "debug" || v === "info" || v === "warn" || v === "error") {
+        return v;
+    }
+    return fallback;
+}
+function formatHuman(level, name, message, fields) {
+    const base = `${level.toUpperCase().padEnd(5)} [${name}] ${message}`;
+    if (!fields || Object.keys(fields).length === 0) {
+        return `${base}\n`;
+    }
+    return `${base} ${JSON.stringify(fields)}\n`;
+}
+function formatJson(level, name, message, fields, ts) {
+    return `${JSON.stringify({
+        ts,
+        level,
+        name,
+        message,
+        ...(fields ?? {}),
+    })}\n`;
+}
+class LoggerImpl {
+    level;
+    json;
+    name;
+    baseFields;
+    stdout;
+    stderr;
+    now;
+    constructor(options = {}, baseFields = {}) {
+        this.level = options.level ?? parseLogLevel(process.env[ENV_LOG_LEVEL], "info");
+        this.json = options.json ?? false;
+        this.name = options.name ?? "skill-hub";
+        this.baseFields = baseFields;
+        this.stdout = options.stdout ?? process.stdout;
+        this.stderr = options.stderr ?? process.stderr;
+        this.now = options.now ?? (() => new Date());
+    }
+    enabled(level) {
+        return LEVEL_ORDER[level] >= LEVEL_ORDER[this.level];
+    }
+    write(level, message, fields) {
+        if (!this.enabled(level))
+            return;
+        const merged = { ...this.baseFields, ...fields };
+        const stream = level === "error" || level === "warn" ? this.stderr : this.stdout;
+        const line = this.json
+            ? formatJson(level, this.name, message, merged, this.now().toISOString())
+            : formatHuman(level, this.name, message, merged);
+        stream.write(line);
+    }
+    debug(message, fields) {
+        this.write("debug", message, fields);
+    }
+    info(message, fields) {
+        this.write("info", message, fields);
+    }
+    warn(message, fields) {
+        this.write("warn", message, fields);
+    }
+    error(message, fields) {
+        this.write("error", message, fields);
+    }
+    child(fields) {
+        return new LoggerImpl({
+            level: this.level,
+            json: this.json,
+            name: this.name,
+            stdout: this.stdout,
+            stderr: this.stderr,
+            now: this.now,
+        }, { ...this.baseFields, ...fields });
+    }
+}
+/** 创建 logger 实例。 */
+export function createLogger(options) {
+    return new LoggerImpl(options);
+}
+/** 进程级默认 logger（惰性按需可再建）。 */
+export const defaultLogger = createLogger();

package/packages/shared/dist/paths.js

@@ -0,0 +1,118 @@
+/**
+ * 路径展开与规范化。
+ * 原则：写 symlink / 配置落地前一律转为绝对路径。
+ */
+import { homedir } from "node:os";
+import path from "node:path";
+import { CATALOG_FILENAME, CONFIG_FILENAME, DEFAULT_HUB_DIRNAME, ENV_HUB_CONFIG, ENV_HUB_HOME, } from "./constants.js";
+import { SkillHubError } from "./errors.js";
+/**
+ * 展开 `~` / `~/...` 为绝对 home 路径，再 `path.resolve`。
+ * - 空串 → E_PATH
+ * - 不自动检查存在性（存在性由调用方 fs 层判断）
+ */
+export function expandUserPath(input, home = homedir()) {
+    const raw = input.trim();
+    if (!raw) {
+        throw new SkillHubError({
+            code: "E_PATH",
+            message: "路径不能为空",
+        });
+    }
+    let expanded = raw;
+    if (raw === "~") {
+        expanded = home;
+    }
+    else if (raw.startsWith("~/") || raw.startsWith("~\\")) {
+        expanded = path.join(home, raw.slice(2));
+    }
+    return path.resolve(expanded);
+}
+/**
+ * 确保得到绝对路径：相对路径相对 `cwd`（默认 process.cwd()）。
+ * 若含 `~`，先 expand。
+ */
+export function resolveAbsolutePath(input, options) {
+    const home = options?.home ?? homedir();
+    const cwd = options?.cwd ?? process.cwd();
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new SkillHubError({
+            code: "E_PATH",
+            message: "路径不能为空",
+        });
+    }
+    if (trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+        return expandUserPath(trimmed, home);
+    }
+    if (path.isAbsolute(trimmed)) {
+        return path.normalize(trimmed);
+    }
+    return path.resolve(cwd, trimmed);
+}
+/** 默认 `~/.skill-hub`，可被 `SKILL_HUB_HOME` 覆盖。 */
+export function getDefaultHubHome(env = process.env) {
+    const override = env[ENV_HUB_HOME]?.trim();
+    if (override) {
+        return expandUserPath(override);
+    }
+    return path.join(homedir(), DEFAULT_HUB_DIRNAME);
+}
+/** 默认配置路径：`SKILL_HUB_CONFIG` 或 `$HUB/config.yaml`。 */
+export function getDefaultConfigPath(env = process.env) {
+    const override = env[ENV_HUB_CONFIG]?.trim();
+    if (override) {
+        return expandUserPath(override);
+    }
+    return path.join(getDefaultHubHome(env), CONFIG_FILENAME);
+}
+/** hub 子路径约定。 */
+export function hubLayout(hubHome = getDefaultHubHome()) {
+    const home = expandUserPath(hubHome);
+    return {
+        home,
+        skills: path.join(home, "skills"),
+        index: path.join(home, "index"),
+        backups: path.join(home, "backups"),
+        config: path.join(home, CONFIG_FILENAME),
+        catalog: path.join(home, CATALOG_FILENAME),
+        history: path.join(home, "history.jsonl"),
+    };
+}
+/**
+ * Skill 名称规范化（DATA_MODEL §3）：
+ * 1. trim + lower case
+ * 2. 空白 → `-`
+ * 3. 仅保留 `[a-z0-9._-]`，其余剔除
+ * 4. 折叠连续 `-`，去掉首尾 `-`
+ * 5. 空名 → E_PARSE
+ */
+export function normalizeSkillName(raw) {
+    const lowered = raw.trim().toLowerCase();
+    if (!lowered) {
+        throw new SkillHubError({
+            code: "E_PARSE",
+            message: "skill 名称不能为空",
+        });
+    }
+    const spaced = lowered.replace(/[\s_]+/g, "-");
+    const cleaned = spaced
+        .replace(/[^a-z0-9._-]+/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (!cleaned || cleaned === "." || cleaned === "..") {
+        throw new SkillHubError({
+            code: "E_PARSE",
+            message: "skill 名称规范化后为空",
+            details: { raw },
+        });
+    }
+    return cleaned;
+}
+/** 判断路径是否落在 `root` 之下（解析后的绝对路径）。 */
+export function isPathInside(child, root) {
+    const absChild = resolveAbsolutePath(child);
+    const absRoot = resolveAbsolutePath(root);
+    const rel = path.relative(absRoot, absChild);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}

package/packages/shared/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * 跨包共享的基础类型（配置摘要、结果外壳等）。
+ * 领域实体（SkillMeta 等）以 core 为主；此处放配置与 IO 契约碎片。
+ */
+export function ok(data) {
+    return { ok: true, data };
+}
+export function err(code, message, details) {
+    return details === undefined
+        ? { ok: false, code, message }
+        : { ok: false, code, message, details };
+}

package/packages/sync/dist/apply.js

@@ -0,0 +1,227 @@
+import { lstat, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { SkillHubError } from "#skill-hub/shared";
+import { assertPathAbsent, atomicSymlink, copyPathToEmpty, movePathToEmpty, uniqueSiblingPath, } from "./fs-utils.js";
+import { assertSafeSkillName, inspectProjectionIntegrity } from "./integrity.js";
+/**
+ * 执行 sync plan：symlink 或 copy 模式的 create / update / replace。
+ * conflict / noop / skipped 跳过；create 动作只接受仍不存在的目标。
+ */
+export async function applySync(plan, options = {}) {
+    const dryRun = options.dryRun === true;
+    const createOnly = options.createOnly === true;
+    const results = [];
+    let applied = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (const item of plan.items) {
+        if (item.action === "noop" || item.action === "conflict" || item.action === "skipped") {
+            results.push({ ...item, result: "skipped" });
+            skipped += 1;
+            continue;
+        }
+        if (createOnly &&
+            (item.action === "update_symlink" ||
+                item.action === "replace_real" ||
+                item.action === "update_copy" ||
+                item.action === "replace_real_copy")) {
+            results.push({
+                ...item,
+                result: "skipped",
+                detail: item.detail ?? `create-only: 跳过 ${item.action}`,
+            });
+            skipped += 1;
+            continue;
+        }
+        if (!isWritableAction(item.action)) {
+            results.push({ ...item, result: "skipped" });
+            skipped += 1;
+            continue;
+        }
+        if (isReplaceAction(item.action) && !dryRun && !options.replaceStashDir) {
+            results.push({
+                ...item,
+                result: "failed",
+                error: "replace_real/replace_real_copy 需要 replaceStashDir（CLI 由 --backup-dir/replaced-real 提供）",
+            });
+            failed += 1;
+            continue;
+        }
+        if (dryRun) {
+            results.push({ ...item, result: "applied", detail: item.detail ?? "dry-run apply" });
+            applied += 1;
+            continue;
+        }
+        try {
+            await applyOne(item, options.replaceStashDir, plan.canonicalDir);
+            results.push({ ...item, result: "applied" });
+            applied += 1;
+        }
+        catch (err) {
+            results.push({
+                ...item,
+                result: "failed",
+                error: err instanceof Error ? err.message : String(err),
+            });
+            failed += 1;
+        }
+    }
+    return { dryRun, applied, skipped, failed, items: results };
+}
+async function applyOne(item, replaceStashDir, canonicalDir) {
+    const copyMode = item.action === "create_copy" ||
+        item.action === "update_copy" ||
+        item.action === "replace_real_copy";
+    const integrity = await inspectProjectionIntegrity({
+        canonicalDir,
+        source: item.source,
+        target: item.target,
+        skillName: item.skillName,
+        expectedSkillHash: item.expectedSkillHash,
+        requireTreeHash: copyMode,
+    });
+    const safeItem = { ...item, source: integrity.source, target: integrity.target };
+    if (isReplaceAction(safeItem.action)) {
+        if (!replaceStashDir) {
+            throw new SkillHubError({
+                code: "E_SYNC",
+                message: "replace_real/replace_real_copy 缺少 stash 目录",
+                details: { target: safeItem.target },
+            });
+        }
+        await replaceRealProjection(safeItem, replaceStashDir);
+        return;
+    }
+    if (safeItem.action === "create_copy" || safeItem.action === "create_symlink") {
+        // 两个 helper 都会二次 lstat，并且只把 ENOENT 视作可创建。
+        await createProjection(safeItem);
+        return;
+    }
+    if (safeItem.action === "update_copy" || safeItem.action === "update_symlink") {
+        await replaceSymlinkProjection(safeItem);
+        return;
+    }
+    throw new SkillHubError({
+        code: "E_SYNC",
+        message: `未知同步 action: ${safeItem.action}`,
+        details: { action: safeItem.action, target: safeItem.target },
+    });
+}
+async function replaceRealProjection(item, replaceStashDir) {
+    const targetInfo = await lstat(item.target);
+    if (targetInfo.isSymbolicLink()) {
+        throw new SkillHubError({
+            code: "E_SYNC",
+            message: `replace_real 目标是 symlink，请使用 update action: ${item.target}`,
+            details: { target: item.target },
+        });
+    }
+    if (!targetInfo.isDirectory() && !targetInfo.isFile()) {
+        throw new SkillHubError({
+            code: "E_SYNC",
+            message: `replace_real 目标类型不支持: ${item.target}`,
+            details: { target: item.target },
+        });
+    }
+    assertSafeStashSegment(item.agentId, "agent id");
+    assertSafeSkillName(item.skillName);
+    const stashPath = path.join(replaceStashDir, item.agentId, item.skillName);
+    // 不覆盖任何既存 stash（包括坏链）；保留可追溯历史备份。
+    await assertPathAbsent(stashPath);
+    await movePathToEmpty(item.target, stashPath);
+    try {
+        await createProjection(item);
+    }
+    catch (projectionError) {
+        try {
+            // 投影未创建时原目标必须回到原路径；若此时有第三方新建 target，宁可失败也不覆盖。
+            await movePathToEmpty(stashPath, item.target);
+        }
+        catch (restoreError) {
+            throw new SkillHubError({
+                code: "E_SYNC",
+                message: `创建投影失败，且无法恢复原目标: ${item.target}`,
+                details: { target: item.target, stashPath },
+                cause: new AggregateError([projectionError, restoreError]),
+            });
+        }
+        throw projectionError;
+    }
+}
+/** update 只替换计划中已观察到的 symlink；失败时恢复旧链。 */
+async function replaceSymlinkProjection(item) {
+    const targetInfo = await lstat(item.target);
+    if (!targetInfo.isSymbolicLink()) {
+        throw new SkillHubError({
+            code: "E_SYNC",
+            message: `目标不再是 symlink，拒绝 update: ${item.target}`,
+            details: { target: item.target },
+        });
+    }
+    const rollbackPath = uniqueSiblingPath(item.target, "rollback");
+    await assertPathAbsent(rollbackPath);
+    await rename(item.target, rollbackPath);
+    try {
+        await createProjection(item);
+    }
+    catch (projectionError) {
+        try {
+            await assertPathAbsent(item.target);
+            await rename(rollbackPath, item.target);
+        }
+        catch (restoreError) {
+            throw new SkillHubError({
+                code: "E_SYNC",
+                message: `更新投影失败，且无法恢复旧 symlink: ${item.target}`,
+                details: { target: item.target, rollbackPath },
+                cause: new AggregateError([projectionError, restoreError]),
+            });
+        }
+        throw projectionError;
+    }
+    try {
+        await rm(rollbackPath, { force: false });
+    }
+    catch (err) {
+        throw new SkillHubError({
+            code: "E_SYNC",
+            message: `投影已更新，但无法清理旧 symlink: ${rollbackPath}`,
+            details: { target: item.target, rollbackPath },
+            cause: err,
+        });
+    }
+}
+async function createProjection(item) {
+    if (item.action === "create_copy" ||
+        item.action === "update_copy" ||
+        item.action === "replace_real_copy") {
+        await copyPathToEmpty(item.source, item.target);
+        return;
+    }
+    await atomicSymlink(item.source, item.target);
+}
+function isWritableAction(action) {
+    return (action === "create_symlink" ||
+        action === "update_symlink" ||
+        action === "replace_real" ||
+        action === "create_copy" ||
+        action === "update_copy" ||
+        action === "replace_real_copy");
+}
+function isReplaceAction(action) {
+    return action === "replace_real" || action === "replace_real_copy";
+}
+function assertSafeStashSegment(value, label) {
+    if (!value ||
+        value === "." ||
+        value === ".." ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        value.includes("\0")) {
+        throw new SkillHubError({
+            code: "E_SYNC",
+            message: `非法 ${label}，拒绝构造 stash 路径: ${JSON.stringify(value)}`,
+            details: { value, label },
+        });
+    }
+}