sailfork / t3code-github / packages/ source-control-core/ src/ server/ discovery.ts

import * as NodeUtil from "node:util";
import {
  VcsProcessSpawnError,
  type SourceControlProviderAuth,
  type SourceControlProviderDiscoveryItem,
  type SourceControlProviderInfo,
  type SourceControlProviderKind,
} from "@t3tools/contracts";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { SpawnExecutableResolution } from "@t3tools/shared/shell";
import type * as Cause from "effect/Cause";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as PlatformError from "effect/PlatformError";
import * as Result from "effect/Result";
import * as Schema from "effect/Schema";

import type * as SourceControlProvider from "./SourceControlProvider.ts";
import type * as SourceControlHost from "./SourceControlHost.ts";

export interface SourceControlAuthProbeInput {
  readonly stdout: string;
  readonly stderr: string;
  readonly exitCode: SourceControlHost.SourceControlProcessOutput["exitCode"];
}

export interface SourceControlUnknownRemoteRefinementInput {
  readonly cwd: string;
  readonly context: SourceControlProvider.SourceControlProviderContext;
  readonly auth: SourceControlAuthProbeInput;
}

interface SourceControlDiscoverySpecBase {
  readonly kind: SourceControlProviderKind;
  readonly label: string;
  readonly installHint: string;
}

export type SourceControlCliDiscoverySpec = SourceControlDiscoverySpecBase & {
  readonly type: "cli";
  readonly executable: string;
  readonly versionArgs: ReadonlyArray<string>;
  readonly authArgs: ReadonlyArray<string>;
  /** Asked once when `authArgs` reports signed out; its answer counts only when it finds a sign-in. */
  readonly authRetryArgs?: ReadonlyArray<string>;
  readonly remoteRefinementArgs?: (
    context: SourceControlProvider.SourceControlProviderContext,
  ) => ReadonlyArray<string>;
  readonly probeTimeoutMs?: number;
  readonly parseAuth: (input: SourceControlAuthProbeInput) => SourceControlProviderAuth;
  /** `null` when the CLI holds nothing for the remote; `undefined` when its output cannot say. */
  readonly refineUnknownRemote?: (
    input: SourceControlUnknownRemoteRefinementInput,
  ) => SourceControlProviderInfo | null | undefined;
};

export type SourceControlApiDiscoverySpec = SourceControlDiscoverySpecBase & {
  readonly type: "api";
  readonly probeAuth: Effect.Effect<SourceControlProviderAuth, never>;
};

export type SourceControlManagedCliDiscoverySpec = SourceControlDiscoverySpecBase & {
  readonly type: "managed-cli";
  readonly probe: (cwd: string) => Effect.Effect<SourceControlProviderDiscoveryItem>;
  /** Null includes missing CLIs. Failure means unknown and must not be cached by the registry. */
  readonly refineUnknownRemote: (input: {
    readonly cwd: string;
    readonly context: SourceControlProvider.SourceControlProviderContext;
  }) => Effect.Effect<SourceControlProviderInfo | null, Cause.YieldableError>;
};

export type SourceControlProviderDiscoverySpec =
  | SourceControlCliDiscoverySpec
  | SourceControlManagedCliDiscoverySpec
  | SourceControlApiDiscoverySpec;

type SourceControlCliRemoteRefinementSpec = SourceControlCliDiscoverySpec & {
  readonly refineUnknownRemote: NonNullable<SourceControlCliDiscoverySpec["refineUnknownRemote"]>;
};

const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
/** An API host that stalls must not hold the whole discovery answer behind it. */
const API_PROBE_TIMEOUT = "3 seconds";

function probeTimeoutMs(spec: SourceControlCliDiscoverySpec): number {
  return spec.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
}

interface DiscoveryProbeResult {
  readonly kind: SourceControlProviderKind;
  readonly label: string;
  readonly executable: string;
  readonly status: "available" | "missing";
  readonly version: Option.Option<string>;
  readonly installHint: string;
  readonly detail: Option.Option<string>;
}

export function firstNonEmptyLine(text: string): Option.Option<string> {
  const line = NodeUtil.stripVTControlCharacters(text)
    .split(/\r?\n/)
    .map((entry) => entry.trim())
    .find((entry) => entry.length > 0);
  return line === undefined ? Option.none() : Option.some(line);
}

export function detailFromCause(cause: unknown): Option.Option<string> {
  if (cause instanceof Error && cause.message.trim().length > 0) {
    return Option.some(cause.message.trim());
  }
  return Option.none();
}

function authAccount(account: string | undefined): Option.Option<string> {
  const trimmed = account?.trim();
  return trimmed === undefined || trimmed.length === 0 ? Option.none() : Option.some(trimmed);
}

function authHost(host: string | undefined): Option.Option<string> {
  const trimmed = host?.trim();
  return trimmed === undefined || trimmed.length === 0 ? Option.none() : Option.some(trimmed);
}

function authDetail(detail: string | undefined): Option.Option<string> {
  const trimmed = detail?.trim();
  return trimmed === undefined || trimmed.length === 0 ? Option.none() : Option.some(trimmed);
}

export function providerAuth(input: {
  readonly status: SourceControlProviderAuth["status"];
  readonly account?: string | undefined;
  readonly host?: string | undefined;
  readonly detail?: string | undefined;
}): SourceControlProviderAuth {
  return {
    status: input.status,
    account: authAccount(input.account),
    host: authHost(input.host),
    detail: authDetail(input.detail),
  };
}

function unknownAuth(detail?: string): SourceControlProviderAuth {
  return providerAuth({ status: "unknown", detail });
}

export function combinedAuthOutput(input: SourceControlAuthProbeInput): string {
  const parts: string[] = [];
  for (const entry of [input.stdout, input.stderr]) {
    if (entry.trim().length > 0) {
      parts.push(entry);
    }
  }
  return parts.join("\n");
}

function sanitizedAuthLines(text: string): ReadonlyArray<string> {
  const lines: string[] = [];
  for (const entry of text.split(/\r?\n/)) {
    const line = entry.trim();
    if (line.length === 0) continue;
    if (/^[-\s]*token(?:\s+scopes?)?:/iu.test(line)) continue;
    lines.push(line);
  }
  return lines;
}

export function firstSafeAuthLine(text: string): string | undefined {
  return sanitizedAuthLines(text)[0];
}

export function parseCliHost(text: string): string | undefined {
  return sanitizedAuthLines(text)
    .map((line) => line.replace(/^[^a-z0-9]+/iu, ""))
    .find((line) => /^[a-z0-9][a-z0-9.-]*(?::\d+)?$/iu.test(line));
}

export function matchFirst(text: string, patterns: ReadonlyArray<RegExp>): string | undefined {
  for (const pattern of patterns) {
    const match = pattern.exec(text);
    const value = match?.[1]?.trim();
    if (value && value.length > 0) return value;
  }
  return undefined;
}

function isCliRemoteRefinementSpec(
  spec: SourceControlProviderDiscoverySpec,
): spec is SourceControlCliRemoteRefinementSpec {
  return spec.type === "cli" && spec.refineUnknownRemote !== undefined;
}

function probeCli(input: {
  readonly spec: SourceControlCliDiscoverySpec;
  readonly process: SourceControlHost.SourceControlHost["Service"]["process"];
  readonly cwd: string;
}): Effect.Effect<DiscoveryProbeResult> {
  return input.process
    .run({
      operation: "source-control.discovery.probe",
      command: input.spec.executable,
      args: input.spec.versionArgs,
      cwd: input.cwd,
      timeoutMs: probeTimeoutMs(input.spec),
      maxOutputBytes: 8_000,
      appendTruncationMarker: true,
    })
    .pipe(
      Effect.map(
        (result) =>
          ({
            kind: input.spec.kind,
            label: input.spec.label,
            executable: input.spec.executable,
            status: "available" as const,
            version: Option.orElse(firstNonEmptyLine(result.stdout), () =>
              firstNonEmptyLine(result.stderr),
            ),
            installHint: input.spec.installHint,
            detail: Option.none<string>(),
          }) satisfies DiscoveryProbeResult,
      ),
      Effect.catch((cause) =>
        Effect.gen(function* () {
          const installHint = yield* unavailableInstallHint(
            input.spec.executable,
            input.spec.installHint,
            cause,
          );
          return {
            kind: input.spec.kind,
            label: input.spec.label,
            executable: input.spec.executable,
            status: "missing" as const,
            version: Option.none<string>(),
            installHint,
            detail: detailFromCause(cause),
          } satisfies DiscoveryProbeResult;
        }),
      ),
    );
}

export function probeSourceControlProvider(input: {
  readonly spec: SourceControlProviderDiscoverySpec;
  readonly process: SourceControlHost.SourceControlHost["Service"]["process"];
  readonly cwd: string;
}): Effect.Effect<SourceControlProviderDiscoveryItem> {
  if (input.spec.type === "managed-cli") return input.spec.probe(input.cwd);
  if (input.spec.type === "api") {
    return input.spec.probeAuth.pipe(
      Effect.timeoutOption(API_PROBE_TIMEOUT),
      Effect.map(
        Option.getOrElse(() =>
          unknownAuth("The hosting service did not answer in time. Refresh to try again."),
        ),
      ),
      Effect.map(
        (auth) =>
          ({
            kind: input.spec.kind,
            label: input.spec.label,
            status: "available" as const,
            version: Option.none<string>(),
            installHint: input.spec.installHint,
            detail: Option.none<string>(),
            auth,
          }) satisfies SourceControlProviderDiscoveryItem,
      ),
    );
  }

  const spec = input.spec;
  const runAuth = (args: ReadonlyArray<string>) =>
    input.process
      .run({
        operation: "source-control.discovery.auth",
        command: spec.executable,
        args,
        cwd: input.cwd,
        allowNonZeroExit: true,
        timeoutMs: probeTimeoutMs(spec),
        maxOutputBytes: 8_000,
        appendTruncationMarker: true,
      })
      .pipe(
        Effect.map(spec.parseAuth),
        Effect.catch((cause) =>
          Effect.succeed(unknownAuth(Option.getOrUndefined(detailFromCause(cause)))),
        ),
      );
  const retryArgs = spec.authRetryArgs;
  const auth =
    retryArgs === undefined
      ? runAuth(spec.authArgs)
      : runAuth(spec.authArgs).pipe(
          Effect.filterOrElse(
            (result) => result.status !== "unauthenticated",
            (signedOut) =>
              runAuth(retryArgs).pipe(
                Effect.map((retry) => (retry.status === "authenticated" ? retry : signedOut)),
              ),
          ),
        );

  // The auth check does not depend on the version output, so both spawn at once.
  return Effect.all(
    [
      probeCli({
        spec,
        process: input.process,
        cwd: input.cwd,
      }),
      auth,
    ],
    { concurrency: "unbounded" },
  ).pipe(
    Effect.map(
      ([item, auth]) =>
        ({
          ...item,
          auth:
            item.status === "available"
              ? auth
              : unknownAuth("Hosting integration command was not found on the server PATH."),
        }) satisfies SourceControlProviderDiscoveryItem,
    ),
  );
}

const isVcsProcessSpawnError = Schema.is(VcsProcessSpawnError);

/** The spawner checks cwd first, so ChildProcess NotFound identifies the executable. */
export function isMissingExecutable(error: unknown): boolean {
  return (
    isVcsProcessSpawnError(error) &&
    PlatformError.isPlatformError(error.cause) &&
    error.cause.reason._tag === "NotFound" &&
    error.cause.reason.module === "ChildProcess"
  );
}

// macOS's EBADARCH, which Node has no name for: the binary is built for another CPU, such as an
// Intel-only `gh` on Apple Silicon without Rosetta.
const BAD_CPU_TYPE_ERRNO = -86;

export const unavailableInstallHint = Effect.fn("discovery.unavailableInstallHint")(function* (
  executable: string,
  installHint: string,
  cause: unknown,
) {
  const platform = yield* HostProcess.Platform;
  if (
    platform !== "darwin" ||
    !isVcsProcessSpawnError(cause) ||
    !(cause.cause instanceof Error) ||
    !("errno" in cause.cause) ||
    cause.cause.errno !== BAD_CPU_TYPE_ERRNO
  ) {
    return installHint;
  }
  const resolveExecutable = yield* SpawnExecutableResolution;
  const path = resolveExecutable(executable, platform, yield* HostProcess.Environment);
  const architecture = yield* HostProcess.Architecture;
  return `\`${path ?? executable}\` is built for another CPU architecture, so this ${architecture} machine cannot run it. Remove or replace it. ${installHint}`;
});

class UnknownRemoteUnanswered extends Schema.TaggedError<UnknownRemoteUnanswered>()(
  "UnknownRemoteUnanswered",
  {},
) {}

export interface UnknownRemoteVerdict {
  readonly provider: SourceControlProviderInfo | null;
  readonly settled: boolean;
}

function refineWithSpec(input: {
  readonly spec: SourceControlProviderDiscoverySpec;
  readonly process: SourceControlHost.SourceControlHost["Service"]["process"];
  readonly cwd: string;
  readonly context: SourceControlProvider.SourceControlProviderContext;
}): Effect.Effect<SourceControlProviderInfo | null, Cause.YieldableError> {
  const { spec, context } = input;
  if (spec.type === "managed-cli") {
    return spec.refineUnknownRemote({ cwd: input.cwd, context });
  }
  if (!isCliRemoteRefinementSpec(spec)) return Effect.succeed(null);
  return input.process
    .run({
      operation: "source-control.discovery.refine-unknown-remote",
      command: spec.executable,
      args: spec.remoteRefinementArgs?.(context) ?? spec.authArgs,
      cwd: input.cwd,
      allowNonZeroExit: true,
      timeoutMs: probeTimeoutMs(spec),
      maxOutputBytes: 8_000,
      appendTruncationMarker: true,
    })
    .pipe(
      Effect.catchIf(isMissingExecutable, () => Effect.void),
      Effect.flatMap((auth) => {
        const provider =
          auth === undefined ? null : spec.refineUnknownRemote({ cwd: input.cwd, context, auth });
        return provider === undefined
          ? Effect.fail(new UnknownRemoteUnanswered())
          : Effect.succeed(provider);
      }),
    );
}

export const refineUnknownRemoteProvider = Effect.fn("refineUnknownRemoteProvider")(
  function* (input: {
    readonly specs: ReadonlyArray<SourceControlProviderDiscoverySpec>;
    readonly process: SourceControlHost.SourceControlHost["Service"]["process"];
    readonly cwd: string;
    readonly context: SourceControlProvider.SourceControlProviderContext;
  }): Effect.fn.Return<UnknownRemoteVerdict> {
    const results = yield* Effect.forEach(input.specs, (spec) =>
      refineWithSpec({ ...input, spec }).pipe(Effect.result),
    );
    // An earlier integration that could not answer might have claimed this host.
    let settled = true;
    for (const result of results) {
      if (Result.isFailure(result)) settled = false;
      else if (result.success !== null) return { provider: result.success, settled };
    }
    return { provider: null, settled };
  },
);