@indigoai-us/hq-cli 5.3.0 → 5.4.0

package/src/commands/list.ts

@@ -0,0 +1,66 @@
+/**
+ * hq modules list command (US-005)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import { findHqRoot, readManifest, readLock, getModulesDir } from '../utils/manifest.js';
+import { isRepo, getCurrentCommit, isBehindRemote } from '../utils/git.js';
+
+export function registerListCommand(program: Command): void {
+  program
+    .command('list')
+    .alias('ls')
+    .description('List all modules and their status')
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const manifest = readManifest(hqRoot);
+
+        if (!manifest || manifest.modules.length === 0) {
+          console.log('No modules in manifest. Use "hq modules add" to add modules.');
+          return;
+        }
+
+        const modulesDir = getModulesDir(hqRoot);
+        const lock = readLock(hqRoot);
+
+        console.log('Modules:\n');
+
+        for (const module of manifest.modules) {
+          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}`);
+          console.log(`    Paths:    ${module.paths.map(p => `${p.src} -> ${p.dest}`).join(', ')}`);
+
+          if (installed) {
+            const commit = await getCurrentCommit(moduleDir);
+            const shortCommit = commit.slice(0, 7);
+            const lockedCommit = lock?.locked[module.name];
+            const isLocked = lockedCommit === commit;
+
+            console.log(`    Status:   ✓ installed @ ${shortCommit}${isLocked ? ' (locked)' : ''}`);
+
+            // Check if behind upstream
+            const { behind, commits } = await isBehindRemote(moduleDir);
+            if (behind) {
+              console.log(`    Updates:  ${commits} commit(s) behind remote`);
+            }
+          } else {
+            console.log(`    Status:   ✗ not installed`);
+          }
+
+          console.log();
+        }
+
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/login.ts

@@ -0,0 +1,29 @@
+/**
+ * hq login — opens browser for Clerk auth, caches token (US-004)
+ */
+
+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';
+
+export function registerLoginCommand(program: Command): void {
+  program
+    .command('login')
+    .description('Authenticate with the HQ package registry')
+    .action(async () => {
+      try {
+        const registryUrl = getRegistryUrl();
+        const token = await startAuthFlow(registryUrl);
+        await saveToken(token);
+        console.log(chalk.green(`Logged in as ${token.email}`));
+      } catch (error) {
+        console.error(
+          chalk.red('Login failed:'),
+          error instanceof Error ? error.message : 'Unknown error'
+        );
+        process.exit(1);
+      }
+    });
+}

package/src/commands/logout.ts

@@ -0,0 +1,25 @@
+/**
+ * hq logout — clears cached session (US-004)
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { clearToken } from '../utils/token-store.js';
+
+export function registerLogoutCommand(program: Command): void {
+  program
+    .command('logout')
+    .description('Log out and clear cached credentials')
+    .action(async () => {
+      try {
+        await clearToken();
+        console.log(chalk.green('Logged out successfully'));
+      } catch (error) {
+        console.error(
+          chalk.red('Logout failed:'),
+          error instanceof Error ? error.message : 'Unknown error'
+        );
+        process.exit(1);
+      }
+    });
+}

package/src/commands/pkg-install.ts

@@ -0,0 +1,181 @@
+/**
+ * hq packages install <slug> — download, verify, and extract a package (US-005)
+ *
+ * Flow:
+ * 1. Check auth (prompt login if needed)
+ * 2. Check entitlement via API
+ * 3. Download tarball via presigned URL
+ * 4. Verify SHA256 hash
+ * 5. Verify RSA signature (if provided)
+ * 6. Extract to packages/installed/<slug>/
+ * 7. Validate extracted package.yaml slug matches
+ * 8. Update packages/registry.yaml
+ * 9. Print next-step message
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { execSync } from 'child_process';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getAuthToken } from '../utils/auth.js';
+import { findHqRoot } from '../utils/hq-root.js';
+import {
+  getRegistryUrl,
+  RegistryClient,
+} from '../utils/registry-client.js';
+import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
+import { addToRegistry } from '../utils/registry.js';
+
+export function registerPackageInstallCommand(parent: Command): void {
+  parent
+    .command('install <slug>')
+    .description('Install a package from the registry')
+    .option('--company <co>', 'Scope the package to a specific company')
+    .action(async (slug: string, opts: { company?: string }) => {
+      try {
+        await installPackage(slug, opts.company);
+      } catch (error) {
+        console.error(
+          chalk.red('Install failed:'),
+          error instanceof Error ? error.message : 'Unknown error'
+        );
+        process.exit(1);
+      }
+    });
+}
+
+async function installPackage(
+  slug: string,
+  company?: string
+): Promise<void> {
+  // 1. Auth
+  const token = await getAuthToken();
+  const registryUrl = getRegistryUrl();
+  const client = new RegistryClient(registryUrl, token.clerk_session_token);
+
+  // 2. Check entitlement
+  console.log(chalk.dim(`Checking entitlement for ${slug}...`));
+  const entitlement = await client.checkEntitlement(slug);
+  if (!entitlement.entitled) {
+    throw new Error(
+      `You are not entitled to package "${slug}". Visit the registry to purchase or request access.`
+    );
+  }
+
+  // 3. Get download URL
+  console.log(chalk.dim('Fetching download URL...'));
+  const download = await client.getDownloadUrl(slug);
+
+  // 4. Download to temp file
+  const tmpDir = os.tmpdir();
+  const tmpFile = path.resolve(tmpDir, `hq-pkg-${slug}-${Date.now()}.tar.gz`);
+
+  try {
+    console.log(chalk.dim('Downloading package...'));
+    const response = await fetch(download.url, {
+      signal: AbortSignal.timeout(120_000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Download failed (${response.status})`);
+    }
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+    fs.writeFileSync(tmpFile, buffer);
+
+    // 5. Verify SHA256
+    console.log(chalk.dim('Verifying integrity...'));
+    const hashValid = await verifySha256(tmpFile, download.sha256);
+    if (!hashValid) {
+      throw new Error(
+        'SHA256 hash mismatch — the downloaded file may be corrupted or tampered with.'
+      );
+    }
+
+    // 6. Verify RSA signature (if provided)
+    if (download.signature) {
+      const sigValid = verifyRsaSignature(download.sha256, download.signature);
+      if (!sigValid) {
+        throw new Error(
+          'RSA signature verification failed — the package may have been tampered with or the public key is missing/invalid. Aborting install.'
+        );
+      }
+    }
+
+    // 7. Extract
+    const hqRoot = findHqRoot();
+    const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
+
+    // Clean existing installation
+    if (fs.existsSync(installDir)) {
+      fs.rmSync(installDir, { recursive: true, force: true });
+    }
+    fs.mkdirSync(installDir, { recursive: true });
+
+    execSync(`tar -xzf "${tmpFile}" -C "${installDir}"`, {
+      stdio: 'pipe',
+    });
+
+    // 8. Validate package.yaml slug
+    const packageYamlPath = path.resolve(installDir, 'package.yaml');
+    if (fs.existsSync(packageYamlPath)) {
+      const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
+      const pkgMeta = yaml.load(pkgContent) as { slug?: string } | null;
+      if (pkgMeta?.slug && pkgMeta.slug !== slug) {
+        // Mismatch — clean up and abort
+        fs.rmSync(installDir, { recursive: true, force: true });
+        throw new Error(
+          `Package slug mismatch: expected "${slug}", got "${pkgMeta.slug}"`
+        );
+      }
+    }
+
+    // 9. Get package info for registry entry
+    let version = 'unknown';
+    let name = slug;
+    try {
+      const pkgInfo = await client.getPackage(slug);
+      version = pkgInfo.package.latest_version;
+      name = pkgInfo.package.name;
+    } catch {
+      // Best-effort — fall back to package.yaml if present
+      const packageYaml = path.resolve(installDir, 'package.yaml');
+      if (fs.existsSync(packageYaml)) {
+        const content = fs.readFileSync(packageYaml, 'utf-8');
+        const meta = yaml.load(content) as {
+          version?: string;
+          name?: string;
+        } | null;
+        if (meta?.version) version = meta.version;
+        if (meta?.name) name = meta.name;
+      }
+    }
+
+    // 10. Update registry.yaml
+    const now = new Date().toISOString();
+    addToRegistry(hqRoot, {
+      name,
+      slug,
+      version,
+      source: registryUrl,
+      scope: company,
+      installed_at: now,
+      updated_at: now,
+    });
+
+    console.log(chalk.green(`\nInstalled ${slug}@${version} to packages/installed/${slug}/`));
+    console.log(
+      chalk.cyan(
+        'Run /package-install ' + slug + ' in Claude to merge into your HQ.'
+      )
+    );
+  } finally {
+    // Clean up temp file — never leave partial downloads
+    if (fs.existsSync(tmpFile)) {
+      fs.unlinkSync(tmpFile);
+    }
+  }
+}

package/src/commands/pkg-list.ts

@@ -0,0 +1,98 @@
+/**
+ * hq packages list — show installed packages and available entitlements (US-005)
+ *
+ * Graceful offline: if registry is unreachable, show cached data with a note.
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { findHqRoot } from '../utils/hq-root.js';
+import { readRegistry } from '../utils/registry.js';
+import { loadToken, isTokenExpired } from '../utils/token-store.js';
+import {
+  getRegistryUrl,
+  RegistryClient,
+  type EntitlementEntry,
+} from '../utils/registry-client.js';
+
+export function registerPackageListCommand(parent: Command): void {
+  parent
+    .command('list')
+    .alias('ls')
+    .description('List installed and available packages')
+    .action(async () => {
+      try {
+        await listPackages();
+      } catch (error) {
+        console.error(
+          chalk.red('List failed:'),
+          error instanceof Error ? error.message : 'Unknown error'
+        );
+        process.exit(1);
+      }
+    });
+}
+
+async function listPackages(): Promise<void> {
+  const hqRoot = findHqRoot();
+  const installed = readRegistry(hqRoot);
+
+  // Print installed packages
+  if (installed.length > 0) {
+    console.log(chalk.bold('Installed packages:\n'));
+    for (const pkg of installed) {
+      const scope = pkg.scope ? chalk.dim(` (${pkg.scope})`) : '';
+      console.log(`  ${chalk.green(pkg.slug)}@${pkg.version}${scope}`);
+      console.log(
+        chalk.dim(
+          `    Installed: ${pkg.installed_at.slice(0, 10)}  Updated: ${pkg.updated_at.slice(0, 10)}`
+        )
+      );
+    }
+    console.log();
+  } else {
+    console.log(chalk.dim('No packages installed.\n'));
+  }
+
+  // Try to show available (but not installed) packages from entitlements
+  let entitlements: EntitlementEntry[] = [];
+  let offline = false;
+
+  try {
+    const token = await loadToken();
+    if (token && !isTokenExpired(token)) {
+      const registryUrl = getRegistryUrl();
+      const client = new RegistryClient(
+        registryUrl,
+        token.clerk_session_token
+      );
+      const result = await client.getMyEntitlements();
+      entitlements = result.entitlements;
+    }
+  } catch {
+    offline = true;
+  }
+
+  const installedSlugs = new Set(installed.map((p) => p.slug));
+  const available = entitlements.filter((e) => !installedSlugs.has(e.slug));
+
+  if (available.length > 0) {
+    console.log(chalk.bold('Available (not installed):\n'));
+    for (const ent of available) {
+      console.log(
+        `  ${chalk.cyan(ent.slug)} ${chalk.dim(`[${ent.tier}]`)}  ${chalk.yellow('available')}`
+      );
+    }
+    console.log(
+      chalk.dim('\nRun "hq packages install <slug>" to install.\n')
+    );
+  }
+
+  if (offline) {
+    console.log(
+      chalk.yellow(
+        'Note: Could not reach registry — showing cached data only.'
+      )
+    );
+  }
+}

package/src/commands/pkg-remove.ts

@@ -0,0 +1,71 @@
+/**
+ * hq packages remove <slug> — archive and unregister a package (US-005)
+ *
+ * 1. Archive packages/installed/<slug>/ to packages/.archive/<slug>-<timestamp>/
+ * 2. Remove entry from packages/registry.yaml
+ * 3. Print next-step message
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { findHqRoot } from '../utils/hq-root.js';
+import { removeFromRegistry, readRegistry } from '../utils/registry.js';
+
+export function registerPackageRemoveCommand(parent: Command): void {
+  parent
+    .command('remove <slug>')
+    .description('Remove an installed package (archives it first)')
+    .action(async (slug: string) => {
+      try {
+        await removePackage(slug);
+      } catch (error) {
+        console.error(
+          chalk.red('Remove failed:'),
+          error instanceof Error ? error.message : 'Unknown error'
+        );
+        process.exit(1);
+      }
+    });
+}
+
+async function removePackage(slug: string): Promise<void> {
+  const hqRoot = findHqRoot();
+  const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
+
+  // Verify it is actually installed
+  const entries = readRegistry(hqRoot);
+  const entry = entries.find((e) => e.slug === slug);
+  if (!entry && !fs.existsSync(installDir)) {
+    throw new Error(`Package "${slug}" is not installed.`);
+  }
+
+  // 1. Archive
+  if (fs.existsSync(installDir)) {
+    const timestamp = new Date()
+      .toISOString()
+      .replace(/[:.]/g, '-')
+      .replace('T', '_')
+      .slice(0, 19);
+    const archiveDir = path.resolve(
+      hqRoot,
+      'packages',
+      '.archive',
+      `${slug}-${timestamp}`
+    );
+    fs.mkdirSync(path.dirname(archiveDir), { recursive: true });
+    fs.renameSync(installDir, archiveDir);
+    console.log(chalk.dim(`Archived to packages/.archive/${slug}-${timestamp}/`));
+  }
+
+  // 2. Remove from registry.yaml
+  removeFromRegistry(hqRoot, slug);
+
+  console.log(chalk.green(`\nRemoved ${slug}.`));
+  console.log(
+    chalk.cyan(
+      'Run /package-remove ' + slug + ' in Claude to clean up merged content.'
+    )
+  );
+}

package/src/commands/pkg-update.ts

@@ -0,0 +1,189 @@
+/**
+ * hq packages update [slug] — check for and apply package updates (US-005)
+ *
+ * If no slug: check all installed packages for updates.
+ * If slug given: update only that package.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { execSync } from 'child_process';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getAuthToken } from '../utils/auth.js';
+import { findHqRoot } from '../utils/hq-root.js';
+import {
+  getRegistryUrl,
+  RegistryClient,
+} from '../utils/registry-client.js';
+import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
+import {
+  readRegistry,
+  addToRegistry,
+  type RegistryEntry,
+} from '../utils/registry.js';
+
+export function registerPackageUpdateCommand(parent: Command): void {
+  parent
+    .command('update [slug]')
+    .description('Check for and apply package updates')
+    .action(async (slug?: string) => {
+      try {
+        await updatePackages(slug);
+      } catch (error) {
+        console.error(
+          chalk.red('Update failed:'),
+          error instanceof Error ? error.message : 'Unknown error'
+        );
+        process.exit(1);
+      }
+    });
+}
+
+async function updatePackages(slug?: string): Promise<void> {
+  const hqRoot = findHqRoot();
+  const entries = readRegistry(hqRoot);
+
+  if (entries.length === 0) {
+    console.log('No packages installed. Use "hq packages install <slug>" to install one.');
+    return;
+  }
+
+  const token = await getAuthToken();
+  const registryUrl = getRegistryUrl();
+  const client = new RegistryClient(registryUrl, token.clerk_session_token);
+
+  const toCheck = slug
+    ? entries.filter((e) => e.slug === slug)
+    : entries;
+
+  if (slug && toCheck.length === 0) {
+    throw new Error(`Package "${slug}" is not installed.`);
+  }
+
+  let updatedCount = 0;
+
+  for (const entry of toCheck) {
+    try {
+      const pkgInfo = await client.getPackage(entry.slug);
+      const latestVersion = pkgInfo.package.latest_version;
+
+      if (latestVersion === entry.version) {
+        console.log(chalk.dim(`${entry.slug}@${entry.version} — up to date`));
+        continue;
+      }
+
+      console.log(
+        chalk.yellow(
+          `${entry.slug}: ${entry.version} → ${latestVersion}`
+        )
+      );
+
+      // Download new version
+      const download = await client.getDownloadUrl(
+        entry.slug,
+        latestVersion
+      );
+
+      const tmpFile = path.resolve(
+        os.tmpdir(),
+        `hq-pkg-${entry.slug}-${Date.now()}.tar.gz`
+      );
+
+      try {
+        const response = await fetch(download.url, {
+          signal: AbortSignal.timeout(120_000),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Download failed (${response.status})`);
+        }
+
+        const buffer = Buffer.from(await response.arrayBuffer());
+        fs.writeFileSync(tmpFile, buffer);
+
+        // Verify SHA256
+        const hashValid = await verifySha256(tmpFile, download.sha256);
+        if (!hashValid) {
+          throw new Error('SHA256 hash mismatch');
+        }
+
+        // Verify RSA signature (if provided)
+        if (download.signature) {
+          const sigValid = verifyRsaSignature(
+            download.sha256,
+            download.signature
+          );
+          if (!sigValid) {
+            console.warn(
+              chalk.yellow(
+                `  Warning: RSA signature verification failed for ${entry.slug}. Proceeding with SHA256-only.`
+              )
+            );
+          }
+        }
+
+        // Extract over existing
+        const installDir = path.resolve(
+          hqRoot,
+          'packages',
+          'installed',
+          entry.slug
+        );
+
+        if (fs.existsSync(installDir)) {
+          fs.rmSync(installDir, { recursive: true, force: true });
+        }
+        fs.mkdirSync(installDir, { recursive: true });
+
+        execSync(`tar -xzf "${tmpFile}" -C "${installDir}"`, {
+          stdio: 'pipe',
+        });
+
+        // Validate package.yaml slug
+        const packageYamlPath = path.resolve(installDir, 'package.yaml');
+        if (fs.existsSync(packageYamlPath)) {
+          const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
+          const pkgMeta = yaml.load(pkgContent) as {
+            slug?: string;
+          } | null;
+          if (pkgMeta?.slug && pkgMeta.slug !== entry.slug) {
+            fs.rmSync(installDir, { recursive: true, force: true });
+            throw new Error(
+              `Package slug mismatch: expected "${entry.slug}", got "${pkgMeta.slug}"`
+            );
+          }
+        }
+
+        // Update registry entry — preserve scope
+        const now = new Date().toISOString();
+        const updated: RegistryEntry = {
+          ...entry,
+          version: latestVersion,
+          updated_at: now,
+        };
+        addToRegistry(hqRoot, updated);
+
+        console.log(
+          chalk.green(`  Updated ${entry.slug} to ${latestVersion}`)
+        );
+        updatedCount++;
+      } finally {
+        if (fs.existsSync(tmpFile)) {
+          fs.unlinkSync(tmpFile);
+        }
+      }
+    } catch (error) {
+      console.error(
+        chalk.red(`  Error updating ${entry.slug}:`),
+        error instanceof Error ? error.message : 'Unknown error'
+      );
+    }
+  }
+
+  console.log(
+    `\n${updatedCount} package(s) updated${updatedCount > 0 ? '.' : ' — everything is current.'}`
+  );
+}