@indigoai-us/hq-cloud 5.30.0 → 5.32.0

package/src/personal-vault.ts

@@ -14,8 +14,14 @@
  *   - `.git`: a git repo's own metadata is hostile to multi-machine
  *     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.
+ *   - `companies/`: the top-level `companies/` directory is never enumerated
+ *     wholesale. Team-backed companies are synced by the runner's
+ *     per-membership fanout (one bucket per company). Individual
+ *     `companies/{slug}/` subdirs MAY be added back via
+ *     `computePersonalCompanySubdirs()` for companies that explicitly
+ *     declare `cloud: false` in `company.yaml` and are not in the operator's
+ *     team-synced membership set — those land under the personal bucket as
+ *     `companies/{slug}/...` keys.
  *   - `repos/`, `workspace/`: per user directive — heavy local-only
  *     content (cloned remotes, session threads) that has no business in
  *     the personal vault.
@@ -41,23 +47,143 @@ export const PERSONAL_VAULT_EXCLUDED_TOP_LEVEL: readonly string[] = [
 ];
 
 /**
- * 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).
+ * Company slugs that are never eligible for the personal-bucket fallback,
+ * regardless of their `cloud:` marker. `_template` is the scaffolding
+ * source for `/newcompany` — copying it into the personal vault would
+ * pollute every machine's vault with the template tree.
+ */
+export const PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS: readonly string[] = [
+  "_template",
+];
+
+export interface PersonalVaultOptions {
+  /**
+   * Slugs of companies that already have their own team bucket (i.e. the
+   * operator has an active Membership row for them). These are excluded
+   * from the personal-bucket fallback so a single company's content never
+   * ends up in two buckets.
+   */
+  teamSyncedSlugs?: ReadonlySet<string>;
+  /**
+   * When true, walk `companies/` and include subdirs that explicitly opt in
+   * via `cloud: false` in their `company.yaml` (after applying the standard
+   * filter: exclude `_template`, exclude team-synced slugs). When false
+   * (the default), `companies/` is never enumerated — same as the legacy
+   * personal-vault scope. Gated behind a runtime flag so the new behavior
+   * stays opt-in until operators explicitly request it via
+   * `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1`.
+   */
+  includeLocalCompanies?: boolean;
+}
+
+/**
+ * Compute absolute paths to share for the personal vault.
+ *
+ * Two sources are concatenated:
+ *   1. Every top-level entry under `hqRoot` whose basename is NOT in
+ *      `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL`.
+ *   2. Every `companies/{slug}/` subdir that opts into the personal
+ *      bucket via `company.yaml: cloud: false`, after excluding (a)
+ *      `_template`, (b) slugs already in `opts.teamSyncedSlugs`, and
+ *      (c) any subdir without an explicit `cloud: false` marker.
+ *
  * 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[] {
+export function computePersonalVaultPaths(
+  hqRoot: string,
+  opts: PersonalVaultOptions = {},
+): string[] {
   let entries: string[];
   try {
     entries = fs.readdirSync(hqRoot);
   } catch {
     return [];
   }
-  return entries
+  const topLevel = entries
     .filter((name) => !PERSONAL_VAULT_EXCLUDED_TOP_LEVEL.includes(name))
     .map((name) => path.join(hqRoot, name));
+  const companySubdirs = opts.includeLocalCompanies === true
+    ? computePersonalCompanySubdirs(hqRoot, opts.teamSyncedSlugs)
+    : [];
+  return [...topLevel, ...companySubdirs];
+}
+
+/**
+ * Discover `companies/{slug}/` subdirs that should sync to the personal
+ * bucket as a fallback for companies the operator has not designated as
+ * team-backed. Filter rules (all must hold):
+ *
+ *   1. The subdir is a directory (skip stray files).
+ *   2. The slug is NOT in `PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS`
+ *      (currently just `_template`).
+ *   3. The slug is NOT in `teamSyncedSlugs` (membership-backed slugs sync
+ *      to their own bucket and must not be double-written).
+ *   4. `companies/{slug}/company.yaml` exists and contains a
+ *      `cloud: false` line. A missing file or `cloud: true` opts the
+ *      directory OUT of the personal vault — silent inclusion would
+ *      capture scratch/dead dirs the user never intended to ship.
+ *
+ * Returns absolute paths.
+ */
+export function computePersonalCompanySubdirs(
+  hqRoot: string,
+  teamSyncedSlugs: ReadonlySet<string> = new Set(),
+): string[] {
+  const companiesRoot = path.join(hqRoot, "companies");
+  let slugs: string[];
+  try {
+    slugs = fs.readdirSync(companiesRoot);
+  } catch {
+    return [];
+  }
+  const eligible: string[] = [];
+  for (const slug of slugs) {
+    if (PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS.includes(slug)) continue;
+    if (teamSyncedSlugs.has(slug)) continue;
+    const subdir = path.join(companiesRoot, slug);
+    let isDir = false;
+    try {
+      isDir = fs.statSync(subdir).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    if (!companyHasCloudFalseMarker(subdir)) continue;
+    eligible.push(subdir);
+  }
+  return eligible;
+}
+
+/**
+ * True iff `{subdir}/company.yaml` exists and contains an explicit
+ * top-level `cloud: false` line. Matches the canonical shape
+ * `/designate-team` writes — that command's awk is the only producer of
+ * this key, and it always emits `cloud: <bool>` at column zero with no
+ * indentation, no quoting, lowercase boolean, optional trailing comment.
+ *
+ * Anchored at column 0 deliberately:
+ *   - rejects `meta:\n  cloud: false` (nested key, would be `meta.cloud`
+ *     in a real YAML parser — false positive for us if we allowed
+ *     arbitrary leading whitespace)
+ *   - rejects `- cloud: false` (list item, also a nested key)
+ *   - rejects flow mappings like `{ cloud: false }`
+ *
+ * Other intentional rejections (lowercase `false` only, no YAML-alt
+ * boolean spellings): `cloud: False`, `cloud: FALSE`, `cloud: no`,
+ * `cloud: off`, `cloud: "false"`, `cloud: 'false'`. None of these are
+ * produced by `/designate-team`; matching them risks confusing
+ * round-trips with hand-edited YAML.
+ */
+function companyHasCloudFalseMarker(subdir: string): boolean {
+  const yamlPath = path.join(subdir, "company.yaml");
+  let text: string;
+  try {
+    text = fs.readFileSync(yamlPath, "utf8");
+  } catch {
+    return false;
+  }
+  return /^cloud:\s*false\b/m.test(text);
 }

package/src/s3.test.ts

@@ -629,4 +629,34 @@ describe("downloadFile", () => {
     expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
     expect(fs.readlinkSync(localPath)).toBe("fresh-target.md");
   });
+
+  it("returns the object's user-metadata (including created-by) for a regular file", async () => {
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([104, 105]); // "hi"
+      })(),
+      Metadata: { "created-by": "alice@example.com", "created-by-sub": "sub-123" },
+    };
+
+    const localPath = path.join(tmpRoot, "authored.md");
+    const result = await downloadFile(makeCtx(), "authored.md", localPath);
+
+    expect(result.metadata?.["created-by"]).toBe("alice@example.com");
+    expect(fs.readFileSync(localPath, "utf-8")).toBe("hi");
+  });
+
+  it("returns the object's user-metadata for a symlink record", async () => {
+    const localPath = path.join(tmpRoot, "authored-link.md");
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array();
+      })(),
+      Metadata: { "hq-symlink-target": "x", "created-by": "bob@example.com" },
+    };
+
+    const result = await downloadFile(makeCtx(), "authored-link.md", localPath);
+
+    expect(result.metadata?.["created-by"]).toBe("bob@example.com");
+    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
+  });
 });

package/src/s3.ts

@@ -279,11 +279,20 @@ export async function uploadSymlink(
   return { etag: response.ETag || "" };
 }
 
+/**
+ * Download an object to localPath and return its S3 user-metadata.
+ *
+ * Materializes regular files and symlink records (the symlink branch
+ * reconstructs the link from the body/marker). The GetObject response
+ * already carries `response.Metadata` (S3 lowercases keys), so we
+ * return it to callers — e.g. the pull loop reads `created-by` to
+ * attribute downloaded files to their author with zero extra network.
+ */
 export async function downloadFile(
   ctx: EntityContext,
   key: string,
   localPath: string,
-): Promise<void> {
+): Promise<{ metadata?: Record<string, string> }> {
   const client = buildClient(ctx);
 
   const response = await client.send(
@@ -362,7 +371,7 @@ export async function downloadFile(
       }
     }
     fs.symlinkSync(symlinkTarget, localPath);
-    return;
+    return { metadata: response.Metadata };
   }
 
   // Symmetric to the symlink branch above: when a key was previously a
@@ -395,6 +404,7 @@ export async function downloadFile(
     chunks.push(Buffer.from(chunk));
   }
   fs.writeFileSync(localPath, Buffer.concat(chunks));
+  return { metadata: response.Metadata };
 }
 
 export interface RemoteFile {