@actiondock/core 2.19.0 → 2.21.0

package/dist/project/loader.js

@@ -1,9 +1,10 @@
-import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { NodeModuleLoader, unwrapDefaultExport } from "../platform/module-loader.js";
 import { ActionDockError, ACTION_LOAD_FAILED, describeActionLoadFailure, INVALID_ACTION_ID, INVALID_JSON, INVALID_PACKAGE_ID, INVALID_PLAYBOOK_ID, MANIFEST_LOAD_FAILED, PLAYBOOK_NOT_FOUND, PROJECT_CONFIG_NOT_FOUND, } from "../errors.js";
 import { loadManifest, ACTION_ID_REGEX, PLAYBOOK_ID_REGEX } from "./manifest.js";
+import { assertValidConfigDeclarations } from "./config-declarations.js";
+import { runPackageManager } from "./package-manager.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
  *
@@ -68,6 +69,9 @@ export function loadProjectConfig(projectRoot) {
         if (parsed.playbooksDir) {
             assertWithinProjectRoot(projectRoot, parsed.playbooksDir, "playbooksDir");
         }
+        if (parsed.config !== undefined) {
+            assertValidConfigDeclarations(parsed.config);
+        }
         return parsed;
     }
     catch (err) {
@@ -81,36 +85,21 @@ export const ALLOWED_INSTALLERS = new Set(["npm", "bun"]);
 /**
  * 异步探测包管理器可用性（通过执行 --version 并检查退出码）。
  *
- * 异步化取舍说明：
- * - 替换同步阻塞子进程调用，避免阻塞 Node.js 事件循环；
- * - Windows 兼容性保留：npm 在 Windows 上是 .cmd 批处理脚本，在 shell 开启下执行以避免直接调用报错；
- * - 探测命令限制于白名单内部候选，杜绝外部输入注入风险。
+ * 运维规范：
+ * - 复用统一包管理器启动解析与驱动底座，以 shell: false 执行；
+ * - 短超时限制，避免探测阻滞事件循环；
+ * - 仅在未明确指定包管理器时进行回退探测，选择后的执行失败不盲目换工具。
  */
-function probePackageManager(command) {
-    return new Promise((resolve) => {
-        try {
-            const proc = spawn(command, ["--version"], {
-                stdio: "pipe",
-                shell: process.platform === "win32",
-            });
-            let settled = false;
-            proc.on("error", () => {
-                if (!settled) {
-                    settled = true;
-                    resolve(false);
-                }
-            });
-            proc.on("close", (code) => {
-                if (!settled) {
-                    settled = true;
-                    resolve(code === 0);
-                }
-            });
-        }
-        catch {
-            resolve(false);
-        }
-    });
+async function probePackageManager(command) {
+    try {
+        const result = await runPackageManager(command, ["--version"], {
+            timeoutMs: 3000,
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * 探测宿主系统中可用的包管理工具。

package/dist/project/manifest.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { assertValidConfigDeclarations, validateConfigDeclarations } from "./config-declarations.js";
 import { isPathOutsideBoundary, PACKAGE_ID_REGEX } from "../utils/index.js";
 import { ActionDockError, MANIFEST_CORRUPTED, MANIFEST_INVALID, MANIFEST_READ_FAILED, UNSUPPORTED_MANIFEST_SCHEMA, } from "../errors.js";
 export const MANIFEST_FILE_NAME = "actiondock.json";
@@ -38,6 +39,9 @@ export function loadManifest(projectRoot) {
     if (!parsed.id) {
         parsed.id = basename(projectRoot);
     }
+    if (parsed.config !== undefined) {
+        assertValidConfigDeclarations(parsed.config);
+    }
     return parsed;
 }
 /**
@@ -65,6 +69,12 @@ export function validateManifest(manifest, options) {
             errors.push(`Manifest 'id' is invalid: '${m.id}' (must match ${PACKAGE_ID_REGEX})`);
         }
     }
+    if (m.config !== undefined) {
+        const configErrors = validateConfigDeclarations(m.config);
+        for (const err of configErrors) {
+            errors.push(err);
+        }
+    }
     if (m.actions !== undefined) {
         if (!m.actions || typeof m.actions !== "object" || Array.isArray(m.actions)) {
             errors.push("Manifest 'actions' must be an object");

package/dist/project/package-manager.d.ts

@@ -0,0 +1,40 @@
+import { type CommandExecutionResult, type ExecuteCommandOptions } from "../process/command-executor.js";
+export type { CommandExecutionResult };
+export interface ResolvePackageManagerOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    execPath?: string;
+}
+export interface PackageManagerInvocation {
+    executable: string;
+    args: string[];
+}
+export interface RunPackageManagerOptions extends ExecuteCommandOptions {
+    platform?: NodeJS.Platform;
+    execPath?: string;
+}
+/**
+ * 解析包管理器在目标平台上的确定性启动规范。
+ *
+ * 核心设计契约：
+ * - 保持参数边界与数组结构（保留 argv 边界，路径中的空格、引号、&、% 与 ! 原样保留）；
+ * - shell: false 语义，杜绝命令注入与 Node.js DEP0190 警告；
+ * - POSIX 平台保留正常 PATH 命令执行，兼容已有 fake npm 脚本；
+ * - Windows 平台查找遵循 PATH 目录顺序及 PATHEXT 后缀顺序（默认 .COM;.EXE;.BAT;.CMD）；
+ * - PATH 所选工具为唯一事实源，显式传入 env 必须被尊重，绝不从 process.env 漏回其它 PATH；
+ * - Windows 平台原生程序（.exe, .com）直接保留该可执行文件与原数组 args，无需绕过原生版本管理器；
+ * - Windows 平台 Bun 仅支持原生程序，遇到 cmd/bat 包装脚本明确报错，无工具时严禁退回名称；
+ * - Windows 平台 npm.cmd/bat：优先其真实目录布局定位标准 npm-cli.js，由 execPath (Node) 无 shell 启动；
+ * - 仅支持标准可定位 CLI 布局，非标准 wrapper 显式报错，无有效 PATH 工具显式报错。
+ */
+export declare function resolvePackageManagerInvocation(manager: "npm" | "bun", args: readonly string[], options?: ResolvePackageManagerOptions): PackageManagerInvocation;
+/**
+ * 统一执行包管理器命令。
+ *
+ * 运维规范：
+ * - 结合 resolvePackageManagerInvocation 完成无 shell 真实命令定位；
+ * - 通过统一 ProcessDriver 底座执行命令，保留取消、超时、输出流监听与进程树收敛；
+ * - 内部可信工具执行保持标准非阻塞异步。
+ */
+export declare function runPackageManager(manager: "npm" | "bun", args: readonly string[], options?: RunPackageManagerOptions): Promise<CommandExecutionResult>;

package/dist/project/package-manager.js

@@ -0,0 +1,224 @@
+import { realpathSync, statSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { ActionDockError, DEPENDENCY_INSTALL_FAILED, } from "../errors.js";
+import { executeCommand, } from "../process/command-executor.js";
+function isFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch (error) {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+            return false;
+        }
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Failed to inspect file at '${filePath}': ${error?.message ?? String(error)}`, { stage: "resolve", path: filePath, cause: error });
+    }
+}
+/**
+ * 规范化 Windows 环境变量字典。
+ *
+ * 核心契约：
+ * - 保持与 Node.js Windows child_process 相同的字典序排序与大小写去重语义；
+ * - 先由字典序首位键决定该大小写分组的最终获胜键；
+ * - 若获胜键的值为 undefined，则该变量视为未设置（同组后续键不可顶替）；
+ * - 仅保留值非 undefined 的有效键值对，杜绝后续执行器剔除 undefined 时残留失效同名键。
+ */
+function normalizeWindowsEnvironment(env) {
+    const keys = [];
+    for (const key in env) {
+        keys.push(key);
+    }
+    keys.sort();
+    const seenUpper = new Set();
+    const normalized = {};
+    for (const key of keys) {
+        const upper = key.toUpperCase();
+        if (seenUpper.has(upper)) {
+            continue;
+        }
+        seenUpper.add(upper);
+        const value = env[key];
+        if (value !== undefined) {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+function getNormalizedEnvValue(env, targetKey) {
+    const targetUpper = targetKey.toUpperCase();
+    for (const [key, value] of Object.entries(env)) {
+        if (key.toUpperCase() === targetUpper) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function resolvePathExt(rawPathExt) {
+    if (!rawPathExt || rawPathExt.trim() === "") {
+        return [".COM", ".EXE", ".BAT", ".CMD"];
+    }
+    const list = rawPathExt
+        .split(";")
+        .map((e) => e.trim())
+        .filter(Boolean)
+        .map((e) => (e.startsWith(".") ? e : `.${e}`));
+    return list.length > 0 ? list : [".COM", ".EXE", ".BAT", ".CMD"];
+}
+function findMatchingExecutable(dir, manager, ext) {
+    // Windows 文件系统大小写不敏感：优先尝试小写拼写，使返回路径与磁盘上常见的小写文件名一致；
+    // 再回退 PATHEXT 原样与全大写拼写，仅影响返回路径的外现大小写，不改变命中顺序。
+    const lowerCandidate = join(dir, `${manager}${ext.toLowerCase()}`);
+    if (isFile(lowerCandidate)) {
+        return lowerCandidate;
+    }
+    const directCandidate = join(dir, `${manager}${ext}`);
+    if (directCandidate !== lowerCandidate && isFile(directCandidate)) {
+        return directCandidate;
+    }
+    const upperCandidate = join(dir, `${manager}${ext.toUpperCase()}`);
+    if (upperCandidate !== directCandidate &&
+        upperCandidate !== lowerCandidate &&
+        isFile(upperCandidate)) {
+        return upperCandidate;
+    }
+    return null;
+}
+function findNpmCliInDirectory(targetDir) {
+    const candidates = [
+        join(targetDir, "node_modules", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "..", "node_modules", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "..", "npm", "bin", "npm-cli.js"),
+        join(targetDir, "npm", "bin", "npm-cli.js"),
+    ];
+    for (const candidate of candidates) {
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * 解析包管理器在目标平台上的确定性启动规范。
+ *
+ * 核心设计契约：
+ * - 保持参数边界与数组结构（保留 argv 边界，路径中的空格、引号、&、% 与 ! 原样保留）；
+ * - shell: false 语义，杜绝命令注入与 Node.js DEP0190 警告；
+ * - POSIX 平台保留正常 PATH 命令执行，兼容已有 fake npm 脚本；
+ * - Windows 平台查找遵循 PATH 目录顺序及 PATHEXT 后缀顺序（默认 .COM;.EXE;.BAT;.CMD）；
+ * - PATH 所选工具为唯一事实源，显式传入 env 必须被尊重，绝不从 process.env 漏回其它 PATH；
+ * - Windows 平台原生程序（.exe, .com）直接保留该可执行文件与原数组 args，无需绕过原生版本管理器；
+ * - Windows 平台 Bun 仅支持原生程序，遇到 cmd/bat 包装脚本明确报错，无工具时严禁退回名称；
+ * - Windows 平台 npm.cmd/bat：优先其真实目录布局定位标准 npm-cli.js，由 execPath (Node) 无 shell 启动；
+ * - 仅支持标准可定位 CLI 布局，非标准 wrapper 显式报错，无有效 PATH 工具显式报错。
+ */
+export function resolvePackageManagerInvocation(manager, args, options) {
+    const platform = options?.platform ?? process.platform;
+    const execPath = options?.execPath ?? process.execPath;
+    if (platform !== "win32") {
+        return {
+            executable: manager,
+            args: [...args],
+        };
+    }
+    const envSource = options?.env !== undefined ? options.env : process.env;
+    const effectiveEnv = normalizeWindowsEnvironment(envSource);
+    const rawPath = getNormalizedEnvValue(effectiveEnv, "PATH") ?? "";
+    const rawPathExt = getNormalizedEnvValue(effectiveEnv, "PATHEXT");
+    const pathExtList = resolvePathExt(rawPathExt);
+    const cwd = options?.cwd ?? process.cwd();
+    const pathDirs = [];
+    for (const rawEntry of rawPath.split(";")) {
+        let entry = rawEntry.trim();
+        if (!entry)
+            continue;
+        if (entry.startsWith('"') && entry.endsWith('"') && entry.length >= 2) {
+            entry = entry.slice(1, -1).trim();
+        }
+        if (!entry)
+            continue;
+        pathDirs.push(isAbsolute(entry) ? entry : resolve(cwd, entry));
+    }
+    let selectedPath = null;
+    for (const dir of pathDirs) {
+        for (const ext of pathExtList) {
+            const match = findMatchingExecutable(dir, manager, ext);
+            if (match) {
+                selectedPath = match;
+                break;
+            }
+        }
+        if (selectedPath) {
+            break;
+        }
+    }
+    if (!selectedPath) {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Cannot locate ${manager} on Windows: '${manager}' was not found in PATH (${rawPath || "empty"}).`, { stage: "resolve", manager, path: rawPath });
+    }
+    const selectedExt = extname(selectedPath).toLowerCase();
+    const isNative = selectedExt === ".exe" || selectedExt === ".com";
+    if (isNative) {
+        return {
+            executable: selectedPath,
+            args: [...args],
+        };
+    }
+    if (manager === "bun") {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Unsupported bun wrapper at '${selectedPath}': only native executable (.exe, .com) is supported on Windows. Non-standard wrappers cannot be executed without shell.`, { stage: "resolve", manager: "bun", path: selectedPath });
+    }
+    // Windows npm 非原生分支仅支持 .cmd 与 .bat
+    if (selectedExt !== ".cmd" && selectedExt !== ".bat") {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Unsupported npm wrapper extension '${selectedExt}' at '${selectedPath}': only native binaries (.exe, .com) or standard Windows batch scripts (.cmd, .bat) are supported.`, { stage: "resolve", manager: "npm", path: selectedPath });
+    }
+    // Windows npm .cmd / .bat wrapper 解析
+    let realWrapperPath;
+    try {
+        realWrapperPath = realpathSync(selectedPath);
+    }
+    catch (error) {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Failed to resolve realpath for npm wrapper at '${selectedPath}': ${error?.message ?? String(error)}`, { stage: "resolve", manager: "npm", path: selectedPath, cause: error });
+    }
+    let foundCli = null;
+    if (basename(realWrapperPath).toLowerCase() === "npm-cli.js" && isFile(realWrapperPath)) {
+        foundCli = realWrapperPath;
+    }
+    if (!foundCli) {
+        const realDir = dirname(realWrapperPath);
+        foundCli = findNpmCliInDirectory(realDir);
+    }
+    if (!foundCli) {
+        throw new ActionDockError(DEPENDENCY_INSTALL_FAILED, `Unsupported npm wrapper at '${selectedPath}': cannot locate npm-cli.js in standard installation layout. Non-standard npm wrappers cannot be executed without shell.`, { stage: "resolve", manager: "npm", path: selectedPath });
+    }
+    return {
+        executable: execPath,
+        args: [foundCli, ...args],
+    };
+}
+/**
+ * 统一执行包管理器命令。
+ *
+ * 运维规范：
+ * - 结合 resolvePackageManagerInvocation 完成无 shell 真实命令定位；
+ * - 通过统一 ProcessDriver 底座执行命令，保留取消、超时、输出流监听与进程树收敛；
+ * - 内部可信工具执行保持标准非阻塞异步。
+ */
+export async function runPackageManager(manager, args, options) {
+    const platform = options?.platform ?? process.platform;
+    const normalizedEnv = platform === "win32" && options?.env !== undefined
+        ? normalizeWindowsEnvironment(options.env)
+        : options?.env;
+    const invocation = resolvePackageManagerInvocation(manager, args, {
+        cwd: options?.cwd,
+        env: normalizedEnv,
+        platform: options?.platform,
+        execPath: options?.execPath,
+    });
+    return executeCommand(invocation.executable, invocation.args, {
+        cwd: options?.cwd,
+        env: normalizedEnv,
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs,
+        maxOutputBytes: options?.maxOutputBytes,
+        onOutput: options?.onOutput,
+        driver: options?.driver,
+    });
+}

package/dist/project/preparation.d.ts

@@ -0,0 +1,8 @@
+import type { LocalPackagePreparer } from "../invocation/types.js";
+import { type EnsureProjectDependenciesOptions } from "./dependencies.js";
+/**
+ * 创建单个宿主使用的本地包准备器。
+ * 包实例独立缓存就绪状态；同一根调用的同一安装目录共享在途任务。
+ * 共享成功后，各包仍须通过自己的依赖检查；失败不重试、不缓存。
+ */
+export declare function createLocalPackagePreparer(options?: Omit<EnsureProjectDependenciesOptions, "signal">): LocalPackagePreparer;

package/dist/project/preparation.js

@@ -0,0 +1,130 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { ActionDockError, ACTION_CANCELLED, DEPENDENCIES_NOT_READY } from "../errors.js";
+import { ensureProjectDependencies, resolveInstallRoot, } from "./dependencies.js";
+function cancellationError(reason) {
+    return new ActionDockError(ACTION_CANCELLED, reason instanceof Error ? reason.message : String(reason ?? "Package preparation was cancelled"), { cause: reason });
+}
+function isCancellation(error) {
+    return (error instanceof ActionDockError && error.code === ACTION_CANCELLED) ||
+        (error instanceof Error && error.name === "AbortError");
+}
+/**
+ * 创建单个宿主使用的本地包准备器。
+ * 包实例独立缓存就绪状态；同一根调用的同一安装目录共享在途任务。
+ * 共享成功后，各包仍须通过自己的依赖检查；失败不重试、不缓存。
+ */
+export function createLocalPackagePreparer(options = {}) {
+    const readyCache = new Set();
+    const canonicalRootCache = new Map();
+    const inFlightTasks = new Map();
+    function getPackageInstanceKey(target) {
+        let canonicalRoot = canonicalRootCache.get(target.packageRoot);
+        if (!canonicalRoot) {
+            const path = resolve(target.packageRoot);
+            try {
+                canonicalRoot = realpathSync(path);
+                canonicalRootCache.set(target.packageRoot, canonicalRoot);
+            }
+            catch (error) {
+                throw new ActionDockError(DEPENDENCIES_NOT_READY, `Cannot resolve project directory '${path}': ${error?.message || String(error)}`, { path, cause: error });
+            }
+        }
+        return JSON.stringify([
+            target.identity.id,
+            target.identity.instanceId,
+            target.identity.generation,
+            canonicalRoot,
+        ]);
+    }
+    async function waitForTask(task, signal) {
+        let released = false;
+        const releaseWaiter = () => {
+            if (!released) {
+                released = true;
+                task.waiters--;
+            }
+            return task.waiters;
+        };
+        const stopIfUnused = async () => {
+            if (releaseWaiter() !== 0 || task.settled)
+                return;
+            task.controller.abort(signal.reason);
+            try {
+                await task.promise;
+            }
+            catch (error) {
+                if (!isCancellation(error))
+                    throw error;
+            }
+        };
+        if (signal.aborted) {
+            await stopIfUnused();
+            throw cancellationError(signal.reason);
+        }
+        let onAbort;
+        const aborted = new Promise((_resolve, reject) => {
+            onAbort = () => {
+                void stopIfUnused().then(() => reject(cancellationError(signal.reason)), reject);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
+        });
+        try {
+            await Promise.race([task.promise, aborted]);
+            if (signal.aborted)
+                throw cancellationError(signal.reason);
+        }
+        finally {
+            releaseWaiter();
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+    return async function prepareLocalPackage(target, context) {
+        if (context.signal.aborted)
+            throw cancellationError(context.signal.reason);
+        if (!target.packageRoot)
+            return;
+        const instanceKey = getPackageInstanceKey(target);
+        if (readyCache.has(instanceKey))
+            return;
+        const root = resolveInstallRoot(target.packageRoot);
+        if (root.skip || !root.installRoot) {
+            if (context.signal.aborted)
+                throw cancellationError(context.signal.reason);
+            readyCache.add(instanceKey);
+            return;
+        }
+        const flightKey = JSON.stringify([context.rootRunId, root.installRoot]);
+        while (!readyCache.has(instanceKey)) {
+            if (context.signal.aborted)
+                throw cancellationError(context.signal.reason);
+            const existing = inFlightTasks.get(flightKey);
+            if (existing) {
+                existing.waiters++;
+                await waitForTask(existing, context.signal);
+                continue;
+            }
+            const controller = new AbortController();
+            let task;
+            // 先登记任务与等待者，再开始底层检查，兼容同步完成的测试驱动。
+            const promise = Promise.resolve().then(async () => {
+                try {
+                    if (controller.signal.aborted)
+                        throw cancellationError(controller.signal.reason);
+                    await ensureProjectDependencies(target.packageRoot, { ...options, signal: controller.signal });
+                    readyCache.add(instanceKey);
+                }
+                finally {
+                    task.settled = true;
+                    if (inFlightTasks.get(flightKey) === task)
+                        inFlightTasks.delete(flightKey);
+                }
+            });
+            task = { controller, promise, waiters: 1, settled: false };
+            inFlightTasks.set(flightKey, task);
+            await waitForTask(task, context.signal);
+        }
+    };
+}

package/dist/project/transactions.d.ts

@@ -45,7 +45,9 @@ export declare function acquireProjectLock(projectRoot: string, options?: {
 /**
  * 依据恢复后的锁文件异步执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
  */
-export declare function runFrozenInstall(projectRoot: string): Promise<void>;
+export declare function runFrozenInstall(projectRoot: string, options?: {
+    signal?: AbortSignal;
+} | AbortSignal): Promise<void>;
 /**
  * 检查项目是否存在未完成提交的悬空事务。
  */
@@ -60,4 +62,6 @@ export declare function beginTransaction(projectRoot: string, description?: stri
  */
 export declare function recoverPendingTransactions(projectRoot: string, options?: {
     frozenInstall?: boolean;
+    allowInstall?: boolean;
+    signal?: AbortSignal;
 }): Promise<string[]>;