@indigoai-us/hq-cli 5.345.147 → 5.345.148

package/dist/utils/copy-tree.js

@@ -0,0 +1,249 @@
+/**
+ * copy-tree: portable replacement for the `rsync -a` copies on the pack
+ * install path.
+ *
+ * Pack installs used to shell out to `rsync`, which Windows does not ship, so
+ * every git-subpath or local-directory install failed there with
+ * `spawnSync rsync ENOENT`. This module does the same copy in Node on every
+ * platform:
+ *
+ *   - `copyTree(src, dest)` copies the CONTENTS of `src` into `dest` (the
+ *     `rsync -a src/ dest/` trailing-slash form). Directories recurse, regular
+ *     files keep their permission bits and mtimes, and symlinks are recreated
+ *     as symlinks with the identical target string. Links are never followed.
+ *     Optional `exclude` names match an entry's basename at any depth, like
+ *     `rsync --exclude=<name>`. Sockets, FIFOs and devices are skipped with a
+ *     warning, as a non-root `rsync -a` does.
+ *   - `removeTreeNoFollow(target)` deletes a tree without ever following a
+ *     symlink or junction inside it: each entry is lstat'd, links are removed
+ *     as links (unlink, or a non-recursive rmdir for a Windows junction), and
+ *     directories are emptied then removed with a non-recursive rmdir. A
+ *     Windows directory that is a reparse point but not a link (a volume mount
+ *     point, a cloud-synced placeholder folder) stops the removal with
+ *     `ReparsePointError`; its contents are never deleted.
+ *
+ * On Windows, creating a symlink needs Developer Mode or an elevated shell.
+ * When that fails with EPERM/EACCES and the link points at a directory inside
+ * the tree being copied, the copy falls back to a junction (no privilege
+ * needed). A junction needs an absolute target, so it points at the matching
+ * entry under `finalRoot`: the path the copy will live at once the caller has
+ * renamed it into place. Any other link target throws `CopyTreeLinkError` with
+ * a Developer Mode hint instead of silently dropping the link.
+ *
+ * TODO(windows-links): src/utils/safe-link.ts (PR 1967, branch
+ * fix/windows-install-path-daemon) adds its own junction fallback and
+ * link-only removal. Whichever of the two PRs merges second should reconcile
+ * these helpers into one module.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class CopyTreeLinkError extends Error {
+    constructor(linkPath, target, cause) {
+        super(`Could not create the symlink ${linkPath} -> ${target} (${cause.code ?? cause.message}). ` +
+            'Windows only lets elevated shells create symlinks unless Developer Mode is on. ' +
+            'Turn on Developer Mode (Settings > System > For developers) or run the install from an elevated terminal, then retry.');
+        this.name = 'CopyTreeLinkError';
+    }
+}
+export class ReparsePointError extends Error {
+    constructor(dir) {
+        super(`Refusing to delete ${dir}: it is a Windows reparse point (such as a volume mount point or a cloud-synced ` +
+            'placeholder folder), not a plain folder or link. Deleting through it could remove files stored elsewhere. ' +
+            'Unmount or remove it by hand, then retry.');
+        this.name = 'ReparsePointError';
+    }
+}
+export function copyTree(src, dest, opts = {}) {
+    const exclude = new Set(opts.exclude ?? []);
+    const srcRoot = path.resolve(src);
+    const destRoot = path.resolve(dest);
+    const finalRoot = path.resolve(opts.finalRoot ?? dest);
+    const rootStat = fs.statSync(srcRoot);
+    if (!rootStat.isDirectory()) {
+        throw new Error(`copyTree source is not a directory: ${srcRoot}`);
+    }
+    fs.mkdirSync(destRoot, { recursive: true });
+    copyDirContents(srcRoot, destRoot, { srcRoot, finalRoot, exclude });
+    applyMetadata(destRoot, rootStat);
+}
+function copyDirContents(srcDir, destDir, ctx) {
+    for (const name of fs.readdirSync(srcDir)) {
+        if (ctx.exclude.has(name))
+            continue;
+        const srcPath = path.join(srcDir, name);
+        const destPath = path.join(destDir, name);
+        const st = fs.lstatSync(srcPath);
+        if (st.isSymbolicLink()) {
+            copyLink(srcPath, destPath, ctx);
+        }
+        else if (st.isDirectory()) {
+            fs.mkdirSync(destPath, { recursive: true });
+            copyDirContents(srcPath, destPath, ctx);
+            // Children are written first, so the directory's own mtime and mode are
+            // set last and stay equal to the source.
+            applyMetadata(destPath, st);
+        }
+        else if (st.isFile()) {
+            fs.copyFileSync(srcPath, destPath);
+            applyMetadata(destPath, st);
+        }
+        else {
+            process.stderr.write(`hq: skipping special file ${srcPath} (not a file, directory or symlink)\n`);
+        }
+    }
+}
+function applyMetadata(target, st) {
+    fs.chmodSync(target, st.mode & 0o7777);
+    fs.utimesSync(target, st.atime, st.mtime);
+}
+function copyLink(srcPath, destPath, ctx) {
+    const target = fs.readlinkSync(srcPath);
+    const resolved = path.resolve(path.dirname(srcPath), target);
+    const targetIsDir = isDirectory(resolved);
+    try {
+        fs.symlinkSync(target, destPath, targetIsDir ? 'dir' : 'file');
+    }
+    catch (err) {
+        const e = err;
+        if (process.platform !== 'win32' || (e.code !== 'EPERM' && e.code !== 'EACCES'))
+            throw e;
+        if (!targetIsDir || !isInside(ctx.srcRoot, resolved)) {
+            throw new CopyTreeLinkError(destPath, target, e);
+        }
+        // A junction needs an absolute target. Point it at the same directory in
+        // the copy as it will be after the caller's final rename, so the junction
+        // stays inside the installed tree and does not dangle once a staging dir
+        // is renamed. Windows creates a junction to a path that does not exist
+        // yet, so nothing is created here: the target appears when the copy
+        // reaches it, and a target under an excluded name stays absent, as the
+        // link would dangle after `rsync --exclude`.
+        const junctionTarget = path.join(ctx.finalRoot, path.relative(ctx.srcRoot, resolved));
+        fs.symlinkSync(junctionTarget, destPath, 'junction');
+    }
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isInside(root, candidate) {
+    const rel = path.relative(root, candidate);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/**
+ * Remove `target` and everything under it without following links. A missing
+ * target is not an error. If `target` itself is a link, only the link goes.
+ */
+export function removeTreeNoFollow(target) {
+    removeEntry(target, () => listedAsLink(target));
+}
+/**
+ * `listedAsLink` reports whether the directory listing marks the entry as a
+ * link. On Windows Node marks every entry with FILE_ATTRIBUTE_REPARSE_POINT
+ * that way, while lstat reports only symlinks and junctions as links. A
+ * directory that lstat calls a directory but the listing calls a link is a
+ * reparse point of another kind, such as a volume mount point or a cloud
+ * placeholder. Elsewhere the two always agree.
+ */
+function removeEntry(target, listedAsLink) {
+    let st;
+    try {
+        st = fs.lstatSync(target);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (st.isSymbolicLink()) {
+        removeLinkOnly(target);
+        return;
+    }
+    if (st.isDirectory()) {
+        if (listedAsLink())
+            throw new ReparsePointError(target);
+        for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+            removeEntry(path.join(target, entry.name), () => entry.isSymbolicLink());
+        }
+        fs.rmdirSync(target);
+        return;
+    }
+    try {
+        fs.unlinkSync(target);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'EPERM' && code !== 'EACCES')
+            throw err;
+        if (process.platform === 'win32') {
+            // Windows refuses to delete a file with the read-only attribute, which a
+            // copied 0o444 file carries. Clear it on the file itself (not a link,
+            // checked above) and retry once.
+            retryWithMode(target, 0o666, () => fs.unlinkSync(target));
+        }
+        else {
+            // On POSIX the right to unlink comes from the parent folder, which a
+            // copied 0o555 folder lacks. Give its owner write access and retry once.
+            const parent = path.dirname(target);
+            retryWithMode(parent, (fs.statSync(parent).mode & 0o7777) | 0o700, () => fs.unlinkSync(target), true);
+        }
+    }
+}
+/**
+ * Set `p` to `mode`, run `op` once, and put the original mode back if `op`
+ * throws, or always when `alwaysRestore` is set.
+ */
+function retryWithMode(p, mode, op, alwaysRestore = false) {
+    const original = fs.statSync(p).mode & 0o7777;
+    fs.chmodSync(p, mode);
+    let ok = false;
+    try {
+        op();
+        ok = true;
+    }
+    finally {
+        if (!ok || alwaysRestore) {
+            try {
+                fs.chmodSync(p, original);
+            }
+            catch {
+                // The retry's own error, or its success, is what the caller needs.
+            }
+        }
+    }
+}
+function listedAsLink(target) {
+    const parent = path.dirname(target);
+    if (parent === target)
+        return false;
+    const name = path.basename(target);
+    let entries;
+    try {
+        entries = fs.readdirSync(parent, { withFileTypes: true });
+    }
+    catch (err) {
+        // A parent that cannot be listed gives no listing to compare against.
+        // Each child is still checked against its own listing during the walk.
+        if (err.code === 'EACCES' || err.code === 'EPERM')
+            return false;
+        throw err;
+    }
+    return entries.some((e) => e.name === name && e.isSymbolicLink());
+}
+function removeLinkOnly(linkPath) {
+    try {
+        fs.unlinkSync(linkPath);
+    }
+    catch (err) {
+        const code = err.code;
+        // Windows directory symlinks and junctions can refuse unlink. A
+        // non-recursive rmdir removes the link entry and never touches the target.
+        if (code !== 'EPERM' && code !== 'EISDIR' && code !== 'EACCES')
+            throw err;
+        fs.rmdirSync(linkPath);
+    }
+}
+//# sourceMappingURL=copy-tree.js.map

package/dist/utils/environmental-error.js

@@ -262,9 +262,13 @@ export function filesystemErrorMessage(err) {
     const safePath = redactedPath(details.rawPath);
     const synced = syncedFolder(resolvedPath);
     const permissionDenied = details.code === "EACCES" || details.code === "EPERM";
-    const remedy = permissionDenied && process.platform !== "win32" && synced === "none"
-        ? "Check file and folder permissions, close the file, then retry."
-        : "Close the file or exclude its folder from cloud sync; if it persists, check permissions, then retry.";
+    // Windows refuses symlinks without SeCreateSymbolicLinkPrivilege; that is a
+    // privilege problem, not a locked or cloud-synced file.
+    const remedy = permissionDenied && process.platform === "win32" && details.syscall === "symlink"
+        ? "Windows needs Developer Mode (Settings > System > For developers) or an elevated terminal to create links; turn one on, then retry."
+        : permissionDenied && process.platform !== "win32" && synced === "none"
+            ? "Check file and folder permissions, close the file, then retry."
+            : "Close the file or exclude its folder from cloud sync; if it persists, check permissions, then retry.";
     return `Filesystem operation ${details.syscall} failed (${details.code}) at ${safePath}. ${remedy}`;
 }
 //# sourceMappingURL=environmental-error.js.map

package/dist/utils/npm-invocation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * npm-invocation: run npm without a shell on every platform.
+ *
+ * On Windows `npm` is a `npm.cmd` batch shim. `execFileSync('npm', ...)`
+ * cannot find it (ENOENT), and since Node's CVE-2024-27980 fix a `.cmd` file
+ * only runs through a shell, which would re-parse caller-supplied arguments
+ * such as a pack source. Instead, on Windows this resolves npm's JavaScript
+ * entry (`node_modules/npm/bin/npm-cli.js`, the file the shim itself runs)
+ * and launches it with the current Node binary as a plain argv array.
+ *
+ * Elsewhere `npm` is an executable on PATH and is used as is.
+ */
+export interface NpmInvocation {
+    command: string;
+    args: string[];
+}
+export interface NpmInvocationEnv {
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    env?: NodeJS.ProcessEnv;
+    exists?: (file: string) => boolean;
+}
+export declare class NpmNotFoundError extends Error {
+    constructor(searched: string[]);
+}
+export declare function npmInvocation(args: readonly string[], ctx?: NpmInvocationEnv): NpmInvocation;
+//# sourceMappingURL=npm-invocation.d.ts.map

package/dist/utils/npm-invocation.js

@@ -0,0 +1,54 @@
+/**
+ * npm-invocation: run npm without a shell on every platform.
+ *
+ * On Windows `npm` is a `npm.cmd` batch shim. `execFileSync('npm', ...)`
+ * cannot find it (ENOENT), and since Node's CVE-2024-27980 fix a `.cmd` file
+ * only runs through a shell, which would re-parse caller-supplied arguments
+ * such as a pack source. Instead, on Windows this resolves npm's JavaScript
+ * entry (`node_modules/npm/bin/npm-cli.js`, the file the shim itself runs)
+ * and launches it with the current Node binary as a plain argv array.
+ *
+ * Elsewhere `npm` is an executable on PATH and is used as is.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class NpmNotFoundError extends Error {
+    constructor(searched) {
+        super('Could not find npm. Looked for npm-cli.js at: ' +
+            (searched.length > 0 ? searched.join(', ') : '(no candidate locations)') +
+            '. Install Node.js with npm, or make sure npm.cmd is on PATH, then retry.');
+        this.name = 'NpmNotFoundError';
+    }
+}
+export function npmInvocation(args, ctx = {}) {
+    const platform = ctx.platform ?? process.platform;
+    if (platform !== 'win32')
+        return { command: 'npm', args: [...args] };
+    const execPath = ctx.execPath ?? process.execPath;
+    const env = ctx.env ?? process.env;
+    const exists = ctx.exists ?? ((file) => fs.existsSync(file));
+    const win = path.win32;
+    const cliUnder = (dir) => win.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    // Prefer the npm the user's shell would run, so an npm installed or
+    // upgraded on its own (`npm i -g npm`, a version manager) wins over the
+    // copy bundled with node.exe.
+    const candidates = [];
+    // Set when hq itself runs under an npm script.
+    const npmExecPath = env.npm_execpath;
+    if (npmExecPath && win.basename(npmExecPath).toLowerCase() === 'npm-cli.js')
+        candidates.push(npmExecPath);
+    // The first npm.cmd shim on PATH, followed to the npm-cli.js beside it.
+    const pathValue = env.Path ?? env.PATH ?? '';
+    for (const dir of pathValue.split(';').filter(Boolean)) {
+        if (exists(win.join(dir, 'npm.cmd')))
+            candidates.push(cliUnder(dir));
+    }
+    // Fallback: the Node.js installer, nvm-windows and fnm put npm next to
+    // node.exe.
+    candidates.push(cliUnder(win.dirname(execPath)));
+    const cli = candidates.find((candidate) => exists(candidate));
+    if (!cli)
+        throw new NpmNotFoundError(candidates);
+    return { command: execPath, args: [cli, ...args] };
+}
+//# sourceMappingURL=npm-invocation.js.map

package/dist/utils/safe-link.d.ts

@@ -0,0 +1,50 @@
+export type LinkKind = 'symlink' | 'junction' | 'copy';
+export interface LinkDeps {
+    platform?: NodeJS.Platform;
+    /** Copy the folder when Windows refuses both link types. Default true. */
+    allowCopy?: boolean;
+}
+/** Marker file written into a skill folder that HQ copied instead of linked. */
+export declare const SKILL_COPY_MARKER = ".hq-skill-copy";
+/** Thrown when Windows refuses a directory symlink, a junction and a copy. */
+export declare class LinkUnavailableError extends Error {
+    readonly linkPath: string;
+    readonly expected: true;
+    constructor(linkPath: string, cause: unknown);
+}
+/**
+ * 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 declare function linkDirectory(target: string, linkPath: string, deps?: LinkDeps): LinkKind;
+/**
+ * The source folder recorded in a skill copy's marker, or null when `p` is
+ * not a real folder carrying a valid marker.
+ */
+export declare function skillCopySource(p: string): string | null;
+/**
+ * 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 declare function removeSkillEntry(p: string, onKept?: (line: string) => void): boolean;
+/**
+ * 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 declare function removeEntryNoFollow(p: string, opts?: {
+    force?: boolean;
+}): boolean;
+/**
+ * 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 declare function removeLinkOnly(linkPath: string): boolean;
+//# sourceMappingURL=safe-link.d.ts.map