akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{registry-resolve.js → registry/resolve.js}

@@ -3,9 +3,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { fetchWithRetry } from "./common";
-import { UsageError } from "./errors";
-import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "./github";
+import { fetchWithRetry, jsonWithByteCap } from "../core/common";
+import { UsageError } from "../core/errors";
+import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github";
 /**
  * Validate that a URL is safe to pass to git.
  * Allowlists https:, http:, ssh:, git: schemes and git@ SSH shorthand.
@@ -451,7 +451,7 @@ function fileUriToPath(ref) {
 /**
  * Build a human-readable local ID from an absolute path.
  *   /home/user/akm/skills     → ~/akm/skills
- *   /tmp/my-kit               → /tmp/my-kit
+ *   /tmp/my-stash               → /tmp/my-stash
  */
 function toReadableLocalId(absolutePath) {
     const home = os.homedir();
@@ -571,16 +571,20 @@ export function maxSatisfying(versions, range) {
     candidates.sort((a, b) => compareSemver(b.parsed, a.parsed));
     return candidates[0].version;
 }
+// Cap JSON responses at 10 MB — npm package manifests and GitHub API
+// responses are typically a few KB; a compromised registry streaming
+// tens of MB of JSON is a DoS surface, not a feature.
+const REGISTRY_JSON_BYTE_CAP = 10 * 1024 * 1024;
 async function fetchJson(url, headers) {
     const response = await fetchWithRetry(url, { headers });
     if (!response.ok) {
         throw new Error(`Request failed (${response.status}) for ${url}`);
     }
-    return (await response.json());
+    return jsonWithByteCap(response, REGISTRY_JSON_BYTE_CAP);
 }
 async function tryFetchJson(url, headers) {
     const response = await fetchWithRetry(url, { headers });
     if (!response.ok)
         return null;
-    return (await response.json());
+    return jsonWithByteCap(response, REGISTRY_JSON_BYTE_CAP);
 }

package/dist/{detect.js → setup/detect.js}

@@ -91,30 +91,3 @@ export function detectAgentPlatforms() {
         path: path.join(home, p.relPath),
     }));
 }
-// ── OpenViking Detection ────────────────────────────────────────────────────
-/**
- * Check if an OpenViking server is reachable at the given URL.
- * Uses the lightweight /api/v1/fs/stat endpoint (GET) rather than
- * the search endpoint which requires a running search index.
- */
-export async function detectOpenViking(url) {
-    const normalized = url.replace(/\/+$/, "");
-    try {
-        // Any HTTP response (even non-2xx) from the API endpoint means the server is reachable.
-        // Only network errors / timeouts indicate the server is truly unavailable.
-        await fetch(`${normalized}/api/v1/fs/stat?uri=${encodeURIComponent("viking://")}`, {
-            signal: AbortSignal.timeout(5000),
-        });
-        return { available: true, url: normalized };
-    }
-    catch {
-        // stat endpoint unreachable — try root URL as fallback
-        try {
-            await fetch(normalized, { signal: AbortSignal.timeout(5000) });
-            return { available: true, url: normalized };
-        }
-        catch {
-            return { available: false, url: normalized };
-        }
-    }
-}

package/dist/{ripgrep-install.js → setup/ripgrep-install.js}

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

package/dist/{ripgrep-resolve.js → setup/ripgrep-resolve.js}

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "./common";
-import { getBinDir } from "./paths";
+import { IS_WINDOWS } from "../core/common";
+import { getBinDir } from "../core/paths";
 export const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
 function canExecute(filePath) {
     if (!fs.existsSync(filePath))

package/dist/{setup.js → setup/setup.js}

@@ -7,25 +7,26 @@
  */
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { isHttpUrl } from "./common";
-import { DEFAULT_CONFIG, getConfigPath, loadUserConfig, saveConfig } from "./config";
-import { closeDatabase, isVecAvailable, openDatabase } from "./db";
-import { detectAgentPlatforms, detectOllama, detectOpenViking } from "./detect";
-import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedder";
-import { akmIndex } from "./indexer";
-import { akmInit } from "./init";
-import { probeLlmCapabilities } from "./llm";
-import { getDefaultStashDir } from "./paths";
-import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./semantic-status";
+import { akmInit } from "../commands/init";
+import { isHttpUrl } from "../core/common";
+import { DEFAULT_CONFIG, getConfigPath, loadUserConfig, saveConfig } from "../core/config";
+import { getDefaultStashDir } from "../core/paths";
+import { closeDatabase, isVecAvailable, openDatabase } from "../indexer/db";
+import { akmIndex } from "../indexer/indexer";
+import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "../indexer/semantic-status";
+import { probeLlmCapabilities } from "../llm/client";
+import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "../llm/embedder";
+import { detectAgentPlatforms, detectOllama } from "./detect";
+import { createSetupContext, runSetupSteps } from "./steps";
 // ── Constants ───────────────────────────────────────────────────────────────
-/** Recommended GitHub repositories shown during setup. */
-const RECOMMENDED_GITHUB_REPOS = [
-    {
-        url: "https://github.com/andrewyng/context-hub",
-        name: "context-hub",
-        hint: "community knowledge",
-    },
-];
+/**
+ * Recommended GitHub repositories shown during setup.
+ *
+ * Currently empty — populating from the akm-registry at runtime is a
+ * separate feature. The wizard prompt infrastructure is retained for that
+ * future use.
+ */
+const RECOMMENDED_GITHUB_REPOS = [];
 // Approximate first-download sizes used in the setup note.
 // LOCAL_MODEL_APPROX_SIZE_MB tracks the default local model (DEFAULT_LOCAL_MODEL).
 const LOCAL_MODEL_APPROX_SIZE_MB = 130;
@@ -136,11 +137,11 @@ async function prepareSemanticSearchAssets(config) {
     const remote = isRemoteEmbeddingConfig(config.embedding);
     // For local embeddings, ensure the required package is installed first.
     if (!remote) {
-        if (!(await isTransformersAvailable())) {
+        if (!isTransformersAvailable()) {
             const spin = p.spinner();
             spin.start("Installing @huggingface/transformers...");
             try {
-                const pkgRoot = path.resolve(import.meta.dir, "..");
+                const pkgRoot = path.resolve(import.meta.dir, "../..");
                 const proc = Bun.spawn(["bun", "add", "@huggingface/transformers"], {
                     cwd: pkgRoot,
                     stdout: "pipe",
@@ -499,40 +500,44 @@ async function stepRegistries(current) {
 /**
  * @internal Exported for testing only.
  */
-export async function stepStashSources(current) {
-    const stashes = [...(current.stashes ?? [])];
+export async function stepAddSources(current) {
+    const stashes = [...(current.sources ?? current.stashes ?? [])];
     if (stashes.length > 0) {
         p.log.info(`You have ${stashes.length} existing stash source(s).`);
     }
     // ── Recommended GitHub repos ───────────────────────────────────────────
-    const existingUrls = new Set(stashes.map((s) => s.url));
-    const repoOptions = RECOMMENDED_GITHUB_REPOS.map((r) => ({
-        value: r.url,
-        label: r.name,
-        hint: existingUrls.has(r.url) ? `${r.hint} (already added)` : r.hint,
-    }));
-    const selectedRepos = await prompt(() => p.multiselect({
-        message: "Recommended GitHub repositories — toggle to add or remove:",
-        options: repoOptions,
-        initialValues: repoOptions.filter((o) => existingUrls.has(o.value)).map((o) => o.value),
-        required: false,
-    }));
-    // Add newly selected repos
-    for (const url of selectedRepos) {
-        if (!existingUrls.has(url)) {
-            const rec = RECOMMENDED_GITHUB_REPOS.find((r) => r.url === url);
-            stashes.push({ type: "git", url, name: rec?.name });
-            existingUrls.add(url);
+    // Skip the prompt entirely when there are no recommendations to show.
+    // The infrastructure is retained for a future registry-driven version.
+    if (RECOMMENDED_GITHUB_REPOS.length > 0) {
+        const existingUrls = new Set(stashes.map((s) => s.url));
+        const repoOptions = RECOMMENDED_GITHUB_REPOS.map((r) => ({
+            value: r.url,
+            label: r.name,
+            hint: existingUrls.has(r.url) ? `${r.hint} (already added)` : r.hint,
+        }));
+        const selectedRepos = await prompt(() => p.multiselect({
+            message: "Recommended GitHub repositories — toggle to add or remove:",
+            options: repoOptions,
+            initialValues: repoOptions.filter((o) => existingUrls.has(o.value)).map((o) => o.value),
+            required: false,
+        }));
+        // Add newly selected repos
+        for (const url of selectedRepos) {
+            if (!existingUrls.has(url)) {
+                const rec = RECOMMENDED_GITHUB_REPOS.find((r) => r.url === url);
+                stashes.push({ type: "git", url, name: rec?.name });
+                existingUrls.add(url);
+            }
         }
-    }
-    // Remove deselected repos that were previously configured
-    for (const rec of RECOMMENDED_GITHUB_REPOS) {
-        if (existingUrls.has(rec.url) && !selectedRepos.includes(rec.url)) {
-            const idx = stashes.findIndex((s) => s.url === rec.url);
-            if (idx !== -1) {
-                stashes.splice(idx, 1);
-                existingUrls.delete(rec.url);
-                p.log.info(`Removed ${rec.name}.`);
+        // Remove deselected repos that were previously configured
+        for (const rec of RECOMMENDED_GITHUB_REPOS) {
+            if (existingUrls.has(rec.url) && !selectedRepos.includes(rec.url)) {
+                const idx = stashes.findIndex((s) => s.url === rec.url);
+                if (idx !== -1) {
+                    stashes.splice(idx, 1);
+                    existingUrls.delete(rec.url);
+                    p.log.info(`Removed ${rec.name}.`);
+                }
             }
         }
     }
@@ -542,7 +547,6 @@ export async function stepStashSources(current) {
         const action = await prompt(() => p.select({
             message: "Add another stash source?",
             options: [
-                { value: "openviking", label: "OpenViking server", hint: "remote stash" },
                 { value: "github-repo", label: "GitHub repository", hint: "custom URL" },
                 { value: "filesystem", label: "Filesystem path", hint: "local directory" },
                 { value: "done", label: "Done — no more sources" },
@@ -552,45 +556,6 @@ export async function stepStashSources(current) {
             addMore = false;
             break;
         }
-        if (action === "openviking") {
-            const url = await promptOrBack(() => p.text({
-                message: "Enter the OpenViking server URL:",
-                placeholder: "https://your-openviking-server.example.com",
-                validate: (v) => {
-                    if (!v?.trim())
-                        return "URL cannot be empty";
-                    if (!v.startsWith("http://") && !v.startsWith("https://"))
-                        return "URL must start with http:// or https://";
-                },
-            }));
-            if (url === null)
-                continue;
-            const spin = p.spinner();
-            spin.start("Checking OpenViking server...");
-            const result = await detectOpenViking(url.trim());
-            if (result.available) {
-                spin.stop("Server is reachable");
-            }
-            else {
-                spin.stop("Server not reachable — adding anyway (it may be temporarily down)");
-            }
-            const name = await promptOrBack(() => p.text({
-                message: "Give this stash a name (optional):",
-                placeholder: "my-openviking",
-            }));
-            if (name === null)
-                continue;
-            // Use the normalized URL from detection (trailing slashes stripped)
-            const entry = { type: "openviking", url: result.url };
-            if (name.trim())
-                entry.name = name.trim();
-            if (!stashes.some((s) => s.url === entry.url)) {
-                stashes.push(entry);
-            }
-            else {
-                p.log.warn("This URL is already configured.");
-            }
-        }
         if (action === "github-repo") {
             const url = await promptOrBack(() => p.text({
                 message: "Enter the GitHub repository URL:",
@@ -685,60 +650,128 @@ async function stepAgentPlatforms(current) {
     return entries;
 }
 // ── Main Wizard ─────────────────────────────────────────────────────────────
+/**
+ * Build the canonical list of `SetupStep`s for the interactive wizard.
+ * Exposed (and exported) so tests and `akm init` can compose subsets.
+ *
+ * Each step wraps the existing `step*` functions, accumulating its result
+ * into the shared `SetupContext`. The `nonInteractive` flag controls
+ * inclusion in `akm init` (a non-interactive preset of `akm setup`).
+ */
+export function buildSetupSteps(options) {
+    const outcome = { semantic: options.semanticSearchOutcome };
+    // Local cache of Ollama-detected fields surfaced from the embedding step
+    // to the LLM step. Mutable by design — `stepLlm` needs them.
+    let ollamaEndpoint;
+    let ollamaChatModels;
+    const steps = [
+        {
+            id: "stash-dir",
+            label: "Stash Directory",
+            nonInteractive: true,
+            async run(ctx) {
+                const stashDir = await stepStashDir(ctx.config);
+                ctx.apply({ stashDir });
+            },
+        },
+        {
+            id: "embedding",
+            label: "Embedding",
+            async run(ctx) {
+                if (!options.online) {
+                    ctx.apply({ embedding: ctx.config.embedding });
+                    return;
+                }
+                const result = await stepOllama(ctx.config);
+                ollamaEndpoint = result.ollamaEndpoint;
+                ollamaChatModels = result.ollamaChatModels;
+                ctx.apply({ embedding: result.embedding });
+            },
+        },
+        {
+            id: "llm",
+            label: "LLM Provider",
+            async run(ctx) {
+                if (!options.online) {
+                    ctx.apply({ llm: ctx.config.llm });
+                    return;
+                }
+                const llm = await stepLlm(ctx.config, ollamaEndpoint, ollamaChatModels);
+                ctx.apply({ llm });
+            },
+        },
+        {
+            id: "semantic-search",
+            label: "Semantic Search",
+            async run(ctx) {
+                const semantic = await stepSemanticSearch(ctx.config, ctx.config.embedding);
+                outcome.semantic = semantic;
+                ctx.apply({ semanticSearchMode: semantic.mode });
+            },
+        },
+        {
+            id: "registries",
+            label: "Registries",
+            async run(ctx) {
+                const registries = await stepRegistries(ctx.config);
+                ctx.apply({ registries });
+            },
+        },
+        {
+            id: "stash-sources",
+            label: "Stash Sources",
+            async run(ctx) {
+                const stashes = await stepAddSources(ctx.config);
+                const platforms = await stepAgentPlatforms(ctx.config);
+                const merged = [...stashes];
+                for (const ps of platforms) {
+                    if (!merged.some((s) => s.path === ps.path))
+                        merged.push(ps);
+                }
+                ctx.apply({ sources: merged.length > 0 ? merged : undefined });
+            },
+        },
+    ];
+    return { steps, outcome };
+}
 export async function runSetupWizard() {
     p.intro("akm setup");
     const current = loadUserConfig();
     const configPath = getConfigPath();
-    // Step 1: Stash directory
-    p.log.step("Step 1: Stash Directory");
-    const stashDir = await stepStashDir(current);
     // Quick connectivity check — skip network-dependent steps when offline
     const online = await isOnline();
     if (!online) {
         p.log.warn("No network connectivity detected. Skipping Ollama detection and remote embedding checks.\n" +
             "Local-only setup will continue. Re-run `akm setup` when online for full configuration.");
     }
-    // Step 2: Embedding (Ollama detection drives the embedding choice + surfaces
-    // the Ollama endpoint to the LLM step that follows).
-    p.log.step("Step 2: Embedding");
-    const { embedding, ollamaEndpoint, ollamaChatModels } = online
-        ? await stepOllama(current)
-        : { embedding: current.embedding };
-    // Step 2b: LLM provider — Anthropic / OpenAI / Gemini / Ollama / custom.
-    p.log.step("Step 2b: LLM Provider");
-    const llm = online ? await stepLlm(current, ollamaEndpoint, ollamaChatModels) : current.llm;
-    // Step 3: Semantic search assets
-    p.log.step("Step 3: Semantic Search");
-    const semanticSearchMode = await stepSemanticSearch(current, embedding);
-    // Step 4: Registries
-    p.log.step("Step 4: Registries");
-    const registries = await stepRegistries(current);
-    // Step 5: Stash sources
-    p.log.step("Step 5: Stash Sources");
-    const stashes = await stepStashSources(current);
-    // Step 6: Agent platform detection
-    p.log.step("Step 6: Agent Platform Detection");
-    const platformStashes = await stepAgentPlatforms(current);
-    // Merge platform stashes into main stashes list
-    const allStashes = [...stashes];
-    for (const ps of platformStashes) {
-        if (!allStashes.some((s) => s.path === ps.path)) {
-            allStashes.push(ps);
-        }
-    }
-    // Build final config
+    const ctx = createSetupContext(current, { nonInteractive: false });
+    const { steps, outcome } = buildSetupSteps({
+        online,
+        semanticSearchOutcome: { mode: current.semanticSearchMode, prepareAssets: false },
+    });
+    // Wrap each step with a `p.log.step()` header so the wizard UI is
+    // unchanged. The canonical `runSetupSteps()` runner is used directly by
+    // `akm init` (non-interactive) and by tests.
+    const labeledSteps = steps.map((step) => ({
+        ...step,
+        async run(stepCtx) {
+            p.log.step(step.label);
+            await step.run(stepCtx);
+        },
+    }));
+    await runSetupSteps(labeledSteps, ctx);
     const newConfig = {
-        ...current,
-        stashDir,
-        embedding,
-        llm,
-        registries,
-        stashes: allStashes.length > 0 ? allStashes : undefined,
-        // Preserve existing fields
-        semanticSearchMode: semanticSearchMode.mode,
+        ...ctx.config,
+        // Preserve fields the steps don't manage explicitly.
         installed: current.installed,
         output: current.output,
     };
+    const semanticSearchMode = outcome.semantic;
+    const stashDir = newConfig.stashDir ?? current.stashDir ?? getDefaultStashDir();
+    const embedding = newConfig.embedding;
+    const llm = newConfig.llm;
+    const registries = newConfig.registries;
+    const allStashes = newConfig.stashes ?? [];
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];
     p.note([

package/dist/setup/steps.js

@@ -0,0 +1,45 @@
+/**
+ * Composable runner abstraction for `akm setup`.
+ *
+ * The interactive wizard in `setup.ts` historically ran a fixed series of
+ * step functions (`stepStashDir`, `stepOllama`, `stepLlm`, ...) inline.
+ * This module formalizes that pattern so steps can be:
+ *   - reused by `akm init` (non-interactive preset, see Finding 31),
+ *   - tested in isolation by passing a stub `SetupContext`, and
+ *   - extended by plugins without touching the wizard call site.
+ *
+ * Steps mutate state through `SetupContext.apply()`, which accumulates a
+ * delta on top of the original config. `stepLlm` reading the embedding
+ * endpoint that `stepSemanticSearch` produced is the canonical example of
+ * why mutable accumulation is preferred over immutable returns.
+ */
+/**
+ * Build a fresh `SetupContext` over a starting config. The returned context
+ * applies deltas in-place onto an internal accumulator and exposes the
+ * latest snapshot via `ctx.config`.
+ */
+export function createSetupContext(initial, options) {
+    let acc = { ...initial };
+    return {
+        get config() {
+            return acc;
+        },
+        nonInteractive: options.nonInteractive,
+        apply(delta) {
+            acc = { ...acc, ...delta };
+        },
+    };
+}
+/**
+ * Run a list of steps against a context. Steps marked interactive-only are
+ * skipped when `ctx.nonInteractive` is true. Returns the final accumulated
+ * config so callers can persist it without re-reading the context.
+ */
+export async function runSetupSteps(steps, ctx) {
+    for (const step of steps) {
+        if (ctx.nonInteractive && !step.nonInteractive)
+            continue;
+        await step.run(ctx);
+    }
+    return ctx.config;
+}

package/dist/{kit-include.js → sources/include.js}

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isWithin } from "./common";
+import { isWithin } from "../core/common";
 // ── Helpers ─────────────────────────────────────────────────────────────────
 /** Key to check in package.json for akm include configuration. */
 const INCLUDE_CONFIG_KEYS = ["akm"];

package/dist/sources/provider-factory.js

@@ -0,0 +1,36 @@
+/**
+ * Source provider factory map.
+ *
+ * Maps source kind identifiers (e.g. "filesystem", "git", "website", "npm")
+ * to factory functions that build {@link SourceProvider} instances from a
+ * {@link SourceConfigEntry}.
+ *
+ * Distinct from the registry-discovery factory (`registry/factory.ts`).
+ * Both share `create-provider-registry.ts` for the underlying string→factory
+ * map.
+ */
+import { createProviderRegistry } from "../registry/create-provider-registry";
+// ── Factory map ─────────────────────────────────────────────────────────────
+const registry = createProviderRegistry();
+export function registerSourceProvider(type, factory) {
+    registry.register(type, factory);
+}
+export function resolveSourceProviderFactory(type) {
+    return registry.resolve(type);
+}
+/**
+ * Build a {@link SourceProvider} for every enabled source in the config that
+ * has a registered factory.
+ */
+export function resolveSourceProviders(config) {
+    const providers = [];
+    for (const entry of config.sources ?? config.stashes ?? []) {
+        if (entry.enabled === false)
+            continue;
+        const factory = registry.resolve(entry.type);
+        if (factory) {
+            providers.push(factory(entry));
+        }
+    }
+    return providers;
+}

package/dist/sources/provider.js

@@ -0,0 +1,21 @@
+/**
+ * SourceProvider — minimal v1 interface (spec §2.1).
+ *
+ * A SourceProvider gets files into a directory. The indexer walks `path()`
+ * and reads files from disk. Search and show go through the indexer, not
+ * through provider methods.
+ *
+ * Three required members + one optional:
+ *   - name      configured source name
+ *   - kind      "filesystem" | "git" | "website" | "npm"
+ *   - init(ctx) called once after construction
+ *   - path()    the directory the indexer walks (stable for instance lifetime)
+ *   - sync?()   refresh the directory from upstream (no-op for filesystem)
+ *
+ * All other writing/reading concerns live outside this interface:
+ *   - Writes:    src/core/write-source.ts (Phase 5)
+ *   - Reads:     src/indexer.ts (Phase 4)
+ *   - Install:   src/sources/providers/sync-from-ref.ts (install-time helpers,
+ *                separate from configured-source plumbing)
+ */
+export {};

package/dist/sources/providers/filesystem.js

@@ -0,0 +1,35 @@
+import { resolveStashDir } from "../../core/common";
+import { ConfigError } from "../../core/errors";
+import { registerSourceProvider } from "../provider-factory";
+/**
+ * Filesystem source — points at a directory the user already manages.
+ *
+ * Implements the v1 {@link SourceProvider} interface (spec §2.1, §2.4):
+ * just `{ name, kind, init, path }`. No `sync()` — content is the user's
+ * own directory, never refreshed by akm.
+ */
+class FilesystemSourceProvider {
+    kind = "filesystem";
+    name;
+    #stashDir;
+    constructor(entry) {
+        if (entry.type !== "filesystem") {
+            throw new ConfigError(`FilesystemSourceProvider invoked with type="${entry.type}"`);
+        }
+        this.#stashDir = entry.path ?? resolveStashDir();
+        if (!this.#stashDir) {
+            throw new ConfigError("filesystem source requires a `path`");
+        }
+        this.name = entry.name ?? this.#stashDir;
+    }
+    async init(_ctx) {
+        // Filesystem sources resolve their path eagerly in the constructor;
+        // init has nothing to do beyond letting the registry know we're ready.
+    }
+    path() {
+        return this.#stashDir;
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerSourceProvider("filesystem", (config) => new FilesystemSourceProvider(config));
+export { FilesystemSourceProvider };