@antprofuse/saddle-skill 0.1.1

package/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: saddle-service
+description: Build and review minimal Rust Service applications against the published Saddle facade package `saddle-framework = "=0.1.1"`. Use when Codex needs to create a Saddle 0.1.1 Service contract, handler, registration, HTTP/JSON exposure, fixed process entry, or verify generated business code without reading or changing Saddle middleware implementation.
+---
+
+# Saddle Service 0.1.1
+
+Use only the public API shipped by `saddle-framework = "=0.1.1"`.
+
+## Workflow
+
+1. Pin the facade exactly as `saddle-framework = "=0.1.1"`; import it as `saddle`.
+2. Read [references/service-0.1.1.md](references/service-0.1.1.md) before generating Service code.
+3. Start from the verified `examples/helloworld` consumer when working in the Saddle repository.
+4. Keep business code limited to request/response types, a Service contract, its handler, and Saddle assembly.
+5. Run both the Rust 1.85 and current-toolchain checks documented in [references/service-0.1.1.md](references/service-0.1.1.md) after changing the reference example.
+6. Reject APIs that are only described as V1 goals but are absent from the published facade.
+
+## Boundaries
+
+- Do not inspect or modify Saddle component implementation.
+- Do not replace Saddle's process entry, async runtime, HTTP server, database pool, or observability setup.
+- Do not create threads, runtimes, detached tasks, routers, I/O clients, or DB pools in business code.
+- Do not claim DB, transaction, internal Service call, graceful shutdown, or observability usage patterns without a compiling 0.1.1 consumer.
+- If a required public API is missing, preserve a minimal reproducible consumer failure and submit it through remote Git for the control workspace to assess. Do not patch middleware here.
+- Treat local design documents as intent and crates.io 0.1.1 compilation as the source of truth for usable API.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Saddle Service 0.1.1"
+  short_description: "Build verified Saddle 0.1.1 Service applications"
+  default_prompt: "Use $saddle-service to build a minimal Saddle Service application."

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@antprofuse/saddle-skill",
+  "version": "0.1.1",
+  "description": "AI Coding skill for building verified Saddle 0.1.1 Service applications.",
+  "license": "MIT OR Apache-2.0",
+  "files": [
+    "SKILL.md",
+    "agents",
+    "references"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/references/service-0.1.1.md

@@ -0,0 +1,163 @@
+# Saddle Service 0.1.1 contract
+
+## Dependency
+
+Use the published facade package at an exact version:
+
+```toml
+[package]
+edition = "2024"
+rust-version = "1.85"
+
+[dependencies]
+saddle-framework = "=0.1.1"
+serde = { version = "1", features = ["derive"] }
+```
+
+The Cargo package is `saddle-framework`; the Rust library name is `saddle`.
+
+## Correct minimal pattern
+
+Define one zero-sized contract type, serializable request/response types, and a separate handler:
+
+```rust
+use saddle::{
+    CallContext,
+    service::{Service, ServiceFuture, ServiceHandler},
+};
+use serde::{Deserialize, Serialize};
+
+struct Hello;
+
+#[derive(Deserialize)]
+struct HelloRequest {
+    name: String,
+}
+
+#[derive(Serialize)]
+struct HelloResponse {
+    message: String,
+}
+
+impl Service for Hello {
+    type Request = HelloRequest;
+    type Response = HelloResponse;
+}
+
+struct HelloHandler;
+
+impl ServiceHandler<Hello> for HelloHandler {
+    fn call<'a>(
+        &'a self,
+        _context: &'a CallContext,
+        request: HelloRequest,
+    ) -> ServiceFuture<'a, HelloResponse> {
+        Box::pin(async move {
+            Ok(HelloResponse {
+                message: format!("Hello, {}!", request.name),
+            })
+        })
+    }
+}
+```
+
+Register and expose it only through Saddle:
+
+```rust
+builder.register::<Hello, _>(
+    ServiceDescriptor::new("helloworld", "hello", "say_hello"),
+    HelloHandler,
+)?;
+builder.expose_json::<Hello>("/hello");
+```
+
+Use the fixed process entry:
+
+```rust
+let database_url = std::env::var("SADDLE_DATABASE_URL")
+    .expect("SADDLE_DATABASE_URL must be set by deployment configuration");
+let config = SaddleConfig::new("helloworld", database_url, listen);
+
+Saddle::run(config, |builder| {
+    // Register and expose Services here.
+    Ok(())
+})
+```
+
+See `examples/helloworld` for the complete compiling consumer.
+
+## Incorrect patterns
+
+Do not use an unpinned or compatible version range:
+
+```toml
+# Wrong: 0.1.x may change incompatibly.
+saddle-framework = "0.1"
+```
+
+Do not embed database credentials or provide an insecure fallback:
+
+```rust
+// Wrong: canonical examples must not normalize secrets in source.
+let database_url = "mysql://user:password@127.0.0.1/application";
+
+// Wrong: a missing deployment value must fail instead of silently using credentials.
+let database_url = std::env::var("SADDLE_DATABASE_URL")
+    .unwrap_or_else(|_| "mysql://user:password@127.0.0.1/application".into());
+```
+
+Do not import Service traits from the facade root:
+
+```rust
+// Wrong in 0.1.1: these are under saddle::service.
+use saddle::{Service, ServiceHandler};
+```
+
+Do not implement business execution with Tokio or Axum:
+
+```rust
+// Wrong: business code must not own the runtime or HTTP server.
+#[tokio::main]
+async fn main() {}
+
+tokio::spawn(async move {});
+axum::Router::new();
+```
+
+Do not invent ergonomic macros or async trait syntax that 0.1.1 does not publish:
+
+```rust
+// Wrong: not verified public APIs in 0.1.1.
+#[saddle::service]
+async fn hello(...) { ... }
+
+#[saddle::main]
+async fn main() { ... }
+```
+
+Do not create a registry or database directly:
+
+```rust
+// Wrong: assembly and managed I/O construction belong to Saddle.
+let registry = saddle::service::ServiceRegistryBuilder::new();
+let database = saddle::db::Database::connect(...);
+```
+
+## Validation
+
+Run:
+
+```bash
+cargo +1.85.0 check --locked --manifest-path examples/helloworld/Cargo.toml
+cargo check --locked --manifest-path examples/helloworld/Cargo.toml
+cargo tree --locked --manifest-path examples/helloworld/Cargo.toml \
+  -p saddle-framework@0.1.1
+```
+
+Current verified result:
+
+- The Rust 1.85 and current-toolchain checks compile against the crates.io `saddle-framework 0.1.1` artifact.
+- The dependency tree resolves every Saddle component to 0.1.1.
+- The lockfile is resolved with Cargo 1.85's incompatible-Rust-version fallback so every selected package supports the declared minimum.
+
+The example does not prove runtime readiness because `SADDLE_DATABASE_URL` must identify a reachable database and the configured listen address must be available.