akm-cli 0.8.0-rc2 → 0.8.1

package/dist/commands/env.js

@@ -0,0 +1,213 @@
+// 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/.
+/**
+ * Environment asset type (`env`) — whole `.env` file storage.
+ *
+ * An `env` asset holds a GROUP of related CONFIGURATION for an app or service
+ * (URLs, feature flags, and any credentials it needs) in a single `.env` file,
+ * sourced/injected wholesale. Values may or may not be sensitive — akm protects
+ * them all the same. For a single sensitive value used on its own for
+ * authentication (a token, key, or cert), use the `secret` type instead.
+ *
+ * Unlike the deprecated `vault` type it replaces, akm does NOT manage individual
+ * KEY=value entries (no `set`/`unset`/quoting): you edit the `.env` file with
+ * your own editor, and akm loads it. The simplification removes the
+ * hand-rolled quoting/escaping surface; the safety guarantee moves to the READ
+ * path instead (see `buildShellExportScript` + `akm env export`).
+ *
+ * Invariant: env values must never be written to stdout, returned through the
+ * indexer, the `akm show` renderer, or any structured output channel. Key
+ * NAMES and start-of-line comments ARE surfaced by design (discoverability) —
+ * only values are secret. The supported value-load paths are:
+ *
+ *   - `akm env run <ref> -- <command>` — values injected into the child
+ *     process env (never via a shell), see `injectIntoEnv` / `loadEnv`. This is
+ *     the primary path and the only one safe for AI agents (no values ever
+ *     reach stdout). For an interactive shell, `akm env run <ref> -- $SHELL`.
+ *   - `akm env export <ref> --out <file>` — write parse-then-reserialized safe
+ *     `export KEY='value'` lines to a file (mode 0600) for `source`-ing. Values
+ *     are re-emitted single-quoted so a raw `.env` containing `X=$(cmd)` cannot
+ *     execute on load. `export` never prints values to stdout (would leak into
+ *     an agent's context); `path` prints only the file path.
+ *
+ * Value parsing is delegated to the `dotenv` package — we deliberately do not
+ * implement our own quoting/escaping rules for security-sensitive content.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+import { writeFileAtomic } from "../core/common";
+/** Matches a KEY=value assignment line, capturing only the key. */
+const ASSIGN_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/** Scan lines and return KEY names in file order, without duplicates. */
+function scanKeys(text) {
+    const keys = [];
+    const seen = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(ASSIGN_RE);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+/**
+ * Scan lines and return start-of-line `#` comments (with the leading `#` and
+ * any leading whitespace stripped). Inline/trailing `#` after an assignment is
+ * never extracted.
+ */
+function scanComments(text) {
+    const comments = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("#")) {
+            comments.push(trimmed.slice(1).trimStart());
+        }
+    }
+    return comments;
+}
+/**
+ * Read and return ONLY non-secret metadata (keys + start-of-line comments).
+ *
+ * The function reads the whole file into memory (same as any dotenv parser)
+ * but deliberately does not parse values — the LHS-only regex scanners above
+ * ensure no value content is retained or returned. The guarantee is that
+ * values never leave this function.
+ */
+export function listKeys(envPath) {
+    if (!fs.existsSync(envPath))
+        return { keys: [], comments: [] };
+    const text = fs.readFileSync(envPath, "utf8");
+    return { keys: scanKeys(text), comments: scanComments(text) };
+}
+/**
+ * Return structured `entries` pairing each key with the nearest preceding
+ * comment line (if any). This is an easier-to-consume shape than the parallel
+ * `keys[]` + `comments[]` of `listKeys` (QA #35).
+ *
+ * Values are never included — the same privacy guarantee as `listKeys`.
+ */
+export function listEntries(envPath) {
+    if (!fs.existsSync(envPath))
+        return [];
+    const text = fs.readFileSync(envPath, "utf8");
+    const lines = text.split(/\r?\n/);
+    const seen = new Set();
+    const entries = [];
+    let pendingComment;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("#")) {
+            // Capture the most recent comment before a key
+            pendingComment = trimmed.slice(1).trimStart() || undefined;
+            continue;
+        }
+        const m = line.match(ASSIGN_RE);
+        if (m) {
+            const key = m[1];
+            if (!seen.has(key)) {
+                seen.add(key);
+                const entry = { key };
+                if (pendingComment)
+                    entry.comment = pendingComment;
+                entries.push(entry);
+            }
+            pendingComment = undefined;
+        }
+        else {
+            // Any non-comment, non-assignment line (including blank lines)
+            // breaks "nearest preceding comment line" association.
+            pendingComment = undefined;
+        }
+    }
+    return entries;
+}
+/**
+ * Read all KEY=value pairs from an env file. Intended for programmatic callers
+ * that need to inject values into a process environment. Callers MUST NOT write
+ * the returned values to stdout or any logged output.
+ *
+ * Value parsing (quoting, escapes, multi-line, etc.) is delegated to dotenv.
+ */
+export function loadEnv(envPath) {
+    if (!fs.existsSync(envPath))
+        return {};
+    const buf = fs.readFileSync(envPath);
+    return dotenv.parse(buf);
+}
+/**
+ * Load an env file and assign its values into `target` (defaults to
+ * `process.env`). Returns the list of keys that were set so the caller can
+ * log/observe without touching values.
+ *
+ * Existing keys in `target` are overwritten — callers who want to preserve
+ * pre-existing environment variables should filter before calling.
+ */
+export function injectIntoEnv(envPath, target = process.env) {
+    const env = loadEnv(envPath);
+    for (const [key, value] of Object.entries(env)) {
+        target[key] = value;
+    }
+    return Object.keys(env);
+}
+/**
+ * Serialise an env file's values as a POSIX shell script of `export KEY='value'`
+ * lines, with single-quote escaping (`'\''`). Every line is an assignment of a
+ * literal string — there is no expansion, command substitution, or
+ * non-assignment content, so `eval`-ing the output is safe regardless of what
+ * the source file contains.
+ *
+ * This is the trust boundary for shell loading: a raw `.env` may contain
+ * `X=$(rm -rf ~)`, which would execute if `source`d directly, but dotenv parses
+ * it to the literal string `$(rm -rf ~)` and we re-emit it single-quoted. This
+ * backs `akm env export <ref> --out <file>` (file-only; never printed to stdout).
+ */
+export function buildShellExportScript(envPath) {
+    const env = loadEnv(envPath);
+    const lines = [];
+    for (const [key, value] of Object.entries(env)) {
+        // Defence in depth: dotenv already validates key shape, but reject any
+        // key we wouldn't be able to export safely.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        const escaped = value.replace(/'/g, "'\\''");
+        lines.push(`export ${key}='${escaped}'`);
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+/** Create an empty env file (does nothing if it already exists). */
+export function createEnv(envPath) {
+    ensureParentDir(envPath);
+    if (fs.existsSync(envPath))
+        return;
+    writeFileAtomic(envPath, "", 0o600);
+}
+/**
+ * Write (create or overwrite) an env file with the given text content,
+ * atomically at mode 0600. Used to ingest an existing `.env` file
+ * (`env create --from-file` / `--from-stdin`).
+ */
+export function writeEnv(envPath, content) {
+    ensureParentDir(envPath);
+    writeFileAtomic(envPath, content, 0o600);
+}
+/** Remove an env file (and its `.sensitive` marker, if present). Returns true if it existed. */
+export function removeEnv(envPath) {
+    if (!fs.existsSync(envPath))
+        return false;
+    fs.rmSync(envPath);
+    const marker = `${envPath}.sensitive`;
+    if (fs.existsSync(marker))
+        fs.rmSync(marker);
+    return true;
+}
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}

package/dist/commands/eval-cases.js

@@ -1,3 +1,6 @@
+// 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 { writeFileAtomic } from "../core/common";

package/dist/commands/events.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * `akm events list` and `akm events tail` (#204).
  *

package/dist/commands/extract-cli.js

@@ -0,0 +1,127 @@
+// 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/.
+/**
+ * CLI surface for `akm extract`.
+ *
+ * Examples:
+ *   akm extract --type claude-code --session-id <id>
+ *   akm extract --type claude-code --since 24h
+ *   akm extract --type opencode --since 7d --dry-run
+ *   akm extract --auto                 # iterate all available harnesses
+ *   akm extract --type claude-code --location /custom/path --session-id <id>
+ *
+ * Output is the AkmExtractResult JSON envelope (or an aggregated one when
+ * `--auto` runs multiple harnesses).
+ */
+import { defineCommand } from "citty";
+import { output, runWithJsonErrors } from "../cli/shared";
+import { UsageError } from "../core/errors";
+import { getAvailableHarnesses } from "../integrations/session-logs";
+import { akmExtract } from "./extract";
+export const extractCommand = defineCommand({
+    meta: {
+        name: "extract",
+        description: "Extract durable insights from native session files (claude-code, opencode) and queue them as proposals. Replaces the legacy session-checkpoint hook.",
+    },
+    args: {
+        type: {
+            type: "string",
+            description: "Harness name (claude-code, opencode). Required unless --auto.",
+        },
+        "session-id": {
+            type: "string",
+            description: "Process only this session ID. When absent, discover sessions via --since.",
+        },
+        location: {
+            type: "string",
+            description: "Override the harness's default session-discovery location.",
+        },
+        since: {
+            type: "string",
+            description: "Discovery cutoff. ISO timestamp or duration (24h, 7d, 30m). Default 24h.",
+        },
+        auto: {
+            type: "boolean",
+            description: "Iterate every available harness with default --since. Mutually exclusive with --type.",
+            default: false,
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "Show candidates without queuing proposals.",
+            default: false,
+        },
+        force: {
+            type: "boolean",
+            description: "Re-process sessions even if they were already extracted and have no new events. Default: skip already-seen sessions.",
+            default: false,
+        },
+        "timeout-ms": {
+            type: "string",
+            description: "Per-session LLM timeout in ms (default 60000).",
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const type = typeof args.type === "string" ? args.type.trim() : "";
+            const sessionId = typeof args["session-id"] === "string" ? args["session-id"].trim() : "";
+            const location = typeof args.location === "string" ? args.location.trim() : "";
+            const since = typeof args.since === "string" ? args.since.trim() : "";
+            const auto = args.auto === true;
+            const dryRun = args["dry-run"] === true;
+            const force = args.force === true;
+            const timeoutMs = typeof args["timeout-ms"] === "string" && args["timeout-ms"] !== ""
+                ? Number.parseInt(args["timeout-ms"], 10)
+                : undefined;
+            if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+                throw new UsageError(`--timeout-ms must be a positive integer (got "${args["timeout-ms"]}").`, "INVALID_FLAG_VALUE");
+            }
+            if (auto && type) {
+                throw new UsageError("--auto and --type are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
+            }
+            if (!auto && !type) {
+                throw new UsageError("--type is required (or pass --auto to try every available harness).", "MISSING_REQUIRED_ARGUMENT");
+            }
+            const commonOptions = {
+                ...(sessionId ? { sessionId } : {}),
+                ...(location ? { location } : {}),
+                ...(since ? { since } : {}),
+                dryRun,
+                force,
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            };
+            if (auto) {
+                const harnesses = getAvailableHarnesses();
+                if (harnesses.length === 0) {
+                    output("extract", {
+                        schemaVersion: 1,
+                        ok: false,
+                        shape: "extract-auto-result",
+                        warnings: ["no available harnesses found on this machine"],
+                        results: [],
+                    });
+                    return;
+                }
+                const results = [];
+                for (const h of harnesses) {
+                    const result = await akmExtract({ type: h.name, ...commonOptions });
+                    results.push(result);
+                }
+                const ok = results.every((r) => r.ok);
+                const totalProposals = results.reduce((sum, r) => sum + r.proposals.length, 0);
+                output("extract", {
+                    schemaVersion: 1,
+                    ok,
+                    shape: "extract-auto-result",
+                    dryRun,
+                    harnessesProcessed: results.length,
+                    totalProposals,
+                    results,
+                });
+                return;
+            }
+            const result = await akmExtract({ type, ...commonOptions });
+            output("extract", result);
+        });
+    },
+});

package/dist/commands/extract-prompt.js

@@ -0,0 +1,217 @@
+// 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/.
+/**
+ * Prompt + schema for `akm extract <session>`.
+ *
+ * Mirrors the REFLECT_JSON_SCHEMA pattern: a strict JSON Schema describing
+ * the LLM output, plus a {@link buildExtractPrompt} helper that interpolates
+ * session data into the markdown template loaded from
+ * `src/assets/prompts/extract-session.md`.
+ *
+ * The schema is intentionally strict — providers with `supportsJsonSchema:
+ * true` enforce shape upstream, so the parser only has to handle the
+ * happy path. `additionalProperties: false` means any hallucinated keys
+ * the model emits get dropped before we parse.
+ */
+import promptTemplate from "../assets/prompts/extract-session.md" with { type: "text" };
+/**
+ * JSON Schema for the structured extract output. Passed to `chatCompletion`
+ * when the configured LLM connection has `supportsJsonSchema: true`.
+ *
+ * Shape:
+ *   {
+ *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence}, ...],
+ *     "rationale_if_empty"?: string
+ *   }
+ *
+ * `additionalProperties: false` at each level so any hallucinated keys are
+ * dropped before parsing.
+ */
+export const EXTRACT_JSON_SCHEMA = {
+    type: "object",
+    required: ["candidates"],
+    additionalProperties: false,
+    properties: {
+        candidates: {
+            type: "array",
+            description: "Zero or more durable-insight candidates extracted from the session.",
+            items: {
+                type: "object",
+                required: ["type", "name", "description", "body", "confidence", "evidence"],
+                additionalProperties: false,
+                properties: {
+                    type: {
+                        type: "string",
+                        enum: ["memory", "lesson", "knowledge"],
+                        description: "Asset type the candidate would land as.",
+                    },
+                    name: {
+                        type: "string",
+                        description: "Kebab-case slug for the new asset.",
+                        pattern: "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+                    },
+                    description: {
+                        type: "string",
+                        minLength: 20,
+                        maxLength: 400,
+                        description: "One-sentence summary of the candidate.",
+                    },
+                    when_to_use: {
+                        type: "string",
+                        minLength: 15,
+                        maxLength: 400,
+                        description: "Trigger sentence for the candidate; REQUIRED when type=lesson.",
+                    },
+                    body: {
+                        type: "string",
+                        minLength: 50,
+                        description: "Markdown body of the candidate asset.",
+                    },
+                    confidence: {
+                        type: "number",
+                        minimum: 0,
+                        maximum: 1,
+                        description: "Self-rated confidence in [0, 1] that this candidate is a real durable insight.",
+                    },
+                    evidence: {
+                        type: "string",
+                        minLength: 5,
+                        description: "One-line pointer to the moment in the session that supports this candidate.",
+                    },
+                },
+            },
+        },
+        rationale_if_empty: {
+            type: "string",
+            minLength: 10,
+            description: "Required when `candidates` is empty — explains why nothing rose to durable-insight level.",
+        },
+    },
+};
+/**
+ * Format inline refs as a bullet list for the "Already preserved" section.
+ * If empty, returns a sentinel string so the LLM knows the agent saved
+ * nothing inline.
+ */
+function formatAlreadyPreserved(inlineRefs) {
+    if (inlineRefs.length === 0) {
+        return "(none — the agent did not call `akm remember` or `akm feedback` during this session)";
+    }
+    return inlineRefs
+        .map((ref) => {
+        const prefix = ref.kind === "remember" ? "- remember:" : `- feedback ${ref.ref ?? "<ref>"}:`;
+        const body = ref.text.trim().slice(0, 200);
+        return `${prefix} ${body}${ref.text.length > 200 ? "…" : ""}`;
+    })
+        .join("\n");
+}
+/**
+ * Format pre-filtered events as a transcript snippet. Each event becomes:
+ *   [<role> @ <iso>] <text>
+ * Events are already truncated/cleaned by the pre-filter; this is purely
+ * a render step.
+ */
+function formatTranscript(events) {
+    if (events.length === 0)
+        return "(empty — pre-filter removed all events as noise)";
+    return events
+        .map((e) => {
+        const tsLabel = e.ts ? new Date(e.ts).toISOString() : "unknown-ts";
+        const roleLabel = e.role ?? "unknown";
+        return `[${roleLabel} @ ${tsLabel}] ${e.text}`;
+    })
+        .join("\n\n");
+}
+/**
+ * Build the user-prompt body for the extract LLM call by interpolating
+ * session metadata, already-preserved refs, and the filtered transcript
+ * into the template.
+ */
+export function buildExtractPrompt(input) {
+    const ref = input.data.ref;
+    const startedAt = ref.startedAt ? new Date(ref.startedAt).toISOString() : "unknown";
+    const endedAt = ref.endedAt ? new Date(ref.endedAt).toISOString() : "unknown";
+    return promptTemplate
+        .replace("{{HARNESS}}", ref.harness)
+        .replace("{{TITLE}}", ref.title ?? "(no title)")
+        .replace("{{STARTED_AT}}", startedAt)
+        .replace("{{ENDED_AT}}", endedAt)
+        .replace("{{PROJECT_HINT}}", ref.projectHint ?? "(no project hint)")
+        .replace("{{ALREADY_PRESERVED}}", formatAlreadyPreserved(input.inlineRefs))
+        .replace("{{TRANSCRIPT}}", formatTranscript(input.events));
+}
+/**
+ * Parse the LLM's JSON response into a structured {@link ExtractPayload}.
+ * Defensive — drops candidates that violate the shape rather than failing
+ * the whole call. Returns the empty-candidates payload when nothing parses.
+ */
+export function parseExtractPayload(stdout) {
+    if (!stdout || stdout.trim().length === 0) {
+        return { candidates: [], rationale_if_empty: "LLM returned empty response" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        // Tolerate prose preamble/postamble by extracting the first balanced
+        // top-level JSON object.
+        const start = stdout.indexOf("{");
+        const end = stdout.lastIndexOf("}");
+        if (start === -1 || end <= start) {
+            return { candidates: [], rationale_if_empty: `LLM response was not parseable JSON` };
+        }
+        try {
+            parsed = JSON.parse(stdout.slice(start, end + 1));
+        }
+        catch {
+            return { candidates: [], rationale_if_empty: `LLM response was not parseable JSON` };
+        }
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return { candidates: [], rationale_if_empty: "LLM response was not an object" };
+    }
+    const obj = parsed;
+    const rawCandidates = Array.isArray(obj.candidates) ? obj.candidates : [];
+    const candidates = [];
+    for (const raw of rawCandidates) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const c = raw;
+        const type = c.type;
+        if (type !== "memory" && type !== "lesson" && type !== "knowledge")
+            continue;
+        if (typeof c.name !== "string" || !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(c.name))
+            continue;
+        if (typeof c.description !== "string" || c.description.trim().length < 20)
+            continue;
+        if (typeof c.body !== "string" || c.body.trim().length < 50)
+            continue;
+        if (typeof c.confidence !== "number" || !Number.isFinite(c.confidence))
+            continue;
+        if (typeof c.evidence !== "string" || c.evidence.trim().length < 5)
+            continue;
+        if (type === "lesson") {
+            if (typeof c.when_to_use !== "string" || c.when_to_use.trim().length < 15)
+                continue;
+        }
+        const confidence = Math.max(0, Math.min(1, c.confidence));
+        const candidate = {
+            type,
+            name: c.name,
+            description: c.description.trim(),
+            body: c.body,
+            confidence,
+            evidence: c.evidence.trim(),
+        };
+        if (typeof c.when_to_use === "string")
+            candidate.when_to_use = c.when_to_use.trim();
+        candidates.push(candidate);
+    }
+    const result = { candidates };
+    if (typeof obj.rationale_if_empty === "string") {
+        result.rationale_if_empty = obj.rationale_if_empty.trim();
+    }
+    return result;
+}