zinkee 0.1.41 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "description": "CLI for Zinkee API v2",
   "repository": {
     "type": "git",

package/src/api/formulas.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { normalizeUuidOrSlug } from "../parsers/selectors.js";
+import { ApiClient } from "../client.js";
+import { FormulasApi } from "./formulas.js";
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 202,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("FormulasApi", () => {
+  it.each([
+    {
+      input: {
+        scope: "FIELD" as const,
+        schema: normalizeUuidOrSlug("invoices"),
+        field: normalizeUuidOrSlug("total"),
+      },
+      body: { scope: "FIELD", schema: "invoices", field: "total" },
+    },
+    {
+      input: {
+        scope: "SCHEMA" as const,
+        schema: normalizeUuidOrSlug("550e8400-e29b-41d4-a716-446655440001"),
+      },
+      body: {
+        scope: "SCHEMA",
+        schema: "550e8400-e29b-41d4-a716-446655440001",
+      },
+    },
+    {
+      input: { scope: "WORKSPACE" as const },
+      body: { scope: "WORKSPACE" },
+    },
+  ])("posts the $input.scope payload to the recompute endpoint", async ({ input, body }) => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+      jsonResponse({
+        requestId: "request-1",
+        scope: input.scope,
+        formulaCount: 1,
+        skippedFormulaCount: 0,
+        eventsQueued: 1,
+        status: "QUEUED",
+      }),
+    );
+    const api = new FormulasApi(
+      new ApiClient({
+        baseUrl: "https://api.zinkee.test",
+        apiKey: "test-token",
+        fetch: fetchMock,
+      }),
+    );
+
+    await api.recompute(input);
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe("https://api.zinkee.test/api/v2/formulas:recompute");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual(body);
+  });
+});

package/src/api/formulas.ts

@@ -0,0 +1,67 @@
+import { ApiClient } from "../client.js";
+import type { NormalizedUuidOrSlug } from "../parsers/selectors.js";
+
+export type FormulaRecomputeScope = "FIELD" | "SCHEMA" | "WORKSPACE";
+
+export interface FormulaRecomputeResponse {
+  requestId: string;
+  scope: FormulaRecomputeScope;
+  formulaCount: number;
+  skippedFormulaCount: number;
+  eventsQueued: number;
+  status: "QUEUED";
+}
+
+export type FormulaRecomputeInput =
+  | {
+      scope: "FIELD";
+      schema: NormalizedUuidOrSlug;
+      field: NormalizedUuidOrSlug;
+    }
+  | {
+      scope: "SCHEMA";
+      schema: NormalizedUuidOrSlug;
+    }
+  | {
+      scope: "WORKSPACE";
+    };
+
+function selectorValue(selector: NormalizedUuidOrSlug): string {
+  return selector.value;
+}
+
+function toRequestBody(input: FormulaRecomputeInput): Record<string, string> {
+  if (input.scope === "FIELD") {
+    return {
+      scope: input.scope,
+      schema: selectorValue(input.schema),
+      field: selectorValue(input.field),
+    };
+  }
+
+  if (input.scope === "SCHEMA") {
+    return {
+      scope: input.scope,
+      schema: selectorValue(input.schema),
+    };
+  }
+
+  return { scope: input.scope };
+}
+
+export class FormulasApi {
+  constructor(private readonly client: ApiClient) {}
+
+  recompute(input: FormulaRecomputeInput): Promise<FormulaRecomputeResponse> {
+    return this.client.requestJson<FormulaRecomputeResponse>(
+      "/api/v2/formulas:recompute",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(toRequestBody(input)),
+      },
+    );
+  }
+}

package/src/command-registry.ts

@@ -14,6 +14,27 @@ const readOutput: CommandOutputCapability = "table-json";
 const writeOutput: CommandOutputCapability = "json-only";
 
 export const commandRegistry = {
+  "formulas recompute field": {
+    command: "formulas recompute field",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "formulas recompute schema": {
+    command: "formulas recompute schema",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "formulas recompute workspace": {
+    command: "formulas recompute workspace",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
   "config path": {
     command: "config path",
     accessLevel: "read",

package/src/commands/formulas.test.ts

@@ -0,0 +1,194 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { Command } from "commander";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { registerFormulasCommands } from "./formulas.js";
+
+function createConfig(): string {
+  const dir = mkdtempSync(join(tmpdir(), "zinkee-formulas-"));
+  const filePath = join(dir, "config.toml");
+  writeFileSync(
+    filePath,
+    `default_profile = "test"\n\n[profiles.test]\napi_key = "token"\nbase_url = "https://api.zinkee.test"\n`,
+    "utf8",
+  );
+  return filePath;
+}
+
+function createStdoutBuffer() {
+  let output = "";
+  return {
+    stdout: {
+      write(chunk: string) {
+        output += chunk;
+        return true;
+      },
+    },
+    read: () => output,
+  };
+}
+
+function buildProgram(options: { configPath: string; stdout: { write(chunk: string): unknown } }): Command {
+  const program = new Command();
+  program
+    .name("zinkee")
+    .enablePositionalOptions()
+    .option("--read-only")
+    .option("--json");
+  registerFormulasCommands(program, options);
+  return program;
+}
+
+function queuedResponse(scope: "FIELD" | "SCHEMA" | "WORKSPACE", eventsQueued = 1): Response {
+  return new Response(
+    JSON.stringify({
+      requestId: "request-1",
+      scope,
+      formulaCount: eventsQueued,
+      skippedFormulaCount: 0,
+      eventsQueued,
+      status: "QUEUED",
+    }),
+    { status: 202, headers: { "content-type": "application/json" } },
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("formulas commands", () => {
+  it("registers the formulas command group", () => {
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    expect(program.commands.some((command) => command.name() === "formulas")).toBe(true);
+  });
+
+  it("queues one field by slug and emits the JSON envelope", async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(queuedResponse("FIELD"));
+    vi.stubGlobal("fetch", fetchMock);
+    const configPath = createConfig();
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "formulas",
+      "recompute",
+      "field",
+      "invoices",
+      "total",
+    ]);
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(JSON.parse(String(init?.body))).toEqual({
+      scope: "FIELD",
+      schema: "invoices",
+      field: "total",
+    });
+    expect(JSON.parse(output.read())).toEqual({
+      data: {
+        requestId: "request-1",
+        scope: "FIELD",
+        formulaCount: 1,
+        skippedFormulaCount: 0,
+        eventsQueued: 1,
+        status: "QUEUED",
+      },
+      meta: { command: "formulas recompute field", configPath },
+    });
+  });
+
+  it.each([
+    ["schema", ["invoices"]],
+    ["workspace", []],
+  ])("requires --yes before the %s request", async (scope, args) => {
+    const fetchMock = vi.fn<typeof fetch>();
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "formulas",
+        "recompute",
+        scope,
+        ...args,
+      ]),
+    ).rejects.toThrow("requires --yes");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("queues every schema formula after confirmation", async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(queuedResponse("SCHEMA", 3));
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "formulas",
+      "recompute",
+      "schema",
+      "invoices",
+      "--yes",
+    ]);
+
+    expect(output.read()).toContain("Queued 3 formula recalculation event(s)");
+    expect(output.read()).not.toContain("completed");
+  });
+
+  it("queues the workspace payload after confirmation", async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(queuedResponse("WORKSPACE", 5));
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "formulas",
+      "recompute",
+      "workspace",
+      "--yes",
+    ]);
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(JSON.parse(String(init?.body))).toEqual({ scope: "WORKSPACE" });
+  });
+
+  it.each([
+    ["field", ["invoices", "total"]],
+    ["schema", ["invoices", "--yes"]],
+    ["workspace", ["--yes"]],
+  ])("blocks %s in read-only mode before any network request", async (scope, args) => {
+    const fetchMock = vi.fn<typeof fetch>();
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--read-only",
+        "formulas",
+        "recompute",
+        scope,
+        ...args,
+      ]),
+    ).rejects.toThrow("not allowed in read-only mode");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

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/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: