@framers/agentos-ext-github 0.1.4 → 0.2.1

package/dist/documents/GitHubDocumentsConnector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview A repository's documentation as account sources, read through a GitHub App's installation: each
+ * repository's tree read once a commit within a request budget, the documentation kept by a filter, each file read as
+ * raw bytes under a cap, and a push compared by the tree at its `after` commit.
+ * @module agentos-ext-github/documents/GitHubDocumentsConnector
+ */
+import { type AccountSourceConnector, type SourceChanges, type SourceGone, type SourceItem, type SourceRead, type SourceSelection } from '@framers/agentos-ext-account-sources';
+import type { GitHubAppCredential } from '../app/credential.js';
+import { type TreeBlob, type TreeFilter } from './tree.js';
+/** One repository of a link. */
+export interface LinkedRepository {
+    id: number;
+    fullName: string;
+    defaultBranch: string;
+}
+/**
+ * What `changesSince` compares: the repository (its id, first of `ids`), and from a push its `after` commit and its
+ * `ref`, with the listing at `after` when the caller holds it.
+ */
+export interface GitHubChangesSelection extends SourceSelection {
+    /** The commit to compare at; the default branch's head when absent. */
+    after?: string;
+    /** The push's ref, such as `refs/heads/main`; a push to another branch than the default changes nothing. */
+    ref?: string;
+    /** The documentation's listing at `after`, which spares the tree's read. */
+    listing?: readonly TreeBlob[];
+}
+/**
+ * A repository's documentation as account sources: an item's id is `<repositoryId>:<path>`, its version
+ * `<blob>@<commit>`, and the cursor of `changesSince` the JSON of each documentation path's blob at the commit last
+ * read. An installation is removed by the app's own call (`uninstallInstallation`), never by a link's connector.
+ */
+export declare class GitHubDocumentsConnector implements AccountSourceConnector {
+    private readonly credential;
+    private readonly installationId;
+    private readonly repositories;
+    private readonly filter;
+    private readonly fetchImpl;
+    private readonly apiBase;
+    readonly kind = "github";
+    /**
+     * @param credential The app's credential; each repository is read with an installation token narrowed to it.
+     * @param installationId The installation the repositories are read through.
+     * @param repositories The repositories of the link.
+     * @param filter What is kept as documentation, and the bounds on reading it.
+     * @param fetchImpl The fetch the repositories are read with.
+     * @param apiBase GitHub's REST API, or a stand-in's address in tests.
+     */
+    constructor(credential: GitHubAppCredential, installationId: number, repositories: readonly LinkedRepository[], filter?: TreeFilter, fetchImpl?: typeof fetch, apiBase?: string);
+    private repository;
+    private token;
+    /** The head commit of a repository's default branch. */
+    head(repositoryId: number, signal?: AbortSignal): Promise<string>;
+    /**
+     * The documentation files of a repository at a commit: its tree read once within the request budget, never walking
+     * a skipped folder, then filtered. A caller keeps it for that commit and hands it to `changesSince`.
+     */
+    listing(repositoryId: number, commit: string, signal?: AbortSignal): Promise<TreeBlob[]>;
+    /** The documentation of each selected repository (its id in `ids`) at its default branch's head. */
+    list(selection: SourceSelection, signal?: AbortSignal): Promise<{
+        items: SourceItem[];
+        gone: SourceGone[];
+    }>;
+    /**
+     * A file's raw bytes at the commit of its version, read as a stream and cut at `maxFileBytes`: PDF, Word and HTML
+     * as bytes with their media type, the rest as UTF-8 text, each with a `github` attribution linking the file at that
+     * commit. A file GitHub no longer has, or one past the cap, is answered gone with reason `removed`.
+     */
+    read(item: SourceItem, signal?: AbortSignal): Promise<SourceRead | SourceGone>;
+    /**
+     * What a push to `after` changed, from the listing at `after` (read here when the caller holds none) against the
+     * blobs read before (`cursor`: the JSON of each path's blob). A push's own commit lists are never read, so a force
+     * push, or a push of more commits than its event lists, is read like any other. A push to another branch than the
+     * default answers no change and the cursor it was given.
+     */
+    changesSince(cursor: string | null, selection: GitHubChangesSelection, signal?: AbortSignal): Promise<SourceChanges>;
+    /** Nothing to end here: an installation is removed by the app's own call (`uninstallInstallation`). */
+    revoke(): Promise<void>;
+}
+//# sourceMappingURL=GitHubDocumentsConnector.d.ts.map

package/dist/documents/GitHubDocumentsConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubDocumentsConnector.d.ts","sourceRoot":"","sources":["../../src/documents/GitHubDocumentsConnector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,UAAU,EAEf,KAAK,eAAe,EACrB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAA8E,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvI,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4GAA4G;IAC5G,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC/B;AAeD;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,sBAAsB;IAYnE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhB1B,QAAQ,CAAC,IAAI,YAAY;IAEzB;;;;;;;OAOG;gBAEgB,UAAU,EAAE,mBAAmB,EAC/B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,SAAS,gBAAgB,EAAE,EACzC,MAAM,GAAE,UAAe,EACvB,SAAS,GAAE,OAAO,KAAa,EAC/B,OAAO,SAAkB;IAG5C,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,KAAK;IAIb,wDAAwD;IAClD,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAOvE;;;OAGG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAS9F,oGAAoG;IAC9F,IAAI,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,IAAI,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IAWlH;;;;OAIG;IACG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC;IAoCpF;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAiB1H,uGAAuG;IACjG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAG9B"}

package/dist/documents/GitHubDocumentsConnector.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview A repository's documentation as account sources, read through a GitHub App's installation: each
+ * repository's tree read once a commit within a request budget, the documentation kept by a filter, each file read as
+ * raw bytes under a cap, and a push compared by the tree at its `after` commit.
+ * @module agentos-ext-github/documents/GitHubDocumentsConnector
+ */
+import { readCapped, ReadCapExceeded, } from '@framers/agentos-ext-account-sources';
+import { discardBody, GITHUB_API_BASE, GitHubApiError, githubFetch, githubHeaders, objectOf, stringIn } from '../app/http.js';
+import { DEFAULT_MAX_FILE_BYTES, extensionOf, pathFilter, readTree, SKIPPED_FOLDERS } from './tree.js';
+/** The files answered as bytes with their media type; every other kept file is answered as text. */
+const MEDIA_TYPES = {
+    '.pdf': 'application/pdf',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+};
+/** A path with each of its segments encoded for an address. */
+function encodedPath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+/**
+ * A repository's documentation as account sources: an item's id is `<repositoryId>:<path>`, its version
+ * `<blob>@<commit>`, and the cursor of `changesSince` the JSON of each documentation path's blob at the commit last
+ * read. An installation is removed by the app's own call (`uninstallInstallation`), never by a link's connector.
+ */
+export class GitHubDocumentsConnector {
+    credential;
+    installationId;
+    repositories;
+    filter;
+    fetchImpl;
+    apiBase;
+    kind = 'github';
+    /**
+     * @param credential The app's credential; each repository is read with an installation token narrowed to it.
+     * @param installationId The installation the repositories are read through.
+     * @param repositories The repositories of the link.
+     * @param filter What is kept as documentation, and the bounds on reading it.
+     * @param fetchImpl The fetch the repositories are read with.
+     * @param apiBase GitHub's REST API, or a stand-in's address in tests.
+     */
+    constructor(credential, installationId, repositories, filter = {}, fetchImpl = fetch, apiBase = GITHUB_API_BASE) {
+        this.credential = credential;
+        this.installationId = installationId;
+        this.repositories = repositories;
+        this.filter = filter;
+        this.fetchImpl = fetchImpl;
+        this.apiBase = apiBase;
+    }
+    repository(id) {
+        const found = this.repositories.find((repository) => repository.id === id);
+        if (found === undefined)
+            throw new Error(`repository ${id} is not part of this link`);
+        return found;
+    }
+    token(id) {
+        return this.credential.installationToken(this.installationId, [id]);
+    }
+    /** The head commit of a repository's default branch. */
+    async head(repositoryId, signal) {
+        const repository = this.repository(repositoryId);
+        const url = `${this.apiBase}/repos/${repository.fullName}/branches/${encodeURIComponent(repository.defaultBranch)}`;
+        const branch = objectOf(await githubFetch(this.fetchImpl, url, { token: await this.token(repositoryId), signal }), 'a branch');
+        return stringIn(objectOf(branch.commit, "a branch's commit"), 'sha', "a branch's commit");
+    }
+    /**
+     * The documentation files of a repository at a commit: its tree read once within the request budget, never walking
+     * a skipped folder, then filtered. A caller keeps it for that commit and hands it to `changesSince`.
+     */
+    async listing(repositoryId, commit, signal) {
+        const tree = await readTree(this.fetchImpl, await this.token(repositoryId), this.repository(repositoryId).fullName, commit, this.apiBase, {
+            maxRequests: this.filter.maxTreeRequests,
+            skipFolders: this.filter.skipFolders ?? SKIPPED_FOLDERS,
+            signal,
+        });
+        return pathFilter(this.filter)(tree);
+    }
+    /** The documentation of each selected repository (its id in `ids`) at its default branch's head. */
+    async list(selection, signal) {
+        const items = [];
+        for (const id of selection.ids.map(Number)) {
+            const commit = await this.head(id, signal);
+            for (const blob of await this.listing(id, commit, signal)) {
+                items.push({ id: `${id}:${blob.path}`, title: blob.path, size: blob.size, version: `${blob.sha}@${commit}` });
+            }
+        }
+        return { items, gone: [] };
+    }
+    /**
+     * A file's raw bytes at the commit of its version, read as a stream and cut at `maxFileBytes`: PDF, Word and HTML
+     * as bytes with their media type, the rest as UTF-8 text, each with a `github` attribution linking the file at that
+     * commit. A file GitHub no longer has, or one past the cap, is answered gone with reason `removed`.
+     */
+    async read(item, signal) {
+        const [repositoryId, ...rest] = item.id.split(':');
+        const path = rest.join(':');
+        const repository = this.repository(Number(repositoryId));
+        const commit = (item.version ?? '').split('@')[1] ?? repository.defaultBranch;
+        const response = await this.fetchImpl(`${this.apiBase}/repos/${repository.fullName}/contents/${encodedPath(path)}?ref=${encodeURIComponent(commit)}`, {
+            headers: githubHeaders(await this.token(repository.id), 'application/vnd.github.raw+json'),
+            signal,
+        });
+        if (response.status === 404) {
+            await discardBody(response);
+            return { id: item.id, reason: 'removed' };
+        }
+        if (!response.ok) {
+            await discardBody(response);
+            throw new GitHubApiError(response.status);
+        }
+        let bytes;
+        try {
+            bytes = await readCapped(response, this.filter.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES);
+        }
+        catch (error) {
+            if (error instanceof ReadCapExceeded)
+                return { id: item.id, reason: 'removed' };
+            throw error;
+        }
+        const ref = {
+            kind: 'github',
+            title: path,
+            path,
+            url: `https://github.com/${repository.fullName}/blob/${commit}/${encodedPath(path)}`,
+            version: commit,
+            readAt: new Date().toISOString(),
+        };
+        const mediaType = MEDIA_TYPES[extensionOf(path)];
+        return { item, content: mediaType === undefined ? { text: new TextDecoder().decode(bytes) } : { bytes, mediaType }, ref };
+    }
+    /**
+     * What a push to `after` changed, from the listing at `after` (read here when the caller holds none) against the
+     * blobs read before (`cursor`: the JSON of each path's blob). A push's own commit lists are never read, so a force
+     * push, or a push of more commits than its event lists, is read like any other. A push to another branch than the
+     * default answers no change and the cursor it was given.
+     */
+    async changesSince(cursor, selection, signal) {
+        const id = Number(selection.ids[0]);
+        const repository = this.repository(id);
+        if (selection.ref !== undefined && selection.ref !== `refs/heads/${repository.defaultBranch}`) {
+            return { changed: [], gone: [], cursor: cursor ?? '{}' };
+        }
+        const before = new Map(Object.entries(cursor === null ? {} : JSON.parse(cursor)));
+        const after = selection.after ?? (await this.head(id, signal));
+        const blobs = selection.listing ?? (await this.listing(id, after, signal));
+        const now = new Map(blobs.map((blob) => [blob.path, blob.sha]));
+        const changed = blobs
+            .filter((blob) => before.get(blob.path) !== blob.sha)
+            .map((blob) => ({ id: `${id}:${blob.path}`, title: blob.path, size: blob.size, version: `${blob.sha}@${after}` }));
+        const gone = [...before.keys()].filter((path) => !now.has(path)).map((path) => ({ id: `${id}:${path}`, reason: 'removed' }));
+        return { changed, gone, cursor: JSON.stringify(Object.fromEntries(now)) };
+    }
+    /** Nothing to end here: an installation is removed by the app's own call (`uninstallInstallation`). */
+    async revoke() {
+        // A link's connector holds no grant of its own; the app's installation outlives any one link.
+    }
+}
+//# sourceMappingURL=GitHubDocumentsConnector.js.map

package/dist/documents/GitHubDocumentsConnector.js.map

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

package/dist/documents/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview The `./documents` entry: a GitHub App's installation mode (its JWT and installation tokens, the user's
+ * web flow, what a user token reaches, the webhook signature, the daily reconcile, the uninstall) and
+ * `GitHubDocumentsConnector`, a repository's documentation as an account source. Every call goes to GitHub's REST API
+ * over an injected `fetch`.
+ * @module agentos-ext-github/documents
+ */
+/** The documentation connector and the shape of a push it compares. */
+export { GitHubDocumentsConnector, type GitHubChangesSelection, type LinkedRepository } from './GitHubDocumentsConnector.js';
+/** A repository's tree within a request budget, and the filter that keeps its documentation. */
+export { readTree, pathFilter, extensionOf, TreeTooLarge, DOCUMENT_EXTENSIONS, SKIPPED_FOLDERS, DEFAULT_MAX_FILES, DEFAULT_MAX_FILE_BYTES, DEFAULT_MAX_TREE_REQUESTS, type ReadTreeOptions, type TreeBlob, type TreeFilter, } from './tree.js';
+/** The app's JWT and installation tokens. */
+export { appJwt, GitHubAppCredential, type GitHubAppIdentity } from '../app/credential.js';
+/** The user's web flow on the auth module's redirect flow. */
+export { GitHubAppUserFlow, GITHUB_OAUTH_ENDPOINTS, type GitHubAppClient, type GitHubOAuthEndpoints } from '../app/userFlow.js';
+/** What a user token reaches, and the app's own installations. */
+export { userOfToken, installationsOfUser, repositoriesOfUser, listInstallations, uninstallInstallation, type GitHubAccount, type GitHubInstallation, type GitHubUser, type UserRepository, } from '../app/installations.js';
+/** A webhook delivery's signature. */
+export { verifyWebhookSignature } from '../app/webhook.js';
+/** The daily reconcile. */
+export { reconcileInstallations, type MovedRepository, type ReconcileLink, type ReconcileOptions, type ReconcileOutcome, type ReconcileRepository, type UnreadableRepository, } from '../app/reconcile.js';
+/** The API version every call pins, GitHub's address, and the error of an answer outside 2xx. */
+export { GITHUB_API_BASE, GITHUB_API_VERSION, GitHubApiError, type GitHubApiOptions } from '../app/http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/documents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/documents/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uEAAuE;AACvE,OAAO,EAAE,wBAAwB,EAAE,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAC7H,gGAAgG;AAChG,OAAO,EACL,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,6CAA6C;AAC7C,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,8DAA8D;AAC9D,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChI,kEAAkE;AAClE,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,yBAAyB,CAAC;AACjC,sCAAsC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,2BAA2B;AAC3B,OAAO,EACL,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,iGAAiG;AACjG,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/documents/index.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview The `./documents` entry: a GitHub App's installation mode (its JWT and installation tokens, the user's
+ * web flow, what a user token reaches, the webhook signature, the daily reconcile, the uninstall) and
+ * `GitHubDocumentsConnector`, a repository's documentation as an account source. Every call goes to GitHub's REST API
+ * over an injected `fetch`.
+ * @module agentos-ext-github/documents
+ */
+/** The documentation connector and the shape of a push it compares. */
+export { GitHubDocumentsConnector } from './GitHubDocumentsConnector.js';
+/** A repository's tree within a request budget, and the filter that keeps its documentation. */
+export { readTree, pathFilter, extensionOf, TreeTooLarge, DOCUMENT_EXTENSIONS, SKIPPED_FOLDERS, DEFAULT_MAX_FILES, DEFAULT_MAX_FILE_BYTES, DEFAULT_MAX_TREE_REQUESTS, } from './tree.js';
+/** The app's JWT and installation tokens. */
+export { appJwt, GitHubAppCredential } from '../app/credential.js';
+/** The user's web flow on the auth module's redirect flow. */
+export { GitHubAppUserFlow, GITHUB_OAUTH_ENDPOINTS } from '../app/userFlow.js';
+/** What a user token reaches, and the app's own installations. */
+export { userOfToken, installationsOfUser, repositoriesOfUser, listInstallations, uninstallInstallation, } from '../app/installations.js';
+/** A webhook delivery's signature. */
+export { verifyWebhookSignature } from '../app/webhook.js';
+/** The daily reconcile. */
+export { reconcileInstallations, } from '../app/reconcile.js';
+/** The API version every call pins, GitHub's address, and the error of an answer outside 2xx. */
+export { GITHUB_API_BASE, GITHUB_API_VERSION, GitHubApiError } from '../app/http.js';
+//# sourceMappingURL=index.js.map

package/dist/documents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/documents/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uEAAuE;AACvE,OAAO,EAAE,wBAAwB,EAAsD,MAAM,+BAA+B,CAAC;AAC7H,gGAAgG;AAChG,OAAO,EACL,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,GAI1B,MAAM,WAAW,CAAC;AACnB,6CAA6C;AAC7C,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAA0B,MAAM,sBAAsB,CAAC;AAC3F,8DAA8D;AAC9D,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAmD,MAAM,oBAAoB,CAAC;AAChI,kEAAkE;AAClE,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GAKtB,MAAM,yBAAyB,CAAC;AACjC,sCAAsC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,2BAA2B;AAC3B,OAAO,EACL,sBAAsB,GAOvB,MAAM,qBAAqB,CAAC;AAC7B,iGAAiG;AACjG,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAyB,MAAM,gBAAgB,CAAC"}

package/dist/documents/tree.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview A repository's tree at a commit, read within a request budget, and the filter that keeps its
+ * documentation. GitHub cuts a recursive tree past 100,000 entries or 7 MB and marks it `truncated`; such a tree is
+ * read again one subtree at a time.
+ * @module agentos-ext-github/documents/tree
+ */
+/** One file of a tree: its path from the repository's root, its blob and its size in bytes. */
+export interface TreeBlob {
+    path: string;
+    sha: string;
+    size: number;
+}
+/** What a repository's documentation is: the files kept and the bounds on reading them. Each has a default. */
+export interface TreeFilter {
+    /** The file extensions kept, with their dot ({@link DOCUMENT_EXTENSIONS} when absent). */
+    extensions?: readonly string[];
+    /** The folders skipped at any depth, by name ({@link SKIPPED_FOLDERS} when absent). */
+    skipFolders?: readonly string[];
+    /** At most this many files, in path order ({@link DEFAULT_MAX_FILES} when absent). */
+    maxFiles?: number;
+    /** A file larger than this is left out of a listing, and a read past it is answered gone ({@link DEFAULT_MAX_FILE_BYTES} when absent). */
+    maxFileBytes?: number;
+    /** At most this many tree requests to list one commit ({@link DEFAULT_MAX_TREE_REQUESTS} when absent). */
+    maxTreeRequests?: number;
+}
+/** The documentation kept by default: Markdown, text, reStructuredText, HTML, PDF and Word files. */
+export declare const DOCUMENT_EXTENSIONS: readonly string[];
+/** The folders skipped by default: dependencies, build output and vendored code. */
+export declare const SKIPPED_FOLDERS: readonly string[];
+/** The files kept by default. */
+export declare const DEFAULT_MAX_FILES = 2000;
+/** The largest file kept by default: 10 MiB. */
+export declare const DEFAULT_MAX_FILE_BYTES = 10485760;
+/** The tree requests one listing makes by default. */
+export declare const DEFAULT_MAX_TREE_REQUESTS = 50;
+/** A tree that cannot be read within its request budget. */
+export declare class TreeTooLarge extends Error {
+    readonly maxRequests: number;
+    /** @param maxRequests The budget the tree needed more than. */
+    constructor(maxRequests: number);
+}
+/** The budget of a tree read, the folders it never walks into, and its abort signal. */
+export interface ReadTreeOptions {
+    /** At most this many requests ({@link DEFAULT_MAX_TREE_REQUESTS} when absent). */
+    maxRequests?: number;
+    /** Folders, by name, whose files are left out and which a read by subtree never requests. */
+    skipFolders?: readonly string[];
+    signal?: AbortSignal;
+}
+/** A file's extension with its dot, in lower case, or `''` when its name has none. */
+export declare function extensionOf(path: string): string;
+/**
+ * Every file of a repository's tree at a commit (symbolic links aside). The tree is asked for recursively; when GitHub
+ * answers it truncated, its top level is read and each subtree is asked for the same way, so only the parts too large
+ * for one answer cost a request per folder. Each request counts against `maxRequests`, and the read throws
+ * {@link TreeTooLarge} rather than make one more.
+ *
+ * @param fetchImpl The fetch the tree is read with.
+ * @param token An installation token that reads the repository.
+ * @param repo The repository's full name, `owner/name`.
+ * @param commit The commit whose tree is read.
+ * @param apiBase GitHub's REST API, or a stand-in's address in tests.
+ * @param options The request budget, the folders skipped and an abort signal.
+ */
+export declare function readTree(fetchImpl: typeof fetch, token: string, repo: string, commit: string, apiBase?: string, options?: ReadTreeOptions): Promise<TreeBlob[]>;
+/**
+ * The filter that keeps a tree's documentation: the extensions kept, nothing under a skipped folder, nothing past the
+ * size cap, in path order, at most `maxFiles`.
+ */
+export declare function pathFilter(filter?: TreeFilter): (blobs: readonly TreeBlob[]) => TreeBlob[];
+//# sourceMappingURL=tree.d.ts.map

package/dist/documents/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/documents/tree.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,+GAA+G;AAC/G,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,uFAAuF;IACvF,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0IAA0I;IAC1I,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0GAA0G;IAC1G,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAA2E,CAAC;AAE7H,oFAAoF;AACpF,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAuE,CAAC;AAErH,iCAAiC;AACjC,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAEvC,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,WAAa,CAAC;AAEjD,sDAAsD;AACtD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAK5C,4DAA4D;AAC5D,qBAAa,YAAa,SAAQ,KAAK;IAEzB,QAAQ,CAAC,WAAW,EAAE,MAAM;IADxC,+DAA+D;gBAC1C,WAAW,EAAE,MAAM;CAIzC;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAsBD,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,OAAO,KAAK,EACvB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,MAAwB,EACjC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,EAAE,CAAC,CAsCrB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAE,UAAe,GAAG,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,KAAK,QAAQ,EAAE,CAU9F"}

package/dist/documents/tree.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview A repository's tree at a commit, read within a request budget, and the filter that keeps its
+ * documentation. GitHub cuts a recursive tree past 100,000 entries or 7 MB and marks it `truncated`; such a tree is
+ * read again one subtree at a time.
+ * @module agentos-ext-github/documents/tree
+ */
+import { arrayOf, GITHUB_API_BASE, githubFetch, objectOf, stringIn } from '../app/http.js';
+/** The documentation kept by default: Markdown, text, reStructuredText, HTML, PDF and Word files. */
+export const DOCUMENT_EXTENSIONS = ['.md', '.markdown', '.txt', '.rst', '.html', '.htm', '.pdf', '.docx'];
+/** The folders skipped by default: dependencies, build output and vendored code. */
+export const SKIPPED_FOLDERS = ['node_modules', 'vendor', 'dist', 'build', '.git', 'third_party'];
+/** The files kept by default. */
+export const DEFAULT_MAX_FILES = 2_000;
+/** The largest file kept by default: 10 MiB. */
+export const DEFAULT_MAX_FILE_BYTES = 10_485_760;
+/** The tree requests one listing makes by default. */
+export const DEFAULT_MAX_TREE_REQUESTS = 50;
+/** A symbolic link's mode in a tree; its blob holds the link's target, not a document. */
+const SYMLINK_MODE = '120000';
+/** A tree that cannot be read within its request budget. */
+export class TreeTooLarge extends Error {
+    maxRequests;
+    /** @param maxRequests The budget the tree needed more than. */
+    constructor(maxRequests) {
+        super(`the tree needs more than ${maxRequests} requests to read`);
+        this.maxRequests = maxRequests;
+        this.name = 'TreeTooLarge';
+    }
+}
+function entryOf(value) {
+    const fields = objectOf(value, 'a tree entry');
+    return {
+        path: stringIn(fields, 'path', 'a tree entry'),
+        type: stringIn(fields, 'type', 'a tree entry'),
+        sha: stringIn(fields, 'sha', 'a tree entry'),
+        mode: typeof fields.mode === 'string' ? fields.mode : '',
+        size: typeof fields.size === 'number' ? fields.size : null,
+    };
+}
+/** A file's extension with its dot, in lower case, or `''` when its name has none. */
+export function extensionOf(path) {
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    return dot <= 0 ? '' : name.slice(dot).toLowerCase();
+}
+function inSkippedFolder(path, skip) {
+    return path.split('/').slice(0, -1).some((folder) => skip.has(folder));
+}
+/**
+ * Every file of a repository's tree at a commit (symbolic links aside). The tree is asked for recursively; when GitHub
+ * answers it truncated, its top level is read and each subtree is asked for the same way, so only the parts too large
+ * for one answer cost a request per folder. Each request counts against `maxRequests`, and the read throws
+ * {@link TreeTooLarge} rather than make one more.
+ *
+ * @param fetchImpl The fetch the tree is read with.
+ * @param token An installation token that reads the repository.
+ * @param repo The repository's full name, `owner/name`.
+ * @param commit The commit whose tree is read.
+ * @param apiBase GitHub's REST API, or a stand-in's address in tests.
+ * @param options The request budget, the folders skipped and an abort signal.
+ */
+export async function readTree(fetchImpl, token, repo, commit, apiBase = GITHUB_API_BASE, options = {}) {
+    const maxRequests = options.maxRequests ?? DEFAULT_MAX_TREE_REQUESTS;
+    const skip = new Set(options.skipFolders ?? []);
+    const blobs = [];
+    let requests = 0;
+    const read = async (sha, recursive) => {
+        if (requests >= maxRequests)
+            throw new TreeTooLarge(maxRequests);
+        requests += 1;
+        const url = `${apiBase}/repos/${repo}/git/trees/${encodeURIComponent(sha)}${recursive ? '?recursive=1' : ''}`;
+        const answer = objectOf(await githubFetch(fetchImpl, url, { token, signal: options.signal }), 'a tree');
+        return { truncated: answer.truncated === true, entries: arrayOf(answer.tree, 'a tree').map(entryOf) };
+    };
+    const keep = (entry, path) => {
+        if (entry.type === 'blob' && entry.mode !== SYMLINK_MODE && !inSkippedFolder(path, skip)) {
+            blobs.push({ path, sha: entry.sha, size: entry.size ?? 0 });
+        }
+    };
+    const walk = async (sha, prefix) => {
+        const whole = await read(sha, true);
+        if (!whole.truncated) {
+            for (const entry of whole.entries)
+                keep(entry, `${prefix}${entry.path}`);
+            return;
+        }
+        const top = await read(sha, false);
+        for (const entry of top.entries) {
+            if (entry.type === 'tree') {
+                if (!skip.has(entry.path))
+                    await walk(entry.sha, `${prefix}${entry.path}/`);
+            }
+            else {
+                keep(entry, `${prefix}${entry.path}`);
+            }
+        }
+    };
+    await walk(commit, '');
+    return blobs;
+}
+/**
+ * The filter that keeps a tree's documentation: the extensions kept, nothing under a skipped folder, nothing past the
+ * size cap, in path order, at most `maxFiles`.
+ */
+export function pathFilter(filter = {}) {
+    const extensions = new Set((filter.extensions ?? DOCUMENT_EXTENSIONS).map((extension) => extension.toLowerCase()));
+    const skip = new Set(filter.skipFolders ?? SKIPPED_FOLDERS);
+    const maxFiles = filter.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxFileBytes = filter.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    return (blobs) => blobs
+        .filter((blob) => extensions.has(extensionOf(blob.path)) && blob.size <= maxFileBytes && !inSkippedFolder(blob.path, skip))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .slice(0, maxFiles);
+}
+//# sourceMappingURL=tree.js.map

package/dist/documents/tree.js.map

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

package/manifest.json

@@ -2,8 +2,8 @@
   "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
   "id": "com.framers.integrations.github",
   "name": "GitHub Extension",
-  "version": "0.1.4",
-  "description": "GitHub API tools — 26 tools for repos, issues, PRs, branches, commits, releases, Actions, files, gists, and codebase indexing.",
+  "version": "0.2.1",
+  "description": "GitHub API tools: 26 tools for repos, issues, PRs, branches, commits, releases, Actions, files, gists, and codebase indexing. Its ./documents entry adds a GitHub App's installation mode (the app's JWT, installation tokens, the user's web flow, webhook signatures, a daily reconcile) and a connector that reads a repository's documentation as account sources.",
   "categories": ["tool", "developer"],
   "extensions": [
     { "kind": "tool", "id": "githubSearch", "displayName": "GitHub Search" },
@@ -44,6 +44,8 @@
     "File reading and writing",
     "Release listing and creation",
     "GitHub Actions workflow listing and triggering",
-    "Gist creation"
+    "Gist creation",
+    "GitHub App installation mode: app JWT, installation tokens, the user's web flow, installations and repositories a user can reach, webhook signatures, daily reconcile",
+    "Repository documentation as account sources, read by tree with raw file reads and compared by tree on a push"
   ]
 }

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "@framers/agentos-ext-github",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "type": "module",
   "description": "GitHub API tools for AgentOS — search repos/code, manage issues/PRs, read files, create gists",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./documents": {
+      "import": "./dist/documents/index.js",
+      "types": "./dist/documents/index.d.ts"
+    },
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
   "keywords": [
     "agentos",
     "extension",
@@ -22,16 +34,17 @@
     "manifest.json"
   ],
   "dependencies": {
-    "@octokit/rest": "^21.0.0"
+    "@framers/agentos-ext-account-sources": "^0.1.0",
+    "@octokit/rest": "^22.0.1"
   },
   "peerDependencies": {
-    "@framers/agentos": ">=0.10.40"
+    "@framers/agentos": ">=0.13.40"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.7",
-    "@framers/agentos": "^0.13.47"
+    "@framers/agentos": "^0.13.89"
   },
   "engines": {
     "node": ">=22"