zinkee 0.1.44 → 0.1.46

package/src/utils/examples.test.ts

@@ -1,374 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { commandRegistry } from "../command-registry.js";
-import { getCommandExamples, getResolvedCommandExamples } from "./examples.js";
-
-describe("getCommandExamples", () => {
-  it("returns registered examples for complex commands", () => {
-    const examples = getCommandExamples("records query");
-
-    expect(examples.length).toBeGreaterThan(0);
-    expect(examples[0]?.command).toContain("records query");
-
-    const searchExample = examples.find((example) =>
-      example.command.includes("--search"),
-    );
-    expect(searchExample?.command).toContain("--search garcia");
-    expect(searchExample?.raw).toContain('"search": { "term": "garcia" }');
-  });
-
-  it("returns fallback examples for simple commands", () => {
-    const examples = getCommandExamples("schemas list");
-
-    expect(examples.length).toBeGreaterThan(0);
-    expect(examples[0]?.command).toContain("schemas list");
-  });
-
-  it("returns schema field examples filtered by member type", () => {
-    const examples = getCommandExamples("schemas fields create", { type: "member" });
-
-    expect(examples).toHaveLength(1);
-    expect(examples[0]?.command).toContain('"type":"MemberField"');
-    expect(examples[0]?.description).toBe("Member field");
-  });
-
-  it("returns monthly and daily variants for schedule fields", () => {
-    const examples = getCommandExamples("schemas fields create", { type: "schedule" });
-
-    expect(examples).toHaveLength(2);
-    expect(examples.map((example) => example.description)).toEqual([
-      "Schedule field (monthly)",
-      "Schedule field (daily)",
-    ]);
-    expect(examples[0]?.command).toContain('"type":"ScheduleField"');
-    expect(examples[0]?.command).toContain('"frequency":"monthly"');
-    expect(examples[1]?.command).toContain('"frequency":"daily"');
-  });
-
-  it("covers every backend number field variant", () => {
-    const examples = getCommandExamples("schemas fields create", { type: "number" });
-
-    expect(examples).toHaveLength(6);
-
-    const descriptions = examples.map((example) => example.description);
-    expect(descriptions).toEqual([
-      "Number field (plain integer)",
-      "Number field (decimal with thousands)",
-      "Number field (currency € prefix)",
-      "Number field (currency $ suffix)",
-      "Number field (percentage)",
-      "Number field (duration HH:MM)",
-    ]);
-
-    expect(examples[0]?.command).toContain('"slug":"quantity"');
-    expect(examples[0]?.command).toContain('"format":"number"');
-
-    const eurCurrency = examples[2]?.command ?? "";
-    expect(eurCurrency).toContain('"format":"currency"');
-    expect(eurCurrency).toContain('"symbolEnabled":true');
-    expect(eurCurrency).toContain('"symbolPosition":"before"');
-    expect(eurCurrency).toContain('"symbolValue":"€"');
-
-    const usdCurrency = examples[3]?.command ?? "";
-    expect(usdCurrency).toContain('"symbolPosition":"right"');
-    expect(usdCurrency).toContain('"symbolValue":" $"');
-
-    expect(examples[4]?.command).toContain('"format":"percentage"');
-    expect(examples[5]?.command).toContain('"format":"duration"');
-    expect(examples[5]?.command).toContain('"durationFormat":"HH:MM"');
-  });
-
-  it("returns canonical automation creation examples", () => {
-    const examples = getCommandExamples("automations create");
-
-    expect(examples.length).toBeGreaterThanOrEqual(3);
-    expect(examples[0]?.command).toContain("--trigger-type scheduled");
-    expect(examples.some((example) => example.command.includes("--trigger-type record_changed"))).toBe(
-      true,
-    );
-  });
-
-  it("returns automation trigger, webhook, and connection examples", () => {
-    expect(getCommandExamples("automations trigger set")).not.toHaveLength(0);
-    expect(getCommandExamples("automations webhook set")).not.toHaveLength(0);
-    expect(getCommandExamples("automations connections create")).not.toHaveLength(0);
-    expect(getCommandExamples("automations connections update")).not.toHaveLength(0);
-  });
-
-  it("includes raw payloads for key automation examples", () => {
-    const createExamples = getCommandExamples("automations create");
-    const actionExamples = getCommandExamples("automations actions add");
-    const webhookExamples = getCommandExamples("automations webhook set");
-
-    expect(createExamples.every((example) => typeof example.raw === "string" && example.raw.length > 0)).toBe(
-      true,
-    );
-    expect(actionExamples.some((example) => example.command.includes("--condition-json"))).toBe(true);
-    expect(actionExamples.some((example) => example.raw?.includes('"rawValue"'))).toBe(true);
-    expect(webhookExamples[0]?.raw).toContain("idempotencyKeyJsonPath");
-  });
-
-  it("covers every action type documented by the backend", () => {
-    const actionExamples = getCommandExamples("automations actions add");
-    const backendActionTypes = [
-      "create_record",
-      "update_record",
-      "search_records",
-      "send_message",
-      "http_request",
-      "execute_plugin",
-      "generate_document",
-    ];
-
-    for (const type of backendActionTypes) {
-      expect(
-        actionExamples.some((example) => example.command.includes(`--type ${type}`)),
-      ).toBe(true);
-    }
-  });
-
-  it("documents send_message with wrapped {rawValue, source} values keyed by recipients/subject/body", () => {
-    const actionExamples = getCommandExamples("automations actions add");
-    const sendMessage = actionExamples.find((example) =>
-      example.command.includes("--type send_message"),
-    );
-
-    expect(sendMessage?.command).toContain("--to customer@example.com");
-    expect(sendMessage?.command).toContain("--subject");
-    expect(sendMessage?.command).toContain("--message");
-    expect(sendMessage?.raw).toContain(`"recipients"`);
-    expect(sendMessage?.raw).toContain(`"rawValue"`);
-    expect(sendMessage?.raw).not.toContain(`"channel"`);
-  });
-
-  it("documents generate_document with template, schema, and file-field ids", () => {
-    const actionExamples = getCommandExamples("automations actions add");
-    const generateDocument = actionExamples.find((example) =>
-      example.command.includes("--type generate_document"),
-    );
-
-    expect(generateDocument?.command).toContain("--document-template");
-    expect(generateDocument?.command).toContain("--target-schema");
-    expect(generateDocument?.command).toContain("--target-file-field");
-    expect(generateDocument?.raw).toContain("documentTemplateId");
-    expect(generateDocument?.raw).toContain("targetFileFieldId");
-  });
-
-  it("covers every records query operator documented by the backend", () => {
-    const examples = getCommandExamples("records query");
-    const backendOperators = [
-      "eq",
-      "neq",
-      "gt",
-      "gte",
-      "lt",
-      "lte",
-      "contains",
-      "in",
-      "is_empty",
-      "is_not_empty",
-    ];
-
-    for (const op of backendOperators) {
-      expect(
-        examples.some((example) => example.raw?.includes(`"op": "${op}"`)),
-        `expected an example with op "${op}"`,
-      ).toBe(true);
-    }
-  });
-
-  it("offers minimal, multi-type, and reference records create examples", () => {
-    const examples = getCommandExamples("records create");
-
-    expect(examples).toHaveLength(3);
-    expect(examples[0]?.raw).toContain('"contact-name"');
-    expect(examples[1]?.raw).toContain('"customer-ref"');
-    expect(examples[1]?.raw).toContain('"owner"');
-    expect(examples[2]?.raw).toContain('"customer-ref"');
-    expect(examples[2]?.response).toContain("data_field_reference_not_found");
-  });
-
-  it("provides full/minimal/folder variants for schemas create", () => {
-    const examples = getCommandExamples("schemas create");
-
-    expect(examples).toHaveLength(3);
-    expect(examples.some((example) => example.raw?.includes('"folderId"'))).toBe(true);
-    expect(examples.every((example) => example.command.startsWith("zinkee --json schemas create"))).toBe(
-      true,
-    );
-  });
-
-  it("covers all widget types in displays widgets create", () => {
-    const examples = getCommandExamples("displays widgets create");
-    const rawPayloads = examples.map((example) => example.raw ?? "");
-
-    expect(examples.length).toBeGreaterThanOrEqual(7);
-    for (const widgetType of ["TABLE_OR_SUBTABLE", "DETAIL", "KPI", "CHART", "TIMELINE", "KANBAN", "HIERARCHY"]) {
-      expect(rawPayloads.some((raw) => raw.includes(`"type": "${widgetType}"`))).toBe(true);
-    }
-  });
-
-  it("does not teach legacy system columns in display widget examples", () => {
-    const legacyColumns = ["id", "createdat", "updatedat", "createdby", "updatedby"];
-    const commands = ["displays widgets create", "displays widgets update", "displays list", "displays get"];
-
-    for (const command of commands) {
-      for (const example of getCommandExamples(command)) {
-        for (const column of legacyColumns) {
-          expect(example.command).not.toContain(`--field ${column}`);
-        }
-
-        const examplePayloads = [example.raw, example.response].filter(Boolean);
-        for (const payload of examplePayloads) {
-          expect(payload).not.toMatch(/"fields"\s*:\s*\[[^\]]*"(id|createdat|updatedat|createdby|updatedby)"/);
-          expect(payload).not.toMatch(/"fieldCalc"\s*:\s*"(id|createdat|updatedat|createdby|updatedby)"/);
-        }
-      }
-    }
-  });
-
-  it("covers REFERENCE, MEMBER and DATE variants in displays variables create", () => {
-    const examples = getCommandExamples("displays variables create");
-    const rawPayloads = examples.map((example) => example.raw ?? "");
-
-    expect(examples.length).toBeGreaterThanOrEqual(6);
-    for (const variableType of ["REFERENCE", "MEMBER", "DATE"]) {
-      expect(rawPayloads.some((raw) => raw.includes(`"type": "${variableType}"`))).toBe(true);
-    }
-    expect(rawPayloads.some((raw) => raw.includes('"dynamicOption": "thisMonth"'))).toBe(true);
-  });
-
-  it("documents navigation resources move as schema-only with no resourceType", () => {
-    const examples = getCommandExamples("navigation resources move");
-    const rawPayloads = examples.map((example) => example.raw ?? "");
-
-    expect(examples.length).toBeGreaterThanOrEqual(2);
-    // Navigation only moves schemas now, so the payload no longer carries a
-    // resourceType and the example commands must not pass --type.
-    for (const raw of rawPayloads) {
-      expect(raw).not.toContain("resourceType");
-    }
-    for (const example of examples) {
-      expect(example.command).not.toContain("--type");
-    }
-    // Covers moving into a folder and back to the root folder.
-    expect(
-      rawPayloads.some((raw) => raw.includes('"targetFolderId": "00000000-0000-0000-0000-000000000000"')),
-    ).toBe(true);
-  });
-
-  it("covers slug and UUID variants in teamspace resources publish", () => {
-    const examples = getCommandExamples("teamspace resources publish");
-
-    expect(examples.length).toBeGreaterThanOrEqual(4);
-    expect(examples.some((example) => example.command.includes("customer-records"))).toBe(true);
-    expect(examples.some((example) => example.command.includes("2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e"))).toBe(
-      true,
-    );
-  });
-
-  it("enriches displays list with the documented response body", () => {
-    const examples = getCommandExamples("displays list");
-
-    expect(examples).toHaveLength(1);
-    expect(examples[0]?.response).toContain('"layoutTemplate": "widget_row_tabs"');
-    expect(examples[0]?.response).toContain('"layoutTemplate": "freeform"');
-    expect(examples[0]?.response).toContain('"layoutTemplate": "grid"');
-    expect(examples[0]?.response).toContain('"folder"');
-    expect(examples[0]?.response).toContain('"isRoot": true');
-  });
-
-  it("attaches a response body to schemas create and teamspace resources publish", () => {
-    const schemaExamples = getCommandExamples("schemas create");
-    const publishExamples = getCommandExamples("teamspace resources publish");
-
-    expect(schemaExamples[0]?.response).toContain('"schemaId"');
-    expect(publishExamples[0]?.response).toContain('"targetFolder"');
-    expect(publishExamples[0]?.response).toContain('"previousFolder"');
-  });
-
-  it("attaches a rich response body to displays get", () => {
-    const examples = getCommandExamples("displays get");
-
-    expect(examples).toHaveLength(1);
-    expect(examples[0]?.response).toContain('"widgets"');
-    expect(examples[0]?.response).toContain('"variables"');
-    expect(examples[0]?.response).toContain('"crossWidgetFilter"');
-    expect(examples[0]?.response).toContain('"navigationTargets"');
-  });
-
-  it("attaches responses to automations reads and mutations", () => {
-    expect(getCommandExamples("automations list")[0]?.response).toContain('"triggerType"');
-    expect(getCommandExamples("automations get")[0]?.response).toContain('"trigger"');
-    expect(getCommandExamples("automations create")[0]?.response).toContain('"automationId"');
-    expect(getCommandExamples("automations create")[0]?.response).toContain('"webhookEndpoint"');
-    expect(getCommandExamples("automations webhook set")[0]?.response).toContain('"endpointUrl"');
-    expect(getCommandExamples("automations folders create")[0]?.response).toContain('"automationCount": 0');
-    expect(getCommandExamples("automations connections create")[0]?.response).toContain(
-      '"ownerMemberId"',
-    );
-  });
-
-  it("covers every profiles and config subcommand with an example that emits JSON", () => {
-    const profileAndConfigCommands = [
-      "profiles list",
-      "profiles get",
-      "profiles use",
-      "profiles add",
-      "profiles update",
-      "profiles remove",
-      "config path",
-      "config show",
-      "config validate",
-    ];
-
-    for (const commandName of profileAndConfigCommands) {
-      const examples = getCommandExamples(commandName);
-      expect(examples.length, `${commandName} has no examples`).toBeGreaterThan(0);
-      for (const example of examples) {
-        expect(example.command.startsWith("zinkee "), `${commandName}: ${example.command}`).toBe(true);
-        expect(example.response, `${commandName} missing response`).toBeTruthy();
-      }
-    }
-
-    expect(getCommandExamples("profiles list")[0]?.response).toContain('"apiKey": "********cdef"');
-    expect(getCommandExamples("config show")[0]?.response).toContain('"defaultProfile": "prod"');
-    expect(getCommandExamples("config validate")[0]?.response).toContain('"valid": true');
-  });
-
-  it("wraps example responses in the { data, meta } JSON envelope", () => {
-    const listExample = getCommandExamples("schemas list")[0];
-    const parsed = JSON.parse(listExample?.response ?? "{}");
-
-    expect(parsed).toHaveProperty("data");
-    expect(parsed).toHaveProperty("meta");
-    expect(parsed.meta).toMatchObject({ command: "schemas list" });
-    expect(Array.isArray(parsed.data)).toBe(true);
-
-    // get/detail commands wrap a single object under data, not an array
-    const getExample = getCommandExamples("schemas get")[0];
-    const parsedGet = JSON.parse(getExample?.response ?? "{}");
-    expect(Array.isArray(parsedGet.data)).toBe(false);
-    expect(parsedGet.data).toHaveProperty("fields");
-  });
-
-  it.each(Object.keys(commandRegistry))(
-    "returns at least one example for %s",
-    (commandName) => {
-      const examples = getCommandExamples(commandName);
-      expect(examples.length, `${commandName} has no examples`).toBeGreaterThan(0);
-      for (const example of examples) {
-        expect(example.command, `${commandName} example missing command`).toBeTruthy();
-        expect(example.description, `${commandName} example missing description`).toBeTruthy();
-      }
-    },
-  );
-
-  it("getResolvedCommandExamples is synchronous and matches getCommandExamples", () => {
-    for (const commandName of Object.keys(commandRegistry)) {
-      const resolved = getResolvedCommandExamples(commandName);
-      expect(resolved, `${commandName} resolved must not be a thenable`).not.toHaveProperty("then");
-      expect(resolved).toEqual(getCommandExamples(commandName));
-    }
-  });
-});

package/src/utils/output.test.ts

@@ -1,65 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { getCommandMeta } from "../command-registry.js";
-
-import { buildJsonError, buildJsonSuccess, folderColumns } from "./output.js";
-
-describe("folderColumns", () => {
-  it("flattens a named folder into id/name/isRoot columns", () => {
-    expect(folderColumns({ id: "f1", name: "Finance", isRoot: false })).toEqual({
-      folderId: "f1",
-      folderName: "Finance",
-      folderIsRoot: "false",
-    });
-  });
-
-  it("renders the root folder (null name) as (root)", () => {
-    expect(folderColumns({ id: "root-1", name: null, isRoot: true })).toEqual({
-      folderId: "root-1",
-      folderName: "(root)",
-      folderIsRoot: "true",
-    });
-  });
-
-  it("leaves every column empty when there is no folder", () => {
-    expect(folderColumns(undefined)).toEqual({
-      folderId: "",
-      folderName: "",
-      folderIsRoot: "",
-    });
-  });
-});
-
-describe("buildJsonSuccess", () => {
-  it("wraps data in the standard success envelope", () => {
-    expect(buildJsonSuccess([{ id: "1" }], { command: "schemas list" })).toEqual({
-      data: [{ id: "1" }],
-      meta: { command: "schemas list" },
-    });
-  });
-});
-
-describe("buildJsonError", () => {
-  it("wraps error details in the standard error envelope", () => {
-    expect(
-      buildJsonError({ reason: "invalid_request", message: "Bad request" }, {}),
-    ).toMatchObject({
-      error: { reason: "invalid_request" },
-      meta: {},
-    });
-  });
-});
-
-describe("command registry", () => {
-  it("looks up registered command metadata cleanly", () => {
-    const meta = getCommandMeta("profiles add");
-
-    expect(meta).toEqual({
-      command: "profiles add",
-      accessLevel: "write",
-      supportsExample: true,
-      supportsRaw: false,
-      output: "json-only",
-    });
-  });
-});

package/src/utils/output.ts

@@ -1,154 +0,0 @@
-import Table from "cli-table3";
-
-import type {
-  JsonEnvelopeMeta,
-  JsonErrorEnvelope,
-  JsonSuccessEnvelope,
-  OutputFormat,
-} from "../types.js";
-
-export interface TableColumn {
-  key: string;
-  label: string;
-}
-
-export interface TableCell {
-  key: string;
-  value: string;
-}
-
-export interface TableRow {
-  cells: TableCell[];
-}
-
-export interface OutputWriter {
-  write(chunk: string): unknown;
-}
-
-function stringifyCellValue(value: unknown): string {
-  if (value === null || value === undefined) {
-    return "";
-  }
-
-  if (typeof value === "string") {
-    return value;
-  }
-
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return String(value);
-  }
-
-  return JSON.stringify(value);
-}
-
-export function buildJsonSuccess<TData, TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta>(
-  data: TData,
-  meta: TMeta = {} as TMeta,
-): JsonSuccessEnvelope<TData, TMeta> {
-  return { data, meta };
-}
-
-export function buildJsonError<TErr, TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta>(
-  error: TErr,
-  meta: TMeta = {} as TMeta,
-): JsonErrorEnvelope<TErr, TMeta> {
-  return { error, meta };
-}
-
-export function buildTableColumns(keys: readonly string[]): readonly TableColumn[] {
-  return keys.map((key) => ({ key, label: key }));
-}
-
-export interface FolderLocation {
-  id?: string;
-  name?: string | null;
-  isRoot?: boolean;
-}
-
-/** Column keys, in order, produced by {@link folderColumns}. Append them to a table's key list. */
-export const FOLDER_TABLE_KEYS = ["folderId", "folderName", "folderIsRoot"] as const;
-
-/**
- * Flattens the API `folder` object (`{ id, name, isRoot }`) into the folderId/folderName/folderIsRoot table columns.
- * The root folder arrives with a null name, so folderName renders it as "(root)". A missing folder (e.g. a workspace
- * without a default group) leaves every column empty.
- */
-export function folderColumns(folder: FolderLocation | null | undefined): {
-  folderId: string;
-  folderName: string;
-  folderIsRoot: string;
-} {
-  if (!folder) {
-    return { folderId: "", folderName: "", folderIsRoot: "" };
-  }
-
-  return {
-    folderId: folder.id ?? "",
-    folderName: folder.name ?? (folder.isRoot === true ? "(root)" : ""),
-    folderIsRoot: folder.isRoot === undefined ? "" : String(folder.isRoot),
-  };
-}
-
-export function buildTableRows(
-  rows: readonly Record<string, unknown>[],
-  columns: readonly TableColumn[],
-): readonly TableRow[] {
-  return rows.map((row) => ({
-    cells: columns.map((column) => ({
-      key: column.key,
-      value: stringifyCellValue(row[column.key]),
-    })),
-  }));
-}
-
-function getWriter(writer?: OutputWriter): OutputWriter {
-  return writer ?? process.stdout;
-}
-
-export function printJson(value: unknown, writer?: OutputWriter): void {
-  getWriter(writer).write(`${JSON.stringify(value, null, 2)}\n`);
-}
-
-export function printTable(
-  rows: readonly Record<string, unknown>[],
-  keys?: readonly string[],
-  writer?: OutputWriter,
-): void {
-  if (rows.length === 0) {
-    getWriter(writer).write("No results.\n");
-    return;
-  }
-
-  const firstRow = rows[0];
-
-  if (!firstRow) {
-    getWriter(writer).write("No results.\n");
-    return;
-  }
-
-  const headings = [...(keys ?? Object.keys(firstRow))];
-  const table = new Table({
-    head: headings,
-    wordWrap: true,
-  });
-
-  for (const row of rows) {
-    table.push(headings.map((heading) => stringifyCellValue(row[heading])));
-  }
-
-  getWriter(writer).write(`${table.toString()}\n`);
-}
-
-export function printOutput(
-  format: OutputFormat,
-  rows: readonly Record<string, unknown>[],
-  keys?: readonly string[],
-  writer?: OutputWriter,
-): void {
-  if (format === "json") {
-    printJson(rows, writer);
-    return;
-  }
-
-  printTable(rows, keys, writer);
-}