@loucompanion/forge-bridge 0.1.1-dev.242bb53ef13f

package/README.md

@@ -0,0 +1,63 @@
+# Forge Bridge CLI
+
+`@loucompanion/forge-bridge` connects a local runner machine to a Forge server so Forge can dispatch work to approved local tooling and repositories.
+
+## Install
+
+Stable production channel:
+
+```bash
+npm install -g @loucompanion/forge-bridge@latest
+```
+
+Tailnet dev channel:
+
+```bash
+npm install -g @loucompanion/forge-bridge@next
+```
+
+## Basic usage
+
+```bash
+forge-bridge status
+forge-bridge connect --server <forge-url> --runner-id <runner-id> --device-token <device-token>
+```
+
+The bridge can also read connection settings from environment variables:
+
+- `FORGE_URL`
+- `FORGE_RUNNER_ID`
+- `FORGE_DEVICE_TOKEN`
+- `FORGE_DEVICE_NAME`
+- `FORGE_REPO_ROOT`
+- `FORGE_CLI_PROVIDERS`
+
+## Repo-local development
+
+For active Forge branch development, run the bridge directly from the checkout instead of publishing a package:
+
+```bash
+scripts/run-bridge-dev.sh status
+scripts/run-bridge-dev.sh connect --server <forge-url> --runner-id <runner-id> --device-token <device-token>
+```
+
+The tailnet dev server advertises the installable `@next` prerelease version. Repo-local execution is for contributors testing the current checkout.
+
+## Repository mappings
+
+Map Forge project labels to local repository paths:
+
+```bash
+forge-bridge add-repo Forge /path/to/Forge
+forge-bridge remove-repo Forge
+```
+
+## Package smoke check
+
+From this package directory:
+
+```bash
+npm run smoke:package
+```
+
+The smoke check builds the CLI, packs the package, installs the tarball into a temporary prefix, and verifies the installed `forge-bridge` binary can run `status`.

package/dist/bridge/bridge.base.d.ts

@@ -0,0 +1,17 @@
+import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeServiceConfig } from "./bridge.types.js";
+export interface BridgeService {
+    connectOnce(): Promise<void>;
+    run(signal?: AbortSignal): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface BridgeConnection {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onClose(handler: (error?: Error) => void): void;
+    onDispatch(handler: BridgeDispatchHandler): void;
+    onCancel(handler: BridgeCancelHandler): void;
+    invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
+}
+export interface BridgeConnectionFactory {
+    create(config: BridgeServiceConfig): BridgeConnection;
+}

package/dist/bridge/bridge.base.js

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

package/dist/bridge/bridge.service.d.ts

@@ -0,0 +1,45 @@
+import type { SessionService } from "../session/session.base.js";
+import type { BridgeConnection, BridgeConnectionFactory, BridgeService } from "./bridge.base.js";
+import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeServiceConfig } from "./bridge.types.js";
+export declare class ForgeBridgeService implements BridgeService {
+    private readonly config;
+    private readonly sessions;
+    private readonly connections;
+    private connection;
+    private heartbeatTimer;
+    private closed;
+    private stopped;
+    private readonly activeSessions;
+    constructor(config: BridgeServiceConfig, sessions?: SessionService, connections?: BridgeConnectionFactory);
+    connectOnce(): Promise<void>;
+    run(signal?: AbortSignal): Promise<void>;
+    stop(): Promise<void>;
+    private handleDispatch;
+    private handleCancel;
+    private abortActiveSessions;
+    private normalizeDispatch;
+    private sendResult;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private sendHeartbeat;
+    private capabilities;
+    private invokeAck;
+    private waitForClose;
+    private stopConnection;
+}
+export declare class SignalRBridgeConnectionFactory implements BridgeConnectionFactory {
+    create(config: BridgeServiceConfig): BridgeConnection;
+}
+export declare class SignalRBridgeConnection implements BridgeConnection {
+    private readonly config;
+    private readonly connection;
+    constructor(config: BridgeServiceConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onClose(handler: (error?: Error) => void): void;
+    onDispatch(handler: BridgeDispatchHandler): void;
+    onCancel(handler: BridgeCancelHandler): void;
+    invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
+}
+export declare function defaultBridgeServiceConfig(overrides?: Partial<BridgeServiceConfig>): BridgeServiceConfig;
+export declare function resolveBridgeRunnerHubUrl(serverUrl: string): URL;

package/dist/bridge/bridge.service.js

@@ -0,0 +1,340 @@
+import { HubConnectionBuilder, LogLevel } from "@microsoft/signalr";
+import path from "node:path";
+import { defaultForgeBridgeConfig } from "../config.js";
+import { redactSecrets, redactText } from "../shared/redaction/redaction.js";
+import { BridgeSessionService } from "../session/session.service.js";
+import { failureResult, parseRunOnceDispatchPacket } from "../session/session.types.js";
+import { forgeBridgeVersion } from "../version.js";
+export class ForgeBridgeService {
+    config;
+    sessions;
+    connections;
+    connection = null;
+    heartbeatTimer = null;
+    closed = null;
+    stopped = false;
+    activeSessions = new Map();
+    constructor(config, sessions = new BridgeSessionService(), connections = new SignalRBridgeConnectionFactory()) {
+        this.config = config;
+        this.sessions = sessions;
+        this.connections = connections;
+    }
+    async connectOnce() {
+        await this.stopConnection();
+        this.stopped = false;
+        const connection = this.connections.create(this.config);
+        this.connection = connection;
+        this.closed = new Promise((resolve) => {
+            connection.onClose(() => {
+                this.stopHeartbeat();
+                this.abortActiveSessions("bridge connection closed");
+                resolve();
+            });
+        });
+        connection.onDispatch((dispatch) => this.handleDispatch(dispatch));
+        connection.onCancel((request) => this.handleCancel(request));
+        await connection.start();
+        await this.invokeAck("Hello", {
+            version: this.config.version,
+            protocolVersion: this.config.protocolVersion,
+            minServerVersion: this.config.minServerVersion ?? null,
+            capabilities: this.capabilities()
+        });
+        this.startHeartbeat();
+    }
+    async run(signal) {
+        let attempt = 0;
+        try {
+            while (!this.stopped && !signal?.aborted) {
+                try {
+                    await this.connectOnce();
+                    attempt = 0;
+                    await this.waitForClose(signal);
+                }
+                catch (error) {
+                    if (this.stopped || signal?.aborted) {
+                        break;
+                    }
+                    const backoff = this.config.reconnectBackoffMs[Math.min(attempt, this.config.reconnectBackoffMs.length - 1)] ?? 5000;
+                    attempt += 1;
+                    await delay(backoff, signal);
+                }
+            }
+        }
+        finally {
+            if (signal?.aborted) {
+                this.abortActiveSessions(String(signal.reason ?? "bridge stopping"));
+            }
+            await this.stopConnection();
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        this.abortActiveSessions("bridge stopping");
+        await this.stopConnection();
+    }
+    async handleDispatch(dispatch) {
+        const leaseId = dispatch.lease.id;
+        const fencingToken = dispatch.lease.fencingToken;
+        const redactionSecrets = exactSecrets(dispatch);
+        if (this.activeSessions.has(leaseId)) {
+            await this.sendResult(leaseId, fencingToken, failureResult("Dispatch is already active on this bridge.")).catch(() => undefined);
+            return;
+        }
+        const controller = new AbortController();
+        this.activeSessions.set(leaseId, { fencingToken, controller });
+        try {
+            const normalized = this.normalizeDispatch(dispatch);
+            const result = await this.sessions.runOnce(normalized, {
+                emit: async (event) => {
+                    await this.invokeAck("DispatchEvent", {
+                        leaseId,
+                        fencingToken,
+                        event: redactSecrets(event, redactionSecrets)
+                    });
+                }
+            }, controller.signal);
+            await this.sendResult(leaseId, fencingToken, redactSecrets(result, redactionSecrets));
+        }
+        catch (error) {
+            const summary = controller.signal.aborted
+                ? `Dispatch cancelled: ${String(controller.signal.reason ?? "cancelled")}`
+                : redactText(error instanceof Error ? error.message : String(error), redactionSecrets);
+            await this.sendResult(leaseId, fencingToken, failureResult(summary)).catch(() => undefined);
+        }
+        finally {
+            this.activeSessions.delete(leaseId);
+        }
+    }
+    async handleCancel(request) {
+        const active = this.activeSessions.get(request.leaseId);
+        if (!active || active.fencingToken !== request.fencingToken) {
+            return;
+        }
+        active.controller.abort(request.reason ?? "cancelled by server");
+    }
+    abortActiveSessions(reason) {
+        for (const active of this.activeSessions.values()) {
+            active.controller.abort(reason);
+        }
+        this.activeSessions.clear();
+    }
+    normalizeDispatch(dispatch) {
+        const mapping = findRepoMapping(dispatch, this.config.repoMappings);
+        const localPath = mapping?.localPath?.trim();
+        const repoRoot = localPath ? path.dirname(path.resolve(localPath)) : this.config.defaultRepoRoot;
+        return {
+            ...dispatch,
+            repo: {
+                ...dispatch.repo,
+                serverLocalPath: localPath ? path.resolve(localPath) : null,
+                cloneOnDemand: localPath ? false : dispatch.repo.cloneOnDemand
+            },
+            serverLocal: {
+                repoRoot,
+                cleanupWorktrees: this.config.cleanupWorktrees
+            }
+        };
+    }
+    async sendResult(leaseId, fencingToken, result) {
+        const payload = {
+            leaseId,
+            fencingToken,
+            result
+        };
+        await this.invokeAck("DispatchResult", payload);
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        const intervalMs = positiveFiniteNumber(this.config.heartbeatIntervalMs, 30_000);
+        this.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat().catch(() => undefined);
+        }, intervalMs);
+        this.heartbeatTimer.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    async sendHeartbeat() {
+        await this.invokeAck("Heartbeat", {
+            status: "online",
+            capabilities: this.capabilities(),
+            version: this.config.version,
+            protocolVersion: this.config.protocolVersion
+        });
+    }
+    capabilities() {
+        return {
+            schemaVersion: 1,
+            activeSessionCount: this.activeSessions.size,
+            cliProviders: this.config.cliProviders,
+            providerStatuses: this.config.providerStatuses,
+            projectLabels: this.config.projectLabels,
+            repoMappings: this.config.repoMappings,
+            os: this.config.os,
+            sandboxProfiles: this.config.sandboxProfiles,
+            supportsApiSecretGrant: this.config.supportsApiSecretGrant
+        };
+    }
+    async invokeAck(methodName, payload) {
+        const connection = this.connection;
+        if (!connection) {
+            throw new Error("Bridge is not connected.");
+        }
+        const ack = await connection.invoke(methodName, payload);
+        if (!ack.accepted) {
+            throw new Error(ack.message ?? ack.code ?? `${methodName} callback was rejected.`);
+        }
+        return ack;
+    }
+    async waitForClose(signal) {
+        if (!this.closed) {
+            return;
+        }
+        await Promise.race([this.closed, abortPromise(signal)]);
+    }
+    async stopConnection() {
+        this.stopHeartbeat();
+        if (this.connection) {
+            await this.connection.stop().catch(() => undefined);
+            this.connection = null;
+        }
+    }
+}
+export class SignalRBridgeConnectionFactory {
+    create(config) {
+        return new SignalRBridgeConnection(config);
+    }
+}
+export class SignalRBridgeConnection {
+    config;
+    connection;
+    constructor(config) {
+        this.config = config;
+        const url = resolveBridgeRunnerHubUrl(config.serverUrl);
+        url.searchParams.set("runnerId", config.runnerId);
+        this.connection = new HubConnectionBuilder()
+            .withUrl(url.toString(), {
+            accessTokenFactory: () => config.deviceToken
+        })
+            .configureLogging(LogLevel.Warning)
+            .build();
+    }
+    start() {
+        return this.connection.start();
+    }
+    stop() {
+        return this.connection.stop();
+    }
+    onClose(handler) {
+        this.connection.onclose(handler);
+    }
+    onDispatch(handler) {
+        this.connection.on("Dispatch", (raw) => {
+            let dispatch;
+            try {
+                dispatch = parseRunOnceDispatchPacket(raw);
+            }
+            catch {
+                return;
+            }
+            void handler(dispatch).catch(() => undefined);
+        });
+    }
+    onCancel(handler) {
+        this.connection.on("Cancel", (request) => {
+            void handler(request).catch(() => undefined);
+        });
+    }
+    invoke(methodName, payload) {
+        return this.connection.invoke(methodName, payload);
+    }
+}
+export function defaultBridgeServiceConfig(overrides = {}) {
+    const defaults = defaultForgeBridgeConfig();
+    const cliProviders = splitCsv(process.env.FORGE_CLI_PROVIDERS ?? "codex");
+    const config = {
+        serverUrl: process.env.FORGE_URL ?? "http://localhost:5208",
+        runnerId: process.env.FORGE_RUNNER_ID ?? "",
+        deviceToken: process.env.FORGE_DEVICE_TOKEN ?? "",
+        deviceName: process.env.FORGE_DEVICE_NAME ?? "",
+        defaultRepoRoot: process.env.FORGE_REPO_ROOT ?? defaults.defaultRepoRoot,
+        cleanupWorktrees: process.env.FORGE_CLEANUP_WORKTREES !== "false" && defaults.cleanupWorktrees,
+        cliProviders,
+        providerStatuses: Object.fromEntries(cliProviders.map((provider) => [provider, { signedIn: true, version: "" }])),
+        projectLabels: splitCsv(process.env.FORGE_PROJECT_LABELS ?? ""),
+        repoMappings: [],
+        os: process.platform,
+        sandboxProfiles: ["default"],
+        supportsApiSecretGrant: true,
+        version: process.env.FORGE_BRIDGE_VERSION ?? forgeBridgeVersion,
+        protocolVersion: 1,
+        minServerVersion: null,
+        heartbeatIntervalMs: positiveFiniteNumber(Number(process.env.FORGE_HEARTBEAT_INTERVAL_MS ?? 30_000), 30_000),
+        reconnectBackoffMs: [1000, 2000, 5000, 10000, 30000],
+        ...overrides
+    };
+    return {
+        ...config,
+        heartbeatIntervalMs: positiveFiniteNumber(config.heartbeatIntervalMs, 30_000)
+    };
+}
+export function resolveBridgeRunnerHubUrl(serverUrl) {
+    return new URL("hubs/bridge-runners", normalizeServerUrl(serverUrl));
+}
+function normalizeServerUrl(serverUrl) {
+    if (!serverUrl.trim()) {
+        throw new Error("Forge server URL is required.");
+    }
+    return serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`;
+}
+function positiveFiniteNumber(value, fallback) {
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function splitCsv(value) {
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function findRepoMapping(dispatch, mappings) {
+    return mappings.find((mapping) => {
+        if (!mapping.localPath?.trim()) {
+            return false;
+        }
+        return (equalsIgnoreCase(mapping.repoId, dispatch.repo.id) ||
+            equalsIgnoreCase(mapping.name, dispatch.repo.name) ||
+            (!!mapping.remoteUrl?.trim() && equalsIgnoreCase(mapping.remoteUrl, dispatch.repo.remoteUrl)));
+    });
+}
+function equalsIgnoreCase(left, right) {
+    return !!left?.trim() && !!right?.trim() && left.trim().toLowerCase() === right.trim().toLowerCase();
+}
+function delay(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const timeout = setTimeout(resolve, ms);
+        timeout.unref?.();
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            resolve();
+        }, { once: true });
+    });
+}
+function abortPromise(signal) {
+    if (!signal) {
+        return new Promise(() => undefined);
+    }
+    if (signal.aborted) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+function exactSecrets(dispatch) {
+    return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
+}

package/dist/bridge/bridge.types.d.ts

@@ -0,0 +1,76 @@
+import type { RunOnceDispatchPacket, RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
+export interface BridgeServiceConfig {
+    readonly serverUrl: string;
+    readonly runnerId: string;
+    readonly deviceToken: string;
+    readonly deviceName: string;
+    readonly defaultRepoRoot: string;
+    readonly cleanupWorktrees: boolean;
+    readonly cliProviders: readonly string[];
+    readonly providerStatuses: Readonly<Record<string, BridgeProviderStatus>>;
+    readonly projectLabels: readonly string[];
+    readonly repoMappings: readonly BridgeRepoMapping[];
+    readonly os: string;
+    readonly sandboxProfiles: readonly string[];
+    readonly supportsApiSecretGrant: boolean;
+    readonly version: string;
+    readonly protocolVersion: number;
+    readonly minServerVersion?: string | null;
+    readonly heartbeatIntervalMs: number;
+    readonly reconnectBackoffMs: readonly number[];
+}
+export interface BridgeRepoMapping {
+    readonly repoId?: string | null;
+    readonly name?: string | null;
+    readonly remoteUrl?: string | null;
+    readonly localPath?: string | null;
+}
+export interface BridgeProviderStatus {
+    readonly signedIn?: boolean | null;
+    readonly version?: string | null;
+}
+export interface BridgeCapabilities {
+    readonly schemaVersion?: number | null;
+    readonly activeSessionCount?: number | null;
+    readonly cliProviders?: readonly string[] | null;
+    readonly providerStatuses?: Readonly<Record<string, BridgeProviderStatus>> | null;
+    readonly projectLabels?: readonly string[] | null;
+    readonly repoMappings?: readonly BridgeRepoMapping[] | null;
+    readonly os?: string | null;
+    readonly sandboxProfiles?: readonly string[] | null;
+    readonly supportsApiSecretGrant?: boolean | null;
+}
+export interface BridgeHelloRequest {
+    readonly version: string;
+    readonly protocolVersion: number;
+    readonly capabilities: BridgeCapabilities;
+    readonly minServerVersion?: string | null;
+}
+export interface BridgeHeartbeatRequest {
+    readonly status?: string | null;
+    readonly capabilities?: BridgeCapabilities | null;
+    readonly version?: string | null;
+    readonly protocolVersion?: number | null;
+}
+export interface BridgeCallbackAck {
+    readonly accepted: boolean;
+    readonly code?: string | null;
+    readonly message?: string | null;
+}
+export interface BridgeDispatchEventCallback {
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly event: RunnerDispatchEvent;
+}
+export interface BridgeDispatchResultCallback {
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly result: RunOnceResultPacket;
+}
+export interface BridgeCancelRequest {
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly reason?: string | null;
+}
+export type BridgeDispatchHandler = (dispatch: RunOnceDispatchPacket) => Promise<void>;
+export type BridgeCancelHandler = (request: BridgeCancelRequest) => Promise<void>;

package/dist/bridge/bridge.types.js

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

package/dist/bridge/index.d.ts

@@ -0,0 +1,2 @@
+export { ForgeBridgeService } from "./bridge.service.js";
+export type { BridgeService } from "./bridge.base.js";

package/dist/bridge/index.js

@@ -0,0 +1 @@
+export { ForgeBridgeService } from "./bridge.service.js";

package/dist/bridge/internals.d.ts

@@ -0,0 +1,3 @@
+export { SignalRBridgeConnection, SignalRBridgeConnectionFactory, defaultBridgeServiceConfig } from "./bridge.service.js";
+export type { BridgeConnection, BridgeConnectionFactory } from "./bridge.base.js";
+export type { BridgeCallbackAck, BridgeCancelHandler, BridgeCancelRequest, BridgeCapabilities, BridgeDispatchEventCallback, BridgeDispatchHandler, BridgeDispatchResultCallback, BridgeHeartbeatRequest, BridgeHelloRequest, BridgeRepoMapping, BridgeServiceConfig } from "./bridge.types.js";

package/dist/bridge/internals.js

@@ -0,0 +1 @@
+export { SignalRBridgeConnection, SignalRBridgeConnectionFactory, defaultBridgeServiceConfig } from "./bridge.service.js";

package/dist/cleanup/cleanup.base.d.ts

@@ -0,0 +1,4 @@
+import type { CleanupRequest, CleanupResult } from "./cleanup.types.js";
+export interface CleanupService {
+    run(request: CleanupRequest): Promise<CleanupResult>;
+}

package/dist/cleanup/cleanup.base.js

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

package/dist/cleanup/cleanup.service.d.ts

@@ -0,0 +1,5 @@
+import type { CleanupService } from "./cleanup.base.js";
+import type { CleanupRequest, CleanupResult } from "./cleanup.types.js";
+export declare class NoopCleanupService implements CleanupService {
+    run(_request: CleanupRequest): Promise<CleanupResult>;
+}

package/dist/cleanup/cleanup.service.js

@@ -0,0 +1,5 @@
+export class NoopCleanupService {
+    async run(_request) {
+        return { removedWorktrees: 0 };
+    }
+}

package/dist/cleanup/cleanup.types.d.ts

@@ -0,0 +1,6 @@
+export interface CleanupRequest {
+    readonly repoRoot: string;
+}
+export interface CleanupResult {
+    readonly removedWorktrees: number;
+}

package/dist/cleanup/cleanup.types.js

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

package/dist/cleanup/index.d.ts

@@ -0,0 +1,2 @@
+export { NoopCleanupService } from "./cleanup.service.js";
+export type { CleanupService } from "./cleanup.base.js";

package/dist/cleanup/index.js

@@ -0,0 +1 @@
+export { NoopCleanupService } from "./cleanup.service.js";

package/dist/cleanup/internals.d.ts

@@ -0,0 +1,3 @@
+export { NoopCleanupService } from "./cleanup.service.js";
+export type { CleanupService } from "./cleanup.base.js";
+export type { CleanupRequest, CleanupResult } from "./cleanup.types.js";

package/dist/cleanup/internals.js

@@ -0,0 +1 @@
+export { NoopCleanupService } from "./cleanup.service.js";

package/dist/cli/bin.d.ts

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

package/dist/cli/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { ForgeBridgeCliService } from "./cli.service.js";
+const service = new ForgeBridgeCliService();
+process.exitCode = await service.run(process.argv.slice(2));

package/dist/cli/cli.base.d.ts

@@ -0,0 +1,7 @@
+export interface CliService {
+    run(argv: readonly string[], io?: CliIo): Promise<number>;
+}
+export interface CliIo {
+    readonly stdout: Pick<NodeJS.WriteStream, "write">;
+    readonly stderr: Pick<NodeJS.WriteStream, "write">;
+}

package/dist/cli/cli.base.js

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