akm-cli 0.9.0-beta.54 → 0.9.0-beta.56

package/dist/commands/read/remember-cli.js

@@ -1,8 +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 { defineCommand } from "citty";
-import { output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "../remember.js";
@@ -26,7 +26,7 @@ async function fetchSimilarMemories(query, excludeRef) {
     }
 }
 // ── Command definition ────────────────────────────────────────────────────────
-export const rememberCommand = defineCommand({
+export const rememberCommand = defineJsonCommand({
     meta: {
         name: "remember",
         description: "Record a memory in the default stash",
@@ -102,141 +102,42 @@ export const rememberCommand = defineCommand({
         },
     },
     async run({ args }) {
-        return runWithJsonErrors(async () => {
-            const body = readMemoryContent(resolveRememberContentArg(args.content));
-            // `--name` is a flat name; subdirectory placement is `--path`'s job.
-            assertFlatAssetName(args.name);
-            // 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,
-                    path: args.path,
-                });
-                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 body = readMemoryContent(resolveRememberContentArg(args.content));
+        // `--name` is a flat name; subdirectory placement is `--path`'s job.
+        assertFlatAssetName(args.name);
+        // 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 = {};
+        for (const k of ["user", "agent", "run", "channel"]) {
+            const v = getStringArg(args, k);
+            if (v)
+                scopeFields[k] = v;
+        }
+        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({
-                description,
-                tags,
-                source,
-                observed_at,
-                expires,
-                subjective,
                 captureMode: "hot",
                 beliefState: "asserted",
-                ...(hasScope ? { scope: scopeFields } : {}),
             });
             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,
                 path: args.path,
@@ -244,22 +145,116 @@ export const rememberCommand = defineCommand({
             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 } : {}),
-                },
+                metadata: { path: result.path, force: args.force === true },
             });
             if (args.showSimilar) {
-                const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+                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,
+            path: args.path,
+        });
+        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/read/search-cli.js

@@ -86,7 +86,7 @@ export const searchCommand = defineJsonCommand({
         const includeProposed = args["include-proposed"] === true;
         const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
         const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
-        const includeSessions = getHyphenatedBoolean(args, "include-sessions");
+        const includeSessions = args["include-sessions"];
         const result = await akmSearch({
             query,
             type,

package/dist/commands/registry-cli.js

@@ -3,27 +3,24 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defineCommand } from "citty";
 import { parsePositiveIntFlag } from "../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../cli/shared.js";
+import { defineJsonCommand, output } from "../cli/shared.js";
 import { DEFAULT_CONFIG, loadUserConfig, saveConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
-import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context.js";
 import { buildRegistryIndex, writeRegistryIndex } from "../registry/build-index.js";
 import { searchRegistry } from "./read/registry-search.js";
 export const registryCommand = defineCommand({
     meta: { name: "registry", description: "Manage stash registries" },
     subCommands: {
-        list: defineCommand({
+        list: defineJsonCommand({
             meta: { name: "list", description: "List configured registries" },
-            run() {
-                return runWithJsonErrors(() => {
-                    const config = loadUserConfig();
-                    const registries = config.registries ?? DEFAULT_CONFIG.registries;
-                    output("registry-list", { registries });
-                });
+            async run() {
+                const config = loadUserConfig();
+                const registries = config.registries ?? DEFAULT_CONFIG.registries;
+                output("registry-list", { registries });
             },
         }),
-        add: defineCommand({
+        add: defineJsonCommand({
             meta: { name: "add", description: "Add a registry by URL" },
             args: {
                 url: { type: "positional", description: "Registry index URL", required: true },
@@ -36,75 +33,71 @@ export const registryCommand = defineCommand({
                     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.");
+            async run({ args }) {
+                if (!args.url.startsWith("http")) {
+                    throw new UsageError("Registry URL must start with http:// or https://");
+                }
+                if (args.url.startsWith("http://")) {
+                    const allowInsecure = 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.");
                     }
-                    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;
+                    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);
                     }
-                    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");
-                        }
+                    catch {
+                        throw new UsageError("--options must be valid JSON");
                     }
-                    registries.push(entry);
-                    saveConfig({ ...config, registries });
-                    output("registry-add", { registries, added: true });
-                });
+                }
+                registries.push(entry);
+                saveConfig({ ...config, registries });
+                output("registry-add", { registries, added: true });
             },
         }),
-        remove: defineCommand({
+        remove: defineJsonCommand({
             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 });
+            async run({ args }) {
+                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({
+        search: defineJsonCommand({
             meta: { name: "search", description: "Search enabled registries for stashes" },
             args: {
                 query: { type: "positional", description: "Search query", required: true },
@@ -112,14 +105,12 @@ export const registryCommand = defineCommand({
                 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);
-                });
+                const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+                const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
+                output("registry-search", result);
             },
         }),
-        "build-index": defineCommand({
+        "build-index": defineJsonCommand({
             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" },
@@ -128,21 +119,19 @@ export const registryCommand = defineCommand({
                 "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,
-                    });
+                const result = await buildRegistryIndex({
+                    manualEntriesPath: args.manual,
+                    npmRegistryBase: args["npm-registry"],
+                    githubApiBase: 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,
                 });
             },
         }),