@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/dlx/lockfile.d.ts

@@ -1,31 +1,28 @@
 /**
- * @fileoverview Package pin generation for dlx installs.
- *
- * `generatePackagePin` resolves an npm package against the registry
- * using Arborist's lockfile-only mode and fetches its top-level tarball
- * to return both hash formats plus the lockfile content — everything
- * needed to vendor a reproducible install.
- *
- * The `LockfileSpec` type is also exported here for use as the
- * `lockfile` option on `downloadPackage`. Sniff/write handling lives
- * inline in `./package.ts` — no helper.
+ * @file Package pin generation for dlx installs. `generatePackagePin` resolves
+ *   an npm package against the registry using Arborist's lockfile-only mode and
+ *   fetches its top-level tarball to return both hash formats plus the lockfile
+ *   content — everything needed to vendor a reproducible install. The
+ *   `LockfileSpec` type is also exported here for use as the `lockfile` option
+ *   on `downloadPackage`. Sniff/write handling lives inline in `./package.ts` —
+ *   no helper.
  */
-import type { ComputedHashes } from './integrity';
+import type { ComputedHashes } from '../integrity';
 /**
  * Lockfile source for the `lockfile` option on `downloadPackage`.
  *
- * Bare strings are sniffed: a leading `{` (after whitespace) means
- * JSON content, anything else is treated as a filesystem path. Pass the
- * explicit `{ type, value }` form to override sniffing.
+ * Bare strings are sniffed: a leading `{` (after whitespace) means JSON
+ * content, anything else is treated as a filesystem path. Pass the explicit `{
+ * type, value }` form to override sniffing.
  *
  * @example
- * // Sniffed as path:
- * './scripts/dlx/claude/package-lock.json'
- * // Sniffed as content:
- * '{ "lockfileVersion": 3, ... }'
- * // Explicit:
- * { type: 'path', value: '/abs/package-lock.json' }
- * { type: 'content', value: '{ ... }' }
+ *   // Sniffed as path:
+ *   './scripts/dlx/claude/package-lock.json'
+ *   // Sniffed as content:
+ *   '{ "lockfileVersion": 3, ... }'
+ *   // Explicit:
+ *   { type: 'path', value: '/abs/package-lock.json' }
+ *   { type: 'content', value: '{ ... }' }
  */
 export type LockfileSpec = string | {
     type: 'path';
@@ -35,30 +32,31 @@ export type LockfileSpec = string | {
     value: string;
 };
 /**
- * Default minimum release age in days applied when a caller passes
- * neither `minReleaseDays` nor `minReleaseMins`. Pass `minReleaseDays: 0`
- * to disable the cutoff explicitly.
+ * Default minimum release age in days applied when a caller passes neither
+ * `minReleaseDays` nor `minReleaseMins`. Pass `minReleaseDays: 0` to disable
+ * the cutoff explicitly.
  */
 export declare const DEFAULT_MIN_RELEASE_DAYS = 7;
 /**
  * Options for generating a vendorable pin for an npm package.
  */
 export interface GeneratePackagePinOptions {
-    /** Package spec, e.g. `'@anthropic-ai/claude-code@2.1.92'`. */
+    /**
+     * Package spec, e.g. `'@anthropic-ai/claude-code@2.1.92'`.
+     */
     package: string;
     /**
-     * Minimum release age in days. Refuses to resolve any version (direct
-     * or transitive) published more recently than `Date.now() - N days`.
+     * Minimum release age in days. Refuses to resolve any version (direct or
+     * transitive) published more recently than `Date.now() - N days`.
      *
-     * Matches npm's `min-release-age` config (unit: days). Mutually
-     * exclusive with {@link minReleaseMins}. Defaults to
-     * {@link DEFAULT_MIN_RELEASE_DAYS} (7) when neither field is set.
-     * Pass `0` to disable.
+     * Matches npm's `min-release-age` config (unit: days). Mutually exclusive
+     * with {@link minReleaseMins}. Defaults to {@link DEFAULT_MIN_RELEASE_DAYS}
+     * (7) when neither field is set. Pass `0` to disable.
      */
     minReleaseDays?: number | undefined;
     /**
-     * Minimum release age in minutes. Refuses to resolve any version
-     * published more recently than `Date.now() - N minutes`.
+     * Minimum release age in minutes. Refuses to resolve any version published
+     * more recently than `Date.now() - N minutes`.
      *
      * Matches pnpm's `minimumReleaseAge` config (unit: minutes). Mutually
      * exclusive with {@link minReleaseDays}.
@@ -66,24 +64,34 @@ export interface GeneratePackagePinOptions {
     minReleaseMins?: number | undefined;
 }
 /**
- * Result of {@link generatePackagePin}. All file data is returned as
- * content — the caller decides whether/where to write it.
+ * Result of {@link generatePackagePin}. All file data is returned as content —
+ * the caller decides whether/where to write it.
  */
 export interface PinDetails {
-    /** Resolved package name. */
+    /**
+     * Resolved package name.
+     */
     name: string;
-    /** Resolved package version. */
+    /**
+     * Resolved package version.
+     */
     version: string;
-    /** Both hash formats of the top-level tarball. */
+    /**
+     * Both hash formats of the top-level tarball.
+     */
     hash: ComputedHashes;
-    /** `package.json` JSON content, ready to write to disk. */
+    /**
+     * `package.json` JSON content, ready to write to disk.
+     */
     packageJson: string;
-    /** `package-lock.json` JSON content, ready to write to disk. */
+    /**
+     * `package-lock.json` JSON content, ready to write to disk.
+     */
     lockfile: string;
 }
 /**
- * Thrown when a lockfile spec is malformed (unrecognized string, missing
- * file, invalid JSON) or drifts from its package.json.
+ * Thrown when a lockfile spec is malformed (unrecognized string, missing file,
+ * invalid JSON) or drifts from its package.json.
  */
 export declare class DlxLockfileError extends Error {
     constructor(message: string, options?: {
@@ -94,22 +102,31 @@ export declare class DlxLockfileError extends Error {
  * Generate a vendorable pin for an npm package without installing it.
  *
  * Runs Arborist in lockfile-only mode (`packageLockOnly: true`) against a
- * temporary directory, fetches the top-level tarball once to compute
- * sha256 hex (since Arborist only exposes SRI from the registry), then
- * tears the tmp directory down before returning.
+ * temporary directory, fetches the top-level tarball once to compute sha256 hex
+ * (since Arborist only exposes SRI from the registry), then tears the tmp
+ * directory down before returning.
  *
- * The result contains everything a caller needs to pin the package for
- * future installs: the exact resolved name/version, both hash formats,
- * and the lockfile content (ready to commit).
+ * The result contains everything a caller needs to pin the package for future
+ * installs: the exact resolved name/version, both hash formats, and the
+ * lockfile content (ready to commit).
  *
  * @example
- * ```ts
- * const pin = await generatePackagePin({
- *   package: '@anthropic-ai/claude-code@2.1.92',
- * })
- * await fs.writeFile('./claude.lock.json', pin.lockfile, 'utf8')
- * // pin.hash.integrity → 'sha512-…'
- * // pin.hash.checksum  → hex
- * ```
+ *   ;```ts
+ *   const pin = await generatePackagePin({
+ *     package: '@anthropic-ai/claude-code@2.1.92',
+ *   })
+ *   await fs.writeFile('./claude.lock.json', pin.lockfile, 'utf8')
+ *   // pin.hash.integrity → 'sha512-…'
+ *   // pin.hash.checksum  → hex
+ *   ```
  */
 export declare function generatePackagePin(options: GeneratePackagePinOptions): Promise<PinDetails>;
+/**
+ * Extract the package name from a spec like `'name@range'` or
+ * `'@scope/name@range'` or a bare `'name'`.
+ */
+export declare function specName(spec: string): string;
+/**
+ * Extract the version range (or `'latest'`) from a spec.
+ */
+export declare function specRange(spec: string): string;

package/dist/dlx/lockfile.js

@@ -32,31 +32,21 @@ var lockfile_exports = {};
 __export(lockfile_exports, {
   DEFAULT_MIN_RELEASE_DAYS: () => DEFAULT_MIN_RELEASE_DAYS,
   DlxLockfileError: () => DlxLockfileError,
-  generatePackagePin: () => generatePackagePin
+  generatePackagePin: () => generatePackagePin,
+  specName: () => specName,
+  specRange: () => specRange
 });
 module.exports = __toCommonJS(lockfile_exports);
-var import_node_os = require("node:os");
+var import_node_os = __toESM(require("node:os"));
 var import_pacote = __toESM(require("../external/pacote"));
-var import_fs = require("../fs");
+var import_safe = require("../fs/safe");
 var import_arborist = require("./arborist");
-var import_integrity = require("./integrity");
-var import_primordials = require("../primordials");
-let _fs;
-// @__NO_SIDE_EFFECTS__
-function getFs() {
-  if (_fs === void 0) {
-    _fs = require("node:fs");
-  }
-  return _fs;
-}
-let _path;
-// @__NO_SIDE_EFFECTS__
-function getPath() {
-  if (_path === void 0) {
-    _path = require("node:path");
-  }
-  return _path;
-}
+var import_integrity = require("../integrity");
+var import_date = require("../primordials/date");
+var import_json = require("../primordials/json");
+var import_string = require("../primordials/string");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
 const DEFAULT_MIN_RELEASE_DAYS = 7;
 class DlxLockfileError extends Error {
   constructor(message, options) {
@@ -64,23 +54,9 @@ class DlxLockfileError extends Error {
     this.name = "DlxLockfileError";
   }
 }
-function specName(spec) {
-  const atIdx = (0, import_primordials.StringPrototypeLastIndexOf)(spec, "@");
-  if (atIdx <= 0) {
-    return spec;
-  }
-  return (0, import_primordials.StringPrototypeSlice)(spec, 0, atIdx);
-}
-function specRange(spec) {
-  const atIdx = (0, import_primordials.StringPrototypeLastIndexOf)(spec, "@");
-  if (atIdx <= 0) {
-    return "latest";
-  }
-  return (0, import_primordials.StringPrototypeSlice)(spec, atIdx + 1) || "latest";
-}
 async function generatePackagePin(options) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
   const { minReleaseDays, minReleaseMins, package: spec } = options;
   if (typeof spec !== "string" || spec.length === 0) {
     throw new DlxLockfileError("generatePackagePin requires a package spec");
@@ -92,21 +68,21 @@ async function generatePackagePin(options) {
   }
   const effectiveDays = minReleaseDays !== void 0 ? minReleaseDays : minReleaseMins !== void 0 ? void 0 : DEFAULT_MIN_RELEASE_DAYS;
   const ageMs = effectiveDays !== void 0 ? effectiveDays * 864e5 : minReleaseMins !== void 0 ? minReleaseMins * 6e4 : 0;
-  const before = ageMs > 0 ? new import_primordials.DateCtor((0, import_primordials.DateNow)() - ageMs) : void 0;
+  const before = ageMs > 0 ? new import_date.DateCtor((0, import_date.DateNow)() - ageMs) : void 0;
   const scratch = path.join(
-    (0, import_node_os.tmpdir)(),
+    import_node_os.default.tmpdir(),
     `socket-lib-pin-${process.pid}-${Date.now()}`
   );
-  await (0, import_fs.safeMkdir)(scratch, { recursive: true });
+  await (0, import_safe.safeMkdir)(scratch, { recursive: true });
   try {
-    const packageJson = (0, import_primordials.JSONStringify)(
+    const packageJson = (0, import_json.JSONStringify)(
       {
         name: "socket-lib-pin",
         version: "0.0.0",
         private: true,
         dependencies: { [specName(spec)]: specRange(spec) }
       },
-      null,
+      void 0,
       2
     );
     await fs.promises.writeFile(
@@ -130,14 +106,30 @@ async function generatePackagePin(options) {
     };
   } finally {
     try {
-      await (0, import_fs.safeDelete)(scratch, { force: true });
+      await (0, import_safe.safeDelete)(scratch, { force: true });
     } catch {
     }
   }
 }
+function specName(spec) {
+  const atIdx = (0, import_string.StringPrototypeLastIndexOf)(spec, "@");
+  if (atIdx <= 0) {
+    return spec;
+  }
+  return (0, import_string.StringPrototypeSlice)(spec, 0, atIdx);
+}
+function specRange(spec) {
+  const atIdx = (0, import_string.StringPrototypeLastIndexOf)(spec, "@");
+  if (atIdx <= 0) {
+    return "latest";
+  }
+  return (0, import_string.StringPrototypeSlice)(spec, atIdx + 1) || "latest";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_MIN_RELEASE_DAYS,
   DlxLockfileError,
-  generatePackagePin
+  generatePackagePin,
+  specName,
+  specRange
 });

package/dist/dlx/manifest.d.ts

@@ -1,34 +1,26 @@
 /**
- * @fileoverview DLX manifest storage utilities.
- * Manages persistent caching of DLX package and binary metadata with TTL support
- * and atomic file operations.
+ * @file DLX manifest storage utilities. Manages persistent caching of DLX
+ *   package and binary metadata with TTL support and atomic file operations.
+ *   Primary API (on {@link DlxManifest}):
  *
- * Primary API (on {@link DlxManifest}):
- * - `getManifestEntry(spec)` — retrieve a manifest entry by spec
- * - `setPackageEntry(spec, key, details)` — store npm package metadata
- * - `setBinaryEntry(spec, key, details)` — store binary download metadata
- * - `getAllPackages()` — enumerate cached package names
- * - `clear(name)` / `clearAll()` — eviction
- * - `isFresh(record, ttlMs)` — TTL check
- *
- * The bare `get(name)` / `set(name, record)` methods are deprecated
- * legacy shims kept for backward compatibility with pre-5.x callers.
- *
- * Features:
- * - TTL-based cache expiration
- * - Atomic file operations with locking
- * - JSON-based persistent storage
- * - Error-resistant implementation
- *
- * Storage Format:
- * - Stores in ~/.socket/_dlx/.dlx-manifest.json
- * - Per-spec manifest entries with timestamps
- * - Thread-safe operations using process lock utility
- *
- * Usage:
- * - Update check caching
- * - Binary metadata tracking
- * - Rate limiting registry requests
+ *   - `getManifestEntry(spec)` — retrieve a manifest entry by spec
+ *   - `setPackageEntry(spec, key, details)` — store npm package metadata
+ *   - `setBinaryEntry(spec, key, details)` — store binary download metadata
+ *   - `getAllPackages()` — enumerate cached package names
+ *   - `clear(name)` / `clearAll()` — eviction
+ *   - `isFresh(record, ttlMs)` — TTL check The bare `get(name)` / `set(name,
+ *     record)` methods are deprecated legacy shims kept for backward
+ *     compatibility with pre-5.x callers. Features:
+ *   - TTL-based cache expiration
+ *   - Atomic file operations with locking
+ *   - JSON-based persistent storage
+ *   - Error-resistant implementation Storage Format:
+ *   - Stores in ~/.socket/_dlx/.dlx-manifest.json
+ *   - Per-spec manifest entries with timestamps
+ *   - Thread-safe operations using process lock utility Usage:
+ *   - Update check caching
+ *   - Binary metadata tracking
+ *   - Rate limiting registry requests
  */
 /**
  * Details for npm package entries.
@@ -46,7 +38,9 @@ export interface PackageDetails {
  * Details for binary download entries.
  */
 export interface BinaryDetails {
-    /** SRI integrity hash (sha512-<base64>, aligned with npm). */
+    /**
+     * SRI integrity hash (sha512-<base64>, aligned with npm).
+     */
     integrity: string;
     platform: string;
     arch: string;
@@ -56,7 +50,9 @@ export interface BinaryDetails {
         url?: string;
         path?: string;
     };
-    /** Update check metadata (same structure as packages). */
+    /**
+     * Update check metadata (same structure as packages).
+     */
     update_check?: {
         last_check: number;
         last_notification: number;
@@ -64,10 +60,10 @@ export interface BinaryDetails {
     };
 }
 /**
- * Unified manifest entry for all cached items (packages and binaries).
- * Shared fields at root, type-specific fields in details.
+ * Unified manifest entry for all cached items (packages and binaries). Shared
+ * fields at root, type-specific fields in details.
  */
-export interface ManifestEntry {
+export interface DlxManifestEntry {
     type: 'package' | 'binary';
     cache_key: string;
     timestamp: number;
@@ -91,33 +87,33 @@ export interface DlxManifestOptions {
  * Type guard for binary entries.
  *
  * @example
- * ```typescript
- * const entry = manifest.getManifestEntry('https://example.com/tool')
- * if (entry && isBinaryEntry(entry)) {
- *   console.log(entry.details.integrity)
- * }
- * ```
+ *   ;```typescript
+ *   const entry = manifest.getManifestEntry('https://example.com/tool')
+ *   if (entry && isBinaryEntry(entry)) {
+ *     console.log(entry.details.integrity)
+ *   }
+ *   ```
  */
-export declare function isBinaryEntry(entry: ManifestEntry): entry is ManifestEntry & {
+export declare function isBinaryEntry(entry: DlxManifestEntry): entry is DlxManifestEntry & {
     details: BinaryDetails;
 };
 /**
  * Type guard for package entries.
  *
  * @example
- * ```typescript
- * const entry = manifest.getManifestEntry('@socketsecurity/cli@^2.0.0')
- * if (entry && isPackageEntry(entry)) {
- *   console.log(entry.details.installed_version)
- * }
- * ```
+ *   ;```typescript
+ *   const entry = manifest.getManifestEntry('@socketsecurity/cli@^2.0.0')
+ *   if (entry && isPackageEntry(entry)) {
+ *     console.log(entry.details.installed_version)
+ *   }
+ *   ```
  */
-export declare function isPackageEntry(entry: ManifestEntry): entry is ManifestEntry & {
+export declare function isPackageEntry(entry: DlxManifestEntry): entry is DlxManifestEntry & {
     details: PackageDetails;
 };
 /**
- * DLX manifest storage manager with atomic operations.
- * Supports both legacy format (package name keys) and new unified manifest format (spec keys).
+ * DLX manifest storage manager with atomic operations. Supports both legacy
+ * format (package name keys) and new unified manifest format (spec keys).
  */
 export declare class DlxManifest {
     private readonly manifestPath;
@@ -125,6 +121,7 @@ export declare class DlxManifest {
     constructor(options?: DlxManifestOptions);
     /**
      * Read the entire manifest file.
+     *
      * @private
      */
     private readManifest;
@@ -139,6 +136,7 @@ export declare class DlxManifest {
     clearAll(): Promise<void>;
     /**
      * Get cached update information for a package (legacy format).
+     *
      * @deprecated Use getManifestEntry() for new code.
      */
     get(name: string): StoreRecord | undefined;
@@ -149,13 +147,14 @@ export declare class DlxManifest {
     /**
      * Get a manifest entry by spec (e.g., "@socketsecurity/cli@^2.0.11").
      */
-    getManifestEntry(spec: string): ManifestEntry | undefined;
+    getManifestEntry(spec: string): DlxManifestEntry | undefined;
     /**
      * Check if cached data is fresh based on TTL.
      */
     isFresh(record: StoreRecord | undefined, ttlMs: number): boolean;
     /**
      * Store update information for a package (legacy format).
+     *
      * @deprecated Use setPackageEntry() for new code.
      */
     set(name: string, record: StoreRecord): Promise<void>;