Update style rules

Code style cleanup to mostly conform to PSR-12

.gitignore

@@ -1,17 +1,27 @@
-# Temporary files and dependencies
+# Temporary files
 
-/vendor/
-/vendor-bin/*/vendor
-/node_modules
+/release/
 /documentation/
 /manual/
 /tests/coverage/
+/dist/arch/arsse/
+/dist/arch/src/
+/dist/arch/pkg/
+/dist/man/
 /arsse.db*
 /config.php
 /.php_cs.cache
-/yarn-error.log
+/.php-cs-fixer.cache
 /tests/.phpunit.result.cache
 
+# Dependencies
+
+/vendor/
+/vendor-bin/*/vendor
+/node_modules
+/yarn.lock
+/yarn-error.log
+
 
 # Windows files
 
@@ -26,7 +36,6 @@ $RECYCLE.BIN/
 .DS_Store
 .AppleDouble
 .LSOverride
-Icon
 ._*
 .Spotlight-V100
 .Trashes
@@ -37,6 +46,7 @@ Icon
 *.zip
 *.7z
 *.tar.gz
+*.tar.xz
 *.tgz
 *.deb
 *.rpm

.php_cs.dist → .php-cs-fixer.dist.php

@@ -4,6 +4,7 @@
  * See LICENSE and AUTHORS files for details */
 
 declare(strict_types=1);
+
 namespace JKingWeb\Arsse;
 
 const BASE = __DIR__.DIRECTORY_SEPARATOR;
@@ -13,7 +14,10 @@ $paths = [
     BASE."arsse.php",
     BASE."RoboFile.php",
     BASE."lib",
-    BASE."tests",
+    BASE."tests/cases",
+    BASE."tests/lib",
+    BASE."tests/bootstrap.php",
+    BASE."tests/server.php",
 ];
 $rules = [
     // house rules where PSR series is silent
@@ -35,6 +39,7 @@ $rules = [
     'no_blank_lines_after_phpdoc'               => true,
     'no_empty_comment'                          => true,
     'no_empty_phpdoc'                           => true,
+    'no_empty_statement'                        => true,
     'no_extra_blank_lines'                      => true, // this could probably use more configuration
     'no_mixed_echo_print'                       => ['use' => "echo"],
     'no_short_bool_cast'                        => true,
@@ -48,28 +53,16 @@ $rules = [
     'pow_to_exponentiation'                     => true,
     'set_type_to_cast'                          => true,
     'standardize_not_equals'                    => true,
-    'trailing_comma_in_multiline_array'         => true,
+    'trailing_comma_in_multiline'               => ['elements' => ["arrays"]],
     'unary_operator_spaces'                     => true,
     'yoda_style'                                => false,
     // PSR standard to apply
-    '@PSR2' => true,
-    // PSR-12 rules; php-cs-fixer does not yet support PSR-12 natively
-    'compact_nullable_typehint'                 => true,
-    'declare_equal_normalize'                   => ['space' => "none"],
-    'function_typehint_space'                   => true,
-    'lowercase_cast'                            => true,
-    'lowercase_static_reference'                => true,
-    'no_alternative_syntax'                     => true,
-    'no_empty_statement'                        => true,
-    'no_leading_import_slash'                   => true,
-    'no_leading_namespace_whitespace'           => true,
-    'no_whitespace_in_blank_line'               => true,
-    'return_type_declaration'                   => ['space_before' => "none"],
-    'single_trait_insert_per_statement'         => true,
-    'short_scalar_cast'                         => true,
-    'visibility_required'                       => ['elements' => ["const", "property", "method"]],
+    '@PSR12' => true,
     // house exceptions to PSR rules
-    'braces'                                    => ['position_after_functions_and_oop_constructs' => "same"],
+    'curly_braces_position'                     => [
+        'functions_opening_brace' => "same_line",
+        'classes_opening_brace'   => "same_line",
+    ],
     'function_declaration'                      => ['closure_function_spacing' => "none"],
     'new_with_braces'                           => false, // no option to specify absence of braces
     ];
@@ -82,4 +75,4 @@ foreach ($paths as $path) {
         $finder = $finder->in($path);
     }
 }
-return \PhpCsFixer\Config::create()->setRiskyAllowed(true)->setRules($rules)->setFinder($finder);
+return (new \PhpCsFixer\Config)->setRiskyAllowed(true)->setRules($rules)->setFinder($finder);

CHANGELOG

@@ -1,9 +1,100 @@
+Version 0.??.? (????-??-??)
+===========================
+
+Changes:
+- Require PHP 7.3
+
+Version 0.10.4 (2023-01-24)
+===========================
+
+Changes:
+- Support PHP 8.2
+
+Version 0.10.3 (2022-09-14)
+===========================
+
+Bug fixes:
+- Return all removed articles when multiple statuses are requested in Miniflux
+- Allow multiple date ranges in search strings in Tiny Tiny RSS
+- Honour user time zone when interpreting search strings in Tiny Tiny RSS
+- Perform MySQL table maintenance more reliably
+- Address CVE-2022-31090, CVE-2022-31091, CVE-2022-29248, and CVE-2022-31109
+
+Version 0.10.2 (2022-04-04)
+===========================
+
+Changes:
+- Update Guzzle PSR-7 due to CVE-2022-24775
+
+Version 0.10.1 (2022-01-17)
+===========================
+
+Changes:
+- Support PHP 8.1
+
+Version 0.10.0 (2021-07-11)
+===========================
+
+New features:
+- Complete Unix manual page
+- Support for running service as a forking daemon
+- Respond to TERM and HUP signals when possible
+
+Changes:
+- Packages for Debian and related are now available (see manual for details)
+
+Version 0.9.2 (2021-05-25)
+==========================
+
+Bug fixes:
+- Do not fail adding users to an empty database (regression since 0.9.0)
+- Cleanly ignore unknown configuration properties
+- Set access mode to rw-r---- when creating SQLite databases
+
+Changes:
+- Packages for Arch Linux are now available (see manual for details)
+- Numerous improvements to the manual
+
+Version 0.9.1 (2021-03-18)
+==========================
+
+Bug fixes:
+- Respond to PUT requests with 201 rather than 200 in Miniflux
+
+Changes:
+- Correct Web server configuration in manual
+
+Version 0.9.0 (2021-03-06)
+==========================
+
+New features:
+- Support for the Miniflux protocol (see manual for details)
+- Support for API level 15 of Tiny Tiny RSS
+- Support for feed icons in Fever
+- Command-line functionality for managing user metadata
+- Command-line functionality for managing Miniflux login tokens
+
+Bug fixes:
+- Further relax Fever HTTP correctness, to fix more clients
+- Use icons specified in Atom feeds when available
+- Do not return null as subscription unread count
+- Explicitly forbid U+003A COLON and control characters in usernames, for 
+  compatibility with RFC 7617
+- Never return 401 in response to an OPTIONS request
+- Accept "t" and "f" as booleans in Tiny Tiny RSS
+
+Changes:
+- Administrator account requirements for Nextcloud News functionality are
+  now enforced
+- E_DEPRECATED is now suppressed for compatibility with PHP 8 until affected
+  dependencies can be replaced
+
 Version 0.8.5 (2020-10-27)
 ==========================
 
 Bug fixes:
 - Relax Fever HTTP correctness, to fix some clients
-- Added the QUERY_STRING FastCGI paramater to the sample Nginx configuration
+- Add the QUERY_STRING FastCGI parameter to the sample Nginx configuration
 
 Version 0.8.4 (2020-09-09)
 ==========================
@@ -84,7 +175,7 @@ Bug fixes:
 Version 0.6.1 (2019-01-23)
 ==========================
 
-Bug Fixes:
+Bug fixes:
 - Unify SQL timeout settings
 - Correctly escape shell command in subprocess service driver
 - Correctly allow null time intervals in configuration when appropriate
@@ -204,4 +295,5 @@ Bug fixes:
 Version 0.1.0 (2017-08-29)
 ==========================
 
-Initial release
+New features:
+- Initial release

README.md

@@ -8,7 +8,7 @@ Information on how to install and use the software can be found in [the manual](
 
 The main repository for The Arsse can be found at [code.mensbeam.com](https://code.mensbeam.com/MensBeam/arsse/), with a mirror also available [at GitHub](https://github.com/mensbeam/arsse/). The GitHub mirror does not accept bug reports, but the two should otherwise be equivalent.
 
-[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install --no-dev` is recommended.
+[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install -o --no-dev --no-scripts` is recommended.
 
 # Repository structure
 
@@ -34,13 +34,15 @@ Also necessary to the functioning of the application is the `/vendor/` directory
 
 The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server.
 
-The `/dist/` directory, on the other hand, contains samples of configuration for Web servers and init systems. These are not used by The Arsse itself, but are merely distributed with it for reference.
+The `/dist/` directory, on the other hand, contains general and system-specific build files, and samples of configuration for Web servers and other system integration. These are not used by The Arsse itself, but are used during the process of preparing new releases for supported operating systems.
 
 ## Documentation
 
 The source text for The Arsse's manual can be found in `/docs/`, with pages written in [Markdown](https://spec.commonmark.org/current/) and converted to HTML [with Daux](#building-the-manual). If a static manual is generated its files will appear under `/manual/`.
 
-In addition to the manual the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
+The Arsse also has a UNIX manual page, also written in Markdown, which can be found under `/manpages/`. [Pandoc](https://pandoc.org/) is needed to convert it to the appropriate format, with the results stored under `/dist/man/`.
+
+In addition to the manuals the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
 
 ## Tests
 
@@ -50,7 +52,7 @@ The `/tests/` directory contains everything related to automated testing. It is
 |--------------------|------------------------------------------------------------------------------------|
 | `cases/`           | The test cases themselves, organized in roughly the same structure as the code     |
 | `coverage/`        | (optional) Generated code coverage reports                                         |
-| `docroot/`         | Sample documents used in some tests, to be returned by the PHP's basic HTTP server |
+| `docroot/`         | Sample documents used in some tests, to be returned by PHP's basic HTTP server |
 | `lib/`             | Supporting classes which do not contain test cases                                 |
 | `bootstrap.php`    | Bootstrap script, equivalent to `/arsse.php`, but for tests                        |
 | `phpunit.dist.xml` | PHPUnit configuration file                                                         |
@@ -74,7 +76,7 @@ The `/vendor-bin/` directory houses the files needed for the tools used in The A
 | `/robo`           | Simple wrapper for executing Robo on POSIX systems       |
 | `/robo.bat`       | Simple wrapper for executing Robo on Windows             |
 
-In addition the files `/package.json`, `/yarn.lock`, and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
+In addition the files `/package.json` and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
 
 # Common tasks
 
@@ -105,15 +107,18 @@ The Arsse's user manual, made using [Daux](https://daux.io/), can be compiled by
 
 The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running `./robo manual:theme`. This requires that [NodeJS](https://nodejs.org) and [Yarn](https://yarnpkg.com/) be installed, but JavaScript tools are not required to modify The Arsse itself, nor the content of the manual.
 
+## Building the man page
+
+The Arsse's UNIX manual page is authored in Markdown, and must be converted to the native roff format using [Pandoc](https://pandoc.org/). This can be done by running `./robo manpage`, which will output appropriate files to `/dist/man/`. The conversion should not be done manually as there is post-processing required for optimal output.
+
 ## Packaging a release
 
-Producing a release package is done by running `./robo package`. This performs the following operations:
+Producing release packages is done by running `./robo package`. This performs the following operations:
 
-- Duplicates a working tree with the commit (usually a release tag) to package
-- Generates the manual
+- Duplicates a [Git](https://git-scm.com/) working tree with the commit (usually a release tag) to package
+- Generates UNIX manual pages with [Pandoc](https://pandoc.org/)
+- Generates the HTML manual
 - Installs runtime Composer dependencies with an optimized autoloader
 - Deletes numerous unneeded files
 - Exports the default configuration of The Arsse to a file
 - Compresses the remaining files into a tarball
-
-Due to the first step, [Git](https://git-scm.com/) is required to package a release.

RoboFile.php

@@ -6,6 +6,8 @@ const BASE = __DIR__.\DIRECTORY_SEPARATOR;
 const BASE_TEST = BASE."tests".\DIRECTORY_SEPARATOR;
 define("IS_WIN", defined("PHP_WINDOWS_VERSION_MAJOR"));
 define("IS_MAC", php_uname("s") === "Darwin");
+define("IS_LINUX", !IS_WIN && !IS_MAC);
+error_reporting(0);
 
 function norm(string $path): string {
     $out = realpath($path);
@@ -53,8 +55,8 @@ class RoboFile extends \Robo\Tasks {
      * tests/coverage/. Additional reports may be produced by passing
      * arguments to this task as one would to PHPUnit.
      *
-     * Robo first tries to use pcov and will fall back first to xdebug then
-     * phpdbg. Neither pcov nor xdebug need to be enabled to be used; they
+     * Robo first tries to use pcov and will fall back to xdebug.
+     * Neither pcov nor xdebug need to be enabled to be used; they
      * only need to be present in the extension load path to be used.
      */
     public function coverage(array $args): Result {
@@ -78,9 +80,9 @@ class RoboFile extends \Robo\Tasks {
         return $this->runTests($exec, "typical", array_merge(["--coverage-html", BASE_TEST."coverage"], $args));
     }
 
-    /** Runs the coding standards fixer */
+    /** Runs the coding-style fixer */
     public function clean($opts = ['demo|d' => false]): Result {
-        $t = $this->taskExec(norm(BASE."vendor/bin/php-cs-fixer"));
+        $t = $this->taskExec(norm(BASE."vendor-bin/csfixer/vendor/bin/php-cs-fixer"));
         $t->arg("fix");
         if ($opts['demo']) {
             $t->args("--dry-run", "--diff")->option("--diff-format", "udiff");
@@ -88,39 +90,42 @@ class RoboFile extends \Robo\Tasks {
         return $t->run();
     }
 
+    /** Finds the first suitable means of computing code coverage, either pcov or xdebug. */
     protected function findCoverageEngine(): string {
         $dir = rtrim(ini_get("extension_dir"), "/").\DIRECTORY_SEPARATOR;
-        $ext = IS_WIN ? "dll" : (IS_MAC ? "dylib" : "so");
+        $ext = IS_WIN ? "dll" : "so";
         $php = escapeshellarg(\PHP_BINARY);
         $code = escapeshellarg(BASE."lib");
         if (extension_loaded("pcov")) {
             return "$php -d pcov.enabled=1 -d pcov.directory=$code";
         } elseif (extension_loaded("xdebug")) {
-            return $php;
+            return "$php -d xdebug.mode=coverage";
         } elseif (file_exists($dir."pcov.$ext")) {
             return "$php -d extension=pcov.$ext -d pcov.enabled=1 -d pcov.directory=$code";
-        } elseif (file_exists($dir."pcov.$ext")) {
-            return "$php -d zend_extension=xdebug.$ext";
+        } elseif (file_exists($dir."xdebug.$ext")) {
+            return "$php -d zend_extension=xdebug.$ext -d xdebug.mode=coverage";
         } else {
-            if (IS_WIN) {
-                $dbg = dirname(\PHP_BINARY)."\\phpdbg.exe";
-                $dbg = file_exists($dbg) ? $dbg : "";
-            } else {
-                $dbg = trim(`which phpdbg 2>/dev/null`);
-            }
-            if ($dbg) {
-                return escapeshellarg($dbg)." -qrr";
-            } else {
-                return $php;
-            }
+            return $php;
         }
     }
 
+    /** Returns the necessary shell arguments to print error output or all output to the bitbucket
+     *
+     * @param bool $all Whether all output (true) or only error output (false) should be suppressed
+     */
     protected function blackhole(bool $all = false): string {
         $hole = IS_WIN ? "nul" : "/dev/null";
         return $all ? ">$hole 2>&1" : "2>$hole";
     }
 
+    /** Executes PHPUnit, used by the test and coverage tasks.
+     *
+     * This also executes the built-in PHP Web server, which is required to fetch some newsfeeds during tests
+     *
+     * @param string $executor The path to the PHP binary to execute with any required extra arguments. Normally this is either "php" or the result of findCoverageEngine()
+     * @param string $set The set of tests to run, either "typical" (excludes redundant tests), "quick" (excludes redundant and slow tests), "coverage" (excludes tests not needed for coverage), or "full" (all tests)
+     * @param array $args Extra arguments passed by Robo from the command line
+     */
     protected function runTests(string $executor, string $set, array $args): Result {
         switch ($set) {
             case "typical":
@@ -144,71 +149,270 @@ class RoboFile extends \Robo\Tasks {
         return $this->taskExec($executor)->option("-d", "zend.assertions=1")->arg($execpath)->option("-c", $confpath)->args(array_merge($set, $args))->run();
     }
 
+    /** Returns a Git version string for a given Git tree-ish ID
+     *
+     * Returns an array containing the tree-ish string and the version string.
+     *
+     * @param string|null $commit The tree-ish ID. If not supplied the user will be prompted
+     */
+    protected function commitVersion(?string $commit): array {
+        $target = $commit ?? $this->askDefault("Reference commit:", "HEAD");
+        $base = escapeshellarg(BASE);
+        $blackhole = $this->blackhole();
+        // get useable version strings from Git
+        $version = trim(`git -C $base describe --tags $target $blackhole`);
+        if (!$version) {
+            throw new \Exception("Commit reference invalid");
+        }
+        return [$target, $version];
+    }
+
+    /** Checks whether all the supplied terminal commands are available in path */
+    protected function toolExists(string ...$binary): bool {
+        $blackhole = $this->blackhole(IS_WIN);
+        foreach ($binary as $bin) {
+            if (!exec(escapeshellarg($bin)." --help $blackhole", $junk, $status) || $status) {
+                return false;
+            }
+        }
+        return true;
+    }
+
     /** Packages a given commit of the software into a release tarball
      *
-     * The version to package may be any Git tree-ish identifier: a tag, a branch,
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
      * or any commit hash. If none is provided on the command line, Robo will prompt
-     * for a commit to package; the default is "head".
+     * for a commit to package; the default is "HEAD".
      *
      * Note that while it is possible to re-package old versions, the resultant tarball
      * may not be equivalent due to subsequent changes in the exclude list, or because
      * of new tooling.
      */
-    public function package(string $version = null): Result {
+    public function packageGeneric(string $commit = null): Result {
+        if (!$this->toolExists("git", "pandoc")) {
+            throw new \Exception("Git and Pandoc are required in PATH to produce generic release tarballs");
+        }
         // establish which commit to package
-        $version = $version ?? $this->askDefault("Commit to package:", "HEAD");
-        $archive = BASE."arsse-$version.tar.gz";
+        [$commit, $version] = $this->commitVersion($commit);
+        preg_match('/^([^-]+)(?:-(\d+)-(\w+))?$/', $version, $m);
+        $archVersion = $m[1].($m[2] ? ".r$m[2].$m[3]" : "");
+        $baseVersion = $m[1];
+        $release = $m[2];
+        // name the generic release tarball
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
         // start a collection
         $t = $this->collectionBuilder();
         // create a temporary directory
         $dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
         // create a Git worktree for the selected commit in the temp location
-        $t->taskExec("git worktree add ".escapeshellarg($dir)." ".escapeshellarg($version));
-        // perform Composer installation in the temp location with dev dependencies
-        $t->taskComposerInstall()->dir($dir);
-        // generate the manual
-        $t->taskExec(escapeshellarg($dir."robo")." manual")->dir($dir);
-        // perform Composer installation in the temp location for final output
-        $t->taskComposerInstall()->dir($dir)->noDev()->optimizeAutoloader()->arg("--no-scripts");
-        // delete unwanted files
-        $t->taskFilesystemStack()->remove([
-            $dir.".git",
-            $dir.".gitignore",
-            $dir.".gitattributes",
-            $dir."composer.json",
-            $dir."composer.lock",
-            $dir.".php_cs.dist",
-            $dir."phpdoc.dist.xml",
-            $dir."build.xml",
-            $dir."RoboFile.php",
-            $dir."CONTRIBUTING.md",
-            $dir."docs",
-            $dir."tests",
-            $dir."vendor-bin",
-            $dir."vendor/bin",
-            $dir."robo",
-            $dir."robo.bat",
-            $dir."package.json",
-            $dir."yarn.lock",
-            $dir."postcss.config.js",
-        ]);
-        // generate a sample configuration file
-        $t->taskExec(escapeshellarg(\PHP_BINARY)." arsse.php conf save-defaults config.defaults.php")->dir($dir);
-        // package it all up
-        $t->taskPack($archive)->addDir("arsse", $dir);
-        // execute the collection
-        $out = $t->run();
-        // clean the Git worktree list
-        $this->_exec("git worktree prune");
-        return $out;
+        $result = $this->taskExec("git worktree add ".escapeshellarg($dir)." ".escapeshellarg($version))->dir(BASE)->run();
+        if ($result->getExitCode() > 0) {
+            return $result;
+        }
+        try {
+            // Perform Arch-specific tasks
+            if (file_exists($dir."dist/arch")) {
+                // patch the Arch PKGBUILD file with the correct version string
+                $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^pkgver=.*$/m')->to("pkgver=$archVersion"));
+                // patch the Arch PKGBUILD file with the correct source file
+                $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^source=\("arsse-[^"]+"\)$/m')->to('source=("'.basename($tarball).'")'));
+            }
+            // perform Debian-specific tasks
+            if (file_exists($dir."dist/debian")) {
+                // generate the Debian changelog; this also validates our original changelog
+                $changelog = $this->changelogParse(file_get_contents($dir."CHANGELOG"), $version);
+                $debianChangelog = $this->changelogDebian($changelog, $version);
+                // save the Debian-format changelog
+                $t->addTask($this->taskWriteToFile($dir."dist/debian/changelog")->text($debianChangelog));
+            }
+            // perform RPM-specific tasks
+            if (file_exists($dir."dist/rpm")) {
+                // patch the spec file with the correct version and release
+                $t->addTask($this->taskReplaceInFile($dir."dist/rpm/arsse.spec")->regex('/^Version:        .*$/m')->to("Version:        $baseVersion"));
+                $t->addTask($this->taskReplaceInFile($dir."dist/rpm/arsse.spec")->regex('/^Release:        .*$/m')->to("Release:        $release"));
+                // patch the spec file with the correct tarball name
+                $t->addTask($this->taskReplaceInFile($dir."dist/rpm/arsse.spec")->regex('/^Source0:        .*$/m')->to("Source0:        arsse-$version.tar.gz"));
+                // append the RPM changelog to the spec file
+                $t->addTask($this->taskWriteToFile($dir."dist/rpm/arsse.spec")->append(true)->text("\n\n%changelog\n".$this->changelogRPM($changelog, $version)));
+            }
+            // save commit description to VERSION file for reference
+            $t->addTask($this->taskWriteToFile($dir."VERSION")->text($version));
+            if (file_exists($dir."docs") || file_exists($dir."manpages")) {
+                // perform Composer installation in the temp location with dev dependencies to include Robo and Daux
+                $t->addTask($this->taskExec("composer install")->arg("-q")->dir($dir));
+            }
+            if (file_exists($dir."manpages")) {
+                // generate manpages
+                $t->addTask($this->taskExec("./robo manpage")->dir($dir));
+            }
+            if (file_exists($dir."docs")) {
+                // generate the HTML manual
+                $t->addTask($this->taskExec("./robo manual -q")->dir($dir));
+            }
+            // perform Composer installation in the temp location for final output
+            $t->addTask($this->taskExec("composer install")->dir($dir)->arg("--no-dev")->arg("-o")->arg("--no-scripts")->arg("-q"));
+            // delete unwanted files
+            $t->addTask($this->taskFilesystemStack()->remove([
+                $dir.".git",
+                $dir.".gitignore",
+                $dir.".gitattributes",
+                $dir."dist/debian/.gitignore",
+                $dir."composer.json",
+                $dir."composer.lock",
+                $dir.".php_cs.dist",
+                $dir."phpdoc.dist.xml",
+                $dir."build.xml",
+                $dir."RoboFile.php",
+                $dir."CONTRIBUTING.md",
+                $dir."docs",
+                $dir."manpages",
+                $dir."tests",
+                $dir."vendor-bin",
+                $dir."vendor/bin",
+                $dir."robo",
+                $dir."robo.bat",
+                $dir."package.json",
+                $dir."yarn.lock",
+                $dir."postcss.config.js",
+            ]));
+            $t->addCode(function() use ($dir) {
+                // Remove files which lintian complains about; they're otherwise harmless
+                $files = [];
+                foreach (new \CallbackFilterIterator(new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($dir."vendor", \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS)), function($v, $k, $i) {
+                    return preg_match('/\/\.git(?:ignore|attributes|modules)$/D', $v);
+                }) as $f) {
+                    $files[] = $f;
+                }
+                return $this->taskFilesystemStack()->remove($files)->run();
+            });
+            // generate a sample configuration file
+            $t->addTask($this->taskExec(escapeshellarg(\PHP_BINARY)." arsse.php conf save-defaults config.defaults.php")->dir($dir));
+            // remove any existing archive
+            $t->addTask($this->taskFilesystemStack()->remove($tarball));
+            // package it all up
+            $t->addTask($this->taskFilesystemStack()->mkdir(dirname($tarball)));
+            $t->addTask($this->taskPack($tarball)->addDir("arsse", $dir));
+            // execute the collection
+            $result = $t->run();
+        } finally {
+            // remove the Git worktree
+            $this->taskFilesystemStack()->remove($dir)->run();
+            $this->taskExec("git worktree prune")->dir(BASE)->run();
+        }
+        return $result;
+    }
+
+    /** Packages a release tarball into a Debian source package
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     */
+    public function packageDebsrc(string $commit = null): Result {
+        // establish which commit to package
+        [$commit, $version] = $this->commitVersion($commit);
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
+        // determine the base version (i.e. x.y.z) and the Debian version (i.e. x.y.z-a)
+        preg_match('/^(\d+(?:\.\d+)+)(?:-(\d+))?/', $version, $m);
+        $baseVersion = $m[1];
+        $debVersion = $m[1]."-".($version === $baseVersion ? "1" : $m[2]);
+        // start a task collection and create a temporary directory
+        $t = $this->collectionBuilder();
+        $dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
+        // build the generic release tarball if it doesn't exist
+        if (!file_exists($tarball)) {
+            $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        }
+        $base = $dir."arsse-$version".\DIRECTORY_SEPARATOR;
+        // start by extracting the tarball
+        $t->addCode(function() use ($tarball, $dir, $base) {
+            // Robo's extract task is broken, so we do it manually
+            (new \Archive_Tar($tarball))->extract($dir, false);
+            return $this->taskFilesystemStack()->rename($dir."arsse", $base)->run();
+        });
+        // re-pack the tarball using a specific name special to Debian
+        $t->addTask($this->taskPack($dir."arsse_$baseVersion.orig.tar.gz")->addDir("arsse-$baseVersion", $base));
+        // pack the debian tarball
+        $t->addTask($this->taskPack($dir."arsse_$debVersion.debian.tar.gz")->addDir("debian", $base."dist/debian"));
+        // generate the DSC file
+        $t->addCode(function() use ($t, $debVersion, $baseVersion, $dir, $base) {
+            try {
+                $dsc = $this->generateDebianSourceControl($base."dist/debian/", $debVersion, [$dir."arsse_$baseVersion.orig.tar.gz", $dir."arsse_$debVersion.debian.tar.gz"]);
+            } catch (\Exception $e) {
+                return new Result($t, 1, $e->getMessage());
+            }
+            // write the DSC file
+            return $this->taskWriteToFile($dir."arsse_$debVersion.dsc")->text($dsc)->run();
+        });
+        // delete any existing files
+        $t->AddTask($this->taskFilesystemStack()->remove([BASE."release/$version/arsse_$baseVersion.orig.tar.gz", BASE."release/$version/arsse_$debVersion.debian.tar.gz", BASE."release/$version/arsse_$debVersion.dsc"]));
+        // copy the new files over
+        $t->addTask($this->taskFilesystemStack()->copy($dir."arsse_$baseVersion.orig.tar.gz", BASE."release/$version/arsse_$baseVersion.orig.tar.gz")->copy($dir."arsse_$debVersion.debian.tar.gz", BASE."release/$version/arsse_$debVersion.debian.tar.gz")->copy($dir."arsse_$debVersion.dsc", BASE."release/$version/arsse_$debVersion.dsc"));
+        return $t->run();
+    }
+
+    /** Packages a given commit of the software and produces all relevant release files
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     *
+     * In addition to the release tarball, a Debian source package, Arch PKGBUILD,
+     * and RPM spec file are output as well. These are suitable for use with Open
+     * Build Service instances and with slight modification the Arch User Repository.
+     * Use for Launchpad PPAs has not been tested.
+     */
+    public function package(string $commit = null): Result {
+        if (!$this->toolExists("git")) {