@actiondock/cli 2.0.12 → 2.2.1

package/dist/commands/playbook.js

@@ -0,0 +1,433 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { assertPathWithinRoot, fetchRemotePlaybooks, fetchRemotePlaybookShow, filterWithFallbackInfo, findProjectRoot, listLinkedPackages, loadActions, loadManifest, loadPlaybooks, loadProjectConfig, resolveActionProject, resolvePackageRoot, resolvePlaybookProject, resolveTarget, saveManifest, } from "@actiondock/core";
+import { ArgumentError, CliError, ExecutionError } from "../errors.js";
+import { renderPlaybookDetail, renderPlaybookList, renderResult, writeStdout, } from "../renderer.js";
+import { getEffectiveOptions, resolveIntent } from "../utils/index.js";
+/**
+ * 注册 Playbook 命令集合（list, show, validate, create）。
+ *
+ * @param program Commander 根程序对象
+ * @param context 命令行上下文
+ */
+export function registerPlaybookCommands(program, context) {
+    const pbCmd = program
+        .command("playbook")
+        .description("Manage task Playbooks (Task SOPs for AI Agents)");
+    // playbook list
+    pbCmd
+        .command("list [patterns...]")
+        .description("List playbooks in current project or linked packages")
+        .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("-p, --profile <name>", "Query against a specific profile")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("--no-fallback", "Disable fallback to full list when no items match intent")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action(async (patterns = [], rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const effectiveIntent = resolveIntent(options.intent, patterns);
+        const shouldFallback = options.fallback !== false;
+        const isMachine = Boolean(options.json || options.envelope);
+        // 1. 远端服务分支
+        const target = resolveTarget({
+            profile: options.profile,
+            server: options.server,
+            token: options.token,
+        }, context?.customHome);
+        if (target.type === "remote") {
+            const remotePbs = await fetchRemotePlaybooks(target.serverUrl, target.token, {
+                intent: effectiveIntent,
+                package: options.package,
+            });
+            renderResult(remotePbs, {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => renderPlaybookList(remotePbs, `Playbooks on remote server ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""}`, false, effectiveIntent),
+                context,
+            });
+            return;
+        }
+        // 2. 本地工程模式
+        let targetRoot = null;
+        if (options.package) {
+            targetRoot = resolvePackageRoot(options.package);
+            if (!targetRoot) {
+                throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+            }
+        }
+        else {
+            targetRoot = findProjectRoot();
+        }
+        if (targetRoot) {
+            const config = loadProjectConfig(targetRoot);
+            const playbooks = loadPlaybooks(targetRoot, config.playbooksDir);
+            const rawList = Array.from(playbooks.values()).map((pb) => ({
+                id: pb.id,
+                description: pb.description,
+                packageId: config.id,
+            }));
+            const filterRes = filterWithFallbackInfo(rawList, effectiveIntent, [(p) => p.id, (p) => p.description], shouldFallback);
+            if (filterRes.isFallback && isMachine) {
+                renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0 }, { json: options.json, envelope: options.envelope, context });
+                return;
+            }
+            renderResult(filterRes.items, {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => renderPlaybookList(filterRes.items, `Playbooks in ${config.id} (${targetRoot})`, filterRes.isFallback, effectiveIntent),
+                context,
+            });
+            return;
+        }
+        // 3. 扫描所有已链接的外部包
+        const linkedList = listLinkedPackages(context?.customHome);
+        if (linkedList.length === 0) {
+            renderResult([], {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => "No ActionDock project in current directory, and no packages linked.",
+                context,
+            });
+            return;
+        }
+        const aggregated = [];
+        for (const pkg of linkedList) {
+            if (!existsSync(pkg.path))
+                continue;
+            try {
+                const config = loadProjectConfig(pkg.path);
+                const pbs = loadPlaybooks(pkg.path, config.playbooksDir);
+                const list = Array.from(pbs.values()).map((p) => ({
+                    id: p.id,
+                    description: p.description,
+                }));
+                aggregated.push({
+                    packageId: pkg.id,
+                    packageName: pkg.name,
+                    path: pkg.path,
+                    playbooks: list,
+                });
+            }
+            catch {
+                // 单个链接包清单损坏或 Playbook 加载失败时跳过，继续聚合其余包
+            }
+        }
+        let filteredPackages = [];
+        let isFallback = false;
+        if (!effectiveIntent) {
+            filteredPackages = aggregated;
+        }
+        else {
+            for (const pkg of aggregated) {
+                const pkgMatches = filterWithFallbackInfo([pkg], effectiveIntent, [(p) => p.packageId, (p) => p.packageName, (p) => p.path], false).matchedCount > 0;
+                if (pkgMatches) {
+                    filteredPackages.push(pkg);
+                }
+                else {
+                    const matchedPbs = filterWithFallbackInfo(pkg.playbooks, effectiveIntent, [(p) => p.id, (p) => p.description], false).items;
+                    if (matchedPbs.length > 0) {
+                        filteredPackages.push({
+                            ...pkg,
+                            playbooks: matchedPbs,
+                        });
+                    }
+                }
+            }
+            if (filteredPackages.length === 0 && shouldFallback) {
+                filteredPackages = aggregated;
+                isFallback = true;
+            }
+        }
+        if (isFallback && isMachine) {
+            renderResult({ packages: filteredPackages, isFallback: true, matchedCount: 0 }, { json: options.json, envelope: options.envelope, context });
+            return;
+        }
+        renderResult(filteredPackages, {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => {
+                const lines = ["Linked Playbooks:\n"];
+                for (const pkg of filteredPackages) {
+                    lines.push(`- Package: ${pkg.packageId} (${pkg.path})`);
+                    for (const pb of pkg.playbooks) {
+                        lines.push(`    - ${pb.id.padEnd(26)} ${pb.description || ""}`);
+                    }
+                }
+                return lines.join("\n");
+            },
+            context,
+        });
+    });
+    // playbook show <id>
+    pbCmd
+        .command("show <id>")
+        .description("Show playbook content and metadata")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("-p, --profile <name>", "Query against a specific profile")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action(async (id, rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        if (!id) {
+            throw new ArgumentError("Playbook ID is required for show");
+        }
+        // 1. 远端服务分支
+        const target = resolveTarget({
+            profile: options.profile,
+            server: options.server,
+            token: options.token,
+        }, context?.customHome);
+        if (target.type === "remote") {
+            const detail = await fetchRemotePlaybookShow(target.serverUrl, id, target.token);
+            renderResult(detail, {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => renderPlaybookDetail(detail),
+                context,
+            });
+            return;
+        }
+        // 2. 本地项目模式
+        let showTarget = id;
+        if (options.package && !id.includes("/")) {
+            const pkgRoot = resolvePackageRoot(options.package);
+            if (!pkgRoot) {
+                throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+            }
+            showTarget = `${options.package}/${id}`;
+        }
+        let resolved;
+        try {
+            resolved = resolvePlaybookProject(showTarget);
+        }
+        catch (err) {
+            throw new ArgumentError(err.message);
+        }
+        const pb = resolved.playbook;
+        const detail = {
+            id: pb.id,
+            packageId: resolved.packageId,
+            description: pb.description,
+            actions: pb.actions,
+            filePath: pb.filePath,
+            content: pb.content,
+        };
+        renderResult(detail, {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => renderPlaybookDetail(detail),
+            context,
+        });
+    });
+    // playbook validate
+    pbCmd
+        .command("validate [id]")
+        .description("Validate playbook format and action references (in current project or linked packages)")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action(async (id, rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        let root = null;
+        if (options.package) {
+            root = resolvePackageRoot(options.package);
+            if (!root) {
+                throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+            }
+        }
+        else {
+            root = findProjectRoot();
+        }
+        const targets = [];
+        if (root) {
+            const config = loadProjectConfig(root);
+            const playbooks = loadPlaybooks(root, config.playbooksDir);
+            if (id) {
+                const pb = playbooks.get(id);
+                if (!pb) {
+                    throw new ArgumentError(`Playbook '${id}' not found in package '${config.id}'`);
+                }
+                targets.push({ root, packageId: config.id, playbooks: [pb] });
+            }
+            else {
+                targets.push({ root, packageId: config.id, playbooks: Array.from(playbooks.values()) });
+            }
+        }
+        else if (id) {
+            let resolved;
+            try {
+                resolved = resolvePlaybookProject(id);
+            }
+            catch (err) {
+                throw new ArgumentError(err.message);
+            }
+            targets.push({
+                root: resolved.projectRoot,
+                packageId: resolved.packageId,
+                playbooks: [resolved.playbook],
+            });
+        }
+        else {
+            const linkedList = listLinkedPackages(context?.customHome);
+            if (linkedList.length === 0) {
+                throw new ArgumentError("Not in an ActionDock project, and no packages linked.");
+            }
+            for (const pkg of linkedList) {
+                if (!existsSync(pkg.path))
+                    continue;
+                try {
+                    const config = loadProjectConfig(pkg.path);
+                    const playbooks = loadPlaybooks(pkg.path, config.playbooksDir);
+                    targets.push({
+                        root: pkg.path,
+                        packageId: pkg.id,
+                        playbooks: Array.from(playbooks.values()),
+                    });
+                }
+                catch {
+                    // 单个链接包清单损坏或 Playbook 加载失败时跳过，不阻断整体校验
+                }
+            }
+        }
+        const results = [];
+        for (const target of targets) {
+            const config = loadProjectConfig(target.root);
+            const manifest = loadManifest(target.root);
+            const actions = await loadActions(target.root, config.actionsDir);
+            for (const pb of target.playbooks) {
+                const warnings = [];
+                const errors = [];
+                if (!pb.id) {
+                    errors.push("Missing id in playbook");
+                }
+                if (!pb.description) {
+                    warnings.push("Missing description in actiondock.json");
+                }
+                if (pb.actions && Array.isArray(pb.actions)) {
+                    for (const actRef of pb.actions) {
+                        if (actRef.includes("/")) {
+                            try {
+                                await resolveActionProject(actRef);
+                            }
+                            catch (e) {
+                                errors.push(`Referenced cross-package action '${actRef}' not resolvable: ${e.message}`);
+                            }
+                        }
+                        else {
+                            const foundInActions = actions.has(actRef);
+                            const foundInManifest = Boolean(manifest?.actions?.[actRef]);
+                            if (!foundInActions && !foundInManifest) {
+                                errors.push(`Referenced action '${actRef}' not found in project actions`);
+                            }
+                        }
+                    }
+                }
+                results.push({
+                    id: pb.id,
+                    packageId: target.packageId,
+                    valid: errors.length === 0,
+                    warnings,
+                    errors,
+                });
+            }
+        }
+        const allValid = results.every((r) => r.valid);
+        renderResult({ valid: allValid, results }, {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => {
+                const lines = [];
+                for (const r of results) {
+                    const tag = r.valid ? "[OK]" : "[FAIL]";
+                    lines.push(`${tag} ${r.packageId}/${r.id}: ${r.valid ? "Valid" : "Invalid"}`);
+                    for (const e of r.errors) {
+                        lines.push(`    Error: ${e}`);
+                    }
+                    for (const w of r.warnings) {
+                        lines.push(`    Warning: ${w}`);
+                    }
+                }
+                return lines.join("\n");
+            },
+            context,
+        });
+        if (!allValid) {
+            process.exitCode = 1;
+            return;
+        }
+    });
+    // playbook create / new
+    pbCmd
+        .command("create <id>")
+        .alias("new")
+        .description("Scaffold a new Playbook markdown file")
+        .option("-d, --desc <description>", "Playbook description")
+        .option("-a, --actions <actions...>", "Referenced action IDs")
+        .option("-f, --file <filePath>", "Target file path relative to playbooks dir")
+        .action((id, options) => {
+        handlePlaybookCreate(id, options, context);
+    });
+}
+export function handlePlaybookCreate(id, options, context) {
+    const root = findProjectRoot();
+    if (!root) {
+        throw new ExecutionError("Not in an ActionDock project (actiondock.json not found)");
+    }
+    try {
+        const config = loadProjectConfig(root);
+        const pbDir = resolve(root, config.playbooksDir || "playbooks");
+        if (!existsSync(pbDir)) {
+            mkdirSync(pbDir, { recursive: true });
+        }
+        if (options.file && isAbsolute(options.file)) {
+            throw new ExecutionError(`--file option must be a relative path, received: ${options.file}`);
+        }
+        const cleanName = id.replace(/[^a-zA-Z0-9-_]/g, "-");
+        const targetRelFile = options.file || `${cleanName}.md`;
+        const targetFullFile = resolve(pbDir, targetRelFile);
+        assertPathWithinRoot(pbDir, targetFullFile, "playbook file");
+        if (existsSync(targetFullFile)) {
+            throw new ExecutionError(`File '${targetFullFile}' already exists`);
+        }
+        mkdirSync(dirname(targetFullFile), { recursive: true });
+        const desc = options.desc || `SOP guide for ${id}`;
+        const actionsList = Array.isArray(options.actions) ? options.actions : [];
+        const template = `# ${id.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())} SOP
+
+This playbook provides task execution guidance for AI Agents.
+
+## Instructions
+
+- Inspect available actions with \`<binary> list --json\`.
+- Follow the required steps to complete the task.
+`;
+        writeFileSync(targetFullFile, template, "utf-8");
+        const manifest = loadManifest(root) || {
+            $schema: "https://actiondock.dev/schema/v2/actiondock.json",
+            id: config.id,
+            name: config.name,
+            version: config.version,
+            playbooks: {},
+        };
+        manifest.playbooks = manifest.playbooks || {};
+        const relEntry = relative(root, targetFullFile).replace(/\\/g, "/");
+        manifest.playbooks[id] = {
+            entry: relEntry,
+            description: desc,
+            actions: actionsList,
+        };
+        saveManifest(root, manifest);
+        writeStdout(`[OK] Created Playbook '${id}' at ${targetFullFile}`, context);
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            throw err;
+        }
+        throw new ExecutionError(err.message);
+    }
+}

package/dist/commands/profile.js

@@ -0,0 +1,253 @@
+import { addProfile, checkRemoteHealth, filterWithFallbackInfo, getProfile, listProfiles, loadProfiles, maskSecretValue, removeProfile, resolveProfileToken, resolveTarget, toSnakeUpperCase, useProfile, } from "@actiondock/core";
+import { ArgumentError, CliError, ExecutionError, } from "../errors.js";
+import { renderResult, writeStdout } from "../renderer.js";
+import { getEffectiveOptions, resolveFallbackStrategy, resolveIntent } from "../utils/index.js";
+export function registerProfileCommands(program) {
+    const profileCmd = program
+        .command("profile")
+        .description("Manage multi-cloud and remote execution profiles");
+    // ad profile list
+    profileCmd
+        .command("list [patterns...]")
+        .description("List all configured profiles")
+        .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
+        .option("--reveal, --show-secrets", "Reveal plain text values for tokens")
+        .option("--fallback", "Enable fallback to full list when no items match intent")
+        .option("--no-fallback", "Disable fallback to full list when no items match intent")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action((patterns, rawOptions, cmd) => {
+        try {
+            const options = getEffectiveOptions(rawOptions, cmd);
+            const effectiveIntent = resolveIntent(options.intent, patterns);
+            const { isMachine, shouldFallback } = resolveFallbackStrategy(options);
+            const reveal = Boolean(options.reveal || options.showSecrets);
+            const list = listProfiles();
+            const enriched = list.map((p) => {
+                const resolved = resolveProfileToken(p.name, p.entry);
+                return {
+                    name: p.name,
+                    isCurrent: p.isCurrent,
+                    serverUrl: p.entry.serverUrl,
+                    description: p.entry.description || "",
+                    tokenEnv: p.entry.tokenEnv,
+                    tokenConfigured: resolved.source !== "none",
+                    tokenSource: resolved.source,
+                    token: reveal ? resolved.token : (resolved.token ? maskSecretValue(resolved.token) : undefined),
+                };
+            });
+            const filterRes = filterWithFallbackInfo(enriched, effectiveIntent, [(p) => p.name, (p) => p.serverUrl, (p) => p.description, (p) => p.tokenSource], shouldFallback);
+            if (filterRes.isFallback && isMachine) {
+                renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0 }, { json: options.json, envelope: options.envelope });
+                return;
+            }
+            renderResult(filterRes.items, {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => {
+                    const lines = ["ActionDock Execution Profiles:\n"];
+                    if (filterRes.isFallback && effectiveIntent) {
+                        lines.push(`(No profiles matched intent '${effectiveIntent}', showing all profiles)\n`);
+                    }
+                    for (const item of filterRes.items) {
+                        const currentMarker = item.isCurrent ? "* " : "  ";
+                        let tokenInfo = "";
+                        if (item.tokenSource === "tokenEnv") {
+                            tokenInfo = ` [token: env(${item.tokenEnv})]`;
+                        }
+                        else if (item.tokenSource === "profileEnv") {
+                            tokenInfo = ` [token: env(ACTIONDOCK_${toSnakeUpperCase(item.name)}_TOKEN)]`;
+                        }
+                        else if (item.tokenSource === "profile") {
+                            tokenInfo = ` [token: stored in profile]`;
+                        }
+                        else if (item.tokenSource === "globalEnv") {
+                            tokenInfo = ` [token: env(ACTIONDOCK_TOKEN)]`;
+                        }
+                        if (reveal && item.token) {
+                            tokenInfo += ` = ${item.token}`;
+                        }
+                        const desc = item.description ? ` - ${item.description}` : "";
+                        lines.push(`${currentMarker}${item.name.padEnd(20)} ${item.serverUrl}${tokenInfo}${desc}`);
+                    }
+                    lines.push("\nUse 'ad profile use <name>' to switch or 'ad run <action> --profile <name>' to execute on a specific target.");
+                    return lines.join("\n");
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof ArgumentError || err instanceof CliError)
+                throw err;
+            throw new ExecutionError(err.message);
+        }
+    });
+    // ad profile add <name>
+    profileCmd
+        .command("add <name>")
+        .description("Add or update a remote execution profile")
+        .requiredOption("-s, --server <url>", "Remote ActionDock server URL (e.g. http://1.2.3.4:5177)")
+        .option("-t, --token <token>", "Authentication token for the remote server (deprecated; prefer --token-env)")
+        .option("--token-env <env>", "Environment variable name containing the authentication token")
+        .option("-d, --desc <description>", "Description of this profile/machine")
+        .action((name, options) => {
+        try {
+            if (options.token) {
+                console.warn("Warning: storing tokens directly in profiles.json is deprecated. Use --token-env or standard environment variables (e.g. ACTIONDOCK_<PROFILE>_TOKEN) instead.");
+            }
+            addProfile(name, {
+                serverUrl: options.server,
+                token: options.token,
+                tokenEnv: options.tokenEnv,
+                description: options.desc,
+            });
+            writeStdout(`[OK] Profile '${name}' configured for server: ${options.server}`);
+        }
+        catch (err) {
+            throw new ExecutionError(err.message);
+        }
+    });
+    // ad profile use <name>
+    profileCmd
+        .command("use <name>")
+        .description("Switch active default profile")
+        .action((name) => {
+        try {
+            useProfile(name);
+            writeStdout(`[OK] Active profile switched to '${name}'`);
+        }
+        catch (err) {
+            throw new ExecutionError(err.message);
+        }
+    });
+    // ad profile show [name]
+    profileCmd
+        .command("show [name]")
+        .description("Display details of a profile (defaults to active profile)")
+        .option("--reveal, --show-secrets", "Reveal plain text values for tokens")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action((name, rawOptions, cmd) => {
+        try {
+            const options = getEffectiveOptions(rawOptions, cmd);
+            const config = loadProfiles();
+            const targetName = name || config.currentProfile || "local";
+            const entry = getProfile(targetName);
+            const reveal = Boolean(options.reveal || options.showSecrets);
+            if (!entry && targetName !== "local") {
+                throw new ArgumentError(`Profile '${targetName}' not found.`);
+            }
+            const resolved = resolveProfileToken(targetName, entry);
+            const displayToken = reveal
+                ? resolved.token
+                : (resolved.token ? maskSecretValue(resolved.token) : undefined);
+            const data = {
+                name: targetName,
+                isCurrent: config.currentProfile === targetName,
+                serverUrl: entry?.serverUrl || "local",
+                tokenConfigured: resolved.source !== "none",
+                tokenSource: resolved.source,
+                tokenEnv: entry?.tokenEnv,
+                token: displayToken,
+                description: entry?.description || "",
+            };
+            renderResult(data, {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => {
+                    const lines = [];
+                    lines.push(`Profile:      ${data.name}${data.isCurrent ? " (Active)" : ""}`);
+                    lines.push(`Server URL:   ${data.serverUrl}`);
+                    let sourceDetail = "None";
+                    if (data.tokenSource === "tokenEnv") {
+                        sourceDetail = `Environment Variable ($${data.tokenEnv})`;
+                    }
+                    else if (data.tokenSource === "profileEnv") {
+                        sourceDetail = `Profile Environment Variable ($ACTIONDOCK_${toSnakeUpperCase(data.name)}_TOKEN)`;
+                    }
+                    else if (data.tokenSource === "profile") {
+                        sourceDetail = "Stored in profiles.json (Deprecated)";
+                    }
+                    else if (data.tokenSource === "globalEnv") {
+                        sourceDetail = "Global Environment Variable ($ACTIONDOCK_TOKEN)";
+                    }
+                    lines.push(`Auth Source:  ${sourceDetail}`);
+                    if (data.tokenConfigured) {
+                        lines.push(`Token Value:  ${data.token}`);
+                    }
+                    if (data.description) {
+                        lines.push(`Description:  ${data.description}`);
+                    }
+                    return lines.join("\n");
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof ArgumentError || err instanceof CliError) {
+                throw err;
+            }
+            throw new ExecutionError(err.message);
+        }
+    });
+    // ad profile rm / remove <name>
+    profileCmd
+        .command("rm <name>")
+        .alias("remove")
+        .description("Remove a profile")
+        .action((name) => {
+        try {
+            if (name === "local") {
+                throw new ExecutionError("Cannot remove built-in 'local' profile");
+            }
+            const removed = removeProfile(name);
+            if (!removed) {
+                throw new ExecutionError(`Profile '${name}' not found`);
+            }
+            writeStdout(`[OK] Profile '${name}' removed`);
+        }
+        catch (err) {
+            if (err instanceof CliError) {
+                throw err;
+            }
+            throw new ExecutionError(err.message);
+        }
+    });
+    // ad profile test [name]
+    profileCmd
+        .command("test [name]")
+        .description("Test connection latency and health of a profile")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action(async (name, rawOptions, cmd) => {
+        try {
+            const options = getEffectiveOptions(rawOptions, cmd);
+            const target = resolveTarget({ profile: name });
+            if (target.type === "local") {
+                renderResult({ ok: true, type: "local", message: "Local execution" }, {
+                    json: options.json,
+                    envelope: options.envelope,
+                    humanFormatter: () => `Target profile '${target.profileName || "local"}' is local (runs in local runtime).`,
+                });
+                return;
+            }
+            const health = await checkRemoteHealth(target.serverUrl, target.token);
+            renderResult(health, {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => {
+                    if (health.ok) {
+                        return `[OK] Connected to ${target.serverUrl} (${health.latencyMs}ms) - Version: ${health.version}, Status: ${health.status}`;
+                    }
+                    return `[FAIL] Connection to ${target.serverUrl} failed (${health.latencyMs}ms): ${health.error}`;
+                },
+            });
+            if (!health.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            if (err instanceof ArgumentError || err instanceof CliError)
+                throw err;
+            throw new ExecutionError(err.message);
+        }
+    });
+}