akm-cli 0.0.0 → 0.0.17

package/dist/stash-source.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStashDir } from "./common";
+import { loadConfig } from "./config";
+import { warn } from "./warn";
+// ── Resolution ──────────────────────────────────────────────────────────────
+/**
+ * Build the ordered list of stash sources (search paths):
+ *   1. Primary stash dir (user's own, destination for clone)
+ *   2. Additional search paths (user-configured)
+ *   3. Installed kit paths (cache-managed, from registry)
+ *
+ * The first entry is always the primary stash. Additional entries come
+ * from `searchPaths` config and `installed` kit entries.
+ */
+export function resolveStashSources(overrideStashDir, existingConfig) {
+    const stashDir = overrideStashDir ?? resolveStashDir();
+    const config = existingConfig ?? loadConfig();
+    const sources = [{ path: stashDir }];
+    for (const dir of config.searchPaths) {
+        if (isSuspiciousStashRoot(dir)) {
+            warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
+        }
+        if (isValidDirectory(dir)) {
+            sources.push({ path: dir });
+        }
+    }
+    for (const entry of config.installed ?? []) {
+        if (isSuspiciousStashRoot(entry.stashRoot)) {
+            warn(`Warning: stash root "${entry.stashRoot}" appears to be a system directory. This may be unintentional.`);
+        }
+        if (isValidDirectory(entry.stashRoot)) {
+            sources.push({
+                path: entry.stashRoot,
+                registryId: entry.id,
+            });
+        }
+    }
+    return sources;
+}
+/**
+ * Convenience: returns just the directory paths, preserving priority order.
+ */
+export function resolveAllStashDirs(overrideStashDir) {
+    return resolveStashSources(overrideStashDir).map((s) => s.path);
+}
+/**
+ * Find which source a file path belongs to.
+ */
+export function findSourceForPath(filePath, sources) {
+    const resolved = path.resolve(filePath);
+    for (const source of sources) {
+        if (resolved.startsWith(path.resolve(source.path) + path.sep))
+            return source;
+    }
+    return undefined;
+}
+/**
+ * Return the primary stash source (first entry in the list).
+ * This is the user's working stash and the default destination for clone.
+ */
+export function getPrimarySource(sources) {
+    return sources[0];
+}
+// ── Editability ─────────────────────────────────────────────────────────────
+/**
+ * Determine whether a file is safe to edit in place.
+ *
+ * The only files that are NOT editable are those inside a cache directory
+ * managed by the package manager (`installed[].cacheDir`). These
+ * will be overwritten by `akm update` without warning.
+ *
+ * Everything else — working stash, search paths, local project dirs — is
+ * the user's domain to manage.
+ */
+export function isEditable(filePath, config) {
+    const cfg = config ?? loadConfig();
+    const resolved = path.resolve(filePath);
+    const cacheManaged = cfg.installed ?? [];
+    const isWin = process.platform === "win32";
+    for (const entry of cacheManaged) {
+        // Local sources reference original paths — always editable
+        if (entry.source === "local")
+            continue;
+        const cacheRoot = path.resolve(entry.cacheDir);
+        if (isWin) {
+            // Windows paths are case-insensitive — normalize both sides
+            if (resolved.toLowerCase().startsWith(cacheRoot.toLowerCase() + path.sep))
+                return false;
+        }
+        else {
+            if (resolved.startsWith(cacheRoot + path.sep))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Build an actionable hint for the agent when a file is not editable.
+ * Callers must check `isEditable()` before calling — this function
+ * unconditionally returns the hint string.
+ */
+export function buildEditHint(_filePath, assetType, assetName, origin) {
+    const ref = origin ? `${origin}//${assetType}:${assetName}` : `${assetType}:${assetName}`;
+    return `This asset is managed by akm and may be overwritten on update. To edit, run: akm clone ${ref}`;
+}
+// ── Validation ──────────────────────────────────────────────────────────────
+const SUSPICIOUS_ROOTS = new Set(["/", "/etc", "/bin", "/sbin", "/usr", "/var", "/tmp", "/dev", "/proc", "/sys"]);
+function isSuspiciousStashRoot(dir) {
+    const resolved = path.resolve(dir);
+    const normalized = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+    if (SUSPICIOUS_ROOTS.has(normalized))
+        return true;
+    if (process.platform === "win32") {
+        // Check for Windows system directories
+        const winDir = (process.env.SystemRoot || "C:\\Windows").toLowerCase();
+        if (normalized === winDir || normalized.startsWith(winDir + path.sep))
+            return true;
+    }
+    return false;
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function isValidDirectory(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/stash-types.js

@@ -0,0 +1 @@
+export {};

package/dist/walker.js

@@ -0,0 +1,163 @@
+/**
+ * Shared filesystem walker for akm stash directories.
+ *
+ * Provides a single implementation used by both the search fallback
+ * (stash.ts) and the indexer (indexer.ts) to walk type-specific asset
+ * directories and group files by parent directory.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { isRelevantAssetFile } from "./asset-spec";
+import { buildFileContext } from "./file-context";
+/**
+ * Walk a type root directory and return files grouped by their parent directory.
+ *
+ * Only files relevant to the given `assetType` are included (e.g. `.md` for
+ * commands, script extensions for scripts, `SKILL.md` for skills).
+ */
+export function walkStash(typeRoot, assetType) {
+    if (!fs.existsSync(typeRoot))
+        return [];
+    const groups = new Map();
+    const stack = [typeRoot];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = fs.readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === ".stash.json")
+                continue;
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(fullPath);
+            }
+            else if (entry.isFile() && isRelevantAssetFile(assetType, entry.name)) {
+                const parentDir = path.dirname(fullPath);
+                const existing = groups.get(parentDir);
+                if (existing) {
+                    existing.push(fullPath);
+                }
+                else {
+                    groups.set(parentDir, [fullPath]);
+                }
+            }
+        }
+    }
+    return Array.from(groups, ([dirPath, files]) => ({ dirPath, files }));
+}
+/**
+ * Walk an entire stash root directory and return FileContext objects for every
+ * regular file found.
+ *
+ * Unlike walkStash(), this does NOT filter by asset type or require files to
+ * live under type-specific directories. Matchers decide what each file is.
+ *
+ * If the directory is a git repo, uses `git ls-files` to respect .gitignore.
+ * Otherwise falls back to a manual walk that skips .git, node_modules, bin,
+ * .cache, dot-directories, and .stash.json files.
+ */
+export function walkStashFlat(stashRoot) {
+    if (!fs.existsSync(stashRoot))
+        return [];
+    // Try git-based walk first (respects .gitignore)
+    const gitResult = walkStashGit(stashRoot);
+    if (gitResult)
+        return gitResult;
+    // Fallback: manual walk
+    return walkStashManual(stashRoot);
+}
+/**
+ * Walk using `git ls-files` to respect .gitignore.
+ * Returns null if the directory is not a git repo or git fails.
+ */
+function walkStashGit(stashRoot) {
+    // Quick check: is this a git repo? Look for .git in this dir or parents.
+    if (!isInsideGitRepo(stashRoot))
+        return null;
+    // Get tracked + untracked (non-ignored) files
+    const result = spawnSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", "."], {
+        cwd: stashRoot,
+        encoding: "utf8",
+        timeout: 30_000,
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+    });
+    if (result.status !== 0)
+        return null;
+    const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
+    const SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
+    const files = result.stdout
+        .split("\0")
+        .filter((f) => f.length > 0)
+        .filter((f) => !f.startsWith("..") && !path.isAbsolute(f))
+        .filter((f) => {
+        const dirParts = path
+            .dirname(f)
+            .split(/[\\/]+/)
+            .filter(Boolean);
+        return !dirParts.some((part) => SKIP_DIRS.has(part) || part.startsWith("."));
+    })
+        .filter((f) => !SKIP_FILES.has(path.basename(f)))
+        .filter((f) => !f.includes("/.") && !f.startsWith(".")); // skip dot-dirs/files
+    const results = [];
+    for (const relFile of files) {
+        const absPath = path.join(stashRoot, relFile);
+        try {
+            if (fs.statSync(absPath).isFile()) {
+                results.push(buildFileContext(stashRoot, absPath));
+            }
+        }
+        catch {
+            // File may have been deleted since git ls-files ran
+        }
+    }
+    return results;
+}
+/** Check if a directory is inside a git repository by walking up to find .git. */
+function isInsideGitRepo(dir) {
+    let current = path.resolve(dir);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        try {
+            const gitDir = path.join(current, ".git");
+            const stat = fs.statSync(gitDir);
+            if (stat.isDirectory() || stat.isFile())
+                return true;
+        }
+        catch {
+            // .git doesn't exist at this level, keep climbing
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return false;
+}
+/** 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();
+        if (!current)
+            continue;
+        const entries = fs.readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === ".stash.json")
+                continue;
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                    continue;
+                stack.push(fullPath);
+            }
+            else if (entry.isFile()) {
+                results.push(buildFileContext(stashRoot, fullPath));
+            }
+        }
+    }
+    return results;
+}

package/dist/warn.js

@@ -0,0 +1,20 @@
+/**
+ * Module-level quiet flag for suppressing stderr warnings.
+ * Controlled by the CLI --quiet / -q flag.
+ */
+let quiet = false;
+export function setQuiet(value) {
+    quiet = value;
+}
+export function isQuiet() {
+    return quiet;
+}
+/**
+ * Emit a warning to stderr unless --quiet is active.
+ * Drop-in replacement for console.warn() across the codebase.
+ */
+export function warn(...args) {
+    if (!quiet) {
+        console.warn(...args);
+    }
+}

package/package.json

@@ -1,17 +1,63 @@
 {
   "name": "akm-cli",
-  "version": "0.0.0",
-  "description": "Placeholder — akm (the Agent-i-Kit) is coming soon. https://github.com/itlackey/agentikit",
-  "bin": { "akm": "index.js" },
-  "keywords": ["akm", "agent-i-kit", "ai-agent", "cli", "package-manager"],
-  "license": "MPL-2.0",
-  "author": "itlackey",
+  "version": "0.0.17",
+  "type": "module",
+  "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
+  "keywords": [
+    "akm",
+    "agent-i-kit",
+    "ai-agent",
+    "agent-framework",
+    "developer-tools",
+    "cli",
+    "tools",
+    "skills",
+    "commands"
+  ],
+  "homepage": "https://github.com/itlackey/agentikit#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/itlackey/agentikit.git"
   },
-  "homepage": "https://github.com/itlackey/agentikit#readme",
   "bugs": {
     "url": "https://github.com/itlackey/agentikit/issues"
+  },
+  "license": "MPL-2.0",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "akm": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun run tsc --project ./tsconfig.json --outDir dist",
+    "check": "bun run lint && bunx tsc --noEmit && bun test ./tests",
+    "check:changed": "bun test tests/output-baseline.test.ts tests/e2e.test.ts tests/stash-search.test.ts && bun run lint && bunx tsc --noEmit",
+    "test": "bun test ./tests",
+    "lint": "bunx biome check src/ tests/",
+    "lint:fix": "bunx biome check --write src/ tests/",
+    "format": "bunx biome format --write src/ tests/",
+    "prepublishOnly": "bun run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/node": "^22.0.0",
+    "bun-types": "^1.3.10",
+    "typescript": "^5.9.3"
+  },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.0",
+    "sqlite-vec": "0.1.7-alpha.2"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "citty": "^0.2.1"
   }
 }

package/index.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-console.log("akm (the Agent-i-Kit) is coming soon.");
-console.log("See: https://github.com/itlackey/agentikit");
-process.exit(0);