@actiondock/core 2.0.11 → 2.2.0

package/dist/profile/manager.js

@@ -0,0 +1,294 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { toSnakeUpperCase } from "../runtime/env.js";
+import { isLoopbackHost } from "../server/security.js";
+import { getActionDockHome } from "../utils/index.js";
+const PROFILE_NAME_REGEX = /^[a-zA-Z0-9_\-\.]+$/;
+/**
+ * 默认初始 Profiles 配置（预设 local 本地环境）。
+ */
+export const DEFAULT_PROFILES_CONFIG = {
+    currentProfile: "local",
+    profiles: {
+        local: {
+            serverUrl: "local",
+            description: "Local execution environment",
+        },
+    },
+};
+/**
+ * 格式化并规范化 Server URL 地址（若未指定协议，本地回环地址默认使用 http://，非本地回环地址默认使用 https://，并移除末尾斜杠）。
+ */
+export function normalizeServerUrl(url) {
+    let cleaned = url.trim().replace(/\/+$/, "");
+    if (!cleaned || cleaned === "local") {
+        return cleaned;
+    }
+    if (!/^https?:\/\//i.test(cleaned)) {
+        let hostname = cleaned;
+        const slashIdx = hostname.indexOf("/");
+        if (slashIdx !== -1) {
+            hostname = hostname.slice(0, slashIdx);
+        }
+        if (hostname.startsWith("[")) {
+            const endBracket = hostname.indexOf("]");
+            if (endBracket !== -1) {
+                hostname = hostname.slice(1, endBracket);
+            }
+        }
+        else {
+            const colonIdx = hostname.indexOf(":");
+            if (colonIdx !== -1) {
+                hostname = hostname.slice(0, colonIdx);
+            }
+        }
+        const isLoopback = isLoopbackHost(hostname);
+        cleaned = `${isLoopback ? "http" : "https"}://${cleaned}`;
+    }
+    return cleaned;
+}
+/**
+ * 获取 profiles.json 配置文件的物理绝对路径（~/.actiondock/profiles.json）。
+ */
+export function getProfilesFilePath(customHome) {
+    const baseDir = getActionDockHome(customHome);
+    return join(baseDir, ".actiondock", "profiles.json");
+}
+/**
+ * 加载并读取 profiles.json 配置文件。
+ */
+export function loadProfiles(customHome) {
+    const filePath = getProfilesFilePath(customHome);
+    if (!existsSync(filePath)) {
+        return structuredClone(DEFAULT_PROFILES_CONFIG);
+    }
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || !parsed.profiles) {
+            return structuredClone(DEFAULT_PROFILES_CONFIG);
+        }
+        return parsed;
+    }
+    catch {
+        return structuredClone(DEFAULT_PROFILES_CONFIG);
+    }
+}
+/**
+ * 保存并写入 profiles.json 配置文件，并严格限制文件权限为 0600。
+ */
+export function saveProfiles(data, customHome) {
+    const filePath = getProfilesFilePath(customHome);
+    const dir = dirname(filePath);
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch {
+            // Ignore on systems where chmod is not supported
+        }
+    }
+    catch {
+        // Ignore
+    }
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    try {
+        chmodSync(filePath, 0o600);
+    }
+    catch {
+        // Ignore on systems where chmod is not supported
+    }
+}
+export function addProfile(name, entry, customHome) {
+    const trimmedName = name.trim();
+    if (!trimmedName) {
+        throw new Error("Profile name cannot be empty");
+    }
+    if (!PROFILE_NAME_REGEX.test(trimmedName)) {
+        throw new Error(`Invalid profile name '${trimmedName}'. Profile names may only contain letters, numbers, hyphens, underscores, and dots.`);
+    }
+    const profilesConfig = loadProfiles(customHome);
+    const normalizedServer = normalizeServerUrl(entry.serverUrl);
+    profilesConfig.profiles[trimmedName] = {
+        serverUrl: normalizedServer,
+        token: entry.token?.trim() || undefined,
+        tokenEnv: entry.tokenEnv?.trim() || undefined,
+        description: entry.description?.trim() || undefined,
+    };
+    saveProfiles(profilesConfig, customHome);
+}
+export function removeProfile(name, customHome) {
+    const trimmedName = name.trim();
+    const profilesConfig = loadProfiles(customHome);
+    if (!profilesConfig.profiles[trimmedName]) {
+        return false;
+    }
+    delete profilesConfig.profiles[trimmedName];
+    if (profilesConfig.currentProfile === trimmedName) {
+        profilesConfig.currentProfile = "local";
+    }
+    saveProfiles(profilesConfig, customHome);
+    return true;
+}
+export function useProfile(name, customHome) {
+    const trimmedName = name.trim();
+    const profilesConfig = loadProfiles(customHome);
+    if (trimmedName !== "local" && !profilesConfig.profiles[trimmedName]) {
+        throw new Error(`Profile '${trimmedName}' not found. Use 'ad profile list' to see available profiles or 'ad profile add' to register one.`);
+    }
+    profilesConfig.currentProfile = trimmedName;
+    saveProfiles(profilesConfig, customHome);
+}
+export function getProfile(name, customHome) {
+    const profilesConfig = loadProfiles(customHome);
+    return profilesConfig.profiles[name.trim()];
+}
+export function listProfiles(customHome) {
+    const profilesConfig = loadProfiles(customHome);
+    const current = profilesConfig.currentProfile || "local";
+    const entries = [];
+    // Ensure 'local' is listed
+    if (!profilesConfig.profiles["local"]) {
+        entries.push({
+            name: "local",
+            isCurrent: current === "local",
+            entry: {
+                serverUrl: "local",
+                description: "Local execution environment",
+            },
+        });
+    }
+    for (const [name, entry] of Object.entries(profilesConfig.profiles)) {
+        entries.push({
+            name,
+            isCurrent: name === current,
+            entry,
+        });
+    }
+    return entries;
+}
+/**
+ * Resolves token following multi-tier precedence:
+ * 1. CLI explicit --token
+ * 2. profile.tokenEnv specified environment variable
+ * 3. Derived profile environment variable: ACTIONDOCK_<PROFILE>_TOKEN or <PROFILE>_TOKEN
+ * 4. Stored token in profiles.json (deprecated)
+ * 5. Global ACTIONDOCK_TOKEN
+ */
+export function resolveProfileToken(profileName, entry, explicitToken) {
+    // 1. Explicit CLI --token
+    if (explicitToken && explicitToken.trim()) {
+        return { token: explicitToken.trim(), source: "cli" };
+    }
+    // 2. Explicit tokenEnv in profile
+    if (entry?.tokenEnv && entry.tokenEnv.trim()) {
+        const envKey = entry.tokenEnv.trim();
+        const envVal = process.env[envKey];
+        if (envVal !== undefined && envVal.trim()) {
+            return { token: envVal.trim(), source: "tokenEnv" };
+        }
+    }
+    // 3. Derived profile environment variable: ACTIONDOCK_<PROFILE>_TOKEN / <PROFILE>_TOKEN
+    if (profileName && profileName !== "local") {
+        const snakeName = toSnakeUpperCase(profileName);
+        const candidate1 = `ACTIONDOCK_${snakeName}_TOKEN`;
+        const candidate2 = `${snakeName}_TOKEN`;
+        if (process.env[candidate1] && process.env[candidate1].trim()) {
+            return { token: process.env[candidate1].trim(), source: "profileEnv" };
+        }
+        if (process.env[candidate2] && process.env[candidate2].trim()) {
+            return { token: process.env[candidate2].trim(), source: "profileEnv" };
+        }
+    }
+    // 4. Stored token in profiles.json (deprecated fallback)
+    if (entry?.token && entry.token.trim()) {
+        return { token: entry.token.trim(), source: "profile" };
+    }
+    // 5. Global ACTIONDOCK_TOKEN
+    if (process.env.ACTIONDOCK_TOKEN && process.env.ACTIONDOCK_TOKEN.trim()) {
+        return { token: process.env.ACTIONDOCK_TOKEN.trim(), source: "globalEnv" };
+    }
+    return { token: undefined, source: "none" };
+}
+export function resolveTarget(options, customHome) {
+    // 1. Explicit CLI --server flag
+    if (options?.server && options.server.trim()) {
+        const resolvedToken = resolveProfileToken(undefined, undefined, options.token);
+        return {
+            type: "remote",
+            serverUrl: normalizeServerUrl(options.server),
+            token: resolvedToken.token,
+            tokenSource: resolvedToken.source,
+        };
+    }
+    const profilesConfig = loadProfiles(customHome);
+    // 2. Explicit CLI --profile flag
+    if (options?.profile && options.profile.trim()) {
+        const pName = options.profile.trim();
+        if (pName === "local") {
+            return { type: "local", profileName: "local" };
+        }
+        const found = profilesConfig.profiles[pName];
+        if (!found) {
+            throw new Error(`Profile '${pName}' not found. Configure it with 'ad profile add ${pName} --server <url>'`);
+        }
+        const resolvedToken = resolveProfileToken(pName, found, options.token);
+        return {
+            type: "remote",
+            profileName: pName,
+            serverUrl: found.serverUrl,
+            token: resolvedToken.token,
+            tokenSource: resolvedToken.source,
+        };
+    }
+    // 3. Environment variable ACTIONDOCK_SERVER_URL
+    if (process.env.ACTIONDOCK_SERVER_URL && process.env.ACTIONDOCK_SERVER_URL.trim()) {
+        const resolvedToken = resolveProfileToken(undefined, undefined, options?.token);
+        return {
+            type: "remote",
+            serverUrl: normalizeServerUrl(process.env.ACTIONDOCK_SERVER_URL),
+            token: resolvedToken.token,
+            tokenSource: resolvedToken.source,
+        };
+    }
+    // 4. Environment variable ACTIONDOCK_PROFILE
+    if (process.env.ACTIONDOCK_PROFILE && process.env.ACTIONDOCK_PROFILE.trim()) {
+        const pName = process.env.ACTIONDOCK_PROFILE.trim();
+        if (pName === "local") {
+            return { type: "local", profileName: "local" };
+        }
+        const found = profilesConfig.profiles[pName];
+        if (!found) {
+            throw new Error(`Profile '${pName}' (from ACTIONDOCK_PROFILE) not found. Configure it with 'ad profile add ${pName} --server <url>'`);
+        }
+        const resolvedToken = resolveProfileToken(pName, found, options?.token);
+        return {
+            type: "remote",
+            profileName: pName,
+            serverUrl: found.serverUrl,
+            token: resolvedToken.token,
+            tokenSource: resolvedToken.source,
+        };
+    }
+    // 5. Current Profile in config
+    const current = profilesConfig.currentProfile;
+    if (current && current !== "local") {
+        const found = profilesConfig.profiles[current];
+        if (found && found.serverUrl && found.serverUrl !== "local") {
+            const resolvedToken = resolveProfileToken(current, found, options?.token);
+            return {
+                type: "remote",
+                profileName: current,
+                serverUrl: found.serverUrl,
+                token: resolvedToken.token,
+                tokenSource: resolvedToken.source,
+            };
+        }
+    }
+    // 6. Default to local
+    return { type: "local", profileName: "local" };
+}

package/dist/profile/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 单个远端配置环境（Profile）实体定义。
+ */
+export interface ProfileEntry {
+    /** 远端 ActionDock 服务端地址（如 "http://192.168.1.100:5177" 或 "local"） */
+    serverUrl: string;
+    /**
+     * 存储在配置文件中的明文鉴权 Token。
+     * @deprecated 强烈建议使用 tokenEnv 或标准环境变量（如 ACTIONDOCK_<PROFILE>_TOKEN），避免明文持久化
+     */
+    token?: string;
+    /** 指定从哪一个操作系统环境变量名动态读取 Token */
+    tokenEnv?: string;
+    /** 该机器/环境的描述信息 */
+    description?: string;
+}
+/**
+ * 全局 profiles.json 配置文件结构契约。
+ */
+export interface ProfilesConfig {
+    /** 当前激活的默认 Profile 名称（默认为 "local"） */
+    currentProfile?: string;
+    /** 已配置的 Profile 字典映射表 */
+    profiles: Record<string, ProfileEntry>;
+}
+/**
+ * Token 解析命中来源枚举。
+ */
+export type TokenResolutionSource = "cli" | "tokenEnv" | "profileEnv" | "profile" | "globalEnv" | "none";
+/**
+ * 经过解析后确定的最终执行目标环境。
+ */
+export interface ResolvedTarget {
+    /** 执行环境类型：local (本地 Node.js 进程) 或 remote (远端 HTTP Server) */
+    type: "local" | "remote";
+    /** 命中的 Profile 名称 */
+    profileName?: string;
+    /** 远端 Server URL */
+    serverUrl?: string;
+    /** 解析出的有效鉴权 Token */
+    token?: string;
+    /** Token 数据来源 */
+    tokenSource?: TokenResolutionSource;
+}
+/**
+ * 远端服务器健康探测与时延检测结果。
+ */
+export interface RemoteHealthResult {
+    /** 服务端是否连通且鉴权成功 */
+    ok: boolean;
+    /** 服务端状态标识（如 "ok"） */
+    status?: string;
+    /** 远端 ActionDock 版本号 */
+    version?: string;
+    /** 远端服务运行时间（秒） */
+    uptime?: number;
+    /** 网络往返延迟（毫秒） */
+    latencyMs: number;
+    /** 探测失败时的错误信息 */
+    error?: string;
+}

package/dist/profile/types.js

@@ -0,0 +1 @@
+export {};

package/dist/project/closure.d.ts

@@ -0,0 +1,25 @@
+export interface EnsureDependencyClosureOptions {
+    /**
+     * 自定义依赖安装回调函数（便于单测 Mock 与自定义扩展）
+     */
+    ensure?: (root: string) => boolean | Promise<boolean>;
+    /**
+     * 自定义 ActionDock 家目录
+     */
+    customHome?: string;
+}
+export interface DependencyClosureResult {
+    /** 成功执行依赖安装或更新的项目根路径列表 */
+    installed: string[];
+    /** 无法在注册表中解析包引用的警告列表 */
+    warnings: string[];
+}
+/**
+ * 广度优先遍历 (BFS) uses 声明的跨包依赖闭包，对涉及的每个项目包逐一执行依赖预装（ensureProjectDependencies）。
+ * 内部已尊重 ACTIONDOCK_AUTO_INSTALL=false 环境变量。
+ *
+ * @param roots 根项目目录列表
+ * @param opts 选项参数
+ * @returns 安装成功的路径列表及警告信息
+ */
+export declare function ensureDependencyClosure(roots: string[], opts?: EnsureDependencyClosureOptions): Promise<DependencyClosureResult>;

package/dist/project/closure.js

@@ -0,0 +1,68 @@
+import { resolve } from "node:path";
+import { ActionResolver } from "../catalog/action-resolver.js";
+import { resolvePackageRoot } from "../registry/registry.js";
+import { ensureProjectDependencies } from "./loader.js";
+import { loadManifest } from "./manifest.js";
+/**
+ * 广度优先遍历 (BFS) uses 声明的跨包依赖闭包，对涉及的每个项目包逐一执行依赖预装（ensureProjectDependencies）。
+ * 内部已尊重 ACTIONDOCK_AUTO_INSTALL=false 环境变量。
+ *
+ * @param roots 根项目目录列表
+ * @param opts 选项参数
+ * @returns 安装成功的路径列表及警告信息
+ */
+export async function ensureDependencyClosure(roots, opts = {}) {
+    const seen = new Set();
+    const queue = [...roots];
+    const installed = [];
+    const warnings = [];
+    while (queue.length > 0) {
+        const rawRoot = queue.shift();
+        if (!rawRoot)
+            continue;
+        const root = resolve(rawRoot);
+        if (seen.has(root))
+            continue;
+        seen.add(root);
+        const ensureFn = opts.ensure ?? ensureProjectDependencies;
+        const wasInstalled = await ensureFn(root);
+        if (wasInstalled) {
+            installed.push(root);
+        }
+        let manifest;
+        try {
+            manifest = loadManifest(root);
+        }
+        catch {
+            continue;
+        }
+        if (!manifest || !manifest.actions)
+            continue;
+        for (const actionEntry of Object.values(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 {
+                    warnings.push(`uses 声明 '${rawRef}' 未在注册表中解析到包`);
+                    continue;
+                }
+                if (parsed.packageId) {
+                    const depRoot = resolvePackageRoot(parsed.packageId, root, opts.customHome);
+                    if (depRoot) {
+                        queue.push(resolve(depRoot));
+                    }
+                    else {
+                        warnings.push(`uses 声明 '${rawRef}' 未在注册表中解析到包`);
+                    }
+                }
+            }
+        }
+    }
+    return { installed, warnings };
+}

package/dist/project/digest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 解析 JSON 文本并在检测到重复键时抛出错误。
+ * 遵循 RFC 8785 清单校验规范：解析阶段必须率先拦截并拒绝重复键。
+ */
+export declare function parseJsonWithoutDuplicates<T = unknown>(jsonText: string): T;
+/**
+ * 依据 RFC 8785 规范化 JSON 数据。
+ * 规则：
+ * - 对象属性依据 UTF-16 代码单元进行升序排序；
+ * - 符号与键值之间不包含多余空白字符；
+ * - 浮点数与整数遵循 ECMAScript 规范序列化（负零转为零，拒绝非有限数）；
+ * - 字符串转义严格遵循标准规范；
+ * - 数组保持原有顺序且元素递归规范化。
+ */
+export declare function canonicalizeJson(value: unknown): string;
+/**
+ * 计算任意 JSON 结构或 JSON 字符串的 SHA-256 规范化摘要。
+ * 输出格式为 sha256-<hex>。
+ */
+export declare function computeDigest(value: unknown): string;
+/**
+ * 计算 Action 清单对象的唯一确定性 RFC 8785 摘要。
+ * 清单中的等价空格变化与字段顺序不会改变摘要结果。
+ */
+export declare function computeManifestDigest(manifest: unknown): string;
+/**
+ * 校验给定清单的摘要是否与期望值一致。
+ */
+export declare function verifyManifestDigest(manifest: unknown, expectedDigest: string): boolean;