akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/indexer/usage/unmigrated-vaults-guard.js

@@ -1,95 +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/.
-/**
- * One-time, read-only guard for un-migrated `vaults/` directories (0.9.0).
- *
- * Background: 0.8.0 introduced the `env` asset type and a `vaults/` → `env/`
- * copy migration (run by `akm-migrate-storage`). 0.9.0 removed the `vault`
- * asset type entirely, and the indexer now unconditionally SKIPS `vaults/`
- * (the `akm` adapter's `recognize` abstains on it — see `akmStashAbstains` in
- * `core/adapter/adapters/akm-adapter.ts`). A user who upgrades straight
- * to 0.9.0 without ever running the storage migration therefore has the `.env`
- * data in their `vaults/` directory silently dropped from the index — it was
- * never copied to `env/`, and `vaults/` is no longer scanned.
- *
- * This guard detects exactly that state on a stash and emits ONE clear warning
- * pointing at `akm-migrate-storage`. It is:
- *   - Non-destructive: it never reads `.env` contents, never writes, never
- *     deletes, and never moves anything. It only stats directory entries.
- *   - Idempotent: the warning is emitted at most once per process per stash
- *     directory (deduped in-memory).
- *
- * It deliberately does NOT auto-run the copy: filesystem mutation + chmod of
- * secret material stays in the dedicated `akm-migrate-storage` bin, behind the
- * user's explicit invocation, never as a side effect of a normal `akm` command.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { warn } from "../../core/warn.js";
-/**
- * Marker filename the `vaults/` → `env/` migration drops inside `vaults/` after
- * a successful copy. Single source of truth shared with
- * `scripts/migrate-storage.ts` (which writes it) and this guard (which reads
- * it). Its presence means the data already lives under `env/` (or was a no-op
- * fresh install).
- */
-export const MIGRATED_MARKER = ".migrated";
-/** Stashes already warned about in this process — keyed by absolute stash dir. */
-const warnedStashDirs = new Set();
-/** True when `dir` contains at least one `*.env` / `.env` file (recursively). */
-function hasEnvFilesRecursive(dir) {
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return false;
-    }
-    for (const entry of entries) {
-        const full = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (hasEnvFilesRecursive(full))
-                return true;
-        }
-        else if (entry.name === ".env" || entry.name.endsWith(".env")) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Warn (once) when `<stashDir>/vaults/` holds `.env` data that was never
- * migrated to `env/`. No-op when there is no `vaults/` dir, when the
- * `vaults/.migrated` marker is present, or when `vaults/` has no `.env` files.
- *
- * @returns `true` when a warning was emitted, `false` otherwise. The return is
- *   primarily for tests; callers can ignore it.
- */
-export function warnOnUnmigratedVaults(stashDir) {
-    const resolved = path.resolve(stashDir);
-    if (warnedStashDirs.has(resolved))
-        return false;
-    const vaultsDir = path.join(resolved, "vaults");
-    if (!fs.existsSync(vaultsDir))
-        return false;
-    // The migration writes this marker after a successful copy. Its presence
-    // means the data already lives under env/ (or was a no-op fresh install).
-    if (fs.existsSync(path.join(vaultsDir, MIGRATED_MARKER)))
-        return false;
-    if (!hasEnvFilesRecursive(vaultsDir))
-        return false;
-    // Mark before emitting so a throw in `warn` can't cause a re-warn loop.
-    warnedStashDirs.add(resolved);
-    warn(`[akm] WARNING: found un-migrated secrets in ${vaultsDir}.\n` +
-        `  The 'vault' asset type was removed in 0.9.0 and 'vaults/' is no longer indexed,\n` +
-        `  so this data will NOT appear under 'env:' until you migrate it. Run:\n` +
-        `      akm-migrate-storage --yes\n` +
-        `  This copies 'vaults/' -> 'env/' (non-destructive — your 'vaults/' dir is left intact).\n` +
-        `  See docs/migration/v0.8-to-v0.9.md.`);
-    return true;
-}
-/** Test-only: clear the per-process dedup set. */
-export function _resetUnmigratedVaultsGuardForTests() {
-    warnedStashDirs.clear();
-}

package/dist/llm/memory-infer-impl.js

@@ -1,138 +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/.
-/**
- * LLM helper for the `akm index` memory-inference pass (#201).
- *
- * Compresses a single memory body into one higher-signal derived memory. The
- * pass itself (in `src/indexer/memory-inference.ts`) is responsible for
- * deciding which memories are pending, persisting the derived memory with the
- * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and marking
- * the parent as processed for idempotency.
- *
- * This module is intentionally tiny and stateless so tests can stub it via
- * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
- *
- * Locked v1 contract (#208): the LLM connection always comes from the
- * selected named LLM engine. Callers obtain
- * the connection via `resolveIndexPassLLM("memory", config)` and pass it
- * straight through.
- */
-import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" with { type: "text" };
-import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
-import { toErrorMessage } from "../core/common.js";
-import { warn } from "../core/warn.js";
-import { parseEmbeddedJsonResponse } from "./client.js";
-import { callStructured } from "./structured-call.js";
-/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
-const MAX_BODY_CHARS = 4000;
-const SYSTEM_PROMPT = memoryInferSystemPrompt;
-const USER_PROMPT_PREFIX = memoryInferUserPrompt;
-/**
- * Strict JSON Schema for the derived-memory payload. Sent to providers that
- * opt in via `LlmConnectionConfig.supportsJsonSchema = true`; the client
- * silently drops the schema for providers that don't.
- *
- * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
- * the memory-inference path. Mirrors the validation gate below
- * (title/description/content + non-empty tags/searchHints) so a
- * schema-compliant response is guaranteed to pass the downstream check
- * — no more "incomplete derived memory payload from LLM; skipping memory"
- * for shape-only failures.
- */
-const DERIVED_MEMORY_JSON_SCHEMA = {
-    type: "object",
-    properties: {
-        title: { type: "string", minLength: 1 },
-        description: { type: "string", minLength: 1 },
-        content: { type: "string", minLength: 1 },
-        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
-        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
-    },
-    required: ["title", "description", "content", "tags", "searchHints"],
-    additionalProperties: false,
-};
-/**
- * Compress a single memory body into one derived memory via the configured LLM.
- *
- * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
- * Errors are logged via `warn()` but never thrown — a failed split for one memory
- * must not abort the rest of the index pass.
- *
- * Routes through `callStructured({ feature: "memory_inference", ... })` so the
- * feature gate, error classification, and onFallback hook are honoured uniformly
- * (Fix C5).
- */
-export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
-    const trimmedBody = body.trim();
-    if (!trimmedBody)
-        return undefined;
-    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
-    // Memory-inference is ALWAYS gated: no `akmConfig` ⇒ gate closed (no chat,
-    // `disabled` fallback), never the seam's ungated/propagate path (which is for
-    // direct callers like `enhanceMetadata`). This is the gate-closed branch
-    // `tryLlmFeature(_, undefined, _)` took before the migration.
-    if (!akmConfig) {
-        onFallback?.({ feature: "memory_inference", reason: "disabled" });
-        return undefined;
-    }
-    return callStructured({
-        feature: "memory_inference",
-        akmConfig,
-        config: llmConfig,
-        messages: [
-            { role: "system", content: SYSTEM_PROMPT },
-            { role: "user", content: userPrompt },
-        ],
-        request: {
-            temperature: 0.1,
-            timeoutMs: llmConfig.timeoutMs,
-            signal,
-            responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
-            onRetryAttempt,
-        },
-        parse: (raw) => {
-            if (!raw)
-                return undefined;
-            const parsed = parseEmbeddedJsonResponse(raw);
-            if (!parsed) {
-                warn("memory inference: invalid JSON response from LLM; skipping memory.");
-                return undefined;
-            }
-            const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
-            const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
-            const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
-            const tags = Array.isArray(parsed.tags)
-                ? parsed.tags
-                    .filter((t) => typeof t === "string")
-                    .map((t) => t.trim())
-                    .filter(Boolean)
-                    .slice(0, 8)
-                : [];
-            const searchHints = Array.isArray(parsed.searchHints)
-                ? parsed.searchHints
-                    .filter((h) => typeof h === "string")
-                    .map((h) => h.trim())
-                    .filter(Boolean)
-                    .slice(0, 6)
-                : [];
-            if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
-                warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
-                return undefined;
-            }
-            return { title, description, tags, searchHints, content };
-        },
-        onError: (cls, err) => {
-            if (cls === "html") {
-                if (telemetry)
-                    telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
-                warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
-                return undefined;
-            }
-            warn(`memory inference failed: ${toErrorMessage(err)}`);
-            return undefined;
-        },
-        fallback: undefined,
-        onFallback,
-    });
-}

package/dist/migrate/legacy/config-source-migration.js

@@ -1,223 +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/.
-/**
- * @removeIn next-minor — Chunk-8 config-shape migration (WI-8.4).
- *
- * Translates the pre-cutover source configuration
- * (`stashDir` / `sources[]` / `installed[]`) into the 0.9.0 `bundles` +
- * `defaultBundle` shape (spec §10.1). Runs as a pure pre-validation transform in
- * the migrator's config-applied phase (`cli/config-migrate.ts`): the old keys
- * are removed and the emitted `bundles` map is keyed by exactly what
- * `deriveInstallations` derives for each source at runtime (D-R5 no-identity
- * shift), because BOTH sides call the ONE shared {@link deriveBundleId} helper.
- *
- * `defaultBundle` is the primary stash's derived id — the source marked
- * `primary: true`, else the synthetic entry built from top-level `stashDir`.
- *
- * Ordering mirrors the transitional runtime resolvers (primary first, then
- * `sources[]` in declared order, then `installed[]`) so the emitted map's
- * insertion order reproduces the runtime installation-priority order after the
- * migration.
- *
- * WI-8.5 desired/resolved split (spec §10.2): an `installed[]` entry is emitted
- * as its DESIRED source descriptor — a git/npm bundle carrying the re-installable
- * LOCATOR (`{ git: ref }` / `{ npm: ref }`), NOT the materialized cache root. The
- * resolved root lives exclusively in the lock (`localRoot`), emitted by
- * {@link migratedLockEntries} keyed by the same derived bundle id, from which the
- * runtime ({@link import("../../indexer/search/search-source.js").resolveSourceEntries})
- * resolves the git/npm bundle's content dir. A local/filesystem install still
- * emits `{ path: stashRoot }` (a real path, no cache to re-materialize). The
- * original registry id is preserved in the entry's `registryId` locator so
- * nothing is lost.
- */
-import os from "node:os";
-import path from "node:path";
-import { installedSourceDescriptor } from "../../core/config/config-sources.js";
-import { deriveBundleId } from "../../indexer/installations.js";
-/** The pre-cutover source keys this transform consumes and removes. */
-const OLD_SOURCE_KEYS = ["stashDir", "sources", "installed"];
-/** True when a raw config object carries any pre-cutover source key. */
-export function hasOldSourceShape(raw) {
-    return OLD_SOURCE_KEYS.some((k) => k in raw && raw[k] !== undefined);
-}
-/** Expand a leading `~` against the home directory (config paths may use it). */
-function expandTilde(p) {
-    if (p === "~")
-        return os.homedir();
-    if (p.startsWith("~/") || p.startsWith("~\\"))
-        return path.join(os.homedir(), p.slice(2));
-    return p;
-}
-function readString(value) {
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-/** Build the 0.9.0 source descriptor for one pre-cutover `sources[]` entry. */
-function sourceEntryDescriptor(entry) {
-    const type = readString(entry.type) ?? "filesystem";
-    const entryPath = readString(entry.path);
-    const url = readString(entry.url);
-    const options = entry.options ?? undefined;
-    const maxPages = typeof options?.maxPages === "number" ? options.maxPages : undefined;
-    switch (type) {
-        case "filesystem":
-            return entryPath ? { path: entryPath } : undefined;
-        case "git":
-            return url ? { git: url } : undefined;
-        case "website":
-            return url ? { website: { url, ...(maxPages !== undefined ? { maxPages } : {}) } } : undefined;
-        case "npm":
-            // Today's npm source carries the package spec in `path` (parseSourceSpec).
-            return entryPath ? { npm: entryPath } : undefined;
-        default:
-            return entryPath ? { path: entryPath } : undefined;
-    }
-}
-/**
- * Extract the ordered pre-cutover source list from a raw config object, mirroring
- * the runtime resolution order: primary first, then `sources[]`, then
- * `installed[]`.
- */
-export function oldConfigMigratableSources(raw) {
-    const out = [];
-    const sources = Array.isArray(raw.sources) ? raw.sources : [];
-    const installed = Array.isArray(raw.installed) ? raw.installed : [];
-    const stashDir = readString(raw.stashDir);
-    // Primary: an explicit `primary: true` source wins; otherwise the top-level
-    // `stashDir` (a synthetic writable filesystem primary).
-    const primaryEntry = sources.find((entry) => entry.primary === true);
-    if (primaryEntry) {
-        const descriptor = sourceEntryDescriptor(primaryEntry);
-        const p = readString(primaryEntry.path);
-        if (descriptor) {
-            out.push({
-                derivationPath: p ? path.resolve(expandTilde(p)) : (readString(primaryEntry.url) ?? ""),
-                registryId: readString(primaryEntry.name),
-                writable: primaryEntry.writable === true,
-                primary: true,
-                descriptor,
-            });
-        }
-    }
-    else if (stashDir) {
-        out.push({
-            derivationPath: path.resolve(expandTilde(stashDir)),
-            writable: true,
-            primary: true,
-            descriptor: { path: stashDir },
-        });
-    }
-    for (const entry of sources) {
-        if (entry === primaryEntry)
-            continue;
-        const descriptor = sourceEntryDescriptor(entry);
-        if (!descriptor)
-            continue;
-        const p = readString(entry.path);
-        out.push({
-            derivationPath: p ? path.resolve(expandTilde(p)) : (readString(entry.url) ?? ""),
-            registryId: readString(entry.name),
-            writable: entry.writable === true,
-            descriptor,
-        });
-    }
-    for (const entry of installed) {
-        const stashRoot = readString(entry.stashRoot);
-        if (!stashRoot)
-            continue;
-        const source = readString(entry.source);
-        const ref = readString(entry.ref);
-        // WI-8.5 desired/resolved split: emit the DESIRED source descriptor (git/npm
-        // locator), NOT the materialized cache root. The resolved root belongs in the
-        // lock (`localRoot`), keyed by the derived bundle id — see {@link migratedLockEntries}.
-        const descriptor = source ? installedSourceDescriptor(source, ref, stashRoot) : { path: stashRoot };
-        const resolvedRoot = path.resolve(expandTilde(stashRoot));
-        // A git/npm descriptor carries a locator, so the runtime resolves its content
-        // dir from the lock's localRoot; record that resolved state for the lock.
-        const needsLock = ("git" in descriptor || "npm" in descriptor) && !!source && !!ref;
-        out.push({
-            derivationPath: resolvedRoot,
-            registryId: readString(entry.id),
-            writable: entry.writable === true,
-            descriptor,
-            ...(needsLock ? { lock: { source: source, ref: ref, localRoot: resolvedRoot } } : {}),
-        });
-    }
-    return out;
-}
-/**
- * Derive the §10.2 lock entries the config-shape migration produces for
- * `installed[]` entries whose desired descriptor is a git/npm LOCATOR. Each
- * entry is keyed by the SAME derived bundle id as {@link migrateConfigSourcesToBundles}
- * (both share {@link oldConfigMigratableSources} + {@link deriveBundleId} over
- * the same ordered list), so the runtime resolves the git/npm bundle's content
- * dir from `localRoot`. Filesystem/local bundles resolve directly from their
- * config `path` and get no lock entry. Returns `[]` for an already-migrated or
- * old-shape-free config (idempotent, side-effect free).
- */
-export function migratedLockEntries(raw) {
-    if ("bundles" in raw)
-        return [];
-    if (!hasOldSourceShape(raw))
-        return [];
-    const usedIds = new Set();
-    const entries = [];
-    for (const src of oldConfigMigratableSources(raw)) {
-        const id = deriveBundleId(src.registryId, src.derivationPath, usedIds);
-        if (src.lock) {
-            entries.push({ id, source: src.lock.source, ref: src.lock.ref, localRoot: src.lock.localRoot });
-        }
-    }
-    return entries;
-}
-/**
- * The SearchSource[] view of the pre-cutover config — the exact input a "direct
- * `deriveInstallations` run over the old source list" consumes for the D-R5
- * no-identity-shift proof.
- */
-export function oldConfigToSearchSources(raw) {
-    return oldConfigMigratableSources(raw).map((src) => ({
-        path: src.derivationPath,
-        ...(src.registryId ? { registryId: src.registryId } : {}),
-        ...(src.writable ? { writable: true } : {}),
-    }));
-}
-/**
- * Translate the pre-cutover source shape into `bundles` + `defaultBundle`,
- * removing `stashDir`/`sources`/`installed`. Idempotent: a config with no old
- * source keys (already migrated, or none configured) is returned unchanged, so
- * the transform is safe to run over any migration target.
- */
-export function migrateConfigSourcesToBundles(raw) {
-    // Already migrated (or half-migrated — the schema rejects that): leave as-is.
-    if ("bundles" in raw)
-        return raw;
-    if (!hasOldSourceShape(raw))
-        return raw;
-    const migratable = oldConfigMigratableSources(raw);
-    const usedIds = new Set();
-    const bundles = {};
-    let defaultBundle;
-    for (const src of migratable) {
-        // The ONE shared derivation, so the emitted key equals the runtime
-        // installation id by construction (D-R5).
-        const id = deriveBundleId(src.registryId, src.derivationPath, usedIds);
-        const entry = { ...src.descriptor };
-        if (src.writable)
-            entry.writable = true;
-        // Preserve the original registry id when the slug-legal key differs from it
-        // (a non-slug-legal id like `github:owner/repo`), so the locator is not lost.
-        if (src.registryId && src.registryId !== id)
-            entry.registryId = src.registryId;
-        bundles[id] = entry;
-        if (src.primary)
-            defaultBundle = id;
-    }
-    const out = { ...raw };
-    for (const key of OLD_SOURCE_KEYS)
-        delete out[key];
-    out.bundles = bundles;
-    if (defaultBundle !== undefined)
-        out.defaultBundle = defaultBundle;
-    return out;
-}