zinkee 0.1.0

package/src/commands/records.ts

@@ -0,0 +1,726 @@
+import { readFileSync } from "node:fs";
+import type { Writable } from "node:stream";
+
+import { Command, InvalidArgumentError } from "commander";
+
+import {
+  type ApiRecord,
+  type CreateRecordInput,
+  type RecordQueryExpression,
+  type RecordQueryInput,
+  type RecordQueryResult,
+  RecordsApi,
+  type UpdateRecordInput,
+} from "../api/records.js";
+import { SchemasApi } from "../api/schemas.js";
+import { ApiClient } from "../client.js";
+import { defaultConfigPath, readConfig } from "../config.js";
+import {
+  type ParsedExpression,
+  parseExpression,
+} from "../parsers/expressions.js";
+import {
+  parseJsonAssignment,
+  parseKeyValue,
+  type JsonKeyValueAssignment,
+  type KeyValueAssignment,
+} from "../parsers/kv.js";
+import {
+  normalizeUuidOrSlug,
+  type NormalizedUuidOrSlug,
+} from "../parsers/selectors.js";
+import { resolveRuntimeContext } from "../runtime-context.js";
+import type { JsonObject, RuntimeOverrides } from "../types.js";
+import { CliError } from "../utils/errors.js";
+import { buildJsonSuccess, printTable } from "../utils/output.js";
+
+interface CommandIo {
+  write(chunk: string): unknown;
+}
+
+export interface RegisterRecordsCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions extends RuntimeOverrides {}
+
+interface RecordsQueryCommandOptions {
+  select?: string[];
+  where?: ParsedExpression[];
+  sort?: string[];
+  limit?: number;
+  offset?: number;
+  raw?: string;
+  rawFile?: string;
+}
+
+interface RecordsListCommandOptions {
+  limit?: number;
+  offset?: number;
+}
+
+interface RecordsCreateCommandOptions {
+  set?: KeyValueAssignment[];
+  setJson?: JsonKeyValueAssignment[];
+  raw?: string;
+  rawFile?: string;
+}
+
+interface RecordsUpdateCommandOptions extends RecordsCreateCommandOptions {
+  unset?: string[];
+}
+
+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,
+  meta: Record<string, unknown> = {},
+): void {
+  writeLine(
+    stdout,
+    JSON.stringify(buildJsonSuccess(data, { command: commandName, configPath, ...meta })),
+  );
+}
+
+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 createRecordsApi(
+  command: Command,
+  filePath: string,
+): {
+  api: RecordsApi;
+  schemasApi: SchemasApi;
+  json: boolean;
+  profile: string;
+  readOnly: boolean;
+} {
+  try {
+    const config = readConfig(filePath);
+    const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
+
+    if (!runtime.baseUrl) {
+      throw new CliError(
+        "configuration_error",
+        `Resolved profile "${runtime.profile}" is missing a base URL.`,
+      );
+    }
+
+    const client = new ApiClient({
+      baseUrl: runtime.baseUrl,
+      apiKey: runtime.apiKey,
+    });
+
+    return {
+      api: new RecordsApi(client),
+      schemasApi: new SchemasApi(client),
+      json: runtime.json,
+      profile: runtime.profile,
+      readOnly: runtime.readOnly,
+    };
+  } catch (error) {
+    toConfigurationError(filePath, error);
+  }
+}
+
+function ensureWritable(
+  commandName: string,
+  readOnly: boolean,
+  commandMode: "write" | "destructive",
+): void {
+  if (readOnly) {
+    throw new CliError(
+      "command_not_allowed_in_read_only_mode",
+      `Command "${commandName}" is not allowed in read-only mode.`,
+      {
+        commandMode,
+        executionMode: "read-only",
+      },
+    );
+  }
+}
+
+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 parseNonNegativeInteger(input: string): number {
+  if (!/^\d+$/.test(input.trim())) {
+    throw new InvalidArgumentError(`Expected a non-negative integer, received "${input}".`);
+  }
+
+  return Number(input);
+}
+
+function parseCommaSeparatedValues(
+  input: string,
+  label: string,
+): string[] {
+  const values = input
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  if (values.length === 0) {
+    throw new InvalidArgumentError(`Expected ${label} to contain at least one value.`);
+  }
+
+  return values;
+}
+
+function parseExpressionValue(input: string): ParsedExpression {
+  try {
+    return parseExpression(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid expression.";
+    throw new InvalidArgumentError(message);
+  }
+}
+
+function parseKeyValueAssignment(input: string): KeyValueAssignment {
+  try {
+    return parseKeyValue(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid assignment.";
+    throw new InvalidArgumentError(message);
+  }
+}
+
+function parseJsonKeyValueAssignment(input: string): JsonKeyValueAssignment {
+  try {
+    return parseJsonAssignment(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid JSON assignment.";
+    throw new InvalidArgumentError(message);
+  }
+}
+
+function collectStringValues(value: string, previous: string[] = []): string[] {
+  return [...previous, value];
+}
+
+function collectSortValues(value: string, previous: string[] = []): string[] {
+  return [...previous, ...parseCommaSeparatedValues(value, "--sort")];
+}
+
+function collectWhereExpressions(
+  value: string,
+  previous: ParsedExpression[] = [],
+): ParsedExpression[] {
+  return [...previous, parseExpressionValue(value)];
+}
+
+function collectKeyValueAssignments(
+  value: string,
+  previous: KeyValueAssignment[] = [],
+): KeyValueAssignment[] {
+  return [...previous, parseKeyValueAssignment(value)];
+}
+
+function collectJsonAssignments(
+  value: string,
+  previous: JsonKeyValueAssignment[] = [],
+): JsonKeyValueAssignment[] {
+  return [...previous, parseJsonKeyValueAssignment(value)];
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseRawJsonObject(input: string, sourceLabel: string): JsonObject {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid JSON.";
+    throw new CliError(
+      "invalid_cli_usage",
+      `Failed to parse JSON from ${sourceLabel}: ${message}`,
+    );
+  }
+
+  if (!isJsonObject(parsed)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Expected ${sourceLabel} to contain a JSON object.`,
+    );
+  }
+
+  return parsed;
+}
+
+function readRawObject(
+  raw: string | undefined,
+  rawFile: string | undefined,
+): JsonObject {
+  if (raw && rawFile) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Provide either "--raw" or "--raw-file", not both.',
+    );
+  }
+
+  if (raw) {
+    return parseRawJsonObject(raw, "--raw");
+  }
+
+  if (rawFile) {
+    let contents: string;
+
+    try {
+      contents = readFileSync(rawFile, "utf8");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unable to read file.";
+      throw new CliError(
+        "invalid_cli_usage",
+        `Failed to read raw payload from ${rawFile}: ${message}`,
+      );
+    }
+
+    return parseRawJsonObject(contents, `--raw-file ${rawFile}`);
+  }
+
+  return {};
+}
+
+function isEmptyObject(value: object): boolean {
+  return Object.keys(value).length === 0;
+}
+
+function buildAssignmentObject(
+  assignments: readonly KeyValueAssignment[] = [],
+  jsonAssignments: readonly JsonKeyValueAssignment[] = [],
+): Record<string, unknown> {
+  const output: Record<string, unknown> = {};
+
+  for (const assignment of assignments) {
+    output[assignment.key] = assignment.value;
+  }
+
+  for (const assignment of jsonAssignments) {
+    output[assignment.key] = assignment.value;
+  }
+
+  return output;
+}
+
+function toQueryExpressions(
+  expressions: readonly ParsedExpression[] | undefined,
+): RecordQueryExpression[] | undefined {
+  if (!expressions || expressions.length === 0) {
+    return undefined;
+  }
+
+  return expressions.map((expression) => ({
+    field: expression.field,
+    comparator: expression.comparator,
+    value: expression.value,
+  }));
+}
+
+function buildRecordQueryInput(
+  options: RecordsQueryCommandOptions,
+  allowRaw: boolean,
+): RecordQueryInput {
+  const input: RecordQueryInput = allowRaw
+    ? readRawObject(options.raw, options.rawFile)
+    : {};
+
+  if (options.select && options.select.length > 0) {
+    input.select = [...options.select];
+  }
+
+  const where = toQueryExpressions(options.where);
+
+  if (where && where.length > 0) {
+    input.where = where;
+  }
+
+  if (options.sort && options.sort.length > 0) {
+    input.sort = [...options.sort];
+  }
+
+  if (options.limit !== undefined) {
+    input.limit = options.limit;
+  }
+
+  if (options.offset !== undefined) {
+    input.offset = options.offset;
+  }
+
+  return input;
+}
+
+function buildRecordCreateInput(
+  options: RecordsCreateCommandOptions,
+): CreateRecordInput {
+  const values = {
+    ...readRawObject(options.raw, options.rawFile),
+    ...buildAssignmentObject(options.set, options.setJson),
+  };
+
+  if (isEmptyObject(values)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Provide record fields via "--set", "--set-json", "--raw", or "--raw-file".',
+    );
+  }
+
+  return { values };
+}
+
+function readRawSetPayload(raw: JsonObject): Record<string, unknown> {
+  const setValue = raw.set;
+
+  if (setValue === undefined) {
+    return {};
+  }
+
+  if (!isJsonObject(setValue)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Expected raw update payload field "set" to be a JSON object.',
+    );
+  }
+
+  return { ...setValue };
+}
+
+function readRawUnsetPayload(raw: JsonObject): string[] {
+  const unsetValue = raw.unset;
+
+  if (unsetValue === undefined) {
+    return [];
+  }
+
+  if (!Array.isArray(unsetValue) || !unsetValue.every((value) => typeof value === "string")) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Expected raw update payload field "unset" to be an array of strings.',
+    );
+  }
+
+  return [...unsetValue];
+}
+
+function buildRecordUpdateInput(
+  options: RecordsUpdateCommandOptions,
+): UpdateRecordInput {
+  const raw = readRawObject(options.raw, options.rawFile);
+  const input: UpdateRecordInput = { ...raw };
+  const setPayload = {
+    ...readRawSetPayload(raw),
+    ...buildAssignmentObject(options.set, options.setJson),
+  };
+  const unsetPayload = [...readRawUnsetPayload(raw), ...(options.unset ?? [])];
+
+  for (const key of Object.keys(setPayload)) {
+    const unsetIndex = unsetPayload.indexOf(key);
+
+    if (unsetIndex !== -1) {
+      unsetPayload.splice(unsetIndex, 1);
+    }
+  }
+
+  if (Object.keys(setPayload).length > 0) {
+    input.set = setPayload;
+  } else {
+    delete input.set;
+  }
+
+  if (unsetPayload.length > 0) {
+    input.unset = [...new Set(unsetPayload)];
+  } else {
+    delete input.unset;
+  }
+
+  if (isEmptyObject(input)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Provide record updates via "--set", "--set-json", "--unset", "--raw", or "--raw-file".',
+    );
+  }
+
+  return input;
+}
+
+function toTableRows(data: unknown): Record<string, unknown>[] {
+  if (Array.isArray(data)) {
+    return data.map((entry) => (isJsonObject(entry) ? entry : { value: entry }));
+  }
+
+  if (isJsonObject(data)) {
+    return [data];
+  }
+
+  return [{ value: data }];
+}
+
+function emitTable(stdout: CommandIo, data: unknown): void {
+  printTable(toTableRows(data), undefined, stdout);
+}
+
+function getQueryRecords(result: RecordQueryResult): ApiRecord[] {
+  return Array.isArray(result.records) ? result.records : [];
+}
+
+function getRecordIdentifier(record: ApiRecord): string {
+  return typeof record.recordId === "string" ? record.recordId : "unknown";
+}
+
+async function resolveSchemaSelector(
+  api: SchemasApi,
+  selector: NormalizedUuidOrSlug,
+): Promise<NormalizedUuidOrSlug> {
+  if (selector.kind === "uuid") {
+    return selector;
+  }
+
+  const schemas = await api.listSchemas();
+  const match = schemas.find((entry) => entry.slug === selector.value);
+
+  if (!match || typeof match.id !== "string") {
+    throw new CliError("invalid_cli_usage", `Schema "${selector.value}" not found.`);
+  }
+
+  return {
+    kind: "uuid",
+    value: match.id,
+  };
+}
+
+export function registerRecordsCommands(
+  program: Command,
+  options: RegisterRecordsCommandsOptions = {},
+): void {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const records = program.command("records").description("Manage schema records");
+
+  records
+    .command("list")
+    .description("List records for a schema with simple pagination")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .option("--limit <number>", "limit results", parseNonNegativeInteger)
+    .option("--offset <number>", "offset results", parseNonNegativeInteger)
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      commandOptions: RecordsListCommandOptions,
+    ) {
+      const { api, schemasApi, json } = createRecordsApi(this, filePath);
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+      const data = await api.listRecords(
+        resolvedSchema,
+        buildRecordQueryInput(commandOptions, false),
+      );
+      const recordsData = getQueryRecords(data);
+
+      if (json) {
+        emitJson(
+          stdout,
+          "records list",
+          recordsData,
+          filePath,
+          data.page ? { page: data.page } : {},
+        );
+        return;
+      }
+
+      emitTable(stdout, recordsData);
+    });
+
+  records
+    .command("query")
+    .description("Query records for a schema")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .option("--select <fields>", "comma-separated field selection", (value) => (
+      parseCommaSeparatedValues(value, "--select")
+    ))
+    .option("--where <expression>", "where expression", collectWhereExpressions, [])
+    .option("--sort <field:direction>", "sort field(s)", collectSortValues, [])
+    .option("--limit <number>", "limit results", parseNonNegativeInteger)
+    .option("--offset <number>", "offset results", parseNonNegativeInteger)
+    .option("--raw <json>", "raw JSON object payload")
+    .option("--raw-file <path>", "path to a raw JSON object payload")
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      commandOptions: RecordsQueryCommandOptions,
+    ) {
+      const { api, schemasApi, json } = createRecordsApi(this, filePath);
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+      const data = await api.queryRecords(
+        resolvedSchema,
+        buildRecordQueryInput(commandOptions, true),
+      );
+      const recordsData = getQueryRecords(data);
+
+      if (json) {
+        emitJson(
+          stdout,
+          "records query",
+          recordsData,
+          filePath,
+          data.page ? { page: data.page } : {},
+        );
+        return;
+      }
+
+      emitTable(stdout, recordsData);
+    });
+
+  records
+    .command("get")
+    .description("Get a record by UUID or slug")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .argument("<record>", "record uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      record: NormalizedUuidOrSlug,
+    ) {
+      const { api, schemasApi, json } = createRecordsApi(this, filePath);
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+      const data = await api.getRecord(resolvedSchema, record);
+
+      if (json) {
+        emitJson(stdout, "records get", data, filePath);
+        return;
+      }
+
+      emitTable(stdout, data);
+    });
+
+  records
+    .command("create")
+    .description("Create a record")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .option("--set <field=value>", "set a string field", collectKeyValueAssignments, [])
+    .option("--set-json <field=json>", "set a structured field", collectJsonAssignments, [])
+    .option("--raw <json>", "raw JSON object payload")
+    .option("--raw-file <path>", "path to a raw JSON object payload")
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      commandOptions: RecordsCreateCommandOptions,
+    ) {
+      const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
+      ensureWritable("records create", readOnly, "write");
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+
+      const data = await api.createRecord(
+        resolvedSchema,
+        buildRecordCreateInput(commandOptions),
+      );
+
+      if (json) {
+        emitJson(stdout, "records create", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Created record "${getRecordIdentifier(data)}".`);
+    });
+
+  records
+    .command("update")
+    .description("Update a record")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .argument("<record>", "record uuid or slug", parseUuidOrSlugSelector)
+    .option("--set <field=value>", "set a string field", collectKeyValueAssignments, [])
+    .option("--set-json <field=json>", "set a structured field", collectJsonAssignments, [])
+    .option("--unset <field>", "unset a field", collectStringValues, [])
+    .option("--raw <json>", "raw JSON object payload")
+    .option("--raw-file <path>", "path to a raw JSON object payload")
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      record: NormalizedUuidOrSlug,
+      commandOptions: RecordsUpdateCommandOptions,
+    ) {
+      const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
+      ensureWritable("records update", readOnly, "write");
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+
+      const data = await api.updateRecord(
+        resolvedSchema,
+        record,
+        buildRecordUpdateInput(commandOptions),
+      );
+
+      if (json) {
+        emitJson(stdout, "records update", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Updated record "${getRecordIdentifier(data)}".`);
+    });
+
+  records
+    .command("delete")
+    .description("Delete a record")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .argument("<record>", "record uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      record: NormalizedUuidOrSlug,
+    ) {
+      const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
+      ensureWritable("records delete", readOnly, "destructive");
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+
+      await api.deleteRecord(resolvedSchema, record);
+      const data = {
+        schema: resolvedSchema.value,
+        record: record.value,
+        deleted: true,
+      };
+
+      if (json) {
+        emitJson(stdout, "records delete", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Deleted record "${record.value}" from schema "${schema.value}".`);
+    });
+}