@indigoai-us/hq-cli 5.47.15 → 5.47.17

package/src/commands/files-delete.test.ts

@@ -38,6 +38,7 @@ import { Command } from "commander";
 import {
   registerFilesCommand,
   runFilesDelete,
+  stripRedundantCompanyScope,
   FilesDeleteHttpError,
   formatFilesDeleteError,
   type FilesDeleteResponse,
@@ -242,6 +243,137 @@ describe("hq files delete — root/empty prefix rejected client-side", () => {
   }
 });
 
+// HQ-8F: a caller who pastes an HQ *local* tree path (`companies/<slug>/…`)
+// over-prefixes the bucket-relative vault key; the server rejects it with a 400
+// (INVALID_PREFIX_COMPANIES_SCOPED), the source of the recurring warning. The
+// CLI now strips the redundant scope BEFORE sending, so the local-looking path
+// is gracefully normalized to bucket-relative.
+describe("stripRedundantCompanyScope (HQ-8F, pure)", () => {
+  it("strips a leading companies/<slug>/ to the bucket-relative remainder", () => {
+    expect(stripRedundantCompanyScope("companies/acme/projects/foo")).toEqual({
+      prefix: "projects/foo",
+      strippedSlug: "acme",
+    });
+    expect(stripRedundantCompanyScope("companies/acme/projects/foo/*")).toEqual({
+      prefix: "projects/foo/*",
+      strippedSlug: "acme",
+    });
+  });
+
+  it("returns an EMPTY remainder for the company-root spellings (→ root-reject)", () => {
+    expect(stripRedundantCompanyScope("companies/acme")).toEqual({
+      prefix: "",
+      strippedSlug: "acme",
+    });
+    expect(stripRedundantCompanyScope("companies/acme/")).toEqual({
+      prefix: "",
+      strippedSlug: "acme",
+    });
+  });
+
+  it("leaves an already bucket-relative prefix untouched (null)", () => {
+    expect(stripRedundantCompanyScope("projects/foo/*")).toBeNull();
+    expect(stripRedundantCompanyScope("reports/q3/")).toBeNull();
+    // A non-scope path that merely starts with the word "companies" is NOT a
+    // scope prefix and must be left alone.
+    expect(stripRedundantCompanyScope("companiesreport/x")).toBeNull();
+  });
+});
+
+describe("hq files delete — HQ-8F company-scope normalization", () => {
+  it("strips companies/<slug>/ and sends the BUCKET-RELATIVE prefix (no 400)", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: true, matched: 1, keys: ["projects/foo/a.md"] }),
+    );
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ matched: 1, deleted: 1, tombstoned: 1, keys: ["projects/foo/a.md"] }),
+    );
+
+    await runFilesDelete(
+      {
+        // Trailing slash → also exercises the `/` → `/*` glob normalization.
+        prefix: "companies/acme/projects/foo/",
+        dryRun: false,
+        yes: true,
+        companySlug: undefined,
+      },
+      { confirm: async () => true },
+    );
+
+    const bodies = deleteCallBodies();
+    // Both the preview and the delete carry the stripped, bucket-relative prefix.
+    expect(bodies.map((b) => b.prefix)).toEqual(["projects/foo/*", "projects/foo/*"]);
+    expect(printedErr()).toContain("stripped redundant 'companies/acme/'");
+  });
+
+  it("a bare companies/<slug> strips to empty → root-reject, no network call", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["files", "delete", "companies/acme", "--yes"], {
+        from: "user",
+      }),
+    ).rejects.toThrow(/__EXIT__:1/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(printedErr()).toContain("Refusing to delete the vault root");
+  });
+});
+
+// HQ-CA: the EXACT-KEY sibling of HQ-8F. When the over-prefixed path has no
+// trailing slash and no wildcard (a literal key like
+// `companies/<slug>/notes/foo.md`), the server takes the exact-key branch where
+// `validateObjectKey` — not `validatePrefix` — rejects it with a 400 ("Invalid
+// key: … do not prefix with 'companies/<slug>/'."). The same client-side strip
+// runs UPSTREAM of the server's exact-vs-glob split, so it normalizes the exact
+// key to bucket-relative and the 400 is never emitted. This locks that path,
+// which #117 only exercised via the trailing-slash (glob) spelling.
+describe("hq files delete — HQ-CA exact-key company-scope normalization", () => {
+  it("strips companies/<slug>/ from an EXACT key and sends the bucket-relative key (no glob, no 400)", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({
+        dryRun: true,
+        mode: "exact",
+        prefix: "notes/foo.md",
+        matched: 1,
+        keys: ["notes/foo.md"],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({
+        mode: "exact",
+        prefix: "notes/foo.md",
+        matched: 1,
+        deleted: 1,
+        tombstoned: 1,
+        keys: ["notes/foo.md"],
+      }),
+    );
+
+    await runFilesDelete(
+      {
+        // No trailing slash, no wildcard → server takes the EXACT-key branch.
+        prefix: "companies/acme/notes/foo.md",
+        dryRun: false,
+        yes: true,
+        companySlug: undefined,
+      },
+      { confirm: async () => true },
+    );
+
+    const bodies = deleteCallBodies();
+    // Preview + delete both carry the stripped, bucket-relative EXACT key —
+    // never the `companies/acme/...` over-prefix that 400s, and never glob-ified
+    // into a prefix delete.
+    expect(bodies.map((b) => b.prefix)).toEqual(["notes/foo.md", "notes/foo.md"]);
+    for (const b of bodies) {
+      expect(b.prefix.startsWith("companies/")).toBe(false);
+      expect(b.prefix).not.toContain("*");
+    }
+    expect(printedErr()).toContain("stripped redundant 'companies/acme/'");
+  });
+});
+
 describe("hq files delete — server error mapping", () => {
   it("403 surfaces a clear not-authorized message and exits 1", async () => {
     fetchSpy.mockResolvedValueOnce(membershipResponse());

package/src/commands/files.ts

@@ -782,17 +782,58 @@ function printKeyPreview(resp: FilesDeleteResponse): void {
   }
 }
 
+/**
+ * The vault bucket is already company-scoped, so a delete prefix must be
+ * BUCKET-RELATIVE (e.g. `projects/foo/*`). A caller who pastes an HQ *local*
+ * tree path (`companies/<slug>/projects/foo`) over-prefixes it; the server then
+ * rejects it with INVALID_PREFIX_COMPANIES_SCOPED (HTTP 400), the source of the
+ * recurring Sentry warning HQ-8F. Strip a redundant leading `companies/<slug>/`
+ * so the local-looking path is normalized to the bucket-relative key the vault
+ * actually stores. Returns the stripped slug for a one-line notice, or null when
+ * there was nothing to strip. Pure → unit-testable.
+ *
+ * This runs UPSTREAM of the server's exact-vs-glob branch, so it covers both
+ * the glob spelling (`companies/<slug>/projects/foo/*` → `validatePrefix`,
+ * HQ-8F) and the EXACT-key spelling (`companies/<slug>/notes/foo.md` →
+ * `validateObjectKey`, HQ-CA) with the same normalization.
+ */
+export function stripRedundantCompanyScope(
+  prefix: string,
+): { prefix: string; strippedSlug: string } | null {
+  const m = /^companies\/([^/]+)(?:\/(.*))?$/.exec(prefix);
+  if (!m) return null;
+  return { prefix: m[2] ?? "", strippedSlug: m[1] };
+}
+
 export async function runFilesDelete(
   params: RunFilesDeleteParams,
   deps: { confirm?: ConfirmFn } = {},
 ): Promise<void> {
   const confirm = deps.confirm ?? realConfirm;
 
+  // The vault is already company-scoped — a `companies/<slug>/` prefix is the HQ
+  // LOCAL tree layout, not a vault key, and the server 400s it (HQ-8F). Strip it
+  // here so a pasted local path is gracefully normalized to bucket-relative
+  // BEFORE the dry-run/preview (so the operator still sees the exact keys and
+  // confirms the right target). If stripping empties the prefix, the root-reject
+  // below catches it with a clear message.
+  const scope = stripRedundantCompanyScope(params.prefix);
+  if (scope) {
+    console.error(
+      chalk.yellow(
+        `Note: stripped redundant 'companies/${scope.strippedSlug}/' — the vault ` +
+          `is already company-scoped; using bucket-relative ` +
+          `'${scope.prefix || "(root)"}'.`,
+      ),
+    );
+  }
+  const rawPrefix = scope ? scope.prefix : params.prefix;
+
   // Normalize exactly as the share/unshare/acl paths do (trailing `/` → `/*`),
   // then reject the root/empty prefix CLIENT-side so a typo never reaches the
   // server as a vault-wide delete. The server enforces this too (defense in
   // depth), but failing fast here is clearer and avoids a wasted round-trip.
-  const normalized = normalizeFilePrefix(params.prefix);
+  const normalized = normalizeFilePrefix(rawPrefix);
   if (normalized === "" || normalized === "*" || normalized === "/*") {
     console.error(
       chalk.red(

package/src/commands/people.test.ts

@@ -0,0 +1,426 @@
+/**
+ * Unit tests for the `hq people` capability:
+ *   - utils/people.ts — parse, list, search, resolve (pure + filesystem)
+ *   - people.ts       — active-company resolution + wired list/search/resolve
+ */
+
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  assertSafeCompanySlug,
+  companyPeopleDir,
+  parsePersonMeta,
+  listCompanyPeople,
+  searchPeople,
+  resolveNameToEmail,
+  type PersonRecord,
+} from "../utils/people.js";
+import { registerPeopleCommand, resolveCompanySlug } from "./people.js";
+
+// ---------------------------------------------------------------------------
+// Filesystem fixture helpers
+// ---------------------------------------------------------------------------
+
+let tmpRoot: string;
+
+function makePerson(
+  company: string,
+  slug: string,
+  meta: Record<string, unknown> | string,
+): void {
+  const dir = path.join(tmpRoot, "companies", company, "people", slug);
+  fs.mkdirSync(dir, { recursive: true });
+  const body =
+    typeof meta === "string"
+      ? meta
+      : Object.entries(meta)
+          .map(([k, v]) =>
+            Array.isArray(v)
+              ? `${k}: [${v.join(", ")}]`
+              : `${k}: ${JSON.stringify(v)}`,
+          )
+          .join("\n");
+  fs.writeFileSync(path.join(dir, "meta.yaml"), body + "\n");
+}
+
+function writeCompaniesManifest(
+  companies: Record<string, Record<string, unknown> | null>,
+): void {
+  const dir = path.join(tmpRoot, "companies");
+  fs.mkdirSync(dir, { recursive: true });
+  const yamlBody =
+    "companies:\n" +
+    Object.entries(companies)
+      .map(([slug, entry]) => {
+        if (!entry) return `  ${slug}:`;
+        const fields = Object.entries(entry)
+          .map(([k, v]) => `    ${k}: ${JSON.stringify(v)}`)
+          .join("\n");
+        return `  ${slug}:\n${fields}`;
+      })
+      .join("\n") +
+    "\n";
+  fs.writeFileSync(path.join(dir, "manifest.yaml"), yamlBody);
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-people-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// assertSafeCompanySlug
+// ---------------------------------------------------------------------------
+
+describe("assertSafeCompanySlug", () => {
+  it("accepts ordinary slugs", () => {
+    expect(() => assertSafeCompanySlug("indigo")).not.toThrow();
+    expect(() => assertSafeCompanySlug("acme-co_1.2")).not.toThrow();
+  });
+
+  it("rejects path-traversal and separators", () => {
+    expect(() => assertSafeCompanySlug("..")).toThrow();
+    expect(() => assertSafeCompanySlug("a/b")).toThrow();
+    expect(() => assertSafeCompanySlug("../etc")).toThrow();
+    expect(() => assertSafeCompanySlug("")).toThrow();
+  });
+
+  it("rejects reserved slugs", () => {
+    expect(() => assertSafeCompanySlug("personal")).toThrow(/reserved/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parsePersonMeta
+// ---------------------------------------------------------------------------
+
+describe("parsePersonMeta", () => {
+  it("parses a full record and trims fields", () => {
+    const rec = parsePersonMeta(
+      "name: Jane Smith\nemail: jane@example.com\ntype: internal\nrole: Head of Eng\ntags: [eng, lead]\n",
+      "jane-smith",
+      "/x/meta.yaml",
+    );
+    expect(rec).toEqual({
+      slug: "jane-smith",
+      name: "Jane Smith",
+      email: "jane@example.com",
+      type: "internal",
+      role: "Head of Eng",
+      tags: ["eng", "lead"],
+      source: "/x/meta.yaml",
+    });
+  });
+
+  it("returns null when name is missing or blank", () => {
+    expect(parsePersonMeta("email: a@b.com\n", "x", "/x")).toBeNull();
+    expect(parsePersonMeta("name: '   '\n", "x", "/x")).toBeNull();
+  });
+
+  it("returns null for empty / non-object docs", () => {
+    expect(parsePersonMeta("", "x", "/x")).toBeNull();
+    expect(parsePersonMeta("- a\n- b\n", "x", "/x")).toBeNull();
+  });
+
+  it("throws on unparseable yaml", () => {
+    expect(() => parsePersonMeta("name: [unterminated\n", "x", "/x")).toThrow(
+      /Failed to parse/,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listCompanyPeople
+// ---------------------------------------------------------------------------
+
+describe("listCompanyPeople", () => {
+  it("returns [] when the company has no people directory", () => {
+    writeCompaniesManifest({ acme: { status: "active" } });
+    expect(listCompanyPeople(tmpRoot, "acme")).toEqual([]);
+  });
+
+  it("reads people, skips _scaffolding, nameless, and meta-less folders, sorted by name", () => {
+    makePerson("acme", "zed", { name: "Zed Zebra", email: "zed@acme.com" });
+    makePerson("acme", "ann", { name: "Ann Apple", email: "ann@acme.com" });
+    makePerson("acme", "_example", { name: "Template Person" });
+    makePerson("acme", "nameless", { email: "noone@acme.com" });
+    // folder with no meta.yaml
+    fs.mkdirSync(path.join(tmpRoot, "companies", "acme", "people", "empty"), {
+      recursive: true,
+    });
+
+    const people = listCompanyPeople(tmpRoot, "acme");
+    expect(people.map((p) => p.name)).toEqual(["Ann Apple", "Zed Zebra"]);
+  });
+
+  it("never reads outside the named company (tenancy)", () => {
+    makePerson("acme", "ann", { name: "Ann Apple", email: "ann@acme.com" });
+    makePerson("other", "bob", { name: "Bob Other", email: "bob@other.com" });
+    const people = listCompanyPeople(tmpRoot, "acme");
+    expect(people.map((p) => p.name)).toEqual(["Ann Apple"]);
+  });
+
+  it("rejects an unsafe company slug", () => {
+    expect(() => listCompanyPeople(tmpRoot, "../other")).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// searchPeople
+// ---------------------------------------------------------------------------
+
+const SAMPLE: PersonRecord[] = [
+  { slug: "jane-smith", name: "Jane Smith", email: "jane@example.com", source: "a" },
+  { slug: "john-doe", name: "John Doe", email: "john@acme.com", source: "b" },
+  { slug: "janet-lee", name: "Janet Lee", source: "c" },
+];
+
+describe("searchPeople", () => {
+  it("matches on name (case-insensitive)", () => {
+    // "jane" is a substring of both "Jane Smith" and "Janet Lee".
+    expect(searchPeople(SAMPLE, "jane").map((p) => p.slug)).toEqual([
+      "jane-smith",
+      "janet-lee",
+    ]);
+    expect(searchPeople(SAMPLE, "smith").map((p) => p.slug)).toEqual([
+      "jane-smith",
+    ]);
+    expect(searchPeople(SAMPLE, "JAN").map((p) => p.slug)).toEqual([
+      "jane-smith",
+      "janet-lee",
+    ]);
+  });
+
+  it("matches on email", () => {
+    expect(searchPeople(SAMPLE, "acme.com").map((p) => p.slug)).toEqual([
+      "john-doe",
+    ]);
+  });
+
+  it("matches on slug", () => {
+    expect(searchPeople(SAMPLE, "janet-lee").map((p) => p.slug)).toEqual([
+      "janet-lee",
+    ]);
+  });
+
+  it("returns nothing for an empty/whitespace keyword", () => {
+    expect(searchPeople(SAMPLE, "")).toEqual([]);
+    expect(searchPeople(SAMPLE, "   ")).toEqual([]);
+  });
+
+  it("returns nothing when no one matches", () => {
+    expect(searchPeople(SAMPLE, "zzz")).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveNameToEmail
+// ---------------------------------------------------------------------------
+
+describe("resolveNameToEmail", () => {
+  it("resolves an exact name to its email", () => {
+    expect(resolveNameToEmail(SAMPLE, "Jane Smith")).toEqual({
+      status: "found",
+      email: "jane@example.com",
+      person: SAMPLE[0],
+    });
+  });
+
+  it("is case-insensitive on exact name", () => {
+    const r = resolveNameToEmail(SAMPLE, "jane smith");
+    expect(r.status).toBe("found");
+  });
+
+  it("prefers an exact name over looser substring matches", () => {
+    const people: PersonRecord[] = [
+      { slug: "jan", name: "Jan", email: "jan@x.com", source: "a" },
+      { slug: "jana", name: "Janabc", email: "jana@x.com", source: "b" },
+    ];
+    expect(resolveNameToEmail(people, "Jan")).toMatchObject({
+      status: "found",
+      email: "jan@x.com",
+    });
+  });
+
+  it("resolves via slug when name doesn't match exactly", () => {
+    expect(resolveNameToEmail(SAMPLE, "john-doe")).toMatchObject({
+      status: "found",
+      email: "john@acme.com",
+    });
+  });
+
+  it("reports ambiguity when a substring matches several", () => {
+    const r = resolveNameToEmail(SAMPLE, "jan");
+    expect(r.status).toBe("ambiguous");
+    if (r.status === "ambiguous") {
+      expect(r.matches.map((m) => m.slug)).toEqual(["jane-smith", "janet-lee"]);
+    }
+  });
+
+  it("reports no_email when the sole match has no email", () => {
+    expect(resolveNameToEmail(SAMPLE, "Janet Lee")).toMatchObject({
+      status: "no_email",
+    });
+  });
+
+  it("reports not_found when nothing matches", () => {
+    expect(resolveNameToEmail(SAMPLE, "Nobody")).toEqual({
+      status: "not_found",
+    });
+    expect(resolveNameToEmail(SAMPLE, "   ")).toEqual({ status: "not_found" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveCompanySlug
+// ---------------------------------------------------------------------------
+
+describe("resolveCompanySlug", () => {
+  it("passes through an explicit, valid slug", () => {
+    expect(resolveCompanySlug(tmpRoot, "indigo")).toBe("indigo");
+  });
+
+  it("rejects an explicit unsafe slug", () => {
+    expect(() => resolveCompanySlug(tmpRoot, "../escape")).toThrow();
+  });
+
+  it("defaults to the sole company in the manifest", () => {
+    writeCompaniesManifest({ indigo: { status: "active" } });
+    expect(resolveCompanySlug(tmpRoot, undefined)).toBe("indigo");
+  });
+
+  it("ignores archived companies when defaulting", () => {
+    writeCompaniesManifest({
+      indigo: { status: "active" },
+      old: { status: "archived" },
+    });
+    expect(resolveCompanySlug(tmpRoot, undefined)).toBe("indigo");
+  });
+
+  it("requires --company when several companies exist", () => {
+    writeCompaniesManifest({ a: { status: "active" }, b: { status: "active" } });
+    expect(() => resolveCompanySlug(tmpRoot, undefined)).toThrow(
+      /Multiple companies/,
+    );
+  });
+
+  it("errors clearly when the manifest is absent", () => {
+    expect(() => resolveCompanySlug(tmpRoot, undefined)).toThrow(
+      /manifest\.yaml not found/,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// companyPeopleDir
+// ---------------------------------------------------------------------------
+
+describe("companyPeopleDir", () => {
+  it("builds the scoped path", () => {
+    expect(companyPeopleDir("/hq", "indigo")).toBe(
+      path.join("/hq", "companies", "indigo", "people"),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Wired CLI surface (list / search / resolve)
+// ---------------------------------------------------------------------------
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride(); // throw instead of process.exit on commander errors
+  registerPeopleCommand(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<void> {
+  await buildProgram().parseAsync(["node", "hq", ...args]);
+}
+
+describe("hq people (wired)", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let errSpy: ReturnType<typeof vi.spyOn>;
+  let exitSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    writeCompaniesManifest({ acme: { status: "active" } });
+    makePerson("acme", "jane-smith", {
+      name: "Jane Smith",
+      email: "jane@acme.com",
+      role: "CEO",
+      type: "internal",
+    });
+    makePerson("acme", "john-doe", {
+      name: "John Doe",
+      email: "john@acme.com",
+      type: "internal",
+    });
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(((): never => {
+      throw new Error("__exit__");
+    }) as never);
+  });
+
+  it("list --json emits both people", async () => {
+    await run(["people", "list", "--company", "acme", "--hq-root", tmpRoot, "--json"]);
+    const out = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(out.map((p: PersonRecord) => p.name).sort()).toEqual([
+      "Jane Smith",
+      "John Doe",
+    ]);
+  });
+
+  it("search narrows to the matching person", async () => {
+    await run([
+      "people",
+      "search",
+      "jane",
+      "--company",
+      "acme",
+      "--hq-root",
+      tmpRoot,
+      "--json",
+    ]);
+    const out = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(out).toHaveLength(1);
+    expect(out[0].email).toBe("jane@acme.com");
+  });
+
+  it("resolve prints the bare email on stdout", async () => {
+    await run([
+      "people",
+      "resolve",
+      "Jane Smith",
+      "--company",
+      "acme",
+      "--hq-root",
+      tmpRoot,
+    ]);
+    expect(logSpy).toHaveBeenCalledWith("jane@acme.com");
+  });
+
+  it("resolve exits non-zero when not found", async () => {
+    await expect(
+      run([
+        "people",
+        "resolve",
+        "Nobody",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+      ]),
+    ).rejects.toThrow("__exit__");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});