zinkee 0.1.23 → 0.1.25

package/src/commands/document-templates.ts

@@ -0,0 +1,563 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import type { Writable } from "node:stream";
+
+import { Command, InvalidArgumentError } from "commander";
+
+import {
+  DocumentTemplatesApi,
+  type ApiDocumentTemplate,
+  type CreateDocumentTemplateInput,
+  type UpdateDocumentTemplateInput,
+} from "../api/document-templates.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 { JsonObject, RuntimeOverrides } from "../types.js";
+import { CliError } from "../utils/errors.js";
+import { buildJsonSuccess, printTable } from "../utils/output.js";
+
+interface CommandIo {
+  write(chunk: string | Uint8Array): unknown;
+}
+
+export interface RegisterDocumentTemplatesCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions extends RuntimeOverrides {}
+
+interface TemplateCreateCommandOptions {
+  name?: string;
+  raw?: string;
+  rawFile?: string;
+}
+
+interface TemplateUpdateCommandOptions {
+  name?: string;
+}
+
+interface AssetAddCommandOptions {
+  name?: string;
+}
+
+interface AssetDownloadCommandOptions {
+  output?: 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 writeBinary(stdout: CommandIo, value: ArrayBuffer): void {
+  stdout.write(Buffer.from(value));
+}
+
+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 createDocumentTemplatesApi(
+  command: Command,
+  filePath: string,
+): { api: DocumentTemplatesApi; 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 DocumentTemplatesApi(
+        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,
+  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 isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isEmptyObject(value: object): boolean {
+  return Object.keys(value).length === 0;
+}
+
+function parseJsonValue(input: string, sourceLabel: string): unknown {
+  try {
+    return 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}`,
+    );
+  }
+}
+
+function readTextFile(filePath: string, label: string): string {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unable to read file.";
+    throw new CliError(
+      "invalid_cli_usage",
+      `Failed to read ${label} from ${filePath}: ${message}`,
+    );
+  }
+}
+
+function readJsonObjectOption(
+  raw: string | undefined,
+  rawFile: string | undefined,
+  rawLabel: string,
+  rawFileLabel: string,
+): JsonObject {
+  if (raw && rawFile) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Provide either "${rawLabel}" or "${rawFileLabel}", not both.`,
+    );
+  }
+
+  let parsed: unknown;
+
+  if (raw) {
+    parsed = parseJsonValue(raw, rawLabel);
+  } else if (rawFile) {
+    parsed = parseJsonValue(readTextFile(rawFile, rawFileLabel), `${rawFileLabel} ${rawFile}`);
+  } else {
+    return {};
+  }
+
+  if (!isJsonObject(parsed)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Expected ${raw ? rawLabel : rawFileLabel} to contain a JSON object.`,
+    );
+  }
+
+  return parsed;
+}
+
+function readLocalFile(filePath: string): Buffer {
+  try {
+    return readFileSync(filePath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unable to read file.";
+    throw new CliError("invalid_cli_usage", `Failed to read file at ${filePath}: ${message}`);
+  }
+}
+
+function writeDownloadedFile(outputPath: string, value: ArrayBuffer): void {
+  try {
+    writeFileSync(outputPath, Buffer.from(value));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unable to write file.";
+    throw new CliError(
+      "invalid_cli_usage",
+      `Failed to write downloaded file to ${outputPath}: ${message}`,
+    );
+  }
+}
+
+function templateRows(templates: readonly ApiDocumentTemplate[]): Record<string, unknown>[] {
+  return templates.map((template) => ({
+    id: template.id ?? "",
+    name: template.name ?? "",
+    assetCount: Array.isArray(template.assets) ? template.assets.length : 0,
+    updatedAt: template.updatedAt ?? "",
+  }));
+}
+
+function resolveTemplate(
+  templates: readonly ApiDocumentTemplate[],
+  selector: NormalizedUuidOrSlug,
+): ApiDocumentTemplate {
+  if (selector.kind === "uuid") {
+    const match = templates.find((template) => template.id === selector.value);
+
+    if (match) {
+      return match;
+    }
+
+    throw new CliError(
+      "invalid_cli_usage",
+      `Document template "${selector.value}" was not found.`,
+    );
+  }
+
+  const matches = templates.filter((template) => template.name === selector.value);
+
+  if (matches.length === 1) {
+    return matches[0] as ApiDocumentTemplate;
+  }
+
+  if (matches.length > 1) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Document template "${selector.value}" is ambiguous. Found ${matches.length} matches.`,
+    );
+  }
+
+  throw new CliError(
+    "invalid_cli_usage",
+    `Document template "${selector.value}" was not found.`,
+  );
+}
+
+async function resolveTemplateSelector(
+  api: DocumentTemplatesApi,
+  selector: NormalizedUuidOrSlug,
+): Promise<NormalizedUuidOrSlug> {
+  if (selector.kind === "uuid") {
+    return selector;
+  }
+
+  const templates = await api.listTemplates();
+  const resolved = resolveTemplate(templates, selector);
+
+  if (typeof resolved.id !== "string" || resolved.id.length === 0) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Document template "${selector.value}" is missing an id in the API response.`,
+    );
+  }
+
+  return { kind: "uuid", value: resolved.id };
+}
+
+function buildCreateInput(
+  options: TemplateCreateCommandOptions,
+): CreateDocumentTemplateInput {
+  const raw = readJsonObjectOption(options.raw, options.rawFile, "--raw", "--raw-file");
+  const input: JsonObject = { ...raw };
+
+  if (options.name !== undefined) {
+    input.name = options.name;
+  }
+
+  if (typeof input.name !== "string" || input.name.trim().length === 0) {
+    throw new CliError("invalid_cli_usage", 'Provide template name via "--name".');
+  }
+
+  if (input.assets === undefined) {
+    input.assets = [];
+  }
+
+  return input as unknown as CreateDocumentTemplateInput;
+}
+
+function buildUpdateInput(
+  options: TemplateUpdateCommandOptions,
+): UpdateDocumentTemplateInput {
+  const input: UpdateDocumentTemplateInput = {};
+
+  if (options.name !== undefined) {
+    input.name = options.name;
+  }
+
+  if (isEmptyObject(input as object)) {
+    throw new CliError("invalid_cli_usage", 'Provide template updates via "--name".');
+  }
+
+  return input;
+}
+
+export function registerDocumentTemplatesCommands(
+  program: Command,
+  options: RegisterDocumentTemplatesCommandsOptions = {},
+): void {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const templates = program
+    .command("document-templates")
+    .description("Manage document templates and their assets");
+
+  templates
+    .command("list")
+    .description("List document templates")
+    .action(async function action(this: Command) {
+      const { api, json } = createDocumentTemplatesApi(this, filePath);
+      const data = await api.listTemplates();
+
+      if (json) {
+        emitJson(stdout, "document-templates list", data, filePath);
+        return;
+      }
+
+      printTable(templateRows(data), ["id", "name", "assetCount", "updatedAt"], stdout);
+    });
+
+  templates
+    .command("get")
+    .description("Get a document template by UUID or exact name")
+    .argument("<template>", "template UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, template: NormalizedUuidOrSlug) {
+      const { api, json } = createDocumentTemplatesApi(this, filePath);
+      const list = await api.listTemplates();
+      const data = resolveTemplate(list, template);
+
+      if (json) {
+        emitJson(stdout, "document-templates get", data, filePath);
+        return;
+      }
+
+      printTable([data as Record<string, unknown>], undefined, stdout);
+    });
+
+  templates
+    .command("create")
+    .description("Create a document template")
+    .option("--name <name>", "template name")
+    .option("--raw <json>", "raw create JSON payload")
+    .option("--raw-file <path>", "path to raw create JSON payload")
+    .action(async function action(
+      this: Command,
+      commandOptions: TemplateCreateCommandOptions,
+    ) {
+      const { api, json, readOnly } = createDocumentTemplatesApi(this, filePath);
+      ensureWritable("document-templates create", readOnly, "write");
+      const data = await api.createTemplate(buildCreateInput(commandOptions));
+
+      if (json) {
+        emitJson(stdout, "document-templates create", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Created document template "${String(data.name ?? commandOptions.name)}".`);
+    });
+
+  templates
+    .command("update")
+    .description("Rename a document template")
+    .argument("<template>", "template UUID or exact name", parseUuidOrSlugSelector)
+    .option("--name <name>", "new template name")
+    .action(async function action(
+      this: Command,
+      template: NormalizedUuidOrSlug,
+      commandOptions: TemplateUpdateCommandOptions,
+    ) {
+      const { api, json, readOnly } = createDocumentTemplatesApi(this, filePath);
+      ensureWritable("document-templates update", readOnly, "write");
+      const resolved = await resolveTemplateSelector(api, template);
+      const data = await api.updateTemplate(resolved, buildUpdateInput(commandOptions));
+
+      if (json) {
+        emitJson(stdout, "document-templates update", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Updated document template "${String(data.name ?? template.value)}".`);
+    });
+
+  templates
+    .command("delete")
+    .description("Delete a document template (and its assets)")
+    .argument("<template>", "template UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, template: NormalizedUuidOrSlug) {
+      const { api, json, readOnly } = createDocumentTemplatesApi(this, filePath);
+      ensureWritable("document-templates delete", readOnly, "destructive");
+      const resolved = await resolveTemplateSelector(api, template);
+      const data = await api.deleteTemplate(resolved);
+
+      if (json) {
+        emitJson(stdout, "document-templates delete", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Deleted document template "${template.value}".`);
+    });
+
+  const assets = templates.command("assets").description("Manage document template assets");
+
+  assets
+    .command("add")
+    .description("Upload an asset file to a document template")
+    .argument("<template>", "template UUID or exact name", parseUuidOrSlugSelector)
+    .argument("<path>", "path to the local file")
+    .option("--name <name>", "override the asset display name")
+    .action(async function action(
+      this: Command,
+      template: NormalizedUuidOrSlug,
+      localPath: string,
+      commandOptions: AssetAddCommandOptions,
+    ) {
+      const { api, json, readOnly } = createDocumentTemplatesApi(this, filePath);
+      ensureWritable("document-templates assets add", readOnly, "write");
+
+      const contents = readLocalFile(localPath);
+      const formData = new FormData();
+      formData.append("file", new Blob([contents]), basename(localPath));
+
+      if (commandOptions.name !== undefined) {
+        formData.append("name", commandOptions.name);
+      }
+
+      const resolved = await resolveTemplateSelector(api, template);
+      const data = await api.addAsset(resolved, formData);
+
+      if (json) {
+        emitJson(stdout, "document-templates assets add", data, filePath);
+        return;
+      }
+
+      writeLine(
+        stdout,
+        `Added asset "${commandOptions.name ?? basename(localPath)}" to template "${template.value}".`,
+      );
+    });
+
+  assets
+    .command("delete")
+    .description("Delete one asset from a document template")
+    .argument("<template>", "template UUID or exact name", parseUuidOrSlugSelector)
+    .argument("<asset>", "asset UUID")
+    .action(async function action(
+      this: Command,
+      template: NormalizedUuidOrSlug,
+      assetId: string,
+    ) {
+      const { api, json, readOnly } = createDocumentTemplatesApi(this, filePath);
+      ensureWritable("document-templates assets delete", readOnly, "destructive");
+      const resolved = await resolveTemplateSelector(api, template);
+      const data = await api.deleteAsset(resolved, assetId);
+
+      if (json) {
+        emitJson(stdout, "document-templates assets delete", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Deleted asset "${assetId}" from template "${template.value}".`);
+    });
+
+  assets
+    .command("download")
+    .description("Download the raw bytes of a document template asset")
+    .argument("<template>", "template UUID or exact name", parseUuidOrSlugSelector)
+    .argument("<asset>", "asset UUID")
+    .option("--output <path>", "write the downloaded bytes to a path")
+    .action(async function action(
+      this: Command,
+      template: NormalizedUuidOrSlug,
+      assetId: string,
+      commandOptions: AssetDownloadCommandOptions,
+    ) {
+      const { api, json } = createDocumentTemplatesApi(this, filePath);
+
+      if (json && !commandOptions.output) {
+        throw new CliError(
+          "invalid_cli_usage",
+          'Provide "--output" when using "--json" with "document-templates assets download".',
+        );
+      }
+
+      const resolved = await resolveTemplateSelector(api, template);
+      const data = await api.downloadAsset(resolved, assetId);
+
+      if (commandOptions.output) {
+        writeDownloadedFile(commandOptions.output, data);
+
+        if (json) {
+          emitJson(
+            stdout,
+            "document-templates assets download",
+            {
+              template: resolved.value,
+              asset: assetId,
+              output: commandOptions.output,
+              bytes: data.byteLength,
+            },
+            filePath,
+          );
+          return;
+        }
+
+        writeLine(stdout, `Downloaded asset to "${commandOptions.output}".`);
+        return;
+      }
+
+      writeBinary(stdout, data);
+    });
+}

package/src/commands/navigation.test.ts

@@ -157,7 +157,7 @@ describe("navigation commands", () => {
     ).rejects.toThrowError('Folder "Finance" is ambiguous. Found 2 matches.');
   });
 
-  it("shapes move payloads using the resource type and resolved folder id", async () => {
+  it("shapes move payloads using the resolved folder id (schemas only, no resource type)", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
     const fetchMock = createFetchMock();
@@ -171,7 +171,7 @@ describe("navigation commands", () => {
             {
               id: "resource-1",
               name: "Invoices",
-              type: "DISPLAY",
+              type: "SCHEMA",
               isInSpace: false,
             },
           ],
@@ -189,8 +189,6 @@ describe("navigation commands", () => {
       "resources",
       "move",
       "resource-1",
-      "--type",
-      "display",
       "--to",
       "Finance",
     ]);
@@ -207,7 +205,6 @@ describe("navigation commands", () => {
     expect(moveInit?.method).toBe("POST");
     expect(JSON.parse(String(moveInit?.body))).toEqual({
       resourceId: "resource-1",
-      resourceType: "DISPLAY",
       targetFolderId: "aaaabbbb-cccc-dddd-eeee-ffffffffffff",
     });
   });

package/src/commands/navigation.ts

@@ -251,9 +251,9 @@ export function registerNavigationCommands(
     .command("create")
     .description("Create a navigation folder")
     .requiredOption("--name <name>", "folder name")
-    .option("--order <n>", "folder order")
-    .option("--props <json>", "folder additionalProperties JSON")
-    .option("--props-file <path>", "folder additionalProperties JSON file")
+    .option("--order <n>", "display order (lower values appear first)")
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"color\":\"blue\",\"icon\":\"chart-line\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(this: Command, commandOptions: FolderMutationOptions) {
       const { api, json, readOnly } = createNavigationApi(this, filePath);
       ensureWritable("navigation folders create", readOnly, "write");
@@ -272,9 +272,9 @@ export function registerNavigationCommands(
     .description("Update a navigation folder")
     .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
     .option("--name <name>", "folder name")
-    .option("--order <n>", "folder order")
-    .option("--props <json>", "folder additionalProperties JSON")
-    .option("--props-file <path>", "folder additionalProperties JSON file")
+    .option("--order <n>", "display order (lower values appear first)")
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"color\":\"blue\",\"icon\":\"chart-line\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(this: Command, folder: NormalizedUuidOrSlug, commandOptions: FolderMutationOptions) {
       const { api, json, readOnly } = createNavigationApi(this, filePath);
       ensureWritable("navigation folders update", readOnly, "write");
@@ -319,14 +319,15 @@ export function registerNavigationCommands(
     .command("resources")
     .description("Manage navigation resources")
     .command("move")
-    .description("Move a resource into a folder")
-    .argument("<resource>", "resource UUID")
-    .requiredOption("--type <type>", "resource type")
+    .description(
+      "Move a schema into a navigation folder. Only schemas can be moved (the navigation menu holds databases); schedules and sub-schemas follow their parent schema. Use the root folder UUID 00000000-0000-0000-0000-000000000000 to move it back to the workspace root.",
+    )
+    .argument("<resource>", "schema UUID")
     .requiredOption("--to <folder>", "target folder UUID or exact name")
     .action(async function action(
       this: Command,
       resourceId: string,
-      commandOptions: { type: string; to: string },
+      commandOptions: { to: string },
     ) {
       const { api, json, readOnly } = createNavigationApi(this, filePath);
       ensureWritable("navigation resources move", readOnly, "write");
@@ -334,7 +335,6 @@ export function registerNavigationCommands(
       const resolved = resolveFolder(allFolders, parseUuidOrSlugSelector(commandOptions.to));
       const data = await api.moveResource({
         resourceId,
-        resourceType: commandOptions.type.toUpperCase(),
         targetFolderId: resolved.id,
       });