patchrelay 0.1.0

package/dist/linear-types.js

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

package/dist/linear-workflow.js

@@ -0,0 +1,78 @@
+import { resolveWorkflowById } from "./workflow-policy.js";
+const STATUS_MARKER = "<!-- patchrelay:status-comment -->";
+export function resolveActiveLinearState(project, stage) {
+    return resolveWorkflowById(project, stage)?.activeState;
+}
+export function resolveFallbackLinearState(project, stage) {
+    return resolveWorkflowById(project, stage)?.fallbackState;
+}
+export function buildRunningStatusComment(params) {
+    return [
+        STATUS_MARKER,
+        `PatchRelay is running the ${params.stageRun.stage} workflow.`,
+        "",
+        `- Issue: \`${params.issue.issueKey ?? params.issue.linearIssueId}\``,
+        `- Workflow: \`${params.stageRun.stage}\``,
+        `- Branch: \`${params.branchName}\``,
+        `- Thread: \`${params.stageRun.threadId ?? "starting"}\``,
+        `- Turn: \`${params.stageRun.turnId ?? "starting"}\``,
+        `- Started: \`${params.stageRun.startedAt}\``,
+        "- Status: `working`",
+    ].join("\n");
+}
+export function buildAwaitingHandoffComment(params) {
+    return [
+        STATUS_MARKER,
+        `PatchRelay finished the ${params.stageRun.stage} workflow, but Linear is still in \`${params.activeState}\`.`,
+        "",
+        `- Issue: \`${params.issue.issueKey ?? params.issue.linearIssueId}\``,
+        `- Workflow: \`${params.stageRun.stage}\``,
+        `- Thread: \`${params.stageRun.threadId ?? "unknown"}\``,
+        `- Turn: \`${params.stageRun.turnId ?? "unknown"}\``,
+        `- Completed: \`${params.stageRun.endedAt ?? new Date().toISOString()}\``,
+        "- Status: `awaiting-final-state`",
+        "",
+        "The workflow likely finished without moving the issue to its next Linear state. Please review the thread report and update the issue state.",
+    ].join("\n");
+}
+export function buildStageFailedComment(params) {
+    const mode = params.mode ?? "launch";
+    return [
+        STATUS_MARKER,
+        mode === "launch"
+            ? `PatchRelay could not start the ${params.stageRun.stage} workflow.`
+            : `PatchRelay marked the ${params.stageRun.stage} workflow as failed.`,
+        "",
+        `- Issue: \`${params.issue.issueKey ?? params.issue.linearIssueId}\``,
+        `- Workflow: \`${params.stageRun.stage}\``,
+        `- Started: \`${params.stageRun.startedAt}\``,
+        `- Failure: \`${params.message}\``,
+        `- Recommended state: \`${params.fallbackState ?? "Human Needed"}\``,
+        mode === "launch" ? "- Status: `launch-failed`" : "- Status: `stage-failed`",
+    ].join("\n");
+}
+export function isPatchRelayStatusComment(commentId, body, trackedCommentId) {
+    if (trackedCommentId && commentId === trackedCommentId) {
+        return true;
+    }
+    return typeof body === "string" && body.includes(STATUS_MARKER);
+}
+export function resolveWorkflowLabelNames(project, mode) {
+    const working = project.workflowLabels?.working;
+    const awaitingHandoff = project.workflowLabels?.awaitingHandoff;
+    if (mode === "working") {
+        return {
+            add: working ? [working] : [],
+            remove: awaitingHandoff ? [awaitingHandoff] : [],
+        };
+    }
+    return {
+        add: awaitingHandoff ? [awaitingHandoff] : [],
+        remove: working ? [working] : [],
+    };
+}
+export function resolveWorkflowLabelCleanup(project) {
+    return {
+        remove: [project.workflowLabels?.working, project.workflowLabels?.awaitingHandoff].filter((value) => Boolean(value)),
+    };
+}

package/dist/logging.js

@@ -0,0 +1,62 @@
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import pino, {} from "pino";
+export function createLogger(config) {
+    const options = {
+        level: config.logging.level,
+        base: null,
+        redact: {
+            paths: [
+                "headers.authorization",
+                "headers.cookie",
+                "headers.set-cookie",
+                "headers.linear-signature",
+                "req.headers.authorization",
+                "req.headers.cookie",
+                "req.headers.set-cookie",
+                "req.headers.linear-signature",
+                "authorization",
+                "accessToken",
+                "refreshToken",
+                "access_token",
+                "refresh_token",
+                "clientSecret",
+                "client_secret",
+                "webhookSecret",
+                "tokenEncryptionKey",
+                "bearerToken",
+                "accessTokenCiphertext",
+                "refreshTokenCiphertext",
+                "linear.webhookSecret",
+                "linear.oauth.clientSecret",
+                "operatorApi.bearerToken",
+            ],
+            censor: "[redacted]",
+        },
+        transport: {
+            targets: [
+                {
+                    target: "pino-logfmt",
+                    options: buildLogfmtOptions(1),
+                },
+                {
+                    target: "pino-logfmt",
+                    options: buildLogfmtOptions(config.logging.filePath),
+                },
+            ],
+        },
+    };
+    mkdirSync(path.dirname(config.logging.filePath), { recursive: true });
+    return pino(options);
+}
+function buildLogfmtOptions(destination) {
+    return {
+        destination,
+        flattenNestedObjects: true,
+        flattenNestedSeparator: ".",
+        includeLevelLabel: true,
+        levelLabelKey: "level",
+        formatTime: true,
+        escapeMultilineStrings: true,
+    };
+}

package/dist/preflight.js

@@ -0,0 +1,227 @@
+import { accessSync, constants, existsSync, mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { execCommand } from "./utils.js";
+export async function runPreflight(config) {
+    const checks = [];
+    if (!config.linear.webhookSecret) {
+        checks.push(fail("linear", "LINEAR_WEBHOOK_SECRET is missing"));
+    }
+    else {
+        checks.push(pass("linear", "Linear webhook secret is configured"));
+    }
+    if (!config.linear.oauth.clientId) {
+        checks.push(fail("linear_oauth", "LINEAR_OAUTH_CLIENT_ID is missing"));
+    }
+    else {
+        checks.push(pass("linear_oauth", `Linear OAuth is configured with actor=${config.linear.oauth.actor}`));
+    }
+    if (!config.linear.oauth.clientSecret) {
+        checks.push(fail("linear_oauth", "LINEAR_OAUTH_CLIENT_SECRET is missing"));
+    }
+    else {
+        checks.push(pass("linear_oauth", "Linear OAuth client secret is configured"));
+    }
+    if (!config.linear.tokenEncryptionKey) {
+        checks.push(fail("linear_oauth", "PATCHRELAY_TOKEN_ENCRYPTION_KEY is missing"));
+    }
+    else {
+        checks.push(pass("linear_oauth", "Token encryption key is configured"));
+    }
+    if (config.linear.oauth.actor === "app") {
+        const scopes = new Set(config.linear.oauth.scopes);
+        const missingScopes = ["app:assignable", "app:mentionable"].filter((scope) => !scopes.has(scope));
+        if (missingScopes.length > 0) {
+            checks.push(warn("linear_oauth", `Linear app actor is missing recommended agent scopes: ${missingScopes.join(", ")}`));
+        }
+        else {
+            checks.push(pass("linear_oauth", "Linear app actor includes assignable and mentionable scopes"));
+        }
+        for (const project of config.projects) {
+            if (!project.triggerEvents.includes("agentSessionCreated")) {
+                checks.push(warn(`project:${project.id}:triggers`, "App-mode delegation works best when trigger_events includes agentSessionCreated"));
+            }
+            if (!project.triggerEvents.includes("agentPrompted")) {
+                checks.push(warn(`project:${project.id}:triggers`, "Native follow-up agent prompts will not reach an active run unless trigger_events includes agentPrompted"));
+            }
+        }
+    }
+    if (config.operatorApi.enabled) {
+        if (config.operatorApi.bearerToken) {
+            checks.push(pass("operator_api", "Operator API is enabled with bearer token protection"));
+        }
+        else if (config.server.bind === "127.0.0.1") {
+            checks.push(warn("operator_api", "Operator API is enabled without a bearer token; safe only on loopback binds"));
+        }
+        else {
+            checks.push(fail("operator_api", "Operator API is enabled without a bearer token on a non-loopback bind"));
+        }
+    }
+    else {
+        checks.push(pass("operator_api", "Operator API is disabled"));
+    }
+    checks.push(...checkPublicBaseUrl(config));
+    checks.push(...checkOAuthRedirectUri(config));
+    checks.push(...checkPath("database", path.dirname(config.database.path), "directory", { createIfMissing: true, writable: true }));
+    checks.push(...checkPath("logging", path.dirname(config.logging.filePath), "directory", { createIfMissing: true, writable: true }));
+    if (config.logging.webhookArchiveDir) {
+        checks.push(...checkPath("archive", config.logging.webhookArchiveDir, "directory", { createIfMissing: true, writable: true }));
+    }
+    else {
+        checks.push(warn("archive", "Raw webhook archival is disabled"));
+    }
+    if (config.projects.length === 0) {
+        checks.push(warn("projects", "No projects are configured yet; add one with `patchrelay project apply <id> <repo-path>` before connecting Linear"));
+    }
+    for (const project of config.projects) {
+        checks.push(...checkPath(`project:${project.id}:repo`, project.repoPath, "directory", { writable: true }));
+        checks.push(...checkPath(`project:${project.id}:worktrees`, project.worktreeRoot, "directory", { createIfMissing: true, writable: true }));
+        for (const workflow of project.workflows) {
+            checks.push(...checkPath(`project:${project.id}:workflow:${workflow.id}`, workflow.workflowFile, "file", {}));
+        }
+    }
+    checks.push(await checkExecutable("git", config.runner.gitBin));
+    checks.push(await checkExecutable("codex", config.runner.codex.bin));
+    return {
+        checks,
+        ok: checks.every((check) => check.status !== "fail"),
+    };
+}
+function checkPath(scope, targetPath, expectedType, options) {
+    const checks = [];
+    if (!existsSync(targetPath)) {
+        if (expectedType === "directory" && options.createIfMissing) {
+            try {
+                mkdirSync(targetPath, { recursive: true });
+                checks.push(pass(scope, `Created missing directory ${targetPath}`));
+            }
+            catch (error) {
+                checks.push(fail(scope, `Unable to create directory ${targetPath}: ${formatError(error)}`));
+                return checks;
+            }
+        }
+        else {
+            checks.push(fail(scope, `Missing ${expectedType}: ${targetPath}`));
+            return checks;
+        }
+    }
+    let stats;
+    try {
+        stats = statSync(targetPath);
+    }
+    catch (error) {
+        checks.push(fail(scope, `Unable to stat ${targetPath}: ${formatError(error)}`));
+        return checks;
+    }
+    if (expectedType === "file" && !stats.isFile()) {
+        checks.push(fail(scope, `Expected a file: ${targetPath}`));
+        return checks;
+    }
+    if (expectedType === "directory" && !stats.isDirectory()) {
+        checks.push(fail(scope, `Expected a directory: ${targetPath}`));
+        return checks;
+    }
+    if (options.writable) {
+        try {
+            accessSync(targetPath, constants.W_OK);
+            checks.push(pass(scope, `${targetPath} is writable`));
+        }
+        catch (error) {
+            checks.push(fail(scope, `${targetPath} is not writable: ${formatError(error)}`));
+            return checks;
+        }
+    }
+    else {
+        checks.push(pass(scope, `${targetPath} exists`));
+    }
+    return checks;
+}
+async function checkExecutable(scope, command) {
+    try {
+        const result = await execCommand(command, ["--version"], {
+            timeoutMs: 5000,
+        });
+        if (result.exitCode !== 0) {
+            return fail(scope, `${command} --version exited with ${result.exitCode}`);
+        }
+        const firstLine = result.stdout.split(/\r?\n/, 1)[0]?.trim() || "version command succeeded";
+        return pass(scope, `${command} available: ${firstLine}`);
+    }
+    catch (error) {
+        return fail(scope, `${command} is not executable: ${formatError(error)}`);
+    }
+}
+function checkPublicBaseUrl(config) {
+    const publicBaseUrl = config.server.publicBaseUrl;
+    if (!publicBaseUrl) {
+        return [
+            warn("public_url", "server.public_base_url is not configured; set it to the public HTTPS origin that Linear should call"),
+        ];
+    }
+    try {
+        const url = new URL(publicBaseUrl);
+        const checks = [pass("public_url", `Public base URL configured: ${url.origin}`)];
+        if (url.protocol !== "https:") {
+            checks.push(warn("public_url", "server.public_base_url is not HTTPS; Linear-facing ingress should usually be HTTPS"));
+        }
+        if (isLoopbackHost(url.hostname)) {
+            checks.push(warn("public_url", "server.public_base_url points at a loopback host and will not be reachable by Linear"));
+        }
+        if (url.pathname !== "/" && url.pathname !== "") {
+            checks.push(warn("public_url", "server.public_base_url path is ignored; use only scheme, host, and optional port"));
+        }
+        return checks;
+    }
+    catch (error) {
+        return [fail("public_url", `Invalid server.public_base_url: ${formatError(error)}`)];
+    }
+}
+function checkOAuthRedirectUri(config) {
+    try {
+        const url = new URL(config.linear.oauth.redirectUri);
+        const checks = [];
+        if (url.pathname !== "/oauth/linear/callback") {
+            checks.push(fail("linear_oauth", 'linear.oauth.redirect_uri must use the fixed "/oauth/linear/callback" path'));
+            return checks;
+        }
+        if (isLoopbackHost(url.hostname)) {
+            checks.push(pass("linear_oauth", "Linear OAuth redirect URI is configured for local callback handling"));
+        }
+        else {
+            checks.push(pass("linear_oauth", `Linear OAuth redirect URI is configured for public callback handling at ${url.origin}`));
+            if (url.protocol !== "https:") {
+                checks.push(warn("linear_oauth", "Public Linear OAuth redirect URIs should usually use HTTPS"));
+            }
+        }
+        return checks;
+    }
+    catch (error) {
+        return [fail("linear_oauth", `Invalid linear.oauth.redirect_uri: ${formatError(error)}`)];
+    }
+}
+function isLoopbackHost(host) {
+    return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function pass(scope, message) {
+    return {
+        status: "pass",
+        scope,
+        message,
+    };
+}
+function warn(scope, message) {
+    return {
+        status: "warn",
+        scope,
+        message,
+    };
+}
+function fail(scope, message) {
+    return {
+        status: "fail",
+        scope,
+        message,
+    };
+}

package/dist/project-resolution.js

@@ -0,0 +1,51 @@
+import { matchesProject } from "./workflow-policy.js";
+export function resolveProject(config, issue) {
+    const matches = config.projects.filter((project) => matchesProject(issue, project));
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    return undefined;
+}
+export function triggerEventAllowed(project, triggerEvent) {
+    if (project.triggerEvents.includes(triggerEvent)) {
+        return true;
+    }
+    if (triggerEvent === "agentSessionCreated") {
+        return project.triggerEvents.includes("delegateChanged") || project.triggerEvents.includes("statusChanged");
+    }
+    return project.triggerEvents.includes(triggerEvent);
+}
+function normalizeTrustValue(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.toLowerCase() : undefined;
+}
+export function trustedActorAllowed(project, actor) {
+    const trusted = project.trustedActors;
+    if (!trusted) {
+        return true;
+    }
+    const hasRules = trusted.ids.length > 0 || trusted.names.length > 0 || trusted.emails.length > 0 || trusted.emailDomains.length > 0;
+    if (!hasRules) {
+        return true;
+    }
+    if (!actor) {
+        return false;
+    }
+    const actorId = actor.id?.trim();
+    if (actorId && trusted.ids.includes(actorId)) {
+        return true;
+    }
+    const actorName = normalizeTrustValue(actor.name);
+    if (actorName && trusted.names.map((value) => value.trim().toLowerCase()).includes(actorName)) {
+        return true;
+    }
+    const actorEmail = normalizeTrustValue(actor.email);
+    if (actorEmail && trusted.emails.map((value) => value.trim().toLowerCase()).includes(actorEmail)) {
+        return true;
+    }
+    const actorDomain = actorEmail?.split("@").at(-1);
+    if (actorDomain && trusted.emailDomains.map((value) => value.trim().toLowerCase()).includes(actorDomain)) {
+        return true;
+    }
+    return false;
+}

package/dist/reconciliation-action-applier.js

@@ -0,0 +1,55 @@
+export class ReconciliationActionApplier {
+    callbacks;
+    constructor(callbacks) {
+        this.callbacks = callbacks;
+    }
+    async apply(params) {
+        const { snapshot, decision } = params;
+        const threadId = snapshot.runLease.threadId;
+        const turnId = snapshot.runLease.turnId;
+        const obligationTargetAction = decision.actions.find((action) => action.type === "deliver_obligation" || action.type === "route_obligation");
+        const targetThreadId = obligationTargetAction?.type === "deliver_obligation" || obligationTargetAction?.type === "route_obligation"
+            ? obligationTargetAction.threadId
+            : threadId;
+        const targetTurnId = obligationTargetAction?.type === "deliver_obligation" || obligationTargetAction?.type === "route_obligation"
+            ? obligationTargetAction.turnId
+            : turnId;
+        const clearAction = decision.actions.find((action) => action.type === "clear_active_run" || action.type === "release_issue_ownership");
+        const nextLifecycleStatus = clearAction?.type === "clear_active_run" || clearAction?.type === "release_issue_ownership"
+            ? clearAction.nextLifecycleStatus
+            : undefined;
+        if (decision.outcome === "launch") {
+            this.callbacks.enqueueIssue(snapshot.runLease.projectId, snapshot.runLease.linearIssueId);
+            return;
+        }
+        if (decision.outcome === "continue") {
+            if (targetThreadId) {
+                await this.callbacks.deliverPendingObligations(snapshot.runLease.projectId, snapshot.runLease.linearIssueId, targetThreadId, targetTurnId);
+            }
+            return;
+        }
+        const completedAction = decision.actions.find((action) => action.type === "mark_run_completed");
+        if (decision.outcome === "complete" || (decision.outcome === "release" && completedAction?.type === "mark_run_completed")) {
+            const liveThread = snapshot.input.live?.codex?.status === "found" ? snapshot.input.live.codex.thread : undefined;
+            if (!liveThread) {
+                return;
+            }
+            const latestTurn = liveThread.turns.at(-1);
+            this.callbacks.completeRun(snapshot.runLease.projectId, snapshot.runLease.linearIssueId, liveThread, {
+                threadId: liveThread.id,
+                ...(latestTurn?.id ? { turnId: latestTurn.id } : {}),
+                ...(nextLifecycleStatus ? { nextLifecycleStatus } : {}),
+            });
+            return;
+        }
+        if (decision.outcome === "fail" || decision.outcome === "release") {
+            const failedAction = decision.actions.find((action) => action.type === "mark_run_failed");
+            if (decision.outcome === "release" && failedAction?.type !== "mark_run_failed") {
+                return;
+            }
+            await this.callbacks.failRunDuringReconciliation(snapshot.runLease.projectId, snapshot.runLease.linearIssueId, failedAction?.type === "mark_run_failed" && failedAction.threadId
+                ? failedAction.threadId
+                : threadId ?? `missing-thread-${snapshot.runLease.id}`, decision.reasons[0] ?? "Thread was not found during startup reconciliation", ...(failedAction?.type === "mark_run_failed" && failedAction.turnId ? [{ turnId: failedAction.turnId }] : []));
+        }
+    }
+}

package/dist/reconciliation-actions.js

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