akm-cli 0.0.0 → 0.0.16

package/dist/stash-ref.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { isAssetType } from "./common";
+import { UsageError } from "./errors";
+// ── Construction ────────────────────────────────────────────────────────────
+/**
+ * Build a ref string from components.
+ *
+ * Examples:
+ *   makeAssetRef("tool", "deploy.sh")
+ *     → "tool:deploy.sh"
+ *   makeAssetRef("tool", "deploy.sh", "npm:@scope/pkg")
+ *     → "npm:@scope/pkg//tool:deploy.sh"
+ *   makeAssetRef("skill", "code-review", "local")
+ *     → "local//skill:code-review"
+ *   makeAssetRef("tool", "db/migrate/run.sh", "owner/repo")
+ *     → "owner/repo//tool:db/migrate/run.sh"
+ */
+export function makeAssetRef(type, name, origin) {
+    validateName(name);
+    const normalized = normalizeName(name);
+    // "tool" is a transparent alias for "script" -- normalize to "script" in refs
+    const resolvedType = type === "tool" ? "script" : type;
+    const asset = `${resolvedType}:${normalized}`;
+    if (!origin)
+        return asset;
+    return `${origin}//${asset}`;
+}
+// ── Parsing ─────────────────────────────────────────────────────────────────
+/**
+ * Parse a ref string in the format `[origin//]type:name`.
+ */
+export function parseAssetRef(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new UsageError("Empty ref.");
+    let origin;
+    let body = trimmed;
+    const boundary = trimmed.indexOf("//");
+    if (boundary >= 0) {
+        origin = trimmed.slice(0, boundary);
+        body = trimmed.slice(boundary + 2);
+        if (!origin)
+            throw new UsageError("Empty origin in ref.");
+    }
+    const colon = body.indexOf(":");
+    if (colon <= 0) {
+        throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name`);
+    }
+    const rawType = body.slice(0, colon);
+    const rawName = body.slice(colon + 1);
+    if (!isAssetType(rawType)) {
+        throw new UsageError(`Invalid asset type: "${rawType}".`);
+    }
+    validateName(rawName);
+    const name = normalizeName(rawName);
+    return { type: rawType, name, origin: origin || undefined };
+}
+// ── Validation ──────────────────────────────────────────────────────────────
+function validateName(name) {
+    if (!name)
+        throw new UsageError("Empty asset name.");
+    if (name.includes("\0"))
+        throw new UsageError("Null byte in asset name.");
+    if (/^[A-Za-z]:/.test(name))
+        throw new UsageError("Windows drive path in asset name.");
+    const normalized = path.posix.normalize(name.replace(/\\/g, "/"));
+    if (path.posix.isAbsolute(normalized))
+        throw new UsageError("Absolute path in asset name.");
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new UsageError("Path traversal in asset name.");
+    }
+}
+function normalizeName(name) {
+    return path.posix.normalize(name.replace(/\\/g, "/"));
+}

package/dist/stash-registry.js

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+import { resolveStashDir } from "./common";
+import { loadConfig } from "./config";
+import { NotFoundError, UsageError } from "./errors";
+import { agentikitIndex } from "./indexer";
+import { removeLockEntry, upsertLockEntry } from "./lockfile";
+import { installRegistryRef, removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./registry-install";
+import { parseRegistryRef } from "./registry-resolve";
+export async function agentikitList(input) {
+    const stashDir = input?.stashDir ?? resolveStashDir();
+    const config = loadConfig();
+    const installed = config.registry?.installed ?? [];
+    return {
+        schemaVersion: 1,
+        stashDir,
+        installed: installed.map((entry) => ({
+            ...entry,
+            status: {
+                cacheDirExists: directoryExists(entry.cacheDir),
+                stashRootExists: directoryExists(entry.stashRoot),
+            },
+        })),
+        totalInstalled: installed.length,
+    };
+}
+export async function agentikitRemove(input) {
+    const target = input.target.trim();
+    if (!target)
+        throw new UsageError("Target is required.");
+    const stashDir = input.stashDir ?? resolveStashDir();
+    const config = loadConfig();
+    const installed = config.registry?.installed ?? [];
+    const entry = resolveInstalledTarget(installed, target);
+    const updatedConfig = removeInstalledRegistryEntry(entry.id);
+    removeLockEntry(entry.id);
+    // Only clean up cache for non-local sources — local sources point to the
+    // user's real directory on disk and must never be deleted.
+    if (entry.source !== "local") {
+        cleanupDirectoryBestEffort(entry.cacheDir);
+    }
+    const index = await agentikitIndex({ stashDir });
+    return {
+        schemaVersion: 1,
+        stashDir,
+        target,
+        removed: {
+            id: entry.id,
+            source: entry.source,
+            ref: entry.ref,
+            cacheDir: entry.cacheDir,
+            stashRoot: entry.stashRoot,
+        },
+        config: {
+            searchPaths: updatedConfig.searchPaths,
+            installedRegistryCount: updatedConfig.registry?.installed.length ?? 0,
+        },
+        index: {
+            mode: index.mode,
+            totalEntries: index.totalEntries,
+            directoriesScanned: index.directoriesScanned,
+            directoriesSkipped: index.directoriesSkipped,
+        },
+    };
+}
+export async function agentikitUpdate(input) {
+    const stashDir = input?.stashDir ?? resolveStashDir();
+    const target = input?.target?.trim();
+    const all = input?.all === true;
+    const force = input?.force === true;
+    const installedEntries = loadConfig().registry?.installed ?? [];
+    const selectedEntries = selectTargets(installedEntries, target, all);
+    const processed = [];
+    for (const entry of selectedEntries) {
+        if (force && shouldCleanupCache(entry)) {
+            cleanupDirectoryBestEffort(entry.cacheDir);
+        }
+        const installed = await installRegistryRef(entry.ref);
+        upsertInstalledRegistryEntry(toInstalledEntry(installed));
+        upsertLockEntry({
+            id: installed.id,
+            source: installed.source,
+            ref: installed.ref,
+            resolvedVersion: installed.resolvedVersion,
+            resolvedRevision: installed.resolvedRevision,
+            integrity: installed.integrity ?? (installed.source === "local" ? "local" : undefined),
+        });
+        if (entry.cacheDir !== installed.cacheDir && shouldCleanupCache(entry)) {
+            cleanupDirectoryBestEffort(entry.cacheDir);
+        }
+        const versionChanged = (entry.resolvedVersion ?? "") !== (installed.resolvedVersion ?? "");
+        const revisionChanged = (entry.resolvedRevision ?? "") !== (installed.resolvedRevision ?? "");
+        processed.push({
+            id: entry.id,
+            source: entry.source,
+            ref: entry.ref,
+            previous: {
+                resolvedVersion: entry.resolvedVersion,
+                resolvedRevision: entry.resolvedRevision,
+                cacheDir: entry.cacheDir,
+            },
+            installed: toInstallStatus(installed),
+            changed: {
+                version: versionChanged,
+                revision: revisionChanged,
+                any: versionChanged || revisionChanged,
+            },
+        });
+    }
+    const index = await agentikitIndex({ stashDir });
+    const config = loadConfig();
+    return {
+        schemaVersion: 1,
+        stashDir,
+        target,
+        all,
+        processed,
+        config: {
+            searchPaths: config.searchPaths,
+            installedRegistryCount: config.registry?.installed.length ?? 0,
+        },
+        index: {
+            mode: index.mode,
+            totalEntries: index.totalEntries,
+            directoriesScanned: index.directoriesScanned,
+            directoriesSkipped: index.directoriesSkipped,
+        },
+    };
+}
+function selectTargets(installed, target, all) {
+    if (all && target) {
+        throw new UsageError("Specify either <target> or --all, not both.");
+    }
+    if (all)
+        return installed;
+    if (!target) {
+        throw new UsageError("Either <target> or --all is required.");
+    }
+    return [resolveInstalledTarget(installed, target)];
+}
+function resolveInstalledTarget(installed, target) {
+    const byId = installed.find((entry) => entry.id === target);
+    if (byId)
+        return byId;
+    const byRef = installed.find((entry) => entry.ref === target);
+    if (byRef)
+        return byRef;
+    let parsedId;
+    try {
+        parsedId = parseRegistryRef(target).id;
+    }
+    catch {
+        parsedId = undefined;
+    }
+    if (parsedId) {
+        const byParsedId = installed.find((entry) => entry.id === parsedId);
+        if (byParsedId)
+            return byParsedId;
+    }
+    throw new NotFoundError(`No installed registry entry matched target: ${target}`);
+}
+function toInstalledEntry(status) {
+    return {
+        id: status.id,
+        source: status.source,
+        ref: status.ref,
+        artifactUrl: status.artifactUrl,
+        resolvedVersion: status.resolvedVersion,
+        resolvedRevision: status.resolvedRevision,
+        stashRoot: status.stashRoot,
+        cacheDir: status.cacheDir,
+        installedAt: status.installedAt,
+    };
+}
+function toInstallStatus(status) {
+    return {
+        id: status.id,
+        source: status.source,
+        ref: status.ref,
+        artifactUrl: status.artifactUrl,
+        resolvedVersion: status.resolvedVersion,
+        resolvedRevision: status.resolvedRevision,
+        stashRoot: status.stashRoot,
+        cacheDir: status.cacheDir,
+        extractedDir: status.extractedDir,
+        installedAt: status.installedAt,
+    };
+}
+function cleanupDirectoryBestEffort(target) {
+    try {
+        fs.rmSync(target, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort cleanup only.
+    }
+}
+function shouldCleanupCache(entry) {
+    return entry.source !== "local";
+}
+function directoryExists(target) {
+    try {
+        return fs.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/stash-resolve.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
+import { hasErrnoCode, isWithin, normalizeAssetType } from "./common";
+import { NotFoundError, UsageError } from "./errors";
+/**
+ * Resolve an asset path from a stash directory, type, and name.
+ *
+ * When `type` is "script" or "tool" (which is a transparent alias for "script"),
+ * resolution tries both the primary type directory and the alias directory:
+ *   - script → tries scripts/ then tools/
+ *   - tool   → tries tools/ then scripts/
+ * This ensures that `script:deploy.sh` can find files in either `scripts/` or `tools/`.
+ */
+export function resolveAssetPath(stashDir, type, name) {
+    // For script/tool, try the primary directory first, then the alias directory.
+    if (type === "script" || type === "tool") {
+        const primaryDir = TYPE_DIRS[type];
+        const aliasDir = type === "script" ? "tools" : "scripts";
+        const dirsToTry = [primaryDir, aliasDir];
+        let primaryError;
+        let lastError;
+        for (let i = 0; i < dirsToTry.length; i++) {
+            try {
+                return resolveInTypeDir(stashDir, dirsToTry[i], type, name);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                if (i === 0)
+                    primaryError = error;
+                lastError = error;
+                // Only fall through on NotFoundError -- rethrow security/usage errors immediately
+                if (err instanceof UsageError)
+                    throw err;
+            }
+        }
+        // Prefer the primary directory's error when it's about extension validation
+        // (i.e., the file was found but had the wrong extension) over a generic
+        // "not found" from the alias directory.
+        const errorToThrow = primaryError?.message.includes("supported script extension")
+            ? primaryError
+            : (lastError ?? new NotFoundError(`Stash asset not found for ref: ${normalizeAssetType(type)}:${name}`));
+        throw errorToThrow;
+    }
+    return resolveInTypeDir(stashDir, TYPE_DIRS[type], type, name);
+}
+/**
+ * Try to resolve an asset path within a specific type directory.
+ */
+function resolveInTypeDir(stashDir, typeDir, type, name) {
+    const root = path.join(stashDir, typeDir);
+    const target = resolveAssetPathFromName(type, root, name);
+    const resolvedRoot = resolveAndValidateTypeRoot(root, type, name);
+    const resolvedTarget = path.resolve(target);
+    if (!isWithin(resolvedTarget, resolvedRoot)) {
+        throw new UsageError("Ref resolves outside the stash root.");
+    }
+    if (!fs.existsSync(resolvedTarget) || !fs.statSync(resolvedTarget).isFile()) {
+        throw new NotFoundError(`Stash asset not found for ref: ${normalizeAssetType(type)}:${name}`);
+    }
+    const realTarget = fs.realpathSync(resolvedTarget);
+    if (!isWithin(realTarget, resolvedRoot)) {
+        throw new UsageError("Ref resolves outside the stash root.");
+    }
+    // Use "script" for relevance check since tool is an alias for script
+    const relevanceType = type === "tool" ? "script" : type;
+    if (!isRelevantAssetFile(relevanceType, path.basename(resolvedTarget))) {
+        if (type === "tool" || type === "script") {
+            throw new NotFoundError("Script ref must resolve to a file with a supported script extension. Refer to the akm documentation for the complete list of supported script extensions.");
+        }
+        throw new NotFoundError(`Stash asset not found for ref: ${normalizeAssetType(type)}:${name}`);
+    }
+    return realTarget;
+}
+function resolveAndValidateTypeRoot(root, type, name) {
+    const rootStat = readTypeRootStat(root, type, name);
+    if (!rootStat.isDirectory()) {
+        throw new NotFoundError(`Stash type root is not a directory for ref: ${normalizeAssetType(type)}:${name}`);
+    }
+    return fs.realpathSync(root);
+}
+function readTypeRootStat(root, type, name) {
+    try {
+        return fs.statSync(root);
+    }
+    catch (error) {
+        if (hasErrnoCode(error, "ENOENT")) {
+            throw new NotFoundError(`Stash type root not found for ref: ${normalizeAssetType(type)}:${name}`);
+        }
+        throw error;
+    }
+}