zinkee 0.1.0

package/src/utils/output.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+
+import { getCommandMeta } from "../command-registry.js";
+
+import { buildJsonError, buildJsonSuccess } from "./output.js";
+
+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

@@ -0,0 +1,124 @@
+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 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);
+}

package/src/utils/schema-fields.ts

@@ -0,0 +1,529 @@
+import type { JsonObject } from "../types.js";
+import { CliError } from "./errors.js";
+
+export type SchemaFieldTypeKey =
+  | "text"
+  | "number"
+  | "date"
+  | "option"
+  | "file"
+  | "reference"
+  | "formula"
+  | "member"
+  | "autoincremental";
+
+export interface SchemaFieldTypeDefinition {
+  key: SchemaFieldTypeKey;
+  className: string;
+  aliases: readonly string[];
+  description: string;
+  rawShape: string;
+  examplePayload: JsonObject;
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toJsonObject(value: unknown): JsonObject | undefined {
+  return isJsonObject(value) ? value : undefined;
+}
+
+function toStringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function toNumberValue(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+
+  return undefined;
+}
+
+const fieldTypeDefinitions = [
+  {
+    key: "text",
+    className: "TextField",
+    aliases: ["text", "TextField"],
+    description: "Plain text field.",
+    rawShape:
+      '{"type":"text","slug":"name","label":"Name"}',
+    examplePayload: {
+      type: "text",
+      slug: "name",
+      label: "Name",
+    },
+  },
+  {
+    key: "number",
+    className: "NumberField",
+    aliases: ["number", "NumberField"],
+    description: "Numeric field.",
+    rawShape:
+      '{"type":"number","slug":"price-eur","label":"Price EUR","config":{"defaultValue":"0","formatOptions":{"format":"number","decimals":2,"thousandsSeparator":true,"symbolEnabled":true,"symbolValue":" €","symbolPosition":"right"}}}',
+    examplePayload: {
+      type: "number",
+      slug: "price-eur",
+      label: "Price EUR",
+      config: {
+        defaultValue: "0",
+        formatOptions: {
+          format: "number",
+          decimals: 2,
+          thousandsSeparator: true,
+          symbolEnabled: true,
+          symbolValue: " €",
+          symbolPosition: "right",
+        },
+      },
+    },
+  },
+  {
+    key: "date",
+    className: "DateField",
+    aliases: ["date", "DateField"],
+    description: "Date or datetime field.",
+    rawShape:
+      '{"type":"date","slug":"due-date","label":"Due date"}',
+    examplePayload: {
+      type: "date",
+      slug: "due-date",
+      label: "Due date",
+    },
+  },
+  {
+    key: "option",
+    className: "OptionField",
+    aliases: ["option", "OptionField"],
+    description: "Dropdown/select field with options.",
+    rawShape:
+      '{"type":"option","slug":"status","label":"Status","config":{"options":[{"id":1,"name":"Open","color":"default"},{"id":2,"name":"Closed","color":"success"}]}}',
+    examplePayload: {
+      type: "option",
+      slug: "status",
+      label: "Status",
+      config: {
+        options: [
+          {
+            id: 1,
+            name: "Open",
+            color: "default",
+          },
+          {
+            id: 2,
+            name: "Closed",
+            color: "success",
+          },
+        ],
+      },
+    },
+  },
+  {
+    key: "file",
+    className: "FileField",
+    aliases: ["file", "FileField"],
+    description: "File attachment field.",
+    rawShape:
+      '{"type":"file","slug":"attachment","label":"Attachment"}',
+    examplePayload: {
+      type: "file",
+      slug: "attachment",
+      label: "Attachment",
+    },
+  },
+  {
+    key: "reference",
+    className: "ReferenceField",
+    aliases: ["reference", "ReferenceField"],
+    description: "Reference to another schema.",
+    rawShape:
+      '{"type":"reference","slug":"project","label":"Project","config":{"targetSchema":"<schema-uuid>","targetDisplayField":"<field-uuid>","deleteBehavior":"SET_NULL"}}',
+    examplePayload: {
+      type: "reference",
+      slug: "project",
+      label: "Project",
+      config: {
+        targetSchema: "<schema-uuid>",
+        targetDisplayField: "<field-uuid>",
+        deleteBehavior: "SET_NULL",
+      },
+    },
+  },
+  {
+    key: "formula",
+    className: "FormulaField",
+    aliases: ["formula", "FormulaField"],
+    description: "Calculated field from a formula.",
+    rawShape:
+      '{"type":"formula","slug":"total","label":"Total","config":{"formulaText":"{price} * {quantity}"}}',
+    examplePayload: {
+      type: "formula",
+      slug: "total",
+      label: "Total",
+      config: {
+        formulaText: "{price} * {quantity}",
+      },
+    },
+  },
+  {
+    key: "member",
+    className: "MemberField",
+    aliases: ["member", "MemberField"],
+    description: "Workspace member field.",
+    rawShape:
+      '{"type":"member","slug":"owner","label":"Owner","config":{"defaultValue":"<member-id>"}}',
+    examplePayload: {
+      type: "member",
+      slug: "owner",
+      label: "Owner",
+      config: {
+        defaultValue: "<member-id>",
+      },
+    },
+  },
+  {
+    key: "autoincremental",
+    className: "AutoIncrementalField",
+    aliases: [
+      "autoincremental",
+      "auto-incremental",
+      "auto_incremental",
+      "AutoIncrementalField",
+    ],
+    description: "Auto-generated incremental counter.",
+    rawShape:
+      '{"type":"autoincremental","slug":"counter","label":"Counter","config":{"segmentedByFieldId":null}}',
+    examplePayload: {
+      type: "autoincremental",
+      slug: "counter",
+      label: "Counter",
+      config: {
+        segmentedByFieldId: null,
+      },
+    },
+  },
+] as const satisfies readonly SchemaFieldTypeDefinition[];
+
+const fieldTypeDefinitionByAlias = new Map(
+  fieldTypeDefinitions.flatMap((definition) =>
+    definition.aliases.map((alias) => [alias.trim().toLowerCase(), definition] as const),
+  ),
+);
+
+const fieldTypeDefinitionByClassName = new Map<string, SchemaFieldTypeDefinition>(
+  fieldTypeDefinitions.map((definition) => [definition.className, definition] as const),
+);
+
+const optionValidationMessage =
+  'Option fields require an "options" array with at least one entry like {"id":1,"name":"Open","color":"default"}.';
+
+export function getSchemaFieldTypeDefinitions(): readonly SchemaFieldTypeDefinition[] {
+  return fieldTypeDefinitions;
+}
+
+export function listSchemaFieldTypes(): readonly SchemaFieldTypeKey[] {
+  return fieldTypeDefinitions.map((definition) => definition.key);
+}
+
+export function formatSchemaFieldTypes(): string {
+  return listSchemaFieldTypes().join(", ");
+}
+
+export function resolveSchemaFieldType(
+  input: string | undefined,
+): SchemaFieldTypeDefinition | undefined {
+  if (!input) {
+    return undefined;
+  }
+
+  return fieldTypeDefinitionByAlias.get(input.trim().toLowerCase());
+}
+
+export function resolveSchemaFieldTypeByClassName(
+  className: string | undefined,
+): SchemaFieldTypeDefinition | undefined {
+  if (!className) {
+    return undefined;
+  }
+
+  return fieldTypeDefinitionByClassName.get(className);
+}
+
+export function normalizeSchemaFieldType(input: string): string {
+  const definition = resolveSchemaFieldType(input);
+
+  if (definition) {
+    return definition.className;
+  }
+
+  if (/^[a-z]/.test(input) && !input.endsWith("Field")) {
+    return `${input.charAt(0).toUpperCase()}${input.slice(1)}Field`;
+  }
+
+  return input;
+}
+
+export function assertSupportedSchemaFieldType(type: string): void {
+  if (!resolveSchemaFieldTypeByClassName(type)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Unsupported field type "${type}". Valid types: ${formatSchemaFieldTypes()}.`,
+    );
+  }
+}
+
+interface OptionEntry {
+  [key: string]: string | number;
+  id: number;
+  name: string;
+  color: string;
+}
+
+function normalizeOptionEntries(entries: readonly unknown[]): OptionEntry[] {
+  return entries.flatMap((entry) => {
+    if (!isJsonObject(entry)) {
+      return [];
+    }
+
+    const id = toNumberValue(entry.id);
+    const name = toStringValue(entry.name) ?? toStringValue(entry.label);
+    const color = toStringValue(entry.color) ?? "default";
+
+    if (id === undefined || !name) {
+      return [];
+    }
+
+    return [{ id, name, color }];
+  });
+}
+
+function normalizeOptionPayload(input: JsonObject): JsonObject {
+  const additionalProperties = toJsonObject(input.additionalProperties) ?? {};
+  const config = toJsonObject(input.config);
+  const rootOptions = Array.isArray(input.options) ? input.options : undefined;
+  const nestedOptions = Array.isArray(additionalProperties.options)
+    ? additionalProperties.options
+    : Array.isArray(config?.options)
+      ? config.options
+      : undefined;
+  const optionObjects = normalizeOptionEntries(
+    nestedOptions ??
+      (Array.isArray(rootOptions) ? rootOptions : []),
+  );
+
+  if (optionObjects.length === 0) {
+    throw new CliError("invalid_cli_usage", optionValidationMessage);
+  }
+
+  const { options: _options, additionalProperties: _additionalProperties, ...rest } = input;
+  const defaultValue =
+    config?.defaultValue ?? input.defaultValue ?? additionalProperties.defaultValue;
+  const conditionalFormatting =
+    config?.conditionalFormatting ?? additionalProperties.conditionalFormatting;
+  const buttonConfig = config?.buttonConfig ?? additionalProperties.buttonConfig;
+
+  return {
+    ...rest,
+    config: {
+      ...(config ?? {}),
+      options: optionObjects,
+      ...(defaultValue !== undefined ? { defaultValue } : {}),
+      ...(conditionalFormatting !== undefined ? { conditionalFormatting } : {}),
+      ...(buttonConfig !== undefined ? { buttonConfig } : {}),
+    },
+  };
+}
+
+function normalizeReferencePayload(input: JsonObject): JsonObject {
+  const additionalProperties = toJsonObject(input.additionalProperties) ?? {};
+  const config = toJsonObject(input.config) ?? {};
+  const targetSchema =
+    config.targetSchema ?? input.targetSchema ?? additionalProperties.targetSchema;
+  const targetDisplayField =
+    config.targetDisplayField ??
+    input.targetDisplayField ??
+    additionalProperties.targetDisplayField;
+  const deleteBehavior =
+    config.deleteBehavior ?? input.deleteBehavior ?? additionalProperties.deleteBehavior;
+  const defaultValue =
+    config.defaultValue ?? input.defaultValue ?? additionalProperties.defaultValue;
+  const filterFields =
+    config.filterFields ?? input.filterFields ?? additionalProperties.filterFields;
+  const descriptionFields =
+    config.descriptionFields ??
+    input.descriptionFields ??
+    additionalProperties.descriptionFields;
+  const conditionalFormatting =
+    config.conditionalFormatting ??
+    input.conditionalFormatting ??
+    additionalProperties.conditionalFormatting;
+
+  const normalized: JsonObject = {
+    ...input,
+  };
+
+  normalized.config = {
+    ...config,
+    ...(targetSchema !== undefined ? { targetSchema } : {}),
+    ...(targetDisplayField !== undefined ? { targetDisplayField } : {}),
+    ...(deleteBehavior !== undefined ? { deleteBehavior } : {}),
+    ...(defaultValue !== undefined ? { defaultValue } : {}),
+    ...(filterFields !== undefined ? { filterFields } : {}),
+    ...(descriptionFields !== undefined ? { descriptionFields } : {}),
+    ...(conditionalFormatting !== undefined ? { conditionalFormatting } : {}),
+  };
+
+  const normalizedConfig = toJsonObject(normalized.config) ?? {};
+
+  if (
+    !toStringValue(normalizedConfig.targetSchema) ||
+    !toStringValue(normalizedConfig.targetDisplayField)
+  ) {
+    const definition = resolveSchemaFieldType("reference")!;
+    throw new CliError(
+      "invalid_cli_usage",
+      `Reference fields require "targetSchema" and "targetDisplayField". Expected raw shape: ${definition.rawShape}`,
+    );
+  }
+
+  return normalized;
+}
+
+function normalizeFormulaPayload(input: JsonObject): JsonObject {
+  const { status: _status, ...rest } = input;
+  const rawAdditionalProperties = toJsonObject(input.additionalProperties);
+  const rawConfig = toJsonObject(input.config);
+  const { status: _additionalStatus, ...additionalProperties } =
+    rawAdditionalProperties ?? {};
+  const { status: _configStatus, ...config } = rawConfig ?? {};
+  const formulaText =
+    config.formulaText ??
+    rest.formulaText ??
+    rest.expression ??
+    additionalProperties.formulaText ??
+    additionalProperties.expression;
+
+  const normalized: JsonObject = {
+    ...rest,
+  };
+
+  normalized.config = {
+    ...config,
+    ...(formulaText !== undefined ? { formulaText } : {}),
+    ...(config.uiFormatKind !== undefined ? { uiFormatKind: config.uiFormatKind } : {}),
+    ...(config.defaultValue !== undefined ? { defaultValue: config.defaultValue } : {}),
+    ...(config.numberFormatOptions !== undefined
+      ? { numberFormatOptions: config.numberFormatOptions }
+      : {}),
+    ...(config.dateFormatOptions !== undefined
+      ? { dateFormatOptions: config.dateFormatOptions }
+      : {}),
+    ...(config.conditionalFormatting !== undefined
+      ? { conditionalFormatting: config.conditionalFormatting }
+      : {}),
+  };
+
+  const normalizedConfig = toJsonObject(normalized.config) ?? {};
+
+  if (!toStringValue(normalizedConfig.formulaText)) {
+    const definition = resolveSchemaFieldType("formula")!;
+    throw new CliError(
+      "invalid_cli_usage",
+      `Formula fields require "formulaText". Expected raw shape: ${definition.rawShape}`,
+    );
+  }
+
+  return normalized;
+}
+
+export function normalizeSchemaFieldCreatePayload(input: JsonObject): JsonObject {
+  const rawType = toStringValue(input.type);
+  const normalizedType = rawType ? normalizeSchemaFieldType(rawType) : undefined;
+  const definition = resolveSchemaFieldTypeByClassName(normalizedType);
+
+  if (!definition) {
+    return input;
+  }
+
+  const normalizedWithType: JsonObject = {
+    ...input,
+    type: definition.className,
+  };
+
+  switch (definition.key) {
+    case "option":
+      return normalizeOptionPayload(normalizedWithType);
+    case "reference":
+      return normalizeReferencePayload(normalizedWithType);
+    case "formula":
+      return normalizeFormulaPayload(normalizedWithType);
+    case "autoincremental": {
+      const config = toJsonObject(normalizedWithType.config) ?? {};
+      const segmentedByFieldId =
+        config.segmentedByFieldId ??
+        normalizedWithType.segmentedByFieldId ??
+        null;
+      return {
+        ...normalizedWithType,
+        config: {
+          ...config,
+          segmentedByFieldId,
+          ...(config.conditionalFormatting !== undefined
+            ? { conditionalFormatting: config.conditionalFormatting }
+            : {}),
+        },
+      };
+    }
+    default:
+      return normalizedWithType;
+  }
+}
+
+export function normalizeSchemaFieldUpdatePayload(
+  type: string,
+  input: JsonObject,
+): JsonObject {
+  const definition = resolveSchemaFieldTypeByClassName(type);
+
+  if (definition?.key === "formula") {
+    return normalizeFormulaPayload(input);
+  }
+
+  return input;
+}
+
+export function buildSchemaFieldCreateHelpText(): string {
+  const sections = fieldTypeDefinitions.map(
+    (definition) =>
+      `  - ${definition.key}: ${definition.description}\n    raw: ${definition.rawShape}`,
+  );
+
+  return [
+    "",
+    "Valid field types:",
+    `  ${formatSchemaFieldTypes()}`,
+    "",
+    "Raw payload shapes by type:",
+    ...sections,
+    "",
+    'Use "zinkee --example schemas fields create --type <type>" to show a concrete example for one type.',
+  ].join("\n");
+}
+
+export function buildSchemaFieldCreateValidationMessage(type: string): string {
+  const definition = resolveSchemaFieldTypeByClassName(type);
+
+  if (!definition) {
+    return `Invalid payload for field type "${type}". Valid types: ${formatSchemaFieldTypes()}.`;
+  }
+
+  return `Invalid payload for field type "${definition.key}". Expected raw shape: ${definition.rawShape}`;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}