akm-cli 0.9.0-beta.0 → 0.9.0-beta.2

package/CHANGELOG.md

@@ -6,6 +6,69 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.0-beta.2] - 2026-06-09
+
+### Fixed
+
+- **Consolidation starved merge recall; the memory pool grew unbounded.** Commit
+  `633ece41` made the `incrementalSince` narrowing unconditional, so every
+  consolidation run only judged memories changed since the last run plus their
+  immediate vector-neighbors. Stale-but-unmerged duplicate clusters were never
+  re-examined, so the eligible pool grew monotonically and never shrank, and
+  contradiction detection (which rides on the consolidation pass) went dark.
+  Consolidation only runs on the nightly default-profile pass (`quick`/`frequent`
+  disable it), so a full-pool sweep is correct and affordable; the override is
+  removed. `lastConsolidateTs` still gates whether the pass runs. (Forward-port
+  of the 0.8.5 fix.)
+- **`akm tasks sync` ignored schedule changes** — forward-ported from 0.8.4.
+  Sync classified any task already present in the OS scheduler as "unchanged"
+  without comparing its installed entry, so editing a task's `schedule:` in the
+  `.yml` never reached the crontab; the same gap affected `tasks enable`/`disable`
+  (toggled the comment, re-enabling a stale schedule). Sync now compares the
+  backend's installed signature against the signature the current definition
+  renders to and reinstalls on drift (new `updated[]` field); `enable`/`disable`
+  reinstall from the current `.yml`. The cron backend gains `expectedSignature()`
+  and a per-entry signature on `list()`; other backends fall back to an
+  idempotent reinstall.
+
+### Added
+
+- **`akm improve --skip-if-locked`** — forward-ported from 0.8.4. When another
+  improve run already holds the lock, the run logs and exits 0 with a no-op
+  result (`skipped.reason: "lock-held"`) instead of failing with the "already
+  running" config error (exit 78). Intended for high-frequency scheduled runs
+  (e.g. an every-30-min `quick` pass) that overlap a longer run. Default off.
+
+### Removed
+
+- **`akm config edit`** — the interactive menu-based editor was removed. A
+  prompt-driven drill-down was clunkier than just editing the file. Edit the
+  config directly (the path is shown by `akm config path`), use
+  `akm config set/get/unset` for scripted changes, and `akm config validate` to
+  check it.
+
+## [0.9.0-beta.1] - 2026-06-08
+
+### Fixed
+
+- **`improve.lock` leaked on signal death (cron timeout)** — forward-ported from
+  0.8.3. The improve SIGTERM/SIGINT/SIGHUP handler calls `process.exit()`, which
+  skips `finally` blocks, so the `finally` releasing `improve.lock` never ran and
+  every timed-out cron run leaked the lock. It is now released from a
+  `process.on("exit", …)` handler registered at acquire time, via a new
+  ownership-checked `releaseLockIfOwned(path, pid)`.
+- **`quick` profile was not quick** — forward-ported from 0.8.3. It did not
+  disable the default-ON session-`extract` process, so a `quick` run processed
+  the entire session backlog (~40 min). `quick` now sets
+  `processes.extract.enabled: false`.
+- **`akm-eval` smoke suite adapted to the 0.9.0 CLI** (CI/tooling only). The
+  eval harness called `akm search --detail agent`, but 0.9.0 moved the
+  agent/summary projections to `--shape`; it now uses `--shape agent`.
+  Additionally, the improve-run history readers (`listRecentImproveRunIds` /
+  `resolveImproveRunId`) treated a missing `state.db` as an error rather than
+  "no runs", which broke the read-only smoke + replay-determinism gates on a
+  fresh checkout; a missing `state.db` is now handled as an empty history.
+
 ## [0.9.0-beta.0] - 2026-06-08
 
 ### Added
@@ -191,6 +254,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `migrate-storage` change is pinned by a sha256 + file-mode fixture-stash
   differential test.
 
+## [0.8.3] - 2026-06-08
+
+### Fixed
+
+- **`improve.lock` leaked on signal death (cron timeout).** The improve
+  SIGTERM/SIGINT/SIGHUP handler calls `process.exit()`, which skips `finally`
+  blocks — so the `finally` that releases `improve.lock` never ran, and every
+  timed-out cron run leaked the lock sentinel. (It wasn't a permanent deadlock
+  only because the next run reclaims a dead-PID lock, a path that PID reuse can
+  defeat.) The lock is now released from a `process.on("exit", …)` handler
+  registered at acquire time (exit handlers DO run on `process.exit()`), via a
+  new ownership-checked `releaseLockIfOwned(path, pid)` so a backstop release can
+  never delete a different run's lock. This generalizes to the budget watchdog
+  and any future exit path.
+- **`quick` profile was not quick.** It was documented "Reflect-only" but did
+  not disable the session-`extract` process (which is default-ON), so a `quick`
+  run processed the entire unindexed-session backlog (~40 min) — guaranteeing a
+  5-minute cron timeout → SIGTERM → the lock leak above, every run. `quick` now
+  explicitly sets `processes.extract.enabled: false`.
+
 ## [0.8.2] - 2026-06-05
 
 ### Added

package/dist/assets/profiles/quick.json

@@ -1,10 +1,11 @@
 {
-  "description": "Reflect-only pass — no distill, consolidate, memoryInference, or graphExtraction.",
+  "description": "Reflect-only pass — no extract, distill, consolidate, memoryInference, or graphExtraction.",
   "processes": {
     "reflect": {
       "enabled": true,
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
     },
+    "extract": { "enabled": false },
     "distill": { "enabled": false },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },

package/dist/commands/config-cli.js

@@ -320,16 +320,6 @@ export const configCommand = defineJsonCommand({
                 }
             },
         }),
-        edit: defineJsonCommand({
-            meta: {
-                name: "edit",
-                description: "Interactively edit configuration via a schema-driven menu (TTY only).",
-            },
-            async run() {
-                const { runConfigEdit } = await import("./config-edit.js");
-                await runConfigEdit();
-            },
-        }),
         validate: defineJsonCommand({
             meta: {
                 name: "validate",

package/dist/commands/improve/improve-cli.js

@@ -54,6 +54,11 @@ export const improveCommand = defineCommand({
             description: "Emit the full JSON result on stdout (legacy behaviour). (0.8.0+: full result is recorded in the improve_runs table of state.db and stdout is empty; use this flag for the prior behaviour, e.g. `akm improve --json-to-stdout | jq`.)",
             default: false,
         },
+        "skip-if-locked": {
+            type: "boolean",
+            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
+            default: false,
+        },
         profile: {
             type: "string",
             description: "Named improve profile from profiles.improve or built-in profiles (default, quick, thorough, memory-focus, graph-refresh). Controls which sub-processes run and which asset types are processed.",
@@ -92,6 +97,7 @@ export const improveCommand = defineCommand({
             const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
             const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
             const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
+            const skipIfLocked = getHyphenatedBoolean(args, "skip-if-locked");
             const profileArg = getStringArg(args, "profile");
             // Only set the keys the user actually passed (citty leaves the flag
             // undefined unless `--sync`/`--no-sync` / `--push`/`--no-push` appears),
@@ -189,6 +195,7 @@ export const improveCommand = defineCommand({
                     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                     ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
                     ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                    ...(skipIfLocked ? { skipIfLocked } : {}),
                     ...(profileArg !== undefined ? { profile: profileArg } : {}),
                     ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
                     consolidateOptions: {

package/dist/commands/improve/improve.js

@@ -10,7 +10,7 @@ import { daysToMs, isAssetType } from "../../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../../core/file-lock.js";
+import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "../../core/file-lock.js";
 import { classifyImproveAction } from "../../core/improve-types.js";
 import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
 import { openStateDatabase, purgeOldEvents, purgeOldImproveRuns } from "../../core/state-db.js";
@@ -498,7 +498,7 @@ export async function akmImprove(options = {}) {
         fs.mkdirSync(path.dirname(resolvedLockPath), { recursive: true });
         const lockPayload = () => JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
         if (tryAcquireLockSync(resolvedLockPath, lockPayload()))
-            return;
+            return "acquired";
         // Lock file already exists — probe to determine whether it's still held
         // or whether the prior run died without cleaning up.
         const probe = probeLock(resolvedLockPath, { staleAfterMs: MAX_LOCK_AGE_MS });
@@ -533,9 +533,19 @@ export async function akmImprove(options = {}) {
             }
             releaseLock(resolvedLockPath);
             if (tryAcquireLockSync(resolvedLockPath, lockPayload()))
-                return;
+                return "acquired";
+            // Lost the race to another run that grabbed the freed stale lock.
+            if (options.skipIfLocked) {
+                warn("[improve] another run acquired the lock during stale recovery; skipping (--skip-if-locked)");
+                return "skipped";
+            }
             throw new ConfigError(`akm improve is already running. Delete ${resolvedLockPath} to force.`, "INVALID_CONFIG_FILE");
         }
+        // Lock is held by a live run within the staleness window.
+        if (options.skipIfLocked) {
+            warn(`[improve] another improve run holds the lock (PID ${lock?.pid}, started ${lock?.startedAt}); skipping (--skip-if-locked)`);
+            return "skipped";
+        }
         throw new ConfigError(`akm improve is already running (PID ${lock?.pid}, started ${lock?.startedAt}). Delete ${resolvedLockPath} to force.`, "INVALID_CONFIG_FILE");
     };
     // Phase 4 lock-leak guard (§7 ordering hazard): hoisting `improve.lock` above
@@ -560,6 +570,17 @@ export async function akmImprove(options = {}) {
         }
         lockAcquired = false;
     };
+    // Signal-safe lock release. The SIGTERM/SIGINT/SIGHUP handler in improve-cli.ts
+    // calls `process.exit()`, which does NOT run the `finally` below that owns lock
+    // release — so a cron-timeout SIGTERM leaked `improve.lock` every run.
+    // `process.exit()` DOES fire `'exit'` listeners, so we release the lock from
+    // one. `releaseLockIfOwned` only unlinks a lock still owned by this PID, so it
+    // is safe even if a later run re-acquired it. The listener is removed in the
+    // `finally` so the normal path stays single-release and repeated in-process
+    // `akmImprove` calls (tests) do not accumulate listeners.
+    const releaseLockOnExit = () => {
+        releaseLockIfOwned(resolvedLockPath, process.pid);
+    };
     const preEnsureCleanupWarnings = [];
     let plannedRefs;
     let memorySummary;
@@ -572,8 +593,25 @@ export async function akmImprove(options = {}) {
         // The dry-run branch below produces plannedRefs/memorySummary WITHOUT the lock
         // or triage (decision: dry-run never mutates the queue).
         if (!options.dryRun) {
-            acquireLock();
+            if (acquireLock() === "skipped") {
+                // Another improve holds the lock and the caller asked to skip rather
+                // than fail. Return a clean no-op result (exit 0) before any index/DB
+                // work — never registered the exit listener, never set lockAcquired,
+                // so we release nothing belonging to the run that owns the lock.
+                return {
+                    schemaVersion: 1,
+                    ok: true,
+                    scope,
+                    dryRun: false,
+                    skipped: { reason: "lock-held" },
+                    memorySummary: { eligible: 0, derived: 0 },
+                    plannedRefs: [],
+                };
+            }
             lockAcquired = true;
+            // Backstop release on process.exit() (signal handler / budget watchdog),
+            // which skips the finally below. Removed in that finally on the normal path.
+            process.on("exit", releaseLockOnExit);
             // Phase 4 triage pre-pass (§7, §13): drain the standing pending backlog
             // BEFORE ensureIndex so improve generates fresh proposals against a cleared
             // queue (no `duplicate_pending` collisions) and ensureIndex absorbs triage's
@@ -1002,6 +1040,9 @@ export async function akmImprove(options = {}) {
         catch {
             // ignore
         }
+        // The normal path released the lock above; drop the process.exit backstop so
+        // it does not fire later (or accumulate across repeated in-process calls).
+        process.removeListener("exit", releaseLockOnExit);
         // I1: close the long-lived state.db connection opened at the top of the run.
         try {
             eventsDb?.close();
@@ -1324,16 +1365,13 @@ async function runConsolidationPass(args) {
             // Tie consolidate proposals back to this improve invocation so
             // accept-rate-per-run aggregation works. Mirrors reflect/propose/extract.
             sourceRun: `consolidate-${Date.now()}`,
-            // Incremental consolidation: pass the last-consolidation timestamp so
-            // akmConsolidate skips chunks with no memory changed since then. Converts
-            // consolidation cost from O(pool) to O(changed clusters) — the fix for
-            // the rising p95 tail where full-pool re-judging produced 5–10 min runs
-            // that promoted ~0. undefined → full pass on first-ever run (bootstrap).
-            // volumeTriggered correctly forces the run past cooldown but must NOT
-            // override incrementalSince — the stash has ~1400 eligible memories so
-            // volumeTriggered=true on every run, permanently forcing full 12-chunk
-            // scans (~264s) instead of the intended 1-2 chunk incremental path (~44s).
-            incrementalSince: lastConsolidateTs,
+            // Full-pool sweep: consolidation only runs on the nightly default-profile
+            // pass (quick/frequent disable it), so a complete re-cluster is correct and
+            // affordable here. Do NOT pass incrementalSince — the time-window narrowing
+            // it triggers permanently excludes stale-but-unmerged duplicate clusters,
+            // starving merge recall and letting the pool grow unbounded. (The narrowing
+            // was a band-aid for an every-30-min consolidation cadence that the profile
+            // split has since eliminated.) lastConsolidateTs still gates whether we run.
             maxChunkSize: improveProfile?.processes?.consolidate?.maxChunkSize,
             // Honor profile.autoAccept (already merged into options.autoAccept at the
             // top of akmImprove). The CLI parser always supplies 90 when --auto-accept

package/dist/commands/tasks/tasks.js

@@ -218,7 +218,13 @@ export async function akmTasksSetEnabled(id, enabled) {
     fs.writeFileSync(filePath, updated, "utf8");
     const sched = selectBackend();
     try {
-        await sched.setEnabled(normalised, enabled);
+        // Reinstall from the (just-updated) definition rather than only toggling
+        // the comment. A plain toggle leaves a stale schedule in place if the
+        // .yml's `schedule:` changed while the task was disabled — re-enabling
+        // would silently keep the old cron line. install() renders the block with
+        // both the current schedule and the new enabled state, and is idempotent.
+        const task = parseTaskDocument({ yaml: updated, filePath, id: normalised });
+        await sched.install(task);
     }
     catch (err) {
         // Roll the file back so the YAML source-of-truth and the OS
@@ -254,9 +260,12 @@ export async function akmTasksHistory(input) {
  * Reconcile the on-disk task files with the OS scheduler.
  *   • install missing tasks (after validating them — invalid files are
  *     skipped with a per-task reason rather than aborting the whole sync)
+ *   • reinstall tasks whose schedule or enabled state changed in the .yml
+ *     (drift detected by comparing the backend's installed signature against
+ *     the signature the current definition would produce)
  *   • remove orphan scheduler entries that no longer have a backing file
  */
-export async function akmTasksSync() {
+export async function akmTasksSync(deps = {}) {
     const stashDir = resolveStashDir();
     const typeRoot = path.join(stashDir, "tasks");
     if (fs.existsSync(typeRoot))
@@ -267,10 +276,13 @@ export async function akmTasksSync() {
             .filter((f) => f.endsWith(".yml"))
             .map((f) => f.slice(0, -4))
         : [];
-    const sched = selectBackend();
+    const sched = deps.backend ?? selectBackend();
     const backend = backendNameForPlatform();
-    const present = new Set((await sched.list()).map((t) => t.id));
+    // Map id → installed signature so sync can detect schedule/enabled drift on
+    // tasks that already exist in the scheduler, not just presence/absence.
+    const present = new Map((await sched.list()).map((t) => [t.id, t.signature]));
     const installed = [];
+    const updated = [];
     const unchanged = [];
     const skipped = [];
     for (const id of fileIds) {
@@ -290,22 +302,34 @@ export async function akmTasksSync() {
             skipped.push({ id, reason: err instanceof Error ? err.message : String(err) });
             continue;
         }
-        if (present.has(id)) {
+        if (!present.has(id)) {
+            await sched.install(task);
+            installed.push(id);
+            continue;
+        }
+        // Already installed — reconcile against the current definition. Compare the
+        // installed signature to what this task would render to; reinstall on drift.
+        // When the backend can't produce a signature (no expectedSignature, or it
+        // didn't record one), reinstall unconditionally — install() is idempotent,
+        // so the cost is one crontab write and correctness is guaranteed.
+        const installedSig = present.get(id);
+        const expectedSig = sched.expectedSignature?.(task);
+        if (installedSig !== undefined && expectedSig !== undefined && installedSig === expectedSig) {
             unchanged.push(id);
         }
         else {
             await sched.install(task);
-            installed.push(id);
+            updated.push(id);
         }
     }
     const removed = [];
-    for (const installedId of present) {
+    for (const installedId of present.keys()) {
         if (!fileIds.includes(installedId)) {
             await sched.uninstall(installedId);
             removed.push(installedId);
         }
     }
-    return { installed, removed, unchanged, skipped, backend: sched.name };
+    return { installed, updated, removed, unchanged, skipped, backend: sched.name };
 }
 export async function akmTasksDoctor() {
     const warnings = [];

package/dist/core/file-lock.js

@@ -79,6 +79,28 @@ export function releaseLock(lockPath) {
         // Sentinel already gone — fine.
     }
 }
+/**
+ * Release a lock ONLY if it is still owned by `ownerPid`. Safe to call from a
+ * `process.exit()` / `'exit'` handler as a backstop: `process.exit()` skips
+ * `finally` blocks — so the normal lock-release never runs on signal death
+ * (SIGTERM/SIGINT) — but it DOES fire `'exit'` listeners synchronously. Checking
+ * ownership first means that if the lock was already released and re-acquired by
+ * a different process, this leaves that process's lock intact (no cross-run
+ * deletion / PID-reuse footgun). Synchronous so it is valid inside an exit handler.
+ */
+export function releaseLockIfOwned(lockPath, ownerPid) {
+    let rawContent;
+    try {
+        rawContent = fs.readFileSync(lockPath, "utf8");
+    }
+    catch {
+        // Absent or unreadable — nothing of ours to release.
+        return;
+    }
+    if (extractHolderPid(rawContent) === ownerPid) {
+        releaseLock(lockPath);
+    }
+}
 /**
  * Extract a PID from a sentinel body. Accepts the two shapes used across
  * the codebase: a bare numeric string (config-io, vault, lockfile) and

package/dist/tasks/backends/cron.js

@@ -64,13 +64,11 @@ export function CRON_BACKEND(options = {}) {
         },
         list() {
             const existing = readCrontab(exec);
-            const ids = [];
-            for (const line of existing.split(/\r?\n/)) {
-                const m = line.match(BLOCK_RE);
-                if (m)
-                    ids.push(m[1]);
-            }
-            return ids.map((id) => ({ id }));
+            return listBlocks(existing).map(({ id, body }) => ({ id, signature: normalizeSignature(body) }));
+        },
+        expectedSignature(task) {
+            const cronLine = buildCronLine(task, akmArgv, logDir);
+            return normalizeSignature(cronBlockBody(cronLine, task.enabled));
         },
     };
 }
@@ -82,9 +80,48 @@ export function buildCronLine(task, akmArgv, logDir) {
     const cmd = [...akmArgv, "tasks", "run", task.id].map((part) => quoteForCron(part)).join(" ");
     return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
 }
+/** The crontab line as it appears inside a block — commented when disabled. */
+export function cronBlockBody(cronLine, enabled) {
+    return enabled ? cronLine : `${DISABLED_PREFIX}${cronLine}`;
+}
 export function renderBlock(id, cronLine, enabled) {
-    const body = enabled ? cronLine : `${DISABLED_PREFIX}${cronLine}`;
-    return [BEGIN(id), body, END(id)].join("\n");
+    return [BEGIN(id), cronBlockBody(cronLine, enabled), END(id)].join("\n");
+}
+/**
+ * Parse the akm-owned blocks out of a crontab, returning each task id with the
+ * raw body line(s) between its BEGIN/END markers. Used by `list()` to build a
+ * drift signature, and exported for tests.
+ */
+export function listBlocks(existing) {
+    const out = [];
+    const lines = existing.split(/\r?\n/);
+    let currentId = null;
+    let body = [];
+    for (const line of lines) {
+        const begin = line.match(BLOCK_RE);
+        if (begin) {
+            currentId = begin[1];
+            body = [];
+            continue;
+        }
+        if (currentId !== null && line === END(currentId)) {
+            out.push({ id: currentId, body: body.join("\n") });
+            currentId = null;
+            body = [];
+            continue;
+        }
+        if (currentId !== null)
+            body.push(line);
+    }
+    return out;
+}
+/** Collapse incidental whitespace so signature comparison ignores it. */
+function normalizeSignature(body) {
+    return body
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .join("\n");
 }
 export function upsertBlock(existing, id, block) {
     const trimmed = existing.replace(/\s+$/g, "");

package/package.json

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

package/dist/commands/config-edit.js

@@ -1,344 +0,0 @@
-// 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/.
-/**
- * Interactive `akm config edit` — a schema-driven, menu-based config editor.
- *
- * ## Why @clack/prompts (not a widget TUI)
- *
- * The issue (#513) originally proposed a `neo-blessed` BIOS-style widget TUI.
- * After evaluation (see `docs/technical/ink-tui-evaluation.md` and the #513
- * comments) we ship this on `@clack/prompts` — the prompt library akm already
- * uses for `akm setup` and `confirmDestructive`. Zero new deps, the same
- * interaction paradigm as setup, and a proven packaging path through the
- * `bun build --compile` single binary.
- *
- * ## Schema-driven, single source of truth
- *
- * The section list, the per-section fields, and each field's input type are
- * DERIVED from the Zod config schema (`core/config/config-schema.ts`) by
- * {@link buildConfigEditModel}. There is no hand-maintained parallel field
- * table — adding a field to the schema makes it appear in the editor for free.
- *
- * ## Reuse, don't reimplement
- *
- * The write path reuses the existing machinery verbatim:
- *   - {@link setConfigValue} (the config-cli walker front-end) for coercion,
- *     validation, legacy aliasing, and apiKey rejection.
- *   - {@link loadConfig} / {@link saveConfig} for read/write.
- *   - {@link backupExistingConfig} for the timestamped pre-write snapshot.
- *
- * ## Pure core, thin shell
- *
- * {@link buildConfigEditModel} and {@link applyConfigEdit} are pure and unit
- * tested directly — no TTY required. {@link runConfigEdit} is the thin
- * @clack interaction layer.
- */
-import * as p from "@clack/prompts";
-import { z } from "zod";
-import { loadConfig, saveConfig } from "../core/config/config.js";
-import { backupExistingConfig } from "../core/config/config-io.js";
-import { AkmConfigShape } from "../core/config/config-schema.js";
-import { UsageError } from "../core/errors.js";
-import { getConfigPath } from "../core/paths.js";
-import { getConfigValue, setConfigValue } from "./config-cli.js";
-/** Maximum nesting depth walked when deriving fields. Guards against records. */
-const MAX_FIELD_DEPTH = 3;
-/** Strip Zod wrappers (.optional/.default/.nullable/.catch/.effects). */
-function unwrapSchema(schema) {
-    let current = schema;
-    for (;;) {
-        if (current instanceof z.ZodOptional)
-            current = current._def.innerType;
-        else if (current instanceof z.ZodDefault)
-            current = current._def.innerType;
-        else if (current instanceof z.ZodNullable)
-            current = current._def.innerType;
-        else if (current instanceof z.ZodCatch)
-            current = current._def.innerType;
-        else if (current instanceof z.ZodReadonly)
-            current = current._def.innerType;
-        else if (current instanceof z.ZodEffects)
-            current = current._def.schema;
-        else
-            return current;
-    }
-}
-/** Classify an unwrapped leaf schema into a {@link ConfigFieldKind}. */
-function classifyLeaf(schema, isSecret) {
-    if (isSecret)
-        return "secret";
-    if (schema instanceof z.ZodString)
-        return "text";
-    if (schema instanceof z.ZodNumber)
-        return "number";
-    if (schema instanceof z.ZodBoolean)
-        return "boolean";
-    if (schema instanceof z.ZodEnum)
-        return "select";
-    // ZodNativeEnum / ZodLiteral are treated as select/text fallbacks.
-    if (schema instanceof z.ZodLiteral)
-        return "text";
-    // Unions of primitives (e.g. configVersion: string|number) → text.
-    if (schema instanceof z.ZodUnion) {
-        const opts = schema._def.options.map(unwrapSchema);
-        if (opts.some((o) => o instanceof z.ZodString || o instanceof z.ZodNumber))
-            return "text";
-    }
-    return null;
-}
-/**
- * Recursively collect editable leaf fields from an object schema. Descends
- * into nested `z.object(...)` shapes (building dotted paths); records, arrays,
- * and unknown composites are surfaced as a single `json` field so the user can
- * still edit them as raw JSON via the walker's JSON coercion path.
- */
-function collectFields(schema, prefix, depth) {
-    const unwrapped = unwrapSchema(schema);
-    const fields = [];
-    if (unwrapped instanceof z.ZodObject && depth < MAX_FIELD_DEPTH) {
-        const shape = unwrapped.shape;
-        for (const [key, child] of Object.entries(shape)) {
-            const path = prefix ? `${prefix}.${key}` : key;
-            const childUnwrapped = unwrapSchema(child);
-            const isSecret = key === "apiKey";
-            if (childUnwrapped instanceof z.ZodObject && depth + 1 < MAX_FIELD_DEPTH) {
-                fields.push(...collectFields(childUnwrapped, path, depth + 1));
-                continue;
-            }
-            const kind = classifyLeaf(childUnwrapped, isSecret);
-            if (kind === null) {
-                // Records / arrays / nested composites at the depth limit: editable as JSON.
-                if (childUnwrapped instanceof z.ZodRecord ||
-                    childUnwrapped instanceof z.ZodArray ||
-                    childUnwrapped instanceof z.ZodObject) {
-                    fields.push({ path, label: key, kind: "json", secret: false });
-                }
-                continue;
-            }
-            const field = {
-                path,
-                label: key,
-                kind,
-                secret: kind === "secret",
-            };
-            if (kind === "select") {
-                field.options = [...childUnwrapped._def.values];
-            }
-            fields.push(field);
-        }
-    }
-    return fields;
-}
-/**
- * Build the schema-driven edit model: one section per top-level config key,
- * each with its editable leaf fields and input kinds. Pure — depends only on
- * the schema (the `config` argument is reserved for future value-aware
- * shaping; current callers pass it through unchanged for symmetry with
- * {@link applyConfigEdit}).
- *
- * Sections that yield no editable fields (pure records/arrays like `sources`,
- * `installed`, `registries`, `index`, `profiles`) are still surfaced with a
- * single `json` field so they remain reachable in the menu.
- */
-export function buildConfigEditModel(shape = AkmConfigShape, _config) {
-    const sections = [];
-    for (const [key, schema] of Object.entries(shape)) {
-        const unwrapped = unwrapSchema(schema);
-        let fields;
-        if (unwrapped instanceof z.ZodObject) {
-            fields = collectFields(unwrapped, key, 1);
-            if (fields.length === 0) {
-                fields = [{ path: key, label: key, kind: "json", secret: false }];
-            }
-        }
-        else {
-            const kind = classifyLeaf(unwrapped, false);
-            if (kind) {
-                const field = { path: key, label: key, kind, secret: false };
-                if (kind === "select")
-                    field.options = [...unwrapped._def.values];
-                fields = [field];
-            }
-            else {
-                // Arrays / records / unknown top-level shapes → editable as JSON.
-                fields = [{ path: key, label: key, kind: "json", secret: false }];
-            }
-        }
-        sections.push({ key, fields });
-    }
-    return sections.length > 0 ? { sections } : { sections: [] };
-}
-// ── Apply (pure write delegation) ────────────────────────────────────────────
-/**
- * Apply a single edit to a config object, returning the next config. Pure —
- * delegates to {@link setConfigValue} (the existing walker front-end), so it
- * inherits coercion, schema validation, legacy aliasing, AND the apiKey
- * rejection guard (#454). Callers must NOT pass apiKey paths; the editor shell
- * routes secrets to env-var guidance and never reaches here for them.
- *
- * @throws UsageError on apiKey paths, unknown keys, or invalid values.
- */
-export function applyConfigEdit(config, path, value) {
-    return setConfigValue(config, path, value);
-}
-/** Environment variable a secret field steers the user toward (#454). */
-export function envVarForSecret(path) {
-    if (path === "embedding.apiKey")
-        return "AKM_EMBED_API_KEY";
-    if (path === "llm.apiKey")
-        return "AKM_LLM_API_KEY";
-    if (path.startsWith("profiles.llm."))
-        return "AKM_LLM_API_KEY";
-    return "AKM_LLM_API_KEY / AKM_EMBED_API_KEY";
-}
-// ── Interactive shell (thin @clack layer) ────────────────────────────────────
-/**
- * Determine whether the current process can run an interactive editor.
- * Requires a real TTY on both stdin and stdout and a non-CI environment.
- */
-export function isInteractiveTerminal(env = process.env) {
-    const ci = env.CI;
-    const isCi = ci !== undefined && ci !== null && !["", "0", "false"].includes(String(ci).trim().toLowerCase());
-    if (isCi)
-        return false;
-    return process.stdin.isTTY === true && process.stdout.isTTY === true;
-}
-const NON_INTERACTIVE_MESSAGE = "`akm config edit` is interactive and requires a TTY. " +
-    "Use `akm config set <key> <value>` for scripted or CI edits.";
-function formatValue(value) {
-    if (value === null || value === undefined)
-        return "(unset)";
-    if (typeof value === "object")
-        return JSON.stringify(value);
-    return String(value);
-}
-/**
- * Run the interactive config editor. Throws {@link UsageError} when no TTY is
- * available (CI / piped). Otherwise drives a menu loop:
- *   section select → field select → typed value prompt → confirm → backup+save.
- */
-export async function runConfigEdit() {
-    if (!isInteractiveTerminal()) {
-        throw new UsageError(NON_INTERACTIVE_MESSAGE, "NON_INTERACTIVE_REQUIRES_YES");
-    }
-    let config = loadConfig();
-    const model = buildConfigEditModel(AkmConfigShape, config);
-    let dirty = false;
-    p.intro("akm config edit");
-    for (;;) {
-        const sectionKey = await p.select({
-            message: "Select a config section to edit:",
-            options: [
-                ...model.sections.map((s) => ({ value: s.key, label: s.key })),
-                { value: "__exit__", label: dirty ? "Save and exit" : "Exit" },
-            ],
-        });
-        if (p.isCancel(sectionKey) || sectionKey === "__exit__")
-            break;
-        const section = model.sections.find((s) => s.key === sectionKey);
-        if (!section)
-            continue;
-        const fieldPath = await p.select({
-            message: `Select a field in "${section.key}":`,
-            options: [
-                ...section.fields.map((f) => ({
-                    value: f.path,
-                    label: f.label,
-                    hint: `${f.kind} — ${formatValue(safeGet(config, f.path))}`,
-                })),
-                { value: "__back__", label: "← Back" },
-            ],
-        });
-        if (p.isCancel(fieldPath) || fieldPath === "__back__")
-            continue;
-        const field = section.fields.find((f) => f.path === fieldPath);
-        if (!field)
-            continue;
-        // #454: never persist secrets. Show env-var guidance and skip the write.
-        if (field.secret) {
-            p.note(`API keys are never stored in config (they leak through backups, logs, and version control).\n` +
-                `Export the environment variable instead:\n\n  export ${envVarForSecret(field.path)}=…\n\n` +
-                `AKM reads it at request time.`, "apiKey is not persisted");
-            continue;
-        }
-        const newValue = await promptForField(field, safeGet(config, field.path));
-        if (newValue === undefined)
-            continue; // cancelled / back
-        try {
-            config = applyConfigEdit(config, field.path, newValue);
-            dirty = true;
-            p.log.success(`Set ${field.path} = ${newValue}`);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            p.log.error(msg);
-        }
-    }
-    if (!dirty) {
-        p.outro("No changes made.");
-        return;
-    }
-    const confirmed = await p.confirm({ message: "Save changes to config?", initialValue: true });
-    if (p.isCancel(confirmed) || confirmed !== true) {
-        p.outro("Discarded changes.");
-        return;
-    }
-    const backup = backupExistingConfig(getConfigPath());
-    saveConfig(config);
-    if (backup) {
-        p.outro(`Saved. Backup written to ${backup.timestamped}`);
-    }
-    else {
-        p.outro("Saved.");
-    }
-}
-/** Read a value via the existing walker front-end, swallowing unknown-key errors. */
-function safeGet(config, path) {
-    try {
-        return getConfigValue(config, path);
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Prompt for a single field's new value, typed by its schema-derived kind.
- * Returns the raw string to pass to {@link applyConfigEdit}, or `undefined`
- * when the user cancels.
- */
-async function promptForField(field, current) {
-    if (field.kind === "boolean") {
-        const v = await p.confirm({
-            message: `${field.label}:`,
-            initialValue: current === true,
-        });
-        if (p.isCancel(v))
-            return undefined;
-        return v ? "true" : "false";
-    }
-    if (field.kind === "select" && field.options) {
-        const v = await p.select({
-            message: `${field.label}:`,
-            options: field.options.map((o) => ({ value: o, label: o })),
-            initialValue: typeof current === "string" ? current : undefined,
-        });
-        if (p.isCancel(v))
-            return undefined;
-        return v;
-    }
-    const placeholder = field.kind === "json" ? "JSON value (or empty to clear)" : "";
-    const initial = current === null || current === undefined
-        ? ""
-        : typeof current === "object"
-            ? JSON.stringify(current)
-            : String(current);
-    const v = await p.text({
-        message: `${field.label}${field.kind === "number" ? " (number)" : ""}:`,
-        placeholder,
-        initialValue: initial,
-    });
-    if (p.isCancel(v))
-        return undefined;
-    return v;
-}