akm-cli 0.4.1 → 0.5.0-rc2

package/dist/renderers.js

@@ -9,10 +9,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { hasErrnoCode } from "./common";
+import { UsageError } from "./errors";
 import { registerRenderer } from "./file-context";
 import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
 import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc } from "./markdown";
 import { extractDescriptionFromComments, loadStashFile } from "./metadata";
+import { makeAssetRef } from "./stash-ref";
+import { listKeys as listVaultKeys } from "./vault";
+import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
 // ── Interpreter auto-detection map ───────────────────────────────────────────
 const INTERPRETER_MAP = {
     ".sh": "bash",
@@ -149,6 +153,12 @@ function deriveName(ctx) {
     const ext = path.extname(ctx.relPath);
     return ext ? ctx.relPath.slice(0, -ext.length) : ctx.relPath;
 }
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function buildWorkflowAction(ref) {
+    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+}
 /**
  * Load the matching StashEntry for a file path from the directory's .stash.json.
  */
@@ -309,6 +319,85 @@ const knowledgeMdRenderer = {
         }
     },
 };
+// ── 4b. wiki-md ──────────────────────────────────────────────────────────────
+const WIKI_PAGE_ACTION = "Wiki page — read below. Use 'toc' to scan, 'section <heading>' for depth.";
+const wikiMdRenderer = {
+    name: "wiki-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const v = ctx.matchResult.meta?.view ?? { mode: "full" };
+        const content = ctx.content();
+        switch (v.mode) {
+            case "toc": {
+                const toc = parseMarkdownToc(content);
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: formatToc(toc),
+                };
+            }
+            case "frontmatter": {
+                const fm = extractFrontmatterOnly(content);
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: fm ?? "(no frontmatter)",
+                };
+            }
+            case "section": {
+                const section = extractSection(content, v.heading);
+                if (!section) {
+                    return {
+                        type: "wiki",
+                        name,
+                        path: ctx.absPath,
+                        action: WIKI_PAGE_ACTION,
+                        content: `Section "${v.heading}" not found in ${name}. Try \`akm show wiki:${name} toc\` to discover available headings.`,
+                    };
+                }
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: section.content,
+                };
+            }
+            case "lines": {
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: extractLineRange(content, v.start, v.end),
+                };
+            }
+            default: {
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content,
+                };
+            }
+        }
+    },
+    extractMetadata(entry, ctx) {
+        try {
+            const toc = parseMarkdownToc(ctx.content());
+            if (toc.headings.length > 0)
+                entry.toc = toc.headings;
+        }
+        catch {
+            // Non-fatal: skip TOC if file can't be read
+        }
+    },
+};
 // ── 5. memory-md ─────────────────────────────────────────────────────────────
 const memoryMdRenderer = {
     name: "memory-md",
@@ -323,7 +412,58 @@ const memoryMdRenderer = {
         };
     },
 };
-// ── 6. script-source ─────────────────────────────────────────────────────────
+// ── 6. workflow-md ───────────────────────────────────────────────────────────
+const workflowMdRenderer = {
+    name: "workflow-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const workflow = parseWorkflowForRendering(ctx.content());
+        const ref = makeAssetRef("workflow", name, ctx.origin);
+        return {
+            type: "workflow",
+            name,
+            path: ctx.absPath,
+            action: buildWorkflowAction(ref),
+            description: workflow.description,
+            workflowTitle: workflow.title,
+            parameters: workflow.parameters?.map((parameter) => parameter.name),
+            workflowParameters: workflow.parameters,
+            steps: workflow.steps,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        const workflow = parseWorkflowForRendering(ctx.content());
+        const hints = new Set(entry.searchHints ?? []);
+        hints.add(workflow.title);
+        for (const step of workflow.steps) {
+            hints.add(step.title);
+            hints.add(step.id);
+            hints.add(step.instructions);
+            for (const criterion of step.completionCriteria ?? []) {
+                hints.add(criterion);
+            }
+        }
+        entry.searchHints = Array.from(hints).filter(Boolean);
+        if (workflow.parameters?.length) {
+            entry.parameters = workflow.parameters.map((parameter) => ({
+                name: parameter.name,
+                ...(parameter.description ? { description: parameter.description } : {}),
+            }));
+        }
+    },
+};
+function parseWorkflowForRendering(content) {
+    try {
+        return parseWorkflowMarkdown(content);
+    }
+    catch (error) {
+        if (error instanceof WorkflowValidationError) {
+            throw new UsageError(error.message);
+        }
+        throw error;
+    }
+}
+// ── 7. script-source ─────────────────────────────────────────────────────────
 const scriptSourceRenderer = {
     name: "script-source",
     buildShowResponse(ctx) {
@@ -379,6 +519,43 @@ const scriptSourceRenderer = {
         }
     },
 };
+// ── 8. vault-env ─────────────────────────────────────────────────────────────
+/**
+ * Vault renderer. Returns ONLY key names and start-of-line comments — never
+ * values. Deliberately omits content/template/prompt so vault values cannot
+ * leak through `akm show`.
+ */
+const vaultEnvRenderer = {
+    name: "vault-env",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const { keys, comments } = listVaultKeys(ctx.absPath);
+        return {
+            type: "vault",
+            name,
+            path: ctx.absPath,
+            action: 'Vault — keys + comments only. Use `eval "$(akm vault load <ref>)"` to load values into the current shell. Values stay on disk and are never written to akm\'s stdout.',
+            description: comments.length > 0 ? comments.join("\n") : undefined,
+            keys,
+            comments,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        // Re-derive from the file directly to guarantee no value ever transits
+        // through any other code path. Caller already short-circuits in
+        // generateMetadata{,Flat}, but this is defense in depth.
+        const { keys, comments } = listVaultKeys(ctx.absPath);
+        if (comments.length > 0 && !entry.description) {
+            entry.description = comments.join(" ").slice(0, 500);
+            entry.source = "comments";
+            entry.confidence = 0.7;
+        }
+        if (keys.length > 0) {
+            entry.searchHints = keys;
+        }
+        entry.tags = Array.from(new Set([...(entry.tags ?? []), "vault", "secrets"]));
+    },
+};
 // ── Registration ─────────────────────────────────────────────────────────────
 /** All built-in renderers. */
 const builtinRenderers = [
@@ -386,8 +563,11 @@ const builtinRenderers = [
     commandMdRenderer,
     agentMdRenderer,
     knowledgeMdRenderer,
+    wikiMdRenderer,
     memoryMdRenderer,
+    workflowMdRenderer,
     scriptSourceRenderer,
+    vaultEnvRenderer,
 ];
 /**
  * Register all built-in renderers with the file-context registry.
@@ -399,4 +579,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, vaultEnvRenderer, wikiMdRenderer, workflowMdRenderer, };

package/dist/search-fields.js

@@ -41,6 +41,10 @@ export function buildSearchFields(entry) {
         if (entry.intent.output)
             hintParts.push(entry.intent.output);
     }
+    if (entry.xrefs)
+        hintParts.push(entry.xrefs.join(" "));
+    if (entry.pageKind)
+        hintParts.push(entry.pageKind);
     const hints = hintParts.join(" ").toLowerCase();
     const contentParts = [];
     if (entry.toc) {

package/dist/search-source.js

@@ -20,7 +20,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
     const config = existingConfig ?? loadConfig();
     const sources = [{ path: stashDir }];
     const seen = new Set([path.resolve(stashDir)]);
-    const addSource = (dir, registryId) => {
+    const addSource = (dir, registryId, wikiName) => {
         const resolved = path.resolve(dir);
         if (seen.has(resolved))
             return;
@@ -29,17 +29,21 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
         }
         if (isValidDirectory(dir)) {
-            sources.push({ path: resolved, ...(registryId ? { registryId } : {}) });
+            sources.push({
+                path: resolved,
+                ...(registryId ? { registryId } : {}),
+                ...(wikiName ? { wikiName } : {}),
+            });
         }
     };
     // Filesystem entries from stashes[]
     for (const entry of config.stashes ?? []) {
         if (entry.type === "filesystem" && entry.path && entry.enabled !== false) {
-            addSource(entry.path, entry.name);
+            addSource(entry.path, entry.name, entry.wikiName);
         }
     }
     // Git stash entries: resolve cache directory so the indexer can walk it.
-    // "context-hub", "github", and "git" provider types are handled.
+    // "git" provider type (and its legacy aliases "context-hub", "github") are handled.
     for (const entry of config.stashes ?? []) {
         if (GIT_STASH_TYPES.has(entry.type) && entry.url && entry.enabled !== false) {
             try {
@@ -48,7 +52,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
                 // The content/ subdirectory inside the extracted repo is the actual
                 // stash root containing DOC.md / SKILL.md files that the walker indexes.
                 const contentDir = path.join(cachePaths.repoDir, "content");
-                addSource(contentDir, entry.name);
+                addSource(contentDir, entry.name, entry.wikiName);
             }
             catch (err) {
                 warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
@@ -61,7 +65,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
         if (entry.type === "website" && entry.url && entry.enabled !== false) {
             try {
                 const cachePaths = getWebsiteCachePaths(entry.url);
-                addSource(cachePaths.stashDir, entry.name ?? entry.url);
+                addSource(cachePaths.stashDir, entry.name ?? entry.url, entry.wikiName);
             }
             catch (err) {
                 warn(`Warning: failed to resolve website stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
@@ -70,7 +74,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
     }
     // Installed kits (registry and local)
     for (const entry of config.installed ?? []) {
-        addSource(entry.stashRoot, entry.id);
+        addSource(entry.stashRoot, entry.id, entry.wikiName);
     }
     return sources;
 }
@@ -180,7 +184,7 @@ export async function ensureStashCaches(config) {
         try {
             const repo = parseGitRepoUrl(entry.url);
             const cachePaths = getCachePaths(repo.canonicalUrl);
-            await ensureGitMirror(repo, cachePaths, { requireRepoDir: true });
+            await ensureGitMirror(repo, cachePaths, { requireRepoDir: true, writable: entry.writable === true });
         }
         catch (err) {
             warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);

package/dist/self-update.js

@@ -1,9 +1,14 @@
+import * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, IS_WINDOWS } from "./common";
 import { githubHeaders } from "./github";
 const REPO = "itlackey/akm";
+const DEFAULT_PACKAGE_NAME = "akm-cli";
+const NODE_MODULES_SEGMENT = "/node_modules/";
+const BUN_GLOBAL_INSTALL_PATTERN = /(^|\/)\.bun\/(?:[^/]+\/)+node_modules\//;
+const PNPM_GLOBAL_INSTALL_PATTERN = /(^|\/)(?:pnpm\/global|\.pnpm-global)(?:\/\d+)?\/node_modules\//;
 /** Read live runtime signals. */
 export function getInstallSignals() {
     return {
@@ -15,8 +20,14 @@ export function getInstallSignals() {
 // AKM_VERSION ambient type is declared in globals.d.ts
 export function detectInstallMethod(signals) {
     const s = signals ?? getInstallSignals();
-    // npm/bun global install: import.meta.dir contains node_modules
-    if (s.importMetaDir?.includes("node_modules")) {
+    const normalizedImportMetaDir = normalizePathSeparators(s.importMetaDir);
+    if (normalizedImportMetaDir.includes(NODE_MODULES_SEGMENT)) {
+        if (BUN_GLOBAL_INSTALL_PATTERN.test(normalizedImportMetaDir)) {
+            return "bun";
+        }
+        if (PNPM_GLOBAL_INSTALL_PATTERN.test(normalizedImportMetaDir)) {
+            return "pnpm";
+        }
         return "npm";
     }
     // Bun-compiled binaries: Bun.main points to a virtual /$bunfs/ path,
@@ -69,34 +80,51 @@ export async function checkForUpdate(currentVersion) {
 export async function performUpgrade(check, opts) {
     const { currentVersion, latestVersion, installMethod } = check;
     const force = opts?.force === true;
-    if (installMethod === "npm") {
+    // All install methods can short-circuit here unless the user explicitly forces an upgrade.
+    if (!check.updateAvailable && !force) {
         return {
             currentVersion,
             newVersion: latestVersion,
             upgraded: false,
             installMethod,
-            message: `akm installed via npm. Run: bun install -g akm-cli@latest`,
+            message: `akm v${currentVersion} is already the latest version`,
         };
     }
-    if (installMethod === "unknown") {
+    const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod);
+    if (packageManagerCommand) {
+        if (!latestVersion) {
+            throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
+        }
+        const result = childProcess.spawnSync(packageManagerCommand.command, packageManagerCommand.args, {
+            encoding: "utf8",
+            env: process.env,
+            stdio: "pipe",
+        });
+        if (result.error) {
+            throw new Error(`Failed to run '${packageManagerCommand.displayCommand}': ${result.error.message}`);
+        }
+        if (result.status !== 0) {
+            const details = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
+            throw new Error(`Failed to upgrade akm via ${installMethod}: ${details}\nRun manually: ${packageManagerCommand.displayCommand}`);
+        }
         return {
             currentVersion,
             newVersion: latestVersion,
-            upgraded: false,
+            upgraded: true,
             installMethod,
-            message: `Unable to detect install method. Upgrade manually from https://github.com/${REPO}/releases`,
+            message: `akm upgraded via ${installMethod}`,
         };
     }
-    // Binary install
-    if (!check.updateAvailable && !force) {
+    if (installMethod === "unknown") {
         return {
             currentVersion,
             newVersion: latestVersion,
             upgraded: false,
             installMethod,
-            message: `akm v${currentVersion} is already the latest version`,
+            message: `Unable to detect install method. Upgrade manually from https://github.com/${REPO}/releases`,
         };
     }
+    // Binary install
     if (!latestVersion) {
         throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
     }
@@ -270,3 +298,51 @@ function parseChecksumForFile(checksumsText, filename) {
     }
     return undefined;
 }
+function normalizePathSeparators(value) {
+    return (value ?? "").replaceAll("\\", "/");
+}
+function getInstalledPackageName() {
+    try {
+        const pkgPath = path.resolve(import.meta.dir ?? __dirname, "../package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.name === "string" && pkg.name.trim()) {
+                return pkg.name.trim();
+            }
+        }
+    }
+    catch {
+        // Swallow and fall back to default package name.
+    }
+    return DEFAULT_PACKAGE_NAME;
+}
+function resolveNodePackageManagerCommand(name) {
+    const extension = IS_WINDOWS ? ".cmd" : "";
+    const adjacent = path.join(path.dirname(process.execPath), `${name}${extension}`);
+    return fs.existsSync(adjacent) ? adjacent : name;
+}
+export function getPackageManagerUpgradeCommand(installMethod, packageName = getInstalledPackageName()) {
+    const pkgRef = `${packageName}@latest`;
+    if (installMethod === "bun") {
+        return {
+            command: "bun",
+            args: ["install", "-g", pkgRef],
+            displayCommand: `bun install -g ${pkgRef}`,
+        };
+    }
+    if (installMethod === "pnpm") {
+        return {
+            command: resolveNodePackageManagerCommand("pnpm"),
+            args: ["add", "-g", pkgRef],
+            displayCommand: `pnpm add -g ${pkgRef}`,
+        };
+    }
+    if (installMethod === "npm") {
+        return {
+            command: resolveNodePackageManagerCommand("npm"),
+            args: ["install", "-g", pkgRef],
+            displayCommand: `npm install -g ${pkgRef}`,
+        };
+    }
+    return undefined;
+}