zinkee 0.1.41 → 0.1.43

package/src/commands/formulas.ts

@@ -0,0 +1,243 @@
+import type { Writable } from "node:stream";
+
+import { Command, InvalidArgumentError } from "commander";
+
+import {
+  FormulasApi,
+  type FormulaRecomputeInput,
+  type FormulaRecomputeResponse,
+} from "../api/formulas.js";
+import { ApiClient } from "../client.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
+import {
+  normalizeUuidOrSlug,
+  type NormalizedUuidOrSlug,
+} from "../parsers/selectors.js";
+import { resolveRuntimeContext } from "../runtime-context.js";
+import type { RuntimeOverrides } from "../types.js";
+import { CliError } from "../utils/errors.js";
+import { buildJsonSuccess } from "../utils/output.js";
+
+interface CommandIo {
+  write(chunk: string): unknown;
+}
+
+export interface RegisterFormulasCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions extends RuntimeOverrides {}
+
+interface ConfirmedCommandOptions {
+  yes?: boolean;
+}
+
+function getCommandIo(stdout: CommandIo | undefined): CommandIo {
+  return stdout ?? (process.stdout as Writable);
+}
+
+function writeLine(stdout: CommandIo, value: string): void {
+  stdout.write(`${value}\n`);
+}
+
+function getGlobalOptions(command: Command): GlobalOptions {
+  return command.optsWithGlobals<GlobalOptions>();
+}
+
+function toConfigurationError(filePath: string, error: unknown): never {
+  if (error instanceof CliError) {
+    throw error;
+  }
+
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  ) {
+    throw new CliError("configuration_error", `Config file not found at ${filePath}.`);
+  }
+
+  if (error instanceof Error) {
+    throw new CliError("configuration_error", error.message);
+  }
+
+  throw error;
+}
+
+function createFormulasApi(
+  command: Command,
+  filePath: string,
+): { api: FormulasApi; json: boolean; readOnly: boolean } {
+  try {
+    const config = readRuntimeConfig(filePath);
+    const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
+
+    if (!runtime.baseUrl) {
+      throw new CliError(
+        "configuration_error",
+        `Resolved profile "${runtime.profile}" is missing a base URL.`,
+      );
+    }
+
+    return {
+      api: new FormulasApi(
+        new ApiClient({
+          baseUrl: runtime.baseUrl,
+          apiKey: runtime.apiKey,
+        }),
+      ),
+      json: runtime.json,
+      readOnly: runtime.readOnly,
+    };
+  } catch (error) {
+    toConfigurationError(filePath, error);
+  }
+}
+
+function ensureWritable(commandName: string, readOnly: boolean): void {
+  if (readOnly) {
+    throw new CliError(
+      "command_not_allowed_in_read_only_mode",
+      `Command "${commandName}" is not allowed in read-only mode.`,
+      {
+        commandMode: "write",
+        executionMode: "read-only",
+      },
+    );
+  }
+}
+
+function ensureConfirmed(commandName: string, confirmed: boolean | undefined): void {
+  if (!confirmed) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Command "${commandName}" requires --yes because it may enqueue a large recalculation.`,
+    );
+  }
+}
+
+function parseUuidOrSlugSelector(input: string): NormalizedUuidOrSlug {
+  try {
+    return normalizeUuidOrSlug(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid selector.";
+    throw new InvalidArgumentError(message);
+  }
+}
+
+function emitResult(
+  stdout: CommandIo,
+  commandName: string,
+  result: FormulaRecomputeResponse,
+  configPath: string,
+  json: boolean,
+): void {
+  if (json) {
+    writeLine(
+      stdout,
+      JSON.stringify(buildJsonSuccess(result, { command: commandName, configPath })),
+    );
+    return;
+  }
+
+  writeLine(
+    stdout,
+    `Queued ${result.eventsQueued} formula recalculation event(s) for ${result.scope.toLowerCase()} scope (request ${result.requestId}).`,
+  );
+}
+
+async function recompute(
+  command: Command,
+  commandName: string,
+  input: FormulaRecomputeInput,
+  options: RegisterFormulasCommandsOptions,
+  requireConfirmation: boolean,
+  confirmed?: boolean,
+): Promise<void> {
+  const configPath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const { api, json, readOnly } = createFormulasApi(command, configPath);
+
+  ensureWritable(commandName, readOnly);
+  if (requireConfirmation) {
+    ensureConfirmed(commandName, confirmed);
+  }
+
+  const result = await api.recompute(input);
+  emitResult(stdout, commandName, result, configPath, json);
+}
+
+export function registerFormulasCommands(
+  program: Command,
+  options: RegisterFormulasCommandsOptions = {},
+): void {
+  const formulas = program
+    .command("formulas")
+    .description("Recalculate formula values");
+  const recomputeCommand = formulas
+    .command("recompute")
+    .description("Queue a full formula recalculation");
+
+  recomputeCommand
+    .command("field")
+    .description("Queue recalculation of one formula column")
+    .argument("<schema>", "schema UUID or slug", parseUuidOrSlugSelector)
+    .argument("<field>", "formula field UUID or slug", parseUuidOrSlugSelector)
+    .action(
+      async function action(
+        this: Command,
+        schema: NormalizedUuidOrSlug,
+        field: NormalizedUuidOrSlug,
+      ) {
+        await recompute(
+          this,
+          "formulas recompute field",
+          { scope: "FIELD", schema, field },
+          options,
+          false,
+        );
+      },
+    );
+
+  recomputeCommand
+    .command("schema")
+    .description("Queue recalculation of all active formulas in one schema")
+    .argument("<schema>", "schema UUID or slug", parseUuidOrSlugSelector)
+    .option("--yes", "confirm the potentially expensive recalculation")
+    .action(
+      async function action(
+        this: Command,
+        schema: NormalizedUuidOrSlug,
+        commandOptions: ConfirmedCommandOptions,
+      ) {
+        await recompute(
+          this,
+          "formulas recompute schema",
+          { scope: "SCHEMA", schema },
+          options,
+          true,
+          commandOptions.yes,
+        );
+      },
+    );
+
+  recomputeCommand
+    .command("workspace")
+    .description("Queue recalculation of all active formulas in the workspace")
+    .option("--yes", "confirm the potentially expensive recalculation")
+    .action(async function action(
+      this: Command,
+      commandOptions: ConfirmedCommandOptions,
+    ) {
+      await recompute(
+        this,
+        "formulas recompute workspace",
+        { scope: "WORKSPACE" },
+        options,
+        true,
+        commandOptions.yes,
+      );
+    });
+}

package/src/commands/schemas.test.ts

@@ -381,6 +381,48 @@ describe("schemas commands", () => {
     });
   });
 
+  it("creates fields with a description from the dedicated flag", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "field-1",
+        type: "TextField",
+        slug: "email",
+        label: "Email",
+        description: "Primary contact email",
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "fields",
+      "create",
+      "contacts",
+      "--type",
+      "text",
+      "--slug",
+      "email",
+      "--label",
+      "Email",
+      "--description",
+      "Primary contact email",
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({
+      type: "TextField",
+      slug: "email",
+      label: "Email",
+      description: "Primary contact email",
+    });
+  });
+
   it("creates fields with a default value flag", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
@@ -589,6 +631,53 @@ describe("schemas commands", () => {
     });
   });
 
+  it.each([
+    ["sets", "Shown in customer notifications"],
+    ["clears", ""],
+  ])("%s a field description without another metadata change", async (_action, description) => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "550e8400-e29b-41d4-a716-446655440003",
+        type: "TextField",
+        slug: "notes",
+        label: "Notes",
+        required: false,
+      }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "550e8400-e29b-41d4-a716-446655440003",
+        type: "TextField",
+        slug: "notes",
+        label: "Notes",
+        description,
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "fields",
+      "update",
+      "contacts",
+      "550E8400-E29B-41D4-A716-446655440003",
+      "--description",
+      description,
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[2]?.[1]?.body))).toEqual({
+      type: "TextField",
+      description,
+    });
+  });
+
   it("strips formula status from update payloads", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/schemas.ts

@@ -78,6 +78,7 @@ interface FieldCreateCommandOptions {
   type?: string;
   slug?: string;
   label?: string;
+  description?: string;
   required?: boolean;
   default?: string;
   raw?: string;
@@ -86,6 +87,7 @@ interface FieldCreateCommandOptions {
 
 interface FieldUpdateCommandOptions {
   label?: string;
+  description?: string;
   required?: boolean;
   default?: string;
   raw?: string;
@@ -386,6 +388,10 @@ function buildFieldCreateInput(
     input.required = options.required;
   }
 
+  if (options.description !== undefined) {
+    input.description = options.description;
+  }
+
   applyFieldDefaultValue(input, options.default);
 
   if ("config" in input && isJsonObject(input.config) && isEmptyObject(input.config)) {
@@ -462,6 +468,10 @@ function buildFieldUpdateInput(
     input.required = options.required;
   }
 
+  if (options.description !== undefined) {
+    input.description = options.description;
+  }
+
   applyFieldDefaultValue(input, options.default);
 
   return input;
@@ -769,6 +779,7 @@ export function registerSchemasCommands(
     .option("--type <type>", `field type (${formatSchemaFieldTypes()})`)
     .option("--slug <slug>", "field slug")
     .option("--label <label>", "field label")
+    .option("--description <text>", "field description")
     .option("--required <bool>", "required flag", parseBooleanFlag)
     .option("--default <value>", "default field value")
     .option("--raw <json>", 'raw JSON object payload (see type-specific shapes in --help)')
@@ -803,6 +814,7 @@ export function registerSchemasCommands(
     .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
     .argument("<field>", "field uuid or slug", parseUuidOrSlugSelector)
     .option("--label <label>", "field label")
+    .option("--description <text>", 'field description (use "" to clear)')
     .option("--required <bool>", "required flag", parseBooleanFlag)
     .option("--default <value>", "default field value")
     .option("--raw <json>", "raw JSON object payload")
@@ -832,7 +844,7 @@ export function registerSchemasCommands(
       if (isEmptyObject(input)) {
         throw new CliError(
           "invalid_cli_usage",
-          'Provide at least one field update via "--label", "--required", "--raw", or "--raw-file".',
+          'Provide at least one field update via "--label", "--description", "--required", "--default", "--raw", or "--raw-file".',
         );
       }
 

package/src/program.ts

@@ -8,6 +8,7 @@ import { registerCommentsCommands } from "./commands/comments.js";
 import { registerDisplaysCommands } from "./commands/displays.js";
 import { registerDocumentTemplatesCommands } from "./commands/document-templates.js";
 import { registerFilesCommands } from "./commands/files.js";
+import { registerFormulasCommands } from "./commands/formulas.js";
 import { registerLogsCommands } from "./commands/logs.js";
 import { registerNavigationCommands } from "./commands/navigation.js";
 import { registerProfilesCommands } from "./commands/profiles.js";
@@ -51,6 +52,7 @@ export function buildProgram(options: BuildProgramOptions = {}): Command {
   registerDisplaysCommands(program, options);
   registerDocumentTemplatesCommands(program, options);
   registerFilesCommands(program, options);
+  registerFormulasCommands(program, options);
   registerNavigationCommands(program, options);
   registerSchemasCommands(program, options);
   registerRecordsCommands(program, options);

package/src/utils/examples.ts

@@ -27,6 +27,60 @@ export function buildCommandExamples(examples: readonly CommandExample[]): reado
 const SAMPLE_UUID = "550e8400-e29b-41d4-a716-446655440001";
 
 const specificExamples: Record<string, readonly CommandExample[]> = {
+  "formulas recompute field": buildCommandExamples([
+    {
+      description: "Queue a full recalculation of one formula column.",
+      command: "zinkee --json formulas recompute field invoices total",
+      raw: `{
+  "scope": "FIELD",
+  "schema": "invoices",
+  "field": "total"
+}`,
+      response: `{
+  "requestId": "02ab5d47-cb5f-4eb2-afb8-e9a3a9eb34d4",
+  "scope": "FIELD",
+  "formulaCount": 1,
+  "skippedFormulaCount": 0,
+  "eventsQueued": 1,
+  "status": "QUEUED"
+}`,
+    },
+  ]),
+  "formulas recompute schema": buildCommandExamples([
+    {
+      description: "Queue recalculation of every active formula in one schema.",
+      command: "zinkee --json formulas recompute schema invoices --yes",
+      raw: `{
+  "scope": "SCHEMA",
+  "schema": "invoices"
+}`,
+      response: `{
+  "requestId": "02ab5d47-cb5f-4eb2-afb8-e9a3a9eb34d4",
+  "scope": "SCHEMA",
+  "formulaCount": 8,
+  "skippedFormulaCount": 1,
+  "eventsQueued": 8,
+  "status": "QUEUED"
+}`,
+    },
+  ]),
+  "formulas recompute workspace": buildCommandExamples([
+    {
+      description: "Queue recalculation of every active formula in the workspace.",
+      command: "zinkee --json formulas recompute workspace --yes",
+      raw: `{
+  "scope": "WORKSPACE"
+}`,
+      response: `{
+  "requestId": "02ab5d47-cb5f-4eb2-afb8-e9a3a9eb34d4",
+  "scope": "WORKSPACE",
+  "formulaCount": 24,
+  "skippedFormulaCount": 2,
+  "eventsQueued": 24,
+  "status": "QUEUED"
+}`,
+    },
+  ]),
   "profiles list": buildCommandExamples([
     {
       description:
@@ -350,6 +404,22 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     },
   ]),
   "schemas fields update": buildCommandExamples([
+    {
+      description: "Set the field description without changing its label or configuration.",
+      command:
+        'zinkee --json schemas fields update contacts contact-name --description "Primary name shown for the customer"',
+      raw: `{
+  "description": "Primary name shown for the customer"
+}`,
+    },
+    {
+      description: "Clear the field description.",
+      command:
+        'zinkee --json schemas fields update contacts contact-name --description ""',
+      raw: `{
+  "description": ""
+}`,
+    },
     {
       description: "Rename slug and label.",
       command:
@@ -1175,11 +1245,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   "displays create": buildCommandExamples([
     {
       description:
-        "Create a freeform display with an initial widget layout. Freeform layouts travel through --freeform-layouts.",
+        "Create a described freeform display with an initial widget layout. Freeform layouts travel through --freeform-layouts.",
       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}]}'`,
+        `zinkee --json displays create --name "Control Proyecto Freeform" --description "Project delivery overview" --template freeform --freeform-layouts '{"lg":[{"i":"widget-1","x":0,"y":0,"w":6,"h":5}]}'`,
       raw: `{
   "name": "Control Proyecto Freeform",
+  "description": "Project delivery overview",
   "layout": {
     "template": "freeform",
     "freeformLayouts": {
@@ -3081,6 +3152,22 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     },
   ]),
   "displays update": buildCommandExamples([
+    {
+      description: "Update only the display description.",
+      command:
+        'zinkee --json displays update 0f6f062f-1478-4df2-96a1-c495d037d260 --description "Sales pipeline overview"',
+      raw: `{
+  "description": "Sales pipeline overview"
+}`,
+    },
+    {
+      description: "Clear the display description.",
+      command:
+        'zinkee --json displays update 0f6f062f-1478-4df2-96a1-c495d037d260 --description ""',
+      raw: `{
+  "description": ""
+}`,
+    },
     {
       description: "Rename a display (patch of top-level metadata only).",
       command:
@@ -4463,8 +4550,26 @@ function buildSchemaFieldCreateExamples(type?: string): readonly CommandExample[
     definition.examplePayloads.map((example) => ({ definition, example })),
   );
 
-  return buildCommandExamples(
-    flat.map(({ example }, index) => {
+  const flagExamples: CommandExample[] =
+    selectedDefinition === undefined || selectedDefinition.key === "text"
+      ? [
+          {
+            description: "Text field with a description.",
+            command:
+              'zinkee --json schemas fields create contacts --type text --slug customer-name --label "Customer Name" --description "Primary name shown for the customer"',
+            raw: `{
+  "type": "TextField",
+  "slug": "customer-name",
+  "label": "Customer Name",
+  "description": "Primary name shown for the customer"
+}`,
+          },
+        ]
+      : [];
+
+  return buildCommandExamples([
+    ...flagExamples,
+    ...flat.map(({ example }, index) => {
       const slug =
         typeof example.payload.slug === "string" ? example.payload.slug : "field";
       const command = `zinkee --json schemas fields create contacts --raw '${JSON.stringify(example.payload)}'`;
@@ -4486,7 +4591,7 @@ function buildSchemaFieldCreateExamples(type?: string): readonly CommandExample[
         command,
       };
     }),
-  );
+  ]);
 }
 
 export function getCommandExamples(