@hachej/boring-feedback 0.0.0-stage → 0.2.4

package/dist/store/store.d.ts

@@ -0,0 +1,121 @@
+import type { ProviderGuarantees, PublicationLookup, ResourceAccess, ResourcePublisher, ResourceReader, ResourceView } from '@hachej/boring-files';
+import type { FeedbackDraft, FeedbackListItem, FeedbackReport, FeedbackRoot, Observed } from '../format/index.js';
+export type FeedbackProtection = 'protected' | 'unprotected';
+export type FeedbackPermission = 'annotate' | 'read';
+export type FeedbackAction = 'create' | 'resolve';
+/** What the host authorizes. `key` is the subject key (`subjectKeyOf`): list, read and resolve decide on it alone, so a
+ * decision must be a function of `key`. `observed` is supplied on create only. */
+export interface FeedbackSubject {
+    readonly key: string;
+    readonly observed?: Observed;
+}
+/** `id` is the caller's stable operation id (the browser's per-draft id, or the agent's admitted `[namespace, taskId]`).
+ * `key` is the binding admitted with it, computed by `store.operationKey` when the operation was first admitted. */
+export interface FeedbackOperation {
+    readonly id: string;
+    readonly key: string;
+}
+export interface FeedbackStoreOptions<Context = void> {
+    readonly providerId: string;
+    readonly view: ResourceView;
+    readonly reader: ResourceReader;
+    readonly publisher: ResourcePublisher;
+    readonly lookup: PublicationLookup;
+    /** The provider's declared capabilities (a `ResourceCapabilities` satisfies this). */
+    readonly capabilities: {
+        readonly guarantees: ProviderGuarantees;
+    };
+    /** The names of the files in one folder of the view (`''` is the view's root), or a refusal. The host lists its workspace's file
+     * system here (Pi's `listDir`); a missing folder is an empty list. */
+    readonly listFolder: (folder: string, access: ResourceAccess) => Promise<readonly string[] | FeedbackRefusal>;
+    /** The folder of the reports: empty or a relative path ending with `/`. */
+    readonly root: string;
+    /** Stable identity of the storage partition and this binding. */
+    readonly operationNamespace: string;
+    /** The host's access resolution, kept for the routes and tools built on this store. The store itself never calls it:
+     * every method takes the access the caller resolved for this request or tool call. */
+    readonly resolveAccess: (context: Context) => ResourceAccess | Promise<ResourceAccess>;
+    readonly authorizeSubject: (access: ResourceAccess, subject: FeedbackSubject, permission: FeedbackPermission) => boolean | Promise<boolean>;
+    readonly displayName: (principalId: string) => string | Promise<string>;
+    /** `'protected'`: native working tools, shell and Git cannot write the root. `'unprotected'` must be chosen explicitly,
+     * and every surface states it. */
+    readonly protection: FeedbackProtection;
+    /** Time source for `created`, and resolutions. Defaults to the system clock. */
+    readonly now?: () => Date;
+}
+export interface FeedbackDenied {
+    readonly kind: 'denied';
+    readonly reason: string;
+}
+export interface FeedbackUnavailable {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+}
+export interface FeedbackMissing {
+    readonly kind: 'missing';
+}
+/** `current` is the report's current revision when the conflict is on the report, `null` when it has none or the
+ * conflict is not on a report revision. */
+export interface FeedbackConflict {
+    readonly kind: 'conflict';
+    readonly current: string | null;
+    readonly reason: string;
+}
+/** The effect is not known: reconcile `operationId` later. Never a success. */
+export interface FeedbackUnknown {
+    readonly kind: 'unknown';
+    readonly operationId: string;
+    readonly reason: string;
+}
+export type FeedbackRefusal = FeedbackDenied | FeedbackUnavailable;
+export interface FeedbackStored {
+    readonly report: FeedbackReport;
+    readonly revision: string;
+}
+export interface FeedbackApplied extends FeedbackStored {
+    readonly kind: 'applied';
+    readonly operationId: string;
+}
+export type FeedbackCreateResult = FeedbackApplied | FeedbackConflict | FeedbackRefusal | FeedbackUnknown;
+export type FeedbackResolveResult = FeedbackApplied | FeedbackConflict | FeedbackMissing | FeedbackRefusal | FeedbackUnknown;
+export type FeedbackReadResult = ({
+    readonly kind: 'available';
+} & FeedbackStored) | FeedbackMissing | FeedbackRefusal;
+export type { FeedbackListItem };
+export type FeedbackListResult = {
+    readonly kind: 'available';
+    readonly items: readonly FeedbackListItem[];
+    readonly cursor: string | null;
+    readonly protection: FeedbackProtection;
+} | FeedbackRefusal;
+export interface FeedbackListQuery {
+    readonly status?: 'open' | 'addressed';
+    readonly subject?: string;
+    readonly cursor?: string;
+}
+export interface FeedbackResolveInput {
+    readonly expectedRevision: string;
+    readonly note: string;
+}
+export interface FeedbackStore<Context = void> {
+    readonly root: FeedbackRoot;
+    readonly resolveAccess: (context: Context) => ResourceAccess | Promise<ResourceAccess>;
+    /** The binding to admit with an operation id: namespace, root, provider, view, access fields, action and arguments. */
+    readonly operationKey: (action: FeedbackAction, args: unknown, access: ResourceAccess) => string;
+    readonly create: (draft: FeedbackDraft, access: ResourceAccess, operation: FeedbackOperation) => Promise<FeedbackCreateResult>;
+    readonly read: (id: string, access: ResourceAccess) => Promise<FeedbackReadResult>;
+    readonly list: (query: FeedbackListQuery, access: ResourceAccess) => Promise<FeedbackListResult>;
+    readonly resolve: (id: string, input: FeedbackResolveInput, access: ResourceAccess, operation: FeedbackOperation) => Promise<FeedbackResolveResult>;
+    readonly guarantees: () => {
+        readonly protection: FeedbackProtection;
+    };
+}
+export declare const FEEDBACK_PAGE_SIZE = 50;
+/** The most report files `list` reads in one call; a folder holding more is refused, never silently truncated. */
+export declare const FEEDBACK_LIST_LIMIT = 5000;
+/** `fb_` and 16 base-58 characters from the platform's cryptographic source (rejection sampling, no modulo bias). */
+export declare function feedbackId(): string;
+/** Build a store over injected resource contracts. Refuses to start without conditional publication, operation lookup, an
+ * atomic mutation and receipt, or an explicit protection declaration. */
+export declare function createFeedbackStore<Context = void>(options: FeedbackStoreOptions<Context>): FeedbackStore<Context>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store/store.js

@@ -0,0 +1,353 @@
+import { randomUUID } from '@hachej/boring-files/platform';
+import { FEEDBACK_ID, FeedbackFormatError, checkFeedback, createRequest, draftProblems, draftReport, draftBody, listItemOf, parseFeedback, reportLocator, reportPath, resolveRequest, serializeFeedback, subjectKeyOf, } from '../format/index.js';
+export const FEEDBACK_PAGE_SIZE = 50;
+/** The most report files `list` reads in one call; a folder holding more is refused, never silently truncated. */
+export const FEEDBACK_LIST_LIMIT = 5000;
+const BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** `fb_` and 16 base-58 characters from the platform's cryptographic source (rejection sampling, no modulo bias). */
+export function feedbackId() {
+    let out = '';
+    while (out.length < 16) {
+        const hex = randomUUID().replace(/-/g, '');
+        // Skip the UUID's version and variant nibbles, which are not random.
+        const random = hex.slice(0, 12) + hex.slice(13, 16) + hex.slice(17);
+        for (let at = 0; at + 2 <= random.length && out.length < 16; at += 2) {
+            const byte = Number.parseInt(random.slice(at, at + 2), 16);
+            if (byte < 232)
+                out += BASE58[byte % 58];
+        }
+    }
+    return `fb_${out}`;
+}
+/** JSON with object keys sorted, so equal values give equal keys whatever their property order. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(item => canonical(item === undefined ? null : item)).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+const problemsText = (error) => error.problems.map(problem => `${problem.at}: ${problem.message}`).join('; ');
+const sameBytes = (a, b) => a.length === b.length && a.every((byte, index) => byte === b[index]);
+const time = (value) => { const parsed = Date.parse(value); return Number.isNaN(parsed) ? 0 : parsed; };
+/** Newest first; ties by id, so the order is total and a cursor is stable. */
+const order = (a, b) => (time(b.created) - time(a.created)) || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0);
+function encodeCursor(entry) {
+    return btoa(JSON.stringify([entry.created, entry.id])).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function decodeCursor(cursor) {
+    try {
+        const value = JSON.parse(atob(cursor.replace(/-/g, '+').replace(/_/g, '/')));
+        if (Array.isArray(value) && value.length === 2 && typeof value[0] === 'string' && typeof value[1] === 'string' && FEEDBACK_ID.test(value[1]) && !Number.isNaN(Date.parse(value[0])))
+            return { created: value[0], id: value[1] };
+    }
+    catch { /* refused below */ }
+    return undefined;
+}
+/** Build a store over injected resource contracts. Refuses to start without conditional publication, operation lookup, an
+ * atomic mutation and receipt, or an explicit protection declaration. */
+export function createFeedbackStore(options) {
+    const { providerId, view, reader, publisher, lookup, listFolder, operationNamespace, authorizeSubject, displayName, protection } = options;
+    const guarantees = options.capabilities?.guarantees;
+    if (guarantees?.conditionalPublication !== true || guarantees.operationLookup !== true || guarantees.atomicMutationAndReceipt !== true) {
+        throw new TypeError('The feedback store needs a provider that declares conditionalPublication, operationLookup and atomicMutationAndReceipt');
+    }
+    if (protection !== 'protected' && protection !== 'unprotected')
+        throw new TypeError("The feedback store needs an explicit protection: 'protected' or 'unprotected'");
+    if (!providerId)
+        throw new TypeError('A resource provider id is required');
+    if (!operationNamespace)
+        throw new TypeError('A stable operation namespace is required');
+    if (typeof options.root !== 'string' || (options.root && (!options.root.endsWith('/') || options.root.startsWith('/') || options.root.split('/').some(segment => segment === '..' || segment === '.')))) {
+        throw new TypeError('The feedback root must be empty or a relative folder ending with /');
+    }
+    if (!view || (view.kind !== 'published' && view.kind !== 'working'))
+        throw new TypeError('A resource view is required');
+    for (const [name, value] of [['reader.read', reader?.read], ['publisher.publish', publisher?.publish], ['lookup.lookup', lookup?.lookup], ['listFolder', listFolder], ['authorizeSubject', authorizeSubject], ['displayName', displayName], ['resolveAccess', options.resolveAccess]]) {
+        if (typeof value !== 'function')
+            throw new TypeError(`${name} is required`);
+    }
+    const root = Object.freeze({ providerId, view, path: options.root });
+    const now = () => (options.now ?? (() => new Date()))().toISOString();
+    const operationKey = (action, args, access) => canonical([
+        'boring.feedback.operation.v1', operationNamespace, providerId, view, root.path, access.scopeId, access.principalId, access.initiatorId, access.authorizationRef ?? null, action, args,
+    ]);
+    async function allowed(access, subject, permission) {
+        try {
+            return await authorizeSubject({ ...access }, subject, permission) === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function readReport(id, access, revision) {
+        let read;
+        try {
+            read = await reader.read({ target: reportLocator(root, id), revision: revision === undefined ? { kind: 'latest' } : { kind: 'exact', value: revision } }, access);
+        }
+        catch {
+            return { ok: false, refusal: { kind: 'unavailable', reason: 'The feedback report could not be read' } };
+        }
+        if (read.kind !== 'available')
+            return { ok: false, refusal: read };
+        const parsed = parseFeedback(read.snapshot.bytes);
+        if (!parsed.ok || parsed.report.id !== id)
+            return { ok: false, refusal: { kind: 'unavailable', reason: `The feedback report ${id} is not valid` } };
+        if (revision !== undefined && read.snapshot.ref.revision !== revision)
+            return { ok: false, refusal: { kind: 'unavailable', reason: 'Expected the exact report revision' } };
+        return { ok: true, value: { ref: read.snapshot.ref, report: parsed.report } };
+    }
+    async function submit(request, access) {
+        let result;
+        try {
+            result = await publisher.publish(request, access);
+        }
+        catch {
+            return { kind: 'uncertain', reason: 'The publication did not answer' };
+        }
+        if (result.kind === 'committed')
+            return result;
+        if (result.kind === 'conflict')
+            return { kind: 'conflict' };
+        if (result.kind === 'denied' || result.kind === 'unavailable')
+            return { kind: result.kind, reason: result.reason };
+        // A change above the byte limit is a definite refusal: nothing was written, so it is not a partial outcome.
+        if (result.kind === 'file_too_large')
+            return { kind: 'unavailable', reason: result.reason };
+        return { kind: 'uncertain', reason: result.kind === 'unknown' ? result.reason : 'The publication reported a partial outcome' };
+    }
+    const reportChangeOf = (receipt) => {
+        const [first, second] = receipt.changes;
+        if (receipt.changes.length !== 1 || second)
+            return undefined;
+        return first;
+    };
+    const mismatch = () => ({ kind: 'conflict', current: null, reason: 'The operation id is already bound to a different feedback change' });
+    const unreconciled = (operationId, reason) => ({ kind: 'unknown', operationId, reason });
+    /** After an uncertain outcome: one lookup, never a fresh retry. */
+    async function reconcile(operationId, access, match) {
+        let found;
+        try {
+            found = await lookup.lookup(operationId, access);
+        }
+        catch {
+            return unreconciled(operationId, 'The operation lookup did not answer; its effect is unknown');
+        }
+        if (found.kind === 'committed')
+            return match(found.receipt);
+        if (found.kind === 'not-found')
+            return unreconciled(operationId, 'No receipt is retained for the operation; its effect is unknown');
+        if (found.kind === 'conflict')
+            return { kind: 'conflict', current: null, reason: found.reason };
+        if (found.kind === 'denied' || found.kind === 'unavailable')
+            return { kind: found.kind, reason: found.reason };
+        return unreconciled(operationId, found.kind === 'unknown' ? found.reason : 'The operation has a partial outcome');
+    }
+    /** Admission shared by create, resolve and remove: binding check, then a replay lookup before anything is prepared. */
+    async function admit(action, args, access, operation, match, fresh) {
+        if (typeof operation?.id !== 'string' || !operation.id || typeof operation.key !== 'string')
+            return { kind: 'denied', reason: 'A stable operation identity is required' };
+        const operationId = JSON.stringify([operationNamespace, operation.id]);
+        if (operation.key !== operationKey(action, args, access))
+            return unreconciled(operationId, 'The admitted feedback binding changed; reconcile the original operation');
+        let prior;
+        try {
+            prior = await lookup.lookup(operationId, access);
+        }
+        catch {
+            return unreconciled(operationId, 'The operation lookup did not answer');
+        }
+        if (prior.kind === 'committed')
+            return match(prior.receipt);
+        if (prior.kind !== 'not-found')
+            return unreconciled(operationId, prior.kind === 'unknown' ? prior.reason : 'The operation cannot be reconciled');
+        return fresh(operationId);
+    }
+    const create = async (draft, access, operation) => {
+        const problems = draftProblems(draft);
+        if (problems.length)
+            return { kind: 'denied', reason: problems.map(problem => `${problem.at}: ${problem.message}`).join('; ') };
+        let checked;
+        try {
+            checked = draftReport(draft, { id: 'fb_1111111111111111', created: '2000-01-01T00:00:00Z' });
+        }
+        catch (error) {
+            if (error instanceof FeedbackFormatError)
+                return { kind: 'denied', reason: problemsText(error) };
+            throw error;
+        }
+        // Notes and steps are part of the binding only when present, so a Release 1 draft keeps its operation key.
+        const args = draftBody(checked);
+        const subject = { key: subjectKeyOf(checked.observed), observed: checked.observed };
+        const match = async (receipt) => {
+            const change = reportChangeOf(receipt);
+            const path = change?.after?.resource.path ?? '';
+            const id = path.slice(root.path.length, -'.md'.length);
+            if (change?.kind !== 'create' || !path.startsWith(root.path) || !FEEDBACK_ID.test(id) || reportPath(root, id) !== path)
+                return mismatch();
+            const stored = await readReport(id, access, change.after.revision);
+            if (!stored.ok)
+                return unreconciled(receipt.operationId, 'The committed report could not be read to reconcile the operation');
+            const { report } = stored.value;
+            const { notes: _notes, steps: _steps, ...withoutBody } = report;
+            const asCalled = checkFeedback({ ...withoutBody, ...args });
+            if (!asCalled.ok || !sameBytes(serializeFeedback(asCalled.report), serializeFeedback(report)) || report.author?.principalId !== access.principalId)
+                return mismatch();
+            if (!await allowed(access, { key: subjectKeyOf(report.observed), observed: report.observed }, 'annotate'))
+                return unreconciled(receipt.operationId, 'Current access does not permit reconciliation of this operation');
+            return { kind: 'applied', operationId: receipt.operationId, report, revision: change.after.revision };
+        };
+        return admit('create', args, access, operation, match, async (operationId) => {
+            if (!await allowed(access, subject, 'annotate'))
+                return { kind: 'denied', reason: 'Annotating this subject is not authorized' };
+            let display;
+            try {
+                display = String(await displayName(access.principalId));
+            }
+            catch {
+                display = '';
+            }
+            if (!display.trim() || /[\n\r]/.test(display))
+                display = access.principalId;
+            const author = { principalId: access.principalId, display };
+            const id = feedbackId(), created = now();
+            let built;
+            try {
+                built = createRequest({ operationId, root, draft: args, id, created, author });
+            }
+            catch (error) {
+                if (error instanceof FeedbackFormatError)
+                    return { kind: 'denied', reason: problemsText(error) };
+                throw error;
+            }
+            const outcome = await submit(built.request, access);
+            if (outcome.kind === 'committed')
+                return match(outcome.receipt);
+            if (outcome.kind === 'uncertain')
+                return reconcile(operationId, access, match);
+            if (outcome.kind !== 'conflict')
+                return outcome;
+            const existing = await readReport(id, access);
+            return { kind: 'conflict', current: existing.ok ? existing.value.ref.revision : null, reason: 'A report with this id already exists' };
+        });
+    };
+    /** The current report, then authorization on its subject. */
+    async function authorized(id, access, permission) {
+        if (typeof id !== 'string' || !FEEDBACK_ID.test(id))
+            return { ok: false, refusal: { kind: 'missing' } };
+        const current = await readReport(id, access);
+        if (!current.ok)
+            return current;
+        if (!await allowed(access, { key: subjectKeyOf(current.value.report.observed) }, permission))
+            return { ok: false, refusal: { kind: 'denied', reason: permission === 'read' ? 'Reading this feedback is not authorized' : 'Annotating this subject is not authorized' } };
+        return current;
+    }
+    const read = async (id, access) => {
+        const found = await authorized(id, access, 'read');
+        if (!found.ok)
+            return found.refusal;
+        return { kind: 'available', report: found.value.report, revision: found.value.ref.revision };
+    };
+    const list = async (query, access) => {
+        const after = query.cursor === undefined ? undefined : decodeCursor(query.cursor);
+        if (query.cursor !== undefined && !after)
+            return { kind: 'unavailable', reason: 'The cursor is not valid' };
+        let names;
+        try {
+            names = await listFolder(root.path, { ...access });
+        }
+        catch {
+            return { kind: 'unavailable', reason: 'The feedback folder could not be listed' };
+        }
+        if (!Array.isArray(names))
+            return names;
+        const ids = names.filter(name => name.endsWith('.md') && FEEDBACK_ID.test(name.slice(0, -'.md'.length))).map(name => name.slice(0, -'.md'.length));
+        if (ids.length > FEEDBACK_LIST_LIMIT)
+            return { kind: 'unavailable', reason: `The feedback folder holds more than ${FEEDBACK_LIST_LIMIT} reports` };
+        const decisions = new Map();
+        const readable = async (key) => {
+            let decision = decisions.get(key);
+            if (decision === undefined) {
+                decision = await allowed(access, { key }, 'read');
+                decisions.set(key, decision);
+            }
+            return decision;
+        };
+        const entries = [];
+        for (const id of ids) {
+            const stored = await readReport(id, access);
+            // A file that vanished or is not a valid report is not a report: it is not listed.
+            if (stored.ok)
+                entries.push(listItemOf(root, stored.value.report));
+        }
+        const items = [];
+        let more = false;
+        for (const entry of entries.sort(order)) {
+            if (after && order(after, entry) >= 0)
+                continue;
+            if (query.status !== undefined && entry.status !== query.status)
+                continue;
+            if (query.subject !== undefined && entry.subject !== query.subject)
+                continue;
+            if (!await readable(entry.subject))
+                continue;
+            if (items.length === FEEDBACK_PAGE_SIZE) {
+                more = true;
+                break;
+            }
+            items.push(entry);
+        }
+        const last = items.at(-1);
+        return { kind: 'available', items, cursor: more && last ? encodeCursor(last) : null, protection };
+    };
+    const resolve = async (id, input, access, operation) => {
+        const args = { id, expectedRevision: input?.expectedRevision, note: input?.note };
+        const match = async (receipt) => {
+            const change = reportChangeOf(receipt);
+            if (change?.kind !== 'replace' || change.before.resource.path !== reportPath(root, id) || change.before.revision !== args.expectedRevision)
+                return mismatch();
+            const stored = await readReport(id, access, change.after.revision);
+            if (!stored.ok)
+                return unreconciled(receipt.operationId, 'The committed report could not be read to reconcile the operation');
+            const { report } = stored.value;
+            const last = report.resolutions.at(-1);
+            if (last?.note !== args.note || last.by !== access.principalId)
+                return mismatch();
+            if (!await allowed(access, { key: subjectKeyOf(report.observed) }, 'annotate'))
+                return unreconciled(receipt.operationId, 'Current access does not permit reconciliation of this operation');
+            return { kind: 'applied', operationId: receipt.operationId, report, revision: change.after.revision };
+        };
+        return admit('resolve', args, access, operation, match, async (operationId) => {
+            if (typeof args.expectedRevision !== 'string' || !args.expectedRevision)
+                return { kind: 'denied', reason: 'An expected revision is required' };
+            if (typeof args.note !== 'string')
+                return { kind: 'denied', reason: 'A resolution note is required' };
+            const current = await authorized(id, access, 'annotate');
+            if (!current.ok)
+                return current.refusal;
+            if (current.value.ref.revision !== args.expectedRevision)
+                return { kind: 'conflict', current: current.value.ref.revision, reason: 'The report changed' };
+            let built;
+            try {
+                built = resolveRequest({ operationId, root, current: current.value, resolution: { at: now(), by: access.principalId, note: args.note } });
+            }
+            catch (error) {
+                if (error instanceof FeedbackFormatError)
+                    return { kind: 'denied', reason: problemsText(error) };
+                throw error;
+            }
+            const outcome = await submit(built.request, access);
+            if (outcome.kind === 'committed')
+                return match(outcome.receipt);
+            if (outcome.kind === 'uncertain')
+                return reconcile(operationId, access, match);
+            if (outcome.kind !== 'conflict')
+                return outcome;
+            const latest = await readReport(id, access);
+            return latest.ok ? { kind: 'conflict', current: latest.value.ref.revision, reason: 'The report changed' } : latest.refusal;
+        });
+    };
+    return Object.freeze({ root, resolveAccess: options.resolveAccess, operationKey, create, read, list, resolve, guarantees: () => ({ protection }) });
+}

package/dist/tickets/index.d.ts

@@ -0,0 +1,5 @@
+export { parseTicket, withTicketOutcome, createTicketSinks } from './ticket.js';
+export type { ProjectInfo, ProjectRepo, Ticket, TicketSink, TicketSinkContext, TicketSinkResult, TicketOutcome, ParsedTicket, TicketSinkOptions, TicketSinks, TicketMirrorResult } from './ticket.js';
+export { githubSink, fileSink, ticketRepoOf, GITHUB_API } from './sinks.js';
+export type { GithubSinkOptions, FileSinkOptions } from './sinks.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tickets/index.js

@@ -0,0 +1,5 @@
+// @hachej/boring-feedback/tickets (FEEDBACK.md, "Tickets"), server only: a ticket is a Markdown file the assistant writes under `tickets/` with
+// Pi's own file tools; `createTicketSinks(...).mirror(path)`, called by the host when a write creates one, publishes it once to the first
+// sink that accepts the project and writes the outcome back into its front matter. Imports `@hachej/boring-files` contracts (type-only) and nothing else.
+export { parseTicket, withTicketOutcome, createTicketSinks } from './ticket.js';
+export { githubSink, fileSink, ticketRepoOf, GITHUB_API } from './sinks.js';

package/dist/tickets/sinks.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectInfo, Ticket, TicketSink } from './ticket.js';
+export declare const GITHUB_API = "https://api.github.com";
+/** The repository a project's tickets go to: the one with role `app`, else the first; only `owner/name` entries count. */
+export declare function ticketRepoOf(project: ProjectInfo): string | undefined;
+export interface GithubSinkOptions {
+    /** A token that may create issues in the project's repository. Server environment only. */
+    readonly token: string;
+    readonly fetch?: typeof globalThis.fetch;
+    /** Defaults to https://api.github.com (GitHub Enterprise: `https://<host>/api/v3`). */
+    readonly apiUrl?: string;
+    /** Added to the ticket's own labels. Defaults to `feedback`. */
+    readonly labels?: readonly string[];
+    readonly timeoutMs?: number;
+}
+/**
+ * Opens one GitHub issue per ticket: `POST /repos/<owner>/<name>/issues` with the ticket's title, body and labels (plus `labels`). One
+ * request, never retried: a refusal (401, 403, 404, 410, 422, any other status, no answer) is returned with a plain reason, and nothing
+ * is filed twice by this sink.
+ */
+export declare function githubSink(options: GithubSinkOptions): TicketSink;
+export interface FileSinkOptions {
+    /** The viewer or share link of a ticket file. */
+    readonly linkFor: (ticket: Ticket) => string;
+}
+/** The ticket file is the ticket: accepts every project and answers its link. */
+export declare function fileSink(options: FileSinkOptions): TicketSink;
+//# sourceMappingURL=sinks.d.ts.map

package/dist/tickets/sinks.js

@@ -0,0 +1,84 @@
+export const GITHUB_API = 'https://api.github.com';
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** The repository a project's tickets go to: the one with role `app`, else the first; only `owner/name` entries count. */
+export function ticketRepoOf(project) {
+    const repos = project.repos.filter(item => REPO.test(item.repo));
+    return (repos.find(item => item.role === 'app') ?? repos[0])?.repo;
+}
+const REFUSALS = {
+    401: () => 'GitHub refused the token (401): it is missing, expired or revoked.',
+    403: repo => `GitHub denied access (403): the token may not create issues in ${repo}.`,
+    404: repo => `GitHub cannot see ${repo} (404): check the repository name and the token's access.`,
+    410: repo => `Issues are turned off in ${repo} (410).`,
+};
+async function messageOf(response) {
+    try {
+        const body = await response.json();
+        const message = body !== null && typeof body === 'object' ? body['message'] : undefined;
+        return typeof message === 'string' && message.trim() ? message.trim().slice(0, 200) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Opens one GitHub issue per ticket: `POST /repos/<owner>/<name>/issues` with the ticket's title, body and labels (plus `labels`). One
+ * request, never retried: a refusal (401, 403, 404, 410, 422, any other status, no answer) is returned with a plain reason, and nothing
+ * is filed twice by this sink.
+ */
+export function githubSink(options) {
+    const token = options.token;
+    if (typeof token !== 'string' || !token.trim())
+        throw new TypeError('A GitHub token is required');
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const api = (options.apiUrl ?? GITHUB_API).replace(/\/+$/, '');
+    const extra = options.labels ?? ['source:feedback'];
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    return Object.freeze({
+        name: 'github',
+        accepts: (project) => ticketRepoOf(project) !== undefined,
+        publish: async (ticket, context) => {
+            const repo = ticketRepoOf(context.project);
+            if (!repo)
+                return { refused: `The project "${context.project.name}" names no GitHub repository.` };
+            const labels = [...new Set([...ticket.labels, ...extra])];
+            const body = `${ticket.body}\n\n<!-- boring-ticket: ${ticket.id} -->\n`;
+            const signal = context.signal ? AbortSignal.any([context.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+            let response;
+            try {
+                response = await fetchImpl(`${api}/repos/${repo}/issues`, {
+                    method: 'POST', signal,
+                    headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'content-type': 'application/json', 'user-agent': 'boring-feedback-tickets' },
+                    body: JSON.stringify({ title: ticket.title, body, labels }),
+                });
+            }
+            catch {
+                return { refused: `GitHub did not answer; the issue may or may not exist in ${repo}: check before filing again.` };
+            }
+            if (response.status === 201) {
+                let url;
+                try {
+                    url = (await response.json())['html_url'];
+                }
+                catch {
+                    url = undefined;
+                }
+                return typeof url === 'string' && /^https:\/\//.test(url) ? { url } : { refused: `GitHub created an issue in ${repo} but sent no link to it.` };
+            }
+            const known = REFUSALS[response.status];
+            if (known)
+                return { refused: known(repo) };
+            if (response.status === 422)
+                return { refused: `GitHub refused the issue (422)${await messageOf(response).then(message => message ? `: ${message}` : '')}.` };
+            return { refused: `GitHub answered ${response.status}; nothing is known to be filed in ${repo}.` };
+        },
+    });
+}
+/** The ticket file is the ticket: accepts every project and answers its link. */
+export function fileSink(options) {
+    return Object.freeze({
+        name: 'file',
+        accepts: () => true,
+        publish: async (ticket) => ({ url: options.linkFor(ticket) }),
+    });
+}