@rse/ase 1.0.7 → 2.0.1

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

@@ -0,0 +1,666 @@
+/*
+**  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 { giteaApi } from "gitea-js";
+import { LRUCache } from "lru-cache";
+import * as TaskFormat from "./ase-task-format.js";
+import * as TaskIssues from "./ase-task-store-issues.js";
+/*  the reserved label, the task id mapping, and the timestamp of the common issue tracker parts  */
+const { LABEL_PROJECT, idOf, numberOf, stamp } = TaskIssues;
+/*  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", "Phase", "After", "Tags", "Assignee"];
+/*  the page size of the listings (the default maximum of Gitea)  */
+const PAGE = 50;
+/*  the current time and a normalized timestamp as ISO timestamp (UTC, millisecond-precise),
+    as Gitea delivers its timestamps in the time zone of the server  */
+const now = () => new Date().toISOString();
+const iso = (timestamp) => new Date(timestamp).toISOString();
+/*  a failed request of the Gitea REST API with its HTTP status  */
+class GiteaError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/*  the HTTP status of a request failure, and a "not found" (404) request failure mapped onto null  */
+const statusOf = (err) => err instanceof GiteaError ? err.status : undefined;
+const found = (p) => p.catch((err) => {
+    if (statusOf(err) === 404)
+        return null;
+    throw err;
+});
+/*  the label names of an issue, whether an issue is a live task (no pull request),
+    and whether an issue belongs to the given repository  */
+const labelNames = (issue) => (issue.labels ?? []).map((label) => label.name);
+const live = (issue) => issue.pull_request === undefined || issue.pull_request === null;
+const inRepo = (loc, issue) => issue.repository === undefined || issue.repository === null
+    || (issue.repository.owner.toLowerCase() === loc.owner.toLowerCase()
+        && issue.repository.name.toLowerCase() === loc.repo.toLowerCase());
+/*  the Gitea storage plugin: a project is a repository (registered by its
+    "ase:project" label, which also persists the sequence number high-water mark, as
+    Gitea never reuses the number of a deleted issue) 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,
+    "After" onto the dependencies (the blocking issues), "Created"/"Modified" onto the
+    issue timestamps, any other key (including "Group", as Gitea has no parent issues)
+    onto "ase:<key>:<value>" labels, and the attachments onto the issue comments  */
+class GiteaTaskStoragePlugin {
+    ctx;
+    name = "gitea";
+    url;
+    source;
+    gt;
+    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();
+    assignable = new LRUCache({ max: 64, ttl: 60 * 1000 });
+    depends = new LRUCache({ max: 1024, ttl: 60 * 1000 });
+    loads = new LRUCache({ max: 256, ttl: 2 * 1000 });
+    constructor(ctx) {
+        this.ctx = ctx;
+        const options = ctx.options;
+        const token = options.token ?? process.env.GITEA_TOKEN ?? "";
+        if (typeof token !== "string" || token === "")
+            throw new Error("task store: plugin \"gitea\" requires the \"token\" option (or $GITEA_TOKEN)");
+        const url = options.url ?? "https://gitea.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 "gitea" received invalid URL "${String(url)}" of the Gitea instance`);
+        this.url = base.href.replace(/\/+$/, "");
+        if (typeof options.repos !== "object" || options.repos === null || Array.isArray(options.repos))
+            throw new Error("task store: plugin \"gitea\" 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 "gitea" 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 \"gitea\" requires a \"poll\" interval of 0 (disabled) resp. 1 to 86400 seconds");
+        /*  create the Gitea REST API client, with every request bounded in time  */
+        this.source = options.token !== undefined ? "the \"token\" option (resp. \"project.task.store.token\")" : "$GITEA_TOKEN";
+        this.gt = giteaApi(this.url, {
+            token,
+            customFetch: (input, init) => fetch(input, { ...init, signal: init?.signal ?? AbortSignal.timeout(60 * 1000) })
+        });
+    }
+    /*  convert a failed request (thrown as its response by the Gitea REST API client)
+        into an error, explaining a denied access, as the Gitea message names neither
+        the token source nor the missing permission  */
+    explain(err, loc) {
+        if (!(err instanceof Response))
+            throw err;
+        const info = err.error;
+        const message = typeof info?.message === "string" && info.message !== "" ? info.message : err.statusText;
+        if (err.status === 401 || err.status === 403) {
+            const repo = loc !== undefined ? ` to repository "${loc.owner}/${loc.repo}"` : "";
+            throw new Error(`Gitea denied access${repo} (HTTP ${String(err.status)}: ${message}) -- ` +
+                `the token of ${this.source} needs the scopes "write:issue" and "read:repository" ` +
+                "and write access to the repository (resp. its administration, for deleting a task)");
+        }
+        throw new GiteaError(`Gitea request failed (HTTP ${String(err.status)}: ${message})`, err.status);
+    }
+    /*  perform a request, delivering its data  */
+    async call(loc, request) {
+        try {
+            return (await request).data;
+        }
+        catch (err) {
+            this.explain(err, loc);
+        }
+    }
+    /*  perform a paginated listing request, delivering the data of all pages  */
+    async all(loc, request) {
+        const out = [];
+        for (let page = 1;; page++) {
+            let r;
+            try {
+                r = await request({ page, limit: PAGE });
+            }
+            catch (err) {
+                this.explain(err, loc);
+            }
+            out.push(...r.data);
+            const total = Number.parseInt(r.headers.get("x-total-count") ?? "", 10);
+            if (r.data.length === 0 || (Number.isFinite(total) ? out.length >= total : r.data.length < PAGE))
+                return out;
+        }
+    }
+    /*  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 Gitea repository (see option "repos")`);
+        return loc;
+    }
+    /*  the labels of a repository by their lower-cased name (freshly listed on request)  */
+    async labelMap(loc, fresh = false) {
+        const key = `${loc.owner}/${loc.repo}`;
+        let map = this.labels.get(key);
+        if (map === undefined || fresh) {
+            const labels = await this.all(loc, (query) => this.gt.repos.issueListLabels(loc.owner, loc.repo, query));
+            map = new Map(labels.map((label) => [label.name.toLowerCase(), label]));
+            this.labels.set(key, map);
+        }
+        return map;
+    }
+    /*  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 this.labelMap(loc, true)).get(LABEL_PROJECT);
+            if (label !== undefined)
+                value = TaskIssues.registryEntry(label.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, "Gitea") };
+    }
+    /*  write the registry entry of a project into the description of its "ase:project" label  */
+    async register(prjId, loc, entry, exists) {
+        const description = TaskIssues.registryDescription(entry);
+        const label = exists ? (await this.labelMap(loc, true)).get(LABEL_PROJECT) : undefined;
+        if (label === undefined)
+            await this.call(loc, this.gt.repos.issueCreateLabel(loc.owner, loc.repo, { name: LABEL_PROJECT, color: "#5319e7", description }));
+        else
+            await this.call(loc, this.gt.repos.issueEditLabel(loc.owner, loc.repo, label.id, { color: "#5319e7", description }));
+        this.labels.delete(`${loc.owner}/${loc.repo}`);
+        this.registry.set(prjId, { value: entry });
+    }
+    /*  the highest issue or pull request number of a repository, as the listing
+        delivers the most recently created issue first  */
+    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;
+        const issues = await this.call(loc, this.gt.repos.issueListIssues(loc.owner, loc.repo, { state: "all", page: 1, limit: 1 }));
+        const number = issues[0]?.number ?? 0;
+        this.latest.set(key, { number, at: Date.now() });
+        return number;
+    }
+    /*  the high-water mark of the sequence numbers of a registered project: the highest
+        issue number, or the persisted one if higher (as numbers of deleted issues)  */
+    async seqmark(loc, entry, fresh = false) {
+        return Math.max(await this.latestNumber(loc, fresh), entry?.seqmark ?? 0);
+    }
+    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 sequence number high-water mark as 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, lifecycle: entry.lifecycle, idscheme: entry.idscheme, seqmark: await this.seqmark(this.repo(prjId), entry) };
+    }
+    async projectSet(prjId, lifecycle, idscheme) {
+        const loc = this.repo(prjId);
+        TaskIssues.requireSeqScheme(idscheme, "Gitea");
+        /*  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";
+        await this.register(prjId, loc, { lifecycle, idscheme, ...(entry?.seqmark !== undefined ? { seqmark: entry.seqmark } : {}) }, entry !== null);
+        return entry === null ? "created" : "updated";
+    }
+    /*  persist the high-water mark of the sequence numbers for the number of a hard deleted
+        issue, if it exceeds the known one (deliberately not as the optional "projectMark"
+        method, as the server also marks allocated task ids, which have to stay the numbers
+        of the next created issues)  */
+    async retire(prjId, seqmark) {
+        const loc = this.repo(prjId);
+        const entry = await this.registered(prjId);
+        if (entry !== null && seqmark > (entry.seqmark ?? 0))
+            await this.register(prjId, loc, { ...entry, seqmark }, true);
+    }
+    async projectDelete(prjId) {
+        const loc = this.repos.get(prjId);
+        if (loc === undefined)
+            return false;
+        const label = (await this.labelMap(loc, true)).get(LABEL_PROJECT);
+        const result = label !== undefined ?
+            await found(this.call(loc, this.gt.repos.issueDeleteLabel(loc.owner, loc.repo, label.id)).then(() => true)) : null;
+        this.labels.delete(`${loc.owner}/${loc.repo}`);
+        this.registry.delete(prjId);
+        return label !== undefined && 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.call(loc, this.gt.repos.issueGetIssue(loc.owner, loc.repo, n)));
+        return issue !== null && issue.number === n && inRepo(loc, issue) && live(issue) ? issue : null;
+    }
+    /*  the blocking issues of an issue within its repository, from its dependencies (none if
+        disabled), reused for 60 seconds per update time, as a listing needs them for every issue  */
+    async blockers(loc, issue, fresh = false) {
+        const key = `${loc.owner}/${loc.repo}#${issue.number}@${issue.updated_at}`;
+        if (fresh)
+            this.depends.delete(key);
+        let depends = this.depends.get(key);
+        if (depends === undefined) {
+            depends = found(this.all(loc, (query) => this.gt.repos.issueListIssueDependencies(loc.owner, loc.repo, String(issue.number), query)))
+                .then((issues) => (issues ?? []));
+            this.depends.set(key, depends);
+            depends.catch(() => {
+                this.depends.delete(key);
+            });
+        }
+        return (await depends).filter((blocker) => inRepo(loc, blocker));
+    }
+    /*  the comments of an issue  */
+    async comments(loc, n) {
+        return await this.call(loc, this.gt.repos.issueGetComments(loc.owner, loc.repo, n));
+    }
+    /*  derive the header of an issue: the natively mapped keys, "Status" from the issue
+        state (closed for the finished states) refined by its "ase:Status:<state>" label
+        (where an open issue with a finished state could not be closed because of its
+        open blocking issues), and all other keys from their "ase:<key>:<value>" labels  */
+    header(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)
+        };
+        if (issue.milestone !== undefined && issue.milestone !== null)
+            header.Phase = issue.milestone.title;
+        if (after.length > 0)
+            header.After = after.map((blocker) => idOf(scheme, blocker.number));
+        const status = TaskIssues.labelHeader(header, labelNames(issue), nativeKeys);
+        const assignee = issue.assignees?.[0]?.login;
+        if (assignee !== undefined)
+            header.Assignee = assignee;
+        const closed = issue.state === "closed";
+        const derived = !closed && status !== undefined && lifecycle.finished.includes(status) ? status :
+            TaskIssues.issueStatus(lifecycle, closed, status === "CANCELLED", 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(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 ====  */
+    /*  the ids of labels, created on demand  */
+    async ensureLabels(loc, names) {
+        const ids = [];
+        for (const name of names) {
+            let label = (await this.labelMap(loc)).get(name.toLowerCase());
+            if (label === undefined) {
+                label = await this.call(loc, this.gt.repos.issueCreateLabel(loc.owner, loc.repo, { name, color: name.startsWith("ase:") ? "#c5def5" : "#ededed" })).catch(async (err) => {
+                    /*  tolerate a label created concurrently  */
+                    const label = statusOf(err) === 422 ? (await this.labelMap(loc, true)).get(name.toLowerCase()) : undefined;
+                    if (label === undefined)
+                        throw err;
+                    return label;
+                });
+                const map = await this.labelMap(loc);
+                map.set(name.toLowerCase(), label);
+            }
+            ids.push(label.id);
+        }
+        return ids;
+    }
+    /*  delete the "ase:<key>:<value>" labels no longer used by any issue  */
+    async collectLabels(loc, names) {
+        for (const name of names) {
+            if (!TaskIssues.LABEL_KEY_RE.test(name) || name.includes(","))
+                continue;
+            const label = (await this.labelMap(loc)).get(name.toLowerCase());
+            if (label === undefined)
+                continue;
+            const issues = await this.call(loc, this.gt.repos.issueListIssues(loc.owner, loc.repo, { state: "all", labels: name, page: 1, limit: 1 }));
+            if (issues.length === 0) {
+                await found(this.call(loc, this.gt.repos.issueDeleteLabel(loc.owner, loc.repo, label.id)));
+                this.labels.get(`${loc.owner}/${loc.repo}`)?.delete(name.toLowerCase());
+            }
+        }
+    }
+    /*  the id 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.all(loc, (query) => this.gt.repos.issueGetMilestonesList(loc.owner, loc.repo, { state: "all", ...query }));
+            map = new Map(milestones.map((milestone) => [milestone.title ?? "", milestone.id ?? 0]));
+            this.milestones.set(key, map);
+        }
+        let id = map.get(title);
+        if (id === undefined) {
+            id = (await this.call(loc, this.gt.repos.issueCreateMilestone(loc.owner, loc.repo, { title }))).id ?? 0;
+            map.set(title, id);
+        }
+        return id;
+    }
+    /*  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) ?? [];
+            const key = `${loc.owner}/${loc.repo}`;
+            let users = this.assignable.get(key);
+            if (users === undefined) {
+                users = this.call(loc, this.gt.repos.repoGetAssignees(loc.owner, loc.repo))
+                    .then((list) => new Set(list.map((user) => (user.login ?? "").toLowerCase())));
+                this.assignable.set(key, users);
+                users.catch(() => {
+                    this.assignable.delete(key);
+                });
+            }
+            if (logins.includes(assignee))
+                assignees = logins;
+            else if ((await users).has(assignee.toLowerCase()))
+                assignees = [assignee];
+            else
+                labels.push(`ase:Assignee:${assignee}`);
+        }
+        return { labels, assignees };
+    }
+    /*  synchronize the blocking issues (within the repository)  */
+    async syncBlockers(loc, issue, after) {
+        const current = await this.blockers(loc, issue, true);
+        const have = new Set(current.map((blocker) => blocker.number));
+        const want = new Set(after.map((blocker) => blocker.number));
+        const meta = (blocker) => ({ owner: loc.owner, repo: loc.repo, index: blocker.number });
+        for (const blocker of after) {
+            if (have.has(blocker.number))
+                continue;
+            await this.call(loc, this.gt.repos.issueCreateIssueDependencies(loc.owner, loc.repo, String(issue.number), meta(blocker)))
+                .catch((err) => {
+                if (statusOf(err) === 404)
+                    throw new Error(`Gitea rejected the dependency of issue #${issue.number} on issue #${blocker.number} ` +
+                        `-- enable the issue dependencies in the settings of repository "${loc.owner}/${loc.repo}"`, { cause: err });
+                throw err;
+            });
+        }
+        for (const blocker of current)
+            if (!want.has(blocker.number))
+                await found(this.call(loc, this.gt.repos.issueRemoveIssueDependencies(loc.owner, loc.repo, String(issue.number), meta(blocker))));
+    }
+    /*  synchronize the comments with the attachments, touching changed ones only
+        (see the common issue tracker parts)  */
+    async syncComments(loc, issue, attachments) {
+        const comments = issue.comments > 0 ? await this.comments(loc, issue.number) : [];
+        const ops = TaskIssues.attachmentSync(comments.map((comment) => this.attachment(comment)), attachments);
+        for (const op of ops) {
+            if (op.op === "delete")
+                await this.call(loc, this.gt.repos.issueDeleteComment(loc.owner, loc.repo, comments[op.index].id));
+            else if (op.op === "create")
+                await this.call(loc, this.gt.repos.issueCreateComment(loc.owner, loc.repo, issue.number, { body: TaskIssues.attachmentComment(op.attachment) }));
+            else
+                await this.call(loc, this.gt.repos.issueEditComment(loc.owner, loc.repo, 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  */
+    written(prjId, issue) {
+        this.pollState(prjId).seen.set(issue.number, issue.updated_at);
+        this.loads.delete(`${prjId}#${issue.number}`);
+    }
+    /*  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.comments(loc, n))
+            ]);
+            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 = await this.all(loc, (query) => this.gt.repos.issueListIssues(loc.owner, loc.repo, { state: "all", type: "issues", ...query }));
+        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(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, comment, and label
+        changes; an issue which cannot be closed because of its open blocking issues
+        stays open, with its finished state carried by the "ase:Status:<state>" label  */
+    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;
+        if (typeof group === "string" && group !== "")
+            await this.target(loc, scheme, "Group", group);
+        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) : 0;
+        const { labels, assignees } = await this.assign(loc, plan.header, issue);
+        const labelIds = await this.ensureLabels(loc, labels);
+        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 delete an issue
+                which lost the race for this number (retiring its number)  */
+            const next = await this.seqmark(loc, await this.registered(prjId), 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.call(loc, this.gt.repos.issueCreateIssue(loc.owner, loc.repo, {
+                title, body, labels: labelIds, assignees, ...(milestone !== 0 ? { milestone } : {})
+            }));
+            if (issue.number !== number) {
+                await this.call(loc, this.gt.repos.issueDelete(loc.owner, loc.repo, issue.number));
+                await this.retire(prjId, issue.number);
+                throw new Error(`task "${taskId}" cannot be created, as issue "${idOf(scheme, number)}" was created concurrently`);
+            }
+        }
+        await this.syncBlockers(loc, issue, after);
+        await this.syncComments(loc, issue, plan.attachment);
+        const current = (issue.labels ?? []).map((label) => label.id).sort((a, b) => a - b);
+        if (current.join(",") !== [...labelIds].sort((a, b) => a - b).join(","))
+            await this.call(loc, this.gt.repos.issueReplaceLabels(loc.owner, loc.repo, number, { labels: labelIds }));
+        const edit = { title, body, assignees, milestone };
+        let updated;
+        if (closed === (issue.state === "closed"))
+            updated = await this.call(loc, this.gt.repos.issueEditIssue(loc.owner, loc.repo, number, edit));
+        else {
+            updated = await this.call(loc, this.gt.repos.issueEditIssue(loc.owner, loc.repo, number, { ...edit, state: closed ? "closed" : "open" })).catch(async (err) => {
+                /*  keep an issue with open blocking issues open, as Gitea refuses to close it
+                    (after it applied all other changes)  */
+                if (!closed || statusOf(err) !== 412)
+                    throw err;
+                return await this.call(loc, this.gt.repos.issueGetIssue(loc.owner, loc.repo, number));
+            });
+        }
+        this.written(prjId, updated);
+        await this.collectLabels(loc, labelNames(issue).filter((name) => !labels.includes(name)));
+        return result;
+    }
+    /*  hard delete the issue of a task plan (requiring the administration of the repository)  */
+    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.call(loc, this.gt.repos.issueDelete(loc.owner, loc.repo, issue.number));
+        await this.retire(prjId, issue.number);
+        this.pollState(prjId).seen.delete(issue.number);
+        this.loads.delete(`${prjId}#${issue.number}`);
+        await this.collectLabels(loc, labelNames(issue));
+        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 Gitea 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 (Gitea supports no
+        conditional requests), and report the issues not seen at their update time yet:
+        as added if created after the opening, else as updated (issues deleted on Gitea
+        are not reported, as Gitea 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 issues = await this.all(loc, (query) => this.gt.repos.issueListIssues(loc.owner, loc.repo, { state: "all", type: "issues", since: state.since, ...query }));
+        const change = { added: [], updated: [] };
+        for (const issue of issues.reverse()) {
+            if (!live(issue))
+                continue;
+            if (iso(issue.updated_at) > state.since)
+                state.since = iso(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 (!known && iso(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))
+            listener(prjId, change);
+    }
+}
+/*  the plugin factory  */
+const factory = (ctx) => new GiteaTaskStoragePlugin(ctx);
+export default factory;