@indigoai-us/hq-cloud 6.14.8 → 6.14.10

package/src/manifest-reconcile.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, describe, expect, it } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import yaml from "js-yaml";
+
+import { reconcileCompanyManifest } from "./manifest-reconcile.js";
+import type { EntityInfo } from "./vault-client.js";
+
+let hqRoot: string | undefined;
+
+afterEach(() => {
+  if (hqRoot) {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+    hqRoot = undefined;
+  }
+});
+
+describe("reconcileCompanyManifest", () => {
+  it("atomically restores one successful cloud entry after the personal leg without replacing existing manifest state", async () => {
+    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-reconcile-"));
+    const companiesDir = path.join(hqRoot, "companies");
+    fs.mkdirSync(path.join(companiesDir, "acme"), { recursive: true });
+    fs.mkdirSync(path.join(companiesDir, "failed"), { recursive: true });
+    fs.mkdirSync(path.join(companiesDir, "deleted"), { recursive: true });
+
+    // This is the older manifest the personal-vault leg pulled after the
+    // cloud-company legs completed. The final merge must retain this state and
+    // add only the live, successful cloud target.
+    const manifestPath = path.join(companiesDir, "manifest.yaml");
+    fs.writeFileSync(
+      manifestPath,
+      `version: 3\nsettings:\n  keep: true\ncompanies:\n  local-only:\n    name: Local Only\n    repos:\n      - repos/local\n  preserved:\n    name: Keep Me\n    cloud_uid: cmp_preserved\n`,
+    );
+
+    const entities: Record<string, EntityInfo> = {
+      cmp_acme: {
+        uid: "cmp_acme",
+        slug: "acme",
+        type: "company",
+        status: "active",
+        name: "Acme Inc",
+        bucketName: "hq-vault-cmp-acme",
+        createdAt: "2026-01-01T00:00:00Z",
+      },
+      cmp_failed: {
+        uid: "cmp_failed",
+        slug: "failed",
+        type: "company",
+        status: "active",
+        name: "Failed Corp",
+        bucketName: "hq-vault-cmp-failed",
+        createdAt: "2026-01-01T00:00:00Z",
+      },
+      cmp_deleted: {
+        uid: "cmp_deleted",
+        slug: "deleted",
+        type: "company",
+        status: "deleted",
+        name: "Deleted Corp",
+        bucketName: "hq-vault-cmp-deleted",
+        createdAt: "2026-01-01T00:00:00Z",
+      },
+    };
+    const options = {
+      hqRoot,
+      targets: [
+        { uid: "cmp_acme", slug: "acme" },
+        { uid: "cmp_failed", slug: "failed" },
+        { uid: "cmp_deleted", slug: "deleted" },
+        { uid: "cmp_missing-directory", slug: "missing-directory" },
+        { uid: "prs_me", slug: "personal", personalMode: true },
+      ],
+      completedCompanySlugs: new Set(["acme", "deleted", "missing-directory", "personal"]),
+      getEntity: async (uid: string) => {
+        const entity = entities[uid];
+        if (!entity) throw new Error("entity not found");
+        return entity;
+      },
+    };
+
+    await reconcileCompanyManifest(options);
+    const firstWrite = fs.readFileSync(manifestPath, "utf8");
+    await reconcileCompanyManifest(options);
+
+    expect(fs.readFileSync(manifestPath, "utf8")).toBe(firstWrite);
+    expect(yaml.load(firstWrite)).toEqual({
+      version: 3,
+      settings: { keep: true },
+      companies: {
+        "local-only": {
+          name: "Local Only",
+          repos: ["repos/local"],
+        },
+        preserved: {
+          name: "Keep Me",
+          cloud_uid: "cmp_preserved",
+        },
+        acme: {
+          name: "Acme Inc",
+          cloud_uid: "cmp_acme",
+          bucket_name: "hq-vault-cmp-acme",
+        },
+      },
+    });
+  });
+});

package/src/manifest-reconcile.ts

@@ -0,0 +1,160 @@
+/**
+ * Reconcile successfully pulled cloud companies into the local manifest.
+ *
+ * The personal-vault leg also carries `companies/manifest.yaml`, so this runs
+ * only after the complete fanout has settled. That makes the locally
+ * materialized cloud companies authoritative for their own manifest entries
+ * without discarding entries the personal vault already had.
+ */
+
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+
+import type { EntityInfo } from "./vault-client.js";
+
+export interface ManifestReconcileTarget {
+  uid: string;
+  slug: string;
+  personalMode?: boolean;
+}
+
+export interface ManifestReconcileOptions {
+  hqRoot: string;
+  targets: readonly ManifestReconcileTarget[];
+  completedCompanySlugs: ReadonlySet<string>;
+  getEntity: (uid: string) => Promise<EntityInfo>;
+}
+
+interface ManifestCompany {
+  name?: unknown;
+  cloud_uid?: unknown;
+  bucket_name?: unknown;
+  [key: string]: unknown;
+}
+
+interface ManifestDocument {
+  companies?: Record<string, ManifestCompany>;
+  [key: string]: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isLiveCompany(entity: EntityInfo, uid: string): boolean {
+  return (
+    entity.uid === uid &&
+    entity.type === "company" &&
+    entity.status === "active" &&
+    typeof entity.name === "string" &&
+    entity.name.length > 0 &&
+    typeof entity.bucketName === "string" &&
+    entity.bucketName.length > 0
+  );
+}
+
+function hasCompanyDirectory(companiesDir: string, slug: string): boolean {
+  const resolvedCompaniesDir = path.resolve(companiesDir);
+  const companyDir = path.resolve(resolvedCompaniesDir, slug);
+  if (path.dirname(companyDir) !== resolvedCompaniesDir) return false;
+  try {
+    return fs.statSync(companyDir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function loadManifest(manifestPath: string): ManifestDocument | null {
+  try {
+    const raw = fs.readFileSync(manifestPath, "utf8");
+    const parsed = yaml.load(raw);
+    return isRecord(parsed) ? (parsed as ManifestDocument) : null;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return {};
+    return null;
+  }
+}
+
+function writeManifestAtomically(manifestPath: string, document: ManifestDocument): void {
+  const temporaryPath = path.join(
+    path.dirname(manifestPath),
+    `.manifest-${process.pid}-${randomUUID()}.yaml`,
+  );
+  fs.writeFileSync(temporaryPath, yaml.dump(document, { lineWidth: -1 }), "utf8");
+  fs.renameSync(temporaryPath, manifestPath);
+}
+
+/**
+ * Atomically merge live, successfully pulled company targets into
+ * `companies/manifest.yaml`. Targets that are personal, incomplete, deleted,
+ * no longer resolvable, or not materialized on disk are intentionally ignored.
+ */
+export async function reconcileCompanyManifest(
+  options: ManifestReconcileOptions,
+): Promise<void> {
+  const companiesDir = path.join(options.hqRoot, "companies");
+  const candidates: Array<{ slug: string; entity: EntityInfo }> = [];
+
+  for (const target of options.targets) {
+    if (
+      target.personalMode === true ||
+      !options.completedCompanySlugs.has(target.slug) ||
+      !hasCompanyDirectory(companiesDir, target.slug)
+    ) {
+      continue;
+    }
+
+    try {
+      const entity = await options.getEntity(target.uid);
+      if (isLiveCompany(entity, target.uid)) {
+        candidates.push({ slug: target.slug, entity });
+      }
+    } catch {
+      // The target is not presently a live, resolvable company. Never mint a
+      // manifest entry from stale fanout data.
+    }
+  }
+
+  if (candidates.length === 0) return;
+
+  const manifestPath = path.join(companiesDir, "manifest.yaml");
+  const document = loadManifest(manifestPath);
+  if (!document) return;
+
+  let companies: Record<string, ManifestCompany>;
+  if (document.companies === undefined) {
+    companies = {};
+    document.companies = companies;
+  } else if (isRecord(document.companies)) {
+    companies = document.companies as Record<string, ManifestCompany>;
+  } else {
+    // A malformed `companies` key is user state; refusing to replace it is
+    // safer than losing a manifest that cannot be interpreted unambiguously.
+    return;
+  }
+
+  let changed = false;
+  for (const { slug, entity } of candidates) {
+    const existing = companies[slug];
+    if (existing !== undefined && !isRecord(existing)) continue;
+    const entry: ManifestCompany = existing ?? {};
+    if (
+      entry.name === entity.name &&
+      entry.cloud_uid === entity.uid &&
+      entry.bucket_name === entity.bucketName
+    ) {
+      continue;
+    }
+    companies[slug] = {
+      ...entry,
+      name: entity.name,
+      cloud_uid: entity.uid,
+      bucket_name: entity.bucketName,
+    };
+    changed = true;
+  }
+
+  if (changed) writeManifestAtomically(manifestPath, document);
+}

package/src/personal-vault.ts

@@ -105,6 +105,21 @@ export interface PersonalVaultOptions {
  */
 export const PERSONAL_VAULT_MANIFEST_KEY = "companies/manifest.yaml";
 
+/**
+ * Release-owned scaffold and reindex-generated wrappers must never be
+ * delete-propagated from the personal vault. They are recreated locally by a
+ * release or `hq reindex`, so an ordinary local absence is not user intent.
+ */
+export function isPersonalVaultDeletionExcluded(key: string): boolean {
+  const normalized = key.split("\\").join("/").replace(/^\.\//, "");
+  return (
+    normalized === "core" ||
+    normalized.startsWith("core/") ||
+    normalized === ".claude/skills" ||
+    normalized.startsWith(".claude/skills/")
+  );
+}
+
 export function computePersonalVaultPaths(
   hqRoot: string,
   opts: PersonalVaultOptions = {},

package/src/s3.test.ts

@@ -93,6 +93,7 @@ import {
   decodeSymlinkMetadataValue,
   FILE_MTIME_META_KEY,
   FILE_BTIME_META_KEY,
+  classifyVaultKey,
   validateVaultUploadKey,
 } from "./s3.js";
 import {
@@ -1450,6 +1451,23 @@ describe("validateVaultUploadKey — direct-S3 key poisoning guard (incident 202
     },
   );
 
+  it.each([
+    [
+      "companies/indigo/knowledge/x.md",
+      "company",
+      "INVALID_KEY_COMPANIES_SCOPED",
+    ],
+    ["bad\x00key.md", "personal", "INVALID_KEY_CONTROL_CHARS"],
+    ["docs/good.md", "personal", null],
+  ] as const)(
+    "classifyVaultKey reports the validator outcome without throwing: %j",
+    (key, scope, code) => {
+      expect(classifyVaultKey(key, scope)).toEqual(
+        code === null ? null : expect.objectContaining({ code }),
+      );
+    },
+  );
+
   it("uploadFile refuses to PUT a companies/-prefixed key into a company (cmp_) vault — no S3 command is sent", async () => {
     await expect(
       uploadFile(makeCtx(), tmpFile, "companies/indigo/knowledge/x.md"),

package/src/s3.ts

@@ -561,67 +561,101 @@ export function toPosixKey(key: string): string {
  * (`cmp_*` → "company", otherwise "personal").
  *
  * Errors carry the same `code` values the server throws so telemetry and
- * operator messaging line up across client and server.
+ * operator messaging line up across client and server. Pull planning also
+ * uses the non-throwing classifier below to keep poison keys away from the
+ * presign transport.
  */
 // Matching control chars is the whole point — block NUL/0x00–0x1F/0x7F in keys
 // (they can smuggle past path checks or corrupt HTTP headers on the signed URL).
 // eslint-disable-next-line no-control-regex
 const KEY_CONTROL_CHARS = /[\x00-\x1F\x7F]/;
 
-export function validateVaultUploadKey(
+export type VaultKeyScope = "company" | "personal";
+
+export interface VaultKeyValidationIssue {
+  code: string;
+  message: string;
+}
+
+/**
+ * Classify a vault key with the same rules as {@link validateVaultUploadKey}
+ * without throwing. Callers that enumerate remote objects can use this before
+ * presigning so permanently-invalid legacy keys remain benign skips.
+ */
+export function classifyVaultKey(
   key: string,
-  scope: "company" | "personal",
-): void {
-  const fail = (message: string, code: string): never => {
-    throw Object.assign(new Error(message), { code });
-  };
+  scope: VaultKeyScope,
+): VaultKeyValidationIssue | null {
   if (key.length === 0) {
-    fail("Invalid key: must not be empty", "INVALID_KEY_EMPTY");
+    return {
+      code: "INVALID_KEY_EMPTY",
+      message: "Invalid key: must not be empty",
+    };
   }
   if (key.startsWith("/")) {
-    fail("Invalid key: leading '/' not allowed", "INVALID_KEY_LEADING_SLASH");
+    return {
+      code: "INVALID_KEY_LEADING_SLASH",
+      message: "Invalid key: leading '/' not allowed",
+    };
   }
   if (key.endsWith("/")) {
-    fail(
-      "Invalid key: trailing '/' (folder marker, not an object)",
-      "INVALID_KEY_TRAILING_SLASH",
-    );
+    return {
+      code: "INVALID_KEY_TRAILING_SLASH",
+      message: "Invalid key: trailing '/' (folder marker, not an object)",
+    };
   }
   if (scope === "company" && key.startsWith("companies/")) {
-    fail(
-      "Invalid key: vault keys are bucket-relative and the vault is already " +
+    return {
+      code: "INVALID_KEY_COMPANIES_SCOPED",
+      message:
+        "Invalid key: vault keys are bucket-relative and the vault is already " +
         "company-scoped — do not prefix with 'companies/<slug>/'. This " +
         "usually means a stale doubled local tree " +
         "(companies/<slug>/companies/<slug>/…); remove the inner copy.",
-      "INVALID_KEY_COMPANIES_SCOPED",
-    );
+    };
   }
   if (KEY_CONTROL_CHARS.test(key)) {
-    fail("Invalid key: contains control characters", "INVALID_KEY_CONTROL_CHARS");
+    return {
+      code: "INVALID_KEY_CONTROL_CHARS",
+      message: "Invalid key: contains control characters",
+    };
   }
   if (key.includes("\\")) {
-    // Unreachable after toPosixKey normalization at the upload boundary, but
-    // kept so the validator mirrors the server rule set 1:1 for other callers.
-    fail(
-      "Invalid key: backslash separators are not allowed — vault keys are POSIX ('/')",
-      "INVALID_KEY_BACKSLASH",
-    );
+    return {
+      code: "INVALID_KEY_BACKSLASH",
+      message:
+        "Invalid key: backslash separators are not allowed — vault keys are POSIX ('/')",
+    };
   }
   if (key.includes("//")) {
-    fail("Invalid key: consecutive slashes not allowed", "INVALID_KEY_DOUBLE_SLASH");
+    return {
+      code: "INVALID_KEY_DOUBLE_SLASH",
+      message: "Invalid key: consecutive slashes not allowed",
+    };
   }
   for (const segment of key.split("/")) {
     if (segment === "." || segment === "..") {
-      fail(
-        "Invalid key: '.' and '..' path components are not allowed",
-        "INVALID_KEY_DOT_COMPONENT",
-      );
+      return {
+        code: "INVALID_KEY_DOT_COMPONENT",
+        message: "Invalid key: '.' and '..' path components are not allowed",
+      };
     }
   }
+  return null;
+}
+
+export function validateVaultUploadKey(
+  key: string,
+  scope: VaultKeyScope,
+): void {
+  const issue = classifyVaultKey(key, scope);
+  if (issue !== null) {
+    throw Object.assign(new Error(issue.message), { code: issue.code });
+  }
 }
 
 /** Scope for {@link validateVaultUploadKey}, derived from the entity uid. */
-function uploadScopeFor(ctx: EntityContext): "company" | "personal" {
+function uploadScopeFor(ctx: EntityContext): VaultKeyScope {
   return ctx.uid.startsWith("cmp_") ? "company" : "personal";
 }
 
@@ -775,6 +809,7 @@ export async function downloadFile(
   ctx: EntityContext,
   key: string,
   localPath: string,
+  options: { beforeReplace?: () => void } = {},
 ): Promise<{
   metadata?: Record<string, string>;
   contentHash?: string;
@@ -868,6 +903,7 @@ export async function downloadFile(
     const tempPath = downloadTempPath(localPath);
     try {
       fs.symlinkSync(symlinkTarget, tempPath);
+      options.beforeReplace?.();
       fs.renameSync(tempPath, localPath);
     } catch (err) {
       removeTempPath(tempPath);
@@ -977,6 +1013,7 @@ export async function downloadFile(
       }
     }
 
+    options.beforeReplace?.();
     fs.renameSync(tempPath, localPath);
     tempReady = false;
   } finally {

package/src/types.ts

@@ -26,6 +26,8 @@ export interface JournalEntry {
   size: number;
   syncedAt: string;
   direction: "up" | "down";
+  /** Kind of local object represented by this entry. */
+  kind?: "file" | "symlink";
   /**
    * Cognito `sub` of the file's author, captured from the object's
    * `created-by-sub` S3 user-metadata at download time (zero extra network —
@@ -72,6 +74,17 @@ export interface JournalEntry {
    */
   removedAt?: string;
   removedReason?: "scope_shrink" | "narrow_apply" | "manual" | "local-delete";
+  /**
+   * Explicit local-delete intent. Unlike the legacy `removedReason` marker,
+   * this is bound to the exact synced remote revision and local object shape
+   * that the user approved for deletion.
+   */
+  localDeleteIntent?: {
+    version: 1;
+    remoteEtag: string;
+    localHash: string;
+    localKind: "file" | "symlink";
+  };
   /**
    * Durable automatic-pull retention marker. Set when a scope shrink keeps an
    * out-of-scope caller-authored or unknown-author entry on disk instead of