@indigoai-us/hq-cli 5.13.1 → 5.14.1

package/src/commands/pack-install.test.ts

@@ -0,0 +1,148 @@
+/**
+ * pack-install layout tests — guards the boundary between hq-cli and the
+ * HQ template's on-disk layout.
+ *
+ * The HQ template (hq-core / hq-core-staging) ships:
+ *   - `core/packages/` as the install root for content packs
+ *   - `core/scripts/scan-packages.sh` as the post-install wirer
+ *   - NO top-level `modules/` directory under the new layout
+ *
+ * Earlier `pack-install` wrote to `packages/<name>/` (top-level), called
+ * `scripts/scan-packages.sh` (top-level), and appended entries to
+ * `modules/modules.yaml` — leaving three orphan trees alongside the real
+ * `core/packages/`. This file pins the new contract end-to-end.
+ *
+ * Uses real `rsync` (POSIX-available on macOS / Linux runners) so the test
+ * exercises the same shell-out the production path does — no hand-rolled
+ * mocks of payload-copy behavior.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { installToPackages, runScanPackages } from './pack-install.js';
+import type { PackManifest } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function mkFakeHq(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'hq-cli-test-hq-'));
+}
+
+function mkFakePackPayload(files: Record<string, string>): string {
+  const payload = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-cli-test-pack-'));
+  for (const [rel, body] of Object.entries(files)) {
+    const abs = path.join(payload, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, body);
+  }
+  return payload;
+}
+
+function fakeManifest(overrides?: Partial<PackManifest>): PackManifest {
+  return {
+    name: 'hq-pack-test',
+    version: '1.0.0',
+    contributes: {},
+    ...overrides,
+  } as PackManifest;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('pack-install: install path layout', () => {
+  let hqRoot: string;
+  let payload: string;
+
+  beforeEach(() => {
+    hqRoot = mkFakeHq();
+    payload = mkFakePackPayload({
+      'README.md': '# pack readme',
+      'package.yaml': 'name: hq-pack-test\nversion: 1.0.0\n',
+      'hooks/pre.sh': '#!/bin/sh\necho hi\n',
+    });
+  });
+
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+    fs.rmSync(payload, { recursive: true, force: true });
+  });
+
+  // ---- 1. install destination ---------------------------------------------
+  it('installToPackages writes the payload under core/packages/<name>/, NOT top-level packages/', () => {
+    const dest = installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+
+    // New layout: core/packages/<name>/
+    expect(dest).toBe(path.join(hqRoot, 'core', 'packages', 'hq-pack-test'));
+    expect(fs.existsSync(path.join(hqRoot, 'core', 'packages', 'hq-pack-test', 'README.md'))).toBe(
+      true,
+    );
+    expect(
+      fs.existsSync(path.join(hqRoot, 'core', 'packages', 'hq-pack-test', 'hooks', 'pre.sh')),
+    ).toBe(true);
+
+    // Top-level packages/ must NOT be created — that was the old buggy layout.
+    expect(fs.existsSync(path.join(hqRoot, 'packages'))).toBe(false);
+  });
+
+  // ---- 2. re-install idempotency -----------------------------------------
+  it('installToPackages replaces an existing core/packages/<name> destination cleanly', () => {
+    // Seed a stale install with a file the new payload doesn't have. A clean
+    // re-install must wipe it — otherwise stale contributions linger and
+    // scan-packages.sh wires them back into host paths.
+    const dest = path.join(hqRoot, 'core', 'packages', 'hq-pack-test');
+    fs.mkdirSync(dest, { recursive: true });
+    fs.writeFileSync(path.join(dest, 'STALE-FILE.md'), 'old content');
+
+    installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+
+    expect(fs.existsSync(path.join(dest, 'README.md'))).toBe(true); // new content
+    expect(fs.existsSync(path.join(dest, 'STALE-FILE.md'))).toBe(false); // wiped
+  });
+
+  // ---- 3. scan-packages.sh resolution -------------------------------------
+  it('runScanPackages invokes core/scripts/scan-packages.sh when present', () => {
+    const scriptDir = path.join(hqRoot, 'core', 'scripts');
+    fs.mkdirSync(scriptDir, { recursive: true });
+    const sentinel = path.join(hqRoot, '.scan-ran');
+    // Self-attesting script: writes a sentinel file when invoked. Lets us
+    // verify path resolution without spying on spawnSync.
+    fs.writeFileSync(
+      path.join(scriptDir, 'scan-packages.sh'),
+      `#!/bin/sh\ntouch "${sentinel}"\n`,
+      { mode: 0o755 },
+    );
+
+    runScanPackages(hqRoot);
+
+    expect(fs.existsSync(sentinel)).toBe(true);
+  });
+
+  it('runScanPackages skips with a dim warning when core/scripts/scan-packages.sh is absent', () => {
+    // No script anywhere — runScanPackages must not throw, must not invoke
+    // the old top-level scripts/scan-packages.sh either.
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+    expect(() => runScanPackages(hqRoot)).not.toThrow();
+
+    expect(logSpy).toHaveBeenCalled();
+    // The "skipping auto-wire" message goes through chalk.dim, so just match
+    // the human-readable substring rather than the ANSI sequence.
+    const allLogs = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+    expect(allLogs).toMatch(/scan-packages\.sh not present/);
+    logSpy.mockRestore();
+  });
+
+  // ---- 4. no modules/ directory -------------------------------------------
+  it('regression: installing a pack does not create top-level modules/ or modules.yaml', () => {
+    installToPackages(payload, fakeManifest({ name: 'hq-pack-test' }), hqRoot);
+
+    expect(fs.existsSync(path.join(hqRoot, 'modules'))).toBe(false);
+    expect(fs.existsSync(path.join(hqRoot, 'modules.yaml'))).toBe(false);
+  });
+});

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/index.ts

@@ -34,6 +34,7 @@ import {
   maybeWarnNewVersion,
   refreshVersionCache,
 } from "./utils/version-check.js";
+import { CLI_VERSION } from "./cli-version.js";
 
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes the pipe early.
 const onPipeError = (err: NodeJS.ErrnoException): void => {
@@ -53,7 +54,7 @@ const program = new Command();
 program
   .name("hq")
   .description("HQ management CLI — modules, packages, and cloud sync")
-  .version("5.12.4");
+  .version(CLI_VERSION);
 
 // Module management subcommand group
 const modulesCmd = program

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