@ats-cx/cx-cli 0.1.0

package/dist/skills.js

@@ -0,0 +1,430 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, realpathSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isApmConfigured, loadConfig, machineConfigDir, SENTENCE } from "@ats-cx/cx-core";
+import { jsonOut } from "./output.js";
+export const SKILLS_INSTALL_HELP = `Usage: cx-cli skills install
+
+把包内 skills/<name> 软链进本机 Agent（两段链）:
+  <包根>/skills/<name>     -> ~/.agents/skills/<name>    中央 skills 库；Codex 直接读这里
+  ~/.agents/skills/<name>  -> ~/.claude/skills/<name>    仅当 ~/.claude/ 存在；Claude Code 只读这里
+并创建机器级覆盖目录 ~/.config/cx-cli/（遵 $XDG_CONFIG_HOME），缺 apm-provider.local.json 则落骨架（已有不覆盖）。
+
+幂等: 已指向当前包的链不动；指向别处或悬空的软链重指（输出 updated）；目标是真实文件/目录则跳过并警告，不删。
+只支持 npm 全局安装（npm i -g @ats-cx/cx-cli）与维护者的 pnpm link；npx 缓存与 pnpm add -g 下拒绝（exit 1）。
+装好后 Agent 无需重启；包升级后新增的 skill 需重跑本命令；更名 / 删除的旧链由本命令自动清理（pruned）。
+
+输出:
+  { packageRoot, packageVersion, centralDir, agents, skills, created, updated, skipped, pruned, configDir, warnings, hint }`;
+export const SKILLS_STATUS_HELP = `Usage: cx-cli skills status
+
+检查包内每个 skill 的两段链（中央库 ~/.agents/skills/<name>；~/.claude/ 存在时再查 ~/.claude/skills/<name>）
+与机器级覆盖目录 ~/.config/cx-cli/ 是否就绪。链状态: linked / stale（指向别处）/ dangling（悬空）/ missing / occupied（被真实目录占用）。
+全部 linked 才 ok；否则 exit 1 并在 issues 列出。apm 未配置只进 hint，不影响 ok。
+
+输出:
+  { ok, packageRoot, packageVersion, centralDir, agents, skills: [{ name, central, claude? }], orphans, issues, configDir, hint }`;
+export const SKILLS_UNINSTALL_HELP = `Usage: cx-cli skills uninstall
+
+解除本包的 skills 链接: 删 ~/.claude/skills/<name>、~/.codex/skills/<name> 中指向中央库的软链，
+再删 ~/.agents/skills/<name> 中指向当前包或已悬空的软链。指向别处的软链与真实文件/目录一律不动（列入 skipped）。
+不动 ~/.config/cx-cli/。卸载顺序: 先本命令，再 npm rm -g @ats-cx/cx-cli。
+
+输出:
+  { packageRoot, packageVersion, removed, skipped: [{ path, reason }], warnings, hint }`;
+function skillInventory(packageRoot) {
+    const skillsDir = join(packageRoot, "skills");
+    const warnings = [];
+    const names = [];
+    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+        if (entry.name.startsWith(".") || !entry.isDirectory()) {
+            continue;
+        }
+        const skillFile = join(skillsDir, entry.name, "SKILL.md");
+        if (!existsSync(skillFile)) {
+            warnings.push(`跳过 ${join(skillsDir, entry.name)}：缺少 SKILL.md。`);
+            continue;
+        }
+        names.push(entry.name);
+    }
+    names.sort();
+    return { names, warnings };
+}
+function inspectLink(path, expected, mode) {
+    if (!existsSync(path)) {
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink()) {
+                return { path, state: "dangling", target: readlinkSync(path) };
+            }
+            return { path, state: "occupied" };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return { path, state: "missing" };
+            }
+            throw error;
+        }
+    }
+    const stat = lstatSync(path);
+    if (!stat.isSymbolicLink()) {
+        return { path, state: "occupied" };
+    }
+    const target = readlinkSync(path);
+    const resolvesTo = realpathSync(path);
+    const linked = mode === "realpath" ? resolvesTo === expected : target === expected;
+    return { path, state: linked ? "linked" : "stale", target, resolvesTo };
+}
+function symlinkTarget(path) {
+    try {
+        return lstatSync(path).isSymbolicLink() ? readlinkSync(path) : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+function directoryNames(path) {
+    if (!existsSync(path)) {
+        return [];
+    }
+    return readdirSync(path).sort();
+}
+function findOrphans(packageRoot, skillNames, home) {
+    const known = new Set(skillNames);
+    const centralDir = join(home, ".agents", "skills");
+    const packageSkillsPrefix = `${join(packageRoot, "skills")}${sep}`;
+    const centralOrphans = new Map();
+    for (const name of directoryNames(centralDir)) {
+        if (known.has(name)) {
+            continue;
+        }
+        const path = join(centralDir, name);
+        const target = symlinkTarget(path);
+        if (target?.startsWith(packageSkillsPrefix)) {
+            centralOrphans.set(name, { path, target });
+        }
+    }
+    const mountOrphans = [];
+    for (const mountDir of [join(home, ".claude", "skills"), join(home, ".codex", "skills")]) {
+        for (const name of directoryNames(mountDir)) {
+            if (known.has(name)) {
+                continue;
+            }
+            const path = join(mountDir, name);
+            const target = symlinkTarget(path);
+            const centralPath = join(centralDir, name);
+            if (target === centralPath && (centralOrphans.has(name) || !existsSync(path))) {
+                mountOrphans.push({ path, target });
+            }
+        }
+    }
+    return [...mountOrphans, ...centralOrphans.values()];
+}
+function machineApmStatus(packageRoot) {
+    const state = loadConfig(join(packageRoot, "config"), { source: "toolkit" }).apmProviderState;
+    return {
+        apmConfigured: isApmConfigured(state),
+        ...(state?.kind === "invalid" ? { apmError: state.error } : {}),
+    };
+}
+function ensurePeriod(sentence) {
+    return sentence.endsWith("。") ? sentence : `${sentence}。`;
+}
+function stateIssue(name, link) {
+    if (link.state === "linked") {
+        return null;
+    }
+    if (link.state === "missing") {
+        return `${name}: ${link.path} 缺失`;
+    }
+    if (link.state === "dangling") {
+        return `${name}: ${link.path} 悬空（目标 ${link.target ?? "未知"} 不存在）`;
+    }
+    if (link.state === "occupied") {
+        return `${name}: ${link.path} 被真实文件/目录占用`;
+    }
+    const destination = link.resolvesTo ?? link.target;
+    const skillSuffix = `${sep}skills${sep}${name}`;
+    const otherRoot = destination?.endsWith(skillSuffix)
+        ? destination.slice(0, -skillSuffix.length)
+        : destination ?? "未知位置";
+    return `${link.path} 指向另一份 cx-cli（${otherRoot}）：若那是旧安装，运行 cx-cli skills install 重指到当前这份；若想继续用那一份，nvm use 回安装它的 node 版本。`;
+}
+export function centralSkillsWarning(packageRoot) {
+    const resolvedRoot = realpathSync(resolve(packageRoot));
+    if (!existsSync(join(resolvedRoot, "skills"))) {
+        return null;
+    }
+    const inventory = skillInventory(resolvedRoot);
+    const centralDir = join(homedir(), ".agents", "skills");
+    const unlinked = inventory.names.filter(name => inspectLink(join(centralDir, name), join(resolvedRoot, "skills", name), "realpath").state !== "linked").length;
+    return unlinked === 0
+        ? null
+        : `skills 未安装到本机 Agent（${unlinked} 条链缺失/悬空/指向别处），运行 cx-cli skills install`;
+}
+export function runSkillsInstall(options) {
+    try {
+        const packageRoot = realpathSync(resolve(options.packageRoot));
+        if (packageRoot.includes("/_npx/") ||
+            packageRoot.includes("/.pnpm/") ||
+            /\/store\/v\d+\/links\//.test(packageRoot)) {
+            return jsonOut({
+                error: `当前 cx-cli 安装位置不支持 skills install：${packageRoot}`,
+                kind: "unsupported_install",
+                hint: "npm i -g @ats-cx/cx-cli",
+            }, 1);
+        }
+        const inventory = skillInventory(packageRoot);
+        const home = homedir();
+        const centralDir = join(home, ".agents", "skills");
+        const claudeDir = join(home, ".claude", "skills");
+        const agents = {
+            claude: existsSync(join(home, ".claude")),
+            codex: existsSync(join(home, ".codex")),
+        };
+        const created = [];
+        const updated = [];
+        const skipped = [];
+        const warnings = [...inventory.warnings];
+        mkdirSync(centralDir, { recursive: true });
+        if (agents.claude) {
+            mkdirSync(claudeDir, { recursive: true });
+        }
+        const orphans = findOrphans(packageRoot, inventory.names, home);
+        const pruned = orphans.map(orphan => {
+            unlinkSync(orphan.path);
+            return orphan.path;
+        });
+        for (const name of inventory.names) {
+            const skillDir = join(packageRoot, "skills", name);
+            const centralPath = join(centralDir, name);
+            const central = inspectLink(centralPath, skillDir, "realpath");
+            if (central.state === "missing") {
+                symlinkSync(skillDir, centralPath);
+                created.push(centralPath);
+            }
+            else if (central.state === "linked") {
+                skipped.push(centralPath);
+            }
+            else if (central.state === "stale" || central.state === "dangling") {
+                unlinkSync(centralPath);
+                symlinkSync(skillDir, centralPath);
+                updated.push({ path: centralPath, from: central.target ?? "" });
+            }
+            else {
+                warnings.push(`跳过 ${centralPath}：已存在同名真实文件/目录（非软链），请手动处理。`);
+                continue;
+            }
+            if (agents.claude) {
+                const claudePath = join(claudeDir, name);
+                const claude = inspectLink(claudePath, centralPath, "readlink");
+                if (claude.state === "missing") {
+                    symlinkSync(centralPath, claudePath);
+                    created.push(claudePath);
+                }
+                else if (claude.state === "linked") {
+                    skipped.push(claudePath);
+                }
+                else if (claude.state === "stale" || claude.state === "dangling") {
+                    unlinkSync(claudePath);
+                    symlinkSync(centralPath, claudePath);
+                    updated.push({ path: claudePath, from: claude.target ?? "" });
+                }
+                else {
+                    warnings.push(`跳过 ${claudePath}：已存在同名真实文件/目录（非软链），请手动处理。`);
+                }
+            }
+        }
+        const configDir = resolve(machineConfigDir());
+        const configPath = join(configDir, "apm-provider.local.json");
+        const configDirExisted = existsSync(configDir);
+        mkdirSync(configDir, { recursive: true });
+        const configExisted = existsSync(configPath);
+        if (!configExisted) {
+            writeFileSync(configPath, `${JSON.stringify({ baseUrl: "", defaults: { host: "" } }, null, 2)}\n`);
+        }
+        const apm = machineApmStatus(packageRoot);
+        const hintParts = ["skills 已链接，Agent 无需重启。"];
+        if (!agents.claude) {
+            hintParts.push("未探测到 Claude Code（~/.claude/ 不存在），装好后重跑 cx-cli skills install。");
+        }
+        if (agents.codex) {
+            hintParts.push("Codex 读 ~/.agents/skills，无需额外链。");
+        }
+        if (pruned.length > 0) {
+            hintParts.push(`已清理 ${pruned.length} 条旧版本留下的 skill 链。`);
+        }
+        if (apm.apmError) {
+            hintParts.push(ensurePeriod(`apm 配置无效：${apm.apmError}`));
+        }
+        else if (!apm.apmConfigured) {
+            hintParts.push(SENTENCE(configPath));
+        }
+        return jsonOut({
+            packageRoot,
+            packageVersion: options.packageVersion,
+            centralDir,
+            agents,
+            skills: inventory.names,
+            created,
+            updated,
+            skipped,
+            pruned,
+            configDir: {
+                path: configDir,
+                created: !configDirExisted || !configExisted,
+                ...apm,
+            },
+            warnings,
+            hint: hintParts.join(""),
+        });
+    }
+    catch (error) {
+        return jsonOut({
+            error: error instanceof Error ? error.message : String(error),
+            kind: "io",
+            hint: "请检查相关目录权限后重试 cx-cli skills install。",
+        }, 1);
+    }
+}
+export function runSkillsStatus(options) {
+    try {
+        const packageRoot = realpathSync(resolve(options.packageRoot));
+        const inventory = skillInventory(packageRoot);
+        const home = homedir();
+        const centralDir = join(home, ".agents", "skills");
+        const claudeDir = join(home, ".claude", "skills");
+        const agents = {
+            claude: existsSync(join(home, ".claude")),
+            codex: existsSync(join(home, ".codex")),
+        };
+        const issues = [...inventory.warnings];
+        const orphans = findOrphans(packageRoot, inventory.names, home);
+        const skills = inventory.names.map(name => {
+            const central = inspectLink(join(centralDir, name), join(packageRoot, "skills", name), "realpath");
+            const centralIssue = stateIssue(name, central);
+            if (centralIssue) {
+                issues.push(centralIssue);
+            }
+            if (!agents.claude) {
+                return { name, central };
+            }
+            const claude = inspectLink(join(claudeDir, name), join(centralDir, name), "readlink");
+            const claudeIssue = stateIssue(name, claude);
+            if (claudeIssue) {
+                issues.push(claudeIssue);
+            }
+            return { name, central, claude };
+        });
+        for (const orphan of orphans) {
+            issues.push(`孤儿链 ${orphan.path} → ${orphan.target}（当前包无此 skill），运行 cx-cli skills install 清理`);
+        }
+        const ok = orphans.length === 0 &&
+            skills.every(skill => skill.central.state === "linked" && (!agents.claude || skill.claude?.state === "linked"));
+        const configDir = resolve(machineConfigDir());
+        const configPath = join(configDir, "apm-provider.local.json");
+        const apm = machineApmStatus(packageRoot);
+        const hintParts = [ok ? "skills 链接正常。" : "运行 cx-cli skills install 修复。"];
+        if (apm.apmError) {
+            hintParts.push(ensurePeriod(`apm 配置无效：${apm.apmError}`));
+        }
+        else if (!apm.apmConfigured) {
+            hintParts.push(SENTENCE(configPath));
+        }
+        return jsonOut({
+            ok,
+            packageRoot,
+            packageVersion: options.packageVersion,
+            centralDir,
+            agents,
+            skills,
+            orphans,
+            issues,
+            configDir: { path: configDir, exists: existsSync(configDir), ...apm },
+            hint: hintParts.join(""),
+        }, ok ? 0 : 1);
+    }
+    catch (error) {
+        return jsonOut({
+            error: error instanceof Error ? error.message : String(error),
+            kind: "io",
+            hint: "请检查相关目录权限后重试 cx-cli skills status。",
+        }, 1);
+    }
+}
+function isWithin(path, root) {
+    const fromRoot = relative(root, path);
+    return fromRoot === "" || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== ".." && !isAbsolute(fromRoot));
+}
+export function runSkillsUninstall(options) {
+    try {
+        const packageRoot = realpathSync(resolve(options.packageRoot));
+        const inventory = skillInventory(packageRoot);
+        const home = homedir();
+        const centralDir = join(home, ".agents", "skills");
+        const mountDirs = [join(home, ".claude", "skills"), join(home, ".codex", "skills")];
+        const orphans = findOrphans(packageRoot, inventory.names, home);
+        const removed = [];
+        const skipped = [];
+        for (const mountDir of mountDirs) {
+            for (const name of inventory.names) {
+                const path = join(mountDir, name);
+                const target = symlinkTarget(path);
+                if (target === join(centralDir, name)) {
+                    unlinkSync(path);
+                    removed.push(path);
+                }
+                else if (target !== null) {
+                    skipped.push({ path, reason: `指向别处：${target}` });
+                }
+                else if (existsSync(path)) {
+                    skipped.push({ path, reason: "已存在同名真实文件/目录（非软链）" });
+                }
+            }
+        }
+        for (const orphan of orphans.filter(orphan => dirname(orphan.path) !== centralDir)) {
+            unlinkSync(orphan.path);
+            removed.push(orphan.path);
+        }
+        for (const name of inventory.names) {
+            const path = join(centralDir, name);
+            const target = symlinkTarget(path);
+            if (target === null) {
+                if (existsSync(path)) {
+                    skipped.push({ path, reason: "已存在同名真实文件/目录（非软链）" });
+                }
+                continue;
+            }
+            if (!existsSync(path) || isWithin(realpathSync(path), packageRoot)) {
+                unlinkSync(path);
+                removed.push(path);
+            }
+            else {
+                skipped.push({ path, reason: `指向别处：${target}` });
+            }
+        }
+        for (const orphan of orphans.filter(orphan => dirname(orphan.path) === centralDir)) {
+            unlinkSync(orphan.path);
+            removed.push(orphan.path);
+        }
+        return jsonOut({
+            packageRoot,
+            packageVersion: options.packageVersion,
+            removed,
+            skipped,
+            warnings: inventory.warnings,
+            hint: "skills 链接已解除；接着 npm rm -g @ats-cx/cx-cli。~/.config/cx-cli/ 未动（含 apm 覆盖与产物），不再需要可手动删除。",
+        });
+    }
+    catch (error) {
+        return jsonOut({
+            error: error instanceof Error ? error.message : String(error),
+            kind: "io",
+            hint: "请检查相关目录权限后重试 cx-cli skills uninstall。",
+        }, 1);
+    }
+}
+//# sourceMappingURL=skills.js.map

package/dist/tools/apm-tools.d.ts

@@ -0,0 +1,115 @@
+import type { ApmClientDeps, ApmPortalDeps } from "@ats-cx/cx-core";
+export declare function createApmQueryTool(deps?: ApmClientDeps): import("../contract.js").ToolDefinition<{
+    type: "error" | "performance" | "api" | "paint" | "user_behav" | "network" | "server_error" | "footprint" | "server_api";
+    order: "ASC" | "DESC";
+    preview: number;
+    count: boolean;
+    full: boolean;
+    noFlush: boolean;
+    where: Record<string, string>;
+    from: string;
+    search?: string | undefined;
+    out?: string | undefined;
+    subType?: string | undefined;
+    to?: string | undefined;
+    project?: string | undefined;
+    user?: string | undefined;
+    collection?: string | undefined;
+    session?: string | undefined;
+    event?: string | undefined;
+    app?: string | undefined;
+    bizline?: string | undefined;
+    item?: string | undefined;
+    limit?: number | undefined;
+    run?: string | undefined;
+}, import("../apm-output.js").QueryPreview | {
+    total: number;
+}>;
+export declare function createApmFlushTool(deps?: ApmClientDeps): import("../contract.js").ToolDefinition<{}, {
+    flushed: boolean;
+    message: string | undefined;
+}>;
+export declare function createApmResolveTool(deps?: ApmPortalDeps): import("../contract.js").ToolDefinition<{
+    email?: string | undefined;
+    phone?: string | undefined;
+    host?: string | undefined;
+}, {
+    userId: string;
+    email: string;
+    host: string;
+    phone?: undefined;
+} | {
+    userId: string;
+    phone: string;
+    host: string;
+    email?: undefined;
+}>;
+export declare function createApmProjectTool(deps?: ApmPortalDeps): import("../contract.js").ToolDefinition<{
+    projectId: string;
+    out?: string | undefined;
+    run?: string | undefined;
+    host?: string | undefined;
+}, {
+    projectId: string;
+    host: string;
+    file: string;
+    bytes: number;
+    updatedDate: unknown;
+}>;
+export declare const apmQueryTool: import("../contract.js").ToolDefinition<{
+    type: "error" | "performance" | "api" | "paint" | "user_behav" | "network" | "server_error" | "footprint" | "server_api";
+    order: "ASC" | "DESC";
+    preview: number;
+    count: boolean;
+    full: boolean;
+    noFlush: boolean;
+    where: Record<string, string>;
+    from: string;
+    search?: string | undefined;
+    out?: string | undefined;
+    subType?: string | undefined;
+    to?: string | undefined;
+    project?: string | undefined;
+    user?: string | undefined;
+    collection?: string | undefined;
+    session?: string | undefined;
+    event?: string | undefined;
+    app?: string | undefined;
+    bizline?: string | undefined;
+    item?: string | undefined;
+    limit?: number | undefined;
+    run?: string | undefined;
+}, import("../apm-output.js").QueryPreview | {
+    total: number;
+}>;
+export declare const apmResolveTool: import("../contract.js").ToolDefinition<{
+    email?: string | undefined;
+    phone?: string | undefined;
+    host?: string | undefined;
+}, {
+    userId: string;
+    email: string;
+    host: string;
+    phone?: undefined;
+} | {
+    userId: string;
+    phone: string;
+    host: string;
+    email?: undefined;
+}>;
+export declare const apmProjectTool: import("../contract.js").ToolDefinition<{
+    projectId: string;
+    out?: string | undefined;
+    run?: string | undefined;
+    host?: string | undefined;
+}, {
+    projectId: string;
+    host: string;
+    file: string;
+    bytes: number;
+    updatedDate: unknown;
+}>;
+export declare const apmFlushTool: import("../contract.js").ToolDefinition<{}, {
+    flushed: boolean;
+    message: string | undefined;
+}>;