patchrelay 0.1.0

package/dist/webhooks.js

@@ -0,0 +1,301 @@
+function deriveTriggerEvent(payload) {
+    if (payload.type === "AgentSessionEvent") {
+        if (payload.action === "created") {
+            return "agentSessionCreated";
+        }
+        if (payload.action === "prompted") {
+            return "agentPrompted";
+        }
+        return "issueUpdated";
+    }
+    if (payload.type === "Issue") {
+        if (payload.action === "create") {
+            return "issueCreated";
+        }
+        if (payload.action === "remove") {
+            return "issueRemoved";
+        }
+        const updatedFields = new Set(Object.keys(payload.updatedFrom ?? {}));
+        if (updatedFields.has("labels")) {
+            return "labelChanged";
+        }
+        if (updatedFields.has("stateId") || updatedFields.has("state")) {
+            return "statusChanged";
+        }
+        if (updatedFields.has("assigneeId") || updatedFields.has("assignee")) {
+            return "assignmentChanged";
+        }
+        if (updatedFields.has("delegateId") || updatedFields.has("delegate")) {
+            return "delegateChanged";
+        }
+        return "issueUpdated";
+    }
+    if (payload.type === "Comment") {
+        if (payload.action === "create") {
+            return "commentCreated";
+        }
+        if (payload.action === "remove") {
+            return "commentRemoved";
+        }
+        return "commentUpdated";
+    }
+    if (payload.type === "PermissionChange") {
+        return "installationPermissionsChanged";
+    }
+    if (payload.type === "OAuthApp" && payload.action === "revoked") {
+        return "installationRevoked";
+    }
+    if (payload.type === "AppUserNotification") {
+        return "appUserNotification";
+    }
+    return "issueUpdated";
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function getString(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function getBoolean(record, key) {
+    const value = record[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+function getStringArray(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
+}
+function extractLabelNames(record) {
+    const source = record.labels;
+    if (Array.isArray(source)) {
+        return source
+            .flatMap((entry) => {
+            if (typeof entry === "string") {
+                return [entry];
+            }
+            const entryRecord = asRecord(entry);
+            const name = entryRecord ? getString(entryRecord, "name") : undefined;
+            return name ? [name] : [];
+        })
+            .filter(Boolean);
+    }
+    const labelsRecord = asRecord(source);
+    const nodes = labelsRecord?.nodes;
+    if (Array.isArray(nodes)) {
+        return nodes
+            .flatMap((entry) => {
+            const entryRecord = asRecord(entry);
+            const name = entryRecord ? getString(entryRecord, "name") : undefined;
+            return name ? [name] : [];
+        })
+            .filter(Boolean);
+    }
+    return [];
+}
+function extractIssueMetadata(payload) {
+    const data = asRecord(payload.data);
+    if (!data) {
+        return undefined;
+    }
+    const issueRecord = payload.type === "Issue"
+        ? data
+        : payload.type === "AgentSessionEvent"
+            ? (() => {
+                const sessionRecord = asRecord(data.agentSession) ?? data;
+                return asRecord(sessionRecord.issue) ?? asRecord(data.issue) ?? sessionRecord;
+            })()
+            : payload.type === "AppUserNotification"
+                ? (() => {
+                    const notificationRecord = asRecord(data.notification) ?? data;
+                    return (asRecord(notificationRecord.issue) ??
+                        asRecord(asRecord(notificationRecord.comment)?.issue) ??
+                        asRecord(data.issue));
+                })()
+                : (() => {
+                    const nestedIssue = asRecord(data.issue);
+                    return nestedIssue ?? data;
+                })();
+    if (!issueRecord) {
+        return undefined;
+    }
+    const id = getString(issueRecord, "id") ?? getString(data, "issueId");
+    if (!id) {
+        return undefined;
+    }
+    const teamRecord = asRecord(issueRecord.team);
+    const identifier = getString(issueRecord, "identifier");
+    const title = getString(issueRecord, "title");
+    const url = getString(issueRecord, "url") ?? payload.url;
+    const delegateRecord = asRecord(issueRecord.delegate);
+    const teamId = getString(issueRecord, "teamId") ?? getString(teamRecord ?? {}, "id");
+    const teamKey = getString(teamRecord ?? {}, "key");
+    const stateRecord = asRecord(issueRecord.state);
+    const stateId = getString(issueRecord, "stateId") ?? getString(stateRecord ?? {}, "id");
+    const stateName = getString(stateRecord ?? {}, "name");
+    const stateType = getString(stateRecord ?? {}, "type");
+    const delegateId = getString(issueRecord, "delegateId") ?? getString(delegateRecord ?? {}, "id");
+    const delegateName = getString(delegateRecord ?? {}, "name");
+    return {
+        id,
+        ...(identifier ? { identifier } : {}),
+        ...(title ? { title } : {}),
+        ...(url ? { url } : {}),
+        ...(teamId ? { teamId } : {}),
+        ...(teamKey ? { teamKey } : {}),
+        ...(stateId ? { stateId } : {}),
+        ...(stateName ? { stateName } : {}),
+        ...(stateType ? { stateType } : {}),
+        ...(delegateId ? { delegateId } : {}),
+        ...(delegateName ? { delegateName } : {}),
+        labelNames: extractLabelNames(issueRecord),
+    };
+}
+function extractActorFromRecord(record) {
+    if (!record) {
+        return undefined;
+    }
+    const nestedUser = asRecord(record.user);
+    const id = getString(record, "id") ?? getString(record, "actorId") ?? getString(record, "userId") ?? getString(nestedUser ?? {}, "id");
+    const name = getString(record, "name") ?? getString(nestedUser ?? {}, "name");
+    const email = getString(record, "email") ?? getString(nestedUser ?? {}, "email");
+    const type = getString(record, "type") ?? getString(record, "__typename");
+    if (!id && !name && !email && !type) {
+        return undefined;
+    }
+    return {
+        ...(id ? { id } : {}),
+        ...(name ? { name } : {}),
+        ...(email ? { email } : {}),
+        ...(type ? { type } : {}),
+    };
+}
+function extractActorMetadata(payload) {
+    const payloadActor = extractActorFromRecord(asRecord(payload.actor));
+    if (payloadActor) {
+        return payloadActor;
+    }
+    const data = asRecord(payload.data);
+    const fallbacks = [
+        extractActorFromRecord(asRecord(data?.actor)),
+        extractActorFromRecord(asRecord(data?.user)),
+        extractActorFromRecord(asRecord(data?.creator)),
+        extractActorFromRecord(asRecord(data?.createdBy)),
+    ];
+    return fallbacks.find(Boolean);
+}
+function extractCommentMetadata(payload) {
+    if (payload.type !== "Comment") {
+        return undefined;
+    }
+    const data = asRecord(payload.data);
+    if (!data) {
+        return undefined;
+    }
+    const id = getString(data, "id");
+    const body = getString(data, "body");
+    const userRecord = asRecord(data.user);
+    const userName = getString(userRecord ?? {}, "name");
+    if (!id) {
+        return undefined;
+    }
+    return {
+        id,
+        ...(body ? { body } : {}),
+        ...(userName ? { userName } : {}),
+    };
+}
+function extractAgentSessionMetadata(payload) {
+    if (payload.type !== "AgentSessionEvent") {
+        return undefined;
+    }
+    const data = asRecord(payload.data);
+    if (!data) {
+        return undefined;
+    }
+    const sessionRecord = asRecord(data.agentSession) ?? data;
+    const id = getString(sessionRecord, "id") ?? getString(data, "agentSessionId");
+    if (!id) {
+        return undefined;
+    }
+    const agentActivity = asRecord(data.agentActivity);
+    const commentRecord = asRecord(data.comment) ?? asRecord(sessionRecord.comment);
+    const promptContext = getString(data, "promptContext") ?? getString(sessionRecord, "promptContext");
+    const promptBody = getString(agentActivity ?? {}, "body") ?? getString(commentRecord ?? {}, "body");
+    const issueCommentId = getString(commentRecord ?? {}, "id");
+    return {
+        id,
+        ...(promptContext ? { promptContext } : {}),
+        ...(promptBody ? { promptBody } : {}),
+        ...(issueCommentId ? { issueCommentId } : {}),
+    };
+}
+function extractInstallationMetadata(payload) {
+    const data = asRecord(payload.data);
+    if (!data) {
+        return undefined;
+    }
+    if (payload.type === "PermissionChange") {
+        const organizationId = getString(data, "organizationId");
+        const oauthClientId = getString(data, "oauthClientId");
+        const appUserId = getString(data, "appUserId");
+        const canAccessAllPublicTeams = getBoolean(data, "canAccessAllPublicTeams");
+        return {
+            ...(organizationId ? { organizationId } : {}),
+            ...(oauthClientId ? { oauthClientId } : {}),
+            ...(appUserId ? { appUserId } : {}),
+            ...(canAccessAllPublicTeams !== undefined ? { canAccessAllPublicTeams } : {}),
+            addedTeamIds: getStringArray(data, "addedTeamIds"),
+            removedTeamIds: getStringArray(data, "removedTeamIds"),
+        };
+    }
+    if (payload.type === "OAuthApp") {
+        const organizationId = getString(data, "organizationId");
+        const oauthClientId = getString(data, "oauthClientId");
+        return {
+            ...(organizationId ? { organizationId } : {}),
+            ...(oauthClientId ? { oauthClientId } : {}),
+            addedTeamIds: [],
+            removedTeamIds: [],
+        };
+    }
+    if (payload.type === "AppUserNotification") {
+        const notificationRecord = asRecord(data.notification) ?? data;
+        const organizationId = getString(data, "organizationId");
+        const oauthClientId = getString(data, "oauthClientId");
+        const appUserId = getString(data, "appUserId");
+        const notificationType = getString(notificationRecord, "type");
+        return {
+            ...(organizationId ? { organizationId } : {}),
+            ...(oauthClientId ? { oauthClientId } : {}),
+            ...(appUserId ? { appUserId } : {}),
+            ...(notificationType ? { notificationType } : {}),
+            addedTeamIds: [],
+            removedTeamIds: [],
+        };
+    }
+    return undefined;
+}
+export function normalizeWebhook(params) {
+    const issue = extractIssueMetadata(params.payload);
+    const comment = extractCommentMetadata(params.payload);
+    const agentSession = extractAgentSessionMetadata(params.payload);
+    const installation = extractInstallationMetadata(params.payload);
+    const actor = extractActorMetadata(params.payload);
+    if (!issue && !installation) {
+        throw new Error(`Unable to determine issue metadata from ${params.payload.type} webhook`);
+    }
+    const triggerEvent = deriveTriggerEvent(params.payload);
+    return {
+        webhookId: params.webhookId,
+        entityType: params.payload.type,
+        action: params.payload.action,
+        triggerEvent,
+        eventType: `${params.payload.type}.${params.payload.action}`,
+        ...(actor ? { actor } : {}),
+        ...(issue ? { issue } : {}),
+        ...(comment ? { comment } : {}),
+        ...(agentSession ? { agentSession } : {}),
+        ...(installation ? { installation } : {}),
+        payload: params.payload,
+    };
+}

package/dist/workflow-policy.js

@@ -0,0 +1,42 @@
+function normalize(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.toLowerCase() : undefined;
+}
+function extractIssuePrefix(identifier) {
+    const value = identifier?.trim();
+    if (!value) {
+        return undefined;
+    }
+    const [prefix] = value.split("-", 1);
+    return prefix ? prefix.toUpperCase() : undefined;
+}
+export function resolveWorkflow(project, stateName) {
+    const normalized = normalize(stateName);
+    if (!normalized) {
+        return undefined;
+    }
+    return project.workflows.find((workflow) => normalize(workflow.whenState) === normalized);
+}
+export function resolveWorkflowStage(project, stateName) {
+    return resolveWorkflow(project, stateName)?.id;
+}
+export function resolveWorkflowById(project, workflowId) {
+    const normalized = normalize(workflowId);
+    if (!normalized) {
+        return undefined;
+    }
+    return project.workflows.find((workflow) => normalize(workflow.id) === normalized);
+}
+export function listRunnableStates(project) {
+    return project.workflows.map((workflow) => workflow.whenState);
+}
+export function matchesProject(issue, project) {
+    const issuePrefix = extractIssuePrefix(issue.identifier);
+    const teamCandidates = [issue.teamId, issue.teamKey].filter((value) => Boolean(value));
+    const labelNames = new Set(issue.labelNames.map((label) => label.toLowerCase()));
+    const matchesPrefix = project.issueKeyPrefixes.length === 0 ||
+        (issuePrefix ? project.issueKeyPrefixes.map((value) => value.toUpperCase()).includes(issuePrefix) : false);
+    const matchesTeam = project.linearTeamIds.length === 0 || teamCandidates.some((candidate) => project.linearTeamIds.includes(candidate));
+    const matchesLabel = project.allowLabels.length === 0 || project.allowLabels.some((label) => labelNames.has(label.toLowerCase()));
+    return matchesPrefix && matchesTeam && matchesLabel;
+}

package/dist/workflow-ports.js

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

package/dist/workflow-types.js

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

package/dist/worktree-manager.js

@@ -0,0 +1,66 @@
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { ensureDir, execCommand } from "./utils.js";
+export class WorktreeManager {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async ensureIssueWorktree(repoPath, worktreeRoot, worktreePath, branchName) {
+        if (existsSync(worktreePath)) {
+            await this.assertTrustedExistingWorktree(repoPath, worktreeRoot, worktreePath);
+            return;
+        }
+        await ensureDir(path.dirname(worktreePath));
+        await execCommand(this.config.runner.gitBin, ["-C", repoPath, "worktree", "add", "--force", "-B", branchName, worktreePath, "HEAD"], {
+            timeoutMs: 120_000,
+        });
+    }
+    async assertTrustedExistingWorktree(repoPath, worktreeRoot, worktreePath) {
+        const worktreeStats = lstatSync(worktreePath);
+        if (worktreeStats.isSymbolicLink()) {
+            throw new Error(`Refusing to reuse symlinked worktree path: ${worktreePath}`);
+        }
+        if (!worktreeStats.isDirectory()) {
+            throw new Error(`Refusing to reuse non-directory worktree path: ${worktreePath}`);
+        }
+        const resolvedRoot = realpathSync(worktreeRoot);
+        const resolvedWorktree = realpathSync(worktreePath);
+        if (!isPathWithinRoot(resolvedRoot, resolvedWorktree)) {
+            throw new Error(`Refusing to reuse worktree outside configured root: ${worktreePath}`);
+        }
+        const listedWorktrees = await this.listRegisteredWorktrees(repoPath);
+        if (!listedWorktrees.has(resolvedWorktree)) {
+            throw new Error(`Refusing to reuse unregistered worktree path: ${worktreePath}`);
+        }
+    }
+    async listRegisteredWorktrees(repoPath) {
+        const result = await execCommand(this.config.runner.gitBin, ["-C", repoPath, "worktree", "list", "--porcelain"], {
+            timeoutMs: 120_000,
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(`Unable to verify registered worktrees for ${repoPath}`);
+        }
+        const worktrees = new Set();
+        for (const line of result.stdout.split(/\r?\n/)) {
+            if (!line.startsWith("worktree ")) {
+                continue;
+            }
+            const listedPath = line.slice("worktree ".length).trim();
+            if (!listedPath) {
+                continue;
+            }
+            try {
+                worktrees.add(realpathSync(listedPath));
+            }
+            catch {
+                worktrees.add(path.resolve(listedPath));
+            }
+        }
+        return worktrees;
+    }
+}
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}

package/infra/patchrelay-reload.service

@@ -0,0 +1,6 @@
+[Unit]
+Description=PatchRelay reload helper (systemd user service)
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/env systemctl --user reload-or-restart patchrelay.service

package/infra/patchrelay.path

@@ -0,0 +1,11 @@
+[Unit]
+Description=Watch PatchRelay config and env changes
+
+[Path]
+Unit=patchrelay-reload.service
+PathChanged=/home/your-user/.config/patchrelay/runtime.env
+PathChanged=/home/your-user/.config/patchrelay/service.env
+PathChanged=/home/your-user/.config/patchrelay/patchrelay.json
+
+[Install]
+WantedBy=default.target

package/infra/patchrelay.service

@@ -0,0 +1,28 @@
+[Unit]
+Description=PatchRelay (systemd user service)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/home/your-user
+EnvironmentFile=-/home/your-user/.config/patchrelay/runtime.env
+EnvironmentFile=/home/your-user/.config/patchrelay/service.env
+Environment=NODE_ENV=production
+Environment=PATCHRELAY_CONFIG=/home/your-user/.config/patchrelay/patchrelay.json
+Environment=PATH=/home/your-user/.local/bin:/usr/local/bin:/usr/bin:/bin
+ExecStart=/usr/bin/env patchrelay serve
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=false
+ReadWritePaths=/home/your-user/.config/patchrelay /home/your-user/.local/state/patchrelay /home/your-user/.local/share/patchrelay
+
+# PatchRelay is intended to run as your real user so Codex inherits your
+# existing git, SSH, and local tool permissions.
+# Add your managed repository roots to ReadWritePaths if you keep hardening enabled.
+
+[Install]
+WantedBy=default.target

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "patchrelay",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krasnoperov/patchrelay.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "patchrelay": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "runtime.env.example",
+    "service.env.example",
+    "config/patchrelay.example.json",
+    "infra/patchrelay.service",
+    "infra/patchrelay-reload.service",
+    "infra/patchrelay.path"
+  ],
+  "description": "Self-hosted harness for Linear-driven Codex work with durable issue worktrees, staged runs, and inspection.",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "dev": "node --watch --experimental-transform-types src/index.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/index.js && node scripts/write-build-info.mjs",
+    "prepack": "npm run build",
+    "start": "node dist/index.js serve",
+    "doctor": "node dist/index.js doctor",
+    "restart": "node dist/index.js restart-service",
+    "lint": "eslint .",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-transform-types --test test/**/*.test.ts",
+    "ci": "npm run lint && npm run check && npm test && npm run build"
+  },
+  "dependencies": {
+    "fastify": "^5.8.2",
+    "fastify-raw-body": "^5.0.0",
+    "pino": "^10.3.1",
+    "pino-logfmt": "^1.1.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.0",
+    "eslint": "^10.0.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.0"
+  }
+}

package/runtime.env.example

@@ -0,0 +1,8 @@
+# PatchRelay runtime overrides.
+# These are non-secret process-level overrides that both the service and local
+# CLI may need to read.
+
+# PATCHRELAY_CONFIG=$HOME/.config/patchrelay/patchrelay.json
+# PATCHRELAY_DB_PATH=$HOME/.local/state/patchrelay/patchrelay.sqlite
+# PATCHRELAY_LOG_LEVEL=info
+# PATCHRELAY_LOG_FILE=$HOME/.local/state/patchrelay/patchrelay.log

package/service.env.example

@@ -0,0 +1,7 @@
+# PatchRelay service secrets.
+# Keep these values at the machine level for this PatchRelay instance.
+
+LINEAR_WEBHOOK_SECRET=replace-with-linear-webhook-secret
+PATCHRELAY_TOKEN_ENCRYPTION_KEY=replace-with-long-random-secret
+LINEAR_OAUTH_CLIENT_ID=replace-with-linear-oauth-client-id
+LINEAR_OAUTH_CLIENT_SECRET=replace-with-linear-oauth-client-secret