akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/core/config/config-version.js

@@ -0,0 +1,29 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/** Compare legacy numeric or semver-like config versions for diagnostics only. */
+export function compareConfigVersion(a, b) {
+    const left = normalize(a);
+    const right = normalize(b);
+    if (!left || !right)
+        return undefined;
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const l = left[index] ?? 0;
+        const r = right[index] ?? 0;
+        if (l < r)
+            return -1;
+        if (l > r)
+            return 1;
+    }
+    return 0;
+}
+function normalize(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return [0, Math.trunc(value), 0];
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const parts = value.trim().replace(/^v/i, "").split(/[-+]/, 1)[0].split(".");
+    if (parts.some((part) => !/^\d+$/.test(part)))
+        return undefined;
+    return parts.map(Number);
+}

package/dist/core/config/config-walker.js

@@ -22,7 +22,8 @@
  */
 import { z } from "zod";
 import { UsageError } from "../errors.js";
-import { AkmConfigBaseSchema, listTopLevelConfigKeys } from "./config-schema.js";
+import { AkmConfigBaseSchema, EngineConfigSchema, listTopLevelConfigKeys } from "./config-schema.js";
+import { deepMergeConfig } from "./deep-merge.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.
@@ -73,9 +74,10 @@ function unwrap(schema) {
  * AkmConfig schema. Returns `undefined` if any path segment doesn't match a
  * known schema field.
  */
-function resolveSchemaAt(path) {
+function resolveSchemaAt(path, config, raw) {
     let schema = AkmConfigBaseSchema;
-    for (const segment of path) {
+    let existing = config;
+    for (const [index, segment] of path.entries()) {
         schema = unwrap(schema);
         if (schema instanceof z.ZodObject) {
             const next = schema.shape[segment];
@@ -84,23 +86,56 @@ function resolveSchemaAt(path) {
                 const catchall = schema._def.catchall;
                 if (catchall && !(catchall instanceof z.ZodNever)) {
                     schema = catchall;
-                    continue;
                 }
-                return undefined;
+                else {
+                    return undefined;
+                }
+            }
+            else {
+                schema = next;
             }
-            schema = next;
         }
         else if (schema instanceof z.ZodRecord) {
-            // Records (profiles.llm, profiles.agent, profiles.improve, sources, etc.)
+            // Named records (engines, improve.strategies, sources, etc.)
             // accept any string key — descend into the value schema.
             schema = schema._def.valueType;
         }
+        else if (schema instanceof z.ZodUnion) {
+            const option = selectUnionObjectOption(schema._def.options, segment, existing, index === path.length - 1 ? raw : undefined);
+            if (!option)
+                return undefined;
+            schema = option.shape[segment];
+        }
         else {
             // Cannot descend into a non-object schema.
             return undefined;
         }
+        existing = isPlainObject(existing) ? existing[segment] : undefined;
     }
-    return unwrap(schema);
+    // Preserve leaf refinements/transforms for validation. Traversal unwraps at
+    // the start of each loop iteration, while coercion unwraps independently.
+    return schema;
+}
+function selectUnionObjectOption(candidates, segment, existing, raw) {
+    const options = candidates
+        .map((candidate) => unwrap(candidate))
+        .filter((candidate) => candidate instanceof z.ZodObject);
+    if (raw !== undefined) {
+        const requested = options.find((option) => {
+            const leaf = option.shape[segment];
+            if (!leaf || !(unwrap(leaf) instanceof z.ZodLiteral))
+                return false;
+            return leaf.safeParse(coerceForSchema(leaf, raw, segment)).success;
+        });
+        if (requested)
+            return requested;
+    }
+    if (isPlainObject(existing)) {
+        const selected = options.find((option) => Object.entries(option.shape).some(([key, field]) => key in existing && unwrap(field) instanceof z.ZodLiteral && field.safeParse(existing[key]).success));
+        if (selected)
+            return segment in selected.shape ? selected : undefined;
+    }
+    return options.find((option) => segment in option.shape);
 }
 /**
  * Get the value at the dotted path from a config-shaped object. Returns
@@ -109,7 +144,7 @@ function resolveSchemaAt(path) {
  */
 export function configGet(config, dotted) {
     const path = parsePath(dotted);
-    const schema = resolveSchemaAt(path);
+    const schema = resolveSchemaAt(path, config);
     if (!schema) {
         throw new UsageError(`Unknown config key: ${dotted}`, "INVALID_FLAG_VALUE", unknownKeyHint(dotted));
     }
@@ -129,23 +164,38 @@ export function configGet(config, dotted) {
  *
  * Throws {@link UsageError} on:
  *   - unknown path
- *   - apiKey paths (#454)
+ *   - invalid apiKey paths
  *   - coercion failure
  */
 export function configSet(config, dotted, raw) {
     const path = parsePath(dotted);
+    if (path.length === 1 && path[0] === "configVersion") {
+        throw new UsageError("configVersion cannot be changed through config set.", "INVALID_FLAG_VALUE");
+    }
     // #454: apiKey paths are not persistable. Throw at set time.
     rejectApiKeyPath(path, dotted);
-    const schema = resolveSchemaAt(path);
-    if (!schema) {
+    const schema = resolveSchemaAt(path, config, raw);
+    const symbolicApiKey = (path[0] === "engines" && path[2] === "apiKey") ||
+        (path[0] === "embedding" && path.length === 2 && path[1] === "apiKey");
+    if (!schema && !symbolicApiKey) {
         throw new UsageError(`Unknown config key: ${dotted}`, "INVALID_FLAG_VALUE", unknownKeyHint(dotted));
     }
-    const value = coerceForSchema(schema, raw, dotted);
+    const value = path[0] === "engines" && path.length === 2
+        ? parseObjectPatch(raw, dotted)
+        : symbolicApiKey
+            ? raw
+            : coerceForSchema(schema, raw, dotted);
     // Validate the coerced value against the leaf schema. This catches enum
     // mismatches, out-of-range numbers, schema-level shape errors (writable
     // npm/website sources via .superRefine, strict-mode unknown keys in nested
     // objects, etc.) BEFORE we apply the patch.
-    const parsed = schema.safeParse(value);
+    const parsed = path[0] === "engines" && path.length === 2
+        ? EngineConfigSchema.safeParse(value)
+        : symbolicApiKey
+            ? /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(raw)
+                ? { success: true, data: value }
+                : { success: false, error: { issues: [{ path: [], message: `apiKey must be $VAR or \${VAR}` }] } }
+            : schema.safeParse(value);
     if (!parsed.success) {
         const lines = parsed.error.issues
             .map((i) => {
@@ -155,7 +205,12 @@ export function configSet(config, dotted, raw) {
             .join("\n");
         throw new UsageError(`Invalid value for ${dotted}:\n${lines}`, "INVALID_FLAG_VALUE");
     }
-    const next = setPath(config, path, parsed.data);
+    const existing = path.reduce((value, key) => {
+        if (value && typeof value === "object")
+            return value[key];
+        return undefined;
+    }, config);
+    const next = setPath(config, path, isPlainObject(existing) && isPlainObject(parsed.data) ? deepMergeConfig(existing, parsed.data) : parsed.data);
     // Targeted invariant: defaultWriteTarget must point at a configured source
     // (#464.a). Whole-config validation happens at save time; this check fires
     // at set time so the user sees the typo immediately. Empty-sources case is
@@ -175,8 +230,11 @@ export function configSet(config, dotted, raw) {
  */
 export function configUnset(config, dotted) {
     const path = parsePath(dotted);
+    if (path.length === 1 && path[0] === "configVersion") {
+        throw new UsageError("configVersion cannot be removed through config unset.", "INVALID_FLAG_VALUE");
+    }
     // Validate the path resolves to a real schema field (so typos don't no-op).
-    const schema = resolveSchemaAt(path);
+    const schema = resolveSchemaAt(path, config);
     if (!schema) {
         throw new UsageError(`Unknown config key: ${dotted}`, "INVALID_FLAG_VALUE", unknownKeyHint(dotted));
     }
@@ -184,12 +242,14 @@ export function configUnset(config, dotted) {
 }
 // ── apiKey rejection (#454) ─────────────────────────────────────────────────
 /**
- * Reject any attempt to persist an apiKey via `akm config set`. Matches:
- *   - `llm.apiKey` (legacy alias mapped to default LLM profile)
- *   - `embedding.apiKey`
- *   - `profiles.llm.<name>.apiKey`
+ * Embedding credentials are never persisted. Engine credentials are symbolic
+ * configuration and are validated by the engine schema below.
  */
 function rejectApiKeyPath(path, dotted) {
+    if (path[0] === "engines" && path[2] === "apiKey")
+        return;
+    if (path[0] === "embedding" && path.length === 2 && path[1] === "apiKey")
+        return;
     const last = path[path.length - 1];
     if (last !== "apiKey")
         return;
@@ -197,14 +257,25 @@ function rejectApiKeyPath(path, dotted) {
     throw new UsageError(`apiKey cannot be persisted in config; export ${recipe} instead. (key: ${dotted})`, "INVALID_FLAG_VALUE", "Storing API keys in config.json leaks them through backups, logs, and version control. " +
         "Use the corresponding environment variable. AKM reads it at request time.");
 }
+function parseObjectPatch(raw, key) {
+    try {
+        const value = JSON.parse(raw);
+        if (!isPlainObject(value))
+            throw new Error("expected an object");
+        return value;
+    }
+    catch (err) {
+        throw new UsageError(`Invalid JSON object for ${key}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_JSON_CONFIG_VALUE");
+    }
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function recipeForApiKey(path, _dotted) {
     if (path[0] === "embedding")
         return "AKM_EMBED_API_KEY";
-    if (path[0] === "llm")
-        return "AKM_LLM_API_KEY";
-    if (path[0] === "profiles" && path[1] === "llm" && typeof path[2] === "string") {
-        const upper = path[2].toUpperCase().replace(/-/g, "_");
-        return `AKM_PROFILE_${upper}_API_KEY (or AKM_LLM_API_KEY for the default profile)`;
+    if (path[0] === "engines" && typeof path[1] === "string") {
+        return `AKM_ENGINE_${path[1].toUpperCase().replaceAll("-", "_")}_API_KEY`;
     }
     return "AKM_LLM_API_KEY / AKM_EMBED_API_KEY";
 }
@@ -237,7 +308,7 @@ function coerceForSchema(schema, raw, key) {
         return raw;
     }
     if (target instanceof z.ZodLiteral) {
-        return target._def.value;
+        return typeof target._def.value === "string" ? raw : target._def.value;
     }
     if (target instanceof z.ZodArray || target instanceof z.ZodObject || target instanceof z.ZodRecord) {
         if (raw === "" || raw === "null")
@@ -333,5 +404,5 @@ function unsetPath(config, path) {
 // ── Hint generation (#460) ──────────────────────────────────────────────────
 export function unknownKeyHint(_attempted) {
     const keys = listTopLevelConfigKeys();
-    return `Valid top-level keys: ${keys.join(", ")}. Use dotted paths for nested values (e.g. embedding.endpoint, profiles.llm.<name>.model).`;
+    return `Valid top-level keys: ${keys.join(", ")}. Use dotted paths for nested values (e.g. embedding.endpoint, engines.<name>.model).`;
 }