akm-cli 0.6.0-rc1 → 0.6.0

package/dist/{stash-ref.js → core/asset-ref.js}

@@ -30,7 +30,7 @@ export function makeAssetRef(type, name, origin) {
 export function parseAssetRef(ref) {
     const trimmed = ref.trim();
     if (!trimmed)
-        throw new UsageError("Empty ref.");
+        throw new UsageError("Empty ref.", "MISSING_REQUIRED_ARGUMENT");
     let origin;
     let body = trimmed;
     const boundary = trimmed.indexOf("//");
@@ -38,16 +38,16 @@ export function parseAssetRef(ref) {
         origin = trimmed.slice(0, boundary);
         body = trimmed.slice(boundary + 2);
         if (!origin)
-            throw new UsageError("Empty origin in ref.");
+            throw new UsageError("Empty origin in ref.", "MISSING_REQUIRED_ARGUMENT");
     }
     const colon = body.indexOf(":");
     if (colon <= 0) {
-        throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name`);
+        throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name, e.g. skill:deploy or knowledge:guide.md`, "MISSING_REQUIRED_ARGUMENT");
     }
     const rawType = body.slice(0, colon);
     const rawName = body.slice(colon + 1);
     if (!isAssetType(rawType)) {
-        throw new UsageError(`Invalid asset type: "${rawType}".`);
+        throw new UsageError(`Invalid asset type: "${rawType}".`, "MISSING_REQUIRED_ARGUMENT");
     }
     validateName(rawName);
     const name = normalizeName(rawName);

package/dist/{asset-registry.js → core/asset-registry.js}

@@ -10,7 +10,7 @@
  * `db-search.ts` import from, eliminating the import-order dependency
  * entirely.
  */
-import { buildWorkflowAction } from "./renderers";
+import { buildWorkflowAction } from "../output/renderers";
 /** Map asset types to their primary renderer names. */
 export const TYPE_TO_RENDERER = {
     script: "script-source",

package/dist/{asset-spec.js → core/asset-spec.js}

@@ -1,7 +1,7 @@
 import path from "node:path";
+import { buildWorkflowAction } from "../output/renderers";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
 import { toPosix } from "./common";
-import { buildWorkflowAction } from "./renderers";
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {

package/dist/{config.js → core/config.js}

@@ -2,7 +2,9 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { filterNonEmptyStrings } from "./common";
+import { ConfigError } from "./errors";
 import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "./paths";
+import { warn } from "./warn";
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     semanticSearchMode: "auto",
@@ -106,20 +108,7 @@ export function saveConfig(config) {
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
     const sanitized = sanitizeConfigForWrite(config);
-    const tmpPath = `${configPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    try {
-        fs.writeFileSync(tmpPath, `${JSON.stringify(sanitized, null, 2)}\n`, "utf8");
-        fs.renameSync(tmpPath, configPath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+    writeConfigObject(configPath, sanitized);
 }
 /**
  * Strip apiKey fields before writing config to disk.
@@ -186,16 +175,16 @@ function pickKnownKeys(raw) {
         const legacySemanticSearch = raw.semanticSearch;
         config.semanticSearchMode = legacySemanticSearch ? "auto" : "off";
     }
-    // Migrate legacy searchPaths into stashes
+    // Migrate legacy searchPaths into sources
     if (Array.isArray(raw.searchPaths)) {
         const legacyPaths = raw.searchPaths.filter((d) => typeof d === "string");
         if (legacyPaths.length > 0) {
-            const existing = config.stashes ?? [];
+            const existing = config.sources ?? [];
             const migrated = legacyPaths
                 .filter((p) => !existing.some((s) => s.type === "filesystem" && s.path === p))
                 .map((p) => ({ type: "filesystem", path: p }));
             if (migrated.length > 0) {
-                config.stashes = [...existing, ...migrated];
+                config.sources = [...existing, ...migrated];
             }
         }
     }
@@ -220,9 +209,20 @@ function pickKnownKeys(raw) {
         config.stashInheritance = raw.disableGlobalStashes ? "replace" : "merge";
         config.disableGlobalStashes = raw.disableGlobalStashes;
     }
-    const stashes = parseStashesConfig(raw.stashes);
-    if (stashes)
-        config.stashes = stashes;
+    // Load `sources` (new key) first, then fall back to legacy `stashes` key.
+    const sources = parseStashesConfig(raw.sources);
+    if (sources) {
+        config.sources = sources;
+    }
+    else {
+        const legacyStashes = parseStashesConfig(raw.stashes);
+        if (legacyStashes) {
+            // Backwards-compat fallback: configs that still carry `stashes[]` are
+            // normalized to `sources[]` after the raw file loader has had a chance to
+            // auto-migrate the on-disk key.
+            config.sources = legacyStashes;
+        }
+    }
     const security = parseSecurityConfig(raw.security);
     if (security)
         config.security = security;
@@ -232,24 +232,32 @@ function pickKnownKeys(raw) {
     if (typeof raw.writable === "boolean") {
         config.writable = raw.writable;
     }
+    if (typeof raw.defaultWriteTarget === "string" && raw.defaultWriteTarget.trim()) {
+        config.defaultWriteTarget = raw.defaultWriteTarget.trim();
+    }
+    if (typeof raw.search === "object" && raw.search !== null && !Array.isArray(raw.search)) {
+        const searchRaw = raw.search;
+        const searchConfig = {};
+        if (typeof searchRaw.minScore === "number" && Number.isFinite(searchRaw.minScore) && searchRaw.minScore >= 0) {
+            searchConfig.minScore = searchRaw.minScore;
+        }
+        if (Object.keys(searchConfig).length > 0)
+            config.search = searchConfig;
+    }
     return config;
 }
 function readNormalizedConfig(configPath) {
     const raw = readConfigObject(configPath);
-    const expanded = raw ? expandEnvVars(raw) : undefined;
+    const migrated = raw ? maybeAutoMigrateLegacyStashes(configPath, raw) : undefined;
+    const expanded = migrated ? expandEnvVars(migrated) : undefined;
     return expanded ? pickKnownKeys(expanded) : undefined;
 }
-function readNormalizedConfigFromText(_configPath, text) {
-    let raw;
-    try {
-        raw = JSON.parse(stripJsonComments(text));
-    }
-    catch {
-        return undefined;
-    }
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+function readNormalizedConfigFromText(configPath, text) {
+    const raw = parseConfigObjectFromText(text);
+    if (!raw)
         return undefined;
-    const expanded = expandEnvVars(raw);
+    const migrated = maybeAutoMigrateLegacyStashes(configPath, raw);
+    const expanded = expandEnvVars(migrated);
     return pickKnownKeys(expanded);
 }
 function parseOutputConfig(value) {
@@ -312,6 +320,14 @@ function expandEnvVars(value, fieldName) {
 function readConfigObject(configPath) {
     try {
         const text = fs.readFileSync(configPath, "utf8");
+        return parseConfigObjectFromText(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseConfigObjectFromText(text) {
+    try {
         const raw = JSON.parse(stripJsonComments(text));
         if (typeof raw !== "object" || raw === null || Array.isArray(raw))
             return undefined;
@@ -321,6 +337,47 @@ function readConfigObject(configPath) {
         return undefined;
     }
 }
+/**
+ * Best-effort on-disk config migration for the legacy `stashes` key.
+ *
+ * When a config file still uses `stashes` and does not already define
+ * `sources`, rewrite the file in place with `sources` replacing `stashes`,
+ * emit a one-time notice on success, and return the migrated object. If the
+ * rewrite fails, emit a warning and return the original object so the loader
+ * can still continue with an in-memory fallback.
+ */
+function maybeAutoMigrateLegacyStashes(configPath, raw) {
+    if (Object.hasOwn(raw, "sources") || !Object.hasOwn(raw, "stashes")) {
+        return raw;
+    }
+    const migrated = Object.fromEntries(Object.entries(raw).map(([key, value]) => (key === "stashes" ? ["sources", value] : [key, value])));
+    try {
+        writeConfigObject(configPath, migrated);
+        warn('Config migrated: "stashes" → "sources" in config.json');
+        return migrated;
+    }
+    catch {
+        warn('Failed to migrate "stashes" → "sources" in config.json; continuing with the legacy key in memory. ' +
+            "Check file permissions or rename the key manually if this persists.");
+        return raw;
+    }
+}
+function writeConfigObject(configPath, config) {
+    const tmpPath = `${configPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    try {
+        fs.writeFileSync(tmpPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+        fs.renameSync(tmpPath, configPath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
 /**
  * Strip JavaScript-style comments from a JSON string (JSONC support).
  * Handles // line comments and /* block comments while preserving
@@ -435,11 +492,10 @@ function parseLlmConfig(value) {
         console.warn(`[akm] Ignoring llm config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
         return undefined;
     }
-    if (typeof obj.model !== "string" || !obj.model)
-        return undefined;
+    const model = typeof obj.model === "string" ? obj.model : "";
     const result = {
         endpoint: obj.endpoint,
-        model: obj.model,
+        model,
     };
     if (typeof obj.provider === "string" && obj.provider) {
         result.provider = obj.provider;
@@ -531,7 +587,7 @@ function asNonEmptyString(value) {
  * Restricted to the four kinds that the install pipeline produces
  * (`"npm" | "github" | "git" | "local"`). The full {@link KitSource} union is
  * wider, but persisted `installed[]` entries should never carry the runtime
- * provider kinds (`"filesystem" | "website" | "openviking"`).
+ * provider kinds (`"filesystem" | "website"`).
  */
 function asKitSource(value) {
     if (value === "npm" || value === "github" || value === "git" || value === "local")
@@ -552,7 +608,7 @@ function parseStashesConfig(value) {
     if (!Array.isArray(value))
         return undefined;
     const entries = value
-        .map((entry) => parseStashConfigEntry(entry))
+        .map((entry) => parseSourceConfigEntry(entry))
         .filter((entry) => entry !== undefined);
     return entries;
 }
@@ -623,13 +679,17 @@ const STASH_TYPE_ALIASES = {
     "context-hub": "git",
     github: "git",
 };
-function parseStashConfigEntry(value) {
+function parseSourceConfigEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const obj = value;
     const rawType = asNonEmptyString(obj.type);
     if (!rawType)
         return undefined;
+    if (rawType === "openviking") {
+        const name = asNonEmptyString(obj.name) ?? "unnamed";
+        throw new ConfigError(`openviking is not supported in akm v1. API-backed sources will return as a\nseparate QuerySource tier post-v1. Remove the source named "${name}" from your config file\nor downgrade to 0.6.x. See docs/migration/v1.md.`, "INVALID_CONFIG_FILE", `Run \`akm remove ${name}\` then re-run, or edit your config file directly at ${_getConfigPath()} to remove the openviking entry.`);
+    }
     const type = STASH_TYPE_ALIASES[rawType] ?? rawType;
     const entry = { type };
     const entryPath = asNonEmptyString(obj.path);
@@ -647,6 +707,14 @@ function parseStashConfigEntry(value) {
         entry.writable = obj.writable;
     if (typeof obj.primary === "boolean")
         entry.primary = obj.primary;
+    // Locked decision 4 (§6 v1 implementation plan): reject writable: true on
+    // website / npm sources at config load. The next sync() would clobber
+    // writes — allowing this is a footgun, not a feature. Throw early so the
+    // user sees the problem at `akm` startup, not when they try to write.
+    if (entry.writable === true && (type === "website" || type === "npm")) {
+        const label = entry.name ? ` "${entry.name}"` : "";
+        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${type}" on source${label}).`, "INVALID_CONFIG_FILE", "To author into a checked-out package, add the same path as a separate filesystem source.");
+    }
     if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
         entry.options = obj.options;
     }
@@ -655,9 +723,9 @@ function parseStashConfigEntry(value) {
         entry.wikiName = wikiName;
     return entry;
 }
-// ── StashEntry runtime construction ─────────────────────────────────────────
+// ── ConfiguredSource runtime construction ─────────────────────────────────────────
 /**
- * Synthesize a stable identifier when a {@link StashConfigEntry} omits its
+ * Synthesize a stable identifier when a {@link SourceConfigEntry} omits its
  * `name`. Uses a short hash of the discriminating fields so two equivalent
  * entries collapse to the same generated name.
  */
@@ -673,8 +741,8 @@ function deriveStashEntryName(entry) {
     return `${entry.type}-${hash}`;
 }
 /**
- * Convert a persisted {@link StashConfigEntry} into the runtime
- * {@link StashSource} discriminated union. Returns `undefined` when the
+ * Convert a persisted {@link SourceConfigEntry} into the runtime
+ * {@link SourceSpec} discriminated union. Returns `undefined` when the
  * entry is missing the fields its provider type requires (e.g. a
  * `filesystem` entry with no `path`); callers should drop or warn for those.
  *
@@ -682,7 +750,7 @@ function deriveStashEntryName(entry) {
  * legacy aliases (`"context-hub"`, `"github"` for git) still produce a usable
  * runtime value when a path/url is supplied.
  */
-export function parseStashEntrySource(entry) {
+export function parseSourceSpec(entry) {
     switch (entry.type) {
         case "filesystem":
             return entry.path ? { type: "filesystem", path: entry.path } : undefined;
@@ -700,8 +768,6 @@ export function parseStashEntrySource(entry) {
                     ...(typeof entry.options?.maxPages === "number" ? { maxPages: entry.options.maxPages } : {}),
                 }
                 : undefined;
-        case "openviking":
-            return entry.url ? { type: "openviking", url: entry.url } : undefined;
         case "npm":
             // Persisted `npm` stash entries are unusual but supported for symmetry.
             return entry.path ? { type: "npm", package: entry.path } : undefined;
@@ -711,29 +777,31 @@ export function parseStashEntrySource(entry) {
     }
 }
 /**
- * Build the full ordered list of runtime {@link StashEntry} values from a
+ * Build the full ordered list of runtime {@link ConfiguredSource} values from a
  * loaded {@link AkmConfig}. Order is the canonical iteration order:
  *
  *   1. The entry marked `primary: true` (or, as a backwards-compat shim,
  *      a synthetic filesystem entry built from the top-level `stashDir`).
- *   2. Remaining `stashes[]` entries in declared order.
+ *   2. Remaining `sources[]` entries in declared order.
  *   3. Legacy `installed[]` entries, mapped into runtime entries.
  *
  * Entries with `enabled: false` are still emitted — callers decide whether
  * to honour the flag (mirrors how `installed[]` entries have always been
- * unconditional). Entries that fail {@link parseStashEntrySource} are
+ * unconditional). Entries that fail {@link parseSourceSpec} are
  * dropped silently.
  */
-export function resolveStashEntries(config) {
+export function resolveConfiguredSources(config) {
     const entries = [];
-    const stashes = config.stashes ?? [];
+    // `sources` is the canonical key. `stashes` is the legacy key that the loader
+    // migrates in-memory; only one of the two should be set at runtime.
+    const stashes = config.sources ?? config.stashes ?? [];
     // (1) Primary entry: explicit `primary: true` wins; fall back to top-level stashDir.
     let primary = stashes.find((entry) => entry.primary === true);
     if (!primary && config.stashDir) {
         primary = { type: "filesystem", path: config.stashDir, primary: true };
     }
     if (primary) {
-        const runtime = toStashEntry(primary, true);
+        const runtime = toConfiguredSource(primary, true);
         if (runtime)
             entries.push(runtime);
     }
@@ -741,7 +809,7 @@ export function resolveStashEntries(config) {
     for (const entry of stashes) {
         if (entry === primary)
             continue;
-        const runtime = toStashEntry(entry, false);
+        const runtime = toConfiguredSource(entry, false);
         if (runtime)
             entries.push(runtime);
     }
@@ -758,8 +826,8 @@ export function resolveStashEntries(config) {
     }
     return entries;
 }
-function toStashEntry(persisted, isPrimary) {
-    const source = parseStashEntrySource(persisted);
+function toConfiguredSource(persisted, isPrimary) {
+    const source = parseSourceSpec(persisted);
     if (!source)
         return undefined;
     return {
@@ -841,12 +909,21 @@ function mergeLoadedConfig(base, override) {
     // `disableGlobalStashes` boolean so old config files behave identically.
     const replaceStashes = override.stashInheritance === "replace" ||
         (override.stashInheritance === undefined && override.disableGlobalStashes === true);
+    // Merge `sources` (canonical key). Legacy `stashes` key is handled via the
+    // pickKnownKeys migration which promotes it to `sources` at load time.
+    const overrideSources = override.sources ?? override.stashes ?? [];
+    const baseSources = base.sources ?? base.stashes ?? [];
     if (replaceStashes) {
-        merged.stashes = [...(override.stashes ?? [])];
+        merged.sources = [...overrideSources];
+    }
+    else if (overrideSources.length > 0) {
+        merged.sources = [...baseSources, ...overrideSources];
     }
-    else if (override.stashes) {
-        merged.stashes = [...(base.stashes ?? []), ...override.stashes];
+    else if (baseSources.length > 0) {
+        merged.sources = [...baseSources];
     }
+    // Clear deprecated stashes field on the merged result — sources is canonical.
+    delete merged.stashes;
     return merged;
 }
 function applyRuntimeEnvApiKeys(config) {

package/dist/core/errors.js

@@ -0,0 +1,90 @@
+/**
+ * Typed error classes for structured exit code classification.
+ *
+ * - ConfigError  -> exit 78  (configuration / environment problems)
+ * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
+ * - NotFoundError -> exit 1  (requested resource missing)
+ *
+ * Each error carries a machine-readable `code` field. Codes are stable
+ * identifiers safe to consume from scripts and JSON output. Existing throw
+ * sites without an explicit code receive a default code per error class so
+ * older call sites continue to compile and behave unchanged.
+ *
+ * Each error also exposes a `hint()` method returning an actionable hint
+ * string (or `undefined`). Hints can be supplied at construction time or
+ * derived from the error `code` via the per-class default mapping below.
+ * The CLI surfaces this via `error.hint()` rather than message-regex parsing.
+ */
+/**
+ * Default hint for each ConfigError code. Keep these short, actionable, and
+ * imperative. Returning undefined means "no canned hint".
+ */
+const CONFIG_HINTS = {
+    STASH_DIR_NOT_FOUND: "Run `akm init` to create the default stash, or set stashDir in your config.",
+    STASH_DIR_NOT_A_DIRECTORY: "The configured stashDir exists but isn't a directory. Update stashDir to point at a folder.",
+    STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update stashDir.",
+    EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
+    LLM_NOT_CONFIGURED: 'Run `akm config set llm \'{"endpoint":"...","model":"..."}\'` to configure the LLM.',
+};
+/** Default hint for each UsageError code. */
+const USAGE_HINTS = {
+    INVALID_SOURCE_VALUE: "Pick one of: stash, registry, both.",
+    INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, text, yaml.",
+    INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full, summary, agent.",
+    INVALID_JSON_CONFIG_VALUE: 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.',
+    MISSING_OR_AMBIGUOUS_TARGET: "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg` (not both).",
+    TARGET_NOT_UPDATABLE: "Run `akm list` to view your sources, then retry with one of those values.",
+    MISSING_REQUIRED_ARGUMENT: "Refs use the form type:name, e.g. `akm show skill:deploy` or `akm show knowledge:guide.md`.",
+};
+/** Default hint for each NotFoundError code. */
+const NOT_FOUND_HINTS = {
+    SOURCE_NOT_FOUND: "Run `akm list` to view your sources, then retry with one of those values.",
+};
+/** Raised when configuration or environment is invalid or missing. */
+export class ConfigError extends Error {
+    code;
+    _hint;
+    constructor(msg, code = "INVALID_CONFIG_FILE", hint) {
+        super(msg);
+        this.name = "ConfigError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? CONFIG_HINTS[this.code];
+    }
+}
+/** Raised when the user supplies invalid arguments or input. */
+export class UsageError extends Error {
+    code;
+    _hint;
+    constructor(msg, code = "INVALID_FLAG_VALUE", hint) {
+        super(msg);
+        this.name = "UsageError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? USAGE_HINTS[this.code];
+    }
+}
+/** Raised when a requested resource (asset, entry, file) is not found. */
+export class NotFoundError extends Error {
+    code;
+    _hint;
+    constructor(msg, code = "ASSET_NOT_FOUND", hint) {
+        super(msg);
+        this.name = "NotFoundError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? NOT_FOUND_HINTS[this.code];
+    }
+}

package/dist/{frontmatter.js → core/frontmatter.js}

@@ -11,11 +11,13 @@
  *
  * **Limitations**: This is a hand-rolled YAML-subset parser with intentional
  * constraints for simplicity and safety:
- * - **List support**: YAML block sequences (`- item`) and flow arrays
- *   (`[a, b, c]`) are both supported for top-level list-valued keys.
+ * - **Top-level values**: string, boolean, and number scalars are supported,
+ *   as well as top-level list-valued keys using YAML block sequences
+ *   (`- item`) or flow arrays (`[a, b, c]`).
+ * - **List item types**: list items must be scalar values and may be strings,
+ *   booleans, or numbers.
  * - **No nested objects beyond one level**: Only a single level of indented
  *   key-value pairs is supported.
- * - **Scalar values only**: string, boolean, and number scalars are supported.
  */
 export function parseFrontmatter(raw) {
     const parsedBlock = parseFrontmatterBlock(raw);