@oh-hai/cli 0.2.0 → 0.2.1

package/README.md

@@ -53,6 +53,24 @@ Bare `oh-hai login` (the browser **device-code** flow) is not available yet —
 server device-authorization grant + a web approval page (tracked in **#166**); until then it
 declines with a pointer to `--token-stdin`.
 
+### Per-project identity (`use`)
+
+Running multiple agents on one machine? Bind a directory to a specific agent so sessions in
+that tree target it automatically — no `--account` on every command. The **simple path stays
+simple**: one agent, zero config, no `use` needed.
+
+```bash
+oh-hai use my-project-agent   # bind this directory (and its subtree) to my-project-agent
+oh-hai whoami                 # → agent: my-project-agent · via: binding (<dir>)
+oh-hai use --list             # show all directory bindings
+oh-hai use --unset            # remove this directory's binding
+```
+
+Bindings are **user-side** (`~/.config/oh-hai/bindings.json`), scoped per Hub, and **never**
+settable from a repo — a cloned `.oh-hai/config.toml` can't re-route your identity
+([spec §6](../docs/specs/cli.md)). Precedence: `--account`/`MA2H_AGENT_ID` > directory
+binding > user `default_account`. Offline — the agent need not be logged in yet.
+
 ### Messaging (`notify` / `ask` / `task`)
 
 The productized counterparts of the `@oh-hai/scripts` wrappers ([spec §4.4](../docs/specs/cli.md)):
@@ -77,23 +95,48 @@ oh-hai ask submit --envelope @captured.json    # idempotent replay of a captured
 
 ## Install
 
-```bash
-# npm (global)
-npm install -g @oh-hai/cli
+> **New to OH HAI?** For a top-to-bottom walkthrough — install → onboard → your first
+> `notify`/`ask`/`task` — see the [Connect your agent guide](../docs/guides/connect-your-agent.md).
+> This README is the implementer-facing package reference.
 
-# Homebrew (tap)
-brew install autnmy/tap/oh-hai
+The headline path is the standalone binary — no Node required. The installer detects your
+OS + arch, downloads the matching binary from the ohhai.app distribution mirror, verifies
+its SHA-256 checksum, and puts `oh-hai` on your `PATH`:
 
-# curl installer (served at ohhai.app once DNS lands — issue #99)
-curl -fsSL https://ohhai.app/install | sh
+```sh
+# macOS / Linux
+curl -fsSL https://ohhai.autonomy.com.ai/install | sh
+
+# Windows (PowerShell)
+irm https://ohhai.autonomy.com.ai/install.ps1 | iex
+```
+
+> `ohhai.autonomy.com.ai` is the live Pages domain today; the same scripts are served at
+> `https://ohhai.app/install.sh` and `https://ohhai.app/install.ps1` once the dist Worker
+> is live.
+>
+> The repo is private, so binaries are served from the public **ohhai.app mirror**
+> (`dist-worker/` + an R2 bucket CI fills on each release — issue #357). Until the
+> coordinator provisions the bucket/Worker/secrets (see `dist-worker/README.md`), the
+> binary download 404s and an unauthenticated install falls back to npm. Use the npm
+> install below until then.
+
+npm is the secondary channel for node devs (and the automatic fallback when a host has no
+prebuilt binary, e.g. windows-arm64):
+
+```bash
+npm install -g @oh-hai/cli
 ```
 
+`OH_HAI_VERSION` pins a version on either channel. (Homebrew was dropped in favor of the
+standalone binaries — epic #277.)
+
 ## Command surface (see [spec §4](../docs/specs/cli.md))
 
 ```
 oh-hai [global flags] <command> [subcommand] [flags]
 
-  Auth      login | logout | whoami
+  Auth      login | logout | whoami | use
   Messaging notify | ask | task
   Agents    agents list | create | revoke
   Health    doctor

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

@@ -1,5 +1,7 @@
+import { originOf } from "../url.js";
 import type { ResolvedConfig, TokenSource } from "../config.js";
 import type { CredentialStore } from "./token-store.js";
+export { originOf };
 export interface ResolvedToken {
     token: string | undefined;
     source: TokenSource;
@@ -12,10 +14,6 @@ export interface ResolvedIdentity {
     token: string | undefined;
     source: TokenSource;
 }
-/** 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 declare function originOf(baseUrl: string): string;
 /** 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 declare function resolveToken(config: ResolvedConfig, store?: CredentialStore): Promise<ResolvedToken>;

package/dist/auth/resolve-token.js

@@ -15,17 +15,10 @@
 // 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;
-    }
-}
+import { originOf } from "../url.js";
+// `originOf` now has a single home in url.ts (shared with the config layer's binding-origin
+// resolution); re-exported here so the existing importers (`../auth/resolve-token.js`) are unaffected.
+export { originOf };
 /** 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) {

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

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

package/dist/bindings.d.ts

@@ -0,0 +1,65 @@
+/** One directory→agent binding, scoped to a Hub origin. `path` is an absolute, normalized directory. */
+export interface Binding {
+    path: string;
+    account: string;
+    origin: string;
+}
+/**
+ * Injectable filesystem/environment seam so the store is unit-testable against an in-memory map with
+ * zero disk access (mirrors `ConfigFileIo` in config-file.ts). `readFile` returns undefined for a
+ * missing/unreadable file; `writeFile` creates any missing parent directories.
+ */
+export interface BindingsIo {
+    readFile(path: string): string | undefined;
+    writeFile(path: string, content: string): void;
+    homedir: string;
+    xdgConfigHome: string | undefined;
+    /** The process working directory — the directory `oh-hai use` binds, and the walk-up anchor for
+     *  resolution. A single injected source (mirrors `ConfigFileIo.cwd`) so the command that WRITES a
+     *  binding and the entrypoint that RESOLVES one agree on the same cwd. */
+    cwd: string;
+}
+/**
+ * Resolve the absolute path of the bindings file under the trusted config dir (`resolveXdgConfigHome`,
+ * shared with `loadUserConfig`). That helper enforces the credential-safety guarantee — a relative or
+ * blank `$XDG_CONFIG_HOME` must never let a cwd-relative file act as the trusted bindings store — and
+ * returns undefined when no absolute config dir exists (e.g. a minimal container with an empty homedir).
+ */
+export declare function bindingsFilePath(io: BindingsIo): string | undefined;
+/**
+ * Load and parse the bindings file. Undefined config dir, missing file, unparseable JSON, or a
+ * non-array `bindings` all degrade to `[]` — a broken bindings file never crashes the CLI. Malformed
+ * individual records are dropped; the rest are kept.
+ */
+export declare function loadBindings(io: BindingsIo): Binding[];
+/** Whether the binding store can be safely WRITTEN, for the mutating commands (`use <agent>` /
+ *  `use --unset`) to check BEFORE reporting success:
+ *   - `"unavailable"` — no trusted absolute config dir (bindingsFilePath undefined); a write would
+ *     silently no-op, so a caller must NOT claim a persisted binding.
+ *   - `"unsupported-version"` — the file was written by a NEWER CLI; `loadBindings` read-degrades it to
+ *     [], but blindly writing a fresh v1 doc would ERASE the newer CLI's bindings — refuse instead.
+ *   - `"ok"` — absent, malformed (safe to overwrite; loadBindings already degrades it to []), or a v1
+ *     file. Reads never need this (loadBindings is always safe); only writes do. */
+export declare function bindingStoreStatus(io: BindingsIo): "ok" | "unavailable" | "unsupported-version";
+/**
+ * Resolve the binding that applies to `cwd` for `origin`, walking up (git-style): among bindings for
+ * this origin whose directory is `cwd` or an ancestor of it, the NEAREST (deepest — longest path) wins.
+ * Pure — no I/O. Returns undefined when `cwd` is non-absolute (nothing meaningful to walk) or no
+ * binding matches.
+ */
+export declare function resolveBinding(bindings: Binding[], cwd: string, origin: string): {
+    account: string;
+    path: string;
+} | undefined;
+/**
+ * Bind `cwd` → `account` for `origin`, upserting by `(path, origin)` so re-binding the same directory
+ * for the same Hub replaces the account rather than duplicating. Returns the normalized bound path.
+ */
+export declare function setBinding(io: BindingsIo, cwd: string, origin: string, account: string): string;
+/**
+ * Remove the binding for `cwd` + `origin`. Idempotent — returns true when a binding was removed, false
+ * when there was none (so the caller can report "nothing to unbind" without erroring).
+ */
+export declare function unsetBinding(io: BindingsIo, cwd: string, origin: string): boolean;
+/** Production `BindingsIo` backed by the real filesystem, home dir, and environment. */
+export declare function nodeBindingsIo(): BindingsIo;

package/dist/bindings.js

@@ -0,0 +1,242 @@
+// User-side directory→agent bindings (docs/specs/cli.md §6, #321 — part of #307). A binding maps a
+// project DIRECTORY to the agent that sessions in that tree should act as, scoped to a Hub origin, so a
+// session no longer has to thread `--account <id>` through every invocation. This is the foundational,
+// purely-additive slice of per-project identity: with no binding, resolution behaves exactly as before.
+//
+// CREDENTIAL-SAFETY (§6). The binding is honored ONLY from the USER config dir (`~/.config/oh-hai/`,
+// $XDG_CONFIG_HOME honored), never from a repo. A repo-controlled `.oh-hai/config.toml` is already
+// forbidden from setting `account`; a directory binding cannot come from a repo either, because this
+// loader reads a single user-global file under an ABSOLUTE config dir (the same discipline
+// `loadUserConfig` uses in config-file.ts) — a relative/blank XDG that could resolve against cwd is
+// rejected, so a checked-out file can never masquerade as the bindings store.
+//
+// Storage is `~/.config/oh-hai/bindings.json` — structured relational records don't fit the flat
+// `key = value` TOML dialect, and JSON is zero-dep to read/write. A missing or malformed file degrades
+// to "no bindings" (never throws), matching the config loader's tolerant posture.
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { resolveXdgConfigHome, safeOsValue } from "./os.js";
+/**
+ * Resolve the absolute path of the bindings file under the trusted config dir (`resolveXdgConfigHome`,
+ * shared with `loadUserConfig`). That helper enforces the credential-safety guarantee — a relative or
+ * blank `$XDG_CONFIG_HOME` must never let a cwd-relative file act as the trusted bindings store — and
+ * returns undefined when no absolute config dir exists (e.g. a minimal container with an empty homedir).
+ */
+export function bindingsFilePath(io) {
+    const configHome = resolveXdgConfigHome(io);
+    return configHome === undefined ? undefined : join(configHome, "oh-hai", "bindings.json");
+}
+/** Coerce one parsed record into a `Binding`, or undefined when it's malformed. A binding is only
+ *  kept when path/account/origin are all non-empty strings AND the path is absolute — a relative path
+ *  would resolve against cwd during resolution and break the user-side isolation, so it's dropped. */
+function asBinding(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const record = value;
+    const path = record.path;
+    const account = record.account;
+    const origin = record.origin;
+    if (typeof path !== "string" ||
+        typeof account !== "string" ||
+        typeof origin !== "string" ||
+        path.trim() === "" ||
+        account.trim() === "" ||
+        origin.trim() === "" ||
+        !isAbsolute(path)) {
+        return undefined;
+    }
+    // Normalize the path so stored and resolution-time comparisons agree (collapse `.`/`..`, dedupe seps).
+    return { path: resolve(path), account, origin };
+}
+/**
+ * Load and parse the bindings file. Undefined config dir, missing file, unparseable JSON, or a
+ * non-array `bindings` all degrade to `[]` — a broken bindings file never crashes the CLI. Malformed
+ * individual records are dropped; the rest are kept.
+ */
+export function loadBindings(io) {
+    const filePath = bindingsFilePath(io);
+    if (filePath === undefined) {
+        return [];
+    }
+    const text = io.readFile(filePath);
+    if (text === undefined) {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return [];
+    }
+    // Version gate: this loader understands v1 (the only version written). A file stamped with a NEWER
+    // version is from a future CLI whose format we can't safely parse, so ignore it (degrade to []) rather
+    // than misread it. A MISSING version is tolerated as v1 — this CLI is the sole writer and always stamps
+    // v1, so an absent stamp means a hand-authored/legacy file, not a format we don't understand.
+    const version = parsed.version;
+    if (version !== undefined && version !== 1) {
+        return [];
+    }
+    const raw = parsed.bindings;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const out = [];
+    for (const record of raw) {
+        const binding = asBinding(record);
+        if (binding !== undefined) {
+            out.push(binding);
+        }
+    }
+    return out;
+}
+/** Whether the binding store can be safely WRITTEN, for the mutating commands (`use <agent>` /
+ *  `use --unset`) to check BEFORE reporting success:
+ *   - `"unavailable"` — no trusted absolute config dir (bindingsFilePath undefined); a write would
+ *     silently no-op, so a caller must NOT claim a persisted binding.
+ *   - `"unsupported-version"` — the file was written by a NEWER CLI; `loadBindings` read-degrades it to
+ *     [], but blindly writing a fresh v1 doc would ERASE the newer CLI's bindings — refuse instead.
+ *   - `"ok"` — absent, malformed (safe to overwrite; loadBindings already degrades it to []), or a v1
+ *     file. Reads never need this (loadBindings is always safe); only writes do. */
+export function bindingStoreStatus(io) {
+    const filePath = bindingsFilePath(io);
+    if (filePath === undefined) {
+        return "unavailable";
+    }
+    const text = io.readFile(filePath);
+    if (text === undefined) {
+        return "ok"; // absent → a fresh write is fine
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === "object" && parsed !== null) {
+            const version = parsed.version;
+            if (version !== undefined && version !== 1) {
+                return "unsupported-version";
+            }
+        }
+    }
+    catch {
+        // Malformed JSON is not a newer-version file — loadBindings degrades it to [], so overwriting a
+        // corrupt store is acceptable (nothing recoverable is lost).
+    }
+    return "ok";
+}
+/** True when `ancestor` is `dir` itself or a parent directory of it — a segment-aware test (NOT a raw
+ *  string prefix, so `/a/bc` is not treated as an ancestor of `/a/bcd`). Both inputs are assumed
+ *  already absolute + normalized. */
+function isAncestorOrEqual(ancestor, dir) {
+    const rel = relative(ancestor, dir);
+    // "" → same dir; a within-tree descendant → a relative path that neither ESCAPES the ancestor nor is
+    // absolute (a different Windows drive yields an absolute relative()). The escape test is separator-
+    // aware — exactly ".." or a ".." FIRST SEGMENT (".." + sep) — so a descendant directory whose own name
+    // merely starts with ".." (e.g. `/proj/..cache/build` → rel `..cache/build`) is NOT misread as an escape.
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** Depth of a normalized absolute path, as a segment count — the unambiguous "nearest ancestor" metric
+ *  for the walk-up. (For two ancestors of the same directory this agrees with string length, since they
+ *  are strictly nested; segment count states the intent directly and can't be second-guessed.) */
+function pathDepth(path) {
+    return path.split(sep).filter((segment) => segment !== "").length;
+}
+/**
+ * Resolve the binding that applies to `cwd` for `origin`, walking up (git-style): among bindings for
+ * this origin whose directory is `cwd` or an ancestor of it, the NEAREST (deepest — longest path) wins.
+ * Pure — no I/O. Returns undefined when `cwd` is non-absolute (nothing meaningful to walk) or no
+ * binding matches.
+ */
+export function resolveBinding(bindings, cwd, origin) {
+    if (!isAbsolute(cwd)) {
+        return undefined;
+    }
+    const here = resolve(cwd);
+    let best;
+    for (const binding of bindings) {
+        if (binding.origin !== origin) {
+            continue;
+        }
+        if (!isAncestorOrEqual(binding.path, here)) {
+            continue;
+        }
+        // Nearest ancestor = deepest (most path segments); all candidates are ancestors of `here`, so
+        // they're strictly nested and the deepest is the most specific binding.
+        if (best === undefined || pathDepth(binding.path) > pathDepth(best.path)) {
+            best = binding;
+        }
+    }
+    return best === undefined ? undefined : { account: best.account, path: best.path };
+}
+/** Persist the given bindings to the store (creates the config dir). No-op when no absolute config
+ *  dir exists — writing to a cwd-relative path would defeat the user-side isolation. */
+function writeBindings(io, bindings) {
+    const filePath = bindingsFilePath(io);
+    if (filePath === undefined) {
+        return;
+    }
+    const doc = { version: 1, bindings };
+    io.writeFile(filePath, `${JSON.stringify(doc, null, 2)}\n`);
+}
+/**
+ * Bind `cwd` → `account` for `origin`, upserting by `(path, origin)` so re-binding the same directory
+ * for the same Hub replaces the account rather than duplicating. Returns the normalized bound path.
+ */
+export function setBinding(io, cwd, origin, account) {
+    const path = resolve(cwd);
+    const kept = loadBindings(io).filter((b) => !(b.path === path && b.origin === origin));
+    kept.push({ path, account, origin });
+    writeBindings(io, kept);
+    return path;
+}
+/**
+ * Remove the binding for `cwd` + `origin`. Idempotent — returns true when a binding was removed, false
+ * when there was none (so the caller can report "nothing to unbind" without erroring).
+ */
+export function unsetBinding(io, cwd, origin) {
+    const path = resolve(cwd);
+    const all = loadBindings(io);
+    const kept = all.filter((b) => !(b.path === path && b.origin === origin));
+    if (kept.length === all.length) {
+        return false;
+    }
+    writeBindings(io, kept);
+    return true;
+}
+/** Generous ceiling on the bindings file — a real one is a handful of records; larger is a mistake or a
+ *  hostile plant, so it's skipped rather than read into memory (mirrors config-file.ts). */
+const MAX_BINDINGS_BYTES = 1024 * 1024;
+/** Production `BindingsIo` backed by the real filesystem, home dir, and environment. */
+export function nodeBindingsIo() {
+    return {
+        readFile: (path) => {
+            try {
+                const stats = statSync(path);
+                if (!stats.isFile() || stats.size > MAX_BINDINGS_BYTES) {
+                    return undefined;
+                }
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return undefined; // missing / unreadable → "no bindings file here"
+            }
+        },
+        writeFile: (path, content) => {
+            mkdirSync(dirname(path), { recursive: true });
+            // Atomic write: stage to a sibling temp file, then rename(2) over the target. rename is atomic on
+            // the same filesystem, so a crash (or a concurrent reader) never observes a half-written or
+            // truncated bindings.json — the blast radius of a torn write would be the ENTIRE binding set. The
+            // temp lives in the same dir so the rename stays intra-filesystem.
+            const tmp = `${path}.${process.pid}.tmp`;
+            writeFileSync(tmp, content, "utf8");
+            renameSync(tmp, path);
+        },
+        homedir: safeOsValue(homedir),
+        xdgConfigHome: process.env.XDG_CONFIG_HOME,
+        cwd: safeOsValue(() => process.cwd()),
+    };
+}
+//# sourceMappingURL=bindings.js.map

package/dist/bindings.js.map

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