Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-10166 Email reporters who leave a contact email when fixed (#7960)

Andrew Mikofalvy98b148c13a4b
diff --git a/.github/scripts/release-signing-environment-shape.test.mjs b/.github/scripts/release-signing-environment-shape.test.mjs
index 6fd347411..25741e12b 100644
--- a/.github/scripts/release-signing-environment-shape.test.mjs
+++ b/.github/scripts/release-signing-environment-shape.test.mjs
@@ -33,6 +33,7 @@ const OTHER_SECRETS = [
'LINUX_REPO_R2_SECRET_ACCESS_KEY',
'OK_RELEASE_BRIDGE_APP_ID',
'OK_RELEASE_BRIDGE_APP_PRIVATE_KEY',
+ 'RESEND_API_KEY',
'SLACK_RELEASES_WEBHOOK_URL',
'SLACK_WEBHOOK_URL',
];
diff --git a/.github/scripts/write-back-gate.mjs b/.github/scripts/write-back-gate.mjs
index a054e501a..306361ea4 100644
--- a/.github/scripts/write-back-gate.mjs
+++ b/.github/scripts/write-back-gate.mjs
@@ -13,6 +13,67 @@ const RELEASE_VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/;
const RELEASES_URL = 'https://github.com/inkeep/open-knowledge/releases';
+const CONTACT_EMAIL_LINE_RE = /^ {0,3}[-*+]\s+Contact email:(.*)$/i;
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+const ADDRESS_RE = /^[^\s@<>()[\]:]+@[^\s@<>()[\]]+\.[^\s@<>()[\].]+$/;
+const ADDRESS_IN_TEXT_RE = /[^\s@<>()[\]:]+@[^\s@<>()[\]]+\.[^\s@<>()[\].]+/;
+const INTERNAL_DOMAIN_RE = /(?:^|\.)inkeep\.[a-z]{2,}$/i;
+
+export function parseContactEmail(description) {
+ let fence = null;
+ for (const line of String(description ?? '').split(/\r?\n/)) {
+ const marker = FENCE_RE.exec(line)?.[1];
+ if (fence) {
+ if (
+ marker &&
+ marker[0] === fence[0] &&
+ marker.length >= fence.length &&
+ !line.trim().slice(marker.length)
+ )
+ fence = null;
+ continue;
+ }
+ if (marker) {
+ fence = marker;
+ continue;
+ }
+ const field = CONTACT_EMAIL_LINE_RE.exec(line);
+ if (field) return addressFromField(field[1]);
+ }
+ return null;
+}
+
+function addressFromField(raw) {
+ const value = raw.replace(/\\([!-/:-@[-`{-~])/g, '$1');
+ const mailto = /mailto:([^\s<>()]+)/i.exec(value)?.[1];
+ let address = mailto ?? ADDRESS_IN_TEXT_RE.exec(value)?.[0] ?? '';
+ try {
+ address = decodeURIComponent(address);
+ } catch {
+ return null;
+ }
+ return ADDRESS_RE.test(address) ? address : null;
+}
+
+export function isInternalContactEmail(address) {
+ return INTERNAL_DOMAIN_RE.test(
+ String(address ?? '')
+ .split('@')
+ .at(-1),
+ );
+}
+
+export function contactEmailOrigin(address, reportIdentifier, reportKind = 'bug-report') {
+ return {
+ kind: 'repliable-origin',
+ channel: 'email',
+ url: `mailto:${address.toLowerCase()}`,
+ address,
+ reportIdentifier,
+ reportKind,
+ };
+}
+
export function classifyAttachment(rawUrl) {
const url = String(rawUrl ?? '').trim();
if (!url) return { kind: 'unknown', url };
@@ -250,18 +311,49 @@ export function composeReply({
'',
]
: []),
- openingLine(channel, normalizedVersion),
+ openingLine(channel, normalizedVersion, originChannel),
];
- if (coverage.length > 0) {
+ if (coverage.length > 0 && originChannel !== 'email') {
lines.push('', `Covers ${[...coverage].sort().join(', ')}.`);
}
lines.push('', updateInstruction(originChannel, channel, normalizedVersion));
+ if (originChannel === 'email') {
+ lines.push(
+ '',
+ 'You are getting this email because you left this address when you sent the ' +
+ 'Open Knowledge team a report or feedback. Reply to reach the team.',
+ );
+ }
+
return lines.join('\n');
}
+export function composeEmailSubject({
+ identifier,
+ version,
+ channel = 'stable',
+ correction = false,
+ reportKind = 'bug-report',
+}) {
+ const v = String(version ?? '')
+ .trim()
+ .replace(/^v/, '');
+ const subject =
+ reportKind === 'feedback'
+ ? 'what you told us about Open Knowledge'
+ : `your Open Knowledge report ${identifier}`;
+ if (channel === 'beta') {
+ return `${correction ? 'Correction: a' : 'A'} fix for ${subject} is in beta v${v}`;
+ }
+ const sentence = `${subject} is fixed in v${v}`;
+ return correction
+ ? `Correction: ${sentence}`
+ : `${sentence[0].toUpperCase()}${sentence.slice(1)}`;
+}
+
function updateInstruction(originChannel, channel, version) {
const lead =
channel === 'beta'
@@ -271,16 +363,25 @@ function updateInstruction(originChannel, channel, version) {
if (originChannel === 'discord-thread') {
return `${lead} <${url}>.`;
}
+ if (originChannel === 'email') {
+ return channel === 'beta'
+ ? `Read the notes and download the beta at ${url}`
+ : `To pick it up, get the latest Open Knowledge. The notes are at ${url}`;
+ }
return `${lead} [the release page](${url}).`;
}
-function openingLine(channel, version) {
+function openingLine(channel, version, originChannel) {
if (channel === 'beta') {
return (
`This fix is available in Open Knowledge beta v${version}. ` +
- 'Thanks for the report. It will reach the stable channel in an upcoming release, ' +
- 'and we will follow up here when it does.'
+ `${thanks(originChannel)} It will reach the stable channel in an upcoming release, ` +
+ `and we will ${originChannel === 'email' ? 'email you again' : 'follow up here'} when it does.`
);
}
- return `This shipped in Open Knowledge v${version}. Thanks for the report.`;
+ return `This shipped in Open Knowledge v${version}. ${thanks(originChannel)}`;
+}
+
+function thanks(originChannel) {
+ return originChannel === 'email' ? 'Thanks for telling us.' : 'Thanks for the report.';
}
diff --git a/.github/scripts/write-back-gate.test.mjs b/.github/scripts/write-back-gate.test.mjs
index bf5b70744..7e146c9cb 100644
--- a/.github/scripts/write-back-gate.test.mjs
+++ b/.github/scripts/write-back-gate.test.mjs
@@ -2,10 +2,14 @@ import { describe, expect, test } from 'vitest';
import {
classifyAttachment,
compareVersions,
+ composeEmailSubject,
composeReply,
+ contactEmailOrigin,
evaluateFanIn,
highestVersion,
+ isInternalContactEmail,
isOriginRepliableFrom,
+ parseContactEmail,
partitionAttachments,
planIssueClose,
} from './write-back-gate.mjs';
@@ -572,3 +576,143 @@ describe('the two channels say different things', () => {
).toThrow(/derived version/);
});
});
+
+describe('the contact email an intake report carries', () => {
+ const intake = (contactLine, note = 'It froze.') =>
+ [
+ 'Automated intake from the in-app OpenKnowledge bug reporter.',
+ '',
+ '* Level: full',
+ '* App version: 0.88.6',
+ ...(contactLine === null ? [] : [contactLine]),
+ '',
+ '**User note:**',
+ '',
+ '```',
+ note,
+ '```',
+ ].join('\n');
+
+ test('the address is read from the form Linear stores, an autolinked bullet', () => {
+ expect(
+ parseContactEmail(intake('* Contact email: [[email protected]](<mailto:[email protected]>)')),
+ ).toBe('[email protected]');
+ });
+
+ test('the address is read from the plain line the intake writes', () => {
+ expect(parseContactEmail(intake('- Contact email: [email protected]'))).toBe('[email protected]');
+ });
+
+ test('the mailto target wins over link text Linear escaped', () => {
+ expect(
+ parseContactEmail(
+ intake('* Contact email: [jo\\[email protected]](<mailto:[email protected]>)'),
+ ),
+ ).toBe('[email protected]');
+ });
+
+ test('a report without the line has no contact email', () => {
+ expect(parseContactEmail(intake(null))).toBeNull();
+ expect(parseContactEmail('')).toBeNull();
+ expect(parseContactEmail(undefined)).toBeNull();
+ });
+
+ test('an address typed into the note is never mistaken for the contact field', () => {
+ expect(parseContactEmail(intake(null, '- Contact email: [email protected]'))).toBeNull();
+ });
+
+ test('prose that mentions the field without an address yields nothing', () => {
+ expect(parseContactEmail('Bug reports now carry an optional Contact email: field.')).toBeNull();
+ expect(parseContactEmail('- Contact email: (none)')).toBeNull();
+ });
+
+ test('every Inkeep domain is internal, and nothing else is', () => {
+ expect(isInternalContactEmail('[email protected]')).toBe(true);
+ expect(isInternalContactEmail('[email protected]')).toBe(true);
+ expect(isInternalContactEmail('[email protected]')).toBe(true);
+ expect(isInternalContactEmail('[email protected]')).toBe(false);
+ expect(isInternalContactEmail('[email protected]')).toBe(false);
+ });
+
+ test('an email origin is keyed by its mailto url and remembers the report it came from', () => {
+ expect(contactEmailOrigin('[email protected]', 'PRD-9')).toEqual({
+ kind: 'repliable-origin',
+ channel: 'email',
+ url: 'mailto:[email protected]',
+ address: '[email protected]',
+ reportIdentifier: 'PRD-9',
+ reportKind: 'bug-report',
+ });
+ });
+});
+
+describe('an emailed reply', () => {
+ const changeset = { title: 'Fix', body: 'Fix the download.' };
+
+ test('says how to update without assuming the desktop app, and leaves out internal tickets', () => {
+ const text = composeReply({
+ changeset,
+ version: '0.89.0',
+ originChannel: 'email',
+ coverage: ['PRD-1'],
+ });
+ expect(text).toContain('get the latest Open Knowledge');
+ expect(text).toContain('Thanks for telling us.');
+ expect(text).not.toContain('Thanks for the report');
+ expect(text).not.toContain('desktop app');
+ expect(text).not.toContain('Covers');
+ });
+
+ test('names the release by a bare URL, since a mail client does not render markdown', () => {
+ const text = composeReply({ changeset, version: '0.89.0', originChannel: 'email' });
+ expect(text).toContain('https://github.com/inkeep/open-knowledge/releases/tag/v0.89.0');
+ expect(text).not.toContain('](');
+ expect(text).not.toContain('<https://');
+ });
+
+ test('a beta email promises a second email rather than a reply "here"', () => {
+ const text = composeReply({
+ changeset,
+ version: '0.89.0-beta.1',
+ originChannel: 'email',
+ channel: 'beta',
+ });
+ expect(text).toContain('email you again');
+ expect(text).not.toContain('follow up here');
+ });
+
+ test('says why the reader is getting it', () => {
+ const text = composeReply({ changeset, version: '0.89.0', originChannel: 'email' });
+ expect(text).toContain(
+ 'left this address when you sent the Open Knowledge team a report or feedback',
+ );
+ });
+
+ test('the subject names the report and the release, and a correction says so', () => {
+ expect(
+ composeEmailSubject({ identifier: 'PRD-10089', version: '0.89.0', channel: 'stable' }),
+ ).toBe('Your Open Knowledge report PRD-10089 is fixed in v0.89.0');
+ expect(
+ composeEmailSubject({ identifier: 'PRD-10089', version: '0.89.0-beta.1', channel: 'beta' }),
+ ).toBe('A fix for your Open Knowledge report PRD-10089 is in beta v0.89.0-beta.1');
+ expect(
+ composeEmailSubject({
+ identifier: 'PRD-10089',
+ version: '0.89.0',
+ channel: 'stable',
+ correction: true,
+ }),
+ ).toBe('Correction: your Open Knowledge report PRD-10089 is fixed in v0.89.0');
+ expect(
+ composeEmailSubject({ identifier: 'PRD-1', version: '0.89.0', reportKind: 'feedback' }),
+ ).toBe('What you told us about Open Knowledge is fixed in v0.89.0');
+ expect(
+ composeEmailSubject({
+ identifier: 'PRD-1',
+ version: '0.89.0-beta.1',
+ channel: 'beta',
+ reportKind: 'feedback',
+ }),
+ ).toBe('A fix for what you told us about Open Knowledge is in beta v0.89.0-beta.1');
+ });
+});
diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjs
index 260cd5b7d..0e0bbbbcd 100644
--- a/.github/scripts/write-back.mjs
+++ b/.github/scripts/write-back.mjs
@@ -1,6 +1,7 @@
#!/usr/bin/env node
/* biome-ignore-all lint/suspicious/noUndeclaredEnvVars: GitHub Actions invokes this entrypoint outside Turbo. */
import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
import { pathToFileURL } from 'node:url';
import {
deriveChannel,
@@ -19,10 +20,14 @@ import {
import { createTagContainment } from './tag-containment.mjs';
import {
compareVersions,
+ composeEmailSubject,
composeReply,
+ contactEmailOrigin,
evaluateFanIn,
+ isInternalContactEmail,
isOriginRepliableFrom,
markerSuffixFor,
+ parseContactEmail,
partitionAttachments,
planIssueClose,
} from './write-back-gate.mjs';
@@ -33,6 +38,9 @@ const RELEASES_TAG_BASE = 'https://github.com/inkeep/open-knowledge/releases/tag
const DEFAULT_PRIVATE_REPO = 'inkeep/agents-private';
const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
const PAGE_SIZE = 50;
+const RESEND_EMAILS_URL = 'https://api.resend.com/emails';
+const EMAIL_FROM = 'OpenKnowledge <[email protected]>';
+const EMAIL_REPLY_TO = '[email protected]';
export const CANDIDATE_QUERY = `
query WriteBackCandidates($after: String) {
@@ -54,6 +62,30 @@ export const CANDIDATE_QUERY = `
}
`;
+export const CONTACT_EMAIL_QUERY = `
+ query WriteBackContactEmails($after: String) {
+ issues(
+ first: ${PAGE_SIZE}
+ after: $after
+ filter: {
+ state: { type: { in: ["completed", "duplicate"] } }
+ labels: { some: { name: { in: ["ok:intake", "ok:feedback"] } } }
+ description: { containsIgnoreCase: "Contact email:" }
+ }
+ ) {
+ pageInfo { hasNextPage endCursor }
+ nodes {
+ id
+ identifier
+ description
+ state { type }
+ labels { nodes { name } }
+ relations { nodes { type relatedIssue { id } } }
+ }
+ }
+ }
+`;
+
export const CHILDREN_QUERY = `
query WriteBackChildren($parentId: ID!, $after: String) {
issues(first: ${PAGE_SIZE}, after: $after, filter: { parent: { id: { eq: $parentId } } }) {
@@ -302,6 +334,59 @@ const KEPT_OPEN_HINTS = {
'and close it by hand if none is still open',
};
+const EMAIL_MODES = new Set(['off', 'dry-run', 'live']);
+
+export function emailIdempotencyKey(ticketId, markerUrl) {
+ if (!ticketId || !markerUrl)
+ throw new Error('emailIdempotencyKey needs a ticket id and a marker');
+ return `write-back-${createHash('sha256').update(`${ticketId}\n${markerUrl}`).digest('hex')}`;
+}
+
+export function resolveEmailMode({ resendKey, live, emailModeVariable }) {
+ if (!String(resendKey ?? '').trim()) return 'off';
+ return live && emailModeVariable === 'live' ? 'live' : 'dry-run';
+}
+
+export function createRunOutput({
+ redactor = createRedactor(),
+ out = console.log,
+ err = console.error,
+} = {}) {
+ return {
+ redactor,
+ log: (message) => out(redactor.scrub(message)),
+ error: (message) => err(redactor.scrub(message)),
+ };
+}
+
+function escapeRegExp(text) {
+ return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function createRedactor() {
+ const addresses = new Set();
+ return {
+ add(address) {
+ if (address) addresses.add(String(address).toLowerCase());
+ },
+ scrub(text) {
+ let out = String(text ?? '');
+ for (const address of addresses) {
+ for (const form of new Set([address, encodeURIComponent(address)])) {
+ out = out.replace(new RegExp(escapeRegExp(form), 'gi'), 'the contact email');
+ }
+ }
+ return out;
+ },
+ };
+}
+
+function originLabel(origin) {
+ return origin.channel === 'email'
+ ? `the contact email from ${origin.reportIdentifier}`
+ : origin.url;
+}
+
export class NeedsHumanError extends Error {
constructor(message) {
super(message);
@@ -344,9 +429,15 @@ export async function runWriteBack({
classifyRelease,
channel = 'stable',
selfRepo = process.env.GITHUB_REPOSITORY,
+ emailMode = 'off',
live = false,
log = () => {},
}) {
+ if (!EMAIL_MODES.has(emailMode)) {
+ throw new Error(
+ `runWriteBack requires emailMode 'off', 'dry-run' or 'live', got '${emailMode}'`,
+ );
+ }
if (typeof classifyRelease !== 'function') {
throw new Error('runWriteBack requires classifyRelease; see makeReleaseWindow.');
}
@@ -383,10 +474,22 @@ export async function runWriteBack({
unrepliable,
fixReferences,
} = partitionAttachments(candidate.attachmentUrls ?? []);
- const origins = attachedOrigins.filter((origin) => isOriginRepliableFrom(origin, selfRepo));
+ const contacts = (candidate.contacts ?? []).map((c) =>
+ contactEmailOrigin(c.address, c.reportIdentifier, c.reportKind),
+ );
+ const externalContacts = contacts.filter((c) => !isInternalContactEmail(c.address));
+ const origins = [
+ ...attachedOrigins.filter((origin) => isOriginRepliableFrom(origin, selfRepo)),
+ ...(emailMode === 'off' ? [] : externalContacts),
+ ];
if (origins.length === 0 && unrepliable.length === 0) {
- if (attachedOrigins.length > 0) {
+ if (contacts.length > 0) {
+ skip(
+ candidate.identifier,
+ externalContacts.length > 0 ? 'email-unconfigured' : 'internal-reporter',
+ );
+ } else if (attachedOrigins.length > 0) {
log(
`::debug::write-back: ${candidate.identifier} reports from ` +
`${attachedOrigins.map((o) => o.url).join(', ')}, outside ${selfRepo || 'this repo'}; ` +
@@ -479,7 +582,9 @@ export async function runWriteBack({
return;
}
+ const emailFailures = [];
for (const origin of origins) {
+ const label = originLabel(origin);
const attachmentUrls = candidate.attachmentUrls ?? [];
const marker = notificationMarkerUrl({ version: gate.version, originUrl: origin.url });
const notifiedVersions = notificationVersions({
@@ -505,6 +610,16 @@ export async function runWriteBack({
channel,
isPublishedVersion,
});
+ const subject =
+ origin.channel === 'email'
+ ? composeEmailSubject({
+ identifier: origin.reportIdentifier,
+ version: gate.version,
+ channel,
+ correction: recoveryFrom.length > 0,
+ reportKind: origin.reportKind,
+ })
+ : undefined;
const text =
changeset === null
? null
@@ -535,13 +650,14 @@ export async function runWriteBack({
? `${origin.url} (${closure.open.length ? `${closure.reason}: ${closure.open.join(', ')}` : closure.reason})`
: null;
- if (!live) {
+ const sendLive = live && (origin.channel !== 'email' || emailMode === 'live');
+ if (!sendLive) {
log(
- `::notice::write-back: [dry run] would reply to ${origin.url} for ${candidate.identifier} ` +
+ `::notice::write-back: [dry run] would reply to ${label} for ${candidate.identifier} ` +
`(v${gate.version}, covers ${gate.coverage.join(', ')}).`,
);
log(
- `::notice::write-back: [dry run] ${recoveryFrom.length ? 'recovery correction' : 'release announcement'}: ${text.replaceAll('\n', ' ')}`,
+ `::notice::write-back: [dry run] ${recoveryFrom.length ? 'recovery correction' : 'release announcement'}: ${subject ? `${subject}: ` : ''}${text.replaceAll('\n', ' ')}`,
);
if (closure) {
log(
@@ -550,7 +666,7 @@ export async function runWriteBack({
}
posted.push({
identifier: candidate.identifier,
- origin: origin.url,
+ origin: label,
version: gate.version,
dryRun: true,
closed: closure?.close === true,
@@ -558,29 +674,67 @@ export async function runWriteBack({
continue;
}
+ if (origin.channel === 'email') {
+ let sent;
+ try {
+ sent = await postReply(origin, text, {
+ subject,
+ idempotencyKey: emailIdempotencyKey(candidate.id, marker),
+ });
+ } catch (err) {
+ emailFailures.push(
+ `${label}, on the ${channel} leg for v${gate.version} (${err.message})`,
+ );
+ continue;
+ }
+ const messageId = sent?.id ?? null;
+ log(
+ sent?.alreadyAccepted
+ ? `::warning::write-back: Resend had already accepted a message to ${label} for ` +
+ `${candidate.identifier} (v${gate.version}) under this ticket's key, with different text; ` +
+ 'recording the marker without sending again.'
+ : `::notice::write-back: emailed ${label} for ${candidate.identifier} (v${gate.version}, ` +
+ `Resend message ${messageId}); recording the marker next.`,
+ );
+ await recordNotification({
+ issueId: candidate.id,
+ url: marker,
+ title: `Reporter notified: v${gate.version}`,
+ });
+ posted.push({
+ identifier: candidate.identifier,
+ origin: label,
+ version: gate.version,
+ dryRun: false,
+ closed: false,
+ messageId,
+ });
+ continue;
+ }
+
await recordNotification({
issueId: candidate.id,
url: marker,
title: `Reporter notified: v${gate.version}`,
});
log(
- `::debug::write-back: marker written for ${origin.url} (${candidate.identifier}); posting reply next.`,
+ `::debug::write-back: marker written for ${label} (${candidate.identifier}); posting reply next.`,
);
try {
- await postReply(origin, text);
+ await postReply(origin, text, { subject });
} catch (err) {
throw new NeedsHumanError(
- `marker for ${origin.url} was written but the reply did NOT send (${err.message}). ` +
+ `marker for ${label} was written but the reply did NOT send (${err.message}). ` +
`No future run will retry it; post the reply by hand${closure?.close ? ', then close the issue' : ''}.`,
);
}
log(
- `::notice::write-back: replied to ${origin.url} for ${candidate.identifier} ` +
+ `::notice::write-back: replied to ${label} for ${candidate.identifier} ` +
`(v${gate.version}).`,
);
const entry = {
identifier: candidate.identifier,
- origin: origin.url,
+ origin: label,
version: gate.version,
dryRun: false,
closed: false,
@@ -609,6 +763,13 @@ export async function runWriteBack({
`::notice::write-back: closed ${origin.url} for ${candidate.identifier} (v${gate.version}).`,
);
}
+ if (emailFailures.length > 0) {
+ throw new Error(
+ `email to ${emailFailures.join('; ')} did not send; the next run retries it. If Resend keeps ` +
+ "refusing one address, end its retries by attaching that address's marker for that " +
+ 'version to the ticket, as RELEASES.md describes under the email reply leg',
+ );
+ }
};
let candidates;
@@ -650,6 +811,19 @@ export async function runWriteBack({
return { posted, skipped, errored, deferred, dryRun: !live };
}
+export function runSummary(result, { linearRequests }) {
+ return {
+ dryRun: result.dryRun,
+ linearRequests,
+ deferred: result.deferred,
+ posted: result.posted.filter((entry) => !entry.dryRun).length,
+ previewed: result.posted.filter((entry) => entry.dryRun).length,
+ closed: result.posted.filter((entry) => !entry.dryRun && entry.closed).length,
+ skipped: result.skipped,
+ errored: result.errored,
+ };
+}
+
export function runFailureMessage({ errored = [], deferred } = {}) {
if (errored.length === 0) return null;
if (deferred === null) {
@@ -661,7 +835,7 @@ export function runFailureMessage({ errored = [], deferred } = {}) {
const needsHuman = errored.filter((e) => e.disposition === 'needs-human');
if (needsHuman.length === 0) {
- return `${head}. No marker was written for any of them, so the next release run picks them up again.`;
+ return `${head}. Every reply that failed was left unmarked, so the next release run picks them up again.`;
}
return (
`${head}. ACTION REQUIRED: ${needsHuman.map((e) => e.identifier).join(', ')} ` +
@@ -849,7 +1023,51 @@ export function toNode(raw) {
};
}
-async function paginate({ apiKey, query, variables, log, fetchImpl }) {
+export function toContactNode(raw) {
+ const labels = (raw.labels?.nodes ?? []).map((label) => label.name);
+ const canonical =
+ raw.state?.type === 'duplicate'
+ ? (raw.relations?.nodes ?? []).find((relation) => relation.type === 'duplicate')?.relatedIssue
+ ?.id
+ : raw.id;
+ return {
+ targetId: canonical ?? null,
+ address: parseContactEmail(raw.description),
+ reportIdentifier: raw.identifier,
+ reportKind: labels.includes('ok:intake') ? 'bug-report' : 'feedback',
+ own: canonical === raw.id,
+ };
+}
+
+export async function listCandidatesWithContacts({ paginate, redactor }) {
+ const candidates = await paginate(CANDIDATE_QUERY, toNode);
+ const contacts = await paginate(CONTACT_EMAIL_QUERY, toContactNode);
+ for (const contact of contacts) redactor?.add(contact.address);
+ return attachContactEmails(candidates, contacts);
+}
+
+export function attachContactEmails(candidates, contactNodes) {
+ const byTarget = new Map();
+ const ordered = [...contactNodes].sort((a, b) => Number(b.own) - Number(a.own));
+ for (const node of ordered) {
+ if (!node.targetId || !node.address) continue;
+ const list = byTarget.get(node.targetId) ?? [];
+ const address = node.address.toLowerCase();
+ if (!list.some((c) => c.address.toLowerCase() === address)) {
+ list.push({
+ address: node.address,
+ reportIdentifier: node.reportIdentifier,
+ reportKind: node.reportKind,
+ });
+ }
+ byTarget.set(node.targetId, list);
+ }
+ return candidates.map((candidate) =>
+ byTarget.has(candidate.id) ? { ...candidate, contacts: byTarget.get(candidate.id) } : candidate,
+ );
+}
+
+async function paginate({ apiKey, query, variables, log, fetchImpl, toItem = toNode }) {
const collected = [];
let after = null;
do {
@@ -865,7 +1083,7 @@ async function paginate({ apiKey, query, variables, log, fetchImpl }) {
throw new Error(
'Linear returned no issues connection; refusing to treat that as an empty result.',
);
- collected.push(...page.nodes.map(toNode));
+ collected.push(...page.nodes.map(toItem));
after = page.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;
} while (after);
return collected;
@@ -1022,7 +1240,50 @@ export function parseChangeset(raw) {
return { title: firstLine.trim(), body: withoutFrontmatter };
}
-async function realPostReply(origin, text) {
+export async function sendReporterEmail({
+ origin,
+ text,
+ subject,
+ idempotencyKey,
+ apiKey,
+ fetchImpl = fetch,
+}) {
+ if (!apiKey) throw new Error('RESEND_API_KEY is required to email a reporter');
+ if (!idempotencyKey) throw new Error('an idempotency key is required to email a reporter');
+ const res = await fetchImpl(RESEND_EMAILS_URL, {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ authorization: `Bearer ${apiKey}`,
+ 'idempotency-key': idempotencyKey,
+ },
+ body: JSON.stringify({
+ from: EMAIL_FROM,
+ to: [origin.address],
+ reply_to: EMAIL_REPLY_TO,
+ subject,
+ text,
+ }),
+ signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+ });
+ const body = await res.text();
+ let payload = null;
+ try {
+ payload = JSON.parse(body);
+ } catch {
+ payload = null;
+ }
+ if (res.ok) return { id: typeof payload?.id === 'string' ? payload.id : null };
+ if (res.status === 409 && payload?.name === 'invalid_idempotent_request') {
+ return { id: null, alreadyAccepted: true };
+ }
+ throw new Error(`Resend returned HTTP ${res.status}: ${body.slice(0, 200)}`);
+}
+
+async function realPostReply(origin, text, { subject, idempotencyKey, resendKey } = {}) {
+ if (origin.channel === 'email') {
+ return sendReporterEmail({ origin, text, subject, idempotencyKey, apiKey: resendKey });
+ }
if (origin.channel === 'github-issue') {
execFileSync(
'gh',
@@ -1118,11 +1379,13 @@ function realCloseIssue(origin) {
);
}
+const output = createRunOutput();
+
async function main() {
- const log = (message) => console.log(message);
+ const { log, redactor } = output;
const apiKey = (process.env.LINEAR_API_KEY ?? '').trim();
if (!apiKey) {
- console.log(
+ log(
'::notice::write-back: LINEAR_API_KEY is not set on this repo, so there is nothing to enumerate. ' +
'Add it as a repo secret to enable reporter write-back. Nothing was posted.',
);
@@ -1169,6 +1432,24 @@ async function main() {
);
}
+ const resendKey = String(process.env.RESEND_API_KEY ?? '').trim();
+ const emailMode = resolveEmailMode({
+ resendKey,
+ live,
+ emailModeVariable: process.env.WRITE_BACK_EMAIL_MODE,
+ });
+ if (emailMode === 'off') {
+ log(
+ '::notice::write-back: RESEND_API_KEY is not set, so contact emails are not read as a reply channel; ' +
+ 'a ticket whose only reachable reporter left one is skipped as email-unconfigured.',
+ );
+ } else if (emailMode === 'dry-run') {
+ log(
+ '::notice::write-back: email replies are previewed, not sent (set WRITE_BACK_EMAIL_MODE=live, ' +
+ 'with WRITE_BACK_MODE=live, to arm them).',
+ );
+ }
+
let linearRequests = 0;
const fetchImpl = (...args) => {
linearRequests++;
@@ -1176,7 +1457,11 @@ async function main() {
};
const result = await runWriteBack({
listCandidates: () =>
- paginate({ apiKey, query: CANDIDATE_QUERY, variables: {}, log, fetchImpl }),
+ listCandidatesWithContacts({
+ paginate: (query, toItem) =>
+ paginate({ apiKey, query, variables: {}, log, fetchImpl, toItem }),
+ redactor,
+ }),
listChildren: (parentId) =>
paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId }, log, fetchImpl }),
versionFor: (node) => versionFor(node, channel),
@@ -1184,8 +1469,9 @@ async function main() {
isPublishedVersion: (version) => stableTags.includes(`v${version}`),
classifyRelease,
channel,
+ emailMode,
readChangesetProse: (candidate, ctx) => realReadChangesetProse(candidate, ctx),
- postReply: realPostReply,
+ postReply: (origin, text, message) => realPostReply(origin, text, { ...message, resendKey }),
readIssueClosure: createIssueClosureReader({
readIssueState: (origin) => readIssueStateWith(gh, origin),
queryCarriers: (url) =>
@@ -1209,17 +1495,7 @@ async function main() {
log,
});
- console.log(
- JSON.stringify({
- dryRun: result.dryRun,
- linearRequests,
- deferred: result.deferred,
- posted: result.posted.length,
- closed: result.posted.filter((entry) => entry.closed).length,
- skipped: result.skipped,
- errored: result.errored,
- }),
- );
+ log(JSON.stringify(runSummary(result, { linearRequests })));
const failure = runFailureMessage(result);
if (failure) throw new Error(failure);
@@ -1227,7 +1503,7 @@ async function main() {
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
main().catch((err) => {
- console.error(`::error::write-back: ${err.message}`);
+ output.error(`::error::write-back: ${err.message}`);
process.exit(1);
});
}
diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjs
index 4b8fe9044..5b9136deb 100644
--- a/.github/scripts/write-back.test.mjs
+++ b/.github/scripts/write-back.test.mjs
@@ -6,10 +6,15 @@ import { describe, expect, test } from 'vitest';
import { parse } from 'yaml';
import { deriveChannel } from './published-release-tags.mjs';
import {
+ attachContactEmails,
CANDIDATE_QUERY,
+ CONTACT_EMAIL_QUERY,
changesetDirFor,
createIssueClosureReader,
+ createRedactor,
+ createRunOutput,
deriveVersionForFixRefs,
+ emailIdempotencyKey,
findChangesetPath,
isFixRepoInRemit,
isRetryableNetworkError,
@@ -20,16 +25,21 @@ import {
LINEAR_RETRY_CAP_MS,
LinearRateLimitError,
linearGraphql,
+ listCandidatesWithContacts,
makeReleaseWindow,
notificationMarkerUrl,
parseChangeset,
parseMergeShaOutput,
parseRetryAfterSeconds,
readIssueStateWith,
+ resolveEmailMode,
retryDelayMs,
runFailureMessage,
+ runSummary,
runWriteBack,
selectGhToken,
+ sendReporterEmail,
+ toContactNode,
toNode,
} from './write-back.mjs';
import { composeReply, planIssueClose } from './write-back-gate.mjs';
@@ -816,6 +826,601 @@ describe('write-back run', () => {
});
});
+describe('emailing a reporter who left a contact email', () => {
+ const ADDRESS = '[email protected]';
+ const CONTACT = { address: ADDRESS, reportIdentifier: 'PRD-7539' };
+ const MAILTO = `mailto:${ADDRESS}`;
+ const emailHarness = (overrides = {}) => {
+ const h = harness({
+ emailMode: 'live',
+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL], contacts: [CONTACT] })],
+ ...overrides,
+ });
+ h.deps.postReply =
+ overrides.postReply ??
+ (async (origin, text, message) => {
+ h.writes.push({ kind: 'post', origin: origin.url, text, ...message });
+ return origin.channel === 'email' ? { id: 'msg_123' } : undefined;
+ });
+ return h;
+ };
+ const leaked = (h, result) =>
+ [...h.logs, JSON.stringify(result), runFailureMessage(result) ?? ''].some((line) =>
+ line.includes(ADDRESS),
+ );
+
+ test('the email is sent first, under a key derived from its marker, and then marked', async () => {
+ const h = emailHarness({ live: true });
+ const result = await h.run();
+ const marker = notificationMarkerUrl({ version: '0.36.0', originUrl: MAILTO });
+ expect(h.writes.map((w) => w.kind)).toEqual(['post', 'mark']);
+ const [post, mark] = h.writes;
+ expect(mark.url).toBe(marker);
+ expect(post.origin).toBe(MAILTO);
+ expect(post.idempotencyKey).toBe(emailIdempotencyKey('uuid-7539', marker));
+ expect(post.subject).toBe('Your Open Knowledge report PRD-7539 is fixed in v0.36.0');
+ expect(post.text).toContain('https://github.com/inkeep/open-knowledge/releases/tag/v0.36.0');
+ expect(result.posted).toEqual([
+ expect.objectContaining({ origin: 'the contact email from PRD-7539', messageId: 'msg_123' }),
+ ]);
+ expect(h.logs.some((m) => m.includes('Resend message msg_123'))).toBe(true);
+ });
+
+ test('the idempotency key is the same on every run, so a retried send is not delivered twice', () => {
+ const marker = notificationMarkerUrl({ version: '0.36.0', originUrl: MAILTO });
+ expect(emailIdempotencyKey('uuid-7539', marker)).toBe(emailIdempotencyKey('uuid-7539', marker));
+ expect(emailIdempotencyKey('uuid-7539', marker)).not.toContain(ADDRESS);
+ expect(emailIdempotencyKey('uuid-7539', marker)).not.toBe(
+ emailIdempotencyKey(
+ 'uuid-7539',
+ notificationMarkerUrl({ version: '0.36.1', originUrl: MAILTO }),
+ ),
+ );
+ });
+
+ test('two tickets from one address in one release are two sends, not one', () => {
+ const marker = notificationMarkerUrl({ version: '0.36.0', originUrl: MAILTO });
+ expect(emailIdempotencyKey('uuid-1', marker)).not.toBe(emailIdempotencyKey('uuid-2', marker));
+ });
+
+ test('a key Resend already accepted for this ticket is marked, and says it sent nothing new', async () => {
+ const h = emailHarness({
+ live: true,
+ postReply: async (origin) => {
+ h.writes.push({ kind: 'post', origin: origin.url });
+ return { id: null, alreadyAccepted: true };
+ },
+ });
+ const result = await h.run();
+ expect(h.writes.map((w) => w.kind)).toEqual(['post', 'mark']);
+ expect(result.errored).toEqual([]);
+ expect(
+ h.logs.some((m) => m.startsWith('::warning::') && m.includes('without sending again')),
+ ).toBe(true);
+ expect(h.logs.some((m) => m.includes('emailed the contact email'))).toBe(false);
+ });
+
+ test('the message id is logged before the marker, so a failed marker still names the send', async () => {
+ const h = emailHarness({
+ live: true,
+ recordNotification: async () => {
+ throw new Error('Linear attachmentCreate reported failure');
+ },
+ });
+ await h.run();
+ expect(h.logs.some((m) => m.includes('Resend message msg_123'))).toBe(true);
+ });
+
+ test('a send that fails writes no marker and is left for the next run', async () => {
+ const h = emailHarness({
+ live: true,
+ postReply: async () => {
+ throw new Error('Resend returned HTTP 503: unavailable');
+ },
+ });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.errored).toEqual([
+ expect.objectContaining({ identifier: 'PRD-7539', disposition: 'retried-next-run' }),
+ ]);
+ });
+
+ test('the marker is keyed on the lowercased address, so a hand-written one matches', async () => {
+ const marker = notificationMarkerUrl({ version: '0.36.0', originUrl: MAILTO });
+ const h = emailHarness({
+ live: true,
+ listCandidates: async () => [
+ candidate({
+ attachmentUrls: [GH_PULL, marker],
+ contacts: [{ ...CONTACT, address: '[email protected]' }],
+ }),
+ ],
+ });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'already-notified' }]);
+ });
+
+ test("one address that fails does not stop the ticket's other addresses", async () => {
+ const SAM = 'mailto:[email protected]';
+ const h = emailHarness({
+ live: true,
+ listCandidates: async () => [
+ candidate({
+ attachmentUrls: [GH_PULL],
+ contacts: [CONTACT, { address: '[email protected]', reportIdentifier: 'PRD-9945' }],
+ }),
+ ],
+ postReply: async (origin) => {
+ if (origin.url === MAILTO) throw new Error('Resend returned HTTP 422: invalid to');
+ h.writes.push({ kind: 'post', origin: origin.url });
+ return { id: 'msg_9' };
+ },
+ });
+ const result = await h.run();
+ expect(h.writes.map((w) => [w.kind, w.origin ?? w.url])).toEqual([
+ ['post', SAM],
+ ['mark', notificationMarkerUrl({ version: '0.36.0', originUrl: SAM })],
+ ]);
+ expect(result.errored).toEqual([
+ expect.objectContaining({ identifier: 'PRD-7539', disposition: 'retried-next-run' }),
+ ]);
+ expect(result.errored[0].message).toContain('the contact email from PRD-7539');
+ expect(result.errored[0].message).toContain('on the stable leg for v0.36.0');
+ expect(result.errored[0].message).toContain("attaching that address's marker");
+ });
+
+ test('a marker that fails after the send is left for the next run, not a person', async () => {
+ const h = emailHarness({
+ live: true,
+ recordNotification: async () => {
+ throw new Error('Linear attachmentCreate reported failure');
+ },
+ });
+ const result = await h.run();
+ expect(h.writes.map((w) => w.kind)).toEqual(['post']);
+ expect(result.errored[0].disposition).toBe('retried-next-run');
+ });
+
+ test('a report that also came from a GitHub issue answers both', async () => {
+ const h = emailHarness({
+ live: true,
+ listCandidates: async () => [
+ candidate({ attachmentUrls: [GH_PULL, GH_ISSUE], contacts: [CONTACT] }),
+ ],
+ });
+ await h.run();
+ expect(h.writes.filter((w) => w.kind === 'post').map((w) => w.origin)).toEqual([
+ GH_ISSUE,
+ MAILTO,
+ ]);
+ });
+
+ test('the address is emailed once per release, however many runs see it', async () => {
+ const marker = notificationMarkerUrl({ version: '0.36.0', originUrl: MAILTO });
+ const h = emailHarness({
+ live: true,
+ listCandidates: async () => [
+ candidate({ attachmentUrls: [GH_PULL, marker], contacts: [CONTACT] }),
+ ],
+ });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'already-notified' }]);
+ });
+
+ test('a beta email names the beta and promises a second email', async () => {
+ const h = emailHarness({
+ live: true,
+ channel: 'beta',
+ versionFor: async () => '0.36.0-beta.1',
+ stableVersionFor: async () => null,
+ classifyRelease: makeReleaseWindow({
+ releaseTag: 'v0.36.0-beta.1',
+ channel: 'beta',
+ minimumVersion: '0.35.0-beta.0',
+ }),
+ });
+ await h.run();
+ const post = h.writes.find((w) => w.kind === 'post');
+ expect(post.subject).toBe(
+ 'A fix for your Open Knowledge report PRD-7539 is in beta v0.36.0-beta.1',
+ );
+ expect(post.text).toContain('email you again');
+ });
+
+ test('an email that corrects an unavailable release says so in its subject', async () => {
+ const h = emailHarness({
+ live: true,
+ isPublishedVersion: (version) => version !== '0.35.9',
+ listCandidates: async () => [
+ candidate({
+ attachmentUrls: [
+ GH_PULL,
+ notificationMarkerUrl({ version: '0.35.9', originUrl: MAILTO }),
+ ],
+ contacts: [CONTACT],
+ }),
+ ],
+ });
+ await h.run();
+ expect(h.writes.find((w) => w.kind === 'post').subject).toBe(
+ 'Correction: your Open Knowledge report PRD-7539 is fixed in v0.36.0',
+ );
+ });
+
+ test('an Inkeep address is never emailed', async () => {
+ const h = emailHarness({
+ live: true,
+ listCandidates: async () => [
+ candidate({
+ attachmentUrls: [GH_PULL],
+ contacts: [{ address: '[email protected]', reportIdentifier: 'PRD-7539' }],
+ }),
+ ],
+ });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'internal-reporter' }]);
+ });
+
+ test('an Inkeep address does not stop a reply to the GitHub issue beside it', async () => {
+ const h = emailHarness({
+ live: true,
+ listCandidates: async () => [
+ candidate({
+ attachmentUrls: [GH_PULL, GH_ISSUE],
+ contacts: [{ address: '[email protected]', reportIdentifier: 'PRD-7539' }],
+ }),
+ ],
+ });
+ await h.run();
+ expect(h.writes.filter((w) => w.kind === 'post').map((w) => w.origin)).toEqual([GH_ISSUE]);
+ });
+
+ test('with no mail transport configured the address is left alone, not marked', async () => {
+ const h = emailHarness({ live: true, emailMode: 'off' });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'email-unconfigured' }]);
+ });
+
+ test('a configured key alone previews email while the other channels stay live', async () => {
+ const h = emailHarness({
+ live: true,
+ emailMode: 'dry-run',
+ listCandidates: async () => [
+ candidate({ attachmentUrls: [GH_PULL, GH_ISSUE], contacts: [CONTACT] }),
+ ],
+ });
+ const result = await h.run();
+ expect(h.writes.map((w) => [w.kind, w.origin ?? w.url])).toEqual([
+ ['mark', notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE })],
+ ['post', GH_ISSUE],
+ ]);
+ expect(result.posted.map((p) => [p.origin, p.dryRun])).toEqual([
+ [GH_ISSUE, false],
+ ['the contact email from PRD-7539', true],
+ ]);
+ expect(h.logs.some((m) => m.includes('[dry run] would reply to the contact email'))).toBe(true);
+ });
+
+ test('an email reporter is not shown the internal tickets a fix covers', async () => {
+ const h = emailHarness({
+ live: true,
+ listChildren: async () => [
+ {
+ id: 'a',
+ identifier: 'PRD-7398',
+ stateType: 'completed',
+ labels: ['Bug'],
+ attachmentUrls: [],
+ },
+ ],
+ listCandidates: async () => [
+ candidate({ attachmentUrls: [GH_PULL, GH_ISSUE], contacts: [CONTACT] }),
+ ],
+ });
+ await h.run();
+ const [github, email] = h.writes.filter((w) => w.kind === 'post');
+ expect(github.text).toContain('Covers PRD-7398.');
+ expect(email.text).not.toContain('PRD-7398');
+ });
+
+ test('feedback is answered without a ticket id the sender was never shown', async () => {
+ const h = emailHarness({
+ live: true,
+ listCandidates: async () => [
+ candidate({
+ attachmentUrls: [GH_PULL],
+ contacts: [{ ...CONTACT, reportKind: 'feedback' }],
+ }),
+ ],
+ });
+ await h.run();
+ expect(h.writes.find((w) => w.kind === 'post').subject).toBe(
+ 'What you told us about Open Knowledge is fixed in v0.36.0',
+ );
+ });
+
+ test('an unknown email mode is refused rather than read as off', async () => {
+ await expect(emailHarness({ emailMode: 'yes' }).run()).rejects.toThrow(/emailMode/);
+ });
+
+ test('the run itself names an email origin only by its label', async () => {
+ const dry = emailHarness();
+ expect(leaked(dry, await dry.run())).toBe(false);
+ expect(dry.logs.some((m) => m.includes('[dry run]') && m.includes('PRD-7539'))).toBe(true);
+
+ const live = emailHarness({ live: true });
+ expect(leaked(live, await live.run())).toBe(false);
+ });
+});
+
+describe('keeping addresses out of the public log', () => {
+ test('every form of a known address is scrubbed, whatever its case', () => {
+ const redactor = createRedactor();
+ redactor.add('[email protected]');
+ const marker = notificationMarkerUrl({
+ version: '0.36.0',
+ originUrl: 'mailto:[email protected]',
+ });
+ const scrubbed = redactor.scrub(
+ `failed for [email protected] and ${marker} and jo.reporter%2Bok%40example.com`,
+ );
+ expect(scrubbed).not.toMatch(/jo\.reporter/i);
+ expect(scrubbed).toContain('the contact email');
+ });
+
+ test("both of the run's output sinks scrub what they print", () => {
+ const printed = [];
+ const output = createRunOutput({
+ out: (m) => printed.push(['out', m]),
+ err: (m) => printed.push(['err', m]),
+ });
+ output.redactor.add('[email protected]');
+ output.log('notice for [email protected]');
+ output.error('error for JO%40EXAMPLE.COM');
+ expect(printed).toEqual([
+ ['out', 'notice for the contact email'],
+ ['err', 'error for the contact email'],
+ ]);
+ });
+
+ test('a redactor that knows no address changes nothing', () => {
+ expect(createRedactor().scrub('PRD-7539 at [email protected]')).toBe('PRD-7539 at [email protected]');
+ });
+});
+
+describe('finding the contact email on a ticket', () => {
+ test('a narrow query lists completed and duplicate intake tickets that name the field', () => {
+ expect(CONTACT_EMAIL_QUERY).toContain('state: { type: { in: ["completed", "duplicate"] } }');
+ expect(CONTACT_EMAIL_QUERY).toContain(
+ 'labels: { some: { name: { in: ["ok:intake", "ok:feedback"] } } }',
+ );
+ expect(CONTACT_EMAIL_QUERY).toContain('description: { containsIgnoreCase: "Contact email:" }');
+ expect(CONTACT_EMAIL_QUERY).toContain('relations { nodes { type relatedIssue { id } } }');
+ expect(CANDIDATE_QUERY).not.toContain('description');
+ });
+
+ const raw = (id, description, { duplicateOf, label = 'ok:intake' } = {}) => ({
+ id,
+ identifier: `PRD-${id}`,
+ description,
+ labels: { nodes: [{ name: label }, { name: 'Bug' }] },
+ state: { type: duplicateOf ? 'duplicate' : 'completed' },
+ relations: {
+ nodes: duplicateOf ? [{ type: 'duplicate', relatedIssue: { id: duplicateOf } }] : [],
+ },
+ });
+ const line = (address) => `* Contact email: [${address}](<mailto:${address}>)`;
+ const merge = (raws) =>
+ attachContactEmails(
+ ['1', '2', '3'].map((id) => candidate({ id, identifier: `PRD-${id}` })),
+ raws.map(toContactNode),
+ ).map((c) => c.contacts ?? []);
+
+ test('the address found on a ticket rides on that ticket and on no other', () => {
+ expect(
+ merge([raw('1', line('[email protected]')), raw('3', 'Mentions a Contact email: field only.')]),
+ ).toEqual([
+ [{ address: '[email protected]', reportIdentifier: 'PRD-1', reportKind: 'bug-report' }],
+ [],
+ [],
+ ]);
+ });
+
+ test('a report merged as a duplicate is answered when its canonical ships, under its own id', () => {
+ expect(
+ merge([
+ raw('9', line('[email protected]'), { duplicateOf: '2' }),
+ raw('2', line('[email protected]')),
+ ]),
+ ).toEqual([
+ [],
+ [
+ { address: '[email protected]', reportIdentifier: 'PRD-2', reportKind: 'bug-report' },
+ { address: '[email protected]', reportIdentifier: 'PRD-9', reportKind: 'bug-report' },
+ ],
+ [],
+ ]);
+ });
+
+ test('one address on a canonical and its duplicate is emailed once, under the canonical', () => {
+ expect(
+ merge([
+ raw('9', line('[email protected]'), { duplicateOf: '1' }),
+ raw('1', line('[email protected]')),
+ ])[0],
+ ).toEqual([{ address: '[email protected]', reportIdentifier: 'PRD-1', reportKind: 'bug-report' }]);
+ });
+
+ test('the run lists candidates and contacts together and learns every address to scrub', async () => {
+ const calls = [];
+ const redactor = createRedactor();
+ const merged = await listCandidatesWithContacts({
+ paginate: async (query, toItem) => {
+ calls.push([query, toItem]);
+ return query === CANDIDATE_QUERY
+ ? [candidate({ id: '1', identifier: 'PRD-1' })]
+ : [toItem(raw('1', line('[email protected]')))];
+ },
+ redactor,
+ });
+ expect(calls).toEqual([
+ [CANDIDATE_QUERY, toNode],
+ [CONTACT_EMAIL_QUERY, toContactNode],
+ ]);
+ expect(merged[0].contacts).toEqual([
+ { address: '[email protected]', reportIdentifier: 'PRD-1', reportKind: 'bug-report' },
+ ]);
+ expect(redactor.scrub('[email protected]')).toBe('the contact email');
+ });
+
+ test('an in-app report is a bug report and a feedback ticket is feedback', () => {
+ expect(toContactNode(raw('1', line('[email protected]'))).reportKind).toBe('bug-report');
+ expect(
+ toContactNode(raw('1', line('[email protected]'), { label: 'ok:feedback' })).reportKind,
+ ).toBe('feedback');
+ });
+
+ test('a duplicate that names no canonical rides on nothing', () => {
+ const orphan = raw('9', line('[email protected]'), { duplicateOf: '1' });
+ orphan.relations.nodes = [];
+ expect(merge([orphan])).toEqual([[], [], []]);
+ });
+
+ test('each reporter on a canonical gets their own email, subject and marker', async () => {
+ const h = harness({
+ live: true,
+ emailMode: 'live',
+ listCandidates: async () => [
+ candidate({
+ attachmentUrls: [GH_PULL],
+ contacts: [
+ { address: '[email protected]', reportIdentifier: 'PRD-7539' },
+ { address: '[email protected]', reportIdentifier: 'PRD-9945' },
+ ],
+ }),
+ ],
+ });
+ h.deps.postReply = async (origin, _text, message) =>
+ h.writes.push({ kind: 'post', origin: origin.url, subject: message.subject });
+ await h.run();
+ expect(h.writes.filter((w) => w.kind === 'mark').map((w) => w.url)).toEqual([
+ notificationMarkerUrl({ version: '0.36.0', originUrl: 'mailto:[email protected]' }),
+ notificationMarkerUrl({ version: '0.36.0', originUrl: 'mailto:[email protected]' }),
+ ]);
+ expect(h.writes.filter((w) => w.kind === 'post').map((w) => w.subject)).toEqual([
+ 'Your Open Knowledge report PRD-7539 is fixed in v0.36.0',
+ 'Your Open Knowledge report PRD-9945 is fixed in v0.36.0',
+ ]);
+ });
+});
+
+describe('arming the email leg', () => {
+ test('no key is off, a key alone previews, and only both switches live send', () => {
+ const mode = (resendKey, live, emailModeVariable) =>
+ resolveEmailMode({ resendKey, live, emailModeVariable });
+ expect(mode('', true, 'live')).toBe('off');
+ expect(mode(' ', true, 'live')).toBe('off');
+ expect(mode('re_x', false, undefined)).toBe('dry-run');
+ expect(mode('re_x', true, undefined)).toBe('dry-run');
+ expect(mode('re_x', false, 'live')).toBe('dry-run');
+ expect(mode('re_x', true, 'live')).toBe('live');
+ });
+
+ test('the closing line counts previewed emails apart from what was sent', () => {
+ const summary = runSummary(
+ {
+ dryRun: false,
+ deferred: 0,
+ skipped: [],
+ errored: [],
+ posted: [
+ { origin: GH_ISSUE, dryRun: false, closed: true },
+ { origin: 'the contact email from PRD-1', dryRun: true, closed: false },
+ ],
+ },
+ { linearRequests: 4 },
+ );
+ expect(summary).toMatchObject({ posted: 1, previewed: 1, closed: 1, linearRequests: 4 });
+ expect(
+ runSummary(
+ {
+ dryRun: true,
+ deferred: 0,
+ skipped: [],
+ errored: [],
+ posted: [{ origin: GH_ISSUE, dryRun: true, closed: true }],
+ },
+ { linearRequests: 1 },
+ ),
+ ).toMatchObject({ posted: 0, previewed: 1, closed: 0 });
+ });
+});
+
+describe('the mail transport', () => {
+ const origin = { channel: 'email', url: 'mailto:[email protected]', address: '[email protected]' };
+ const reply = (status, body) => async () => ({
+ ok: status < 300,
+ status,
+ text: async () => JSON.stringify(body),
+ });
+ const send = (fetchImpl, overrides = {}) =>
+ sendReporterEmail({
+ origin,
+ text: 'This shipped.',
+ subject: 'Subject line',
+ idempotencyKey: 'write-back-abc',
+ apiKey: 're_test',
+ fetchImpl,
+ ...overrides,
+ });
+
+ test('sends one plain-text email from the verified sender, keyed, with replies to the team', async () => {
+ const requests = [];
+ const sent = await send(async (url, init) => {
+ requests.push({ url, init });
+ return { ok: true, status: 200, text: async () => '{"id":"msg_1"}' };
+ });
+ expect(sent).toEqual({ id: 'msg_1' });
+ expect(requests).toHaveLength(1);
+ expect(requests[0].url).toBe('https://api.resend.com/emails');
+ expect(requests[0].init.headers.authorization).toBe('Bearer re_test');
+ expect(requests[0].init.headers['idempotency-key']).toBe('write-back-abc');
+ expect(JSON.parse(requests[0].init.body)).toEqual({
+ from: 'OpenKnowledge <[email protected]>',
+ reply_to: '[email protected]',
+ subject: 'Subject line',
+ text: 'This shipped.',
+ });
+ });
+
+ test('a key Resend already used for a send counts as sent', async () => {
+ await expect(
+ send(reply(409, { name: 'invalid_idempotent_request', message: 'used' })),
+ ).resolves.toEqual({ id: null, alreadyAccepted: true });
+ });
+
+ test('a send still in flight under the same key is not counted as sent', async () => {
+ await expect(
+ send(reply(409, { name: 'concurrent_idempotent_requests', message: 'busy' })),
+ ).rejects.toThrow(/HTTP 409/);
+ });
+
+ test('any refused send throws with its status, for the next run to retry', async () => {
+ await expect(send(reply(422, { name: 'invalid_parameter' }))).rejects.toThrow(/HTTP 422/);
+ await expect(send(reply(503, { name: 'internal_server_error' }))).rejects.toThrow(/HTTP 503/);
+ });
+
+ test('no key or no idempotency key is a thrown error, never an unkeyed send', async () => {
+ await expect(send(fetch, { apiKey: '' })).rejects.toThrow(/RESEND_API_KEY/);
+ await expect(send(fetch, { idempotencyKey: '' })).rejects.toThrow(/idempotency key/);
+ });
+});
+
describe('changeset parsing', () => {
test('the bump block is stripped and the release note is what remains', () => {
const parsed = parseChangeset(
diff --git a/.github/workflows/write-back.yml b/.github/workflows/write-back.yml
index 680f150bb..2a09a5f0c 100644
--- a/.github/workflows/write-back.yml
+++ b/.github/workflows/write-back.yml
@@ -39,6 +39,10 @@ name: Reporter Write-Back
# without performing a single write. Live posting therefore needs two
# deliberate operator actions, so wiring up credentials cannot arm
# reporter-facing posts by accident. Both steps are in RELEASES.md.
+# Email has its own pair on top of those: with no RESEND_API_KEY contact
+# emails are read but never used as a reply channel; with the key they are
+# previewed; they are sent only when WRITE_BACK_EMAIL_MODE is also live
+# alongside WRITE_BACK_MODE.
on:
schedule:
@@ -145,4 +149,6 @@ jobs:
WRITE_BACK_MODE: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run && 'dry-run' || vars.WRITE_BACK_MODE }}
DISCORD_NOTIFY_URL: ${{ secrets.DISCORD_NOTIFY_URL }}
DISCORD_NOTIFY_TOKEN: ${{ secrets.DISCORD_NOTIFY_TOKEN }}
+ RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+ WRITE_BACK_EMAIL_MODE: ${{ vars.WRITE_BACK_EMAIL_MODE }}
run: node .github/scripts/write-back.mjs
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index 4346b5f2b..c9f8c3700 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -427,9 +427,9 @@ None of your content, by default. Everything above is written to your own disk.
| What | When | Where it goes |
| --- | --- | --- |
| Diagnostic bundle | Only when you run `ok diagnose bundle` (you can inspect it first). On macOS it also carries the crash reports the OS recorded for this app and its helper processes (listed above), which are machine-wide rather than project-scoped; only this app's are collected, never another application's, though a report of ours still names the processes it was running alongside, and the summary printed before the zip is written says what that search found even when the answer is nothing. On every platform it also carries the past week of the operating system's records of this app being ended from outside (listed above), and the same summary says what that read found | Wherever you send it |
-| In-app bug report | Only when you click **Send** in the desktop app's **Help → Report a bug…** dialog, or the `Cmd+Shift+D` / `Ctrl+Shift+D` shortcut that opens the same dialog — it builds a secret-redacted zip you can reveal and inspect first, and nothing is sent without that explicit click. The zip carries a picture of the app window unless you uncheck **Screenshot** in that dialog, and the preview there is the picture that would be sent. You can also attach up to three images by dropping them on the **What happened?** box, pasting them anywhere in the dialog (`Cmd+V` / `Ctrl+V`), or browsing with the paperclip in that box. Neither these images nor the screenshot are scanned or redacted, so review them before sending. A report started from an agent chat's **Report a problem with this chat…** also carries, unless you uncheck **This conversation**, the newest 4 MB of that chat's messages, tool calls, and their output, and the chat's metadata file, which names the chat's title, the project folder's path, the document the chat started from, and the agent and its settings. Known secrets are scrubbed from both. Images and other binary content in the chat, including images pasted into a message, are replaced by a note of their type and size, while text files attached to a message are included and scrubbed the same way. If the chat's messages can't be added, the review step says so and the report goes without the conversation. If only the metadata file can't be read, the report carries the messages without it, and the review step doesn't say so. A report started from the command palette, the Help popover, the Windows and Linux menu bar, or an agent chat's **Settings** menu photographs the screen with that palette or menu left out, and carries no marker, because the pointer was only choosing the command. To photograph the command palette itself, press the shortcut while it is open. Every other report you start yourself photographs the screen as it is, so an open menu or another person's document visible at the time is in the picture, and carries a marker drawn where your pointer was, since a screenshot never includes the cursor. No marker is drawn either if the pointer has not moved since the window loaded, or has since left the window. The invitation that appears on its own after a crash is the exception to all of this: it carries no picture at all. When the app holds a crash dump, the same dialog adds a **Crash dump** checkbox. It starts checked on the invitation that follows a crash with a dump available, and unchecked on a report you open yourself. A crash dump is a memory snapshot that can contain document content and can't be redacted, so it is attached only if that box is checked when you create the report, and you review the result before anything is sent. The invitation attaches the dump of the crash it was raised for, never a newer one; if that dump can't be added, the review step says so and the report goes without it. On macOS the zip also carries the update helper's install log (listed above), which is machine-wide rather than project-scoped; the zip's own README names it and says where it came from. At the **Detailed diagnostics** level — pre-checked on the invitation that follows a crash — it additionally carries the crash reports macOS itself recorded for this app and its helpers (also listed above), which are machine-wide for the same reason and named in the same README; only this app's are collected, never another application's, though a report of ours still names the processes it was running alongside, and the zip always says what that search found even when the answer is nothing. On every platform the same level also adds the past week of the operating system's records of this app being ended from outside (also listed above), listed in `manifest.json` for a project's zip and named in the same README for a system-wide zip whenever records were kept. The zip also carries a short send history of the bug reports previously generated on this machine — when each was generated and whether sending it succeeded — which is what makes a report that failed to send diagnosable at all. That history is machine-wide too, so it names the other projects you have filed reports from; it carries no document content, and the README names it the same way | Send uploads the zip to the bug-report intake: `openknowledge.ai` unless [`OK_BUG_REPORT_INTAKE_URL`](./configuration.mdx#environment-variables) points elsewhere. If the upload fails, Send falls back to a prefilled email draft to [email protected] that you send yourself, naming the zip to attach |
-| Uninstall feedback | Only if you answer the optional "Before you go" screen or prompt. The macOS desktop asks after you confirm removal, before the app quits and cleanup starts; feedback can be sent even if cleanup later fails. Interactive `ok uninstall` asks only after successful cleanup. Skipping sends nothing; CLI runs with `--yes`, `--json`, or non-interactive input never ask | `openknowledge.ai/api/feedback` — the reason you picked, your note, your email address if you gave one, plus the app version and platform. It files one ticket for the team; nothing from your notes is included |
-| Feedback form | Only when you click **Send** in the feedback form, opened from **Help → Send feedback**, the command palette's **Send feedback** command, or the feedback card in the window's bottom-left corner. Images you drop on, paste into, or attach to the message box go with it; like bug report images, they are not scanned or redacted | `openknowledge.ai/api/feedback` — your rating, the reasons you picked, your note, your email address if you gave one, up to three attached images, plus the app version and platform. In the desktop app the images upload first to the bug-report intake (`openknowledge.ai` unless [`OK_BUG_REPORT_INTAKE_URL`](./configuration.mdx#environment-variables) points elsewhere) and the feedback carries links to them. If an image upload fails, the images go inline with the feedback to `openknowledge.ai/api/feedback` instead |
+| In-app bug report | Only when you click **Send** in the desktop app's **Help → Report a bug…** dialog, or the `Cmd+Shift+D` / `Ctrl+Shift+D` shortcut that opens the same dialog — it builds a secret-redacted zip you can reveal and inspect first, and nothing is sent without that explicit click. The zip carries a picture of the app window unless you uncheck **Screenshot** in that dialog, and the preview there is the picture that would be sent. You can also attach up to three images by dropping them on the **What happened?** box, pasting them anywhere in the dialog (`Cmd+V` / `Ctrl+V`), or browsing with the paperclip in that box. Neither these images nor the screenshot are scanned or redacted, so review them before sending. A report started from an agent chat's **Report a problem with this chat…** also carries, unless you uncheck **This conversation**, the newest 4 MB of that chat's messages, tool calls, and their output, and the chat's metadata file, which names the chat's title, the project folder's path, the document the chat started from, and the agent and its settings. Known secrets are scrubbed from both. Images and other binary content in the chat, including images pasted into a message, are replaced by a note of their type and size, while text files attached to a message are included and scrubbed the same way. If the chat's messages can't be added, the review step says so and the report goes without the conversation. If only the metadata file can't be read, the report carries the messages without it, and the review step doesn't say so. A report started from the command palette, the Help popover, the Windows and Linux menu bar, or an agent chat's **Settings** menu photographs the screen with that palette or menu left out, and carries no marker, because the pointer was only choosing the command. To photograph the command palette itself, press the shortcut while it is open. Every other report you start yourself photographs the screen as it is, so an open menu or another person's document visible at the time is in the picture, and carries a marker drawn where your pointer was, since a screenshot never includes the cursor. No marker is drawn either if the pointer has not moved since the window loaded, or has since left the window. The invitation that appears on its own after a crash is the exception to all of this: it carries no picture at all. When the app holds a crash dump, the same dialog adds a **Crash dump** checkbox. It starts checked on the invitation that follows a crash with a dump available, and unchecked on a report you open yourself. A crash dump is a memory snapshot that can contain document content and can't be redacted, so it is attached only if that box is checked when you create the report, and you review the result before anything is sent. The invitation attaches the dump of the crash it was raised for, never a newer one; if that dump can't be added, the review step says so and the report goes without it. On macOS the zip also carries the update helper's install log (listed above), which is machine-wide rather than project-scoped; the zip's own README names it and says where it came from. At the **Detailed diagnostics** level — pre-checked on the invitation that follows a crash — it additionally carries the crash reports macOS itself recorded for this app and its helpers (also listed above), which are machine-wide for the same reason and named in the same README; only this app's are collected, never another application's, though a report of ours still names the processes it was running alongside, and the zip always says what that search found even when the answer is nothing. On every platform the same level also adds the past week of the operating system's records of this app being ended from outside (also listed above), listed in `manifest.json` for a project's zip and named in the same README for a system-wide zip whenever records were kept. The zip also carries a short send history of the bug reports previously generated on this machine — when each was generated and whether sending it succeeded — which is what makes a report that failed to send diagnosable at all. That history is machine-wide too, so it names the other projects you have filed reports from; it carries no document content, and the README names it the same way | Send uploads the zip to the bug-report intake: `openknowledge.ai` unless [`OK_BUG_REPORT_INTAKE_URL`](./configuration.mdx#environment-variables) points elsewhere. If the upload fails, Send falls back to a prefilled email draft to [email protected] that you send yourself, naming the zip to attach. If you gave an email address, OpenKnowledge also emails it when a fix for what you reported reaches a stable release, and first when it reaches a beta if it ships in one before stable, from `[email protected]` through its mail provider (Resend); replies go to the team |
+| Uninstall feedback | Only if you answer the optional "Before you go" screen or prompt. The macOS desktop asks after you confirm removal, before the app quits and cleanup starts; feedback can be sent even if cleanup later fails. Interactive `ok uninstall` asks only after successful cleanup. Skipping sends nothing; CLI runs with `--yes`, `--json`, or non-interactive input never ask | `openknowledge.ai/api/feedback` — the reason you picked, your note, your email address if you gave one, plus the app version and platform. It files one ticket for the team; nothing from your notes is included. If you gave an email address, OpenKnowledge also emails it when a fix for what you reported reaches a stable release, and first when it reaches a beta if it ships in one before stable, from `[email protected]` through its mail provider (Resend); replies go to the team |
+| Feedback form | Only when you click **Send** in the feedback form, opened from **Help → Send feedback**, the command palette's **Send feedback** command, or the feedback card in the window's bottom-left corner. Images you drop on, paste into, or attach to the message box go with it; like bug report images, they are not scanned or redacted | `openknowledge.ai/api/feedback` — your rating, the reasons you picked, your note, your email address if you gave one, up to three attached images, plus the app version and platform. In the desktop app the images upload first to the bug-report intake (`openknowledge.ai` unless [`OK_BUG_REPORT_INTAKE_URL`](./configuration.mdx#environment-variables) points elsewhere) and the feedback carries links to them. If an image upload fails, the images go inline with the feedback to `openknowledge.ai/api/feedback` instead. If you gave an email address, OpenKnowledge also emails it when a fix for what you reported reaches a stable release, and first when it reaches a beta if it ships in one before stable, from `[email protected]` through its mail provider (Resend); replies go to the team |
| Semantic search embeddings | Only when you enable [semantic search](./configuration.mdx#semantic-search) **and** set a key — off by default | Your configured embeddings provider (OpenAI by default) |
| GitHub sync / share | When you sync, clone, publish, or share | GitHub |
| Update check | Automatically — on launch and periodically while the desktop app runs | OpenKnowledge update service (`openknowledge.ai/updates`), which redirects to GitHub; sends the app version and channel |