@vltpkg/cli-sdk 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/exec-command.js

@@ -0,0 +1,313 @@
+/**
+ * impl for `vlt run`, `vlt run-exec`, `vlt exec-local`, `vlt exec`
+ * @module
+ */
+import { error } from '@vltpkg/error-cause';
+import { isErrorWithCause } from '@vltpkg/types';
+import { Query } from '@vltpkg/query';
+import { createDiffFilesProvider } from "./query-diff-files.js";
+import { actual } from '@vltpkg/graph';
+import { isRunResult } from '@vltpkg/run';
+import { Monorepo } from '@vltpkg/workspaces';
+import { ansiToAnsi } from 'ansi-to-pre';
+import { stderr, stdout, styleTextStdout } from "./output.js";
+import assert from 'node:assert';
+import { resolve } from 'node:path';
+import { createHostContextsMap } from "./query-host-contexts.js";
+const isScriptSet = (o) => {
+    if (!o || typeof o !== 'object')
+        return false;
+    for (const v of Object.values(o)) {
+        if (typeof v !== 'string')
+            return false;
+    }
+    return true;
+};
+const isMultiScriptSet = (o) => {
+    for (const v of Object.values(o)) {
+        if (!isScriptSet(v))
+            return false;
+    }
+    return true;
+};
+const isSingleSuccess = (o) => o.signal === null && o.status === 0;
+const setExitCode = (result) => {
+    /* c8 ignore next */
+    process.exitCode ||= result.status ?? 1;
+};
+export const views = {
+    // run results for single or multiple will be printed along the way.
+    human: result => {
+        if (isScriptSet(result))
+            stdout('Scripts available:', result);
+        else if (isMultiScriptSet(result)) {
+            stdout('Scripts available:');
+            for (const [path, scripts] of Object.entries(result)) {
+                stdout(path, scripts);
+            }
+        }
+    },
+    json: result => isRunResult(result) && isSingleSuccess(result) ?
+        undefined
+        : result,
+};
+export class ExecCommand {
+    bg;
+    fg;
+    arg0;
+    args;
+    env;
+    #monorepo;
+    #nodes;
+    #defaultIgnoreMissing = false;
+    conf;
+    projectRoot;
+    view;
+    validViewValues = new Map([
+        ['human', 'human'],
+        ['json', 'json'],
+        ['inspect', 'inspect'],
+        ['silent', 'silent'],
+    ]);
+    constructor(conf, bg, fg) {
+        this.conf = conf;
+        this.bg = bg;
+        this.fg = fg;
+        this.view = this.validViewValues.get(conf.values.view) ?? 'human';
+        const { projectRoot, positionals: [arg0, ...args], } = conf;
+        this.arg0 = arg0;
+        this.args = args;
+        this.projectRoot = projectRoot;
+    }
+    #targetCount() {
+        if (this.#nodes)
+            return this.#nodes.length;
+        return this.#monorepo?.size ?? 1;
+    }
+    hasArg0() {
+        return !!this.arg0;
+    }
+    async run() {
+        const { conf } = this;
+        const queryString = conf.get('scope');
+        const paths = conf.get('workspace');
+        const groups = conf.get('workspace-group');
+        const recursive = conf.get('recursive');
+        // scope takes precedence over workspaces or groups
+        if (queryString) {
+            this.#defaultIgnoreMissing = true;
+            const mainManifest = conf.options.packageJson.maybeRead(this.projectRoot);
+            let graph;
+            if (mainManifest) {
+                graph = actual.load({
+                    ...conf.options,
+                    mainManifest,
+                    monorepo: Monorepo.load(this.projectRoot),
+                    loadManifests: false,
+                });
+            }
+            const hostContexts = await createHostContextsMap(conf);
+            const query = new Query({
+                /* c8 ignore start */
+                nodes: graph ? new Set(graph.nodes.values()) : new Set(),
+                edges: graph?.edges ?? new Set(),
+                importers: graph?.importers ?? new Set(),
+                /* c8 ignore stop */
+                securityArchive: undefined,
+                hostContexts,
+                diffFiles: createDiffFilesProvider(this.projectRoot),
+            });
+            const { nodes } = await query.search(queryString, {
+                signal: new AbortController().signal,
+            });
+            this.#nodes = [];
+            for (const node of nodes) {
+                const { location } = node.toJSON();
+                assert(location, error(`node ${node.id} has no location`, {
+                    found: node,
+                }));
+                this.#nodes.push(location);
+            }
+        }
+        else if (paths?.length || groups?.length || recursive) {
+            this.#defaultIgnoreMissing = true;
+            this.#monorepo = Monorepo.load(this.projectRoot, {
+                load: { paths, groups },
+            });
+        }
+        if (this.#targetCount() === 1) {
+            const arg = this.fgArg();
+            if (!arg)
+                return this.noArgsSingle();
+            const result = await this.fg(arg);
+            if (isRunResult(result)) {
+                setExitCode(result);
+            }
+            return result;
+        }
+        if (this.#targetCount() === 0) {
+            if (queryString) {
+                throw error('no matching nodes found for query', {
+                    found: queryString,
+                });
+            }
+            else {
+                throw error('no matching workspaces found', {
+                    /* c8 ignore next - already guarded */
+                    validOptions: [...(this.#monorepo?.load().paths() ?? [])],
+                });
+            }
+        }
+        if (!this.hasArg0()) {
+            return this.noArgsMulti();
+        }
+        // run across workspaces
+        let failed = false;
+        const runInDir = async (cwd, label) => {
+            const result = await this.bg(this.bgArg(cwd)).catch((er) => {
+                if (isErrorWithCause(er) && isRunResult(er.cause)) {
+                    this.printResult(label, er.cause);
+                }
+                failed = true;
+                throw er;
+            });
+            // If we are allowed to ignore missing commands, then command might be
+            // an emptry string. If so, we don't print anything and return null to
+            // be filtered out later.
+            if (!result.command)
+                return null;
+            if (!failed)
+                this.printResult(label, result);
+            return result;
+        };
+        const resultMap = new Map();
+        if (this.#nodes) {
+            for (const { label, cwd } of this.getTargets()) {
+                const result = await runInDir(cwd, label);
+                if (result)
+                    resultMap.set(label, result);
+            }
+        }
+        else if (this.#monorepo) {
+            const wsResultMap = await this.#monorepo.run(ws => runInDir(ws.fullpath, ws.path));
+            for (const [ws, result] of wsResultMap) {
+                if (result)
+                    resultMap.set(ws.path, result);
+            }
+        }
+        const results = {};
+        for (const [path, result] of resultMap) {
+            results[path] = result;
+        }
+        return results;
+    }
+    printResult(path, result) {
+        // non-human results just get printed at the end
+        if (this.view !== 'human')
+            return;
+        if (result.status === 0 && result.signal === null) {
+            /* c8 ignore start */
+            if (result.stderr)
+                stderr(ansiToAnsi(result.stderr));
+            if (result.stdout)
+                stdout(ansiToAnsi(result.stdout));
+            /* c8 ignore stop */
+            stdout(path, 'ok');
+        }
+        else {
+            stdout(styleTextStdout(['bgWhiteBright', 'black', 'bold'], path + ' failure'), {
+                status: result.status,
+                signal: result.signal,
+            });
+            /* c8 ignore start */
+            if (result.stderr)
+                stderr(ansiToAnsi(result.stderr));
+            if (result.stdout)
+                stdout(ansiToAnsi(result.stdout));
+            /* c8 ignore stop */
+            setExitCode(result);
+        }
+    }
+    /* c8 ignore start - env specific */
+    interactiveShell() {
+        return (process.env.SHELL ??
+            this.conf.get('script-shell') ??
+            (process.platform === 'win32' ? 'cmd.exe' : '/bin/sh'));
+    }
+    /* c8 ignore stop */
+    // overridden by 'vlt run' which returns undefined
+    defaultArg0() {
+        return this.interactiveShell();
+    }
+    getCwd() {
+        if (this.#nodes) {
+            const [first] = this.#nodes;
+            assert(first, error('no nodes found'));
+            return resolve(this.projectRoot, first);
+        }
+        // When no workspace/monorepo targeting is specified, use the current
+        // working directory. This matches npx behavior and is required for
+        // tools like node-gyp that must run in the correct directory.
+        return (this.#monorepo?.values().next().value?.fullpath ?? process.cwd());
+    }
+    fgArg() {
+        const cwd = this.getCwd();
+        const arg0 = this.arg0 ?? this.defaultArg0();
+        // return undefined so noArgsSingle will be called instead
+        if (typeof arg0 !== 'string')
+            return;
+        return {
+            cwd,
+            arg0,
+            args: this.args,
+            env: this.env,
+            projectRoot: this.projectRoot,
+            packageJson: this.conf.options.packageJson,
+            'script-shell': this.arg0 ? this.conf.get('script-shell') : false,
+        };
+    }
+    bgArg(cwd) {
+        return {
+            cwd,
+            acceptFail: !this.conf.get('bail'),
+            ignoreMissing: this.conf.get('if-present') ?? this.#defaultIgnoreMissing,
+            arg0: this.arg0,
+            args: this.args,
+            env: this.env,
+            projectRoot: this.projectRoot,
+            packageJson: this.conf.options.packageJson,
+            'script-shell': this.conf.get('script-shell'),
+        };
+    }
+    /* c8 ignore start - not used, only here to override */
+    noArgsSingle() {
+        throw error('Failed to determine interactive shell to spawn');
+    }
+    /* c8 ignore stop - not used, only here to override */
+    noArgsMulti() {
+        throw error('Cannot spawn interactive shells in multiple workspaces');
+    }
+    getTargets() {
+        const targets = [];
+        if (this.#nodes) {
+            for (const location of this.#nodes) {
+                const manifest = this.conf.options.packageJson.read(location);
+                const label = 
+                /* c8 ignore next */
+                location.startsWith('./') ? location.slice(2) : location;
+                const cwd = resolve(this.projectRoot, location);
+                targets.push({ label, cwd, manifest });
+            }
+        }
+        else if (this.#monorepo) {
+            this.#monorepo.runSync(ws => {
+                targets.push({
+                    label: ws.path,
+                    cwd: ws.fullpath,
+                    manifest: ws.manifest,
+                });
+            });
+        }
+        return targets;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Command, CommandFn, CommandUsage, } from './load-command.ts';
+declare const run: () => Promise<void>;
+export default run;

package/dist/index.js

@@ -0,0 +1,72 @@
+import { format } from 'node:util';
+import { asRootError } from '@vltpkg/output/error';
+import { loadPackageJson } from 'package-json-from-dist';
+import { getSortedCliOptions, getSortedKeys, } from "./config/definition.js";
+import { Config } from "./config/index.js";
+import { outputCommand, stderr, stdout } from "./output.js";
+import { indent } from "./print-err.js";
+import { loadCommand } from "./load-command.js";
+const { version } = loadPackageJson(import.meta.filename, process.env.__VLT_INTERNAL_CLI_PACKAGE_JSON);
+const loadVlt = async (cwd, argv) => {
+    try {
+        return await Config.load(cwd, argv);
+    }
+    catch (e) {
+        const err = asRootError(e, { code: 'JACKSPEAK' });
+        const { found, path, wanted, name } = err.cause;
+        const isConfigFile = typeof path === 'string';
+        const msg = isConfigFile ?
+            `Problem in Config File ${path}`
+            : 'Invalid Option Flag';
+        const validOptions = wanted ? undefined
+            : isConfigFile ? getSortedKeys()
+                : getSortedCliOptions();
+        stderr(msg);
+        stderr(err.message);
+        if (name)
+            stderr(indent(`Field: ${format(name)}`));
+        if (found) {
+            stderr(indent(`Found: ${isConfigFile ? JSON.stringify(found) : format(found)}`));
+        }
+        if (wanted)
+            stderr(indent(`Wanted: ${format(wanted)}`));
+        if (validOptions) {
+            stderr(indent('Valid Options:'));
+            stderr(indent(validOptions.join('\n'), 4));
+        }
+        stderr(indent(`Run 'vlt help' for more information about available options.`));
+        return process.exit(process.exitCode || 1);
+    }
+};
+const run = async () => {
+    const start = Date.now();
+    const cwd = process.cwd();
+    const vlt = await loadVlt(cwd, process.argv);
+    if (vlt.get('version')) {
+        return stdout(version);
+    }
+    const { monorepo } = vlt.options;
+    // Infer the workspace by being in that directory.
+    if (vlt.get('workspace') === undefined) {
+        const ws = monorepo?.get(cwd);
+        if (ws) {
+            vlt.values.workspace = [ws.path];
+            vlt.options.workspace = [ws.path];
+        }
+    }
+    if (vlt.command !== 'init' &&
+        (vlt.get('workspace') || vlt.get('workspace-group')) &&
+        ![...(monorepo?.values() ?? [])].length) {
+        stderr(`Error: No matching workspaces found. Make sure the vlt.json config contains the correct workspaces.`);
+        if (vlt.get('workspace')) {
+            stderr(indent(`Workspace: ${format(vlt.get('workspace'))}`));
+        }
+        if (vlt.get('workspace-group')) {
+            stderr(indent(`Workspace Group: ${format(vlt.get('workspace-group'))}`));
+        }
+        return process.exit(process.exitCode || 1);
+    }
+    const command = await loadCommand(vlt.command);
+    await outputCommand(command, vlt, { start });
+};
+export default run;

package/dist/load-command.d.ts

@@ -0,0 +1,15 @@
+import type { Jack } from 'jackspeak';
+import type { Commands, LoadedConfig } from './config/index.ts';
+import type { Views } from './view.ts';
+export type CommandUsage = () => Jack;
+/**
+ * A command function that may return a result of `T`.
+ * If the result is `undefined`, no final output will be displayed by default.
+ */
+export type CommandFn<T = unknown> = (conf: LoadedConfig) => Promise<T>;
+export type Command<T> = {
+    command: CommandFn<T>;
+    usage: CommandUsage;
+    views: Views<T>;
+};
+export declare const loadCommand: <T>(command: Commands[keyof Commands] | undefined) => Promise<Command<T>>;

package/dist/load-command.js

@@ -0,0 +1,20 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { error } from '@vltpkg/error-cause';
+export const loadCommand = async (command) => {
+    try {
+        return (await import(__rewriteRelativeImportExtension(`./commands/${command}.ts`)));
+    }
+    catch (e) {
+        throw error('Could not load command', {
+            found: command,
+            cause: e,
+        });
+    }
+};

package/dist/mermaid-image-view.d.ts

@@ -0,0 +1,18 @@
+import { ViewClass } from './view.ts';
+import type { OutputFormat } from './render-mermaid.ts';
+import type { MermaidOutputGraph } from '@vltpkg/graph';
+/**
+ * A ViewClass that renders mermaid output as SVG or PNG
+ * (saved to a temp file and opened).
+ *
+ * Uses `beautiful-mermaid` for SVG rendering and
+ * `@resvg/resvg-wasm` for PNG conversion — no external
+ * process spawning.
+ */
+export declare class MermaidImageView extends ViewClass<MermaidOutputGraph> {
+    format: OutputFormat;
+    constructor(...args: ConstructorParameters<typeof ViewClass<MermaidOutputGraph>>);
+    done(result: MermaidOutputGraph, _opts: {
+        time: number;
+    }): Promise<void>;
+}

package/dist/mermaid-image-view.js

@@ -0,0 +1,36 @@
+import { mermaidOutput } from '@vltpkg/graph';
+import { urlOpen } from '@vltpkg/url-open';
+import { stderr } from "./output.js";
+import { ViewClass } from "./view.js";
+/**
+ * A ViewClass that renders mermaid output as SVG or PNG
+ * (saved to a temp file and opened).
+ *
+ * Uses `beautiful-mermaid` for SVG rendering and
+ * `@resvg/resvg-wasm` for PNG conversion — no external
+ * process spawning.
+ */
+export class MermaidImageView extends ViewClass {
+    format;
+    constructor(...args) {
+        super(...args);
+        this.format = this.config.values.view;
+    }
+    async done(result, _opts) {
+        const mermaidText = mermaidOutput(result);
+        // Dynamic import to avoid loading render-mermaid eagerly
+        const { renderMermaidToFile, renderMermaidToPng } = await import("./render-mermaid.js");
+        if (this.format === 'png') {
+            stderr(`Generating PNG image...`);
+            const filePath = await renderMermaidToPng(mermaidText);
+            stderr(`Image saved to: ${filePath}`);
+            await urlOpen(filePath);
+        }
+        else {
+            stderr(`Generating SVG image...`);
+            const filePath = await renderMermaidToFile(mermaidText);
+            stderr(`Image saved to: ${filePath}`);
+            await urlOpen(filePath);
+        }
+    }
+}

package/dist/output.d.ts

@@ -0,0 +1,20 @@
+import { styleText as utilStyleText } from 'node:util';
+import type { LoadedConfig } from './config/index.ts';
+import type { Command } from './index.ts';
+import type { View, Views } from './view.ts';
+export declare const stdout: (...args: unknown[]) => void;
+export declare const stderr: (...args: unknown[]) => void;
+type StyleTextFn = (format: Parameters<typeof utilStyleText>[0], s: string) => string;
+export declare let styleTextStdout: StyleTextFn;
+export declare let styleTextStderr: StyleTextFn;
+export declare const getView: <T>(conf: LoadedConfig, views?: Views<T>) => View<T>;
+export type OnDone<T> = (result: T) => Promise<unknown>;
+/**
+ * Main export. Run the command appropriately, displaying output using
+ * the user-requested view, or the default if the user requested a view
+ * that is not defined for this command.
+ */
+export declare const outputCommand: <T>(cliCommand: Command<T>, conf: LoadedConfig, { start }?: {
+    start: number;
+}) => Promise<void>;
+export {};

package/dist/output.js

@@ -0,0 +1,125 @@
+import { formatWithOptions, styleText as utilStyleText, } from 'node:util';
+import { createSupportsColor } from 'supports-color';
+import { defaultView } from "./config/definition.js";
+import { printErr, formatOptions } from "./print-err.js";
+import { isViewClass } from "./view.js";
+import { generateDefaultHelp, generateFullHelp, } from "./custom-help.js";
+const supportsColor = (stream) => {
+    const res = createSupportsColor(stream, { sniffFlags: false });
+    if (res === false)
+        return false;
+    /* c8 ignore next */
+    return res.level > 0;
+};
+// eslint-disable-next-line no-console
+export const stdout = (...args) => console.log(...args);
+// eslint-disable-next-line no-console
+export const stderr = (...args) => console.error(...args);
+/* c8 ignore start */
+const styleText = (f, s) => utilStyleText(f, s, { validateStream: false });
+/* c8 ignore stop */
+// TODO: stop exporting mutable variables once exec output is refactored
+/* c8 ignore start */
+export let styleTextStdout = (_, s) => s;
+export let styleTextStderr = (_, s) => s;
+/* c8 ignore stop */
+const identity = (x) => x;
+export const getView = (conf, views) => {
+    const viewName = conf.values.view;
+    const viewFn = viewName === 'inspect' ? identity
+        : viewName === 'silent' ? () => undefined
+            : typeof views === 'function' ? views
+                : views && typeof views === 'object' ? views[viewName]
+                    : identity;
+    // if the user specified a view that doesn't exist, then set it back to the
+    // default, and try again. This will fall back to identity if it's also
+    // missing. We also always treat 'json' as a valid view that falls back to
+    // identity. This allows the explicit use of `--view=json` to work even
+    // when the default view is `human`.
+    if (!viewFn &&
+        conf.values.view !== defaultView &&
+        conf.values.view !== 'json' &&
+        conf.values.view !== 'silent') {
+        conf.values.view = defaultView;
+        process.env.VLT_VIEW = defaultView;
+        return getView(conf, views);
+    }
+    return viewFn ?? identity;
+};
+/**
+ * If the view is a View class, then instantiate and start it.
+ * If it's a view function, then just define the onDone method.
+ */
+const startView = (conf, opts, views, { start } = { start: Date.now() }) => {
+    const View = getView(conf, views);
+    if (isViewClass(View)) {
+        const view = new View(opts, conf);
+        view.start();
+        return {
+            async onDone(r) {
+                return view.done(r, { time: Date.now() - start });
+            },
+            onError(err) {
+                view.error(err);
+            },
+        };
+    }
+    return {
+        async onDone(r) {
+            if (r === undefined)
+                return;
+            return View(r, opts, conf);
+        },
+    };
+};
+/**
+ * Main export. Run the command appropriately, displaying output using
+ * the user-requested view, or the default if the user requested a view
+ * that is not defined for this command.
+ */
+export const outputCommand = async (cliCommand, conf, { start } = { start: Date.now() }) => {
+    const { usage, views, command } = cliCommand;
+    const stdoutColor = conf.values.color ?? supportsColor(process.stdout);
+    const stderrColor = conf.values.color ?? supportsColor(process.stderr);
+    if (conf.values.help) {
+        // Show custom help for main vlt command
+        /* c8 ignore start */
+        if (conf.command === 'help' && conf.positionals.length === 0) {
+            if (conf.get('all')) {
+                return stdout(generateFullHelp(stdoutColor));
+            }
+            return stdout(generateDefaultHelp(stdoutColor));
+        }
+        /* c8 ignore stop */
+        return stdout(usage().usage());
+    }
+    /* c8 ignore start */
+    if (stdoutColor)
+        styleTextStdout = styleText;
+    if (stderrColor)
+        styleTextStderr = styleText;
+    /* c8 ignore stop */
+    const { onDone, onError } = startView(conf, 
+    // assume views will always output to stdout so use color support from there
+    { colors: stdoutColor }, views, { start });
+    try {
+        const output = await onDone(await command(conf));
+        if (output !== undefined && conf.values.view !== 'silent') {
+            stdout(conf.values.view === 'json' ?
+                JSON.stringify(output, null, 2)
+                : formatWithOptions({
+                    ...formatOptions,
+                    colors: stdoutColor,
+                }, output));
+        }
+    }
+    catch (err) {
+        onError?.(err);
+        process.exitCode ||= 1;
+        printErr(err, usage, stderr, {
+            ...formatOptions,
+            colors: stderrColor,
+        });
+        process.exit(process.exitCode);
+    }
+};

package/dist/pack-tarball.d.ts

@@ -0,0 +1,23 @@
+import type { NormalizedManifest } from '@vltpkg/types';
+import type { LoadedConfig } from './config/index.ts';
+export type PackTarballResult = {
+    name: string;
+    version: string;
+    filename: string;
+    tarballName: string;
+    tarballData: Buffer;
+    unpackedSize: number;
+    files: string[];
+    integrity?: string;
+    shasum?: string;
+    /** The manifest used for packing (may differ from input when publishConfig.directory is set). */
+    resolvedManifest: NormalizedManifest;
+};
+/**
+ * Create a tarball from a package directory
+ * @param {NormalizedManifest} manifest - The manifest of the package to pack
+ * @param {string} dir - The directory containing the package to pack
+ * @param {LoadedConfig} [config] - The loaded configuration (for workspace/catalog resolution)
+ * @returns {Promise<PackTarballResult>} The manifest, filename, and tarball data (unless dry run)
+ */
+export declare const packTarball: (manifest: NormalizedManifest, dir: string, config: LoadedConfig) => Promise<PackTarballResult>;