akm-cli 0.6.0-rc1 → 0.6.0

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

@@ -7,17 +7,17 @@
  */
 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 { createSetupContext, runSetupSteps } from "./setup-steps";
+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.
@@ -141,7 +141,7 @@ async function prepareSemanticSearchAssets(config) {
             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",
@@ -500,8 +500,8 @@ 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).`);
     }
@@ -547,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" },
@@ -557,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:",
@@ -761,14 +721,14 @@ export function buildSetupSteps(options) {
             id: "stash-sources",
             label: "Stash Sources",
             async run(ctx) {
-                const stashes = await stepStashSources(ctx.config);
+                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({ stashes: merged.length > 0 ? merged : undefined });
+                ctx.apply({ sources: merged.length > 0 ? merged : undefined });
             },
         },
     ];

package/dist/{stash-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 };

package/dist/{stash-providers → sources/providers}/git.js

@@ -2,12 +2,12 @@ import { spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "../common";
-import { loadConfig } from "../config";
-import { ConfigError, UsageError } from "../errors";
-import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../paths";
-import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../registry-resolve";
-import { registerStashProvider } from "../stash-provider-factory";
+import { resolveStashDir } from "../../core/common";
+import { loadConfig } from "../../core/config";
+import { ConfigError, UsageError } from "../../core/errors";
+import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../../core/paths";
+import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve";
+import { registerSourceProvider } from "../provider-factory";
 import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, isExpired, sanitizeString, } from "./provider-utils";
 /** Cache TTL before refreshing the mirrored repo (12 hours). */
 const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
@@ -15,74 +15,63 @@ const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 const GIT_STASH_TYPES = new Set(["git"]);
 /**
- * Git stash provider. Implements {@link SyncableStashProvider} (which extends
- * the LiveStashProvider surface) — the indexer walks the cloned repo, and
- * `sync()` clones/pulls into a local mirror.
+ * Git source provider — clones (and re-pulls) a remote repo into a local
+ * cache directory. Implements the v1 {@link SourceProvider} interface (spec
+ * §2.1, §2.5): `{ name, kind, init, path, sync }`.
+ *
+ * Reading is the indexer's job — this class doesn't implement `search` or
+ * `show`. The install-time helpers `syncRegistryGitRef` / `syncMirroredRepo`
+ * live below as standalone functions used by `akm add` / `akm update`.
  */
-class GitStashProvider {
-    type = "git";
-    kind = "syncable";
+class GitSourceProvider {
+    kind = "git";
     name;
-    config;
+    #config;
+    #path = null;
     constructor(config) {
-        this.config = config;
+        this.#config = config;
         this.name = config.name ?? "git";
     }
-    /** Content is indexed through the standard FTS5 pipeline. */
-    async search(_options) {
-        return { hits: [] };
-    }
-    /** Content is local files, shown via showLocal. */
-    async show(_ref, _view) {
-        throw new Error("Git provider content is shown via local index");
-    }
-    /** Content is local; no remote show needed. */
-    canShow(_ref) {
-        return false;
+    async init(_ctx) {
+        // Resolve the on-disk content directory once. For configured git sources
+        // this is the cached working tree; for one-shot install refs it's the
+        // path the install pipeline materialised.
+        this.#path = resolveGitContentDir(this.#config);
+    }
+    path() {
+        if (this.#path == null) {
+            // Lazy resolution: providers are sometimes constructed without an
+            // explicit init() call (e.g. by legacy callers that just want the
+            // path). Resolve on demand and cache.
+            this.#path = resolveGitContentDir(this.#config);
+        }
+        return this.#path;
     }
-    async sync(config, options) {
+    async sync() {
         // Two execution modes:
-        //   1. Long-lived configured stash (config.url) — mirror into the
+        //   1. Long-lived configured source (config.url) — mirror into the
         //      registry-index cache and serve as a read-only working tree.
-        //   2. One-shot install ref (config.options.ref like "git:..." / "github:...") —
-        //      run the historical clone-into-cache flow used by `akm add`.
-        if (typeof config.options?.ref === "string" && config.options.ref) {
-            return syncRegistryGitRef(String(config.options.ref), options);
-        }
-        return syncMirroredRepo(config, options);
-    }
-    getContentDir(config) {
-        if (config.path)
-            return config.path;
-        if (config.url) {
-            const repo = parseGitRepoUrl(config.url);
-            return getCachePaths(repo.canonicalUrl).repoDir;
-        }
-        throw new ConfigError("git stash entry must have either `path` or `url`");
-    }
-    async remove(config) {
-        if (config.path && isDirectory(config.path)) {
-            try {
-                fs.rmSync(path.dirname(config.path), { recursive: true, force: true });
-            }
-            catch {
-                /* best-effort */
-            }
-        }
-        else if (config.url) {
-            const repo = parseGitRepoUrl(config.url);
-            const paths = getCachePaths(repo.canonicalUrl);
-            try {
-                fs.rmSync(paths.rootDir, { recursive: true, force: true });
-            }
-            catch {
-                /* best-effort */
-            }
+        //   2. One-shot install ref (options.ref like "git:..." / "github:...") —
+        //      delegate to the install-time pipeline.
+        if (typeof this.#config.options?.ref === "string" && this.#config.options.ref) {
+            await syncRegistryGitRef(String(this.#config.options.ref));
+            return;
         }
+        await syncMirroredRepo(this.#config);
     }
 }
+/** Resolve the on-disk content directory for a configured git source. */
+function resolveGitContentDir(config) {
+    if (config.path)
+        return config.path;
+    if (config.url) {
+        const repo = parseGitRepoUrl(config.url);
+        return getCachePaths(repo.canonicalUrl).repoDir;
+    }
+    throw new ConfigError("git source entry must have either `path` or `url`");
+}
 // ── Self-register ───────────────────────────────────────────────────────────
-registerStashProvider("git", (config) => new GitStashProvider(config));
+registerSourceProvider("git", (config) => new GitSourceProvider(config));
 // ── Cache management ────────────────────────────────────────────────────────
 function getCachePaths(repoUrl) {
     const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
@@ -414,7 +403,7 @@ export function saveGitStash(name, message, writableOverride) {
     let writable = false;
     if (name) {
         const config = loadConfig();
-        const stash = config.stashes?.find((s) => s.name === name || s.url === name);
+        const stash = (config.sources ?? config.stashes ?? []).find((s) => s.name === name || s.url === name);
         if (!stash)
             throw new UsageError(`No git stash found with name "${name}"`);
         if (!GIT_STASH_TYPES.has(stash.type)) {
@@ -476,4 +465,4 @@ export function saveGitStash(name, message, writableOverride) {
     };
 }
 // ── Exports ─────────────────────────────────────────────────────────────────
-export { ensureGitMirror, GitStashProvider, getCachePaths, parseGitRepoUrl };
+export { ensureGitMirror, GitSourceProvider, getCachePaths, parseGitRepoUrl };

package/dist/{stash-providers → sources/providers}/index.js

@@ -1,12 +1,11 @@
 /**
- * Centralized stash provider registration.
+ * Centralized source provider registration.
  *
- * Import this module (side-effect import) to register all built-in stash
+ * Import this module (side-effect import) to register all built-in source
  * providers with the provider registry. This replaces the individual
- * side-effect imports that were duplicated in stash-search.ts and stash-show.ts.
+ * side-effect imports that were duplicated in source-search.ts and source-show.ts.
  */
 import "./filesystem";
 import "./git";
 import "./npm";
-import "./openviking";
 import "./website";

package/dist/sources/providers/install-types.js

@@ -0,0 +1,14 @@
+/**
+ * Install-time types used by `syncFromRef` and the legacy install pipeline.
+ *
+ * Distinct from the v1 {@link SourceProvider} interface (which only deals
+ * with "configured sources" — entries already resolved into a directory).
+ * These types describe the resolution+lockfile step that runs when
+ * `akm add <install-ref>` materialises an upstream artifact into a local
+ * cache directory.
+ *
+ * They live here, outside `provider.ts`, so the v1 SourceProvider
+ * interface stays minimal (`{ name, kind, init, path, sync? }`) per the
+ * architecture spec §2.1.
+ */
+export {};

package/dist/{stash-providers → sources/providers}/npm.js

@@ -12,53 +12,46 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { ConfigError, UsageError } from "../errors";
-import { getRegistryCacheDir } from "../paths";
-import { parseRegistryRef, resolveRegistryArtifact } from "../registry-resolve";
-import { registerStashProvider } from "../stash-provider-factory";
+import { ConfigError, UsageError } from "../../core/errors";
+import { getRegistryCacheDir } from "../../core/paths";
+import { parseRegistryRef, resolveRegistryArtifact } from "../../registry/resolve";
+import { registerSourceProvider } from "../provider-factory";
 import { applyAkmIncludeConfig, buildInstallCacheDir, computeFileHash, detectStashRoot, downloadArchive, isDirectory, } from "./provider-utils";
 import { extractTarGzSecure, verifyArchiveIntegrity } from "./tar-utils";
-class NpmStashProvider {
-    type = "npm";
-    kind = "syncable";
+/**
+ * NPM source provider — fetches a tarball from the npm registry and extracts
+ * it into a local cache. Implements the v1 {@link SourceProvider} interface
+ * (spec §2.1): `{ name, kind, init, path, sync }`.
+ *
+ * The install-time pipeline (`syncNpmRef`) lives below as a standalone
+ * function used by `akm add` / `akm update` — that path produces a
+ * {@link SourceLockData} record for lockfile bookkeeping. The provider's own
+ * `sync()` is a void refresh (delegates to the install pipeline but discards
+ * the lock data, which is owned by `lockfile.ts`).
+ */
+class NpmSourceProvider {
+    kind = "npm";
     name;
+    #config;
     constructor(config) {
+        this.#config = config;
         this.name = config.name ?? config.url ?? "npm";
     }
-    /** Content is indexed through the standard FTS5 pipeline. */
-    async search(_options) {
-        return { hits: [] };
+    async init(_ctx) {
+        // Resolution happens lazily in path(): until `sync()` runs there's no
+        // reliable on-disk path. Init is the registration handshake.
     }
-    /** Content is local files, shown via showLocal. */
-    async show(_ref, _view) {
-        throw new Error("NPM provider content is shown via local index");
+    path() {
+        if (this.#config.path)
+            return this.#config.path;
+        throw new ConfigError(`npm source "${this.name}" has no resolved content path — run \`akm update\` to sync it before indexing.`);
     }
-    canShow(_ref) {
-        return false;
-    }
-    async sync(config, options) {
-        const ref = npmRefFromConfig(config);
-        return syncNpmRef(ref, options);
-    }
-    getContentDir(config) {
-        if (config.path)
-            return config.path;
-        throw new ConfigError("npm stash entry missing resolved content path");
-    }
-    async remove(config) {
-        if (config.path && isDirectory(config.path)) {
-            // Remove the whole versioned cache dir if we know the parent layout.
-            const parent = path.dirname(config.path);
-            try {
-                fs.rmSync(parent, { recursive: true, force: true });
-            }
-            catch {
-                /* best-effort */
-            }
-        }
+    async sync() {
+        const ref = npmRefFromConfig(this.#config);
+        await syncNpmRef(ref);
     }
 }
-registerStashProvider("npm", (config) => new NpmStashProvider(config));
+registerSourceProvider("npm", (config) => new NpmSourceProvider(config));
 function npmRefFromConfig(config) {
     // Prefer an explicit ref-bearing field (set by akmAdd when persisting), else fall back
     // to options or url so the provider stays usable from a hand-rolled config.
@@ -69,7 +62,7 @@ function npmRefFromConfig(config) {
     return candidate.startsWith("npm:") ? candidate : `npm:${candidate}`;
 }
 /**
- * Fetch and extract an npm tarball, returning a populated `StashLockData`.
+ * Fetch and extract an npm tarball, returning a populated `SourceLockData`.
  *
  * Mirrors the historical `installRegistryRef()` path for npm sources:
  *   - resolve artifact URL + integrity from the npm registry
@@ -127,9 +120,17 @@ async function doSyncNpm(parsed, options) {
         verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
         integrity = await computeFileHash(archivePath);
         extractTarGzSecure(archivePath, extractedDir);
-        provisionalKitRoot = detectStashRoot(extractedDir);
+        const detectedProvisionalKitRoot = detectStashRoot(extractedDir);
+        if (!detectedProvisionalKitRoot) {
+            throw new UsageError(`Unable to detect a stash root in extracted npm package: ${resolved.ref}`);
+        }
+        provisionalKitRoot = detectedProvisionalKitRoot;
         installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
-        stashRoot = detectStashRoot(installRoot);
+        const detectedStashRoot = detectStashRoot(installRoot);
+        if (!detectedStashRoot) {
+            throw new UsageError(`Unable to detect a stash root after applying .akm-include configuration for npm package: ${resolved.ref}`);
+        }
+        stashRoot = detectedStashRoot;
     }
     catch (err) {
         // Clean up so stale or partial extractions don't cause false cache hits.
@@ -156,4 +157,4 @@ async function doSyncNpm(parsed, options) {
         syncedAt,
     };
 }
-export { NpmStashProvider };
+export { NpmSourceProvider };

package/dist/{stash-providers → sources/providers}/provider-utils.js

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../asset-spec";
-import { fetchWithRetry } from "../common";
-import { copyIncludedPaths, findNearestIncludeConfig } from "../stash-include";
+import { TYPE_DIRS } from "../../core/asset-spec";
+import { fetchWithRetry } from "../../core/common";
+import { copyIncludedPaths, findNearestIncludeConfig } from "../include";
 const REGISTRY_STASH_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
 /** Strip terminal control characters from untrusted strings. */
 export function sanitizeString(value, maxLength = 255) {

package/dist/{stash-providers → sources/providers}/sync-from-ref.js

@@ -9,8 +9,8 @@
  * `akmUpdate`) decide whether to run `auditInstallCandidate` on the
  * synced `contentDir` because they own the `--trust` flag.
  */
-import { UsageError } from "../errors";
-import { parseRegistryRef } from "../registry-resolve";
+import { UsageError } from "../../core/errors";
+import { parseRegistryRef } from "../../registry/resolve";
 import { detectStashRoot } from "./provider-utils";
 export async function syncFromRef(ref, options) {
     const parsed = parseRegistryRef(ref);

package/dist/{stash-providers → sources/providers}/tar-utils.js

@@ -6,15 +6,15 @@
  * and verify integrity hashes (SRI or hex shasum) before extraction.
  *
  * Extracted from `registry-install.ts` and shared by all syncable
- * providers that fetch tarballs (currently `NpmStashProvider` and the
+ * providers that fetch tarballs (currently `NpmSourceProvider` and the
  * registry index builder).
  */
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { isWithin } from "../common";
-import { warn } from "../warn";
+import { isWithin } from "../../core/common";
+import { warn } from "../../core/warn";
 /**
  * Verify an archive's integrity against a known hash. Throws and removes
  * the archive when verification fails.
@@ -103,11 +103,14 @@ function scanExtractedFiles(dir, root) {
                 throw new Error(`Post-extraction scan: symlink escapes destination directory: ${fullPath} -> ${target}`);
             }
         }
-        // Belt-and-suspenders: any regular entry whose resolved path lands outside
-        // the destination root is rejected, regardless of how its name looks. This
-        // catches anything the tar pre-validation missed.
-        if (!entry.isSymbolicLink() && !isWithin(fullPath, root)) {
-            throw new Error(`Post-extraction scan: entry escapes destination directory: ${fullPath}`);
+        // Belt-and-suspenders: check that the resolved path of regular entries
+        // stays within the destination root. This catches path traversal attempts
+        // via symlink TOCTOU, directory renames, or any other anomalies.
+        if (!entry.isSymbolicLink()) {
+            const resolved = path.resolve(fullPath);
+            if (!isWithin(resolved, root)) {
+                throw new Error(`Post-extraction scan: entry escapes destination directory: ${fullPath}`);
+            }
         }
         if (entry.isDirectory()) {
             scanExtractedFiles(fullPath, root);