akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/sources/provider-factory.js

@@ -1,7 +1,17 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { getSources } from "../core/config/config.js";
+/**
+ * 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.js";
 // ── Factory map ─────────────────────────────────────────────────────────────
 const registry = createProviderRegistry();
@@ -11,19 +21,3 @@ export function registerSourceProvider(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 getSources(config)) {
-        if (entry.enabled === false)
-            continue;
-        const factory = registry.resolve(entry.type);
-        if (factory) {
-            providers.push(factory(entry));
-        }
-    }
-    return providers;
-}

package/dist/sources/providers/filesystem.js

@@ -7,9 +7,8 @@ import { registerSourceProvider } from "../provider-factory.js";
 /**
  * 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.
+ * Implements {@link SourceProvider} with `{ name, kind, path }`. No `sync()`:
+ * content is the user's own directory, never refreshed by akm.
  */
 registerSourceProvider("filesystem", (entry) => {
     if (entry.type !== "filesystem") {

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

@@ -5,10 +5,11 @@ import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { isWithin } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { getRegistryCacheDir } from "../../core/paths.js";
 import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve.js";
-import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, } from "./provider-utils.js";
+import { applyAkmIncludeConfig, buildInstallCacheDir, detectStashRoot, isDirectory } from "./provider-utils.js";
 /**
  * Shared subprocess wrapper for `git` invocations. Disables git's interactive
  * terminal prompt so a missing credential never hangs the process.
@@ -20,12 +21,109 @@ export function runGit(args, options) {
         env: { ...process.env, ...options?.env, GIT_TERMINAL_PROMPT: "0" },
     });
 }
+/** Fetch and classify the current branch against its upstream without changing the worktree. */
+export function inspectGitUpstream(repoDir) {
+    const remotes = runGit(["-C", repoDir, "remote"]);
+    if (remotes.status !== 0)
+        throw new UsageError(`Cannot inspect Git remotes at ${repoDir}: ${remotes.stderr.trim()}`);
+    if (!remotes.stdout.trim())
+        return { hasRemote: false, ahead: 0, behind: 0 };
+    const fetch = runGit(["-C", repoDir, "fetch", "--prune"], { timeout: 120_000 });
+    if (fetch.status !== 0)
+        throw new UsageError(`Cannot refresh Git target at ${repoDir}: ${fetch.stderr.trim()}`);
+    const upstream = runGit(["-C", repoDir, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    if (upstream.status !== 0 || !upstream.stdout.trim()) {
+        throw new UsageError(`Git target at ${repoDir} has a remote but no upstream branch; configure one before writing.`);
+    }
+    const relation = gitRelation(repoDir, upstream.stdout.trim());
+    return { hasRemote: true, upstream: upstream.stdout.trim(), ...relation };
+}
 /**
- * Sync mode for a one-shot install ref (`akm add github:owner/repo` or
- * `akm add git:url`). Runs the clone → strip → include-filter pipeline that
- * historically lived in `installRegistryRef()`.
+ * Verify the actually-cloned HEAD matches the revision resolved before the
+ * clone ran (R-011). This is a presence/identity check only — full
+ * content-digest verification across install/update is separate, larger
+ * scope work. `expectedRevision` may be an annotated tag's OBJECT id (which
+ * `git ls-remote` reports, distinct from the commit it points to), so the
+ * comparison peels it (`^{commit}`) before comparing against HEAD; a plain
+ * commit SHA peels to itself.
  */
-export async function syncRegistryGitRef(ref, options) {
+export function verifyClonedRevision(cloneDir, url, expectedRevision) {
+    if (!expectedRevision)
+        return;
+    const head = runGit(["-C", cloneDir, "rev-parse", "HEAD"]);
+    if (head.status !== 0 || !head.stdout.trim()) {
+        throw new UsageError(`Failed to read cloned HEAD at ${cloneDir}: ${head.stderr.trim() || "rev-parse failed"}`);
+    }
+    const actual = head.stdout.trim();
+    const peeled = runGit(["-C", cloneDir, "rev-parse", `${expectedRevision}^{commit}`]);
+    const expectedCommit = peeled.status === 0 ? peeled.stdout.trim() : expectedRevision;
+    if (actual !== expectedCommit) {
+        throw new UsageError(`Cloned HEAD ${actual} at ${cloneDir} does not match the revision resolved from ${url} (${expectedRevision}); refusing to install a mismatched checkout.`);
+    }
+}
+function gitRelation(repoDir, target) {
+    const result = runGit(["-C", repoDir, "rev-list", "--left-right", "--count", `HEAD...${target}`]);
+    const match = result.stdout.trim().match(/^(\d+)\s+(\d+)$/);
+    if (result.status !== 0 || !match) {
+        throw new UsageError(`Cannot compare Git history at ${repoDir}: ${result.stderr.trim() || "unknown relation"}`);
+    }
+    return { ahead: Number(match[1]), behind: Number(match[2]) };
+}
+/** Reject a fast-forward that would replace an ignored, untracked local path. */
+export function assertNoIgnoredPathOverwrite(repoDir, targetRevision) {
+    const ignored = runGit(["-C", repoDir, "ls-files", "--others", "--ignored", "--exclude-standard", "-z"]);
+    if (ignored.status !== 0) {
+        throw new UsageError(`Cannot inspect ignored files at ${repoDir}: ${ignored.stderr.trim()}`);
+    }
+    const ignoredPaths = ignored.stdout.split("\0").filter(Boolean);
+    if (ignoredPaths.length === 0)
+        return;
+    const changed = runGit(["-C", repoDir, "diff", "--name-only", "--no-renames", "-z", "HEAD", targetRevision]);
+    if (changed.status !== 0) {
+        throw new UsageError(`Cannot inspect incoming Git paths at ${repoDir}: ${changed.stderr.trim()}`);
+    }
+    const changedPaths = changed.stdout.split("\0").filter(Boolean);
+    const conflict = ignoredPaths.find((ignoredPath) => changedPaths.some((changedPath) => changedPath === ignoredPath ||
+        changedPath.startsWith(`${ignoredPath}/`) ||
+        ignoredPath.startsWith(`${changedPath}/`)));
+    if (conflict) {
+        throw new UsageError(`Git update would overwrite ignored local path ${path.join(repoDir, conflict)}; move or remove it before update.`);
+    }
+}
+function normalizeRemoteUrl(value) {
+    return value
+        .trim()
+        .replace(/\/+$/, "")
+        .replace(/\.git$/i, "");
+}
+function replaceDirectory(stagedDir, destination) {
+    const backup = `${destination}.backup-${randomBytes(4).toString("hex")}`;
+    const hadDestination = fs.existsSync(destination);
+    if (hadDestination)
+        fs.renameSync(destination, backup);
+    try {
+        fs.renameSync(stagedDir, destination);
+    }
+    catch (error) {
+        if (hadDestination && fs.existsSync(backup))
+            fs.renameSync(backup, destination);
+        throw error;
+    }
+    if (hadDestination) {
+        try {
+            fs.rmSync(backup, { recursive: true, force: true });
+        }
+        catch {
+            // The new destination is live; a stale backup is safer than reporting a
+            // failed replacement after the swap already succeeded.
+        }
+    }
+}
+/**
+ * Materialize a Git install ref (`akm bundle add github:owner/repo` or
+ * `akm bundle add git:url`) through the clone, strip, and include-filter pipeline.
+ */
+export async function syncGitRef(ref, options) {
     const parsed = parseRegistryRef(ref);
     if (parsed.source === "github") {
         const githubRef = {
@@ -39,22 +137,40 @@ export async function syncRegistryGitRef(ref, options) {
         return { ...result, source: "github" };
     }
     if (parsed.source !== "git") {
-        throw new UsageError(`syncRegistryGitRef requires a git: or github: ref, got "${ref}"`);
+        throw new UsageError(`syncGitRef requires a git: or github: ref, got "${ref}"`);
     }
     return doSyncGit(parsed, options);
 }
 async function doSyncGit(parsed, options) {
+    validateGitUrl(parsed.url);
+    if (parsed.requestedRef)
+        validateGitRef(parsed.requestedRef);
     const resolved = await resolveRegistryArtifact(parsed);
     const syncedAt = (options?.now ?? new Date()).toISOString();
+    if (options?.writable && options.writableRoot) {
+        return syncExistingWritableCheckout(parsed, resolved, options.writableRoot, syncedAt, options.writableRequiredRoots);
+    }
     const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheDir();
-    const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, resolved.resolvedRevision);
+    const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, options?.writable ? "writable" : resolved.resolvedRevision);
     const cloneDir = path.join(cacheDir, "clone");
     const extractedDir = path.join(cacheDir, "extracted");
-    // Cache hit
-    if (!options?.force && isDirectory(extractedDir)) {
+    // Cache hit. Writable installs must remain real checkouts so every mutation
+    // can be committed; an older extracted snapshot is not eligible.
+    if (isDirectory(extractedDir) && (!options?.writable || isDirectory(path.join(extractedDir, ".git")))) {
+        if (options?.writable) {
+            const provisionalBundleRoot = detectStashRoot(extractedDir);
+            const installRoot = applyAkmIncludeConfig(provisionalBundleRoot, cacheDir, extractedDir) ?? provisionalBundleRoot;
+            if (installRoot !== provisionalBundleRoot) {
+                throw new UsageError("Writable Git installs do not support akm.include (package.json) filtered snapshots.");
+            }
+            return syncExistingWritableCheckout(parsed, resolved, detectStashRoot(installRoot), syncedAt, options.writableRequiredRoots);
+        }
         try {
-            const provisionalKitRoot = detectStashRoot(extractedDir);
-            const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+            if (options?.force) {
+                throw new Error("refresh read-only snapshot");
+            }
+            const provisionalBundleRoot = detectStashRoot(extractedDir);
+            const installRoot = applyAkmIncludeConfig(provisionalBundleRoot, cacheDir, extractedDir) ?? provisionalBundleRoot;
             const stashRoot = detectStashRoot(installRoot);
             if (stashRoot) {
                 return {
@@ -72,20 +188,20 @@ async function doSyncGit(parsed, options) {
                 };
             }
         }
-        catch {
+        catch (error) {
             // Cache invalid, re-clone
         }
     }
+    const cacheExisted = fs.existsSync(cacheDir);
     fs.mkdirSync(cacheDir, { recursive: true });
-    // Validate URL and ref before passing to git to prevent command injection
-    validateGitUrl(parsed.url);
-    if (parsed.requestedRef)
-        validateGitRef(parsed.requestedRef);
-    let provisionalKitRoot;
+    fs.rmSync(cloneDir, { recursive: true, force: true });
+    let provisionalBundleRoot;
     let installRoot;
     let stashRoot;
     try {
-        const cloneArgs = ["clone", "--depth", "1"];
+        const cloneArgs = ["clone"];
+        if (!options?.writable)
+            cloneArgs.push("--depth", "1");
         if (parsed.requestedRef) {
             cloneArgs.push("--branch", parsed.requestedRef);
         }
@@ -94,20 +210,40 @@ async function doSyncGit(parsed, options) {
         if (cloneResult.status !== 0) {
             throw new Error(classifyCloneFailure(parsed.url, cloneResult.stderr, cloneResult.error));
         }
-        // Copy contents to extracted dir without .git
-        fs.mkdirSync(extractedDir, { recursive: true });
-        copyDirectoryContents(cloneDir, extractedDir);
-        // Clean up the clone dir
-        fs.rmSync(cloneDir, { recursive: true, force: true });
-        provisionalKitRoot = detectStashRoot(extractedDir);
-        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        // R-011: `resolved.resolvedRevision` was resolved via a SEPARATE
+        // `git ls-remote` round-trip before this clone ran (resolveGitArtifact /
+        // resolveGithubArtifact in registry/resolve.ts) and was never checked
+        // against what actually got cloned. Verify it now, while `.git` still
+        // exists (the read-only branch below strips it).
+        verifyClonedRevision(cloneDir, parsed.url, resolved.resolvedRevision);
+        if (options?.writable) {
+            const branch = runGit(["-C", cloneDir, "branch", "--show-current"]);
+            if (branch.status !== 0 || !branch.stdout.trim()) {
+                throw new UsageError("Writable Git installs require a branch ref; tags and detached revisions are read-only.");
+            }
+            const stagedRoot = detectStashRoot(cloneDir);
+            if (applyAkmIncludeConfig(stagedRoot, cacheDir, cloneDir)) {
+                throw new UsageError("Writable Git installs do not support akm.include (package.json) filtered snapshots.");
+            }
+            replaceDirectory(cloneDir, extractedDir);
+        }
+        else {
+            // Read-only installs are immutable snapshots and do not retain Git metadata.
+            fs.rmSync(path.join(cloneDir, ".git"), { recursive: true, force: true });
+            replaceDirectory(cloneDir, extractedDir);
+        }
+        provisionalBundleRoot = detectStashRoot(extractedDir);
+        installRoot = applyAkmIncludeConfig(provisionalBundleRoot, cacheDir, extractedDir) ?? provisionalBundleRoot;
+        if (options?.writable && installRoot !== provisionalBundleRoot) {
+            throw new UsageError("Writable Git installs do not support akm.include (package.json) filtered snapshots.");
+        }
         stashRoot = detectStashRoot(installRoot);
     }
     catch (err) {
-        // Clean up the cache directory so stale or partially-cloned artifacts
-        // don't cause false cache hits on the next install attempt.
+        fs.rmSync(cloneDir, { recursive: true, force: true });
         try {
-            fs.rmSync(cacheDir, { recursive: true, force: true });
+            if (!cacheExisted)
+                fs.rmSync(cacheDir, { recursive: true, force: true });
         }
         catch {
             /* best-effort */
@@ -128,12 +264,123 @@ async function doSyncGit(parsed, options) {
         syncedAt,
     };
 }
+export function syncExistingWritableCheckout(parsed, resolved, contentRoot, syncedAt, requiredRoots = []) {
+    const root = path.resolve(contentRoot);
+    const repoResult = runGit(["-C", root, "rev-parse", "--show-toplevel"]);
+    if (repoResult.status !== 0 || !repoResult.stdout.trim()) {
+        throw new UsageError(`Writable Git install at ${root} is not a checkout; refusing to replace it because it may contain local work.`);
+    }
+    const repoDir = path.resolve(repoResult.stdout.trim());
+    if (!isWithin(root, repoDir)) {
+        throw new UsageError(`Writable Git content root ${root} resolves outside its checkout at ${repoDir}.`);
+    }
+    const remote = runGit(["-C", repoDir, "remote", "get-url", "origin"]);
+    if (remote.status !== 0 || normalizeRemoteUrl(remote.stdout) !== normalizeRemoteUrl(parsed.url)) {
+        throw new UsageError(`Writable Git install at ${root} points at a different origin; refusing to update or replace the checkout.`);
+    }
+    const status = runGit(["-C", repoDir, "status", "--porcelain"]);
+    if (status.status !== 0 || status.stdout.trim()) {
+        throw new UsageError(`Writable Git install at ${root} has uncommitted changes; commit or discard them before update.`);
+    }
+    if (parsed.requestedRef) {
+        const branch = runGit(["-C", repoDir, "branch", "--show-current"]);
+        const expectedBranch = parsed.requestedRef.replace(/^refs\/heads\//, "");
+        if (branch.status !== 0 || !branch.stdout.trim() || branch.stdout.trim() !== expectedBranch) {
+            throw new UsageError(`Writable Git install at ${root} is checked out on a different branch than requested ref "${parsed.requestedRef}".`);
+        }
+    }
+    const shallow = runGit(["-C", repoDir, "rev-parse", "--is-shallow-repository"]);
+    const fetchArgs = ["-C", repoDir, "fetch", "--prune", "--tags"];
+    if (shallow.status === 0 && shallow.stdout.trim() === "true")
+        fetchArgs.push("--unshallow");
+    fetchArgs.push("origin");
+    if (parsed.requestedRef)
+        fetchArgs.push(parsed.requestedRef);
+    const fetch = runGit(fetchArgs, { timeout: 120_000 });
+    if (fetch.status !== 0) {
+        throw new UsageError(`Writable Git install at ${root} could not fetch its expected origin; local work was preserved. ${fetch.stderr.trim()}`);
+    }
+    let targetRevision = resolved.resolvedRevision;
+    if (targetRevision) {
+        const resolvedTarget = runGit(["-C", repoDir, "rev-parse", "--verify", `${targetRevision}^{commit}`]);
+        if (resolvedTarget.status === 0)
+            targetRevision = resolvedTarget.stdout.trim();
+        else
+            targetRevision = undefined;
+    }
+    if (!targetRevision) {
+        const fallbackTarget = runGit([
+            "-C",
+            repoDir,
+            "rev-parse",
+            "--verify",
+            parsed.requestedRef ? "FETCH_HEAD" : "@{u}",
+        ]);
+        if (fallbackTarget.status !== 0 || !fallbackTarget.stdout.trim()) {
+            throw new UsageError(`Writable Git install at ${root} has no verifiable upstream revision.`);
+        }
+        targetRevision = fallbackTarget.stdout.trim();
+    }
+    const relation = gitRelation(repoDir, targetRevision);
+    if (relation.ahead > 0) {
+        throw new UsageError(`Writable Git install at ${root} has local commits that are not in the requested upstream revision; push or reconcile them before update.`);
+    }
+    assertNoIgnoredPathOverwrite(repoDir, targetRevision);
+    const rootsToPreserve = [...new Set([root, ...requiredRoots.map((candidate) => path.resolve(candidate))])];
+    for (const requiredRoot of rootsToPreserve) {
+        if (!isWithin(requiredRoot, repoDir)) {
+            throw new UsageError(`Configured Git component root ${requiredRoot} resolves outside ${repoDir}.`);
+        }
+        const relative = path.relative(repoDir, requiredRoot).replaceAll(path.sep, "/");
+        if (!relative)
+            continue;
+        const tree = runGit(["-C", repoDir, "ls-tree", "-d", "-z", "--name-only", targetRevision, "--", relative]);
+        const names = tree.stdout.split("\0").filter(Boolean);
+        if (tree.status !== 0 || !names.includes(relative)) {
+            throw new UsageError(`Writable Git update would remove configured content root ${requiredRoot}; the existing checkout was left unchanged.`);
+        }
+    }
+    if (relation.behind > 0) {
+        const statusBeforeMerge = runGit(["-C", repoDir, "status", "--porcelain"]);
+        if (statusBeforeMerge.status !== 0 || statusBeforeMerge.stdout.trim()) {
+            throw new UsageError(`Writable Git install at ${root} changed while its update was prepared; local work was preserved.`);
+        }
+        assertNoIgnoredPathOverwrite(repoDir, targetRevision);
+        const merge = runGit(["-C", repoDir, "merge", "--ff-only", "--no-overwrite-ignore", targetRevision], {
+            timeout: 120_000,
+        });
+        if (merge.status !== 0) {
+            throw new UsageError(`Writable Git install at ${root} cannot fast-forward; local commits were preserved. ${merge.stderr.trim()}`);
+        }
+    }
+    for (const requiredRoot of rootsToPreserve) {
+        if (!isDirectory(requiredRoot)) {
+            throw new UsageError(`Writable Git update did not preserve configured content root ${requiredRoot}.`);
+        }
+    }
+    const head = runGit(["-C", repoDir, "rev-parse", "HEAD"]);
+    return {
+        id: resolved.id,
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+        resolvedVersion: resolved.resolvedVersion,
+        resolvedRevision: head.status === 0 ? head.stdout.trim() : targetRevision,
+        contentDir: root,
+        cacheDir: repoDir,
+        extractedDir: repoDir,
+        writable: true,
+        syncedAt,
+    };
+}
 export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
     // Stage the clone into a sibling temp dir so that a failed clone never
     // destroys a previously-valid destDir (e.g. when the remote is temporarily
     // unreachable and we have a valid cached copy).
     const tmpDir = `${destDir}.tmp-${randomBytes(4).toString("hex")}`;
-    const args = ["clone", "--depth", "1"];
+    const args = ["clone"];
+    if (!writable)
+        args.push("--depth", "1");
     if (ref)
         args.push("--branch", ref);
     args.push(cloneUrl, tmpDir);
@@ -150,10 +397,7 @@ export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
             if (fs.existsSync(gitDir))
                 fs.rmSync(gitDir, { recursive: true, force: true });
         }
-        // Swap: remove the old destDir (if any) then atomically rename tmpDir into place.
-        if (fs.existsSync(destDir))
-            fs.rmSync(destDir, { recursive: true, force: true });
-        fs.renameSync(tmpDir, destDir);
+        replaceDirectory(tmpDir, destDir);
     }
     catch (err) {
         // Post-clone steps failed — clean up the temp dir to avoid orphaned dirs.
@@ -164,7 +408,7 @@ export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
 // ── Clone-failure classification (#487) ─────────────────────────────────────
 /**
  * Translate git's stderr into an actionable message. Without this, a user
- * who passes a nonexistent or private repo to `akm add` sees:
+ * who passes a nonexistent or private repo to `akm bundle add` sees:
  *
  *   "could not read Username for 'https://github.com': No such device or
  *    address"

package/dist/sources/providers/git-provider.js

@@ -11,7 +11,7 @@ import { getRegistryIndexCacheDir } from "../../core/paths.js";
 import { validateGitUrl } from "../../registry/resolve.js";
 import { withFreshnessCache } from "../freshness.js";
 import { registerSourceProvider } from "../provider-factory.js";
-import { cloneRepo, runGit, syncRegistryGitRef } from "./git-install.js";
+import { assertNoIgnoredPathOverwrite, cloneRepo, inspectGitUpstream, runGit } from "./git-install.js";
 import { sanitizeString } from "./provider-utils.js";
 /** Cache TTL before refreshing the mirrored repo (12 hours). */
 const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
@@ -19,12 +19,11 @@ const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 /**
  * 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 }`.
+ * cache directory. Implements the {@link SourceProvider} interface.
  *
  * 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`.
+ * `show`. Install refs are materialized by `syncFromRef`; this provider only
+ * refreshes configured Git sources.
  */
 export class GitSourceProvider {
     kind = "git";
@@ -37,23 +36,11 @@ export class GitSourceProvider {
     }
     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(options) {
-        // Two execution modes:
-        //   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 (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), { force: options?.force });
-            return;
-        }
         await syncMirroredRepo(this.#config, { force: options?.force });
     }
 }
@@ -88,6 +75,7 @@ export async function ensureGitMirror(repo, cachePaths, options) {
         ttlMs: CACHE_TTL_MS,
         staleMs: CACHE_STALE_MS,
         force: options?.force === true,
+        allowStaleOnRefreshFailure: !(options?.force === true && writable),
         isUsable: () => !requireRepoDir || hasExtractedRepo(cachePaths.repoDir),
         refresh: async () => {
             fs.mkdirSync(cachePaths.rootDir, { recursive: true });
@@ -134,12 +122,26 @@ export async function syncMirroredRepo(config, options) {
     };
 }
 function pullRepo(repoDir) {
-    const result = runGit(["-C", repoDir, "pull", "--ff-only"], {
-        timeout: 120_000,
-    });
-    if (result.status !== 0) {
-        const err = result.stderr?.trim() || result.error?.message || "unknown error";
-        throw new Error(`Failed to pull ${repoDir}: ${err}`);
+    const status = runGit(["-C", repoDir, "status", "--porcelain"]);
+    if (status.status !== 0 || status.stdout.trim()) {
+        throw new UsageError(`Writable Git source at ${repoDir} has uncommitted changes; refusing to update it.`);
+    }
+    const relation = inspectGitUpstream(repoDir);
+    if (relation.ahead > 0) {
+        throw new UsageError(`Writable Git source at ${repoDir} has unpushed commits; refusing to update it.`);
+    }
+    if (relation.behind > 0 && relation.upstream) {
+        const statusBeforeMerge = runGit(["-C", repoDir, "status", "--porcelain"]);
+        if (statusBeforeMerge.status !== 0 || statusBeforeMerge.stdout.trim()) {
+            throw new UsageError(`Writable Git source at ${repoDir} changed while its update was prepared; refusing to merge.`);
+        }
+        assertNoIgnoredPathOverwrite(repoDir, relation.upstream);
+        const merge = runGit(["-C", repoDir, "merge", "--ff-only", "--no-overwrite-ignore", relation.upstream], {
+            timeout: 120_000,
+        });
+        if (merge.status !== 0) {
+            throw new Error(`Failed to fast-forward ${repoDir}: ${merge.stderr?.trim() || "unknown error"}`);
+        }
     }
 }
 function hasExtractedRepo(repoDir) {