harnery 0.0.1 → 0.2.0

package/src/lib/format.ts

@@ -0,0 +1,147 @@
+/** ANSI color helpers, minimal, no dependencies */
+const isColor = process.stdout.isTTY !== false;
+
+const code = (n: number) => (isColor ? `\x1b[${n}m` : "");
+const reset = code(0);
+
+export const c = {
+  bold: (s: string) => `${code(1)}${s}${reset}`,
+  dim: (s: string) => `${code(2)}${s}${reset}`,
+  green: (s: string) => `${code(32)}${s}${reset}`,
+  red: (s: string) => `${code(31)}${s}${reset}`,
+  yellow: (s: string) => `${code(33)}${s}${reset}`,
+  cyan: (s: string) => `${code(36)}${s}${reset}`,
+  gray: (s: string) => `${code(90)}${s}${reset}`,
+  magenta: (s: string) => `${code(35)}${s}${reset}`,
+};
+
+/** Placeholder shown when a value is missing (null/empty), e.g. an unknown branch or age. */
+export const NO_DATA = "—";
+
+/**
+ * Pretty-print + ANSI-colorize a JSON value. 2-space indent. TTY-aware: when
+ * stdout is not a TTY, the underlying `c.*` helpers emit no ANSI codes, so
+ * output is plain text. Use this for `--pretty` flags on JSON-emitting commands.
+ *
+ * Colors: keys=cyan, strings=green, numbers=magenta, booleans=yellow, null=dim.
+ */
+export function colorJson(value: unknown, indent = 0): string {
+  const seen = new WeakSet<object>();
+  const step = "  ";
+
+  function fmt(v: unknown, depth: number): string {
+    if (v === null) return c.dim("null");
+    if (typeof v === "boolean") return c.yellow(String(v));
+    if (typeof v === "number") return c.magenta(String(v));
+    if (typeof v === "string") return c.green(JSON.stringify(v));
+    if (typeof v === "bigint") return c.magenta(`${v}n`);
+    if (Array.isArray(v)) {
+      if (v.length === 0) return "[]";
+      if (seen.has(v)) return c.dim('"[Circular]"');
+      seen.add(v);
+      const pad = step.repeat(depth + 1);
+      const close = step.repeat(depth);
+      const items = v.map((x) => pad + fmt(x, depth + 1)).join(",\n");
+      return `[\n${items}\n${close}]`;
+    }
+    if (typeof v === "object") {
+      // Class instances that define toJSON() (Big.js, Decimal.js, Date, etc.)
+      // would render as their raw internal shape if we walked Object.keys
+      // directly. Unwrap once so callers see the intended representation
+      // (Big.js → "1.97" instead of {s,e,c} from BigQuery NUMERIC fields).
+      const maybeJsonable = v as { toJSON?: () => unknown };
+      if (typeof maybeJsonable.toJSON === "function") {
+        return fmt(maybeJsonable.toJSON(), depth);
+      }
+      const obj = v as Record<string, unknown>;
+      const keys = Object.keys(obj);
+      if (keys.length === 0) return "{}";
+      if (seen.has(obj)) return c.dim('"[Circular]"');
+      seen.add(obj);
+      const pad = step.repeat(depth + 1);
+      const close = step.repeat(depth);
+      const items = keys
+        .map((k) => `${pad}${c.cyan(JSON.stringify(k))}: ${fmt(obj[k], depth + 1)}`)
+        .join(",\n");
+      return `{\n${items}\n${close}}`;
+    }
+    return JSON.stringify(v) ?? "null";
+  }
+
+  return fmt(value, indent);
+}
+
+/** Render a table from rows of objects */
+export function table(
+  rows: Record<string, unknown>[],
+  opts: { maxColWidth?: number } = {},
+): string {
+  if (rows.length === 0) return c.dim("(no rows)");
+
+  const maxCol = opts.maxColWidth ?? 60;
+  const keys = Object.keys(rows[0]!);
+
+  // Compute column widths
+  const widths = new Map<string, number>();
+  for (const key of keys) {
+    let max = key.length;
+    for (const row of rows) {
+      const val = stringify(row[key]);
+      max = Math.max(max, Math.min(val.length, maxCol));
+    }
+    widths.set(key, max);
+  }
+
+  // Header
+  const header = keys.map((k) => c.bold(k.padEnd(widths.get(k)!))).join("  ");
+  const separator = keys.map((k) => "─".repeat(widths.get(k)!)).join("──");
+
+  // Rows
+  const lines = rows.map((row) =>
+    keys
+      .map((k) => {
+        const val = stringify(row[k]);
+        const display = val.length > maxCol ? `${val.slice(0, maxCol - 1)}…` : val;
+        return display.padEnd(widths.get(k)!);
+      })
+      .join("  "),
+  );
+
+  return [header, separator, ...lines].join("\n");
+}
+
+/** Convert a value to a display string */
+function stringify(val: unknown): string {
+  if (val === null || val === undefined) return "NULL";
+  if (typeof val === "object") {
+    if (val instanceof Date) return val.toISOString();
+    // BigQuery returns { value: "..." } for some types
+    if ("value" in val && Object.keys(val).length === 1) {
+      return String((val as { value: unknown }).value);
+    }
+    return JSON.stringify(val);
+  }
+  return String(val);
+}
+
+/** Format rows as CSV */
+export function csv(rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) return "";
+  const keys = Object.keys(rows[0]!);
+  const header = keys.map(csvEscape).join(",");
+  const lines = rows.map((row) => keys.map((k) => csvEscape(stringify(row[k]))).join(","));
+  return [header, ...lines].join("\n");
+}
+
+function csvEscape(val: string): string {
+  if (val.includes(",") || val.includes('"') || val.includes("\n")) {
+    return `"${val.replace(/"/g, '""')}"`;
+  }
+  return val;
+}
+
+/** Print a labeled key-value section */
+export function kvLine(label: string, value: string, color?: (s: string) => string): string {
+  const colorFn = color ?? ((s: string) => s);
+  return `  ${c.dim(label.padEnd(14))} ${colorFn(value)}`;
+}

package/src/lib/http/client.ts

@@ -0,0 +1,211 @@
+import type { Cookie, CookieJar } from "../cookies/index.ts";
+
+/**
+ * Simple cookie-aware HTTP client.
+ *
+ * Wraps the global `fetch` (Bun's native one) with two extras:
+ *   - Attaches a `Cookie:` header from a CookieJar before the request.
+ *   - Persists `Set-Cookie` responses back into the same jar.
+ *
+ * Used by the `fetch` command and other tooling that wants to share session
+ * state with `browse`.
+ */
+
+export interface FetchOptions {
+  /** HTTP method. Default GET. */
+  method?: string;
+  /** Request body. Strings/Buffers/Streams pass through to fetch directly. */
+  body?: BodyInit | null;
+  /** Extra headers (merged with auto-added Cookie). */
+  headers?: Record<string, string>;
+  /**
+   * Optional CookieJar. When provided:
+   *   - Matching cookies become a Cookie header.
+   *   - Set-Cookie response headers are parsed and merged into the jar.
+   * Pass `null` (or omit) to disable.
+   */
+  jar?: CookieJar | null;
+  /** Optional override for redirect handling. Default `'follow'`. */
+  redirect?: RequestRedirect;
+  /** AbortSignal for timeout/cancel control. */
+  signal?: AbortSignal;
+  /**
+   * Optional callback that returns extra headers to attach based on the
+   * target URL. Consumers can inject extra HTTP headers per-URL via this
+   * callback (e.g., a Cloudflare-bypass header for specific zones).
+   * Caller-provided explicit headers always win; auto-attached values
+   * only land when the key isn't already set.
+   */
+  extraHeaders?: (url: string) => Record<string, string>;
+}
+
+export interface FetchResult {
+  status: number;
+  statusText: string;
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  /** Number of cookies persisted back into the jar (0 if no jar passed). */
+  cookiesSaved: number;
+}
+
+/**
+ * Fetch a URL with optional cookie-jar attach + persist.
+ *
+ * Returns the response body as a string (callers handle JSON parsing).
+ * Streams aren't supported; this is a CLI helper, not a streaming HTTP
+ * client. Use Bun's `fetch` directly for streaming workloads.
+ */
+export async function fetchWithJar(url: string, opts: FetchOptions = {}): Promise<FetchResult> {
+  const headers: Record<string, string> = { ...(opts.headers ?? {}) };
+
+  if (opts.jar) {
+    const cookieHeader = opts.jar.header(url);
+    if (cookieHeader && !headers.Cookie && !headers.cookie) {
+      headers.Cookie = cookieHeader;
+    }
+  }
+
+  // Caller-provided extraHeaders callback (e.g., for Cloudflare-bypass or
+  // custom auth headers). Caller-supplied explicit headers always win.
+  if (opts.extraHeaders) {
+    for (const [k, v] of Object.entries(opts.extraHeaders(url))) {
+      if (!(k in headers) && !(k.toLowerCase() in headers)) headers[k] = v;
+    }
+  }
+
+  const response = await fetch(url, {
+    method: opts.method ?? "GET",
+    body: opts.body,
+    headers,
+    redirect: opts.redirect ?? "follow",
+    signal: opts.signal,
+  });
+
+  let cookiesSaved = 0;
+  if (opts.jar) {
+    const setCookieHeaders = collectSetCookie(response.headers);
+    if (setCookieHeaders.length > 0) {
+      const parsedHost = new URL(response.url).hostname;
+      const cookies: Cookie[] = setCookieHeaders
+        .map((sc) => parseSetCookie(sc, parsedHost))
+        .filter((c): c is Cookie => c !== null);
+      for (const cookie of cookies) {
+        opts.jar.set(cookie);
+      }
+      cookiesSaved = cookies.length;
+    }
+  }
+
+  const headerObj: Record<string, string> = {};
+  response.headers.forEach((value, key) => {
+    headerObj[key] = value;
+  });
+
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    url: response.url,
+    headers: headerObj,
+    body: await response.text(),
+    cookiesSaved,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Set-Cookie parsing
+// ---------------------------------------------------------------------------
+//
+// `fetch` joins multiple Set-Cookie headers with `, ` per the spec, but that
+// collides with the comma-separated date format in `Expires=`. We use the
+// dual-mode approach: prefer the `getSetCookie()` method when available
+// (Node 20+, Bun 1.0+) and fall back to manual splitting otherwise.
+
+function collectSetCookie(headers: Headers): string[] {
+  const h = headers as Headers & { getSetCookie?: () => string[] };
+  if (typeof h.getSetCookie === "function") {
+    return h.getSetCookie();
+  }
+  const raw = headers.get("set-cookie");
+  return raw ? splitSetCookieHeader(raw) : [];
+}
+
+function splitSetCookieHeader(raw: string): string[] {
+  // Splits on ", " that precedes a new cookie (heuristic: a token followed
+  // by `=`), avoiding date-internal commas like `Expires=Wed, 21 Oct …`.
+  const parts: string[] = [];
+  let depth = 0;
+  let buf = "";
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === "," && depth === 0) {
+      const ahead = raw.slice(i + 1).trimStart();
+      if (/^[A-Za-z0-9_!#$%&'*+\-.^`|~]+=/.test(ahead)) {
+        parts.push(buf.trim());
+        buf = "";
+        continue;
+      }
+    }
+    if (ch === "=") depth++;
+    if (ch === ";") depth = 0;
+    buf += ch;
+  }
+  if (buf.trim()) parts.push(buf.trim());
+  return parts;
+}
+
+function parseSetCookie(raw: string, defaultDomain: string): Cookie | null {
+  const parts = raw.split(";").map((p) => p.trim());
+  if (parts.length === 0) return null;
+
+  const first = parts[0];
+  if (!first) return null;
+  const eq = first.indexOf("=");
+  if (eq < 0) return null;
+  const name = first.slice(0, eq).trim();
+  const value = first.slice(eq + 1).trim();
+  if (!name) return null;
+
+  const cookie: Cookie = {
+    name,
+    value,
+    domain: defaultDomain,
+    path: "/",
+    expires: -1,
+    httpOnly: false,
+    secure: false,
+    session: true,
+    size: name.length + value.length,
+  };
+
+  for (const attr of parts.slice(1)) {
+    const lower = attr.toLowerCase();
+    if (lower.startsWith("domain=")) {
+      const d = attr.slice(7).trim();
+      cookie.domain = d.startsWith(".") ? d : `.${d}`;
+    } else if (lower.startsWith("path=")) {
+      cookie.path = attr.slice(5).trim() || "/";
+    } else if (lower.startsWith("expires=")) {
+      const ts = Date.parse(attr.slice(8).trim());
+      if (!Number.isNaN(ts)) {
+        cookie.expires = Math.floor(ts / 1000);
+        cookie.session = false;
+      }
+    } else if (lower.startsWith("max-age=")) {
+      const seconds = Number.parseInt(attr.slice(8).trim(), 10);
+      if (!Number.isNaN(seconds)) {
+        cookie.expires = Math.floor(Date.now() / 1000) + seconds;
+        cookie.session = false;
+      }
+    } else if (lower === "secure") {
+      cookie.secure = true;
+    } else if (lower === "httponly") {
+      cookie.httpOnly = true;
+    } else if (lower.startsWith("samesite=")) {
+      const v = attr.slice(9).trim();
+      cookie.sameSite = v.charAt(0).toUpperCase() + v.slice(1).toLowerCase();
+    }
+  }
+
+  return cookie;
+}

package/src/lib/http/index.ts

@@ -0,0 +1 @@
+export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";

package/src/lib/identities/index.ts

@@ -0,0 +1,210 @@
+/**
+ * Agent persona identity registry: per-agent durable UUIDs.
+ *
+ * The coord layer has two id concepts that get confused:
+ *   - `instance_id`: Claude Code session UUID (fresh per session). Lives at
+ *     `.harnery/active/<instance_id>.json` as the heartbeat filename.
+ *   - `agent_id` (this module): durable per-AGENT-PERSONA UUID. Stable
+ *     across sessions; same UUID for every Maya session, regardless of
+ *     how many times she restarts Claude Code.
+ *
+ * Storage: `.harnery/identities/<agent_id>.json`, one file per persona.
+ * The filename IS the id so reverse lookup is O(1) by id; forward lookup
+ * by name is a scan (small directory, ~100 personas tops in practice).
+ *
+ * Used as the canonical identifier in:
+ *   - Council manifests (`created_by_id`, `steward_id`, `member_ids[]`)
+ *   - Council body filenames (`<agent_id>.md` not `<name>.md`)
+ *   - Session events ndjson (new `agent_id` field alongside `agent_name`)
+ *   - Heartbeats (new `agent_id` field; existing CC subagent-call id
+ *     renamed to `subagent_call_id`)
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+
+import { monorepoRoot } from "../../core/agents/index.ts";
+
+export const IDENTITY_SCHEMA_VERSION = 1 as const;
+
+export interface AgentIdentity {
+  schema_version: 1;
+  /** Persistent persona UUID. v4. */
+  agent_id: string;
+  /** Current display name (e.g. "Maya", without the "agent-" prefix). */
+  name: string;
+  /** Prior names this identity has been known by. Updated by renameIdentity(). */
+  aliases: Array<{ name: string; retired_at: string }>;
+  /** UTC ISO-8601 timestamp of first mint. */
+  created_at: string;
+}
+
+function identitiesDir(): string | null {
+  const root = monorepoRoot();
+  if (!root) return null;
+  return resolve(root, ".harnery", "identities");
+}
+
+function ensureDir(): string {
+  const dir = identitiesDir();
+  if (!dir) throw new Error("not in an agent session; no monorepo root");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function identityPath(agentId: string): string {
+  return resolve(ensureDir(), `${agentId}.json`);
+}
+
+function nowIso(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function readIdentityFile(path: string): AgentIdentity | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as AgentIdentity;
+    if (parsed.schema_version !== IDENTITY_SCHEMA_VERSION) {
+      throw new Error(
+        `identity ${path}: unsupported schema_version=${parsed.schema_version} (expected ${IDENTITY_SCHEMA_VERSION})`,
+      );
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Strip an "agent-" prefix if present. The registry stores bare names. */
+export function bareName(raw: string): string {
+  const trimmed = raw.trim();
+  return trimmed.startsWith("agent-") ? trimmed.slice("agent-".length) : trimmed;
+}
+
+/** Re-add the "agent-" prefix for display contexts. */
+export function displayName(name: string): string {
+  return name.startsWith("agent-") ? name : `agent-${name}`;
+}
+
+/** Read one identity by id. Null if missing. */
+export function lookupById(agentId: string): AgentIdentity | null {
+  const dir = identitiesDir();
+  if (!dir) return null;
+  const fp = resolve(dir, `${agentId}.json`);
+  if (!existsSync(fp)) return null;
+  return readIdentityFile(fp);
+}
+
+/** Read one identity by display name (case-insensitive on bare name).
+ * Scans the directory; O(N) on identity count. */
+export function lookupByName(name: string): AgentIdentity | null {
+  const dir = identitiesDir();
+  if (!dir || !existsSync(dir)) return null;
+  const wanted = bareName(name).toLowerCase();
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    const id = readIdentityFile(resolve(dir, f));
+    if (!id) continue;
+    if (id.name.toLowerCase() === wanted) return id;
+    for (const alias of id.aliases) {
+      if (alias.name.toLowerCase() === wanted) return id;
+    }
+  }
+  return null;
+}
+
+/** All known identities, sorted by created_at ascending. */
+export function listIdentities(): AgentIdentity[] {
+  const dir = identitiesDir();
+  if (!dir || !existsSync(dir)) return [];
+  const out: AgentIdentity[] = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    const id = readIdentityFile(resolve(dir, f));
+    if (id) out.push(id);
+  }
+  out.sort((a, b) => a.created_at.localeCompare(b.created_at));
+  return out;
+}
+
+/**
+ * Find an identity by name, or mint one. Returns the resolved identity.
+ * Idempotent: calling twice with the same name returns the same record.
+ *
+ * Mint path: generates a fresh uuid v4, writes the file atomically (tmp +
+ * rename), returns the new identity. Race-safe: if two processes mint
+ * simultaneously, both files land (different ids), but lookupByName will
+ * surface whichever happened to be read first; the second is orphaned.
+ * For agent personas (added at human cadence) this race is theoretical.
+ */
+export function ensureIdentity(name: string): AgentIdentity {
+  const existing = lookupByName(name);
+  if (existing) return existing;
+  const id: AgentIdentity = {
+    schema_version: IDENTITY_SCHEMA_VERSION,
+    agent_id: randomUUID(),
+    name: bareName(name),
+    aliases: [],
+    created_at: nowIso(),
+  };
+  writeIdentity(id);
+  return id;
+}
+
+/** Persist an identity (tmp + rename). Creates the dir if missing. */
+export function writeIdentity(id: AgentIdentity): void {
+  ensureDir();
+  const fp = identityPath(id.agent_id);
+  const tmp = `${fp}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(id, null, 2)}\n`, "utf8");
+  renameSync(tmp, fp);
+}
+
+/**
+ * Rename an existing identity. The prior name lands in aliases[] so name
+ * lookup still resolves correctly. The agent_id is stable across renames,
+ * which is the whole point of the registry.
+ */
+export function renameIdentity(agentId: string, newName: string): AgentIdentity {
+  const existing = lookupById(agentId);
+  if (!existing) {
+    throw new Error(`renameIdentity: no identity matching '${agentId}'`);
+  }
+  const bare = bareName(newName);
+  if (existing.name === bare) return existing;
+  const next: AgentIdentity = {
+    ...existing,
+    name: bare,
+    aliases: [...existing.aliases, { name: existing.name, retired_at: nowIso() }],
+  };
+  writeIdentity(next);
+  return next;
+}
+
+/**
+ * Resolve a string to an agent_id. Accepts:
+ *   - A UUID (already an id), verified to exist in registry
+ *   - A display name (e.g. "agent-Maya" or "Maya"), resolved via lookupByName
+ * Returns null when the input is neither a known id nor a known name.
+ *
+ * Does NOT mint. Callers that want mint-on-miss should call ensureIdentity()
+ * with a name, then use the returned agent_id.
+ */
+export function resolveAgentId(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  // UUID shape check, relaxed; we only need the lookupById to confirm.
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(trimmed)) {
+    const byId = lookupById(trimmed);
+    if (byId) return byId.agent_id;
+  }
+  const byName = lookupByName(trimmed);
+  return byName ? byName.agent_id : null;
+}

package/src/lib/machine.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+import { coordEnv } from "./env.ts";
+
+/**
+ * Resolve a human-friendly label for the current machine. Used to tag
+ * coordination artifacts (scratch-doc headers, session telemetry) by the host
+ * they originated on.
+ *
+ * Precedence (first non-empty wins):
+ *   1. HARNERY_MACHINE env var:          transient / per-launch / CI override
+ *   2. ~/.config/harnery/machine file:   persistent, harness-neutral identity
+ *   3. os.hostname() (normalized):       automatic floor; never empty
+ *
+ * The env var sits on top for ad-hoc overrides; the file is the durable home for
+ * a machine's name (it survives across Claude Code / Cursor / Codex and GUI
+ * launches that don't inherit a shell rc); hostname guarantees a real answer
+ * with zero configuration.
+ */
+export function resolveMachineLabel(): string {
+  const fromEnv = coordEnv("MACHINE")?.trim();
+  if (fromEnv) return fromEnv;
+
+  const fromFile = readMachineFile();
+  if (fromFile) return fromFile;
+
+  return normalizeHost(hostname());
+}
+
+/** Absolute path of the machine-label file, honoring XDG_CONFIG_HOME. */
+export function machineFilePath(): string | null {
+  const home = process.env.HOME ?? process.env.USERPROFILE;
+  if (!home) return null;
+  const configHome = process.env.XDG_CONFIG_HOME?.trim() || resolve(home, ".config");
+  return resolve(configHome, "harnery", "machine");
+}
+
+/** First non-empty, non-comment line of the machine-label file, or null. */
+function readMachineFile(): string | null {
+  const path = machineFilePath();
+  if (!path || !existsSync(path)) return null;
+  try {
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#")) return trimmed;
+    }
+  } catch {
+    /* unreadable; fall through to hostname */
+  }
+  return null;
+}
+
+/** Lowercase, strip a trailing `.local` (macOS mDNS suffix). Never empty. */
+function normalizeHost(raw: string): string {
+  const cleaned = raw
+    .trim()
+    .replace(/\.local$/i, "")
+    .toLowerCase();
+  return cleaned || "unknown";
+}