@indigoai-us/hq-cli 5.17.0 → 5.18.1

package/src/commands/sync-mode.ts

@@ -0,0 +1,387 @@
+/**
+ * `hq sync mode <mode>` (US-006) — flip a membership's syncMode for a company.
+ *
+ * Subcommand of the `hq sync` group. Three call shapes:
+ *
+ *   hq sync mode shared|all|custom [--company <slug>]
+ *       Resolves the target membership for the given company (or the cwd's
+ *       active company from `.hq/config.json` if `--company` is omitted) and
+ *       calls `VaultClient.setMembershipSyncConfig`. Prints membershipId +
+ *       previous mode → new mode as a chat audit trail.
+ *
+ *   hq sync mode --show
+ *       No positional. Prints a table of every membership the caller has
+ *       with its company slug, current sync-mode, and last-updated stamp.
+ *
+ *   hq sync mode custom --paths a/,b/  (planned follow-up)
+ *       For the `custom` mode the server requires `customPaths`. This command
+ *       accepts `--paths` as a comma-separated list to forward to the API; if
+ *       omitted on `custom` the server validation will reject.
+ *
+ * Auto-detect of `--company` from cwd: best-effort via the active-company
+ * slug in `<hq-root>/.hq/config.json`. If absent, the caller must pass
+ * `--company` explicitly — there's no cwd-walk to a `companies/<slug>/`
+ * folder in this initial implementation (follow-up US could add it).
+ *
+ * Cross-package note: this command depends on `VaultClient`
+ * (`getMembershipSyncConfig` / `setMembershipSyncConfig`) added in
+ * hq-cloud US-004 (commit 41e5ee1). While that hq-cloud release is
+ * unpublished, hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud`
+ * in package.json — revert that line to `^5.20.0` (or whatever the
+ * published cut is) once US-004 ships to npm.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+  VaultClient,
+  type MembershipSyncConfig,
+  type Membership,
+  type SyncMode,
+} from "@indigoai-us/hq-cloud";
+
+import {
+  DEFAULT_HQ_ROOT,
+  ensureCognitoToken,
+  buildVaultConfig,
+} from "../utils/cognito-session.js";
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+export const LEGAL_SYNC_MODES: readonly SyncMode[] = [
+  "shared",
+  "all",
+  "custom",
+] as const;
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** Subset of VaultClient surface this command exercises (test seam). */
+export interface SyncModeVaultClient {
+  listMyMemberships(): Promise<Membership[]>;
+  getMembershipSyncConfig(membershipId: string): Promise<MembershipSyncConfig>;
+  setMembershipSyncConfig(
+    membershipId: string,
+    partial: { syncMode: SyncMode; customPaths?: string[] },
+  ): Promise<MembershipSyncConfig>;
+  entity: {
+    get(uid: string): Promise<{ uid: string; slug: string; name?: string }>;
+  };
+}
+
+export interface SetSyncModeOptions {
+  /** Validated mode — already known to be a legal SyncMode. */
+  mode: SyncMode;
+  /** Company slug (caller-provided or resolved from cwd). Required. */
+  companySlug: string;
+  /** Required when `mode === "custom"`. Server rejects otherwise. */
+  customPaths?: string[];
+  /** Injected vault client (real impl built from access token by default). */
+  vaultClient: SyncModeVaultClient;
+}
+
+export interface SetSyncModeResult {
+  membershipId: string;
+  companySlug: string;
+  previousMode: SyncMode;
+  newMode: SyncMode;
+  previousWasDefault: boolean;
+  newConfig: MembershipSyncConfig;
+}
+
+export interface ShowSyncModesOptions {
+  vaultClient: SyncModeVaultClient;
+}
+
+export interface ShowSyncModesRow {
+  companySlug: string;
+  companyName?: string;
+  membershipId: string;
+  syncMode: SyncMode;
+  isDefault: boolean;
+  updatedAt?: string;
+}
+
+// ── Pure helpers ────────────────────────────────────────────────────────────
+
+/** Throws a helpful Error if `mode` is not a legal SyncMode. */
+export function validateMode(mode: string): SyncMode {
+  if ((LEGAL_SYNC_MODES as readonly string[]).includes(mode)) {
+    return mode as SyncMode;
+  }
+  throw new Error(
+    `Invalid sync mode '${mode}'. Legal values: ${LEGAL_SYNC_MODES.join(", ")}.`,
+  );
+}
+
+/**
+ * Read the active company slug from `<hq-root>/.hq/config.json`. Returns
+ * undefined when the file is missing or `activeCompany` isn't set. Never
+ * throws — auto-detect is best-effort.
+ */
+export function readActiveCompanySlug(hqRoot: string): string | undefined {
+  const configPath = path.join(hqRoot, ".hq", "config.json");
+  if (!fs.existsSync(configPath)) return undefined;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8")) as {
+      activeCompany?: unknown;
+    };
+    const slug = cfg.activeCompany;
+    return typeof slug === "string" && slug.length > 0 ? slug : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parse `--paths a/,b/c/` into trimmed non-empty entries. */
+export function parseCustomPaths(raw: string | undefined): string[] | undefined {
+  if (!raw) return undefined;
+  const parts = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  return parts.length > 0 ? parts : undefined;
+}
+
+// ── Orchestrators (pure, injectable — driven by tests) ──────────────────────
+
+/**
+ * Resolve a membership by company slug, then PUT the new sync-mode. Returns
+ * the membershipId, the previous mode (read via GET first), and the server's
+ * fresh config (which sets `isDefault: false` once a row exists).
+ */
+export async function setSyncMode(
+  options: SetSyncModeOptions,
+): Promise<SetSyncModeResult> {
+  const { mode, companySlug, customPaths, vaultClient } = options;
+
+  // 1. Find the caller's membership for this company.
+  const memberships = await vaultClient.listMyMemberships();
+  // Resolve slug → uid via entity.get on each membership's companyUid in
+  // parallel. Cheaper than a per-membership lookup loop and matches the
+  // pattern AppBar uses to render its company picker.
+  const enriched = await Promise.all(
+    memberships.map(async (m) => {
+      try {
+        const ent = await vaultClient.entity.get(m.companyUid);
+        return { membership: m, slug: ent.slug, name: ent.name };
+      } catch {
+        return { membership: m, slug: undefined, name: undefined };
+      }
+    }),
+  );
+
+  const match = enriched.find((row) => row.slug === companySlug);
+  if (!match) {
+    const known = enriched
+      .map((r) => r.slug)
+      .filter((s): s is string => !!s)
+      .join(", ");
+    throw new Error(
+      `No membership found for company '${companySlug}'. Memberships visible to you: ${
+        known || "(none)"
+      }.`,
+    );
+  }
+
+  const membershipId = match.membership.membershipKey;
+
+  // 2. Read the current config (server defaults to `shared`/isDefault:true
+  //    when no row exists). We surface this in the audit line.
+  const before = await vaultClient.getMembershipSyncConfig(membershipId);
+
+  // 3. Write the new mode.
+  const after = await vaultClient.setMembershipSyncConfig(membershipId, {
+    syncMode: mode,
+    customPaths,
+  });
+
+  return {
+    membershipId,
+    companySlug,
+    previousMode: before.syncMode,
+    previousWasDefault: before.isDefault,
+    newMode: after.syncMode,
+    newConfig: after,
+  };
+}
+
+/**
+ * Fetch every membership the caller has, resolve company slugs, and look up
+ * each effective sync-config in parallel. Returns rows sorted by slug for
+ * stable table output.
+ */
+export async function showSyncModes(
+  options: ShowSyncModesOptions,
+): Promise<ShowSyncModesRow[]> {
+  const { vaultClient } = options;
+  const memberships = await vaultClient.listMyMemberships();
+  if (memberships.length === 0) return [];
+
+  const rows = await Promise.all(
+    memberships.map(async (m): Promise<ShowSyncModesRow> => {
+      const [config, entity] = await Promise.all([
+        vaultClient.getMembershipSyncConfig(m.membershipKey).catch(
+          (): MembershipSyncConfig => ({
+            membershipId: m.membershipKey,
+            syncMode: "shared",
+            isDefault: true,
+          }),
+        ),
+        vaultClient.entity
+          .get(m.companyUid)
+          .catch(() => ({ uid: m.companyUid, slug: m.companyUid, name: undefined as string | undefined })),
+      ]);
+      return {
+        companySlug: entity.slug,
+        companyName: entity.name,
+        membershipId: m.membershipKey,
+        syncMode: config.syncMode,
+        isDefault: config.isDefault,
+        updatedAt: config.updatedAt,
+      };
+    }),
+  );
+
+  rows.sort((a, b) => a.companySlug.localeCompare(b.companySlug));
+  return rows;
+}
+
+// ── Table rendering (used by CLI action, separable for tests) ──────────────
+
+/**
+ * Render the `--show` table as plain text. No external dep — hq-cli doesn't
+ * use cli-table3, so we hand-format columns to match the existing chalk +
+ * padEnd pattern used by `hq members list`.
+ */
+export function formatShowTable(rows: ShowSyncModesRow[]): string {
+  if (rows.length === 0) {
+    return "No memberships found. Run `hq onboard` or accept an invite first.";
+  }
+  const cols = ["COMPANY", "MODE", "UPDATED", "MEMBERSHIP"];
+  const data = rows.map((r) => [
+    r.companySlug,
+    r.isDefault ? `${r.syncMode} (default)` : r.syncMode,
+    r.updatedAt ?? "—",
+    r.membershipId,
+  ]);
+  const widths = cols.map((c, i) =>
+    Math.max(c.length, ...data.map((row) => row[i].length)),
+  );
+  const renderRow = (row: string[]): string =>
+    row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+  const lines = [
+    chalk.bold(renderRow(cols)),
+    chalk.dim(renderRow(widths.map((w) => "─".repeat(w)))),
+    ...data.map(renderRow),
+  ];
+  return lines.join("\n");
+}
+
+// ── CLI registration ────────────────────────────────────────────────────────
+
+interface SyncModeCliOptions {
+  company?: string;
+  show?: boolean;
+  hqRoot: string;
+  paths?: string;
+}
+
+/**
+ * Wire `hq sync mode` onto an existing `sync` Commander group. The caller
+ * (`src/index.ts`) constructs the `sync` group and calls this after
+ * `registerCloudCommands` so push/pull/status/mode all coexist.
+ */
+export function registerSyncModeCommand(syncCmd: Command): void {
+  syncCmd
+    .command("mode [mode]")
+    .description(
+      "Flip a membership's sync-mode (shared|all|custom), or --show every membership's current mode",
+    )
+    .option(
+      "--company <slug>",
+      "Company slug (defaults to the active company in <hq-root>/.hq/config.json)",
+    )
+    .option(
+      "--show",
+      "Print the current sync-mode for every membership the caller has",
+    )
+    .option(
+      "--paths <csv>",
+      "Comma-separated allowed prefixes (required when mode is 'custom')",
+    )
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(async (modeArg: string | undefined, options: SyncModeCliOptions) => {
+      try {
+        const accessToken = await ensureCognitoToken();
+        const vaultConfig = buildVaultConfig(accessToken);
+        const client = new VaultClient(vaultConfig);
+
+        if (options.show) {
+          if (modeArg !== undefined) {
+            throw new Error(
+              "`--show` is incompatible with a positional <mode>. Pass one or the other.",
+            );
+          }
+          const rows = await showSyncModes({ vaultClient: client });
+          console.log(formatShowTable(rows));
+          return;
+        }
+
+        if (!modeArg) {
+          throw new Error(
+            `Missing <mode>. Usage: hq sync mode <${LEGAL_SYNC_MODES.join(
+              "|",
+            )}> [--company <slug>]   or   hq sync mode --show`,
+          );
+        }
+
+        const mode = validateMode(modeArg);
+        const customPaths = parseCustomPaths(options.paths);
+        const companySlug =
+          options.company ?? readActiveCompanySlug(options.hqRoot);
+        if (!companySlug) {
+          throw new Error(
+            "No company specified. Pass --company <slug> or set activeCompany in <hq-root>/.hq/config.json.",
+          );
+        }
+
+        const result = await setSyncMode({
+          mode,
+          companySlug,
+          customPaths,
+          vaultClient: client,
+        });
+
+        const prevLabel = result.previousWasDefault
+          ? `${result.previousMode} (default)`
+          : result.previousMode;
+        console.log(
+          chalk.green("✓"),
+          `Set sync-mode for ${chalk.bold(result.companySlug)}: ${chalk.dim(prevLabel)} → ${chalk.bold(result.newMode)}`,
+        );
+        console.log(chalk.dim(`  membershipId: ${result.membershipId}`));
+        if (result.newConfig.customPaths && result.newConfig.customPaths.length > 0) {
+          console.log(
+            chalk.dim(`  customPaths:  ${result.newConfig.customPaths.join(", ")}`),
+          );
+        }
+        if (result.newConfig.updatedAt) {
+          console.log(chalk.dim(`  updatedAt:    ${result.newConfig.updatedAt}`));
+        }
+      } catch (err) {
+        console.error(
+          chalk.red("✗ sync mode failed:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}