@actiondock/core 2.5.1 → 2.7.0

package/dist/doctor/checks/registry.js

@@ -0,0 +1,207 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ActionResolver } from "../../catalog/action-resolver.js";
+import { findProjectRoot, loadProjectConfig } from "../../project/loader.js";
+import { loadManifest } from "../../project/manifest.js";
+import { getRegistryStatus, listLinkedPackages, resolvePackageRoot } from "../../registry/registry.js";
+/**
+ * 按白名单过滤已链接包列表（白名单为空时保留全部）。
+ */
+function filterLinkedList(ctx) {
+    let linkedList = listLinkedPackages(ctx.customHome);
+    if (ctx.packageAllowlist && ctx.packageAllowlist.length > 0) {
+        linkedList = linkedList.filter((pkg) => ctx.packageAllowlist.includes(pkg.id));
+    }
+    return linkedList;
+}
+/**
+ * 检查全局注册表健康度（链接数量与失效路径）。
+ */
+export const checkGlobalRegistry = {
+    id: "registry.global",
+    run: (ctx) => {
+        try {
+            const regStatus = getRegistryStatus(ctx.customHome);
+            if (regStatus.staleCount > 0) {
+                ctx.checks.push({
+                    id: "registry.global",
+                    category: "registry",
+                    name: "Global Registry",
+                    status: "warn",
+                    message: `${regStatus.totalPackagesCount} package(s), ${regStatus.workspaces.length} workspace(s), but ${regStatus.staleCount} stale path(s) detected`,
+                    fix: "Run 'ad unlink --prune' to clean up stale entries from registry",
+                });
+            }
+            else {
+                ctx.checks.push({
+                    id: "registry.global",
+                    category: "registry",
+                    name: "Global Registry",
+                    status: "ok",
+                    message: `${regStatus.totalPackagesCount} linked package(s), ${regStatus.workspaces.length} workspace(s) (0 stale)`,
+                });
+            }
+        }
+        catch (err) {
+            ctx.checks.push({
+                id: "registry.global",
+                category: "registry",
+                name: "Global Registry",
+                status: "error",
+                message: `Failed to read registry: ${err.message}`,
+            });
+        }
+    },
+};
+/**
+ * 检查已链接包的依赖完整性（声明依赖但缺失 node_modules）。
+ */
+export const checkLinkedPackageDependencies = {
+    id: "registry.dependencies",
+    run: (ctx) => {
+        try {
+            const linkedList = filterLinkedList(ctx);
+            const missingNodeModules = [];
+            for (const pkg of linkedList) {
+                if (!existsSync(pkg.path))
+                    continue;
+                const pkgJsonPath = join(pkg.path, "package.json");
+                if (!existsSync(pkgJsonPath))
+                    continue;
+                try {
+                    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+                    const hasDeps = (pkgJson.dependencies && Object.keys(pkgJson.dependencies).length > 0) ||
+                        (pkgJson.devDependencies && Object.keys(pkgJson.devDependencies).length > 0);
+                    if (hasDeps && !existsSync(join(pkg.path, "node_modules"))) {
+                        missingNodeModules.push(pkg.id);
+                    }
+                }
+                catch (err) {
+                    // 单包 package.json 损坏：计入检查告警而非无声跳过，诊断工具必须暴露异常
+                    missingNodeModules.push(`${pkg.id} (unreadable package.json: ${err?.message || String(err)})`);
+                }
+            }
+            if (missingNodeModules.length > 0) {
+                ctx.checks.push({
+                    id: "registry.dependencies",
+                    category: "registry",
+                    name: "Linked Package Dependencies",
+                    status: "warn",
+                    message: `${missingNodeModules.length} linked package(s) declare dependencies but miss node_modules: ${missingNodeModules.join(", ")}`,
+                    fix: "Run 'npm install' in the affected package directories, or execute 'ad run' to auto-install",
+                });
+            }
+            else {
+                ctx.checks.push({
+                    id: "registry.dependencies",
+                    category: "registry",
+                    name: "Linked Package Dependencies",
+                    status: "ok",
+                    message: linkedList.length > 0
+                        ? "All linked packages have dependencies installed"
+                        : "No linked packages requiring dependency verification",
+                });
+            }
+        }
+        catch (err) {
+            // 依赖检查整体失败：转为 error 检查项呈现在报告中，而非无声跳过
+            ctx.checks.push({
+                id: "registry.dependencies",
+                category: "registry",
+                name: "Linked Package Dependencies",
+                status: "error",
+                message: `Failed to check linked package dependencies: ${err?.message || String(err)}`,
+            });
+        }
+    },
+};
+/**
+ * 检查清单 uses 声明的跨包依赖闭包可解析性。
+ */
+export const checkUsesClosure = {
+    id: "registry.uses_closure",
+    run: (ctx) => {
+        try {
+            const linkedList = filterLinkedList(ctx);
+            let packagesToCheck = linkedList.map((p) => ({
+                id: p.id,
+                root: p.path,
+            }));
+            const curProjectRoot = ctx.packageIdOrPath
+                ? resolvePackageRoot(ctx.packageIdOrPath, ctx.cwd, ctx.customHome) || findProjectRoot(ctx.packageIdOrPath)
+                : findProjectRoot(ctx.cwd);
+            if (curProjectRoot && !packagesToCheck.some((p) => p.root === curProjectRoot)) {
+                try {
+                    const cfg = loadProjectConfig(curProjectRoot);
+                    packagesToCheck.push({ id: cfg.id, root: curProjectRoot });
+                }
+                catch (err) {
+                    // 当前工程配置损坏：无法纳入闭包检查范围，输出告警而非无声跳过
+                    console.warn(`[Doctor] Skipping corrupted current project in uses-closure check: '${curProjectRoot}' (${err?.message || String(err)})`);
+                }
+            }
+            if (ctx.packageAllowlist && ctx.packageAllowlist.length > 0) {
+                packagesToCheck = packagesToCheck.filter((p) => ctx.packageAllowlist.includes(p.id));
+            }
+            const unresolvableUses = [];
+            for (const pkg of packagesToCheck) {
+                if (!existsSync(pkg.root))
+                    continue;
+                const manifest = loadManifest(pkg.root);
+                if (!manifest || !manifest.actions)
+                    continue;
+                for (const [actionId, actionEntry] of Object.entries(manifest.actions)) {
+                    if (!Array.isArray(actionEntry.uses))
+                        continue;
+                    for (const rawRef of actionEntry.uses) {
+                        if (typeof rawRef !== "string" || !rawRef.trim())
+                            continue;
+                        let parsed;
+                        try {
+                            parsed = ActionResolver.parseRef(rawRef);
+                        }
+                        catch {
+                            unresolvableUses.push(`${pkg.id}/${actionId} -> '${rawRef}'`);
+                            continue;
+                        }
+                        if (parsed.packageId) {
+                            const depRoot = resolvePackageRoot(parsed.packageId, pkg.root, ctx.customHome);
+                            if (!depRoot || !existsSync(depRoot)) {
+                                unresolvableUses.push(`${pkg.id}/${actionId} -> '${rawRef}'`);
+                            }
+                        }
+                    }
+                }
+            }
+            if (unresolvableUses.length > 0) {
+                ctx.checks.push({
+                    id: "registry.uses_closure",
+                    category: "registry",
+                    name: "Cross-Package Uses Dependencies",
+                    status: "warn",
+                    message: `${unresolvableUses.length} unresolvable cross-package dependency reference(s) found in manifest uses: ${unresolvableUses.join(", ")}`,
+                    fix: "Link missing packages with 'ad link', or correct unresolvable uses declarations",
+                });
+            }
+            else {
+                ctx.checks.push({
+                    id: "registry.uses_closure",
+                    category: "registry",
+                    name: "Cross-Package Uses Dependencies",
+                    status: "ok",
+                    message: "All cross-package uses declarations in manifests resolved successfully",
+                });
+            }
+        }
+        catch (err) {
+            // 闭包检查整体失败：转为 error 检查项呈现在报告中，而非无声跳过
+            ctx.checks.push({
+                id: "registry.uses_closure",
+                category: "registry",
+                name: "Cross-Package Uses Dependencies",
+                status: "error",
+                message: `Failed to check cross-package uses dependencies: ${err?.message || String(err)}`,
+            });
+        }
+    },
+};

package/dist/doctor/checks/runtime.d.ts

@@ -0,0 +1,13 @@
+import type { DoctorCheck } from "../context.js";
+/**
+ * 检查 Node.js 运行时版本是否满足最低要求（>= 24.12.0）。
+ */
+export declare const checkNodeRuntime: DoctorCheck;
+/**
+ * 检查 Bun 运行时可用性（可选环境，用于跨运行时兼容性测试）。
+ */
+export declare const checkBunRuntime: DoctorCheck;
+/**
+ * 检查 CLI 可执行文件（ad）是否在 PATH 中。
+ */
+export declare const checkCliExecutable: DoctorCheck;

package/dist/doctor/checks/runtime.js

@@ -0,0 +1,90 @@
+import { findExecutable } from "../../utils/index.js";
+function compareSemver(v1, v2) {
+    const p1 = v1.replace(/^v/, "").split(".").map(Number);
+    const p2 = v2.replace(/^v/, "").split(".").map(Number);
+    for (let i = 0; i < Math.max(p1.length, p2.length); i++) {
+        const num1 = p1[i] || 0;
+        const num2 = p2[i] || 0;
+        if (num1 > num2)
+            return 1;
+        if (num1 < num2)
+            return -1;
+    }
+    return 0;
+}
+/**
+ * 检查 Node.js 运行时版本是否满足最低要求（>= 24.12.0）。
+ */
+export const checkNodeRuntime = {
+    id: "runtime.node",
+    run: (ctx) => {
+        const nodeVersion = process.versions.node;
+        if (nodeVersion) {
+            const isGte24 = compareSemver(nodeVersion, "24.12.0") >= 0;
+            ctx.checks.push({
+                id: "runtime.node",
+                category: "runtime",
+                name: "Node.js Runtime",
+                status: isGte24 ? "ok" : "warn",
+                message: `v${nodeVersion} (${isGte24 ? ">= 24.12.0 supported" : ">= 24.12.0 recommended"})`,
+                fix: isGte24 ? undefined : "Upgrade Node.js to v24.12.0 or higher",
+            });
+        }
+    },
+};
+/**
+ * 检查 Bun 运行时可用性（可选环境，用于跨运行时兼容性测试）。
+ */
+export const checkBunRuntime = {
+    id: "runtime.bun",
+    run: (ctx) => {
+        const bunVersion = (typeof globalThis.Bun !== "undefined" && globalThis.Bun.version) ||
+            process.versions.bun;
+        if (bunVersion) {
+            ctx.checks.push({
+                id: "runtime.bun",
+                category: "runtime",
+                name: "Bun Runtime",
+                status: "ok",
+                message: `v${bunVersion} (available for cross-environment testing)`,
+            });
+        }
+        else {
+            ctx.checks.push({
+                id: "runtime.bun",
+                category: "runtime",
+                name: "Bun Runtime",
+                status: "ok",
+                message: "Bun runtime not detected (optional, used for cross-environment compatibility testing)",
+            });
+        }
+    },
+};
+/**
+ * 检查 CLI 可执行文件（ad）是否在 PATH 中。
+ */
+export const checkCliExecutable = {
+    id: "runtime.cli",
+    run: (ctx) => {
+        const adPath = findExecutable("ad");
+        if (adPath) {
+            ctx.checks.push({
+                id: "runtime.cli",
+                category: "runtime",
+                name: "CLI Executable",
+                status: "ok",
+                message: `Found 'ad' in PATH at ${adPath}`,
+            });
+        }
+        else {
+            ctx.checks.push({
+                id: "runtime.cli",
+                category: "runtime",
+                name: "CLI Executable",
+                status: "warn",
+                message: "'ad' command not found in PATH",
+                fix: "Run 'npm install -g @actiondock/cli' or in SDK workspace run 'cd packages/cli && npm link'",
+            });
+        }
+    },
+};

package/dist/doctor/checks/storage.d.ts

@@ -0,0 +1,5 @@
+import type { DoctorCheck } from "../context.js";
+/**
+ * 检查全局存储（全局 SQLite 数据库）可写性。
+ */
+export declare const checkGlobalStorage: DoctorCheck;

package/dist/doctor/checks/storage.js

@@ -0,0 +1,34 @@
+import { createGlobalStorage } from "../../storage/index.js";
+import { getActionDockHome } from "../../utils/index.js";
+/**
+ * 检查全局存储（全局 SQLite 数据库）可写性。
+ */
+export const checkGlobalStorage = {
+    id: "storage.global",
+    run: async (ctx) => {
+        const globalHome = getActionDockHome(ctx.customHome);
+        try {
+            const globalStorage = createGlobalStorage(ctx.customHome);
+            await globalStorage.setConfig("_doctor_probe_", "ok");
+            await globalStorage.deleteConfig("_doctor_probe_");
+            globalStorage.close();
+            ctx.checks.push({
+                id: "storage.global",
+                category: "storage",
+                name: "Global Storage",
+                status: "ok",
+                message: `Global SQLite database verified at ${globalHome}`,
+            });
+        }
+        catch (err) {
+            ctx.checks.push({
+                id: "storage.global",
+                category: "storage",
+                name: "Global Storage",
+                status: "error",
+                message: `Failed to access global storage: ${err.message}`,
+                fix: `Ensure directory '${globalHome}' is writable`,
+            });
+        }
+    },
+};

package/dist/doctor/context.d.ts

@@ -0,0 +1,35 @@
+import type { DoctorCheckItem } from "./types.js";
+/**
+ * 体检诊断共享上下文：承载诊断输入选项、工程定位结果与累积检查项。
+ * 各检查函数按注册表顺序执行，并将检查项追加到 checks 列表。
+ */
+export interface DoctorCheckContext {
+    /** 工作目录（默认 process.cwd()） */
+    cwd: string;
+    /** 目标包 ID 或磁盘路径（可选） */
+    packageIdOrPath?: string;
+    /** 自定义 ActionDock Home 目录（用于测试隔离） */
+    customHome?: string;
+    /** 允许纳入诊断的包 ID 白名单（可选） */
+    packageAllowlist?: string[];
+    /** 累积的检查项列表（保持注册顺序，直接决定报告展示顺序） */
+    checks: DoctorCheckItem[];
+    /** 诊断目标工程根目录（工程定位阶段写入；null 表示无工程上下文或被白名单排除） */
+    projectRoot: string | null;
+    /** 诊断目标工程的包 ID（工程配置加载成功后写入） */
+    packageId?: string;
+}
+/** 单项体检检查：从共享上下文读取输入，并将检查项追加到 ctx.checks。 */
+export interface DoctorCheck {
+    /** 检查阶段唯一标识（用于注册表定位与排查） */
+    id: string;
+    /** 执行检查逻辑（可同步或异步） */
+    run: (ctx: DoctorCheckContext) => void | Promise<void>;
+}
+/** 基于诊断选项构建共享上下文（checks 从空列表开始累积）。 */
+export declare function createDoctorCheckContext(options?: {
+    cwd?: string;
+    packageIdOrPath?: string;
+    customHome?: string;
+    packageAllowlist?: string[];
+}): DoctorCheckContext;

package/dist/doctor/context.js

@@ -0,0 +1,11 @@
+/** 基于诊断选项构建共享上下文（checks 从空列表开始累积）。 */
+export function createDoctorCheckContext(options) {
+    return {
+        cwd: options?.cwd || process.cwd(),
+        packageIdOrPath: options?.packageIdOrPath,
+        customHome: options?.customHome,
+        packageAllowlist: options?.packageAllowlist,
+        checks: [],
+        projectRoot: null,
+    };
+}

package/dist/doctor/doctor.d.ts

@@ -1,4 +1,9 @@
 import type { DoctorReport } from "./types.js";
+/**
+ * 执行环境与依赖体检诊断。
+ * 按注册表顺序执行各检查阶段（各阶段自行兜底异常，转为对应检查项呈现），
+ * 最终汇总各状态计数并输出结构化诊断报告。
+ */
 export declare function runDoctorChecks(options?: {
     cwd?: string;
     packageIdOrPath?: string;