@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/semantics/code-scanning-upload.js

@@ -0,0 +1,97 @@
+// Code scanning from an uploaded analysis: a scanner (CodeQL in Actions, or any tool that writes SARIF) uploads its
+// results for a commit and ref, gzip-compressed and Base64-encoded, and GitHub processes them into an analysis and
+// alerts: a result not seen before on that ref opens an alert, and an open alert the new analysis no longer reports is
+// fixed (docs.github.com/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data,
+// docs.github.com/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github).
+// The upload answers 202 with the id its processing status is read by.
+//
+// Where the documentation stops and the twin decides: processing completes at once; an alert is keyed by its rule, file
+// and line; SARIF's `level` (error, warning, note) is the rule's severity, `warning` when absent.
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { githubNotFound } from "../github-twin.js";
+import { gh, nextSeq, put, send } from "./shared.js";
+const invalid = (ctx, message) => ctx.reply({ message, documentation_url: 'https://docs.github.com/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data' }, 400);
+/** The runs of an uploaded SARIF, gzip-compressed and Base64-encoded, or nothing when it is not. */
+function sarifRuns(sarif) {
+    try {
+        const doc = JSON.parse(gunzipSync(Buffer.from(String(sarif ?? ''), 'base64')).toString('utf8'));
+        return Array.isArray(doc.runs) ? doc.runs : [];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** GitHub's refusal of a sarif field that is not gzip-compressed and Base64-encoded SARIF. */
+function notSarif(ctx) {
+    return invalid(ctx, 'The sarif field must be gzip-compressed and Base64-encoded SARIF.');
+}
+/** A result an alert already holds, found again: a fixed alert is open again, anything else keeps its state. */
+async function stillFound(ctx, repo, existing, instance, occurredAt) {
+    await put(ctx, { operation: 'code_scanning_alert.update', subjectType: 'code_scanning_alert', subjectId: `csalert:${repo}#${existing.number}`, fields: { ...existing, state: existing.state === 'fixed' ? 'open' : existing.state, fixed_at: null, most_recent_instance: instance, updated_at: occurredAt } });
+}
+const upload = async (ctx) => {
+    const { repo, body, occurredAt, state } = gh(ctx);
+    if (!state().repos.some((r) => r.full_name === repo))
+        return send(ctx, githubNotFound());
+    const commit = String(body.commit_sha ?? '');
+    const ref = String(body.ref ?? '');
+    if (!/^[0-9a-f]{40}$/i.test(commit))
+        return ctx.reply({ message: 'Invalid request.', errors: ['commit_sha is not a 40-character SHA'] }, 422);
+    if (!/^refs\/(heads|tags|pull)\//.test(ref))
+        return ctx.reply({ message: 'Invalid request.', errors: ['ref must be refs/heads/<branch>, refs/tags/<tag> or refs/pull/<n>/merge'] }, 422);
+    const runs = sarifRuns(body.sarif);
+    if (!runs)
+        return notSarif(ctx);
+    const sarifId = createHash('sha256').update(`${repo}:${commit}:${ref}:${occurredAt}:${String(body.sarif).length}`).digest('hex').slice(0, 36);
+    const analysisIds = [];
+    for (const run of runs) {
+        const tool = String(run.tool?.driver?.name ?? body.tool_name ?? 'CodeQL');
+        const rules = new Map((run.tool?.driver?.rules ?? []).map((r) => [String(r.id), r]));
+        const results = run.results ?? [];
+        const key = run.automationDetails?.id ?? `${tool}:${ref}`;
+        const id = nextSeq(ctx, 'csanalysis');
+        await put(ctx, { operation: 'code_scanning_analysis.create', subjectType: 'code_scanning_analysis', subjectId: `csanalysis:${id}`,
+            fields: { repository: repo, ref, commit_sha: commit, analysis_key: key, tool_name: tool, results_count: results.length, rules_count: rules.size, sarif_id: sarifId, created_at: occurredAt } });
+        analysisIds.push(id);
+        const found = new Set();
+        for (const result of results) {
+            const ruleId = String(result.ruleId ?? 'unknown');
+            const loc = result.locations?.[0]?.physicalLocation;
+            const path = String(loc?.artifactLocation?.uri ?? '');
+            const start = Number(loc?.region?.startLine ?? 1);
+            const identity = `${ruleId}:${path}:${start}`;
+            found.add(identity);
+            const alerts = state().codeScanningAlerts.filter((a) => a.repository === repo && a.tool_name === tool);
+            const existing = alerts.find((a) => a.rule_id === ruleId && a.most_recent_instance?.path === path && a.most_recent_instance?.start_line === start);
+            const rule = rules.get(ruleId);
+            const instance = { ref, analysis_key: key, commit_sha: commit, state: 'open', message: String(result.message?.text ?? ''), path, start_line: start, end_line: Number(loc?.region?.endLine ?? start) };
+            if (existing) {
+                await stillFound(ctx, repo, existing, instance, occurredAt);
+                continue;
+            }
+            const number = Math.max(0, ...state().codeScanningAlerts.filter((a) => a.repository === repo).map((a) => a.number)) + 1;
+            await put(ctx, { operation: 'code_scanning_alert.create', subjectType: 'code_scanning_alert', subjectId: `csalert:${repo}#${number}`,
+                fields: { number, repository: repo, state: 'open', rule_id: ruleId, rule_severity: String(result.level ?? rule?.defaultConfiguration?.level ?? 'warning'), rule_description: rule?.shortDescription?.text, tool_name: tool, tool_version: run.tool?.driver?.version, most_recent_instance: instance, created_at: occurredAt, updated_at: occurredAt } });
+        }
+        // what this ref's analysis no longer reports is fixed
+        for (const a of state().codeScanningAlerts.filter((x) => x.repository === repo && x.tool_name === tool && x.state === 'open' && x.most_recent_instance?.ref === ref)) {
+            if (!found.has(`${a.rule_id}:${a.most_recent_instance?.path}:${a.most_recent_instance?.start_line}`)) {
+                await put(ctx, { operation: 'code_scanning_alert.update', subjectType: 'code_scanning_alert', subjectId: `csalert:${repo}#${a.number}`, fields: { ...a, state: 'fixed', fixed_at: occurredAt, updated_at: occurredAt } });
+            }
+        }
+    }
+    await put(ctx, { operation: 'code_scanning_sarif.create', subjectType: 'code_scanning_sarif', subjectId: `sarif:${repo}#${sarifId}`, fields: { repository: repo, sarif_id: sarifId, analyses: analysisIds, created_at: occurredAt } });
+    return ctx.reply({ id: sarifId, url: `https://api.github.com/repos/${repo}/code-scanning/sarifs/${sarifId}` }, 202);
+};
+const status = async (ctx) => {
+    const { repo, seg } = gh(ctx);
+    const id = decodeURIComponent(seg[5]);
+    if (!ctx.rowsRaw('code_scanning_sarif').some((r) => r.id === `sarif:${repo}#${id}`))
+        return send(ctx, githubNotFound());
+    return ctx.reply({ processing_status: 'complete', analyses_url: `https://api.github.com/repos/${repo}/code-scanning/analyses?sarif_id=${id}`, errors: null });
+};
+export const codeScanningUpload = {
+    'code-scanning/upload-sarif': upload,
+    'code-scanning/get-sarif': status,
+};

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

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

package/dist/src/semantics/codespaces.js

@@ -0,0 +1,58 @@
+// GitHub's codespaces family, for the authenticated user: the codespace resource and its lifecycle
+// (create → Available, stop → Shutdown, start → Available, delete). The machine's compute is out of
+// scope; its state is modeled.
+import { createHash } from 'node:crypto';
+import { githubNotFound, paginate, toGithubCodespace } from "../github-twin.js";
+import { gh, put, send } from "./shared.js";
+/** start → Available, stop → Shutdown: from any state, as the twin has always answered. */
+const move = (verb) => async (ctx) => {
+    const { seg, occurredAt, state } = gh(ctx);
+    const name = decodeURIComponent(seg[2]);
+    const existing = state().codespaces.find((c) => c.name === name);
+    if (!existing)
+        return send(ctx, githubNotFound());
+    await put(ctx, { operation: `codespace.${verb}`, subjectType: 'codespace', subjectId: `codespace:${name}`, fields: { name, repository: existing.repository, state: verb === 'start' ? 'Available' : 'Shutdown', updated_at: occurredAt } });
+    return ctx.reply(toGithubCodespace(state().codespaces.find((x) => x.name === name)));
+};
+export function codespacesSemantics() {
+    const codespacesListForAuthenticatedUser = async (ctx) => {
+        const { query, state } = gh(ctx);
+        const st = state();
+        return ctx.reply({ total_count: st.codespaces.length, codespaces: paginate(st.codespaces, query).map(toGithubCodespace) });
+    };
+    const codespacesGetForAuthenticatedUser = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const c = state().codespaces.find((x) => x.name === decodeURIComponent(seg[2]));
+        return send(ctx, c ? { status: 200, body: toGithubCodespace(c) } : githubNotFound());
+    };
+    const codespacesCreateForAuthenticatedUser = async (ctx) => {
+        const { body, occurredAt, state } = gh(ctx);
+        const repo = body.repository !== undefined ? String(body.repository) : body.repository_id !== undefined ? String(body.repository_id) : undefined;
+        if (!repo)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Codespace', field: 'repository_id', code: 'missing_field' }] }, 422);
+        // one past every codespace stored, tombstones included: each create gets its own name
+        const seq = ctx.rowsRaw('codespace', { withDeleted: true }).length + 1;
+        const name = `octocat-${createHash('sha256').update(`codespace:${repo}:${seq}`).digest('hex').slice(0, 12)}`;
+        const fields = { name, repository: repo, state: 'Available', machine: String(body.machine ?? 'basicLinux32gb'), git_branch: String(body.ref ?? 'main'), owner: 'octocat', created_at: occurredAt, updated_at: occurredAt };
+        await put(ctx, { operation: 'codespace.create', subjectType: 'codespace', subjectId: `codespace:${name}`, fields });
+        return ctx.reply(toGithubCodespace(state().codespaces.find((x) => x.name === name)), 201);
+    };
+    const codespacesDeleteForAuthenticatedUser = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const name = decodeURIComponent(seg[2]);
+        if (!state().codespaces.find((c) => c.name === name))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'codespace.delete', subjectType: 'codespace', subjectId: `codespace:${name}`, fields: { deleted: true, name } });
+        return ctx.raw(null, { status: 202 });
+    };
+    return {
+        'codespaces/list-for-authenticated-user': codespacesListForAuthenticatedUser,
+        'codespaces/get-for-authenticated-user': codespacesGetForAuthenticatedUser,
+        // create (Available); needs a repository
+        'codespaces/create-for-authenticated-user': codespacesCreateForAuthenticatedUser,
+        'codespaces/start-for-authenticated-user': move('start'),
+        'codespaces/stop-for-authenticated-user': move('stop'),
+        // tombstone the codespace (202, as GitHub accepts a deletion)
+        'codespaces/delete-for-authenticated-user': codespacesDeleteForAuthenticatedUser,
+    };
+}

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

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

package/dist/src/semantics/commits.js

@@ -0,0 +1,109 @@
+import { githubNotFound, hasBareRepo, isAncestorInPlane, paginate, planeAncestors, planeCommitBody, resolvePlaneRef, toGithubCommitComment, toGithubRest, } from "../github-twin.js";
+import { announce, asView, gh, nextSeq, put, send } from "./shared.js";
+const defaultBranchOf = (ctx) => {
+    const { repo, state } = gh(ctx);
+    return state().repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+};
+const refOf = (ctx) => decodeURIComponent(gh(ctx).seg[4]);
+export function commitsSemantics() {
+    const reposListCommits = async (ctx) => {
+        const { repo, query, root } = gh(ctx);
+        const params = new URLSearchParams(query ?? '');
+        const tip = await resolvePlaneRef(repo, params.get('sha') ?? undefined, defaultBranchOf(ctx), root);
+        if (!tip)
+            return send(ctx, githubNotFound());
+        const since = params.get('since') ? Date.parse(params.get('since')) : -Infinity;
+        const until = params.get('until') ? Date.parse(params.get('until')) : Infinity;
+        // newest first; commits made in the same instant keep history's order, a commit before its parents (as git log walks)
+        const found = [...(await planeAncestors(repo, tip, root))].map(([sha, at], walked) => ({ sha, at, walked })).filter(({ at }) => !(at < since) && !(at > until));
+        found.sort((a, b) => b.at - a.at || a.walked - b.walked);
+        const bodies = [];
+        for (const f of paginate(found, query)) {
+            const b = await planeCommitBody(repo, f.sha, root);
+            if (b)
+                bodies.push(b);
+        }
+        return ctx.reply(bodies);
+    };
+    const reposGetCommit = async (ctx) => {
+        const { repo, root } = gh(ctx);
+        const sha = await resolvePlaneRef(repo, refOf(ctx), defaultBranchOf(ctx), root);
+        const body = sha ? await planeCommitBody(repo, sha, root) : null;
+        return send(ctx, body ? { status: 200, body } : githubNotFound());
+    };
+    const reposListPullRequestsAssociatedWithCommit = async (ctx) => {
+        const { repo, query, root, state } = gh(ctx);
+        const st = state();
+        const ref = refOf(ctx);
+        const defaultBranch = defaultBranchOf(ctx);
+        const tip = hasBareRepo(repo, root) ? await resolvePlaneRef(repo, defaultBranch, defaultBranch, root) : null;
+        // A repository known only through the API has no history to walk: a pull request merged into the
+        // default branch put its commits there.
+        const onDefault = tip ? (tip === ref || await isAncestorInPlane(repo, ref, tip, root)) : null;
+        const items = st.prs.filter((p) => p.repository === repo && (p.head_sha === ref || p.merge_commit_sha === ref))
+            .filter((p) => ((onDefault ?? ((p.merged === true || !!p.merged_at) && p.base_ref === defaultBranch)) ? p.merged === true || !!p.merged_at : p.state === 'open'))
+            .sort((a, b) => a.number - b.number);
+        return ctx.reply(paginate(items, query).map((p) => asView('pull-request-simple', toGithubRest(p, st.milestones))));
+    };
+    const reposListCommentsForCommit = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const ref = refOf(ctx);
+        return ctx.reply(paginate(state().commitComments.filter((c) => c.repository === repo && c.commit_sha === ref), query).map(toGithubCommitComment));
+    };
+    const reposListCommitCommentsForRepo = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().commitComments.filter((c) => c.repository === repo).sort((a, b) => a.id - b.id), query).map(toGithubCommitComment));
+    };
+    const reposGetCommitComment = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const c = state().commitComments.find((x) => x.repository === repo && x.id === Number(decodeURIComponent(seg[4])));
+        return send(ctx, c ? { status: 200, body: toGithubCommitComment(c) } : githubNotFound());
+    };
+    const reposCreateCommitComment = async (ctx) => {
+        const { repo, body, occurredAt, state } = gh(ctx);
+        const sha = refOf(ctx);
+        if (!body.body)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'CommitComment', field: 'body', code: 'missing_field' }] }, 422);
+        const seq = nextSeq(ctx, 'commitcomment');
+        const fields = { repository: repo, commit_sha: sha, body: String(body.body), path: body.path ?? null, line: body.line !== undefined ? Number(body.line) : null, position: body.position !== undefined ? Number(body.position) : null, created_at: occurredAt, updated_at: occurredAt };
+        await put(ctx, { operation: 'commit_comment.create', subjectType: 'commit_comment', subjectId: `commitcomment:${seq}`, fields });
+        const answer = toGithubCommitComment(state().commitComments.find((x) => x.repository === repo && x.id === seq));
+        await announce(ctx, [{ event: 'commit_comment', action: 'created', repository: repo, number: 0, body: String(body.body) }]);
+        return ctx.reply(answer, 201);
+    };
+    const reposUpdateCommitComment = async (ctx) => {
+        const { repo, seg, body, occurredAt, state } = gh(ctx);
+        const id = Number(decodeURIComponent(seg[4]));
+        const existing = state().commitComments.find((c) => c.repository === repo && c.id === id);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'commit_comment.update', subjectType: 'commit_comment', subjectId: `commitcomment:${id}`, fields: { repository: repo, commit_sha: existing.commit_sha, body: body.body !== undefined ? String(body.body) : existing.body, path: existing.path, line: existing.line, position: existing.position, created_at: existing.created_at, updated_at: occurredAt } });
+        return ctx.reply(toGithubCommitComment(state().commitComments.find((x) => x.repository === repo && x.id === id)));
+    };
+    const reposDeleteCommitComment = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const id = Number(decodeURIComponent(seg[4]));
+        if (!state().commitComments.find((c) => c.repository === repo && c.id === id))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'commit_comment.delete', subjectType: 'commit_comment', subjectId: `commitcomment:${id}`, fields: { deleted: true, repository: repo } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    return {
+        // Commits reachable from ?sha (a branch, tag or sha; the default branch when absent), newest first by
+        // commit date, filtered by ?since / ?until. A repository with no history in the plane, or a ref it
+        // cannot resolve, answers 404 like GitHub's empty or unknown ref.
+        'repos/list-commits': reposListCommits,
+        // a single commit by sha, branch or tag
+        'repos/get-commit': reposGetCommit,
+        // A pull request is associated when its head or merge commit is the commit, or its carried commit
+        // list holds it; a commit reachable only through a PR's history in the plane is not found here.
+        'repos/list-pull-requests-associated-with-commit': reposListPullRequestsAssociatedWithCommit,
+        // oldest first
+        'repos/list-comments-for-commit': reposListCommentsForCommit,
+        'repos/list-commit-comments-for-repo': reposListCommitCommentsForRepo,
+        'repos/get-commit-comment': reposGetCommitComment,
+        'repos/create-commit-comment': reposCreateCommitComment,
+        'repos/update-commit-comment': reposUpdateCommitComment,
+        'repos/delete-commit-comment': reposDeleteCommitComment,
+    };
+}

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

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

package/dist/src/semantics/contents.js

@@ -0,0 +1,131 @@
+// A repository's contents (a file, or a directory's listing) and README, and file writes. A repository
+// with a git plane reads and writes there: a file write is a commit on the branch (a push: the branch
+// row follows, open pull requests riding it are re-pointed, push and synchronize announced); one known
+// only through the API keeps the files its REST writes stored.
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { githubContents, githubNotFound, hasBareRepo, isValidBranchName, listGitPlaneRefs, planeContents, planeEntryAt, planeFileContent, planeQueryRef, readGitCommitFromPlane, resolvePlaneRef, syncPrHeadsToBranchTip, toGithubContent, updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTreeToPlane, } from "../github-twin.js";
+import { directPushRules } from "./push-reactions.js";
+import { announce, atomic, gh, identityOf, put, send } from "./shared.js";
+/** The file path a path names (the path may hold slashes). */
+const pathOf = (ctx) => decodeURIComponent(gh(ctx).seg.slice(4).join('/'));
+/** A file write (PUT creates or replaces, DELETE removes). */
+async function writeFile(ctx, removing) {
+    const { repo, body, occurredAt, root, state } = gh(ctx);
+    const p = pathOf(ctx);
+    const method = removing ? 'DELETE' : 'PUT';
+    if (hasBareRepo(repo, root)) {
+        const defaultBranch = state().repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+        const branch = String(body.branch ?? defaultBranch);
+        const invalid = (message) => ctx.reply({ message }, 422);
+        if (!isValidBranchName(branch) || p.split('/').some((part) => !part || part === '.' || part === '..' || part.includes('\0')) || typeof body.message !== 'string' || !body.message)
+            return invalid('A valid branch, path and commit message are required.');
+        for (const field of ['author', 'committer'])
+            if (body[field] !== undefined && (!body[field] || typeof body[field].name !== 'string' || !body[field].name || typeof body[field].email !== 'string' || !body[field].email))
+                return invalid(`${field} requires name and email`);
+        for (const field of ['author', 'committer'])
+            if (body[field]?.date !== undefined && (typeof body[field].date !== 'string' || !Number.isFinite(Date.parse(body[field].date))))
+                return invalid(`${field}.date must be a timestamp`);
+        // an active ruleset requiring pull requests refuses a direct push to its branch
+        const ruled = directPushRules(state(), repo, branch);
+        if (ruled.refused)
+            return ctx.reply({ message: `Repository rule violations found\n\n${ruled.refused}`, documentation_url: 'https://docs.github.com/rest/repos/contents#create-or-update-file-contents', status: '409' }, 409);
+        const refs = await listGitPlaneRefs(repo, root);
+        const parent = refs.find((ref) => ref.ref === `refs/heads/${branch}`)?.object_sha ?? null;
+        if (!parent && (refs.length || branch !== defaultBranch || method === 'DELETE'))
+            return send(ctx, githubNotFound());
+        const previous = parent ? await planeEntryAt(repo, parent, p, root) : null;
+        if (previous && previous.kind !== 'file')
+            return invalid('Path is a directory or submodule');
+        // Refuse file/directory collisions before constructing an invalid Git tree.
+        const parts = p.split('/');
+        for (let n = 1; parent && n < parts.length; n++) {
+            const ancestor = await planeEntryAt(repo, parent, parts.slice(0, n).join('/'), root);
+            if (ancestor && ancestor.kind !== 'dir')
+                return invalid('A parent path is a file or submodule');
+        }
+        if (previous && body.sha === undefined)
+            return invalid('sha is required when replacing a file');
+        if ((previous?.kind === 'file' && body.sha !== previous.entry.sha) || (!previous && body.sha))
+            return ctx.reply({ message: 'File SHA does not match the requested branch.' }, 409);
+        if (!previous && method === 'DELETE')
+            return send(ctx, githubNotFound());
+        if (method === 'PUT' && (typeof body.content !== 'string' || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(body.content.replace(/\s/g, ''))))
+            return invalid('content must be Base64 encoded');
+        const blob = method === 'PUT' ? await writeGitBlobToPlane(repo, body.content, root) : '';
+        const baseTree = parent ? (await readGitCommitFromPlane(repo, parent, root))?.tree_sha : undefined;
+        if (parent && !baseTree)
+            return ctx.reply({ message: 'Branch commit is unavailable.' }, 409);
+        const tree = await writeGitTreeToPlane(repo, [{ path: p, mode: previous?.kind === 'file' ? previous.entry.mode : '100644', type: 'blob', sha: blob }], baseTree, root);
+        const commit = await writeGitCommitToPlane(repo, { message: body.message, treeSha: tree, parents: parent ? [parent] : [], author: body.author ?? body.committer ?? identityOf(gh(ctx)), committer: body.committer ?? identityOf(gh(ctx)), occurredAt }, root);
+        if (!await updateGitRefInPlane(repo, `refs/heads/${branch}`, commit, root, parent))
+            return ctx.reply({ message: 'Branch moved while editing the file; read it again before retrying.' }, 409);
+        await put(ctx, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${repo}#refs/heads/${branch}`, fields: { repository: repo, ref: `refs/heads/${branch}`, object_sha: commit, object_type: 'commit' } });
+        await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${branch}`, fields: { repository: repo, name: branch, commit_sha: commit } });
+        const events = [{ event: 'push', action: '', repository: repo, number: 0, ref: `refs/heads/${branch}`, before: parent ?? '0'.repeat(40), after: commit }];
+        await syncPrHeadsToBranchTip(repo, branch, commit, root, occurredAt, (pr, base) => events.push({ event: 'pull_request', action: 'synchronize', repository: base, number: Number(pr.number), pr }), atomic(ctx));
+        const answer = { content: method === 'DELETE' ? null : (await planeContents(repo, commit, p, branch, root))?.body, commit: { sha: commit, message: body.message } };
+        await announce(ctx, events);
+        return ctx.reply(answer, previous ? 200 : 201);
+    }
+    const subjectId = `content:${repo}#${p}`;
+    if (method === 'DELETE') {
+        if (!state().contents.find((c) => c.repository === repo && c.path === p))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'content_file.delete', subjectType: 'content_file', subjectId, fields: { deleted: true, repository: repo, path: p } });
+        const sha = createHash('sha256').update(`${repo}:${p}:deleted:${occurredAt}`).digest('hex').slice(0, 40);
+        return ctx.reply({ content: null, commit: { sha, message: body.message ?? `Delete ${p}` } });
+    }
+    if (body.content === undefined)
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Content', field: 'content', code: 'missing_field' }] }, 422);
+    const content_b64 = String(body.content);
+    let size = 0;
+    try {
+        size = Buffer.from(content_b64, 'base64').length;
+    }
+    catch {
+        size = content_b64.length;
+    }
+    const sha = createHash('sha256').update(`${repo}:${p}:${content_b64}`).digest('hex').slice(0, 40);
+    const fields = { repository: repo, path: p, content_b64, sha, size, branch: body.branch ?? 'main' };
+    const existed = state().contents.some((c) => c.repository === repo && c.path === p);
+    await put(ctx, { operation: existed ? 'content_file.update' : 'content_file.create', subjectType: 'content_file', subjectId, fields });
+    const answer = { content: toGithubContent(state().contents.find((c) => c.repository === repo && c.path === p)), commit: { sha, message: body.message ?? `Add ${p}` } };
+    await announce(ctx, [{ event: 'push', action: '', repository: repo, number: 0 }]);
+    return ctx.reply(answer, existed ? 200 : 201);
+}
+export function contentsSemantics() {
+    return {
+        'repos/get-content': async (ctx) => {
+            const { repo, query, root, state } = gh(ctx);
+            return send(ctx, await githubContents(state(), repo, pathOf(ctx), query, root));
+        },
+        'repos/create-or-update-file-contents': async (ctx) => writeFile(ctx, false),
+        'repos/delete-file': async (ctx) => writeFile(ctx, true),
+        // The README at the root: the stored one (a repository without a plane), else the plane's at ?ref.
+        'repos/get-readme': async (ctx) => {
+            const { repo, query, root, state } = gh(ctx);
+            const st = state();
+            const readme = (hasBareRepo(repo, root) ? [] : st.contents).filter((c) => c.repository === repo && /^readme(\.[a-z]+)?$/i.test(c.path)).sort((a, b) => a.path.length - b.path.length)[0];
+            if (!readme) {
+                const defaultBranch = st.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+                const sha = await resolvePlaneRef(repo, planeQueryRef(query), defaultBranch, root);
+                const top = sha ? await planeEntryAt(repo, sha, '', root) : null;
+                const entry = top?.kind === 'dir' ? top.entries.find((e) => e.type === 'blob' && /^readme(\.[a-z]+)?$/i.test(e.path)) : undefined;
+                if (entry) {
+                    const body = await planeFileContent(repo, planeQueryRef(query) ?? defaultBranch, entry.path, entry, root);
+                    if (body)
+                        return ctx.reply(body);
+                }
+                return send(ctx, githubNotFound());
+            }
+            return ctx.reply({
+                type: 'file', name: readme.path.split('/').pop(), path: readme.path, sha: readme.sha, size: readme.size ?? 0,
+                encoding: 'base64', content: readme.content_b64 ?? '',
+                url: `https://api.github.com/repos/${repo}/contents/${readme.path}`,
+                html_url: `https://github.com/${repo}/blob/${readme.branch ?? 'main'}/${readme.path}`,
+                download_url: `https://raw.githubusercontent.com/${repo}/${readme.branch ?? 'main'}/${readme.path}`,
+            });
+        },
+    };
+}

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

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

package/dist/src/semantics/deployments.js

@@ -0,0 +1,127 @@
+// A repository's deployments, their statuses, and its environments. A deployment's ref names a
+// commit, resolved through the git plane when the repository has history there. Creating a
+// deployment or a status announces its webhook.
+import { createHash } from 'node:crypto';
+import { githubNotFound, hasBareRepo, paginate, resolvePlaneRef, toGithubDeployment, toGithubDeploymentStatus, toGithubEnvironment } from "../github-twin.js";
+import { announce, gh, nextSeq, put, send } from "./shared.js";
+const deploymentOf = (ctx) => {
+    const { repo, seg, state } = gh(ctx);
+    const id = Number(decodeURIComponent(seg[4]));
+    const st = state();
+    return { id, st, dep: st.deployments.find((d) => d.repository === repo && d.id === id) };
+};
+export function deploymentsSemantics() {
+    const reposListDeployments = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const params = new URLSearchParams((query ?? '').replace(/^\?/, ''));
+        let inRepo = state().deployments.filter((d) => d.repository === repo);
+        const env = params.get('environment');
+        if (env)
+            inRepo = inRepo.filter((d) => d.environment === env);
+        const ref = params.get('ref');
+        if (ref)
+            inRepo = inRepo.filter((d) => d.ref === ref);
+        const sha = params.get('sha');
+        if (sha)
+            inRepo = inRepo.filter((d) => d.sha === sha);
+        return ctx.reply(paginate(inRepo, query).map(toGithubDeployment));
+    };
+    const reposGetDeployment = async (ctx) => {
+        const { dep } = deploymentOf(ctx);
+        return send(ctx, dep ? { status: 200, body: toGithubDeployment(dep) } : githubNotFound());
+    };
+    const reposCreateDeployment = async (ctx) => {
+        const { repo, body, occurredAt, caller, root, state } = gh(ctx);
+        if (body.ref === undefined)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Deployment', field: 'ref', code: 'missing_field' }] }, 422);
+        const id = nextSeq(ctx, 'deployment');
+        const ref = String(body.ref);
+        const plane = hasBareRepo(repo, root);
+        const planeSha = plane ? await resolvePlaneRef(repo, ref, state().repos.find((r) => r.full_name === repo)?.default_branch ?? 'main', root) : null;
+        if (plane && !planeSha)
+            return ctx.reply({ message: `No ref found for: ${ref}`, documentation_url: 'https://docs.github.com/rest/deployments/deployments#create-a-deployment' }, 422);
+        const sha = planeSha ?? (/^[0-9a-f]{40}$/i.test(ref) ? ref : createHash('sha256').update(`${repo}:dep:${ref}`).digest('hex').slice(0, 40));
+        const fields = { repository: repo, ref, sha, task: String(body.task ?? 'deploy'), environment: String(body.environment ?? 'production'), description: body.description ?? null, transient_environment: body.transient_environment === true, production_environment: body.production_environment === undefined ? String(body.environment ?? 'production') === 'production' : body.production_environment === true, created_at: occurredAt, updated_at: occurredAt, ...(caller ? { creator_login: caller } : {}) };
+        await put(ctx, { operation: 'deployment.create', subjectType: 'deployment', subjectId: `deployment:${id}`, fields });
+        const d = state().deployments.find((x) => x.id === id);
+        await announce(ctx, [{ event: 'deployment', action: 'created', repository: repo, number: 0 }]);
+        return ctx.reply(toGithubDeployment(d), 201);
+    };
+    const reposListDeploymentStatuses = async (ctx) => {
+        const { id, st, dep } = deploymentOf(ctx);
+        if (!dep)
+            return send(ctx, githubNotFound());
+        const { repo, query } = gh(ctx);
+        const items = st.deploymentStatuses.filter((s) => s.repository === repo && s.deployment_id === id).sort((a, b) => b.id - a.id);
+        return ctx.reply(paginate(items, query).map(toGithubDeploymentStatus));
+    };
+    const reposGetDeploymentStatus = async (ctx) => {
+        const { id, st, dep } = deploymentOf(ctx);
+        if (!dep)
+            return send(ctx, githubNotFound());
+        const { repo, seg } = gh(ctx);
+        const s = st.deploymentStatuses.find((x) => x.repository === repo && x.deployment_id === id && x.id === Number(decodeURIComponent(seg[6])));
+        return send(ctx, s ? { status: 200, body: toGithubDeploymentStatus(s) } : githubNotFound());
+    };
+    const reposCreateDeploymentStatus = async (ctx) => {
+        const { id: depId, dep } = deploymentOf(ctx);
+        if (!dep)
+            return send(ctx, githubNotFound());
+        const { repo, body, occurredAt, caller, state } = gh(ctx);
+        if (body.state === undefined)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'DeploymentStatus', field: 'state', code: 'missing_field' }] }, 422);
+        if (!['error', 'failure', 'inactive', 'in_progress', 'queued', 'pending', 'success'].includes(String(body.state)))
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'DeploymentStatus', field: 'state', code: 'invalid' }] }, 422);
+        const id = nextSeq(ctx, 'depstatus');
+        const fields = { repository: repo, deployment_id: depId, state: String(body.state), description: body.description ?? null, environment: body.environment ?? dep.environment, environment_url: body.environment_url, log_url: body.log_url, created_at: occurredAt, ...(caller ? { creator_login: caller } : {}) };
+        await put(ctx, { operation: 'deployment_status.create', subjectType: 'deployment_status', subjectId: `depstatus:${id}`, fields });
+        const s = state().deploymentStatuses.find((x) => x.id === id);
+        await announce(ctx, [{ event: 'deployment_status', action: 'created', repository: repo, number: 0 }]);
+        return ctx.reply(toGithubDeploymentStatus(s), 201);
+    };
+    const reposGetAllEnvironments = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const inRepo = state().environments.filter((e) => e.repository === repo);
+        return ctx.reply({ total_count: inRepo.length, environments: paginate(inRepo, query).map(toGithubEnvironment) });
+    };
+    const reposGetEnvironment = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const e = state().environments.find((x) => x.repository === repo && x.name === decodeURIComponent(seg[4]));
+        return send(ctx, e ? { status: 200, body: toGithubEnvironment(e) } : githubNotFound());
+    };
+    const reposCreateOrUpdateEnvironment = async (ctx) => {
+        const { repo, seg, body, occurredAt, state } = gh(ctx);
+        const name = decodeURIComponent(seg[4]);
+        const reviewers = Array.isArray(body.reviewers) ? body.reviewers.map((r) => String(r.reviewer?.login ?? r.login ?? r)) : undefined;
+        const fields = { repository: repo, name, wait_timer: body.wait_timer !== undefined ? Number(body.wait_timer) : undefined, reviewers, created_at: occurredAt, updated_at: occurredAt };
+        await put(ctx, { operation: 'environment.upsert', subjectType: 'environment', subjectId: `env:${repo}#${name}`, fields });
+        return ctx.reply(toGithubEnvironment(state().environments.find((x) => x.repository === repo && x.name === name)));
+    };
+    const reposDeleteAnEnvironment = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const name = decodeURIComponent(seg[4]);
+        if (!state().environments.find((e) => e.repository === repo && e.name === name))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'environment.delete', subjectType: 'environment', subjectId: `env:${repo}#${name}`, fields: { deleted: true, repository: repo, name } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    return {
+        // ?environment= / ?ref= / ?sha= filter, as GitHub's do
+        'repos/list-deployments': reposListDeployments,
+        'repos/get-deployment': reposGetDeployment,
+        // 422 without `ref`. A ref names a commit: resolved through the git plane when the repository has
+        // history there, where GitHub refuses a ref (or full sha) it cannot find; a repository known only
+        // through the API keeps a deterministic stand-in. A short sha is not expanded (the plane's object
+        // store has no prefix lookup) and is refused as unknown.
+        'repos/create-deployment': reposCreateDeployment,
+        // newest first, as GitHub lists them
+        'repos/list-deployment-statuses': reposListDeploymentStatuses,
+        'repos/get-deployment-status': reposGetDeploymentStatus,
+        'repos/create-deployment-status': reposCreateDeploymentStatus,
+        'repos/get-all-environments': reposGetAllEnvironments,
+        'repos/get-environment': reposGetEnvironment,
+        // create or update (200); reviewers are stored as logins
+        'repos/create-or-update-environment': reposCreateOrUpdateEnvironment,
+        'repos/delete-an-environment': reposDeleteAnEnvironment,
+    };
+}

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

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