zinkee 0.1.2 → 0.1.7

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

@@ -0,0 +1,307 @@
+# Zinkee CLI E2E Status
+
+Estado de pruebas E2E reales ejecutadas contra el perfil `local` de:
+
+- `/Users/david/.config/zinkee/config.toml`
+
+Las pruebas se han lanzado contra el binario real:
+
+```bash
+node dist/index.js ...
+```
+
+## Preflight y Contrato Global
+
+- [x] `node dist/index.js --json config validate`
+- [x] `node dist/index.js --json --profile local profiles get local`
+- [x] `node dist/index.js --json --profile local schemas list`
+- [x] `--read-only` bloquea escrituras con `exitCode = 7`
+- [x] `--example` validado en E2E real
+- [x] errores JSON validados en más casos representativos
+
+Notas transversales:
+
+- `--example` está validado en real, pero la cobertura es irregular: por ejemplo `automations create`, `schemas fields create` y `navigation resources move` sí tienen ejemplo, mientras `schemas get`, `records update`, `files upload`, `teamspace folders create`, `automations folders create`, `automations webhook set` y `automations connections create` no.
+- `--json` no se respeta en todos los errores: fallos de runtime sí devuelven `{ error, meta }`, pero errores de parseo/Commander como `schemas get` sin argumento siguen saliendo en texto plano.
+- muchos `400`/`404` siguen colapsando a `code="unknown_error"` aunque el backend sí devuelve JSON estructurado con `reason`, `action`, `requestId` y `timestamp`; la CLI está perdiendo esa información.
+- la ayuda global anuncia `--example` sin explicar bien la ruta de comando esperada, así que desde fuera hay algo de prueba y error.
+
+## Files E2E
+
+Estado: `PASS`
+
+Recursos usados:
+
+- `0349c88d-65e0-40a4-b8f5-72025de79308`
+- `5cbaacc7-0b5e-43d5-893f-22eb5826e0f4`
+
+- [x] upload
+- [x] storage info
+- [x] download binario
+- [x] `--json --output`
+- [x] delete
+- [x] cleanup remoto
+- [x] cleanup local
+
+## Navigation E2E
+
+Estado: `PASS`
+
+Run id:
+
+- `e2e-nav-20260324203721-22108`
+
+Recursos usados:
+
+- folder id: `506bba9e-2756-40f0-a58d-3588c6fee35e`
+
+- [x] create folder
+- [x] get folder por UUID
+- [x] get folder por nombre exacto
+- [x] update folder
+- [x] move resource
+- [x] delete folder
+- [x] cleanup correcto
+
+## Teamspace E2E
+
+Estado: `PASS_WITH_CONCERNS`
+
+Run id:
+
+- `e2e-team-20260324203721-31756`
+
+Recursos usados:
+
+- folder id: `e7ec8dc8-0e5a-4c52-b019-3433557b116a`
+
+- [x] create folder
+- [x] list folders
+- [x] list con `--include-resources`
+- [x] get folder por UUID
+- [x] get folder por nombre exacto
+- [x] update folder
+- [x] publish resource
+- [x] unpublish resource
+- [x] delete folder
+- [x] cleanup correcto
+- [x] `folders get` devuelve el recurso completo
+
+Nota:
+
+- el comando `teamspace folders get` está devolviendo el selector resuelto (`{ kind, value }`) en vez del recurso de carpeta completo
+
+## Schemas E2E
+
+Estado: `PARTIAL`
+
+Run útil observado:
+
+- `e2e-schema-20260324193743-256e46`
+
+Recursos observados:
+
+- schema id: `4d90b9e8-3f1f-411e-9ed9-b2b92bdef3a0`
+- field ids:
+  - `d1d8fd9a-5646-4453-b0d8-af9466211463`
+  - `13cd6117-3fe0-4408-81f7-71368bfb2475`
+
+- [x] create schema
+- [x] get schema por slug
+- [x] get schema por UUID
+- [x] create field sin `config`
+- [x] create field en schema temporal
+- [x] list fields
+- [x] get field
+- [x] update field sin `config`
+- [x] update field en schema temporal
+- [x] update schema
+- [x] delete field
+- [x] delete schema
+- [ ] create field con `config`
+
+Fallos observados:
+
+- `schemas fields create` con `config` devuelve `400`
+- el backend responde `reason=schema_field_create_request_invalid`, pero la CLI lo aplana a `unknown_error`
+
+## Records E2E
+
+Estado: `PARTIAL`
+
+Schema real usado:
+
+- `contacts`
+- id: `2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e`
+
+Records temporales usados:
+
+- `038efec2-73ef-4f7a-a8fe-b30990ff923e`
+- `76d5fdce-5bfa-4a0d-809b-ab6d97237c99`
+
+- [x] create record sobre schema real existente
+- [x] delete record sobre schema real existente
+- [x] create record sobre schema temporal recién creado
+- [ ] query real sobre schema temporal
+- [x] update real sobre schema temporal
+- [x] delete real sobre schema temporal
+
+Nota:
+
+- el rojo anterior de `records create` sobre schema temporal ya no reproduce tras los últimos fixes
+- `records create` y `records query` siguen fallando si se usa el slug del schema temporal aunque la ayuda diga `schema uuid or slug`
+- el backend responde `reason=schema_id_invalid` y pide UUID real en el path `schemaId`; no es un slug que resuelva la CLI en esas rutas
+- `records query` sobre schema temporal funciona por UUID y con `--where`, pero sin filtro devolvió `data: []` aunque el record existía
+
+## Comments E2E
+
+Estado: `PASS`
+
+- [x] list comments sobre record real
+- [x] create comment sobre record real
+- [x] create comment sobre schema `commentable`
+- [x] list comment en schema de prueba
+
+## Displays E2E
+
+Estado: `PARTIAL`
+
+Run id:
+
+- `e2e-disp-20260324203805-21463`
+
+Recursos usados:
+
+- display id: `1cf8e169-22cc-42ce-9f9f-9908fc2f9a00`
+- variable id: `a6f156ab-8394-4315-ba33-d268eec2fffe`
+
+- [x] create display
+- [x] get display
+- [x] get layout
+- [x] create tab con layout compatible (`side_tabs_widgets`)
+- [x] create variable
+- [x] create widget con `--type table`
+- [x] delete variable
+- [x] delete created tab
+- [x] delete created widget
+- [x] list widgets
+- [x] get widget
+- [x] list tabs
+- [x] update display
+- [x] update layout
+- [ ] create tab en más layouts válidos
+- [x] update tab
+- [x] delete tab
+- [x] list/get/update variable completo
+- [x] update widget
+- [x] delete widget
+- [x] navigation-targets lifecycle
+- [x] cross-widget-filter lifecycle
+- [x] delete display con cleanup correcto
+
+Fallos observados:
+
+- `displays tabs create` devuelve `400` fuera del caso validado `side_tabs_widgets`; en real siguió fallando en `widget_row_tabs` y `top_bar_tabs`
+
+Nota:
+
+- `displays widgets create` ya funciona para el caso `--type table`
+- `displays tabs create` ya funciona para `side_tabs_widgets`
+- los intentos `chart`/`text` siguen sin validarse en real
+- `displays delete` ya no reproduce el `500`; en esta tanda el cleanup real quedó OK
+
+## Automations E2E
+
+Estado: `PARTIAL`
+
+- [x] folders list
+- [x] folders create
+- [x] folders update
+- [x] folders delete
+- [x] folders move
+- [x] automations list
+- [x] automations get
+- [ ] automations create
+- [ ] automations update
+- [x] automations delete
+- [x] activate
+- [x] deactivate
+- [x] trigger get
+- [ ] trigger set
+- [x] actions list
+- [x] actions add
+- [ ] actions update
+- [x] actions delete
+- [x] flow get
+- [x] flow set
+- [x] webhook get
+- [x] webhook set
+- [x] webhook delete
+- [x] plugins list
+- [x] plugins get
+- [x] connections list
+- [x] connections get
+- [ ] connections create
+- [x] connections update
+- [x] connections delete
+
+- [x] read-only block on folder writes
+- [x] reversible activate/deactivate on existing test automation
+
+Fallos observados:
+
+- `automations create` devuelve `400` con `reason=automation_create_payload_invalid`
+- `automations update` devuelve `200` pero no aplica la mutación observada en real
+- `trigger set`, `actions update` y `connections create` siguen devolviendo `4xx` genéricos en las rutas probadas
+
+Nota:
+
+- varias rutas write solo fueron utilizables de forma fiable con `--raw`: `actions add`, `webhook set` y `connections update`
+- `connections update` ya no parece romper el parser en la forma `--set path=value`, pero la mutación es parcial: `name` sí cambia y `config.headerName` no
+- `automations update` manda `PATCH` con `{"name","description"}`, pero el backend devuelve el recurso con `name` y `description` originales
+
+## Flujos Cruzados
+
+- [x] schema -> record -> comment
+- [x] schema -> navigation -> teamspace
+- [x] schema -> display
+- [ ] schema -> automation
+
+Notas:
+
+- `schema -> navigation -> teamspace` quedó validado con schema temporal `e964e712-ec1d-43ca-98a0-55c3631114d4`, folder de navigation `ff639d7d-a715-47e7-b626-240656a5fbad` y folder de teamspace `21807303-d9da-445d-a08e-cebcd9c49535`
+- `schema -> display` quedó validado creando un widget table sobre un schema temporal en display `1ebcc70c-1513-4e5c-b3fe-0e9874506e25`
+- `schema -> automation` sigue bloqueado porque `automations create` devolvió `400` también con `--trigger-type record_created --trigger-schema <uuid>`
+
+## Prioridad Recomendada
+
+- [x] arreglar `schemas get` por slug
+- [x] arreglar `schemas fields update`
+- [x] arreglar `comments create`
+- [x] arreglar `records create` sobre schema temporal
+- [ ] arreglar `schemas fields create` con `config`
+- [x] probar `comments create` sobre schema realmente `commentable` como flujo dedicado
+- [x] arreglar `displays delete`
+- [ ] ampliar `displays tabs` más allá del caso compatible ya validado
+- [ ] ampliar `displays widgets` más allá del caso compatible ya validado
+- [ ] cerrar E2E de `automations` en `create/update/trigger/actions/connections` sin depender de `--raw`
+
+## Estado Global
+
+- [x] CLI funcional y estable en local
+- [x] binario real validado
+- [x] varios dominios con E2E verde real
+- [x] fallos actuales ya son de integración real, no de scaffolding
+
+## Bloqueos Reales Pendientes
+
+- [ ] `schemas fields create` con `config`
+  - en real devuelve `400` para `POST /api/v2/schemas/{id}/fields` con `reason=schema_field_create_request_invalid`
+- [ ] `automations create`
+  - en real devuelve `400` con `reason=automation_create_payload_invalid` incluso con payload alineado con la ayuda y con el ejemplo expuesto por la CLI
+- [ ] `automations update`
+  - en real devuelve `200`, pero el objeto sale sin los cambios observados
+- [ ] `records create/query` con slug
+  - en real devuelve `400` con `reason=schema_id_invalid`; esas rutas del backend exigen UUID real en `schemaId`
+- [ ] `automations connections update` para paths anidados
+  - en real acepta el patch y actualiza campos planos como `name`, pero ignora claves anidadas como `config.headerName`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.2",
+  "version": "0.1.7",
   "description": "CLI for Zinkee API v2",
   "type": "module",
   "bin": {

package/src/api/logs.ts

@@ -0,0 +1,34 @@
+import { ApiClient } from "../client.js";
+import type { NormalizedUuidOrSlug } from "../parsers/selectors.js";
+
+export interface ApiLogChange {
+  beforeValue?: string | null;
+  afterValue?: string | null;
+  author?: string;
+  operation?: string;
+}
+
+export interface ApiLog {
+  [key: string]: unknown;
+  recordId?: string;
+  timestamp?: string;
+  changeField?: string;
+  change?: ApiLogChange;
+}
+
+function selectorValue(selector: NormalizedUuidOrSlug): string {
+  return selector.value;
+}
+
+export class LogsApi {
+  constructor(private readonly client: ApiClient) {}
+
+  listLogs(
+    schema: NormalizedUuidOrSlug,
+    recordId: string,
+  ): Promise<ApiLog[]> {
+    return this.client.getJson<ApiLog[]>(
+      `/api/v2/schemas/${selectorValue(schema)}/records/${recordId}/logs`,
+    );
+  }
+}

package/src/cli-examples.ts

@@ -171,5 +171,12 @@ export async function showExamples(
         writer.write(`     ${line}\n`);
       }
     }
+
+    if (example.response) {
+      writer.write("   Example response:\n");
+      for (const line of example.response.split("\n")) {
+        writer.write(`     ${line}\n`);
+      }
+    }
   }
 }

package/src/command-registry.ts

@@ -679,6 +679,13 @@ export const commandRegistry = {
     supportsRaw: true,
     output: writeOutput,
   },
+  "logs list": {
+    command: "logs list",
+    accessLevel: "read",
+    supportsExample: true,
+    supportsRaw: false,
+    output: readOutput,
+  },
   "teamspace folders list": {
     command: "teamspace folders list",
     accessLevel: "read",

package/src/commands/logs.test.ts

@@ -0,0 +1,123 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { buildProgram } from "../index.js";
+
+function createTempConfig(contents: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "zinkee-logs-"));
+  const filePath = join(dir, "config.toml");
+  writeFileSync(filePath, contents, "utf8");
+  return filePath;
+}
+
+function createApiConfig(): string {
+  return createTempConfig(`
+default_profile = "prod"
+
+[profiles.prod]
+api_key = "logs-token-1234"
+base_url = "https://api.zinkee.test"
+`);
+}
+
+function createStdoutBuffer() {
+  let output = "";
+
+  return {
+    stdout: {
+      write(chunk: string) {
+        output += chunk;
+        return true;
+      },
+    },
+    read() {
+      return output;
+    },
+  };
+}
+
+function jsonResponse(body: unknown, status: number = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+    },
+  });
+}
+
+function createFetchMock() {
+  const fetchMock = vi.fn<typeof fetch>();
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("logs commands", () => {
+  it("registers the logs command group", () => {
+    const program = buildProgram();
+
+    expect(program.commands.some((command) => command.name() === "logs")).toBe(true);
+  });
+
+  it("lists logs for a record and lowercases the record uuid in the path", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse([
+        {
+          recordId: "550e8400-e29b-41d4-a716-446655440001",
+          timestamp: "2026-04-22T10:00:00Z",
+          changeField: "",
+          change: {
+            beforeValue: null,
+            afterValue: null,
+            author: "developer@zinkee.com",
+            operation: "CREATE",
+          },
+        },
+      ]),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "logs",
+      "list",
+      "contacts",
+      "550E8400-E29B-41D4-A716-446655440001",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/contacts/records/550e8400-e29b-41d4-a716-446655440001/logs",
+    );
+    expect(fetchMock.mock.calls[0]?.[1]?.method ?? "GET").toBe("GET");
+    expect(JSON.parse(output.read())).toEqual({
+      data: [
+        {
+          recordId: "550e8400-e29b-41d4-a716-446655440001",
+          timestamp: "2026-04-22T10:00:00Z",
+          changeField: "",
+          change: {
+            beforeValue: null,
+            afterValue: null,
+            author: "developer@zinkee.com",
+            operation: "CREATE",
+          },
+        },
+      ],
+      meta: {
+        command: "logs list",
+      },
+    });
+  });
+});

package/src/commands/logs.ts

@@ -0,0 +1,159 @@
+import type { Writable } from "node:stream";
+
+import { Command, InvalidArgumentError } from "commander";
+
+import { LogsApi } from "../api/logs.js";
+import { ApiClient } from "../client.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
+import {
+  normalizeUuidOrSlug,
+  type NormalizedUuidOrSlug,
+} from "../parsers/selectors.js";
+import { resolveRuntimeContext } from "../runtime-context.js";
+import type { JsonObject, RuntimeOverrides } from "../types.js";
+import { CliError } from "../utils/errors.js";
+import { buildJsonSuccess, printTable } from "../utils/output.js";
+
+interface CommandIo {
+  write(chunk: string): unknown;
+}
+
+export interface RegisterLogsCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions extends RuntimeOverrides {}
+
+function getCommandIo(stdout: CommandIo | undefined): CommandIo {
+  return stdout ?? (process.stdout as Writable);
+}
+
+function writeLine(stdout: CommandIo, value: string): void {
+  stdout.write(`${value}\n`);
+}
+
+function getGlobalOptions(command: Command): GlobalOptions {
+  return command.optsWithGlobals<GlobalOptions>();
+}
+
+function emitJson(
+  stdout: CommandIo,
+  commandName: string,
+  data: unknown,
+  ..._extra: unknown[]
+): void {
+  writeLine(
+    stdout,
+    JSON.stringify(buildJsonSuccess(data, { command: commandName })),
+  );
+}
+
+function toConfigurationError(filePath: string, error: unknown): never {
+  if (error instanceof CliError) {
+    throw error;
+  }
+
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  ) {
+    throw new CliError("configuration_error", `Config file not found at ${filePath}.`);
+  }
+
+  if (error instanceof Error) {
+    throw new CliError("configuration_error", error.message);
+  }
+
+  throw error;
+}
+
+function createLogsApi(
+  command: Command,
+  filePath: string,
+): { api: LogsApi; json: boolean } {
+  try {
+    const config = readRuntimeConfig(filePath);
+    const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
+
+    if (!runtime.baseUrl) {
+      throw new CliError(
+        "configuration_error",
+        `Resolved profile "${runtime.profile}" is missing a base URL.`,
+      );
+    }
+
+    return {
+      api: new LogsApi(
+        new ApiClient({
+          baseUrl: runtime.baseUrl,
+          apiKey: runtime.apiKey,
+        }),
+      ),
+      json: runtime.json,
+    };
+  } catch (error) {
+    toConfigurationError(filePath, error);
+  }
+}
+
+function parseUuidOrSlugSelector(input: string): NormalizedUuidOrSlug {
+  try {
+    return normalizeUuidOrSlug(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid selector.";
+    throw new InvalidArgumentError(message);
+  }
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toTableRows(data: unknown): Record<string, unknown>[] {
+  if (Array.isArray(data)) {
+    return data.map((entry) => (isJsonObject(entry) ? entry : { value: entry }));
+  }
+
+  if (isJsonObject(data)) {
+    return [data];
+  }
+
+  return [{ value: data }];
+}
+
+function emitTable(stdout: CommandIo, data: unknown): void {
+  printTable(toTableRows(data), undefined, stdout);
+}
+
+export function registerLogsCommands(
+  program: Command,
+  options: RegisterLogsCommandsOptions = {},
+): void {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const logs = program.command("logs").description("Inspect record change logs");
+
+  logs
+    .command("list")
+    .description("List change logs for a record")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .argument("<record>", "record uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      record: NormalizedUuidOrSlug,
+    ) {
+      const { api, json } = createLogsApi(this, filePath);
+      const data = await api.listLogs(schema, record.value);
+
+      if (json) {
+        emitJson(stdout, "logs list", data, filePath);
+        return;
+      }
+
+      emitTable(stdout, data);
+    });
+}