@vltpkg/cli-sdk 1.0.0-rc.3 → 1.0.0-rc.30

package/dist/{esm/query-host-contexts.js → query-host-contexts.js}

@@ -1,6 +1,7 @@
 import { homedir } from 'node:os';
 import { parse, posix } from 'node:path';
-import { getProjectData, readProjectFolders, reloadConfig, } from '@vltpkg/server';
+import { readProjectFolders } from "./read-project-folders.js";
+import { reloadConfig } from "./reload-config.js";
 import { actual, createVirtualRoot } from '@vltpkg/graph';
 import { SecurityArchive } from '@vltpkg/security-archive';
 import { error } from '@vltpkg/error-cause';
@@ -13,6 +14,11 @@ try {
 }
 catch { }
 const home = foundHome ?? posix.dirname(posix.format(parse(process.cwd())));
+const isVltInstalled = (folder) => !!folder.resolve('node_modules/.vlt').lstatSync()?.isDirectory() ||
+    !!folder
+        .resolve('node_modules/.vlt-lock.json')
+        .lstatSync()
+        ?.isFile();
 /**
  * Generates possible project keys for a given folder.
  */
@@ -89,12 +95,8 @@ export const createHostContextsMap = async (conf) => {
         for (const folder of projectFolders) {
             try {
                 const config = await reloadConfig(folder.fullpath());
-                const projectInfo = getProjectData({
-                    packageJson: config.options.packageJson,
-                    scurry: config.options.scurry,
-                }, folder);
                 // only include projects that are vlt-installed
-                if (!projectInfo.vltInstalled) {
+                if (!isVltInstalled(folder)) {
                     continue;
                 }
                 // load each individual graph
@@ -132,4 +134,3 @@ export const createHostContextsMap = async (conf) => {
     });
     return hostContexts;
 };
-//# sourceMappingURL=query-host-contexts.js.map

package/dist/{esm/read-password.d.ts → read-password.d.ts}

@@ -5,4 +5,3 @@ export type Streams = {
     stdout: NodeJS.WritableStream;
 };
 export declare const readPassword: (prompt: string, { stdin, stdout }?: Streams) => Promise<string>;
-//# sourceMappingURL=read-password.d.ts.map

package/dist/{esm/read-password.js → read-password.js}

@@ -30,4 +30,3 @@ export const readPassword = async (prompt, { stdin, stdout } = process) => {
     });
     return input;
 };
-//# sourceMappingURL=read-password.js.map

package/dist/read-project-folders.d.ts

@@ -0,0 +1,17 @@
+import type { PathBase, PathScurry } from 'path-scurry';
+type ProjectFolderOptions = {
+    path?: string;
+    scurry: PathScurry;
+    userDefinedProjectPaths: string[];
+};
+/**
+ * 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 declare const readProjectFolders: ({ path, scurry, userDefinedProjectPaths, }: ProjectFolderOptions, maxDepth?: number) => Promise<PathBase[]>;
+export {};

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/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/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>;

package/dist/telemetry.js

@@ -0,0 +1,170 @@
+/**
+ * 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
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { XDG } from '@vltpkg/xdg';
+const POSTHOG_API_KEY = 'phc_k9xCAgC6sPIBLb5UhjhnGWpt1mos0hLV4mmEhZTGPpO';
+const POSTHOG_HOST = 'https://us.i.posthog.com';
+/** Timeout (ms) we wait for PostHog to flush before giving up. */
+const SHUTDOWN_TIMEOUT_MS = 2_000;
+const xdg = new XDG('vlt');
+/**
+ * Check whether telemetry is disabled via environment variables.
+ *
+ * - `DO_NOT_TRACK=1` — https://consoledonottrack.com/
+ * - `VLT_TELEMETRY=0`
+ */
+export const isOptedOut = () => process.env.DO_NOT_TRACK === '1' ||
+    process.env.VLT_TELEMETRY === '0';
+/**
+ * Return (or create) a stable anonymous distinct ID.
+ * Stored at `<XDG_DATA_HOME>/vlt/telemetry-id`.
+ */
+const getAnonymousId = () => {
+    const dir = xdg.data();
+    const file = xdg.data('telemetry-id');
+    try {
+        const existing = readFileSync(file, 'utf8').trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // file doesn't exist yet — create it below
+    }
+    const id = randomUUID();
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(file, id + '\n');
+    }
+    catch {
+        // best-effort — if we can't persist, just use a transient id
+    }
+    return id;
+};
+// ---------------------------------------------------------------------------
+// PostHog client — lazily initialised
+// ---------------------------------------------------------------------------
+let _posthog;
+let _initFailed = false;
+const getClient = () => {
+    if (_posthog)
+        return _posthog;
+    if (_initFailed)
+        return undefined;
+    try {
+        // Dynamic import would be async; posthog-node also ships a
+        // synchronous constructor, so we use createRequire to keep
+        // the hot-path synchronous in this ESM package.
+        const req = createRequire(import.meta.url);
+        const { PostHog } = req('posthog-node');
+        _posthog = new PostHog(POSTHOG_API_KEY, {
+            host: POSTHOG_HOST,
+            // Buffer up to 20 events and flush every 10 s — but we always
+            // call shutdown at the end so this is just a safety net.
+            flushAt: 20,
+            flushInterval: 10_000,
+        });
+        return _posthog;
+        /* c8 ignore next 4 */
+    }
+    catch {
+        _initFailed = true;
+        return undefined;
+    }
+};
+/**
+ * Capture a `cli_command` event.
+ */
+export const trackCommand = (ev, telemetryFlag) => {
+    if (telemetryFlag === false || isOptedOut())
+        return;
+    const ph = getClient();
+    if (!ph)
+        return;
+    try {
+        ph.capture({
+            distinctId: getAnonymousId(),
+            event: 'cli_command',
+            properties: { ...ev },
+        });
+    }
+    catch {
+        // fail silently
+    }
+};
+/**
+ * Capture a `cli_install` event.
+ */
+export const trackInstall = (ev, telemetryFlag) => {
+    if (telemetryFlag === false || isOptedOut())
+        return;
+    const ph = getClient();
+    if (!ph)
+        return;
+    try {
+        ph.capture({
+            distinctId: getAnonymousId(),
+            event: 'cli_install',
+            properties: { ...ev },
+        });
+    }
+    catch {
+        // fail silently
+    }
+};
+/**
+ * Capture a `cli_error` event.
+ */
+export const trackError = (ev, telemetryFlag) => {
+    if (telemetryFlag === false || isOptedOut())
+        return;
+    const ph = getClient();
+    if (!ph)
+        return;
+    try {
+        ph.capture({
+            distinctId: getAnonymousId(),
+            event: 'cli_error',
+            properties: { ...ev },
+        });
+    }
+    catch {
+        // fail silently
+    }
+};
+/**
+ * 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 const flush = () => {
+    const ph = _posthog;
+    if (!ph)
+        return Promise.resolve();
+    // Clear the reference so no further events are captured and
+    // PostHog's internal timers can be garbage-collected.
+    _posthog = undefined;
+    return Promise.race([
+        ph.shutdown().catch(() => { }),
+        new Promise(r => {
+            const t = setTimeout(r, SHUTDOWN_TIMEOUT_MS);
+            // Unref so this timer alone won't keep the process alive.
+            if (typeof t === 'object' && 'unref' in t)
+                t.unref();
+        }),
+    ]);
+};

package/dist/{esm/view.d.ts → view.d.ts}

@@ -27,4 +27,3 @@ export type ViewFn<T = unknown> = (result: T, options: ViewOptions, conf: Loaded
 export type View<T = unknown> = ViewFn<T> | typeof ViewClass<T>;
 export declare const isViewClass: <T = unknown>(view: View<T>) => view is typeof ViewClass<T>;
 export type Views<T = unknown> = View<T> | Record<string, View<T>>;
-//# sourceMappingURL=view.d.ts.map

package/dist/{esm/view.js → view.js}

@@ -17,7 +17,7 @@ export class ViewClass {
         this.config = config;
     }
     // TODO: maybe have start() return a flag to say "i got this, do not
-    // run the command", for example to have the gui just open a web browser
+    // run the command", for example to just open a web browser
     // to the page relevant to a given thing, rather than computing it twice
     start() { }
     async done(_result, _opts) {
@@ -28,4 +28,3 @@ export class ViewClass {
 export const isViewClass = (view) => typeof view === 'function' &&
     'prototype' in view &&
     view.prototype instanceof ViewClass;
-//# sourceMappingURL=view.js.map