@indigoai-us/hq-cli 5.1.0

package/src/commands/cloud.ts

@@ -0,0 +1,300 @@
+/**
+ * hq sync commands — cloud sync management via API proxy
+ *
+ * All sync operations go through the hq-cloud API (authenticated with Clerk
+ * tokens from US-002). No AWS credentials or direct S3 access needed.
+ *
+ * Commands:
+ *   hq sync push    — Upload changed local files to cloud
+ *   hq sync pull    — Download changed cloud files to local
+ *   hq sync start   — Begin background auto-sync watcher
+ *   hq sync stop    — Halt the background watcher
+ *   hq sync status  — Show sync state, last sync time, file counts
+ */
+
+import { Command } from 'commander';
+import { fork } from 'child_process';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { findHqRoot } from '../utils/manifest.js';
+import { readCredentials, isExpired } from '../utils/credentials.js';
+import {
+  pushChanges,
+  pullChanges,
+  fullSync,
+  computeLocalManifest,
+  readSyncState,
+  writeSyncState,
+  getQuota,
+  type CloudSyncState,
+} from '../utils/sync.js';
+
+/**
+ * Verify that the user is authenticated before running sync commands.
+ * Throws if not logged in or token is expired.
+ */
+function requireAuth(): void {
+  const creds = readCredentials();
+  if (!creds) {
+    throw new Error('Not logged in. Run "hq auth login" first.');
+  }
+  if (isExpired(creds)) {
+    throw new Error('Session expired. Run "hq auth login" to re-authenticate.');
+  }
+}
+
+/**
+ * Check if a background sync process is actually running (not just recorded).
+ */
+function isProcessRunning(pid: number): boolean {
+  try {
+    // Sending signal 0 checks if process exists without killing it
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function registerCloudCommands(program: Command): void {
+  // ── hq sync push ────────────────────────────────────────────────────────
+
+  program
+    .command('push')
+    .description('Upload changed local files to cloud via API proxy')
+    .action(async () => {
+      try {
+        requireAuth();
+        const hqRoot = findHqRoot();
+
+        console.log(chalk.blue('Computing local manifest...'));
+        const manifest = computeLocalManifest(hqRoot);
+        console.log(chalk.dim(`  ${manifest.length} local files scanned`));
+
+        console.log(chalk.blue('Checking for changes...'));
+        const result = await pushChanges(hqRoot);
+
+        if (result.uploaded === 0 && result.errors.length === 0) {
+          console.log(chalk.green('Already up to date. No files to push.'));
+        } else {
+          console.log(chalk.green(`Pushed ${result.uploaded} file${result.uploaded !== 1 ? 's' : ''} to cloud.`));
+        }
+
+        if (result.errors.length > 0) {
+          console.log(chalk.yellow(`  ${result.errors.length} error${result.errors.length !== 1 ? 's' : ''}:`));
+          for (const err of result.errors.slice(0, 5)) {
+            console.log(chalk.red(`    - ${err}`));
+          }
+          if (result.errors.length > 5) {
+            console.log(chalk.dim(`    ... and ${result.errors.length - 5} more`));
+          }
+        }
+
+        // Update sync state
+        const state = readSyncState(hqRoot);
+        state.lastSync = new Date().toISOString();
+        state.fileCount = manifest.length;
+        state.errors = result.errors;
+        writeSyncState(hqRoot, state);
+      } catch (error) {
+        console.error(chalk.red('Push failed:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
+  // ── hq sync pull ────────────────────────────────────────────────────────
+
+  program
+    .command('pull')
+    .description('Download changed cloud files to local via API proxy')
+    .action(async () => {
+      try {
+        requireAuth();
+        const hqRoot = findHqRoot();
+
+        console.log(chalk.blue('Computing local manifest...'));
+        const manifest = computeLocalManifest(hqRoot);
+        console.log(chalk.dim(`  ${manifest.length} local files scanned`));
+
+        console.log(chalk.blue('Checking for changes...'));
+        const result = await pullChanges(hqRoot);
+
+        if (result.downloaded === 0 && result.errors.length === 0) {
+          console.log(chalk.green('Already up to date. No files to pull.'));
+        } else {
+          console.log(chalk.green(`Pulled ${result.downloaded} file${result.downloaded !== 1 ? 's' : ''} from cloud.`));
+        }
+
+        if (result.errors.length > 0) {
+          console.log(chalk.yellow(`  ${result.errors.length} error${result.errors.length !== 1 ? 's' : ''}:`));
+          for (const err of result.errors.slice(0, 5)) {
+            console.log(chalk.red(`    - ${err}`));
+          }
+          if (result.errors.length > 5) {
+            console.log(chalk.dim(`    ... and ${result.errors.length - 5} more`));
+          }
+        }
+
+        // Update sync state
+        const state = readSyncState(hqRoot);
+        state.lastSync = new Date().toISOString();
+        state.fileCount = manifest.length;
+        state.errors = result.errors;
+        writeSyncState(hqRoot, state);
+      } catch (error) {
+        console.error(chalk.red('Pull failed:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
+  // ── hq sync start ──────────────────────────────────────────────────────
+
+  program
+    .command('start')
+    .description('Start background auto-sync watcher (polls every 30s)')
+    .option('-i, --interval <seconds>', 'Polling interval in seconds', '30')
+    .action(async (opts: { interval: string }) => {
+      try {
+        requireAuth();
+        const hqRoot = findHqRoot();
+        const intervalSec = parseInt(opts.interval, 10);
+
+        if (isNaN(intervalSec) || intervalSec < 5) {
+          throw new Error('Interval must be at least 5 seconds.');
+        }
+
+        // Check if already running
+        const existingState = readSyncState(hqRoot);
+        if (existingState.running && existingState.pid && isProcessRunning(existingState.pid)) {
+          console.log(chalk.yellow(`Sync watcher already running (PID ${existingState.pid}).`));
+          console.log('Use "hq sync stop" to stop it first.');
+          return;
+        }
+
+        // Fork a background worker process
+        // The worker script path is relative to the compiled output
+        const thisFile = fileURLToPath(import.meta.url);
+        const workerScript = path.join(path.dirname(thisFile), '..', 'sync-worker.js');
+
+        const child = fork(workerScript, [hqRoot, String(intervalSec * 1000)], {
+          detached: true,
+          stdio: 'ignore',
+        });
+
+        if (!child.pid) {
+          throw new Error('Failed to start background sync process.');
+        }
+
+        // Allow the parent to exit without waiting for the child
+        child.unref();
+
+        // Record state
+        const state: CloudSyncState = {
+          running: true,
+          pid: child.pid,
+          lastSync: existingState.lastSync,
+          fileCount: existingState.fileCount,
+          errors: [],
+        };
+        writeSyncState(hqRoot, state);
+
+        console.log(chalk.green(`Sync watcher started (PID ${child.pid}, interval: ${intervalSec}s).`));
+        console.log('Use "hq sync status" to check, "hq sync stop" to halt.');
+      } catch (error) {
+        console.error(chalk.red('Start failed:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
+  // ── hq sync stop ───────────────────────────────────────────────────────
+
+  program
+    .command('stop')
+    .description('Stop the background sync watcher')
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const state = readSyncState(hqRoot);
+
+        if (!state.running || !state.pid) {
+          console.log(chalk.yellow('No sync watcher is running.'));
+          return;
+        }
+
+        if (isProcessRunning(state.pid)) {
+          try {
+            process.kill(state.pid, 'SIGTERM');
+            console.log(chalk.green(`Sync watcher stopped (PID ${state.pid}).`));
+          } catch {
+            console.log(chalk.yellow(`Could not stop process ${state.pid} — it may have already exited.`));
+          }
+        } else {
+          console.log(chalk.dim(`Sync watcher process ${state.pid} is no longer running. Cleaning up state.`));
+        }
+
+        // Update state
+        state.running = false;
+        state.pid = undefined;
+        writeSyncState(hqRoot, state);
+      } catch (error) {
+        console.error(chalk.red('Stop failed:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
+  // ── hq sync status ─────────────────────────────────────────────────────
+
+  program
+    .command('status')
+    .description('Show sync state, last sync time, and file counts')
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const state = readSyncState(hqRoot);
+
+        // Check if the recorded PID is actually alive
+        const actuallyRunning = state.running && state.pid
+          ? isProcessRunning(state.pid)
+          : false;
+
+        if (state.running && !actuallyRunning) {
+          // Stale state — clean it up
+          state.running = false;
+          state.pid = undefined;
+          writeSyncState(hqRoot, state);
+        }
+
+        console.log(chalk.bold('HQ Cloud Sync Status'));
+        console.log();
+        console.log(`  Watcher:    ${actuallyRunning ? chalk.green('running') + ` (PID ${state.pid})` : chalk.dim('stopped')}`);
+        console.log(`  Last sync:  ${state.lastSync ? state.lastSync : chalk.dim('never')}`);
+        console.log(`  Files:      ${state.fileCount != null ? `${state.fileCount} tracked` : chalk.dim('unknown')}`);
+        console.log(`  HQ root:    ${hqRoot}`);
+
+        if (state.errors.length > 0) {
+          console.log(`  Errors:     ${chalk.yellow(String(state.errors.length))}`);
+          for (const err of state.errors.slice(0, 5)) {
+            console.log(chalk.red(`    - ${err}`));
+          }
+        }
+
+        // Try to fetch quota info (non-fatal if it fails)
+        try {
+          requireAuth();
+          const quota = await getQuota();
+          console.log();
+          console.log(chalk.bold('  Storage Quota'));
+          const usedMB = (quota.used / (1024 * 1024)).toFixed(1);
+          const limitMB = (quota.limit / (1024 * 1024)).toFixed(1);
+          const pctColor = quota.percentage > 90 ? chalk.red : quota.percentage > 70 ? chalk.yellow : chalk.green;
+          console.log(`    Used:     ${usedMB} MB / ${limitMB} MB (${pctColor(quota.percentage + '%')})`);
+        } catch {
+          // Quota info is optional — skip silently
+        }
+      } catch (error) {
+        console.error(chalk.red('Status check failed:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/initial-upload.ts

@@ -0,0 +1,263 @@
+/**
+ * Initial HQ file upload for first-time cloud setup.
+ *
+ * After Clerk auth and Claude token setup, this command uploads the user's
+ * local HQ files to the cloud so the first session has access to the workspace.
+ *
+ * Respects the same ignore rules as sync (shouldIgnore from utils/sync.ts):
+ *   - .git/, node_modules/, .claude/, dist/, cdk.out/, etc.
+ *   - .log files, .env files, .DS_Store, Thumbs.db
+ *
+ * Exports `runInitialUpload` so it can be called programmatically from the
+ * create-hq installer (US-004) or other commands.
+ */
+
+import * as readline from 'readline';
+import chalk from 'chalk';
+import { apiRequest } from '../utils/api-client.js';
+import {
+  walkDir,
+  uploadFile,
+  computeLocalManifest,
+  readSyncState,
+  writeSyncState,
+} from '../utils/sync.js';
+
+/** Response shape from GET /api/files/list */
+export interface RemoteFileList {
+  files: string[];
+}
+
+/** Result returned by runInitialUpload */
+export interface InitialUploadResult {
+  /** Total local files discovered (after ignore filtering) */
+  totalFiles: number;
+  /** Number of files successfully uploaded */
+  uploaded: number;
+  /** Number of files that failed to upload */
+  failed: number;
+  /** Error messages for failed uploads */
+  errors: string[];
+  /** Whether the user chose to skip (remote had files and user declined) */
+  skipped: boolean;
+}
+
+/**
+ * Prompt the user with a yes/no question on stdin.
+ * Returns true for 'y'/'yes', false for 'n'/'no'.
+ * Defaults to defaultAnswer if user just presses Enter.
+ */
+export function promptYesNo(
+  question: string,
+  defaultAnswer: boolean = true,
+): Promise<boolean> {
+  const hint = defaultAnswer ? '[Y/n]' : '[y/N]';
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`${question} ${hint} `, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      if (trimmed === '') {
+        resolve(defaultAnswer);
+      } else {
+        resolve(trimmed === 'y' || trimmed === 'yes');
+      }
+    });
+  });
+}
+
+/**
+ * Prompt the user to choose between merge and replace.
+ * Returns 'merge' or 'replace'.
+ */
+export function promptMergeOrReplace(): Promise<'merge' | 'replace'> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question('Choose [m]erge or [r]eplace: ', (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      if (trimmed === 'r' || trimmed === 'replace') {
+        resolve('replace');
+      } else {
+        resolve('merge');
+      }
+    });
+  });
+}
+
+/**
+ * Delete all remote files (used when user chooses 'replace').
+ */
+async function deleteRemoteFiles(): Promise<void> {
+  const resp = await apiRequest('DELETE', '/api/files/all');
+  if (!resp.ok) {
+    throw new Error(`Failed to clear remote files: ${resp.error ?? `HTTP ${resp.status}`}`);
+  }
+}
+
+/**
+ * Write a progress line that overwrites the previous line.
+ * Falls back to newline output if stdout is not a TTY (e.g., in tests or pipes).
+ */
+export function writeProgress(current: number, total: number): void {
+  const pct = total > 0 ? Math.round((current / total) * 100) : 0;
+  const line = `Uploading: ${current}/${total} files (${pct}%)`;
+
+  if (process.stdout.isTTY) {
+    process.stdout.write(`\r${line}`);
+  }
+}
+
+/**
+ * Run the initial HQ file upload.
+ *
+ * This is the core function that:
+ * 1. Lists remote files via GET /api/files/list
+ * 2. If remote has files, asks user to merge or replace
+ * 3. Walks local files (respecting ignore rules)
+ * 4. Uploads all files with progress indicator
+ * 5. Updates sync state
+ *
+ * @param hqRoot - Absolute path to the HQ root directory
+ * @param options - Optional overrides (for testing / programmatic use)
+ * @returns Upload result with counts and any errors
+ */
+export async function runInitialUpload(
+  hqRoot: string,
+  options?: {
+    /** Override the merge/replace prompt (for non-interactive use) */
+    onConflict?: 'merge' | 'replace' | 'skip';
+    /** Suppress console output */
+    quiet?: boolean;
+  },
+): Promise<InitialUploadResult> {
+  const quiet = options?.quiet ?? false;
+
+  const log = (msg: string) => {
+    if (!quiet) console.log(msg);
+  };
+
+  // 1. Check remote state
+  log(chalk.blue('Checking cloud storage...'));
+
+  let remoteFiles: string[] = [];
+  try {
+    const resp = await apiRequest<RemoteFileList>('GET', '/api/files/list');
+    if (resp.ok && resp.data) {
+      remoteFiles = resp.data.files ?? [];
+    }
+  } catch {
+    // If the endpoint doesn't exist yet or fails, treat as empty
+  }
+
+  // 2. Handle existing remote files
+  if (remoteFiles.length > 0) {
+    log('');
+    log(chalk.yellow(`Cloud storage already has ${remoteFiles.length} file${remoteFiles.length !== 1 ? 's' : ''}.`));
+
+    let action: 'merge' | 'replace' | 'skip';
+
+    if (options?.onConflict) {
+      action = options.onConflict;
+    } else {
+      log('  merge  — Upload local files, keeping existing remote files');
+      log('  replace — Delete all remote files first, then upload');
+      log('');
+      action = await promptMergeOrReplace();
+    }
+
+    if (action === 'skip') {
+      log(chalk.dim('Skipping upload.'));
+      return { totalFiles: 0, uploaded: 0, failed: 0, errors: [], skipped: true };
+    }
+
+    if (action === 'replace') {
+      log(chalk.dim('Clearing remote files...'));
+      await deleteRemoteFiles();
+      log(chalk.dim('Remote files cleared.'));
+    } else {
+      log(chalk.dim('Merging: existing remote files will be preserved.'));
+    }
+  }
+
+  // 3. Walk local files
+  log(chalk.blue('Scanning local HQ files...'));
+  const localFiles = walkDir(hqRoot);
+
+  if (localFiles.length === 0) {
+    log(chalk.yellow('No files found to upload.'));
+    return { totalFiles: 0, uploaded: 0, failed: 0, errors: [], skipped: false };
+  }
+
+  log(chalk.dim(`  Found ${localFiles.length} file${localFiles.length !== 1 ? 's' : ''} to upload`));
+  log('');
+
+  // 4. Upload with progress
+  const errors: string[] = [];
+  let uploaded = 0;
+
+  for (let i = 0; i < localFiles.length; i++) {
+    const filePath = localFiles[i];
+
+    if (!quiet) {
+      writeProgress(i + 1, localFiles.length);
+    }
+
+    try {
+      await uploadFile(filePath, hqRoot);
+      uploaded++;
+    } catch (err) {
+      errors.push(
+        `${filePath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  // Clear the progress line
+  if (!quiet && process.stdout.isTTY) {
+    process.stdout.write('\r' + ' '.repeat(60) + '\r');
+  }
+
+  // 5. Report results
+  if (errors.length === 0) {
+    log(chalk.green(`Uploaded ${uploaded}/${localFiles.length} files successfully.`));
+  } else {
+    log(chalk.green(`Uploaded ${uploaded}/${localFiles.length} files.`));
+    log(chalk.yellow(`  ${errors.length} error${errors.length !== 1 ? 's' : ''}:`));
+    for (const err of errors.slice(0, 5)) {
+      log(chalk.red(`    - ${err}`));
+    }
+    if (errors.length > 5) {
+      log(chalk.dim(`    ... and ${errors.length - 5} more`));
+    }
+  }
+
+  // 6. Update sync state
+  const manifest = computeLocalManifest(hqRoot);
+  const state = readSyncState(hqRoot);
+  state.lastSync = new Date().toISOString();
+  state.fileCount = manifest.length;
+  state.errors = errors;
+  writeSyncState(hqRoot, state);
+
+  if (errors.length === 0) {
+    log('');
+    log(chalk.green('Sync status: in sync'));
+  }
+
+  return {
+    totalFiles: localFiles.length,
+    uploaded,
+    failed: errors.length,
+    errors,
+    skipped: false,
+  };
+}

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