@shardflux/cli 0.15.2 → 0.17.0

package/dist/cli-proxy.d.ts

@@ -0,0 +1,325 @@
+import type { Handler, Ctx } from './commands.js';
+import type { Values } from './args.js';
+import type { EnsureResult, HubCloud, HubInfo } from './cli-proxy-hub.js';
+import type { HomeProject } from './cli-proxy-hub.js';
+/** Runs a program, stdout on success, null when it is missing or fails (detection never throws). */
+export type ProgramRunner = (program: string, args: string[]) => Promise<string | null>;
+export declare const runProgram: ProgramRunner;
+/**
+ * The programs and probes detection, stop and the launchd install use by default. The CLI test support replaces them,
+ * so no test inspects, stops or replaces a CLIProxyAPI or forwarder running on the developer's computer.
+ */
+export declare const cliProxyTools: {
+    run: ProgramRunner;
+    answers: (port: number) => Promise<boolean>;
+    identity: (port?: number) => Promise<ForwarderIdentity | null>;
+    inVm: () => boolean;
+    kill: (pid: number) => void;
+};
+/** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
+export declare const FORWARD_LABEL = "dev.shardflux.cli-proxy-forward";
+/** Where every VM finds the hub info (the machine template carries it). */
+export declare const VM_HUB_INFO_PATH = "/home/user/.config/shardflux-cli-proxy.json";
+export interface LocalLogin {
+    file: string;
+    provider: string | null;
+    email: string | null;
+}
+/** A Docker container that publishes the port; `cliProxy` when its image or name is CLIProxyAPI's. */
+export interface LocalContainer {
+    id: string;
+    name: string;
+    image: string;
+    cliProxy: boolean;
+}
+export interface LocalListener {
+    pid: number;
+    command: string;
+    /** The process's executable (ps comm). */
+    executable: string;
+    /** Shardflux's own forwarder (`shard cli-proxy forward`, `sf-agent cli-proxy-forward`) holds the port. */
+    forwarder: boolean;
+    /** Verified to be CLIProxyAPI by its executable name (cli-proxy-api, cliproxyapi). Only such a process is offered to stop. */
+    cliProxy: boolean;
+    /** The listener is Docker's port proxy for this container (never the Docker process itself). */
+    container: LocalContainer | null;
+}
+export type LocalService = {
+    kind: 'brew';
+    formula: string;
+    label: string;
+} | {
+    kind: 'launchd';
+    label: string;
+    plist: string;
+};
+export interface LocalCliProxy {
+    /** The auth directory (`auth-dir` of the config, default ~/.cli-proxy-api). */
+    authDir: string;
+    /** Every auth directory a CLIProxyAPI on this computer reads: the config's, and ~/.cli-proxy-api while it holds logins. */
+    authDirs: string[];
+    /** One per auth file: provider and email only (never token contents). */
+    logins: LocalLogin[];
+    configPath: string | null;
+    /** The port it listens on: the config's `port` (`server.port` in the v8 layout), default 8317. */
+    port: number;
+    /** What listens on that port now. */
+    listener: LocalListener | null;
+    /** The Homebrew service or launchd agent that runs it. */
+    service: LocalService | null;
+}
+export interface DetectOptions {
+    env?: Record<string, string | undefined>;
+    home?: string;
+    /** An explicit config file (shard cli-proxy import --config). */
+    configPath?: string;
+    run?: ProgramRunner;
+    platform?: NodeJS.Platform;
+}
+/** The listening port of a CLIProxyAPI config (either layout), or null when it names none. */
+export declare function configPort(doc: unknown): number | null;
+/**
+ * CLIProxyAPI on this computer: its auth files (provider and email of each), its config and port, the process that
+ * listens there and the service that runs it. Null when there is none of these.
+ */
+export declare function detectLocalCliProxy(opts?: DetectOptions): Promise<LocalCliProxy | null>;
+/**
+ * Who an auth file signs in as: its provider (`type`) and every identifying field it has (email, account, organization,
+ * workspace, user and project ids), from its JSON. Two files are the same login only when they have the same provider
+ * and the same fields with the same values: one email can sign in to several accounts or workspaces, so a file that
+ * names a different (or one more) account is another login. A file without any is only itself (its path).
+ */
+export declare function loginIdentity(text: string, file: string): string;
+/**
+ * After the hub has the logins: moves every auth file out of each directory a local CLIProxyAPI reads, into a sibling
+ * `<dir>.moved-to-shardflux` (0700; files keep their 0600), so a local copy started again has no tokens to refresh.
+ * Other files (a config.yaml, logs) stay where they are.
+ */
+export declare function moveAuthFilesAside(dirs: readonly string[], now?: Date): Array<{
+    from: string;
+    to: string;
+    files: number;
+}>;
+/** Whether something accepts connections on 127.0.0.1:port (also a listener on all interfaces). */
+export declare function portAnswers(port: number, host?: string): Promise<boolean>;
+/** How it is stopped for good: the steps, and the same as one command line to show. */
+export interface StopPlan {
+    line: string;
+    steps: Array<{
+        run: string[];
+    } | {
+        kill: number;
+    } | {
+        move: [string, string];
+    }>;
+}
+/**
+ * A Homebrew service: `brew services stop` (it also leaves login). Another launchd agent: bootout, disable, and its plist
+ * moved aside, so it cannot come back at login. A plain process: ending it.
+ */
+export declare function stopPlan(local: LocalCliProxy, uid?: number): StopPlan | null;
+export interface StopDeps {
+    run?: ProgramRunner;
+    kill?: (pid: number) => void;
+    answers?: (port: number) => Promise<boolean>;
+    /** Shardflux's own forwarder answers on the port (nothing to stop). */
+    ours?: () => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Longest wait for the user to stop it themselves (default 5 minutes). */
+    waitMs?: number;
+    uid?: number;
+}
+/**
+ * Stops the local CLIProxyAPI on its own port so only the hosted copy refreshes the logins. A Homebrew service is
+ * stopped with `brew services stop` (said first); a process or another launchd agent only with the user's consent
+ * ([Y/n] on a terminal, defaulting to yes; --yes otherwise): declined, the exact command is shown and the port is
+ * watched until it is free. Refuses when something starts it again.
+ */
+export declare function stopLocalCliProxy(ctx: Ctx, local: LocalCliProxy, values?: Values, deps?: StopDeps): Promise<{
+    result: 'none' | 'stopped';
+    plan: StopPlan | null;
+}>;
+/** How the user starts the local CLIProxyAPI again (`shard cli-proxy export` names it). */
+export declare function startLine(local: LocalCliProxy, uid?: number): string;
+export interface PlistOptions {
+    node: string;
+    script: string;
+    configDir: string;
+    apiUrl: string;
+    logFile: string;
+    path?: string;
+}
+/** The launchd agent: `shard cli-proxy forward` at login, started again whenever it exits. */
+export declare function forwarderPlist(o: PlistOptions): string;
+export declare function forwarderPlistPath(home: string): string;
+/** Whether Shardflux's forwarder answers on 127.0.0.1:port, and for which hub. */
+export interface ForwarderIdentity {
+    hub: string | null; /** `mac`: shard cli-proxy forward; `vm`: sf-agent cli-proxy-forward. */
+    kind: 'mac' | 'vm';
+    version: string | null;
+}
+/** Whether Shardflux's forwarder (this computer's, or a VM's sf-agent) answers on 127.0.0.1:port, and for which hub. */
+export declare function forwarderIdentity(port?: number): Promise<ForwarderIdentity | null>;
+/** A Shardflux VM (its guest agent is installed): the hub is set up from the computer where CLIProxyAPI runs. */
+export declare function inShardfluxVm(): boolean;
+export interface LaunchdDeps {
+    run?: ProgramRunner;
+    uid?: number;
+    identity?: () => Promise<ForwarderIdentity | null>;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export declare function refreshForwarderAgent(env: Record<string, string | undefined>, dir: string, deps?: {
+    run?: ProgramRunner;
+    uid?: number;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;
+/** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
+export declare function installForwarderAgent(ctx: Ctx, apiUrl: string, deps?: LaunchdDeps): Promise<string>;
+/**
+ * Puts the hub info into the machine template (opening the machine VM like `shard machine`, then saving it), so every
+ * new VM's forwarder reaches the hub. Skipped when the saved machine already carries this hub info.
+ */
+export declare function saveHubInfoToMachine(ctx: Ctx, info: HubInfo, opts?: {
+    machine?: MachineAccess;
+    current?: () => Promise<HubInfo>;
+}): Promise<{
+    version: number;
+    saved: boolean;
+}>;
+/**
+ * The hub's home: the organization's first project (oldest), listed with the user session. Null when signed out, so a
+ * new hub is never created by guesswork in another project.
+ */
+export declare function homeProject(ctx: Ctx, organizationId: string): Promise<HomeProject | null>;
+/** The account's machine as the import changes it: open its VM (as `shard machine` does), write a file, save. */
+export interface MachineAccess {
+    /** The saved machine version. */
+    version(): Promise<number>;
+    open(): Promise<{
+        write(path: string, text: string): Promise<void>;
+        save(): Promise<number>;
+    }>;
+}
+export declare function sdkMachine(ctx: Ctx): MachineAccess;
+export interface HubAccount {
+    provider: string;
+    email: string | null;
+    status: string | null;
+    disabled: boolean;
+}
+/** The hub's logins from its management API (wakes the hub). */
+export declare function hubAccounts(info: HubInfo, timeoutMs?: number): Promise<HubAccount[]>;
+/** Whether the hub answers /healthz through its callback URL, and the edge's reason when it does not. */
+export declare function hubHealth(info: HubInfo, timeoutMs?: number): Promise<{
+    ok: boolean;
+    reason: string | null;
+}>;
+export interface ImportOptions {
+    values?: Values;
+    /** What was found on this computer (detectLocalCliProxy() when omitted). */
+    local?: LocalCliProxy | null;
+    hub?: HubCloud;
+    stop?: StopDeps;
+    launchd?: LaunchdDeps | false;
+    /** Save the hub info into the machine template (default true). */
+    machine?: boolean;
+    platform?: NodeJS.Platform;
+}
+export interface ImportResult {
+    hub: {
+        workspace_id: string;
+        created: boolean;
+        process: EnsureResult['process'];
+    };
+    /**
+     * added: accounts this import gave the hub; already: accounts the hub had (its tokens stay); moved_aside: where this
+     * computer's auth files went once the hub had them (`<dir>.moved-to-shardflux`).
+     */
+    logins: {
+        uploaded: string[];
+        kept: string[];
+        added: Array<{
+            provider: string | null;
+            email: string | null;
+        }>;
+        already: Array<{
+            provider: string | null;
+            email: string | null;
+        }>;
+        moved_aside: string[];
+    };
+    /** Whether the hub's config was made from this computer's, or the hub kept the one it has. */
+    config: 'from_this_computer' | 'kept';
+    local: 'none' | 'stopped';
+    /** The port the local CLIProxyAPI listened on; this computer's forwarder serves 8317. */
+    port: number;
+    forwarder: {
+        launchd: string | null;
+    };
+    /** The machine version that carries the hub info, or why it could not be saved (run the import again). */
+    machine: {
+        version: number;
+        saved: boolean;
+    } | {
+        error: string;
+    } | null;
+    dropped: string[];
+    accounts: HubAccount[] | null;
+}
+/**
+ * Moves CLIProxyAPI from this computer into the account (or connects this computer to the account's hub): ensure the
+ * hub from the user's config, stop the local copy, upload the auth files the hub does not have yet (never overwriting
+ * one: the hub's copy may hold a newer refresh token), start the forwarder on 127.0.0.1:8317 and put the hub info into
+ * the machine template.
+ */
+export declare function importCliProxy(ctx: Ctx, opts?: ImportOptions): Promise<ImportResult>;
+export interface ExportOptions {
+    values?: Values;
+    hub?: HubCloud;
+    launchd?: LaunchdDeps | false;
+    platform?: NodeJS.Platform;
+}
+export interface ExportResult {
+    /** Where the logins were written (the auth directory the import took them from, else ~/.cli-proxy-api). */
+    auth_dir: string;
+    logins: string[];
+    hub: {
+        workspace_id: string;
+        state: 'stopped';
+        logins_set_aside: string | null;
+    };
+    forwarder: {
+        removed: boolean;
+    };
+    /** The command that starts the local CLIProxyAPI again. */
+    start: string;
+}
+/**
+ * Brings the hub's logins back to this computer: the hub stops first (from then on only this computer refreshes
+ * them), its auth files as last refreshed are written to the local auth directory (0600), the hub sets its copies
+ * aside (a later import uploads this computer's), this computer's forwarder agent goes, and the hub is suspended.
+ * Undone by `shard cli-proxy import`.
+ */
+export declare function exportCliProxy(ctx: Ctx, opts?: ExportOptions): Promise<ExportResult>;
+/**
+ * After the edge refused the hub's callback URL (`callback_invalid`: the API key that created it was revoked):
+ * replaces the URLs the edge refuses (under the hub's lock), saves them locally and gives VMs the new VM address.
+ */
+export declare function renewHubCallbacks(ctx: Ctx, opts?: {
+    hub?: HubCloud;
+    machine?: MachineAccess;
+}): Promise<{
+    info: HubInfo;
+    vms: Promise<{
+        machine: number | null;
+        note: string | null;
+    }>;
+}>;
+/** Removes the launchd agent (tests and a future `shard cli-proxy forward --stop`). */
+export declare function removeForwarderAgent(home: string, run?: ProgramRunner, uid?: number): Promise<void>;
+export declare const CLI_PROXY_HANDLERS: Record<string, Handler>;