@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/lib/doctor/checks/release-links.js

@@ -6,11 +6,15 @@
  * user customization and is left alone.
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import { removeLinkOnly } from "../../../utils/safe-link.js";
 export const RELEASE_LINKS_FAMILY_ID = "release-links";
 export const RELEASE_LINKS_FAMILY_TITLE = "Release links";
 export const RELEASE_LINKS_CHECK_ID = "release-links.resolve";
-export const RELEASE_LINK_REMEDIATION = "Run `hq rescue -y` again. On Windows without Developer Mode, a directory link is written as a junction and a file link as a copy.";
+export const RELEASE_LINK_REMEDIATION = "Run `hq doctor --fix` (or `hq rescue -y`) to restore the shipped link. A dangling link that points outside the HQ root and the temp folder is treated as your own and left alone. On Windows, a directory link is written as a junction and a file link as a copy when symlinks are not allowed.";
+/** Message prefix for a link whose target is missing; `--fix` keys off it. */
+export const DANGLING_RELEASE_LINK_PROBLEM = "does not resolve.";
 const CYGWIN_SYMLINK_COOKIE = Buffer.from("!<symlink>", "latin1");
 /** Paths git records as symlinks in the hq-core release. */
 export const RELEASE_LINKS = [
@@ -80,7 +84,11 @@ function releaseLinkProblem(hqRoot, entry) {
             resolved = fs.realpathSync.native(destination);
         }
         catch {
-            return "does not resolve. Its target is missing, often because an update linked it at a staging folder that was then deleted.";
+            const current = readlinkAbsOrNull(destination);
+            if (current !== null && !isRepairableDanglingTarget(hqRoot, current)) {
+                return `points at ${current}, which is missing and outside this HQ root. It is treated as your own link and left alone; fix or remove it yourself.`;
+            }
+            return `${DANGLING_RELEASE_LINK_PROBLEM} Its target is missing, often because an update linked it at a staging folder that was then deleted.`;
         }
         if (!pathIsInside(hqRoot, resolved)) {
             return "points outside this HQ root, so it does not resolve to the shipped target.";
@@ -108,6 +116,42 @@ function releaseLinkProblem(hqRoot, entry) {
     // A real directory in place of a directory link is a user replacement.
     return null;
 }
+function readlinkAbsOrNull(destination) {
+    try {
+        return path.resolve(path.dirname(destination), fs.readlinkSync(destination));
+    }
+    catch {
+        return null;
+    }
+}
+/** Prefix of the folder hq-cloud's rescue creates with mkdtemp. */
+const RESCUE_STAGING_SEGMENT_PREFIX = "hq-replace-rescue-";
+/**
+ * The rescue staging roots, mirroring hq-cloud's `resolveRescueStagingRoot`:
+ * the system temp folder, or `tmp` beside the backup root (`~/.hq/tmp`, or
+ * next to `$HQ_BACKUP_DIR`) when the temp folder is on another filesystem.
+ */
+function rescueStagingRoots(deps) {
+    const backupRoot = deps.backupRoot ?? process.env.HQ_BACKUP_DIR ?? path.join(os.homedir(), ".hq", "backups");
+    return [
+        ...tempRoots(deps.tmpDir ?? os.tmpdir()),
+        ...tempRoots(path.join(path.dirname(path.resolve(backupRoot)), "tmp")),
+    ];
+}
+/**
+ * A dangling link HQ may repair. Its current target is under the HQ root,
+ * under the system temp folder, under the rescue staging root beside the
+ * backup root, or has a path segment starting with `hq-replace-rescue-` (the
+ * rescue's mkdtemp folder, wherever it was staged). Anything else is the
+ * user's own link and is left alone.
+ */
+function isRepairableDanglingTarget(hqRoot, current, deps = {}) {
+    const segments = path.resolve(current).split(path.sep);
+    if (segments.some((segment) => segment.startsWith(RESCUE_STAGING_SEGMENT_PREFIX)))
+        return true;
+    const roots = [...tempRoots(path.resolve(hqRoot)), ...rescueStagingRoots(deps)];
+    return roots.some((root) => isUnder(root, current));
+}
 function containedTarget(hqRoot, entry) {
     const destination = path.join(hqRoot, entry.rel);
     const resolved = path.resolve(path.dirname(destination), entry.linkText);
@@ -149,4 +193,146 @@ function readFileOrNull(target) {
         return null;
     }
 }
+/**
+ * Repair HQ-managed release links whose target no longer exists, such as a
+ * `.agents/skills` or `.codex/claude` link an earlier rescue pointed at its
+ * deleted temp extraction folder (feedback_2ab63e50).
+ *
+ * Only the fixed {@link RELEASE_LINKS} paths are considered, and only when the
+ * entry itself is a symlink or junction that does not resolve. A real file or
+ * directory is never touched, a link that resolves anywhere is left alone, and
+ * the link's parent folder must sit inside the HQ root, so a `.agents` folder
+ * that is itself a link out of the tree is skipped.
+ *
+ * Ownership rule: a dangling link is repaired only when its current target is
+ * under the HQ root or under the system temp folder (where a rescue extracts
+ * its staging copy). A dangling link anywhere else, such as `/Volumes/X`, is
+ * the user's own link to a drive that is not mounted; it is left alone and
+ * reported as `skipped`.
+ *
+ * The repaired link carries the text HQ ships (`../.claude/skills`), so the
+ * git-tracked link is unchanged. On Windows a directory link is an absolute
+ * junction and a file link an absolute symlink, falling back to a copy. When
+ * the shipped target is missing too, the dangling link is removed and nothing
+ * is created. The old entry is removed with {@link removeLinkOnly}, which never
+ * follows it. A failure on one link is reported as `failed` and the remaining
+ * links are still repaired.
+ */
+export function repairDanglingReleaseLinks(hqRoot, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    let rootReal;
+    try {
+        rootReal = fs.realpathSync.native(path.resolve(hqRoot));
+    }
+    catch {
+        return [];
+    }
+    const repairs = [];
+    for (const entry of RELEASE_LINKS) {
+        if (deps.only !== undefined && entry.rel !== deps.only)
+            continue;
+        const destination = path.join(rootReal, entry.rel);
+        const lst = lstatOrNull(destination);
+        if (!lst || !lst.isSymbolicLink())
+            continue;
+        if (resolvesOrNull(destination) !== null)
+            continue;
+        const parentReal = resolvesOrNull(path.dirname(destination));
+        if (parentReal === null || !isUnder(rootReal, parentReal))
+            continue;
+        const target = path.resolve(path.dirname(destination), entry.linkText);
+        if (!isUnder(rootReal, target))
+            continue;
+        let current;
+        try {
+            current = path.resolve(path.dirname(destination), fs.readlinkSync(destination));
+        }
+        catch (err) {
+            repairs.push({ rel: entry.rel, action: "failed", reason: errorMessage(err) });
+            continue;
+        }
+        if (!isRepairableDanglingTarget(rootReal, current, { tmpDir: deps.tmpDir, backupRoot: deps.backupRoot })) {
+            repairs.push({
+                rel: entry.rel,
+                action: "skipped",
+                reason: `it points at ${current}, outside the HQ root, so it is left as your own link`,
+            });
+            continue;
+        }
+        const targetStat = statOrNull(target);
+        const targetUsable = targetStat !== null &&
+            (entry.kind === "dir" ? targetStat.isDirectory() : targetStat.isFile()) &&
+            isUnder(rootReal, resolvesOrNull(target) ?? "");
+        try {
+            removeLinkOnly(destination);
+            if (!targetUsable) {
+                repairs.push({ rel: entry.rel, action: "removed" });
+                continue;
+            }
+            const linkText = writeReleaseLink(entry, target, destination, platform);
+            repairs.push({ rel: entry.rel, action: "repointed", target, linkText });
+        }
+        catch (err) {
+            repairs.push({ rel: entry.rel, action: "failed", reason: errorMessage(err) });
+        }
+    }
+    return repairs;
+}
+/** Write the link and return the text it carries. */
+function writeReleaseLink(entry, target, destination, platform) {
+    if (platform !== "win32") {
+        fs.symlinkSync(entry.linkText, destination, entry.kind);
+        return entry.linkText;
+    }
+    if (entry.kind === "dir") {
+        fs.symlinkSync(target, destination, "junction");
+        return target;
+    }
+    try {
+        fs.symlinkSync(target, destination, "file");
+        return target;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EPERM" && code !== "EACCES")
+            throw err;
+        // Windows without the symlink privilege: the check accepts a copy whose
+        // bytes equal the target.
+        fs.copyFileSync(target, destination);
+        return target;
+    }
+}
+function tempRoots(tmpDir) {
+    const roots = [path.resolve(tmpDir)];
+    const real = resolvesOrNull(tmpDir);
+    if (real && !roots.includes(real))
+        roots.push(real);
+    return roots;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isUnder(rootReal, candidate) {
+    if (!candidate)
+        return false;
+    const abs = path.resolve(candidate);
+    const base = rootReal.endsWith(path.sep) ? rootReal.slice(0, -1) : rootReal;
+    return abs === base || abs.startsWith(base + path.sep);
+}
+function resolvesOrNull(target) {
+    try {
+        return fs.realpathSync.native(target);
+    }
+    catch {
+        return null;
+    }
+}
+function statOrNull(target) {
+    try {
+        return fs.statSync(target);
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=release-links.js.map

package/dist/lib/doctor/fix/apply.js

@@ -44,6 +44,7 @@ import { getStateDir } from "@indigoai-us/hq-cloud";
 import { isPersonalJournalSlug } from "../checks/sync-health.js";
 import { createDefaultRegistry } from "../registry.js";
 import { flattenFamilies } from "../report.js";
+import { repairDanglingReleaseLinks } from "../checks/release-links.js";
 import { parseHookGateProfiles, requiredMissingProfiles, } from "../hook-gate-profiles.js";
 import { createBackup } from "./backup.js";
 import { removeStrayGateEntries } from "../stray-gate-entries.js";
@@ -905,6 +906,8 @@ function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultR
             return planRefreshSync(hqRoot, result, rem, refreshSync);
         case "refresh-manifest":
             return planRefreshManifest(hqRoot, result, rem, refreshManifest);
+        case "repair-release-link":
+            return planRepairReleaseLink(hqRoot, result, rem);
         default:
             return null;
     }
@@ -1075,6 +1078,57 @@ function planRefreshManifest(hqRoot, result, rem, refreshManifest) {
         failureReason: () => failureReason,
     };
 }
+/**
+ * Repoint (or remove) one dangling HQ-managed release link. The repair writes
+ * only the link entry, never a hook body, so it needs no backup: a link that
+ * does not resolve has no content to restore.
+ */
+function planRepairReleaseLink(hqRoot, result, rem) {
+    const rel = rem.fixTarget;
+    if (!rel)
+        return null;
+    let failure;
+    return {
+        checkId: result.checkId,
+        fixClass: "repair-release-link",
+        target: rel,
+        relpath: "",
+        preview: `  ${rel}\n` +
+            `    - dangling link\n` +
+            `    + the shipped link to its target under the HQ root (removed if that target is missing)`,
+        summary: `repair dangling link ${rel}`,
+        apply: () => {
+            // Each plan repairs only its own link, and a throw is recorded as this
+            // plan's failure so the remaining plans still run.
+            try {
+                const own = repairDanglingReleaseLinks(hqRoot, { only: rel });
+                const entry = own.find((item) => item.rel === rel);
+                if (!entry) {
+                    failure = `${rel} was not repaired`;
+                }
+                else if (entry.action === "skipped" || entry.action === "failed") {
+                    failure = `${rel} was not repaired: ${entry.reason ?? entry.action}`;
+                }
+                else {
+                    failure = undefined;
+                }
+            }
+            catch (err) {
+                failure = `${rel} was not repaired: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+        postStatus: (results) => {
+            const own = results.filter((entry) => entry.checkId === result.checkId);
+            if (own.some((entry) => entry.target === rel))
+                return "FAIL";
+            // Another link's failure is that plan's status, not this one's.
+            if (own.some((entry) => entry.status === "FAIL"))
+                return "PASS";
+            return own[0]?.status ?? null;
+        },
+        failureReason: () => failure,
+    };
+}
 /** Restore the execute bit on a hook script. */
 function planExecutableBit(hqRoot, result, rem) {
     const abs = rem.fixTarget;

package/dist/lib/doctor/fix/remediation.d.ts

@@ -43,6 +43,13 @@
  *                         hq-cli shim (see `lib/windows/ps1-shims.ts`); the
  *                         execution policy is never changed. This is the one
  *                         scoped exception to the no-delete rule below.
+ *   - `repair-release-link` — repoint an HQ-managed release link
+ *                         (`.agents/skills`, `.codex/claude`, ...) whose target
+ *                         is missing, using the link text HQ ships (absolute junction on Windows).
+ *                         When that target is missing too, the dangling link
+ *                         entry is removed. Only a link that does not resolve
+ *                         is touched; a real file or folder never is, and the
+ *                         link is removed without following it.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -54,7 +61,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "refresh-manifest" | "bot-node-path" | "bot-hq-binary" | "remove-ps1-shims";
+export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "refresh-manifest" | "bot-node-path" | "bot-hq-binary" | "remove-ps1-shims" | "repair-release-link";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle

package/dist/lib/doctor/fix/remediation.js

@@ -43,6 +43,13 @@
  *                         hq-cli shim (see `lib/windows/ps1-shims.ts`); the
  *                         execution policy is never changed. This is the one
  *                         scoped exception to the no-delete rule below.
+ *   - `repair-release-link` — repoint an HQ-managed release link
+ *                         (`.agents/skills`, `.codex/claude`, ...) whose target
+ *                         is missing, using the link text HQ ships (absolute junction on Windows).
+ *                         When that target is missing too, the dangling link
+ *                         entry is removed. Only a link that does not resolve
+ *                         is touched; a real file or folder never is, and the
+ *                         link is removed without following it.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -53,6 +60,7 @@
  * deciding which of two diverged copies is correct needs human judgement.
  */
 import * as path from "node:path";
+import { DANGLING_RELEASE_LINK_PROBLEM, RELEASE_LINKS, RELEASE_LINKS_CHECK_ID, } from "../checks/release-links.js";
 import { isCompanyJournalSlug, isSafeCompanySlug, isPersonalJournalSlug, journalSlugFromCheckId, } from "../checks/sync-health.js";
 /** Matches an exec-bit remediation command, quoted or not: `chmod +x <path>`. */
 const CHMOD_EXEC = /^chmod\s+\+x\s+(.+)$/;
@@ -165,6 +173,20 @@ export function deriveRemediation(result) {
             command: "hq.cmd install --global",
         };
     }
+    // repair-release-link — a shipped link whose target is missing, such as one
+    // a rescue pointed at its deleted temp folder (feedback_2ab63e50).
+    if (checkId === RELEASE_LINKS_CHECK_ID &&
+        result.status === "FAIL" &&
+        RELEASE_LINKS.some((entry) => entry.rel === target) &&
+        result.message.startsWith(target + " " + DANGLING_RELEASE_LINK_PROBLEM)) {
+        return {
+            autoFixable: true,
+            fixClass: "repair-release-link",
+            fixTarget: target,
+            action: `Repoint the dangling ${target} link at its target under the HQ root (or remove the link when that target is missing).`,
+            command: "hq doctor --fix",
+        };
+    }
     // Available hq-core upgrade. WARN is intentional in `hq doctor` and is
     // not a broken sync; --fix has no mechanical repair for it.
     if (checkId === "sync.update.core") {