akm-cli 0.1.3 → 0.2.0

package/dist/usage-events.js

@@ -0,0 +1,73 @@
+/**
+ * Usage event helpers for telemetry and utility-based re-ranking.
+ *
+ * Schema (created by ensureUsageEventsSchema):
+ *   id, event_type, query, entry_id (nullable), entry_ref, signal, metadata, created_at
+ */
+// ── Schema ──────────────────────────────────────────────────────────────────
+export function ensureUsageEventsSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS usage_events (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_type TEXT NOT NULL,
+      query      TEXT,
+      entry_id   INTEGER,
+      entry_ref  TEXT,
+      signal     TEXT,
+      metadata   TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_usage_events_entry ON usage_events(entry_id);
+    CREATE INDEX IF NOT EXISTS idx_usage_events_type ON usage_events(event_type);
+    CREATE INDEX IF NOT EXISTS idx_usage_events_ref ON usage_events(entry_ref);
+  `);
+}
+// ── Insert ───────────────────────────────────────────────────────────────────
+/**
+ * Insert a usage event into the database. Fire-and-forget: errors are
+ * silently caught so callers are never blocked or disrupted.
+ */
+export function insertUsageEvent(db, event) {
+    try {
+        db.prepare(`INSERT INTO usage_events (event_type, query, entry_id, entry_ref, signal, metadata)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(event.event_type, event.query ?? null, event.entry_id ?? null, event.entry_ref ?? null, event.signal ?? null, event.metadata ?? null);
+    }
+    catch {
+        /* fire-and-forget: silently ignore errors */
+    }
+}
+// ── Query ────────────────────────────────────────────────────────────────────
+/**
+ * Retrieve usage events, optionally filtered by event_type and/or entry_ref.
+ */
+export function getUsageEvents(db, filters) {
+    const conditions = [];
+    const params = [];
+    if (filters?.event_type) {
+        conditions.push("event_type = ?");
+        params.push(filters.event_type);
+    }
+    if (filters?.entry_ref) {
+        conditions.push("entry_ref = ?");
+        params.push(filters.entry_ref);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, created_at
+               FROM usage_events ${where}
+               ORDER BY id ASC`;
+    return db.prepare(sql).all(...params);
+}
+/**
+ * Delete usage events older than the given number of days.
+ */
+export function purgeOldUsageEvents(db, retentionDays) {
+    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
+        return;
+    try {
+        const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
+        db.prepare("DELETE FROM usage_events WHERE created_at < ?").run(cutoff);
+    }
+    catch {
+        /* Table may not exist yet */
+    }
+}

package/dist/version.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+// Version: prefer compile-time define, then package.json, then fallback
+export const pkgVersion = (() => {
+    // Injected at compile time via `bun build --define`
+    if (typeof AKM_VERSION !== "undefined")
+        return AKM_VERSION;
+    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.version === "string")
+                return pkg.version;
+        }
+    }
+    catch {
+        // swallow — running as compiled binary without package.json
+    }
+    return "0.0.0-dev";
+})();

package/dist/walker.js

@@ -9,6 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { isRelevantAssetFile } from "./asset-spec";
 import { buildFileContext } from "./file-context";
+const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
 /**
  * Walk a type root directory and return files grouped by their parent directory.
  *
@@ -82,7 +83,6 @@ function walkStashGit(stashRoot) {
     // result.success is false if the process exited non-zero OR git was not found
     if (!result.success)
         return null;
-    const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
     const SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
     const stdout = Buffer.isBuffer(result.stdout) ? result.stdout.toString("utf8") : String(result.stdout ?? "");
     const files = stdout
@@ -139,7 +139,6 @@ function isInsideGitRepo(dir) {
 /** Manual walk for non-git directories. */
 function walkStashManual(stashRoot) {
     const results = [];
-    const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
     const stack = [stashRoot];
     while (stack.length > 0) {
         const current = stack.pop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [
@@ -59,6 +59,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "citty": "^0.2.1"
+    "citty": "^0.2.1",
+    "yaml": "^2.8.2"
   }
 }

package/dist/stash-providers/context-hub.js

@@ -1,390 +0,0 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { fetchWithRetry } from "../common";
-import { ConfigError, NotFoundError, UsageError } from "../errors";
-import { parseFrontmatter, toStringOrUndefined } from "../frontmatter";
-import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc } from "../markdown";
-import { getRegistryIndexCacheDir } from "../paths";
-import { extractTarGzSecure } from "../registry-install";
-import { registerStashProvider } from "../stash-provider-factory";
-/** Cache TTL before refreshing the mirrored repo (12 hours). */
-const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
-/** Maximum stale age allowed when refresh fails (7 days). */
-const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
-const CONTEXT_HUB_REF_PREFIX = "context-hub://";
-class ContextHubStashProvider {
-    type = "context-hub";
-    name;
-    repo;
-    constructor(config) {
-        this.repo = parseContextHubRepoUrl(config.url ?? "");
-        this.name = config.name ?? `${this.repo.owner}/${this.repo.repo}`;
-    }
-    async search(options) {
-        try {
-            const entries = await this.loadEntries();
-            const filtered = entries
-                .filter((entry) => matchesType(entry, options.type))
-                .map((entry) => ({ entry, score: scoreEntry(entry, options.query) }))
-                .filter(({ score }) => options.query.trim() === "" || score > 0)
-                .sort((a, b) => b.score - a.score || a.entry.sortName.localeCompare(b.entry.sortName))
-                .slice(0, options.limit);
-            return {
-                hits: filtered.map(({ entry, score }) => entryToHit(entry, score)),
-            };
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return { hits: [], warnings: [`Stash ${this.name}: ${message}`] };
-        }
-    }
-    async show(ref, view) {
-        const filePath = parseContextHubRef(ref);
-        const repoDir = await this.loadRepoDir();
-        const resolved = resolveCachedFilePath(repoDir, filePath);
-        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
-            throw new NotFoundError(`Context Hub asset not found: ${filePath}`);
-        }
-        const raw = fs.readFileSync(resolved, "utf8");
-        const parsed = parseFrontmatter(raw);
-        const relFromContent = path.posix.normalize(path.relative(path.join(repoDir, "content"), resolved).replace(/\\/g, "/"));
-        const author = sanitizeString(relFromContent.split("/")[0] ?? "") || "unknown";
-        const name = sanitizeString(toStringOrUndefined(parsed.data.name) ?? path.basename(path.dirname(resolved)));
-        const description = sanitizeString(toStringOrUndefined(parsed.data.description), 1000);
-        const assetType = path.basename(resolved) === "SKILL.md" ? "skill" : "knowledge";
-        const content = renderContentForView(raw, view);
-        return {
-            type: assetType,
-            name: `${author}/${name}`,
-            path: ref,
-            content,
-            description,
-            editable: false,
-            origin: this.type,
-            action: `Context Hub content from ${this.repo.canonicalUrl}`,
-        };
-    }
-    canShow(ref) {
-        return ref.trim().startsWith(CONTEXT_HUB_REF_PREFIX);
-    }
-    async loadEntries() {
-        const cachePaths = getCachePaths(this.repo.canonicalUrl);
-        const index = await ensureContextHubMirror(this.repo, cachePaths);
-        return index.entries;
-    }
-    async loadRepoDir() {
-        const cachePaths = getCachePaths(this.repo.canonicalUrl);
-        await ensureContextHubMirror(this.repo, cachePaths, { requireRepoDir: true });
-        return cachePaths.repoDir;
-    }
-}
-registerStashProvider("context-hub", (config) => new ContextHubStashProvider(config));
-registerStashProvider("github", (config) => new ContextHubStashProvider(config));
-function getCachePaths(repoUrl) {
-    const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
-    const rootDir = path.join(getRegistryIndexCacheDir(), `context-hub-${key}`);
-    return {
-        rootDir,
-        archivePath: path.join(rootDir, "repo.tar.gz"),
-        repoDir: path.join(rootDir, "repo"),
-        indexPath: path.join(rootDir, "index.json"),
-    };
-}
-async function ensureContextHubMirror(repo, cachePaths, options) {
-    const requireRepoDir = options?.requireRepoDir === true;
-    const cached = readCachedIndex(cachePaths.indexPath);
-    if (cached && !isExpired(cached.mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
-        return { entries: cached.entries };
-    }
-    try {
-        fs.mkdirSync(cachePaths.rootDir, { recursive: true });
-        await downloadArchive(buildTarballUrl(repo), cachePaths.archivePath);
-        extractTarGzSecure(cachePaths.archivePath, cachePaths.repoDir);
-        const entries = buildContextHubIndex(cachePaths.repoDir);
-        writeCachedIndex(cachePaths.indexPath, entries);
-        return { entries };
-    }
-    catch (err) {
-        if (cached &&
-            !isExpired(cached.mtime, CACHE_STALE_MS) &&
-            (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
-            return { entries: cached.entries };
-        }
-        throw err;
-    }
-}
-function hasExtractedRepo(repoDir) {
-    try {
-        return fs.statSync(repoDir).isDirectory() && fs.statSync(path.join(repoDir, "content")).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-function readCachedIndex(indexPath) {
-    try {
-        const stat = fs.statSync(indexPath);
-        const raw = JSON.parse(fs.readFileSync(indexPath, "utf8"));
-        if (!Array.isArray(raw))
-            return null;
-        const entries = raw.filter(isContextHubEntry);
-        return { entries, mtime: stat.mtimeMs };
-    }
-    catch {
-        return null;
-    }
-}
-function writeCachedIndex(indexPath, entries) {
-    const dir = path.dirname(indexPath);
-    fs.mkdirSync(dir, { recursive: true });
-    const tmpPath = `${indexPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    fs.writeFileSync(tmpPath, JSON.stringify(entries), { encoding: "utf8", mode: 0o600 });
-    fs.renameSync(tmpPath, indexPath);
-}
-async function downloadArchive(url, destination) {
-    const response = await fetchWithRetry(url, undefined, { timeout: 120_000, retries: 1 });
-    if (!response.ok) {
-        throw new Error(`Failed to download Context Hub archive (${response.status}) from ${url}`);
-    }
-    const BunRuntime = globalThis.Bun;
-    if (BunRuntime?.write) {
-        await BunRuntime.write(destination, response);
-        return;
-    }
-    const arrayBuffer = await response.arrayBuffer();
-    fs.writeFileSync(destination, Buffer.from(arrayBuffer));
-}
-function buildContextHubIndex(repoDir) {
-    const contentDir = path.join(repoDir, "content");
-    if (!fs.existsSync(contentDir) || !fs.statSync(contentDir).isDirectory()) {
-        throw new Error(`Context Hub repo at ${repoDir} is missing a content/ directory`);
-    }
-    const files = findEntryFiles(contentDir);
-    const entries = [];
-    for (const filePath of files) {
-        const entry = buildEntry(repoDir, contentDir, filePath);
-        if (entry)
-            entries.push(entry);
-    }
-    return entries;
-}
-function findEntryFiles(dir) {
-    const results = [];
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        const full = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            results.push(...findEntryFiles(full));
-        }
-        else if (entry.name === "DOC.md" || entry.name === "SKILL.md") {
-            results.push(full);
-        }
-    }
-    return results;
-}
-function buildEntry(repoDir, contentDir, fullPath) {
-    const raw = fs.readFileSync(fullPath, "utf8");
-    const parsed = parseFrontmatter(raw);
-    const relPath = path.posix.normalize(path.relative(repoDir, fullPath).replace(/\\/g, "/"));
-    const relFromContent = path.posix.normalize(path.relative(contentDir, fullPath).replace(/\\/g, "/"));
-    const segments = relFromContent.split("/");
-    const author = sanitizeString(segments[0] ?? "");
-    if (!author)
-        return null;
-    const name = sanitizeString(toStringOrUndefined(parsed.data.name) ?? path.basename(path.dirname(fullPath)));
-    if (!name)
-        return null;
-    const metadata = (parsed.data.metadata ?? {});
-    const tags = parseCsv(metadata.tags);
-    const language = sanitizeString(toStringOrUndefined(metadata.languages));
-    const version = sanitizeString(toStringOrUndefined(metadata.versions));
-    const id = `${author}/${name}`;
-    const assetType = path.basename(fullPath) === "SKILL.md" ? "skill" : "knowledge";
-    return {
-        id,
-        ref: makeContextHubRef(relPath),
-        assetType,
-        filePath: relPath,
-        description: sanitizeString(toStringOrUndefined(parsed.data.description), 1000),
-        tags,
-        language: language || undefined,
-        version: version || undefined,
-        sortName: `${id}:${language ?? ""}:${version ?? ""}`,
-    };
-}
-function scoreEntry(entry, query) {
-    const trimmed = query.trim().toLowerCase();
-    if (!trimmed)
-        return 1;
-    const tokens = trimmed.split(/\s+/).filter(Boolean);
-    if (tokens.length === 0)
-        return 1;
-    const haystacks = [
-        { text: entry.id.toLowerCase(), weight: 4 },
-        { text: entry.description?.toLowerCase() ?? "", weight: 2 },
-        { text: (entry.tags ?? []).join(" ").toLowerCase(), weight: 2 },
-        { text: entry.language?.toLowerCase() ?? "", weight: 1 },
-        { text: entry.version?.toLowerCase() ?? "", weight: 1 },
-    ];
-    let matched = 0;
-    let score = 0;
-    for (const token of tokens) {
-        let tokenScore = 0;
-        for (const { text, weight } of haystacks) {
-            if (!text)
-                continue;
-            if (text === token)
-                tokenScore = Math.max(tokenScore, weight * 2);
-            else if (text.includes(token))
-                tokenScore = Math.max(tokenScore, weight);
-        }
-        if (tokenScore > 0) {
-            matched++;
-            score += tokenScore;
-        }
-    }
-    if (matched === 0)
-        return 0;
-    const coverage = matched / tokens.length;
-    return Math.round((score * coverage + (entry.id.toLowerCase() === trimmed ? 5 : 0)) * 1000) / 1000;
-}
-function matchesType(entry, requested) {
-    if (!requested || requested === "any")
-        return true;
-    return entry.assetType === requested;
-}
-function entryToHit(entry, score) {
-    const details = [entry.language, entry.version].filter(Boolean).join(" • ");
-    const description = [entry.description, details].filter(Boolean).join(" — ") || undefined;
-    return {
-        type: entry.assetType,
-        name: entry.id,
-        path: entry.ref,
-        ref: entry.ref,
-        origin: "context-hub",
-        editable: false,
-        description,
-        tags: entry.tags,
-        action: `akm show ${entry.ref}`,
-        score,
-    };
-}
-function renderContentForView(content, view) {
-    if (!view || view.mode === "full")
-        return content;
-    switch (view.mode) {
-        case "toc":
-            return formatToc(parseMarkdownToc(content));
-        case "frontmatter":
-            return extractFrontmatterOnly(content) ?? "(no frontmatter)";
-        case "section": {
-            const section = extractSection(content, view.heading);
-            if (!section) {
-                throw new UsageError(`Section not found: ${view.heading}`);
-            }
-            return section.content;
-        }
-        case "lines":
-            return extractLineRange(content, view.start, view.end);
-        default:
-            return content;
-    }
-}
-function resolveCachedFilePath(repoDir, filePath) {
-    const normalized = path.posix.normalize(filePath.replace(/\\/g, "/"));
-    if (!normalized.startsWith("content/")) {
-        throw new UsageError(`Invalid Context Hub ref: ${filePath}`);
-    }
-    const resolved = path.resolve(repoDir, normalized);
-    const root = path.resolve(repoDir);
-    if (!resolved.startsWith(root + path.sep)) {
-        throw new UsageError(`Invalid Context Hub ref: ${filePath}`);
-    }
-    return resolved;
-}
-function buildTarballUrl(repo) {
-    return `https://github.com/${repo.owner}/${repo.repo}/archive/refs/heads/${repo.ref}.tar.gz`;
-}
-function parseContextHubRepoUrl(rawUrl) {
-    if (!rawUrl) {
-        throw new ConfigError("Context Hub provider requires a GitHub repository URL");
-    }
-    let parsed;
-    try {
-        parsed = new URL(rawUrl);
-    }
-    catch {
-        throw new ConfigError(`Context Hub URL is not valid: "${rawUrl}"`);
-    }
-    if (parsed.protocol !== "https:") {
-        throw new ConfigError(`Context Hub URL must use https://, got "${parsed.protocol}"`);
-    }
-    if (parsed.hostname !== "github.com") {
-        throw new ConfigError(`Context Hub provider only supports github.com URLs, got "${parsed.hostname}"`);
-    }
-    const segments = parsed.pathname.split("/").filter(Boolean);
-    if (segments.length < 2) {
-        throw new ConfigError(`Context Hub URL must point to a GitHub repository, got "${rawUrl}"`);
-    }
-    const owner = sanitizeString(segments[0]);
-    const repo = sanitizeString(segments[1].replace(/\.git$/i, ""));
-    let ref = "main";
-    if (segments[2] === "tree" && segments.length >= 4) {
-        ref = sanitizeString(segments.slice(3).join("/"), 255) || "main";
-    }
-    if (!owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) {
-        throw new ConfigError(`Unsupported Context Hub repository URL: "${rawUrl}"`);
-    }
-    if (!ref || ref.includes("..") || !/^[A-Za-z0-9._/-]+$/.test(ref)) {
-        throw new ConfigError(`Unsupported Context Hub branch/ref in URL: "${rawUrl}"`);
-    }
-    return {
-        owner,
-        repo,
-        ref,
-        canonicalUrl: `https://github.com/${owner}/${repo}/tree/${ref}`,
-    };
-}
-function makeContextHubRef(filePath) {
-    return `${CONTEXT_HUB_REF_PREFIX}${path.posix.normalize(filePath)}`;
-}
-function parseContextHubRef(ref) {
-    const trimmed = ref.trim();
-    if (!trimmed.startsWith(CONTEXT_HUB_REF_PREFIX)) {
-        throw new UsageError(`Invalid Context Hub ref: ${ref}`);
-    }
-    const filePath = trimmed.slice(CONTEXT_HUB_REF_PREFIX.length);
-    if (!filePath) {
-        throw new UsageError(`Invalid Context Hub ref: ${ref}`);
-    }
-    return filePath;
-}
-function parseCsv(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const items = value
-        .split(",")
-        .map((item) => sanitizeString(item.trim(), 100))
-        .filter(Boolean);
-    return items.length > 0 ? items : undefined;
-}
-function sanitizeString(value, maxLength = 255) {
-    if (typeof value !== "string")
-        return "";
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: strips untrusted control chars from remote metadata
-    return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, maxLength);
-}
-function isExpired(mtimeMs, ttlMs) {
-    return Date.now() - mtimeMs > ttlMs;
-}
-function isContextHubEntry(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return false;
-    const obj = value;
-    return (typeof obj.id === "string" &&
-        typeof obj.ref === "string" &&
-        (obj.assetType === "knowledge" || obj.assetType === "skill") &&
-        typeof obj.filePath === "string" &&
-        typeof obj.sortName === "string");
-}
-export { ContextHubStashProvider, buildContextHubIndex, makeContextHubRef, parseContextHubRef, parseContextHubRepoUrl };