chore: establish phase 0 baseline

crates/kiln-cli/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "kiln-cli"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[[bin]]
+name = "kiln"
+path = "src/main.rs"
+
+[dependencies]
+kiln-core = { version = "=0.0.1", path = "../kiln-core" }
+
+[lints]
+workspace = true

crates/kiln-cli/src/main.rs

@@ -0,0 +1,36 @@
+//! Private smoke CLI for the Project Kiln workspace.
+
+use std::env;
+use std::process::ExitCode;
+
+use kiln_core::CONTRACT_SCHEMA_VERSION;
+
+const HELP: &str = "Project Kiln private scaffold\n\nUSAGE:\n    kiln <COMMAND>\n\nCOMMANDS:\n    version          Print the private build version\n    doctor [--json]  Check the scaffold contract\n    help             Print this help\n";
+
+fn main() -> ExitCode {
+    let mut arguments = env::args().skip(1);
+    match (arguments.next().as_deref(), arguments.next().as_deref()) {
+        (None | Some("help" | "--help" | "-h"), None) => {
+            print!("{HELP}");
+            ExitCode::SUCCESS
+        }
+        (Some("version" | "--version" | "-V"), None) => {
+            println!("kiln {} (private placeholder)", env!("CARGO_PKG_VERSION"));
+            ExitCode::SUCCESS
+        }
+        (Some("doctor"), None) => {
+            println!("ok: core contract schema {CONTRACT_SCHEMA_VERSION}");
+            ExitCode::SUCCESS
+        }
+        (Some("doctor"), Some("--json")) => {
+            println!(
+                "{{\"schema_version\":{CONTRACT_SCHEMA_VERSION},\"status\":\"ok\",\"private_placeholder\":true}}"
+            );
+            ExitCode::SUCCESS
+        }
+        _ => {
+            eprintln!("error: unsupported arguments\n\n{HELP}");
+            ExitCode::from(2)
+        }
+    }
+}

crates/kiln-core/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "kiln-core"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[lints]
+workspace = true
+

crates/kiln-core/src/lib.rs

@@ -0,0 +1,107 @@
+//! Shared, provider-independent contracts for Project Kiln.
+
+use std::fmt;
+use std::str::FromStr;
+
+/// Schema version emitted by the initial private machine-readable smoke path.
+pub const CONTRACT_SCHEMA_VERSION: u32 = 1;
+
+/// A store-qualified game identity such as `steam:620` or `native:supertuxkart`.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct GameId {
+    namespace: String,
+    value: String,
+}
+
+impl GameId {
+    /// Returns the provider/store namespace.
+    #[must_use]
+    pub fn namespace(&self) -> &str {
+        &self.namespace
+    }
+
+    /// Returns the provider-owned identity value.
+    #[must_use]
+    pub fn value(&self) -> &str {
+        &self.value
+    }
+}
+
+impl fmt::Display for GameId {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(formatter, "{}:{}", self.namespace, self.value)
+    }
+}
+
+/// Why a game identity could not be parsed.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum GameIdError {
+    /// The `namespace:value` separator is absent.
+    MissingSeparator,
+    /// The namespace is empty or contains unsupported characters.
+    InvalidNamespace,
+    /// The provider-owned value is empty or contains control characters.
+    InvalidValue,
+}
+
+impl fmt::Display for GameIdError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::MissingSeparator => "game ID must contain a ':' separator",
+            Self::InvalidNamespace => "game ID namespace must be lowercase ASCII",
+            Self::InvalidValue => {
+                "game ID value must be non-empty and contain no control characters"
+            }
+        };
+        formatter.write_str(message)
+    }
+}
+
+impl std::error::Error for GameIdError {}
+
+impl FromStr for GameId {
+    type Err = GameIdError;
+
+    fn from_str(raw: &str) -> Result<Self, Self::Err> {
+        let (namespace, value) = raw.split_once(':').ok_or(GameIdError::MissingSeparator)?;
+        if namespace.is_empty()
+            || !namespace
+                .bytes()
+                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+        {
+            return Err(GameIdError::InvalidNamespace);
+        }
+        if value.is_empty() || value.chars().any(char::is_control) {
+            return Err(GameIdError::InvalidValue);
+        }
+        Ok(Self {
+            namespace: namespace.to_owned(),
+            value: value.to_owned(),
+        })
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::{GameId, GameIdError};
+
+    #[test]
+    fn accepts_store_qualified_identity() {
+        let id: GameId = "steam:620".parse().expect("valid ID");
+        assert_eq!(id.namespace(), "steam");
+        assert_eq!(id.value(), "620");
+        assert_eq!(id.to_string(), "steam:620");
+    }
+
+    #[test]
+    fn rejects_unqualified_identity() {
+        assert_eq!("620".parse::<GameId>(), Err(GameIdError::MissingSeparator));
+    }
+
+    #[test]
+    fn rejects_shell_hostile_namespace() {
+        assert_eq!(
+            "steam;touch:620".parse::<GameId>(),
+            Err(GameIdError::InvalidNamespace)
+        );
+    }
+}