@indigoai-us/hq-cli 5.47.14 → 5.47.16

package/src/schemas/hq-package.schema.json

@@ -132,6 +132,24 @@
           "minLength": 1
         }
       }
+    },
+    "initialization": {
+      "type": "object",
+      "description": "Optional post-install onboarding. `entrypoint` is the pack's primary get-started action (a skill or command that must resolve to one of this package's exposes.skills / exposes.commands entries); HQ surfaces a safe auto-generated 'get started' line from it after install. `prompt` is optional free-text the user can copy/paste into their agent to begin setup — treated as UNTRUSTED instruction text, surfaced only after marketplace injection-scan/moderation (suppressed for non-marketplace installs).",
+      "additionalProperties": false,
+      "properties": {
+        "entrypoint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Primary get-started action — a skill or command name (with or without a leading slash) that must resolve to a declared exposes.skills / exposes.commands entry."
+        },
+        "prompt": {
+          "type": "string",
+          "maxLength": 2000,
+          "description": "Optional copy/paste setup prompt. Untrusted; surfaced only after moderation for marketplace packs, suppressed for local/git installs."
+        }
+      },
+      "required": ["entrypoint"]
     }
   }
 }

package/src/types.ts

@@ -117,4 +117,11 @@ export interface PackManifest {
    * yet enforced.
    */
   capabilities?: string[];
+  /**
+   * Post-install initialization (US-004/US-005). Optional — absent on legacy
+   * packs. `entrypoint` names a declared `contributes.skills`/`commands` entry
+   * (slash-normalized); `prompt` is optional free-text prose (PHASE 1 does NOT
+   * render the prose — only an auto-generated get-started line from entrypoint).
+   */
+  initialization?: { entrypoint: string; prompt?: string };
 }

package/src/utils/people.ts

@@ -0,0 +1,222 @@
+/**
+ * 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.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+
+/** 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;
+}
+
+/**
+ * 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: string): void {
+  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: string, companySlug: string): string {
+  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: string,
+  slug: string,
+  source: string,
+): PersonRecord | null {
+  let doc: unknown;
+  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 as Record<string, unknown>;
+
+  const name = typeof d.name === "string" ? d.name.trim() : "";
+  if (!name) return null;
+
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.trim() ? v.trim() : undefined;
+
+  const tags = Array.isArray(d.tags)
+    ? d.tags.filter((t): t is string => 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: string,
+  companySlug: string,
+): PersonRecord[] {
+  const dir = companyPeopleDir(hqRoot, companySlug);
+  if (!fs.existsSync(dir)) return [];
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const people: PersonRecord[] = [];
+
+  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: PersonRecord[],
+  keyword: string,
+): PersonRecord[] {
+  const needle = keyword.trim().toLowerCase();
+  if (!needle) return [];
+  return people.filter((p) => {
+    const haystacks = [p.name, p.email, p.slug].filter(
+      (v): v is string => typeof v === "string",
+    );
+    return haystacks.some((h) => h.toLowerCase().includes(needle));
+  });
+}
+
+/** 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 function resolveNameToEmail(
+  people: PersonRecord[],
+  name: string,
+): ResolveResult {
+  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 };
+}