@glubean/grpc 0.1.4 → 0.2.2

package/README.md

@@ -1,6 +1,11 @@
 # @glubean/grpc
 
-gRPC plugin for [Glubean](https://glubean.dev) — workflow-level gRPC testing with built-in tracing.
+gRPC for [Glubean](https://glubean.dev). This package owns two layers:
+
+- **Contract** — author gRPC API intent as a single artifact (`contract.grpc.with(...)`). Executable spec, agent-readable, fits `contract.flow()` composition. **Recommended for new work.**
+- **Transport plugin** — low-level gRPC client with auto-tracing, used via `configure({ plugins: { ... } })`. Still supported for test-after / exploratory work.
+
+> **v0.2.0 single-package release note:** in earlier drafts, gRPC contract was planned as a separate `@glubean/contract-grpc` package. Decision 2026-04-20: one package per protocol. Importing `@glubean/grpc` now registers the contract adapter as a side effect. No new install, no second package.
 
 ## Install
 
@@ -8,9 +13,102 @@ gRPC plugin for [Glubean](https://glubean.dev) — workflow-level gRPC testing w
 npm install @glubean/grpc @grpc/grpc-js @grpc/proto-loader
 ```
 
-`@grpc/grpc-js` and `@grpc/proto-loader` are peer dependencies — you install them alongside the plugin.
+`@grpc/grpc-js` and `@grpc/proto-loader` are peer dependencies.
+
+---
+
+## Quick Start — Contract
+
+```ts
+import { contract, configure } from "@glubean/sdk";
+import { grpc } from "@glubean/grpc";
+// ^ importing @glubean/grpc registers contract.grpc side-effect
+
+const { payment } = configure({
+  plugins: {
+    payment: grpc({
+      proto: "./protos/payment.proto",
+      address: "{{PAYMENT_SERVICE_ADDR}}",
+      package: "acme.payment.v1",
+      service: "PaymentService",
+    }),
+  },
+});
+
+const paymentContracts = contract.grpc.with("payment-api", {
+  client: payment,
+});
+
+export const completePayment = paymentContracts("complete-payment", {
+  target: "PaymentService/Complete",
+  description: "Complete a pending payment by order id + amount",
+  cases: {
+    happy: {
+      description: "order with valid payment method completes successfully",
+      request: { currency: "USD" },
+      expect: {
+        statusCode: 0, // OK
+        message: { status: "completed" },
+      },
+    },
+    notFound: {
+      description: "unknown order id returns NOT_FOUND",
+      request: { orderId: "does-not-exist" },
+      expect: {
+        statusCode: 5, // NOT_FOUND
+      },
+    },
+  },
+});
+```
+
+Run with `glubean run`. Each case becomes a first-class test; failure surfaces structured gRPC status on the trace.
+
+### Cases in a flow
+
+Contract cases compose into `contract.flow()` steps — the same artifact serves both single-case and multi-step verification:
+
+```ts
+import { contract } from "@glubean/sdk";
+import { completePayment } from "./payment.contract.ts";
+import { createOrder, getOrder } from "./orders.contract.ts"; // HTTP
+
+export const checkoutFlow = contract
+  .flow("checkout")
+  .meta({
+    description: "Create order → complete payment → confirm",
+    tags: ["e2e"],
+  })
+  // Step 1: HTTP — create order
+  .step(createOrder.case("happy"), {
+    out: (_s, res: any) => ({ orderId: res.body.id, amount: res.body.total }),
+  })
+  // Step 2: gRPC — complete payment
+  .step(completePayment.case("happy"), {
+    in: (s: any) => ({ request: { orderId: s.orderId, amount: s.amount } }),
+    out: (s, res: any) => ({ ...s, paymentId: res.message.paymentId }),
+  })
+  // Step 3: HTTP — confirm
+  .step(getOrder.case("byId"), {
+    in: (s: any) => ({ params: { id: s.orderId } }),
+  });
+```
+
+Flow state threads through via typed `in` / `out` lenses, **across protocols**.
+
+### What you get
+
+- **Case-level lifecycle** — mark cases `deferred` (with reason) or `deprecated` (with replacement hint)
+- **Structured failure classification** — gRPC status codes map to `transient` / `client` / `semantic` / `auth` / `server` kinds; transient codes (1 CANCELLED, 4 DEADLINE_EXCEEDED, 8 RESOURCE_EXHAUSTED, 14 UNAVAILABLE) marked `retryable`
+- **Projection to Markdown** — case inventory with lifecycle markers, via `glubean contracts`
+- **Flow composition** — mix with HTTP / GraphQL cases, same artifact
+- **Scanner + MCP integration** — `glubean scan`, `glubean_extract_contracts` MCP tool, all work unchanged for `contract.grpc(...)`
 
-## Quick Start
+---
+
+## Quick Start — Transport plugin (low-level)
+
+For quick tests or exploratory work that doesn't need a declared contract:
 
 ```ts
 import { test, configure } from "@glubean/sdk";
@@ -35,7 +133,7 @@ export const getUser = test("get-user", async (ctx) => {
 });
 ```
 
-## Standalone (without `configure()`)
+### Standalone (without `configure()`)
 
 ```ts
 import { createGrpcClient } from "@glubean/grpc";
@@ -59,9 +157,79 @@ console.log(res.duration);    // ms
 client.close();
 ```
 
-## API
+---
+
+## API Reference
+
+### Contract
+
+#### `contract.grpc.with(instanceName, defaults?)`
+
+Returns a scoped factory. Direct `contract.grpc("id", spec)` is not supported — use `.with(...)` first.
+
+Instance defaults (`GrpcContractDefaults`):
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `client` | `GrpcClient` | Default client (from `configure({ plugins })`) |
+| `tags` | `string[]` | Tags inherited by all contracts in this instance |
+| `feature` | `string` | Grouping key for projection |
+| `metadata` | `Record<string, string>` | Default metadata for all contracts |
+| `deadlineMs` | `number` | Default deadline |
+| `extensions` | `Extensions` | Projection-level extensions (x-* keys) |
+
+#### `contract.grpc.with(...)("contractId", spec)`
+
+Creates one contract. Spec shape (`GrpcContractSpec`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `string` | Wire target `"Service/Method"` — renders as `"Service.Method"` in UI |
+| `description` | `string` | Contract-level description |
+| `requestSchema` | `SchemaLike<Req>` | Contract-level request schema (for projection) |
+| `defaultRequest` | `Partial<Req>` | Merged under each case's `request` |
+| `defaultMetadata` | `Record<string, string>` | Merged under each case's `metadata` |
+| `deadlineMs` | `number` | Contract-level deadline |
+| `client` | `GrpcClient` | Override instance client |
+| `cases` | `Record<string, GrpcContractCase>` | Named cases — required |
+
+Case shape (`GrpcContractCase<Req, Res, S>`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | `string` | Required — why this case exists |
+| `request` | `Req \| (state) => Req` | Request message; deep-merged over contract defaults |
+| `metadata` | `Record<string, string> \| fn` | Per-call metadata |
+| `deadlineMs` | `number` | Per-call deadline override |
+| `expect` | `GrpcContractExpect<Res>` | `statusCode` / `schema` / `message` / `metadata` / `metadataMatch` |
+| `setup` / `teardown` | `(ctx, state?) => Promise<void>` | Lifecycle |
+| `verify` | `(ctx, GrpcCaseResult) => Promise<void>` | Business-logic check after other assertions |
+| `deferred` | `string` | Skip with reason |
+| `deprecated` | `string` | Deprecate with reason |
+| `tags` / `severity` / `requires` / `defaultRun` | — | Standard case metadata |
+
+`expect` fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `statusCode` | `number` | Expected gRPC status code (default: `0` / OK) |
+| `schema` | `SchemaLike<Res>` | Response schema; validated via `ctx.validate` |
+| `message` | `Partial<Res>` | Partial match on response message |
+| `metadata` | `SchemaLike<Record<string, string>>` | Schema for trailing metadata |
+| `metadataMatch` | `Record<string, string>` | Partial match on trailing metadata |
+
+`GrpcCaseResult<Res>` — shape passed to `verify` and flow `out` lens:
 
-### `grpc(options)` — Plugin Factory
+| Field | Type |
+|-------|------|
+| `message` | `Res` |
+| `status.code` / `status.details` | `number` / `string` |
+| `responseMetadata` | `Record<string, string>` |
+| `duration` | `number` (ms) |
+
+### Transport
+
+#### `grpc(options)` — Plugin Factory
 
 For use with `configure({ plugins })`. Supports `{{template}}` placeholders in `address` and `metadata` values, resolved from Glubean vars and secrets.
 
@@ -75,9 +243,9 @@ For use with `configure({ plugins })`. Supports `{{template}}` placeholders in `
 | `tls` | `boolean` | Use TLS (default: `false`) |
 | `deadlineMs` | `number` | Default deadline in ms (default: `30000`) |
 
-### `createGrpcClient(options, hooks?)` — Standalone
+#### `createGrpcClient(options, hooks?)` — Standalone
 
-Same options as above (without template support). Optional `hooks` parameter for instrumentation:
+Same options as above (without template support). Optional `hooks` parameter:
 
 ```ts
 createGrpcClient(options, {
@@ -85,7 +253,7 @@ createGrpcClient(options, {
 });
 ```
 
-### `client.call(method, request, options?)`
+#### `client.call(method, request, options?)`
 
 Make a unary RPC call.
 
@@ -108,10 +276,36 @@ Returns `GrpcCallResult`:
 
 Errors don't throw — they return with a non-zero `status.code` for assertion-friendly testing.
 
-### `client.close()`
+#### `client.close()`
 
 Close the underlying gRPC channel.
 
+---
+
+## Custom matchers
+
+`import "@glubean/grpc"` side-effect registers gRPC matchers onto the shared
+`ctx.expect()` surface. No extra import or configure field needed.
+
+```ts
+import "@glubean/grpc";
+
+// Works on GrpcCallResult (transport) and GrpcCaseResult (contract verify / flow out lens)
+ctx.expect(res).toHaveGrpcStatus(0);                  // exact code
+ctx.expect(res).toHaveGrpcOk();                       // convenience for code 0
+ctx.expect(res).toHaveGrpcStatus(5, "user lookup");   // with context label
+ctx.expect(res).toHaveGrpcMetadata("x-request-id");   // presence
+ctx.expect(res).toHaveGrpcMetadata("x-tenant", "acme"); // value
+ctx.expect(res).not.toHaveGrpcStatus(0);              // negation
+```
+
+All matchers inherit `.not` negation, `.orFail()` chaining, and soft-by-default
+semantics from `@glubean/sdk`'s `Expectation`. Types come through
+`CustomMatchers<T>` declaration merging automatically — no user-side
+`declare module` required.
+
+---
+
 ## Tracing
 
 Every RPC call emits a single `trace` event with the full request/response cycle:
@@ -130,7 +324,7 @@ Every RPC call emits a single `trace` event with the full request/response cycle
 | `response` | `object` | Response payload (success only) |
 | `metadata` | `object` | Merged request metadata (static + per-call) |
 
-These traces share the same event channel as HTTP traces, enabling unified timeline rendering in the Glubean dashboard.
+Traces share the same event channel as HTTP — enables unified timeline rendering in the Glubean dashboard and cross-protocol flow inspection.
 
 ## Auth
 
@@ -151,15 +345,54 @@ await client.call("GetUser", { id: "u_123" }, {
 });
 ```
 
+At the contract layer, metadata merges in this order (right wins):
+instance `defaults.metadata` < contract `defaultMetadata` < case `metadata` < flow-step `in` lens `metadata`.
+
+---
+
+## Migration: 0.1.x → 0.2.0
+
+**What's new:**
+- Contract adapter shipped inside this package. `import "@glubean/grpc"` now also registers `contract.grpc.with(...)`.
+- Single-package model: no separate `@glubean/contract-grpc` package.
+
+**What's not broken:**
+- Existing `configure({ plugins: { x: grpc({ ... }) } })` usage is unchanged.
+- Existing `createGrpcClient(...)` usage is unchanged.
+- All 0.1.x transport tests still pass without modification.
+
+**Only additive API changes:**
+- `contract.grpc.with(...)` now available from `@glubean/sdk` after importing this package.
+- Export surface gained contract types (`GrpcContractSpec`, `GrpcContractCase`, etc.).
+
+If you currently use `@glubean/grpc` only as a transport plugin and do not import `contract.grpc` anywhere, no migration is required.
+
 ## Scope
 
-This is a v1 focused on unary RPC. Not included:
+### Phase 1 (shipped)
+
+- Unary RPC calls (contract + transport layers)
+- Status code assertions + schema validation
+- Response metadata match
+- Deadline + metadata merge through contract → instance → case → flow-step
+- gRPC status → FailureKind classification for repair loop
+- Markdown projection (case list + lifecycle markers)
+- Cross-protocol flow composition (HTTP + gRPC verified end-to-end)
+
+### Phase 2 (planned)
 
 - Server / client / bidirectional streaming
+- GraphQL subscription sharing the same streaming case design
+- See `internal/40-discovery/proposals/contract-async-protocol-plugins.md`
+
+### Out of scope (Phase 3+)
+
 - Reflection-based service discovery
-- Static codegen / type generation
-- grpc-web / Connect RPC
-- Retry policies
+- grpc-gateway / HTTP transcoding projection
+- Buf schema registry integration
+- Generating `.proto` from contract (solvable via annotation passthrough, but deferred — see proposal §7b)
+
+---
 
 ## License
 

package/dist/contract/adapter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Built-in gRPC contract adapter for @glubean/grpc 0.2.0.
+ *
+ * Shipped alongside the transport plugin in @glubean/grpc (single-package
+ * model — "contract is a first-class citizen"). Registered via
+ * `contract.register("grpc", grpcAdapter)` on import — see ./index.ts.
+ *
+ * Responsibilities (same interface as HTTP adapter):
+ *   - execute: run a case's setup → request → expect → verify → teardown
+ *   - executeCaseInFlow: deep-merge resolvedInputs, run case in flow mode
+ *   - validateCaseForFlow: reject function-valued request/metadata fields
+ *   - project: runtime ContractProjection<GrpcPayloadSchemas>
+ *   - normalize: runtime → JSON-safe ExtractedContractProjection
+ *   - classifyFailure: gRPC status 0-16 → FailureKind
+ *   - renderTarget: "Service/Method" → "Service.Method" (display-only)
+ *   - toMarkdown: case list
+ *   - describePayload: high-level summary for index views
+ *
+ * Phase 1 scope: unary RPCs only. Streaming deferred to Phase 2.
+ */
+import type { ContractProtocolAdapter } from "@glubean/sdk";
+import type { GrpcContractMeta, GrpcContractSafeMeta, GrpcContractSpec, GrpcPayloadSchemas, GrpcSafeSchemas } from "./types.js";
+/**
+ * Split "Service/Method" wire target into parsed parts.
+ * Returns `undefined` for malformed targets rather than throwing, so
+ * normalize + projection can tolerate hand-authored data in scanner output.
+ */
+export declare function parseTarget(target: string): {
+    service: string;
+    method: string;
+} | undefined;
+/** Convert a SchemaLike to a JSON Schema fragment if possible (best-effort). */
+export declare function schemaToJsonSchema(schema: unknown): Record<string, unknown> | null;
+/**
+ * Reject cases that reference case-local setup state via function-valued
+ * `request` or `metadata` fields when used in a flow. Flow mode can't
+ * supply per-case setup state (state belongs to flow orchestration).
+ *
+ * Parallels HTTP's `validateHttpCaseForFlow` — same discipline as HTTP's
+ * function-valued body/params/query/headers rejection.
+ */
+export declare function validateGrpcCaseForFlow(spec: GrpcContractSpec, caseKey: string, contractId: string): void;
+export declare const grpcAdapter: ContractProtocolAdapter<GrpcContractSpec, GrpcPayloadSchemas, GrpcContractMeta, GrpcSafeSchemas, GrpcContractSafeMeta>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/contract/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/contract/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAEV,uBAAuB,EAMxB,MAAM,cAAc,CAAC;AAOtB,OAAO,KAAK,EAEV,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAMpB;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,GACb;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOjD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAalF;AAuZD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,IAAI,CAoBN;AAqGD,eAAO,MAAM,WAAW,EAAE,uBAAuB,CAC/C,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,CAuBrB,CAAC"}