@indigoai-us/hq-cli 5.345.147 → 5.345.148

package/dist/utils/safe-link.js

@@ -0,0 +1,300 @@
+// src/utils/safe-link.ts
+//
+// Directory links that degrade gracefully on Windows, and link removal that
+// never touches the link target.
+//
+// A plain `fs.symlinkSync` on Windows needs SeCreateSymbolicLinkPrivilege
+// (Developer Mode or an elevated shell). A standard user gets EPERM, which is
+// what broke `hq install --global` on a cold Windows machine. A directory
+// junction needs no privilege, so it is the fallback for directory targets.
+// Node reports a junction as `isSymbolicLink()` and `readlinkSync` returns its
+// absolute target, so code that recognises HQ links keeps working.
+//
+// A junction must point at an absolute path on a local volume. When the target
+// is on a network share, or Windows refuses the junction too, the last resort
+// is a copy of the folder, marked with a `.hq-skill-copy` file that records the
+// source, the entry name and a hash of the copied files. Uninstall removes a
+// skill folder only when it is a link or carries that marker, so a folder the
+// user made by hand is never deleted. A marked copy whose files changed, or
+// whose marker names a different entry, is kept with a printed notice.
+//
+// Removing a junction recursively (`rm -r`, `rmdir /s`, `fs.rmSync(..,
+// { recursive: true })`) can delete the files of the folder it points to. Every
+// HQ path that removes a skill link goes through `removeLinkOnly`, which removes
+// the link entry and nothing else.
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+/** Marker file written into a skill folder that HQ copied instead of linked. */
+export const SKILL_COPY_MARKER = '.hq-skill-copy';
+/** Thrown when Windows refuses a directory symlink, a junction and a copy. */
+export class LinkUnavailableError extends Error {
+    linkPath;
+    expected = true;
+    constructor(linkPath, cause) {
+        super(`Windows refused to create a link at ${linkPath}. ` +
+            'Turn on Developer Mode (Settings > System > For developers) or run from an elevated terminal, then run the command again.', { cause });
+        this.linkPath = linkPath;
+        this.name = 'LinkUnavailableError';
+    }
+}
+const PRIVILEGE_CODES = new Set(['EPERM', 'EACCES']);
+// A junction to a network path fails with EINVAL or ENOTSUP in libuv. EXDEV
+// and the privilege codes cover the other refusals.
+const JUNCTION_REFUSED_CODES = new Set([...PRIVILEGE_CODES, 'EINVAL', 'ENOTSUP', 'EXDEV']);
+function hasCode(err, codes) {
+    const code = err?.code;
+    return typeof code === 'string' && codes.has(code);
+}
+/**
+ * Link `linkPath` to the directory `target`. On Windows a privilege refusal
+ * falls back to a junction (absolute target, no privilege needed), and a
+ * refused junction falls back to a marked copy unless `allowCopy` is false.
+ * Other platforms keep the plain symlink behaviour.
+ */
+export function linkDirectory(target, linkPath, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== 'win32') {
+        fs.symlinkSync(target, linkPath);
+        return 'symlink';
+    }
+    try {
+        fs.symlinkSync(target, linkPath, 'dir');
+        return 'symlink';
+    }
+    catch (err) {
+        if (!hasCode(err, PRIVILEGE_CODES))
+            throw err;
+    }
+    // Junctions require an absolute target; resolve a relative one against the
+    // link's own folder, which is how the symlink would have resolved it.
+    const absolute = path.resolve(path.dirname(linkPath), target);
+    try {
+        fs.symlinkSync(absolute, linkPath, 'junction');
+        return 'junction';
+    }
+    catch (err) {
+        if (!hasCode(err, JUNCTION_REFUSED_CODES))
+            throw err;
+        if (deps.allowCopy === false)
+            throw new LinkUnavailableError(linkPath, err);
+        try {
+            copySkillFolder(absolute, linkPath);
+        }
+        catch (copyErr) {
+            throw new LinkUnavailableError(linkPath, copyErr);
+        }
+        return 'copy';
+    }
+}
+function copySkillFolder(source, dest) {
+    let created = false;
+    try {
+        fs.mkdirSync(dest);
+        created = true;
+        copyTreeDereferenced(source, dest, new Set([fs.realpathSync(source)]));
+        const marker = { source, name: path.basename(dest), hash: skillCopyHash(dest) };
+        fs.writeFileSync(path.join(dest, SKILL_COPY_MARKER), `${JSON.stringify(marker)}\n`);
+    }
+    catch (err) {
+        // Remove the partial copy, but only when this call created the folder.
+        if (created) {
+            try {
+                removeTreeNoFollow(dest);
+            }
+            catch { /* report the copy error */ }
+        }
+        throw err;
+    }
+}
+/**
+ * Copy the contents of `source` into the existing folder `dest`, following
+ * links. `ancestors` holds the real paths of the folders on the current path
+ * from the copy root down to `source`, so only a link back to one of them (a
+ * loop) is skipped. Two links to the same folder, or a link to a sibling
+ * folder, are each copied in full.
+ */
+function copyTreeDereferenced(source, dest, ancestors) {
+    for (const entry of fs.readdirSync(source)) {
+        const from = path.join(source, entry);
+        const to = path.join(dest, entry);
+        const st = fs.statSync(from);
+        if (st.isDirectory()) {
+            const real = fs.realpathSync(from);
+            if (ancestors.has(real))
+                continue;
+            fs.mkdirSync(to);
+            ancestors.add(real);
+            try {
+                copyTreeDereferenced(from, to, ancestors);
+            }
+            finally {
+                ancestors.delete(real);
+            }
+        }
+        else if (st.isFile()) {
+            fs.copyFileSync(from, to, fs.constants.COPYFILE_EXCL);
+        }
+    }
+}
+/**
+ * A sha256 over the names and contents of everything in a skill copy, except
+ * the marker file itself. Links are hashed by their target text, not followed.
+ */
+function skillCopyHash(dir) {
+    const hash = crypto.createHash('sha256');
+    const walk = (rel) => {
+        const abs = rel === '' ? dir : path.join(dir, rel);
+        for (const entry of fs.readdirSync(abs).sort()) {
+            if (rel === '' && entry === SKILL_COPY_MARKER)
+                continue;
+            const childRel = rel === '' ? entry : `${rel}/${entry}`;
+            const child = path.join(abs, entry);
+            const st = fs.lstatSync(child);
+            if (st.isSymbolicLink()) {
+                hash.update(`l:${childRel}\0${fs.readlinkSync(child)}\0`);
+            }
+            else if (st.isDirectory()) {
+                hash.update(`d:${childRel}\0`);
+                walk(childRel);
+            }
+            else {
+                const content = crypto.createHash('sha256').update(fs.readFileSync(child)).digest('hex');
+                hash.update(`f:${childRel}\0${content}\0`);
+            }
+        }
+    };
+    walk('');
+    return hash.digest('hex');
+}
+function readSkillCopyMarker(p) {
+    try {
+        if (!fs.lstatSync(p).isDirectory())
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(path.join(p, SKILL_COPY_MARKER), 'utf-8'));
+        if (typeof parsed.source !== 'string' || parsed.source.length === 0)
+            return null;
+        return {
+            source: parsed.source,
+            name: typeof parsed.name === 'string' ? parsed.name : undefined,
+            hash: typeof parsed.hash === 'string' ? parsed.hash : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The source folder recorded in a skill copy's marker, or null when `p` is
+ * not a real folder carrying a valid marker.
+ */
+export function skillCopySource(p) {
+    return readSkillCopyMarker(p)?.source ?? null;
+}
+/** Delete a real folder tree without following any link inside it. */
+function removeTreeNoFollow(p) {
+    const st = fs.lstatSync(p);
+    if (st.isSymbolicLink()) {
+        removeLinkOnly(p);
+        return;
+    }
+    if (!st.isDirectory()) {
+        fs.unlinkSync(p);
+        return;
+    }
+    for (const entry of fs.readdirSync(p))
+        removeTreeNoFollow(path.join(p, entry));
+    fs.rmdirSync(p);
+}
+/**
+ * Remove an HQ skill entry: a link (never recursing into it) or a folder HQ
+ * copied and marked. Refuses an unmarked real folder. A marked copy is kept,
+ * with a notice through `onKept`, when its marker names a different entry
+ * (the user renamed or duplicated it) or its files changed since HQ copied
+ * them. Returns false when nothing exists at `p` or the copy was kept.
+ */
+export function removeSkillEntry(p, onKept = (line) => console.warn(line)) {
+    let st;
+    try {
+        st = fs.lstatSync(p);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    if (st.isSymbolicLink())
+        return removeLinkOnly(p);
+    const marker = readSkillCopyMarker(p);
+    if (marker === null) {
+        throw new Error(`Refusing to remove ${p}: it is not a link or a skill copy made by HQ.`);
+    }
+    const name = path.basename(p);
+    if (marker.name === undefined || marker.hash === undefined) {
+        onKept(`Kept ${p}: HQ cannot confirm it is an unchanged copy it made. Remove it yourself if you do not need it.`);
+        return false;
+    }
+    if (marker.name !== name) {
+        onKept(`Kept ${p}: HQ made it as ${marker.name}, so it is a renamed or duplicated copy. Remove it yourself if you do not need it.`);
+        return false;
+    }
+    if (skillCopyHash(p) !== marker.hash) {
+        onKept(`Kept ${p}: its files changed since HQ copied them. Remove it yourself when you no longer need the changes.`);
+        return false;
+    }
+    removeTreeNoFollow(p);
+    return true;
+}
+/**
+ * Remove whatever is at `p` without following any link: a link at `p` goes
+ * through `removeLinkOnly`, and a real folder is removed entry by entry so a
+ * link nested inside it is removed as a link. With `force`, a missing path is
+ * not an error.
+ */
+export function removeEntryNoFollow(p, opts = {}) {
+    let st;
+    try {
+        st = fs.lstatSync(p);
+    }
+    catch (err) {
+        if (opts.force && err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    if (st.isSymbolicLink())
+        return removeLinkOnly(p);
+    removeTreeNoFollow(p);
+    return true;
+}
+/**
+ * Remove a symlink or junction without recursing into it. Refuses anything
+ * that is not a link, so a real folder is never deleted through this path.
+ * Returns false when nothing exists at `linkPath`.
+ */
+export function removeLinkOnly(linkPath) {
+    let st;
+    try {
+        st = fs.lstatSync(linkPath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    if (!st.isSymbolicLink()) {
+        throw new Error(`Refusing to remove ${linkPath}: it is not a link.`);
+    }
+    try {
+        fs.unlinkSync(linkPath);
+    }
+    catch (err) {
+        const code = err.code;
+        // Some Windows builds report a directory junction as a directory to
+        // unlink(). A non-recursive rmdir removes only the junction entry.
+        if (code !== 'EPERM' && code !== 'EISDIR')
+            throw err;
+        fs.rmdirSync(linkPath);
+    }
+    return true;
+}
+//# sourceMappingURL=safe-link.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.147",
+  "version": "5.345.148",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -21,7 +21,9 @@
     "CHANGELOG.md",
     "README.md",
     "contracts",
-    "scripts/mesh-daemon-if-stale.mjs"
+    "scripts/mesh-daemon-if-stale.mjs",
+    "scripts/install-hook-engine.mjs",
+    "scripts/hook-engine-manifest.mjs"
   ],
   "scripts": {
     "build": "node scripts/generate-dsn.mjs && node scripts/build-flag-registry-worker.mjs && tsc && node scripts/generate-command-catalog.mjs --check && node scripts/copy-schemas.mjs && node scripts/chmod-bins.mjs && node scripts/bundle-sync-runner.mjs",
@@ -40,15 +42,17 @@
     "check:lanes-module-cycles": "node scripts/check-lanes-module-cycles.mjs",
     "vitest": "vitest",
     "clean": "rm -rf dist",
-    "postinstall": "node scripts/mesh-daemon-if-stale.mjs || true",
+    "postinstall": "node scripts/install-hook-engine.mjs && node scripts/mesh-daemon-if-stale.mjs || node -e \"process.exit(0)\"",
     "prepare": "husky || true",
-    "check:no-hermes": "bash scripts/check-no-hermes.sh"
+    "check:no-hermes": "bash scripts/check-no-hermes.sh",
+    "prepack": "node scripts/hook-engine-manifest.mjs",
+    "postpublish": "node scripts/hook-engine-manifest.mjs restore"
   },
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "~6.18.87",
+    "@indigoai-us/hq-cloud": "~6.18.88",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",
@@ -108,5 +112,13 @@
   },
   "lint-staged": {
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
+  },
+  "optionalDependencies": {
+    "@indigoai-us/hq-hook-win32-x64": "5.345.148",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.148",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.148",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.148",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.148",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.148"
   }
 }

package/scripts/hook-engine-manifest.mjs

@@ -0,0 +1,22 @@
+// The six packages do not exist before the first approved release. Keep source
+// installs reproducible; add exact-version optional dependencies to the tarball.
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from 'node:fs';
+const platforms = ['win32-x64', 'win32-arm64', 'darwin-x64', 'darwin-arm64', 'linux-x64', 'linux-arm64'];
+const backup = '.hook-engine-package-backup.json';
+if (process.argv[2] === 'restore') {
+  if (existsSync(backup)) { writeFileSync('package.json', readFileSync(backup)); unlinkSync(backup); }
+} else {
+  const source = readFileSync('package.json', 'utf8');
+  const pkg = JSON.parse(source);
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(pkg.version)) throw new Error('Invalid package version');
+  // npm publish reads package.json again AFTER postpack. Do not restore it in
+  // postpack or registry metadata loses optionalDependencies. Restore only in
+  // postpublish (or explicitly after a local pack). Repeated smoke packs are safe.
+  // A backup is current only while package.json still carries the stamped deps.
+  // An unstamped package.json means the backup is left over from an earlier
+  // local pack, so replace it rather than restore stale content later.
+  const stamped = platforms.every(p => pkg.optionalDependencies?.[`@indigoai-us/hq-hook-${p}`] === pkg.version);
+  if (!existsSync(backup) || !stamped) writeFileSync(backup, source);
+  pkg.optionalDependencies = { ...pkg.optionalDependencies, ...Object.fromEntries(platforms.map(p => [`@indigoai-us/hq-hook-${p}`, pkg.version])) };
+  writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+}

package/scripts/install-hook-engine.mjs

@@ -0,0 +1,10 @@
+import { existsSync } from 'node:fs';
+// A source checkout has not built dist during pnpm install. Published tarballs
+// never contain src; a broken tarball warns and keeps existing bash hooks active.
+if (!existsSync(new URL('../dist/lib/hook-engine/resolve.js', import.meta.url)) && existsSync(new URL('../src/index.ts', import.meta.url))) process.exit(0);
+try {
+  const { installHookEngine } = await import('../dist/lib/hook-engine/resolve.js');
+  if (!installHookEngine()) throw new Error('Optional platform package missing');
+} catch (error) {
+  console.warn(`HQ native hook engine unavailable: ${error instanceof Error ? error.message : String(error)}. Existing bash hooks remain active. Repair: npm install -g @indigoai-us/hq-cli --include=optional`);
+}