Skip to main content

qualia_client_core/
bundled_qapps.rs

1//! Seed qapps shipped beside the desktop executable into `{storage}/Qapps/`.
2//!
3//! Release bundles place packages under `{exe}/bundled/qapps/{Name}/`.
4//! Dev builds resolve `bundled/qapps/{Name}/`, then gitignored `app-development/{Name}/`.
5
6use std::fs;
7use std::path::{Path, PathBuf};
8
9use serde::Serialize;
10
11use crate::qapp_paths::{ensure_qapps_dir, qapps_dir, resolve_package_manifest_path};
12use crate::qapp_registry::QAPP_PACKAGE_MANIFEST;
13use crate::qapp_version::{is_version_newer, normalize_version_label};
14
15/// Default qapps copied on first launch when absent from user storage.
16pub const DEFAULT_BUNDLED_QAPPS: &[&str] = &[
17    "Anatomy",
18    "Poet",
19    "Wallet",
20    "Projects",
21    "Library",
22    "LlmAgents",
23    "CommsDirectory",
24    "Browser",
25];
26
27/// Version + update offer for an installed qapp.
28#[derive(Debug, Clone, Serialize)]
29pub struct QappVersionStatus {
30    pub qapp_name: String,
31    pub installed: bool,
32    pub installed_version: Option<String>,
33    pub offered_version: Option<String>,
34    pub update_available: bool,
35    /// `bundled` | `external` | `none`
36    pub offer_source: String,
37    pub message: String,
38}
39
40fn exe_dir() -> Option<PathBuf> {
41    std::env::current_exe()
42        .ok()
43        .and_then(|p| p.parent().map(|d| d.to_path_buf()))
44}
45
46fn has_valid_manifest(dir: &Path) -> bool {
47    resolve_package_manifest_path(dir).is_some_and(|p| p.is_file())
48}
49
50/// Read `version` from a qapp package directory's manifest.
51pub fn read_qapp_version_from_dir(qapp_dir: &Path) -> Option<String> {
52    let manifest_path = resolve_package_manifest_path(qapp_dir)?;
53    let content = fs::read_to_string(manifest_path).ok()?;
54    let manifest: crate::qapp_registry::QappPackageManifest =
55        serde_json::from_str(&content).ok()?;
56    Some(normalize_version_label(&manifest.version))
57}
58
59/// Resolve bundled source for a qapp directory name (e.g. `"Anatomy"`).
60pub fn resolve_bundled_qapp_source(qapp_name: &str) -> Option<PathBuf> {
61    if let Ok(extra) = std::env::var("QUALIA_BUNDLED_QAPPS_DIR") {
62        let candidate = PathBuf::from(extra).join(qapp_name);
63        if has_valid_manifest(&candidate) {
64            return Some(candidate);
65        }
66    }
67
68    if let Some(root) = exe_dir() {
69        for rel in [
70            format!("bundled/qapps/{qapp_name}"),
71            format!("qapps/{qapp_name}"),
72            format!("bundled/{qapp_name}"),
73        ] {
74            let candidate = root.join(&rel);
75            if has_valid_manifest(&candidate) {
76                return Some(candidate);
77            }
78        }
79    }
80
81    let repo_root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
82    for rel in [
83        format!("bundled/qapps/{qapp_name}"),
84        format!("app-development/{qapp_name}"),
85    ] {
86        let candidate = repo_root.join(&rel);
87        if has_valid_manifest(&candidate) {
88            return Some(candidate);
89        }
90    }
91
92    None
93}
94
95/// Installed qapp version.
96pub fn installed_qapp_version(storage_path: &Path, qapp_name: &str) -> Option<String> {
97    let dir = qapps_dir(storage_path).join(qapp_name);
98    if dir.join(QAPP_PACKAGE_MANIFEST).is_file() {
99        read_qapp_version_from_dir(&dir)
100    } else {
101        None
102    }
103}
104
105/// Bundled offered version.
106pub fn bundled_offered_version(qapp_name: &str) -> Option<String> {
107    resolve_bundled_qapp_source(qapp_name).and_then(|p| read_qapp_version_from_dir(&p))
108}
109
110/// Read `did_git` multi-repo identifier and `export_targets` from a bundled qapp manifest.
111pub fn bundled_qapp_repo_info(qapp_name: &str) -> Option<(String, Vec<String>)> {
112    let source_dir = resolve_bundled_qapp_source(qapp_name)?;
113    let manifest_path = resolve_package_manifest_path(&source_dir)?;
114    let content = fs::read_to_string(manifest_path).ok()?;
115    let manifest: crate::qapp_registry::QappPackageManifest =
116        serde_json::from_str(&content).ok()?;
117    let x_qualia = manifest.x_qualia?;
118    let did_git = x_qualia.did_git?;
119    Some((did_git, x_qualia.export_targets))
120}
121
122fn build_version_status(
123    qapp_name: &str,
124    installed_version: Option<String>,
125    offered_version: Option<String>,
126    offer_source: &str,
127) -> QappVersionStatus {
128    let installed = installed_version.is_some();
129    let update_available = match (&installed_version, &offered_version) {
130        (Some(inst), Some(off)) => is_version_newer(off, inst),
131        (None, Some(_)) => true,
132        _ => false,
133    };
134
135    let message = match (&installed_version, &offered_version, update_available) {
136        (None, Some(off), true) => format!("Install qapp {qapp_name} v{off} from {offer_source}."),
137        (Some(inst), Some(off), true) => {
138            format!("Update available: v{inst} → v{off} ({offer_source}).")
139        }
140        (Some(inst), None, false) => format!("Installed v{inst}; no newer package found."),
141        (Some(inst), Some(off), false) if inst == off => {
142            format!("Up to date at v{inst}.")
143        }
144        (Some(inst), Some(off), false) => {
145            format!("Installed v{inst}; bundled/external offer v{off} is not newer.")
146        }
147        (None, None, false) => {
148            format!("{qapp_name} is not installed and no package source was found.")
149        }
150        _ => format!("{qapp_name} version status evaluated."),
151    };
152
153    QappVersionStatus {
154        qapp_name: qapp_name.to_string(),
155        installed,
156        installed_version,
157        offered_version,
158        update_available,
159        offer_source: offer_source.to_string(),
160        message,
161    }
162}
163
164/// Compare installed copy against the bundled/desktop-shipped package.
165pub fn check_bundled_qapp_update(qapp_name: &str, storage_path: &Path) -> QappVersionStatus {
166    let installed_version = installed_qapp_version(storage_path, qapp_name);
167    let offered_version = bundled_offered_version(qapp_name);
168    build_version_status(qapp_name, installed_version, offered_version, "bundled")
169}
170
171/// Compare installed copy against an external directory (manual install / dev tree).
172pub fn check_qapp_update_from_source(
173    qapp_name: &str,
174    storage_path: &Path,
175    source_dir: &Path,
176) -> Result<QappVersionStatus, String> {
177    if !has_valid_manifest(source_dir) {
178        return Err(format!("qapp.json not found in {}", source_dir.display()));
179    }
180    let offered_version = read_qapp_version_from_dir(source_dir)
181        .ok_or_else(|| "Could not read version from source qapp.json".to_string())?;
182    let installed_version = installed_qapp_version(storage_path, qapp_name);
183    Ok(build_version_status(
184        qapp_name,
185        installed_version,
186        Some(offered_version),
187        "external",
188    ))
189}
190
191/// List update offers for installed qapps and default bundled catalog entries.
192pub fn list_bundled_qapp_updates(storage_path: &Path) -> Vec<QappVersionStatus> {
193    let mut names = Vec::new();
194    let qapps_root = qapps_dir(storage_path);
195    if let Ok(entries) = fs::read_dir(&qapps_root) {
196        for entry in entries.filter_map(Result::ok) {
197            if entry.path().is_dir() {
198                names.push(entry.file_name().to_string_lossy().to_string());
199            }
200        }
201    }
202    for name in DEFAULT_BUNDLED_QAPPS {
203        if !names.iter().any(|n| n == *name) {
204            names.push((*name).to_string());
205        }
206    }
207
208    let mut reports: Vec<QappVersionStatus> = names
209        .iter()
210        .map(|name| check_bundled_qapp_update(name, storage_path))
211        .collect();
212    reports.sort_by(|a, b| a.qapp_name.cmp(&b.qapp_name));
213    reports
214}
215
216/// Copy bundled qapp into `{storage}/Qapps/{name}` when not already installed.
217pub fn seed_qapp_if_missing(
218    storage_path: impl AsRef<Path>,
219    qapp_name: &str,
220) -> Result<bool, String> {
221    let storage = storage_path.as_ref();
222    let dest = qapps_dir(storage).join(qapp_name);
223    if dest.join(QAPP_PACKAGE_MANIFEST).is_file() {
224        return Ok(false);
225    }
226
227    let source = resolve_bundled_qapp_source(qapp_name)
228        .ok_or_else(|| format!("Bundled qapp source not found for {qapp_name}"))?;
229
230    crate::qapp_install::install_package_atomic(
231        storage,
232        &source,
233        crate::qapp_install::InstallPolicy::Development,
234        None,
235    )
236    .map_err(|e| e.to_string())?;
237    Ok(true)
238}
239
240/// Replace an installed qapp with files from `source_dir` and re-register capabilities.
241pub fn upgrade_qapp_from_source(
242    storage_path: &Path,
243    qapp_name: &str,
244    source_dir: &Path,
245) -> Result<String, String> {
246    if !has_valid_manifest(source_dir) {
247        return Err(format!("qapp.json not found in {}", source_dir.display()));
248    }
249
250    let manifest = crate::api::load_qapp_package_from_dir(source_dir)
251        .map_err(|e| format!("Invalid source manifest: {e}"))?;
252    if manifest.name != qapp_name {
253        return Err(format!(
254            "Source manifest name '{}' does not match expected '{}'",
255            manifest.name, qapp_name
256        ));
257    }
258
259    let previous = installed_qapp_version(storage_path, qapp_name);
260    let next = normalize_version_label(&manifest.version);
261    let entry = crate::qapp_install::install_package_atomic(
262        storage_path,
263        source_dir,
264        crate::qapp_install::InstallPolicy::Development,
265        None,
266    )
267    .map_err(|e| e.to_string())?;
268
269    let _ = crate::qapp_manifest::install_qapp_capabilities(&manifest);
270    let _ = entry;
271
272    Ok(match previous {
273        Some(old) => format!("Upgraded {qapp_name} v{old} → v{next}"),
274        None => format!("Installed {qapp_name} v{next}"),
275    })
276}
277
278/// Apply a bundled update when a newer version is available.
279pub fn apply_bundled_qapp_update(storage_path: &Path, qapp_name: &str) -> Result<String, String> {
280    let status = check_bundled_qapp_update(qapp_name, storage_path);
281    if !status.update_available {
282        return Err(status.message);
283    }
284    let source = resolve_bundled_qapp_source(qapp_name)
285        .ok_or_else(|| format!("Bundled qapp source not found for {qapp_name}"))?;
286    upgrade_qapp_from_source(storage_path, qapp_name, &source)
287}
288
289fn register_default_capabilities(_storage_path: &Path) {
290    for name in DEFAULT_BUNDLED_QAPPS {
291        if let Ok(manifest) = crate::api::load_installed_qapp_package(name) {
292            let _ = crate::qapp_manifest::install_qapp_capabilities(&manifest);
293        } else if let Some(src) = resolve_bundled_qapp_source(name) {
294            if let Ok(manifest) = crate::api::load_qapp_package_from_dir(&src) {
295                let _ = crate::qapp_manifest::install_qapp_capabilities(&manifest);
296            }
297        }
298    }
299}
300
301/// Seed all default bundled qapps and register Anatomy capabilities when present.
302pub fn seed_bundled_qapps() -> Result<Vec<String>, String> {
303    let state = crate::state::APP_STATE
304        .get()
305        .ok_or("APP_STATE not initialized")?;
306    let storage = state
307        .config
308        .lock()
309        .map_err(|e| e.to_string())?
310        .storage_path
311        .clone();
312    let storage_path = PathBuf::from(&storage);
313    let _ = ensure_qapps_dir(&storage_path).map_err(|e| e.to_string())?;
314
315    let mut seeded = Vec::new();
316    for name in DEFAULT_BUNDLED_QAPPS {
317        match seed_qapp_if_missing(&storage_path, name) {
318            Ok(true) => seeded.push((*name).to_string()),
319            Ok(false) => {}
320            Err(e) => eprintln!("[bundled_qapps] skip {name}: {e}"),
321        }
322    }
323
324    register_default_capabilities(&storage_path);
325    let _ = crate::qapp_install::reconcile_registry_with_disk(&storage_path);
326
327    for offer in list_bundled_qapp_updates(&storage_path) {
328        if offer.update_available {
329            eprintln!(
330                "[bundled_qapps] update available for {}: {}",
331                offer.qapp_name, offer.message
332            );
333        }
334    }
335
336    Ok(seeded)
337}
338
339#[cfg(test)]
340mod tests {
341    use super::*;
342
343    #[test]
344    fn tracked_anatomy_source_resolves_when_present() {
345        let tracked =
346            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../bundled/qapps/Anatomy/qapp.json");
347        if tracked.is_file() {
348            let src = resolve_bundled_qapp_source("Anatomy");
349            assert!(src.is_some(), "expected bundled Anatomy path");
350        }
351    }
352
353    #[test]
354    fn anatomy_manifest_version_reads_when_present() {
355        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
356        let anatomy = root.join("bundled/qapps/Anatomy");
357        if !anatomy.join("qapp.json").is_file() {
358            return;
359        }
360        let v = read_qapp_version_from_dir(&anatomy);
361        assert_eq!(v.as_deref(), Some("0.0.12"));
362    }
363
364    #[test]
365    fn default_bundled_qapps_manifests_resolve_and_validate() {
366        for name in DEFAULT_BUNDLED_QAPPS {
367            let src = resolve_bundled_qapp_source(name)
368                .unwrap_or_else(|| panic!("expected bundled source for {name}"));
369            let manifest_path = src.join("qapp.json");
370            assert!(manifest_path.is_file(), "qapp.json missing for {name}");
371            let content = fs::read_to_string(&manifest_path)
372                .unwrap_or_else(|e| panic!("failed to read qapp.json for {name}: {e}"));
373            let manifest: crate::qapp_registry::QappPackageManifest = serde_json::from_str(&content)
374                .unwrap_or_else(|e| panic!("failed to parse qapp.json for {name}: {e}"));
375            assert_eq!(&manifest.name, *name, "manifest name mismatch for {name}");
376            assert!(!manifest.version.is_empty(), "version empty for {name}");
377            let x = manifest
378                .x_qualia
379                .as_ref()
380                .unwrap_or_else(|| panic!("missing x_qualia for {name}"));
381            if *name != "Anatomy" {
382                assert!(x.did_git.is_some(), "missing did_git for {name}");
383                assert!(!x.export_targets.is_empty(), "missing export_targets for {name}");
384            }
385        }
386    }
387}