zinkee 0.1.40 → 0.1.42

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:

package/.claude/settings.local.json

@@ -1,70 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test *)",
-      "Bash(npm run *)",
-      "Bash(pnpm typecheck *)",
-      "Bash(pnpm test *)",
-      "Bash(npx tsc *)",
-      "Read(//home/guillermo/dev/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/log/**)",
-      "Read(//home/guillermo/dev/z2-backend/**)",
-      "Bash(grep *)",
-      "Bash(npx vitest *)",
-      "Bash(npx tsx *)",
-      "Bash(node dist/index.js --help)",
-      "Bash(gh repo *)",
-      "WebFetch(domain:github.com)",
-      "Bash(git config *)",
-      "Read(//home/guillermo/.config/**)",
-      "Read(//home/guillermo/**)",
-      "Bash(curl *)",
-      "Bash(node dist/index.js --show-completion zsh)",
-      "Bash(node *)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee\" COMP_CWORD=1 node *)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas\" COMP_CWORD=2 node *)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas fields\" COMP_CWORD=3 node dist/index.js)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas fields cr\" COMP_CWORD=3 node dist/index.js)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas list --j\" COMP_CWORD=3 node dist/index.js)",
-      "Bash(rm -rf /tmp/zinkee-install)",
-      "Bash(mkdir -p /tmp/zinkee-install)",
-      "Bash(HOME=/tmp/zinkee-install SHELL=/bin/zsh node dist/index.js --install-completion)",
-      "Read(//tmp/**)",
-      "Read(//tmp/zinkee-install/**)",
-      "Bash(rm -rf /tmp/zinkee-install-bash)",
-      "Bash(mkdir -p /tmp/zinkee-install-bash)",
-      "Bash(HOME=/tmp/zinkee-install-bash SHELL=/bin/bash node dist/index.js --install-completion)",
-      "Bash(rm -rf /tmp/zinkee-install-fish)",
-      "Bash(mkdir -p /tmp/zinkee-install-fish)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete node dist/index.js)",
-      "Bash(echo \"exit: $?\")",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas\" COMP_CWORD=abc node dist/index.js)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee config show --foo --bar baz quux ?\" COMP_CWORD=10 node dist/index.js)",
-      "Bash(git -C /home/guillermo/dev/cli status)",
-      "Bash(git -C /home/guillermo/dev/cli branch --show-current)",
-      "Bash(git -C /home/guillermo/dev/cli diff --stat)",
-      "Bash(git fetch *)",
-      "Bash(pnpm exec *)",
-      "Bash(echo \"=== exit $? \\(grep\\) ===\")",
-      "Bash(grep -rn \"resourceType\" src/)",
-      "Bash(grep -rn \"automation-folders/\\\\${\\\\|/automations:move\\\\|{folderId}/automations\" src/)",
-      "Bash(grep -rn \"navigation resources move.*--type\\\\|resourceType\" docs/ README.md)",
-      "Bash(zinkee --version)",
-      "Bash(zinkee --json profiles list)",
-      "Bash(zinkee displays *)",
-      "Bash(chmod +x /tmp/audit_search.sh)",
-      "Bash(/tmp/audit_search.sh)",
-      "Bash(head -60 CLAUDE.md)",
-      "Bash(head -40 AGENTS.md)",
-      "Bash(xargs cat)",
-      "Bash(./gradlew :api:test --tests \"com.zinkee.api.service.v2.data.DataV2TranslatorTest\" --tests \"com.zinkee.api.service.v2.data.DataV2ServiceTest\" --tests \"com.zinkee.api.domain.model.v2.data.DataV2PatchRecordRequestTest\")",
-      "Bash(./gradlew :api:test --tests \"com.zinkee.api.service.v2.data.DataV2ServiceTest\" --tests \"com.zinkee.api.domain.model.v2.data.DataV2PatchRecordRequestTest\")",
-      "Bash(./gradlew :api:spotlessApply)",
-      "Bash(./gradlew :api:test :api:spotbugsMain spotlessCheck)",
-      "Bash(./gradlew :api:spotbugsMain)",
-      "Bash(./gradlew spotlessCheck)",
-      "Bash(git --no-pager diff --stat)",
-      "Bash(git --no-pager diff -- src/commands/records.ts src/api/records.ts)",
-      "Bash(echo \"===EXIT: $?===\")"
-    ]
-  }
-}