@mawesome/npm-vm 0.0.0-alpha.0 → 0.1.0

package/dist/index-B071ZJDk.d.cts

@@ -0,0 +1,164 @@
+//#region src/own-npm.d.ts
+/** The npm in the active Node's prefix: bundled, or whatever `npm i -g npm@x` put there. */
+interface OwnNpm {
+  root: string;
+  version: string;
+  cliPath: string;
+  npxCliPath: string;
+}
+//#endregion
+//#region src/spec.d.ts
+type HashAlgorithm = "sha512" | "sha256" | "sha224";
+interface SpecHash {
+  algorithm: HashAlgorithm;
+  hex: string;
+}
+/** One npm version requirement: a range, or an exact version optionally pinned to a tarball hash. */
+interface NpmSpec {
+  /** The range as written, without any hash suffix. */
+  range: string;
+  /** Set when the range is a single exact version. */
+  exact: string | null;
+  hash: SpecHash | null;
+}
+type OnFail = "ignore" | "warn" | "error" | "download";
+type SpecField = "devEngines" | "packageManager";
+interface ParsedSpecs {
+  /** Alternatives: Node's own npm or a candidate satisfies the project when it matches any of them. */
+  specs: NpmSpec[];
+  /** The policy of the last `devEngines.packageManager` entry (spec RES-7); `error` for `packageManager`. */
+  onFail: OnFail;
+  field: SpecField;
+}
+declare class SpecError extends Error {
+  override name: string;
+  readonly field: string;
+  /** The project's policy for this failure, when the entry declaring it could still be read. */
+  onFail: OnFail;
+  constructor(field: string, message: string);
+}
+/**
+ * Validates one version string before it reaches a transport argv or a message (spec RES-4).
+ * Build metadata other than a well-formed hash suffix is rejected: semver would silently drop it.
+ */
+declare function parseVersionSpec(raw: string, field: string): NpmSpec;
+/**
+ * Reads the npm requirements of a parsed `package.json` (spec RES-4).
+ * Returns null when the project declares nothing for npm, including when it declares only pnpm or yarn.
+ */
+declare function parseSpecs(pkg: unknown): ParsedSpecs | null;
+//#endregion
+//#region src/select.d.ts
+interface RegistrySignature {
+  keyid: string;
+  sig: string;
+}
+/** A published npm version as the registry or the cache describes it. */
+interface Candidate {
+  version: string;
+  /** `engines.node` of the package; missing means any Node. */
+  enginesNode: string | null;
+  /** `dist.integrity` (sha512 SRI). */
+  integrity: string;
+  /** Where the candidate lives when it is already cached. */
+  entryPath: string | null;
+  /** `dist.signatures` from the registry; null for a cached candidate. */
+  signatures: RegistrySignature[] | null;
+  /** For a cached entry: the key that verified it, or null when only a project's pin did. */
+  keyid?: string | null;
+  /** For a cached entry: the tarball digests recorded at verification, so a pin can be judged without the bytes. */
+  digests?: {
+    sha256: string;
+    sha224: string;
+  } | null;
+}
+interface Selection {
+  candidate: Candidate;
+  /** Pins from the specs that selected the candidate; the download must match one of them. Empty: unpinned. */
+  hashes: SpecHash[];
+}
+type SelectFailure = {
+  kind: "engine";
+  version: string;
+  enginesNode: string;
+} | {
+  kind: "nomatch";
+  reason: string;
+};
+type SelectResult = {
+  kind: "selected";
+  selection: Selection;
+} | {
+  kind: "failed";
+  failure: SelectFailure;
+};
+/** The hex digest of a `sha512-<base64>` SRI string, or null for any other form. */
+declare function sriHex(integrity: string): string | null;
+/**
+ * Picks the highest candidate matching any spec and the active Node (spec RES-6), cached first.
+ * Returns the reason when nothing fits, distinguishing an `engines.node` exclusion from no match at all.
+ */
+declare function selectCandidate(specs: readonly NpmSpec[], candidates: readonly Candidate[], nodeVersion: string): SelectResult;
+//#endregion
+//#region src/errors.d.ts
+/** Exit codes of `npm-vm` itself and of the shim before npm starts (spec section 10). */
+declare const EXIT: {
+  readonly ok: 0;
+  readonly problems: 1;
+  readonly partial: 2;
+  readonly resolution: 3;
+  readonly transport: 4;
+  readonly verification: 5;
+  readonly abi: 6;
+  readonly usage: 64;
+};
+type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** A failure with a message id from spec section 12 and the exit code it maps to. */
+declare class NpmVmError extends Error {
+  override name: string;
+  readonly id: string;
+  readonly exitCode: ExitCode;
+  constructor(id: string, exitCode: ExitCode, message: string);
+}
+declare function isNpmVmError(error: unknown): error is NpmVmError;
+//#endregion
+//#region src/index.d.ts
+interface ResolveSource {
+  file: string;
+  field: "devEngines" | "packageManager" | "env";
+}
+interface ResolveResult {
+  kind: "own" | "cached" | "download";
+  version: string;
+  /** Absolute path to `bin/npm-cli.js`; for a download, the path the entry will have once fetched. */
+  cliPath: string;
+  source: ResolveSource | null;
+  projectRoot: string | null;
+  /** Set for `cached` and `download`: what to fetch or verify. */
+  selection: Selection | null;
+  /** The project's npm requirements, when it declares any. */
+  specs: NpmSpec[] | null;
+  /** A warning to print on stderr before running Node's own npm (`onFail: warn`). */
+  warning: string | null;
+}
+interface ResolveOptions {
+  env?: NodeJS.ProcessEnv;
+  offline?: boolean;
+  /** The npm-vm home holding the cache namespace; defaults to `NPM_VM_HOME` or the platform location. */
+  home?: string;
+}
+/** The lookups resolution depends on; the install layer provides the real ones. */
+interface ResolveProviders {
+  ownNpm(): OwnNpm | null;
+  cached(specs: readonly NpmSpec[]): Promise<Candidate[]>;
+  registry(specs: readonly NpmSpec[]): Promise<Candidate[]>;
+  nodeVersion: string;
+  /** Path a download will occupy, so callers can report it before fetching. */
+  entryPathFor(candidate: Candidate): string;
+}
+/** Resolves the npm to run for `argv` in `cwd` (spec section 5); writes only under the cache, spawns npm only as the transport. */
+declare function resolveNpm(argv: readonly string[], cwd: string, options?: ResolveOptions): Promise<ResolveResult>;
+declare function resolveNpmWith(argv: readonly string[], cwd: string, options: ResolveOptions, providers: ResolveProviders): Promise<ResolveResult>;
+//#endregion
+export { ParsedSpecs as _, resolveNpm as a, parseVersionSpec as b, NpmVmError as c, RegistrySignature as d, Selection as f, OnFail as g, NpmSpec as h, ResolveSource as i, isNpmVmError as l, sriHex as m, ResolveProviders as n, resolveNpmWith as o, selectCandidate as p, ResolveResult as r, EXIT as s, ResolveOptions as t, Candidate as u, SpecError as v, OwnNpm as x, parseSpecs as y };
+//# sourceMappingURL=index-B071ZJDk.d.cts.map

package/dist/index-B071ZJDk.d.ts

@@ -0,0 +1,164 @@
+//#region src/own-npm.d.ts
+/** The npm in the active Node's prefix: bundled, or whatever `npm i -g npm@x` put there. */
+interface OwnNpm {
+  root: string;
+  version: string;
+  cliPath: string;
+  npxCliPath: string;
+}
+//#endregion
+//#region src/spec.d.ts
+type HashAlgorithm = "sha512" | "sha256" | "sha224";
+interface SpecHash {
+  algorithm: HashAlgorithm;
+  hex: string;
+}
+/** One npm version requirement: a range, or an exact version optionally pinned to a tarball hash. */
+interface NpmSpec {
+  /** The range as written, without any hash suffix. */
+  range: string;
+  /** Set when the range is a single exact version. */
+  exact: string | null;
+  hash: SpecHash | null;
+}
+type OnFail = "ignore" | "warn" | "error" | "download";
+type SpecField = "devEngines" | "packageManager";
+interface ParsedSpecs {
+  /** Alternatives: Node's own npm or a candidate satisfies the project when it matches any of them. */
+  specs: NpmSpec[];
+  /** The policy of the last `devEngines.packageManager` entry (spec RES-7); `error` for `packageManager`. */
+  onFail: OnFail;
+  field: SpecField;
+}
+declare class SpecError extends Error {
+  override name: string;
+  readonly field: string;
+  /** The project's policy for this failure, when the entry declaring it could still be read. */
+  onFail: OnFail;
+  constructor(field: string, message: string);
+}
+/**
+ * Validates one version string before it reaches a transport argv or a message (spec RES-4).
+ * Build metadata other than a well-formed hash suffix is rejected: semver would silently drop it.
+ */
+declare function parseVersionSpec(raw: string, field: string): NpmSpec;
+/**
+ * Reads the npm requirements of a parsed `package.json` (spec RES-4).
+ * Returns null when the project declares nothing for npm, including when it declares only pnpm or yarn.
+ */
+declare function parseSpecs(pkg: unknown): ParsedSpecs | null;
+//#endregion
+//#region src/select.d.ts
+interface RegistrySignature {
+  keyid: string;
+  sig: string;
+}
+/** A published npm version as the registry or the cache describes it. */
+interface Candidate {
+  version: string;
+  /** `engines.node` of the package; missing means any Node. */
+  enginesNode: string | null;
+  /** `dist.integrity` (sha512 SRI). */
+  integrity: string;
+  /** Where the candidate lives when it is already cached. */
+  entryPath: string | null;
+  /** `dist.signatures` from the registry; null for a cached candidate. */
+  signatures: RegistrySignature[] | null;
+  /** For a cached entry: the key that verified it, or null when only a project's pin did. */
+  keyid?: string | null;
+  /** For a cached entry: the tarball digests recorded at verification, so a pin can be judged without the bytes. */
+  digests?: {
+    sha256: string;
+    sha224: string;
+  } | null;
+}
+interface Selection {
+  candidate: Candidate;
+  /** Pins from the specs that selected the candidate; the download must match one of them. Empty: unpinned. */
+  hashes: SpecHash[];
+}
+type SelectFailure = {
+  kind: "engine";
+  version: string;
+  enginesNode: string;
+} | {
+  kind: "nomatch";
+  reason: string;
+};
+type SelectResult = {
+  kind: "selected";
+  selection: Selection;
+} | {
+  kind: "failed";
+  failure: SelectFailure;
+};
+/** The hex digest of a `sha512-<base64>` SRI string, or null for any other form. */
+declare function sriHex(integrity: string): string | null;
+/**
+ * Picks the highest candidate matching any spec and the active Node (spec RES-6), cached first.
+ * Returns the reason when nothing fits, distinguishing an `engines.node` exclusion from no match at all.
+ */
+declare function selectCandidate(specs: readonly NpmSpec[], candidates: readonly Candidate[], nodeVersion: string): SelectResult;
+//#endregion
+//#region src/errors.d.ts
+/** Exit codes of `npm-vm` itself and of the shim before npm starts (spec section 10). */
+declare const EXIT: {
+  readonly ok: 0;
+  readonly problems: 1;
+  readonly partial: 2;
+  readonly resolution: 3;
+  readonly transport: 4;
+  readonly verification: 5;
+  readonly abi: 6;
+  readonly usage: 64;
+};
+type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** A failure with a message id from spec section 12 and the exit code it maps to. */
+declare class NpmVmError extends Error {
+  override name: string;
+  readonly id: string;
+  readonly exitCode: ExitCode;
+  constructor(id: string, exitCode: ExitCode, message: string);
+}
+declare function isNpmVmError(error: unknown): error is NpmVmError;
+//#endregion
+//#region src/index.d.ts
+interface ResolveSource {
+  file: string;
+  field: "devEngines" | "packageManager" | "env";
+}
+interface ResolveResult {
+  kind: "own" | "cached" | "download";
+  version: string;
+  /** Absolute path to `bin/npm-cli.js`; for a download, the path the entry will have once fetched. */
+  cliPath: string;
+  source: ResolveSource | null;
+  projectRoot: string | null;
+  /** Set for `cached` and `download`: what to fetch or verify. */
+  selection: Selection | null;
+  /** The project's npm requirements, when it declares any. */
+  specs: NpmSpec[] | null;
+  /** A warning to print on stderr before running Node's own npm (`onFail: warn`). */
+  warning: string | null;
+}
+interface ResolveOptions {
+  env?: NodeJS.ProcessEnv;
+  offline?: boolean;
+  /** The npm-vm home holding the cache namespace; defaults to `NPM_VM_HOME` or the platform location. */
+  home?: string;
+}
+/** The lookups resolution depends on; the install layer provides the real ones. */
+interface ResolveProviders {
+  ownNpm(): OwnNpm | null;
+  cached(specs: readonly NpmSpec[]): Promise<Candidate[]>;
+  registry(specs: readonly NpmSpec[]): Promise<Candidate[]>;
+  nodeVersion: string;
+  /** Path a download will occupy, so callers can report it before fetching. */
+  entryPathFor(candidate: Candidate): string;
+}
+/** Resolves the npm to run for `argv` in `cwd` (spec section 5); writes only under the cache, spawns npm only as the transport. */
+declare function resolveNpm(argv: readonly string[], cwd: string, options?: ResolveOptions): Promise<ResolveResult>;
+declare function resolveNpmWith(argv: readonly string[], cwd: string, options: ResolveOptions, providers: ResolveProviders): Promise<ResolveResult>;
+//#endregion
+export { ParsedSpecs as _, resolveNpm as a, parseVersionSpec as b, NpmVmError as c, RegistrySignature as d, Selection as f, OnFail as g, NpmSpec as h, ResolveSource as i, isNpmVmError as l, sriHex as m, ResolveProviders as n, resolveNpmWith as o, selectCandidate as p, ResolveResult as r, EXIT as s, ResolveOptions as t, Candidate as u, SpecError as v, OwnNpm as x, parseSpecs as y };
+//# sourceMappingURL=index-B071ZJDk.d.ts.map

package/dist/index.cjs

@@ -0,0 +1,7 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_src = require("./src-Bc9nN1Kl.cjs");
+exports.EXIT = require_src.EXIT;
+exports.NpmVmError = require_src.NpmVmError;
+exports.isNpmVmError = require_src.isNpmVmError;
+exports.resolveNpm = require_src.resolveNpm;
+exports.resolveNpmWith = require_src.resolveNpmWith;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { _ as ParsedSpecs, a as resolveNpm, c as NpmVmError, f as Selection, g as OnFail, h as NpmSpec, i as ResolveSource, l as isNpmVmError, n as ResolveProviders, o as resolveNpmWith, r as ResolveResult, s as EXIT, t as ResolveOptions, u as Candidate } from "./index-B071ZJDk.cjs";
+export { type Candidate, EXIT, type NpmSpec, NpmVmError, type OnFail, type ParsedSpecs, ResolveOptions, ResolveProviders, ResolveResult, ResolveSource, type Selection, isNpmVmError, resolveNpm, resolveNpmWith };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { _ as ParsedSpecs, a as resolveNpm, c as NpmVmError, f as Selection, g as OnFail, h as NpmSpec, i as ResolveSource, l as isNpmVmError, n as ResolveProviders, o as resolveNpmWith, r as ResolveResult, s as EXIT, t as ResolveOptions, u as Candidate } from "./index-B071ZJDk.js";
+export { type Candidate, EXIT, type NpmSpec, NpmVmError, type OnFail, type ParsedSpecs, ResolveOptions, ResolveProviders, ResolveResult, ResolveSource, type Selection, isNpmVmError, resolveNpm, resolveNpmWith };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { G as EXIT, K as NpmVmError, n as resolveNpmWith, q as isNpmVmError, t as resolveNpm } from "./src-NhNG2mnQ.js";
+export { EXIT, NpmVmError, isNpmVmError, resolveNpm, resolveNpmWith };