zinkee 0.1.0

package/src/commands/profiles.ts

@@ -0,0 +1,281 @@
+import type { Writable } from "node:stream";
+
+import { Command } from "commander";
+
+import {
+  defaultConfigPath,
+  readConfigIfExists,
+  redactProfile,
+  removeProfileConfig,
+  setDefaultProfile,
+  setProfileConfig,
+  writeConfig,
+} from "../config.js";
+import type { AppConfig, ProfileConfig } from "../types.js";
+import { CliError } from "../utils/errors.js";
+import { buildJsonSuccess, printTable } from "../utils/output.js";
+
+interface CommandIo {
+  write(chunk: string): unknown;
+}
+
+export interface RegisterProfilesCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions {
+  json?: boolean;
+}
+
+export interface DisplayProfile extends ProfileConfig {
+  name: string;
+  isDefault: 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 emitJson(
+  stdout: CommandIo,
+  commandName: string,
+  data: unknown,
+  configPath: string,
+): void {
+  writeLine(
+    stdout,
+    JSON.stringify(buildJsonSuccess(data, { command: commandName, configPath })),
+  );
+}
+
+function readRequiredConfig(filePath: string): AppConfig {
+  const config = readConfigIfExists(filePath);
+
+  if (config) {
+    return config;
+  }
+
+  throw new CliError("configuration_error", `Config file not found at ${filePath}.`);
+}
+
+function getRequiredProfile(config: AppConfig, profileName: string): ProfileConfig {
+  const profile = config.profiles[profileName];
+
+  if (profile) {
+    return profile;
+  }
+
+  throw new CliError("configuration_error", `Profile "${profileName}" not found in config.`);
+}
+
+function toDisplayProfile(
+  profileName: string,
+  profile: ProfileConfig,
+  defaultProfile: string | undefined,
+): DisplayProfile {
+  return {
+    name: profileName,
+    isDefault: defaultProfile === profileName,
+    ...redactProfile(profile),
+  };
+}
+
+function loadConfigForAdd(filePath: string): AppConfig {
+  return readConfigIfExists(filePath) ?? { profiles: {} };
+}
+
+function emitProfilesTable(stdout: CommandIo, data: readonly DisplayProfile[]): void {
+  printTable(
+    data.map((profile) => ({
+      name: profile.name,
+      default: profile.isDefault ? "yes" : "",
+      baseUrl: profile.baseUrl ?? "",
+      apiKey: profile.apiKey ?? "",
+    })),
+    ["name", "default", "baseUrl", "apiKey"],
+    stdout,
+  );
+}
+
+export function registerProfilesCommands(
+  program: Command,
+  options: RegisterProfilesCommandsOptions = {},
+): void {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const profiles = program.command("profiles").description("Manage local CLI profiles");
+
+  profiles
+    .command("list")
+    .description("List configured profiles")
+    .action(function action(this: Command) {
+      const config = readRequiredConfig(filePath);
+      const data = Object.entries(config.profiles).map(([name, profile]) =>
+        toDisplayProfile(name, profile, config.defaultProfile),
+      );
+
+      if (getGlobalOptions(this).json) {
+        emitJson(stdout, "profiles list", data, filePath);
+        return;
+      }
+
+      emitProfilesTable(stdout, data);
+    });
+
+  profiles
+    .command("get")
+    .description("Show a single configured profile")
+    .argument("<profile>", "profile name")
+    .action(function action(this: Command, profileName: string) {
+      const config = readRequiredConfig(filePath);
+      const profile = getRequiredProfile(config, profileName);
+      const data = toDisplayProfile(profileName, profile, config.defaultProfile);
+
+      if (getGlobalOptions(this).json) {
+        emitJson(stdout, "profiles get", data, filePath);
+        return;
+      }
+
+      emitProfilesTable(stdout, [data]);
+    });
+
+  profiles
+    .command("use")
+    .description("Set the default profile")
+    .argument("<profile>", "profile name")
+    .action(function action(this: Command, profileName: string) {
+      const config = readRequiredConfig(filePath);
+      getRequiredProfile(config, profileName);
+
+      const nextConfig = setDefaultProfile(config, profileName);
+      writeConfig(nextConfig, filePath);
+      const data = {
+        profile: profileName,
+        defaultProfile: nextConfig.defaultProfile,
+      };
+
+      if (getGlobalOptions(this).json) {
+        emitJson(stdout, "profiles use", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Using profile "${profileName}".`);
+    });
+
+  profiles
+    .command("add")
+    .description("Add a profile to the local config")
+    .argument("<profile>", "profile name")
+    .requiredOption("--api-key <token>", "API key")
+    .option("--base-url <url>", "base URL")
+    .action(function action(
+      this: Command,
+      profileName: string,
+      commandOptions: { apiKey: string; baseUrl?: string },
+    ) {
+      const config = loadConfigForAdd(filePath);
+
+      if (config.profiles[profileName]) {
+        throw new CliError(
+          "configuration_error",
+          `Profile "${profileName}" already exists in config.`,
+        );
+      }
+
+      let nextConfig = setProfileConfig(config, profileName, {
+        apiKey: commandOptions.apiKey,
+        baseUrl: commandOptions.baseUrl,
+      });
+
+      if (!nextConfig.defaultProfile) {
+        nextConfig = setDefaultProfile(nextConfig, profileName);
+      }
+
+      writeConfig(nextConfig, filePath);
+      const data = toDisplayProfile(
+        profileName,
+        nextConfig.profiles[profileName] ?? {},
+        nextConfig.defaultProfile,
+      );
+
+      if (getGlobalOptions(this).json) {
+        emitJson(stdout, "profiles add", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Added profile "${profileName}".`);
+    });
+
+  profiles
+    .command("update")
+    .description("Update an existing profile")
+    .argument("<profile>", "profile name")
+    .option("--api-key <token>", "API key")
+    .option("--base-url <url>", "base URL")
+    .action(function action(
+      this: Command,
+      profileName: string,
+      commandOptions: { apiKey?: string; baseUrl?: string },
+    ) {
+      if (commandOptions.apiKey === undefined && commandOptions.baseUrl === undefined) {
+        throw new CliError(
+          "configuration_error",
+          'Provide at least one of "--api-key" or "--base-url".',
+        );
+      }
+
+      const config = readRequiredConfig(filePath);
+      getRequiredProfile(config, profileName);
+
+      const nextConfig = setProfileConfig(config, profileName, {
+        apiKey: commandOptions.apiKey,
+        baseUrl: commandOptions.baseUrl,
+      });
+
+      writeConfig(nextConfig, filePath);
+      const data = toDisplayProfile(
+        profileName,
+        nextConfig.profiles[profileName] ?? {},
+        nextConfig.defaultProfile,
+      );
+
+      if (getGlobalOptions(this).json) {
+        emitJson(stdout, "profiles update", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Updated profile "${profileName}".`);
+    });
+
+  profiles
+    .command("remove")
+    .description("Remove a profile from the local config")
+    .argument("<profile>", "profile name")
+    .action(function action(this: Command, profileName: string) {
+      const config = readRequiredConfig(filePath);
+      getRequiredProfile(config, profileName);
+
+      const nextConfig = removeProfileConfig(config, profileName);
+      writeConfig(nextConfig, filePath);
+      const data = {
+        profile: profileName,
+        defaultProfile: nextConfig.defaultProfile,
+      };
+
+      if (getGlobalOptions(this).json) {
+        emitJson(stdout, "profiles remove", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Removed profile "${profileName}".`);
+    });
+}

package/src/commands/records.test.ts

@@ -0,0 +1,367 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { buildProgram } from "../index.js";
+
+function createTempConfig(contents: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "zinkee-records-"));
+  const filePath = join(dir, "config.toml");
+  writeFileSync(filePath, contents, "utf8");
+  return filePath;
+}
+
+function createApiConfig(): string {
+  return createTempConfig(`
+default_profile = "prod"
+
+[profiles.prod]
+api_key = "records-token-1234"
+base_url = "https://api.zinkee.test"
+`);
+}
+
+function createStdoutBuffer() {
+  let output = "";
+
+  return {
+    stdout: {
+      write(chunk: string) {
+        output += chunk;
+        return true;
+      },
+    },
+    read() {
+      return output;
+    },
+  };
+}
+
+function jsonResponse(body: unknown, status: number = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+    },
+  });
+}
+
+function createFetchMock() {
+  const fetchMock = vi.fn<typeof fetch>();
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+function mockSchemaLookup(fetchMock: ReturnType<typeof createFetchMock>, id: string = "schema-1") {
+  fetchMock.mockResolvedValueOnce(
+    jsonResponse([
+      {
+        id,
+        slug: "contacts",
+        name: "Contacts",
+      },
+    ]),
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("records commands", () => {
+  it("registers the records command group", () => {
+    const program = buildProgram();
+
+    expect(program.commands.some((command) => command.name() === "records")).toBe(true);
+  });
+
+  it("lists records with simple pagination and emits page metadata", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        records: [
+          {
+            recordId: "record-1",
+            values: { name: "Ana" },
+          },
+        ],
+        page: { offset: 20, limit: 10, total: 1, count: 1, hasMore: false },
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "list",
+      "contacts",
+      "--limit",
+      "10",
+      "--offset",
+      "20",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("https://api.zinkee.test/api/v2/schemas");
+
+    const url = new URL(String(fetchMock.mock.calls[1]?.[0]));
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(url.origin + url.pathname).toBe("https://api.zinkee.test/api/v2/schemas/schema-1/records");
+    expect(init?.method).toBe("GET");
+    expect(url.searchParams.get("limit")).toBe("10");
+    expect(url.searchParams.get("offset")).toBe("20");
+    expect(JSON.parse(output.read())).toEqual({
+      data: [{ recordId: "record-1", values: { name: "Ana" } }],
+      meta: {
+        command: "records list",
+        configPath,
+        page: { offset: 20, limit: 10, total: 1, count: 1, hasMore: false },
+      },
+    });
+  });
+
+  it("queries records with the same normalized query model used by list", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        records: [{ recordId: "record-1", values: { name: "Ana" } }],
+        page: { offset: 10, limit: 5, total: 1, count: 1, hasMore: false },
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "query",
+      "contacts",
+      "--select",
+      "id,name",
+      "--where",
+      "status eq active",
+      "--sort",
+      "name:asc,createdAt:desc",
+      "--limit",
+      "5",
+      "--offset",
+      "10",
+      "--raw",
+      '{"select":["wrong"],"extra":"keep"}',
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+    const headers = new Headers(init?.headers);
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/schema-1/records:query",
+    );
+    expect(init?.method).toBe("POST");
+    expect(headers.get("content-type")).toBe("application/json");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      extra: "keep",
+      select: ["id", "name"],
+      where: [
+        {
+          field: "status",
+          op: "eq",
+          value: "active",
+        },
+      ],
+      sort: [
+        { field: "name", direction: "ASC" },
+        { field: "createdAt", direction: "DESC" },
+      ],
+      page: { limit: 5, offset: 10 },
+    });
+    expect(JSON.parse(output.read())).toEqual({
+      data: [{ recordId: "record-1", values: { name: "Ana" } }],
+      meta: {
+        command: "records query",
+        configPath,
+        page: { offset: 10, limit: 5, total: 1, count: 1, hasMore: false },
+      },
+    });
+  });
+
+  it("normalizes UUID selectors for records get", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        recordId: "550e8400-e29b-41d4-a716-446655440001",
+        values: { name: "Ana" },
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "get",
+      "550E8400-E29B-41D4-A716-446655440000",
+      "550E8400-E29B-41D4-A716-446655440001",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/550e8400-e29b-41d4-a716-446655440000/records/550e8400-e29b-41d4-a716-446655440001",
+    );
+  });
+
+  it("creates records by merging raw JSON with set and set-json assignments", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "record-1",
+        name: "Ana",
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "create",
+      "contacts",
+      "--set",
+      "name=Ana",
+      "--set-json",
+      'profile={"tier":"gold"}',
+      "--raw",
+      '{"name":"Wrong","status":"active"}',
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/schema-1/records",
+    );
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      values: {
+        name: "Ana",
+        status: "active",
+        profile: {
+          tier: "gold",
+        },
+      },
+    });
+  });
+
+  it("updates records with the patch-style set and unset contract", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const rawFile = join(
+      mkdtempSync(join(tmpdir(), "zinkee-record-update-")),
+      "record.json",
+    );
+    writeFileSync(
+      rawFile,
+      JSON.stringify({
+        set: {
+          status: "inactive",
+          metadata: {
+            imported: true,
+          },
+        },
+        unset: ["legacyCode"],
+        audit: {
+          reason: "sync",
+        },
+      }),
+      "utf8",
+    );
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "550e8400-e29b-41d4-a716-446655440001",
+        status: "active",
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "update",
+      "contacts",
+      "550E8400-E29B-41D4-A716-446655440001",
+      "--set",
+      "status=active",
+      "--set-json",
+      'profile={"tier":"gold"}',
+      "--unset",
+      "tempField",
+      "--unset",
+      "status",
+      "--raw-file",
+      rawFile,
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/schema-1/records/550e8400-e29b-41d4-a716-446655440001",
+    );
+    expect(init?.method).toBe("PATCH");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      audit: {
+        reason: "sync",
+      },
+      set: {
+        status: "active",
+        metadata: {
+          imported: true,
+        },
+        profile: {
+          tier: "gold",
+        },
+      },
+      unset: ["legacyCode", "tempField"],
+    });
+  });
+
+  it("blocks destructive record commands in read-only mode", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--read-only",
+        "records",
+        "delete",
+        "contacts",
+        "record-1",
+      ]),
+    ).rejects.toThrowError('Command "records delete" is not allowed in read-only mode.');
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});