zinkee 0.1.1 → 0.1.4

package/package.json

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

package/src/commands/automations.ts

@@ -20,7 +20,7 @@ import {
   type UpdateAutomationInput,
 } from "../api/automations.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import { parseJsonAssignment, parseKeyValue } from "../parsers/kv.js";
 import {
   normalizeUuidOrSlug,
@@ -210,7 +210,7 @@ function createAutomationsApi(
   filePath: string,
 ): { api: AutomationsApi; json: boolean; readOnly: boolean } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/commands/comments.ts

@@ -8,7 +8,7 @@ import {
   type CreateCommentInput,
 } from "../api/comments.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import {
   normalizeUuidOrSlug,
   type NormalizedUuidOrSlug,
@@ -85,7 +85,7 @@ function createCommentsApi(
   filePath: string,
 ): { api: CommentsApi; json: boolean; readOnly: boolean } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/commands/displays.ts

@@ -5,7 +5,7 @@ import { Command, InvalidArgumentError } from "commander";
 
 import { DisplaysApi, type DisplayResource, type DisplaySummary } from "../api/displays.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import { normalizeUuidOrSlug, type NormalizedUuidOrSlug } from "../parsers/selectors.js";
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { RuntimeOverrides } from "../types.js";
@@ -148,7 +148,7 @@ function createDisplaysApi(
   filePath: string,
 ): { api: DisplaysApi; json: boolean; readOnly: boolean } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/commands/files.ts

@@ -6,7 +6,7 @@ import { Command, InvalidArgumentError } from "commander";
 
 import { FilesApi } from "../api/files.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.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";
@@ -83,7 +83,7 @@ function createFilesApi(
   filePath: string,
 ): { api: FilesApi; json: boolean; readOnly: boolean } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/commands/navigation.ts

@@ -5,7 +5,7 @@ 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 { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import { normalizeUuidOrSlug, type NormalizedUuidOrSlug } from "../parsers/selectors.js";
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { RuntimeOverrides } from "../types.js";
@@ -72,7 +72,7 @@ function createNavigationApi(
   filePath: string,
 ): { api: NavigationApi; json: boolean; readOnly: boolean } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/commands/records.ts

@@ -14,7 +14,7 @@ import {
 } from "../api/records.js";
 import { SchemasApi } from "../api/schemas.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import {
   type ParsedExpression,
   parseExpression,
@@ -128,7 +128,7 @@ function createRecordsApi(
   readOnly: boolean;
 } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/commands/schemas.ts

@@ -14,7 +14,7 @@ import {
 } from "../api/schemas.js";
 import { ApiClientError } from "../client.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import {
   normalizeUuidOrSlug,
   type NormalizedUuidOrSlug,
@@ -124,7 +124,7 @@ function createSchemasApi(
   filePath: string,
 ): { api: SchemasApi; json: boolean; profile: string; readOnly: boolean } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/commands/teamspace.ts

@@ -10,7 +10,7 @@ import {
   type UpdateTeamspaceFolderInput,
 } from "../api/teamspace.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import {
   normalizeUuidOrSlug,
   type NormalizedUuidOrSlug,
@@ -98,7 +98,7 @@ function createTeamspaceApi(
   filePath: string,
 ): { api: TeamspaceApi; json: boolean; readOnly: boolean } {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
 
     if (!runtime.baseUrl) {

package/src/config.test.ts

@@ -1,9 +1,17 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  DEFAULT_PRODUCTION_BASE_URL,
+  ENV_API_KEY,
+  ENV_BASE_URL,
+  ENV_PROFILE,
   parseConfig,
   redactConfig,
   redactSecret,
+  readRuntimeConfig,
+  readEnvApiKey,
+  readEnvBaseUrl,
+  readEnvProfile,
   removeProfileConfig,
   resolveProfile,
   serializeConfig,
@@ -30,6 +38,14 @@ retry_count = 3
   });
 });
 
+describe("readRuntimeConfig", () => {
+  it("returns an empty runtime config when the file does not exist", () => {
+    expect(readRuntimeConfig("/tmp/definitely-missing-zinkee-config.toml")).toEqual({
+      profiles: {},
+    });
+  });
+});
+
 describe("resolveProfile", () => {
   it("prefers explicit profile over default_profile", () => {
     const config = {
@@ -89,8 +105,167 @@ describe("resolveRuntimeContext", () => {
       apiKey: "override-token",
       readOnly: true,
       json: false,
+      profileSource: "flag",
+      baseUrlSource: "flag",
+      apiKeySource: "flag",
+    });
+  });
+
+  it("resolves runtime directly from env vars without config", () => {
+    const previousApiKey = process.env[ENV_API_KEY];
+    const previousBaseUrl = process.env[ENV_BASE_URL];
+    const previousProfile = process.env[ENV_PROFILE];
+    process.env[ENV_API_KEY] = "env-token";
+    process.env[ENV_BASE_URL] = "http://localhost:8088/";
+    delete process.env[ENV_PROFILE];
+
+    try {
+      expect(resolveRuntimeContext({ profiles: {} }, {})).toEqual({
+        profile: "runtime",
+        baseUrl: "http://localhost:8088",
+        apiKey: "env-token",
+        readOnly: false,
+        json: false,
+        profileSource: undefined,
+        baseUrlSource: "env",
+        apiKeySource: "env",
+      });
+    } finally {
+      if (previousApiKey === undefined) delete process.env[ENV_API_KEY];
+      else process.env[ENV_API_KEY] = previousApiKey;
+      if (previousBaseUrl === undefined) delete process.env[ENV_BASE_URL];
+      else process.env[ENV_BASE_URL] = previousBaseUrl;
+      if (previousProfile === undefined) delete process.env[ENV_PROFILE];
+      else process.env[ENV_PROFILE] = previousProfile;
+    }
+  });
+
+  it("prefers env vars over config values", () => {
+    const previousApiKey = process.env[ENV_API_KEY];
+    const previousBaseUrl = process.env[ENV_BASE_URL];
+    const previousProfile = process.env[ENV_PROFILE];
+    process.env[ENV_API_KEY] = "env-token";
+    process.env[ENV_BASE_URL] = "http://localhost:8088";
+    process.env[ENV_PROFILE] = "local";
+
+    try {
+      expect(
+        resolveRuntimeContext({
+          defaultProfile: "prod",
+          profiles: {
+            prod: { apiKey: "prod-token", baseUrl: "https://api.zinkee.com" },
+            local: { apiKey: "local-token", baseUrl: "http://127.0.0.1:9999" },
+          },
+        }, {}),
+      ).toEqual({
+        profile: "local",
+        baseUrl: "http://localhost:8088",
+        apiKey: "env-token",
+        readOnly: false,
+        json: false,
+        profileSource: "env",
+        baseUrlSource: "env",
+        apiKeySource: "env",
+      });
+    } finally {
+      if (previousApiKey === undefined) delete process.env[ENV_API_KEY];
+      else process.env[ENV_API_KEY] = previousApiKey;
+      if (previousBaseUrl === undefined) delete process.env[ENV_BASE_URL];
+      else process.env[ENV_BASE_URL] = previousBaseUrl;
+      if (previousProfile === undefined) delete process.env[ENV_PROFILE];
+      else process.env[ENV_PROFILE] = previousProfile;
+    }
+  });
+
+  it("falls back to the production base URL when the resolved profile has no base URL", () => {
+    expect(
+      resolveRuntimeContext({
+        defaultProfile: "prod",
+        profiles: {
+          prod: { apiKey: "prod-token" },
+        },
+      }, {}),
+    ).toEqual({
+      profile: "prod",
+      baseUrl: DEFAULT_PRODUCTION_BASE_URL,
+      apiKey: "prod-token",
+      readOnly: false,
+      json: false,
+      profileSource: "config",
+      baseUrlSource: "config",
+      apiKeySource: "config",
     });
   });
+
+  it("still prefers an explicit base URL override over the production fallback", () => {
+    expect(
+      resolveRuntimeContext({
+        defaultProfile: "prod",
+        profiles: {
+          prod: { apiKey: "prod-token" },
+        },
+      }, {
+        profile: "prod",
+        baseUrl: "http://localhost:8088",
+        apiKey: "override-token",
+      }),
+    ).toEqual({
+      profile: "prod",
+      baseUrl: "http://localhost:8088",
+      apiKey: "override-token",
+      readOnly: false,
+      json: false,
+      profileSource: "flag",
+      baseUrlSource: "flag",
+      apiKeySource: "flag",
+    });
+  });
+
+  it("throws a clear error when runtime api key is provided without base url", () => {
+    const previousApiKey = process.env[ENV_API_KEY];
+    const previousBaseUrl = process.env[ENV_BASE_URL];
+    process.env[ENV_API_KEY] = "env-token";
+    delete process.env[ENV_BASE_URL];
+
+    try {
+      expect(() => resolveRuntimeContext({ profiles: {} }, {})).toThrowError(
+        `Runtime API key was provided, but ${ENV_BASE_URL} or --base-url is missing.`,
+      );
+    } finally {
+      if (previousApiKey === undefined) delete process.env[ENV_API_KEY];
+      else process.env[ENV_API_KEY] = previousApiKey;
+      if (previousBaseUrl === undefined) delete process.env[ENV_BASE_URL];
+      else process.env[ENV_BASE_URL] = previousBaseUrl;
+    }
+  });
+
+  it("throws a clear error when runtime base url is provided without api key", () => {
+    const previousApiKey = process.env[ENV_API_KEY];
+    const previousBaseUrl = process.env[ENV_BASE_URL];
+    delete process.env[ENV_API_KEY];
+    process.env[ENV_BASE_URL] = "http://localhost:8088";
+
+    try {
+      expect(() => resolveRuntimeContext({ profiles: {} }, {})).toThrowError(
+        `Runtime base URL was provided, but ${ENV_API_KEY} or --api-key is missing.`,
+      );
+    } finally {
+      if (previousApiKey === undefined) delete process.env[ENV_API_KEY];
+      else process.env[ENV_API_KEY] = previousApiKey;
+      if (previousBaseUrl === undefined) delete process.env[ENV_BASE_URL];
+      else process.env[ENV_BASE_URL] = previousBaseUrl;
+    }
+  });
+});
+
+describe("env readers", () => {
+  it("normalizes env values", () => {
+    expect(readEnvApiKey({ [ENV_API_KEY]: " token " } as NodeJS.ProcessEnv)).toBe("token");
+    expect(readEnvProfile({ [ENV_PROFILE]: " local " } as NodeJS.ProcessEnv)).toBe("local");
+    expect(readEnvBaseUrl({ [ENV_BASE_URL]: " http://localhost:8088/ " } as NodeJS.ProcessEnv)).toBe(
+      "http://localhost:8088",
+    );
+  });
 });
 
 describe("config mutation helpers", () => {

package/src/config.ts

@@ -8,6 +8,10 @@ import type { AppConfig, ProfileConfig, RuntimeOverrides, ResolvedProfile } from
 
 export const defaultConfigPath = join(homedir(), ".config", "zinkee", "config.toml");
 export const redactedSecretMask = "********";
+export const ENV_API_KEY = "ZINKEE_API_KEY";
+export const ENV_BASE_URL = "ZINKEE_API_BASE_URL";
+export const ENV_PROFILE = "ZINKEE_PROFILE";
+export const DEFAULT_PRODUCTION_BASE_URL = "https://api-z2.zinkee.com";
 
 export class ProfileResolutionError extends Error {
   override name = "ProfileResolutionError";
@@ -25,6 +29,11 @@ function toStringValue(value: unknown): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
+function toNonEmptyString(value: string | undefined): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+
 function parseProfileConfig(value: unknown): ProfileConfig {
   const profile: ProfileConfig = {};
 
@@ -102,6 +111,10 @@ export function readConfigIfExists(filePath: string = defaultConfigPath): AppCon
   }
 }
 
+export function readRuntimeConfig(filePath: string = defaultConfigPath): AppConfig {
+  return readConfigIfExists(filePath) ?? { profiles: {} };
+}
+
 function serializeProfileConfig(profile: ProfileConfig): Record<string, unknown> {
   const serialized: Record<string, unknown> = {};
 
@@ -246,3 +259,40 @@ export function resolveProfile(
 
   throw new ProfileResolutionError("No profile could be resolved from config.");
 }
+
+export function validateBaseUrl(value: string): 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.`,
+    );
+  }
+
+  if (!["http:", "https:"].includes(parsed.protocol) || !parsed.host) {
+    throw new ProfileResolutionError(
+      `Environment variable ${ENV_BASE_URL} must be an absolute http(s) URL.`,
+    );
+  }
+
+  return value.replace(/\/+$/, "");
+}
+
+export function readEnvApiKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return toNonEmptyString(env[ENV_API_KEY]);
+}
+
+export function readEnvBaseUrl(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const baseUrl = toNonEmptyString(env[ENV_BASE_URL]);
+  if (!baseUrl) {
+    return undefined;
+  }
+
+  return validateBaseUrl(baseUrl);
+}
+
+export function readEnvProfile(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return toNonEmptyString(env[ENV_PROFILE]);
+}

package/src/runtime-context.ts

@@ -1,18 +1,97 @@
 import type { AppConfig, RuntimeContext, RuntimeOverrides } from "./types.js";
 
-import { resolveProfile } from "./config.js";
+import {
+  DEFAULT_PRODUCTION_BASE_URL,
+  ENV_API_KEY,
+  ENV_BASE_URL,
+  readEnvApiKey,
+  readEnvBaseUrl,
+  readEnvProfile,
+  resolveProfile,
+  ProfileResolutionError,
+} from "./config.js";
 
 export function resolveRuntimeContext(
   config: AppConfig,
   overrides: RuntimeOverrides = {},
 ): RuntimeContext {
-  const profile = resolveProfile(config, overrides);
+  const envProfile = readEnvProfile();
+  const envApiKey = readEnvApiKey();
+  const envBaseUrl = readEnvBaseUrl();
+
+  const profileOverride = overrides.profile ?? envProfile;
+  const apiKeyOverride = overrides.apiKey ?? envApiKey;
+  const baseUrlOverride = overrides.baseUrl ?? envBaseUrl;
+
+  if (apiKeyOverride && !baseUrlOverride) {
+    throw new ProfileResolutionError(
+      `Runtime API key was provided, but ${ENV_BASE_URL} or --base-url is missing.`,
+    );
+  }
+
+  if (baseUrlOverride && !apiKeyOverride) {
+    throw new ProfileResolutionError(
+      `Runtime base URL was provided, but ${ENV_API_KEY} or --api-key is missing.`,
+    );
+  }
+
+  if (apiKeyOverride && baseUrlOverride) {
+    return {
+      profile: profileOverride ?? "runtime",
+      baseUrl: baseUrlOverride,
+      apiKey: apiKeyOverride,
+      readOnly: overrides.readOnly ?? false,
+      json: overrides.json ?? false,
+      profileSource:
+        overrides.profile !== undefined
+          ? "flag"
+          : envProfile !== undefined
+            ? "env"
+            : undefined,
+      baseUrlSource:
+        overrides.baseUrl !== undefined
+          ? "flag"
+          : envBaseUrl !== undefined
+            ? "env"
+            : undefined,
+      apiKeySource:
+        overrides.apiKey !== undefined
+          ? "flag"
+          : envApiKey !== undefined
+            ? "env"
+            : undefined,
+    };
+  }
+
+  const profile = resolveProfile(config, {
+    profile: profileOverride,
+    baseUrl: baseUrlOverride,
+    apiKey: apiKeyOverride,
+  });
 
   return {
     profile: profile.name,
-    baseUrl: overrides.baseUrl ?? profile.baseUrl,
-    apiKey: overrides.apiKey ?? profile.apiKey,
+    baseUrl: baseUrlOverride ?? profile.baseUrl ?? DEFAULT_PRODUCTION_BASE_URL,
+    apiKey: apiKeyOverride ?? profile.apiKey,
     readOnly: overrides.readOnly ?? false,
     json: overrides.json ?? false,
+    profileSource:
+      overrides.profile !== undefined
+        ? "flag"
+        : envProfile !== undefined
+          ? "env"
+          : "config",
+    baseUrlSource:
+      overrides.baseUrl !== undefined
+        ? "flag"
+        : envBaseUrl !== undefined
+          ? "env"
+          : "config",
+    apiKeySource:
+      overrides.apiKey !== undefined
+        ? "flag"
+        : envApiKey !== undefined
+          ? "env"
+          : "config",
   };
 }

package/src/types.ts

@@ -26,12 +26,17 @@ export interface RuntimeOverrides {
   json?: boolean;
 }
 
+export type RuntimeValueSource = "flag" | "env" | "config";
+
 export interface RuntimeContext {
   profile: string;
   baseUrl?: string;
   apiKey?: string;
   readOnly: boolean;
   json: boolean;
+  profileSource?: RuntimeValueSource;
+  baseUrlSource?: RuntimeValueSource;
+  apiKeySource?: RuntimeValueSource;
 }
 
 export type JsonScalar = string | number | boolean | null;

package/src/utils/examples.ts

@@ -1,7 +1,7 @@
 import { AutomationsApi } from "../api/automations.js";
 import { SchemasApi, type ApiSchema, type ApiSchemaField } from "../api/schemas.js";
 import { ApiClient } from "../client.js";
-import { defaultConfigPath, readConfig } from "../config.js";
+import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import type { NormalizedUuidOrSlug } from "../parsers/selectors.js";
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { RuntimeOverrides } from "../types.js";
@@ -466,7 +466,7 @@ async function createExampleAutomationContext(
   }
 
   try {
-    const config = readConfig(options.configPath ?? defaultConfigPath);
+    const config = readRuntimeConfig(options.configPath ?? defaultConfigPath);
     const runtime = resolveRuntimeContext(config, options.overrides);
 
     if (!runtime.baseUrl) {