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

package/dist/indexer/search/search-source.js

@@ -3,100 +3,102 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "../../core/common.js";
-import { getSources, loadConfig } from "../../core/config/config.js";
+import { isSourceWriteActivated } from "../../core/activation-policy.js";
+import { isWithin, resolveStashDir } from "../../core/common.js";
+import { bundleComponentConfig, bundlesToSourceEntries, getSources, loadConfig } from "../../core/config/config.js";
+import { resolveGitContentRoot, resolveWritable } from "../../core/write-source.js";
+import { lockContentRootFor } from "../../integrations/lockfile.js";
 import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
 import "../../sources/providers/index.js";
 import { warn } from "../../core/warn.js";
-// Legacy "context-hub" / "github" type aliases are normalized to "git" at
-// config-load time (see src/config.ts), so this set only contains the canonical
-// type.
-const GIT_STASH_TYPES = new Set(["git"]);
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
  * Build the ordered list of stash sources, walking every configured stash
  * once. Iteration order:
  *
- *   1. The primary stash directory (the entry marked `primary: true`, or the
- *      legacy top-level `stashDir`). Always emitted, even when the directory
- *      does not yet exist on disk, so callers can use it as the clone target.
- *   2. Each entry in `config.sources[]` (in declared order), excluding the
- *      one already emitted as the primary.
- *   3. Each entry in `config.installed[]` (registry-managed stashes).
+ *   1. An explicit argument or `AKM_BUNDLE_DIR`, when present.
+ *   2. The configured `defaultBundle`, after component-root validation.
+ *   3. Remaining configured bundles in installation-priority order.
  *
  * Replaces the previous four-pass loop that walked `stashes[]` separately
- * for each provider kind. Disabled entries (`enabled: false`) and entries
- * whose disk path doesn't exist are filtered after deduplication.
+ * for each provider kind. Disabled entries (`enabled: false`) are filtered
+ * after deduplication. Missing configured roots remain in the result so the
+ * indexer can classify their scan as incomplete instead of mistaking them for
+ * removed sources.
  */
 export function resolveSourceEntries(overrideStashDir, existingConfig) {
-    const stashDir = overrideStashDir ?? resolveStashDir();
     const config = existingConfig ?? loadConfig();
-    // Primary stash is always writable.
-    const sources = [{ path: stashDir, writable: true }];
-    const seen = new Set([path.resolve(stashDir)]);
-    const addSource = (dir, registryId, wikiName, writable) => {
+    const configuredEntries = bundlesToSourceEntries(config) ?? [];
+    const envOverride = process.env.AKM_BUNDLE_DIR?.trim();
+    const implicitStashDir = overrideStashDir !== undefined
+        ? path.resolve(overrideStashDir)
+        : envOverride
+            ? resolveStashDir()
+            : config.defaultBundle
+                ? undefined
+                : resolveStashDir();
+    // Explicit and environment overrides stay first. Without either override,
+    // the configured default enters through the validated loop below.
+    const sources = implicitStashDir ? [{ path: implicitStashDir, writable: true }] : [];
+    const seen = new Set(implicitStashDir ? [implicitStashDir] : []);
+    const addSource = (dir, registryId, writable, type, adapterId, unresolved = false) => {
         const resolved = path.resolve(dir);
         if (seen.has(resolved)) {
             // Already in the source list — typically the primary stash injected at
             // sources[0] before this loop. Enrich that entry with whatever metadata
-            // the matching config source carries so `--source <config-name>` can
+            // the matching config source carries so `--from <config-name>` can
             // find it via registryId. Without this, the primary stash entry stays
             // identity-less and a user-named primary source ("name": "my-stash")
             // would validate but match zero entries when filtering.
             const existing = sources.find((s) => s.path === resolved);
-            if (existing) {
-                if (registryId && !existing.registryId)
+            if (existing && existing.type === undefined) {
+                if (registryId)
                     existing.registryId = registryId;
-                if (wikiName && !existing.wikiName)
-                    existing.wikiName = wikiName;
-                if (writable && !existing.writable)
-                    existing.writable = true;
+                existing.type = type;
+                existing.writable = writable;
+                existing.adapterId = adapterId;
             }
+            if (existing && unresolved)
+                existing.unresolved = true;
             return;
         }
         seen.add(resolved);
         if (isSuspiciousStashRoot(dir)) {
             warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
         }
-        if (isValidDirectory(dir)) {
-            sources.push({
-                path: resolved,
-                ...(registryId ? { registryId } : {}),
-                ...(wikiName ? { wikiName } : {}),
-                ...(writable ? { writable: true } : {}),
-            });
-        }
-    };
-    // (1) + (2) Single pass over declared stashes — primary first if present,
-    // then the rest in declared order. The primary's directory is already
-    // injected as `sources[0]` above, so we only need to dedupe the source set.
-    const stashes = getSources(config);
-    const primaryIdx = stashes.findIndex((entry) => entry.primary === true);
-    const ordered = [];
-    if (primaryIdx >= 0) {
-        ordered.push(stashes[primaryIdx]);
-        stashes.forEach((entry, i) => {
-            if (i !== primaryIdx)
-                ordered.push(entry);
+        sources.push({
+            path: resolved,
+            ...(registryId ? { registryId } : {}),
+            writable,
+            type,
+            ...(adapterId ? { adapterId } : {}),
+            ...(unresolved ? { unresolved: true } : {}),
         });
-    }
-    else {
-        ordered.push(...stashes);
-    }
-    for (const entry of ordered) {
+    };
+    // 0.9.0 shape (spec §10.1 / D-R5): resolve from `bundles` + `defaultBundle`.
+    // `bundlesToSourceEntries` returns the configured default first, then map
+    // insertion order. Each entry is validated before insertion so a component
+    // root can never escape its provider's materialized content root.
+    for (const entry of configuredEntries) {
         if (entry.enabled === false)
             continue;
-        const dir = resolveEntryContentDir(entry);
-        if (dir == null)
+        const component = bundleComponentConfig(config.bundles?.[entry.name ?? ""]);
+        const contentRoot = resolveEntryContentDir(entry);
+        if (contentRoot == null) {
+            const unresolvedPath = path.join(implicitStashDir ?? process.cwd(), ".akm", "unresolved-sources", entry.name ?? entry.type);
+            addSource(unresolvedPath, entry.name, component?.writable ?? resolveWritable(entry), entry.type, component?.adapter, true);
             continue;
-        addSource(dir, entry.name, entry.wikiName, entry.writable === true);
-    }
-    // (3) Installed stashes (registry-managed). Always last.
-    // Only installed entries explicitly marked writable: true are considered writable.
-    for (const entry of config.installed ?? []) {
-        addSource(entry.stashRoot, entry.id, entry.wikiName, entry.writable === true);
+        }
+        const dir = path.resolve(contentRoot, component?.root ?? ".");
+        if (!isWithin(dir, contentRoot)) {
+            warn(`Warning: component root "${component?.root}" escapes bundle "${entry.name}"; skipping source.`);
+            const unresolvedPath = path.join(contentRoot, ".akm", "unresolved-sources", entry.name ?? entry.type);
+            addSource(unresolvedPath, entry.name, component?.writable ?? resolveWritable(entry), entry.type, component?.adapter, true);
+            continue;
+        }
+        addSource(dir, entry.name, component?.writable ?? resolveWritable(entry), entry.type, component?.adapter);
     }
     return sources;
 }
@@ -116,7 +118,19 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
  * That convention is part of the akm content layout, not a provider concern,
  * so it stays here.
  */
-function resolveEntryContentDir(entry) {
+export function resolveEntryContentDir(entry) {
+    // §10.2 (WI-8.5) desired/resolved split: a git/npm bundle's desired config
+    // carries only the source LOCATOR, not the materialized cache root — the
+    // resolved root lives in the lock (`localRoot`). Resolve from there first via
+    // the SHARED lock-first resolver (the same one write-source consults, so reads
+    // and writes agree on where content is); the localRoot is the already-walkable
+    // content root (installed sources are extracted to their content dir), so no
+    // content/-subdir step is applied. Fall back to the provider path logic when no
+    // lock entry exists (e.g. a git bundle migrated from a `sources[]` url, whose
+    // provider re-derives the mirror path).
+    const localRoot = lockContentRootFor(entry.name, entry.type);
+    if (localRoot != null)
+        return localRoot;
     const factory = resolveSourceProviderFactory(entry.type);
     if (!factory)
         return undefined;
@@ -140,9 +154,8 @@ function resolveEntryContentDir(entry) {
     // layout puts indexable files under `<repo>/content/`, so the walker needs
     // that subdirectory. This is a content-layout convention, not a provider
     // capability — keep it here.
-    if (GIT_STASH_TYPES.has(entry.type)) {
-        const contentDir = path.join(dir, "content");
-        return isValidDirectory(contentDir) ? contentDir : dir;
+    if (entry.type === "git") {
+        return resolveGitContentRoot(dir);
     }
     return dir;
 }
@@ -154,15 +167,10 @@ export function resolveAllStashDirs(overrideStashDir) {
 }
 /**
  * Return the resolved absolute paths of all writable stash sources.
- *
- * The primary stash is always writable. Filesystem/git sources that have
- * `writable: true` in config are also included. Registry-cached sources
- * (installed without `writable: true`) are excluded because they are
- * overwritten on `akm update` and must never be mutated.
  */
 export function getWritableStashDirs(overrideStashDir, existingConfig) {
     return resolveSourceEntries(overrideStashDir, existingConfig)
-        .filter((s) => s.writable === true)
+        .filter((s) => isSourceWriteActivated(s))
         .map((s) => s.path);
 }
 /**
@@ -197,45 +205,22 @@ export function getPrimarySource(sources) {
 }
 // ── Editability ─────────────────────────────────────────────────────────────
 /**
- * Determine whether a file is safe to edit in place.
- *
- * The only files that are NOT editable are those inside a cache directory
- * managed by the package manager (`installed[].cacheDir`). These
- * will be overwritten by `akm update` without warning.
- *
- * Everything else — working stash, additional stashes, local project dirs — is
- * the user's domain to manage.
+ * Determine whether AKM policy allows modifying this exact file in place.
+ * Ownership is resolved by longest source-root match and unknown ownership
+ * fails closed. Resolved sources already carry canonical `resolveWritable()`
+ * semantics; editability is never persisted in the index.
  */
-export function isEditable(filePath, config) {
-    const cfg = config ?? loadConfig();
-    const resolved = path.resolve(filePath);
-    const cacheManaged = cfg.installed ?? [];
-    const isWin = process.platform === "win32";
-    for (const entry of cacheManaged) {
-        // Local sources reference original paths — always editable
-        if (entry.source === "local")
-            continue;
-        const cacheRoot = path.resolve(entry.cacheDir);
-        if (isWin) {
-            // Windows paths are case-insensitive — normalize both sides
-            if (resolved.toLowerCase().startsWith(cacheRoot.toLowerCase() + path.sep))
-                return false;
-        }
-        else {
-            if (resolved.startsWith(cacheRoot + path.sep))
-                return false;
-        }
-    }
-    return true;
+export function isEditable(filePath, config, sources) {
+    const resolvedSources = sources ?? resolveSourceEntries(undefined, config ?? loadConfig());
+    return findSourceForPath(filePath, resolvedSources)?.writable === true;
 }
 /**
  * Build an actionable hint for the agent when a file is not editable.
  * Callers must check `isEditable()` before calling — this function
  * unconditionally returns the hint string.
  */
-export function buildEditHint(_filePath, assetType, assetName, origin) {
-    const ref = origin ? `${origin}//${assetType}:${assetName}` : `${assetType}:${assetName}`;
-    return `This asset is managed by akm and may be overwritten on update. To edit, run: akm clone ${ref}`;
+export function buildEditHint(ref) {
+    return `This asset is read-only under current AKM source policy. To make an editable copy, run: akm clone ${ref}`;
 }
 // ── Validation ──────────────────────────────────────────────────────────────
 const SUSPICIOUS_ROOTS = new Set(["/", "/etc", "/bin", "/sbin", "/usr", "/var", "/tmp", "/dev", "/proc", "/sys"]);
@@ -252,33 +237,53 @@ function isSuspiciousStashRoot(dir) {
     }
     return false;
 }
-// ── Helpers ─────────────────────────────────────────────────────────────────
-function isValidDirectory(dir) {
-    try {
-        return fs.statSync(dir).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 // ── Stash cache integration ─────────────────────────────────────────────────
 /**
  * Ensure all cache-backed stash providers are refreshed so their cache
  * directories exist on disk. Must be called (async) before
  * `resolveSourceEntries()` so the content directories pass the
  * `isValidDirectory()` check.
+ *
+ * `materialize` (default `true`) is the query-time safety valve (spec §14.3 /
+ * D11): the sanctioned materialization callers (`akm index`, source
+ * add/update/sync, improve's blocking preflight) pass it truthy and clone/pull/
+ * fetch as needed. A READ command's inline auto-index passes `materialize:
+ * false` — network is FORBIDDEN at query time, so instead of `sync()` we only
+ * check whether each cache-backed source is already materialized: a present
+ * cache is served as-is (last-known-good; no TTL pull either), while an absent
+ * or partially-staged cache makes that source UNAVAILABLE for the read and is
+ * skipped with one warning naming the remedy. The rest of the command still
+ * resolves.
  */
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
+    const materialize = options?.materialize !== false;
     // Polymorphic refresh: walk every enabled source through its registered
     // provider and call `sync()`. Every cache-backed kind (git, website, npm)
     // refreshes the same way — a bad source warns and is skipped without
     // aborting the others. The git content/-subdir layout convention stays in
-    // resolveEntryContentDir.
+    // resolveEntryContentDir. NEW shape reads `bundles`; old shape reads sources[].
+    //
+    // DISTINCTION (deliberately NOT lock-first): refresh derives the PROVIDER's
+    // own cache path to git-pull/re-materialize INTO — that derived path is where
+    // content ENDS UP; the lock's `localRoot` merely records the result. So this
+    // path correctly uses the provider, not the shared `lockContentRootFor`
+    // resolver that reads/writes use to agree on where content already IS.
     for (const entry of getSources(cfg)) {
         if (entry.enabled === false)
             continue;
+        const lockedRoot = lockContentRootFor(entry.name, entry.type);
+        if (lockedRoot) {
+            if (!isMaterializedDir(lockedRoot)) {
+                warn(`Warning: managed source "${entry.name}" is missing its locked materialization at ${lockedRoot}; ` +
+                    `run \`akm bundle update ${entry.name}\` to restore it.`);
+            }
+            // Managed installs are refreshed only by add/update. Hydrating the URL-
+            // derived provider cache here would create a second checkout while reads
+            // and writes continue using the lock root.
+            continue;
+        }
         const factory = resolveSourceProviderFactory(entry.type);
         if (!factory)
             continue;
@@ -292,6 +297,12 @@ export async function ensureSourceCaches(config, options) {
         }
         if (!provider.sync)
             continue;
+        if (!materialize) {
+            // READ path: never clone/pull/fetch. Serve an already-materialized cache
+            // as last-known-good; skip an absent/partial one with a single warning.
+            warnIfSourceUnavailableForRead(entry, provider.name);
+            continue;
+        }
         try {
             await provider.sync({ force });
         }
@@ -300,3 +311,38 @@ export async function ensureSourceCaches(config, options) {
         }
     }
 }
+/**
+ * True when `dir` holds already-materialized content: it exists, is a
+ * directory, and is non-empty. A non-existent path or an empty leftover /
+ * partial staging dir reads as NOT materialized so the read skips it rather
+ * than walking a hollow cache.
+ */
+function isMaterializedDir(dir) {
+    try {
+        if (!fs.statSync(dir).isDirectory())
+            return false;
+        return fs.readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * On a read-path auto-index, warn (once per source) that a cache-backed source
+ * is not materialized locally and is being skipped — naming the remedy. Uses
+ * the SAME lock-first content-root resolution the walker uses, so an installed
+ * source whose content lives at its lock `localRoot` counts as materialized.
+ */
+function warnIfSourceUnavailableForRead(entry, providerName) {
+    let dir;
+    try {
+        dir = resolveEntryContentDir(entry);
+    }
+    catch {
+        dir = undefined;
+    }
+    if (dir && isMaterializedDir(dir))
+        return;
+    warn(`Warning: source "${providerName}" is not materialized locally; skipping it for this read. ` +
+        "Run `akm index` (or `akm bundle update`) to fetch it.");
+}

package/dist/indexer/search/semantic-status.js

@@ -11,7 +11,10 @@ export function deriveSemanticProviderFingerprint(embedding) {
         return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
     }
     if (embedding?.endpoint) {
-        return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;
+        // Fingerprint keys on vector identity only (model + dimension). The endpoint
+        // is transport/routing and has no bearing on vector compatibility, so moving
+        // the same model+dimension to a different host must not force a full re-embed.
+        return `remote:${embedding.model}|${embedding.dimension ?? "default"}`;
     }
     return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}`;
 }

package/dist/indexer/usage/usage-events.js

@@ -1,6 +1,14 @@
 // 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/.
+const USAGE_EVENT_SOURCES = new Set(["user", "improve", "task", "audit", "unknown"]);
+/** Resolve subprocess provenance without treating an invalid value as user demand. */
+export function resolveUsageEventSource(env = process.env) {
+    const raw = env.AKM_EVENT_SOURCE;
+    if (raw === undefined || raw === "")
+        return "user";
+    return USAGE_EVENT_SOURCES.has(raw) ? raw : "unknown";
+}
 // ── Schema ──────────────────────────────────────────────────────────────────
 export function ensureUsageEventsSchema(db) {
     db.exec(`
@@ -29,41 +37,13 @@ export function ensureUsageEventsSchema(db) {
 export function insertUsageEvent(db, event) {
     try {
         db.prepare(`INSERT INTO usage_events (event_type, query, entry_id, entry_ref, signal, metadata, source)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(event.event_type, event.query ?? null, event.entry_id ?? null, event.entry_ref ?? null, event.signal ?? null, event.metadata ?? null, event.source ?? "user");
+       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(event.event_type, event.query ?? null, event.entry_id ?? null, event.entry_ref ?? null, event.signal ?? null, event.metadata ?? null, event.source ?? "unknown");
     }
     catch {
         /* fire-and-forget: silently ignore errors */
     }
 }
 // ── Query ────────────────────────────────────────────────────────────────────
-/**
- * Retrieve usage events, optionally filtered by event_type and/or entry_ref.
- */
-export function getUsageEvents(db, filters) {
-    const conditions = [];
-    const params = [];
-    if (filters?.event_type) {
-        conditions.push("event_type = ?");
-        params.push(filters.event_type);
-    }
-    if (filters?.entry_ref) {
-        conditions.push("entry_ref = ?");
-        params.push(filters.entry_ref);
-    }
-    if (filters?.source) {
-        conditions.push("source = ?");
-        params.push(filters.source);
-    }
-    if (filters?.since) {
-        conditions.push("created_at >= ?");
-        params.push(filters.since);
-    }
-    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-    const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, source, created_at
-               FROM usage_events ${where}
-               ORDER BY id ASC`;
-    return db.prepare(sql).all(...params);
-}
 /**
  * Aggregate positive/negative feedback counts for a single entry.
  *
@@ -78,7 +58,7 @@ export function countFeedbackSignals(db, entryId) {
          SUM(CASE WHEN signal = 'positive' THEN 1 ELSE 0 END) AS pos,
          SUM(CASE WHEN signal = 'negative' THEN 1 ELSE 0 END) AS neg
        FROM usage_events
-       WHERE event_type = 'feedback' AND entry_id = ?`)
+       WHERE event_type = 'feedback' AND entry_id = ? AND source = 'user'`)
         .get(entryId);
     return { pos: counts?.pos ?? 0, neg: counts?.neg ?? 0 };
 }

package/dist/indexer/walk/file-context.js

@@ -67,8 +67,6 @@ export function buildFileContext(stashRoot, absPath) {
     };
 }
 // ── Registry ─────────────────────────────────────────────────────────────────
-/** Ordered list of registered matchers. Later registrations win ties. */
-const matchers = [];
 /** Renderer lookup by name. */
 const renderers = new Map();
 /**
@@ -77,21 +75,12 @@ const renderers = new Map();
  * Delegates to the single `initIndexer()` composition root (see
  * `src/indexer/init.ts`). Imported dynamically to keep this a lazy gate and to
  * avoid a static import cycle (init -> renderers -> file-context). Called on
- * first use of runMatchers/getRenderer/getAllRenderers; idempotent.
+ * first use of getRenderer/getAllRenderers; idempotent.
  */
 async function ensureBuiltinsRegistered() {
     const { initIndexer } = await import("../init.js");
     await initIndexer();
 }
-/**
- * Register an AssetMatcher.
- *
- * Matchers are evaluated in registration order. When two matchers produce
- * the same specificity score, the one registered later wins.
- */
-export function registerMatcher(matcher) {
-    matchers.push(matcher);
-}
 /**
  * Register an AssetRenderer.
  *
@@ -114,47 +103,16 @@ export async function getAllRenderers() {
     await ensureBuiltinsRegistered();
     return Array.from(renderers.values());
 }
-/**
- * Run every registered matcher against a FileContext and return the
- * highest-specificity result.
- *
- * Resolution rules:
- * 1. Every matcher is invoked; null returns are discarded.
- * 2. Results are ranked by specificity (descending).
- * 3. Ties are broken by registration order: the matcher registered later wins
- *    (this lets user-registered matchers override built-in ones).
- * 4. Returns null when no matcher claims the file.
- */
-export async function runMatchers(ctx) {
-    await ensureBuiltinsRegistered();
-    // Collect (result, registrationIndex) pairs from all matchers.
-    const hits = [];
-    for (let i = 0; i < matchers.length; i++) {
-        const result = matchers[i](ctx);
-        if (result !== null) {
-            hits.push({ result, index: i });
-        }
-    }
-    if (hits.length === 0)
-        return null;
-    // Sort by specificity descending, then by registration index descending (later wins ties).
-    hits.sort((a, b) => {
-        const specDiff = b.result.specificity - a.result.specificity;
-        if (specDiff !== 0)
-            return specDiff;
-        return b.index - a.index;
-    });
-    return hits[0].result;
-}
 /**
  * Build a RenderContext by merging a FileContext with its winning MatchResult
  * and the list of stash search paths.
  */
-export function buildRenderContext(ctx, match, stashDirs, origin) {
+export function buildRenderContext(ctx, match, stashDirs, origin, defaultBundle) {
     return {
         ...ctx,
         matchResult: match,
         stashDirs,
         origin,
+        defaultBundle,
     };
 }