@indigoai-us/hq-cli 5.1.0

package/src/utils/api-client.ts

@@ -0,0 +1,111 @@
+/**
+ * API client for hq-cloud.
+ * Reads stored credentials and attaches Authorization header to all requests.
+ *
+ * Base URL resolution order:
+ * 1. HQ_CLOUD_API_URL environment variable
+ * 2. ~/.hq/config.json "apiUrl" field
+ * 3. Default production URL
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { readCredentials } from './credentials.js';
+
+/** Default API base URL (production) */
+const DEFAULT_API_URL = 'https://api.hq.indigoai.com';
+
+/** Path to optional config file */
+const CONFIG_PATH = path.join(os.homedir(), '.hq', 'config.json');
+
+/**
+ * Resolve the hq-cloud API base URL.
+ */
+export function getApiUrl(): string {
+  // 1. Environment variable takes precedence
+  if (process.env['HQ_CLOUD_API_URL']) {
+    return process.env['HQ_CLOUD_API_URL'].replace(/\/+$/, '');
+  }
+
+  // 2. Config file
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const raw = fs.readFileSync(CONFIG_PATH, 'utf-8');
+      const config = JSON.parse(raw) as { apiUrl?: string };
+      if (config.apiUrl) {
+        return config.apiUrl.replace(/\/+$/, '');
+      }
+    }
+  } catch {
+    // Ignore config read errors
+  }
+
+  // 3. Default
+  return DEFAULT_API_URL;
+}
+
+/** Standard response shape from the API */
+export interface ApiResponse<T = unknown> {
+  ok: boolean;
+  status: number;
+  data?: T;
+  error?: string;
+}
+
+/**
+ * Make an authenticated request to the hq-cloud API.
+ * Throws if not logged in. Returns parsed JSON response.
+ */
+export async function apiRequest<T = unknown>(
+  method: string,
+  urlPath: string,
+  body?: unknown,
+): Promise<ApiResponse<T>> {
+  const creds = readCredentials();
+  if (!creds) {
+    throw new Error('Not logged in. Run "hq auth login" first.');
+  }
+
+  const baseUrl = getApiUrl();
+  const url = `${baseUrl}${urlPath.startsWith('/') ? urlPath : '/' + urlPath}`;
+
+  const headers: Record<string, string> = {
+    'Authorization': `Bearer ${creds.token}`,
+    'Content-Type': 'application/json',
+  };
+
+  const fetchOptions: RequestInit = {
+    method,
+    headers,
+  };
+
+  if (body !== undefined && method !== 'GET') {
+    fetchOptions.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(url, fetchOptions);
+
+  let data: T | undefined;
+  try {
+    data = await response.json() as T;
+  } catch {
+    // Response may not be JSON
+  }
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      status: response.status,
+      error: (data as Record<string, string> | undefined)?.message
+        ?? (data as Record<string, string> | undefined)?.error
+        ?? `HTTP ${response.status}`,
+    };
+  }
+
+  return {
+    ok: true,
+    status: response.status,
+    data,
+  };
+}

package/src/utils/credentials.ts

@@ -0,0 +1,124 @@
+/**
+ * Credential storage for HQ CLI authentication.
+ * Stores Clerk auth tokens in ~/.hq/credentials.json.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/** Stored credential shape */
+export interface HqCredentials {
+  /** Clerk session token (JWT) */
+  token: string;
+  /** Clerk user ID */
+  userId: string;
+  /** User's email (for display) */
+  email?: string;
+  /** When the token was stored (ISO string) */
+  storedAt: string;
+  /** When the token expires (ISO string, if known) */
+  expiresAt?: string;
+}
+
+/**
+ * Override for the config directory base path.
+ * Set via HQ_CONFIG_HOME env var or _setConfigHome (for testing).
+ * When null, defaults to os.homedir().
+ */
+let configHomeOverride: string | null = null;
+
+/**
+ * Set the base directory for config files. Intended for testing only.
+ */
+export function _setConfigHome(dir: string | null): void {
+  configHomeOverride = dir;
+}
+
+/**
+ * Get the ~/.hq config directory path.
+ * Respects HQ_CONFIG_HOME env var, _setConfigHome override, or defaults to ~/.hq.
+ */
+function getConfigDir(): string {
+  const base = configHomeOverride
+    ?? process.env['HQ_CONFIG_HOME']
+    ?? os.homedir();
+  return path.join(base, '.hq');
+}
+
+/**
+ * Get the credentials file path.
+ */
+function getCredentialsFilePath(): string {
+  return path.join(getConfigDir(), 'credentials.json');
+}
+
+/**
+ * Ensure the config directory exists with restricted permissions.
+ */
+function ensureConfigDir(): void {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Read stored credentials. Returns null if not logged in or file is missing/corrupt.
+ */
+export function readCredentials(): HqCredentials | null {
+  try {
+    const credPath = getCredentialsFilePath();
+    if (!fs.existsSync(credPath)) {
+      return null;
+    }
+    const raw = fs.readFileSync(credPath, 'utf-8');
+    const creds = JSON.parse(raw) as HqCredentials;
+    if (!creds.token || !creds.userId) {
+      return null;
+    }
+    return creds;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write credentials to disk. Creates ~/.hq if needed.
+ * File permissions are set to owner-only (0o600).
+ */
+export function writeCredentials(creds: HqCredentials): void {
+  ensureConfigDir();
+  const content = JSON.stringify(creds, null, 2);
+  fs.writeFileSync(getCredentialsFilePath(), content, { mode: 0o600 });
+}
+
+/**
+ * Clear stored credentials (logout).
+ * Returns true if credentials were removed, false if none existed.
+ */
+export function clearCredentials(): boolean {
+  const credPath = getCredentialsFilePath();
+  if (!fs.existsSync(credPath)) {
+    return false;
+  }
+  fs.unlinkSync(credPath);
+  return true;
+}
+
+/**
+ * Get the credentials file path (for display/debugging).
+ */
+export function getCredentialsPath(): string {
+  return getCredentialsFilePath();
+}
+
+/**
+ * Check if credentials are expired (if expiresAt is set).
+ */
+export function isExpired(creds: HqCredentials): boolean {
+  if (!creds.expiresAt) {
+    return false;
+  }
+  return new Date(creds.expiresAt) <= new Date();
+}

package/src/utils/git.ts

@@ -0,0 +1,74 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { simpleGit, type 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/manifest.ts

@@ -0,0 +1,111 @@
+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 (true) {
+    if (fs.existsSync(path.join(dir, '.claude')) || fs.existsSync(path.join(dir, 'workers'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // Reached filesystem root (works on Windows and Unix)
+    dir = parent;
+  }
+  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@');
+}