@glubean/cli 0.1.2

package/templates/README.md

@@ -0,0 +1,226 @@
+# Glubean API Tests
+
+This project was generated by `glubean init`.
+
+## Project Structure
+
+```
+├── tests/                  # Permanent tests — run in CI, Cloud, and locally
+├── explore/                # Exploratory tests — quick iteration in your editor
+├── data/                   # Shared test data (JSON, CSV, YAML) used by both
+├── context/                # API specs and reference docs for AI and tooling
+├── deno.json               # Config: tasks, SDK import, testDir/exploreDir
+├── .env                    # Default environment variables (BASE_URL, etc.)
+├── .env.secrets            # Default secrets (API keys — gitignored)
+├── .env.staging            # Staging environment variables
+├── .env.staging.secrets    # Staging secrets (gitignored)
+├── CLAUDE.md               # AI instructions (Claude Code, Cursor)
+└── AGENTS.md               # AI instructions (Codex, other agents)
+```
+
+**Required:** `tests/` and `deno.json`. Everything else is recommended.
+
+> **AI instructions:** Both `CLAUDE.md` and `AGENTS.md` are generated with the same content. Keep whichever your AI tool
+> reads — **Claude Code** reads `CLAUDE.md`, **Codex** reads `AGENTS.md`, **Cursor** reads both. Delete the one you
+> don't need.
+
+- **`tests/`** — Your permanent test files (`*.test.ts`). These are what `deno task test` and CI run. All test files
+  must end in `.test.ts`.
+- **`explore/`** — Same `*.test.ts` files, but for interactive exploration. Think of it as a scratchpad: quick API
+  calls, debugging, prototyping. Move files to `tests/` when they're ready to be permanent. Run with
+  `deno task explore`.
+- **`data/`** — Shared test data files (JSON, CSV, YAML). Both `tests/` and `explore/` can import from here. Keeps test
+  logic clean and data reviewable.
+- **`context/`** — API specs (OpenAPI), reference docs, and anything that helps you (or your AI) understand the API
+  under test. Drop your OpenAPI spec here and point your AI at it.
+
+The `data/` and `context/` directories are optional conventions — you can organize data and specs however you prefer.
+These defaults exist because they work well with the CLI tooling and AI workflows.
+
+## Prerequisites
+
+1. Install [Deno](https://deno.land) (v2+):
+
+```bash
+# macOS
+brew install deno
+
+# or see https://docs.deno.com/runtime/getting_started/installation/
+```
+
+2. Install the Glubean CLI:
+
+```bash
+deno install -Ag -n glubean jsr:@glubean/cli
+```
+
+## Quick start
+
+1. Edit `.env` with your API base URL
+2. Edit `.env.secrets` with any API keys
+3. Run tests:
+
+```bash
+deno task test            # run all tests in tests/
+deno task test:verbose    # with detailed output
+deno task test:staging    # run against staging environment
+deno task explore         # run explore/ tests
+```
+
+Or run a specific file:
+
+```bash
+glubean run tests/demo.test.ts --verbose
+```
+
+## Environment switching
+
+The same tests can run against different environments by switching env files. Each env file pairs with a secrets file
+automatically:
+
+| Env file       | Secrets file           | Task shortcut            |
+| -------------- | ---------------------- | ------------------------ |
+| `.env`         | `.env.secrets`         | `deno task test`         |
+| `.env.staging` | `.env.staging.secrets` | `deno task test:staging` |
+
+To add more environments (e.g. production), create `.env.production` and `.env.production.secrets`, then run:
+
+```bash
+glubean run --env-file .env.production
+```
+
+Or add a task in `deno.json`:
+
+```json
+"test:production": "glubean run --env-file .env.production"
+```
+
+All `*.secrets` files are gitignored by default. The non-secret `.env.*` files can be committed safely — they typically
+only contain `BASE_URL` and other non-sensitive config.
+
+## Use your AI to generate tests (from OpenAPI)
+
+This project includes a sample OpenAPI spec at `context/openapi.sample.json`. Most AI coding tools can use this spec to
+generate accurate tests quickly.
+
+Copy/paste prompts you can try (edit as needed):
+
+1. Generate a smoke suite:
+
+> Read `context/openapi.sample.json` and `CLAUDE.md` (or `AGENTS.md`). Generate Glubean tests in `tests/smoke.test.ts`
+> that cover all GET endpoints with 200 responses. Use the builder API with `.step()` for multi-step flows. Use
+> `ctx.http` for requests (auto-traces every call). Add assertions for status code and basic response schema. Group
+> tests by tag.
+
+2. Generate auth + negative tests:
+
+> Using `context/openapi.sample.json`, generate tests in `tests/auth.test.ts` that verify authentication behavior:
+> missing API key returns 401, invalid API key returns 401, insufficient scope returns 403. Use the builder API with
+> `.setup()` for shared auth headers. Use `ctx.secrets.require("API_KEY")` and also test missing/empty API key scenarios
+> safely.
+
+3. Generate CRUD flow tests:
+
+> From `context/openapi.sample.json`, identify resources with create/read/update/delete endpoints. Generate builder API
+> tests in `tests/crud.test.ts` with steps: create → verify → update → verify → delete → verify. Pass state (IDs)
+> between steps.
+
+4. Generate validation tests:
+
+> From `context/openapi.sample.json`, identify POST/PUT endpoints with request bodies. Generate tests in
+> `tests/validation.test.ts` for validation edge cases (missing required fields, invalid enums, min/max constraints).
+> Assert 422 responses and validate the error schema shape.
+
+## Try MCP in Cursor (AI closed loop)
+
+Glubean also ships an MCP (Model Context Protocol) server so your AI tool can **discover tests**, **run them**, read
+**structured failures**, and iterate quickly:
+
+> AI writes tests → runs locally → reads assertions/logs/traces → fixes → reruns → ✓ pass
+
+### Setup
+
+1. Configure the MCP server in Cursor (via UI or `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "glubean": {
+      "command": "deno",
+      "args": ["run", "-A", "jsr:@glubean/mcp"],
+      "description": "Glubean test runner and cloud integration"
+    }
+  }
+}
+```
+
+2. Restart Cursor.
+
+### Prompts to try
+
+- Generate + run + fix (local):
+
+> Use the Glubean MCP tools to discover tests in `tests/`, run them locally, and if any fail, fix the test code and
+> rerun until everything passes. Keep changes minimal and explain each fix.
+
+- Generate tests from spec + run (local):
+
+> Read `context/openapi.sample.json` and generate Glubean tests in `tests/smoke.test.ts`. Then use MCP to run them
+> locally. If validation or auth failures happen, adjust payloads/headers and rerun until green.
+
+### Optional: enable cloud tools
+
+Local MCP tools do not require cloud auth. If you also want the AI to trigger remote runs via the Open Platform, set:
+
+```bash
+export GLUBEAN_TOKEN=gpt_your_project_token
+export GLUBEAN_API_URL=https://api.glubean.com
+```
+
+## What you get from the cloud (and why it matters)
+
+Running locally is great for authoring and debugging. The cloud is where the same verification code becomes a
+**continuous operational workflow** — no rewrites, no extra config files, no separate CI pipeline.
+
+### The problem Glubean Cloud solves
+
+| Without Glubean Cloud                            | With Glubean Cloud                                                      |
+| ------------------------------------------------ | ----------------------------------------------------------------------- |
+| Tests run in CI, pass, and are forgotten         | Tests run on a schedule — every 5 min, hourly, daily                    |
+| Staging tested, production assumed OK            | Same tests, different environments, zero code changes                   |
+| API breaks at 3am, discovered next morning       | Slack/email alert within minutes with exact failure details             |
+| Test results are ephemeral terminal output       | Structured history: assertions, traces, logs — searchable and shareable |
+| Secrets hardcoded or scattered across CI configs | Encrypted environment groups, injected at runtime, never in git         |
+
+### What the cloud provides
+
+- **Automatic bundle builds**: `git push` triggers a build — your test files are packaged into an immutable bundle (like
+  a Docker image for verification).
+- **Environment groups**: configure `staging` and `production` with different `BASE_URL`, API keys, and secrets. Run the
+  same tests against both.
+- **Scheduling**: every N minutes, daily at a specific time, weekly, or cron. Workers pick up runs from a queue —
+  nothing to maintain.
+- **Alerts**: Slack, email, or webhooks. Failures include the exact assertion that broke (`expected 200, got 502`), not
+  a generic "tests failed" message.
+- **Dashboard**: full run history with assertion timelines, API traces, HTTP metrics, and step-level breakdowns.
+- **Open Platform**: project-scoped tokens and webhooks for integrating results into your internal tools and automation.
+
+### Get started with the cloud
+
+1. Create an account at `https://app.glubean.com`
+2. Create a Project and connect your GitHub repository
+3. Push your tests:
+
+```bash
+git add .
+git commit -m "add api tests"
+git push
+```
+
+4. Glubean builds your bundle automatically. Click **Run Now** in the dashboard, or set up a schedule to run
+   continuously.
+
+## Notes
+
+- `.env.secrets` should stay local and must not be committed.
+- Edit test files in `tests/` to match your real API behavior and contracts.

package/templates/claude-skill-glubean-test.md

@@ -0,0 +1,382 @@
+---
+name: gb
+description: Generate Glubean API tests from OpenAPI specs or user instructions. Reads context/, writes tests, runs them via MCP, and fixes failures automatically.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - mcp__glubean__glubean_run_local_file
+  - mcp__glubean__glubean_discover_tests
+  - mcp__glubean__glubean_list_test_files
+  - mcp__glubean__glubean_diagnose_config
+  - mcp__glubean__glubean_get_last_run_summary
+  - mcp__glubean__glubean_get_local_events
+---
+
+# Glubean Test Generator
+
+You are a Glubean test expert. Generate, run, and fix API tests using `@glubean/sdk`.
+
+## Your workflow
+
+1. **Read the API spec** — first check for `context/*-endpoints/_index.md` (pre-split specs). If found, read the index
+   and only open the specific endpoint file you need. If no split endpoints exist, search `context/` for OpenAPI specs
+   (`.json`, `.yaml`). If a spec is larger than 50K, suggest the user run `glubean spec split context/<file>` first. If
+   no spec found, ask the user for endpoint details.
+2. **Read existing tests** — check `tests/` and `explore/` for patterns, configure files, and naming conventions already
+   in use.
+3. **Write tests** — generate test files following the SDK API and conventions below.
+4. **Run tests** — use MCP tool `glubean_run_local_file` to execute. If MCP is unavailable, use `deno task test` via
+   Bash.
+5. **Fix failures** — read the structured failure output, fix the test code, and rerun. Repeat until green.
+
+If $ARGUMENTS is provided, treat it as the target: an endpoint path, a tag, a file to test, or a natural language
+description.
+
+## Project structure
+
+```
+tests/           # Permanent test files (*.test.ts)
+explore/         # Exploratory tests (same format, for iteration)
+data/            # Test data files (JSON, CSV, YAML)
+context/         # OpenAPI specs and reference docs
+.env             # Public variables (BASE_URL)
+.env.secrets     # Credentials — gitignored
+deno.json        # Runtime config, imports, glubean settings
+```
+
+## Import convention
+
+Always use the import map alias from `deno.json`:
+
+```typescript
+import { configure, fromCsv, fromDir, fromYaml, test } from "@glubean/sdk";
+```
+
+Never use `jsr:` URLs directly.
+
+---
+
+## SDK API Reference
+
+### test()
+
+```typescript
+// Quick mode — single function
+export const myTest = test(
+  { id: "kebab-case-id", name: "Human name", tags: ["api"] },
+  async (ctx) => { ... }
+);
+
+// Builder mode — multi-step
+export const myFlow = test("flow-id")
+  .meta({ name: "Flow name", tags: ["api"] })
+  .setup(async (ctx) => { return { token: "..." }; })
+  .step("step-name", async (ctx, state) => { return { ...state, new: "data" }; })
+  .teardown(async (ctx, state) => { /* cleanup, always runs */ });
+
+// Reusable steps with .use() — extract common sequences into plain functions
+const withAuth = (b: TestBuilder<unknown>) => b
+  .step("login", async (ctx) => {
+    const { token } = await ctx.http.post("/login", { json: { ... } }).json<{ token: string }>();
+    return { token };
+  });
+
+export const testA = test("test-a").use(withAuth).step("act", async (ctx, { token }) => { ... });
+export const testB = test("test-b").use(withAuth).step("verify", async (ctx, { token }) => { ... });
+
+// .group(id, fn) — same as .use() but tags steps for visual grouping in reports
+export const checkout = test("checkout")
+  .group("auth", withAuth)
+  .step("pay", async (ctx, { token }) => { ... });
+// Report: checkout → [auth] login → pay
+```
+
+### TestContext (ctx)
+
+```typescript
+ctx.http                              // HTTP client (auto-traces)
+ctx.expect(value)                     // Soft assertion
+ctx.assert(condition, message?)       // Hard assertion
+ctx.log(message, data?)               // Structured log
+ctx.vars.require("KEY")              // Read env var (throws if missing)
+ctx.secrets.require("KEY")           // Read secret (auto-redacted)
+ctx.metric("name", value, { unit? }) // Record metric
+ctx.validate(data, zodSchema)        // Schema validation
+ctx.pollUntil({ timeoutMs }, fn)     // Poll until truthy
+ctx.skip(reason?)                    // Skip test
+```
+
+### HTTP Client
+
+```typescript
+const res = await ctx.http.get(url, options?);
+const data = await ctx.http.post(url, { json: { ... } }).json<T>();
+// Also: .put(), .patch(), .delete()
+// Response: .json<T>(), .text(), .blob()
+```
+
+Options:
+
+```typescript
+{
+  json: { ... },                    // JSON body
+  searchParams: { key: "value" },   // Query params
+  headers: { "X-Custom": "val" },   // Headers
+  timeout: 5000,                    // ms
+  retry: 3,                         // Retry count
+}
+```
+
+Extend with defaults:
+
+```typescript
+const authed = ctx.http.extend({
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+### Assertions — ctx.expect()
+
+```typescript
+expect(x).toBe(y); // Strict equal
+expect(x).toEqual(y); // Deep equal
+expect(x).toBeTruthy();
+expect(x).toBeDefined();
+expect(n).toBeGreaterThan(5);
+expect(s).toContain("sub");
+expect(s).toMatch(/regex/);
+expect(arr).toHaveLength(3);
+expect(obj).toMatchObject({ key: "val" });
+expect(obj).toHaveProperty("path.to.key");
+expect(res).toHaveStatus(200); // HTTP response
+expect(x).not.toBe(y); // Negate
+expect(x).toBe(y).orFail(); // Hard fail (stop test)
+```
+
+### configure() — shared HTTP client
+
+```typescript
+// config/api.ts or tests/configure.ts
+import { configure } from "@glubean/sdk";
+
+export const { http, vars, secrets } = configure({
+  vars: { baseUrl: "BASE_URL" },
+  secrets: { apiKey: "API_KEY" },
+  http: {
+    prefixUrl: "BASE_URL", // Env var name
+    headers: {
+      Authorization: "Bearer {{API_KEY}}", // {{var}} interpolation
+    },
+  },
+});
+```
+
+### Data loading
+
+```typescript
+const rows = await fromDir<T>("./data/users/"); // One JSON file = one row
+const cases = await fromDir.merge<T>("./data/search/"); // Merged for test.pick
+const csv = await fromCsv<T>("./data/file.csv");
+const yaml = await fromYaml<T>("./data/file.yaml");
+```
+
+**Data file formats:**
+
+`fromDir` — each file is one row. File content is a flat object:
+
+```json
+// data/users/alice.json — becomes one row with _name="alice"
+{ "username": "alice", "role": "admin", "expected": 200 }
+```
+
+`fromDir.merge` — each file contains named examples as top-level keys. Keys = pick names, values = scenario objects. All
+files are shallow-merged into one map:
+
+```json
+// data/search/queries.json
+{
+  "by-name":     { "q": "phone", "expected": "phone" },
+  "by-category": { "q": "laptop", "expected": "laptop" }
+}
+// data/search/edge-cases.json
+{
+  "empty-query": { "q": "", "expected": "" }
+}
+// → merged result: { "by-name": {...}, "by-category": {...}, "empty-query": {...} }
+```
+
+Inline examples (no data file needed):
+
+```typescript
+// test.each — array of objects
+test.each([
+  { id: 1, expected: 200 },
+  { id: 999, expected: 404 },
+])("get-user-$id", async (ctx, { id, expected }) => { ... });
+
+// test.pick — object with named keys
+test.pick({
+  "normal":    { name: "Alice", age: 25 },
+  "edge-case": { name: "", age: -1 },
+})("create-user-$_pick", async (ctx, data) => { ... });
+```
+
+### test.each — data-driven
+
+```typescript
+// Quick mode — single function per row
+const users = await fromDir<{ username: string }>("./data/users/");
+export const tests = test.each(users)(
+  "user-lookup-$username",           // $field interpolates
+  async (ctx, { username }) => { ... },
+);
+
+// Builder mode — multi-step per row (omit callback to get builder)
+export const flows = test.each(users)("user-flow-$username")
+  .step("fetch", async (ctx, _state, row) => {
+    const res = await ctx.http.get(`/users/${row.username}`).json<{ id: string }>();
+    return { id: res.id };
+  })
+  .step("verify", async (ctx, state, row) => {
+    ctx.expect(state.id).toBeDefined();
+  });
+```
+
+### test.pick — named examples
+
+```typescript
+// Quick mode — single function
+const cases = await fromDir.merge<{ q: string }>("./data/search/");
+export const tests = test.pick(cases)(
+  "search-$_pick",                   // $_pick = case name
+  async (ctx, { q }) => { ... },
+);
+
+// Builder mode — multi-step per picked example (omit callback to get builder)
+export const flows = test.pick(cases)("search-flow-$_pick")
+  .setup(async (ctx, row) => ({ query: row.q }))
+  .step("search", async (ctx, state, row) => {
+    const res = await ctx.http.get("/search", { searchParams: { q: state.query } }).json<{ total: number }>();
+    return { ...state, total: res.total };
+  })
+  .step("verify", async (ctx, state) => {
+    ctx.expect(state.total).toBeGreaterThan(0);
+  })
+  .teardown(async (ctx, state) => { /* cleanup */ });
+```
+
+Both `test.each` and `test.pick` support the same builder API as `test()`. Omit the callback to enter builder mode;
+chain `.step()`, `.setup()`, `.teardown()`, `.meta()`, etc.
+
+---
+
+## Patterns
+
+### Simple API test
+
+```typescript
+import { test } from "@glubean/sdk";
+import { http } from "./configure.ts";
+
+export const listUsers = test(
+  { id: "list-users", tags: ["api", "smoke"] },
+  async ({ expect }) => {
+    const users = await http.get("users").json<{ users: unknown[] }>();
+    expect(users.users.length).toBeGreaterThan(0);
+  },
+);
+```
+
+### CRUD with cleanup
+
+```typescript
+export const crud = test("resource-crud")
+  .meta({ tags: ["api"] })
+  .setup(async () => {
+    const item = await http.post("items", { json: { name: "test" } }).json<{ id: string }>();
+    return { id: item.id };
+  })
+  .step("read", async ({ expect }, state) => {
+    const item = await http.get(`items/${state.id}`).json<{ name: string }>();
+    expect(item.name).toBe("test");
+    return state;
+  })
+  .step("update", async ({ expect }, state) => {
+    const item = await http.put(`items/${state.id}`, { json: { name: "updated" } }).json<{ name: string }>();
+    expect(item.name).toBe("updated");
+    return state;
+  })
+  .teardown(async (_ctx, state) => {
+    if (state?.id) await http.delete(`items/${state.id}`);
+  });
+```
+
+### Auth flow
+
+```typescript
+export const auth = test("auth-flow")
+  .meta({ tags: ["api", "auth"] })
+  .step("login", async ({ http, expect, secrets }) => {
+    const res = await http.post("https://api.example.com/auth/login", {
+      json: { username: secrets.require("USERNAME"), password: secrets.require("PASSWORD") },
+    }).json<{ token: string }>();
+    expect(res.token).toBeDefined();
+    return { token: res.token };
+  })
+  .step("access protected", async ({ http, expect }, state) => {
+    const authed = http.extend({ headers: { Authorization: `Bearer ${state.token}` } });
+    const profile = await authed.get("https://api.example.com/me").json<{ id: string }>();
+    expect(profile.id).toBeDefined();
+  });
+```
+
+### Error / negative test
+
+```typescript
+export const unauthorized = test(
+  { id: "unauthorized-access", tags: ["api", "auth"] },
+  async ({ http, expect }) => {
+    const res = await http.get("https://api.example.com/protected");
+    expect(res).toHaveStatus(401);
+  },
+);
+```
+
+---
+
+## Rules
+
+- **IDs**: kebab-case, unique across the project
+- **Tags**: always set — `["smoke"]`, `["api"]`, `["e2e"]`, `["auth"]`
+- **Secrets**: use `secrets.require("KEY")` or `{{KEY}}` in configure. Never hardcode.
+- **Cleanup**: any test that creates data MUST have `.teardown()`
+- **Data**: keep test data in `data/`, not inline in test files
+- **Imports**: use `.ts` extensions for local files
+- **One export per behavior**: each `export const` is one test case
+
+## Coverage expectations
+
+For each endpoint, consider:
+
+- Success path (200/201)
+- Auth boundary (401/403) — missing or invalid credentials
+- Validation boundary (400/422) — invalid input
+- Not-found boundary (404) — nonexistent resource
+
+Cover all applicable boundaries unless the user asks for a narrower scope. If the spec lacks detail for a negative case,
+say so explicitly.
+
+## Anti-patterns to avoid
+
+- Hardcoded secrets or base URLs
+- Using raw `fetch()` instead of `ctx.http` or configured client
+- No tags on tests
+- Creating resources without teardown cleanup
+- Guessing endpoint paths — always check the spec first
+- Using `jsr:` URLs instead of `@glubean/sdk` alias
+- Using `any` or `unknown` for HTTP response types — always provide a type parameter: `.json<{ id: string }>()`, not
+  `.json<any>()`. The SDK is fully typed; if you know the shape from the spec, type it.

package/templates/data/create-user.json

@@ -0,0 +1,14 @@
+{
+  "normal": {
+    "body": { "firstName": "Alice", "lastName": "Smith", "age": 28 },
+    "query": { "org": "acme" }
+  },
+  "young": {
+    "body": { "firstName": "Bob", "lastName": "Junior", "age": 18 },
+    "query": { "org": "acme" }
+  },
+  "edge-case": {
+    "body": { "firstName": "", "lastName": "", "age": -1 },
+    "query": { "org": "test" }
+  }
+}

package/templates/data/endpoints.csv

@@ -0,0 +1,5 @@
+method,path,expected
+GET,/products/1,200
+GET,/products/99999,404
+GET,/users/1,200
+GET,/carts/1,200

package/templates/data/scenarios.yaml

@@ -0,0 +1,19 @@
+# Scenarios for data-driven API tests
+# Each entry describes one test case
+- id: get-first-product
+  method: GET
+  path: /products/1
+  expected: 200
+  description: Fetch first product
+
+- id: get-missing-product
+  method: GET
+  path: /products/99999
+  expected: 404
+  description: Non-existent product returns 404
+
+- id: get-product-categories
+  method: GET
+  path: /products/categories
+  expected: 200
+  description: Product categories should be accessible

package/templates/data/search-examples.json

@@ -0,0 +1,14 @@
+{
+  "by-name": {
+    "q": "phone",
+    "expected": { "minResults": 1, "titleContains": "phone" }
+  },
+  "by-category": {
+    "q": "laptop",
+    "expected": { "minResults": 1, "titleContains": "laptop" }
+  },
+  "no-results": {
+    "q": "zzzznotreal",
+    "expected": { "minResults": 0, "titleContains": "" }
+  }
+}

package/templates/data/users.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": 1,
+    "expected": 200,
+    "role": "admin"
+  },
+  {
+    "id": 2,
+    "expected": 200,
+    "role": "user"
+  },
+  {
+    "id": 99999,
+    "expected": 404,
+    "role": "unknown"
+  }
+]