akm-cli 0.8.3 → 0.9.0-beta.1

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

@@ -3,13 +3,15 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { backupExistingConfig, parseConfigText, withConfigLock, writeConfigAtomic } from "./config-io";
-import { CURRENT_CONFIG_VERSION, compareConfigVersion, migrateConfigShape } from "./config-migration";
-import { AkmConfigSchema } from "./config-schema";
-import { ConfigError } from "./errors";
-export { stripJsonComments } from "./config-io";
-import { getCacheDir, getConfigPath } from "./paths";
-import { warn } from "./warn";
+import { ConfigError } from "../errors.js";
+import { backupExistingConfig, parseConfigText, withConfigLock, writeConfigAtomic } from "./config-io.js";
+import { CURRENT_CONFIG_VERSION, compareConfigVersion, migrateConfigShape } from "./config-migration.js";
+import { AkmConfigSchema } from "./config-schema.js";
+export { stripJsonComments } from "./config-io.js";
+import { getCacheDir, getConfigPath } from "../paths.js";
+import { warn } from "../warn.js";
+// Canonical harness-id source of truth (#565) — runtime value re-export.
+export { VALID_HARNESS_IDS } from "./config-types.js";
 // ── Feedback failure-mode constants (F-3 / #384) ────────────────────────────
 /**
  * Curated taxonomy of failure modes for negative feedback.
@@ -409,7 +411,7 @@ export function getIndexPassConfig(config, passName) {
     return entry;
 }
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
-export { parseSourceSpec, resolveConfiguredSources } from "./config-sources";
+export { parseSourceSpec, resolveConfiguredSources } from "./config-sources.js";
 /**
  * Merge a partial user-config override onto a base config. Used by
  * {@link loadUserConfig} (DEFAULT_CONFIG + on-disk) and {@link updateConfig}

package/dist/core/env-secret-ref.js

@@ -0,0 +1,90 @@
+// 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/.
+/**
+ * Shared ref-resolution helpers for the `env` and `secret` command families
+ * (WS6). These were duplicated/co-located inline in `src/cli.ts`; hoisting them
+ * here lets `src/commands/env/env-cli.ts` and `src/commands/env/secret-cli.ts` import a
+ * single copy of the parse/resolve/make + path-traversal-guard logic (the WS6
+ * "env traversal-guard copies 5 → 1" KPI). Behaviour is byte-identical to the
+ * inline forms: env/secret VALUES are never read or surfaced here — these
+ * helpers only resolve refs to absolute paths and guard against directory
+ * traversal.
+ */
+import path from "node:path";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "./asset/asset-create.js";
+import { parseAssetRef } from "./asset/asset-ref.js";
+import { resolveAssetPathFromName } from "./asset/asset-spec.js";
+import { isWithin } from "./common.js";
+import { loadConfig } from "./config/config.js";
+import { NotFoundError, UsageError } from "./errors.js";
+export function parseEnvRef(ref) {
+    return parseAssetRef(ref.includes(":") ? ref : `env:${ref}`);
+}
+export function findEnvSource(origin) {
+    const sources = resolveSourceEntries(undefined, loadConfig());
+    if (sources.length === 0) {
+        throw new UsageError("No stashes configured. Run `akm init` to create your working stash.");
+    }
+    if (!origin || origin === "local")
+        return sources[0];
+    const named = sources.find((source) => source.registryId === origin);
+    if (!named) {
+        throw new NotFoundError(`Source not found for origin: ${origin}`);
+    }
+    return named;
+}
+export function makeEnvRef(name, source) {
+    return source?.registryId ? `${source.registryId}//env:${name}` : `env:${name}`;
+}
+/**
+ * Resolve an env ref to an absolute `.env` path. Accepts `env:` and
+ * `environment:` (alias) refs as well as bare names. The path is returned even
+ * when the file does not yet exist (so `create` writes under `env/`).
+ */
+export function resolveEnvPath(ref) {
+    const parsed = parseEnvRef(ref);
+    if (parsed.type !== "env") {
+        throw new UsageError(`Expected an env ref (env:<name>); got "${ref}".`);
+    }
+    const source = findEnvSource(parsed.origin);
+    const envRoot = path.join(source.path, "env");
+    const envPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the env directory.
+    // validateName already rejects traversal patterns like "../../foo", but an
+    // absolute-path override or symlink-based attack could still escape without
+    // this second check.
+    if (!isWithin(envPath, envRoot)) {
+        throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+    }
+    return { name: parsed.name, absPath: envPath, source, parsedRef: parsed, dir: "env" };
+}
+export function parseSecretRef(ref) {
+    return parseAssetRef(ref.includes(":") ? ref : `secret:${ref}`);
+}
+export function makeSecretRef(name, source) {
+    return source?.registryId ? `${source.registryId}//secret:${name}` : `secret:${name}`;
+}
+export function resolveSecretPath(ref, 
+// Create-only (`secret set`): enforce a flat ref name and apply `--path` as
+// the subdirectory. Lookup callers omit this so nested refs keep resolving.
+create) {
+    const parsed = parseSecretRef(ref);
+    if (parsed.type !== "secret") {
+        throw new UsageError(`Expected a secret ref (secret:<name>); got "${ref}".`);
+    }
+    if (create) {
+        assertFlatAssetName(parsed.name);
+        parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
+    }
+    // Source resolution is identical for every asset type; reuse the env helper.
+    const source = findEnvSource(parsed.origin);
+    const typeRoot = path.join(source.path, "secrets");
+    const absPath = resolveAssetPathFromName("secret", typeRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
+    if (!isWithin(absPath, typeRoot)) {
+        throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
+    }
+    return { name: parsed.name, absPath, source };
+}

package/dist/core/errors.js

@@ -34,8 +34,16 @@ const NOT_FOUND_HINTS = {
     WORKFLOW_NOT_FOUND: "Run `akm workflow list --active` to see runs.",
     FILE_NOT_FOUND: "Check the path exists and is readable.",
 };
+/**
+ * Base class for all akm-thrown, classified errors. Carries the `kind`
+ * discriminant consumed by the CLI exit-code classifier. Errors that are NOT
+ * instances of `AkmError` are treated as genuinely unexpected (INTERNAL).
+ */
+export class AkmError extends Error {
+}
 /** Raised when configuration or environment is invalid or missing. */
-export class ConfigError extends Error {
+export class ConfigError extends AkmError {
+    kind = "config";
     code;
     _hint;
     constructor(msg, code = "INVALID_CONFIG_FILE", hint) {
@@ -51,7 +59,8 @@ export class ConfigError extends Error {
     }
 }
 /** Raised when the user supplies invalid arguments or input. */
-export class UsageError extends Error {
+export class UsageError extends AkmError {
+    kind = "usage";
     code;
     _hint;
     constructor(msg, code = "INVALID_FLAG_VALUE", hint) {
@@ -67,7 +76,8 @@ export class UsageError extends Error {
     }
 }
 /** Raised when a requested resource (asset, entry, file) is not found. */
-export class NotFoundError extends Error {
+export class NotFoundError extends AkmError {
+    kind = "not-found";
     code;
     _hint;
     constructor(msg, code = "ASSET_NOT_FOUND", hint) {

package/dist/core/events.js

@@ -1,11 +1,34 @@
 // 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/.
+/**
+ * Append-only events stream — backed by state.db (#204, Phase 3).
+ *
+ * Every mutating CLI verb funnels through `appendEvent` so external
+ * observers (sync, replication, audit, dashboards) can react to stash
+ * changes. Events are stored in the `events` table in `state.db`
+ * (SQLite, WAL mode) instead of a flat `events.jsonl` file.
+ *
+ * The helper is the only thing in akm that writes to the events table. It
+ * accepts an injectable `dbPath` (via `EventsContext`) so tests can pin a
+ * tmpdir without any global mutation.
+ *
+ * Format (each EventEnvelope):
+ *   { "schemaVersion": 1, "id": <number>, "ts": "<ISO>",
+ *     "eventType": "<verb>", "ref"?: "<asset-ref>", ... }
+ *
+ * - `id` is a monotonic SQLite AUTOINCREMENT rowid. Callers can persist it
+ *   as a durable cursor for `--since` resumption (replaces the old byte-offset
+ *   cursor). The public API still surfaces this as `nextOffset` (an opaque
+ *   number) for backward compatibility with callers that stored byte-offset
+ *   cursors.
+ * - `ts` is ISO-8601 (UTC, millisecond precision).
+ */
 import path from "node:path";
-import { rethrowIfTestIsolationError } from "./errors";
-import { getDataDir } from "./paths";
-import { insertEvent, openStateDatabase, readStateEvents } from "./state-db";
-import { error } from "./warn";
+import { rethrowIfTestIsolationError } from "./errors.js";
+import { getDataDir } from "./paths.js";
+import { insertEvent, openStateDatabase, readStateEvents } from "./state-db.js";
+import { error } from "./warn.js";
 /**
  * Legacy events.jsonl path — used only by the migration script
  * (`scripts/migrate-storage.ts`) to import existing event history into

package/dist/core/file-lock.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
-import { isProcessAlive } from "./common";
+import { isProcessAlive } from "./common.js";
 /**
  * Atomically create a sentinel at `lockPath` with `payload` as the body.
  * Returns true if we now own the lock, false if a sentinel already

package/dist/core/improve-types.js

@@ -0,0 +1,48 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { assertNever } from "./assert.js";
+/**
+ * Map an {@link ImproveActionMode} to its coarse audit bucket. Single source of
+ * truth shared by `state-db.ts#computeImproveRunMetrics` and
+ * `improve.ts#emitImproveCompletedEvent` so the aggregate accepted/rejected/
+ * error counts can never disagree between the persisted `metrics_json` and the
+ * emitted `improve_completed` event.
+ *
+ * Buckets:
+ * - `accepted` — a write/content-authoring action succeeded.
+ * - `rejected` — the action was deliberately not applied (cooldown, skip,
+ *   distill-skip, or a content-policy guard rejection). NOTE: as of the
+ *   round-2 health pass `reflect-guard-rejected` is bucketed here. Previously
+ *   the `state-db.ts` switch omitted it entirely (no case, no default), so a
+ *   guard rejection silently vanished from accepted/rejected/error totals — a
+ *   data-integrity miscount. It is a deliberate non-application of the action,
+ *   so it belongs with the other "rejected" outcomes.
+ * - `error` — the action failed (LLM/runtime error).
+ * - `noop` — bookkeeping that is neither a write nor a rejection (memory-prune);
+ *   intentionally counted in none of the three numeric buckets.
+ *
+ * The `default: assertNever(mode)` arm makes any future union variant a
+ * compile-time error here, forcing an explicit bucket choice.
+ */
+export function classifyImproveAction(mode) {
+    switch (mode) {
+        case "reflect":
+        case "distill":
+        case "memory-inference":
+        case "graph-extraction":
+            return "accepted";
+        case "reflect-cooldown":
+        case "reflect-skipped":
+        case "distill-skipped":
+        case "reflect-guard-rejected":
+            return "rejected";
+        case "reflect-failed":
+        case "error":
+            return "error";
+        case "memory-prune":
+            return "noop";
+        default:
+            return assertNever(mode);
+    }
+}

package/dist/core/lesson-lint.js

@@ -23,8 +23,8 @@
  * without dragging in the rest of the runtime.
  */
 import fs from "node:fs";
-import { UsageError } from "./errors";
-import { parseFrontmatter } from "./frontmatter";
+import { parseFrontmatter } from "./asset/frontmatter.js";
+import { UsageError } from "./errors.js";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }

package/dist/core/paths.js

@@ -10,8 +10,8 @@
  */
 import os from "node:os";
 import path from "node:path";
-import { IS_WINDOWS } from "./common";
-import { ConfigError } from "./errors";
+import { IS_WINDOWS } from "./common.js";
+import { ConfigError } from "./errors.js";
 /**
  * Returns true when the current process appears to be running under
  * `bun test` (either via the BUN_TEST sentinel Bun sets on the test

package/dist/core/ripgrep/install.js

@@ -4,8 +4,8 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "../common";
-import { RG_BINARY, resolveRg } from "./resolve";
+import { IS_WINDOWS } from "../common.js";
+import { RG_BINARY, resolveRg } from "./resolve.js";
 /**
  * Platform and architecture detection for ripgrep binary downloads.
  */

package/dist/core/ripgrep/resolve.js

@@ -3,8 +3,8 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "../common";
-import { getBinDir } from "../paths";
+import { IS_WINDOWS } from "../common.js";
+import { getBinDir } from "../paths.js";
 export const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
 function canExecute(filePath) {
     if (!fs.existsSync(filePath))

package/dist/core/state-db.js

@@ -49,11 +49,13 @@
  *
  * @module state-db
  */
-import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import path from "node:path";
-import { getDataDir } from "./paths";
-import { error } from "./warn";
+import { openDatabase } from "../storage/database.js";
+import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { classifyImproveAction } from "./improve-types.js";
+import { getDataDir } from "./paths.js";
+import { error } from "./warn.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -96,7 +98,7 @@ export function openStateDatabase(dbPath) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const db = new Database(resolvedPath);
+    const db = openDatabase(resolvedPath);
     // PRAGMAs must run before any DDL or DML.
     db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA foreign_keys = ON");
@@ -104,6 +106,12 @@ export function openStateDatabase(dbPath) {
     runMigrations(db);
     return db;
 }
+// ── Migration engine ─────────────────────────────────────────────────────────
+//
+// The runner itself (ensureMigrationsTable + runMigrations) lives in the shared
+// engine at src/storage/engines/sqlite-migrations.ts. This module owns only its
+// own MIGRATIONS array and delegates application to that shared runner. The
+// {@link Migration} interface is imported from there.
 /**
  * All migrations in application order. New migrations are APPENDED to this
  * array — never inserted in the middle or reordered.
@@ -451,41 +459,16 @@ const MIGRATIONS = [
     `,
     },
 ];
-/**
- * Create the migrations table if it does not exist. This must be called
- * unconditionally on every open so a fresh database bootstraps correctly.
- */
-function ensureMigrationsTable(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS schema_migrations (
-      id         TEXT    PRIMARY KEY,
-      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
-    );
-  `);
-}
 /**
  * Apply every pending migration in a single transaction per migration.
  *
- * Each migration is applied in its own transaction so a failure in migration N
- * does not roll back already-applied migrations 1..N-1. The migration row is
- * inserted AFTER the DDL succeeds, so a crash mid-migration leaves no row and
- * the migration will be retried on next open (all DDL in `up` uses IF NOT
- * EXISTS so the retry is safe).
+ * Delegates to the shared SQLite migration engine; state.db has no
+ * pre-versioning bootstrap step, so no `bootstrap` hook is passed.
  *
  * Called automatically by `openStateDatabase()`.
  */
 export function runMigrations(db) {
-    ensureMigrationsTable(db);
-    const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
-    const applied = new Set(appliedRows.map((r) => r.id));
-    for (const migration of MIGRATIONS) {
-        if (applied.has(migration.id))
-            continue;
-        db.transaction(() => {
-            db.exec(migration.up);
-            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
-        })();
-    }
+    runSqliteMigrations(db, MIGRATIONS);
 }
 /**
  * Convert a raw `EventRow` from the database to the public `EventEnvelope`
@@ -779,6 +762,47 @@ export function queryTaskHistory(db, options = {}) {
        FROM task_history ${where} ORDER BY started_at DESC`)
         .all(...params);
 }
+/**
+ * Read COMPLETED `akm-improve` task_history runs whose `started_at` falls in
+ * `[since, until)` (or `started_at >= since` when `until` is omitted), ordered
+ * oldest-first by `started_at`. Only rows with a non-null `completed_at` are
+ * returned (in-flight runs are excluded). The `task_id = 'akm-improve'`
+ * predicate is fixed because the only caller (commands/health.ts
+ * `loadTaskIntervals`) builds wall-time intervals for the improve cron task.
+ *
+ * Owns the SQL formerly inlined in commands/health.ts. Note the bound is
+ * EXCLUSIVE on the upper end (`started_at < ?`) — callers pass an already
+ * widened window; this helper does not widen.
+ *
+ * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
+ * returning.
+ */
+export function queryCompletedTaskIntervals(db, since, until) {
+    const sql = until
+        ? "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND started_at < ? AND completed_at IS NOT NULL ORDER BY started_at"
+        : "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND completed_at IS NOT NULL ORDER BY started_at";
+    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
+}
+// ── schema introspection ─────────────────────────────────────────────────────
+/**
+ * Return the subset of `names` that exist as TABLEs in this database, ordered
+ * by name. Used by health's state-db-schema check to detect missing required
+ * tables without leaking a `sqlite_master` query into command code.
+ *
+ * The `IN (...)` predicate is built from parameter placeholders so table names
+ * are bound, never interpolated.
+ *
+ * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
+ * returning.
+ */
+export function listExistingTableNames(db, names) {
+    if (names.length === 0)
+        return [];
+    const placeholders = names.map(() => "?").join(", ");
+    return db
+        .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders}) ORDER BY name`)
+        .all(...names);
+}
 // ── events.jsonl import ──────────────────────────────────────────────────────
 /**
  * Import all events from an `events.jsonl` file into the `events` table.
@@ -877,25 +901,23 @@ export function computeImproveRunMetrics(result) {
     let autoAcceptedCount = 0;
     let errorCount = 0;
     for (const action of actions) {
-        switch (action.mode) {
-            case "reflect":
-            case "distill":
-            case "memory-inference":
-            case "graph-extraction":
+        // Bucketing delegated to the shared classifyImproveAction so this aggregate
+        // and the improve_completed event in improve.ts can never disagree, and so a
+        // new union variant is a compile error rather than a silent drop. Note:
+        // `reflect-guard-rejected` now counts as "rejected" (previously this switch
+        // omitted it entirely — a data-integrity miscount). "noop" (memory-prune) is
+        // intentionally counted in none of the three numeric buckets.
+        switch (classifyImproveAction(action.mode)) {
+            case "accepted":
                 acceptedCount++;
                 break;
-            case "reflect-cooldown":
-            case "reflect-skipped":
-            case "distill-skipped":
+            case "rejected":
                 rejectedCount++;
                 break;
-            case "reflect-failed":
             case "error":
                 errorCount++;
                 break;
-            case "memory-prune":
-                // Prune is bookkeeping, not "accepted" content authoring; count
-                // separately as a no-op for the audit aggregate.
+            case "noop":
                 break;
         }
         // Legacy: pre-gate action results may carry autoAccepted: true (reflect path).
@@ -929,6 +951,26 @@ export function recordImproveRun(db, input) {
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.profile, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
 }
+/**
+ * Read real (non-dry-run) improve_runs rows whose `started_at` falls in the
+ * window `[since, until)`. When `until` is omitted the window is open-ended
+ * (`started_at >= since`). Rows are returned newest-first (`ORDER BY
+ * started_at DESC`).
+ *
+ * Owns the SQL formerly inlined in commands/health.ts (`loadImproveRunRows`).
+ * The `dry_run = 0` filter is first-class so dry-run probes never pollute
+ * productivity audits.
+ *
+ * Connection-lifetime rule (WS5): `.all()` fully materializes the result set
+ * into a plain array before returning — no live cursor escapes the caller's
+ * `openStateDatabase` scope.
+ */
+export function queryImproveRuns(db, since, until) {
+    const sql = until
+        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
+        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
+    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
+}
 /**
  * Delete improve_runs rows older than `retentionDays` (default: 90). Mirrors
  * {@link purgeOldEvents} — same default, same return shape (number of rows
@@ -1027,7 +1069,7 @@ export function shouldSkipAlreadyExtractedSession(prior, liveSessionEndedAtMs) {
 // ── registry_index_cache (goes in index.db, not state.db) ───────────────────
 /**
  * DDL for the `registry_index_cache` table that lives in the EXISTING index.db
- * (managed by src/indexer/db.ts).
+ * (managed by src/indexer/db/db.ts).
  *
  * Design: uses the same migration-safe ADD COLUMN approach. The table is
  * created with CREATE TABLE IF NOT EXISTS so it is safe to call inside
@@ -1051,7 +1093,7 @@ export function shouldSkipAlreadyExtractedSession(prior, liveSessionEndedAtMs) {
  *   ALTER TABLE registry_index_cache ADD COLUMN error_message TEXT DEFAULT NULL;
  *
  * To add this table to index.db, call ensureRegistryIndexCacheSchema(db) from
- * within ensureSchema() in src/indexer/db.ts, or add it as a new CREATE TABLE
+ * within ensureSchema() in src/indexer/db/db.ts, or add it as a new CREATE TABLE
  * IF NOT EXISTS block inside the existing ensureSchema() call.
  */
 export const REGISTRY_INDEX_CACHE_DDL = `