reprobe 0.0.0-stage → 0.1.0

package/dist/sources/sentry.js

@@ -0,0 +1,123 @@
+import { run } from "../exec.js";
+import { config } from "../config.js";
+import { redactText } from "../redact.js";
+const DAY_MS = 86_400_000;
+const AUTH_HINT = 'sentry-cli is not logged in: run `sentry-cli login`';
+/** Sentry is reached only through sentry-cli, which holds its own credentials. */
+export async function sentryAuthState(runner = run) {
+    if (!config.sources.sentry)
+        return { source: 'sentry', state: 'skipped', detail: 'no sentry source in the config' };
+    const r = await runner('sentry-cli', ['info'], { timeoutMs: 15_000 });
+    if (r.code === 127)
+        return { source: 'sentry', state: 'missing-credentials', detail: 'sentry-cli not installed' };
+    if (r.code !== 0 || r.stdout.includes('Method: Unauthorized')) {
+        return { source: 'sentry', state: 'missing-credentials', detail: AUTH_HINT };
+    }
+    return { source: 'sentry', state: 'ok', detail: 'sentry-cli authenticated' };
+}
+const SCOPE_HINT = 'the sentry-cli token cannot read issues (an org CI token has only org:ci). Create a personal token with event:read, project:read and org:read, then `sentry-cli login --auth-token <token>`';
+/** Logged in is not enough: CI tokens authenticate but get 403 on issues. */
+export async function sentryReadState(runner = run) {
+    if (config.sources.sentry && !config.sources.sentry.projects?.length) {
+        return { source: 'sentry', state: 'error', detail: 'no Sentry projects configured' };
+    }
+    const auth = await sentryAuthState(runner);
+    if (auth.state !== 'ok')
+        return auth;
+    const { org, projects } = config.sources.sentry;
+    const r = await runner('sentry-cli', ['issues', 'list', '-o', org, '-p', projects[0], '--max-rows', '1'], { timeoutMs: 30_000 });
+    if (r.code === 0)
+        return { source: 'sentry', state: 'ok', detail: `can read issues in ${org}/${projects[0]}` };
+    const err = `${r.stderr}\n${r.stdout}`;
+    if (/403|permission/i.test(err))
+        return { source: 'sentry', state: 'missing-credentials', detail: SCOPE_HINT };
+    return { source: 'sentry', state: 'error', detail: redactText(err.split('\n').find((l) => l.trim()) ?? `exit ${r.code}`).slice(0, 200) };
+}
+/** Parses the ASCII table from `sentry-cli issues list`. Columns are mapped by header name. */
+export function parseIssueTable(text, project) {
+    const rows = text
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.startsWith('|'))
+        .map((l) => l.split('|').slice(1, -1).map((c) => c.trim()));
+    const headerIdx = rows.findIndex((cells) => cells.some((c) => c.toLowerCase() === 'issue id' || c.toLowerCase() === 'short id'));
+    if (headerIdx < 0)
+        return [];
+    const header = rows[headerIdx].map((c) => c.toLowerCase());
+    const col = (name) => header.indexOf(name);
+    const idx = {
+        id: col('issue id'),
+        shortId: col('short id'),
+        title: col('title'),
+        status: col('status'),
+        lastSeen: col('last seen'),
+    };
+    const cell = (cells, i) => (i < 0 ? '' : (cells[i] ?? ''));
+    return rows
+        .slice(headerIdx + 1)
+        .filter((cells) => cells.some((c) => c !== ''))
+        .map((cells) => ({
+        id: cell(cells, idx.id),
+        shortId: cell(cells, idx.shortId),
+        title: cell(cells, idx.title),
+        lastSeen: cell(cells, idx.lastSeen),
+        status: cell(cells, idx.status),
+    }));
+}
+export async function gatherSentry(opts) {
+    const runner = opts.runner ?? run;
+    if (config.sources.sentry && !config.sources.sentry.projects?.length) {
+        return { status: { source: 'sentry', state: 'error', detail: 'no Sentry projects configured' }, evidence: [] };
+    }
+    const auth = await sentryAuthState(runner);
+    if (auth.state !== 'ok')
+        return { status: auth, evidence: [] };
+    const { org: ORG, projects: PROJECTS, url } = config.sources.sentry;
+    const baseUrl = url ? `${url.replace(/\/+$/, '')}/organizations/${encodeURIComponent(ORG)}` : `https://${ORG}.sentry.io`;
+    // Issues active around the incident, not whatever is unresolved today.
+    const cutoff = Date.parse(opts.window.from) - DAY_MS;
+    const iso = (ms) => new Date(ms).toISOString();
+    const query = opts.issue || `${opts.userId ? `user.id:${opts.userId} ` : ''}firstSeen:<=${iso(Date.parse(opts.window.to))} lastSeen:>=${iso(cutoff)}`;
+    const evidence = [];
+    const failures = [];
+    let successfulProjects = 0;
+    for (const project of PROJECTS) {
+        const r = await runner('sentry-cli', ['issues', 'list', '-o', ORG, '-p', project, '--query', query, '--max-rows', '50'], { timeoutMs: 30_000 });
+        if (r.code !== 0) {
+            failures.push(/403|permission/i.test(r.stderr) ? SCOPE_HINT : redactText((r.stderr.split('\n')[0] ?? '').trim()) || `exit ${r.code}`);
+            continue;
+        }
+        successfulProjects++;
+        for (const row of parseIssueTable(r.stdout, project)) {
+            const ms = parseLastSeen(row.lastSeen);
+            if (!opts.issue && (ms === null || ms < cutoff))
+                continue;
+            // Prefix fallback ids so redaction cannot mistake them for phone numbers.
+            const ref = row.shortId || `issue-${row.id}`;
+            evidence.push({
+                id: `sentry:${project}:${ref}`,
+                source: 'sentry',
+                at: ms === null ? null : new Date(ms).toISOString(),
+                kind: 'sentry.issue',
+                summary: `${ref} ${row.title} (${row.status})`,
+                data: row,
+                // A numeric id is not a short-id search, and a numeric URL would be redacted again.
+                ...(row.shortId ? { link: `${baseUrl}/issues/?query=${encodeURIComponent(row.shortId)}` } : {}),
+            });
+        }
+    }
+    if (successfulProjects === 0) {
+        return { status: { source: 'sentry', state: failures[0] === SCOPE_HINT ? 'missing-credentials' : 'error', detail: failures[0] ?? 'sentry-cli failed' }, evidence: [] };
+    }
+    if (evidence.length === 0) {
+        return { status: { source: 'sentry', state: failures.length ? 'error' : 'empty', detail: failures.length ? `some project reads failed: ${failures.join('; ')}` : 'no matching issues' }, evidence };
+    }
+    return { status: { source: 'sentry', state: 'ok', detail: `${evidence.length} issues${failures.length ? `; some project reads failed: ${failures.join('; ')}` : ''}` }, evidence };
+}
+/** "2026-07-28 08:44:48.123 UTC" -> epoch ms, or null when it does not parse. */
+function parseLastSeen(s) {
+    if (!s)
+        return null;
+    const ms = Date.parse(s.replace(' UTC', 'Z').replace(' ', 'T'));
+    return Number.isNaN(ms) ? null : ms;
+}

package/dist/types.d.ts

@@ -0,0 +1,160 @@
+import type { Config } from './config.ts';
+import type { Runner } from './exec.ts';
+import type { ObservationAnnotator } from './sources/langfuse.ts';
+import type { Pg } from './sources/postgres.ts';
+/** Built-in sources are 'postgres', 'langfuse', 'langsmith', 'sentry', 'logs', 'archive', 'query'; packs add their own. */
+export type SourceName = string;
+export type SourceState = 'ok' | 'empty' | 'missing-credentials' | 'unreachable' | 'expired' | 'not-found' | 'skipped' | 'error';
+export interface SourceStatus {
+    source: SourceName;
+    state: SourceState;
+    detail: string;
+}
+/** One fact from one source. `id` is stable across runs so reports and citations diff cleanly. */
+export interface Evidence {
+    id: string;
+    source: SourceName;
+    at: string | null;
+    kind: string;
+    summary: string;
+    data: unknown;
+    link?: string;
+}
+export interface Window {
+    from: string;
+    to: string;
+}
+export interface Input {
+    complaint: string;
+    trace?: string;
+    user?: string;
+    chat?: string;
+    sentry?: string;
+    reporter?: string;
+    at?: string;
+    sinceMs: number;
+}
+export interface Subject {
+    userId?: string;
+    label?: string;
+    how?: string;
+    sessionIds: string[];
+    traceIds: string[];
+}
+export interface ReplayFile {
+    /** Path relative to the repo root. */
+    path: string;
+    content: string;
+    mode: 'create' | 'append';
+}
+/**
+ * A focused test that encodes the invariant the bug broke. It must print `<marker>:START` before its
+ * assertions and exactly one of `<marker>:PASS` / `<marker>:FAIL` after, so a run that crashed before
+ * reaching the assertion is classified BROKEN instead of FAIL.
+ */
+export interface Replay {
+    description: string;
+    files: ReplayFile[];
+    /** Directory relative to the repo root that the command runs in. */
+    cwd: string;
+    /** argv, no shell. command[0] must be a known test runner or listed in verify.allow. */
+    command: string[];
+    /** Files that must exist at the target commit for the replay to apply. */
+    requires: string[];
+    /** REPROBE_REPLAY:<id> */
+    marker: string;
+    /** Free-form tag a pack can use to pick its worktree preparation (e.g. 'server-jest', 'dart-test'). */
+    kind?: string;
+}
+export type Confidence = 'high' | 'medium' | 'low';
+export interface Finding {
+    signature: string;
+    title: string;
+    confidence: Confidence;
+    rootCause: string;
+    evidence: string[];
+    unknowns: string[];
+    replay?: Replay;
+}
+export interface Gathered {
+    input: Input;
+    window: Window;
+    subject: Subject;
+    sources: SourceStatus[];
+    evidence: Evidence[];
+}
+/** What the complaint says, independent of any product. Packs add product topics on top. */
+export interface Intent {
+    build: string | null;
+    aboutOther: boolean;
+    retries: number | null;
+    words: string;
+}
+export interface GatherCtx {
+    config: Config;
+    input: Input;
+    intent: Intent;
+    window: Window;
+    subject: Subject;
+    sources: SourceStatus[];
+    evidence: Evidence[];
+    /** The read-only Postgres client, when configured and verified read-only. */
+    pg: Pg | null;
+    /** Extra ids (user ids, session ids) that make a log line relevant. */
+    logIds: string[];
+    log: (s: string) => void;
+    run: Runner;
+}
+export interface DetectCtx {
+    g: Gathered;
+    intent: Intent;
+    caseId: string;
+    /** Evidence sorted by time, then id. */
+    ev: Evidence[];
+}
+export type Detector = (c: DetectCtx) => Finding[];
+export interface PrepareResult {
+    /** Replaces the replay command (e.g. a toolchain picked for the commit date). */
+    command?: string[];
+    notes?: string[];
+    /** A reason the commit cannot run the replay; the result is BROKEN with this detail. */
+    error?: string;
+}
+/**
+ * A pack teaches reprobe one product: how to find the user, which rows matter, which failure
+ * signatures it has, and how to build an old commit. Every hook is optional.
+ * Packs import only types from reprobe; everything they call at runtime arrives in the ctx.
+ */
+export interface Pack {
+    name: string;
+    /** Before logs are read: resolve who the complaint is about, or a candidate set (push ids to ctx.logIds). */
+    resolveSubject?(ctx: GatherCtx): Promise<void>;
+    /** After logs are read: narrow candidates using log evidence, then read product rows. */
+    gather?(ctx: GatherCtx): Promise<void>;
+    /** Product facts read off each Langfuse observation (flags for detectors, words for the summary). */
+    observation?: ObservationAnnotator;
+    detectors?: Detector[];
+    /** Attach a replay to a core finding (e.g. a masked 4xx on a route the pack knows how to test). */
+    replayFor?(finding: Finding, ctx: DetectCtx): Replay | undefined;
+    /** Runs in the worktree after the replay files are written and setup steps ran. */
+    prepareWorktree?(wt: string, replay: Replay, sha: string, tools: WorktreeTools): Promise<PrepareResult>;
+    doctor?(ctx: {
+        config: Config;
+        pg: Pg | null;
+        run: Runner;
+    }): Promise<Check[]>;
+}
+export interface WorktreeTools {
+    run: Runner;
+    git(args: string[], cwd?: string): ReturnType<Runner>;
+    /** Resolve a relative path inside a root, refusing symlinks and escapes. */
+    safePath(root: string, rel: string): string;
+    log(s: string): void;
+}
+export interface Check {
+    name: string;
+    ok: boolean;
+    detail: string;
+    fix?: string;
+    required?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,27 @@
+import { type Runner } from './exec.ts';
+import type { Pack, Replay } from './types.ts';
+export type Outcome = 'pass' | 'fail' | 'broken' | 'not-applicable';
+export interface VerifyResult {
+    commit: string;
+    sha: string;
+    outcome: Outcome;
+    detail: string;
+    logFile: string;
+}
+/** Validate paths serialized in evidence before they can escape a worktree. */
+export declare function assertSafeRelativePath(path: string, label: string): string;
+export declare function assertSafeCheckoutPath(root: string, path: string): string;
+/** Reject paths that can redirect a cached worktree into the user's source checkout. */
+export declare function assertSafeWorktreeLocation(repoPath: string, cachePath: string, worktreePath: string): void;
+/** Test runners a replay may start. A config can add more under verify.allow. */
+export declare const DEFAULT_RUNNERS: string[];
+export declare function assertSafeReplay(replay: Replay, allow?: string[]): void;
+/** A run that never reached its assertion is BROKEN, not FAIL: only a failing assertion proves the bug. */
+export declare function classify(code: number, output: string, marker?: string | null): {
+    outcome: Outcome;
+    detail: string;
+};
+/** A step for `server` runs only for replays whose cwd is inside `server`; a step for `.` always runs. */
+export declare const stepApplies: (stepDir: string, replayCwd: string) => boolean;
+export declare function verifyReplay(caseDir: string, replay: Replay, commits: string[], pack?: Pack | null, log?: (s: string) => void, runner?: Runner): Promise<VerifyResult[]>;
+export declare function cleanWorktrees(runner?: Runner): Promise<string[]>;