akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/workflows/db.js

@@ -1,215 +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/.
-import fs from "node:fs";
-import path from "node:path";
-import { getWorkflowDbPath } from "../core/paths.js";
-import { openDatabase } from "../storage/database.js";
-import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
-import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
-/**
- * workflow.db — Durable SQLite database for workflow run state.
- *
- * Owns the `workflow_runs` and `workflow_run_steps` tables that track active /
- * completed workflow executions. Like `state.db` (and unlike `index.db`), the
- * rows here are NON-REGENERABLE — losing them is data loss. Schema must evolve
- * via incremental, additive migrations recorded in `schema_migrations`.
- *
- * ## Migration-safety contract
- *
- * The `schema_migrations` table records every applied migration by a stable
- * string ID. `runMigrations(db)` is idempotent: new installs run every
- * migration in order; upgrades run only the ones not yet applied. The
- * migration framework here intentionally mirrors `src/core/state-db.ts` so
- * future schema evolution follows a single proven pattern.
- *
- * Permitted schema evolution operations (always migration-safe in SQLite):
- *   - ALTER TABLE … ADD COLUMN <name> <type> DEFAULT <value>
- *   - CREATE INDEX IF NOT EXISTS …
- *   - CREATE TABLE IF NOT EXISTS … (additive new tables)
- *
- * ## Bootstrapping pre-versioning databases
- *
- * Workflow databases created before this file gained `schema_migrations`
- * already have the `workflow_runs.scope_key` column applied by the previous
- * ad-hoc `PRAGMA table_info` + `ALTER TABLE` code. To avoid re-running the
- * migration (which would no-op but still wastes work and clutters logs), the
- * runner detects this state and back-fills the `schema_migrations` row for
- * the scope-key migration before evaluating the migration list. See
- * `bootstrapPreVersioningDb()`.
- *
- * @module workflows/db
- */
-// ── Public API ───────────────────────────────────────────────────────────────
-export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
-    const dir = path.dirname(dbPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    const db = openDatabase(dbPath);
-    // #589: 30 s busy timeout, matching index.db / state.db. Without it the
-    // default is 0 ms, so any concurrent writer fails immediately with
-    // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
-    applyStandardPragmas(db, { dataDir: dir });
-    ensureBaseSchema(db);
-    runMigrations(db);
-    return db;
-}
-export function closeWorkflowDatabase(db) {
-    db.close();
-}
-// ── Base schema ──────────────────────────────────────────────────────────────
-/**
- * Create the baseline `workflow_runs` and `workflow_run_steps` tables if they
- * do not exist. These statements are idempotent: existing databases keep their
- * current schema, and migrations evolve them further.
- *
- * NOTE: the `scope_key` column on `workflow_runs` is intentionally NOT declared
- * here. It is added by migration `001-add-scope-key`. Fresh databases will run
- * the migration immediately on first open; pre-versioning databases that
- * already have the column are bootstrapped — see {@link runMigrations}.
- */
-function ensureBaseSchema(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS workflow_runs (
-      id                TEXT PRIMARY KEY,
-      workflow_ref      TEXT NOT NULL,
-      workflow_entry_id INTEGER,
-      workflow_title    TEXT NOT NULL,
-      status            TEXT NOT NULL CHECK (status IN ('active', 'completed', 'blocked', 'failed')),
-      params_json       TEXT NOT NULL DEFAULT '{}',
-      current_step_id   TEXT,
-      created_at        TEXT NOT NULL,
-      updated_at        TEXT NOT NULL,
-      completed_at      TEXT
-    );
-
-    CREATE INDEX IF NOT EXISTS idx_workflow_runs_ref ON workflow_runs(workflow_ref);
-    CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
-
-    CREATE TABLE IF NOT EXISTS workflow_run_steps (
-      run_id          TEXT NOT NULL,
-      step_id         TEXT NOT NULL,
-      step_title      TEXT NOT NULL,
-      instructions    TEXT NOT NULL,
-      completion_json TEXT,
-      sequence_index  INTEGER NOT NULL,
-      status          TEXT NOT NULL CHECK (status IN ('pending', 'completed', 'blocked', 'failed', 'skipped')),
-      notes           TEXT,
-      evidence_json   TEXT,
-      completed_at    TEXT,
-      PRIMARY KEY (run_id, step_id),
-      FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
-    );
-
-    CREATE INDEX IF NOT EXISTS idx_workflow_run_steps_run_sequence
-      ON workflow_run_steps(run_id, sequence_index);
-  `);
-}
-// ── Migration engine ─────────────────────────────────────────────────────────
-//
-// The runner itself (ensureMigrationsTable + runMigrations) lives in the shared
-// engine at src/storage/engines/sqlite-migrations.ts. This module owns its own
-// MIGRATIONS array plus the pre-versioning `bootstrap` hook, and delegates
-// application to that shared runner. The {@link Migration} interface is imported
-// from there.
-/**
- * All workflow.db migrations in application order. New migrations are
- * APPENDED — never inserted in the middle or reordered.
- */
-const MIGRATIONS = [
-    // ── Migration 001 — add scope_key column ────────────────────────────────────
-    //
-    // Adds the `scope_key` column to `workflow_runs` so runs can be partitioned
-    // per stash/scope. Pre-versioning databases that already have this column
-    // are bootstrapped before this migration runs — see runMigrations().
-    {
-        id: "001-add-scope-key",
-        up: `
-      ALTER TABLE workflow_runs ADD COLUMN scope_key TEXT;
-
-      CREATE INDEX IF NOT EXISTS idx_workflow_runs_scope_ref_status
-        ON workflow_runs(scope_key, workflow_ref, status);
-    `,
-    },
-    // ── Migration 002 — record agent harness + session identity ──────────────────
-    //
-    // Persists the agent harness identifier (e.g. "claude-code", "opencode") and
-    // the platform-native session id that owns each workflow run. This is the
-    // first concrete slice of #501 / #506: capturing *who* is driving a run so a
-    // future (separately-approved) monitor can correlate workflow runs with
-    // session activity. Both columns are nullable — runs started outside an agent
-    // harness, and all pre-existing runs, simply have NULL identity.
-    {
-        id: "002-add-agent-identity",
-        up: `
-      ALTER TABLE workflow_runs ADD COLUMN agent_harness TEXT;
-      ALTER TABLE workflow_runs ADD COLUMN agent_session_id TEXT;
-
-      CREATE INDEX IF NOT EXISTS idx_workflow_runs_agent_session
-        ON workflow_runs(agent_harness, agent_session_id);
-    `,
-    },
-    // ── Migration 003 — check-in arming + per-step summary (#506) ────────────────
-    //
-    // Builds on the agent identity recorded by migration 002. Arms a file-signal
-    // check-in (a timestamp, NOT a background thread — see
-    // docs/technical/workflow-agent-checkin-adr.md) so a stalled run can be
-    // re-targeted with a `continue` directive, and adds a per-step `summary`
-    // column so step/workflow completion can capture and validate a required
-    // summary of work done. Both columns are nullable.
-    {
-        id: "003-checkin-and-step-summary",
-        up: `
-      ALTER TABLE workflow_runs ADD COLUMN checkin_armed_at TEXT;
-      ALTER TABLE workflow_run_steps ADD COLUMN summary TEXT;
-    `,
-    },
-];
-/**
- * Stable id of the scope_key migration. Exported for bootstrap detection and
- * tests.
- */
-const SCOPE_KEY_MIGRATION_ID = "001-add-scope-key";
-/**
- * Detect whether a column exists on a given table.
- */
-function hasColumn(db, table, column) {
-    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
-    return rows.some((r) => r.name === column);
-}
-/**
- * Back-fill `schema_migrations` rows for any schema state that existed before
- * this file gained migration tracking.
- *
- * The pre-versioning code added the `scope_key` column on `workflow_runs` via
- * an ad-hoc PRAGMA / ALTER TABLE pair. Those databases must not re-run the
- * scope_key migration (the ALTER would fail with "duplicate column name"
- * since the migration body does not use IF NOT EXISTS — SQLite does not
- * support that clause on ALTER TABLE ADD COLUMN). Instead, we mark the
- * migration as already applied.
- *
- * This function is a no-op on fresh databases: the `scope_key` column does
- * not exist, so the migration runs normally and records itself.
- */
-function bootstrapPreVersioningDb(db) {
-    const alreadyRecorded = db.prepare("SELECT 1 FROM schema_migrations WHERE id = ?").get(SCOPE_KEY_MIGRATION_ID);
-    if (alreadyRecorded)
-        return;
-    if (hasColumn(db, "workflow_runs", "scope_key")) {
-        db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(SCOPE_KEY_MIGRATION_ID);
-    }
-}
-/**
- * Apply every pending migration in a single transaction per migration.
- *
- * Delegates to the shared SQLite migration engine, passing the
- * `bootstrapPreVersioningDb` hook so databases created before this file gained
- * migration tracking back-fill their scope_key row instead of re-running the
- * ALTER.
- *
- * Called automatically by {@link openWorkflowDatabase}.
- */
-export function runMigrations(db) {
-    runSqliteMigrations(db, MIGRATIONS, { bootstrap: bootstrapPreVersioningDb });
-}

package/docs/data-and-telemetry.md

@@ -1,226 +0,0 @@
-# AKM Data & Telemetry
-
-AKM stores data locally on your machine. **It has no remote telemetry.** No data is sent to Anthropic, the AKM project, or any third party. This document describes exactly what AKM reads and writes on your machine.
-
-## No Remote Data Collection
-
-AKM does not:
-- Send usage data, events, or crash reports to any server
-- Contact any AKM-operated endpoint at runtime (only your own configured LLM/embedding endpoints)
-- Include any analytics SDK or beacon
-- Collect email, name, or any personally-identifying information
-
-The only network requests AKM makes are:
-1. Fetching registry metadata and stash packages from sources you explicitly configure (GitHub, npm, websites)
-2. Calls to your configured LLM/embedding endpoint (if you enabled those features)
-3. `akm upgrade` — fetches the latest release from GitHub releases
-4. `akm setup` — a single DNS lookup for `github.com` to decide whether to skip network-dependent steps (Ollama detection, remote embedding probes) when offline. No HTTP request is made by this probe; if it succeeds, akm proceeds with the network-dependent steps you already configured.
-
----
-
-## Local On-Disk Surface
-
-AKM writes to these locations on your machine. All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions on Linux/macOS and Windows conventions on Windows.
-
-### Config Directory (`$XDG_CONFIG_HOME/akm` or `~/.config/akm/`)
-
-| Path | Contents | Safe to delete? |
-|---|---|---|
-| `config.json` | Your AKM configuration: LLM endpoints, stash paths, feature flags, profiles | **No** — deleting resets all settings |
-
-Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
-
-### Data Directory (`$XDG_DATA_HOME/akm` or `~/.local/share/akm/`)
-
-| Path | Contents | Safe to delete? |
-|---|---|---|
-| `index.db` | Search index for all your stash assets (FTS5 + metadata) | Yes — rebuilds via `akm index --full` |
-| `workflow.db` | Workflow run state and history | Caution — deletes run history |
-| `state.db` | Events, proposals, task history, improve run results | **No** — deletes event log, proposal queue, improve history |
-| `akm.lock` | Inter-process write lock | Yes — recreated automatically |
-| `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
-
-Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.
-
-### Cache Directory (`$XDG_CACHE_HOME/akm` or `~/.cache/akm/`)
-
-Everything in the cache is regenerable. It is safe to delete the entire cache directory; AKM will recreate what it needs on next use.
-
-| Path | Contents | Safe to delete? |
-|---|---|---|
-| `config-backups/config-<timestamp>.json` | Pre-save config snapshots (5 retained; owner-only permissions — file `0600`, dir `0700`, since 08-F4) | Yes |
-| `config-backups/config.latest.json` | Latest backup alias (owner-only `0600`) | Yes |
-| `registry/` | Downloaded registry tarballs (stash packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm add` or `akm update` |
-| `registry-index/` | Legacy per-URL JSON cache (v0.7 artifact) | Yes — fully replaced by `index.db` in 0.8.0 |
-| `semantic-status.json` | Semantic index build status marker | Yes |
-| `bin/` | Downloaded AKM binary cache (used by `akm upgrade`) | Yes |
-| `tasks/logs/` | Scheduled task log files | Yes — ephemeral logs |
-| `tasks/history/` | Legacy task history JSONL (v0.7 migration artifact) | Yes |
-
-Override: set `AKM_CACHE_DIR` or `XDG_CACHE_HOME`.
-
-### Stash Directory (`~/akm/` by default, or user-configured)
-
-| Path | Contents | Safe to delete? |
-|---|---|---|
-| `<stash>/` | All your asset files: agents, skills, commands, knowledge, workflows, memories, env files, secrets, wikis, lessons, facts | **No** — this is YOUR data |
-| `<stash>/.akm/` | Hidden AKM metadata (v0.7 proposals, legacy runs) | Caution — check for pending proposals first |
-
-Override: set `AKM_STASH_DIR` (or configure `stashDir` in `config.json`).
-
----
-
-## What Is Stored in `state.db`
-
-`state.db` holds three categories of non-regenerable data:
-
-### 1. Events Table
-
-An append-only log of every mutating action you perform with AKM. Events are stored locally for self-improvement (the improve loop uses them to surface usage patterns) and for inspection via `akm log`.
-
-**What is recorded:**
-- `event_type` — what action was taken (see full list below)
-- `ts` — ISO-8601 UTC timestamp
-- `ref` — the asset ref affected (e.g. `skill:code-review`), if applicable
-- `metadata` — structured payload specific to the event type (e.g. query text for `search`, score for `feedback`)
-
-**What is NOT recorded:**
-- File contents
-- LLM prompts or responses
-- API keys or secrets (config is not stored in events)
-- Personal information
-
-**Retention:** Events older than 90 days are purged automatically when `akm improve` runs its maintenance pass. Purge is controlled by `purgeOldEvents()` with a 90-day default.
-
-**Full event type list:**
-
-| Event type | When emitted | Key metadata fields |
-|---|---|---|
-| `add` | `akm add <source>` | `ref`, `provider` |
-| `remove` | `akm remove <source>` | `ref` |
-| `update` | `akm update [source]` | `ref` |
-| `remember` | `akm remember <text>` | `ref` |
-| `import` | `akm import <file>` | `ref` |
-| `save` | `akm sync` | `ref` |
-| `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
-| `search` | `akm search <query>` | `query`, `source`, `signal` |
-| `curate` | `akm curate <prompt>` | `query`, `source` |
-| `show` | `akm show <ref>` | `ref`, `type`, `name` |
-| `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
-| `promoted` | `akm proposal accept <id>` | `ref` |
-| `rejected` | `akm proposal reject <id>` | `ref` |
-| `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, profile |
-| `reflect_completed` | Reflect phase produced a proposal | `ref` |
-| `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
-| `propose_invoked` | `akm propose` | `ref` |
-| `distill_invoked` | `akm distill` | |
-| `improve_skipped` | Asset skipped by cooldown or budget | `ref`, `reason` |
-| `improve_completed` | `akm improve` run finished | run stats |
-| `improve_failed` | `akm improve` run errored | error |
-| `improve_lock_recovered` | Stale lock cleared at startup | |
-| `proposal_orphan_purge` | Stale proposals pruned | `checked`, `rejected` |
-| `proposal_creation_rejected` | `createProposal()` validation failed | `ref`, `reason`, `source` |
-| `proposal_expired` | Proposal expired | `ref` |
-| `events_purged` | Old events deleted by maintenance | `purgedCount`, `retentionDays` |
-| `workflow_started` | `akm workflow start <ref>` | `ref`, `runId` |
-| `workflow_step_completed` | `akm workflow next` | `ref`, `runId`, `stepId` |
-| `workflow_finished` | `akm workflow complete` | `ref`, `runId` |
-| `schema_repair_invoked` | `akm lint --repair` triggered schema repair | `ref` |
-| `archive_cleanup` | Archive cleanup during consolidation | |
-
-### 2. Proposals Table
-
-The proposal queue: pending, accepted, and rejected improvement proposals for your stash assets. Generated by `akm improve`, `akm propose`, and related proposal-producing flows.
-
-Contents:
-- Proposal UUID (primary key)
-- Target asset ref
-- Status (pending/accepted/rejected)
-- Source (which process generated it — e.g. `reflect`, `distill`)
-- Full proposal content (Markdown text)
-- Created/updated timestamps
-
-### 3. Task History Table
-
-A record of scheduled task runs (from `akm tasks`):
-- Task ID, status, start/end times
-- Log file path (the log content stays in `$CACHE/tasks/logs/`)
-
----
-
-## How to Inspect and Clear Local Data
-
-### Inspect events
-
-```sh
-# List recent events
-akm log list
-
-# Stream live events (tail)
-akm log tail
-
-# Filter by type
-akm log list --type search --limit 20
-
-# Filter by asset ref
-akm log list --ref skill:code-review
-```
-
-### Inspect proposals
-
-```sh
-# List pending proposals
-akm proposal list
-
-# Show a specific proposal
-akm proposal show <id>
-```
-
-### Clear specific data
-
-```sh
-# Delete the search index (safe — rebuilds with akm index --full)
-rm ~/.local/share/akm/index.db
-
-# Delete all cached registry downloads
-rm -rf ~/.cache/akm/registry/
-
-# Delete config backups
-rm -rf ~/.cache/akm/config-backups/
-
-# Delete the events log from state.db (non-reversible)
-# There is no akm CLI command to do this directly in 0.8.0.
-# Use SQLite directly:
-sqlite3 ~/.local/share/akm/state.db "DELETE FROM events;"
-
-# Delete all proposals
-sqlite3 ~/.local/share/akm/state.db "DELETE FROM proposals;"
-```
-
-### Start completely fresh (nuclear reset)
-
-```sh
-rm -f ~/.config/akm/config.json
-rm -rf ~/.local/share/akm/
-rm -rf ~/.cache/akm/
-# Your stash files in ~/akm/ are NOT touched by the above.
-```
-
----
-
-## Environment Variable Overrides
-
-You can redirect any AKM directory to a custom path:
-
-| Variable | Overrides |
-|---|---|
-| `AKM_CONFIG_DIR` | Config directory (`~/.config/akm/`) |
-| `AKM_DATA_DIR` | Data directory (`~/.local/share/akm/`) |
-| `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE`. Use `DELETE`/`TRUNCATE` on network filesystems (NFS/SMB) where WAL is impossible. When left at the `WAL` default, akm auto-detects a network FS for the data dir and falls back to `DELETE`. |
-| `AKM_STATE_DIR` | State directory (`~/.local/state/akm/`) |
-| `AKM_CACHE_DIR` | Cache directory (`~/.cache/akm/`) |
-| `AKM_STASH_DIR` | Default stash directory (`~/akm/`) |
-| `XDG_CONFIG_HOME` | XDG base — akm appends `/akm` |
-| `XDG_DATA_HOME` | XDG base — akm appends `/akm` |
-| `XDG_STATE_HOME` | XDG base — akm appends `/akm` |
-| `XDG_CACHE_HOME` | XDG base — akm appends `/akm` |