ghcr-cleanup-manager 1.1.0

package/dist/cleanup-summary/_cleanup-summary-markdown.js

@@ -0,0 +1,224 @@
+import { ManifestKinds } from "../core/index.js";
+import { DeletePlanValidationStatuses } from "../db/index.js";
+const _DEFAULT_MAX_DIRECT_TARGET_TAGS = 100;
+const _DEFAULT_MAX_ROOTS_PER_SECTION = 100;
+const _DEFAULT_MAX_TAG_TEXT_LENGTH = 40;
+export function renderCleanupSummaryMarkdown(summary, options) {
+    const maxDirectTargetTags = options.maxDirectTargetTags ?? _DEFAULT_MAX_DIRECT_TARGET_TAGS;
+    const maxRootsPerSection = options.maxRootsPerSection ?? _DEFAULT_MAX_ROOTS_PER_SECTION;
+    const lines = [
+        "## Cleanup Summary",
+        "",
+        "| Field | Value |",
+        "| --- | --- |",
+        `| 📦 Package | \`${_escapeInlineCode(`${summary.owner}/${summary.packageName}`)}\` |`,
+        `| ⚙️ Mode | ${summary.dryRun ? "Cleanup dry-run" : "Cleanup"} |`,
+        `| 🏷️ Selected tags | ${summary.directTargetTags.length} |`,
+        `| 🔖 Deleted tags | ${summary.changes.deletedTags} |`,
+        `| 🖼️ Deleted images | ${summary.changes.deletedImages} |`,
+        `| 📚 Deleted multi-arch manifests | ${summary.changes.deletedMultiArchManifests} |`,
+        `| 🗂️ Deleted indexes | ${summary.changes.deletedIndexes} |`,
+        `| 📄 Deleted total | ${summary.changes.deletedTotal} |`,
+        `| 🔗 Tag-only updates | ${summary.untagOnlyRoots.length} |`,
+        `| 🛡️ Blocked items | ${summary.blockedRoots.length} |`,
+        ""
+    ];
+    lines.push(..._renderPlannedDeleteBreakdown(summary));
+    lines.push(..._renderPlannerInputs(summary.plannerInputs));
+    lines.push(..._renderDirectTargetTags(summary.directTargetTags, maxDirectTargetTags));
+    lines.push(..._renderRootSection("🗑️ Deleted items", summary.fullyDeletableRoots, maxRootsPerSection));
+    lines.push(..._renderRootSection("🔗 Tags removed only", summary.untagOnlyRoots, maxRootsPerSection));
+    lines.push(..._renderRootSection("🛡️ Blocked items", summary.blockedRoots, maxRootsPerSection));
+    if (!summary.dryRun && (summary.deletedPackageVersionCount > 0 || summary.detachedTagCount > 0)) {
+        lines.push(..._renderLiveEffects(summary));
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+function _renderPlannedDeleteBreakdown(summary) {
+    const rows = [
+        { label: "Images", count: summary.changes.deletedImages },
+        { label: "Multi-arch manifests", count: summary.changes.deletedMultiArchManifests },
+        { label: "Artifact manifests", count: summary.changes.deletedArtifactManifests },
+        { label: "Signatures", count: summary.changes.deletedSignatures },
+        { label: "Attestations", count: summary.changes.deletedAttestations },
+        { label: "Generic indexes", count: summary.changes.deletedIndexes }
+    ].filter((row) => row.count > 0);
+    if (rows.length === 0) {
+        return [];
+    }
+    return [
+        "<details>",
+        "<summary>📦 Deleted item breakdown</summary>",
+        "",
+        "| Type | Count |",
+        "| --- | --- |",
+        ...rows.map((row) => `| ${row.label} | ${row.count} |`),
+        "",
+        "</details>",
+        ""
+    ];
+}
+function _renderPlannerInputs(plannerInputs) {
+    const rows = _getPlannerInputRows(plannerInputs);
+    const patternLines = _getPlannerPatternLines(plannerInputs);
+    return [
+        "<details>",
+        "<summary>⚙️ Cleanup filter</summary>",
+        "",
+        "| Filter | Value |",
+        "| --- | --- |",
+        ...(rows.length > 0 ? rows : ["| (none) | No cleanup filters recorded |"]),
+        ...(patternLines.length > 0 ? ["", ...patternLines] : []),
+        "",
+        "</details>",
+        ""
+    ];
+}
+function _renderDirectTargetTags(tags, maxDirectTargetTags) {
+    if (tags.length === 0) {
+        return [];
+    }
+    const visibleTags = tags.slice(0, maxDirectTargetTags).map((tag) => `- \`${_escapeInlineCode(tag)}\``);
+    const lines = ["<details>", "<summary>🏷️ Selected tags</summary>", "", ...visibleTags];
+    if (tags.length > maxDirectTargetTags) {
+        lines.push("", `_Showing first ${maxDirectTargetTags} of ${tags.length} selected tags._`);
+    }
+    lines.push("", "</details>", "");
+    return lines;
+}
+function _renderRootSection(title, roots, maxRootsPerSection) {
+    if (roots.length === 0) {
+        return [];
+    }
+    const lines = ["<details>", `<summary>${title}</summary>`, ""];
+    lines.push("| Version | Type | Digest | Tags | Outcome |");
+    lines.push("| --- | --- | --- | --- | --- |");
+    for (const root of roots.slice(0, maxRootsPerSection)) {
+        lines.push(`| ${root.versionId} | ${_escapeMarkdown(_describeManifestKind(root.manifestKind))} | \`${_escapeInlineCode(_shortDigest(root.digest))}\` | ${_escapeMarkdown(_formatTags(root))} | ${_escapeMarkdown(_formatReason(root))} |`);
+    }
+    lines.push("", "_Tag lists may be truncated for table width._");
+    if (roots.length > maxRootsPerSection) {
+        lines.push("", `_Showing first ${maxRootsPerSection} of ${roots.length} ${title.toLowerCase()}._`);
+    }
+    lines.push("", "</details>", "");
+    return lines;
+}
+function _renderLiveEffects(summary) {
+    const lines = ["### Applied changes", ""];
+    lines.push(`- Deleted package versions: ${summary.deletedPackageVersionCount}`);
+    lines.push(`- Detached tags: ${summary.detachedTagCount}`);
+    lines.push("");
+    return lines;
+}
+function _formatTags(root) {
+    const tags = root.rootTags.length > 0 ? root.rootTags : root.matchedTags;
+    if (tags.length === 0) {
+        return "(untagged)";
+    }
+    const joinedTags = tags.join(", ");
+    if (joinedTags.length <= _DEFAULT_MAX_TAG_TEXT_LENGTH) {
+        return joinedTags;
+    }
+    return `${joinedTags.slice(0, _DEFAULT_MAX_TAG_TEXT_LENGTH - 3)}...`;
+}
+function _formatReason(root) {
+    if (root.validationStatus === DeletePlanValidationStatuses.blocked) {
+        const blocking = root.blockingDigest ? _shortDigest(root.blockingDigest) : "another item";
+        const overlap = root.overlapDigest ? ` via ${_shortDigest(root.overlapDigest)}` : "";
+        return `Blocked by retained item ${blocking}${overlap}`;
+    }
+    if (root.validationStatus === DeletePlanValidationStatuses.untagOnly) {
+        return "Remove selected tags, keep item";
+    }
+    return "Delete item and descendants";
+}
+function _shortDigest(value) {
+    if (!value.startsWith("sha256:") || value.length <= 20) {
+        return value;
+    }
+    return `${value.slice(0, 15)}...${value.slice(-8)}`;
+}
+function _escapeInlineCode(value) {
+    return value.replaceAll("`", "\\`");
+}
+function _escapeMarkdown(value) {
+    return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+function _getPlannerInputRows(plannerInputs) {
+    const rows = [];
+    for (const [key, value] of Object.entries(plannerInputs)) {
+        rows.push(`| ${_escapeMarkdown(_plannerInputLabel(key))} | ${_escapeMarkdown(_formatPlannerInputValue(value))} |`);
+    }
+    return rows;
+}
+function _plannerInputLabel(key) {
+    switch (key) {
+        case "deleteTags":
+            return "Delete tags";
+        case "excludeTags":
+            return "Exclude tags";
+        case "useRegex":
+            return "Use regex";
+        case "deleteUntagged":
+            return "Delete untagged";
+        case "keepNTagged":
+            return "Keep newest tagged";
+        case "keepNUntagged":
+            return "Keep newest untagged";
+        case "olderThan":
+            return "Older than";
+        case "cutoffTimestamp":
+            return "Cutoff timestamp";
+        case "deleteGhostImages":
+            return "Delete ghost images";
+        case "deletePartialImages":
+            return "Delete partial images";
+        case "deleteOrphanedImages":
+            return "Delete orphaned images";
+        default:
+            return key;
+    }
+}
+function _formatPlannerInputValue(value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return "(none)";
+        }
+        return value.length === 1 ? "1 pattern" : `${value.length} patterns`;
+    }
+    if (typeof value === "boolean") {
+        return value ? "yes" : "no";
+    }
+    return String(value);
+}
+function _getPlannerPatternLines(plannerInputs) {
+    const lines = [];
+    for (const [key, value] of Object.entries(plannerInputs)) {
+        if (!Array.isArray(value) || value.length === 0) {
+            continue;
+        }
+        lines.push(`- ${_plannerInputLabel(key)}:`);
+        for (const item of value) {
+            lines.push(`  - \`${_escapeInlineCode(String(item))}\``);
+        }
+    }
+    return lines;
+}
+function _describeManifestKind(manifestKind) {
+    switch (manifestKind) {
+        case ManifestKinds.imageManifest:
+            return "image";
+        case ManifestKinds.multiArchManifest:
+            return "multi-arch";
+        case ManifestKinds.indexManifest:
+            return "index";
+        case ManifestKinds.signatureManifest:
+            return "signature";
+        case ManifestKinds.attestationManifest:
+            return "attestation";
+        case ManifestKinds.artifactManifest:
+            return "artifact";
+        default:
+            return "item";
+    }
+}

package/dist/cleanup-summary/_cleanup-summary.d.ts

@@ -0,0 +1,56 @@
+import type { ManifestKind } from "../core/index.js";
+import type { DeletePlan, DeletePlanSelectionMode, DeletePlanSelectionReason, DeletePlanValidationReasonCode, DeletePlanValidationStatus } from "../db/index.js";
+import type { DeleteExecutionSummary } from "../execute/index.js";
+export interface CleanupSummaryRoot {
+    versionId: number;
+    digest: string;
+    manifestKind?: ManifestKind;
+    rootTags: string[];
+    matchedTags: string[];
+    selectionMode: DeletePlanSelectionMode;
+    selectionReason: DeletePlanSelectionReason;
+    validationStatus: DeletePlanValidationStatus;
+    validationReasonCode: DeletePlanValidationReasonCode;
+    validationReason: string;
+    blockingVersionId?: number;
+    blockingDigest?: string;
+    overlapDigest?: string;
+    overlapManifestKind?: ManifestKind;
+}
+export interface CleanupSummaryAffectedManifest {
+    digest: string;
+    manifestKind?: ManifestKind;
+}
+export interface CleanupSummaryChanges {
+    deletedTags: number;
+    deletedImages: number;
+    deletedIndexes: number;
+    deletedMultiArchManifests: number;
+    deletedArtifactManifests: number;
+    deletedAttestations: number;
+    deletedSignatures: number;
+    deletedTotal: number;
+}
+export interface CleanupSummary {
+    command: "cleanup";
+    owner: string;
+    packageName: string;
+    scanCompletedAt: string;
+    dryRun: boolean;
+    plannerInputs: DeletePlan["plannerInputs"];
+    directTargetTags: string[];
+    collateralTags: string[];
+    fullyDeletableRoots: CleanupSummaryRoot[];
+    untagOnlyRoots: CleanupSummaryRoot[];
+    blockedRoots: CleanupSummaryRoot[];
+    affectedManifests: CleanupSummaryAffectedManifest[];
+    changes: CleanupSummaryChanges;
+    deletedPackageVersionCount: DeleteExecutionSummary["deletedPackageVersionCount"];
+    detachedTagCount: DeleteExecutionSummary["detachedTagCount"];
+}
+export declare function buildCleanupSummary(plan: DeletePlan, options: {
+    dryRun: boolean;
+    rootTagsByVersionId: ReadonlyMap<number, string[]>;
+    changes: CleanupSummaryChanges;
+    executionSummary?: DeleteExecutionSummary;
+}): CleanupSummary;

package/dist/cleanup-summary/_cleanup-summary.js

@@ -0,0 +1,59 @@
+import { DeletePlanValidationStatuses } from "../db/index.js";
+export function buildCleanupSummary(plan, options) {
+    const directTargetTagSet = new Set(plan.directTargetTags);
+    const roots = plan.rootDecisions.map((decision) => _mapRootDecision(decision, directTargetTagSet, options.rootTagsByVersionId));
+    const fullyDeletableRoots = roots.filter((root) => root.validationStatus === DeletePlanValidationStatuses.fullyDeletable);
+    const blockedRoots = roots.filter((root) => root.validationStatus === DeletePlanValidationStatuses.blocked);
+    const untagOnlyRoots = roots.filter((root) => root.validationStatus === DeletePlanValidationStatuses.untagOnly);
+    const affectedManifests = _listAffectedManifests(plan, fullyDeletableRoots.map((root) => root.digest));
+    return {
+        command: "cleanup",
+        owner: plan.owner,
+        packageName: plan.packageName,
+        scanCompletedAt: plan.scanCompletedAt,
+        dryRun: options.dryRun,
+        plannerInputs: plan.plannerInputs,
+        directTargetTags: plan.directTargetTags,
+        collateralTags: plan.collateralTags,
+        fullyDeletableRoots,
+        untagOnlyRoots,
+        blockedRoots,
+        affectedManifests,
+        changes: options.changes,
+        deletedPackageVersionCount: options.executionSummary?.deletedPackageVersionCount ?? 0,
+        detachedTagCount: options.executionSummary?.detachedTagCount ?? 0
+    };
+}
+function _mapRootDecision(decision, directTargetTagSet, rootTagsByVersionId) {
+    const rootTags = rootTagsByVersionId.get(decision.versionId) ?? [];
+    return {
+        versionId: decision.versionId,
+        digest: decision.digest,
+        manifestKind: decision.manifestKind,
+        rootTags,
+        matchedTags: rootTags.filter((tag) => directTargetTagSet.has(tag)),
+        selectionMode: decision.selectionMode,
+        selectionReason: decision.selectionReason,
+        validationStatus: decision.validationStatus,
+        validationReasonCode: decision.validationReasonCode,
+        validationReason: decision.validationReason,
+        blockingVersionId: decision.blockingVersionId,
+        blockingDigest: decision.blockingDigest,
+        overlapDigest: decision.overlapDigest,
+        overlapManifestKind: decision.overlapManifestKind
+    };
+}
+function _listAffectedManifests(plan, fullyDeletableRootDigests) {
+    const fullyDeletableRootDigestSet = new Set(fullyDeletableRootDigests);
+    const manifestsByDigest = new Map();
+    for (const manifest of plan.closureManifests) {
+        if (!fullyDeletableRootDigestSet.has(manifest.sourceDigest)) {
+            continue;
+        }
+        manifestsByDigest.set(manifest.memberDigest, {
+            digest: manifest.memberDigest,
+            manifestKind: manifest.memberManifestKind
+        });
+    }
+    return [...manifestsByDigest.values()].sort((left, right) => left.digest.localeCompare(right.digest));
+}

package/dist/cleanup-summary/index.d.ts

@@ -0,0 +1,2 @@
+export { buildCleanupSummary, type CleanupSummary, type CleanupSummaryAffectedManifest, type CleanupSummaryChanges, type CleanupSummaryRoot } from "./_cleanup-summary.js";
+export { renderCleanupSummaryMarkdown } from "./_cleanup-summary-markdown.js";

package/dist/cleanup-summary/index.js

@@ -0,0 +1,2 @@
+export { buildCleanupSummary } from "./_cleanup-summary.js";
+export { renderCleanupSummaryMarkdown } from "./_cleanup-summary-markdown.js";

package/dist/cli/_args.d.ts

@@ -0,0 +1,7 @@
+import { type LogLevel } from "./_logger.js";
+export declare function requireOption(args: string[], name: string): string;
+export declare function findOption(args: string[], name: string): string | undefined;
+export declare function collectRepeatedOption(args: string[], name: string): string[];
+export declare function hasFlag(args: string[], name: string): boolean;
+export declare function resolveToken(args: string[]): string;
+export declare function resolveLogLevel(args: string[]): LogLevel;

package/dist/cli/_args.js

@@ -0,0 +1,41 @@
+import { isLogLevel } from "./_logger.js";
+export function requireOption(args, name) {
+    const value = findOption(args, name);
+    if (!value) {
+        throw new Error(`missing required option: ${name}`);
+    }
+    return value;
+}
+export function findOption(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0) {
+        return undefined;
+    }
+    return args[index + 1];
+}
+export function collectRepeatedOption(args, name) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === name && args[index + 1]) {
+            values.push(args[index + 1]);
+        }
+    }
+    return values;
+}
+export function hasFlag(args, name) {
+    return args.includes(name);
+}
+export function resolveToken(args) {
+    const cliToken = findOption(args, "--token");
+    if (cliToken) {
+        return cliToken;
+    }
+    throw new Error("missing required option: --token");
+}
+export function resolveLogLevel(args) {
+    const rawLevel = findOption(args, "--log-level") ?? "info";
+    if (!isLogLevel(rawLevel)) {
+        throw new Error(`invalid log level: ${rawLevel}`);
+    }
+    return rawLevel;
+}

package/dist/cli/_cleanup-command.d.ts

@@ -0,0 +1 @@
+export declare function handleCleanup(args: string[]): Promise<number>;

package/dist/cli/_cleanup-command.js

@@ -0,0 +1,142 @@
+import { ManifestKinds } from "../core/index.js";
+import { buildCleanupSummary } from "../cleanup-summary/index.js";
+import { CleanupRunWriter, openDatabase, PlannerRepository } from "../db/index.js";
+import { executeDeletePlan } from "../execute/index.js";
+import { hasFlag, resolveLogLevel, resolveToken } from "./_args.js";
+import { writeJsonOutput } from "./_json-output.js";
+import { createLogger } from "./_logger.js";
+import { loadDeletePlan, resolvePlanCommandInputs } from "./_planner-options.js";
+import { resolveTagSelectors } from "./_tag-selector-resolver.js";
+export async function handleCleanup(args) {
+    const inputs = resolvePlanCommandInputs(args);
+    const dryRun = hasFlag(args, "--dry-run");
+    const token = dryRun ? undefined : resolveToken(args);
+    const logger = createLogger(resolveLogLevel(args));
+    const database = openDatabase(inputs.databasePath);
+    try {
+        const repository = new PlannerRepository(database, logger);
+        const cleanupRunWriter = new CleanupRunWriter(database);
+        const scanId = repository.getLatestCompletedScanId(inputs.owner, inputs.packageName);
+        logger.debug(`Starting cleanup for ${inputs.owner}/${inputs.packageName}`);
+        const plan = loadDeletePlan(repository, resolveTagSelectors(database, inputs));
+        const rootTagsByVersionId = _loadRootTagsByVersionId(database, inputs.owner, inputs.packageName, plan.rootDecisions.map((decision) => decision.versionId));
+        const cleanupRunId = cleanupRunWriter.persistCleanupRun(scanId, plan, {
+            dryRun,
+            cleanupStartedAt: new Date().toISOString()
+        });
+        if (dryRun) {
+            const summary = buildCleanupSummary(plan, {
+                dryRun: true,
+                rootTagsByVersionId,
+                changes: _loadSummaryChanges(database, cleanupRunId)
+            });
+            logger.debug(`Completed dry-run cleanup for ${inputs.owner}/${inputs.packageName}`);
+            writeJsonOutput(args, "--summary-json-path", summary);
+            return 0;
+        }
+        const executionSummary = await executeDeletePlan(plan, {
+            token: token,
+            logger,
+            listRootTags: (root) => _listRootTags(database, root.owner, root.packageName, root.versionId)
+        });
+        const summary = buildCleanupSummary(plan, {
+            dryRun: false,
+            rootTagsByVersionId,
+            changes: _loadSummaryChanges(database, cleanupRunId),
+            executionSummary
+        });
+        logger.debug(`Completed cleanup for ${inputs.owner}/${inputs.packageName}`);
+        writeJsonOutput(args, "--summary-json-path", summary);
+        return 0;
+    }
+    finally {
+        database.close();
+    }
+}
+function _listRootTags(database, owner, packageName, versionId) {
+    const rows = database
+        .prepare(`
+        SELECT tags.tag
+        FROM tags
+        INNER JOIN v_latest_scan_per_package latest_scan ON latest_scan.scan_id = tags.scan_id
+        WHERE latest_scan.owner = ?
+          AND latest_scan.package_name = ?
+          AND tags.version_id = ?
+          AND tags.is_digest_tag = 0
+        ORDER BY tags.tag
+      `)
+        .all(owner, packageName, versionId);
+    return rows.map((row) => row.tag);
+}
+function _loadRootTagsByVersionId(database, owner, packageName, versionIds) {
+    const requestedVersionIds = new Set(versionIds);
+    const tagsByVersionId = new Map();
+    for (const versionId of requestedVersionIds) {
+        tagsByVersionId.set(versionId, []);
+    }
+    if (requestedVersionIds.size === 0) {
+        return tagsByVersionId;
+    }
+    const rows = database
+        .prepare(`
+        SELECT tags.version_id, tags.tag
+        FROM tags
+        INNER JOIN v_latest_scan_per_package latest_scan ON latest_scan.scan_id = tags.scan_id
+        WHERE latest_scan.owner = ?
+          AND latest_scan.package_name = ?
+          AND tags.is_digest_tag = 0
+        ORDER BY tags.version_id, tags.tag
+      `)
+        .all(owner, packageName);
+    for (const row of rows) {
+        if (!requestedVersionIds.has(row.version_id)) {
+            continue;
+        }
+        tagsByVersionId.get(row.version_id)?.push(row.tag);
+    }
+    return tagsByVersionId;
+}
+function _loadSummaryChanges(database, cleanupRunId) {
+    const deletedTags = database
+        .prepare(`
+          SELECT COUNT(*) AS count
+          FROM cleanup_selected_tags
+          WHERE cleanup_run_id = ?
+            AND is_deleted = 1
+        `)
+        .get(cleanupRunId).count;
+    const manifestCounts = database
+        .prepare(`
+        WITH fully_deletable_manifests AS (
+          SELECT DISTINCT
+            reachable.descendant_digest AS digest,
+            manifest.manifest_kind
+          FROM cleanup_root_decisions decision
+          JOIN manifest_reachability reachable
+            ON reachable.scan_id = decision.scan_id
+           AND reachable.ancestor_digest = decision.digest
+          JOIN manifests manifest
+            ON manifest.scan_id = reachable.scan_id
+           AND manifest.digest = reachable.descendant_digest
+          WHERE decision.cleanup_run_id = ?
+            AND decision.validation_status = 'fully-deletable'
+        )
+        SELECT
+          manifest_kind,
+          COUNT(*) AS count
+        FROM fully_deletable_manifests
+        GROUP BY manifest_kind
+      `)
+        .all(cleanupRunId);
+    const countsByKind = new Map(manifestCounts.map((row) => [row.manifest_kind ?? "", row.count]));
+    return {
+        deletedTags,
+        deletedImages: countsByKind.get(ManifestKinds.imageManifest) ?? 0,
+        deletedIndexes: countsByKind.get(ManifestKinds.indexManifest) ?? 0,
+        deletedMultiArchManifests: countsByKind.get(ManifestKinds.multiArchManifest) ?? 0,
+        deletedArtifactManifests: countsByKind.get(ManifestKinds.artifactManifest) ?? 0,
+        deletedAttestations: countsByKind.get(ManifestKinds.attestationManifest) ?? 0,
+        deletedSignatures: countsByKind.get(ManifestKinds.signatureManifest) ?? 0,
+        deletedTotal: manifestCounts.reduce((total, row) => total + row.count, 0)
+    };
+}

package/dist/cli/_db-merge-command.d.ts

@@ -0,0 +1 @@
+export declare function handleDbMerge(args: string[]): Promise<number>;

package/dist/cli/_db-merge-command.js

@@ -0,0 +1,41 @@
+import { collectRepeatedOption, requireOption } from "./_args.js";
+import { DbMergeRepository, openDatabase } from "../db/index.js";
+export async function handleDbMerge(args) {
+    const databasePath = requireOption(args, "--db");
+    const sourceDatabasePaths = collectRepeatedOption(args, "--source-db");
+    if (sourceDatabasePaths.length === 0) {
+        throw new Error("missing required option: --source-db");
+    }
+    const targetDatabase = openDatabase(databasePath);
+    try {
+        const merger = new DbMergeRepository(targetDatabase);
+        const summaries = [];
+        let importedScanCount = 0;
+        let skippedScanCount = 0;
+        let importedCleanupRunCount = 0;
+        let skippedCleanupRunCount = 0;
+        for (const sourceDatabasePath of sourceDatabasePaths) {
+            const sourceDatabase = openDatabase(sourceDatabasePath);
+            sourceDatabase.close();
+            const summary = merger.mergeSourceDatabase(sourceDatabasePath);
+            summaries.push(summary);
+            importedScanCount += summary.importedScanCount;
+            skippedScanCount += summary.skippedScanCount;
+            importedCleanupRunCount += summary.importedCleanupRunCount;
+            skippedCleanupRunCount += summary.skippedCleanupRunCount;
+        }
+        console.log(JSON.stringify({
+            targetDatabasePath: databasePath,
+            sourceDatabaseCount: sourceDatabasePaths.length,
+            importedScanCount,
+            skippedScanCount,
+            importedCleanupRunCount,
+            skippedCleanupRunCount,
+            sources: summaries
+        }, null, 2));
+        return 0;
+    }
+    finally {
+        targetDatabase.close();
+    }
+}

package/dist/cli/_github-output.d.ts

@@ -0,0 +1,10 @@
+export interface GitHubScanOutputs {
+    owner: string;
+    packageName: string;
+    scanCompletedAt: string;
+    packageVersions: number;
+    tags: number;
+    manifests: number;
+    manifestEdges: number;
+}
+export declare function writeGitHubScanOutputs(outputPath: string, outputs: GitHubScanOutputs): void;

package/dist/cli/_github-output.js

@@ -0,0 +1,13 @@
+import { appendFileSync } from "node:fs";
+export function writeGitHubScanOutputs(outputPath, outputs) {
+    const lines = [
+        `owner=${outputs.owner}`,
+        `package_name=${outputs.packageName}`,
+        `scan_completed_at=${outputs.scanCompletedAt}`,
+        `package_versions=${outputs.packageVersions}`,
+        `tags=${outputs.tags}`,
+        `manifests=${outputs.manifests}`,
+        `manifest_edges=${outputs.manifestEdges}`
+    ];
+    appendFileSync(outputPath, `${lines.join("\n")}\n`);
+}

package/dist/cli/_json-output.d.ts

@@ -0,0 +1 @@
+export declare function writeJsonOutput(args: string[], optionName: string, payload: unknown): void;

package/dist/cli/_json-output.js

@@ -0,0 +1,11 @@
+import { writeFileSync } from "node:fs";
+import { findOption } from "./_args.js";
+export function writeJsonOutput(args, optionName, payload) {
+    const json = JSON.stringify(payload);
+    const outputPath = findOption(args, optionName);
+    if (outputPath) {
+        writeFileSync(outputPath, `${json}\n`, "utf8");
+        return;
+    }
+    console.log(json);
+}

package/dist/cli/_logger.d.ts

@@ -0,0 +1,10 @@
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "silent";
+export interface Logger {
+    trace(message: string): void;
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export declare function isLogLevel(value: string): value is LogLevel;
+export declare function createLogger(level: LogLevel, sink?: NodeJS.WritableStream): Logger;

package/dist/cli/_logger.js

@@ -0,0 +1,26 @@
+const _logLevelPriority = {
+    trace: 0,
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 50
+};
+export function isLogLevel(value) {
+    return value in _logLevelPriority;
+}
+export function createLogger(level, sink = process.stderr) {
+    return {
+        trace: _write.bind(null, "trace", level, sink),
+        debug: _write.bind(null, "debug", level, sink),
+        info: _write.bind(null, "info", level, sink),
+        warn: _write.bind(null, "warn", level, sink),
+        error: _write.bind(null, "error", level, sink)
+    };
+}
+function _write(level, threshold, sink, message) {
+    if (_logLevelPriority[level] < _logLevelPriority[threshold]) {
+        return;
+    }
+    sink.write(`${new Date().toISOString()} ${level.toUpperCase()} ${message}\n`);
+}

package/dist/cli/_older-than.d.ts

@@ -0,0 +1,5 @@
+export interface OlderThanResolution {
+    olderThan: string;
+    cutoffTimestamp: string;
+}
+export declare function resolveOlderThan(rawValue: string, now: Date): OlderThanResolution;