@actiondock/core 2.5.0 → 2.6.0

package/dist/app/types.d.ts

@@ -187,6 +187,11 @@ export interface ActionDockAppOptions {
     packageInstanceId?: string;
     /** 快照代次标识 */
     generationId?: string;
+    /**
+     * 是否以数据目录持有者身份打开存储：true 时构造阶段收割遗留非终态运行记录。
+     * 默认 true（App 主路径即持有者）；外部工具创建旁观视图时置 false。
+     */
+    recoverOrphans?: boolean;
     /** 临时配置覆写字典 */
     configOverrides?: Record<string, unknown>;
     /** 宿主所有者标识 */

package/dist/catalog/action-index.js

@@ -12,8 +12,9 @@ export class ActionIndex {
             try {
                 manifest = loadManifest(pkg.projectRoot);
             }
-            catch {
-                // Skip invalid manifest during catalog indexing
+            catch (err) {
+                // 清单损坏时跳过索引但输出告警含路径，回退扫描 actions 目录
+                console.warn(`[Catalog] Failed to load manifest for package '${packageId}' at '${pkg.projectRoot}': ${err?.message || String(err)}`);
             }
             if (manifest && manifest.actions) {
                 for (const [actionId, item] of Object.entries(manifest.actions)) {
@@ -57,8 +58,9 @@ export class ActionIndex {
                             }
                         }
                     }
-                    catch {
-                        // 忽略读取目录异常
+                    catch (err) {
+                        // 目录扫描失败时输出告警含路径，不再无声吞没
+                        console.warn(`[Catalog] Failed to scan actions directory for package '${packageId}' at '${actionsDir}': ${err?.message || String(err)}`);
                     }
                 }
             }

package/dist/catalog/package-catalog.js

@@ -44,7 +44,8 @@ export class PackageCatalog {
                 if (e.message?.startsWith("PACKAGE_ID_CONFLICT")) {
                     throw e;
                 }
-                // 忽略无效项目
+                // 无效项目跳过注册但输出告警含路径，杜绝无声丢弃
+                console.warn(`[Catalog] Skipping invalid package at '${abs}': ${e?.message || String(e)}`);
             }
         };
         // 优先包含当前工作目录所在项目

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

@@ -0,0 +1,5 @@
+export { checkBunRuntime, checkCliExecutable, checkNodeRuntime } from "./runtime.js";
+export { checkGlobalStorage } from "./storage.js";
+export { checkGlobalRegistry, checkLinkedPackageDependencies, checkUsesClosure, } from "./registry.js";
+export { locateProject } from "./project-locate.js";
+export { checkProject } from "./project.js";

package/dist/doctor/checks/index.js

@@ -0,0 +1,5 @@
+export { checkBunRuntime, checkCliExecutable, checkNodeRuntime } from "./runtime.js";
+export { checkGlobalStorage } from "./storage.js";
+export { checkGlobalRegistry, checkLinkedPackageDependencies, checkUsesClosure, } from "./registry.js";
+export { locateProject } from "./project-locate.js";
+export { checkProject } from "./project.js";

package/dist/doctor/checks/project-locate.d.ts

@@ -0,0 +1,6 @@
+import type { DoctorCheck } from "../context.js";
+/**
+ * 定位诊断目标工程根目录（支持包 ID / 磁盘路径 / 当前目录向上查找），
+ * 并按白名单预校验；结果写入 ctx.projectRoot，供后续工程级检查消费。
+ */
+export declare const locateProject: DoctorCheck;

package/dist/doctor/checks/project-locate.js

@@ -0,0 +1,36 @@
+import { findProjectRoot, loadProjectConfig } from "../../project/loader.js";
+import { resolvePackageRoot } from "../../registry/registry.js";
+/**
+ * 定位诊断目标工程根目录（支持包 ID / 磁盘路径 / 当前目录向上查找），
+ * 并按白名单预校验；结果写入 ctx.projectRoot，供后续工程级检查消费。
+ */
+export const locateProject = {
+    id: "project.locate",
+    run: (ctx) => {
+        let projectRoot = null;
+        if (ctx.packageIdOrPath) {
+            projectRoot =
+                resolvePackageRoot(ctx.packageIdOrPath, ctx.cwd, ctx.customHome) ||
+                    findProjectRoot(ctx.packageIdOrPath);
+        }
+        else {
+            projectRoot = findProjectRoot(ctx.cwd);
+        }
+        if (projectRoot) {
+            try {
+                const config = loadProjectConfig(projectRoot);
+                if (ctx.packageAllowlist &&
+                    Array.isArray(ctx.packageAllowlist) &&
+                    ctx.packageAllowlist.length > 0 &&
+                    !ctx.packageAllowlist.includes(config.id)) {
+                    projectRoot = null;
+                }
+            }
+            catch (err) {
+                // 预校验失败不改变根目录定位，交由后续详细诊断呈现具体错误；但绝不无声吞没，输出告警
+                console.warn(`[Doctor] Failed to pre-validate project config at '${projectRoot}': ${err?.message || String(err)}`);
+            }
+        }
+        ctx.projectRoot = projectRoot;
+    },
+};

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

@@ -0,0 +1,6 @@
+import type { DoctorCheck } from "../context.js";
+/**
+ * 工程级诊断入口：加载工程配置后按序执行全部工程检查；
+ * 配置损坏时转为 project.config error 检查项（此时 packageId 已就绪的值保持不回滚）。
+ */
+export declare const checkProject: DoctorCheck;

package/dist/doctor/checks/project.js

@@ -0,0 +1,383 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { discoverActionFiles, loadActions, loadPlaybooks, loadProjectConfig } from "../../project/loader.js";
+import { loadManifest, MANIFEST_FILE_NAME } from "../../project/manifest.js";
+import { createStorage, resolveDatabasePath } from "../../storage/index.js";
+/**
+ * 检查工程配置可解析性，并写入 ctx.packageId 供报告汇总使用。
+ */
+function checkProjectConfig(scope) {
+    const { ctx, config } = scope;
+    ctx.packageId = config.id;
+    ctx.checks.push({
+        id: "project.config",
+        category: "project",
+        name: "Project Configuration",
+        status: "ok",
+        message: `Valid (${config.id} v${config.version})`,
+    });
+}
+/**
+ * 检查工程 node_modules 中 @actiondock/sdk 的可解析性。
+ */
+function checkProjectSdk(scope) {
+    const { ctx, projectRoot } = scope;
+    const hasSdkInNodeModules = existsSync(join(projectRoot, "node_modules", "@actiondock", "sdk")) ||
+        existsSync(join(projectRoot, "node_modules", "@actiondock", "sdk", "package.json"));
+    if (hasSdkInNodeModules) {
+        ctx.checks.push({
+            id: "project.sdk",
+            category: "project",
+            name: "SDK Dependency",
+            status: "ok",
+            message: "Resolved @actiondock/sdk in node_modules",
+        });
+    }
+    else {
+        ctx.checks.push({
+            id: "project.sdk",
+            category: "project",
+            name: "SDK Dependency",
+            status: "warn",
+            message: "@actiondock/sdk not found in project node_modules",
+            fix: "Run 'npm link @actiondock/sdk' or 'npm install' in project directory",
+        });
+    }
+}
+/**
+ * 检查工程运行时数据库可写性。
+ */
+async function checkProjectStorage(scope) {
+    const { ctx, config } = scope;
+    const dbPath = resolveDatabasePath(config.id, { customHome: ctx.customHome });
+    try {
+        const projectStorage = createStorage(config.id, { customHome: ctx.customHome });
+        await projectStorage.setConfig("_doctor_probe_", "ok");
+        await projectStorage.deleteConfig("_doctor_probe_");
+        projectStorage.close();
+        ctx.checks.push({
+            id: "project.storage",
+            category: "project",
+            name: "Project Database",
+            status: "ok",
+            message: `Database writable at ${dbPath}`,
+        });
+    }
+    catch (err) {
+        ctx.checks.push({
+            id: "project.storage",
+            category: "project",
+            name: "Project Database",
+            status: "error",
+            message: `Failed to write project runtime database: ${err.message}`,
+            fix: `Check write permissions for '${dirname(dbPath)}'`,
+        });
+    }
+}
+/**
+ * 检查工程 Actions 可加载性与数量。
+ */
+async function checkProjectActions(scope) {
+    const { ctx, projectRoot, config } = scope;
+    try {
+        const manifest = loadManifest(projectRoot);
+        let actionsCount = 0;
+        if (manifest?.actions) {
+            actionsCount = Object.keys(manifest.actions).length;
+        }
+        else {
+            const actions = await loadActions(projectRoot, config.actionsDir);
+            actionsCount = actions.size;
+        }
+        if (actionsCount === 0) {
+            ctx.checks.push({
+                id: "project.actions",
+                category: "project",
+                name: "Actions",
+                status: "warn",
+                message: `No actions found in '${config.actionsDir || "actions"}'`,
+                fix: "Run 'ad action new <id>' to create your first action",
+            });
+        }
+        else {
+            ctx.checks.push({
+                id: "project.actions",
+                category: "project",
+                name: "Actions",
+                status: "ok",
+                message: `${actionsCount} action(s) valid and loaded`,
+            });
+        }
+    }
+    catch (err) {
+        ctx.checks.push({
+            id: "project.actions",
+            category: "project",
+            name: "Actions",
+            status: "error",
+            message: `Failed to load actions: ${err.message}`,
+        });
+    }
+}
+/**
+ * 检查 Action 清单与源码文件的双向一致性（轻量静态检测）。
+ */
+function checkProjectManifest(scope) {
+    const { ctx, projectRoot, config } = scope;
+    try {
+        const manifestPath = join(projectRoot, MANIFEST_FILE_NAME);
+        const manifest = loadManifest(projectRoot);
+        const actionFiles = discoverActionFiles(projectRoot, config.actionsDir || "actions");
+        if (!existsSync(manifestPath)) {
+            if (actionFiles.length > 0) {
+                ctx.checks.push({
+                    id: "project.manifest",
+                    category: "project",
+                    name: "Action Manifest",
+                    status: "warn",
+                    message: `${MANIFEST_FILE_NAME} not found (${actionFiles.length} action source file(s) exist)`,
+                    fix: "Run 'ad validate' to generate or check manifest",
+                });
+            }
+        }
+        else if (manifest && manifest.actions) {
+            const missingFiles = Object.entries(manifest.actions)
+                .filter(([_, item]) => !existsSync(join(projectRoot, item.entry)))
+                .map(([id, item]) => `${id} (${item.entry})`);
+            const manifestEntries = new Set(Object.values(manifest.actions).map((a) => a.entry.replace(/\\/g, "/")));
+            const untracked = actionFiles
+                .map((f) => relative(projectRoot, f).replace(/\\/g, "/"))
+                .filter((rel) => !manifestEntries.has(rel));
+            if (missingFiles.length > 0) {
+                ctx.checks.push({
+                    id: "project.manifest",
+                    category: "project",
+                    name: "Action Manifest",
+                    status: "warn",
+                    message: `${missingFiles.length} action(s) in manifest point to missing files: ${missingFiles.join(", ")}`,
+                    fix: "Run 'ad validate' to check or update actiondock.json",
+                });
+            }
+            else if (untracked.length > 0) {
+                ctx.checks.push({
+                    id: "project.manifest",
+                    category: "project",
+                    name: "Action Manifest",
+                    status: "warn",
+                    message: `${untracked.length} action file(s) not declared in manifest: ${untracked.join(", ")}`,
+                    fix: "Run 'ad validate' to check or update actiondock.json",
+                });
+            }
+            else {
+                const manifestStat = statSync(manifestPath);
+                const newerFiles = actionFiles.filter((f) => statSync(f).mtimeMs > manifestStat.mtimeMs + 2000);
+                if (newerFiles.length > 0) {
+                    ctx.checks.push({
+                        id: "project.manifest",
+                        category: "project",
+                        name: "Action Manifest",
+                        status: "ok",
+                        message: `Manifest valid (Note: ${newerFiles.length} action file(s) modified after manifest; run 'ad validate' if definitions changed)`,
+                    });
+                }
+                else {
+                    ctx.checks.push({
+                        id: "project.manifest",
+                        category: "project",
+                        name: "Action Manifest",
+                        status: "ok",
+                        message: "Manifest synchronized with action files",
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        ctx.checks.push({
+            id: "project.manifest",
+            category: "project",
+            name: "Action Manifest",
+            status: "error",
+            message: `Failed to inspect manifest: ${err.message}`,
+        });
+    }
+}
+/**
+ * 检查 files 声明边界与源码目录未声明引用。
+ */
+function checkProjectFiles(scope) {
+    const { ctx, projectRoot, config } = scope;
+    try {
+        const declaredFiles = config.files || [];
+        const hasSrc = existsSync(join(projectRoot, "src"));
+        const hasLib = existsSync(join(projectRoot, "lib"));
+        if (declaredFiles.length > 0) {
+            const missingDeclared = declaredFiles.filter((f) => !existsSync(join(projectRoot, f)));
+            if (missingDeclared.length > 0) {
+                ctx.checks.push({
+                    id: "project.files",
+                    category: "project",
+                    name: "Declared Files",
+                    status: "error",
+                    message: `${missingDeclared.length} path(s) declared in 'files' do not exist: ${missingDeclared.join(", ")}`,
+                    fix: `Verify and update 'files' in ${MANIFEST_FILE_NAME}`,
+                });
+            }
+            else {
+                ctx.checks.push({
+                    id: "project.files",
+                    category: "project",
+                    name: "Declared Files",
+                    status: "ok",
+                    message: `All ${declaredFiles.length} declared file/directory boundaries verified`,
+                });
+            }
+        }
+        else if (hasSrc || hasLib) {
+            const actionFiles = discoverActionFiles(projectRoot, config.actionsDir || "actions");
+            let hasReferenceToSrcOrLib = false;
+            const unreadableFiles = [];
+            for (const actFile of actionFiles) {
+                try {
+                    const src = readFileSync(actFile, "utf-8");
+                    if (/['"](?:\.\.\/(?:src|lib)|\.\/(?:src|lib))[^'"]*['"]/.test(src)) {
+                        hasReferenceToSrcOrLib = true;
+                        break;
+                    }
+                }
+                catch (err) {
+                    // 单文件读取失败：计入告警名单，边界检测结论不再基于无声缺失的数据
+                    unreadableFiles.push(`${actFile} (${err?.message || String(err)})`);
+                }
+            }
+            if (hasReferenceToSrcOrLib) {
+                ctx.checks.push({
+                    id: "project.files",
+                    category: "project",
+                    name: "Declared Files",
+                    status: "error",
+                    message: `Actions import modules from ${hasSrc ? "'src/'" : ""}${hasSrc && hasLib ? " and " : ""}${hasLib ? "'lib/'" : ""}, but 'files' is not declared in ${MANIFEST_FILE_NAME}`,
+                    fix: `Add "files": [${hasSrc ? '"src"' : ""}${hasSrc && hasLib ? ', "lib"' : hasLib && !hasSrc ? '"lib"' : ""}] to ${MANIFEST_FILE_NAME}`,
+                });
+            }
+            else {
+                ctx.checks.push({
+                    id: "project.files",
+                    category: "project",
+                    name: "Declared Files",
+                    status: unreadableFiles.length > 0 ? "warn" : "ok",
+                    message: unreadableFiles.length > 0
+                        ? `Project source directories clean, but ${unreadableFiles.length} action file(s) unreadable during boundary scan: ${unreadableFiles.join(", ")}`
+                        : `Project source directories clean (no undeclared references to ${hasSrc ? "src/" : "lib/"})`,
+                });
+            }
+        }
+    }
+    catch (err) {
+        // 文件边界检测整体失败：转为 error 检查项呈现在报告中，而非无声跳过
+        ctx.checks.push({
+            id: "project.files",
+            category: "project",
+            name: "Declared Files",
+            status: "error",
+            message: `Failed to inspect declared files and source boundaries: ${err?.message || String(err)}`,
+        });
+    }
+}
+/**
+ * 检查工程 Playbook 规程文档可加载性。
+ */
+function checkProjectPlaybooks(scope) {
+    const { ctx, projectRoot, config } = scope;
+    try {
+        const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
+        ctx.checks.push({
+            id: "project.playbooks",
+            category: "project",
+            name: "Playbooks",
+            status: "ok",
+            message: `${playbooks.size} playbook(s) valid`,
+        });
+    }
+    catch (err) {
+        ctx.checks.push({
+            id: "project.playbooks",
+            category: "project",
+            name: "Playbooks",
+            status: "warn",
+            message: `Playbooks issue: ${err.message}`,
+        });
+    }
+}
+/**
+ * 检查声明配置项的就绪状态（存储值 / 环境变量 / 默认值兜底）。
+ */
+async function checkProjectConfigReadiness(scope) {
+    const { ctx, config } = scope;
+    if (config.config && Object.keys(config.config).length > 0) {
+        const missingKeys = [];
+        const projectStorage = createStorage(config.id, { customHome: ctx.customHome });
+        for (const [key, def] of Object.entries(config.config)) {
+            const inStorage = await projectStorage.getConfig(key);
+            const envNames = Array.isArray(def.env) ? def.env : def.env ? [def.env] : [key];
+            const inEnv = envNames.some((e) => process.env[e] !== undefined);
+            const isRequired = def.required || (def.default === undefined && def.secret);
+            if ((isRequired || def.default === undefined) && inStorage === undefined && !inEnv) {
+                missingKeys.push(key);
+            }
+        }
+        projectStorage.close();
+        if (missingKeys.length > 0) {
+            ctx.checks.push({
+                id: "project.config_readiness",
+                category: "project",
+                name: "Config Readiness",
+                status: "warn",
+                message: `Required config item(s) missing: ${missingKeys.join(", ")}`,
+                fix: `Run 'ad config set <KEY> <VALUE>' to configure missing keys`,
+            });
+        }
+        else {
+            ctx.checks.push({
+                id: "project.config_readiness",
+                category: "project",
+                name: "Config Readiness",
+                status: "ok",
+                message: "All declared configuration dependencies satisfied",
+            });
+        }
+    }
+}
+/**
+ * 工程级诊断入口：加载工程配置后按序执行全部工程检查；
+ * 配置损坏时转为 project.config error 检查项（此时 packageId 已就绪的值保持不回滚）。
+ */
+export const checkProject = {
+    id: "project.detail",
+    run: async (ctx) => {
+        const projectRoot = ctx.projectRoot;
+        if (!projectRoot)
+            return;
+        try {
+            const config = loadProjectConfig(projectRoot);
+            const scope = { ctx, projectRoot, config };
+            checkProjectConfig(scope);
+            checkProjectSdk(scope);
+            await checkProjectStorage(scope);
+            await checkProjectActions(scope);
+            checkProjectManifest(scope);
+            checkProjectFiles(scope);
+            checkProjectPlaybooks(scope);
+            await checkProjectConfigReadiness(scope);
+        }
+        catch (err) {
+            ctx.checks.push({
+                id: "project.config",
+                category: "project",
+                name: "Project Configuration",
+                status: "error",
+                message: `Invalid actiondock.json: ${err.message}`,
+            });
+        }
+    },
+};

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

@@ -0,0 +1,13 @@
+import type { DoctorCheck } from "../context.js";
+/**
+ * 检查全局注册表健康度（链接数量与失效路径）。
+ */
+export declare const checkGlobalRegistry: DoctorCheck;
+/**
+ * 检查已链接包的依赖完整性（声明依赖但缺失 node_modules）。
+ */
+export declare const checkLinkedPackageDependencies: DoctorCheck;
+/**
+ * 检查清单 uses 声明的跨包依赖闭包可解析性。
+ */
+export declare const checkUsesClosure: DoctorCheck;