0
  #   ˆl–ßi~”Ò~êqAãLÜªbÑ¿Ä„®	¿ÁÆ ?÷     #!/usr/local/cpanel/3rdparty/bin/perl

#                                      Copyright 2025 WebPros International, LLC
#                                                           All rights reserved.
# copyright@cpanel.net                                         http://cpanel.net
# This code is subject to the cPanel license. Unauthorized copying is prohibited.

=encoding utf-8

=head1 NAME

comet_protected_item_maintenance - Maintenance and retention operations for Comet Protected Items and deleted users

=head1 SYNOPSIS

    comet_protected_item_maintenance [--status]
    comet_protected_item_maintenance --list-users
    comet_protected_item_maintenance --prune-days=90 [--user=USERNAME] [--users=USER1,USER2,...] [--dry-run]
    comet_protected_item_maintenance --list-deleted-user-snapshots
    comet_protected_item_maintenance --prune-user=USERNAME [--dry-run]
    comet_protected_item_maintenance --prune-all-deleted-users [--dry-run]

=head1 DESCRIPTION

Performs maintenance on the consolidated metadata database for Comet Protected Items
and deleted cPanel users. Supports listing users, pruning terminated Protected Item
records, pruning deleted user snapshot records from backup run logs, enumerating
snapshots for deleted users, and deleting those snapshots from storage.

The metadata database tracks both active Protected Item mappings and retention
information for deleted users. Snapshot data is stored in the backup run logs database.

=cut

package scripts::comet_protected_item_maintenance;

use cPstrict;

use Getopt::Long ();
use Pod::Usage   ();

use FindBin;
use lib "$FindBin::Bin/../plugins/whm/comet/perl/usr/local/cpanel";

use Whostmgr::CometBackup::ProtectedItemMap ();

use Whostmgr::CometBackup::DeletedUsers ();

# Option variables
my $prune_days              = 0;
my $list_users              = 0;
my $help                    = 0;
my $status                  = 0;     # explicit status request
my $prune_user              = '';
my $prune_all_deleted_users = 0;
my $list_deleted_snapshots  = 0;
my $dry_run                 = 0;
my $user                    = '';    # single user for --prune-days
my $users                   = '';    # comma-separated users for --prune-days

sub main {

    # Plugin policy: nothing in this process should be world-readable.
    umask 0027;

    Getopt::Long::GetOptions(
        'prune-days=i'                => \$prune_days,
        'list-users'                  => \$list_users,
        'help|h'                      => \$help,
        'status'                      => \$status,
        'prune-user=s'                => \$prune_user,
        'prune-all-deleted-users'     => \$prune_all_deleted_users,
        'list-deleted-user-snapshots' => \$list_deleted_snapshots,
        'dry-run'                     => \$dry_run,
        'user=s'                      => \$user,
        'users=s'                     => \$users,
    ) or Pod::Usage::pod2usage(2);

    if ($help) {
        Pod::Usage::pod2usage(1);
        return;
    }

    my $map     = Whostmgr::CometBackup::ProtectedItemMap->new();
    my $deleted = Whostmgr::CometBackup::DeletedUsers->new();

    # Dispatch precedence: prune specific user, prune all, list snapshots, prune-days, list-users, status(default)
    if ($prune_user) {
        prune_single_deleted_user( $deleted, $prune_user, $dry_run );
        return;
    }

    if ($prune_all_deleted_users) {
        prune_all_deleted_users( $deleted, $dry_run );
        return;
    }
    if ($list_deleted_snapshots) {
        list_deleted_user_snapshots($deleted);
        return;
    }
    if ($prune_days) {
        prune_old_records( $map, $prune_days, $dry_run, $user, $users );
        return;
    }

    if ($list_users) {
        list_users_with_protected_items($map);
        return;
    }

    # Default status view
    show_status( $map, $deleted );
    return;
}

sub show_status ( $map, $deleted ) {
    print "Comet Protected Item / Deleted User Status\n";
    print "========================================\n\n";

    my @all_users