@griffin-app/griffin-ts 0.1.0

package/ASSERTIONS_QUICK_REF.md

@@ -0,0 +1,161 @@
+# Assertion DSL Quick Reference
+
+## Basic Structure
+
+```typescript
+.assert((state) => [
+  Assert(state["node_name"].accessor["path"]).predicate(),
+])
+```
+
+## Accessors
+
+| Accessor   | Description          | Example                                 |
+| ---------- | -------------------- | --------------------------------------- |
+| `.body`    | Response body (JSON) | `state["node"].body["data"]["id"]`      |
+| `.headers` | Response headers     | `state["node"].headers["content-type"]` |
+| `.status`  | HTTP status code     | `state["node"].status`                  |
+
+## Array Access
+
+```typescript
+state["node"].body["items"].at(0)["name"]; // First item
+state["node"].body["matrix"].at(2).at(3); // 2D array
+```
+
+## Unary Predicates
+
+| Predicate      | Description                  | Negation                         |
+| -------------- | ---------------------------- | -------------------------------- |
+| `.isNull()`    | Value is null                | `.not.isNull()` / `.isDefined()` |
+| `.isDefined()` | Value is not null            | `.not.isDefined()` / `.isNull()` |
+| `.isTrue()`    | Value is true                | `.not.isTrue()`                  |
+| `.isFalse()`   | Value is false               | `.not.isFalse()`                 |
+| `.isEmpty()`   | String/array/object is empty | `.not.isEmpty()`                 |
+
+## Binary Predicates - Equality
+
+| Predicate        | Description           | Example                               |
+| ---------------- | --------------------- | ------------------------------------- |
+| `.equals(x)`     | Value equals x        | `Assert(status).equals(200)`          |
+| `.not.equals(x)` | Value doesn't equal x | `Assert(error).not.equals("timeout")` |
+
+## Binary Predicates - Comparison
+
+| Predicate                | Description | Example                              |
+| ------------------------ | ----------- | ------------------------------------ |
+| `.greaterThan(x)`        | Value > x   | `Assert(count).greaterThan(0)`       |
+| `.greaterThanOrEqual(x)` | Value >= x  | `Assert(age).greaterThanOrEqual(18)` |
+| `.lessThan(x)`           | Value < x   | `Assert(time_ms).lessThan(500)`      |
+| `.lessThanOrEqual(x)`    | Value <= x  | `Assert(score).lessThanOrEqual(100)` |
+
+Negations reverse the operator:
+
+- `.not.greaterThan(100)` → value <= 100
+- `.not.lessThan(0)` → value >= 0
+
+## Binary Predicates - Strings
+
+| Predicate            | Description                 | Example                                  |
+| -------------------- | --------------------------- | ---------------------------------------- |
+| `.contains(x)`       | String contains x           | `Assert(type).contains("json")`          |
+| `.not.contains(x)`   | String doesn't contain x    | `Assert(url).not.contains("staging")`    |
+| `.startsWith(x)`     | String starts with x        | `Assert(path).startsWith("/api/")`       |
+| `.not.startsWith(x)` | String doesn't start with x | `Assert(version).not.startsWith("v1.")`  |
+| `.endsWith(x)`       | String ends with x          | `Assert(email).endsWith("@example.com")` |
+| `.not.endsWith(x)`   | String doesn't end with x   | `Assert(file).not.endsWith(".tmp")`      |
+
+## Common Patterns
+
+### Status Checks
+
+```typescript
+Assert(state["node"].status).equals(200);
+Assert(state["node"].status).lessThan(400); // Any success
+Assert(state["node"].status).not.equals(500); // Not server error
+```
+
+### Existence Checks
+
+```typescript
+Assert(state["node"].body["id"]).not.isNull();
+Assert(state["node"].body["data"]).isDefined();
+Assert(state["node"].body["items"]).not.isEmpty();
+```
+
+### Value Validation
+
+```typescript
+Assert(state["node"].body["email"]).equals("test@example.com");
+Assert(state["node"].body["age"]).greaterThanOrEqual(18);
+Assert(state["node"].body["score"]).lessThan(100);
+```
+
+### String Matching
+
+```typescript
+Assert(state["node"].headers["content-type"]).contains("application/json");
+Assert(state["node"].body["version"]).startsWith("v2.");
+Assert(state["node"].body["email"]).endsWith("@example.com");
+```
+
+### Boolean Checks
+
+```typescript
+Assert(state["node"].body["active"]).isTrue();
+Assert(state["node"].body["deleted"]).isFalse();
+Assert(state["node"].body["verified"]).not.isFalse();
+```
+
+### Array Elements
+
+```typescript
+Assert(state["node"].body["items"].at(0)["name"]).equals("First");
+Assert(state["node"].body["users"].at(2)["active"]).isTrue();
+```
+
+## Multi-Node Example
+
+```typescript
+createTestBuilder({ name: "user-flow" })
+  .request("create", { method: POST /* ... */ })
+  .request("verify", { method: GET /* ... */ })
+  .assert((state) => [
+    // Check create response
+    Assert(state["create"].status).equals(201),
+    Assert(state["create"].body["id"]).not.isNull(),
+
+    // Check verify response
+    Assert(state["verify"].status).equals(200),
+    Assert(state["verify"].body["email"]).equals("test@example.com"),
+  ]);
+```
+
+## Type Safety
+
+TypeScript provides autocomplete and errors:
+
+```typescript
+.request("user_create", { /* ... */ })
+.assert((state) => [
+  state["user_create"]  // ✓ Autocomplete shows this node
+  state["typo"]         // ❌ TypeScript error
+
+  state["user_create"].body     // ✓ Valid accessor
+  state["user_create"].invalid  // ❌ TypeScript error
+])
+```
+
+## Cheat Sheet
+
+| Task              | Code                                                     |
+| ----------------- | -------------------------------------------------------- |
+| Status is 200     | `Assert(state["n"].status).equals(200)`                  |
+| Body field exists | `Assert(state["n"].body["x"]).not.isNull()`              |
+| String contains   | `Assert(state["n"].body["msg"]).contains("ok")`          |
+| Number in range   | `Assert(state["n"].body["age"]).greaterThanOrEqual(18)`  |
+| Boolean true      | `Assert(state["n"].body["active"]).isTrue()`             |
+| Header has value  | `Assert(state["n"].headers["x-id"]).not.isEmpty()`       |
+| Array not empty   | `Assert(state["n"].body["items"]).not.isEmpty()`         |
+| First array item  | `Assert(state["n"].body["items"].at(0)["name"])...`      |
+| Nested object     | `Assert(state["n"].body["user"]["profile"]["email"])...` |

package/README.md

@@ -0,0 +1,297 @@
+# griffin Test System
+
+The griffin Test System provides a TypeScript DSL for defining API tests. Tests are written in TypeScript and output JSON test plans that can be executed by the plan executor.
+
+## Features
+
+- TypeScript DSL for defining API checks
+- Chainable API for building test plans
+- Support for endpoints, waits, assertions, and edges
+- Outputs JSON test plans for execution
+
+## Installation
+
+```bash
+npm install griffin
+```
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+Create test files in `__griffin__` directories. When executed, they output JSON test plans.
+
+griffin provides two builder APIs:
+
+- **`createTestBuilder`**: Simple sequential tests (recommended for most use cases)
+- **`createGraphBuilder`**: Complex graphs with parallel execution and branching
+
+### Sequential Builder (Recommended for Simple Tests)
+
+The sequential builder automatically connects steps in order - no need to manage edges manually.
+
+```typescript
+import { GET, createTestBuilder, JSON, Frequency } from "griffin-ts";
+
+const plan = createTestBuilder({
+  name: "health-check",
+  frequency: Frequency.every(1).minute(),
+})
+  .request({
+    method: GET,
+    response_format: JSON,
+    path: "/health",
+  })
+  .assert([
+    { type: "status", expected: 200 },
+    { type: "body", expected: { status: "ok" } },
+  ])
+  .build();
+
+export default plan;
+```
+
+#### Sequential Example with Waits
+
+```typescript
+import {
+  GET,
+  POST,
+  createTestBuilder,
+  JSON,
+  Frequency,
+  Wait,
+} from "griffin-ts";
+
+const plan = createTestBuilder({
+  name: "create-and-verify-user",
+  frequency: Frequency.every(5).minute(),
+})
+  .request({
+    method: POST,
+    response_format: JSON,
+    path: "/api/v1/users",
+    body: { name: "Test User", email: "test@example.com" },
+  })
+  .assert([{ type: "status", expected: 201 }])
+  .wait(Wait.seconds(2))
+  .request({
+    method: GET,
+    response_format: JSON,
+    path: "/api/v1/users/test@example.com",
+  })
+  .assert([
+    { type: "status", expected: 200 },
+    { type: "body.name", expected: "Test User" },
+  ])
+  .build();
+
+export default plan;
+```
+
+### Graph Builder (For Complex Workflows)
+
+The graph builder gives you full control over the test graph, enabling parallel execution and complex branching.
+
+```typescript
+import {
+  GET,
+  POST,
+  createGraphBuilder,
+  Endpoint,
+  Assertion,
+  WaitNode,
+  JSON,
+  START,
+  END,
+  Frequency,
+  Wait,
+} from "griffin-ts";
+
+const plan = createGraphBuilder({
+  name: "foo-bar-check",
+  frequency: Frequency.every(1).minute(),
+})
+  .addNode(
+    "create_foo",
+    Endpoint({
+      method: POST,
+      response_format: JSON,
+      path: "/api/v1/foo",
+      body: { name: "test", value: 42 },
+    }),
+  )
+  .addNode(
+    "get_foo",
+    Endpoint({
+      method: GET,
+      response_format: JSON,
+      path: "/api/v1/foo/1",
+    }),
+  )
+  .addNode("wait_between", WaitNode(Wait.seconds(2)))
+  .addNode("check_status", Assertion([{ type: "status", expected: 200 }]))
+  .addEdge(START, "create_foo")
+  .addEdge("create_foo", "wait_between")
+  .addEdge("wait_between", "get_foo")
+  .addEdge("get_foo", "check_status")
+  .addEdge("check_status", END)
+  .build();
+
+export default plan;
+```
+
+### Using Secrets
+
+griffin supports secure secret management for API keys, tokens, and other credentials. Secrets are referenced in your test plans and resolved at runtime by the configured secret providers.
+
+#### With Sequential Builder
+
+```typescript
+import { GET, createTestBuilder, JSON, Frequency, secret } from "griffin-ts";
+
+const plan = createTestBuilder({
+  name: "authenticated-check",
+  frequency: Frequency.every(5).minute(),
+})
+  .request({
+    method: GET,
+    response_format: JSON,
+    path: "/api/protected",
+    headers: {
+      // Use environment variable
+      "X-API-Key": secret("env:API_KEY"),
+      // Use AWS Secrets Manager
+      Authorization: secret("aws:prod/api-token"),
+      // Extract field from JSON secret
+      "X-Custom-Header": secret("aws:prod/config", { field: "customHeader" }),
+    },
+    body: {
+      // Secrets can also be used in request bodies
+      apiKey: secret("env:API_KEY"),
+    },
+  })
+  .assert([{ type: "status", expected: 200 }])
+  .build();
+
+export default plan;
+```
+
+#### With Graph Builder
+
+```typescript
+import {
+  GET,
+  createGraphBuilder,
+  Endpoint,
+  Assertion,
+  JSON,
+  START,
+  END,
+  Frequency,
+  secret,
+} from "griffin-ts";
+
+const plan = createGraphBuilder({
+  name: "authenticated-check",
+  frequency: Frequency.every(5).minute(),
+})
+  .addNode(
+    "authenticated_request",
+    Endpoint({
+      method: GET,
+      response_format: JSON,
+      path: "/api/protected",
+      headers: {
+        "X-API-Key": secret("env:API_KEY"),
+        Authorization: secret("aws:prod/api-token"),
+      },
+    }),
+  )
+  .addNode("verify", Assertion([{ type: "status", expected: 200 }]))
+  .addEdge(START, "authenticated_request")
+  .addEdge("authenticated_request", "verify")
+  .addEdge("verify", END)
+  .build();
+
+export default plan;
+```
+
+#### Secret Providers
+
+**Environment Variables** (always available):
+
+```typescript
+secret("env:VARIABLE_NAME");
+```
+
+**AWS Secrets Manager** (requires AWS configuration):
+
+```typescript
+secret("aws:secret-name");
+secret("aws:secret-name", { field: "key" }); // Extract field from JSON secret
+secret("aws:secret-name", { version: "AWSPREVIOUS" }); // Pin to specific version
+```
+
+**HashiCorp Vault** (requires Vault configuration):
+
+```typescript
+secret("vault:secret/data/path");
+secret("vault:secret/data/path", { field: "key" });
+secret("vault:secret/data/path", { version: "2" });
+```
+
+See the [griffin-runner CONFIG.md](../griffin-runner/CONFIG.md) for configuration details.
+
+### API Reference
+
+#### Sequential Builder Methods
+
+- **`.request(config)`**: Add an HTTP endpoint request
+- **`.wait(duration)`**: Add a delay (use `Wait.seconds(n)` or `Wait.minutes(n)`)
+- **`.assert(assertions)`**: Add assertions to validate responses
+- **`.build()`**: Generate the final test plan
+
+#### Graph Builder Methods
+
+- **`.addNode(name, node)`**: Add a node to the graph using `Endpoint()`, `WaitNode()`, or `Assertion()`
+- **`.addEdge(from, to)`**: Connect two nodes (use `START` and `END` constants for entry/exit)
+- **`.build()`**: Generate the final test plan (validates all nodes are connected)
+
+#### General
+
+- **Frequency**: Use `Frequency.every(n).minute()`, `.hour()`, or `.day()` (note the parentheses)
+- **Secrets**: Use `secret("provider:path")` to reference secrets that are resolved at runtime
+- **Assertions**: Currently in development - assertion functions are stored but not yet evaluated during execution
+
+## Output
+
+The test system outputs a JSON test plan to stdout when `plan.create()` is called. This JSON is consumed by the plan executor. Example output:
+
+```json
+{
+  "name": "health-check",
+  "frequency": {
+    "every": 1,
+    "unit": "minute"
+  },
+  "nodes": [
+    {
+      "id": "health",
+      "type": "endpoint",
+      "method": "GET",
+      "path": "/health",
+      "response_format": "JSON"
+    }
+  ],
+  "edges": [
+    { "from": "__START__", "to": "health" },
+    { "from": "health", "to": "__END__" }
+  ]
+}
+```

package/dist/assertions.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Rich assertion DSL for constructing type-safe test assertions with JSONPath support.
+ *
+ * This module provides:
+ * - StateProxy: Tracks node access patterns and converts them to JSONPath
+ * - Assert: Builder for creating assertions with fluent API
+ * - Support for unary and binary predicates with negation
+ */
+/**
+ * Identifies which node and which part of its result we're asserting on
+ */
+export interface PathDescriptor {
+    nodeId: string;
+    accessor: "body" | "headers" | "status";
+    path: string[];
+}
+/**
+ * Unary predicates that check a property without comparing to a value
+ */
+export declare enum UnaryPredicate {
+    IS_NULL = "IS_NULL",
+    IS_NOT_NULL = "IS_NOT_NULL",
+    IS_TRUE = "IS_TRUE",
+    IS_FALSE = "IS_FALSE",
+    IS_EMPTY = "IS_EMPTY",
+    IS_NOT_EMPTY = "IS_NOT_EMPTY"
+}
+/**
+ * Binary predicate operators that compare against an expected value
+ */
+export declare enum BinaryPredicateOperator {
+    EQUAL = "EQUAL",
+    NOT_EQUAL = "NOT_EQUAL",
+    GREATER_THAN = "GREATER_THAN",
+    LESS_THAN = "LESS_THAN",
+    GREATER_THAN_OR_EQUAL = "GREATER_THAN_OR_EQUAL",
+    LESS_THAN_OR_EQUAL = "LESS_THAN_OR_EQUAL",
+    CONTAINS = "CONTAINS",
+    NOT_CONTAINS = "NOT_CONTAINS",
+    STARTS_WITH = "STARTS_WITH",
+    NOT_STARTS_WITH = "NOT_STARTS_WITH",
+    ENDS_WITH = "ENDS_WITH",
+    NOT_ENDS_WITH = "NOT_ENDS_WITH"
+}
+/**
+ * Binary predicate with operator and expected value
+ */
+export interface BinaryPredicate {
+    operator: BinaryPredicateOperator;
+    expected: unknown;
+}
+/**
+ * Serialized assertion ready for execution
+ */
+export interface SerializedAssertion {
+    nodeId: string;
+    accessor: "body" | "headers" | "status";
+    path: string[];
+    predicate: UnaryPredicate | BinaryPredicate;
+}
+/**
+ * Symbol used to store path metadata in proxy objects
+ */
+declare const PATH_SYMBOL: unique symbol;
+/**
+ * Internal interface for proxy objects that carry path information
+ */
+interface ProxyWithPath {
+    [PATH_SYMBOL]: PathDescriptor;
+}
+/**
+ * Proxy for accessing nested properties within a node result accessor (body, headers, status)
+ * Note: The 'at' method is available at runtime but typed as NestedProxy for simplicity
+ */
+export type NestedProxy = ProxyWithPath & {
+    [key: string]: NestedProxy;
+};
+/**
+ * Proxy for a node result with body, headers, and status accessors
+ */
+export type NodeResultProxy = {
+    body: NestedProxy;
+    headers: NestedProxy;
+    status: NestedProxy;
+};
+/**
+ * State proxy that maps node names to their result proxies
+ */
+export type StateProxy<NodeNames extends string = string> = {
+    [K in NodeNames]: NodeResultProxy;
+};
+/**
+ * Creates a state proxy for the given node names
+ */
+export declare function createStateProxy<NodeNames extends string>(nodeNames: NodeNames[]): StateProxy<NodeNames>;
+export declare class AssertBuilder {
+    private descriptor;
+    private negated;
+    constructor(descriptor: PathDescriptor);
+    /**
+     * Negation modifier - flips the meaning of the subsequent predicate
+     *
+     * @example
+     * Assert(state["node"].body["id"]).not.isNull()  // IS_NOT_NULL
+     * Assert(state["node"].body["name"]).not.equals("") // NOT_EQUAL
+     */
+    get not(): this;
+    isNull(): SerializedAssertion;
+    isDefined(): SerializedAssertion;
+    isTrue(): SerializedAssertion;
+    isFalse(): SerializedAssertion;
+    isEmpty(): SerializedAssertion;
+    equals(expected: unknown): SerializedAssertion;
+    greaterThan(expected: number): SerializedAssertion;
+    lessThan(expected: number): SerializedAssertion;
+    greaterThanOrEqual(expected: number): SerializedAssertion;
+    lessThanOrEqual(expected: number): SerializedAssertion;
+    contains(expected: string): SerializedAssertion;
+    startsWith(expected: string): SerializedAssertion;
+    endsWith(expected: string): SerializedAssertion;
+    private createAssertion;
+}
+/**
+ * Creates an assertion builder from a state proxy reference
+ *
+ * @param proxyRef - A reference obtained from the state proxy (e.g., state["node"].body["id"])
+ * @returns An AssertBuilder for constructing the assertion
+ *
+ * @example
+ * Assert(state["create_user"].body["data"]["id"]).not.isNull()
+ * Assert(state["create_user"].status).equals(201)
+ * Assert(state["create_user"].headers["content-type"]).contains("application/json")
+ */
+export declare function Assert(proxyRef: NestedProxy): AssertBuilder;
+export {};
+//# sourceMappingURL=assertions.d.ts.map

package/dist/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"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"}