@indigoai-us/hq-cli 5.3.0 → 5.4.0

package/dist/utils/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Registry YAML helpers — read/write packages/registry.yaml (US-005)
+ */
+export interface RegistryEntry {
+    name: string;
+    slug: string;
+    version: string;
+    source: string;
+    license_key?: string;
+    scope?: string;
+    installed_at: string;
+    updated_at: string;
+}
+/**
+ * Read all entries from packages/registry.yaml.
+ * Returns an empty array if the file does not exist.
+ */
+export declare function readRegistry(hqRoot: string): RegistryEntry[];
+/**
+ * Write the full registry back to packages/registry.yaml.
+ */
+export declare function writeRegistry(hqRoot: string, entries: RegistryEntry[]): void;
+/**
+ * Add or update an entry in packages/registry.yaml.
+ * If an entry with the same slug exists, it is replaced.
+ */
+export declare function addToRegistry(hqRoot: string, entry: RegistryEntry): void;
+/**
+ * Remove an entry by slug from packages/registry.yaml.
+ * No-op if the slug is not found.
+ */
+export declare function removeFromRegistry(hqRoot: string, slug: string): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/utils/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/utils/registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAQ5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,EAAE,GACvB,IAAI,CAWN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,GACnB,IAAI,CASN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,IAAI,CAGN"}

package/dist/utils/registry.js

@@ -0,0 +1,58 @@
+/**
+ * Registry YAML helpers — read/write packages/registry.yaml (US-005)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+function registryPath(hqRoot) {
+    return path.resolve(hqRoot, 'packages', 'registry.yaml');
+}
+/**
+ * Read all entries from packages/registry.yaml.
+ * Returns an empty array if the file does not exist.
+ */
+export function readRegistry(hqRoot) {
+    const filePath = registryPath(hqRoot);
+    if (!fs.existsSync(filePath)) {
+        return [];
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const parsed = yaml.load(content);
+    return parsed?.packages ?? [];
+}
+/**
+ * Write the full registry back to packages/registry.yaml.
+ */
+export function writeRegistry(hqRoot, entries) {
+    const filePath = registryPath(hqRoot);
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const content = yaml.dump({ packages: entries }, { lineWidth: 120, noRefs: true });
+    fs.writeFileSync(filePath, content, 'utf-8');
+}
+/**
+ * Add or update an entry in packages/registry.yaml.
+ * If an entry with the same slug exists, it is replaced.
+ */
+export function addToRegistry(hqRoot, entry) {
+    const entries = readRegistry(hqRoot);
+    const idx = entries.findIndex((e) => e.slug === entry.slug);
+    if (idx >= 0) {
+        entries[idx] = entry;
+    }
+    else {
+        entries.push(entry);
+    }
+    writeRegistry(hqRoot, entries);
+}
+/**
+ * Remove an entry by slug from packages/registry.yaml.
+ * No-op if the slug is not found.
+ */
+export function removeFromRegistry(hqRoot, slug) {
+    const entries = readRegistry(hqRoot).filter((e) => e.slug !== slug);
+    writeRegistry(hqRoot, entries);
+}
+//# sourceMappingURL=registry.js.map

package/dist/utils/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/utils/registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAiBhC,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAwB,CAAC;IACzD,OAAO,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,OAAwB;IAExB,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CACvB,EAAE,QAAQ,EAAE,OAAO,EAAE,EACrB,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CACjC,CAAC;IACF,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,KAAoB;IAEpB,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5D,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,IAAY;IAEZ,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACpE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/utils/token-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Auth token store — manages ~/.hq/auth.json with secure file permissions (US-004)
+ */
+export interface AuthToken {
+    clerk_session_token: string;
+    user_id: string;
+    email: string;
+    expires_at: string;
+}
+/**
+ * Save auth token to ~/.hq/auth.json with 0600 permissions.
+ * Token content is never logged or written to stdout.
+ */
+export declare function saveToken(token: AuthToken): Promise<void>;
+/**
+ * Load auth token from ~/.hq/auth.json.
+ * Returns null if file is missing, unreadable, or contains invalid JSON.
+ */
+export declare function loadToken(): Promise<AuthToken | null>;
+/**
+ * Delete the auth token file.
+ */
+export declare function clearToken(): Promise<void>;
+/**
+ * Check if a token is expired or within 5 minutes of expiry.
+ */
+export declare function isTokenExpired(token: AuthToken): boolean;
+//# sourceMappingURL=token-store.d.ts.map

package/dist/utils/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../src/utils/token-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,SAAS;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAWD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/D;AAED;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAsB3D;AAED;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAQhD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAIxD"}

package/dist/utils/token-store.js

@@ -0,0 +1,68 @@
+/**
+ * Auth token store — manages ~/.hq/auth.json with secure file permissions (US-004)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const HQ_DIR = path.join(os.homedir(), '.hq');
+const AUTH_FILE = path.join(HQ_DIR, 'auth.json');
+function ensureHqDir() {
+    if (!fs.existsSync(HQ_DIR)) {
+        fs.mkdirSync(HQ_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Save auth token to ~/.hq/auth.json with 0600 permissions.
+ * Token content is never logged or written to stdout.
+ */
+export async function saveToken(token) {
+    ensureHqDir();
+    const content = JSON.stringify(token, null, 2);
+    fs.writeFileSync(AUTH_FILE, content, { mode: 0o600 });
+}
+/**
+ * Load auth token from ~/.hq/auth.json.
+ * Returns null if file is missing, unreadable, or contains invalid JSON.
+ */
+export async function loadToken() {
+    try {
+        if (!fs.existsSync(AUTH_FILE)) {
+            return null;
+        }
+        const content = fs.readFileSync(AUTH_FILE, 'utf-8');
+        const parsed = JSON.parse(content);
+        // Validate required fields
+        if (typeof parsed.clerk_session_token !== 'string' ||
+            typeof parsed.user_id !== 'string' ||
+            typeof parsed.email !== 'string' ||
+            typeof parsed.expires_at !== 'string') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete the auth token file.
+ */
+export async function clearToken() {
+    try {
+        if (fs.existsSync(AUTH_FILE)) {
+            fs.unlinkSync(AUTH_FILE);
+        }
+    }
+    catch {
+        // Ignore errors — file may already be gone
+    }
+}
+/**
+ * Check if a token is expired or within 5 minutes of expiry.
+ */
+export function isTokenExpired(token) {
+    const expiresAt = new Date(token.expires_at).getTime();
+    const bufferMs = 5 * 60 * 1000; // 5 minutes
+    return Date.now() >= expiresAt - bufferMs;
+}
+//# sourceMappingURL=token-store.js.map

package/dist/utils/token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.js","sourceRoot":"","sources":["../../src/utils/token-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AASzB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;AAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEjD,SAAS,WAAW;IAClB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAgB;IAC9C,WAAW,EAAE,CAAC;IACd,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/C,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEnC,2BAA2B;QAC3B,IACE,OAAO,MAAM,CAAC,mBAAmB,KAAK,QAAQ;YAC9C,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAClC,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;YAChC,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,EACrC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,MAAmB,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2CAA2C;IAC7C,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;IACvD,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;IAC5C,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,SAAS,GAAG,QAAQ,CAAC;AAC5C,CAAC"}

package/package.json

@@ -1,45 +1,35 @@
-{
-  "name": "@indigoai-us/hq-cli",
-  "version": "5.3.0",
-  "description": "HQ management CLI — modules and cloud sync",
-  "main": "dist/index.js",
-  "bin": {
-    "hq": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "js-yaml": "^4.1.0",
-    "simple-git": "^3.27.0"
-  },
-  "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0",
-    "vitest": "^1.2.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/indigoai-us/hq.git",
-    "directory": "packages/hq-cli"
-  },
-  "files": [
-    "dist"
-  ],
-  "keywords": [
-    "hq",
-    "ai",
-    "modules",
-    "sync",
-    "cloud"
-  ],
-  "license": "MIT",
-  "type": "module"
-}
+{
+  "name": "@indigoai-us/hq-cli",
+  "version": "5.4.0",
+  "description": "HQ by Indigo management CLI — modules and cloud sync",
+  "main": "dist/index.js",
+  "bin": {
+    "hq": "dist/index.js",
+    "hq-auth-refresh": "dist/bin/hq-auth-refresh.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@indigoai-us/hq-cloud": "5.1.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0",
+    "simple-git": "^3.27.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/indigoai-us/hq.git",
+    "directory": "packages/hq-cli"
+  },
+  "keywords": ["hq", "ai", "modules", "sync", "cloud"],
+  "license": "MIT",
+  "type": "module"
+}

package/src/bin/hq-auth-refresh.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone `hq-auth-refresh` entry point.
+ *
+ * Exists so the deploy skill (.claude/skills/deploy/SKILL.md step 4) can
+ * shell out to a plain binary instead of a subcommand. Equivalent to
+ * `hq auth refresh`.
+ *
+ * Exit 0 on refresh, exit 1 if no cached session or refresh failed.
+ * Writes the refreshed tokens to ~/.hq/cognito-tokens.json.
+ */
+
+import { refreshCachedSession } from "../utils/cognito-session.js";
+
+async function main(): Promise<void> {
+  const result = await refreshCachedSession();
+  if (result.refreshed) {
+    process.exit(0);
+  }
+  if (result.reason) {
+    process.stderr.write(`hq-auth-refresh: ${result.reason}\n`);
+  }
+  process.exit(1);
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `hq-auth-refresh: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exit(1);
+});

package/src/commands/add.ts

@@ -0,0 +1,74 @@
+/**
+ * hq modules add command (US-003)
+ */
+
+import { Command } from 'commander';
+import { findHqRoot, addModule, parseRepoName, isValidRepoUrl } from '../utils/manifest.js';
+import type { ModuleDefinition, SyncStrategy } from '../types.js';
+
+export function registerAddCommand(program: Command): void {
+  program
+    .command('add <repo-url>')
+    .description('Add a module to the manifest')
+    .option('--as <name>', 'Module name (defaults to repo name)')
+    .option('--branch <branch>', 'Git branch to track', 'main')
+    .option('--strategy <strategy>', 'Sync strategy: link | merge | copy', 'link')
+    .option('--path <mapping>', 'Path mapping src:dest (can repeat)', (val, prev: string[]) => [...prev, val], [])
+    .action(async (repoUrl: string, options: {
+      as?: string;
+      branch: string;
+      strategy: string;
+      path: string[];
+    }) => {
+      try {
+        // Validate repo URL
+        if (!isValidRepoUrl(repoUrl)) {
+          console.error('Error: Invalid repo URL. Must start with https:// or git@');
+          process.exit(1);
+        }
+
+        // Parse name
+        const name = options.as || parseRepoName(repoUrl);
+
+        // Validate strategy
+        const validStrategies: SyncStrategy[] = ['link', 'merge', 'copy'];
+        if (!validStrategies.includes(options.strategy as SyncStrategy)) {
+          console.error(`Error: Invalid strategy "${options.strategy}". Use: ${validStrategies.join(', ')}`);
+          process.exit(1);
+        }
+
+        // Parse path mappings
+        const paths = options.path.length > 0
+          ? options.path.map(p => {
+              const [src, dest] = p.split(':');
+              if (!src || !dest) {
+                throw new Error(`Invalid path mapping: ${p}. Format: src:dest`);
+              }
+              return { src, dest };
+            })
+          : [{ src: '.', dest: `workers/${name}` }]; // Default: entire repo to workers/
+
+        const module: ModuleDefinition = {
+          name,
+          repo: repoUrl,
+          branch: options.branch,
+          strategy: options.strategy as SyncStrategy,
+          paths,
+        };
+
+        const hqRoot = findHqRoot();
+        addModule(hqRoot, module);
+
+        console.log(`Added module "${name}"`);
+        console.log(`  Repo: ${repoUrl}`);
+        console.log(`  Branch: ${options.branch}`);
+        console.log(`  Strategy: ${options.strategy}`);
+        console.log(`  Paths: ${paths.map(p => `${p.src} -> ${p.dest}`).join(', ')}`);
+        console.log('\nRun "hq modules sync" to fetch and sync the module.');
+
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/auth.ts

@@ -0,0 +1,153 @@
+/**
+ * `hq auth` — Cognito identity management for HQ.
+ *
+ * Subcommands:
+ *   hq auth login     — open the Cognito Hosted UI in the browser and cache tokens
+ *   hq auth logout    — clear the cached HQ session
+ *   hq auth refresh   — refresh the cached Cognito session (non-interactive)
+ *   hq auth status    — show whether a valid session is cached + expiry
+ *
+ * Sign-up is owned by the onboarding web app at
+ * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
+ * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
+ * session is kept fresh by `hq auth refresh` / `hq-auth-refresh` and consumed
+ * by the deploy + sync skills.
+ *
+ * Note: the top-level `hq login` command authenticates against the HQ package
+ * registry (Clerk), not Cognito — that is a different auth stack.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import {
+  browserLogin,
+  clearCachedTokens,
+  loadCachedTokens,
+  isExpiring,
+  CognitoAuthError,
+} from "@indigoai-us/hq-cloud";
+import {
+  DEFAULT_COGNITO,
+  refreshCachedSession,
+} from "../utils/cognito-session.js";
+
+/**
+ * Decode the (unverified) ID token payload for display purposes only.
+ * The token was just returned by Cognito's token endpoint, so its contents
+ * are trusted enough to print — we never use these claims for authorization.
+ */
+function peekIdToken(
+  idToken: string,
+): { email?: string; sub?: string } {
+  try {
+    const payload = idToken.split(".")[1];
+    if (!payload) return {};
+    const pad =
+      payload.length % 4 === 0 ? "" : "=".repeat(4 - (payload.length % 4));
+    const normalized =
+      payload.replace(/-/g, "+").replace(/_/g, "/") + pad;
+    const decoded = JSON.parse(
+      Buffer.from(normalized, "base64").toString("utf-8"),
+    );
+    return { email: decoded.email, sub: decoded.sub };
+  } catch {
+    return {};
+  }
+}
+
+export function registerAuthCommands(program: Command): void {
+  const authCmd = program
+    .command("auth")
+    .description("Manage the local HQ Cognito session");
+
+  authCmd
+    .command("login")
+    .description(
+      "Sign in to HQ — opens the Cognito Hosted UI and caches tokens locally",
+    )
+    .action(async () => {
+      const existing = loadCachedTokens();
+      if (existing && !isExpiring(existing, 120)) {
+        const who = peekIdToken(existing.idToken).email ?? "cached session";
+        console.log(
+          chalk.green(`Already signed in (${who}). Run \`hq auth logout\` to switch accounts.`),
+        );
+        return;
+      }
+      try {
+        const tokens = await browserLogin(DEFAULT_COGNITO);
+        const who = peekIdToken(tokens.idToken).email ?? "HQ";
+        console.log(chalk.green(`Signed in as ${who}`));
+        console.log(
+          chalk.dim(`  Token cached at ~/.hq/cognito-tokens.json (expires ${tokens.expiresAt})`),
+        );
+      } catch (err) {
+        const msg =
+          err instanceof CognitoAuthError
+            ? err.message
+            : err instanceof Error
+              ? err.message
+              : String(err);
+        console.error(chalk.red(`Login failed: ${msg}`));
+        console.error(
+          chalk.dim(
+            "  If you do not have an account, sign up at https://onboarding.indigo-hq.com",
+          ),
+        );
+        process.exit(1);
+      }
+    });
+
+  authCmd
+    .command("logout")
+    .description("Clear the cached HQ Cognito session")
+    .action(() => {
+      const existing = loadCachedTokens();
+      if (!existing) {
+        console.log(chalk.yellow("No cached HQ session"));
+        return;
+      }
+      clearCachedTokens();
+      console.log(chalk.green("Signed out — removed ~/.hq/cognito-tokens.json"));
+    });
+
+  authCmd
+    .command("refresh")
+    .description(
+      "Refresh the cached Cognito session using the stored refresh token",
+    )
+    .action(async () => {
+      const result = await refreshCachedSession();
+      if (result.refreshed) {
+        console.log(chalk.green("HQ session refreshed"));
+        return;
+      }
+      console.error(
+        chalk.yellow(`No refresh: ${result.reason ?? "unknown"}`),
+      );
+      process.exit(1);
+    });
+
+  authCmd
+    .command("status")
+    .description("Show whether a valid HQ session is cached")
+    .action(() => {
+      const cached = loadCachedTokens();
+      if (!cached) {
+        console.log(chalk.yellow("No cached HQ session — run `hq auth login`"));
+        process.exit(1);
+      }
+      const who = peekIdToken(cached.idToken).email;
+      const expiring = isExpiring(cached);
+      const label = who ? `${who} — ` : "";
+      console.log(
+        expiring
+          ? chalk.yellow(
+              `${label}HQ session cached but expiring (expiresAt=${cached.expiresAt})`,
+            )
+          : chalk.green(
+              `${label}HQ session valid (expiresAt=${cached.expiresAt})`,
+            ),
+      );
+    });
+}

package/src/commands/cloud.ts

@@ -0,0 +1,125 @@
+/**
+ * hq sync commands — cloud sync management
+ * Bridges hq-cli to @indigoai-us/hq-cloud
+ */
+
+import { Command } from "commander";
+import { findHqRoot } from "../utils/manifest.js";
+
+export function registerCloudCommands(program: Command): void {
+  program
+    .command("init")
+    .description("Authenticate with IndigoAI and set up cloud sync")
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const { initSync } = await import("@indigoai-us/hq-cloud");
+        await initSync(hqRoot);
+      } catch (error) {
+        console.error(
+          "Error:",
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("start")
+    .description("Start the background sync daemon")
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const { startDaemon } = await import("@indigoai-us/hq-cloud");
+        await startDaemon(hqRoot);
+        console.log("Sync daemon started. Use 'hq sync status' to check.");
+      } catch (error) {
+        console.error(
+          "Error:",
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("stop")
+    .description("Stop the sync daemon")
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const { stopDaemon } = await import("@indigoai-us/hq-cloud");
+        await stopDaemon(hqRoot);
+        console.log("Sync daemon stopped.");
+      } catch (error) {
+        console.error(
+          "Error:",
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("status")
+    .description("Show sync status")
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const { getStatus } = await import("@indigoai-us/hq-cloud");
+        const status = await getStatus(hqRoot);
+        console.log(`  State:      ${status.running ? "running" : "stopped"}`);
+        console.log(`  Last sync:  ${status.lastSync || "never"}`);
+        console.log(`  Files:      ${status.fileCount} tracked`);
+        console.log(`  Bucket:     ${status.bucket || "not configured"}`);
+        if (status.errors.length > 0) {
+          console.log(`  Errors:     ${status.errors.length}`);
+          for (const err of status.errors.slice(0, 5)) {
+            console.log(`    - ${err}`);
+          }
+        }
+      } catch (error) {
+        console.error(
+          "Error:",
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("push")
+    .description("Force push all local changes to cloud")
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const { pushAll } = await import("@indigoai-us/hq-cloud");
+        const result = await pushAll(hqRoot);
+        console.log(`Pushed ${result.filesUploaded} files to cloud.`);
+      } catch (error) {
+        console.error(
+          "Error:",
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("pull")
+    .description("Force pull all cloud changes to local")
+    .action(async () => {
+      try {
+        const hqRoot = findHqRoot();
+        const { pullAll } = await import("@indigoai-us/hq-cloud");
+        const result = await pullAll(hqRoot);
+        console.log(`Pulled ${result.filesDownloaded} files from cloud.`);
+      } catch (error) {
+        console.error(
+          "Error:",
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    });
+}