akm-cli 0.0.0 → 0.0.17

package/dist/llm.js

@@ -0,0 +1,87 @@
+import { fetchWithTimeout } from "./common";
+async function chatCompletion(config, messages) {
+    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: config.temperature ?? 0.3,
+            max_tokens: 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() ?? "";
+}
+// ── 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.
+ */
+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 },
+    ]);
+    try {
+        // Strip markdown code fences if present
+        const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "");
+        const parsed = JSON.parse(cleaned);
+        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;
+    }
+    catch {
+        // LLM returned unparseable output, return empty
+        return {};
+    }
+}
+/**
+ * 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;
+    }
+}

package/dist/lockfile.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getConfigDir } from "./config";
+// ── Paths ───────────────────────────────────────────────────────────────────
+function getLockfilePath() {
+    return path.join(getConfigDir(), "stash.lock");
+}
+// ── Read / Write ────────────────────────────────────────────────────────────
+export function readLockfile() {
+    const lockfilePath = getLockfilePath();
+    try {
+        const raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter(isValidLockfileEntry);
+    }
+    catch {
+        return [];
+    }
+}
+export function writeLockfile(entries) {
+    const lockfilePath = getLockfilePath();
+    const dir = path.dirname(lockfilePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = `${lockfilePath}.tmp.${process.pid}`;
+    try {
+        fs.writeFileSync(tmpPath, `${JSON.stringify(entries, null, 2)}\n`, "utf8");
+        fs.renameSync(tmpPath, lockfilePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
+export function upsertLockEntry(entry) {
+    const entries = readLockfile();
+    const withoutExisting = entries.filter((e) => e.id !== entry.id);
+    writeLockfile([...withoutExisting, entry]);
+}
+export function removeLockEntry(id) {
+    const entries = readLockfile();
+    writeLockfile(entries.filter((e) => e.id !== id));
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function isValidLockfileEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const obj = value;
+    return (typeof obj.id === "string" &&
+        obj.id !== "" &&
+        typeof obj.source === "string" &&
+        ["npm", "github", "git", "local"].includes(obj.source) &&
+        typeof obj.ref === "string" &&
+        obj.ref !== "");
+}

package/dist/markdown.js

@@ -0,0 +1,77 @@
+import { parseFrontmatter } from "./frontmatter";
+// ── Parsing ─────────────────────────────────────────────────────────────────
+export function parseMarkdownToc(content) {
+    const lines = content.split(/\r?\n/);
+    const headings = [];
+    const parsed = parseFrontmatter(content);
+    const start = parsed.frontmatter ? parsed.bodyStartLine - 1 : 0;
+    for (let i = start; i < lines.length; i++) {
+        const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
+        if (match) {
+            headings.push({
+                level: match[1].length,
+                text: match[2].replace(/\s+#+\s*$/, "").trim(),
+                line: i + 1,
+            });
+        }
+    }
+    return { headings, totalLines: lines.length };
+}
+// ── Extraction ──────────────────────────────────────────────────────────────
+export function extractSection(content, heading) {
+    const lines = content.split(/\r?\n/);
+    const target = heading.toLowerCase();
+    let startIdx = -1;
+    let startLevel = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
+        if (!match)
+            continue;
+        const text = match[2].replace(/\s+#+\s*$/, "").trim();
+        if (text.toLowerCase() === target && startIdx === -1) {
+            startIdx = i;
+            startLevel = match[1].length;
+        }
+        else if (startIdx !== -1 && match[1].length <= startLevel) {
+            return {
+                content: lines.slice(startIdx, i).join("\n"),
+                startLine: startIdx + 1,
+                endLine: i,
+            };
+        }
+    }
+    if (startIdx === -1)
+        return null;
+    return {
+        content: lines.slice(startIdx).join("\n"),
+        startLine: startIdx + 1,
+        endLine: lines.length,
+    };
+}
+export function extractLineRange(content, start, end) {
+    const lines = content.split(/\r?\n/);
+    if (end < start)
+        return "";
+    const s = Math.max(1, Math.min(start, lines.length));
+    const e = Math.min(end, lines.length);
+    return lines.slice(s - 1, e).join("\n");
+}
+export function extractFrontmatterOnly(content) {
+    const parsed = parseFrontmatter(content);
+    return parsed.frontmatter;
+}
+// ── Formatting ──────────────────────────────────────────────────────────────
+export function formatToc(toc) {
+    if (toc.headings.length === 0) {
+        return `(no headings found — ${toc.totalLines} lines total)`;
+    }
+    const lineWidth = String(toc.totalLines).length;
+    const parts = toc.headings.map((h) => {
+        const lineNum = `L${String(h.line).padStart(lineWidth)}`;
+        const indent = "  ".repeat(h.level - 1);
+        const prefix = "#".repeat(h.level);
+        return `${lineNum}  ${indent}${prefix} ${h.text}`;
+    });
+    parts.push(`\n${toc.totalLines} lines total`);
+    return parts.join("\n");
+}

package/dist/matchers.js

@@ -0,0 +1,159 @@
+/**
+ * Built-in asset matchers for the akm file classification system.
+ *
+ * Four matchers are registered at module load time, each at a different
+ * specificity level. Extension and content determine type; directories are
+ * optional specificity boosts, not requirements.
+ *
+ * - `extensionMatcher` (3) -- classifies any file by extension alone.
+ *   Ensures every known file type is discoverable regardless of directory.
+ * - `directoryMatcher` (10) -- boosts specificity when the first ancestor
+ *   directory matches a known type name (e.g. `scripts/`, `agents/`).
+ * - `parentDirHintMatcher` (15) -- boosts specificity based on the
+ *   immediate parent directory name.
+ * - `smartMdMatcher` (20 / 18 / 8 / 5) -- inspects markdown frontmatter
+ *   and body content for agent/command signals; falls back to "knowledge"
+ *   at specificity 5 when no signals are found. Command signals (`agent`
+ *   frontmatter, `$ARGUMENTS`/`$1`-`$3` placeholders) return 18.
+ */
+import { SCRIPT_EXTENSIONS } from "./asset-spec";
+import { registerMatcher } from "./file-context";
+// ── extensionMatcher (specificity: 3) ────────────────────────────────────────
+/**
+ * Base-level matcher that classifies files purely by extension.
+ *
+ * This is the foundation of the classification system: every file with a
+ * known extension gets a type, regardless of what directory it lives in.
+ * Higher-specificity matchers (directory, content) can override this.
+ *
+ * .md files are NOT handled here -- smartMdMatcher provides richer
+ * classification for markdown via frontmatter inspection.
+ */
+export function extensionMatcher(ctx) {
+    // SKILL.md is a skill regardless of location — high specificity beats
+    // smartMdMatcher's knowledge fallback and all directory-based matchers.
+    if (ctx.fileName === "SKILL.md") {
+        return { type: "skill", specificity: 25, renderer: "skill-md" };
+    }
+    // Known script extensions (excluding .md, handled by smartMdMatcher)
+    if (SCRIPT_EXTENSIONS.has(ctx.ext)) {
+        return { type: "script", specificity: 3, renderer: "script-source" };
+    }
+    return null;
+}
+// ── directoryMatcher (specificity: 10) ──────────────────────────────────────
+/**
+ * Directory-based matcher that boosts specificity when the first ancestor
+ * directory segment from the stash root matches a known type name.
+ */
+export function directoryMatcher(ctx) {
+    const topDir = ctx.ancestorDirs[0];
+    if (!topDir)
+        return null;
+    const ext = ctx.ext;
+    if (topDir === "scripts" && SCRIPT_EXTENSIONS.has(ext)) {
+        return { type: "script", specificity: 10, renderer: "script-source" };
+    }
+    if (topDir === "skills" && ctx.fileName === "SKILL.md") {
+        return { type: "skill", specificity: 10, renderer: "skill-md" };
+    }
+    if (topDir === "commands" && ext === ".md") {
+        return { type: "command", specificity: 10, renderer: "command-md" };
+    }
+    if (topDir === "agents" && ext === ".md") {
+        return { type: "agent", specificity: 10, renderer: "agent-md" };
+    }
+    if (topDir === "knowledge" && ext === ".md") {
+        return { type: "knowledge", specificity: 10, renderer: "knowledge-md" };
+    }
+    return null;
+}
+// ── parentDirHintMatcher (specificity: 15) ──────────────────────────────────
+/**
+ * Uses the immediate parent directory name as a hint. More specific than
+ * the ancestor-based directory matcher because the file might be nested
+ * several levels deep, yet its immediate parent can still carry strong
+ * naming conventions (e.g. `my-project/agents/planning.md`).
+ */
+export function parentDirHintMatcher(ctx) {
+    const { parentDir, ext, fileName } = ctx;
+    if (parentDir === "scripts" && SCRIPT_EXTENSIONS.has(ext)) {
+        return { type: "script", specificity: 15, renderer: "script-source" };
+    }
+    if (parentDir === "skills" && fileName === "SKILL.md") {
+        return { type: "skill", specificity: 15, renderer: "skill-md" };
+    }
+    if (parentDir === "agents" && ext === ".md") {
+        return { type: "agent", specificity: 15, renderer: "agent-md" };
+    }
+    if (parentDir === "commands" && ext === ".md") {
+        return { type: "command", specificity: 15, renderer: "command-md" };
+    }
+    if (parentDir === "knowledge" && ext === ".md") {
+        return { type: "knowledge", specificity: 15, renderer: "knowledge-md" };
+    }
+    return null;
+}
+// ── smartMdMatcher (specificity: 20 / 18 / 8 / 5) ──────────────────────────
+/** Pattern that matches OpenCode command placeholders in markdown body. */
+const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+/**
+ * Content-based matcher for `.md` files. Inspects frontmatter keys and body
+ * content to classify markdown as agent, command, or knowledge.
+ *
+ * Specificity levels:
+ *   20 -- agent-exclusive signals (`tools`, `toolPolicy`)
+ *   18 -- command content signals (`agent` frontmatter, `$ARGUMENTS`/`$1`-`$3`)
+ *    8 -- weak agent signal (`model` alone)
+ *    5 -- knowledge fallback (any unclassified `.md`)
+ *
+ * Command signals at 18 override directory hints (10/15) because the content
+ * unambiguously identifies a command template. Agent-exclusive signals at 20
+ * still win over command signals when both are present.
+ */
+export function smartMdMatcher(ctx) {
+    if (ctx.ext !== ".md")
+        return null;
+    const fm = ctx.frontmatter();
+    if (fm) {
+        // Agent-exclusive indicators: toolPolicy or tools
+        // These return high specificity (20) to override everything else.
+        if ("toolPolicy" in fm || "tools" in fm) {
+            return { type: "agent", specificity: 20, renderer: "agent-md" };
+        }
+        // Command signal: `agent` frontmatter key names a dispatch target.
+        // This is an OpenCode convention specific to commands.
+        if ("agent" in fm) {
+            return { type: "command", specificity: 18, renderer: "command-md" };
+        }
+    }
+    // Command signal: body contains $ARGUMENTS or $1/$2/$3 placeholders.
+    // These are definitively command template patterns (OpenCode convention).
+    const body = ctx.content();
+    if (COMMAND_PLACEHOLDER_RE.test(body)) {
+        return { type: "command", specificity: 18, renderer: "command-md" };
+    }
+    if (fm) {
+        // model alone is a weaker agent signal (specificity 8) -- it can appear
+        // on commands too (OpenCode convention). Directory hints (10/15) win
+        // when the file lives in commands/, but model still classifies an .md
+        // as agent when no directory hint is present.
+        if ("model" in fm) {
+            return { type: "agent", specificity: 8, renderer: "agent-md" };
+        }
+    }
+    // Weak fallback: any .md file is assumed to be knowledge
+    return { type: "knowledge", specificity: 5, renderer: "knowledge-md" };
+}
+// ── Registration ────────────────────────────────────────────────────────────
+/** All built-in matchers in registration order (later wins ties). */
+const builtinMatchers = [extensionMatcher, directoryMatcher, parentDirHintMatcher, smartMdMatcher];
+/**
+ * Register all built-in matchers with the file-context registry.
+ * Called once from the CLI entry point (or ensureBuiltinsRegistered).
+ */
+export function registerBuiltinMatchers() {
+    for (const matcher of builtinMatchers) {
+        registerMatcher(matcher);
+    }
+}