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

package/dist/commands/repo.js

@@ -0,0 +1,157 @@
+import { error } from '@vltpkg/error-cause';
+import { PackageInfoClient } from '@vltpkg/package-info';
+import { Spec } from '@vltpkg/spec';
+import { urlOpen } from '@vltpkg/url-open';
+import { actual } from '@vltpkg/graph';
+import { Query } from '@vltpkg/query';
+import { SecurityArchive } from '@vltpkg/security-archive';
+import { createHostContextsMap } from "../query-host-contexts.js";
+import { commandUsage } from "../config/usage.js";
+import hostedGitInfo from 'hosted-git-info';
+const { fromUrl: hostedGitInfoFromUrl } = hostedGitInfo;
+export const usage = () => commandUsage({
+    command: 'repo',
+    usage: ['[<spec>]', '[--target=<query>]'],
+    description: `Open repository page for a package in a web browser.
+                  Reads repository information from package.json or fetches
+                  manifest data for the specified package.`,
+    options: {
+        target: {
+            value: '<query>',
+            description: 'Query selector to filter packages using DSS syntax.',
+        },
+    },
+    examples: {
+        '': {
+            description: 'Open repo for the current package (reads local package.json)',
+        },
+        'abbrev@2.0.0': {
+            description: 'Open repo for a specific package version',
+        },
+        '--target=":root > *"': {
+            description: 'List repository URLs for all direct dependencies',
+        },
+    },
+});
+export const views = {
+    human: r => {
+        if (Array.isArray(r)) {
+            let msg = 'Multiple package repositories found:\n';
+            msg += r.map(item => `• ${item.name}: ${item.url}`).join('\n');
+            return msg;
+        }
+        return '';
+    },
+    json: r => r,
+};
+const getUrlFromManifest = (manifest) => {
+    const { name, repository, homepage } = manifest;
+    if (!name) {
+        throw error('No package name found');
+    }
+    let url;
+    // Check repository field first
+    if (repository) {
+        const repoUrl = typeof repository === 'string' ? repository
+            : typeof repository === 'object' && 'url' in repository ?
+                repository.url
+                : /* c8 ignore next */ undefined;
+        if (repoUrl) {
+            const info = hostedGitInfoFromUrl(repoUrl.replace(/^git\+/, ''));
+            if (info?.browse && typeof info.browse === 'function') {
+                url = info.browse();
+            }
+            else {
+                // Use the raw URL if hosted-git-info can't parse it
+                url = repoUrl.replace(/^git\+/, '');
+            }
+        }
+    }
+    // Fall back to homepage
+    if (!url && homepage) {
+        url = homepage;
+    }
+    // Fallback to vlt.io package page
+    if (!url) {
+        url = `https://vlt.io/explore/npm/${name}/overview`;
+    }
+    return url;
+};
+export const command = async (conf) => {
+    const { projectRoot, packageJson } = conf.options;
+    const targetOption = conf.get('target');
+    // Handle --target query
+    if (targetOption) {
+        const mainManifest = packageJson.maybeRead(projectRoot);
+        if (!mainManifest) {
+            throw error('No package.json found in project root', {
+                path: projectRoot,
+            });
+        }
+        const graph = actual.load({
+            ...conf.options,
+            mainManifest,
+            monorepo: conf.options.monorepo,
+            loadManifests: true,
+        });
+        const securityArchive = Query.hasSecuritySelectors(targetOption) ?
+            await SecurityArchive.start({
+                nodes: [...graph.nodes.values()],
+            })
+            : undefined;
+        const hostContexts = await createHostContextsMap(conf);
+        const query = new Query({
+            nodes: new Set(graph.nodes.values()),
+            edges: graph.edges,
+            importers: graph.importers,
+            securityArchive,
+            hostContexts,
+        });
+        const { nodes } = await query.search(targetOption, {
+            signal: new AbortController().signal,
+        });
+        const results = [];
+        for (const node of nodes) {
+            if (!node.manifest)
+                continue;
+            const url = getUrlFromManifest(node.manifest);
+            results.push({
+                url,
+                name: node.name /* c8 ignore next */ ?? '(unknown)',
+            });
+        }
+        if (results.length === 0) {
+            throw error('No packages found matching target query', {
+                found: targetOption,
+            });
+        }
+        // If single result, open it
+        if (results.length === 1) {
+            const result = results[0];
+            /* c8 ignore next 3 */
+            if (!result) {
+                throw error('Unexpected empty result');
+            }
+            await urlOpen(result.url);
+            return result;
+        }
+        // Multiple results, return the list
+        return results;
+    }
+    // read the package spec from a positional argument or local package.json
+    const specArg = conf.positionals[0];
+    const manifest = conf.positionals.length === 0 ? packageJson.read(projectRoot)
+        : specArg ?
+            await new PackageInfoClient(conf.options).manifest(Spec.parseArgs(specArg, conf.options))
+            : /* c8 ignore next */ packageJson.read(projectRoot);
+    const url = getUrlFromManifest(manifest);
+    const { name } = manifest;
+    /* c8 ignore start - getUrlFromManifest already validates name */
+    if (!name) {
+        throw error('No package name found');
+    }
+    /* c8 ignore stop */
+    // Open the URL
+    await urlOpen(url);
+    return { url, name };
+};

package/dist/{esm/commands/exec-local.d.ts → commands/run-exec.d.ts}

@@ -1,6 +1,6 @@
 import type { ExecResult } from '../exec-command.ts';
 import type { CommandFn, CommandUsage } from '../index.ts';
 export { views } from '../exec-command.ts';
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<ExecResult>;
-//# sourceMappingURL=exec-local.d.ts.map

package/dist/commands/run-exec.js

@@ -0,0 +1,41 @@
+import { runExec, runExecFG } from '@vltpkg/run';
+import { commandUsage } from "../config/usage.js";
+import { ExecCommand } from "../exec-command.js";
+export { views } from "../exec-command.js";
+export const needsRegistry = true;
+export const usage = () => commandUsage({
+    command: 'run-exec',
+    usage: '[command ...]',
+    description: `If the first argument is a defined script in package.json, then this is
+                  equivalent to \`vlt run\`.
+
+                  If not, then this is equivalent to \`vlt exec\`.`,
+    options: {
+        scope: {
+            value: '<query>',
+            description: 'Filter execution targets using a DSS query.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit execution to matching workspace paths or globs.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit execution to named workspace groups.',
+        },
+        recursive: {
+            description: 'Run across all selected workspaces.',
+        },
+        'if-present': {
+            description: 'When running across multiple packages, only include packages with matching scripts.',
+        },
+        bail: {
+            description: 'When running across multiple workspaces, stop on first failure.',
+        },
+        'script-shell': {
+            value: '<program>',
+            description: 'Shell to use when executing package.json scripts.',
+        },
+    },
+});
+export const command = async (conf) => await new ExecCommand(conf, runExec, runExecFG).run();

package/dist/{esm/commands → commands}/run.d.ts

@@ -3,4 +3,3 @@ import type { CommandFn, CommandUsage } from '../index.ts';
 export { views } from '../exec-command.ts';
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<ExecResult>;
-//# sourceMappingURL=run.d.ts.map

package/dist/{esm/commands → commands}/run.js

@@ -9,6 +9,33 @@ export const usage = () => commandUsage({
                   arguments. Note that vlt config values must be specified *before*
                   the script name, because everything after that is handed off to
                   the script process.`,
+    options: {
+        scope: {
+            value: '<query>',
+            description: 'Filter execution targets using a DSS query.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit execution to matching workspace paths or globs.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit execution to named workspace groups.',
+        },
+        recursive: {
+            description: 'Run across all selected workspaces.',
+        },
+        'if-present': {
+            description: 'When running across multiple packages, only include packages with matching scripts.',
+        },
+        bail: {
+            description: 'When running across multiple workspaces, stop on first failure.',
+        },
+        'script-shell': {
+            value: '<program>',
+            description: 'Shell to use when executing package.json scripts.',
+        },
+    },
 });
 class RunCommand extends ExecCommand {
     constructor(conf) {
@@ -33,4 +60,3 @@ class RunCommand extends ExecCommand {
     }
 }
 export const command = async (conf) => await new RunCommand(conf).run();
-//# sourceMappingURL=run.js.map

package/dist/commands/setup.d.ts

@@ -0,0 +1,25 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+/** Where users sign up for / log into a vlt.io account. */
+export declare const VLT_SIGNUP_URL = "https://www.vlt.io";
+/** Base URL that per-account registries live under. */
+export declare const VLT_REGISTRY_BASE = "https://registry.vlt.io";
+/**
+ * The registry aliases that every vlt.io account is provisioned with.
+ * `npm` is the {@link https://docs.vlt.sh | default bare-spec alias}.
+ */
+export declare const accountRegistries: readonly ["npm", "main"];
+/** Build the per-account registry URL for a given registry name. */
+export declare const accountRegistryURL: (account: string, name: string) => string;
+export type SetupResult = {
+    /** the account slug the registries were built for */
+    account: string;
+    /** which config file the registries were written to */
+    which: 'user' | 'project';
+    /** the alias -> url map that was staged into config */
+    registries: Record<string, string>;
+};
+export declare const views: {
+    readonly human: (result: SetupResult) => string;
+};
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<SetupResult>;

package/dist/commands/setup.js

@@ -0,0 +1,142 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { defaultRegistries } from '@vltpkg/spec';
+import { createInterface } from 'node:readline/promises';
+import { commandUsage } from "../config/usage.js";
+import { stdout } from "../output.js";
+/** Where users sign up for / log into a vlt.io account. */
+export const VLT_SIGNUP_URL = 'https://www.vlt.io';
+/** Base URL that per-account registries live under. */
+export const VLT_REGISTRY_BASE = 'https://registry.vlt.io';
+/**
+ * The registry aliases that every vlt.io account is provisioned with.
+ * `npm` is the {@link https://docs.vlt.sh | default bare-spec alias}.
+ */
+export const accountRegistries = ['npm', 'main'];
+/** Build the per-account registry URL for a given registry name. */
+export const accountRegistryURL = (account, name) => `${VLT_REGISTRY_BASE}/${encodeURIComponent(account)}/${name}/`;
+/** Ensure a registry URL ends with a single trailing slash. */
+const normalizeRegistryURL = (url) => url.endsWith('/') ? url : `${url}/`;
+export const views = {
+    human: (result) => {
+        const lines = [
+            `Configured ${Object.keys(result.registries).length} registry ${Object.keys(result.registries).length === 1 ?
+                'alias'
+                : 'aliases'} for "${result.account}" in ${result.which} config:`,
+        ];
+        for (const [name, url] of Object.entries(result.registries)) {
+            lines.push(`  ${name} -> ${url}`);
+        }
+        lines.push('', 'You can now install packages, e.g.:', '  vlt install <pkg>');
+        return lines.join('\n');
+    },
+};
+export const usage = () => commandUsage({
+    command: 'setup',
+    usage: '[<account>]',
+    description: `Configure the registry aliases for your vlt.io account so
+                  that \`vlt install\` and \`vlx\` work out of the box.
+
+                  Sign up or log in at ${VLT_SIGNUP_URL} first. The wizard
+                  authenticates against your account and writes the
+                  \`npm\` and \`main\` registry aliases (and any additional
+                  aliases you add) to your user \`vlt.json\`.`,
+    options: {
+        config: {
+            value: '<user | project>',
+            description: 'Which config file to write to. Defaults to `user`; pass ' +
+                '`--config=project` to write to the project `vlt.json`.',
+        },
+        registries: {
+            value: '<name=url>',
+            description: 'Additional registry aliases to stage non-interactively. ' +
+                'Combine with `--yes` to run setup unattended.',
+        },
+        yes: {
+            description: 'Skip interactive prompts (requires <account> and does not ' +
+                'open a browser for authentication).',
+        },
+    },
+});
+export const command = async (conf) => {
+    const yes = !!conf.get('yes');
+    const which = conf.get('config') === 'project' ? 'project' : 'user';
+    let rl;
+    const ask = async (question) => {
+        rl ??= createInterface(process.stdin, process.stdout);
+        return (await rl.question(question)).trim();
+    };
+    try {
+        stdout(`Sign up or log in at ${VLT_SIGNUP_URL} before continuing.`);
+        // 1. resolve the account slug
+        let account = conf.positionals[0]?.trim();
+        if (!account) {
+            if (yes) {
+                throw error('An account slug is required in non-interactive mode. ' +
+                    'Pass it as an argument: `vlt setup <account> --yes`.', { code: 'ECONFIG' });
+            }
+            account = await ask('vlt.io account or organization slug: ');
+            if (!account) {
+                throw error('No account slug provided.', { code: 'ECONFIG' });
+            }
+        }
+        // 2. stage the two known account registries
+        const registries = {};
+        for (const name of accountRegistries) {
+            registries[name] = accountRegistryURL(account, name);
+        }
+        // 3. merge any user-supplied registry aliases (skip built-in defaults)
+        const builtinRegistries = defaultRegistries;
+        for (const [name, url] of Object.entries(conf.options.registries)) {
+            if (builtinRegistries[name] === url)
+                continue;
+            registries[name] = normalizeRegistryURL(url);
+        }
+        const rc = new RegistryClient(conf.options);
+        // 4. authenticate against the account registries (interactive only)
+        if (!yes) {
+            const doAuth = await ask('Authenticate with your vlt.io account now? (Y/n) ');
+            if (!/^n/i.test(doAuth)) {
+                for (const name of accountRegistries) {
+                    stdout(`Authenticating against the "${name}" registry...`);
+                    await rc.login(accountRegistryURL(account, name));
+                }
+            }
+            // 5. offer to add further custom aliases
+            for (;;) {
+                const more = await ask('Add another registry alias? (y/N) ');
+                if (!/^y/i.test(more))
+                    break;
+                const name = await ask('  alias name: ');
+                if (!name) {
+                    stdout('  alias name is required, skipping.');
+                    continue;
+                }
+                if (name in registries) {
+                    stdout(`  alias "${name}" is already staged, skipping.`);
+                    continue;
+                }
+                const url = await ask('  registry url: ');
+                if (!url) {
+                    stdout('  registry url is required, skipping.');
+                    continue;
+                }
+                const normalized = normalizeRegistryURL(url);
+                registries[name] = normalized;
+                const auth = await ask(`  authenticate against "${name}" now? (y/N) `);
+                if (/^y/i.test(auth)) {
+                    await rc.login(normalized);
+                }
+            }
+        }
+        // 6. persist the staged registries (merged, not clobbered)
+        await conf.addConfigToFile(which, { registries });
+        return { account, which, registries };
+    }
+    finally {
+        if (rl) {
+            rl.close();
+            process.stdin.pause();
+        }
+    }
+};

package/dist/commands/token.d.ts

@@ -0,0 +1,32 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export type TokenInfo = {
+    /** The server-side key/id for the token */
+    key: string;
+    /** A truncated prefix of the token value */
+    token: string;
+    /** ISO date when the token was created */
+    created: string;
+    /** Whether this token is read-only */
+    readonly: boolean;
+    /** CIDR whitelist, if any */
+    cidr_whitelist?: string[];
+};
+export type RegistryTokens = {
+    registry: string;
+    alias?: string;
+    /** Masked local keychain token, if stored */
+    localToken?: string;
+    tokens: TokenInfo[];
+    error?: string;
+};
+export type TokenListResult = {
+    identity: string;
+    registries: RegistryTokens[];
+};
+export declare const needsRegistry = true;
+export declare const usage: CommandUsage;
+export declare const views: {
+    readonly human: (r: TokenListResult | void) => string | undefined;
+    readonly json: (r: TokenListResult | void) => TokenListResult | undefined;
+};
+export declare const command: CommandFn<TokenListResult | void>;

package/dist/commands/token.js

@@ -0,0 +1,193 @@
+import { error } from '@vltpkg/error-cause';
+import { deleteToken, getKC, getToken, normalizeRegistryKey, registryBase, RegistryClient, setToken, } from '@vltpkg/registry-client';
+import { commandUsage } from "../config/usage.js";
+import { readPassword } from "../read-password.js";
+import { requireRegistry } from "../require-registry.js";
+export const needsRegistry = true;
+export const usage = () => commandUsage({
+    command: 'token',
+    usage: ['list', 'add', 'rm'],
+    description: `Manage registry authentication tokens in the vlt keychain.
+
+                  Target a specific configured registry by alias with
+                  \`vlt registry <alias> token <subcommand>\`.`,
+    subcommands: {
+        list: {
+            usage: '',
+            description: `List tokens for configured registries. Shows
+                      locally stored auth tokens and queries each
+                      registry's token API for remote token metadata.`,
+        },
+        add: {
+            usage: '',
+            description: `Add a token for the specified registry.
+                      You will be prompted to paste the bearer token.`,
+        },
+        rm: {
+            usage: '',
+            description: `Remove the stored token for the specified registry.`,
+        },
+    },
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'Registry URL to manage tokens for.',
+        },
+        registries: {
+            value: '<alias=url>',
+            description: 'Named registry aliases (used by the list subcommand).',
+        },
+        identity: {
+            value: '<name>',
+            description: 'Identity namespace used to store auth tokens.',
+        },
+    },
+});
+const formatDate = (iso) => {
+    const d = new Date(iso);
+    return d.toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+    });
+};
+const maskToken = (token) => {
+    const bare = token.replace(/^(Bearer|Basic)\s+/i, '');
+    if (bare.length <= 8)
+        return bare + '…';
+    return bare.slice(0, 8) + '…';
+};
+const formatTokenEntry = (t) => {
+    const parts = [
+        `key: ${t.key}`,
+        `token: ${t.token}…`,
+        `created: ${formatDate(t.created)}`,
+        `readonly: ${t.readonly ? 'yes' : 'no'}`,
+    ];
+    if (t.cidr_whitelist && t.cidr_whitelist.length > 0) {
+        parts.push(`cidr: ${t.cidr_whitelist.join(', ')}`);
+    }
+    return parts.join(' │ ');
+};
+const formatRegistryTokens = (r) => {
+    const header = r.alias ? `${r.alias} (${r.registry})` : r.registry;
+    const lines = [header];
+    lines.push(`  local: ${r.localToken ? maskToken(r.localToken) : '(none)'}`);
+    if (!r.localToken) {
+        lines.push('  (skipped remote query — no auth token)');
+    }
+    else if (r.error) {
+        lines.push(`  error: ${r.error}`);
+    }
+    else if (r.tokens.length === 0) {
+        lines.push('  (no remote tokens found)');
+    }
+    else {
+        for (const t of r.tokens) {
+            lines.push(`  ${formatTokenEntry(t)}`);
+        }
+    }
+    return lines.join('\n');
+};
+export const views = {
+    human: (r) => {
+        if (!r)
+            return;
+        const header = r.identity ? `identity: ${r.identity}` : 'identity: (default)';
+        return [header, ...r.registries.map(formatRegistryTokens)].join('\n\n');
+    },
+    json: (r) => {
+        if (!r)
+            return;
+        return r;
+    },
+};
+const listTokens = async (rc, registry, identity, alias) => {
+    const localTok = await getToken(normalizeRegistryKey(registry), identity);
+    if (!localTok) {
+        return { registry, alias, tokens: [] };
+    }
+    const tokensUrl = new URL('-/npm/v1/tokens', registryBase(registry));
+    try {
+        const objects = await rc.scroll(tokensUrl, {
+            useCache: false,
+        });
+        return {
+            registry,
+            alias,
+            localToken: localTok,
+            tokens: objects.map(o => ({
+                key: o.key,
+                token: o.token,
+                created: o.created,
+                readonly: o.readonly,
+                cidr_whitelist: o.cidr_whitelist,
+            })),
+        };
+    }
+    catch (err) {
+        return {
+            registry,
+            alias,
+            localToken: localTok,
+            tokens: [],
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+export const command = async (conf) => {
+    const reg = normalizeRegistryKey(requireRegistry(conf));
+    switch (conf.positionals[0]) {
+        case 'ls':
+        case 'list': {
+            const rc = new RegistryClient(conf.options);
+            const identity = conf.options.identity;
+            const registries = [];
+            const seen = new Set();
+            // Always query the default registry first
+            const defaultReg = requireRegistry(conf);
+            seen.add(normalizeRegistryKey(defaultReg));
+            registries.push(await listTokens(rc, defaultReg, identity, 'default'));
+            // Then query all configured registry aliases
+            const configuredRegistries = conf.options.registries;
+            for (const [alias, registry] of Object.entries(configuredRegistries)) {
+                const key = normalizeRegistryKey(registry);
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    registries.push(await listTokens(rc, registry, identity, alias));
+                }
+            }
+            // Also show any keychain entries for registries not
+            // already covered (e.g. added via `vlt token add --registry`)
+            const kc = getKC(identity);
+            for (const key of await kc.keys()) {
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    const tok = await kc.get(key);
+                    registries.push({
+                        registry: key,
+                        localToken: tok ?? undefined,
+                        tokens: [],
+                    });
+                }
+            }
+            return { identity, registries };
+        }
+        case 'add': {
+            await setToken(reg, `Bearer ${await readPassword('Paste bearer token: ')}`, conf.options.identity);
+            break;
+        }
+        case 'remove':
+        case 'rm': {
+            await deleteToken(reg, conf.options.identity);
+            break;
+        }
+        default: {
+            throw error('Invalid token subcommand', {
+                found: conf.positionals[0],
+                validOptions: ['list', 'ls', 'add', 'rm', 'remove'],
+                code: 'EUSAGE',
+            });
+        }
+    }
+};

package/dist/{esm/commands → commands}/uninstall.d.ts

@@ -7,10 +7,10 @@ export type UninstallResult = {
      */
     graph: Graph;
 };
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
     readonly json: (i: UninstallResult) => import("@vltpkg/graph").LockfileData;
     readonly human: typeof InstallReporter;
 };
 export declare const command: CommandFn<UninstallResult>;
-//# sourceMappingURL=uninstall.d.ts.map