@actiondock/core 2.5.0 → 2.6.0

package/dist/profile/client-state.d.ts

@@ -0,0 +1,56 @@
+import type { RemoteClientRequestOptions } from "./client-transport.js";
+/**
+ * 远端状态存储域端点。
+ */
+/**
+ * 列出远端状态键（可按包、Action、命名空间与前缀过滤）。
+ */
+export declare function fetchRemoteStateList(serverUrl: string, token?: string, options?: {
+    package?: string;
+    action?: string;
+    namespace?: string;
+    prefix?: string;
+} & RemoteClientRequestOptions): Promise<{
+    ok: boolean;
+    packageId: string;
+    keys: string[];
+}>;
+/**
+ * 读取单个远端状态键的值。
+ */
+export declare function getRemoteStateKey(serverUrl: string, key: string, token?: string, options?: {
+    package?: string;
+    action?: string;
+    namespace?: string;
+} & RemoteClientRequestOptions): Promise<any>;
+/**
+ * 写入单个远端状态键（可携带 TTL 过期时间）。
+ */
+export declare function setRemoteStateKey(serverUrl: string, key: string, value: unknown, token?: string, options?: {
+    package?: string;
+    action?: string;
+    namespace?: string;
+    ttl?: number;
+} & RemoteClientRequestOptions): Promise<any>;
+/**
+ * 删除单个远端状态键。
+ */
+export declare function deleteRemoteStateKey(serverUrl: string, key: string, token?: string, options?: {
+    package?: string;
+    action?: string;
+    namespace?: string;
+} & RemoteClientRequestOptions): Promise<any>;
+/**
+ * 批量清除远端状态键（可按包、Action、命名空间、前缀与全量标志过滤）。
+ */
+export declare function clearRemoteState(serverUrl: string, token?: string, options?: {
+    package?: string;
+    action?: string;
+    namespace?: string;
+    prefix?: string;
+    all?: boolean;
+} & RemoteClientRequestOptions): Promise<{
+    ok: boolean;
+    packageId: string;
+    clearedCount: number;
+}>;

package/dist/profile/client-state.js

@@ -0,0 +1,83 @@
+import { buildQueryStringPreservingEmpty, fetchRemoteJson } from "./client-query.js";
+/**
+ * 远端状态存储域端点。
+ */
+/**
+ * 列出远端状态键（可按包、Action、命名空间与前缀过滤）。
+ */
+export async function fetchRemoteStateList(serverUrl, token, options) {
+    return fetchRemoteJson(serverUrl, `/api/v2/state${buildQueryStringPreservingEmpty({
+        package: options?.package,
+        action: options?.action,
+        namespace: options?.namespace,
+        prefix: options?.prefix,
+    })}`, token, {
+        errorPrefix: "Failed to list remote state keys",
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}
+/**
+ * 读取单个远端状态键的值。
+ */
+export async function getRemoteStateKey(serverUrl, key, token, options) {
+    return fetchRemoteJson(serverUrl, `/api/v2/state/${encodeURIComponent(key)}${buildQueryStringPreservingEmpty({
+        package: options?.package,
+        action: options?.action,
+        namespace: options?.namespace,
+    })}`, token, {
+        errorPrefix: `Failed to fetch remote state key '${key}'`,
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}
+/**
+ * 写入单个远端状态键（可携带 TTL 过期时间）。
+ */
+export async function setRemoteStateKey(serverUrl, key, value, token, options) {
+    return fetchRemoteJson(serverUrl, `/api/v2/state/${encodeURIComponent(key)}`, token, {
+        method: "PUT",
+        body: {
+            value,
+            package: options?.package,
+            action: options?.action,
+            namespace: options?.namespace,
+            ttl: options?.ttl,
+        },
+        errorPrefix: `Failed to set remote state key '${key}'`,
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}
+/**
+ * 删除单个远端状态键。
+ */
+export async function deleteRemoteStateKey(serverUrl, key, token, options) {
+    return fetchRemoteJson(serverUrl, `/api/v2/state/${encodeURIComponent(key)}${buildQueryStringPreservingEmpty({
+        package: options?.package,
+        action: options?.action,
+        namespace: options?.namespace,
+    })}`, token, {
+        method: "DELETE",
+        errorPrefix: `Failed to delete remote state key '${key}'`,
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}
+/**
+ * 批量清除远端状态键（可按包、Action、命名空间、前缀与全量标志过滤）。
+ */
+export async function clearRemoteState(serverUrl, token, options) {
+    return fetchRemoteJson(serverUrl, "/api/v2/state/clear", token, {
+        method: "POST",
+        body: options || {},
+        errorPrefix: "Failed to clear remote state",
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}

package/dist/profile/client-transport.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 远端客户端传输层。
+ *
+ * 职责单一聚焦：鉴权头拼装、明文传输安全校验、insecure dispatcher 注入
+ * 与 v2 -> v1 协议回退，作为全部远端端点函数的传输样板单一事实源。
+ */
+/**
+ * 校验在携带认证 Token 时传输层协议是否安全。
+ * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
+ * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免。
+ */
+export declare function assertSecureTransport(serverUrl: string, token?: string, allowInsecureHttpOrOptions?: boolean | {
+    allowInsecureHttp?: boolean;
+    insecure?: boolean;
+}, insecureArg?: boolean): void;
+/**
+ * 构造携带鉴权信息的标准请求头。
+ */
+export declare function buildHeaders(token?: string): Record<string, string>;
+/**
+ * 远端请求通用控制选项。
+ */
+export interface RemoteClientRequestOptions {
+    /** 是否允许通过非回环明文 HTTP 发送认证 Token */
+    allowInsecureHttp?: boolean;
+    /** 是否跳过服务端 TLS 证书合法性校验 */
+    insecure?: boolean;
+    /** 自定义底层 HTTP 调度器（平台中立） */
+    dispatcher?: unknown;
+}
+/** 远端请求描述选项。 */
+export interface RemoteFetchInit {
+    /** HTTP 方法（默认 GET） */
+    method?: string;
+    /** JSON 序列化请求体 */
+    body?: unknown;
+    /** 额外合并的请求头 */
+    headers?: Record<string, string>;
+    /** 中断信号 */
+    signal?: AbortSignal;
+}
+/**
+ * 构建绑定传输上下文（Token、安全选项与调度器）的远端请求函数。
+ *
+ * 单一事实源收敛所有 fetchRemoteXxx 端点的传输样板：
+ * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验、
+ * insecure dispatcher 注入与 v2 -> v1 协议回退均在此统一处理。
+ */
+export declare function createRemoteFetch(serverUrl: string, token?: string, options?: RemoteClientRequestOptions): (path: string, init?: RemoteFetchInit) => Promise<Response>;
+/**
+ * 携带协议回退的远端请求单一入口：先打 /api/v2/ 路由，404 时改打 /api/v1/ 路由。
+ *
+ * v1 回退请求若网络失败则沿用 v2 响应，保留原始状态与错误体供上层透传。
+ */
+export declare function fetchWithProtocolFallback(base: string, path: string, init: RequestInit & {
+    dispatcher?: any;
+}): Promise<Response>;
+/**
+ * 列出指定路由的全部协议版本候选 URL（按优先级排序，含原始路由自身）。
+ */
+export declare function listProtocolRouteCandidates(base: string, path: string): string[];

package/dist/profile/client-transport.js

@@ -0,0 +1,155 @@
+import { isLoopbackHost } from "../utils/net.js";
+import { normalizeServerUrl } from "./manager.js";
+import { getInsecureDispatcher } from "../server/dispatcher.js";
+/**
+ * 远端客户端传输层。
+ *
+ * 职责单一聚焦：鉴权头拼装、明文传输安全校验、insecure dispatcher 注入
+ * 与 v2 -> v1 协议回退，作为全部远端端点函数的传输样板单一事实源。
+ */
+/**
+ * 校验在携带认证 Token 时传输层协议是否安全。
+ * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
+ * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免。
+ */
+export function assertSecureTransport(serverUrl, token, allowInsecureHttpOrOptions, insecureArg) {
+    if (!token || !token.trim()) {
+        return;
+    }
+    let allowInsecureHttp = false;
+    let insecure = false;
+    if (typeof allowInsecureHttpOrOptions === "object" && allowInsecureHttpOrOptions !== null) {
+        allowInsecureHttp = Boolean(allowInsecureHttpOrOptions.allowInsecureHttp);
+        insecure = Boolean(allowInsecureHttpOrOptions.insecure);
+    }
+    else {
+        allowInsecureHttp = Boolean(allowInsecureHttpOrOptions);
+        insecure = Boolean(insecureArg);
+    }
+    const allow = allowInsecureHttp ||
+        insecure ||
+        (typeof process !== "undefined" &&
+            (process.env?.ACTIONDOCK_ALLOW_INSECURE_HTTP === "true" ||
+                process.env?.ACTIONDOCK_ALLOW_INSECURE_HTTP === "1" ||
+                process.env?.ACTIONDOCK_INSECURE === "true" ||
+                process.env?.ACTIONDOCK_INSECURE === "1"));
+    if (allow) {
+        return;
+    }
+    const base = normalizeServerUrl(serverUrl);
+    if (base.startsWith("http://")) {
+        try {
+            const parsed = new URL(base);
+            if (!isLoopbackHost(parsed.hostname)) {
+                const err = new Error(`Insecure HTTP connection with authentication token to non-loopback host '${parsed.hostname}' is prohibited. Use HTTPS or pass --allow-insecure-http to override.`);
+                err.code = "INSECURE_TRANSPORT";
+                throw err;
+            }
+        }
+        catch (e) {
+            if (e.code === "INSECURE_TRANSPORT") {
+                throw e;
+            }
+        }
+    }
+}
+/**
+ * 构造携带鉴权信息的标准请求头。
+ */
+export function buildHeaders(token) {
+    const headers = {
+        Accept: "application/json",
+    };
+    if (token && token.trim()) {
+        headers.Authorization = `Bearer ${token.trim()}`;
+    }
+    return headers;
+}
+/**
+ * 构建绑定传输上下文（Token、安全选项与调度器）的远端请求函数。
+ *
+ * 单一事实源收敛所有 fetchRemoteXxx 端点的传输样板：
+ * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验、
+ * insecure dispatcher 注入与 v2 -> v1 协议回退均在此统一处理。
+ */
+export function createRemoteFetch(serverUrl, token, options) {
+    assertSecureTransport(serverUrl, token, {
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+    });
+    const base = normalizeServerUrl(serverUrl);
+    const headers = buildHeaders(token);
+    return async (path, init = {}) => {
+        const method = init.method || "GET";
+        const mergedHeaders = { ...headers };
+        if (init.body !== undefined || init.headers) {
+            for (const [k, v] of Object.entries(init.headers || {})) {
+                mergedHeaders[k] = v;
+            }
+            if (init.body !== undefined) {
+                mergedHeaders["Content-Type"] = mergedHeaders["Content-Type"] || "application/json";
+            }
+        }
+        const fetchInit = {
+            method,
+            headers: mergedHeaders,
+            body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+            signal: init.signal,
+        };
+        if (options?.dispatcher) {
+            fetchInit.dispatcher = options.dispatcher;
+        }
+        else if (options?.insecure) {
+            fetchInit.dispatcher = getInsecureDispatcher();
+        }
+        return fetchWithProtocolFallback(base, path, fetchInit);
+    };
+}
+/** v2 优先、v1 兼容回退的协议版本优先级列表。 */
+const PROTOCOL_PREFERENCE = ["v2", "v1"];
+/**
+ * 判定响应是否应当触发下一优先级协议重试。
+ * 仅 404（路由不存在）回退；其余状态（如 401、403、500）原样透传。
+ */
+function shouldFallbackToNextProtocol(res) {
+    return res.status === 404;
+}
+/**
+ * 携带协议回退的远端请求单一入口：先打 /api/v2/ 路由，404 时改打 /api/v1/ 路由。
+ *
+ * v1 回退请求若网络失败则沿用 v2 响应，保留原始状态与错误体供上层透传。
+ */
+export async function fetchWithProtocolFallback(base, path, init) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const isVersioned = /^\/api\/v\d+\//.test(normalizedPath);
+    let res = await fetch(`${base}${normalizedPath}`, init);
+    if (!isVersioned || !shouldFallbackToNextProtocol(res)) {
+        return res;
+    }
+    const candidates = listProtocolRouteCandidates(base, normalizedPath);
+    // 首个候选即当前已返回 404 的路由，从次优先级继续尝试
+    for (let i = 1; i < candidates.length; i++) {
+        try {
+            const fallbackRes = await fetch(candidates[i], init);
+            if (!shouldFallbackToNextProtocol(fallbackRes)) {
+                return fallbackRes;
+            }
+        }
+        catch {
+            // 回退请求网络异常时保持既有 v2 响应，由上层统一处理
+        }
+    }
+    return res;
+}
+/**
+ * 列出指定路由的全部协议版本候选 URL（按优先级排序，含原始路由自身）。
+ */
+export function listProtocolRouteCandidates(base, path) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const versionMatch = normalizedPath.match(/^\/api\/(v\d+)\/(.*)$/);
+    if (!versionMatch) {
+        return [`${base}${normalizedPath}`];
+    }
+    const rest = versionMatch[2];
+    return PROTOCOL_PREFERENCE.map((version) => `${base}/api/${version}/${rest}`);
+}

package/dist/profile/client.d.ts

@@ -1,145 +1,26 @@
-import type { ExecutionResult, RunRecord } from "@actiondock/sdk";
-import type { RemoteHealthResult } from "./types.js";
 /**
- * 校验在携带认证 Token 时传输层协议是否安全。
- * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
- * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免。
- */
-export declare function assertSecureTransport(serverUrl: string, token?: string, allowInsecureHttpOrOptions?: boolean | {
-    allowInsecureHttp?: boolean;
-    insecure?: boolean;
-}, insecureArg?: boolean): void;
-/**
- * 远端请求通用控制选项。
- */
-export interface RemoteClientRequestOptions {
-    /** 是否允许通过非回环明文 HTTP 发送认证 Token */
-    allowInsecureHttp?: boolean;
-    /** 是否跳过服务端 TLS 证书合法性校验 */
-    insecure?: boolean;
-    /** 自定义底层 HTTP 调度器（平台中立） */
-    dispatcher?: unknown;
-}
-/**
- * 调用远端 ActionDock 服务端执行 Action 时的选项参数。
- */
-export interface RemoteExecuteOptions extends RemoteClientRequestOptions {
-    /** 动态配置覆盖 */
-    configOverrides?: Record<string, unknown>;
-    /** 鉴权 Bearer Token */
-    token?: string;
-    /** 超时毫秒数 */
-    timeoutMs?: number;
-    /** 中断信号 */
-    signal?: AbortSignal;
-    /** 幂等请求去重标识 */
-    requestId?: string;
-    /** 是否异步触发（202 Accepted 立即返回 runId） */
-    async?: boolean;
-}
-/**
- * 远端 Action 执行结果信封对象。
- */
-export type RemoteExecutionResult<T = unknown> = ExecutionResult<T> & {
-    status?: string;
-};
-/**
- * 探测指定远端 ActionDock 服务的健康状态与网络延迟。
+ * 远端 Profile 客户端聚合入口。
+ *
+ * 历史上全部端点函数集中于单一 client.ts（约 950 行），现按域拆分为
+ * 单一职责模块，此处仅保留聚合 re-export，导入路径 ./client 与
+ * @actiondock/core 的公共导出面保持完全兼容。
  *
- * @param serverUrl 目标服务端地址
- * @param token 鉴权 Token（可选）
- * @param timeoutMs 探测超时时间（默认 5000ms）
- * @param options 传输与安全控制选项
+ * 模块划分：
+ * - client-transport：传输层（鉴权头、明文校验、协议回退）
+ * - client-query：共享请求与查询构造层
+ * - client-health：健康检查
+ * - client-actions：执行与 Action 查询
+ * - client-playbooks：Playbook 规程查询
+ * - client-runs：运行记录管理
+ * - client-state：状态存储管理
+ * - client-config：配置管理
  */
-export declare function checkRemoteHealth(serverUrl: string, token?: string, timeoutMs?: number, options?: RemoteClientRequestOptions): Promise<RemoteHealthResult>;
-export declare function executeRemoteAction<T = unknown>(serverUrl: string, actionId: string, input?: unknown, configOverridesOrOptions?: Record<string, unknown> | RemoteExecuteOptions, tokenArg?: string): Promise<RemoteExecutionResult<T>>;
-export declare function fetchRemoteRun(serverUrl: string, runId: string, token?: string, options?: RemoteClientRequestOptions): Promise<RunRecord>;
-export declare function cancelRemoteRun(serverUrl: string, runId: string, token?: string, reason?: string, options?: RemoteClientRequestOptions): Promise<{
-    ok: boolean;
-    runId: string;
-    status: string;
-}>;
-export declare function fetchRemoteActions(serverUrl: string, token?: string, intent?: string, options?: RemoteClientRequestOptions): Promise<Array<{
-    id: string;
-    description: string;
-    packageId?: string;
-}>>;
-export declare function fetchRemoteActionShow(serverUrl: string, actionId: string, token?: string, options?: RemoteClientRequestOptions): Promise<any>;
-export declare function fetchRemoteInfo(serverUrl: string, token?: string, options?: {
-    intent?: string;
-    package?: string;
-    tree?: boolean;
-} & RemoteClientRequestOptions): Promise<any>;
-export declare function fetchRemoteDoctor(serverUrl: string, token?: string, targetPackage?: string, options?: RemoteClientRequestOptions): Promise<any>;
-export declare function fetchRemotePlaybooks(serverUrl: string, token?: string, options?: {
-    intent?: string;
-    package?: string;
-} & RemoteClientRequestOptions): Promise<Array<{
-    id: string;
-    description: string;
-    actions: string[];
-    packageId: string;
-    filePath: string;
-}>>;
-export declare function fetchRemotePlaybookShow(playbookId: string, token?: string, options?: RemoteClientRequestOptions): Promise<any>;
-export declare function fetchRemotePlaybookShow(serverUrl: string, playbookId: string, token?: string, options?: RemoteClientRequestOptions): Promise<any>;
-export declare function fetchRemoteRuns(serverUrl: string, token?: string, options?: {
-    status?: string;
-    actionId?: string;
-    packageId?: string;
-    intent?: string;
-    limit?: number;
-} & RemoteClientRequestOptions): Promise<{
-    ok: boolean;
-    total: number;
-    items: RunRecord[];
-}>;
-export declare function clearRemoteRuns(serverUrl: string, token?: string, options?: {
-    packageId?: string;
-    actionId?: string;
-    status?: string;
-} & RemoteClientRequestOptions): Promise<{
-    ok: boolean;
-    clearedCount: number;
-}>;
-export declare function fetchRemoteStateList(serverUrl: string, token?: string, options?: {
-    package?: string;
-    action?: string;
-    namespace?: string;
-    prefix?: string;
-} & RemoteClientRequestOptions): Promise<{
-    ok: boolean;
-    packageId: string;
-    keys: string[];
-}>;
-export declare function getRemoteStateKey(serverUrl: string, key: string, token?: string, options?: {
-    package?: string;
-    action?: string;
-    namespace?: string;
-} & RemoteClientRequestOptions): Promise<any>;
-export declare function setRemoteStateKey(serverUrl: string, key: string, value: unknown, token?: string, options?: {
-    package?: string;
-    action?: string;
-    namespace?: string;
-    ttl?: number;
-} & RemoteClientRequestOptions): Promise<any>;
-export declare function deleteRemoteStateKey(serverUrl: string, key: string, token?: string, options?: {
-    package?: string;
-    action?: string;
-    namespace?: string;
-} & RemoteClientRequestOptions): Promise<any>;
-export declare function clearRemoteState(serverUrl: string, token?: string, options?: {
-    package?: string;
-    action?: string;
-    namespace?: string;
-    prefix?: string;
-    all?: boolean;
-} & RemoteClientRequestOptions): Promise<{
-    ok: boolean;
-    packageId: string;
-    clearedCount: number;
-}>;
-export declare function fetchRemoteConfig(serverUrl: string, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;
-export declare function setRemoteConfig(serverUrl: string, key: string, value: unknown, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;
-export declare function deleteRemoteConfig(serverUrl: string, key: string, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;
-export declare function fetchRemoteConfigEnv(serverUrl: string, token?: string, packageId?: string, options?: RemoteClientRequestOptions): Promise<any>;
+export { assertSecureTransport, createRemoteFetch, fetchWithProtocolFallback, listProtocolRouteCandidates, } from "./client-transport.js";
+export type { RemoteClientRequestOptions, RemoteFetchInit, } from "./client-transport.js";
+export { checkRemoteHealth } from "./client-health.js";
+export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteDoctor, fetchRemoteInfo, } from "./client-actions.js";
+export type { RemoteExecuteOptions, RemoteExecutionResult } from "./client-actions.js";
+export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./client-playbooks.js";
+export { cancelRemoteRun, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
+export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./client-state.js";
+export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./client-config.js";