@indigoai-us/hq-cli 5.5.0 → 5.5.2-sentry-rc.0

package/src/commands/groups.ts

@@ -0,0 +1,357 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "./secrets.js";
+import { GROUP_ID_PATTERN } from "./_patterns.js";
+
+const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+
+function detectPrincipalType(
+  principal: string,
+): { granteeType: "email" | "person"; granteeId: string } | null {
+  if (EMAIL_PATTERN.test(principal)) {
+    // Server normalizes email again; we normalize here so local validation /
+    // cache keys agree with the server-side canonicalization.
+    return { granteeType: "email", granteeId: principal.trim().toLowerCase() };
+  }
+  if (PERSON_UID_PATTERN.test(principal)) {
+    return { granteeType: "person", granteeId: principal };
+  }
+  return null;
+}
+
+function shortDate(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+export function registerGroupsCommand(program: Command): void {
+  const groups = program
+    .command("groups")
+    .description("Manage groups in HQ vault")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  groups
+    .command("create <groupId>")
+    .description("Create a new group")
+    .requiredOption("--name <name>", "Human-readable group name")
+    .option("--description <desc>", "Optional description")
+    .action(async (groupId: string, opts: { name: string; description?: string }) => {
+      try {
+        if (!GROUP_ID_PATTERN.test(groupId)) {
+          console.error(chalk.red(`Invalid group id '${groupId}': must match grp_<alphanumeric>`));
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        const companySlug = groups.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const body: Record<string, unknown> = { groupId, name: opts.name };
+        if (opts.description) body.description = opts.description;
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/groups`,
+          method: "POST",
+          body,
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized — owner or admin role required"));
+          } else if (res.status === 409) {
+            console.error(chalk.red(`Group already exists: ${groupId}`));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${err.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(err.message ?? err.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        console.log(chalk.green(`Group '${groupId}' (${opts.name}) created`));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  groups
+    .command("delete <groupId>")
+    .description("Delete a group")
+    .action(async (groupId: string) => {
+      try {
+        if (!GROUP_ID_PATTERN.test(groupId)) {
+          console.error(chalk.red(`Invalid group id '${groupId}': must match grp_<alphanumeric>`));
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        const companySlug = groups.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/groups`,
+          method: "DELETE",
+          query: { groupId },
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized — owner or admin role required"));
+          } else if (res.status === 404) {
+            console.error(chalk.red(`Group not found: ${groupId}`));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${err.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(err.message ?? err.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        console.log(chalk.green(`Group '${groupId}' deleted`));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  groups
+    .command("add <groupId> <principal>")
+    .description("Add a person to a group (principal: email or personUid)")
+    .action(async (groupId: string, principal: string) => {
+      try {
+        if (!GROUP_ID_PATTERN.test(groupId)) {
+          console.error(chalk.red(`Invalid group id '${groupId}': must match grp_<alphanumeric>`));
+          process.exit(1);
+        }
+
+        const detected = detectPrincipalType(principal);
+        if (!detected) {
+          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        const companySlug = groups.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/groups/members`,
+          method: "POST",
+          body: { groupId, granteeType: detected.granteeType, granteeId: detected.granteeId },
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized — owner/admin role or group creator required"));
+          } else if (res.status === 404) {
+            // Server provides a helpful message (email not found vs group not found)
+            console.error(chalk.red(err.error ?? `Not found`));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${err.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(err.message ?? err.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        console.log(chalk.green(`Added ${principal} to group '${groupId}'`));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  groups
+    .command("remove <groupId> <principal>")
+    .description("Remove a person from a group (principal: email or personUid)")
+    .action(async (groupId: string, principal: string) => {
+      try {
+        if (!GROUP_ID_PATTERN.test(groupId)) {
+          console.error(chalk.red(`Invalid group id '${groupId}': must match grp_<alphanumeric>`));
+          process.exit(1);
+        }
+
+        const detected = detectPrincipalType(principal);
+        if (!detected) {
+          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        const companySlug = groups.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/groups/members`,
+          method: "DELETE",
+          query: {
+            groupId,
+            granteeType: detected.granteeType,
+            granteeId: detected.granteeId,
+          },
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized — owner/admin role or group creator required"));
+          } else if (res.status === 404) {
+            console.error(chalk.red(err.error ?? `Not found`));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${err.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(err.message ?? err.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        console.log(chalk.green(`Removed ${principal} from group '${groupId}'`));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  groups
+    .command("list")
+    .description("List all groups in the company")
+    .action(async () => {
+      try {
+        const token = await ensureCognitoToken();
+        const companySlug = groups.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/groups`,
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized to list groups"));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${err.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(err.message ?? err.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        const data = await res.json() as {
+          groups: Array<{ groupId: string; name: string; description?: string; createdAt: string }>;
+        };
+
+        if (data.groups.length === 0) {
+          console.log(chalk.gray("No groups in this company yet."));
+          return;
+        }
+
+        const idW = Math.max(8, ...data.groups.map((g) => g.groupId.length));
+        const nameW = Math.max(4, ...data.groups.map((g) => g.name.length));
+        const descW = Math.max(11, ...data.groups.map((g) => (g.description ?? "").length));
+        console.log(chalk.bold([
+          "GROUP_ID".padEnd(idW),
+          "NAME".padEnd(nameW),
+          "DESCRIPTION".padEnd(descW),
+          "CREATED_AT",
+        ].join("  ")));
+        for (const g of data.groups) {
+          console.log([
+            g.groupId.padEnd(idW),
+            g.name.padEnd(nameW),
+            (g.description ?? "").padEnd(descW),
+            shortDate(g.createdAt),
+          ].join("  "));
+        }
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  groups
+    .command("members <groupId>")
+    .description("List members of a group")
+    .action(async (groupId: string) => {
+      try {
+        if (!GROUP_ID_PATTERN.test(groupId)) {
+          console.error(chalk.red(`Invalid group id '${groupId}': must match grp_<alphanumeric>`));
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        const companySlug = groups.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/groups/members`,
+          query: { groupId },
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized to view group members"));
+          } else if (res.status === 404) {
+            console.error(chalk.red(`Group not found: ${groupId}`));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${err.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(err.message ?? err.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        const data = await res.json() as {
+          members: Array<{ personUid: string; addedBy: string; addedAt: string }>;
+        };
+
+        console.log(`Members of '${groupId}':`);
+        if (data.members.length === 0) {
+          console.log(chalk.gray("No members yet — use 'hq groups add' to add."));
+          return;
+        }
+
+        const uidW = Math.max(10, ...data.members.map((m) => m.personUid.length));
+        const byW = Math.max(8, ...data.members.map((m) => m.addedBy.length));
+        console.log(chalk.bold([
+          "PERSON_UID".padEnd(uidW),
+          "ADDED_BY".padEnd(byW),
+          "ADDED_AT",
+        ].join("  ")));
+        for (const m of data.members) {
+          console.log([
+            m.personUid.padEnd(uidW),
+            m.addedBy.padEnd(byW),
+            shortDate(m.addedAt),
+          ].join("  "));
+        }
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/list.ts

@@ -29,10 +29,29 @@ export function registerListCommand(program: Command): void {
         console.log('Modules:\n');
 
         for (const module of manifest.modules) {
+          console.log(`  ${module.name}`);
+
+          if (module.strategy === 'package') {
+            // hq-pack content pack — wired by scripts/scan-packages.sh
+            console.log(`    Strategy: package`);
+            console.log(`    Source:   ${module.source}`);
+            if (module.version) {
+              console.log(`    Version:  ${module.version}`);
+            }
+            if (module.installed_at) {
+              console.log(`    Path:     ${module.installed_at}`);
+            }
+            if (module.resolved_sha) {
+              console.log(`    SHA:      ${module.resolved_sha}`);
+            }
+            console.log();
+            continue;
+          }
+
+          // legacy git-repo module
           const moduleDir = path.join(modulesDir, module.name);
           const installed = await isRepo(moduleDir);
 
-          console.log(`  ${module.name}`);
           console.log(`    Repo:     ${module.repo}`);
           console.log(`    Branch:   ${module.branch || 'main'}`);
           console.log(`    Strategy: ${module.strategy}`);

package/src/commands/login.ts

@@ -1,23 +1,42 @@
 /**
- * hq login — opens browser for Clerk auth, caches token (US-004)
+ * hq login — opens browser for Cognito auth via Google OAuth
  */
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { startAuthFlow } from '../utils/auth.js';
-import { saveToken } from '../utils/token-store.js';
-import { getRegistryUrl } from '../utils/registry-client.js';
+import { browserLogin, loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
+import { DEFAULT_COGNITO } from '../utils/cognito-session.js';
+
+function peekIdToken(idToken: string): { email?: string; sub?: string } {
+  try {
+    const payload = idToken.split('.')[1];
+    if (!payload) return {};
+    const pad = payload.length % 4 === 0 ? '' : '='.repeat(4 - (payload.length % 4));
+    const normalized = payload.replace(/-/g, '+').replace(/_/g, '/') + pad;
+    const decoded = JSON.parse(Buffer.from(normalized, 'base64').toString('utf-8'));
+    return { email: decoded.email, sub: decoded.sub };
+  } catch {
+    return {};
+  }
+}
 
 export function registerLoginCommand(program: Command): void {
   program
     .command('login')
-    .description('Authenticate with the HQ package registry')
+    .description('Authenticate with HQ via Cognito (Google OAuth)')
     .action(async () => {
       try {
-        const registryUrl = getRegistryUrl();
-        const token = await startAuthFlow(registryUrl);
-        await saveToken(token);
-        console.log(chalk.green(`Logged in as ${token.email}`));
+        const existing = loadCachedTokens();
+        if (existing && !isExpiring(existing, 120)) {
+          const who = peekIdToken(existing.idToken).email ?? 'cached session';
+          console.log(chalk.green(`Already logged in as ${who}. Run \`hq logout\` to switch accounts.`));
+          return;
+        }
+
+        console.log('Opening browser for authentication...');
+        const tokens = await browserLogin(DEFAULT_COGNITO);
+        const who = peekIdToken(tokens.idToken).email ?? 'HQ';
+        console.log(chalk.green(`Logged in as ${who}`));
       } catch (error) {
         console.error(
           chalk.red('Login failed:'),

package/src/commands/logout.ts

@@ -1,10 +1,10 @@
 /**
- * hq logout — clears cached session (US-004)
+ * hq logout — clears cached Cognito session
  */
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { clearToken } from '../utils/token-store.js';
+import { clearCachedTokens, loadCachedTokens } from '@indigoai-us/hq-cloud';
 
 export function registerLogoutCommand(program: Command): void {
   program
@@ -12,7 +12,12 @@ export function registerLogoutCommand(program: Command): void {
     .description('Log out and clear cached credentials')
     .action(async () => {
       try {
-        await clearToken();
+        const existing = loadCachedTokens();
+        if (!existing) {
+          console.log(chalk.yellow('No cached HQ session'));
+          return;
+        }
+        clearCachedTokens();
         console.log(chalk.green('Logged out successfully'));
       } catch (error) {
         console.error(

package/src/commands/onboard.ts

@@ -0,0 +1,193 @@
+/**
+ * `hq onboard` — bootstrap an HQ vault: sign in to Cognito + provision
+ * the company entity, S3 bucket, KMS key, owner membership, and STS-vended
+ * credentials in one flow.
+ *
+ * This is the "the entire flow" entry point that VLT-9 was building toward:
+ * a real user can install hq-cli and run `hq onboard create-company` once
+ * to land in a fully provisioned vault, then use `hq sync push|pull` to
+ * round-trip files against S3.
+ *
+ * Subcommands:
+ *   hq onboard create-company  — provision a brand new company
+ *   hq onboard join            — accept an invite from another user
+ *   hq onboard resume          — resume a partially-completed flow from checkpoint
+ *   hq onboard dry-run         — show what create-company would do, without doing it
+ *
+ * Auth: we cache the Cognito access + refresh tokens at ~/.hq/cognito-tokens.json.
+ * If the cached token is missing or expired beyond the refresh window, the
+ * browser-OAuth flow opens automatically.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+
+import { runOnboardCli } from "@indigoai-us/hq-onboarding";
+import {
+  DEFAULT_HQ_ROOT,
+  ensureCognitoToken,
+  buildVaultConfig,
+} from "../utils/cognito-session.js";
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerOnboardCommand(program: Command): void {
+  const onboard = program
+    .command("onboard")
+    .description("Provision an HQ vault: sign in, create company, S3 bucket, STS, sync");
+
+  onboard
+    .command("create-company")
+    .description("Sign in and provision a brand new HQ vault for a company")
+    .requiredOption("--slug <slug>", "Company slug (used as bucket name suffix)")
+    .requiredOption("--name <name>", "Company display name")
+    .requiredOption("--email <email>", "Your email (must match Cognito sign-in)")
+    .requiredOption("--person-name <name>", "Your display name")
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(async (options: {
+      slug: string;
+      name: string;
+      email: string;
+      personName: string;
+      hqRoot: string;
+    }) => {
+      try {
+        console.log(chalk.bold(`\nHQ Onboard — Create Company`));
+        console.log(`  Company:  ${options.name} (${options.slug})`);
+        console.log(`  Person:   ${options.personName} <${options.email}>`);
+        console.log(`  HQ root:  ${options.hqRoot}\n`);
+
+        const accessToken = await ensureCognitoToken();
+        const result = await runOnboardCli({
+          mode: "create-company",
+          personName: options.personName,
+          personEmail: options.email,
+          companyName: options.name,
+          companySlug: options.slug,
+          vaultConfig: buildVaultConfig(accessToken),
+          hqRoot: options.hqRoot,
+        });
+
+        if (!result.success) {
+          console.error(chalk.red(`\n✗ Onboarding failed: ${result.error}`));
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(
+          chalk.red("\n✗ Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  onboard
+    .command("join")
+    .description("Accept an invite and join an existing company")
+    .requiredOption("--invite-token <token>", "Magic link token from your invite email")
+    .requiredOption("--email <email>", "Your email (must match Cognito sign-in)")
+    .requiredOption("--person-name <name>", "Your display name")
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(async (options: {
+      inviteToken: string;
+      email: string;
+      personName: string;
+      hqRoot: string;
+    }) => {
+      try {
+        console.log(chalk.bold(`\nHQ Onboard — Join Company`));
+        console.log(`  Person:   ${options.personName} <${options.email}>`);
+        console.log(`  HQ root:  ${options.hqRoot}\n`);
+
+        const accessToken = await ensureCognitoToken();
+        const result = await runOnboardCli({
+          mode: "join-company",
+          personName: options.personName,
+          personEmail: options.email,
+          inviteToken: options.inviteToken,
+          vaultConfig: buildVaultConfig(accessToken),
+          hqRoot: options.hqRoot,
+        });
+
+        if (!result.success) {
+          console.error(chalk.red(`\n✗ Join failed: ${result.error}`));
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(
+          chalk.red("\n✗ Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  onboard
+    .command("resume")
+    .description("Resume a partially-completed onboarding flow from local checkpoint")
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(async (options: { hqRoot: string }) => {
+      try {
+        const accessToken = await ensureCognitoToken();
+        const result = await runOnboardCli({
+          mode: "resume",
+          vaultConfig: buildVaultConfig(accessToken),
+          hqRoot: options.hqRoot,
+        });
+        if (!result.success) {
+          console.error(chalk.red(`\n✗ Resume failed: ${result.error}`));
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(
+          chalk.red("\n✗ Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  onboard
+    .command("dry-run")
+    .description("Show what create-company would do, without provisioning anything")
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(async (options: { hqRoot: string }) => {
+      try {
+        // No auth needed for dry-run — runOnboardCli handles this branch
+        // without touching the vault-service.
+        const result = await runOnboardCli({
+          mode: "dry-run",
+          vaultConfig: buildVaultConfig("dry-run-no-token"),
+          hqRoot: options.hqRoot,
+        });
+        if (!result.success) {
+          console.error(chalk.red(`\n✗ Dry-run failed: ${result.error}`));
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(
+          chalk.red("\n✗ Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}