@indigoai-us/hq-cloud 5.11.2 → 5.12.0

package/src/bin/sync-runner.ts

@@ -78,6 +78,7 @@ import type {
 import { share as defaultShare } from "../cli/share.js";
 import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
+import type { UploadAuthor } from "../s3.js";
 
 /**
  * Sync direction for a run.
@@ -114,6 +115,58 @@ const DEFAULT_VAULT_API_URL =
 
 const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
 
+// ---------------------------------------------------------------------------
+// Personal-vault scope (exclusion list)
+// ---------------------------------------------------------------------------
+//
+// Top-level directories under `hq_root/` that the personal-vault push MUST
+// NOT upload. Mirrors the Rust constant of the same name in
+// `hq-sync/src-tauri/src/commands/personal.rs` so the Tauri menubar's
+// first-push and this Node runner's steady-state push enforce identical
+// scope. Every other top-level entry under hq_root (e.g. `.claude/`,
+// `knowledge/`, `modules/`, `README.md`, `.codex/`) is included, subject
+// to the gitignore/hqignore filter that share() applies per-file.
+//
+// Rationale per entry:
+//   - `.git`: a repo's internal state is large, opaque, and useless after
+//     sync; .gitignore alone doesn't cover `.git/` because it's the repo
+//     itself, not a tracked path.
+//   - `companies/`: synced separately by the runner's per-membership fanout;
+//     do not double-write into the personal vault.
+//   - `core/`, `data/`, `personal/`, `repos/`, `workspace/`: per user
+//     directive — heavy local-only content (machine-state, datasets, cloned
+//     remotes, session threads) that has no business in the personal vault.
+export const PERSONAL_VAULT_EXCLUDED_TOP_LEVEL: readonly string[] = [
+  ".git",
+  "companies",
+  "core",
+  "data",
+  "personal",
+  "repos",
+  "workspace",
+];
+
+/**
+ * Compute absolute paths to share for the personal vault: every top-level
+ * entry under `hqRoot` whose basename is NOT in `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL`.
+ * Mirrors the Rust `is_personal_vault_path` predicate (just hoisted to the
+ * top-level step). Order is whatever `fs.readdirSync` returns — share()
+ * doesn't care, and the per-file walk inside share() handles recursion
+ * uniformly. Missing hqRoot returns []; callers treat that as "no personal
+ * content to push" rather than a hard error.
+ */
+export function computePersonalVaultPaths(hqRoot: string): string[] {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(hqRoot);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((name) => !PERSONAL_VAULT_EXCLUDED_TOP_LEVEL.includes(name))
+    .map((name) => path.join(hqRoot, name));
+}
+
 // ---------------------------------------------------------------------------
 // Event protocol
 // ---------------------------------------------------------------------------
@@ -348,6 +401,10 @@ interface ParsedArgs {
   onConflict: ConflictStrategy;
   hqRoot: string;
   direction: Direction;
+  /** Auto-sync (Beta): keep the runner alive after the first pass. */
+  watch: boolean;
+  /** Auto-sync (Beta): ms between remote-pull passes. Required when watch=true. */
+  pollRemoteMs?: number;
 }
 
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
@@ -356,6 +413,8 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let onConflict: ConflictStrategy = "abort";
   let hqRoot = DEFAULT_HQ_ROOT;
   let direction: Direction = "pull";
+  let watch = false;
+  let pollRemoteMs: number | undefined;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -391,6 +450,21 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         hqRoot = argv[++i];
         if (!hqRoot) return { error: "--hq-root requires a value" };
         break;
+      case "--watch":
+        watch = true;
+        break;
+      case "--poll-remote-ms": {
+        const val = argv[++i];
+        if (!val) return { error: "--poll-remote-ms requires a value" };
+        const n = Number(val);
+        if (!Number.isInteger(n) || n <= 0) {
+          return {
+            error: `--poll-remote-ms must be a positive integer (ms), got: ${val}`,
+          };
+        }
+        pollRemoteMs = n;
+        break;
+      }
       case "--json":
         // Accepted but ignored — ndjson is the only output mode.
         break;
@@ -405,8 +479,11 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   if (!companies && !company) {
     return { error: "Pass --companies or --company <slug>" };
   }
+  if (pollRemoteMs !== undefined && !watch) {
+    return { error: "--poll-remote-ms requires --watch" };
+  }
 
-  return { companies, company, onConflict, hqRoot, direction };
+  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs };
 }
 
 // ---------------------------------------------------------------------------
@@ -490,6 +567,22 @@ export async function runRunner(
   const client =
     deps.createVaultClient?.(vaultConfig) ?? new VaultClient(vaultConfig);
 
+  // ---- resolve identity claims -----------------------------------------
+  // Read the cached idToken claims once. Two consumers downstream:
+  //   1. The claim-dance (only fires in `--companies` mode for setup-needed
+  //      invitees).
+  //   2. The S3 upload author (every share() call stamps `Metadata['created-by']`
+  //      with `claims.email` so the hq-console vault UI's CREATED BY column
+  //      attributes the file to the syncing user).
+  // Resolved here (not inside `parsed.companies`) so single-company runs also
+  // get author attribution. `null` is fine — share() simply omits the metadata.
+  const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
+  const claims = getClaims();
+  const uploadAuthor: UploadAuthor | undefined =
+    claims?.sub && claims?.email
+      ? { userSub: claims.sub, email: claims.email }
+      : undefined;
+
   // ---- resolve targets --------------------------------------------------
   let memberships: Pick<Membership, "companyUid">[];
   try {
@@ -497,8 +590,6 @@ export async function runRunner(
       // Before giving up on memberships, run the claim-dance: new users signed
       // in via the tray may have email-keyed invites waiting for them. Without
       // this, an invited user would see "setup-needed" on every tray click.
-      const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
-      const claims = getClaims();
       if (claims) {
         await runClaimDance(client, claims, stderr);
       }
@@ -697,13 +788,17 @@ export async function runRunner(
       };
 
       // Push first so a subsequent pull doesn't overwrite files we were about
-      // to broadcast. Uses the walk-everything-under-companies/{slug}/ entry
-      // point with `skipUnchanged` so we don't re-upload files that haven't
-      // changed since the last sync.
+      // to broadcast. Company targets walk `companies/{slug}/`; the personal
+      // target walks every top-level entry under hqRoot minus the exclusion
+      // list (see PERSONAL_VAULT_EXCLUDED_TOP_LEVEL). `skipUnchanged: true`
+      // keeps both cases efficient on re-runs.
       if (doPush) {
         activePhase = "push";
+        const pushPaths = target.personalMode === true
+          ? computePersonalVaultPaths(parsed.hqRoot)
+          : [path.join(parsed.hqRoot, "companies", target.slug)];
         pushResult = await shareFn({
-          paths: [path.join(parsed.hqRoot, "companies", target.slug)],
+          paths: pushPaths,
           company: target.uid,
           vaultConfig,
           hqRoot: parsed.hqRoot,
@@ -715,6 +810,13 @@ export async function runRunner(
           // next pull because the remote object is still listable.
           propagateDeletes: true,
           onEvent: tagAndEmit,
+          ...(uploadAuthor ? { author: uploadAuthor } : {}),
+          // Mirror the pull-side seam: only spread these for the personal
+          // slot so company-target args stay identical to the pre-Slice-2
+          // shape (the "no personalMode/journalSlug keys" regression test
+          // in sync-runner.test.ts pins that contract).
+          ...(target.personalMode !== undefined ? { personalMode: target.personalMode } : {}),
+          ...(target.journalSlug !== undefined ? { journalSlug: target.journalSlug } : {}),
         });
       }
 
@@ -895,8 +997,41 @@ const isDirectInvocation = (() => {
   }
 })();
 
+/**
+ * Auto-sync (Beta) watch loop. Re-runs the one-shot runner every
+ * `pollRemoteMs` until the process is killed (SIGTERM from the menubar's
+ * stop_daemon command) or until a pass returns a non-zero exit code (hard
+ * error worth surfacing to the operator). `setup-needed` and `auth-error`
+ * exit 0 today and so will retry — acceptable noise for the beta; deal with
+ * it via a richer return shape if it shows up in Sentry.
+ */
+export async function runRunnerWithLoop(argv: string[]): Promise<number> {
+  if (!argv.includes("--watch")) {
+    return runRunner(argv);
+  }
+  const pollIdx = argv.indexOf("--poll-remote-ms");
+  const pollMs =
+    pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : 600_000;
+
+  // Strip --watch / --poll-remote-ms before delegating: the parser inside
+  // runRunner accepts them, but we don't want runRunner to think it's
+  // re-entering watch mode each iteration.
+  const passArgv = argv.filter((a, i) => {
+    if (a === "--watch") return false;
+    if (a === "--poll-remote-ms") return false;
+    if (i > 0 && argv[i - 1] === "--poll-remote-ms") return false;
+    return true;
+  });
+
+  while (true) {
+    const code = await runRunner(passArgv);
+    if (code !== 0) return code;
+    await new Promise<void>((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 if (isDirectInvocation) {
-  runRunner(process.argv.slice(2))
+  runRunnerWithLoop(process.argv.slice(2))
     .then((code) => process.exit(code))
     .catch((err) => {
       process.stderr.write(

package/src/cli/share.test.ts

@@ -481,6 +481,54 @@ describe("share", () => {
     expect(journal.files["fresh.md"].remoteEtag).toBe("new-upload-etag");
   });
 
+  it("forwards UploadAuthor to uploadFile when present (created-by metadata)", async () => {
+    // Regression: hq-console vault UI's CREATED BY column was always blank
+    // because the sync engine never stamped Metadata['created-by'] on PUT.
+    // share() now accepts an `author` and threads it to s3.uploadFile so
+    // every synced file lands in S3 with the syncer's identity attached.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "attribution.md");
+    fs.writeFileSync(testFile, "attributed content");
+
+    await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      author: { userSub: "abc-123", email: "alice@example.com" },
+    });
+
+    expect(uploadFile).toHaveBeenCalledWith(
+      expect.anything(),
+      testFile,
+      "attribution.md",
+      { userSub: "abc-123", email: "alice@example.com" },
+    );
+  });
+
+  it("omits author arg when not provided (back-compat)", async () => {
+    // share() must remain a 3-arg call to uploadFile when no author is
+    // configured — older test stubs and external integrations rely on it.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "no-author.md");
+    fs.writeFileSync(testFile, "anonymous");
+
+    await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(uploadFile).toHaveBeenCalledWith(
+      expect.anything(),
+      testFile,
+      "no-author.md",
+    );
+  });
+
   it("skipUnchanged=false (default) uploads even when hash matches", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
@@ -1034,4 +1082,126 @@ describe("share", () => {
     const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
     expect(journal.files["flaky.md"]).toBeDefined();
   });
+
+  // ── personalMode ───────────────────────────────────────────────────────────
+  //
+  // The personal vault (slug "personal" in the runner's fanout plan) shares
+  // files from hqRoot DIRECTLY — not from hqRoot/companies/<slug>/. Mirrors
+  // the Rust hq-sync first-push contract in src-tauri/src/commands/personal.rs:
+  // syncRoot = hqRoot, journal slug = "personal", remote keys are hq-root-
+  // relative (e.g. ".claude/skills/foo.md", "knowledge/notes.md"). The
+  // exclusion list itself is enforced by the runner (sync-runner.ts) by only
+  // passing in the allowed top-level directories — share() trusts its
+  // `paths` input.
+  describe("personalMode", () => {
+    it("personalMode=true keys files hq-root-relative, not companies/{slug}/-relative", async () => {
+      fs.mkdirSync(path.join(tmpDir, ".claude", "skills"), { recursive: true });
+      fs.mkdirSync(path.join(tmpDir, "knowledge"), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, ".claude", "skills", "foo.md"), "skill");
+      fs.writeFileSync(path.join(tmpDir, "knowledge", "notes.md"), "note");
+
+      const result = await share({
+        paths: [
+          path.join(tmpDir, ".claude"),
+          path.join(tmpDir, "knowledge"),
+        ],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        personalMode: true,
+        journalSlug: "personal",
+      });
+
+      expect(result.filesUploaded).toBe(2);
+      // Remote keys must be hq-root-relative, NOT prefixed with companies/personal/
+      const keys = vi.mocked(uploadFile).mock.calls.map((c) => c[2]);
+      expect(keys.sort()).toEqual([".claude/skills/foo.md", "knowledge/notes.md"]);
+    });
+
+    it("personalMode=true writes journal under the personal journalSlug", async () => {
+      fs.mkdirSync(path.join(tmpDir, "knowledge"), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, "knowledge", "notes.md"), "note");
+
+      await share({
+        paths: [path.join(tmpDir, "knowledge")],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        personalMode: true,
+        journalSlug: "personal",
+      });
+
+      // Personal journal is keyed "personal", NOT the company's ctx.slug ("acme")
+      const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+      const acmeJournalPath = path.join(stateDir, "sync-journal.acme.json");
+      expect(fs.existsSync(personalJournalPath)).toBe(true);
+      expect(fs.existsSync(acmeJournalPath)).toBe(false);
+
+      const journal = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+      expect(journal.files["knowledge/notes.md"]).toBeDefined();
+    });
+
+    it("personalMode=true accepts files outside companies/<slug>/ (companion to the company-folder rejection)", async () => {
+      // Same fixture as the "skips files outside the company folder" test
+      // above — file at hqRoot root, NOT under companies/acme/. Without
+      // personalMode this is rejected with a "outside company folder" warning;
+      // with personalMode=true the file IS uploaded because syncRoot=hqRoot.
+      const outsideFile = path.join(tmpDir, "stray.md");
+      fs.writeFileSync(outsideFile, "stray");
+
+      const result = await share({
+        paths: [outsideFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        personalMode: true,
+        journalSlug: "personal",
+      });
+
+      expect(result.filesUploaded).toBe(1);
+      expect(uploadFile).toHaveBeenCalledWith(expect.anything(), outsideFile, "stray.md");
+    });
+
+    it("personalMode=true + skipUnchanged honors the personal-journal hash", async () => {
+      fs.mkdirSync(path.join(tmpDir, "knowledge"), { recursive: true });
+      const testFile = path.join(tmpDir, "knowledge", "stable.md");
+      fs.writeFileSync(testFile, "stable content");
+
+      const { hashFile } = await import("../journal.js");
+      const hash = hashFile(testFile);
+
+      // Pre-seed the PERSONAL journal (not the per-company one) so the
+      // skipUnchanged short-circuit fires for the right slug.
+      const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+      fs.writeFileSync(
+        personalJournalPath,
+        JSON.stringify({
+          version: "1",
+          lastSync: new Date().toISOString(),
+          files: {
+            "knowledge/stable.md": {
+              hash,
+              size: 15,
+              syncedAt: new Date().toISOString(),
+              direction: "up",
+            },
+          },
+        }),
+      );
+
+      const result = await share({
+        paths: [path.join(tmpDir, "knowledge")],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        personalMode: true,
+        journalSlug: "personal",
+        skipUnchanged: true,
+      });
+
+      expect(result.filesUploaded).toBe(0);
+      expect(result.filesSkipped).toBe(1);
+      expect(uploadFile).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/cli/share.ts

@@ -10,6 +10,7 @@ import * as path from "path";
 import type { EntityContext, VaultServiceConfig, SyncJournal } from "../types.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { uploadFile, headRemoteFile, deleteRemoteFile } from "../s3.js";
+import type { UploadAuthor } from "../s3.js";
 import { readJournal, writeJournal, hashFile, updateEntry, removeEntry, normalizeEtag } from "../journal.js";
 import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
 import { resolveConflict } from "./conflict.js";
@@ -184,6 +185,31 @@ export interface ShareOptions {
    * full-tree bidirectional runner opts in.
    */
   propagateDeletes?: boolean;
+  /**
+   * Identity stamped onto each uploaded object's S3 user metadata
+   * (`created-by`, `created-by-sub`, `created-at`). The hq-console vault UI
+   * reads `Metadata['created-by']` for its "CREATED BY" column; uploads
+   * without an author leave that column blank for every file synced via
+   * this engine. The runner pipes Cognito idToken claims through here.
+   */
+  author?: UploadAuthor;
+  /**
+   * When true, share() targets the caller's person-entity bucket: syncRoot
+   * is `hqRoot` itself (NOT `hqRoot/companies/<slug>/`), so remote keys are
+   * hq-root-relative (e.g. ".claude/skills/foo.md", "knowledge/notes.md") to
+   * match the Rust hq-sync first-push contract in
+   * `src-tauri/src/commands/personal.rs`. The exclusion of top-level dirs
+   * (.git, companies, core, data, personal, repos, workspace) is enforced
+   * by the runner — share() trusts its `paths` input.
+   */
+  personalMode?: boolean;
+  /**
+   * Override for the per-slug journal file name. Defaults to `ctx.slug`. The
+   * runner passes `journalSlug: "personal"` for the personal slot so the TS
+   * push and the Rust personal first-push share idempotency state under one
+   * `sync-journal.personal.json` file.
+   */
+  journalSlug?: string;
 }
 
 export interface ShareResult {
@@ -254,9 +280,17 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   // Remote keys are company-relative; the on-disk scoping prefix is
   // companies/{slug}/. Anything outside this folder gets skipped to avoid
   // leaking cross-company state into the vault.
-  const syncRoot = path.join(hqRoot, "companies", ctx.slug);
+  //
+  // In personalMode the syncRoot is `hqRoot` itself — remote keys are
+  // hq-root-relative to match the Rust personal first-push (which uploads
+  // every non-excluded top-level dir under ~/HQ). The exclusion list is
+  // enforced upstream by the runner; share() just trusts `paths`.
+  const syncRoot = options.personalMode === true
+    ? hqRoot
+    : path.join(hqRoot, "companies", ctx.slug);
   const shouldSync = createIgnoreFilter(hqRoot);
-  const journal = readJournal(ctx.slug);
+  const journalSlug = options.journalSlug ?? ctx.slug;
+  const journal = readJournal(journalSlug);
 
   let filesUploaded = 0;
   let bytesUploaded = 0;
@@ -383,7 +417,9 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     try {
       const stat = fs.statSync(absolutePath);
 
-      const { etag } = await uploadFile(ctx, absolutePath, relativePath);
+      const { etag } = options.author
+        ? await uploadFile(ctx, absolutePath, relativePath, options.author)
+        : await uploadFile(ctx, absolutePath, relativePath);
 
       // Update journal with optional message; capture the post-upload ETag
       // so the next sync can distinguish "remote moved since we last wrote"
@@ -446,7 +482,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   // See cli/sync.ts: stamp lastSync on completion so a no-op share still
   // ticks the "Last sync" indicator.
   journal.lastSync = new Date().toISOString();
-  writeJournal(ctx.slug, journal);
+  writeJournal(journalSlug, journal);
 
   return {
     filesUploaded,

package/src/index.ts

@@ -20,7 +20,7 @@ export {
   headRemoteFile,
 } from "./s3.js";
 
-export type { RemoteFile } from "./s3.js";
+export type { RemoteFile, UploadAuthor } from "./s3.js";
 
 export {
   readJournal,