@indigoai-us/hq-cloud 5.1.0 → 5.1.9

package/dist/index.js

@@ -1,138 +1,23 @@
 /**
  * @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";
-// Cognito identity helpers — used by `hq auth refresh` and any consumer
-// that needs a valid HQ access token (deploy skill, onboarding, etc.).
-export { browserLogin, refreshTokens, getValidAccessToken, loadCachedTokens, saveCachedTokens, clearCachedTokens, isExpiring, CognitoAuthError, } from "./cognito-auth.js";
-/**
- * Initialize cloud sync — authenticate and provision bucket
- */
-export async function initSync(hqRoot) {
-    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) {
-    if (!hasCredentials()) {
-        throw new Error("Not authenticated. Run 'hq sync init' first.");
-    }
-    _startDaemon(hqRoot);
-}
-/**
- * Stop the background sync daemon
- */
-export async function stopDaemon(hqRoot) {
-    _stopDaemon(hqRoot);
-}
-/**
- * Get current sync status
- */
-export async function getStatus(hqRoot) {
-    const journal = readJournal(hqRoot);
-    const creds = readCredentials();
-    const running = isDaemonRunning(hqRoot);
-    const errors = [];
-    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) {
-    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) {
-    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, root, filter) {
-    const results = [];
-    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;
-}
+export { resolveEntityContext, refreshEntityContext, clearContextCache, isExpiringSoon, } from "./context.js";
+export { uploadFile, downloadFile, listRemoteFiles, deleteRemoteFile, headRemoteFile, } from "./s3.js";
+export { readJournal, writeJournal, hashFile, updateEntry, getEntry, removeEntry, getJournalPath, } from "./journal.js";
+export { createIgnoreFilter, isWithinSizeLimit, } from "./ignore.js";
+// Cognito browser-OAuth (VLT-9)
+export { browserLogin, refreshTokens, loadCachedTokens, saveCachedTokens, clearCachedTokens, isExpiring, getValidAccessToken, CognitoAuthError, } from "./cognito-auth.js";
+// VaultClient SDK (VLT-7)
+export { VaultClient } from "./vault-client.js";
+export { VaultClientError, VaultAuthError, VaultPermissionDeniedError, VaultNotFoundError, VaultConflictError, } from "./vault-client.js";
+// CLI commands
+export { share, sync } from "./cli/index.js";
+export { resolveConflict, showDiff } from "./cli/index.js";
+// Membership CLI commands (VLT-7)
+export { invite, listInvites, revokeInvite } from "./cli/index.js";
+export { accept, parseToken } from "./cli/index.js";
+export { promote } from "./cli/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,SAAS,CAAC;AAIjB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,WAAW,EACX,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,gCAAgC;AAChC,OAAO,EACL,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B,0BAA0B;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAwB3B,eAAe;AACf,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG3D,kCAAkC;AAClC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/journal.d.ts

@@ -1,10 +1,26 @@
 /**
- * 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 type { SyncJournal, JournalEntry } from "./types.js";
-export declare function getJournalPath(hqRoot: string): string;
-export declare function readJournal(hqRoot: string): SyncJournal;
-export declare function writeJournal(hqRoot: string, journal: SyncJournal): void;
+/**
+ * Where per-company journals are stored. Honors `HQ_STATE_DIR` for tests and
+ * non-standard installs; otherwise falls back to `~/.hq`.
+ */
+export declare function getStateDir(): string;
+export declare function getJournalPath(slug: string): string;
+export declare function readJournal(slug: string): SyncJournal;
+export declare function writeJournal(slug: string, journal: SyncJournal): void;
 export declare function hashFile(filePath: string): string;
 export declare function updateEntry(journal: SyncJournal, relativePath: string, hash: string, size: number, direction: "up" | "down"): void;
 export declare function getEntry(journal: SyncJournal, relativePath: string): JournalEntry | undefined;

package/dist/journal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI5D,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAOvD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAGvE;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,IAAI,GAAG,MAAM,GACvB,IAAI,CAQN;AAED,wBAAgB,QAAQ,CACtB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,GACnB,YAAY,GAAG,SAAS,CAE1B;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,GACnB,IAAI,CAEN"}
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK5D;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAmBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAOrD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAIrE;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,IAAI,GAAG,MAAM,GACvB,IAAI,CAQN;AAED,wBAAgB,QAAQ,CACtB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,GACnB,YAAY,GAAG,SAAS,CAE1B;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,GACnB,IAAI,CAEN"}

package/dist/journal.js

@@ -1,23 +1,60 @@
 /**
- * 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";
-const JOURNAL_FILE = ".hq-sync-journal.json";
-export function getJournalPath(hqRoot) {
-    return path.join(hqRoot, JOURNAL_FILE);
+const JOURNAL_FILE_PREFIX = "sync-journal.";
+const JOURNAL_FILE_SUFFIX = ".json";
+/**
+ * Where per-company journals are stored. Honors `HQ_STATE_DIR` for tests and
+ * non-standard installs; otherwise falls back to `~/.hq`.
+ */
+export function getStateDir() {
+    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) {
+    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) {
+    return path.join(getStateDir(), `${JOURNAL_FILE_PREFIX}${sanitizeSlug(slug)}${JOURNAL_FILE_SUFFIX}`);
 }
-export function readJournal(hqRoot) {
-    const journalPath = getJournalPath(hqRoot);
+export function readJournal(slug) {
+    const journalPath = getJournalPath(slug);
     if (fs.existsSync(journalPath)) {
         const content = fs.readFileSync(journalPath, "utf-8");
         return JSON.parse(content);
     }
     return { version: "1", lastSync: "", files: {} };
 }
-export function writeJournal(hqRoot, journal) {
-    const journalPath = getJournalPath(hqRoot);
+export function writeJournal(slug, journal) {
+    const journalPath = getJournalPath(slug);
+    fs.mkdirSync(path.dirname(journalPath), { recursive: true });
     fs.writeFileSync(journalPath, JSON.stringify(journal, null, 2));
 }
 export function hashFile(filePath) {

package/dist/journal.js.map

@@ -1 +1 @@
-{"version":3,"file":"journal.js","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAE7C,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,OAAoB;IAC/D,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAC3C,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,OAAoB,EACpB,YAAoB,EACpB,IAAY,EACZ,IAAY,EACZ,SAAwB;IAExB,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG;QAC5B,IAAI;QACJ,IAAI;QACJ,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAClC,SAAS;KACV,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,OAAoB,EACpB,YAAoB;IAEpB,OAAO,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,OAAoB,EACpB,YAAoB;IAEpB,OAAO,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"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"}

package/dist/journal.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=journal.test.d.ts.map

package/dist/journal.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.test.d.ts","sourceRoot":"","sources":["../src/journal.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/journal.test.js

@@ -0,0 +1,114 @@
+/**
+ * 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";
+describe("journal", () => {
+    let stateDir;
+    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 = {
+                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 = { 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("");
+        });
+    });
+});
+//# sourceMappingURL=journal.test.js.map

package/dist/journal.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.test.js","sourceRoot":"","sources":["../src/journal.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;IACvB,IAAI,QAAgB,CAAC;IAErB,UAAU,CAAC,GAAG,EAAE;QACd,QAAQ,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;QACtE,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,QAAQ,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QAC3B,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;YACrC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;YAChD,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;YAChC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;QAC9B,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;YACtC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CACnC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,0BAA0B,CAAC,CAChD,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;YACvD,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;YAC1C,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CACpC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,2BAA2B,CAAC,CACjD,CAAC;YACF,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CACtC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,6BAA6B,CAAC,CACnD,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;YAC9B,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;YAChD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QAC3B,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;YAC9D,MAAM,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;YAChC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC5B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;YACnD,MAAM,QAAQ,GAAgB;gBAC5B,OAAO,EAAE,GAAG;gBACZ,QAAQ,EAAE,0BAA0B;gBACpC,KAAK,EAAE;oBACL,iBAAiB,EAAE;wBACjB,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,EAAE;wBACR,QAAQ,EAAE,0BAA0B;wBACpC,SAAS,EAAE,MAAM;qBAClB;iBACF;aACF,CAAC;YACF,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YACjC,MAAM,YAAY,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC5B,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;YACzD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;YACxD,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,SAAS,CAAC;YACrC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAE7C,YAAY,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;YAClE,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5C,MAAM,CACJ,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,0BAA0B,CAAC,CAAC,CAChE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;YAChD,YAAY,CAAC,QAAQ,EAAE;gBACrB,OAAO,EAAE,GAAG;gBACZ,QAAQ,EAAE,EAAE;gBACZ,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;aACzE,CAAC,CAAC;YACH,YAAY,CAAC,YAAY,EAAE;gBACzB,OAAO,EAAE,GAAG;gBACZ,QAAQ,EAAE,EAAE;gBACZ,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;aACzE,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;YACrC,MAAM,UAAU,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;YAC7C,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAC5C,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAChD,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAChD,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QAC3B,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;YACnD,MAAM,CAAC,GAAgB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YACjE,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;YAC3C,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC7C,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChD,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAChC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/s3.d.ts

@@ -1,15 +1,27 @@
 /**
- * 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().
  */
-export declare function uploadFile(localPath: string, relativePath: string): Promise<void>;
-export declare function downloadFile(relativePath: string, localPath: string): Promise<void>;
+import type { EntityContext } from "./types.js";
+export declare function uploadFile(ctx: EntityContext, localPath: string, key: string): Promise<void>;
+export declare function downloadFile(ctx: EntityContext, key: string, localPath: string): Promise<void>;
 export interface RemoteFile {
     key: string;
-    relativePath: string;
     size: number;
     lastModified: Date;
     etag: string;
 }
-export declare function listRemoteFiles(): Promise<RemoteFile[]>;
-export declare function deleteRemoteFile(relativePath: string): Promise<void>;
+export declare function listRemoteFiles(ctx: EntityContext, prefix?: string): Promise<RemoteFile[]>;
+export declare function deleteRemoteFile(ctx: EntityContext, key: string): Promise<void>;
+/**
+ * Check if a remote key exists and return its metadata.
+ */
+export declare function headRemoteFile(ctx: EntityContext, key: string): Promise<{
+    lastModified: Date;
+    etag: string;
+    size: number;
+} | null>;
 //# sourceMappingURL=s3.d.ts.map

package/dist/s3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA;;GAEG;AAqDH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAgC7D;AAED,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1E"}
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkBhD,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,EAAE,CAAC,CA6BvB;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAoBpE"}

package/dist/s3.js

@@ -1,59 +1,42 @@
 /**
- * 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";
 import * as path from "path";
-import { S3Client, PutObjectCommand, GetObjectCommand, ListObjectsV2Command, DeleteObjectCommand, } from "@aws-sdk/client-s3";
-import { readCredentials, refreshAwsCredentials } from "./auth.js";
-let s3Client = null;
-function getConfig(creds) {
-    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() {
-    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,
-            },
-        });
-    }
-    return { client: s3Client, config: getConfig(creds) };
+import { S3Client, PutObjectCommand, GetObjectCommand, ListObjectsV2Command, DeleteObjectCommand, HeadObjectCommand, } from "@aws-sdk/client-s3";
+/**
+ * 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) {
+    return new S3Client({
+        region: ctx.region,
+        credentials: {
+            accessKeyId: ctx.credentials.accessKeyId,
+            secretAccessKey: ctx.credentials.secretAccessKey,
+            sessionToken: ctx.credentials.sessionToken,
+        },
+    });
 }
-export async function uploadFile(localPath, relativePath) {
-    const { client, config } = await getClient();
-    const key = `${config.prefix}${relativePath}`;
+export async function uploadFile(ctx, localPath, key) {
+    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, localPath) {
-    const { client, config } = await getClient();
-    const key = `${config.prefix}${relativePath}`;
+export async function downloadFile(ctx, key, localPath) {
+    const client = buildClient(ctx);
     const response = await client.send(new GetObjectCommand({
-        Bucket: config.bucket,
+        Bucket: ctx.bucketName,
         Key: key,
     }));
     if (!response.Body) {
@@ -70,25 +53,21 @@ export async function downloadFile(relativePath, localPath) {
     }
     fs.writeFileSync(localPath, Buffer.concat(chunks));
 }
-export async function listRemoteFiles() {
-    const { client, config } = await getClient();
+export async function listRemoteFiles(ctx, prefix) {
+    const client = buildClient(ctx);
     const files = [];
     let continuationToken;
     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 || "",
@@ -98,14 +77,36 @@ export async function listRemoteFiles() {
     } while (continuationToken);
     return files;
 }
-export async function deleteRemoteFile(relativePath) {
-    const { client, config } = await getClient();
-    const key = `${config.prefix}${relativePath}`;
+export async function deleteRemoteFile(ctx, key) {
+    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, key) {
+    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) {
+        if (err && typeof err === "object" && "name" in err && err.name === "NotFound") {
+            return null;
+        }
+        throw err;
+    }
+}
 function getMimeType(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     const mimeTypes = {