akm-cli 0.7.2 → 0.7.3

package/dist/setup/setup.js

@@ -5,6 +5,8 @@
  * registry selection, stash sources, and agent platform discovery.
  * Collects all choices and writes config once at the end.
  */
+import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { akmInit } from "../commands/init";
@@ -90,6 +92,114 @@ async function promptOrBack(fn) {
         return null;
     return result;
 }
+function configuredSourceKey(source) {
+    return `${source.type}:${source.path ?? source.url ?? source.name ?? "unknown"}`;
+}
+function describeConfiguredSource(source) {
+    const target = source.path ?? source.url ?? "(unknown target)";
+    const typeLabel = source.type === "git" ? "Git" : source.type === "filesystem" ? "Filesystem" : source.type;
+    return {
+        value: configuredSourceKey(source),
+        label: source.name ?? target,
+        hint: `${typeLabel}: ${target}`,
+    };
+}
+function renderConfiguredSourceList(sources) {
+    return sources
+        .map((source) => {
+        const described = describeConfiguredSource(source);
+        return `- ${described.label} (${described.hint})`;
+    })
+        .join("\n");
+}
+function renderInstalledSourceList(installed) {
+    return installed.map((entry) => `- ${entry.id} (${entry.source})`).join("\n");
+}
+function cloneLlmConfig(llm) {
+    if (!llm)
+        return undefined;
+    return {
+        ...llm,
+        ...(llm.capabilities ? { capabilities: { ...llm.capabilities } } : {}),
+        ...(llm.features ? { features: { ...llm.features } } : {}),
+        ...(llm.extraParams ? { extraParams: { ...llm.extraParams } } : {}),
+    };
+}
+async function stepAdditionalSources(currentSources) {
+    const sources = [...currentSources];
+    let addMore = true;
+    while (addMore) {
+        const action = await prompt(() => p.select({
+            message: "Add another stash source?",
+            options: [
+                { value: "done", label: "Done — no more sources" },
+                { value: "github-repo", label: "GitHub repository", hint: "custom URL" },
+                { value: "filesystem", label: "Filesystem path", hint: "local directory" },
+            ],
+            initialValue: "done",
+        }));
+        if (action === "done") {
+            addMore = false;
+            break;
+        }
+        if (action === "github-repo") {
+            const url = await promptOrBack(() => p.text({
+                message: "Enter the GitHub repository URL:",
+                placeholder: "https://github.com/owner/repo",
+                validate: (v) => {
+                    if (!v?.trim())
+                        return "URL cannot be empty";
+                },
+            }));
+            if (url === null)
+                continue;
+            const name = await promptOrBack(() => p.text({
+                message: "Give this stash a name (optional):",
+                placeholder: "my-repo",
+            }));
+            if (name === null)
+                continue;
+            const entry = { type: "git", url: url.trim() };
+            if (name.trim())
+                entry.name = name.trim();
+            if (!sources.some((s) => s.url === entry.url)) {
+                sources.push(entry);
+            }
+            else {
+                p.log.warn("This URL is already configured.");
+            }
+        }
+        if (action === "filesystem") {
+            const fsPath = await promptOrBack(() => p.text({
+                message: "Enter the directory path:",
+                placeholder: "/path/to/stash",
+                validate: (v) => {
+                    if (!v?.trim())
+                        return "Path cannot be empty";
+                },
+            }));
+            if (fsPath === null)
+                continue;
+            const resolved = fsPath.trim();
+            const name = await promptOrBack(() => p.text({
+                message: "Give this stash a name (optional):",
+                placeholder: "my-stash",
+            }));
+            if (name === null)
+                continue;
+            const entry = { type: "filesystem", path: resolved };
+            if (name.trim())
+                entry.name = name.trim();
+            if (!sources.some((s) => s.path === entry.path)) {
+                sources.push(entry);
+            }
+            else {
+                p.log.warn("This path is already configured.");
+            }
+        }
+    }
+    return sources;
+}
 /**
  * Quick connectivity check. Returns true if we can reach a public
  * endpoint within 3 seconds, false otherwise. Used to skip network-
@@ -196,8 +306,10 @@ async function prepareSemanticSearchAssets(config) {
     }
     spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedding model downloaded and ready.");
     let db;
+    let probeDir;
     try {
-        db = openDatabase();
+        probeDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-setup-vec-probe-"));
+        db = openDatabase(path.join(probeDir, "probe.db"), config.embedding?.dimension ? { embeddingDim: config.embedding.dimension } : undefined);
         if (isVecAvailable(db)) {
             p.log.info("sqlite-vec is available for fast vector search.");
         }
@@ -213,6 +325,14 @@ async function prepareSemanticSearchAssets(config) {
     finally {
         if (db)
             closeDatabase(db);
+        if (probeDir) {
+            try {
+                fs.rmSync(probeDir, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore cleanup failure */
+            }
+        }
     }
     return { ok: true };
 }
@@ -382,7 +502,7 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels) {
         initialValue,
     }));
     if (choice === "keep")
-        return current.llm;
+        return cloneLlmConfig(current.llm);
     if (choice === "none")
         return undefined;
     let llm;
@@ -514,10 +634,26 @@ export async function stepRegistries(current) {
 /**
  * @internal Exported for testing only.
  */
-export async function stepAddSources(current) {
-    const sources = [...(current.sources ?? current.stashes ?? [])];
-    if (sources.length > 0) {
-        p.log.info(`You have ${sources.length} existing stash source(s).`);
+export async function stepAddSources(current, options) {
+    const existingSources = [...(current.sources ?? current.stashes ?? [])];
+    const sources = [];
+    if (existingSources.length > 0) {
+        p.note(renderConfiguredSourceList(existingSources), "Configured stash sources");
+        const options = existingSources.map(describeConfiguredSource);
+        const selected = await prompt(() => p.multiselect({
+            message: "Configured stash sources — uncheck any you want to disable:",
+            options,
+            initialValues: options.map((option) => option.value),
+            required: false,
+        }));
+        for (const source of existingSources) {
+            if (selected.includes(configuredSourceKey(source))) {
+                sources.push(source);
+            }
+        }
+    }
+    if ((current.installed?.length ?? 0) > 0) {
+        p.note(renderInstalledSourceList(current.installed ?? []), "Installed managed stashes (preserved)");
     }
     // ── Recommended GitHub repos ───────────────────────────────────────────
     // Skip the prompt entirely when there are no recommendations to show.
@@ -558,78 +694,10 @@ export async function stepAddSources(current) {
             }
         }
     }
-    // ── Additional stash sources loop ──────────────────────────────────────
-    let addMore = true;
-    while (addMore) {
-        const action = await prompt(() => p.select({
-            message: "Add another stash source?",
-            options: [
-                { value: "github-repo", label: "GitHub repository", hint: "custom URL" },
-                { value: "filesystem", label: "Filesystem path", hint: "local directory" },
-                { value: "done", label: "Done — no more sources" },
-            ],
-        }));
-        if (action === "done") {
-            addMore = false;
-            break;
-        }
-        if (action === "github-repo") {
-            const url = await promptOrBack(() => p.text({
-                message: "Enter the GitHub repository URL:",
-                placeholder: "https://github.com/owner/repo",
-                validate: (v) => {
-                    if (!v?.trim())
-                        return "URL cannot be empty";
-                },
-            }));
-            if (url === null)
-                continue;
-            const name = await promptOrBack(() => p.text({
-                message: "Give this stash a name (optional):",
-                placeholder: "my-repo",
-            }));
-            if (name === null)
-                continue;
-            const entry = { type: "git", url: url.trim() };
-            if (name.trim())
-                entry.name = name.trim();
-            if (!sources.some((s) => s.url === entry.url)) {
-                sources.push(entry);
-            }
-            else {
-                p.log.warn("This URL is already configured.");
-            }
-        }
-        if (action === "filesystem") {
-            const fsPath = await promptOrBack(() => p.text({
-                message: "Enter the directory path:",
-                placeholder: "/path/to/stash",
-                validate: (v) => {
-                    if (!v?.trim())
-                        return "Path cannot be empty";
-                },
-            }));
-            if (fsPath === null)
-                continue;
-            const resolved = fsPath.trim();
-            const name = await promptOrBack(() => p.text({
-                message: "Give this stash a name (optional):",
-                placeholder: "my-stash",
-            }));
-            if (name === null)
-                continue;
-            const entry = { type: "filesystem", path: resolved };
-            if (name.trim())
-                entry.name = name.trim();
-            if (!sources.some((s) => s.path === entry.path)) {
-                sources.push(entry);
-            }
-            else {
-                p.log.warn("This path is already configured.");
-            }
-        }
+    if (options?.promptForAdditional === false) {
+        return sources;
     }
-    return sources;
+    return stepAdditionalSources(sources);
 }
 async function stepAgentPlatforms(current) {
     const platforms = detectAgentPlatforms();
@@ -637,7 +705,7 @@ async function stepAgentPlatforms(current) {
         p.log.info("No agent platform configurations detected.");
         return [];
     }
-    const existingPaths = new Set((current.stashes ?? []).map((s) => s.path));
+    const existingPaths = new Set((current.sources ?? current.stashes ?? []).map((s) => s.path));
     // Filter out platforms already configured
     const newPlatforms = platforms.filter((pl) => !existingPaths.has(pl.path));
     if (newPlatforms.length === 0) {
@@ -666,6 +734,60 @@ async function stepAgentPlatforms(current) {
     }
     return entries;
 }
+export async function stepAgentSelection(current, detections) {
+    const available = detections.filter((d) => d.available);
+    if (available.length === 0) {
+        return current.agent;
+    }
+    const initialValue = pickDefaultAgentProfile(detections, current.agent?.default) ?? available[0]?.name;
+    const selectedDefault = await prompt(() => p.select({
+        message: "Which detected agent CLI should be the default?",
+        options: [
+            ...available.map((d) => ({
+                value: d.name,
+                label: d.name,
+                hint: d.resolvedPath ?? d.bin,
+            })),
+            { value: "disabled", label: "Disabled", hint: "do not configure a default agent CLI" },
+        ],
+        initialValue,
+    }));
+    if (selectedDefault === "disabled") {
+        if (!current.agent?.profiles && !current.agent?.timeoutMs) {
+            return undefined;
+        }
+        return {
+            ...(current.agent ?? {}),
+            default: undefined,
+        };
+    }
+    return {
+        ...(current.agent ?? {}),
+        default: selectedDefault,
+    };
+}
+export async function stepOutputConfig(current) {
+    const defaultOutput = current.output ?? DEFAULT_CONFIG.output ?? { format: "json", detail: "brief" };
+    const format = await prompt(() => p.select({
+        message: "Default output format?",
+        options: [
+            { value: "json", label: "json", hint: "structured default" },
+            { value: "text", label: "text", hint: "human-readable CLI output" },
+            { value: "yaml", label: "yaml", hint: "structured text" },
+        ],
+        initialValue: defaultOutput.format ?? "json",
+    }));
+    const detail = await prompt(() => p.select({
+        message: "Default output detail level?",
+        options: [
+            { value: "brief", label: "brief", hint: "compact summaries" },
+            { value: "normal", label: "normal", hint: "balanced detail" },
+            { value: "full", label: "full", hint: "max available detail" },
+        ],
+        initialValue: defaultOutput.detail ?? "brief",
+    }));
+    return { format: format, detail: detail };
+}
 /**
  * Detect installed agent CLIs and produce an updated `agent` config block
  * with a sensible `default` (the first detected profile that the user has
@@ -761,20 +883,20 @@ export function buildSetupSteps(options) {
             id: "stash-sources",
             label: "Stash Sources",
             async run(ctx) {
-                const stashes = await stepAddSources(ctx.config);
-                const platforms = await stepAgentPlatforms(ctx.config);
+                const stashes = await stepAddSources(ctx.config, { promptForAdditional: false });
+                const platforms = await stepAgentPlatforms({ ...ctx.config, sources: stashes });
                 const merged = [...stashes];
                 for (const ps of platforms) {
                     if (!merged.some((s) => s.path === ps.path))
                         merged.push(ps);
                 }
-                ctx.apply({ sources: merged.length > 0 ? merged : undefined });
+                const withAdditional = await stepAdditionalSources(merged);
+                ctx.apply({ sources: withAdditional.length > 0 ? withAdditional : undefined });
             },
         },
         {
             id: "agent-cli",
             label: "Agent CLI",
-            nonInteractive: true,
             async run(ctx) {
                 const result = stepAgentCliDetection(ctx.config);
                 const detected = result.detections.filter((d) => d.available);
@@ -785,7 +907,16 @@ export function buildSetupSteps(options) {
                 else {
                     p.log.info("No agent CLIs detected on PATH. Agent commands will be disabled until one is installed and `akm setup` is re-run.");
                 }
-                ctx.apply({ agent: result.agent });
+                const agent = await stepAgentSelection({ ...ctx.config, agent: result.agent }, result.detections);
+                ctx.apply({ agent });
+            },
+        },
+        {
+            id: "output",
+            label: "Output Defaults",
+            async run(ctx) {
+                const output = await stepOutputConfig(ctx.config);
+                ctx.apply({ output });
             },
         },
     ];
@@ -821,7 +952,6 @@ export async function runSetupWizard() {
         ...ctx.config,
         // Preserve fields the steps don't manage explicitly.
         installed: current.installed,
-        output: current.output,
     };
     const semanticSearchMode = outcome.semantic;
     const stashDir = newConfig.stashDir ?? current.stashDir ?? getDefaultStashDir();
@@ -838,6 +968,8 @@ export async function runSetupWizard() {
         `Semantic search:  ${semanticSearchMode.mode}`,
         `Registries:       ${effectiveRegistries.filter((r) => r.enabled !== false).length} enabled`,
         `Stash sources:    ${allStashes.length}`,
+        `Agent default:    ${newConfig.agent?.default ?? "disabled"}`,
+        `Output:           ${newConfig.output?.format ?? "json"} / ${newConfig.output?.detail ?? "brief"}`,
     ].join("\n"), "Configuration Summary");
     const shouldSave = await prompt(() => p.confirm({
         message: "Save this configuration?",

package/dist/sources/providers/git.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { TYPE_DIRS } from "../../core/asset-spec";
 import { resolveStashDir } from "../../core/common";
 import { loadConfig } from "../../core/config";
 import { ConfigError, UsageError } from "../../core/errors";
@@ -123,7 +124,7 @@ async function ensureGitMirror(repo, cachePaths, options) {
  * shared registry-index cache (12h TTL) and exposes the working tree as the
  * stash content directory.
  */
-async function syncMirroredRepo(config, options) {
+export async function syncMirroredRepo(config, options) {
     if (!config.url) {
         throw new ConfigError("git stash entry requires a URL when no install ref is supplied");
     }
@@ -303,7 +304,18 @@ function pullRepo(repoDir) {
 }
 function hasExtractedRepo(repoDir) {
     try {
-        return fs.statSync(repoDir).isDirectory() && fs.statSync(path.join(repoDir, "content")).isDirectory();
+        if (!fs.statSync(repoDir).isDirectory())
+            return false;
+        if (fs.statSync(path.join(repoDir, "content")).isDirectory())
+            return true;
+    }
+    catch {
+        /* fall through to root-layout detection */
+    }
+    try {
+        if (!fs.statSync(repoDir).isDirectory())
+            return false;
+        return Object.values(TYPE_DIRS).some((dirName) => fs.existsSync(path.join(repoDir, dirName)));
     }
     catch {
         return false;

package/dist/wiki/wiki.js

@@ -894,7 +894,17 @@ export function regenerateWikiIndex(stashDir, name) {
             }
             lines.push("");
         }
-        fs.writeFileSync(path.join(wikiDir, INDEX_MD), lines.join("\n"), "utf8");
+        const next = `${lines.join("\n")}\n`;
+        const indexPath = path.join(wikiDir, INDEX_MD);
+        try {
+            const current = fs.readFileSync(indexPath, "utf8");
+            if (current === next)
+                return false;
+        }
+        catch {
+            /* missing file -> write below */
+        }
+        fs.writeFileSync(indexPath, next, "utf8");
         return true;
     }
     catch {

package/dist/workflows/parser.js

@@ -24,10 +24,25 @@ const SUBSECTION_COMPLETION_CRITERIA = "Completion Criteria";
  * the matcher and parser cannot drift.
  */
 export function looksLikeWorkflow(body) {
-    return (/^#\s+Workflow:\s+/m.test(body) &&
-        /^##\s+Step:\s+/m.test(body) &&
-        /^Step ID:\s+/m.test(body) &&
-        /^###\s+Instructions\s*$/m.test(body));
+    const structuralBody = stripFencedCodeBlocks(body);
+    return (/^#\s+Workflow:\s+/m.test(structuralBody) &&
+        /^##\s+Step:\s+/m.test(structuralBody) &&
+        /^Step ID:\s+/m.test(structuralBody) &&
+        /^###\s+Instructions\s*$/m.test(structuralBody));
+}
+function stripFencedCodeBlocks(body) {
+    let inFence = false;
+    const lines = body.split(/\r?\n/);
+    const stripped = [];
+    for (const line of lines) {
+        if (/^\s*```/.test(line) || /^\s*~~~/.test(line)) {
+            inFence = !inFence;
+            stripped.push("");
+            continue;
+        }
+        stripped.push(inFence ? "" : line);
+    }
+    return stripped.join("\n");
 }
 export function parseWorkflow(markdown, source) {
     const errors = [];

package/dist/workflows/runs.js

@@ -5,7 +5,7 @@ import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
 import { getDbPath } from "../core/paths";
-import { closeDatabase, openDatabase } from "../indexer/db";
+import { closeDatabase, openExistingDatabase } from "../indexer/db";
 import { resolveSourceEntries } from "../indexer/search-source";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve";
 import { resolveAssetPath } from "../sources/resolve";
@@ -264,7 +264,7 @@ function readWorkflowDocumentFromIndex(sourcePath, ref) {
     const dbPath = getDbPath();
     if (!fs.existsSync(dbPath))
         return null;
-    const db = openDatabase(dbPath);
+    const db = openExistingDatabase(dbPath);
     try {
         const parsed = parseAssetRef(ref);
         const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
@@ -315,7 +315,7 @@ function resolveWorkflowEntryId(sourcePath, ref) {
     const dbPath = getDbPath();
     if (!fs.existsSync(dbPath))
         return null;
-    const db = openDatabase(dbPath);
+    const db = openExistingDatabase(dbPath);
     try {
         const parsed = parseAssetRef(ref);
         const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;

package/docs/README.md

@@ -10,8 +10,8 @@
 
 ## Upgrading
 
-- [v1 migration guide](migration/v1.md) -- The path from 0.x to v1.0
-- [Release notes (latest: 0.7.0)](migration/release-notes/0.7.0.md) -- Per-release notes drop into `migration/release-notes/`
+- [v1 migration guide](migration/v1.md) -- The path from 0.x to v1.0, including the `.stash.json` removal scheduled for v0.8.0
+- [Release notes (latest: 0.7.0)](migration/release-notes/0.7.0.md) -- Per-release notes drop into `migration/release-notes/`, including current pre-release removals
 - [v0.5 → v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
 
 ## Reference
@@ -19,7 +19,7 @@
 - [CLI](cli.md) -- All `akm` commands and flags
 - [Registry](registry.md) -- Registries, search, hosting, and managing sources
 - [Configuration](configuration.md) -- Providers, settings, and Ollama setup
-- [Filesystem](technical/filesystem.md) -- Directory layout and `.stash.json` schema
+- [Filesystem](technical/filesystem.md) -- Directory layout plus `.stash.json` deprecation and migration notes
 
 ## Official Ecosystem Repositories
 

package/docs/migration/release-notes/0.7.0.md

@@ -17,6 +17,14 @@ If you are coming from 0.6.x, the
 canonical upgrade reference. This file is the executive summary of
 what's new in 0.7.0.
 
+For stash authors on the 0.7.x pre-release line: `.stash.json` remains supported
+for compatibility in this release, but it is deprecated and will be removed in
+v0.8.0. That timeline is intentional: during this aggressive pre-release
+phase-out window, compatibility shims do not stay around until 1.0 unless they
+still earn their cost. Prefer frontmatter for markdown assets and structured
+code comments for scripts, and migrate any remaining `.stash.json` metadata
+before taking the 0.8 upgrade.
+
 ## Major new surfaces in 0.7.0
 
 ### Proposal queue (`akm proposal *`) — new (#225, #226, #233)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -66,7 +66,7 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "3.8.1",
+    "@huggingface/transformers": "^4.2.0",
     "sqlite-vec": "0.1.7-alpha.2"
   },
   "engines": {