akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{installed-kits.js → commands/installed-stashes.js}

@@ -6,34 +6,38 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "./common";
-import { loadConfig } from "./config";
-import { NotFoundError, UsageError } from "./errors";
-import { akmIndex } from "./indexer";
-import { removeLockEntry, upsertLockEntry } from "./lockfile";
-import { installRegistryRef, removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./registry-install";
-import { parseRegistryRef } from "./registry-resolve";
-import { removeStash } from "./stash-source-manage";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { NotFoundError, UsageError } from "../core/errors";
+import { akmIndex } from "../indexer/indexer";
+import { removeLockEntry, upsertLockEntry } from "../integrations/lockfile";
+import { parseRegistryRef } from "../registry/resolve";
+import { syncFromRef } from "../sources/providers/sync-from-ref";
+import { ensureWebsiteMirror } from "../sources/providers/website";
+import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
+import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add";
+import { removeStash } from "./source-manage";
 export async function akmListSources(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
     const config = loadConfig();
     const kindFilter = input?.kind;
     const sources = [];
-    // Stash entries → local or remote sources
-    for (const stash of config.stashes ?? []) {
-        const isRemote = stash.url != null;
-        const kind = isRemote ? "remote" : "local";
+    // Stash entries — each entry exposes its provider type as kind (spec §2.1).
+    // Writable defaults: true for filesystem, false for git/npm/website (CLAUDE.md "Writes").
+    for (const stash of config.sources ?? config.stashes ?? []) {
+        const kind = stash.type ?? "filesystem";
         if (kindFilter && !kindFilter.includes(kind))
             continue;
+        const isFilesystem = kind === "filesystem";
+        const writableDefault = isFilesystem;
         const name = stash.name ?? stash.path ?? stash.url ?? "unknown";
         sources.push({
             name,
             kind,
             wiki: stash.wikiName,
             path: stash.path,
-            provider: isRemote ? stash.type : undefined,
-            updatable: false,
-            writable: stash.writable === true,
+            provider: stash.url != null ? stash.type : undefined,
+            writable: stash.writable !== undefined ? stash.writable : writableDefault,
             status: { exists: stash.path ? directoryExists(stash.path) : true },
         });
     }
@@ -49,7 +53,6 @@ export async function akmListSources(input) {
             path: entry.stashRoot,
             ref: entry.ref,
             version: entry.resolvedVersion,
-            updatable: true,
             writable: entry.writable === true,
             status: { exists: directoryExists(entry.stashRoot) },
         });
@@ -64,7 +67,7 @@ export async function akmListSources(input) {
 export async function akmRemove(input) {
     const target = input.target.trim();
     if (!target)
-        throw new UsageError("Target is required. Provide the source id, ref, path, URL, or name (e.g. `akm remove npm:@scope/kit` or `akm remove ~/my-stash`).");
+        throw new UsageError("Target is required. Provide the source id, ref, path, URL, or name (e.g. `akm remove npm:@scope/stash` or `akm remove ~/my-stash`).");
     const stashDir = input.stashDir ?? resolveStashDir();
     const config = loadConfig();
     const installed = config.installed ?? [];
@@ -89,7 +92,7 @@ export async function akmRemove(input) {
                 stashRoot: entry.stashRoot,
             },
             config: {
-                stashCount: updatedConfig.stashes?.length ?? 0,
+                sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
                 installedKitCount: updatedConfig.installed?.length ?? 0,
             },
             index: {
@@ -103,7 +106,7 @@ export async function akmRemove(input) {
     // Fall through to stashes[] (local/remote sources)
     const stashResult = removeStash(target);
     if (!stashResult.removed || !stashResult.entry) {
-        throw new NotFoundError(`No matching source for target: ${target}`);
+        throw new NotFoundError(`No matching source for target: ${target}`, "SOURCE_NOT_FOUND");
     }
     const removedEntry = stashResult.entry;
     const index = await akmIndex({ stashDir });
@@ -120,7 +123,7 @@ export async function akmRemove(input) {
             stashRoot: removedEntry.path ?? "",
         },
         config: {
-            stashCount: updatedConfig.stashes?.length ?? 0,
+            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -136,28 +139,102 @@ export async function akmUpdate(input) {
     const target = input?.target?.trim();
     const all = input?.all === true;
     const force = input?.force === true;
-    const installedEntries = loadConfig().installed ?? [];
+    const config = loadConfig();
+    const installedEntries = config.installed ?? [];
+    // Check if the target refers to a website source — those are syncable via
+    // ensureWebsiteMirror and are stored in sources[] not installed[].
+    if (target && !all) {
+        const stashes = config.sources ?? config.stashes ?? [];
+        const isUrl = target.startsWith("http://") || target.startsWith("https://");
+        const resolvedPath = !isUrl ? path.resolve(target) : undefined;
+        const websiteMatch = stashes.find((s) => {
+            if (s.type !== "website")
+                return false;
+            if (isUrl && s.url === target)
+                return true;
+            if (s.name === target)
+                return true;
+            if (resolvedPath && s.path && path.resolve(s.path) === resolvedPath)
+                return true;
+            return false;
+        });
+        if (websiteMatch) {
+            // TODO: full incremental re-crawl with delta tracking (#19)
+            await ensureWebsiteMirror(websiteMatch, { requireStashDir: true, force: true });
+            const index = await akmIndex({ stashDir });
+            const updatedConfig = loadConfig();
+            return {
+                schemaVersion: 1,
+                stashDir,
+                target,
+                all,
+                processed: [],
+                config: {
+                    sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+                    installedKitCount: updatedConfig.installed?.length ?? 0,
+                },
+                index: {
+                    mode: index.mode,
+                    totalEntries: index.totalEntries,
+                    directoriesScanned: index.directoriesScanned,
+                    directoriesSkipped: index.directoriesSkipped,
+                },
+            };
+        }
+    }
     const selectedEntries = selectTargets(installedEntries, target, all);
+    const auditConfig = config;
     const processed = [];
     for (const entry of selectedEntries) {
         if (force && shouldCleanupCache(entry)) {
             cleanupDirectoryBestEffort(entry.cacheDir);
         }
-        const installed = await installRegistryRef(entry.ref);
-        upsertInstalledRegistryEntry(toInstalledEntry(installed));
+        const synced = await syncFromRef(entry.ref, { force });
+        // Mirror the post-sync audit hook from akmAdd so `akm update` can't
+        // silently land malicious content during refresh.
+        const registryLabels = deriveRegistryLabels({
+            source: synced.source,
+            ref: synced.ref,
+            artifactUrl: synced.artifactUrl,
+        });
+        enforceRegistryInstallPolicy(registryLabels, auditConfig, entry.ref);
+        const audit = auditInstallCandidate({
+            rootDir: synced.extractedDir,
+            source: synced.source,
+            ref: synced.ref,
+            registryLabels,
+            config: auditConfig,
+        });
+        if (audit.blocked) {
+            throw new Error(formatInstallAuditFailure(synced.ref, audit));
+        }
+        const installedEntry = {
+            id: synced.id,
+            source: synced.source,
+            ref: synced.ref,
+            artifactUrl: synced.artifactUrl,
+            resolvedVersion: synced.resolvedVersion,
+            resolvedRevision: synced.resolvedRevision,
+            stashRoot: synced.contentDir,
+            cacheDir: synced.cacheDir,
+            installedAt: synced.syncedAt,
+            writable: synced.writable ?? entry.writable,
+            ...(entry.wikiName ? { wikiName: entry.wikiName } : {}),
+        };
+        upsertInstalledRegistryEntry(installedEntry);
         await upsertLockEntry({
-            id: installed.id,
-            source: installed.source,
-            ref: installed.ref,
-            resolvedVersion: installed.resolvedVersion,
-            resolvedRevision: installed.resolvedRevision,
-            integrity: installed.integrity ?? (installed.source === "local" ? "local" : undefined),
+            id: synced.id,
+            source: synced.source,
+            ref: synced.ref,
+            resolvedVersion: synced.resolvedVersion,
+            resolvedRevision: synced.resolvedRevision,
+            integrity: synced.integrity ?? (synced.source === "local" ? "local" : undefined),
         });
-        if (entry.cacheDir !== installed.cacheDir && shouldCleanupCache(entry)) {
+        if (entry.cacheDir !== synced.cacheDir && shouldCleanupCache(entry)) {
             cleanupDirectoryBestEffort(entry.cacheDir);
         }
-        const versionChanged = (entry.resolvedVersion ?? "") !== (installed.resolvedVersion ?? "");
-        const revisionChanged = (entry.resolvedRevision ?? "") !== (installed.resolvedRevision ?? "");
+        const versionChanged = (entry.resolvedVersion ?? "") !== (synced.resolvedVersion ?? "");
+        const revisionChanged = (entry.resolvedRevision ?? "") !== (synced.resolvedRevision ?? "");
         processed.push({
             id: entry.id,
             source: entry.source,
@@ -167,7 +244,7 @@ export async function akmUpdate(input) {
                 resolvedRevision: entry.resolvedRevision,
                 cacheDir: entry.cacheDir,
             },
-            installed: toInstallStatus(installed),
+            installed: { ...installedEntry, extractedDir: synced.extractedDir, audit },
             changed: {
                 version: versionChanged,
                 revision: revisionChanged,
@@ -176,7 +253,7 @@ export async function akmUpdate(input) {
         });
     }
     const index = await akmIndex({ stashDir });
-    const config = loadConfig();
+    const finalConfig = loadConfig();
     return {
         schemaVersion: 1,
         stashDir,
@@ -184,8 +261,8 @@ export async function akmUpdate(input) {
         all,
         processed,
         config: {
-            stashCount: config.stashes?.length ?? 0,
-            installedKitCount: config.installed?.length ?? 0,
+            sourceCount: (finalConfig.sources ?? finalConfig.stashes ?? []).length,
+            installedKitCount: finalConfig.installed?.length ?? 0,
         },
         index: {
             mode: index.mode,
@@ -197,19 +274,19 @@ export async function akmUpdate(input) {
 }
 function selectTargets(installed, target, all) {
     if (all && target) {
-        throw new UsageError("Specify either <target> or --all, not both.");
+        throw new UsageError("Specify either <target> or --all, not both.", "MISSING_OR_AMBIGUOUS_TARGET");
     }
     if (all)
         return installed;
     if (!target) {
-        throw new UsageError("Either <target> or --all is required.");
+        throw new UsageError("Either <target> or --all is required.", "MISSING_OR_AMBIGUOUS_TARGET");
     }
     const found = tryResolveInstalledTarget(installed, target);
     if (found)
         return [found];
     // Check if target matches a stash source and give a helpful message
     const config = loadConfig();
-    const stashes = config.stashes ?? [];
+    const stashes = config.sources ?? config.stashes ?? [];
     const isUrl = target.startsWith("http://") || target.startsWith("https://");
     const resolvedPath = !isUrl ? path.resolve(target) : undefined;
     const stashMatch = stashes.find((s) => {
@@ -222,10 +299,13 @@ function selectTargets(installed, target, all) {
         return false;
     });
     if (stashMatch) {
-        if (stashMatch.url) {
-            throw new UsageError(`"${target}" is a remote provider — it queries live data and has nothing to update.`);
+        if (stashMatch.type === "website") {
+            // Website sources should be handled before reaching selectTargets.
+            // This path should not be reached; surface a clear message if it is.
+            throw new UsageError(`"${target}" is a website source — website caching not yet implemented for --all. ` +
+                `Run \`akm update ${target}\` to re-mirror this source individually.`, "TARGET_NOT_UPDATABLE");
         }
-        throw new UsageError(`"${target}" is a local directory — it reflects your files in place. To refresh the search index, run: akm index`);
+        throw new UsageError(`"${target}" is a local directory — it reflects your files in place. To refresh the search index, run: akm index`, "TARGET_NOT_UPDATABLE");
     }
     throw new NotFoundError(`No matching source for target: ${target}`);
 }
@@ -250,14 +330,6 @@ function tryResolveInstalledTarget(installed, target) {
     }
     return undefined;
 }
-function toInstalledEntry(status) {
-    // KitInstallStatus extends InstalledKitEntry; omit transient install-only fields.
-    const { extractedDir: _extractedDir, audit: _audit, ...base } = status;
-    return base;
-}
-function toInstallStatus(status) {
-    return { ...status };
-}
 function cleanupDirectoryBestEffort(target) {
     try {
         fs.rmSync(target, { recursive: true, force: true });

package/dist/commands/migration-help.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/CHANGELOG.md";
+const MIGRATION_DOC_URL = "https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md";
+/**
+ * Directory containing per-version release notes. Resolved relative to
+ * `import.meta.dir` so the lookup works whether this module is running
+ * from source (`<repo>/src`) or from the published build (`<pkg>/dist`).
+ * The `docs/migration/release-notes/` directory is shipped via the
+ * `files[]` array in `package.json`.
+ */
+function releaseNotesDir() {
+    return path.resolve(import.meta.dir, "../../docs/migration/release-notes");
+}
+function loadChangelog() {
+    try {
+        const changelogPath = path.resolve(import.meta.dir, "../../CHANGELOG.md");
+        if (fs.existsSync(changelogPath)) {
+            return fs.readFileSync(changelogPath, "utf8");
+        }
+    }
+    catch {
+        // fall through to bundled notes
+    }
+    return undefined;
+}
+/**
+ * Load the bundled migration note for a specific version, if one exists.
+ * Returns the file body verbatim (no transformations). Missing files,
+ * permission errors, and non-file entries all return `undefined` —
+ * callers are responsible for the fallback message.
+ */
+function loadReleaseNote(version) {
+    if (!isSafeVersionComponent(version))
+        return undefined;
+    const notePath = path.join(releaseNotesDir(), `${version}.md`);
+    try {
+        if (!fs.existsSync(notePath))
+            return undefined;
+        const stat = fs.statSync(notePath);
+        if (!stat.isFile())
+            return undefined;
+        return fs.readFileSync(notePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Restrict version lookups to strings that are safe as a single path
+ * segment. Accepts typical semver forms (`0.6.0`, `0.6.0-rc1`,
+ * `0.6.0+build.5`) and rejects anything with slashes, `..`, or control
+ * characters that would let a crafted input escape the release-notes
+ * directory.
+ */
+function isSafeVersionComponent(version) {
+    if (!version || version.length > 64)
+        return false;
+    return /^[A-Za-z0-9._+-]+$/.test(version) && !version.includes("..");
+}
+function normalizeRequestedVersion(input) {
+    const value = input.trim();
+    if (!value)
+        return value;
+    if (value.toLowerCase() === "latest")
+        return "latest";
+    const withoutV = value.replace(/^v/i, "");
+    return withoutV;
+}
+function versionCandidates(requested) {
+    if (requested === "latest")
+        return ["latest"];
+    const exact = requested;
+    const stable = requested.replace(/[-+].*$/, "");
+    return stable === exact ? [exact] : [exact, stable];
+}
+function resolveLatestVersion(changelog) {
+    for (const match of changelog.matchAll(/^## \[([^\]]+)\]/gm)) {
+        const version = match[1];
+        if (version !== "Unreleased")
+            return version;
+    }
+    return undefined;
+}
+function extractChangelogSection(changelog, version) {
+    const pattern = new RegExp(`^## \\[${escapeRegexString(version)}\\][^\\n]*\\n([\\s\\S]*?)(?=^## \\[|\\Z)`, "m");
+    const match = changelog.match(pattern);
+    if (!match)
+        return undefined;
+    return `## [${version}]\n${match[1].trim()}\n`;
+}
+function escapeRegexString(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function fallbackGuide(version) {
+    const bundled = loadReleaseNote(version);
+    if (bundled)
+        return `${bundled.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+    const available = listBundledReleaseVersions();
+    const availableLine = available.length ? `\nAvailable bundled notes: ${available.join(", ")}\n` : "";
+    return (`No dedicated migration note is bundled for akm v${version}.\n${availableLine}\n` +
+        `See the full changelog: ${CHANGELOG_URL}\n` +
+        `Longform migration guide: ${MIGRATION_DOC_URL}\n`);
+}
+export function renderMigrationHelp(versionInput, changelogText = loadChangelog()) {
+    const requested = normalizeRequestedVersion(versionInput);
+    if (!requested) {
+        return `Version is required.\n\nUsage: akm help migrate <version>\n`;
+    }
+    const resolvedLatest = changelogText ? resolveLatestVersion(changelogText) : undefined;
+    const candidates = requested === "latest" && resolvedLatest ? [resolvedLatest] : versionCandidates(requested);
+    if (changelogText) {
+        for (const candidate of candidates) {
+            const section = extractChangelogSection(changelogText, candidate);
+            if (section) {
+                const bundled = loadReleaseNote(candidate);
+                if (!bundled)
+                    return `${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+                return `${bundled.trim()}\n\nRelease notes\n-------------\n${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+            }
+        }
+    }
+    const fallbackVersion = candidates.find((candidate) => candidate !== "latest") ?? requested;
+    return fallbackGuide(fallbackVersion);
+}
+/** Test-only helper — list every version with a bundled release note. */
+export function listBundledReleaseVersions() {
+    try {
+        const dir = releaseNotesDir();
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith(".md") && name !== "README.md")
+            .map((name) => name.slice(0, -".md".length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/{registry-search.js → commands/registry-search.js}

@@ -1,9 +1,8 @@
-import { toErrorMessage } from "./common";
-import { DEFAULT_CONFIG, loadConfig } from "./config";
-import { resolveProviderFactory } from "./registry-factory";
+import { toErrorMessage } from "../core/common";
+import { DEFAULT_CONFIG, loadConfig } from "../core/config";
+import { resolveProviderFactory } from "../registry/factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
-import "./providers/static-index";
-import "./providers/skills-sh";
+import "../registry/providers/index";
 // ── Public API ──────────────────────────────────────────────────────────────
 export async function searchRegistry(query, options) {
     const trimmed = query.trim();
@@ -25,7 +24,8 @@ export async function searchRegistry(query, options) {
     // Merge results grouped by provider
     const allHits = [];
     const allAssetHits = [];
-    for (const result of results) {
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
         if (result.status === "rejected") {
             warnings.push(toErrorMessage(result.reason));
             continue;
@@ -33,9 +33,29 @@ export async function searchRegistry(query, options) {
         const value = result.value;
         if (!value)
             continue;
-        allHits.push(...value.hits);
-        if (value.assetHits)
-            allAssetHits.push(...value.assetHits);
+        const registryLabel = entries[i].name ? `"${entries[i].name}"` : entries[i].url;
+        let dropped = 0;
+        for (const hit of value.hits) {
+            if (isCompleteHit(hit)) {
+                allHits.push(hit);
+            }
+            else {
+                dropped++;
+            }
+        }
+        if (value.assetHits) {
+            for (const hit of value.assetHits) {
+                if (isCompleteAssetHit(hit)) {
+                    allAssetHits.push(hit);
+                }
+                else {
+                    dropped++;
+                }
+            }
+        }
+        if (dropped > 0) {
+            warnings.push(`Registry ${registryLabel} returned ${dropped} incomplete hit(s); dropped from response.`);
+        }
         if (value.warnings)
             warnings.push(...value.warnings);
     }
@@ -97,3 +117,42 @@ function clampLimit(limit) {
         return 20;
     return Math.min(100, Math.max(1, Math.trunc(limit)));
 }
+// A complete hit must have the fields downstream consumers (CLI rendering,
+// `akm add`) rely on. Providers that return partial records would otherwise
+// surface as `{}` in the JSON output.
+function isCompleteHit(hit) {
+    if (!hit || typeof hit !== "object")
+        return false;
+    return (typeof hit.source === "string" &&
+        typeof hit.id === "string" &&
+        hit.id.length > 0 &&
+        typeof hit.title === "string" &&
+        hit.title.length > 0 &&
+        typeof hit.ref === "string" &&
+        hit.ref.length > 0 &&
+        typeof hit.installRef === "string" &&
+        hit.installRef.length > 0);
+}
+function isCompleteAssetHit(hit) {
+    if (!hit || typeof hit !== "object")
+        return false;
+    if (hit.type !== "registry-asset" ||
+        typeof hit.assetType !== "string" ||
+        hit.assetType.length === 0 ||
+        typeof hit.assetName !== "string" ||
+        hit.assetName.length === 0 ||
+        typeof hit.action !== "string") {
+        return false;
+    }
+    // `stash` is required by the consumer (output shaping + asset-action display);
+    // rejecting incomplete stashes here keeps malformed objects out of the JSON
+    // output. Flagged in PR #168 review (#9).
+    const stash = hit.stash;
+    if (!stash || typeof stash !== "object")
+        return false;
+    if (typeof stash.id !== "string" || stash.id.length === 0)
+        return false;
+    if (typeof stash.name !== "string" || stash.name.length === 0)
+        return false;
+    return true;
+}