akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/config-cli.js

@@ -8,232 +8,69 @@
  * new config field is one line of Zod schema in `core/config-schema.ts` and
  * zero lines here — the walker handles get/set/unset/coercion uniformly.
  *
- * Legacy behaviour preserved:
- *   - `akm config set llm.<x>` writes to `profiles.llm.<defaults.llm>` (or
- *     auto-creates a "default" profile), mirroring the pre-rewrite shim.
- *   - `akm config set embedding.ollamaOptions.numCtx` is sugar for
- *     `embedding.ollamaOptions.num_ctx` (camelCase ↔ snake_case bridge).
- *   - `parseConfigValue` returns a Partial<AkmConfig> so it can be merged with
- *     the runtime config object via `mergeConfigValue`.
+ * `configVersion` is controlled by the config lifecycle. All execution
+ * settings use their canonical engine/strategy paths; retired aliases are not
+ * rewritten at this boundary.
  */
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { resolveStashDir } from "../core/common.js";
-import { DEFAULT_CONFIG, getSources, loadConfig, loadUserConfig, saveConfig, } from "../core/config/config.js";
+import { DEFAULT_CONFIG, loadConfig, mutateConfig } from "../core/config/config.js";
 import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config/config-walker.js";
-import { UsageError } from "../core/errors.js";
 import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "../core/paths.js";
-// ── Legacy `llm.*` → `profiles.llm.<default>.*` aliasing ────────────────────
-/**
- * Map a legacy top-level `llm.<sub>` path onto the actual schema path. The
- * default profile name is "default" when `defaults.llm` is unset.
- */
-function rewriteLegacyLlmPath(config, key) {
-    if (key !== "llm" && !key.startsWith("llm."))
-        return key;
-    const sub = key === "llm" ? "" : key.slice("llm.".length);
-    const profileName = config.defaults?.llm ?? "default";
-    return sub ? `profiles.llm.${profileName}.${sub}` : `profiles.llm.${profileName}`;
-}
-/**
- * Translate the legacy `embedding.ollamaOptions.numCtx` to the actual schema
- * key `embedding.ollamaOptions.num_ctx`.
- */
-function rewriteEmbeddingPath(key) {
-    if (key === "embedding.ollamaOptions.numCtx")
-        return "embedding.ollamaOptions.num_ctx";
-    return key;
-}
-/**
- * Translate the deprecated `stashes` alias for `sources` (one-way: both read
- * and write go through `sources`).
- */
-function rewriteSourcesAlias(key) {
-    if (key === "stashes")
-        return "sources";
-    if (key.startsWith("stashes."))
-        return `sources.${key.slice("stashes.".length)}`;
-    return key;
-}
-function rewriteKey(config, key) {
-    let k = rewriteLegacyLlmPath(config, key);
-    k = rewriteEmbeddingPath(k);
-    k = rewriteSourcesAlias(k);
-    return k;
-}
 // ── Public API ──────────────────────────────────────────────────────────────
 export function getConfigValue(config, key) {
-    const k = rewriteKey(config, key);
-    const value = configGet(config, k);
-    if (k.split(".").at(-1) === "apiKey")
-        return null;
-    return omitApiKeysForOutput(value);
+    return redactConfigValue(configGet(config, key));
 }
 export function setConfigValue(config, key, rawValue) {
-    // #454: reject the legacy aliases up front so the error message names the
-    // env var the user typed (AKM_LLM_API_KEY) rather than the rewritten profile
-    // env var (AKM_PROFILE_DEFAULT_API_KEY) — both work at runtime, but the
-    // shorter name matches the user's mental model.
-    if (key === "llm.apiKey") {
-        throw new UsageError("apiKey cannot be persisted in config; export AKM_LLM_API_KEY instead. (key: llm.apiKey)", "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.");
-    }
-    if (key === "embedding.apiKey") {
-        throw new UsageError("apiKey cannot be persisted in config; export AKM_EMBED_API_KEY instead. (key: embedding.apiKey)", "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.");
-    }
-    const k = rewriteKey(config, key);
-    // Legacy ergonomic: `akm config set semanticSearchMode true|false`
-    let coerced = rawValue;
-    if (k === "semanticSearchMode") {
-        if (rawValue === "true")
-            coerced = "auto";
-        else if (rawValue === "false")
-            coerced = "off";
-    }
-    let next = configSet(config, k, coerced);
-    // Legacy ergonomic shim: when the user sets `llm.<field>` and no
-    // `defaults.llm` is set, point it at the freshly-created profile so the
-    // value actually takes effect at runtime.
-    if (key === "llm" || key.startsWith("llm.")) {
-        if (!next.defaults?.llm) {
-            next = {
-                ...next,
-                defaults: { ...(next.defaults ?? {}), llm: "default" },
-            };
-        }
-    }
-    return next;
+    return configSet(config, key, rawValue);
 }
 export function unsetConfigValue(config, key) {
-    const k = rewriteKey(config, key);
-    return configUnset(config, k);
-}
-/**
- * Compatibility shim: returns a `Partial<AkmConfig>` containing just the
- * change. Older code merged this onto the live config — new code should call
- * `setConfigValue` directly (which returns the full merged config).
- */
-export function parseConfigValue(key, value) {
-    // Use a "marker" base so we can detect which top-level fields actually got
-    // touched by the set call. Anything still equal to the marker is untouched.
-    const SENTINEL = Symbol("untouched");
-    const base = { semanticSearchMode: SENTINEL };
-    const next = setConfigValue(base, key, value);
-    const patch = {};
-    for (const k of Object.keys(next)) {
-        if (next[k] !== SENTINEL) {
-            patch[k] = next[k];
-        }
-    }
-    return patch;
+    return configUnset(config, key);
 }
 export function listConfig(config) {
-    const result = {
-        semanticSearchMode: config.semanticSearchMode,
-        registries: config.registries ?? DEFAULT_CONFIG.registries ?? [],
-        output: { ...(DEFAULT_CONFIG.output ?? {}), ...(config.output ?? {}) },
-        stashDir: config.stashDir ?? null,
-        installed: config.installed ?? [],
-        sources: getSources(config),
-    };
-    if (config.defaultWriteTarget)
-        result.defaultWriteTarget = config.defaultWriteTarget;
-    if (config.embedding)
-        result.embedding = config.embedding;
-    if (config.profiles)
-        result.profiles = config.profiles;
-    if (config.defaults)
-        result.defaults = config.defaults;
-    if (config.search)
-        result.search = config.search;
-    if (config.index)
-        result.index = config.index;
-    if (config.feedback)
-        result.feedback = config.feedback;
-    if (config.improve)
-        result.improve = config.improve;
-    if (config.archiveRetentionDays !== undefined)
-        result.archiveRetentionDays = config.archiveRetentionDays;
-    if (config.configVersion !== undefined)
-        result.configVersion = config.configVersion;
-    return omitApiKeysForOutput(result);
+    // 0.9.0 (spec §10.1): sources live in `bundles` (spread from config); the
+    // retired top-level `sources[]` array is no longer surfaced.
+    return redactConfigValue({ ...DEFAULT_CONFIG, ...config });
 }
-function omitApiKeysForOutput(value) {
+function redactConfigValue(value) {
     if (Array.isArray(value))
-        return value.map(omitApiKeysForOutput);
+        return value.map(redactConfigValue);
     if (!value || typeof value !== "object")
         return value;
-    const out = {};
+    const result = {};
     for (const [key, child] of Object.entries(value)) {
-        if (key === "apiKey")
-            continue;
-        out[key] = omitApiKeysForOutput(child);
+        if (key !== "apiKey" ||
+            (typeof child === "string" && /^\$(?:[A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})$/.test(child))) {
+            result[key] = redactConfigValue(child);
+        }
     }
-    return out;
+    return result;
 }
 export { unknownKeyHint };
 // ── `akm config` command surface ────────────────────────────────────────────
 // Extracted verbatim from src/cli.ts (WS6). The `main.subCommands.config` key
-// and every config subcommand's args/output shape are byte-identical. The
-// `skills.sh` toggle helpers and the `CONFIG_SUBCOMMAND_SET` routing constant
-// are used ONLY by this command, so they move with the cluster. Leaf handlers
-// whose body is a plain `runWithJsonErrors(() => { … })` are migrated to
-// `defineJsonCommand`, which emits the same JSON envelope (stdout/stderr/
-// exit-code) as the inline form.
-const SKILLS_SH_NAME = "skills.sh";
-const SKILLS_SH_URL = "https://skills.sh";
-const SKILLS_SH_PROVIDER = "skills-sh";
-function normalizeToggleTarget(target) {
-    const normalized = target.trim().toLowerCase();
-    if (normalized === "skills.sh" || normalized === "skills-sh")
-        return "skills.sh";
-    throw new UsageError(`Unsupported target "${target}". Supported targets: skills.sh`);
-}
-function toggleSkillsShRegistry(enabled) {
-    const config = loadUserConfig();
-    const registries = (config.registries ?? DEFAULT_CONFIG.registries ?? []).map((registry) => ({ ...registry }));
-    const idx = registries.findIndex((registry) => registry.provider === SKILLS_SH_PROVIDER || registry.name === SKILLS_SH_NAME || registry.url === SKILLS_SH_URL);
-    if (idx >= 0) {
-        const existing = registries[idx];
-        const wasEnabled = existing.enabled !== false;
-        existing.enabled = enabled;
-        saveConfig({ ...config, registries });
-        return { changed: wasEnabled !== enabled, component: SKILLS_SH_NAME, enabled };
-    }
-    if (!enabled) {
-        // Materialize the skills.sh registry explicitly if absent.
-        registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: false });
-        saveConfig({ ...config, registries });
-        return { changed: true, component: SKILLS_SH_NAME, enabled: false };
-    }
-    registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: true });
-    saveConfig({ ...config, registries });
-    return { changed: true, component: SKILLS_SH_NAME, enabled: true };
-}
-function toggleComponent(targetRaw, enabled) {
-    const target = normalizeToggleTarget(targetRaw);
-    if (target === "skills.sh")
-        return toggleSkillsShRegistry(enabled);
-    // normalizeToggleTarget throws for any unsupported target; this is unreachable.
-    throw new UsageError(`Unsupported target "${targetRaw}". Supported targets: skills.sh`);
-}
+// and every config subcommand's args/output shape are byte-identical. Leaf
+// handlers whose body is a plain `runWithJsonErrors(() => { … })` are
+// migrated to `defineJsonCommand`, which emits the same JSON envelope
+// (stdout/stderr/exit-code) as the inline form.
+//
+// `akm config enable|disable` (a hardcoded alias for toggling the skills.sh
+// registry) was removed in 0.9.0 (C4). Use `akm registry add|remove`, the
+// general mechanism, instead.
 export const configCommand = defineGroupCommand({
     meta: { name: "config", description: "Show and manage configuration" },
-    args: {
-        list: { type: "boolean", description: "List current configuration", default: false },
-    },
     subCommands: {
         path: defineJsonCommand({
-            meta: { name: "path", description: "Show paths to config, stash, cache, and index" },
+            meta: { name: "path", description: "Show paths to config, bundle, cache, and index" },
             args: {
-                all: { type: "boolean", description: "Show all paths (config, stash, cache, index)", default: false },
+                all: { type: "boolean", description: "Show all paths (config, bundle, cache, index)", default: false },
             },
             run({ args }) {
                 const configPath = getConfigPath();
                 if (args.all) {
                     let stashDir;
                     try {
-                        stashDir = resolveStashDir({ readOnly: true });
+                        stashDir = resolveStashDir();
                     }
                     catch {
                         stashDir = `${getDefaultStashDir()} (not initialized)`;
@@ -241,7 +78,7 @@ export const configCommand = defineGroupCommand({
                     const cacheDir = getCacheDir();
                     const result = {
                         config: configPath,
-                        stash: stashDir,
+                        bundle: stashDir,
                         cache: cacheDir,
                         index: getDbPath(),
                     };
@@ -258,16 +95,10 @@ export const configCommand = defineGroupCommand({
                 output("config", listConfig(loadConfig()));
             },
         }),
-        show: defineJsonCommand({
-            meta: { name: "show", description: "Alias for `akm config list` — list current configuration" },
-            run() {
-                output("config", listConfig(loadConfig()));
-            },
-        }),
         get: defineJsonCommand({
             meta: { name: "get", description: "Get a configuration value by key" },
             args: {
-                key: { type: "positional", required: true, description: "Config key (for example: embedding, stashDir)" },
+                key: { type: "positional", required: true, description: "Config key (for example: embedding, defaultBundle)" },
             },
             run({ args }) {
                 output("config", getConfigValue(loadConfig(), args.key));
@@ -276,7 +107,11 @@ export const configCommand = defineGroupCommand({
         set: defineJsonCommand({
             meta: { name: "set", description: "Set a configuration value by key" },
             args: {
-                key: { type: "positional", required: true, description: "Config key (for example: embedding, llm)" },
+                key: {
+                    type: "positional",
+                    required: true,
+                    description: "Config key (for example: embedding, engines.default)",
+                },
                 value: { type: "positional", required: true, description: "Config value" },
                 // #463: stable machine-friendly entry point for plugins / hooks.
                 // `--silent` suppresses the config dump on stdout so hook-driven
@@ -286,31 +121,16 @@ export const configCommand = defineGroupCommand({
                     description: "Suppress the post-write config dump on stdout. Use from hooks and CI scripts; the write still happens and errors still print.",
                     default: false,
                 },
-                // #463: explicit layer flag for forward-compat. User layer is the only
-                // settable layer today; the flag exists so plugin authors can encode
-                // intent and the surface stays stable if project-layer writes return.
-                layer: {
-                    type: "string",
-                    description: "Config layer to write to. Currently only `user` is supported.",
-                    default: "user",
-                },
             },
             run({ args }) {
-                if (args.layer && args.layer !== "user") {
-                    throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.8.0.`, "INVALID_FLAG_VALUE");
-                }
-                // Use loadConfig (not loadUserConfig) so the project-config
-                // deprecation warning fires consistently with `akm config get`
-                // (#457). Effective merged shape is identical post-0.8.0.
-                const updated = setConfigValue(loadConfig(), args.key, args.value);
-                saveConfig(updated);
+                const updated = mutateConfig((current) => setConfigValue(current, args.key, args.value)).config;
                 if (!args.silent) {
                     output("config", listConfig(updated));
                 }
             },
         }),
         unset: defineJsonCommand({
-            meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/llm section" },
+            meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/engine section" },
             args: {
                 key: { type: "positional", required: true, description: "Config key to unset" },
                 silent: {
@@ -318,78 +138,21 @@ export const configCommand = defineGroupCommand({
                     description: "Suppress the post-write config dump on stdout.",
                     default: false,
                 },
-                layer: {
-                    type: "string",
-                    description: "Config layer to write to. Currently only `user` is supported.",
-                    default: "user",
-                },
             },
             run({ args }) {
-                if (args.layer && args.layer !== "user") {
-                    throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.8.0.`, "INVALID_FLAG_VALUE");
-                }
-                const updated = unsetConfigValue(loadConfig(), args.key);
-                saveConfig(updated);
+                const result = mutateConfig((current) => unsetConfigValue(current, args.key), { absentNoop: true });
+                const updated = result.config;
                 if (!args.silent) {
                     output("config", listConfig(updated));
                 }
             },
         }),
-        validate: defineJsonCommand({
-            meta: {
-                name: "validate",
-                description: "Validate the on-disk config file against the schema. Exits non-zero on errors.",
-            },
-            async run() {
-                const { runConfigValidate } = await import("../cli/config-validate.js");
-                await runConfigValidate();
-            },
-        }),
-        migrate: defineJsonCommand({
-            meta: {
-                name: "migrate",
-                description: "Migrate the config file to the current schema version. Use --dry-run to preview without writing.",
-            },
-            args: {
-                "dry-run": { type: "boolean", description: "Preview the migration result without writing.", default: false },
-                "print-diff": {
-                    type: "boolean",
-                    description: "Print a unified diff of old vs new config alongside the migration output.",
-                    default: false,
-                },
-            },
-            async run({ args }) {
-                const { runConfigMigrate } = await import("../cli/config-migrate.js");
-                await runConfigMigrate({ dryRun: Boolean(args["dry-run"]), printDiff: Boolean(args["print-diff"]) });
-            },
-        }),
-        enable: defineJsonCommand({
-            meta: { name: "enable", description: "Enable an optional component (skills.sh)" },
-            args: {
-                target: { type: "positional", description: "Component to enable (skills.sh)", required: true },
-            },
-            run({ args }) {
-                const result = toggleComponent(args.target, true);
-                output("enable", result);
-            },
-        }),
-        disable: defineJsonCommand({
-            meta: { name: "disable", description: "Disable an optional component (skills.sh)" },
-            args: {
-                target: { type: "positional", description: "Component to disable (skills.sh)", required: true },
-            },
-            run({ args }) {
-                const result = toggleComponent(args.target, false);
-                output("disable", result);
-            },
-        }),
     },
     // The bare `akm config` invocation (and `akm config --list`) dumps the
     // current config. defineGroupCommand short-circuits this body when a
     // registered subcommand ran, so the routing set stays derived from the
-    // subCommands map and can never desync (previously validate/migrate were
-    // missing from a hand-maintained set, causing a spurious second dump).
-    defaultRun() {
-        output("config", listConfig(loadConfig()));
-    },
+    // subCommands map and can never desync.
+    // No `defaultRun`: bare `akm config` is a usage error (exit 2), the canonical
+    // bare-group behavior — owner ruling 12. Run `akm config list` for what the
+    // bare form used to print.
 });

package/dist/commands/env/env-binding.js

@@ -0,0 +1,99 @@
+// 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/.
+/**
+ * Env-ref → resolved values, shared between `akm env run` and the workflow
+ * engine's per-unit env bindings (orchestration plan, *Dispatch context*).
+ *
+ * Extracted from `env-cli.ts`'s `runEnvInjected` so the native executor
+ * REUSES the exact same machinery instead of forking it. Every safety
+ * invariant carries over unchanged:
+ *
+ *   - `${secret:NAME}` tokens resolve against the env's own stash; a missing
+ *     secret is a hard error and NOTHING is injected (no partial injection).
+ *   - Known process-hijacking keys (LD_PRELOAD, PATH, …) are blocked for
+ *     third-party-sourced stashes and warned about for first-party ones.
+ *   - An `env_access` audit event records key NAMES only, never values.
+ *   - Resolved values must never be written to stdout or logs by callers.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { decideDangerousEnvInjection } from "../../core/activation-policy.js";
+import { assetPathForName } from "../../core/asset/asset-placement.js";
+import { isWithin } from "../../core/common.js";
+import { makeEnvRef, makeSecretRef, resolveEnvPath } from "../../core/env-secret-ref.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { isDangerousEnvKey } from "../lint/env-key-rules.js";
+import { loadEnv, resolveSecretTokens } from "./env.js";
+import { readValue } from "./secret.js";
+/**
+ * Resolve an env ref to its injectable values: load the file, apply key
+ * filtering, substitute `${secret:NAME}` tokens from the sibling secrets
+ * directory, enforce the dangerous-key policy, and append the keys-only
+ * `env_access` audit event.
+ */
+export function resolveEnvBinding(target, options = {}) {
+    const warn = options.warn ?? ((message) => process.stderr.write(`warning: ${message}\n`));
+    const { name, absPath, source } = resolveEnvPath(target);
+    const envRef = makeEnvRef(name, source);
+    if (!fs.existsSync(absPath)) {
+        throw new NotFoundError(`Env not found: ${envRef}`);
+    }
+    const allValues = loadEnv(absPath);
+    // Value-safe key filtering (--only / --except operate on key NAMES only).
+    let envValues = allValues;
+    if (options.only && options.except) {
+        throw new UsageError("Pass only one of --only or --except.", "INVALID_FLAG_VALUE");
+    }
+    if (options.only) {
+        const wanted = new Set(options.only);
+        const missing = options.only.filter((k) => !(k in allValues));
+        if (missing.length > 0) {
+            warn(`--only key(s) not present in ${envRef}: ${missing.join(", ")}`);
+        }
+        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => wanted.has(k)));
+    }
+    else if (options.except) {
+        const excluded = new Set(options.except);
+        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => !excluded.has(k)));
+    }
+    // Substitute `${secret:NAME}` tokens with the sibling secret asset in the
+    // SAME stash. A missing secret is a hard error — inject NOTHING.
+    const secretsRoot = path.join(source.path, "secrets");
+    const resolveSecret = (secretName) => {
+        const secretPath = assetPathForName("secret", secretsRoot, secretName);
+        // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
+        if (!isWithin(secretPath, secretsRoot)) {
+            throw new UsageError(`Secret name "${secretName}" escapes the secrets directory.`);
+        }
+        if (!fs.existsSync(secretPath))
+            return undefined;
+        // Match `secret run`: read utf8, do not trim (stay consistent with that path).
+        return readValue(secretPath).toString("utf8");
+    };
+    const { values: substituted, missing } = resolveSecretTokens(envValues, resolveSecret);
+    if (missing.length > 0) {
+        throw new NotFoundError(`Env "${envRef}" references secret(s) not found in its stash: ${missing.map((n) => makeSecretRef(n)).join(", ")}. Nothing was injected.`, "FILE_NOT_FOUND", `Create the missing secret, e.g. \`akm secret set ${makeSecretRef(missing[0])}\`.`);
+    }
+    envValues = substituted;
+    const keys = Object.keys(envValues);
+    // Scan injected keys for known process-hijacking variables. The workspace
+    // activation policy decides block (third-party, registryId set) vs. warn
+    // (first-party stash, where the operator owns the file).
+    const dangerous = keys.filter(isDangerousEnvKey);
+    if (dangerous.length > 0) {
+        const detail = `Env "${envRef}" injects process-hijacking variable(s): ${dangerous.join(", ")}.`;
+        const decision = decideDangerousEnvInjection({ dangerousKeys: dangerous, thirdParty: Boolean(source.registryId) });
+        if (decision === "block") {
+            throw new UsageError(`Refusing to inject env from a third-party stash. ${detail}\n` +
+                `       Review the file, then copy the values into a first-party env if you trust them.`, "INVALID_FLAG_VALUE");
+        }
+        if (decision === "warn") {
+            warn(`${detail} Injecting anyway (first-party stash).`);
+        }
+    }
+    // Audit trail: keys only, never values.
+    appendEvent({ eventType: "env_access", ref: envRef, metadata: { keys } });
+    return { ref: envRef, values: envValues, keys };
+}