akm-cli 0.7.5 → 0.8.0-rc1

package/dist/commands/info.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import { getAssetTypes } from "../core/asset-spec";
-import { loadConfig } from "../core/config";
+import { getSources, loadConfig } from "../core/config";
 import { getDbPath } from "../core/paths";
 import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openExistingDatabase } from "../indexer/db";
 import { getEffectiveSemanticStatus, readSemanticStatus } from "../indexer/semantic-status";
@@ -32,7 +32,7 @@ export function assembleInfo(options) {
     // Stash providers — prefer `sources[]`; fall back to `stashDir` when the
     // user has not yet migrated to the sources[] config shape so that info
     // always reflects at least one provider when a stash is configured.
-    const configuredSources = config.sources ?? config.stashes ?? [];
+    const configuredSources = getSources(config);
     const stashesList = configuredSources.length === 0 && config.stashDir
         ? [{ type: "filesystem", path: config.stashDir, name: "primary" }]
         : configuredSources;

package/dist/commands/init.js

@@ -8,8 +8,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "../core/asset-spec";
-import { getConfigPath, loadUserConfig, saveConfig } from "../core/config";
-import { getBinDir, getDefaultStashDir } from "../core/paths";
+import { loadUserConfig, saveConfig } from "../core/config";
+import { getBinDir, getConfigPath, getDefaultStashDir } from "../core/paths";
 import { ensureRg } from "../setup/ripgrep-install";
 export async function akmInit(options) {
     const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();

package/dist/commands/install-audit.js

@@ -149,6 +149,9 @@ export function auditInstallCandidate(input) {
     };
 }
 export function formatInstallAuditFailure(ref, report) {
+    return formatInstallAuditFailureForAction(ref, report, "add");
+}
+export function formatInstallAuditFailureForAction(ref, report, action) {
     const lines = [`Security audit failed for ${ref}.`, formatInstallAuditSummary(report)];
     for (const finding of report.findings.slice(0, 5)) {
         lines.push(`- [${finding.severity}] ${finding.message}${finding.file ? ` (${finding.file})` : ""}`);
@@ -156,8 +159,9 @@ export function formatInstallAuditFailure(ref, report) {
     if (report.findings.length > 5) {
         lines.push(`- ${report.findings.length - 5} more finding(s) omitted`);
     }
+    const trustCommand = action === "update" ? `akm update ${ref} --trust` : `akm add ${ref} --trust`;
     lines.push("Disable blocking with `security.installAudit.blockOnCritical = false`, or disable audits with `security.installAudit.enabled = false`." +
-        " Or pass --trust on a one-off 'akm add' to bypass this audit for this install only.");
+        ` Or pass --trust on a one-off '${trustCommand}' to bypass this audit for this ${action} only.`);
     return lines.join("\n");
 }
 export function formatInstallAuditSummary(report) {

package/dist/commands/installed-stashes.js

@@ -7,7 +7,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { isWithin, resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
+import { getSources, loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { akmIndex } from "../indexer/indexer";
 import { removeLockEntry, upsertLockEntry } from "../integrations/lockfile";
@@ -16,7 +16,7 @@ import { parseGitRepoUrl, syncMirroredRepo } from "../sources/providers/git";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
 import { ensureWebsiteMirror } from "../sources/website-ingest";
 import { listWikis, resolveWikisRoot } from "../wiki/wiki";
-import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
+import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailureForAction, } from "./install-audit";
 import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add";
 import { removeStash } from "./source-manage";
 export async function akmListSources(input) {
@@ -26,7 +26,7 @@ export async function akmListSources(input) {
     const sources = [];
     // 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 ?? []) {
+    for (const stash of getSources(config)) {
         const kind = stash.type ?? "filesystem";
         if (kindFilter && !kindFilter.includes(kind))
             continue;
@@ -119,7 +119,7 @@ export async function akmRemove(input) {
                 stashRoot: entry.stashRoot,
             },
             config: {
-                sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+                sourceCount: getSources(updatedConfig).length,
                 installedKitCount: updatedConfig.installed?.length ?? 0,
             },
             index: {
@@ -150,7 +150,7 @@ export async function akmRemove(input) {
             stashRoot: removedEntry.path ?? "",
         },
         config: {
-            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+            sourceCount: getSources(updatedConfig).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -161,6 +161,109 @@ export async function akmRemove(input) {
         },
     };
 }
+// ── akmUpdate helpers ────────────────────────────────────────────────────────
+/** Build a standard UpdateResponse summary block from the current config and index run. */
+async function buildUpdateResponse(stashDir, target, all, processed, full = false) {
+    const index = await akmIndex({ stashDir, ...(full ? { full: true } : {}) });
+    const finalConfig = loadConfig();
+    return {
+        schemaVersion: 1,
+        stashDir,
+        target,
+        all,
+        processed,
+        config: {
+            sourceCount: getSources(finalConfig).length,
+            installedKitCount: finalConfig.installed?.length ?? 0,
+        },
+        index: {
+            mode: index.mode,
+            totalEntries: index.totalEntries,
+            directoriesScanned: index.directoriesScanned,
+            directoriesSkipped: index.directoriesSkipped,
+        },
+    };
+}
+/** Sync a git-mirrored source and return an UpdateResponse. */
+async function updateGitSource(stashDir, target, all, gitSource) {
+    await syncMirroredRepo(gitSource, { force: true, writable: gitSource.writable === true });
+    return buildUpdateResponse(stashDir, target, all, [], true);
+}
+/** Re-crawl a website source and return an UpdateResponse. */
+async function updateWebsiteSource(stashDir, target, all, websiteSource) {
+    // TODO: full incremental re-crawl with delta tracking (#19)
+    await ensureWebsiteMirror(websiteSource, { requireStashDir: true, force: true });
+    return buildUpdateResponse(stashDir, target, all, []);
+}
+/** Sync a single installed registry entry and return the processed record. */
+async function updateRegistryEntry(entry, force, auditConfig) {
+    if (force && shouldCleanupCache(entry)) {
+        cleanupDirectoryBestEffort(entry.cacheDir);
+    }
+    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 UsageError(formatInstallAuditFailureForAction(synced.ref, audit, "update"), "INVALID_FLAG_VALUE", `Re-run with \`akm update ${synced.ref} --trust\` only if you intentionally trust this source.`);
+    }
+    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: 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 !== synced.cacheDir && shouldCleanupCache(entry)) {
+        cleanupDirectoryBestEffort(entry.cacheDir);
+    }
+    const versionChanged = (entry.resolvedVersion ?? "") !== (synced.resolvedVersion ?? "");
+    const revisionChanged = (entry.resolvedRevision ?? "") !== (synced.resolvedRevision ?? "");
+    return {
+        id: entry.id,
+        source: entry.source,
+        ref: entry.ref,
+        previous: {
+            resolvedVersion: entry.resolvedVersion,
+            resolvedRevision: entry.resolvedRevision,
+            cacheDir: entry.cacheDir,
+        },
+        installed: { ...installedEntry, extractedDir: synced.extractedDir, audit },
+        changed: {
+            version: versionChanged,
+            revision: revisionChanged,
+            any: versionChanged || revisionChanged,
+        },
+    };
+}
+// ── akmUpdate dispatcher ─────────────────────────────────────────────────────
 export async function akmUpdate(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
     const target = input?.target?.trim();
@@ -168,10 +271,10 @@ export async function akmUpdate(input) {
     const force = input?.force === true;
     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[].
+    // Check if the target refers to a git or website source — those are stored
+    // in sources[] not installed[] and need a different update path.
     if (target && !all) {
-        const stashes = config.sources ?? config.stashes ?? [];
+        const stashes = getSources(config);
         const isUrl = target.startsWith("http://") || target.startsWith("https://");
         const resolvedPath = !isUrl ? path.resolve(target) : undefined;
         const gitMatch = stashes.find((s) => {
@@ -195,28 +298,8 @@ export async function akmUpdate(input) {
             }
             return false;
         });
-        if (gitMatch) {
-            await syncMirroredRepo(gitMatch, { force: true, writable: gitMatch.writable === true });
-            const index = await akmIndex({ stashDir, full: true });
-            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,
-                },
-            };
-        }
+        if (gitMatch)
+            return updateGitSource(stashDir, target, all, gitMatch);
         const websiteMatch = stashes.find((s) => {
             if (s.type !== "website")
                 return false;
@@ -228,119 +311,16 @@ export async function akmUpdate(input) {
                 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,
-                },
-            };
-        }
+        if (websiteMatch)
+            return updateWebsiteSource(stashDir, target, all, websiteMatch);
     }
     const selectedEntries = selectTargets(installedEntries, target, all);
     const auditConfig = config;
     const processed = [];
     for (const entry of selectedEntries) {
-        if (force && shouldCleanupCache(entry)) {
-            cleanupDirectoryBestEffort(entry.cacheDir);
-        }
-        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: 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 !== synced.cacheDir && shouldCleanupCache(entry)) {
-            cleanupDirectoryBestEffort(entry.cacheDir);
-        }
-        const versionChanged = (entry.resolvedVersion ?? "") !== (synced.resolvedVersion ?? "");
-        const revisionChanged = (entry.resolvedRevision ?? "") !== (synced.resolvedRevision ?? "");
-        processed.push({
-            id: entry.id,
-            source: entry.source,
-            ref: entry.ref,
-            previous: {
-                resolvedVersion: entry.resolvedVersion,
-                resolvedRevision: entry.resolvedRevision,
-                cacheDir: entry.cacheDir,
-            },
-            installed: { ...installedEntry, extractedDir: synced.extractedDir, audit },
-            changed: {
-                version: versionChanged,
-                revision: revisionChanged,
-                any: versionChanged || revisionChanged,
-            },
-        });
+        processed.push(await updateRegistryEntry(entry, force, auditConfig));
     }
-    const index = await akmIndex({ stashDir });
-    const finalConfig = loadConfig();
-    return {
-        schemaVersion: 1,
-        stashDir,
-        target,
-        all,
-        processed,
-        config: {
-            sourceCount: (finalConfig.sources ?? finalConfig.stashes ?? []).length,
-            installedKitCount: finalConfig.installed?.length ?? 0,
-        },
-        index: {
-            mode: index.mode,
-            totalEntries: index.totalEntries,
-            directoriesScanned: index.directoriesScanned,
-            directoriesSkipped: index.directoriesSkipped,
-        },
-    };
+    return buildUpdateResponse(stashDir, target, all, processed);
 }
 function selectTargets(installed, target, all) {
     if (all && target) {
@@ -356,7 +336,7 @@ function selectTargets(installed, target, all) {
         return [found];
     // Check if target matches a stash source and give a helpful message
     const config = loadConfig();
-    const stashes = config.sources ?? config.stashes ?? [];
+    const stashes = getSources(config);
     const isUrl = target.startsWith("http://") || target.startsWith("https://");
     const resolvedPath = !isUrl ? path.resolve(target) : undefined;
     const stashMatch = stashes.find((s) => {

package/dist/commands/knowledge.js

@@ -0,0 +1,133 @@
+/**
+ * Knowledge-command helpers extracted from `src/cli.ts`.
+ *
+ * Covers the shared pipeline for reading, naming, and writing markdown assets
+ * (knowledge and memory) from the CLI. Extracted to keep the CLI entry point
+ * focused on command definitions and routing.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { resolveAssetPathFromName } from "../core/asset-spec";
+import { isHttpUrl, isWithin, tryReadStdinText } from "../core/common";
+import { loadConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { resolveWriteTarget, writeAssetToSource } from "../core/write-source";
+import { fetchWebsiteMarkdownSnapshot } from "../sources/website-ingest";
+const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
+// ── Asset-name normalisation ─────────────────────────────────────────────────
+/**
+ * Validate and normalise a markdown asset name supplied by the user.
+ *
+ * Strips the `.md` extension, rejects empty names, and guards against path
+ * traversal (`..` segments). The `fallback` is used when `name` is undefined.
+ */
+export function normalizeMarkdownAssetName(name, fallback) {
+    const trimmed = (name ?? fallback)
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/\.md$/i, "");
+    if (!trimmed)
+        throw new UsageError("Asset name cannot be empty.");
+    const segments = trimmed.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new UsageError("Asset name must be a relative path without '.' or '..' segments.");
+    }
+    return trimmed;
+}
+function slugifyAssetName(value, fallbackPrefix) {
+    const slug = value
+        .toLowerCase()
+        .replace(/^[#>\-\s]+/, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_CAPTURED_ASSET_SLUG_LENGTH);
+    return slug || `${fallbackPrefix}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+}
+/**
+ * Derive a slug-style asset name from `content` and an optional `preferred`
+ * hint (e.g. a URL-derived page title or the source filename stem).
+ */
+export function inferAssetName(content, fallbackPrefix, preferred) {
+    const firstNonEmptyLine = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    const basis = preferred?.trim() || firstNonEmptyLine || fallbackPrefix;
+    return slugifyAssetName(basis, fallbackPrefix);
+}
+// ── Content reading ──────────────────────────────────────────────────────────
+/**
+ * Read knowledge content from a local file path or stdin (`"-"`).
+ *
+ * Returns the raw text and an optional `preferredName` derived from the
+ * source filename stem (used as a slug fallback when no `--name` flag was
+ * supplied).
+ */
+export function readKnowledgeContent(source) {
+    if (source === "-") {
+        const content = tryReadStdinText();
+        if (!content?.trim()) {
+            throw new UsageError("No stdin content received. Pipe a document into stdin or pass a file path.");
+        }
+        return { content };
+    }
+    const resolvedSource = path.resolve(source);
+    let stat;
+    try {
+        stat = fs.statSync(resolvedSource);
+    }
+    catch {
+        throw new UsageError(`Knowledge source not found: "${source}". Pass a readable file path or "-" for stdin.`);
+    }
+    if (!stat.isFile()) {
+        throw new UsageError(`Knowledge source must be a file: "${source}".`);
+    }
+    return {
+        content: fs.readFileSync(resolvedSource, "utf8"),
+        preferredName: path.basename(resolvedSource, path.extname(resolvedSource)),
+    };
+}
+/**
+ * Read knowledge content from a local path, stdin (`"-"`), or a remote URL.
+ *
+ * URLs are fetched via `fetchWebsiteMarkdownSnapshot`; local sources delegate
+ * to `readKnowledgeContent`.
+ */
+export async function readKnowledgeInput(source) {
+    if (!isHttpUrl(source))
+        return readKnowledgeContent(source);
+    const snapshot = await fetchWebsiteMarkdownSnapshot(source);
+    return { content: snapshot.content, preferredName: snapshot.preferredName };
+}
+// ── Asset writing ────────────────────────────────────────────────────────────
+/**
+ * Write a markdown asset (knowledge or memory) to the resolved write target.
+ *
+ * Resolves the write target via the v1 precedence chain (`--target` →
+ * `defaultWriteTarget` → working stash), validates the path is within the
+ * type root, enforces `--force` semantics, and delegates the actual write
+ * to `writeAssetToSource`.
+ */
+export async function writeMarkdownAsset(options) {
+    const cfg = loadConfig();
+    const { source, config } = resolveWriteTarget(cfg, options.target);
+    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
+    const normalizedName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
+    // Pre-flight: existence + force semantics. The helper itself overwrites
+    // unconditionally; the CLI surfaces a friendlier UsageError before any
+    // disk activity when --force is absent.
+    const assetPath = resolveAssetPathFromName(options.type, typeRoot, normalizedName);
+    if (!isWithin(assetPath, typeRoot)) {
+        throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
+    }
+    if (fs.existsSync(assetPath) && !options.force) {
+        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    const result = await writeAssetToSource(source, config, { type: options.type, name: normalizedName }, options.content);
+    return {
+        ref: result.ref,
+        path: result.path,
+        stashDir: source.path,
+    };
+}

package/dist/commands/lint/agent-linter.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { BaseLinter } from "./base-linter";
+/**
+ * Linter for `agents/` assets.
+ *
+ * Extra check beyond base:
+ *   - `missing-name-or-type`: frontmatter exists but `name` or `type` field is
+ *     absent. Not auto-fixable; detail includes a suggested slug.
+ */
+export class AgentLinter extends BaseLinter {
+    types = ["agents"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        const missingFieldDetail = this.#checkMissingNameOrType(ctx.data, ctx.frontmatter);
+        if (missingFieldDetail) {
+            const slug = this.#suggestSlug(ctx.filePath);
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-name-or-type",
+                detail: `${missingFieldDetail}; suggested slug: ${slug}`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+    #checkMissingNameOrType(data, frontmatterText) {
+        if (!frontmatterText)
+            return null;
+        const missingFields = [];
+        if (!("name" in data) || !data.name)
+            missingFields.push("name");
+        if (!("type" in data) || !data.type)
+            missingFields.push("type");
+        if (missingFields.length === 0)
+            return null;
+        return `missing fields: ${missingFields.join(", ")}`;
+    }
+    #suggestSlug(filePath) {
+        return path
+            .basename(filePath, ".md")
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "");
+    }
+}