@indigoai-us/hq-cli 5.14.0 → 5.14.1

package/src/commands/pack-install.ts

@@ -26,9 +26,12 @@
  *   3. Parse + validate package.yaml (10 checks from spec)
  *   4. Evaluate `conditional` predicate — skip if exits non-zero
  *   5. Confirm hooks if `contributes.hooks` non-empty (unless --allow-hooks)
- *   6. Move into packages/{name}/
- *   7. Append entry to modules.yaml with strategy: package
- *   8. Run scan-packages.sh to wire contributions into host paths
+ *   6. Move into core/packages/{name}/
+ *   7. Run core/scripts/scan-packages.sh to wire contributions into host paths
+ *
+ * Installed packs are tracked by filesystem presence — there's no separate
+ * registry file under the v12 layout. (`hq update <pack>` re-resolves source
+ * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 
 import * as fs from 'fs';
@@ -42,17 +45,8 @@ import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
-import {
-  findHqRoot,
-  readManifest,
-  writeManifest,
-} from '../utils/manifest.js';
-import type {
-  PackManifest,
-  PackModuleDefinition,
-  ModulesManifest,
-  PackContributeKey,
-} from '../types.js';
+import { findHqRoot } from '../utils/manifest.js';
+import type { PackManifest, PackContributeKey } from '../types.js';
 
 // ---------------------------------------------------------------------------
 // Source classification
@@ -519,15 +513,28 @@ function evalConditional(expr: string): boolean {
 }
 
 // ---------------------------------------------------------------------------
-// Move into packages/ + update modules.yaml + scan
+// Move into core/packages/ + run core/scripts/scan-packages.sh
 // ---------------------------------------------------------------------------
 
-function installToPackages(
+/**
+ * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
+ * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships
+ * `core/packages/` as the canonical pack root; writing to top-level
+ * `packages/` would leave an orphan tree alongside the real one.
+ *
+ * Re-installs replace the existing destination so stale contributions don't
+ * linger (the post-install `scan-packages.sh` would otherwise wire them
+ * back into host paths).
+ *
+ * Exported for tests in pack-install.test.ts — see that file for the
+ * contract this function pins.
+ */
+export function installToPackages(
   payloadDir: string,
   pkg: PackManifest,
   hqRoot: string
 ): string {
-  const packagesDir = path.join(hqRoot, 'packages');
+  const packagesDir = path.join(hqRoot, 'core', 'packages');
   fs.mkdirSync(packagesDir, { recursive: true });
   const destDir = path.join(packagesDir, pkg.name);
   if (fs.existsSync(destDir)) {
@@ -540,35 +547,21 @@ function installToPackages(
   return destDir;
 }
 
-function updateModulesYaml(
-  hqRoot: string,
-  pkg: PackManifest,
-  fetched: FetchResult
-): void {
-  const manifest: ModulesManifest =
-    readManifest(hqRoot) ?? { version: '1', modules: [] };
-  // Drop any existing entry for this pack (idempotent re-install)
-  manifest.modules = manifest.modules.filter((m) => m.name !== pkg.name);
-  const entry: PackModuleDefinition = {
-    name: pkg.name,
-    strategy: 'package',
-    source: fetched.resolvedSource,
-    version: pkg.version,
-    installed_at: path.posix.join('packages', pkg.name),
-    installed_at_iso: new Date().toISOString(),
-    access: pkg.access === 'public' ? 'public' : undefined,
-  };
-  if (fetched.resolvedSha) entry.resolved_sha = fetched.resolvedSha;
-  manifest.modules.push(entry);
-  writeManifest(hqRoot, manifest);
-}
-
-function runScanPackages(hqRoot: string): void {
-  const script = path.join(hqRoot, 'scripts', 'scan-packages.sh');
+/**
+ * Run `<hqRoot>/core/scripts/scan-packages.sh` to wire the newly installed
+ * pack's contributions into the host paths (skills, hooks, policies, etc.).
+ * Skipping with a dim warning if the script is missing keeps fresh HQs (or
+ * older templates) usable — the next session start picks them up via its
+ * own scan.
+ *
+ * Exported for tests.
+ */
+export function runScanPackages(hqRoot: string): void {
+  const script = path.join(hqRoot, 'core', 'scripts', 'scan-packages.sh');
   if (!fs.existsSync(script)) {
     console.log(
       chalk.dim(
-        `  (scripts/scan-packages.sh not present — skipping auto-wire; ` +
+        `  (core/scripts/scan-packages.sh not present — skipping auto-wire; ` +
           `will run on next session start)`
       )
     );
@@ -647,7 +640,12 @@ export async function installPack(
     }
 
     const destDir = installToPackages(fetched.payloadDir, pkg, hqRoot);
-    updateModulesYaml(hqRoot, pkg, fetched);
+    // Under the v12 HQ layout, packs live at `core/packages/<name>/` and are
+    // tracked by filesystem presence alone — no `modules.yaml` write. That
+    // removes the side effect that created a top-level `modules/` directory
+    // alongside the canonical `core/`. `hq update <pack>` will re-resolve a
+    // pack's source from its on-disk package.yaml or prompt for it, but that
+    // tradeoff is intentional — see the layout-fix PR for rationale.
     runScanPackages(hqRoot);
 
     console.log(

package/src/utils/cognito-session.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Unit tests for resolveDefaultHqRoot — Cognito session helper bits that
+ * don't need a live JWT or vault round-trip.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveDefaultHqRoot } from "./cognito-session.js";
+
+describe("resolveDefaultHqRoot", () => {
+  let tmpRoot: string;
+  let origCwd: string;
+  let origEnv: string | undefined;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), "hq-cli-resolveroot-"));
+    origCwd = process.cwd();
+    origEnv = process.env.HQ_ROOT;
+    delete process.env.HQ_ROOT;
+  });
+
+  afterEach(() => {
+    process.chdir(origCwd);
+    rmSync(tmpRoot, { recursive: true, force: true });
+    if (origEnv === undefined) delete process.env.HQ_ROOT;
+    else process.env.HQ_ROOT = origEnv;
+  });
+
+  it("priority 1: honors $HQ_ROOT env var (resolved to absolute path)", () => {
+    const explicit = join(tmpRoot, "explicit-target");
+    mkdirSync(explicit, { recursive: true });
+    process.env.HQ_ROOT = explicit;
+
+    expect(resolveDefaultHqRoot()).toBe(explicit);
+  });
+
+  it("priority 2: walks up from cwd to the nearest dir containing core.yaml AND companies/", () => {
+    const hqDir = join(tmpRoot, "Documents", "coding-projects", "hq");
+    const nested = join(hqDir, "companies", "sum-digital");
+    mkdirSync(nested, { recursive: true });
+    writeFileSync(join(hqDir, "core.yaml"), "version: 14.1.1\n");
+    // companies/ already exists (we mkdir'd nested inside it)
+
+    process.chdir(nested);
+    expect(resolveDefaultHqRoot()).toBe(hqDir);
+
+    process.chdir(hqDir);
+    expect(resolveDefaultHqRoot()).toBe(hqDir);
+  });
+
+  it("priority 2: SKIPS a nested core/core.yaml without a sibling companies/ dir (Codex P2 on hq#146)", () => {
+    // Recreates the live HQ layout: a real root has core.yaml + companies/,
+    // and the synced core/ subtree contains its own core.yaml (the template
+    // version-source-of-truth) but NO companies/. Single-marker detection
+    // would stop at <hqRoot>/core/ and silently miss the real content.
+    const hqDir = join(tmpRoot, "Documents", "coding-projects", "hq");
+    const innerCore = join(hqDir, "core");
+    const cwdInsideCore = join(innerCore, "knowledge");
+    mkdirSync(cwdInsideCore, { recursive: true });
+    mkdirSync(join(hqDir, "companies"), { recursive: true });
+    writeFileSync(join(hqDir, "core.yaml"), "version: 14.1.1\n");
+    writeFileSync(join(innerCore, "core.yaml"), "template-version: 14.1.1\n");
+
+    process.chdir(cwdInsideCore);
+    // Should walk PAST the inner core/core.yaml (no companies/ sibling) and
+    // resolve to the real hqDir.
+    expect(resolveDefaultHqRoot()).toBe(hqDir);
+  });
+
+  it("priority 3: falls back when neither $HQ_ROOT nor an HQ-root marker pair are found", () => {
+    const stranded = join(tmpRoot, "stranded");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    const result = resolveDefaultHqRoot();
+    // Walks up to filesystem root, no core.yaml+companies/ pair found, falls
+    // back to ~/hq. We don't assert the exact value (depends on the test
+    // runner's $HOME) but the result should NOT be the stranded dir.
+    expect(result).not.toBe(stranded);
+    expect(result.endsWith("/hq")).toBe(true);
+  });
+
+  it("priority 3: a dir with only core.yaml (no companies/) is NOT a valid HQ root", () => {
+    // core.yaml present but no companies/ sibling → fall through to ~/hq.
+    // This is the synced core/ subtree's signature.
+    const lonelyCoreYaml = join(tmpRoot, "lonely");
+    mkdirSync(lonelyCoreYaml, { recursive: true });
+    writeFileSync(join(lonelyCoreYaml, "core.yaml"), "");
+    process.chdir(lonelyCoreYaml);
+
+    const result = resolveDefaultHqRoot();
+    expect(result).not.toBe(lonelyCoreYaml);
+    expect(result.endsWith("/hq")).toBe(true);
+  });
+
+  it("$HQ_ROOT wins over walking-up resolution", () => {
+    const walkable = join(tmpRoot, "walkable");
+    const explicit = join(tmpRoot, "explicit");
+    mkdirSync(join(walkable, "nested"), { recursive: true });
+    mkdirSync(join(walkable, "companies"), { recursive: true });
+    mkdirSync(explicit, { recursive: true });
+    writeFileSync(join(walkable, "core.yaml"), "");
+
+    process.chdir(join(walkable, "nested"));
+    process.env.HQ_ROOT = explicit;
+
+    expect(resolveDefaultHqRoot()).toBe(explicit);
+  });
+});

package/src/utils/cognito-session.ts

@@ -19,6 +19,7 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
+import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import chalk from "chalk";
@@ -52,7 +53,51 @@ export const DEFAULT_COGNITO: CognitoAuthConfig = {
 export const DEFAULT_VAULT_API_URL =
   process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
 
-export const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
+/**
+ * Resolve the default HQ tree root for cloud-aware subcommands.
+ *
+ * Priority order:
+ *   1. `$HQ_ROOT` env var (explicit user override)
+ *   2. Walk up from `process.cwd()` to the nearest dir containing BOTH a
+ *      `core.yaml` file AND a `companies/` directory (root-unique marker
+ *      pair — see note below).
+ *   3. Fall back to `~/hq` (the historical default)
+ *
+ * Why both markers?
+ *   The HQ root has `core.yaml` AND a sibling `companies/` directory. The
+ *   synced `core/` subtree (which is itself part of the root's personal-vault
+ *   scope) ALSO contains a `core.yaml` (the template's version-source-of-
+ *   truth), but does NOT contain `companies/`. Single-marker `core.yaml`
+ *   detection would stop at `<hqRoot>/core/` when the CLI is launched from
+ *   somewhere inside that subtree, and downstream `companies/` lookups would
+ *   silently miss the real content. Requiring `companies/` as well guarantees
+ *   we resolve to the actual HQ root (Codex P2 on hq#146).
+ *
+ * Evaluated once at module load — commander.js `.option()` callers pin the
+ * value at registration time, which matches the user's actual cwd at process
+ * start. Re-importable as a function for tests and command-time resolution.
+ */
+export function resolveDefaultHqRoot(): string {
+  if (process.env.HQ_ROOT) return path.resolve(process.env.HQ_ROOT);
+  let cur = path.resolve(process.cwd());
+  while (cur !== path.dirname(cur)) {
+    if (isHqRoot(cur)) return cur;
+    cur = path.dirname(cur);
+  }
+  return path.join(os.homedir(), "hq");
+}
+
+/** True iff `dir` looks like an HQ root (has core.yaml + companies/ dir). */
+function isHqRoot(dir: string): boolean {
+  if (!fs.existsSync(path.join(dir, "core.yaml"))) return false;
+  try {
+    return fs.statSync(path.join(dir, "companies")).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export const DEFAULT_HQ_ROOT = resolveDefaultHqRoot();
 
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in