zinkee 0.1.1 → 0.1.4

package/AGENTS.md

@@ -13,6 +13,10 @@ Use this order when reasoning about behavior:
 ## Key Runtime Rules
 
 - Existing config compatibility is mandatory: `~/.config/zinkee/config.toml`
+- Runtime env compatibility is mandatory for agentic/backend use:
+  - `ZINKEE_PROFILE`
+  - `ZINKEE_API_BASE_URL`
+  - `ZINKEE_API_KEY`
 - `--read-only` must block write/destructive commands before network calls
 - `--example <command path>` should return concrete usage examples without running the command
 - `--json` must keep stdout machine-readable

package/README.md

@@ -64,6 +64,31 @@ base_url = "https://api.zinkee.com"
 | `--example` | Show examples for a command |
 | `--json` | Emit JSON output |
 
+## Runtime Resolution
+
+The CLI resolves runtime settings with this precedence:
+
+1. CLI flags: `--profile`, `--base-url`, `--api-key`
+2. Environment variables: `ZINKEE_PROFILE`, `ZINKEE_API_BASE_URL`, `ZINKEE_API_KEY`
+3. `~/.config/zinkee/config.toml`
+
+If a runtime API key is provided, a runtime base URL must also be provided.
+If a runtime base URL is provided, a runtime API key must also be provided.
+
+Example for local development without config:
+
+```bash
+ZINKEE_API_BASE_URL=http://localhost:8088 \
+ZINKEE_API_KEY="<workspace_token>" \
+zinkee --json schemas list
+```
+
+Example using an env-selected profile:
+
+```bash
+ZINKEE_PROFILE=local zinkee --json schemas list
+```
+
 ## JSON Contract
 
 Successful commands emit:

package/dist/index.js

@@ -1317,6 +1317,10 @@ import { dirname, join } from "path";
 import { parseTOML, stringifyTOML } from "confbox/toml";
 var defaultConfigPath = join(homedir(), ".config", "zinkee", "config.toml");
 var redactedSecretMask = "********";
+var ENV_API_KEY = "ZINKEE_API_KEY";
+var ENV_BASE_URL = "ZINKEE_API_BASE_URL";
+var ENV_PROFILE = "ZINKEE_PROFILE";
+var DEFAULT_PRODUCTION_BASE_URL = "https://api-z2.zinkee.com";
 var ProfileResolutionError = class extends Error {
   name = "ProfileResolutionError";
   constructor(message) {
@@ -1329,6 +1333,10 @@ function isRecord2(value) {
 function toStringValue(value) {
   return typeof value === "string" ? value : void 0;
 }
+function toNonEmptyString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
 function parseProfileConfig(value) {
   const profile = {};
   if (!isRecord2(value)) {
@@ -1384,6 +1392,9 @@ function readConfigIfExists(filePath = defaultConfigPath) {
     throw error;
   }
 }
+function readRuntimeConfig(filePath = defaultConfigPath) {
+  return readConfigIfExists(filePath) ?? { profiles: {} };
+}
 function serializeProfileConfig(profile) {
   const serialized = {};
   for (const [key, value] of Object.entries(profile)) {
@@ -1492,16 +1503,80 @@ function resolveProfile(config, overrides = {}) {
   }
   throw new ProfileResolutionError("No profile could be resolved from config.");
 }
+function validateBaseUrl(value) {
+  let parsed;
+  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(/\/+$/, "");
+}
+function readEnvApiKey(env = process.env) {
+  return toNonEmptyString(env[ENV_API_KEY]);
+}
+function readEnvBaseUrl(env = process.env) {
+  const baseUrl = toNonEmptyString(env[ENV_BASE_URL]);
+  if (!baseUrl) {
+    return void 0;
+  }
+  return validateBaseUrl(baseUrl);
+}
+function readEnvProfile(env = process.env) {
+  return toNonEmptyString(env[ENV_PROFILE]);
+}
 
 // src/runtime-context.ts
 function resolveRuntimeContext(config, overrides = {}) {
-  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 !== void 0 ? "flag" : envProfile !== void 0 ? "env" : void 0,
+      baseUrlSource: overrides.baseUrl !== void 0 ? "flag" : envBaseUrl !== void 0 ? "env" : void 0,
+      apiKeySource: overrides.apiKey !== void 0 ? "flag" : envApiKey !== void 0 ? "env" : void 0
+    };
+  }
+  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
+    json: overrides.json ?? false,
+    profileSource: overrides.profile !== void 0 ? "flag" : envProfile !== void 0 ? "env" : "config",
+    baseUrlSource: overrides.baseUrl !== void 0 ? "flag" : envBaseUrl !== void 0 ? "env" : "config",
+    apiKeySource: overrides.apiKey !== void 0 ? "flag" : envApiKey !== void 0 ? "env" : "config"
   };
 }
 
@@ -2288,7 +2363,7 @@ async function createExampleAutomationContext(options = {}) {
     return null;
   }
   try {
-    const config = readConfig(options.configPath ?? defaultConfigPath);
+    const config = readRuntimeConfig(options.configPath ?? defaultConfigPath);
     const runtime = resolveRuntimeContext(config, options.overrides);
     if (!runtime.baseUrl) {
       return null;
@@ -2907,7 +2982,7 @@ function toConfigurationError2(filePath, error) {
 }
 function createAutomationsApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions2(command));
     if (!runtime.baseUrl) {
       throw new CliError(
@@ -4144,7 +4219,7 @@ function toConfigurationError3(filePath, error) {
 }
 function createCommentsApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions3(command));
     if (!runtime.baseUrl) {
       throw new CliError(
@@ -4497,7 +4572,7 @@ function toConfigurationError4(filePath, error) {
 }
 function createDisplaysApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions4(command));
     if (!runtime.baseUrl) {
       throw new CliError("configuration_error", `Resolved profile "${runtime.profile}" is missing a base URL.`);
@@ -5092,7 +5167,7 @@ function toConfigurationError5(filePath, error) {
 }
 function createFilesApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions5(command));
     if (!runtime.baseUrl) {
       throw new CliError(
@@ -5311,7 +5386,7 @@ function toConfigurationError6(filePath, error) {
 }
 function createNavigationApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions6(command));
     if (!runtime.baseUrl) {
       throw new CliError("configuration_error", `Resolved profile "${runtime.profile}" is missing a base URL.`);
@@ -5861,7 +5936,7 @@ function toConfigurationError7(filePath, error) {
 }
 function createRecordsApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions8(command));
     if (!runtime.baseUrl) {
       throw new CliError(
@@ -6283,7 +6358,7 @@ function toConfigurationError8(filePath, error) {
 }
 function createSchemasApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions9(command));
     if (!runtime.baseUrl) {
       throw new CliError(
@@ -6777,7 +6852,7 @@ function toConfigurationError9(filePath, error) {
 }
 function createTeamspaceApi(command, filePath) {
   try {
-    const config = readConfig(filePath);
+    const config = readRuntimeConfig(filePath);
     const runtime = resolveRuntimeContext(config, getGlobalOptions10(command));
     if (!runtime.baseUrl) {
       throw new CliError(