zinkee 0.1.0

package/src/commands/navigation.test.ts

@@ -0,0 +1,214 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { Command } from "commander";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { registerNavigationCommands } from "./navigation.js";
+
+function createTempConfig(contents: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "zinkee-navigation-"));
+  const filePath = join(dir, "config.toml");
+  writeFileSync(filePath, contents, "utf8");
+  return filePath;
+}
+
+function createApiConfig(): string {
+  return createTempConfig(`
+default_profile = "prod"
+
+[profiles.prod]
+api_key = "navigation-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 buildProgram(configPath: string, stdout: { write(chunk: string): unknown }) {
+  const program = new Command();
+
+  program
+    .name("zinkee")
+    .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("--json", "emit JSON output");
+
+  registerNavigationCommands(program, { configPath, stdout });
+
+  return program;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("navigation commands", () => {
+  it("resolves exact folder names for get and rejects duplicate matches", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse([
+        {
+          id: "11111111-1111-1111-1111-111111111111",
+          name: "Finance",
+          order: 10,
+          resources: [],
+        },
+        {
+          id: "22222222-2222-2222-2222-222222222222",
+          name: "Marketing",
+          order: 20,
+          resources: [],
+        },
+      ]),
+    );
+    const program = buildProgram(configPath, output.stdout);
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "navigation",
+      "folders",
+      "get",
+      "Finance",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/navigation/folders",
+    );
+    expect(JSON.parse(output.read())).toEqual({
+      data: {
+        id: "11111111-1111-1111-1111-111111111111",
+        name: "Finance",
+        order: 10,
+        resources: [],
+      },
+      meta: {
+        command: "navigation folders get",
+        configPath,
+      },
+    });
+
+    fetchMock.mockReset();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse([
+        {
+          id: "11111111-1111-1111-1111-111111111111",
+          name: "Finance",
+          order: 10,
+          resources: [],
+        },
+        {
+          id: "22222222-2222-2222-2222-222222222222",
+          name: "Finance",
+          order: 20,
+          resources: [],
+        },
+      ]),
+    );
+
+    await expect(
+      buildProgram(configPath, output.stdout).parseAsync([
+        "node",
+        "zinkee",
+        "navigation",
+        "folders",
+        "get",
+        "Finance",
+      ]),
+    ).rejects.toThrowError('Folder "Finance" is ambiguous. Found 2 matches.');
+  });
+
+  it("shapes move payloads using the resource type and resolved folder id", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse([
+        {
+          id: "aaaabbbb-cccc-dddd-eeee-ffffffffffff",
+          name: "Finance",
+          order: 10,
+          resources: [
+            {
+              id: "resource-1",
+              name: "Invoices",
+              type: "DISPLAY",
+              isInSpace: false,
+            },
+          ],
+        },
+      ]),
+    );
+    fetchMock.mockResolvedValueOnce(jsonResponse({ resourceId: "resource-1", targetFolderId: "aaaabbbb-cccc-dddd-eeee-ffffffffffff" }));
+    const program = buildProgram(configPath, output.stdout);
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "navigation",
+      "resources",
+      "move",
+      "resource-1",
+      "--type",
+      "display",
+      "--to",
+      "Finance",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/navigation/folders",
+    );
+
+    const moveInit = fetchMock.mock.calls[1]?.[1];
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/navigation/resources:move",
+    );
+    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

@@ -0,0 +1,348 @@
+import { readFileSync } from "node:fs";
+import type { Writable } from "node:stream";
+
+import { Command, InvalidArgumentError } from "commander";
+
+import { NavigationApi, type NavigationFolder } from "../api/navigation.js";
+import { ApiClient } from "../client.js";
+import { defaultConfigPath, readConfig } from "../config.js";
+import { normalizeUuidOrSlug, type NormalizedUuidOrSlug } from "../parsers/selectors.js";
+import { resolveRuntimeContext } from "../runtime-context.js";
+import type { 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 RegisterNavigationCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions extends RuntimeOverrides {}
+
+interface FolderMutationOptions {
+  name?: string;
+  order?: string;
+  props?: string;
+  propsFile?: 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,
+): void {
+  writeLine(stdout, JSON.stringify(buildJsonSuccess(data, { command: commandName, configPath })));
+}
+
+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 createNavigationApi(
+  command: Command,
+  filePath: string,
+): { api: NavigationApi; json: boolean; 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.`);
+    }
+
+    return {
+      api: new NavigationApi(
+        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, mode: "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: mode, 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 parseInteger(value: string | undefined, flagName: string): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new CliError("invalid_cli_usage", `${flagName} must be an integer.`);
+  }
+
+  return parsed;
+}
+
+function readJsonObject(raw?: string, rawFile?: string): Record<string, unknown> {
+  if (raw && rawFile) {
+    throw new CliError("invalid_cli_usage", 'Use either "--props" or "--props-file", not both.');
+  }
+
+  const source = rawFile ? readFileSync(rawFile, "utf8") : raw;
+  if (!source) {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(source) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new CliError("invalid_cli_usage", "Props payload must be a JSON object.");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+    throw new CliError("invalid_cli_usage", "Props payload is invalid JSON.");
+  }
+}
+
+function buildFolderBody(options: FolderMutationOptions): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+
+  if (options.name !== undefined) {
+    body.name = options.name;
+  }
+
+  const order = parseInteger(options.order, "--order");
+  if (order !== undefined) {
+    body.order = order;
+  }
+
+  const props = readJsonObject(options.props, options.propsFile);
+  if (Object.keys(props).length > 0) {
+    body.additionalProperties = props;
+  }
+
+  return body;
+}
+
+function resolveFolder(
+  folders: readonly NavigationFolder[],
+  selector: NormalizedUuidOrSlug,
+): NavigationFolder {
+  if (selector.kind === "uuid") {
+    const match = folders.find((folder) => folder.id === selector.value);
+    if (!match) {
+      throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
+    }
+    return match;
+  }
+
+  const matches = folders.filter((folder) => folder.name === selector.value);
+  if (matches.length === 1) {
+    return matches[0] as NavigationFolder;
+  }
+
+  if (matches.length > 1) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Folder "${selector.value}" is ambiguous. Found ${matches.length} matches.`,
+    );
+  }
+
+  throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
+}
+
+function folderRows(folders: readonly NavigationFolder[]): Record<string, unknown>[] {
+  return folders.map((folder) => ({
+    id: folder.id,
+    order: folder.order ?? "",
+    name: folder.name ?? "",
+    resourceCount: Array.isArray(folder.resources) ? folder.resources.length : "",
+  }));
+}
+
+export function registerNavigationCommands(
+  program: Command,
+  options: RegisterNavigationCommandsOptions = {},
+): void {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const navigation = program.command("navigation").description("Manage workspace navigation");
+  const folders = navigation.command("folders").description("Manage navigation folders");
+
+  folders
+    .command("list")
+    .description("List navigation folders")
+    .action(async function action(this: Command) {
+      const { api, json } = createNavigationApi(this, filePath);
+      const data = await api.listFolders();
+
+      if (json) {
+        emitJson(stdout, "navigation folders list", data, filePath);
+        return;
+      }
+
+      printTable(folderRows(data), ["id", "order", "name", "resourceCount"], stdout);
+    });
+
+  folders
+    .command("get")
+    .description("Get a navigation folder by UUID or exact name")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, folder: NormalizedUuidOrSlug) {
+      const { api, json } = createNavigationApi(this, filePath);
+      const data = await api.listFolders();
+      const resolved = resolveFolder(data, folder);
+
+      if (json) {
+        emitJson(stdout, "navigation folders get", resolved, filePath);
+        return;
+      }
+
+      printTable(folderRows([resolved]), ["id", "order", "name", "resourceCount"], stdout);
+    });
+
+  folders
+    .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")
+    .action(async function action(this: Command, commandOptions: FolderMutationOptions) {
+      const { api, json, readOnly } = createNavigationApi(this, filePath);
+      ensureWritable("navigation folders create", readOnly, "write");
+      const data = await api.createFolder(buildFolderBody(commandOptions));
+
+      if (json) {
+        emitJson(stdout, "navigation folders create", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Created navigation folder "${String(data.name ?? commandOptions.name)}".`);
+    });
+
+  folders
+    .command("update")
+    .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")
+    .action(async function action(this: Command, folder: NormalizedUuidOrSlug, commandOptions: FolderMutationOptions) {
+      const { api, json, readOnly } = createNavigationApi(this, filePath);
+      ensureWritable("navigation folders update", readOnly, "write");
+      const allFolders = await api.listFolders();
+      const resolved = resolveFolder(allFolders, folder);
+      const body = buildFolderBody(commandOptions);
+
+      if (Object.keys(body).length === 0) {
+        throw new CliError("invalid_cli_usage", "Nothing to update.");
+      }
+
+      const data = await api.updateFolder({ kind: "uuid", value: resolved.id }, body);
+
+      if (json) {
+        emitJson(stdout, "navigation folders update", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Updated navigation folder "${String(data.name ?? resolved.name ?? resolved.id)}".`);
+    });
+
+  folders
+    .command("delete")
+    .description("Delete a navigation folder")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, folder: NormalizedUuidOrSlug) {
+      const { api, json, readOnly } = createNavigationApi(this, filePath);
+      ensureWritable("navigation folders delete", readOnly, "destructive");
+      const allFolders = await api.listFolders();
+      const resolved = resolveFolder(allFolders, folder);
+      const data = await api.deleteFolder({ kind: "uuid", value: resolved.id });
+
+      if (json) {
+        emitJson(stdout, "navigation folders delete", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Deleted navigation folder "${resolved.name ?? resolved.id}".`);
+    });
+
+  navigation
+    .command("resources")
+    .description("Manage navigation resources")
+    .command("move")
+    .description("Move a resource into a folder")
+    .argument("<resource>", "resource UUID")
+    .requiredOption("--type <type>", "resource type")
+    .requiredOption("--to <folder>", "target folder UUID or exact name")
+    .action(async function action(
+      this: Command,
+      resourceId: string,
+      commandOptions: { type: string; to: string },
+    ) {
+      const { api, json, readOnly } = createNavigationApi(this, filePath);
+      ensureWritable("navigation resources move", readOnly, "write");
+      const allFolders = await api.listFolders();
+      const resolved = resolveFolder(allFolders, parseUuidOrSlugSelector(commandOptions.to));
+      const data = await api.moveResource({
+        resourceId,
+        resourceType: commandOptions.type.toUpperCase(),
+        targetFolderId: resolved.id,
+      });
+
+      if (json) {
+        emitJson(stdout, "navigation resources move", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Moved resource "${resourceId}" to "${resolved.name ?? resolved.id}".`);
+    });
+}

package/src/commands/profiles.test.ts

@@ -0,0 +1,82 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { buildProgram } from "../index.js";
+
+function createTempConfig(contents: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "zinkee-profiles-"));
+  const filePath = join(dir, "config.toml");
+  writeFileSync(filePath, contents, "utf8");
+  return filePath;
+}
+
+function createStdoutBuffer() {
+  let output = "";
+
+  return {
+    stdout: {
+      write(chunk: string) {
+        output += chunk;
+        return true;
+      },
+    },
+    read() {
+      return output;
+    },
+  };
+}
+
+describe("profiles commands", () => {
+  it("registers the profiles command group", () => {
+    const program = buildProgram();
+
+    expect(program.commands.some((command) => command.name() === "profiles")).toBe(true);
+  });
+
+  it("redacts secrets when showing a profile", async () => {
+    const configPath = createTempConfig(`
+default_profile = "prod"
+
+[profiles.prod]
+api_key = "secret-token-1234"
+base_url = "https://api.zinkee.test"
+`);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync(["node", "zinkee", "profiles", "get", "prod"]);
+
+    expect(output.read()).toContain("apiKey");
+    expect(output.read()).toContain("********1234");
+    expect(output.read()).not.toContain("secret-token-1234");
+  });
+
+  it("adds a profile and writes a TOML config file", async () => {
+    const configPath = join(mkdtempSync(join(tmpdir(), "zinkee-profiles-add-")), "config.toml");
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "profiles",
+      "add",
+      "local",
+      "--api-key",
+      "new-token-5678",
+      "--base-url",
+      "http://localhost:8088",
+    ]);
+
+    const saved = readFileSync(configPath, "utf8");
+
+    expect(output.read()).toContain('Added profile "local".');
+    expect(saved).toContain('[profiles.local]');
+    expect(saved).toContain('api_key = "new-token-5678"');
+    expect(saved).toContain('base_url = "http://localhost:8088"');
+    expect(saved).toContain('default_profile = "local"');
+  });
+});