@indigoai-us/hq-cloud 6.1.0 → 6.2.0

package/src/cli/reindex.ts

@@ -1,30 +1,22 @@
 /**
- * hq reindex — surfaces namespaced skills as Claude Code skill wrappers,
- * mirrors personal/{knowledge,policies,workers,settings} into core/, prunes
- * orphan wrappers, and regenerates the workers registry.
+ * hq reindex — surfaces namespaced skills as Claude Code skill wrappers under
+ * .claude/skills/<ns>:<skill>/ (one symlink per source file), mirrors
+ * personal/{knowledge,policies,workers,settings}/<entry> into core/<type>/,
+ * prunes orphan wrappers + legacy command symlinks, and regenerates the
+ * workers registry.
  *
- * The implementation lives in scripts/reindex.sh, shipped with this package.
- * This module resolves that script relative to the package (dist/cli → package
- * root) and execs it against the caller's HQ root. Historically the script ran
- * directly as a Claude Code hook inside hq-core (named "master-sync"); it now
- * lives here so a single copy is maintained, and the hq-core hook is a thin
- * shim over `hq reindex`.
+ * The logic historically lived in a bundled bash script (scripts/reindex.sh)
+ * that this module exec'd via `bash`. It is now implemented natively in
+ * TypeScript so the package ships a single, testable code path with no runtime
+ * dependency on a shipped shell script. Behaviour is preserved exactly: the
+ * same skill wrappers, personal-overlay mirrors, legacy-symlink cleanup, and
+ * idempotent re-runs as before. Historically the script ran directly as a
+ * Claude Code hook inside hq-core (named "master-sync"); the hq-core hook
+ * remains a thin shim over `hq reindex`.
  */
 import { spawnSync } from "child_process";
-import { fileURLToPath } from "url";
-import path from "path";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Absolute path to the bundled reindex.sh. From the compiled module at
- * dist/cli/reindex.js, the package root is two levels up; the script lives
- * at <package-root>/scripts/reindex.sh.
- */
-export function reindexScriptPath(): string {
-  return path.resolve(__dirname, "..", "..", "scripts", "reindex.sh");
-}
+import * as fs from "fs";
+import * as path from "path";
 
 export interface ReindexOptions {
   /** HQ root to operate on. Defaults to process.cwd(). */
@@ -32,26 +24,343 @@ export interface ReindexOptions {
 }
 
 export interface ReindexResult {
-  /** Exit status of the underlying script (0 = success). */
+  /** 0 = success; 1 = invalid repo root (mirrors the old script's exit codes). */
   status: number;
 }
 
+// --- small fs helpers (each mirrors a bash test operator) -------------------
+
+/** `[ -d "$p" ]` — exists and is a directory (follows symlinks). */
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** `[ -f "$p" ]` — exists and is a regular file (follows symlinks). */
+function isFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** `[ -e "$p" ]` — exists, dereferencing symlinks (a broken symlink is false). */
+function existsFollow(p: string): boolean {
+  try {
+    fs.statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `[ -x "$p" ]` — exists and is executable. */
+function isExecutable(p: string): boolean {
+  try {
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** lstat without throwing (null when the path doesn't exist). */
+function lstatOrNull(p: string): fs.Stats | null {
+  try {
+    return fs.lstatSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/** readlink without throwing (null when not a symlink / missing). */
+function readlinkOrNull(p: string): string | null {
+  try {
+    return fs.readlinkSync(p);
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Run reindex against an HQ root. Synchronous — the script is cheap and
+ * Entries of `dir` matching a bash `dir/*` glob: dotfiles excluded (no
+ * dotglob), sorted lexicographically (bash glob order). Missing dir → [].
+ */
+function globEntries(dir: string): string[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names.filter((n) => !n.startsWith(".")).sort();
+}
+
+function warn(msg: string): void {
+  process.stderr.write(`${msg}\n`);
+}
+
+// --- legacy `.claude/commands/<ns>/<skill>.md` symlink matcher --------------
+// Mirrors the bash `case` patterns; `*` matches any chars (including `/`).
+function isLegacyCommandTarget(t: string): boolean {
+  return (
+    /^\.\.\/\.\.\/\.\.\/companies\/.*\/skills\/.*\/SKILL\.md$/.test(t) ||
+    /^\.\.\/\.\.\/\.\.\/core\/skills\/.*\/SKILL\.md$/.test(t) ||
+    /^\.\.\/\.\.\/\.\.\/personal\/skills\/.*\/SKILL\.md$/.test(t) ||
+    /^\.\.\/\.\.\/\.\.\/core\/packages\/.*\/skills\/.*\/SKILL\.md$/.test(t)
+  );
+}
+
+/**
+ * Run reindex against an HQ root. Synchronous — the work is cheap and
  * idempotent, and callers (the hook shim, sync/rescue, tests) want the exit
- * status. stdout/stderr from the script are forwarded to stderr so the
- * caller's stdout stays clean (hooks must not emit stdout that the agent
- * interprets).
+ * status. Diagnostics are written to stderr so the caller's stdout stays clean
+ * (hooks must not emit stdout that the agent interprets).
  */
 export function reindex(opts: ReindexOptions = {}): ReindexResult {
-  const repoRoot = opts.repoRoot ?? process.cwd();
-  const script = reindexScriptPath();
-  const res = spawnSync("bash", [script, repoRoot], {
-    stdio: ["ignore", "inherit", "inherit"],
-  });
-  if (res.error) {
-    process.stderr.write(`reindex: failed to run ${script}: ${res.error.message}\n`);
+  const rawRoot = opts.repoRoot ?? process.cwd();
+  if (!isDir(rawRoot)) {
+    warn(`reindex: REPO_ROOT '${rawRoot}' is not a directory`);
     return { status: 1 };
   }
-  return { status: res.status ?? 1 };
+  const root = path.resolve(rawRoot);
+
+  fs.mkdirSync(path.join(root, ".claude", "skills"), { recursive: true });
+
+  // --- Build (namespace, src_rel) pairs -------------------------------------
+  const pairs: { ns: string; srcRel: string }[] = [];
+  const addNs = (ns: string, srcRel: string): void => {
+    if (isDir(path.join(root, srcRel))) pairs.push({ ns, srcRel });
+  };
+
+  for (const slug of globEntries(path.join(root, "companies"))) {
+    if (isDir(path.join(root, "companies", slug))) {
+      addNs(slug, `companies/${slug}/skills`);
+    }
+  }
+  addNs("core", "core/skills");
+  addNs("personal", "personal/skills");
+  for (const pack of globEntries(path.join(root, "core", "packages"))) {
+    if (isDir(path.join(root, "core", "packages", pack))) {
+      addNs(pack, `core/packages/${pack}/skills`);
+    }
+  }
+
+  // --- Cleanup pass A: drop legacy .claude/commands/<ns>/<skill>.md links ----
+  const commandsDir = path.join(root, ".claude", "commands");
+  if (isDir(commandsDir)) {
+    for (const nsName of globEntries(commandsDir)) {
+      const cmdNsDir = path.join(commandsDir, nsName);
+      // Only real directories (bash `*/`); folder-level symlinks are left for
+      // a human to resolve. lstat().isDirectory() is false for a symlink, so
+      // this single check covers both bash guards.
+      const st = lstatOrNull(cmdNsDir);
+      if (!st || !st.isDirectory()) continue;
+
+      for (const f of globEntries(cmdNsDir)) {
+        if (!f.endsWith(".md")) continue;
+        const fp = path.join(cmdNsDir, f);
+        const fst = lstatOrNull(fp);
+        if (!fst || !fst.isSymbolicLink()) continue;
+        const target = readlinkOrNull(fp);
+        if (target && isLegacyCommandTarget(target)) {
+          try {
+            fs.rmSync(fp);
+          } catch {
+            /* best-effort */
+          }
+        }
+      }
+
+      // rmdir if empty; ignore "directory not empty".
+      try {
+        fs.rmdirSync(cmdNsDir);
+      } catch {
+        /* not empty / gone — fine */
+      }
+    }
+  }
+
+  // --- Skill wrapper creation -----------------------------------------------
+  const expectedWrappers = new Set<string>();
+  const seen = new Set<string>();
+
+  for (const { ns, srcRel } of pairs) {
+    // First writer for a namespace wins.
+    if (seen.has(ns)) {
+      warn(
+        `reindex: namespace '${ns}' already claimed by an earlier source; skipping ${srcRel}`,
+      );
+      continue;
+    }
+    seen.add(ns);
+
+    const srcAbs = path.join(root, srcRel);
+    for (const skillName of globEntries(srcAbs)) {
+      const skillPath = path.join(srcAbs, skillName);
+      if (!isDir(skillPath)) continue;
+      // Skip `_shared`, `_template`, etc. (dotfiles already excluded by glob).
+      if (skillName.startsWith("_")) continue;
+      if (!isFile(path.join(skillPath, "SKILL.md"))) continue;
+
+      const wrapperName = `${ns}:${skillName}`;
+      const wrapper = path.join(root, ".claude", "skills", wrapperName);
+      expectedWrappers.add(wrapperName);
+
+      const wst = lstatOrNull(wrapper);
+      // If something non-directory, non-symlink occupies the slot, bail.
+      if (wst && !wst.isSymbolicLink() && !wst.isDirectory()) {
+        warn(`reindex: ${wrapper} exists and is not a directory; skipping`);
+        continue;
+      }
+      // If it's a symlink (legacy directory-symlink form), replace it with a
+      // real directory of per-file symlinks.
+      if (wst && wst.isSymbolicLink()) {
+        try {
+          fs.rmSync(wrapper);
+        } catch {
+          /* best-effort */
+        }
+      }
+      fs.mkdirSync(wrapper, { recursive: true });
+
+      // Symlink every (non-hidden) entry in the source skill folder. The
+      // wrapper lives three levels below REPO_ROOT.
+      for (const entry of globEntries(skillPath)) {
+        const entryPath = path.join(skillPath, entry);
+        if (!existsFollow(entryPath)) continue;
+        const linkPath = path.join(wrapper, entry);
+        const relativeTarget = `../../../${srcRel}/${skillName}/${entry}`;
+
+        const lst = lstatOrNull(linkPath);
+        if (lst && lst.isSymbolicLink()) {
+          const current = readlinkOrNull(linkPath);
+          if (current === relativeTarget) continue;
+          warn(
+            `reindex: .claude/skills/${wrapperName}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
+          );
+          continue;
+        } else if (lst) {
+          warn(`reindex: ${linkPath} already exists and is not a symlink; skipping`);
+          continue;
+        }
+
+        fs.symlinkSync(relativeTarget, linkPath);
+      }
+
+      // Prune symlinks in the wrapper whose source entry no longer exists.
+      for (const entry of globEntries(wrapper)) {
+        const linkPath = path.join(wrapper, entry);
+        const lst = lstatOrNull(linkPath);
+        if (!lst || !lst.isSymbolicLink()) continue;
+        if (existsFollow(linkPath)) continue;
+        try {
+          fs.rmSync(linkPath);
+        } catch {
+          /* best-effort */
+        }
+      }
+    }
+  }
+
+  // --- Cleanup pass B: drop orphan <ns>:<skill> wrappers --------------------
+  const skillsDir = path.join(root, ".claude", "skills");
+  for (const entry of globEntries(skillsDir)) {
+    const entryPath = path.join(skillsDir, entry);
+    const lst = lstatOrNull(entryPath);
+    if (!lst) continue; // accept broken symlinks (lstat still succeeds)
+    if (!entry.includes(":")) continue; // not a namespaced wrapper
+    if (expectedWrappers.has(entry)) continue; // maintained this run
+
+    // A wrapper is "managed" only when its namespace prefix matches the
+    // namespace encoded in its symlink target — this distinguishes
+    // script-produced wrappers from hand-authored composite wrappers.
+    const ns = entry.slice(0, entry.indexOf(":"));
+    const matchTarget = (t: string | null, p: string): boolean => {
+      if (!t) return false;
+      if (t.startsWith(`${p}/personal/skills/`)) return ns === "personal";
+      if (t.startsWith(`${p}/core/skills/`)) return ns === "core";
+      if (t.startsWith(`${p}/companies/${ns}/skills/`)) return true;
+      if (t.startsWith(`${p}/core/packages/${ns}/skills/`)) return true;
+      return false;
+    };
+
+    let isManaged = false;
+    if (lst.isSymbolicLink()) {
+      // (a) directory-style symlink wrapper (older shape): 2-level target.
+      isManaged = matchTarget(readlinkOrNull(entryPath), "../..");
+    } else if (lst.isDirectory()) {
+      // (b) real directory of per-file symlinks (current shape): 3-level.
+      for (const f of globEntries(entryPath)) {
+        const fp = path.join(entryPath, f);
+        const fst = lstatOrNull(fp);
+        if (!fst || !fst.isSymbolicLink()) continue;
+        if (matchTarget(readlinkOrNull(fp), "../../..")) {
+          isManaged = true;
+          break;
+        }
+      }
+    }
+    if (!isManaged) continue;
+
+    // Managed-namespace wrapper with no corresponding live source → drop.
+    try {
+      if (lst.isSymbolicLink()) {
+        fs.rmSync(entryPath);
+      } else if (lst.isDirectory()) {
+        fs.rmSync(entryPath, { recursive: true, force: true });
+      }
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  // --- Personal type mirroring ----------------------------------------------
+  // Mirror personal/<type>/<entry> into core/<type>/<entry> as symlinks.
+  for (const type of ["knowledge", "policies", "workers", "settings"]) {
+    const personalDir = path.join(root, "personal", type);
+    const coreDir = path.join(root, "core", type);
+
+    if (!isDir(personalDir)) continue;
+    fs.mkdirSync(coreDir, { recursive: true });
+
+    for (const entry of globEntries(personalDir)) {
+      const entryPath = path.join(personalDir, entry);
+      if (!existsFollow(entryPath)) continue;
+
+      const linkPath = path.join(coreDir, entry);
+      const relativeTarget = `../../personal/${type}/${entry}`;
+
+      const lst = lstatOrNull(linkPath);
+      if (lst && lst.isSymbolicLink()) {
+        const current = readlinkOrNull(linkPath);
+        if (current === relativeTarget) continue;
+        warn(
+          `reindex: core/${type}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
+        );
+        continue;
+      } else if (lst) {
+        warn(`reindex: core/${type}/${entry} already exists and is not a symlink; skipping`);
+        continue;
+      }
+
+      fs.symlinkSync(relativeTarget, linkPath);
+    }
+  }
+
+  // --- Workers registry regeneration ----------------------------------------
+  // Source of truth: each worker.yaml. The registry is a derived index — the
+  // generator (when present in the operated-on tree) keeps it in sync.
+  // Best-effort and idempotent; never fails the reindex.
+  const genScript = path.join(root, "core", "scripts", "generate-workers-registry.sh");
+  if (isExecutable(genScript)) {
+    // Route the generator's stdout+stderr to our stderr (`>&2 2>&1`).
+    spawnSync("bash", [genScript], { stdio: ["ignore", 2, 2] });
+  }
+
+  return { status: 0 };
 }