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}