@oh-hai/cli 0.1.0-beta.0

package/dist/config-file.js

@@ -0,0 +1,233 @@
+// Config-file loading (docs/specs/cli.md §6). `config.ts` owns the pure resolution CONTRACT over
+// already-parsed config objects; this module owns the missing half — reading and parsing the TOML
+// files into those objects (#176). Kept separate so `config.ts` stays a pure, disk-free function.
+//
+// Two files feed §6:
+//   • user-global  ~/.config/oh-hai/config.toml  ($XDG_CONFIG_HOME honored) — the ONLY file that may
+//     set routing values (base_url / default_account), plus non-routing (output / timeout_ms / color).
+//   • per-project  .oh-hai/config.toml  (walked up from cwd) — non-routing values only; base_url /
+//     account are passed THROUGH so `resolveConfig` can DETECT + reject them (credential-safety §6),
+//     rather than the loader silently dropping the security signal.
+//
+// Zero runtime deps by design: a tolerant reader for the flat `key = value` + optional `[oh-hai]`
+// section dialect (strings, ints, bools, comments). Malformed lines are skipped, never thrown — a
+// broken config file degrades to "no config", it never crashes the CLI.
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+/**
+ * Parse the minimal config dialect: flat `key = value` lines plus an optional `[oh-hai]` section.
+ * Values are quoted strings (single/double), integers (optional sign + `_` separators), or booleans.
+ * `#` starts a comment. Keys are collected from the top level (before any section header) and from an
+ * `[oh-hai]` section; keys under any other section are ignored. Unparseable lines are skipped so a
+ * malformed file degrades gracefully — this function never throws.
+ */
+export function parseToml(text) {
+    const out = {};
+    // Top-level (before any section header) is collected; a section header flips this per-section.
+    let collecting = true;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#")) {
+            continue;
+        }
+        // A section header, tolerating a trailing inline comment (`[other] # note`). Matching the raw
+        // `[...]` only would leave `collecting` unchanged on a commented header, leaking that section's
+        // keys into the collected namespace.
+        const section = /^\[([^\]]*)\]\s*(?:#.*)?$/.exec(line);
+        if (section !== null) {
+            collecting = section[1]?.trim() === "oh-hai";
+            continue;
+        }
+        if (!collecting) {
+            continue;
+        }
+        const eq = line.indexOf("=");
+        if (eq <= 0) {
+            continue; // no key ("= value") or no separator ("garbage") — skip tolerantly
+        }
+        const key = line.slice(0, eq).trim();
+        if (key === "") {
+            continue;
+        }
+        const value = parseTomlValue(line.slice(eq + 1).trim());
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Classify a raw right-hand-side token into a scalar, or undefined when empty/unparseable. */
+function parseTomlValue(raw) {
+    if (raw === "") {
+        return undefined;
+    }
+    const quote = raw[0];
+    if (quote === '"' || quote === "'") {
+        // Quoted string: content up to the matching close quote; trailing text (e.g. a comment) ignored.
+        // A `#` inside the quotes is preserved. An unterminated quote is malformed → skip.
+        const close = raw.indexOf(quote, 1);
+        return close === -1 ? undefined : raw.slice(1, close);
+    }
+    // Bare value: drop a trailing inline comment, then classify by shape.
+    const hash = raw.indexOf("#");
+    const bare = (hash === -1 ? raw : raw.slice(0, hash)).trim();
+    if (bare === "") {
+        return undefined;
+    }
+    if (bare === "true") {
+        return true;
+    }
+    if (bare === "false") {
+        return false;
+    }
+    if (/^[+-]?\d[\d_]*$/.test(bare)) {
+        const parsed = Number.parseInt(bare.replace(/_/g, ""), 10);
+        return Number.isFinite(parsed) ? parsed : bare;
+    }
+    return bare; // an unquoted string
+}
+/** Type-only coercers: pick a known key when it has the expected type, else drop it (tolerance). */
+function asString(value) {
+    // A blank string counts as absent (matching resolveConfig's presence semantics) so an empty
+    // `account = ""` can't `??`-mask a `default_account` account-setting attempt in mapProjectConfig.
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+/** Node's timer ceiling (`TIMEOUT_MAX`, 2^31 - 1 ms ≈ 24.8 days). A delay above this is silently
+ *  rescheduled as 1 ms (with a `TimeoutOverflowWarning`), so an out-of-range config timeout must be
+ *  dropped rather than accepted — otherwise `whoami --check` would time out almost instantly. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * A timeout must be a non-negative integer no larger than Node's timer ceiling — the same bound the
+ * `--timeout` flag and `MA2H_TIMEOUT_MS` env already enforce. A config-file value outside that range
+ * is dropped here so a stray `timeout_ms = -1` (or an above-ceiling value) can't reach
+ * `AbortSignal.timeout` and either throw or collapse to a 1 ms timeout instead of the sane default.
+ */
+function asTimeout(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= MAX_TIMEOUT_MS
+        ? value
+        : undefined;
+}
+function asBool(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function asOutput(value) {
+    return value === "human" || value === "json" ? value : undefined;
+}
+/** Map a parsed record to the user-global config — the only file that may carry routing values. */
+function mapUserConfig(record) {
+    return {
+        base_url: asString(record.base_url),
+        default_account: asString(record.default_account),
+        output: asOutput(record.output),
+        timeout_ms: asTimeout(record.timeout_ms),
+        color: asBool(record.color),
+    };
+}
+/**
+ * Map a parsed record to the per-project config. base_url / account are carried through on purpose:
+ * `resolveConfig` detects and rejects them with a warning (credential-safety §6) — dropping them here
+ * would hide the fact that a repo tried to redirect the authenticated Hub.
+ */
+function mapProjectConfig(record) {
+    return {
+        base_url: asString(record.base_url),
+        // Accept BOTH the project key (`account`) and the user-config spelling (`default_account`) as an
+        // account-setting attempt, so a repo trying to choose the identity via either name is surfaced to
+        // resolveConfig for a credential-safety rejection rather than silently ignored.
+        account: asString(record.account) ?? asString(record.default_account),
+        output: asOutput(record.output),
+        timeout_ms: asTimeout(record.timeout_ms),
+        color: asBool(record.color),
+    };
+}
+/** Load `~/.config/oh-hai/config.toml` ($XDG_CONFIG_HOME honored). Undefined when the file is absent. */
+export function loadUserConfig(io) {
+    const xdg = io.xdgConfigHome?.trim();
+    const home = io.homedir.trim();
+    // The user-global config is TRUSTED (it alone may set base_url / default_account), so its directory
+    // must be ABSOLUTE — a relative path would resolve against cwd and let a repo-committed file
+    // masquerade as user-global config, bypassing per-project rejection. Prefer an absolute
+    // $XDG_CONFIG_HOME; a relative/blank XDG is ignored in favor of the ~/.config default; if neither
+    // yields an absolute dir (e.g. a minimal container with an empty homedir), skip the user config.
+    const configHome = xdg !== undefined && xdg !== "" && isAbsolute(xdg)
+        ? xdg
+        : home !== "" && isAbsolute(home)
+            ? join(home, ".config")
+            : undefined;
+    if (configHome === undefined) {
+        return undefined;
+    }
+    const text = io.readFile(join(configHome, "oh-hai", "config.toml"));
+    return text === undefined ? undefined : mapUserConfig(parseToml(text));
+}
+/**
+ * Discover the per-project config by walking up from cwd for a `.oh-hai/config.toml`; the nearest
+ * ancestor wins. Undefined when none is found up to the filesystem root.
+ */
+export function loadProjectConfig(io) {
+    // Project discovery needs a real absolute cwd. A non-absolute cwd (e.g. "" when the working
+    // directory was removed before the process started) has nothing meaningful to walk up, so skip
+    // rather than resolving relative paths against a missing cwd.
+    if (!isAbsolute(io.cwd)) {
+        return undefined;
+    }
+    let dir = io.cwd;
+    for (;;) {
+        const text = io.readFile(join(dir, ".oh-hai", "config.toml"));
+        if (text !== undefined) {
+            return mapProjectConfig(parseToml(text));
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return undefined; // reached the root without a hit
+        }
+        dir = parent;
+    }
+}
+/** Load both config files (user-global + per-project) for `resolveConfig`. */
+export function loadConfigFiles(io) {
+    return {
+        userConfig: loadUserConfig(io),
+        projectConfig: loadProjectConfig(io),
+    };
+}
+/** Generous ceiling on a config file's size — real configs are a few keys; anything larger is either
+ *  a mistake or a hostile plant, so it's skipped rather than read into memory. */
+const MAX_CONFIG_BYTES = 1024 * 1024;
+/** Read an OS value that can throw (notably `process.cwd()` when the working dir was removed), degrading
+ *  to "" so config loading never crashes a command that doesn't even need the value. */
+function safeOsValue(read) {
+    try {
+        return read();
+    }
+    catch {
+        return "";
+    }
+}
+/** Production `ConfigFileIo` backed by the real filesystem, home dir, cwd, and environment. */
+export function nodeConfigFileIo() {
+    return {
+        readFile: (path) => {
+            try {
+                // The per-project `.oh-hai/config.toml` path is repo-controlled, so a hostile checkout could
+                // plant a FIFO, a device, or a symlink to `/dev/zero` there — an unconditional readFileSync
+                // would hang or exhaust memory. Stat first (stat never blocks on a FIFO) and only read a
+                // regular file within the size cap. The stat→read TOCTOU is irrelevant here: the threat is a
+                // static malicious checkout, not a local attacker racing us between the two calls.
+                const stats = statSync(path);
+                if (!stats.isFile() || stats.size > MAX_CONFIG_BYTES) {
+                    return undefined;
+                }
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return undefined; // missing / unreadable → treated as "no config file here"
+            }
+        },
+        homedir: safeOsValue(homedir),
+        cwd: safeOsValue(() => process.cwd()),
+        xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    };
+}
+//# sourceMappingURL=config-file.js.map

package/dist/config-file.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,64 @@
+export declare const DEFAULT_BASE_URL = "http://localhost:8787";
+export type OutputFormat = "human" | "json";
+export type TokenSource = "env" | "keychain" | "file" | "none";
+/** Global flags after parsing (the subset that feeds config resolution). */
+export interface RawFlags {
+    baseUrl?: string | undefined;
+    account?: string | undefined;
+    json?: boolean | undefined;
+    noColor?: boolean | undefined;
+    timeoutMs?: number | undefined;
+}
+/** The environment variables §6 consumes (the `MA2H_*` set kept for back-compat). */
+export interface EnvVars {
+    MA2H_BASE_URL?: string | undefined;
+    MA2H_AGENT_ID?: string | undefined;
+    MA2H_AGENT_TOKEN?: string | undefined;
+    MA2H_TIMEOUT_MS?: string | undefined;
+    NO_COLOR?: string | undefined;
+}
+/** User-global config (`~/.config/oh-hai/config.toml`) — the ONLY file that may set routing values. */
+export interface UserConfig {
+    base_url?: string | undefined;
+    default_account?: string | undefined;
+    output?: OutputFormat | undefined;
+    timeout_ms?: number | undefined;
+    color?: boolean | undefined;
+}
+/**
+ * Per-project config (`.oh-hai/config.toml` discovered by walking up from cwd).
+ * `base_url` / `account` are accepted in the type only so we can DETECT and reject them —
+ * they are never honored (credential-safety, §6).
+ */
+export interface ProjectConfig {
+    base_url?: string | undefined;
+    account?: string | undefined;
+    output?: OutputFormat | undefined;
+    timeout_ms?: number | undefined;
+    color?: boolean | undefined;
+}
+export interface ResolvedConfig {
+    baseUrl: string;
+    account: string | undefined;
+    output: OutputFormat;
+    timeoutMs: number | undefined;
+    color: boolean;
+    token: string | undefined;
+    tokenSource: TokenSource;
+}
+export interface ResolveInput {
+    flags?: RawFlags | undefined;
+    env?: EnvVars | undefined;
+    userConfig?: UserConfig | undefined;
+    projectConfig?: ProjectConfig | undefined;
+}
+export interface ResolveResult {
+    config: ResolvedConfig;
+    /** Non-fatal warnings (e.g. a per-project config tried to set a routing value). */
+    warnings: string[];
+}
+/**
+ * Resolve the effective config from flags, env, and (already-parsed) config objects,
+ * honoring §6 precedence, the token special-case, and per-project credential-safety.
+ */
+export declare function resolveConfig(input?: ResolveInput): ResolveResult;

package/dist/config.js

@@ -0,0 +1,97 @@
+// Config precedence + resolution (docs/specs/cli.md §6).
+//
+//   value := first-present( CLI flag , environment , config file , built-in default )
+//
+// Two rules make this security-relevant, so they live here as pure, tested functions:
+//   1. The TOKEN is special-cased — it comes from the `MA2H_AGENT_TOKEN` env (the CI path)
+//      here, and NEVER from a config-file value (§5.4). Keychain/file backends land in #106.
+//   2. Per-project config is credential-safe — a repo-controlled `.oh-hai/config.toml` may
+//      set only non-routing values (output/timeout/color). It MUST NOT redirect `base_url`
+//      or `account`, or a hostile checkout could send the bearer to an endpoint it chose.
+//
+// #105 implements the resolution CONTRACT over an already-parsed, in-memory config object.
+// The TOML file loader + per-project discovery + keychain read land in #106/#107.
+export const DEFAULT_BASE_URL = "http://localhost:8787";
+/** A string is "present" only when non-empty after trimming; the trimmed value is returned
+ *  so stray whitespace never rides along into a base URL / account / token. */
+function presentString(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** First present value in precedence order (undefined / empty-string entries are skipped). */
+function firstPresent(...values) {
+    for (const value of values) {
+        const present = presentString(value);
+        if (present !== undefined) {
+            return present;
+        }
+    }
+    return undefined;
+}
+function parseTimeout(value) {
+    const present = presentString(value);
+    if (present === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(present, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+/**
+ * Resolve the effective config from flags, env, and (already-parsed) config objects,
+ * honoring §6 precedence, the token special-case, and per-project credential-safety.
+ */
+export function resolveConfig(input = {}) {
+    const flags = input.flags ?? {};
+    const env = input.env ?? {};
+    const userConfig = input.userConfig ?? {};
+    const projectConfig = input.projectConfig ?? {};
+    const warnings = [];
+    // Credential-safety: a per-project config may NOT set base_url / account (§6). Detect
+    // and drop them so a repo-controlled checkout can never redirect the authenticated Hub.
+    if (presentString(projectConfig.base_url) !== undefined) {
+        warnings.push("ignoring per-project `base_url` — the Hub URL must come from --base-url or MA2H_BASE_URL (credential-safety, cli spec §6)");
+    }
+    if (presentString(projectConfig.account) !== undefined) {
+        warnings.push("ignoring per-project `account` — the account must come from --account or MA2H_AGENT_ID (credential-safety, cli spec §6)");
+    }
+    // base_url: flag > env > USER config only > default. Project config is excluded on purpose.
+    // Strip trailing slashes so downstream URL construction (`${baseUrl}/v1/…`, #107) can't
+    // double up — matches the scripts/ layer's resolveBaseUrl. A slash-only value strips to
+    // empty, so fall back to the default rather than yield an unusable "".
+    const resolvedBase = (firstPresent(flags.baseUrl, env.MA2H_BASE_URL, userConfig.base_url) ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const baseUrl = resolvedBase === "" ? DEFAULT_BASE_URL : resolvedBase;
+    // account: flag > env > USER config only. Project config excluded on purpose.
+    const account = firstPresent(flags.account, env.MA2H_AGENT_ID, userConfig.default_account);
+    // output: an explicit --json flag wins EITHER way (--json → json, --json=false → human, upholding
+    // flag > config precedence); only when the flag is absent does the config `output` decide; else human.
+    const output = flags.json === true
+        ? "json"
+        : flags.json === false
+            ? "human"
+            : projectConfig.output ?? userConfig.output ?? "human";
+    // timeout: flag > env > project > user config. (project MAY set this — non-routing.)
+    const timeoutMs = flags.timeoutMs ??
+        parseTimeout(env.MA2H_TIMEOUT_MS) ??
+        projectConfig.timeout_ms ??
+        userConfig.timeout_ms;
+    // color: --no-color / NO_COLOR force off; else project/user config; else auto (true here,
+    // the print layer narrows to TTY). Non-routing, so project config MAY set it.
+    let color;
+    if (flags.noColor === true || presentString(env.NO_COLOR) !== undefined) {
+        color = false;
+    }
+    else {
+        color = projectConfig.color ?? userConfig.color ?? true;
+    }
+    // token: env only (#105); keychain/file land in #106. NEVER from a config value (§5.4).
+    const envToken = presentString(env.MA2H_AGENT_TOKEN);
+    const tokenSource = envToken !== undefined ? "env" : "none";
+    return {
+        config: { baseUrl, account, output, timeoutMs, color, token: envToken, tokenSource },
+        warnings,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/envelope.d.ts

@@ -0,0 +1,25 @@
+import { type ErrorCode, type ExitCode } from "./exit-codes.js";
+/** A command failure carrying a stable `error.code` (§8) → §7 exit code. */
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+    /** The §7 exit code this error maps to. */
+    get exitCode(): ExitCode;
+}
+export interface JsonEnvelope {
+    ok: boolean;
+    command: string;
+    data: Record<string, unknown> | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+/** Drop `undefined` values so absent optional fields are omitted from `data`, not `null` (§8). */
+export declare function pruneUndefined(data: Record<string, unknown>): Record<string, unknown>;
+/** Build a success envelope. `data` is pruned of undefined optionals. */
+export declare function buildOk(command: string, data: Record<string, unknown>): JsonEnvelope;
+/** Build a failure envelope. `data` is always null; the token is never present (§5.4). */
+export declare function buildErr(command: string, code: string, message: string): JsonEnvelope;
+/** Serialize an envelope to the single line printed on stdout under `--json`. */
+export declare function serializeEnvelope(envelope: JsonEnvelope): string;

package/dist/envelope.js

@@ -0,0 +1,41 @@
+// The uniform `--json` output envelope (docs/specs/cli.md §8) and the CliError type
+// that carries a stable `error.code`. The envelope builders are the single choke point
+// for machine output, so the redaction rule (§5.4 — the token is NEVER in the envelope)
+// and the "absent optional fields are omitted, not null" rule are enforced in one place.
+import { exitCodeForError } from "./exit-codes.js";
+/** A command failure carrying a stable `error.code` (§8) → §7 exit code. */
+export class CliError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+    }
+    /** The §7 exit code this error maps to. */
+    get exitCode() {
+        return exitCodeForError(this.code);
+    }
+}
+/** Drop `undefined` values so absent optional fields are omitted from `data`, not `null` (§8). */
+export function pruneUndefined(data) {
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Build a success envelope. `data` is pruned of undefined optionals. */
+export function buildOk(command, data) {
+    return { ok: true, command, data: pruneUndefined(data), error: null };
+}
+/** Build a failure envelope. `data` is always null; the token is never present (§5.4). */
+export function buildErr(command, code, message) {
+    return { ok: false, command, data: null, error: { code, message } };
+}
+/** Serialize an envelope to the single line printed on stdout under `--json`. */
+export function serializeEnvelope(envelope) {
+    return JSON.stringify(envelope);
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,uFAAuF;AACvF,wFAAwF;AACxF,yFAAyF;AAEzF,OAAO,EAAE,gBAAgB,EAAiC,MAAM,iBAAiB,CAAC;AAElF,4EAA4E;AAC5E,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAY;IAEzB,YAAY,IAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,2CAA2C;IAC3C,IAAI,QAAQ;QACV,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;CACF;AASD,kGAAkG;AAClG,MAAM,UAAU,cAAc,CAAC,IAA6B;IAC1D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,IAA6B;IACpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACxE,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,IAAY,EAAE,OAAe;IACrE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;AACtE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,QAAsB;IACtD,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/exit-codes.d.ts

@@ -0,0 +1,51 @@
+export declare const ExitCode: {
+    /** 0 — Success. */
+    readonly SUCCESS: 0;
+    /** 1 — Generic / unexpected error. */
+    readonly ERROR: 1;
+    /** 2 — Usage error (bad local flags/args, before any Hub call). */
+    readonly USAGE: 2;
+    /** 3 — Not authenticated / auth failed (Hub 401/403; no token). */
+    readonly AUTH: 3;
+    /** 4 — Not found (unknown id / resource; Hub 404). */
+    readonly NOT_FOUND: 4;
+    /** 5 — Network / offline (DNS, connection refused, unreachable). */
+    readonly NETWORK: 5;
+    /** 6 — Hub server error (5xx). */
+    readonly SERVER: 6;
+    /** 7 — Timeout (per-request `--timeout`, or `await` poll budget). */
+    readonly TIMEOUT: 7;
+    /** 8 — Conflict (Hub 409; duplicate idempotency key, different payload). */
+    readonly CONFLICT: 8;
+    /** 9 — Invalid request (Hub 400/422/413; version not supported). */
+    readonly INVALID_REQUEST: 9;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * Stable `error.code` strings (§8) → exit codes (§7). An exit code may cover more
+ * than one code string (e.g. the four request errors all map to 9). `not_implemented`
+ * is the scaffold's own code for commands that land in #106–#108 → generic exit 1.
+ */
+declare const ERROR_CODE_TO_EXIT: {
+    readonly error: 1;
+    readonly usage: 2;
+    readonly auth: 3;
+    readonly not_found: 4;
+    readonly network: 5;
+    readonly server: 6;
+    readonly timeout: 7;
+    readonly conflict: 8;
+    readonly bad_request: 9;
+    readonly validation_error: 9;
+    readonly payload_too_large: 9;
+    readonly version_not_supported: 9;
+    readonly not_implemented: 1;
+};
+export type ErrorCode = keyof typeof ERROR_CODE_TO_EXIT;
+/** Map a (possibly unknown) `error.code` string to its exit code; unknown → generic 1. */
+export declare function exitCodeForError(code: string): ExitCode;
+/** True when `code` is one of the documented `error.code` strings (§8). Lets callers distinguish a
+ *  recognized code from an arbitrary/undocumented one (which `exitCodeForError` flattens to 1), so a
+ *  Hub-supplied `error.code` like `rate_limited` is never surfaced verbatim in the CLI envelope. */
+export declare function isErrorCode(code: string): code is ErrorCode;
+export {};

package/dist/exit-codes.js

@@ -0,0 +1,57 @@
+// The stable exit-code table (docs/specs/cli.md §7) and the map from a `--json`
+// envelope `error.code` string (§8) to its exit code. This is the machine contract
+// every command branches on; keep it in lockstep with the spec.
+export const ExitCode = {
+    /** 0 — Success. */
+    SUCCESS: 0,
+    /** 1 — Generic / unexpected error. */
+    ERROR: 1,
+    /** 2 — Usage error (bad local flags/args, before any Hub call). */
+    USAGE: 2,
+    /** 3 — Not authenticated / auth failed (Hub 401/403; no token). */
+    AUTH: 3,
+    /** 4 — Not found (unknown id / resource; Hub 404). */
+    NOT_FOUND: 4,
+    /** 5 — Network / offline (DNS, connection refused, unreachable). */
+    NETWORK: 5,
+    /** 6 — Hub server error (5xx). */
+    SERVER: 6,
+    /** 7 — Timeout (per-request `--timeout`, or `await` poll budget). */
+    TIMEOUT: 7,
+    /** 8 — Conflict (Hub 409; duplicate idempotency key, different payload). */
+    CONFLICT: 8,
+    /** 9 — Invalid request (Hub 400/422/413; version not supported). */
+    INVALID_REQUEST: 9,
+};
+/**
+ * Stable `error.code` strings (§8) → exit codes (§7). An exit code may cover more
+ * than one code string (e.g. the four request errors all map to 9). `not_implemented`
+ * is the scaffold's own code for commands that land in #106–#108 → generic exit 1.
+ */
+const ERROR_CODE_TO_EXIT = {
+    error: ExitCode.ERROR,
+    usage: ExitCode.USAGE,
+    auth: ExitCode.AUTH,
+    not_found: ExitCode.NOT_FOUND,
+    network: ExitCode.NETWORK,
+    server: ExitCode.SERVER,
+    timeout: ExitCode.TIMEOUT,
+    conflict: ExitCode.CONFLICT,
+    bad_request: ExitCode.INVALID_REQUEST,
+    validation_error: ExitCode.INVALID_REQUEST,
+    payload_too_large: ExitCode.INVALID_REQUEST,
+    version_not_supported: ExitCode.INVALID_REQUEST,
+    not_implemented: ExitCode.ERROR,
+};
+/** Map a (possibly unknown) `error.code` string to its exit code; unknown → generic 1. */
+export function exitCodeForError(code) {
+    const table = ERROR_CODE_TO_EXIT;
+    return table[code] ?? ExitCode.ERROR;
+}
+/** True when `code` is one of the documented `error.code` strings (§8). Lets callers distinguish a
+ *  recognized code from an arbitrary/undocumented one (which `exitCodeForError` flattens to 1), so a
+ *  Hub-supplied `error.code` like `rate_limited` is never surfaced verbatim in the CLI envelope. */
+export function isErrorCode(code) {
+    return Object.prototype.hasOwnProperty.call(ERROR_CODE_TO_EXIT, code);
+}
+//# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,mFAAmF;AACnF,gEAAgE;AAEhE,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,mBAAmB;IACnB,OAAO,EAAE,CAAC;IACV,sCAAsC;IACtC,KAAK,EAAE,CAAC;IACR,mEAAmE;IACnE,KAAK,EAAE,CAAC;IACR,mEAAmE;IACnE,IAAI,EAAE,CAAC;IACP,sDAAsD;IACtD,SAAS,EAAE,CAAC;IACZ,oEAAoE;IACpE,OAAO,EAAE,CAAC;IACV,kCAAkC;IAClC,MAAM,EAAE,CAAC;IACT,qEAAqE;IACrE,OAAO,EAAE,CAAC;IACV,4EAA4E;IAC5E,QAAQ,EAAE,CAAC;IACX,oEAAoE;IACpE,eAAe,EAAE,CAAC;CACV,CAAC;AAIX;;;;GAIG;AACH,MAAM,kBAAkB,GAAG;IACzB,KAAK,EAAE,QAAQ,CAAC,KAAK;IACrB,KAAK,EAAE,QAAQ,CAAC,KAAK;IACrB,IAAI,EAAE,QAAQ,CAAC,IAAI;IACnB,SAAS,EAAE,QAAQ,CAAC,SAAS;IAC7B,OAAO,EAAE,QAAQ,CAAC,OAAO;IACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;IACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;IACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;IAC3B,WAAW,EAAE,QAAQ,CAAC,eAAe;IACrC,gBAAgB,EAAE,QAAQ,CAAC,eAAe;IAC1C,iBAAiB,EAAE,QAAQ,CAAC,eAAe;IAC3C,qBAAqB,EAAE,QAAQ,CAAC,eAAe;IAC/C,eAAe,EAAE,QAAQ,CAAC,KAAK;CACvB,CAAC;AAIX,0FAA0F;AAC1F,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAA6B,kBAAkB,CAAC;IAC3D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC;AACvC,CAAC;AAED;;oGAEoG;AACpG,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;AACxE,CAAC"}

package/dist/help.d.ts

@@ -0,0 +1 @@
+export declare const TOP_LEVEL_HELP: string;

package/dist/help.js

@@ -0,0 +1,17 @@
+// Help text. The top-level copy mirrors docs/specs/cli.md §10; per-command help comes
+// from the registry (read directly off the CommandSpec at dispatch).
+export const TOP_LEVEL_HELP = [
+    "oh-hai — reach a human from your agent, through an MA2H Hub.",
+    "",
+    "Usage: oh-hai [global flags] <command> [subcommand] [flags]",
+    "",
+    "Auth:       login | logout | whoami",
+    "Messaging:  notify | ask | task",
+    "Inbox:      inbox watch",
+    "Agents:     agents list | create | revoke",
+    "Health:     doctor",
+    "",
+    "Global flags: --base-url --account --json --quiet --verbose --no-color --timeout",
+    "Run 'oh-hai <command> --help' for details.",
+].join("\n");
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,qEAAqE;AAErE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,8DAA8D;IAC9D,EAAE;IACF,6DAA6D;IAC7D,EAAE;IACF,qCAAqC;IACrC,iCAAiC;IACjC,yBAAyB;IACzB,2CAA2C;IAC3C,oBAAoB;IACpB,EAAE;IACF,kFAAkF;IAClF,4CAA4C;CAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/dist/terminal.d.ts

@@ -0,0 +1,5 @@
+/** Strip terminal control characters (C0/C1 + DEL) from a server-supplied string before echoing it.
+ *  Built by code point to avoid a control-char regex literal. The raw value is kept for lookups and
+ *  the `--json` envelope (JSON.stringify escapes control characters) — only terminal output is
+ *  sanitized. */
+export declare function sanitizeForTerminal(value: string): string;