@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/semantics/meta.js

@@ -0,0 +1,144 @@
+// GitHub's platform meta family: the service root, the rate limit, and the stateless reference
+// catalogs (gitignore templates, licenses, emojis, service metadata) and the Markdown renderer.
+// None of it is account state; every answer is fixed data or computed from the request.
+import { createHash } from 'node:crypto';
+import { githubNotFound } from "../github-twin.js";
+import { gh, send } from "./shared.js";
+// ── Static meta catalogs (the platform's stateless reference endpoints) ───────────────────
+// GitHub serves these from a fixed, well-known catalog (they are not per-account state). The
+// twin returns a faithful representative subset — vendor-shaped objects, deterministic, never
+// fabricated per-request. (The real catalogs are long; a representative slice is honest here.)
+const GITIGNORE_TEMPLATES = ['Node', 'Python', 'Go', 'Rust', 'Java', 'Ruby', 'C', 'C++', 'VisualStudio'];
+const GITIGNORE_SOURCE = {
+    Node: 'node_modules\nnpm-debug.log\n.env\ndist\n',
+    Python: '__pycache__/\n*.py[cod]\n.venv\n.env\n',
+    Go: '*.exe\n*.test\n/vendor/\n',
+};
+const LICENSES = [
+    { key: 'mit', name: 'MIT License', spdx_id: 'MIT' },
+    { key: 'apache-2.0', name: 'Apache License 2.0', spdx_id: 'Apache-2.0' },
+    { key: 'gpl-3.0', name: 'GNU General Public License v3.0', spdx_id: 'GPL-3.0' },
+    { key: 'bsd-3-clause', name: 'BSD 3-Clause "New" or "Revised" License', spdx_id: 'BSD-3-Clause' },
+    { key: 'unlicense', name: 'The Unlicense', spdx_id: 'Unlicense' },
+];
+const EMOJIS = {
+    '+1': 'https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png',
+    '-1': 'https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png',
+    smile: 'https://github.githubassets.com/images/icons/emoji/unicode/1f604.png',
+    rocket: 'https://github.githubassets.com/images/icons/emoji/unicode/1f680.png',
+    tada: 'https://github.githubassets.com/images/icons/emoji/unicode/1f389.png',
+    eyes: 'https://github.githubassets.com/images/icons/emoji/unicode/1f440.png',
+    heart: 'https://github.githubassets.com/images/icons/emoji/unicode/2764.png',
+};
+/** A .gitignore template's text, by its name (any case); undefined for a name the catalog lacks. */
+export function gitignoreTemplate(name) {
+    const found = GITIGNORE_TEMPLATES.find((t) => t.toLowerCase() === name.toLowerCase());
+    return found && (GITIGNORE_SOURCE[found] ?? `# ${found} .gitignore\n`);
+}
+// The license texts GitHub serves, [year] and [fullname] left for whoever copies them in: MIT's is the body
+// docs.github.com/rest/licenses/licenses#get-a-license shows (its example's leading blank lines dropped). Where the
+// documentation stops: the other catalog licenses keep their name alone.
+const LICENSE_TEXTS = {
+    mit: 'The MIT License (MIT)\n\nCopyright (c) [year] [fullname]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the "Software"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n',
+};
+/** A license's text, by its key (any case); undefined for a key the catalog lacks. Given a holder, its placeholders are
+ *  filled as the license's implementation note says: [year] with the year and [fullname] with the copyright holder. */
+export function licenseTemplate(key, fill) {
+    const found = LICENSES.find((l) => l.key === key.toLowerCase());
+    if (!found)
+        return undefined;
+    const text = LICENSE_TEXTS[found.key] ?? `${found.name}\n`;
+    return fill ? text.replaceAll('[year]', fill.year).replaceAll('[fullname]', fill.fullname) : text;
+}
+function licenseToRest(l) {
+    return { key: l.key, name: l.name, spdx_id: l.spdx_id, url: `https://api.github.com/licenses/${l.key}`, node_id: createHash('sha256').update(`license:${l.key}`).digest('base64').slice(0, 16), html_url: `https://choosealicense.com/licenses/${l.key}/` };
+}
+// A minimal-but-faithful GitHub-Flavored-Markdown renderer for POST /markdown. GitHub returns
+// rendered HTML; the twin supports the common inline/block forms (headings, bold, italic,
+// inline code, links) deterministically. Not a full CommonMark engine — a faithful subset.
+function renderMarkdown(text) {
+    const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const inline = (s) => esc(s)
+        .replace(/`([^`]+)`/g, '<code>$1</code>')
+        .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+        .replace(/\*([^*]+)\*/g, '<em>$1</em>')
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+    const out = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trimEnd();
+        if (!line)
+            continue;
+        const h = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (h) {
+            const lvl = h[1].length;
+            out.push(`<h${lvl}>${inline(h[2])}</h${lvl}>`);
+            continue;
+        }
+        out.push(`<p>${inline(line)}</p>`);
+    }
+    return out.join('\n');
+}
+export function metaSemantics(_opts) {
+    const metaRoot = async (ctx) => {
+        const a = 'https://api.github.com';
+        return ctx.reply({
+            current_user_url: `${a}/user`, current_user_authorizations_html_url: 'https://github.com/settings/connections/applications{/client_id}',
+            authorizations_url: `${a}/authorizations`, code_search_url: `${a}/search/code?q={query}{&page,per_page,sort,order}`,
+            commit_search_url: `${a}/search/commits?q={query}{&page,per_page,sort,order}`, emails_url: `${a}/user/emails`, emojis_url: `${a}/emojis`,
+            events_url: `${a}/events`, feeds_url: `${a}/feeds`, followers_url: `${a}/user/followers`, following_url: `${a}/user/following{/target}`,
+            gists_url: `${a}/gists{/gist_id}`, hub_url: `${a}/hub`, issue_search_url: `${a}/search/issues?q={query}{&page,per_page,sort,order}`,
+            issues_url: `${a}/issues`, keys_url: `${a}/user/keys`, label_search_url: `${a}/search/labels?q={query}&repository_id={repository_id}{&page,per_page}`,
+            notifications_url: `${a}/notifications`, organization_url: `${a}/orgs/{org}`, organization_repositories_url: `${a}/orgs/{org}/repos{?type,page,per_page,sort}`,
+            organization_teams_url: `${a}/orgs/{org}/teams`, public_gists_url: `${a}/gists/public`, rate_limit_url: `${a}/rate_limit`,
+            repository_url: `${a}/repos/{owner}/{repo}`, repository_search_url: `${a}/search/repositories?q={query}{&page,per_page,sort,order}`,
+            current_user_repositories_url: `${a}/user/repos{?type,page,per_page,sort}`, starred_url: `${a}/user/starred{/owner}{/repo}`,
+            starred_gists_url: `${a}/gists/starred`, topic_search_url: `${a}/search/topics?q={query}{&page,per_page}`, user_url: `${a}/users/{user}`,
+            user_organizations_url: `${a}/user/orgs`, user_repositories_url: `${a}/users/{user}/repos{?type,page,per_page,sort}`,
+            user_search_url: `${a}/search/users?q={query}{&page,per_page,sort,order}`,
+        });
+    };
+    const rateLimitGet = async (ctx) => {
+        const reset = 4102444800; // 2100-01-01T00:00:00Z — a stable, far-future sentinel.
+        const bucket = (limit) => ({ limit, used: 0, remaining: limit, reset });
+        const resources = { core: bucket(5000), search: bucket(30), graphql: bucket(5000), integration_manifest: bucket(5000), code_scanning_upload: bucket(500) };
+        return ctx.reply({ resources, rate: resources.core });
+    };
+    const gitignoreGetTemplate = async (ctx) => {
+        const name = GITIGNORE_TEMPLATES.find((t) => t.toLowerCase() === decodeURIComponent(gh(ctx).seg[2]).toLowerCase());
+        if (!name)
+            return send(ctx, githubNotFound());
+        return ctx.reply({ name, source: gitignoreTemplate(name) });
+    };
+    const licensesGet = async (ctx) => {
+        const l = LICENSES.find((x) => x.key === decodeURIComponent(gh(ctx).seg[1]).toLowerCase());
+        if (!l)
+            return send(ctx, githubNotFound());
+        return ctx.reply({ ...licenseToRest(l), description: `${l.name}.`, permissions: [], conditions: [], limitations: [], body: licenseTemplate(l.key), featured: l.key === 'mit' });
+    };
+    const markdownRender = async (ctx) => {
+        const { body } = gh(ctx);
+        if (typeof body.text !== 'string')
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Markdown', field: 'text', code: 'missing_field' }] }, 422);
+        return ctx.reply(renderMarkdown(body.text));
+    };
+    return {
+        // the twin's own root: which service this is and whether it takes writes
+        // the API's root: the URL templates of its resources, as api.github.com answers (docs.github.com/rest/meta/meta#github-api-root)
+        'meta/root': metaRoot,
+        // Rate limit: the twin is local + unmetered, so it reports a faithful full-budget envelope
+        // in GitHub's exact {resources:{core,search,...}, rate} shape. The reset is a fixed sentinel
+        // (deterministic — never Date.now()).
+        'rate-limit/get': rateLimitGet,
+        'gitignore/get-all-templates': async (ctx) => ctx.reply(GITIGNORE_TEMPLATES),
+        'gitignore/get-template': gitignoreGetTemplate,
+        'licenses/get-all-commonly-used': async (ctx) => ctx.reply(LICENSES.map(licenseToRest)),
+        'licenses/get': licensesGet,
+        // the named-emoji → asset-URL map
+        'emojis/get': async (ctx) => ctx.reply(EMOJIS),
+        // the platform's service metadata envelope
+        'meta/get': async (ctx) => ctx.reply({ verifiable_password_authentication: false, ssh_key_fingerprints: {}, hooks: [], web: [], api: [], git: [], packages: [], pages: [], importer: [], actions: [], dependabot: [] }),
+        // Render Markdown to HTML (GitHub returns text/html). The twin renders a faithful GFM subset
+        // deterministically; `text` is required (422 when absent, like GitHub).
+        'markdown/render': markdownRender,
+    };
+}

package/dist/src/semantics/notifications.d.ts

@@ -0,0 +1,4 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type GithubWriteEvent } from '../github-twin.js';
+/** The thread an event puts in the World's user's inbox, when it concerns them and someone else did it. */
+export declare function notify(ctx: SemanticsContext, event: GithubWriteEvent): Promise<void>;

package/dist/src/semantics/notifications.js

@@ -0,0 +1,62 @@
+// The notifications GitHub sends the signed-in person (the World's user): when someone else @mentions them, assigns
+// them, asks for their review, or comments on or reviews their issue or pull request, the thread for that issue or pull
+// request is unread in their inbox with the reason (docs.github.com/account-and-profile/managing-subscriptions-and-
+// notifications-on-github/setting-up-notifications/about-notifications#reasons-for-receiving-notifications). One
+// thread per issue or pull request: a new reason on it marks it unread again. The person's own acts notify no one.
+import { createHash } from 'node:crypto';
+import { GITHUB_WORLD_USER } from "../github-twin.js";
+import { gh, put } from "./shared.js";
+const loginOf = (u) => (u && typeof u === 'object' ? u.login : undefined);
+const mentions = (text, login) => typeof text === 'string' && new RegExp(`(^|[^\\w-])@${login}\\b`, 'i').test(text);
+/** Whether a review request names the World's user. */
+function reviewRequestedOf(event, me) {
+    const requested = event.pr?.requested_reviewers ?? [];
+    return requested.some((r) => (typeof r === 'string' ? r : loginOf(r)) === me);
+}
+/** Why an event notifies the World's user, or nothing. */
+function reasonFor(event, me, author) {
+    const text = event.comment?.body ?? event.review?.body ?? event.issue?.body ?? event.body;
+    if (mentions(text, me))
+        return 'mention';
+    if (event.event === 'pull_request' && event.action === 'review_requested' && reviewRequestedOf(event, me))
+        return 'review_requested';
+    if (event.event === 'issues' && (event.action === 'opened' || event.action === 'assigned' || event.action === 'edited')) {
+        const assignees = event.issue?.assignees ?? [];
+        if (assignees.some((a) => loginOf(a) === me))
+            return 'assign';
+    }
+    if ((event.event === 'issue_comment' || event.event === 'pull_request_review') && author === me)
+        return 'author';
+    return undefined;
+}
+/** The thread an event puts in the World's user's inbox, when it concerns them and someone else did it. */
+export async function notify(ctx, event) {
+    const { caller, state } = gh(ctx);
+    const me = GITHUB_WORLD_USER;
+    if (!caller || caller === me || !event.number)
+        return;
+    const st = state();
+    const pr = st.prs.find((p) => p.repository === event.repository && Number(p.number) === event.number);
+    const issue = st.issues.find((i) => i.repository === event.repository && Number(i.number) === event.number);
+    const author = pr?.user_login ?? issue?.user_login ?? undefined;
+    const reason = reasonFor(event, me, author);
+    if (!reason)
+        return;
+    const isPull = Boolean(pr) || event.event.startsWith('pull_request');
+    const id = String(parseInt(createHash('sha256').update(`${event.repository}#${event.number}`).digest('hex').slice(0, 8), 16));
+    // an ignored thread stays quiet; an unsubscribed one until the next @mention, which subscribes the person again
+    const thread = st.notifications.find((n) => n.id === id);
+    if (thread?.subscription?.ignored)
+        return;
+    if (thread?.subscription === null && reason !== 'mention')
+        return;
+    await put(ctx, {
+        operation: 'notification.create', subjectType: 'notification', subjectId: `notification:${id}`,
+        fields: {
+            id, repository: event.repository, subject_title: String(pr?.title ?? issue?.title ?? `#${event.number}`),
+            subject_type: isPull ? 'PullRequest' : 'Issue', subject_url: `https://api.github.com/repos/${event.repository}/${isPull ? 'pulls' : 'issues'}/${event.number}`,
+            reason, unread: true, updated_at: ctx.occurredAt,
+            ...(thread?.subscription === null ? { subscription: { subscribed: true, ignored: false, created_at: ctx.occurredAt } } : {}),
+        },
+    });
+}

package/dist/src/semantics/orgs.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare function orgsSemantics(): Record<string, Semantics>;