@griffin-app/griffin-plan-executor 0.1.0

package/src/secrets/secrets.test.ts

@@ -0,0 +1,318 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { isSecretRef } from "./types.js";
+import { SecretProviderRegistry } from "./registry.js";
+import { EnvSecretProvider } from "./providers/env.js";
+import {
+  resolveSecretsInPlan,
+  collectSecretsFromPlan,
+  planHasSecrets,
+} from "./resolver.js";
+import { NodeType, ResponseFormat, HttpMethod } from "griffin/schema";
+import { TestPlanV1 } from "griffin/types";
+
+// Helper to create a secret ref (mirrors the DSL's secret function)
+function createSecretRef(path: string) {
+  const colonIndex = path.indexOf(":");
+  const provider = path.slice(0, colonIndex);
+  const ref = path.slice(colonIndex + 1);
+  return { $secret: { provider, ref } };
+}
+
+describe("Secret Types", () => {
+  describe("isSecretRef", () => {
+    it("should return true for valid secret refs", () => {
+      expect(
+        isSecretRef({ $secret: { provider: "env", ref: "API_KEY" } }),
+      ).toBe(true);
+      expect(
+        isSecretRef({
+          $secret: { provider: "aws", ref: "my-secret", version: "1" },
+        }),
+      ).toBe(true);
+    });
+
+    it("should return false for non-secret values", () => {
+      expect(isSecretRef("string")).toBe(false);
+      expect(isSecretRef(123)).toBe(false);
+      expect(isSecretRef(null)).toBe(false);
+      expect(isSecretRef(undefined)).toBe(false);
+      expect(isSecretRef({})).toBe(false);
+      expect(isSecretRef({ secret: { provider: "env", ref: "KEY" } })).toBe(
+        false,
+      ); // wrong key
+    });
+  });
+});
+
+describe("SecretProviderRegistry", () => {
+  let registry: SecretProviderRegistry;
+
+  beforeEach(() => {
+    registry = new SecretProviderRegistry();
+  });
+
+  it("should register and retrieve providers", () => {
+    const envProvider = new EnvSecretProvider();
+    registry.register(envProvider);
+
+    expect(registry.has("env")).toBe(true);
+    expect(registry.get("env")).toBe(envProvider);
+    expect(registry.getProviderNames()).toEqual(["env"]);
+  });
+
+  it("should throw when getting unregistered provider", () => {
+    expect(() => registry.get("unknown")).toThrow(/not configured/);
+  });
+
+  it("should throw when registering duplicate provider", () => {
+    const envProvider = new EnvSecretProvider();
+    registry.register(envProvider);
+    expect(() => registry.register(envProvider)).toThrow(/already registered/);
+  });
+
+  it("should resolve secrets using the correct provider", async () => {
+    const envProvider = new EnvSecretProvider({
+      env: { TEST_SECRET: "secret-value" },
+    });
+    registry.register(envProvider);
+
+    const result = await registry.resolve({
+      provider: "env",
+      ref: "TEST_SECRET",
+    });
+
+    expect(result).toBe("secret-value");
+  });
+});
+
+describe("EnvSecretProvider", () => {
+  it("should resolve environment variables", async () => {
+    const provider = new EnvSecretProvider({
+      env: { MY_API_KEY: "test-key-123" },
+    });
+
+    const result = await provider.resolve("MY_API_KEY");
+    expect(result).toBe("test-key-123");
+  });
+
+  it("should throw for missing environment variables", async () => {
+    const provider = new EnvSecretProvider({ env: {} });
+
+    await expect(provider.resolve("MISSING_VAR")).rejects.toThrow(/not set/);
+  });
+
+  it("should support prefix", async () => {
+    const provider = new EnvSecretProvider({
+      env: { APP_API_KEY: "prefixed-value" },
+      prefix: "APP_",
+    });
+
+    const result = await provider.resolve("API_KEY");
+    expect(result).toBe("prefixed-value");
+  });
+});
+
+describe("Plan Secret Resolution", () => {
+  const createTestPlan = (
+    headers?: Record<string, any>,
+    body?: any,
+  ): TestPlanV1 => ({
+    id: "test-plan-1",
+    name: "Test Plan",
+    version: "1.0",
+    environment: "default",
+    nodes: [
+      {
+        id: "endpoint-1",
+        type: NodeType.ENDPOINT,
+        method: HttpMethod.GET,
+        path: "/api/test",
+        base: { type: "target", key: "api-gateway" },
+        response_format: ResponseFormat.JSON,
+        headers,
+        body,
+      },
+    ],
+    edges: [
+      { from: "__START__", to: "endpoint-1" },
+      { from: "endpoint-1", to: "__END__" },
+    ],
+  });
+
+  describe("planHasSecrets", () => {
+    it("should return false for plans without secrets", () => {
+      const plan = createTestPlan({ "Content-Type": "application/json" });
+      expect(planHasSecrets(plan)).toBe(false);
+    });
+
+    it("should return true for plans with secret refs in headers", () => {
+      const plan = createTestPlan({
+        Authorization: createSecretRef("env:API_KEY"),
+      });
+      expect(planHasSecrets(plan)).toBe(true);
+    });
+
+    it("should return true for plans with secret refs in body", () => {
+      const plan = createTestPlan(undefined, {
+        token: createSecretRef("env:TOKEN"),
+      });
+      expect(planHasSecrets(plan)).toBe(true);
+    });
+  });
+
+  describe("collectSecretsFromPlan", () => {
+    it("should collect secrets from headers", () => {
+      const plan = createTestPlan({
+        Authorization: createSecretRef("env:API_KEY"),
+        "X-Custom": createSecretRef("aws:custom-secret"),
+      });
+
+      const collected = collectSecretsFromPlan(plan);
+
+      expect(collected.refs).toHaveLength(2);
+      expect(collected.refs).toContainEqual({
+        provider: "env",
+        ref: "API_KEY",
+      });
+      expect(collected.refs).toContainEqual({
+        provider: "aws",
+        ref: "custom-secret",
+      });
+    });
+
+    it("should collect secrets from nested body", () => {
+      const plan = createTestPlan(undefined, {
+        auth: {
+          token: createSecretRef("env:TOKEN"),
+        },
+        items: [{ key: createSecretRef("env:ITEM_KEY") }],
+      });
+
+      const collected = collectSecretsFromPlan(plan);
+
+      expect(collected.refs).toHaveLength(2);
+      expect(collected.refs).toContainEqual({ provider: "env", ref: "TOKEN" });
+      expect(collected.refs).toContainEqual({
+        provider: "env",
+        ref: "ITEM_KEY",
+      });
+    });
+
+    it("should deduplicate secret refs", () => {
+      const plan = createTestPlan({
+        Authorization: createSecretRef("env:API_KEY"),
+        "X-Backup-Auth": createSecretRef("env:API_KEY"),
+      });
+
+      const collected = collectSecretsFromPlan(plan);
+
+      expect(collected.refs).toHaveLength(1);
+      expect(collected.paths).toHaveLength(2);
+    });
+  });
+
+  describe("resolveSecretsInPlan", () => {
+    it("should resolve secrets in headers", async () => {
+      const plan = createTestPlan({
+        Authorization: createSecretRef("env:API_KEY"),
+        "Content-Type": "application/json",
+      });
+
+      const registry = new SecretProviderRegistry();
+      registry.register(
+        new EnvSecretProvider({
+          env: { API_KEY: "Bearer secret-token" },
+        }),
+      );
+
+      const resolved = await resolveSecretsInPlan(plan, registry);
+
+      const endpoint = resolved.nodes[0];
+      if (endpoint.type !== NodeType.ENDPOINT) {
+        throw new Error("Endpoint not found");
+      }
+      expect(endpoint.headers?.Authorization).toBe("Bearer secret-token");
+      expect(endpoint.headers?.["Content-Type"]).toBe("application/json");
+    });
+
+    it("should resolve secrets in body", async () => {
+      const plan = createTestPlan(undefined, {
+        token: createSecretRef("env:TOKEN"),
+        data: "plain-value",
+      });
+
+      const registry = new SecretProviderRegistry();
+      registry.register(
+        new EnvSecretProvider({
+          env: { TOKEN: "resolved-token" },
+        }),
+      );
+
+      const resolved = await resolveSecretsInPlan(plan, registry);
+
+      const endpoint = resolved.nodes[0];
+      if (endpoint.type !== NodeType.ENDPOINT) {
+        throw new Error("Endpoint not found");
+      }
+      expect(endpoint.body.token).toBe("resolved-token");
+      expect(endpoint.body.data).toBe("plain-value");
+    });
+
+    it("should not modify original plan", async () => {
+      const plan = createTestPlan({
+        Authorization: createSecretRef("env:API_KEY"),
+      });
+
+      const registry = new SecretProviderRegistry();
+      registry.register(
+        new EnvSecretProvider({
+          env: { API_KEY: "secret" },
+        }),
+      );
+
+      const resolved = await resolveSecretsInPlan(plan, registry);
+
+      // Original should still have secret ref
+      const originalEndpoint = plan.nodes[0];
+      if (originalEndpoint.type !== NodeType.ENDPOINT) {
+        throw new Error("Endpoint not found");
+      }
+      expect(originalEndpoint.headers?.Authorization).toEqual(
+        createSecretRef("env:API_KEY"),
+      );
+
+      // Resolved should have string
+      const resolvedEndpoint = resolved.nodes[0];
+      if (resolvedEndpoint.type !== NodeType.ENDPOINT) {
+        throw new Error("Endpoint not found");
+      }
+      expect(resolvedEndpoint.headers?.Authorization).toBe("secret");
+    });
+
+    it("should throw for unregistered provider", async () => {
+      const plan = createTestPlan({
+        Authorization: createSecretRef("unknown:API_KEY"),
+      });
+
+      const registry = new SecretProviderRegistry();
+      registry.register(new EnvSecretProvider({ env: {} }));
+
+      await expect(resolveSecretsInPlan(plan, registry)).rejects.toThrow(
+        /not configured/,
+      );
+    });
+
+    it("should throw for missing secret", async () => {
+      const plan = createTestPlan({
+        Authorization: createSecretRef("env:MISSING_KEY"),
+      });
+
+      const registry = new SecretProviderRegistry();
+      registry.register(new EnvSecretProvider({ env: {} }));
+
+      await expect(resolveSecretsInPlan(plan, registry)).rejects.toThrow(
+        /not set/,
+      );
+    });
+  });
+});

package/src/secrets/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Secret provider types for griffin plan executor.
+ */
+
+/**
+ * Data structure for a secret reference as it appears in a plan.
+ */
+export interface SecretRefData {
+  provider: string;
+  ref: string;
+  version?: string;
+  field?: string;
+}
+
+/**
+ * Secret reference marker in plan JSON.
+ */
+export interface SecretRef {
+  $secret: SecretRefData;
+}
+
+/**
+ * Options passed to secret resolution.
+ */
+export interface SecretResolveOptions {
+  version?: string;
+  field?: string;
+}
+
+/**
+ * Interface that all secret providers must implement.
+ */
+export interface SecretProvider {
+  /** Unique name of the provider (e.g., "env", "aws", "vault") */
+  readonly name: string;
+
+  /**
+   * Resolve a single secret reference.
+   * @param ref - The secret path/identifier within this provider
+   * @param options - Optional version or field extraction
+   * @returns The resolved secret value
+   * @throws Error if secret cannot be resolved
+   */
+  resolve(ref: string, options?: SecretResolveOptions): Promise<string>;
+
+  /**
+   * Optional batch resolution for efficiency.
+   * Default implementation calls resolve() for each ref.
+   */
+  resolveMany?(
+    refs: Array<{ ref: string; options?: SecretResolveOptions }>,
+  ): Promise<Map<string, string>>;
+
+  /**
+   * Optional validation/health check.
+   * Called during provider initialization.
+   */
+  validate?(): Promise<void>;
+}
+
+/**
+ * Error thrown when secret resolution fails.
+ */
+export class SecretResolutionError extends Error {
+  public readonly provider: string;
+  public readonly ref: string;
+  public readonly cause?: Error;
+
+  constructor(
+    message: string,
+    details: { provider: string; ref: string; cause?: unknown },
+  ) {
+    super(message);
+    this.name = "SecretResolutionError";
+    this.provider = details.provider;
+    this.ref = details.ref;
+    if (details.cause instanceof Error) {
+      this.cause = details.cause;
+    }
+  }
+}
+
+/**
+ * Type guard to check if a value is a secret reference.
+ */
+export function isSecretRef(value: unknown): value is SecretRef {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+  if (
+    !("$secret" in obj) ||
+    typeof obj.$secret !== "object" ||
+    obj.$secret === null
+  ) {
+    return false;
+  }
+
+  const secretData = obj.$secret as Record<string, unknown>;
+  return (
+    typeof secretData.provider === "string" &&
+    typeof secretData.ref === "string"
+  );
+}

package/src/shared.ts

@@ -0,0 +1,46 @@
+import {
+  TSchema,
+  TSchemaOptions,
+  TUnsafe,
+  Static,
+  Unsafe,
+  Type,
+} from "typebox";
+import { Value } from "typebox/value";
+import { Memory } from "typebox/system";
+
+export function Ref<T extends TSchema>(
+  t: T,
+  options: TSchemaOptions = {},
+): TUnsafe<Static<T>> {
+  const id = (t as unknown as Record<string, string | undefined>).$id;
+  if (!id) {
+    throw new Error("missing ID on schema");
+  }
+  return Unsafe<Static<T>>({ ...t, $ref: id, $id: undefined, ...options });
+}
+
+export class TUnionOneOf<Types extends TSchema[] = TSchema[]> extends Type.Base<
+  TSchema[]
+> {
+  public oneOf: Types;
+  constructor(oneOf: Types) {
+    super();
+    this.oneOf = oneOf;
+  }
+}
+export function UnionOneOf(oneOf: TSchema[]): TUnionOneOf {
+  return new TUnionOneOf(oneOf);
+}
+
+//export interface TUnionOneOf<Types extends TSchema[] = TSchema[]> extends TSchema {
+//  '~kind': 'UnionOneOf'
+//  //static: { [K in keyof Types]: Static<Types[K]> }[number]
+//  oneOf: Types
+//}
+//
+//export function UnionOneOf<Types extends TSchema[]>(oneOf: [...Types], options: TSchemaOptions = {}) {
+//  return { ...options, ["~kind"]: 'UnionOneOf', oneOf } as TUnionOneOf<Types>
+//
+//  ///return Memory.Create({ '~kind': 'UnionOneOf' }, { oneOf }, options) as never
+//}

package/src/test-plan-types.ts

@@ -0,0 +1,49 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+export type ResponseFormat = "JSON" | "XML" | "TEXT";
+
+export interface Endpoint {
+  id: string;
+  type: "endpoint";
+  method: HttpMethod;
+  path: string;
+  response_format: ResponseFormat;
+  headers?: Record<string, string>;
+  body?: any;
+}
+
+export interface WaitNode {
+  id: string;
+  type: "wait";
+  duration_ms: number;
+}
+
+export interface AssertionNode {
+  id: string;
+  type: "assertion";
+  assertions: Assertion[];
+}
+
+export interface Assertion {
+  type: string;
+  expected?: any;
+  actual?: any;
+  message?: string;
+}
+
+export interface Edge {
+  from: string;
+  to: string;
+}
+
+export interface Frequency {
+  every: number;
+  unit: "minute" | "hour" | "day";
+}
+
+export interface TestPlan {
+  name: string;
+  endpoint_host: string;
+  frequency?: Frequency;
+  nodes: (Endpoint | WaitNode | AssertionNode)[];
+  edges: Edge[];
+}

package/src/types.ts

@@ -0,0 +1,95 @@
+import type { ExecutionEventEmitter } from "./events/index.js";
+import type { SecretProviderRegistry } from "./secrets/index.js";
+
+export const START = "__START__" as const;
+export const END = "__END__" as const;
+
+export type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | { [key: string]: JSONValue }
+  | JSONValue[];
+
+/**
+ * Complete response data from an endpoint execution
+ */
+export interface NodeResponseData {
+  body: JSONValue;
+  headers: Record<string, string>;
+  status: number;
+}
+
+export interface HttpRequest {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  timeout?: number;
+}
+
+export interface HttpResponse {
+  status: number;
+  statusText: string;
+  data: unknown;
+  headers?: Record<string, string>;
+}
+
+export interface HttpClientAdapter {
+  request(req: HttpRequest): Promise<HttpResponse>;
+}
+
+export interface ExecutionOptions {
+  mode: "local" | "remote";
+  timeout?: number;
+  httpClient: HttpClientAdapter;
+
+  /** Optional event emitter for execution observability */
+  eventEmitter?: ExecutionEventEmitter;
+
+  /** Unique execution ID for correlating events (generated if not provided) */
+  executionId?: string;
+
+  /**
+   * Optional secret provider registry for resolving secret references.
+   * If provided, secrets in the plan will be resolved before execution.
+   * If not provided, any secret references in the plan will cause an error.
+   */
+  secretRegistry?: SecretProviderRegistry;
+
+  /**
+   * Target resolver for mapping target keys to base URLs.
+   * Required when plan contains target references.
+   */
+  targetResolver: (key: string) => Promise<string | undefined>;
+}
+
+export interface NodeResult {
+  nodeId: string;
+  success: boolean;
+  response?: JSONValue;
+  error?: string;
+  duration_ms: number;
+}
+
+export interface ExecutionResult {
+  success: boolean;
+  results: NodeResult[];
+  errors: string[];
+  totalDuration_ms: number;
+}
+
+export interface EndpointResult {
+  success: boolean;
+  response?: JSONValue;
+  headers?: Record<string, string>;
+  status?: number;
+  error?: string;
+  duration_ms: number;
+}
+
+export interface WaitResult {
+  success: boolean;
+  duration_ms: number;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.{test,spec}.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      exclude: ["node_modules/", "dist/", "**/*.d.ts", "**/*.config.*"],
+    },
+  },
+});