@framers/agentos-ext-github 0.7.0 → 0.9.0

package/dist/documents/links.js

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview The GitHub addresses a person pastes, read without a request: a repository, a folder or a file on
+ * github.com, and a file on raw.githubusercontent.com. Any other address on GitHub's hosts is refused, so no form of a
+ * GitHub address is read as another site's page; an address on any other host is not GitHub's. A text is read as the
+ * URL standard reads an address, so every form a browser opens as a GitHub address is answered as one.
+ * @module agentos-ext-github/documents/links
+ */
+/** The hosts of GitHub's site, where a repository, a folder and a file are read. */
+const SITE_HOSTS = new Set(['github.com', 'www.github.com']);
+/** The host that serves a repository's files as their bytes alone. */
+const RAW_HOST = 'raw.githubusercontent.com';
+/** GitHub's other hosts, whose addresses name no repository, folder or file read here: gists, the API, archives, uploads. */
+const OTHER_HOSTS = new Set(['gist.github.com', 'api.github.com', 'codeload.github.com', 'uploads.github.com']);
+/** The domain under which GitHub serves its users' content: raw files, gists, release assets, avatars. */
+const CONTENT_DOMAIN = 'githubusercontent.com';
+/**
+ * The domain of GitHub Enterprise Cloud with data residency: each enterprise on a subdomain of its own, its API on
+ * `api.<subdomain>.ghe.com`
+ * (https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency).
+ * Its repositories are not read here.
+ */
+const ENTERPRISE_DOMAIN = 'ghe.com';
+/** First path segments of github.com that name GitHub's own pages, never an account. */
+const SITE_PAGES = new Set([
+    'about', 'account', 'apps', 'codespaces', 'collections', 'contact', 'copilot', 'customer-stories', 'dashboard',
+    'enterprise', 'events', 'explore', 'features', 'issues', 'join', 'login', 'logout', 'marketplace', 'new',
+    'notifications', 'organizations', 'orgs', 'pricing', 'pulls', 'search', 'security', 'sessions', 'settings', 'site',
+    'sponsors', 'stars', 'topics', 'trending', 'users', 'watching',
+]);
+/** An account's login: letters, digits, dashes and underscores, starting with a letter or a digit. */
+const OWNER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
+/** A repository's name: letters, digits, dots, dashes and underscores. */
+const REPO = /^[A-Za-z0-9._-]{1,100}$/;
+/**
+ * A scheme and the slashes before an address's host, as the URL standard reads them
+ * (https://url.spec.whatwg.org/#scheme-state), in any case: after `http`, `https`, `ws`, `wss` and `ftp`, special
+ * schemes, any run of `/` and `\`, none included (https://url.spec.whatwg.org/#special-authority-slashes-state); after
+ * `file`, two of them (https://url.spec.whatwg.org/#file-slash-state), and none when a third follows, since the host is
+ * then empty (https://url.spec.whatwg.org/#file-host-state) and the address names no host; after any other scheme
+ * (`git://`, `ssh://`), `//`.
+ */
+const AUTHORITY = /^(?:(?:https?|wss?|ftp):[/\\]*|file:[/\\]{2}(?![/\\])|(?!file:)[a-z][a-z0-9+.-]*:\/\/)/i;
+/** The characters the URL standard removes wherever they stand in an address: tab, line feed and carriage return. */
+const TAB_OR_NEWLINE = /[\t\n\r]/g;
+/** A white space character, as `String.prototype.trim` drops it. */
+const WHITE_SPACE = /\s/;
+/** An opaque address, such as `mailto:` or `javascript:`, which names no host. */
+const OPAQUE = /^[A-Za-z][A-Za-z0-9+-]*:/;
+/**
+ * Credentials before a host and a path with no scheme, `<user>:<password>@<host>/...`, which reads as an opaque address
+ * by the URL standard and which a browser opens as an `https://` address carrying the credentials: an `@` before the
+ * first `/`, `?` or `#`, and a `/` after the host. An opaque address of an `@` alone (`mailto:someone@github.com`) has
+ * no path and stays opaque.
+ */
+const CREDENTIALS = /^[^/?#\s@]*@[^/?#\s]*\//;
+/** Git's address of a repository over SSH without a scheme: `git@github.com:<owner>/<repo>.git`. */
+const SCP = /^([A-Za-z0-9._-]+)@([^/:\s]+):(?!\/)(.*)$/;
+/** A refusal: the address is GitHub's, and names nothing read here. */
+function refused() {
+    return { kind: 'refused' };
+}
+/**
+ * True for a character dropped around a pasted address: a C0 control or a space, as the URL standard drops them
+ * (https://url.spec.whatwg.org/#concept-basic-url-parser), or any other white space, as `String.prototype.trim` does.
+ */
+function isAround(code) {
+    return code <= 0x20 || WHITE_SPACE.test(String.fromCharCode(code));
+}
+/**
+ * A pasted text as the URL standard reads an address: without the C0 controls, spaces and other white space around it,
+ * and without any tab or newline within it. Read by a loop at each end, so a text of many such characters costs one
+ * pass.
+ */
+function cleaned(text) {
+    let start = 0;
+    let end = text.length;
+    while (start < end && isAround(text.charCodeAt(start)))
+        start += 1;
+    while (end > start && isAround(text.charCodeAt(end - 1)))
+        end -= 1;
+    return text.slice(start, end).replace(TAB_OR_NEWLINE, '');
+}
+/**
+ * The address a text holds, read as its `https://` form: the scheme and the slashes before the host are dropped
+ * whatever the scheme, and a text without one (`github.com/<owner>/<repo>`,
+ * `<user>:<password>@github.com/<owner>/<repo>`) is read as if it had it. Null for an opaque address (a scheme the URL
+ * standard does not treat as special, without `//`) and for text that is no address.
+ */
+function addressOf(text) {
+    const authority = AUTHORITY.exec(text);
+    if (authority === null && OPAQUE.test(text) && !CREDENTIALS.test(text))
+        return null;
+    try {
+        return new URL(`https://${authority === null ? text : text.slice(authority[0].length)}`);
+    }
+    catch {
+        // Text that is no address; the parser's message would quote it.
+        return null;
+    }
+}
+/**
+ * A host as an address names it, in lower case, without the dots that end it: the URL standard keeps every one
+ * (`github.com..` is a host of its own there), and GitHub's hosts are answered whatever their spelling. Read by a loop,
+ * so a host of many dots costs one pass.
+ */
+function hostOf(host) {
+    let end = host.length;
+    while (end > 0 && host.charCodeAt(end - 1) === 0x2e)
+        end -= 1;
+    return host.slice(0, end).toLowerCase();
+}
+/** True for `domain` itself or a host under it. */
+function isUnder(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/**
+ * True for a host of GitHub's: its site, its raw files, its other hosts, the hosts of its users' content, and the
+ * hosts of GitHub Enterprise Cloud with data residency.
+ */
+function isGitHubHost(host) {
+    return SITE_HOSTS.has(host) || host === RAW_HOST || OTHER_HOSTS.has(host) || isUnder(host, CONTENT_DOMAIN) || isUnder(host, ENTERPRISE_DOMAIN);
+}
+/**
+ * An address's path as its segments, each decoded, without a trailing slash; null for a path with an empty segment
+ * or an escape that does not decode.
+ */
+function segmentsOf(pathname) {
+    const raw = pathname.split('/').slice(1);
+    if (raw.length > 0 && raw[raw.length - 1] === '')
+        raw.pop();
+    const segments = [];
+    for (const segment of raw) {
+        if (segment === '')
+            return null;
+        try {
+            segments.push(decodeURIComponent(segment));
+        }
+        catch {
+            return null;
+        }
+    }
+    return segments;
+}
+/** True for a text holding a control character, which no ref or path a link names holds. */
+function hasControl(text) {
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * A folder's or a file's `<ref>/<path>` from the segments after `/tree/`, `/blob/` or `/raw/`, GitHub's own form of a
+ * branch by its full name (`refs/heads/<branch>`) read as the branch. Null for none, for another kind of reference
+ * (`refs/tags/`, `refs/pull/`), and for a text with an empty, `.` or `..` segment or a control character once decoded.
+ */
+function refAndPathOf(segments) {
+    let parts = segments;
+    if (parts[0] === 'refs') {
+        if (parts[1] !== 'heads' || parts.length < 3)
+            return null;
+        parts = parts.slice(2);
+    }
+    const text = parts.join('/');
+    if (text === '' || hasControl(text))
+        return null;
+    return text.split('/').every((part) => part !== '' && part !== '.' && part !== '..') ? text : null;
+}
+/** The owner and the repository of an address's first two segments, `.git` dropped; null when either is not one. */
+function repositoryOf(segments) {
+    const owner = segments[0];
+    const name = segments[1];
+    const repo = name.endsWith('.git') ? name.slice(0, -'.git'.length) : name;
+    if (!OWNER.test(owner) || SITE_PAGES.has(owner.toLowerCase()) || !REPO.test(repo) || repo === '.' || repo === '..')
+        return null;
+    return { owner, repo };
+}
+/** What a path on github.com names. */
+function siteLink(segments) {
+    if (segments.length < 2)
+        return refused();
+    const repository = repositoryOf(segments);
+    if (repository === null)
+        return refused();
+    if (segments.length === 2)
+        return { kind: 'github_repository', ...repository };
+    const view = segments[2];
+    if (view !== 'tree' && view !== 'blob' && view !== 'raw')
+        return refused();
+    const refAndPath = refAndPathOf(segments.slice(3));
+    if (refAndPath === null)
+        return refused();
+    const named = refAndPath.includes('/');
+    // GitHub shows the folder for a blob address that names a ref alone, and answers none for a raw one.
+    if (view === 'tree' || (view === 'blob' && !named))
+        return { kind: 'github_folder', ...repository, refAndPath };
+    if (!named)
+        return refused();
+    return { kind: 'github_file', ...repository, refAndPath, raw: view === 'raw' };
+}
+/** What a path on raw.githubusercontent.com names: `/<owner>/<repo>/<ref>/<path>`. */
+function rawLink(segments) {
+    if (segments.length < 4)
+        return refused();
+    const repository = repositoryOf(segments);
+    const refAndPath = refAndPathOf(segments.slice(2));
+    if (repository === null || refAndPath === null || !refAndPath.includes('/'))
+        return refused();
+    return { kind: 'github_file', ...repository, refAndPath, raw: true };
+}
+/**
+ * What a GitHub address names, read without a request. Null for an address whose host is not GitHub's, and for text
+ * that is no address; `refused` for an address on GitHub's hosts that names no repository, folder or file read here: an
+ * account, an issue, a pull request, a wiki, a release, a commit, a tag by its full name (`refs/tags/<tag>`), a gist,
+ * the API, an archive, GitHub's own pages, an address that carries credentials (with a scheme or without one:
+ * `<user>:<password>@github.com/...`), a host of GitHub Enterprise Cloud with data residency (`<subdomain>.ghe.com`),
+ * and a host other than github.com, www.github.com and raw.githubusercontent.com. The scheme (or its absence), a port,
+ * the dots that end a host, `.git`, a trailing slash, a query and a fragment are ignored, and so is the `git` user of
+ * an SSH address (`git@github.com:<owner>/<repo>.git`).
+ *
+ * The text is read as the URL standard reads an address: the C0 controls and spaces around it, and any other white
+ * space there, are dropped, and every tab and newline in it; after `http`, `https`, `ws`, `wss` and `ftp` any run of
+ * `/` and `\` stands before the host, none included (`https:github.com/<owner>/<repo>`,
+ * `https:\\github.com\<owner>\<repo>`), as a browser opens such an address; after `file`, two of them; after any
+ * other scheme, `//`. A backslash in the path is a slash.
+ *
+ * A folder's and a file's ref and path are answered as one text, each segment decoded, since a branch name may hold a
+ * slash; GitHub's form of a branch by its full name, `refs/heads/<branch>`, is read as the branch. A `/blob/` address
+ * whose text has no slash names a ref alone and is a folder, as GitHub shows it (its `/blob/<ref>` redirects to
+ * `/tree/<ref>`); one whose text has a slash is a file, which `resolveRef` may settle as a ref alone (an empty path).
+ *
+ * @param text The address as pasted; the controls and spaces around it are dropped.
+ * @throws TypeError when `text` is not a string.
+ */
+export function parseGitHubLink(text) {
+    if (typeof text !== 'string')
+        throw new TypeError('a link is a string');
+    const pasted = cleaned(text);
+    if (pasted === '')
+        return null;
+    const scp = SCP.exec(pasted);
+    if (scp !== null) {
+        const host = hostOf(scp[2]);
+        if (!isGitHubHost(host))
+            return null;
+        if (scp[1] !== 'git' || !SITE_HOSTS.has(host))
+            return refused();
+        const address = addressOf(`${host}/${scp[3]}`);
+        const segments = address === null ? null : segmentsOf(address.pathname);
+        return segments === null ? refused() : siteLink(segments);
+    }
+    const address = addressOf(pasted);
+    if (address === null)
+        return null;
+    const host = hostOf(address.hostname);
+    if (!isGitHubHost(host))
+        return null;
+    // A token in an address is a secret, never something to read a repository with.
+    if ((address.username !== '' && address.username !== 'git') || address.password !== '')
+        return refused();
+    const segments = segmentsOf(address.pathname);
+    if (segments === null)
+        return refused();
+    if (SITE_HOSTS.has(host))
+        return siteLink(segments);
+    if (host === RAW_HOST)
+        return rawLink(segments);
+    return refused();
+}
+//# sourceMappingURL=links.js.map

package/dist/documents/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/documents/links.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,oFAAoF;AACpF,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAElF,sEAAsE;AACtE,MAAM,QAAQ,GAAG,2BAA2B,CAAC;AAE7C,6HAA6H;AAC7H,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,oBAAoB,CAAC,CAAC,CAAC;AAErI,0GAA0G;AAC1G,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAEpC,wFAAwF;AACxF,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,EAAE,WAAW;IAC9G,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK;IACxG,eAAe,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM;IAClH,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU;CAC/D,CAAC,CAAC;AAEH,sGAAsG;AACtG,MAAM,KAAK,GAAG,kCAAkC,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,IAAI,GAAG,yBAAyB,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,SAAS,GAAG,yFAAyF,CAAC;AAE5G,qHAAqH;AACrH,MAAM,cAAc,GAAG,WAAW,CAAC;AAEnC,oEAAoE;AACpE,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB,kFAAkF;AAClF,MAAM,MAAM,GAAG,0BAA0B,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,GAAG,yBAAyB,CAAC;AAE9C,oGAAoG;AACpG,MAAM,GAAG,GAAG,2CAA2C,CAAC;AAExD,uEAAuE;AACvE,SAAS,OAAO;IACd,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,IAAI,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,OAAO,KAAK,GAAG,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAAE,KAAK,IAAI,CAAC,CAAC;IACnE,OAAO,GAAG,GAAG,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QAAE,GAAG,IAAI,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,SAAS,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACpF,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,WAAW,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,IAAY;IAC1B,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,OAAO,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI;QAAE,GAAG,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;AAC1C,CAAC;AAED,mDAAmD;AACnD,SAAS,OAAO,CAAC,IAAY,EAAE,MAAc;IAC3C,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,QAAQ,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;AACjJ,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,QAAgB;IAClC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE;QAAE,GAAG,CAAC,GAAG,EAAE,CAAC;IAC5D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,OAAO,IAAI,GAAG,EAAE,CAAC;QAC1B,IAAI,OAAO,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,4FAA4F;AAC5F,SAAS,UAAU,CAAC,IAAY;IAC9B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,QAA2B;IAC/C,IAAI,KAAK,GAAG,QAAQ,CAAC;IACrB,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;QACxB,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1D,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,EAAE,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACrG,CAAC;AAED,oHAAoH;AACpH,SAAS,YAAY,CAAC,QAA2B;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1E,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChI,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,uCAAuC;AACvC,SAAS,QAAQ,CAAC,QAA2B;IAC3C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,EAAE,CAAC;IAC1C,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,OAAO,EAAE,CAAC;IAC1C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,GAAG,UAAU,EAAE,CAAC;IAC/E,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,OAAO,EAAE,CAAC;IAC3E,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,OAAO,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACvC,qGAAqG;IACrG,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,UAAU,EAAE,UAAU,EAAE,CAAC;IAChH,IAAI,CAAC,KAAK;QAAE,OAAO,OAAO,EAAE,CAAC;IAC7B,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,KAAK,KAAK,EAAE,CAAC;AACjF,CAAC;AAED,sFAAsF;AACtF,SAAS,OAAO,CAAC,QAA2B;IAC1C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,EAAE,CAAC;IAC1C,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,EAAE,CAAC;IAC9F,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,oBAAoB,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,OAAO,EAAE,CAAC;QAChE,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxE,OAAO,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,gFAAgF;IAChF,IAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,EAAE,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,KAAK,EAAE;QAAE,OAAO,OAAO,EAAE,CAAC;IACzG,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,OAAO,EAAE,CAAC;IACxC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChD,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC"}

package/dist/documents/tree.d.ts

@@ -48,6 +48,11 @@ export declare const CODE_EXTENSIONS: readonly string[];
 export declare const GENERATED_CODE_ENDINGS: readonly string[];
 /** True for a code file a tool wrote, by its name's ending ({@link GENERATED_CODE_ENDINGS}), in any case. */
 export declare function isGeneratedCode(path: string): boolean;
+/**
+ * The image files `planTree` answers as images by default: raster and vector images and icons. An image is never kept
+ * as documentation unless a filter's `extensions` names its extension.
+ */
+export declare const IMAGE_EXTENSIONS: readonly string[];
 /** The files kept by default. */
 export declare const DEFAULT_MAX_FILES = 2000;
 /** The largest file kept by default: 10 MiB. */
@@ -104,6 +109,14 @@ export declare function extensionOf(path: string): string;
  * @throws TypeError before any request when `repository` is a number that is not a positive integer.
  */
 export declare function readTree(fetchImpl: typeof fetch, token: string, repository: number | string, commit: string, apiBase?: string, options?: ReadTreeOptions): Promise<TreeBlob[]>;
+/**
+ * The path of a folder or a file of a repository a caller names, checked: absent and `''` name the whole repository
+ * and answer `''`. A path with an empty, `.` or `..` segment (a leading or a trailing slash among them), and a value
+ * that is not text, throw a `TypeError` that quotes none of it.
+ */
+export declare function pathOf(path: unknown): string;
+/** The blobs at `path` or under it: a folder's files, or the one file it names; every blob for `''`. */
+export declare function withinPath<T extends TreeBlob>(blobs: readonly T[], path: string): T[];
 /**
  * The filter that keeps a tree's documentation: the extensions kept, and with `includeCode` the code extensions beside
  * them; nothing under a skipped folder, nothing past the size cap, at most `maxFiles`, in path order. With code asked
@@ -112,4 +125,50 @@ export declare function readTree(fetchImpl: typeof fetch, token: string, reposit
  * turning code on never drops a document a listing held.
  */
 export declare function pathFilter(filter?: TreeFilter): (blobs: readonly TreeBlob[]) => TreeBlob[];
+/**
+ * Why `planTree` leaves a file out: `folder` under a skipped folder; `kind` for a file that is neither documentation,
+ * code nor an image (data, configuration, a binary, a file with no extension); `image` for an image; `code` for code
+ * while code is not asked for; `generated` for code a tool wrote ({@link isGeneratedCode}), left out while code is asked
+ * for; `size` past the size bound; `count` past `maxFiles`.
+ */
+export type PlanSkipReason = 'folder' | 'kind' | 'image' | 'code' | 'generated' | 'size' | 'count';
+/** One file of a tree with what becomes of it: kept as a `note`, or skipped with the reason. */
+export interface PlannedBlob extends TreeBlob {
+    outcome: 'note' | {
+        skipped: PlanSkipReason;
+    };
+}
+/** What `planTree` keeps: a {@link TreeFilter}, a lower bound for a code file and the extensions read as images. */
+export interface PlanTreeOptions extends TreeFilter {
+    /**
+     * While code is asked for (`includeCode`), a file of a code extension ({@link CODE_EXTENSIONS}) larger than this many
+     * bytes is skipped with `size`, whatever `extensions` names, below `maxFileBytes` when it is lower; `maxFileBytes`
+     * when absent. A non-negative integer.
+     */
+    maxCodeBytes?: number;
+    /** The extensions, with their dot, of the files skipped as images ({@link IMAGE_EXTENSIONS} when absent). */
+    imageExtensions?: readonly string[];
+    /**
+     * A folder of the tree, or a file, by its path with no leading or trailing slash: only the files at it or under it
+     * are planned, and `maxFiles` counts them alone, as a listing keeps them under the same `path`. The whole tree when
+     * absent or `''`; a path with an empty, `.` or `..` segment, or one that is not text, is a `TypeError`.
+     */
+    path?: string;
+}
+/**
+ * `pathFilter`'s sibling: every file of a tree, in path order, with its outcome under the same filter, so a caller can
+ * show what is left out and why. The files answered `note` are exactly those `pathFilter` keeps under the filter, a
+ * code file past `maxCodeBytes` aside; each file left out carries the first reason it is left out, in this order: where
+ * it is (`folder`), what it is (`kind`, `image`, `code`, `generated`), how large it is (`size`) and how many came first
+ * (`count`, the documentation keeping its places first and the code taking the room left, as in `pathFilter`). A file
+ * whose extension the filter's `extensions` names is documentation, an image's included; while code is asked for, one
+ * of a code extension keeps `maxCodeBytes` as its bound, as a code file a tool wrote is left out whatever `extensions`
+ * names. Each answer is a new object holding the file's `path`, `sha` and `size` and its `outcome`. With a `path`, only
+ * the files of that folder, or the one file it names, are planned, and counted alone.
+ *
+ * @param blobs The files of a tree, as `readTree` answers them.
+ * @param options The filter, the code bound, the image extensions and the folder.
+ * @throws TypeError when `maxCodeBytes` is not a non-negative integer, or `path` is not a path.
+ */
+export declare function planTree(blobs: readonly TreeBlob[], options?: PlanTreeOptions): PlannedBlob[];
 //# sourceMappingURL=tree.d.ts.map

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

@@ -1 +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;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,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;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAM5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAGnD,CAAC;AAEF,6GAA6G;AAC7G,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED,iCAAiC;AACjC,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAEvC,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,WAAa,CAAC;AAEjD,sDAAsD;AACtD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAK5C;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAMnC,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,MAAM,EAAE,kBAAkB;IANrC;;;OAGG;gBAEQ,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,kBAA6B;CAKjD;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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,OAAO,KAAK,EACvB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,MAAwB,EACjC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,EAAE,CAAC,CAyCrB;AAOD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAE,UAAe,GAAG,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,KAAK,QAAQ,EAAE,CAe9F"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/documents/tree.ts"],"names":[],"mappings":"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"}

package/dist/documents/tree.js

@@ -36,6 +36,13 @@ export function isGeneratedCode(path) {
     const name = path.slice(path.lastIndexOf('/') + 1).toLowerCase();
     return GENERATED_CODE_ENDINGS.some((ending) => name.endsWith(ending));
 }
+/**
+ * The image files `planTree` answers as images by default: raster and vector images and icons. An image is never kept
+ * as documentation unless a filter's `extensions` names its extension.
+ */
+export const IMAGE_EXTENSIONS = [
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.bmp', '.ico', '.tif', '.tiff', '.avif', '.heic', '.heif',
+];
 /** The files kept by default. */
 export const DEFAULT_MAX_FILES = 2_000;
 /** The largest file kept by default: 10 MiB. */
@@ -149,6 +156,26 @@ export async function readTree(fetchImpl, token, repository, commit, apiBase = G
 function byPath(a, b) {
     return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
 }
+/**
+ * The path of a folder or a file of a repository a caller names, checked: absent and `''` name the whole repository
+ * and answer `''`. A path with an empty, `.` or `..` segment (a leading or a trailing slash among them), and a value
+ * that is not text, throw a `TypeError` that quotes none of it.
+ */
+export function pathOf(path) {
+    if (path === undefined || path === '')
+        return '';
+    if (typeof path !== 'string' || path.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new TypeError('a path is text with no empty, . or .. segment');
+    }
+    return path;
+}
+/** The blobs at `path` or under it: a folder's files, or the one file it names; every blob for `''`. */
+export function withinPath(blobs, path) {
+    if (path === '')
+        return [...blobs];
+    const folder = `${path}/`;
+    return blobs.filter((blob) => blob.path === path || blob.path.startsWith(folder));
+}
 /**
  * The filter that keeps a tree's documentation: the extensions kept, and with `includeCode` the code extensions beside
  * them; nothing under a skipped folder, nothing past the size cap, at most `maxFiles`, in path order. With code asked
@@ -172,4 +199,69 @@ export function pathFilter(filter = {}) {
         return [...documentation, ...sources.slice(0, Math.max(room, 0))].sort(byPath);
     };
 }
+/**
+ * `pathFilter`'s sibling: every file of a tree, in path order, with its outcome under the same filter, so a caller can
+ * show what is left out and why. The files answered `note` are exactly those `pathFilter` keeps under the filter, a
+ * code file past `maxCodeBytes` aside; each file left out carries the first reason it is left out, in this order: where
+ * it is (`folder`), what it is (`kind`, `image`, `code`, `generated`), how large it is (`size`) and how many came first
+ * (`count`, the documentation keeping its places first and the code taking the room left, as in `pathFilter`). A file
+ * whose extension the filter's `extensions` names is documentation, an image's included; while code is asked for, one
+ * of a code extension keeps `maxCodeBytes` as its bound, as a code file a tool wrote is left out whatever `extensions`
+ * names. Each answer is a new object holding the file's `path`, `sha` and `size` and its `outcome`. With a `path`, only
+ * the files of that folder, or the one file it names, are planned, and counted alone.
+ *
+ * @param blobs The files of a tree, as `readTree` answers them.
+ * @param options The filter, the code bound, the image extensions and the folder.
+ * @throws TypeError when `maxCodeBytes` is not a non-negative integer, or `path` is not a path.
+ */
+export function planTree(blobs, options = {}) {
+    if (options.maxCodeBytes !== undefined && !(Number.isSafeInteger(options.maxCodeBytes) && options.maxCodeBytes >= 0)) {
+        throw new TypeError('maxCodeBytes is a number of bytes: a non-negative integer');
+    }
+    const path = pathOf(options.path);
+    const documents = new Set((options.extensions ?? DOCUMENT_EXTENSIONS).map((extension) => extension.toLowerCase()));
+    const codeAsked = options.includeCode === true;
+    const code = new Set(CODE_EXTENSIONS);
+    const images = new Set((options.imageExtensions ?? IMAGE_EXTENSIONS).map((extension) => extension.toLowerCase()));
+    const skip = new Set(options.skipFolders ?? SKIPPED_FOLDERS);
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const maxCodeBytes = Math.min(options.maxCodeBytes ?? maxFileBytes, maxFileBytes);
+    const planned = withinPath(blobs, path)
+        .sort(byPath)
+        .map((blob) => ({ path: blob.path, sha: blob.sha, size: blob.size, outcome: 'note' }));
+    const documentation = [];
+    const sources = [];
+    for (const blob of planned) {
+        const extension = extensionOf(blob.path);
+        if (inSkippedFolder(blob.path, skip))
+            blob.outcome = { skipped: 'folder' };
+        else if (codeAsked && code.has(extension) && isGeneratedCode(blob.path))
+            blob.outcome = { skipped: 'generated' };
+        else if (documents.has(extension)) {
+            // A code extension the filter names as documentation keeps the code bound while code is asked for.
+            if (blob.size > (codeAsked && code.has(extension) ? maxCodeBytes : maxFileBytes))
+                blob.outcome = { skipped: 'size' };
+            else
+                documentation.push(blob);
+        }
+        else if (code.has(extension)) {
+            if (!codeAsked)
+                blob.outcome = { skipped: 'code' };
+            else if (blob.size > maxCodeBytes)
+                blob.outcome = { skipped: 'size' };
+            else
+                sources.push(blob);
+        }
+        else
+            blob.outcome = { skipped: images.has(extension) ? 'image' : 'kind' };
+    }
+    // The documentation keeps its places under the count first, and the code takes the room left, as in pathFilter.
+    for (const blob of documentation.slice(maxFiles))
+        blob.outcome = { skipped: 'count' };
+    const room = Math.max(maxFiles - documentation.length, 0);
+    for (const blob of sources.slice(room))
+        blob.outcome = { skipped: 'count' };
+    return planned;
+}
 //# sourceMappingURL=tree.js.map

package/dist/documents/tree.js.map

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

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
   "id": "com.framers.integrations.github",
   "name": "GitHub Extension",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "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 deliveries checked and read as typed events, a daily reconcile, every call under a deadline with rate limit timing) and a connector that reads a repository's documentation as account sources.",
   "categories": ["tool", "developer"],
   "extensions": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos-ext-github",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "GitHub API tools for AgentOS — search repos/code, manage issues/PRs, read files, create gists",
   "main": "dist/index.js",