@indigoai-us/hq-cli 5.60.0 → 5.62.0

package/src/commands/workers.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Unit tests for `hq workers` (workers.ts).
+ *
+ * Coverage:
+ *   - readWorkerRegistry — parses registry.yaml, empty when missing
+ *   - filterAccessibleWorkers — public always; company only for active company
+ *   - workerVaultPrefix — companies/{co}/workers/{id}/ -> workers/{id}/; null for public
+ *   - classifyPrincipal — @all | email | grp_ | invalid
+ *   - resolveActiveCompany — reads .current -> meta.yaml company_slug
+ *   - writeGrantSidecar — creates + unions .grants.yaml idempotently
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import {
+  readWorkerRegistry,
+  filterAccessibleWorkers,
+  workerVaultPrefix,
+  classifyPrincipal,
+  resolveActiveCompany,
+  writeGrantSidecar,
+  type RegistryWorker,
+} from "./workers.js";
+
+let hqRoot: string;
+
+function writeRegistry(workers: RegistryWorker[]): void {
+  const p = path.join(hqRoot, "core/workers/registry.yaml");
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, yaml.dump({ version: "5.1", workers }), "utf8");
+}
+
+const pub: RegistryWorker = {
+  id: "architect",
+  path: "core/workers/public/dev-team/architect/",
+  type: "CodeWorker",
+  visibility: "public",
+  description: "System design",
+};
+const indigo: RegistryWorker = {
+  id: "deal-brain",
+  path: "companies/indigo/workers/deal-brain/",
+  type: "OpsWorker",
+  visibility: "private",
+  company: "indigo",
+  description: "GTM teammate",
+};
+const amass: RegistryWorker = {
+  id: "gtm-refresh",
+  path: "companies/amass/workers/gtm-refresh/",
+  type: "OpsWorker",
+  visibility: "private",
+  company: "amass",
+  description: "Depletions",
+};
+
+beforeEach(() => {
+  hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-workers-"));
+});
+afterEach(() => {
+  fs.rmSync(hqRoot, { recursive: true, force: true });
+});
+
+describe("readWorkerRegistry", () => {
+  it("returns [] when the registry does not exist", () => {
+    expect(readWorkerRegistry(hqRoot)).toEqual([]);
+  });
+  it("parses the workers list", () => {
+    writeRegistry([pub, indigo]);
+    const got = readWorkerRegistry(hqRoot);
+    expect(got.map((w) => w.id)).toEqual(["architect", "deal-brain"]);
+  });
+});
+
+describe("filterAccessibleWorkers", () => {
+  it("always includes public workers", () => {
+    expect(filterAccessibleWorkers([pub], undefined).map((w) => w.id)).toEqual(["architect"]);
+  });
+  it("includes company workers only for the active company", () => {
+    const got = filterAccessibleWorkers([pub, indigo, amass], "indigo").map((w) => w.id);
+    expect(got).toEqual(["architect", "deal-brain"]);
+    expect(got).not.toContain("gtm-refresh");
+  });
+  it("excludes all company workers when no active company", () => {
+    expect(filterAccessibleWorkers([pub, indigo, amass], undefined).map((w) => w.id)).toEqual([
+      "architect",
+    ]);
+  });
+});
+
+describe("workerVaultPrefix", () => {
+  it("maps a company worker path to a company-relative glob prefix (covers everything under the worker dir)", () => {
+    expect(workerVaultPrefix(indigo)).toBe("workers/deal-brain/*");
+  });
+  it("returns null for a public worker", () => {
+    expect(workerVaultPrefix(pub)).toBeNull();
+  });
+});
+
+describe("classifyPrincipal", () => {
+  it("classifies @all as company-wide with empty granteeId", () => {
+    expect(classifyPrincipal("@all")).toEqual({
+      granteeType: "company-wide",
+      granteeId: "",
+      label: "everyone in the company",
+    });
+  });
+  it("lowercases emails", () => {
+    expect(classifyPrincipal("Me@Co.com")).toEqual({
+      granteeType: "email",
+      granteeId: "me@co.com",
+      label: "me@co.com",
+    });
+  });
+  it("accepts group ids", () => {
+    expect(classifyPrincipal("grp_finance")).toEqual({
+      granteeType: "group",
+      granteeId: "grp_finance",
+      label: "grp_finance",
+    });
+  });
+  it("rejects invalid principals", () => {
+    expect(classifyPrincipal("not-a-principal")).toBeNull();
+    expect(classifyPrincipal("grp_")).toBeNull();
+  });
+});
+
+describe("resolveActiveCompany", () => {
+  it("undefined when no session pointer", () => {
+    expect(resolveActiveCompany(hqRoot)).toBeUndefined();
+  });
+  it("reads company_slug from the current session meta", () => {
+    const sess = "sess-123";
+    fs.mkdirSync(path.join(hqRoot, "workspace/sessions", sess), { recursive: true });
+    fs.writeFileSync(path.join(hqRoot, "workspace/sessions/.current"), sess);
+    fs.writeFileSync(
+      path.join(hqRoot, "workspace/sessions", sess, "meta.yaml"),
+      "company_slug: indigo\n",
+    );
+    expect(resolveActiveCompany(hqRoot)).toBe("indigo");
+  });
+});
+
+describe("writeGrantSidecar", () => {
+  it("creates .grants.yaml with the principal, then unions idempotently", () => {
+    fs.mkdirSync(path.join(hqRoot, indigo.path), { recursive: true });
+    writeGrantSidecar(hqRoot, indigo.path, "grp_finance");
+    writeGrantSidecar(hqRoot, indigo.path, "grp_finance"); // idempotent
+    writeGrantSidecar(hqRoot, indigo.path, "me@co.com");
+    const doc = yaml.load(
+      fs.readFileSync(path.join(hqRoot, indigo.path, ".grants.yaml"), "utf8"),
+    ) as { grants: string[] };
+    expect(doc.grants).toEqual(["grp_finance", "me@co.com"]);
+  });
+});

package/src/commands/workers.ts

@@ -0,0 +1,298 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "./secrets.js";
+import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+import { findHqRoot } from "../utils/manifest.js";
+
+// A worker entry as it appears in the auto-generated core/workers/registry.yaml.
+export interface RegistryWorker {
+  id: string;
+  path: string;
+  type: string;
+  visibility: string;
+  company?: string;
+  team?: string;
+  status?: string;
+  description?: string;
+  triggers?: string;
+  grants?: string;
+}
+
+/** Read + parse the worker registry. Empty array if it does not exist. */
+export function readWorkerRegistry(hqRoot: string): RegistryWorker[] {
+  const p = path.join(hqRoot, "core/workers/registry.yaml");
+  if (!fs.existsSync(p)) return [];
+  const doc = yaml.load(fs.readFileSync(p, "utf8")) as
+    | { workers?: RegistryWorker[] }
+    | null;
+  return doc?.workers ?? [];
+}
+
+/**
+ * Best-effort active company: workspace/sessions/.current -> meta.yaml
+ * company_slug. Undefined when no session context is set. Pure/read-only.
+ */
+export function resolveActiveCompany(hqRoot: string): string | undefined {
+  try {
+    const currentFile = path.join(hqRoot, "workspace/sessions/.current");
+    const current = fs.readFileSync(currentFile, "utf8").trim();
+    if (!current) return undefined;
+    const metaPath = path.join(hqRoot, "workspace/sessions", current, "meta.yaml");
+    if (!fs.existsSync(metaPath)) return undefined;
+    const meta = yaml.load(fs.readFileSync(metaPath, "utf8")) as
+      | Record<string, unknown>
+      | null;
+    const co = meta?.company_slug;
+    return typeof co === "string" && co ? co : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Membership-aware access filter for worker discovery: public workers always;
+ * company workers only for the active company. Mirrors the /run skill and the
+ * inject-worker-suggestion hook so all three surfaces agree.
+ */
+export function filterAccessibleWorkers(
+  workers: RegistryWorker[],
+  activeCompany: string | undefined,
+): RegistryWorker[] {
+  return workers.filter((w) => {
+    if (w.visibility === "public") return true;
+    if (!w.company) return false;
+    return activeCompany !== undefined && w.company === activeCompany;
+  });
+}
+
+/**
+ * The company-relative vault prefix for a worker, e.g.
+ * companies/indigo/workers/deal-brain/ -> workers/deal-brain/. Returns null for
+ * a worker with no company (public/shared — not shareable via ACL).
+ */
+export function workerVaultPrefix(w: RegistryWorker): string | null {
+  if (!w.company) return null;
+  const companyRoot = `companies/${w.company}/`;
+  const rel = w.path.startsWith(companyRoot)
+    ? w.path.slice(companyRoot.length)
+    : w.path;
+  return normalizeFilePrefix(rel);
+}
+
+export type GranteeType = "company-wide" | "email" | "group";
+
+export interface ClassifiedPrincipal {
+  granteeType: GranteeType;
+  granteeId: string;
+  label: string;
+}
+
+/** Classify a share principal (@all | email | grp_*) — null when invalid. */
+export function classifyPrincipal(principal: string): ClassifiedPrincipal | null {
+  if (principal === "@all") {
+    return { granteeType: "company-wide", granteeId: "", label: "everyone in the company" };
+  }
+  if (EMAIL_PATTERN.test(principal)) {
+    const id = principal.trim().toLowerCase();
+    return { granteeType: "email", granteeId: id, label: id };
+  }
+  if (GROUP_ID_PATTERN.test(principal)) {
+    return { granteeType: "group", granteeId: principal, label: principal };
+  }
+  return null;
+}
+
+/**
+ * Record a grant locally in the worker's tool-owned .grants.yaml sidecar. Kept
+ * out of worker.yaml so we never rewrite a hand-authored file; the registry
+ * generator unions this sidecar into the registry `grants:` field. Idempotent.
+ */
+export function writeGrantSidecar(
+  hqRoot: string,
+  workerPath: string,
+  principalLabel: string,
+): void {
+  const dir = path.join(hqRoot, workerPath);
+  const sidecar = path.join(dir, ".grants.yaml");
+  let grants: string[] = [];
+  if (fs.existsSync(sidecar)) {
+    const doc = yaml.load(fs.readFileSync(sidecar, "utf8")) as
+      | { grants?: string[] }
+      | null;
+    if (Array.isArray(doc?.grants)) grants = doc!.grants.filter((g) => typeof g === "string");
+  }
+  if (!grants.includes(principalLabel)) grants.push(principalLabel);
+  const header =
+    "# Worker access grants — tool-owned, written by `hq workers share`.\n" +
+    "# Unioned into core/workers/registry.yaml `grants:` by the registry generator.\n";
+  fs.writeFileSync(sidecar, header + yaml.dump({ grants }), "utf8");
+}
+
+async function runWorkersShare(
+  workerId: string,
+  opts: { with: string; permission?: string; company?: string },
+): Promise<void> {
+  const hqRoot = findHqRoot();
+  const worker = readWorkerRegistry(hqRoot).find((w) => w.id === workerId);
+  if (!worker) {
+    console.error(
+      chalk.red(`Worker '${workerId}' not found in registry.`),
+      "\nRun 'hq workers list' to see accessible workers.",
+    );
+    process.exit(1);
+  }
+
+  const prefix = workerVaultPrefix(worker!);
+  if (!prefix) {
+    console.error(
+      chalk.red(`'${workerId}' is a shared/public worker (visibility ${worker!.visibility}).`),
+      "\nPublic workers already ship to every HQ install — only company-scoped workers are shared with `hq workers share`.",
+    );
+    process.exit(1);
+  }
+
+  const permission = opts.permission ?? "read";
+  if (!["read", "write"].includes(permission)) {
+    console.error(chalk.red(`Invalid permission '${permission}': must be read or write`));
+    process.exit(1);
+  }
+
+  const classified = classifyPrincipal(opts.with);
+  if (!classified) {
+    console.error(
+      chalk.red(
+        `Invalid principal '${opts.with}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`,
+      ),
+    );
+    process.exit(1);
+  }
+
+  const companySlug = opts.company ?? worker!.company;
+  const token = await ensureCognitoToken();
+  const companyUid = await getCompanyUid(token, companySlug);
+
+  const body = {
+    prefix,
+    granteeType: classified!.granteeType,
+    granteeId: classified!.granteeId,
+    permission,
+  };
+  let res = await vaultApiFetch({
+    token,
+    path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
+    method: "POST",
+    body,
+  });
+  // No ACL row for this prefix yet — auto-create one with this grant.
+  if (res.status === 404) {
+    res = await vaultApiFetch({
+      token,
+      path: `/files/${encodeURIComponent(companyUid)}/acl`,
+      method: "POST",
+      body: {
+        prefix,
+        entries: [
+          {
+            granteeType: classified!.granteeType,
+            granteeId: classified!.granteeId,
+            permission,
+          },
+        ],
+      },
+    });
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    console.error(chalk.red(`Failed to share worker (HTTP ${res.status}). ${text}`));
+    process.exit(1);
+  }
+
+  writeGrantSidecar(hqRoot, worker!.path, classified!.label);
+
+  console.log(
+    chalk.green("✓"),
+    `Shared worker '${workerId}' with ${classified!.label} (${permission}).`,
+  );
+  console.log(
+    chalk.dim(
+      `  Vault prefix ${prefix} granted in company '${companySlug}'. It will sync to granted members and appear in their /run list.`,
+    ),
+  );
+}
+
+function runWorkersList(opts: { company?: string; mine?: boolean; shared?: boolean }): void {
+  const hqRoot = findHqRoot();
+  const activeCompany = opts.company ?? resolveActiveCompany(hqRoot);
+  let workers = filterAccessibleWorkers(readWorkerRegistry(hqRoot), activeCompany);
+
+  if (opts.shared) workers = workers.filter((w) => Boolean(w.grants && w.grants.trim()));
+  if (opts.mine) workers = workers.filter((w) => Boolean(w.company) && w.company === activeCompany);
+
+  if (workers.length === 0) {
+    console.log("No accessible workers.");
+    return;
+  }
+
+  const publicWorkers = workers.filter((w) => w.visibility === "public");
+  const companyWorkers = workers.filter((w) => w.visibility !== "public");
+
+  console.log(chalk.bold("Available Workers:"));
+  const printGroup = (title: string, list: RegistryWorker[]) => {
+    if (list.length === 0) return;
+    console.log(`\n  ${chalk.cyan(title)}:`);
+    for (const w of list.sort((a, b) => a.id.localeCompare(b.id))) {
+      const desc = (w.description ?? "").slice(0, 72);
+      const shared = w.grants && w.grants.trim() ? chalk.dim(`  [shared: ${w.grants}]`) : "";
+      console.log(`    ${w.id.padEnd(24)} ${desc}${shared}`);
+    }
+  };
+  printGroup("Public", publicWorkers);
+  if (activeCompany) printGroup(activeCompany, companyWorkers);
+
+  console.log(chalk.dim("\nUsage: hq run {worker-id} [skill] [args]"));
+  console.log(
+    chalk.dim(
+      "Share a company worker: hq workers share {worker-id} --with {grp_<name>|@all} --permission read",
+    ),
+  );
+}
+
+export function registerWorkersCommand(program: Command): void {
+  const workers = program
+    .command("workers")
+    .description("Discover and share HQ workers")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  workers
+    .command("list")
+    .description("List workers you can access (public + your active company's)")
+    .option("--mine", "Only this company's workers")
+    .option("--shared", "Only workers that have been shared with someone")
+    .action((opts: { mine?: boolean; shared?: boolean }) => {
+      runWorkersList({ ...opts, company: workers.opts().company as string | undefined });
+    });
+
+  workers
+    .command("share <workerId>")
+    .description("Grant a teammate, group, or @all access to a company worker")
+    .requiredOption(
+      "--with <principal>",
+      "Email address, group id (grp_<name>), or '@all' to share with every active company member",
+    )
+    .option("--permission <level>", "Permission level: read | write (default: read)")
+    .action(async (workerId: string, opts: { with: string; permission?: string }) => {
+      try {
+        await runWorkersShare(workerId, {
+          ...opts,
+          company: workers.opts().company as string | undefined,
+        });
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+}

package/src/index.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./cli-version.js", () => ({
+  CLI_VERSION: "5.60.0",
+  CLI_NAME: "@indigoai-us/hq-cli",
+}));
+
+vi.mock("./node-preflight.js", () => ({}));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.resetModules();
+});
+
+describe("bin bootstrap", () => {
+  it("answers --version without importing the command graph", async () => {
+    const originalArgv = process.argv;
+    const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    const runCli = vi.fn();
+    vi.doMock("./main.js", () => ({ runCli }));
+    process.argv = ["node", "hq", "--version"];
+
+    try {
+      await import("./index.js");
+    } finally {
+      process.argv = originalArgv;
+    }
+
+    expect(write).toHaveBeenCalledWith("5.60.0\n");
+    expect(runCli).not.toHaveBeenCalled();
+  });
+});