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

package/dist/config/definition.js

@@ -0,0 +1,684 @@
+import { error } from '@vltpkg/error-cause';
+import { XDG } from '@vltpkg/xdg';
+import { jack } from 'jackspeak';
+export const defaultView = 
+// If stdout is a TTY, use human output
+process.stdout.isTTY ? 'human'
+    // If its not a TTY but is a CI environment, use human output
+    // TODO: make a better view option for CI environments
+    : process.env.CI ? 'human'
+        // Otherwise, use json output
+        : 'json';
+export const defaultEditor = () => process.env.EDITOR ||
+    process.env.VISUAL ||
+    (process.platform === 'win32' ?
+        `${process.env.SYSTEMROOT}\\notepad.exe`
+        : 'vi');
+const canonicalCommands = {
+    bugs: 'bugs',
+    build: 'build',
+    cache: 'cache',
+    ci: 'ci',
+    config: 'config',
+    create: 'create',
+    docs: 'docs',
+    exec: 'exec',
+    'exec-local': 'exec-local',
+    help: 'help',
+    init: 'init',
+    install: 'install',
+    login: 'login',
+    logout: 'logout',
+    list: 'list',
+    ls: 'ls',
+    pack: 'pack',
+    ping: 'ping',
+    pkg: 'pkg',
+    publish: 'publish',
+    query: 'query',
+    repo: 'repo',
+    'run-exec': 'run-exec',
+    run: 'run',
+    token: 'token',
+    uninstall: 'uninstall',
+    update: 'update',
+    'exec-cache': 'exec-cache',
+    version: 'version',
+    view: 'view',
+    whoami: 'whoami',
+};
+const aliases = {
+    i: 'install',
+    add: 'install',
+    rm: 'uninstall',
+    u: 'update',
+    p: 'pkg',
+    pub: 'publish',
+    q: 'query',
+    b: 'build',
+    r: 'run',
+    'run-script': 'run',
+    rx: 'run-exec',
+    x: 'exec',
+    xl: 'exec-local',
+    h: 'help',
+    '?': 'help',
+    info: 'view',
+    ls: 'list',
+    show: 'view',
+    xc: 'exec-cache',
+};
+/**
+ * Command aliases mapped to their canonical names
+ */
+export const commands = {
+    ...canonicalCommands,
+    ...aliases,
+};
+/**
+ * Canonical command names mapped to an array of its aliases
+ */
+export const commandAliases = Object.entries(aliases).reduce((acc, [alias, canonical]) => {
+    const commandAliases = acc.get(canonical);
+    if (commandAliases) {
+        commandAliases.push(alias);
+    }
+    else {
+        acc.set(canonical, [alias]);
+    }
+    return acc;
+}, new Map());
+export const getCommand = (s) => s && s in commands ? commands[s] : undefined;
+const xdg = new XDG('vlt');
+const cacheDir = xdg.cache();
+/**
+ * Fields that are parsed as a set of key=value pairs
+ */
+export const recordFields = [
+    'git-hosts',
+    'registries',
+    'git-host-archives',
+    'scope-registries',
+    'jsr-registries',
+];
+export const isRecordField = (s) => recordFields.includes(s);
+const stopParsingCommands = [
+    'create',
+    'run',
+    'run-exec',
+    'exec-local',
+    'exec',
+];
+let stopParsing = undefined;
+const j = jack({
+    envPrefix: 'VLT',
+    allowPositionals: true,
+    usage: `vlt [<options>] [<cmd> [<args> ...]]`,
+    stopAtPositionalTest: arg => {
+        if (stopParsing)
+            return true;
+        const a = arg;
+        // we stop parsing AFTER the thing, so you can do
+        // vlt run --vlt --configs scriptName --args --for --script
+        // or
+        // vlt exec --vlt --configs command --args --for --command
+        if (stopParsingCommands.includes(commands[a])) {
+            stopParsing = true;
+        }
+        return false;
+    },
+})
+    .heading('vlt')
+    .description(`More documentation available at <https://docs.vlt.sh>`)
+    .heading('Subcommands');
+j.description(Object.keys(canonicalCommands).join(', '), {
+    pre: true,
+}).description('Run `vlt <cmd> --help` for more information about a specific command');
+export const definition = j
+    /**
+     * Definition of all configuration values used by vlt.
+     */
+    .heading('Configuration')
+    .description(`If a \`vlt.json\` file is present in the root of the current project,
+     then that will be used as a source of configuration information.
+
+     Next, the \`vlt.json\` file in the XDG specified config directory
+     will be checked, and loaded for any fields not set in the local project.
+
+     Object type values will be merged together. Set a field to \`null\` in
+     the JSON configuration to explicitly remove it.
+
+     Command-specific fields may be set in a nested \`command\` object that
+     overrides any options defined at the top level.
+    `)
+    .flag({
+    color: {
+        short: 'c',
+        description: 'Use colors (Default for TTY)',
+    },
+    'no-color': {
+        short: 'C',
+        description: 'Do not use colors (Default for non-TTY)',
+    },
+})
+    .opt({
+    registry: {
+        hint: 'url',
+        default: 'https://registry.npmjs.org/',
+        description: `Sets the registry for fetching packages, when no registry
+                    is explicitly set on a specifier.
+
+                    For example, \`express@latest\` will be resolved by looking
+                    up the metadata from this registry.
+
+                    Note that alias specifiers starting with \`npm:\` will
+                    still map to \`https://registry.npmjs.org/\` if this is
+                    changed, unless the a new mapping is created via the
+                    \`--registries\` option.
+      `,
+    },
+})
+    .optList({
+    registries: {
+        hint: 'name=url',
+        description: `Specify named registry hosts by their prefix. To set the
+                    default registry used for non-namespaced specifiers,
+                    use the \`--registry\` option.
+
+                    Prefixes can be used as a package alias. For example:
+
+                    \`\`\`
+                    vlt --registries loc=http://reg.local install foo@loc:foo@1.x
+                    \`\`\`
+
+                    By default, the public npm registry is registered to the
+                    \`npm:\` prefix. It is not recommended to change this
+                    mapping in most cases.
+                    `,
+    },
+    'scope-registries': {
+        hint: '@scope=url',
+        description: `Map package name scopes to registry URLs.
+
+                    For example,
+                    \`--scope-registries @acme=https://registry.acme/\`
+                    would tell vlt to fetch any packages named
+                    \`@acme/...\` from the \`https://registry.acme/\`
+                    registry.
+
+                    Note: this way of specifying registries is more ambiguous,
+                    compared with using the \`--registries\` field and explicit
+                    prefixes, because instead of failing when the configuration
+                    is absent, it will instead attempt to fetch from the
+                    default registry.
+
+                    By comparison, using
+                    \`--registries acme=https://registry.acme/\` and then
+                    specifying dependencies such as \`"foo": "acme:foo@1.x"\`
+                    means that regardless of the name, the package will be
+                    fetched from the explicitly named registry, or fail if
+                    no registry is defined with that name.
+
+                    However, custom registry aliases are not supported by other
+                    package managers.`,
+    },
+    'jsr-registries': {
+        hint: 'name=url',
+        description: `Map alias names to JSR.io registry urls.
+
+                    For example,
+                    \`--jsr-registries acme=https://jsr.acme.io/\` would
+                    tell vlt to fetch any packages with the \`acme:\` registry
+                    prefix from the \`https://jsr.acme.io/\` registry, using
+                    the "npm Compatibility" translation. So for example,
+                    the package \`acme:@foo/bar\` would fetch the
+                    \`@jsr/foo__bar\` package from the \`jsr.acme.io\`
+                    registry.
+
+                    By default the \`jsr\` alias is always mapped to
+                    \`https://npm.jsr.io/\`, so existing \`jsr:\` packages will
+                    be fetched from the public \`jsr\` registry appropriately.
+                   `,
+    },
+    'git-hosts': {
+        hint: `name=template`,
+        short: 'G',
+        description: `Map a shorthand name to a git remote URL template.
+
+                    The \`template\` may contain placeholders, which will be
+                    swapped with the relevant values.
+
+                    \`$1\`, \`$2\`, etc. are replaced with the appropriate
+                    n-th path portion. For example, \`github:user/project\`
+                    would replace the \`$1\` in the template with \`user\`,
+                    and \`$2\` with \`project\`.`,
+    },
+    'git-host-archives': {
+        hint: `name=template`,
+        short: 'A',
+        description: `Similar to the \`--git-host <name>=<template>\` option,
+                    this option can define a template string that will be
+                    expanded to provide the URL to download a pre-built
+                    tarball of the git repository.
+
+                    In addition to the n-th path portion expansions performed
+                    by \`--git-host\`, this field will also expand the
+                    string \`$committish\` in the template, replacing it with
+                    the resolved git committish value to be fetched.`,
+    },
+})
+    .opt({
+    cache: {
+        hint: 'path',
+        description: `
+        Location of the vlt on-disk cache. Defaults to the platform-specific
+        directory recommended by the XDG specification.
+      `,
+        default: cacheDir,
+    },
+    tag: {
+        description: `Default \`dist-tag\` to install or publish`,
+        default: 'latest',
+    },
+    before: {
+        hint: 'date',
+        description: `Do not install any packages published after this date`,
+    },
+    os: {
+        description: `The operating system to use as the selector when choosing
+                    packages based on their \`os\` value.`,
+        default: process.platform,
+    },
+    arch: {
+        description: `CPU architecture to use as the selector when choosing
+                    packages based on their \`cpu\` value.`,
+        default: process.arch,
+    },
+    libc: {
+        description: `Override the libc family to use as the selector when choosing
+                    packages based on their \`libc\` value (e.g. glibc, musl).
+                    By default, this is auto-detected on Linux systems.`,
+    },
+    'node-version': {
+        hint: 'version',
+        description: `Node version to use when choosing packages based on
+                    their \`engines.node\` value.`,
+        default: process.version,
+    },
+})
+    .flag({
+    'git-shallow': {
+        description: `Set to force \`--depth=1\` on all git clone actions.
+                    When set explicitly to false with --no-git-shallow,
+                    then \`--depth=1\` will not be used.
+
+                    When not set explicitly, \`--depth=1\` will be used for
+                    git hosts known to support this behavior.`,
+    },
+})
+    .num({
+    'fetch-retries': {
+        hint: 'n',
+        description: `Number of retries to perform when encountering network
+                    errors or likely-transient errors from git hosts.`,
+        default: 3,
+    },
+    'fetch-retry-factor': {
+        hint: 'n',
+        description: `The exponential backoff factor to use when retrying
+                    requests due to network issues.`,
+        default: 2,
+    },
+    'fetch-retry-mintimeout': {
+        hint: 'n',
+        description: `Number of milliseconds before starting first retry`,
+        default: 0,
+    },
+    'fetch-retry-maxtimeout': {
+        hint: 'n',
+        description: `Maximum number of milliseconds between two retries`,
+        default: 30_000,
+    },
+    'stale-while-revalidate-factor': {
+        hint: 'n',
+        default: 60,
+        description: `If the server does not serve a \`stale-while-revalidate\`
+                    value in the \`cache-control\` header, then this multiplier
+                    is applied to the \`max-age\` or \`s-maxage\` values.
+
+                    By default, this is \`60\`, so for example a response that
+                    is cacheable for 5 minutes will allow a stale response
+                    while revalidating for up to 5 hours.
+
+                    If the server *does* provide a \`stale-while-revalidate\`
+                    value, then that is always used.
+
+                    Set to 0 to prevent any \`stale-while-revalidate\` behavior
+                    unless explicitly allowed by the server's \`cache-control\`
+                    header.
+      `,
+    },
+})
+    .opt({
+    identity: {
+        short: 'i',
+        validate: (v) => typeof v === 'string' && /^[a-z0-9]*$/.test(v),
+        hint: 'name',
+        default: '',
+        description: `Provide a string to define an identity for storing auth
+                    information when logging into registries.
+
+                    Authentication tokens will be stored in the XDG data
+                    directory, in \`vlt/auth/$\{identity}/keychain.json\`.
+
+                    If no identity is provided, then the default \`''\` will
+                    be used, storing the file at \`vlt/auth/keychain.json\`.
+
+                    May only contain lowercase alphanumeric characters.
+                    `,
+    },
+})
+    .optList({
+    workspace: {
+        hint: 'ws',
+        short: 'w',
+        description: `Set to limit the spaces being worked on when working on
+                    workspaces.
+
+                    Can be paths or glob patterns matching paths.
+
+                    Specifying workspaces by package.json name is not
+                    supported.`,
+    },
+    'workspace-group': {
+        description: `Specify named workspace group names to load and operate on
+                    when doing recursive operations on workspaces.`,
+    },
+})
+    .opt({
+    scope: {
+        short: 's',
+        hint: 'query',
+        description: 'Set to filter the scope of an operation using a DSS Query.',
+    },
+    target: {
+        short: 't',
+        hint: 'query',
+        description: 'Set to select packages using a DSS Query selector.',
+    },
+})
+    .flag({
+    'if-present': {
+        description: `When running scripts across multiple packages,
+                    only include packages that have the script.
+
+                    If this is not set, then the run will fail if any
+                    packages do not have the script.
+
+                    This will default to true if --scope, --workspace,
+                    --workspace-group, or --recursive is set. Otherwise,
+                    it will default to false.`,
+    },
+})
+    .flag({
+    recursive: {
+        short: 'r',
+        description: `Run an operation across multiple workspaces.
+
+                    No effect when used in non-monorepo projects.
+
+                    Implied by setting --workspace or --workspace-group. If
+                    not set, then the action is run on the project root.`,
+    },
+    bail: {
+        short: 'b',
+        description: `When running scripts across multiple workspaces, stop
+                    on the first failure.`,
+        default: true,
+    },
+    'no-bail': {
+        short: 'B',
+        description: `When running scripts across multiple workspaces, continue
+                    on failure, running the script for all workspaces.`,
+    },
+})
+    .opt({
+    config: {
+        hint: 'all | user | project',
+        description: `Specify which configuration to show or operate on when running
+                    \`vlt config\` commands. For read operations (get, pick, list):
+                    \`all\` shows merged configuration from both user and project
+                    files (default). For write operations (set, delete, edit):
+                    defaults to \`project\`. \`user\` shows/modifies only user-level
+                    configuration, \`project\` shows/modifies only project-level
+                    configuration.`,
+        validOptions: ['all', 'user', 'project'],
+        default: 'all',
+    },
+    editor: {
+        hint: 'program',
+        description: `The blocking editor to use for \`vlt config edit\` and
+                    any other cases where a file should be opened for
+                    editing.
+
+                    Defaults to the \`EDITOR\` or \`VISUAL\` env if set, or
+                    \`notepad.exe\` on Windows, or \`vi\` elsewhere.`,
+        default: defaultEditor(),
+    },
+    'script-shell': {
+        hint: 'program',
+        description: `The shell to use when executing \`package.json#scripts\`.
+
+                    For \`vlt exec\` and \`vlt exec-local\`, this is never set,
+                    meaning that command arguments are run exactly as provided.
+
+                    For \`vlt run\` (and other things that run lifecycle
+                    scripts in \`package.json#scripts\`), the entire command
+                    with all arguments is provided as a single string, meaning
+                    that some value must be provided for shell interpretation,
+                    and so for these contexts, the \`script-shell\` value will
+                    default to \`/bin/sh\` on POSIX systems or \`cmd.exe\` on
+                    Windows.
+      `,
+    },
+    'fallback-command': {
+        hint: 'command',
+        description: `The command to run when the first argument doesn't
+                    match any known commands.
+
+                    For pnpm-style behavior, set this to 'run-exec'. e.g:
+                    \`\`\`
+                    vlt config set fallback-command=run-exec
+                    \`\`\``,
+        default: 'help',
+        validOptions: Object.keys(canonicalCommands),
+    },
+})
+    .opt({
+    package: {
+        hint: 'p',
+        description: `When running \`vlt exec\`, this allows you to explicitly
+                    set the package to search for bins. If not provided, then
+                    vlt will interpret the first argument as the package, and
+                    attempt to run the default executable.`,
+    },
+})
+    .opt({
+    call: {
+        hint: 'cmd',
+        description: `When running \`vlt exec\`, provide an arbitrary command
+                    string to execute after installing and adding any specified
+                    package bins to the PATH.
+
+                    If a package is specified (via positionals or
+                    \`--package\`), it will be installed and its executables
+                    added to the PATH before the \`--call\` command runs.
+
+                    The command string is executed via the configured
+                    \`script-shell\`, or the \`SHELL\` environment variable,
+                    falling back to \`/bin/sh\` on Unix or \`cmd.exe\` on
+                    Windows. On Unix, the shell is invoked with \`-c\`; on
+                    Windows with \`/c\`.
+
+                    Example:
+                    \`vlt exec create-react-app --call="echo $PWD"\`
+                    \`vlt exec --call="echo $PWD" --scope=":workspace"\``,
+    },
+})
+    .opt({
+    view: {
+        hint: 'output',
+        default: defaultView,
+        description: `Configures the output format for commands.
+
+                    Defaults to \`human\` if stdout is a TTY, or \`json\`
+                    if it is not.
+
+                    - human: Maximally ergonomic output reporting for human
+                      consumption.
+                    - json: Parseable JSON output for machines.
+                    - inspect: Output results with \`util.inspect\`.
+                    - mermaid: Output mermaid diagramming syntax. (Only
+                      relevant for certain commands.)
+                    - svg: Render the dependency graph as an SVG image and
+                      open it. (Only relevant for certain commands.)
+                    - png: Render the dependency graph as a PNG image and
+                      open it. (Only relevant for certain commands.)
+                    - count: Output the number of dependency relationships in
+                      the result set.
+                    - silent: Suppress all output to stdout.
+
+                    If the requested view format is not supported for the
+                    current command, or if no option is provided, then it
+                    will fall back to the default.
+      `,
+        validOptions: [
+            'human',
+            'json',
+            'mermaid',
+            'svg',
+            'png',
+            'count',
+            'inspect',
+            'silent',
+        ],
+    },
+})
+    .optList({
+    'dashboard-root': {
+        hint: 'path',
+        description: `The root directory to use for the dashboard browser-based UI.
+                    If not set, the user home directory is used.`,
+    },
+})
+    .flag({
+    'save-dev': {
+        short: 'D',
+        description: `Save installed packages to a package.json file as
+                    devDependencies`,
+    },
+    'save-optional': {
+        short: 'O',
+        description: `Save installed packages to a package.json file as
+                    optionalDependencies`,
+    },
+    'save-peer': {
+        description: `Save installed packages to a package.json file as
+                    peerDependencies`,
+    },
+    'save-prod': {
+        short: 'P',
+        description: `Save installed packages into dependencies specifically.
+                    This is useful if a package already exists in
+                    devDependencies or optionalDependencies, but you want to
+                    move it to be a non-optional production dependency.`,
+    },
+})
+    .opt({
+    'expect-results': {
+        hint: 'value',
+        validate: (v) => typeof v === 'string' && /^([<>]=?)?[0-9]+$/.test(v),
+        description: `When running \`vlt query\`, this option allows you to
+                    set a expected number of resulting items.
+
+                    Accepted values are numbers and strings.
+
+                    Strings starting with \`>\`, \`<\`, \`>=\` or \`<=\`
+                    followed by a number can be used to check if the result
+                    is greater than or less than a specific number.`,
+    },
+})
+    .flag({
+    'dry-run': {
+        description: 'Run command without making any changes',
+    },
+    'expect-lockfile': {
+        description: 'Fail if lockfile is missing or out of date. Used by ci command to enforce lockfile integrity.',
+    },
+    'frozen-lockfile': {
+        description: 'Fail if lockfile is missing or out of sync with package.json. Prevents any lockfile modifications.',
+    },
+    'lockfile-only': {
+        description: 'Only update the lockfile (vlt-lock.json) and package.json files, skip all node_modules operations including package extraction and filesystem changes.',
+    },
+})
+    .opt({
+    'allow-scripts': {
+        hint: 'query',
+        description: `Filter which packages are allowed to run lifecycle scripts using DSS query syntax.
+                    When provided, only packages matching the query will execute their
+                    install, preinstall, postinstall, prepare, preprepare, and postprepare scripts.
+                    Defaults to ':not(*)' which means no scripts will be run.
+                    
+                    Example: --allow-scripts=":root > *, #my-package"
+                    Runs scripts only for direct dependencies of the current project and any occurrences
+                    of a specific dependency with the name "my-package" anywhere in the dependency graph.`,
+    },
+})
+    .opt({
+    access: {
+        description: 'Set the access level of the package',
+        validOptions: ['public', 'restricted'],
+    },
+})
+    .opt({
+    otp: {
+        description: `Provide an OTP to use when publishing a package.`,
+    },
+    'publish-directory': {
+        hint: 'path',
+        description: `Directory to use for pack and publish operations instead of the current directory.
+                    The directory must exist and nothing will be copied to it.`,
+    },
+})
+    .flag({
+    yes: {
+        short: 'y',
+        description: `Automatically accept any confirmation prompts`,
+    },
+    version: {
+        short: 'v',
+        description: 'Print the version',
+    },
+    help: {
+        short: 'h',
+        description: 'Print helpful information',
+    },
+    all: {
+        short: 'a',
+        description: 'Show all commands, bins, and flags',
+    },
+});
+export const getSortedCliOptions = () => {
+    const defs = definition.toJSON();
+    return getSortedKeys().map((k) => {
+        const def = defs[k];
+        /* c8 ignore next */
+        if (!def)
+            throw error('invalid key found', { found: k });
+        if (def.type === 'boolean')
+            return `--${k}`;
+        return `--${k}=<${def.hint ?? k}>`;
+    });
+};
+export const getSortedKeys = () => Object.keys(definition.toJSON()).sort((a, b) => a.localeCompare(b));