@opsee/cli 0.11.13 → 0.11.18

package/src/foreman/credential-store.ts

@@ -0,0 +1,247 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { VENDOR_CREDENTIAL_FILE, type Vendor } from "./vendor.js";
+
+/**
+ * Where a vendor keeps the credential for one config directory, per platform.
+ *
+ * This exists because of a wrong assumption that reached a release: that a subscription's
+ * credential is a file inside its config directory. **On macOS Claude Code writes no such file.**
+ * It derives a Keychain item per `CLAUDE_CONFIG_DIR` and stores the credential there, so a file
+ * check finds nothing however well the login went — which is exactly what refused three Accounts
+ * that had been logged into correctly.
+ *
+ * Two callers, wanting different things, and the difference is deliberate:
+ *
+ * - `account add --login` wants to know whether a login *happened* (`credentialPresence`). It never
+ *   needs the secret, and never asks for one.
+ * - The usage poller wants the token itself (`readCredentialText`), which ADR-0013's amendment
+ *   permits for the single purpose of asking that vendor about the user's own quota.
+ *
+ * Nothing else in the package may call `readCredentialText`.
+ */
+
+/** The service name Claude Code uses for the default profile — no `CLAUDE_CONFIG_DIR` set. */
+export const CLAUDE_DEFAULT_KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+/** The directory Claude Code uses when `CLAUDE_CONFIG_DIR` is not set. */
+export const CLAUDE_DEFAULT_CONFIG_DIR = ".claude";
+
+/**
+ * Apple's own binary, by absolute path.
+ *
+ * Never resolved through `PATH`: this reads a credential, so a `security` planted earlier on the
+ * path would be handed one. `/usr/bin/security` is present on every macOS.
+ */
+const SECURITY = "/usr/bin/security";
+
+/** A wedged Keychain — a locked login keychain on a headless or SSH host, prompting for an unlock
+ * nobody will give — must not hang a command. A healthy one answers in well under 100ms. */
+const SECURITY_TIMEOUT_MS = 5_000;
+
+/** `errSecItemNotFound`, as `security` surfaces it: the one non-zero status that means "no such
+ * item" rather than "I could not tell you". */
+const NOT_FOUND_STATUS = 44;
+
+/** What a credential lookup found. `unknown` is the important one: it means the question could not
+ * be answered, and **no caller may refuse anything on it**. */
+export type CredentialPresence = "present" | "absent" | "unknown";
+
+/** What `security` reported: its exit status, whatever it printed, and whether it ran at all. */
+export interface SecurityResult {
+  /** Null when the command could not be run or did not finish. */
+  status: number | null;
+  stdout: string;
+  /** Set when the command was killed at `SECURITY_TIMEOUT_MS`, which a caller reports differently
+   * from a binary that is missing: one is a Keychain nobody can reach, the other is not macOS. */
+  timedOut?: boolean;
+}
+
+export interface CredentialDeps {
+  platform: NodeJS.Platform;
+  env: Readonly<Record<string, string | undefined>>;
+  /** The user's home, for recognising the default profile. Injected so the rule is testable. */
+  home: string;
+  /** The OS account name, used when the environment carries none (`osUsername`). */
+  osUsername: () => string;
+  fileExists: (path: string) => boolean;
+  readFile: (path: string) => string;
+  security: (args: readonly string[]) => Promise<SecurityResult>;
+}
+
+/**
+ * The real seams. Deliberately **not** a default parameter: `ConfigDirFs` and `HostProbeDeps` are
+ * both required arguments in this package, and a default is how a call site silently keeps the
+ * production implementation in a test — which is how the file-only assumption survived review.
+ */
+export const realCredentialDeps: CredentialDeps = {
+  platform: process.platform,
+  env: process.env,
+  home: homedir(),
+  osUsername: () => userInfo().username,
+  fileExists: (path) => existsSync(path),
+  readFile: (path) => readFileSync(path, "utf-8"),
+  security: (args) =>
+    new Promise((resolve) => {
+      // `execFile`, not `spawnSync`: this runs inside the daemon, which is streaming live Workers.
+      // A wedged Keychain would otherwise block the event loop for the whole timeout, per Account
+      // — trading the thing that matters for the thing that helps, which the poll tick's own
+      // comment warns against.
+      execFile(SECURITY, [...args], { timeout: SECURITY_TIMEOUT_MS, encoding: "utf-8" }, (error, stdout) => {
+        const killed = (error as { killed?: boolean } | null)?.killed === true;
+        const status = (error as { code?: number } | null)?.code;
+        resolve({
+          status: error ? (typeof status === "number" ? status : null) : 0,
+          stdout: stdout ?? "",
+          ...(killed ? { timedOut: true } : {}),
+        });
+      });
+    }),
+};
+
+/**
+ * The Keychain service name Claude Code derives for a config directory.
+ *
+ * The vendor's own scheme: the first 8 hex characters of the SHA-256 of the **exact string exported
+ * as `CLAUDE_CONFIG_DIR`**, NFC-normalised, after a fixed prefix. Hash what is exported and nothing
+ * else — `/a/b` and `/a/b/` are different strings and so are different items, and resolving or
+ * tidying the path here would look up an item the vendor never wrote.
+ *
+ * The Foreman always exports the absolute path it stored at registration (`validateConfigDir`
+ * resolves it once, through the same `expandHome` the login path uses), so the string hashed here
+ * is the string the login used.
+ */
+export function keychainServiceName(configDir: string): string {
+  const digest = createHash("sha256").update(configDir.normalize("NFC"), "utf8").digest("hex").slice(0, 8);
+  return `${CLAUDE_DEFAULT_KEYCHAIN_SERVICE}-${digest}`;
+}
+
+/**
+ * The Keychain account name, mirroring the vendor's `getUsername()`: `$USER`, then the OS account
+ * name, then a fixed string.
+ *
+ * The middle step is the one that matters, and it is not `$LOGNAME`. Under launchd — which is how
+ * `foreman service install` runs the daemon — neither `USER` nor `LOGNAME` is set, so an
+ * environment-only lookup would fall through to the fixed string, key a different item than the one
+ * the login wrote, and fail every poll on the machine. That is the original bug wearing a different
+ * hat, so the OS is asked rather than the environment.
+ */
+export function keychainAccountName(deps: Pick<CredentialDeps, "env" | "osUsername">): string {
+  if (deps.env.USER) return deps.env.USER;
+  try {
+    const name = deps.osUsername();
+    if (name) return name;
+  } catch {
+    /* a container with no passwd entry; the fixed name below is the vendor's own last resort */
+  }
+  return "claude-code-user";
+}
+
+/**
+ * Whether a credential exists for this config directory.
+ *
+ * Three answers, and the third is the point: `unknown` means the question could not be answered —
+ * a locked Keychain, a denied prompt, a `security` that would not run. **A caller must not refuse
+ * anything on `unknown`.** Treating "I could not tell" as "there is nothing there" is precisely the
+ * bug this module was written to fix.
+ *
+ * Presence never asks for the value: on macOS the lookup omits `-w`, and off it the file is only
+ * stat-ed. Answering "is there one" by reading one would be a credential read with no permission
+ * behind it.
+ */
+export async function credentialPresence(vendor: Vendor, configDir: string, deps: CredentialDeps): Promise<CredentialPresence> {
+  if (!usesKeychain(vendor, deps.platform)) {
+    return deps.fileExists(credentialPath(vendor, configDir)) ? "present" : "absent";
+  }
+  for (const service of keychainServices(configDir, deps)) {
+    const found = await lookUp(deps, service, { wantValue: false });
+    if (found.kind === "found") return "present";
+    if (found.kind === "unusable") return "unknown";
+  }
+  return "absent";
+}
+
+/**
+ * The credential as the vendor stored it, or a one-line reason.
+ *
+ * **The only credential read in this package**, and permitted by ADR-0013's amendment for one
+ * purpose: asking that same vendor about the user's own quota. Every failure reason is built here
+ * and quotes nothing that was read — a poller failure is written to the usage store, printed by
+ * `account usage` and logged, so a reason carrying the file or the item would leak into all three.
+ */
+export async function readCredentialText(
+  vendor: Vendor,
+  configDir: string,
+  deps: CredentialDeps,
+): Promise<{ ok: true; text: string } | { ok: false; reason: string }> {
+  if (!usesKeychain(vendor, deps.platform)) {
+    try {
+      return { ok: true, text: deps.readFile(credentialPath(vendor, configDir)) };
+    } catch {
+      return { ok: false, reason: `no readable ${VENDOR_CREDENTIAL_FILE[vendor]} in ${configDir}` };
+    }
+  }
+  for (const service of keychainServices(configDir, deps)) {
+    const found = await lookUp(deps, service, { wantValue: true });
+    if (found.kind === "found") return { ok: true, text: found.value };
+    if (found.kind === "unusable") return { ok: false, reason: found.reason };
+  }
+  return { ok: false, reason: "no Keychain item holds a credential for this config directory; the vendor has not been logged in there" };
+}
+
+type LookUp = { kind: "found"; value: string } | { kind: "missing" } | { kind: "unusable"; reason: string };
+
+/**
+ * One Keychain lookup. The only difference between asking whether an item exists and asking what is
+ * in it is `-w`, so both callers come through here rather than each keeping its own copy of the
+ * argument list and the three-way reading of the exit status.
+ */
+async function lookUp(deps: CredentialDeps, service: string, options: { wantValue: boolean }): Promise<LookUp> {
+  const args = ["find-generic-password", "-a", keychainAccountName(deps), ...(options.wantValue ? ["-w"] : []), "-s", service];
+  const found = await deps.security(args);
+  // `-w` prints the value and one newline; strip exactly that.
+  if (found.status === 0) return { kind: "found", value: found.stdout.replace(/\n$/, "") };
+  if (found.status === NOT_FOUND_STATUS) return { kind: "missing" };
+  return {
+    kind: "unusable",
+    reason: found.timedOut
+      ? `the macOS Keychain did not answer within ${SECURITY_TIMEOUT_MS}ms for this Account`
+      : `the macOS Keychain could not be read for this Account (security exited ${found.status ?? "without running"})`,
+  };
+}
+
+/**
+ * Claude Code keeps credentials in the Keychain on macOS and in a file everywhere else. Codex is
+ * file-based on every platform (`auth.json`, vendor.ts), so it never comes here.
+ */
+function usesKeychain(vendor: Vendor, platform: NodeJS.Platform): boolean {
+  return vendor === "claude" && platform === "darwin";
+}
+
+/**
+ * The Keychain items to try, in order.
+ *
+ * Normally exactly one: the item derived from this config directory. The default profile's
+ * unhashed item is tried **only when the directory is the default one**, which is the single case
+ * where both names can legitimately describe the same login: exporting `CLAUDE_CONFIG_DIR` makes
+ * the vendor write a hashed item, but somebody who has only ever used the default profile may have
+ * just the unhashed one.
+ *
+ * Trying it for every directory — which this did at first — is a hole, not a courtesy: a directory
+ * with no item of its own would have found the *default profile's* credential, so `--login` would
+ * register an Account nobody signed into, and the poller would file one identity's quota under
+ * another Account. Two Accounts would report one quota and the scheduler would believe twice the
+ * capacity that exists.
+ */
+function keychainServices(configDir: string, deps: CredentialDeps): string[] {
+  const services = [keychainServiceName(configDir)];
+  if (configDir === join(deps.home, CLAUDE_DEFAULT_CONFIG_DIR)) services.push(CLAUDE_DEFAULT_KEYCHAIN_SERVICE);
+  return services;
+}
+
+function credentialPath(vendor: Vendor, configDir: string): string {
+  return join(configDir, VENDOR_CREDENTIAL_FILE[vendor]);
+}

package/src/foreman/usage-activity.ts

@@ -0,0 +1,102 @@
+import { count } from "./core/text.js";
+import type { AccountUsage, ActivityTurn } from "./usage.js";
+import type { UsageStore } from "./usage-store.js";
+
+/**
+ * What this Foreman has itself spent on an Account (the multi-account headroom design, §6).
+ *
+ * What the Foreman itself has spent on an Account, from the `costUsd` and turn count that already
+ * ride the completed event and were, until now, explicitly unconsumed.
+ *
+ * **It deliberately reports no percentage.** The design sketched this as a third estimator
+ * producing estimated window percentages for Accounts the poller cannot measure, and that
+ * part is not built, because it cannot be built honestly: converting "eleven turns and $4.20" into
+ * "38% of a five-hour window" needs the plan's limit, which nothing on this machine knows and which
+ * differs by subscription tier. A number like that would be invented, and — worse — it would sit in
+ * the same column as measurements that are real.
+ *
+ * What it is good for is the question a percentage cannot answer anyway: *how hard has the Foreman
+ * been leaning on this Account?* That is a fact, it is this machine's to know, and it is what a
+ * human looks for when an Account keeps hitting its limit. It is reported beside the windows in
+ * `foreman account usage`, never used to hold an Account back or to rank a Lane.
+ *
+ * Called activity on purpose: `cli/CONTEXT.md` puts "Ledger" on the avoid list
+ * for both the Run Record and the Process Table, and a third thing wearing the word would undo
+ * exactly the vocabulary that file exists to keep straight.
+ */
+
+/** The windows this reports on, matching the vendor's own two. */
+const FIVE_HOURS = 5 * 60 * 60_000;
+const SEVEN_DAYS = 7 * 24 * 60 * 60_000;
+
+/** The longest window reported on: a turn older than this answers no question asked here. */
+const ACTIVITY_HORIZON_MS = SEVEN_DAYS;
+
+/** The most turns kept for one Account. A busy fleet would otherwise grow the record without bound,
+ * and the oldest turns are the ones that have already aged out of every window that matters. */
+export const ACTIVITY_TURN_CAP = 2_000;
+
+/** Turns inside `windowMs`, and what they cost. A turn whose cost the vendor did not report still
+ * counts as a turn: the turn happened, and that is the part this is sure of. */
+export function activityIn(usage: AccountUsage | undefined, windowMs: number, now: number): { turns: number; costUsd: number } {
+  let turns = 0;
+  let costUsd = 0;
+  for (const turn of usage?.activity?.turns ?? []) {
+    const at = Date.parse(turn.at);
+    if (!Number.isFinite(at) || at < now - windowMs || at > now) continue;
+    turns++;
+    if (typeof turn.costUsd === "number" && Number.isFinite(turn.costUsd)) costUsd += turn.costUsd;
+  }
+  return { turns, costUsd };
+}
+
+/** What the Foreman has spent on this Account, in one line, or undefined when it has run none. */
+export function summariseActivity(usage: AccountUsage | undefined, now: number): string | undefined {
+  const recent = activityIn(usage, FIVE_HOURS, now);
+  const week = activityIn(usage, SEVEN_DAYS, now);
+  if (week.turns === 0) return undefined;
+  const spent = week.costUsd > 0 ? `, $${week.costUsd.toFixed(2)} this week` : "";
+  return `this Foreman ran ${count(recent.turns, "turn")} in the last 5h and ${count(week.turns, "turn")} in 7d${spent}`;
+}
+
+/**
+ * Records one completed turn against an Account.
+ *
+ * Goes through the store's merge like everything else, so a turn recorded by one Run and a window
+ * measured by the poller at the same moment cannot lose each other (`mergeActivity`).
+ */
+export function recordTurn(store: UsageStore, account: string, at: number, costUsd: number | undefined): void {
+  store.observe(account, {}, at, {
+    turns: [costUsd === undefined ? { at: new Date(at).toISOString() } : { at: new Date(at).toISOString(), costUsd }],
+  });
+}
+
+/** Turns still worth keeping: inside the horizon, newest-last, and no more than the cap. */
+export function pruneTurns(turns: readonly ActivityTurn[], now: number): ActivityTurn[] {
+  const kept = turns
+    .filter((turn) => {
+      const at = Date.parse(turn.at);
+      return Number.isFinite(at) && at >= now - ACTIVITY_HORIZON_MS;
+    })
+    .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+  return kept.length > ACTIVITY_TURN_CAP ? kept.slice(kept.length - ACTIVITY_TURN_CAP) : kept;
+}
+
+/**
+ * Both writers' turns, in order, with duplicates dropped.
+ *
+ * The usage store has two writers — a Run recording a turn, the daemon's poller recording windows —
+ * and per-Account files keep them from losing each other's *Accounts*. This is what keeps them from
+ * losing each other's *turns*: a read-modify-write that overwrote the activity list would drop
+ * whatever the other process appended in between.
+ *
+ * A turn is identified by its instant and its cost. Two genuinely simultaneous turns of identical
+ * cost on one Account collapse into one, which costs the record a turn it would have counted; the
+ * alternative is an id per turn on a record that is already advisory, and this record is explicitly
+ * not a number anything depends on.
+ */
+export function mergeActivity(mine: readonly ActivityTurn[] | undefined, theirs: readonly ActivityTurn[] | undefined, now: number): ActivityTurn[] {
+  const byKey = new Map<string, ActivityTurn>();
+  for (const turn of [...(mine ?? []), ...(theirs ?? [])]) byKey.set(`${turn.at}|${turn.costUsd ?? ""}`, turn);
+  return pruneTurns([...byKey.values()], now);
+}

package/src/foreman/usage-format.ts

@@ -0,0 +1,107 @@
+import { thresholdFor, type Account } from "../foreman/account.js";
+import { formatTable, printableOneLine } from "./core/text.js";
+import { summariseActivity } from "./usage-activity.js";
+import { describeAge, describeUntil, headroom, thresholdHold, type AccountUsage } from "./usage.js";
+
+/**
+ * How usage is rendered for a terminal.
+ *
+ * Out of `commands/account-usage.ts` because the command had grown four reasons to change — two
+ * table shapes, a measurement path and an empty-state message — against the seam the README states
+ * for `commands/initiative.ts`: a command parses arguments and prints, and formatting that turns up
+ * in one is the seam asking for a module of its own.
+ */
+/**
+ * One line per Account: what is left, which window decides that, when it resets, and the state.
+ *
+ * Headroom is the tightest live window's, which is the number every dispatch decision uses — an
+ * Account at 20% of its five-hour and 98% of its seven-day has 2% to spend, not 41%.
+ */
+export function summaryRows(accounts: Account[], known: Map<string, AccountUsage>, now: number): string[] {
+  const rows: string[][] = [["ACCOUNT", "HEADROOM", "TIGHTEST", "RESETS", "STATE"]];
+  for (const account of accounts) {
+    const record = known.get(account.name);
+    if (account.type === "api_key") {
+      rows.push([account.name, "-", "-", "-", "API key: no usage is reported for it, and it is never held back"]);
+      continue;
+    }
+    const left = headroom(record, now);
+    if (left.kind === "unknown") {
+      rows.push([account.name, "-", "-", "-", failureNote(record, now) ?? "never observed"]);
+      continue;
+    }
+    const hold = thresholdHold(record, thresholdFor(account), now);
+    const notes = [
+      hold ? `held at ${hold.reason}` : "active",
+      describeAge(left.observedAt, now) === "just now" ? "" : `seen ${describeAge(left.observedAt, now)}`,
+      failureNote(record, now) ?? "",
+      summariseActivity(record, now) ?? "",
+    ].filter(Boolean);
+    rows.push([account.name, `${left.remainingPct}%`, left.tightest, describeUntil(left.resetsAt, now), notes.join("; ")]);
+  }
+  return formatTable(rows, ["left", "right", "left", "right"]);
+}
+
+/**
+ * A row per window: what `--windows` is for.
+ *
+ * Freshness and provenance are on every line on purpose. A percentage with no age reads as current
+ * however old it is, and the sources are not equally trustworthy: `in_band` is what the vendor told
+ * a Worker, `polled` is a measurement of an idle Account. The `foreman` row beneath them is not a
+ * source at all — it is this Foreman's own tally of what it spent, and states no percentage
+ * (usage-activity.ts says why it cannot honestly state one).
+ */
+export function windowRows(accounts: Account[], known: Map<string, AccountUsage>, now: number): string[] {
+  const rows: string[][] = [["ACCOUNT", "WINDOW", "USED", "LEFT", "RESETS", "SEEN", "SOURCE", "STATE"]];
+  for (const account of accounts) {
+    const record = known.get(account.name);
+    // An API-key Account is not an unmeasured subscription: there is no window to measure, it is
+    // never rate limited as far as the Foreman can see, and the usage-aware strategies must not
+    // read it as spent. Said in words so nobody reads a blank row as "exhausted".
+    if (account.type === "api_key") {
+      rows.push([account.name, "-", "-", "-", "-", "-", "-", "API key: no usage is reported for it, and it is never held back"]);
+      continue;
+    }
+    const windows = Object.entries(record?.windows ?? {});
+    if (windows.length === 0) {
+      rows.push([account.name, "-", "-", "-", "-", "-", "-", failureNote(record, now) ?? "never observed"]);
+      continue;
+    }
+    const hold = thresholdHold(record, thresholdFor(account), now);
+    const left = headroom(record, now);
+    for (const [name, window] of windows.sort(([a], [b]) => a.localeCompare(b))) {
+      const live = Date.parse(window.resetsAt) > now;
+      const state = !live
+        ? "window has reset; the number is last window's"
+        : hold?.window === name
+          ? `held back until it resets (at or past the ${thresholdFor(account)}% threshold)`
+          : left.kind === "known" && left.tightest === name
+            ? "the tightest window, so this is what decides dispatch"
+            : "";
+      rows.push([
+        account.name,
+        name,
+        `${window.usedPct}%`,
+        live ? `${Math.max(0, Math.min(100, 100 - window.usedPct))}%` : "-",
+        live ? describeUntil(window.resetsAt, now) : "-",
+        describeAge(window.observedAt, now),
+        window.source,
+        state,
+      ]);
+    }
+    const failure = failureNote(record, now);
+    if (failure) rows.push([account.name, "-", "-", "-", "-", "-", "-", failure]);
+    // This Foreman's own tally beside the vendor's windows, and clearly not one of them: it is what
+    // was spent, never a share of a limit.
+    const activity = summariseActivity(record, now);
+    if (activity) rows.push([account.name, "-", "-", "-", "-", "-", "foreman", activity]);
+  }
+  return formatTable(rows, ["left", "left", "right", "right", "right", "right"]);
+}
+
+/** The last poll failure in one line, so a reader can tell a stale number from a current one. */
+function failureNote(record: AccountUsage | undefined, now: number): string | undefined {
+  if (!record?.pollFailedAt) return undefined;
+  const waiting = record.pollBackoffUntil && Date.parse(record.pollBackoffUntil) > now ? `, not asking again until ${describeUntil(record.pollBackoffUntil, now)}` : "";
+  return `last poll failed ${describeAge(record.pollFailedAt, now)}: ${printableOneLine(record.pollFailure ?? "no reason given")}${waiting}`;
+}