akm-cli 0.9.31 → 0.10.261001-beta

package/dist/cli/shared.js

@@ -156,19 +156,8 @@ export const GLOBAL_OUTPUT_ARGS = {
     format: { type: "string", description: "Output format: json|jsonl|yaml|text|md|html (global flag)" },
     detail: {
         type: "string",
-        description: "Detail level (verbosity): brief|normal|full (global flag).",
-    },
-    // R-050(c): single-sourced with the root command's own `--shape` help
-    // (`main.args.shape` in src/cli.ts, which spreads this object) so the
-    // caveat is visible from every leaf's own `--help`, not only the top-level
-    // one. `summary` outside `show` falls back to `agent` with a warning
-    // (shapeForCommand in src/output/shapes.ts) — `--shape` is a global flag,
-    // so a script that passes it to a mixed batch of commands still works.
-    shape: {
-        type: "string",
-        description: "Output projection: human|agent|summary (global flag). 'agent' trims to agent-essential fields; " +
-            "'summary' only has a dedicated projection on 'akm show' — elsewhere it falls back to 'agent' with a " +
-            "warning. Default: human.",
+        description: "Detail level: brief|normal|full (verbosity), or agent (trims search, curate and show to agent-essential " +
+            "fields; other commands ignore it) (global flag).",
     },
     output: {
         type: "string",
@@ -294,51 +283,45 @@ export function outputWithExitCode(command, result, exitCode) {
 }
 export function output(command, result) {
     const mode = getOutputMode();
-    const shaped = shapeForCommand(command, result, mode.detail, mode.shape);
-    if (mode.format === "jsonl") {
-        outputJsonl(command, shaped);
+    const { format } = mode;
+    if (format === "jsonl") {
+        outputJsonl(command, shapeForCommand(command, result, mode.detail, mode.shape));
         return;
     }
+    deliverRendered(renderOutput(command, result, { ...mode, format }), mode.outputPath);
+}
+/**
+ * Shape and render a command result into the document `output()` delivers.
+ * Pure: reads no process-level output mode and writes nothing, so in-process
+ * callers (`src/api.ts`) get text byte-identical to the CLI's stdout from an
+ * explicit `mode`.
+ */
+export function renderOutput(command, result, mode) {
+    const shaped = shapeForCommand(command, result, mode.detail, mode.shape);
     switch (mode.format) {
         case "json":
-            deliverRendered(JSON.stringify(shaped, null, 2), mode.outputPath);
-            return;
+            return JSON.stringify(shaped, null, 2);
         case "yaml":
-            deliverRendered(yamlStringify(shaped), mode.outputPath);
-            return;
-        case "text": {
+            return yamlStringify(shaped);
+        case "text":
             // D7 — registry first, generic rendering of the shaped envelope second.
-            // Mirrors the md/html fallback immediately below: a command with no
-            // registered text formatter used to fall through to
+            // A command with no registered text formatter used to fall through to
             // `JSON.stringify(shaped, null, 2)`, i.e. silently hand back JSON while
-            // claiming `--format text` — the same "wrong format wearing the right
-            // flag" bug D7 already closed for md/html. `renderGenericText` (a
-            // DISTINCT function from `renderGenericMarkdown` — see its doc comment
-            // in src/output/generic-render.ts for why reusing the md renderer here
-            // was itself a version of the same bug) renders flat `key=value` text
-            // matching the house style already established by registered text
-            // formatters like `config list`.
-            const plain = formatPlain(command, shaped, mode.detail);
-            deliverRendered(plain ?? renderGenericText(command, shaped), mode.outputPath);
-            return;
-        }
-        case "md": {
-            // D7 — registry first, generic rendering of the shaped envelope second.
-            // No command emits JSON under `--format md` any more: silently handing
-            // back the wrong format was the worst of the three behaviours this
-            // replaced.
-            const rendered = getMdRendererHandler(command)?.(shaped, mode.detail);
-            deliverRendered(rendered ?? renderGenericMarkdown(command, shaped), mode.outputPath);
-            return;
-        }
-        case "html": {
+            // claiming `--format text`. `renderGenericText` renders flat
+            // `key=value` text matching the house style of registered formatters
+            // like `config list`; it is a DISTINCT function from
+            // `renderGenericMarkdown` (see src/output/generic-render.ts).
+            return formatPlain(command, shaped, mode.detail) ?? renderGenericText(command, shaped);
+        case "md":
+            // D7 — registry first, generic rendering second; no command emits JSON
+            // under `--format md`.
+            return getMdRendererHandler(command)?.(shaped, mode.detail) ?? renderGenericMarkdown(command, shaped);
+        case "html":
             // `akm health` and `akm metrics` are the only commands with a bespoke
             // HTML report, so they are called directly rather than through a
             // registry with two possible registrants (see `output/render-registry.ts`).
-            const rendered = command === "health" ? renderHealthHtml(shaped) : command === "metrics" ? renderMetricsHtml(shaped) : null;
-            deliverRendered(rendered ?? renderGenericHtml(command, shaped), mode.outputPath);
-            return;
-        }
+            return ((command === "health" ? renderHealthHtml(shaped) : command === "metrics" ? renderMetricsHtml(shaped) : null) ??
+                renderGenericHtml(command, shaped));
     }
 }
 // parseAllFlagValues moved to ./invocation (chunk-9 WI-9.9 argv-normalization

package/dist/cli/unknown-flags.js

@@ -28,7 +28,6 @@
 import { UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
 import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray, } from "./invocation.js";
-import { retiredFlagHint } from "./retired-commands.js";
 /**
  * Commands that must never refuse on an unrecognized flag — `akm info` warns
  * and continues instead of exiting 2, the same tolerance a bare `akm help
@@ -39,36 +38,6 @@ import { retiredFlagHint } from "./retired-commands.js";
 const UNKNOWN_FLAG_TOLERANT_COMMANDS = new Set(["info"]);
 /** Flags citty implements itself, which no command declares. */
 const IMPLICIT_FLAGS = ["help", "h", "version", "v"];
-/**
- * Retired flags whose commands still diagnose them THEMSELVES, with a message
- * that names the replacement ("`--scope` was removed, use `--filter`",
- * "`--source` was renamed to `--generator`"). A generic "unknown flag" would
- * preempt the better diagnosis, so these are passed through — but ONLY on the
- * command path that owns the diagnostic, keyed by the resolved path. On every
- * other command the same spelling is a genuine typo and still fails fast
- * A retired flag is rejected everywhere else, where silently dropping it could
- * run a real mutation.
- *
- * Shrink-only: when a command drops its bespoke diagnostic, drop the entry and
- * the generic error takes over.
- */
-const SELF_DIAGNOSED_FLAGS = new Map(Object.entries({
-    show: ["akmView", "scope"], // removed view grammar; --scope points at --filter
-    index: ["enrich", "re-enrich"], // removed index-time enrichment flags
-    "proposal accept": ["source"], // renamed to --generator
-    "proposal reject": ["source"], // renamed to --generator
-    "proposal drain": ["profile"], // retired, points at --strategy
-    search: ["source"], // renamed to --from
-    curate: ["source"], // renamed to --from
-    "task list": ["source"], // renamed to --from (alias of `search --type task`, #951)
-    remember: ["target"], // renamed to --bundle
-    clone: ["target"], // renamed to --bundle
-    improve: ["auto-accept", "target"], // retired in 0.9.0 / renamed to --bundle
-    "task add": ["target"], // renamed to --bundle
-    "task run": ["target"], // renamed to --bundle
-    "task history": ["target"], // renamed to --bundle
-    "task sync": ["target"], // renamed to --bundle
-}).map(([path, flags]) => [path, new Set(flags.map(cittyComparableName))]));
 /**
  * Union the arg definitions declared along the resolved command path. The
  * subcommand walk delegates to {@link findCittyTopLevelCommandIndex} — the
@@ -111,6 +80,12 @@ function collectKnownArgs(root, rawArgs) {
             break;
         const idx = findCittyTopLevelCommandIndex(args, (cmd.args ?? {}));
         const token = idx >= 0 ? args[idx] : undefined;
+        // A command that takes a positional AND has subcommands (`improve [scope]`
+        // beside `improve report`) is itself the target when the token is absent
+        // or names none of them.
+        const takesPositional = Object.values(cmd.args ?? {}).some((def) => def.type === "positional");
+        if (takesPositional && (token === undefined || !subCommands[token]))
+            break;
         // A group with no subcommand token: citty reports "no command specified".
         if (token === undefined)
             return { names, valueFlags, booleanFlags, displayNames, path, resolved: false };
@@ -166,15 +141,6 @@ export function closestMatch(attempted, candidates, threshold) {
  * @param attempted  The spelling to edit-distance against `--long` candidates.
  */
 function throwUnknownFlag(shown, attempted, known) {
-    // Flags the 0.9 overhaul removed outright get their retirement note, not a
-    // did-you-mean — same reasoning as `retiredCommandHint` in src/cli.ts:
-    // edit distance can point at an unrelated survivor rather than the real
-    // replacement procedure (e.g. `index --background` is closer to no other
-    // `index` flag than it is to any useful suggestion).
-    const retired = retiredFlagHint(known.path, attempted);
-    if (retired) {
-        throw new UsageError(`Unknown flag "${shown}".`, "UNKNOWN_FLAG", retired);
-    }
     const threshold = Math.max(2, Math.ceil(attempted.length / 3));
     const suggestion = closestMatch(attempted, known.displayNames, threshold);
     throw new UsageError(`Unknown flag "${shown}".`, "UNKNOWN_FLAG", suggestion
@@ -207,7 +173,6 @@ export function assertKnownFlags(root, rawArgs) {
     // scanner, so it needs the identical exemption).
     const dynamicNamedFlagCommands = new Set(["workflow run", "task run", "task explain"]);
     const dynamicWorkflowParams = dynamicNamedFlagCommands.has(known.path.join(" "));
-    const selfDiagnosed = SELF_DIAGNOSED_FLAGS.get(known.path.join(" "));
     const tolerant = UNKNOWN_FLAG_TOLERANT_COMMANDS.has(known.path.join(" "));
     for (let i = 0; i < ownArgs.length; i += 1) {
         const token = ownArgs[i];
@@ -250,8 +215,6 @@ export function assertKnownFlags(root, rawArgs) {
             ? rawName.slice(3)
             : undefined;
         const candidates = [cittyComparableName(rawName), ...(negated ? [cittyComparableName(negated)] : [])];
-        if (selfDiagnosed !== undefined && candidates.some((name) => selfDiagnosed.has(name)))
-            continue;
         if (!candidates.some((name) => known.names.has(name))) {
             // `workflow run` owns one deliberately dynamic namespace: long options
             // become exact-name workflow parameters and are checked against the

package/dist/cli.js

@@ -58,7 +58,6 @@ process.on("uncaughtException", (err) => {
 import fs from "node:fs";
 import { defineCommand, parseArgs, renderUsage, runCommand, showUsage } from "citty";
 import { findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
-import { retiredCommandHint } from "./cli/retired-commands.js";
 import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "./cli/shared.js";
 import { assertKnownFlags, closestMatch } from "./cli/unknown-flags.js";
 import { agentCommand, lintCommand } from "./commands/agent/contribute-cli.js";
@@ -137,7 +136,7 @@ function printSetupTtyHint(result) {
     if (!result?.bundleDir)
         return;
     console.error(plainize(`\n✓ Bundle created at ${result.bundleDir}\n` +
-        '  Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm help agents`'));
+        '  Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm hints`'));
 }
 /**
  * Module Naming:
@@ -264,7 +263,7 @@ const healthCommand = defineCommand({
     args: {
         // R-051: `health` 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
+        // `--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,
@@ -383,9 +382,6 @@ const healthCommand = defineCommand({
         }
     },
 });
-function loadAgentHints(full) {
-    return full ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
-}
 const hintsCommand = defineCommand({
     meta: {
         name: "hints",
@@ -401,7 +397,7 @@ const hintsCommand = defineCommand({
     run({ args }) {
         return runWithJsonErrors(() => {
             const detail = parseDetailLevel(args.detail) ?? "normal";
-            process.stdout.write(loadAgentHints(detail !== "brief"));
+            process.stdout.write(detail === "brief" ? EMBEDDED_HINTS : EMBEDDED_HINTS_FULL);
         });
     },
 });
@@ -504,24 +500,6 @@ const helpCommand = defineGroupCommand({
     },
     subCommands: {
         ...commandHelpTopics,
-        agents: defineCommand({
-            meta: {
-                name: "agents",
-                description: "Print agent instructions on how to use akm — the short guide by default; pass --full for the complete guide",
-            },
-            args: {
-                full: {
-                    type: "boolean",
-                    default: false,
-                    description: "Print the complete guide instead of the short one.",
-                },
-            },
-            run({ args }) {
-                return runWithJsonErrors(() => {
-                    process.stdout.write(loadAgentHints(args.full === true));
-                });
-            },
-        }),
         migrate: defineCommand({
             meta: {
                 name: "migrate",
@@ -855,7 +833,7 @@ function renderCommandSections() {
  * USAGE line + global OPTIONS, then cuts the string before citty's own
  * "COMMANDS" heading (present because `main` has `subCommands`) and appends
  * the grouped sections plus a one-line bundle/ref-grammar tagline and the
- * `akm help agents` pointer.
+ * `akm hints` pointer.
  */
 async function renderSectionedRootHelp() {
     const base = await renderUsage(main, undefined);
@@ -872,7 +850,7 @@ async function renderSectionedRootHelp() {
             "`akm search` output rather than synthesizing them.",
         "",
         "Run `akm help <command>` or `akm <command> --help` for details on any command.",
-        "Agents: run `akm hints` for the complete guide or `akm help agents` for the short guide.",
+        "Agents: run `akm hints` for the complete guide, or `akm hints --detail brief` for the short one.",
     ].join("\n");
     return [head, "", renderCommandSections(), "", epilogue].join("\n");
 }
@@ -910,7 +888,7 @@ function findUnknownCommandAttempt(rawArgs) {
 }
 /** Closest command within a length-scaled distance threshold (shared DP in cli/unknown-flags.ts). */
 function closestCommandMatch(attempted, candidates) {
-    return closestMatch(attempted, candidates, Math.max(2, Math.ceil(attempted.length / 2)));
+    return closestMatch(attempted, candidates, Math.floor(attempted.length / 3));
 }
 const CLI_HELP_POINTER = "Run `akm --help` for usage.";
 /**
@@ -944,12 +922,8 @@ function cittyCliErrorUsageCode(error) {
 function toUsageErrorFromCliError(error, rawArgs) {
     const code = cittyCliErrorUsageCode(error);
     const attempt = code === "UNKNOWN_COMMAND" ? findUnknownCommandAttempt(rawArgs) : undefined;
-    // Retired spellings from the 0.9 hard break get their replacement, not a
-    // did-you-mean: edit distance suggests the WRONG command for most of them
-    // (`init`→`info`, `update`→`upgrade`), and agents follow suggestions.
-    const retired = attempt ? retiredCommandHint(attempt.parentPath, attempt.attempted) : undefined;
-    const suggestion = retired === undefined && attempt ? closestCommandMatch(attempt.attempted, attempt.candidates) : undefined;
-    const hint = retired ?? (suggestion ? `Did you mean \`${suggestion}\`? ${CLI_HELP_POINTER}` : CLI_HELP_POINTER);
+    const suggestion = attempt ? closestCommandMatch(attempt.attempted, attempt.candidates) : undefined;
+    const hint = suggestion ? `Did you mean \`${suggestion}\`? ${CLI_HELP_POINTER}` : CLI_HELP_POINTER;
     // citty colorizes error.message with ANSI escapes even when stdout/stderr
     // is not a TTY. Strip them so the JSON envelope's `error` field is plain
     // text instead of embedding raw escape sequences.

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

@@ -112,7 +112,7 @@ export const lintCommand = defineCommand({
     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
+        // `--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,

package/dist/commands/completions.js

@@ -7,8 +7,7 @@ import path from "node:path";
 import { placementTypes } from "../core/asset/asset-placement.js";
 const FLAG_VALUES = {
     "--format": [{ values: ["json", "jsonl", "yaml", "text", "md", "html"] }],
-    "--detail": [{ values: ["brief", "normal", "full"] }],
-    "--shape": [{ values: ["human", "agent", "summary"] }],
+    "--detail": [{ values: ["brief", "normal", "full", "agent"] }],
     "--type": [{ values: () => [...placementTypes(), "any"] }],
     "--shell": [{ values: ["bash"] }],
     "--from": [{ paths: ["akm search", "akm curate"], values: ["local", "registry", "all"] }],

package/dist/commands/config-cli.js

@@ -14,11 +14,11 @@
  */
 import { isDeepStrictEqual } from "node:util";
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
-import { isRecord, resolveStashDir } from "../core/common.js";
+import { isRecord } from "../core/common.js";
 import { DEFAULT_CONFIG, getConfigValueSource, loadConfig, mutateConfig, parseAndValidateConfigText, resolveConfigRefSource, } 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";
+import { getConfigPath } from "../core/paths.js";
 import { formatRegistryUrl } from "../core/registry-url.js";
 // ── Public API ──────────────────────────────────────────────────────────────
 export function getConfigValue(config, key) {
@@ -118,32 +118,9 @@ export const configCommand = defineGroupCommand({
     meta: { name: "config", description: "Show and manage configuration" },
     subCommands: {
         path: defineJsonCommand({
-            meta: { name: "path", description: "Show paths to config, bundle, cache, and index" },
-            args: {
-                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();
-                    }
-                    catch {
-                        stashDir = `${getDefaultStashDir()} (not initialized)`;
-                    }
-                    const cacheDir = getCacheDir();
-                    const result = {
-                        config: configPath,
-                        bundle: stashDir,
-                        cache: cacheDir,
-                        index: getDbPath(),
-                    };
-                    output("config", result);
-                }
-                else {
-                    console.log(configPath);
-                }
+            meta: { name: "path", description: "Print the path to the config file" },
+            run() {
+                console.log(getConfigPath());
             },
         }),
         list: defineJsonCommand({

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

@@ -56,7 +56,7 @@ const envCreateCommand = defineJsonCommand({
             description: "Exclude this env file from env list output and the search index",
             default: false,
         },
-        target: {
+        bundle: {
             type: "string",
             description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
@@ -64,8 +64,8 @@ const envCreateCommand = defineJsonCommand({
     async run({ args }) {
         const { createEnv, writeEnv } = await import("./env.js");
         // `create` always targets env/, never the frozen vaults/ copy. `--path` is
-        // the subdirectory; `--target` selects the writable destination source.
-        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.name, args.target, {
+        // the subdirectory; `--bundle` selects the writable destination source.
+        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.name, args.bundle, {
             subPath: getStringArg(args, "path"),
         });
         const fromFile = args["from-file"];
@@ -304,13 +304,13 @@ const envRemoveCommand = defineJsonCommand({
     args: {
         ref: { type: "positional", description: "Env ref", required: true },
         yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
-        target: {
+        bundle: {
             type: "string",
             description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
     },
     async run({ args }) {
-        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.ref, args.target);
+        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.ref, args.bundle);
         const { confirmDestructive } = await import("../../cli/confirm.js");
         const confirmed = await confirmDestructive(`Remove env "${args.ref}"? This cannot be undone.`, {
             yes: args.yes === true,

package/dist/commands/env/secret-cli.js

@@ -108,14 +108,14 @@ const secretSetCommand = defineJsonCommand({
         },
         "from-file": { type: "string", description: "Read the value from this file (stored byte-exact)" },
         "from-env": { type: "string", description: "Read the value from the named environment variable" },
-        target: {
+        bundle: {
             type: "string",
             description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
     },
     async run({ args }) {
         const { setSecret } = await import("./secret.js");
-        const { name, absPath, target, ref } = resolveSecretWriteTarget(args.ref, args.target, {
+        const { name, absPath, target, ref } = resolveSecretWriteTarget(args.ref, args.bundle, {
             subPath: getStringArg(args, "path"),
         });
         const fromEnv = args["from-env"];