@indigoai-us/hq-cloud 6.15.0 → 6.15.2

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

@@ -1,258 +0,0 @@
-import { VaultAuthError, VaultNotFoundError, type Membership } from "../index.js";
-import {
-  pickCanonicalPersonEntity,
-  pickAgentSelfEntity,
-} from "../vault-client.js";
-import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
-import type { RunnerEvent, VaultClientSurface } from "./sync-runner.js";
-
-interface IdentityClaims {
-  sub?: string;
-  email?: string;
-  name?: string;
-  given_name?: string;
-  family_name?: string;
-  /**
-   * Entity-bound machine-principal claims (US-013, unblocks US-004). A
-   * headless agent or Outpost authenticates with machine credentials; its
-   * idToken carries the machine's own entity binding here. The `--personal`
-   * target resolver reads agent claims to resolve the agent AS itself: when
-   * `custom:entityType === "agent"`, the personal slot resolves to the
-   * agent's OWN entity (`custom:entityUid`, `agt_*`) instead of the
-   * person-only canonical pick.
-   */
-  "custom:entityType"?: string;
-  "custom:entityUid"?: string;
-}
-
-export interface RunnerTarget {
-  uid: string;
-  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"; reason: SetupNeededReason; pendingInviteCount?: number }
-  | { status: "memberships"; memberships: Pick<Membership, "companyUid">[] };
-
-export async function resolveMembershipsForRun(options: {
-  personal: boolean;
-  companies: boolean;
-  company?: string;
-  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<number>;
-  listMemberships: (
-    client: VaultClientSurface,
-  ) => Promise<Pick<Membership, "companyUid">[]>;
-}): Promise<MembershipResolution> {
-  if (options.personal) {
-    return { status: "memberships", memberships: [] };
-  }
-
-  if (options.companies) {
-    let pendingInviteCount = 0;
-    if (options.claims && options.claims["custom:entityType"] !== "outpost") {
-      pendingInviteCount = await options.runClaimDance(
-        options.client,
-        options.claims,
-        options.stderr,
-      );
-    }
-
-    const memberships = await options.listMemberships(options.client);
-    if (memberships.length === 0) {
-      // 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 };
-  }
-
-  return {
-    status: "memberships",
-    memberships: [{ companyUid: options.company! }],
-  };
-}
-
-/**
- * Company slugs the desktop app has paused via per-workspace Off toggles.
- *
- * `HQ_SYNC_SKIP_COMPANIES` is a comma-separated slug list (whitespace tolerated).
- * Empty / missing → no filter. Used by `--companies` fanout and the watch
- * scoped-drain so Sync Now / Auto-sync honor `workspaceSyncEnabled=false`.
- */
-export function resolveSkipCompanies(
-  envValue: string | undefined = process.env.HQ_SYNC_SKIP_COMPANIES,
-): Set<string> {
-  const raw = (envValue ?? "").trim();
-  if (!raw) return new Set();
-  return new Set(
-    raw
-      .split(",")
-      .map((slug) => slug.trim().toLowerCase())
-      .filter((slug) => slug.length > 0 && slug !== "personal"),
-  );
-}
-
-export async function buildFanoutPlan(options: {
-  memberships: Pick<Membership, "companyUid">[];
-  companies: boolean;
-  personal: boolean;
-  skipPersonal: boolean;
-  client: VaultClientSurface;
-  claims: IdentityClaims | null;
-  resolveSkipPersonal: (flag: boolean) => boolean;
-  /** Optional company-slug denylist (desktop per-workspace Off toggles). */
-  skipCompanies?: Set<string>;
-}): Promise<
-  | { status: "setup-needed"; reason: SetupNeededReason }
-  | { status: "plan"; plan: RunnerTarget[]; deferredUnresolved: number }
-> {
-  const skipCompanies = options.skipCompanies ?? new Set<string>();
-  const plan: RunnerTarget[] = [];
-  let deferredUnresolved = 0;
-  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;
-    let entityResolved = false;
-    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;
-      entityResolved = true;
-    } catch (err) {
-      if (err instanceof VaultAuthError) throw err;
-      // A stale membership can outlive its company entity. Do not schedule a
-      // target that the sync leg can only fail to resolve later. Other lookup
-      // failures stay best-effort so a transient discovery blip does not
-      // silently drop an otherwise valid company from this run — unless a
-      // slug denylist is active (see fail-closed / deferred check below).
-      if (
-        err instanceof VaultNotFoundError ||
-        (typeof err === "object" &&
-          err !== null &&
-          "statusCode" in err &&
-          err.statusCode === 404)
-      ) {
-        continue;
-      }
-      // Best-effort — keep UID as the display identifier.
-    }
-    // Desktop Off toggles ship slug denylists. Proven matches (slug or UID)
-    // skip cleanly. When a denylist is active but entity lookup failed and the
-    // UID itself is not listed, we cannot tell paused-by-slug from an enabled
-    // company that blipped — omit from the plan (do not sync ambiguous) and
-    // ask the runner to retry (non-zero) so watch scoped drain cannot publish
-    // without a successful upload pass.
-    if (
-      skipCompanies.has(slug.toLowerCase()) ||
-      skipCompanies.has(m.companyUid.toLowerCase())
-    ) {
-      continue;
-    }
-    if (skipCompanies.size > 0 && !entityResolved) {
-      deferredUnresolved += 1;
-      continue;
-    }
-    plan.push({
-      uid: m.companyUid,
-      slug,
-      ...(name ? { name } : {}),
-      ...(bucketName ? { bucketName } : {}),
-      ...(entityType ? { entityType } : {}),
-      ...(entityStatus ? { entityStatus } : {}),
-    });
-  }
-
-  if (
-    (options.companies || options.personal) &&
-    !options.resolveSkipPersonal(options.skipPersonal)
-  ) {
-    // Self-entity listing. `/entity/by-type/:type` is type-filtered: querying
-    // `person` for an agent JWT returns no agent entity in production.  Query
-    // the caller-scoped agent collection for a machine identity instead, then
-    // require the JWT-bound UID below.  A machine caller must never fall back
-    // to a person entity, which could otherwise select somebody else's vault.
-    const isAgentIdentity = options.claims?.["custom:entityType"] === "agent";
-    const agentSelfUid = options.claims?.["custom:entityUid"] ?? "";
-    const selfEntities = await options.client.entity.listByType(
-      isAgentIdentity ? "agent" : "person",
-    );
-    const pick = isAgentIdentity
-      ? pickAgentSelfEntity(selfEntities, agentSelfUid)
-      : pickCanonicalPersonEntity(selfEntities);
-    if (pick?.bucketName) {
-      plan.push({
-        slug: "personal",
-        uid: pick.uid,
-        bucketName: pick.bucketName,
-        personalMode: true,
-        journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-      });
-    } else if (options.personal) {
-      return { status: "setup-needed", reason: "no-person-entity" };
-    }
-  }
-
-  return { status: "plan", plan, deferredUnresolved };
-}
-
-export function emitFanoutPlan(
-  emit: (event: RunnerEvent) => void,
-  plan: RunnerTarget[],
-): void {
-  emit({ type: "fanout-plan", companies: plan });
-}

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

@@ -1,37 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  rollupAllComplete,
-  type CompanyState,
-} from "./sync-runner-rollup.js";
-
-describe("rollupAllComplete", () => {
-  it("aggregates a very large changed-path set without using it as call arguments", () => {
-    const changedPathCount = 150_000;
-    const changedPaths = Array.from(
-      { length: changedPathCount },
-      (_, index) => `workspace/session-${index}/state.json`,
-    );
-    const state: CompanyState = {
-      company: "personal",
-      status: "complete",
-      filesDownloaded: changedPathCount,
-      bytesDownloaded: 0,
-      filesTombstoned: 0,
-      scopeOrphansRemoved: 0,
-      changedPaths,
-      filesUploaded: 0,
-      bytesUploaded: 0,
-    };
-
-    const rollup = rollupAllComplete(
-      [{ uid: "prs_personal", slug: "personal", personalMode: true }],
-      new Map([["personal", state]]),
-    );
-
-    expect(rollup.changedPaths).toHaveLength(changedPathCount);
-    expect(rollup.changedPaths[0]).toBe("workspace/session-0/state.json");
-    expect(rollup.changedPaths.at(-1)).toBe(
-      `workspace/session-${changedPathCount - 1}/state.json`,
-    );
-  });
-});

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

@@ -1,97 +0,0 @@
-import type { RunnerEvent } from "./sync-runner.js";
-import type { RunnerTarget } from "./sync-runner-planning.js";
-
-export type CompanyStatus = "complete" | "aborted" | "errored" | "transient-network";
-
-export interface CompanyState {
-  company: string;
-  status: CompanyStatus;
-  filesDownloaded: number;
-  bytesDownloaded: number;
-  filesTombstoned: number;
-  scopeOrphansRemoved: number;
-  changedPaths: string[];
-  filesUploaded: number;
-  bytesUploaded: number;
-}
-
-export interface AllCompleteRollup {
-  totalDownloaded: number;
-  totalDownloadedBytes: number;
-  totalTombstoned: number;
-  totalScopeOrphansRemoved: number;
-  totalUploaded: number;
-  totalUploadedBytes: number;
-  changedPaths: string[];
-  needsReindex: boolean;
-  partial: boolean;
-  companies: Extract<RunnerEvent, { type: "all-complete" }>["companies"];
-}
-
-export function createCompanyState(company: string): CompanyState {
-  return {
-    company,
-    status: "errored",
-    filesDownloaded: 0,
-    bytesDownloaded: 0,
-    filesTombstoned: 0,
-    scopeOrphansRemoved: 0,
-    changedPaths: [],
-    filesUploaded: 0,
-    bytesUploaded: 0,
-  };
-}
-
-export function rollupAllComplete(
-  plan: RunnerTarget[],
-  stateByCompany: Map<string, CompanyState>,
-): AllCompleteRollup {
-  let totalDownloaded = 0;
-  let totalDownloadedBytes = 0;
-  let totalTombstoned = 0;
-  let totalScopeOrphansRemoved = 0;
-  let totalUploaded = 0;
-  let totalUploadedBytes = 0;
-  const changedPaths: string[] = [];
-  let partial = false;
-  const companies: AllCompleteRollup["companies"] = [];
-
-  for (const target of plan) {
-    const s = stateByCompany.get(target.slug);
-    if (!s) continue;
-    totalDownloaded += s.filesDownloaded;
-    totalDownloadedBytes += s.bytesDownloaded;
-    totalTombstoned += s.filesTombstoned;
-    totalScopeOrphansRemoved += s.scopeOrphansRemoved;
-    totalUploaded += s.filesUploaded;
-    totalUploadedBytes += s.bytesUploaded;
-    for (const changedPath of s.changedPaths) {
-      changedPaths.push(changedPath);
-    }
-    if (s.status !== "complete") partial = true;
-    companies.push({
-      company: s.company,
-      status: s.status,
-      filesDownloaded: s.filesDownloaded,
-      bytesDownloaded: s.bytesDownloaded,
-      filesUploaded: s.filesUploaded,
-      bytesUploaded: s.bytesUploaded,
-    });
-  }
-
-  return {
-    totalDownloaded,
-    totalDownloadedBytes,
-    totalTombstoned,
-    totalScopeOrphansRemoved,
-    totalUploaded,
-    totalUploadedBytes,
-    changedPaths,
-    needsReindex:
-      totalDownloaded > 0 ||
-      totalTombstoned > 0 ||
-      totalScopeOrphansRemoved > 0,
-    partial,
-    companies,
-  };
-}

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

@@ -1,15 +0,0 @@
-export async function emitTelemetry(options: {
-  collectTelemetry?: () => Promise<void>;
-  defaultCollectTelemetry: () => Promise<void>;
-  onError?: (err: unknown) => void;
-}): Promise<void> {
-  const telemetryFn =
-    options.collectTelemetry ?? options.defaultCollectTelemetry;
-  await telemetryFn().catch((err) => {
-    try {
-      options.onError?.(err);
-    } catch {
-      /* diagnostics must never affect sync */
-    }
-  });
-}