@vltpkg/cli-js 1.0.9 → 1.1.0

package/{chunk-HRY5MJCA.js → chunk-CTQSUNNE.js}

@@ -20,13 +20,16 @@ import {
   pickManifest,
   resolve,
   revs
-} from "./chunk-USTJECVS.js";
+} from "./chunk-X2AWQGYG.js";
 import {
   Spec
 } from "./chunk-XKVU23NC.js";
+import {
+  registryErrorMessage
+} from "./chunk-SNOBGFNM.js";
 import {
   logRequest
-} from "./chunk-UBLFPJHV.js";
+} from "./chunk-U7TEQCBN.js";
 import {
   asPackument
 } from "./chunk-VFBCWAOC.js";
@@ -83,11 +86,13 @@ var rename = platform !== "win32" ? fsRename : (async function(oldPath, newPath)
 var debug = debuglog("vlt");
 var xdg = new XDG("vlt");
 var delimiter = "~";
+var PACKUMENT_ACCEPT = "application/vnd.vlt.packument-v1+json; q=1.0, application/json; q=0.8, */*; q=0.1";
 var manifestCacheMaxAge = 5 * 60 * 1e3;
 var noRegistryError = (spec) => error(
   'No registry configured to resolve this spec. Set "registry" in vlt.json, pass --registry, or run `vlt login --registry=<url>`. See https://docs.vlt.sh/cli',
   { code: "ECONFIG", spec }
 );
+var isMovingSelector = (f) => !!(f.distTag || f.range?.isAny);
 var PackageInfoClient = class {
   #registryClient;
   #projectRoot;
@@ -101,7 +106,9 @@ var PackageInfoClient = class {
   #cachePath;
   // In-flight coalescing key is `${registry}${name}` — no representation
   // component. Safe only because every caller requests the same full
-  // packument (see #fetchPackument).
+  // packument (see #fetchPackument). The one thing that does vary per
+  // caller is forceRevalidate, so record it and let a moving selector
+  // reuse a forced promise but never a non-forced one (see packument()).
   #packumentPromises = /* @__PURE__ */ new Map();
   // unique temp file names for atomic manifest cache writes
   #manifestWriteRandom = randomBytes(6).toString("hex");
@@ -116,7 +123,7 @@ var PackageInfoClient = class {
   #tarPoolPromise;
   async getRegistryClient() {
     if (this.#registryClient) return this.#registryClient;
-    this.#registryClientPromise ??= import("./src-MEEFRFWA.js").then(({ RegistryClient }) => {
+    this.#registryClientPromise ??= import("./src-XJT4IJSV.js").then(({ RegistryClient }) => {
       this.#registryClient = new RegistryClient(this.options);
       return this.#registryClient;
     });
@@ -225,7 +232,7 @@ var PackageInfoClient = class {
             throw this.#resolveError(
               spec,
               options,
-              `Registry returned HTTP ${response.statusCode} when fetching the tarball for ${spec}. The resolved version may have been unpublished, or the registry may be misconfigured or unreachable.`,
+              `${registryErrorMessage(response)} when fetching the tarball for ${spec}. The resolved version may have been unpublished, or the registry may be misconfigured or unreachable.`,
               {
                 url: r.resolved,
                 response
@@ -283,7 +290,7 @@ var PackageInfoClient = class {
           throw this.#resolveError(
             spec,
             options,
-            "failed to fetch remote tarball",
+            `failed to fetch remote tarball: ${registryErrorMessage(response)}`,
             {
               url: r.resolved,
               response
@@ -398,7 +405,7 @@ var PackageInfoClient = class {
       return;
     }
     const f = spec.final;
-    if (f.distTag || f.range?.isAny) {
+    if (isMovingSelector(f)) {
       return;
     }
     const key = this.#manifestCacheKey(f, options);
@@ -459,7 +466,7 @@ var PackageInfoClient = class {
             throw this.#resolveError(
               spec,
               options,
-              `Registry returned HTTP ${response.statusCode} when fetching the tarball for ${spec} at ${tarball}. The version may have been unpublished, or the registry may be misconfigured or unreachable.`,
+              `${registryErrorMessage(response)} when fetching the tarball for ${spec} at ${tarball}. The version may have been unpublished, or the registry may be misconfigured or unreachable.`,
               { response, url: tarball }
             );
           }
@@ -539,7 +546,7 @@ var PackageInfoClient = class {
           throw this.#resolveError(
             spec,
             options,
-            "failed to fetch URL",
+            `failed to fetch URL: ${registryErrorMessage(response)}`,
             { response, url: remoteURL }
           );
         }
@@ -642,7 +649,7 @@ var PackageInfoClient = class {
             throw this.#resolveError(
               s,
               options,
-              "failed to fetch URL",
+              `failed to fetch URL: ${registryErrorMessage(response)}`,
               { response, url: remoteURL }
             );
           }
@@ -732,29 +739,38 @@ var PackageInfoClient = class {
         const { registry, name } = f;
         if (!registry) throw noRegistryError(spec);
         const packumentKey = `${registry}${name}`;
+        const forced = isMovingSelector(f);
         const inflight = this.#packumentPromises.get(packumentKey);
-        if (inflight) return inflight;
+        if (inflight && (!forced || inflight.forced))
+          return inflight.promise;
         const pakuURL = new URL(name, registry);
         const promise = this.#fetchPackument(spec, options, pakuURL);
-        this.#packumentPromises.set(packumentKey, promise);
-        promise.then(
-          () => this.#packumentPromises.delete(packumentKey),
-          () => this.#packumentPromises.delete(packumentKey)
-        );
+        const record = { promise, forced };
+        this.#packumentPromises.set(packumentKey, record);
+        const clear = () => {
+          if (this.#packumentPromises.get(packumentKey) === record) {
+            this.#packumentPromises.delete(packumentKey);
+          }
+        };
+        promise.then(clear, clear);
         return promise;
       }
     }
   }
   async #fetchPackument(spec, options, pakuURL, useCache) {
     const response = await (await this.getRegistryClient()).request(pakuURL, {
-      headers: { accept: "application/json" },
-      ...useCache === false ? { useCache } : {}
+      headers: { accept: PACKUMENT_ACCEPT },
+      ...useCache === false ? { useCache } : {},
+      // costs a conditional GET per moving selector on an otherwise warm
+      // cache, install included. 304s are cheap but not free; the
+      // alternative is serving a dist tag that moved (#1656).
+      ...isMovingSelector(spec.final) ? { forceRevalidate: true } : {}
     });
     if (response.statusCode !== 200) {
       throw this.#resolveError(
         spec,
         options,
-        "failed to fetch packument",
+        `failed to fetch packument: ${registryErrorMessage(response)}`,
         {
           url: pakuURL,
           response

package/{chunk-ATYE2HQV.js → chunk-GJGQTRAT.js}

@@ -11,16 +11,18 @@ import {createRequire as _vlt_createRequire} from "node:module";
 var require = _vlt_createRequire(import.meta.filename);
 import {
   urlOpen
-} from "./chunk-HAYXR3MW.js";
+} from "./chunk-APMYKJI2.js";
+import {
+  assertOk,
+  registryErrorMessage
+} from "./chunk-SNOBGFNM.js";
 import {
   loadPackageJson
 } from "./chunk-E74WGW5C.js";
 import {
-  I
-} from "./chunk-LPIBYUMT.js";
-import {
+  I,
   logRequest
-} from "./chunk-UBLFPJHV.js";
+} from "./chunk-U7TEQCBN.js";
 import {
   asError
 } from "./chunk-VFBCWAOC.js";
@@ -1074,7 +1076,7 @@ var require_util = __commonJS({
         return new BodyAsyncIterable(body);
       } else if (body && isFormDataLike(body)) {
         return body;
-      } else if (body && typeof body !== "string" && !ArrayBuffer.isView(body) && isIterable2(body)) {
+      } else if (body && typeof body !== "string" && !ArrayBuffer.isView(body) && isIterable3(body)) {
         return new BodyAsyncIterable(body);
       } else {
         return body;
@@ -1195,7 +1197,7 @@ var require_util = __commonJS({
     function isAsyncIterable(obj) {
       return !!(obj != null && typeof obj[Symbol.asyncIterator] === "function");
     }
-    function isIterable2(obj) {
+    function isIterable3(obj) {
       return !!(obj != null && (typeof obj[Symbol.iterator] === "function" || typeof obj[Symbol.asyncIterator] === "function"));
     }
     function hasSafeIterator(obj) {
@@ -1806,7 +1808,7 @@ var require_util = __commonJS({
       parseURL,
       getServerName,
       isStream,
-      isIterable: isIterable2,
+      isIterable: isIterable3,
       hasSafeIterator,
       isAsyncIterable,
       isDestroyed,
@@ -2115,7 +2117,7 @@ var require_request = __commonJS({
       destroy,
       isBuffer,
       isFormDataLike,
-      isIterable: isIterable2,
+      isIterable: isIterable3,
       hasSafeIterator,
       isBlobLike,
       serializePathWithQuery,
@@ -2230,7 +2232,7 @@ var require_request = __commonJS({
           this.body = body.byteLength ? Buffer.from(body) : null;
         } else if (typeof body === "string") {
           this.body = body.length ? Buffer.from(body) : null;
-        } else if (isFormDataLike(body) || isIterable2(body) || isBlobLike(body)) {
+        } else if (isFormDataLike(body) || isIterable3(body) || isBlobLike(body)) {
           this.body = body;
         } else {
           throw new InvalidArgumentError("body must be a string, a Buffer, a Readable stream, an iterable, or an async iterable");
@@ -26601,6 +26603,19 @@ var CacheEntry = class _CacheEntry {
   get statusCode() {
     return this.#statusCode;
   }
+  /**
+   * True when the registry answered with a 2xx.
+   *
+   * `RegistryClient.request()` resolves for every status, so this is how
+   * code holding a real CacheEntry asks "did it work?".
+   *
+   * Note this is the strict form. Use it only where a genuine CacheEntry
+   * is guaranteed; `assertOk` uses the loose range check because it is
+   * also handed duck-typed responses.
+   */
+  get ok() {
+    return this.#statusCode >= 200 && this.#statusCode < 300;
+  }
   get headers() {
     return this.#headers;
   }
@@ -26953,9 +26968,9 @@ var __CODE_SPLIT_SCRIPT_NAME2 = resolve3(import.meta.dirname, "registry-client-s
 var isDeno2 = globalThis.Deno != void 0;
 var didProcessBeforeExitHook2 = false;
 var registered2 = /* @__PURE__ */ new Map();
-var register2 = (path, method, url) => {
+var register2 = (path, method, url, accept) => {
   const r = registered2.get(path) ?? /* @__PURE__ */ new Set();
-  const key = `${method} ${url}`;
+  const key = `${method} ${url}${accept ? ` ${String(accept)}` : ""}`;
   r.add(key);
   registered2.set(path, r);
   if (!didProcessBeforeExitHook2) {
@@ -27005,6 +27020,33 @@ var bun = isBun ? proc.versions.bun : void 0;
 var deno = isDeno3 ? proc.versions.deno : void 0;
 var node = isNode ? proc.versions.node : void 0;
 
+// ../../src/registry-client/src/get-header.ts
+var isIterable2 = (o) => !!o && typeof o === "object" && Symbol.iterator in o;
+var getHeader = (headers, key) => {
+  if (!headers) return void 0;
+  key = key.toLowerCase();
+  if (Array.isArray(headers)) {
+    if (!headers.length) return void 0;
+    if (Array.isArray(headers[0])) {
+      for (const [k, v] of headers) {
+        if (k.toLowerCase() === key) return v;
+      }
+    } else if (headers.length % 2 === 0) {
+      for (let i = 0; i < headers.length; i += 2) {
+        if (headers[i]?.toLowerCase() === key) return headers[i + 1];
+      }
+    }
+  } else if (isIterable2(headers)) {
+    for (const [k, v] of headers) {
+      if (k.toLowerCase() === key) return v;
+    }
+  } else {
+    for (const [k, v] of Object.entries(headers)) {
+      if (k.toLowerCase() === key) return v;
+    }
+  }
+};
+
 // ../../src/registry-client/src/handle-304-response.ts
 var handleCacheHitResponse = (resp, entry) => {
   if (resp.statusCode !== 304 && resp.statusCode !== 412 || !entry)
@@ -27053,6 +27095,9 @@ var otplease = async (client, options, response) => {
   );
   if (wwwAuth.has("ipaddress")) {
     throw error("Authorization is not allowed from your ip address", {
+      code: "ENEEDAUTH",
+      status: response.statusCode,
+      method: options.method,
       response
     });
   }
@@ -27085,17 +27130,30 @@ var otplease = async (client, options, response) => {
       }
     }
     throw error("Unrecognized OTP authentication challenge", {
+      code: "ENEEDAUTH",
+      status: response.statusCode,
+      method: options.method,
       response
     });
   }
   if (wwwAuth.has("bearer")) {
     throw error(
       "Missing or invalid authentication token. Run `vlt login` or `vlt token add` to authenticate.",
-      { response }
+      {
+        code: "ENEEDAUTH",
+        status: response.statusCode,
+        method: options.method,
+        response
+      }
     );
   }
   if (wwwAuth.size) {
-    throw error("Unknown authentication challenge", { response });
+    throw error("Unknown authentication challenge", {
+      code: "ENEEDAUTH",
+      status: response.statusCode,
+      method: options.method,
+      response
+    });
   }
   const text = await responseBodyText(response).catch(() => "");
   if (text.toLowerCase().includes("one-time pass")) {
@@ -27446,7 +27504,40 @@ var RegistryClient = class {
    */
   async scroll(url, options = {}, seek) {
     const resp = await this.request(url, options);
-    const { objects, urls } = resp.json();
+    const { statusCode } = resp;
+    if (statusCode < 200 || statusCode >= 300) {
+      let detail;
+      try {
+        const body2 = resp.json();
+        if (body2 && typeof body2 === "object" && "error" in body2) {
+          detail = body2.error;
+        }
+      } catch {
+      }
+      const status = STATUS_CODES[statusCode];
+      throw error(
+        `Failed to fetch paginated results: ${statusCode}${status ? ` ${status}` : ""}${typeof detail === "string" && detail ? `: ${detail}` : ""}`,
+        { code: "EREQUEST", status: statusCode, url: String(url) }
+      );
+    }
+    let body;
+    try {
+      body = resp.json();
+    } catch (cause) {
+      throw error("Invalid JSON in paginated registry response", {
+        code: "EREQUEST",
+        url: String(url),
+        cause
+      });
+    }
+    if (!body || typeof body !== "object" || !("objects" in body) || !Array.isArray(body.objects) || !("urls" in body) || !body.urls || typeof body.urls !== "object" || Array.isArray(body.urls) || "next" in body.urls && body.urls.next !== null && body.urls.next !== void 0 && typeof body.urls.next !== "string") {
+      throw error("Invalid pagination in registry response", {
+        code: "EREQUEST",
+        url: String(url)
+      });
+    }
+    const objects = body.objects;
+    const urls = body.urls;
     return urls.next && !(seek && objects.some(seek)) ? objects.concat(await this.scroll(urls.next, options, seek)) : objects;
   }
   /**
@@ -27465,17 +27556,41 @@ var RegistryClient = class {
     const s = tok.replace(/^(Bearer|Basic) /i, "");
     const base = registryBase(registry);
     const tokensUrl = new URL("-/npm/v1/tokens", base);
-    const record = await this.seek(tokensUrl, ({ token }) => s.startsWith(token), {
-      useCache: false
-    }).catch(() => void 0);
-    if (record) {
-      const { key } = record;
-      await this.request(
-        new URL(`-/npm/v1/tokens/token/${key}`, base),
-        { useCache: false, method: "DELETE" }
-      );
+    const stillLive = `Removing the local credential anyway; revoke the token in the registry UI if it is still live.`;
+    try {
+      let record;
+      try {
+        record = await this.seek(tokensUrl, ({ token }) => s.startsWith(token), {
+          useCache: false
+        });
+      } catch (er) {
+        log3(
+          `Could not list tokens at ${tokensUrl}: ${asError(er).message}
+` + stillLive
+        );
+      }
+      if (record) {
+        const deleteUrl = new URL(
+          `-/npm/v1/tokens/token/${record.key}`,
+          base
+        );
+        const failed = (detail) => log3(
+          `Failed to revoke the token on the registry: ${detail}
+` + stillLive
+        );
+        try {
+          const response = await this.request(deleteUrl, {
+            useCache: false,
+            method: "DELETE"
+          });
+          if (!response.ok) failed(registryErrorMessage(response));
+        } catch (er) {
+          failed(asError(er).message);
+        }
+      }
+    } finally {
+      await deleteToken(registry, this.identity);
     }
-    await deleteToken(registry, this.identity);
   }
   /**
    * Log into the registry specified.
@@ -27579,11 +27694,19 @@ var RegistryClient = class {
       }
       return await this.#checkLogin(url, options);
     }
+    assertOk(response, {
+      message: "Web login failed",
+      url,
+      advice: (statusCode) => statusCode === 404 ? "This registry does not implement the web login endpoint." : void 0
+    });
     if (response.statusCode === 200) {
       const token = getTokenResponse(response.json());
       if (token) return token;
     }
     throw error("Invalid response from web login endpoint", {
+      code: "EREQUEST",
+      url,
+      status: response.statusCode,
       response
     });
   }
@@ -27641,7 +27764,8 @@ var RegistryClient = class {
       redirections = /* @__PURE__ */ new Set(),
       signal,
       otp = (process.env.VLT_OTP ?? "").trim(),
-      staleWhileRevalidate = true
+      staleWhileRevalidate = true,
+      forceRevalidate = false
     } = options;
     let { trustIntegrity } = options;
     const m = isCacheableMethod(method) ? method : void 0;
@@ -27650,12 +27774,18 @@ var RegistryClient = class {
     const key = cacheKey(method, u);
     const buffer = useCache ? await this.cache.fetch(key, { context: { integrity } }) : void 0;
     const entry = buffer ? this.#decodeCached(buffer) : void 0;
-    if (entry?.valid) {
+    if (entry?.valid && !forceRevalidate) {
       logRequest(url, "cache", { method });
       return entry;
     }
-    if (staleWhileRevalidate && entry?.staleWhileRevalidate && m) {
-      register2(dirname3(this.cache.path()), m, url);
+    const forcedFallback = forceRevalidate && entry?.staleWhileRevalidate ? entry : void 0;
+    if (!forceRevalidate && staleWhileRevalidate && entry?.staleWhileRevalidate && m) {
+      register2(
+        dirname3(this.cache.path()),
+        m,
+        url,
+        getHeader(options.headers, "accept")
+      );
       logRequest(url, "stale", { method });
       return entry;
     }
@@ -27700,6 +27830,10 @@ var RegistryClient = class {
         options
       );
     } catch (er) {
+      if (forcedFallback && !signal?.aborted) {
+        logRequest(url, "stale", { method });
+        return forcedFallback;
+      }
       throw error("Request failed", {
         code: "EREQUEST",
         cause: er,
@@ -27728,7 +27862,8 @@ var RegistryClient = class {
     if (result.isGzip && !trustIntegrity) {
       result.checkIntegrity({ url });
     }
-    if (useCache) {
+    const clobbersCachedEntry = forceRevalidate && !!entry && result.statusCode !== 200;
+    if (useCache && !clobbersCachedEntry) {
       const buffer2 = result.encode();
       this.cache.set(
         key,

package/{chunk-YAIKXFLN.js → chunk-HYCYL4RX.js}

@@ -14,7 +14,7 @@ import {
 } from "./chunk-WGDTG44V.js";
 import {
   commandAliases
-} from "./chunk-XISRK3R5.js";
+} from "./chunk-CEHPRPGQ.js";
 import {
   loadPackageJson
 } from "./chunk-E74WGW5C.js";

package/{chunk-EBXBZ2Y5.js → chunk-J2XWQVDK.js}

@@ -11,12 +11,12 @@ import {createRequire as _vlt_createRequire} from "node:module";
 var require = _vlt_createRequire(import.meta.filename);
 import {
   PackageInfoClient
-} from "./chunk-HRY5MJCA.js";
+} from "./chunk-CTQSUNNE.js";
 import {
   Monorepo,
   PackageJson,
   PathScurry
-} from "./chunk-USTJECVS.js";
+} from "./chunk-X2AWQGYG.js";
 import {
   resetCaches
 } from "./chunk-YOE3VZFX.js";
@@ -27,7 +27,7 @@ import {
   getCommand,
   isRecordField,
   recordFields
-} from "./chunk-XISRK3R5.js";
+} from "./chunk-CEHPRPGQ.js";
 import {
   find,
   load,
@@ -38,6 +38,7 @@ import {
   assertRecordStringString,
   assertRecordStringT,
   getOptions,
+  isObject,
   isRecordStringString
 } from "./chunk-VFBCWAOC.js";
 import {
@@ -150,6 +151,7 @@ var assertRegistryKeys = (registries, file) => {
   for (const key of Object.keys(obj)) {
     if (key === "" || key.includes("~")) {
       throw error("Reserved character found in registries name", {
+        code: "ECONFIG",
         path: file,
         found: key
       });
@@ -190,6 +192,26 @@ var recordsToPairs = (obj) => {
   );
 };
 var kRecord = /* @__PURE__ */ Symbol("parsed key=value record");
+var envKey = (k) => `VLT_${k.replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase()}`;
+var kParentEnv = "__VLT_INTERNAL_EXPLICIT";
+var parentEnv = () => {
+  try {
+    const p = JSON.parse(process.env[kParentEnv] ?? "");
+    return isObject(p) && isObject(p.explicit) && Object.entries(p.explicit).every(
+      ([k, v]) => isRecordField(k) ? Array.isArray(v) && v.every((x) => typeof x === "string") : !isObject(v)
+    ) && isRecordStringString(p.env) ? p : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var dedupePairs = (pairs) => [
+  ...new Map(
+    pairs.map((p) => {
+      const eq = p.indexOf("=");
+      return [eq === -1 ? p : p.substring(0, eq), p];
+    })
+  ).values()
+];
 var Config = class _Config {
   /**
    * The {@link https://npmjs.com/jackspeak | JackSpeak} object
@@ -308,17 +330,56 @@ var Config = class _Config {
   parse(args = process.argv) {
     if (isParsed(this)) return this;
     this.#originalArgs = [...args];
+    const envKeys = Object.keys(defaultValues).filter(
+      (k) => process.env[envKey(k)] !== void 0
+    );
+    const parent = parentEnv();
+    const fileValues = this.#defaults();
     this.jack.loadEnvDefaults();
+    const envValues = this.#defaults();
     const p = this.jack.parseRaw(args);
+    const cliKeys = Object.keys(p.values);
     const fallback = getCommand(p.values["fallback-command"]);
     this.command = getCommand(p.positionals[0]);
     const cmdOrFallback = this.command ?? fallback;
     const cmdSpecific = cmdOrFallback && this.commandValues[cmdOrFallback];
-    if (cmdSpecific) {
-      this.jack.setConfigValues(recordsToPairs(cmdSpecific));
-    }
+    const cmdPairs = cmdSpecific ? recordsToPairs(cmdSpecific) : {};
+    if (cmdSpecific) this.jack.setConfigValues(cmdPairs);
     this.jack.applyDefaults(p);
+    const values = p.values;
+    const explicit = {};
+    for (const k of /* @__PURE__ */ new Set([...envKeys, ...cliKeys])) {
+      const cli = cliKeys.includes(k) ? values[k] : void 0;
+      const env = this.#explicitEnv(k, envValues[k], parent);
+      if (isRecordField(k)) {
+        const pairs = [
+          ...env ?? [],
+          ...cli ?? []
+        ];
+        if (pairs.length) explicit[k] = dedupePairs(pairs);
+      } else if (cli !== void 0) explicit[k] = cli;
+      else if (env !== void 0 && !(k in cmdPairs))
+        explicit[k] = env;
+    }
+    this.explicit = explicit;
+    for (const k of recordFields) {
+      const env = envKeys.includes(k) ? envValues[k] : [];
+      const cli = cliKeys.includes(k) ? values[k] : [];
+      const pairs = [...env, ...cli];
+      if (!pairs.length) continue;
+      const base = (k in cmdPairs ? cmdPairs[k] : fileValues[k]) ?? [];
+      values[k] = dedupePairs([...base, ...pairs]);
+    }
     this.jack.writeEnv(p);
+    process.env[kParentEnv] = JSON.stringify({
+      explicit,
+      env: Object.fromEntries(
+        Object.keys(defaultValues).flatMap((k) => {
+          const v = process.env[envKey(k)];
+          return v === void 0 ? [] : [[envKey(k), v]];
+        })
+      )
+    });
     if (this.command) p.positionals.shift();
     else this.command = getCommand(p.values["fallback-command"]);
     Object.assign(this, p);
@@ -328,6 +389,35 @@ var Config = class _Config {
     if (!isParsed(this)) throw error("failed to parse config");
     return this;
   }
+  /**
+   * Values set on the command line or via `VLT_*` env for this run.
+   * Record fields hold only those `key=value` pairs, not the ones from
+   * config files.
+   *
+   * `VLT_*` env left as a parent vlt process wrote it only counts for
+   * what was explicit in that parent.
+   */
+  explicit = {};
+  // a field's explicit env value: all of it at the top level, the new
+  // pairs (or changed scalar) when inherited from a parent vlt. once a
+  // script changes a record var, the parent's explicit pairs are dropped.
+  #explicitEnv(k, value, parent) {
+    const cur = process.env[envKey(k)];
+    if (cur === void 0) return void 0;
+    const written = parent?.env[envKey(k)];
+    if (cur === written) return parent?.explicit[k];
+    if (!isRecordField(k) || written === void 0) return value;
+    const old = new Set(written.split("\n"));
+    return value.filter((p) => !old.has(p));
+  }
+  // the current jack defaults, ie config file (+ env, once loaded) values
+  #defaults() {
+    const d = { values: {}, positionals: [] };
+    this.jack.applyDefaults(
+      d
+    );
+    return d.values;
+  }
   /**
    * Get a `key=value` list option value as an object.
    *
@@ -605,8 +695,10 @@ var configWriteTarget = (conf, fallback) => {
 };
 
 export {
+  registrySelectors,
   registrySelectionFields,
   kCustomInspect,
+  assertRegistryKeys,
   pairsToRecords,
   recordsToPairs,
   Config,