@actiondock/cli 2.5.1 → 2.7.0

package/dist/utils/spawn.js

@@ -1,9 +1,40 @@
 import { spawn } from "node:child_process";
+import { ArgumentError } from "../errors.js";
+/**
+ * npm/bun 包说明符白名单字符集。
+ *
+ * 覆盖 npm 依赖说明符语法所需的安全字符：
+ * - 字母数字与 `.`（名称与版本组成）
+ * - `@`（scope 前缀与版本定界符）、`/`（scope 分隔符）
+ * - `:`（git 协议与 tag 前缀）、`-` 与 `_`（名称连字符与版本预发布段）
+ * - `+`（semver build 元数据）
+ *
+ * 显式拒绝全部 shell 元字符（空格、引号、`$`、反引号、`&`、`|`、`<`、`>`、`(`、`)` 等），
+ * 从源头消除 win32 shell 拼接模式下的命令注入面。
+ */
+const PACKAGE_SPEC_PATTERN = /^[a-zA-Z0-9@/:\-_.+]+$/;
+/**
+ * 校验包管理器依赖说明符仅包含白名单字符。
+ * 非法字符直接抛出参数错误，不进入子进程拼接链路。
+ *
+ * @param spec 待校验的包说明符（如 `@scope/pkg@^1.2.3`）
+ */
+export function assertSafePackageSpec(spec) {
+    if (!PACKAGE_SPEC_PATTERN.test(spec)) {
+        throw new ArgumentError(`Invalid package specifier '${spec}': only letters, digits, '@', '/', ':', '-', '_', '.', '+' are allowed`);
+    }
+}
 /**
  * 异步执行子进程（Promise 化 spawn），保留 win32 shell 处理与退出码透传。
  *
  * 与 spawnSync 语义对齐：stdio 默认 pipe，进程结束（而非继承输出）后返回聚合结果。
  *
+ * win32 shell 取舍说明：npm 在 Windows 上是 `.cmd` 批处理脚本，Node 20.12+
+ * 针对 CVE-2024-27980 的缓解措施使 `shell:false` 直接 spawn `.cmd` 抛出 EINVAL，
+ * 因此 win32 保留 shell 拼接模式；命令注入面由调用方的
+ * assertSafePackageSpec 白名单前置校验关闭（包说明符仅允许
+ * 字母数字与 `@/:/-_/.+`，全部 shell 元字符被拒绝）。
+ *
  * @param command 可执行文件名
  * @param args 参数列表
  * @param options 附加选项（cwd 与 shell 策略）

package/dist/utils/target.d.ts

@@ -29,12 +29,27 @@ export interface TargetResolutionOptions {
     /** 是否允许向非回环地址发送明文 HTTP 请求（对应 --allow-insecure-http） */
     allowInsecureHttp?: boolean;
 }
+/**
+ * 目标拓扑解析单一入口：从命令选项视图解析远端/本地目标拓扑信息。
+ *
+ * 收拢全部解析字段（profile/server/token/insecure/allowInsecureHttp），
+ * 消除命令间逐字段内联复制导致的漂移（如漏传 allowInsecureHttp）。
+ *
+ * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
+ * @param context CLI 上下文
+ * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Target 实例）
+ */
+export declare function resolveTargetFromOptions(options: TargetResolutionOptions, context?: CliContext): ResolvedTarget;
 /**
  * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
  *
  * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
  * 都保证 target 资源被正确释放，业务异常原样透传。
  *
+ * 默认旁观打开：内部创建的本地 Host 以非收割模式打开存储（不置 recoverOrphans），
+ * 供 ad state / ad runs / ad config 等查询命令与运行中的 serve 进程并发访问同一库；
+ * 需要持有者语义的执行命令通过 localOptions.ownDataDir 显式声明。
+ *
  * @param options 命令选项视图（profile/server/token/package/dataDir/insecure/allowInsecureHttp）
  * @param context CLI 上下文
  * @param fn 业务回调（target 为已创建的门面实例，resolved 为拓扑解析结果）
@@ -45,6 +60,12 @@ export declare function withTarget(options: TargetResolutionOptions, context: Cl
     localRoot?: string | (() => string | undefined);
     /** 是否扫描全局链接包（对应 scanLinkedPackages） */
     scanLinkedPackages?: boolean;
+    /**
+     * 是否以数据目录持有者身份打开本地 Host：true 时 App 存储打开阶段收割遗留孤儿运行。
+     * 执行类命令（ad run）应置 true；查询类命令（state/runs/config/list/describe）
+     * 保持缺省 false，避免误收割并发 serve 进程的在途运行记录。
+     */
+    ownDataDir?: boolean;
 }): Promise<void>;
 /**
  * 仅远端模式目标执行辅助：创建远端 Target 并保证资源释放。

package/dist/utils/target.js

@@ -15,31 +15,51 @@ export function applyTargetOptions(command) {
         .option("-k, --insecure", "Allow insecure server connections (skip TLS certificate validation)")
         .option("--allow-insecure-http", "Allow sending auth token over unencrypted HTTP to non-loopback hosts");
 }
+/**
+ * 目标拓扑解析单一入口：从命令选项视图解析远端/本地目标拓扑信息。
+ *
+ * 收拢全部解析字段（profile/server/token/insecure/allowInsecureHttp），
+ * 消除命令间逐字段内联复制导致的漂移（如漏传 allowInsecureHttp）。
+ *
+ * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
+ * @param context CLI 上下文
+ * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Target 实例）
+ */
+export function resolveTargetFromOptions(options, context) {
+    return resolveTarget({
+        profile: options.profile,
+        server: options.server,
+        token: options.token,
+        insecure: options.insecure,
+        allowInsecureHttp: options.allowInsecureHttp,
+    }, context?.customHome);
+}
 /**
  * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
  *
  * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
  * 都保证 target 资源被正确释放，业务异常原样透传。
  *
+ * 默认旁观打开：内部创建的本地 Host 以非收割模式打开存储（不置 recoverOrphans），
+ * 供 ad state / ad runs / ad config 等查询命令与运行中的 serve 进程并发访问同一库；
+ * 需要持有者语义的执行命令通过 localOptions.ownDataDir 显式声明。
+ *
  * @param options 命令选项视图（profile/server/token/package/dataDir/insecure/allowInsecureHttp）
  * @param context CLI 上下文
  * @param fn 业务回调（target 为已创建的门面实例，resolved 为拓扑解析结果）
  * @param localOptions 本地分支附加选项（如 scanLinkedPackages）与 localRoot 回退策略
  */
 export async function withTarget(options, context, fn, localOptions) {
-    const resolved = resolveTarget({
-        profile: options.profile,
-        server: options.server,
-        token: options.token,
-        insecure: options.insecure,
-        allowInsecureHttp: options.allowInsecureHttp,
-    }, context?.customHome);
+    const resolved = resolveTargetFromOptions(options, context);
     // localRoot 仅在 local 分支求值，避免远端模式下触发包寻址副作用
     const localRoot = resolved.type === "local"
         ? (typeof localOptions?.localRoot === "function" ? localOptions.localRoot() : localOptions?.localRoot) ??
             findProjectRoot() ??
             undefined
         : undefined;
+    // 本地执行命令声明持有者身份时，向 App 层透传收割开关；
+    // 查询命令保持缺省不传，存储以旁观模式打开
+    const appRecoverOrphans = localOptions?.ownDataDir === true ? { recoverOrphans: true } : undefined;
     const target = await createActionDockTarget(resolved.type === "remote"
         ? {
             type: "remote",
@@ -61,6 +81,7 @@ export async function withTarget(options, context, fn, localOptions) {
             ...(localOptions?.scanLinkedPackages !== undefined
                 ? { scanLinkedPackages: localOptions.scanLinkedPackages }
                 : undefined),
+            ...(appRecoverOrphans ? { recoverOrphans: true } : undefined),
         });
     try {
         await fn(target, resolved);
@@ -74,13 +95,7 @@ export async function withTarget(options, context, fn, localOptions) {
  * 适用于 runs cancel 等明确要求远端目标的命令。
  */
 export async function withRemoteTarget(options, context, fn) {
-    const resolved = resolveTarget({
-        profile: options.profile,
-        server: options.server,
-        token: options.token,
-        insecure: options.insecure,
-        allowInsecureHttp: options.allowInsecureHttp,
-    }, context?.customHome);
+    const resolved = resolveTargetFromOptions(options, context);
     const target = await createActionDockTarget({
         type: "remote",
         serverUrl: resolved.serverUrl,

package/dist/utils/utils.d.ts

@@ -20,18 +20,17 @@ export declare function getTargetRoot(packageOption?: string, keyHint?: string):
     key: string;
 };
 /**
- * 聚合命令自身选项与根程序全局选项（如 --json、--envelope、--data-dir 等）。
+ * 聚合命令自身选项与根程序全局选项（如 --json、--data-dir 等）。
  */
 export declare function getEffectiveOptions(rawOptions: any, cmd?: any): any;
 /**
  * 解析意图过滤回退策略。
- * 机器输出模式（--json/--envelope）仅在显式传 --fallback 时回退，
+ * 机器输出模式（--json）仅在显式传 --fallback 时回退，
  * 人类交互模式默认回退（可被 --no-fallback 关闭）。
  */
 export declare function resolveFallbackStrategy(options: {
     fallback?: boolean;
     json?: boolean;
-    envelope?: boolean;
 }): {
     isMachine: boolean;
     shouldFallback: boolean;

package/dist/utils/utils.js

@@ -1,5 +1,5 @@
 import { resolvePackageRoot, findProjectRoot } from "@actiondock/core";
-import { ArgumentError } from "../errors.js";
+import { ArgumentError, notInProjectError, packageNotFoundError } from "../errors.js";
 /**
  * 解析意图字符串（从显式 --intent 或位置模式参数聚合）。
  * 多个关键字使用 '|'（正则逻辑或）连接。
@@ -78,16 +78,16 @@ export function getTargetRoot(packageOption, keyHint) {
     const root = resolvePackageRoot(targetPackage) || (targetPackage ? null : findProjectRoot());
     if (!root) {
         if (targetPackage) {
-            throw new ArgumentError(`Package '${targetPackage}' not found in linked packages or path`);
+            throw packageNotFoundError(targetPackage);
         }
         else {
-            throw new ArgumentError("Not in an ActionDock project (actiondock.json not found). Please specify -P, --package <id> or cd into a project directory.");
+            throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
         }
     }
     return { root, key: effectiveKey };
 }
 /**
- * 聚合命令自身选项与根程序全局选项（如 --json、--envelope、--data-dir 等）。
+ * 聚合命令自身选项与根程序全局选项（如 --json、--data-dir 等）。
  */
 export function getEffectiveOptions(rawOptions, cmd) {
     if (cmd && typeof cmd.optsWithGlobals === "function") {
@@ -97,11 +97,11 @@ export function getEffectiveOptions(rawOptions, cmd) {
 }
 /**
  * 解析意图过滤回退策略。
- * 机器输出模式（--json/--envelope）仅在显式传 --fallback 时回退，
+ * 机器输出模式（--json）仅在显式传 --fallback 时回退，
  * 人类交互模式默认回退（可被 --no-fallback 关闭）。
  */
 export function resolveFallbackStrategy(options) {
-    const isMachine = Boolean(options.json || options.envelope);
+    const isMachine = Boolean(options.json);
     const fallbackExplicit = options.fallback === true ||
         (Array.isArray(process.argv) && process.argv.includes("--fallback"));
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {
@@ -34,11 +34,11 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/builder": "^2.5.1",
-    "@actiondock/core": "^2.5.1",
-    "@actiondock/mcp": "^2.5.1",
-    "@actiondock/runtime-node": "^2.5.1",
-    "@actiondock/sdk": "^2.5.1",
+    "@actiondock/builder": "^2.7.0",
+    "@actiondock/core": "^2.7.0",
+    "@actiondock/mcp": "^2.7.0",
+    "@actiondock/runtime-node": "^2.7.0",
+    "@actiondock/sdk": "^2.7.0",
     "commander": "^13.1.0",
     "selfsigned": "^5.5.0"
   },