akm-cli 0.5.0 → 0.6.0-rc1

package/dist/llm.js

@@ -1,128 +1,16 @@
-import { fetchWithTimeout } from "./common";
-export async function chatCompletion(config, messages, options) {
-    const headers = { "Content-Type": "application/json" };
-    if (config.apiKey) {
-        headers.Authorization = `Bearer ${config.apiKey}`;
-    }
-    const response = await fetchWithTimeout(config.endpoint, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-            model: config.model,
-            messages,
-            temperature: options?.temperature ?? config.temperature ?? 0.3,
-            max_tokens: options?.maxTokens ?? config.maxTokens ?? 512,
-        }),
-    });
-    if (!response.ok) {
-        const body = await response.text().catch(() => "");
-        throw new Error(`LLM request failed (${response.status}): ${body}`);
-    }
-    const json = (await response.json());
-    return json.choices?.[0]?.message?.content?.trim() ?? "";
-}
-/** Strip leading/trailing markdown code fences from an LLM response. */
-function stripJsonFences(raw) {
-    return raw
-        .trim()
-        .replace(/^```(?:json)?\s*\n?/i, "")
-        .replace(/\n?```\s*$/i, "")
-        .trim();
-}
-/** Parse a possibly-fenced JSON response. Returns undefined if invalid. */
-export function parseJsonResponse(raw) {
-    try {
-        return JSON.parse(stripJsonFences(raw));
-    }
-    catch {
-        return undefined;
-    }
-}
-// ── Metadata Enhancement ────────────────────────────────────────────────────
-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.`;
 /**
- * Use an LLM to enhance a stash entry's metadata: improve description,
- * generate searchHints, and suggest tags.
+ * Backward-compatible facade for the LLM module.
+ *
+ * The implementation has been split into:
+ * - `./llm-client`     — transport (chatCompletion, parseJsonResponse,
+ *                       isLlmAvailable, probeLlmCapabilities, ChatMessage,
+ *                       ChatCompletionOptions, stripJsonFences)
+ * - `./metadata-enhance` — higher-level metadata enhancement workflow
+ *                          (enhanceMetadata)
+ *
+ * New code should import from those modules directly. This re-export barrel
+ * exists so existing call sites and tests that import from `./llm` keep
+ * working without modification.
  */
-export async function enhanceMetadata(config, entry, fileContent) {
-    const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
-    if (entry.description)
-        contextParts.push(`Current description: ${entry.description}`);
-    if (entry.tags?.length)
-        contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
-    if (fileContent) {
-        // Limit content to first 2000 chars to stay within token limits
-        const truncated = fileContent.length > 2000 ? `${fileContent.slice(0, 2000)}\n... (truncated)` : fileContent;
-        contextParts.push(`File content:\n${truncated}`);
-    }
-    const userPrompt = `${contextParts.join("\n")}
-
-Generate improved metadata for this ${entry.type}. Return JSON with these fields:
-- "description": a clear, concise one-sentence description of what this does
-- "searchHints": an array of 3-6 natural language task phrases an agent might use to find this (e.g. "deploy a docker container", "run database migrations")
-- "tags": an array of 3-8 relevant keyword tags
-
-Return ONLY the JSON object, no explanation.`;
-    const raw = await chatCompletion(config, [
-        { role: "system", content: SYSTEM_PROMPT },
-        { role: "user", content: userPrompt },
-    ]);
-    const parsed = parseJsonResponse(raw);
-    if (!parsed)
-        return {};
-    const result = {};
-    if (typeof parsed.description === "string" && parsed.description) {
-        result.description = parsed.description;
-    }
-    if (Array.isArray(parsed.searchHints)) {
-        result.searchHints = parsed.searchHints
-            .filter((s) => typeof s === "string" && s.trim().length > 0)
-            .slice(0, 8);
-    }
-    if (Array.isArray(parsed.tags)) {
-        result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
-    }
-    return result;
-}
-/**
- * Check if the LLM endpoint is reachable.
- */
-export async function isLlmAvailable(config) {
-    try {
-        const result = await chatCompletion(config, [{ role: "user", content: "Respond with just the word: ok" }]);
-        return result.length > 0;
-    }
-    catch {
-        return false;
-    }
-}
-// ── Capability probe ────────────────────────────────────────────────────────
-/**
- * Ask the model to emit a strict JSON object so we know whether the knowledge
- * wiki ingest/lint flows can rely on structured output. Failure is non-fatal —
- * the caller can fall back to assist-only mode.
- */
-export async function probeLlmCapabilities(config) {
-    try {
-        const raw = await chatCompletion(config, [
-            {
-                role: "system",
-                content: "You return only valid JSON. No prose, no markdown fences.",
-            },
-            {
-                role: "user",
-                content: 'Return exactly this JSON object and nothing else: {"ok": true, "ingest": true, "lint": true}',
-            },
-        ], { maxTokens: 64, temperature: 0 });
-        if (!raw)
-            return { reachable: false, structuredOutput: false, error: "empty response" };
-        const parsed = parseJsonResponse(raw);
-        return {
-            reachable: true,
-            structuredOutput: Boolean(parsed && parsed.ok === true),
-        };
-    }
-    catch (err) {
-        return { reachable: false, structuredOutput: false, error: err instanceof Error ? err.message : String(err) };
-    }
-}
+export * from "./llm-client";
+export { enhanceMetadata } from "./metadata-enhance";

package/dist/lockfile.js

@@ -2,8 +2,34 @@ import fs from "node:fs";
 import path from "node:path";
 import { getConfigDir } from "./config";
 // ── Paths ───────────────────────────────────────────────────────────────────
+const LOCKFILE_NAME = "akm.lock";
+const LEGACY_LOCKFILE_NAME = "stash.lock";
 function getLockfilePath() {
-    return path.join(getConfigDir(), "stash.lock");
+    return path.join(getConfigDir(), LOCKFILE_NAME);
+}
+function getLegacyLockfilePath() {
+    return path.join(getConfigDir(), LEGACY_LOCKFILE_NAME);
+}
+/**
+ * One-time migration: if the new `akm.lock` does not exist but the legacy
+ * `stash.lock` does, copy it across so installed-stash tracking survives the
+ * rename. Best-effort; failures are silent because the lockfile loader treats
+ * a missing file as an empty lockfile.
+ */
+function migrateLegacyLockfileIfNeeded() {
+    const newPath = getLockfilePath();
+    const legacyPath = getLegacyLockfilePath();
+    try {
+        if (fs.existsSync(newPath))
+            return;
+        if (!fs.existsSync(legacyPath))
+            return;
+        fs.mkdirSync(path.dirname(newPath), { recursive: true });
+        fs.copyFileSync(legacyPath, newPath);
+    }
+    catch {
+        /* best-effort — fall through to empty lockfile */
+    }
 }
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -74,6 +100,7 @@ function releaseLockSentinel() {
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
+    migrateLegacyLockfileIfNeeded();
     const lockfilePath = getLockfilePath();
     try {
         const raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));

package/dist/matchers.js

@@ -51,7 +51,7 @@ export function extensionMatcher(ctx) {
  * directory segment from the stash root matches a known type name.
  *
  * The first matching type-like ancestor wins. This preserves intuitive
- * behavior for nested kit layouts such as `agent-stash/agents/blog/foo.md`
+ * behavior for nested stash layouts such as `agent-stash/agents/blog/foo.md`
  * while still honoring earlier type roots like `commands/agents/foo.md`.
  */
 export function directoryMatcher(ctx) {

package/dist/metadata-enhance.js

@@ -0,0 +1,53 @@
+/**
+ * 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 `llm-client.ts`.
+ */
+import { chatCompletion, parseJsonResponse } from "./llm-client";
+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.`;
+/**
+ * Use an LLM to enhance a stash entry's metadata: improve description,
+ * generate searchHints, and suggest tags.
+ */
+export async function enhanceMetadata(config, entry, fileContent) {
+    const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
+    if (entry.description)
+        contextParts.push(`Current description: ${entry.description}`);
+    if (entry.tags?.length)
+        contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
+    if (fileContent) {
+        // Limit content to first 2000 chars to stay within token limits
+        const truncated = fileContent.length > 2000 ? `${fileContent.slice(0, 2000)}\n... (truncated)` : fileContent;
+        contextParts.push(`File content:\n${truncated}`);
+    }
+    const userPrompt = `${contextParts.join("\n")}
+
+Generate improved metadata for this ${entry.type}. Return JSON with these fields:
+- "description": a clear, concise one-sentence description of what this does
+- "searchHints": an array of 3-6 natural language task phrases an agent might use to find this (e.g. "deploy a docker container", "run database migrations")
+- "tags": an array of 3-8 relevant keyword tags
+
+Return ONLY the JSON object, no explanation.`;
+    const raw = await chatCompletion(config, [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: userPrompt },
+    ]);
+    const parsed = parseJsonResponse(raw);
+    if (!parsed)
+        return {};
+    const result = {};
+    if (typeof parsed.description === "string" && parsed.description) {
+        result.description = parsed.description;
+    }
+    if (Array.isArray(parsed.searchHints)) {
+        result.searchHints = parsed.searchHints
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .slice(0, 8);
+    }
+    if (Array.isArray(parsed.tags)) {
+        result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+    }
+    return result;
+}

package/dist/migration-help.js

@@ -1,40 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
 const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/CHANGELOG.md";
-const EMBEDDED_MIGRATION_GUIDES = {
-    "0.5.0": `Migration notes for akm v0.5.0
-
-- New top-level surfaces: \`akm wiki …\`, \`akm workflow …\`, \`akm vault …\`, and \`akm save\`.
-- If you tried the unreleased single-wiki LLM prototype, move to the new \`akm wiki …\` workflow.
-- Removed from the prototype surface: \`akm lint\`, \`akm import --llm\`, \`akm import --dry-run\`, \`knowledge.pageKinds\`, and the old ingest/lint LLM prompts.
-- Existing raw wiki-like content should be moved into \`wikis/<name>/raw/\` and then managed with the new wiki commands.
-`,
-    "0.3.0": `Migration notes for akm v0.3.0
-
-- The old \`stash\` and \`kit\` command groups were folded into the top-level CLI.
-- Use \`akm add\`, \`akm list\`, and \`akm remove\` instead of the older split command surfaces.
-- Documentation and examples from older releases should be updated to the unified source model.
-`,
-    "0.2.0": `Migration notes for akm v0.2.0
-
-- Asset refs are user-facing \`type:name\` values; do not rely on URI-style refs.
-- The old fixed asset-type union was replaced by an extensible asset type system.
-- \`tool\` assets were removed; use \`script\` assets instead.
-- Config and docs should treat remote provider scores and local scores as part of one shared search pipeline.
-`,
-    "0.1.0": `Migration notes for akm v0.1.0
-
-- The package and project were rebranded from Agent-i-Kit to akm.
-- Update package references from \`agent-i-kit\` to \`akm-cli\`.
-- Update config, registry, plugin, path, and environment-variable references from \`agent-i-kit\` / \`AGENT_I_KIT_*\` to \`akm\` / \`AKM_*\`.
-- The \`tool\` asset type and \`submit\` command were removed.
-`,
-    "0.0.13": `Migration notes for akm v0.0.13
-
-- Initial public release.
-- No migration steps are required for earlier akm versions.
-`,
-};
+const MIGRATION_DOC_URL = "https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md";
+/**
+ * Directory containing per-version release notes. Resolved relative to
+ * `import.meta.dir` so the lookup works whether this module is running
+ * from source (`<repo>/src`) or from the published build (`<pkg>/dist`).
+ * The `docs/migration/release-notes/` directory is shipped via the
+ * `files[]` array in `package.json`.
+ */
+function releaseNotesDir() {
+    return path.resolve(import.meta.dir, "../docs/migration/release-notes");
+}
 function loadChangelog() {
     try {
         const changelogPath = path.resolve(import.meta.dir, "../CHANGELOG.md");
@@ -43,12 +20,43 @@ function loadChangelog() {
         }
     }
     catch {
-        // fall through to embedded notes
+        // fall through to bundled notes
     }
     return undefined;
 }
-function escapeRegexString(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Load the bundled migration note for a specific version, if one exists.
+ * Returns the file body verbatim (no transformations). Missing files,
+ * permission errors, and non-file entries all return `undefined` —
+ * callers are responsible for the fallback message.
+ */
+function loadReleaseNote(version) {
+    if (!isSafeVersionComponent(version))
+        return undefined;
+    const notePath = path.join(releaseNotesDir(), `${version}.md`);
+    try {
+        if (!fs.existsSync(notePath))
+            return undefined;
+        const stat = fs.statSync(notePath);
+        if (!stat.isFile())
+            return undefined;
+        return fs.readFileSync(notePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Restrict version lookups to strings that are safe as a single path
+ * segment. Accepts typical semver forms (`0.6.0`, `0.6.0-rc1`,
+ * `0.6.0+build.5`) and rejects anything with slashes, `..`, or control
+ * characters that would let a crafted input escape the release-notes
+ * directory.
+ */
+function isSafeVersionComponent(version) {
+    if (!version || version.length > 64)
+        return false;
+    return /^[A-Za-z0-9._+-]+$/.test(version) && !version.includes("..");
 }
 function normalizeRequestedVersion(input) {
     const value = input.trim();
@@ -81,11 +89,18 @@ function extractChangelogSection(changelog, version) {
         return undefined;
     return `## [${version}]\n${match[1].trim()}\n`;
 }
+function escapeRegexString(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function fallbackGuide(version) {
-    const embedded = EMBEDDED_MIGRATION_GUIDES[version];
-    if (embedded)
-        return `${embedded.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
-    return `No dedicated migration note is bundled for akm v${version}.\n\nSee the full changelog: ${CHANGELOG_URL}\n`;
+    const bundled = loadReleaseNote(version);
+    if (bundled)
+        return `${bundled.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+    const available = listBundledReleaseVersions();
+    const availableLine = available.length ? `\nAvailable bundled notes: ${available.join(", ")}\n` : "";
+    return (`No dedicated migration note is bundled for akm v${version}.\n${availableLine}\n` +
+        `See the full changelog: ${CHANGELOG_URL}\n` +
+        `Longform migration guide: ${MIGRATION_DOC_URL}\n`);
 }
 export function renderMigrationHelp(versionInput, changelogText = loadChangelog()) {
     const requested = normalizeRequestedVersion(versionInput);
@@ -98,13 +113,29 @@ export function renderMigrationHelp(versionInput, changelogText = loadChangelog(
         for (const candidate of candidates) {
             const section = extractChangelogSection(changelogText, candidate);
             if (section) {
-                const embedded = EMBEDDED_MIGRATION_GUIDES[candidate];
-                if (!embedded)
+                const bundled = loadReleaseNote(candidate);
+                if (!bundled)
                     return `${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
-                return `${embedded.trim()}\n\nRelease notes\n-------------\n${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+                return `${bundled.trim()}\n\nRelease notes\n-------------\n${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
             }
         }
     }
     const fallbackVersion = candidates.find((candidate) => candidate !== "latest") ?? requested;
     return fallbackGuide(fallbackVersion);
 }
+/** Test-only helper — list every version with a bundled release note. */
+export function listBundledReleaseVersions() {
+    try {
+        const dir = releaseNotesDir();
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith(".md") && name !== "README.md")
+            .map((name) => name.slice(0, -".md".length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/output-context.js

@@ -0,0 +1,77 @@
+/**
+ * Process-level output mode singleton.
+ *
+ * Output mode (format + detail + forAgent) 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.
+ *
+ * Initialized from `cli.ts` before `runMain`.
+ */
+import { UsageError } from "./errors";
+export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl"];
+export const DETAIL_LEVELS = ["brief", "normal", "full", "summary", "agent"];
+export function parseOutputFormat(value) {
+    if (!value)
+        return undefined;
+    if (OUTPUT_FORMATS.includes(value))
+        return value;
+    throw new UsageError(`Invalid value for --format: ${value}. Expected one of: ${OUTPUT_FORMATS.join("|")}`);
+}
+export function parseDetailLevel(value) {
+    if (!value)
+        return undefined;
+    if (DETAIL_LEVELS.includes(value))
+        return value;
+    throw new UsageError(`Invalid value for --detail: ${value}. Expected one of: ${DETAIL_LEVELS.join("|")}`);
+}
+export function parseFlagValue(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === flag)
+            return argv[i + 1];
+        if (arg.startsWith(`${flag}=`))
+            return arg.slice(flag.length + 1);
+    }
+    return undefined;
+}
+export function hasBooleanFlag(argv, flag) {
+    return argv.some((arg) => arg === flag || arg === `${flag}=true`);
+}
+/**
+ * Resolve output mode from a synthetic argv array and config defaults.
+ * Pure function — no IO. Suitable for unit tests.
+ */
+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 };
+}
+let _mode;
+/**
+ * Initialize the process-level output mode. Must be called once at startup
+ * before any code calls `getOutputMode()`. Subsequent calls overwrite.
+ */
+export function initOutputMode(argv, defaults = {}) {
+    _mode = resolveOutputMode(argv, defaults);
+    return _mode;
+}
+/**
+ * Read the process-level output mode. Throws if `initOutputMode()` was not
+ * called first — that is a programmer error, not a runtime condition.
+ */
+export function getOutputMode() {
+    if (!_mode) {
+        throw new Error("OutputMode not initialized. Call initOutputMode() before getOutputMode().");
+    }
+    return _mode;
+}
+/**
+ * Reset the singleton. Test-only utility.
+ */
+export function resetOutputMode() {
+    _mode = undefined;
+}

package/dist/output-shapes.js

@@ -0,0 +1,198 @@
+/**
+ * Pure shaping functions that select and trim fields from command result
+ * objects according to the active detail level / agent mode.
+ *
+ * Every function in this module is side-effect free and operates on plain
+ * `Record<string, unknown>` shapes, which makes them trivial to unit test.
+ */
+const NORMAL_DESCRIPTION_LIMIT = 250;
+export function shapeForCommand(command, result, detail, forAgent = false) {
+    switch (command) {
+        case "search":
+            return shapeSearchOutput(result, detail, forAgent);
+        case "registry-search":
+            return shapeRegistrySearchOutput(result, detail);
+        case "show":
+            return shapeShowOutput(result, detail, forAgent);
+        default:
+            return result;
+    }
+}
+export function shapeSearchOutput(result, detail, forAgent = false) {
+    const hits = Array.isArray(result.hits) ? result.hits : [];
+    const registryHits = Array.isArray(result.registryHits) ? result.registryHits : [];
+    const shapedHits = forAgent
+        ? hits.map((hit) => shapeSearchHitForAgent(hit))
+        : hits.map((hit) => shapeSearchHit(hit, detail));
+    const shapedRegistryHits = forAgent
+        ? registryHits.map((hit) => shapeSearchHitForAgent(hit))
+        : registryHits.map((hit) => shapeSearchHit(hit, detail));
+    if (forAgent) {
+        return {
+            hits: shapedHits,
+            ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
+            ...(result.tip ? { tip: result.tip } : {}),
+        };
+    }
+    if (detail === "full") {
+        return {
+            schemaVersion: result.schemaVersion,
+            stashDir: result.stashDir,
+            source: result.source,
+            hits: shapedHits,
+            ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
+            ...(result.semanticSearch ? { semanticSearch: result.semanticSearch } : {}),
+            ...(result.tip ? { tip: result.tip } : {}),
+            ...(result.warnings ? { warnings: result.warnings } : {}),
+            ...(result.timing ? { timing: result.timing } : {}),
+        };
+    }
+    return {
+        hits: shapedHits,
+        ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
+        ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        ...(result.tip ? { tip: result.tip } : {}),
+    };
+}
+export function shapeRegistrySearchOutput(result, detail) {
+    const hits = Array.isArray(result.hits) ? result.hits : [];
+    const assetHits = Array.isArray(result.assetHits) ? result.assetHits : [];
+    // Shape stash hits as registry type
+    const shapedKitHits = hits.map((hit) => shapeSearchHit({ ...hit, type: "registry" }, detail));
+    // Shape asset hits by detail level
+    const shapedAssetHits = assetHits.map((hit) => shapeAssetHit(hit, detail));
+    const shaped = {
+        hits: shapedKitHits,
+        ...(shapedAssetHits.length > 0 ? { assetHits: shapedAssetHits } : {}),
+        ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+    };
+    if (detail === "full") {
+        shaped.query = result.query;
+    }
+    return shaped;
+}
+export function shapeAssetHit(hit, detail) {
+    if (detail === "brief")
+        return pickFields(hit, ["assetName", "assetType", "action", "estimatedTokens"]);
+    if (detail === "normal") {
+        return capDescription(pickFields(hit, ["assetName", "assetType", "description", "stash", "action", "estimatedTokens"]), NORMAL_DESCRIPTION_LIMIT);
+    }
+    return hit;
+}
+export function shapeSearchHit(hit, detail) {
+    if (hit.type === "registry") {
+        if (detail === "brief")
+            return pickFields(hit, ["name", "action"]);
+        if (detail === "normal") {
+            return capDescription(pickFields(hit, ["name", "description", "action", "curated"]), NORMAL_DESCRIPTION_LIMIT);
+        }
+        return hit;
+    }
+    // Stash hit (local or remote)
+    if (detail === "brief")
+        return pickFields(hit, ["type", "name", "action", "estimatedTokens"]);
+    if (detail === "normal") {
+        return capDescription(pickFields(hit, ["type", "name", "description", "action", "score", "estimatedTokens"]), NORMAL_DESCRIPTION_LIMIT);
+    }
+    return hit;
+}
+/** Agent-optimized search hit: only fields an LLM agent needs to decide and act */
+export function shapeSearchHitForAgent(hit) {
+    const picked = pickFields(hit, ["name", "ref", "type", "description", "action", "score", "estimatedTokens"]);
+    return capDescription(picked, NORMAL_DESCRIPTION_LIMIT);
+}
+export function capDescription(hit, limit) {
+    if (typeof hit.description !== "string")
+        return hit;
+    return { ...hit, description: truncateDescription(hit.description, limit) };
+}
+export function truncateDescription(description, limit) {
+    const normalized = description.replace(/\s+/g, " ").trim();
+    if (normalized.length <= limit)
+        return normalized;
+    const truncated = normalized.slice(0, limit - 1);
+    const lastSpace = truncated.lastIndexOf(" ");
+    const safe = lastSpace >= Math.floor(limit * 0.6) ? truncated.slice(0, lastSpace) : truncated;
+    return `${safe.trimEnd()}...`;
+}
+export function shapeShowOutput(result, detail, forAgent = false) {
+    if (forAgent) {
+        return pickFields(result, [
+            "type",
+            "name",
+            "description",
+            "action",
+            "content",
+            "template",
+            "prompt",
+            "run",
+            "setup",
+            "cwd",
+            "toolPolicy",
+            "modelHint",
+            "agent",
+            "parameters",
+            "workflowTitle",
+            "workflowParameters",
+            "steps",
+            "keys",
+            "comments",
+        ]);
+    }
+    if (detail === "summary") {
+        return pickFields(result, [
+            "type",
+            "name",
+            "description",
+            "tags",
+            "parameters",
+            "workflowTitle",
+            "action",
+            "run",
+            "origin",
+            "keys",
+            "comments",
+        ]);
+    }
+    const base = pickFields(result, [
+        "type",
+        "name",
+        "origin",
+        "action",
+        "description",
+        "tags",
+        "content",
+        "template",
+        "prompt",
+        "toolPolicy",
+        "modelHint",
+        "agent",
+        "parameters",
+        "workflowTitle",
+        "workflowParameters",
+        "steps",
+        "run",
+        "setup",
+        "cwd",
+        "keys",
+        "comments",
+    ]);
+    if (detail !== "full") {
+        return base;
+    }
+    return {
+        schemaVersion: 1,
+        ...base,
+        ...pickFields(result, ["path", "editable", "editHint"]),
+    };
+}
+export function pickFields(source, fields) {
+    const result = {};
+    for (const field of fields) {
+        if (source[field] !== undefined) {
+            result[field] = source[field];
+        }
+    }
+    return result;
+}
+export { NORMAL_DESCRIPTION_LIMIT };