@indigoai-us/hq-cli 5.5.1 → 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

@@ -20,6 +20,7 @@ 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();
 
@@ -64,12 +65,15 @@ registerCloudCommands(syncCmd);
 // Team commands (top-level)
 registerTeamSyncCommand(program);
 
-// Auth commands (top-level — registry auth via Clerk, separate from Cognito)
+// 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);
 

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

@@ -65,13 +65,13 @@ export async function ensureCognitoToken(options: {
   if (cached) {
     try {
       if (interactive) {
-        console.log(chalk.dim("  Refreshing expiring HQ session..."));
+        console.error(chalk.dim("  Refreshing expiring HQ session..."));
       }
       const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
       return refreshed.accessToken;
     } catch (err) {
       if (interactive) {
-        console.log(
+        console.error(
           chalk.dim(
             `  Refresh failed (${err instanceof Error ? err.message : err}), falling back to browser login`,
           ),
@@ -86,7 +86,7 @@ export async function ensureCognitoToken(options: {
     );
   }
 
-  console.log(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
+  console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
   const tokens = await browserLogin(DEFAULT_COGNITO);
   return tokens.accessToken;
 }

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);
 }

package/src/utils/secrets-cache.ts

@@ -0,0 +1,129 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const CACHE_DIR = path.join(os.homedir(), ".hq", "secrets-cache");
+const KEY_PATH = path.join(CACHE_DIR, ".key");
+const TTL_MS = 5 * 60 * 1000;
+const ALGORITHM = "aes-256-gcm";
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+
+function ensureCacheDir(companyUid: string): void {
+  const dir = path.join(CACHE_DIR, companyUid);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+function validateInputs(companyUid: string, name: string): boolean {
+  if (!companyUid || companyUid.includes("/") || companyUid.includes("..")) return false;
+  if (!/^[A-Z][A-Z0-9_]*$/.test(name)) return false;
+  return true;
+}
+
+function getOrCreateKey(): Buffer {
+  try {
+    const key = fs.readFileSync(KEY_PATH);
+    if (key.length === 32) {
+      const mode = fs.statSync(KEY_PATH).mode & 0o777;
+      if (mode !== 0o600) {
+        process.stderr.write(`Warning: secrets cache key has permissions ${mode.toString(8)}, expected 600\n`);
+      }
+      return key;
+    }
+  } catch {
+    // Key doesn't exist or is unreadable — generate a new one
+  }
+  fs.mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 });
+  const key = crypto.randomBytes(32);
+  const tmpPath = `${KEY_PATH}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpPath, key, { mode: 0o600 });
+  fs.renameSync(tmpPath, KEY_PATH);
+  return fs.readFileSync(KEY_PATH);
+}
+
+export function readCache(companyUid: string, name: string): string | null {
+  if (!validateInputs(companyUid, name)) return null;
+  const filePath = path.join(CACHE_DIR, companyUid, name);
+  let raw: Buffer;
+  try {
+    raw = fs.readFileSync(filePath);
+  } catch {
+    return null;
+  }
+
+  // Format: [8 bytes timestamp][12 bytes IV][16 bytes authTag][...ciphertext]
+  const headerLen = 8 + IV_BYTES + AUTH_TAG_BYTES;
+  if (raw.length < headerLen) return null;
+
+  const timestampMs = Number(raw.readBigInt64BE(0));
+  if (Date.now() - timestampMs > TTL_MS) {
+    try { fs.unlinkSync(filePath); } catch { /* ok */ }
+    return null;
+  }
+
+  const iv = raw.subarray(8, 8 + IV_BYTES);
+  const authTag = raw.subarray(8 + IV_BYTES, headerLen);
+  const ciphertext = raw.subarray(headerLen);
+
+  let key: Buffer;
+  try {
+    key = getOrCreateKey();
+  } catch {
+    return null;
+  }
+
+  try {
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString("utf8");
+  } catch {
+    try { fs.unlinkSync(filePath); } catch { /* ok */ }
+    return null;
+  }
+}
+
+export function writeCache(companyUid: string, name: string, value: string): void {
+  try {
+    if (!validateInputs(companyUid, name)) return;
+    ensureCacheDir(companyUid);
+    const key = getOrCreateKey();
+    const iv = crypto.randomBytes(IV_BYTES);
+    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+
+    const timestamp = Buffer.alloc(8);
+    timestamp.writeBigInt64BE(BigInt(Date.now()));
+
+    const out = Buffer.concat([timestamp, iv, authTag, encrypted]);
+    const filePath = path.join(CACHE_DIR, companyUid, name);
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmpPath, out, { mode: 0o600 });
+    fs.renameSync(tmpPath, filePath);
+  } catch {
+    // Cache write failure is non-fatal
+  }
+}
+
+export function removeCacheEntry(companyUid: string, name: string): void {
+  if (!validateInputs(companyUid, name)) return;
+  const filePath = path.join(CACHE_DIR, companyUid, name);
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+    // Cache entry may not exist
+  }
+}
+
+export function clearAllCache(): { removed: number } {
+  let removed = 0;
+  try {
+    fs.rmSync(CACHE_DIR, { recursive: true, force: true });
+    removed = 1;
+  } catch {
+    // Cache dir may not exist
+  }
+  return { removed };
+}

package/tsconfig.json

@@ -4,5 +4,6 @@
     "outDir": "dist",
     "rootDir": "src"
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
 }