akm-cli 0.8.0-rc2 → 0.8.1

package/dist/llm/index-passes.js

@@ -1,35 +1,50 @@
+// 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 { getDefaultLlmConfig, getIndexPassConfig } from "../core/config";
 /**
- * Per-pass LLM config resolution for `akm index`.
- *
- * Locked v1 contract (#208):
- * - There is exactly one provider/model configuration: `akm.llm`.
- * - Every LLM-using pass inside `akm index` defaults to that block.
- * - A pass can be opted out individually with `index.<passName>.llm = false`.
- * - Any attempt to supply provider/model fields under `index.<passName>` is
- *   rejected at config-load time by `parseIndexConfig` in
- *   {@link ../core/config.ts} (`ConfigError("INVALID_CONFIG_FILE")`).
- *
- * Passes plug in by calling {@link resolveIndexPassLLM} with their pass
- * name (e.g. `"memory"` for #201's memory-inference pass, `"graph"` for
- * #207's graph-extraction pass). They do not read `config.llm` directly.
- * This keeps the config surface small and the wiring uniform.
- */
-/**
- * Resolve the {@link LlmConnectionConfig} a single index pass should use, or
- * `undefined` when the pass should run without an LLM.
- *
- * Returns `undefined` if any of:
- * - No top-level `akm.llm` block is configured.
- * - The pass is explicitly opted out (`index.<passName>.llm === false`).
- *
- * Otherwise returns the shared `akm.llm` config. There is no per-pass
- * provider override; that decision is locked by §9 of the v1 spec.
+ * Map a pass name (as used by callers — "memory", "graph", etc.) to the
+ * matching key under `profiles.improve.default.processes`. Pass names with
+ * no improve-profile counterpart return undefined and resolve via the
+ * default LLM only.
  */
+function improveProcessKeyForPass(passName) {
+    switch (passName) {
+        case "memory":
+            return "memoryInference";
+        case "graph":
+            return "graphExtraction";
+        default:
+            return undefined;
+    }
+}
 export function resolveIndexPassLLM(passName, config) {
-    if (!config.llm)
-        return undefined;
-    const passConfig = config.index?.[passName];
+    // Gate 1 — explicit opt-out via the index-config block stays authoritative.
+    const passConfig = getIndexPassConfig(config.index, passName);
     if (passConfig?.llm === false)
         return undefined;
-    return config.llm;
+    // Gate 2 — per-process profile from the improve profile, when present.
+    // This is the path that lets
+    //   profiles.improve.default.processes.graphExtraction.profile = "ministral-3b"
+    // actually take effect on the graph pass instead of being silently
+    // ignored.
+    const processKey = improveProcessKeyForPass(passName);
+    if (processKey) {
+        const processConfig = config.profiles?.improve?.default?.processes?.[processKey];
+        // Honor enabled === false here too — an explicit disable wins.
+        if (processConfig?.enabled === false)
+            return undefined;
+        const profileName = processConfig?.profile;
+        if (profileName) {
+            const profile = config.profiles?.llm?.[profileName];
+            if (profile)
+                return profile;
+            // A named-but-missing profile is a configuration error in spirit, but
+            // we fall through to default rather than throwing — callers gracefully
+            // treat `undefined` as "pass disabled" and emitting a hard throw here
+            // would take the whole improve run down on a typo.
+        }
+    }
+    // Gate 3 — fall back to the default LLM profile.
+    return getDefaultLlmConfig(config);
 }

package/dist/llm/memory-infer.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * LLM helper for the `akm index` memory-inference pass (#201).
  *
@@ -24,11 +27,35 @@ const MAX_BODY_CHARS = 4000;
 const SYSTEM_PROMPT = "You compress a developer memory into one high-signal derived memory for later retrieval. " +
     "Return only valid JSON. No prose outside the JSON object. No markdown fences.";
 const USER_PROMPT_PREFIX = `Compress the memory below into one derived memory. Output ONLY JSON:
-{"title":"string","description":"string","tags":["string"],"searchHints":["string"],"content":"string"}
-Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, max 3 sentences body, 3-8 tags, 3-6 searchHints.
+{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
+Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
 
 Memory:
 `;
+/**
+ * Strict JSON Schema for the derived-memory payload. Sent to providers that
+ * opt in via `LlmConnectionConfig.supportsJsonSchema = true`; the client
+ * silently drops the schema for providers that don't.
+ *
+ * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
+ * the memory-inference path. Mirrors the validation gate below
+ * (title/description/content + non-empty tags/searchHints) so a
+ * schema-compliant response is guaranteed to pass the downstream check
+ * — no more "incomplete derived memory payload from LLM; skipping memory"
+ * for shape-only failures.
+ */
+const DERIVED_MEMORY_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        content: { type: "string", minLength: 1 },
+        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
+        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
+    },
+    required: ["title", "description", "content", "tags", "searchHints"],
+    additionalProperties: false,
+};
 /**
  * Compress a single memory body into one derived memory via the configured LLM.
  *
@@ -53,6 +80,7 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
                 temperature: 0.1,
                 timeoutMs: llmConfig.timeoutMs,
                 signal,
+                responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
             });
             if (!raw)
                 return undefined;

package/dist/llm/metadata-enhance.js

@@ -1,10 +1,6 @@
-/**
- * LLM-driven metadata enhancement for stash entries.
- *
- * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
- * improve descriptions/tags/searchHints) lives separately from the low-level
- * transport client in `client.ts`.
- */
+// 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 { chatCompletion, parseJsonResponse } from "./client";
 import { tryLlmFeature } from "./feature-gate";
 const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;

package/dist/output/cli-hints.js

@@ -1,12 +1,15 @@
+// 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/.
 /**
  * Embedded "agent CLI hints" rendered by `akm hints` when no other source
  * is available.
  *
  * Extracted from `src/cli.ts` so it does not bloat the CLI module and so
  * docs/CI tooling can re-use the same constants. Two flavors:
- * `EMBEDDED_HINTS` (default reference, ~40 lines) and
- * `EMBEDDED_HINTS_FULL` (`--detail full`, ~250 lines).
+ * `EMBEDDED_HINTS` (`--detail brief`, short reference, ~40 lines) and
+ * `EMBEDDED_HINTS_FULL` (`--detail normal|full`, ~250 lines).
  */
-import EMBEDDED_HINTS_FULL from "./cli-hints-full.md" with { type: "text" };
-import EMBEDDED_HINTS from "./cli-hints-short.md" with { type: "text" };
+import EMBEDDED_HINTS_FULL from "../assets/hints/cli-hints-full.md" with { type: "text" };
+import EMBEDDED_HINTS from "../assets/hints/cli-hints-short.md" with { type: "text" };
 export { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL };

package/dist/output/context.js

@@ -1,7 +1,10 @@
+// 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/.
 /**
  * Process-level output mode singleton.
  *
- * Output mode (format + detail + forAgent) is parsed once at startup from
+ * Output mode (format + detail + shape) is parsed once at startup from
  * `process.argv` and the persisted user config. All subsequent `output()`
  * calls read from this in-memory singleton instead of re-scanning argv and
  * re-loading config on every call.
@@ -9,8 +12,9 @@
  * Initialized from `cli.ts` before `runMain`.
  */
 import { UsageError } from "../core/errors";
-export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl"];
-export const DETAIL_LEVELS = ["brief", "normal", "full", "summary", "agent"];
+export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md"];
+export const DETAIL_LEVELS = ["brief", "normal", "full"];
+export const SHAPE_MODES = ["human", "agent", "summary"];
 export function parseOutputFormat(value) {
     if (!value)
         return undefined;
@@ -25,6 +29,13 @@ export function parseDetailLevel(value) {
         return value;
     throw new UsageError(`Invalid value for --detail: ${value}. Expected one of: ${DETAIL_LEVELS.join("|")}`, "INVALID_DETAIL_VALUE");
 }
+export function parseShapeMode(value) {
+    if (!value)
+        return undefined;
+    if (SHAPE_MODES.includes(value))
+        return value;
+    throw new UsageError(`Invalid value for --shape: ${value}. Expected one of: ${SHAPE_MODES.join("|")}`, "INVALID_SHAPE_VALUE");
+}
 export function parseFlagValue(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -62,11 +73,52 @@ export function getHyphenatedBoolean(args, key) {
  */
 export function resolveOutputMode(argv, defaults = {}) {
     const format = parseOutputFormat(parseFlagValue(argv, "--format")) ?? defaults?.format ?? "json";
-    const detail = parseDetailLevel(parseFlagValue(argv, "--detail")) ?? defaults?.detail ?? "brief";
-    // `--detail=agent` is the preferred preset. `--for-agent` is kept for one
-    // release cycle as an alias so existing scripts and docs keep working.
-    const forAgent = detail === "agent" || hasBooleanFlag(argv, "--for-agent");
-    return { format, detail, forAgent };
+    const rawDetail = parseFlagValue(argv, "--detail");
+    const rawShape = parseFlagValue(argv, "--shape");
+    const usedForAgent = hasBooleanFlag(argv, "--for-agent");
+    // Back-compat: the projection presets `summary`/`agent` used to live on
+    // `--detail`. They moved to `--shape` in 0.8 (removed from `--detail` in
+    // 0.9.0). Map the legacy spellings onto `--shape` + warn, and treat the
+    // verbosity axis as `normal` (the prior effective behaviour).
+    let detailForVerbosity = rawDetail;
+    let shapeFromLegacyDetail;
+    if (rawDetail === "summary" || rawDetail === "agent") {
+        // Only nudge toward `--shape` when the caller did not already pass an
+        // explicit `--shape` (which wins below). Otherwise the "use --shape <x>"
+        // advice would name a projection the caller did not request.
+        if (rawShape === undefined)
+            emitDetailShapeDeprecation(rawDetail);
+        shapeFromLegacyDetail = rawDetail;
+        detailForVerbosity = "normal";
+    }
+    else if (rawDetail === "per-run") {
+        // Legacy `akm health --detail per-run` (→ `--group-by run`). The health
+        // command owns the back-compat warning + mapping; the global singleton must
+        // not reject the value here, so fall through to the default verbosity.
+        detailForVerbosity = undefined;
+    }
+    if (usedForAgent) {
+        emitForAgentDeprecation();
+    }
+    const detail = parseDetailLevel(detailForVerbosity) ?? defaults?.detail ?? "brief";
+    // Precedence: explicit `--shape` wins; then legacy `--detail summary|agent`;
+    // then legacy `--for-agent`; default `human`.
+    const shape = parseShapeMode(rawShape) ?? shapeFromLegacyDetail ?? (usedForAgent ? "agent" : "human");
+    return { format, detail, shape, forAgent: shape === "agent" };
+}
+/** Suppress deprecation warnings under `--quiet` (mirrors the rest of the CLI). */
+function isQuietArgv() {
+    return process.argv.includes("--quiet") || process.argv.includes("-q");
+}
+function emitDetailShapeDeprecation(value) {
+    if (isQuietArgv())
+        return;
+    process.stderr.write(`warning: '--detail ${value}' is deprecated; use '--shape ${value}'. Removed in 0.9.0.\n`);
+}
+function emitForAgentDeprecation() {
+    if (isQuietArgv())
+        return;
+    process.stderr.write("warning: '--for-agent' is deprecated; use '--shape agent'. Removed in 0.9.0.\n");
 }
 let _mode;
 /**