@indigoai-us/hq-cloud 5.1.0 → 5.1.8

package/src/cli/share.ts

@@ -0,0 +1,212 @@
+/**
+ * `hq share` command — selective push to entity vault (VLT-5 US-002).
+ *
+ * Broadcasts local file(s) to the company's S3 vault bucket.
+ * Refuses to overwrite a newer remote version without prompting.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { VaultServiceConfig } from "../types.js";
+import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
+import { uploadFile, headRemoteFile } from "../s3.js";
+import { readJournal, writeJournal, hashFile, updateEntry } from "../journal.js";
+import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
+import { resolveConflict } from "./conflict.js";
+import type { ConflictStrategy } from "./conflict.js";
+
+export interface ShareOptions {
+  /** Path(s) to share (files or directories) */
+  paths: string[];
+  /** Company slug or UID (defaults to active company from config) */
+  company?: string;
+  /** Optional message attached to journal entries */
+  message?: string;
+  /** Non-interactive conflict strategy */
+  onConflict?: ConflictStrategy;
+  /** Vault service config */
+  vaultConfig: VaultServiceConfig;
+  /** HQ root directory */
+  hqRoot: string;
+}
+
+export interface ShareResult {
+  filesUploaded: number;
+  bytesUploaded: number;
+  filesSkipped: number;
+  aborted: boolean;
+}
+
+/**
+ * Share local file(s) to the entity vault.
+ */
+export async function share(options: ShareOptions): Promise<ShareResult> {
+  const { paths, company, message, onConflict, vaultConfig, hqRoot } = options;
+
+  // Resolve company — slug, UID, or from active config
+  const companyRef = company ?? resolveActiveCompany(hqRoot);
+  if (!companyRef) {
+    throw new Error(
+      "No company specified and no active company found. " +
+      "Use --company <slug> or set up .hq/config.json.",
+    );
+  }
+
+  // Resolve entity context (handles STS vending + caching)
+  let ctx = await resolveEntityContext(companyRef, vaultConfig);
+  const shouldSync = createIgnoreFilter(hqRoot);
+  const journal = readJournal(ctx.slug);
+
+  let filesUploaded = 0;
+  let bytesUploaded = 0;
+  let filesSkipped = 0;
+
+  // Collect all files to share
+  const filesToShare = collectFiles(paths, hqRoot, shouldSync);
+
+  for (const { absolutePath, relativePath } of filesToShare) {
+    if (!isWithinSizeLimit(absolutePath)) {
+      console.error(`  Skipped (too large): ${relativePath}`);
+      filesSkipped++;
+      continue;
+    }
+
+    // Auto-refresh context if credentials expiring
+    if (isExpiringSoon(ctx.expiresAt)) {
+      ctx = await refreshEntityContext(companyRef, vaultConfig);
+    }
+
+    // Check for remote conflict — refuse to overwrite newer remote version
+    const remoteMeta = await headRemoteFile(ctx, relativePath);
+    if (remoteMeta) {
+      const journalEntry = journal.files[relativePath];
+      const localHash = hashFile(absolutePath);
+
+      // If remote has changed since our last sync, it's a conflict
+      if (journalEntry && journalEntry.hash !== localHash) {
+        // Local has changes — check if remote also changed
+        const resolution = await resolveConflict(
+          {
+            path: relativePath,
+            localHash,
+            remoteModified: remoteMeta.lastModified,
+            direction: "push",
+          },
+          onConflict,
+        );
+
+        if (resolution === "abort") {
+          return { filesUploaded, bytesUploaded, filesSkipped, aborted: true };
+        }
+        if (resolution === "keep" || resolution === "skip") {
+          filesSkipped++;
+          continue;
+        }
+        // "overwrite" falls through to upload
+      }
+    }
+
+    // Upload
+    try {
+      const stat = fs.statSync(absolutePath);
+      const hash = hashFile(absolutePath);
+
+      await uploadFile(ctx, absolutePath, relativePath);
+
+      // Update journal with optional message
+      updateEntry(journal, relativePath, hash, stat.size, "up");
+      if (message) {
+        journal.files[relativePath] = {
+          ...journal.files[relativePath],
+          message,
+        } as typeof journal.files[string] & { message: string };
+      }
+
+      filesUploaded++;
+      bytesUploaded += stat.size;
+      console.log(`  ✓ ${relativePath}`);
+    } catch (err) {
+      console.error(
+        `  ✗ ${relativePath} — ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+
+  writeJournal(ctx.slug, journal);
+
+  return { filesUploaded, bytesUploaded, filesSkipped, aborted: false };
+}
+
+/**
+ * Resolve active company from .hq/config.json or parent directory chain.
+ */
+function resolveActiveCompany(hqRoot: string): string | undefined {
+  const configPath = path.join(hqRoot, ".hq", "config.json");
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      return config.activeCompany ?? config.companySlug;
+    } catch {
+      // Ignore parse errors
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Collect files from paths (expanding directories recursively).
+ */
+function collectFiles(
+  paths: string[],
+  hqRoot: string,
+  filter: (p: string) => boolean,
+): { absolutePath: string; relativePath: string }[] {
+  const results: { absolutePath: string; relativePath: string }[] = [];
+
+  for (const p of paths) {
+    const absolutePath = path.isAbsolute(p) ? p : path.resolve(hqRoot, p);
+
+    if (!fs.existsSync(absolutePath)) {
+      console.error(`  Warning: ${p} does not exist, skipping.`);
+      continue;
+    }
+
+    const stat = fs.statSync(absolutePath);
+    if (stat.isDirectory()) {
+      results.push(...walkDir(absolutePath, hqRoot, filter));
+    } else if (stat.isFile()) {
+      const relativePath = path.relative(hqRoot, absolutePath);
+      if (filter(absolutePath)) {
+        results.push({ absolutePath, relativePath });
+      }
+    }
+  }
+
+  return results;
+}
+
+function walkDir(
+  dir: string,
+  root: string,
+  filter: (p: string) => boolean,
+): { absolutePath: string; relativePath: string }[] {
+  const results: { absolutePath: string; relativePath: string }[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(dir, entry.name);
+    if (!filter(absolutePath)) continue;
+
+    if (entry.isDirectory()) {
+      results.push(...walkDir(absolutePath, root, filter));
+    } else if (entry.isFile()) {
+      results.push({
+        absolutePath,
+        relativePath: path.relative(root, absolutePath),
+      });
+    }
+  }
+
+  return results;
+}

package/src/cli/sync.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Unit tests for hq sync command (VLT-5 US-002).
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { clearContextCache } from "../context.js";
+import type { VaultServiceConfig } from "../types.js";
+
+// Mock s3 module at the top level
+vi.mock("../s3.js", async () => {
+  const { vi: innerVi } = await import("vitest");
+  const innerFs = await import("fs");
+  const innerPath = await import("path");
+
+  const remoteFiles = [
+    { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"abc123"' },
+    { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
+  ];
+
+  return {
+    uploadFile: innerVi.fn().mockResolvedValue(undefined),
+    downloadFile: innerVi.fn().mockImplementation(async (_ctx: unknown, _key: string, localPath: string) => {
+      const dir = innerPath.dirname(localPath);
+      if (!innerFs.existsSync(dir)) innerFs.mkdirSync(dir, { recursive: true });
+      innerFs.writeFileSync(localPath, "mock file content");
+    }),
+    listRemoteFiles: innerVi.fn().mockResolvedValue(remoteFiles),
+    deleteRemoteFile: innerVi.fn().mockResolvedValue(undefined),
+    headRemoteFile: innerVi.fn().mockResolvedValue(null),
+  };
+});
+
+import { sync } from "./sync.js";
+
+const mockConfig: VaultServiceConfig = {
+  apiUrl: "https://vault-api.test",
+  authToken: "test-jwt-token",
+  region: "us-east-1",
+};
+
+const mockEntity = {
+  uid: "cmp_01ABCDEF",
+  slug: "acme",
+  bucketName: "hq-vault-acme-123",
+  status: "active",
+};
+
+const mockVendResponse = {
+  credentials: {
+    accessKeyId: "ASIA_TEST_KEY",
+    secretAccessKey: "test-secret",
+    sessionToken: "test-session-token",
+    expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+  },
+  expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+};
+
+function setupFetchMock() {
+  const fetchMock = vi.fn().mockImplementation(async (url: string) => {
+    const urlStr = String(url);
+    if (urlStr.includes("/entity/by-slug/")) {
+      return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+    }
+    if (urlStr.includes("/sts/vend")) {
+      return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+    }
+    return { ok: false, status: 404, text: async () => "Not found" };
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("sync", () => {
+  let tmpDir: string;
+  let stateDir: string;
+  let journalPath: string;
+
+  beforeEach(() => {
+    clearContextCache();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sync-test-"));
+    // Journal moved to ~/.hq/sync-journal.{slug}.json (ADR-0001 Phase 5).
+    // Redirect to a tmp dir via HQ_STATE_DIR so the test doesn't pollute the
+    // user's real ~/.hq. mockEntity.slug is "acme".
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    journalPath = path.join(stateDir, "sync-journal.acme.json");
+    setupFetchMock();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
+  });
+
+  it("downloads remote files that don't exist locally", async () => {
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesDownloaded).toBe(2);
+    expect(result.aborted).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, "docs", "handoff.md"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, "knowledge", "readme.md"))).toBe(true);
+  });
+
+  it("throws when no company specified and no active company", async () => {
+    await expect(
+      sync({ vaultConfig: mockConfig, hqRoot: tmpDir }),
+    ).rejects.toThrow(/No company specified/);
+  });
+
+  it("uses active company from .hq/config.json", async () => {
+    fs.mkdirSync(path.join(tmpDir, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, ".hq", "config.json"),
+      JSON.stringify({ activeCompany: "acme" }),
+    );
+
+    const result = await sync({ vaultConfig: mockConfig, hqRoot: tmpDir });
+    expect(result.filesDownloaded).toBe(2);
+  });
+
+  it("detects conflicts with local changes and keeps local on --on-conflict keep", async () => {
+    fs.mkdirSync(path.join(tmpDir, "docs"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "docs", "handoff.md"), "local version");
+
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "docs/handoff.md": {
+            hash: "old-hash-from-last-sync",
+            size: 20,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.conflicts).toBe(1);
+    expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
+    expect(fs.readFileSync(path.join(tmpDir, "docs", "handoff.md"), "utf-8")).toBe("local version");
+  });
+
+  it("aborts on --on-conflict abort", async () => {
+    fs.mkdirSync(path.join(tmpDir, "docs"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "docs", "handoff.md"), "local version");
+
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "docs/handoff.md": {
+            hash: "old-hash",
+            size: 20,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "abort",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.aborted).toBe(true);
+  });
+
+  it("overwrites local on --on-conflict overwrite", async () => {
+    fs.mkdirSync(path.join(tmpDir, "docs"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "docs", "handoff.md"), "local version");
+
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "docs/handoff.md": {
+            hash: "old-hash",
+            size: 20,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "overwrite",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.conflicts).toBe(1);
+    expect(result.filesDownloaded).toBeGreaterThanOrEqual(1);
+    // File should be overwritten with mock content
+    expect(fs.readFileSync(path.join(tmpDir, "docs", "handoff.md"), "utf-8")).toBe("mock file content");
+  });
+});

package/src/cli/sync.ts

@@ -0,0 +1,225 @@
+/**
+ * `hq sync` command — pull everything allowed from entity vault (VLT-5 US-002).
+ *
+ * Pulls all files the caller's STS session policy permits.
+ * Never auto-overwrites local changes — prompts on conflict.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { VaultServiceConfig } from "../types.js";
+import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
+import { downloadFile, listRemoteFiles } from "../s3.js";
+import { readJournal, writeJournal, hashFile, updateEntry, getEntry } from "../journal.js";
+import { createIgnoreFilter } from "../ignore.js";
+import { resolveConflict } from "./conflict.js";
+import type { ConflictStrategy } from "./conflict.js";
+
+/**
+ * Per-file events emitted by `sync()` as it progresses.
+ *
+ * When `SyncOptions.onEvent` is set, these events are delivered to the caller
+ * in place of the default human-readable `console.log` / `console.error`
+ * output. This is the seam that lets `hq-sync-runner` stream ndjson to the
+ * AppBar menubar without the engine knowing anything about ndjson (ADR-0001).
+ *
+ * The human CLI (`hq sync`) leaves `onEvent` undefined and falls through to
+ * `defaultConsoleLogger` below, which preserves the existing tty output.
+ */
+export type SyncProgressEvent =
+  | { type: "progress"; path: string; bytes: number; message?: string }
+  | { type: "error"; path: string; message: string };
+
+export interface SyncOptions {
+  /** Company slug or UID (defaults to active company from config) */
+  company?: string;
+  /** Non-interactive conflict strategy */
+  onConflict?: ConflictStrategy;
+  /** Vault service config */
+  vaultConfig: VaultServiceConfig;
+  /** HQ root directory */
+  hqRoot: string;
+  /**
+   * Per-file event callback. When present, suppresses the default
+   * `console.log`/`console.error` human output — the caller is expected to
+   * render events themselves (e.g. emit ndjson to stdout). When absent, the
+   * default human logger is used. See `SyncProgressEvent`.
+   */
+  onEvent?: (event: SyncProgressEvent) => void;
+}
+
+export interface SyncResult {
+  filesDownloaded: number;
+  bytesDownloaded: number;
+  filesSkipped: number;
+  conflicts: number;
+  aborted: boolean;
+}
+
+/**
+ * Sync (pull) all allowed files from the entity vault.
+ */
+export async function sync(options: SyncOptions): Promise<SyncResult> {
+  const { company, onConflict, vaultConfig, hqRoot } = options;
+  const emit = options.onEvent ?? defaultConsoleLogger;
+
+  // Resolve company
+  const companyRef = company ?? resolveActiveCompany(hqRoot);
+  if (!companyRef) {
+    throw new Error(
+      "No company specified and no active company found. " +
+      "Use --company <slug> or set up .hq/config.json.",
+    );
+  }
+
+  // Resolve entity context
+  let ctx = await resolveEntityContext(companyRef, vaultConfig);
+  const shouldSync = createIgnoreFilter(hqRoot);
+  const journal = readJournal(ctx.slug);
+
+  let filesDownloaded = 0;
+  let bytesDownloaded = 0;
+  let filesSkipped = 0;
+  let conflicts = 0;
+
+  // List all remote files (IAM session policy filters at the AWS layer)
+  const remoteFiles = await listRemoteFiles(ctx);
+
+  for (const remoteFile of remoteFiles) {
+    const localPath = path.join(hqRoot, remoteFile.key);
+
+    // Apply ignore rules
+    if (!shouldSync(localPath)) {
+      filesSkipped++;
+      continue;
+    }
+
+    // Auto-refresh context if credentials expiring
+    if (isExpiringSoon(ctx.expiresAt)) {
+      ctx = await refreshEntityContext(companyRef, vaultConfig);
+    }
+
+    // Check for local conflict
+    const journalEntry = getEntry(journal, remoteFile.key);
+
+    if (fs.existsSync(localPath)) {
+      const localHash = hashFile(localPath);
+
+      // If local file has changed since last sync, it's a conflict
+      if (journalEntry && journalEntry.hash !== localHash) {
+        conflicts++;
+
+        const resolution = await resolveConflict(
+          {
+            path: remoteFile.key,
+            localHash,
+            remoteModified: remoteFile.lastModified,
+            localModified: fs.statSync(localPath).mtime,
+            direction: "pull",
+          },
+          onConflict,
+        );
+
+        if (resolution === "abort") {
+          writeJournal(ctx.slug, journal);
+          return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: true };
+        }
+        if (resolution === "keep" || resolution === "skip") {
+          filesSkipped++;
+          continue;
+        }
+        // "overwrite" falls through to download
+      } else if (journalEntry && journalEntry.hash === localHash) {
+        // Local unchanged since last sync — check if remote changed
+        // by comparing etag/timestamp
+        const lastSyncTime = new Date(journalEntry.syncedAt).getTime();
+        const remoteModTime = remoteFile.lastModified.getTime();
+        if (remoteModTime <= lastSyncTime) {
+          // Remote hasn't changed either — skip
+          filesSkipped++;
+          continue;
+        }
+      }
+    }
+
+    // Download
+    try {
+      await downloadFile(ctx, remoteFile.key, localPath);
+
+      const hash = hashFile(localPath);
+      const stat = fs.statSync(localPath);
+      updateEntry(journal, remoteFile.key, hash, stat.size, "down");
+
+      // Attach message from journal entry if present
+      const remoteJournalMessage = (journalEntry as { message?: string } | undefined)?.message;
+      emit({
+        type: "progress",
+        path: remoteFile.key,
+        bytes: stat.size,
+        ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
+      });
+
+      filesDownloaded++;
+      bytesDownloaded += stat.size;
+    } catch (err) {
+      // STS session policy may deny access to some paths — this is expected
+      // for guest members with allowedPrefixes
+      if (isAccessDenied(err)) {
+        filesSkipped++;
+      } else {
+        emit({
+          type: "error",
+          path: remoteFile.key,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  writeJournal(ctx.slug, journal);
+
+  return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: false };
+}
+
+/**
+ * Resolve active company from .hq/config.json.
+ */
+function resolveActiveCompany(hqRoot: string): string | undefined {
+  const configPath = path.join(hqRoot, ".hq", "config.json");
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      return config.activeCompany ?? config.companySlug;
+    } catch {
+      // Ignore parse errors
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Check if an error is an S3 access denied (expected for filtered guests).
+ */
+function isAccessDenied(err: unknown): boolean {
+  if (err && typeof err === "object" && "name" in err) {
+    return err.name === "AccessDenied" || err.name === "Forbidden";
+  }
+  return false;
+}
+
+/**
+ * Default human-readable event rendering. Preserves the exact output format
+ * that `hq sync` emitted before SyncProgressEvent was introduced, so callers
+ * without an `onEvent` see no behavioral change.
+ */
+function defaultConsoleLogger(event: SyncProgressEvent): void {
+  if (event.type === "progress") {
+    if (event.message) {
+      console.log(`  ✓ ${event.path} — "${event.message}"`);
+    } else {
+      console.log(`  ✓ ${event.path}`);
+    }
+  } else if (event.type === "error") {
+    console.error(`  ✗ ${event.path} — ${event.message}`);
+  }
+}