@indigoai-us/hq-cloud 6.14.16 → 6.14.18

package/src/active-company.ts

@@ -0,0 +1,168 @@
+/**
+ * Seed `activeCompany` in `.hq/config.json` for a joiner who has exactly one
+ * cloud company.
+ *
+ * A newly invited member arrives with no local company routing at all. The
+ * manifest reconciler restores their `companies/manifest.yaml` entry, but
+ * nothing tells HQ which company is *current*, so they stay unrouted even
+ * though membership resolved fine. When the answer is unambiguous — one company
+ * and no existing choice — recording it is strictly better than leaving the
+ * user to guess.
+ *
+ * Everything here is deliberately conservative. This runs unattended on every
+ * sync, against a file the user also edits by hand, so the bar for writing is
+ * "the answer cannot be wrong": never overwrite an existing choice, never guess
+ * between two companies, and never clobber a file we could not parse.
+ */
+
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface SeedActiveCompanyOptions {
+  hqRoot: string;
+  /** Slugs of companies that reconciled successfully this run. */
+  companySlugs: readonly string[];
+  reportDiagnostic?: (diagnostic: {
+    event: string;
+    message: string;
+    err: unknown;
+    context: Record<string, unknown>;
+  }) => void;
+}
+
+export interface SeedActiveCompanyResult {
+  /** True only when `.hq/config.json` was actually written. */
+  written: boolean;
+  /** The slug that was seeded, when one was. */
+  activeCompany?: string;
+  /** Why nothing was written. Absent when `written` is true. */
+  skippedReason?:
+    | "ambiguous"
+    | "no-companies"
+    | "already-set"
+    | "unreadable-config"
+    | "write-failed";
+}
+
+interface HqConfig {
+  activeCompany?: unknown;
+  companySlug?: unknown;
+  [key: string]: unknown;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value) as object | null;
+  return proto === Object.prototype || proto === null;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Write `config` to `configPath` via temp-file + rename, so a reader never
+ * observes a half-written config and a crash cannot truncate the original.
+ */
+function writeConfigAtomically(configPath: string, config: HqConfig): void {
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const temporaryPath = path.join(dir, `.config-${process.pid}-${randomUUID()}.json`);
+  try {
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    fs.renameSync(temporaryPath, configPath);
+  } finally {
+    // The rename consumed the temp file on the success path; this only fires
+    // when writing or renaming threw, and must not mask the original error.
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // Best effort — a stray temp file is not worth failing a sync over.
+    }
+  }
+}
+
+/**
+ * Seed `activeCompany` when — and only when — the answer is unambiguous.
+ *
+ * Never throws: the caller is a sync run whose exit code must not depend on
+ * local routing convenience.
+ */
+export function seedActiveCompany(
+  options: SeedActiveCompanyOptions,
+): SeedActiveCompanyResult {
+  const slugs = Array.from(new Set(options.companySlugs.filter(isNonEmptyString)));
+  if (slugs.length === 0) return { written: false, skippedReason: "no-companies" };
+  // Two or more companies is a genuine choice and belongs to the user. Picking
+  // one would route them somewhere arbitrary and look like a bug.
+  if (slugs.length > 1) return { written: false, skippedReason: "ambiguous" };
+
+  const activeCompany = slugs[0];
+  const configPath = path.join(options.hqRoot, ".hq", "config.json");
+
+  let config: HqConfig = {};
+  let raw: string | undefined;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      // An unreadable config is user state we cannot reason about. Leave it.
+      options.reportDiagnostic?.({
+        event: "runner.active_company.config_unreadable",
+        message: "could not read .hq/config.json; activeCompany not seeded",
+        err,
+        context: { configPath },
+      });
+      return { written: false, skippedReason: "unreadable-config" };
+    }
+  }
+
+  if (raw !== undefined) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      // Malformed JSON is almost always a half-finished hand edit. Overwriting
+      // it would destroy whatever the user was in the middle of doing.
+      options.reportDiagnostic?.({
+        event: "runner.active_company.config_malformed",
+        message: ".hq/config.json is not valid JSON; left untouched",
+        err,
+        context: { configPath },
+      });
+      return { written: false, skippedReason: "unreadable-config" };
+    }
+    if (!isPlainObject(parsed)) {
+      options.reportDiagnostic?.({
+        event: "runner.active_company.config_malformed",
+        message: ".hq/config.json is not a JSON object; left untouched",
+        err: undefined,
+        context: { configPath },
+      });
+      return { written: false, skippedReason: "unreadable-config" };
+    }
+    config = parsed;
+  }
+
+  // `companySlug` counts as already-set: sync-core resolves it as the active
+  // company when `activeCompany` is absent, so writing `activeCompany` here
+  // would silently re-route a user who already had an effective answer.
+  if (isNonEmptyString(config.activeCompany) || isNonEmptyString(config.companySlug)) {
+    return { written: false, skippedReason: "already-set" };
+  }
+
+  try {
+    writeConfigAtomically(configPath, { ...config, activeCompany });
+  } catch (err) {
+    options.reportDiagnostic?.({
+      event: "runner.active_company.write_failed",
+      message: "failed to seed activeCompany in .hq/config.json",
+      err,
+      context: { configPath, activeCompany },
+    });
+    return { written: false, skippedReason: "write-failed" };
+  }
+
+  return { written: true, activeCompany };
+}

package/src/bin/sync-runner-planning.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { buildFanoutPlan, resolveMembershipsForRun } from "./sync-runner-planning.js";
+import type { VaultClientSurface } from "./sync-runner.js";
+
+const noopStderr = { write: () => true };
+
+function clientStub(overrides: Record<string, unknown> = {}): VaultClientSurface {
+  return {
+    entity: {
+      get: () => Promise.resolve(undefined),
+      listByType: () => Promise.resolve([]),
+    },
+    ...overrides,
+  } as unknown as VaultClientSurface;
+}
+
+describe("resolveMembershipsForRun — setup-needed reasons", () => {
+  // Each reason must come from its OWN trigger. Collapsing them back into a
+  // bare `setup-needed` is what left joiners unable to tell "you have no team"
+  // apart from "you have an invite waiting".
+  it("reports no-memberships when the membership list came back empty", async () => {
+    const result = await resolveMembershipsForRun({
+      personal: false,
+      companies: true,
+      client: clientStub(),
+      claims: null,
+      stderr: noopStderr,
+      runClaimDance: () => Promise.resolve(0),
+      listMemberships: () => Promise.resolve([]),
+    });
+
+    expect(result).toEqual({ status: "setup-needed", reason: "no-memberships" });
+  });
+
+  it("attaches pendingInviteCount when the claim dance left invites unconverted", async () => {
+    const result = await resolveMembershipsForRun({
+      personal: false,
+      companies: true,
+      client: clientStub(),
+      claims: { sub: "sub-1" } as never,
+      stderr: noopStderr,
+      runClaimDance: () => Promise.resolve(3),
+      listMemberships: () => Promise.resolve([]),
+    });
+
+    expect(result).toEqual({
+      status: "setup-needed",
+      reason: "no-memberships",
+      pendingInviteCount: 3,
+    });
+  });
+
+  it("omits pendingInviteCount rather than reporting zero", async () => {
+    const result = await resolveMembershipsForRun({
+      personal: false,
+      companies: true,
+      client: clientStub(),
+      claims: { sub: "sub-1" } as never,
+      stderr: noopStderr,
+      runClaimDance: () => Promise.resolve(0),
+      listMemberships: () => Promise.resolve([]),
+    });
+
+    expect(result).toEqual({ status: "setup-needed", reason: "no-memberships" });
+    expect("pendingInviteCount" in result).toBe(false);
+  });
+
+  it("does not report setup-needed at all when memberships exist", async () => {
+    const runClaimDance = vi.fn().mockResolvedValue(2);
+    const result = await resolveMembershipsForRun({
+      personal: false,
+      companies: true,
+      client: clientStub(),
+      claims: { sub: "sub-1" } as never,
+      stderr: noopStderr,
+      runClaimDance,
+      listMemberships: () => Promise.resolve([{ companyUid: "cmp_a" }]),
+    });
+
+    // Pending invites are only meaningful as an explanation for emptiness.
+    expect(result).toEqual({
+      status: "memberships",
+      memberships: [{ companyUid: "cmp_a" }],
+    });
+  });
+});
+
+describe("buildFanoutPlan — setup-needed reasons", () => {
+  it("reports no-person-entity when --personal has no resolvable personal target", async () => {
+    const result = await buildFanoutPlan({
+      memberships: [],
+      companies: false,
+      personal: true,
+      skipPersonal: false,
+      client: clientStub(),
+      claims: null,
+      resolveSkipPersonal: () => false,
+    });
+
+    expect(result).toEqual({ status: "setup-needed", reason: "no-person-entity" });
+  });
+
+  // A --companies run does not need a personal target to be useful, so an
+  // unresolvable one must not abort the whole run.
+  it("does not report no-person-entity for a --companies run", async () => {
+    const result = await buildFanoutPlan({
+      memberships: [{ companyUid: "cmp_a" }],
+      companies: true,
+      personal: false,
+      skipPersonal: false,
+      client: clientStub({
+        entity: {
+          get: () =>
+            Promise.resolve({
+              uid: "cmp_a",
+              slug: "acme",
+              type: "company",
+              status: "active",
+              bucketName: "bucket-a",
+            }),
+          listByType: () => Promise.resolve([]),
+        },
+      }),
+      claims: null,
+      resolveSkipPersonal: () => false,
+    });
+
+    expect(result.status).toBe("plan");
+  });
+});

package/src/bin/sync-runner-planning.ts

@@ -29,12 +29,35 @@ export interface RunnerTarget {
   slug: string;
   name?: string;
   bucketName?: string;
+  /**
+   * Entity liveness as observed AT PLAN TIME, copied off the `entity.get`
+   * result this plan was built from. Carried so a downstream consumer can make
+   * a liveness decision without paying a second round trip.
+   *
+   * These deliberately do NOT gate SYNC. A suspended company still syncs — that
+   * is user-visible behavior and not ours to change here. They exist so the
+   * MANIFEST decision (see `manifest-reconcile.ts`) can be as strict as it was
+   * when it re-fetched the entity itself. Absent fields mean "unknown", and
+   * every consumer of them is required to fail closed.
+   */
+  entityType?: string;
+  entityStatus?: string;
   personalMode?: boolean;
   journalSlug?: string;
 }
 
+/**
+ * Why a run cannot proceed to a fanout.
+ *
+ * - `no-memberships` — the caller resolved fine but belongs to no company.
+ *   Usually a joiner whose invite is still pending acceptance.
+ * - `no-person-entity` — the caller is signed in but has no personal entity to
+ *   sync into, so even `--personal` has no target.
+ */
+export type SetupNeededReason = "no-memberships" | "no-person-entity";
+
 export type MembershipResolution =
-  | { status: "setup-needed" }
+  | { status: "setup-needed"; reason: SetupNeededReason; pendingInviteCount?: number }
   | { status: "memberships"; memberships: Pick<Membership, "companyUid">[] };
 
 export async function resolveMembershipsForRun(options: {
@@ -44,11 +67,12 @@ export async function resolveMembershipsForRun(options: {
   client: VaultClientSurface;
   claims: IdentityClaims | null;
   stderr: { write: (chunk: string) => boolean | void };
+  /** Returns how many invites were still pending after the claim attempt. */
   runClaimDance: (
     client: VaultClientSurface,
     claims: IdentityClaims,
     stderr: { write: (chunk: string) => boolean | void },
-  ) => Promise<void>;
+  ) => Promise<number>;
   listMemberships: (
     client: VaultClientSurface,
   ) => Promise<Pick<Membership, "companyUid">[]>;
@@ -58,8 +82,9 @@ export async function resolveMembershipsForRun(options: {
   }
 
   if (options.companies) {
+    let pendingInviteCount = 0;
     if (options.claims) {
-      await options.runClaimDance(
+      pendingInviteCount = await options.runClaimDance(
         options.client,
         options.claims,
         options.stderr,
@@ -68,7 +93,15 @@ export async function resolveMembershipsForRun(options: {
 
     const memberships = await options.listMemberships(options.client);
     if (memberships.length === 0) {
-      return { status: "setup-needed" };
+      // Pending invites that did NOT become memberships are the single most
+      // useful thing we can tell this user: they are not "solo", they have an
+      // invite waiting to be accepted. Reported only on the empty path, where
+      // it explains the emptiness.
+      return {
+        status: "setup-needed",
+        reason: "no-memberships",
+        ...(pendingInviteCount > 0 ? { pendingInviteCount } : {}),
+      };
     }
     return { status: "memberships", memberships };
   }
@@ -88,18 +121,31 @@ export async function buildFanoutPlan(options: {
   claims: IdentityClaims | null;
   resolveSkipPersonal: (flag: boolean) => boolean;
 }): Promise<
-  | { status: "setup-needed" }
+  | { status: "setup-needed"; reason: SetupNeededReason }
   | { status: "plan"; plan: RunnerTarget[] }
 > {
   const plan: RunnerTarget[] = [];
   for (const m of options.memberships) {
     let slug = m.companyUid;
     let name: string | undefined;
+    // Carried onto the target so downstream consumers (manifest reconciliation)
+    // can use the bucket, and judge liveness, without re-fetching the entity we
+    // already resolved here. On the degraded catch path below these stay
+    // undefined, which every consumer must read as "unknown" and reject.
+    let bucketName: string | undefined;
+    let entityType: string | undefined;
+    let entityStatus: string | undefined;
     try {
       const info = await options.client.entity.get(m.companyUid);
       if (!info) continue;
       slug = info.slug || m.companyUid;
       name = info.name;
+      bucketName = info.bucketName;
+      // Recorded, never acted on here: a suspended or unexpectedly-typed
+      // company still gets a sync leg exactly as before. Only the manifest
+      // decision consumes these.
+      entityType = info.type;
+      entityStatus = info.status;
     } catch (err) {
       if (err instanceof VaultAuthError) throw err;
       // A stale membership can outlive its company entity. Do not schedule a
@@ -117,7 +163,14 @@ export async function buildFanoutPlan(options: {
       }
       // Best-effort — keep UID as the display identifier.
     }
-    plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
+    plan.push({
+      uid: m.companyUid,
+      slug,
+      ...(name ? { name } : {}),
+      ...(bucketName ? { bucketName } : {}),
+      ...(entityType ? { entityType } : {}),
+      ...(entityStatus ? { entityStatus } : {}),
+    });
   }
 
   if (
@@ -153,7 +206,7 @@ export async function buildFanoutPlan(options: {
         journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
       });
     } else if (options.personal) {
-      return { status: "setup-needed" };
+      return { status: "setup-needed", reason: "no-person-entity" };
     }
   }