M5: retention policy, prune with repacking, append-only locations

- RetentionPolicy (last/daily/weekly/monthly) and PruneService: forget
  snapshots the policy drops, delete packs nothing uses and repack mostly
  unused ones by copying encrypted blobs as-is; new packs are indexed
  before old ones are removed
- a location lock keeps prune and backups apart; append-only locations
  are never pruned (cleanup via the location's lifecycle rules)
- weekly prune from the background job; occ backup:prune [--dry-run],
  backup:retention, backup:target:append-only
- tests: forget+prune frees space and the remaining snapshot restores
  identically, repack of mixed packs, dry-run preview, retention buckets

lib/Command/Prune.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Command;
+
+use OCA\NgBackup\Service\PruneService;
+use OCA\NgBackup\Service\TargetService;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class Prune extends Command {
+	public function __construct(
+		private TargetService $targets,
+		private PruneService $prune,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure(): void {
+		$this->setName('backup:prune')
+			->setDescription('Apply the retention policy: remove old snapshots and the data only they used')
+			->addArgument('target', InputArgument::OPTIONAL, 'Location name or id (default: all that are not append-only)')
+			->addOption('dry-run', null, InputOption::VALUE_NONE, 'Only show what would be removed');
+	}
+
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$name = $input->getArgument('target');
+		$targets = $name === null ? array_filter($this->targets->list(), fn ($t) => !$t->getAppendOnly()) : [$this->targets->get($name)];
+		$dry = (bool)$input->getOption('dry-run');
+		$output->writeln('Policy: ' . json_encode($this->prune->policy()->toArray()) . ($dry ? ' (dry run)' : ''));
+		$rc = 0;
+		foreach ($targets as $t) {
+			try {
+				$r = $this->prune->apply($t, $dry);
+			} catch (\Throwable $e) {
+				$output->writeln('<error>' . $t->getName() . ': ' . $e->getMessage() . '</error>');
+				$rc = 1;
+				continue;
+			}
+			$p = $r['prune'];
+			$output->writeln(sprintf('<info>%s</info>: keep %d, %s %d snapshots; packs: %d, %s %d, repack %d, frees %.1f MiB',
+				$t->getName(), count($r['kept']), $dry ? 'would forget' : 'forgot', count($r['forgotten']), $p['packs'],
+				$dry ? 'would delete' : 'deleted', $p['deleted'], $p['repacked'], $p['freedBytes'] / 1048576));
+		}
+		return $rc;
+	}
+}

lib/Command/Retention.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Command;
+
+use OCA\NgBackup\Service\PruneService;
+use OCA\NgBackup\Service\RetentionPolicy;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class Retention extends Command {
+	public function __construct(
+		private PruneService $prune,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure(): void {
+		$this->setName('backup:retention')
+			->setDescription('Show or set how many snapshots are kept')
+			->addOption('last', null, InputOption::VALUE_REQUIRED, 'Always keep the newest N')
+			->addOption('daily', null, InputOption::VALUE_REQUIRED, 'Keep one per day for the last N days with a backup')
+			->addOption('weekly', null, InputOption::VALUE_REQUIRED, 'Keep one per week for N weeks')
+			->addOption('monthly', null, InputOption::VALUE_REQUIRED, 'Keep one per month for N months')
+			->setHelp("Example: occ backup:retention --last=3 --daily=7 --weekly=4 --monthly=12");
+	}
+
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$p = $this->prune->policy()->toArray();
+		$changed = false;
+		foreach (['last', 'daily', 'weekly', 'monthly'] as $k) {
+			if ($input->getOption($k) !== null) {
+				$p[$k] = max(0, (int)$input->getOption($k));
+				$changed = true;
+			}
+		}
+		if ($changed) {
+			try {
+				$this->prune->setPolicy(RetentionPolicy::fromArray($p));
+			} catch (\InvalidArgumentException $e) {
+				$output->writeln('<error>' . $e->getMessage() . '</error>');
+				return 1;
+			}
+		}
+		$output->writeln(sprintf('Keep the last %d, plus one per day for %d days, per week for %d weeks, per month for %d months.', $p['last'], $p['daily'], $p['weekly'], $p['monthly']));
+		return 0;
+	}
+}

lib/Command/TargetAppendOnly.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Command;
+
+use OCA\NgBackup\Service\TargetService;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class TargetAppendOnly extends Command {
+	public function __construct(
+		private TargetService $targets,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure(): void {
+		$this->setName('backup:target:append-only')
+			->setDescription('Make a location append-only (NG Backup never deletes there) or normal again')
+			->addArgument('target', InputArgument::REQUIRED, 'Location name or id')
+			->addArgument('state', InputArgument::REQUIRED, 'on or off')
+			->setHelp("Append-only protects backups if this server is compromised: combine it with credentials\nwithout delete rights and a lifecycle rule or object lock on the location itself.");
+	}
+
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$state = strtolower((string)$input->getArgument('state'));
+		if (!in_array($state, ['on', 'off'], true)) {
+			$output->writeln('<error>state must be on or off</error>');
+			return 1;
+		}
+		$t = $this->targets->setAppendOnly($this->targets->get($input->getArgument('target')), $state === 'on');
+		$output->writeln($t->getName() . ' is ' . ($t->getAppendOnly() ? 'append-only' : 'normal') . '.');
+		return 0;
+	}
+}