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

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

@@ -4,6 +4,16 @@ 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";
+import { flush as flushTelemetry, trackCommand, trackError, } from "./telemetry.js";
+/* c8 ignore start - CI env detection is a best-effort heuristic */
+const isCI = () => !!(process.env.CI ||
+    process.env.GITHUB_ACTIONS ||
+    process.env.GITLAB_CI ||
+    process.env.CIRCLECI ||
+    process.env.JENKINS_URL ||
+    process.env.BUILDKITE ||
+    process.env.TRAVIS);
+/* c8 ignore stop */
 const supportsColor = (stream) => {
     const res = createSupportsColor(stream, { sniffFlags: false });
     if (res === false)
@@ -77,7 +87,9 @@ const startView = (conf, opts, views, { start } = { start: Date.now() }) => {
  * 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() }) => {
+export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
+    start: Date.now(),
+}) => {
     const { usage, views, command } = cliCommand;
     const stdoutColor = conf.values.color ?? supportsColor(process.stdout);
     const stderrColor = conf.values.color ?? supportsColor(process.stderr);
@@ -102,8 +114,21 @@ export const outputCommand = async (cliCommand, conf, { start } = { start: Date.
     const { onDone, onError } = startView(conf, 
     // assume views will always output to stdout so use color support from there
     { colors: stdoutColor }, views, { start });
+    const telemetryEnabled = conf.values.telemetry;
+    const commandName = conf.command;
     try {
         const output = await onDone(await command(conf));
+        const duration_ms = Date.now() - start;
+        trackCommand({
+            command: commandName,
+            duration_ms,
+            success: true,
+            node_version: process.version,
+            vlt_version: vltVersion ?? 'unknown',
+            os: process.platform,
+            arch: process.arch,
+            ci: isCI(),
+        }, telemetryEnabled);
         if (output !== undefined && conf.values.view !== 'silent') {
             stdout(conf.values.view === 'json' ?
                 JSON.stringify(output, null, 2)
@@ -112,10 +137,39 @@ export const outputCommand = async (cliCommand, conf, { start } = { start: Date.
                     colors: stdoutColor,
                 }, output));
         }
+        // Await the flush so pending telemetry events are sent before
+        // the process exits.  The flush has a built-in timeout cap
+        // (SHUTDOWN_TIMEOUT_MS) so it will never block for long, and the
+        // timer is unreffed so even if this is not awaited the process
+        // can still exit promptly.
+        await flushTelemetry();
     }
     catch (err) {
         onError?.(err);
         process.exitCode ||= 1;
+        const duration_ms = Date.now() - start;
+        trackCommand({
+            command: commandName,
+            duration_ms,
+            success: false,
+            node_version: process.version,
+            vlt_version: vltVersion ?? 'unknown',
+            os: process.platform,
+            arch: process.arch,
+            ci: isCI(),
+        }, telemetryEnabled);
+        const errorCode = (err instanceof Error &&
+            err.cause &&
+            typeof err.cause === 'object' &&
+            'code' in err.cause &&
+            typeof err.cause.code === 'string') ?
+            err.cause.code
+            : undefined;
+        trackError({
+            command: commandName,
+            error_code: errorCode,
+        }, telemetryEnabled);
+        await flushTelemetry();
         printErr(err, usage, stderr, {
             ...formatOptions,
             colors: stderrColor,
@@ -123,4 +177,3 @@ export const outputCommand = async (cliCommand, conf, { start } = { start: Date.
         process.exit(process.exitCode);
     }
 };
-//# sourceMappingURL=output.js.map

package/dist/{esm/pack-tarball.d.ts → pack-tarball.d.ts}

@@ -10,7 +10,22 @@ export type PackTarballResult = {
     files: string[];
     integrity?: string;
     shasum?: string;
+    /** The manifest used for packing (may differ from input when publishConfig.directory is set). */
+    resolvedManifest: NormalizedManifest;
 };
+/**
+ * Build the tar filter function for packing.
+ *
+ * Follows npm's precedence rules:
+ *   1. `files` field in package.json → allowlist (ignore files are not read)
+ *   2. `.npmignore` → denylist (`.gitignore` is NOT read)
+ *   3. `.gitignore` → fallback denylist when no `.npmignore` exists
+ *
+ * Regardless of mode, always-excluded files (lockfiles, .git, node_modules,
+ * .npmrc, vlt.json, etc.) are excluded and always-included files (package.json,
+ * README, LICENSE, etc.) are included.
+ */
+export declare const buildPackFilter: (manifest: NormalizedManifest, packDir: string) => ((path: string) => boolean);
 /**
  * Create a tarball from a package directory
  * @param {NormalizedManifest} manifest - The manifest of the package to pack
@@ -19,4 +34,3 @@ export type PackTarballResult = {
  * @returns {Promise<PackTarballResult>} The manifest, filename, and tarball data (unless dry run)
  */
 export declare const packTarball: (manifest: NormalizedManifest, dir: string, config: LoadedConfig) => Promise<PackTarballResult>;
-//# sourceMappingURL=pack-tarball.d.ts.map

package/dist/{esm/pack-tarball.js → pack-tarball.js}

@@ -3,10 +3,11 @@ import { minimatch } from 'minimatch';
 import { error } from '@vltpkg/error-cause';
 import * as ssri from 'ssri';
 import assert from 'node:assert';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { Spec } from '@vltpkg/spec';
 import { join } from 'node:path';
 import { parse, stringify } from 'polite-json';
+import ignore from 'ignore';
 /**
  * Replace workspace: and catalog: specs with actual versions
  * @param {NormalizedManifest} manifest_ - The manifest to process
@@ -82,6 +83,121 @@ const replaceWorkspaceAndCatalogSpecs = (manifest_, config) => {
     }
     return manifest;
 };
+const alwaysExcludePatterns = [
+    /^\.?\/?\.git(\/|$)/,
+    /^\.?\/?node_modules(\/|$)/,
+    /^\.?\/?\.nyc_output(\/|$)/,
+    /^\.?\/?coverage(\/|$)/,
+    /^\.?\/?\.vscode(\/|$)/,
+    /^\.?\/?\.idea(\/|$)/,
+    /^\.?\/?\.DS_Store$/,
+    /^\.?\/?\.npmrc$/,
+    /^\.?\/?\.gitignore$/,
+    /^\.?\/?\.npmignore$/,
+    /^\.?\/?\.editorconfig$/,
+    /^\.?\/?package-lock\.json$/,
+    /^\.?\/?yarn\.lock$/,
+    /^\.?\/?pnpm-lock\.yaml$/,
+    /^\.?\/?bun\.lockb$/,
+    /^\.?\/?bun\.lock$/,
+    /^\.?\/?vlt-lock\.json$/,
+    /^\.?\/?vlt\.json$/,
+    /~$/,
+    /\.swp$/,
+    /\.tgz$/,
+];
+const alwaysIncludePatterns = [
+    /^README(\..*)?$/i,
+    /^CHANGELOG(\..*)?$/i,
+    /^HISTORY(\..*)?$/i,
+    /^LICENSE(\..*)?$/i,
+    /^LICENCE(\..*)?$/i,
+];
+/**
+ * Read an ignore file (.npmignore or .gitignore) and return its contents,
+ * or undefined if the file does not exist.
+ */
+const readIgnoreFile = (dir, name) => {
+    const filePath = join(dir, name);
+    if (!existsSync(filePath))
+        return undefined;
+    return readFileSync(filePath, 'utf8');
+};
+/**
+ * Build the tar filter function for packing.
+ *
+ * Follows npm's precedence rules:
+ *   1. `files` field in package.json → allowlist (ignore files are not read)
+ *   2. `.npmignore` → denylist (`.gitignore` is NOT read)
+ *   3. `.gitignore` → fallback denylist when no `.npmignore` exists
+ *
+ * Regardless of mode, always-excluded files (lockfiles, .git, node_modules,
+ * .npmrc, vlt.json, etc.) are excluded and always-included files (package.json,
+ * README, LICENSE, etc.) are included.
+ */
+export const buildPackFilter = (manifest, packDir) => {
+    const manifestWithFiles = manifest;
+    const hasFilesField = Array.isArray(manifestWithFiles.files) &&
+        manifestWithFiles.files.length > 0;
+    const hasEmptyFilesField = Array.isArray(manifestWithFiles.files) &&
+        manifestWithFiles.files.length === 0;
+    // Build ignore matcher from .npmignore or .gitignore (only when no files field)
+    let ig;
+    if (!hasFilesField && !hasEmptyFilesField) {
+        const npmignoreContent = readIgnoreFile(packDir, '.npmignore');
+        if (npmignoreContent !== undefined) {
+            ig = ignore().add(npmignoreContent);
+        }
+        else {
+            const gitignoreContent = readIgnoreFile(packDir, '.gitignore');
+            if (gitignoreContent !== undefined) {
+                ig = ignore().add(gitignoreContent);
+            }
+        }
+    }
+    return (path) => {
+        const normalizedPath = path.replace(/^\.\//, '');
+        if (path === '.' || normalizedPath === '') {
+            return true;
+        }
+        if (alwaysExcludePatterns.some(pattern => pattern.test(normalizedPath))) {
+            return false;
+        }
+        if (alwaysIncludePatterns.some(pattern => pattern.test(normalizedPath))) {
+            return true;
+        }
+        if (normalizedPath === 'package.json') {
+            return true;
+        }
+        // files field: allowlist mode
+        if (hasEmptyFilesField) {
+            return false;
+        }
+        if (hasFilesField && manifestWithFiles.files) {
+            return manifestWithFiles.files.some((pattern) => {
+                if (pattern.endsWith('/')) {
+                    const dirName = pattern.slice(0, -1);
+                    const globPattern = pattern.replace(/\/$/, '/**');
+                    const matchesDir = normalizedPath === dirName;
+                    const matchesContents = minimatch(normalizedPath, globPattern, { dot: true });
+                    return matchesDir || matchesContents;
+                }
+                const directMatch = minimatch(normalizedPath, pattern, {
+                    dot: true,
+                });
+                const isParentDir = pattern.includes('/') &&
+                    pattern.startsWith(normalizedPath + '/');
+                const isChildOfPattern = minimatch(normalizedPath, pattern + '/**', { dot: true });
+                return directMatch || isParentDir || isChildOfPattern;
+            });
+        }
+        // Ignore-file mode: apply .npmignore or .gitignore deny patterns
+        if (ig?.ignores(normalizedPath)) {
+            return false;
+        }
+        return true;
+    };
+};
 /**
  * Create a tarball from a package directory
  * @param {NormalizedManifest} manifest - The manifest of the package to pack
@@ -91,21 +207,25 @@ const replaceWorkspaceAndCatalogSpecs = (manifest_, config) => {
  */
 export const packTarball = async (manifest, dir, config) => {
     let packDir = dir;
-    // Check if publishDirectory is configured
-    const publishDirectory = config.get('publish-directory');
+    // Check if publishDirectory is configured via CLI flag or package.json publishConfig.directory
+    const cliPublishDir = config.get('publish-directory');
+    const manifestPublishDir = manifest.publishConfig?.directory;
+    const publishDirectory = cliPublishDir ?? manifestPublishDir;
     if (publishDirectory) {
+        // CLI flag paths are used as-is; publishConfig.directory is relative to the package dir
+        const resolvedPublishDir = cliPublishDir ? publishDirectory : join(dir, publishDirectory);
         // Validate that the publish directory exists and is a directory
-        assert(existsSync(publishDirectory), error(`Publish directory does not exist: ${publishDirectory}`, {
-            found: publishDirectory,
+        assert(existsSync(resolvedPublishDir), error(`Publish directory does not exist: ${resolvedPublishDir}`, {
+            found: resolvedPublishDir,
         }));
-        assert(statSync(publishDirectory).isDirectory(), error(`Publish directory is not a directory: ${publishDirectory}`, {
-            found: publishDirectory,
+        assert(statSync(resolvedPublishDir).isDirectory(), error(`Publish directory is not a directory: ${resolvedPublishDir}`, {
+            found: resolvedPublishDir,
             wanted: 'directory',
         }));
-        if (existsSync(join(publishDirectory, 'package.json'))) {
-            manifest = config.options.packageJson.read(publishDirectory);
+        if (existsSync(join(resolvedPublishDir, 'package.json'))) {
+            manifest = config.options.packageJson.read(resolvedPublishDir);
         }
-        packDir = publishDirectory;
+        packDir = resolvedPublishDir;
     }
     assert(manifest.name && manifest.version, error('Package must have a name and version'));
     const processedManifest = replaceWorkspaceAndCatalogSpecs(manifest, config);
@@ -113,91 +233,13 @@ export const packTarball = async (manifest, dir, config) => {
     const tarballName = `${manifest.name}-${manifest.version}.tgz`;
     try {
         config.options.packageJson.write(packDir, processedManifest);
+        const packFilter = buildPackFilter(manifest, packDir);
         const tarballData = await tarCreate({
             cwd: packDir,
             gzip: true,
             portable: true,
             prefix: 'package/',
-            filter: (path) => {
-                // Normalize path - remove leading './'
-                const normalizedPath = path.replace(/^\.\//, '');
-                // Always include root directory
-                if (path === '.' || normalizedPath === '') {
-                    return true;
-                }
-                // Always exclude certain files/directories
-                const alwaysExcludePatterns = [
-                    /^\.?\/?\.git(\/|$)/,
-                    /^\.?\/?node_modules(\/|$)/,
-                    /^\.?\/?\.nyc_output(\/|$)/,
-                    /^\.?\/?coverage(\/|$)/,
-                    /^\.?\/?\.DS_Store$/,
-                    /^\.?\/?\.npmrc$/,
-                    /^\.?\/?package-lock\.json$/,
-                    /^\.?\/?yarn\.lock$/,
-                    /^\.?\/?pnpm-lock\.yaml$/,
-                    /^\.?\/?bun\.lockb$/,
-                    /^\.?\/?bun\.lock$/,
-                    /^\.?\/?vlt-lock\.json$/,
-                    /~$/,
-                    /\.swp$/,
-                ];
-                if (alwaysExcludePatterns.some(pattern => pattern.test(normalizedPath))) {
-                    return false;
-                }
-                // Always include certain files
-                const alwaysIncludePatterns = [
-                    /^README(\..*)?$/i,
-                    /^CHANGELOG(\..*)?$/i,
-                    /^HISTORY(\..*)?$/i,
-                    /^LICENSE(\..*)?$/i,
-                    /^LICENCE(\..*)?$/i,
-                ];
-                if (alwaysIncludePatterns.some(pattern => pattern.test(normalizedPath))) {
-                    return true;
-                }
-                // Always include package.json
-                if (normalizedPath === 'package.json') {
-                    return true;
-                }
-                // If files field is specified in package.json, use it for inclusion
-                const manifestWithFiles = manifest;
-                if (manifestWithFiles.files &&
-                    Array.isArray(manifestWithFiles.files)) {
-                    // Empty files array means exclude everything except always-included files
-                    if (manifestWithFiles.files.length === 0) {
-                        return false;
-                    }
-                    return manifestWithFiles.files.some((pattern) => {
-                        if (pattern.endsWith('/')) {
-                            const dirName = pattern.slice(0, -1);
-                            const globPattern = pattern.replace(/\/$/, '/**');
-                            const matchesDir = normalizedPath === dirName;
-                            const matchesContents = minimatch(normalizedPath, globPattern, {
-                                dot: true,
-                            });
-                            return matchesDir || matchesContents;
-                        }
-                        // File pattern: check direct match and if this path is a directory that could contain the pattern
-                        const directMatch = minimatch(normalizedPath, pattern, {
-                            dot: true,
-                        });
-                        // Check if this path is a directory that could contain the pattern
-                        const isParentDir = pattern.includes('/') &&
-                            pattern.startsWith(normalizedPath + '/');
-                        return directMatch || isParentDir;
-                    });
-                }
-                // Default behavior when no files field - exclude common development files
-                const defaultExcludePatterns = [
-                    /^\.?\/?\.vscode(\/|$)/,
-                    /^\.?\/?\.idea(\/|$)/,
-                    /^\.?\/?\.gitignore$/,
-                    /^\.?\/?\.npmignore$/,
-                    /^\.?\/?\.editorconfig$/,
-                ];
-                return !defaultExcludePatterns.some(pattern => pattern.test(normalizedPath));
-            },
+            filter: packFilter,
         }, ['.']).concat();
         let unpackedSize = 0;
         const files = [];
@@ -239,6 +281,7 @@ export const packTarball = async (manifest, dir, config) => {
             files,
             integrity,
             shasum,
+            resolvedManifest: processedManifest,
         };
     }
     finally {
@@ -246,4 +289,3 @@ export const packTarball = async (manifest, dir, config) => {
         config.options.packageJson.write(packDir, manifest);
     }
 };
-//# sourceMappingURL=pack-tarball.js.map

package/dist/{esm/parse-add-remove-args.d.ts → parse-add-remove-args.d.ts}

@@ -1,3 +1,4 @@
+import type { PathScurry } from 'path-scurry';
 import type { AddImportersDependenciesMap, RemoveImportersDependenciesMap } from '@vltpkg/graph';
 import type { Monorepo } from '@vltpkg/workspaces';
 import type { LoadedConfig } from './config/index.ts';
@@ -17,6 +18,11 @@ export type WorkspaceTypes = {
     workspace?: string[];
     'workspace-group'?: string[];
 };
-export declare const parseAddArgs: (config: LoadedConfig, monorepo?: Monorepo) => ParsedAddArgs;
-export declare const parseRemoveArgs: (config: LoadedConfig, monorepo?: Monorepo) => ParsedRemoveArgs;
-//# sourceMappingURL=parse-add-remove-args.d.ts.map
+/**
+ * Parses the positional arguments into {@link AddImportersDependenciesMap}.
+ */
+export declare const parseAddArgs: (config: LoadedConfig, scurry: PathScurry, monorepo?: Monorepo) => ParsedAddArgs;
+/**
+ * Parses the positional arguments into {@link RemoveImportersDependenciesMap}.
+ */
+export declare const parseRemoveArgs: (config: LoadedConfig, scurry: PathScurry, monorepo?: Monorepo) => ParsedRemoveArgs;

package/dist/{esm/parse-add-remove-args.js → parse-add-remove-args.js}

@@ -1,12 +1,27 @@
-import { joinDepIDTuple } from '@vltpkg/dep-id';
 import { asDependency } from '@vltpkg/graph';
+import { joinDepIDTuple } from '@vltpkg/dep-id';
 import { Spec } from '@vltpkg/spec';
 const rootDepID = joinDepIDTuple(['file', '.']);
+/**
+ * Compute a DepID for the current working directory relative to the project
+ * root. Returns the root DepID if cwd is the project root, otherwise returns
+ * the computed DepID.
+ */
+const getCwdDepID = (scurry) => {
+    const cwd = process.cwd();
+    const relPath = scurry.relativePosix(cwd);
+    // If cwd is the project root or outside it, return root DepID
+    if (!relPath || relPath.startsWith('..')) {
+        return rootDepID;
+    }
+    // Return a DepID for the nested folder (posix-style path)
+    return joinDepIDTuple(['file', relPath.split('\\').join('/')]);
+};
 /**
  * Get the list of importers that are currently selected
  * in {@link WorkspaceTypes}.
  */
-const getImporters = (opts, monorepo) => {
+const getWorkspaceImporters = (opts, monorepo) => {
     const res = new Set();
     // collects DepID references to any selected workspace
     if (monorepo) {
@@ -14,10 +29,6 @@ const getImporters = (opts, monorepo) => {
             res.add(ws.id);
         }
     }
-    // if no references were found, default behavior is to point to project root
-    if (!res.size) {
-        res.add(rootDepID);
-    }
     return res;
 };
 const getType = (opts) => opts['save-prod'] ? 'prod'
@@ -34,38 +45,59 @@ class AddImportersDependenciesMapImpl extends Map {
 class RemoveImportersDependenciesMapImpl extends Map {
     modifiedDependencies = false;
 }
-export const parseAddArgs = (config, monorepo) => {
+/**
+ * Parses the positional arguments into {@link AddImportersDependenciesMap}.
+ */
+export const parseAddArgs = (config, scurry, monorepo) => {
     const add = new AddImportersDependenciesMapImpl();
     const items = config.positionals;
     const type = getType(config.values);
-    const importers = getImporters(config.values, monorepo);
+    const importers = getWorkspaceImporters(config.values, monorepo);
     const newDependencies = new Map();
     const specOptions = config.options;
     // nameless spec definitions will need to use their full
     // stringified spec result instead of their name in order
     // to have an unique key name in the resulting Map
     const getName = (s) => s.name === '(unknown)' ? s.spec : s.name;
+    // parses each positional argument into a Spec and
+    // adds it to the new dependencies Map
     for (const item of items) {
         const spec = Spec.parseArgs(item, specOptions);
         newDependencies.set(getName(spec), asDependency({ spec, type }));
         add.modifiedDependencies = true;
     }
+    // assigns the new dependencies to each selected workspace importer
     for (const importer of importers) {
         add.set(importer, newDependencies);
     }
+    // if no workspaces were selected, default to the cwd importer which
+    // can be either the root or a nested folder in case the user is installing
+    // from a subfolder that is also a file: type dependency
+    if (!importers.size) {
+        const cwdDepID = getCwdDepID(scurry);
+        add.set(cwdDepID, newDependencies);
+    }
     return {
         add,
     };
 };
-export const parseRemoveArgs = (config, monorepo) => {
+/**
+ * Parses the positional arguments into {@link RemoveImportersDependenciesMap}.
+ */
+export const parseRemoveArgs = (config, scurry, monorepo) => {
     const remove = new RemoveImportersDependenciesMapImpl();
-    const importers = getImporters(config.values, monorepo);
+    const importers = getWorkspaceImporters(config.values, monorepo);
     for (const importer of importers) {
         remove.set(importer, new Set(config.positionals));
         remove.modifiedDependencies = true;
     }
+    // if no workspaces were selected, default to the cwd importer
+    if (!importers.size) {
+        const cwdDepID = getCwdDepID(scurry);
+        remove.set(cwdDepID, new Set(config.positionals));
+        remove.modifiedDependencies = true;
+    }
     return {
         remove,
     };
 };
-//# sourceMappingURL=parse-add-remove-args.js.map

package/dist/{esm/print-err.d.ts → print-err.d.ts}

@@ -11,4 +11,3 @@ export type ErrorFormatOptions = InspectOptions & {
 export type Formatter = (arg: unknown, options?: ErrorFormatOptions) => string;
 export declare const indent: (lines: string, num?: number) => string;
 export declare const printErr: (e: unknown, usage: CommandUsage, stderr: (...a: string[]) => void, baseOpts?: ErrorFormatOptions) => void;
-//# sourceMappingURL=print-err.d.ts.map

package/dist/{esm/print-err.js → print-err.js}

@@ -2,8 +2,8 @@ import { splitDepID } from '@vltpkg/dep-id';
 import { parseError } from '@vltpkg/output/error';
 import { isErrorWithCause, isObject } from '@vltpkg/types';
 import { XDG } from '@vltpkg/xdg';
-import { isGraphRunError } from 'graph-run';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { isGraphRunError } from '@vltpkg/graph-run';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { formatWithOptions } from 'node:util';
 export const formatOptions = {
@@ -33,6 +33,14 @@ const writeErrorLog = (e, format) => {
         return null;
     }
 };
+const readErrorLog = (file) => {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
 export const printErr = (e, usage, stderr, baseOpts) => {
     const format = (arg, opts) => {
         const { maxLines = 200, ...rest } = {
@@ -62,6 +70,14 @@ export const printErr = (e, usage, stderr, baseOpts) => {
     if (fileWritten) {
         stderr('');
         stderr(`Full details written to: ${fileWritten}`);
+        if (process.env.CI) {
+            const fullErrorLog = readErrorLog(fileWritten);
+            if (fullErrorLog) {
+                stderr('');
+                stderr('Full details:');
+                stderr(fullErrorLog);
+            }
+        }
     }
     if (!knownError || knownError.bug) {
         stderr('');
@@ -175,4 +191,3 @@ const printCode = (err, usage, stderr, format) => {
         }
     }
 };
-//# sourceMappingURL=print-err.js.map

package/dist/query-diff-files.d.ts

@@ -0,0 +1,17 @@
+import type { DiffFilesProvider } from '@vltpkg/query';
+/**
+ * Validates that a commitish string is safe to use
+ * in a git command.
+ */
+export declare const validateCommitish: (commitish: string) => string;
+/**
+ * Creates a {@link DiffFilesProvider} that uses
+ * `git diff --name-only` to determine changed files.
+ * @param {string} projectRoot - The absolute path to the
+ *   project root directory where git commands will be
+ *   executed.
+ * @returns {DiffFilesProvider} A function that takes a
+ *   commitish and returns a Set of changed file paths
+ *   relative to the project root.
+ */
+export declare const createDiffFilesProvider: (projectRoot: string) => DiffFilesProvider;

package/dist/query-diff-files.js

@@ -0,0 +1,63 @@
+import { execSync } from 'node:child_process';
+import { error } from '@vltpkg/error-cause';
+/**
+ * Pattern to validate commitish arguments.
+ * Allows branch names, tags, SHAs, HEAD~N, HEAD^N, etc.
+ * Rejects shell metacharacters to prevent command injection.
+ */
+const VALID_COMMITISH = /^[a-zA-Z0-9_./@^~:#{}-]+$/;
+/**
+ * Validates that a commitish string is safe to use
+ * in a git command.
+ */
+export const validateCommitish = (commitish) => {
+    if (!commitish) {
+        throw error('Missing commitish argument for :diff() selector');
+    }
+    if (!VALID_COMMITISH.test(commitish)) {
+        throw error('Invalid commitish argument for :diff() selector', {
+            found: commitish,
+        });
+    }
+    return commitish;
+};
+/**
+ * Creates a {@link DiffFilesProvider} that uses
+ * `git diff --name-only` to determine changed files.
+ * @param {string} projectRoot - The absolute path to the
+ *   project root directory where git commands will be
+ *   executed.
+ * @returns {DiffFilesProvider} A function that takes a
+ *   commitish and returns a Set of changed file paths
+ *   relative to the project root.
+ */
+export const createDiffFilesProvider = (projectRoot) => {
+    // Cache results per commitish to avoid repeated git calls
+    const cache = new Map();
+    return (commitish) => {
+        const cached = cache.get(commitish);
+        if (cached)
+            return cached;
+        const safeCommitish = validateCommitish(commitish);
+        try {
+            const stdout = execSync(`git diff --name-only ${safeCommitish}`, {
+                cwd: projectRoot,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 30_000,
+            });
+            const files = new Set();
+            for (const line of stdout.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed) {
+                    files.add(trimmed);
+                }
+            }
+            cache.set(commitish, files);
+            return files;
+        }
+        catch (err) {
+            throw error(`Failed to run git diff for commitish: ${safeCommitish}`, { cause: err });
+        }
+    };
+};

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

@@ -13,4 +13,3 @@ export type HostContextsMapResult = {
  * pseudo selector to dynamically load graphs from different sources.
  */
 export declare const createHostContextsMap: (conf: LoadedConfig) => Promise<Map<string, () => Promise<HostContextsMapResult>>>;
-//# sourceMappingURL=query-host-contexts.d.ts.map