zinkee 0.1.44 → 0.1.45

package/docs/superpowers/plans/2026-03-26-display-freeform-create.md

@@ -1,389 +0,0 @@
-# Display Freeform Create 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:** Extend the public display create API so clients can create a freeform display and persist `freeformLayouts` in the initial `POST`, while preserving all existing create behavior for non-freeform layouts.
-
-**Architecture:** Keep the contract shape consistent by adding optional `layout.freeformLayouts` to the create request, then route creation through the same layout rules already used by `PATCH /api/v2/displays/{id}/layout`. The backend remains the source of truth for layout validation and persistence, and the CLI can adopt the new field later without requiring a second request.
-
-**Tech Stack:** Java Spring WebFlux backend, Java records for API contracts, JUnit/Reactor tests, TypeScript ESM CLI with Commander/Vitest for follow-up parity.
-
----
-
-## File Map
-
-**Backend files**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/display/DisplayV2CreateRequest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2ContractValidator.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2Service.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/infra/web/v2/ApiV2DisplayDocumentation.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/display/DisplayV2ServiceTest.java`
-
-**CLI follow-up files**
-- Modify: `/Users/david/dev/z2/cli/src/commands/displays.ts`
-- Modify: `/Users/david/dev/z2/cli/src/utils/examples.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/displays.test.ts`
-
-## Task 1: Extend the Create Contract to Accept `layout.freeformLayouts`
-
-**Files:**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/display/DisplayV2CreateRequest.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2ContractValidator.java`
-
-- [ ] **Step 1: Add or adjust the relevant tests**
-
-Add service-level tests that cover these create cases:
-
-```java
-new DisplayV2CreateRequest(
-    "Board",
-    new DisplayV2CreateRequest.Layout("freeform", Map.of("lg", List.of()))
-)
-```
-
-and:
-
-```java
-new DisplayV2CreateRequest(
-    "Board",
-    new DisplayV2CreateRequest.Layout("widget_row", Map.of("lg", List.of()))
-)
-```
-
-Assert that:
-- freeform create accepts `freeformLayouts`
-- non-freeform create rejects `freeformLayouts`
-- existing create without `freeformLayouts` still works
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: compilation or test failure because `DisplayV2CreateRequest.Layout` does not yet accept `freeformLayouts`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/display/DisplayV2CreateRequest.java`:
-- add `Object freeformLayouts` to the nested `Layout` record
-
-In `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2ContractValidator.java`:
-- keep `name` and `layout.template` required
-- reject `layout.freeformLayouts` when `layout.template` is not `"freeform"`
-- do not require `freeformLayouts` for freeform layouts
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: create contract compiles and validation cases behave as intended.
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-git add api/src/main/java/com/zinkee/api/domain/model/v2/display/DisplayV2CreateRequest.java api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2ContractValidator.java api/src/test/java/com/zinkee/api/service/v2/display/DisplayV2ServiceTest.java
-git commit -m "feat: accept freeform layouts in display create contract"
-```
-
-## Task 2: Persist `currentLayouts` During Display Creation
-
-**Files:**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2Service.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/display/DisplayV2ServiceTest.java`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add a test proving that:
-
-```java
-service.createDisplay(
-    APP_NAME,
-    new DisplayV2CreateRequest(
-        "Employees",
-        new DisplayV2CreateRequest.Layout(
-            "freeform",
-            Map.of("lg", List.of(Map.of("i", "widget-1", "x", 0, "y", 0, "w", 6, "h", 5)))
-        )
-    )
-)
-```
-
-persists:
-- `"layoutTemplate": "freeform"`
-- `"slots": "{\"grid\":[]}"`
-- `"currentLayouts"` with serialized freeform JSON
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: the new persistence assertion fails because `createDisplay` currently never writes `currentLayouts`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2Service.java`:
-- update `createDisplay` to read `request.layout().freeformLayouts()`
-- when template is `"freeform"` and layouts are present, persist them to `additionalProperties.put("currentLayouts", writeJson(...))`
-- keep slot initialization unchanged
-
-Refactor only if it materially reduces duplication:
-- extract a private helper that applies `layoutTemplate`, `slots`, and optional `currentLayouts` to `additionalProperties`
-- use the helper from both `createDisplay` and `patchDisplayLayout`
-
-Do not change response shapes or existing slot behavior.
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: create now persists `currentLayouts` only for valid freeform create requests.
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-git add api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2Service.java api/src/test/java/com/zinkee/api/service/v2/display/DisplayV2ServiceTest.java
-git commit -m "feat: persist freeform layouts during display creation"
-```
-
-## Task 3: Keep Error Messages and Serialization Semantics Consistent
-
-**Files:**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2Service.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/test/java/com/zinkee/api/service/v2/display/DisplayV2ServiceTest.java`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add a test that passes a non-serializable `freeformLayouts` object through create and asserts the backend returns a display-layout validation error instead of saving broken data.
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: either no coverage for the case exists, or the current error code/message is tied specifically to patch-only wording.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2Service.java`:
-- rename or generalize `writeJson` failure messaging so it is correct for both create and patch flows
-- keep the error in the display layout family
-- avoid introducing create-only and patch-only serializers if one shared helper is enough
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: invalid freeform layout payloads fail with a clear, reusable display layout validation error.
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-git add api/src/main/java/com/zinkee/api/service/v2/display/DisplayV2Service.java api/src/test/java/com/zinkee/api/service/v2/display/DisplayV2ServiceTest.java
-git commit -m "refactor: reuse display layout serialization errors across create and patch"
-```
-
-## Task 4: Update the Public API Documentation
-
-**Files:**
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/infra/web/v2/ApiV2DisplayDocumentation.java`
-- Modify: `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/display/DisplayV2CreateRequest.java`
-
-- [ ] **Step 1: Add or adjust the relevant example**
-
-Update the documented create example so it shows both:
-- a normal create payload with `layout.template`
-- a freeform create payload with nested `layout.freeformLayouts`
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: no behavior change, but docs still show the old create-only-template example until updated.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/infra/web/v2/ApiV2DisplayDocumentation.java`:
-- update the create description to mention optional `layout.freeformLayouts` for freeform displays
-- replace the current example with one that reflects the new contract
-
-In `/Users/david/dev/z2/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/display/DisplayV2CreateRequest.java`:
-- add `@Schema` descriptions for the new nested field
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: the API docs and record schema now describe the new create capability without changing runtime behavior.
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-git add api/src/main/java/com/zinkee/api/infra/web/v2/ApiV2DisplayDocumentation.java api/src/main/java/com/zinkee/api/domain/model/v2/display/DisplayV2CreateRequest.java
-git commit -m "docs: document freeform layouts in display create api"
-```
-
-## Task 5: Add CLI Parity for Single-Step Freeform Create
-
-**Files:**
-- Modify: `/Users/david/dev/z2/cli/src/commands/displays.ts`
-- Modify: `/Users/david/dev/z2/cli/src/utils/examples.ts`
-- Modify: `/Users/david/dev/z2/cli/src/commands/displays.test.ts`
-
-- [ ] **Step 1: Add or adjust the relevant test**
-
-Add a CLI test asserting that:
-
-```bash
-zinkee --json displays create --name Pipeline --template freeform --freeform-layouts '{"lg":[]}'
-```
-
-sends:
-
-```json
-{
-  "name": "Pipeline",
-  "layout": {
-    "template": "freeform",
-    "freeformLayouts": {
-      "lg": []
-    }
-  }
-}
-```
-
-- [ ] **Step 2: Run the relevant check and capture the current result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/cli
-npm test -- src/commands/displays.test.ts
-```
-
-Expected: the new assertion fails because `displays create` currently only sends `name` and `layout.template`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `/Users/david/dev/z2/cli/src/commands/displays.ts`:
-- add `--freeform-layouts <json>` and `--freeform-layouts-file <path>` to `displays create`
-- reuse `readNamedJsonOption(...)`
-- include `layout.freeformLayouts` only when provided
-
-In `/Users/david/dev/z2/cli/src/utils/examples.ts`:
-- add a concrete freeform create example
-
-- [ ] **Step 4: Run verification to confirm the intended result**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/cli
-npm test -- src/commands/displays.test.ts
-```
-
-Expected: CLI create supports the new API contract in one request.
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Users/david/dev/z2/cli
-git add src/commands/displays.ts src/utils/examples.ts src/commands/displays.test.ts
-git commit -m "feat: support freeform layouts in displays create"
-```
-
-## Task 6: Run Final Verification Across Backend and CLI
-
-**Files:**
-- Verify only
-
-- [ ] **Step 1: Run backend display tests**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-./gradlew :api:test --tests com.zinkee.api.service.v2.display.DisplayV2ServiceTest
-```
-
-Expected: all display service tests pass.
-
-- [ ] **Step 2: Run CLI display tests**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/cli
-npm test -- src/commands/displays.test.ts
-```
-
-Expected: CLI display tests pass.
-
-- [ ] **Step 3: Run a focused end-to-end create flow manually**
-
-Run:
-
-```bash
-cd /Users/david/dev/z2/cli
-zinkee --json displays create --name "Freeform desde CLI" --template freeform --freeform-layouts '{"lg":[{"i":"widget-1","x":0,"y":0,"w":6,"h":5}]}'
-```
-
-Then verify with:
-
-```bash
-zinkee --json displays get <display-id>
-```
-
-Expected: the returned `layout.freeformLayouts` is present immediately after create, without a second layout patch.
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd /Users/david/dev/z2/z2-backend
-git status --short
-cd /Users/david/dev/z2/cli
-git status --short
-```
-
-Expected: only intended backend and CLI files remain changed.

package/docs/superpowers/specs/2026-03-24-zinkee-cli-backend-blockers.md

@@ -1,172 +0,0 @@
-# Zinkee CLI Backend Blockers
-
-Lista de problemas detectados desde la CLI contra el backend local (`z2` + `api`) que parecen ser del backend o del contrato backend, no del binario del CLI.
-
-Perfil usado para reproducir:
-
-- `local`
-- `base_url = http://localhost:8088`
-
-## 1. `schemas fields create` falla cuando se manda `config`
-
-### Síntoma
-
-La creación de fields funciona si la CLI no manda `config`, pero falla cuando se manda `config` en el payload.
-
-### Request
-
-Ruta:
-
-```text
-POST /api/v2/schemas/{schemaId}/fields
-```
-
-Ejemplo de payload que falla:
-
-```json
-{
-  "type": "TextField",
-  "slug": "test-name",
-  "label": "Test Name",
-  "required": true,
-  "config": {
-    "textType": "LONG",
-    "defaultValue": "Ada",
-    "conditionalFormatting": []
-  }
-}
-```
-
-### Resultado
-
-- HTTP `500`
-
-### Error observado en logs
-
-```text
-InvalidDefinitionException
-Cannot construct instance of `com.fasterxml.jackson.databind.JsonNode`
-through reference chain: com.zinkee.api.domain.model.v2.schema.SchemaV2CreateFieldRequest["config"]
-```
-
-### Interpretación
-
-El backend local está rompiendo en binding/deserialización del campo `config` en `SchemaV2CreateFieldRequest`.
-
-## 2. `displays delete` no tiene ruta efectiva en API v2
-
-### Síntoma
-
-La CLI intenta borrar displays con:
-
-```text
-DELETE /api/v2/displays/{displayId}
-```
-
-pero el backend responde con error.
-
-### Resultado
-
-- HTTP `500`
-
-### Error observado en logs
-
-```text
-500 Server Error for HTTP DELETE "/api/v2/displays/{displayId}"
-ResponseStatusException: 404 NOT_FOUND
-```
-
-### Interpretación
-
-La ruta de borrado parece no existir realmente en `ApiV2DisplayRoutes`, aunque desde el punto de vista del dominio sería esperable.
-
-## 3. `automations create` devuelve `automation_create_payload_invalid`
-
-### Síntoma
-
-La creación de automatizaciones falla incluso con payloads alineados con la documentación.
-
-### Request
-
-Ruta:
-
-```text
-POST /api/v2/automations
-```
-
-Payload mínimo probado:
-
-```json
-{
-  "name": "e2e-auto-direct",
-  "folderId": "0fd93776-33ac-4089-a7b8-ec1fcb810312",
-  "trigger": {
-    "type": "scheduled",
-    "config": {
-      "cronExpression": "0 15 10 * * 1"
-    }
-  }
-}
-```
-
-### Resultado
-
-- HTTP `400`
-
-### Error observado
-
-```json
-{
-  "reason": "automation_create_payload_invalid",
-  "message": "Automation create payload is invalid."
-}
-```
-
-### Interpretación
-
-El backend local rechaza `POST /api/v2/automations` incluso con payloads que parecen compatibles con:
-
-- `AutomationV2CreateRequest`
-- `AutomationTriggerV2PutRequest`
-- `AutomationScheduledTriggerV2Config`
-
-No se observó stacktrace claro asociado en logs, solo paso por el error handler.
-
-## 4. `displays tabs create` falla correctamente en layouts que no soportan tabs
-
-### Nota
-
-Esto no parece bug del backend, sino validación correcta.
-
-### Error observado
-
-- HTTP `400`
-- `reason=display_tabs_unsupported`
-
-Mensaje:
-
-```text
-Display layout does not support shared tabs.
-```
-
-### Observación útil
-
-`displays tabs create` sí funciona con el layout:
-
-- `side_tabs_widgets`
-
-## 5. Warnings de entorno no bloqueantes
-
-Estos warnings aparecen en logs pero no parecen ser la causa de los fallos funcionales:
-
-- OTLP metrics:
-  - `Connection refused` a `http://localhost:4318/v1/metrics`
-- warning de Netty DNS nativo en macOS
-
-## Resumen
-
-Problemas a revisar en backend:
-
-- [ ] binding de `config` en `SchemaV2CreateFieldRequest`
-- [ ] existencia/soporte de `DELETE /api/v2/displays/{displayId}`
-- [ ] validación/binding de `POST /api/v2/automations`