@indigoai-us/hq-cloud 5.1.0

package/dist/cli/sync.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `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 type { VaultServiceConfig } from "../types.js";
+import type { ConflictStrategy } from "./conflict.js";
+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;
+}
+export interface SyncResult {
+    filesDownloaded: number;
+    bytesDownloaded: number;
+    filesSkipped: number;
+    conflicts: number;
+    aborted: boolean;
+}
+/**
+ * Sync (pull) all allowed files from the entity vault.
+ */
+export declare function sync(options: SyncOptions): Promise<SyncResult>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/cli/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,2BAA2B;IAC3B,WAAW,EAAE,kBAAkB,CAAC;IAChC,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAoHpE"}

package/dist/cli/sync.js

@@ -0,0 +1,138 @@
+/**
+ * `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 { 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";
+/**
+ * Sync (pull) all allowed files from the entity vault.
+ */
+export async function sync(options) {
+    const { company, onConflict, vaultConfig, hqRoot } = options;
+    // 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(hqRoot);
+    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(hqRoot, 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?.message;
+            if (remoteJournalMessage) {
+                console.log(`  ✓ ${remoteFile.key} — "${remoteJournalMessage}"`);
+            }
+            else {
+                console.log(`  ✓ ${remoteFile.key}`);
+            }
+            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 {
+                console.error(`  ✗ ${remoteFile.key} — ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+    writeJournal(hqRoot, journal);
+    return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: false };
+}
+/**
+ * Resolve active company from .hq/config.json.
+ */
+function resolveActiveCompany(hqRoot) {
+    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) {
+    if (err && typeof err === "object" && "name" in err) {
+        return err.name === "AccessDenied" || err.name === "Forbidden";
+    }
+    return false;
+}
+//# sourceMappingURL=sync.js.map

package/dist/cli/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAsBhD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAoB;IAC7C,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAE7D,kBAAkB;IAClB,MAAM,UAAU,GAAG,OAAO,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,oDAAoD;YACpD,iDAAiD,CAClD,CAAC;IACJ,CAAC;IAED,yBAAyB;IACzB,IAAI,GAAG,GAAG,MAAM,oBAAoB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAEpC,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,sEAAsE;IACtE,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;IAE/C,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;QAEpD,qBAAqB;QACrB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,YAAY,EAAE,CAAC;YACf,SAAS;QACX,CAAC;QAED,+CAA+C;QAC/C,IAAI,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,GAAG,GAAG,MAAM,oBAAoB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QAC5D,CAAC;QAED,2BAA2B;QAC3B,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;QAEvD,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;YAEtC,6DAA6D;YAC7D,IAAI,YAAY,IAAI,YAAY,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACpD,SAAS,EAAE,CAAC;gBAEZ,MAAM,UAAU,GAAG,MAAM,eAAe,CACtC;oBACE,IAAI,EAAE,UAAU,CAAC,GAAG;oBACpB,SAAS;oBACT,cAAc,EAAE,UAAU,CAAC,YAAY;oBACvC,aAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK;oBAC3C,SAAS,EAAE,MAAM;iBAClB,EACD,UAAU,CACX,CAAC;gBAEF,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;oBAC3B,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;oBAC9B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;gBACtF,CAAC;gBACD,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;oBACnD,YAAY,EAAE,CAAC;oBACf,SAAS;gBACX,CAAC;gBACD,wCAAwC;YAC1C,CAAC;iBAAM,IAAI,YAAY,IAAI,YAAY,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC3D,4DAA4D;gBAC5D,8BAA8B;gBAC9B,MAAM,YAAY,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC;gBAC/D,MAAM,aAAa,GAAG,UAAU,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;gBACxD,IAAI,aAAa,IAAI,YAAY,EAAE,CAAC;oBAClC,sCAAsC;oBACtC,YAAY,EAAE,CAAC;oBACf,SAAS;gBACX,CAAC;YACH,CAAC;QACH,CAAC;QAED,WAAW;QACX,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAEnD,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YACpC,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAE9D,+CAA+C;YAC/C,MAAM,oBAAoB,GAAI,YAAiD,EAAE,OAAO,CAAC;YACzF,IAAI,oBAAoB,EAAE,CAAC;gBACzB,OAAO,CAAC,GAAG,CAAC,OAAO,UAAU,CAAC,GAAG,OAAO,oBAAoB,GAAG,CAAC,CAAC;YACnE,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,OAAO,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC;YACvC,CAAC;YAED,eAAe,EAAE,CAAC;YAClB,eAAe,IAAI,IAAI,CAAC,IAAI,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sEAAsE;YACtE,yCAAyC;YACzC,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,YAAY,EAAE,CAAC;YACjB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CACX,OAAO,UAAU,CAAC,GAAG,MAAM,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CACtE,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE9B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACvF,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,MAAc;IAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;YAChE,OAAO,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,WAAW,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,GAAY;IAClC,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QACpD,OAAO,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC;IACjE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/cli/sync.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for hq sync command (VLT-5 US-002).
+ */
+export {};
+//# sourceMappingURL=sync.test.d.ts.map

package/dist/cli/sync.test.d.ts.map

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

package/dist/cli/sync.test.js

@@ -0,0 +1,172 @@
+/**
+ * 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";
+// 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, _key, localPath) => {
+            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 = {
+    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) => {
+        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;
+    beforeEach(() => {
+        clearContextCache();
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sync-test-"));
+        setupFetchMock();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    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(path.join(tmpDir, ".hq-sync-journal.json"), 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(path.join(tmpDir, ".hq-sync-journal.json"), 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(path.join(tmpDir, ".hq-sync-journal.json"), 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");
+    });
+});
+//# sourceMappingURL=sync.test.js.map

package/dist/cli/sync.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.test.js","sourceRoot":"","sources":["../../src/cli/sync.test.ts"],"names":[],"mappings":"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"}

package/dist/cognito-auth.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Cognito browser-OAuth helper (VLT-9).
+ *
+ * Drives the Cognito Hosted UI authorization-code + PKCE flow for the
+ * vault-service User Pool. Used by the CLI (`hq login`, `create-hq`) to
+ * obtain a JWT that is then passed to the vault-service API as
+ * `Authorization: Bearer <accessToken>`.
+ *
+ * Why PKCE: the CLI is a public client (no secret), so we use PKCE per
+ * RFC 7636 to prove that the same process that started the auth request
+ * is the one exchanging the code for tokens.
+ *
+ * Why a localhost callback: Cognito allows `http://localhost:*` as a
+ * redirect URI specifically for native/CLI apps (RFC 8252 §7). We spin
+ * up a one-shot HTTP server on the chosen port, capture exactly one
+ * callback, then close it.
+ */
+export interface CognitoAuthConfig {
+    /** AWS region the User Pool lives in (e.g. "us-east-1"). */
+    region: string;
+    /** Cognito User Pool Domain prefix (e.g. "vault-indigo-stefanjohnson"). */
+    userPoolDomain: string;
+    /** App Client ID (e.g. "4mmujmjq3srakdueg656b9m0mp"). */
+    clientId: string;
+    /** Loopback callback port. Defaults to 3000. */
+    port?: number;
+    /** OAuth scopes. Defaults to ["openid", "email", "profile"]. */
+    scopes?: string[];
+}
+export interface CognitoTokens {
+    accessToken: string;
+    idToken: string;
+    refreshToken: string;
+    /** ISO 8601 timestamp when the access token expires. */
+    expiresAt: string;
+    tokenType: "Bearer";
+}
+/** Returned when an interactive login is needed but stdin/browser is unavailable. */
+export declare class CognitoAuthError extends Error {
+    constructor(message: string);
+}
+export declare function loadCachedTokens(): CognitoTokens | null;
+export declare function saveCachedTokens(tokens: CognitoTokens): void;
+export declare function clearCachedTokens(): void;
+/** True when the token expires within the given buffer (default 60s). */
+export declare function isExpiring(tokens: CognitoTokens, bufferSeconds?: number): boolean;
+/**
+ * Open the Cognito Hosted UI in the user's browser, wait for the redirect
+ * back to localhost, and exchange the auth code for tokens.
+ *
+ * Times out after 5 minutes if the user doesn't complete the flow.
+ */
+export declare function browserLogin(config: CognitoAuthConfig): Promise<CognitoTokens>;
+/**
+ * Use the refresh token to obtain a fresh access token without user interaction.
+ * The refresh token itself is NOT rotated by Cognito on the refresh grant, so
+ * we preserve the existing one in the result.
+ */
+export declare function refreshTokens(config: CognitoAuthConfig, currentRefreshToken: string): Promise<CognitoTokens>;
+/**
+ * High-level helper: return a non-expired access token, refreshing or
+ * launching browser login as needed.
+ *
+ * Pass `interactive: false` from automated contexts where you would rather
+ * fail fast than open a browser.
+ */
+export declare function getValidAccessToken(config: CognitoAuthConfig, options?: {
+    interactive?: boolean;
+}): Promise<string>;
+//# sourceMappingURL=cognito-auth.d.ts.map

package/dist/cognito-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cognito-auth.d.ts","sourceRoot":"","sources":["../src/cognito-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,QAAQ,CAAC;CACrB;AAED,qFAAqF;AACrF,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AASD,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAQvD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAK5D;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,aAAa,SAAK,GAAG,OAAO,CAG7E;AAsCD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,aAAa,CAAC,CAmGxB;AAsDD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,iBAAiB,EACzB,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAAC,aAAa,CAAC,CA4BxB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,OAAO,CAAC,MAAM,CAAC,CAuBjB"}