zinkee 0.1.0

package/src/config.ts

@@ -0,0 +1,248 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { parseTOML, stringifyTOML } from "confbox/toml";
+
+import type { AppConfig, ProfileConfig, RuntimeOverrides, ResolvedProfile } from "./types.js";
+
+export const defaultConfigPath = join(homedir(), ".config", "zinkee", "config.toml");
+export const redactedSecretMask = "********";
+
+export class ProfileResolutionError extends Error {
+  override name = "ProfileResolutionError";
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toStringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function parseProfileConfig(value: unknown): ProfileConfig {
+  const profile: ProfileConfig = {};
+
+  if (!isRecord(value)) {
+    return profile;
+  }
+
+  for (const [key, rawValue] of Object.entries(value)) {
+    if (key === "api_key") {
+      profile.apiKey = toStringValue(rawValue);
+      continue;
+    }
+
+    if (key === "base_url") {
+      profile.baseUrl = toStringValue(rawValue);
+      continue;
+    }
+
+    profile[key] = rawValue;
+  }
+
+  return profile;
+}
+
+export function parseConfig(toml: string): AppConfig {
+  const parsed = parseTOML<unknown>(toml);
+  const config: AppConfig = { profiles: {} };
+
+  if (!isRecord(parsed)) {
+    return config;
+  }
+
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key === "default_profile") {
+      config.defaultProfile = toStringValue(value);
+      continue;
+    }
+
+    if (key === "profiles") {
+      if (!isRecord(value)) {
+        continue;
+      }
+
+      for (const [profileName, profileValue] of Object.entries(value)) {
+        config.profiles[profileName] = parseProfileConfig(profileValue);
+      }
+
+      continue;
+    }
+
+    config[key] = value;
+  }
+
+  return config;
+}
+
+export function readConfig(filePath: string = defaultConfigPath): AppConfig {
+  return parseConfig(readFileSync(filePath, "utf8"));
+}
+
+export function readConfigIfExists(filePath: string = defaultConfigPath): AppConfig | undefined {
+  try {
+    return readConfig(filePath);
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      error.code === "ENOENT"
+    ) {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+function serializeProfileConfig(profile: ProfileConfig): Record<string, unknown> {
+  const serialized: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(profile)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    if (key === "apiKey") {
+      serialized.api_key = value;
+      continue;
+    }
+
+    if (key === "baseUrl") {
+      serialized.base_url = value;
+      continue;
+    }
+
+    serialized[key] = value;
+  }
+
+  return serialized;
+}
+
+export function serializeConfig(config: AppConfig): string {
+  const serialized: Record<string, unknown> = {};
+
+  if (config.defaultProfile !== undefined) {
+    serialized.default_profile = config.defaultProfile;
+  }
+
+  for (const [key, value] of Object.entries(config)) {
+    if (key === "defaultProfile" || key === "profiles" || value === undefined) {
+      continue;
+    }
+
+    serialized[key] = value;
+  }
+
+  const serializedProfiles = Object.fromEntries(
+    Object.entries(config.profiles).map(([name, profile]) => [name, serializeProfileConfig(profile)]),
+  );
+
+  if (Object.keys(serializedProfiles).length > 0) {
+    serialized.profiles = serializedProfiles;
+  }
+
+  return stringifyTOML(serialized).trimEnd().concat("\n");
+}
+
+export function writeConfig(config: AppConfig, filePath: string = defaultConfigPath): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, serializeConfig(config), "utf8");
+}
+
+export function setProfileConfig(
+  config: AppConfig,
+  profileName: string,
+  updates: Partial<ProfileConfig>,
+): AppConfig {
+  return {
+    ...config,
+    profiles: {
+      ...config.profiles,
+      [profileName]: {
+        ...config.profiles[profileName],
+        ...updates,
+      },
+    },
+  };
+}
+
+export function removeProfileConfig(config: AppConfig, profileName: string): AppConfig {
+  const nextProfiles = { ...config.profiles };
+  delete nextProfiles[profileName];
+
+  return {
+    ...config,
+    defaultProfile:
+      config.defaultProfile === profileName
+        ? undefined
+        : config.defaultProfile,
+    profiles: nextProfiles,
+  };
+}
+
+export function setDefaultProfile(config: AppConfig, profileName: string): AppConfig {
+  return {
+    ...config,
+    defaultProfile: profileName,
+  };
+}
+
+export function redactSecret(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (value.length <= 4) {
+    return redactedSecretMask;
+  }
+
+  return `${redactedSecretMask}${value.slice(-4)}`;
+}
+
+export function redactProfile(profile: ProfileConfig): ProfileConfig {
+  return {
+    ...profile,
+    apiKey: redactSecret(profile.apiKey),
+  };
+}
+
+export function redactConfig(config: AppConfig): AppConfig {
+  return {
+    ...config,
+    profiles: Object.fromEntries(
+      Object.entries(config.profiles).map(([name, profile]) => [name, redactProfile(profile)]),
+    ),
+  };
+}
+
+export function resolveProfile(
+  config: AppConfig,
+  overrides: Pick<RuntimeOverrides, "profile" | "baseUrl" | "apiKey"> = {},
+): ResolvedProfile {
+  const profileName = overrides.profile ?? config.defaultProfile;
+  if (profileName) {
+    const profile = config.profiles[profileName];
+
+    if (!profile) {
+      const label = overrides.profile ? "Profile" : "Default profile";
+      throw new ProfileResolutionError(`${label} "${profileName}" not found in config.`);
+    }
+
+    return {
+      ...profile,
+      name: profileName,
+      baseUrl: overrides.baseUrl ?? profile.baseUrl,
+      apiKey: overrides.apiKey ?? profile.apiKey,
+    };
+  }
+
+  throw new ProfileResolutionError("No profile could be resolved from config.");
+}

package/src/index.test.ts

@@ -0,0 +1,140 @@
+import { mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { extractExampleRequest, showExamples } from "./cli-examples.js";
+import { isExecutedAsEntry } from "./cli-runner.js";
+import { buildProgram } from "./program.js";
+
+const tempDirs: string[] = [];
+
+describe("project bootstrap", () => {
+  afterEach(() => {
+    while (tempDirs.length > 0) {
+      rmSync(tempDirs.pop()!, { force: true, recursive: true });
+    }
+  });
+
+  it("loads the CLI entry module", async () => {
+    const mod = await import("./index.js");
+
+    expect(mod).toBeTruthy();
+    expect(mod.buildProgram).toBeTypeOf("function");
+  });
+
+  it("registers the global --example option", () => {
+    const program = buildProgram();
+
+    expect(program.options.some((option) => option.long === "--example")).toBe(true);
+  });
+
+  it("extracts example requests before commander parsing", () => {
+    expect(
+      extractExampleRequest(["node", "zinkee", "--json", "--example", "records", "query"]),
+    ).toEqual({
+      commandName: "records query",
+      filters: {},
+      overrides: {},
+      json: true,
+    });
+  });
+
+  it("extracts typed schema field examples without treating schema args as part of the command", () => {
+    expect(
+      extractExampleRequest([
+        "node",
+        "zinkee",
+        "--profile",
+        "local",
+        "--example",
+        "schemas",
+        "fields",
+        "create",
+        "contacts",
+        "--type",
+        "option",
+      ]),
+    ).toEqual({
+      commandName: "schemas fields create",
+      filters: {
+        type: "option",
+      },
+      overrides: {
+        profile: "local",
+      },
+      json: false,
+    });
+  });
+
+  it("shows field examples filtered by type", async () => {
+    let output = "";
+
+    await showExamples(
+      "schemas fields create",
+      false,
+      {
+        write(chunk: string) {
+          output += chunk;
+          return true;
+        },
+      },
+      { type: "option" },
+    );
+
+    expect(output).toContain('zinkee --json schemas fields create contacts --raw');
+    expect(output).toContain('"type":"option"');
+    expect(output).not.toContain('"type":"text"');
+    expect(output).toContain("Create a option field");
+  });
+
+  it("shows both number creation examples, including Moneda formatting", async () => {
+    let output = "";
+
+    await showExamples(
+      "schemas fields create",
+      false,
+      {
+        write(chunk: string) {
+          output += chunk;
+          return true;
+        },
+      },
+      { type: "number" },
+    );
+
+    expect(output).toContain('"slug":"amount"');
+    expect(output).toContain('"symbolEnabled":true');
+    expect(output).toContain('"symbolPosition":"right"');
+  });
+
+  it("shows automation examples with descriptions and equivalent payloads", async () => {
+    let output = "";
+
+    await showExamples("automations create", false, {
+      write(chunk: string) {
+        output += chunk;
+        return true;
+      },
+    });
+
+    expect(output).toContain("Create a scheduled automation with a six-field cron expression");
+    expect(output).toContain("Equivalent JSON payload:");
+    expect(output).toContain('"type": "scheduled"');
+    expect(output).toContain('"cronExpression": "0 15 10 * * 1"');
+  });
+
+  it("treats symlinked executables as the CLI entrypoint", () => {
+    const tempDir = mkdtempSync(join(tmpdir(), "zinkee-entry-"));
+    const realEntry = join(tempDir, "real-entry.js");
+    const linkedEntry = join(tempDir, "zinkee");
+    tempDirs.push(tempDir);
+
+    symlinkSync(fileURLToPath(import.meta.url), realEntry);
+    symlinkSync(realEntry, linkedEntry);
+
+    expect(isExecutedAsEntry(linkedEntry, pathToFileURL(realEntry).href)).toBe(true);
+  });
+});

package/src/index.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli, isExecutedAsEntry } from "./cli-runner.js";
+export { buildProgram, type BuildProgramOptions } from "./program.js";
+
+if (isExecutedAsEntry(process.argv[1], import.meta.url)) {
+  await runCli(process.argv);
+}

package/src/parsers/expressions.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { parseExpression } from "./expressions.js";
+
+describe("parseExpression", () => {
+  it("parses space-separated equality filters", () => {
+    expect(parseExpression("status eq active")).toEqual({
+      field: "status",
+      comparator: "eq",
+      value: "active",
+      raw: "status eq active",
+    });
+  });
+
+  it("parses contains filters with spaces in the value", () => {
+    expect(parseExpression("email contains @acme.com")).toEqual({
+      field: "email",
+      comparator: "contains",
+      value: "@acme.com",
+      raw: "email contains @acme.com",
+    });
+  });
+
+  it("parses unary null checks", () => {
+    expect(parseExpression("closedAt is-null")).toEqual({
+      field: "closedAt",
+      comparator: "is-null",
+      value: null,
+      raw: "closedAt is-null",
+    });
+  });
+
+  it("parses repeated value lists", () => {
+    expect(parseExpression("ownerId in a,b,c")).toEqual({
+      field: "ownerId",
+      comparator: "in",
+      value: ["a", "b", "c"],
+      raw: "ownerId in a,b,c",
+    });
+  });
+
+  it("parses colon-delimited condition expressions", () => {
+    expect(parseExpression("amount:gt:1000")).toEqual({
+      field: "amount",
+      comparator: "gt",
+      value: "1000",
+      raw: "amount:gt:1000",
+    });
+  });
+});

package/src/parsers/expressions.ts

@@ -0,0 +1,111 @@
+export type ExpressionComparator = "eq" | "contains" | "gt" | "is-null" | "in";
+
+export type ExpressionValue = string | readonly string[] | null;
+
+export interface ParsedExpression {
+  field: string;
+  comparator: ExpressionComparator;
+  value: ExpressionValue;
+  raw: string;
+}
+
+const supportedComparators = new Set<ExpressionComparator>([
+  "eq",
+  "contains",
+  "gt",
+  "is-null",
+  "in",
+]);
+
+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 (comparator === "is-null") {
+    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

@@ -0,0 +1,35 @@
+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

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,23 @@
+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

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