@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/services/forge-cli-command.d.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+/**
+ * Timeout for the per-host CLI auth probe (`gh`/`glab`/`tea` auth status) used
+ * to detect a self-hosted forge. This intentionally has no anonymous HTTP
+ * fallback: a remote-derived host is trusted only when the CLI already knows it.
+ */
+export declare const CLI_AUTH_PROBE_TIMEOUT_MS = 10000;
+interface CliCommandErrorShape extends Error {
+    stderr: string;
+}
+interface NormalizeCliCommandErrorOptions {
+    error: unknown;
+    args: string[];
+    cwd: string;
+    commandName: string;
+    timeoutMs?: number;
+    isAlreadyClassified: (error: unknown) => boolean;
+    isCommandError: (error: unknown) => error is CliCommandErrorShape;
+    isAuthFailureText: (text: string) => boolean;
+    createAuthError: (stderr: string) => Error;
+    createMissingError: () => Error;
+    createCommandError: (params: {
+        args: string[];
+        cwd: string;
+        exitCode: number | null;
+        stderr: string;
+    }) => Error;
+}
+interface ParseCliJsonOutputOptions<T> {
+    commandName: string;
+    args: string[];
+    cwd: string;
+    stdout: string;
+    schema: z.ZodType<T>;
+    createCommandError: NormalizeCliCommandErrorOptions["createCommandError"];
+}
+interface ProbeHostViaCliAuthStatusOptions {
+    cli: string;
+    host: string;
+    envOverlay?: Record<string, string>;
+}
+export interface ForgeCliRunnerOptions {
+    cwd: string;
+    envOverlay?: Record<string, string>;
+}
+export interface ForgeCliRunnerResult {
+    stdout: string;
+    stderr: string;
+}
+export type ForgeCliRunner = (args: string[], options: ForgeCliRunnerOptions) => Promise<ForgeCliRunnerResult>;
+export interface ForgeCliRunnerErrorClasses {
+    isAlreadyClassified: (error: unknown) => boolean;
+    isCommandError: (error: unknown) => error is CliCommandErrorShape;
+    createAuthError: (stderr: string) => Error;
+    createMissingError: () => Error;
+    createCommandError: (params: ForgeCommandFailureParams) => Error;
+}
+export interface CreateForgeCliRunnerOptions {
+    binary: string;
+    envOverlay: Record<string, string>;
+    timeoutMs: number;
+    isAuthFailureText: (text: string) => boolean;
+    errorClasses: ForgeCliRunnerErrorClasses;
+}
+export interface ForgeCliRunnerFactory {
+    run: ForgeCliRunner;
+    normalizeError: (error: unknown, context: {
+        args: string[];
+        cwd: string;
+        timeoutMs?: number;
+    }) => Error;
+}
+/**
+ * Shared shape behind the gh/glab/tea CLI adapters: an exec wrapper (10MB
+ * maxBuffer, per-call env overlay merged over the binary's defaults, a
+ * timeout) plus error normalization through the binary's own error-class
+ * trio. The three adapters differ only in the params passed here.
+ */
+export declare function createForgeCliRunner(options: CreateForgeCliRunnerOptions): ForgeCliRunnerFactory;
+export declare class ForgeCliMissingError extends Error {
+    readonly kind = "missing-cli";
+}
+export declare class ForgeAuthenticationError extends Error {
+    readonly kind = "auth-failure";
+    readonly stderr: string;
+    constructor(message: string, params: {
+        stderr: string;
+    });
+}
+export interface ForgeCommandFailureParams {
+    args: string[];
+    cwd: string;
+    exitCode: number | null;
+    stderr: string;
+    /**
+     * Whatever the failing command printed to stdout. GraphQL batch callers use
+     * this to salvage partial `data` when one aliased sub-query errors but the
+     * others succeeded (the CLI exits non-zero yet still prints the body).
+     */
+    stdout?: string;
+}
+export declare class ForgeCommandError extends Error {
+    readonly kind = "command-error";
+    readonly args: string[];
+    readonly cwd: string;
+    readonly exitCode: number | null;
+    readonly stderr: string;
+    readonly stdout?: string;
+    constructor(label: {
+        brand: string;
+        binary: string;
+    }, params: ForgeCommandFailureParams);
+}
+/**
+ * Memoize a CLI path resolver (`findExecutable`) for the lifetime of a service
+ * instance. A found path is cached permanently; a miss (or a rejected probe)
+ * evicts the cache so a CLI installed after the daemon started is picked up
+ * on the next call instead of requiring a restart. Concurrent callers during
+ * resolution share the same in-flight promise.
+ */
+export declare function createCachedCliPathResolver(resolve: () => Promise<string | null>): () => Promise<string | null>;
+export declare function bufferOrStringToString(value: unknown): string;
+export declare function normalizeCliCommandError(options: NormalizeCliCommandErrorOptions): Error;
+export declare function parseCliJsonOutput<T>(options: ParseCliJsonOutputOptions<T>): T;
+export declare function defaultResolveRemoteUrl(cwd: string): Promise<string | null>;
+export declare function probeHostViaCliAuthStatus(options: ProbeHostViaCliAuthStatusOptions): Promise<boolean>;
+export {};
+//# sourceMappingURL=forge-cli-command.d.ts.map

package/dist/server/services/forge-cli-command.js

@@ -0,0 +1,212 @@
+import { findExecutable } from "../executable-resolution/executable-resolution.js";
+import { runGitCommand } from "../utils/run-git-command.js";
+import { execCommand } from "../utils/spawn.js";
+/**
+ * Timeout for the per-host CLI auth probe (`gh`/`glab`/`tea` auth status) used
+ * to detect a self-hosted forge. This intentionally has no anonymous HTTP
+ * fallback: a remote-derived host is trusted only when the CLI already knows it.
+ */
+export const CLI_AUTH_PROBE_TIMEOUT_MS = 10000;
+/**
+ * Shared shape behind the gh/glab/tea CLI adapters: an exec wrapper (10MB
+ * maxBuffer, per-call env overlay merged over the binary's defaults, a
+ * timeout) plus error normalization through the binary's own error-class
+ * trio. The three adapters differ only in the params passed here.
+ */
+export function createForgeCliRunner(options) {
+    const run = (args, runOptions) => execCommand(options.binary, args, {
+        cwd: runOptions.cwd,
+        envOverlay: { ...options.envOverlay, ...runOptions.envOverlay },
+        maxBuffer: 10 * 1024 * 1024,
+        timeout: options.timeoutMs,
+    });
+    function normalizeError(error, context) {
+        return normalizeCliCommandError({
+            error,
+            args: context.args,
+            cwd: context.cwd,
+            commandName: options.binary,
+            timeoutMs: context.timeoutMs ?? options.timeoutMs,
+            isAlreadyClassified: options.errorClasses.isAlreadyClassified,
+            isCommandError: options.errorClasses.isCommandError,
+            isAuthFailureText: options.isAuthFailureText,
+            createAuthError: options.errorClasses.createAuthError,
+            createMissingError: options.errorClasses.createMissingError,
+            createCommandError: options.errorClasses.createCommandError,
+        });
+    }
+    return { run, normalizeError };
+}
+export class ForgeCliMissingError extends Error {
+    constructor() {
+        super(...arguments);
+        this.kind = "missing-cli";
+    }
+}
+export class ForgeAuthenticationError extends Error {
+    constructor(message, params) {
+        super(message);
+        this.kind = "auth-failure";
+        this.stderr = params.stderr;
+    }
+}
+export class ForgeCommandError extends Error {
+    constructor(label, params) {
+        super(`${label.brand} CLI command failed: ${label.binary} ${params.args.join(" ")}`);
+        this.kind = "command-error";
+        this.args = [...params.args];
+        this.cwd = params.cwd;
+        this.exitCode = params.exitCode;
+        this.stderr = params.stderr;
+        if (params.stdout !== undefined) {
+            this.stdout = params.stdout;
+        }
+    }
+}
+/**
+ * Memoize a CLI path resolver (`findExecutable`) for the lifetime of a service
+ * instance. A found path is cached permanently; a miss (or a rejected probe)
+ * evicts the cache so a CLI installed after the daemon started is picked up
+ * on the next call instead of requiring a restart. Concurrent callers during
+ * resolution share the same in-flight promise.
+ */
+export function createCachedCliPathResolver(resolve) {
+    let pending = null;
+    return function resolveCliPath() {
+        if (pending) {
+            return pending;
+        }
+        const current = resolve()
+            .then((path) => {
+            if (path === null && pending === current) {
+                pending = null;
+            }
+            return path;
+        })
+            .catch((error) => {
+            if (pending === current) {
+                pending = null;
+            }
+            throw error;
+        });
+        pending = current;
+        return current;
+    };
+}
+export function bufferOrStringToString(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (Buffer.isBuffer(value)) {
+        return value.toString("utf8");
+    }
+    return "";
+}
+export function normalizeCliCommandError(options) {
+    if (options.isAlreadyClassified(options.error)) {
+        return options.error;
+    }
+    if (options.isCommandError(options.error)) {
+        if (options.isAuthFailureText(options.error.stderr)) {
+            return options.createAuthError(options.error.stderr);
+        }
+        return options.error;
+    }
+    const failure = toCommandFailureLike(options.error);
+    if (failure.code === "ENOENT") {
+        return options.createMissingError();
+    }
+    const stderr = bufferOrStringToString(failure.stderr);
+    const stdout = bufferOrStringToString(failure.stdout);
+    const message = failure.message ?? "";
+    if (options.isAuthFailureText(stderr) || options.isAuthFailureText(message)) {
+        return options.createAuthError(stderr);
+    }
+    if (failure.killed === true && options.timeoutMs !== undefined) {
+        return options.createCommandError({
+            args: options.args,
+            cwd: options.cwd,
+            exitCode: null,
+            stderr: stderr ||
+                `${options.commandName} was terminated before completing (timed out after ${options.timeoutMs}ms or exceeded the output limit)`,
+            ...(stdout ? { stdout } : {}),
+        });
+    }
+    return options.createCommandError({
+        args: options.args,
+        cwd: options.cwd,
+        exitCode: typeof failure.code === "number" ? failure.code : null,
+        stderr: stderr || message,
+        ...(stdout ? { stdout } : {}),
+    });
+}
+export function parseCliJsonOutput(options) {
+    let data;
+    try {
+        data = JSON.parse(options.stdout);
+    }
+    catch {
+        throw options.createCommandError({
+            args: options.args,
+            cwd: options.cwd,
+            exitCode: null,
+            stderr: `${options.commandName} did not return valid JSON (${options.stdout.length} bytes)`,
+        });
+    }
+    const parsed = options.schema.safeParse(data);
+    if (!parsed.success) {
+        throw options.createCommandError({
+            args: options.args,
+            cwd: options.cwd,
+            exitCode: null,
+            stderr: `${options.commandName} JSON did not match the expected schema: ${parsed.error.message}`,
+        });
+    }
+    return parsed.data;
+}
+export async function defaultResolveRemoteUrl(cwd) {
+    try {
+        const { stdout } = await runGitCommand(["config", "--get", "remote.origin.url"], { cwd });
+        const url = stdout.trim();
+        return url.length > 0 ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function probeHostViaCliAuthStatus(options) {
+    const cliPath = await findExecutable(options.cli);
+    if (!cliPath) {
+        return false;
+    }
+    try {
+        await execCommand(options.cli, ["auth", "status", "--hostname", options.host], {
+            envOverlay: options.envOverlay,
+            timeout: CLI_AUTH_PROBE_TIMEOUT_MS,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toCommandFailureLike(error) {
+    if (!error || typeof error !== "object") {
+        return { message: String(error) };
+    }
+    const record = error;
+    return {
+        code: typeof record.code === "string" || typeof record.code === "number" || record.code === null
+            ? record.code
+            : undefined,
+        killed: typeof record.killed === "boolean" ? record.killed : undefined,
+        stderr: typeof record.stderr === "string" || Buffer.isBuffer(record.stderr)
+            ? record.stderr
+            : undefined,
+        stdout: typeof record.stdout === "string" || Buffer.isBuffer(record.stdout)
+            ? record.stdout
+            : undefined,
+        message: typeof record.message === "string" ? record.message : undefined,
+    };
+}
+//# sourceMappingURL=forge-cli-command.js.map

package/dist/server/services/forge-registry.d.ts

@@ -0,0 +1,25 @@
+import type { ForgeService } from "./forge-service.js";
+export type ForgeServiceFactory = () => ForgeService;
+export interface ForgeAdapterRegistration {
+    createService: ForgeServiceFactory;
+    matchesHost?: (host: string) => boolean;
+    probeHost?: (host: string) => Promise<boolean>;
+}
+/**
+ * Open composition boundary for forge adapters. Resolver code depends only on
+ * these registration hooks, so a new adapter does not require another branch.
+ */
+export declare class ForgeRegistry {
+    #private;
+    constructor(entries?: Iterable<readonly [string, ForgeAdapterRegistration]>);
+    register(forge: string, adapter: ForgeAdapterRegistration): () => void;
+    ids(): string[];
+    has(forge: string): boolean;
+    create(forge: string): ForgeService | null;
+    matchHost(host: string): string | null;
+    probeHost(host: string): Promise<string | null>;
+}
+export declare const defaultForgeRegistry: ForgeRegistry;
+export declare function createForgeService(forge: string): ForgeService | null;
+export declare function probeRegisteredForgeHost(host: string): Promise<string | null>;
+//# sourceMappingURL=forge-registry.d.ts.map

package/dist/server/services/forge-registry.js

@@ -0,0 +1,155 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ForgeRegistry_instances, _ForgeRegistry_adapters, _ForgeRegistry_warnedAmbiguousHosts, _ForgeRegistry_warnAmbiguous;
+import { getForgeDefinition } from "@camerontaylor/paseo-protocol/forge-manifest";
+import { normalizeHost } from "@camerontaylor/paseo-protocol/git-remote";
+import { createGitHubService, probeGitHubHost } from "./github-service.js";
+import { createGiteaService, resolveGiteaFamilyForge } from "./gitea-service.js";
+import { createGitLabService, probeGitLabHost } from "./gitlab-service.js";
+/**
+ * Open composition boundary for forge adapters. Resolver code depends only on
+ * these registration hooks, so a new adapter does not require another branch.
+ */
+export class ForgeRegistry {
+    constructor(entries = []) {
+        _ForgeRegistry_instances.add(this);
+        _ForgeRegistry_adapters.set(this, new Map());
+        _ForgeRegistry_warnedAmbiguousHosts.set(this, new Set());
+        for (const [forge, adapter] of entries) {
+            this.register(forge, adapter);
+        }
+    }
+    register(forge, adapter) {
+        const normalizedForge = parseForgeId(forge);
+        if (!normalizedForge) {
+            throw new Error(`Invalid forge adapter id: ${forge}`);
+        }
+        if (__classPrivateFieldGet(this, _ForgeRegistry_adapters, "f").has(normalizedForge)) {
+            throw new Error(`Forge adapter already registered: ${normalizedForge}`);
+        }
+        __classPrivateFieldGet(this, _ForgeRegistry_adapters, "f").set(normalizedForge, adapter);
+        return () => {
+            if (__classPrivateFieldGet(this, _ForgeRegistry_adapters, "f").get(normalizedForge) === adapter) {
+                __classPrivateFieldGet(this, _ForgeRegistry_adapters, "f").delete(normalizedForge);
+            }
+        };
+    }
+    ids() {
+        return [...__classPrivateFieldGet(this, _ForgeRegistry_adapters, "f").keys()];
+    }
+    has(forge) {
+        const normalizedForge = parseForgeId(forge);
+        return normalizedForge ? __classPrivateFieldGet(this, _ForgeRegistry_adapters, "f").has(normalizedForge) : false;
+    }
+    create(forge) {
+        const normalizedForge = parseForgeId(forge);
+        if (!normalizedForge) {
+            return null;
+        }
+        const adapter = __classPrivateFieldGet(this, _ForgeRegistry_adapters, "f").get(normalizedForge);
+        return adapter ? adapter.createService() : null;
+    }
+    matchHost(host) {
+        const matches = [];
+        for (const [forge, adapter] of __classPrivateFieldGet(this, _ForgeRegistry_adapters, "f")) {
+            if (adapter.matchesHost?.(host)) {
+                matches.push(forge);
+            }
+        }
+        if (matches.length > 1) {
+            __classPrivateFieldGet(this, _ForgeRegistry_instances, "m", _ForgeRegistry_warnAmbiguous).call(this, "matched", host, matches);
+            return null;
+        }
+        return matches[0] ?? null;
+    }
+    async probeHost(host) {
+        const entries = [...__classPrivateFieldGet(this, _ForgeRegistry_adapters, "f")];
+        // allSettled, not all: a third-party probe that throws means "not this
+        // forge", never a crash of the shared resolution path.
+        const settled = await Promise.allSettled(entries.map(async ([, adapter]) => adapter.probeHost ? await adapter.probeHost(host) : false));
+        const matches = entries
+            .filter((_, index) => {
+            const result = settled[index];
+            return result.status === "fulfilled" && result.value === true;
+        })
+            .map(([forge]) => forge);
+        if (matches.length > 1) {
+            __classPrivateFieldGet(this, _ForgeRegistry_instances, "m", _ForgeRegistry_warnAmbiguous).call(this, "recognized", host, matches);
+            return null;
+        }
+        return matches[0] ?? null;
+    }
+}
+_ForgeRegistry_adapters = new WeakMap(), _ForgeRegistry_warnedAmbiguousHosts = new WeakMap(), _ForgeRegistry_instances = new WeakSet(), _ForgeRegistry_warnAmbiguous = function _ForgeRegistry_warnAmbiguous(verb, host, matches) {
+    const key = `${verb}:${host}`;
+    if (__classPrivateFieldGet(this, _ForgeRegistry_warnedAmbiguousHosts, "f").has(key)) {
+        return;
+    }
+    __classPrivateFieldGet(this, _ForgeRegistry_warnedAmbiguousHosts, "f").add(key);
+    console.warn(`Multiple forge adapters ${verb} host ${host}: ${matches.join(", ")}`);
+};
+function parseForgeId(forge) {
+    const normalized = forge.trim().toLowerCase();
+    return /^[a-z0-9][a-z0-9._-]*$/.test(normalized) ? normalized : null;
+}
+/**
+ * Build a host matcher from a forge's declared cloud hosts in the manifest, so
+ * the registry never hardcodes a host list. Returns undefined for forges with
+ * no cloud hosts (recognized only by runtime probe, e.g. Forgejo).
+ */
+function matchesCloudHost(forgeId) {
+    const hosts = getForgeDefinition(forgeId)?.cloudHosts;
+    if (!hosts || hosts.length === 0) {
+        return undefined;
+    }
+    const normalized = new Set(hosts.map(normalizeHost));
+    return (host) => normalized.has(normalizeHost(host));
+}
+export const defaultForgeRegistry = new ForgeRegistry([
+    // GitHub Enterprise Server is recognized at runtime by probeHost, exactly like
+    // self-hosted GitLab/Gitea: github.com short-circuits via matchHost, so the
+    // probe only runs on non-cloud hosts. The PR-status poll gates on the resolver
+    // alone (no cloud-identity check), so a probed GHES host polls normally.
+    [
+        "github",
+        {
+            createService: createGitHubService,
+            matchesHost: matchesCloudHost("github"),
+            probeHost: probeGitHubHost,
+        },
+    ],
+    [
+        "gitlab",
+        {
+            createService: createGitLabService,
+            matchesHost: matchesCloudHost("gitlab"),
+            probeHost: probeGitLabHost,
+        },
+    ],
+    [
+        "gitea",
+        {
+            createService: createGiteaService,
+            matchesHost: matchesCloudHost("gitea"),
+            probeHost: async (host) => (await resolveGiteaFamilyForge(host)) === "gitea",
+        },
+    ],
+    [
+        "forgejo",
+        {
+            createService: createGiteaService,
+            probeHost: async (host) => (await resolveGiteaFamilyForge(host)) === "forgejo",
+        },
+    ],
+    ["codeberg", { createService: createGiteaService, matchesHost: matchesCloudHost("codeberg") }],
+]);
+export function createForgeService(forge) {
+    return defaultForgeRegistry.create(forge);
+}
+export function probeRegisteredForgeHost(host) {
+    return defaultForgeRegistry.probeHost(host);
+}
+//# sourceMappingURL=forge-registry.js.map

package/dist/server/services/forge-resolver.d.ts

@@ -0,0 +1,38 @@
+import { type SshHostnameResolver } from "../utils/ssh-hostname.js";
+import type { ForgeService } from "./forge-service.js";
+export interface ForgeResolution {
+    /** Registered forge id, e.g. "github" or "gitlab". */
+    forge: string;
+    /** Remote host the cwd resolves to, e.g. "github.com" or "gitlab.example.com". */
+    host: string;
+    /** Adapter for {@link forge}, shared across resolutions of the same forge. */
+    service: ForgeService;
+}
+/** Probe a host for a forge id when the name heuristic is inconclusive. */
+export type ForgeHostProbe = (host: string) => Promise<string | null>;
+export interface CreateForgeResolverOptions {
+    resolveRemoteUrl?: (cwd: string) => Promise<string | null>;
+    createService?: (forge: string) => ForgeService | null;
+    probeForge?: ForgeHostProbe;
+    resolveSshHostname?: SshHostnameResolver;
+    now?: () => number;
+}
+export interface ForgeResolver {
+    /** Resolve the forge for a working directory, or null when none applies. */
+    resolve(cwd: string): Promise<ForgeResolution | null>;
+    /** Resolve from a known origin remote URL using only the name heuristic + probe cache. */
+    resolveFromRemoteUrl(remoteUrl: string | null): ForgeResolution | null;
+    /** Resolve from a known origin remote URL, running the per-host probe when needed. */
+    resolveFromRemoteUrlAsync(remoteUrl: string | null): Promise<ForgeResolution | null>;
+    /**
+     * Invalidate every cached adapter's state for a cwd. Routed through the
+     * resolver so invalidation hits the same adapter instance the poller reads,
+     * regardless of which forge backs the workspace.
+     */
+    invalidate(cwd: string): void;
+}
+export declare function parseRemoteHost(url: string): string | null;
+/** Map a remote host through the matchers owned by registered adapters. */
+export declare function forgeForHost(host: string): string | null;
+export declare function createForgeResolver(options?: CreateForgeResolverOptions): ForgeResolver;
+//# sourceMappingURL=forge-resolver.d.ts.map