@indigoai-us/hq-cli 5.5.0 → 5.5.2

package/src/commands/team-sync.ts

@@ -17,8 +17,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import simpleGit from 'simple-git';
 import { findHqRoot } from '../utils/hq-root.js';
-import { getAuthToken } from '../utils/auth.js';
-import type { AuthToken } from '../utils/token-store.js';
+import { ensureCognitoToken } from '../utils/cognito-session.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -57,7 +56,7 @@ interface TeamSyncResult {
 
 // ─── API helpers ────────────────────────────────────────────────────────────
 
-const API_BASE = 'https://hq.indigoai.com/api';
+const API_BASE = 'https://example.com/api';
 
 async function apiGet<T>(urlPath: string, token: string): Promise<T> {
   const res = await fetch(`${API_BASE}${urlPath}`, {
@@ -255,7 +254,7 @@ function discoverTeamDirs(hqRoot: string): { dir: string; meta: TeamMetadata }[]
 async function syncTeam(
   teamDir: string,
   meta: TeamMetadata,
-  authToken: AuthToken
+  accessToken: string
 ): Promise<TeamSyncResult> {
   const result: TeamSyncResult = {
     slug: meta.team_slug,
@@ -286,7 +285,7 @@ async function syncTeam(
   try {
     const entitlements = await fetchTeamEntitlements(
       meta.team_id,
-      authToken.clerk_session_token
+      accessToken
     );
     const entitledPaths = entitlements.flatMap((e) => e.paths);
 
@@ -339,7 +338,7 @@ async function syncTeam(
   try {
     repoConfig = await fetchRepoConfig(
       meta.team_id,
-      authToken.clerk_session_token
+      accessToken
     );
   } catch (err) {
     result.message = `Failed to fetch repo credentials: ${err instanceof Error ? err.message : 'Unknown error'}`;
@@ -467,9 +466,9 @@ export function registerTeamSyncCommand(program: Command): void {
           }
 
           // 2. Get valid auth token (handles refresh / re-auth prompt)
-          let authToken: AuthToken;
+          let authToken: string;
           try {
-            authToken = await getAuthToken();
+            authToken = await ensureCognitoToken();
           } catch (err) {
             console.error(
               chalk.red(

package/src/commands/whoami.ts

@@ -1,10 +1,23 @@
 /**
- * hq whoami — displays current user or 'not logged in' (US-004)
+ * hq whoami — displays current user or 'not logged in'
  */
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { loadToken, isTokenExpired } from '../utils/token-store.js';
+import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
+
+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 registerWhoamiCommand(program: Command): void {
   program
@@ -12,21 +25,23 @@ export function registerWhoamiCommand(program: Command): void {
     .description('Show the currently authenticated user')
     .action(async () => {
       try {
-        const token = await loadToken();
+        const cached = loadCachedTokens();
 
-        if (!token) {
+        if (!cached) {
           console.log("Not logged in. Run 'hq login' to authenticate.");
           return;
         }
 
-        if (isTokenExpired(token)) {
+        if (isExpiring(cached, 0)) {
+          const who = peekIdToken(cached.idToken).email ?? 'unknown';
           console.log(
-            chalk.yellow(`Session expired for ${token.email}. Run 'hq login' to re-authenticate.`)
+            chalk.yellow(`Session expired for ${who}. Run 'hq login' to re-authenticate.`)
           );
           return;
         }
 
-        console.log(`Logged in as ${token.email} (${token.user_id})`);
+        const { email, sub } = peekIdToken(cached.idToken);
+        console.log(`Logged in as ${email ?? 'unknown'}${sub ? ` (${sub})` : ''}`);
       } catch (error) {
         console.error(
           chalk.red('Error:'),

package/src/index.ts

@@ -13,12 +13,14 @@ import { registerCloudCommands } from "./commands/cloud.js";
 import { registerLoginCommand } from "./commands/login.js";
 import { registerLogoutCommand } from "./commands/logout.js";
 import { registerWhoamiCommand } from "./commands/whoami.js";
+import { registerOnboardCommand } from "./commands/onboard.js";
 import { registerPackageInstallCommand } from "./commands/pkg-install.js";
 import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
 import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
 import { registerPackageListCommand } from "./commands/pkg-list.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerSecretsCommand } from "./commands/secrets.js";
 
 const program = new Command();
 
@@ -63,10 +65,16 @@ registerCloudCommands(syncCmd);
 // Team commands (top-level)
 registerTeamSyncCommand(program);
 
-// Auth commands (top-level)
+// Auth commands (top-level — Cognito OAuth)
 registerLoginCommand(program);
 registerLogoutCommand(program);
 registerWhoamiCommand(program);
 registerAuthCommands(program);
 
+// Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
+registerSecretsCommand(program);
+
+// Onboarding (top-level — Cognito + vault-service provisioning)
+registerOnboardCommand(program);
+
 program.parse();

package/src/strategies/link.ts

@@ -5,10 +5,10 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import type { ModuleDefinition, SyncResult } from '../types.js';
+import type { LegacyModuleDefinition, SyncResult } from '../types.js';
 
 export async function linkSync(
-  module: ModuleDefinition,
+  module: LegacyModuleDefinition,
   moduleDir: string,
   hqRoot: string
 ): Promise<SyncResult> {

package/src/strategies/merge.ts

@@ -6,7 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
-import type { ModuleDefinition, SyncResult, SyncState } from '../types.js';
+import type { LegacyModuleDefinition, SyncResult, SyncState } from '../types.js';
 import { readState, writeState } from '../utils/manifest.js';
 
 function hashFile(filePath: string): string {
@@ -69,7 +69,7 @@ function copyRecursive(
 }
 
 export async function mergeSync(
-  module: ModuleDefinition,
+  module: LegacyModuleDefinition,
   moduleDir: string,
   hqRoot: string
 ): Promise<SyncResult> {

package/src/types.ts

@@ -1,8 +1,15 @@
 /**
  * HQ Module Manifest Types (US-001)
+ *
+ * `modules.yaml` hosts two kinds of entries, discriminated by `strategy`:
+ *   - link | merge | copy  → git-repo-based module sync (existing flow)
+ *   - package              → hq-pack content pack installed via `hq install`
+ *                            (new in hq-core v12.0.0; see
+ *                            knowledge/public/hq-core/package-yaml-spec.md)
  */
 
-export type SyncStrategy = 'link' | 'merge' | 'copy';
+export type LegacyStrategy = 'link' | 'merge' | 'copy';
+export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
 
 export interface PathMapping {
@@ -10,15 +17,28 @@ export interface PathMapping {
   dest: string;  // Path in HQ tree (relative to HQ root)
 }
 
-export interface ModuleDefinition {
+export interface LegacyModuleDefinition {
   name: string;
   repo: string;              // Git URL (https or git@)
   branch?: string;           // Default: main
-  strategy: SyncStrategy;    // link | merge | copy
+  strategy: LegacyStrategy;
   paths: PathMapping[];      // What to sync and where
-  access?: AccessLevel;      // For future RBAC
+  access?: AccessLevel;
 }
 
+export interface PackModuleDefinition {
+  name: string;              // e.g. 'hq-pack-gstack'
+  strategy: 'package';
+  source: string;            // '@scope/name@ver' | git URL#sha | local path
+  version?: string;          // semver from the pack's package.yaml
+  installed_at?: string;     // e.g. 'packages/hq-pack-gstack'
+  installed_at_iso?: string; // ISO timestamp
+  resolved_sha?: string;     // git transport only
+  access?: AccessLevel;
+}
+
+export type ModuleDefinition = LegacyModuleDefinition | PackModuleDefinition;
+
 export interface ModulesManifest {
   version: '1';
   modules: ModuleDefinition[];
@@ -45,3 +65,33 @@ export interface SyncResult {
   message?: string;
   filesChanged?: number;
 }
+
+// ---------------------------------------------------------------------------
+// hq-pack content-pack manifest (packages/{name}/package.yaml).
+//
+// Distinct from packages/hq-cli/src/schemas/hq-package.schema.json, which
+// covers the entitlement-gated registry flow (`hq packages install <slug>`).
+// ---------------------------------------------------------------------------
+
+export type PackContributeKey =
+  | 'workers'
+  | 'knowledge'
+  | 'skills'
+  | 'commands'
+  | 'hooks'
+  | 'policies'
+  | 'scripts';
+
+export interface PackManifest {
+  name: string;                 // ^hq-pack-[a-z0-9][a-z0-9-]*$
+  version: string;              // semver
+  publisher: string;            // @scope
+  access: 'public' | 'private';
+  requires: { hqCore: string }; // semver range
+  contributes: Partial<Record<PackContributeKey, string[]>>;
+  description?: string;
+  license?: string;
+  repository?: string;
+  keywords?: string[];
+  conditional?: string;         // bash predicate; skip install if exits non-zero
+}

package/src/utils/cognito-session.ts

@@ -1,41 +1,56 @@
 /**
  * Shared Cognito session helpers for hq-cli commands.
  *
- * Consumed by `hq auth refresh` and the standalone `hq-auth-refresh` bin
- * invoked by the deploy skill (.claude/skills/deploy/SKILL.md step 4).
+ * Consumed by:
+ *   - `hq onboard` and `hq sync push|pull` (need token + VaultServiceConfig)
+ *   - `hq auth refresh` and the standalone `hq-auth-refresh` bin invoked by
+ *     the deploy skill (.claude/skills/deploy/SKILL.md step 4)
  *
- * Defaults point at the shared hq-vault-dev Cognito pool. Override via env:
+ * Defaults point at the shared hq-vault-dev Cognito pool. They mirror
+ * tools/vlt-e2e/e2e-create-company-smoke.ts so the CLI and the in-tree demo script
+ * stay drift-free. Override any of them via env:
  *
  *   AWS_REGION                 — e.g. us-east-1
  *   HQ_COGNITO_DOMAIN          — Cognito User Pool domain prefix
  *   HQ_COGNITO_CLIENT_ID       — App Client ID
  *   HQ_COGNITO_CALLBACK_PORT   — Loopback OAuth callback port
+ *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
+import * as os from "os";
+import * as path from "path";
+import chalk from "chalk";
 import {
   loadCachedTokens,
   isExpiring,
   refreshTokens,
   browserLogin,
   type CognitoAuthConfig,
+  type VaultServiceConfig,
 } from "@indigoai-us/hq-cloud";
 
 export const DEFAULT_COGNITO: CognitoAuthConfig = {
   region: process.env.AWS_REGION ?? "us-east-1",
   userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "hq-vault-dev",
-  clientId:
-    process.env.HQ_COGNITO_CLIENT_ID ?? "4mmujmjq3srakdueg656b9m0mp",
+  clientId: process.env.HQ_COGNITO_CLIENT_ID ?? "4mmujmjq3srakdueg656b9m0mp",
   port: process.env.HQ_COGNITO_CALLBACK_PORT
     ? Number(process.env.HQ_COGNITO_CALLBACK_PORT)
     : 8765,
 };
 
+export const DEFAULT_VAULT_API_URL =
+  process.env.HQ_VAULT_API_URL ??
+  "https://tqdwdqxv75.execute-api.us-east-1.amazonaws.com";
+
+export const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
+
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
  * as needed. Cache lives at ~/.hq/cognito-tokens.json.
  *
- * Pass `interactive: false` from automated contexts where failing fast is
- * better than opening a browser.
+ * Pass `interactive: false` from automated contexts (e.g. the `hq-auth-refresh`
+ * bin invoked by the deploy skill) where failing fast is better than opening
+ * a browser.
  */
 export async function ensureCognitoToken(options: {
   interactive?: boolean;
@@ -49,13 +64,19 @@ export async function ensureCognitoToken(options: {
 
   if (cached) {
     try {
-      const refreshed = await refreshTokens(
-        DEFAULT_COGNITO,
-        cached.refreshToken,
-      );
+      if (interactive) {
+        console.error(chalk.dim("  Refreshing expiring HQ session..."));
+      }
+      const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
       return refreshed.accessToken;
-    } catch {
-      // fall through to browser login
+    } catch (err) {
+      if (interactive) {
+        console.error(
+          chalk.dim(
+            `  Refresh failed (${err instanceof Error ? err.message : err}), falling back to browser login`,
+          ),
+        );
+      }
     }
   }
 
@@ -65,14 +86,25 @@ export async function ensureCognitoToken(options: {
     );
   }
 
+  console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
   const tokens = await browserLogin(DEFAULT_COGNITO);
   return tokens.accessToken;
 }
 
+/** Build a VaultServiceConfig with the given access token. */
+export function buildVaultConfig(authToken: string): VaultServiceConfig {
+  return {
+    apiUrl: DEFAULT_VAULT_API_URL,
+    authToken,
+    region: DEFAULT_COGNITO.region,
+  };
+}
+
 /**
  * Refresh the cached Cognito session once and return the result. Used by
  * `hq auth refresh` and the `hq-auth-refresh` bin. Never opens a browser —
- * if no cached tokens exist or the refresh fails, throws.
+ * if no cached tokens exist or the refresh fails, returns `refreshed: false`
+ * with a reason string so the caller can decide what to do.
  */
 export async function refreshCachedSession(): Promise<{
   refreshed: boolean;

package/src/utils/manifest.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Regression tests for manifest path resolution.
+ *
+ * Bug caught during hq-core-split S3 testing (2026-04-21): prior to this
+ * fix, `getManifestPath()` returned a flat path (`{hqRoot}/modules.yaml`),
+ * but real HQ installs use the nested layout (`{hqRoot}/modules/modules.yaml`).
+ * Running `hq install` against a real HQ would silently create a shadow
+ * manifest at the root, orphaning the canonical nested one.
+ *
+ * These tests lock in:
+ *   1. Nested layout is preferred when it exists.
+ *   2. Flat layout is honored when (and only when) it already exists.
+ *   3. Fresh HQs default to writing the nested form — never shadow-writing
+ *      a root-level `modules.yaml`.
+ *   4. Read/write round-trips correctly against the nested layout.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+
+import {
+  addModule,
+  getManifestPath,
+  readManifest,
+  writeManifest,
+} from './manifest.js';
+import type { ModulesManifest } from '../types.js';
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-manifest-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+const sampleManifest: ModulesManifest = {
+  version: '1',
+  modules: [
+    {
+      name: 'knowledge-public-hq-core',
+      repo: 'https://github.com/indigoai-us/knowledge-public-hq-core.git',
+      strategy: 'link',
+      paths: [
+        {
+          src: '.',
+          dest: 'knowledge/public/hq-core',
+        },
+      ],
+    },
+  ],
+};
+
+describe('getManifestPath', () => {
+  it('prefers nested modules/modules.yaml when it exists', () => {
+    const nested = path.join(tmpRoot, 'modules', 'modules.yaml');
+    fs.mkdirSync(path.dirname(nested), { recursive: true });
+    fs.writeFileSync(nested, yaml.dump(sampleManifest));
+
+    expect(getManifestPath(tmpRoot)).toBe(nested);
+  });
+
+  it('honors legacy flat modules.yaml when only the flat form exists', () => {
+    // Legacy fixtures / very old HQ instances may pre-date the nested layout.
+    const flat = path.join(tmpRoot, 'modules.yaml');
+    fs.writeFileSync(flat, yaml.dump(sampleManifest));
+
+    expect(getManifestPath(tmpRoot)).toBe(flat);
+  });
+
+  it('defaults to nested path on a fresh HQ (neither file exists)', () => {
+    // Regression: previously returned the flat path, which meant writeManifest
+    // created a shadow root-level manifest on real HQs.
+    expect(getManifestPath(tmpRoot)).toBe(
+      path.join(tmpRoot, 'modules', 'modules.yaml'),
+    );
+  });
+});
+
+describe('readManifest / writeManifest round-trip', () => {
+  it('round-trips against the nested layout', () => {
+    writeManifest(tmpRoot, sampleManifest);
+
+    const nested = path.join(tmpRoot, 'modules', 'modules.yaml');
+    expect(fs.existsSync(nested)).toBe(true);
+
+    const roundTripped = readManifest(tmpRoot);
+    expect(roundTripped).toEqual(sampleManifest);
+  });
+
+  it('writes into the nested modules/ dir on fresh HQs (creates dir)', () => {
+    // The nested dir does not exist yet — writeManifest must mkdir-p.
+    expect(fs.existsSync(path.join(tmpRoot, 'modules'))).toBe(false);
+
+    writeManifest(tmpRoot, sampleManifest);
+
+    expect(fs.existsSync(path.join(tmpRoot, 'modules'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpRoot, 'modules', 'modules.yaml'))).toBe(
+      true,
+    );
+  });
+
+  it('does NOT shadow-write a root-level modules.yaml on fresh HQs', () => {
+    // This is the original bug: pre-fix, writeManifest on a fresh HQ created
+    // `{hqRoot}/modules.yaml`, which shadowed the canonical nested manifest.
+    writeManifest(tmpRoot, sampleManifest);
+
+    expect(fs.existsSync(path.join(tmpRoot, 'modules.yaml'))).toBe(false);
+  });
+
+  it('rewrites into the flat layout when flat already exists (legacy compat)', () => {
+    const flat = path.join(tmpRoot, 'modules.yaml');
+    fs.writeFileSync(flat, yaml.dump({ version: '1', modules: [] }));
+
+    writeManifest(tmpRoot, sampleManifest);
+
+    // Flat stays flat; no silent migration to nested, no shadow write.
+    expect(fs.existsSync(flat)).toBe(true);
+    expect(
+      fs.existsSync(path.join(tmpRoot, 'modules', 'modules.yaml')),
+    ).toBe(false);
+
+    const reread = readManifest(tmpRoot);
+    expect(reread).toEqual(sampleManifest);
+  });
+});
+
+describe('addModule', () => {
+  it('appends to the existing nested manifest without creating a flat shadow', () => {
+    writeManifest(tmpRoot, sampleManifest);
+
+    addModule(tmpRoot, {
+      name: 'knowledge-public-testing',
+      repo: 'https://github.com/indigoai-us/knowledge-public-testing.git',
+      strategy: 'link',
+      paths: [{ src: '.', dest: 'knowledge/public/testing' }],
+    });
+
+    const after = readManifest(tmpRoot);
+    expect(after?.modules).toHaveLength(2);
+    expect(fs.existsSync(path.join(tmpRoot, 'modules.yaml'))).toBe(false);
+  });
+});

package/src/utils/manifest.ts

@@ -18,8 +18,25 @@ export function findHqRoot(): string {
   return process.cwd();
 }
 
+/**
+ * Resolve the manifest path for a given HQ root.
+ *
+ * The canonical layout is nested: `{hqRoot}/modules/modules.yaml` (catalog)
+ * alongside `{hqRoot}/modules/<module-name>/` (clone targets).
+ *
+ * Legacy fixtures and very old HQ instances may have the flat layout
+ * (`{hqRoot}/modules.yaml`); we honor that if — and only if — the flat file
+ * already exists. On fresh HQs we default to the nested form so we never
+ * silently create a second shadow manifest at the root.
+ *
+ * Exported for tests.
+ */
 export function getManifestPath(hqRoot: string): string {
-  return path.join(hqRoot, MANIFEST_FILE);
+  const nested = path.join(hqRoot, 'modules', MANIFEST_FILE);
+  const flat = path.join(hqRoot, MANIFEST_FILE);
+  if (fs.existsSync(nested)) return nested;
+  if (fs.existsSync(flat)) return flat;
+  return nested; // default for fresh HQs — see getModulesDir()
 }
 
 export function getLockPath(hqRoot: string): string {
@@ -45,6 +62,10 @@ export function readManifest(hqRoot: string): ModulesManifest | null {
 
 export function writeManifest(hqRoot: string, manifest: ModulesManifest): void {
   const manifestPath = getManifestPath(hqRoot);
+  // Ensure the parent directory exists — on a fresh HQ the nested
+  // `modules/` dir may not yet be present, and fs.writeFileSync does not
+  // auto-mkdir. Safe no-op when the dir already exists.
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
   const content = yaml.dump(manifest, { lineWidth: -1 });
   fs.writeFileSync(manifestPath, content);
 }