akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/agent/agent-dispatch.js

@@ -16,6 +16,8 @@
 import fs from "node:fs";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
 /**
@@ -60,10 +62,18 @@ async function resolveAssetBody(ref) {
 export async function akmAgentDispatch(options) {
     if (!options.agentConfig)
         throw new UsageError("agent requires a valid config with an agent engine.", "MISSING_REQUIRED_ARGUMENT");
-    const engineName = options.engine ?? options.agentConfig.defaults?.engine;
+    // Same implicit opencode-sdk fallback the workflow and task surfaces apply,
+    // so an engine-less install is usable everywhere or nowhere — not a mix.
+    const { config: agentConfig, fallbackEngineName } = withEngineFallback(options.agentConfig);
+    const engineName = options.engine ?? agentConfig.defaults?.engine;
+    // Announced, never silent: `options.engine` outranks the default, so the
+    // fallback is only reportable when it is the engine actually selected.
+    const engineAnnouncement = fallbackAnnouncement(fallbackEngineName, engineName);
+    if (engineAnnouncement)
+        warn(engineAnnouncement);
     if (!engineName)
-        throw new UsageError("agent requires --engine or defaults.engine.", "MISSING_REQUIRED_ARGUMENT");
-    const runner = resolveEngine(engineName, options.agentConfig);
+        throw new UsageError(`agent ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "MISSING_REQUIRED_ARGUMENT");
+    const runner = resolveEngine(engineName, agentConfig);
     if (runner.kind === "llm") {
         throw new UsageError(`Engine "${engineName}" is an LLM engine; akm agent requires an agent engine.`, "INVALID_FLAG_VALUE");
     }
@@ -108,5 +118,6 @@ export async function akmAgentDispatch(options) {
         durationMs: result.durationMs,
         ...(result.error !== undefined ? { error: result.error } : {}),
         ...(result.reason !== undefined ? { reason: result.reason } : {}),
+        ...(engineAnnouncement ? { warnings: [engineAnnouncement] } : {}),
     };
 }

package/dist/commands/agent/contribute-cli.js

@@ -2,49 +2,56 @@
 // 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/.
 /**
- * Contribution command cluster (`akm agent`, `akm lint`, `akm propose`) —
- * the asset authoring / validation / proposal-creation verbs. Extracted
- * verbatim from src/cli.ts (WS6) so the God Module shrinks; the
- * `main.subCommands.{agent,lint,propose}` keys and every command's args /
- * output shape stay byte-identical.
+ * Contribution command cluster (`akm agent`, `akm lint`) — the asset
+ * authoring / validation verbs. Extracted verbatim from src/cli.ts (WS6) so
+ * the God Module shrinks; the `main.subCommands.{agent,lint}` keys and every
+ * command's args / output shape stay byte-identical.
  *
- * These three handlers each branch on the result and call `process.exit`
- * conditionally (exit 1 on a failed dispatch / proposal, or on
- * `--fail-on-flagged` lint findings), so they keep the inline
- * `runWithJsonErrors` form rather than migrating to `defineJsonCommand`
- * (which is reserved for plain runWithJsonErrors+output handlers).
+ * These handlers branch on the result and set a non-zero `process.exitCode`
+ * conditionally (exit 1 on a failed dispatch, or on `--fail-on-flagged` lint
+ * findings) rather than emitting through the thrown-error path, so they keep
+ * the inline `runWithJsonErrors` form rather than migrating to
+ * `defineJsonCommand` (which is reserved for plain runWithJsonErrors+output
+ * handlers). `process.exitCode` (not `process.exit()`) so the process still
+ * exits via natural event-loop drain rather than skipping pending cleanup —
+ * see R-067 / F4.
  *
- * NOTE on `propose` vs `proposal`: the proposal MANAGEMENT family
- * (list/show/accept/reject/…) lives in src/commands/proposal-cli.ts. The
- * `propose` (create) verb here is the asset-authoring entry point and shares
- * no private helper with that module — its path/name helpers come from the
- * shared src/core/asset-create.ts module, imported below.
+ * NOTE: the asset-authoring `propose` verb (formerly here) moved to
+ * `akm proposal new` (0.9 CLI overhaul, S8) — see
+ * src/commands/proposal/propose-cli.ts.
  */
 import fs from "node:fs";
-import path from "node:path";
 import { defineCommand } from "citty";
 import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { EXIT_CODES, output, runWithJsonErrors } from "../../cli/shared.js";
-import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
+import { EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
+import { getHyphenatedBoolean } from "../../output/context.js";
 import { akmLint } from "../lint/index.js";
-import { akmPropose } from "../proposal/propose.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
 const EXIT_GENERAL = EXIT_CODES.GENERAL;
+export function readPromptStdin(read = () => fs.readFileSync(0, "utf8")) {
+    return read();
+}
 export const agentCommand = defineCommand({
     meta: {
         name: "agent",
-        description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent asset that provides the system prompt, model, and tool policy. Use <agent-ref> to embody a stash agent, --model to override the model, and --prompt/--command/--workflow to provide the task.",
+        description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent asset that provides the system prompt, model, and tool policy. Use <agent-ref> to embody a bundle agent, --model to override the model, and --prompt/--command/--workflow to provide the task.",
     },
     args: {
+        ...GLOBAL_OUTPUT_ARGS,
         "agent-ref": {
             type: "positional",
-            description: "Optional agent asset ref (e.g. agents/code-reviewer). Loads system prompt, model, and tool policy from the stash asset.",
+            description: "Optional agent asset ref (e.g. agents/code-reviewer). Loads system prompt, model, and tool policy from the bundle asset.",
             required: false,
         },
         prompt: { type: "string", description: "Task prompt to pass to the agent" },
+        "prompt-stdin": {
+            type: "boolean",
+            description: "Read the task prompt from stdin (mutually exclusive with --prompt, --command, and --workflow)",
+            default: false,
+        },
         engine: { type: "string", description: "Agent engine to use (default: defaults.engine)" },
         command: { type: "string", description: "Load prompt from a command asset" },
         workflow: { type: "string", description: "Load prompt from a workflow asset" },
@@ -71,7 +78,10 @@ export const agentCommand = defineCommand({
             if (agentRef) {
                 const { akmShowUnified } = await import("../read/show.js");
                 const asset = await akmShowUnified({ ref: agentRef, detail: "full", eventSource: resolveUsageEventSource() });
-                systemPrompt = typeof asset.content === "string" ? asset.content : undefined;
+                if (asset.type !== "agent") {
+                    throw new UsageError(`Asset ref "${agentRef}" resolves to type "${asset.type}", expected "agent".`, "INVALID_FLAG_VALUE");
+                }
+                systemPrompt = typeof asset.prompt === "string" ? asset.prompt : undefined;
                 assetModel = typeof asset.modelHint === "string" ? asset.modelHint : undefined;
                 assetTools = asset.toolPolicy;
             }
@@ -80,22 +90,27 @@ export const agentCommand = defineCommand({
             const promptText = getStringArg(args, "prompt");
             const commandRef = getStringArg(args, "command");
             const workflowRef = getStringArg(args, "workflow");
+            const promptStdin = args["prompt-stdin"] === true;
+            if (promptStdin && (promptText !== undefined || commandRef !== undefined || workflowRef !== undefined)) {
+                throw new UsageError("--prompt-stdin cannot be combined with --prompt, --command, or --workflow.", "INVALID_FLAG_VALUE");
+            }
+            const stdinPrompt = promptStdin ? readPromptStdin() : undefined;
             const cwd = getStringArg(args, "cwd");
             // Only build a dispatch request when there is something to dispatch — a
             // prompt, an agent asset, or a model override. When none of these are
             // present the agent is launched interactively (no injected prompt, no
             // platform-specific flags beyond the profile's base args).
-            const hasDispatchContent = !!(promptText ?? commandRef ?? workflowRef ?? systemPrompt ?? model ?? assetTools);
+            const hasDispatchContent = stdinPrompt !== undefined || !!(promptText ?? commandRef ?? workflowRef ?? systemPrompt ?? model ?? assetTools);
             const result = await akmAgentDispatch({
                 engine: getStringArg(args, "engine"),
-                prompt: promptText,
+                prompt: stdinPrompt ?? promptText,
                 commandRef,
                 workflowRef,
                 agentConfig,
                 ...(hasDispatchContent
                     ? {
                         dispatch: {
-                            prompt: promptText ?? "",
+                            prompt: stdinPrompt ?? promptText ?? "",
                             systemPrompt,
                             model,
                             tools: assetTools,
@@ -108,7 +123,16 @@ export const agentCommand = defineCommand({
             });
             output("agent-result", result);
             if (!result.ok) {
-                process.exit(EXIT_GENERAL);
+                // R-067-style fix: this used to call `process.exit(EXIT_GENERAL)`
+                // directly, which terminates synchronously and skips any pending
+                // `finally`/cleanup up the call stack (including the dispatched
+                // agent process' own bookkeeping). `output()` has already run above,
+                // so there is nothing left in this handler that depends on
+                // terminating immediately — `process.exitCode` + `return` (this is
+                // the last statement anyway) lets the process exit naturally once
+                // the event loop drains.
+                process.exitCode = EXIT_GENERAL;
+                return;
             }
         });
     },
@@ -116,16 +140,33 @@ export const agentCommand = defineCommand({
 export const lintCommand = defineCommand({
     meta: {
         name: "lint",
-        description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths, broken refs in body text and in refs/xrefs/supersededBy/contradictedBy frontmatter). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
+        description: "Scan bundle .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths, broken refs in body text and in refs/xrefs/supersededBy/contradictedBy frontmatter). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
     },
     args: {
+        // R-051: `lint` is a raw `defineCommand` (not `defineJsonCommand`), so it
+        // does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
+        // `--shape`/`--output` already parsed correctly here (this command has no
+        // positional for a stray value to fall into), so this is purely a
+        // `--help` visibility / consistency fix, not a behavior change.
+        ...GLOBAL_OUTPUT_ARGS,
         fix: {
             type: "boolean",
-            alias: "auto-fix",
-            description: "Apply auto-fixes in place (alias: --auto-fix)",
+            description: "Apply auto-fixes in place",
             default: false,
         },
-        dir: { type: "string", description: "Override stash root directory (default: from config)" },
+        // Declared as its own arg rather than `alias: "auto-fix"`: citty's alias
+        // handling (node:util parseArgs `short` options) only supports
+        // SINGLE-character aliases. A
+        // multi-char alias rendered in help as `-auto-fix` (one dash) and parsed
+        // as a pile of junk single-char flags, so BOTH advertised spellings —
+        // `-auto-fix` and `--auto-fix` — silently ran a plain lint while claiming
+        // to fix. Two real boolean args, OR'd at the call site, work and render.
+        "auto-fix": {
+            type: "boolean",
+            description: "Apply auto-fixes in place (same as --fix)",
+            default: false,
+        },
+        dir: { type: "string", description: "Override bundle root directory (default: from config)" },
         "fail-on-flagged": {
             type: "boolean",
             description: "Exit non-zero when summary.flagged > 0 (CI-friendly). Default: exit 0 regardless of findings.",
@@ -139,8 +180,8 @@ export const lintCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = akmLint({
-                fix: args.fix ?? false,
+            const result = await akmLint({
+                fix: args.fix === true || getHyphenatedBoolean(args, "auto-fix"),
                 dir: getStringArg(args, "dir"),
                 typeFilter: getStringArg(args, "type"),
             });
@@ -152,59 +193,3 @@ export const lintCommand = defineCommand({
         });
     },
 });
-export const proposeCommand = defineCommand({
-    meta: {
-        name: "propose",
-        description: "Ask the configured agent CLI to author a brand-new asset and queue it as a proposal",
-    },
-    args: {
-        // Optional in citty so run() is invoked when omitted; we re-validate
-        // below to surface a structured UsageError (exit 2) instead of citty's
-        // default help-banner exit-0.
-        type: { type: "positional", description: "Asset type (skill, command, knowledge, lesson, ...)", required: false },
-        name: {
-            type: "positional",
-            description: "Asset name (flat, no '/'; use --path for a subdirectory)",
-            required: false,
-        },
-        path: {
-            type: "string",
-            description: "Relative subdirectory under the type dir to place the proposed asset in (e.g. 'release'). The filename comes from the name.",
-        },
-        task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
-        file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
-        engine: { type: "string", description: "Engine to use (defaults to defaults.engine)" },
-        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
-    },
-    async run({ args }) {
-        await runWithJsonErrors(async () => {
-            // citty silently shows help and exits 0 when required positionals are
-            // omitted. Re-validate explicitly so the exit code is 2 (USAGE) and a
-            // structured JSON error reaches scripted callers.
-            const taskFromFlag = typeof args.task === "string" ? args.task : undefined;
-            const fileFromFlag = typeof args.file === "string" ? args.file : undefined;
-            if (!args.type || !args.name || (!taskFromFlag && !fileFromFlag)) {
-                throw new UsageError("Usage: akm propose <type> <name> (--task '<task>' | --file <path>).", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and exactly one of --task or --file.");
-            }
-            if (taskFromFlag && fileFromFlag) {
-                throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
-            }
-            // `name` is flat; subdirectory placement is `--path`'s job.
-            assertFlatAssetName(String(args.name));
-            const proposedName = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), String(args.name));
-            const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
-            const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
-            const result = await akmPropose({
-                type: String(args.type),
-                name: proposedName,
-                task: taskText,
-                engine: getStringArg(args, "engine"),
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            });
-            output("propose", result);
-            if (result.ok === false) {
-                process.exit(EXIT_GENERAL);
-            }
-        });
-    },
-});

package/dist/commands/completions.js

@@ -5,32 +5,72 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { placementTypes } from "../core/asset/asset-placement.js";
-// ── Known flag values ────────────────────────────────────────────────────────
 const FLAG_VALUES = {
-    "--format": ["json", "text", "yaml", "jsonl"],
-    "--detail": ["brief", "normal", "full", "summary"],
-    "--type": () => [...placementTypes(), "any"],
-    "--source": ["stash", "registry", "both"],
-    "--shell": ["bash"],
+    "--format": [{ values: ["json", "jsonl", "yaml", "text", "md", "html"] }],
+    "--detail": [{ values: ["brief", "normal", "full"] }],
+    "--shape": [{ values: ["human", "agent", "summary"] }],
+    "--type": [{ values: () => [...placementTypes(), "any"] }],
+    "--shell": [{ values: ["bash"] }],
+    "--from": [{ paths: ["akm search", "akm curate"], values: ["local", "registry", "all"] }],
 };
+function resolveRuleValues(rule) {
+    return typeof rule.values === "function" ? rule.values() : rule.values;
+}
+/**
+ * Build the `${prev}`-case body for one flag. When the flag has no
+ * path-scoped rules, every command shares one value set (unchanged from
+ * before R-052a). When it does (currently only `--from`), nest a
+ * `${cmd_path}` match inside the flag's case so the suggestion depends on
+ * which command is being completed — with a `*)` fallback to any
+ * unscoped/global rule declared alongside the scoped ones, or no suggestion
+ * at all when every rule for that flag is scoped.
+ */
+function buildFlagValueCaseBody(rules) {
+    const scoped = rules.filter((rule) => rule.paths && rule.paths.length > 0);
+    const global = rules.find((rule) => !rule.paths || rule.paths.length === 0);
+    if (scoped.length === 0) {
+        return `      COMPREPLY=( $(compgen -W "${resolveRuleValues(global).join(" ")}" -- "\${cur}") )`;
+    }
+    const branches = scoped
+        .map((rule) => `        ${rule.paths.map((p) => `"${p}"`).join("|")})
+          COMPREPLY=( $(compgen -W "${resolveRuleValues(rule).join(" ")}" -- "\${cur}") )
+          ;;`)
+        .join("\n");
+    const fallback = global
+        ? `        *)
+          COMPREPLY=( $(compgen -W "${resolveRuleValues(global).join(" ")}" -- "\${cur}") )
+          ;;`
+        : "";
+    return `      case "\${cmd_path}" in
+${branches}
+${fallback}
+      esac`;
+}
 function walkCommandTree(cmd, parentPath = "") {
     const name = cmd.meta?.name ?? "";
     const currentPath = parentPath ? `${parentPath} ${name}` : name;
     const result = [];
-    const subcommands = Object.keys(cmd.subCommands ?? {});
+    // `meta.hidden` (e.g. `migrate`, S11) is excluded from completion the same
+    // way citty's own `renderUsage` excludes it from a rendered COMMANDS list —
+    // a hidden command still runs, it just isn't suggested.
+    const visibleSubEntries = Object.entries((cmd.subCommands ?? {})).filter(([, sub]) => !sub.meta?.hidden);
+    const subcommands = visibleSubEntries.map(([key]) => key);
     const flags = [];
+    const valueFlags = [];
     if (cmd.args) {
         for (const [flagName, arg] of Object.entries(cmd.args)) {
             if (arg.type === "positional")
                 continue;
             flags.push(`--${flagName}`);
+            if (arg.type === "boolean" && arg.default === true)
+                flags.push(`--no-${flagName}`);
+            if (arg.type !== "boolean")
+                valueFlags.push(`--${flagName}`);
         }
     }
-    result.push({ path: currentPath, subcommands, flags });
-    if (cmd.subCommands) {
-        for (const sub of Object.values(cmd.subCommands)) {
-            result.push(...walkCommandTree(sub, currentPath));
-        }
+    result.push({ path: currentPath, subcommands, flags, valueFlags });
+    for (const [, sub] of visibleSubEntries) {
+        result.push(...walkCommandTree(sub, currentPath));
     }
     return result;
 }
@@ -41,6 +81,7 @@ export function generateBashCompletions(cmd) {
     // Collect global flags from root command
     const rootInfo = commands.find((c) => c.path === rootName);
     const globalFlags = rootInfo?.flags ?? [];
+    const valueFlags = [...new Set(commands.flatMap((info) => info.valueFlags))];
     // Build the case blocks for subcommand completion
     const caseBlocks = [];
     for (const info of commands) {
@@ -61,10 +102,9 @@ export function generateBashCompletions(cmd) {
     }
     // Build flag-value completion cases
     const valueCases = [];
-    for (const [flag, valuesOrFn] of Object.entries(FLAG_VALUES)) {
-        const values = typeof valuesOrFn === "function" ? valuesOrFn() : valuesOrFn;
+    for (const [flag, rules] of Object.entries(FLAG_VALUES)) {
         valueCases.push(`    ${flag})
-      COMPREPLY=( $(compgen -W "${values.join(" ")}" -- "\${cur}") )
+${buildFlagValueCaseBody(rules)}
       return 0
       ;;`);
     }
@@ -83,20 +123,37 @@ _${rootName}() {
     cword=\${COMP_CWORD}
   fi
 
-  # Complete flag values
-  case "\${prev}" in
-${valueCases.join("\n")}
-  esac
-
-  # Build the command path from COMP_WORDS
+  # Build the command path from recognized subcommand transitions only. Positional
+  # arguments and option values cannot extend the path, so completion remains
+  # command-aware after either one.
   local cmd_path="${rootName}"
+  local skip_value=0
   for (( i=1; i < cword; i++ )); do
+    if (( skip_value )); then
+      skip_value=0
+      continue
+    fi
     case "\${words[i]}" in
+      --) break ;;
+      --*=*) continue ;;
+      ${valueFlags.join("|")}) skip_value=1; continue ;;
       -*) continue ;;
-      *) cmd_path="\${cmd_path} \${words[i]}" ;;
+      *)
+        case "\${cmd_path}:\${words[i]}" in
+${commands
+        .filter((info) => info.subcommands.length > 0)
+        .flatMap((info) => info.subcommands.map((subcommand) => `          "${info.path}:${subcommand}") cmd_path="${info.path} ${subcommand}" ;;`))
+        .join("\n")}
+        esac
+        ;;
     esac
   done
 
+  # Complete flag values
+  case "\${prev}" in
+${valueCases.join("\n")}
+  esac
+
   # Complete based on current command path
   case "\${cmd_path}" in
 ${caseBlocks.join("\n")}