@vltpkg/cli-sdk 1.0.0-rc.9 → 1.0.2

package/dist/read-project-folders.js

@@ -0,0 +1,100 @@
+import { availableParallelism, homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { callLimit } from 'promise-call-limit';
+const limit = Math.max(availableParallelism() - 1, 1) * 8;
+let home;
+try {
+    home = homedir();
+}
+catch {
+    home = dirname(process.cwd());
+}
+const ignoredHomedirFolderNames = [
+    'downloads',
+    'movies',
+    'music',
+    'pictures',
+    'private',
+    'library',
+    'dropbox',
+].concat(process.platform === 'darwin' ?
+    [
+        'public',
+        'private',
+        'applications',
+        'applications (parallels)',
+        'sites',
+        'sync',
+    ]
+    : process.platform === 'win32' ?
+        [
+            'appdata',
+            'application data',
+            'favorites',
+            'links',
+            'videos',
+            'contacts',
+            'searches',
+        ]
+        : ['videos', 'public']);
+/**
+ * Retrieves folders from a given directory, if that directory is
+ * recognized to be the current cli project root folder then we
+ * proceed to read its siblings.
+ *
+ * Traverses nested directory recursively until project folders can
+ * be find, always stopping at the first level where a package.json
+ * is present.
+ */
+export const readProjectFolders = async ({ path = home, scurry, userDefinedProjectPaths, }, maxDepth = 7) => {
+    const result = [];
+    const homeEntry = scurry.cwd.resolve(home);
+    const paths = userDefinedProjectPaths.length ? userDefinedProjectPaths : [path];
+    const step = (entry, depth) => async () => {
+        try {
+            for (const child of await entry.readdir()) {
+                if (await collectResult(child, result, scurry, entry === homeEntry, depth, maxDepth)) {
+                    traverse.push(step(child, depth + 1));
+                }
+            }
+            /* c8 ignore next 4 */
+        }
+        catch {
+            // Ignore directories that can't be read.
+            // This commonly happens in restricted environments.
+        }
+    };
+    let traverse = (await Promise.all(paths.map(path => scurry.lstat(path))))
+        .filter(p => !!p)
+        .map(p => step(p, 0));
+    // have to do it in phases this way because pushing into the queue
+    // during the promise-call-limit confuses its tracking.
+    let t;
+    do {
+        t = traverse;
+        traverse = [];
+        await callLimit(t, { limit });
+    } while (traverse.length);
+    return result;
+};
+const collectResult = async (entry, result, scurry, fromHome, depth, maxDepth) => {
+    if (!entry.isDirectory() ||
+        entry.isSymbolicLink() ||
+        entry.name === 'node_modules' ||
+        (fromHome &&
+            ignoredHomedirFolderNames.includes(entry.name.toLowerCase())) ||
+        entry.name.startsWith('.') ||
+        depth > maxDepth) {
+        return false;
+    }
+    const resolved = entry.fullpath();
+    const statPackageJson = await scurry
+        .lstat(`${resolved}/package.json`)
+        .catch(() => { });
+    const hasValidPackageJson = statPackageJson &&
+        statPackageJson.isFile() &&
+        !statPackageJson.isSymbolicLink();
+    if (hasValidPackageJson)
+        result.push(entry);
+    return !hasValidPackageJson;
+};

package/dist/registry-error-message.d.ts

@@ -0,0 +1,2 @@
+import type { CacheEntry } from '@vltpkg/registry-client';
+export declare const registryErrorMessage: (response: CacheEntry) => string;

package/dist/registry-error-message.js

@@ -0,0 +1,29 @@
+import { STATUS_CODES } from 'node:http';
+export const registryErrorMessage = (response) => {
+    const statusMessage = STATUS_CODES[response.statusCode];
+    const status = `${response.statusCode}${statusMessage ? ` ${statusMessage}` : ''}`;
+    let text;
+    try {
+        text = response.text().trim();
+    }
+    catch {
+        return status;
+    }
+    if (!text)
+        return status;
+    let detail = text;
+    try {
+        const body = JSON.parse(text);
+        if (body &&
+            typeof body === 'object' &&
+            'error' in body &&
+            typeof body.error === 'string' &&
+            body.error) {
+            detail = body.error;
+        }
+    }
+    catch {
+        // A non-JSON response body is itself the most useful error detail.
+    }
+    return `${status} — ${detail}`;
+};

package/dist/reload-config.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedConfig } from './config/index.ts';
+export declare const reloadConfig: (folder: string) => Promise<ParsedConfig>;

package/dist/reload-config.js

@@ -0,0 +1,11 @@
+export const reloadConfig = async (folder) => {
+    try {
+        const { unload } = (await import('@vltpkg/vlt-json'));
+        unload('user');
+        unload('project');
+        /* c8 ignore next */
+    }
+    catch { }
+    const { Config } = await import("./config/index.js");
+    return Config.load(folder, process.argv, true);
+};

package/dist/render-mermaid.d.ts

@@ -0,0 +1,22 @@
+export type OutputFormat = 'svg' | 'png';
+/**
+ * Renders mermaid diagram text to an SVG string using
+ * the `beautiful-mermaid` library. No external process
+ * is spawned — everything runs in-process.
+ * @returns {string} The SVG markup as a string.
+ */
+export declare const renderMermaidSvg: (mermaidText: string) => string;
+/**
+ * Renders mermaid diagram text to an SVG file.
+ * Uses `beautiful-mermaid` in-process, then writes
+ * the result to a temp directory.
+ * @returns {Promise<string>} The file path of the generated SVG.
+ */
+export declare const renderMermaidToFile: (mermaidText: string) => Promise<string>;
+/**
+ * Renders mermaid diagram text to a PNG file.
+ * Uses `beautiful-mermaid` for SVG, then `@resvg/resvg-wasm`
+ * to convert SVG to PNG. Writes to a temp directory.
+ * @returns {Promise<string>} The file path of the generated PNG.
+ */
+export declare const renderMermaidToPng: (mermaidText: string) => Promise<string>;

package/dist/render-mermaid.js

@@ -0,0 +1,68 @@
+import { writeFile, mkdtemp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { error } from '@vltpkg/error-cause';
+import { renderMermaidSVG } from 'beautiful-mermaid';
+/**
+ * Replace `#64;` with `@` for display rendering.
+ * Mermaid text uses `#64;` to avoid issues with `@` in
+ * GitHub/markdown parsers, but SVG/PNG should show `@`.
+ */
+const decodeForDisplay = (mermaidText) => mermaidText.replace(/#64;/g, '@');
+/**
+ * Renders mermaid diagram text to an SVG string using
+ * the `beautiful-mermaid` library. No external process
+ * is spawned — everything runs in-process.
+ * @returns {string} The SVG markup as a string.
+ */
+export const renderMermaidSvg = (mermaidText) => {
+    try {
+        return renderMermaidSVG(decodeForDisplay(mermaidText), {
+            bg: '#FFFFFF',
+            fg: '#27272A',
+            padding: 40,
+        });
+    }
+    catch (cause) {
+        throw error('Error rendering SVG', { cause });
+    }
+};
+/**
+ * Renders mermaid diagram text to an SVG file.
+ * Uses `beautiful-mermaid` in-process, then writes
+ * the result to a temp directory.
+ * @returns {Promise<string>} The file path of the generated SVG.
+ */
+export const renderMermaidToFile = async (mermaidText) => {
+    const svg = renderMermaidSvg(mermaidText);
+    const dir = await mkdtemp(join(tmpdir(), 'vlt-mermaid-'));
+    const outputFile = join(dir, 'graph.svg');
+    await writeFile(outputFile, svg);
+    return outputFile;
+};
+/**
+ * Renders mermaid diagram text to a PNG file.
+ * Uses `beautiful-mermaid` for SVG, then `@resvg/resvg-wasm`
+ * to convert SVG to PNG. Writes to a temp directory.
+ * @returns {Promise<string>} The file path of the generated PNG.
+ */
+export const renderMermaidToPng = async (mermaidText) => {
+    const svg = renderMermaidSvg(mermaidText);
+    const { Resvg, initWasm } = await import('@resvg/resvg-wasm');
+    const { readFile: rf } = await import('node:fs/promises');
+    const { createRequire: cr } = await import('node:module');
+    const wasmPath = cr(import.meta.url).resolve('@resvg/resvg-wasm/index_bg.wasm');
+    try {
+        await initWasm(await rf(wasmPath));
+    }
+    catch {
+        // WASM may already be initialized — ignore
+    }
+    const resvg = new Resvg(svg);
+    const pngData = resvg.render();
+    const pngBuffer = pngData.asPng();
+    const dir = await mkdtemp(join(tmpdir(), 'vlt-mermaid-'));
+    const outputFile = join(dir, 'graph.png');
+    await writeFile(outputFile, pngBuffer);
+    return outputFile;
+};

package/dist/require-registry.d.ts

@@ -0,0 +1,48 @@
+import type { RegistryCandidate } from './select-registry.ts';
+import type { LoadedConfig } from './config/index.ts';
+/**
+ * There is no default registry. This is the single message used
+ * everywhere a registry is required but missing.
+ */
+export declare const missingRegistryError: () => Error;
+/**
+ * Multiple registries are configured and none was selected. Used in
+ * non-interactive contexts where we cannot prompt and there is no
+ * `default-registry-alias` to fall back to.
+ */
+export declare const ambiguousRegistryError: (candidates: RegistryCandidate[]) => Error;
+/**
+ * Resolve a named registry alias to its URL, throwing an `ECONFIG`
+ * error (listing the known aliases) when the alias is not configured.
+ */
+export declare const resolveRegistryAlias: (conf: LoadedConfig, alias: string) => string;
+/**
+ * Whether the current config provides a registry a `needsRegistry`
+ * command could act against without prompting for setup. True when an
+ * explicit `--registry` URL is set or the user has configured at least
+ * one non-default registry alias. Kept consistent with
+ * {@link resolveRegistry} so the pre-command gate never rejects a config
+ * the resolver would otherwise accept or prompt for.
+ */
+export declare const hasConfiguredRegistry: (conf: LoadedConfig) => boolean;
+/**
+ * Synchronous, non-interactive registry resolution used by
+ * programmatic callers. Precedence: explicit alias > `--registry`
+ * scalar > single configured alias > `default-registry-alias`. Throws
+ * when nothing is configured or the choice is ambiguous.
+ */
+export declare const requireRegistry: (conf: LoadedConfig, alias?: string) => string;
+/**
+ * Resolve the registry a command should act against.
+ *
+ * Precedence: explicit `alias` (from `vlt registry <alias> <cmd>`) >
+ * `--registry` URL scalar > the single configured alias. When multiple
+ * aliases are configured and none was chosen, prompt interactively on a
+ * TTY, otherwise fall back to `default-registry-alias`, else error.
+ */
+export declare const resolveRegistry: (conf: LoadedConfig, { alias, interactive, input, output, }?: {
+    alias?: string;
+    interactive?: boolean;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}) => Promise<string>;

package/dist/require-registry.js

@@ -0,0 +1,122 @@
+import { error } from '@vltpkg/error-cause';
+import { defaultRegistries } from '@vltpkg/spec';
+import { selectRegistry } from "./select-registry.js";
+/**
+ * There is no default registry. This is the single message used
+ * everywhere a registry is required but missing.
+ */
+export const missingRegistryError = () => error([
+    'Missing registry configuration.',
+    '',
+    'vlt has no default registry. Run `vlt setup` to get configured.',
+    '',
+    'See https://docs.vlt.sh/cli for other ways to set a registry.',
+].join('\n'), { code: 'ECONFIG' });
+/**
+ * Multiple registries are configured and none was selected. Used in
+ * non-interactive contexts where we cannot prompt and there is no
+ * `default-registry-alias` to fall back to.
+ */
+export const ambiguousRegistryError = (candidates) => error([
+    'Multiple registries are configured; specify which one to use.',
+    '',
+    'Run `vlt registry <alias> <command>` with one of:',
+    ...candidates.map(c => `  ${c.alias} -> ${c.url}`),
+].join('\n'), {
+    code: 'ECONFIG',
+    validOptions: candidates.map(c => c.alias),
+});
+/**
+ * Resolve a named registry alias to its URL, throwing an `ECONFIG`
+ * error (listing the known aliases) when the alias is not configured.
+ */
+export const resolveRegistryAlias = (conf, alias) => {
+    const url = conf.options.registries[alias];
+    if (!url) {
+        throw error(`Unknown registry alias: ${alias}`, {
+            code: 'ECONFIG',
+            found: alias,
+            validOptions: Object.keys(conf.options.registries),
+        });
+    }
+    return url;
+};
+/**
+ * The registries the user has actually configured, when no explicit
+ * `--registry` URL is set. Order follows the `registries` config (which
+ * preserves insertion order).
+ *
+ * Built-in defaults (eg `gh`) are excluded so they don't implicitly
+ * satisfy "a registry is configured" for account/auth commands. A
+ * built-in alias the user has overridden to a different URL counts as
+ * configured. Built-in aliases can still be targeted explicitly via
+ * `vlt registry <alias> <cmd>` (which resolves through
+ * {@link resolveRegistryAlias}).
+ */
+const gatherCandidates = (conf) => {
+    const builtins = defaultRegistries;
+    return Object.entries(conf.options.registries)
+        .filter(([alias, url]) => builtins[alias] !== url)
+        .map(([alias, url]) => ({ alias, url }));
+};
+/**
+ * Whether the current config provides a registry a `needsRegistry`
+ * command could act against without prompting for setup. True when an
+ * explicit `--registry` URL is set or the user has configured at least
+ * one non-default registry alias. Kept consistent with
+ * {@link resolveRegistry} so the pre-command gate never rejects a config
+ * the resolver would otherwise accept or prompt for.
+ */
+export const hasConfiguredRegistry = (conf) => !!conf.options.registry || gatherCandidates(conf).length > 0;
+/**
+ * Synchronous, non-interactive registry resolution used by
+ * programmatic callers. Precedence: explicit alias > `--registry`
+ * scalar > single configured alias > `default-registry-alias`. Throws
+ * when nothing is configured or the choice is ambiguous.
+ */
+export const requireRegistry = (conf, alias) => {
+    if (alias !== undefined)
+        return resolveRegistryAlias(conf, alias);
+    const { registry } = conf.options;
+    if (registry)
+        return registry;
+    const candidates = gatherCandidates(conf);
+    const [first, second] = candidates;
+    if (!first)
+        throw missingRegistryError();
+    if (!second)
+        return first.url;
+    const defaultUrl = conf.options.registries[conf.options['default-registry-alias']];
+    if (defaultUrl)
+        return defaultUrl;
+    throw ambiguousRegistryError(candidates);
+};
+/**
+ * Resolve the registry a command should act against.
+ *
+ * Precedence: explicit `alias` (from `vlt registry <alias> <cmd>`) >
+ * `--registry` URL scalar > the single configured alias. When multiple
+ * aliases are configured and none was chosen, prompt interactively on a
+ * TTY, otherwise fall back to `default-registry-alias`, else error.
+ */
+export const resolveRegistry = async (conf, { alias, interactive = process.stdin.isTTY, input, output, } = {}) => {
+    if (alias !== undefined)
+        return resolveRegistryAlias(conf, alias);
+    const { registry } = conf.options;
+    if (registry)
+        return registry;
+    const candidates = gatherCandidates(conf);
+    const [first, second] = candidates;
+    if (!first)
+        throw missingRegistryError();
+    if (!second)
+        return first.url;
+    const defaultAlias = conf.options['default-registry-alias'];
+    if (interactive) {
+        return selectRegistry(candidates, { defaultAlias, input, output });
+    }
+    const defaultUrl = conf.options.registries[defaultAlias];
+    if (defaultUrl)
+        return defaultUrl;
+    throw ambiguousRegistryError(candidates);
+};

package/dist/select-registry.d.ts

@@ -0,0 +1,23 @@
+/** A configured registry the user can act against. */
+export type RegistryCandidate = {
+    /** the configured alias name (a key in `registries`) */
+    alias: string;
+    /** the resolved registry URL */
+    url: string;
+};
+export type SelectStreams = {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+};
+/**
+ * Interactively prompt the user to choose one of the configured
+ * registries. `defaultAlias` (when present in `candidates`) is
+ * pre-selected so pressing enter accepts it.
+ *
+ * Streams are injectable so tests can drive the prompt deterministically.
+ */
+export declare const selectRegistry: (candidates: RegistryCandidate[], { defaultAlias, input, output, }?: {
+    defaultAlias?: string;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}) => Promise<string>;

package/dist/select-registry.js

@@ -0,0 +1,40 @@
+import { error } from '@vltpkg/error-cause';
+import { createInterface } from 'node:readline/promises';
+/**
+ * Interactively prompt the user to choose one of the configured
+ * registries. `defaultAlias` (when present in `candidates`) is
+ * pre-selected so pressing enter accepts it.
+ *
+ * Streams are injectable so tests can drive the prompt deterministically.
+ */
+export const selectRegistry = async (candidates, { defaultAlias, input = process.stdin, output = process.stdout, } = {}) => {
+    const defaultIndex = Math.max(candidates.findIndex(c => c.alias === defaultAlias), 0);
+    const fallback = candidates[defaultIndex] ?? candidates[0];
+    if (!fallback) {
+        throw error('No registries to select from', { code: 'ECONFIG' });
+    }
+    const rl = createInterface({ input, output });
+    try {
+        output.write('Multiple registries are configured. Select one:\n');
+        for (const [i, c] of candidates.entries()) {
+            const marker = i === defaultIndex ? ' (default)' : '';
+            output.write(`  ${i + 1}) ${c.alias} -> ${c.url}${marker}\n`);
+        }
+        const answer = (await rl.question(`Registry [${defaultIndex + 1}]: `)).trim();
+        if (!answer)
+            return fallback.url;
+        const choice = Number(answer);
+        const picked = candidates[choice - 1];
+        if (!Number.isInteger(choice) || !picked) {
+            throw error('Invalid registry selection', {
+                found: answer,
+                validOptions: candidates.map((_, i) => String(i + 1)),
+                code: 'EUSAGE',
+            });
+        }
+        return picked.url;
+    }
+    finally {
+        rl.close();
+    }
+};

package/dist/telemetry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Anonymized telemetry for the vlt CLI.
+ *
+ * - Sends anonymous, non-PII events to PostHog.
+ * - Generates a random UUID on first run, stored in XDG data dir.
+ * - Respects opt-out via `DO_NOT_TRACK=1`, `VLT_TELEMETRY=0`,
+ *   or the `--telemetry=false` config flag.
+ * - Flush is awaited with a timeout cap so it never blocks CLI exit for long.
+ * - Fails silently on any network or runtime error.
+ * @module
+ */
+/**
+ * Check whether telemetry is disabled via environment variables.
+ *
+ * - `DO_NOT_TRACK=1` — https://consoledonottrack.com/
+ * - `VLT_TELEMETRY=0`
+ */
+export declare const isOptedOut: () => boolean;
+export interface CommandEvent {
+    command: string;
+    duration_ms: number;
+    success: boolean;
+    node_version: string;
+    vlt_version: string;
+    os: string;
+    arch: string;
+    ci: boolean;
+}
+export interface InstallEvent {
+    dependency_count: number;
+    duration_ms: number;
+}
+export interface ErrorEvent {
+    command: string;
+    error_code?: string;
+}
+/**
+ * Capture a `cli_command` event.
+ */
+export declare const trackCommand: (ev: CommandEvent, telemetryFlag?: boolean) => void;
+/**
+ * Capture a `cli_install` event.
+ */
+export declare const trackInstall: (ev: InstallEvent, telemetryFlag?: boolean) => void;
+/**
+ * Capture a `cli_error` event.
+ */
+export declare const trackError: (ev: ErrorEvent, telemetryFlag?: boolean) => void;
+/**
+ * Flush pending events. Returns a promise that resolves once flushing
+ * completes **or** when `SHUTDOWN_TIMEOUT_MS` elapses — whichever
+ * comes first. Never rejects.
+ *
+ * The safety-net timer is unreffed so it cannot keep the process alive
+ * on its own — if the caller does not `await` this, Node will still
+ * exit promptly once all other handles are drained.
+ */
+export declare const flush: () => Promise<void>;