@indigoai-us/hq-cli 5.31.0 → 5.32.0

package/src/commands/group-grants.ts

@@ -0,0 +1,452 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { GROUP_ID_PATTERN } from "./_patterns.js";
+
+/**
+ * `hq group-grants` — manage cross-company group access grants.
+ *
+ * A *group grant* lets a group defined in a SOURCE company be granted a role
+ * on a TARGET company. The hq-pro API authorizes the operation against the
+ * TARGET company (the caller must be able to invite into it). The CLI is a
+ * thin client — it passes the right params and surfaces the server's 403 as an
+ * actionable cross-tenant permission error. NO authorization is reimplemented
+ * here.
+ *
+ * Backend contract (hq-pro feature/agency-cross-company-group-grants):
+ *   - POST /group-grants            { groupId, sourceCompanyUid, targetCompanyUid, role }
+ *   - POST /group-grants/revoke     { groupId, sourceCompanyUid, targetCompanyUid }
+ *   - GET  /group-grants/outbound?sourceCompanyUid&groupId
+ *   - GET  /group-grants/inbound?companyUid
+ *
+ * All require a Cognito idToken bearer; 403 (code FORBIDDEN) on authz failure.
+ */
+
+export const VALID_GRANT_ROLES = new Set(["owner", "admin", "member", "guest"]);
+
+export type GrantRole = "owner" | "admin" | "member" | "guest";
+
+export interface GroupGrant {
+  groupId: string;
+  sourceCompanyUid: string;
+  targetCompanyUid: string;
+  role: string;
+  grantedBy?: string;
+  grantedAt?: string;
+}
+
+export interface GrantGroupOptions {
+  groupId: string;
+  sourceCompanyUid: string;
+  targetCompanyUid: string;
+  role: string;
+  token: string;
+}
+
+export interface RevokeGroupGrantOptions {
+  groupId: string;
+  sourceCompanyUid: string;
+  targetCompanyUid: string;
+  token: string;
+}
+
+/**
+ * Typed HTTP error mirroring members.ts's `InviteHttpError`. Carries the
+ * server status + optional error `code` (e.g. `FORBIDDEN`) so the command
+ * layer can render an actionable message and exit non-zero.
+ */
+export class GrantHttpError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+    public code?: string,
+  ) {
+    super(message);
+    this.name = "GrantHttpError";
+  }
+}
+
+/**
+ * Map a `GrantHttpError` onto an actionable, human-readable message. The 403
+ * branch is the story's key cross-tenant case: authorization is enforced
+ * against the TARGET company, so the message names the target the caller
+ * lacks rights on.
+ */
+export function formatGrantHttpError(
+  status: number,
+  fallback: string,
+  ctx: { targetCompany?: string; code?: string } = {},
+): string {
+  if (status === 401) return "Not authenticated — please run `hq login`";
+  if (status === 403) {
+    const target = ctx.targetCompany ? ` '${ctx.targetCompany}'` : "";
+    return (
+      `Permission denied: you must be an owner or admin of the target company${target} to grant a group into it. ` +
+      "The grant is authorized against the target company — ask an owner/admin there, or have them enable adminCanInvite."
+    );
+  }
+  if (status === 404) {
+    return `Not found: ${fallback}. Check the group id and that both companies exist.`;
+  }
+  if (status === 409) {
+    return `That grant already exists: ${fallback}`;
+  }
+  if (status >= 500) return `Server error: ${fallback}`;
+  return fallback;
+}
+
+function shortDate(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+/**
+ * POST /group-grants — grant a group's access to a target company at a role.
+ * Pure-ish: validates inputs, then calls the API client. Throws
+ * `GrantHttpError` on non-2xx so the command layer surfaces it.
+ */
+export async function grantGroup(options: GrantGroupOptions): Promise<GroupGrant> {
+  if (!GROUP_ID_PATTERN.test(options.groupId)) {
+    throw new Error(
+      `Invalid group id '${options.groupId}': must match grp_<alphanumeric, underscore, hyphen>`,
+    );
+  }
+  if (!VALID_GRANT_ROLES.has(options.role)) {
+    throw new Error(
+      `Invalid role '${options.role}': must be one of owner, admin, member, guest`,
+    );
+  }
+  if (options.sourceCompanyUid === options.targetCompanyUid) {
+    throw new Error(
+      "Source and target companies are the same — a group grant must cross company boundaries.",
+    );
+  }
+
+  const res = await vaultApiFetch({
+    token: options.token,
+    path: "/group-grants",
+    method: "POST",
+    body: {
+      groupId: options.groupId,
+      sourceCompanyUid: options.sourceCompanyUid,
+      targetCompanyUid: options.targetCompanyUid,
+      role: options.role,
+    },
+  });
+
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new GrantHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+      err.code,
+    );
+  }
+
+  const data = (await res.json()) as { grant?: GroupGrant };
+  return (
+    data.grant ?? {
+      groupId: options.groupId,
+      sourceCompanyUid: options.sourceCompanyUid,
+      targetCompanyUid: options.targetCompanyUid,
+      role: options.role,
+    }
+  );
+}
+
+/** POST /group-grants/revoke — remove a group's grant on a target company. */
+export async function revokeGroupGrant(
+  options: RevokeGroupGrantOptions,
+): Promise<void> {
+  if (!GROUP_ID_PATTERN.test(options.groupId)) {
+    throw new Error(
+      `Invalid group id '${options.groupId}': must match grp_<alphanumeric, underscore, hyphen>`,
+    );
+  }
+
+  const res = await vaultApiFetch({
+    token: options.token,
+    path: "/group-grants/revoke",
+    method: "POST",
+    body: {
+      groupId: options.groupId,
+      sourceCompanyUid: options.sourceCompanyUid,
+      targetCompanyUid: options.targetCompanyUid,
+    },
+  });
+
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new GrantHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+      err.code,
+    );
+  }
+}
+
+/** GET /group-grants/outbound — grants a source company's group(s) hold. */
+export async function listOutboundGrants(
+  token: string,
+  sourceCompanyUid: string,
+  groupId?: string,
+): Promise<GroupGrant[]> {
+  const query: Record<string, string> = { sourceCompanyUid };
+  if (groupId) query.groupId = groupId;
+
+  const res = await vaultApiFetch({
+    token,
+    path: "/group-grants/outbound",
+    query,
+  });
+
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new GrantHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+      err.code,
+    );
+  }
+
+  const data = (await res.json()) as { grants?: GroupGrant[] | null };
+  return data.grants ?? [];
+}
+
+/** GET /group-grants/inbound — grants other companies' groups hold on us. */
+export async function listInboundGrants(
+  token: string,
+  companyUid: string,
+): Promise<GroupGrant[]> {
+  const res = await vaultApiFetch({
+    token,
+    path: "/group-grants/inbound",
+    query: { companyUid },
+  });
+
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new GrantHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+      err.code,
+    );
+  }
+
+  const data = (await res.json()) as { grants?: GroupGrant[] | null };
+  return data.grants ?? [];
+}
+
+function printGrantsTable(grants: GroupGrant[]): void {
+  const idW = Math.max(8, ...grants.map((g) => g.groupId.length));
+  const srcW = Math.max(6, ...grants.map((g) => g.sourceCompanyUid.length));
+  const tgtW = Math.max(6, ...grants.map((g) => g.targetCompanyUid.length));
+  const roleW = Math.max(4, ...grants.map((g) => g.role.length));
+  console.log(
+    chalk.bold(
+      [
+        "GROUP_ID".padEnd(idW),
+        "SOURCE".padEnd(srcW),
+        "TARGET".padEnd(tgtW),
+        "ROLE".padEnd(roleW),
+        "GRANTED_AT",
+      ].join("  "),
+    ),
+  );
+  for (const g of grants) {
+    console.log(
+      [
+        g.groupId.padEnd(idW),
+        g.sourceCompanyUid.padEnd(srcW),
+        g.targetCompanyUid.padEnd(tgtW),
+        g.role.padEnd(roleW),
+        g.grantedAt ? shortDate(g.grantedAt) : "",
+      ].join("  "),
+    );
+  }
+}
+
+export function registerGroupGrantsCommand(program: Command): void {
+  const grants = program
+    .command("group-grants")
+    .description(
+      "Grant a group's access to another company (cross-company), and revoke or inspect those grants",
+    )
+    .option(
+      "--company <slug>",
+      "Source company slug (the company that owns the group; resolves to sourceCompanyUid)",
+    );
+
+  grants
+    .command("grant <groupId> <targetCompany>")
+    .description(
+      "Grant a group (from the source company) access to <targetCompany> at a role",
+    )
+    .option(
+      "--role <role>",
+      "Role the group receives on the target company: owner, admin, member, or guest",
+      "member",
+    )
+    .action(
+      async (
+        groupId: string,
+        targetCompany: string,
+        opts: { role: string },
+      ) => {
+        try {
+          const token = await ensureCognitoToken();
+          const sourceSlug = grants.opts().company as string | undefined;
+          const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
+          const targetCompanyUid = await getCompanyUid(token, targetCompany);
+
+          const grant = await grantGroup({
+            groupId,
+            sourceCompanyUid,
+            targetCompanyUid,
+            role: opts.role,
+            token,
+          });
+
+          console.log(
+            chalk.green(
+              `Granted group '${grant.groupId}' access to '${targetCompany}' as ${grant.role}`,
+            ),
+          );
+          console.log(
+            chalk.dim(
+              `  source: ${grant.sourceCompanyUid}  →  target: ${grant.targetCompanyUid}`,
+            ),
+          );
+        } catch (err) {
+          if (err instanceof GrantHttpError) {
+            console.error(
+              chalk.red(
+                formatGrantHttpError(err.status, err.message, {
+                  targetCompany,
+                  code: err.code,
+                }),
+              ),
+            );
+            process.exit(1);
+          }
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
+          process.exit(1);
+        }
+      },
+    );
+
+  grants
+    .command("revoke <groupId> <targetCompany>")
+    .description(
+      "Revoke a group's grant on <targetCompany>",
+    )
+    .action(async (groupId: string, targetCompany: string) => {
+      try {
+        const token = await ensureCognitoToken();
+        const sourceSlug = grants.opts().company as string | undefined;
+        const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
+        const targetCompanyUid = await getCompanyUid(token, targetCompany);
+
+        await revokeGroupGrant({
+          groupId,
+          sourceCompanyUid,
+          targetCompanyUid,
+          token,
+        });
+
+        console.log(
+          chalk.green(
+            `Revoked group '${groupId}' grant on '${targetCompany}'`,
+          ),
+        );
+      } catch (err) {
+        if (err instanceof GrantHttpError) {
+          console.error(
+            chalk.red(
+              formatGrantHttpError(err.status, err.message, {
+                targetCompany,
+                code: err.code,
+              }),
+            ),
+          );
+          process.exit(1);
+        }
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  grants
+    .command("outbound")
+    .description(
+      "List grants the source company's groups hold on other companies",
+    )
+    .option(
+      "--group <groupId>",
+      "Filter to a single group id",
+    )
+    .action(async (opts: { group?: string }) => {
+      try {
+        const token = await ensureCognitoToken();
+        const sourceSlug = grants.opts().company as string | undefined;
+        const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
+
+        const list = await listOutboundGrants(token, sourceCompanyUid, opts.group);
+        if (list.length === 0) {
+          console.log(chalk.gray("No outbound group grants."));
+          return;
+        }
+        printGrantsTable(list);
+      } catch (err) {
+        if (err instanceof GrantHttpError) {
+          console.error(
+            chalk.red(formatGrantHttpError(err.status, err.message)),
+          );
+          process.exit(1);
+        }
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  grants
+    .command("inbound")
+    .description(
+      "List grants other companies' groups hold on this company",
+    )
+    .action(async () => {
+      try {
+        const token = await ensureCognitoToken();
+        const companySlug = grants.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const list = await listInboundGrants(token, companyUid);
+        if (list.length === 0) {
+          console.log(chalk.gray("No inbound group grants."));
+          return;
+        }
+        printGrantsTable(list);
+      } catch (err) {
+        if (err instanceof GrantHttpError) {
+          console.error(
+            chalk.red(formatGrantHttpError(err.status, err.message)),
+          );
+          process.exit(1);
+        }
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}

package/src/commands/pack-install.ts

@@ -45,6 +45,7 @@ import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
+import semverGt from 'semver/functions/gt.js';
 import { findHqRoot } from '../utils/manifest.js';
 import type { PackManifest, PackContributeKey } from '../types.js';
 
@@ -52,9 +53,9 @@ import type { PackManifest, PackContributeKey } from '../types.js';
 // Source classification
 // ---------------------------------------------------------------------------
 
-type Transport = 'npm' | 'git' | 'local';
+export type Transport = 'npm' | 'git' | 'local';
 
-function classify(source: string): Transport {
+export function classify(source: string): Transport {
   if (source.startsWith('@')) return 'npm';
   if (
     source.startsWith('http://') ||
@@ -109,7 +110,7 @@ function expandGithubShorthand(url: string): string {
  * Disambiguation: fragment containing '/' is a subpath (optionally with
  * '@<ref>' suffix); fragment without '/' is a ref.
  */
-function parseGitFragment(source: string): {
+export function parseGitFragment(source: string): {
   url: string;
   subpath?: string;
   ref?: string;
@@ -335,6 +336,97 @@ function isNamedRef(url: string, ref: string): boolean {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Update-availability probe (no install) — used by `hq packs update --check-only`
+// ---------------------------------------------------------------------------
+
+export interface LatestResult {
+  transport: Transport;
+  /** Identifier of the currently-installed pack (sha for git, version for npm). */
+  current?: string;
+  /** Latest available identifier from the remote. */
+  latest?: string;
+  /** true/false when a comparison was possible; null when undeterminable (local). */
+  updateAvailable: boolean | null;
+  error?: string;
+}
+
+/** Extract the ref (sha or named ref) recorded in a stamped git source. */
+function gitRefFromSource(source: string): string | undefined {
+  const { subpath, ref } = parseGitFragment(source);
+  // For 'url#subpath@ref' parseGitFragment returns ref; for 'url#ref' likewise.
+  // A bare 'url#subpath' (no @ref) has no ref.
+  void subpath;
+  return ref;
+}
+
+/**
+ * Probe whether a newer version of an already-installed pack is available,
+ * WITHOUT fetching or installing. Reuses the same git/npm primitives as the
+ * install path. Never throws — network/parse failures return
+ * `{ updateAvailable: null, error }` so callers (the menubar) stay resilient.
+ *
+ * @param source         the stamped `source:` from the installed package.yaml
+ * @param installedVersion the installed pack's manifest `version` (npm compare)
+ */
+export function resolveLatest(
+  source: string,
+  installedVersion?: string,
+): LatestResult {
+  let transport: Transport;
+  try {
+    transport = classify(source);
+  } catch (e) {
+    return { transport: 'local', updateAvailable: null, error: (e as Error).message };
+  }
+
+  if (transport === 'local') {
+    return { transport, updateAvailable: null, error: 'local source — re-run to re-sync' };
+  }
+
+  if (transport === 'npm') {
+    const pkg = stripVersion(source);
+    const current =
+      installedVersion ?? (source.lastIndexOf('@') > 0 ? source.slice(source.lastIndexOf('@') + 1) : undefined);
+    try {
+      const latest = execFileSync('npm', ['view', pkg, 'version'], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+      const updateAvailable =
+        current && latest ? semverGt(latest, current) : null;
+      return { transport, current, latest, updateAvailable };
+    } catch (e) {
+      return { transport, current, updateAvailable: null, error: `npm view failed: ${(e as Error).message}` };
+    }
+  }
+
+  // git
+  const parsed = parseGitFragment(source);
+  let url: string;
+  try {
+    url = expandGithubShorthand(parsed.url);
+  } catch (e) {
+    return { transport, updateAvailable: null, error: (e as Error).message };
+  }
+  const current = gitRefFromSource(source);
+  // If install followed a named ref (branch/tag), compare that ref's tip;
+  // otherwise (default SHA-pin) compare the default branch HEAD.
+  const refArg = current && isNamedRef(url, current) ? current : 'HEAD';
+  try {
+    const out = execFileSync('git', ['ls-remote', url, refArg], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const latest = out.split(/\s+/)[0] || undefined;
+    const updateAvailable =
+      current && latest ? !latest.startsWith(current) && !current.startsWith(latest) : null;
+    return { transport, current, latest, updateAvailable };
+  } catch (e) {
+    return { transport, current, updateAvailable: null, error: `git ls-remote failed: ${(e as Error).message}` };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Manifest validation (spec §Validation, 10 checks)
 // ---------------------------------------------------------------------------
@@ -611,24 +703,30 @@ export function stampInstallSource(destDir: string, source: string): void {
  * own scan.
  *
  * Exported for tests.
+ *
+ * `quiet` keeps the script's stdout off our stdout (it routes only stderr
+ * through, and sets HQ_SCAN_QUIET=1) so callers emitting machine-readable
+ * JSON — e.g. `hq packs uninstall --json` — produce clean output.
  */
-export function runScanPackages(hqRoot: string): void {
+export function runScanPackages(hqRoot: string, opts: { quiet?: boolean } = {}): void {
   const script = path.join(hqRoot, 'core', 'scripts', 'scan-packages.sh');
   if (!fs.existsSync(script)) {
-    console.log(
-      chalk.dim(
-        `  (core/scripts/scan-packages.sh not present — skipping auto-wire; ` +
-          `will run on next session start)`
-      )
-    );
+    if (!opts.quiet) {
+      console.log(
+        chalk.dim(
+          `  (core/scripts/scan-packages.sh not present — skipping auto-wire; ` +
+            `will run on next session start)`
+        )
+      );
+    }
     return;
   }
   const r = spawnSync('bash', [script], {
     cwd: hqRoot,
-    env: { ...process.env, HQ_ROOT: hqRoot },
-    stdio: 'inherit',
+    env: { ...process.env, HQ_ROOT: hqRoot, ...(opts.quiet ? { HQ_SCAN_QUIET: '1' } : {}) },
+    stdio: opts.quiet ? ['ignore', 'ignore', 'inherit'] : 'inherit',
   });
-  if (r.status !== 0) {
+  if (r.status !== 0 && !opts.quiet) {
     console.log(chalk.yellow('  scan-packages.sh exited non-zero; see output above.'));
   }
 }
@@ -640,6 +738,13 @@ export function runScanPackages(hqRoot: string): void {
 export interface InstallPackOptions {
   allowHooks?: boolean;
   followBranch?: boolean;
+  /**
+   * Route this function's human output to stderr (and silence scan-packages
+   * stdout) so a caller emitting machine-readable JSON keeps stdout clean.
+   * The fetch tools are already quiet/stderr-only (`npm pack --silent`,
+   * `rsync -a`, `git clone` progress -> stderr), so this is sufficient.
+   */
+  quiet?: boolean;
 }
 
 export async function installPack(
@@ -649,8 +754,11 @@ export async function installPack(
   const transport = classify(source);
   const hqRoot = findHqRoot();
   const hqVersion = readHqVersion(hqRoot);
+  const say: (...a: unknown[]) => void = opts.quiet
+    ? (...a) => console.error(...a)
+    : (...a) => console.log(...a);
 
-  console.log(chalk.dim(`→ transport: ${transport}; source: ${source}`));
+  say(chalk.dim(`-> transport: ${transport}; source: ${source}`));
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-pack-'));
   try {
     let fetched: FetchResult;
@@ -671,7 +779,7 @@ export async function installPack(
     if (pkg.conditional) {
       const allowed = await confirmConditional(pkg, opts.allowHooks ?? false);
       if (!allowed) {
-        console.log(
+        say(
           chalk.red(
             'Install aborted (conditional predicate not approved).',
           ),
@@ -680,7 +788,7 @@ export async function installPack(
       }
       const ok = evalConditional(pkg.conditional);
       if (!ok) {
-        console.log(
+        say(
           chalk.yellow(
             `Skipping ${pkg.name}: conditional "${pkg.conditional}" returned non-zero.`
           )
@@ -691,7 +799,7 @@ export async function installPack(
 
     const confirmed = await confirmHooks(pkg, opts.allowHooks ?? false);
     if (!confirmed) {
-      console.log(chalk.red('Install aborted (hooks denied).'));
+      say(chalk.red('Install aborted (hooks denied).'));
       return;
     }
 
@@ -705,14 +813,14 @@ export async function installPack(
     // re-runs. Stamping the literal input (not the resolved SHA/version)
     // matches the verbatim equality check in setup.sh.
     stampInstallSource(destDir, source);
-    runScanPackages(hqRoot);
+    runScanPackages(hqRoot, { quiet: opts.quiet });
 
-    console.log(
+    say(
       chalk.green(
-        `\n✓ Installed ${pkg.name}@${pkg.version} → ${path.relative(hqRoot, destDir)}/`
+        `\nOK Installed ${pkg.name}@${pkg.version} -> ${path.relative(hqRoot, destDir)}/`
       )
     );
-    console.log(
+    say(
       chalk.dim(
         `  Wired ${Object.values(pkg.contributes).flat().filter(Boolean).length} ` +
           `contribution(s) into host-side paths.`