dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/application/snapshot-cache.js

@@ -0,0 +1,160 @@
+/**
+ * Discovery caching: one scan cache shared by every dimension, plus a
+ * freshness-bounded snapshot per dimension.
+ *
+ * Install / enable / surface toggles re-derive a snapshot from cached
+ * discovery (a cheap mapping) instead of re-walking every checkout — a full
+ * rescan of a 2,500-suite catalog costs ~1s and UI mutations happen in bursts.
+ * Content-changing mutations (add / update / remove / adopt / refresh /
+ * acquire) clear every cached discovery generation; the TTL bounds staleness
+ * for in-place working-tree edits of local sources.
+ */
+import { join, resolve } from 'node:path';
+import { resolveProjectRoot, STATE_FILE_NAME } from '../catalog/paths.js';
+import { discoverSourceListWithNotes } from '../catalog/source-catalog.js';
+import { loadState } from '../runtime/state-store.js';
+export const SCAN_CACHE_TTL_MS = 30_000;
+const SCAN_CACHE_MAX_ENTRIES = 8;
+export class SnapshotCache {
+    host;
+    ttls;
+    scanCache = new Map();
+    scanPromises = new Map();
+    userSnapshot;
+    userSnapshotExpiresAt = 0;
+    userSnapshotPromise;
+    /** Project-dimension snapshots keyed by project root, with TTL freshness. */
+    projectSnapshots = new Map();
+    projectSnapshotPromises = new Map();
+    constructor(host, ttls) {
+        this.host = host;
+        this.ttls = ttls;
+    }
+    /** Read one coherent user-dimension snapshot, reusing in-flight discovery. */
+    async readUserCatalog() {
+        // TTL 0 disables snapshot caching: every read observes fresh discovery,
+        // mirroring the project dimension's caching-disabled semantics.
+        if (this.ttls.user <= 0)
+            return this.build(this.host.state, 'user', this.host.userRoot);
+        if (this.userSnapshot !== undefined && Date.now() < this.userSnapshotExpiresAt)
+            return this.userSnapshot;
+        if (this.userSnapshotPromise !== undefined)
+            return this.userSnapshotPromise;
+        const revision = this.host.revision;
+        const generation = this.host.scanGeneration;
+        const promise = this.build(this.host.state, 'user', this.host.userRoot)
+            .then(snapshot => {
+            if (revision === this.host.revision && generation === this.host.scanGeneration) {
+                this.userSnapshot = snapshot;
+                this.userSnapshotExpiresAt = Date.now() + this.ttls.user;
+            }
+            return snapshot;
+        })
+            .finally(() => {
+            if (this.userSnapshotPromise === promise)
+                this.userSnapshotPromise = undefined;
+        });
+        this.userSnapshotPromise = promise;
+        return promise;
+    }
+    /** Read one coherent project-dimension snapshot for a workspace cwd. */
+    async readProjectCatalog(cwd) {
+        const projectRoot = await resolveProjectRoot(cwd);
+        // A cwd with no `.git` ancestor resolves to itself as its own project root,
+        // so a session started in the harness home lands on the user dimension root.
+        // That directory is the user's catalog, not a project's: reading it would
+        // present every user-level suite as a project suite of that one session.
+        if (resolve(projectRoot) === resolve(this.host.userRoot)) {
+            return { revision: this.host.revision, sources: [], suites: [], enabledSuites: [] };
+        }
+        if (this.ttls.project <= 0)
+            return this.buildProjectSnapshot(projectRoot);
+        const cached = this.projectSnapshots.get(projectRoot);
+        if (cached !== undefined && cached.expiresAt > Date.now())
+            return cached.snapshot;
+        const inFlight = this.projectSnapshotPromises.get(projectRoot);
+        if (inFlight !== undefined)
+            return inFlight;
+        const revision = this.host.revision;
+        const generation = this.host.scanGeneration;
+        const promise = this.buildProjectSnapshot(projectRoot)
+            .then(snapshot => {
+            if (revision === this.host.revision && generation === this.host.scanGeneration) {
+                this.projectSnapshots.set(projectRoot, { snapshot, expiresAt: Date.now() + this.ttls.project });
+            }
+            return snapshot;
+        })
+            .finally(() => {
+            if (this.projectSnapshotPromises.get(projectRoot) === promise)
+                this.projectSnapshotPromises.delete(projectRoot);
+        });
+        this.projectSnapshotPromises.set(projectRoot, promise);
+        return promise;
+    }
+    /** One snapshot for a dimension root, reusing cached discovery when it is fresh. */
+    async build(state, dimension, dimensionRoot, skipScanCache = false) {
+        const fingerprint = JSON.stringify([dimension, dimensionRoot, state.sources, this.host.scanProjectLayouts]);
+        const cached = this.scanCache.get(fingerprint);
+        // The user snapshot's TTL also bounds scan reuse: a snapshot rebuild that
+        // replays a 30s scan cache would silently outlive its own staleness bound.
+        const scanCacheTtl = dimension === 'user' ? Math.min(this.ttls.user, SCAN_CACHE_TTL_MS) : SCAN_CACHE_TTL_MS;
+        const cacheFresh = !skipScanCache && cached !== undefined && Date.now() - cached.at < scanCacheTtl;
+        let discovered;
+        let scanNotes;
+        if (cacheFresh && cached !== undefined) {
+            discovered = cached.discovered;
+            scanNotes = cached.scanNotes;
+        }
+        else {
+            const generation = this.host.scanGeneration;
+            let pending = this.scanPromises.get(fingerprint);
+            if (pending === undefined) {
+                pending = discoverSourceListWithNotes(state.sources, dimension, dimensionRoot, this.host.scanProjectLayouts);
+                this.scanPromises.set(fingerprint, pending);
+            }
+            let result;
+            try {
+                result = await pending;
+            }
+            finally {
+                if (this.scanPromises.get(fingerprint) === pending)
+                    this.scanPromises.delete(fingerprint);
+            }
+            discovered = result.suites;
+            scanNotes = result.scanNotes;
+            // A scan started before a content mutation must not repopulate its cache.
+            if (generation === this.host.scanGeneration) {
+                if (this.scanCache.size >= SCAN_CACHE_MAX_ENTRIES)
+                    this.scanCache.clear();
+                this.scanCache.set(fingerprint, { at: Date.now(), discovered, scanNotes });
+            }
+        }
+        const suites = this.host.project(discovered, state, dimension);
+        return {
+            revision: this.host.revision,
+            sources: [...state.sources],
+            suites,
+            enabledSuites: suites.filter(suite => suite.enabled),
+            ...(Object.keys(scanNotes).length > 0 ? { scanNotes } : {})
+        };
+    }
+    /** Drop every cached dimension snapshot and its in-flight dedupe slot. */
+    invalidateSnapshots() {
+        this.userSnapshot = undefined;
+        this.userSnapshotExpiresAt = 0;
+        this.userSnapshotPromise = undefined;
+        this.projectSnapshots.clear();
+        this.projectSnapshotPromises.clear();
+    }
+    /** Drop cached discovery and its in-flight dedupe slots. */
+    invalidateScans() {
+        this.scanCache.clear();
+        this.scanPromises.clear();
+    }
+    async buildProjectSnapshot(projectRoot) {
+        const state = await loadState(join(projectRoot, STATE_FILE_NAME));
+        // TTL 0 means caching is disabled for this dimension: bypass the scan
+        // cache so every read observes the working tree as it stands.
+        return this.build(state, 'project', projectRoot, this.ttls.project <= 0);
+    }
+}

package/lib/application/source-store.js

@@ -0,0 +1,521 @@
+/**
+ * Source acquisition and source CRUD.
+ *
+ * A source is a configured Git repository, archive URL, or local directory the
+ * catalog reads suites from. This module owns everything that touches the
+ * `.sources/` storage: adoption of pre-existing checkouts, id selection,
+ * clone/archive/download, refresh, removal, and the progress state the market
+ * page polls while a long acquisition runs.
+ */
+import { mkdir, readdir, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { archiveInstall } from '../catalog/archive.js';
+import { gitClone, gitCurrentBranch, gitHead, gitRemoteUrl, gitRemove, gitSetRemoteUrl, gitSync } from '../catalog/git.js';
+import { repoName } from '../catalog/manifests.js';
+import { deriveSourceIdCandidates, expandHome, sanitizeId, sourceCheckoutDir, sourcesDir } from '../catalog/paths.js';
+import { isDirectory, pathExists } from '../catalog/fs-probes.js';
+import { canonicalGitUrl } from '../catalog/scan-resolvers.js';
+import { readLocalePreference } from '../runtime/host-locale.js';
+import { githubCloneUrl, resolveRegion } from '../runtime/regions.js';
+import { resolveSourceKind } from '../model/types.js';
+export class SourceStore {
+    context;
+    ports;
+    headCache = new Map();
+    /** Progress snapshot of the source mutation currently in flight. */
+    currentSourceState;
+    constructor(context, ports) {
+        this.context = context;
+        this.ports = ports;
+    }
+    /**
+     * Add a source and acquire it immediately (clone, download, or in-place).
+     *
+     * Git sources with an already-present checkout whose `origin` matches the
+     * input URL are adopted in place — the manual-clone repair path — so no
+     * second clone is made and no `-2` suffixed id is invented. Adopted
+     * checkouts are never deleted on source removal.
+     */
+    async add(input) {
+        return this.context.enqueue(async () => {
+            const kind = input.local === true ? 'local' : resolveSourceKind({ url: input.url, kind: input.kind });
+            if (kind === 'git') {
+                // Adoption first: a pre-existing checkout with a matching origin URL
+                // is registered as-is, skipping the clone entirely.
+                const adoptable = await this.findAdoptableCheckout(input.url, deriveSourceIdCandidates(input.url));
+                if (adoptable !== undefined) {
+                    const source = {
+                        id: adoptable,
+                        url: input.url,
+                        ...(input.branch === undefined ? {} : { branch: input.branch }),
+                        kind: 'git',
+                        adopted: true
+                    };
+                    const head = await tryHead(sourceCheckoutDir(this.context.userRoot, adoptable));
+                    if (head !== undefined)
+                        this.headCache.set(source.id, head);
+                    await this.context.commit({ ...this.context.state, sources: [...this.context.state.sources, source] });
+                    await this.context.notifyChanged();
+                    return source;
+                }
+            }
+            const baseId = await this.pickSourceId(deriveSourceIdCandidates(input.url), kind === 'local');
+            const source = {
+                id: baseId,
+                url: input.url,
+                ...(input.branch === undefined ? {} : { branch: input.branch }),
+                ...(kind === 'local' ? { local: true } : { kind }),
+                ...(input.kind === 'archive' && input.sha256 !== undefined && input.sha256 !== '' ? { sha256: input.sha256 } : {})
+            };
+            let checkout = this.checkoutPath(source);
+            if (kind === 'local') {
+                if (!(await isDirectory(checkout)))
+                    throw new Error(`local source directory ${checkout} is missing`);
+            }
+            else {
+                this.beginSourceState(baseId, kind === 'archive' ? 'downloading' : 'cloning', false);
+                try {
+                    const lock = await this.acquire(source);
+                    if (lock !== undefined)
+                        this.headCache.set(source.id, lock);
+                }
+                catch (error) {
+                    this.endSourceState();
+                    throw error;
+                }
+                this.updateSourceStep('reading');
+            }
+            // The repo's own manifest names the source; move the checkout along so
+            // the registered id and its `.sources/` directory stay coherent. URL
+            // derived candidates stay as readable fallbacks before numeric suffixes.
+            const named = [...new Set([sanitizeId(await repoName(checkout)), ...deriveSourceIdCandidates(input.url)])];
+            const finalId = await this.pickSourceId(named, kind === 'local', kind === 'local' ? undefined : checkout);
+            if (kind !== 'local' && finalId !== baseId) {
+                const targetDir = sourceCheckoutDir(this.context.userRoot, finalId);
+                await rename(checkout, targetDir);
+                checkout = targetDir;
+            }
+            source.id = finalId;
+            if (resolveSourceKind(source) === 'git') {
+                const head = await tryHead(checkout);
+                if (head !== undefined)
+                    this.headCache.set(source.id, head);
+            }
+            this.endSourceState();
+            await this.context.commit({ ...this.context.state, sources: [...this.context.state.sources, source] });
+            await this.context.notifyChanged();
+            return source;
+        });
+    }
+    /** Register one unmanaged `.sources/` checkout as a source without touching its files. */
+    async adopt(id) {
+        return this.context.enqueue(async () => {
+            if (this.context.state.sources.some(source => source.id === id))
+                throw new Error(`source "${id}" is already registered`);
+            // The id becomes one path segment under `.sources/`: only flat safe
+            // names qualify. Anything else (separators, `..`, leading dots) could
+            // traverse out of the checkouts root and register an outside directory.
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id) || id.includes('..')) {
+                throw new Error(`invalid checkout id "${id}" — use letters, digits, dots, dashes, or underscores`);
+            }
+            const dir = sourceCheckoutDir(this.context.userRoot, id);
+            if (!(await isDirectory(dir)))
+                throw new Error(`no checkout directory at ${dir}`);
+            let source;
+            try {
+                const origin = await gitRemoteUrl(dir);
+                source = { id, url: origin, kind: 'git', adopted: true };
+                const head = await tryHead(dir);
+                if (head !== undefined)
+                    this.headCache.set(id, head);
+            }
+            catch {
+                // Not a git checkout: read it in place, like a local source.
+                source = { id, url: dir, local: true, adopted: true };
+            }
+            await this.context.commit({ ...this.context.state, sources: [...this.context.state.sources, source] });
+            await this.context.notifyChanged();
+            return source;
+        });
+    }
+    /** Unmanaged `.sources/` checkouts: present on disk, absent from state. */
+    async unmanaged() {
+        const checkoutRoot = sourcesDir(this.context.userRoot);
+        let entries;
+        try {
+            entries = await readdir(checkoutRoot, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const registered = new Set(this.context.state.sources.map(source => source.id));
+        const unmanaged = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.') || registered.has(entry.name))
+                continue;
+            const dir = join(checkoutRoot, entry.name);
+            try {
+                unmanaged.push({ id: entry.name, url: await gitRemoteUrl(dir) });
+            }
+            catch {
+                unmanaged.push({ id: entry.name });
+            }
+        }
+        return unmanaged;
+    }
+    /** Update one source's URL, branch, kind, or archive digest. */
+    async update(sourceId, patch) {
+        return this.context.enqueue(async () => {
+            const index = this.context.state.sources.findIndex(source => source.id === sourceId);
+            const current = this.context.state.sources[index];
+            if (current === undefined)
+                throw new Error(`unknown source "${sourceId}"`);
+            const nextLocal = patch.local !== undefined ? patch.local : current.local === true;
+            // A local source carries the legacy flag only; `kind` stays unwritten
+            // so the persisted shape matches the pre-kind records.
+            const nextKind = nextLocal ? undefined : (patch.kind ?? current.kind);
+            const next = {
+                id: sourceId,
+                url: patch.url ?? current.url,
+                ...(patch.branch !== undefined ? { branch: patch.branch } : current.branch === undefined ? {} : { branch: current.branch }),
+                ...(nextLocal ? { local: true } : {}),
+                ...(nextKind === undefined ? {} : { kind: nextKind }),
+                ...(patch.sha256 !== undefined ? (patch.sha256 === '' ? {} : { sha256: patch.sha256 }) : current.sha256 === undefined ? {} : { sha256: current.sha256 }),
+                ...(current.adopted === true ? { adopted: true } : {})
+            };
+            const urlChanged = patch.url !== undefined && patch.url !== current.url;
+            // A URL change invalidates the old checkout — except for adopted (user
+            // cloned) and local sources, whose directories we never own.
+            if (urlChanged && current.local !== true && current.adopted !== true) {
+                this.headCache.delete(sourceId);
+                await gitRemove(sourceCheckoutDir(this.context.userRoot, sourceId));
+            }
+            await this.context.commit({ ...this.context.state, sources: this.context.state.sources.map((source, i) => (i === index ? next : source)) });
+            await this.context.notifyChanged();
+        });
+    }
+    /**
+     * Remove a source and its install entries. `deleteCheckout` (the UI's
+     * "also delete the managed market directory" option) physically removes the
+     * `.sources/<id>` checkout — including an adopted one, since a directory
+     * under `.sources` is manager-owned storage. A `local` source whose URL
+     * points outside `.sources` is registration-only: its directory is never
+     * touched. Deleting the checkout is what keeps a removed source from
+     * reappearing as an unmanaged entry.
+     */
+    async remove(sourceId, deleteCheckout = false) {
+        return this.context.enqueue(async () => {
+            const source = this.context.state.sources.find(entry => entry.id === sourceId);
+            await this.context.commit({
+                ...this.context.state,
+                sources: this.context.state.sources.filter(entry => entry.id !== sourceId),
+                installed: Object.fromEntries(Object.entries(this.context.state.installed).filter(([key]) => !key.startsWith(`${sourceId}/`)))
+            });
+            this.headCache.delete(sourceId);
+            // A checkout under `.sources` is manager-owned even when it was first
+            // discovered/adopted. Only an explicit local path points outside the
+            // manager's storage and must remain untouched.
+            const externalLocal = source?.local === true && source.url !== sourceCheckoutDir(this.context.userRoot, sourceId);
+            if (!externalLocal && deleteCheckout)
+                await gitRemove(sourceCheckoutDir(this.context.userRoot, sourceId));
+            await this.context.notifyChanged();
+        });
+    }
+    /** Refresh one source checkout, or every source when sourceId is omitted. */
+    async refresh(sourceId) {
+        return this.context.enqueue(async () => {
+            const targets = sourceId === undefined ? this.context.state.sources : this.context.state.sources.filter(source => source.id === sourceId);
+            for (const source of targets) {
+                const kind = resolveSourceKind(source);
+                if (kind === 'local') {
+                    if (!(await isDirectory(expandHome(source.url))))
+                        throw new Error(`local source directory ${expandHome(source.url)} is missing`);
+                    continue;
+                }
+                const checkout = sourceCheckoutDir(this.context.userRoot, source.id);
+                this.headCache.delete(source.id);
+                if (kind === 'archive') {
+                    // Re-download and swap; the fresh digest becomes the lock value.
+                    const lock = await this.acquire(source);
+                    if (lock !== undefined)
+                        this.headCache.set(source.id, lock);
+                    continue;
+                }
+                // Adopted checkouts are user-owned working trees: no `reset --hard`
+                // (it would destroy uncommitted work), and no re-acquire either —
+                // a broken HEAD means the user repairs the checkout, not that the
+                // manager may clone or extract over their directory.
+                if (source.adopted === true) {
+                    try {
+                        this.headCache.set(source.id, await gitHead(checkout));
+                    }
+                    catch {
+                        // A failed HEAD read means the next overview re-probes.
+                    }
+                    continue;
+                }
+                try {
+                    await gitHead(checkout);
+                }
+                catch {
+                    const lock = await this.acquire(source);
+                    if (lock !== undefined) {
+                        this.headCache.set(source.id, lock);
+                    }
+                    else {
+                        try {
+                            this.headCache.set(source.id, await gitHead(checkout));
+                        }
+                        catch {
+                            // A failed HEAD read means the next overview re-probes.
+                        }
+                    }
+                    continue;
+                }
+                // Shallow-friendly sync: fetch depth 1 into FETCH_HEAD, hard reset.
+                const branch = source.branch ?? (await gitCurrentBranch(checkout).catch(() => undefined));
+                // Keep origin on the region's route: a clone made before a region
+                // switch (or an explicit flip) re-points origin so the fetch follows.
+                // Only origins this plugin itself wrote (the direct or proxied
+                // source.url) are re-pointed — a foreign remote is left untouched.
+                if (source.kind === 'git' || (source.kind === undefined && source.local !== true)) {
+                    try {
+                        const region = resolveRegion(await this.ports.downloadRegion(), await readLocalePreference());
+                        const routed = githubCloneUrl(region, source.url);
+                        const origin = await gitRemoteUrl(checkout);
+                        if (origin !== routed && (origin === source.url || origin === githubCloneUrl('china', source.url))) {
+                            await gitSetRemoteUrl(checkout, routed);
+                        }
+                    }
+                    catch {
+                        // Origin reconciliation is best effort; plain sync still runs.
+                    }
+                }
+                await gitSync(checkout, branch, this.context.git);
+                try {
+                    this.headCache.set(source.id, await gitHead(checkout));
+                }
+                catch {
+                    // A failed HEAD read means the next overview re-probes.
+                }
+            }
+            await this.context.notifyChanged();
+        });
+    }
+    /** Progress snapshot for the progress route. */
+    progress() {
+        const state = this.currentSourceState;
+        return state === undefined ? { active: false, sourceId: '', step: '' } : { active: true, sourceId: state.sourceId, step: state.step };
+    }
+    /**
+     * Checkout status of one source for the market overview. A mutation owning
+     * the source right now short-circuits the probe: a Git read raced against
+     * that mutation's checkout would report a half-swapped directory.
+     */
+    async describeCheckout(source) {
+        const inFlight = this.currentSourceState?.sourceId === source.id ? this.currentSourceState : undefined;
+        const checkout = this.checkoutPath(source);
+        const kind = resolveSourceKind(source);
+        let cloned = false;
+        let lockCommit;
+        let error;
+        if (kind === 'local') {
+            cloned = await isDirectory(checkout);
+            if (!cloned)
+                error = `local source directory ${checkout} is missing`;
+        }
+        else if (kind === 'archive') {
+            cloned = await isDirectory(checkout);
+            lockCommit = this.headCache.get(source.id);
+        }
+        else if (inFlight !== undefined) {
+            // A mutation owns this source right now: do not race git against its checkout.
+            cloned = inFlight.cloned || (await isDirectory(checkout));
+            lockCommit = inFlight.head;
+        }
+        else {
+            const cachedHead = this.headCache.get(source.id);
+            if (cachedHead !== undefined && (await isDirectory(checkout))) {
+                cloned = true;
+                lockCommit = cachedHead;
+            }
+            else {
+                try {
+                    lockCommit = await gitHead(checkout);
+                    cloned = true;
+                    this.headCache.set(source.id, lockCommit);
+                }
+                catch {
+                    // Not cloned yet or a broken checkout; refresh reports the actionable error.
+                }
+            }
+        }
+        return { cloned, ...(lockCommit === undefined ? {} : { lockCommit }), ...(error === undefined ? {} : { error }) };
+    }
+    /** Per-source rows of the market overview for one user-dimension snapshot. */
+    async overviewRows(snapshot) {
+        const rows = [];
+        for (const source of snapshot.sources) {
+            const status = await this.describeCheckout(source);
+            const sourceSuites = snapshot.suites.filter(suite => suite.sourceId === source.id);
+            const scanNotes = snapshot.scanNotes?.[source.id];
+            rows.push({
+                id: source.id,
+                url: source.url,
+                ...(source.branch === undefined ? {} : { branch: source.branch }),
+                ...(source.local === true ? { local: true } : {}),
+                kind: resolveSourceKind(source),
+                ...(source.adopted === true ? { adopted: true } : {}),
+                cloned: status.cloned,
+                ...(status.lockCommit === undefined ? {} : { lockCommit: status.lockCommit }),
+                ...(status.error === undefined ? {} : { error: status.error }),
+                ...(scanNotes === undefined ? {} : { scanNotes }),
+                suiteIds: sourceSuites.map(suite => suite.id)
+            });
+        }
+        return rows;
+    }
+    /**
+     * Acquire one source's content by kind: clone (git), download+extract
+     * (archive), or an in-place existence check (local). Returns a lock value
+     * when the acquisition yields one (archive SHA-256, tarball fallback
+     * digest); git HEAD is read separately by the callers.
+     */
+    async acquire(source) {
+        const kind = resolveSourceKind(source);
+        if (kind === 'local') {
+            if (!(await isDirectory(expandHome(source.url))))
+                throw new Error(`local source directory ${expandHome(source.url)} is missing`);
+            return undefined;
+        }
+        const checkout = sourceCheckoutDir(this.context.userRoot, source.id);
+        await mkdir(sourcesDir(this.context.userRoot), { recursive: true });
+        if (kind === 'archive') {
+            const { sha256 } = await archiveInstall(source.url, checkout, {
+                ...(source.sha256 === undefined ? {} : { sha256: source.sha256 }),
+                ...(this.context.git.timeoutMs === undefined ? {} : { timeoutMs: this.context.git.timeoutMs }),
+                ...(this.context.git.allowHttpArchives === true ? { allowHttp: true } : {})
+            });
+            return sha256;
+        }
+        try {
+            // The region routes github.com clones through the China mirror prefix;
+            // the proxied URL becomes `origin`, so refreshes follow the same route.
+            const region = resolveRegion(await this.ports.downloadRegion(), await readLocalePreference());
+            await gitClone(githubCloneUrl(region, source.url), source.branch, checkout, this.context.git);
+            return undefined;
+        }
+        catch (error) {
+            if (this.context.git.fallbackTarball !== true)
+                throw error;
+            const tarballUrl = codeloadTarballUrl(source.url, source.branch);
+            if (tarballUrl === undefined)
+                throw error;
+            // The codeload URL ends in a branch path, not `.tar.gz`, so the format
+            // must be stated explicitly — extension detection cannot see it.
+            const { sha256 } = await archiveInstall(tarballUrl, checkout, {
+                ...(this.context.git.timeoutMs === undefined ? {} : { timeoutMs: this.context.git.timeoutMs }),
+                format: 'targz'
+            });
+            return sha256;
+        }
+    }
+    /** The filesystem location of one source. */
+    checkoutPath(source) {
+        return source.local === true ? expandHome(source.url) : sourceCheckoutDir(this.context.userRoot, source.id);
+    }
+    /** The last HEAD this store observed for one source, when it cached one. */
+    knownHead(sourceId) {
+        return this.headCache.get(sourceId);
+    }
+    /**
+     * First candidate id whose `.sources/` checkout already exists and whose
+     * `origin` remote matches the input URL (canonical-form equality) — the
+     * signature of a manual clone of the very same repository. Registered ids
+     * and checkouts of differently-origined directories never adopt.
+     */
+    async findAdoptableCheckout(url, candidates) {
+        const registered = new Set(this.context.state.sources.map(source => source.id));
+        for (const candidate of candidates) {
+            if (registered.has(candidate))
+                continue;
+            const dir = sourceCheckoutDir(this.context.userRoot, candidate);
+            if (!(await isDirectory(dir)))
+                continue;
+            let origin;
+            try {
+                origin = await gitRemoteUrl(dir);
+            }
+            catch {
+                continue;
+            }
+            if (origin !== '' && canonicalGitUrl(origin) === canonicalGitUrl(url))
+                return candidate;
+        }
+        return undefined;
+    }
+    /**
+     * First candidate id not claimed by a registered source; for git candidates
+     * the checkout directory must also be free, so a stale or foreign directory
+     * under `.sources/` is never cloned over (it would fail `git clone` with a
+     * confusing "destination exists" error). `ownedCheckout` marks the directory
+     * the in-flight mutation already controls, keeping a rename onto it legal.
+     * Local sources skip the disk check: they read their own path in place and
+     * never occupy `.sources/`.
+     */
+    async pickSourceId(candidates, skipDisk, ownedCheckout) {
+        const free = async (id) => {
+            if (this.context.state.sources.some(source => source.id === id))
+                return false;
+            if (skipDisk)
+                return true;
+            const dir = sourceCheckoutDir(this.context.userRoot, id);
+            return dir === ownedCheckout || !(await pathExists(dir));
+        };
+        for (const candidate of candidates) {
+            if (await free(candidate))
+                return candidate;
+        }
+        for (let suffix = 2;; suffix++) {
+            const candidate = `${candidates[0]}-${suffix}`;
+            if (await free(candidate))
+                return candidate;
+        }
+    }
+    /** Begin reporting progress for a source mutation. */
+    beginSourceState(sourceId, step, cloned) {
+        this.currentSourceState = { sourceId, step, cloned };
+    }
+    /** Advance the in-flight source mutation step. */
+    updateSourceStep(step) {
+        if (this.currentSourceState !== undefined)
+            this.currentSourceState = { ...this.currentSourceState, step };
+    }
+    /** Stop reporting source mutation progress. */
+    endSourceState() {
+        this.currentSourceState = undefined;
+    }
+}
+/** Read a checkout's HEAD when it is a Git repository. */
+export async function tryHead(dir) {
+    try {
+        return await gitHead(dir);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The codeload tarball URL of a GitHub repository, or undefined for any
+ * other host. `https://github.com/<owner>/<repo>` maps to
+ * `https://codeload.github.com/<owner>/<repo>/tar.gz/refs/heads/<branch>`
+ * (or `/tar.gz/HEAD` for the default branch) — the git-protocol fallback
+ * when a clone cannot get through but plain HTTPS file download can.
+ */
+export function codeloadTarballUrl(url, branch) {
+    const match = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/i.exec(url.trim());
+    if (match === null)
+        return undefined;
+    const [, owner, repo] = match;
+    return `https://codeload.github.com/${owner}/${repo}/tar.gz/${branch === undefined ? 'HEAD' : `refs/heads/${branch}`}`;
+}