@indigoai-us/hq-cli 5.47.15 → 5.47.16

package/dist/commands/people.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `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 { Command } from "commander";
+/**
+ * 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 declare function resolveCompanySlug(hqRoot: string, explicit: string | undefined): string;
+export declare function registerPeopleCommand(program: Command): void;
+//# sourceMappingURL=people.d.ts.map

package/dist/commands/people.js

@@ -0,0 +1,187 @@
+/**
+ * `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.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="076b7f64-6626-5733-8992-ab9361a3e31d")}catch(e){}}();
+import * as fs from "fs";
+import { Option } from "commander";
+import chalk from "chalk";
+import * as yaml from "js-yaml";
+import { findHqRoot } from "../utils/manifest.js";
+import { manifestPath } from "./cloud-provision.js";
+import { assertSafeCompanySlug, listCompanyPeople, searchPeople, resolveNameToEmail, companyPeopleDir, } from "../utils/people.js";
+/** Companies that still exist (anything not explicitly `status: archived`). */
+function activeCompanySlugs(manifest) {
+    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, explicit) {
+    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;
+    try {
+        manifest = yaml.load(fs.readFileSync(mPath, "utf-8"));
+    }
+    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) {
+    return opts.hqRoot ?? findHqRoot();
+}
+function printPeopleTable(people) {
+    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) {
+    console.error(chalk.red(message));
+    process.exit(1);
+}
+export function registerPeopleCommand(program) {
+    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) => {
+        try {
+            const scope = people.opts();
+            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, opts) => {
+        try {
+            const scope = people.opts();
+            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, opts) => {
+        try {
+            const scope = people.opts();
+            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));
+        }
+    });
+}
+//# sourceMappingURL=people.js.map
+//# debugId=076b7f64-6626-5733-8992-ab9361a3e31d

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="964b8c71-056c-51fb-893a-d51f8f6ad5d9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aeb143c7-7e19-5999-b6cb-790fc79034cc")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -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";
@@ -134,6 +135,9 @@ const filesCmd = registerFilesCommand(program);
 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)
 registerOnboardCommand(program);
@@ -180,4 +184,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=964b8c71-056c-51fb-893a-d51f8f6ad5d9
+//# debugId=aeb143c7-7e19-5999-b6cb-790fc79034cc

package/dist/utils/people.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Company people (membership) directory reader + search.
+ *
+ * The local source of truth for "who belongs to a company" is the per-company
+ * people store on disk:
+ *
+ *     companies/<company-slug>/people/<person-slug>/meta.yaml
+ *
+ * Each `meta.yaml` carries at least `name` and `type` ("internal" | "external")
+ * plus optional `email`, `role`, `organization`, `tags`, etc. (see
+ * `companies/_template/people/_example/meta.yaml` for the canonical schema).
+ *
+ * Everything here is scoped to ONE company directory. Callers resolve a single
+ * company slug up front; nothing in this module ever enumerates or reads across
+ * company boundaries — HQ tenancy rules forbid cross-company member lookups.
+ */
+/** A single person/member record parsed from a `people/<slug>/meta.yaml`. */
+export interface PersonRecord {
+    /** Folder slug under `companies/<company>/people/<slug>/`. */
+    slug: string;
+    /** Display name (required field in `meta.yaml`). */
+    name: string;
+    /** Contact email, when recorded. */
+    email?: string;
+    /** "internal" (team member) | "external" (client, vendor, …). */
+    type?: string;
+    /** Role/title inside (or relative to) the company. */
+    role?: string;
+    /** External-only: the person's own organization. */
+    organization?: string;
+    /** Freeform tags for filtering. */
+    tags?: string[];
+    /** Absolute path to the `meta.yaml` this record was parsed from. */
+    source: string;
+}
+export declare function assertSafeCompanySlug(slug: string): void;
+/** Absolute path to a company's `people/` directory. */
+export declare function companyPeopleDir(hqRoot: string, companySlug: string): string;
+/**
+ * Parse a single `meta.yaml` body into a `PersonRecord`. Returns `null` when the
+ * file is empty, unparseable, or has no usable `name` — a person record without
+ * a name can't be listed, searched, or resolved, so it's skipped rather than
+ * surfaced as a half-row. Exported for unit testing.
+ */
+export declare function parsePersonMeta(raw: string, slug: string, source: string): PersonRecord | null;
+/**
+ * List every person recorded for ONE company. Reads
+ * `companies/<companySlug>/people/<personSlug>/meta.yaml` for each person
+ * folder.
+ *
+ * - Folders whose name starts with `_` are skipped (e.g. the `_example`
+ *   template that ships in `companies/_template/people/`).
+ * - Folders without a `meta.yaml`, or whose `meta.yaml` has no `name`, are
+ *   skipped silently — they aren't members yet.
+ * - Returns `[]` when the company has no `people/` directory at all.
+ *
+ * Results are sorted by name (case-insensitive) for stable output.
+ */
+export declare function listCompanyPeople(hqRoot: string, companySlug: string): PersonRecord[];
+/**
+ * Case-insensitive keyword search over a person's NAME and EMAIL (plus the
+ * folder slug, which is a normalized alias of the name). Pure — operates on an
+ * already-loaded list so it's trivially testable and reusable.
+ *
+ * An empty/whitespace keyword matches nothing (callers should treat that as a
+ * usage error rather than "return everyone").
+ */
+export declare function searchPeople(people: PersonRecord[], keyword: string): PersonRecord[];
+/** Outcome of resolving a name to an email address. */
+export type ResolveResult = {
+    status: "found";
+    email: string;
+    person: PersonRecord;
+} | {
+    status: "no_email";
+    person: PersonRecord;
+} | {
+    status: "ambiguous";
+    matches: PersonRecord[];
+} | {
+    status: "not_found";
+};
+/**
+ * Resolve a person NAME to their email, built on top of {@link searchPeople}.
+ *
+ * Match precedence (narrowest first) so a precise query isn't drowned out by
+ * looser substring hits:
+ *   1. exact name match (case-insensitive, trimmed)
+ *   2. exact folder-slug match
+ *   3. substring search over name/email/slug
+ *
+ * The first tier that yields any match decides the result:
+ *   - exactly one match with an email  → `found`
+ *   - exactly one match, no email      → `no_email`
+ *   - more than one match              → `ambiguous` (caller disambiguates)
+ *   - no match in any tier             → `not_found`
+ */
+export declare function resolveNameToEmail(people: PersonRecord[], name: string): ResolveResult;
+//# sourceMappingURL=people.d.ts.map

package/dist/utils/people.js

@@ -0,0 +1,168 @@
+/**
+ * Company people (membership) directory reader + search.
+ *
+ * The local source of truth for "who belongs to a company" is the per-company
+ * people store on disk:
+ *
+ *     companies/<company-slug>/people/<person-slug>/meta.yaml
+ *
+ * Each `meta.yaml` carries at least `name` and `type` ("internal" | "external")
+ * plus optional `email`, `role`, `organization`, `tags`, etc. (see
+ * `companies/_template/people/_example/meta.yaml` for the canonical schema).
+ *
+ * Everything here is scoped to ONE company directory. Callers resolve a single
+ * company slug up front; nothing in this module ever enumerates or reads across
+ * company boundaries — HQ tenancy rules forbid cross-company member lookups.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aac5adc3-c336-5d9a-8a1a-edaf16ef4c11")}catch(e){}}();
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+/**
+ * Company slugs map directly onto a filesystem path segment, so we validate
+ * them before joining to keep a malicious or fat-fingered `--company` value
+ * from escaping the `companies/` tree. Mirrors the slug rules used by
+ * cloud-provision.
+ */
+const COMPANY_SLUG_REGEX = /^[A-Za-z0-9._-]+$/;
+const FORBIDDEN_COMPANY_SLUGS = new Set(["personal", ".", ".."]);
+export function assertSafeCompanySlug(slug) {
+    if (!slug || !COMPANY_SLUG_REGEX.test(slug)) {
+        throw new Error(`Invalid company slug "${slug}" — must match ${COMPANY_SLUG_REGEX.source}`);
+    }
+    if (FORBIDDEN_COMPANY_SLUGS.has(slug)) {
+        throw new Error(`Company slug "${slug}" is reserved and cannot be used here`);
+    }
+}
+/** Absolute path to a company's `people/` directory. */
+export function companyPeopleDir(hqRoot, companySlug) {
+    assertSafeCompanySlug(companySlug);
+    return path.join(hqRoot, "companies", companySlug, "people");
+}
+/**
+ * Parse a single `meta.yaml` body into a `PersonRecord`. Returns `null` when the
+ * file is empty, unparseable, or has no usable `name` — a person record without
+ * a name can't be listed, searched, or resolved, so it's skipped rather than
+ * surfaced as a half-row. Exported for unit testing.
+ */
+export function parsePersonMeta(raw, slug, source) {
+    let doc;
+    try {
+        doc = yaml.load(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${source}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!doc || typeof doc !== "object")
+        return null;
+    const d = doc;
+    const name = typeof d.name === "string" ? d.name.trim() : "";
+    if (!name)
+        return null;
+    const str = (v) => typeof v === "string" && v.trim() ? v.trim() : undefined;
+    const tags = Array.isArray(d.tags)
+        ? d.tags.filter((t) => typeof t === "string")
+        : undefined;
+    return {
+        slug,
+        name,
+        email: str(d.email),
+        type: str(d.type),
+        role: str(d.role),
+        organization: str(d.organization),
+        ...(tags && tags.length > 0 ? { tags } : {}),
+        source,
+    };
+}
+/**
+ * List every person recorded for ONE company. Reads
+ * `companies/<companySlug>/people/<personSlug>/meta.yaml` for each person
+ * folder.
+ *
+ * - Folders whose name starts with `_` are skipped (e.g. the `_example`
+ *   template that ships in `companies/_template/people/`).
+ * - Folders without a `meta.yaml`, or whose `meta.yaml` has no `name`, are
+ *   skipped silently — they aren't members yet.
+ * - Returns `[]` when the company has no `people/` directory at all.
+ *
+ * Results are sorted by name (case-insensitive) for stable output.
+ */
+export function listCompanyPeople(hqRoot, companySlug) {
+    const dir = companyPeopleDir(hqRoot, companySlug);
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const people = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith("_"))
+            continue; // _example and other scaffolding
+        const metaPath = path.join(dir, entry.name, "meta.yaml");
+        if (!fs.existsSync(metaPath))
+            continue;
+        const raw = fs.readFileSync(metaPath, "utf-8");
+        const record = parsePersonMeta(raw, entry.name, metaPath);
+        if (record)
+            people.push(record);
+    }
+    people.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+    return people;
+}
+/**
+ * Case-insensitive keyword search over a person's NAME and EMAIL (plus the
+ * folder slug, which is a normalized alias of the name). Pure — operates on an
+ * already-loaded list so it's trivially testable and reusable.
+ *
+ * An empty/whitespace keyword matches nothing (callers should treat that as a
+ * usage error rather than "return everyone").
+ */
+export function searchPeople(people, keyword) {
+    const needle = keyword.trim().toLowerCase();
+    if (!needle)
+        return [];
+    return people.filter((p) => {
+        const haystacks = [p.name, p.email, p.slug].filter((v) => typeof v === "string");
+        return haystacks.some((h) => h.toLowerCase().includes(needle));
+    });
+}
+/**
+ * Resolve a person NAME to their email, built on top of {@link searchPeople}.
+ *
+ * Match precedence (narrowest first) so a precise query isn't drowned out by
+ * looser substring hits:
+ *   1. exact name match (case-insensitive, trimmed)
+ *   2. exact folder-slug match
+ *   3. substring search over name/email/slug
+ *
+ * The first tier that yields any match decides the result:
+ *   - exactly one match with an email  → `found`
+ *   - exactly one match, no email      → `no_email`
+ *   - more than one match              → `ambiguous` (caller disambiguates)
+ *   - no match in any tier             → `not_found`
+ */
+export function resolveNameToEmail(people, name) {
+    const query = name.trim();
+    if (!query)
+        return { status: "not_found" };
+    const lowered = query.toLowerCase();
+    const exactName = people.filter((p) => p.name.toLowerCase() === lowered);
+    const exactSlug = people.filter((p) => p.slug.toLowerCase() === lowered);
+    const substring = searchPeople(people, query);
+    const matches = exactName.length > 0
+        ? exactName
+        : exactSlug.length > 0
+            ? exactSlug
+            : substring;
+    if (matches.length === 0)
+        return { status: "not_found" };
+    if (matches.length > 1)
+        return { status: "ambiguous", matches };
+    const person = matches[0];
+    if (!person.email)
+        return { status: "no_email", person };
+    return { status: "found", email: person.email, person };
+}
+//# sourceMappingURL=people.js.map
+//# debugId=aac5adc3-c336-5d9a-8a1a-edaf16ef4c11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.47.15",
+  "version": "5.47.16",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {