@on-par/repo-context 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 On PAR Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @on-par/repo-context
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only repository reader behind a stable interface, with GitHub contents-API and in-memory implementations. Zero runtime dependencies.
+
+Part of [Software Factory](https://github.com/on-par/software-factory), a multi-agent factory that ships verified work autonomously. Most users want the CLI, [`@on-par/factory-cli`](https://www.npmjs.com/package/@on-par/factory-cli); the other packages are its building blocks.
+
+## Documentation
+
+- [README and Quick Start](https://github.com/on-par/software-factory#readme)
+- [Architecture and package graph](https://github.com/on-par/software-factory/blob/main/docs/architecture.md)
+- [Changelog](https://github.com/on-par/software-factory/blob/main/CHANGELOG.md)
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/fs.d.ts

@@ -0,0 +1,31 @@
+import type { OnDegrade, RepoContextReader } from './reader.js';
+/** Minimal `node:fs/promises` surface the reader needs; injected in tests. */
+export interface FsDirent {
+    name: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+}
+export interface FsStatLike {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    size: number;
+}
+export interface FsLike {
+    stat(path: string): Promise<FsStatLike>;
+    readdir(path: string, options: {
+        withFileTypes: true;
+    }): Promise<readonly FsDirent[]>;
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    realpath(path: string): Promise<string>;
+}
+export interface FsReaderOptions {
+    /** Absolute path to the checkout root; every read is confined to it. */
+    root: string;
+    /** Files larger than this degrade to `too-large`. Defaults to DEFAULT_MAX_FILE_BYTES. */
+    maxFileBytes?: number;
+    /** Injected for tests; defaults to node:fs/promises. */
+    fs?: FsLike;
+    onDegrade?: OnDegrade;
+}
+export declare function createFsReader(options: FsReaderOptions): RepoContextReader;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAA+B,SAAS,EAAE,iBAAiB,EAAgB,MAAM,aAAa,CAAC;AAG3G,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,IAAI,OAAO,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,IAAI,OAAO,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AA0BD,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,iBAAiB,CAyK1E"}

package/dist/fs.js

@@ -0,0 +1,184 @@
+// src/fs.ts — local-filesystem RepoContextReader impl over a checkout root (#481).
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { DEFAULT_MAX_FILE_BYTES } from './github.js';
+import { joinRepoPath, normalizeRepoPath } from './path.js';
+import { EMPTY_DIR } from './reader.js';
+const nodeFs = {
+    stat: (p) => stat(p),
+    readdir: (p, o) => readdir(p, o),
+    readFile: (p, e) => readFile(p, e),
+    realpath: (p) => realpath(p),
+};
+function classifyFsError(error) {
+    const code = error?.code;
+    switch (code) {
+        case 'ENOENT':
+        case 'ENOTDIR':
+            return 'not-found';
+        case 'EACCES':
+        case 'EPERM':
+            return 'unauthorized';
+        case 'ELOOP':
+        case 'ENAMETOOLONG':
+            return 'invalid-path';
+        default:
+            return 'invalid-response';
+    }
+}
+export function createFsReader(options) {
+    const { root, onDegrade } = options;
+    const fs = options.fs ?? nodeFs;
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    let rootRealPromise;
+    function rootReal() {
+        rootRealPromise ??= fs.realpath(root).catch(() => undefined);
+        return rootRealPromise;
+    }
+    function emit(event) {
+        if (!onDegrade) {
+            return;
+        }
+        try {
+            onDegrade(event);
+        }
+        catch {
+            // Never let a throwing observer break the "never throws" contract.
+        }
+    }
+    async function resolveWithin(normalized) {
+        const abs = normalized === '' ? root : join(root, normalized);
+        let real;
+        try {
+            real = await fs.realpath(abs);
+        }
+        catch (error) {
+            return { ok: false, reason: classifyFsError(error) };
+        }
+        const base = await rootReal();
+        if (base === undefined) {
+            return { ok: false, reason: 'not-found' };
+        }
+        if (real !== base && !real.startsWith(base + sep)) {
+            return { ok: false, reason: 'invalid-path' };
+        }
+        return { ok: true, abs: real };
+    }
+    return {
+        async readFile(rawPath) {
+            const normalized = normalizeRepoPath(rawPath);
+            if (normalized === undefined) {
+                emit({ operation: 'readFile', path: rawPath, reason: 'invalid-path' });
+                return undefined;
+            }
+            const resolved = await resolveWithin(normalized);
+            if (!resolved.ok) {
+                emit({ operation: 'readFile', path: normalized, reason: resolved.reason });
+                return undefined;
+            }
+            let fileStat;
+            try {
+                fileStat = await fs.stat(resolved.abs);
+            }
+            catch (error) {
+                emit({ operation: 'readFile', path: normalized, reason: classifyFsError(error) });
+                return undefined;
+            }
+            if (fileStat.isDirectory()) {
+                emit({ operation: 'readFile', path: normalized, reason: 'wrong-type' });
+                return undefined;
+            }
+            if (fileStat.size > maxFileBytes) {
+                emit({ operation: 'readFile', path: normalized, reason: 'too-large' });
+                return undefined;
+            }
+            if (!fileStat.isFile()) {
+                emit({ operation: 'readFile', path: normalized, reason: 'wrong-type' });
+                return undefined;
+            }
+            let text;
+            try {
+                text = await fs.readFile(resolved.abs, 'utf8');
+            }
+            catch (error) {
+                emit({ operation: 'readFile', path: normalized, reason: classifyFsError(error) });
+                return undefined;
+            }
+            if (text.includes('\u0000')) {
+                emit({ operation: 'readFile', path: normalized, reason: 'unsupported-content' });
+                return undefined;
+            }
+            return { path: normalized, text, size: fileStat.size };
+        },
+        async readDir(rawPath) {
+            const normalized = normalizeRepoPath(rawPath);
+            if (normalized === undefined) {
+                emit({ operation: 'readDir', path: rawPath, reason: 'invalid-path' });
+                return EMPTY_DIR;
+            }
+            const resolved = await resolveWithin(normalized);
+            if (!resolved.ok) {
+                emit({ operation: 'readDir', path: normalized, reason: resolved.reason });
+                return EMPTY_DIR;
+            }
+            let dirStat;
+            try {
+                dirStat = await fs.stat(resolved.abs);
+            }
+            catch (error) {
+                emit({ operation: 'readDir', path: normalized, reason: classifyFsError(error) });
+                return EMPTY_DIR;
+            }
+            if (!dirStat.isDirectory()) {
+                emit({ operation: 'readDir', path: normalized, reason: 'wrong-type' });
+                return EMPTY_DIR;
+            }
+            let dirents;
+            try {
+                dirents = await fs.readdir(resolved.abs, { withFileTypes: true });
+            }
+            catch (error) {
+                emit({ operation: 'readDir', path: normalized, reason: classifyFsError(error) });
+                return EMPTY_DIR;
+            }
+            const entries = [];
+            for (const dirent of dirents) {
+                const childPath = joinRepoPath(normalized, dirent.name);
+                if (dirent.isDirectory()) {
+                    entries.push({ name: dirent.name, path: childPath, type: 'dir' });
+                    continue;
+                }
+                if (dirent.isFile()) {
+                    entries.push({ name: dirent.name, path: childPath, type: 'file' });
+                    continue;
+                }
+                // Symlink or other special file: resolve via stat, skip on failure.
+                try {
+                    const childStat = await fs.stat(join(resolved.abs, dirent.name));
+                    entries.push({ name: dirent.name, path: childPath, type: childStat.isDirectory() ? 'dir' : 'file' });
+                }
+                catch {
+                    continue;
+                }
+            }
+            return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        },
+        async exists(rawPath) {
+            const normalized = normalizeRepoPath(rawPath);
+            if (normalized === undefined) {
+                emit({ operation: 'exists', path: rawPath, reason: 'invalid-path' });
+                return false;
+            }
+            const resolved = await resolveWithin(normalized);
+            if (!resolved.ok) {
+                if (resolved.reason === 'not-found') {
+                    return false;
+                }
+                emit({ operation: 'exists', path: normalized, reason: resolved.reason });
+                return false;
+            }
+            return true;
+        },
+    };
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAgCxC,MAAM,MAAM,GAAW;IACrB,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IAClC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC7B,CAAC;AAEF,SAAS,eAAe,CAAC,KAAc;IACrC,MAAM,IAAI,GAAI,KAA2C,EAAE,IAAI,CAAC;IAChE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC;QACrB,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,OAAO,cAAc,CAAC;QACxB,KAAK,OAAO,CAAC;QACb,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;QACxB;YACE,OAAO,kBAAkB,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAwB;IACrD,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,MAAM,CAAC;IAChC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAC;IAEpE,IAAI,eAAwD,CAAC;IAC7D,SAAS,QAAQ;QACf,eAAe,KAAK,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC7D,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,SAAS,IAAI,CAAC,KAAmB;QAC/B,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,SAAS,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;IACH,CAAC;IAID,KAAK,UAAU,aAAa,CAAC,UAAkB;QAC7C,MAAM,GAAG,GAAG,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC9D,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,QAAQ,EAAE,CAAC;QAC9B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAC5C,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAC/C,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IACjC,CAAC;IAED,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,OAAO;YACpB,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;YAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;gBACvE,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,UAAU,CAAC,CAAC;YACjD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC3E,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,QAAoB,CAAC;YACzB,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAClF,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;gBAC3B,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;gBACxE,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,QAAQ,CAAC,IAAI,GAAG,YAAY,EAAE,CAAC;gBACjC,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;gBACvE,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;gBACvB,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;gBACxE,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,IAAY,CAAC;YACjB,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACjD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAClF,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;gBACjF,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACzD,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,OAAO;YACnB,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;YAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;gBACtE,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,UAAU,CAAC,CAAC;YACjD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC1E,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,OAAmB,CAAC;YACxB,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACjF,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;gBAC3B,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;gBACvE,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,OAA4B,CAAC;YACjC,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACpE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACjF,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;gBACxD,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;oBACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;oBAClE,SAAS;gBACX,CAAC;gBACD,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;oBACpB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;oBACnE,SAAS;gBACX,CAAC;gBACD,oEAAoE;gBACpE,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;oBACjE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;gBACvG,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS;gBACX,CAAC;YACH,CAAC;YAED,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClF,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,OAAO;YAClB,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;YAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,IAAI,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;gBACrE,OAAO,KAAK,CAAC;YACf,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,UAAU,CAAC,CAAC;YACjD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;oBACpC,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,IAAI,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;gBACzE,OAAO,KAAK,CAAC;YACf,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/github.d.ts

@@ -0,0 +1,30 @@
+import type { OnDegrade, RepoContextReader } from './reader.js';
+export interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<FetchLikeResponse>;
+export declare const DEFAULT_GITHUB_API_BASE_URL = "https://api.github.com";
+/** GitHub's contents API refuses to inline files above ~1 MB. */
+export declare const DEFAULT_MAX_FILE_BYTES = 1000000;
+export interface GitHubContentsReaderOptions {
+    owner: string;
+    repo: string;
+    /** Branch, tag, or commit SHA. Omit to use the repo's default branch. */
+    ref?: string;
+    /** Read-only token. Omit for unauthenticated (public, heavily rate-limited) access. */
+    token?: string;
+    baseUrl?: string;
+    maxFileBytes?: number;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    onDegrade?: OnDegrade;
+}
+export declare function createGitHubContentsReader(options: GitHubContentsReaderOptions): RepoContextReader;
+//# sourceMappingURL=github.d.ts.map

package/dist/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,SAAS,EAET,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEjH,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AACpE,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,UAAY,CAAC;AAEhD,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAqBD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,iBAAiB,CAoLlG"}

package/dist/github.js

@@ -0,0 +1,178 @@
+// src/github.ts — GitHub contents-API RepoContextReader impl (#468).
+import { Buffer } from 'node:buffer';
+import { normalizeRepoPath } from './path.js';
+import { EMPTY_DIR } from './reader.js';
+export const DEFAULT_GITHUB_API_BASE_URL = 'https://api.github.com';
+/** GitHub's contents API refuses to inline files above ~1 MB. */
+export const DEFAULT_MAX_FILE_BYTES = 1_000_000;
+function encodeContentsPath(path) {
+    return path
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+}
+function stripTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url[end - 1] === '/') {
+        end -= 1;
+    }
+    return url.slice(0, end);
+}
+export function createGitHubContentsReader(options) {
+    const { owner, repo, ref, token, onDegrade } = options;
+    const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_GITHUB_API_BASE_URL);
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const globalFetch = globalThis.fetch;
+    const doFetch = options.fetch ?? (globalFetch ? (url, init) => globalFetch(url, init) : undefined);
+    function emit(event) {
+        if (!onDegrade) {
+            return;
+        }
+        try {
+            onDegrade(event);
+        }
+        catch {
+            // Never let a throwing observer break the "never throws" contract.
+        }
+    }
+    function emitFailure(operation, result) {
+        emit({ operation, path: result.path, reason: result.reason, status: result.status, detail: result.detail });
+    }
+    function buildUrl(path) {
+        const encodedPath = encodeContentsPath(path);
+        const suffix = encodedPath === '' ? '' : `/${encodedPath}`;
+        const url = `${baseUrl}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents${suffix}`;
+        return ref ? `${url}?ref=${encodeURIComponent(ref)}` : url;
+    }
+    function buildHeaders() {
+        const headers = {
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+        };
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        return headers;
+    }
+    function classifyStatus(res) {
+        switch (res.status) {
+            case 404:
+                return 'not-found';
+            case 401:
+                return 'unauthorized';
+            case 403:
+                return res.headers.get('x-ratelimit-remaining') === '0' ? 'rate-limited' : 'unauthorized';
+            case 429:
+                return 'rate-limited';
+            default:
+                return 'invalid-response';
+        }
+    }
+    async function request(rawPath) {
+        const normalized = normalizeRepoPath(rawPath);
+        if (normalized === undefined) {
+            return { ok: false, path: rawPath, reason: 'invalid-path' };
+        }
+        if (!doFetch) {
+            return { ok: false, path: normalized, reason: 'network', detail: 'global fetch is unavailable' };
+        }
+        let res;
+        try {
+            res = await doFetch(buildUrl(normalized), { headers: buildHeaders() });
+        }
+        catch (error) {
+            return { ok: false, path: normalized, reason: 'network', detail: error.message };
+        }
+        if (!res.ok) {
+            return { ok: false, path: normalized, reason: classifyStatus(res), status: res.status };
+        }
+        let raw;
+        try {
+            raw = await res.text();
+        }
+        catch (error) {
+            return { ok: false, path: normalized, reason: 'invalid-response', detail: error.message };
+        }
+        try {
+            return { ok: true, path: normalized, body: JSON.parse(raw) };
+        }
+        catch (error) {
+            return { ok: false, path: normalized, reason: 'invalid-response', detail: error.message };
+        }
+    }
+    return {
+        async readFile(rawPath) {
+            const result = await request(rawPath);
+            if (!result.ok) {
+                emitFailure('readFile', result);
+                return undefined;
+            }
+            const body = result.body;
+            if (body === null ||
+                typeof body !== 'object' ||
+                Array.isArray(body) ||
+                body.type !== 'file') {
+                emit({ operation: 'readFile', path: result.path, reason: 'wrong-type' });
+                return undefined;
+            }
+            const record = body;
+            const size = typeof record.size === 'number' ? record.size : 0;
+            if (size > maxFileBytes) {
+                emit({ operation: 'readFile', path: result.path, reason: 'too-large' });
+                return undefined;
+            }
+            if (record.encoding === 'none') {
+                emit({ operation: 'readFile', path: result.path, reason: 'too-large' });
+                return undefined;
+            }
+            if (record.encoding !== 'base64' || typeof record.content !== 'string') {
+                emit({ operation: 'readFile', path: result.path, reason: 'unsupported-content' });
+                return undefined;
+            }
+            const text = Buffer.from(record.content, 'base64').toString('utf8');
+            if (text.includes('\u0000')) {
+                emit({ operation: 'readFile', path: result.path, reason: 'unsupported-content' });
+                return undefined;
+            }
+            return { path: result.path, text, size };
+        },
+        async readDir(rawPath) {
+            const result = await request(rawPath);
+            if (!result.ok) {
+                emitFailure('readDir', result);
+                return EMPTY_DIR;
+            }
+            if (!Array.isArray(result.body)) {
+                emit({ operation: 'readDir', path: result.path, reason: 'wrong-type' });
+                return EMPTY_DIR;
+            }
+            const entries = [];
+            for (const item of result.body) {
+                if (item === null || typeof item !== 'object') {
+                    continue;
+                }
+                const record = item;
+                if (typeof record.name !== 'string' || typeof record.path !== 'string') {
+                    continue;
+                }
+                if (record.type !== 'file' && record.type !== 'dir') {
+                    continue;
+                }
+                entries.push({ name: record.name, path: record.path, type: record.type });
+            }
+            return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        },
+        async exists(rawPath) {
+            const result = await request(rawPath);
+            if (!result.ok) {
+                if (result.reason === 'not-found') {
+                    return false;
+                }
+                emitFailure('exists', result);
+                return false;
+            }
+            return Array.isArray(result.body) || (result.body !== null && typeof result.body === 'object');
+        },
+    };
+}
+//# sourceMappingURL=github.js.map

package/dist/github.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './fs.js';
+export * from './github.js';
+export * from './memory.js';
+export * from './path.js';
+export * from './reader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// src/index.ts — @on-par/repo-context public surface (#468).
+export * from './fs.js';
+export * from './github.js';
+export * from './memory.js';
+export * from './path.js';
+export * from './reader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/memory.d.ts

@@ -0,0 +1,7 @@
+import type { OnDegrade, RepoContextReader } from './reader.js';
+export interface InMemoryReaderOptions {
+    onDegrade?: OnDegrade;
+}
+/** In-memory `RepoContextReader` over a flat `path -> contents` map. */
+export declare function createInMemoryReader(files: Readonly<Record<string, string>>, options?: InMemoryReaderOptions): RepoContextReader;
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAgB,SAAS,EAAE,iBAAiB,EAAgB,MAAM,aAAa,CAAC;AAG5F,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACvC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,iBAAiB,CAmGnB"}

package/dist/memory.js

@@ -0,0 +1,99 @@
+// src/memory.ts — in-memory RepoContextReader over a flat path -> contents map (#468).
+import { Buffer } from 'node:buffer';
+import { normalizeRepoPath } from './path.js';
+import { EMPTY_DIR } from './reader.js';
+/** In-memory `RepoContextReader` over a flat `path -> contents` map. */
+export function createInMemoryReader(files, options) {
+    const onDegrade = options?.onDegrade;
+    const store = new Map();
+    for (const [rawPath, contents] of Object.entries(files)) {
+        const normalized = normalizeRepoPath(rawPath);
+        if (normalized === undefined || normalized === '') {
+            continue;
+        }
+        store.set(normalized, contents);
+    }
+    function emit(event) {
+        if (!onDegrade) {
+            return;
+        }
+        try {
+            onDegrade(event);
+        }
+        catch {
+            // Never let a throwing observer break the "never throws" contract.
+        }
+    }
+    function isDirPrefix(path) {
+        const prefix = `${path}/`;
+        for (const key of store.keys()) {
+            if (key.startsWith(prefix)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    return {
+        async readFile(rawPath) {
+            const normalized = normalizeRepoPath(rawPath);
+            if (normalized === undefined) {
+                emit({ operation: 'readFile', path: rawPath, reason: 'invalid-path' });
+                return undefined;
+            }
+            const text = store.get(normalized);
+            if (text !== undefined) {
+                return { path: normalized, text, size: Buffer.byteLength(text, 'utf8') };
+            }
+            if (isDirPrefix(normalized)) {
+                emit({ operation: 'readFile', path: normalized, reason: 'wrong-type' });
+                return undefined;
+            }
+            emit({ operation: 'readFile', path: normalized, reason: 'not-found' });
+            return undefined;
+        },
+        async readDir(rawPath) {
+            const normalized = normalizeRepoPath(rawPath);
+            if (normalized === undefined) {
+                emit({ operation: 'readDir', path: rawPath, reason: 'invalid-path' });
+                return EMPTY_DIR;
+            }
+            if (store.has(normalized)) {
+                emit({ operation: 'readDir', path: normalized, reason: 'wrong-type' });
+                return EMPTY_DIR;
+            }
+            const prefix = normalized === '' ? '' : `${normalized}/`;
+            const children = new Map();
+            for (const key of store.keys()) {
+                if (!key.startsWith(prefix)) {
+                    continue;
+                }
+                const rest = key.slice(prefix.length);
+                const segments = rest.split('/');
+                const name = segments[0];
+                const childPath = prefix === '' ? name : `${prefix}${name}`;
+                const type = segments.length === 1 ? 'file' : 'dir';
+                const existing = children.get(childPath);
+                if (!existing || (existing.type === 'file' && type === 'dir')) {
+                    children.set(childPath, { name, path: childPath, type });
+                }
+            }
+            if (children.size === 0 && normalized !== '') {
+                emit({ operation: 'readDir', path: normalized, reason: 'not-found' });
+                return EMPTY_DIR;
+            }
+            return [...children.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        },
+        async exists(rawPath) {
+            const normalized = normalizeRepoPath(rawPath);
+            if (normalized === undefined) {
+                emit({ operation: 'exists', path: rawPath, reason: 'invalid-path' });
+                return false;
+            }
+            if (normalized === '' || store.has(normalized) || isDirPrefix(normalized)) {
+                return true;
+            }
+            return false;
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

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

package/dist/path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalizes a repo-root-relative path: trims whitespace, collapses `//`, drops a leading
+ * `/` or `./`, drops a trailing `/`, and maps '', '.', '/', './' to the repo root ''.
+ * Returns `undefined` when any segment is `..` — the path would escape the repo root.
+ */
+export declare function normalizeRepoPath(path: string): string | undefined;
+export declare function joinRepoPath(base: string, name: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWlE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/path.js

@@ -0,0 +1,20 @@
+// src/path.ts — pure repo-path normalization (#468).
+/**
+ * Normalizes a repo-root-relative path: trims whitespace, collapses `//`, drops a leading
+ * `/` or `./`, drops a trailing `/`, and maps '', '.', '/', './' to the repo root ''.
+ * Returns `undefined` when any segment is `..` — the path would escape the repo root.
+ */
+export function normalizeRepoPath(path) {
+    const segments = path
+        .trim()
+        .split('/')
+        .filter((segment) => segment !== '' && segment !== '.');
+    if (segments.some((segment) => segment === '..')) {
+        return undefined;
+    }
+    return segments.join('/');
+}
+export function joinRepoPath(base, name) {
+    return base === '' ? name : `${base}/${name}`;
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,QAAQ,GAAG,IAAI;SAClB,IAAI,EAAE;SACN,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC;IAE1D,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAY;IACrD,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC"}

package/dist/reader.d.ts

@@ -0,0 +1,47 @@
+/** A file read from the target repo. `path` is the normalized, repo-root-relative path. */
+export interface RepoFile {
+    path: string;
+    /** UTF-8 decoded contents. */
+    text: string;
+    /** Byte length reported by the backend. */
+    size: number;
+}
+export type RepoEntryType = 'file' | 'dir';
+export interface RepoDirEntry {
+    /** Basename, e.g. 'README.md'. */
+    name: string;
+    /** Repo-root-relative path, e.g. 'docs/adr/README.md'. */
+    path: string;
+    type: RepoEntryType;
+}
+/**
+ * Read-only access to one repository at one revision.
+ *
+ * Backend coordinates (owner/repo/ref/token/worktree root) are bound when the reader is
+ * constructed, never passed here — that is what lets a gh-contents reader, an fs-backed
+ * reader, and a future blobless sparse-checkout reader be swapped without changing callers.
+ *
+ * No method throws. A path that is missing, unreadable, unauthorized, rate-limited, too
+ * large, or not text degrades to the empty result for that method; pass `onDegrade` to the
+ * factory to observe why.
+ */
+export interface RepoContextReader {
+    readFile(path: string): Promise<RepoFile | undefined>;
+    readDir(path: string): Promise<readonly RepoDirEntry[]>;
+    exists(path: string): Promise<boolean>;
+}
+export type RepoContextOperation = 'readFile' | 'readDir' | 'exists';
+export type DegradeReason = 'invalid-path' | 'not-found' | 'wrong-type' | 'unauthorized' | 'rate-limited' | 'too-large' | 'unsupported-content' | 'network' | 'invalid-response';
+export interface DegradeEvent {
+    operation: RepoContextOperation;
+    /** The requested path, normalized when normalization succeeded. */
+    path: string;
+    reason: DegradeReason;
+    /** HTTP status, when the backend is remote. */
+    status?: number;
+    detail?: string;
+}
+export type OnDegrade = (event: DegradeEvent) => void;
+/** The empty listing every backend degrades to, so callers can compare identity if useful. */
+export declare const EMPTY_DIR: readonly RepoDirEntry[];
+//# sourceMappingURL=reader.d.ts.map

package/dist/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AAEA,2FAA2F;AAC3F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IACtD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IACxD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErE,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,WAAW,GACX,YAAY,GACZ,cAAc,GACd,cAAc,GACd,WAAW,GACX,qBAAqB,GACrB,SAAS,GACT,kBAAkB,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,oBAAoB,CAAC;IAChC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAEtD,8FAA8F;AAC9F,eAAO,MAAM,SAAS,EAAE,SAAS,YAAY,EAAsB,CAAC"}

package/dist/reader.js

@@ -0,0 +1,4 @@
+// src/reader.ts — the read-only repo access port every backend implements (#468).
+/** The empty listing every backend degrades to, so callers can compare identity if useful. */
+export const EMPTY_DIR = Object.freeze([]);
+//# sourceMappingURL=reader.js.map

package/dist/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AAAA,kFAAkF;AA+DlF,8FAA8F;AAC9F,MAAM,CAAC,MAAM,SAAS,GAA4B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@on-par/repo-context",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "Read-only repo reader behind a stable interface: GitHub contents-API and in-memory implementations.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/on-par/software-factory.git",
+    "directory": "packages/repo-context"
+  },
+  "homepage": "https://github.com/on-par/software-factory#readme",
+  "bugs": {
+    "url": "https://github.com/on-par/software-factory/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "prepack": "node ../../scripts/pack-hygiene-cli.ts prepack"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.6.4"
+  }
+}