/**
 * Types for bin/lifecycle.mjs.
 *
 * Hand-written rather than inferred: turning on `allowJs` would pull bin/*.mjs into the compiled
 * program and emit it under dist/, changing the packaged layout for the sake of a type check. This
 * file exists so `tsc --noEmit` can see the module the tests import, and emits nothing.
 *
 * It is a DECLARATION, so it cannot drift silently in the direction that matters: if a signature
 * here stops matching the implementation, the tests that call it stop compiling.
 */

/** The pid listening on `port` in `netstat -ano -p TCP` output, or null. */
export function parseNetstatListener(stdout: string, port: number | string): number | null;

/** The result of a port lookup: a pid, nobody, or that nobody could look. */
export interface Listener { pid: number | null; checked: boolean; why?: string }
type ListenerLookup = (port: number) => Listener;
/** The root variables of a listening process, or null when they cannot be read. */
type EnvLookup = (pid: number) => { XMESH_STATE_DIR?: string; XMESH_TEAM_ROOT?: string } | null;

/** Which runtime a client means: XMESH_URL; else the root's live lease; else XMESH_PORT, the root's port setting, or 8787. */
export interface Tenant {
  url: string;
  via: string;
  source: "XMESH_URL" | "lease" | "XMESH_PORT" | "setting" | "default";
  root: string;
  named: boolean;
  unverified: string | null;
}
export function tenantUrl(env?: Record<string, string | undefined>, opts?: { listener?: ListenerLookup }): Tenant;

/** The same directory, canonicalised (symlinks resolved), or resolved when it does not exist. */
export function canonDir(p: string): string;

/** One NAME=value variable out of `ps eww` output, read to the next variable so a value may contain spaces. */
export function envVarFromPs(text: string, name: string): string | null;

/** Which state root serves a URL's port: null for a remote URL, else what the listener lookup and its environment say. */
export type ListenerRoot =
  | { checked: false; why?: string }
  | { checked: true; pid: null }
  | { checked: true; pid: number; dir: string; via: "lease" | "XMESH_STATE_DIR" | "XMESH_TEAM_ROOT"; value: string }
  | { checked: true; pid: number; dir: null; why: string };
export function rootOfListeningPort(url: string, opts?: { root?: string | null; listener?: ListenerLookup; envOf?: EnvLookup }): ListenerRoot | null;

/** How a listener's root is named in a message. */
export function describeOwner(o: { via: string; value: string; dir: string }): string;

/** Whether a client may send the named root's credential to tenant.url; with the reason when it may not. */
export function namedRootGuard(tenant: Pick<Tenant, "url" | "via" | "root" | "named">, opts?: { listener?: ListenerLookup; envOf?: EnvLookup; credentialGiven?: boolean }):
  { ok: true; owner: ListenerRoot | null } | { ok: false; why: string };

/** The tenant `xmesh stop|restart|update` mean when no root is named and the default root has no live runtime, or null. */
export function servedRoot(env?: Record<string, string | undefined>, opts?: { listener?: ListenerLookup; envOf?: EnvLookup }):
  { url: string; pid: number; via: "XMESH_STATE_DIR" | "XMESH_TEAM_ROOT"; value: string; dir: string } | null;

/** The xmesh entrypoint inside a process command line, or null. */
export function parseEntrypoint(commandLine: string | null | undefined): string | null;

/** This CLI's own entrypoint path. */
export function ownEntry(): string;

/** What `xmesh restart` may start again, decided before anything is stopped: the running code's entry, this CLI's own
 *  when nothing runs, launchd's own program when supervised, or a refusal when the running code cannot be told. */
export function restartTarget(
  running: { pkgRoot?: string; why?: string | null } | null,
  supervised: boolean,
  own?: string,
): { entry: string } | { refuse: string };

/** Whether an entrypoint's package can actually boot (has a built dist). */
export function bootable(entry: string): { ok: true } | { ok: false; why: string };

/** Spawn a detached runtime from `entry` (default: this CLI's own), with `--foreground` unless told otherwise. Returns its pid. */
export function startDetached(entry?: string, args?: string[], env?: Record<string, string | undefined>): number | undefined;

/** Where a detached runtime writes what it says. */
export function daemonLog(): string;

/** Where the runtime keeps its web cockpit's passcode. */
export function passcodeFile(): string;

/** An environment for a runtime started on behalf of one coding-agent session, the session's identity taken out. */
export function runtimeEnv(env?: Record<string, string | undefined>): Record<string, string>;

/** Whether plain `xmesh` runs in the background: only at a terminal with no supervisor, container or --foreground. */
export function startMode(opts?: {
  args?: string[];
  env?: Record<string, string | undefined>;
  stdoutIsTTY?: boolean;
  exists?: (file: string) => boolean;
}): { mode: "foreground" | "background"; why: string };

/** Make sure the runtime is running, starting it detached when it is not; never a second one beside a live one. */
export function ensureRunning(opts?: {
  waitMs?: number;
  entry?: string;
  onStart?: () => void;
  onWait?: (w: { pid: number; port: number; waitMs: number }) => void;
  env?: Record<string, string | undefined>;
  listener?: ListenerLookup;
}): Promise<
  | { state: "running" | "started"; url: string; pid: number; version?: string }
  | { state: "failed"; why: string; log?: string }
>;

export function stop(opts?: { quiet?: boolean }): Promise<{
  stopped: boolean;
  reason?: string;
  port?: number;
  supervised?: string;
}>;

export function restart(opts?: { own?: string }): Promise<{ version: string; tree?: string } | null>;

export function update(opts?: { check?: boolean }): Promise<
  | { installed: string; latest: string; running: string | null; where: string; root: string }
  | { ok: false; reason?: string }
  | null
>;