agentikit 0.0.13 → 0.0.15

package/dist/matchers.js

@@ -0,0 +1,163 @@
+/**
+ * Built-in asset matchers for the agentikit 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_BROAD } 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
+    if (ctx.fileName === "SKILL.md") {
+        return { type: "skill", specificity: 3, renderer: "skill-md" };
+    }
+    // Known script extensions (excluding .md, handled by smartMdMatcher)
+    if (SCRIPT_EXTENSIONS_BROAD.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.
+ *
+ * Accepts ALL known script extensions in both `tools/` and `scripts/`
+ * directories -- the distinction is purely organizational.
+ */
+export function directoryMatcher(ctx) {
+    const topDir = ctx.ancestorDirs[0];
+    if (!topDir)
+        return null;
+    const ext = ctx.ext;
+    if ((topDir === "tools" || topDir === "scripts") && SCRIPT_EXTENSIONS_BROAD.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`).
+ *
+ * Accepts ALL known script extensions in both `tools/` and `scripts/`.
+ */
+export function parentDirHintMatcher(ctx) {
+    const { parentDir, ext, fileName } = ctx;
+    if ((parentDir === "tools" || parentDir === "scripts") && SCRIPT_EXTENSIONS_BROAD.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);
+    }
+}

package/dist/{src/metadata.js → metadata.js}

@@ -1,9 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
+import { deriveCanonicalAssetName, isRelevantAssetFile } from "./asset-spec";
+import { tryGetHandler } from "./asset-type-handler";
 import { isAssetType } from "./common";
-import { isRelevantAssetFile, deriveCanonicalAssetName } from "./asset-spec";
 import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-import { tryGetHandler } from "./asset-type-handler";
+import { warn } from "./warn";
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
 export function stashFilePath(dirPath) {
@@ -20,8 +21,15 @@ export function loadStashFile(dirPath) {
         const entries = [];
         for (const e of raw.entries) {
             const validated = validateStashEntry(e);
-            if (validated)
+            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;
     }
@@ -31,7 +39,20 @@ export function loadStashFile(dirPath) {
 }
 export function writeStashFile(dirPath, stash) {
     const filePath = stashFilePath(dirPath);
-    fs.writeFileSync(filePath, JSON.stringify(stash, null, 2) + "\n", "utf8");
+    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)
@@ -74,7 +95,8 @@ export function validateStashEntry(entry) {
         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)) {
+    if (typeof e.source === "string" &&
+        ["package", "frontmatter", "comments", "filename", "manual", "llm"].includes(e.source)) {
         result.source = e.source;
     }
     if (Array.isArray(e.aliases)) {
@@ -87,9 +109,7 @@ export function validateStashEntry(entry) {
             if (typeof h !== "object" || h === null)
                 return false;
             const rec = h;
-            return typeof rec.level === "number"
-                && typeof rec.text === "string"
-                && typeof rec.line === "number";
+            return typeof rec.level === "number" && typeof rec.text === "string" && typeof rec.line === "number";
         });
         if (validated.length > 0)
             result.toc = validated;
@@ -123,9 +143,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
         // Skip non-relevant files
         if (!isRelevantAssetFile(assetType, fileName))
             continue;
-        const canonicalName = assetType === "skill"
-            ? deriveCanonicalAssetName(assetType, typeRoot, file) ?? baseName
-            : baseName;
+        const canonicalName = assetType === "skill" ? (deriveCanonicalAssetName(assetType, typeRoot, file) ?? baseName) : baseName;
         const entry = {
             name: canonicalName,
             type: assetType,
@@ -134,7 +152,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
             confidence: 0.55,
             source: "filename",
         };
-        // Priority 1: package.json metadata
+        // Priority 1: Package.json metadata
         if (pkgMeta) {
             if (pkgMeta.description && !entry.description) {
                 entry.description = pkgMeta.description;
@@ -144,7 +162,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
             if (pkgMeta.keywords && pkgMeta.keywords.length > 0)
                 entry.tags = normalizeTerms(pkgMeta.keywords);
         }
-        // Priority 2: Frontmatter (for .md files — overrides package.json description)
+        // Priority 2: Frontmatter (for .md files -- overrides package.json description)
         if (ext === ".md") {
             const fm = extractFrontmatterDescription(file);
             if (fm) {
@@ -153,7 +171,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
                 entry.confidence = 0.9;
             }
         }
-        // Type-specific metadata extraction (e.g. TOC for knowledge, comments for tools/scripts)
+        // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for tools/scripts)
         const handler = tryGetHandler(assetType);
         if (handler?.extractTypeMetadata) {
             handler.extractTypeMetadata(entry, file, ext);
@@ -215,7 +233,10 @@ export function extractDescriptionFromComments(filePath) {
             const line = lines[i];
             if (i > blockStart && /\*\//.test(line))
                 break;
-            const cleaned = line.replace(/^\s*\/?\*\*?\s?/, "").replace(/\*\/\s*$/, "").trim();
+            const cleaned = line
+                .replace(/^\s*\/?\*\*?\s?/, "")
+                .replace(/\*\/\s*$/, "")
+                .trim();
             if (cleaned)
                 desc.push(cleaned);
         }
@@ -233,7 +254,6 @@ export function extractDescriptionFromComments(filePath) {
             hashLines.push(line.replace(/^#+\s*/, "").trim());
         }
         else if (line === "") {
-            continue;
         }
         else {
             break;

package/dist/{src/origin-resolve.js → origin-resolve.js}

@@ -5,21 +5,22 @@ import { parseRegistryRef } from "./registry-resolve";
  * sources, return the subset of sources to search.
  *
  * Resolution order:
- *   1. undefined   → all sources (working → mounted → installed)
- *   2. "local"     → working stash only
- *   3. exact match → installed source whose registryId matches verbatim
+ *   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  → mounted source whose path matches
+ *   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.filter((s) => s.kind === "working");
+        return allSources.length > 0 ? [allSources[0]] : [];
     }
     // Exact registryId match (e.g. origin is "npm:@scope/pkg")
-    const byExactId = allSources.filter((s) => s.kind === "installed" && s.registryId === origin);
+    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.
@@ -27,16 +28,16 @@ export function resolveSourcesForOrigin(origin, allSources) {
     // "@scope/pkg" matches "npm:@scope/pkg".
     try {
         const parsed = parseRegistryRef(origin);
-        const byParsedId = allSources.filter((s) => s.kind === "installed" && s.registryId === parsed.id);
+        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
     }
-    // Mounted stash by resolved path
+    // Match by resolved path (any source, including installed)
     const resolvedOrigin = path.resolve(origin);
-    const byPath = allSources.filter((s) => s.kind === "mounted" && path.resolve(s.path) === resolvedOrigin);
+    const byPath = allSources.filter((s) => path.resolve(s.path) === resolvedOrigin);
     if (byPath.length > 0)
         return byPath;
     // No match — origin may be remote/uninstalled

package/dist/paths.js

@@ -0,0 +1,83 @@
+/**
+ * Centralized path resolution for all agentikit 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) {
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim();
+        if (appData)
+            return path.join(appData, "agentikit");
+        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", "agentikit");
+    }
+    const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
+    if (xdgConfigHome)
+        return path.join(xdgConfigHome, "agentikit");
+    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", "agentikit");
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), "config.json");
+}
+// ── Cache directory ──────────────────────────────────────────────────────────
+export function getCacheDir() {
+    if (IS_WINDOWS) {
+        const localAppData = process.env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "agentikit");
+        const userProfile = process.env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "agentikit");
+        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", "agentikit");
+    }
+    const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+    if (xdgCacheHome)
+        return path.join(xdgCacheHome, "agentikit");
+    const home = process.env.HOME?.trim();
+    if (!home)
+        return path.join("/tmp", "agentikit-cache");
+    return path.join(home, ".cache", "agentikit");
+}
+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() {
+    if (IS_WINDOWS) {
+        const userProfile = process.env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "Documents", "agentikit");
+        return path.join("C:\\", "agentikit");
+    }
+    const home = process.env.HOME?.trim();
+    if (!home) {
+        throw new ConfigError("Unable to determine default stash directory. Set HOME.");
+    }
+    return path.join(home, "agentikit");
+}