ghcr-manager 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -7,6 +7,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-05-21
+
+### Changed
+
+- Cleanup selector planning now composes tagged and untagged selector families in one SQL-backed planner path.
+- Cleanup CLI help and docs now describe the composed selector model, including tagged selectors combined with
+  `delete-untagged`.
+
+### Fixed
+
+- `exclude-tag` now works correctly when a tagged selector family is combined with `delete-untagged`.
+
 ## [0.9.2] - 2026-05-21
 
 ### Changed

package/README.md

@@ -33,7 +33,7 @@ jobs:
 
       - name: Preview GHCR cleanup
         id: ghcr-manager
-        uses: gh-workflow/ghcr-manager@0.9.2
+        uses: gh-workflow/ghcr-manager@0.9.3
         with:
           command: cleanup
           token: ${{ github.token }}
@@ -72,7 +72,7 @@ The action supports three commands:
 ### Preview cleanup
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.2
+- uses: gh-workflow/ghcr-manager@0.9.3
   with:
     command: cleanup
     token: ${{ github.token }}
@@ -93,7 +93,7 @@ The action supports three commands:
 ### Apply cleanup
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.2
+- uses: gh-workflow/ghcr-manager@0.9.3
   with:
     command: cleanup
     token: ${{ github.token }}
@@ -112,7 +112,7 @@ Note: the second scan only runs if cleanup actually makes changes.
 ### Remove selected tags directly
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.2
+- uses: gh-workflow/ghcr-manager@0.9.3
   with:
     command: untag
     token: ${{ github.token }}
@@ -128,7 +128,7 @@ Note: the second scan only runs if cleanup actually makes changes.
 ### Scan one package
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.2
+- uses: gh-workflow/ghcr-manager@0.9.3
   with:
     command: scan
     token: ${{ github.token }}
@@ -169,6 +169,12 @@ Note: the second scan only runs if cleanup actually makes changes.
 
 `Cmds`: `s` = `scan`, `c` = `cleanup`, `u` = `untag`
 
+Cleanup notes:
+
+- Tagged selector families may be combined with `delete-untagged`.
+- `exclude-tags` requires at least one tagged selector family.
+- `delete-untagged` and `keep-n-untagged` cannot be combined.
+
 ## Outputs
 
 | Output         | Description                            |

package/dist/cli/_planner-options.js

@@ -27,14 +27,14 @@ export function resolvePlanCommandInputs(args) {
         deletePartialImages ||
         deleteOrphanedImages ||
         keepNTagged !== undefined;
-    const selectorCount = (deleteUntagged ? 1 : 0) + (taggedSelectorActive ? 1 : 0) + (keepNUntagged !== undefined ? 1 : 0);
-    if (selectorCount > 1) {
-        throw new Error("plan currently supports exactly one selector family: --delete-untagged, --delete-tag, --delete-ghost-images, --delete-partial-images, --delete-orphaned-images, --keep-n-tagged, or --keep-n-untagged");
+    const hasAnySelector = deleteUntagged || taggedSelectorActive || keepNUntagged !== undefined;
+    if (deleteUntagged && keepNUntagged !== undefined) {
+        throw new Error("--delete-untagged and --keep-n-untagged cannot be combined");
     }
-    if (selectorCount === 0) {
+    if (!hasAnySelector) {
         throw new Error("missing required cleanup selector: --delete-untagged, --delete-tag, --delete-ghost-images, --delete-partial-images, --delete-orphaned-images, --keep-n-tagged, or --keep-n-untagged");
     }
-    if ((deleteUntagged || keepNUntagged !== undefined) && excludeTags.length > 0) {
+    if (!taggedSelectorActive && excludeTags.length > 0) {
         throw new Error("--exclude-tag is only supported with tagged selector families");
     }
     if (olderThanRaw.length > 1) {
@@ -60,35 +60,17 @@ export function resolvePlanCommandInputs(args) {
     };
 }
 export function loadDeletePlan(repository, inputs) {
-    if (inputs.keepNUntagged !== undefined) {
-        return repository.getKeepNUntaggedPlanWithCutoff(inputs.owner, inputs.packageName, inputs.keepNUntagged, {
-            olderThan: inputs.olderThan,
-            cutoffTimestamp: inputs.cutoffTimestamp
-        });
-    }
-    if (inputs.deleteUntagged) {
-        return repository.getDeleteUntaggedPlanWithCutoff(inputs.owner, inputs.packageName, {
-            olderThan: inputs.olderThan,
-            cutoffTimestamp: inputs.cutoffTimestamp
-        });
-    }
-    if (!inputs.deleteTagsRequested &&
-        !inputs.deleteGhostImages &&
-        !inputs.deletePartialImages &&
-        !inputs.deleteOrphanedImages &&
-        inputs.keepNTagged !== undefined) {
-        return repository.getKeepNTaggedPlanWithCutoff(inputs.owner, inputs.packageName, inputs.keepNTagged, [], {
-            olderThan: inputs.olderThan,
-            cutoffTimestamp: inputs.cutoffTimestamp
-        });
-    }
-    return repository.getDeleteTagsPlanWithCutoff(inputs.owner, inputs.packageName, inputs.deleteTags, inputs.excludeTags, {
+    return repository.getCleanupPlanWithCutoff(inputs.owner, inputs.packageName, {
+        deleteTags: inputs.deleteTags,
+        deleteTagsRequested: inputs.deleteTagsRequested,
         deleteGhostImages: inputs.deleteGhostImages,
         deletePartialImages: inputs.deletePartialImages,
         deleteOrphanedImages: inputs.deleteOrphanedImages,
-        deleteTagsRequested: inputs.deleteTagsRequested,
-        keepNTagged: inputs.keepNTagged,
+        excludeTags: inputs.excludeTags,
+        deleteUntagged: inputs.deleteUntagged,
         useRegex: inputs.useRegex,
+        keepNTagged: inputs.keepNTagged,
+        keepNUntagged: inputs.keepNUntagged,
         olderThan: inputs.olderThan,
         cutoffTimestamp: inputs.cutoffTimestamp
     });

package/dist/cli/index.js

@@ -26,16 +26,24 @@ export async function main(argv) {
 }
 function printUsage() {
     console.error(`Usage:
-  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] --delete-untagged [--older-than <interval>]
-  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] --delete-ghost-images [--exclude-tag <tag> ...] [--use-regex] [--keep-n-tagged <count>] [--older-than <interval>]
-  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] --delete-partial-images [--exclude-tag <tag> ...] [--use-regex] [--keep-n-tagged <count>] [--older-than <interval>]
-  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] --delete-orphaned-images [--exclude-tag <tag> ...] [--use-regex] [--keep-n-tagged <count>] [--older-than <interval>]
-  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] --keep-n-tagged <count> [--older-than <interval>]
-  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] --keep-n-untagged <count> [--older-than <interval>]
-  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] --delete-tag <tag> [--delete-tag <tag> ...] [--exclude-tag <tag> ...] [--use-regex] [--older-than <interval>]
+  ghcr-manager cleanup --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> [--token <token>] <cleanup selectors...> [--exclude-tag <tag> ...] [--use-regex] [--older-than <interval>]
   ghcr-manager db-merge --db <target-path> --source-db <path> [--source-db <path> ...]
   ghcr-manager scan --db <path> [--log-level <trace|debug|info|warn|error|silent>] [--github-output <path>] --owner <org> --package <name> --token <token>
-  ghcr-manager untag [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> --token <token> --tag <tag> [--tag <tag> ...]`);
+  ghcr-manager untag [--log-level <trace|debug|info|warn|error|silent>] [--dry-run] --owner <org> --package <name> --token <token> --tag <tag> [--tag <tag> ...]
+
+Cleanup selectors:
+  --delete-untagged
+  --delete-ghost-images
+  --delete-partial-images
+  --delete-orphaned-images
+  --delete-tag <tag> [--delete-tag <tag> ...]
+  --keep-n-tagged <count>
+  --keep-n-untagged <count>
+
+Notes:
+  - Tagged selector families may be combined with --delete-untagged.
+  - --exclude-tag requires at least one tagged selector family.
+  - --delete-untagged and --keep-n-untagged cannot be combined.`);
 }
 const _entryPath = process.argv[1];
 const _isDirectExecution = realpathSync(_entryPath) === realpathSync(fileURLToPath(import.meta.url));

package/dist/db/planner/_planner-direct-target-roots.d.ts

@@ -0,0 +1,17 @@
+import { PlannerSql } from "./_planner-sql.js";
+import { type DeletePlanRoot } from "./_planner-types.js";
+export interface DirectTargetRootOptions {
+    deleteTags: string[];
+    deleteTagsRequested: boolean;
+    excludeTags: string[];
+    deleteUntagged: boolean;
+    keepNTagged?: number;
+    keepNUntagged?: number;
+    useRegex?: boolean;
+    cutoffTimestamp?: string;
+}
+export declare class PlannerDirectTargetRoots {
+    #private;
+    constructor(sql: PlannerSql);
+    list(scanId: number, options: DirectTargetRootOptions): DeletePlanRoot[];
+}

package/dist/db/planner/_planner-direct-target-roots.js

@@ -0,0 +1,199 @@
+import { buildTagSelectorPredicate } from "./_planner-tag-selectors.js";
+import { mapPlanRootRow } from "./_planner-types.js";
+export class PlannerDirectTargetRoots {
+    #sql;
+    constructor(sql) {
+        this.#sql = sql;
+    }
+    list(scanId, options) {
+        const selectedTagPredicate = options.deleteTags.length > 0
+            ? buildTagSelectorPredicate(this.#sql.database, "t.tag", options.deleteTags, options.useRegex ?? false)
+            : undefined;
+        const excludedTagPredicate = options.excludeTags.length > 0
+            ? buildTagSelectorPredicate(this.#sql.database, "xt.tag", options.excludeTags, options.useRegex ?? false)
+            : undefined;
+        const params = [scanId];
+        const cutoffSql = options.cutoffTimestamp ? "AND created_at < ?" : "";
+        if (options.cutoffTimestamp) {
+            params.push(options.cutoffTimestamp);
+        }
+        const selectedTagsSql = selectedTagPredicate
+            ? `
+        SELECT DISTINCT t.version_id, t.tag
+        FROM tags t
+        WHERE t.scan_id = ?
+          AND (${selectedTagPredicate.sql})
+      `
+            : `
+        SELECT NULL AS version_id, NULL AS tag
+        WHERE 1 = 0
+      `;
+        if (selectedTagPredicate) {
+            params.push(scanId, ...selectedTagPredicate.params);
+        }
+        const excludedVersionsSql = excludedTagPredicate
+            ? `
+        SELECT DISTINCT xt.version_id
+        FROM tags xt
+        WHERE xt.scan_id = ?
+          AND (${excludedTagPredicate.sql})
+      `
+            : `
+        SELECT NULL AS version_id
+        WHERE 1 = 0
+      `;
+        if (excludedTagPredicate) {
+            params.push(scanId, ...excludedTagPredicate.params);
+        }
+        const taggedBranchEnabled = options.deleteTagsRequested || options.keepNTagged !== undefined ? 1 : 0;
+        const deleteTagsRequested = options.deleteTagsRequested ? 1 : 0;
+        const keepNTaggedActive = options.keepNTagged !== undefined ? 1 : 0;
+        const deleteUntagged = options.deleteUntagged ? 1 : 0;
+        const keepNUntaggedActive = options.keepNUntagged !== undefined ? 1 : 0;
+        const paramsTail = [
+            taggedBranchEnabled,
+            deleteTagsRequested,
+            deleteTagsRequested,
+            keepNTaggedActive,
+            deleteTagsRequested,
+            keepNTaggedActive,
+            options.keepNTagged ?? 0,
+            deleteUntagged,
+            keepNUntaggedActive,
+            deleteUntagged,
+            deleteUntagged,
+            keepNUntaggedActive,
+            options.keepNUntagged ?? 0
+        ];
+        const sql = `
+      WITH root_candidates AS (
+        SELECT
+          root_version_id AS version_id,
+          root_digest,
+          root_manifest_kind,
+          created_at,
+          tag_count,
+          is_tagged
+        FROM v_scan_root_manifests
+        WHERE scan_id = ?
+          AND has_ancestor = 0
+          ${cutoffSql}
+      ),
+      selected_tags AS (
+        ${selectedTagsSql}
+      ),
+      excluded_versions AS (
+        ${excludedVersionsSql}
+      ),
+      matched_tag_counts AS (
+        SELECT
+          st.version_id,
+          COUNT(DISTINCT st.tag) AS matched_tag_count
+        FROM selected_tags st
+        GROUP BY st.version_id
+      ),
+      eligible_tagged_roots AS (
+        SELECT
+          rc.version_id,
+          rc.root_digest,
+          rc.root_manifest_kind,
+          rc.created_at,
+          rc.tag_count AS total_tag_count,
+          COALESCE(mtc.matched_tag_count, 0) AS matched_tag_count
+        FROM root_candidates rc
+        LEFT JOIN matched_tag_counts mtc
+          ON mtc.version_id = rc.version_id
+        LEFT JOIN excluded_versions ev
+          ON ev.version_id = rc.version_id
+        WHERE rc.is_tagged = 1
+          AND ev.version_id IS NULL
+          AND ? = 1
+      ),
+      ranked_tagged_roots AS (
+        SELECT
+          version_id,
+          root_digest,
+          root_manifest_kind,
+          total_tag_count,
+          matched_tag_count,
+          ROW_NUMBER() OVER (
+            ORDER BY created_at DESC, version_id DESC, root_digest DESC
+          ) AS recency_rank
+        FROM eligible_tagged_roots
+        WHERE ? = 0
+           OR matched_tag_count > 0
+      ),
+      final_tagged_targets AS (
+        SELECT
+          version_id,
+          root_digest,
+          root_manifest_kind,
+          CASE
+            WHEN ? = 0
+              THEN 'keep-n-tagged-overflow'
+            WHEN ? = 1 AND total_tag_count = matched_tag_count
+              THEN 'keep-n-tagged-overflow'
+            WHEN total_tag_count = matched_tag_count
+              THEN 'delete-tags-all-tags-selected'
+            ELSE 'delete-tags-partial-tag-match'
+          END AS direct_target_reason,
+          CASE
+            WHEN ? = 0
+              THEN 'delete-root'
+            WHEN total_tag_count = matched_tag_count
+              THEN 'delete-root'
+            ELSE 'untag-only'
+          END AS selection_mode
+        FROM ranked_tagged_roots
+        WHERE ? = 0
+           OR recency_rank > ?
+      ),
+      ranked_untagged_roots AS (
+        SELECT
+          rc.version_id,
+          rc.root_digest,
+          rc.root_manifest_kind,
+          ROW_NUMBER() OVER (
+            ORDER BY rc.created_at DESC, rc.version_id DESC, rc.root_digest DESC
+          ) AS recency_rank
+        FROM root_candidates rc
+        WHERE rc.is_tagged = 0
+          AND (? = 1 OR ? = 1)
+      ),
+      final_untagged_targets AS (
+        SELECT
+          version_id,
+          root_digest,
+          root_manifest_kind,
+          CASE
+            WHEN ? = 1
+              THEN 'delete-untagged'
+            ELSE 'keep-n-untagged-overflow'
+          END AS direct_target_reason,
+          'delete-root' AS selection_mode
+        FROM ranked_untagged_roots
+        WHERE ? = 1
+           OR (? = 1 AND recency_rank > ?)
+      )
+      SELECT
+        version_id,
+        root_digest,
+        root_manifest_kind,
+        direct_target_reason,
+        selection_mode
+      FROM final_tagged_targets
+
+      UNION ALL
+
+      SELECT
+        version_id,
+        root_digest,
+        root_manifest_kind,
+        direct_target_reason,
+        selection_mode
+      FROM final_untagged_targets
+      ORDER BY root_digest
+    `;
+        return this.#sql.all(sql, [...params, ...paramsTail]).map(mapPlanRootRow);
+    }
+}

package/dist/db/planner/_planner-latest-scan.d.ts

@@ -0,0 +1,10 @@
+import type { ScanRow } from "./_planner-types.js";
+interface LatestScanSql {
+    get<T>(sql: string, params: Array<number | string>): T | undefined;
+}
+export declare class PlannerLatestScan {
+    #private;
+    constructor(sql: LatestScanSql);
+    get(owner: string, packageName: string): ScanRow;
+}
+export {};

package/dist/db/planner/_planner-latest-scan.js

@@ -0,0 +1,20 @@
+export class PlannerLatestScan {
+    #sql;
+    constructor(sql) {
+        this.#sql = sql;
+    }
+    get(owner, packageName) {
+        const sql = `
+      SELECT scan_id, owner, package_name, scan_completed_at
+      FROM v_latest_scan_per_package
+      WHERE owner = ?
+        AND package_name = ?
+      LIMIT 1
+    `;
+        const row = this.#sql.get(sql, [owner, packageName]);
+        if (!row) {
+            throw new Error(`database does not contain completed package scan for ${owner}/${packageName}`);
+        }
+        return row;
+    }
+}

package/dist/db/planner/_planner-repository.d.ts

@@ -7,7 +7,6 @@ export declare class PlannerRepository {
     getDeleteUntaggedPlan(owner: string, packageName: string): DeletePlan;
     getLatestCompletedScanId(owner: string, packageName: string): number;
     getKeepNUntaggedPlan(owner: string, packageName: string, keepCount: number): DeletePlan;
-    getKeepNTaggedPlan(owner: string, packageName: string, keepCount: number): DeletePlan;
     getDeleteUntaggedPlanWithCutoff(owner: string, packageName: string, options?: {
         olderThan?: string;
         cutoffTimestamp?: string;
@@ -16,10 +15,6 @@ export declare class PlannerRepository {
         olderThan?: string;
         cutoffTimestamp?: string;
     }): DeletePlan;
-    getKeepNTaggedPlanWithCutoff(owner: string, packageName: string, keepCount: number, excludeTags: string[], options?: {
-        olderThan?: string;
-        cutoffTimestamp?: string;
-    }): DeletePlan;
     getDeleteTagsPlan(owner: string, packageName: string, deleteTags: string[], excludeTags: string[]): DeletePlan;
     getDeleteTagsPlanWithCutoff(owner: string, packageName: string, deleteTags: string[], excludeTags: string[], options?: {
         deleteTagsRequested?: boolean;
@@ -31,4 +26,18 @@ export declare class PlannerRepository {
         olderThan?: string;
         cutoffTimestamp?: string;
     }): DeletePlan;
+    getCleanupPlanWithCutoff(owner: string, packageName: string, options?: {
+        deleteUntagged?: boolean;
+        deleteGhostImages?: boolean;
+        deletePartialImages?: boolean;
+        deleteOrphanedImages?: boolean;
+        deleteTags?: string[];
+        deleteTagsRequested?: boolean;
+        excludeTags?: string[];
+        keepNTagged?: number;
+        keepNUntagged?: number;
+        useRegex?: boolean;
+        olderThan?: string;
+        cutoffTimestamp?: string;
+    }): DeletePlan;
 }

package/dist/db/planner/_planner-repository.js

@@ -1,95 +1,73 @@
+import { PlannerDirectTargetRoots } from "./_planner-direct-target-roots.js";
+import { PlannerDirectTargetTags } from "./_planner-direct-target-tags.js";
+import { PlannerLatestScan } from "./_planner-latest-scan.js";
 import { buildPlanOutputs } from "./_planner-output.js";
 import { PlannerPlanArtifacts } from "./_planner-plan-artifacts.js";
 import { PlannerSql } from "./_planner-sql.js";
-import { PlannerTaggedTargets } from "./_planner-tagged-targets.js";
-import { PlannerUntaggedTargets } from "./_planner-untagged-targets.js";
 export class PlannerRepository {
-    #untaggedTargets;
-    #taggedTargets;
+    #latestScan;
+    #directTargetTags;
+    #directTargetRoots;
     #planArtifacts;
     constructor(database, logger) {
         const sql = new PlannerSql(database, logger);
-        this.#untaggedTargets = new PlannerUntaggedTargets(sql);
-        this.#taggedTargets = new PlannerTaggedTargets(sql);
+        this.#latestScan = new PlannerLatestScan(sql);
+        this.#directTargetTags = new PlannerDirectTargetTags(sql);
+        this.#directTargetRoots = new PlannerDirectTargetRoots(sql);
         this.#planArtifacts = new PlannerPlanArtifacts(sql);
     }
     getDeleteUntaggedPlan(owner, packageName) {
         return this.getDeleteUntaggedPlanWithCutoff(owner, packageName);
     }
     getLatestCompletedScanId(owner, packageName) {
-        return this.#untaggedTargets.getLatestCompletedScan(owner, packageName).scan_id;
+        return this.#latestScan.get(owner, packageName).scan_id;
     }
     getKeepNUntaggedPlan(owner, packageName, keepCount) {
         return this.getKeepNUntaggedPlanWithCutoff(owner, packageName, keepCount);
     }
-    getKeepNTaggedPlan(owner, packageName, keepCount) {
-        return this.getKeepNTaggedPlanWithCutoff(owner, packageName, keepCount, []);
-    }
     getDeleteUntaggedPlanWithCutoff(owner, packageName, options) {
-        const scan = this.#untaggedTargets.getLatestCompletedScan(owner, packageName);
-        const directTargetRoots = this.#untaggedTargets.listDeleteUntaggedDirectTargetRoots(scan.scan_id, options?.cutoffTimestamp);
-        const planArtifacts = this.#planArtifacts.build(scan.scan_id, directTargetRoots);
-        return {
-            owner: scan.owner,
-            packageName: scan.package_name,
-            scanCompletedAt: scan.scan_completed_at,
-            plannerInputs: _buildPlannerInputs({
-                deleteUntagged: true,
-                olderThan: options?.olderThan,
-                cutoffTimestamp: options?.cutoffTimestamp
-            }),
-            ...buildPlanOutputs([], directTargetRoots, planArtifacts)
-        };
+        return this.getCleanupPlanWithCutoff(owner, packageName, {
+            deleteUntagged: true,
+            olderThan: options?.olderThan,
+            cutoffTimestamp: options?.cutoffTimestamp
+        });
     }
     getKeepNUntaggedPlanWithCutoff(owner, packageName, keepCount, options) {
-        const scan = this.#untaggedTargets.getLatestCompletedScan(owner, packageName);
-        const directTargetRoots = this.#untaggedTargets.listKeepNUntaggedDirectTargetRoots(scan.scan_id, keepCount, options?.cutoffTimestamp);
-        const planArtifacts = this.#planArtifacts.build(scan.scan_id, directTargetRoots);
-        return {
-            owner: scan.owner,
-            packageName: scan.package_name,
-            scanCompletedAt: scan.scan_completed_at,
-            plannerInputs: _buildPlannerInputs({
-                keepNUntagged: keepCount,
-                olderThan: options?.olderThan,
-                cutoffTimestamp: options?.cutoffTimestamp
-            }),
-            ...buildPlanOutputs([], directTargetRoots, planArtifacts)
-        };
-    }
-    getKeepNTaggedPlanWithCutoff(owner, packageName, keepCount, excludeTags, options) {
-        const scan = this.#untaggedTargets.getLatestCompletedScan(owner, packageName);
-        const directTargetRoots = this.#taggedTargets.listTaggedDirectTargetRoots(scan.scan_id, {
-            deleteTags: [],
-            excludeTags,
-            keepCount,
+        return this.getCleanupPlanWithCutoff(owner, packageName, {
+            keepNUntagged: keepCount,
+            olderThan: options?.olderThan,
             cutoffTimestamp: options?.cutoffTimestamp
         });
-        const planArtifacts = this.#planArtifacts.build(scan.scan_id, directTargetRoots);
-        return {
-            owner: scan.owner,
-            packageName: scan.package_name,
-            scanCompletedAt: scan.scan_completed_at,
-            plannerInputs: _buildPlannerInputs({
-                excludeTags,
-                keepNTagged: keepCount,
-                olderThan: options?.olderThan,
-                cutoffTimestamp: options?.cutoffTimestamp
-            }),
-            ...buildPlanOutputs([], directTargetRoots, planArtifacts)
-        };
     }
     getDeleteTagsPlan(owner, packageName, deleteTags, excludeTags) {
         return this.getDeleteTagsPlanWithCutoff(owner, packageName, deleteTags, excludeTags);
     }
     getDeleteTagsPlanWithCutoff(owner, packageName, deleteTags, excludeTags, options) {
-        const scan = this.#untaggedTargets.getLatestCompletedScan(owner, packageName);
-        const directTargetTags = this.#taggedTargets.listDeleteTagDirectTargetTags(scan.scan_id, deleteTags, excludeTags, options?.useRegex ?? false, options?.cutoffTimestamp);
-        const directTargetRoots = this.#taggedTargets.listTaggedDirectTargetRoots(scan.scan_id, {
+        return this.getCleanupPlanWithCutoff(owner, packageName, {
             deleteTags,
+            excludeTags,
+            deleteGhostImages: options?.deleteGhostImages,
+            deletePartialImages: options?.deletePartialImages,
+            deleteOrphanedImages: options?.deleteOrphanedImages,
             deleteTagsRequested: options?.deleteTagsRequested ?? true,
+            keepNTagged: options?.keepNTagged,
+            useRegex: options?.useRegex,
+            olderThan: options?.olderThan,
+            cutoffTimestamp: options?.cutoffTimestamp
+        });
+    }
+    getCleanupPlanWithCutoff(owner, packageName, options) {
+        const scan = this.#latestScan.get(owner, packageName);
+        const deleteTags = options?.deleteTags ?? [];
+        const excludeTags = options?.excludeTags ?? [];
+        const directTargetTags = this.#directTargetTags.listDeleteTagDirectTargetTags(scan.scan_id, deleteTags, excludeTags, options?.useRegex ?? false, options?.cutoffTimestamp);
+        const directTargetRoots = this.#directTargetRoots.list(scan.scan_id, {
+            deleteTags,
+            deleteTagsRequested: options?.deleteTagsRequested ?? false,
             excludeTags,
-            keepCount: options?.keepNTagged,
+            deleteUntagged: options?.deleteUntagged ?? false,
+            keepNTagged: options?.keepNTagged,
+            keepNUntagged: options?.keepNUntagged,
             useRegex: options?.useRegex ?? false,
             cutoffTimestamp: options?.cutoffTimestamp
         });
@@ -103,8 +81,10 @@ export class PlannerRepository {
                 deletePartialImages: options?.deletePartialImages || undefined,
                 deleteOrphanedImages: options?.deleteOrphanedImages || undefined,
                 deleteTags,
+                deleteUntagged: options?.deleteUntagged || undefined,
                 excludeTags,
                 keepNTagged: options?.keepNTagged,
+                keepNUntagged: options?.keepNUntagged,
                 useRegex: options?.useRegex || undefined,
                 olderThan: options?.olderThan,
                 cutoffTimestamp: options?.cutoffTimestamp
@@ -118,9 +98,6 @@ function _buildPlannerInputs(inputs) {
         if (value === undefined) {
             return false;
         }
-        if (value === false) {
-            return false;
-        }
         return !(Array.isArray(value) && value.length === 0);
     }));
 }

package/package.json

@@ -9,7 +9,7 @@
     "type": "git",
     "url": "https://github.com/gh-workflow/ghcr-manager"
   },
-  "version": "0.9.2",
+  "version": "0.9.3",
   "type": "module",
   "engines": {
     "node": ">=20.0.0"

package/dist/db/planner/_planner-delete-tag-root-targets.d.ts

@@ -1,7 +0,0 @@
-import { PlannerSql } from "./_planner-sql.js";
-import { type DeletePlanRoot } from "./_planner-types.js";
-export declare class PlannerDeleteTagRootTargets {
-    #private;
-    constructor(sql: PlannerSql);
-    list(scanId: number, deleteTags: string[], excludeTags: string[], useRegex: boolean, keepCount?: number, cutoffTimestamp?: string): DeletePlanRoot[];
-}

package/dist/db/planner/_planner-delete-tag-root-targets.js

@@ -1,130 +0,0 @@
-import { buildTagSelectorPredicate } from "./_planner-tag-selectors.js";
-import { mapPlanRootRow } from "./_planner-types.js";
-export class PlannerDeleteTagRootTargets {
-    #sql;
-    constructor(sql) {
-        this.#sql = sql;
-    }
-    list(scanId, deleteTags, excludeTags, useRegex, keepCount, cutoffTimestamp) {
-        const selectedTagPredicate = buildTagSelectorPredicate(this.#sql.database, "st.tag", deleteTags, useRegex);
-        const excludedTagPredicate = excludeTags.length > 0
-            ? buildTagSelectorPredicate(this.#sql.database, "xt.tag", excludeTags, useRegex)
-            : undefined;
-        const excludedVersionsCte = excludedTagPredicate
-            ? `
-        excluded_versions AS (
-          SELECT DISTINCT xt.version_id
-          FROM tags xt
-          WHERE xt.scan_id = ?
-            AND (${excludedTagPredicate.sql})
-        ),
-      `
-            : "";
-        const excludedJoinSql = excludedTagPredicate
-            ? `
-        LEFT JOIN excluded_versions ev
-          ON ev.version_id = st.version_id
-      `
-            : "";
-        const excludedWhereSql = excludedTagPredicate ? "AND ev.version_id IS NULL" : "";
-        const cutoffSql = cutoffTimestamp ? "AND pv.created_at < ?" : "";
-        const keepSql = keepCount !== undefined ? "WHERE recency_rank > ?" : "";
-        const params = [scanId, ...selectedTagPredicate.params];
-        if (excludedTagPredicate) {
-            params.push(scanId, ...excludedTagPredicate.params);
-        }
-        if (cutoffTimestamp) {
-            params.push(cutoffTimestamp);
-        }
-        params.push(scanId);
-        const tailParams = [keepCount !== undefined ? 1 : 0];
-        if (keepCount !== undefined) {
-            tailParams.push(keepCount);
-        }
-        const sql = `
-      WITH selected_tags AS (
-        SELECT st.scan_id, st.version_id, st.tag
-        FROM tags st
-        WHERE st.scan_id = ?
-          AND (${selectedTagPredicate.sql})
-      ),
-      ${excludedVersionsCte}
-      matched_candidate_roots AS (
-        SELECT DISTINCT
-          st.version_id AS version_id,
-          m.digest AS root_digest,
-          m.manifest_kind AS root_manifest_kind,
-          pv.created_at
-        FROM selected_tags st
-        JOIN manifests m
-          ON m.scan_id = st.scan_id
-         AND m.version_id = st.version_id
-        JOIN package_versions pv
-          ON pv.scan_id = st.scan_id
-         AND pv.version_id = st.version_id
-        ${excludedJoinSql}
-        WHERE 1 = 1
-          ${excludedWhereSql}
-          ${cutoffSql}
-          AND NOT EXISTS (
-            SELECT 1
-            FROM manifest_reachability mr
-            WHERE mr.scan_id = st.scan_id
-              AND mr.descendant_digest = m.digest
-              AND mr.min_distance > 0
-          )
-      ),
-      matched_roots AS (
-        SELECT
-          mcr.version_id,
-          mcr.root_digest,
-          mcr.root_manifest_kind,
-          mcr.created_at,
-          COUNT(t.tag) AS total_tag_count,
-          COUNT(st.tag) AS matched_tag_count
-        FROM matched_candidate_roots mcr
-        JOIN tags t
-          ON t.scan_id = ?
-         AND t.version_id = mcr.version_id
-        LEFT JOIN selected_tags st
-          ON st.scan_id = t.scan_id
-         AND st.version_id = t.version_id
-         AND st.tag = t.tag
-        GROUP BY mcr.version_id, mcr.root_digest, mcr.root_manifest_kind, mcr.created_at
-        HAVING matched_tag_count > 0
-      ),
-      ranked_roots AS (
-        SELECT
-          version_id,
-          root_digest,
-          root_manifest_kind,
-          total_tag_count,
-          matched_tag_count,
-          ROW_NUMBER() OVER (
-            ORDER BY created_at DESC, version_id DESC, root_digest DESC
-          ) AS recency_rank
-        FROM matched_roots
-      )
-      SELECT
-        version_id,
-        root_digest,
-        root_manifest_kind,
-        CASE
-          WHEN total_tag_count = matched_tag_count AND ? = 1
-            THEN 'keep-n-tagged-overflow'
-          WHEN total_tag_count = matched_tag_count
-            THEN 'delete-tags-all-tags-selected'
-          ELSE 'delete-tags-partial-tag-match'
-        END AS direct_target_reason,
-        CASE
-          WHEN total_tag_count = matched_tag_count
-            THEN 'delete-root'
-          ELSE 'untag-only'
-        END AS selection_mode
-      FROM ranked_roots
-      ${keepSql}
-      ORDER BY root_digest
-    `;
-        return this.#sql.all(sql, [...params, ...tailParams]).map(mapPlanRootRow);
-    }
-}

package/dist/db/planner/_planner-keep-tagged-root-targets.d.ts

@@ -1,7 +0,0 @@
-import { PlannerSql } from "./_planner-sql.js";
-import { type DeletePlanRoot } from "./_planner-types.js";
-export declare class PlannerKeepTaggedRootTargets {
-    #private;
-    constructor(sql: PlannerSql);
-    list(scanId: number, excludeTags: string[], useRegex: boolean, keepCount?: number, cutoffTimestamp?: string): DeletePlanRoot[];
-}

package/dist/db/planner/_planner-keep-tagged-root-targets.js

@@ -1,74 +0,0 @@
-import { buildTagSelectorPredicate } from "./_planner-tag-selectors.js";
-import { mapPlanRootRow } from "./_planner-types.js";
-export class PlannerKeepTaggedRootTargets {
-    #sql;
-    constructor(sql) {
-        this.#sql = sql;
-    }
-    list(scanId, excludeTags, useRegex, keepCount, cutoffTimestamp) {
-        const excludedTagPredicate = excludeTags.length > 0
-            ? buildTagSelectorPredicate(this.#sql.database, "xt.tag", excludeTags, useRegex)
-            : undefined;
-        const excludedRootSql = excludedTagPredicate
-            ? `
-        AND NOT EXISTS (
-          SELECT 1
-          FROM tags xt
-          WHERE xt.scan_id = pv.scan_id
-            AND xt.version_id = pv.version_id
-            AND (${excludedTagPredicate.sql})
-        )
-      `
-            : "";
-        const cutoffSql = cutoffTimestamp ? "AND pv.created_at < ?" : "";
-        const keepSql = keepCount !== undefined ? "WHERE recency_rank > ?" : "";
-        const params = [scanId, ...(excludedTagPredicate?.params ?? [])];
-        if (cutoffTimestamp) {
-            params.push(cutoffTimestamp);
-        }
-        if (keepCount !== undefined) {
-            params.push(keepCount);
-        }
-        const sql = `
-      WITH eligible_tagged_roots AS (
-        SELECT
-          pv.version_id AS version_id,
-          m.digest AS root_digest,
-          m.manifest_kind AS root_manifest_kind,
-          ROW_NUMBER() OVER (
-            ORDER BY pv.created_at DESC, pv.version_id DESC, m.digest DESC
-          ) AS recency_rank
-        FROM package_versions pv
-        JOIN manifests m
-          ON m.scan_id = pv.scan_id
-         AND m.version_id = pv.version_id
-        WHERE pv.scan_id = ?
-          AND EXISTS (
-            SELECT 1
-            FROM tags t
-            WHERE t.scan_id = pv.scan_id
-              AND t.version_id = pv.version_id
-          )
-          ${excludedRootSql}
-          AND NOT EXISTS (
-            SELECT 1
-            FROM manifest_reachability mr
-            WHERE mr.scan_id = pv.scan_id
-              AND mr.descendant_digest = m.digest
-              AND mr.min_distance > 0
-          )
-          ${cutoffSql}
-      )
-      SELECT
-        version_id,
-        root_digest,
-        root_manifest_kind,
-        'keep-n-tagged-overflow' AS direct_target_reason,
-        'delete-root' AS selection_mode
-      FROM eligible_tagged_roots
-      ${keepSql}
-      ORDER BY root_digest
-    `;
-        return this.#sql.all(sql, params).map(mapPlanRootRow);
-    }
-}

package/dist/db/planner/_planner-tagged-root-targets.d.ts

@@ -1,15 +0,0 @@
-import { PlannerSql } from "./_planner-sql.js";
-import type { DeletePlanRoot } from "./_planner-types.js";
-export interface TaggedRootTargetOptions {
-    deleteTags: string[];
-    deleteTagsRequested?: boolean;
-    excludeTags: string[];
-    keepCount?: number;
-    useRegex?: boolean;
-    cutoffTimestamp?: string;
-}
-export declare class PlannerTaggedRootTargets {
-    #private;
-    constructor(sql: PlannerSql);
-    listTaggedDirectTargetRoots(scanId: number, options: TaggedRootTargetOptions): DeletePlanRoot[];
-}

package/dist/db/planner/_planner-tagged-root-targets.js

@@ -1,19 +0,0 @@
-import { PlannerDeleteTagRootTargets } from "./_planner-delete-tag-root-targets.js";
-import { PlannerKeepTaggedRootTargets } from "./_planner-keep-tagged-root-targets.js";
-export class PlannerTaggedRootTargets {
-    #deleteTagTargets;
-    #keepTaggedTargets;
-    constructor(sql) {
-        this.#deleteTagTargets = new PlannerDeleteTagRootTargets(sql);
-        this.#keepTaggedTargets = new PlannerKeepTaggedRootTargets(sql);
-    }
-    listTaggedDirectTargetRoots(scanId, options) {
-        if (options.deleteTagsRequested && options.deleteTags.length === 0) {
-            return [];
-        }
-        if (options.deleteTags.length === 0) {
-            return this.#keepTaggedTargets.list(scanId, options.excludeTags, options.useRegex ?? false, options.keepCount, options.cutoffTimestamp);
-        }
-        return this.#deleteTagTargets.list(scanId, options.deleteTags, options.excludeTags, options.useRegex ?? false, options.keepCount, options.cutoffTimestamp);
-    }
-}

package/dist/db/planner/_planner-tagged-targets.d.ts

@@ -1,8 +0,0 @@
-import { type TaggedRootTargetOptions } from "./_planner-tagged-root-targets.js";
-import { PlannerSql } from "./_planner-sql.js";
-export declare class PlannerTaggedTargets {
-    #private;
-    constructor(sql: PlannerSql);
-    listDeleteTagDirectTargetTags(scanId: number, deleteTags: string[], excludeTags: string[], useRegex: boolean, cutoffTimestamp?: string): string[];
-    listTaggedDirectTargetRoots(scanId: number, options: TaggedRootTargetOptions): import("./_planner-types.js").DeletePlanRoot[];
-}

package/dist/db/planner/_planner-tagged-targets.js

@@ -1,16 +0,0 @@
-import { PlannerDirectTargetTags } from "./_planner-direct-target-tags.js";
-import { PlannerTaggedRootTargets } from "./_planner-tagged-root-targets.js";
-export class PlannerTaggedTargets {
-    #directTargetTags;
-    #rootTargets;
-    constructor(sql) {
-        this.#directTargetTags = new PlannerDirectTargetTags(sql);
-        this.#rootTargets = new PlannerTaggedRootTargets(sql);
-    }
-    listDeleteTagDirectTargetTags(scanId, deleteTags, excludeTags, useRegex, cutoffTimestamp) {
-        return this.#directTargetTags.listDeleteTagDirectTargetTags(scanId, deleteTags, excludeTags, useRegex, cutoffTimestamp);
-    }
-    listTaggedDirectTargetRoots(scanId, options) {
-        return this.#rootTargets.listTaggedDirectTargetRoots(scanId, options);
-    }
-}

package/dist/db/planner/_planner-untagged-targets.d.ts

@@ -1,9 +0,0 @@
-import { PlannerSql } from "./_planner-sql.js";
-import { type DeletePlanRoot, type ScanRow } from "./_planner-types.js";
-export declare class PlannerUntaggedTargets {
-    #private;
-    constructor(sql: PlannerSql);
-    getLatestCompletedScan(owner: string, packageName: string): ScanRow;
-    listDeleteUntaggedDirectTargetRoots(scanId: number, cutoffTimestamp?: string): DeletePlanRoot[];
-    listKeepNUntaggedDirectTargetRoots(scanId: number, keepCount: number, cutoffTimestamp?: string): DeletePlanRoot[];
-}

package/dist/db/planner/_planner-untagged-targets.js

@@ -1,91 +0,0 @@
-import { mapPlanRootRow } from "./_planner-types.js";
-export class PlannerUntaggedTargets {
-    #sql;
-    constructor(sql) {
-        this.#sql = sql;
-    }
-    getLatestCompletedScan(owner, packageName) {
-        const sql = `
-      SELECT scan_id, owner, package_name, scan_completed_at
-      FROM v_latest_scan_per_package
-      WHERE owner = ?
-        AND package_name = ?
-      LIMIT 1
-    `;
-        const row = this.#sql.get(sql, [owner, packageName]);
-        if (!row) {
-            throw new Error(`database does not contain completed package scan for ${owner}/${packageName}`);
-        }
-        return row;
-    }
-    listDeleteUntaggedDirectTargetRoots(scanId, cutoffTimestamp) {
-        const cutoffSql = cutoffTimestamp ? "AND created_at < ?" : "";
-        const sql = `
-      SELECT
-        root_version_id AS version_id,
-        root_digest,
-        root_manifest_kind,
-        'delete-untagged' AS direct_target_reason,
-        'delete-root' AS selection_mode
-      FROM v_scan_root_manifests
-      WHERE scan_id = ?
-        AND is_tagged = 0
-        AND has_ancestor = 0
-        ${cutoffSql}
-      ORDER BY root_digest
-    `;
-        const rows = this.#sql.all(sql, [
-            scanId,
-            ...(cutoffTimestamp ? [cutoffTimestamp] : [])
-        ]);
-        return rows.map(mapPlanRootRow);
-    }
-    listKeepNUntaggedDirectTargetRoots(scanId, keepCount, cutoffTimestamp) {
-        const cutoffSql = cutoffTimestamp ? "AND pv.created_at < ?" : "";
-        const sql = `
-      WITH eligible_untagged_roots AS (
-        SELECT
-          pv.version_id AS version_id,
-          m.digest AS root_digest,
-          m.manifest_kind AS root_manifest_kind,
-          ROW_NUMBER() OVER (
-            ORDER BY pv.created_at DESC, pv.version_id DESC, m.digest DESC
-          ) AS recency_rank
-        FROM package_versions pv
-        JOIN manifests m
-          ON m.scan_id = pv.scan_id
-         AND m.version_id = pv.version_id
-        WHERE pv.scan_id = ?
-          AND NOT EXISTS (
-            SELECT 1
-            FROM tags t
-            WHERE t.scan_id = pv.scan_id
-              AND t.version_id = pv.version_id
-          )
-          AND NOT EXISTS (
-            SELECT 1
-            FROM manifest_reachability mr
-            WHERE mr.scan_id = pv.scan_id
-              AND mr.descendant_digest = m.digest
-              AND mr.min_distance > 0
-          )
-          ${cutoffSql}
-      )
-      SELECT
-        version_id,
-        root_digest,
-        root_manifest_kind,
-        'keep-n-untagged-overflow' AS direct_target_reason,
-        'delete-root' AS selection_mode
-      FROM eligible_untagged_roots
-      WHERE recency_rank > ?
-      ORDER BY root_digest
-    `;
-        const rows = this.#sql.all(sql, [
-            scanId,
-            ...(cutoffTimestamp ? [cutoffTimestamp] : []),
-            keepCount
-        ]);
-        return rows.map(mapPlanRootRow);
-    }
-}