crashrelay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SNR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# crashrelay
+
+Catch backend crashes, HTTP 5xx responses, and error-log lines — plus
+frontend JS errors via [`crashrelay-browser`](https://github.com/Rifat024/crashrelay-browser)
+— and auto-file tickets in Jira or GitHub Issues.
+
+## The one thing to understand before using this
+
+**Crash/HTTP-5xx capture is a library you embed in your own app, not a
+process that watches another process from the outside.** A separate daemon
+cannot hook `uncaughtException`/`unhandledRejection` in a *different* OS
+process — that's a Node/OS limitation, not a design choice. So:
+
+- `require('crashrelay').installCrashHandlers(...)` / `httpStatusMiddleware(...)`
+  / `expressErrorHandler(...)` run **inside your own server's process**.
+- `crashrelay start` runs the two pieces that genuinely *can* be a separate
+  always-on daemon: log-file tailing, and the ingestion endpoint that
+  receives frontend error beacons from `crashrelay-browser`.
+
+Both pieces ship in this one package — it's just that "backend crash
+detection" and "standalone daemon" are different things wearing the same
+npm install.
+
+**On "24/7"**: `crashrelay start` is a foreground Node process. Surviving a
+crash, an OOM kill, or a server reboot needs an external supervisor —
+`pm2`, `systemd`, or a Docker restart policy. This package reports crashes;
+it doesn't resurrect its own killed process.
+
+## Install
+
+```bash
+npm install crashrelay
+```
+
+## Setup
+
+```bash
+npx crashrelay init
+```
+
+Interactive wizard — prompts for Jira and/or GitHub Issues credentials, and
+prints an `export KEY="value"` block. **It never writes a file.** Load the
+output into your process manager, systemd unit, or Docker secrets — this
+tool only ever reads credentials from environment variables.
+
+```bash
+npx crashrelay test-ticket          # dry-run connectivity check
+npx crashrelay test-ticket --live   # creates one real test ticket
+```
+
+## Usage
+
+### 1. Embed crash + HTTP-5xx capture in your own app
+
+```ts
+import { installCrashHandlers, loadConfig, resolveProviders, realFetcher, createPipeline } from 'crashrelay';
+
+const config = loadConfig();
+const pipeline = createPipeline(config, resolveProviders(config, realFetcher));
+
+installCrashHandlers(pipeline.handleDefect);
+```
+
+For HTTP 5xx (Express/Connect):
+
+```ts
+import { httpStatusMiddleware, expressErrorHandler } from 'crashrelay';
+
+app.use(httpStatusMiddleware(pipeline.handleDefect)); // status-code-only, works with any framework
+app.use(expressErrorHandler(pipeline.handleDefect));  // captures the actual Error, Express/Connect only — mount last
+```
+
+Fastify doesn't support 4-arg error middleware at all — call `reportDefect`
+directly from `fastify.setErrorHandler()` instead:
+
+```ts
+import { reportDefect } from 'crashrelay';
+fastify.setErrorHandler((err, req) => reportDefect(pipeline.handleDefect, err, { route: req.url }));
+```
+
+### 2. Run the standalone daemon (log tailing + frontend ingestion)
+
+```bash
+npx crashrelay start
+```
+
+Runs under whatever supervisor you use for the rest of your stack (pm2,
+systemd, Docker).
+
+### 3. Check status
+
+```bash
+npx crashrelay status
+```
+
+## Environment variables
+
+| Variable | Required for | Notes |
+| --- | --- | --- |
+| `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`, `JIRA_PROJECT_KEY` | Jira | All four or none |
+| `JIRA_ISSUE_TYPE` | Jira | Default `Bug` |
+| `GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO` | GitHub Issues | All three or none |
+| `INGESTION_TOKEN` | Frontend ingestion | Enables the endpoint when set. Public "write key" (like a Sentry DSN) — not confidential, readable in browser devtools |
+| `INGESTION_PORT` | Frontend ingestion | Default `4318` |
+| `INGESTION_ALLOWED_ORIGINS` | Frontend ingestion | Comma-separated CORS allowlist |
+| `DEDUP_COOLDOWN_HOURS` | — | Default `24` |
+| `COMMENT_COOLDOWN_MINUTES` | — | Default `60` |
+| `LOG_TAIL_PATH`, `LOG_TAIL_PATTERN` | Log tailing | Pattern default `ERROR` |
+
+If both Jira and GitHub are configured, Jira is used — the dedup cache
+stores one ticket per fingerprint, not one per provider, so only the first
+configured provider actually creates/owns tickets.
+
+## Deduplication
+
+Repeated identical crashes don't spam a ticket per occurrence. Each defect
+is fingerprinted (message + top stack frames, with IDs/timestamps/addresses
+normalized out) and checked against a local cache
+(`.crashrelay-dedup-cache.json`):
+
+- New fingerprint, or past its cooldown (`DEDUP_COOLDOWN_HOURS`, default
+  24h) → creates a ticket.
+- Same fingerprint within the cooldown → adds a "seen again ×N" comment on
+  the existing ticket (throttled separately by `COMMENT_COOLDOWN_MINUTES` so
+  a tight crash loop doesn't spam comments either).
+
+This caps tickets **per fingerprint per window** — distinct crash
+signatures each still get their own ticket. If a human closes a ticket and
+the same fingerprint recurs inside the cooldown, v1 comments on the closed
+ticket rather than reopening or filing a new one.
+
+## Frontend errors
+
+Pair with [`crashrelay-browser`](https://github.com/Rifat024/crashrelay-browser):
+
+```ts
+import { initErrorReporter } from 'crashrelay-browser';
+
+initErrorReporter({
+  endpoint: 'https://your-api.example.com/report',
+  token: process.env.CRASHRELAY_INGESTION_TOKEN, // the public write key from `crashrelay init`
+});
+```
+
+## Limitations
+
+- Not a guarantee of 24/7 uptime — that's an infra/supervisor concern layered on top.
+- Log tailing is single-instance; running multiple daemon replicas without a shared store multiplies first-occurrence tickets by replica count.
+- No ticket-status awareness — a closed ticket that recurs within its cooldown gets a comment, not a reopen.
+- `INGESTION_TOKEN` is a public write key, not a secret — its abuse-mitigation is rate-limiting and dedup, not confidentiality.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const prompts_1 = require("@inquirer/prompts");
+const init_1 = require("./init");
+const config_1 = require("./config");
+const providers_1 = require("./providers");
+const fetcher_1 = require("./fetcher");
+const pipeline_1 = require("./pipeline");
+const daemon_1 = require("./daemon");
+const dedup_1 = require("./dedup");
+const program = new commander_1.Command();
+program
+    .name('crashrelay')
+    .description('Catch backend crashes, HTTP 5xx responses, log errors, and frontend JS errors, and auto-file tickets in Jira or GitHub Issues.')
+    .version('0.1.0');
+const realPrompter = { checkbox: prompts_1.checkbox, input: prompts_1.input, password: prompts_1.password, confirm: prompts_1.confirm };
+program
+    .command('init')
+    .description('Interactive setup wizard — prints an environment-variable block, never writes a file.')
+    .action(async () => {
+    const output = await (0, init_1.runInitWizard)(realPrompter);
+    console.log('\n' + output);
+});
+program
+    .command('start')
+    .description('Run the standalone daemon: log-file tailing + the frontend-error ingestion endpoint.')
+    .action(() => {
+    const config = (0, config_1.loadConfig)();
+    const providers = (0, providers_1.resolveProviders)(config, fetcher_1.realFetcher);
+    const pipeline = (0, pipeline_1.createPipeline)(config, providers);
+    (0, daemon_1.startDaemon)(config, pipeline.handleDefect);
+    console.log('[crashrelay] daemon running. Remember: crash/HTTP-5xx capture must be required inside your own app — see the README.');
+});
+program
+    .command('test-ticket')
+    .description('Verify ticket-provider connectivity. Dry-run by default; --live creates one real test ticket.')
+    .option('--live', 'create a real test ticket instead of just checking the connection', false)
+    .action(async (opts) => {
+    const config = (0, config_1.loadConfig)();
+    const providers = (0, providers_1.resolveProviders)(config, fetcher_1.realFetcher);
+    const provider = providers[0];
+    if (!provider) {
+        console.error('No ticket provider configured.');
+        process.exitCode = 1;
+        return;
+    }
+    if (!opts.live) {
+        await provider.checkConnection();
+        console.log(`✓ ${provider.name} connection OK.`);
+        return;
+    }
+    const ticket = await provider.createTicket({
+        type: 'process-crash',
+        message: 'crashrelay test-ticket — safe to close',
+        occurredAt: new Date().toISOString(),
+    });
+    console.log(`✓ Created test ticket: ${ticket.url}`);
+});
+program
+    .command('status')
+    .description('Show the dedup cache: recently seen defects and their tickets.')
+    .action(async () => {
+    const config = (0, config_1.loadConfig)();
+    const cache = await (0, dedup_1.readCache)(config.cacheFilePath);
+    const entries = Object.entries(cache.entries);
+    if (entries.length === 0) {
+        console.log('No defects recorded yet.');
+        return;
+    }
+    for (const [fp, entry] of entries) {
+        console.log(`${fp.slice(0, 12)}  count=${entry.count}  ${entry.ticket.provider}:${entry.ticket.id}  ${entry.ticket.url}`);
+    }
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});

package/dist/collectors/httpErrors.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DefectHandler } from './processCrash';
+export interface HttpErrorOptions {
+    now?: () => Date;
+}
+/**
+ * Status-code-only detection. Works identically across Express/Connect/
+ * Fastify's Node-compat layer because they all share the underlying
+ * `ServerResponse` — genuinely framework-agnostic. Does not capture the
+ * thrown Error object; use `expressErrorHandler` (or the framework's own
+ * error hook) for that.
+ */
+export declare function httpStatusMiddleware(handler: DefectHandler, options?: HttpErrorOptions): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+/**
+ * Express/Connect-style 4-arg error middleware. Fastify does not support
+ * this signature at all — Fastify users must call `reportDefect` directly
+ * from `fastify.setErrorHandler()` instead.
+ */
+export declare function expressErrorHandler(handler: DefectHandler, options?: HttpErrorOptions): (err: Error, req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+/** For frameworks (e.g. Fastify) with their own error-hook signature — call this directly from that hook. */
+export declare function reportDefect(handler: DefectHandler, err: Error, context?: Record<string, string | number | undefined>, options?: HttpErrorOptions): void;

package/dist/collectors/httpErrors.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpStatusMiddleware = httpStatusMiddleware;
+exports.expressErrorHandler = expressErrorHandler;
+exports.reportDefect = reportDefect;
+function buildStatusDefect(req, res, now) {
+    return {
+        type: 'http-5xx',
+        message: `HTTP ${res.statusCode} ${req.method ?? 'UNKNOWN'} ${req.url ?? ''}`.trim(),
+        context: { method: req.method, url: req.url, statusCode: res.statusCode },
+        occurredAt: now().toISOString(),
+    };
+}
+/**
+ * Status-code-only detection. Works identically across Express/Connect/
+ * Fastify's Node-compat layer because they all share the underlying
+ * `ServerResponse` — genuinely framework-agnostic. Does not capture the
+ * thrown Error object; use `expressErrorHandler` (or the framework's own
+ * error hook) for that.
+ */
+function httpStatusMiddleware(handler, options = {}) {
+    const now = options.now ?? (() => new Date());
+    return (req, res, next) => {
+        res.on('finish', () => {
+            if (res.statusCode >= 500)
+                void handler(buildStatusDefect(req, res, now));
+        });
+        next();
+    };
+}
+/**
+ * Express/Connect-style 4-arg error middleware. Fastify does not support
+ * this signature at all — Fastify users must call `reportDefect` directly
+ * from `fastify.setErrorHandler()` instead.
+ */
+function expressErrorHandler(handler, options = {}) {
+    const now = options.now ?? (() => new Date());
+    return (err, req, res, next) => {
+        void handler({
+            type: 'http-5xx',
+            message: err.message,
+            stack: err.stack,
+            context: { method: req.method, url: req.url, statusCode: res.statusCode },
+            occurredAt: now().toISOString(),
+        });
+        next(err);
+    };
+}
+/** For frameworks (e.g. Fastify) with their own error-hook signature — call this directly from that hook. */
+function reportDefect(handler, err, context, options = {}) {
+    const now = options.now ?? (() => new Date());
+    void handler({ type: 'http-5xx', message: err.message, stack: err.stack, context, occurredAt: now().toISOString() });
+}

package/dist/collectors/logTail.d.ts

@@ -0,0 +1,27 @@
+import type { DefectHandler } from './processCrash';
+export interface FileState {
+    offset: number;
+    inode: number;
+}
+export interface PollResult {
+    lines: string[];
+    state: FileState;
+}
+/**
+ * Reads only the bytes appended since `state.offset`. Detects rotation
+ * (inode changed — the old file was replaced) and truncation (size shrank
+ * below the last offset) and resets to the start of the new/truncated file
+ * in either case — naive tailing breaks silently after logrotate/Docker log
+ * truncation otherwise, and a crash-looping service is exactly the kind
+ * whose logs rotate often.
+ */
+export declare function readNewLines(path: string, state: FileState): Promise<PollResult>;
+export declare function buildMatcher(pattern: string | RegExp): (line: string) => boolean;
+export interface TailLogOptions {
+    pollIntervalMs?: number;
+    now?: () => Date;
+    /** Injected in tests to bypass the real filesystem entirely. */
+    poll?: (state: FileState) => Promise<PollResult>;
+}
+/** Starts polling `path` for new lines matching `pattern`, reporting each match as a `log-error` defect. Returns a dispose function. */
+export declare function tailLog(path: string, pattern: string | RegExp, handler: DefectHandler, options?: TailLogOptions): () => void;

package/dist/collectors/logTail.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readNewLines = readNewLines;
+exports.buildMatcher = buildMatcher;
+exports.tailLog = tailLog;
+const node_fs_1 = require("node:fs");
+/**
+ * Reads only the bytes appended since `state.offset`. Detects rotation
+ * (inode changed — the old file was replaced) and truncation (size shrank
+ * below the last offset) and resets to the start of the new/truncated file
+ * in either case — naive tailing breaks silently after logrotate/Docker log
+ * truncation otherwise, and a crash-looping service is exactly the kind
+ * whose logs rotate often.
+ */
+async function readNewLines(path, state) {
+    const stat = await node_fs_1.promises.stat(path);
+    let offset = state.offset;
+    if (stat.ino !== state.inode || stat.size < offset) {
+        offset = 0;
+    }
+    if (stat.size <= offset) {
+        return { lines: [], state: { offset, inode: stat.ino } };
+    }
+    const handle = await node_fs_1.promises.open(path, 'r');
+    try {
+        const length = stat.size - offset;
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, offset);
+        const text = buffer.toString('utf8');
+        const lastNewline = text.lastIndexOf('\n');
+        if (lastNewline === -1) {
+            // No complete line yet — don't advance the offset past a partial line.
+            return { lines: [], state: { offset, inode: stat.ino } };
+        }
+        const complete = text.slice(0, lastNewline);
+        const lines = complete.split('\n').filter((line) => line.length > 0);
+        const newOffset = offset + Buffer.byteLength(text.slice(0, lastNewline + 1), 'utf8');
+        return { lines, state: { offset: newOffset, inode: stat.ino } };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function buildMatcher(pattern) {
+    if (typeof pattern === 'string') {
+        return (line) => line.includes(pattern);
+    }
+    return (line) => pattern.test(line);
+}
+/** Starts polling `path` for new lines matching `pattern`, reporting each match as a `log-error` defect. Returns a dispose function. */
+function tailLog(path, pattern, handler, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 1000;
+    const now = options.now ?? (() => new Date());
+    const matches = buildMatcher(pattern);
+    const matcherId = typeof pattern === 'string' ? pattern : pattern.source;
+    const poll = options.poll ?? ((state) => readNewLines(path, state));
+    let state = { offset: 0, inode: -1 };
+    let disposed = false;
+    const tick = async () => {
+        if (disposed)
+            return;
+        try {
+            const result = await poll(state);
+            state = result.state;
+            for (const line of result.lines) {
+                if (matches(line)) {
+                    const defect = {
+                        type: 'log-error',
+                        message: line,
+                        context: { matcher: matcherId, path },
+                        occurredAt: now().toISOString(),
+                    };
+                    await handler(defect);
+                }
+            }
+        }
+        catch {
+            // File may not exist yet (app hasn't started logging) — retry next tick rather than crashing the daemon.
+        }
+    };
+    const timer = setInterval(() => void tick(), pollIntervalMs);
+    return () => {
+        disposed = true;
+        clearInterval(timer);
+    };
+}

package/dist/collectors/processCrash.d.ts

@@ -0,0 +1,24 @@
+import type { Defect } from '../types';
+export interface CrashTarget {
+    on(event: 'uncaughtException', listener: (err: Error) => void): unknown;
+    on(event: 'unhandledRejection', listener: (reason: unknown) => void): unknown;
+    off(event: string, listener: (...args: unknown[]) => void): unknown;
+    exit(code: number): void;
+}
+export type DefectHandler = (defect: Defect) => Promise<void>;
+export interface InstallCrashHandlersOptions {
+    /** Defaults to the real `process` — inject a fake EventEmitter-like target in tests so the real process is never touched. */
+    target?: CrashTarget;
+    /** Node's own guidance: process state is undefined after an uncaughtException, so the default is report-then-exit, not swallow-and-continue. */
+    exitOnUncaughtException?: boolean;
+    /** How long to wait for the report to flush before exiting. */
+    exitGraceMs?: number;
+    now?: () => Date;
+}
+/**
+ * Installs process-level crash handlers. `unhandledRejection` is
+ * report-only (Node doesn't treat it as fatal by default, and many apps
+ * intentionally don't either); `uncaughtException` is report-then-exit,
+ * since process state is undefined afterward.
+ */
+export declare function installCrashHandlers(handler: DefectHandler, options?: InstallCrashHandlersOptions): () => void;

package/dist/collectors/processCrash.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installCrashHandlers = installCrashHandlers;
+function reasonToDefect(type, reason, now) {
+    if (reason instanceof Error) {
+        return { type, message: reason.message, stack: reason.stack, occurredAt: now().toISOString() };
+    }
+    return { type, message: typeof reason === 'string' ? reason : JSON.stringify(reason), occurredAt: now().toISOString() };
+}
+/**
+ * Installs process-level crash handlers. `unhandledRejection` is
+ * report-only (Node doesn't treat it as fatal by default, and many apps
+ * intentionally don't either); `uncaughtException` is report-then-exit,
+ * since process state is undefined afterward.
+ */
+function installCrashHandlers(handler, options = {}) {
+    const target = options.target ?? process;
+    const exitOnUncaughtException = options.exitOnUncaughtException ?? true;
+    const exitGraceMs = options.exitGraceMs ?? 1000;
+    const now = options.now ?? (() => new Date());
+    const onUncaughtException = (err) => {
+        const defect = reasonToDefect('process-crash', err, now);
+        const reportPromise = handler(defect).catch(() => undefined);
+        if (exitOnUncaughtException) {
+            const timer = setTimeout(() => target.exit(1), exitGraceMs);
+            reportPromise.finally(() => {
+                clearTimeout(timer);
+                target.exit(1);
+            });
+        }
+    };
+    const onUnhandledRejection = (reason) => {
+        void handler(reasonToDefect('unhandled-rejection', reason, now));
+    };
+    target.on('uncaughtException', onUncaughtException);
+    target.on('unhandledRejection', onUnhandledRejection);
+    return () => {
+        target.off('uncaughtException', onUncaughtException);
+        target.off('unhandledRejection', onUnhandledRejection);
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from './types';
+export declare class ConfigError extends Error {
+}
+/**
+ * Reads configuration from environment variables only — this tool never
+ * writes credentials to a file it manages itself. At least one of
+ * JIRA_* / GITHUB_* must be fully configured, or nothing can ever create a
+ * ticket.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+exports.loadConfig = loadConfig;
+class ConfigError extends Error {
+}
+exports.ConfigError = ConfigError;
+function envInt(env, key, fallback) {
+    const raw = env[key];
+    if (raw === undefined || raw === '')
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        throw new ConfigError(`${key} must be a number, got "${raw}"`);
+    return value;
+}
+/**
+ * Reads configuration from environment variables only — this tool never
+ * writes credentials to a file it manages itself. At least one of
+ * JIRA_* / GITHUB_* must be fully configured, or nothing can ever create a
+ * ticket.
+ */
+function loadConfig(env = process.env) {
+    const jiraFields = ['JIRA_BASE_URL', 'JIRA_EMAIL', 'JIRA_API_TOKEN', 'JIRA_PROJECT_KEY'];
+    const hasJira = jiraFields.some((key) => env[key]);
+    if (hasJira && !jiraFields.every((key) => env[key])) {
+        throw new ConfigError(`Partial Jira config detected — set all of ${jiraFields.join(', ')} or none of them.`);
+    }
+    const githubFields = ['GITHUB_TOKEN', 'GITHUB_OWNER', 'GITHUB_REPO'];
+    const hasGithub = githubFields.some((key) => env[key]);
+    if (hasGithub && !githubFields.every((key) => env[key])) {
+        throw new ConfigError(`Partial GitHub config detected — set all of ${githubFields.join(', ')} or none of them.`);
+    }
+    if (!hasJira && !hasGithub) {
+        throw new ConfigError('No ticket provider configured. Run `crashrelay init` first, or set JIRA_* / GITHUB_* environment variables.');
+    }
+    const ingestionEnabled = env.INGESTION_TOKEN !== undefined;
+    return {
+        jira: hasJira
+            ? {
+                baseUrl: env.JIRA_BASE_URL,
+                email: env.JIRA_EMAIL,
+                apiToken: env.JIRA_API_TOKEN,
+                projectKey: env.JIRA_PROJECT_KEY,
+                issueType: env.JIRA_ISSUE_TYPE || 'Bug',
+            }
+            : undefined,
+        github: hasGithub
+            ? {
+                token: env.GITHUB_TOKEN,
+                owner: env.GITHUB_OWNER,
+                repo: env.GITHUB_REPO,
+            }
+            : undefined,
+        ingestion: ingestionEnabled
+            ? {
+                enabled: true,
+                port: envInt(env, 'INGESTION_PORT', 4318),
+                token: env.INGESTION_TOKEN,
+                allowedOrigins: (env.INGESTION_ALLOWED_ORIGINS ?? '').split(',').map((s) => s.trim()).filter(Boolean),
+            }
+            : undefined,
+        dedupCooldownHours: envInt(env, 'DEDUP_COOLDOWN_HOURS', 24),
+        commentCooldownMinutes: envInt(env, 'COMMENT_COOLDOWN_MINUTES', 60),
+        logTailPath: env.LOG_TAIL_PATH || undefined,
+        logTailPattern: env.LOG_TAIL_PATTERN || 'ERROR',
+        cacheFilePath: env.CRASHRELAY_CACHE_PATH || '.crashrelay-dedup-cache.json',
+    };
+}

package/dist/daemon.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from './types';
+import type { DefectHandler } from './collectors/processCrash';
+export interface DaemonHandle {
+    stop(): Promise<void>;
+}
+/**
+ * Runs the two pieces of crashrelay that genuinely can live in a separate
+ * always-on process: log-file tailing and the frontend-error ingestion
+ * endpoint. Crash/HTTP-5xx capture is a library embedded in the monitored
+ * app itself (see index.ts) — a separate process cannot hook another
+ * process's exceptions, that's a Node/OS limitation.
+ */
+export declare function startDaemon(config: Config, handler: DefectHandler): DaemonHandle;

package/dist/daemon.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startDaemon = startDaemon;
+const logTail_1 = require("./collectors/logTail");
+const server_1 = require("./ingestion/server");
+/**
+ * Runs the two pieces of crashrelay that genuinely can live in a separate
+ * always-on process: log-file tailing and the frontend-error ingestion
+ * endpoint. Crash/HTTP-5xx capture is a library embedded in the monitored
+ * app itself (see index.ts) — a separate process cannot hook another
+ * process's exceptions, that's a Node/OS limitation.
+ */
+function startDaemon(config, handler) {
+    const disposers = [];
+    if (config.logTailPath) {
+        console.log(`[crashrelay] tailing ${config.logTailPath} for pattern "${config.logTailPattern}"`);
+        disposers.push((0, logTail_1.tailLog)(config.logTailPath, config.logTailPattern, handler));
+    }
+    else {
+        console.log('[crashrelay] no LOG_TAIL_PATH configured — skipping log tailing');
+    }
+    if (config.ingestion?.enabled) {
+        const server = (0, server_1.createIngestionServer)(config.ingestion, handler);
+        server.listen(config.ingestion.port);
+        console.log(`[crashrelay] ingestion endpoint listening on port ${config.ingestion.port}`);
+        disposers.push(() => new Promise((resolve) => server.close(() => resolve())));
+    }
+    else {
+        console.log('[crashrelay] no INGESTION_TOKEN configured — frontend ingestion endpoint disabled');
+    }
+    return {
+        async stop() {
+            for (const dispose of disposers)
+                await dispose();
+        },
+    };
+}

package/dist/dedup.d.ts

@@ -0,0 +1,18 @@
+import type { DedupCache, DedupDecision, TicketRef } from './types';
+export declare function readCache(path: string): Promise<DedupCache>;
+/** Writes via a temp file + rename so a reader never observes a partially-written (truncated/corrupt) cache file, even under concurrent access. */
+export declare function writeCache(path: string, cache: DedupCache): Promise<void>;
+export interface DecideOptions {
+    cooldownHours: number;
+    commentCooldownMinutes: number;
+    now?: () => Date;
+}
+/**
+ * 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.
+ */
+export declare function decide(cache: DedupCache, fp: string, options: DecideOptions): DedupDecision;
+export declare function recordCreate(cache: DedupCache, fp: string, ticket: TicketRef, options: DecideOptions): DedupCache;
+export declare function recordSeenAgain(cache: DedupCache, fp: string, options: DecideOptions, commented: boolean): DedupCache;