zinkee 0.1.15 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.15",
+  "version": "0.1.18",
   "description": "CLI for Zinkee API v2",
   "type": "module",
   "bin": {

package/src/cli-examples.ts

@@ -18,11 +18,6 @@ export interface ExampleRequest {
   filters: {
     type?: string;
   };
-  overrides: {
-    profile?: string;
-    baseUrl?: string;
-    apiKey?: string;
-  };
   json: boolean;
 }
 
@@ -48,46 +43,6 @@ function extractExampleFilters(tokens: readonly string[]): { type?: string } {
   return filters;
 }
 
-function extractExampleOverrides(tokens: readonly string[]): {
-  profile?: string;
-  baseUrl?: string;
-  apiKey?: string;
-} {
-  const overrides: {
-    profile?: string;
-    baseUrl?: string;
-    apiKey?: string;
-  } = {};
-
-  for (let index = 0; index < tokens.length; index += 1) {
-    const token = tokens[index];
-    const value = tokens[index + 1];
-
-    if (!value || value.startsWith("-")) {
-      continue;
-    }
-
-    if (token === "--profile") {
-      overrides.profile = value;
-      index += 1;
-      continue;
-    }
-
-    if (token === "--base-url") {
-      overrides.baseUrl = value;
-      index += 1;
-      continue;
-    }
-
-    if (token === "--api-key") {
-      overrides.apiKey = value;
-      index += 1;
-    }
-  }
-
-  return overrides;
-}
-
 export function extractExampleRequest(
   argv: readonly string[],
   optionMeta: OptionMetadata = createDefaultOptionMetadata(),
@@ -109,27 +64,17 @@ export function extractExampleRequest(
   return {
     commandName: cmdPath.commandName,
     filters: extractExampleFilters(remainingTokens),
-    overrides: extractExampleOverrides(argv),
     json: argv.includes("--json"),
   };
 }
 
-export async function showExamples(
+export function showExamples(
   commandName: string,
   json: boolean,
   stdout?: CommandIo,
   filters: { type?: string } = {},
-  options: {
-    enabled?: boolean;
-    configPath?: string;
-    overrides?: {
-      profile?: string;
-      baseUrl?: string;
-      apiKey?: string;
-    };
-  } = {},
-): Promise<void> {
-  const examples = await getResolvedCommandExamples(commandName, filters, options);
+): void {
+  const examples = getResolvedCommandExamples(commandName, filters);
 
   if (examples.length === 0) {
     throw new CliError("invalid_cli_usage", `No examples registered for "${commandName}".`);

package/src/cli-runner.ts

@@ -65,15 +65,11 @@ export async function runCli(argv: string[]): Promise<void> {
     const exampleRequest = extractExampleRequest(argv, optionMeta);
 
     if (exampleRequest) {
-      await showExamples(
+      showExamples(
         exampleRequest.commandName,
         exampleRequest.json,
         undefined,
         exampleRequest.filters,
-        {
-          enabled: true,
-          overrides: exampleRequest.overrides,
-        },
       );
       throw new ExampleDisplayed();
     }

package/src/client.test.ts

@@ -113,6 +113,67 @@ describe("ApiClient", () => {
     }
   });
 
+  it("surfaces the underlying network cause in the error message", async () => {
+    const dnsCause = Object.assign(new Error("getaddrinfo ENOTFOUND api-z2.zinkee.invalid"), {
+      code: "ENOTFOUND",
+    });
+    const fetchError = Object.assign(new TypeError("fetch failed"), { cause: dnsCause });
+    const fetchMock = vi.fn(async () => {
+      throw fetchError;
+    });
+
+    const client = new ApiClient({
+      baseUrl: "https://api-z2.zinkee.invalid",
+      fetch: fetchMock,
+    });
+
+    await expect(client.getJson("/api/v2/schemas")).rejects.toMatchObject({
+      name: "ApiClientError",
+      code: "network_error",
+      message:
+        "Request failed for GET https://api-z2.zinkee.invalid/api/v2/schemas: getaddrinfo ENOTFOUND api-z2.zinkee.invalid.",
+      cause: fetchError,
+    });
+  });
+
+  it("appends the cause code when it is not already part of the message", async () => {
+    const tlsCause = Object.assign(new Error("self signed certificate"), {
+      code: "DEPTH_ZERO_SELF_SIGNED_CERT",
+    });
+    const fetchError = Object.assign(new TypeError("fetch failed"), { cause: tlsCause });
+    const fetchMock = vi.fn(async () => {
+      throw fetchError;
+    });
+
+    const client = new ApiClient({
+      baseUrl: "https://self-signed.example.com",
+      fetch: fetchMock,
+    });
+
+    await expect(client.getJson("/api/v2/schemas")).rejects.toMatchObject({
+      code: "network_error",
+      message:
+        "Request failed for GET https://self-signed.example.com/api/v2/schemas: self signed certificate (DEPTH_ZERO_SELF_SIGNED_CERT).",
+    });
+  });
+
+  it("falls back to the bare message when the network cause has no useful detail", async () => {
+    const fetchMock = vi.fn(async () => {
+      throw new TypeError("fetch failed");
+    });
+
+    const client = new ApiClient({
+      baseUrl: "https://api.example.com",
+      fetch: fetchMock,
+    });
+
+    await expect(client.getJson("/api/v2/schemas")).rejects.toMatchObject({
+      name: "ApiClientError",
+      code: "network_error",
+      message: "Request failed for GET https://api.example.com/api/v2/schemas.",
+    });
+  });
+
   it("returns binary responses as ArrayBuffers", async () => {
     const fetchMock = vi.fn(async () => binaryResponse([1, 2, 3]));
 

package/src/client.ts

@@ -110,6 +110,27 @@ function parseErrorBody(text: string, contentType: string | null): unknown {
   }
 }
 
+function summarizeNetworkCause(cause: unknown): string | undefined {
+  const seen = new Set<unknown>();
+  let current: unknown = cause;
+
+  while (current && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+
+    const candidate = current as { message?: unknown; code?: unknown; cause?: unknown };
+    const message = typeof candidate.message === "string" ? candidate.message.trim() : "";
+    const code = typeof candidate.code === "string" ? candidate.code : undefined;
+
+    if (message && message !== "fetch failed") {
+      return code && !message.includes(code) ? `${message} (${code})` : message;
+    }
+
+    current = candidate.cause;
+  }
+
+  return undefined;
+}
+
 export class ApiClient {
   private readonly fetchImpl: typeof fetch;
 
@@ -206,7 +227,12 @@ export class ApiClient {
         });
       }
 
-      throw new ApiClientError("network_error", `Request failed for ${method} ${url}.`, {
+      const causeSummary = summarizeNetworkCause(cause);
+      const message = causeSummary
+        ? `Request failed for ${method} ${url}: ${causeSummary}.`
+        : `Request failed for ${method} ${url}.`;
+
+      throw new ApiClientError("network_error", message, {
         url,
         method,
         cause,

package/src/commands/profiles.test.ts

@@ -79,4 +79,113 @@ base_url = "https://api.zinkee.test"
     expect(saved).toContain('base_url = "http://localhost:8088"');
     expect(saved).toContain('default_profile = "local"');
   });
+
+  it("rejects a malformed base URL when adding a profile", async () => {
+    const configPath = join(
+      mkdtempSync(join(tmpdir(), "zinkee-profiles-add-bad-url-")),
+      "config.toml",
+    );
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "profiles",
+        "add",
+        "broken",
+        "--api-key",
+        "any",
+        "--base-url",
+        "api-z2.zinkee.com",
+      ]),
+    ).rejects.toMatchObject({
+      name: "CliError",
+      code: "configuration_error",
+      message: '"--base-url" must be an absolute http(s) URL.',
+    });
+  });
+
+  it("rejects a non-http(s) base URL when adding a profile", async () => {
+    const configPath = join(
+      mkdtempSync(join(tmpdir(), "zinkee-profiles-add-ftp-")),
+      "config.toml",
+    );
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "profiles",
+        "add",
+        "broken",
+        "--api-key",
+        "any",
+        "--base-url",
+        "ftp://api-z2.zinkee.com",
+      ]),
+    ).rejects.toMatchObject({
+      name: "CliError",
+      code: "configuration_error",
+      message: '"--base-url" must be an absolute http(s) URL.',
+    });
+  });
+
+  it("normalizes trailing slashes when adding a profile", async () => {
+    const configPath = join(
+      mkdtempSync(join(tmpdir(), "zinkee-profiles-add-slash-")),
+      "config.toml",
+    );
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "profiles",
+      "add",
+      "local",
+      "--api-key",
+      "any",
+      "--base-url",
+      "https://api-z2.zinkee.com///",
+    ]);
+
+    const saved = readFileSync(configPath, "utf8");
+
+    expect(saved).toContain('base_url = "https://api-z2.zinkee.com"');
+  });
+
+  it("rejects a malformed base URL when updating a profile", async () => {
+    const configPath = createTempConfig(`
+[profiles.prod]
+api_key = "secret"
+base_url = "https://api-z2.zinkee.com"
+`);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "profiles",
+        "update",
+        "prod",
+        "--base-url",
+        "not a url",
+      ]),
+    ).rejects.toMatchObject({
+      name: "CliError",
+      code: "configuration_error",
+      message: '"--base-url" must be an absolute http(s) URL.',
+    });
+
+    const saved = readFileSync(configPath, "utf8");
+
+    expect(saved).toContain('base_url = "https://api-z2.zinkee.com"');
+  });
 });

package/src/commands/profiles.ts

@@ -4,11 +4,13 @@ import { Command } from "commander";
 
 import {
   defaultConfigPath,
+  ProfileResolutionError,
   readConfigIfExists,
   redactProfile,
   removeProfileConfig,
   setDefaultProfile,
   setProfileConfig,
+  validateBaseUrl,
   writeConfig,
 } from "../config.js";
 import type { AppConfig, ProfileConfig } from "../types.js";
@@ -93,6 +95,22 @@ function loadConfigForAdd(filePath: string): AppConfig {
   return readConfigIfExists(filePath) ?? { profiles: {} };
 }
 
+function normalizeProfileBaseUrl(baseUrl: string | undefined): string | undefined {
+  if (baseUrl === undefined) {
+    return undefined;
+  }
+
+  try {
+    return validateBaseUrl(baseUrl, '"--base-url"');
+  } catch (error) {
+    if (error instanceof ProfileResolutionError) {
+      throw new CliError("configuration_error", error.message);
+    }
+
+    throw error;
+  }
+}
+
 function emitProfilesTable(stdout: CommandIo, data: readonly DisplayProfile[]): void {
   printTable(
     data.map((profile) => ({
@@ -191,9 +209,11 @@ export function registerProfilesCommands(
         );
       }
 
+      const baseUrl = normalizeProfileBaseUrl(commandOptions.baseUrl);
+
       let nextConfig = setProfileConfig(config, profileName, {
         apiKey: commandOptions.apiKey,
-        baseUrl: commandOptions.baseUrl,
+        baseUrl,
       });
 
       if (!nextConfig.defaultProfile) {
@@ -236,9 +256,11 @@ export function registerProfilesCommands(
       const config = readRequiredConfig(filePath);
       getRequiredProfile(config, profileName);
 
+      const baseUrl = normalizeProfileBaseUrl(commandOptions.baseUrl);
+
       const nextConfig = setProfileConfig(config, profileName, {
         apiKey: commandOptions.apiKey,
-        baseUrl: commandOptions.baseUrl,
+        baseUrl,
       });
 
       writeConfig(nextConfig, filePath);

package/src/config.test.ts

@@ -256,6 +256,28 @@ describe("resolveRuntimeContext", () => {
       else process.env[ENV_BASE_URL] = previousBaseUrl;
     }
   });
+
+  it("rejects a --base-url override that is not an absolute http(s) URL", () => {
+    expect(() =>
+      resolveRuntimeContext({ profiles: {} }, { baseUrl: "api-z2.zinkee.com", apiKey: "k" }),
+    ).toThrowError('"--base-url" must be an absolute http(s) URL.');
+
+    expect(() =>
+      resolveRuntimeContext(
+        { profiles: {} },
+        { baseUrl: "ftp://api-z2.zinkee.com", apiKey: "k" },
+      ),
+    ).toThrowError('"--base-url" must be an absolute http(s) URL.');
+  });
+
+  it("normalizes trailing slashes on a --base-url override", () => {
+    expect(
+      resolveRuntimeContext(
+        { profiles: {} },
+        { baseUrl: "https://api-z2.zinkee.com///", apiKey: "k" },
+      ).baseUrl,
+    ).toBe("https://api-z2.zinkee.com");
+  });
 });
 
 describe("env readers", () => {

package/src/config.ts

@@ -260,21 +260,17 @@ export function resolveProfile(
   throw new ProfileResolutionError("No profile could be resolved from config.");
 }
 
-export function validateBaseUrl(value: string): string {
+export function validateBaseUrl(value: string, source: string = "Base URL"): string {
   let parsed: URL;
 
   try {
     parsed = new URL(value);
   } catch {
-    throw new ProfileResolutionError(
-      `Environment variable ${ENV_BASE_URL} must be an absolute http(s) URL.`,
-    );
+    throw new ProfileResolutionError(`${source} must be an absolute http(s) URL.`);
   }
 
   if (!["http:", "https:"].includes(parsed.protocol) || !parsed.host) {
-    throw new ProfileResolutionError(
-      `Environment variable ${ENV_BASE_URL} must be an absolute http(s) URL.`,
-    );
+    throw new ProfileResolutionError(`${source} must be an absolute http(s) URL.`);
   }
 
   return value.replace(/\/+$/, "");
@@ -290,7 +286,7 @@ export function readEnvBaseUrl(env: NodeJS.ProcessEnv = process.env): string | u
     return undefined;
   }
 
-  return validateBaseUrl(baseUrl);
+  return validateBaseUrl(baseUrl, `Environment variable ${ENV_BASE_URL}`);
 }
 
 export function readEnvProfile(env: NodeJS.ProcessEnv = process.env): string | undefined {

package/src/index.test.ts

@@ -37,7 +37,6 @@ describe("project bootstrap", () => {
     ).toEqual({
       commandName: "records query",
       filters: {},
-      overrides: {},
       json: true,
     });
   });
@@ -62,9 +61,6 @@ describe("project bootstrap", () => {
       filters: {
         type: "option",
       },
-      overrides: {
-        profile: "local",
-      },
       json: false,
     });
   });
@@ -75,7 +71,6 @@ describe("project bootstrap", () => {
     ).toEqual({
       commandName: "schemas list",
       filters: {},
-      overrides: {},
       json: false,
     });
   });
@@ -96,12 +91,11 @@ describe("project bootstrap", () => {
     ).toEqual({
       commandName: "schemas fields create",
       filters: { type: "option" },
-      overrides: {},
       json: false,
     });
   });
 
-  it("extracts example overrides regardless of --example position", () => {
+  it("extracts example requests regardless of --example position", () => {
     expect(
       extractExampleRequest([
         "node",
@@ -116,7 +110,6 @@ describe("project bootstrap", () => {
     ).toEqual({
       commandName: "schemas list",
       filters: {},
-      overrides: { profile: "staging" },
       json: true,
     });
   });

package/src/runtime-context.ts

@@ -9,6 +9,7 @@ import {
   readEnvProfile,
   resolveProfile,
   ProfileResolutionError,
+  validateBaseUrl,
 } from "./config.js";
 
 export function resolveRuntimeContext(
@@ -19,9 +20,14 @@ export function resolveRuntimeContext(
   const envApiKey = readEnvApiKey();
   const envBaseUrl = readEnvBaseUrl();
 
+  const flagBaseUrl =
+    overrides.baseUrl !== undefined
+      ? validateBaseUrl(overrides.baseUrl, '"--base-url"')
+      : undefined;
+
   const profileOverride = overrides.profile ?? envProfile;
   const apiKeyOverride = overrides.apiKey ?? envApiKey;
-  const baseUrlOverride = overrides.baseUrl ?? envBaseUrl;
+  const baseUrlOverride = flagBaseUrl ?? envBaseUrl;
 
   if (apiKeyOverride && !baseUrlOverride) {
     throw new ProfileResolutionError(

package/src/utils/errors.test.ts

@@ -28,7 +28,7 @@ describe("formatCliErrorJson", () => {
 
     expect(JSON.parse(formatCliErrorJson(error, { exitCode: 1 }))).toEqual({
       error: {
-        code: "unknown_error",
+        code: "http_error",
         message: "Schema is locked.",
         exitCode: 1,
         details: {
@@ -45,4 +45,41 @@ describe("formatCliErrorJson", () => {
       },
     });
   });
+
+  it("preserves network_error code for transport-layer failures", () => {
+    const error = new ApiClientError(
+      "network_error",
+      "Request failed for GET https://api.example.com/api/v2/schemas: getaddrinfo ENOTFOUND api.example.com.",
+      {
+        url: "https://api.example.com/api/v2/schemas",
+        method: "GET",
+        cause: new Error("getaddrinfo ENOTFOUND api.example.com"),
+      },
+    );
+
+    expect(JSON.parse(formatCliErrorJson(error)).error.code).toBe("network_error");
+  });
+
+  it("preserves timeout code for aborted requests", () => {
+    const error = new ApiClientError("timeout", "Request timed out after 10ms.", {
+      url: "https://api.example.com/api/v2/schemas",
+      method: "GET",
+    });
+
+    expect(JSON.parse(formatCliErrorJson(error)).error.code).toBe("timeout");
+  });
+
+  it("preserves invalid_json code for unparseable responses", () => {
+    const error = new ApiClientError(
+      "invalid_json",
+      "Failed to parse JSON response from GET https://api.example.com/api/v2/schemas.",
+      {
+        url: "https://api.example.com/api/v2/schemas",
+        method: "GET",
+        responseText: "<html>oops</html>",
+      },
+    );
+
+    expect(JSON.parse(formatCliErrorJson(error)).error.code).toBe("invalid_json");
+  });
 });

package/src/utils/errors.ts

@@ -7,13 +7,21 @@ export type CliErrorCode =
   | "unknown_error"
   | "invalid_cli_usage"
   | "configuration_error"
-  | "command_not_allowed_in_read_only_mode";
+  | "command_not_allowed_in_read_only_mode"
+  | "network_error"
+  | "http_error"
+  | "timeout"
+  | "invalid_json";
 
 export const cliExitCodeByErrorCode = {
   unknown_error: 1,
   invalid_cli_usage: 2,
   configuration_error: 2,
   command_not_allowed_in_read_only_mode: 7,
+  network_error: 1,
+  http_error: 1,
+  timeout: 1,
+  invalid_json: 1,
 } as const satisfies Record<CliErrorCode, number>;
 
 export interface CliErrorDetails {
@@ -144,7 +152,7 @@ export function toCliError(error: unknown): CliError {
   if (error instanceof ApiClientError) {
     const apiError = extractApiErrorDetails(error);
 
-    return new CliError("unknown_error", apiError.message, apiError.details);
+    return new CliError(error.code, apiError.message, apiError.details);
   }
 
   if (error instanceof Error) {

package/src/utils/examples.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
-import { getCommandExamples } from "./examples.js";
+import { commandRegistry } from "../command-registry.js";
+import { getCommandExamples, getResolvedCommandExamples } from "./examples.js";
 
 describe("getCommandExamples", () => {
   it("returns registered examples for complex commands", () => {
@@ -250,4 +251,24 @@ describe("getCommandExamples", () => {
     expect(getCommandExamples("config show")[0]?.response).toContain('"defaultProfile": "prod"');
     expect(getCommandExamples("config validate")[0]?.response).toContain('"valid": true');
   });
+
+  it.each(Object.keys(commandRegistry))(
+    "returns at least one example for %s",
+    (commandName) => {
+      const examples = getCommandExamples(commandName);
+      expect(examples.length, `${commandName} has no examples`).toBeGreaterThan(0);
+      for (const example of examples) {
+        expect(example.command, `${commandName} example missing command`).toBeTruthy();
+        expect(example.description, `${commandName} example missing description`).toBeTruthy();
+      }
+    },
+  );
+
+  it("getResolvedCommandExamples is synchronous and matches getCommandExamples", () => {
+    for (const commandName of Object.keys(commandRegistry)) {
+      const resolved = getResolvedCommandExamples(commandName);
+      expect(resolved, `${commandName} resolved must not be a thenable`).not.toHaveProperty("then");
+      expect(resolved).toEqual(getCommandExamples(commandName));
+    }
+  });
 });