@solidrt/flux-types 0.0.11 → 0.0.14

package/modules/http.d.ts

@@ -0,0 +1,197 @@
+declare module "flux:http" {
+  /** Path parameters captured from a route pattern (e.g. ":page"). */
+  type RouteParams = Record<string, string>
+
+  /**
+   * The request passed to a handler: a standard {@link Request} plus the route
+   * params captured from the matched pattern.
+   */
+  type FluxRequest = Request & {
+    /**
+     * Route params from the matched pattern (e.g. `:page` -> `params.page`). An
+     * empty object for the `fetch` fallback, which matches no pattern.
+     */
+    params: RouteParams
+  }
+
+  /**
+   * What a handler may return: a string (sent as a 200 text response), a
+   * {@link Response}, or a promise of either. Returning nothing is only valid
+   * after `server.upgrade(req)` accepted a websocket; otherwise it becomes a 500.
+   */
+  type HandlerResult = string | Response | void | Promise<string | Response | void>
+
+  /**
+   * Handles a matched route or the `fetch` fallback. Receives the request (with
+   * captured `params`) and the running {@link Server}.
+   */
+  type RouteHandler = (req: FluxRequest, server: Server) => HandlerResult
+
+  /**
+   * A per-method route object, e.g. `{ GET, POST }`. A request whose method has
+   * no entry gets a 405 with an `Allow` header listing the defined methods.
+   */
+  type MethodRoutes = {
+    GET?: RouteHandler
+    HEAD?: RouteHandler
+    POST?: RouteHandler
+    PUT?: RouteHandler
+    DELETE?: RouteHandler
+    PATCH?: RouteHandler
+    OPTIONS?: RouteHandler
+  }
+
+  /**
+   * A value in the route table: a handler function, a static {@link Response}
+   * (snapshotted once at registration and served on every request), or a
+   * per-method object.
+   */
+  type Route = RouteHandler | Response | MethodRoutes
+
+  /**
+   * The per-connection socket handle passed to the `websocket` callbacks.
+   * Returned send/publish counts are the bytes (or sockets) queued.
+   */
+  type ServerWebSocket = {
+    /**
+     * Arbitrary value attached via `upgrade(req, { data })`; `undefined` when
+     * none was given. Settable.
+     */
+    data: any
+    /**
+     * Queue a message: a string sends a text frame, a Uint8Array a binary frame.
+     * Returns the bytes queued, 0 if the socket is no longer open, or -1 when the
+     * queue exceeds `backpressureLimit` (the message is still queued and `drain`
+     * fires once the queue empties).
+     */
+    send(data: string | Uint8Array): number
+    /**
+     * Send a ping control frame; the peer's reply surfaces in the `pong`
+     * callback. Payload must be 125 bytes or fewer. Same return values as `send`.
+     */
+    ping(data?: string | Uint8Array): number
+    /** Send an unsolicited pong control frame (125 bytes or fewer). */
+    pong(data?: string | Uint8Array): number
+    /**
+     * Join a topic; `server.publish(topic)` and peers' `ws.publish(topic)` then
+     * reach this socket. No-op on a closing or closed socket.
+     */
+    subscribe(topic: string): void
+    /** Leave a topic. Closing the socket unsubscribes everything automatically. */
+    unsubscribe(topic: string): void
+    /** Whether this socket is currently subscribed to `topic`. */
+    isSubscribed(topic: string): boolean
+    /**
+     * Publish to every subscriber of `topic` except this socket. Returns the
+     * number of sockets the message was queued to.
+     */
+    publish(topic: string, data: string | Uint8Array): number
+    /**
+     * Send a close frame (default code 1000). The connection finishes once the
+     * peer echoes the close, or the grace period expires.
+     */
+    close(code?: number, reason?: string): void
+    /** Connection state: CONNECTING 0, OPEN 1, CLOSING 2, CLOSED 3. */
+    readonly readyState: number
+  }
+
+  /**
+   * The `websocket` serve option: per-server socket lifecycle callbacks, shared
+   * by every connection. Incoming pings are answered automatically by the
+   * protocol layer and never surface (so there is no `ping` callback).
+   */
+  type WebSocketHandlers = {
+    /** Fired once a connection is established (after `server.upgrade`). */
+    open?(ws: ServerWebSocket): void
+    /** Fired for each text (string) or binary (Uint8Array) message. */
+    message?(ws: ServerWebSocket, data: string | Uint8Array): void
+    /** Fired when a backpressured send queue empties. */
+    drain?(ws: ServerWebSocket): void
+    /** Fired when the peer replies to a `ws.ping()`. */
+    pong?(ws: ServerWebSocket, data: Uint8Array): void
+    /** Fired once when the connection closes, with the close code and reason. */
+    close?(ws: ServerWebSocket, code: number, reason: string): void
+    /**
+     * Queue-size threshold (bytes) at which `send` returns -1 and `drain` later
+     * fires. Defaults to the runtime's built-in limit.
+     */
+    backpressureLimit?: number
+  }
+
+  /** Options for {@link Server.upgrade}. */
+  type UpgradeOptions = {
+    /** Becomes `ws.data` on the upgraded socket. */
+    data?: any
+    /**
+     * Extra headers appended to the 101 response (e.g. `Set-Cookie`). An invalid
+     * header fails the upgrade.
+     */
+    headers?: Record<string, string> | Headers
+  }
+
+  type Server = {
+    /** The bound port. */
+    readonly port: number
+    /** The bound hostname/interface. */
+    readonly hostname: string
+    /** The server's base URL, e.g. `"http://0.0.0.0:3000/"`. */
+    readonly url: string
+    /**
+     * Accept a websocket handshake for `req`. On `true` the handler must return
+     * nothing: the held 101 response is sent when it returns and the `websocket`
+     * callbacks take over. `false` means the request cannot upgrade (not a
+     * websocket request, already upgraded, or no `websocket` option), so the
+     * handler can serve a normal response instead.
+     */
+    upgrade(req: FluxRequest, opts?: UpgradeOptions): boolean
+    /**
+     * Publish a message to every socket subscribed to `topic`. Returns the number
+     * of sockets the message was queued to.
+     */
+    publish(topic: string, data: string | Uint8Array): number
+    /** How many sockets are currently subscribed to `topic`. */
+    subscriberCount(topic: string): number
+    /**
+     * Stop accepting new connections and gracefully shut down open ones. Safe to
+     * call more than once.
+     */
+    stop(): void
+  }
+
+  type ServeOptions = {
+    /** Port to listen on. */
+    port: number
+    /** Hostname/interface to bind. Defaults to "0.0.0.0" (all interfaces). */
+    hostname?: string
+    /**
+     * Route table keyed by path pattern. Patterns may contain `:name` segments,
+     * exposed on `req.params`. Each value is a handler function, a static
+     * {@link Response}, or a per-method object.
+     */
+    routes?: Record<string, Route>
+    /**
+     * Fallback handler for requests no route matched. Without it (and with no
+     * matching route), unmatched requests get a 404.
+     */
+    fetch?: RouteHandler
+    /**
+     * Handles a throw or rejection from a handler; its result becomes the
+     * response. Without it, a handler error becomes a plaintext 500.
+     */
+    error?: (error: any) => string | Response | Promise<string | Response>
+    /**
+     * WebSocket lifecycle callbacks. Providing this enables `server.upgrade()`;
+     * without it `upgrade()` always returns false.
+     */
+    websocket?: WebSocketHandlers
+  }
+
+  /**
+   * Start an HTTP server. Loosely models Bun's `Bun.serve`.
+   *
+   * @param options  Port, hostname, routes, fetch fallback, error handler, and
+   *                 websocket callbacks.
+   * @returns The running {@link Server}.
+   */
+  export function serve(options: ServeOptions): Server
+}

package/modules/mdns.d.ts

@@ -0,0 +1,54 @@
+declare module "flux:mdns" {
+  /** Options common to {@link resolve}, {@link browse}, and {@link services}. */
+  type MdnsOptions = {
+    /** How long (ms) to collect multicast answers before resolving. Default 1500. */
+    timeoutMs?: number
+  }
+
+  /** A reverse-resolved address, from {@link resolve}. */
+  type Resolved = {
+    /** The queried IPv4 address. */
+    ip: string
+    /** Its mDNS hostname, e.g. "printer.local". */
+    host: string
+  }
+
+  /** One discovered DNS-SD service instance, from {@link browse}. */
+  type ServiceInstance = {
+    /** The human instance label, e.g. "Office Printer". */
+    instance: string
+    /** The service type, e.g. "_ipp._tcp". */
+    service: string
+    /** The target host the SRV record points at, e.g. "printer.local". */
+    host: string
+    /** The advertised port. */
+    port: number
+    /** A/AAAA addresses for `host`, when the responder bundled them. */
+    addrs: string[]
+    /** TXT attributes (a bare flag attribute has an empty-string value). */
+    txt: Record<string, string>
+  }
+
+  /**
+   * Reverse-resolve IPv4 addresses to their mDNS `.local` hostnames over the
+   * link-local multicast group (a PTR query against `in-addr.arpa`). `.local`
+   * names are mDNS, not unicast DNS, so this works with no `nss-mdns` resolver and
+   * no external binary. Addresses that do not answer within the window — and any
+   * IPv6 inputs — are simply absent from the result; an empty input resolves to
+   * `[]` without touching the network. Needs a Bonjour/avahi responder on the LAN.
+   */
+  export function resolve(ips: string[], opts?: MdnsOptions): Promise<Resolved[]>
+
+  /**
+   * Browse a DNS-SD service type for the instances on the LAN. `service` may be
+   * bare (`"_http._tcp"`) or fully qualified. Resolves to `[]` if nothing answers
+   * within the window.
+   */
+  export function browse(service: string, opts?: MdnsOptions): Promise<ServiceInstance[]>
+
+  /**
+   * Enumerate the service types advertised on the LAN (the
+   * `_services._dns-sd._udp.local` meta-query), e.g. `["_http._tcp", "_ipp._tcp"]`.
+   */
+  export function services(opts?: MdnsOptions): Promise<string[]>
+}

package/modules/net.d.ts

@@ -0,0 +1,139 @@
+declare module "flux:net" {
+  /** Options for {@link probe} and {@link connect}. */
+  type ConnectOptions = {
+    /** Give up after this many ms. Default 1000 for {@link probe}, 10000 for {@link connect}. */
+    timeoutMs?: number
+  }
+
+  /** Options for {@link listen}. */
+  type ListenOptions = {
+    /** Local address to bind. Default "0.0.0.0" (all interfaces). */
+    host?: string
+  }
+
+  /** Options for {@link udp}. */
+  type UdpOptions = {
+    /** Local port to bind. Default 0 (OS-assigned). */
+    port?: number
+    /** Set SO_REUSEADDR/REUSEPORT so several sockets can share the port. */
+    reuse?: boolean
+  }
+
+  /**
+   * Outcome of a {@link probe}. `closed` (a refusal) still means the host is up —
+   * something answered; only `filtered` (a timeout/unreachable) is no evidence.
+   */
+  type Liveness = "open" | "closed" | "filtered"
+
+  /** One address on a {@link NetInterface}. */
+  type InterfaceAddr = {
+    /** The IP address. */
+    ip: string
+    /** CIDR prefix length (e.g. 24). */
+    prefix: number
+    /** Address family. */
+    family: "v4" | "v6"
+  }
+
+  /** A local network interface, from {@link interfaces}. */
+  type NetInterface = {
+    /** Interface name, e.g. "wlan0". */
+    name: string
+    /** Hardware (MAC) address, or `null` if none. */
+    mac: string | null
+    /** Whether the interface is up. */
+    up: boolean
+    /** Whether it is a loopback interface. */
+    loopback: boolean
+    /** Whether it supports multicast. */
+    multicast: boolean
+    /** The interface's bound addresses. */
+    addrs: InterfaceAddr[]
+  }
+
+  /** A received datagram, from {@link Udp.recv}. */
+  type Datagram = {
+    /** The payload bytes. */
+    data: Uint8Array
+    /** Sender IP. */
+    host: string
+    /** Sender port. */
+    port: number
+  }
+
+  /**
+   * A connected TCP stream: a byte duplex. It is its own async iterator, so
+   * `for await (let chunk of conn)` reads it until end-of-stream.
+   */
+  export class Conn implements AsyncIterable<Uint8Array> {
+    /** The remote peer's address, e.g. "192.168.2.37:445". */
+    readonly peer: string
+    /** Write all of `data`. Resolves once it is handed to the OS. */
+    write(data: string | Uint8Array): Promise<void>
+    /** Stop reading and close the connection. */
+    close(): void
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>
+  }
+
+  /**
+   * A bound TCP listener: an async-iterable of incoming connections, so
+   * `for await (let conn of listener)` accepts them. Drop it to stop.
+   */
+  export class Listener implements AsyncIterable<Conn> {
+    /** The bound local address (with the OS-assigned port when 0 was requested). */
+    readonly localAddr: string
+    [Symbol.asyncIterator](): AsyncIterator<Conn>
+  }
+
+  /** A bound UDP socket with the broadcast/multicast controls a peer beacon needs. */
+  export class Udp {
+    /** The bound local address (with the OS-assigned port when 0 was requested). */
+    readonly localAddr: string
+    /** Send a datagram to `host:port` — a unicast peer, a broadcast address, or a multicast group. */
+    send(data: string | Uint8Array, host: string, port: number): Promise<void>
+    /** Receive the next datagram. */
+    recv(): Promise<Datagram>
+    /** Allow sending to the broadcast address (SO_BROADCAST). */
+    setBroadcast(on: boolean): void
+    /** TTL for outgoing multicast (1 keeps it on the local link). */
+    setMulticastTtl(ttl: number): void
+    /** Whether multicast this socket sends loops back to sockets on this host. */
+    setMulticastLoop(on: boolean): void
+    /**
+     * Join multicast `group` on the interface with address `iface`
+     * (default "0.0.0.0", OS-chosen). Required to receive that group's datagrams.
+     */
+    joinMulticast(group: string, iface?: string): void
+    /** Leave a multicast group previously joined with {@link joinMulticast}. */
+    leaveMulticast(group: string, iface?: string): void
+  }
+
+  /**
+   * Probe `host:port` with a TCP connect and report what it says about the host.
+   * Infallible — every outcome maps to a {@link Liveness}, so a sweep never has to
+   * catch. The connect-scan primitive: count `open` or `closed` as a live host.
+   *
+   * @param opts  timeoutMs (default 1000).
+   */
+  export function probe(host: string, port: number, opts?: ConnectOptions): Promise<Liveness>
+
+  /**
+   * Open a TCP connection. Unlike {@link probe} this returns a live {@link Conn}
+   * for app protocols / banner grabs.
+   *
+   * @param opts  timeoutMs (default 10000).
+   */
+  export function connect(host: string, port: number, opts?: ConnectOptions): Promise<Conn>
+
+  /** Bind a TCP {@link Listener} on `port` (0 = OS-assigned). */
+  export function listen(port: number, opts?: ListenOptions): Promise<Listener>
+
+  /** Bind a {@link Udp} socket. */
+  export function udp(opts?: UdpOptions): Promise<Udp>
+
+  /**
+   * Enumerate local network interfaces and their addresses — the no-subprocess
+   * way to find the subnet to scan (replaces parsing `ip addr`). Synchronous.
+   */
+  export function interfaces(): NetInterface[]
+}

package/modules/p2p.d.ts

@@ -0,0 +1,85 @@
+declare module "flux:p2p" {
+  /** Options for {@link Endpoint.create}. */
+  type EndpointOptions = {
+    /**
+     * 64 hex chars (32 bytes) for a stable identity across restarts. Omit for an
+     * ephemeral key.
+     */
+    secretKey?: string
+    /** A self-hosted relay URL. Omit to use the public n0 relays. */
+    relayUrl?: string
+    /** Protocols this endpoint will {@link Endpoint.accept}. */
+    protocols?: string[]
+  }
+
+  /** One transport address from {@link Endpoint.connInfo}. */
+  type ConnAddr = {
+    /** "relay", "direct" (an IP path), or "custom". */
+    kind: "relay" | "direct" | "custom"
+    /** The address string. */
+    addr: string
+    /** Whether this path is currently active. */
+    active: boolean
+  }
+
+  /** A snapshot of how a connection is currently carried. */
+  type ConnInfo = {
+    /**
+     * "direct" (a direct IP path is active), "relay" (only a relay path),
+     * "mixed" (both), or "none".
+     */
+    path: "direct" | "relay" | "mixed" | "none"
+    /** Every known transport address. */
+    addrs: ConnAddr[]
+  }
+
+  /**
+   * A single bidirectional p2p stream: a byte duplex. It is its own async
+   * iterator, so `for await (let chunk of stream)` reads the recv half.
+   */
+  export class P2pStream implements AsyncIterable<Uint8Array> {
+    /** The remote peer's endpoint id. */
+    readonly remoteId: string
+    /** Queue bytes on the send half. */
+    write(data: string | Uint8Array): void
+    /** Finish the send half (QUIC FIN) after queued writes flush. The recv half stays open. */
+    finish(): void
+    /** Tear the stream down: finish the send half and stop reading. */
+    close(): void
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>
+  }
+
+  /** A bound iroh endpoint with a stable keypair. */
+  export class Endpoint {
+    /**
+     * Bind an endpoint.
+     *
+     * @param opts  secretKey, relayUrl, protocols.
+     */
+    static create(opts?: EndpointOptions): Promise<Endpoint>
+    /** This endpoint's dial address: the string peers pass to {@link connect}. */
+    readonly id: string
+    /** The secret key as 64 hex chars, for the caller to persist and feed back to {@link create}. */
+    readonly secretKey: string
+    /**
+     * A self-contained dial token (`id|relay|ips`) so a peer can {@link connect}
+     * without relying on discovery.
+     */
+    ticket(): Promise<string>
+    /**
+     * Dial a peer and open one bidirectional stream over `protocol`. `peer` is
+     * either a `ticket` (preferred; connects directly) or a bare endpoint `id`
+     * (needs discovery to resolve the address).
+     */
+    connect(peer: string, protocol: string): Promise<P2pStream>
+    /**
+     * An async-iterable of incoming streams whose protocol matches `protocol`.
+     * Iterating ends when the endpoint is closed.
+     */
+    accept(protocol: string): AsyncIterable<P2pStream>
+    /** Snapshot of how the connection to `id` is currently carried. */
+    connInfo(id: string): Promise<ConnInfo>
+    /** Close the endpoint, ending any {@link accept} iteration. */
+    close(): Promise<void>
+  }
+}

package/modules/path.d.ts

@@ -0,0 +1,26 @@
+declare module "flux:path" {
+  /**
+   * Resolves `path` against the trusted base directory `base`, returning the
+   * absolute result only if it stays inside `base`; otherwise `null`. Fusing
+   * normalization and containment means a `..`-laden or absolute `path` that
+   * would escape `base` is rejected rather than silently resolved.
+   *
+   * Purely lexical: it does not resolve symlinks, so a symlink inside `base`
+   * pointing out of it is not caught.
+   *
+   * @param base  Trusted root directory. Relative values resolve against cwd.
+   * @param path  Untrusted path to place within `base`.
+   * @returns The contained absolute path, or `null` if it would escape `base`.
+   *
+   * @example
+   * let target = resolveWithin(".", req.params.page)
+   * if (!target) return new Response("Not found", { status: 404 })
+   */
+  export function resolveWithin(base: string, path: string): string | null
+
+  /**
+   * Joins and normalizes path `segments`. Lexical only, with no containment
+   * guarantee; use `resolveWithin` when a segment is untrusted.
+   */
+  export function join(...segments: string[]): string
+}

package/modules/process.d.ts

@@ -0,0 +1,36 @@
+declare module "flux:process" {
+  /**
+   * The program's command-line arguments. `argv[0]` is the script path;
+   * `argv[1]` onward are the user-supplied arguments.
+   */
+  export let argv: string[]
+  /** The host OS: "darwin", "win32", "linux", "android", ... */
+  export let platform: string
+  /** The CPU architecture: "x64", "arm64", ... */
+  export let arch: string
+  /**
+   * Current-process memory usage. `rss` is the resident set size in bytes.
+   * (Node also reports heapTotal/heapUsed/external/arrayBuffers; only rss is
+   * provided for now.)
+   */
+  export function memoryUsage(): { rss: number }
+  /**
+   * Listen for an OS signal. The callback receives the signal name. Returns an
+   * unsubscribe function. Unix only; a no-op elsewhere.
+   *
+   * @param signal  One of "SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGUSR1",
+   *                "SIGUSR2".
+   * @param callback  Invoked on each delivery with the signal name.
+   * @returns An unsubscribe function.
+   */
+  export function on(signal: string, callback: (signal: string) => void): () => void
+  /**
+   * Like {@link on}, but the listener fires at most once and then unsubscribes.
+   *
+   * @param signal  One of "SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGUSR1",
+   *                "SIGUSR2".
+   * @param callback  Invoked once with the signal name.
+   * @returns An unsubscribe function.
+   */
+  export function once(signal: string, callback: (signal: string) => void): () => void
+}

package/modules/sqlite.d.ts

@@ -0,0 +1,53 @@
+declare module "flux:sqlite" {
+  /** Values accepted as bound parameters. booleans bind as 0/1. */
+  type SqlParam = null | boolean | number | string | Uint8Array
+  /** Values returned in result rows. BLOB comes back as Uint8Array. */
+  type SqlValue = null | number | string | Uint8Array
+  type Row = Record<string, SqlValue>
+
+  /** The outcome of a write. */
+  type RunResult = { changes: number; lastInsertRowid: number }
+
+  /**
+   * A reusable prepared statement. Created with {@link Database.query}; its
+   * executions reuse the compiled statement (cached on the connection).
+   */
+  export class Statement {
+    /** Run the statement and resolve to all matching rows. */
+    all(params?: SqlParam[]): Promise<Row[]>
+    /** Run the statement and resolve to the first row, or `undefined`. */
+    get(params?: SqlParam[]): Promise<Row | undefined>
+    /** Run the statement as a write and resolve to its {@link RunResult}. */
+    run(params?: SqlParam[]): Promise<RunResult>
+  }
+
+  /**
+   * Open mode: "ro" (default, read-only, must exist), "rw" (read-write, must
+   * exist), "rw+" (read-write, create if missing).
+   */
+  type OpenMode = "ro" | "rw" | "rw+"
+
+  export class Database {
+    /**
+     * Open a connection to the database at `path`.
+     *
+     * @param path  Database file path.
+     * @param mode  Open mode; defaults to "ro".
+     */
+    static connect(path: string, mode?: OpenMode): Promise<Database>
+    /** Create a reusable prepared statement (synchronous; compiles on first run). */
+    query(sql: string): Statement
+    /** One-shot write; uses plain prepare (no caching). */
+    run(sql: string, params?: SqlParam[]): Promise<RunResult>
+    /** Run a multi-statement script (no params), e.g. schema setup / migrations. */
+    exec(sql: string): Promise<void>
+    /**
+     * Run a batch of [sql, params] statements in one transaction (BEGIN/COMMIT,
+     * ROLLBACK on any error). Resolves to one result per statement. Statements
+     * must be writes/DDL. Cannot branch on intermediate results.
+     */
+    transaction(statements: [string, SqlParam[]?][]): Promise<RunResult[]>
+    /** Close the connection. */
+    close(): Promise<void>
+  }
+}

package/modules/subprocess.d.ts

@@ -0,0 +1,89 @@
+declare module "flux:subprocess" {
+  /** Options for {@link command}. */
+  type CommandOptions = {
+    /** Working directory for the child. */
+    cwd?: string
+    /** Extra env vars, added to / overriding the inherited environment. */
+    env?: Record<string, string>
+    /** Bytes written to the child's stdin, after which stdin is closed. */
+    stdin?: string | Uint8Array
+    /** Kill the child if it has not exited within this many milliseconds. */
+    timeoutMs?: number
+    /**
+     * "buffer" returns stdout/stderr as `Uint8Array`; the default returns them
+     * as UTF-8 strings.
+     */
+    encoding?: "buffer" | "utf8"
+  }
+
+  /** The buffered result of a child run to completion via {@link Command.output}. */
+  type CommandOutput = {
+    /** Exit code, or `null` if the child was killed by a signal. */
+    code: number | null
+    /** Signal name that killed the child (Unix), or `null`. */
+    signal: string | null
+    /** `true` when `code` is 0. */
+    success: boolean
+    /** Captured stdout. `Uint8Array` when `encoding` is "buffer", else a string. */
+    stdout: string | Uint8Array
+    /** Captured stderr. `Uint8Array` when `encoding` is "buffer", else a string. */
+    stderr: string | Uint8Array
+  }
+
+  /** The exit status of a spawned child (the {@link CommandOutput} shape without buffered streams). */
+  type CommandStatus = {
+    /** Exit code, or `null` if the child was killed by a signal. */
+    code: number | null
+    /** Signal name that killed the child (Unix), or `null`. */
+    signal: string | null
+    /** `true` when `code` is 0. */
+    success: boolean
+  }
+
+  /** A running child process, returned by {@link Command.spawn}. */
+  type Child = {
+    /** The OS process id, if available. */
+    pid: number | undefined
+    /** Live stdout as an async-iterable of byte chunks. */
+    stdout: AsyncIterable<Uint8Array>
+    /** Live stderr as an async-iterable of byte chunks. */
+    stderr: AsyncIterable<Uint8Array>
+    /** Queue bytes to the child's stdin. Writes serialize and respect backpressure. */
+    write(data: string | Uint8Array): Promise<void>
+    /** Close the child's stdin (after queued writes drain) so it sees EOF. */
+    endStdin(): Promise<void>
+    /** Request termination (portable; SIGKILL / TerminateProcess). */
+    kill(): void
+    /** Resolves with the exit status when the child exits. */
+    status(): Promise<CommandStatus>
+  }
+
+  /** A parsed, reusable command spec. Created with {@link command}; runnable more than once. */
+  type Command = {
+    cmd: string
+    args: string[]
+    /** Run the child to completion, buffering stdout/stderr. */
+    output(): Promise<CommandOutput>
+    /** Spawn the child and return a handle with live streams, stdin, and control. */
+    spawn(): Child
+  }
+
+  /**
+   * Build a command. Arguments are always passed as an array and never through a
+   * shell, so there is no shell quoting or injection to reason about, and the JS
+   * is identical on every OS.
+   *
+   * @param cmd   The program to run.
+   * @param args  Arguments, passed verbatim (no shell).
+   * @param opts  cwd, env, stdin, timeoutMs, encoding.
+   */
+  export function command(cmd: string, args?: string[], opts?: CommandOptions): Command
+
+  /**
+   * Cross-platform PATH lookup (handles Windows PATHEXT / .exe).
+   *
+   * @param cmd  Binary name to resolve.
+   * @returns The absolute path to the resolved executable, or `null` if not found.
+   */
+  export function which(cmd: string): string | null
+}