@agent-inspect/harness 3.0.0

package/dist/index.d.cts

@@ -0,0 +1,101 @@
+import { InspectRunOptions } from 'agent-inspect';
+
+type HarnessDiagnosticSeverity = "warning" | "error";
+type HarnessDiagnosticCode = "target_not_found" | "bootstrap_failed" | "resolve_failed" | "invoke_failed" | "shutdown_failed" | "cli_usage_error" | "fixture_read_failed" | "stdin_read_failed" | "expected_read_failed" | "expected_output_mismatch";
+interface HarnessDiagnosticError {
+    name?: string;
+    message: string;
+    stack?: string;
+}
+interface HarnessDiagnostic {
+    code: HarnessDiagnosticCode;
+    severity: HarnessDiagnosticSeverity;
+    message: string;
+    targetName?: string;
+    timestamp: number;
+    error?: HarnessDiagnosticError;
+}
+type HarnessDiagnosticInput = Omit<HarnessDiagnostic, "timestamp"> & {
+    timestamp?: number;
+};
+interface FixtureRunnerContext<TApp = unknown> {
+    readonly runnerName: string;
+    readonly targetName: string;
+    readonly app: TApp | undefined;
+    addDiagnostic(diagnostic: HarnessDiagnosticInput): void;
+    getDiagnostics(): readonly HarnessDiagnostic[];
+}
+interface TargetDefinition<TApp, TTarget, TInput, TOutput> {
+    /** Human-readable label for target listing. Experimental during v1.x. */
+    description?: string;
+    /** Safe, bounded metadata for local tooling and recipes. Experimental during v1.x. */
+    metadata?: Record<string, unknown>;
+    /** Resolve a framework-specific object or function from the bootstrapped app. */
+    resolve(app: TApp, context: FixtureRunnerContext<TApp>): TTarget | Promise<TTarget>;
+    /** Invoke the resolved target with fixture input. */
+    invoke(target: TTarget, input: TInput, context: FixtureRunnerContext<TApp>): TOutput | Promise<TOutput>;
+}
+type FixtureTargets<TApp = unknown> = Record<string, TargetDefinition<TApp, unknown, unknown, unknown>>;
+type TargetInput<TDefinition> = TDefinition extends TargetDefinition<infer _TApp, infer _TTarget, infer TInput, infer _TOutput> ? TInput : never;
+type TargetOutput<TDefinition> = TDefinition extends TargetDefinition<infer _TApp, infer _TTarget, infer _TInput, infer TOutput> ? TOutput : never;
+type HarnessTraceMode = "off" | "run" | "run-if-enabled" | "observe";
+interface HarnessTraceOptions extends InspectRunOptions {
+    /**
+     * `run-if-enabled` uses `maybeInspectRun()` and is the default.
+     * `observe` proxies resolved targets and traces `run` / `execute` / `invoke` methods when enabled.
+     */
+    mode?: HarnessTraceMode;
+    runName?: string | ((targetName: string) => string);
+}
+interface FixtureRunnerOptions<TApp, TTargets extends FixtureTargets<TApp>> {
+    name?: string;
+    targets: TTargets;
+    trace?: HarnessTraceOptions;
+    bootstrap?(context: FixtureRunnerContext<TApp>): TApp | Promise<TApp>;
+    shutdown?(app: TApp | undefined, context: FixtureRunnerContext<TApp>): void | Promise<void>;
+}
+interface FixtureRunOptions {
+    trace?: HarnessTraceOptions;
+}
+interface HarnessArgvIo {
+    cwd?: string;
+    stdin?(): string | Promise<string>;
+    stdout?(chunk: string): void;
+    stderr?(chunk: string): void;
+}
+interface HarnessArgvResult {
+    ok: boolean;
+    exitCode: 0 | 1;
+    targetName?: string;
+    listed?: boolean;
+    matchedExpected?: boolean;
+    output?: unknown;
+    error?: HarnessDiagnosticError;
+    diagnostics: readonly HarnessDiagnostic[];
+}
+interface HarnessTargetInfo {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+interface FixtureRunner<TApp, TTargets extends FixtureTargets<TApp>> {
+    listTargets(): HarnessTargetInfo[];
+    getDiagnostics(): readonly HarnessDiagnostic[];
+    runTarget<TName extends Extract<keyof TTargets, string>>(targetName: TName, input: TargetInput<TTargets[TName]>, options?: FixtureRunOptions): Promise<TargetOutput<TTargets[TName]>>;
+    runFromArgv(argv?: readonly string[], io?: HarnessArgvIo): Promise<HarnessArgvResult>;
+}
+declare class HarnessError extends Error {
+    readonly code: HarnessDiagnosticCode;
+    readonly targetName?: string;
+    constructor(code: HarnessDiagnosticCode, message: string, options?: {
+        targetName?: string;
+        cause?: unknown;
+    });
+}
+declare class HarnessTargetNotFoundError extends HarnessError {
+    constructor(targetName: string);
+}
+declare function defineTarget<TApp, TTarget, TInput, TOutput>(definition: TargetDefinition<TApp, TTarget, TInput, TOutput>): TargetDefinition<TApp, TTarget, TInput, TOutput>;
+declare function createFixtureRunner<TApp, const TTargets extends FixtureTargets<TApp>>(options: FixtureRunnerOptions<TApp, TTargets>): FixtureRunner<TApp, TTargets>;
+
+export { type FixtureRunOptions, type FixtureRunner, type FixtureRunnerContext, type FixtureRunnerOptions, type FixtureTargets, type HarnessArgvIo, type HarnessArgvResult, type HarnessDiagnostic, type HarnessDiagnosticCode, type HarnessDiagnosticError, type HarnessDiagnosticInput, type HarnessDiagnosticSeverity, HarnessError, type HarnessTargetInfo, HarnessTargetNotFoundError, type HarnessTraceMode, type HarnessTraceOptions, type TargetDefinition, type TargetInput, type TargetOutput, createFixtureRunner, defineTarget };

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { InspectRunOptions } from 'agent-inspect';
+
+type HarnessDiagnosticSeverity = "warning" | "error";
+type HarnessDiagnosticCode = "target_not_found" | "bootstrap_failed" | "resolve_failed" | "invoke_failed" | "shutdown_failed" | "cli_usage_error" | "fixture_read_failed" | "stdin_read_failed" | "expected_read_failed" | "expected_output_mismatch";
+interface HarnessDiagnosticError {
+    name?: string;
+    message: string;
+    stack?: string;
+}
+interface HarnessDiagnostic {
+    code: HarnessDiagnosticCode;
+    severity: HarnessDiagnosticSeverity;
+    message: string;
+    targetName?: string;
+    timestamp: number;
+    error?: HarnessDiagnosticError;
+}
+type HarnessDiagnosticInput = Omit<HarnessDiagnostic, "timestamp"> & {
+    timestamp?: number;
+};
+interface FixtureRunnerContext<TApp = unknown> {
+    readonly runnerName: string;
+    readonly targetName: string;
+    readonly app: TApp | undefined;
+    addDiagnostic(diagnostic: HarnessDiagnosticInput): void;
+    getDiagnostics(): readonly HarnessDiagnostic[];
+}
+interface TargetDefinition<TApp, TTarget, TInput, TOutput> {
+    /** Human-readable label for target listing. Experimental during v1.x. */
+    description?: string;
+    /** Safe, bounded metadata for local tooling and recipes. Experimental during v1.x. */
+    metadata?: Record<string, unknown>;
+    /** Resolve a framework-specific object or function from the bootstrapped app. */
+    resolve(app: TApp, context: FixtureRunnerContext<TApp>): TTarget | Promise<TTarget>;
+    /** Invoke the resolved target with fixture input. */
+    invoke(target: TTarget, input: TInput, context: FixtureRunnerContext<TApp>): TOutput | Promise<TOutput>;
+}
+type FixtureTargets<TApp = unknown> = Record<string, TargetDefinition<TApp, unknown, unknown, unknown>>;
+type TargetInput<TDefinition> = TDefinition extends TargetDefinition<infer _TApp, infer _TTarget, infer TInput, infer _TOutput> ? TInput : never;
+type TargetOutput<TDefinition> = TDefinition extends TargetDefinition<infer _TApp, infer _TTarget, infer _TInput, infer TOutput> ? TOutput : never;
+type HarnessTraceMode = "off" | "run" | "run-if-enabled" | "observe";
+interface HarnessTraceOptions extends InspectRunOptions {
+    /**
+     * `run-if-enabled` uses `maybeInspectRun()` and is the default.
+     * `observe` proxies resolved targets and traces `run` / `execute` / `invoke` methods when enabled.
+     */
+    mode?: HarnessTraceMode;
+    runName?: string | ((targetName: string) => string);
+}
+interface FixtureRunnerOptions<TApp, TTargets extends FixtureTargets<TApp>> {
+    name?: string;
+    targets: TTargets;
+    trace?: HarnessTraceOptions;
+    bootstrap?(context: FixtureRunnerContext<TApp>): TApp | Promise<TApp>;
+    shutdown?(app: TApp | undefined, context: FixtureRunnerContext<TApp>): void | Promise<void>;
+}
+interface FixtureRunOptions {
+    trace?: HarnessTraceOptions;
+}
+interface HarnessArgvIo {
+    cwd?: string;
+    stdin?(): string | Promise<string>;
+    stdout?(chunk: string): void;
+    stderr?(chunk: string): void;
+}
+interface HarnessArgvResult {
+    ok: boolean;
+    exitCode: 0 | 1;
+    targetName?: string;
+    listed?: boolean;
+    matchedExpected?: boolean;
+    output?: unknown;
+    error?: HarnessDiagnosticError;
+    diagnostics: readonly HarnessDiagnostic[];
+}
+interface HarnessTargetInfo {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+interface FixtureRunner<TApp, TTargets extends FixtureTargets<TApp>> {
+    listTargets(): HarnessTargetInfo[];
+    getDiagnostics(): readonly HarnessDiagnostic[];
+    runTarget<TName extends Extract<keyof TTargets, string>>(targetName: TName, input: TargetInput<TTargets[TName]>, options?: FixtureRunOptions): Promise<TargetOutput<TTargets[TName]>>;
+    runFromArgv(argv?: readonly string[], io?: HarnessArgvIo): Promise<HarnessArgvResult>;
+}
+declare class HarnessError extends Error {
+    readonly code: HarnessDiagnosticCode;
+    readonly targetName?: string;
+    constructor(code: HarnessDiagnosticCode, message: string, options?: {
+        targetName?: string;
+        cause?: unknown;
+    });
+}
+declare class HarnessTargetNotFoundError extends HarnessError {
+    constructor(targetName: string);
+}
+declare function defineTarget<TApp, TTarget, TInput, TOutput>(definition: TargetDefinition<TApp, TTarget, TInput, TOutput>): TargetDefinition<TApp, TTarget, TInput, TOutput>;
+declare function createFixtureRunner<TApp, const TTargets extends FixtureTargets<TApp>>(options: FixtureRunnerOptions<TApp, TTargets>): FixtureRunner<TApp, TTargets>;
+
+export { type FixtureRunOptions, type FixtureRunner, type FixtureRunnerContext, type FixtureRunnerOptions, type FixtureTargets, type HarnessArgvIo, type HarnessArgvResult, type HarnessDiagnostic, type HarnessDiagnosticCode, type HarnessDiagnosticError, type HarnessDiagnosticInput, type HarnessDiagnosticSeverity, HarnessError, type HarnessTargetInfo, HarnessTargetNotFoundError, type HarnessTraceMode, type HarnessTraceOptions, type TargetDefinition, type TargetInput, type TargetOutput, createFixtureRunner, defineTarget };