WIP: Deb upload, todos, and errata

The "repository" field doesn't have a type right now, so I'm going to
skip deserializing it. The returned JSON has a value for this field, but
Serde will ignore it.

The `Packages.pkg_type` field is called "type" in the JSON string (and
Go code, as mentioned in the comment). Similarly, the PackageType enum
I have to represent this field in Rust has capital starting letters
where the JSON uses all lowercase. Both problems are solved with a Serde
rename attribute.

Cargo.toml

@@ -1,16 +1,16 @@
 [package]
 name = "gt-tool"
-version = "3.0.0"
+version = "4.0.0-dev"
 edition = "2024"
 
 [dependencies]
-clap = { version = "4.0.7", features = ["derive", "env"] }
-colored = "2.0.0"
-itertools = "0.10.0"
-reqwest = { version = "0.11.13", features = ["json", "stream", "multipart"] }
-serde = { version = "1.0.152", features = ["derive"] }
-tokio = { version = "1.24.2", features = ["macros", "rt-multi-thread"] }
-toml = "0.5"
+clap = { version = "4.5.23", features = ["derive", "env"] }
+colored = "2.2.0"
+itertools = "0.13.0"
+reqwest = { version = "0.12.15", features = ["json", "stream", "multipart"] }
+serde = { version = "1.0.217", features = ["derive"] }
+tokio = { version = "1.43.1", features = ["macros", "rt-multi-thread"] }
+toml = "0.8.19"
 
 # Packages available in Debian (Sid)
 # clap = "4.5.23"

README.md

@@ -126,3 +126,11 @@ Similar to how unspecified project settings will fall back to those in the "`[al
 | token | Gitea auth token, exactly the same as `$RELEASE_KEY_GITEA` |
 
 Additional keys are quietly ignored. The config loading is done by querying a HashMap, so anything not touched doesn't get inspected. The only requirements are that the file is valid TOML, and that these keys are all strings.h
+
+# Errata
+
+- Gitea's package *uploading* API endpoints are not documented with Swagger.
+  * https://github.com/go-gitea/gitea/issues/30597
+  * It seems this is intentional because of which side defines the protocol (the consumer, not Gitea).
+  * This is an open issue (as of 12-Sep-2025) that doesn't have much attention.
+  * HTTP-POST (`curl`) is sufficient for upload. Use that either directly or as reference to make custom code.

debian/changelog

@@ -1,121 +0,0 @@
-gt-tool (3.0.0-1) unstable; urgency=medium
-
-  * Make the README title singular
-  * Add a Cargo.toml & Git tag version comparison
-  * Scaffold the new config module
-  * Add property-get utility function
-  * Add a get-table util function
-  * Util fn's can use anything that impl's ToString
-  * Util to get sometimes-empty config property
-  * Add partial- and whole- config structs
-  * Prototype load-config function
-  * Put the per-project test expects in for lconf()
-  * Finish `fn lconf()`. Project-specific vals load
-  * Create-and-assign struct to whole.all
-  * Use the get_table util to extract "[all]" table
-  * Extract PartCfg readers to a try_from impl
-  * Add a builder-pattern proj-path setter, for flavor
-  * Assert empty conf str is an error, TODO: semantics
-  * Rename the config-string-reading function
-  * Externalize the test table
-  * Remove some debug prints
-  * Signature & tests for fn load_from_file()
-  * Implement the load_from_file function
-  * "Merge" method on PartialConfig
-  * Complete the public `get_config()` function
-  * Pass in search files rather than generating them
-  * Make default search paths available as util fn
-  * Remove `WholeFile` struct & anything that uses it
-  * Autoformat
-  * Cargo clippy fixes
-  * Delete a now-solved FIXME comment
-  * Make the URL and Repo FQRN CLI args optional
-  * Wire in the conf file loading, assume PWD project
-  * Add more unit tests for the config loader
-  * Add test for skipping unavailable conf files
-  * Fix config unit tests: project path is set!
-  * Add docstring for PartialConfig::try_from()
-  * Fix: use empty PartialConfig if proj conf missing
-  * Fix: use default "[all]" if one isn't present
-  * Another autoformat
-  * Fix some clippy lints
-  * Mark pre-release 3.0.0-alpha.1
-  * Add a project path CLI option
-  * Update CLI usage guide, add project lookup guide
-  * Write configuration guide in the README
-  * Split the owner and repo args apart in CLI parser
-  * Use current-dir as final fallback repo name
-  * Drop notice about CLI not having "repo" & "owner"
-  * Revise help text for CLI "--project" arg
-  * Update usage printout
-  * Create a short, complete explanation of req. info.
-  * New 'authentication' section
-  * Delete the old CLI option sections
-  * Rename remaining CLI arg sections
-  * Revise explanation of `--project` option
-  * Drop the "no-repo" comment in TOML example
-  * Rephrase the all-projects setting introduction
-  * Mark the file-format and search-path conf sections
-  * Lint and format
-  * Bump crate version to v3.0.0
-  * Update automation workflow with new CLI args
-  * Add new upstream dependency to debian/control
-  * Rediff patches
-
- -- Robert Garrett <robertgarrett404@gmail.com>  Tue, 22 Jul 2025 09:54:28 -0500
-
-gt-tool (2.2.0-2) unstable; urgency=medium
-
-  * Fix: "Source:" URL in debian/copyright
-  * Fix typo in copyright comment
-
- -- Robert Garrett <robertgarrett404@gmail.com>  Sun, 13 Jul 2025 16:59:25 -0500
-
-gt-tool (2.2.0-1) unstable; urgency=medium
-
-  * Basic impl Display for the Release struct
-  * Print releases in reverse order for easier reading
-  * Colorize the output!
-  * Remove trailing newline in Release item printout
-  * Galaxy-brained newline intersperse function
-  * Change to free-fn intersperse for stdlib compat
-  * `Release.colorized()`, not std::fmt::Display
-  * Address most of the cargo-clippy lints
-  * Prefix unused variables to quiet the linter
-  * Autoformat
-  * Oops, missed one
-  * Bump to v2.2.0
-  * Lift the empty-body string outside the let-if
-  * Add the new dependencies to debian/control
-
- -- Robert Garrett <robertgarrett404@gmail.com>  Fri, 04 Jul 2025 10:10:54 -0500
-
-gt-tool (2.1.0-1) unstable; urgency=medium
-
-  * Fix: incorrect field names for `Attachment`
-
- -- Robert Garrett <robertgarrett404@gmail.com>  Thu, 12 Jun 2025 17:51:12 -0500
-
-gt-tool (2.0.0-1) unstable; urgency=medium
-
-  * Interrogate list_releases result more closely
-  * Interrogate create_release result more closely
-  * Drop unused imports
-  * "Fix" the test case
-  * Interrogate create_release_attachment result
-  * Fold client-error-decode into a util function
-  * Add `Attachment` struct, new iface for create-rel
-  * Update main.rs to use new attachment iface
-  * Delete the unit tests
-  * ... and the unit testing notes in README.md
-  * Drop unused import in api/release.rs
-  * Use pre Rust 1.81 compatible file-exists test
-  * Rediff patches
-
- -- Robert Garrett <robertgarrett404@gmail.com>  Thu, 12 Jun 2025 16:28:18 -0500
-
-gt-tool (1.0.0-1) unstable; urgency=low
-
-  * Experimental release.
-
- -- Robert Garrett <robertgarrett404@gmail.com>  Sun, 1 Jun 2025 16:05:00 -0500

debian/control

@@ -1,33 +0,0 @@
-Source: gt-tool
-Maintainer: Robert Garrett <robertgarrett404@gmail.com>
-Section: misc
-Priority: optional
-Standards-Version: 4.6.2
-Build-Depends:
- debhelper-compat (= 13),
- dh-cargo,
- librust-clap-dev,
- librust-colored-dev,
- librust-itertools-dev,
- librust-reqwest-dev,
- librust-serde-dev,
- librust-tokio-dev,
- librust-toml-dev,
-Homepage: https://git.gelvin.dev/robert/gt-tool
-Vcs-Git: https://git.gelvin.dev/robert/gt-tool
-Vcs-Browser: https://git.gelvin.dev/robert/gt-tool
-Rules-Requires-Root: no
-
-Package: gt-tool
-Architecture: any
-Depends:
- ${misc:Depends},
- ${shlibs:Depends},
-Description: CLI tools for interacting with the Gitea API.
- Use interactively to talk to your Gitea instance, or automatically via a CI/CD
- pipeline. Currently supports:
- .
-  - showing the Releases for a project
-  - creating a new Release for a project
-  - attaching files to a release
-

debian/copyright

@@ -1,43 +0,0 @@
-Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-Upstream-Name: gt-tools
-Upstream-Contact: Robert Garrett <robertgarrett404@gmail.com>
-Source: https://git.gelvin.dev/robert/gt-tool
-
-Files: *
-Copyright: 2025 Robert Garrett <robertgarrett404@gmail.com>
-License: GPL-3+
-
-Files: debian/*
-Copyright: 2025 Robert Garrett <robertgarrett404@gmail.com>
-License: GPL-3+
-
-Files: debian/rules
-Copyright:
- Johannes Schauer Marin Rodrigues <josch@debian.org>
- 2025 Robert Garrett <robertgarrett404@gmail.com>
-License: GPL-3+
-Comment:
- The debian/rules file is lifted directly from the tuigreet package. It was
- linked in the Debian Rust Team Book as a pretty simple example package. The
- only change I've made is to remove the documentation generation target.
- .
- https://salsa.debian.org/debian/tuigreet/-/blob/master/debian/rules?ref_type=heads
-
-
-License: GPL-3+
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
- .
- It is distributed in the hope that it will be useful, but WITHOUT
- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
- License for more details.
- .
- You should have received a copy of the GNU General Public License
- along with it.  If not, see <http://www.gnu.org/licenses/>.
- .
- On Debian systems, the full text of the GNU General Public License version 3
- can be found in the file /usr/share/common-licenses/GPL-3.
-

debian/gbp.conf

@@ -1,6 +0,0 @@
-[DEFAULT]
-compression = xz
-compression-level = 9
-upstream-tag = v%(version)s
-debian-branch = deb/bookworm
-

debian/patches/0001-Rust-edition-downgrade-to-2021.patch

@@ -1,23 +0,0 @@
-From: Robert Garrett <robertgarrett404@gmail.com>
-Date: Sun, 1 Jun 2025 17:59:20 -0500
-Subject: Rust edition downgrade to 2021
-
-Debian Bookworm uses Rust 1.63 which only supports up to the 2021
-edition.
----
- Cargo.toml | 2 +-
- 1 file changed, 1 insertion(+), 1 deletion(-)
-
-diff --git a/Cargo.toml b/Cargo.toml
-index 39341a1..4ec2031 100644
---- a/Cargo.toml
-+++ b/Cargo.toml
-@@ -1,7 +1,7 @@
- [package]
- name = "gt-tool"
- version = "3.0.0"
--edition = "2024"
-+edition = "2021"
- 
- [dependencies]
- clap = { version = "4.0.7", features = ["derive", "env"] }

debian/patches/0002-Lift-the-empty-body-string-outside-the-let-if.patch

@@ -1,39 +0,0 @@
-From: Robert Garrett <robertgarrett404@gmail.com>
-Date: Fri, 4 Jul 2025 09:36:52 -0500
-Subject: Lift the empty-body string outside the let-if
-
-The if-else block that selects between the body of the Release or a
-placeholder is returning references to variables that only exist
-*inside* the body of the if-else blocks. Newer Rust versions seem to
-understand the intent and do The Right Thing anyway (or they have some
-other rule for how if-else block scopes work).
-
-Manually lifting the variable to an outer scope resolves the problem.
----
- src/structs/release.rs | 7 +++++--
- 1 file changed, 5 insertions(+), 2 deletions(-)
-
-diff --git a/src/structs/release.rs b/src/structs/release.rs
-index 9ed537e..3c4a434 100644
---- a/src/structs/release.rs
-+++ b/src/structs/release.rs
-@@ -1,3 +1,5 @@
-+use std::io::empty;
-+
- use colored::Colorize;
- use serde::{Deserialize, Serialize};
- 
-@@ -27,10 +29,11 @@ impl Release {
-         let published = "Published:".bright_green();
-         let created = "Created:".green().dimmed();
-         let author = "Author:".blue();
-+        let empty_body = String::from("(empty body)").dimmed();
-         let body = if !self.body.is_empty() {
--            &self.body.white()
-+            self.body.white()
-         } else {
--            &String::from("(empty body)").dimmed()
-+            empty_body
-         };
- 
-         format!(

debian/patches/series

@@ -1,2 +0,0 @@
-0001-Rust-edition-downgrade-to-2021.patch
-0002-Lift-the-empty-body-string-outside-the-let-if.patch

debian/rules

@@ -1,26 +0,0 @@
-#!/usr/bin/make -f
-
-export DEB_BUILD_MAINT_OPTIONS = hardening=+all
-DPKG_EXPORT_BUILDFLAGS = 1
-include /usr/share/dpkg/default.mk
-include /usr/share/rustc/architecture.mk
-export DEB_HOST_RUST_TYPE
-export PATH:=/usr/share/cargo/bin:$(PATH)
-export CARGO=/usr/share/cargo/bin/cargo
-export CARGO_HOME=$(CURDIR)/debian/cargo_home
-export CARGO_REGISTRY=$(CURDIR)/debian/cargo_registry
-export DEB_CARGO_CRATE=$(DEB_SOURCE)_$(DEB_VERSION_UPSTREAM)
-
-%:
-	dh $@ --buildsystem=cargo
-
-execute_after_dh_auto_clean:
-	$(CARGO) clean
-	rm -rf $(CARGO_HOME)
-	rm -rf $(CARGO_REGISTRY)
-	rm -f debian/cargo-checksum.json
-
-execute_before_dh_auto_configure:
-	$(CARGO) prepare-debian $(CARGO_REGISTRY) --link-from-system
-	rm -f Cargo.lock
-	touch debian/cargo-checksum.json

debian/source/format

@@ -1 +0,0 @@
-3.0 (quilt)

src/api/packages.rs

@@ -1,4 +1,42 @@
-pub fn list_packages() {}
+use std::{fs, path::Path};
+
+use crate::structs::package::{Package, PackageType};
+
+/// Gets all packages of an owner
+///
+/// https://github.com/go-gitea/gitea/blob/main/routers/api/v1/packages/package.go#L22
+///
+/// Matches the route `GET /packages/{owner}`
+pub async fn list_packages(
+    client: &reqwest::Client,
+    gitea_url: &str,
+    owner: &str,
+    pkg_type: Option<PackageType>,
+) -> crate::Result<Vec<Package>> {
+    let request_url = format!("{gitea_url}/api/v1/packages/{owner}");
+    // add the query parameter only when a package type filter has been set.
+    let request_url = if let Some(pkg_type) = pkg_type {
+        let pkg_type = pkg_type.to_string();
+        format!("{request_url}?type={pkg_type}")
+    } else {
+        request_url
+    };
+    let req = client.get(request_url).send().await;
+    let response = req.map_err(crate::Error::WrappedReqwestErr)?;
+
+    if response.status().is_success() {
+        let release_list = response
+            .json::<Vec<Package>>()
+            .await
+            .map_err(crate::Error::WrappedReqwestErr)?;
+        return Ok(release_list);
+    } else if response.status().is_client_error() {
+        let mesg = crate::decode_client_error(response).await?;
+        return Err(crate::Error::ApiErrorMessage(mesg));
+    }
+    panic!("Reached the end of `api::list_packages()` without matching a return pathway.");
+}
+
 pub fn get_packages() {}
 pub fn delete_package() {}
 pub fn list_package_files() {}
@@ -6,3 +44,73 @@ pub fn get_latest_package_version() {}
 pub fn link_package() {}
 pub fn unlink_package() {}
 pub fn search_packages() {}
+
+
+/// Upload a Debian package and link it to it's source repository
+fn upload_debian(
+    client: &reqwest::Client,
+    gitea_url: &str,
+    repo: &str,
+    file: &Path,
+    owner: &str,
+    distribution: &str,
+    component: &str,
+) -> crate::Result<()> {
+    let request_url = format!("{gitea_url}/api/packages/{owner}/debian/pool/{distribution}/{component}/upload");
+    match file.try_exists() {
+        Ok(true) => (),
+        Ok(false) => return Err(crate::Error::NoSuchFile),
+        Err(e) => {
+            eprintln!("Uh oh! The file-exists check couldn't be done: {e}");
+            panic!(
+                "TODO: Deal with scenario where the file's existence cannot be checked (e.g.: no permission)"
+            );
+        }
+    };
+
+    let data = reqwest::multipart::Part::stream(fs::read(&file).unwrap())
+        .file_name("deb-pkg")
+        .mime_str("text/plain")?;
+
+    Ok(())
+}
+
+/// Uploads a package file to the Gitea registry.
+/// 
+/// This route is not documented in Swagger. The reason seems to be that some
+/// package managers have their own upload protocol (e.g. `docker push`). Gitea
+/// implements it but does not define it, so it doesn't include the API docs.
+pub fn upload_package(
+    client: &reqwest::Client,
+    gitea_url: &str,
+    file: String, // TODO: Use a path buffer of some flavor.
+) {
+    let request_url = format!("{gitea_url}/{}", route_for_upload(PackageType::Debian));
+}
+
+fn route_for_upload(kind: PackageType) -> &'static str {
+    match kind {
+        PackageType::Alpine => "https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}",
+        PackageType::Arch => "api/packages/{owner}/arch/{repository}",
+        PackageType::Cargo => todo!(),
+        PackageType::Chef => todo!(),
+        PackageType::Composer => todo!(),
+        PackageType::Conan => todo!(),
+        PackageType::Conda => todo!(),
+        PackageType::Container => todo!(),
+        PackageType::Cran => todo!(),
+        PackageType::Debian => "https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload",
+        PackageType::Generic => todo!(),
+        PackageType::Go => todo!(),
+        PackageType::Helm => todo!(),
+        PackageType::Maven => todo!(),
+        PackageType::Npm => todo!(),
+        PackageType::Nuget => todo!(),
+        PackageType::Pub => todo!(),
+        PackageType::PyPi => todo!(),
+        PackageType::Rpm => todo!(),
+        PackageType::RubyGems => todo!(),
+        PackageType::Swift => todo!(),
+        PackageType::Vagrant => todo!(),
+    }
+}

src/cli.rs

@@ -44,4 +44,5 @@ pub enum Commands {
         #[arg()]
         files: Vec<String>,
     },
+    ListPackages,
 }

src/main.rs

@@ -134,6 +134,16 @@ async fn main() -> Result<(), gt_tool::Error> {
                 return Err(gt_tool::Error::NoSuchRelease);
             }
         }
+        gt_tool::cli::Commands::ListPackages => {
+            let packages = gt_tool::api::packages::list_packages(&client, &gitea_url, &owner, None).await?;
+            itertools::Itertools::intersperse(
+                packages
+                    .iter()
+                    .rev()
+                    .map(|pkg| pkg.colorized()),
+                String::from("")
+            ).for_each(|package| println!("{package}"));
+        }
     }
 
     Ok(())

src/structs/mod.rs

@@ -1,5 +1,6 @@
 use serde::{Deserialize, Serialize};
 
+pub mod package;
 pub mod release;
 pub mod repo;
 

src/structs/package.rs

@@ -0,0 +1,94 @@
+use colored::Colorize;
+use serde::{Deserialize, Serialize};
+
+use crate::structs::release::Author;
+
+/// Represents the package as described by JSON
+///
+/// https://github.com/go-gitea/gitea/blob/main/modules/structs/package.go
+#[derive(Debug, Deserialize, Serialize)]
+pub struct Package {
+    created_at: String,          // TODO: Datetime struct
+    creator: Author,
+    html_url: String,
+    id: u64,
+    name: String,
+    owner: Author,
+    #[serde(skip)]
+    repository: (),             // TODO: Create a `struct Repository`
+    #[serde(rename = "type")]   // field is "type" in JSON & Go, but that's a
+    pkg_type: PackageType,      // keyword in Rust so we need to serde-rename it.
+    version: String,
+}
+
+impl Package {
+    pub fn colorized(&self) -> String {
+        let name = "Name:".green().bold();
+        let version = &self.version;
+        let pkg_type = "Type:".green();
+
+        format!(
+            "{name} {} {version}
+{pkg_type} {}",
+            self.name,
+            self.version,
+        )
+    }
+}
+
+/// A marker for the kind of package being handled.
+#[derive(Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PackageType {
+    Alpine,
+    Arch,
+    Cargo,
+    Chef,
+    Composer,
+    Conan,
+    Conda,
+    Container,
+    Cran,
+    Debian,
+    Generic,
+    Go,
+    Helm,
+    Maven,
+    Npm,
+    Nuget,
+    Pub,
+    PyPi,
+    Rpm,
+    RubyGems,
+    Swift,
+    Vagrant,
+}
+
+impl ToString for PackageType {
+    fn to_string(&self) -> String {
+        match self {
+            PackageType::Alpine => "alpine".into(),
+            PackageType::Arch => "arch".into(),
+            PackageType::Cargo => "cargo".into(),
+            PackageType::Chef => "chef".into(),
+            PackageType::Composer => "composer".into(),
+            PackageType::Conan => "conan".into(),
+            PackageType::Conda => "conda".into(),
+            PackageType::Container => "container".into(),
+            PackageType::Cran => "cran".into(),
+            PackageType::Debian => "debian".into(),
+            PackageType::Generic => "generic".into(),
+            PackageType::Go => "go".into(),
+            PackageType::Helm => "helm".into(),
+            PackageType::Maven => "maven".into(),
+            PackageType::Npm => "npm".into(),
+            PackageType::Nuget => "nuget".into(),
+            PackageType::Pub => "pub".into(),
+            PackageType::PyPi => "pypi".into(),
+            PackageType::Rpm => "rpm".into(),
+            PackageType::RubyGems => "rubygems".into(),
+            PackageType::Swift => "swift".into(),
+            PackageType::Vagrant => "vagrant".into(),
+        }
+    }
+}

src/structs/release.rs

@@ -50,6 +50,7 @@ impl Release {
     }
 }
 
+// TODO: Rename to "User" to match Gitea's code
 #[derive(Debug, Deserialize, Serialize)]
 pub struct Author {
     id: usize,