akm-cli 0.4.0 → 0.4.1

package/dist/cli.js

@@ -2,7 +2,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
-import { resolveStashDir } from "./common";
+import { resolveAssetPathFromName } from "./asset-spec";
+import { isWithin, resolveStashDir } from "./common";
 import { generateBashCompletions, installBashCompletions } from "./completions";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, saveConfig } from "./config";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./config-cli";
@@ -28,8 +29,12 @@ import { setQuiet, warn } from "./warn";
 const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl"];
 const DETAIL_LEVELS = ["brief", "normal", "full", "summary"];
 const NORMAL_DESCRIPTION_LIMIT = 250;
+const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
 const CONTEXT_HUB_ALIAS_REF = "context-hub";
 const CONTEXT_HUB_ALIAS_URL = "https://github.com/andrewyng/context-hub";
+const SKILLS_SH_NAME = "skills.sh";
+const SKILLS_SH_URL = "https://skills.sh";
+const SKILLS_SH_PROVIDER = "skills-sh";
 import { stringify as yamlStringify } from "yaml";
 function parseOutputFormat(value) {
     if (!value)
@@ -1356,6 +1361,164 @@ const feedbackCommand = defineCommand({
         });
     },
 });
+function tryReadStdinText() {
+    if (process.stdin.isTTY)
+        return undefined;
+    const input = fs.readFileSync(0, "utf8");
+    return input.length > 0 ? input : undefined;
+}
+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)}`;
+}
+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);
+}
+function readMemoryContent(contentArg) {
+    const content = contentArg ?? tryReadStdinText();
+    if (!content?.trim()) {
+        throw new UsageError("Memory content is required. Pass quoted text or pipe markdown into stdin.");
+    }
+    return content;
+}
+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)),
+    };
+}
+function writeMarkdownAsset(options) {
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, options.type === "knowledge" ? "knowledge" : "memories");
+    fs.mkdirSync(typeRoot, { recursive: true });
+    const normalizedName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
+    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.`);
+    }
+    fs.mkdirSync(path.dirname(assetPath), { recursive: true });
+    fs.writeFileSync(assetPath, options.content.endsWith("\n") ? options.content : `${options.content}\n`, "utf8");
+    return {
+        ref: `${options.type}:${normalizedName}`,
+        path: assetPath,
+        stashDir,
+    };
+}
+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,
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = writeMarkdownAsset({
+                type: "memory",
+                content: readMemoryContent(args.content),
+                name: args.name,
+                fallbackPrefix: "memory",
+                force: args.force,
+            });
+            output("remember", { ok: true, ...result });
+        });
+    },
+});
+const importKnowledgeCommand = defineCommand({
+    meta: {
+        name: "import",
+        description: "Import a knowledge document into the default stash",
+    },
+    args: {
+        source: {
+            type: "positional",
+            description: 'Source file path, or "-" to read from stdin',
+            required: true,
+        },
+        name: {
+            type: "string",
+            description: "Knowledge name (defaults to the source filename or content slug)",
+        },
+        force: {
+            type: "boolean",
+            description: "Overwrite an existing knowledge document with the same name",
+            default: false,
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const { content, preferredName } = readKnowledgeContent(args.source);
+            const result = writeMarkdownAsset({
+                type: "knowledge",
+                content,
+                name: args.name,
+                fallbackPrefix: "knowledge",
+                preferredName,
+                force: args.force,
+            });
+            output("import", { ok: true, source: args.source, ...result });
+        });
+    },
+});
 const hintsCommand = defineCommand({
     meta: {
         name: "hints",
@@ -1401,6 +1564,83 @@ const completionsCommand = defineCommand({
         }
     },
 });
+function normalizeToggleTarget(target) {
+    const normalized = target.trim().toLowerCase();
+    if (normalized === "skills.sh" || normalized === "skills-sh")
+        return "skills.sh";
+    if (normalized === "context-hub")
+        return "context-hub";
+    throw new UsageError(`Unsupported target "${target}". Supported targets: skills.sh, context-hub`);
+}
+function toggleSkillsShRegistry(enabled) {
+    const config = loadUserConfig();
+    const registries = (config.registries ?? DEFAULT_CONFIG.registries ?? []).map((registry) => ({ ...registry }));
+    const idx = registries.findIndex((registry) => registry.provider === SKILLS_SH_PROVIDER || registry.name === SKILLS_SH_NAME || registry.url === SKILLS_SH_URL);
+    if (idx >= 0) {
+        const existing = registries[idx];
+        const wasEnabled = existing.enabled !== false;
+        existing.enabled = enabled;
+        saveConfig({ ...config, registries });
+        return { changed: wasEnabled !== enabled, component: SKILLS_SH_NAME, enabled };
+    }
+    if (!enabled) {
+        // Materialize the skills.sh registry explicitly if absent.
+        registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: false });
+        saveConfig({ ...config, registries });
+        return { changed: true, component: SKILLS_SH_NAME, enabled: false };
+    }
+    registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: true });
+    saveConfig({ ...config, registries });
+    return { changed: true, component: SKILLS_SH_NAME, enabled: true };
+}
+function toggleContextHubStash(enabled) {
+    const config = loadUserConfig();
+    const stashes = [...(config.stashes ?? [])];
+    const idx = stashes.findIndex((stash) => stash.name === CONTEXT_HUB_ALIAS_REF || stash.url === CONTEXT_HUB_ALIAS_URL);
+    if (idx >= 0) {
+        const existing = stashes[idx];
+        const wasEnabled = existing.enabled !== false;
+        existing.enabled = enabled;
+        saveConfig({ ...config, stashes });
+        return { changed: wasEnabled !== enabled, component: CONTEXT_HUB_ALIAS_REF, enabled };
+    }
+    if (!enabled) {
+        return { changed: false, component: CONTEXT_HUB_ALIAS_REF, enabled: false };
+    }
+    stashes.push({ type: "git", url: CONTEXT_HUB_ALIAS_URL, name: CONTEXT_HUB_ALIAS_REF, enabled: true });
+    saveConfig({ ...config, stashes });
+    return { changed: true, component: CONTEXT_HUB_ALIAS_REF, enabled: true };
+}
+function toggleComponent(targetRaw, enabled) {
+    const target = normalizeToggleTarget(targetRaw);
+    if (target === "skills.sh")
+        return toggleSkillsShRegistry(enabled);
+    return toggleContextHubStash(enabled);
+}
+const enableCommand = defineCommand({
+    meta: { name: "enable", description: "Enable an optional component (skills.sh or context-hub)" },
+    args: {
+        target: { type: "positional", description: "Component to enable (skills.sh|context-hub)", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = toggleComponent(args.target, true);
+            output("enable", result);
+        });
+    },
+});
+const disableCommand = defineCommand({
+    meta: { name: "disable", description: "Disable an optional component (skills.sh or context-hub)" },
+    args: {
+        target: { type: "positional", description: "Component to disable (skills.sh|context-hub)", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = toggleComponent(args.target, false);
+            output("disable", result);
+        });
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -1425,9 +1665,13 @@ const main = defineCommand({
         search: searchCommand,
         curate: curateCommand,
         show: showCommand,
+        remember: rememberCommand,
+        import: importKnowledgeCommand,
         clone: cloneCommand,
         registry: registryCommand,
         config: configCommand,
+        enable: enableCommand,
+        disable: disableCommand,
         feedback: feedbackCommand,
         hints: hintsCommand,
         completions: completionsCommand,
@@ -1592,6 +1836,9 @@ akm curate "<task>"                          # Curate the best matches for a tas
 akm search "<query>" --type skill             # Filter by type
 akm search "<query>" --source both            # Also search registries
 akm show <ref>                                # View asset details
+akm remember "Deployment needs VPN access"    # Record a memory in your stash
+akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
+akm feedback <ref> --positive|--negative      # Record whether an asset helped
 akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
 akm registry search "<query>"                 # Search all registries
@@ -1606,6 +1853,10 @@ akm registry search "<query>"                 # Search all registries
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
 | knowledge | A reference doc (use \`toc\` or \`section "..."\` to navigate) |
+| memory | Recalled context (read the content for background information) |
+
+When an asset meaningfully helps or fails, record that with \`akm feedback\` so
+future search ranking can learn from real usage.
 
 Run \`akm -h\` for the full command reference.
 `;
@@ -1668,6 +1919,20 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | knowledge | \`content\` (with view modes: \`full\`, \`toc\`, \`frontmatter\`, \`section\`, \`lines\`) |
 | memory | \`content\` (recalled context) |
 
+## Capture Knowledge While You Work
+
+\`\`\`sh
+akm remember "Deployment needs VPN access"     # Record a memory in your stash
+akm remember --name release-retro < notes.md   # Save multiline memory from stdin
+akm import ./docs/auth-flow.md                 # Import a file as knowledge
+akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
+akm feedback skill:code-review --positive      # Record that an asset helped
+akm feedback agent:reviewer --negative         # Record that an asset missed the mark
+\`\`\`
+
+Use \`akm feedback\` whenever an asset materially helps or fails so future search
+ranking can learn from actual usage.
+
 ## Add & Manage Sources
 
 \`\`\`sh
@@ -1675,6 +1940,10 @@ akm add <ref>                                 # Add a source
 akm add @scope/kit                            # From npm (managed)
 akm add owner/repo                            # From GitHub (managed)
 akm add ./path/to/local/kit                   # Local directory
+akm enable skills.sh                          # Enable the skills.sh registry
+akm disable skills.sh                         # Disable the skills.sh registry
+akm enable context-hub                        # Add/enable the context-hub source
+akm disable context-hub                       # Disable the context-hub source
 akm list                                      # List all sources
 akm list --kind managed                       # List managed sources only
 akm remove <target>                           # Remove by id, ref, path, or name

package/dist/embedder.js

@@ -102,6 +102,28 @@ function l2Normalize(vec) {
     return vec.map((v) => v / norm);
 }
 // ── OpenAI-compatible remote embedder ───────────────────────────────────────
+function normalizeEmbeddingEndpoint(endpoint) {
+    let parsed;
+    try {
+        parsed = new URL(endpoint);
+    }
+    catch {
+        return endpoint;
+    }
+    const normalizedPath = parsed.pathname.replace(/\/+$/, "");
+    if (normalizedPath.endsWith("/embeddings")) {
+        return parsed.toString();
+    }
+    parsed.pathname = normalizedPath ? `${normalizedPath}/embeddings` : "/embeddings";
+    return parsed.toString();
+}
+function embeddingEndpointPathHint(endpoint) {
+    const normalizedEndpoint = normalizeEmbeddingEndpoint(endpoint);
+    if (normalizedEndpoint !== endpoint) {
+        return ` Check that your endpoint includes the full embeddings path (for example "${normalizedEndpoint}", not just "${endpoint}").`;
+    }
+    return "";
+}
 async function embedRemote(text, config) {
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {
@@ -114,7 +136,7 @@ async function embedRemote(text, config) {
     if (config.dimension) {
         body.dimensions = config.dimension;
     }
-    const response = await fetchWithTimeout(config.endpoint, {
+    const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(config.endpoint), {
         method: "POST",
         headers,
         body: JSON.stringify(body),
@@ -125,7 +147,7 @@ async function embedRemote(text, config) {
     }
     const json = (await response.json());
     if (!json.data?.[0]?.embedding) {
-        throw new Error("Unexpected embedding response format: missing data[0].embedding");
+        throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(config.endpoint)}`);
     }
     return l2Normalize(json.data[0].embedding);
 }
@@ -228,7 +250,7 @@ async function embedRemoteBatch(texts, config) {
         if (config.dimension) {
             body.dimensions = config.dimension;
         }
-        const response = await fetchWithTimeout(config.endpoint, {
+        const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(config.endpoint), {
             method: "POST",
             headers,
             body: JSON.stringify(body),
@@ -239,7 +261,7 @@ async function embedRemoteBatch(texts, config) {
         }
         const json = (await response.json());
         if (!json.data || json.data.length !== batch.length) {
-            throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}`);
+            throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(config.endpoint)}`);
         }
         // Sort by index to guarantee correct order (OpenAI API doesn't guarantee order)
         const sorted = [...json.data].sort((a, b) => a.index - b.index);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [