@indigoai-us/hq-cli 5.3.1 → 5.4.0

package/src/utils/cognito-session.ts

@@ -0,0 +1,94 @@
+/**
+ * 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).
+ *
+ * Defaults point at the shared hq-vault-dev Cognito pool. Override 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
+ */
+
+import {
+  loadCachedTokens,
+  isExpiring,
+  refreshTokens,
+  browserLogin,
+  type CognitoAuthConfig,
+} 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",
+  port: process.env.HQ_COGNITO_CALLBACK_PORT
+    ? Number(process.env.HQ_COGNITO_CALLBACK_PORT)
+    : 8765,
+};
+
+/**
+ * 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.
+ */
+export async function ensureCognitoToken(options: {
+  interactive?: boolean;
+} = {}): Promise<string> {
+  const interactive = options.interactive ?? true;
+  const cached = loadCachedTokens();
+
+  if (cached && !isExpiring(cached, 120)) {
+    return cached.accessToken;
+  }
+
+  if (cached) {
+    try {
+      const refreshed = await refreshTokens(
+        DEFAULT_COGNITO,
+        cached.refreshToken,
+      );
+      return refreshed.accessToken;
+    } catch {
+      // fall through to browser login
+    }
+  }
+
+  if (!interactive) {
+    throw new Error(
+      "No valid HQ session and interactive login is disabled. Run `hq login` first.",
+    );
+  }
+
+  const tokens = await browserLogin(DEFAULT_COGNITO);
+  return tokens.accessToken;
+}
+
+/**
+ * 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.
+ */
+export async function refreshCachedSession(): Promise<{
+  refreshed: boolean;
+  reason?: string;
+}> {
+  const cached = loadCachedTokens();
+  if (!cached) {
+    return { refreshed: false, reason: "no cached session" };
+  }
+  try {
+    await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+    return { refreshed: true };
+  } catch (err) {
+    return {
+      refreshed: false,
+      reason: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/utils/git.ts

@@ -0,0 +1,74 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import simpleGit, { SimpleGit } from 'simple-git';
+
+export async function cloneRepo(repoUrl: string, targetDir: string, branch?: string): Promise<void> {
+  const git = simpleGit();
+  const options = branch ? ['--branch', branch] : [];
+  await git.clone(repoUrl, targetDir, options);
+}
+
+export async function fetchRepo(repoDir: string): Promise<void> {
+  const git = simpleGit(repoDir);
+  await git.fetch(['--all']);
+}
+
+export async function pullRepo(repoDir: string): Promise<void> {
+  const git = simpleGit(repoDir);
+  await git.pull();
+}
+
+export async function getCurrentCommit(repoDir: string): Promise<string> {
+  const git = simpleGit(repoDir);
+  const log = await git.log({ maxCount: 1 });
+  return log.latest?.hash ?? '';
+}
+
+export async function checkoutCommit(repoDir: string, commitSha: string): Promise<void> {
+  const git = simpleGit(repoDir);
+  await git.checkout(commitSha);
+}
+
+export async function isRepo(dir: string): Promise<boolean> {
+  if (!fs.existsSync(dir)) return false;
+  try {
+    const git = simpleGit(dir);
+    return await git.checkIsRepo();
+  } catch {
+    return false;
+  }
+}
+
+export async function getRemoteUrl(repoDir: string): Promise<string | null> {
+  try {
+    const git = simpleGit(repoDir);
+    const remotes = await git.getRemotes(true);
+    const origin = remotes.find(r => r.name === 'origin');
+    return origin?.refs?.fetch ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function isBehindRemote(repoDir: string): Promise<{ behind: boolean; commits: number }> {
+  try {
+    const git = simpleGit(repoDir);
+    await git.fetch();
+    const status = await git.status();
+    return { behind: status.behind > 0, commits: status.behind };
+  } catch {
+    return { behind: false, commits: 0 };
+  }
+}
+
+export function ensureGitignore(hqRoot: string, entry: string): void {
+  const gitignorePath = path.join(hqRoot, '.gitignore');
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  }
+  if (!content.includes(entry)) {
+    content = content.trimEnd() + '\n' + entry + '\n';
+    fs.writeFileSync(gitignorePath, content);
+  }
+}

package/src/utils/hq-root.ts

@@ -0,0 +1,27 @@
+/**
+ * HQ root detection — walks up from cwd looking for HQ markers (US-004)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Find the HQ root directory by walking up from cwd.
+ * Looks for CLAUDE.md or .claude/ directory as markers.
+ * Throws if not found.
+ */
+export function findHqRoot(): string {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (
+      fs.existsSync(path.join(dir, 'CLAUDE.md')) ||
+      fs.existsSync(path.join(dir, '.claude'))
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  throw new Error(
+    'Could not find HQ root. Run this command from within your HQ directory.'
+  );
+}

package/src/utils/integrity.ts

@@ -0,0 +1,54 @@
+/**
+ * Integrity verification — SHA256 hash and RSA signature checks (US-005)
+ */
+
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { findHqRoot } from './hq-root.js';
+
+/**
+ * Verify a file's SHA256 hash matches the expected value.
+ */
+export async function verifySha256(
+  filePath: string,
+  expectedHash: string
+): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => {
+      const computed = hash.digest('hex');
+      resolve(computed === expectedHash.toLowerCase());
+    });
+    stream.on('error', reject);
+  });
+}
+
+/**
+ * Verify an RSA signature of a SHA256 hash using the registry public key.
+ * The public key is expected at packages/.keys/registry-public.pem.
+ * Returns false (does not throw) if the key file is missing.
+ */
+export function verifyRsaSignature(
+  sha256Hash: string,
+  signature: string,
+  publicKeyPath?: string
+): boolean {
+  const keyPath =
+    publicKeyPath ??
+    path.resolve(findHqRoot(), 'packages', '.keys', 'registry-public.pem');
+
+  if (!fs.existsSync(keyPath)) {
+    return false;
+  }
+
+  const publicKey = fs.readFileSync(keyPath, 'utf-8');
+  const verifier = crypto.createVerify('SHA256');
+  verifier.update(sha256Hash);
+  verifier.end();
+
+  return verifier.verify(publicKey, Buffer.from(signature, 'base64'));
+}

package/src/utils/manifest.ts

@@ -0,0 +1,109 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import type { ModulesManifest, ModuleDefinition, ModuleLock, SyncState } from '../types.js';
+
+const MANIFEST_FILE = 'modules.yaml';
+const LOCK_FILE = 'modules.lock';
+const STATE_FILE = '.hq-sync-state.json';
+
+export function findHqRoot(): string {
+  let dir = process.cwd();
+  while (dir !== '/') {
+    if (fs.existsSync(path.join(dir, '.claude')) || fs.existsSync(path.join(dir, 'workers'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+export function getManifestPath(hqRoot: string): string {
+  return path.join(hqRoot, MANIFEST_FILE);
+}
+
+export function getLockPath(hqRoot: string): string {
+  return path.join(hqRoot, LOCK_FILE);
+}
+
+export function getStatePath(hqRoot: string): string {
+  return path.join(hqRoot, STATE_FILE);
+}
+
+export function getModulesDir(hqRoot: string): string {
+  return path.join(hqRoot, 'modules');
+}
+
+export function readManifest(hqRoot: string): ModulesManifest | null {
+  const manifestPath = getManifestPath(hqRoot);
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  const content = fs.readFileSync(manifestPath, 'utf-8');
+  return yaml.load(content) as ModulesManifest;
+}
+
+export function writeManifest(hqRoot: string, manifest: ModulesManifest): void {
+  const manifestPath = getManifestPath(hqRoot);
+  const content = yaml.dump(manifest, { lineWidth: -1 });
+  fs.writeFileSync(manifestPath, content);
+}
+
+export function readLock(hqRoot: string): ModuleLock | null {
+  const lockPath = getLockPath(hqRoot);
+  if (!fs.existsSync(lockPath)) {
+    return null;
+  }
+  const content = fs.readFileSync(lockPath, 'utf-8');
+  return yaml.load(content) as ModuleLock;
+}
+
+export function writeLock(hqRoot: string, lock: ModuleLock): void {
+  const lockPath = getLockPath(hqRoot);
+  const content = yaml.dump(lock, { lineWidth: -1 });
+  fs.writeFileSync(lockPath, content);
+}
+
+export function readState(hqRoot: string): SyncState | null {
+  const statePath = getStatePath(hqRoot);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  const content = fs.readFileSync(statePath, 'utf-8');
+  return JSON.parse(content) as SyncState;
+}
+
+export function writeState(hqRoot: string, state: SyncState): void {
+  const statePath = getStatePath(hqRoot);
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+
+export function addModule(hqRoot: string, module: ModuleDefinition): void {
+  let manifest = readManifest(hqRoot);
+  if (!manifest) {
+    manifest = { version: '1', modules: [] };
+  }
+
+  // Check for duplicates
+  if (manifest.modules.some(m => m.name === module.name)) {
+    throw new Error(`Module "${module.name}" already exists`);
+  }
+
+  manifest.modules.push(module);
+  writeManifest(hqRoot, manifest);
+}
+
+export function parseRepoName(repoUrl: string): string {
+  // Extract repo name from URL
+  // https://github.com/user/repo.git -> repo
+  // git@github.com:user/repo.git -> repo
+  const match = repoUrl.match(/[\/:]([^\/]+?)(\.git)?$/);
+  if (!match) {
+    throw new Error(`Cannot parse repo name from: ${repoUrl}`);
+  }
+  return match[1];
+}
+
+export function isValidRepoUrl(url: string): boolean {
+  return url.startsWith('https://') || url.startsWith('git@');
+}

package/src/utils/registry-client.ts

@@ -0,0 +1,204 @@
+/**
+ * Registry client — reads registry URL from packages/sources.yaml and provides
+ * API methods for the HQ package registry (US-004 base, US-005 full client).
+ *
+ * Auth tokens are NEVER written to stdout or logs.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { findHqRoot } from './hq-root.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface SourceEntry {
+  name: string;
+  url: string;
+  type: string;
+  auth: string;
+}
+
+interface SourcesFile {
+  sources: SourceEntry[];
+}
+
+export interface PackageMeta {
+  slug: string;
+  name: string;
+  description: string;
+  tier: string;
+  latest_version: string;
+  author?: string;
+}
+
+export interface PackageListResponse {
+  packages: PackageMeta[];
+}
+
+export interface PackageResponse {
+  package: PackageMeta;
+  versions: { version: string; published_at: string }[];
+}
+
+export interface EntitlementEntry {
+  slug: string;
+  tier: string;
+  granted_at: string;
+  expires_at?: string;
+}
+
+export interface EntitlementListResponse {
+  entitlements: EntitlementEntry[];
+}
+
+export interface EntitlementCheckResponse {
+  entitled: boolean;
+  tier?: string;
+  expires_at?: string;
+}
+
+export interface DownloadResponse {
+  url: string;
+  sha256: string;
+  signature?: string;
+}
+
+// ---------------------------------------------------------------------------
+// URL helper (unchanged from US-004)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the registry URL from packages/sources.yaml in the user's HQ root.
+ * Returns the URL of the first source entry.
+ * Throws if sources.yaml is missing or has no sources.
+ */
+export function getRegistryUrl(): string {
+  const hqRoot = findHqRoot();
+  const sourcesPath = path.join(hqRoot, 'packages', 'sources.yaml');
+
+  if (!fs.existsSync(sourcesPath)) {
+    throw new Error(
+      `No packages/sources.yaml found at ${sourcesPath}. Is your HQ packages directory set up?`
+    );
+  }
+
+  const content = fs.readFileSync(sourcesPath, 'utf-8');
+  const parsed = yaml.load(content) as SourcesFile;
+
+  if (!parsed?.sources?.length) {
+    throw new Error('No sources defined in packages/sources.yaml');
+  }
+
+  return parsed.sources[0].url;
+}
+
+// ---------------------------------------------------------------------------
+// RegistryClient
+// ---------------------------------------------------------------------------
+
+export class RegistryClient {
+  private baseUrl: string;
+  private authToken?: string;
+
+  constructor(baseUrl: string, authToken?: string) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.authToken = authToken;
+  }
+
+  // ---- helpers ----
+
+  private headers(auth: boolean): Record<string, string> {
+    const h: Record<string, string> = {
+      Accept: 'application/json',
+    };
+    if (auth && this.authToken) {
+      h['Authorization'] = `Bearer ${this.authToken}`;
+    }
+    return h;
+  }
+
+  private async request<T>(
+    method: string,
+    urlPath: string,
+    opts: { auth?: boolean; body?: unknown; timeout?: number } = {}
+  ): Promise<T> {
+    const auth = opts.auth ?? false;
+    const url = `${this.baseUrl}${urlPath}`;
+
+    const init: RequestInit = {
+      method,
+      headers: this.headers(auth),
+      signal: AbortSignal.timeout(opts.timeout ?? 30_000),
+    };
+
+    if (opts.body) {
+      (init.headers as Record<string, string>)['Content-Type'] =
+        'application/json';
+      init.body = JSON.stringify(opts.body);
+    }
+
+    const res = await fetch(url, init);
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(
+        `Registry API ${method} ${urlPath} failed (${res.status}): ${text}`
+      );
+    }
+
+    return (await res.json()) as T;
+  }
+
+  // ---- public (no auth) ----
+
+  async listPackages(opts?: {
+    tier?: string;
+    q?: string;
+  }): Promise<PackageListResponse> {
+    const params = new URLSearchParams();
+    if (opts?.tier) params.set('tier', opts.tier);
+    if (opts?.q) params.set('q', opts.q);
+    const qs = params.toString();
+    return this.request<PackageListResponse>(
+      'GET',
+      `/packages${qs ? `?${qs}` : ''}`
+    );
+  }
+
+  async getPackage(slug: string): Promise<PackageResponse> {
+    return this.request<PackageResponse>('GET', `/packages/${encodeURIComponent(slug)}`);
+  }
+
+  // ---- auth required ----
+
+  async getMyEntitlements(): Promise<EntitlementListResponse> {
+    return this.request<EntitlementListResponse>('GET', '/entitlements', {
+      auth: true,
+    });
+  }
+
+  async checkEntitlement(slug: string): Promise<EntitlementCheckResponse> {
+    return this.request<EntitlementCheckResponse>(
+      'GET',
+      `/entitlements/${encodeURIComponent(slug)}`,
+      { auth: true }
+    );
+  }
+
+  async getDownloadUrl(
+    slug: string,
+    version?: string
+  ): Promise<DownloadResponse> {
+    const params = new URLSearchParams();
+    if (version) params.set('version', version);
+    const qs = params.toString();
+    return this.request<DownloadResponse>(
+      'GET',
+      `/packages/${encodeURIComponent(slug)}/download${qs ? `?${qs}` : ''}`,
+      { auth: true }
+    );
+  }
+}

package/src/utils/registry.ts

@@ -0,0 +1,89 @@
+/**
+ * Registry YAML helpers — read/write packages/registry.yaml (US-005)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+
+export interface RegistryEntry {
+  name: string;
+  slug: string;
+  version: string;
+  source: string;
+  license_key?: string;
+  scope?: string;
+  installed_at: string;
+  updated_at: string;
+}
+
+interface RegistryFile {
+  packages: RegistryEntry[];
+}
+
+function registryPath(hqRoot: string): string {
+  return path.resolve(hqRoot, 'packages', 'registry.yaml');
+}
+
+/**
+ * Read all entries from packages/registry.yaml.
+ * Returns an empty array if the file does not exist.
+ */
+export function readRegistry(hqRoot: string): RegistryEntry[] {
+  const filePath = registryPath(hqRoot);
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const parsed = yaml.load(content) as RegistryFile | null;
+  return parsed?.packages ?? [];
+}
+
+/**
+ * Write the full registry back to packages/registry.yaml.
+ */
+export function writeRegistry(
+  hqRoot: string,
+  entries: RegistryEntry[]
+): void {
+  const filePath = registryPath(hqRoot);
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const content = yaml.dump(
+    { packages: entries },
+    { lineWidth: 120, noRefs: true }
+  );
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Add or update an entry in packages/registry.yaml.
+ * If an entry with the same slug exists, it is replaced.
+ */
+export function addToRegistry(
+  hqRoot: string,
+  entry: RegistryEntry
+): void {
+  const entries = readRegistry(hqRoot);
+  const idx = entries.findIndex((e) => e.slug === entry.slug);
+  if (idx >= 0) {
+    entries[idx] = entry;
+  } else {
+    entries.push(entry);
+  }
+  writeRegistry(hqRoot, entries);
+}
+
+/**
+ * Remove an entry by slug from packages/registry.yaml.
+ * No-op if the slug is not found.
+ */
+export function removeFromRegistry(
+  hqRoot: string,
+  slug: string
+): void {
+  const entries = readRegistry(hqRoot).filter((e) => e.slug !== slug);
+  writeRegistry(hqRoot, entries);
+}