@lobu/connector-sdk 7.1.0 → 8.0.0

package/dist/sources/local-file-source.js

@@ -0,0 +1,343 @@
+/**
+ * LocalFileSource — adapter over a local directory.
+ *
+ * URI shape: `file:///absolute/path/`
+ *
+ *  - `fetch()` stream-copies the source tree into a per-ref cache dir
+ *    (`${WORKSPACE_DIR}/.lobu-cache/sources/<uri-hash>/refs/<ref>/`),
+ *    sealing each file's sha256 during the copy so the manifest's hashes
+ *    record exactly the bytes that landed in the cache. The Snapshot
+ *    reads from that per-ref dir — never the live source — so
+ *    `snapshot.ref` matches `sha256(snapshot.readFile(path))` for the
+ *    bytes captured at fetch time, even under concurrent writes against
+ *    the source. See `Snapshot` in `file-source.ts` for the honest
+ *    same-UID mutability contract.
+ *  - `ref` is the canonical manifest hash (sha256 of sorted `(path, sha256)`
+ *    pairs).
+ *  - `diffSinceRef(prevRef)`: re-walks the live directory, builds a fresh
+ *    manifest, and diffs it against the stored per-ref manifest that
+ *    matches `prevRef`. If no stored manifest matches (cache was cleared
+ *    between runs), the diff treats every current file as `added`.
+ */
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readFile, readdir, realpath, rename, rm, stat, } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative, sep } from 'node:path';
+import { canonicalManifestRef, cachePathsFor, defaultCacheRoot, diffManifests, readAndVerifyMeta, readManifest, requireMeta, withSourceLock, writeManifest, writeMeta, } from './cache.js';
+import { walkDirectoryRelative } from './glob.js';
+import { DirectorySnapshot } from './snapshot.js';
+export class LocalFileSource {
+    #uri;
+    #rootDir;
+    #paths;
+    /**
+     * When the local source root happens to *contain* the SDK cache dir
+     * (`${WORKSPACE_DIR}/.lobu-cache`) — typical when the source is the
+     * workspace root, OR when WORKSPACE_DIR is nested inside the source —
+     * we must NOT ingest our own cache files, or every fetch() would mutate
+     * the ref and self-pollute.
+     *
+     * Resolved at fetch() time using realpath() on both source root and the
+     * cache directory, so we exclude exactly the right subtree no matter
+     * where the cache lives relative to the source. If the cache is outside
+     * the source entirely, the predicate excludes nothing.
+     */
+    #exclude = () => false;
+    constructor(uri) {
+        if (!uri.startsWith('file://')) {
+            throw new Error(`LocalFileSource: expected file:// URI, got ${uri}`);
+        }
+        this.#uri = uri;
+        this.#rootDir = fileURLToPath(uri);
+        this.#paths = cachePathsFor(uri);
+    }
+    fetch() {
+        return withSourceLock(this.#uri, async () => {
+            const s = await stat(this.#rootDir).catch(() => null);
+            if (!s || !s.isDirectory()) {
+                throw new Error(`LocalFileSource: ${this.#rootDir} is not a directory`);
+            }
+            await mkdir(this.#paths.root, { recursive: true });
+            await readAndVerifyMeta(this.#paths.metaPath, this.#uri);
+            // Recompute exclude predicate each fetch(): the cache dir's location
+            // relative to the source can shift if WORKSPACE_DIR changes between
+            // calls (different process, different cwd).
+            this.#exclude = await resolveCacheExclude(this.#rootDir);
+            // Race-free pipeline:
+            //
+            //  1. List the source's relative file paths (no byte reads yet).
+            //  2. For each file: stream-pipe the source bytes through a sha256 hash
+            //     AND into a staging copy in a single pass. The per-file hash is
+            //     SEALED at copy time — the bytes that landed in staging are
+            //     identical to the bytes the hash was computed over, and there
+            //     is no second pass over staging that could observe a post-copy
+            //     mutation. THIS is the actual mechanism that pins
+            //     `snapshot.ref` to the bytes the Snapshot will read; an earlier
+            //     pass also chmod-locked the per-ref dir to 0500/0400, but
+            //     chmod doesn't bind same-UID writers (the owner can re-mode
+            //     their own files), so it was theater against the threat model
+            //     that matters and has been removed.
+            //  3. Staging lives INSIDE the cache root at
+            //     `${root}/refs/<crypto-random-32hex>` — same filesystem as the
+            //     destination per-ref dir, so `rename()` is atomic.
+            //  4. Compute the canonical ref from the sealed per-file hashes.
+            //  5. If `refs/<ref>` already exists, drop staging; else rename
+            //     staging into the per-ref dir.
+            //
+            // The Snapshot reads from the per-ref dir — never from the live
+            // source — so `snapshot.ref` matches the bytes Snapshot.readFile
+            // returns at the moment fetch() resolved. Same-UID post-fetch
+            // mutation is documented as out-of-scope in the Snapshot contract.
+            const relPaths = await listRelativeFiles(this.#rootDir, this.#exclude);
+            await mkdir(join(this.#paths.root, 'refs'), { recursive: true });
+            const stagingDir = join(this.#paths.root, 'refs', randomBytes(16).toString('hex'));
+            await mkdir(stagingDir, { recursive: true, mode: 0o700 });
+            let stagingMoved = false;
+            let refDir;
+            let files;
+            let ref;
+            try {
+                files = await streamCopyAndHash(this.#rootDir, stagingDir, relPaths);
+                ref = canonicalManifestRef(files);
+                refDir = perRefDir(this.#paths.root, ref);
+                if (await dirExists(refDir)) {
+                    // Same content already installed; throw away the staging copy.
+                    await rm(stagingDir, { recursive: true, force: true });
+                    stagingMoved = true;
+                }
+                else {
+                    await rename(stagingDir, refDir);
+                    stagingMoved = true;
+                }
+            }
+            finally {
+                if (!stagingMoved) {
+                    await rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+                }
+            }
+            const manifest = {
+                ref,
+                files,
+                fetched_at: new Date().toISOString(),
+            };
+            await writeManifest(this.#paths.manifestPath, manifest);
+            await writeMeta(this.#paths.metaPath, { uri: this.#uri, kind: 'local' });
+            // Also persist a per-ref copy so diffSinceRef can look up prior refs.
+            await writePerRefManifest(this.#paths.root, manifest);
+            // Keep the per-ref cache bounded — `refs/` accumulates a new dir per
+            // distinct content state if the source is rewritten. Always preserve
+            // the just-returned dir (`refDir`), including the cache-hit branch
+            // where its mtime is older than newer entries — pruning it would
+            // ENOENT the Snapshot we just handed back. Mirrors the
+            // `protectedRefDir` argument tarball-file-source.ts already uses.
+            await pruneOldRefDirs(this.#paths.root, MAX_REF_DIRS, refDir);
+            return new DirectorySnapshot(refDir, ref);
+        });
+    }
+    diffSinceRef(prevRef) {
+        return withSourceLock(this.#uri, async () => {
+            await requireMeta(this.#paths.metaPath, this.#uri);
+            this.#exclude = await resolveCacheExclude(this.#rootDir);
+            const files = await collectFilesFromLive(this.#rootDir, this.#exclude);
+            const curRef = canonicalManifestRef(files);
+            if (curRef === prevRef)
+                return { added: [], modified: [], removed: [] };
+            const prev = await readPerRefManifest(this.#paths.root, prevRef);
+            const next = { ref: curRef, files, fetched_at: new Date().toISOString() };
+            if (!prev) {
+                // No record of the previous ref — caller's checkpoint references a ref
+                // we no longer have on disk. Treat as "everything is new" so the
+                // connector re-ingests rather than silently dropping data.
+                return { added: files.map((f) => f.path), modified: [], removed: [] };
+            }
+            return diffManifests(prev, next);
+        });
+    }
+}
+/**
+ * Compute the exclude predicate for `.lobu-cache`. Realpaths both source root
+ * and `${cacheRoot}/.lobu-cache`, then:
+ *   - If the cache dir is contained under the source root, exclude that exact
+ *     relative subtree (POSIX-separated).
+ *   - Otherwise return a no-op predicate — no exclusion needed.
+ *
+ * This handles three layouts correctly:
+ *   (a) source root === workspace root → exclude `.lobu-cache/`
+ *   (b) WORKSPACE_DIR is nested inside source (e.g. `source/workspace/`) →
+ *       exclude `workspace/.lobu-cache/`
+ *   (c) workspace lives outside source → no exclusion
+ *
+ * Realpath defends against symlinked workspace dirs.
+ */
+async function resolveCacheExclude(sourceRoot) {
+    const cacheBase = join(defaultCacheRoot(), '.lobu-cache');
+    const realSource = await realpath(sourceRoot).catch(() => sourceRoot);
+    const realCache = await realpath(cacheBase).catch(() => cacheBase);
+    const rel = relative(realSource, realCache);
+    if (rel === '' || rel.startsWith('..') || rel.split(sep).includes('..')) {
+        // cache is outside source (or coincides with the source root, which is
+        // degenerate — nothing meaningful to exclude). No-op predicate.
+        return () => false;
+    }
+    const posixRel = sep === '/' ? rel : rel.split(sep).join('/');
+    const prefix = `${posixRel}/`;
+    return (relPath) => relPath === posixRel || relPath.startsWith(prefix);
+}
+function perRefDir(root, ref) {
+    return join(root, 'refs', ref);
+}
+async function dirExists(p) {
+    const s = await stat(p).catch(() => null);
+    return !!s && s.isDirectory();
+}
+/** Max number of `refs/<hash>` per-ref directories kept on disk. */
+const MAX_REF_DIRS = 3;
+/** List relative paths from the source root, applying the exclude predicate. */
+async function listRelativeFiles(rootDir, exclude) {
+    const out = [];
+    for await (const rel of walkDirectoryRelative(rootDir)) {
+        if (exclude(rel))
+            continue;
+        out.push(rel);
+    }
+    return out;
+}
+/**
+ * Stream-copy each tracked file from `sourceRoot` into `stagingDir`, feeding
+ * the bytes through a sha256 hasher in the same pass. Per-file hash is
+ * SEALED at copy time — the manifest entry records exactly the bytes that
+ * were written into staging. There is no second pass over staging that
+ * could observe a post-copy mutation.
+ *
+ * Why streaming instead of copy-on-write + post-hash: COW (`COPYFILE_FICLONE`)
+ * shares pages with the source until either side writes; a concurrent
+ * truncate-and-rewrite on the source breaks the share and may race the
+ * hash pass. A read-then-hash-then-write streaming pipe seals the bytes
+ * the instant they leave the source.
+ */
+async function streamCopyAndHash(sourceRoot, stagingDir, relPaths) {
+    const out = [];
+    for (const rel of relPaths) {
+        const src = join(sourceRoot, rel);
+        const dst = join(stagingDir, rel);
+        await mkdir(dirname(dst), { recursive: true });
+        const hash = createHash('sha256');
+        const reader = createReadStream(src);
+        reader.on('data', (chunk) => {
+            hash.update(chunk);
+        });
+        await pipeline(reader, createWriteStream(dst));
+        out.push({ path: rel, sha256: hash.digest('hex') });
+    }
+    return out;
+}
+/**
+ * Hash files directly from the live source root — used by `diffSinceRef()`,
+ * which doesn't return a Snapshot and only needs a manifest to compare
+ * against. Race-tolerant: a mid-walk write just shows up as part of the
+ * next diff.
+ */
+async function collectFilesFromLive(rootDir, exclude) {
+    const out = [];
+    for await (const rel of walkDirectoryRelative(rootDir)) {
+        if (exclude(rel))
+            continue;
+        const abs = join(rootDir, rel);
+        const buf = await readFile(abs);
+        const sha = createHash('sha256').update(buf).digest('hex');
+        out.push({ path: rel, sha256: sha });
+    }
+    return out;
+}
+/**
+ * Keep at most `keep` per-ref directories under `${root}/refs/`. Sorted by
+ * mtime descending; the oldest are rm-rf'd. `protectedRefDir` is always
+ * preserved regardless of mtime — the cache-hit branch in fetch() returns
+ * an existing dir whose mtime may be older than newer entries, and the
+ * Snapshot we just handed back is reading from it. Pre-this-guard, the
+ * mtime sort happily pruned exactly the dir the caller was about to read,
+ * leaving the Snapshot pointing at an ENOENT. Matches the
+ * `protectedRefDir` parameter tarball-file-source.ts already uses
+ * (lines 137 + 228-273).
+ *
+ * Snapshots already handed out keep working as long as their backing
+ * dir wasn't pruned — `keep=3` accommodates a fresh fetch plus two
+ * in-flight overlapping syncs.
+ *
+ * Filters by name shape (64-hex sha256). Skips in-flight staging dirs
+ * (32-hex random names co-located in `refs/`) AND any legacy `.staging.*`
+ * directories from older builds. Per-ref manifest JSON files
+ * (`<ref>.json`) are files, not directories, and are kept indefinitely
+ * so historical diffs work even after the data dir is gone.
+ *
+ * v1 limitation: this prune is process-local (`withSourceLock` is an
+ * in-memory mutex). Two processes sharing the same
+ * `${WORKSPACE_DIR}/.lobu-cache` can race-prune each other's per-ref
+ * dirs — including the one a peer's Snapshot is reading. v1 supports
+ * one cache owner per workspace; multi-process sharing would need a
+ * filesystem advisory lock around fetch+prune.
+ */
+async function pruneOldRefDirs(root, keep, protectedRefDir) {
+    const refsRoot = join(root, 'refs');
+    let entries;
+    try {
+        entries = await readdir(refsRoot, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    const candidates = [];
+    for (const ent of entries) {
+        if (!ent.isDirectory())
+            continue;
+        // Only touch completed per-ref dirs (64-hex sha256). In-flight staging
+        // dirs use a 32-hex randomBytes name and must not be pruned.
+        if (!/^[a-f0-9]{64}$/.test(ent.name))
+            continue;
+        const abs = join(refsRoot, ent.name);
+        try {
+            const s = await stat(abs);
+            candidates.push({
+                name: ent.name,
+                abs,
+                mtimeMs: s.mtimeMs,
+                protected: abs === protectedRefDir,
+            });
+        }
+        catch {
+            // Skip — concurrent prune from another process is fine.
+        }
+    }
+    if (candidates.length <= keep)
+        return;
+    const protectedDirs = candidates.filter((c) => c.protected);
+    const others = candidates
+        .filter((c) => !c.protected)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const keepers = new Set([
+        ...protectedDirs.map((c) => c.name),
+        ...others.slice(0, Math.max(0, keep - protectedDirs.length)).map((c) => c.name),
+    ]);
+    for (const c of candidates) {
+        if (keepers.has(c.name))
+            continue;
+        await rm(c.abs, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Per-ref manifest storage under `<root>/refs/<ref>.json`. Lets a connector
+ * keep checkpointing arbitrary `prevRef`s without us guessing.
+ */
+async function writePerRefManifest(root, manifest) {
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(join(root, 'refs'), { recursive: true });
+    await writeManifest(join(root, 'refs', `${manifest.ref}.json`), manifest);
+}
+async function readPerRefManifest(root, ref) {
+    return readManifest(join(root, 'refs', `${ref}.json`));
+}
+//# sourceMappingURL=local-file-source.js.map

package/dist/sources/local-file-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-source.js","sourceRoot":"","sources":["../../src/sources/local-file-source.ts"],"names":[],"mappings":"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"}

package/dist/sources/resolver.d.ts

@@ -0,0 +1,6 @@
+/**
+ * URI → FileSystemSource resolver. Imported by `file-source.ts`.
+ */
+import type { FileSystemSource } from '../file-source.js';
+export declare function resolveUri(uri: string): FileSystemSource;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/sources/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/sources/resolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAK1D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CA8DxD"}

package/dist/sources/resolver.js

@@ -0,0 +1,47 @@
+import { GitFileSource } from './git-file-source.js';
+import { LocalFileSource } from './local-file-source.js';
+import { TarballFileSource } from './tarball-file-source.js';
+export function resolveUri(uri) {
+    if (typeof uri !== 'string' || uri.length === 0) {
+        throw new Error('fileSystemSourceFromUri: uri must be a non-empty string');
+    }
+    // git+ssh:// — explicit reject with helpful suggestion.
+    if (uri.startsWith('git+ssh://') || uri.startsWith('ssh://')) {
+        throw new Error(`Unsupported scheme: ${uri.split('://')[0]}://. SSH auth requires operator keys ` +
+            `and is out of scope for v1. Use git+https://github.com/owner/repo.git instead.`);
+    }
+    // git+http:// — explicit reject (no plaintext clones).
+    if (uri.startsWith('git+http://')) {
+        throw new Error(`Unsupported scheme: git+http://. Plaintext git fetch is rejected; use git+https://.`);
+    }
+    if (uri.startsWith('git+https://')) {
+        return new GitFileSource(uri);
+    }
+    if (uri.startsWith('file://')) {
+        return new LocalFileSource(uri);
+    }
+    if (uri.startsWith('https://')) {
+        // Tarball schemes: must end in .tar.gz or .tgz (query-stripped).
+        const pathPart = uri.split('?')[0]?.split('#')[0] ?? uri;
+        if (pathPart.endsWith('.tar.gz') || pathPart.endsWith('.tgz')) {
+            return new TarballFileSource(uri);
+        }
+        throw new Error(`Unsupported HTTPS URL: ${uri}. Only .tar.gz / .tgz are supported in v1 ` +
+            `(no .zip, .7z, or raw directories).`);
+    }
+    if (uri.startsWith('http://')) {
+        throw new Error(`Unsupported scheme: http://. Plaintext tarball fetch is rejected; use https://.`);
+    }
+    // Future schemes — surface them by name so the error tells operators what
+    // we know about, not just "unknown".
+    const knownFutureSchemes = ['s3://', 'gs://', 'azure://', 'gcs://', 'r2://'];
+    for (const scheme of knownFutureSchemes) {
+        if (uri.startsWith(scheme)) {
+            throw new Error(`Scheme ${scheme} is reserved for a future implementation and not supported ` +
+                `in v1 of FileSystemSource.`);
+        }
+    }
+    throw new Error(`Unsupported FileSystemSource URI: ${uri}. ` +
+        `Expected git+https://…, https://…tar.gz, or file:///…`);
+}
+//# sourceMappingURL=resolver.js.map

package/dist/sources/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/sources/resolver.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,wDAAwD;IACxD,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,uBAAuB,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,uCAAuC;YAC/E,gFAAgF,CACnF,CAAC;IACJ,CAAC;IAED,uDAAuD;IACvD,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,iEAAiE;QACjE,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;QACzD,IAAI,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9D,OAAO,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,IAAI,KAAK,CACb,0BAA0B,GAAG,4CAA4C;YACvE,qCAAqC,CACxC,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,qCAAqC;IACrC,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7E,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,UAAU,MAAM,6DAA6D;gBAC3E,4BAA4B,CAC/B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,qCAAqC,GAAG,IAAI;QAC1C,uDAAuD,CAC1D,CAAC;AACJ,CAAC"}

package/dist/sources/snapshot.d.ts

@@ -0,0 +1,19 @@
+import type { Snapshot } from '../file-source.js';
+export interface DirectorySnapshotOptions {
+    /**
+     * Predicate run against each POSIX-style relative path during walk and
+     * read. Returning `true` excludes the path. Used to hide internal dirs
+     * (`.git/` for git sources, `.lobu-cache/` for local sources rooted at
+     * the workspace).
+     */
+    exclude?: (relativePath: string) => boolean;
+}
+export declare class DirectorySnapshot implements Snapshot {
+    #private;
+    readonly ref: string;
+    constructor(rootDir: string, ref: string, options?: DirectorySnapshotOptions);
+    walkFiles(glob: string): AsyncIterable<string>;
+    readFile(relativePath: string): Promise<Buffer>;
+    readText(relativePath: string): Promise<string>;
+}
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/sources/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/sources/snapshot.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;CAC7C;AAED,qBAAa,iBAAkB,YAAW,QAAQ;;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAMT,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;IAUzE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;IAO/C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CA6CtD"}

package/dist/sources/snapshot.js

@@ -0,0 +1,91 @@
+/**
+ * Concrete `Snapshot` backed by a directory on disk. Reused by all three
+ * source implementations — the rootDir stays hidden from the connector.
+ *
+ * Two layers of defense:
+ *
+ *  1. Lexical: `#resolveSafe` rejects absolute paths and `..` escapes.
+ *  2. Runtime: `readFile` / `readText` resolve the *real* path (following
+ *     symlinks) and verify it still falls under the snapshot root. This
+ *     blocks symlink-based escape from extracted tarballs / local sources
+ *     that happen to contain a `link -> /etc/passwd` symlink.
+ *
+ * An optional `exclude` predicate skips entries during `walkFiles` AND
+ * denies them in `readFile`/`readText` — used to hide `.git/` from git
+ * snapshots and `.lobu-cache/` from local-source snapshots rooted at the
+ * workspace.
+ */
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { matchesGlob, walkDirectoryRelative } from './glob.js';
+export class DirectorySnapshot {
+    ref;
+    /** @internal — NOT exported on the public Snapshot interface. */
+    #rootDir;
+    #realRootDir;
+    #exclude;
+    constructor(rootDir, ref, options = {}) {
+        this.#rootDir = resolve(rootDir);
+        this.ref = ref;
+        this.#exclude = options.exclude ?? (() => false);
+        // Realpath the root once; symlink checks resolve against the canonical
+        // form so we don't reject a legitimate request just because the cache
+        // directory itself sits under a symlinked path.
+        this.#realRootDir = realpath(this.#rootDir).catch(() => this.#rootDir);
+    }
+    async *walkFiles(glob) {
+        for await (const rel of walkDirectoryRelative(this.#rootDir)) {
+            if (this.#exclude(rel))
+                continue;
+            if (matchesGlob(rel, glob))
+                yield rel;
+        }
+    }
+    async readFile(relativePath) {
+        return readFile(await this.#resolveSafe(relativePath));
+    }
+    async readText(relativePath) {
+        return readFile(await this.#resolveSafe(relativePath), 'utf8');
+    }
+    /**
+     * Resolve `relativePath` inside `rootDir`. Layered defenses:
+     *  1. Reject absolute paths.
+     *  2. Reject `..` escapes (lexical).
+     *  3. Reject paths matched by the exclude predicate.
+     *  4. Resolve the path with `realpath()` (follows symlinks). Verify the
+     *     canonical form still falls under the canonical root.
+     */
+    async #resolveSafe(relativePath) {
+        if (isAbsolute(relativePath)) {
+            throw new Error(`Snapshot.readFile: absolute paths are not allowed (${relativePath})`);
+        }
+        const joined = normalize(join(this.#rootDir, relativePath));
+        const rel = relative(this.#rootDir, joined);
+        if (rel.startsWith('..') || isAbsolute(rel) || rel.split(sep).includes('..')) {
+            throw new Error(`Snapshot.readFile: path escapes snapshot root (${relativePath})`);
+        }
+        const posixRel = sep === '/' ? rel : rel.split(sep).join('/');
+        if (this.#exclude(posixRel)) {
+            throw new Error(`Snapshot.readFile: path is excluded from the snapshot (${relativePath})`);
+        }
+        // Runtime defense: follow symlinks and verify the target is under root.
+        let realTarget;
+        try {
+            realTarget = await realpath(joined);
+        }
+        catch (err) {
+            // File doesn't exist or isn't reachable — let readFile() surface the
+            // canonical ENOENT.
+            if (err.code === 'ENOENT')
+                return joined;
+            throw err;
+        }
+        const realRoot = await this.#realRootDir;
+        const relReal = relative(realRoot, realTarget);
+        if (relReal.startsWith('..') || isAbsolute(relReal)) {
+            throw new Error(`Snapshot.readFile: path resolves outside snapshot root via symlink (${relativePath})`);
+        }
+        return realTarget;
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/sources/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/sources/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/sources/tarball-file-source.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TarballFileSource — download a remote `.tar.gz`/`.tgz`, extract once,
+ * snapshot from the extraction directory.
+ *
+ *  - Download via `undici.request` (Node built-in, no extra dep).
+ *  - Extract via `tar` (npm `tar`, ~50KB) — streaming, won't buffer the
+ *    archive in memory.
+ *  - Atomic install: extract to `${root}/snapshot.tmp.<rand>` and rename
+ *    over `${root}/snapshot/` once extraction completes. Partial fetches
+ *    don't corrupt the cache.
+ *  - `ref` is the canonical manifest hash; identical content → identical
+ *    `ref` regardless of when/where it was fetched.
+ *  - `diffSinceRef` re-fetches and compares against the per-ref manifest
+ *    stored alongside the cache. Full tarballs have no incremental wire
+ *    support — the gain is "did anything change?" not "send me the delta".
+ */
+import type { FileDelta, FileSystemSource, Snapshot } from '../file-source.js';
+export interface TarballFileSourceOptions {
+    /** Strip the leading directory component during extraction (default 0). */
+    stripComponents?: number;
+}
+export declare class TarballFileSource implements FileSystemSource {
+    #private;
+    constructor(uri: string, opts?: TarballFileSourceOptions);
+    fetch(): Promise<Snapshot>;
+    diffSinceRef(prevRef: string): Promise<FileDelta>;
+}
+//# sourceMappingURL=tarball-file-source.d.ts.map

package/dist/sources/tarball-file-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball-file-source.d.ts","sourceRoot":"","sources":["../../src/sources/tarball-file-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAkB/E,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,iBAAkB,YAAW,gBAAgB;;gBAK5C,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,wBAA6B;IAgB5D,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC;IA8EpB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;CA2BxD"}