akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/commands/command/command-execution.js

@@ -0,0 +1,308 @@
+// 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/.
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { cloneExecutionJsonObject } from "../../execution/json.js";
+import { createInlineResolvedCommand, createResolvedCommand, createResolvedPersona, } from "../../execution/resolved-request.js";
+import { isPortableExecutionAgentSelector, } from "../../execution/source.js";
+import { recordIndexedShowUsage } from "../../indexer/usage/show-usage.js";
+import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
+import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, } from "../../integrations/agent/engine-fallback.js";
+import { requireAuthorizedExecutionPlan, } from "../../integrations/agent/execution-cascade.js";
+import { dispatchLoweredExecutionRequest, lowerResolvedExecutionRequest, } from "../../integrations/agent/execution-lowering.js";
+import { prepareResolvedExecution } from "../../integrations/agent/execution-preparation.js";
+import { parseBuiltinCommandAction } from "./builtin-action.js";
+import { loadAdapterExecutionSource, } from "./execution-source-loader.js";
+import { applyPortableCommandArguments } from "./portable-template.js";
+function own(value, key) {
+    return Object.hasOwn(value, key);
+}
+function selectAgent(command, invocationDefaults, current) {
+    let selected = {
+        present: false,
+        source: "command",
+    };
+    for (const [source, values] of [
+        ["command", command],
+        ["invocation", invocationDefaults],
+        ["current", current],
+    ]) {
+        if (values && own(values, "agent"))
+            selected = { present: true, value: values.agent, source };
+    }
+    return selected;
+}
+function defaultSourceLoader(ref, kind, options) {
+    return kind === "command"
+        ? loadAdapterExecutionSource(ref, "command", options)
+        : loadAdapterExecutionSource(ref, "persona", options);
+}
+function qualifyCommandSelectedPersona(selector, command) {
+    if (!command || selector.includes("//"))
+        return selector;
+    return `${command.identity.bundle}//${selector}`;
+}
+function snapshotCommandConfig(config, path = "command config") {
+    return cloneExecutionJsonObject(config, path);
+}
+export async function prepareCommandInvocation(options) {
+    const inputConfig = snapshotCommandConfig(options.config, "command input config");
+    const action = parseBuiltinCommandAction(options.action);
+    const sourceLoader = options.sourceLoader ?? defaultSourceLoader;
+    let renderedCommand;
+    let commandDefaults = Object.freeze({});
+    let command;
+    if (action.kind === "stored") {
+        const rendered = await sourceLoader(action.ref, "command", {
+            config: inputConfig,
+            ...(options.sourceLookup ? { lookup: options.sourceLookup } : {}),
+        });
+        if (rendered.kind !== "command")
+            throw new TypeError("command source loader returned a non-command source");
+        renderedCommand = rendered;
+        commandDefaults = rendered.defaults;
+        const applied = applyPortableCommandArguments(rendered.content, action.arguments, rendered.identity.ref);
+        command = createResolvedCommand({
+            source: rendered,
+            ...(own(applied, "argumentInput") ? { argumentInput: applied.argumentInput } : {}),
+            content: applied.content,
+        });
+    }
+    else {
+        if (options.inlineContentMode === "literal") {
+            if (action.arguments !== undefined) {
+                throw new UsageError("Literal inline command content cannot declare portable arguments.", "INVALID_FLAG_VALUE");
+            }
+            command = createInlineResolvedCommand({ template: action.content, content: action.content });
+        }
+        else {
+            const applied = applyPortableCommandArguments(action.content, action.arguments, "inline command");
+            command = createInlineResolvedCommand({
+                template: applied.template,
+                ...(own(applied, "argumentInput") ? { argumentInput: applied.argumentInput } : {}),
+                content: applied.content,
+            });
+        }
+    }
+    const selectedAgent = selectAgent(commandDefaults, options.invocationDefaults, options.current);
+    let renderedPersona;
+    if (selectedAgent.present &&
+        typeof selectedAgent.value === "string" &&
+        isPortableExecutionAgentSelector(selectedAgent.value)) {
+        const lookupRef = selectedAgent.source === "command"
+            ? qualifyCommandSelectedPersona(selectedAgent.value, renderedCommand)
+            : selectedAgent.value;
+        const rendered = await sourceLoader(lookupRef, "persona", {
+            config: inputConfig,
+            ...(options.sourceLookup ? { lookup: options.sourceLookup } : {}),
+        });
+        if (rendered.kind !== "persona")
+            throw new TypeError("persona source loader returned a non-persona source");
+        renderedPersona = rendered;
+    }
+    const persona = renderedPersona ? createResolvedPersona(renderedPersona) : selectedAgent.present ? null : undefined;
+    return prepareResolvedExecution({
+        command,
+        config: inputConfig,
+        invocationKind: options.invocationKind ?? "direct",
+        ...(persona !== undefined ? { persona } : {}),
+        ...(renderedPersona ? { agentLayer: { id: renderedPersona.identity.ref, values: renderedPersona.defaults } } : {}),
+        commandLayer: {
+            id: renderedCommand?.identity.ref ?? "inline-command",
+            values: commandDefaults,
+        },
+        ...(options.invocationDefaults ? { invocationDefaults: options.invocationDefaults } : {}),
+        ...(options.current ? { current: options.current } : {}),
+        ...(options.modelMap ? { modelMap: options.modelMap } : {}),
+        ...(options.authorizeTools ? { authorizeTools: options.authorizeTools } : {}),
+    });
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+const DIAGNOSTIC_PROVENANCE_FIELDS = new Set([
+    "/inference",
+    "agent",
+    "authorization",
+    "command",
+    "engine",
+    "engine.requested",
+    "model",
+    "outputSchema",
+    "persona",
+    "runtime.environment",
+    "runtime.settings",
+    "runtime.timeoutMs",
+    "runtime.workspace",
+    "tools",
+]);
+const DIAGNOSTIC_NOTICE_FIELDS = new Set([
+    "agent",
+    "command.content",
+    "command.extensions",
+    "conversation",
+    "engine",
+    "engine.extensions",
+    "extensions",
+    "inference",
+    "model",
+    "outputSchema",
+    "persona",
+    "persona.extensions",
+    "runtime.environment",
+    "runtime.extensions",
+    "runtime.settings",
+    "runtime.timeoutMs",
+    "runtime.workspace",
+    "tools",
+]);
+function canonicalDiagnosticProvenanceField(field) {
+    if (field.startsWith("/inference/"))
+        return "/inference/*";
+    return DIAGNOSTIC_PROVENANCE_FIELDS.has(field) ? field : undefined;
+}
+function canonicalDiagnosticNoticeField(field) {
+    if (typeof field !== "string")
+        return undefined;
+    if (field.startsWith("inference."))
+        return "inference.*";
+    return DIAGNOSTIC_NOTICE_FIELDS.has(field) ? field : undefined;
+}
+function diagnosticProvenance(provenance) {
+    const canonical = new Map();
+    for (const [field, source] of Object.entries(provenance)) {
+        const safeField = canonicalDiagnosticProvenanceField(field);
+        if (!safeField)
+            continue;
+        const candidate = Object.freeze({ field: safeField, layer: source.layer, kind: source.kind, via: source.via });
+        const previous = canonical.get(safeField);
+        if (!previous || compareText(JSON.stringify(candidate), JSON.stringify(previous)) < 0) {
+            canonical.set(safeField, candidate);
+        }
+    }
+    return Object.freeze([...canonical.values()].sort((left, right) => compareText(left.field, right.field)));
+}
+function safeDiagnosticToken(value) {
+    return value.length <= 128 && /^[a-z][a-z0-9-]*$/.test(value);
+}
+/** Rebuild a known lowerer notice instead of forwarding its optional details or arbitrary message bytes. */
+function safeDiagnosticNotice(notice) {
+    if (!safeDiagnosticToken(notice.adapter))
+        return undefined;
+    switch (notice.code) {
+        case "engine-fallback":
+            return Object.freeze({
+                code: "engine-fallback",
+                severity: "info",
+                adapter: "akm",
+                field: "engine",
+                message: "No engine was selected; using the fixed opencode-sdk fallback.",
+            });
+        case "unrecognized-request-notice":
+            return Object.freeze({
+                code: "unrecognized-request-notice",
+                severity: "warning",
+                adapter: "akm",
+                message: "An unrecognized durable execution notice was omitted at the engine lowering boundary.",
+            });
+        case "untranslated-field": {
+            const field = canonicalDiagnosticNoticeField(notice.field);
+            if (!field)
+                return undefined;
+            return Object.freeze({
+                code: "untranslated-field",
+                severity: "warning",
+                adapter: notice.adapter,
+                field,
+                message: `The ${notice.adapter} lowerer does not translate resolved field ${field}; dispatch will continue optimistically.`,
+            });
+        }
+        case "conversation-prompt-composed":
+            return Object.freeze({
+                code: "conversation-prompt-composed",
+                severity: "warning",
+                adapter: notice.adapter,
+                field: "conversation",
+                message: `The ${notice.adapter} transport has no native multi-message channel; AKM composed the conversation prefix into one deterministic JSON prompt block.`,
+            });
+        case "persona-prompt-composed":
+            return Object.freeze({
+                code: "persona-prompt-composed",
+                severity: "info",
+                adapter: notice.adapter,
+                field: "persona",
+                message: "The selected engine has no native persona channel; AKM composed the persona into the prompt.",
+            });
+        default:
+            return undefined;
+    }
+}
+function diagnosticNotices(notices) {
+    const canonical = new Map();
+    for (const notice of notices) {
+        const safe = safeDiagnosticNotice(notice);
+        if (safe)
+            canonical.set(JSON.stringify(safe), safe);
+    }
+    return Object.freeze([...canonical.values()].sort((left, right) => compareText(JSON.stringify(left), JSON.stringify(right))));
+}
+/**
+ * Authorize and lower a prepared invocation, then project only safe structural
+ * diagnostics. It never acquires a dispatch lease, materializes credentials,
+ * records usage, or exposes request/plan values.
+ */
+export function inspectPreparedCommandInvocation(prepared) {
+    const request = requireAuthorizedExecutionPlan(prepared.plan);
+    const lowered = lowerResolvedExecutionRequest(request, prepared.config);
+    const selectedEngine = request.engine.name;
+    if (!selectedEngine) {
+        throw new ConfigError(`command ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        shape: "command-dry-run",
+        ok: true,
+        dryRun: true,
+        engine: selectedEngine,
+        provenance: diagnosticProvenance(prepared.plan.provenance),
+        notices: diagnosticNotices(lowered.notices),
+    });
+}
+function resultEnvelope(result, engine, warnings, notices) {
+    return {
+        schemaVersion: 2,
+        ok: result.ok,
+        shape: "agent-result",
+        engine,
+        exitCode: result.exitCode,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        durationMs: result.durationMs,
+        ...(result.error !== undefined ? { error: result.error } : {}),
+        ...(result.reason !== undefined ? { reason: result.reason } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
+        ...(notices.length > 0 ? { notices } : {}),
+    };
+}
+export async function dispatchPreparedCommandInvocation(prepared, options = {}) {
+    const request = requireAuthorizedExecutionPlan(prepared.plan);
+    const lowered = lowerResolvedExecutionRequest(request, prepared.config);
+    const selectedEngine = request.engine.name;
+    if (!selectedEngine) {
+        throw new ConfigError(`command ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
+    }
+    const result = await dispatchLoweredExecutionRequest(lowered, options);
+    const consumedRefs = new Set();
+    if (request.command.source)
+        consumedRefs.add(request.command.source.ref);
+    if (request.persona)
+        consumedRefs.add(request.persona.source.ref);
+    const eventSource = resolveUsageEventSource();
+    for (const ref of consumedRefs)
+        recordIndexedShowUsage(ref, eventSource);
+    const announcement = fallbackAnnouncement(prepared.fallbackEngineName, selectedEngine);
+    return resultEnvelope(result, selectedEngine, announcement ? [announcement] : [], lowered.notices);
+}
+export async function executeCommandInvocation(options, dispatchOptions = {}) {
+    return dispatchPreparedCommandInvocation(await prepareCommandInvocation(options), dispatchOptions);
+}

package/dist/commands/command/execution-source-loader.js

@@ -0,0 +1,176 @@
+// 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/.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { adapterForId } from "../../core/adapter/registry.js";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { isWithin } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { bundleComponentConfig, bundlesToSourceEntries } from "../../core/config/config-sources.js";
+import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { lookupBundleRef } from "../../indexer/indexer.js";
+import { deriveInstallations } from "../../indexer/installations.js";
+import { resolveEntryContentDir, resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { buildFileContext } from "../../indexer/walk/file-context.js";
+async function defaultLookup(ref) {
+    return lookupBundleRef(ref);
+}
+async function effectiveConfig(config) {
+    if (config)
+        return config;
+    return loadConfig();
+}
+function realDirectory(value, label) {
+    let real;
+    let stat;
+    try {
+        real = fs.realpathSync(value);
+        stat = fs.statSync(real);
+    }
+    catch {
+        throw new NotFoundError(`${label} is missing or unreadable. Rebuild the index and retry.`, "FILE_NOT_FOUND");
+    }
+    if (!stat.isDirectory())
+        throw new ConfigError(`${label} is not a directory.`, "INVALID_CONFIG_FILE");
+    return real;
+}
+function realRegularFile(value, label) {
+    let real;
+    let stat;
+    try {
+        real = fs.realpathSync(value);
+        stat = fs.statSync(real);
+    }
+    catch {
+        throw new NotFoundError(`${label} is stale, missing, or unreadable. Rebuild the index and retry.`, "FILE_NOT_FOUND");
+    }
+    if (!stat.isFile())
+        throw new NotFoundError(`${label} is not a regular file.`, "FILE_NOT_FOUND");
+    return real;
+}
+function isLexicallyWithin(candidate, root) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function implicitComponentForEntry(entry, config, realRoot) {
+    const sources = resolveSourceEntries(undefined, config);
+    const installations = deriveInstallations(sources);
+    for (const [index, installation] of installations.entries()) {
+        if (installation.id !== entry.bundleId)
+            continue;
+        const source = sources[index];
+        const component = installation.components[0];
+        if (!source || !component)
+            continue;
+        const canonicalRoot = realDirectory(component.root, `Canonical implicit source root for ${entry.bundleId}`);
+        if (canonicalRoot !== realRoot) {
+            throw new ConfigError(`Canonical implicit source root drift for ${JSON.stringify(entry.itemRef)}; the indexed root no longer matches the working bundle source.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing AKM_BUNDLE_DIR or the default bundle directory.");
+        }
+        if (component.adapter !== entry.adapterId) {
+            throw new ConfigError(`Implicit adapter drift for ${JSON.stringify(entry.itemRef)}: the index records ${JSON.stringify(entry.adapterId)} but the canonical working source selects ${JSON.stringify(component.adapter)}.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing the working source adapter.");
+        }
+        return Object.freeze({
+            id: installation.id,
+            adapter: component.adapter,
+            root: canonicalRoot,
+            writable: component.writable,
+        });
+    }
+    return undefined;
+}
+function componentForEntry(entry, config, realRoot) {
+    const configured = config.bundles?.[entry.bundleId];
+    if (!configured) {
+        const implicit = implicitComponentForEntry(entry, config, realRoot);
+        if (implicit)
+            return implicit;
+        throw new ConfigError(`Indexed execution source ${JSON.stringify(entry.itemRef)} belongs to unconfigured bundle ${JSON.stringify(entry.bundleId)}.`, "INVALID_CONFIG_FILE", "Refresh the bundle configuration and rebuild the index before dispatching this asset.");
+    }
+    const component = bundleComponentConfig(configured);
+    const configuredAdapter = component?.adapter;
+    if (configuredAdapter && configuredAdapter !== entry.adapterId) {
+        throw new ConfigError(`Configured adapter drift for ${JSON.stringify(entry.itemRef)}: the index records ${JSON.stringify(entry.adapterId)} but the bundle config selects ${JSON.stringify(configuredAdapter)}.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing a bundle adapter.");
+    }
+    const configuredSource = bundlesToSourceEntries(config)?.find((source) => source.name === entry.bundleId);
+    const configuredContentRoot = configuredSource ? resolveEntryContentDir(configuredSource) : undefined;
+    if (!configuredSource || !configuredContentRoot) {
+        throw new ConfigError(`Configured source for ${JSON.stringify(entry.itemRef)} no longer resolves to materialized content.`, "INVALID_CONFIG_FILE", "Restore or update the bundle, then run `akm index --full` before dispatching this asset.");
+    }
+    const lexicalSourceRoot = path.resolve(configuredContentRoot);
+    const lexicalConfiguredRoot = path.resolve(configuredContentRoot, component?.root ?? ".");
+    if (!isLexicallyWithin(lexicalConfiguredRoot, lexicalSourceRoot)) {
+        throw new ConfigError(`Configured component root for ${JSON.stringify(entry.itemRef)} resolves outside its materialized bundle source.`, "INVALID_CONFIG_FILE", "Keep component roots inside their owning bundle source, then run `akm index --full`.");
+    }
+    const configuredSourceRoot = realDirectory(lexicalSourceRoot, `Configured source root for ${entry.bundleId}`);
+    let configuredRoot;
+    try {
+        configuredRoot = realDirectory(lexicalConfiguredRoot, `Configured component root for ${entry.bundleId}`);
+    }
+    catch {
+        throw new ConfigError(`Configured ${JSON.stringify(configuredSource.type)} source for ${JSON.stringify(entry.itemRef)} is not materialized at its current component root.`, "INVALID_CONFIG_FILE", "Restore or update the bundle, then run `akm index --full` before dispatching this asset.");
+    }
+    if (!isWithin(configuredRoot, configuredSourceRoot)) {
+        throw new ConfigError(`Configured component root for ${JSON.stringify(entry.itemRef)} resolves outside its materialized bundle source.`, "INVALID_CONFIG_FILE", "Remove the escaping symlink or component path, then run `akm index --full`.");
+    }
+    if (configuredRoot !== realRoot) {
+        throw new ConfigError(`Configured source or component root drift for ${JSON.stringify(entry.itemRef)}; the indexed root no longer matches the ${JSON.stringify(configuredSource.type)} bundle source.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing a bundle source or component root.");
+    }
+    const writable = component?.writable ?? configured.writable ?? configured.path !== undefined;
+    return Object.freeze({
+        id: entry.bundleId,
+        adapter: entry.adapterId,
+        root: realRoot,
+        writable,
+    });
+}
+function expectedIndexedType(kind) {
+    return kind === "command" ? "command" : "agent";
+}
+function assertRenderedIdentity(source, entry, realRoot, realFile, content) {
+    const expectedFile = path.relative(realRoot, realFile).replace(/\\/g, "/");
+    const expectedHash = createHash("sha256").update(content, "utf8").digest("hex");
+    if (source.identity.ref !== entry.itemRef ||
+        source.identity.bundle !== entry.bundleId ||
+        source.identity.adapter !== entry.adapterId ||
+        source.identity.file !== expectedFile ||
+        source.identity.hash !== expectedHash) {
+        throw new ConfigError(`Execution renderer identity drift for ${JSON.stringify(entry.itemRef)}.`, "INVALID_CONFIG_FILE", "Run `akm index --full`; if the mismatch remains, repair the owning bundle adapter.");
+    }
+}
+export async function loadAdapterExecutionSource(refInput, expectedKind, options = {}) {
+    const parsed = parseBundleRef(refInput);
+    if (parsed.fragment !== undefined) {
+        throw new UsageError(`Execution source ${JSON.stringify(refInput)} cannot select a fragment.`, "INVALID_FLAG_VALUE");
+    }
+    const entry = await (options.lookup ?? defaultLookup)(parsed);
+    if (!entry) {
+        throw new NotFoundError(`Execution source ${JSON.stringify(refInput)} was not found in the local index.`, "ASSET_NOT_FOUND", "Run `akm index --full`, then retry the command ref.");
+    }
+    const indexedType = expectedIndexedType(expectedKind);
+    if (entry.type !== indexedType) {
+        throw new UsageError(`Execution source ${JSON.stringify(refInput)} resolves to type ${JSON.stringify(entry.type)}, expected ${JSON.stringify(indexedType)}.`, "INVALID_FLAG_VALUE");
+    }
+    const config = await effectiveConfig(options.config);
+    const realRoot = realDirectory(entry.stashDir, `Indexed component root for ${entry.itemRef}`);
+    const realFile = realRegularFile(entry.filePath, `Indexed execution source ${entry.itemRef}`);
+    if (!isWithin(realFile, realRoot) || realFile === realRoot) {
+        throw new ConfigError(`Indexed execution source ${JSON.stringify(entry.itemRef)} resolves outside its component root.`, "INVALID_CONFIG_FILE", "Remove the escaping path and rebuild the index.");
+    }
+    const component = componentForEntry(entry, config, realRoot);
+    const adapter = (options.adapterFor ?? adapterForId)(entry.adapterId);
+    if (!adapter) {
+        throw new ConfigError(`Execution source adapter ${JSON.stringify(entry.adapterId)} is not registered.`, "INVALID_CONFIG_FILE");
+    }
+    if (!adapter.renderExecutionSource) {
+        throw new UsageError(`Bundle adapter ${JSON.stringify(entry.adapterId)} does not support command or persona execution.`, "INVALID_FLAG_VALUE");
+    }
+    const fileContext = (options.fileContext ?? buildFileContext)(entry.stashDir, entry.filePath);
+    const rendered = adapter.renderExecutionSource(component, fileContext);
+    if (!rendered || rendered.kind !== expectedKind) {
+        throw new ConfigError(`Bundle adapter ${JSON.stringify(entry.adapterId)} did not render ${JSON.stringify(entry.itemRef)} as a ${expectedKind}.`, "INVALID_CONFIG_FILE", "Rebuild the index; if the mismatch remains, repair the source file or owning adapter.");
+    }
+    assertRenderedIdentity(rendered, entry, realRoot, realFile, fileContext.content());
+    return rendered;
+}

package/dist/commands/command/portable-template.js

@@ -0,0 +1,60 @@
+// 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/.
+import { UsageError } from "../../core/errors.js";
+export const PORTABLE_ARGUMENTS_PLACEHOLDER = "$ARGUMENTS";
+const UNSUPPORTED_TEMPLATE_CONSTRUCTS = Object.freeze([
+    { label: "$ARGUMENTS[N]", pattern: /\$ARGUMENTS\s*\[/u },
+    { label: "```! ... ```", pattern: /(?:^|\r?\n)[\t ]*```!/u },
+    { label: "!`...`", pattern: /!`/u },
+    { label: "@file", pattern: /(?<![A-Za-z0-9._%+-])@(?:\.{0,2}\/)?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*/u },
+    { label: "$" + "{...}", pattern: /\$\{/u },
+    { label: "$(...)", pattern: /\$\(/u },
+    { label: "$N", pattern: /\$\d/u },
+    { label: "$NAME", pattern: /\$[A-Za-z_][A-Za-z0-9_]*/u },
+    { label: "{{...}}", pattern: /\{\{|\}\}/u },
+]);
+function unsupportedTemplate(source, label) {
+    return new UsageError(`Command ${JSON.stringify(source)} uses unsupported portable template construct ${label}.`, "INVALID_FLAG_VALUE", `AKM command execution supports only the literal ${PORTABLE_ARGUMENTS_PLACEHOLDER} placeholder. Invoke native-only templates through their owning tool instead.`);
+}
+/**
+ * Validate the deliberately small portable command-template language.
+ *
+ * The source identifier is safe to surface; template and argument bytes never
+ * enter the error because they may contain user or secret material.
+ */
+export function validatePortableCommandTemplate(template, source) {
+    if (typeof template !== "string")
+        throw new TypeError("command template must be a string");
+    if (typeof source !== "string" || source.length === 0)
+        throw new TypeError("command source must be a string");
+    // Check native extensions of the portable spelling before masking the one
+    // supported token. AKM never interprets indexed native placeholders.
+    const indexedArguments = UNSUPPORTED_TEMPLATE_CONSTRUCTS[0];
+    if (indexedArguments?.pattern.test(template))
+        throw unsupportedTemplate(source, indexedArguments.label);
+    // Mask only the exact portable token. Everything else remains visible to the
+    // unsupported-construct detectors, including `$ARGUMENTS_SUFFIX`.
+    const portableMasked = template.replace(/\$ARGUMENTS(?![A-Za-z0-9_])/gu, "");
+    for (const construct of UNSUPPORTED_TEMPLATE_CONSTRUCTS.slice(1)) {
+        if (construct.pattern.test(portableMasked))
+            throw unsupportedTemplate(source, construct.label);
+    }
+}
+/**
+ * Apply literal `$ARGUMENTS` replacement once. `split`/`join` is intentional:
+ * unlike `String.replace`, caller bytes such as `$&` have no replacement-string
+ * semantics, and inserted `$ARGUMENTS` text is never rescanned.
+ */
+export function applyPortableCommandArguments(template, argumentInput, source) {
+    validatePortableCommandTemplate(template, source);
+    if (argumentInput !== undefined && typeof argumentInput !== "string") {
+        throw new TypeError("command argument input must be a string or omitted");
+    }
+    const content = template.split(PORTABLE_ARGUMENTS_PLACEHOLDER).join(argumentInput ?? "");
+    return Object.freeze({
+        template,
+        ...(argumentInput === undefined ? {} : { argumentInput }),
+        content,
+    });
+}

package/dist/commands/config-cli.js

@@ -17,9 +17,10 @@ import { resolveStashDir } from "../core/common.js";
 import { DEFAULT_CONFIG, loadConfig, mutateConfig } from "../core/config/config.js";
 import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config/config-walker.js";
 import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "../core/paths.js";
+import { formatRegistryUrl } from "../core/registry-url.js";
 // ── Public API ──────────────────────────────────────────────────────────────
 export function getConfigValue(config, key) {
-    return redactConfigValue(configGet(config, key));
+    return redactConfigValue(configGet(config, key), key.split("."));
 }
 export function setConfigValue(config, key, rawValue) {
     return configSet(config, key, rawValue);
@@ -32,20 +33,25 @@ export function listConfig(config) {
     // retired top-level `sources[]` array is no longer surfaced.
     return redactConfigValue({ ...DEFAULT_CONFIG, ...config });
 }
-function redactConfigValue(value) {
+function redactConfigValue(value, path = []) {
+    if (typeof value === "string" && isRegistryUrlPath(path))
+        return formatRegistryUrl(value);
     if (Array.isArray(value))
-        return value.map(redactConfigValue);
+        return value.map((child, index) => redactConfigValue(child, [...path, String(index)]));
     if (!value || typeof value !== "object")
         return value;
     const result = {};
     for (const [key, child] of Object.entries(value)) {
         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);
+            result[key] = redactConfigValue(child, [...path, key]);
         }
     }
     return result;
 }
+function isRegistryUrlPath(path) {
+    return path[0] === "registries" && path.at(-1) === "url";
+}
 export { unknownKeyHint };
 // ── `akm config` command surface ────────────────────────────────────────────
 // Extracted verbatim from src/cli.ts (WS6). The `main.subCommands.config` key

package/dist/commands/env/env.js

@@ -53,7 +53,7 @@ import { sensitiveMarkerPath } from "./marker-path.js";
 /** Matches a KEY=value assignment line, capturing only the key. */
 const ASSIGN_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
 /** Scan lines and return KEY names in file order, without duplicates. */
-function scanKeys(text) {
+export function scanEnvKeyNames(text) {
     const keys = [];
     const seen = new Set();
     for (const line of text.split(/\r?\n/)) {
@@ -61,6 +61,8 @@ function scanKeys(text) {
         if (!m)
             continue;
         const key = m[1];
+        if (!key)
+            continue;
         if (seen.has(key))
             continue;
         seen.add(key);
@@ -81,7 +83,7 @@ export function listKeys(envPath) {
     if (!fs.existsSync(envPath))
         return { keys: [] };
     const text = fs.readFileSync(envPath, "utf8");
-    return { keys: scanKeys(text) };
+    return { keys: scanEnvKeyNames(text) };
 }
 /**
  * Read all KEY=value pairs from an env file. Intended for programmatic callers

package/dist/commands/feedback-cli.js

@@ -315,7 +315,7 @@ export const feedbackCommand = defineJsonCommand({
                 throw new UsageError(`Source "${parsedRef.bundle}" is not configured.`, "INVALID_FLAG_VALUE");
             }
             const lookupRef = makeBundleRef(parsedRef.bundle, parsedRef.conceptId);
-            const entryId = findEntryIdByRef(db, lookupRef, requestedSource?.path);
+            const entryId = findEntryIdByRef(db, lookupRef, parsedRef.bundle);
             if (entryId === undefined) {
                 // NotFoundError (exit 1), not UsageError (exit 2): the flags parsed
                 // fine, the asset just isn't there. The documented exit-code table