akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/commands/registry-cli.js

@@ -0,0 +1,150 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { defineCommand } from "citty";
+import { parsePositiveIntFlag } from "../cli/parse-args";
+import { output, runWithJsonErrors } from "../cli/shared";
+import { DEFAULT_CONFIG, loadUserConfig, saveConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { warn } from "../core/warn";
+import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context";
+import { buildRegistryIndex, writeRegistryIndex } from "../registry/build-index";
+import { searchRegistry } from "./registry-search";
+export const registryCommand = defineCommand({
+    meta: { name: "registry", description: "Manage stash registries" },
+    subCommands: {
+        list: defineCommand({
+            meta: { name: "list", description: "List configured registries" },
+            run() {
+                return runWithJsonErrors(() => {
+                    const config = loadUserConfig();
+                    const registries = config.registries ?? DEFAULT_CONFIG.registries;
+                    output("registry-list", { registries });
+                });
+            },
+        }),
+        add: defineCommand({
+            meta: { name: "add", description: "Add a registry by URL" },
+            args: {
+                url: { type: "positional", description: "Registry index URL", required: true },
+                name: { type: "string", description: "Human-friendly name for the registry" },
+                provider: { type: "string", description: "Provider type (e.g. static-index, skills-sh)" },
+                options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
+                "allow-insecure": {
+                    type: "boolean",
+                    description: "Allow a plain HTTP registry URL (otherwise rejected)",
+                    default: false,
+                },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    if (!args.url.startsWith("http")) {
+                        throw new UsageError("Registry URL must start with http:// or https://");
+                    }
+                    if (args.url.startsWith("http://")) {
+                        const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
+                        if (!allowInsecure) {
+                            throw new UsageError("Registry URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious index. " +
+                                "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.");
+                        }
+                        warn("Warning: registry URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious index.");
+                    }
+                    const config = loadUserConfig();
+                    const registries = [...(config.registries ?? [])];
+                    // Deduplicate by URL
+                    if (registries.some((r) => r.url === args.url)) {
+                        output("registry-add", { registries, added: false, message: "Registry URL already configured" });
+                        return;
+                    }
+                    const entry = { url: args.url };
+                    if (args.name)
+                        entry.name = args.name;
+                    if (args.provider)
+                        entry.provider = args.provider;
+                    if (args.options) {
+                        try {
+                            entry.options = JSON.parse(args.options);
+                        }
+                        catch {
+                            throw new UsageError("--options must be valid JSON");
+                        }
+                    }
+                    registries.push(entry);
+                    saveConfig({ ...config, registries });
+                    output("registry-add", { registries, added: true });
+                });
+            },
+        }),
+        remove: defineCommand({
+            meta: { name: "remove", description: "Remove a registry by URL or name" },
+            args: {
+                target: { type: "positional", description: "Registry URL or name to remove", required: true },
+                yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+            },
+            run({ args }) {
+                return runWithJsonErrors(async () => {
+                    const config = loadUserConfig();
+                    const registries = [...(config.registries ?? [])];
+                    const idx = registries.findIndex((r) => r.url === args.target || r.name === args.target);
+                    if (idx === -1) {
+                        output("registry-remove", { registries, removed: false, message: "No matching registry found" });
+                        return;
+                    }
+                    const { confirmDestructive } = await import("../cli/confirm.js");
+                    const confirmed = await confirmDestructive(`Remove registry "${args.target}"? This cannot be undone.`, {
+                        yes: args.yes === true,
+                    });
+                    if (!confirmed) {
+                        process.stderr.write("Aborted.\n");
+                        return;
+                    }
+                    const removed = registries.splice(idx, 1)[0];
+                    saveConfig({ ...config, registries });
+                    output("registry-remove", { registries, removed: true, entry: removed });
+                });
+            },
+        }),
+        search: defineCommand({
+            meta: { name: "search", description: "Search enabled registries for stashes" },
+            args: {
+                query: { type: "positional", description: "Search query", required: true },
+                limit: { type: "string", description: "Maximum number of results" },
+                assets: { type: "boolean", description: "Include asset-level search results", default: false },
+            },
+            async run({ args }) {
+                await runWithJsonErrors(async () => {
+                    const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+                    const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
+                    output("registry-search", result);
+                });
+            },
+        }),
+        "build-index": defineCommand({
+            meta: { name: "build-index", description: "Build a v2 registry index from discovery and manual entries" },
+            args: {
+                out: { type: "string", description: "Output path for the generated index" },
+                manual: { type: "string", description: "Manual entries JSON file" },
+                "npm-registry": { type: "string", description: "Override npm registry base URL" },
+                "github-api": { type: "string", description: "Override GitHub API base URL" },
+            },
+            async run({ args }) {
+                await runWithJsonErrors(async () => {
+                    const result = await buildRegistryIndex({
+                        manualEntriesPath: args.manual,
+                        npmRegistryBase: getHyphenatedArg(args, "npm-registry"),
+                        githubApiBase: getHyphenatedArg(args, "github-api"),
+                    });
+                    const outPath = writeRegistryIndex(result.index, args.out);
+                    output("registry-build-index", {
+                        outPath,
+                        version: result.index.version,
+                        updatedAt: result.index.updatedAt,
+                        totalKits: result.counts.total,
+                        counts: result.counts,
+                        manualEntriesPath: result.paths.manualEntriesPath,
+                    });
+                });
+            },
+        }),
+    },
+});

package/dist/commands/registry-search.js

@@ -1,5 +1,8 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { toErrorMessage } from "../core/common";
-import { DEFAULT_CONFIG, loadConfig } from "../core/config";
+import { DEFAULT_CONFIG } from "../core/config";
 import { warn } from "../core/warn";
 import { resolveProviderFactory } from "../registry/factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
@@ -133,7 +136,7 @@ export function resolveRegistries(configRegistries) {
         }
         return entries;
     }
-    const registries = configRegistries ?? loadConfig().registries ?? DEFAULT_CONFIG.registries ?? [];
+    const registries = configRegistries ?? DEFAULT_CONFIG.registries ?? [];
     return registries.filter((r) => r.enabled !== false);
 }
 // ── Provider resolution ─────────────────────────────────────────────────────

package/dist/commands/remember-cli.js

@@ -0,0 +1,257 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { defineCommand } from "citty";
+import { output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared";
+import { UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
+import { inferAssetName, writeMarkdownAsset } from "./knowledge";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "./remember";
+import { akmSearch } from "./search";
+// ── Helper: similar memory search ────────────────────────────────────────────
+/**
+ * Best-effort top-3 similar memory search for `--show-similar`.
+ * Scoped to memory: type; excludes the just-written ref.
+ */
+async function fetchSimilarMemories(query, excludeRef) {
+    try {
+        const result = await akmSearch({ query, type: "memory", limit: 4 });
+        return (result.hits ?? [])
+            .filter((h) => "ref" in h && h.ref !== excludeRef)
+            .slice(0, 3)
+            .map((h) => ({ ref: h.ref, ...(h.name ? { title: h.name } : {}) }));
+    }
+    catch {
+        return [];
+    }
+}
+// ── Command definition ────────────────────────────────────────────────────────
+export const rememberCommand = defineCommand({
+    meta: {
+        name: "remember",
+        description: "Record a memory in the default stash",
+    },
+    args: {
+        content: {
+            type: "positional",
+            description: "Memory content. Omit to read markdown from stdin.",
+            required: false,
+        },
+        name: {
+            type: "string",
+            description: "Memory name (defaults to a slug from the content)",
+        },
+        force: {
+            type: "boolean",
+            description: "Overwrite an existing memory with the same name",
+            default: false,
+        },
+        description: {
+            type: "string",
+            description: "Short description written to frontmatter (persisted as the memory's description field)",
+        },
+        tag: {
+            type: "string",
+            description: "Tag to add to the memory (repeatable: --tag foo --tag bar)",
+        },
+        expires: {
+            type: "string",
+            description: "Expiry duration shorthand (e.g. 30d, 12h, 6m). Resolved to an ISO date.",
+        },
+        source: {
+            type: "string",
+            description: "Source reference (URL, asset ref, file path, or any free-form string)",
+        },
+        auto: {
+            type: "boolean",
+            description: "Apply heuristic tagging (code, subjective, source, observed_at) from the body",
+            default: false,
+        },
+        enrich: {
+            type: "boolean",
+            description: "Call the configured LLM to propose tags and description (requires LLM config)",
+            default: false,
+        },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+        },
+        user: {
+            type: "string",
+            description: "Scope this memory to a user id (persisted as `scope_user` frontmatter)",
+        },
+        agent: {
+            type: "string",
+            description: "Scope this memory to an agent id (persisted as `scope_agent` frontmatter)",
+        },
+        run: {
+            type: "string",
+            description: "Scope this memory to a run id (persisted as `scope_run` frontmatter)",
+        },
+        channel: {
+            type: "string",
+            description: "Scope this memory to a channel name (persisted as `scope_channel` frontmatter)",
+        },
+        showSimilar: {
+            type: "boolean",
+            description: "Return top-3 similar existing memories in output (opt-in)",
+        },
+    },
+    async run({ args }) {
+        return runWithJsonErrors(async () => {
+            const body = readMemoryContent(resolveRememberContentArg(args.content));
+            // Determine if the user has requested any structured metadata mode.
+            // Collect all --tag occurrences directly from process.argv because citty
+            // only exposes the last value for repeated string flags.
+            const rawTags = parseAllFlagValues("--tag");
+            // Collect scope flags. Scope alone counts as structured metadata so we
+            // emit frontmatter, but it does NOT trigger the "tags required" check —
+            // memory + scope (no tags) is a valid combination for multi-tenant use.
+            const scopeFields = {};
+            if (typeof args.user === "string" && args.user.trim())
+                scopeFields.user = args.user.trim();
+            if (typeof args.agent === "string" && args.agent.trim())
+                scopeFields.agent = args.agent.trim();
+            if (typeof args.run === "string" && args.run.trim())
+                scopeFields.run = args.run.trim();
+            if (typeof args.channel === "string" && args.channel.trim())
+                scopeFields.channel = args.channel.trim();
+            const hasScope = Object.keys(scopeFields).length > 0;
+            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description;
+            const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
+            if (!hasStructuredArgs) {
+                // Phase 1B / Rec 7: even the zero-flag hot-path emits
+                // `captureMode: hot` + `beliefState: asserted` so user-supplied
+                // memories outrank background-derived ones during ranking.
+                const frontmatterBlock = buildMemoryFrontmatter({
+                    captureMode: "hot",
+                    beliefState: "asserted",
+                });
+                const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+                // Derive the asset slug from the body (not the frontmatter block);
+                // otherwise inferAssetName would key off the leading `---` delimiter.
+                const result = await writeMarkdownAsset({
+                    type: "memory",
+                    content: contentWithFrontmatter,
+                    name: args.name,
+                    fallbackPrefix: "memory",
+                    preferredName: inferAssetName(body, "memory"),
+                    force: args.force,
+                    target: args.target,
+                });
+                appendEvent({
+                    eventType: "remember",
+                    ref: result.ref,
+                    metadata: { path: result.path, force: args.force === true },
+                });
+                if (args.showSimilar) {
+                    const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref);
+                    output("remember", { ok: true, ...result, similar });
+                }
+                else {
+                    output("remember", { ok: true, ...result });
+                }
+                return;
+            }
+            // ── Accumulate metadata from all three modes ──────────────────────────
+            // Start with CLI args (Mode 1: always)
+            const tags = [...rawTags];
+            // --description is persisted as-is; LLM enrichment may fill it if absent.
+            let description = args.description || undefined;
+            let source = args.source;
+            let observed_at;
+            let expires;
+            let subjective;
+            // Resolve --expires to an ISO date string
+            if (args.expires) {
+                const durationMs = parseDuration(args.expires);
+                const expiresDate = new Date(Date.now() + durationMs);
+                expires = expiresDate.toISOString().slice(0, 10);
+            }
+            // Mode 2: --auto heuristics
+            if (args.auto) {
+                const auto = runAutoHeuristics(body);
+                for (const t of auto.tags) {
+                    if (!tags.includes(t))
+                        tags.push(t);
+                }
+                if (!source && auto.source)
+                    source = auto.source;
+                if (!observed_at && auto.observed_at)
+                    observed_at = auto.observed_at;
+                if (!subjective && auto.subjective)
+                    subjective = auto.subjective;
+            }
+            // Mode 3: --enrich LLM (fail-soft)
+            if (args.enrich) {
+                const enriched = await runLlmEnrich(body);
+                for (const t of enriched.tags) {
+                    if (!tags.includes(t))
+                        tags.push(t);
+                }
+                if (!description && enriched.description)
+                    description = enriched.description;
+                if (!observed_at && enriched.observed_at)
+                    observed_at = enriched.observed_at;
+            }
+            // ── Required-field check (before any write) ───────────────────────────
+            // Tags remain required when the user explicitly asked for tag-bearing
+            // metadata (--tag / --enrich / --description / --source / --expires).
+            // `--auto` alone is allowed even when its heuristics derive zero tags.
+            // Scope-only writes (`akm remember "..." --user u1`) also skip this
+            // check — scope is independent metadata and a memory with only scope is
+            // valid.
+            const missing = [];
+            if (hasTagRequiringArgs && tags.length === 0)
+                missing.push("tags");
+            if (missing.length > 0) {
+                throw new UsageError(`Memory is missing required frontmatter field(s): ${missing.join(", ")}. ` +
+                    "Provide them via --tag <value>, --auto (heuristics), or --enrich (LLM).");
+            }
+            // ── Build frontmatter and write ───────────────────────────────────────
+            // Phase 1B / Rec 7: the hot-path CLI write always marks the memory as
+            // `captureMode: hot` and `beliefState: asserted`. Ranking applies a
+            // hot-capture boost so user-supplied memories outrank otherwise-equal
+            // background-derived ones.
+            const frontmatterBlock = buildMemoryFrontmatter({
+                description,
+                tags,
+                source,
+                observed_at,
+                expires,
+                subjective,
+                captureMode: "hot",
+                beliefState: "asserted",
+                ...(hasScope ? { scope: scopeFields } : {}),
+            });
+            const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+            const result = await writeMarkdownAsset({
+                type: "memory",
+                content: contentWithFrontmatter,
+                name: args.name,
+                fallbackPrefix: "memory",
+                force: args.force,
+                target: args.target,
+            });
+            appendEvent({
+                eventType: "remember",
+                ref: result.ref,
+                metadata: {
+                    path: result.path,
+                    force: args.force === true,
+                    tagCount: tags.length,
+                    enriched: args.enrich === true,
+                    auto: args.auto === true,
+                    ...(hasScope ? { scope: scopeFields } : {}),
+                },
+            });
+            if (args.showSimilar) {
+                const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+                output("remember", { ok: true, ...result, similar });
+            }
+            else {
+                output("remember", { ok: true, ...result });
+            }
+        });
+    },
+});

package/dist/commands/remember.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Memory-specific helpers for `akm remember`.
  *
@@ -5,12 +8,13 @@
  * heuristic derivation, LLM enrichment) is testable in isolation and the
  * CLI entry point stays focused on argument parsing + output routing.
  */
-import { stringify as yamlStringify } from "yaml";
+import { serializeFrontmatter } from "../core/asset-serialize";
 import { toErrorMessage, tryReadStdinText } from "../core/common";
-import { loadConfig } from "../core/config";
+import { getDefaultLlmConfig, loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { SCOPE_KEYS } from "../indexer/metadata";
+import { parseFlagValue } from "../output/context";
 /**
  * Parse a shorthand duration string to a number of milliseconds.
  * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
@@ -53,6 +57,12 @@ export function buildMemoryFrontmatter(fields) {
         obj.expires = fields.expires;
     if (fields.subjective)
         obj.subjective = true;
+    if (fields.captureMode === "hot" || fields.captureMode === "background") {
+        obj.captureMode = fields.captureMode;
+    }
+    if (typeof fields.beliefState === "string" && fields.beliefState.trim()) {
+        obj.beliefState = fields.beliefState.trim();
+    }
     // Scope keys are emitted as flat top-level keys (`scope_user`, …) so the
     // existing one-level frontmatter parser can read them without nesting.
     // A scope object with no populated values is dropped.
@@ -68,7 +78,7 @@ export function buildMemoryFrontmatter(fields) {
     // produce `---\n{}\n---` (the YAML serializer's empty-object form).
     if (Object.keys(obj).length === 0)
         return "---\n---";
-    const serialized = yamlStringify(obj).trimEnd();
+    const serialized = serializeFrontmatter(obj);
     return `---\n${serialized}\n---`;
 }
 /**
@@ -133,12 +143,12 @@ const LLM_ENRICH_TIMEOUT_MS = 10_000;
  */
 export async function runLlmEnrich(body) {
     const config = loadConfig();
-    if (!config.llm) {
-        warn("Warning: --enrich requires an LLM to be configured. Run `akm config set llm` to configure one.");
+    const llmConfig = getDefaultLlmConfig(config);
+    if (!llmConfig) {
+        warn("Warning: --enrich requires an LLM to be configured. Run `akm setup` to configure one.");
         return { tags: [] };
     }
-    const llmConfig = config.llm;
-    const { chatCompletion, parseJsonResponse } = await import("../llm/client");
+    const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client");
     const prompt = `You are a memory tagger for a developer knowledge base.
 Given the memory text below, return ONLY a JSON object with these fields:
 - "tags": array of 1-5 short lowercase keyword tags
@@ -188,3 +198,56 @@ Return ONLY the JSON object, no prose, no markdown fences.`;
         return { tags: [] };
     }
 }
+// ── Content-arg disambiguation ───────────────────────────────────────────────
+/**
+ * Guard against citty consuming a global flag value as the `content` positional.
+ *
+ * When the user runs `akm remember --format json` without a content argument,
+ * citty may assign `"json"` to the `content` positional because of how it
+ * handles flag order. This helper detects that case and returns `undefined`
+ * so `readMemoryContent` falls through to stdin.
+ */
+export function resolveRememberContentArg(content) {
+    if (content === undefined)
+        return undefined;
+    const parsedFormat = parseFlagValue(process.argv, "--format");
+    if (parsedFormat !== undefined &&
+        content === parsedFormat &&
+        wasRememberFlagValueConsumedAsContent(content, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined &&
+        content === parsedDetail &&
+        wasRememberFlagValueConsumedAsContent(content, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return content;
+}
+function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
+    const argv = process.argv.slice(2);
+    const rememberIndex = argv.indexOf("remember");
+    const tokens = rememberIndex >= 0 ? argv.slice(rememberIndex + 1) : argv;
+    let flagIndex = -1;
+    let flagConsumesNextToken = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === flagName) {
+            flagIndex = i;
+            flagConsumesNextToken = true;
+            break;
+        }
+        if (token === `${flagName}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    if (tokens.slice(0, flagIndex).includes(content))
+        return false;
+    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? 2 : 1);
+    if (tokens.slice(firstTokenAfterFlag).includes(content))
+        return false;
+    return true;
+}