akm-cli 0.0.0 → 0.0.17

package/dist/metadata.js

@@ -0,0 +1,408 @@
+import fs from "node:fs";
+import path from "node:path";
+import { deriveCanonicalAssetName, isRelevantAssetFile, TYPE_DIRS } from "./asset-spec";
+import { isAssetType } from "./common";
+import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
+import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
+import { warn } from "./warn";
+// ── Load / Write ────────────────────────────────────────────────────────────
+const STASH_FILENAME = ".stash.json";
+export function stashFilePath(dirPath) {
+    return path.join(dirPath, STASH_FILENAME);
+}
+export function loadStashFile(dirPath) {
+    const filePath = stashFilePath(dirPath);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        if (!raw || !Array.isArray(raw.entries))
+            return null;
+        const entries = [];
+        for (const e of raw.entries) {
+            const validated = validateStashEntry(e);
+            if (validated) {
+                entries.push(validated);
+            }
+            else {
+                const name = typeof e === "object" && e !== null && typeof e.name === "string"
+                    ? e.name
+                    : "(unknown)";
+                warn(`Warning: Skipping invalid entry "${name}" in ${filePath}`);
+            }
+        }
+        return entries.length > 0 ? { entries } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeStashFile(dirPath, stash) {
+    const filePath = stashFilePath(dirPath);
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    try {
+        fs.writeFileSync(tmpPath, `${JSON.stringify(stash, null, 2)}\n`, "utf8");
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
+export function validateStashEntry(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return null;
+    const e = entry;
+    if (typeof e.name !== "string" || !e.name)
+        return null;
+    if (typeof e.type !== "string" || !isAssetType(e.type))
+        return null;
+    const result = {
+        name: e.name,
+        type: e.type,
+    };
+    if (typeof e.description === "string" && e.description)
+        result.description = e.description;
+    if (Array.isArray(e.tags))
+        result.tags = e.tags.filter((t) => typeof t === "string");
+    if (Array.isArray(e.examples))
+        result.examples = e.examples.filter((x) => typeof x === "string");
+    if (Array.isArray(e.searchHints)) {
+        const filtered = e.searchHints.filter((s) => typeof s === "string" && s.trim().length > 0);
+        if (filtered.length > 0)
+            result.searchHints = filtered;
+    }
+    if (typeof e.intent === "object" && e.intent !== null) {
+        const intent = e.intent;
+        result.intent = {};
+        if (typeof intent.when === "string")
+            result.intent.when = intent.when;
+        if (typeof intent.input === "string")
+            result.intent.input = intent.input;
+        if (typeof intent.output === "string")
+            result.intent.output = intent.output;
+    }
+    if (typeof e.filename === "string" && e.filename)
+        result.filename = e.filename;
+    if (e.quality === "generated" || e.quality === "curated")
+        result.quality = e.quality;
+    if (typeof e.confidence === "number" && Number.isFinite(e.confidence))
+        result.confidence = Math.max(0, Math.min(1, e.confidence));
+    if (typeof e.source === "string" &&
+        ["package", "frontmatter", "comments", "filename", "manual", "llm"].includes(e.source)) {
+        result.source = e.source;
+    }
+    if (Array.isArray(e.aliases)) {
+        const filtered = e.aliases.filter((a) => typeof a === "string" && a.trim().length > 0);
+        if (filtered.length > 0)
+            result.aliases = normalizeTerms(filtered);
+    }
+    if (Array.isArray(e.toc)) {
+        const validated = e.toc.filter((h) => {
+            if (typeof h !== "object" || h === null)
+                return false;
+            const rec = h;
+            return typeof rec.level === "number" && typeof rec.text === "string" && typeof rec.line === "number";
+        });
+        if (validated.length > 0)
+            result.toc = validated;
+    }
+    const usage = normalizeNonEmptyStringList(e.usage);
+    if (usage)
+        result.usage = usage;
+    if (typeof e.run === "string" && e.run.trim())
+        result.run = e.run.trim();
+    if (typeof e.setup === "string" && e.setup.trim())
+        result.setup = e.setup.trim();
+    if (typeof e.cwd === "string" && e.cwd.trim())
+        result.cwd = e.cwd.trim();
+    if (typeof e.fileSize === "number" && Number.isFinite(e.fileSize) && e.fileSize >= 0)
+        result.fileSize = e.fileSize;
+    return result;
+}
+function normalizeNonEmptyStringList(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : undefined;
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    const filtered = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    return filtered.length > 0 ? filtered : undefined;
+}
+// ── Metadata Generation ─────────────────────────────────────────────────────
+export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
+    const entries = [];
+    const pkgMeta = extractPackageMetadata(dirPath);
+    for (const file of files) {
+        const ext = path.extname(file).toLowerCase();
+        const baseName = path.basename(file, ext);
+        const fileName = path.basename(file);
+        // Skip non-relevant files
+        if (!isRelevantAssetFile(assetType, fileName))
+            continue;
+        const canonicalName = deriveCanonicalAssetName(assetType, typeRoot, file) ?? baseName;
+        const entry = {
+            name: canonicalName,
+            type: assetType,
+            quality: "generated",
+            confidence: 0.55,
+            source: "filename",
+        };
+        // Priority 1: Package.json metadata
+        if (pkgMeta) {
+            if (pkgMeta.description && !entry.description) {
+                entry.description = pkgMeta.description;
+                entry.source = "package";
+                entry.confidence = 0.8;
+            }
+            if (pkgMeta.keywords && pkgMeta.keywords.length > 0)
+                entry.tags = normalizeTerms(pkgMeta.keywords);
+        }
+        // Priority 2: Frontmatter (for .md files -- overrides package.json description)
+        if (ext === ".md") {
+            const fm = extractFrontmatterDescription(file);
+            if (fm) {
+                entry.description = fm;
+                entry.source = "frontmatter";
+                entry.confidence = 0.9;
+            }
+        }
+        // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for scripts)
+        const fileCtx = buildFileContext(typeRoot, file);
+        const match = runMatchers(fileCtx);
+        if (match) {
+            const renderer = getRenderer(match.renderer);
+            if (renderer?.extractMetadata) {
+                const renderCtx = buildRenderContext(fileCtx, match, [typeRoot]);
+                renderer.extractMetadata(entry, renderCtx);
+            }
+        }
+        // Priority 4: Filename heuristics (fallback)
+        if (!entry.description) {
+            entry.description = fileNameToDescription(baseName);
+            entry.source = "filename";
+            entry.confidence = Math.min(entry.confidence ?? 0.55, 0.55);
+        }
+        if (!entry.tags || entry.tags.length === 0) {
+            entry.tags = extractTagsFromPath(file, dirPath);
+        }
+        entry.tags = normalizeTerms(entry.tags ?? []);
+        entry.aliases = buildAliases(canonicalName, entry.tags);
+        // Search hints are only generated when LLM is configured (via enhanceStashWithLlm)
+        // Heuristic search hints are too noisy to be useful for search quality
+        entry.filename = path.basename(file);
+        entries.push(entry);
+    }
+    return { entries };
+}
+/** Set of all known type directory names (e.g. "scripts", "skills", "agents") */
+const TYPE_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
+/**
+ * Generate metadata for files using the matcher system instead of a fixed asset type.
+ *
+ * This is the flat-walk counterpart of `generateMetadata`. It classifies each
+ * file via `runMatchers()` and uses the matched type for canonical naming.
+ * Files that no matcher claims are silently skipped.
+ */
+export function generateMetadataFlat(stashRoot, files) {
+    const entries = [];
+    const pkgMetaCache = new Map();
+    for (const file of files) {
+        const ctx = buildFileContext(stashRoot, file);
+        const match = runMatchers(ctx);
+        if (!match)
+            continue;
+        const assetType = match.type;
+        if (!isAssetType(assetType))
+            continue;
+        // If the file lives under a known type directory, use that as the root
+        // for canonical naming so names don't include the type prefix.
+        // e.g. scripts/deploy.sh → "deploy.sh" not "scripts/deploy.sh"
+        const firstAncestor = ctx.ancestorDirs[0];
+        const effectiveRoot = firstAncestor && TYPE_DIR_NAMES.has(firstAncestor) ? path.join(stashRoot, firstAncestor) : stashRoot;
+        const ext = path.extname(file).toLowerCase();
+        const baseName = path.basename(file, ext);
+        const canonicalName = deriveCanonicalAssetName(assetType, effectiveRoot, file) ?? baseName;
+        const entry = {
+            name: canonicalName,
+            type: assetType,
+            quality: "generated",
+            confidence: 0.55,
+            source: "filename",
+        };
+        // Package.json metadata
+        const dirPath = path.dirname(file);
+        if (!pkgMetaCache.has(dirPath)) {
+            pkgMetaCache.set(dirPath, extractPackageMetadata(dirPath));
+        }
+        const pkgMeta = pkgMetaCache.get(dirPath);
+        if (pkgMeta) {
+            if (pkgMeta.description && !entry.description) {
+                entry.description = pkgMeta.description;
+                entry.source = "package";
+                entry.confidence = 0.8;
+            }
+            if (pkgMeta.keywords?.length)
+                entry.tags = normalizeTerms(pkgMeta.keywords);
+        }
+        // Frontmatter
+        if (ext === ".md") {
+            const fm = extractFrontmatterDescription(file);
+            if (fm) {
+                entry.description = fm;
+                entry.source = "frontmatter";
+                entry.confidence = 0.9;
+            }
+        }
+        // Renderer metadata extraction
+        const renderer = getRenderer(match.renderer);
+        if (renderer?.extractMetadata) {
+            const renderCtx = buildRenderContext(ctx, match, [stashRoot]);
+            renderer.extractMetadata(entry, renderCtx);
+        }
+        // Filename heuristics fallback
+        if (!entry.description) {
+            entry.description = fileNameToDescription(baseName);
+            entry.source = "filename";
+            entry.confidence = Math.min(entry.confidence ?? 0.55, 0.55);
+        }
+        if (!entry.tags || entry.tags.length === 0) {
+            entry.tags = extractTagsFromPath(file, dirPath);
+        }
+        entry.tags = normalizeTerms(entry.tags ?? []);
+        entry.aliases = buildAliases(canonicalName, entry.tags);
+        entry.filename = path.basename(file);
+        entries.push(entry);
+    }
+    return { entries };
+}
+function normalizeTerms(values) {
+    const normalized = new Set();
+    for (const value of values) {
+        const cleaned = value.toLowerCase().replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim();
+        if (!cleaned)
+            continue;
+        normalized.add(cleaned);
+        if (cleaned.endsWith("s") && cleaned.length > 3) {
+            normalized.add(cleaned.slice(0, -1));
+        }
+    }
+    return Array.from(normalized);
+}
+function buildAliases(name, tags) {
+    const aliases = new Set();
+    const spaced = name.replace(/[-_]+/g, " ").trim().toLowerCase();
+    if (spaced && spaced !== name.toLowerCase())
+        aliases.add(spaced);
+    if (tags.length > 1)
+        aliases.add(tags.join(" "));
+    return Array.from(aliases);
+}
+export function extractDescriptionFromComments(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const lines = content.split(/\r?\n/).slice(0, 50);
+    // Try JSDoc-style block comment: /** ... */
+    const blockStart = lines.findIndex((l) => /^\s*\/\*\*/.test(l));
+    if (blockStart >= 0) {
+        const desc = [];
+        for (let i = blockStart; i < lines.length; i++) {
+            const line = lines[i];
+            if (i > blockStart && /\*\//.test(line))
+                break;
+            const cleaned = line
+                .replace(/^\s*\/?\*\*?\s?/, "")
+                .replace(/\*\/\s*$/, "")
+                .trim();
+            if (cleaned)
+                desc.push(cleaned);
+        }
+        if (desc.length > 0)
+            return desc.join(" ");
+    }
+    // Try hash comments at start of file (skip shebang)
+    let start = 0;
+    if (lines[0]?.startsWith("#!"))
+        start = 1;
+    const hashLines = [];
+    for (let i = start; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.startsWith("#") && !line.startsWith("#!")) {
+            hashLines.push(line.replace(/^#+\s*/, "").trim());
+        }
+        else if (line === "") {
+        }
+        else {
+            break;
+        }
+    }
+    if (hashLines.length > 0)
+        return hashLines.join(" ");
+    return null;
+}
+export function extractFrontmatterDescription(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const parsed = parseFrontmatter(content);
+    return toStringOrUndefined(parsed.data.description) ?? null;
+}
+export function extractPackageMetadata(dirPath) {
+    const pkgPath = path.join(dirPath, "package.json");
+    if (!fs.existsSync(pkgPath))
+        return null;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        const result = {};
+        if (typeof pkg.name === "string")
+            result.name = pkg.name;
+        if (typeof pkg.description === "string")
+            result.description = pkg.description;
+        if (Array.isArray(pkg.keywords)) {
+            result.keywords = pkg.keywords.filter((k) => typeof k === "string");
+        }
+        return Object.keys(result).length > 0 ? result : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function fileNameToDescription(fileName) {
+    return fileName
+        .replace(/[-_]+/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .trim();
+}
+export function extractTagsFromPath(filePath, rootDir) {
+    const rel = path.relative(rootDir, filePath);
+    const parts = rel.split(path.sep);
+    const tags = new Set();
+    for (const part of parts) {
+        const name = part.replace(path.extname(part), "");
+        for (const token of name.split(/[-_./\\]+/)) {
+            const clean = token.toLowerCase().trim();
+            if (clean && clean.length > 1)
+                tags.add(clean);
+        }
+    }
+    return Array.from(tags);
+}

package/dist/origin-resolve.js

@@ -0,0 +1,54 @@
+import path from "node:path";
+import { parseRegistryRef } from "./registry-resolve";
+/**
+ * Given an origin string (from an AssetRef) and the full list of stash
+ * sources, return the subset of sources to search.
+ *
+ * Resolution order:
+ *   1. undefined   → all sources
+ *   2. "local"     → primary stash only (first entry)
+ *   3. exact match → source whose registryId matches verbatim
+ *   4. parsed match → parse origin as a registry ref, match by parsed ID
+ *   5. path match  → source whose resolved path matches the origin
+ *   6. empty       → indicates a remote/uninstalled origin (caller decides)
+ */
+export function resolveSourcesForOrigin(origin, allSources) {
+    if (!origin)
+        return allSources;
+    // "local" means the primary stash (first entry)
+    if (origin === "local") {
+        return allSources.length > 0 ? [allSources[0]] : [];
+    }
+    // Exact registryId match (e.g. origin is "npm:@scope/pkg")
+    const byExactId = allSources.filter((s) => s.registryId !== undefined && s.registryId === origin);
+    if (byExactId.length > 0)
+        return byExactId;
+    // Parse origin as a registry ref and match by parsed ID.
+    // Allows shorthand: "owner/repo" matches "github:owner/repo",
+    // "@scope/pkg" matches "npm:@scope/pkg".
+    try {
+        const parsed = parseRegistryRef(origin);
+        const byParsedId = allSources.filter((s) => s.registryId !== undefined && s.registryId === parsed.id);
+        if (byParsedId.length > 0)
+            return byParsedId;
+    }
+    catch {
+        // Not a valid registry ref — continue to path matching
+    }
+    // Match by resolved path (any source, including installed)
+    const resolvedOrigin = path.resolve(origin);
+    const byPath = allSources.filter((s) => path.resolve(s.path) === resolvedOrigin);
+    if (byPath.length > 0)
+        return byPath;
+    // No match — origin may be remote/uninstalled
+    return [];
+}
+/**
+ * Check whether an origin refers to something that could be fetched remotely
+ * (i.e. it looks like a registry ref but isn't installed locally).
+ */
+export function isRemoteOrigin(origin, allSources) {
+    if (origin === "local")
+        return false;
+    return resolveSourcesForOrigin(origin, allSources).length === 0;
+}

package/dist/paths.js

@@ -0,0 +1,92 @@
+/**
+ * Centralized path resolution for all akm directories.
+ *
+ * Provides platform-aware paths for config, cache, and stash directories,
+ * following XDG Base Directory conventions on Unix and standard locations
+ * on Windows.
+ */
+import path from "node:path";
+import { ConfigError } from "./errors";
+const IS_WINDOWS = process.platform === "win32";
+// ── Config directory ─────────────────────────────────────────────────────────
+export function getConfigDir(env = process.env, platform = process.platform) {
+    const override = env.AKM_CONFIG_DIR?.trim();
+    if (override)
+        return override;
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim();
+        if (appData)
+            return path.join(appData, "akm");
+        const userProfile = env.USERPROFILE?.trim();
+        if (!userProfile) {
+            throw new ConfigError("Unable to determine config directory. Set APPDATA or USERPROFILE.");
+        }
+        return path.join(userProfile, "AppData", "Roaming", "akm");
+    }
+    const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
+    if (xdgConfigHome)
+        return path.join(xdgConfigHome, "akm");
+    const home = env.HOME?.trim();
+    if (!home) {
+        throw new ConfigError("Unable to determine config directory. Set XDG_CONFIG_HOME or HOME.");
+    }
+    return path.join(home, ".config", "akm");
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), "config.json");
+}
+// ── Cache directory ──────────────────────────────────────────────────────────
+export function getCacheDir() {
+    const override = process.env.AKM_CACHE_DIR?.trim();
+    if (override)
+        return override;
+    if (IS_WINDOWS) {
+        const localAppData = process.env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm");
+        const userProfile = process.env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm");
+        const appData = process.env.APPDATA?.trim();
+        if (!appData) {
+            throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.");
+        }
+        return path.join(appData, "..", "Local", "akm");
+    }
+    const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+    if (xdgCacheHome)
+        return path.join(xdgCacheHome, "akm");
+    const home = process.env.HOME?.trim();
+    if (!home)
+        return path.join("/tmp", "akm-cache");
+    return path.join(home, ".cache", "akm");
+}
+export function getDbPath() {
+    return path.join(getCacheDir(), "index.db");
+}
+export function getRegistryCacheDir() {
+    return path.join(getCacheDir(), "registry");
+}
+export function getRegistryIndexCacheDir() {
+    return path.join(getCacheDir(), "registry-index");
+}
+export function getBinDir() {
+    return path.join(getCacheDir(), "bin");
+}
+// ── Default stash directory ──────────────────────────────────────────────────
+export function getDefaultStashDir() {
+    const override = process.env.AKM_STASH_DIR?.trim();
+    if (override)
+        return override;
+    if (IS_WINDOWS) {
+        const userProfile = process.env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "Documents", "akm");
+        return path.join("C:\\", "akm");
+    }
+    const home = process.env.HOME?.trim();
+    if (!home) {
+        throw new ConfigError("Unable to determine default stash directory. Set HOME.");
+    }
+    return path.join(home, "akm");
+}