zinkee 0.1.44 → 0.1.46

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

@@ -1,1576 +0,0 @@
-# Zinkee CLI Design
-
-## Context
-
-This repository will host a new CLI for Zinkee that replaces a previous, outdated CLI.
-
-The new CLI must:
-
-- target Zinkee Public API v2
-- be designed for general users but especially optimized for AI agents
-- follow the same stack and a very similar project structure to the reference CLI in `/Users/david/dev/pichardo-projects/store-manager`
-- preserve compatibility with the existing user configuration file at `/Users/david/.config/zinkee/config.toml`
-
-This document captures the design decisions agreed during the analysis and specification phase before implementation starts.
-
-## Source References
-
-Primary references used for this design:
-
-- Reference CLI: `/Users/david/dev/pichardo-projects/store-manager`
-- Zinkee backend API v2: `/Users/david/dev/z2/z2-backend/api`
-- Public docs: `doc.zinkee.com`
-
-## Design Direction
-
-The CLI will be:
-
-- resource-oriented, not endpoint-oriented
-- complete across all Zinkee API v2 domains
-- optimized for legible command flags first
-- compatible with advanced JSON payload injection where needed
-- safe to run in read-only environments used by AI agents
-
-The implementation may later be executed by domain, but the specification covers the full CLI surface from the start.
-
-## Global Contract
-
-### Command Shape
-
-The CLI will use this general structure:
-
-```bash
-zinkee [global-options] <domain> <command> [args] [options]
-```
-
-### Top-Level Domains
-
-Proposed top-level command groups:
-
-- `config`
-- `profiles`
-- `schemas`
-- `records`
-- `comments`
-- `files`
-- `navigation`
-- `teamspace`
-- `displays`
-- `automations`
-
-### Global Options
-
-Initial global options agreed so far:
-
-- `--profile <name>`: select a profile from config
-- `--base-url <url>`: override the profile base URL for the current invocation
-- `--api-key <token>`: override the profile API key for the current invocation
-- `--json`: return stable JSON output for agents
-- `--read-only`: block any command classified as write or destructive
-- `--verbose`: show richer operational context
-- `--debug`: print low-level debugging context
-- `--no-color`: disable colored terminal output
-
-### Output Model
-
-Agreed output behavior:
-
-- default output format is `table`
-- `--json` enables stable machine-readable output for agents
-- JSON output should prefer a stable envelope over raw backend passthrough
-
-Target JSON shape:
-
-```json
-{
-  "data": {},
-  "meta": {}
-}
-```
-
-The exact envelope can be refined later, but the contract should remain stable for agents.
-
-### Examples
-
-The CLI should expose example usage directly from commands.
-
-Agreed convention:
-
-- `--help` explains the command contract
-- `--example` prints one or more realistic command examples
-- `--json --example` should return examples in a structured format suitable for agents
-
-Rules:
-
-- every command should have at least one example
-- complex commands should expose multiple examples
-- examples should use realistic values instead of placeholder noise
-
-## Configuration Compatibility
-
-The new CLI must preserve compatibility with the existing config file:
-
-- `/Users/david/.config/zinkee/config.toml`
-
-Observed current shape:
-
-```toml
-default_profile = "default"
-
-[profiles.default]
-api_key = ""
-
-[profiles.local]
-api_key = "..."
-base_url = "http://localhost:8088"
-```
-
-### Compatibility Rules
-
-Agreed rules:
-
-- the current TOML format must continue working without migration
-- new optional keys may be added in the future
-- existing keys must not be broken or reinterpreted incompatibly
-- `default_profile` remains the default profile selector
-
-The new CLI may extend the config format with optional fields later, but backward compatibility is mandatory.
-
-## Read-Only Execution Model
-
-AI agents are expected to run the CLI in read-only mode in many deployments.
-
-The agreed design is:
-
-- read-only is an execution context, not a persisted profile property
-- it should be enabled globally per invocation
-- it should not be stored in `config.toml`
-
-### Read-Only Activation
-
-Agreed activation mechanisms:
-
-- global CLI flag: `--read-only`
-- optional environment variable: `ZINKEE_READ_ONLY=1`
-
-Resolution precedence:
-
-1. CLI flag
-2. environment variable
-3. default behavior: read-write
-
-### Command Access Levels
-
-Every command will be classified internally as one of:
-
-- `read`
-- `write`
-- `destructive`
-
-Behavior:
-
-- read-only mode allows only `read`
-- `write` and `destructive` commands fail before calling the API
-
-Example error:
-
-```text
-Error: Command "records create" is not allowed in read-only mode.
-```
-
-Example JSON error:
-
-```json
-{
-  "error": {
-    "code": "command_not_allowed_in_read_only_mode",
-    "message": "Command \"records create\" is not allowed in read-only mode.",
-    "commandMode": "write",
-    "executionMode": "read-only"
-  }
-}
-```
-
-## UX Philosophy
-
-Core UX decisions agreed so far:
-
-- the primary interface should use legible flags
-- `--raw` is a fallback for advanced or highly structured payloads
-- the CLI should optimize for agent clarity, not just HTTP completeness
-- the CLI should be complete across all supported v2 domains
-- there is no rush to ship a partial CLI if the contract is not well designed yet
-
-## Pending Sections
-
-The following sections still need to be specified in detail:
-
-- examples policy per domain
-- implementation phasing by domain
-
-## Domain Surface: Core Resources
-
-This section defines the first functional block of the CLI contract:
-
-- `config`
-- `profiles`
-- `schemas`
-- `records`
-- `comments`
-
-These domains establish the naming and command patterns that the rest of the CLI should follow.
-
-### Profiles and Config
-
-The CLI should separate profile management from generic configuration utilities.
-
-#### `profiles`
-
-Proposed commands:
-
-- `profiles list`
-- `profiles get <profile>`
-- `profiles use <profile>`
-- `profiles add <profile> --api-key <token> [--base-url <url>]`
-- `profiles update <profile> [--api-key <token>] [--base-url <url>]`
-- `profiles remove <profile>`
-
-Responsibilities:
-
-- manage `profiles.<name>` blocks in `config.toml`
-- update `default_profile` when `profiles use` is called
-- preserve backward compatibility with the existing TOML shape
-
-#### `config`
-
-Proposed commands:
-
-- `config path`
-- `config show`
-- `config validate`
-
-Responsibilities:
-
-- `config path`: print the effective config file path
-- `config show`: print the resolved config with secrets redacted by default
-- `config validate`: verify that the TOML is parseable and contains a resolvable profile configuration
-
-### Schemas
-
-The `schemas` domain should expose both schema management and field management.
-
-#### Schema Commands
-
-Proposed commands:
-
-- `schemas list`
-- `schemas get <schema>`
-- `schemas create --name <name> --slug <slug> [--auditable] [--commentable]`
-- `schemas update <schema> [--name <name>] [--slug <slug>] [--auditable <bool>] [--commentable <bool>]`
-- `schemas delete <schema>`
-
-#### Schema Field Commands
-
-Proposed commands:
-
-- `schemas fields list <schema>`
-- `schemas fields get <schema> <field>`
-- `schemas fields create <schema> --type <type> --slug <slug> --label <label> [field-config-options]`
-- `schemas fields update <schema> <field> [--label <label>] [--required <bool>] [field-config-options]`
-- `schemas fields delete <schema> <field>`
-
-#### Identifier Rules
-
-Agreed identifier resolution rules:
-
-- `<schema>` should accept either UUID or slug
-- `<field>` should accept either UUID or slug
-- if the value parses as UUID, resolve as UUID
-- otherwise resolve as slug
-
-This makes the CLI friendlier than a UUID-only interface while preserving direct access to exact identifiers.
-
-### Records
-
-Although records are nested under schemas in the HTTP API, the CLI should expose them as a top-level domain because they are a primary workflow surface for both users and agents.
-
-#### Record Commands
-
-Proposed commands:
-
-- `records list <schema>`
-- `records query <schema>`
-- `records get <schema> <record>`
-- `records create <schema> ...`
-- `records update <schema> <record> ...`
-- `records delete <schema> <record>`
-
-#### `records list`
-
-`records list` should provide a lightweight listing/query surface for common use cases.
-
-Proposed flags:
-
-- `--select <fields>` where fields are comma-separated
-- `--sort <field:direction>`
-- `--limit <n>`
-- `--offset <n>`
-
-#### `records query`
-
-`records query` should be the richer query surface for advanced search and filtering.
-
-Proposed flags:
-
-- `--select <fields>`
-- `--where <expression>` repeatable
-- `--sort <field:direction>` repeatable or comma-separated
-- `--limit <n>`
-- `--offset <n>`
-- `--raw <json>`
-- `--raw-file <path>`
-
-Example expressions to support:
-
-- `--where "status eq active"`
-- `--where "email contains @acme.com"`
-- `--where "amount gt 1000"`
-- `--where "closedAt is-null"`
-- `--where "ownerId in a,b,c"`
-
-`records list` and `records query` should share the same internal execution path, with `list` acting as the simpler contract.
-
-#### `records get`
-
-Proposed command:
-
-- `records get <schema> <record>`
-
-Identifier rule:
-
-- `<record>` should be treated as UUID
-
-#### `records create`
-
-The main interface should be based on repeatable field assignment flags rather than requiring raw JSON for every write.
-
-Agreed write interface:
-
-- `--set <field=value>` repeatable
-- `--set-json <field=json>` repeatable
-- `--raw <json>`
-- `--raw-file <path>`
-
-Example:
-
-```bash
-zinkee records create contacts --set name="Ana" --set email="ana@acme.com"
-```
-
-#### `records update`
-
-The update interface should support assignment, removal, and structured values.
-
-Agreed update interface:
-
-- `--set <field=value>` repeatable
-- `--set-json <field=json>` repeatable
-- `--unset <field>` repeatable
-- `--raw <json>`
-- `--raw-file <path>`
-
-Example:
-
-```bash
-zinkee records update contacts 550e8400-e29b-41d4-a716-446655440000 --set status=active --unset legacyCode
-```
-
-#### `records delete`
-
-Proposed command:
-
-- `records delete <schema> <record>`
-
-### Comments
-
-Comments should be exposed as a top-level domain, while still following the schema/record context model of the backend.
-
-#### Comment Commands
-
-Proposed commands:
-
-- `comments list <schema> <record>`
-- `comments create <schema> <record> --text <text>`
-
-#### Comment Write Contract
-
-The initial user-friendly interface should be text-first:
-
-- `--text <text>` for standard comments
-- `--raw <json>` and `--raw-file <path>` for future typed content extensions
-
-This keeps the common case simple while preserving compatibility with richer comment payloads if the backend evolves.
-
-### Naming Conventions Agreed in This Section
-
-The following naming rules are now part of the design:
-
-- prefer simple verbs: `list`, `get`, `create`, `update`, `delete`
-- use `query` only for operations that are materially richer than `list`
-- accept friendly selectors such as slugs wherever the domain supports them
-- avoid mirroring awkward HTTP route naming when a clearer CLI contract exists
-
-## Domain Surface: Files, Navigation, Teamspace
-
-This section defines the next functional block:
-
-- `files`
-- `navigation`
-- `teamspace`
-
-These domains mix CRUD operations with more action-oriented workflows such as moving, publishing, unpublishing, and downloading.
-
-### Files
-
-The backend exposes upload, storage info, download, and delete capabilities. The CLI should model them in a more intention-oriented shape.
-
-#### File Commands
-
-Proposed commands:
-
-- `files upload <path>`
-- `files download <file> [--output <path>]`
-- `files delete <file>`
-- `files storage`
-
-#### File Design Rules
-
-Agreed rules:
-
-- `<file>` should accept UUID
-- `files upload <path>` is the canonical upload form
-- `files storage` is preferred over a more HTTP-shaped name like `storage-info`
-
-Reasoning:
-
-- `files download` should represent binary content retrieval
-- the CLI should not blur binary download behavior into normal JSON output semantics
-
-#### Binary Output Rule
-
-When `files download` is used:
-
-- default behavior should write bytes to stdout or to a provided output path, depending on the final CLI policy chosen later
-- `--json` should not emit raw binary
-- if needed, `--json` should require `--output` and return structured metadata about the download result
-
-### Navigation
-
-The navigation domain represents internal workspace organization.
-
-The CLI should structure it around folders and resource moves rather than around backend payload shapes.
-
-#### Navigation Commands
-
-Proposed commands:
-
-- `navigation folders list`
-- `navigation folders get <folder>`
-- `navigation folders create --name <name> [--order <n>] [--props <json>]`
-- `navigation folders update <folder> [--name <name>] [--order <n>] [--props <json>]`
-- `navigation folders delete <folder>`
-- `navigation resources move <resource> --type <type> --to <folder>`
-
-#### Navigation Design Rules
-
-Agreed rules:
-
-- expose `folders` and `resources` as explicit subtrees
-- support `navigation folders get <folder>` in the CLI even if implemented internally via list resolution
-- use `--props` or `--props-file` rather than exposing the backend term `additionalProperties` directly
-- resource moves should be modeled in terms of source resource plus destination folder
-
-Example:
-
-```bash
-zinkee navigation resources move 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --type schema --to "Sales"
-```
-
-### Teamspace
-
-The teamspace domain is conceptually similar to navigation, but semantically distinct because it governs published/shared resources rather than internal workspace organization.
-
-#### Teamspace Commands
-
-Proposed commands:
-
-- `teamspace folders list [--include-resources]`
-- `teamspace folders get <folder> [--include-resources]`
-- `teamspace folders create --name <name> [--order <n>] [--props <json>]`
-- `teamspace folders update <folder> [--name <name>] [--order <n>] [--props <json>]`
-- `teamspace folders delete <folder>`
-- `teamspace resources publish <resource> --to <folder>`
-- `teamspace resources unpublish <resource>`
-
-#### Teamspace Design Rules
-
-Agreed rules:
-
-- use `folders` and `resources` as the main subtrees
-- expose `--include-resources` instead of backend-style query values such as `include=resources`
-- use `publish` and `unpublish` directly as verbs
-- if backend ambiguity requires it later, resource type may be added explicitly, but it is not part of the default CLI contract for now
-
-Example:
-
-```bash
-zinkee teamspace folders list --include-resources
-zinkee teamspace resources publish 0f6f062f-1478-4df2-96a1-c495d037d260 --to "Customer Success"
-zinkee teamspace resources unpublish 0f6f062f-1478-4df2-96a1-c495d037d260
-```
-
-### Naming Conventions Agreed in This Section
-
-The following rules are now part of the design:
-
-- use `download` explicitly for binary retrieval
-- use `folders` and `resources` as subtrees for organization domains
-- rename backend-specific payload names like `additionalProperties` into clearer CLI flags such as `--props`
-- prefer intention-driven verbs like `move`, `publish`, and `unpublish` over backend route naming
-
-## Domain Surface: Displays
-
-The `displays` domain is a composed resource area with nested subresources and multiple configuration sections. The CLI should expose it through a stable hierarchy while keeping the most common operations legible.
-
-### Display Commands
-
-Proposed top-level commands:
-
-- `displays list`
-- `displays get <display>`
-- `displays create --name <name> --template <template>`
-- `displays update <display> [--name <name>]`
-- `displays delete <display>`
-
-### Display Layout Commands
-
-Proposed commands:
-
-- `displays layout get <display>`
-- `displays layout update <display> --template <template> [--freeform-layouts <json>] [--freeform-layouts-file <path>]`
-
-Design rule:
-
-- distinguish display-level layout from widget placement
-
-### Display Tab Commands
-
-Proposed commands:
-
-- `displays tabs list <display>`
-- `displays tabs create <display> [--name <name>] [--orientation <orientation>]`
-- `displays tabs update <display> <tab> [--name <name>] [--orientation <orientation>]`
-- `displays tabs delete <display> <tab>`
-
-Identifier rule:
-
-- `<tab>` should be treated as a string identifier, not assumed to be UUID
-
-### Display Variable Commands
-
-Proposed commands:
-
-- `displays variables list <display>`
-- `displays variables get <display> <variable>`
-- `displays variables create <display> --type <type> --name <name> [flags]`
-- `displays variables update <display> <variable> [flags]`
-- `displays variables delete <display> <variable>`
-
-#### Variable Flags
-
-Common flags:
-
-- `--type <type>`
-- `--name <name>`
-- `--allow-multiple`
-- `--static`
-- `--default <value>`
-- `--default-value <value>` repeatable
-
-Reference-variable flags:
-
-- `--source-schema <id>`
-- `--source-field <id>`
-- `--filter <expression>` repeatable
-
-Date-variable flags:
-
-- `--date-mode <mode>`
-- `--date-dynamic-option <option>`
-- `--date-specific <iso-date>`
-- `--date-range-start <iso-date>`
-- `--date-range-end <iso-date>`
-
-### Display Widget Commands
-
-Proposed commands:
-
-- `displays widgets list <display>`
-- `displays widgets get <display> <widget>`
-- `displays widgets create <display> --type <type> [flags]`
-- `displays widgets update <display> <widget> [flags]`
-- `displays widgets delete <display> <widget>`
-
-#### Widget Design Rule
-
-Agreed design:
-
-- use generic `widgets create/update` commands with `--type`
-- do not create a separate subcommand per widget type
-- use `--raw` as the fallback when widget configuration becomes too rich for the legible flags
-
-#### Widget Base Flags
-
-Common widget flags:
-
-- `--type table|detail|kpi|chart|timeline|kanban|hierarchy`
-- `--name <name>`
-- `--description <text>`
-- `--icon <icon>`
-- `--color <color>`
-- `--origin-resource <uuid>`
-- `--origin-subschema`
-- `--tab <tabId>`
-- `--slot <slotId>`
-- `--layout <json>`
-- `--layout-file <path>`
-
-View/query-oriented flags:
-
-- `--field <field>` repeatable
-- `--sort <field:direction>` repeatable
-- `--filter <expression>` repeatable
-
-Behavior flags:
-
-- `--widget-read-only`
-- `--hide-add-button`
-- `--hide-delete-button`
-- `--hide-sort-button`
-- `--hide-filter-button`
-- `--hide-see-button`
-
-KPI flags:
-
-- `--calc <type>`
-- `--calc-field <uuid>`
-- `--kpi-config <json>`
-
-Chart flags:
-
-- `--chart-type <type>`
-- `--x-axis-field <uuid>`
-- `--x-axis-date-format <granularity>`
-- `--x-axis-time-series`
-- `--y-axis-serie <json>` repeatable
-- `--legend <json>`
-
-### Display Navigation Target Commands
-
-Proposed commands:
-
-- `displays navigation-targets list <display>`
-- `displays navigation-targets create <display> --source-widget <id> --target-display <id> --target-variable <id> [--label <label>]`
-- `displays navigation-targets update <display> <target> [--source-widget <id>] [--target-display <id>] [--target-variable <id>] [--label <label>]`
-- `displays navigation-targets delete <display> <target>`
-
-Identifier rules:
-
-- `<target>` should be treated as a string identifier
-
-### Display Cross-Widget Filter Commands
-
-Proposed commands:
-
-- `displays cross-widget-filter get <display>`
-- `displays cross-widget-filter set <display> --source-widget <id> --source-field <id> --target <widgetId:fieldId>...`
-- `displays cross-widget-filter delete <display>`
-
-### Display Design Rules
-
-Agreed rules:
-
-- distinguish between display-level layout and widget placement
-- keep high-level operations flag-driven for common use cases
-- allow `--raw` and `--raw-file` for advanced configurations such as layout, widget internals, bindings, and rich chart/KPI config
-- model widgets generically with `--type` instead of one subcommand per widget type
-
-### Naming Conventions Agreed in This Section
-
-The following rules are now part of the design:
-
-- use nested subresources such as `layout`, `tabs`, `variables`, `widgets`, `navigation-targets`, and `cross-widget-filter`
-- treat tabs and navigation targets as non-UUID identifiers unless implementation later proves otherwise
-- model configuration-rich widgets with generic commands plus type-specific flags and raw JSON fallback
-
-## Domain Surface: Automations
-
-The `automations` domain contains folders, automation resources, trigger configuration, actions, flow wiring, webhook endpoints, plugins, and reusable connections. The CLI should expose these parts explicitly rather than hiding them inside a single opaque payload model.
-
-### Automation Folder Commands
-
-Proposed commands:
-
-- `automations folders list`
-- `automations folders create --name <name>`
-- `automations folders update <folder> --name <name>`
-- `automations folders delete <folder>`
-- `automations folders move <automation> --to <folder>`
-
-### Automation Commands
-
-Proposed commands:
-
-- `automations list [--folder <id>] [--status <status>] [--trigger-type <type>] [--action-type <type>] [--plugin <id>] [--search <text>]`
-- `automations get <automation>`
-- `automations create --name <name> [--description <text>] [--folder <id>] [trigger flags]`
-- `automations update <automation> [--name <name>] [--description <text>] [--folder <id>]`
-- `automations delete <automation>`
-- `automations activate <automation>`
-- `automations deactivate <automation>`
-
-Design rule:
-
-- `automations create` should support creating the resource together with its trigger, because the backend create contract already includes trigger configuration
-
-### Automation Trigger Commands
-
-Proposed commands:
-
-- `automations trigger get <automation>`
-- `automations trigger set <automation> [flags]`
-
-Supported trigger types:
-
-- `scheduled`
-- `record_created`
-- `record_changed`
-- `webhook`
-
-#### Trigger Flags
-
-Common:
-
-- `--trigger-type <type>`
-
-Scheduled:
-
-- `--cron <expression>`
-
-Record created:
-
-- `--trigger-schema <uuid>`
-- `--condition <field:comparator:value>` repeatable
-
-Record changed:
-
-- `--trigger-schema <uuid>`
-- `--trigger-field <uuid>` repeatable
-- `--condition <field:comparator:value>` repeatable
-
-Webhook:
-
-- `--webhook-endpoint-id <uuid>`
-
-Fallbacks:
-
-- `--raw <json>`
-- `--raw-file <path>`
-
-### Automation Action Commands
-
-Proposed commands:
-
-- `automations actions list <automation>`
-- `automations actions add <automation> --type <type> [flags]`
-- `automations actions update <automation> <action> [flags]`
-- `automations actions delete <automation> <action>`
-
-Supported action types:
-
-- `create_record`
-- `update_record`
-- `search_records`
-- `send_message`
-- `http_request`
-- `execute_plugin`
-
-#### Action Design Rule
-
-Agreed design:
-
-- actions are modeled with generic `add/update` commands plus `--type`
-- do not create dedicated subcommands per action type
-- use `--raw` and `--raw-file` for advanced or highly nested action configuration
-
-#### Action Base Flags
-
-Common:
-
-- `--type <type>`
-- `--name <name>`
-
-Create record:
-
-- `--target-schema <uuid>`
-- `--map <field=value>` repeatable
-- `--map-json <field=json>` repeatable
-
-Update record:
-
-- `--target-schema <uuid>`
-- `--map <field=value>` repeatable
-- `--map-json <field=json>` repeatable
-- `--condition <field:comparator:value>` repeatable
-- `--use-trigger-record`
-
-Search records:
-
-- `--target-schema <uuid>`
-- `--condition <field:comparator:value>` repeatable
-- `--use-trigger-record`
-
-Send message:
-
-- `--map <field=value>` repeatable
-- `--map-json <field=json>` repeatable
-
-HTTP request:
-
-- `--method GET|POST|PUT|PATCH|DELETE`
-- `--url <url>`
-- `--header <key=value>` repeatable
-- `--body <json>`
-- `--body-file <path>`
-- `--content-type <type>`
-- `--timeout-ms <n>`
-- `--var <key=value>` repeatable
-- `--auth-mode <mode>`
-- `--connection <uuid>`
-
-Execute plugin:
-
-- `--plugin <id>`
-- `--arg <key=value>` repeatable
-- `--arg-json <key=json>` repeatable
-
-Fallbacks:
-
-- `--raw <json>`
-- `--raw-file <path>`
-
-### Automation Flow Commands
-
-Proposed commands:
-
-- `automations flow get <automation>`
-- `automations flow set <automation> [--entry <actionId>]... [--transition <from:to>]...`
-- `automations flow auto <automation>`
-
-Design rule:
-
-- the explicit contract is `flow set` with entry actions and transitions
-- `flow auto` may exist later as a helper, but it is not the core execution contract
-
-### Automation Webhook Commands
-
-Proposed commands:
-
-- `automations webhook get <automation>`
-- `automations webhook set <automation> [flags]`
-- `automations webhook delete <automation>`
-
-Webhook flags:
-
-- `--active`
-- `--idempotency-key-path <jsonpath>`
-- `--event-type-path <jsonpath>`
-- `--allowed-event-type <value>` repeatable
-- `--field-mapping <json>` repeatable
-- `--field-mapping-file <path>`
-- `--raw <json>`
-- `--raw-file <path>`
-
-### Automation Plugin Commands
-
-Proposed commands:
-
-- `automations plugins list`
-- `automations plugins get <plugin>`
-
-Plugins are read-only resources in the CLI contract.
-
-### Automation Connection Commands
-
-Proposed commands:
-
-- `automations connections list`
-- `automations connections get <connection>`
-- `automations connections create --name <name> --type <type> --scope <scope> [--owner-member <uuid>] [--config <json>] [--secret <key=value>]... [--active]`
-- `automations connections update <connection> [--set <path=value>]... [--unset <path>]...`
-- `automations connections delete <connection>`
-
-#### Connection Design Rules
-
-Agreed rules:
-
-- keep `config` and `secret` conceptually separate during creation
-- model update as patch-like set/unset because the backend patch contract is generic
-- avoid forcing users to pass the entire connection payload just to adjust one field
-
-### Naming Conventions Agreed in This Section
-
-The following rules are now part of the design:
-
-- expose `folders`, `trigger`, `actions`, `flow`, `webhook`, `plugins`, and `connections` as first-class automation subresources
-- model trigger and action polymorphism with generic commands plus `--type`
-- use explicit verbs like `activate`, `deactivate`, `move`, and `set`
-- prefer structured flags for common cases and `--raw` for advanced nested payloads
-
-## Mutation Safety Policy
-
-The current agreed mutation policy is intentionally simple.
-
-### Global Safety Guard
-
-The main safety mechanism is the global read-only execution mode:
-
-- `--read-only`
-- `ZINKEE_READ_ONLY=1`
-
-When read-only mode is active:
-
-- commands classified as `write` or `destructive` must fail before calling the API
-
-### Confirmation Policy
-
-For now, the CLI will not require extra confirmation flags such as `--force` or interactive prompts as a general rule.
-
-That means:
-
-- `delete`
-- `unpublish`
-- `publish`
-- `move`
-- `activate`
-- `deactivate`
-- `update`
-
-all execute directly when the CLI is not in read-only mode.
-
-This policy can be revisited later if real usage shows a need for additional safety rails, but it is not part of the initial contract.
-
-## JSON Output, Errors, and Exit Codes
-
-The CLI is designed for both humans and agents.
-
-For humans:
-
-- default output is `table`
-
-For agents:
-
-- `--json` is the stable machine-readable contract
-
-### JSON Success Envelope
-
-Agreed decision:
-
-- the CLI should use a consistent success envelope
-- success payloads should not be returned as bare top-level values
-
-Canonical shape:
-
-```json
-{
-  "data": {},
-  "meta": {}
-}
-```
-
-Reasoning:
-
-- agents can always parse the same top-level structure
-- metadata can evolve without changing the shape of `data`
-- pagination, profile resolution, and execution context can be surfaced consistently
-
-Example:
-
-```json
-{
-  "data": [
-    {
-      "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
-      "name": "Contacts",
-      "slug": "contacts"
-    }
-  ],
-  "meta": {
-    "profile": "prod",
-    "baseUrl": "https://api.zinkee.com",
-    "command": "schemas list",
-    "readOnly": false
-  }
-}
-```
-
-### Pagination in JSON
-
-When a command produces paginated results, pagination metadata should live in `meta.page`.
-
-Canonical shape:
-
-```json
-{
-  "data": [],
-  "meta": {
-    "page": {
-      "offset": 0,
-      "limit": 50,
-      "total": 120,
-      "count": 50,
-      "hasMore": true
-    }
-  }
-}
-```
-
-This keeps the CLI JSON contract more uniform than mirroring each backend response shape directly.
-
-### JSON Error Envelope
-
-Agreed decision:
-
-- the CLI should also use a consistent error envelope
-- backend error fields should be preserved whenever available
-
-Canonical shape:
-
-```json
-{
-  "error": {
-    "status": 400,
-    "error": "BAD_REQUEST",
-    "reason": "schema_id_invalid",
-    "message": "Schema identifier is invalid.",
-    "action": "Use a valid UUID in the schemaId field.",
-    "retryable": false,
-    "path": "/api/v2/schemas/...",
-    "requestId": "req-123",
-    "timestamp": "2026-03-24T12:00:00Z"
-  },
-  "meta": {
-    "profile": "prod",
-    "baseUrl": "https://api.zinkee.com",
-    "command": "schemas get"
-  }
-}
-```
-
-For CLI-native errors, the same envelope model should be used:
-
-```json
-{
-  "error": {
-    "status": 1,
-    "error": "CLI_ERROR",
-    "reason": "command_not_allowed_in_read_only_mode",
-    "message": "Command \"records create\" is not allowed in read-only mode.",
-    "action": "Run the command without --read-only if write access is intended.",
-    "retryable": false
-  },
-  "meta": {
-    "profile": "prod",
-    "command": "records create"
-  }
-}
-```
-
-### JSON Output Rules
-
-When `--json` is active:
-
-- stdout must contain only structured JSON
-- no tables
-- no color
-- no banners
-- no stray explanatory text
-- debug or diagnostic noise must not be printed to stdout
-
-If debugging output is enabled, it must go to stderr or be explicitly structured.
-
-### Example Output in JSON
-
-When `--example --json` is used, the CLI should return structured examples.
-
-Canonical shape:
-
-```json
-{
-  "data": {
-    "examples": [
-      {
-        "description": "Query records with a text filter",
-        "command": "zinkee records query contacts --where \"email contains @acme.com\""
-      }
-    ]
-  },
-  "meta": {
-    "command": "records query"
-  }
-}
-```
-
-### Binary Output Rule
-
-Binary-producing commands such as `files download` must not dump raw bytes into a JSON response.
-
-Rule:
-
-- if `--json` is used with a binary command, the CLI should require `--output`
-- the JSON response should then describe the result, not embed the binary payload
-
-### Exit Codes
-
-The CLI should use a small, stable exit code taxonomy.
-
-Agreed mapping:
-
-- `0`: success
-- `1`: general CLI error
-- `2`: invalid usage or invalid local arguments
-- `3`: authentication or authorization error
-- `4`: resource not found
-- `5`: conflict or invalid resource state
-- `6`: network, timeout, or backend availability error
-- `7`: command blocked by read-only mode
-
-### Exit Code Mapping Rules
-
-Recommended mapping:
-
-- local parsing, flag validation, config validation: `2`
-- backend `401` or `403`: `3`
-- backend `404`: `4`
-- backend `409`: `5`
-- backend `5xx`, timeouts, connection failures: `6`
-- local read-only enforcement: `7`
-- uncategorized or generic failures: `1`
-
-## Naming Conventions
-
-The CLI should be highly predictable across domains.
-
-### Global Naming Rules
-
-Agreed rules:
-
-- commands and subcommands use `kebab-case`
-- long flags use `kebab-case`
-- resource command groups use plural nouns
-- verbs should remain small and consistent
-
-Preferred verbs:
-
-- `list`
-- `get`
-- `create`
-- `update`
-- `delete`
-- `query`
-- `set`
-- `add`
-- `move`
-- `publish`
-- `unpublish`
-- `activate`
-- `deactivate`
-
-### Boolean Flags
-
-Boolean design rules:
-
-- activation-style booleans use bare flags
-- booleans that may need explicit true/false during update operations may accept a value
-
-Examples:
-
-- `--json`
-- `--read-only`
-- `--active`
-- `--allow-multiple`
-- `--static`
-- `--commentable true`
-- `--auditable false`
-
-### Resource Selectors
-
-Selector rules:
-
-- use UUID or slug where the domain naturally supports slugs
-- use UUID where slugs do not clearly exist or could be ambiguous
-
-Current selector policy:
-
-- `schemas`: UUID or slug
-- `schema fields`: UUID or slug
-- `records`: schema by UUID or slug, record by UUID
-- `files`: UUID
-- `navigation folders`: UUID or exact folder name
-- `teamspace folders`: UUID or exact folder name
-- `displays`: UUID for now
-- `widgets`: UUID
-- `variables`: UUID
-- `tabs`: string
-- `automations`: UUID
-- `automation folders`: UUID or exact folder name
-- `actions`: UUID
-- `connections`: UUID
-- `plugins`: string id
-
-Folder resolution rule:
-
-- folder selectors may resolve by UUID or exact name
-- if an exact-name lookup matches more than one folder, the CLI must fail with an ambiguity error and ask for UUID
-
-### Lists and Repeated Flags
-
-The CLI should prefer repeated flags for complex or structured lists, and CSV only for simple ergonomic cases.
-
-Use repeated flags for:
-
-- `--where`
-- `--filter`
-- `--condition`
-- `--set`
-- `--unset`
-- `--header`
-- `--entry`
-- `--transition`
-
-Use CSV for:
-
-- `--select id,name,email`
-
-### JSON Payload Conventions
-
-For command-wide structured input:
-
-- `--raw <json>`
-- `--raw-file <path>`
-
-For sub-sections:
-
-- `--layout <json>` / `--layout-file <path>`
-- `--props <json>` / `--props-file <path>`
-- `--body <json>` / `--body-file <path>`
-
-Rule:
-
-- when a JSON inline flag is expected to carry non-trivial payloads, a file-based variant should also exist
-
-### Key-Value Conventions
-
-Simple mappings should use `key=value`.
-
-Examples:
-
-- `--set field=value`
-- `--header Authorization=Bearer-token`
-- `--secret client_secret=abc`
-- `--arg retries=3`
-
-Structured mappings should use explicit JSON forms.
-
-Examples:
-
-- `--set-json field='{"a":1}'`
-- `--arg-json payload='{"x":2}'`
-
-### Expression Conventions
-
-The CLI should reuse the same human-readable expression style across filter-like features whenever possible.
-
-Target style:
-
-- `--where "status eq active"`
-- `--condition "amount gt 1000"`
-- `--filter "ownerId in a,b,c"`
-
-These should ideally share a common parser internally.
-
-### Reserved Global Flags
-
-The following names are reserved globally and should not be repurposed locally:
-
-- `--profile`
-- `--base-url`
-- `--api-key`
-- `--json`
-- `--read-only`
-- `--verbose`
-- `--debug`
-- `--no-color`
-- `--example`
-
-Command-local advanced payload flags:
-
-- `--raw`
-- `--raw-file`
-
-These are not root-level global flags. They are available only on commands that explicitly support structured payload fallback.
-
-## Internal Architecture
-
-The CLI should follow the same stack and almost the same structure as the reference CLI in `/Users/david/dev/pichardo-projects/store-manager`, while adapting from Shopify GraphQL to Zinkee REST API v2.
-
-### Technology Stack
-
-Agreed stack direction:
-
-- Node.js 20+
-- TypeScript
-- ESM
-- `commander` for CLI command modeling
-- `chalk` for human-friendly terminal output
-- `cli-table3` for table output
-- `tsup` for builds
-- `tsx` for local development
-- `vitest` for tests
-- native `fetch` for HTTP
-
-### Project Structure
-
-Proposed structure:
-
-```text
-src/
-  index.ts
-  client.ts
-  config.ts
-  types.ts
-  command-registry.ts
-  commands/
-    config.ts
-    profiles.ts
-    schemas.ts
-    records.ts
-    comments.ts
-    files.ts
-    navigation.ts
-    teamspace.ts
-    displays.ts
-    automations.ts
-  api/
-    schemas.ts
-    records.ts
-    comments.ts
-    files.ts
-    navigation.ts
-    teamspace.ts
-    displays.ts
-    automations.ts
-  utils/
-    output.ts
-    errors.ts
-    examples.ts
-    identifiers.ts
-    flags.ts
-    json.ts
-  parsers/
-    expressions.ts
-    kv.ts
-    selectors.ts
-```
-
-This keeps the same mental model as the reference:
-
-- one command module per domain
-- one transport-facing module per domain
-- shared helpers centralized in utils/parsers/config/client
-
-### Entry Point
-
-`src/index.ts` should:
-
-- create the root `Command`
-- register global options
-- register every domain command module
-- enable `showHelpAfterError`
-- centralize top-level error handling
-
-### Config Layer
-
-`src/config.ts` should:
-
-- read and write `/Users/david/.config/zinkee/config.toml`
-- resolve the effective profile
-- apply runtime overrides from flags
-- preserve backward compatibility with the legacy TOML contract
-
-### HTTP Client Layer
-
-`src/client.ts` should:
-
-- encapsulate `fetch`
-- handle auth headers
-- enforce request timeout
-- normalize HTTP and JSON parsing failures
-- preserve backend error fields when available
-- expose a small REST-friendly API for domain modules
-
-Recommended client responsibilities:
-
-- build request URL from `baseUrl`
-- add bearer token from resolved profile or override
-- parse JSON success and error responses
-- detect non-JSON payloads where applicable
-- support binary download paths for file commands
-
-### Domain API Modules
-
-`src/api/*.ts` should:
-
-- map domain operations to concrete API v2 HTTP calls
-- contain minimal transport shaping logic
-- avoid owning CLI parsing concerns
-
-Examples:
-
-- `src/api/schemas.ts`: `/api/v2/schemas`, `/fields`
-- `src/api/records.ts`: `/api/v2/schemas/{schemaId}/records`
-- `src/api/displays.ts`: `/api/v2/displays` and subresources
-- `src/api/automations.ts`: `/api/v2/automations`, folders, trigger, actions, flow, webhook, plugins, connections
-
-### Command Modules
-
-`src/commands/*.ts` should:
-
-- register commander commands
-- parse and validate CLI arguments
-- resolve selectors
-- call domain API helpers
-- format output
-
-They should not:
-
-- own low-level fetch logic
-- duplicate generic error formatting
-- parse TOML directly
-
-### Command Registry
-
-The new CLI needs a central registry that the reference CLI does not currently need as explicitly.
-
-`src/command-registry.ts` should define metadata such as:
-
-- canonical command name
-- access level: `read`, `write`, `destructive`
-- whether `--example` is supported
-- whether `--raw` is supported
-- output capabilities such as table/json/binary
-
-This registry should power:
-
-- read-only enforcement
-- example generation
-- consistent metadata in `--json`
-- future documentation extraction
-
-### Parsing Utilities
-
-The CLI will benefit from explicit parser helpers for repeated mini-languages.
-
-`src/parsers/expressions.ts` should parse:
-
-- `--where`
-- `--filter`
-- `--condition`
-
-`src/parsers/kv.ts` should parse:
-
-- `--set`
-- `--set-json`
-- `--arg`
-- `--arg-json`
-- `--header`
-- `--secret`
-
-`src/parsers/selectors.ts` should parse and normalize:
-
-- UUID-or-slug selectors
-- typed resource selectors where needed
-
-### Output Utilities
-
-`src/utils/output.ts` should centralize:
-
-- table rendering
-- JSON success envelope rendering
-- JSON error envelope rendering
-- binary command output metadata
-
-### Error Utilities
-
-`src/utils/errors.ts` should centralize:
-
-- CLI-native error classes
-- mapping backend errors to exit codes
-- mapping local validation failures to stable reasons
-- formatting human-readable error output
-
-### Example Utilities
-
-`src/utils/examples.ts` should centralize:
-
-- command examples
-- JSON example rendering
-- example lookup by command identity
-
-This avoids scattering example strings across unrelated command logic.
-
-### Testing Strategy
-
-The testing model should stay close to the reference CLI:
-
-- favor unit tests for pure helpers, parsers, selector resolution, and command input normalization
-- avoid unnecessarily heavy end-to-end mocking where pure tests are enough
-- add focused transport tests for client error handling and JSON envelope behavior
-
-Suggested test files:
-
-- `src/config.test.ts`
-- `src/client.test.ts`
-- `src/parsers/expressions.test.ts`
-- `src/parsers/kv.test.ts`
-- `src/commands/schemas.test.ts`
-- `src/commands/records.test.ts`
-- `src/commands/displays.test.ts`
-- `src/commands/automations.test.ts`
-
-### Agent-Facing Documentation
-
-In line with the reference CLI, the repository should include agent-oriented documentation close to the codebase.
-
-Recommended artifacts:
-
-- `README.md`
-- `AGENTS.md`
-- a CLI contract reference file
-- examples that match the true command help
-
-The source of truth order should be:
-
-1. live `--help`
-2. command modules
-3. repository docs