zinkee 0.1.44 → 0.1.46

package/docs/superpowers/specs/2026-03-24-zinkee-cli-e2e-checklist.md

@@ -1,215 +0,0 @@
-# Zinkee CLI E2E Checklist
-
-Checklist operativo para despachar subagentes que ejecuten pruebas E2E de forma independiente.
-
-## Reglas Globales
-
-- [ ] Usar el perfil `local` de `~/.config/zinkee/config.toml`
-- [ ] Confirmar que el workspace es de pruebas antes de mutar nada
-- [ ] Ejecutar siempre el binario real: `node dist/index.js ...`
-- [ ] Usar un prefijo único por ejecución: `e2e-<timestamp>-<rand>`
-- [ ] Registrar todos los recursos creados para cleanup
-- [ ] Hacer cleanup en orden inverso al final del bloque
-- [ ] Si falla cleanup, reportarlo explícitamente
-- [ ] Verificar siempre stdout, stderr y exit code
-- [ ] En comandos con `--json`, validar envelope `{ data, meta }` o `{ error, meta }`
-
-## Preflight
-
-- [ ] `zinkee --json config validate`
-- [ ] `zinkee --json profiles get local`
-- [ ] `zinkee --json schemas list`
-- [ ] Verificar que `base_url` y `api_key` están resueltos
-- [ ] Verificar que el backend local responde
-
-## Contrato Global
-
-- [ ] `--json` éxito devuelve `{ data, meta }`
-- [ ] `--json` error devuelve `{ error, meta }`
-- [ ] `--read-only` bloquea escrituras
-- [ ] `--example` devuelve ejemplos sin ejecutar el comando real
-- [ ] Exit codes básicos son consistentes
-
-## Profiles / Config
-
-- [ ] Probar con config temporal aislado, no con el real
-- [ ] `profiles list`
-- [ ] `profiles get`
-- [ ] `profiles add`
-- [ ] `profiles update`
-- [ ] `profiles use`
-- [ ] `profiles remove`
-- [ ] `config path`
-- [ ] `config show`
-- [ ] `config validate`
-- [ ] Verificar redacción de secretos
-
-## Schemas
-
-- [ ] Crear schema
-- [ ] Listar schemas
-- [ ] Obtener schema
-- [ ] Actualizar schema
-- [ ] Crear field
-- [ ] Obtener field
-- [ ] Listar fields
-- [ ] Actualizar field
-- [ ] Borrar field
-- [ ] Borrar schema
-
-## Records / Comments
-
-- [ ] Crear record con `--set`
-- [ ] Crear record con `--set-json`
-- [ ] Query con `--select`
-- [ ] Query con `--where`
-- [ ] Query con `--sort`
-- [ ] Query con `--limit`
-- [ ] Query con `--offset`
-- [ ] Obtener record
-- [ ] Actualizar record con `--set`
-- [ ] Actualizar record con `--set-json`
-- [ ] Actualizar record con `--unset`
-- [ ] Borrar record
-- [ ] Listar comments
-- [ ] Crear comment con `--text`
-
-## Files
-
-- [ ] Upload de fichero
-- [ ] Storage info
-- [ ] Download binario a stdout
-- [ ] Download con `--output`
-- [ ] Download con `--json --output`
-- [ ] Validar que `--json` sin `--output` falla
-- [ ] Delete de fichero
-
-## Navigation
-
-- [ ] Crear folder
-- [ ] Listar folders
-- [ ] Get folder por UUID
-- [ ] Get folder por nombre exacto
-- [ ] Verificar error por ambigüedad de nombre
-- [ ] Actualizar folder
-- [ ] Mover resource con `navigation resources move`
-- [ ] Borrar folder
-
-## Teamspace
-
-- [ ] Crear folder
-- [ ] Listar folders
-- [ ] Get folder por UUID
-- [ ] Get folder por nombre exacto
-- [ ] `--include-resources`
-- [ ] Verificar error por ambigüedad de nombre
-- [ ] Actualizar folder
-- [ ] Publish resource
-- [ ] Unpublish resource
-- [ ] Borrar folder
-
-## Displays
-
-- [ ] Crear display
-- [ ] Listar displays
-- [ ] Obtener display
-- [ ] Actualizar display
-- [ ] Borrar display
-- [ ] Get layout
-- [ ] Update layout
-- [ ] Crear tab
-- [ ] Update tab
-- [ ] Delete tab
-- [ ] List variables
-- [ ] Get variable
-- [ ] Crear variable
-- [ ] Update variable
-- [ ] Delete variable
-- [ ] List widgets
-- [ ] Get widget
-- [ ] Crear widget con `--type`
-- [ ] Update widget con `--type`
-- [ ] Delete widget
-- [ ] List navigation-targets
-- [ ] Crear navigation-target
-- [ ] Update navigation-target
-- [ ] Delete navigation-target
-- [ ] Get cross-widget-filter
-- [ ] Set cross-widget-filter
-- [ ] Delete cross-widget-filter
-
-## Automations
-
-- [ ] List folders
-- [ ] Create folder
-- [ ] Update folder
-- [ ] Delete folder
-- [ ] Move automation to folder
-- [ ] List automations
-- [ ] Get automation
-- [ ] Create automation
-- [ ] Update automation
-- [ ] Delete automation
-- [ ] Activate automation
-- [ ] Deactivate automation
-- [ ] Get trigger
-- [ ] Set trigger con `--type`
-- [ ] List actions
-- [ ] Add action con `--type`
-- [ ] Update action con `--type`
-- [ ] Delete action
-- [ ] Get flow
-- [ ] Set flow con `--entry` y `--transition`
-- [ ] Get webhook
-- [ ] Set webhook
-- [ ] Delete webhook
-- [ ] List plugins
-- [ ] Get plugin
-- [ ] List connections
-- [ ] Get connection
-- [ ] Create connection
-- [ ] Update connection
-- [ ] Delete connection
-
-## Flujos Cruzados
-
-- [ ] Schema -> Record -> Comment
-- [ ] Schema -> Navigation -> Teamspace
-- [ ] Schema -> Display -> Widget/Variable
-- [ ] Schema -> Automation trigger/action/flow
-
-## Cleanup
-
-- [ ] Borrar automations creadas
-- [ ] Borrar displays creados
-- [ ] Unpublish de teamspace
-- [ ] Deshacer moves de navigation si aplica
-- [ ] Borrar records creados
-- [ ] Borrar files subidos
-- [ ] Borrar schemas creados
-- [ ] Borrar folders creados
-- [ ] Borrar connections creadas
-
-## Split Recomendado Para Subagentes
-
-- [ ] Subagente 1: preflight + contrato global
-- [ ] Subagente 2: profiles/config
-- [ ] Subagente 3: schemas
-- [ ] Subagente 4: records/comments
-- [ ] Subagente 5: files
-- [ ] Subagente 6: navigation
-- [ ] Subagente 7: teamspace
-- [ ] Subagente 8: displays
-- [ ] Subagente 9: automations
-- [ ] Subagente 10: flujos cruzados
-
-## Formato De Reporte Esperado
-
-- [ ] Qué comandos se ejecutaron
-- [ ] Qué recursos se crearon
-- [ ] Qué recursos se limpiaron
-- [ ] Qué assertions pasaron
-- [ ] Qué assertions fallaron
-- [ ] stdout/stderr relevante
-- [ ] exit codes
-- [ ] si el fallo es del CLI, del backend o del entorno

package/docs/superpowers/specs/2026-03-24-zinkee-cli-e2e-design.md

@@ -1,492 +0,0 @@
-# Zinkee CLI E2E Test Design
-
-## Context
-
-The Zinkee CLI is now implemented as a real TypeScript ESM CLI that targets Zinkee Public API v2.
-
-The next step is to design a full end-to-end test battery that exercises the real CLI binary against a real test workspace.
-
-These E2E tests should validate:
-
-- the real command-line interface, not just internal modules
-- real config resolution through the existing config file contract
-- real network interactions against the local Zinkee API/backend
-- output contracts for human mode and JSON mode
-- write safety behavior via `--read-only`
-- lifecycle behavior across all implemented domains
-
-## Environment Assumptions
-
-The E2E suite will use the existing `local` profile already present in:
-
-- `/Users/david/.config/zinkee/config.toml`
-
-The user explicitly confirmed that:
-
-- the `local` workspace is a dedicated test workspace
-- it is safe for E2E tests to create and destroy real resources there
-
-## Design Direction
-
-The E2E battery will:
-
-- run against the real CLI entrypoint
-- use the `local` profile as the default execution context for tests
-- create real resources with isolated test prefixes
-- clean up created resources after each scenario or suite
-- validate both success and failure contracts
-
-The preferred design is hybrid:
-
-- preflight checks
-- domain-specific suites
-- selected cross-domain flows
-
-## Core Principles
-
-### Real CLI, Not Internal Function Calls
-
-E2E tests must execute the built CLI process itself.
-
-Recommended execution target:
-
-```bash
-node dist/index.js ...
-```
-
-This ensures the tests cover:
-
-- commander parsing
-- root/global flag behavior
-- stdout and stderr behavior
-- exit codes
-- config resolution
-- JSON envelopes
-
-### Real Workspace, Isolated Data
-
-All write tests should use unique run-scoped identifiers.
-
-Recommended naming pattern:
-
-- `e2e-<timestamp>-<random>`
-
-Examples:
-
-- schema slug: `e2e-20260324-abc123-contacts`
-- display name: `e2e-20260324-abc123-pipeline`
-- automation name: `e2e-20260324-abc123-lead-flow`
-
-This allows:
-
-- safe repeated runs
-- post-failure inspection
-- optional future parallelization
-
-### Cleanup Is Mandatory
-
-The suite must track created resources and delete them in reverse dependency order.
-
-If cleanup fails:
-
-- the suite should report it explicitly
-- the failure should not be silently swallowed
-
-## Test Modes
-
-The battery should support three execution levels.
-
-### `e2e:smoke`
-
-Purpose:
-
-- verify that the CLI works end-to-end at a shallow level
-- catch obvious regressions quickly
-
-Coverage:
-
-- preflight
-- one or two representative read flows
-- one small create/delete lifecycle
-- `--json`
-- `--read-only`
-
-### `e2e:standard`
-
-Purpose:
-
-- primary day-to-day E2E suite
-
-Coverage:
-
-- preflight
-- one lifecycle-focused suite per domain
-- cleanup validation
-
-### `e2e:full`
-
-Purpose:
-
-- exhaustive contract coverage
-
-Coverage:
-
-- all standard coverage
-- error-path assertions
-- output contract assertions
-- more `--raw` and `--example` checks
-- more cross-domain integration flows
-
-## Preflight Suite
-
-The preflight suite should run before any destructive or mutating test group.
-
-It should validate:
-
-- `local` profile exists
-- resolved profile has `api_key`
-- resolved profile has `base_url`
-- backend responds to basic read commands
-- CLI binary is built and invokable
-
-Recommended checks:
-
-- `zinkee --json config validate`
-- `zinkee --json profiles get local`
-- one lightweight read command such as `schemas list`
-
-If preflight fails:
-
-- stop the test run immediately
-
-## Global Contract Suite
-
-This suite validates CLI-wide behavior independent of domain.
-
-Coverage:
-
-- `--json` success envelope is `{ data, meta }`
-- `--json` error envelope is `{ error, meta }`
-- `--read-only` blocks write/destructive commands
-- `--example` returns examples and does not run the command
-- exit codes are stable for representative cases
-- human output does not break basic expectations
-
-Representative checks:
-
-- success: `zinkee --json schemas list`
-- failure: invalid selector or invalid config override
-- read-only: `zinkee --read-only records create ...`
-- example: `zinkee --json --example records query`
-
-## Domain Suites
-
-### Profiles and Config
-
-These should run against a temporary isolated config file, not mutate the user’s real config.
-
-Coverage:
-
-- config compatibility with current TOML shape
-- profile add/update/remove/use
-- config show redaction
-- config validate
-- global overrides
-
-Purpose:
-
-- verify compatibility without touching real user state
-
-### Schemas
-
-Coverage:
-
-- create schema
-- list schemas
-- get schema
-- update schema
-- create field
-- get field
-- list fields
-- update field
-- delete field
-- delete schema
-
-Assertions:
-
-- JSON envelope
-- read/write lifecycle
-- UUID-or-slug selector behavior where applicable
-
-### Records and Comments
-
-Coverage:
-
-- create record via `--set`
-- create record via `--set-json`
-- query records with `--select`, `--where`, `--sort`, `--limit`, `--offset`
-- get record
-- update record with `--set`, `--set-json`, `--unset`
-- delete record
-- list comments
-- create comment via `--text`
-
-Assertions:
-
-- values mapping behavior
-- pagination metadata in `meta.page`
-- comment creation against a real record
-
-### Files
-
-Coverage:
-
-- upload file
-- storage info
-- download to stdout
-- download with `--output`
-- `--json --output`
-- delete file
-
-Assertions:
-
-- binary behavior
-- JSON rule for `files download`
-- file cleanup
-
-### Navigation
-
-Coverage:
-
-- create folder
-- list folders
-- get folder by UUID
-- get folder by exact name
-- update folder
-- move resource into folder
-- delete folder
-
-Assertions:
-
-- exact-name resolution
-- ambiguity failure on duplicate names
-- payload shape for `resources move`
-
-### Teamspace
-
-Coverage:
-
-- create folder
-- list folders
-- get folder by UUID
-- get folder by exact name
-- `--include-resources`
-- update folder
-- publish resource
-- unpublish resource
-- delete folder
-
-Assertions:
-
-- exact-name resolution
-- ambiguity handling
-- publish/unpublish payload shape
-
-### Displays
-
-Coverage:
-
-- create display
-- list/get/update/delete display
-- get/update layout
-- create/update/delete tab
-- list/get/create/update/delete variable
-- list/get/create/update/delete widget
-- create/update/delete navigation target
-- get/set/delete cross-widget filter
-
-Assertions:
-
-- generic `widgets create/update --type`
-- basic widget payload shaping
-- display subresource access through the real binary
-
-### Automations
-
-Coverage:
-
-- folder list/create/update/delete/move
-- automation list/get/create/update/delete
-- activate/deactivate
-- trigger get/set
-- actions list/add/update/delete
-- flow get/set
-- webhook get/set/delete
-- plugins list/get
-- connections list/get/create/update/delete
-
-Assertions:
-
-- generic trigger/action `--type`
-- flow transitions payload shape
-- connection config/secret behavior
-
-## Cross-Domain Scenarios
-
-These scenarios validate integration between domains, not just isolated endpoints.
-
-Recommended flows:
-
-### Flow 1: Schema to Records to Comments
-
-- create schema
-- create fields
-- create record
-- query record
-- add comment
-- delete comment parent resource chain in cleanup
-
-### Flow 2: Schema to Navigation to Teamspace
-
-- create schema
-- move schema into navigation folder
-- publish schema into teamspace folder
-- unpublish schema
-- cleanup
-
-### Flow 3: Display Built on Schema
-
-- create schema
-- create display
-- create variable referencing schema
-- create widget using display `--type`
-- add navigation target or cross-widget filter
-- cleanup
-
-### Flow 4: Automation Around Schema
-
-- create schema
-- create automation with record-based trigger
-- add action referencing schema
-- set flow
-- activate/deactivate
-- cleanup
-
-## Data and Cleanup Strategy
-
-The E2E harness should maintain a run-scoped resource registry.
-
-Recommended tracked resource categories:
-
-- schemas
-- records
-- comments if necessary
-- files
-- navigation folders
-- teamspace folders
-- displays
-- automations
-- automation folders
-- automation connections
-
-Cleanup order should be dependency-aware:
-
-1. automation webhooks / actions / flows if needed
-2. automations
-3. displays
-4. teamspace publications
-5. navigation placements
-6. records
-7. files
-8. schemas
-9. folders / connections
-
-## Proposed Test Harness Shape
-
-Recommended structure:
-
-```text
-e2e/
-  helpers/
-    cli.ts
-    config.ts
-    ids.ts
-    cleanup.ts
-    json.ts
-  preflight.test.ts
-  contract.test.ts
-  schemas.test.ts
-  records-comments.test.ts
-  files.test.ts
-  navigation.test.ts
-  teamspace.test.ts
-  displays.test.ts
-  automations.test.ts
-  integration-flows.test.ts
-```
-
-### Helper Responsibilities
-
-`helpers/cli.ts`
-
-- run `node dist/index.js ...`
-- capture stdout, stderr, exit code
-- expose helpers for JSON mode and text mode
-
-`helpers/config.ts`
-
-- resolve local profile assumptions
-- optionally enforce `local` profile for test runs
-
-`helpers/ids.ts`
-
-- generate unique test ids and names
-
-`helpers/cleanup.ts`
-
-- track created resources
-- run cleanup in reverse order
-
-`helpers/json.ts`
-
-- parse and assert `{ data, meta }`
-- parse and assert `{ error, meta }`
-
-## Scripts
-
-Recommended future scripts:
-
-```json
-{
-  "e2e:smoke": "...",
-  "e2e:standard": "...",
-  "e2e:full": "..."
-}
-```
-
-The exact runner can be decided during implementation, but it should remain compatible with the current project tooling.
-
-## Recommended Implementation Order
-
-Build the E2E battery in this order:
-
-1. preflight helpers and CLI runner
-2. contract/global behavior tests
-3. schemas
-4. records/comments
-5. files
-6. navigation/teamspace
-7. displays
-8. automations
-9. cross-domain flows
-10. smoke/standard/full orchestration
-
-## Success Criteria
-
-The E2E battery is successful when:
-
-- it runs against the real `local` profile
-- it creates and cleans up real test resources
-- it validates both success and failure envelopes
-- it covers the implemented command surface across all domains
-- it can be run in at least smoke and standard modes