@actiondock/cli 2.13.0 → 2.15.0

package/dist/utils/target.d.ts

@@ -1,5 +1,6 @@
-import { type ActionDockService } from "@actiondock/core";
+import { loadProjectConfig, type ActionDockService, type LocalSkillDirectory } from "@actiondock/core";
 import { type ResolvedTarget } from "@actiondock/core/profile";
+import { type PackageGraph } from "@actiondock/core/graph";
 import type { Command } from "commander";
 import type { CliContext } from "../types.js";
 /**
@@ -30,17 +31,106 @@ export interface TargetResolutionOptions {
     /** 是否允许向非回环地址发送明文 HTTP 请求（对应 --allow-insecure-http） */
     allowInsecureHttp?: boolean;
 }
+/** 仅供清单查询使用的内部解析策略；执行命令默认保持封闭校验。 */
+export interface TargetResolutionStrategy {
+    readonly metadataOnly?: boolean;
+}
 /**
  * 目标拓扑解析单一入口：从命令选项视图解析远端/本地目标拓扑信息。
  *
- * 收拢全部解析字段（profile/server/token/insecure/allowInsecureHttp），
- * 消除命令间逐字段内联复制导致的漂移（如漏传 allowInsecureHttp）。
+ * 显式路径与包标识符分类规则：
+ * - 显式路径形态（以 .、/、~ 开头或包含非 scoped 分隔符）：
+ *   严格作为本地技能或包目录解析；禁止与显式远端选项（--server 或非 local 的 --profile）组合，违规抛出 ArgumentError；
+ *   不受隐式 Profile 或 ACTIONDOCK_SERVER_URL 环境变量改变目标，本地执行优先；
+ *   若本地目录不存在或不合法，抛出 packageNotFoundError；
+ * - 纯词法包标识符（如 pkg.a、@scope/pkg）：
+ *   若存在远端目标（显式 --server、非 local profile 或默认远端环境），严格作为远端包标识解析，绝不因本地 cwd 存在同名目录而劫持为本地执行；
+ *   若无远端目标，正常按本地目标解析。
  *
  * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
  * @param context CLI 上下文
+ * @param strategy 内部解析策略；仅清单查询可跳过单包闭包校验
  * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Service 实例）
  */
-export declare function resolveTargetFromOptions(options: TargetResolutionOptions, context?: CliContext): ResolvedTarget;
+export declare function resolveTargetFromOptions(options: TargetResolutionOptions, context?: CliContext, strategy?: TargetResolutionStrategy): ResolvedTarget;
+/**
+ * 统一计算目标资源引用（Action 或 Playbook）的辅助函数（单一事实源）。
+ *
+ * 规则：
+ * - 远端分支：options.package 存在且资源标识未限定时，前缀拼接 options.package；
+ * - 本地单包技能：资源标识未限定时，前缀拼接真实 packageId（而非路径目录名）；
+ * - 本地复合技能：保持短名，供后续图解析裁决唯一匹配或多包歧义；完全限定名直接透传；
+ * - 普通工程包：非技能且 options.package 存在时，未限定则拼接 options.package。
+ *
+ * @param resourceId 资源标识符（动作名或规程名）
+ * @param options 命令选项视图
+ * @param localSkill 本地技能目录视图
+ */
+export declare function resolveResourceRef(resourceId: string, options: TargetResolutionOptions, localSkill?: LocalSkillDirectory | null): string;
+/**
+ * 统一计算目标 Playbook 引用的辅助函数。
+ */
+export declare function resolvePlaybookRef(playbookId: string, options: TargetResolutionOptions, localSkill?: LocalSkillDirectory | null): string;
+/**
+ * 构造与目标作用域严格对应的 PackageGraph（单一事实源）。
+ *
+ * 封闭保证：
+ * - 当目标为 LocalSkillDirectory 时，仅以 localSkill.packages 显式包集合构建封闭图；
+ *   绝不扫描 cwd 也不扫描全局 Registry/开发软链，防止外部同名包或污染泄漏；
+ * - 当目标为普通本地工程或包 ID 时，维持原有的基于项目根与全局链接表的拓扑图构建模式。
+ */
+export declare function buildScopedPackageGraph(target: CommandTargetResolution, context?: CliContext): PackageGraph;
+/**
+ * 命令目标与动作引用解析结果。
+ */
+export interface CommandTargetResolution {
+    /** 目标拓扑信息 */
+    resolved: ResolvedTarget;
+    /** 是否为远端目标 */
+    isRemote: boolean;
+    /** 本地技能目录或单包元数据作用域（未寻址本地包时为 null） */
+    localSkill: LocalSkillDirectory | null;
+    /** 本地包根目录路径（远端分支为 undefined，未找到为 undefined） */
+    targetPackageRoot?: string;
+    /** 统一计算目标 Action 引用的辅助函数 */
+    resolveActionRef: (actionId: string) => string;
+    /** 统一计算目标 Playbook 引用的辅助函数 */
+    resolvePlaybookRef: (playbookId: string) => string;
+}
+/**
+ * 统一解析 CLI 命令的目标拓扑与包作用域（run, describe, list 等命令的单一事实源）。
+ *
+ * 保证：
+ * - 优先判定目标拓扑；
+ * - 远端目标（remote）完全隔离：不执行任何本地目录探测、清单加载或包根寻址；
+ * - 远端目标动作与规程引用保持原始词法包 ID 拼接（${options.package}/${id}），绝不被本地同名目录或清单 ID 篡改；
+ * - 本地目标默认按封闭技能目录或工程包严格解析；元数据策略仅跳过单包闭包校验；
+ * - 显式目标不存在时透明抛出 packageNotFoundError。
+ */
+export declare function resolveCommandTarget(options: TargetResolutionOptions, context?: CliContext, strategy?: TargetResolutionStrategy): CommandTargetResolution;
+/**
+ * 配置与状态管理目标作用域。
+ */
+export interface TargetPackageScope {
+    /** 解析后的目标拓扑 */
+    resolved: ResolvedTarget;
+    /** 是否为远端目标 */
+    isRemote: boolean;
+    /** 目标包标识（远端为 options.package 原值，本地为工程配置 id 或 "global"） */
+    packageId: string;
+    /** 本地工程根目录（远端分支为 undefined） */
+    root?: string;
+    /** 本地工程配置（远端分支为 undefined） */
+    projConfig?: ReturnType<typeof loadProjectConfig>;
+}
+/**
+ * 校验并拒绝复合技能目录用于配置或状态管理命令（单一事实源）。
+ */
+export declare function assertNotCompositeSkill(packageOption?: string): void;
+/**
+ * 统一解析配置与状态命令的目标作用域（支持单包技能目录、本地工程、远端服务与 --profile local）。
+ */
+export declare function resolveTargetPackageScope(options: TargetResolutionOptions, context?: CliContext): TargetPackageScope;
 /**
  * 高阶服务执行辅助：统一封装「目标解析 → Service 创建 → 业务回调 → try/finally close」样板。
  *

package/dist/utils/target.js

@@ -1,7 +1,8 @@
-import { connectActionDock, createActionDock, createNodePlatform, findProjectRoot, } from "@actiondock/core";
+import { connectActionDock, createActionDock, createNodePlatform, findProjectRoot, inspectLocalPackageDirectory, isExplicitPath, loadProjectConfig, queryLocalPackageDirectory, } from "@actiondock/core";
 import { resolvePackageRoot, } from "@actiondock/core/registry";
 import { resolveTarget, } from "@actiondock/core/profile";
-import { ArgumentError } from "../errors.js";
+import { PackageGraphBuilder, } from "@actiondock/core/graph";
+import { ArgumentError, packageNotFoundError } from "../errors.js";
 /**
  * 统一为 Commander 命令节点挂载目标环境解析相关选项（单一事实源）。
  * 包括：-p/--profile, -s/--server, -t/--token, -k/--insecure, --allow-insecure-http。
@@ -17,24 +18,276 @@ 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");
 }
+/** 本地寻址策略只有一个实现入口，查询与严格闭包均委托核心目录能力。 */
+function inspectCommandDirectory(packageOption, context, strategy) {
+    if (!strategy?.metadataOnly)
+        return inspectLocalPackageDirectory(packageOption);
+    const directory = queryLocalPackageDirectory(packageOption);
+    if (directory)
+        return directory;
+    const root = resolvePackageRoot(packageOption, undefined, context?.customHome);
+    return root ? queryLocalPackageDirectory(root) : null;
+}
 /**
- * 目标拓扑解析单一入口：从命令选项视图解析远端/本地目标拓扑信息。
- *
- * 收拢全部解析字段（profile/server/token/insecure/allowInsecureHttp），
- * 消除命令间逐字段内联复制导致的漂移（如漏传 allowInsecureHttp）。
- *
- * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
- * @param context CLI 上下文
- * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Service 实例）
+ * 内部统一解析目标拓扑与包作用域，单次调用闭包完成全部发现，无跨调用缓存。
  */
-export function resolveTargetFromOptions(options, context) {
-    return resolveTarget({
+function resolveCommandTargetInternal(options, context, strategy) {
+    const isExplicit = options.package ? isExplicitPath(options.package) : false;
+    if (isExplicit) {
+        const hasExplicitServer = Boolean(options.server && options.server.trim());
+        const hasExplicitProfile = Boolean(options.profile && options.profile.trim() && options.profile.trim() !== "local");
+        if (hasExplicitServer || hasExplicitProfile) {
+            throw new ArgumentError("Cannot combine local package/skill directory with remote target options (--server or --profile). Specify a package ID for remote targets, or remove remote target options for local directory execution.");
+        }
+        const localSkill = inspectCommandDirectory(options.package, context, strategy);
+        if (!localSkill) {
+            throw packageNotFoundError(options.package);
+        }
+        return {
+            resolved: {
+                type: "local",
+                profileName: "local",
+            },
+            localSkill,
+            targetPackageRoot: localSkill.root,
+        };
+    }
+    const resolved = resolveTarget({
         profile: options.profile,
         server: options.server,
         token: options.token,
         insecure: options.insecure,
         allowInsecureHttp: options.allowInsecureHttp,
     }, context?.customHome);
+    if (resolved.type === "remote") {
+        return {
+            resolved,
+            localSkill: null,
+            targetPackageRoot: undefined,
+        };
+    }
+    // 本地分支（options.package 为短名或未传）
+    if (options.package) {
+        const localSkill = inspectCommandDirectory(options.package, context, strategy);
+        const targetPackageRoot = localSkill
+            ? localSkill.root
+            : strategy?.metadataOnly
+                ? resolvePackageRoot(options.package, undefined, context?.customHome)
+                : resolveLocalPackageRoot(options.package);
+        if (!targetPackageRoot) {
+            throw packageNotFoundError(options.package);
+        }
+        return {
+            resolved,
+            localSkill,
+            targetPackageRoot,
+        };
+    }
+    const projectRoot = findProjectRoot();
+    return {
+        resolved,
+        localSkill: null,
+        targetPackageRoot: projectRoot || undefined,
+    };
+}
+/**
+ * 目标拓扑解析单一入口：从命令选项视图解析远端/本地目标拓扑信息。
+ *
+ * 显式路径与包标识符分类规则：
+ * - 显式路径形态（以 .、/、~ 开头或包含非 scoped 分隔符）：
+ *   严格作为本地技能或包目录解析；禁止与显式远端选项（--server 或非 local 的 --profile）组合，违规抛出 ArgumentError；
+ *   不受隐式 Profile 或 ACTIONDOCK_SERVER_URL 环境变量改变目标，本地执行优先；
+ *   若本地目录不存在或不合法，抛出 packageNotFoundError；
+ * - 纯词法包标识符（如 pkg.a、@scope/pkg）：
+ *   若存在远端目标（显式 --server、非 local profile 或默认远端环境），严格作为远端包标识解析，绝不因本地 cwd 存在同名目录而劫持为本地执行；
+ *   若无远端目标，正常按本地目标解析。
+ *
+ * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
+ * @param context CLI 上下文
+ * @param strategy 内部解析策略；仅清单查询可跳过单包闭包校验
+ * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Service 实例）
+ */
+export function resolveTargetFromOptions(options, context, strategy) {
+    return resolveCommandTargetInternal(options, context, strategy).resolved;
+}
+/**
+ * 统一计算目标资源引用（Action 或 Playbook）的辅助函数（单一事实源）。
+ *
+ * 规则：
+ * - 远端分支：options.package 存在且资源标识未限定时，前缀拼接 options.package；
+ * - 本地单包技能：资源标识未限定时，前缀拼接真实 packageId（而非路径目录名）；
+ * - 本地复合技能：保持短名，供后续图解析裁决唯一匹配或多包歧义；完全限定名直接透传；
+ * - 普通工程包：非技能且 options.package 存在时，未限定则拼接 options.package。
+ *
+ * @param resourceId 资源标识符（动作名或规程名）
+ * @param options 命令选项视图
+ * @param localSkill 本地技能目录视图
+ */
+export function resolveResourceRef(resourceId, options, localSkill) {
+    if (!options.package)
+        return resourceId;
+    if (localSkill) {
+        if (localSkill.type === "single" && !resourceId.includes("/")) {
+            return `${localSkill.packages[0].packageId}/${resourceId}`;
+        }
+        // 复合技能短名不拼目录名，保持 resourceId 供后续裁决唯一匹配或多包歧义
+        return resourceId;
+    }
+    if (!resourceId.includes("/")) {
+        return `${options.package}/${resourceId}`;
+    }
+    return resourceId;
+}
+/**
+ * 统一计算目标 Playbook 引用的辅助函数。
+ */
+export function resolvePlaybookRef(playbookId, options, localSkill) {
+    return resolveResourceRef(playbookId, options, localSkill);
+}
+/**
+ * 构造与目标作用域严格对应的 PackageGraph（单一事实源）。
+ *
+ * 封闭保证：
+ * - 当目标为 LocalSkillDirectory 时，仅以 localSkill.packages 显式包集合构建封闭图；
+ *   绝不扫描 cwd 也不扫描全局 Registry/开发软链，防止外部同名包或污染泄漏；
+ * - 当目标为普通本地工程或包 ID 时，维持原有的基于项目根与全局链接表的拓扑图构建模式。
+ */
+export function buildScopedPackageGraph(target, context) {
+    if (target.localSkill) {
+        const isSingle = target.localSkill.type === "single";
+        const discovered = target.localSkill.packages.map((pkg) => ({
+            id: pkg.packageId,
+            root: pkg.packageRoot,
+            manifest: pkg.projectConfig,
+            isCurrentProject: isSingle,
+        }));
+        return new PackageGraphBuilder({
+            packages: discovered,
+            root: isSingle ? target.localSkill.packages[0].packageId : undefined,
+        }).buildSync();
+    }
+    return new PackageGraphBuilder({
+        root: target.targetPackageRoot,
+        customHome: context?.customHome,
+        allowDevLinks: true,
+    }).buildSync();
+}
+/**
+ * 统一解析 CLI 命令的目标拓扑与包作用域（run, describe, list 等命令的单一事实源）。
+ *
+ * 保证：
+ * - 优先判定目标拓扑；
+ * - 远端目标（remote）完全隔离：不执行任何本地目录探测、清单加载或包根寻址；
+ * - 远端目标动作与规程引用保持原始词法包 ID 拼接（${options.package}/${id}），绝不被本地同名目录或清单 ID 篡改；
+ * - 本地目标默认按封闭技能目录或工程包严格解析；元数据策略仅跳过单包闭包校验；
+ * - 显式目标不存在时透明抛出 packageNotFoundError。
+ */
+export function resolveCommandTarget(options, context, strategy) {
+    const result = resolveCommandTargetInternal(options, context, strategy);
+    if (result.resolved.type === "remote") {
+        const resolveRemoteRef = (id) => {
+            if (options.package && !id.includes("/")) {
+                return `${options.package}/${id}`;
+            }
+            return id;
+        };
+        return {
+            resolved: result.resolved,
+            isRemote: true,
+            localSkill: null,
+            targetPackageRoot: undefined,
+            resolveActionRef: resolveRemoteRef,
+            resolvePlaybookRef: resolveRemoteRef,
+        };
+    }
+    return {
+        resolved: result.resolved,
+        isRemote: false,
+        localSkill: result.localSkill,
+        targetPackageRoot: result.targetPackageRoot,
+        resolveActionRef: (actionId) => resolveResourceRef(actionId, options, result.localSkill),
+        resolvePlaybookRef: (playbookId) => resolvePlaybookRef(playbookId, options, result.localSkill),
+    };
+}
+/**
+ * 校验并拒绝复合技能目录用于配置或状态管理命令（单一事实源）。
+ */
+export function assertNotCompositeSkill(packageOption) {
+    if (!packageOption)
+        return;
+    const localSkill = inspectLocalPackageDirectory(packageOption);
+    if (localSkill?.type === "composite") {
+        throw new ArgumentError("Multi-package entries do not support config/state management; configure actions using --config and --data-dir.");
+    }
+}
+/**
+ * 统一解析配置与状态命令的目标作用域（支持单包技能目录、本地工程、远端服务与 --profile local）。
+ */
+export function resolveTargetPackageScope(options, context) {
+    // 1. 目标拓扑解析
+    const resolved = resolveTargetFromOptions(options, context);
+    // 2. 远端分支：直接消费 options.package，不触碰本地文件系统
+    if (resolved.type === "remote") {
+        return {
+            resolved,
+            isRemote: true,
+            packageId: options.package || "",
+            root: undefined,
+            projConfig: undefined,
+        };
+    }
+    // 3. 复合技能目录守卫（单一事实源）仅在本地分支生效
+    assertNotCompositeSkill(options.package);
+    // 4. 本地分支：统一解析单包目录、工程包或全局作用域
+    if (options.package) {
+        const localSkill = inspectLocalPackageDirectory(options.package);
+        if (localSkill?.type === "single") {
+            const pkg = localSkill.packages[0];
+            return {
+                resolved,
+                isRemote: false,
+                packageId: pkg.packageId,
+                root: pkg.packageRoot,
+                projConfig: pkg.projectConfig,
+            };
+        }
+        const root = resolveLocalPackageRoot(options.package);
+        if (!root) {
+            throw packageNotFoundError(options.package);
+        }
+        const projConfig = loadProjectConfig(root);
+        return {
+            resolved,
+            isRemote: false,
+            packageId: projConfig.id,
+            root,
+            projConfig,
+        };
+    }
+    // 未指定 -P：当前目录工程探测
+    const root = findProjectRoot();
+    if (root) {
+        try {
+            const projConfig = loadProjectConfig(root);
+            return {
+                resolved,
+                isRemote: false,
+                packageId: projConfig.id,
+                root,
+                projConfig,
+            };
+        }
+        catch {
+            // 当前目录配置损坏时仍允许全局操作
+        }
+    }
+    return {
+        resolved,
+        isRemote: false,
+        packageId: "global",
+        root: undefined,
+        projConfig: undefined,
+    };
 }
 /**
  * 高阶服务执行辅助：统一封装「目标解析 → Service 创建 → 业务回调 → try/finally close」样板。
@@ -56,10 +309,13 @@ export async function withService(options, context, fn, localOptions) {
     if (localOptions?.requireRemote && resolved.type === "local") {
         throw new ArgumentError("'ad runs cancel' is only supported for remote execution targets. Use --profile <name> or --server <url>.");
     }
+    const localSkill = resolved.type === "local" && options.package
+        ? inspectLocalPackageDirectory(options.package)
+        : null;
     // localRoot 仅在 local 分支求值，避免远端模式下触发包寻址副作用
-    const localRoot = resolved.type === "local"
+    const localRoot = resolved.type === "local" && !localSkill
         ? (typeof localOptions?.localRoot === "function" ? localOptions.localRoot() : localOptions?.localRoot) ??
-            findProjectRoot() ??
+            (options.package ? resolveLocalPackageRoot(options.package) : findProjectRoot()) ??
             undefined
         : undefined;
     const recoverOrphans = localOptions?.recoverOrphans ?? (localOptions?.ownDataDir === true);
@@ -70,20 +326,38 @@ export async function withService(options, context, fn, localOptions) {
             insecure: resolved.insecure,
             allowInsecureHttp: resolved.allowInsecureHttp ?? options.allowInsecureHttp,
         })
-        : await createActionDock({
-            type: "local",
-            projectRoot: localRoot,
-            customHome: context?.customHome,
-            dataDir: options.dataDir || context?.dataDir,
-            platform: createNodePlatform({
+        : localSkill
+            ? await createActionDock({
+                type: "local",
+                packages: localSkill.packages.map((pkg) => ({
+                    packageRoot: pkg.packageRoot,
+                    projectConfig: pkg.projectConfig,
+                    dataDir: options.dataDir || context?.dataDir,
+                })),
+                customHome: context?.customHome,
+                dataDir: options.dataDir || context?.dataDir,
+                platform: createNodePlatform({
+                    customHome: context?.customHome,
+                    dataDir: options.dataDir || context?.dataDir,
+                }),
+                autoLoadCurrentProject: false,
+                scanLinkedPackages: false,
+                recoverOrphans,
+            })
+            : await createActionDock({
+                type: "local",
+                projectRoot: localRoot,
                 customHome: context?.customHome,
                 dataDir: options.dataDir || context?.dataDir,
-            }),
-            ...(localOptions?.scanLinkedPackages !== undefined
-                ? { scanLinkedPackages: localOptions.scanLinkedPackages }
-                : undefined),
-            recoverOrphans,
-        });
+                platform: createNodePlatform({
+                    customHome: context?.customHome,
+                    dataDir: options.dataDir || context?.dataDir,
+                }),
+                ...(localOptions?.scanLinkedPackages !== undefined
+                    ? { scanLinkedPackages: localOptions.scanLinkedPackages }
+                    : undefined),
+                recoverOrphans,
+            });
     try {
         await fn(service, resolved);
     }
@@ -97,6 +371,10 @@ export async function withService(options, context, fn, localOptions) {
  */
 export function resolveLocalPackageRoot(pkgId) {
     if (pkgId) {
+        const localSkill = inspectLocalPackageDirectory(pkgId);
+        if (localSkill) {
+            return localSkill.root;
+        }
         return resolvePackageRoot(pkgId);
     }
     return findProjectRoot();

package/package.json

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

package/dist/utils/warning.d.ts

@@ -1,4 +0,0 @@
-/**
- * 实验性特性警告静默函数（统一对齐 @actiondock/core/warning 单一事实源）。
- */
-export { suppressExperimentalWarnings } from "@actiondock/core/warning";

package/dist/utils/warning.js

@@ -1,4 +0,0 @@
-/**
- * 实验性特性警告静默函数（统一对齐 @actiondock/core/warning 单一事实源）。
- */
-export { suppressExperimentalWarnings } from "@actiondock/core/warning";