@indigoai-us/hq-cli 5.1.0

package/src/commands/sync.ts

@@ -0,0 +1,149 @@
+/**
+ * hq modules sync command (US-004)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import {
+  findHqRoot,
+  readManifest,
+  readLock,
+  writeLock,
+  getModulesDir,
+} from '../utils/manifest.js';
+import {
+  cloneRepo,
+  fetchRepo,
+  pullRepo,
+  getCurrentCommit,
+  checkoutCommit,
+  isRepo,
+  ensureGitignore,
+} from '../utils/git.js';
+import { linkSync } from '../strategies/link.js';
+import { mergeSync } from '../strategies/merge.js';
+import type { ModuleDefinition, ModuleLock, SyncResult } from '../types.js';
+
+async function syncModule(
+  module: ModuleDefinition,
+  moduleDir: string,
+  hqRoot: string,
+  locked: boolean,
+  lockData: ModuleLock | null
+): Promise<SyncResult> {
+  const repoExists = await isRepo(moduleDir);
+
+  // Clone or fetch
+  if (!repoExists) {
+    console.log(`  Cloning ${module.name}...`);
+    await cloneRepo(module.repo, moduleDir, module.branch);
+  } else {
+    console.log(`  Fetching ${module.name}...`);
+    await fetchRepo(moduleDir);
+
+    // Checkout locked commit if --locked
+    if (locked && lockData?.locked[module.name]) {
+      await checkoutCommit(moduleDir, lockData.locked[module.name]);
+    } else {
+      await pullRepo(moduleDir);
+    }
+  }
+
+  // Apply sync strategy
+  console.log(`  Syncing with strategy: ${module.strategy}`);
+  let result: SyncResult;
+
+  switch (module.strategy) {
+    case 'link':
+      result = await linkSync(module, moduleDir, hqRoot);
+      break;
+    case 'merge':
+    case 'copy':
+      result = await mergeSync(module, moduleDir, hqRoot);
+      break;
+    default:
+      result = {
+        module: module.name,
+        success: false,
+        action: 'skipped',
+        message: `Unknown strategy: ${module.strategy}`,
+      };
+  }
+
+  return result;
+}
+
+export function registerSyncCommand(program: Command): void {
+  program
+    .command('sync')
+    .description('Sync all modules from manifest')
+    .option('--locked', 'Use locked versions from modules.lock')
+    .action(async (options: { locked?: boolean }) => {
+      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);
+        if (!fs.existsSync(modulesDir)) {
+          fs.mkdirSync(modulesDir, { recursive: true });
+        }
+
+        // Ensure modules/ is gitignored
+        ensureGitignore(hqRoot, 'modules/');
+
+        const lockData = options.locked ? readLock(hqRoot) : null;
+        const results: SyncResult[] = [];
+        const newLock: ModuleLock = { version: '1', locked: {} };
+
+        console.log(`Syncing ${manifest.modules.length} module(s)...\n`);
+
+        for (const module of manifest.modules) {
+          console.log(`[${module.name}]`);
+          const moduleDir = path.join(modulesDir, module.name);
+
+          const result = await syncModule(
+            module,
+            moduleDir,
+            hqRoot,
+            options.locked ?? false,
+            lockData
+          );
+          results.push(result);
+
+          // Record commit for lock file
+          if (result.success) {
+            const commit = await getCurrentCommit(moduleDir);
+            newLock.locked[module.name] = commit;
+          }
+
+          const status = result.success ? '✓' : '✗';
+          const msg = result.message || `${result.filesChanged ?? 0} files`;
+          console.log(`  ${status} ${result.action}: ${msg}\n`);
+        }
+
+        // Write lock file (US-008)
+        if (!options.locked) {
+          writeLock(hqRoot, newLock);
+        }
+
+        // Summary
+        const success = results.filter(r => r.success).length;
+        const failed = results.filter(r => !r.success).length;
+        console.log(`Done: ${success} succeeded, ${failed} failed`);
+
+        if (failed > 0) {
+          process.exit(1);
+        }
+
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/update.ts

@@ -0,0 +1,71 @@
+/**
+ * hq modules update command (US-008)
+ * Updates lock for specific module
+ */
+
+import * as path from 'path';
+import { Command } from 'commander';
+import { findHqRoot, readManifest, readLock, writeLock, getModulesDir } from '../utils/manifest.js';
+import { fetchRepo, pullRepo, getCurrentCommit, isRepo } from '../utils/git.js';
+
+export function registerUpdateCommand(program: Command): void {
+  program
+    .command('update [module-name]')
+    .description('Update lock for a specific module (or all if no name given)')
+    .action(async (moduleName?: string) => {
+      try {
+        const hqRoot = findHqRoot();
+        const manifest = readManifest(hqRoot);
+
+        if (!manifest || manifest.modules.length === 0) {
+          console.log('No modules in manifest.');
+          return;
+        }
+
+        let lock = readLock(hqRoot);
+        if (!lock) {
+          lock = { version: '1', locked: {} };
+        }
+
+        const modulesDir = getModulesDir(hqRoot);
+        const modulesToUpdate = moduleName
+          ? manifest.modules.filter(m => m.name === moduleName)
+          : manifest.modules;
+
+        if (moduleName && modulesToUpdate.length === 0) {
+          console.error(`Module "${moduleName}" not found in manifest.`);
+          process.exit(1);
+        }
+
+        for (const module of modulesToUpdate) {
+          const moduleDir = path.join(modulesDir, module.name);
+
+          if (!await isRepo(moduleDir)) {
+            console.log(`  ${module.name}: not installed, skipping`);
+            continue;
+          }
+
+          console.log(`  ${module.name}: fetching...`);
+          await fetchRepo(moduleDir);
+          await pullRepo(moduleDir);
+
+          const commit = await getCurrentCommit(moduleDir);
+          const oldCommit = lock.locked[module.name];
+          lock.locked[module.name] = commit;
+
+          if (oldCommit === commit) {
+            console.log(`  ${module.name}: already up to date @ ${commit.slice(0, 7)}`);
+          } else {
+            console.log(`  ${module.name}: updated ${oldCommit?.slice(0, 7) || 'none'} -> ${commit.slice(0, 7)}`);
+          }
+        }
+
+        writeLock(hqRoot, lock);
+        console.log('\nLock file updated.');
+
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/hq-cloud.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type declarations for @hq-cloud/file-sync (legacy package reference).
+ * cloud.ts still imports from this package via dynamic import().
+ * Will be removed when cloud.ts is rewritten for US-005 (API proxy mode).
+ */
+declare module '@hq-cloud/file-sync' {
+  export function initSync(hqRoot: string): Promise<void>;
+  export function startDaemon(hqRoot: string): Promise<void>;
+  export function stopDaemon(hqRoot: string): Promise<void>;
+  export function getStatus(hqRoot: string): Promise<{
+    running: boolean;
+    lastSync: string | null;
+    fileCount: number;
+    bucket: string | null;
+    errors: string[];
+  }>;
+  export function pushAll(hqRoot: string): Promise<{ filesUploaded: number }>;
+  export function pullAll(hqRoot: string): Promise<{ filesDownloaded: number }>;
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * HQ CLI - Module 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 { registerAuthCommand } from "./commands/auth.js";
+import { registerCloudSetupCommand } from "./commands/cloud-setup.js";
+
+const program = new Command();
+
+program
+  .name("hq")
+  .description("HQ management CLI — modules and cloud sync")
+  .version("5.1.0");
+
+// Module management subcommand group
+const modulesCmd = program
+  .command("modules")
+  .description("Module management commands");
+
+registerAddCommand(modulesCmd);
+registerSyncCommand(modulesCmd);
+registerListCommand(modulesCmd);
+registerUpdateCommand(modulesCmd);
+
+// Cloud sync subcommand group
+const syncCmd = program
+  .command("sync")
+  .description("Cloud sync commands — sync HQ files via API proxy");
+
+registerCloudCommands(syncCmd);
+
+// Authentication commands (hq auth login|logout|status)
+registerAuthCommand(program);
+
+// Cloud session management (hq cloud setup-token|status)
+registerCloudSetupCommand(program);
+
+program.parse();

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).replace(/\\/g, '/');
+      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).replace(/\\/g, '/');
+      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/sync-worker.ts

@@ -0,0 +1,82 @@
+/**
+ * Background sync worker for "hq sync start".
+ *
+ * Forked as a detached child process. Polls for changes at a configurable
+ * interval and runs a full bidirectional sync each cycle.
+ *
+ * Usage (internal — called by cloud.ts):
+ *   node sync-worker.js <hqRoot> <intervalMs>
+ */
+
+import { fullSync, readSyncState, writeSyncState, computeLocalManifest } from './utils/sync.js';
+
+const hqRoot = process.argv[2];
+const intervalMs = parseInt(process.argv[3] ?? '30000', 10);
+
+if (!hqRoot) {
+  process.exit(1);
+}
+
+/** Run one sync cycle. */
+async function syncCycle(): Promise<void> {
+  try {
+    const result = await fullSync(hqRoot);
+
+    // Update state
+    const manifest = computeLocalManifest(hqRoot);
+    const state = readSyncState(hqRoot);
+    state.running = true;
+    state.pid = process.pid;
+    state.lastSync = new Date().toISOString();
+    state.fileCount = manifest.length;
+    state.errors = result.errors;
+    writeSyncState(hqRoot, state);
+  } catch {
+    // Log errors to state, but keep running
+    try {
+      const state = readSyncState(hqRoot);
+      state.errors = ['Sync cycle failed — will retry next interval'];
+      writeSyncState(hqRoot, state);
+    } catch {
+      // Can't even write state — just continue
+    }
+  }
+}
+
+/** Main loop. */
+async function run(): Promise<void> {
+  // Handle graceful shutdown
+  process.on('SIGTERM', () => {
+    try {
+      const state = readSyncState(hqRoot);
+      state.running = false;
+      state.pid = undefined;
+      writeSyncState(hqRoot, state);
+    } catch {
+      // Best-effort cleanup
+    }
+    process.exit(0);
+  });
+
+  process.on('SIGINT', () => {
+    try {
+      const state = readSyncState(hqRoot);
+      state.running = false;
+      state.pid = undefined;
+      writeSyncState(hqRoot, state);
+    } catch {
+      // Best-effort cleanup
+    }
+    process.exit(0);
+  });
+
+  // Run first sync immediately
+  await syncCycle();
+
+  // Then poll at the configured interval
+  setInterval(() => {
+    void syncCycle();
+  }, intervalMs);
+}
+
+void run();

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