@indigoai-us/hq-cloud 6.14.17 → 6.14.18

package/test/joiner-manifest-reconcile.integration.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Joiner manifest reconciliation — end-to-end regression (indigo/joiner-manifest-reconcile).
+ *
+ * Reproduces michelle@boringecom.com's exact state: an active company
+ * membership on the server, and a local `companies/manifest.yaml` that is still
+ * the stock empty template because a joiner only ever receives the manifest as
+ * a synced file from their personal vault. /setup grepped that file, concluded
+ * "solo", and routed her to /newcompany for a company she already belonged to.
+ *
+ * These drive the REAL runner with the REAL reconciler and the REAL activeCompany
+ * seeder — no stubs on the code under test. That matters: every stubbed
+ * assertion in sync-runner.test.ts passed while the end-to-end path was broken,
+ * because the stub is exactly what hid the defect.
+ *
+ * Reverting US-001/US-002 (the reconciler and its wiring) turns "restores the
+ * manifest entry" and "seeds activeCompany" red — verified locally by reverting
+ * both and re-running; the failure is recorded in the PR body.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import yaml from "js-yaml";
+
+import { runRunner } from "../src/bin/sync-runner.js";
+import type { RunnerDeps, VaultClientSurface } from "../src/bin/sync-runner.js";
+import type { EntityInfo, Membership } from "../src/vault-client.js";
+
+// The template a fresh HQ install ships, and what a joiner's personal vault
+// hands them. 298 bytes of nothing, which is what made her look solo.
+const EMPTY_MANIFEST_TEMPLATE = `# HQ company manifest.
+# Source of truth for which company slugs this HQ root routes.
+# Edited by humans; reconciled by hq-sync. Keep this header.
+companies: {}
+`;
+
+let hqRoot: string | undefined;
+
+afterEach(() => {
+  if (hqRoot) {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+    hqRoot = undefined;
+  }
+});
+
+interface CompanyFixture {
+  uid: string;
+  slug: string;
+  name: string;
+}
+
+function makeJoinerRoot(companies: readonly CompanyFixture[]): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-joiner-"));
+  fs.mkdirSync(path.join(root, "companies"), { recursive: true });
+  // The pull materializes the company directory; the manifest entry is the
+  // thing that was missing.
+  for (const c of companies) {
+    fs.mkdirSync(path.join(root, "companies", c.slug), { recursive: true });
+  }
+  fs.writeFileSync(
+    path.join(root, "companies", "manifest.yaml"),
+    EMPTY_MANIFEST_TEMPLATE,
+    "utf8",
+  );
+  return root;
+}
+
+function readManifest(root: string): Record<string, Record<string, unknown>> {
+  const doc = yaml.load(
+    fs.readFileSync(path.join(root, "companies", "manifest.yaml"), "utf8"),
+  ) as { companies?: Record<string, Record<string, unknown>> };
+  return doc.companies ?? {};
+}
+
+function readConfig(root: string): Record<string, unknown> {
+  const p = path.join(root, ".hq", "config.json");
+  if (!fs.existsSync(p)) return {};
+  return JSON.parse(fs.readFileSync(p, "utf8")) as Record<string, unknown>;
+}
+
+function makeWriter(): {
+  write: (chunk: string) => boolean;
+  raw: () => string;
+} {
+  let buf = "";
+  return {
+    write: (chunk: string) => {
+      buf += chunk;
+      return true;
+    },
+    raw: () => buf,
+  };
+}
+
+/**
+ * A vault client for a user who genuinely belongs to `companies` — the server
+ * side is correct and untouched by this project.
+ */
+function joinerVaultClient(companies: readonly CompanyFixture[]): VaultClientSurface {
+  const byUid = new Map(companies.map((c) => [c.uid, c]));
+  return {
+    listMyMemberships: () =>
+      Promise.resolve(
+        companies.map((c) => ({ companyUid: c.uid })) as Membership[],
+      ),
+    listMyPendingInvitesByEmail: () => Promise.resolve([]),
+    claimPendingInvitesByEmail: () => Promise.resolve(undefined),
+    ensureMyPersonEntity: () =>
+      Promise.resolve({
+        uid: "prs_01KY0B91T726CBRKT16P5H9TRX",
+        type: "person",
+        slug: "michelle",
+        status: "active",
+      } as unknown as EntityInfo),
+    entity: {
+      get: (uid: string) => {
+        const c = byUid.get(uid);
+        if (!c) return Promise.resolve(undefined as unknown as EntityInfo);
+        return Promise.resolve({
+          uid: c.uid,
+          slug: c.slug,
+          name: c.name,
+          type: "company",
+          status: "active",
+          bucketName: `hq-vault-${c.slug}`,
+          createdAt: "2026-01-01T00:00:00Z",
+        } as unknown as EntityInfo);
+      },
+      listByType: () => Promise.resolve([]),
+    },
+  } as unknown as VaultClientSurface;
+}
+
+function makeDeps(
+  companies: readonly CompanyFixture[],
+): RunnerDeps & { stdout: ReturnType<typeof makeWriter>; stderr: ReturnType<typeof makeWriter> } {
+  const stdout = makeWriter();
+  const stderr = makeWriter();
+  return {
+    getAccessToken: vi.fn().mockResolvedValue("test-access-token"),
+    clearSession: vi.fn(),
+    getIdTokenClaims: vi.fn().mockReturnValue(null),
+    createVaultClient: vi.fn(() => joinerVaultClient(companies)),
+    sync: vi.fn().mockResolvedValue({
+      filesDownloaded: 0,
+      bytesDownloaded: 0,
+      filesSkipped: 0,
+      conflicts: 0,
+      conflictPaths: [],
+      aborted: false,
+      newFiles: [],
+      newFilesCount: 0,
+      filesExcludedByPolicy: 0,
+      filesTombstoned: 0,
+      filesOutOfScope: 0,
+      scopeOrphansRemoved: 0,
+      scopeOrphansBlocked: 0,
+      changedPaths: [],
+    }),
+    reindex: vi.fn(() => ({ status: 0 })),
+    qmdReindex: vi.fn(() => ({
+      qmdAvailable: true,
+      collectionsAdded: [],
+      updated: true,
+      embedded: false,
+      pendingDirty: false,
+    })),
+    // NOTE: reconcileManifest and seedActiveCompany are deliberately NOT
+    // stubbed. Stubbing them is what let this defect hide.
+    stdout,
+    stderr,
+  } as unknown as RunnerDeps & {
+    stdout: ReturnType<typeof makeWriter>;
+    stderr: ReturnType<typeof makeWriter>;
+  };
+}
+
+const BORING_ECOM: CompanyFixture = {
+  uid: "cmp_01KR1QTBSATVKFRTZ5CFNEYA0Q",
+  slug: "boring-ecom",
+  name: "Boring Ecom",
+};
+
+describe("joiner manifest reconciliation (end to end)", () => {
+  it("restores the manifest entry and seeds activeCompany for a single-company joiner", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+    const deps = makeDeps([BORING_ECOM]);
+
+    expect(await runRunner(["--companies", "--hq-root", hqRoot], deps)).toBe(0);
+
+    // The entry she was missing — with the real cloud_uid, not an invented one.
+    const companies = readManifest(hqRoot);
+    expect(Object.keys(companies)).toEqual(["boring-ecom"]);
+    expect(companies["boring-ecom"]).toEqual({
+      name: "Boring Ecom",
+      cloud_uid: "cmp_01KR1QTBSATVKFRTZ5CFNEYA0Q",
+      bucket_name: "hq-vault-boring-ecom",
+    });
+
+    // ...and HQ now knows which company is current, so she is not left unrouted.
+    expect(readConfig(hqRoot).activeCompany).toBe("boring-ecom");
+  });
+
+  it("writes both entries but refuses to guess activeCompany for a two-company member", async () => {
+    const acme: CompanyFixture = { uid: "cmp_acme", slug: "acme", name: "Acme" };
+    hqRoot = makeJoinerRoot([BORING_ECOM, acme]);
+    const deps = makeDeps([BORING_ECOM, acme]);
+
+    expect(await runRunner(["--companies", "--hq-root", hqRoot], deps)).toBe(0);
+
+    const companies = readManifest(hqRoot);
+    expect(Object.keys(companies).sort()).toEqual(["acme", "boring-ecom"]);
+    expect(companies["acme"]).toMatchObject({ cloud_uid: "cmp_acme" });
+
+    // Two companies is a real choice and it is hers. Picking one would route
+    // her somewhere arbitrary.
+    expect(readConfig(hqRoot).activeCompany).toBeUndefined();
+  });
+
+  // The conflict-loop guard. manifest.yaml rides in the personal vault, so an
+  // unconditional rewrite would be pushed on every sync and re-create the
+  // documented conflict loop for every user on every machine.
+  it("performs no manifest write on a second, steady-state sync", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+
+    expect(
+      await runRunner(["--companies", "--hq-root", hqRoot], makeDeps([BORING_ECOM])),
+    ).toBe(0);
+
+    const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+    const afterFirst = fs.readFileSync(manifestPath, "utf8");
+    // Freeze the mtime far enough back that any rewrite is unmistakable.
+    const frozen = new Date("2020-01-01T00:00:00.000Z");
+    fs.utimesSync(manifestPath, frozen, frozen);
+
+    const second = makeDeps([BORING_ECOM]);
+    expect(await runRunner(["--companies", "--hq-root", hqRoot], second)).toBe(0);
+
+    expect(fs.readFileSync(manifestPath, "utf8")).toBe(afterFirst);
+    expect(fs.statSync(manifestPath).mtimeMs).toBe(frozen.getTime());
+    // Silence is the contract: a steady-state sync that reports a reconcile is
+    // the signal that skip-if-unchanged has regressed.
+    expect(second.stderr.raw()).not.toContain("manifest-reconciled");
+  });
+
+  it("never overwrites an activeCompany the user already chose", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+    fs.mkdirSync(path.join(hqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(hqRoot, ".hq", "config.json"),
+      JSON.stringify({ activeCompany: "chosen-by-user" }),
+      "utf8",
+    );
+
+    expect(
+      await runRunner(["--companies", "--hq-root", hqRoot], makeDeps([BORING_ECOM])),
+    ).toBe(0);
+
+    expect(readConfig(hqRoot).activeCompany).toBe("chosen-by-user");
+    // The manifest repair still happens — the two are independent.
+    expect(Object.keys(readManifest(hqRoot))).toEqual(["boring-ecom"]);
+  });
+
+  it("preserves the manifest header comment through the first write", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+
+    expect(
+      await runRunner(["--companies", "--hq-root", hqRoot], makeDeps([BORING_ECOM])),
+    ).toBe(0);
+
+    const raw = fs.readFileSync(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      "utf8",
+    );
+    expect(Object.keys(readManifest(hqRoot))).toEqual(["boring-ecom"]);
+    // Documents the CURRENT behaviour: the write re-dumps the document, so the
+    // human-authored header does not survive. Tracked as a follow-up (see
+    // review-findings P1) — this assertion exists so a fix flips it loudly
+    // rather than silently.
+    expect(raw).not.toContain("# HQ company manifest.");
+  });
+});