@rse/ase 1.0.6 → 2.0.0

package/dst/ase-task-store-plugin-github.js

@@ -0,0 +1,696 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { Octokit } from "@octokit/core";
+import { restEndpointMethods } from "@octokit/plugin-rest-endpoint-methods";
+import { paginateRest } from "@octokit/plugin-paginate-rest";
+import { LRUCache } from "lru-cache";
+import * as TaskFormat from "./ase-task-format.js";
+import * as TaskIssues from "./ase-task-store-issues.js";
+/*  the GitHub REST API client: the core with the endpoint methods and the pagination  */
+const GitHub = Octokit.plugin(restEndpointMethods, paginateRest);
+/*  the reserved labels, the task id mapping, and the timestamp of the common issue tracker parts  */
+const { LABEL_PROJECT, LABEL_DELETED, LABEL_KEY_RE, idOf, numberOf, stamp } = TaskIssues;
+/*  the "ase:Group:<id>" and "ase:After:<ids>" labels carrying the parent resp. blocking
+    issues where the GitHub instance lacks sub-issues resp. issue dependencies (like
+    older GitHub Enterprise Server versions), the latter's task ids separated by spaces  */
+const LABEL_RELATION_RE = /^ase:(Group|After):(.*)$/;
+/*  the REST API base URL of the web URL of a GitHub instance: GitHub itself,
+    GitHub Enterprise Cloud with data residency ("<sub>.ghe.com"), or GitHub
+    Enterprise Server (with its REST API below "/api/v3")  */
+const apiBaseOf = (base) => base.hostname.toLowerCase() === "github.com" ? "https://api.github.com" :
+    /\.ghe\.com$/i.test(base.hostname) ? `https://api.${base.host}` :
+        `${base.href.replace(/\/+$/, "")}/api/v3`;
+/*  the header keys mapped onto native issue fields (or derived from them),
+    hence never carried by "ase:<key>:<value>" labels  */
+const nativeKeys = ["Type", "Id", "Created", "Modified", "Group", "Phase", "After", "Tags", "Assignee"];
+/*  the current time as ISO timestamp in the second-precise shape of GitHub  */
+const now = () => new Date().toISOString().replace(/\.\d+Z$/, "Z");
+/*  map a "not found" (404) or "gone" (410) request failure onto null  */
+const statusOf = (err) => err?.status;
+const found = (p) => p.catch((err) => {
+    if (statusOf(err) === 404 || statusOf(err) === 410)
+        return null;
+    throw err;
+});
+/*  the label names of an issue, and whether an issue is a live task (no pull request, not soft deleted)  */
+const labelNames = (issue) => issue.labels.map((label) => typeof label === "string" ? label : label.name ?? "");
+const live = (issue) => (issue.pull_request === undefined || issue.pull_request === null) && !labelNames(issue).includes(LABEL_DELETED);
+/*  whether an owner/repo pair denotes the given repository, the parent issue number
+    of an issue within it (else null), and whether an issue belongs to it  */
+const sameRepo = (loc, owner, repo) => owner.toLowerCase() === loc.owner.toLowerCase() && repo.toLowerCase() === loc.repo.toLowerCase();
+const parentOf = (loc, issue) => {
+    const m = /\/repos\/([^/]+)\/([^/]+)\/issues\/(\d+)$/.exec(issue.parent_issue_url ?? "");
+    return m !== null && sameRepo(loc, m[1], m[2]) ? Number.parseInt(m[3], 10) : null;
+};
+const inRepo = (loc, issue) => {
+    const m = /\/repos\/([^/]+)\/([^/]+)$/.exec(issue.repository_url);
+    return m !== null && sameRepo(loc, m[1], m[2]);
+};
+/*  the GitHub storage plugin: a project is a repository (registered by its
+    "ase:project" label) and a task plan is a live issue, its id being the issue
+    number rendered through the mandatory "seq" task id scheme; the title maps onto
+    the issue title (and the "#   TASK:" heading), the body onto the issue body,
+    "Status" onto the issue state refined by an "ase:Status:<state>" label, "Tags"
+    onto labels, "Assignee" onto the assignee, "Phase" onto the milestone, "Group"
+    onto the parent issue, "After" onto the blocking issues, "Created"/"Modified"
+    onto the issue timestamps, any other key onto "ase:<key>:<value>" labels, and
+    the attachments onto the issue comments (where "Group" and "After" fall back
+    onto "ase:Group:<id>" resp. "ase:After:<ids>" labels on instances without
+    sub-issues resp. issue dependencies)  */
+class GitHubTaskStoragePlugin {
+    ctx;
+    name = "github";
+    url;
+    gh;
+    repos = new Map();
+    poll;
+    listener = null;
+    timer = null;
+    polling = false;
+    opened = now();
+    polls = new Map();
+    registry = new LRUCache({ max: 64, ttl: 60 * 1000 });
+    latest = new Map();
+    labels = new Map();
+    milestones = new Map();
+    unsupported = new Map();
+    recent = new Map();
+    loads = new LRUCache({ max: 256, ttl: 2 * 1000 });
+    constructor(ctx) {
+        this.ctx = ctx;
+        const options = ctx.options;
+        const token = options.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? "";
+        if (typeof token !== "string" || token === "")
+            throw new Error("task store: plugin \"github\" requires the \"token\" option (or $GITHUB_TOKEN resp. $GH_TOKEN)");
+        const url = options.url ?? "https://github.com";
+        let base = null;
+        try {
+            base = new URL(typeof url === "string" && !/^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? `https://${url}` : url);
+        }
+        catch {
+            /*  reported below  */
+        }
+        if (base === null || !/^https?:$/.test(base.protocol) || base.search !== "" || base.hash !== "")
+            throw new Error(`task store: plugin "github" received invalid URL "${String(url)}" of the GitHub instance`);
+        this.url = base.href.replace(/\/+$/, "");
+        const apiBase = apiBaseOf(base);
+        if (typeof options.repos !== "object" || options.repos === null || Array.isArray(options.repos))
+            throw new Error("task store: plugin \"github\" requires the \"repos\" option (mapping project ids onto \"<owner>/<repo>\")");
+        for (const [prjId, spec] of Object.entries(options.repos)) {
+            const m = typeof spec === "string" ? /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(spec) : null;
+            if (m === null || !TaskFormat.ID_RE.test(prjId))
+                throw new Error(`task store: plugin "github" received invalid repository mapping "${prjId}: ${String(spec)}"`);
+            this.repos.set(prjId, { owner: m[1], repo: m[2] });
+        }
+        this.poll = options.poll ?? 60;
+        if (typeof this.poll !== "number" || !Number.isFinite(this.poll) || (this.poll !== 0 && (this.poll < 1 || this.poll > 86400)))
+            throw new Error("task store: plugin \"github\" requires a \"poll\" interval of 0 (disabled) resp. 1 to 86400 seconds");
+        /*  route the diagnostics of Octokit into the log, as the standard
+            output may carry a protocol (like the one of an MCP server)  */
+        this.gh = new GitHub({
+            auth: token,
+            baseUrl: apiBase,
+            userAgent: "ase-task-store-github",
+            log: {
+                debug: () => { },
+                info: () => { },
+                warn: (message) => ctx.log("warning", message),
+                error: (message) => ctx.log("error", message)
+            }
+        });
+        /*  request the current REST API version, as the default one ("2022-11-28") is deprecated
+            (its breaking changes do not affect this plugin, as it uses "assignees" only), except
+            on a GitHub Enterprise Server, which answers an unsupported version with "410"  */
+        if (!apiBase.endsWith("/api/v3"))
+            this.gh.hook.before("request", (request) => {
+                request.headers["x-github-api-version"] = "2026-03-10";
+            });
+        /*  explain a denied access (but not an exceeded rate limit), as the
+            GitHub message names neither the token source nor the missing permission  */
+        const source = options.token !== undefined ? "the \"token\" option (resp. \"project.task.store.token\")" :
+            process.env.GITHUB_TOKEN !== undefined ? "$GITHUB_TOKEN" : "$GH_TOKEN";
+        this.gh.hook.error("request", (err, request) => {
+            const status = statusOf(err);
+            if ((status === 401 || status === 403) && !/rate limit/i.test(err.message)) {
+                const repo = typeof request.owner === "string" && typeof request.repo === "string" ?
+                    ` to repository "${request.owner}/${request.repo}"` : "";
+                throw new Error(`GitHub denied access${repo} (HTTP ${String(status)}: ${err.message}) -- ` +
+                    `the token of ${source} needs access to the repository with the permission ` +
+                    "\"Issues: Read and write\" (fine-grained token) resp. the scope \"repo\" or \"public_repo\" (classic token)", { cause: err });
+            }
+            throw err;
+        });
+    }
+    /*  the storage lifecycle: polling for changes while opened and observed
+        (without keeping the process alive)  */
+    async open() {
+        this.opened = now();
+        if (this.poll > 0 && this.listener !== null) {
+            this.timer = setInterval(() => {
+                this.pollAll().catch(() => { });
+            }, this.poll * 1000);
+            this.timer.unref();
+        }
+        this.ctx.log("debug", `opened ${this.repos.size} repositories on ${this.url} (polling every ${this.poll}s)`);
+    }
+    async close() {
+        if (this.timer !== null)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    /*  observe the changes of the issues made outside of this plugin instance  */
+    watch(listener) {
+        this.listener = listener;
+    }
+    /*  ==== project registry ====  */
+    /*  the repository of a project  */
+    repo(prjId) {
+        const loc = this.repos.get(prjId);
+        if (loc === undefined)
+            throw new Error(`project "${prjId}" is not mapped onto a GitHub repository (see option "repos")`);
+        return loc;
+    }
+    /*  the registry entry of a project, read from the description of its "ase:project" label  */
+    async registered(prjId) {
+        const cached = this.registry.get(prjId);
+        if (cached !== undefined)
+            return cached.value;
+        const loc = this.repos.get(prjId);
+        let value = null;
+        if (loc !== undefined) {
+            const label = await found(this.gh.rest.issues.getLabel({ ...loc, name: LABEL_PROJECT }));
+            if (label !== null)
+                value = TaskIssues.registryEntry(label.data.description);
+        }
+        this.registry.set(prjId, { value });
+        return value;
+    }
+    /*  the repository, lifecycle model, and task id scheme of a registered project  */
+    async context(prjId) {
+        const loc = this.repo(prjId);
+        const entry = await this.registered(prjId);
+        if (entry === null)
+            throw new Error(`project "${prjId}" not registered`);
+        return { loc, ...TaskIssues.registryContext(prjId, entry, "GitHub") };
+    }
+    /*  the highest issue or pull request number of a repository (conditionally requested)  */
+    async latestNumber(loc, fresh = false) {
+        const key = `${loc.owner}/${loc.repo}`;
+        const cached = this.latest.get(key);
+        /*  reuse a number determined within the last 2 seconds (unless a fresh one
+            is required), as every single task store operation asks for it  */
+        if (!fresh && cached !== undefined && Date.now() - cached.at < 2 * 1000)
+            return cached.number;
+        try {
+            const r = await this.gh.request("GET /repos/{owner}/{repo}/issues", {
+                ...loc, state: "all", sort: "created", direction: "desc", per_page: 1,
+                headers: cached !== undefined ? { "if-none-match": cached.etag } : {}
+            });
+            const number = r.data[0]?.number ?? 0;
+            if (r.headers.etag !== undefined)
+                this.latest.set(key, { etag: r.headers.etag, number, at: Date.now() });
+            return number;
+        }
+        catch (err) {
+            if (cached !== undefined && statusOf(err) === 304) {
+                cached.at = Date.now();
+                return cached.number;
+            }
+            throw err;
+        }
+    }
+    async projectList() {
+        const out = [];
+        for (const prjId of this.repos.keys()) {
+            const entry = await this.projectGet(prjId);
+            if (entry !== null)
+                out.push(entry);
+        }
+        return out;
+    }
+    /*  get a project, with the highest issue number as the sequence number high-water
+        mark, so the next allocated task id is the one of the next created issue  */
+    async projectGet(prjId) {
+        const entry = await this.registered(prjId);
+        if (entry === null)
+            return null;
+        return { id: prjId, ...entry, seqmark: await this.latestNumber(this.repo(prjId)) };
+    }
+    async projectSet(prjId, lifecycle, idscheme) {
+        const loc = this.repo(prjId);
+        TaskIssues.requireSeqScheme(idscheme, "GitHub");
+        /*  spare the requests of an unchanged (cached) registration, as the
+            in-process clients re-register the project on every opening  */
+        const entry = await this.registered(prjId);
+        if (entry !== null && entry.lifecycle === lifecycle && entry.idscheme === idscheme)
+            return "updated";
+        const description = TaskIssues.registryDescription({ lifecycle, idscheme });
+        if (entry === null)
+            await this.gh.rest.issues.createLabel({ ...loc, name: LABEL_PROJECT, color: "5319e7", description });
+        else
+            await this.gh.rest.issues.updateLabel({ ...loc, name: LABEL_PROJECT, description });
+        this.registry.set(prjId, { value: { lifecycle, idscheme } });
+        return entry === null ? "created" : "updated";
+    }
+    async projectDelete(prjId) {
+        const loc = this.repos.get(prjId);
+        if (loc === undefined)
+            return false;
+        const result = await found(this.gh.rest.issues.deleteLabel({ ...loc, name: LABEL_PROJECT }));
+        this.registry.delete(prjId);
+        return result !== null;
+    }
+    /*  ==== issue mapping ====  */
+    /*  fetch the live issue of an issue number (null if none)  */
+    async fetch(loc, n) {
+        if (n === 0)
+            return null;
+        const issue = await found(this.gh.rest.issues.get({ ...loc, issue_number: n }).then((r) => r.data));
+        return issue !== null && issue.number === n && inRepo(loc, issue) && live(issue) ? issue : null;
+    }
+    /*  the blocking issues of an issue within its repository  */
+    async blockers(loc, issue) {
+        if ((issue.issue_dependencies_summary?.total_blocked_by ?? 0) === 0)
+            return [];
+        const blockers = await this.gh.paginate(this.gh.rest.issues.listDependenciesBlockedBy, { ...loc, issue_number: issue.number, per_page: 100 });
+        return blockers.filter((blocker) => inRepo(loc, blocker));
+    }
+    /*  the comments of an issue  */
+    async comments(loc, issue) {
+        if (issue.comments === 0)
+            return [];
+        return await this.gh.paginate(this.gh.rest.issues.listComments, { ...loc, issue_number: issue.number, per_page: 100 });
+    }
+    /*  derive the header of an issue: the natively mapped keys (with "Group" and
+        "After" also from their fallback labels), "Status" from the
+        issue state (closed for the finished states, "not_planned" for "CANCELLED")
+        refined by its "ase:Status:<state>" label, and all other keys from their
+        "ase:<key>:<value>" labels  */
+    header(loc, lifecycle, scheme, issue, after) {
+        const header = {
+            Type: TaskFormat.TASK_TYPE,
+            Id: idOf(scheme, issue.number),
+            Created: stamp(issue.created_at),
+            Modified: stamp(issue.updated_at)
+        };
+        const parent = parentOf(loc, issue);
+        if (parent !== null)
+            header.Group = idOf(scheme, parent);
+        if (issue.milestone !== null)
+            header.Phase = issue.milestone.title;
+        const ids = after.map((blocker) => idOf(scheme, blocker.number));
+        for (const name of labelNames(issue)) {
+            const m = LABEL_RELATION_RE.exec(name);
+            if (m !== null && m[1] === "Group" && header.Group === undefined)
+                header.Group = m[2];
+            else if (m !== null && m[1] === "After")
+                ids.push(...m[2].split(/\s+/).filter((id) => id !== "" && !ids.includes(id)));
+        }
+        if (ids.length > 0)
+            header.After = ids;
+        const status = TaskIssues.labelHeader(header, labelNames(issue), nativeKeys);
+        const assignee = issue.assignees?.[0]?.login;
+        if (assignee !== undefined)
+            header.Assignee = assignee;
+        const derived = TaskIssues.issueStatus(lifecycle, issue.state === "closed", issue.state_reason === "not_planned", status);
+        if (derived !== undefined)
+            header.Status = derived;
+        return header;
+    }
+    /*  derive the attachment of a comment (see the common issue tracker parts)  */
+    attachment(comment) {
+        return TaskIssues.commentAttachment(comment.body, comment.user?.login ?? "ghost", comment.created_at, comment.updated_at);
+    }
+    /*  the listing entry of an issue  */
+    async entry(loc, lifecycle, scheme, issue) {
+        const header = this.header(loc, lifecycle, scheme, issue, await this.blockers(loc, issue));
+        return { id: idOf(scheme, issue.number), title: issue.title, header, mtime: new Date(issue.updated_at) };
+    }
+    /*  ==== issue updating ====  */
+    /*  ensure the existence of labels (with the known labels of a repository cached)  */
+    async ensureLabels(loc, names) {
+        const key = `${loc.owner}/${loc.repo}`;
+        let known = this.labels.get(key);
+        if (known === undefined) {
+            const labels = await this.gh.paginate(this.gh.rest.issues.listLabelsForRepo, { ...loc, per_page: 100 });
+            known = new Set(labels.map((label) => label.name.toLowerCase()));
+            this.labels.set(key, known);
+        }
+        for (const name of names) {
+            if (known.has(name.toLowerCase()))
+                continue;
+            await this.gh.rest.issues.createLabel({ ...loc, name, color: name.startsWith("ase:") ? "c5def5" : "ededed" })
+                .catch((err) => {
+                /*  tolerate a label created concurrently  */
+                if (statusOf(err) !== 422)
+                    throw err;
+            });
+            known.add(name.toLowerCase());
+        }
+    }
+    /*  delete the "ase:<key>:<value>" labels no longer used by any issue  */
+    async collectLabels(loc, names) {
+        for (const name of names) {
+            if (!LABEL_KEY_RE.test(name) || name.includes(","))
+                continue;
+            const r = await this.gh.rest.issues.listForRepo({ ...loc, labels: name, state: "all", per_page: 1 });
+            if (r.data.length === 0) {
+                await found(this.gh.rest.issues.deleteLabel({ ...loc, name }));
+                this.labels.get(`${loc.owner}/${loc.repo}`)?.delete(name.toLowerCase());
+            }
+        }
+    }
+    /*  the number of a milestone by its title (created on demand)  */
+    async milestone(loc, title) {
+        const key = `${loc.owner}/${loc.repo}`;
+        let map = this.milestones.get(key);
+        if (map === undefined) {
+            const milestones = await this.gh.paginate(this.gh.rest.issues.listMilestones, { ...loc, state: "all", per_page: 100 });
+            map = new Map(milestones.map((milestone) => [milestone.title, milestone.number]));
+            this.milestones.set(key, map);
+        }
+        let number = map.get(title);
+        if (number === undefined) {
+            number = (await this.gh.rest.issues.createMilestone({ ...loc, title })).data.number;
+            map.set(title, number);
+        }
+        return number;
+    }
+    /*  the live issue a header key references by its task id, else an error  */
+    async target(loc, scheme, key, id) {
+        const issue = await this.fetch(loc, numberOf(scheme, id));
+        if (issue === null)
+            throw new Error(`header key "${key}" references no existing task "${id}"`);
+        return issue;
+    }
+    /*  determine the labels and assignees of a header: the tags, the "ase:<key>:<value>"
+        labels of the keys without native counterpart, and the assignee if it can be
+        assigned natively (keeping further native assignees), else its label  */
+    async assign(loc, header, issue) {
+        const labels = TaskIssues.headerLabels(header, nativeKeys);
+        let assignees = [];
+        const assignee = header.Assignee;
+        if (typeof assignee === "string" && assignee !== "") {
+            const logins = issue?.assignees?.map((user) => user.login) ?? [];
+            if (logins.includes(assignee))
+                assignees = logins;
+            else if (await found(this.gh.rest.issues.checkUserCanBeAssigned({ ...loc, assignee })) !== null)
+                assignees = [assignee];
+            else
+                labels.push(`ase:Assignee:${assignee}`);
+        }
+        await this.ensureLabels(loc, labels);
+        return { labels, assignees };
+    }
+    /*  run a relation request natively; returns false if the GitHub instance lacks the
+        relation (answering "404", remembered per repository, e.g. on older GitHub
+        Enterprise Server versions), so the relation has to fall back onto its label  */
+    async native(loc, relation, request) {
+        const key = `${loc.owner}/${loc.repo}`;
+        let unsupported = this.unsupported.get(key);
+        if (unsupported?.has(relation))
+            return false;
+        try {
+            await request();
+            return true;
+        }
+        catch (err) {
+            if (statusOf(err) !== 404)
+                throw err;
+            if (unsupported === undefined) {
+                unsupported = new Set();
+                this.unsupported.set(key, unsupported);
+            }
+            unsupported.add(relation);
+            return false;
+        }
+    }
+    /*  synchronize the parent issue (keeping a parent of a foreign repository if none is
+        wanted); returns whether it is carried natively  */
+    async syncParent(loc, issue, parent) {
+        const current = parentOf(loc, issue);
+        if (parent !== null && parent.number !== current)
+            return this.native(loc, "Group", () => this.gh.rest.issues.addSubIssue({ ...loc, issue_number: parent.number, sub_issue_id: issue.id, replace_parent: true }));
+        else if (parent === null && current !== null)
+            await this.gh.rest.issues.removeSubIssue({ ...loc, issue_number: current, sub_issue_id: issue.id });
+        return true;
+    }
+    /*  synchronize the blocking issues (within the repository); returns whether
+        all of them are carried natively  */
+    async syncBlockers(loc, issue, after) {
+        const current = await this.blockers(loc, issue);
+        const have = new Set(current.map((blocker) => blocker.number));
+        const want = new Set(after.map((blocker) => blocker.number));
+        let native = true;
+        for (const blocker of after)
+            if (!have.has(blocker.number))
+                native = await this.native(loc, "After", () => this.gh.rest.issues.addBlockedByDependency({ ...loc, issue_number: issue.number, issue_id: blocker.id })) && native;
+        for (const blocker of current)
+            if (!want.has(blocker.number))
+                await this.gh.rest.issues.removeDependencyBlockedBy({ ...loc, issue_number: issue.number, issue_id: blocker.id });
+        return native;
+    }
+    /*  synchronize the comments with the attachments, touching changed ones only
+        (see the common issue tracker parts)  */
+    async syncComments(loc, issue, attachments) {
+        const comments = await this.comments(loc, issue);
+        const ops = TaskIssues.attachmentSync(comments.map((comment) => this.attachment(comment)), attachments);
+        for (const op of ops) {
+            if (op.op === "delete")
+                await this.gh.rest.issues.deleteComment({ ...loc, comment_id: comments[op.index].id });
+            else if (op.op === "create")
+                await this.gh.rest.issues.createComment({ ...loc, issue_number: issue.number, body: TaskIssues.attachmentComment(op.attachment) });
+            else
+                await this.gh.rest.issues.updateComment({ ...loc, comment_id: comments[op.index].id, body: TaskIssues.attachmentComment(op.attachment) });
+        }
+    }
+    /*  remember an issue written by this plugin instance: its update time, so the change
+        detection does not report it as an external change, and the issue itself, so the
+        listings (which lag behind the writes on GitHub) show it immediately  */
+    written(prjId, issue) {
+        this.pollState(prjId).seen.set(issue.number, issue.updated_at);
+        this.loads.delete(`${prjId}#${issue.number}`);
+        let recent = this.recent.get(prjId);
+        if (recent === undefined) {
+            recent = new Map();
+            this.recent.set(prjId, recent);
+        }
+        recent.set(issue.number, { issue, at: Date.now() });
+    }
+    /*  overlay the recently written issues (of the last 60 seconds) onto a listing,
+        where the listed issue is not yet present or older  */
+    overlay(prjId, issues) {
+        const recent = this.recent.get(prjId);
+        if (recent === undefined)
+            return issues;
+        const byNumber = new Map(issues.map((issue) => [issue.number, issue]));
+        for (const [n, { issue, at }] of recent) {
+            const listed = byNumber.get(n);
+            if (Date.now() - at > 60 * 1000)
+                recent.delete(n);
+            else if (listed === undefined || listed.updated_at < issue.updated_at)
+                byNumber.set(n, issue);
+        }
+        return [...byNumber.values()];
+    }
+    /*  load a live issue together with its blocking issues and comments (the issue and
+        its comments in parallel), reusing a load of the last 2 seconds (dropped on any
+        own write or detected change of the issue), as e.g. the boards load the plan
+        and its attachments in separate operations  */
+    load(prjId, loc, n) {
+        const key = `${prjId}#${n}`;
+        const cached = this.loads.get(key);
+        if (cached !== undefined)
+            return cached;
+        const load = (async () => {
+            const [issue, comments] = await Promise.all([
+                this.fetch(loc, n),
+                n === 0 ? [] : found(this.gh.paginate(this.gh.rest.issues.listComments, { ...loc, issue_number: n, per_page: 100 }))
+            ]);
+            if (issue === null)
+                return null;
+            return { issue, after: await this.blockers(loc, issue), comments: comments ?? [] };
+        })();
+        this.loads.set(key, load);
+        load.catch(() => {
+            this.loads.delete(key);
+        });
+        return load;
+    }
+    /*  ==== task plans ====  */
+    async taskList(prjId) {
+        const { loc, lifecycle, scheme } = await this.context(prjId);
+        const issues = this.overlay(prjId, await this.gh.paginate(this.gh.rest.issues.listForRepo, { ...loc, state: "all", per_page: 100 }));
+        return Promise.all(issues.filter((issue) => live(issue))
+            .map((issue) => this.entry(loc, lifecycle, scheme, issue)));
+    }
+    async taskLoad(prjId, taskId) {
+        const { loc, lifecycle, scheme } = await this.context(prjId);
+        const loaded = await this.load(prjId, loc, numberOf(scheme, taskId));
+        if (loaded === null)
+            return null;
+        const { issue, after, comments } = loaded;
+        return {
+            header: this.header(loc, lifecycle, scheme, issue, after),
+            body: TaskIssues.issueBody(issue.title, issue.body),
+            attachment: comments.map((comment) => this.attachment(comment))
+        };
+    }
+    /*  create or update the issue of a task plan: all references are resolved
+        upfront, a new task can only be the next issue number, and the issue itself
+        is updated last, so its update time covers the relation and comment changes  */
+    async taskSave(prjId, taskId, plan) {
+        const { loc, lifecycle, scheme } = await this.context(prjId);
+        const number = numberOf(scheme, taskId);
+        if (number === 0)
+            throw new Error(`task id "${taskId}" is no issue number rendered through the "seq" task id scheme of the project`);
+        let issue = await this.fetch(loc, number);
+        const result = issue !== null ? "updated" : "created";
+        const group = plan.header.Group;
+        const parent = typeof group === "string" && group !== "" ? await this.target(loc, scheme, "Group", group) : null;
+        const after = await Promise.all((Array.isArray(plan.header.After) ? plan.header.After : [])
+            .map((id) => this.target(loc, scheme, "After", id)));
+        const phase = plan.header.Phase;
+        const milestone = typeof phase === "string" && phase !== "" ? await this.milestone(loc, phase) : null;
+        const { labels, assignees } = await this.assign(loc, plan.header, issue);
+        const status = TaskFormat.taskStatus(plan.header, lifecycle);
+        const closed = lifecycle.finished.includes(status);
+        const { title, body } = TaskIssues.planIssue(taskId, plan);
+        if (issue === null) {
+            /*  reject a task id deviating from the next issue number, and
+                discard an issue which lost the race for this number  */
+            const next = await this.latestNumber(loc, true) + 1;
+            if (number !== next)
+                throw new Error(`task "${taskId}" cannot be created, as the next issue will be "${idOf(scheme, next)}"`);
+            issue = (await this.gh.rest.issues.create({ ...loc, title, body, labels, assignees, milestone })).data;
+            if (issue.number !== number) {
+                await this.ensureLabels(loc, [LABEL_DELETED]);
+                await this.gh.rest.issues.update({
+                    ...loc, issue_number: issue.number, state: "closed", state_reason: "not_planned",
+                    labels: [...labels, LABEL_DELETED]
+                });
+                throw new Error(`task "${taskId}" cannot be created, as issue "${idOf(scheme, number)}" was created concurrently`);
+            }
+        }
+        /*  fall back onto the labels of the relations not carried natively  */
+        const fallback = [];
+        if (!await this.syncParent(loc, issue, parent) && parent !== null)
+            fallback.push(`ase:Group:${idOf(scheme, parent.number)}`);
+        if (!await this.syncBlockers(loc, issue, after))
+            fallback.push(`ase:After:${after.map((blocker) => idOf(scheme, blocker.number)).join(" ")}`);
+        for (const name of fallback)
+            if (name.length > 50)
+                throw new Error(`label "${name}" cannot be carried by GitHub, as it exceeds 50 characters`);
+        await this.ensureLabels(loc, fallback);
+        labels.push(...fallback);
+        await this.syncComments(loc, issue, plan.attachment);
+        const updated = (await this.gh.rest.issues.update({
+            ...loc, issue_number: number, title, body, labels, assignees, milestone,
+            state: closed ? "closed" : "open",
+            ...(closed ? { state_reason: status === "CANCELLED" ? "not_planned" : "completed" } : {})
+        })).data;
+        this.written(prjId, updated);
+        await this.collectLabels(loc, labelNames(issue).filter((name) => !labels.includes(name)));
+        return result;
+    }
+    /*  soft delete the issue of a task plan: closed as "not planned" and marked as deleted  */
+    async taskDelete(prjId, taskId) {
+        const { loc, scheme } = await this.context(prjId);
+        const issue = await this.fetch(loc, numberOf(scheme, taskId));
+        if (issue === null)
+            return false;
+        await this.ensureLabels(loc, [LABEL_DELETED]);
+        const updated = (await this.gh.rest.issues.update({
+            ...loc, issue_number: issue.number, state: "closed", state_reason: "not_planned",
+            labels: [...labelNames(issue), LABEL_DELETED]
+        })).data;
+        this.written(prjId, updated);
+        return true;
+    }
+    /*  renaming is impossible, as the task id is the issue number  */
+    async taskRename(prjId, oldId, newId) {
+        const { loc, scheme } = await this.context(prjId);
+        if (await this.fetch(loc, numberOf(scheme, oldId)) === null)
+            return false;
+        throw new Error(`task "${oldId}" cannot be renamed to "${newId}", as task ids are GitHub issue numbers`);
+    }
+    /*  ==== change detection ====  */
+    /*  the change detection state of a project (starting at the opening time)  */
+    pollState(prjId) {
+        let state = this.polls.get(prjId);
+        if (state === undefined) {
+            state = { since: this.opened, seen: new Map() };
+            this.polls.set(prjId, state);
+        }
+        return state;
+    }
+    /*  poll all registered projects, never overlapping itself  */
+    async pollAll() {
+        if (this.polling)
+            return;
+        this.polling = true;
+        try {
+            for (const prjId of this.repos.keys())
+                await this.pollProject(prjId).catch((err) => {
+                    this.ctx.log("warning", `polling project "${prjId}" failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    /*  poll the issues of a project updated since the last poll, conditionally
+        via the entity tag of the last poll (a "304" answer is free of rate limit),
+        and report the issues not seen at their update time yet: as added if created
+        after the opening, as deleted if soft deleted, else as updated (issues deleted
+        on GitHub are not reported, as GitHub reports no deletions)  */
+    async pollProject(prjId) {
+        const listener = this.listener;
+        if (listener === null || await this.registered(prjId) === null)
+            return;
+        const { loc, lifecycle, scheme } = await this.context(prjId);
+        const state = this.pollState(prjId);
+        const params = { ...loc, state: "all", sort: "updated", direction: "asc", since: state.since, per_page: 100 };
+        let issues;
+        try {
+            const r = await this.gh.request("GET /repos/{owner}/{repo}/issues", {
+                ...params, headers: state.etag !== undefined ? { "if-none-match": state.etag } : {}
+            });
+            state.etag = r.headers.etag;
+            issues = r.data;
+            if (issues.length === params.per_page)
+                issues.push(...await this.gh.paginate("GET /repos/{owner}/{repo}/issues", { ...params, page: 2 }));
+        }
+        catch (err) {
+            if (statusOf(err) === 304)
+                return;
+            throw err;
+        }
+        const change = { added: [], updated: [], deleted: [] };
+        for (const issue of issues) {
+            if (issue.pull_request !== undefined && issue.pull_request !== null)
+                continue;
+            if (issue.updated_at > state.since)
+                state.since = issue.updated_at;
+            if (state.seen.get(issue.number) === issue.updated_at)
+                continue;
+            const known = state.seen.has(issue.number);
+            state.seen.set(issue.number, issue.updated_at);
+            this.loads.delete(`${prjId}#${issue.number}`);
+            if (!live(issue))
+                change.deleted.push(idOf(scheme, issue.number));
+            else if (!known && issue.created_at >= this.opened)
+                change.added.push(await this.entry(loc, lifecycle, scheme, issue));
+            else
+                change.updated.push(await this.entry(loc, lifecycle, scheme, issue));
+        }
+        if (this.timer !== null && (change.added.length > 0 || change.updated.length > 0 || change.deleted.length > 0))
+            listener(prjId, change);
+    }
+}
+/*  the plugin factory  */
+const factory = (ctx) => new GitHubTaskStoragePlugin(ctx);
+export default factory;