@indigoai-us/hq-cloud 5.1.0 → 5.1.8

package/src/bin/sync-runner.ts

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * hq-sync-runner — machine-targeted entrypoint for `@indigoai-us/hq-cloud`
+ * (ADR-0001).
+ *
+ * The AppBar Sync menubar (Tauri + Rust) spawns this binary as a subprocess
+ * and reads ndjson events from stdout. The protocol is intentionally narrow
+ * and versioned-by-shape, not by tooling — no chalk, no colors, no human
+ * prose. If you want to invoke sync as a human, use `hq sync` in
+ * `@indigoai-us/hq-cli`.
+ *
+ * Flags:
+ *   --companies               Fan out across every membership the caller has
+ *   --company <slug-or-uid>   Sync a single company (alternative to --companies)
+ *   --on-conflict <strategy>  abort | overwrite | keep (default: abort)
+ *   --hq-root <path>          Local HQ directory (default: $HOME/hq)
+ *   --json                    Ignored — ndjson on stdout is the default and
+ *                             only output mode. Accepted for symmetry with the
+ *                             AppBar's argv in case someone passes it.
+ *
+ * Event protocol (one JSON object per line on stdout):
+ *   setup-needed   — caller signed in but has no person entity yet
+ *   auth-error     — no valid token available (interactive login disabled)
+ *   fanout-plan    — list of companies we're about to sync
+ *   progress       — per-file download
+ *   error          — per-file or per-company error
+ *   complete       — per-company summary
+ *   all-complete   — aggregate summary after fanout
+ *
+ * Exit code:
+ *   0 — event stream describes the outcome (including setup-needed)
+ *   1 — argv parse error or unrecoverable pre-sync failure
+ */
+
+import * as os from "os";
+import * as path from "path";
+import * as fs from "fs";
+import { fileURLToPath } from "url";
+import {
+  getValidAccessToken,
+  VaultClient,
+  VaultAuthError,
+  type CognitoAuthConfig,
+  type VaultServiceConfig,
+  type Membership,
+  type EntityInfo,
+} from "../index.js";
+import { sync as defaultSync } from "../cli/sync.js";
+import type {
+  SyncOptions,
+  SyncResult,
+  SyncProgressEvent,
+} from "../cli/sync.js";
+import type { ConflictStrategy } from "../cli/conflict.js";
+
+// ---------------------------------------------------------------------------
+// Defaults — mirror `hq-cli/src/utils/cognito-session.ts`. Inlined (not
+// imported) to avoid a circular dep between hq-cli and hq-cloud. If these
+// drift, the symptom is "runner talks to a different stage than hq sync"
+// — keep both files lined up.
+// ---------------------------------------------------------------------------
+
+const DEFAULT_COGNITO: CognitoAuthConfig = {
+  region: process.env.AWS_REGION ?? "us-east-1",
+  userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "hq-vault-dev",
+  clientId: process.env.HQ_COGNITO_CLIENT_ID ?? "4mmujmjq3srakdueg656b9m0mp",
+  port: process.env.HQ_COGNITO_CALLBACK_PORT
+    ? Number(process.env.HQ_COGNITO_CALLBACK_PORT)
+    : 8765,
+};
+
+const DEFAULT_VAULT_API_URL =
+  process.env.HQ_VAULT_API_URL ??
+  "https://tqdwdqxv75.execute-api.us-east-1.amazonaws.com";
+
+const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
+
+// ---------------------------------------------------------------------------
+// Event protocol
+// ---------------------------------------------------------------------------
+
+/**
+ * Every event emitted on stdout. The `company` field is present on every
+ * event except `setup-needed` / `auth-error` / `fanout-plan` / `all-complete`
+ * (which describe the whole run) — consumers should treat its absence as
+ * "meta-event, not tied to a specific company".
+ */
+export type RunnerEvent =
+  | { type: "setup-needed" }
+  | { type: "auth-error"; message: string }
+  | {
+      type: "fanout-plan";
+      companies: Array<{ uid: string; slug: string }>;
+    }
+  | ({ type: "progress"; company: string } & Omit<Extract<SyncProgressEvent, { type: "progress" }>, "type">)
+  | ({ type: "error"; company?: string } & Omit<Extract<SyncProgressEvent, { type: "error" }>, "type">)
+  | ({ type: "complete"; company: string } & SyncResult)
+  | {
+      type: "all-complete";
+      companiesAttempted: number;
+      filesDownloaded: number;
+      bytesDownloaded: number;
+      errors: Array<{ company: string; message: string }>;
+    };
+
+/**
+ * The narrow VaultClient surface the runner actually uses. Declared here (not
+ * `Pick<VaultClient, ...>`) because `Pick` preserves the *entire* `entity`
+ * accessor object — but the runner only needs `entity.get`, and forcing test
+ * stubs to also implement `findBySlug`/`create` would be dishonest about the
+ * real dependency. Keep this interface in sync with the real VaultClient
+ * method signatures (both return types come straight from the SDK).
+ */
+export interface VaultClientSurface {
+  listMyMemberships: () => Promise<Membership[]>;
+  entity: {
+    get: (uid: string) => Promise<EntityInfo>;
+  };
+}
+
+export interface RunnerDeps {
+  /** Where to write ndjson events. Defaults to `process.stdout`. */
+  stdout?: { write: (chunk: string) => boolean | void };
+  /** Where to write diagnostics. Defaults to `process.stderr`. */
+  stderr?: { write: (chunk: string) => boolean | void };
+  /** Resolve a valid access token. Defaults to `getValidAccessToken` non-interactive. */
+  getAccessToken?: () => Promise<string>;
+  /**
+   * Produce a VaultClient-like object. Defaults to `new VaultClient(config)`.
+   * Tests inject a stub here — only `listMyMemberships` and `entity.get` are
+   * called by the runner, so stubs only need to implement those.
+   */
+  createVaultClient?: (config: VaultServiceConfig) => VaultClientSurface;
+  /** Sync function. Defaults to `cli/sync.sync`. */
+  sync?: (options: SyncOptions) => Promise<SyncResult>;
+}
+
+// ---------------------------------------------------------------------------
+// argv parser — intentionally minimal (no commander/yargs dep)
+// ---------------------------------------------------------------------------
+
+interface ParsedArgs {
+  companies: boolean;
+  company?: string;
+  onConflict: ConflictStrategy;
+  hqRoot: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | { error: string } {
+  let companies = false;
+  let company: string | undefined;
+  let onConflict: ConflictStrategy = "abort";
+  let hqRoot = DEFAULT_HQ_ROOT;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--companies":
+        companies = true;
+        break;
+      case "--company":
+        company = argv[++i];
+        if (!company) return { error: "--company requires a value" };
+        break;
+      case "--on-conflict": {
+        const val = argv[++i];
+        if (val !== "abort" && val !== "overwrite" && val !== "keep") {
+          return {
+            error: `--on-conflict must be one of abort|overwrite|keep, got: ${val ?? "(missing)"}`,
+          };
+        }
+        onConflict = val;
+        break;
+      }
+      case "--hq-root":
+        hqRoot = argv[++i];
+        if (!hqRoot) return { error: "--hq-root requires a value" };
+        break;
+      case "--json":
+        // Accepted but ignored — ndjson is the only output mode.
+        break;
+      default:
+        return { error: `Unknown argument: ${arg}` };
+    }
+  }
+
+  if (companies && company) {
+    return { error: "Pass --companies OR --company <slug>, not both" };
+  }
+  if (!companies && !company) {
+    return { error: "Pass --companies or --company <slug>" };
+  }
+
+  return { companies, company, onConflict, hqRoot };
+}
+
+// ---------------------------------------------------------------------------
+// runRunner — testable entrypoint
+// ---------------------------------------------------------------------------
+
+export async function runRunner(
+  argv: string[],
+  deps: RunnerDeps = {},
+): Promise<number> {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+
+  const emit = (event: RunnerEvent): void => {
+    stdout.write(`${JSON.stringify(event)}\n`);
+  };
+
+  // ---- argv -------------------------------------------------------------
+  const parsed = parseArgs(argv);
+  if ("error" in parsed) {
+    stderr.write(`hq-sync-runner: ${parsed.error}\n`);
+    return 1;
+  }
+
+  // ---- auth -------------------------------------------------------------
+  let accessToken: string;
+  try {
+    const getAccessToken =
+      deps.getAccessToken ??
+      (() => getValidAccessToken(DEFAULT_COGNITO, { interactive: false }));
+    accessToken = await getAccessToken();
+  } catch (err) {
+    emit({
+      type: "auth-error",
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return 0;
+  }
+
+  // ---- vault client -----------------------------------------------------
+  const vaultConfig: VaultServiceConfig = {
+    apiUrl: DEFAULT_VAULT_API_URL,
+    authToken: accessToken,
+    region: DEFAULT_COGNITO.region,
+  };
+  const client =
+    deps.createVaultClient?.(vaultConfig) ?? new VaultClient(vaultConfig);
+
+  // ---- resolve targets --------------------------------------------------
+  let memberships: Pick<Membership, "companyUid">[];
+  try {
+    if (parsed.companies) {
+      memberships = await client.listMyMemberships();
+      if (memberships.length === 0) {
+        emit({ type: "setup-needed" });
+        return 0;
+      }
+    } else {
+      // Single-company mode: fabricate a minimal membership so the fanout
+      // loop below treats it uniformly. We don't need to hit
+      // /membership/me — the caller already told us which company.
+      memberships = [{ companyUid: parsed.company! }];
+    }
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      emit({
+        type: "auth-error",
+        message: err.message,
+      });
+      return 0;
+    }
+    // Any other failure is unrecoverable — surface as an error event and
+    // exit non-zero so the spawner knows the runner didn't get far enough
+    // to emit a useful protocol stream.
+    emit({
+      type: "error",
+      message: err instanceof Error ? err.message : String(err),
+      path: "(discovery)",
+    });
+    return 1;
+  }
+
+  // ---- resolve slugs for the fanout plan --------------------------------
+  // The menubar wants "Syncing indigo" in its UI, not the raw cmp_* ULID.
+  // If the entity fetch fails for some row (entity deleted, scoping issue),
+  // degrade to using the UID as the slug rather than aborting the run.
+  const plan: Array<{ uid: string; slug: string }> = [];
+  for (const m of memberships) {
+    let slug = m.companyUid;
+    try {
+      const info = await client.entity.get(m.companyUid);
+      slug = info.slug || m.companyUid;
+    } catch {
+      // Best-effort — keep UID as the display identifier.
+    }
+    plan.push({ uid: m.companyUid, slug });
+  }
+  emit({ type: "fanout-plan", companies: plan });
+
+  // ---- fanout -----------------------------------------------------------
+  const syncFn = deps.sync ?? defaultSync;
+  let totalFiles = 0;
+  let totalBytes = 0;
+  const errors: Array<{ company: string; message: string }> = [];
+
+  for (const target of plan) {
+    const companyLabel = target.slug;
+    try {
+      const result = await syncFn({
+        company: target.uid,
+        vaultConfig,
+        hqRoot: parsed.hqRoot,
+        onConflict: parsed.onConflict,
+        onEvent: (event) => {
+          // Tag per-file events with the company they belong to so the
+          // menubar can route them to the right company's progress bar.
+          if (event.type === "progress") {
+            emit({
+              type: "progress",
+              company: companyLabel,
+              path: event.path,
+              bytes: event.bytes,
+              ...(event.message ? { message: event.message } : {}),
+            });
+          } else {
+            emit({
+              type: "error",
+              company: companyLabel,
+              path: event.path,
+              message: event.message,
+            });
+          }
+        },
+      });
+      emit({ type: "complete", company: companyLabel, ...result });
+      totalFiles += result.filesDownloaded;
+      totalBytes += result.bytesDownloaded;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ company: companyLabel, message });
+      emit({
+        type: "error",
+        company: companyLabel,
+        path: "(company)",
+        message,
+      });
+      // Continue — one company's failure shouldn't abort the whole fanout.
+    }
+  }
+
+  emit({
+    type: "all-complete",
+    companiesAttempted: plan.length,
+    filesDownloaded: totalFiles,
+    bytesDownloaded: totalBytes,
+    errors,
+  });
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint — only runs when invoked directly, not when imported for tests
+// ---------------------------------------------------------------------------
+
+// Detect whether this module is the entry point. The obvious check
+// (`import.meta.url === file://${argv[1]}`) breaks for every real-world
+// install shape: npm-link'd binaries, global installs via Homebrew, and
+// pnpm's `node_modules/.bin` shims all leave `process.argv[1]` pointing
+// at a symlink named `hq-sync-runner` (no `.js` suffix) while
+// `import.meta.url` always resolves to the underlying `sync-runner.js`.
+//
+// Resolve both sides through realpath before comparing — that's the only
+// way to handle all symlink layouts without false negatives. If realpath
+// fails (argv[1] gone, permissions), fall through to `false` so we
+// don't run twice when imported as a library.
+const isDirectInvocation = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    const modulePath = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argvPath = fs.realpathSync(process.argv[1]);
+    return modulePath === argvPath;
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirectInvocation) {
+  runRunner(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(
+        `hq-sync-runner: uncaught error — ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`,
+      );
+      process.exit(1);
+    });
+}

package/src/cli/accept.ts

@@ -0,0 +1,97 @@
+/**
+ * `hq accept` command — accept a membership invite (VLT-7 US-003).
+ *
+ * Parses magic links (hq://accept/<token> or raw tokens), resolves the
+ * caller's identity from Cognito, and calls VaultClient.acceptInvite().
+ */
+
+import type { VaultServiceConfig } from "../types.js";
+import {
+  VaultClient,
+  VaultAuthError,
+  VaultNotFoundError,
+  VaultConflictError,
+  VaultPermissionDeniedError,
+} from "../vault-client.js";
+import type { Membership } from "../vault-client.js";
+
+export interface AcceptOptions {
+  /** Raw token or magic link (hq://accept/<token>) */
+  tokenOrLink: string;
+  /** Caller's person UID (from Cognito) */
+  callerUid: string;
+  /** Vault service config */
+  vaultConfig: VaultServiceConfig;
+}
+
+export interface AcceptResult {
+  membership: Membership;
+  companySlug?: string;
+}
+
+/**
+ * Parse a magic link or raw token into the raw invite token.
+ */
+export function parseToken(tokenOrLink: string): string {
+  const trimmed = tokenOrLink.trim();
+
+  // hq://accept/<token>
+  if (trimmed.startsWith("hq://accept/")) {
+    return trimmed.slice("hq://accept/".length);
+  }
+
+  // https://hq.indigoai.com/accept/<token> (future web route)
+  const httpsPrefix = "https://hq.indigoai.com/accept/";
+  if (trimmed.startsWith(httpsPrefix)) {
+    return trimmed.slice(httpsPrefix.length);
+  }
+
+  // Raw token
+  return trimmed;
+}
+
+/**
+ * Accept a membership invite.
+ */
+export async function accept(options: AcceptOptions): Promise<AcceptResult> {
+  const { tokenOrLink, callerUid, vaultConfig } = options;
+  const token = parseToken(tokenOrLink);
+
+  if (!token) {
+    throw new Error("No invite token provided. Usage: /accept <token-or-magic-link>");
+  }
+
+  const client = new VaultClient(vaultConfig);
+
+  try {
+    const result = await client.acceptInvite(token, callerUid);
+    const membership = result.membership;
+
+    // Try to resolve company slug for display
+    let companySlug: string | undefined;
+    if (membership.companyUid) {
+      try {
+        const entity = await client.entity.get(membership.companyUid);
+        companySlug = entity.slug;
+      } catch {
+        // Non-critical — just display UID instead
+      }
+    }
+
+    return { membership, companySlug };
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      throw new Error("Authentication failed — run `hq auth` to refresh your session");
+    }
+    if (err instanceof VaultConflictError) {
+      throw new Error("This invite was already accepted");
+    }
+    if (err instanceof VaultNotFoundError) {
+      throw new Error("Invite not found or expired");
+    }
+    if (err instanceof VaultPermissionDeniedError) {
+      throw new Error("This invite was for a different person");
+    }
+    throw err;
+  }
+}

package/src/cli/conflict.ts

@@ -0,0 +1,119 @@
+/**
+ * Conflict resolution for hq share/sync (VLT-5 US-002).
+ *
+ * Interactive prompts in terminal mode; deterministic resolution via
+ * --on-conflict flag for worker/skill callers.
+ */
+
+import * as fs from "fs";
+import * as readline from "readline";
+
+export type ConflictStrategy = "overwrite" | "keep" | "abort";
+
+export interface ConflictInfo {
+  path: string;
+  localHash?: string;
+  remoteHash?: string;
+  localModified?: Date;
+  remoteModified?: Date;
+  direction: "push" | "pull";
+}
+
+export type ConflictResolution = "overwrite" | "keep" | "skip" | "diff" | "abort";
+
+/**
+ * Resolve a conflict interactively or via strategy flag.
+ *
+ * In non-interactive mode (strategy provided), returns deterministically:
+ *   overwrite → "overwrite"
+ *   keep → "keep"
+ *   abort → "abort"
+ *
+ * In interactive mode (strategy undefined), prompts the user.
+ */
+export async function resolveConflict(
+  conflict: ConflictInfo,
+  strategy?: ConflictStrategy,
+): Promise<ConflictResolution> {
+  if (strategy) {
+    return strategy === "abort" ? "abort" : strategy;
+  }
+
+  return promptConflict(conflict);
+}
+
+async function promptConflict(conflict: ConflictInfo): Promise<ConflictResolution> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+
+  const direction = conflict.direction === "push"
+    ? "Remote has a newer version"
+    : "Local file has uncommitted edits";
+
+  console.error(`\n  Conflict: ${conflict.path}`);
+  console.error(`  ${direction}`);
+  if (conflict.localModified) {
+    console.error(`  Local modified:  ${conflict.localModified.toISOString()}`);
+  }
+  if (conflict.remoteModified) {
+    console.error(`  Remote modified: ${conflict.remoteModified.toISOString()}`);
+  }
+
+  const options = conflict.direction === "push"
+    ? "[o]verwrite remote / [k]eep remote / [d]iff / [a]bort"
+    : "[o]verwrite local / [k]eep local / [d]iff / [s]kip";
+
+  const answer = await new Promise<string>((resolve) => {
+    rl.question(`  ${options}: `, (ans) => {
+      rl.close();
+      resolve(ans.trim().toLowerCase());
+    });
+  });
+
+  switch (answer) {
+    case "o":
+    case "overwrite":
+      return "overwrite";
+    case "k":
+    case "keep":
+      return "keep";
+    case "d":
+    case "diff":
+      return "diff";
+    case "s":
+    case "skip":
+      return "skip";
+    case "a":
+    case "abort":
+      return "abort";
+    default:
+      // Default to keep (safe option)
+      console.error("  Unrecognized choice, keeping current version.");
+      return "keep";
+  }
+}
+
+/**
+ * Show a simple diff between local and remote content.
+ * Returns the content strings for display.
+ */
+export function showDiff(
+  localPath: string,
+  remoteContent: Buffer,
+): void {
+  const localContent = fs.existsSync(localPath)
+    ? fs.readFileSync(localPath, "utf-8")
+    : "(file does not exist locally)";
+  const remoteStr = remoteContent.toString("utf-8");
+
+  console.error("\n--- LOCAL ---");
+  console.error(localContent.slice(0, 2000));
+  if (localContent.length > 2000) console.error("... (truncated)");
+
+  console.error("\n--- REMOTE ---");
+  console.error(remoteStr.slice(0, 2000));
+  if (remoteStr.length > 2000) console.error("... (truncated)");
+  console.error("");
+}

package/src/cli/index.ts

@@ -0,0 +1,25 @@
+/**
+ * hq-cloud CLI entry points.
+ *
+ * Registers `hq share`, `hq sync`, and membership commands.
+ * These are consumed by @indigoai-us/hq-cli or invoked directly.
+ */
+
+export { share } from "./share.js";
+export type { ShareOptions, ShareResult } from "./share.js";
+
+export { sync } from "./sync.js";
+export type { SyncOptions, SyncResult, SyncProgressEvent } from "./sync.js";
+
+export { resolveConflict, showDiff } from "./conflict.js";
+export type { ConflictStrategy, ConflictInfo, ConflictResolution } from "./conflict.js";
+
+// Membership commands (VLT-7)
+export { invite, listInvites, revokeInvite } from "./invite.js";
+export type { InviteOptions, InviteResult, InviteListOptions, InviteRevokeOptions } from "./invite.js";
+
+export { accept, parseToken } from "./accept.js";
+export type { AcceptOptions, AcceptResult } from "./accept.js";
+
+export { promote } from "./promote.js";
+export type { PromoteOptions, PromoteResult } from "./promote.js";