@indigoai-us/hq-cloud 5.1.0 → 5.1.8

package/src/ignore.ts

@@ -1,42 +1,106 @@
 /**
- * Ignore file parser for .hqsyncignore
- * Uses gitignore-compatible syntax
+ * Ignore-file parser for cloud sync.
+ *
+ * Three layers, evaluated in order (later patterns override earlier ones):
+ *   1. Built-in defaults — things that should *never* sync (VCS, node_modules,
+ *      build artifacts, caches, env files). Cover the common stacks so that a
+ *      first-time sync over a random project folder doesn't try to push
+ *      `target/`, `node_modules/`, or `.next/` to S3.
+ *   2. Repo `.gitignore` at hqRoot — reuses the user's existing exclusions so
+ *      we don't re-list every build directory ourselves. Root-level only; we
+ *      do not recurse like real git.
+ *   3. `.hqignore` (preferred) or `.hqsyncignore` (legacy name) at hqRoot —
+ *      sync-specific overrides. Use `!pattern` to re-include something an
+ *      earlier layer excluded.
  */
 
 import * as fs from "fs";
 import * as path from "path";
 import ignore from "ignore";
 
-// Default patterns that should never sync
+// Patterns that must never sync regardless of project type.
+// Grouped by ecosystem so new stacks are easy to add.
 const DEFAULT_IGNORES = [
+  // VCS + OS
   ".git/",
   ".git",
-  "node_modules/",
-  "dist/",
   ".DS_Store",
   "Thumbs.db",
+
+  // Node / JS
+  "node_modules/",
+  "dist/",
+  "build/",
+  ".next/",
+  ".nuxt/",
+  ".svelte-kit/",
+  ".turbo/",
+  ".parcel-cache/",
+  ".vite/",
+  "coverage/",
+
+  // Rust / Tauri
+  "target/",
+
+  // Python
+  "__pycache__/",
+  "*.pyc",
+  ".pytest_cache/",
+  ".mypy_cache/",
+  ".ruff_cache/",
+  ".venv/",
+  "venv/",
+
+  // Go / JVM / other
+  "vendor/",
+  "out/",
+  "*.class",
+
+  // Generic caches / temp
+  ".cache/",
+  "tmp/",
+  ".tmp/",
+
+  // HQ sync internal state (never round-trip these)
   "*.pid",
   ".hq-sync.pid",
   ".hq-sync-journal.json",
   ".hq-sync-state.json",
   "modules.lock",
+
+  // HQ repos directory (managed separately, not synced)
   "repos/",
+
+  // Secrets / env
   ".env",
   ".env.*",
 ];
 
+function readIgnoreFile(filePath: string): string | null {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
 export function createIgnoreFilter(hqRoot: string): (filePath: string) => boolean {
   const ig = ignore();
 
-  // Add defaults
+  // Layer 1: baseline defaults
   ig.add(DEFAULT_IGNORES);
 
-  // Read .hqsyncignore if it exists
-  const ignorePath = path.join(hqRoot, ".hqsyncignore");
-  if (fs.existsSync(ignorePath)) {
-    const content = fs.readFileSync(ignorePath, "utf-8");
-    ig.add(content);
-  }
+  // Layer 2: repo's .gitignore (common case — covers most build dirs already)
+  const gitignore = readIgnoreFile(path.join(hqRoot, ".gitignore"));
+  if (gitignore) ig.add(gitignore);
+
+  // Layer 3: sync-specific overrides. .hqignore is the documented name;
+  // .hqsyncignore is the legacy name we still honor.
+  const hqignore =
+    readIgnoreFile(path.join(hqRoot, ".hqignore")) ??
+    readIgnoreFile(path.join(hqRoot, ".hqsyncignore"));
+  if (hqignore) ig.add(hqignore);
 
   return (filePath: string): boolean => {
     const relative = path.relative(hqRoot, filePath);

package/src/index.ts

@@ -1,182 +1,110 @@
 /**
  * @indigoai-us/hq-cloud — public API
- * Used by @indigoai-us/hq-cli to manage cloud sync
+ *
+ * VLT-5: Entity-aware sync engine. Operations resolve their target bucket
+ * and credentials from the vault-service entity registry + STS vending.
  */
 
-import * as fs from "fs";
-import * as path from "path";
-import { authenticate, hasCredentials, readCredentials } from "./auth.js";
-import {
-  startDaemon as _startDaemon,
-  stopDaemon as _stopDaemon,
-  isDaemonRunning,
-} from "./daemon.js";
-import { readJournal, writeJournal, hashFile, updateEntry } from "./journal.js";
-import { uploadFile, downloadFile, listRemoteFiles } from "./s3.js";
-import { createIgnoreFilter, isWithinSizeLimit } from "./ignore.js";
-import type { SyncStatus, PushResult, PullResult } from "./types.js";
+export {
+  resolveEntityContext,
+  refreshEntityContext,
+  clearContextCache,
+  isExpiringSoon,
+} from "./context.js";
+
+export {
+  uploadFile,
+  downloadFile,
+  listRemoteFiles,
+  deleteRemoteFile,
+  headRemoteFile,
+} from "./s3.js";
+
+export type { RemoteFile } from "./s3.js";
+
+export {
+  readJournal,
+  writeJournal,
+  hashFile,
+  updateEntry,
+  getEntry,
+  removeEntry,
+  getJournalPath,
+} from "./journal.js";
 
-export type { SyncStatus, PushResult, PullResult } from "./types.js";
+export {
+  createIgnoreFilter,
+  isWithinSizeLimit,
+} from "./ignore.js";
 
-// Cognito identity helpers — used by `hq auth refresh` and any consumer
-// that needs a valid HQ access token (deploy skill, onboarding, etc.).
+// Cognito browser-OAuth (VLT-9)
 export {
   browserLogin,
   refreshTokens,
-  getValidAccessToken,
   loadCachedTokens,
   saveCachedTokens,
   clearCachedTokens,
   isExpiring,
+  getValidAccessToken,
   CognitoAuthError,
 } from "./cognito-auth.js";
 export type { CognitoAuthConfig, CognitoTokens } from "./cognito-auth.js";
 
-/**
- * Initialize cloud sync — authenticate and provision bucket
- */
-export async function initSync(hqRoot: string): Promise<void> {
-  if (hasCredentials()) {
-    console.log("  Already authenticated. Use 'hq sync start' to begin syncing.");
-    return;
-  }
-
-  console.log("  Setting up IndigoAI cloud sync...");
-  const creds = await authenticate();
-  console.log(`  ✓ Authenticated as ${creds.userId}`);
-  console.log(`  ✓ Bucket: ${creds.bucket}`);
-  console.log(`  ✓ Region: ${creds.region}`);
-  console.log();
-  console.log("  Run 'hq sync start' to begin syncing.");
-}
-
-/**
- * Start the background sync daemon
- */
-export async function startDaemon(hqRoot: string): Promise<void> {
-  if (!hasCredentials()) {
-    throw new Error("Not authenticated. Run 'hq sync init' first.");
-  }
-  _startDaemon(hqRoot);
-}
-
-/**
- * Stop the background sync daemon
- */
-export async function stopDaemon(hqRoot: string): Promise<void> {
-  _stopDaemon(hqRoot);
-}
-
-/**
- * Get current sync status
- */
-export async function getStatus(hqRoot: string): Promise<SyncStatus> {
-  const journal = readJournal(hqRoot);
-  const creds = readCredentials();
-  const running = isDaemonRunning(hqRoot);
-  const errors: string[] = [];
-
-  if (!creds) {
-    errors.push("Not authenticated — run 'hq sync init'");
-  }
-
-  return {
-    running,
-    lastSync: journal.lastSync || null,
-    fileCount: Object.keys(journal.files).length,
-    bucket: creds?.bucket || null,
-    errors,
-  };
-}
-
-/**
- * Force push all local files to S3
- */
-export async function pushAll(hqRoot: string): Promise<PushResult> {
-  const shouldSync = createIgnoreFilter(hqRoot);
-  const journal = readJournal(hqRoot);
-  let filesUploaded = 0;
-  let bytesUploaded = 0;
-
-  const files = walkDir(hqRoot, hqRoot, shouldSync);
-
-  for (const { absolutePath, relativePath } of files) {
-    if (!isWithinSizeLimit(absolutePath)) continue;
-
-    try {
-      const hash = hashFile(absolutePath);
-      const stat = fs.statSync(absolutePath);
-
-      await uploadFile(absolutePath, relativePath);
-      updateEntry(journal, relativePath, hash, stat.size, "up");
-      filesUploaded++;
-      bytesUploaded += stat.size;
-    } catch (err) {
-      console.error(
-        `  Failed: ${relativePath} — ${err instanceof Error ? err.message : err}`
-      );
-    }
-  }
-
-  writeJournal(hqRoot, journal);
-  return { filesUploaded, bytesUploaded };
-}
-
-/**
- * Force pull all remote files to local
- */
-export async function pullAll(hqRoot: string): Promise<PullResult> {
-  const journal = readJournal(hqRoot);
-  let filesDownloaded = 0;
-  let bytesDownloaded = 0;
-
-  const remoteFiles = await listRemoteFiles();
-
-  for (const file of remoteFiles) {
-    try {
-      const localPath = path.join(hqRoot, file.relativePath);
-      await downloadFile(file.relativePath, localPath);
-
-      const hash = hashFile(localPath);
-      updateEntry(journal, file.relativePath, hash, file.size, "down");
-      filesDownloaded++;
-      bytesDownloaded += file.size;
-    } catch (err) {
-      console.error(
-        `  Failed: ${file.relativePath} — ${err instanceof Error ? err.message : err}`
-      );
-    }
-  }
-
-  writeJournal(hqRoot, journal);
-  return { filesDownloaded, bytesDownloaded };
-}
-
-// Helper: recursively walk a directory
-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;
-}
+// VaultClient SDK (VLT-7)
+export { VaultClient } from "./vault-client.js";
+export {
+  VaultClientError,
+  VaultAuthError,
+  VaultPermissionDeniedError,
+  VaultNotFoundError,
+  VaultConflictError,
+} from "./vault-client.js";
+export type {
+  MembershipRole,
+  MembershipStatus,
+  Membership,
+  CreateInviteInput,
+  CreateInviteResult,
+  AcceptInviteResult,
+  UpdateRoleInput,
+  EntityInfo,
+  CreateEntityInput,
+  CreateEntityResult,
+} from "./vault-client.js";
+
+// STS child vending (VLT-8)
+export type {
+  TaskAction,
+  TaskScope,
+  VendChildInput,
+  VendChildResult,
+  StsChildCredentials,
+} from "./vault-client.js";
+
+// CLI commands
+export { share, sync } from "./cli/index.js";
+export type { ShareOptions, ShareResult, SyncOptions, SyncResult, SyncProgressEvent } from "./cli/index.js";
+export { resolveConflict, showDiff } from "./cli/index.js";
+export type { ConflictStrategy, ConflictInfo, ConflictResolution } from "./cli/index.js";
+
+// Membership CLI commands (VLT-7)
+export { invite, listInvites, revokeInvite } from "./cli/index.js";
+export type { InviteOptions, InviteResult, InviteListOptions, InviteRevokeOptions } from "./cli/index.js";
+export { accept, parseToken } from "./cli/index.js";
+export type { AcceptOptions, AcceptResult } from "./cli/index.js";
+export { promote } from "./cli/index.js";
+export type { PromoteOptions, PromoteResult } from "./cli/index.js";
+
+export type {
+  EntityContext,
+  VaultCredentials,
+  VaultServiceConfig,
+  SyncConfig,
+  Credentials,
+  JournalEntry,
+  SyncJournal,
+  SyncStatus,
+  PushResult,
+  PullResult,
+  DaemonState,
+} from "./types.js";

package/src/journal.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Unit tests for the sync journal (ADR-0001 Phase 5).
+ *
+ * Verifies per-company isolation, HQ_STATE_DIR override, and filename
+ * sanitization — all behaviors that the pre-Phase-5 monolithic journal
+ * didn't need.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  getJournalPath,
+  getStateDir,
+  readJournal,
+  writeJournal,
+  updateEntry,
+} from "./journal.js";
+import type { SyncJournal } from "./types.js";
+
+describe("journal", () => {
+  let stateDir: string;
+
+  beforeEach(() => {
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-journal-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+  });
+
+  afterEach(() => {
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
+  });
+
+  describe("getStateDir", () => {
+    it("honors HQ_STATE_DIR env var", () => {
+      expect(getStateDir()).toBe(stateDir);
+    });
+
+    it("falls back to ~/.hq when env var unset", () => {
+      delete process.env.HQ_STATE_DIR;
+      expect(getStateDir()).toBe(path.join(os.homedir(), ".hq"));
+    });
+  });
+
+  describe("getJournalPath", () => {
+    it("produces a per-slug filename", () => {
+      expect(getJournalPath("indigo")).toBe(
+        path.join(stateDir, "sync-journal.indigo.json"),
+      );
+    });
+
+    it("isolates different slugs into different files", () => {
+      expect(getJournalPath("indigo")).not.toBe(getJournalPath("brandstage"));
+    });
+
+    it("sanitizes path-unsafe characters", () => {
+      expect(getJournalPath("foo/bar")).toBe(
+        path.join(stateDir, "sync-journal.foo_bar.json"),
+      );
+      expect(getJournalPath("../escape")).toBe(
+        path.join(stateDir, "sync-journal.___escape.json"),
+      );
+    });
+
+    it("throws on empty slug", () => {
+      expect(() => getJournalPath("")).toThrow(/slug is required/);
+    });
+
+    it("throws on slug that sanitizes to empty", () => {
+      expect(() => getJournalPath("///")).toThrow(/empty identifier/);
+    });
+  });
+
+  describe("readJournal", () => {
+    it("returns an empty journal when the file doesn't exist", () => {
+      const j = readJournal("indigo");
+      expect(j.version).toBe("1");
+      expect(j.files).toEqual({});
+      expect(j.lastSync).toBe("");
+    });
+
+    it("reads a journal written with writeJournal", () => {
+      const original: SyncJournal = {
+        version: "1",
+        lastSync: "2026-04-19T00:00:00.000Z",
+        files: {
+          "docs/handoff.md": {
+            hash: "abc123",
+            size: 42,
+            syncedAt: "2026-04-19T00:00:00.000Z",
+            direction: "down",
+          },
+        },
+      };
+      writeJournal("indigo", original);
+      const roundTripped = readJournal("indigo");
+      expect(roundTripped).toEqual(original);
+    });
+  });
+
+  describe("writeJournal", () => {
+    it("creates the state directory if it doesn't exist", () => {
+      const nestedDir = path.join(stateDir, "nested", "deep");
+      process.env.HQ_STATE_DIR = nestedDir;
+      expect(fs.existsSync(nestedDir)).toBe(false);
+
+      writeJournal("indigo", { version: "1", lastSync: "", files: {} });
+      expect(fs.existsSync(nestedDir)).toBe(true);
+      expect(
+        fs.existsSync(path.join(nestedDir, "sync-journal.indigo.json")),
+      ).toBe(true);
+    });
+
+    it("keeps per-company journals independent", () => {
+      writeJournal("indigo", {
+        version: "1",
+        lastSync: "",
+        files: { "a.md": { hash: "1", size: 1, syncedAt: "", direction: "up" } },
+      });
+      writeJournal("brandstage", {
+        version: "1",
+        lastSync: "",
+        files: { "b.md": { hash: "2", size: 2, syncedAt: "", direction: "up" } },
+      });
+
+      const indigo = readJournal("indigo");
+      const brandstage = readJournal("brandstage");
+      expect(indigo.files).toHaveProperty("a.md");
+      expect(indigo.files).not.toHaveProperty("b.md");
+      expect(brandstage.files).toHaveProperty("b.md");
+      expect(brandstage.files).not.toHaveProperty("a.md");
+    });
+  });
+
+  describe("updateEntry", () => {
+    it("stamps lastSync and the per-file syncedAt", () => {
+      const j: SyncJournal = { version: "1", lastSync: "", files: {} };
+      updateEntry(j, "foo.md", "hash", 10, "up");
+      expect(j.files["foo.md"]?.hash).toBe("hash");
+      expect(j.files["foo.md"]?.direction).toBe("up");
+      expect(j.lastSync).not.toBe("");
+      expect(j.files["foo.md"]?.syncedAt).not.toBe("");
+    });
+  });
+});

package/src/journal.ts

@@ -1,20 +1,61 @@
 /**
- * Sync journal — tracks file state for conflict detection
+ * Sync journal — tracks per-file state (hash, size, last-synced direction) so
+ * sync/share can detect local edits that would be clobbered by a blind pull.
+ *
+ * ADR-0001 Phase 5: the journal is sharded by company slug and lives in
+ * `~/.hq/`, not inside the HQ content root. One monolithic journal per HQ
+ * install conflates state across companies and forces every runner to
+ * serialize through the same file — splitting it lets `hq-sync-runner
+ * --companies` fan out without contention, and a corrupted shard only affects
+ * one company.
+ *
+ * Path: `{stateDir}/sync-journal.{slug}.json`, where `stateDir` resolves to
+ * `HQ_STATE_DIR` (if set) or `~/.hq`.
  */
 
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 import * as crypto from "crypto";
 import type { SyncJournal, JournalEntry } from "./types.js";
 
-const JOURNAL_FILE = ".hq-sync-journal.json";
+const JOURNAL_FILE_PREFIX = "sync-journal.";
+const JOURNAL_FILE_SUFFIX = ".json";
 
-export function getJournalPath(hqRoot: string): string {
-  return path.join(hqRoot, JOURNAL_FILE);
+/**
+ * Where per-company journals are stored. Honors `HQ_STATE_DIR` for tests and
+ * non-standard installs; otherwise falls back to `~/.hq`.
+ */
+export function getStateDir(): string {
+  return process.env.HQ_STATE_DIR ?? path.join(os.homedir(), ".hq");
+}
+
+/**
+ * Filename-safe form of a slug. Slugs from vault-service are already
+ * URL-safe, but this guards against paths, dots, or anything the filesystem
+ * might interpret. Empty-or-invalid slugs throw rather than silently writing
+ * to a shared "sync-journal..json" file.
+ */
+function sanitizeSlug(slug: string): string {
+  if (!slug) {
+    throw new Error("journal: slug is required (empty or undefined)");
+  }
+  const cleaned = slug.replace(/[^a-zA-Z0-9_-]/g, "_");
+  if (!cleaned || /^[_-]+$/.test(cleaned)) {
+    throw new Error(`journal: slug "${slug}" sanitizes to an empty identifier`);
+  }
+  return cleaned;
+}
+
+export function getJournalPath(slug: string): string {
+  return path.join(
+    getStateDir(),
+    `${JOURNAL_FILE_PREFIX}${sanitizeSlug(slug)}${JOURNAL_FILE_SUFFIX}`,
+  );
 }
 
-export function readJournal(hqRoot: string): SyncJournal {
-  const journalPath = getJournalPath(hqRoot);
+export function readJournal(slug: string): SyncJournal {
+  const journalPath = getJournalPath(slug);
   if (fs.existsSync(journalPath)) {
     const content = fs.readFileSync(journalPath, "utf-8");
     return JSON.parse(content) as SyncJournal;
@@ -22,8 +63,9 @@ export function readJournal(hqRoot: string): SyncJournal {
   return { version: "1", lastSync: "", files: {} };
 }
 
-export function writeJournal(hqRoot: string, journal: SyncJournal): void {
-  const journalPath = getJournalPath(hqRoot);
+export function writeJournal(slug: string, journal: SyncJournal): void {
+  const journalPath = getJournalPath(slug);
+  fs.mkdirSync(path.dirname(journalPath), { recursive: true });
   fs.writeFileSync(journalPath, JSON.stringify(journal, null, 2));
 }
 
@@ -37,7 +79,7 @@ export function updateEntry(
   relativePath: string,
   hash: string,
   size: number,
-  direction: "up" | "down"
+  direction: "up" | "down",
 ): void {
   journal.files[relativePath] = {
     hash,
@@ -50,14 +92,14 @@ export function updateEntry(
 
 export function getEntry(
   journal: SyncJournal,
-  relativePath: string
+  relativePath: string,
 ): JournalEntry | undefined {
   return journal.files[relativePath];
 }
 
 export function removeEntry(
   journal: SyncJournal,
-  relativePath: string
+  relativePath: string,
 ): void {
   delete journal.files[relativePath];
 }