/**
 * Types for bin/mcp-setup.mjs, hand-written for the same reason as lifecycle.d.mts: `allowJs` would pull bin/*.mjs into the compiled
 * program. It is a declaration, so a signature that stops matching makes the tests that call it stop compiling.
 */
export const BRIDGE: string;
export const CONFIG_NAME: string;

/** Whether git tracks a file: true, false, or unknown (and why). */
export function gitTracked(file: string): boolean | { unknown: string };

export function ensureBridge(opts?: {
  cwd?: string; url?: string; seat?: string; dryRun?: boolean;
  /** rewrite a .mcp.json that git tracks */
  force?: boolean;
  env?: Record<string, string | undefined>;
  tracked?: (file: string) => boolean | { unknown: string };
}): {
  action: "wired" | "repaired" | "seated" | "unchanged" | "skipped" | "refused";
  reason?: string; file?: string; bridge?: string; url?: string | null; seat?: string | null; previous?: string | null; tracked?: boolean | null;
};

/** What a write put in the file, in one line, or null when nothing was written. */
export function wroteLine(r: { action: string; file?: string; bridge?: string; url?: string | null; seat?: string | null; previous?: string | null }): string | null;

/** `xmesh mcp install --user`: this install's bridge, once for every project, at Claude Code's user scope. */
export function ensureUserBridge(opts?: {
  url?: string;
  home?: string;
  claude?: string;
  run?: (bin: string, args: string[]) => { status: number | null; stdout?: string; stderr?: string; error?: Error; refused?: string };
  dryRun?: boolean;
  env?: Record<string, string | undefined>;
}): {
  action: "wired" | "repaired" | "repointed" | "unchanged" | "kept" | "manual" | "failed" | "skipped";
  reason?: string; command?: string; config?: string; bridge?: string; url?: string;
};

/** Filesystem readers the Windows resolution is given in tests; the real ones by default. */
interface ShimFs { exists?: (file: string) => boolean; read?: (file: string) => string }

/** The `claude` CLI as a program to run without a shell: a script under this node, a native launcher itself, or refused. */
export function claudeProgram(bin: string, args: readonly string[], opts?: ShimFs & { platform?: NodeJS.Platform; env?: Record<string, string | undefined> }):
  { file: string; args: string[] } | { refused: string };

/** The script or native launcher a Windows shim hands its arguments to (the path before %* or $args), or null. */
export function shimEntry(shim: string, opts?: ShimFs): string | null;

export function report(r: unknown): string | null;