zinkee 0.1.0

package/src/commands/teamspace.ts

@@ -0,0 +1,540 @@
+import { readFileSync } from "node:fs";
+import type { Writable } from "node:stream";
+
+import { Command, InvalidArgumentError } from "commander";
+
+import {
+  TeamspaceApi,
+  type ApiTeamspaceFolder,
+  type CreateTeamspaceFolderInput,
+  type UpdateTeamspaceFolderInput,
+} from "../api/teamspace.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 { 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 RegisterTeamspaceCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions extends RuntimeOverrides {}
+
+interface FolderListCommandOptions {
+  includeResources?: boolean;
+}
+
+interface FolderCreateCommandOptions {
+  name?: string;
+  order?: number;
+  props?: string;
+  propsFile?: string;
+}
+
+interface FolderUpdateCommandOptions extends FolderCreateCommandOptions {}
+
+interface ResourcePublishCommandOptions {
+  to: NormalizedUuidOrSlug;
+}
+
+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 createTeamspaceApi(
+  command: Command,
+  filePath: string,
+): { api: TeamspaceApi; 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 TeamspaceApi(
+        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 parseNonNegativeInteger(input: string): number {
+  if (!/^\d+$/.test(input.trim())) {
+    throw new InvalidArgumentError(`Expected a non-negative integer, received "${input}".`);
+  }
+
+  return Number(input);
+}
+
+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 | undefined {
+  if (raw && rawFile) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Provide either "--props" or "--props-file", not both.',
+    );
+  }
+
+  if (raw) {
+    return parseRawJsonObject(raw, "--props");
+  }
+
+  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 props payload from ${rawFile}: ${message}`,
+      );
+    }
+
+    return parseRawJsonObject(contents, `--props-file ${rawFile}`);
+  }
+
+  return undefined;
+}
+
+function isEmptyObject(value: object): boolean {
+  return Object.keys(value).length === 0;
+}
+
+function buildFolderCreateInput(
+  options: FolderCreateCommandOptions,
+): CreateTeamspaceFolderInput {
+  if (options.name === undefined) {
+    throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+  }
+
+  const input: CreateTeamspaceFolderInput = {
+    name: options.name,
+  };
+
+  if (options.order !== undefined) {
+    input.order = options.order;
+  }
+
+  const props = readRawObject(options.props, options.propsFile);
+
+  if (props !== undefined) {
+    input.additionalProperties = props;
+  }
+
+  return input;
+}
+
+function buildFolderUpdateInput(
+  options: FolderUpdateCommandOptions,
+): UpdateTeamspaceFolderInput {
+  const input: UpdateTeamspaceFolderInput = {};
+
+  if (options.name !== undefined) {
+    input.name = options.name;
+  }
+
+  if (options.order !== undefined) {
+    input.order = options.order;
+  }
+
+  const props = readRawObject(options.props, options.propsFile);
+
+  if (props !== undefined) {
+    input.additionalProperties = props;
+  }
+
+  if (isEmptyObject(input)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Provide folder updates via "--name", "--order", "--props", or "--props-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 getFolderIdentifier(folder: ApiTeamspaceFolder): string {
+  return typeof folder.id === "string"
+    ? folder.id
+    : typeof folder.name === "string"
+      ? folder.name
+      : "unknown";
+}
+
+function buildFolderLookup(
+  folders: readonly ApiTeamspaceFolder[],
+  selector: NormalizedUuidOrSlug,
+): NormalizedUuidOrSlug {
+  if (selector.kind === "uuid") {
+    return selector;
+  }
+
+  const matches = folders.filter((folder) => folder.name === selector.value);
+
+  if (matches.length === 1) {
+    const folderId = matches[0]?.id;
+
+    if (typeof folderId === "string" && folderId.length > 0) {
+      return {
+        kind: "uuid",
+        value: folderId,
+      };
+    }
+  }
+
+  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 findFolderEntity(
+  folders: readonly ApiTeamspaceFolder[],
+  selector: NormalizedUuidOrSlug,
+): ApiTeamspaceFolder {
+  if (selector.kind === "uuid") {
+    const match = folders.find((folder) => folder.id === selector.value);
+
+    if (match) {
+      return match;
+    }
+
+    throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
+  }
+
+  const matches = folders.filter((folder) => folder.name === selector.value);
+
+  if (matches.length === 1) {
+    return matches[0] as ApiTeamspaceFolder;
+  }
+
+  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.`);
+}
+
+async function resolveFolderSelector(
+  api: TeamspaceApi,
+  selector: NormalizedUuidOrSlug,
+): Promise<NormalizedUuidOrSlug> {
+  if (selector.kind === "uuid") {
+    return selector;
+  }
+
+  const folders = await api.listFolders(false);
+  return buildFolderLookup(folders, selector);
+}
+
+export function registerTeamspaceCommands(
+  program: Command,
+  options: RegisterTeamspaceCommandsOptions = {},
+): void {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const teamspace = program.command("teamspace").description("Manage teamspace folders and resources");
+
+  const folders = teamspace.command("folders").description("Manage teamspace folders");
+
+  folders
+    .command("list")
+    .description("List teamspace folders")
+    .option("--include-resources", "include nested resources")
+    .action(async function action(this: Command, commandOptions: FolderListCommandOptions) {
+      const { api, json } = createTeamspaceApi(this, filePath);
+      const data = await api.listFolders(Boolean(commandOptions.includeResources));
+
+      if (json) {
+        emitJson(stdout, "teamspace folders list", data, filePath);
+        return;
+      }
+
+      emitTable(stdout, data);
+    });
+
+  folders
+    .command("get")
+    .description("Get a teamspace folder by exact name or UUID")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .option("--include-resources", "include nested resources")
+    .action(async function action(
+      this: Command,
+      folder: NormalizedUuidOrSlug,
+      commandOptions: FolderListCommandOptions,
+    ) {
+      const { api, json } = createTeamspaceApi(this, filePath);
+      const resolvedFolder = await resolveFolderSelector(api, folder);
+      const allFolders = await api.listFolders(Boolean(commandOptions.includeResources));
+      const data = findFolderEntity(allFolders, resolvedFolder);
+
+      if (json) {
+        emitJson(stdout, "teamspace folders get", data, filePath);
+        return;
+      }
+
+      emitTable(stdout, data);
+    });
+
+  folders
+    .command("create")
+    .description("Create a teamspace folder")
+    .requiredOption("--name <name>", "folder name")
+    .option("--order <n>", "folder order", parseNonNegativeInteger)
+    .option("--props <json>", "folder properties payload")
+    .option("--props-file <path>", "path to a folder properties JSON payload")
+    .action(async function action(
+      this: Command,
+      commandOptions: FolderCreateCommandOptions,
+    ) {
+      const { api, json, readOnly } = createTeamspaceApi(this, filePath);
+      ensureWritable("teamspace folders create", readOnly, "write");
+
+      const data = await api.createFolder(buildFolderCreateInput(commandOptions));
+
+      if (json) {
+        emitJson(stdout, "teamspace folders create", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Created folder "${getFolderIdentifier(data)}".`);
+    });
+
+  folders
+    .command("update")
+    .description("Update a teamspace folder")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .option("--name <name>", "folder name")
+    .option("--order <n>", "folder order", parseNonNegativeInteger)
+    .option("--props <json>", "folder properties payload")
+    .option("--props-file <path>", "path to a folder properties JSON payload")
+    .action(async function action(
+      this: Command,
+      folder: NormalizedUuidOrSlug,
+      commandOptions: FolderUpdateCommandOptions,
+    ) {
+      const { api, json, readOnly } = createTeamspaceApi(this, filePath);
+      ensureWritable("teamspace folders update", readOnly, "write");
+
+      const resolvedFolder = await resolveFolderSelector(api, folder);
+      const data = await api.updateFolder(resolvedFolder, buildFolderUpdateInput(commandOptions));
+
+      if (json) {
+        emitJson(stdout, "teamspace folders update", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Updated folder "${getFolderIdentifier(data)}".`);
+    });
+
+  folders
+    .command("delete")
+    .description("Delete a teamspace folder")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, folder: NormalizedUuidOrSlug) {
+      const { api, json, readOnly } = createTeamspaceApi(this, filePath);
+      ensureWritable("teamspace folders delete", readOnly, "destructive");
+
+      const resolvedFolder = await resolveFolderSelector(api, folder);
+      const data = await api.deleteFolder(resolvedFolder);
+
+      if (json) {
+        emitJson(stdout, "teamspace folders delete", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Deleted folder "${resolvedFolder.value}".`);
+    });
+
+  const resources = teamspace.command("resources").description("Manage teamspace resources");
+
+  resources
+    .command("publish")
+    .description("Publish a resource to a teamspace folder")
+    .argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector)
+    .requiredOption("--to <folder>", "target folder", parseUuidOrSlugSelector)
+    .action(async function action(
+      this: Command,
+      resource: NormalizedUuidOrSlug,
+      commandOptions: ResourcePublishCommandOptions,
+    ) {
+      const { api, json, readOnly } = createTeamspaceApi(this, filePath);
+      ensureWritable("teamspace resources publish", readOnly, "write");
+
+      const folder = await resolveFolderSelector(api, commandOptions.to);
+      const data = await api.publishResource({
+        resourceId: resource.value,
+        targetFolderId: folder.value,
+      });
+
+      if (json) {
+        emitJson(stdout, "teamspace resources publish", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Published resource "${resource.value}" to folder "${folder.value}".`);
+    });
+
+  resources
+    .command("unpublish")
+    .description("Unpublish a resource from teamspace")
+    .argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, resource: NormalizedUuidOrSlug) {
+      const { api, json, readOnly } = createTeamspaceApi(this, filePath);
+      ensureWritable("teamspace resources unpublish", readOnly, "write");
+
+      const data = await api.unpublishResource(resource.value);
+
+      if (json) {
+        emitJson(stdout, "teamspace resources unpublish", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Unpublished resource "${resource.value}".`);
+    });
+}

package/src/config.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  parseConfig,
+  redactConfig,
+  redactSecret,
+  removeProfileConfig,
+  resolveProfile,
+  serializeConfig,
+  setDefaultProfile,
+  setProfileConfig,
+} from "./config.js";
+import { resolveRuntimeContext } from "./runtime-context.js";
+
+describe("parseConfig", () => {
+  it("reads the legacy config shape without migration", () => {
+    const config = parseConfig(`
+default_profile = "prod"
+
+[profiles.prod]
+api_key = "token"
+base_url = "https://api.zinkee.com"
+retry_count = 3
+`);
+
+    expect(config.defaultProfile).toBe("prod");
+    expect(config.profiles.prod?.apiKey).toBe("token");
+    expect(config.profiles.prod?.baseUrl).toBe("https://api.zinkee.com");
+    expect(config.profiles.prod?.retry_count).toBe(3);
+  });
+});
+
+describe("resolveProfile", () => {
+  it("prefers explicit profile over default_profile", () => {
+    const config = {
+      defaultProfile: "prod",
+      profiles: {
+        prod: { apiKey: "a" },
+        local: { apiKey: "b", baseUrl: "http://localhost:8088" },
+      },
+    };
+
+    expect(resolveProfile(config, { profile: "local" }).name).toBe("local");
+  });
+
+  it("throws a clear error when the explicit profile is missing", () => {
+    const config = {
+      defaultProfile: "prod",
+      profiles: {
+        prod: { apiKey: "a" },
+      },
+    };
+
+    expect(() => resolveProfile(config, { profile: "local" })).toThrowError(
+      'Profile "local" not found in config.',
+    );
+  });
+
+  it("throws a clear error when no effective profile exists", () => {
+    const config = {
+      profiles: {},
+    };
+
+    expect(() => resolveProfile(config)).toThrowError("No profile could be resolved from config.");
+  });
+});
+
+describe("resolveRuntimeContext", () => {
+  it("applies profile, baseUrl, apiKey, readOnly, and json overrides cleanly", () => {
+    const config = {
+      defaultProfile: "prod",
+      profiles: {
+        prod: { apiKey: "token", baseUrl: "https://api.zinkee.com" },
+        local: { apiKey: "local-token", baseUrl: "http://localhost:8088" },
+      },
+    };
+
+    expect(
+      resolveRuntimeContext(config, {
+        profile: "local",
+        baseUrl: "http://127.0.0.1:8088",
+        apiKey: "override-token",
+        readOnly: true,
+        json: false,
+      }),
+    ).toEqual({
+      profile: "local",
+      baseUrl: "http://127.0.0.1:8088",
+      apiKey: "override-token",
+      readOnly: true,
+      json: false,
+    });
+  });
+});
+
+describe("config mutation helpers", () => {
+  it("serializes updates back to the legacy TOML shape", () => {
+    const nextConfig = setDefaultProfile(
+      setProfileConfig(
+        {
+          profiles: {},
+        },
+        "local",
+        {
+          apiKey: "token",
+          baseUrl: "http://localhost:8088",
+        },
+      ),
+      "local",
+    );
+
+    expect(serializeConfig(nextConfig)).toContain('default_profile = "local"');
+    expect(serializeConfig(nextConfig)).toContain('[profiles.local]');
+    expect(serializeConfig(nextConfig)).toContain('api_key = "token"');
+    expect(serializeConfig(nextConfig)).toContain('base_url = "http://localhost:8088"');
+  });
+
+  it("removes a deleted default profile cleanly", () => {
+    const config = {
+      defaultProfile: "prod",
+      profiles: {
+        prod: { apiKey: "token" },
+        local: { apiKey: "other" },
+      },
+    };
+
+    expect(removeProfileConfig(config, "prod")).toEqual({
+      defaultProfile: undefined,
+      profiles: {
+        local: { apiKey: "other" },
+      },
+    });
+  });
+});
+
+describe("redaction helpers", () => {
+  it("redacts secrets while keeping the last four characters", () => {
+    expect(redactSecret("secret-token-1234")).toBe("********1234");
+    expect(redactSecret("abc")).toBe("********");
+  });
+
+  it("redacts config output without mutating other fields", () => {
+    expect(
+      redactConfig({
+        defaultProfile: "prod",
+        profiles: {
+          prod: {
+            apiKey: "secret-token-1234",
+            baseUrl: "https://api.zinkee.test",
+            retry_count: 3,
+          },
+        },
+      }),
+    ).toEqual({
+      defaultProfile: "prod",
+      profiles: {
+        prod: {
+          apiKey: "********1234",
+          baseUrl: "https://api.zinkee.test",
+          retry_count: 3,
+        },
+      },
+    });
+  });
+});