@oh-hai/cli 0.1.0-beta.0

package/dist/auth/resolve-token.js

@@ -0,0 +1,91 @@
+// Token resolution (docs/specs/cli.md §6) — the layer that composes the pure config precedence
+// (config.ts, which knows only the `MA2H_AGENT_TOKEN` env token) with the local credential
+// stores. Kept OUT of `resolveConfig` so that function stays sync + pure + unit-testable; the
+// keychain/file READ (I/O) lives here behind the injectable `CredentialStore`.
+//
+//   token := MA2H_AGENT_TOKEN   (env; CI path — overrides local stores, §5.3)
+//         || store[<origin>|<agent id>]   (the active backend: keychain, else 0600 file)
+//         || none
+//
+// The token is NEVER read from a config-file value (§5.4). A local lookup requires a resolved
+// agent id (the store is keyed by `<origin>|<agent id>`); without one there is nothing to look
+// up, so the source is `none`.
+//
+// The store layers the keychain over the `0600` file (token-store.ts), so `getWithSource`
+// realizes §6's `keychain || file` as a real dual-read and reports which backend held the
+// token. The store is optional here so `whoami` can skip opening it (and probing the OS
+// keychain) when the CI env token is present — resolution short-circuits before it's needed.
+/** Derive the Hub origin (scheme+host+port) from a resolved base URL, for Hub-scoped keying
+ *  (§5.1). Falls back to the raw string if the URL can't be parsed (resolveConfig guarantees a
+ *  valid default, so this is belt-and-suspenders). */
+export function originOf(baseUrl) {
+    try {
+        return new URL(baseUrl).origin;
+    }
+    catch {
+        return baseUrl;
+    }
+}
+/** Resolve the effective bearer token and where it came from, per §6. `store` may be omitted
+ *  when the caller already knows resolution won't touch it (an env token, or no account). */
+export async function resolveToken(config, store) {
+    // The env token (CI path, §5.3) wins over local stores — resolveConfig already captured it.
+    if (config.tokenSource === "env") {
+        return { token: config.token, source: "env" };
+    }
+    // A local lookup needs an agent id (the stores are keyed by `<origin>|<agent id>`) and a store.
+    if (config.account === undefined || store === undefined) {
+        return { token: undefined, source: "none" };
+    }
+    const found = await store.getWithSource(originOf(config.baseUrl), config.account);
+    return found !== undefined ? { token: found.token, source: found.source } : { token: undefined, source: "none" };
+}
+/**
+ * Resolve the effective identity (§6): the account plus its bearer. Extends `resolveToken` with a
+ * zero-config fallback for the device-code login path, where the bearer is stored under a
+ * Hub-chosen agent id but no `--account`/`MA2H_AGENT_ID`/config account is set. When no account is
+ * configured and the token isn't the CI env credential, fall back to the SOLE stored identity for
+ * the current Hub origin — so a fresh `oh-hai login` then `oh-hai whoami` resolves without a manual
+ * `--account`. Ambiguity is never guessed: with zero or more-than-one stored identity for the
+ * origin, the account stays undefined and the user selects with `--account` (§6). The env path is
+ * never discovered — the env credential is authoritative and its agent id may differ from a stored
+ * login. Discovery keys on the origin (derived from the flag/env/user-config `base_url`, never a
+ * repo-controlled value), so it preserves §5.1 isolation and can't leak a bearer to a chosen Hub.
+ */
+export async function resolveIdentity(config, store) {
+    // The env token (CI path, §5.3) is authoritative — carry the configured account (possibly
+    // undefined) and never consult the store, so `whoami` can keep skipping it for an env token.
+    if (config.tokenSource === "env") {
+        return { account: config.account, token: config.token, source: "env" };
+    }
+    // An explicitly configured account wins — resolve its token directly (no discovery).
+    if (config.account !== undefined) {
+        const { token, source } = await resolveToken(config, store);
+        return { account: config.account, token, source };
+    }
+    // No account and no env token: discover the sole stored identity for this Hub origin.
+    if (store === undefined) {
+        return { account: undefined, token: undefined, source: "none" };
+    }
+    const origin = originOf(config.baseUrl);
+    const listed = (await store.list()).filter((identity) => identity.origin === origin);
+    // Resolve each listed identity to its bearer and keep only the ones that actually resolve.
+    // `list()` reads a keys-only index (redaction-safe: identities, never tokens), which can drift
+    // from the backend — a key manually removed from the keychain, or left behind by a failed delete.
+    // A listed key is a REAL identity only if its token still resolves, so we count RESOLVABLE
+    // identities, not listed keys: otherwise a stale index entry would make a sole real identity look
+    // ambiguous and break the zero-config path. (The per-identity read is required, not a missed
+    // optimization, precisely because `list()` withholds tokens.)
+    const resolved = [];
+    for (const identity of listed) {
+        const found = await store.getWithSource(origin, identity.agentId);
+        if (found !== undefined) {
+            resolved.push({ account: identity.agentId, token: found.token, source: found.source });
+        }
+    }
+    // Exactly one resolvable identity is unambiguous; zero → nothing to resolve, many → ambiguous and
+    // requires --account (§6). Either non-unique case resolves to none.
+    const only = resolved.length === 1 ? resolved[0] : undefined;
+    return only ?? { account: undefined, token: undefined, source: "none" };
+}
+//# sourceMappingURL=resolve-token.js.map

package/dist/auth/resolve-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-token.js","sourceRoot":"","sources":["../../src/auth/resolve-token.ts"],"names":[],"mappings":"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"}

package/dist/auth/secure-write.d.ts

@@ -0,0 +1,2 @@
+/** Atomically write `content` to `path` at mode `0600`, creating the parent dir at `0700`. */
+export declare function writeSecureFile(path: string, content: string): void;

package/dist/auth/secure-write.js

@@ -0,0 +1,30 @@
+// Atomic, permission-tight file writes for the credential store (docs/specs/cli.md §5.2).
+// Both the file backend (the credentials map) and the keychain backend (the keys index) write
+// secret-adjacent data to disk; this is their single source of truth for doing it safely.
+//
+// Write to a sibling temp file created `0600` from the first byte, then `rename()` over the
+// target. Two properties fall out: (1) there is no window where the secret sits at looser
+// permissions (the old write-then-chmod left a sub-millisecond TOCTOU gap on a pre-existing
+// world-readable file), and (2) a crash mid-write never leaves a truncated/partial file — the
+// rename is atomic, so a reader sees either the whole old file or the whole new one.
+//
+// This makes each individual write atomic and crash-safe. It does NOT lock against a *separate
+// process* doing its own read-modify-write concurrently — two `oh-hai` invocations racing the
+// same credentials file can still last-writer-win. The file store is single-user by design
+// (the keychain is the real multi-writer store); a lockfile would be the fix if that changes.
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+// Per-process counter so two writes from the same process never collide on the temp name.
+let tmpSeq = 0;
+/** Atomically write `content` to `path` at mode `0600`, creating the parent dir at `0700`. */
+export function writeSecureFile(path, content) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.tmp.${process.pid}.${tmpSeq++}`;
+    // `mode` on writeFileSync applies on create (tmp is always new); chmod re-asserts exactly
+    // 0600 in case a restrictive umask narrowed it further — the token must not be group/world
+    // readable, and the temp file must be tight before the rename exposes it at `path`.
+    writeFileSync(tmp, content, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+}
+//# sourceMappingURL=secure-write.js.map

package/dist/auth/secure-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-write.js","sourceRoot":"","sources":["../../src/auth/secure-write.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,8FAA8F;AAC9F,0FAA0F;AAC1F,EAAE;AACF,4FAA4F;AAC5F,0FAA0F;AAC1F,4FAA4F;AAC5F,8FAA8F;AAC9F,qFAAqF;AACrF,EAAE;AACF,+FAA+F;AAC/F,8FAA8F;AAC9F,2FAA2F;AAC3F,8FAA8F;AAE9F,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,0FAA0F;AAC1F,IAAI,MAAM,GAAG,CAAC,CAAC;AAEf,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,OAAe;IAC3D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,GAAG,IAAI,QAAQ,OAAO,CAAC,GAAG,IAAI,MAAM,EAAE,EAAE,CAAC;IACrD,0FAA0F;IAC1F,2FAA2F;IAC3F,oFAAoF;IACpF,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC"}

package/dist/auth/token-store.d.ts

@@ -0,0 +1,104 @@
+import { type KeychainRunner } from "./keychain.js";
+/** A pluggable secret backend. Both the keychain and file backends implement this; the store
+ *  is backend-agnostic. Ops are keyed by the already-built `<origin>|<agent id>` string. */
+export interface SecretBackend {
+    readonly name: "keychain" | "file";
+    get(key: string): Promise<string | undefined>;
+    set(key: string, token: string): Promise<void>;
+    /** Returns true when an entry was removed, false when the key was already absent. */
+    delete(key: string): Promise<boolean>;
+    /** Enumerate stored keys (`<origin>|<agent id>`) — never token values. */
+    listKeys(): Promise<string[]>;
+    /** Remove every entry; returns how many were removed. */
+    clearAll(): Promise<number>;
+}
+/** A stored identity, as returned by `list()`. `source` is the active backend. */
+export interface StoredIdentity {
+    origin: string;
+    agentId: string;
+    source: "keychain" | "file";
+}
+/** The loud one-time warning shown when the store falls back to the on-disk file (§5.2). Goes
+ *  to stderr only, so it never pollutes the `--json` stdout envelope (§8). */
+export declare const FILE_FALLBACK_WARNING: string;
+/** Build the Hub-scoped storage key from an origin and agent id (§5.1). */
+export declare function keyOf(origin: string, agentId: string): string;
+/** Split a storage key back into `{ origin, agentId }`. Origins (scheme+host+port) never
+ *  contain `|`, so splitting on the FIRST `|` is unambiguous even if an agent id contained one. */
+export declare function parseKey(key: string): {
+    origin: string;
+    agentId: string;
+};
+/** The keys-only index file the keychain backend uses for enumeration — a sibling of the
+ *  credentials file (`~/.config/oh-hai/keys.json`), honoring the same XDG resolution. */
+export declare function keychainIndexPath(env?: NodeJS.ProcessEnv): string;
+interface StoreOptions {
+    fellBack?: boolean;
+    warn?: (msg: string) => void;
+}
+/** A token plus which backend held it (§6 source reporting). */
+export interface FoundToken {
+    token: string;
+    source: "keychain" | "file";
+}
+/**
+ * A layered credential store over one or more backends. Writes go to the PRIMARY backend
+ * (keychain when available, else the file fallback); reads, deletes, list, and clearAll span
+ * EVERY backend. That dual-read/dual-scrub matters for §6's `keychain || file` chain and for
+ * security: a token written to the `0600` file while the keychain was down must still be
+ * resolved, and — critically — must still be *removed* by `logout`/`logout --all` once the
+ * keychain is back (a single-backend store would leave the unencrypted copy behind). A given
+ * key only ever lives in ONE backend (set writes to the primary), so scanning all backends
+ * never double-counts or duplicates.
+ */
+export declare class CredentialStore {
+    /** The PRIMARY (write) backend's name — surfaced so `login` can report `storage`. */
+    readonly backendName: "keychain" | "file";
+    private readonly backends;
+    private readonly primary;
+    private readonly fellBack;
+    private readonly warn;
+    private warned;
+    constructor(backend: SecretBackend | SecretBackend[], options?: StoreOptions);
+    /** Emit the on-disk warning exactly once per store, only when we fell back to the file. */
+    private maybeWarn;
+    get(origin: string, agentId: string): Promise<string | undefined>;
+    /** Read from the first backend (primary before fallback) that holds the token, reporting
+     *  which one it was — so `whoami`/resolution can show the real source (§6). */
+    getWithSource(origin: string, agentId: string): Promise<FoundToken | undefined>;
+    set(origin: string, agentId: string, token: string): Promise<void>;
+    /** Delete from EVERY backend so a file-fallback copy is scrubbed even when the keychain is
+     *  primary. A backend error doesn't stop the others (the file must always be scrubbed); the
+     *  first error is surfaced after all backends have been attempted. */
+    delete(origin: string, agentId: string): Promise<boolean>;
+    /** Union of identities across all backends (a key lives in exactly one, so no dedup needed —
+     *  the guard is belt-and-suspenders). */
+    list(): Promise<StoredIdentity[]>;
+    /** Clear EVERY backend (so `logout --all` scrubs the file fallback too). As with delete, a
+     *  backend error doesn't skip the others; the first error is surfaced afterward. */
+    clearAll(): Promise<number>;
+}
+export interface OpenStoreOptions {
+    /** Override the credentials file path (tests). */
+    filePath?: string;
+    /** Override the keychain key-index path (tests). */
+    indexPath?: string;
+    /** Inject the keychain runner (tests use a fake so no real keychain is touched). */
+    keychainRunner?: KeychainRunner;
+    /** Force a specific backend, bypassing detection (tests). */
+    backend?: SecretBackend;
+    /** Sink for the one-time fallback warning (tests capture it). */
+    warn?: (msg: string) => void;
+    /** Bound on the keychain availability probe (defaults to KEYCHAIN_PROBE_TIMEOUT_MS). */
+    probeTimeoutMs?: number;
+}
+/**
+ * Open a credential store. The keychain (when available) is the PRIMARY backend with the file
+ * fallback layered underneath — so a token written to the file during a past keychain outage is
+ * still read and, on `logout`, scrubbed (§6). When the keychain is unavailable/locked, the file
+ * is the sole backend and the one-time on-disk warning is armed. Backend selection is the only
+ * async step: a side-effect-free `get` of a sentinel key, bounded by a timeout so a hung/locked
+ * keychain can't hang the CLI — the abandoned probe child is cancelled on timeout.
+ */
+export declare function openStore(options?: OpenStoreOptions): Promise<CredentialStore>;
+export {};

package/dist/auth/token-store.js

@@ -0,0 +1,208 @@
+// The Hub-scoped credential store (docs/specs/cli.md §5). One façade over two backends — the
+// OS keychain (keychain.ts) and the `0600` file fallback (file-backend.ts) — selected at
+// runtime: keychain when the platform tool is available, else the file with a LOUD ONE-TIME
+// warning that the token is on disk unencrypted (§5.2).
+//
+// Every credential is keyed Hub-scoped by `<origin>|<agent id>` (§5.1) so the same agent id on
+// two Hubs (local dev + production) never collides or cross-sends its bearer. Callers pass
+// `(origin, agentId)`; the store builds the key. Enumeration (`list`) is redaction-safe — it
+// returns identities, never tokens.
+import { dirname, join } from "node:path";
+import { FileBackend, credentialsPath } from "./file-backend.js";
+import { KeychainBackend, systemKeychainRunner } from "./keychain.js";
+/** The loud one-time warning shown when the store falls back to the on-disk file (§5.2). Goes
+ *  to stderr only, so it never pollutes the `--json` stdout envelope (§8). */
+export const FILE_FALLBACK_WARNING = "oh-hai: the OS keychain is unavailable — the agent token is being stored UNENCRYPTED in " +
+    "~/.config/oh-hai/credentials (0600). Anyone able to read your home directory can read it.";
+/** Build the Hub-scoped storage key from an origin and agent id (§5.1). */
+export function keyOf(origin, agentId) {
+    return `${origin}|${agentId}`;
+}
+/** Split a storage key back into `{ origin, agentId }`. Origins (scheme+host+port) never
+ *  contain `|`, so splitting on the FIRST `|` is unambiguous even if an agent id contained one. */
+export function parseKey(key) {
+    const idx = key.indexOf("|");
+    return idx < 0 ? { origin: "", agentId: key } : { origin: key.slice(0, idx), agentId: key.slice(idx + 1) };
+}
+/** The keys-only index file the keychain backend uses for enumeration — a sibling of the
+ *  credentials file (`~/.config/oh-hai/keys.json`), honoring the same XDG resolution. */
+export function keychainIndexPath(env = process.env) {
+    return join(dirname(credentialsPath(env)), "keys.json");
+}
+/**
+ * A layered credential store over one or more backends. Writes go to the PRIMARY backend
+ * (keychain when available, else the file fallback); reads, deletes, list, and clearAll span
+ * EVERY backend. That dual-read/dual-scrub matters for §6's `keychain || file` chain and for
+ * security: a token written to the `0600` file while the keychain was down must still be
+ * resolved, and — critically — must still be *removed* by `logout`/`logout --all` once the
+ * keychain is back (a single-backend store would leave the unencrypted copy behind). A given
+ * key only ever lives in ONE backend (set writes to the primary), so scanning all backends
+ * never double-counts or duplicates.
+ */
+export class CredentialStore {
+    /** The PRIMARY (write) backend's name — surfaced so `login` can report `storage`. */
+    backendName;
+    backends;
+    primary;
+    fellBack;
+    warn;
+    warned = false;
+    constructor(backend, options = {}) {
+        const backends = Array.isArray(backend) ? backend : [backend];
+        const primary = backends[0];
+        if (primary === undefined) {
+            throw new Error("CredentialStore requires at least one backend");
+        }
+        this.backends = backends;
+        this.primary = primary;
+        this.backendName = primary.name;
+        this.fellBack = options.fellBack ?? false;
+        this.warn = options.warn ?? ((msg) => process.stderr.write(`${msg}\n`));
+    }
+    /** Emit the on-disk warning exactly once per store, only when we fell back to the file. */
+    maybeWarn() {
+        if (this.fellBack && !this.warned) {
+            this.warned = true;
+            this.warn(FILE_FALLBACK_WARNING);
+        }
+    }
+    async get(origin, agentId) {
+        return (await this.getWithSource(origin, agentId))?.token;
+    }
+    /** Read from the first backend (primary before fallback) that holds the token, reporting
+     *  which one it was — so `whoami`/resolution can show the real source (§6). */
+    async getWithSource(origin, agentId) {
+        const key = keyOf(origin, agentId);
+        for (const backend of this.backends) {
+            const token = await backend.get(key);
+            if (token !== undefined) {
+                return { token, source: backend.name };
+            }
+        }
+        return undefined;
+    }
+    async set(origin, agentId, token) {
+        this.maybeWarn();
+        const key = keyOf(origin, agentId);
+        await this.primary.set(key, token);
+        // Scrub any stale copy of this key from the OTHER backends — e.g. an old plaintext file
+        // token written during a past keychain outage. Without this, an overwrite would leave a
+        // divergent bearer on disk that resolution could fall back to. Best-effort: the primary
+        // write already succeeded, so a failure to scrub a secondary must not fail the login.
+        for (const backend of this.backends) {
+            if (backend === this.primary)
+                continue;
+            try {
+                await backend.delete(key);
+            }
+            catch {
+                // ignore — the authoritative copy is in the primary
+            }
+        }
+    }
+    /** Delete from EVERY backend so a file-fallback copy is scrubbed even when the keychain is
+     *  primary. A backend error doesn't stop the others (the file must always be scrubbed); the
+     *  first error is surfaced after all backends have been attempted. */
+    async delete(origin, agentId) {
+        const key = keyOf(origin, agentId);
+        let removed = false;
+        let firstError;
+        for (const backend of this.backends) {
+            try {
+                if (await backend.delete(key))
+                    removed = true;
+            }
+            catch (error) {
+                firstError ??= error;
+            }
+        }
+        if (firstError !== undefined)
+            throw firstError;
+        return removed;
+    }
+    /** Union of identities across all backends (a key lives in exactly one, so no dedup needed —
+     *  the guard is belt-and-suspenders). */
+    async list() {
+        const seen = new Map();
+        for (const backend of this.backends) {
+            for (const key of await backend.listKeys()) {
+                if (!seen.has(key))
+                    seen.set(key, { ...parseKey(key), source: backend.name });
+            }
+        }
+        return [...seen.values()];
+    }
+    /** Clear EVERY backend (so `logout --all` scrubs the file fallback too). As with delete, a
+     *  backend error doesn't skip the others; the first error is surfaced afterward. */
+    async clearAll() {
+        let total = 0;
+        let firstError;
+        for (const backend of this.backends) {
+            try {
+                total += await backend.clearAll();
+            }
+            catch (error) {
+                firstError ??= error;
+            }
+        }
+        if (firstError !== undefined)
+            throw firstError;
+        return total;
+    }
+}
+/** How long the keychain availability probe may run before we give up and use the file
+ *  fallback. A locked macOS login keychain can make `security` block on a GUI unlock prompt,
+ *  which in a headless/unattended context never answers — without a bound, every command would
+ *  hang forever. Falling back to the `0600` file on timeout is the §5.2 locked-keychain path. */
+const KEYCHAIN_PROBE_TIMEOUT_MS = 5000;
+/** Resolve `promise`, or `fallback` if it doesn't settle within `ms`. The abandoned probe
+ *  process (if any) is left to be reaped when the CLI exits; the timer is unref'd so it never
+ *  keeps the event loop alive on its own. */
+function withTimeout(promise, ms, fallback) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve(fallback);
+            }
+        }, ms);
+        timer.unref?.();
+        const done = (value) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(value);
+            }
+        };
+        promise.then(done, () => done(fallback));
+    });
+}
+/**
+ * Open a credential store. The keychain (when available) is the PRIMARY backend with the file
+ * fallback layered underneath — so a token written to the file during a past keychain outage is
+ * still read and, on `logout`, scrubbed (§6). When the keychain is unavailable/locked, the file
+ * is the sole backend and the one-time on-disk warning is armed. Backend selection is the only
+ * async step: a side-effect-free `get` of a sentinel key, bounded by a timeout so a hung/locked
+ * keychain can't hang the CLI — the abandoned probe child is cancelled on timeout.
+ */
+export async function openStore(options = {}) {
+    const warn = options.warn;
+    if (options.backend !== undefined) {
+        return new CredentialStore(options.backend, warn !== undefined ? { warn } : {});
+    }
+    const file = new FileBackend(options.filePath ?? credentialsPath());
+    const indexPath = options.indexPath ?? keychainIndexPath();
+    const runner = options.keychainRunner ?? systemKeychainRunner();
+    const keychain = new KeychainBackend(runner, indexPath);
+    // Bound the probe and cancel it on timeout: a locked keychain that blocks on a GUI unlock
+    // would otherwise leave the `security`/`secret-tool` child running and keep Node alive.
+    const controller = new AbortController();
+    const available = await withTimeout(keychain.available(controller.signal), options.probeTimeoutMs ?? KEYCHAIN_PROBE_TIMEOUT_MS, false);
+    if (!available) {
+        controller.abort();
+        return new CredentialStore(file, warn !== undefined ? { fellBack: true, warn } : { fellBack: true });
+    }
+    return new CredentialStore([keychain, file], warn !== undefined ? { warn } : {});
+}
+//# sourceMappingURL=token-store.js.map

package/dist/auth/token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.js","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import type { Io, RuntimeDeps } from "./commands/context.js";
+export type { Io } from "./commands/context.js";
+export { flagOn } from "./commands/flags.js";
+/**
+ * True when `moduleUrl`'s file is the process entrypoint. Compares REAL paths (resolving
+ * symlinks) so a bin installed as a symlink by npm/Homebrew — where `process.argv[1]` is the
+ * symlink but `import.meta.url` is the resolved target — is still recognized as the entry.
+ */
+export declare function isMainModule(invokedPath: string | undefined, moduleUrl: string): boolean;
+/**
+ * Run the CLI for the given argv (excluding node + script path) and return the process
+ * exit code. Never calls process.exit — the caller sets `process.exitCode`. `runtime` is
+ * injectable so command tests stay hermetic.
+ */
+export declare function run(argv: string[], io?: Io, runtime?: RuntimeDeps): Promise<number>;