@software-dlc/cli 0.157.2

package/dist/packages-browse.js

@@ -0,0 +1,646 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { compareSemver, defaultPackageView, graphPackageContentTypes, isSemver, latestVersion, markChange, packageDiffView, readVersionDocument, renderTextView } from '@software-dlc/graph/packages';
+import { DEFAULT_GRAPH_PACKAGES_ORIGIN, GRAPH_PACKAGES_SNAPSHOT_INDEX, GraphPackagesLockError, cacheGraphPackageIndex, cacheGraphPackageVersion, defaultGraphPackagesCacheDir, downloadLockedVersion, fetchPackageIndexByCoordinate, fetchPackageIndexById, listCachedGraphPackageVersions, readCachedGraphPackageIndex } from './graph-packages-lock.js';
+import { ownPackageName } from './own-package.js';
+/** Splits `@scope/name@1.2.0` into its coordinate and version; the version is optional. */
+export function parsePackageSpec(spec) {
+    const at = spec.lastIndexOf('@');
+    if (at > 0)
+        return {
+            coordinate: spec.slice(0, at),
+            version: spec.slice(at + 1) || null
+        };
+    return { coordinate: spec, version: null };
+}
+/**
+ * Browsing graph packages offline (docs/specs/graph-packages.md, Browsing and Offline to online):
+ * `sdlc packages list|show|diff` read the bundled snapshot (generated/graph-packages, which the
+ * build writes from graph-packages.lock.json) and the download cache, with no account and no
+ * network. `sdlc packages fetch` reads public indexes and downloads newer versions into the cache.
+ * Every document is checked against its content hash before it is shown.
+ */
+export const BROWSE_ACTIONS = ['list', 'show', 'diff', 'fetch'];
+export const PACKAGES_BROWSE_USAGE = 'Usage: sdlc packages list [--json]\n' +
+    '       sdlc packages show <coordinate>[@<version>] [--json]\n' +
+    '       sdlc packages diff <coordinate> <from-version> <to-version> [--json]\n' +
+    '       sdlc packages fetch [<coordinate>[@<version>]] [--origin <url>]\n' +
+    'Browse graph packages offline, with no account: the public packages bundled with this sdlc and the versions in the download cache. ' +
+    "list shows each package and its versions held here; show prints a version (default: the latest held that is not withdrawn) through its content type's view, with its version history and lineage; " +
+    "diff prints what changed between two versions, with the content type's marks and the gates they need. " +
+    'fetch needs the network but no account: it reads the public index of each package held here, or of the named one, and downloads each newer version that is not withdrawn (or the named version) into the download cache. ' +
+    'The origin is https://www.softwaredlc.com unless --origin or SDLC_GRAPH_PACKAGES_ORIGIN names another; SDLC_GRAPH_PACKAGES_BYPASS passes a protected (staging) origin. ' +
+    'The cache is SDLC_GRAPH_PACKAGES_CACHE, else under XDG_CACHE_HOME or ~/.cache. ' +
+    'Exit 0: done; 1: refused, with the reason on stderr.';
+/** The bundled snapshot as built: `generated/graph-packages` of the installed package. */
+export function defaultGraphPackagesSnapshotDir() {
+    return fileURLToPath(new URL('../generated/graph-packages', import.meta.url));
+}
+/**
+ * Every package held here: the bundled snapshot's versions, then the download cache's, each
+ * checked against its content hash. A bundled version that fails its hash is an error (the install
+ * is damaged); a cached one is reported and skipped.
+ */
+export function readLocalPackages(options) {
+    const warnings = [];
+    const by_id = new Map();
+    const hold = (held) => {
+        const document = held.document;
+        let entry = by_id.get(document.package.id);
+        if (!entry) {
+            entry = {
+                id: document.package.id,
+                coordinate: document.package.coordinate,
+                content_type: document.package.content_type,
+                owner_slug: document.package.owner_slug,
+                display_name: document.package.display_name,
+                description: document.package.description,
+                held: [],
+                index: null
+            };
+            by_id.set(document.package.id, entry);
+        }
+        const same = entry.held.find((other) => other.version === held.version);
+        if (same) {
+            if (same.content_hash !== held.content_hash) {
+                warnings.push(`${entry.coordinate}@${held.version}: the ${held.source} copy (${held.content_hash}) differs from the ${same.source} one (${same.content_hash}); showing the ${same.source} one`);
+            }
+            return;
+        }
+        entry.held.push(held);
+    };
+    for (const held of readSnapshot(options.snapshotDir, warnings))
+        hold(held);
+    for (const cached of listCachedGraphPackageVersions(options.cacheDir)) {
+        if ('tampered' in cached) {
+            warnings.push(cached.tampered);
+            continue;
+        }
+        try {
+            const { document, content_hash } = readVersionDocument(Buffer.from(cached.bytes).toString('utf8'), cached.content_hash);
+            hold({
+                version: document.version,
+                content_hash,
+                source: 'cached',
+                document
+            });
+        }
+        catch (error) {
+            warnings.push(`${cached.file} is not a valid version document: ${error.message}`);
+        }
+    }
+    for (const entry of by_id.values()) {
+        entry.held.sort((a, b) => compareSemver(b.version, a.version));
+        const newest = entry.held[0].document.package;
+        Object.assign(entry, {
+            coordinate: newest.coordinate,
+            content_type: newest.content_type,
+            owner_slug: newest.owner_slug,
+            display_name: newest.display_name,
+            description: newest.description
+        });
+        const indexBytes = readCachedGraphPackageIndex(entry.id, options.cacheDir);
+        if (indexBytes) {
+            const index = readCachedIndex(entry.id, indexBytes);
+            if (typeof index === 'string')
+                warnings.push(index);
+            else {
+                entry.index = index.index;
+                if (index.coordinate)
+                    entry.coordinate = index.coordinate;
+            }
+        }
+    }
+    const packages = [...by_id.values()].sort((a, b) => a.coordinate < b.coordinate ? -1 : a.coordinate > b.coordinate ? 1 : 0);
+    return { packages, warnings };
+}
+function readSnapshot(dir, warnings) {
+    const indexPath = path.join(dir, GRAPH_PACKAGES_SNAPSHOT_INDEX);
+    if (!existsSync(indexPath)) {
+        warnings.push(`no bundled snapshot at ${dir}: this sdlc was not built with one, so only the download cache is read`);
+        return [];
+    }
+    let listed;
+    try {
+        listed = JSON.parse(readFileSync(indexPath, 'utf8')).packages;
+        if (!Array.isArray(listed))
+            throw new Error('packages must be a list');
+    }
+    catch (error) {
+        throw new GraphPackagesLockError(`${indexPath} cannot be read (${error.message}); reinstall or rebuild ${ownPackageName()}`);
+    }
+    return listed.map((entry) => {
+        const file = path.join(dir, String(entry.file));
+        const label = `${String(entry.coordinate)}@${String(entry.version)}`;
+        if (!existsSync(file))
+            throw new GraphPackagesLockError(`the bundled ${label} is missing (${file}); reinstall or rebuild ${ownPackageName()}`);
+        try {
+            const { document, content_hash } = readVersionDocument(readFileSync(file, 'utf8'), String(entry.content_hash));
+            return {
+                version: document.version,
+                content_hash,
+                source: 'bundled',
+                document
+            };
+        }
+        catch (error) {
+            throw new GraphPackagesLockError(`the bundled ${label} (${file}) is damaged: ${error.message}; reinstall or rebuild ${ownPackageName()}`);
+        }
+    });
+}
+/** A cached index, read leniently: only what browsing shows. A string is why it cannot be read. */
+function readCachedIndex(id, bytes) {
+    try {
+        const value = JSON.parse(Buffer.from(bytes).toString('utf8'));
+        if (value?.package?.id !== id || !Array.isArray(value.versions))
+            throw new Error('it does not describe the package');
+        const versions = value.versions
+            .filter((entry) => isSemver(String(entry.version)))
+            .map((entry) => ({
+            version: String(entry.version),
+            content_hash: String(entry.content_hash),
+            withdrawn: entry.withdrawn === true,
+            withdrawn_reason: typeof entry.withdrawn_reason === 'string'
+                ? entry.withdrawn_reason
+                : null
+        }))
+            .sort((a, b) => compareSemver(b.version, a.version));
+        return {
+            index: {
+                visibility: typeof value.package.visibility === 'string'
+                    ? value.package.visibility
+                    : null,
+                versions,
+                latest: typeof value.latest === 'string'
+                    ? value.latest
+                    : latestVersion(versions)
+            },
+            coordinate: typeof value.package.coordinate === 'string'
+                ? value.package.coordinate
+                : null
+        };
+    }
+    catch (error) {
+        return `the cached index of ${id} cannot be read (${error.message}); run sdlc packages fetch again`;
+    }
+}
+/**
+ * The resolver's package source over what is held here (graph-packages.md, Local resolution).
+ * Every held document was checked against its hash when it was read. Neither a version
+ * document nor the public index carries the import policy yet, so it is unknown here.
+ */
+export function localPackageSource(local) {
+    return {
+        document(package_id, version) {
+            const held = local.packages
+                .find((entry) => entry.id === package_id)
+                ?.held.find((v) => v.version === version);
+            return held
+                ? { document: held.document, content_hash: held.content_hash }
+                : null;
+        },
+        importPolicy: () => null
+    };
+}
+/** The package a coordinate (or package id) names, or a refusal naming what is held. */
+export function findLocalPackage(local, name) {
+    const found = local.packages.find((entry) => entry.coordinate === name || entry.id === name);
+    if (found)
+        return found;
+    const known = local.packages.map((entry) => entry.coordinate);
+    throw new GraphPackagesLockError(`no package ${name} is held here${known.length ? ` (held: ${known.join(', ')})` : ''}; download it with sdlc packages fetch ${name}`);
+}
+export function withdrawnOf(entry, version) {
+    const listed = entry.index?.versions.find((v) => v.version === version);
+    return listed?.withdrawn ? listed : null;
+}
+/** The version `show` opens by default: the index's latest when held, else the newest held that is not withdrawn. */
+export function defaultHeldVersion(entry) {
+    const latest = entry.index?.latest;
+    const newest = newestHeld(entry, (version) => Boolean(withdrawnOf(entry, version)));
+    return ((latest && entry.held.find((v) => v.version === latest)) ||
+        entry.held.find((v) => v.version === newest) ||
+        entry.held[0]);
+}
+/** The newest held version that is not withdrawn, by the index's rule: a release before any pre-release. */
+function newestHeld(entry, withdrawn) {
+    return latestVersion(entry.held.map((v) => ({
+        version: v.version,
+        withdrawn: withdrawn(v.version)
+    })));
+}
+export function heldVersion(entry, version) {
+    const held = entry.held.find((v) => v.version === version);
+    if (held)
+        return held;
+    throw new GraphPackagesLockError(`${entry.coordinate}@${version} is not held here (held: ${entry.held.map((v) => v.version).join(', ')}); download it with sdlc packages fetch ${entry.coordinate}@${version}`);
+}
+/** A content type this sdlc does not know: its content drawn by the default view, unmarked. */
+export function contentTypeFor(registry, id) {
+    const known = registry.get(id);
+    if (known)
+        return { type: known, known: true };
+    return {
+        known: false,
+        type: {
+            id,
+            schema_version: 1,
+            label: id,
+            node_types: [],
+            edge_types: [],
+            subjects: [],
+            overridable: () => 'This sdlc does not know the content type.',
+            floors: () => [],
+            mark: () => [],
+            metadata_schema: z.unknown(),
+            view: defaultPackageView
+        }
+    };
+}
+const MAX_LINEAGE = 8;
+/** The base chain of a version, as far as the bases are held here, at most eight links. */
+export function lineageOf(local, document) {
+    const links = [];
+    let base = document.base;
+    while (base && links.length < MAX_LINEAGE) {
+        const pkg = local.packages.find((entry) => entry.id === base.package_id);
+        const held = pkg?.held.find((v) => v.version === base.version && v.content_hash === base.content_hash);
+        links.push({
+            package_id: base.package_id,
+            version: base.version,
+            mode: base.mode,
+            coordinate: held ? pkg.coordinate : null,
+            available: Boolean(held)
+        });
+        base = held ? held.document.base : null;
+    }
+    return { links, truncated: Boolean(base) };
+}
+/** `sdlc packages list|show|diff|fetch`: the exit code. */
+export async function runPackagesBrowseCommand(args, context = {}) {
+    const stdout = context.stdout ?? process.stdout;
+    const stderr = context.stderr ?? process.stderr;
+    try {
+        const [action, ...rest] = args;
+        const options = parseBrowseOptions(action, rest);
+        const env = context.env ?? process.env;
+        const cacheDir = defaultGraphPackagesCacheDir(env);
+        const snapshotDir = context.snapshotDir ?? defaultGraphPackagesSnapshotDir();
+        const registry = context.registry ?? graphPackageContentTypes;
+        if (action === 'fetch') {
+            const fetchOptions = {
+                origin: options.origin ??
+                    env.SDLC_GRAPH_PACKAGES_ORIGIN ??
+                    DEFAULT_GRAPH_PACKAGES_ORIGIN,
+                bypass: env.SDLC_GRAPH_PACKAGES_BYPASS || undefined,
+                fetchImpl: context.fetchImpl
+            };
+            const local = readLocalPackages({ snapshotDir, cacheDir });
+            for (const warning of local.warnings)
+                stderr.write(`warning: ${warning}\n`);
+            const lines = await fetchPackages(local, options.positional[0] ?? null, fetchOptions, cacheDir);
+            stdout.write(`${lines.join('\n')}\n`);
+            return 0;
+        }
+        const local = readLocalPackages({ snapshotDir, cacheDir });
+        for (const warning of local.warnings)
+            stderr.write(`warning: ${warning}\n`);
+        let output;
+        if (action === 'list')
+            output = listPackages(local, registry, options.json);
+        else if (action === 'show')
+            output = showPackage(local, registry, options.positional[0], options.json);
+        else
+            output = diffPackage(local, registry, options.positional, options.json);
+        stdout.write(`${output}\n`);
+        return 0;
+    }
+    catch (error) {
+        stderr.write(`sdlc packages: ${error.message}\n`);
+        return 1;
+    }
+}
+const POSITIONALS = {
+    list: [0, 0, 'sdlc packages list [--json]'],
+    show: [1, 1, 'sdlc packages show <coordinate>[@<version>] [--json]'],
+    diff: [
+        3,
+        3,
+        'sdlc packages diff <coordinate> <from-version> <to-version> [--json]'
+    ],
+    fetch: [
+        0,
+        1,
+        'sdlc packages fetch [<coordinate>[@<version>]] [--origin <url>]'
+    ]
+};
+function parseBrowseOptions(action, args) {
+    const [min, max, usage] = POSITIONALS[action];
+    const positional = [];
+    let json = false;
+    let origin;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--json' && action !== 'fetch')
+            json = true;
+        else if (arg === '--origin' && action === 'fetch') {
+            const value = args[i + 1];
+            if (!value || value.startsWith('--'))
+                throw new GraphPackagesLockError('--origin needs a value');
+            origin = value;
+            i += 1;
+        }
+        else if (arg.startsWith('--'))
+            throw new GraphPackagesLockError(`unexpected option ${arg}; usage: ${usage}`);
+        else
+            positional.push(arg);
+    }
+    if (positional.length < min || positional.length > max)
+        throw new GraphPackagesLockError(`usage: ${usage}`);
+    return { positional, json, origin };
+}
+function versionNote(entry, version) {
+    const withdrawn = withdrawnOf(entry, version);
+    return withdrawn
+        ? ` withdrawn${withdrawn.withdrawn_reason ? `: ${withdrawn.withdrawn_reason}` : ''}`
+        : '';
+}
+function listPackages(local, registry, json) {
+    if (json) {
+        return JSON.stringify({
+            packages: local.packages.map((entry) => ({
+                id: entry.id,
+                coordinate: entry.coordinate,
+                content_type: entry.content_type,
+                content_type_known: Boolean(registry.get(entry.content_type)),
+                display_name: entry.display_name,
+                latest: entry.index?.latest ?? null,
+                held: entry.held.map((v) => ({
+                    version: v.version,
+                    content_hash: v.content_hash,
+                    source: v.source,
+                    withdrawn: Boolean(withdrawnOf(entry, v.version))
+                }))
+            })),
+            warnings: local.warnings
+        }, null, 2);
+    }
+    if (local.packages.length === 0) {
+        return 'No graph packages are held here: none is bundled with this sdlc and the download cache has none. Download a public package with sdlc packages fetch <coordinate>.';
+    }
+    const lines = [];
+    for (const entry of local.packages) {
+        const known = registry.get(entry.content_type)
+            ? ''
+            : ', not known to this sdlc';
+        lines.push(`${entry.coordinate}  ${entry.display_name} (${entry.content_type}${known})`);
+        const held = entry.held
+            .map((v) => `${v.version} ${v.source}${versionNote(entry, v.version)}`)
+            .join(', ');
+        lines.push(`  held: ${held}`);
+        const latest = entry.index?.latest;
+        if (latest && !entry.held.some((v) => v.version === latest))
+            lines.push(`  latest: ${latest}, not held; sdlc packages fetch ${entry.coordinate} downloads it`);
+        else if (latest)
+            lines.push(`  latest: ${latest}`);
+        else
+            lines.push('  latest: unknown; sdlc packages fetch reads the public index');
+    }
+    return lines.join('\n');
+}
+function showPackage(local, registry, spec, json) {
+    const { coordinate, version } = parsePackageSpec(spec);
+    const entry = findLocalPackage(local, coordinate);
+    const held = version
+        ? heldVersion(entry, version)
+        : defaultHeldVersion(entry);
+    const { type, known } = contentTypeFor(registry, entry.content_type);
+    const view = type.view(held.document.content);
+    const lineage = lineageOf(local, held.document);
+    const history = versionHistory(entry);
+    if (json) {
+        return JSON.stringify({
+            package: {
+                id: entry.id,
+                coordinate: entry.coordinate,
+                content_type: entry.content_type,
+                content_type_known: known,
+                owner_slug: entry.owner_slug,
+                display_name: entry.display_name,
+                description: entry.description,
+                visibility: entry.index?.visibility ?? null
+            },
+            version: {
+                version: held.version,
+                content_hash: held.content_hash,
+                source: held.source,
+                published_at: held.document.published_at,
+                withdrawn: Boolean(withdrawnOf(entry, held.version)),
+                base: held.document.base,
+                metadata: held.document.metadata
+            },
+            versions: history,
+            lineage,
+            view
+        }, null, 2);
+    }
+    const lines = [
+        `${entry.coordinate}@${held.version}  ${entry.display_name}`,
+        `owner ${entry.owner_slug} · content type ${entry.content_type}${known ? '' : ' (not known to this sdlc; drawn with the default view)'}${entry.index?.visibility ? ` · ${entry.index.visibility}` : ''}`
+    ];
+    if (entry.description)
+        lines.push(entry.description);
+    lines.push(`version ${held.version}, published ${held.document.published_at}, ${held.source}, ${held.content_hash}${versionNote(entry, held.version)}`);
+    lines.push('', 'Versions');
+    for (const item of history) {
+        const where = item.held ?? 'not held';
+        const flags = [
+            item.version === entry.index?.latest ? 'latest' : null,
+            item.withdrawn
+                ? `withdrawn${item.withdrawn_reason ? `: ${item.withdrawn_reason}` : ''}`
+                : null
+        ].filter(Boolean);
+        const mark = item.version === held.version ? '*' : ' ';
+        lines.push(`${mark} ${item.version}  ${where}${flags.length ? `  (${flags.join('; ')})` : ''}`);
+    }
+    lines.push('', 'Lineage');
+    if (lineage.links.length === 0)
+        lines.push('  no base: this version is the start of its chain');
+    for (const link of lineage.links) {
+        lines.push(link.available
+            ? `  ${link.mode} ${link.coordinate}@${link.version}`
+            : `  ${link.mode} package ${link.package_id} ${link.version}: not available here`);
+    }
+    if (lineage.truncated)
+        lines.push(`  earlier versions are not shown (the first ${MAX_LINEAGE} links)`);
+    lines.push('', renderOrEmpty(view));
+    return lines.join('\n');
+}
+function versionHistory(entry) {
+    const versions = new Set([
+        ...entry.held.map((v) => v.version),
+        ...(entry.index?.versions.map((v) => v.version) ?? [])
+    ]);
+    return [...versions]
+        .sort((a, b) => compareSemver(b, a))
+        .map((version) => {
+        const listed = entry.index?.versions.find((v) => v.version === version);
+        return {
+            version,
+            held: entry.held.find((v) => v.version === version)?.source ?? null,
+            withdrawn: listed?.withdrawn ?? false,
+            withdrawn_reason: listed?.withdrawn_reason ?? null
+        };
+    });
+}
+function renderOrEmpty(view) {
+    return view.sections.length
+        ? renderTextView(view)
+        : 'The version has no content.';
+}
+function diffPackage(local, registry, [name, from, to], json) {
+    const entry = findLocalPackage(local, name);
+    const before = heldVersion(entry, from);
+    const after = heldVersion(entry, to);
+    const { type, known } = contentTypeFor(registry, entry.content_type);
+    const change = markChange({
+        content_type: type,
+        before: before.document.content,
+        after: after.document.content
+    });
+    const view = packageDiffView({
+        content_type: type,
+        before: before.document.content,
+        after: after.document.content
+    });
+    if (json) {
+        return JSON.stringify({
+            package: {
+                id: entry.id,
+                coordinate: entry.coordinate,
+                content_type: entry.content_type,
+                content_type_known: known
+            },
+            from: { version: from, content_hash: before.content_hash },
+            to: { version: to, content_hash: after.content_hash },
+            diff: change.diff,
+            marks: change.marks,
+            required_gates: change.required_gates,
+            view
+        }, null, 2);
+    }
+    const counts = `${change.diff.added.length} added, ${change.diff.modified.length} changed, ${change.diff.deleted.length} removed`;
+    const lines = [
+        `${entry.coordinate} ${from} → ${to}: ${counts}${change.diff.changed_keys.length ? `; also changed: ${change.diff.changed_keys.join(', ')}` : ''}`
+    ];
+    if (!known)
+        lines.push(`${entry.content_type} is not known to this sdlc: drawn with the default view, with no marks`);
+    if (change.required_gates.length)
+        lines.push(`gates the marked changes need: ${change.required_gates.join(', ')}`);
+    const changed = view.sections
+        .map((section) => ({
+        ...section,
+        items: section.items.filter((item) => item.change)
+    }))
+        .filter((section) => section.items.length);
+    lines.push('', changed.length ? renderTextView({ sections: changed }) : 'No changes.');
+    return lines.join('\n');
+}
+/**
+ * Reads the public index of each package held here, or of the named one, keeps it in the cache,
+ * and downloads into the cache each version that is not withdrawn and is newer than the newest
+ * held release (or is the index's latest), or the one named. Every download is checked against the index's hash and its ETag first.
+ */
+async function fetchPackages(local, spec, options, cacheDir) {
+    const lines = [];
+    const targets = [];
+    if (spec) {
+        const { coordinate, version } = parsePackageSpec(spec);
+        const held = local.packages.find((entry) => entry.coordinate === coordinate || entry.id === coordinate);
+        targets.push({
+            name: held?.coordinate ?? coordinate,
+            id: held?.id ?? null,
+            version
+        });
+    }
+    else {
+        for (const entry of local.packages)
+            targets.push({ name: entry.coordinate, id: entry.id, version: null });
+        if (!targets.length)
+            return [
+                'No graph packages are held here to fetch updates for; name one: sdlc packages fetch <coordinate>'
+            ];
+    }
+    for (const target of targets) {
+        let fetched;
+        try {
+            fetched = target.id
+                ? await fetchPackageIndexById(target.id, options)
+                : await fetchPackageIndexByCoordinate(target.name, options);
+        }
+        catch (error) {
+            if (spec)
+                throw error;
+            lines.push(`${target.name}: ${error.message}`);
+            continue;
+        }
+        const { index } = fetched;
+        cacheGraphPackageIndex(index.package.id, fetched.bytes, cacheDir);
+        const entry = local.packages.find((p) => p.id === index.package.id);
+        const heldVersions = new Set(entry?.held.map((v) => v.version) ?? []);
+        // Newer than the newest held release (withdrawn or not, so nothing older than a held version
+        // is downloaded), and always the index's latest: a held pre-release never hides a later release.
+        const newest = entry ? newestHeld(entry, () => false) : null;
+        const wanted = target.version
+            ? index.versions.filter((v) => v.version === target.version)
+            : index.versions.filter((v) => !v.withdrawn &&
+                isSemver(v.version) &&
+                (newest === null ||
+                    v.version === index.latest ||
+                    compareSemver(v.version, newest) > 0));
+        if (target.version && !wanted.length)
+            throw new GraphPackagesLockError(`${index.package.coordinate} has no published version ${target.version}`);
+        const downloaded = [];
+        let failure = null;
+        for (const listed of wanted.sort((a, b) => compareSemver(a.version, b.version))) {
+            if (heldVersions.has(listed.version))
+                continue;
+            const lockEntry = {
+                id: index.package.id,
+                coordinate: index.package.coordinate,
+                version: listed.version,
+                content_hash: listed.content_hash
+            };
+            try {
+                const bytes = await downloadLockedVersion(lockEntry, options);
+                readVersionDocument(Buffer.from(bytes).toString('utf8'), listed.content_hash);
+                cacheGraphPackageVersion(lockEntry, bytes, cacheDir);
+            }
+            catch (error) {
+                // Fetching everything held, one package's failure is its line; the others go on.
+                if (spec)
+                    throw error;
+                failure = error.message;
+                break;
+            }
+            downloaded.push(`${listed.version}${listed.withdrawn ? ` (withdrawn${listed.withdrawn_reason ? `: ${listed.withdrawn_reason}` : ''})` : ''}`);
+        }
+        const latest = index.latest
+            ? `; latest ${index.latest}`
+            : '; no version that is not withdrawn';
+        const done = downloaded.length
+            ? `${index.package.coordinate}: downloaded ${downloaded.join(', ')}${latest}`
+            : null;
+        if (failure)
+            lines.push(`${done ? `${done}; then ` : `${index.package.coordinate}: `}${failure}`);
+        else
+            lines.push(done ??
+                (target.version
+                    ? `${index.package.coordinate}@${target.version} is already held here${latest}`
+                    : `${index.package.coordinate}: nothing newer to download${latest}`));
+    }
+    return lines;
+}
+//# sourceMappingURL=packages-browse.js.map