zinkee 0.1.44 → 0.1.46

package/docs/superpowers/plans/2026-03-25-cli-backend-error-contract.md

@@ -1,503 +0,0 @@
-# CLI and Backend Error Contract Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make the CLI preserve useful backend error details, align request payloads with the real API contract, and close the highest-value backend validation gaps found during real E2E usage.
-
-**Architecture:** Fix the contract at two layers. In the CLI, preserve backend JSON errors instead of collapsing them to `unknown_error`, resolve schema slugs before hitting UUID-only endpoints, and emit patch payloads in the shape the API actually expects. In the backend, tighten request binding/validation so accepted CLI payloads work consistently and rejected payloads fail with specific, actionable reasons.
-
-**Tech Stack:** TypeScript ESM CLI with Commander/Vitest, Java Spring WebFlux backend, workflow service, nexus connection service.
-
----
-
-## File Map
-
-**CLI files**
-- Modify: `/Users/david/dev/z2/cli/src/client.ts`
-- Modify: `/Users/david/dev/z2/cli/src/utils/errors.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/records.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/schemas.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/automations.ts`
-- Modify: `/Users/david/dev/z2/cli/src/utils/examples.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/records.test.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/schemas.test.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/automations.test.ts`
-- Create: `/Users/david/dev/z2/cli/src/client.test.ts`
-
-**Backend files**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/infra/web/v2/schema/SchemaV2Handler.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/schema/SchemaV2CreateFieldRequest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/schema/SchemaV2ContractValidator.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/schema/SchemaV2FieldValidationService.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/schema/SchemaV2FieldTranslator.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationV2Service.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationV2ContractValidator.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationConnectionV2Service.java`
-- Modify: `/Users/david/dev/z2/z2-backend/workflow/src/main/java/com/zinkee/workflow/application/WorkflowService.java`
-- Modify: `/Users/david/dev/z2/z2-backend/nexus/src/main/java/com/zinkee/nexus/application/ConnectionService.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/config/error/GlobalErrorWebExceptionHandlerTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/schema/SchemaV2RequestBindingTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/schema/SchemaV2ServiceTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/automation/AutomationV2ServiceTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/automation/AutomationCatalogV2ServiceTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/workflow/src/test/java/com/zinkee/workflow/application/WorkflowServiceTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/nexus/src/test/java/com/zinkee/nexus/application/ConnectionServiceTest.java`
-
-## Task 1: Preserve Structured Backend Errors in the CLI
-
-**Files:**
-- Modify: `/Users/david/dev/z2/cli/src/client.ts`
-- Modify: `/Users/david/dev/z2/cli/src/utils/errors.ts`
-- Create: `/Users/david/dev/z2/cli/src/client.test.ts`
-
-- [ ] **Step 1: Add or adjust the relevant tests**
-
-Add tests that simulate a backend `400` returning JSON like:
-
-```json
-{
-  "status": 400,
-  "error": "BAD_REQUEST",
-  "reason": "schema_id_invalid",
-  "message": "Schema identifier is invalid.",
-  "action": "Use a valid UUID in the schemaId field.",
-  "requestId": "req-123"
-}
-```
-
-Assert that the CLI error JSON preserves:
-- backend `message`
-- backend `reason`
-- backend `action`
-- backend `requestId`
-- HTTP `status`
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-npm test -- src/client.test.ts
-```
-
-Expected: new assertions fail because `http_error` is currently converted into plain `unknown_error`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `/Users/david/dev/z2/cli/src/client.ts`, keep attaching parsed `responseBody` to `ApiClientError`.
-
-In `/Users/david/dev/z2/cli/src/utils/errors.ts`, detect `ApiClientError` with `responseBody` shaped like the backend envelope and convert it into a `CliError` that preserves details:
-
-```ts
-details: {
-  status,
-  reason,
-  action,
-  requestId,
-  path,
-}
-```
-
-Do not discard the backend `message`.
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-npm test -- src/client.test.ts src/commands/automations.test.ts src/commands/schemas.test.ts src/commands/records.test.ts
-```
-
-Expected: CLI JSON errors now expose the backend reason/action/requestId when present.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/client.ts src/utils/errors.ts src/client.test.ts src/commands/automations.test.ts src/commands/schemas.test.ts src/commands/records.test.ts
-git commit -m "fix: preserve backend error details in cli json output"
-```
-
-## Task 2: Resolve Schema Slugs Before Hitting UUID-Only Record Endpoints
-
-**Files:**
-- Modify: `/Users/david/dev/z2/cli/src/commands/records.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/records.test.ts`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add tests for `records create`, `records query`, `records update`, and `records delete` proving that when the user passes a schema slug, the command resolves it before calling the API path that currently requires UUID.
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-npm test -- src/commands/records.test.ts
-```
-
-Expected: slug-based write/query tests fail or do not exist yet.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Extract the schema-resolution logic already present in `/Users/david/dev/z2/cli/src/commands/schemas.ts` into a shared helper, or duplicate it carefully for records first if you want the smallest safe change.
-
-Apply that resolver before:
-- `api.listRecords`
-- `api.queryRecords`
-- `api.getRecord`
-- `api.createRecord`
-- `api.updateRecord`
-- `api.deleteRecord`
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-npm test -- src/commands/records.test.ts
-```
-
-Expected: record commands accept slug input and hit the API with UUID selectors.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/commands/records.ts src/commands/records.test.ts
-git commit -m "fix: resolve schema slugs for records commands"
-```
-
-## Task 3: Align `automations update` With the Backend Patch Contract
-
-**Files:**
-- Modify: `/Users/david/dev/z2/cli/src/commands/automations.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/automations.test.ts`
-- Modify: `/Users/david/dev/z2/cli/src/utils/examples.ts`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add a test asserting that:
-
-```bash
-zinkee automations update <id> --name X --description Y
-```
-
-builds:
-
-```json
-{
-  "set": {
-    "name": "X",
-    "description": "Y"
-  }
-}
-```
-
-not:
-
-```json
-{
-  "name": "X",
-  "description": "Y"
-}
-```
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-npm test -- src/commands/automations.test.ts
-```
-
-Expected: update payload test fails because the CLI currently sends top-level fields.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Change `buildAutomationUpdateInput` in `/Users/david/dev/z2/cli/src/commands/automations.ts` so CLI flags populate `input.set`, and `--raw` is either:
-- required to already be in backend patch shape, or
-- normalized into patch shape when passed as flat metadata fields.
-
-Do not mix two incompatible patch contracts in the same request.
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-npm test -- src/commands/automations.test.ts
-```
-
-Expected: the command emits patch payloads compatible with `AutomationV2PatchRequest(Map<String,Object> set, List<String> unset)`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/commands/automations.ts src/commands/automations.test.ts src/utils/examples.ts
-git commit -m "fix: send automation patch payloads in backend contract shape"
-```
-
-## Task 4: Make `connections update` Nested Mutations Predictable
-
-**Files:**
-- Modify: `/Users/david/dev/z2/cli/src/commands/automations.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/automations.test.ts`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add tests for:
-
-```bash
-zinkee automations connections update <id> --set name=foo
-zinkee automations connections update <id> --set config.headerName=X-Api-Key
-```
-
-Assert that dotted keys are either:
-- expanded into `{ set: { config: { headerName: "X-Api-Key" }}}`, or
-- rejected locally with a precise CLI error telling the user to use `--raw`.
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-npm test -- src/commands/automations.test.ts
-```
-
-Expected: nested config path behavior is missing or wrong.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Preferred CLI behavior:
-- keep flat keys like `name`
-- expand `config.*` into a nested `config` object inside `set`
-- if multiple `config.*` assignments appear, merge them
-
-Fallback acceptable behavior:
-- reject dotted paths with a precise `invalid_cli_usage` message and force `--raw`
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-npm test -- src/commands/automations.test.ts
-```
-
-Expected: nested connection config updates are deterministic instead of silently partial.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/commands/automations.ts src/commands/automations.test.ts
-git commit -m "fix: normalize nested connection patch paths"
-```
-
-## Task 5: Relax `schemas fields create` So Raw-Driven Flows Are Usable
-
-**Files:**
-- Modify: `/Users/david/dev/z2/cli/src/commands/schemas.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/schemas.test.ts`
-- Modify: `/Users/david/dev/z2/cli/src/utils/examples.ts`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add a test showing that this is valid:
-
-```bash
-zinkee schemas fields create <schema> --raw '{"type":"TextField","slug":"email","label":"Email","config":{"placeholder":"Email"}}'
-```
-
-and does not require duplicate `--type/--slug/--label` flags.
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-npm test -- src/commands/schemas.test.ts
-```
-
-Expected: raw-only field creation fails because Commander requires the explicit flags.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Replace unconditional `.requiredOption(...)` with validation inside the action:
-- accept values from flags or raw payload
-- require `type`, `slug`, `label` only after merging both sources
-- preserve current shorthand normalization from `text` to `TextField`
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-npm test -- src/commands/schemas.test.ts
-```
-
-Expected: field creation works in both flag-first and raw-first flows.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/commands/schemas.ts src/commands/schemas.test.ts src/utils/examples.ts
-git commit -m "fix: allow raw-first schema field creation flows"
-```
-
-## Task 6: Backend Fixes for Schema Field Config and Automation Contracts
-
-**Files:**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/schema/SchemaV2CreateFieldRequest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/schema/SchemaV2FieldValidationService.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/schema/SchemaV2FieldTranslator.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationV2Service.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationV2ContractValidator.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/schema/SchemaV2RequestBindingTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/schema/SchemaV2ServiceTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/automation/AutomationV2ServiceTest.java`
-
-- [ ] **Step 1: Add or adjust the relevant tests**
-
-Backend tests to add:
-- `SchemaV2CreateFieldRequest` binds `config` for `TextField`
-- `SchemaV2Service` accepts a `TextField` with a harmless config payload like `{"placeholder":"Email"}`
-- `AutomationV2Service.createAutomation` accepts the exact payload the CLI currently emits for `record_created`
-- `AutomationV2Service.patchAutomation` keeps honoring `{ set, unset }` and mutates metadata correctly
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew api:test --tests '*SchemaV2*' --tests '*AutomationV2ServiceTest*'
-```
-
-Expected: at least one new test should fail and expose the current mismatch.
-
-- [ ] **Step 3: Write minimal implementation**
-
-For schema field config:
-- inspect `SchemaV2FieldConfigBinding.deserialize(type, config)`
-- make `TextField` config either bind successfully or be explicitly ignored if harmless
-- keep validation strict for truly invalid configs, but stop rejecting benign config objects wholesale
-
-For automation create:
-- inspect `AutomationV2ContractValidator.validateCreateRequest`
-- make sure the CLI-emitted trigger payload for `record_created` is actually accepted if semantically valid
-
-For automation patch:
-- keep the backend contract as `{ set, unset }`
-- confirm `applyMetadataPatch` remains the single source of truth
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew api:test --tests '*SchemaV2RequestBindingTest*' --tests '*SchemaV2ServiceTest*' --tests '*AutomationV2ServiceTest*'
-```
-
-Expected: request binding and contract tests pass.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git -C /Users/david/dev/z2/z2-backend add api/src/main/java api/src/test/java
-git -C /Users/david/dev/z2/z2-backend commit -m "fix: align schema field and automation api contracts"
-```
-
-## Task 7: Backend Fix for Nested Connection Patch Semantics
-
-**Files:**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationConnectionV2Service.java`
-- Modify: `/Users/david/dev/z2/z2-backend/nexus/src/main/java/com/zinkee/nexus/application/ConnectionService.java`
-- Modify: `/Users/david/dev/z2/z2-backend/nexus/src/test/java/com/zinkee/nexus/application/ConnectionServiceTest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/automation/AutomationCatalogV2ServiceTest.java`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add a backend test asserting that a patch like:
-
-```json
-{
-  "set": {
-    "name": "foo",
-    "config": {
-      "headerName": "X-Api-Key"
-    }
-  }
-}
-```
-
-updates both the flat field and the config field.
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew api:test --tests '*AutomationCatalogV2ServiceTest*' --tests '*ConnectionServiceTest*'
-```
-
-Expected: nested config patch coverage is missing or failing.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Keep the backend contract simple:
-- `set.config` replaces config as a whole object
-- do not try to support dotted paths in the backend if the CLI can normalize them first
-- ensure config replacement preserves intentional values and passes validation in `ConnectionService`
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew api:test --tests '*AutomationCatalogV2ServiceTest*' --tests '*ConnectionServiceTest*'
-```
-
-Expected: connection patch semantics are explicit and test-covered.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git -C /Users/david/dev/z2/z2-backend add api/src/main/java nexus/src/main/java api/src/test/java nexus/src/test/java
-git -C /Users/david/dev/z2/z2-backend commit -m "fix: support config replacement in connection patch flows"
-```
-
-## Backend Agent Handoff
-
-Give the backend agent this brief:
-
-1. Reproduce these exact contract mismatches from the CLI investigation:
-   - `POST /api/v2/schemas/{id}/fields` with `{"type":"TextField","slug":"email","label":"Email","required":true,"config":{"placeholder":"Email probe"}}` returns `reason=schema_field_create_request_invalid`.
-   - `POST /api/v2/automations` with `{"name":"proxy-auto-create","trigger":{"type":"record_created","config":{"schemaId":"2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e","conditions":[{"field":"status","comparator":"eq","values":["active"]}]}}}` returns `reason=automation_create_payload_invalid`.
-   - `PATCH /api/v2/automations/{id}` with `{"set":{"name":"X","description":"Y"}}` should update metadata and return the updated resource.
-   - `PATCH /api/v2/automation-connections/{id}` with `{"set":{"name":"foo","config":{"headerName":"X-Api-Key"}}}` should update both name and config.
-
-2. Start in these files:
-   - `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/infra/web/v2/schema/SchemaV2Handler.java`
-   - `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/schema/SchemaV2CreateFieldRequest.java`
-   - `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/schema/SchemaV2FieldValidationService.java`
-   - `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationV2Service.java`
-   - `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationV2ContractValidator.java`
-   - `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/automation/AutomationConnectionV2Service.java`
-   - `/Users/david/dev/z2/z2-backend/nexus/src/main/java/com/zinkee/nexus/application/ConnectionService.java`
-   - `/Users/david/dev/z2/z2-backend/workflow/src/main/java/com/zinkee/workflow/application/WorkflowService.java`
-
-3. Success criteria:
-   - backend keeps returning structured `reason` codes
-   - valid payloads stop failing
-   - patch endpoints actually mutate and return the mutated resource
-   - new tests cover the exact payloads above
-
-4. Verification commands:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew api:test --tests '*SchemaV2*' --tests '*AutomationV2*' --tests '*ConnectionServiceTest*'
-```
-