akm-cli 0.6.0-rc1 → 0.6.0-rc2

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",
@@ -186,16 +188,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 +222,23 @@ 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 migration: `stashes[]` → `sources[]` in-memory.
+            // Emit a one-time deprecation warning and carry the value forward as
+            // `sources`. The renamed key is persisted on the next `akm config` write.
+            warn('Config key "stashes" is deprecated; rename it to "sources" in your config file ' +
+                `(edit it directly at ${_getConfigPath()}). ` +
+                "Your configuration has been loaded successfully — no manual action is required right now.");
+            config.sources = legacyStashes;
+        }
+    }
     const security = parseSecurityConfig(raw.security);
     if (security)
         config.security = security;
@@ -232,6 +248,18 @@ 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) {
@@ -435,11 +463,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 +558,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 +579,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 +650,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 +678,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 +694,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 +712,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 +721,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 +739,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 +748,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 +780,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 +797,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 +880,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);

package/dist/core/write-source.js

@@ -0,0 +1,280 @@
+/**
+ * write-source — the only place in the codebase that branches on `source.kind`.
+ *
+ * v1 architecture spec §2.6 / §2.7 / §10 step 5: writing to a source is *not*
+ * a SourceProvider interface concern. It's a small command-layer helper that
+ * does a plain filesystem write, plus a git-specific commit (and optional
+ * push) when the source is backed by a git working tree.
+ *
+ * If a third kind ever needs special write handling, it gets added here. For
+ * v1 there are exactly two cases. Adding more parallel scoring systems for
+ * different provider kinds is explicitly disallowed by CLAUDE.md.
+ *
+ * This module is the **single dispatch point** for `kind`-branching write
+ * logic. Callers (remember, import, source-add, etc.) MUST go through
+ * `writeAssetToSource` / `deleteAssetFromSource` rather than re-inlining the
+ * filesystem-write + git-commit dance.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { getCachePaths, parseGitRepoUrl } from "../sources/providers/git";
+import { makeAssetRef } from "./asset-ref";
+import { resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
+import { isWithin, resolveStashDir } from "./common";
+import { resolveConfiguredSources } from "./config";
+import { ConfigError, UsageError } from "./errors";
+/**
+ * Source kinds that the loader is allowed to mark `writable: true`. Anything
+ * else is rejected at config load (per locked decision 4) — see
+ * {@link assertWritableAllowedForKind}.
+ */
+const REJECTED_WRITABLE_KINDS = new Set(["website", "npm"]);
+// ── Public helpers ──────────────────────────────────────────────────────────
+/**
+ * Resolve the effective `writable` flag for a source config entry, applying
+ * the v1 default policy from spec §5.4:
+ *
+ *  - `filesystem` → `true` by default
+ *  - everything else → `false` by default
+ *
+ * Users can opt out for `filesystem` via `writable: false`. They cannot opt
+ * **in** for `website` / `npm` — that combination is rejected at config load
+ * (see {@link assertWritableAllowedForKind}).
+ */
+export function resolveWritable(entry) {
+    if (typeof entry.writable === "boolean")
+        return entry.writable;
+    return entry.type === "filesystem";
+}
+/**
+ * Reject `writable: true` on `website` / `npm` sources at config-load time.
+ * Per locked decision 4 (§6 of the v1 implementation plan): `sync()` would
+ * clobber writes on the next refresh, so allowing writes here is a footgun.
+ *
+ * Throws {@link ConfigError} when the combination is rejected.
+ */
+export function assertWritableAllowedForKind(entry) {
+    if (entry.writable !== true)
+        return;
+    if (REJECTED_WRITABLE_KINDS.has(entry.type)) {
+        const label = entry.name ? ` "${entry.name}"` : "";
+        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${entry.type}" on source${label}).`, "INVALID_CONFIG_FILE", "To author into a checked-out package, add the same path as a separate filesystem source.");
+    }
+}
+/**
+ * Write a textual asset (`content`) into `source` at the path implied by
+ * `ref`. Always:
+ *
+ *   1. Refuses if `config.writable` is not truthy (per §5.4).
+ *   2. Performs a plain filesystem write to `path.join(source.path, …)`.
+ *
+ * For sources of `kind === "git"`, additionally:
+ *
+ *   3. `git -C <path> add <file>`
+ *   4. `git -C <path> commit -m "Update <ref>"`
+ *   5. `git -C <path> push` when `config.options.pushOnCommit` is truthy.
+ *
+ * Any other `kind` reaching this helper is a configuration bug — the loader
+ * rejects unsupported writable kinds — so we throw {@link ConfigError}.
+ */
+export async function writeAssetToSource(source, config, ref, content) {
+    ensureWritable(source, config);
+    const filePath = resolveAssetFilePath(source, ref);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const normalized = content.endsWith("\n") ? content : `${content}\n`;
+    fs.writeFileSync(filePath, normalized, "utf8");
+    await runKindSpecificCommit(source, config, filePath, `Update ${formatRefForMessage(ref)}`);
+    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+}
+/**
+ * Delete the asset at `ref` from `source`. Symmetric to
+ * {@link writeAssetToSource}: same writable check, same git-commit-and-push
+ * convenience for `kind === "git"`.
+ */
+export async function deleteAssetFromSource(source, config, ref) {
+    ensureWritable(source, config);
+    const filePath = resolveAssetFilePath(source, ref);
+    if (!fs.existsSync(filePath)) {
+        throw new UsageError(`Asset "${formatRefForMessage(ref)}" not found in source "${source.name}" (expected at ${filePath}).`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    fs.unlinkSync(filePath);
+    await runKindSpecificCommit(source, config, filePath, `Remove ${formatRefForMessage(ref)}`);
+    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+}
+/**
+ * Resolve the destination for a write per locked decision 3:
+ *
+ *   1. Explicit `--target <name>` (when supplied)
+ *   2. `config.defaultWriteTarget`
+ *   3. `config.stashDir` (the working stash created by `akm init`)
+ *   4. `ConfigError("no writable source configured; run `akm init`")`
+ *
+ * The legacy `first-writable-in-source-array-order` fallback is *not* used —
+ * see plan §6 decision 3 for the rationale.
+ */
+export function resolveWriteTarget(akmConfig, explicitTarget) {
+    const configuredSources = resolveConfiguredSources(akmConfig);
+    // 1. Explicit --target wins.
+    if (explicitTarget) {
+        const match = configuredSources.find((s) => s.name === explicitTarget);
+        if (!match) {
+            throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm list\` to see available sources.`, "INVALID_FLAG_VALUE");
+        }
+        // Up-front writable check so an explicit --target fails fast with a
+        // ConfigError (rather than the generic UsageError ensureWritable would
+        // raise after we've already started building paths). Resolve the
+        // effective writable flag (filesystem defaults to true; everything else
+        // defaults to false) so unset values are interpreted correctly.
+        const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
+        if (!effectiveWritable) {
+            throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass --target to a different source.`);
+        }
+        return adaptConfiguredSource(match);
+    }
+    // 2. config.defaultWriteTarget.
+    if (akmConfig.defaultWriteTarget) {
+        const match = configuredSources.find((s) => s.name === akmConfig.defaultWriteTarget);
+        if (match)
+            return adaptConfiguredSource(match);
+        // Fall through if the named target no longer exists — surface a clear error.
+        throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" does not match any configured source.`, "INVALID_CONFIG_FILE", "Update `defaultWriteTarget` in your config (run `akm config get defaultWriteTarget`) or run `akm list` to see configured sources.");
+    }
+    // 3. Working stash (config.stashDir / resolveStashDir()).
+    try {
+        const stashDir = resolveStashDir({ readOnly: true });
+        return {
+            source: { kind: "filesystem", name: "stash", path: stashDir },
+            config: { type: "filesystem", path: stashDir, name: "stash", writable: true },
+        };
+    }
+    catch {
+        // Fall through to the final ConfigError below.
+    }
+    // 4. Nothing usable.
+    throw new ConfigError("no writable source configured; run `akm init`", "STASH_DIR_NOT_FOUND", "Run `akm init` to create a working stash, or set `defaultWriteTarget` in your config.");
+}
+// ── Internals ───────────────────────────────────────────────────────────────
+function ensureWritable(source, config) {
+    // Apply the same default-resolution rule as resolveWritable so callers can
+    // pass through a SourceConfigEntry with an absent `writable` field.
+    const writable = resolveWritable(config);
+    if (!writable) {
+        throw new UsageError(`Source "${source.name}" is not writable. Set \`writable: true\` on the source config entry to enable writes.`, "INVALID_FLAG_VALUE");
+    }
+}
+function resolveAssetFilePath(source, ref) {
+    const typeDir = TYPE_DIRS[ref.type];
+    if (!typeDir) {
+        throw new UsageError(`Unknown asset type "${ref.type}". Cannot resolve a write path.`, "INVALID_FLAG_VALUE");
+    }
+    const typeRoot = path.join(source.path, typeDir);
+    const assetPath = resolveAssetPathFromName(ref.type, typeRoot, ref.name);
+    if (!isWithin(assetPath, typeRoot)) {
+        throw new UsageError(`Resolved asset path escapes its source: "${ref.name}" in source "${source.name}".`, "PATH_ESCAPE_VIOLATION");
+    }
+    return assetPath;
+}
+async function runKindSpecificCommit(source, config, filePath, message) {
+    if (source.kind === "filesystem") {
+        return; // No commit step.
+    }
+    if (source.kind === "git") {
+        runGitCommit(source.path, filePath, message);
+        if (config.options?.pushOnCommit) {
+            runGitPush(source.path);
+        }
+        return;
+    }
+    // Reject any other kind reaching the helper. The config loader is the
+    // first line of defence (assertWritableAllowedForKind), but we throw here
+    // so external callers that bypass the loader still get a clear error.
+    throw new ConfigError(`write-source: unsupported kind "${source.kind}" for source "${source.name}". ` +
+        "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Set `kind: "filesystem"` (or `kind: "git"`) on the source, or add a parallel filesystem entry.');
+}
+function runGitCommit(repoDir, filePath, message) {
+    // Stage the specific file rather than `add -A` so unrelated working-tree
+    // changes don't get folded into the asset commit.
+    const relPath = path.relative(repoDir, filePath) || filePath;
+    const addResult = spawnSync("git", ["-C", repoDir, "add", "--", relPath], { encoding: "utf8" });
+    if (addResult.status !== 0) {
+        throw new Error(`git add failed: ${addResult.stderr?.trim() || "unknown error"}`);
+    }
+    // Provide a fallback identity so fresh CI/test environments without
+    // user.name/user.email configured can always commit.
+    const commitResult = spawnSync("git", ["-C", repoDir, "-c", "user.name=akm", "-c", "user.email=akm@local", "commit", "-m", message], { encoding: "utf8" });
+    if (commitResult.status !== 0) {
+        // `nothing to commit` is a no-op success — the file may have matched the
+        // existing tree exactly. Surface other errors verbatim.
+        const stderr = commitResult.stderr ?? "";
+        if (/nothing to commit|no changes added/i.test(stderr) ||
+            /nothing to commit|no changes added/i.test(commitResult.stdout ?? "")) {
+            return;
+        }
+        throw new Error(`git commit failed: ${stderr.trim() || "unknown error"}`);
+    }
+}
+function runGitPush(repoDir) {
+    const pushResult = spawnSync("git", ["-C", repoDir, "push"], { encoding: "utf8", timeout: 120_000 });
+    if (pushResult.status !== 0) {
+        throw new Error(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`);
+    }
+}
+function formatRefForMessage(ref) {
+    return ref.origin ? `${ref.origin}//${ref.type}:${ref.name}` : `${ref.type}:${ref.name}`;
+}
+/**
+ * Derive a {@link WriteTargetSource} + persisted {@link SourceConfigEntry}
+ * from the runtime {@link ConfiguredSource} representation used elsewhere in
+ * the codebase. The mapping is:
+ *
+ *   ConfiguredSource.type     → WriteTargetSource.kind
+ *   ConfiguredSource.name     → WriteTargetSource.name
+ *   ConfiguredSource.source.* → WriteTargetSource.path  (via parseSourceSpec)
+ *
+ * Legacy aliases (`context-hub`, `github`) have already been normalised to
+ * `git` by the config loader, so this mapping is straightforward.
+ */
+function adaptConfiguredSource(runtime) {
+    const writePath = pathFromConfiguredSource(runtime);
+    if (!writePath) {
+        throw new ConfigError(`Source "${runtime.name}" has no resolvable on-disk path; writes are unsupported for this entry.`, "INVALID_CONFIG_FILE");
+    }
+    // Map the runtime kind to the write helper's `kind` discriminator. Only
+    // filesystem and git produce writable sources at v1.
+    const kind = runtime.type === "filesystem" || runtime.type === "git" ? runtime.type : runtime.type;
+    const config = {
+        type: runtime.type,
+        name: runtime.name,
+        ...(writePath !== undefined ? { path: writePath } : {}),
+        ...(runtime.writable !== undefined ? { writable: runtime.writable } : {}),
+        ...(runtime.options ? { options: runtime.options } : {}),
+    };
+    return {
+        source: { kind, name: runtime.name, path: writePath },
+        config,
+    };
+}
+function pathFromConfiguredSource(runtime) {
+    // ConfiguredSource.source is the parsed SourceSpec (filesystem|git|website|npm).
+    // For writable kinds we only ever care about a local on-disk path: filesystem
+    // sources expose it directly; git sources resolve through the cache mirror
+    // (handled by the existing source provider). For v1 the helper trusts
+    // callers to materialise the cache path beforehand and does not re-clone.
+    const spec = runtime.source;
+    if (spec.type === "filesystem")
+        return spec.path;
+    // For git sources we fall back to the cached repo directory the provider
+    // already materialised. The lookup is intentionally lazy — we only import
+    // it when needed to keep the helper's import graph small.
+    if (spec.type === "git") {
+        try {
+            const repo = parseGitRepoUrl(spec.url);
+            return getCachePaths(repo.canonicalUrl).repoDir;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}