@indigoai-us/hq-cloud 5.1.0 → 5.1.9

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];
 }

package/src/s3.ts

@@ -1,5 +1,9 @@
 /**
- * S3 operations — upload, download, list, delete
+ * S3 operations — upload, download, list, delete.
+ *
+ * VLT-5: All operations now accept an EntityContext (entity-aware bucket +
+ * STS-scoped credentials) instead of reading static env config. The caller
+ * is responsible for resolving the context via resolveEntityContext().
  */
 
 import * as fs from "fs";
@@ -10,79 +14,56 @@ import {
   GetObjectCommand,
   ListObjectsV2Command,
   DeleteObjectCommand,
+  HeadObjectCommand,
 } from "@aws-sdk/client-s3";
-import type { Credentials, SyncConfig } from "./types.js";
-import { readCredentials, refreshAwsCredentials } from "./auth.js";
-
-let s3Client: S3Client | null = null;
-
-function getConfig(creds: Credentials): SyncConfig {
-  const prefix = creds.teamId
-    ? `teams/${creds.teamId}/users/${creds.userId}/hq/`
-    : `users/${creds.userId}/hq/`;
-  return {
-    bucket: creds.bucket,
-    region: creds.region,
-    userId: creds.userId,
-    prefix,
-  };
-}
-
-async function getClient(): Promise<{ client: S3Client; config: SyncConfig }> {
-  let creds = readCredentials();
-  if (!creds) {
-    throw new Error("Not authenticated. Run 'hq sync init' first.");
-  }
-
-  // Refresh if expired or missing access key
-  if (!creds.accessKeyId || (creds.expiration && new Date(creds.expiration) < new Date())) {
-    creds = await refreshAwsCredentials(creds);
-  }
-
-  if (!s3Client) {
-    s3Client = new S3Client({
-      region: creds.region,
-      credentials: {
-        accessKeyId: creds.accessKeyId,
-        secretAccessKey: creds.secretAccessKey,
-        sessionToken: creds.sessionToken,
-      },
-    });
-  }
+import type { EntityContext } from "./types.js";
 
-  return { client: s3Client, config: getConfig(creds) };
+/**
+ * Build an S3Client from an EntityContext's STS-scoped credentials.
+ * A new client is created each time to ensure fresh credentials are used
+ * (the caller handles caching/refresh at the EntityContext level).
+ */
+function buildClient(ctx: EntityContext): S3Client {
+  return new S3Client({
+    region: ctx.region,
+    credentials: {
+      accessKeyId: ctx.credentials.accessKeyId,
+      secretAccessKey: ctx.credentials.secretAccessKey,
+      sessionToken: ctx.credentials.sessionToken,
+    },
+  });
 }
 
 export async function uploadFile(
+  ctx: EntityContext,
   localPath: string,
-  relativePath: string
+  key: string,
 ): Promise<void> {
-  const { client, config } = await getClient();
-  const key = `${config.prefix}${relativePath}`;
+  const client = buildClient(ctx);
   const body = fs.readFileSync(localPath);
 
   await client.send(
     new PutObjectCommand({
-      Bucket: config.bucket,
+      Bucket: ctx.bucketName,
       Key: key,
       Body: body,
-      ContentType: getMimeType(relativePath),
-    })
+      ContentType: getMimeType(key),
+    }),
   );
 }
 
 export async function downloadFile(
-  relativePath: string,
-  localPath: string
+  ctx: EntityContext,
+  key: string,
+  localPath: string,
 ): Promise<void> {
-  const { client, config } = await getClient();
-  const key = `${config.prefix}${relativePath}`;
+  const client = buildClient(ctx);
 
   const response = await client.send(
     new GetObjectCommand({
-      Bucket: config.bucket,
+      Bucket: ctx.bucketName,
       Key: key,
-    })
+    }),
   );
 
   if (!response.Body) {
@@ -104,34 +85,33 @@ export async function downloadFile(
 
 export interface RemoteFile {
   key: string;
-  relativePath: string;
   size: number;
   lastModified: Date;
   etag: string;
 }
 
-export async function listRemoteFiles(): Promise<RemoteFile[]> {
-  const { client, config } = await getClient();
+export async function listRemoteFiles(
+  ctx: EntityContext,
+  prefix?: string,
+): Promise<RemoteFile[]> {
+  const client = buildClient(ctx);
   const files: RemoteFile[] = [];
   let continuationToken: string | undefined;
 
   do {
     const response = await client.send(
       new ListObjectsV2Command({
-        Bucket: config.bucket,
-        Prefix: config.prefix,
+        Bucket: ctx.bucketName,
+        Prefix: prefix,
         ContinuationToken: continuationToken,
-      })
+      }),
     );
 
     for (const obj of response.Contents || []) {
       if (!obj.Key || !obj.Size) continue;
-      const relativePath = obj.Key.replace(config.prefix, "");
-      if (!relativePath) continue;
 
       files.push({
         key: obj.Key,
-        relativePath,
         size: obj.Size,
         lastModified: obj.LastModified || new Date(),
         etag: obj.ETag || "",
@@ -144,18 +124,48 @@ export async function listRemoteFiles(): Promise<RemoteFile[]> {
   return files;
 }
 
-export async function deleteRemoteFile(relativePath: string): Promise<void> {
-  const { client, config } = await getClient();
-  const key = `${config.prefix}${relativePath}`;
+export async function deleteRemoteFile(
+  ctx: EntityContext,
+  key: string,
+): Promise<void> {
+  const client = buildClient(ctx);
 
   await client.send(
     new DeleteObjectCommand({
-      Bucket: config.bucket,
+      Bucket: ctx.bucketName,
       Key: key,
-    })
+    }),
   );
 }
 
+/**
+ * Check if a remote key exists and return its metadata.
+ */
+export async function headRemoteFile(
+  ctx: EntityContext,
+  key: string,
+): Promise<{ lastModified: Date; etag: string; size: number } | null> {
+  const client = buildClient(ctx);
+  try {
+    const response = await client.send(
+      new HeadObjectCommand({
+        Bucket: ctx.bucketName,
+        Key: key,
+      }),
+    );
+    return {
+      lastModified: response.LastModified || new Date(),
+      etag: response.ETag || "",
+      size: response.ContentLength || 0,
+    };
+  } catch (err: unknown) {
+    if (err && typeof err === "object" && "name" in err && err.name === "NotFound") {
+      return null;
+    }
+    throw err;
+  }
+}
+
 function getMimeType(filePath: string): string {
   const ext = path.extname(filePath).toLowerCase();
   const mimeTypes: Record<string, string> = {

package/src/types.ts

@@ -57,3 +57,40 @@ export interface DaemonState {
   startedAt: string;
   hqRoot: string;
 }
+
+/**
+ * Entity-aware context for vault-backed S3 operations (VLT-5).
+ * Resolved from vault-service entity registry + STS vending.
+ */
+export interface EntityContext {
+  /** Entity UID (cmp_*) */
+  uid: string;
+  /** Entity slug (human-readable, stable key for per-company local state). */
+  slug: string;
+  /** S3 bucket name for this entity */
+  bucketName: string;
+  /** AWS region */
+  region: string;
+  /** STS-scoped credentials */
+  credentials: VaultCredentials;
+  /** When the credentials expire (ISO 8601) */
+  expiresAt: string;
+}
+
+export interface VaultCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+}
+
+/**
+ * Configuration for connecting to the vault-service API.
+ */
+export interface VaultServiceConfig {
+  /** Vault API base URL (e.g. https://vault-api.example.com) */
+  apiUrl: string;
+  /** Cognito JWT token for authentication */
+  authToken: string;
+  /** AWS region for S3 client (defaults to entity region or us-east-1) */
+  region?: string;
+}