@volter/twin-github 0.1.2 → 2.0.0

package/dist/src/semantics/issues.js

@@ -0,0 +1,456 @@
+import { authorAssociation, adoptedSubjectId, applyTriageFields, buildIssueTimeline, GITHUB_WORLD_USER, githubIssueId, githubNotFound, issueCommentCount, nextRepoNumber, normalizeLabels, paginate, pullRequestAsIssue, serializeIssueComment, serializeReviewComment, toGithubIssue, toGithubReaction, toLabels, } from "../github-twin.js";
+import { announce, asView, gh, nextSeq, put, send } from "./shared.js";
+/** What every issue door reads: the repository's issues and the issue face of each pull request. */
+function issuesOf(g) {
+    const st = g.state();
+    const repo = g.repo;
+    const inRepo = st.issues.filter((i) => i.repository === repo);
+    const pullsInRepo = st.prs.filter((p) => p.repository === repo && p.is_pull_request);
+    const pullByNumber = new Map(pullsInRepo.map((p) => [p.number, p]));
+    const asIssue = (i) => toGithubIssue(i, st.milestones, pullByNumber.get(i.number), st.comments);
+    // the repo's issues plus the issue face of each pull request (a number already an issue is not doubled)
+    const issueFaces = [...inRepo, ...pullsInRepo.filter((p) => !inRepo.some((i) => i.number === p.number)).map(pullRequestAsIssue)];
+    // A read INTO an issue 404s when nobody filed it: `200 []` would tell the caller the issue is real
+    // and quiet. A pull request number is a legitimate parent (a pull request IS an issue).
+    const issueFaceExists = (n) => issueFaces.some((i) => i.number === n);
+    // one timeline for every door onto it, so the timeline, the typed events and a single event agree
+    const timelineOf = (i) => buildIssueTimeline(repo, i, {
+        pull: pullByNumber.get(i.number),
+        comments: st.comments.filter((c) => c.repository === repo && c.number === i.number && c.kind === 'issue'),
+        reviews: st.reviews.filter((r) => r.repository === repo && r.number === i.number),
+    });
+    return { st, repo, inRepo, pullByNumber, asIssue, issueFaces, issueFaceExists, timelineOf };
+}
+const numberOf = (g) => Number(decodeURIComponent(g.seg[4]));
+const TYPED_EVENTS = new Set(['labeled', 'assigned', 'milestoned', 'locked', 'closed', 'reopened', 'merged', 'renamed', 'unlabeled', 'unassigned']);
+// GitHub's reaction content enum is fixed; an invalid content → 422.
+const REACTION_CONTENTS = ['+1', '-1', 'laugh', 'confused', 'heart', 'hooray', 'rocket', 'eyes'];
+/** The stored issue a write under /issues/:n names (the issue construct itself, not a pull request's face). */
+function storedIssue(g) {
+    const number = numberOf(g);
+    const id = `${g.repo}#issue:${number}`;
+    return { number, id, existing: g.state().issues.find((i) => i.id === id) };
+}
+/** The pull request a write under /issues/:n reaches when no issue was filed at that number: GitHub's pull
+ *  request is an issue, so its labels, assignees, milestone, title, body and state are written there too. */
+function pullAtIssueAddress(g, number) {
+    return g.state().prs.find((p) => p.is_pull_request && p.repository === g.repo && p.number === number);
+}
+/** GET a comment's reactions (the comment must exist, as its own address says). */
+const commentReactions = (kind) => async (ctx) => {
+    const { repo, seg, query, state } = gh(ctx);
+    const st = state();
+    const cid = decodeURIComponent(seg[5]);
+    if (!st.comments.some((c) => c.repository === repo && c.kind === kind && c.id === Number(cid)))
+        return send(ctx, githubNotFound());
+    return ctx.reply(paginate(st.reactions.filter((r) => r.repository === repo && r.subject_type === 'comment' && r.subject_key === cid), query).map(toGithubReaction));
+};
+/** POST a reaction on a comment, whose kind the path's family names. */
+const reactToComment = (kind) => async (ctx) => {
+    const { repo, seg, body, occurredAt, state } = gh(ctx);
+    const content = String(body.content ?? '');
+    if (!REACTION_CONTENTS.includes(content))
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Reaction', field: 'content', code: 'invalid' }] }, 422);
+    const cid = decodeURIComponent(seg[5]);
+    if (!state().comments.some((c) => c.repository === repo && c.kind === kind && c.id === Number(cid)))
+        return send(ctx, githubNotFound());
+    const seq = nextSeq(ctx, 'reaction');
+    await put(ctx, { operation: 'reaction.create', subjectType: 'reaction', subjectId: `reaction:${seq}`, fields: { repository: repo, subject_type: 'comment', subject_key: cid, content, created_at: occurredAt } });
+    return ctx.reply(toGithubReaction({ id: seq, repository: repo, subject_type: 'comment', subject_key: cid, content, created_at: occurredAt }), 201);
+};
+/** DELETE a reaction by id (the reaction's own id, whatever it reacts to, as the twin always read it). */
+const unreact = (idAt) => async (ctx) => {
+    const { repo, seg, state } = gh(ctx);
+    const id = Number(decodeURIComponent(seg[idAt]));
+    if (!state().reactions.find((r) => r.repository === repo && r.id === id))
+        return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'reaction.delete', subjectType: 'reaction', subjectId: `reaction:${id}`, fields: { deleted: true, repository: repo } });
+    return send(ctx, { status: 204, body: undefined });
+};
+/** The per-comment door: GitHub addresses a comment by its own id, without its issue or pull request;
+ *  issue comments and review comments are one stored construct with a `kind`, so both doors are this. */
+const commentDoor = (kind, removing) => async (ctx) => {
+    const { repo, seg, body, state } = gh(ctx);
+    const cid = Number(decodeURIComponent(seg[5]));
+    const existing = state().comments.find((c) => c.repository === repo && c.kind === kind && c.id === cid);
+    if (!existing)
+        return send(ctx, githubNotFound());
+    const subjectType = kind === 'review' ? 'pull_request_review_comment' : 'issue_comment';
+    const subjectId = existing.subject_id;
+    if (!subjectId)
+        throw new Error('Stored comment identity is unavailable');
+    const event = kind === 'review' ? 'pull_request_review_comment' : 'issue_comment';
+    const serialize = kind === 'review' ? serializeReviewComment : serializeIssueComment;
+    if (removing) {
+        const comment = serialize(existing);
+        await put(ctx, { operation: `${subjectType}.delete`, subjectType, subjectId, fields: { deleted: true, repository: repo, number: existing.number } });
+        await announce(ctx, [{ event, action: 'deleted', repository: repo, number: existing.number, comment }]);
+        return send(ctx, { status: 204, body: undefined });
+    }
+    if (body.body === undefined)
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: kind === 'review' ? 'PullRequestReviewComment' : 'IssueComment', field: 'body', code: 'missing_field' }] }, 422);
+    // updated_at moves off created_at: the only signal a consumer has that a comment was edited
+    await put(ctx, { operation: `${subjectType}.update`, subjectType, subjectId, fields: { repository: repo, number: existing.number, body: String(body.body), updated_at: gh(ctx).occurredAt } });
+    const comment = serialize(state().comments.find((c) => c.repository === repo && c.kind === kind && c.id === cid));
+    await announce(ctx, [{ event, action: 'edited', repository: repo, number: existing.number, comment }]);
+    return ctx.reply(comment);
+};
+/** The issue's labels written whole: POST adds (union), PUT sets, DELETE /:name removes one (404 when
+ *  it is not on the issue), DELETE removes all (204). The repository's label catalog is untouched. */
+/** A pull request read at its issue address: the pull request as an issue, or Not Found. */
+function pullAsIssue(ctx, pull, asIssue) {
+    return send(ctx, pull ? { status: 200, body: asIssue(pullRequestAsIssue(pull)) } : githubNotFound());
+}
+/** A label taken off the labels it is on, or nothing when it is not one of them. */
+function withoutLabel(current, name) {
+    return current.includes(name) ? current.filter((l) => l !== name) : undefined;
+}
+/** Labels written at a pull request's issue address: the pull request's, announced as its own event. */
+async function pullLabels(ctx, g, id, number, next, action, how) {
+    await put(ctx, { operation: 'pull_request.update', subjectType: 'pull_request', subjectId: id, fields: { number, repository: g.repo, labels: next } });
+    await announce(ctx, [{ event: 'pull_request', action, repository: g.repo, number }]);
+    return how === 'clear' ? send(ctx, { status: 204, body: undefined }) : ctx.reply(toLabels(next, g.repo, g.state().labels));
+}
+const writeLabels = (how) => async (ctx) => {
+    const g = gh(ctx);
+    const { repo, seg, body, occurredAt } = g;
+    const { number, id, existing } = storedIssue(g);
+    const pull = existing ? undefined : pullAtIssueAddress(g, number);
+    if (!existing && !pull)
+        return send(ctx, githubNotFound());
+    const current = (existing ?? pull).labels ?? [];
+    const next = how === 'remove' ? withoutLabel(current, decodeURIComponent(seg.slice(6).join('/'))) : how === 'clear' ? [] : how === 'set' ? normalizeLabels(body.labels) : [...current, ...normalizeLabels(body.labels).filter((l, i, all) => !current.includes(l) && all.indexOf(l) === i)];
+    if (!next)
+        return send(ctx, githubNotFound());
+    const action = how === 'add' || how === 'set' ? 'labeled' : 'unlabeled';
+    if (pull)
+        return pullLabels(ctx, g, pull.id, number, next, action, how);
+    await put(ctx, { operation: action === 'labeled' ? 'issue.add_labels' : 'issue.remove_labels', subjectType: 'issue', subjectId: id, fields: { number, repository: repo, labels: next, updated_at: occurredAt } });
+    const answer = how === 'clear' ? undefined : toLabels(g.state().issues.find((i) => i.id === id)?.labels, repo, g.state().labels);
+    await announce(ctx, [{ event: 'issues', action, repository: repo, number }]);
+    return how === 'clear' ? send(ctx, { status: 204, body: undefined }) : ctx.reply(answer);
+};
+// A pull request's conversation locks by its number here as an issue's does (GitHub's pull request is an
+// issue): the pull request carries `locked` and announces pull_request locked/unlocked.
+const lock = (locking) => async (ctx) => {
+    const g = gh(ctx);
+    const { number, id, existing } = storedIssue(g);
+    const reason = locking ? (g.body.lock_reason ?? null) : null;
+    if (!existing) {
+        const pull = g.state().prs.find((p) => p.is_pull_request && p.repository === g.repo && p.number === number);
+        if (!pull)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: locking ? 'pull_request.lock' : 'pull_request.unlock', subjectType: 'pull_request', subjectId: pull.id, fields: { number, repository: g.repo, locked: locking, active_lock_reason: reason } });
+        await announce(ctx, [{ event: 'pull_request', action: locking ? 'locked' : 'unlocked', repository: g.repo, number }]);
+        return send(ctx, { status: 204, body: undefined });
+    }
+    await put(ctx, { operation: locking ? 'issue.lock' : 'issue.unlock', subjectType: 'issue', subjectId: id, fields: { number, repository: g.repo, locked: locking, active_lock_reason: reason, updated_at: g.occurredAt } });
+    await announce(ctx, [{ event: 'issues', action: locking ? 'locked' : 'unlocked', repository: g.repo, number }]);
+    return send(ctx, { status: 204, body: undefined });
+};
+/** The issue list, with GitHub's documented filters over the state the twin models: state (default
+ *  open), labels (ANDed), assignee (a login, `none`, `*`), since, sort created|updated|comments with
+ *  direction (default desc; ties by number). `creator` and `mentioned` are not served (the author and
+ *  mentions are unmodeled). Pull requests carry no created_at/updated_at, so they sort with the
+ *  undated rows and `since` never selects one. */
+function listIssues(ctx) {
+    const g = gh(ctx);
+    const { st, repo, asIssue, issueFaces } = issuesOf(g);
+    const lq = new URLSearchParams((g.query ?? '').replace(/^\?/, ''));
+    const stateF = (lq.get('state') ?? 'open').toLowerCase();
+    const labelsF = (lq.get('labels') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const assigneeF = lq.get('assignee') ?? undefined;
+    const sinceMs = lq.get('since') ? Date.parse(lq.get('since')) : Number.NaN;
+    const filtered = issueFaces.filter((i) => {
+        if (stateF !== 'all' && (i.state ?? 'open') !== stateF)
+            return false;
+        if (labelsF.length && !labelsF.every((l) => (i.labels ?? []).includes(l)))
+            return false;
+        if (assigneeF !== undefined) {
+            const on = i.assignees ?? [];
+            if (assigneeF === 'none') {
+                if (on.length)
+                    return false;
+            }
+            else if (assigneeF === '*') {
+                if (!on.length)
+                    return false;
+            }
+            else if (!on.includes(assigneeF))
+                return false;
+        }
+        if (Number.isFinite(sinceMs)) {
+            const upd = Date.parse(i.updated_at ?? i.created_at ?? '');
+            if (!Number.isFinite(upd) || upd < sinceMs)
+                return false;
+        }
+        return true;
+    });
+    const dir = (lq.get('direction') ?? 'desc').toLowerCase() === 'asc' ? 1 : -1;
+    const sortF = (lq.get('sort') ?? '').toLowerCase();
+    const sortKey = (i) => (sortF === 'updated' ? (i.updated_at ?? i.created_at ?? '') : (i.created_at ?? ''));
+    const ordered = [...filtered].sort((a, b) => {
+        if (sortF === 'comments') {
+            const ca = issueCommentCount(repo, a.number, st.comments);
+            const cb = issueCommentCount(repo, b.number, st.comments);
+            if (ca !== cb)
+                return ca < cb ? -dir : dir;
+            return (a.number - b.number) * dir;
+        }
+        const ka = sortKey(a);
+        const kb = sortKey(b);
+        if (ka !== kb)
+            return ka < kb ? -dir : dir;
+        return (a.number - b.number) * dir;
+    });
+    return ctx.reply(paginate(ordered, g.query).map(asIssue));
+}
+/** The issues visible to a sub-issue answer. */
+const asPlainIssue = (st, i) => toGithubIssue(i, st.milestones, undefined, st.comments);
+export function issuesSemantics() {
+    const issuesListEventsForRepo = async (ctx) => {
+        const g = gh(ctx);
+        const { issueFaces, timelineOf } = issuesOf(g);
+        const items = issueFaces.flatMap((i) => timelineOf(i).filter((e) => TYPED_EVENTS.has(String(e.event))).map((e) => asView('issue-event', { ...e, issue: { number: i.number, title: i.title } })));
+        return ctx.reply(paginate(items, g.query));
+    };
+    const issuesGetEvent = async (ctx) => {
+        const g = gh(ctx);
+        const { issueFaces, timelineOf } = issuesOf(g);
+        const eid = Number(decodeURIComponent(g.seg[5]));
+        for (const i of issueFaces) {
+            const ev = timelineOf(i).find((e) => e.id === eid && e.event !== 'cross-referenced');
+            if (ev)
+                return ctx.reply({ ...ev, issue: { number: i.number, title: i.title } });
+        }
+        return send(ctx, githubNotFound());
+    };
+    const issuesListEvents = async (ctx) => {
+        const g = gh(ctx);
+        const { issueFaces, timelineOf } = issuesOf(g);
+        const iss = issueFaces.find((i) => i.number === numberOf(g));
+        if (!iss)
+            return send(ctx, githubNotFound());
+        return ctx.reply(paginate(timelineOf(iss).filter((e) => TYPED_EVENTS.has(String(e.event))).map((e) => asView('issue-event-for-issue', e)), g.query));
+    };
+    const issuesListComments = async (ctx) => {
+        const g = gh(ctx);
+        const { st, repo, issueFaceExists } = issuesOf(g);
+        const n = numberOf(g);
+        if (!issueFaceExists(n))
+            return send(ctx, githubNotFound());
+        return ctx.reply(paginate(st.comments.filter((c) => c.repository === repo && c.number === n && c.kind === 'issue'), g.query).map(serializeIssueComment));
+    };
+    const issuesGetComment = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const cid = Number(decodeURIComponent(seg[5]));
+        const c = state().comments.find((x) => x.repository === repo && x.kind === 'issue' && x.id === cid);
+        return send(ctx, c ? { status: 200, body: serializeIssueComment(c) } : githubNotFound());
+    };
+    const issuesListSubIssues = async (ctx) => {
+        const g = gh(ctx);
+        const { st, inRepo, issueFaceExists } = issuesOf(g);
+        const n = numberOf(g);
+        if (!issueFaceExists(n))
+            return send(ctx, githubNotFound());
+        const childNums = inRepo.find((i) => i.number === n)?.sub_issue_numbers ?? [];
+        const items = childNums.map((cn) => inRepo.find((i) => i.number === cn)).filter((i) => !!i);
+        return ctx.reply(paginate(items, g.query).map((i) => asPlainIssue(st, i)));
+    };
+    const issuesListLabelsOnIssue = async (ctx) => {
+        const g = gh(ctx);
+        const iss = issuesOf(g).issueFaces.find((i) => i.number === numberOf(g));
+        return send(ctx, iss ? { status: 200, body: paginate(toLabels(iss.labels, g.repo, g.state().labels), g.query) } : githubNotFound());
+    };
+    const reactionsListForIssue = async (ctx) => {
+        const g = gh(ctx);
+        const { st, repo, issueFaceExists } = issuesOf(g);
+        const n = numberOf(g);
+        if (!issueFaceExists(n))
+            return send(ctx, githubNotFound());
+        return ctx.reply(paginate(st.reactions.filter((r) => r.repository === repo && r.subject_type === 'issue' && r.subject_key === String(n)), g.query).map(toGithubReaction));
+    };
+    const issuesUpdate = async (ctx) => {
+        const g = gh(ctx);
+        const { repo, body, occurredAt, state } = g;
+        const { number, id, existing } = storedIssue(g);
+        if (!existing) {
+            const pull = pullAtIssueAddress(g, number);
+            if (!pull)
+                return send(ctx, githubNotFound());
+            const fields = { number, repository: repo };
+            if (body.title !== undefined)
+                fields.title = body.title;
+            if (body.body !== undefined)
+                fields.body = body.body;
+            if (body.state !== undefined)
+                fields.state = body.state;
+            applyTriageFields(fields, body);
+            await put(ctx, { operation: 'pull_request.update', subjectType: 'pull_request', subjectId: pull.id, fields });
+            const { asIssue, pullByNumber } = issuesOf(g);
+            await announce(ctx, [{ event: 'pull_request', action: body.state === 'closed' ? 'closed' : body.state === 'open' ? 'reopened' : 'edited', repository: repo, number }]);
+            return ctx.reply(asIssue(pullRequestAsIssue(pullByNumber.get(number))));
+        }
+        const fields = { number, repository: repo, updated_at: occurredAt };
+        if (body.title !== undefined)
+            fields.title = body.title;
+        if (body.body !== undefined)
+            fields.body = body.body;
+        if (body.state !== undefined)
+            fields.state = body.state;
+        if (body.state_reason !== undefined)
+            fields.state_reason = body.state_reason === null ? null : String(body.state_reason);
+        if (body.state === 'closed' && body.state_reason === undefined && (existing.state ?? 'open') !== 'closed')
+            fields.state_reason = 'completed';
+        if (body.state === 'open' && body.state_reason === undefined && (existing.state ?? 'open') === 'closed')
+            fields.state_reason = 'reopened';
+        applyTriageFields(fields, body);
+        await put(ctx, { operation: 'issue.update', subjectType: 'issue', subjectId: id, fields });
+        const st = state();
+        const iss = st.issues.find((i) => i.id === id);
+        const issue = iss ? toGithubIssue(iss, st.milestones, undefined, st.comments) : { number };
+        await announce(ctx, [{ event: 'issues', action: body.state === 'closed' ? 'closed' : 'edited', repository: repo, number, issue }]);
+        return ctx.reply(issue);
+    };
+    const reactionsCreateForIssue = async (ctx) => {
+        const g = gh(ctx);
+        const { repo, body, occurredAt, state } = g;
+        const content = String(body.content ?? '');
+        if (!REACTION_CONTENTS.includes(content))
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Reaction', field: 'content', code: 'invalid' }] }, 422);
+        const number = decodeURIComponent(g.seg[4]);
+        const st = state();
+        if (!(st.issues.some((i) => i.repository === repo && i.number === Number(number)) || st.prs.some((p) => p.repository === repo && p.number === Number(number) && p.is_pull_request)))
+            return send(ctx, githubNotFound());
+        const seq = nextSeq(ctx, 'reaction');
+        await put(ctx, { operation: 'reaction.create', subjectType: 'reaction', subjectId: `reaction:${seq}`, fields: { repository: repo, subject_type: 'issue', subject_key: number, content, created_at: occurredAt } });
+        return ctx.reply(toGithubReaction({ id: seq, repository: repo, subject_type: 'issue', subject_key: number, content, created_at: occurredAt }), 201);
+    };
+    const issuesAddSubIssue = async (ctx) => {
+        const g = gh(ctx);
+        const { repo, body, occurredAt, state } = g;
+        const number = numberOf(g);
+        const parentId = `${repo}#issue:${number}`;
+        const st0 = state();
+        const parent = st0.issues.find((i) => i.id === parentId);
+        const child = st0.issues.find((i) => i.repository === repo && githubIssueId(i.born_in ?? repo, i.number) === Number(body.sub_issue_id));
+        const childNum = child?.number ?? 0;
+        if (!parent || !child)
+            return send(ctx, githubNotFound());
+        const merged = [...(parent.sub_issue_numbers ?? [])];
+        if (!merged.includes(childNum))
+            merged.push(childNum);
+        await put(ctx, { operation: 'issue.add_sub_issue', subjectType: 'issue', subjectId: parentId, fields: { number, repository: repo, sub_issue_numbers: merged, updated_at: occurredAt } });
+        await put(ctx, { operation: 'issue.set_parent', subjectType: 'issue', subjectId: child.id, fields: { number: childNum, repository: repo, parent_issue_number: number, updated_at: occurredAt } });
+        const st = state();
+        const answer = asPlainIssue(st, st.issues.find((i) => i.id === parentId));
+        await announce(ctx, [{ event: 'issues', action: 'edited', repository: repo, number }]);
+        return ctx.reply(answer, 201);
+    };
+    const issuesRemoveSubIssue = async (ctx) => {
+        const g = gh(ctx);
+        const { repo, body, occurredAt, state } = g;
+        const number = numberOf(g);
+        const parentId = `${repo}#issue:${number}`;
+        const childNum = state().issues.find((i) => i.repository === repo && githubIssueId(i.born_in ?? repo, i.number) === Number(body.sub_issue_id))?.number;
+        const parent = state().issues.find((i) => i.id === parentId);
+        if (!parent || childNum === undefined)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'issue.remove_sub_issue', subjectType: 'issue', subjectId: parentId, fields: { number, repository: repo, sub_issue_numbers: (parent.sub_issue_numbers ?? []).filter((cn) => cn !== childNum), updated_at: occurredAt } });
+        const st = state();
+        return ctx.reply(asPlainIssue(st, st.issues.find((i) => i.id === parentId)));
+    };
+    return {
+        'issues/list-for-repo': async (ctx) => listIssues(ctx),
+        // a pull request answers at its issue address too, carrying the `pull_request` key
+        'issues/get': async (ctx) => {
+            const g = gh(ctx);
+            const { inRepo, pullByNumber, asIssue } = issuesOf(g);
+            const n = numberOf(g);
+            const iss = inRepo.find((i) => i.number === n);
+            return iss ? ctx.reply(asIssue(iss)) : pullAsIssue(ctx, pullByNumber.get(n), asIssue);
+        },
+        // the typed issue events across the repo (cross-references are timeline-only; `merged` is typed)
+        'issues/list-events-for-repo': issuesListEventsForRepo,
+        'issues/get-event': issuesGetEvent,
+        // An issue's timeline and events: derived state changes (from the issue's present labels,
+        // assignees and milestone, and its open/closed history), the merge, reviews, comments and
+        // cross-references; a pull request number answers too.
+        // an issue's events are its typed events; comments and cross-references are the timeline's
+        'issues/list-events': issuesListEvents,
+        'issues/list-events-for-timeline': async (ctx) => timeline(ctx),
+        // issue comments (a pull request takes them too)
+        'issues/list-comments': issuesListComments,
+        'issues/get-comment': issuesGetComment,
+        'issues/list-sub-issues': issuesListSubIssues,
+        // the labels ON the issue (a pull request carries them too)
+        'issues/list-labels-on-issue': issuesListLabelsOnIssue,
+        'reactions/list-for-issue': reactionsListForIssue,
+        'reactions/list-for-issue-comment': commentReactions('issue'),
+        'reactions/list-for-pull-request-review-comment': commentReactions('review'),
+        // 422 without a title; labels, assignees and milestone are taken on create as on edit
+        'issues/create': async (ctx) => {
+            const { repo, body, occurredAt, root, state, caller } = gh(ctx);
+            if (!body.title)
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Issue', field: 'title', code: 'missing_field' }] }, 422);
+            const number = nextRepoNumber(state(), repo);
+            const id = `${repo}#issue:${number}`;
+            const fields = { number, repository: repo, title: body.title, body: body.body, state: 'open', created_at: occurredAt, updated_at: occurredAt, user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(state(), repo, caller ?? GITHUB_WORLD_USER) };
+            applyTriageFields(fields, body);
+            await put(ctx, { operation: 'issue.create', subjectType: 'issue', subjectId: id, fields });
+            // Under live use the head performed the write and adopted the vendor's number; the answer
+            // carries it, read back from state so the create answer and a later GET agree.
+            const answeredId = adoptedSubjectId('issue', id, root);
+            const answeredNumber = Number(answeredId.split('#issue:').pop()) || number;
+            const st = state();
+            const created = st.issues.find((i) => i.id === answeredId) ?? st.issues.find((i) => i.id === id);
+            const out = created ? toGithubIssue(created, st.milestones, undefined, st.comments) : toGithubIssue({ id: answeredId, number: answeredNumber, repository: repo, title: body.title, body: body.body, state: 'open', created_at: occurredAt, updated_at: occurredAt });
+            await announce(ctx, [{ event: 'issues', action: 'opened', repository: repo, number: answeredNumber, issue: out }]);
+            return ctx.reply(out, 201);
+        },
+        // Closing with no reason is `completed`; reopening a closed issue is `reopened` (an explicit
+        // state_reason always wins).
+        'issues/update': issuesUpdate,
+        // a comment on an issue or a pull request, by the caller the token names
+        'issues/create-comment': async (ctx) => {
+            const g = gh(ctx);
+            const { repo, body, occurredAt, caller, state } = g;
+            const number = numberOf(g);
+            const st = state();
+            if (!(st.issues.some((i) => i.repository === repo && i.number === number) || st.prs.some((p) => p.repository === repo && p.number === number && p.is_pull_request)))
+                return send(ctx, githubNotFound());
+            const seq = nextSeq(ctx, 'comment');
+            await put(ctx, { operation: 'issue_comment.create', subjectType: 'issue_comment', subjectId: `comment:${seq}`, fields: { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt, user_login: caller ?? GITHUB_WORLD_USER } });
+            const comment = serializeIssueComment(state().comments.find((c) => c.repository === repo && c.kind === 'issue' && c.id === seq));
+            await announce(ctx, [{ event: 'issue_comment', action: 'created', repository: repo, number, comment }]);
+            return ctx.reply(comment, 201);
+        },
+        'issues/update-comment': commentDoor('issue', false),
+        'issues/delete-comment': commentDoor('issue', true),
+        'pulls/update-review-comment': commentDoor('review', false),
+        'pulls/delete-review-comment': commentDoor('review', true),
+        // a reaction on an issue or a pull request's issue face
+        'reactions/create-for-issue': reactionsCreateForIssue,
+        'reactions/create-for-issue-comment': reactToComment('issue'),
+        'reactions/create-for-pull-request-review-comment': reactToComment('review'),
+        'reactions/delete-for-issue': unreact(6),
+        'reactions/delete-for-issue-comment': unreact(7),
+        'reactions/delete-for-pull-request-comment': unreact(7),
+        'issues/add-labels': writeLabels('add'),
+        'issues/set-labels': writeLabels('set'),
+        'issues/remove-label': writeLabels('remove'),
+        'issues/remove-all-labels': writeLabels('clear'),
+        'issues/lock': lock(true),
+        'issues/unlock': lock(false),
+        // attach a child issue, named by its id (not its number), to a parent: both sides are written (201, the parent)
+        'issues/add-sub-issue': issuesAddSubIssue,
+        // detach a child (the body names it)
+        'issues/remove-sub-issue': issuesRemoveSubIssue,
+    };
+}
+function timeline(ctx) {
+    const g = gh(ctx);
+    const { issueFaces, timelineOf } = issuesOf(g);
+    const iss = issueFaces.find((i) => i.number === numberOf(g));
+    return send(ctx, iss ? { status: 200, body: paginate(timelineOf(iss), g.query) } : githubNotFound());
+}

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

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

package/dist/src/semantics/keys.js

@@ -0,0 +1,66 @@
+import { githubNotFound, paginate, toGithubAutolink, toGithubDeployKey } from "../github-twin.js";
+import { gh, nextSeq, put, send } from "./shared.js";
+const idOf = (ctx) => Number(decodeURIComponent(gh(ctx).seg[4]));
+export function keysSemantics() {
+    const reposListDeployKeys = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().deployKeys.filter((k) => k.repository === repo), query).map(toGithubDeployKey));
+    };
+    const reposGetDeployKey = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const k = state().deployKeys.find((x) => x.repository === repo && x.id === idOf(ctx));
+        return send(ctx, k ? { status: 200, body: toGithubDeployKey(k) } : githubNotFound());
+    };
+    const reposCreateDeployKey = async (ctx) => {
+        const { repo, body, occurredAt, state } = gh(ctx);
+        if (!body.key)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'DeployKey', field: 'key', code: 'missing_field' }] }, 422);
+        const id = nextSeq(ctx, 'deploykey');
+        await put(ctx, { operation: 'deploy_key.create', subjectType: 'deploy_key', subjectId: `deploykey:${id}`, fields: { repository: repo, key: String(body.key), title: String(body.title ?? ''), read_only: body.read_only !== false, created_at: occurredAt } });
+        return ctx.reply(toGithubDeployKey(state().deployKeys.find((x) => x.id === id)), 201);
+    };
+    const reposDeleteDeployKey = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const id = idOf(ctx);
+        if (!state().deployKeys.find((k) => k.repository === repo && k.id === id))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'deploy_key.delete', subjectType: 'deploy_key', subjectId: `deploykey:${id}`, fields: { deleted: true, repository: repo } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const reposListAutolinks = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().autolinks.filter((a) => a.repository === repo), query).map(toGithubAutolink));
+    };
+    const reposGetAutolink = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const a = state().autolinks.find((x) => x.repository === repo && x.id === idOf(ctx));
+        return send(ctx, a ? { status: 200, body: toGithubAutolink(a) } : githubNotFound());
+    };
+    const reposCreateAutolink = async (ctx) => {
+        const { repo, body, state } = gh(ctx);
+        const missing = ['key_prefix', 'url_template'].filter((k) => !body[k]);
+        if (missing.length)
+            return ctx.reply({ message: 'Validation Failed', errors: missing.map((field) => ({ resource: 'KeyLink', field, code: 'missing_field' })) }, 422);
+        const id = nextSeq(ctx, 'autolink');
+        await put(ctx, { operation: 'autolink.create', subjectType: 'autolink', subjectId: `autolink:${id}`, fields: { repository: repo, key_prefix: String(body.key_prefix), url_template: String(body.url_template), is_alphanumeric: body.is_alphanumeric !== false } });
+        return ctx.reply(toGithubAutolink(state().autolinks.find((x) => x.id === id)), 201);
+    };
+    const reposDeleteAutolink = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const id = idOf(ctx);
+        if (!state().autolinks.find((a) => a.repository === repo && a.id === id))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'autolink.delete', subjectType: 'autolink', subjectId: `autolink:${id}`, fields: { deleted: true, repository: repo } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    return {
+        'repos/list-deploy-keys': reposListDeployKeys,
+        'repos/get-deploy-key': reposGetDeployKey,
+        'repos/create-deploy-key': reposCreateDeployKey,
+        'repos/delete-deploy-key': reposDeleteDeployKey,
+        'repos/list-autolinks': reposListAutolinks,
+        'repos/get-autolink': reposGetAutolink,
+        'repos/create-autolink': reposCreateAutolink,
+        'repos/delete-autolink': reposDeleteAutolink,
+    };
+}

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

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

package/dist/src/semantics/labels.js

@@ -0,0 +1,100 @@
+import { GITHUB_WORLD_USER, githubNotFound, paginate, toGithubLabel, toGithubMilestone } from "../github-twin.js";
+import { gh, nextSeq, put, send } from "./shared.js";
+/** A label's name as the path names it (a name may hold a slash). */
+const labelName = (ctx) => decodeURIComponent(gh(ctx).seg.slice(4).join('/'));
+export function labelsSemantics() {
+    const issuesListLabelsForRepo = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().labels.filter((l) => l.repository === repo), query).map(toGithubLabel));
+    };
+    const issuesGetLabel = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const name = labelName(ctx);
+        const l = state().labels.find((x) => x.repository === repo && x.name === name);
+        return send(ctx, l ? { status: 200, body: toGithubLabel(l) } : githubNotFound());
+    };
+    const issuesUpdateLabel = async (ctx) => {
+        const { repo, body, state } = gh(ctx);
+        const name = labelName(ctx);
+        const existing = state().labels.find((l) => l.repository === repo && l.name === name);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        const fields = { repository: repo, name: body.new_name !== undefined ? String(body.new_name) : name };
+        if (body.color !== undefined)
+            fields.color = String(body.color);
+        if (body.description !== undefined)
+            fields.description = body.description;
+        await put(ctx, { operation: 'label.update', subjectType: 'label', subjectId: `label:${existing.id}`, fields });
+        return ctx.reply(toGithubLabel(state().labels.find((l) => l.id === existing.id)));
+    };
+    const issuesDeleteLabel = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const name = labelName(ctx);
+        const existing = state().labels.find((l) => l.repository === repo && l.name === name);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'label.delete', subjectType: 'label', subjectId: `label:${existing.id}`, fields: { deleted: true, repository: repo, name } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const issuesListMilestones = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().milestones.filter((m) => m.repository === repo), query).map(toGithubMilestone));
+    };
+    return {
+        'issues/list-labels-for-repo': issuesListLabelsForRepo,
+        'issues/get-label': issuesGetLabel,
+        'issues/create-label': async (ctx) => {
+            const { repo, body, state } = gh(ctx);
+            if (!body.name)
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Label', field: 'name', code: 'missing_field' }] }, 422);
+            const name = String(body.name);
+            if (state().labels.find((l) => l.repository === repo && l.name === name))
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Label', code: 'already_exists', field: 'name' }] }, 422);
+            const seq = nextSeq(ctx, 'label');
+            const fields = { repository: repo, name, color: body.color ?? 'ededed', description: body.description ?? null, default: false };
+            await put(ctx, { operation: 'label.create', subjectType: 'label', subjectId: `label:${seq}`, fields });
+            return ctx.reply(toGithubLabel({ id: seq, repository: repo, name, color: body.color ?? 'ededed', description: body.description ?? null, default: false }), 201);
+        },
+        // an edit may rename the label (`new_name`)
+        'issues/update-label': issuesUpdateLabel,
+        'issues/delete-label': issuesDeleteLabel,
+        'issues/list-milestones': issuesListMilestones,
+        'issues/get-milestone': async (ctx) => {
+            const { repo, seg, state } = gh(ctx);
+            const n = Number(decodeURIComponent(seg[4]));
+            const ms = state().milestones.find((m) => m.repository === repo && m.number === n);
+            return send(ctx, ms ? { status: 200, body: toGithubMilestone(ms) } : githubNotFound());
+        },
+        // numbered per repository: one past the highest
+        'issues/create-milestone': async (ctx) => {
+            const { repo, body, occurredAt, state, caller } = gh(ctx);
+            if (!body.title)
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Milestone', field: 'title', code: 'missing_field' }] }, 422);
+            let number = 0;
+            for (const m of state().milestones)
+                if (m.repository === repo)
+                    number = Math.max(number, m.number);
+            number += 1;
+            const fields = { number, repository: repo, title: body.title, description: body.description, state: body.state ?? 'open', due_on: body.due_on, created_at: occurredAt, updated_at: occurredAt, creator_login: caller ?? GITHUB_WORLD_USER };
+            await put(ctx, { operation: 'milestone.create', subjectType: 'milestone', subjectId: `${repo}#milestone:${number}`, fields });
+            return ctx.reply(toGithubMilestone(state().milestones.find((m) => m.repository === repo && m.number === number)), 201);
+        },
+        'issues/update-milestone': async (ctx) => {
+            const { repo, seg, body, occurredAt, state } = gh(ctx);
+            const number = Number(decodeURIComponent(seg[4]));
+            if (!state().milestones.find((m) => m.id !== undefined && m.repository === repo && m.number === number))
+                return send(ctx, githubNotFound());
+            const fields = { number, repository: repo, updated_at: occurredAt };
+            if (body.title !== undefined)
+                fields.title = body.title;
+            if (body.description !== undefined)
+                fields.description = body.description;
+            if (body.state !== undefined)
+                fields.state = body.state;
+            if (body.due_on !== undefined)
+                fields.due_on = body.due_on;
+            await put(ctx, { operation: 'milestone.update', subjectType: 'milestone', subjectId: `${repo}#milestone:${number}`, fields });
+            return ctx.reply(toGithubMilestone(state().milestones.find((m) => m.repository === repo && m.number === number)));
+        },
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { Semantics } from '@volter/world-core';
+/** A .gitignore template's text, by its name (any case); undefined for a name the catalog lacks. */
+export declare function gitignoreTemplate(name: string): string | undefined;
+/** 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 declare function licenseTemplate(key: string, fill?: {
+    year: string;
+    fullname: string;
+}): string | undefined;
+export declare function metaSemantics(_opts: {
+    readOnly?: boolean;
+}): Record<string, Semantics>;