Skip to main content

metalcraft_packs/
lib.rs

1//! # metalcraft-packs
2//!
3//! The shared **spec / protocol** for Metalcraft integrations and agent packs —
4//! the pieces every part of the ecosystem must agree on, byte for byte:
5//!
6//! - [`IntegrationManifest`] — the `integration.json` shape.
7//! - [`canonical_sha256`] — the one true content digest of a file-map. The
8//!   registry computes it at publish time; the agent recomputes it on install to
9//!   verify integrity. These **must** agree, which is the whole reason this lives
10//!   in one crate rather than being copied into each repo.
11//! - [`is_valid_integration_id`] — the id/slug rule.
12//! - [`version_ge`] — semver "newer-or-equal", used for latest-pointer and
13//!   downgrade decisions.
14//!
15//! Everything else — what a valid agent pack is, how it installs, what a registry
16//! must serve — lives in `metalcraft-agent/specs/AGENT_PACK_FORMAT.md`. Rules that
17//! can be checked independently on each side belong in prose that reaches the
18//! TypeScript clients too; only the digest has to be shared as code, because a hash
19//! that disagrees is unrecoverable in a way a validation rule is not.
20//!
21//! This crate is pure: no I/O, no HTTP, no database. It is the integration
22//! equivalent of [`metalcraft-flows`](https://docs.rs/metalcraft-flows) (the
23//! flow-graph spec).
24
25#![deny(missing_docs)]
26#![cfg_attr(docsrs, feature(doc_cfg))]
27
28pub mod hash;
29pub mod manifest;
30pub mod version;
31
32pub use hash::{canonical_sha256, canonical_sha256_text};
33pub use manifest::{ecosystem_ids, is_ecosystem, IntegrationManifest, ECOSYSTEM_TAG};
34
35/// The pre-0.2 name for [`IntegrationManifest`].
36///
37/// An integration stopped being a unit of installation when agent packs became
38/// one, so "pack" was promising something the system no longer does — and it
39/// collided with "agent pack", which *is* installable. The type is the same;
40/// only the name was wrong.
41#[deprecated(since = "0.2.0", note = "renamed to IntegrationManifest")]
42pub type PackManifest = IntegrationManifest;
43
44pub use version::version_ge;
45
46/// Whether an integration id / slug is well-formed: `^[a-z0-9][a-z0-9_-]{0,63}$`.
47///
48/// Lowercase letters, digits, dashes, and underscores, 1–64 chars, and it must
49/// start with a letter or digit. Underscores are allowed because several
50/// first-party ids use them (`digitalocean_spaces`, `discord_admin`,
51/// `sprite_builder`).
52pub fn is_valid_integration_id(id: &str) -> bool {
53    if id.is_empty() || id.len() > 64 {
54        return false;
55    }
56    let mut chars = id.chars();
57    let first = chars.next().unwrap();
58    if !(first.is_ascii_lowercase() || first.is_ascii_digit()) {
59        return false;
60    }
61    id.chars()
62        .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-' || c == '_')
63}
64
65#[cfg(test)]
66mod tests {
67    use super::*;
68
69    #[test]
70    fn pack_id_rules() {
71        assert!(is_valid_integration_id("github"));
72        assert!(is_valid_integration_id("metalcraft-calendar"));
73        assert!(is_valid_integration_id("digitalocean_spaces"));
74        assert!(is_valid_integration_id("discord_admin"));
75        assert!(!is_valid_integration_id(""));
76        assert!(!is_valid_integration_id("-leading-dash"));
77        assert!(!is_valid_integration_id("_leading_underscore"));
78        assert!(!is_valid_integration_id("Capital"));
79        assert!(!is_valid_integration_id("has space"));
80        assert!(!is_valid_integration_id("../escape"));
81        assert!(!is_valid_integration_id(&"x".repeat(65)));
82    }
83}