zinkee 0.1.44 → 0.1.45

package/src/parsers/expressions.ts

@@ -1,128 +0,0 @@
-export type ExpressionComparator =
-  | "eq"
-  | "neq"
-  | "gt"
-  | "gte"
-  | "lt"
-  | "lte"
-  | "contains"
-  | "in"
-  | "is_empty"
-  | "is_not_empty";
-
-export type ExpressionValue = string | readonly string[] | null;
-
-export interface ParsedExpression {
-  field: string;
-  comparator: ExpressionComparator;
-  value: ExpressionValue;
-  raw: string;
-}
-
-const supportedComparators = new Set<ExpressionComparator>([
-  "eq",
-  "neq",
-  "gt",
-  "gte",
-  "lt",
-  "lte",
-  "contains",
-  "in",
-  "is_empty",
-  "is_not_empty",
-]);
-
-const noValueComparators = new Set<ExpressionComparator>(["is_empty", "is_not_empty"]);
-
-function parseColonExpression(input: string): [string, string, string] {
-  const parts = input.split(":");
-
-  if (parts.length < 2) {
-    throw new Error(`Expected a field:comparator[:value] expression, got "${input}".`);
-  }
-
-  const field = parts[0]?.trim();
-  const comparator = parts[1]?.trim();
-
-  if (!field) {
-    throw new Error(`Expected a field before ":", got "${input}".`);
-  }
-
-  if (!comparator) {
-    throw new Error(`Expected a comparator after "${field}:", got "${input}".`);
-  }
-
-  return [field, comparator, parts.slice(2).join(":").trim()];
-}
-
-function parseSpaceExpression(input: string): [string, string, string] {
-  const parts = input.trim().split(/\s+/);
-
-  if (parts.length < 2) {
-    throw new Error(`Expected a field comparator expression, got "${input}".`);
-  }
-
-  const field = parts[0];
-  const comparator = parts[1];
-
-  if (!field) {
-    throw new Error(`Expected a field comparator expression, got "${input}".`);
-  }
-
-  if (!comparator) {
-    throw new Error(`Expected a comparator after "${field}", got "${input}".`);
-  }
-
-  return [field.trim(), comparator.trim(), parts.slice(2).join(" ").trim()];
-}
-
-function normalizeValue(comparator: ExpressionComparator, rawValue: string): ExpressionValue {
-  if (noValueComparators.has(comparator)) {
-    if (rawValue.length > 0) {
-      throw new Error(`Comparator "${comparator}" does not accept a value.`);
-    }
-
-    return null;
-  }
-
-  if (comparator === "in") {
-    const values = rawValue
-      .split(",")
-      .map((value) => value.trim())
-      .filter(Boolean);
-
-    if (values.length === 0) {
-      throw new Error(`Comparator "${comparator}" requires at least one value.`);
-    }
-
-    return values;
-  }
-
-  if (rawValue.length === 0) {
-    throw new Error(`Comparator "${comparator}" requires a value.`);
-  }
-
-  return rawValue;
-}
-
-export function parseExpression(input: string): ParsedExpression {
-  const trimmed = input.trim();
-  const [field, comparatorCandidate, rawValue] = trimmed.includes(":") && !trimmed.includes(" ")
-    ? parseColonExpression(trimmed)
-    : parseSpaceExpression(trimmed);
-
-  if (!supportedComparators.has(comparatorCandidate as ExpressionComparator)) {
-    throw new Error(
-      `Unsupported comparator "${comparatorCandidate}" in expression "${input}".`,
-    );
-  }
-
-  const comparator = comparatorCandidate as ExpressionComparator;
-
-  return {
-    field,
-    comparator,
-    value: normalizeValue(comparator, rawValue),
-    raw: trimmed,
-  };
-}

package/src/parsers/kv.test.ts

@@ -1,35 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { parseJsonAssignment, parseKeyValue } from "./kv.js";
-
-describe("parseKeyValue", () => {
-  it("splits field=value pairs", () => {
-    expect(parseKeyValue("status=active")).toEqual({
-      key: "status",
-      value: "active",
-    });
-  });
-
-  it("trims surrounding whitespace without changing the assigned value", () => {
-    expect(parseKeyValue("  title = hello world  ")).toEqual({
-      key: "title",
-      value: "hello world",
-    });
-  });
-});
-
-describe("parseJsonAssignment", () => {
-  it("parses field=json pairs", () => {
-    expect(parseJsonAssignment('payload={"a":1}')).toEqual({
-      key: "payload",
-      value: { a: 1 },
-    });
-  });
-
-  it("supports null assignments", () => {
-    expect(parseJsonAssignment("payload=null")).toEqual({
-      key: "payload",
-      value: null,
-    });
-  });
-});

package/src/parsers/kv.ts

@@ -1,49 +0,0 @@
-import type { JsonValue } from "../types.js";
-
-export interface KeyValueAssignment {
-  key: string;
-  value: string;
-}
-
-export interface JsonKeyValueAssignment<TValue = JsonValue> {
-  key: string;
-  value: TValue;
-}
-
-function splitAssignment(input: string): [string, string] {
-  const separatorIndex = input.indexOf("=");
-
-  if (separatorIndex === -1) {
-    throw new Error(`Expected key=value assignment, got "${input}".`);
-  }
-
-  const key = input.slice(0, separatorIndex).trim();
-  const value = input.slice(separatorIndex + 1).trim();
-
-  if (!key) {
-    throw new Error(`Expected a key before "=", got "${input}".`);
-  }
-
-  return [key, value];
-}
-
-export function parseKeyValue(input: string): KeyValueAssignment {
-  const [key, value] = splitAssignment(input);
-
-  return { key, value };
-}
-
-export function parseJsonAssignment<TValue = JsonValue>(
-  input: string,
-): JsonKeyValueAssignment<TValue> {
-  const [key, value] = splitAssignment(input);
-
-  try {
-    return {
-      key,
-      value: JSON.parse(value) as TValue,
-    };
-  } catch (cause) {
-    throw new Error(`Expected ${key}=<json> assignment, got invalid JSON.`, { cause });
-  }
-}

package/src/parsers/selectors.test.ts

@@ -1,23 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { normalizeUuidOrSlug } from "./selectors.js";
-
-describe("normalizeUuidOrSlug", () => {
-  it("recognizes UUID selectors and lowercases them", () => {
-    expect(normalizeUuidOrSlug("550E8400-E29B-41D4-A716-446655440000")).toEqual({
-      kind: "uuid",
-      value: "550e8400-e29b-41d4-a716-446655440000",
-    });
-  });
-
-  it("preserves slug selectors", () => {
-    expect(normalizeUuidOrSlug("customer-records")).toEqual({
-      kind: "slug",
-      value: "customer-records",
-    });
-  });
-
-  it("rejects empty selectors", () => {
-    expect(() => normalizeUuidOrSlug("   ")).toThrowError("Selector cannot be empty.");
-  });
-});

package/src/parsers/selectors.ts

@@ -1,29 +0,0 @@
-export type SelectorKind = "uuid" | "slug";
-
-export interface NormalizedUuidOrSlug {
-  kind: SelectorKind;
-  value: string;
-}
-
-const uuidPattern =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-export function normalizeUuidOrSlug(input: string): NormalizedUuidOrSlug {
-  const value = input.trim();
-
-  if (!value) {
-    throw new Error("Selector cannot be empty.");
-  }
-
-  if (uuidPattern.test(value)) {
-    return {
-      kind: "uuid",
-      value: value.toLowerCase(),
-    };
-  }
-
-  return {
-    kind: "slug",
-    value,
-  };
-}

package/src/program.ts

@@ -1,64 +0,0 @@
-import { createRequire } from "node:module";
-
-import { Command } from "commander";
-
-import { registerConfigCommands } from "./commands/config.js";
-import { registerAutomationsCommands } from "./commands/automations.js";
-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";
-import { registerRecordsCommands } from "./commands/records.js";
-import { registerSchemasCommands } from "./commands/schemas.js";
-import { registerTeamspaceCommands } from "./commands/teamspace.js";
-
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json") as { version: string };
-
-interface CommandIo {
-  write(chunk: string): unknown;
-}
-
-export interface BuildProgramOptions {
-  configPath?: string;
-  stdout?: CommandIo;
-}
-
-export function buildProgram(options: BuildProgramOptions = {}): Command {
-  const program = new Command();
-
-  program
-    .name("zinkee")
-    .description("CLI for Zinkee API v2")
-    .version(version)
-    .enablePositionalOptions()
-    .showHelpAfterError()
-    .option("--profile <name>", "select a profile from config")
-    .option("--base-url <url>", "override the configured base URL")
-    .option("--api-key <token>", "override the configured API key")
-    .option("--read-only", "run in read-only mode")
-    .option("--example", "show examples for a command")
-    .option("--json", "emit JSON output")
-    .option("--install-completion [shell]", "install shell completion (bash, zsh, fish, powershell)")
-    .option("--show-completion [shell]", "print shell completion script for the current shell");
-
-  registerProfilesCommands(program, options);
-  registerAutomationsCommands(program, options);
-  registerConfigCommands(program, options);
-  registerDisplaysCommands(program, options);
-  registerDocumentTemplatesCommands(program, options);
-  registerFilesCommands(program, options);
-  registerFormulasCommands(program, options);
-  registerNavigationCommands(program, options);
-  registerSchemasCommands(program, options);
-  registerRecordsCommands(program, options);
-  registerCommentsCommands(program, options);
-  registerLogsCommands(program, options);
-  registerTeamspaceCommands(program, options);
-
-  return program;
-}

package/src/runtime-context.ts

@@ -1,103 +0,0 @@
-import type { AppConfig, RuntimeContext, RuntimeOverrides } from "./types.js";
-
-import {
-  DEFAULT_PRODUCTION_BASE_URL,
-  ENV_API_KEY,
-  ENV_BASE_URL,
-  readEnvApiKey,
-  readEnvBaseUrl,
-  readEnvProfile,
-  resolveProfile,
-  ProfileResolutionError,
-  validateBaseUrl,
-} from "./config.js";
-
-export function resolveRuntimeContext(
-  config: AppConfig,
-  overrides: RuntimeOverrides = {},
-): RuntimeContext {
-  const envProfile = readEnvProfile();
-  const envApiKey = readEnvApiKey();
-  const envBaseUrl = readEnvBaseUrl();
-
-  const flagBaseUrl =
-    overrides.baseUrl !== undefined
-      ? validateBaseUrl(overrides.baseUrl, '"--base-url"')
-      : undefined;
-
-  const profileOverride = overrides.profile ?? envProfile;
-  const apiKeyOverride = overrides.apiKey ?? envApiKey;
-  const baseUrlOverride = flagBaseUrl ?? envBaseUrl;
-
-  if (apiKeyOverride && !baseUrlOverride) {
-    throw new ProfileResolutionError(
-      `Runtime API key was provided, but ${ENV_BASE_URL} or --base-url is missing.`,
-    );
-  }
-
-  if (baseUrlOverride && !apiKeyOverride) {
-    throw new ProfileResolutionError(
-      `Runtime base URL was provided, but ${ENV_API_KEY} or --api-key is missing.`,
-    );
-  }
-
-  if (apiKeyOverride && baseUrlOverride) {
-    return {
-      profile: profileOverride ?? "runtime",
-      baseUrl: baseUrlOverride,
-      apiKey: apiKeyOverride,
-      readOnly: overrides.readOnly ?? false,
-      json: overrides.json ?? false,
-      profileSource:
-        overrides.profile !== undefined
-          ? "flag"
-          : envProfile !== undefined
-            ? "env"
-            : undefined,
-      baseUrlSource:
-        overrides.baseUrl !== undefined
-          ? "flag"
-          : envBaseUrl !== undefined
-            ? "env"
-            : undefined,
-      apiKeySource:
-        overrides.apiKey !== undefined
-          ? "flag"
-          : envApiKey !== undefined
-            ? "env"
-            : undefined,
-    };
-  }
-
-  const profile = resolveProfile(config, {
-    profile: profileOverride,
-    baseUrl: baseUrlOverride,
-    apiKey: apiKeyOverride,
-  });
-
-  return {
-    profile: profile.name,
-    baseUrl: baseUrlOverride ?? profile.baseUrl ?? DEFAULT_PRODUCTION_BASE_URL,
-    apiKey: apiKeyOverride ?? profile.apiKey,
-    readOnly: overrides.readOnly ?? false,
-    json: overrides.json ?? false,
-    profileSource:
-      overrides.profile !== undefined
-        ? "flag"
-        : envProfile !== undefined
-          ? "env"
-          : "config",
-    baseUrlSource:
-      overrides.baseUrl !== undefined
-        ? "flag"
-        : envBaseUrl !== undefined
-          ? "env"
-          : "config",
-    apiKeySource:
-      overrides.apiKey !== undefined
-        ? "flag"
-        : envApiKey !== undefined
-          ? "env"
-          : "config",
-  };
-}

package/src/types.ts

@@ -1,76 +0,0 @@
-export interface CliContext {
-  argv: string[];
-}
-
-export interface ProfileConfig {
-  apiKey?: string;
-  baseUrl?: string;
-  [key: string]: unknown;
-}
-
-export interface AppConfig {
-  defaultProfile?: string;
-  profiles: Record<string, ProfileConfig>;
-  [key: string]: unknown;
-}
-
-export interface ResolvedProfile extends ProfileConfig {
-  name: string;
-}
-
-export interface RuntimeOverrides {
-  profile?: string;
-  baseUrl?: string;
-  apiKey?: string;
-  readOnly?: boolean;
-  json?: boolean;
-}
-
-export type RuntimeValueSource = "flag" | "env" | "config";
-
-export interface RuntimeContext {
-  profile: string;
-  baseUrl?: string;
-  apiKey?: string;
-  readOnly: boolean;
-  json: boolean;
-  profileSource?: RuntimeValueSource;
-  baseUrlSource?: RuntimeValueSource;
-  apiKeySource?: RuntimeValueSource;
-}
-
-export type JsonScalar = string | number | boolean | null;
-
-export interface JsonObject {
-  [key: string]: JsonValue;
-}
-
-export type JsonValue = JsonScalar | JsonObject | JsonValue[];
-
-export interface JsonEnvelopeMeta {
-  [key: string]: unknown;
-}
-
-export interface JsonSuccessEnvelope<TData = JsonValue, TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta> {
-  data: TData;
-  meta: TMeta;
-}
-
-export interface JsonErrorEnvelope<TErr = JsonValue, TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta> {
-  error: TErr;
-  meta: TMeta;
-}
-
-export type OutputFormat = "json" | "table";
-
-export type CommandAccessLevel = "read" | "write" | "destructive";
-
-export type CommandOutputCapability = "table-json" | "json-only" | "binary";
-
-export interface CommandMeta {
-  command: string;
-  accessLevel: CommandAccessLevel;
-  supportsExample: boolean;
-  supportsRaw: boolean;
-  output: CommandOutputCapability;
-}

package/src/utils/argv-rewrite.test.ts

@@ -1,149 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { commandRegistry } from "../command-registry.js";
-import { buildProgram } from "../program.js";
-import {
-  buildOptionMetadata,
-  hoistGlobalOptions,
-} from "./argv-rewrite.js";
-
-function rewrite(userArgs: readonly string[]): string[] {
-  const optionMeta = buildOptionMetadata(buildProgram());
-  return hoistGlobalOptions(["node", "zinkee", ...userArgs], optionMeta, commandRegistry);
-}
-
-describe("hoistGlobalOptions", () => {
-  it("moves boolean global flags before the subcommand path", () => {
-    expect(rewrite(["schemas", "list", "--json"])).toEqual([
-      "node",
-      "zinkee",
-      "--json",
-      "schemas",
-      "list",
-    ]);
-  });
-
-  it("moves global value flags together with their value", () => {
-    expect(rewrite(["schemas", "list", "--profile", "staging"])).toEqual([
-      "node",
-      "zinkee",
-      "--profile",
-      "staging",
-      "schemas",
-      "list",
-    ]);
-  });
-
-  it("moves multiple globals preserving their relative order", () => {
-    expect(
-      rewrite(["schemas", "list", "--json", "--profile", "staging", "--read-only"]),
-    ).toEqual([
-      "node",
-      "zinkee",
-      "--json",
-      "--profile",
-      "staging",
-      "--read-only",
-      "schemas",
-      "list",
-    ]);
-  });
-
-  it("hoists globals that are interleaved between subcommand path tokens", () => {
-    expect(rewrite(["schemas", "--json", "fields", "create"])).toEqual([
-      "node",
-      "zinkee",
-      "--json",
-      "schemas",
-      "fields",
-      "create",
-    ]);
-  });
-
-  it("does not touch global flags that already appear before the subcommand path", () => {
-    expect(rewrite(["--json", "schemas", "list"])).toEqual([
-      "node",
-      "zinkee",
-      "--json",
-      "schemas",
-      "list",
-    ]);
-  });
-
-  it("preserves --api-key when it appears after profiles add (subcommand-local option)", () => {
-    expect(
-      rewrite(["profiles", "add", "myProfile", "--api-key", "abc", "--base-url", "https://x"]),
-    ).toEqual([
-      "node",
-      "zinkee",
-      "profiles",
-      "add",
-      "myProfile",
-      "--api-key",
-      "abc",
-      "--base-url",
-      "https://x",
-    ]);
-  });
-
-  it("preserves --api-key/--base-url for profiles update while still hoisting other globals", () => {
-    expect(
-      rewrite(["profiles", "update", "myProfile", "--api-key", "abc", "--json"]),
-    ).toEqual([
-      "node",
-      "zinkee",
-      "--json",
-      "profiles",
-      "update",
-      "myProfile",
-      "--api-key",
-      "abc",
-    ]);
-  });
-
-  it("supports the --foo=bar syntax for global value flags", () => {
-    expect(rewrite(["schemas", "list", "--profile=staging"])).toEqual([
-      "node",
-      "zinkee",
-      "--profile=staging",
-      "schemas",
-      "list",
-    ]);
-  });
-
-  it("returns argv unchanged when no subcommand path is found", () => {
-    expect(rewrite(["--json"])).toEqual(["node", "zinkee", "--json"]);
-  });
-
-  it("respects -- and stops hoisting after it", () => {
-    expect(
-      rewrite(["schemas", "list", "--", "--json", "trailing"]),
-    ).toEqual([
-      "node",
-      "zinkee",
-      "schemas",
-      "list",
-      "--",
-      "--json",
-      "trailing",
-    ]);
-  });
-});
-
-describe("buildOptionMetadata", () => {
-  it("registers local options for leaf subcommands", () => {
-    const optionMeta = buildOptionMetadata(buildProgram());
-    const profilesAdd = optionMeta.localOptionsByCommand.get("profiles add");
-
-    expect(profilesAdd?.has("--api-key")).toBe(true);
-    expect(profilesAdd?.has("--base-url")).toBe(true);
-  });
-
-  it("recognises global value vs boolean flags", () => {
-    const optionMeta = buildOptionMetadata(buildProgram());
-
-    expect(optionMeta.valueFlags.has("--profile")).toBe(true);
-    expect(optionMeta.booleanFlags.has("--json")).toBe(true);
-    expect(optionMeta.booleanFlags.has("--read-only")).toBe(true);
-  });
-});