Add publish command by consideRatio · Pull Request #249 · sensmetry/sysand

consideRatio · 2026-04-01T13:05:57Z

for Index rework overview #210

Summary

Adds a new sysand publish command to upload .kpar packages to a Sysand-compatible index, including CLI wiring, core publish logic, docs, and test coverage.

What’s included

New CLI command: `sysand publish`

Usage: sysand publish [OPTIONS] [PATH]
If PATH is omitted, resolves to default build output for the current project.
New option:
- --index <URL> to explicitly select publish target index.

Publish target resolution

When --index is not provided, publish target is resolved in this order:

configured index with default = true
first configured index
built-in fallback https://beta.sysand.org

Core publish flow

Reads and validates project metadata from the .kpar:
- publisher present and canonicalizable
- name canonicalizable
- version valid SemVer 2.0
Builds normalized package identifier (pkg:sysand/<publisher>/<name>@<version>):
- lowercase normalization
- spaces normalized to -
- dots in name preserved
Uploads multipart form (purl + file) to /api/v1/upload.
Uses bearer-token authentication policy for publish requests (basic auth credentials are ignored for publish).
CLI now uses separate auth policies: basic-or-bearer for general commands and bearer-only for publish.
Fails early with a clear error if no matching bearer token credentials are configured for the publish URL.
Maps server responses into typed publish errors/success outcomes.

Docs and CLI help

Added sysand publish command docs.
Updated command summary navigation.
Updated help text and docs to reflect publish index resolution behavior.

Tests

Added/expanded publish integration tests in sysand/tests/cli_publish.rs:
- missing KPAR
- explicit missing KPAR
- network error
- basic auth credentials are ignored for publish
- explicit error when no matching bearer token credentials are configured
- invalid --index
- explicit path outside project dir
- metadata validation failures (publisher, name, version)
- canonicalized purl in upload payload
- default-index and configured-default-index selection behavior
Added unit tests for:
- publish index URL resolution logic
- upload URL construction behavior (path append, query/fragment normalization, invalid schemes)

Signed-off-by: Erik Sundell <erik.sundell@sensmetry.com>

andrius-puksta-sensmetry · 2026-04-02T05:14:01Z

Uploads multipart form (purl + file) to /api/v1/upload

Why not use something like Cargo publish protocol?

Reads and validates project metadata from the .kpar:

publisher present and canonicalizable

name canonicalizable

version valid SemVer 2.0

What about license? Should require it to be an SPDX expression.

andrius-puksta-sensmetry · 2026-04-02T05:25:41Z

sysand/src/cli.rs

+        /// configured default index URL, otherwise the first configured
+        /// index URL, or https://beta.sysand.org
+        #[arg(long, verbatim_doc_comment)]
+        index: Option<String>,


Suggested change

index: Option<String>,

index: Option<Url>,

andrius-puksta-sensmetry · 2026-04-02T05:26:57Z

sysand/src/cli.rs

        #[arg(long, short, default_value_t = false, verbatim_doc_comment)]
        allow_path_usage: bool,
    },
+    /// Publish a KPAR to the sysand package index


Suggested change

/// Publish a KPAR to the sysand package index

/// Publish a KPAR to a sysand package index

Any index, not necessarily "the" index (beta.sysand.org)

andrius-puksta-sensmetry · 2026-04-02T05:44:01Z

sysand/src/lib.rs

+    let basic_or_bearer_auth_policy = Arc::new(auths_builder.build()?);
+    let bearer_only_auth_policy = Arc::new(publish_auths_builder.build()?);


Let's avoid doing additional work for every command. Publish is very rare. Better add a conversion method from the former to the latter, and use that for the publish command.

andrius-puksta-sensmetry · 2026-04-02T06:02:55Z

Uploads multipart form (purl + file) to /api/v1/upload

Why not use something like Cargo publish protocol?

Alaternatively, why not be even simpler: pass the PURL in some header (e.g. X-Sysand-publish-PURL) and the KPAR as the application/zip body?

andrius-puksta-sensmetry · 2026-04-02T06:22:03Z

core/src/commands/publish.rs

+    MissingPublisher,
+
+    #[error(
+        "publisher field `{0}` is invalid for modern project IDs: must be 3-50 characters, use only letters and numbers, may include single spaces or hyphens between words, and must start and end with a letter or number"


Suggested change

"publisher field `{0}` is invalid for modern project IDs: must be 3-50 characters, use only letters and numbers, may include single spaces or hyphens between words, and must start and end with a letter or number"

"publisher field `{0}` is invalid for modern project IDs: must be 3-50 characters, use only ASCII letters and numbers, may include single spaces or hyphens between words, and must start and end with a letter or number"

andrius-puksta-sensmetry · 2026-04-02T06:23:29Z

core/src/commands/publish.rs

+    pub is_new_project: bool,
+}
+
+fn build_upload_url(index_url: &str) -> Result<Url, PublishError> {


Take a parsed URL.

andrius-puksta-sensmetry · 2026-04-02T06:25:50Z

core/src/commands/publish.rs

+                    url: index_url.into(),
+                    reason: "URL cannot be used as a hierarchical base URL".to_string(),
+                })?;
+        segments.pop_if_empty();


Require the URL to be HTTP(S), then unwrap() can be used here, and the errors will be better.

andrius-puksta-sensmetry · 2026-04-02T06:31:20Z

core/src/commands/publish.rs

+    // Keep publish endpoint path stable even if user provided query/fragment in base URL.
+    upload_url.set_query(None);
+    upload_url.set_fragment(None);


IMO it would be better to error out if query/fragment is present, instead of silently dropping them.

Or log::warn

andrius-puksta-sensmetry · 2026-04-02T06:33:37Z

core/src/commands/publish.rs

+    let version = &info.version;
+    if !is_canonicalizable_publisher_field_value(publisher) {
+        return Err(PublishError::NonCanonicalizablePublisher(
+            publisher.to_owned().into_boxed_str(),


Suggested change

publisher.to_owned().into_boxed_str(),

publisher.as_str().into_boxed_str(),

andrius-puksta-sensmetry · 2026-04-02T06:33:48Z

core/src/commands/publish.rs

+    }
+    if !is_canonicalizable_name_field_value(name) {
+        return Err(PublishError::NonCanonicalizableName(
+            name.to_owned().into_boxed_str(),


Suggested change

name.to_owned().into_boxed_str(),

name.as_str().into_boxed_str(),

andrius-puksta-sensmetry · 2026-04-02T06:34:06Z

core/src/commands/publish.rs

+        ));
+    }
+    semver::Version::parse(version).map_err(|source| PublishError::InvalidVersion {
+        version: version.to_owned().into_boxed_str(),


Suggested change

version: version.to_owned().into_boxed_str(),

version: version.as_str().into_boxed_str(),

andrius-puksta-sensmetry · 2026-04-02T06:37:01Z

core/src/commands/publish.rs

+    let request_builder = move |c: &reqwest_middleware::ClientWithMiddleware| {
+        let file_part = reqwest::multipart::Part::stream(file_bytes.clone())
+            .file_name(file_name.clone())
+            .mime_str("application/octet-stream")


Why not application/zip?

andrius-puksta-sensmetry · 2026-04-02T06:37:24Z

core/src/commands/publish.rs

+        let file_part = reqwest::multipart::Part::stream(file_bytes.clone())
+            .file_name(file_name.clone())
+            .mime_str("application/octet-stream")
+            .expect("valid mime type");


Suggested change

.expect("valid mime type");

.unwrap();

andrius-puksta-sensmetry · 2026-04-02T06:39:18Z

core/src/commands/publish.rs

+            .text("purl", purl.clone())
+            .part("file", file_part);
+
+        c.post(upload_url.as_str()).multipart(form)


Suggested change

c.post(upload_url.as_str()).multipart(form)

c.post(upload_url).multipart(form)

Oh, this won't work. Then clone the URL to avoid very expensive reparse.

andrius-puksta-sensmetry · 2026-04-02T06:41:30Z

core/src/commands/publish.rs

+pub fn do_publish_kpar<P: AsRef<Utf8Path>>(
+    kpar_path: P,
+    index_url: &str,
+    auth_policy: Arc<StandardHTTPAuthentication>,


We always use bearer auth and no registry will allow unauthenticated publishing, so use ForceBearerAuth.

andrius-puksta-sensmetry · 2026-04-02T06:43:47Z

core/src/commands/publish.rs

+
+pub fn do_publish_kpar<P: AsRef<Utf8Path>>(
+    kpar_path: P,
+    index_url: &str,


Take a URL.

core/src/commands/publish.rs

andrius-puksta-sensmetry · 2026-04-02T07:22:08Z

core/src/commands/publish.rs

+        let is_separator = b == b'-' || b == b' ' || (allow_dot && b == b'.');
+        if !is_separator {
+            return false;
+        }


This allows non-ASCII to pass through.

andrius-puksta-sensmetry · 2026-04-02T07:28:47Z

core/src/commands/publish.rs

+    })?;
+
+    let status = response.status().as_u16();
+    let body = runtime.block_on(response.text()).unwrap_or_default();


Don't eat errors.

andrius-puksta-sensmetry · 2026-04-02T07:31:12Z

core/src/commands/publish.rs

+
+    #[test]
+    fn publisher_field_canonicalizability() {
+        assert!(is_canonicalizable_publisher_field_value("Acme Labs"));


Add a case for dot in the middle.

Also a case for - (space and punctuation), and one or more cases of non-ASCII.

andrius-puksta-sensmetry · 2026-04-02T07:36:20Z

docs/src/commands/publish.md

@@ -0,0 +1,77 @@
+# `sysand publish`
+
+Publish a KPAR to the sysand package index.


Suggested change

Publish a KPAR to the sysand package index.

Publish a KPAR to a sysand package index.

andrius-puksta-sensmetry · 2026-04-02T07:38:25Z

docs/src/commands/publish.md

+
+- `version`: must be a valid Semantic Versioning 2.0 version.
+
+- `publisher`: 3-50 characters, letters and numbers only, with optional single


Suggested change

- `publisher`: 3-50 characters, letters and numbers only, with optional single

- `publisher`: 3-50 characters, ASCII letters and numbers only, with optional single

andrius-puksta-sensmetry · 2026-04-02T07:38:42Z

docs/src/commands/publish.md

+- `publisher`: 3-50 characters, letters and numbers only, with optional single
+  spaces or hyphens between words, and must start and end with a letter or
+  number.
+- `name`: 3-50 characters, letters and numbers only, with optional single


Suggested change

- `name`: 3-50 characters, letters and numbers only, with optional single

- `name`: 3-50 characters, ASCII letters and numbers only, with optional single

andrius-puksta-sensmetry · 2026-04-02T07:39:38Z

docs/src/commands/publish.md

+## Options
+
+- `--index <URL>`: URL of the package index to publish to. Defaults to the
+  configured default index URL, otherwise the first configured index URL, or


Link to index config

andrius-puksta-sensmetry · 2026-04-02T07:44:40Z