akm-cli 0.0.0 → 0.0.17

package/dist/renderers.js

@@ -0,0 +1,386 @@
+/**
+ * Built-in asset renderers.
+ *
+ * Each renderer implements the show/search/metadata behavior for its asset
+ * type via the AssetRenderer interface from ./file-context. Renderers are
+ * registered at module-load time so that importing this module is sufficient
+ * to make them available.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { hasErrnoCode } from "./common";
+import { registerRenderer } from "./file-context";
+import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
+import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc } from "./markdown";
+import { extractDescriptionFromComments, loadStashFile } from "./metadata";
+// ── Interpreter auto-detection map ───────────────────────────────────────────
+const INTERPRETER_MAP = {
+    ".sh": "bash",
+    ".ts": "bun",
+    ".js": "bun",
+    ".py": "python",
+    ".rb": "ruby",
+    ".go": "go run",
+    ".ps1": "powershell -File",
+    ".cmd": "cmd /c",
+    ".bat": "cmd /c",
+    ".pl": "perl",
+    ".php": "php",
+    ".lua": "lua",
+    ".r": "Rscript",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+};
+// ── Setup signal map ─────────────────────────────────────────────────────────
+const SETUP_SIGNALS = {
+    "package.json": "bun install",
+    "requirements.txt": "pip install -r requirements.txt",
+    Gemfile: "bundle install",
+    "go.mod": "go mod download",
+};
+// ── Comment tag extraction ───────────────────────────────────────────────────
+/**
+ * Extract `@run`, `@setup`, `@cwd` tags from script file header comments.
+ *
+ * Scans the first 50 lines of the file for comment lines containing
+ * `@run <value>`, `@setup <value>`, or `@cwd <value>`.
+ */
+export function extractCommentTags(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return {};
+    }
+    const lines = content.split(/\r?\n/).slice(0, 50);
+    const hints = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Match lines starting with comment markers: //, #, /*, *, ;, --
+        if (!/^(?:\/\/|#|\/?\*|;|--)/.test(trimmed) && !trimmed.startsWith("'"))
+            continue;
+        // Strip comment prefix
+        const cleaned = trimmed
+            .replace(/^(?:\/\/|##?|\/?\*\*?\/?|;|--)\s*/, "")
+            .replace(/\*\/\s*$/, "")
+            .trim();
+        const runMatch = cleaned.match(/^@run\s+(.+)/);
+        if (runMatch)
+            hints.run = runMatch[1].trim();
+        const setupMatch = cleaned.match(/^@setup\s+(.+)/);
+        if (setupMatch)
+            hints.setup = setupMatch[1].trim();
+        const cwdMatch = cleaned.match(/^@cwd\s+(.+)/);
+        if (cwdMatch)
+            hints.cwd = cwdMatch[1].trim();
+    }
+    return hints;
+}
+// ── Auto-detection ───────────────────────────────────────────────────────────
+/**
+ * Auto-detect execution hints from the file extension and nearby files.
+ *
+ * 1. Maps the file extension to an interpreter via INTERPRETER_MAP.
+ * 2. Scans the file's directory for dependency signal files (package.json,
+ *    requirements.txt, etc.) to suggest a setup command.
+ */
+export function detectExecHints(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const hints = {};
+    // Interpreter from extension
+    const interpreter = INTERPRETER_MAP[ext];
+    if (interpreter) {
+        hints.run = `${interpreter} ${filePath}`;
+    }
+    // Setup from nearby dependency files
+    const dir = path.dirname(filePath);
+    try {
+        for (const [file, cmd] of Object.entries(SETUP_SIGNALS)) {
+            if (fs.existsSync(path.join(dir, file))) {
+                hints.setup = cmd;
+                hints.cwd = dir;
+                break;
+            }
+        }
+    }
+    catch {
+        // Non-fatal: skip setup detection on FS errors
+    }
+    return hints;
+}
+// ── Resolution ───────────────────────────────────────────────────────────────
+/**
+ * Resolve execution hints for a script asset.
+ *
+ * Resolution order (first non-empty value wins for each field):
+ * 1. `.stash.json` fields (`run`/`setup`/`cwd`) take priority
+ * 2. Script file header comments (`@run`/`@setup`/`@cwd`) second
+ * 3. Auto-detection from extension + dependency files last
+ */
+export function resolveExecHints(stashEntry, filePath) {
+    const stashHints = {
+        run: stashEntry?.run,
+        setup: stashEntry?.setup,
+        cwd: stashEntry?.cwd,
+    };
+    const commentHints = extractCommentTags(filePath);
+    const autoHints = detectExecHints(filePath);
+    return {
+        run: stashHints.run || commentHints.run || autoHints.run,
+        setup: stashHints.setup || commentHints.setup || autoHints.setup,
+        cwd: stashHints.cwd || commentHints.cwd || autoHints.cwd,
+    };
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Derive a display name from the RenderContext.
+ *
+ * Prefers `matchResult.meta.name` when present; otherwise falls back to the
+ * POSIX-style relative path stripped of its extension.
+ */
+function deriveName(ctx) {
+    const metaName = ctx.matchResult.meta?.name;
+    if (typeof metaName === "string" && metaName)
+        return metaName;
+    // Strip the extension from the relPath for a reasonable fallback.
+    const ext = path.extname(ctx.relPath);
+    return ext ? ctx.relPath.slice(0, -ext.length) : ctx.relPath;
+}
+/**
+ * Load the matching StashEntry for a file path from the directory's .stash.json.
+ */
+function findStashEntryForFile(filePath) {
+    const dir = path.dirname(filePath);
+    const stashFile = loadStashFile(dir);
+    if (!stashFile)
+        return undefined;
+    const fileName = path.basename(filePath);
+    return stashFile.entries.find((e) => e.filename === fileName);
+}
+function extractParameters(template) {
+    const parameters = [];
+    if (/\$ARGUMENTS\b/i.test(template)) {
+        parameters.push("ARGUMENTS");
+    }
+    for (const match of template.matchAll(/\$([1-9])/g)) {
+        const parameter = `$${match[1]}`;
+        if (!parameters.includes(parameter)) {
+            parameters.push(parameter);
+        }
+    }
+    for (const match of template.matchAll(/\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g)) {
+        const parameter = match[1];
+        if (!parameters.includes(parameter)) {
+            parameters.push(parameter);
+        }
+    }
+    return parameters.length > 0 ? parameters : undefined;
+}
+// ── 1. skill-md ──────────────────────────────────────────────────────────────
+const skillMdRenderer = {
+    name: "skill-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        return {
+            type: "skill",
+            name,
+            path: ctx.absPath,
+            action: "Read and follow the instructions below",
+            content: ctx.content(),
+        };
+    },
+};
+// ── 2. command-md ────────────────────────────────────────────────────────────
+const commandMdRenderer = {
+    name: "command-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsedMd = parseFrontmatter(ctx.content());
+        const template = parsedMd.content;
+        return {
+            type: "command",
+            name,
+            path: ctx.absPath,
+            action: "Fill $ARGUMENTS placeholders in the template, then dispatch",
+            description: toStringOrUndefined(parsedMd.data.description),
+            template,
+            modelHint: parsedMd.data.model,
+            agent: toStringOrUndefined(parsedMd.data.agent),
+            parameters: extractParameters(template),
+        };
+    },
+};
+// ── 3. agent-md ──────────────────────────────────────────────────────────────
+const agentMdRenderer = {
+    name: "agent-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsedMd = parseFrontmatter(ctx.content());
+        return {
+            type: "agent",
+            name,
+            path: ctx.absPath,
+            action: "Dispatch using the prompt below verbatim. Use modelHint and toolPolicy if present.",
+            description: toStringOrUndefined(parsedMd.data.description),
+            prompt: parsedMd.content,
+            toolPolicy: parsedMd.data.tools,
+            modelHint: parsedMd.data.model,
+        };
+    },
+};
+// ── 4. knowledge-md ──────────────────────────────────────────────────────────
+const knowledgeMdRenderer = {
+    name: "knowledge-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: "knowledge",
+                    name,
+                    path: ctx.absPath,
+                    action: "Reference material - read the content below. Use 'toc' view for large documents.",
+                    content: formatToc(toc),
+                };
+            }
+            case "frontmatter": {
+                const fm = extractFrontmatterOnly(content);
+                return {
+                    type: "knowledge",
+                    name,
+                    path: ctx.absPath,
+                    action: "Reference material - read the content below. Use 'toc' view for large documents.",
+                    content: fm ?? "(no frontmatter)",
+                };
+            }
+            case "section": {
+                const section = extractSection(content, v.heading);
+                if (!section) {
+                    return {
+                        type: "knowledge",
+                        name,
+                        path: ctx.absPath,
+                        action: "Reference material - read the content below. Use 'toc' view for large documents.",
+                        content: `Section "${v.heading}" not found in ${name}. Try \`akm show <ref> toc\` to discover available headings.`,
+                    };
+                }
+                return {
+                    type: "knowledge",
+                    name,
+                    path: ctx.absPath,
+                    action: "Reference material - read the content below. Use 'toc' view for large documents.",
+                    content: section.content,
+                };
+            }
+            case "lines": {
+                return {
+                    type: "knowledge",
+                    name,
+                    path: ctx.absPath,
+                    action: "Reference material - read the content below. Use 'toc' view for large documents.",
+                    content: extractLineRange(content, v.start, v.end),
+                };
+            }
+            default: {
+                return {
+                    type: "knowledge",
+                    name,
+                    path: ctx.absPath,
+                    action: "Reference material - read the content below. Use 'toc' view for large documents.",
+                    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. script-source ─────────────────────────────────────────────────────────
+const scriptSourceRenderer = {
+    name: "script-source",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const ext = path.extname(ctx.absPath).toLowerCase();
+        // For extensions with a known interpreter, show exec hints
+        if (INTERPRETER_MAP[ext]) {
+            const stashEntry = findStashEntryForFile(ctx.absPath);
+            const hints = resolveExecHints(stashEntry, ctx.absPath);
+            if (hints.run) {
+                return {
+                    type: "script",
+                    name,
+                    path: ctx.absPath,
+                    action: "Execute the run command below",
+                    run: hints.run,
+                    setup: hints.setup,
+                    cwd: hints.cwd,
+                };
+            }
+        }
+        // For other extensions or when no hints are available, show file content
+        return {
+            type: "script",
+            name,
+            path: ctx.absPath,
+            action: "Review the script source below",
+            content: ctx.content(),
+        };
+    },
+    enrichSearchHit(hit, _stashDir) {
+        const ext = path.extname(hit.path).toLowerCase();
+        if (!INTERPRETER_MAP[ext])
+            return;
+        try {
+            const stashEntry = findStashEntryForFile(hit.path);
+            const hints = resolveExecHints(stashEntry, hit.path);
+            hit.run = hints.run;
+        }
+        catch (error) {
+            if (!hasErrnoCode(error, "ENOENT"))
+                throw error;
+        }
+    },
+    extractMetadata(entry, ctx) {
+        if (ctx.ext !== ".md") {
+            const commentDesc = extractDescriptionFromComments(ctx.absPath);
+            if (commentDesc && !entry.description) {
+                entry.description = commentDesc;
+                entry.source = "comments";
+                entry.confidence = 0.7;
+            }
+        }
+    },
+};
+// ── Registration ─────────────────────────────────────────────────────────────
+/** All built-in renderers. */
+const builtinRenderers = [
+    skillMdRenderer,
+    commandMdRenderer,
+    agentMdRenderer,
+    knowledgeMdRenderer,
+    scriptSourceRenderer,
+];
+/**
+ * Register all built-in renderers with the file-context registry.
+ * Called once from the CLI entry point (or ensureBuiltinsRegistered).
+ */
+export function registerBuiltinRenderers() {
+    for (const renderer of builtinRenderers) {
+        registerRenderer(renderer);
+    }
+}
+// ── Named exports for testing ────────────────────────────────────────────────
+export { skillMdRenderer, commandMdRenderer, agentMdRenderer, knowledgeMdRenderer, scriptSourceRenderer, INTERPRETER_MAP, SETUP_SIGNALS, };

package/dist/ripgrep-install.js

@@ -0,0 +1,155 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { IS_WINDOWS } from "./common";
+import { RG_BINARY, resolveRg } from "./ripgrep-resolve";
+/**
+ * Platform and architecture detection for ripgrep binary downloads.
+ */
+function getRgPlatformTarget() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "linux" && arch === "x64") {
+        return { platform: "x86_64-unknown-linux-musl", arch: "x64", ext: ".tar.gz" };
+    }
+    if (platform === "linux" && arch === "arm64") {
+        return { platform: "aarch64-unknown-linux-gnu", arch: "arm64", ext: ".tar.gz" };
+    }
+    if (platform === "darwin" && arch === "x64") {
+        return { platform: "x86_64-apple-darwin", arch: "x64", ext: ".tar.gz" };
+    }
+    if (platform === "darwin" && arch === "arm64") {
+        return { platform: "aarch64-apple-darwin", arch: "arm64", ext: ".tar.gz" };
+    }
+    if (platform === "win32" && arch === "x64") {
+        return { platform: "x86_64-pc-windows-msvc", arch: "x64", ext: ".zip" };
+    }
+    return null;
+}
+const RG_VERSION = "14.1.1";
+/**
+ * Ensure ripgrep is available. If not found on PATH or in the given binDir,
+ * download and install it to binDir.
+ *
+ * @param binDir - Directory to install ripgrep into (e.g. cache/bin from paths.ts)
+ * Returns the path to the ripgrep binary and whether it was newly installed.
+ */
+export function ensureRg(binDir) {
+    // Already available?
+    const existing = resolveRg(binDir);
+    if (existing) {
+        return { rgPath: existing, installed: false, version: getRgVersion(existing) };
+    }
+    // Determine platform
+    const target = getRgPlatformTarget();
+    if (!target) {
+        throw new Error(`Unsupported platform for ripgrep auto-install: ${process.platform}/${process.arch}. ` +
+            `Install ripgrep manually: https://github.com/BurntSushi/ripgrep#installation`);
+    }
+    if (!fs.existsSync(binDir)) {
+        fs.mkdirSync(binDir, { recursive: true });
+    }
+    const archiveName = `ripgrep-${RG_VERSION}-${target.platform}`;
+    const url = `https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${archiveName}${target.ext}`;
+    const destBinary = path.join(binDir, RG_BINARY);
+    if (target.ext === ".tar.gz") {
+        downloadAndExtractTarGz(url, archiveName, destBinary);
+    }
+    else {
+        downloadAndExtractZip(url, archiveName, destBinary);
+    }
+    // Make executable
+    if (!IS_WINDOWS) {
+        fs.chmodSync(destBinary, 0o755);
+    }
+    return { rgPath: destBinary, installed: true, version: RG_VERSION };
+}
+function downloadAndExtractTarGz(url, archiveName, destBinary) {
+    const destDir = path.dirname(destBinary);
+    const tmpTarGz = path.join(destDir, "rg-download.tar.gz");
+    try {
+        // Download archive to a temporary file without using a shell
+        const curlResult = spawnSync("curl", ["-fsSL", "-o", tmpTarGz, url], {
+            encoding: "utf8",
+            timeout: 60_000,
+            env: process.env,
+        });
+        if (curlResult.status !== 0) {
+            const err = curlResult.stderr?.trim() || curlResult.error?.message || "unknown error";
+            throw new Error(`Failed to download ripgrep from ${url}: ${err}`);
+        }
+        // Extract the specific binary from the archive into destDir
+        const tarResult = spawnSync("tar", ["xzf", tmpTarGz, "--strip-components=1", "-C", destDir, `${archiveName}/rg`], {
+            encoding: "utf8",
+            timeout: 60_000,
+            env: process.env,
+        });
+        if (tarResult.status !== 0) {
+            const err = tarResult.stderr?.trim() || tarResult.error?.message || "unknown error";
+            throw new Error(`Failed to extract ripgrep from ${url}: ${err}`);
+        }
+        if (!fs.existsSync(destBinary)) {
+            throw new Error(`ripgrep binary not found at ${destBinary} after extraction`);
+        }
+    }
+    finally {
+        // Best-effort cleanup of temporary archive
+        try {
+            if (fs.existsSync(tmpTarGz)) {
+                fs.unlinkSync(tmpTarGz);
+            }
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}
+function downloadAndExtractZip(url, archiveName, destBinary) {
+    const destDir = path.dirname(destBinary);
+    const tmpZip = path.join(destDir, "rg-download.zip");
+    const expandedDir = path.join(destDir, archiveName);
+    try {
+        // Download
+        const dlResult = spawnSync("curl", ["-fsSL", "-o", tmpZip, url], {
+            encoding: "utf8",
+            timeout: 60_000,
+            env: process.env,
+        });
+        if (dlResult.status !== 0) {
+            throw new Error(dlResult.stderr?.trim() || "download failed");
+        }
+        // Extract the zip archive using separate spawnSync calls with argument arrays
+        // to avoid shell injection via path interpolation in PowerShell -Command strings
+        const expandResult = spawnSync("powershell", ["-Command", "Expand-Archive", "-Path", tmpZip, "-DestinationPath", destDir, "-Force"], {
+            encoding: "utf8",
+            timeout: 60_000,
+            env: process.env,
+        });
+        if (expandResult.status !== 0) {
+            throw new Error(expandResult.stderr?.trim() || "extraction failed");
+        }
+        const srcRgExe = path.join(destDir, archiveName, "rg.exe");
+        const moveResult = spawnSync("powershell", ["-Command", "Move-Item", "-Force", "-Path", srcRgExe, "-Destination", destBinary], {
+            encoding: "utf8",
+            timeout: 60_000,
+            env: process.env,
+        });
+        if (moveResult.status !== 0) {
+            throw new Error(moveResult.stderr?.trim() || "move failed");
+        }
+    }
+    finally {
+        if (fs.existsSync(tmpZip))
+            fs.unlinkSync(tmpZip);
+        if (fs.existsSync(expandedDir))
+            fs.rmSync(expandedDir, { recursive: true, force: true });
+    }
+}
+function getRgVersion(rgPath) {
+    const result = spawnSync(rgPath, ["--version"], { encoding: "utf8", timeout: 5_000, env: process.env });
+    if (result.status === 0 && result.stdout) {
+        const match = result.stdout.match(/ripgrep\s+([\d.]+)/);
+        return match ? match[1] : "unknown";
+    }
+    return "unknown";
+}

package/dist/ripgrep-resolve.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+import { IS_WINDOWS } from "./common";
+import { getBinDir } from "./paths";
+export const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
+function canExecute(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
+    if (IS_WINDOWS)
+        return true;
+    try {
+        fs.accessSync(filePath, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveFromPath() {
+    const rawPath = process.env.PATH;
+    if (!rawPath)
+        return null;
+    const pathEntries = rawPath.split(path.delimiter).filter(Boolean);
+    if (IS_WINDOWS) {
+        const pathext = (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+            .split(";")
+            .filter(Boolean)
+            .map((ext) => ext.toLowerCase());
+        for (const entry of pathEntries) {
+            const directCandidate = path.join(entry, "rg");
+            if (canExecute(directCandidate))
+                return directCandidate;
+            for (const ext of pathext) {
+                const candidate = path.join(entry, `rg${ext}`);
+                if (canExecute(candidate))
+                    return candidate;
+            }
+        }
+        return null;
+    }
+    for (const entry of pathEntries) {
+        const candidate = path.join(entry, "rg");
+        if (canExecute(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Resolve the path to a usable ripgrep binary.
+ * Checks in order:
+ *   1. Provided binDir (or default cache bin dir) for rg
+ *   2. System PATH (rg)
+ * Returns null if ripgrep is not available.
+ */
+export function resolveRg(binDir) {
+    if (binDir) {
+        const directRg = path.join(binDir, RG_BINARY);
+        if (canExecute(directRg))
+            return directRg;
+    }
+    // Check default cache bin dir
+    try {
+        const defaultBinDir = getBinDir();
+        const cachedRg = path.join(defaultBinDir, RG_BINARY);
+        if (canExecute(cachedRg))
+            return cachedRg;
+    }
+    catch {
+        // getBinDir may fail if HOME is not set — fall through
+    }
+    return resolveFromPath();
+}
+/**
+ * Check if ripgrep is available (in cache/bin or system PATH).
+ */
+export function isRgAvailable(binDir) {
+    return resolveRg(binDir) !== null;
+}

package/dist/ripgrep.js

@@ -0,0 +1,2 @@
+export { ensureRg } from "./ripgrep-install";
+export { isRgAvailable, resolveRg } from "./ripgrep-resolve";