@actiondock/core 2.0.0

package/src/profile/manager.ts

@@ -0,0 +1,341 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { toSnakeUpperCase } from "../runtime/env";
+import { getActionDockHome } from "../utils";
+import type {
+  ProfileEntry,
+  ProfilesConfig,
+  ResolvedTarget,
+  TokenResolutionSource,
+} from "./types";
+
+const PROFILE_NAME_REGEX = /^[a-zA-Z0-9_\-\.]+$/;
+
+/**
+ * 默认初始 Profiles 配置（预设 local 本地环境）。
+ */
+export const DEFAULT_PROFILES_CONFIG: ProfilesConfig = {
+  currentProfile: "local",
+  profiles: {
+    local: {
+      serverUrl: "local",
+      description: "Local execution environment",
+    },
+  },
+};
+
+/**
+ * 格式化并规范化 Server URL 地址（自动补齐 http:// 协议头并移除末尾斜杠）。
+ */
+export function normalizeServerUrl(url: string): string {
+  let cleaned = url.trim().replace(/\/+$/, "");
+  if (!/^https?:\/\//i.test(cleaned) && cleaned !== "local") {
+    cleaned = `http://${cleaned}`;
+  }
+  return cleaned;
+}
+
+/**
+ * 获取 profiles.json 配置文件的物理绝对路径（~/.actiondock/profiles.json）。
+ */
+export function getProfilesFilePath(customHome?: string): string {
+  const baseDir = getActionDockHome(customHome);
+  return join(baseDir, ".actiondock", "profiles.json");
+}
+
+/**
+ * 加载并读取 profiles.json 配置文件。
+ */
+export function loadProfiles(customHome?: string): ProfilesConfig {
+  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 as ProfilesConfig;
+  } catch {
+    return structuredClone(DEFAULT_PROFILES_CONFIG);
+  }
+}
+
+/**
+ * 保存并写入 profiles.json 配置文件，并严格限制文件权限为 0600。
+ */
+export function saveProfiles(data: ProfilesConfig, customHome?: string): void {
+  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: string,
+  entry: ProfileEntry,
+  customHome?: string
+): void {
+  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: string, customHome?: string): boolean {
+  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: string, customHome?: string): void {
+  const trimmedName = name.trim();
+  const profilesConfig = loadProfiles(customHome);
+
+  if (trimmedName !== "local" && !profilesConfig.profiles[trimmedName]) {
+    throw new Error(
+      `Profile '${trimmedName}' not found. Use 'ac profile list' to see available profiles or 'ac profile add' to register one.`
+    );
+  }
+
+  profilesConfig.currentProfile = trimmedName;
+  saveProfiles(profilesConfig, customHome);
+}
+
+export function getProfile(
+  name: string,
+  customHome?: string
+): ProfileEntry | undefined {
+  const profilesConfig = loadProfiles(customHome);
+  return profilesConfig.profiles[name.trim()];
+}
+
+export function listProfiles(
+  customHome?: string
+): Array<{ name: string; isCurrent: boolean; entry: ProfileEntry }> {
+  const profilesConfig = loadProfiles(customHome);
+  const current = profilesConfig.currentProfile || "local";
+
+  const entries: Array<{
+    name: string;
+    isCurrent: boolean;
+    entry: ProfileEntry;
+  }> = [];
+
+  // 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?: string,
+  entry?: ProfileEntry,
+  explicitToken?: string
+): { token?: string; source: TokenResolutionSource } {
+  // 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?: { profile?: string; server?: string; token?: string },
+  customHome?: string
+): ResolvedTarget {
+  // 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 'ac 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 'ac 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/src/profile/types.ts

@@ -0,0 +1,71 @@
+/**
+ * 单个远端配置环境（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"        // 来源于显式 CLI 参数 (--token)
+  | "tokenEnv"   // 来源于 Profile 显式绑定的 tokenEnv 环境变量
+  | "profileEnv" // 来源于自动推导的 ACTIONDOCK_<PROFILE>_TOKEN
+  | "profile"    // 来源于 profiles.json 中存储的遗留明文 Token
+  | "globalEnv"  // 来源于全局 ACTIONDOCK_TOKEN
+  | "none";      // 未配置任何 Token
+
+/**
+ * 经过解析后确定的最终执行目标环境。
+ */
+export interface ResolvedTarget {
+  /** 执行环境类型：local (本地 Bun 进程) 或 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/src/project/index.ts

@@ -0,0 +1,3 @@
+export * from "./init";
+export * from "./loader";
+export * from "./types";

package/src/project/init.ts

@@ -0,0 +1,194 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+/**
+ * 项目初始化脚手架选项。
+ */
+export interface InitOptions {
+  /** 自定义项目 ID（默认使用目录名） */
+  id?: string;
+  /** 自定义项目展示名称（默认由目录名美化生成） */
+  name?: string;
+  /** 自定义项目描述 */
+  description?: string;
+}
+
+/**
+ * 在目标目录初始化一个完整的 ActionDock 2.0 Action Package 脚手架。
+ * 生成内容包括：
+ * 1. actiondock.json（项目元数据与配置声明）
+ * 2. package.json（模块依赖与 bun test 脚本）
+ * 3. tsconfig.json（现代 ESNext / Bundler 编译配置）
+ * 4. .gitignore（排除持久化 db、node_modules、dist）
+ * 5. actions/greet.ts（标准示例 Action，演示 config、state、log 使用）
+ * 6. playbooks/greet-user.md（标准 SOP Playbook 演示）
+ * 7. tests/greet.test.ts（基于 createTestRuntime 的零依赖单元测试）
+ * 
+ * @param targetDir 目标项目目录
+ * @param options 初始化选项
+ */
+export function initProject(targetDir: string, options: InitOptions = {}): void {
+  const root = resolve(targetDir);
+  if (!existsSync(root)) {
+    mkdirSync(root, { recursive: true });
+  }
+
+  const dirName = basename(root);
+  const id = options.id || dirName;
+  const name = options.name || dirName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  const description = options.description || "ActionDock AI Agent Actions";
+
+  // 1. actiondock.json
+  const actiondockJson = {
+    id,
+    name,
+    version: "0.1.0",
+    description,
+    actionsDir: "actions",
+    playbooksDir: "playbooks",
+    config: {
+      SAMPLE_GREETING: {
+        description: "Default greeting message",
+        default: "Hello",
+      },
+    },
+  };
+  writeFileSync(
+    join(root, "actiondock.json"),
+    JSON.stringify(actiondockJson, null, 2) + "\n"
+  );
+
+  // 2. package.json
+  const packageJson = {
+    name: id,
+    version: "0.1.0",
+    description,
+    type: "module",
+    scripts: {
+      test: "bun test",
+    },
+    dependencies: {
+      "@actiondock/sdk": "^2.0.0",
+    },
+    devDependencies: {
+      "@types/bun": "latest",
+      "typescript": "^5.7.0",
+    },
+  };
+  writeFileSync(
+    join(root, "package.json"),
+    JSON.stringify(packageJson, null, 2) + "\n"
+  );
+
+  // 3. tsconfig.json
+  const tsconfigJson = {
+    compilerOptions: {
+      target: "ESNext",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      strict: true,
+      skipLibCheck: true,
+      types: ["bun-types"],
+    },
+  };
+  writeFileSync(
+    join(root, "tsconfig.json"),
+    JSON.stringify(tsconfigJson, null, 2) + "\n"
+  );
+
+  // 4. .gitignore
+  const gitignore = `.actiondock/
+node_modules/
+dist/
+bun.lock
+*.db
+`;
+  writeFileSync(join(root, ".gitignore"), gitignore);
+
+  // 5. actions/
+  const actionsDir = join(root, "actions");
+  mkdirSync(actionsDir, { recursive: true });
+
+  const sampleAction = `import { defineAction } from "@actiondock/sdk";
+
+export default defineAction({
+  id: "sample.greet",
+  description: "Greet a user with configurable greeting",
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Name of person to greet" },
+    },
+    required: ["name"],
+  },
+
+  outputSchema: {
+    type: "object",
+    properties: {
+      message: { type: "string" },
+      timestamp: { type: "string" },
+    },
+    required: ["message", "timestamp"],
+  },
+
+  async run(input: { name: string }, ctx) {
+    const greeting = ctx.config.get("SAMPLE_GREETING", "Hello");
+    const count = ((await ctx.state.get<number>("greet_count")) || 0) + 1;
+    await ctx.state.set("greet_count", count);
+
+    ctx.log.info(\`Greeting \${input.name} (times greeted: \${count})\`);
+
+    return {
+      message: \`\${greeting}, \${input.name}!\`,
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+`;
+  writeFileSync(join(actionsDir, "greet.ts"), sampleAction);
+
+  // 6. playbooks/
+  const playbooksDir = join(root, "playbooks");
+  mkdirSync(playbooksDir, { recursive: true });
+
+  const samplePlaybook = `---
+id: greet-user
+description: SOP for greeting a new user and verifying system health
+actions:
+  - sample.greet
+---
+
+# Greeting SOP
+
+1. Call \`sample.greet\` with the user's name.
+2. Confirm the returned greeting message.
+`;
+  writeFileSync(join(playbooksDir, "greet-user.md"), samplePlaybook);
+
+  // 7. tests/
+  const testsDir = join(root, "tests");
+  mkdirSync(testsDir, { recursive: true });
+
+  const sampleTest = `import { describe, expect, it } from "bun:test";
+import { createTestRuntime } from "@actiondock/sdk";
+import greetAction from "../actions/greet";
+
+describe("greet action", () => {
+  it("should greet user with greeting and increment count", async () => {
+    const runtime = createTestRuntime({
+      config: { SAMPLE_GREETING: "Hi" },
+    });
+
+    const res1 = await runtime.run(greetAction, { name: "Alice" });
+    expect(res1.message).toBe("Hi, Alice!");
+    expect(await runtime.state.get("greet_count")).toBe(1);
+
+    const res2 = await runtime.run(greetAction, { name: "Bob" });
+    expect(res2.message).toBe("Hi, Bob!");
+    expect(await runtime.state.get("greet_count")).toBe(2);
+  });
+});
+`;
+  writeFileSync(join(testsDir, "greet.test.ts"), sampleTest);
+}