@indigoai-us/hq-cli 5.47.15 → 5.47.16

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);
+  });
+});

package/src/commands/people.ts

@@ -0,0 +1,240 @@
+/**
+ * `hq people` — read a company's people (membership) records from the local HQ
+ * tree and search/resolve over them.
+ *
+ *   hq people list      [--company <slug>] [--json]
+ *   hq people search <keyword> [--company <slug>] [--json]
+ *   hq people resolve <name>   [--company <slug>] [--json]
+ *
+ * Source of truth is `companies/<company>/people/<person>/meta.yaml`. Every
+ * subcommand operates on exactly ONE company (the active company, or the one
+ * named by `--company`); nothing reads across company boundaries.
+ */
+
+import * as fs from "fs";
+import { Command, Option } from "commander";
+import chalk from "chalk";
+import * as yaml from "js-yaml";
+import { findHqRoot } from "../utils/manifest.js";
+import { manifestPath, type ManifestDoc } from "./cloud-provision.js";
+import {
+  assertSafeCompanySlug,
+  listCompanyPeople,
+  searchPeople,
+  resolveNameToEmail,
+  companyPeopleDir,
+  type PersonRecord,
+} from "../utils/people.js";
+
+interface PeopleScopeOpts {
+  company?: string;
+  hqRoot?: string;
+}
+
+/** Companies that still exist (anything not explicitly `status: archived`). */
+function activeCompanySlugs(manifest: ManifestDoc): string[] {
+  const companies = manifest.companies ?? {};
+  return Object.entries(companies)
+    .filter(([, entry]) => (entry?.status ?? "active") !== "archived")
+    .map(([slug]) => slug)
+    .sort();
+}
+
+/**
+ * Resolve the single company to operate on. Explicit `--company` always wins
+ * (after a path-safety check). Otherwise the active company is inferred from
+ * `companies/manifest.yaml`: if exactly one company exists it's used; if several
+ * do, the caller must disambiguate with `--company`.
+ */
+export function resolveCompanySlug(
+  hqRoot: string,
+  explicit: string | undefined,
+): string {
+  if (explicit) {
+    assertSafeCompanySlug(explicit);
+    return explicit;
+  }
+  const mPath = manifestPath(hqRoot);
+  if (!fs.existsSync(mPath)) {
+    throw new Error(
+      "Could not determine the active company — companies/manifest.yaml not found. " +
+        "Re-run with --company <slug>.",
+    );
+  }
+  let manifest: ManifestDoc;
+  try {
+    manifest = yaml.load(fs.readFileSync(mPath, "utf-8")) as ManifestDoc;
+  } catch (err) {
+    throw new Error(
+      `companies/manifest.yaml is malformed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const slugs = activeCompanySlugs(manifest ?? {});
+  if (slugs.length === 1) return slugs[0];
+  if (slugs.length === 0) {
+    throw new Error(
+      "No companies found in companies/manifest.yaml — re-run with --company <slug>.",
+    );
+  }
+  throw new Error(
+    "Multiple companies found — re-run with --company <slug> to pick one:\n" +
+      slugs.map((s) => `  --company ${s}`).join("\n"),
+  );
+}
+
+/** Resolve the HQ root: explicit override (tests) → cwd walk-up. */
+function resolveHqRoot(opts: PeopleScopeOpts): string {
+  return opts.hqRoot ?? findHqRoot();
+}
+
+function printPeopleTable(people: PersonRecord[]): void {
+  const nameW = Math.max(4, ...people.map((p) => p.name.length));
+  const emailW = Math.max(5, ...people.map((p) => (p.email ?? "—").length));
+  const roleW = Math.max(4, ...people.map((p) => (p.role ?? "—").length));
+  console.log(
+    chalk.bold(
+      [
+        "NAME".padEnd(nameW),
+        "EMAIL".padEnd(emailW),
+        "ROLE".padEnd(roleW),
+        "TYPE",
+      ].join("  "),
+    ),
+  );
+  for (const p of people) {
+    console.log(
+      [
+        p.name.padEnd(nameW),
+        (p.email ?? "—").padEnd(emailW),
+        (p.role ?? "—").padEnd(roleW),
+        p.type ?? "—",
+      ].join("  "),
+    );
+  }
+}
+
+function fail(message: string): never {
+  console.error(chalk.red(message));
+  process.exit(1);
+}
+
+export function registerPeopleCommand(program: Command): void {
+  const people = program
+    .command("people")
+    .description(
+      "List, search, and resolve a company's people (from companies/<co>/people)",
+    )
+    .option(
+      "--company <slug>",
+      "Company slug to scope to (defaults to the active company)",
+    )
+    // Hidden escape hatch for tests / non-standard layouts — point the reader at
+    // an explicit HQ tree root instead of walking up from cwd.
+    .addOption(
+      new Option(
+        "--hq-root <path>",
+        "Override the HQ tree root (advanced)",
+      ).hideHelp(),
+    );
+
+  people
+    .command("list")
+    .description("List all people recorded for the company")
+    .option("--json", "Output JSON instead of a table")
+    .action((opts: { json?: boolean }) => {
+      try {
+        const scope = people.opts() as PeopleScopeOpts;
+        const hqRoot = resolveHqRoot(scope);
+        const slug = resolveCompanySlug(hqRoot, scope.company);
+        const records = listCompanyPeople(hqRoot, slug);
+
+        if (opts.json) {
+          console.log(JSON.stringify(records, null, 2));
+          return;
+        }
+        if (records.length === 0) {
+          console.log(
+            chalk.gray(
+              `No people recorded for '${slug}' (looked in ${companyPeopleDir(hqRoot, slug)}).`,
+            ),
+          );
+          return;
+        }
+        printPeopleTable(records);
+      } catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+      }
+    });
+
+  people
+    .command("search <keyword>")
+    .description("Keyword search over people names and emails")
+    .option("--json", "Output JSON instead of a table")
+    .action((keyword: string, opts: { json?: boolean }) => {
+      try {
+        const scope = people.opts() as PeopleScopeOpts;
+        const hqRoot = resolveHqRoot(scope);
+        const slug = resolveCompanySlug(hqRoot, scope.company);
+        const matches = searchPeople(listCompanyPeople(hqRoot, slug), keyword);
+
+        if (opts.json) {
+          console.log(JSON.stringify(matches, null, 2));
+          return;
+        }
+        if (matches.length === 0) {
+          console.log(chalk.gray(`No people in '${slug}' match "${keyword}".`));
+          return;
+        }
+        printPeopleTable(matches);
+      } catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+      }
+    });
+
+  people
+    .command("resolve <name>")
+    .description("Resolve a person name to their email address")
+    .option("--json", "Output JSON instead of plain text")
+    .action((name: string, opts: { json?: boolean }) => {
+      try {
+        const scope = people.opts() as PeopleScopeOpts;
+        const hqRoot = resolveHqRoot(scope);
+        const slug = resolveCompanySlug(hqRoot, scope.company);
+        const result = resolveNameToEmail(listCompanyPeople(hqRoot, slug), name);
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          if (result.status === "found") return;
+          process.exit(1);
+        }
+
+        switch (result.status) {
+          case "found":
+            // Bare email on stdout so callers can capture it directly.
+            console.log(result.email);
+            return;
+          case "no_email":
+            fail(
+              `Found '${result.person.name}' in '${slug}' but no email is recorded for them.`,
+            );
+            break;
+          case "ambiguous":
+            console.error(
+              chalk.yellow(
+                `"${name}" matches ${result.matches.length} people in '${slug}' — be more specific:`,
+              ),
+            );
+            for (const m of result.matches) {
+              console.error(`  ${m.name}${m.email ? ` <${m.email}>` : ""}`);
+            }
+            process.exit(1);
+            break;
+          case "not_found":
+            fail(`No person matching "${name}" found in '${slug}'.`);
+            break;
+        }
+      } catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+      }
+    });
+}

package/src/index.ts

@@ -36,6 +36,7 @@ import { registerGroupGrantsCommand } from "./commands/group-grants.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
+import { registerPeopleCommand } from "./commands/people.js";
 import { registerDmCommand } from "./commands/dm.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
@@ -166,6 +167,9 @@ registerFilesBrowseCommands(filesCmd);
 
 // Membership management (subcommand group — hq members invite|list|revoke)
 registerMembersCommand(program);
+// People directory (subcommand group — hq people list|search|resolve), reading
+// the local companies/<co>/people store scoped to one company.
+registerPeopleCommand(program);
 registerDmCommand(program);
 
 // Onboarding (top-level — Cognito + vault-service provisioning)