zinkee 0.1.0

package/src/utils/examples.ts

@@ -0,0 +1,855 @@
+import { AutomationsApi } from "../api/automations.js";
+import { SchemasApi, type ApiSchema, type ApiSchemaField } from "../api/schemas.js";
+import { ApiClient } from "../client.js";
+import { defaultConfigPath, readConfig } from "../config.js";
+import type { NormalizedUuidOrSlug } from "../parsers/selectors.js";
+import { resolveRuntimeContext } from "../runtime-context.js";
+import type { RuntimeOverrides } from "../types.js";
+import {
+  getSchemaFieldTypeDefinitions,
+  resolveSchemaFieldType,
+} from "./schema-fields.js";
+
+export interface CommandExample {
+  command: string;
+  description: string;
+  raw?: string;
+}
+
+export interface ExampleContextOptions {
+  enabled?: boolean;
+  configPath?: string;
+  overrides?: RuntimeOverrides;
+}
+
+export function buildCommandExample(example: CommandExample): CommandExample {
+  return {
+    command: example.command,
+    description: example.description,
+    raw: example.raw,
+  };
+}
+
+export function buildCommandExamples(examples: readonly CommandExample[]): readonly CommandExample[] {
+  return examples.map((example) => buildCommandExample(example));
+}
+
+const SAMPLE_UUID = "550e8400-e29b-41d4-a716-446655440001";
+
+const specificExamples: Record<string, readonly CommandExample[]> = {
+  "records query": buildCommandExamples([
+    {
+      description: "Query records with filters, sort and pagination",
+      command: 'zinkee --json records query contacts --select id,name --where "status eq active" --sort createdAt:desc --limit 20 --offset 0',
+    },
+  ]),
+  "records create": buildCommandExamples([
+    {
+      description: "Create a record with simple and structured values",
+      command: `zinkee --json records create contacts --set name=Ana --set-json meta='{"tier":"gold"}'`,
+    },
+  ]),
+  "files download": buildCommandExamples([
+    {
+      description: "Download a file to disk in JSON mode",
+      command: `zinkee --json files download ${SAMPLE_UUID} --output ./download.bin`,
+    },
+  ]),
+  "navigation resources move": buildCommandExamples([
+    {
+      description: "Move a resource into a navigation folder by exact folder name",
+      command: `zinkee --json navigation resources move ${SAMPLE_UUID} --type schema --to Finance`,
+    },
+  ]),
+  "teamspace resources publish": buildCommandExamples([
+    {
+      description: "Publish a resource into a teamspace folder",
+      command: `zinkee --json teamspace resources publish ${SAMPLE_UUID} --to "Customer Success"`,
+    },
+  ]),
+  "displays widgets create": buildCommandExamples([
+    {
+      description: "Create a chart widget through the generic --type path",
+      command: 'zinkee --json displays widgets create display-1 --type chart --name "Revenue" --chart-type bar',
+    },
+  ]),
+  "automations create": buildCommandExamples([
+    {
+      description:
+        "Create a scheduled automation with a six-field cron expression. This is the safest first example because it does not depend on workspace schemas.",
+      command: 'zinkee --json automations create --name "Nightly invoice sync" --trigger-type scheduled --cron "0 15 10 * * 1"',
+      raw: `{
+  "name": "Nightly invoice sync",
+  "trigger": {
+    "type": "scheduled",
+    "config": {
+      "cronExpression": "0 15 10 * * 1"
+    }
+  }
+}`,
+    },
+    {
+      description:
+        "Create a record-created automation using a real schema slug or UUID. Replace 'leads' with a schema from 'zinkee --json schemas list'.",
+      command: 'zinkee --json automations create --name "Lead welcome" --trigger-type record_created --trigger-schema leads',
+      raw: `{
+  "name": "Lead welcome",
+  "trigger": {
+    "type": "record_created",
+    "config": {
+      "schemaId": "leads"
+    }
+  }
+}`,
+    },
+    {
+      description:
+        "Create a record-changed automation using real schema and field slugs or UUIDs. Replace 'orders' and 'status' with values from your workspace.",
+      command: 'zinkee --json automations create --name "Order status sync" --trigger-type record_changed --trigger-schema orders --trigger-field status',
+      raw: `{
+  "name": "Order status sync",
+  "trigger": {
+    "type": "record_changed",
+    "config": {
+      "schemaId": "orders",
+      "fieldIds": ["status"]
+    }
+  }
+}`,
+    },
+  ]),
+  "automations update": buildCommandExamples([
+    {
+      description: "Patch automation metadata using the backend set/unset contract",
+      command:
+        'zinkee --json automations update automation-1 --raw \'{"set":{"description":"Updated by CLI docs"},"unset":["folderId"]}\'',
+      raw: `{
+  "set": {
+    "description": "Updated by CLI docs"
+  },
+  "unset": ["folderId"]
+}`,
+    },
+  ]),
+  "automations trigger set": buildCommandExamples([
+    {
+      description: "Replace the trigger with a scheduled trigger",
+      command: 'zinkee --json automations trigger set automation-1 --trigger-type scheduled --cron "0 0 9 * * *"',
+      raw: `{
+  "type": "scheduled",
+  "config": {
+    "cronExpression": "0 0 9 * * *"
+  }
+}`,
+    },
+    {
+      description: "Replace the trigger with a record-changed trigger and a literal condition",
+      command:
+        'zinkee --json automations trigger set automation-1 --trigger-type record_changed --trigger-schema orders --trigger-field status --condition status:eq:approved',
+      raw: `{
+  "type": "record_changed",
+  "config": {
+    "schemaId": "orders",
+    "fieldIds": ["status"],
+    "conditions": [
+      {
+        "field": "status",
+        "comparator": "eq",
+        "values": [
+          {
+            "rawValue": "approved",
+            "source": null
+          }
+        ]
+      }
+    ]
+  }
+}`,
+    },
+    {
+      description: "Replace the trigger with a webhook trigger using an existing webhook endpoint id",
+      command:
+        'zinkee --json automations trigger set automation-1 --trigger-type webhook --webhook-endpoint-id 550e8400-e29b-41d4-a716-446655440001',
+      raw: `{
+  "type": "webhook",
+  "config": {
+    "webhookEndpointId": "550e8400-e29b-41d4-a716-446655440001"
+  }
+}`,
+    },
+  ]),
+  "automations actions add": buildCommandExamples([
+    {
+      description: "Add a create-record action with literal and trigger-based field mappings",
+      command:
+        'zinkee --json automations actions add automation-1 --type create_record --name "Create follow-up" --target-schema followups --map status=pending --map-json owner=\'{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}\'',
+      raw: `{
+  "type": "create_record",
+  "name": "Create follow-up",
+  "config": {
+    "targetSchemaId": "followups",
+    "fieldMapping": {
+      "status": {
+        "rawValue": "pending",
+        "source": null
+      },
+      "owner": {
+        "rawValue": null,
+        "source": {
+          "type": "TRIGGER",
+          "id": "payload_value"
+        }
+      }
+    }
+  }
+}`,
+    },
+    {
+      description: "Add a search-records action with a trigger-based condition",
+      command:
+        'zinkee --json automations actions add automation-1 --type search_records --name "Find duplicates" --target-schema followups --condition-json \'{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}\'',
+      raw: `{
+  "type": "search_records",
+  "name": "Find duplicates",
+  "config": {
+    "targetSchemaId": "followups",
+    "conditions": [
+      {
+        "field": "email",
+        "comparator": "eq",
+        "values": [
+          {
+            "rawValue": null,
+            "source": {
+              "type": "TRIGGER",
+              "id": "payload_value"
+            }
+          }
+        ]
+      }
+    ]
+  }
+}`,
+    },
+    {
+      description: "Add an HTTP request action through the generic --type path",
+      command:
+        'zinkee --json automations actions add automation-1 --type http_request --name Notify --method POST --url https://example.com/hook --content-type application/json',
+      raw: `{
+  "type": "http_request",
+  "name": "Notify",
+  "config": {
+    "method": "POST",
+    "url": "https://example.com/hook",
+    "contentType": "application/json"
+  }
+}`,
+    },
+    {
+      description:
+        "Add an execute-plugin action with structured plugin arguments. Replace 'clone-budget' with an active id from 'zinkee --json automations plugins list'.",
+      command:
+        'zinkee --json automations actions add automation-1 --type execute_plugin --name "Run plugin" --plugin clone-budget --arg mode=safe --arg-json payload=\'{"dryRun":true}\'',
+      raw: `{
+  "type": "execute_plugin",
+  "name": "Run plugin",
+  "config": {
+    "pluginId": "clone-budget",
+    "pluginArgs": {
+      "mode": "safe",
+      "payload": {
+        "dryRun": true
+      }
+    }
+  }
+}`,
+    },
+  ]),
+  "automations actions update": buildCommandExamples([
+    {
+      description: "Update a record action using the trigger record without sending conditions",
+      command:
+        'zinkee --json automations actions update automation-1 action-1 --type update_record --name "Update trigger record" --target-schema followups --map status=ready --use-trigger-record',
+      raw: `{
+  "type": "update_record",
+  "name": "Update trigger record",
+  "config": {
+    "targetSchemaId": "followups",
+    "fieldMapping": {
+      "status": {
+        "rawValue": "ready",
+        "source": null
+      }
+    },
+    "useTriggerRecord": true
+  }
+}`,
+    },
+  ]),
+  "automations flow set": buildCommandExamples([
+    {
+      description: "Set flow entry actions and transitions",
+      command: 'zinkee --json automations flow set automation-1 --entry action-1 --transition action-1:action-2',
+      raw: `{
+  "entryActionIds": ["action-1"],
+  "transitions": [
+    {
+      "fromActionId": "action-1",
+      "toActionId": "action-2"
+    }
+  ]
+}`,
+    },
+  ]),
+  "automations webhook set": buildCommandExamples([
+    {
+      description:
+        "Configure webhook ingestion paths and field mappings for a webhook automation. This config is separate from the webhook trigger itself.",
+      command:
+        'zinkee --json automations webhook set automation-1 --active --idempotency-key-path "$.id" --event-type-path "$.type" --allowed-event-type frontend.demo.created --field-mapping \'{"variable":"external_id","jsonPath":"$.data.id"}\'',
+      raw: `{
+  "active": true,
+  "idempotencyKeyJsonPath": "$.id",
+  "eventTypeJsonPath": "$.type",
+  "allowedEventTypes": ["frontend.demo.created"],
+  "fieldMappings": [
+    {
+      "variable": "external_id",
+      "jsonPath": "$.data.id"
+    }
+  ]
+}`,
+    },
+  ]),
+  "automations connections create": buildCommandExamples([
+    {
+      description: "Create a stored workspace connection for HTTP request actions",
+      command:
+        'zinkee --json automations connections create --name "ERP API Key" --type api_key --scope workspace --config \'{"headerName":"Authorization"}\' --secret apiKey=super-secret --active',
+      raw: `{
+  "name": "ERP API Key",
+  "type": "api_key",
+  "scope": "workspace",
+  "config": {
+    "headerName": "Authorization"
+  },
+  "secret": {
+    "apiKey": "super-secret"
+  },
+  "active": true
+}`,
+    },
+  ]),
+  "automations connections update": buildCommandExamples([
+    {
+      description: "Patch an existing stored connection",
+      command:
+        'zinkee --json automations connections update connection-1 --raw \'{"set":{"name":"ERP API Key Updated","config":{"headerName":"Authorization"}}}\'',
+      raw: `{
+  "set": {
+    "name": "ERP API Key Updated",
+    "config": {
+      "headerName": "Authorization"
+    }
+  }
+}`,
+    },
+  ]),
+};
+
+function fallbackExamples(commandName: string): readonly CommandExample[] {
+  switch (commandName) {
+    case "profiles list":
+      return [{ description: "List configured profiles", command: "zinkee profiles list" }];
+    case "profiles get":
+      return [{ description: "Show a profile", command: "zinkee profiles get prod" }];
+    case "profiles add":
+      return [{ description: "Add a profile", command: 'zinkee profiles add local --api-key token --base-url http://localhost:8088' }];
+    case "config validate":
+      return [{ description: "Validate config", command: "zinkee --json config validate" }];
+    case "schemas list":
+      return [{ description: "List schemas", command: "zinkee --json schemas list" }];
+    case "schemas create":
+      return [{ description: "Create a schema", command: 'zinkee --json schemas create --name Contacts --slug contacts --auditable --commentable' }];
+    case "comments create":
+      return [{ description: "Create a text comment", command: `zinkee --json comments create contacts ${SAMPLE_UUID} --text "Hello world"` }];
+    case "navigation folders create":
+      return [{ description: "Create a navigation folder", command: 'zinkee --json navigation folders create --name Finance --order 10' }];
+    case "teamspace folders list":
+      return [{ description: "List teamspace folders with resources", command: "zinkee --json teamspace folders list --include-resources" }];
+    case "displays create":
+      return [
+        { description: "Create a display", command: 'zinkee --json displays create --name Pipeline --template widget_row_tabs' },
+        {
+          description: "Create a freeform display with responsive layout data",
+          command: 'zinkee --json displays create --name "Control Proyecto Freeform" --template freeform --freeform-layouts \'{"lg":[{"i":"widget-1","x":0,"y":0,"w":6,"h":5}]}\'',
+        },
+      ];
+    case "automations list":
+      return [{ description: "List automations", command: "zinkee --json automations list" }];
+    default:
+      return [];
+  }
+}
+
+function buildSchemaFieldCreateExamples(type?: string): readonly CommandExample[] {
+  const definitions = getSchemaFieldTypeDefinitions();
+  const selectedDefinition = resolveSchemaFieldType(type);
+  const filteredDefinitions = selectedDefinition
+    ? definitions.filter((definition) => definition.key === selectedDefinition.key)
+    : definitions;
+
+  return buildCommandExamples(
+    filteredDefinitions.flatMap((definition) => {
+      if (definition.key !== "number") {
+        return [{
+          description: `Create a ${definition.key} field`,
+          command: `zinkee --json schemas fields create contacts --raw '${JSON.stringify(definition.examplePayload)}'`,
+        }];
+      }
+
+      return [
+        {
+          description: "Create a plain number field",
+          command:
+            'zinkee --json schemas fields create contacts --raw \'{"type":"number","slug":"amount","label":"Amount"}\'',
+        },
+        {
+          description: "Create a number field formatted like Moneda",
+          command: `zinkee --json schemas fields create contacts --raw '${JSON.stringify(definition.examplePayload)}'`,
+        },
+      ];
+    }),
+  );
+}
+
+export function getCommandExamples(
+  commandName: string,
+  filters: { type?: string } = {},
+): readonly CommandExample[] {
+  if (commandName === "schemas fields create") {
+    return buildSchemaFieldCreateExamples(filters.type);
+  }
+
+  return specificExamples[commandName] ?? fallbackExamples(commandName);
+}
+
+interface ExampleAutomationContext {
+  automationsApi: AutomationsApi;
+  schemasApi: SchemasApi;
+}
+
+interface SchemaFieldReference {
+  schemaId: string;
+  schemaRef: string;
+  fieldId: string;
+  fieldRef: string;
+}
+
+interface AutomationActionReference {
+  automationId: string;
+  actionId: string;
+}
+
+function selector(value: string): NormalizedUuidOrSlug {
+  return {
+    kind: "uuid",
+    value,
+  };
+}
+
+async function createExampleAutomationContext(
+  options: ExampleContextOptions = {},
+): Promise<ExampleAutomationContext | null> {
+  if (options.enabled !== true) {
+    return null;
+  }
+
+  try {
+    const config = readConfig(options.configPath ?? defaultConfigPath);
+    const runtime = resolveRuntimeContext(config, options.overrides);
+
+    if (!runtime.baseUrl) {
+      return null;
+    }
+
+    const client = new ApiClient({
+      baseUrl: runtime.baseUrl,
+      apiKey: runtime.apiKey,
+    });
+
+    return {
+      automationsApi: new AutomationsApi(client),
+      schemasApi: new SchemasApi(client),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function referenceValue(value: { slug?: string; id?: string }): string | undefined {
+  return value.slug ?? value.id;
+}
+
+function pickExampleField(fields: readonly ApiSchemaField[]): ApiSchemaField | undefined {
+  return fields.find((field) => !field.required || field.slug || field.id) ?? fields[0];
+}
+
+async function findSchemaFieldReference(
+  context: ExampleAutomationContext,
+): Promise<SchemaFieldReference | null> {
+  const schemas = await context.schemasApi.listSchemas();
+
+  for (const schema of schemas) {
+    if (typeof schema.id !== "string") {
+      continue;
+    }
+
+    const fullSchema = await context.schemasApi.getSchema(selector(schema.id));
+    const fields = Array.isArray(fullSchema.fields) ? fullSchema.fields : [];
+    const field = pickExampleField(fields);
+    const schemaRef = referenceValue(schema);
+    const fieldRef = field ? referenceValue(field) : undefined;
+    const fieldId = typeof field?.id === "string" ? field.id : undefined;
+
+    if (!schemaRef || !fieldRef || !fieldId) {
+      continue;
+    }
+
+    return {
+      schemaId: schema.id,
+      schemaRef,
+      fieldId,
+      fieldRef,
+    };
+  }
+
+  return null;
+}
+
+async function findAutomationId(context: ExampleAutomationContext): Promise<string | null> {
+  const automations = await context.automationsApi.listAutomations();
+  const first = automations.find((automation) => typeof automation.id === "string");
+  return typeof first?.id === "string" ? first.id : null;
+}
+
+async function findAutomationWithAction(
+  context: ExampleAutomationContext,
+): Promise<AutomationActionReference | null> {
+  const automations = await context.automationsApi.listAutomations();
+
+  for (const automation of automations) {
+    if (typeof automation.id !== "string") {
+      continue;
+    }
+
+    const actions = await context.automationsApi.listActions(selector(automation.id));
+    const firstAction = actions.find((action) => typeof action.id === "string");
+
+    if (typeof firstAction?.id === "string") {
+      return {
+        automationId: automation.id,
+        actionId: firstAction.id,
+      };
+    }
+  }
+
+  return null;
+}
+
+async function buildDynamicAutomationExamples(
+  commandName: string,
+  options: ExampleContextOptions = {},
+): Promise<readonly CommandExample[]> {
+  const context = await createExampleAutomationContext(options);
+
+  if (!context) {
+    return [];
+  }
+
+  const schemaField = await findSchemaFieldReference(context);
+  const automationId = await findAutomationId(context);
+  const automationWithAction = await findAutomationWithAction(context);
+  const plugins = await context.automationsApi.listPlugins();
+  const pluginId = typeof plugins[0]?.id === "string" ? plugins[0].id : undefined;
+  const connections = await context.automationsApi.listConnections();
+  const connectionId = typeof connections[0]?.id === "string" ? connections[0].id : undefined;
+
+  switch (commandName) {
+    case "automations create":
+      if (!schemaField) {
+        return [];
+      }
+      return buildCommandExamples([
+        {
+          description:
+            "Create a scheduled automation with a six-field cron expression. This is the safest first example because it does not depend on workspace schemas.",
+          command:
+            'zinkee --json automations create --name "Nightly invoice sync" --trigger-type scheduled --cron "0 15 10 * * 1"',
+          raw: `{
+  "name": "Nightly invoice sync",
+  "trigger": {
+    "type": "scheduled",
+    "config": {
+      "cronExpression": "0 15 10 * * 1"
+    }
+  }
+}`,
+        },
+        {
+          description:
+            `Create a record-created automation using a real schema reference from this workspace (${schemaField.schemaRef}).`,
+          command: `zinkee --json automations create --name "Record created demo" --trigger-type record_created --trigger-schema ${schemaField.schemaRef}`,
+          raw: `{
+  "name": "Record created demo",
+  "trigger": {
+    "type": "record_created",
+    "config": {
+      "schemaId": "${schemaField.schemaRef}"
+    }
+  }
+}`,
+        },
+        {
+          description:
+            `Create a record-changed automation using a real schema and field reference from this workspace (${schemaField.schemaRef} / ${schemaField.fieldRef}).`,
+          command: `zinkee --json automations create --name "Record changed demo" --trigger-type record_changed --trigger-schema ${schemaField.schemaRef} --trigger-field ${schemaField.fieldRef}`,
+          raw: `{
+  "name": "Record changed demo",
+  "trigger": {
+    "type": "record_changed",
+    "config": {
+      "schemaId": "${schemaField.schemaRef}",
+      "fieldIds": ["${schemaField.fieldRef}"]
+    }
+  }
+}`,
+        },
+      ]);
+    case "automations trigger set":
+      if (!automationId || !schemaField) {
+        return [];
+      }
+      return buildCommandExamples([
+        {
+          description: "Replace the trigger with a scheduled trigger on a real automation from this workspace.",
+          command: `zinkee --json automations trigger set ${automationId} --trigger-type scheduled --cron "0 0 9 * * *"`,
+          raw: `{
+  "type": "scheduled",
+  "config": {
+    "cronExpression": "0 0 9 * * *"
+  }
+}`,
+        },
+        {
+          description:
+            `Replace the trigger with a record-changed trigger using a real schema and field (${schemaField.schemaRef} / ${schemaField.fieldRef}).`,
+          command: `zinkee --json automations trigger set ${automationId} --trigger-type record_changed --trigger-schema ${schemaField.schemaRef} --trigger-field ${schemaField.fieldRef} --condition ${schemaField.fieldRef}:eq:approved`,
+          raw: `{
+  "type": "record_changed",
+  "config": {
+    "schemaId": "${schemaField.schemaRef}",
+    "fieldIds": ["${schemaField.fieldRef}"],
+    "conditions": [
+      {
+        "field": "${schemaField.fieldRef}",
+        "comparator": "eq",
+        "values": [
+          {
+            "rawValue": "approved",
+            "source": null
+          }
+        ]
+      }
+    ]
+  }
+}`,
+        },
+      ]);
+    case "automations actions add":
+      if (!automationId || !schemaField) {
+        return [];
+      }
+      return buildCommandExamples([
+        {
+          description: "Add a create-record action with literal and trigger-based mappings from this workspace.",
+          command: `zinkee --json automations actions add ${automationId} --type create_record --name "Create follow-up" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=pending --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}'`,
+          raw: `{
+  "type": "create_record",
+  "name": "Create follow-up",
+  "config": {
+    "targetSchemaId": "${schemaField.schemaRef}",
+    "fieldMapping": {
+      "${schemaField.fieldRef}": {
+        "rawValue": "pending",
+        "source": null
+      },
+      "owner": {
+        "rawValue": null,
+        "source": {
+          "type": "TRIGGER",
+          "id": "payload_value"
+        }
+      }
+    }
+  }
+}`,
+        },
+        {
+          description: "Add a search-records action with a trigger-based condition from this workspace.",
+          command: `zinkee --json automations actions add ${automationId} --type search_records --name "Find duplicates" --target-schema ${schemaField.schemaRef} --condition-json '{"field":"${schemaField.fieldRef}","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'`,
+          raw: `{
+  "type": "search_records",
+  "name": "Find duplicates",
+  "config": {
+    "targetSchemaId": "${schemaField.schemaRef}",
+    "conditions": [
+      {
+        "field": "${schemaField.fieldRef}",
+        "comparator": "eq",
+        "values": [
+          {
+            "rawValue": null,
+            "source": {
+              "type": "TRIGGER",
+              "id": "payload_value"
+            }
+          }
+        ]
+      }
+    ]
+  }
+}`,
+        },
+        {
+          description: "Add an HTTP request action through the generic --type path.",
+          command: `zinkee --json automations actions add ${automationId} --type http_request --name Notify --method POST --url https://example.com/hook --content-type application/json`,
+          raw: `{
+  "type": "http_request",
+  "name": "Notify",
+  "config": {
+    "method": "POST",
+    "url": "https://example.com/hook",
+    "contentType": "application/json"
+  }
+}`,
+        },
+        ...(pluginId
+          ? buildCommandExamples([
+              {
+                description:
+                  `Add an execute-plugin action using an active plugin from this workspace (${pluginId}).`,
+                command: `zinkee --json automations actions add ${automationId} --type execute_plugin --name "Run plugin" --plugin ${pluginId} --arg mode=safe --arg-json payload='{"dryRun":true}'`,
+                raw: `{
+  "type": "execute_plugin",
+  "name": "Run plugin",
+  "config": {
+    "pluginId": "${pluginId}",
+    "pluginArgs": {
+      "mode": "safe",
+      "payload": {
+        "dryRun": true
+      }
+    }
+  }
+}`,
+              },
+            ])
+          : []),
+      ]);
+    case "automations actions update":
+      if (!automationWithAction || !schemaField) {
+        return [];
+      }
+      return buildCommandExamples([
+        {
+          description: "Update a record action on a real automation/action pair using the trigger record.",
+          command: `zinkee --json automations actions update ${automationWithAction.automationId} ${automationWithAction.actionId} --type update_record --name "Update trigger record" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=ready --use-trigger-record`,
+          raw: `{
+  "type": "update_record",
+  "name": "Update trigger record",
+  "config": {
+    "targetSchemaId": "${schemaField.schemaRef}",
+    "fieldMapping": {
+      "${schemaField.fieldRef}": {
+        "rawValue": "ready",
+        "source": null
+      }
+    },
+    "useTriggerRecord": true
+  }
+}`,
+        },
+      ]);
+    case "automations flow set":
+      if (!automationWithAction) {
+        return [];
+      }
+      return buildCommandExamples([
+        {
+          description: "Set flow entry actions using a real automation/action pair from this workspace.",
+          command: `zinkee --json automations flow set ${automationWithAction.automationId} --entry ${automationWithAction.actionId}`,
+          raw: `{
+  "entryActionIds": ["${automationWithAction.actionId}"],
+  "transitions": []
+}`,
+        },
+      ]);
+    case "automations connections create":
+      return buildCommandExamples([
+        {
+          description: "Create a stored workspace connection for HTTP request actions.",
+          command:
+            'zinkee --json automations connections create --name "ERP API Key" --type api_key --scope workspace --config \'{"headerName":"Authorization"}\' --secret apiKey=super-secret --active',
+          raw: `{
+  "name": "ERP API Key",
+  "type": "api_key",
+  "scope": "workspace",
+  "config": {
+    "headerName": "Authorization"
+  },
+  "secret": {
+    "apiKey": "super-secret"
+  },
+  "active": true
+}`,
+        },
+      ]);
+    case "automations connections update":
+      if (!connectionId) {
+        return [];
+      }
+      return buildCommandExamples([
+        {
+          description: "Patch an existing stored connection from this workspace.",
+          command: `zinkee --json automations connections update ${connectionId} --raw '{"set":{"name":"ERP API Key Updated","config":{"headerName":"Authorization"}}}'`,
+          raw: `{
+  "set": {
+    "name": "ERP API Key Updated",
+    "config": {
+      "headerName": "Authorization"
+    }
+  }
+}`,
+        },
+      ]);
+    default:
+      return [];
+  }
+}
+
+export async function getResolvedCommandExamples(
+  commandName: string,
+  filters: { type?: string } = {},
+  options: ExampleContextOptions = {},
+): Promise<readonly CommandExample[]> {
+  const dynamicExamples = commandName.startsWith("automations")
+    ? await buildDynamicAutomationExamples(commandName, options)
+    : [];
+
+  if (dynamicExamples.length > 0) {
+    return dynamicExamples;
+  }
+
+  return getCommandExamples(commandName, filters);
+}