@socketsecurity/lib 0.0.0 → 1.0.0

package/dist/debug.js

@@ -0,0 +1,345 @@
+/* Socket Lib - Built with esbuild */
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var debug_exports = {};
+__export(debug_exports, {
+  debug: () => debug,
+  debugCache: () => debugCache,
+  debugCacheNs: () => debugCacheNs,
+  debugDir: () => debugDir,
+  debugDirNs: () => debugDirNs,
+  debugLog: () => debugLog,
+  debugLogNs: () => debugLogNs,
+  debugNs: () => debugNs,
+  debuglog: () => debuglog,
+  debugtime: () => debugtime,
+  isDebug: () => isDebug,
+  isDebugNs: () => isDebugNs
+});
+module.exports = __toCommonJS(debug_exports);
+var import_process = require("#constants/process");
+var import_debug = require("#env/debug");
+var import_socket_debug = require("#env/socket-debug");
+var import_is_unicode_supported = __toESM(require("./external/@socketregistry/is-unicode-supported"));
+var import_debug2 = __toESM(require("./external/debug"));
+var import_logger = require("./logger");
+var import_objects = require("./objects");
+var import_strings = require("./strings");
+const ReflectApply = Reflect.apply;
+const debugByNamespace = /* @__PURE__ */ new Map();
+// @__NO_SIDE_EFFECTS__
+function getDebugJsInstance(namespace) {
+  let inst = debugByNamespace.get(namespace);
+  if (inst) {
+    return inst;
+  }
+  if (!import_debug.DEBUG && import_socket_debug.SOCKET_DEBUG && (namespace === "error" || namespace === "notice")) {
+    import_debug2.default.enable(namespace);
+  }
+  inst = (0, import_debug2.default)(namespace);
+  inst.log = customLog;
+  debugByNamespace.set(namespace, inst);
+  return inst;
+}
+let _util;
+// @__NO_SIDE_EFFECTS__
+function getUtil() {
+  if (_util === void 0) {
+    _util = require("node:util");
+  }
+  return _util;
+}
+// @__NO_SIDE_EFFECTS__
+function getCallerInfo(stackOffset = 3) {
+  let name = "";
+  const captureStackTrace = Error.captureStackTrace;
+  if (typeof captureStackTrace === "function") {
+    const obj = {};
+    captureStackTrace(obj, getCallerInfo);
+    const stack = obj.stack;
+    if (typeof stack === "string") {
+      let lineCount = 0;
+      let lineStart = 0;
+      for (let i = 0, { length } = stack; i < length; i += 1) {
+        if (stack[i] === "\n") {
+          lineCount += 1;
+          if (lineCount < stackOffset) {
+            lineStart = i + 1;
+          } else {
+            const line = stack.slice(lineStart, i).trimStart();
+            const match = /(?<=^at\s+).*?(?=\s+\(|$)/.exec(line)?.[0];
+            if (match) {
+              name = match.replace(/^(?:async|bound|get|new|set)\s+/, "");
+              if (name.startsWith("Object.")) {
+                const afterDot = name.slice(
+                  7
+                  /*'Object.'.length*/
+                );
+                if (!(0, import_objects.hasOwn)(Object, afterDot)) {
+                  name = afterDot;
+                }
+              }
+            }
+            break;
+          }
+        }
+      }
+    }
+  }
+  return name;
+}
+// @__NO_SIDE_EFFECTS__
+function customLog(...args) {
+  const util = /* @__PURE__ */ getUtil();
+  const inspectOpts = import_debug2.default.inspectOpts ? {
+    ...import_debug2.default.inspectOpts,
+    showHidden: import_debug2.default.inspectOpts.showHidden === null ? void 0 : import_debug2.default.inspectOpts.showHidden,
+    depth: import_debug2.default.inspectOpts.depth === null || typeof import_debug2.default.inspectOpts.depth === "boolean" ? void 0 : import_debug2.default.inspectOpts.depth
+  } : {};
+  ReflectApply(import_logger.logger.info, import_logger.logger, [
+    util.formatWithOptions(inspectOpts, ...args)
+  ]);
+}
+// @__NO_SIDE_EFFECTS__
+function extractOptions(namespaces) {
+  return namespaces !== null && typeof namespaces === "object" ? { __proto__: null, ...namespaces } : { __proto__: null, namespaces };
+}
+// @__NO_SIDE_EFFECTS__
+function isEnabled(namespaces) {
+  if (!import_socket_debug.SOCKET_DEBUG) {
+    return false;
+  }
+  if (typeof namespaces !== "string" || !namespaces || namespaces === "*") {
+    return true;
+  }
+  const split = namespaces.trim().replace(/\s+/g, ",").split(",").filter(Boolean);
+  const names = [];
+  const skips = [];
+  for (const ns of split) {
+    if (ns.startsWith("-")) {
+      skips.push(ns.slice(1));
+    } else {
+      names.push(ns);
+    }
+  }
+  if (names.length && !names.some((ns) => (/* @__PURE__ */ getDebugJsInstance(ns)).enabled)) {
+    return false;
+  }
+  return skips.every((ns) => !(/* @__PURE__ */ getDebugJsInstance(ns)).enabled);
+}
+// @__NO_SIDE_EFFECTS__
+function debugDirNs(namespacesOrOpts, obj, inspectOpts) {
+  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
+  const { namespaces } = options;
+  if (!/* @__PURE__ */ isEnabled(namespaces)) {
+    return;
+  }
+  const callerName = /* @__PURE__ */ getCallerInfo(4) || "anonymous";
+  if (pointingTriangle === void 0) {
+    const supported = (0, import_is_unicode_supported.default)();
+    pointingTriangle = supported ? "\u25B8" : ">";
+  }
+  let opts = inspectOpts;
+  if (opts === void 0) {
+    const debugOpts = import_debug2.default.inspectOpts;
+    if (debugOpts) {
+      opts = {
+        ...debugOpts,
+        showHidden: debugOpts.showHidden === null ? void 0 : debugOpts.showHidden,
+        depth: debugOpts.depth === null || typeof debugOpts.depth === "boolean" ? null : debugOpts.depth
+      };
+    }
+  }
+  const spinnerInstance = options.spinner || (0, import_process.getSpinner)();
+  const wasSpinning = spinnerInstance?.isSpinning;
+  spinnerInstance?.stop();
+  import_logger.logger.info(`[DEBUG] ${callerName} ${pointingTriangle} object inspection:`);
+  import_logger.logger.dir(obj, inspectOpts);
+  if (wasSpinning) {
+    spinnerInstance?.start();
+  }
+}
+let pointingTriangle;
+// @__NO_SIDE_EFFECTS__
+function debugNs(namespacesOrOpts, ...args) {
+  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
+  const { namespaces } = options;
+  if (!/* @__PURE__ */ isEnabled(namespaces)) {
+    return;
+  }
+  const name = /* @__PURE__ */ getCallerInfo(4) || "anonymous";
+  if (pointingTriangle === void 0) {
+    const supported = (0, import_is_unicode_supported.default)();
+    pointingTriangle = supported ? "\u25B8" : ">";
+  }
+  const text = args.at(0);
+  const logArgs = typeof text === "string" ? [
+    (0, import_strings.applyLinePrefix)(
+      `${name ? `${name} ${pointingTriangle} ` : ""}${text}`,
+      { prefix: "[DEBUG] " }
+    ),
+    ...args.slice(1)
+  ] : args;
+  const spinnerInstance = options.spinner || (0, import_process.getSpinner)();
+  const wasSpinning = spinnerInstance?.isSpinning;
+  spinnerInstance?.stop();
+  ReflectApply(import_logger.logger.info, import_logger.logger, logArgs);
+  if (wasSpinning) {
+    spinnerInstance?.start();
+  }
+}
+// @__NO_SIDE_EFFECTS__
+function debugLogNs(namespacesOrOpts, ...args) {
+  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
+  const { namespaces } = options;
+  if (!/* @__PURE__ */ isEnabled(namespaces)) {
+    return;
+  }
+  const callerName = /* @__PURE__ */ getCallerInfo(4) || "anonymous";
+  if (pointingTriangle === void 0) {
+    const supported = (0, import_is_unicode_supported.default)();
+    pointingTriangle = supported ? "\u25B8" : ">";
+  }
+  const text = args.at(0);
+  const logArgs = typeof text === "string" ? [
+    (0, import_strings.applyLinePrefix)(
+      `${callerName ? `${callerName} ${pointingTriangle} ` : ""}${text}`,
+      { prefix: "[DEBUG] " }
+    ),
+    ...args.slice(1)
+  ] : [`[DEBUG] ${callerName} ${pointingTriangle}`, ...args];
+  const spinnerInstance = options.spinner || (0, import_process.getSpinner)();
+  const wasSpinning = spinnerInstance?.isSpinning;
+  spinnerInstance?.stop();
+  ReflectApply(import_logger.logger.info, import_logger.logger, logArgs);
+  if (wasSpinning) {
+    spinnerInstance?.start();
+  }
+}
+// @__NO_SIDE_EFFECTS__
+function debugCacheNs(namespacesOrOpts, operation, key, meta) {
+  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
+  const { namespaces } = options;
+  if (!/* @__PURE__ */ isEnabled(namespaces)) {
+    return;
+  }
+  const callerName = /* @__PURE__ */ getCallerInfo(4) || "cache";
+  if (pointingTriangle === void 0) {
+    const supported = (0, import_is_unicode_supported.default)();
+    pointingTriangle = supported ? "\u25B8" : ">";
+  }
+  const prefix = `[CACHE] ${callerName} ${pointingTriangle} ${operation}: ${key}`;
+  const logArgs = meta !== void 0 ? [prefix, meta] : [prefix];
+  const spinnerInstance = options.spinner || (0, import_process.getSpinner)();
+  const wasSpinning = spinnerInstance?.isSpinning;
+  spinnerInstance?.stop();
+  ReflectApply(import_logger.logger.info, import_logger.logger, logArgs);
+  if (wasSpinning) {
+    spinnerInstance?.start();
+  }
+}
+// @__NO_SIDE_EFFECTS__
+function debugCache(operation, key, meta) {
+  if (!import_socket_debug.SOCKET_DEBUG) {
+    return;
+  }
+  const callerName = /* @__PURE__ */ getCallerInfo(3) || "cache";
+  if (pointingTriangle === void 0) {
+    const supported = (0, import_is_unicode_supported.default)();
+    pointingTriangle = supported ? "\u25B8" : ">";
+  }
+  const prefix = `[CACHE] ${callerName} ${pointingTriangle} ${operation}: ${key}`;
+  const args = meta !== void 0 ? [prefix, meta] : [prefix];
+  console.log(...args);
+}
+// @__NO_SIDE_EFFECTS__
+function isDebugNs(namespaces) {
+  return !!import_socket_debug.SOCKET_DEBUG && /* @__PURE__ */ isEnabled(namespaces);
+}
+// @__NO_SIDE_EFFECTS__
+function debug(...args) {
+  /* @__PURE__ */ debugNs("*", ...args);
+}
+// @__NO_SIDE_EFFECTS__
+function debugDir(obj, inspectOpts) {
+  /* @__PURE__ */ debugDirNs("*", obj, inspectOpts);
+}
+// @__NO_SIDE_EFFECTS__
+function debugLog(...args) {
+  /* @__PURE__ */ debugLogNs("*", ...args);
+}
+// @__NO_SIDE_EFFECTS__
+function isDebug() {
+  return !!import_socket_debug.SOCKET_DEBUG;
+}
+// @__NO_SIDE_EFFECTS__
+function debuglog(section) {
+  const util = /* @__PURE__ */ getUtil();
+  return util.debuglog(section);
+}
+// @__NO_SIDE_EFFECTS__
+function debugtime(label) {
+  const util = /* @__PURE__ */ getUtil();
+  let startTime;
+  const impl = () => {
+    if (startTime === void 0) {
+      startTime = Date.now();
+    } else {
+      const duration = Date.now() - startTime;
+      util.debuglog("time")(`${label}: ${duration}ms`);
+      startTime = void 0;
+    }
+  };
+  impl.start = () => {
+    startTime = Date.now();
+  };
+  impl.end = () => {
+    if (startTime !== void 0) {
+      const duration = Date.now() - startTime;
+      util.debuglog("time")(`${label}: ${duration}ms`);
+      startTime = void 0;
+    }
+  };
+  return impl;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  debug,
+  debugCache,
+  debugCacheNs,
+  debugDir,
+  debugDirNs,
+  debugLog,
+  debugLogNs,
+  debugNs,
+  debuglog,
+  debugtime,
+  isDebug,
+  isDebugNs
+});
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/debug.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Debug logging utilities with lazy loading and environment-based control.\n * Provides Socket CLI specific debug functionality and logging formatters.\n */\n\nimport { getSpinner } from '#constants/process'\nimport { DEBUG } from '#env/debug'\nimport { SOCKET_DEBUG } from '#env/socket-debug'\nimport isUnicodeSupported from './external/@socketregistry/is-unicode-supported'\nimport debugJs from './external/debug'\n\nimport { logger } from './logger'\nimport { hasOwn } from './objects'\nimport { applyLinePrefix } from './strings'\n\n// IMPORTANT: Do not use destructuring here - use direct assignment instead.\n// tsgo has a bug that incorrectly transpiles destructured exports, resulting in\n// `exports.SomeName = void 0;` which causes runtime errors.\n// See: https://github.com/SocketDev/socket-packageurl-js/issues/3\nconst ReflectApply = Reflect.apply\n\n// Type definitions\ninterface DebugOptions {\n  namespaces?: string\n  spinner?: { isSpinning: boolean; stop(): void; start(): void }\n  [key: string]: unknown\n}\n\ntype NamespacesOrOptions = string | DebugOptions\n\ninterface InspectOptions {\n  depth?: number | null\n  colors?: boolean\n  [key: string]: unknown\n}\n\nexport type { DebugOptions, NamespacesOrOptions, InspectOptions }\n\nconst debugByNamespace = new Map()\n/**\n * Get or create a debug instance for a namespace.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getDebugJsInstance(namespace: string) {\n  let inst = debugByNamespace.get(namespace)\n  if (inst) {\n    return inst\n  }\n  if (\n    !DEBUG &&\n    SOCKET_DEBUG &&\n    (namespace === 'error' || namespace === 'notice')\n  ) {\n    debugJs.enable(namespace)\n  }\n  inst = debugJs(namespace)\n  inst.log = customLog\n  debugByNamespace.set(namespace, inst)\n  return inst\n}\n\nlet _util: typeof import('util') | undefined\n/**\n * Lazily load the util module.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getUtil() {\n  if (_util === undefined) {\n    // Use non-'node:' prefixed require to avoid Webpack errors.\n\n    _util = /*@__PURE__*/ require('node:util')\n  }\n  return _util as typeof import('util')\n}\n\n/**\n * Extract caller information from the stack trace.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getCallerInfo(stackOffset: number = 3): string {\n  let name = ''\n  const captureStackTrace = Error.captureStackTrace\n  if (typeof captureStackTrace === 'function') {\n    const obj: { stack?: unknown } = {}\n    captureStackTrace(obj, getCallerInfo)\n    const stack = obj.stack\n    if (typeof stack === 'string') {\n      let lineCount = 0\n      let lineStart = 0\n      for (let i = 0, { length } = stack; i < length; i += 1) {\n        if (stack[i] === '\\n') {\n          lineCount += 1\n          if (lineCount < stackOffset) {\n            // Store the start index of the next line.\n            lineStart = i + 1\n          } else {\n            // Extract the full line and trim it.\n            const line = stack.slice(lineStart, i).trimStart()\n            // Match the function name portion (e.g., \"async runFix\").\n            const match = /(?<=^at\\s+).*?(?=\\s+\\(|$)/.exec(line)?.[0]\n            if (match) {\n              name = match\n                // Strip known V8 invocation prefixes to get the name.\n                .replace(/^(?:async|bound|get|new|set)\\s+/, '')\n              if (name.startsWith('Object.')) {\n                // Strip leading 'Object.' if not an own property of Object.\n                const afterDot = name.slice(7 /*'Object.'.length*/)\n                if (!hasOwn(Object, afterDot)) {\n                  name = afterDot\n                }\n              }\n            }\n            break\n          }\n        }\n      }\n    }\n  }\n  return name\n}\n\n/**\n * Custom log function for debug output.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction customLog(...args: unknown[]) {\n  const util = getUtil()\n  const inspectOpts = debugJs.inspectOpts\n    ? {\n        ...debugJs.inspectOpts,\n        showHidden:\n          debugJs.inspectOpts.showHidden === null\n            ? undefined\n            : debugJs.inspectOpts.showHidden,\n        depth:\n          debugJs.inspectOpts.depth === null ||\n          typeof debugJs.inspectOpts.depth === 'boolean'\n            ? undefined\n            : debugJs.inspectOpts.depth,\n      }\n    : {}\n  ReflectApply(logger.info, logger, [\n    util.formatWithOptions(inspectOpts, ...args),\n  ])\n}\n\n/**\n * Extract options from namespaces parameter.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction extractOptions(namespaces: NamespacesOrOptions): DebugOptions {\n  return namespaces !== null && typeof namespaces === 'object'\n    ? ({ __proto__: null, ...namespaces } as DebugOptions)\n    : ({ __proto__: null, namespaces } as DebugOptions)\n}\n\n/**\n * Check if debug is enabled for given namespaces.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction isEnabled(namespaces: string | undefined) {\n  // Check if debugging is enabled at all\n  if (!SOCKET_DEBUG) {\n    return false\n  }\n  if (typeof namespaces !== 'string' || !namespaces || namespaces === '*') {\n    return true\n  }\n  // Namespace splitting logic is based the 'debug' package implementation:\n  // https://github.com/debug-js/debug/blob/4.4.1/src/common.js#L169-L173.\n  const split = namespaces\n    .trim()\n    .replace(/\\s+/g, ',')\n    .split(',')\n    .filter(Boolean)\n  const names = []\n  const skips = []\n  for (const ns of split) {\n    if (ns.startsWith('-')) {\n      skips.push(ns.slice(1))\n    } else {\n      names.push(ns)\n    }\n  }\n  if (names.length && !names.some(ns => getDebugJsInstance(ns).enabled)) {\n    return false\n  }\n  return skips.every(ns => !getDebugJsInstance(ns).enabled)\n}\n\n/**\n * Debug output for object inspection with caller info.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debugDirNs(\n  namespacesOrOpts: NamespacesOrOptions,\n  obj: unknown,\n  inspectOpts?: InspectOptions | undefined,\n) {\n  const options = extractOptions(namespacesOrOpts)\n  const { namespaces } = options\n  if (!isEnabled(namespaces as string)) {\n    return\n  }\n  // Get caller info with stack offset of 4 (caller -> debugDirNs -> getCallerInfo).\n  const callerName = getCallerInfo(4) || 'anonymous'\n\n  if (pointingTriangle === undefined) {\n    const supported = isUnicodeSupported()\n    pointingTriangle = supported ? '\u25B8' : '>'\n  }\n\n  let opts: InspectOptions | undefined = inspectOpts\n  if (opts === undefined) {\n    const debugOpts = debugJs.inspectOpts\n    if (debugOpts) {\n      opts = {\n        ...debugOpts,\n        showHidden:\n          debugOpts.showHidden === null ? undefined : debugOpts.showHidden,\n        depth:\n          debugOpts.depth === null || typeof debugOpts.depth === 'boolean'\n            ? null\n            : debugOpts.depth,\n      } as InspectOptions\n    }\n  }\n  const spinnerInstance = options.spinner || getSpinner()\n  const wasSpinning = spinnerInstance?.isSpinning\n  spinnerInstance?.stop()\n  logger.info(`[DEBUG] ${callerName} ${pointingTriangle} object inspection:`)\n  logger.dir(obj, inspectOpts)\n  if (wasSpinning) {\n    spinnerInstance?.start()\n  }\n}\n\nlet pointingTriangle: string | undefined\n/**\n * Debug output with caller info.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debugNs(namespacesOrOpts: NamespacesOrOptions, ...args: unknown[]) {\n  const options = extractOptions(namespacesOrOpts)\n  const { namespaces } = options\n  if (!isEnabled(namespaces as string)) {\n    return\n  }\n  // Get caller info with stack offset of 4 (caller -> debugNs -> getCallerInfo).\n  const name = getCallerInfo(4) || 'anonymous'\n  if (pointingTriangle === undefined) {\n    const supported = isUnicodeSupported()\n    pointingTriangle = supported ? '\u25B8' : '>'\n  }\n  const text = args.at(0)\n  const logArgs =\n    typeof text === 'string'\n      ? [\n          applyLinePrefix(\n            `${name ? `${name} ${pointingTriangle} ` : ''}${text}`,\n            { prefix: '[DEBUG] ' },\n          ),\n          ...args.slice(1),\n        ]\n      : args\n  const spinnerInstance = options.spinner || getSpinner()\n  const wasSpinning = spinnerInstance?.isSpinning\n  spinnerInstance?.stop()\n  ReflectApply(logger.info, logger, logArgs)\n  if (wasSpinning) {\n    spinnerInstance?.start()\n  }\n}\n\n/**\n * Debug logging function with caller info.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debugLogNs(namespacesOrOpts: NamespacesOrOptions, ...args: unknown[]) {\n  const options = extractOptions(namespacesOrOpts)\n  const { namespaces } = options\n  if (!isEnabled(namespaces as string)) {\n    return\n  }\n  // Get caller info with stack offset of 4 (caller -> debugLogNs -> getCallerInfo).\n  const callerName = getCallerInfo(4) || 'anonymous'\n\n  if (pointingTriangle === undefined) {\n    const supported = isUnicodeSupported()\n    pointingTriangle = supported ? '\u25B8' : '>'\n  }\n\n  const text = args.at(0)\n  const logArgs =\n    typeof text === 'string'\n      ? [\n          applyLinePrefix(\n            `${callerName ? `${callerName} ${pointingTriangle} ` : ''}${text}`,\n            { prefix: '[DEBUG] ' },\n          ),\n          ...args.slice(1),\n        ]\n      : [`[DEBUG] ${callerName} ${pointingTriangle}`, ...args]\n\n  const spinnerInstance = options.spinner || getSpinner()\n  const wasSpinning = spinnerInstance?.isSpinning\n  spinnerInstance?.stop()\n  ReflectApply(logger.info, logger, logArgs)\n  if (wasSpinning) {\n    spinnerInstance?.start()\n  }\n}\n\n/**\n * Debug output for cache operations with caller info.\n * First argument is the operation type (hit/miss/set/clear).\n * Second argument is the cache key or message.\n * Optional third argument is metadata object.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debugCacheNs(\n  namespacesOrOpts: NamespacesOrOptions,\n  operation: string,\n  key: string,\n  meta?: unknown | undefined,\n) {\n  const options = extractOptions(namespacesOrOpts)\n  const { namespaces } = options\n  if (!isEnabled(namespaces as string)) {\n    return\n  }\n  // Get caller info with stack offset of 4 (caller -> debugCacheNs -> getCallerInfo).\n  const callerName = getCallerInfo(4) || 'cache'\n\n  if (pointingTriangle === undefined) {\n    const supported = isUnicodeSupported()\n    pointingTriangle = supported ? '\u25B8' : '>'\n  }\n\n  const prefix = `[CACHE] ${callerName} ${pointingTriangle} ${operation}: ${key}`\n  const logArgs = meta !== undefined ? [prefix, meta] : [prefix]\n\n  const spinnerInstance = options.spinner || getSpinner()\n  const wasSpinning = spinnerInstance?.isSpinning\n  spinnerInstance?.stop()\n  ReflectApply(logger.info, logger, logArgs)\n  if (wasSpinning) {\n    spinnerInstance?.start()\n  }\n}\n\n/**\n * Cache debug function with caller info.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function debugCache(\n  operation: string,\n  key: string,\n  meta?: unknown | undefined,\n): void {\n  if (!SOCKET_DEBUG) {\n    return\n  }\n  // Get caller info with stack offset of 3 (caller -> debugCache -> getCallerInfo).\n  const callerName = getCallerInfo(3) || 'cache'\n\n  if (pointingTriangle === undefined) {\n    const supported = isUnicodeSupported()\n    pointingTriangle = supported ? '\u25B8' : '>'\n  }\n\n  const prefix = `[CACHE] ${callerName} ${pointingTriangle} ${operation}: ${key}`\n  const args = meta !== undefined ? [prefix, meta] : [prefix]\n  console.log(...args)\n}\n\n/**\n * Check if debug mode is enabled.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction isDebugNs(namespaces: string | undefined): boolean {\n  return !!SOCKET_DEBUG && isEnabled(namespaces)\n}\n\n/**\n * Debug output with caller info (wrapper for debugNs with default namespace).\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debug(...args: unknown[]): void {\n  debugNs('*', ...args)\n}\n\n/**\n * Debug output for object inspection (wrapper for debugDirNs with default namespace).\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debugDir(\n  obj: unknown,\n  inspectOpts?: InspectOptions | undefined,\n): void {\n  debugDirNs('*', obj, inspectOpts)\n}\n\n/**\n * Debug logging function (wrapper for debugLogNs with default namespace).\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debugLog(...args: unknown[]): void {\n  debugLogNs('*', ...args)\n}\n\n/**\n * Check if debug mode is enabled.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction isDebug(): boolean {\n  return !!SOCKET_DEBUG\n}\n\n/**\n * Create a Node.js util.debuglog compatible function.\n * Returns a function that conditionally writes debug messages to stderr.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debuglog(section: string) {\n  const util = getUtil()\n  return util.debuglog(section)\n}\n\n/**\n * Create timing functions for measuring code execution time.\n * Returns an object with start() and end() methods, plus a callable function.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction debugtime(label: string) {\n  const util = getUtil()\n  // Node.js util doesn't have debugtime - create a custom implementation\n  let startTime: number | undefined\n  const impl = () => {\n    if (startTime === undefined) {\n      startTime = Date.now()\n    } else {\n      const duration = Date.now() - startTime\n      util.debuglog('time')(`${label}: ${duration}ms`)\n      startTime = undefined\n    }\n  }\n  impl.start = () => {\n    startTime = Date.now()\n  }\n  impl.end = () => {\n    if (startTime !== undefined) {\n      const duration = Date.now() - startTime\n      util.debuglog('time')(`${label}: ${duration}ms`)\n      startTime = undefined\n    }\n  }\n  return impl\n}\n\n// Export main debug functions with caller info.\nexport { debug }\n// debugCache is already exported directly above\nexport { debugCacheNs }\nexport { debugDir }\nexport { debugDirNs }\nexport { debugLog }\nexport { debuglog }\nexport { debugLogNs }\nexport { debugNs }\nexport { debugtime }\nexport { isDebug }\nexport { isDebugNs }\n"],
+  "mappings": "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",
+  "names": ["import_debug", "debugJs", "isUnicodeSupported"]
+}

package/dist/dlx-binary.d.ts

@@ -0,0 +1,49 @@
+import type { SpawnExtra, SpawnOptions } from './spawn';
+import { spawn } from './spawn';
+export interface DlxBinaryOptions {
+    /** URL to download the binary from. */
+    url: string;
+    /** Optional name for the cached binary (defaults to URL hash). */
+    name?: string | undefined;
+    /** Expected checksum (sha256) for verification. */
+    checksum?: string | undefined;
+    /** Cache TTL in milliseconds (default: 7 days). */
+    cacheTtl?: number | undefined;
+    /** Force re-download even if cached. */
+    force?: boolean | undefined;
+    /** Additional spawn options. */
+    spawnOptions?: SpawnOptions | undefined;
+}
+export interface DlxBinaryResult {
+    /** Path to the cached binary. */
+    binaryPath: string;
+    /** Whether the binary was newly downloaded. */
+    downloaded: boolean;
+    /** The spawn promise for the running process. */
+    spawnPromise: ReturnType<typeof spawn>;
+}
+/**
+ * Clean expired entries from the DLX cache.
+ */
+export declare function cleanDlxCache(maxAge?: number): Promise<number>;
+/**
+ * Download and execute a binary from a URL with caching.
+ */
+export declare function dlxBinary(args: readonly string[] | string[], options?: DlxBinaryOptions | undefined, spawnExtra?: SpawnExtra | undefined): Promise<DlxBinaryResult>;
+/**
+ * Get the DLX binary cache directory path.
+ * Returns normalized path for cross-platform compatibility.
+ */
+export declare function getDlxCachePath(): string;
+/**
+ * Get information about cached binaries.
+ */
+export declare function listDlxCache(): Promise<Array<{
+    age: number;
+    arch: string;
+    checksum: string;
+    name: string;
+    platform: string;
+    size: number;
+    url: string;
+}>>;