@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/company-resolver.ts

@@ -1,521 +0,0 @@
-/**
- * cwd → owning-company resolution for telemetry edge attribution
- * (surface-hq-console-telemetry US-002).
- *
- * Both telemetry collectors (`./telemetry.ts`, `./skill-telemetry.ts`) stamp an
- * optional `companyUid` on each event so the server can attribute usage to the
- * company that owns the repo the event was produced in. The mapping comes from
- * `<hqRoot>/companies/manifest.yaml`, whose shape is:
- *
- *   companies:
- *     indigo:
- *       repos:
- *         - repos/private/hq-cloud
- *         - repos/public/hq-core
- *       cloud_uid: cmp_01KQWRSQTCTES1SEFKXKDZAAK1
- *     liverecover:
- *       repos:
- *         - repos/private/liverecover-site
- *       # (no cloud_uid — not cloud-backed)
- *
- * companyUid source: the value stamped is the manifest's `cloud_uid`. That is a
- * `cmp_*` entity uid — the SAME value the server membership-keys on
- * (`membershipKey = '<personUid>#<companyUid>'`, where companyUid is the cmp_*
- * uid; see hq-pro `vault-service/handlers/usage.ts` + `skill-invocations.ts`).
- * So no slug→uid round-trip is needed: the manifest already carries the uid the
- * server expects. A company entry WITHOUT a `cloud_uid` (not cloud-backed, e.g.
- * `liverecover`/`temple`) contributes no mapping — its repos resolve to no
- * companyUid and the event is sent unattributed (field omitted).
- *
- * The reserved sentinel `unattributed` is NEVER produced here — "no match"
- * means "return undefined / omit the field", which the server treats as
- * unattributed/personal.
- *
- * Cost: `buildRepoCompanyMap()` parses the manifest ONCE per sync run; the
- * resulting map is reused for every event via `resolveCompanyForCwd()`. No
- * per-event manifest reads.
- *
- * Privacy: this module only ever returns a `cmp_*` uid (or undefined). It never
- * adds a raw path to any payload — the collectors add exactly one new field,
- * `companyUid`.
- */
-
-import { promises as fs } from "node:fs";
-import * as path from "node:path";
-
-import yaml from "js-yaml";
-
-/**
- * A repo-path → companyUid lookup, built once per run. Keys are ABSOLUTE,
- * normalized repo roots (`<hqRoot>/repos/private/hq-cloud`); values are the
- * owning company's `cmp_*` uid. An event `cwd` is attributed to the entry whose
- * repo root is the longest prefix of (or equal to) the cwd.
- */
-export interface RepoCompanyMap {
-  /**
-   * Absolute, normalized repo root → owning company `cmp_*` uid. `matchKey` is
-   * the precomputed `canonicalPath(repoRoot)` used for the containment test, so
-   * per-event matching stays a plain string compare.
-   */
-  entries: Array<{ repoRoot: string; matchKey: string; companyUid: string }>;
-  /**
-   * Company SLUG → owning company `cmp_*` uid, from the manifest keys. Backs
-   * skill-based attribution: a company skill is invoked as `<slug>:<skill>`
-   * (mirroring `companies/<slug>/skills/`), so its usage belongs to the company
-   * named by that slug regardless of the cwd it ran in. Manifest keys are unique,
-   * so a slug resolves to exactly one cloud-backed company here.
-   */
-  bySlug: Map<string, string>;
-  /**
-   * Whether the HQ filesystem folds case, PROBED at build time rather than
-   * inferred from `process.platform`. APFS can be case-sensitive on macOS and
-   * Windows supports per-directory case sensitivity, so the OS is only a hint;
-   * getting this wrong in the folding direction risks cross-tenant
-   * misattribution. Defaults to `false` (exact matching) when the probe fails.
-   */
-  foldsCase: boolean;
-  /**
-   * Match keys that two or more companies claimed. They are excluded from
-   * `entries` (fail closed), and resolution must ALSO refuse to reach them via
-   * the worktree fallback — otherwise an ambiguous `foo-wt-team` would collapse
-   * to `foo` and hand the event to whichever company owns `foo`, quietly
-   * undoing the protection.
-   */
-  ambiguous: Set<string>;
-}
-
-interface ManifestCompany {
-  repos?: unknown;
-  cloud_uid?: unknown;
-  /** HQ-root-relative company directory (e.g. `companies/indigo`). */
-  path?: unknown;
-}
-
-interface ManifestShape {
-  companies?: Record<string, ManifestCompany>;
-}
-
-/** Drop a trailing slash (keeping a bare "/"). Mirrors the scope-path
- *  normalization in `./skill-telemetry.ts` so prefix matching is consistent. */
-function normalizePath(p: string): string {
-  return p.length > 1 ? p.replace(/\/+$/, "") : p;
-}
-
-/**
- * Canonical comparison key for a filesystem path.
- *
- * Both sides of the containment test (`repoRoot` and the event `cwd`) run
- * through this so a match does not hinge on the emitting machine's path
- * dialect. Real prod `cwd` values include Windows roots (`C:\Users\eggsa\HQ`)
- * alongside POSIX ones, and the manifest side is built with `path.resolve`,
- * which emits the HOST separator. Comparing those raw meant Windows clients
- * could never match.
- *
- * Two normalizations, both deliberate:
- *   - Separators collapse to `/` so `C:\Users\x\HQ` and `C:/Users/x/HQ` agree.
- *   - Case is folded only when the HQ filesystem actually folds case, as
- *     PROBED by `probeCaseFolding`. Where it does, `.../HQ` and `.../hq` are
- *     the same directory and not folding would drop real attribution. Where it
- *     does not, they are different directories and folding could attribute a
- *     cwd to a company that does not own it.
- *
- * Correct-but-unattributed always beats attributed-to-the-wrong-company, so the
- * probe defaults to NOT folding whenever it cannot determine the answer.
- */
-function canonicalPath(p: string, foldsCase: boolean): string {
-  const normalized = normalizePath(p.replace(/\\/g, "/"));
-  return foldsCase ? normalized.toLowerCase() : normalized;
-}
-
-/**
- * Determine whether the filesystem folds case for entries INSIDE `hqRoot`, by
- * asking it.
- *
- * `process.platform` is only a hint: APFS volumes can be created case-SENSITIVE
- * on macOS, and Windows supports per-directory case sensitivity — in both cases
- * the platform still reads `darwin`/`win32`. Since folding on a case-sensitive
- * filesystem risks cross-tenant misattribution, we probe instead of assume.
- *
- * The probe deliberately targets a CHILD of `hqRoot` (`companies/`, which must
- * exist — the manifest was just read from inside it) rather than `hqRoot`
- * itself. Under Windows per-directory case sensitivity, the lookup of a
- * directory's own name is governed by its PARENT, so probing `hqRoot` would
- * report the parent's behaviour while every path we actually compare lives
- * inside `hqRoot`. Probing a child measures the directory that matters.
- *
- * The probe stats the child with its basename case inverted and compares inode
- * identity. Any failure (missing, permission denied, no inode) returns `false`,
- * the conservative answer.
- */
-async function probeDirFoldsCase(dir: string): Promise<boolean> {
-  const base = path.basename(dir);
-  const flippedBase = base
-    .split("")
-    .map((c) => (c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()))
-    .join("");
-  if (flippedBase === base) return false; // no cased characters to test with
-  try {
-    const [a, b] = await Promise.all([
-      fs.stat(dir),
-      fs.stat(path.join(path.dirname(dir), flippedBase)),
-    ]);
-    // Same file identity via the flipped-case name ⇒ this directory folds case.
-    return a.ino !== 0 && a.ino === b.ino && a.dev === b.dev;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Whether case may be folded for EVERY directory we actually match under.
- *
- * Windows configures case sensitivity PER DIRECTORY, so one probe cannot speak
- * for the whole tree: `companies/`, `repos/private/`, and an external symlink
- * target can each behave differently. Folding a path whose parent is
- * case-sensitive is the direction that risks stamping the wrong `companyUid`,
- * so this requires unanimity — if any probe says case-sensitive, or there is
- * nothing to probe, matching stays case-exact everywhere.
- *
- * Pass the ROOTS, not their parents. Case behaviour for a name is a property of
- * the directory the name is looked up IN, so flipping a root's basename
- * measures that root's PARENT — precisely the directory we match under.
- * Flipping the parent's own basename would instead measure the grandparent and
- * could report folding for a parent that is actually case-sensitive.
- *
- * The cost is one `stat` pair per distinct root, concurrently, once per run.
- */
-async function probeCaseFolding(roots: string[]): Promise<boolean> {
-  const distinct = [...new Set(roots)];
-  if (distinct.length === 0) return false;
-  const results = await Promise.all(distinct.map(probeDirFoldsCase));
-  return results.every(Boolean);
-}
-
-/**
- * Expand one manifest `repos` entry into the absolute roots it may live at.
- *
- * The manifest records repos as BARE NAMES (`hq-cloud`, `hq-console`) — see
- * `companies/manifest.yaml` — while the checkout lives under
- * `<hqRoot>/repos/{private,public}/<name>`. The original implementation did a
- * plain `path.resolve(hqRoot, repo)`, producing `<hqRoot>/hq-cloud`, a path
- * that exists for no repo. Every entry therefore matched no cwd and NO event
- * was ever attributed (verified in prod: 0 of 3200 sampled usage events across
- * 9 people carried a `companyUid`).
- *
- * An entry that already contains a separator is treated as an HQ-root-relative
- * path verbatim, so the documented `repos/private/<name>` form keeps working.
- */
-function repoRootCandidates(hqRoot: string, repo: string): string[] {
-  const trimmed = repo.trim().replace(/^\.\//, "");
-  if (trimmed.includes("/") || trimmed.includes("\\")) {
-    return [path.resolve(hqRoot, trimmed)];
-  }
-  return [
-    path.resolve(hqRoot, "repos", "private", trimmed),
-    path.resolve(hqRoot, "repos", "public", trimmed),
-  ];
-}
-
-/**
- * Sibling git-worktree checkouts of `repoRoot`, per HQ's `<repo>-wt-<branch>`
- * convention (e.g. `repos/private/hq-pro-wt-feature-x`).
- *
- * These matter a lot in practice: a large share of HQ work happens INSIDE a
- * worktree rather than the primary checkout, and the resolver's slash boundary
- * deliberately rejects `…/hq-pro-wt-feature-x` as a mere string-prefix sibling
- * of `…/hq-pro`. Without this expansion every worktree session stays
- * unattributed — which is exactly the emptiness this whole change is fixing.
- *
- * The prefix test honours `foldsCase`: `readdir` returns the casing stored on
- * disk while `name` comes from the manifest, so on a case-folding filesystem a
- * manifest entry `hq-cloud` must still find a checkout stored as
- * `HQ-Cloud-wt-x`. Using a case-sensitive comparison there would drop the
- * worktree even though the later match treats those casings as the same path.
- *
- * Best-effort: an unreadable parent directory yields no worktrees rather than
- * failing the run.
- */
-async function worktreeSiblings(repoRoot: string, foldsCase: boolean): Promise<string[]> {
-  const parent = path.dirname(repoRoot);
-  const prefix = `${path.basename(repoRoot)}-wt-`;
-  const wanted = foldsCase ? prefix.toLowerCase() : prefix;
-  try {
-    const dirents = await fs.readdir(parent, { withFileTypes: true });
-    return dirents
-      .filter((d) => {
-        if (!d.isDirectory() && !d.isSymbolicLink()) return false;
-        const candidate = foldsCase ? d.name.toLowerCase() : d.name;
-        return candidate.startsWith(wanted);
-      })
-      .map((d) => path.join(parent, d.name));
-  } catch {
-    return [];
-  }
-}
-
-/**
- * The physical path behind `p`, when it differs from the lexical one.
- *
- * HQ's knowledge-repo layout uses symlinked checkouts, and a process launched
- * inside one can report the RESOLVED path as its `cwd`. Matching only the
- * lexical path would then miss the event entirely, so both are registered.
- * Returns `null` when the path does not exist or already is its own realpath.
- */
-/**
- * Whether `candidate` is strictly beneath `root`.
- *
- * Guards manifest-supplied paths. The HQ root itself is NOT inside itself: it
- * spans every tenant, so claiming it for one company would misattribute all of
- * them.
- */
-function isInsideRoot(root: string, candidate: string): boolean {
-  const rel = path.relative(root, candidate);
-  return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
-}
-
-async function physicalAlias(p: string): Promise<string | null> {
-  try {
-    const real = await fs.realpath(p);
-    return real !== p ? real : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Whether the path exists at all (used to keep absent candidates out of the
- *  case probe, where they would look indistinguishable from case-sensitive). */
-async function physicalExists(p: string): Promise<boolean> {
-  try {
-    await fs.stat(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Parse `<hqRoot>/companies/manifest.yaml` ONCE and build the repo-path →
- * companyUid lookup. Best-effort: a missing/unparseable manifest yields an
- * empty map (every event then resolves to no company → unattributed), so a
- * telemetry run never fails on a manifest problem.
- *
- * Only companies that carry a `cloud_uid` (`cmp_*`) contribute entries — a
- * company without one is not cloud-backed and its repos stay unattributed.
- */
-export async function buildRepoCompanyMap(hqRoot: string): Promise<RepoCompanyMap> {
-  const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
-  const empty = (foldsCase = false): RepoCompanyMap => ({
-    entries: [],
-    bySlug: new Map(),
-    foldsCase,
-    ambiguous: new Set(),
-  });
-
-  let doc: ManifestShape;
-  try {
-    const raw = await fs.readFile(manifestPath, "utf-8");
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return empty();
-    doc = parsed as ManifestShape;
-  } catch {
-    // Missing / unreadable / unparseable — no attribution this run.
-    return empty();
-  }
-
-  const companies = doc.companies;
-  if (!companies || typeof companies !== "object") return empty();
-
-  const bySlug = new Map<string, string>();
-  // Roots are collected BEFORE anything is canonicalized, because the case
-  // probe needs to know which parent directories we will actually match under.
-  const rootsToExpand: Array<{ root: string; companyUid: string }> = [];
-
-  for (const [slug, company] of Object.entries(companies)) {
-    if (!company || typeof company !== "object") continue;
-    const cloudUid = company.cloud_uid;
-    // Only cloud-backed companies (with a cmp_* uid) attribute events.
-    if (typeof cloudUid !== "string" || !cloudUid.startsWith("cmp_")) continue;
-    // Slug → uid for skill-based attribution (a `<slug>:<skill>` invocation).
-    if (typeof slug === "string" && slug.length > 0) bySlug.set(slug, cloudUid);
-
-    // The company's own HQ directory (`companies/<slug>`) is company-owned work
-    // too — skills, knowledge, and project files all live there, and in prod a
-    // large share of sessions run from inside the HQ root rather than a repo
-    // checkout. Without this, that work is silently unattributed.
-    const declaredPath =
-      typeof company.path === "string" && company.path.trim().length > 0
-        ? company.path.trim()
-        : `companies/${slug}`;
-    // `path` is documented as HQ-root-RELATIVE, but the manifest is synced and
-    // hand-editable. An absolute path, `.`, or `..` would otherwise register the
-    // HQ root — or an arbitrary directory — as owned by this company, stamping
-    // its uid on every event beneath. Anything that escapes the root is dropped.
-    const companyDir = path.resolve(hqRoot, declaredPath);
-    if (isInsideRoot(hqRoot, companyDir)) {
-      rootsToExpand.push({ root: companyDir, companyUid: cloudUid });
-    }
-
-    const repos = company.repos;
-    if (!Array.isArray(repos)) continue;
-    for (const repo of repos) {
-      if (typeof repo !== "string" || repo.trim().length === 0) continue;
-      // Manifest `repos` are BARE NAMES; expand to the real checkout roots
-      // under `repos/{private,public}/`. See `repoRootCandidates`.
-      for (const candidate of repoRootCandidates(hqRoot, repo)) {
-        rootsToExpand.push({ root: candidate, companyUid: cloudUid });
-      }
-    }
-  }
-
-  // Discover BEFORE probing, so the probe can cover every directory we will
-  // actually match under — including the parents of external symlink targets,
-  // which are unknown until the aliases are resolved.
-  //
-  // Worktree discovery matches its prefix case-INSENSITIVELY here regardless of
-  // the filesystem. That deliberately yields a superset: claims are still keyed
-  // by the probed `foldsCase` below, so a case-variant that the filesystem
-  // considers distinct simply becomes its own (possibly ambiguous) claim rather
-  // than being silently missed at discovery time.
-  const expansions = await Promise.all(
-    rootsToExpand.map(async ({ root, companyUid }) => {
-      const [worktrees, real] = await Promise.all([
-        worktreeSiblings(root, true),
-        physicalAlias(root),
-      ]);
-      const paths = real ? [...worktrees, real] : [...worktrees];
-      const worktreeReals = await Promise.all(worktrees.map(physicalAlias));
-      for (const wr of worktreeReals) if (wr) paths.push(wr);
-      return { paths, companyUid };
-    }),
-  );
-
-  const allPaths = [
-    ...rootsToExpand.map((r) => r.root),
-    ...expansions.flatMap((e) => e.paths),
-  ];
-
-  // Probe the actual filesystem rather than trusting `process.platform`, over
-  // every path we may match under. Only paths that EXIST are probed: a bare
-  // repo name expands to both `repos/private` and `repos/public` and normally
-  // only one is real, so including the missing one would report
-  // case-sensitivity for a directory that is simply absent and wrongly force
-  // the whole map exact.
-  const existing = await Promise.all(
-    allPaths.map(async (p) => ((await physicalExists(p)) ? p : null)),
-  );
-  const foldsCase = await probeCaseFolding(existing.filter((p): p is string => p !== null));
-
-  // Collect claims first, resolve conflicts second. A path claimed by two
-  // DIFFERENT companies is ambiguous and must not be attributed to whichever
-  // one the manifest happened to list first.
-  const claims = new Map<string, { repoRoot: string; companyUids: Set<string> }>();
-  const claim = (absPath: string, companyUid: string): void => {
-    const repoRoot = normalizePath(absPath);
-    const matchKey = canonicalPath(repoRoot, foldsCase);
-    const existingClaim = claims.get(matchKey);
-    if (existingClaim) existingClaim.companyUids.add(companyUid);
-    else claims.set(matchKey, { repoRoot, companyUids: new Set([companyUid]) });
-  };
-  for (const { root, companyUid } of rootsToExpand) claim(root, companyUid);
-  for (const { paths, companyUid } of expansions) {
-    for (const p of paths) claim(p, companyUid);
-  }
-
-  const entries: Array<{ repoRoot: string; matchKey: string; companyUid: string }> = [];
-  const ambiguous = new Set<string>();
-  for (const [matchKey, { repoRoot, companyUids }] of claims) {
-    // Fail CLOSED on ambiguity. Two companies listing the same bare repo name,
-    // or two roots colliding under case folding, cannot be told apart here —
-    // and attributing to the wrong tenant is far worse than not attributing.
-    if (companyUids.size !== 1) {
-      ambiguous.add(matchKey);
-      continue;
-    }
-    entries.push({ repoRoot, matchKey, companyUid: [...companyUids][0] });
-  }
-
-  // Longest root first so the first containment match is the most specific
-  // (handles nested layouts where one repo path prefixes another — notably a
-  // worktree root, which must win over the company dir that contains it).
-  entries.sort((a, b) => b.matchKey.length - a.matchKey.length);
-  return { entries, bySlug, foldsCase, ambiguous };
-}
-
-/**
- * Resolve a skill INVOCATION to its owning company's `cmp_*` uid, or `undefined`
- * when the skill is not a cloud-backed company's skill.
- *
- * A company skill is invoked as `<slug>:<skill>` (the namespaced form of
- * `companies/<slug>/skills/<skill>`); the leading `<slug>` names the owning
- * company. We look that slug up in the manifest's slug→uid map, so a company
- * skill attributes to ITS company no matter which cwd it ran in — this is what
- * surfaces company-skill usage in the company console. A core / `personal:` /
- * `hq-pack-*:` / `anthropic-skills:` skill has no matching manifest company, so
- * it resolves to `undefined` (the cwd resolver remains the fallback).
- */
-export function resolveCompanyForSkill(
-  skill: string | undefined,
-  map: RepoCompanyMap,
-): string | undefined {
-  if (typeof skill !== "string") return undefined;
-  const idx = skill.indexOf(":");
-  if (idx <= 0) return undefined; // un-namespaced (core) skill
-  return map.bySlug.get(skill.slice(0, idx));
-}
-
-/**
- * Resolve an event's `cwd` to the owning company's `cmp_*` uid, or `undefined`
- * when the cwd is inside no cloud-backed company repo (→ omit `companyUid`;
- * the server treats absence as unattributed/personal).
- *
- * Matching is by path containment: the cwd must equal a repo root or sit
- * beneath it (`<repoRoot>/...`). A trailing-slash boundary prevents a sibling
- * that merely shares a string prefix (`<repoRoot>-other`) from matching.
- * Entries are pre-sorted longest-first, so the first match is the most
- * specific.
- *
- * If nothing matches, one lexical retry strips HQ's `-wt-<branch>` worktree
- * suffix from the path. `buildRepoCompanyMap` discovers worktrees by reading
- * the directory, which only sees the ones that exist RIGHT NOW — but telemetry
- * is read from a cursor and a branch worktree is routinely deleted before the
- * next pass. Those pending rows still carry the worktree cwd, and because a
- * successful POST advances the cursor permanently, failing to resolve them
- * loses that attribution for good. The suffix is documented convention, so
- * deriving it from the recorded path needs no directory to still exist.
- */
-export function resolveCompanyForCwd(
-  cwd: string | undefined,
-  map: RepoCompanyMap,
-): string | undefined {
-  if (typeof cwd !== "string" || cwd.length === 0) return undefined;
-  const foldsCase = map.foldsCase === true;
-  const c = canonicalPath(cwd, foldsCase);
-
-  const match = (candidate: string): string | undefined => {
-    for (const { matchKey, companyUid } of map.entries) {
-      if (candidate === matchKey || candidate.startsWith(`${matchKey}/`)) {
-        return companyUid;
-      }
-    }
-    return undefined;
-  };
-
-  const direct = match(c);
-  if (direct) return direct;
-
-  // The path may have been dropped for AMBIGUITY (claimed by two companies).
-  // Falling back would collapse e.g. an ambiguous `foo-wt-team` to `foo` and
-  // hand the event to whoever owns `foo`, silently undoing the fail-closed
-  // protection. An ambiguous path stays unattributed, full stop.
-  const ambiguous = map.ambiguous;
-  if (ambiguous) {
-    for (const key of ambiguous) {
-      if (c === key || c.startsWith(`${key}/`)) return undefined;
-    }
-  }
-
-  // `<...>/hq-pro-wt-feature-x/src` → `<...>/hq-pro/src`. Only the FIRST such
-  // segment is rewritten; `-wt-` deeper in the path is left alone.
-  const collapsed = c.replace(/^(.*?\/[^/]+?)-wt-[^/]*(\/.*)?$/, "$1$2");
-  return collapsed !== c ? match(collapsed) : undefined;
-}