@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-module-sdk/Cargo.toml

@@ -0,0 +1,49 @@
+[package]
+name = "kroma-module-sdk"
+version = "0.1.40-canary.0"
+edition = "2021"
+rust-version = "1.88"
+description = "The KROMA module SDK: the single crate every server module depends on. Re-exports the manifest layer plus the engine/host/domain/http/db surface, so modules never depend on core crates directly."
+license = "MIT"
+
+[dependencies]
+# Manifest layer (below engine): EmbeddedModule / Registry / ModuleManifest.
+kroma-module-manifest = { path = "../kroma-module-manifest" }
+# The embedded_module!() proc-macro, re-exported so modules write one line.
+kroma-module-macros = { path = "../kroma-module-macros" }
+# Host contract: ServerModule, HostCtx, service/port resolution, async_trait.
+kroma-module-host = { path = "../kroma-module-host" }
+# The application surface modules build against. Both are optional and both are
+# off by default: between them they are the whole core, and a sidecar that only
+# publishes an mDNS beacon has no business linking it.
+kroma-domain = { path = "../kroma-domain" }
+kroma-http = { path = "../kroma-http" }
+kroma-db = { path = "../kroma-db", optional = true }
+kroma-primitives = { path = "../kroma-primitives" }
+# `testing::{TempDir, temp_dir}`, the scratch dir every module test writes in.
+kroma-testing = { path = "../kroma-testing", optional = true }
+# Both ends of every port contract live beside its trait: the provider mounts
+# axum routes, the consumer proxies over them.
+axum = { version = "0.8", features = ["macros", "ws"] }
+tokio = { version = "1", features = ["full"] }
+# The port contract types derive serde and return anyhow::Result.
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1" }
+anyhow = { version = "1" }
+
+[features]
+# Everything a module's tests reach: the `StubHost` double, `test_serve`, a
+# throwaway pool and a self-deleting scratch dir. Never `engine`: a round-trip
+# test must not link the whole core.
+testing = ["kroma-module-host/testing", "storage", "kroma-db/testing", "dep:kroma-testing"]
+# The `storage` capability: `host::HostStorage` and the `db` facade. A module
+# enables it when its `module.json` declares `storage`, and only then does its
+# binary link SQLite -- which is 1.5 MB of the 3.3 MB a sidecar used to be.
+storage = ["dep:kroma-db", "kroma-module-host/storage"]
+# The `engine` facade (`engine::services`, `engine::model`): the core's own
+# business logic, for the two modules that orchestrate it. It pulls `kroma-db`
+# with it, because the services it exposes are written against the pool.
+
+
+[lints.rust]
+unexpected_cfgs = { level = "allow", check-cfg = ['cfg(feature, values("engine"))'] }

package/rust/kroma-module-sdk/src/lib.rs

@@ -0,0 +1,70 @@
+//! The KROMA module SDK: the ONE crate a server module depends on.
+//!
+//! A module must not depend on `kroma-engine`, `kroma-db`, `kroma-domain` or
+//! `kroma-http` directly. This facade re-exports the manifest layer at the crate
+//! root (`EmbeddedModule`, `ModuleManifest`, `Registry`, ...) and mirrors the
+//! host / engine / domain / http / db / primitives surface under submodules, so a
+//! module writes `kroma_module_sdk::engine::state::SharedState` instead of
+//! reaching into the core crate.
+//!
+//! What is NOT here is any description of what a module is for. A module reaches
+//! a peer by asking [`host::HostCtx::contributions`] for a point NAME and calling
+//! it with JSON both sides declare themselves; there is no trait here for
+//! torznab, or downloads, or anything else, because the core cannot enumerate the
+//! things modules will do. See docs/module-plugin-model.md.
+
+// Manifest layer (below engine): EmbeddedModule / Module / ModuleManifest /
+// Registry / capability + config types. Re-exported at the crate root.
+pub use kroma_module_manifest::*;
+
+/// `embedded_module!()` builds a module's `MODULE` const by discovering its
+/// `module.json` + `icon.<ext>` at compile time. Write
+/// `pub const MODULE: EmbeddedModule = kroma_module_sdk::embedded_module!();`.
+pub use kroma_module_macros::embedded_module;
+
+/// Host contract: the `ServerModule` trait, `HostCtx`, the point resolvers and
+/// the `service` helper, and the `async_trait` re-export module impls need.
+pub mod host {
+    pub use kroma_module_host::*;
+}
+
+/// The application surface: `state::SharedState`, `services::*`, `model::*`.
+/// Behind the `engine` feature: this is the whole core, and only the two modules
+/// that orchestrate it (acquisition, torrents) have any use for it.
+#[cfg(feature = "engine")]
+pub mod engine {
+    pub use kroma_engine::*;
+}
+
+/// Domain types: permissions and the shared DTOs.
+pub mod domain {
+    pub use kroma_domain::*;
+}
+
+/// The outbound HTTP client (`Fetch`, `Response`).
+pub mod http {
+    pub use kroma_http::*;
+}
+
+/// Direct SQLite access. Behind the `storage` feature, which a module turns on
+/// when its `module.json` declares `storage`; the pools themselves come from
+/// `host::HostStorage`, not from here.
+#[cfg(feature = "storage")]
+pub mod db {
+    pub use kroma_db::*;
+}
+
+/// Small shared primitives (`now_ms`, ...).
+pub mod primitives {
+    pub use kroma_primitives::*;
+}
+
+/// What a module's tests reach: `serve` / `blocking` stand a point's provider up
+/// on a real socket for a test that drives both ends, and `TempDir` / `temp_dir`
+/// are the self-deleting scratch dir. The `StubHost` double is
+/// `host::testing::StubHost`, and a throwaway pool is `db::testing::temp_pool`.
+#[cfg(any(test, feature = "testing"))]
+pub mod testing {
+    pub use kroma_module_host::test_serve::*;
+    pub use kroma_testing::*;
+}

package/rust/kroma-primitives/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "kroma-primitives"
+version = "0.1.40-canary.0"
+edition = "2021"
+rust-version = "1.88"
+description = "Shared low-level primitives: timestamps, short hashes, random tokens"
+license = "MIT"
+
+[dependencies]
+time = { version = "0.3", features = ["formatting", "macros"] }
+sha2 = { version = "0.10" }
+hex = { version = "0.4" }

package/rust/kroma-primitives/src/lib.rs

@@ -0,0 +1,101 @@
+//! Low-level, dependency-light primitives shared across the server's layers:
+//! monotonic-ish wall-clock timestamps, stable short hashes, and random tokens.
+//! `services::{jobs::now_ms, scan::{now_iso8601, short_hash}, auth::random_*}`
+//! re-export these for backwards compatibility.
+
+use sha2::{Digest, Sha256};
+use time::format_description::well_known::Rfc3339;
+use time::OffsetDateTime;
+
+/// Current time as epoch milliseconds (UTC instant).
+pub fn now_ms() -> i64 {
+    (OffsetDateTime::now_utc().unix_timestamp_nanos() / 1_000_000) as i64
+}
+
+/// Current time as an RFC3339 / ISO8601 string (UTC).
+pub fn now_iso8601() -> String {
+    OffsetDateTime::now_utc()
+        .format(&Rfc3339)
+        .unwrap_or_else(|_| "1970-01-01T00:00:00Z".to_string())
+}
+
+/// `hex(sha256(input))[..16]` stable, short, collision-resistant enough.
+pub fn short_hash(input: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(input.as_bytes());
+    hex::encode(hasher.finalize())[..16].to_string()
+}
+
+/// `n` cryptographically-secure random bytes, read from the OS CSPRNG
+/// (`/dev/urandom`, falling back to `/dev/random`).
+///
+/// No algorithmic fallback: every session token and password salt derives
+/// from this, so a clock-seeded stand-in would let an attacker who can
+/// estimate the generation time brute-force the seed. We panic instead of
+/// minting predictable secrets.
+pub fn random_bytes(n: usize) -> Vec<u8> {
+    use std::io::Read;
+    let mut buf = vec![0u8; n];
+    for path in ["/dev/urandom", "/dev/random"] {
+        if let Ok(mut f) = std::fs::File::open(path) {
+            if f.read_exact(&mut buf).is_ok() {
+                return buf;
+            }
+        }
+    }
+    panic!("kroma-primitives: OS CSPRNG unavailable; refusing to generate insecure randomness");
+}
+
+/// A fresh opaque session token: 32 random bytes, hex-encoded (64 chars).
+pub fn random_token() -> String {
+    hex::encode(random_bytes(32))
+}
+
+/// A random `u32` (used to pick Quick Connect numeric codes).
+pub fn random_u32() -> u32 {
+    let b = random_bytes(4);
+    u32::from_le_bytes([b[0], b[1], b[2], b[3]])
+}
+
+/// The shape every self-declared device id must have: 8-64 of
+/// `[A-Za-z0-9._-]`. Long enough to be unique per device, narrow enough that a
+/// caller cannot smuggle a path segment or a control character through one.
+pub fn valid_device_id(id: &str) -> bool {
+    (8..=64).contains(&id.len())
+        && id
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.'))
+}
+
+/// A device-supplied label, trimmed to `max` characters with control characters
+/// stripped: these are rendered in other people's device pickers, where a raw
+/// newline could otherwise forge a line.
+pub fn clean_label(s: &str, max: usize) -> String {
+    let out: String = s.chars().filter(|c| !c.is_control()).take(max).collect();
+    out.trim().to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_device_id_must_be_long_enough_and_plain_enough() {
+        assert!(valid_device_id("tv-abcdef"));
+        assert!(valid_device_id(&"y".repeat(64)));
+        assert!(!valid_device_id("short"));
+        assert!(!valid_device_id(&"y".repeat(65)));
+        assert!(!valid_device_id("has spaces"));
+        assert!(!valid_device_id("../escape"));
+        assert!(!valid_device_id(""));
+    }
+
+    #[test]
+    fn a_label_loses_its_control_characters_and_its_overflow() {
+        assert_eq!(clean_label("  Salon  ", 48), "Salon");
+        assert_eq!(clean_label("Salon\nAdmin", 48), "SalonAdmin");
+        assert_eq!(clean_label(&"a".repeat(80), 10), "a".repeat(10));
+        // Truncation counts characters, not bytes: a multi-byte label survives.
+        assert_eq!(clean_label("téléviseur", 4), "télé");
+    }
+}

package/rust/kroma-testing/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "kroma-testing"
+version = "0.1.40-canary.0"
+edition = "2021"
+rust-version = "1.88"
+description = "Self-deleting temp directories for the test harnesses"
+license = "MIT"
+
+[dependencies]
+tempfile = { version = "3" }

package/rust/kroma-testing/src/lib.rs

@@ -0,0 +1,72 @@
+//! Scratch directories for test harnesses, owned by a guard.
+//!
+//! A hand-built `env::temp_dir().join(pid)` is a path, not a resource: nothing
+//! removes it when the test ends, panics, or is killed. A [`TempDir`] goes when
+//! its holder drops, unwinding included.
+
+pub use tempfile::TempDir;
+
+/// A fresh, empty directory under `$TMPDIR`, named `kroma-<tag>-<random>` so a
+/// stray one is still identifiable.
+///
+/// The directory is removed when the returned guard drops, so bind the guard
+/// for as long as the path is used: a caller that keeps only `path()` is
+/// holding a directory that is already gone.
+pub fn temp_dir(tag: &str) -> TempDir {
+    tempfile::Builder::new()
+        .prefix(&format!("kroma-{tag}-"))
+        .tempdir()
+        .expect("create temp dir")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_directory_exists_while_the_guard_does_and_not_after() {
+        let path = {
+            let dir = temp_dir("selftest");
+            let path = dir.path().to_path_buf();
+            assert!(path.is_dir());
+            std::fs::write(path.join("payload"), b"x").expect("write into the temp dir");
+            path
+        };
+        assert!(!path.exists(), "the guard dropped but left {path:?} behind");
+    }
+
+    #[test]
+    fn two_guards_never_share_a_directory() {
+        let a = temp_dir("selftest");
+        let b = temp_dir("selftest");
+        assert_ne!(a.path(), b.path());
+    }
+
+    #[test]
+    fn a_panicking_test_still_takes_its_directory_with_it() {
+        let leaked = std::panic::catch_unwind(|| {
+            let dir = temp_dir("selftest-panic");
+            let path = dir.path().to_path_buf();
+            panic!("{}", path.display());
+        })
+        .unwrap_err();
+        let path = leaked
+            .downcast_ref::<String>()
+            .expect("panicked with a String");
+        assert!(
+            !std::path::Path::new(path).exists(),
+            "unwinding left {path} behind"
+        );
+    }
+
+    #[test]
+    fn the_name_says_which_harness_made_it() {
+        let dir = temp_dir("scanroot");
+        let name = dir
+            .path()
+            .file_name()
+            .and_then(|n| n.to_str())
+            .expect("a utf-8 name");
+        assert!(name.starts_with("kroma-scanroot-"), "{name}");
+    }
+}

package/templates/base/README.md

@@ -0,0 +1,14 @@
+# __NAME__
+
+A KROMA module (`__ID__`).
+
+```bash
+bunx kroma login http://localhost:4040   # once, an account with settings.manage
+bunx kroma dev                      # build, install, rebuild on every save
+bunx kroma check                    # manifest, types, clippy
+bunx kroma build                    # dist/modules/__ID__.kmod
+```
+
+Layout: `module.json` is the manifest, `ui/` the page a KROMA client renders,
+`server/` the sidecar the server spawns, `locales/` the strings. See
+https://github.com/maxscharwath/kroma/blob/main/modules/README.md.

package/templates/base/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.bundle/
+server/target/

package/templates/base/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512"><title>__NAME__</title><rect width="512" height="512" fill="#4A00E0"/><g transform="translate(122.88 122.88) scale(11.093)" color="#FFFFFF"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 3l8 4.5v9L12 21l-8-4.5v-9L12 3zm0 9l8-4.5M12 12v9m0-9L4 7.5"/></g></svg>

package/templates/base/locales/en.json

@@ -0,0 +1,7 @@
+{
+  "nav.__SLUG__": "__NAME__",
+  "page.title": "__NAME__",
+  "page.hello": "Hello from __NAME__. The sidecar answered: {answer}",
+  "page.loading": "Loading",
+  "page.failed": "The module did not answer"
+}

package/templates/base/locales/fr.json

@@ -0,0 +1,7 @@
+{
+  "nav.__SLUG__": "__NAME__",
+  "page.title": "__NAME__",
+  "page.hello": "Bonjour de __NAME__. Le module a répondu : {answer}",
+  "page.loading": "Chargement",
+  "page.failed": "Le module n'a pas répondu"
+}

package/templates/server/.cargo/config.toml

@@ -0,0 +1,2 @@
+[env]
+LIBSQLITE3_FLAGS = { value = "-USQLITE_ENABLE_FTS3 -USQLITE_ENABLE_FTS3_PARENTHESIS -USQLITE_ENABLE_FTS5 -USQLITE_ENABLE_RTREE", force = true }

package/templates/server/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "__RUST_CHANNEL__"
+components = ["clippy", "rustfmt"]

package/templates/server/server/Cargo.toml

@@ -0,0 +1,37 @@
+[workspace]
+
+[package]
+name = "__CRATE__"
+version = "__VERSION__"
+edition = "2021"
+rust-version = "1.88"
+license = "MIT"
+
+[[bin]]
+name = "kroma-module-__SLUG__"
+path = "src/bin/module.rs"
+
+[dependencies]
+kroma-module-sdk = { path = "__SDK_CRATES__/kroma-module-sdk"__SDK_FEATURES__ }
+kroma-module-runtime = { path = "__SDK_CRATES__/kroma-module-runtime"__RUNTIME_FEATURES__ }
+axum = { version = "0.8", features = ["macros"] }
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+anyhow = "1"
+
+[dev-dependencies]
+kroma-module-sdk = { path = "__SDK_CRATES__/kroma-module-sdk", features = ["testing"] }
+
+[profile.release]
+opt-level = 3
+lto = "thin"
+codegen-units = 16
+strip = true
+
+[profile.release-kmod]
+inherits = "release"
+panic = "abort"
+
+[profile.dev]
+debug = "line-tables-only"

package/templates/server/server/src/bin/module.rs

@@ -0,0 +1,6 @@
+use kroma_module_runtime::RemoteHost;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    kroma_module_runtime::serve_one(|_host| {}, __CRATE_IDENT__::server_module::<RemoteHost>()).await
+}

package/templates/server/server/src/lib.rs

@@ -0,0 +1,43 @@
+use axum::extract::State;
+use axum::routing::get;
+use axum::{Json, Router};
+use serde::Serialize;
+
+use kroma_module_sdk::host::{async_trait, AuthUser, HostCtx, ServerModule};
+use kroma_module_sdk::EmbeddedModule;
+
+pub const MODULE: EmbeddedModule = kroma_module_sdk::embedded_module!();
+
+pub struct __STRUCT__;
+
+#[async_trait]
+impl<S> ServerModule<S> for __STRUCT__
+where
+    S: HostCtx + Clone + Send + Sync + 'static,
+{
+    fn id(&self) -> &'static str {
+        "__ID__"
+    }
+__MIGRATIONS__
+    fn admin_routes(&self, _host: &S) -> Option<Router<S>> {
+        Some(Router::new().route("/hello", get(hello::<S>)))
+    }
+}
+
+#[derive(Serialize)]
+struct Hello {
+    answer: String,
+}
+
+async fn hello<S: HostCtx + Clone + Send + Sync + 'static>(
+    State(_state): State<S>,
+    AuthUser(user): AuthUser,
+) -> Json<Hello> {
+    Json(Hello {
+        answer: format!("hello, {}", user.username),
+    })
+}
+
+pub fn server_module<S: HostCtx + Clone + Send + Sync + 'static>() -> Box<dyn ServerModule<S>> {
+    Box::new(__STRUCT__)
+}

package/templates/ui/ui/src/__PAGE__.tsx

@@ -0,0 +1,22 @@
+import { ModuleFailed, ModuleLoading, useFetch, useModuleApi, useT } from '__SDK__';
+import { PageHeader, Surface, Text } from '@kroma/ui/kit';
+import { Hello } from './schemas';
+
+export default function __PAGE__() {
+  const t = useT();
+  const api = useModuleApi();
+  const hello = useFetch(['hello'], () => api.get('/hello', Hello));
+
+  if (hello.failed) return <ModuleFailed />;
+  if (!hello.data) return <ModuleLoading />;
+  return (
+    <>
+      <PageHeader.Root>
+        <PageHeader.Title>{t('page.title')}</PageHeader.Title>
+      </PageHeader.Root>
+      <Surface elevated border="border" px={22} py={20} mt={24}>
+        <Text>{t('page.hello', { answer: hello.data.answer })}</Text>
+      </Surface>
+    </>
+  );
+}

package/templates/ui/ui/src/module.tsx

@@ -0,0 +1,17 @@
+import { defineModule } from '__SDK__';
+import { lazy } from 'react';
+
+export default defineModule({
+  pages: [
+    {
+      path: '__SLUG__',
+      component: lazy(() => import('./__PAGE__')),
+      nav: {
+        label: 'nav.__SLUG__',
+        icon: 'puzzle',
+        section: 'system',
+        requires: 'settings.manage',
+      },
+    },
+  ],
+});

package/templates/ui/ui/src/schemas.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+
+export const Hello = z.object({
+  answer: z.string(),
+});
+export type Hello = z.infer<typeof Hello>;

package/tsconfig.module.json

@@ -0,0 +1,110 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "jsx": "react-jsx",
+    "types": [
+      "react"
+    ],
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "useDefineForClassFields": true,
+    "paths": {
+      "@kroma/registry": [
+        "./types/registry/src/index.d.ts"
+      ],
+      "@kroma/i18n": [
+        "./types/i18n/src/index.d.ts"
+      ],
+      "@kroma/i18n/react": [
+        "./types/i18n/src/react/index.d.ts"
+      ],
+      "@kroma/spatial-nav": [
+        "./types/spatial-nav/src/index.d.ts"
+      ],
+      "@kroma/spatial-nav/react": [
+        "./types/spatial-nav/src/react.d.ts"
+      ],
+      "@kroma/client": [
+        "./types/client/src/index.d.ts"
+      ],
+      "@kroma/client/query": [
+        "./types/client/src/query/index.d.ts"
+      ],
+      "@kroma/client/test": [
+        "./types/client/src/kroma-client.fixture.d.ts"
+      ],
+      "@kroma/client/*": [
+        "./types/client/src/api/*/index.d.ts"
+      ],
+      "@kroma/core": [
+        "./types/core/src/index.d.ts"
+      ],
+      "@kroma/core/react": [
+        "./types/core/src/react/index.d.ts"
+      ],
+      "@kroma/ui": [
+        "./types/ui/src/index.d.ts"
+      ],
+      "@kroma/ui/kit": [
+        "./types/ui/src/kit.d.ts"
+      ],
+      "@kroma/ui/kit/*": [
+        "./types/ui/src/components/*/index.d.ts"
+      ],
+      "@kroma/ui/atomic": [
+        "./types/ui/src/core/atomic/index.d.ts"
+      ],
+      "@kroma/ui/ssr": [
+        "./types/ui/src/ssr.d.ts"
+      ],
+      "@kroma/ui/expo-image": [
+        "./types/ui/src/lib/expo-image-backend.d.ts"
+      ],
+      "@kroma/ui/testing": [
+        "./types/ui/src/testing.d.ts"
+      ],
+      "@kroma/ui/workbench-config": [
+        "./types/ui/src/workbench-config.d.ts"
+      ],
+      "@kroma/ui/lockup": [
+        "./types/ui/src/lib/lockup-paths.d.ts"
+      ],
+      "@kroma/ui/tokens": [
+        "./types/ui/src/core/tokens/index.d.ts"
+      ],
+      "@kroma/ui/tokens/colors": [
+        "./types/ui/src/core/tokens/colors.d.ts"
+      ],
+      "@kroma/ui/tokens/*": [
+        "./types/ui/src/core/tokens/*.d.ts"
+      ],
+      "@kroma/ui/fonts": [
+        "./types/ui/src/assets/fonts.d.ts"
+      ],
+      "@kroma/module-sdk": [
+        "./types/module-sdk/src/index.d.ts"
+      ],
+      "@kroma/module-sdk/shared": [
+        "./types/module-sdk/src/shared.d.ts"
+      ]
+    }
+  }
+}