Skip to main content

skenion_runtime/
extension_manager.rs

1use std::{
2    env,
3    ffi::OsString,
4    fs,
5    path::{Component, Path, PathBuf},
6};
7
8use serde::Serialize;
9use serde_json::json;
10
11use crate::{DiagnosticSeverity, RuntimeDiagnostic};
12use skenion_contracts::{
13    ExtensionKindV01 as ExtensionKind, ExtensionManifestV01 as ExtensionManifest,
14    ExtensionNativeBindingV01, validate_extension_manifest_v01, validate_node_definition_v01,
15};
16
17pub const RUNTIME_EXTENSION_MANIFEST_FILE: &str = "skenion.extension.json";
18pub const RUNTIME_EXTENSION_ABI_VERSION: &str = "0.1.0";
19pub const SKENION_EXTENSION_PATH_ENV: &str = "SKENION_EXTENSION_PATH";
20const EXTENSION_MANIFEST_SCHEMA: &str = "skenion.extension.manifest";
21const EXTENSION_MANIFEST_SCHEMA_VERSION: &str = "0.1.0";
22
23#[derive(Debug, Clone, Serialize)]
24#[serde(rename_all = "camelCase")]
25pub struct RuntimeExtensionListResponse {
26    pub ok: bool,
27    pub extensions: Vec<RuntimeExtensionDescriptor>,
28    pub diagnostics: Vec<RuntimeDiagnostic>,
29}
30
31#[derive(Debug, Clone, Serialize)]
32#[serde(rename_all = "camelCase")]
33pub struct RuntimeExtensionDescriptor {
34    pub id: String,
35    pub version: String,
36    pub kind: ExtensionKind,
37    pub runtime_abi_version: String,
38    pub manifest_path: String,
39    pub status: RuntimeExtensionStatus,
40    pub capabilities: Vec<String>,
41    pub provided_nodes: Vec<String>,
42    pub provided_codecs: Vec<String>,
43    pub provided_transports: Vec<String>,
44    pub provided_help: Vec<String>,
45    pub test_ids: Vec<String>,
46    pub diagnostics: Vec<RuntimeDiagnostic>,
47}
48
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
50#[serde(rename_all = "lowercase")]
51pub enum RuntimeExtensionStatus {
52    Loaded,
53    Disabled,
54    Failed,
55}
56
57#[derive(Debug, Clone, Default)]
58pub struct RuntimeExtensionManager {
59    package_dirs: Vec<PathBuf>,
60}
61
62impl RuntimeExtensionManager {
63    pub fn from_env() -> Self {
64        Self::from_extension_paths(env::var_os(SKENION_EXTENSION_PATH_ENV))
65    }
66
67    fn from_extension_paths(paths: Option<OsString>) -> Self {
68        let Some(paths) = paths else {
69            return Self::default();
70        };
71
72        Self {
73            package_dirs: env::split_paths(&paths).collect(),
74        }
75    }
76
77    #[cfg(test)]
78    pub(crate) fn with_package_dirs(package_dirs: Vec<PathBuf>) -> Self {
79        Self { package_dirs }
80    }
81
82    pub fn list_extensions(&self) -> RuntimeExtensionListResponse {
83        let mut diagnostics = Vec::new();
84        let extensions = self
85            .package_dirs
86            .iter()
87            .filter_map(|package_dir| {
88                let manifest_path = package_dir.join(RUNTIME_EXTENSION_MANIFEST_FILE);
89                if !manifest_path.exists() {
90                    diagnostics.push(diagnostic(
91                        DiagnosticSeverity::Warning,
92                        format!(
93                            "extension package {} does not contain {RUNTIME_EXTENSION_MANIFEST_FILE}",
94                            package_dir.display()
95                        ),
96                    ));
97                    return None;
98                }
99                Some(read_extension_package(package_dir, &manifest_path))
100            })
101            .collect::<Vec<_>>();
102
103        let ok = diagnostics
104            .iter()
105            .chain(
106                extensions
107                    .iter()
108                    .flat_map(|extension| extension.diagnostics.iter()),
109            )
110            .all(|diagnostic| diagnostic.severity != DiagnosticSeverity::Error);
111
112        RuntimeExtensionListResponse {
113            ok,
114            extensions,
115            diagnostics,
116        }
117    }
118}
119
120impl Default for RuntimeExtensionListResponse {
121    fn default() -> Self {
122        Self {
123            ok: true,
124            extensions: Vec::new(),
125            diagnostics: Vec::new(),
126        }
127    }
128}
129
130fn read_extension_package(package_dir: &Path, manifest_path: &Path) -> RuntimeExtensionDescriptor {
131    let absolute_manifest_path =
132        fs::canonicalize(manifest_path).unwrap_or_else(|_| manifest_path.to_path_buf());
133    let contents = match fs::read_to_string(manifest_path) {
134        Ok(contents) => contents,
135        Err(error) => {
136            return RuntimeExtensionDescriptor {
137                id: package_dir
138                    .file_name()
139                    .and_then(|name| name.to_str())
140                    .unwrap_or("unknown-extension")
141                    .to_owned(),
142                version: "0.0.0".to_owned(),
143                kind: ExtensionKind::NodePack,
144                runtime_abi_version: RUNTIME_EXTENSION_ABI_VERSION.to_owned(),
145                manifest_path: absolute_manifest_path.display().to_string(),
146                status: RuntimeExtensionStatus::Failed,
147                capabilities: Vec::new(),
148                provided_nodes: Vec::new(),
149                provided_codecs: Vec::new(),
150                provided_transports: Vec::new(),
151                provided_help: Vec::new(),
152                test_ids: Vec::new(),
153                diagnostics: vec![RuntimeDiagnostic::structured_error(
154                    "extension.manifest.read-failed",
155                    format!("failed to read extension manifest: {error}"),
156                    json!({
157                        "surface": "extension-manifest",
158                        "packagePath": package_dir.display().to_string(),
159                        "manifestPath": absolute_manifest_path.display().to_string(),
160                    }),
161                )],
162            };
163        }
164    };
165
166    let manifest_value = match serde_json::from_str::<serde_json::Value>(&contents) {
167        Ok(value) => value,
168        Err(error) => {
169            return failed_descriptor_from_manifest_value(
170                package_dir,
171                &absolute_manifest_path,
172                None,
173                RuntimeDiagnostic::structured_error(
174                    "extension.manifest.parse-failed",
175                    format!("failed to parse extension manifest: {error}"),
176                    json!({
177                        "surface": "extension-manifest",
178                        "packagePath": package_dir.display().to_string(),
179                        "manifestPath": absolute_manifest_path.display().to_string(),
180                    }),
181                ),
182            );
183        }
184    };
185
186    let manifest = match serde_json::from_value::<ExtensionManifest>(manifest_value.clone()) {
187        Ok(manifest) => manifest,
188        Err(error) => {
189            let header = manifest_header_from_value(&manifest_value);
190            return failed_descriptor_from_manifest_value(
191                package_dir,
192                &absolute_manifest_path,
193                header.as_ref(),
194                RuntimeDiagnostic::structured_error(
195                    "extension.manifest.parse-failed",
196                    format!("failed to parse extension manifest: {error}"),
197                    json!({
198                        "surface": "extension-manifest",
199                        "packageId": header.as_ref().map(|header| header.id.as_str()),
200                        "manifestId": header.as_ref().map(|header| header.id.as_str()),
201                        "packagePath": package_dir.display().to_string(),
202                        "manifestPath": absolute_manifest_path.display().to_string(),
203                    }),
204                ),
205            );
206        }
207    };
208
209    descriptor_from_manifest(package_dir, absolute_manifest_path, manifest)
210}
211
212fn descriptor_from_manifest(
213    package_dir: &Path,
214    manifest_path: PathBuf,
215    manifest: ExtensionManifest,
216) -> RuntimeExtensionDescriptor {
217    let mut diagnostics = validate_manifest(package_dir, &manifest_path, &manifest);
218    let status = if diagnostics
219        .iter()
220        .any(|diagnostic| diagnostic.severity == DiagnosticSeverity::Error)
221    {
222        RuntimeExtensionStatus::Failed
223    } else {
224        RuntimeExtensionStatus::Loaded
225    };
226
227    let provided_nodes = manifest
228        .provides
229        .nodes
230        .iter()
231        .map(|node| node.id.clone())
232        .collect::<Vec<_>>();
233    let provided_codecs = manifest
234        .provides
235        .codecs
236        .iter()
237        .map(|codec| codec.id.clone())
238        .collect::<Vec<_>>();
239    let provided_transports = manifest
240        .provides
241        .transports
242        .iter()
243        .map(|transport| transport.id.clone())
244        .collect::<Vec<_>>();
245    let provided_help = manifest
246        .provides
247        .help
248        .iter()
249        .map(|help| help.node_id.clone())
250        .collect::<Vec<_>>();
251    let test_ids = manifest
252        .tests
253        .iter()
254        .map(|test| test.id.clone())
255        .collect::<Vec<_>>();
256
257    let capabilities = manifest
258        .provides
259        .nodes
260        .iter()
261        .flat_map(|node| node.capabilities.iter().cloned())
262        .collect::<Vec<_>>();
263
264    RuntimeExtensionDescriptor {
265        id: manifest.id,
266        version: manifest.version,
267        kind: manifest.kind,
268        runtime_abi_version: manifest.runtime_abi_version,
269        manifest_path: manifest_path.display().to_string(),
270        status,
271        capabilities,
272        provided_nodes,
273        provided_codecs,
274        provided_transports,
275        provided_help,
276        test_ids,
277        diagnostics: {
278            diagnostics.sort_by(|a, b| a.message.cmp(&b.message));
279            diagnostics
280        },
281    }
282}
283
284fn validate_manifest(
285    package_dir: &Path,
286    manifest_path: &Path,
287    manifest: &ExtensionManifest,
288) -> Vec<RuntimeDiagnostic> {
289    let mut diagnostics = Vec::new();
290
291    if let Err(report) = validate_extension_manifest_v01(manifest) {
292        diagnostics.extend(report.errors().iter().map(|error| {
293            RuntimeDiagnostic::structured_error(
294                "extension.manifest.contract-invalid",
295                format!(
296                    "extension manifest failed contract validation: {}",
297                    error.message
298                ),
299                json!({
300                    "surface": "extension-manifest",
301                    "packageId": manifest.id,
302                    "manifestId": manifest.id,
303                    "packagePath": package_dir.display().to_string(),
304                    "manifestPath": manifest_path.display().to_string(),
305                    "error": error.message,
306                }),
307            )
308        }));
309    }
310
311    if manifest.schema != EXTENSION_MANIFEST_SCHEMA {
312        diagnostics.push(RuntimeDiagnostic::structured_error(
313            "extension.manifest.invalid-schema",
314            format!(
315                "extension manifest schema must be skenion.extension.manifest, got {}",
316                manifest.schema
317            ),
318            json!({
319                "surface": "extension-manifest",
320                "packageId": manifest.id,
321                "manifestId": manifest.id,
322                "packagePath": package_dir.display().to_string(),
323                "manifestPath": manifest_path.display().to_string(),
324                "expectedSchema": EXTENSION_MANIFEST_SCHEMA,
325                "receivedSchema": manifest.schema,
326            }),
327        ));
328    }
329    if manifest.schema_version != EXTENSION_MANIFEST_SCHEMA_VERSION {
330        diagnostics.push(RuntimeDiagnostic::structured_error(
331            "extension.manifest.unsupported-schema-version",
332            format!(
333                "extension manifest schemaVersion must be 0.1.0, got {}",
334                manifest.schema_version
335            ),
336            json!({
337                "surface": "extension-manifest",
338                "packageId": manifest.id,
339                "manifestId": manifest.id,
340                "packagePath": package_dir.display().to_string(),
341                "manifestPath": manifest_path.display().to_string(),
342                "expectedSchemaVersion": EXTENSION_MANIFEST_SCHEMA_VERSION,
343                "receivedSchemaVersion": manifest.schema_version,
344            }),
345        ));
346    }
347    if manifest.runtime_abi_version != RUNTIME_EXTENSION_ABI_VERSION {
348        diagnostics.push(RuntimeDiagnostic::structured_error(
349            "extension.runtime-abi.unsupported-version",
350            format!(
351                "extension {} requires runtimeAbiVersion {}, but runtime supports {RUNTIME_EXTENSION_ABI_VERSION}",
352                manifest.id, manifest.runtime_abi_version
353            ),
354            json!({
355                "surface": "extension-runtime-abi",
356                "packageId": manifest.id,
357                "manifestId": manifest.id,
358                "packagePath": package_dir.display().to_string(),
359                "manifestPath": manifest_path.display().to_string(),
360                "expectedRuntimeAbiVersion": RUNTIME_EXTENSION_ABI_VERSION,
361                "receivedRuntimeAbiVersion": manifest.runtime_abi_version,
362            }),
363        ));
364    }
365
366    for node in &manifest.provides.nodes {
367        if let Err(report) = validate_node_definition_v01(node) {
368            for error in report.errors() {
369                diagnostics.push(RuntimeDiagnostic::structured_error(
370                    "extension.node.contract-invalid",
371                    format!(
372                        "node {} failed contract validation: {}",
373                        node.id, error.message
374                    ),
375                    json!({
376                        "surface": "extension-node-definition",
377                        "packageId": manifest.id,
378                        "manifestId": manifest.id,
379                        "nodeId": node.id,
380                        "nodeVersion": node.version,
381                        "packagePath": package_dir.display().to_string(),
382                        "manifestPath": manifest_path.display().to_string(),
383                        "error": error.message,
384                    }),
385                ));
386            }
387        }
388    }
389
390    for help in &manifest.provides.help {
391        validate_optional_relative_file(
392            package_dir,
393            help.markdown_path.as_deref(),
394            &mut diagnostics,
395        );
396        validate_optional_relative_file(package_dir, help.graph_path.as_deref(), &mut diagnostics);
397    }
398
399    for test in &manifest.tests {
400        validate_optional_relative_file(
401            package_dir,
402            test.fixture_path.as_deref(),
403            &mut diagnostics,
404        );
405        validate_optional_relative_file(
406            package_dir,
407            test.expected_path.as_deref(),
408            &mut diagnostics,
409        );
410    }
411
412    match manifest.kind {
413        ExtensionKind::NativeRuntime => match &manifest.native {
414            Some(native) => validate_native_binding(package_dir, native, &mut diagnostics),
415            None => diagnostics.push(diagnostic(
416                DiagnosticSeverity::Error,
417                "native-runtime extension must declare native binding".to_owned(),
418            )),
419        },
420        ExtensionKind::CorePackage | ExtensionKind::Codec | ExtensionKind::NodePack => {
421            if let Some(native) = &manifest.native {
422                validate_native_binding(package_dir, native, &mut diagnostics);
423            }
424        }
425    }
426
427    diagnostics
428}
429
430fn validate_native_binding(
431    package_dir: &Path,
432    native: &ExtensionNativeBindingV01,
433    diagnostics: &mut Vec<RuntimeDiagnostic>,
434) {
435    if native.entrypoint != "skenion_extension_init" {
436        diagnostics.push(diagnostic(
437            DiagnosticSeverity::Error,
438            format!(
439                "native entrypoint must be skenion_extension_init, got {}",
440                native.entrypoint
441            ),
442        ));
443    }
444
445    let Some(artifact) = native
446        .artifacts
447        .iter()
448        .find(|artifact| artifact.os == env::consts::OS && artifact.arch == env::consts::ARCH)
449    else {
450        diagnostics.push(diagnostic(
451            DiagnosticSeverity::Error,
452            format!(
453                "native extension has no artifact for {}-{}",
454                env::consts::OS,
455                env::consts::ARCH
456            ),
457        ));
458        return;
459    };
460
461    match relative_package_path(package_dir, &artifact.path) {
462        Ok(path) if path.is_file() => {}
463        Ok(path) => diagnostics.push(diagnostic(
464            DiagnosticSeverity::Error,
465            format!("native artifact does not exist: {}", path.display()),
466        )),
467        Err(message) => diagnostics.push(diagnostic(DiagnosticSeverity::Error, message)),
468    }
469}
470
471fn validate_optional_relative_file(
472    package_dir: &Path,
473    relative_path: Option<&str>,
474    diagnostics: &mut Vec<RuntimeDiagnostic>,
475) {
476    let Some(relative_path) = relative_path else {
477        return;
478    };
479
480    match relative_package_path(package_dir, relative_path) {
481        Ok(path) if path.is_file() => {}
482        Ok(path) => diagnostics.push(diagnostic(
483            DiagnosticSeverity::Error,
484            format!("package file does not exist: {}", path.display()),
485        )),
486        Err(message) => diagnostics.push(diagnostic(DiagnosticSeverity::Error, message)),
487    }
488}
489
490fn relative_package_path(package_dir: &Path, relative_path: &str) -> Result<PathBuf, String> {
491    let path = Path::new(relative_path);
492    if path.is_absolute()
493        || path.components().any(|component| {
494            matches!(
495                component,
496                Component::ParentDir | Component::Prefix(_) | Component::RootDir
497            )
498        })
499    {
500        return Err(format!(
501            "extension package path must stay inside package directory: {relative_path}"
502        ));
503    }
504
505    Ok(package_dir.join(path))
506}
507
508fn diagnostic(severity: DiagnosticSeverity, message: String) -> RuntimeDiagnostic {
509    RuntimeDiagnostic {
510        severity,
511        message,
512        code: None,
513        details: None,
514    }
515}
516
517#[derive(Debug, Clone)]
518struct ManifestHeader {
519    id: String,
520    version: String,
521    runtime_abi_version: String,
522    kind: ExtensionKind,
523}
524
525fn manifest_header_from_value(value: &serde_json::Value) -> Option<ManifestHeader> {
526    let object = value.as_object()?;
527    let kind = object
528        .get("kind")
529        .cloned()
530        .and_then(|value| serde_json::from_value::<ExtensionKind>(value).ok())
531        .unwrap_or(ExtensionKind::NodePack);
532    Some(ManifestHeader {
533        id: object
534            .get("id")
535            .and_then(|value| value.as_str())
536            .unwrap_or("unknown-extension")
537            .to_owned(),
538        version: object
539            .get("version")
540            .and_then(|value| value.as_str())
541            .unwrap_or("0.0.0")
542            .to_owned(),
543        runtime_abi_version: object
544            .get("runtimeAbiVersion")
545            .and_then(|value| value.as_str())
546            .unwrap_or(RUNTIME_EXTENSION_ABI_VERSION)
547            .to_owned(),
548        kind,
549    })
550}
551
552fn failed_descriptor_from_manifest_value(
553    package_dir: &Path,
554    manifest_path: &Path,
555    header: Option<&ManifestHeader>,
556    diagnostic: RuntimeDiagnostic,
557) -> RuntimeExtensionDescriptor {
558    RuntimeExtensionDescriptor {
559        id: header
560            .map(|header| header.id.clone())
561            .or_else(|| {
562                package_dir
563                    .file_name()
564                    .and_then(|name| name.to_str())
565                    .map(str::to_owned)
566            })
567            .unwrap_or_else(|| "unknown-extension".to_owned()),
568        version: header
569            .map(|header| header.version.clone())
570            .unwrap_or_else(|| "0.0.0".to_owned()),
571        kind: header
572            .map(|header| header.kind.clone())
573            .unwrap_or(ExtensionKind::NodePack),
574        runtime_abi_version: header
575            .map(|header| header.runtime_abi_version.clone())
576            .unwrap_or_else(|| RUNTIME_EXTENSION_ABI_VERSION.to_owned()),
577        manifest_path: manifest_path.display().to_string(),
578        status: RuntimeExtensionStatus::Failed,
579        capabilities: Vec::new(),
580        provided_nodes: Vec::new(),
581        provided_codecs: Vec::new(),
582        provided_transports: Vec::new(),
583        provided_help: Vec::new(),
584        test_ids: Vec::new(),
585        diagnostics: vec![diagnostic],
586    }
587}
588
589#[cfg(test)]
590mod tests {
591    use super::*;
592    use std::fs;
593
594    fn temp_dir(name: &str) -> PathBuf {
595        let dir = env::temp_dir().join(format!(
596            "skenion-runtime-extension-manager-{name}-{}",
597            std::process::id()
598        ));
599        let _ = fs::remove_dir_all(&dir);
600        fs::create_dir_all(&dir).unwrap();
601        dir
602    }
603
604    fn write_manifest(package_dir: &Path, body: &str) {
605        fs::write(package_dir.join(RUNTIME_EXTENSION_MANIFEST_FILE), body).unwrap();
606    }
607
608    fn current_artifact(path: &str) -> String {
609        format!(
610            r#"{{ "os": "{}", "arch": "{}", "abi": "c", "path": "{path}" }}"#,
611            env::consts::OS,
612            env::consts::ARCH
613        )
614    }
615
616    fn diagnostic_by_code<'a>(
617        diagnostics: &'a [RuntimeDiagnostic],
618        code: &str,
619    ) -> &'a RuntimeDiagnostic {
620        diagnostics
621            .iter()
622            .find(|diagnostic| diagnostic.code.as_deref() == Some(code))
623            .unwrap_or_else(|| panic!("missing {code} diagnostic: {diagnostics:#?}"))
624    }
625
626    #[test]
627    fn extension_paths_parse_like_runtime_environment() {
628        let first = PathBuf::from("/tmp/skenion-extension-one");
629        let second = PathBuf::from("/tmp/skenion-extension-two");
630        let joined = env::join_paths([&first, &second]).unwrap();
631
632        let manager = RuntimeExtensionManager::from_extension_paths(Some(joined));
633
634        assert_eq!(manager.package_dirs, vec![first, second]);
635    }
636
637    #[test]
638    fn extension_manager_can_be_created_from_process_environment() {
639        let manager = RuntimeExtensionManager::from_env();
640
641        let _ = manager.list_extensions();
642    }
643
644    #[test]
645    fn default_extension_response_is_empty_and_ok() {
646        let response = RuntimeExtensionListResponse::default();
647
648        assert!(response.ok);
649        assert!(response.extensions.is_empty());
650        assert!(response.diagnostics.is_empty());
651    }
652
653    #[test]
654    fn package_directory_without_manifest_is_reported_as_warning() {
655        let package_dir = temp_dir("missing-manifest");
656        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
657
658        let response = manager.list_extensions();
659
660        assert!(response.ok);
661        assert!(response.extensions.is_empty());
662        assert_eq!(
663            response.diagnostics[0].severity,
664            DiagnosticSeverity::Warning
665        );
666    }
667
668    #[test]
669    fn malformed_manifest_fails_only_that_extension() {
670        let package_dir = temp_dir("malformed-manifest");
671        write_manifest(&package_dir, "{ not-json");
672        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
673
674        let response = manager.list_extensions();
675
676        assert!(!response.ok);
677        assert!(response.extensions[0].id.contains("malformed-manifest"));
678        assert_eq!(
679            response.extensions[0].status,
680            RuntimeExtensionStatus::Failed
681        );
682        assert!(
683            response.extensions[0].diagnostics[0]
684                .message
685                .contains("failed to parse extension manifest")
686        );
687    }
688
689    #[test]
690    fn manifest_read_error_reports_failed_extension_with_fallback_path() {
691        let package_dir = temp_dir("unreadable-manifest");
692        let manifest_path = package_dir.join(RUNTIME_EXTENSION_MANIFEST_FILE);
693
694        let descriptor = read_extension_package(&package_dir, &manifest_path);
695
696        assert_eq!(descriptor.status, RuntimeExtensionStatus::Failed);
697        assert_eq!(
698            descriptor.manifest_path,
699            manifest_path.display().to_string()
700        );
701        assert!(
702            descriptor.diagnostics[0]
703                .message
704                .contains("failed to read extension manifest")
705        );
706    }
707
708    #[test]
709    fn unsupported_manifest_schema_version_is_structured_package_failure() {
710        let package_dir = temp_dir("legacy-v01-manifest");
711        write_manifest(
712            &package_dir,
713            r#"{
714              "schema": "skenion.extension.manifest",
715              "schemaVersion": "9.9.9",
716              "id": "example/legacy",
717              "version": "0.1.0",
718              "runtimeAbiVersion": "0.1.0",
719              "kind": "node-pack",
720              "provides": {},
721              "permissions": []
722            }"#,
723        );
724        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
725
726        let response = manager.list_extensions();
727
728        assert!(!response.ok);
729        assert_eq!(
730            response.extensions[0].status,
731            RuntimeExtensionStatus::Failed
732        );
733        let diagnostic = diagnostic_by_code(
734            &response.extensions[0].diagnostics,
735            "extension.manifest.unsupported-schema-version",
736        );
737        assert_eq!(
738            diagnostic.details.as_ref().unwrap()["receivedSchemaVersion"],
739            "9.9.9"
740        );
741    }
742
743    #[test]
744    fn invalid_node_test_or_help_paths_fail_only_that_extension() {
745        let package_dir = temp_dir("invalid-package-paths");
746        write_manifest(
747            &package_dir,
748            r#"{
749              "schema": "skenion.extension.manifest",
750              "schemaVersion": "0.1.0",
751              "id": "example/bad-paths",
752              "version": "0.1.0",
753              "runtimeAbiVersion": "0.1.0",
754              "kind": "node-pack",
755              "provides": {
756                "help": [
757                  { "nodeId": "example.node", "markdownPath": "help/missing.md" }
758                ]
759              },
760              "permissions": [],
761              "tests": [
762                { "id": "missing-fixture", "kind": "node", "target": "example.node", "fixturePath": "../outside.json" }
763              ]
764            }"#,
765        );
766        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
767
768        let response = manager.list_extensions();
769
770        assert!(!response.ok);
771        assert_eq!(response.extensions.len(), 1);
772        assert_eq!(
773            response.extensions[0].status,
774            RuntimeExtensionStatus::Failed
775        );
776        assert!(response.extensions[0].diagnostics.iter().any(|diagnostic| {
777            diagnostic
778                .message
779                .contains("must stay inside package directory")
780        }));
781    }
782
783    #[test]
784    fn schema_abi_and_native_contract_errors_are_package_diagnostics() {
785        let package_dir = temp_dir("invalid-package-contract");
786        write_manifest(
787            &package_dir,
788            r#"{
789              "schema": "other.manifest",
790              "schemaVersion": "9.9.9",
791              "id": "example/native-missing",
792              "version": "0.1.0",
793              "runtimeAbiVersion": "9.9.9",
794              "kind": "native-runtime",
795              "provides": {},
796              "permissions": []
797            }"#,
798        );
799        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir.clone()]);
800
801        let response = manager.list_extensions();
802        let diagnostics = &response.extensions[0].diagnostics;
803        let messages = diagnostics
804            .iter()
805            .map(|diagnostic| diagnostic.message.as_str())
806            .collect::<Vec<_>>();
807
808        assert!(!response.ok);
809        assert!(
810            messages
811                .iter()
812                .any(|message| message.contains("schema must"))
813        );
814        assert!(
815            messages
816                .iter()
817                .any(|message| message.contains("schemaVersion must"))
818        );
819        assert!(
820            messages
821                .iter()
822                .any(|message| message.contains("requires runtimeAbiVersion"))
823        );
824        assert!(
825            messages
826                .iter()
827                .any(|message| message.contains("must declare native binding"))
828        );
829
830        let schema_diagnostic =
831            diagnostic_by_code(diagnostics, "extension.manifest.invalid-schema");
832        let schema_details = schema_diagnostic.details.as_ref().unwrap();
833        assert_eq!(schema_details["surface"], "extension-manifest");
834        assert_eq!(schema_details["packageId"], "example/native-missing");
835        assert_eq!(schema_details["manifestId"], "example/native-missing");
836        assert_eq!(
837            schema_details["packagePath"],
838            package_dir.display().to_string()
839        );
840        assert_eq!(
841            schema_details["manifestPath"],
842            response.extensions[0].manifest_path
843        );
844        assert_eq!(
845            schema_details["expectedSchema"],
846            "skenion.extension.manifest"
847        );
848        assert_eq!(schema_details["receivedSchema"], "other.manifest");
849
850        let schema_version_diagnostic =
851            diagnostic_by_code(diagnostics, "extension.manifest.unsupported-schema-version");
852        let schema_version_details = schema_version_diagnostic.details.as_ref().unwrap();
853        assert_eq!(schema_version_details["surface"], "extension-manifest");
854        assert_eq!(
855            schema_version_details["packageId"],
856            "example/native-missing"
857        );
858        assert_eq!(
859            schema_version_details["manifestId"],
860            "example/native-missing"
861        );
862        assert_eq!(
863            schema_version_details["packagePath"],
864            package_dir.display().to_string()
865        );
866        assert_eq!(
867            schema_version_details["manifestPath"],
868            response.extensions[0].manifest_path
869        );
870        assert_eq!(schema_version_details["expectedSchemaVersion"], "0.1.0");
871        assert_eq!(schema_version_details["receivedSchemaVersion"], "9.9.9");
872
873        let abi_diagnostic =
874            diagnostic_by_code(diagnostics, "extension.runtime-abi.unsupported-version");
875        let abi_details = abi_diagnostic.details.as_ref().unwrap();
876        assert_eq!(abi_details["surface"], "extension-runtime-abi");
877        assert_eq!(abi_details["packageId"], "example/native-missing");
878        assert_eq!(abi_details["manifestId"], "example/native-missing");
879        assert_eq!(
880            abi_details["packagePath"],
881            package_dir.display().to_string()
882        );
883        assert_eq!(
884            abi_details["manifestPath"],
885            response.extensions[0].manifest_path
886        );
887        assert_eq!(
888            abi_details["expectedRuntimeAbiVersion"],
889            RUNTIME_EXTENSION_ABI_VERSION
890        );
891        assert_eq!(abi_details["receivedRuntimeAbiVersion"], "9.9.9");
892    }
893
894    #[test]
895    fn invalid_node_contract_is_reported_as_package_failure() {
896        let package_dir = temp_dir("invalid-node-contract");
897        write_manifest(
898            &package_dir,
899            r#"{
900              "schema": "skenion.extension.manifest",
901              "schemaVersion": "0.1.0",
902              "id": "example/invalid-node",
903              "version": "0.1.0",
904              "runtimeAbiVersion": "0.1.0",
905              "kind": "node-pack",
906              "provides": {
907                "nodes": [
908                  {
909                    "schema": "skenion.node.definition",
910                    "schemaVersion": "9.9.9",
911                    "id": "example.bad",
912                    "version": "0.1.0",
913                    "displayName": "Bad",
914                    "category": "Example",
915                    "ports": [],
916                    "execution": { "model": "value" },
917                    "state": { "persistent": false },
918                    "permissions": [],
919                    "capabilities": []
920                  }
921                ]
922              },
923              "permissions": []
924            }"#,
925        );
926        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
927
928        let response = manager.list_extensions();
929
930        assert!(!response.ok);
931        assert_eq!(
932            response.extensions[0].status,
933            RuntimeExtensionStatus::Failed
934        );
935        assert!(response.extensions[0].diagnostics.iter().any(|diagnostic| {
936            diagnostic
937                .message
938                .contains("node example.bad failed contract validation")
939        }));
940    }
941
942    #[test]
943    fn native_binding_validation_reports_missing_and_unsafe_artifacts() {
944        let missing_artifact_dir = temp_dir("native-missing-artifact");
945        write_manifest(
946            &missing_artifact_dir,
947            &format!(
948                r#"{{
949                  "schema": "skenion.extension.manifest",
950                  "schemaVersion": "0.1.0",
951                  "id": "example/native-missing-artifact",
952                  "version": "0.1.0",
953                  "runtimeAbiVersion": "0.1.0",
954                  "kind": "native-runtime",
955                  "native": {{
956                    "entrypoint": "bad_init",
957                    "artifacts": [{}]
958                  }},
959                  "provides": {{}},
960                  "permissions": []
961                }}"#,
962                current_artifact("target/release/libmissing.dylib")
963            ),
964        );
965
966        let unsupported_artifact_dir = temp_dir("native-unsupported-artifact");
967        write_manifest(
968            &unsupported_artifact_dir,
969            r#"{
970              "schema": "skenion.extension.manifest",
971              "schemaVersion": "0.1.0",
972              "id": "example/native-unsupported-artifact",
973              "version": "0.1.0",
974              "runtimeAbiVersion": "0.1.0",
975              "kind": "native-runtime",
976              "native": {
977                "entrypoint": "skenion_extension_init",
978                "artifacts": [
979                  { "os": "not-this-os", "arch": "not-this-arch", "abi": "c", "path": "libnative.dylib" }
980                ]
981              },
982              "provides": {},
983              "permissions": []
984            }"#,
985        );
986
987        let unsafe_artifact_dir = temp_dir("native-unsafe-artifact");
988        write_manifest(
989            &unsafe_artifact_dir,
990            &format!(
991                r#"{{
992                  "schema": "skenion.extension.manifest",
993                  "schemaVersion": "0.1.0",
994                  "id": "example/native-unsafe-artifact",
995                  "version": "0.1.0",
996                  "runtimeAbiVersion": "0.1.0",
997                  "kind": "native-runtime",
998                  "native": {{
999                    "entrypoint": "skenion_extension_init",
1000                    "artifacts": [{}]
1001                  }},
1002                  "provides": {{}},
1003                  "permissions": []
1004                }}"#,
1005                current_artifact("../outside/libnative.dylib")
1006            ),
1007        );
1008
1009        let manager = RuntimeExtensionManager::with_package_dirs(vec![
1010            missing_artifact_dir,
1011            unsupported_artifact_dir,
1012            unsafe_artifact_dir,
1013        ]);
1014
1015        let response = manager.list_extensions();
1016        let messages = response
1017            .extensions
1018            .iter()
1019            .flat_map(|extension| extension.diagnostics.iter())
1020            .map(|diagnostic| diagnostic.message.as_str())
1021            .collect::<Vec<_>>();
1022
1023        assert!(!response.ok);
1024        assert!(messages.iter().any(|message| message.contains("bad_init")));
1025        assert!(
1026            messages
1027                .iter()
1028                .any(|message| message.contains("native artifact does not exist"))
1029        );
1030        assert!(
1031            messages
1032                .iter()
1033                .any(|message| message.contains("has no artifact"))
1034        );
1035        assert!(
1036            messages
1037                .iter()
1038                .any(|message| message.contains("must stay inside package directory"))
1039        );
1040    }
1041
1042    #[test]
1043    fn core_package_loads_through_same_package_contract() {
1044        let package_dir = temp_dir("core-package");
1045        fs::create_dir_all(package_dir.join("help")).unwrap();
1046        fs::create_dir_all(package_dir.join("tests")).unwrap();
1047        fs::write(package_dir.join("help/value.md"), "# Value").unwrap();
1048        fs::write(package_dir.join("tests/value.input.json"), "{}").unwrap();
1049        fs::write(package_dir.join("tests/value.expected.json"), "{}").unwrap();
1050        write_manifest(
1051            &package_dir,
1052            r#"{
1053              "schema": "skenion.extension.manifest",
1054              "schemaVersion": "0.1.0",
1055              "id": "skenion/core",
1056              "version": "0.1.0",
1057              "runtimeAbiVersion": "0.1.0",
1058              "kind": "core-package",
1059              "provides": {
1060                "nodes": [
1061                  {
1062                    "schema": "skenion.node.definition",
1063                    "schemaVersion": "0.1.0",
1064                    "id": "core.value",
1065                    "version": "0.1.0",
1066                    "displayName": "Value",
1067                    "category": "Core",
1068                    "ports": [
1069                      { "id": "out", "direction": "output", "type": "number.float", "rate": "control" }
1070                    ],
1071                    "execution": { "model": "value" },
1072                    "state": { "persistent": false },
1073                    "permissions": [],
1074                    "capabilities": ["value.number.v0.1"]
1075                  }
1076                ],
1077                "help": [
1078                  { "nodeId": "core.value", "markdownPath": "help/value.md" }
1079                ]
1080              },
1081              "permissions": [],
1082              "tests": [
1083                {
1084                  "id": "value-baseline",
1085                  "kind": "node",
1086                  "target": "core.value",
1087                  "fixturePath": "tests/value.input.json",
1088                  "expectedPath": "tests/value.expected.json"
1089                }
1090              ]
1091            }"#,
1092        );
1093        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
1094
1095        let response = manager.list_extensions();
1096
1097        assert!(response.ok, "{response:?}");
1098        assert_eq!(response.extensions[0].id, "skenion/core");
1099        assert_eq!(
1100            response.extensions[0].status,
1101            RuntimeExtensionStatus::Loaded
1102        );
1103        assert_eq!(response.extensions[0].provided_nodes, vec!["core.value"]);
1104        assert_eq!(response.extensions[0].provided_help, vec!["core.value"]);
1105        assert_eq!(response.extensions[0].test_ids, vec!["value-baseline"]);
1106    }
1107
1108    #[test]
1109    fn native_package_with_artifact_loads_codecs_transports_help_and_tests() {
1110        let package_dir = temp_dir("native-valid");
1111        fs::create_dir_all(package_dir.join("target/release")).unwrap();
1112        fs::create_dir_all(package_dir.join("help")).unwrap();
1113        fs::create_dir_all(package_dir.join("tests")).unwrap();
1114        fs::write(package_dir.join("target/release/libnative.dylib"), "").unwrap();
1115        fs::write(package_dir.join("help/native.md"), "# Native").unwrap();
1116        fs::write(package_dir.join("help/native.graph.json"), "{}").unwrap();
1117        fs::write(package_dir.join("tests/native.input.json"), "{}").unwrap();
1118        fs::write(package_dir.join("tests/native.expected.json"), "{}").unwrap();
1119        write_manifest(
1120            &package_dir,
1121            &format!(
1122                r#"{{
1123                  "schema": "skenion.extension.manifest",
1124                  "schemaVersion": "0.1.0",
1125                  "id": "example/native-valid",
1126                  "version": "0.1.0",
1127                  "runtimeAbiVersion": "0.1.0",
1128                  "kind": "native-runtime",
1129                  "native": {{
1130                    "entrypoint": "skenion_extension_init",
1131                    "artifacts": [{}]
1132                  }},
1133                  "provides": {{
1134                    "codecs": [
1135                      {{
1136                        "id": "example.serial.decode",
1137                        "version": "0.1.0",
1138                        "transportKinds": ["serial"],
1139                        "direction": "decode"
1140                      }}
1141                    ],
1142                    "transports": [
1143                      {{ "id": "example.serial", "version": "0.1.0", "kind": "serial" }}
1144                    ],
1145                    "help": [
1146                      {{
1147                        "nodeId": "example.native",
1148                        "markdownPath": "help/native.md",
1149                        "graphPath": "help/native.graph.json"
1150                      }}
1151                    ]
1152                  }},
1153                  "permissions": ["io.serial"],
1154                  "tests": [
1155                    {{
1156                      "id": "native-baseline",
1157                      "kind": "extension",
1158                      "target": "example/native-valid",
1159                      "fixturePath": "tests/native.input.json",
1160                      "expectedPath": "tests/native.expected.json"
1161                    }}
1162                  ]
1163                }}"#,
1164                current_artifact("target/release/libnative.dylib")
1165            ),
1166        );
1167        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
1168
1169        let response = manager.list_extensions();
1170
1171        assert!(response.ok, "{response:?}");
1172        assert_eq!(
1173            response.extensions[0].status,
1174            RuntimeExtensionStatus::Loaded
1175        );
1176        assert_eq!(
1177            response.extensions[0].provided_codecs,
1178            vec!["example.serial.decode"]
1179        );
1180        assert_eq!(
1181            response.extensions[0].provided_transports,
1182            vec!["example.serial"]
1183        );
1184        assert_eq!(response.extensions[0].provided_help, vec!["example.native"]);
1185        assert_eq!(response.extensions[0].test_ids, vec!["native-baseline"]);
1186    }
1187
1188    #[test]
1189    fn codec_package_can_optionally_declare_native_binding() {
1190        let package_dir = temp_dir("codec-native-valid");
1191        fs::create_dir_all(package_dir.join("target/release")).unwrap();
1192        fs::write(package_dir.join("target/release/libcodec.dylib"), "").unwrap();
1193        write_manifest(
1194            &package_dir,
1195            &format!(
1196                r#"{{
1197                  "schema": "skenion.extension.manifest",
1198                  "schemaVersion": "0.1.0",
1199                  "id": "example/codec-native-valid",
1200                  "version": "0.1.0",
1201                  "runtimeAbiVersion": "0.1.0",
1202                  "kind": "codec",
1203                  "native": {{
1204                    "entrypoint": "skenion_extension_init",
1205                    "artifacts": [{}]
1206                  }},
1207                  "provides": {{
1208                    "codecs": [
1209                      {{
1210                        "id": "example.hid.decode",
1211                        "version": "0.1.0",
1212                        "transportKinds": ["hid"],
1213                        "direction": "decode"
1214                      }}
1215                    ]
1216                  }},
1217                  "permissions": ["io.hid"]
1218                }}"#,
1219                current_artifact("target/release/libcodec.dylib")
1220            ),
1221        );
1222        let manager = RuntimeExtensionManager::with_package_dirs(vec![package_dir]);
1223
1224        let response = manager.list_extensions();
1225
1226        assert!(response.ok, "{response:?}");
1227        assert_eq!(
1228            response.extensions[0].status,
1229            RuntimeExtensionStatus::Loaded
1230        );
1231        assert_eq!(
1232            response.extensions[0].provided_codecs,
1233            vec!["example.hid.decode"]
1234        );
1235    }
1236}