@outfitter/testing 0.2.4 → 0.3.0

package/dist/shared/@outfitter/testing-s2fyaxm2.d.ts

@@ -0,0 +1,134 @@
+import { CliTestResult } from "./testing-fyjbwn80.js";
+import { CLI } from "@outfitter/cli/command";
+import { CommandEnvelope } from "@outfitter/cli/envelope";
+/**
+* Options for testCommand().
+*/
+interface TestCommandOptions {
+	/**
+	* Environment variables to set during CLI execution.
+	* Variables are restored to their original values after execution.
+	*/
+	readonly env?: Readonly<Record<string, string>>;
+	/**
+	* Pre-parsed input object to convert to CLI arguments.
+	*
+	* Each key-value pair is converted to a `--key value` argument:
+	* - `string` → `--key value`
+	* - `number` → `--key value` (stringified)
+	* - `boolean` → `--key` (true) or omitted (false)
+	* - `string[]` → repeated `--key value1 --key value2`
+	*
+	* Input args are appended after the explicit `args` parameter,
+	* allowing both positional args and input overrides.
+	*
+	* @example
+	* ```typescript
+	* // Converts to: ["greet", "--name", "World"]
+	* await testCommand(cli, ["greet"], { input: { name: "World" } });
+	* ```
+	*/
+	readonly input?: Readonly<Record<string, unknown>>;
+	/**
+	* Mock context object to inject into the command execution.
+	*
+	* When provided, the context is stored in a test injection point
+	* and can be retrieved by context factories via `getTestContext()`.
+	* The context is cleaned up after execution.
+	*
+	* @example
+	* ```typescript
+	* await testCommand(cli, ["status"], {
+	*   context: { db: mockDb, config: testConfig },
+	* });
+	* ```
+	*/
+	readonly context?: Readonly<Record<string, unknown>>;
+	/**
+	* Force JSON output mode by setting OUTFITTER_JSON=1.
+	*
+	* When true, the CLI produces JSON output which is automatically
+	* parsed into the `envelope` field of the result.
+	*/
+	readonly json?: boolean;
+}
+/**
+* Enhanced CLI test result with optional envelope parsing.
+*
+* Extends the base `CliTestResult` with an `envelope` field that
+* contains the parsed `CommandEnvelope` when JSON output is detected.
+*/
+interface TestCommandResult extends CliTestResult {
+	/**
+	* Parsed command envelope from JSON output.
+	*
+	* Present when the command outputs a JSON envelope (either via
+	* `runHandler()` with JSON format or when `json: true` is set).
+	* Undefined for non-JSON output.
+	*/
+	readonly envelope?: CommandEnvelope | undefined;
+}
+/**
+* Retrieve the injected test context, if any.
+*
+* Context factories in builder-pattern commands can call this
+* to use the test-provided context instead of constructing a real one.
+*
+* @returns The injected context, or `undefined` if not in a test
+*
+* @example
+* ```typescript
+* // In your command definition:
+* command("status")
+*   .context(async (input) => {
+*     // Use test context if available, otherwise create real one
+*     const testCtx = getTestContext();
+*     if (testCtx) return testCtx;
+*     return { db: await connectDb() };
+*   })
+* ```
+*/
+declare function getTestContext<T extends Record<string, unknown> = Record<string, unknown>>(): T | undefined;
+/**
+* Execute a CLI instance with given arguments and capture output.
+*
+* Creates a fresh CLI instance from the same program, configured with
+* `onExit` to capture exit codes cleanly. Wraps `captureCLI()` to
+* intercept stdout, stderr, and process.exit during execution.
+* No side effects leak to real stdout, stderr, or process.exit.
+* Global process state is fully restored after each call.
+*
+* ### v0.5 Enhancements
+*
+* - **`input`**: Pre-parsed input object auto-converted to CLI args.
+*   Keys become `--key value` flags, booleans become presence/absence flags.
+* - **`context`**: Mock context object injectable via `getTestContext()`.
+*   Context factories can use this to skip real resource construction in tests.
+* - **`json`**: Forces JSON output mode (OUTFITTER_JSON=1) so the result
+*   includes a parsed `envelope` field.
+* - **`envelope`**: Parsed `CommandEnvelope` from JSON output, available on
+*   the result for structured assertion.
+*
+* @param cli - A CLI instance created by `createCLI()`
+* @param args - Command-line arguments (without the program name prefix)
+* @param options - Optional configuration for the test execution
+* @returns Captured stdout, stderr, exitCode, and optional envelope
+*
+* @example
+* ```typescript
+* // Basic usage (backward compatible)
+* const result = await testCommand(cli, ["hello"]);
+* expect(result.stdout).toContain("Hello!");
+*
+* // With pre-parsed input
+* const result = await testCommand(cli, ["greet"], {
+*   input: { name: "World" },
+* });
+*
+* // With JSON envelope
+* const result = await testCommand(cli, ["info"], { json: true });
+* expect(result.envelope?.ok).toBe(true);
+* ```
+*/
+declare function testCommand(cli: CLI, args: string[], options?: TestCommandOptions): Promise<TestCommandResult>;
+export { TestCommandOptions, TestCommandResult, getTestContext, testCommand };

package/dist/shared/@outfitter/{testing-kdwa417a.js → testing-xcd5p1gm.js}

@@ -8,7 +8,7 @@ function createTestLogger(context = {}) {
 }
 function createTestLoggerWithContext(context, logs) {
   const write = (level, message, data) => {
-    const merged = { ...context, ...data ?? {} };
+    const merged = { ...context, ...data };
     const entry = {
       level,
       message

package/dist/test-command.d.ts

@@ -0,0 +1,3 @@
+import { TestCommandOptions, TestCommandResult, getTestContext, testCommand } from "./shared/@outfitter/testing-s2fyaxm2.js";
+import "./shared/@outfitter/testing-fyjbwn80.js";
+export { testCommand, getTestContext, TestCommandResult, TestCommandOptions };

package/dist/test-command.js

@@ -0,0 +1,114 @@
+// @bun
+import {
+  captureCLI
+} from "./shared/@outfitter/testing-xsfjh1n3.js";
+
+// packages/testing/src/test-command.ts
+var injectedTestContext;
+var executionChain = Promise.resolve();
+function getTestContext() {
+  return injectedTestContext;
+}
+async function withProcessLock(run) {
+  const prior = executionChain;
+  let release;
+  executionChain = new Promise((resolve) => {
+    release = resolve;
+  });
+  await prior;
+  try {
+    return await run();
+  } finally {
+    release?.();
+  }
+}
+function inputToArgs(input) {
+  const args = [];
+  for (const [key, value] of Object.entries(input)) {
+    const kebabKey = key.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+    const flag = `--${kebabKey}`;
+    if (typeof value === "boolean") {
+      if (value) {
+        args.push(flag);
+      }
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        args.push(flag, String(item));
+      }
+    } else if (value !== undefined && value !== null) {
+      args.push(flag, String(value));
+    }
+  }
+  return args;
+}
+function parseEnvelope(stdout, stderr) {
+  const stdoutEnvelope = tryParseEnvelope(stdout);
+  if (stdoutEnvelope)
+    return stdoutEnvelope;
+  const stderrEnvelope = tryParseEnvelope(stderr);
+  if (stderrEnvelope)
+    return stderrEnvelope;
+  return;
+}
+function tryParseEnvelope(text) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{"))
+    return;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed["ok"] === "boolean" && typeof parsed["command"] === "string") {
+      return parsed;
+    }
+  } catch {}
+  return;
+}
+async function testCommand(cli, args, options) {
+  return withProcessLock(async () => {
+    const originalEnv = { ...process.env };
+    if (options?.env) {
+      for (const [key, value] of Object.entries(options.env)) {
+        process.env[key] = value;
+      }
+    }
+    if (options?.json) {
+      process.env["OUTFITTER_JSON"] = "1";
+    }
+    if (options?.context) {
+      injectedTestContext = { ...options.context };
+    }
+    const inputArgs = options?.input ? inputToArgs(options.input) : [];
+    const fullArgs = [...args, ...inputArgs];
+    const savedArgv = process.argv;
+    const testArgv = ["node", "test", ...fullArgs];
+    process.argv = testArgv;
+    try {
+      const cliResult = await captureCLI(async () => {
+        await cli.parse(testArgv);
+      });
+      const envelope = parseEnvelope(cliResult.stdout, cliResult.stderr);
+      return {
+        ...cliResult,
+        envelope
+      };
+    } finally {
+      process.argv = savedArgv;
+      for (const key of Object.keys(process.env)) {
+        if (!(key in originalEnv)) {
+          delete process.env[key];
+        }
+      }
+      for (const [key, value] of Object.entries(originalEnv)) {
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
+      injectedTestContext = undefined;
+    }
+  });
+}
+export {
+  testCommand,
+  getTestContext
+};

package/dist/test-tool.d.ts

@@ -0,0 +1,2 @@
+import { TestToolOptions, TestToolResult, testTool } from "./shared/@outfitter/testing-136ebq11.js";
+export { testTool, TestToolResult, TestToolOptions };

package/dist/test-tool.js

@@ -0,0 +1,58 @@
+// @bun
+import {
+  createTestContext
+} from "./shared/@outfitter/testing-xcd5p1gm.js";
+
+// packages/testing/src/test-tool.ts
+import {
+  formatZodIssues,
+  Result,
+  ValidationError
+} from "@outfitter/contracts";
+async function testTool(tool, input, options) {
+  const parseResult = tool.inputSchema.safeParse(input);
+  if (!parseResult.success) {
+    const errorMessages = formatZodIssues(parseResult.error.issues);
+    return Result.err(new ValidationError({
+      message: `Invalid input: ${errorMessages}`
+    }));
+  }
+  const ctxOverrides = {};
+  if (options?.requestId !== undefined) {
+    ctxOverrides.requestId = options.requestId;
+  }
+  if (options?.cwd !== undefined) {
+    ctxOverrides.cwd = options.cwd;
+  }
+  if (options?.env !== undefined) {
+    ctxOverrides.env = options.env;
+  }
+  if (options?.context) {
+    Object.assign(ctxOverrides, options.context);
+  }
+  const ctx = createTestContext(ctxOverrides);
+  const result = await tool.handler(parseResult.data, ctx);
+  if (options?.hints && result.isOk()) {
+    const hints = options.hints(result.value);
+    if (hints.length > 0) {
+      const enhanced = Object.create(Object.getPrototypeOf(result));
+      for (const key of Reflect.ownKeys(result)) {
+        const descriptor = Object.getOwnPropertyDescriptor(result, key);
+        if (descriptor) {
+          Object.defineProperty(enhanced, key, descriptor);
+        }
+      }
+      Object.defineProperty(enhanced, "hints", {
+        value: hints,
+        enumerable: true,
+        configurable: true,
+        writable: false
+      });
+      return enhanced;
+    }
+  }
+  return result;
+}
+export {
+  testTool
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/testing",
   "description": "Test harnesses, fixtures, and utilities for Outfitter packages",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "dist"
@@ -45,32 +45,25 @@
         "default": "./dist/mock-factories.js"
       }
     },
-    "./package.json": "./package.json"
-  },
-  "sideEffects": false,
-  "scripts": {
-    "build": "bunup --filter @outfitter/testing",
-    "lint": "biome lint ./src",
-    "lint:fix": "biome lint --write ./src",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
-  },
-  "dependencies": {
-    "@outfitter/contracts": "0.4.1",
-    "@outfitter/mcp": "0.4.2",
-    "zod": "^4.3.5"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "typescript": "^5.8.0"
+    "./package.json": "./package.json",
+    "./test-command": {
+      "import": {
+        "types": "./dist/test-command.d.ts",
+        "default": "./dist/test-command.js"
+      }
+    },
+    "./test-tool": {
+      "import": {
+        "types": "./dist/test-tool.d.ts",
+        "default": "./dist/test-tool.js"
+      }
+    }
   },
   "keywords": [
-    "outfitter",
-    "testing",
     "fixtures",
     "harness",
+    "outfitter",
+    "testing",
     "typescript"
   ],
   "license": "MIT",
@@ -79,7 +72,27 @@
     "url": "https://github.com/outfitter-dev/outfitter.git",
     "directory": "packages/testing"
   },
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "cd ../.. && bash ./scripts/run-bunup-with-lock.sh bunup --filter @outfitter/testing",
+    "lint": "oxlint ./src",
+    "lint:fix": "oxlint --fix ./src",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
+  },
+  "dependencies": {
+    "@outfitter/cli": "1.0.0",
+    "@outfitter/contracts": "0.5.0",
+    "@outfitter/mcp": "0.5.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.3"
   }
 }

package/dist/shared/@outfitter/testing-05hzzr8n.js

@@ -1,48 +0,0 @@
-// @bun
-import {
-  loadFixture
-} from "./testing-1wd76sr8.js";
-
-// packages/testing/src/mcp-harness.ts
-import {
-  createMcpServer
-} from "@outfitter/mcp";
-function createMcpHarness(server, options = {}) {
-  return {
-    callTool(name, input) {
-      return server.invokeTool(name, input);
-    },
-    listTools() {
-      return server.getTools();
-    },
-    searchTools(query) {
-      const normalized = query.trim().toLowerCase();
-      const tools = server.getTools();
-      if (normalized.length === 0) {
-        return tools;
-      }
-      return tools.filter((tool) => {
-        const nameMatch = tool.name.toLowerCase().includes(normalized);
-        const descriptionMatch = tool.description.toLowerCase().includes(normalized);
-        return nameMatch || descriptionMatch;
-      });
-    },
-    loadFixture(name) {
-      return loadFixture(name, options.fixturesDir ? { fixturesDir: options.fixturesDir } : undefined);
-    },
-    reset() {}
-  };
-}
-function createMCPTestHarness(options) {
-  const server = createMcpServer({
-    name: options.name ?? "mcp-test",
-    version: options.version ?? "0.0.0"
-  });
-  for (const tool of options.tools) {
-    server.registerTool(tool);
-  }
-  return createMcpHarness(server, {
-    ...options.fixturesDir !== undefined ? { fixturesDir: options.fixturesDir } : {}
-  });
-}
-export { createMcpHarness, createMCPTestHarness };

package/dist/shared/@outfitter/testing-wfp5f7pq.js

@@ -1,29 +0,0 @@
-// @bun
-// packages/testing/src/cli-harness.ts
-function createCliHarness(command) {
-  return {
-    async run(args) {
-      const child = Bun.spawn([command, ...args], {
-        stdin: "pipe",
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      child.stdin?.end();
-      const stdoutPromise = child.stdout ? new Response(child.stdout).text() : Promise.resolve("");
-      const stderrPromise = child.stderr ? new Response(child.stderr).text() : Promise.resolve("");
-      const exitCodePromise = child.exited;
-      const [stdout, stderr, exitCode] = await Promise.all([
-        stdoutPromise,
-        stderrPromise,
-        exitCodePromise
-      ]);
-      return {
-        stdout,
-        stderr,
-        exitCode: typeof exitCode === "number" ? exitCode : 1
-      };
-    }
-  };
-}
-
-export { createCliHarness };