cluaupp 1.5.2 → 2.0.0-beta.1

package/rust/cluaupp/src/main.rs

@@ -0,0 +1,717 @@
+use anyhow::{anyhow, Context, Result};
+use clap::{Parser, Subcommand};
+use notify::{Config as NotifyConfig, Event, EventKind, RecommendedWatcher, RecursiveMode, Watcher};
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use sha2::{Digest, Sha256};
+use std::collections::HashSet;
+use std::ffi::OsStr;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Stdio;
+use std::time::Duration;
+use tokio::io::AsyncWriteExt;
+use tokio::process::Command;
+use tokio::sync::Semaphore;
+use walkdir::WalkDir;
+
+#[derive(Parser)]
+#[command(name = "cluaupp", about = "Cluaupp native orchestrator CLI")]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    Init {
+        #[arg(default_value = ".")]
+        folder: String,
+    },
+    Build {
+        #[arg(default_value = ".")]
+        folder: String,
+        #[arg(long, default_value = "default.project.json")]
+        rojo: String,
+        #[arg(long, default_value_t = true)]
+        incremental: bool,
+        #[arg(short = 'j', long)]
+        jobs: Option<usize>,
+    },
+    Watch {
+        #[arg(default_value = ".")]
+        folder: String,
+        #[arg(long, default_value = "default.project.json")]
+        rojo: String,
+        #[arg(short = 'j', long)]
+        jobs: Option<usize>,
+    },
+    Install {
+        #[arg(default_value = ".")]
+        _folder: String,
+    },
+    UpdateTypes {
+        #[arg(default_value = ".")]
+        folder: String,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct ProjectConfig {
+    #[serde(default = "default_root_dir", rename = "rootDir")]
+    root_dir: String,
+    #[serde(default = "default_out_dir", rename = "outDir")]
+    out_dir: String,
+    #[serde(default)]
+    strict: bool,
+}
+
+#[derive(Debug, Deserialize)]
+struct ManifestToml {
+    compiler: Option<ManifestCompiler>,
+    dependencies: Option<HashMapToml>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ManifestCompiler {
+    #[serde(default, rename = "root_dir")]
+    root_dir: Option<String>,
+    #[serde(default, rename = "out_dir")]
+    out_dir: Option<String>,
+    #[serde(default)]
+    strict: Option<bool>,
+}
+
+type HashMapToml = std::collections::BTreeMap<String, toml::Value>;
+
+fn default_root_dir() -> String {
+    "Src".to_string()
+}
+
+fn default_out_dir() -> String {
+    "out".to_string()
+}
+
+#[derive(Debug, Deserialize)]
+struct CompileArtifact {
+    ok: bool,
+    luau: String,
+    #[serde(default, rename = "fileName")]
+    file_name: String,
+    #[serde(default)]
+    error: String,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+struct CacheEntry {
+    source_hash: String,
+    out_rel: String,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+    match cli.command {
+        Commands::Init { folder } => {
+            let dest = std::env::current_dir()?.join(folder);
+            init_project(&dest)?;
+        }
+        Commands::Build {
+            folder,
+            rojo,
+            incremental,
+            jobs,
+        } => {
+            let root = std::env::current_dir()?.join(folder);
+            build_project(&root, &rojo, incremental, jobs).await?;
+        }
+        Commands::Watch { folder, rojo, jobs } => {
+            let root = std::env::current_dir()?.join(folder);
+            watch_project(root, rojo, jobs).await?;
+        }
+        Commands::Install { .. } => {
+            install_dependencies(std::env::current_dir()?.as_path())?;
+        }
+        Commands::UpdateTypes { folder } => {
+            let root = std::env::current_dir()?.join(folder);
+            let status = Command::new("node")
+                .arg("generated/cli.js")
+                .arg("api")
+                .arg("generate")
+                .current_dir(&root)
+                .status()
+                .await
+                .context("failed to run node generated/cli.js api generate")?;
+            if !status.success() {
+                return Err(anyhow!("cluaupp update-types failed"));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn init_project(dest: &Path) -> Result<()> {
+    let home = cluaupp_home()?;
+    let template = home.join("templates").join("game");
+    let include = home.join("include");
+    let runtime = home.join("runtime");
+
+    copy_dir_all(&template, dest)?;
+    copy_dir_all(&include, &dest.join("include"))?;
+    if runtime.exists() {
+        copy_dir_all(&runtime, &dest.join("libs"))?;
+    }
+
+    let cfg = load_config(dest)?;
+    sync_rojo_tree(dest, &cfg, "default.project.json")?;
+    println!("Cluaupp ready in {}", dest.display());
+    Ok(())
+}
+
+fn install_dependencies(root: &Path) -> Result<()> {
+    let libs_root = dirs_home()?.join(".clpp").join("libs");
+    fs::create_dir_all(&libs_root)?;
+    let manifest = root.join("clpp.toml");
+    if !manifest.exists() {
+        println!("cluaupp install: no clpp.toml, created {}", libs_root.display());
+        return Ok(());
+    }
+    let parsed: ManifestToml = toml::from_str(&fs::read_to_string(&manifest)?)?;
+    let deps = parsed.dependencies.unwrap_or_default();
+    if deps.is_empty() {
+        println!("cluaupp install: no [dependencies] in clpp.toml");
+        return Ok(());
+    }
+    for (name, value) in deps {
+        let dep_dir = libs_root.join(&name);
+        fs::create_dir_all(&dep_dir)?;
+        let marker = dep_dir.join(".source");
+        fs::write(marker, value.to_string())?;
+        println!("cluaupp install: linked {name}");
+    }
+    Ok(())
+}
+
+async fn build_project(root: &Path, rojo: &str, incremental: bool, jobs: Option<usize>) -> Result<()> {
+    let cfg = load_config(root)?;
+    let src_dir = root.join(&cfg.root_dir);
+    let out_dir = root.join(&cfg.out_dir);
+    fs::create_dir_all(&out_dir)?;
+    sync_rojo_tree(root, &cfg, rojo)?;
+
+    let files = collect_sources(&src_dir);
+    if files.is_empty() {
+        return Err(anyhow!("no .clpp/.clp/.clh files in {}", src_dir.display()));
+    }
+
+    let clpp_bin = resolve_clpp_bin();
+    let jobs = jobs.unwrap_or_else(|| std::thread::available_parallelism().map(|n| n.get()).unwrap_or(4));
+    let sem = std::sync::Arc::new(Semaphore::new(jobs.max(1)));
+
+    let mut tasks = Vec::new();
+    for file in files {
+        let permit = sem.clone().acquire_owned().await?;
+        let root = root.to_path_buf();
+        let src_dir = src_dir.clone();
+        let out_dir = out_dir.clone();
+        let cfg = cfg.clone();
+        let clpp_bin = clpp_bin.clone();
+        let file_path = file.clone();
+        let rojo_name = rojo.to_string();
+        tasks.push(tokio::spawn(async move {
+            let _permit = permit;
+            compile_one(&root, &src_dir, &out_dir, &cfg, &clpp_bin, &file_path, incremental, &rojo_name).await
+        }));
+    }
+
+    for task in tasks {
+        task.await??;
+    }
+
+    sync_rojo_tree(root, &cfg, rojo)?;
+    Ok(())
+}
+
+async fn watch_project(root: PathBuf, rojo: String, jobs: Option<usize>) -> Result<()> {
+    let cfg = load_config(&root)?;
+    let src_dir = root.join(&cfg.root_dir);
+    if !src_dir.exists() {
+        fs::create_dir_all(&src_dir)?;
+    }
+
+    build_project(&root, &rojo, true, jobs).await?;
+    println!("cluaupp watch {}", src_dir.display());
+
+    let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<Event>();
+    let mut watcher = RecommendedWatcher::new(
+        move |res| {
+            if let Ok(event) = res {
+                let _ = tx.send(event);
+            }
+        },
+        NotifyConfig::default(),
+    )?;
+    watcher.watch(&src_dir, RecursiveMode::Recursive)?;
+
+    while let Some(first) = rx.recv().await {
+        if !is_relevant_event(&first.kind) {
+            continue;
+        }
+        let debounce = Duration::from_millis(350);
+        loop {
+            match tokio::time::timeout(debounce, rx.recv()).await {
+                Ok(Some(next)) if is_relevant_event(&next.kind) => continue,
+                _ => break,
+            }
+        }
+        if let Err(err) = build_project(&root, &rojo, true, jobs).await {
+            eprintln!("{err}");
+        }
+    }
+    Ok(())
+}
+
+fn is_relevant_event(kind: &EventKind) -> bool {
+    matches!(
+        kind,
+        EventKind::Create(_) | EventKind::Modify(_) | EventKind::Remove(_) | EventKind::Any
+    )
+}
+
+async fn compile_one(
+    root: &Path,
+    src_dir: &Path,
+    out_dir: &Path,
+    cfg: &ProjectConfig,
+    clpp_bin: &str,
+    file_path: &Path,
+    incremental: bool,
+    _rojo: &str,
+) -> Result<()> {
+    let rel = normalize(pathdiff(file_path, src_dir)?);
+    let source = fs::read_to_string(file_path)?;
+    let source_hash = fingerprint_source_with_deps(&source, file_path, src_dir, cfg);
+    let out_rel = to_luau_path(&rel);
+    let out_file = out_dir.join(&out_rel);
+    let cache_file = cache_file_for(root, &rel);
+
+    if incremental
+        && cache_file.exists()
+        && out_file.exists()
+        && is_cache_hit(&cache_file, &source_hash, &out_rel)?
+    {
+        return Ok(());
+    }
+
+    let request = json!({
+        "source": source,
+        "fileName": normalize(file_path.to_path_buf()),
+        "strict": cfg.strict,
+        "optimize": true
+    });
+
+    let mut cmd = Command::new(clpp_bin);
+    cmd.arg("api")
+        .arg("compile")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .current_dir(root);
+    let mut child = cmd.spawn().context("failed to spawn clpp api compile")?;
+    if let Some(stdin) = child.stdin.as_mut() {
+        stdin.write_all(request.to_string().as_bytes()).await?;
+    }
+    let output = child.wait_with_output().await?;
+    if !output.status.success() {
+        return Err(anyhow!(
+            "{}",
+            String::from_utf8_lossy(&output.stderr).trim().to_string()
+        ));
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
+    let artifact: CompileArtifact = serde_json::from_str(stdout.trim())
+        .with_context(|| format!("invalid clpp artifact for {rel}"))?;
+    if !artifact.ok {
+        let message = if !artifact.error.is_empty() {
+            artifact.error
+        } else {
+            format!("clpp compile failed for {}", artifact.file_name)
+        };
+        return Err(anyhow!(message));
+    }
+
+    let mut luau = artifact.luau;
+    luau = rewrite_clpp_libs(luau);
+    luau = rewrite_game_rooted_requires(luau);
+    luau = ensure_game_services(luau);
+    if cfg.strict && !luau.starts_with("--!strict") {
+        luau = format!("--!strict\n{luau}");
+    }
+
+    if let Some(parent) = out_file.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    fs::write(&out_file, luau)?;
+    write_cache(&cache_file, &CacheEntry { source_hash, out_rel })?;
+    println!("cluaupp: {} -> {}", rel, normalize(pathdiff(&out_file, root)?));
+    Ok(())
+}
+
+fn rewrite_clpp_libs(input: String) -> String {
+    let re = Regex::new(r#"require\(ClppLibs\.([A-Za-z_][A-Za-z0-9_]*)\)"#).expect("regex");
+    re.replace_all(&input, r#"require(ReplicatedStorage.CluauppLibs.$1)"#)
+        .to_string()
+}
+
+fn rewrite_game_rooted_requires(input: String) -> String {
+    let mut next = input;
+    let services = [
+        "ReplicatedStorage",
+        "ReplicatedFirst",
+        "ServerScriptService",
+        "ServerStorage",
+        "StarterPlayer",
+        "StarterGui",
+        "Workspace",
+    ];
+    for svc in services {
+        let re = Regex::new(&format!(r"script(?:\.Parent)+\.{}\.", svc)).expect("regex");
+        next = re.replace_all(&next, format!("{svc}.")).to_string();
+    }
+    for folder in ["Include", "Modules", "Declarations"] {
+        let re = Regex::new(&format!(r"script(?:\.Parent)+\.{}\.", folder)).expect("regex");
+        next = re
+            .replace_all(&next, format!("ReplicatedStorage.{folder}."))
+            .to_string();
+    }
+    next
+}
+
+fn ensure_game_services(input: String) -> String {
+    let mut needed = Vec::new();
+    for svc in [
+        "ReplicatedStorage",
+        "ReplicatedFirst",
+        "ServerScriptService",
+        "ServerStorage",
+        "StarterPlayer",
+    ] {
+        let need = Regex::new(&format!(r"require\({}\.", svc))
+            .expect("regex")
+            .is_match(&input);
+        let has = Regex::new(&format!(r#"GetService\(\s*"{}"\s*\)"#, svc))
+            .expect("regex")
+            .is_match(&input);
+        if need && !has {
+            needed.push(svc);
+        }
+    }
+    if needed.is_empty() {
+        return input;
+    }
+
+    let block = needed
+        .iter()
+        .map(|svc| format!(r#"const {} = game:GetService("{}")"#, svc, svc))
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    let mut lines = input.lines().collect::<Vec<_>>();
+    let mut insert_at = 0usize;
+    while insert_at < lines.len() && lines[insert_at].starts_with("--") {
+        insert_at += 1;
+    }
+    lines.insert(insert_at, "");
+    lines.insert(insert_at + 1, &block);
+    lines.join("\n")
+}
+
+fn is_cache_hit(cache_file: &Path, source_hash: &str, out_rel: &str) -> Result<bool> {
+    let text = fs::read_to_string(cache_file)?;
+    let cached: CacheEntry = serde_json::from_str(&text)?;
+    Ok(cached.source_hash == source_hash && cached.out_rel == out_rel)
+}
+
+fn write_cache(path: &Path, entry: &CacheEntry) -> Result<()> {
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    fs::write(path, serde_json::to_vec(entry)?)?;
+    Ok(())
+}
+
+fn cache_file_for(root: &Path, rel: &str) -> PathBuf {
+    let key = hex_sha(rel.as_bytes());
+    root.join(".cluaupp")
+        .join("compile-cache")
+        .join(format!("{key}.json"))
+}
+
+fn fingerprint_source_with_deps(source: &str, file_path: &Path, src_dir: &Path, cfg: &ProjectConfig) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(cfg.strict.to_string().as_bytes());
+    hasher.update(source.as_bytes());
+    for dep in resolve_language_deps(source, file_path, src_dir) {
+        hasher.update(dep.to_string_lossy().as_bytes());
+        if let Ok(content) = fs::read(&dep) {
+            hasher.update(content);
+        }
+    }
+    hex_bytes(&hasher.finalize())
+}
+
+fn resolve_language_deps(source: &str, file_path: &Path, src_dir: &Path) -> Vec<PathBuf> {
+    let mut deps = Vec::new();
+    let mut seen = HashSet::new();
+    let link_re = Regex::new(r#"(?m)^\s*link\s+["']([^"']+)["'](?:\s+as\s+[A-Za-z_][A-Za-z0-9_]*)?\s*;?\s*$"#)
+        .expect("regex");
+
+    for cap in link_re.captures_iter(source) {
+        if let Some(path_match) = cap.get(1) {
+            if let Some(dep) = resolve_dep(path_match.as_str(), file_path, src_dir) {
+                let key = normalize(dep.clone());
+                if seen.insert(key) {
+                    deps.push(dep);
+                }
+            }
+        }
+    }
+    deps
+}
+
+fn resolve_dep(raw: &str, from_file: &Path, src_dir: &Path) -> Option<PathBuf> {
+    let from_dir = from_file.parent()?;
+    let candidates = [
+        from_dir.join(raw),
+        src_dir.join(raw),
+        from_dir.join(format!("{raw}.clh")),
+        src_dir.join(format!("{raw}.clh")),
+    ];
+    candidates.into_iter().find(|p| p.is_file())
+}
+
+fn collect_sources(root: &Path) -> Vec<PathBuf> {
+    WalkDir::new(root)
+        .into_iter()
+        .filter_map(|e| e.ok())
+        .filter(|e| e.file_type().is_file())
+        .map(|e| e.into_path())
+        .filter(|p| is_source_file(p.as_path()))
+        .collect()
+}
+
+fn is_source_file(path: &Path) -> bool {
+    matches!(
+        path.extension().and_then(OsStr::to_str).map(|v| v.to_ascii_lowercase()),
+        Some(ext) if ext == "clpp" || ext == "clp" || ext == "clh"
+    )
+}
+
+fn to_luau_path(rel: &str) -> String {
+    Regex::new(r"\.(clpp|clp|clh)$")
+        .expect("regex")
+        .replace(rel, ".luau")
+        .to_string()
+}
+
+fn load_config(root: &Path) -> Result<ProjectConfig> {
+    let manifest = root.join("clpp.toml");
+    if manifest.exists() {
+        let parsed: ManifestToml = toml::from_str(&fs::read_to_string(&manifest)?)?;
+        if let Some(compiler) = parsed.compiler {
+            return Ok(ProjectConfig {
+                root_dir: compiler.root_dir.unwrap_or_else(default_root_dir),
+                out_dir: compiler.out_dir.unwrap_or_else(default_out_dir),
+                strict: compiler.strict.unwrap_or(false),
+            });
+        }
+    }
+    let cfg1 = root.join("cluaupp.config.json");
+    let cfg2 = root.join("cluau.config.json");
+    if cfg1.exists() {
+        let parsed: ProjectConfig = serde_json::from_str(&fs::read_to_string(&cfg1)?)?;
+        return Ok(parsed);
+    }
+    if cfg2.exists() {
+        let parsed: ProjectConfig = serde_json::from_str(&fs::read_to_string(&cfg2)?)?;
+        return Ok(parsed);
+    }
+    Ok(ProjectConfig {
+        root_dir: default_root_dir(),
+        out_dir: default_out_dir(),
+        strict: false,
+    })
+}
+
+fn sync_rojo_tree(root: &Path, cfg: &ProjectConfig, rojo_file: &str) -> Result<()> {
+    let tree = build_rojo_tree(root, &cfg.root_dir, &cfg.out_dir)?;
+    let doc = json!({
+        "name": "cluaupp-game",
+        "tree": tree
+    });
+    fs::write(root.join(rojo_file), format!("{}\n", serde_json::to_string_pretty(&doc)?))?;
+    Ok(())
+}
+
+fn build_rojo_tree(root: &Path, root_dir: &str, out_dir: &str) -> Result<serde_json::Value> {
+    let out_root = root.join(out_dir);
+    let src_root = root.join(root_dir);
+    let source_root = if out_root.exists() { out_root } else { src_root };
+    let rel_root = normalize(pathdiff(&source_root, root)?);
+
+    let mut tree = json!({
+        "$className": "DataModel",
+        "ServerScriptService": { "$className": "ServerScriptService", "$path": format!("{}/Server", rel_root) },
+        "ReplicatedStorage": {
+            "$className": "ReplicatedStorage",
+            "CluauppLibs": { "$path": "libs" },
+            "Declarations": { "$path": format!("{}/Declarations", rel_root) },
+            "Include": { "$path": format!("{}/Include", rel_root) },
+        },
+        "StarterPlayer": {
+            "$className": "StarterPlayer",
+            "StarterPlayerScripts": {
+                "$className": "StarterPlayerScripts",
+                "$path": format!("{}/Client", rel_root)
+            }
+        },
+        "HttpService": {
+            "$className": "HttpService",
+            "$properties": { "HttpEnabled": true }
+        }
+    });
+
+    tree["ServerScriptService"]["Parallel"] = json!({ "$path": format!("{}/Parallel", rel_root) });
+    tree["ServerScriptService"]["Modules"] = json!({});
+    tree["StarterPlayer"]["StarterPlayerScripts"]["Modules"] = json!({});
+    tree["ReplicatedStorage"]["Modules"] = json!({});
+
+    let modules_root = source_root.join("Modules");
+    if modules_root.exists() {
+        for entry in WalkDir::new(&modules_root).into_iter().filter_map(|e| e.ok()) {
+            if !entry.file_type().is_file() {
+                continue;
+            }
+            let file = entry.path();
+            let ext = file.extension().and_then(OsStr::to_str).unwrap_or_default().to_ascii_lowercase();
+            if !["luau", "lua", "clpp", "clp", "clh"].contains(&ext.as_str()) {
+                continue;
+            }
+            let module_rel = normalize(pathdiff(file, &modules_root)?);
+            let stem = module_stem(&module_rel);
+            if stem.is_empty() {
+                continue;
+            }
+            let out_rel = normalize(pathdiff(file, root)?);
+            let is_server = Regex::new(r"\.server\.(luau|lua|clpp|clp|clh)$")
+                .expect("regex")
+                .is_match(&module_rel);
+            let is_client = Regex::new(r"\.client\.(luau|lua|clpp|clp|clh)$")
+                .expect("regex")
+                .is_match(&module_rel);
+            let target = if is_server {
+                &mut tree["ServerScriptService"]["Modules"]
+            } else if is_client {
+                &mut tree["StarterPlayer"]["StarterPlayerScripts"]["Modules"]
+            } else {
+                &mut tree["ReplicatedStorage"]["Modules"]
+            };
+            set_nested_path(target, &stem, &out_rel);
+        }
+    }
+    Ok(tree)
+}
+
+fn module_stem(rel: &str) -> String {
+    let re = Regex::new(r"(\.server|\.client)?\.(luau|lua|clpp|clp|clh)$").expect("regex");
+    re.replace(rel, "").to_string()
+}
+
+fn set_nested_path(node: &mut serde_json::Value, stem: &str, fs_path: &str) {
+    let parts: Vec<&str> = stem.split('/').filter(|p| !p.is_empty()).collect();
+    if parts.is_empty() {
+        return;
+    }
+    let mut cur = node;
+    for part in &parts[..parts.len() - 1] {
+        if cur.get(*part).is_none() {
+            cur[*part] = json!({});
+        }
+        cur = &mut cur[*part];
+    }
+    cur[parts[parts.len() - 1]] = json!({ "$path": fs_path });
+}
+
+fn copy_dir_all(src: &Path, dst: &Path) -> Result<()> {
+    if !src.exists() {
+        return Ok(());
+    }
+    for entry in WalkDir::new(src).into_iter().filter_map(|e| e.ok()) {
+        let rel = entry.path().strip_prefix(src).unwrap_or(entry.path());
+        let target = dst.join(rel);
+        if entry.file_type().is_dir() {
+            fs::create_dir_all(&target)?;
+        } else if entry.file_type().is_file() {
+            if let Some(parent) = target.parent() {
+                fs::create_dir_all(parent)?;
+            }
+            fs::copy(entry.path(), &target)?;
+        }
+    }
+    Ok(())
+}
+
+fn resolve_clpp_bin() -> String {
+    std::env::var("CLPP")
+        .or_else(|_| std::env::var("CLPP_PATH"))
+        .unwrap_or_else(|_| "clpp".to_string())
+}
+
+fn cluaupp_home() -> Result<PathBuf> {
+    if let Ok(home) = std::env::var("CLUAUPP_HOME") {
+        return Ok(PathBuf::from(home));
+    }
+    let exe = std::env::current_exe()?;
+    let base = exe
+        .parent()
+        .and_then(|p| p.parent())
+        .map(|p| p.to_path_buf())
+        .ok_or_else(|| anyhow!("failed to resolve CLUAUPP_HOME"))?;
+    Ok(base)
+}
+
+fn dirs_home() -> Result<PathBuf> {
+    if let Ok(home) = std::env::var("HOME") {
+        return Ok(PathBuf::from(home));
+    }
+    if let Ok(home) = std::env::var("USERPROFILE") {
+        return Ok(PathBuf::from(home));
+    }
+    Err(anyhow!("failed to resolve home directory"))
+}
+
+fn pathdiff(path: &Path, base: &Path) -> Result<PathBuf> {
+    path.strip_prefix(base)
+        .map(|p| p.to_path_buf())
+        .map_err(|_| anyhow!("failed relative path"))
+}
+
+fn normalize(path: PathBuf) -> String {
+    path.to_string_lossy().replace('\\', "/")
+}
+
+fn hex_sha(bytes: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(bytes);
+    hex_bytes(&hasher.finalize())
+}
+
+fn hex_bytes(bytes: &[u8]) -> String {
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for b in bytes {
+        out.push_str(&format!("{:02x}", b));
+    }
+    out
+}