crashrelay 0.1.0

package/dist/dedup.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCache = readCache;
+exports.writeCache = writeCache;
+exports.decide = decide;
+exports.recordCreate = recordCreate;
+exports.recordSeenAgain = recordSeenAgain;
+const node_fs_1 = require("node:fs");
+async function readCache(path) {
+    try {
+        const raw = await node_fs_1.promises.readFile(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.entries !== 'object' || parsed.entries === null)
+            throw new Error('malformed cache');
+        return { entries: parsed.entries };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { entries: {} };
+        throw new Error(`Could not read dedup cache at ${path}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/** Writes via a temp file + rename so a reader never observes a partially-written (truncated/corrupt) cache file, even under concurrent access. */
+async function writeCache(path, cache) {
+    const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await node_fs_1.promises.writeFile(tmpPath, JSON.stringify(cache, null, 2) + '\n', 'utf8');
+    await node_fs_1.promises.rename(tmpPath, path);
+}
+/**
+ * Caps tickets to at most one per fingerprint per cooldown window — not "at
+ * most one ticket ever". Within the window, a recurrence gets a comment on
+ * the existing ticket (throttled separately so a tight crash loop doesn't
+ * spam comments either), not a fresh ticket.
+ */
+function decide(cache, fp, options) {
+    const now = (options.now ?? (() => new Date()))();
+    const entry = cache.entries[fp];
+    if (!entry || new Date(entry.cooldownUntil) <= now) {
+        return { action: 'create' };
+    }
+    const lastComment = entry.lastCommentAt ? new Date(entry.lastCommentAt) : undefined;
+    const commentCooldownMs = options.commentCooldownMinutes * 60 * 1000;
+    if (!lastComment || now.getTime() - lastComment.getTime() >= commentCooldownMs) {
+        return { action: 'comment', entry };
+    }
+    return { action: 'skip', entry };
+}
+function recordCreate(cache, fp, ticket, options) {
+    const now = (options.now ?? (() => new Date()))();
+    const cooldownUntil = new Date(now.getTime() + options.cooldownHours * 60 * 60 * 1000);
+    const entry = {
+        firstSeenAt: now.toISOString(),
+        lastSeenAt: now.toISOString(),
+        count: 1,
+        cooldownUntil: cooldownUntil.toISOString(),
+        ticket,
+    };
+    return { entries: { ...cache.entries, [fp]: entry } };
+}
+function recordSeenAgain(cache, fp, options, commented) {
+    const now = (options.now ?? (() => new Date()))();
+    const existing = cache.entries[fp];
+    if (!existing)
+        return cache;
+    const entry = {
+        ...existing,
+        lastSeenAt: now.toISOString(),
+        count: existing.count + 1,
+        lastCommentAt: commented ? now.toISOString() : existing.lastCommentAt,
+    };
+    return { entries: { ...cache.entries, [fp]: entry } };
+}

package/dist/fetcher.d.ts

@@ -0,0 +1,10 @@
+export type Fetcher = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export declare const realFetcher: Fetcher;

package/dist/fetcher.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.realFetcher = void 0;
+const realFetcher = (url, init) => globalThis.fetch(url, init);
+exports.realFetcher = realFetcher;

package/dist/fingerprint.d.ts

@@ -0,0 +1,7 @@
+import type { Defect } from './types';
+/** Collapses variable data (IDs, timestamps, addresses) so repeated errors with different payloads hash identically. */
+export declare function normalizeMessage(message: string): string;
+/** Keeps only function name + relative-ish file path from the top N application frames, dropping line/column so unrelated line shifts don't fragment the fingerprint. */
+export declare function normalizeStack(stack: string | undefined, maxFrames?: number): string;
+export declare function fingerprint(defect: Defect): string;
+export declare function fingerprintLogLine(matcherId: string, line: string): string;

package/dist/fingerprint.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeMessage = normalizeMessage;
+exports.normalizeStack = normalizeStack;
+exports.fingerprint = fingerprint;
+exports.fingerprintLogLine = fingerprintLogLine;
+const node_crypto_1 = require("node:crypto");
+const UUID_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+const HEX_ADDR_RE = /\b0x[0-9a-f]{4,}\b/gi;
+const ISO_TIMESTAMP_RE = /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?\b/g;
+const LONG_NUMBER_RE = /\b\d{4,}\b/g;
+/** Collapses variable data (IDs, timestamps, addresses) so repeated errors with different payloads hash identically. */
+function normalizeMessage(message) {
+    return message
+        .replace(UUID_RE, '<uuid>')
+        .replace(HEX_ADDR_RE, '<addr>')
+        .replace(ISO_TIMESTAMP_RE, '<timestamp>')
+        .replace(LONG_NUMBER_RE, '<num>')
+        .trim();
+}
+const STACK_FRAME_RE = /^\s*at\s+(?:(.+?)\s+\()?(.+?):\d+:\d+\)?$/;
+/**
+ * Frames from Node's own internals (`node:internal/...`, event-loop/
+ * microtask-queue plumbing like `processTicksAndRejections`). Whether these
+ * trail the real stack depends on incidental async/microtask timing at the
+ * moment the Error was constructed, not on the actual bug — leaving them in
+ * would make the same logical crash hash differently between occurrences
+ * and silently defeat dedup.
+ */
+const INTERNAL_FRAME_RE = /node:internal|\bprocessTicksAndRejections\b|\binternal\/(?:process|timers|modules)\//;
+/** Keeps only function name + relative-ish file path from the top N application frames, dropping line/column so unrelated line shifts don't fragment the fingerprint. */
+function normalizeStack(stack, maxFrames = 5) {
+    if (!stack)
+        return '';
+    const lines = stack
+        .split('\n')
+        .slice(1)
+        .filter((line) => !INTERNAL_FRAME_RE.test(line))
+        .slice(0, maxFrames);
+    return lines
+        .map((line) => {
+        const match = STACK_FRAME_RE.exec(line.trim());
+        if (!match)
+            return line.trim();
+        const [, fn, file] = match;
+        const shortFile = file.split('/').slice(-2).join('/');
+        return `${fn ?? '<anonymous>'}@${shortFile}`;
+    })
+        .join('|');
+}
+function fingerprint(defect) {
+    const parts = [defect.type, normalizeMessage(defect.message), normalizeStack(defect.stack)];
+    return (0, node_crypto_1.createHash)('sha256').update(parts.join('|')).digest('hex');
+}
+function fingerprintLogLine(matcherId, line) {
+    return (0, node_crypto_1.createHash)('sha256').update(`${matcherId}|${normalizeMessage(line)}`).digest('hex');
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from './types';
+export { loadConfig, ConfigError } from './config';
+export { realFetcher } from './fetcher';
+export type { Fetcher } from './fetcher';
+export { resolveProviders } from './providers';
+export type { TicketProvider } from './providers/types';
+export { createPipeline } from './pipeline';
+export type { Pipeline } from './pipeline';
+export { installCrashHandlers } from './collectors/processCrash';
+export type { CrashTarget, DefectHandler, InstallCrashHandlersOptions } from './collectors/processCrash';
+export { httpStatusMiddleware, expressErrorHandler, reportDefect } from './collectors/httpErrors';
+export { tailLog } from './collectors/logTail';
+export { createIngestionServer } from './ingestion/server';
+export { startDaemon } from './daemon';
+export type { DaemonHandle } from './daemon';
+export { fingerprint, fingerprintLogLine } from './fingerprint';

package/dist/index.js

@@ -0,0 +1,42 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fingerprintLogLine = exports.fingerprint = exports.startDaemon = exports.createIngestionServer = exports.tailLog = exports.reportDefect = exports.expressErrorHandler = exports.httpStatusMiddleware = exports.installCrashHandlers = exports.createPipeline = exports.resolveProviders = exports.realFetcher = exports.ConfigError = exports.loadConfig = void 0;
+__exportStar(require("./types"), exports);
+var config_1 = require("./config");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_1.ConfigError; } });
+var fetcher_1 = require("./fetcher");
+Object.defineProperty(exports, "realFetcher", { enumerable: true, get: function () { return fetcher_1.realFetcher; } });
+var providers_1 = require("./providers");
+Object.defineProperty(exports, "resolveProviders", { enumerable: true, get: function () { return providers_1.resolveProviders; } });
+var pipeline_1 = require("./pipeline");
+Object.defineProperty(exports, "createPipeline", { enumerable: true, get: function () { return pipeline_1.createPipeline; } });
+var processCrash_1 = require("./collectors/processCrash");
+Object.defineProperty(exports, "installCrashHandlers", { enumerable: true, get: function () { return processCrash_1.installCrashHandlers; } });
+var httpErrors_1 = require("./collectors/httpErrors");
+Object.defineProperty(exports, "httpStatusMiddleware", { enumerable: true, get: function () { return httpErrors_1.httpStatusMiddleware; } });
+Object.defineProperty(exports, "expressErrorHandler", { enumerable: true, get: function () { return httpErrors_1.expressErrorHandler; } });
+Object.defineProperty(exports, "reportDefect", { enumerable: true, get: function () { return httpErrors_1.reportDefect; } });
+var logTail_1 = require("./collectors/logTail");
+Object.defineProperty(exports, "tailLog", { enumerable: true, get: function () { return logTail_1.tailLog; } });
+var server_1 = require("./ingestion/server");
+Object.defineProperty(exports, "createIngestionServer", { enumerable: true, get: function () { return server_1.createIngestionServer; } });
+var daemon_1 = require("./daemon");
+Object.defineProperty(exports, "startDaemon", { enumerable: true, get: function () { return daemon_1.startDaemon; } });
+var fingerprint_1 = require("./fingerprint");
+Object.defineProperty(exports, "fingerprint", { enumerable: true, get: function () { return fingerprint_1.fingerprint; } });
+Object.defineProperty(exports, "fingerprintLogLine", { enumerable: true, get: function () { return fingerprint_1.fingerprintLogLine; } });

package/dist/ingestion/auth.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage } from 'node:http';
+/**
+ * `timingSafeEqual` requires equal-length buffers, so both sides are hashed
+ * to a fixed 32 bytes first — this also means an attacker learns nothing
+ * from a length mismatch on the raw token.
+ */
+export declare function checkBearerToken(req: IncomingMessage, expectedToken: string): boolean;

package/dist/ingestion/auth.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkBearerToken = checkBearerToken;
+const node_crypto_1 = require("node:crypto");
+function digest(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value).digest();
+}
+/**
+ * `timingSafeEqual` requires equal-length buffers, so both sides are hashed
+ * to a fixed 32 bytes first — this also means an attacker learns nothing
+ * from a length mismatch on the raw token.
+ */
+function checkBearerToken(req, expectedToken) {
+    const header = req.headers.authorization;
+    if (!header?.startsWith('Bearer '))
+        return false;
+    const provided = header.slice('Bearer '.length).trim();
+    if (!provided)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(digest(provided), digest(expectedToken));
+}

package/dist/ingestion/cors.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Reflects the request's Origin header into Access-Control-Allow-Origin
+ * only when it's in the configured allowlist. Returns true if this request
+ * was a handled OPTIONS preflight (caller should stop processing).
+ */
+export declare function applyCors(req: IncomingMessage, res: ServerResponse, allowedOrigins: string[]): boolean;

package/dist/ingestion/cors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyCors = applyCors;
+/**
+ * Reflects the request's Origin header into Access-Control-Allow-Origin
+ * only when it's in the configured allowlist. Returns true if this request
+ * was a handled OPTIONS preflight (caller should stop processing).
+ */
+function applyCors(req, res, allowedOrigins) {
+    const origin = req.headers.origin;
+    if (origin && allowedOrigins.includes(origin)) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
+    }
+    if (req.method === 'OPTIONS') {
+        res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        res.statusCode = 204;
+        res.end();
+        return true;
+    }
+    return false;
+}

package/dist/ingestion/rateLimit.d.ts

@@ -0,0 +1,11 @@
+export interface RateLimiterOptions {
+    windowMs?: number;
+    max?: number;
+    now?: () => number;
+}
+export interface RateLimiter {
+    /** Returns true if the request for `key` is allowed under the current window. */
+    allow(key: string): boolean;
+}
+/** In-memory sliding-window limiter, keyed by an arbitrary string (typically source IP). */
+export declare function createRateLimiter(options?: RateLimiterOptions): RateLimiter;

package/dist/ingestion/rateLimit.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimiter = createRateLimiter;
+/** In-memory sliding-window limiter, keyed by an arbitrary string (typically source IP). */
+function createRateLimiter(options = {}) {
+    const windowMs = options.windowMs ?? 60000;
+    const max = options.max ?? 30;
+    const now = options.now ?? (() => Date.now());
+    const hits = new Map();
+    return {
+        allow(key) {
+            const currentTime = now();
+            const windowStart = currentTime - windowMs;
+            const timestamps = (hits.get(key) ?? []).filter((t) => t > windowStart);
+            if (timestamps.length >= max) {
+                hits.set(key, timestamps);
+                return false;
+            }
+            timestamps.push(currentTime);
+            hits.set(key, timestamps);
+            return true;
+        },
+    };
+}

package/dist/ingestion/server.d.ts

@@ -0,0 +1,15 @@
+import { type Server } from 'node:http';
+import type { IngestionConfig } from '../types';
+import type { DefectHandler } from '../collectors/processCrash';
+import { type RateLimiter } from './rateLimit';
+export interface IngestionServerOptions {
+    now?: () => Date;
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Exposes POST /report for the crashrelay-browser client SDK and GET
+ * /health for uptime checks. INGESTION_TOKEN is a public "write key" (like
+ * a Sentry DSN, readable in devtools) — its abuse-mitigation is this rate
+ * limiter + the dedup pipeline, not confidentiality.
+ */
+export declare function createIngestionServer(config: IngestionConfig, handler: DefectHandler, options?: IngestionServerOptions): Server;

package/dist/ingestion/server.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIngestionServer = createIngestionServer;
+const node_http_1 = require("node:http");
+const auth_1 = require("./auth");
+const cors_1 = require("./cors");
+const rateLimit_1 = require("./rateLimit");
+const MAX_BODY_BYTES = 16 * 1024;
+function sourceIp(req) {
+    return req.socket.remoteAddress ?? 'unknown';
+}
+async function readBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        total += chunk.length;
+        if (total > MAX_BODY_BYTES)
+            return undefined;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Exposes POST /report for the crashrelay-browser client SDK and GET
+ * /health for uptime checks. INGESTION_TOKEN is a public "write key" (like
+ * a Sentry DSN, readable in devtools) — its abuse-mitigation is this rate
+ * limiter + the dedup pipeline, not confidentiality.
+ */
+function createIngestionServer(config, handler, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const rateLimiter = options.rateLimiter ?? (0, rateLimit_1.createRateLimiter)();
+    return (0, node_http_1.createServer)(async (req, res) => {
+        if ((0, cors_1.applyCors)(req, res, config.allowedOrigins))
+            return;
+        if (req.method === 'GET' && req.url === '/health') {
+            res.statusCode = 200;
+            res.end('ok');
+            return;
+        }
+        if (req.method !== 'POST' || req.url !== '/report') {
+            res.statusCode = 404;
+            res.end();
+            return;
+        }
+        if (!(0, auth_1.checkBearerToken)(req, config.token)) {
+            res.statusCode = 401;
+            res.end();
+            return;
+        }
+        if (!rateLimiter.allow(sourceIp(req))) {
+            res.statusCode = 429;
+            res.end();
+            return;
+        }
+        const raw = await readBody(req);
+        if (raw === undefined) {
+            res.statusCode = 413;
+            res.end();
+            return;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            res.statusCode = 400;
+            res.end();
+            return;
+        }
+        // Respond immediately — the client fired via fetch(keepalive)/sendBeacon and isn't waiting on ticket creation.
+        res.statusCode = 202;
+        res.end();
+        if (payload.message) {
+            const defect = {
+                type: 'client-error',
+                message: payload.message,
+                stack: payload.stack,
+                context: { url: payload.url, userAgent: payload.userAgent },
+                occurredAt: now().toISOString(),
+            };
+            void handler(defect);
+        }
+    });
+}

package/dist/init.d.ts

@@ -0,0 +1,30 @@
+export interface Prompter {
+    checkbox(config: {
+        message: string;
+        choices: Array<{
+            name: string;
+            value: string;
+        }>;
+    }): Promise<string[]>;
+    input(config: {
+        message: string;
+        default?: string;
+    }): Promise<string>;
+    password(config: {
+        message: string;
+    }): Promise<string>;
+    confirm(config: {
+        message: string;
+        default?: boolean;
+    }): Promise<boolean>;
+}
+export interface InitOptions {
+    generateToken?: () => string;
+}
+/**
+ * Prompts for provider credentials and prints an env-var export block —
+ * this never touches the filesystem. The user is responsible for loading
+ * the output into their own process manager / systemd unit / Docker
+ * secrets, which is the only place this tool trusts credentials to live.
+ */
+export declare function runInitWizard(prompter: Prompter, options?: InitOptions): Promise<string>;

package/dist/init.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitWizard = runInitWizard;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Prompts for provider credentials and prints an env-var export block —
+ * this never touches the filesystem. The user is responsible for loading
+ * the output into their own process manager / systemd unit / Docker
+ * secrets, which is the only place this tool trusts credentials to live.
+ */
+async function runInitWizard(prompter, options = {}) {
+    const generateToken = options.generateToken ?? (() => (0, node_crypto_1.randomBytes)(24).toString('hex'));
+    const providers = await prompter.checkbox({
+        message: 'Which ticket provider(s)?',
+        choices: [
+            { name: 'Jira', value: 'jira' },
+            { name: 'GitHub Issues', value: 'github' },
+        ],
+    });
+    if (providers.length === 0) {
+        throw new Error('At least one provider must be selected.');
+    }
+    const lines = [
+        '# --- crashrelay environment variables ---',
+        '# Add these to your process manager / systemd unit / Docker secrets.',
+        '# Do NOT commit this output to source control.',
+    ];
+    if (providers.includes('jira')) {
+        const baseUrl = await prompter.input({ message: 'Jira base URL (e.g. https://yourco.atlassian.net)' });
+        const email = await prompter.input({ message: 'Jira account email' });
+        const apiToken = await prompter.password({ message: 'Jira API token' });
+        const projectKey = await prompter.input({ message: 'Jira project key (e.g. OPS)' });
+        const issueType = await prompter.input({ message: 'Jira issue type', default: 'Bug' });
+        lines.push(`export JIRA_BASE_URL="${baseUrl}"`, `export JIRA_EMAIL="${email}"`, `export JIRA_API_TOKEN="${apiToken}"`, `export JIRA_PROJECT_KEY="${projectKey}"`, `export JIRA_ISSUE_TYPE="${issueType}"`);
+    }
+    if (providers.includes('github')) {
+        const token = await prompter.password({ message: 'GitHub personal access token' });
+        const owner = await prompter.input({ message: 'GitHub repo owner' });
+        const repo = await prompter.input({ message: 'GitHub repo name' });
+        lines.push(`export GITHUB_TOKEN="${token}"`, `export GITHUB_OWNER="${owner}"`, `export GITHUB_REPO="${repo}"`);
+    }
+    const enableIngestion = await prompter.confirm({ message: 'Enable the frontend ingestion endpoint (/report)?', default: true });
+    if (enableIngestion) {
+        const port = await prompter.input({ message: 'Ingestion port', default: '4318' });
+        const allowedOrigins = await prompter.input({ message: 'Allowed CORS origin(s), comma-separated' });
+        const token = generateToken();
+        lines.push(`export INGESTION_TOKEN="${token}"`, `export INGESTION_PORT="${port}"`, `export INGESTION_ALLOWED_ORIGINS="${allowedOrigins}"`);
+    }
+    const dedupCooldownHours = await prompter.input({ message: 'Dedup cooldown hours (skip re-filing the same defect within this window)', default: '24' });
+    lines.push(`export DEDUP_COOLDOWN_HOURS="${dedupCooldownHours}"`);
+    const logPath = await prompter.input({ message: 'Log file path to tail (leave blank to skip)', default: '' });
+    if (logPath) {
+        const logPattern = await prompter.input({ message: 'Log line match pattern', default: 'ERROR' });
+        lines.push(`export LOG_TAIL_PATH="${logPath}"`, `export LOG_TAIL_PATTERN="${logPattern}"`);
+    }
+    lines.push('', '# Next: load these into your environment, then run `crashrelay test-ticket` to verify connectivity.');
+    return lines.join('\n') + '\n';
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,14 @@
+import type { Config } from './types';
+import type { TicketProvider } from './providers/types';
+import type { DefectHandler } from './collectors/processCrash';
+export interface Pipeline {
+    handleDefect: DefectHandler;
+}
+/**
+ * Only the first configured provider actually creates/owns the ticket —
+ * the dedup cache stores one ticket ref per fingerprint, so "create in
+ * every configured provider" would need a different cache shape. If both
+ * Jira and GitHub are configured, Jira takes priority (resolveProviders
+ * order); this is a deliberate v1 simplification, not an oversight.
+ */
+export declare function createPipeline(config: Config, providers: TicketProvider[], now?: () => Date): Pipeline;

package/dist/pipeline.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPipeline = createPipeline;
+const dedup_1 = require("./dedup");
+const fingerprint_1 = require("./fingerprint");
+/**
+ * Only the first configured provider actually creates/owns the ticket —
+ * the dedup cache stores one ticket ref per fingerprint, so "create in
+ * every configured provider" would need a different cache shape. If both
+ * Jira and GitHub are configured, Jira takes priority (resolveProviders
+ * order); this is a deliberate v1 simplification, not an oversight.
+ */
+function createPipeline(config, providers, now = () => new Date()) {
+    const provider = providers[0];
+    // Multiple defects can arrive concurrently (e.g. a burst of frontend error
+    // beacons, or a crash-loop firing faster than one read-modify-write cycle
+    // completes). Without serializing access, two concurrent handlers can both
+    // read the cache before either writes, and the second write silently loses
+    // the first's update — or, worse, race a write of the same file if it were
+    // ever run across multiple processes. This queue only protects a single
+    // process's concurrent calls, not multiple daemon replicas sharing one
+    // cache file (see README limitations).
+    let queue = Promise.resolve();
+    function serialized(fn) {
+        const result = queue.then(fn, fn);
+        queue = result.catch(() => undefined);
+        return result;
+    }
+    async function handleDefect(defect) {
+        if (!provider) {
+            throw new Error('No ticket provider configured — run `crashrelay init` first.');
+        }
+        return serialized(async () => {
+            const fp = (0, fingerprint_1.fingerprint)(defect);
+            const cache = await (0, dedup_1.readCache)(config.cacheFilePath);
+            const options = { cooldownHours: config.dedupCooldownHours, commentCooldownMinutes: config.commentCooldownMinutes, now };
+            const decision = (0, dedup_1.decide)(cache, fp, options);
+            if (decision.action === 'create') {
+                const ticket = await provider.createTicket(defect);
+                await (0, dedup_1.writeCache)(config.cacheFilePath, (0, dedup_1.recordCreate)(cache, fp, ticket, options));
+                return;
+            }
+            if (decision.action === 'comment') {
+                await provider.addComment(decision.entry.ticket, `Seen again (now ${decision.entry.count + 1} times). Last seen: ${defect.occurredAt}`);
+                await (0, dedup_1.writeCache)(config.cacheFilePath, (0, dedup_1.recordSeenAgain)(cache, fp, options, true));
+                return;
+            }
+            // 'skip' — within both the ticket cooldown and the comment cooldown; just tally the occurrence.
+            await (0, dedup_1.writeCache)(config.cacheFilePath, (0, dedup_1.recordSeenAgain)(cache, fp, options, false));
+        });
+    }
+    return { handleDefect };
+}

package/dist/providers/adf.d.ts

@@ -0,0 +1,24 @@
+interface AdfTextNode {
+    type: 'text';
+    text: string;
+}
+interface AdfHardBreak {
+    type: 'hardBreak';
+}
+interface AdfParagraph {
+    type: 'paragraph';
+    content: Array<AdfTextNode | AdfHardBreak>;
+}
+export interface AdfDoc {
+    type: 'doc';
+    version: 1;
+    content: AdfParagraph[];
+}
+/**
+ * Jira Cloud's v3 issue API rejects a plain-text `description` — it must be
+ * Atlassian Document Format. This wraps plain text into the minimal valid
+ * shape: blank lines become paragraph breaks, single newlines become
+ * hardBreak nodes within a paragraph.
+ */
+export declare function textToAdf(text: string): AdfDoc;
+export {};

package/dist/providers/adf.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.textToAdf = textToAdf;
+/**
+ * Jira Cloud's v3 issue API rejects a plain-text `description` — it must be
+ * Atlassian Document Format. This wraps plain text into the minimal valid
+ * shape: blank lines become paragraph breaks, single newlines become
+ * hardBreak nodes within a paragraph.
+ */
+function textToAdf(text) {
+    const paragraphs = text.split(/\n{2,}/).filter((p) => p.length > 0);
+    const content = paragraphs.map((paragraph) => {
+        const lines = paragraph.split('\n');
+        const nodes = [];
+        lines.forEach((line, index) => {
+            if (index > 0)
+                nodes.push({ type: 'hardBreak' });
+            if (line.length > 0)
+                nodes.push({ type: 'text', text: line });
+        });
+        return { type: 'paragraph', content: nodes };
+    });
+    return {
+        type: 'doc',
+        version: 1,
+        content: content.length > 0 ? content : [{ type: 'paragraph', content: [{ type: 'text', text: '' }] }],
+    };
+}

package/dist/providers/format.d.ts

@@ -0,0 +1,3 @@
+import type { Defect } from '../types';
+export declare function buildSummary(defect: Defect): string;
+export declare function buildBody(defect: Defect): string;