@indigoai-us/hq-cloud 5.1.0 → 5.1.9

package/src/context.ts

@@ -0,0 +1,178 @@
+/**
+ * Entity context resolution (VLT-5 US-001).
+ *
+ * Resolves an entity (company) via vault-service, vends STS-scoped credentials,
+ * and returns an EntityContext for S3 operations. Handles auto-refresh when
+ * credentials are within 2 minutes of expiry.
+ */
+
+import type { EntityContext, VaultServiceConfig } from "./types.js";
+
+/** Minimum remaining TTL before auto-refresh triggers (2 minutes). */
+const REFRESH_THRESHOLD_MS = 2 * 60 * 1000;
+
+/** STS session duration requested from vault-service (15 minutes). */
+const DEFAULT_SESSION_DURATION_SECONDS = 900;
+
+/** Cached contexts keyed by entity UID. */
+const contextCache = new Map<string, EntityContext>();
+
+/**
+ * Look up an entity by slug or UID via vault-service, then vend STS-scoped
+ * credentials for that entity. Returns an EntityContext ready for S3 ops.
+ *
+ * Caches the result and auto-refreshes when the credentials are within
+ * 2 minutes of expiry.
+ */
+export async function resolveEntityContext(
+  companyUidOrSlug: string,
+  config: VaultServiceConfig,
+): Promise<EntityContext> {
+  // Check cache — return if credentials still fresh
+  const cached = contextCache.get(companyUidOrSlug);
+  if (cached && !isExpiringSoon(cached.expiresAt)) {
+    return cached;
+  }
+
+  // Step 1: Resolve entity — if it looks like a UID (cmp_*), fetch directly;
+  // otherwise look up by slug
+  const entity = companyUidOrSlug.startsWith("cmp_")
+    ? await fetchEntity(companyUidOrSlug, config)
+    : await fetchEntityBySlug("company", companyUidOrSlug, config);
+
+  if (!entity.bucketName) {
+    throw new Error(
+      `Entity ${entity.uid} (${entity.slug}) has no bucket provisioned. ` +
+      `Run VLT-2 bucket provisioning first.`,
+    );
+  }
+
+  // Step 2: Vend STS-scoped credentials
+  const vendResult = await vendCredentials(entity.uid, config);
+
+  const ctx: EntityContext = {
+    uid: entity.uid,
+    slug: entity.slug,
+    bucketName: entity.bucketName,
+    region: config.region ?? "us-east-1",
+    credentials: {
+      accessKeyId: vendResult.credentials.accessKeyId,
+      secretAccessKey: vendResult.credentials.secretAccessKey,
+      sessionToken: vendResult.credentials.sessionToken,
+    },
+    expiresAt: vendResult.expiresAt,
+  };
+
+  // Cache by both UID and slug for fast lookups
+  contextCache.set(entity.uid, ctx);
+  contextCache.set(entity.slug, ctx);
+
+  return ctx;
+}
+
+/**
+ * Check if credentials are expiring within the refresh threshold.
+ */
+export function isExpiringSoon(expiresAt: string): boolean {
+  const expiryMs = new Date(expiresAt).getTime();
+  const nowMs = Date.now();
+  return expiryMs - nowMs < REFRESH_THRESHOLD_MS;
+}
+
+/**
+ * Force-refresh a cached context. Useful when an S3 operation fails with
+ * an expired credentials error.
+ */
+export async function refreshEntityContext(
+  companyUidOrSlug: string,
+  config: VaultServiceConfig,
+): Promise<EntityContext> {
+  // Evict cache entry to force fresh resolution
+  contextCache.delete(companyUidOrSlug);
+  return resolveEntityContext(companyUidOrSlug, config);
+}
+
+/**
+ * Clear the entire context cache. Useful for tests.
+ */
+export function clearContextCache(): void {
+  contextCache.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Vault-service API calls
+// ---------------------------------------------------------------------------
+
+interface EntityResponse {
+  uid: string;
+  slug: string;
+  bucketName?: string;
+  status: string;
+}
+
+interface VendResponse {
+  credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiration: string;
+  };
+  expiresAt: string;
+}
+
+async function fetchEntity(
+  uid: string,
+  config: VaultServiceConfig,
+): Promise<EntityResponse> {
+  const res = await fetch(`${config.apiUrl}/entity/${uid}`, {
+    headers: { Authorization: `Bearer ${config.authToken}` },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Failed to fetch entity ${uid}: ${res.status} ${body}`);
+  }
+  const data = (await res.json()) as { entity: EntityResponse };
+  return data.entity;
+}
+
+async function fetchEntityBySlug(
+  type: string,
+  slug: string,
+  config: VaultServiceConfig,
+): Promise<EntityResponse> {
+  const res = await fetch(`${config.apiUrl}/entity/by-slug/${type}/${slug}`, {
+    headers: { Authorization: `Bearer ${config.authToken}` },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(
+      `Failed to find entity by slug ${type}/${slug}: ${res.status} ${body}`,
+    );
+  }
+  const data = (await res.json()) as { entity: EntityResponse };
+  return data.entity;
+}
+
+async function vendCredentials(
+  companyUid: string,
+  config: VaultServiceConfig,
+): Promise<VendResponse> {
+  const res = await fetch(`${config.apiUrl}/sts/vend`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${config.authToken}`,
+    },
+    body: JSON.stringify({
+      companyUid,
+      durationSeconds: DEFAULT_SESSION_DURATION_SECONDS,
+    }),
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(
+      `STS vend failed for ${companyUid}: ${res.status} ${body}`,
+    );
+  }
+  return (await res.json()) as VendResponse;
+}

package/src/daemon-worker.ts

@@ -1,9 +1,16 @@
 /**
  * Daemon worker — runs as a detached child process
  * Watches HQ directory and syncs changes to S3
+ *
+ * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
+ * When re-enabled, this worker will need to resolve an EntityContext before
+ * constructing the SyncWatcher. The process argv will need to include company
+ * context (slug or UID) and vault-service config.
  */
 
-import { SyncWatcher } from "./watcher.js";
+// Day 1: SyncWatcher now requires an EntityContext.
+// This file is retained for the automatic-sync milestone but is not functional
+// until the daemon startup path is updated to resolve entity context.
 
 const hqRoot = process.argv[2];
 
@@ -12,21 +19,8 @@ if (!hqRoot) {
   process.exit(1);
 }
 
-const watcher = new SyncWatcher(hqRoot);
-watcher.start();
-
-// Handle graceful shutdown
-process.on("SIGTERM", () => {
-  watcher.stop();
-  process.exit(0);
-});
-
-process.on("SIGINT", () => {
-  watcher.stop();
-  process.exit(0);
-});
-
-// Keep process alive
-setInterval(() => {
-  // Heartbeat — could add remote change polling here
-}, 30_000);
+console.error(
+  "Day 1: daemon-worker is not yet wired to entity context resolution. " +
+  "Use 'hq share' and 'hq sync' for manual sync.",
+);
+process.exit(1);

package/src/daemon.ts

@@ -1,6 +1,8 @@
 /**
  * Background sync daemon management
  * Manages a child process that runs the file watcher
+ *
+ * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
  */
 
 import * as fs from "fs";

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,111 @@
 /**
  * @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,
+  PendingInviteByEmail,
+} 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";