@keystrokehq/cli 0.0.1

package/dist/test-BHTgR3UA.mjs

@@ -0,0 +1,698 @@
+#!/usr/bin/env node
+
+import { C as CliExitError, D as throwReportedCliExit, h as toErrorMessage, t as ui } from "./keystroke.mjs";
+import { l as resolveAuthOptions } from "./dist-CUK7yBM0.mjs";
+import { t as assertWorkflowProjectRoot } from "./project-config-D1qsQlO7.mjs";
+import { i as writeJson, n as JsonOptionSchema, t as JSON_OPTION_CONFIG } from "./output-DM4b7KgY.mjs";
+import { t as createTypedCommand } from "./commander-DfTVqQ-3.mjs";
+import { a as readManifestsFromOutDir } from "./dist-BkJUoBiG.mjs";
+import { t as requireWorkflowsDir } from "./resolve-project-DDJ29sCF.mjs";
+import { _ as getOfficialIntegrationMetadata, a as clearHostedActionDispatcher, c as registerHostedActionExecutionPolicy, d as clearOperationContext, f as registerOperationContext, g as registerRuntime, h as clearRuntime, l as clearOperationCredentialResolver, o as clearHostedActionExecutionPolicy, s as registerHostedActionDispatcher, u as registerOperationCredentialResolver } from "./src-C0X6u_Mw.mjs";
+import { a as runWorkflowBuild, n as renderBuildFailure } from "./workflow-build-DBQaBfnn.mjs";
+import { n as getProcessEnv } from "./env-91KwMKov.mjs";
+import { i as requireClient, t as assertProjectConfigMatchesAuthenticatedOrg } from "./context-T7HZuB97.mjs";
+import { t as lookupCurrentDeploymentWorkflow } from "./current-deployment-workflow-poHt27i3.mjs";
+import { n as WorkflowsRunOptionsSchema, t as RUN_OPTIONS_CONFIG } from "./options-CeaTcFxP.mjs";
+import { a as validateInputOrExit, i as resolveInput, r as pollForCompletion, t as handleWorkflowsTryDeploy } from "./try-deploy.handler-DqybNhXx.mjs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { pathToFileURL } from "node:url";
+//#region ../../packages/workflow-core/src/test-runtime/credentials/env-resolver.ts
+/**
+* Computes the env var name for a credential key.
+* Uses the credential set's namespace as the prefix if present, otherwise the raw id.
+* e.g., namespace='keystroke', key='SLACK_BOT_TOKEN' → 'KEYSTROKE_SLACK_BOT_TOKEN'
+*       id='my-api', key='API_KEY' → 'MY_API_API_KEY'
+*/
+function normalizeEnvVarName(credentialSet, key) {
+	return `${(credentialSet.namespace ?? credentialSet.id).replace(/[-]/g, "_").toUpperCase()}_${key}`;
+}
+function getCredentialSetKeys(credentialSet) {
+	return Object.keys(credentialSet.auth.shape);
+}
+function resolveCredentialsFromEnv(credentialSet, options = {}) {
+	const credentials = {};
+	const envVarNames = [];
+	for (const key of getCredentialSetKeys(credentialSet)) {
+		const envVarName = normalizeEnvVarName(credentialSet, key);
+		const value = process.env[envVarName];
+		if (value !== void 0) {
+			credentials[key] = value;
+			envVarNames.push(envVarName);
+			continue;
+		}
+		if (!options.lenient) throw new Error(`Missing credential "${envVarName}"`);
+	}
+	return {
+		credentials,
+		envVarNames
+	};
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/credentials/cache.ts
+function createCredentialCache() {
+	const cache = /* @__PURE__ */ new Map();
+	return { async getOrCreate(key, createValue) {
+		const existing = cache.get(key);
+		if (existing) return existing;
+		const pendingValue = createValue().catch((error) => {
+			cache.delete(key);
+			throw error;
+		});
+		cache.set(key, pendingValue);
+		return pendingValue;
+	} };
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/credentials/server-resolver.ts
+async function createServerCredentialResolver(options, dependencies = {
+	fetch: globalThis.fetch,
+	resolveAuthOptions
+}) {
+	try {
+		const resolvedAuth = await dependencies.resolveAuthOptions({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+			credentialsPath: options.credentialsPath
+		});
+		if (!resolvedAuth.apiKey || !resolvedAuth.baseUrl) return;
+		const cache = createCredentialCache();
+		return { async resolveCredentialSet(credentialSet, keys) {
+			const resolvedCredentialSetId = credentialSet.resolvedCredentialSetId;
+			const cacheKey = `${resolvedCredentialSetId}:${[...keys].sort().join(",")}`;
+			return cache.getOrCreate(cacheKey, async () => {
+				const response = await dependencies.fetch(new URL("api/v1/credentials/resolve", resolvedAuth.baseUrl).toString(), {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${resolvedAuth.apiKey}`,
+						"Content-Type": "application/json"
+					},
+					body: JSON.stringify({
+						credentialSetId: resolvedCredentialSetId,
+						keys: [...keys]
+					})
+				});
+				if (!response.ok) {
+					const message = formatCredentialResolutionErrorMessage({
+						credentialSet,
+						envVarNames: keys.map((key) => normalizeEnvVarName(credentialSet, key)),
+						errorBody: await readCredentialResolutionErrorBody(response),
+						status: response.status
+					});
+					if (response.status === 404) throw new Error(message);
+					throw new Error(message);
+				}
+				return (await response.json()).credentials;
+			});
+		} };
+	} catch {
+		return;
+	}
+}
+async function readCredentialResolutionErrorBody(response) {
+	try {
+		return await response.json();
+	} catch {
+		return;
+	}
+}
+function formatCredentialResolutionErrorMessage(params) {
+	const label = params.errorBody?.remediation?.displayName ?? humanizeCredentialSetLabel(params.credentialSet);
+	const primaryGuidance = params.errorBody?.remediation?.summary ?? params.errorBody?.message ?? params.errorBody?.detail ?? `Set up ${label} in Keystroke and retry.`;
+	const envHint = params.envVarNames.length > 0 ? ` Or export ${params.envVarNames.join(", ")} in the current shell and retry.` : "";
+	if (params.status === 404) return `Keystroke test credential resolution could not resolve ${label}. ${primaryGuidance}${envHint}`;
+	return `Keystroke test credential resolution failed for ${label}. ${primaryGuidance}${envHint}`;
+}
+function humanizeCredentialSetLabel(credentialSet) {
+	return credentialSet.id.split(/[-_]/u).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/credentials/create-test-credential-resolver.ts
+function pickMissingCredentialSets(credentialSets, existingCredentials) {
+	return credentialSets.filter((credentialSet) => existingCredentials?.[credentialSet.id] === void 0);
+}
+function createHostedIntegrationCredentialError(integrationId, sourceLabel, guidance, reason) {
+	const message = `Hosted integration "${integrationId}" cannot resolve credentials locally in ${sourceLabel}. Official hosted integrations must execute through the Keystroke dev server. ${guidance}`;
+	return reason instanceof Error ? new Error(message, { cause: reason }) : new Error(message);
+}
+async function createTestCredentialResolver(options, runtimeOptions = {}) {
+	if (options.mode === "off") return;
+	const sourceLabel = runtimeOptions.sourceLabel ?? "Keystroke test runtime";
+	const createCredentialGuidance = (integrationId) => (runtimeOptions.credentialGuidance ?? "Run `keystroke auth`, configure server-backed credentials (for example `keystroke connect ${integrationId}` when applicable), then retry.").replaceAll("${integrationId}", integrationId);
+	const serverResolver = options.mode === "env-only" ? void 0 : await createServerCredentialResolver(options);
+	const warnedCredentialSets = /* @__PURE__ */ new Set();
+	return { async resolveOperationCredentials(step, partialContext) {
+		const hostedIntegrationMetadata = getOfficialIntegrationMetadata(step);
+		const missingCredentialSets = pickMissingCredentialSets(step.credentialSets, partialContext.credentials);
+		if (missingCredentialSets.length === 0) return;
+		const resolvedCredentials = {};
+		for (const credentialSet of missingCredentialSets) {
+			const overrideCredentials = options.overrides?.[credentialSet.id];
+			const requiredKeys = getCredentialSetKeys(credentialSet);
+			if (overrideCredentials) {
+				resolvedCredentials[credentialSet.id] = overrideCredentials;
+				continue;
+			}
+			if (hostedIntegrationMetadata?.hosted) {
+				if (!serverResolver) throw createHostedIntegrationCredentialError(hostedIntegrationMetadata.integrationId, sourceLabel, createCredentialGuidance(hostedIntegrationMetadata.integrationId));
+				try {
+					resolvedCredentials[credentialSet.id] = await serverResolver.resolveCredentialSet(credentialSet, requiredKeys);
+				} catch (error) {
+					throw createHostedIntegrationCredentialError(hostedIntegrationMetadata.integrationId, sourceLabel, createCredentialGuidance(hostedIntegrationMetadata.integrationId), error);
+				}
+				continue;
+			}
+			const envResult = resolveCredentialsFromEnv(credentialSet, { lenient: true });
+			if (Object.keys(envResult.credentials).length > 0 && !warnedCredentialSets.has(credentialSet.id)) {
+				warnedCredentialSets.add(credentialSet.id);
+				console.warn(`[keystroke:test] Using local env vars for "${credentialSet.id}": ${envResult.envVarNames.join(", ")}`);
+			}
+			if (requiredKeys.every((key) => envResult.credentials[key] !== void 0)) {
+				resolvedCredentials[credentialSet.id] = envResult.credentials;
+				continue;
+			}
+			if (!serverResolver) {
+				const strictEnvResult = resolveCredentialsFromEnv(credentialSet);
+				resolvedCredentials[credentialSet.id] = strictEnvResult.credentials;
+				continue;
+			}
+			const serverCredentials = await serverResolver.resolveCredentialSet(credentialSet, requiredKeys);
+			resolvedCredentials[credentialSet.id] = {
+				...serverCredentials,
+				...envResult.credentials
+			};
+		}
+		return Object.keys(resolvedCredentials).length > 0 ? resolvedCredentials : void 0;
+	} };
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/credentials/options.ts
+const DEFAULT_TEST_CREDENTIAL_MODE = "auto";
+//#endregion
+//#region ../../packages/workflow-core/src/shared/create-mock-hook.ts
+/**
+* Creates a Hook that resolves immediately when awaited.
+*
+* Use when testing workflows that call ctx.createHook() (e.g., human-in-the-loop
+* approval steps). Without a mock, the workflow would block waiting for external
+* approval. This hook resolves immediately so tests complete without delay.
+*
+* @example
+* const runtime = createTestWorkflowContext({
+*   createHook: () => createMockHook(),
+* });
+* await myWorkflow.run(input, runtime);
+*/
+function createMockHook() {
+	const resolved = Promise.resolve(void 0);
+	return {
+		then: (onfulfilled, onrejected) => resolved.then(onfulfilled, onrejected),
+		token: Promise.resolve("mock-token"),
+		resumeUrl: Promise.resolve("http://mock/resume"),
+		cancelUrl: Promise.resolve("http://mock/cancel"),
+		approvalPageUrl: Promise.resolve("http://mock/approve")
+	};
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/helpers/create-test-workflow-context.ts
+function createTestWorkflowContext(options = {}) {
+	return {
+		createHook: options.createHook ?? ((_name) => createMockHook()),
+		stepContext: options.stepContext,
+		wait: options.wait ?? (async () => {}),
+		hasCredentialSet: options.hasCredentialSet ?? (() => false),
+		workflowGlobals: options.workflowGlobals,
+		workflowId: options.workflowId ?? "test-workflow-run"
+	};
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/hosted-actions/create-test-hosted-action-dispatcher.ts
+function createHostedDispatchError(integrationId, sourceLabel, detail, cause) {
+	const message = `Hosted integration "${integrationId}" failed in ${sourceLabel}. ${detail}`;
+	return cause instanceof Error ? new Error(message, { cause }) : new Error(message);
+}
+async function createTestHostedActionDispatcher(options, dependencies = {
+	fetch: globalThis.fetch,
+	resolveAuthOptions
+}) {
+	if (options.mode !== "auto") return;
+	const source = options.source ?? "test-runtime";
+	const sourceLabel = options.sourceLabel ?? "Keystroke test runtime";
+	let resolvedAuth;
+	let authResolutionError;
+	try {
+		resolvedAuth = await dependencies.resolveAuthOptions({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+			credentialsPath: options.credentialsPath
+		});
+	} catch (error) {
+		authResolutionError = error;
+	}
+	return { async dispatch(operation, integrationId, input) {
+		const actionId = `${integrationId}.${operation.id}`;
+		const publicCredentialSetId = (operation.credentialSets ?? [])[0]?.id ?? integrationId;
+		if (authResolutionError) throw createHostedDispatchError(integrationId, sourceLabel, "Run `keystroke auth` and ensure the Keystroke dev server URL is configured before retrying.", authResolutionError);
+		if (!resolvedAuth?.apiKey) throw createHostedDispatchError(integrationId, sourceLabel, "Run `keystroke auth` so the test runtime can authenticate hosted action dispatch.");
+		if (!resolvedAuth.baseUrl) throw createHostedDispatchError(integrationId, sourceLabel, "Configure the Keystroke dev server URL and retry.");
+		const { apiKey, baseUrl } = resolvedAuth;
+		const organizationId = resolvedAuth.activeOrg?.organizationId ?? "local";
+		try {
+			const response = await dependencies.fetch(new URL("/api/v1/hosted-actions/dispatch", baseUrl).toString(), {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({
+					version: 1,
+					actionId,
+					source,
+					organizationId,
+					connection: { publicCredentialSetId },
+					correlation: { testRunId: crypto.randomUUID() },
+					input
+				})
+			});
+			if (response.status === 404) throw createHostedDispatchError(integrationId, sourceLabel, "The connected Keystroke server does not support hosted action dispatch for this integration.");
+			if (response.status === 401 || response.status === 403) throw createHostedDispatchError(integrationId, sourceLabel, "Authentication failed. Run `keystroke auth`, confirm the active organization, and retry.");
+			if (response.status === 422) {
+				const text = await response.text().catch(() => "");
+				throw createHostedDispatchError(integrationId, sourceLabel, "The Keystroke dev server is missing hosted/platform credentials for this integration. Configure the server-side credentials and retry.", new Error(text));
+			}
+			if (!response.ok) {
+				const text = await response.text().catch(() => "");
+				throw createHostedDispatchError(integrationId, sourceLabel, `Dispatch returned status ${response.status}. ${text}`.trim());
+			}
+			const body = await response.json();
+			if (!body.ok) throw createHostedDispatchError(integrationId, sourceLabel, `Hosted action "${actionId}" failed: [${body.error?.code}] ${body.error?.message}`);
+			return {
+				handled: true,
+				result: body.result
+			};
+		} catch (error) {
+			if (error instanceof TypeError && "cause" in error) throw createHostedDispatchError(integrationId, sourceLabel, "The Keystroke dev server is unreachable. Start the server and retry.", error);
+			throw error;
+		}
+	} };
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/runtime/create-keystroke-test-runtime.ts
+async function createKeystrokeTestRuntime(options = {}) {
+	clearHostedActionDispatcher();
+	clearHostedActionExecutionPolicy();
+	clearOperationCredentialResolver();
+	clearOperationContext();
+	clearRuntime();
+	const credentials = {
+		mode: DEFAULT_TEST_CREDENTIAL_MODE,
+		...options.credentials
+	};
+	const sourceLabel = options.sourceLabel ?? "Keystroke test runtime";
+	const credentialResolver = await createTestCredentialResolver(credentials, { sourceLabel });
+	const hostedActionDispatcher = await createTestHostedActionDispatcher({
+		...credentials,
+		source: options.source,
+		sourceLabel
+	});
+	registerRuntime({ getRuntime: () => ({
+		context: createTestWorkflowContext(options),
+		stepContext: options.stepContext
+	}) });
+	registerOperationContext({ getOperationContext: () => ({
+		attempt: options.stepContext?.attempt,
+		credentials: options.stepContext?.credentials ?? {},
+		maxAttempts: options.stepContext?.maxAttempts,
+		stepId: options.stepContext?.stepId ?? "test-step-run",
+		workflowGlobals: options.workflowGlobals
+	}) });
+	if (credentials.mode !== "off") registerHostedActionExecutionPolicy("strict");
+	if (credentialResolver) registerOperationCredentialResolver(credentialResolver);
+	if (hostedActionDispatcher) registerHostedActionDispatcher(hostedActionDispatcher);
+	return { dispose() {
+		clearHostedActionDispatcher();
+		clearHostedActionExecutionPolicy();
+		clearOperationCredentialResolver();
+		clearOperationContext();
+		clearRuntime();
+	} };
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/tools/create-test-tool-context.ts
+/**
+* Builds a minimal `OperationRunContext` for tool/step unit tests.
+*
+* Propagates every `Partial<OperationRunContext>` field the caller provides
+* (credentials, workflowGlobals, stepId, attempt, maxAttempts, toolCallId,
+* traceparent, tracestate). This keeps tests authoritative when they want
+* to assert on retry counts, telemetry headers, or tool-call ids.
+*/
+function createTestToolContext(options = {}) {
+	return {
+		...options,
+		credentials: options.credentials ?? {},
+		workflowGlobals: options.workflowGlobals
+	};
+}
+//#endregion
+//#region ../../packages/workflow-core/src/test-runtime/tools/run-tool.ts
+async function runTool(tool, input, options) {
+	const ctx = createTestToolContext(options);
+	return tool.run(input, ctx);
+}
+//#endregion
+//#region src/commands/test/tool.handler.ts
+const SECRET_FIELD_PATTERN = /(api[_-]?key|access[_-]?key|private[_-]?key|password|secret|token|credential)/i;
+const testToolDependencies = {
+	readManifestsFromOutDir,
+	runWorkflowBuild,
+	createKeystrokeTestRuntime,
+	runTool
+};
+async function handleTestTool(options, ctx) {
+	const client = requireClient(ctx);
+	const workflowsDir = await requireWorkflowsDir(options.path);
+	const projectConfig = await assertWorkflowProjectRoot(workflowsDir);
+	await assertProjectConfigMatchesAuthenticatedOrg(client, projectConfig);
+	const input = await resolveInput({
+		...options,
+		workflow: options.toolName
+	});
+	const resolved = await resolveBuiltTool(workflowsDir, options.toolName, options.agent);
+	if (resolved.tool.sourceKind === "workflow") {
+		await executeWorkflowTool({
+			options,
+			ctx,
+			input,
+			resolved,
+			projectId: projectConfig.projectId
+		});
+		return;
+	}
+	if (resolved.tool.sourceKind === "operation") {
+		await executeOperationTool({
+			options,
+			ctx,
+			input,
+			resolved
+		});
+		return;
+	}
+	throwReportedCliExit(`Tool "${options.toolName}" has unsupported sourceKind "${resolved.tool.sourceKind ?? "unknown"}".`);
+}
+async function executeWorkflowTool(params) {
+	const { options, ctx, input, resolved, projectId } = params;
+	const client = requireClient(ctx);
+	if (!resolved.tool.authoredWorkflowId) throwReportedCliExit(`Workflow tool "${options.toolName}" is missing authoredWorkflowId.`);
+	const inputSchema = (await resolveWorkflowManifest(resolved.workflowsDir, resolved.tool.authoredWorkflowId)).workflowSchemas.input;
+	if (inputSchema && typeof inputSchema === "object" && !Array.isArray(inputSchema)) validateInputOrExit(options.toolName, input, inputSchema);
+	const deploymentLookup = await lookupCurrentDeploymentWorkflow(client, {
+		projectId,
+		authoredWorkflowId: resolved.tool.authoredWorkflowId
+	});
+	if (deploymentLookup.status !== "found") throwReportedCliExit(`Workflow tool "${options.toolName}" is not available in the current deployment. Run \`keystroke deploy\` first.`);
+	if (resolved.tool.deploymentId && deploymentLookup.workflow.deploymentId !== resolved.tool.deploymentId) throwReportedCliExit(`Workflow tool "${options.toolName}" is pinned to deployment ${resolved.tool.deploymentId}, but the current deployment is ${deploymentLookup.workflow.deploymentId}. Redeploy the agent before testing.`);
+	ui.header(`Testing workflow tool "${options.toolName}"...`);
+	const { runId } = await client.workflows.execute({
+		projectId,
+		authoredWorkflowId: resolved.tool.authoredWorkflowId,
+		args: [input]
+	});
+	const snapshot = await pollForCompletion(client, runId, options.timeout, options.verbose);
+	if (ctx.jsonMode) {
+		writeJson({
+			toolName: options.toolName,
+			sourceKind: "workflow",
+			runId,
+			run: snapshot.run,
+			logs: snapshot.logs
+		});
+		return;
+	}
+	ui.hint(`Run ID: ${runId}`);
+	if (snapshot.run.status === "completed") {
+		ui.success(`Tool "${options.toolName}" completed.`);
+		if (snapshot.run.output !== void 0 && snapshot.run.output !== null) {
+			ui.br();
+			ui.header("Output:");
+			ui.text(JSON.stringify(snapshot.run.output, null, 2));
+		}
+		return;
+	}
+	if (snapshot.run.status === "failed") {
+		if (snapshot.run.error) ui.error(toErrorMessage(snapshot.run.error));
+		throw new CliExitError(`Tool "${options.toolName}" failed.`);
+	}
+	ui.warn(`Tool "${options.toolName}" still ${snapshot.run.status} after ${options.timeout}s.`);
+	throw new CliExitError(`Tool "${options.toolName}" did not complete before timeout.`);
+}
+async function executeOperationTool(params) {
+	const { options, ctx, input, resolved } = params;
+	const operation = await loadOperationTool(resolved.artifact, resolved.tool);
+	const runtime = await testToolDependencies.createKeystrokeTestRuntime({
+		credentials: {
+			mode: "auto",
+			apiKey: ctx.apiKey,
+			baseUrl: ctx.baseUrl,
+			credentialsPath: ctx.credentialsPath
+		},
+		source: "cli",
+		sourceLabel: "CLI"
+	});
+	try {
+		ui.header(`Testing operation tool "${options.toolName}"...`);
+		const redacted = redactToolOutput(await testToolDependencies.runTool(operation, input), resolved.artifact.manifest);
+		if (ctx.jsonMode) {
+			writeJson({
+				toolName: options.toolName,
+				sourceKind: "operation",
+				output: redacted.value
+			});
+			return;
+		}
+		ui.success(`Tool "${options.toolName}" completed.`);
+		if (redacted.changed) ui.warn("Output contained credential-looking values and was redacted.");
+		ui.br();
+		ui.header("Output:");
+		ui.text(JSON.stringify(redacted.value, null, 2));
+	} finally {
+		runtime.dispose();
+	}
+}
+async function resolveBuiltTool(workflowsDir, toolName, agentRef) {
+	let build;
+	try {
+		build = await testToolDependencies.runWorkflowBuild({
+			workflowsDir,
+			verbose: false,
+			force: false
+		});
+	} catch (error) {
+		renderBuildFailure(error);
+		throwReportedCliExit(`Build failed while resolving tool "${toolName}".`, { cause: error });
+	}
+	const matches = findToolMatches(build.result.agentArtifacts, toolName, agentRef, workflowsDir);
+	if (matches.length === 0) throwReportedCliExit(`Tool "${toolName}" not found in built agent manifests.`);
+	if (matches.length > 1) {
+		ui.error(`Tool "${toolName}" exists in multiple agents.`);
+		for (const match of matches) ui.hint(`- ${match.artifact.manifest.authoredAgentId} (${match.artifact.manifest.agentName})`);
+		ui.hint("Pass --agent <agentId> to select one.");
+		throwReportedCliExit(`Tool "${toolName}" exists in multiple agents.`);
+	}
+	const match = matches[0];
+	if (!match) throwReportedCliExit(`Tool "${toolName}" not found in built agent manifests.`);
+	return match;
+}
+function findToolMatches(artifacts, toolName, agentRef, workflowsDir) {
+	const matches = [];
+	for (const artifact of artifacts) {
+		if (agentRef && !manifestMatchesRef(artifact.manifest, agentRef)) continue;
+		const tool = (artifact.manifest.tools ?? []).find((candidate) => candidate.toolName === toolName);
+		if (tool) matches.push({
+			artifact,
+			tool,
+			workflowsDir: workflowsDir ?? ""
+		});
+	}
+	return matches;
+}
+async function resolveWorkflowManifest(workflowsDir, authoredWorkflowId) {
+	const match = (await testToolDependencies.readManifestsFromOutDir(workflowsDir, authoredWorkflowId))[0];
+	if (match) return match.manifest;
+	throwReportedCliExit(`Workflow "${authoredWorkflowId}" for tool was not found locally.`);
+}
+async function loadOperationTool(artifact, tool) {
+	const operation = ((await loadAgentFromBundle(artifact)).tools ?? []).find((candidate) => {
+		if (!candidate || typeof candidate !== "object") return false;
+		const candidateId = candidate.id;
+		return candidateId === tool.authoredOperationId || candidateId === tool.toolName;
+	});
+	if (!operation || typeof operation.run !== "function") throwReportedCliExit(`Operation tool "${tool.toolName}" was not found in the built agent bundle.`);
+	return operation;
+}
+async function loadAgentFromBundle(artifact) {
+	const tempDir = await mkdtemp(path.join(tmpdir(), "keystroke-agent-tool-test-"));
+	const modulePath = path.join(tempDir, "agent-bundle.mjs");
+	try {
+		await writeFile(modulePath, artifact.bundle.code, "utf-8");
+		const mod = await import(`${pathToFileURL(modulePath).href}?t=${Date.now()}`);
+		return mod[artifact.agent.localExportName] ?? mod.default;
+	} finally {
+		await rm(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function manifestMatchesRef(manifest, agentRef) {
+	return [
+		manifest.authoredAgentId,
+		manifest.agentId,
+		manifest.agentName,
+		manifest.displayName,
+		manifest.exportName
+	].some((value) => value === agentRef);
+}
+function redactToolOutput(output, manifest) {
+	return redactUnknown(output, collectKnownCredentialValues(manifest));
+}
+function collectKnownCredentialValues(manifest) {
+	const env = getProcessEnv();
+	const values = /* @__PURE__ */ new Set();
+	for (const credentialSet of manifest.credentialSets ?? []) for (const key of credentialSet.credentialKeys) for (const envName of [key, `KEYSTROKE_${key}`]) {
+		const value = env[envName];
+		if (typeof value === "string" && value.length >= 3) values.add(value);
+	}
+	return values;
+}
+function redactUnknown(value, knownSecretValues) {
+	if (typeof value === "string") return redactString(value, knownSecretValues);
+	if (Array.isArray(value)) {
+		let changed = false;
+		return {
+			value: value.map((entry) => {
+				const result = redactUnknown(entry, knownSecretValues);
+				changed ||= result.changed;
+				return result.value;
+			}),
+			changed
+		};
+	}
+	if (isPlainRecord(value)) {
+		let changed = false;
+		const redacted = {};
+		for (const [key, entry] of Object.entries(value)) {
+			if (SECRET_FIELD_PATTERN.test(key) && typeof entry === "string") {
+				redacted[key] = "[REDACTED]";
+				changed = true;
+				continue;
+			}
+			const result = redactUnknown(entry, knownSecretValues);
+			redacted[key] = result.value;
+			changed ||= result.changed;
+		}
+		return {
+			value: redacted,
+			changed
+		};
+	}
+	return {
+		value,
+		changed: false
+	};
+}
+function isPlainRecord(value) {
+	if (!value || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function redactString(value, knownSecretValues) {
+	let redacted = value;
+	for (const secret of knownSecretValues) redacted = redacted.split(secret).join("[REDACTED]");
+	return {
+		value: redacted,
+		changed: redacted !== value
+	};
+}
+//#endregion
+//#region src/commands/test/test.command.ts
+const TestOptionsSchema = JsonOptionSchema;
+const TestToolOptionsSchema = JsonOptionSchema.extend({
+	toolName: z.string().min(1),
+	agent: z.string().min(1).optional(),
+	input: z.string().optional(),
+	inputFile: z.string().optional(),
+	path: z.string().optional(),
+	timeout: z.coerce.number().int().min(1).default(120),
+	verbose: z.boolean().default(false)
+});
+const TEST_OPTIONS_CONFIG = { ...JSON_OPTION_CONFIG };
+const TEST_TOOL_OPTIONS_CONFIG = {
+	...JSON_OPTION_CONFIG,
+	agent: {
+		flag: "--agent <agentId>",
+		description: "Authored agent id, agent id, or agent name containing the tool"
+	},
+	input: {
+		flag: "--input <json>",
+		description: "Tool input as inline JSON string"
+	},
+	inputFile: {
+		flag: "--input-file <path>",
+		description: "Path to a JSON file containing tool input"
+	},
+	path: {
+		flag: "--path <dir>",
+		description: "Path to project root (directory containing keystroke.config.ts); auto-discovered from CWD if omitted"
+	},
+	timeout: {
+		flag: "--timeout <seconds>",
+		description: "Max seconds to wait for workflow completion (default: 120)"
+	},
+	verbose: {
+		flag: "--verbose",
+		description: "Show detailed execution logs while polling workflow tools"
+	}
+};
+function handleTestHelp() {
+	ui.hint("Use `keystroke test tool <toolName> --input='{...}'` or `keystroke test workflow <workflow>`.");
+}
+function createTestCommand() {
+	const cmd = createTypedCommand({
+		name: "test",
+		description: "Test workflows and agent-callable tools",
+		schema: TestOptionsSchema,
+		optionsConfig: TEST_OPTIONS_CONFIG,
+		handler: handleTestHelp,
+		subcommands: [createTypedCommand({
+			name: "tool",
+			description: "Test an agent-callable tool from a built agent manifest",
+			schema: TestToolOptionsSchema,
+			optionsConfig: TEST_TOOL_OPTIONS_CONFIG,
+			argument: {
+				name: "toolName",
+				description: "Agent tool name from the built manifest",
+				key: "toolName"
+			},
+			handler: handleTestTool
+		}), createTypedCommand({
+			name: "workflow",
+			description: "Build, upload, and run a workflow on the server",
+			schema: WorkflowsRunOptionsSchema,
+			optionsConfig: RUN_OPTIONS_CONFIG,
+			argument: {
+				name: "workflow",
+				description: "Authored workflow id (preferred) or workflow name. Multiple workflows with the same name run sequentially.",
+				key: "workflow"
+			},
+			handler: handleWorkflowsTryDeploy
+		})]
+	});
+	cmd.enablePositionalOptions();
+	cmd.passThroughOptions();
+	return cmd;
+}
+//#endregion
+export { createTestCommand };