ghcr-manager 0.0.4 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,55 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-21
+
+`0.9.0` is the first stable pre-`1.0` release of `ghcr-manager`.
+
+### Added
+
+- `cleanup` as the main GHCR maintenance flow for both the GitHub Action and the companion CLI.
+- `untag` as a direct tag-removal mode that works without a scan database.
+- `db-merge` and `merge-run-artifacts` support for combining scan databases across packages and workflow runs.
+- Support for both organization-owned and user-owned GitHub Container Registry packages.
+- Cleanup summary JSON output plus GitHub step summary rendering for action runs.
+- Broad live and scenario-based workflow coverage for cleanup, untag, and cross-owner behavior.
+- User-facing documentation for action usage, CLI usage, DB merge workflows, schema orientation, and SQL recipes.
+
+### Changed
+
+- The GitHub Action now builds and runs the repo-local CLI directly instead of installing `ghcr-manager` from npm at
+  runtime.
+- The primary maintenance surface is now `cleanup` with `dry-run` semantics, with `scan` and `untag` as supporting
+  command modes.
+- The action input and artifact flow were refined around scan databases, cleanup summaries, and optional post-cleanup
+  rescan behavior.
+- Documentation was reorganized around action-first usage, with deeper companion docs for CLI and database workflows.
+- Release validation and workflow gating were tightened around exact version references, changelog readiness, and live
+  scenario checks.
+
+### Removed
+
+- Built-in database artifact encryption and decryption support.
+
+### Fixed
+
+- Digest-selector scenario handling and related workflow wiring for `ghcr-manager`.
+- Latest-scan based verification for cleanup and untag test flows.
+- User-owner cleanup workflow behavior and related test setup details.
+- Numerous workflow, artifact-handling, and planner-audit edge cases discovered during pre-release hardening.
+
+## [0.0.6] - 2026-04-30
+
+### Changed
+
+- Internal workflow/debug wiring.
+
+## [0.0.5] - 2026-04-30
+
+### Changed
+
+- Publish to npmjs by trusted publisher
+
 ## [0.0.4] - 2026-04-30
 
 ### Changed
@@ -32,7 +81,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Immutable per-scan UUID (`package_scans.scan_uuid`) for robust duplicate detection across merged databases.
 - Optional action artifact upload for scan DB export (`upload-db-artifact`, optional retention override).
 - Manual workflow for interactive scan runs (`.github/workflows/manual-run.yml`).
-- Missing-manifest investigation SQL recipes (`docs/missing-manifests-queries.md`) and schema/terminology docs.
+- Missing-manifest investigation SQL recipes (`docs/queries/missing-manifests-queries.md`) and schema/terminology docs.
 
 ### Changed
 

package/README.md

@@ -3,95 +3,204 @@
 [![Release](https://img.shields.io/github/v/release/gh-workflow/ghcr-manager?style=flat-square)](https://github.com/gh-workflow/ghcr-manager/releases)
 [![Immutable Releases](https://img.shields.io/badge/releases-immutable-blue?labelColor=333)](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases)
 [![GitHub Marketplace](https://img.shields.io/badge/marketplace-ghcr--manager-blue?logo=github&labelColor=333&style=flat-square)](https://github.com/marketplace/actions/ghcr-manager)
-[![Tests](https://img.shields.io/github/actions/workflow/status/gh-workflow/ghcr-manager/change-validation.yml?branch=main&label=test&style=flat-square)](https://github.com/gh-workflow/ghcr-manager/actions/workflows/change-validation.yml)
-[![Usage](https://img.shields.io/badge/image-GHCR-2496ED?logo=docker&logoColor=white&style=flat-square)](#usage)
+[![Tests](https://img.shields.io/github/actions/workflow/status/gh-workflow/ghcr-manager/.github/workflows/ci_change-validation.yml?branch=main&label=test&style=flat-square)](https://github.com/gh-workflow/ghcr-manager/actions/workflows/change-validation.yml)
 
-Inspect, analyze, and manage GitHub Container Registry packages.
+Inspect, review, and manage GitHub Container Registry packages.
 
-`ghcr-manager` is a public GitHub Action and companion CLI for safe GHCR cleanup and inspection, with a focus on large
-packages and correct handling of multi-arch images, referrers, and attestations.
+`ghcr-manager` is a GitHub Action for:
 
-## Scope
+- scanning one GHCR package into a SQLite database artifact
+- running cleanup with a GitHub step summary and optional DB artifact
+- previewing cleanup decisions with `dry-run` before making changes
+- directly removing selected tags with `untag`
 
-- :white_check_mark: Full package and manifest scan per run for correctness
-- :white_check_mark: Export database of Container Registry from runs for local analysis
-- :construction: Safe cleanup of GHCR image artifacts in GitHub packages
+## Quick Start
 
-## How
-
-### :white_check_mark: Data Loading
-
-1. Writes Container Registry metadata to a database
-2. Pre-processes data for optimized lookups
-3. Optional: Export of database from runs for local analysis
-
-> :construction: Planned: Support for merging several such databases into one for local analysis
-
-### :construction: Consistency Check
-
-1. Run consistency check against the database
-2. Optional: Export report of missing manifests from runs
-
-### :construction: Safe cleanup of GHCR image artifacts
-
-1. Use filter input to query database for related artifacts (images and manifests)
-2. Optional `dry-run`: Export which image artifacts would be deleted
-3. Delete image artifacts (without `dry-run`)
-
-## Usage
+For a first run, start with `cleanup` in `dry-run` mode.
 
 ```yaml
-concurrency:
-  group: ghcr-manager__${{ inputs.owner }}__${{ inputs.package }}
 jobs:
-  scan:
+  cleanup:
     runs-on: ubuntu-latest
     permissions:
       contents: read
       packages: read
-      actions: write # only required when upload-db-artifact is true
+      actions: write
     concurrency:
-      group: ghcr-manager
+      group: ghcr-manager__OWNER__PACKAGE
     steps:
       - uses: actions/checkout@v6
 
-      - name: Run ghcr-manager action
-        uses: gh-workflow/ghcr-manager@0.0.4
+      - name: Preview GHCR cleanup
+        id: ghcr-manager
+        uses: gh-workflow/ghcr-manager@0.9.0
         with:
+          command: cleanup
           github-token: ${{ github.token }}
           owner: OWNER
           package: PACKAGE
+          dry-run: true
+          delete-untagged: true
+          keep-n-tagged: "10"
+          exclude-tags: |
+            latest
           upload-db-artifact: true
 ```
 
-> Copy the [Manual Run Workflow](.github/workflows/manual-run.yml) as a ready-to-run manual scan workflow.
+After the run:
 
-## Inputs
+1. Open the GitHub step summary for the action run.
+2. Review which tags matched and which roots would be deleted, untagged, or blocked.
+3. Only download the DB artifact if you need deeper inspection.
+
+## Commands
+
+The action supports three commands:
+
+- `cleanup`: Cleans using filters; use `dry-run` to preview the result
+- `untag`: Removes one or more tags directly
+- `scan`: Scans one package and uploads the resulting DB artifact
+
+### Purpose of commands
+
+- `cleanup`: Normal entry point for registry maintenance
+- `untag`: Works directly without a full package scan
+- `scan`: For investigation and audit
+
+## Common Usage
+
+### Preview cleanup
+
+```yaml
+- uses: gh-workflow/ghcr-manager@0.9.0
+  with:
+    command: cleanup
+    github-token: ${{ github.token }}
+    owner: OWNER
+    package: PACKAGE
+    dry-run: true
+    delete-tags: |
+      pr-.*
+    use-regex: true
+    older-than: 30d
+    keep-n-tagged: "5"
+    exclude-tags: |
+      latest
+      stable
+    upload-db-artifact: true
+```
+
+### Apply cleanup
 
-<!-- markdownlint-disable MD013 -->
+```yaml
+- uses: gh-workflow/ghcr-manager@0.9.0
+  with:
+    command: cleanup
+    github-token: ${{ github.token }}
+    owner: OWNER
+    package: PACKAGE
+    delete-untagged: true
+    keep-n-tagged: "10"
+    upload-db-artifact: true
+    scan-after-cleanup: true
+```
+
+If `scan-after-cleanup` is `true`, `cleanup` performs a second scan so the uploaded DB reflects post-mutation state.
+
+Note: the second scan only runs if cleanup actually makes changes.
+
+### Remove selected tags directly
+
+```yaml
+- uses: gh-workflow/ghcr-manager@0.9.0
+  with:
+    command: untag
+    github-token: ${{ github.token }}
+    owner: OWNER
+    package: PACKAGE
+    delete-tags: |
+      old-tag
+      test-tag
+```
+
+`untag` does not use a scan DB and does not support DB artifact upload.
+
+### Scan one package
 
-| Input                        | Description                                                     | Required | Default                        |
-| ---------------------------- | --------------------------------------------------------------- | -------- | ------------------------------ |
-| `github-token`               | GitHub token used for GitHub/GHCR API calls                     | Yes      | `${{ github.token }}`          |
-| `owner`                      | GitHub owner of the container package (user or org)             | Yes      |                                |
-| `package`                    | Container package name                                          | Yes      |                                |
-| `upload-db-artifact`         | Whether to upload the scan database as a workflow run artifact  | No       | `false`                        |
-| `db-artifact-retention-days` | Optional retention days override for uploaded database artifact | No       | `${{ github.retention_days }}` |
+```yaml
+- uses: gh-workflow/ghcr-manager@0.9.0
+  with:
+    command: scan
+    github-token: ${{ github.token }}
+    owner: OWNER
+    package: PACKAGE
+```
+
+`scan` always uploads a DB artifact.
+
+## Inputs
 
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-disable MD013 MD060 -->
+
+| Input                        | Description                         | Cmds | Required    | Default                        |
+| ---------------------------- | ----------------------------------- | ---- | ----------- | ------------------------------ |
+| `command`                    | `scan`, `cleanup`, or `untag`       | all  | Yes         |                                |
+| `github-token`               | GitHub token for API calls          | all  | Yes         | `${{ github.token }}`          |
+| `owner`                      | Package owner                       | all  | Yes         |                                |
+| `package`                    | Package name                        | all  | Yes         |                                |
+| `db-path`                    | Local SQLite DB path                | s,c  | No          |                                |
+| `upload-db-artifact`         | Upload DB and summary artifact      | s,c  | No          | `false`                        |
+| `scan-after-cleanup`         | Run a second scan after cleanup     | c    | No          | `false`                        |
+| `db-artifact-retention-days` | Override artifact retention days    | s,c  | No          | `${{ github.retention_days }}` |
+| `delete-tags`                | Newline-separated tags to delete    | c,u  | for `untag` |                                |
+| `exclude-tags`               | Newline-separated tags to exclude   | c    | No          |                                |
+| `keep-n-tagged`              | Keep newest tagged roots            | c    | No          |                                |
+| `keep-n-untagged`            | Keep newest untagged roots          | c    | No          |                                |
+| `delete-untagged`            | Delete untagged roots               | c    | No          | `false`                        |
+| `delete-ghost-images`        | Delete ghost multi-arch roots       | c    | No          | `false`                        |
+| `delete-partial-images`      | Delete partial multi-arch roots     | c    | No          | `false`                        |
+| `delete-orphaned-images`     | Delete orphaned digest-derived tags | c    | No          | `false`                        |
+| `older-than`                 | Age cutoff for cleanup selectors    | c    | No          |                                |
+| `use-regex`                  | Use regex for cleanup tag selectors | c    | No          | `false`                        |
+| `dry-run`                    | Show changes without mutating GHCR  | c,u  | No          | `false`                        |
+| `log-level`                  | CLI log level                       | all  | No          | `info`                         |
+
+<!-- markdownlint-enable MD013 MD060 -->
+
+`Cmds`: `s` = `scan`, `c` = `cleanup`, `u` = `untag`
 
 ## Outputs
 
-| Output    | Description                                             |
-| --------- | ------------------------------------------------------- |
-| `db-path` | Path to the SQLite database in the GitHub action runner |
+| Output         | Description                            |
+| -------------- | -------------------------------------- |
+| `db-path`      | SQLite DB path on the runner           |
+| `summary-json` | Summary JSON for `cleanup` and `untag` |
 
 ## Artifacts
 
-<!-- markdownlint-disable MD013 -->
+When artifacts are enabled:
+
+- `scan` always uploads one SQLite DB artifact
+- `cleanup` optionally uploads the DB artifact and a cleanup summary JSON artifact
+- `untag` uploads no artifacts
+
+Current naming:
+
+| Artifact type        | Filename pattern                                    |
+| -------------------- | --------------------------------------------------- |
+| scan or cleanup DB   | `${OWNER}__${PACKAGE}.sqlite`                       |
+| cleanup summary JSON | `${OWNER}__${PACKAGE}.sqlite--cleanup-summary.json` |
+
+## Documentation Map
+
+- [docs/action-usage.md](docs/action-usage.md): action commands, including `cleanup`, `scan`, and `untag`
+- [docs/db-merge-workflows.md](docs/db-merge-workflows.md): cleaning up multiple packages with one combined DB
+- [docs/schema-description.md](docs/schema-description.md): practical explanation of the SQLite schema
+- [docs/queries/missing-manifests-queries.md](docs/queries/missing-manifests-queries.md): SQL recipes for missing
+  manifest references
+- [docs/cli-usage.md](docs/cli-usage.md): companion CLI usage
 
-| Name                          | Filename                          | Description                                                          |
-| ----------------------------- | --------------------------------- | -------------------------------------------------------------------- |
-| `${OWNER}__${PACKAGE}.sqlite` | `${OWNER}__${PACKAGE}.sqlite.zip` | Zipped SQLite database containing GitHub Container Registry metadata |
+## Acknowledgment
 
-<!-- markdownlint-enable MD013 -->
+This project was influenced by [dataaxiom/ghcr-cleanup-action](https://github.com/dataaxiom/ghcr-cleanup-action), with a
+similar problem focus and a different implementation approach.

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

@@ -0,0 +1,6 @@
+import type { CleanupSummary } from "./_cleanup-summary.js";
+export declare function renderCleanupSummaryMarkdown(summary: CleanupSummary, options: {
+    maxDirectTargetTags?: number;
+    maxRootsPerSection?: number;
+    maxTagsPerRoot?: number;
+}): string;

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

@@ -0,0 +1,113 @@
+const _DEFAULT_MAX_DIRECT_TARGET_TAGS = 20;
+const _DEFAULT_MAX_ROOTS_PER_SECTION = 20;
+const _DEFAULT_MAX_TAGS_PER_ROOT = 4;
+export function renderCleanupSummaryMarkdown(summary, options) {
+    const maxDirectTargetTags = options.maxDirectTargetTags ?? _DEFAULT_MAX_DIRECT_TARGET_TAGS;
+    const maxRootsPerSection = options.maxRootsPerSection ?? _DEFAULT_MAX_ROOTS_PER_SECTION;
+    const maxTagsPerRoot = options.maxTagsPerRoot ?? _DEFAULT_MAX_TAGS_PER_ROOT;
+    const lines = [
+        "## Cleanup Summary",
+        "",
+        "| Field | Value |",
+        "| --- | --- |",
+        `| 📦 Package | \`${_escapeInlineCode(`${summary.owner}/${summary.packageName}`)}\` |`,
+        `| ⚙️ Mode | ${summary.dryRun ? "Cleanup dry-run" : "Cleanup"} |`,
+        `| 🏷️ Matched tags | ${summary.validationSummary.directTargetTagCount} |`,
+        `| 🗑️ Fully deletable roots | ${summary.validationSummary.fullyDeletableRootCount} |`,
+        `| 🔗 Untag-only roots | ${summary.validationSummary.untagOnlyRootCount} |`,
+        `| 🛡️ Blocked roots | ${summary.validationSummary.blockedDeleteRootCount} |`,
+        ""
+    ];
+    lines.push(..._renderJsonDetails("⚙️ Cleanup filter", summary.plannerInputs));
+    lines.push(..._renderDirectTargetTags(summary.directTargetTags, maxDirectTargetTags));
+    lines.push(..._renderRootSection("🗑️ Fully deletable roots", summary.fullyDeletableRoots, maxRootsPerSection, maxTagsPerRoot));
+    lines.push(..._renderRootSection("🔗 Untag-only roots", summary.untagOnlyRoots, maxRootsPerSection, maxTagsPerRoot));
+    lines.push(..._renderRootSection("🛡️ Blocked roots", summary.blockedRoots, maxRootsPerSection, maxTagsPerRoot));
+    if (!summary.dryRun && (summary.deletedPackageVersions.length > 0 || summary.untaggedTags.length > 0)) {
+        lines.push(..._renderLiveEffects(summary));
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+function _renderJsonDetails(title, value) {
+    return [
+        `<details>`,
+        `<summary>${title}</summary>`,
+        "",
+        "```json",
+        JSON.stringify(value, null, 2),
+        "```",
+        "",
+        "</details>",
+        ""
+    ];
+}
+function _renderDirectTargetTags(tags, maxDirectTargetTags) {
+    if (tags.length === 0) {
+        return [];
+    }
+    const visibleTags = tags.slice(0, maxDirectTargetTags).map((tag) => `- \`${_escapeInlineCode(tag)}\``);
+    const lines = ["<details>", "<summary>🏷️ Matched tags</summary>", "", ...visibleTags];
+    if (tags.length > maxDirectTargetTags) {
+        lines.push("", `_Showing first ${maxDirectTargetTags} of ${tags.length} matched tags._`);
+    }
+    lines.push("", "</details>", "");
+    return lines;
+}
+function _renderRootSection(title, roots, maxRootsPerSection, maxTagsPerRoot) {
+    if (roots.length === 0) {
+        return [];
+    }
+    const lines = ["<details>", `<summary>${title}</summary>`, ""];
+    lines.push("| Version | Digest | Tags | Reason |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const root of roots.slice(0, maxRootsPerSection)) {
+        lines.push(`| ${root.versionId} | \`${_escapeInlineCode(_shortDigest(root.digest))}\` | ${_escapeMarkdown(_formatTags(root, maxTagsPerRoot))} | ${_escapeMarkdown(_formatReason(root))} |`);
+    }
+    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.deletedPackageVersions.length}`);
+    lines.push(`- Detached tags: ${summary.untaggedTags.length}`);
+    if (summary.unsupportedUntagRoots.length > 0) {
+        lines.push(`- Unsupported untag roots: ${summary.unsupportedUntagRoots.length}`);
+    }
+    lines.push("");
+    return lines;
+}
+function _formatTags(root, maxTagsPerRoot) {
+    const tags = root.rootTags.length > 0 ? root.rootTags : root.matchedTags;
+    if (tags.length === 0) {
+        return "(untagged)";
+    }
+    const visible = tags.slice(0, maxTagsPerRoot);
+    const suffix = tags.length > maxTagsPerRoot ? `, +${tags.length - maxTagsPerRoot} more` : "";
+    return visible.join(", ") + suffix;
+}
+function _formatReason(root) {
+    if (root.validationStatus === "blocked") {
+        const blocking = root.blockingDigest ? _shortDigest(root.blockingDigest) : "another root";
+        const overlap = root.overlapDigest ? ` via ${_shortDigest(root.overlapDigest)}` : "";
+        return `Blocked by ${blocking}${overlap}`;
+    }
+    if (root.validationStatus === "untag-only") {
+        return "Selected tags detach; root remains";
+    }
+    return "Root and closure can be deleted";
+}
+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", " ");
+}

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

@@ -0,0 +1,40 @@
+import type { DeletePlan } from "../db/index.js";
+import type { DeleteExecutionSummary } from "../execute/index.js";
+export interface CleanupSummaryRoot {
+    versionId: number;
+    digest: string;
+    manifestKind?: string;
+    rootTags: string[];
+    matchedTags: string[];
+    selectionMode: string;
+    selectionReason: string;
+    validationStatus: "fully-deletable" | "blocked" | "untag-only";
+    validationReasonCode: "untag-only-partial-tag-match" | "fully-deletable-no-retained-overlap" | "blocked-overlap-with-retained-root";
+    validationReason: string;
+    blockingVersionId?: number;
+    blockingDigest?: string;
+    overlapDigest?: string;
+    overlapManifestKind?: string;
+}
+export interface CleanupSummary {
+    command: "cleanup";
+    owner: string;
+    packageName: string;
+    scanCompletedAt: string;
+    dryRun: boolean;
+    plannerInputs: DeletePlan["plannerInputs"];
+    validationSummary: DeletePlan["validationSummary"];
+    directTargetTags: string[];
+    collateralTags: string[];
+    fullyDeletableRoots: CleanupSummaryRoot[];
+    untagOnlyRoots: CleanupSummaryRoot[];
+    blockedRoots: CleanupSummaryRoot[];
+    deletedPackageVersions: DeleteExecutionSummary["deletedPackageVersions"];
+    untaggedTags: DeleteExecutionSummary["untaggedTags"];
+    unsupportedUntagRoots: DeleteExecutionSummary["unsupportedUntagRoots"];
+}
+export declare function buildCleanupSummary(plan: DeletePlan, options: {
+    dryRun: boolean;
+    listRootTags: (versionId: number) => string[];
+    executionSummary?: DeleteExecutionSummary;
+}): CleanupSummary;

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

@@ -0,0 +1,40 @@
+export function buildCleanupSummary(plan, options) {
+    const directTargetTagSet = new Set(plan.directTargetTags);
+    const roots = plan.rootDecisions.map((decision) => _mapRootDecision(decision, directTargetTagSet, options.listRootTags));
+    return {
+        command: "cleanup",
+        owner: plan.owner,
+        packageName: plan.packageName,
+        scanCompletedAt: plan.scanCompletedAt,
+        dryRun: options.dryRun,
+        plannerInputs: plan.plannerInputs,
+        validationSummary: plan.validationSummary,
+        directTargetTags: plan.directTargetTags,
+        collateralTags: plan.collateralTags,
+        fullyDeletableRoots: roots.filter((root) => root.validationStatus === "fully-deletable"),
+        untagOnlyRoots: roots.filter((root) => root.validationStatus === "untag-only"),
+        blockedRoots: roots.filter((root) => root.validationStatus === "blocked"),
+        deletedPackageVersions: options.executionSummary?.deletedPackageVersions ?? [],
+        untaggedTags: options.executionSummary?.untaggedTags ?? [],
+        unsupportedUntagRoots: options.executionSummary?.unsupportedUntagRoots ?? []
+    };
+}
+function _mapRootDecision(decision, directTargetTagSet, listRootTags) {
+    const rootTags = listRootTags(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
+    };
+}

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

@@ -0,0 +1,2 @@
+export { buildCleanupSummary, type CleanupSummary, 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

@@ -2,5 +2,6 @@ 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 resolveGitHubToken(args: string[]): string;
 export declare function resolveLogLevel(args: string[]): LogLevel;

package/dist/cli/_args.js

@@ -22,6 +22,9 @@ export function collectRepeatedOption(args, name) {
     }
     return values;
 }
+export function hasFlag(args, name) {
+    return args.includes(name);
+}
 export function resolveGitHubToken(args) {
     const cliToken = findOption(args, "--token");
     if (cliToken) {

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,63 @@
+import { buildCleanupSummary } from "../cleanup-summary/index.js";
+import { CleanupRunWriter, openDatabase, PlannerRepository } from "../db/index.js";
+import { executeDeletePlan } from "../execute/index.js";
+import { hasFlag, resolveGitHubToken, resolveLogLevel } from "./_args.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 : resolveGitHubToken(args);
+    const logger = createLogger(resolveLogLevel(args));
+    const database = openDatabase(inputs.databasePath);
+    try {
+        const repository = new PlannerRepository(database, logger);
+        const cleanupRunWriter = new CleanupRunWriter(database);
+        logger.debug(`Starting cleanup for ${inputs.owner}/${inputs.packageName}`);
+        const plan = loadDeletePlan(repository, resolveTagSelectors(database, inputs));
+        cleanupRunWriter.persistCleanupRun(repository.getLatestCompletedScanId(inputs.owner, inputs.packageName), plan, {
+            dryRun,
+            cleanupStartedAt: new Date().toISOString()
+        });
+        if (dryRun) {
+            const summary = buildCleanupSummary(plan, {
+                dryRun: true,
+                listRootTags: (versionId) => _listRootTags(database, inputs.owner, inputs.packageName, versionId)
+            });
+            logger.debug(`Completed dry-run cleanup for ${inputs.owner}/${inputs.packageName}`);
+            console.log(JSON.stringify(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,
+            listRootTags: (versionId) => _listRootTags(database, inputs.owner, inputs.packageName, versionId),
+            executionSummary
+        });
+        logger.debug(`Completed cleanup for ${inputs.owner}/${inputs.packageName}`);
+        console.log(JSON.stringify(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 = ?
+        ORDER BY tags.tag
+      `)
+        .all(owner, packageName, versionId);
+    return rows.map((row) => row.tag);
+}

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

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