@indigoai-us/hq-cli 5.3.1 → 5.5.0

package/src/commands/whoami.ts

@@ -0,0 +1,38 @@
+/**
+ * hq whoami — displays current user or 'not logged in' (US-004)
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadToken, isTokenExpired } from '../utils/token-store.js';
+
+export function registerWhoamiCommand(program: Command): void {
+  program
+    .command('whoami')
+    .description('Show the currently authenticated user')
+    .action(async () => {
+      try {
+        const token = await loadToken();
+
+        if (!token) {
+          console.log("Not logged in. Run 'hq login' to authenticate.");
+          return;
+        }
+
+        if (isTokenExpired(token)) {
+          console.log(
+            chalk.yellow(`Session expired for ${token.email}. Run 'hq login' to re-authenticate.`)
+          );
+          return;
+        }
+
+        console.log(`Logged in as ${token.email} (${token.user_id})`);
+      } catch (error) {
+        console.error(
+          chalk.red('Error:'),
+          error instanceof Error ? error.message : 'Unknown error'
+        );
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+/**
+ * HQ CLI - Module management, package management, and cloud sync for HQ
+ */
+
+import { Command } from "commander";
+import { registerAddCommand } from "./commands/add.js";
+import { registerSyncCommand } from "./commands/sync.js";
+import { registerListCommand } from "./commands/list.js";
+import { registerUpdateCommand } from "./commands/update.js";
+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 { 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";
+
+const program = new Command();
+
+program
+  .name("hq")
+  .description("HQ management CLI — modules, packages, and cloud sync")
+  .version("5.5.0");
+
+// Module management subcommand group
+const modulesCmd = program
+  .command("modules")
+  .description("Module management commands");
+
+registerAddCommand(modulesCmd);
+registerSyncCommand(modulesCmd);
+registerListCommand(modulesCmd);
+registerUpdateCommand(modulesCmd);
+
+// Package management subcommand group
+const packagesCmd = program
+  .command("packages")
+  .description("Package management commands");
+
+registerPackageInstallCommand(packagesCmd);
+registerPackageRemoveCommand(packagesCmd);
+registerPackageUpdateCommand(packagesCmd);
+registerPackageListCommand(packagesCmd);
+
+// Top-level shortcuts for package commands
+// "hq install <slug>" = "hq packages install <slug>"
+// "hq remove <slug>"  = "hq packages remove <slug>"
+registerPackageInstallCommand(program);
+registerPackageRemoveCommand(program);
+
+// Cloud sync subcommand group
+const syncCmd = program
+  .command("sync")
+  .description("Cloud sync commands — sync HQ to S3 for mobile access");
+
+registerCloudCommands(syncCmd);
+
+// Team commands (top-level)
+registerTeamSyncCommand(program);
+
+// Auth commands (top-level)
+registerLoginCommand(program);
+registerLogoutCommand(program);
+registerWhoamiCommand(program);
+registerAuthCommands(program);
+
+program.parse();

package/src/schemas/hq-package.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "hq-package.yaml",
+  "description": "Manifest schema for HQ packages — versioned bundles of workers, commands, skills, and knowledge installable via hq install.",
+  "type": "object",
+  "required": ["name", "type", "version", "description", "author", "exposes"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Package slug — lowercase alphanumeric with hyphens. Used as the registry identifier and install target directory name.",
+      "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$",
+      "minLength": 1
+    },
+    "type": {
+      "type": "string",
+      "description": "Package type. Controls install target routing for all exposes entries.",
+      "enum": ["worker-pack", "command-set", "skill-bundle", "knowledge-base", "company-template"]
+    },
+    "version": {
+      "type": "string",
+      "description": "Semver version string for this release.",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
+    },
+    "minHQVersion": {
+      "type": "string",
+      "description": "Minimum HQ version required to install this package. Installer aborts if installed HQ version is below this value.",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Short human-readable description of what this package provides.",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "author": {
+      "type": "string",
+      "description": "Author name or organization that created and maintains this package.",
+      "minLength": 1
+    },
+    "repo": {
+      "type": "string",
+      "description": "Git repository URL for the package source. Used as offline fallback when the registry is unavailable.",
+      "pattern": "^(https?://|git@|ssh://).+"
+    },
+    "requires": {
+      "type": "object",
+      "description": "External dependencies this package needs at runtime.",
+      "additionalProperties": false,
+      "properties": {
+        "packages": {
+          "type": "array",
+          "description": "HQ package slugs this package depends on. Installed before this package.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$"
+          },
+          "uniqueItems": true
+        },
+        "services": {
+          "type": "array",
+          "description": "Service slugs required at runtime. Installer warns if not configured in the target HQ installation.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "exposes": {
+      "type": "object",
+      "description": "Declares what this package installs into the HQ workspace. At least one sub-array must be non-empty.",
+      "additionalProperties": false,
+      "properties": {
+        "workers": {
+          "type": "array",
+          "description": "Paths within the tarball to worker.yaml files to install.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "commands": {
+          "type": "array",
+          "description": "Paths within the tarball to command .md files to install.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "skills": {
+          "type": "array",
+          "description": "Paths within the tarball to skill .md files to install.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "knowledge": {
+          "type": "array",
+          "description": "Paths within the tarball to knowledge directories or files to install.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Shell scripts run at install lifecycle events. Each value is a path within the tarball to an executable shell script.",
+      "additionalProperties": false,
+      "properties": {
+        "on-install": {
+          "type": "string",
+          "description": "Path to shell script run after all files are installed.",
+          "minLength": 1
+        },
+        "on-update": {
+          "type": "string",
+          "description": "Path to shell script run after an existing installation is updated.",
+          "minLength": 1
+        },
+        "on-remove": {
+          "type": "string",
+          "description": "Path to shell script run before files are removed from the HQ workspace.",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/src/strategies/link.ts

@@ -0,0 +1,62 @@
+/**
+ * Link Sync Strategy (US-006)
+ * Symlinks module paths into HQ tree
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { ModuleDefinition, SyncResult } from '../types.js';
+
+export async function linkSync(
+  module: ModuleDefinition,
+  moduleDir: string,
+  hqRoot: string
+): Promise<SyncResult> {
+  let filesChanged = 0;
+
+  for (const mapping of module.paths) {
+    const srcPath = path.join(moduleDir, mapping.src);
+    const destPath = path.join(hqRoot, mapping.dest);
+
+    // Validate source exists
+    if (!fs.existsSync(srcPath)) {
+      return {
+        module: module.name,
+        success: false,
+        action: 'skipped',
+        message: `Source path not found: ${mapping.src}`,
+      };
+    }
+
+    // Ensure dest parent directory exists
+    const destDir = path.dirname(destPath);
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+
+    // Handle existing dest
+    if (fs.existsSync(destPath)) {
+      const stat = fs.lstatSync(destPath);
+      if (stat.isSymbolicLink()) {
+        // Remove existing symlink and recreate
+        fs.unlinkSync(destPath);
+      } else {
+        // Real file exists - warn and skip
+        console.warn(`  Warning: Real file exists at ${mapping.dest}, skipping`);
+        continue;
+      }
+    }
+
+    // Create relative symlink for portability
+    const relativeSrc = path.relative(destDir, srcPath);
+    fs.symlinkSync(relativeSrc, destPath);
+    filesChanged++;
+  }
+
+  return {
+    module: module.name,
+    success: true,
+    action: 'synced',
+    filesChanged,
+  };
+}

package/src/strategies/merge.ts

@@ -0,0 +1,142 @@
+/**
+ * Merge Sync Strategy (US-007)
+ * Copies files from module into HQ, tracks state for conflict detection
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import type { ModuleDefinition, SyncResult, SyncState } from '../types.js';
+import { readState, writeState } from '../utils/manifest.js';
+
+function hashFile(filePath: string): string {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function copyRecursive(
+  srcDir: string,
+  destDir: string,
+  state: SyncState,
+  moduleName: string,
+  hqRoot: string,
+  filesChanged: { count: number }
+): void {
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath, state, moduleName, hqRoot, filesChanged);
+    } else {
+      const relativeDest = path.relative(hqRoot, destPath);
+      const newHash = hashFile(srcPath);
+
+      // Check if file exists and has been modified by user
+      if (fs.existsSync(destPath)) {
+        const existingHash = hashFile(destPath);
+        const lastSyncedHash = state.files[relativeDest]?.hash;
+
+        if (lastSyncedHash && existingHash !== lastSyncedHash && existingHash !== newHash) {
+          // User modified the file since last sync - skip (conflict)
+          console.warn(`  Conflict: ${relativeDest} has local changes, skipping`);
+          continue;
+        }
+
+        if (existingHash === newHash) {
+          // File unchanged, skip
+          continue;
+        }
+      }
+
+      // Copy file
+      fs.copyFileSync(srcPath, destPath);
+      filesChanged.count++;
+
+      // Track in state
+      state.files[relativeDest] = {
+        hash: newHash,
+        syncedAt: new Date().toISOString(),
+        fromModule: moduleName,
+      };
+    }
+  }
+}
+
+export async function mergeSync(
+  module: ModuleDefinition,
+  moduleDir: string,
+  hqRoot: string
+): Promise<SyncResult> {
+  let state = readState(hqRoot);
+  if (!state) {
+    state = { version: '1', files: {} };
+  }
+
+  const filesChanged = { count: 0 };
+
+  for (const mapping of module.paths) {
+    const srcPath = path.join(moduleDir, mapping.src);
+    const destPath = path.join(hqRoot, mapping.dest);
+
+    if (!fs.existsSync(srcPath)) {
+      return {
+        module: module.name,
+        success: false,
+        action: 'skipped',
+        message: `Source path not found: ${mapping.src}`,
+      };
+    }
+
+    const srcStat = fs.statSync(srcPath);
+    if (srcStat.isDirectory()) {
+      copyRecursive(srcPath, destPath, state, module.name, hqRoot, filesChanged);
+    } else {
+      // Single file
+      const destDir = path.dirname(destPath);
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
+
+      const relativeDest = path.relative(hqRoot, destPath);
+      const newHash = hashFile(srcPath);
+
+      if (fs.existsSync(destPath)) {
+        const existingHash = hashFile(destPath);
+        const lastSyncedHash = state.files[relativeDest]?.hash;
+
+        if (lastSyncedHash && existingHash !== lastSyncedHash && existingHash !== newHash) {
+          console.warn(`  Conflict: ${relativeDest} has local changes, skipping`);
+          continue;
+        }
+
+        if (existingHash === newHash) {
+          continue;
+        }
+      }
+
+      fs.copyFileSync(srcPath, destPath);
+      filesChanged.count++;
+
+      state.files[relativeDest] = {
+        hash: newHash,
+        syncedAt: new Date().toISOString(),
+        fromModule: module.name,
+      };
+    }
+  }
+
+  writeState(hqRoot, state);
+
+  return {
+    module: module.name,
+    success: true,
+    action: 'synced',
+    filesChanged: filesChanged.count,
+  };
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * HQ Module Manifest Types (US-001)
+ */
+
+export type SyncStrategy = 'link' | 'merge' | 'copy';
+export type AccessLevel = 'public' | 'team' | `role:${string}`;
+
+export interface PathMapping {
+  src: string;   // Path within module repo
+  dest: string;  // Path in HQ tree (relative to HQ root)
+}
+
+export interface ModuleDefinition {
+  name: string;
+  repo: string;              // Git URL (https or git@)
+  branch?: string;           // Default: main
+  strategy: SyncStrategy;    // link | merge | copy
+  paths: PathMapping[];      // What to sync and where
+  access?: AccessLevel;      // For future RBAC
+}
+
+export interface ModulesManifest {
+  version: '1';
+  modules: ModuleDefinition[];
+}
+
+export interface ModuleLock {
+  version: '1';
+  locked: Record<string, string>; // module name -> commit SHA
+}
+
+export interface SyncState {
+  version: '1';
+  files: Record<string, {
+    hash: string;          // SHA256 of file content at sync time
+    syncedAt: string;      // ISO timestamp
+    fromModule: string;    // Module that provided this file
+  }>;
+}
+
+export interface SyncResult {
+  module: string;
+  success: boolean;
+  action: 'cloned' | 'fetched' | 'synced' | 'skipped';
+  message?: string;
+  filesChanged?: number;
+}

package/src/utils/auth.ts

@@ -0,0 +1,193 @@
+/**
+ * Auth utilities — OAuth PKCE flow for Clerk (US-004)
+ *
+ * Token values are NEVER written to stdout or logs.
+ */
+
+import * as crypto from 'crypto';
+import * as http from 'http';
+import { exec } from 'child_process';
+import { saveToken, loadToken, isTokenExpired } from './token-store.js';
+import { getRegistryUrl } from './registry-client.js';
+import type { AuthToken } from './token-store.js';
+
+/**
+ * Generate a cryptographically random PKCE code verifier (43-128 chars, URL-safe).
+ */
+function generateCodeVerifier(): string {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+/**
+ * Derive the PKCE code challenge from the verifier (S256).
+ */
+function generateCodeChallenge(verifier: string): string {
+  return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+
+/**
+ * Open a URL in the default browser (macOS / Linux).
+ */
+function openBrowser(url: string): void {
+  const command =
+    process.platform === 'darwin' ? `open "${url}"` : `xdg-open "${url}"`;
+  exec(command, (err) => {
+    if (err) {
+      // Non-fatal — user can manually open the URL
+      console.error(
+        `Could not open browser automatically. Please visit:\n  ${url}`
+      );
+    }
+  });
+}
+
+/**
+ * Start the OAuth PKCE auth flow:
+ * 1. Generate PKCE code_verifier + code_challenge
+ * 2. Start local HTTP server on a random port for the callback
+ * 3. Open browser to Clerk auth URL
+ * 4. Wait for callback with auth code
+ * 5. Exchange code for token via registry /auth/token endpoint
+ * 6. Return AuthToken
+ */
+export async function startAuthFlow(
+  registryUrl: string
+): Promise<AuthToken> {
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = generateCodeChallenge(codeVerifier);
+
+  return new Promise<AuthToken>((resolve, reject) => {
+    const server = http.createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url ?? '/', `http://localhost`);
+
+        if (url.pathname !== '/callback') {
+          res.writeHead(404);
+          res.end('Not found');
+          return;
+        }
+
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+
+        if (error) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end(
+            '<html><body><h2>Authentication failed</h2><p>You can close this window.</p></body></html>'
+          );
+          server.close();
+          reject(new Error(`Auth failed: ${error}`));
+          return;
+        }
+
+        if (!code) {
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end(
+            '<html><body><h2>Missing auth code</h2><p>You can close this window.</p></body></html>'
+          );
+          server.close();
+          reject(new Error('No authorization code received'));
+          return;
+        }
+
+        // Exchange code for token
+        const tokenResponse = await fetch(`${registryUrl}/auth/token`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            code,
+            code_verifier: codeVerifier,
+            redirect_uri: `http://localhost:${(server.address() as { port: number }).port}/callback`,
+          }),
+        });
+
+        if (!tokenResponse.ok) {
+          const body = await tokenResponse.text();
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end(
+            '<html><body><h2>Token exchange failed</h2><p>You can close this window.</p></body></html>'
+          );
+          server.close();
+          reject(
+            new Error(`Token exchange failed (${tokenResponse.status}): ${body}`)
+          );
+          return;
+        }
+
+        const tokenData = (await tokenResponse.json()) as AuthToken;
+
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(
+          '<html><body><h2>Authenticated!</h2><p>You can close this window and return to the terminal.</p></body></html>'
+        );
+        server.close();
+        resolve(tokenData);
+      } catch (err) {
+        server.close();
+        reject(err);
+      }
+    });
+
+    // Listen on random port
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address() as { port: number };
+      const redirectUri = `http://localhost:${addr.port}/callback`;
+      const authUrl = `${registryUrl}/auth/login?redirect_uri=${encodeURIComponent(redirectUri)}&code_challenge=${codeChallenge}&code_challenge_method=S256`;
+
+      console.log('Opening browser for authentication...');
+      openBrowser(authUrl);
+      console.log(`\nIf the browser doesn't open, visit:\n  ${authUrl}\n`);
+    });
+
+    // Timeout after 2 minutes
+    setTimeout(() => {
+      server.close();
+      reject(new Error('Authentication timed out after 2 minutes'));
+    }, 120_000);
+  });
+}
+
+/**
+ * Get a valid auth token:
+ * 1. Load from store
+ * 2. If expired or within 5 min buffer: try refresh
+ * 3. If refresh fails: throw with message to re-login
+ * 4. Return valid token
+ *
+ * Token values are NEVER written to stdout.
+ */
+export async function getAuthToken(): Promise<AuthToken> {
+  const token = await loadToken();
+
+  if (!token) {
+    throw new Error("Not logged in. Run 'hq login' to authenticate.");
+  }
+
+  if (!isTokenExpired(token)) {
+    return token;
+  }
+
+  // Attempt refresh
+  try {
+    const registryUrl = getRegistryUrl();
+    const refreshResponse = await fetch(`${registryUrl}/auth/refresh`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        clerk_session_token: token.clerk_session_token,
+      }),
+    });
+
+    if (refreshResponse.ok) {
+      const refreshedToken = (await refreshResponse.json()) as AuthToken;
+      await saveToken(refreshedToken);
+      return refreshedToken;
+    }
+  } catch {
+    // Refresh failed — fall through to error
+  }
+
+  throw new Error(
+    "Session expired. Run 'hq login' to re-authenticate."
+  );
+}