astrid_core/

dirs.rs

//! Directory scaffolding for Astrid home and workspace directories.
//!
//! Two key directory structures:
//!
//! - [`AstridHome`]: Global state at `~/.astrid/` (or `$ASTRID_HOME`).
//!   Linux FHS-aligned layout with `etc/`, `var/`, `run/`, `log/`, `keys/`,
//!   `bin/`, `lib/`, and `home/` for multi-principal isolation.
//!
//! - [`WorkspaceDir`]: Per-project directory at `<project>/.astrid/`.
//!   Holds only committable project-level config (like `.astrid/ASTRID.md`).
//!   Contains a `workspace-id` UUID that links the project to its global state.
//!
//! - [`PrincipalHome`]: Per-principal home directory under `~/.astrid/home/{id}/`.
//!   Each principal gets isolated capsules, KV data, audit chain, tokens, and
//!   config — portable across deployments.
//!
//! # Layout
//!
//! ```text
//! ~/.astrid/                           (AstridHome)
//! ├── etc/
//! │   ├── config.toml                    deployment config
//! │   ├── servers.toml                   MCP server config
//! │   ├── gateway.toml                   daemon config
//! │   ├── hooks/                         system hooks
//! │   └── layout-version                 layout version sentinel
//! ├── var/
//! │   └── state.db/                      system KV (SurrealKV, persistent)
//! ├── run/                               ephemeral runtime state
//! │   ├── system.sock
//! │   ├── system.token
//! │   ├── system.ready
//! │   └── deferred.db/                   deferred queue (ephemeral)
//! ├── log/                               system logs
//! ├── keys/                              runtime signing key
//! ├── bin/                               content-addressed compiled WASM binaries
//! ├── lib/                               shared WASM component libraries (WIT, future)
//! └── home/
//!     └── {principal}/                   per-principal home
//!         ├── .local/
//!         │   ├── capsules/              user-installed capsules
//!         │   ├── kv/                    capsule KV data
//!         │   ├── log/                   capsule logs
//!         │   ├── audit/                 user's audit chain
//!         │   ├── tokens/                capability tokens
//!         │   └── tmp/                   VFS mounts as /tmp
//!         └── .config/
//!             └── env/                   capsule config overrides
//!
//! <project>/.astrid/                   (WorkspaceDir)
//! ├── workspace-id                       UUID linking project to global state
//! └── ASTRID.md                        project-level instructions
//! ```

use std::io;
use std::path::{Component, Path, PathBuf};

use uuid::Uuid;

use crate::principal::PrincipalId;

/// Current layout version. Written to `etc/layout-version` on first boot.
pub const LAYOUT_VERSION: &str = "1";

/// Reject paths containing `..` (parent directory) components.
fn reject_parent_traversal(path: &Path, var_name: &str) -> io::Result<()> {
    if path.components().any(|c| matches!(c, Component::ParentDir)) {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!("{var_name} must not contain '..' path components"),
        ));
    }
    Ok(())
}

// ── AstridHome (system-level) ────────────────────────────────────────────

/// Global Astrid home directory (`~/.astrid/` or `$ASTRID_HOME`).
///
/// FHS-aligned system layout. Contains config (`etc/`), persistent state
/// (`var/`), ephemeral runtime (`run/`), logs (`log/`), keys (`keys/`),
/// shared WASM modules (`lib/`), system capsules (`capsules/`), and
/// per-principal home directories (`home/`).
#[derive(Debug, Clone)]
pub struct AstridHome {
    root: PathBuf,
}

impl AstridHome {
    /// Resolve the home directory.
    ///
    /// Checks `$ASTRID_HOME` first, then falls back to `$HOME/.astrid/`.
    ///
    /// # Errors
    ///
    /// Returns an error if neither `$ASTRID_HOME` nor `$HOME` is set.
    pub fn resolve() -> io::Result<Self> {
        let astrid_home = std::env::var("ASTRID_HOME").ok();
        let home = if astrid_home.is_none() {
            std::env::var("HOME").ok()
        } else {
            None
        };
        Self::resolve_with_env(astrid_home, home)
    }

    /// Internal resolver used to mock environment variables in tests securely.
    fn resolve_with_env(astrid_home: Option<String>, home: Option<String>) -> io::Result<Self> {
        let root = if let Some(custom) = astrid_home {
            let p = PathBuf::from(&custom);
            if !p.is_absolute() {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    "ASTRID_HOME must be an absolute path",
                ));
            }
            reject_parent_traversal(&p, "ASTRID_HOME")?;
            p
        } else {
            let home = home.ok_or_else(|| {
                io::Error::new(
                    io::ErrorKind::NotFound,
                    "neither ASTRID_HOME nor HOME environment variable is set",
                )
            })?;
            let home_path = PathBuf::from(&home);
            if !home_path.is_absolute() {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    "HOME must be an absolute path",
                ));
            }
            reject_parent_traversal(&home_path, "HOME")?;
            home_path.join(".astrid")
        };

        Ok(Self { root })
    }

    /// Create from an explicit path (useful for testing).
    #[must_use]
    pub fn from_path(root: impl Into<PathBuf>) -> Self {
        Self { root: root.into() }
    }

    /// Ensure the system directory structure exists with secure permissions.
    ///
    /// Creates `etc/`, `var/`, `run/`, `log/`, `keys/`, `lib/`, and `home/`.
    /// Writes `etc/layout-version` with the current version.
    /// Sets all directories to `0o700` on Unix.
    ///
    /// Note: `capsules/` (system/distro capsules) is NOT created eagerly.
    /// Nothing writes there yet — user installs go to principal home.
    /// It will be created when an operator install mechanism lands.
    ///
    /// # Errors
    ///
    /// Returns an error if directory creation or permission setting fails.
    pub fn ensure(&self) -> io::Result<()> {
        let dirs = [
            self.etc_dir(),
            self.hooks_dir(),
            self.var_dir(),
            self.run_dir(),
            self.log_dir(),
            self.keys_dir(),
            self.bin_dir(),
            self.wit_dir(),
            self.home_dir(),
        ];
        for dir in &dirs {
            std::fs::create_dir_all(dir)?;
        }

        // Write layout version sentinel (idempotent).
        let version_path = self.etc_dir().join("layout-version");
        if !version_path.exists() {
            std::fs::write(&version_path, LAYOUT_VERSION)?;
        }

        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let perms = std::fs::Permissions::from_mode(0o700);
            std::fs::set_permissions(self.root(), perms.clone())?;
            for dir in &dirs {
                std::fs::set_permissions(dir, perms.clone())?;
            }
        }
        Ok(())
    }

    // ── Path accessors ───────────────────────────────────────────────

    /// Root directory path (`~/.astrid/`).
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// Configuration directory (`etc/`).
    #[must_use]
    pub fn etc_dir(&self) -> PathBuf {
        self.root.join("etc")
    }

    /// Path to the global runtime configuration file (`etc/config.toml`).
    #[must_use]
    pub fn config_path(&self) -> PathBuf {
        self.etc_dir().join("config.toml")
    }

    /// Path to the MCP servers configuration file (`etc/servers.toml`).
    #[must_use]
    pub fn servers_config_path(&self) -> PathBuf {
        self.etc_dir().join("servers.toml")
    }

    /// Path to the gateway daemon configuration file (`etc/gateway.toml`).
    #[must_use]
    pub fn gateway_config_path(&self) -> PathBuf {
        self.etc_dir().join("gateway.toml")
    }

    /// System hooks directory (`etc/hooks/`).
    #[must_use]
    pub fn hooks_dir(&self) -> PathBuf {
        self.etc_dir().join("hooks")
    }

    /// Per-principal profile directory (`etc/profiles/`).
    ///
    /// Per-principal `profile.toml` files live here, NOT inside the
    /// principal's own home directory. Profile contents (enabled,
    /// groups, grants, revokes, quotas, auth public keys, egress
    /// policy, process allowlist) are system-managed policy: a capsule
    /// running as a principal with `fs_read = ["home://"]` must not be
    /// able to read its own policy, and `fs_write` must not let it
    /// self-elevate. Keeping profiles under `etc/` puts them outside
    /// the `home://` VFS scheme entirely.
    #[must_use]
    pub fn profiles_dir(&self) -> PathBuf {
        self.etc_dir().join("profiles")
    }

    /// Per-principal profile path (`etc/profiles/{principal}.toml`).
    /// See [`Self::profiles_dir`] for why this lives outside the
    /// principal's home directory.
    #[must_use]
    pub fn profile_path(&self, id: &PrincipalId) -> PathBuf {
        self.profiles_dir().join(format!("{id}.toml"))
    }

    /// Persistent state directory (`var/`).
    #[must_use]
    pub fn var_dir(&self) -> PathBuf {
        self.root.join("var")
    }

    /// Path to the system KV database (`var/state.db/`).
    #[must_use]
    pub fn state_db_path(&self) -> PathBuf {
        self.var_dir().join("state.db")
    }

    /// Ephemeral runtime directory (`run/`).
    #[must_use]
    pub fn run_dir(&self) -> PathBuf {
        self.root.join("run")
    }

    /// Path to the kernel's Unix domain socket (`run/system.sock`).
    #[must_use]
    pub fn socket_path(&self) -> PathBuf {
        self.run_dir().join("system.sock")
    }

    /// Path to the session authentication token (`run/system.token`).
    #[must_use]
    pub fn token_path(&self) -> PathBuf {
        self.run_dir().join("system.token")
    }

    /// Path to the daemon readiness sentinel (`run/system.ready`).
    ///
    /// Written by the daemon after all capsules are loaded and accepting
    /// connections. The CLI polls for this file instead of the socket file
    /// to avoid connecting before the daemon is fully initialized.
    #[must_use]
    pub fn ready_path(&self) -> PathBuf {
        self.run_dir().join("system.ready")
    }

    /// Path to the deferred queue database (`run/deferred.db/`).
    #[must_use]
    pub fn deferred_db_path(&self) -> PathBuf {
        self.run_dir().join("deferred.db")
    }

    /// System log directory (`log/`).
    #[must_use]
    pub fn log_dir(&self) -> PathBuf {
        self.root.join("log")
    }

    /// Secrets directory (`secrets/`).
    ///
    /// File-per-secret store keyed by
    /// `secrets/<scope>/<capsule>/<key>`. `<scope>` is either an
    /// agent principal name (per-agent override) or `__host__` (the
    /// shared / operator-wide value the kernel's secret-resolve path
    /// falls back to). Files are written `0600`, parent dirs `0700`.
    #[must_use]
    pub fn secrets_dir(&self) -> PathBuf {
        self.root.join("secrets")
    }

    /// Keys directory (`keys/`).
    #[must_use]
    pub fn keys_dir(&self) -> PathBuf {
        self.root.join("keys")
    }

    /// Path to the runtime signing key (`keys/runtime.key`).
    #[must_use]
    pub fn runtime_key_path(&self) -> PathBuf {
        self.keys_dir().join("runtime.key")
    }

    /// Content-addressed compiled WASM binaries (`bin/`).
    #[must_use]
    pub fn bin_dir(&self) -> PathBuf {
        self.root.join("bin")
    }

    /// Content-addressed WIT interface definitions (`wit/`).
    ///
    /// Stores BLAKE3-hashed `.wit` files from third-party capsules.
    /// Standard interfaces ship with the SDK; custom interfaces are
    /// stored here on capsule install.
    #[must_use]
    pub fn wit_dir(&self) -> PathBuf {
        self.root.join("wit")
    }

    /// Shared WASM component libraries (`lib/`).
    ///
    /// Reserved for future WIT interface components that capsules can import.
    /// Not created eagerly — will be populated when component linking lands.
    #[must_use]
    pub fn lib_dir(&self) -> PathBuf {
        self.root.join("lib")
    }

    /// Principal home directories root (`home/`).
    #[must_use]
    pub fn home_dir(&self) -> PathBuf {
        self.root.join("home")
    }

    /// Get the home directory for a specific principal.
    #[must_use]
    pub fn principal_home(&self, id: &PrincipalId) -> PrincipalHome {
        PrincipalHome {
            root: self.home_dir().join(id.as_str()),
        }
    }
}

// ── PrincipalHome (per-user) ─────────────────────────────────────────────

/// Per-principal home directory (`~/.astrid/home/{principal}/`).
///
/// Each principal gets isolated storage following the XDG-like convention:
/// `.local/` for data and `.config/` for configuration.
#[derive(Debug, Clone)]
pub struct PrincipalHome {
    root: PathBuf,
}

impl PrincipalHome {
    /// Create from an explicit path (useful for testing).
    #[must_use]
    pub fn from_path(root: impl Into<PathBuf>) -> Self {
        Self { root: root.into() }
    }

    /// Ensure the full principal directory tree exists with secure permissions.
    ///
    /// # Errors
    ///
    /// Returns an error if directory creation or permission setting fails.
    pub fn ensure(&self) -> io::Result<()> {
        let dirs = [
            self.capsules_dir(),
            self.kv_dir(),
            self.log_dir(),
            self.audit_dir(),
            self.tokens_dir(),
            self.tmp_dir(),
            self.env_dir(),
        ];
        for dir in &dirs {
            std::fs::create_dir_all(dir)?;
        }
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let perms = std::fs::Permissions::from_mode(0o700);
            std::fs::set_permissions(&self.root, perms.clone())?;
            // Secure the two top-level dot-dirs.
            std::fs::set_permissions(self.root.join(".local"), perms.clone())?;
            std::fs::set_permissions(self.root.join(".config"), perms)?;
        }
        Ok(())
    }

    // ── Path accessors ───────────────────────────────────────────────

    /// Principal home root (`home/{principal}/`).
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// User-installed capsules (`.local/capsules/`).
    #[must_use]
    pub fn capsules_dir(&self) -> PathBuf {
        self.root.join(".local").join("capsules")
    }

    /// Capsule KV data (`.local/kv/`).
    #[must_use]
    pub fn kv_dir(&self) -> PathBuf {
        self.root.join(".local").join("kv")
    }

    /// Capsule logs (`.local/log/`).
    #[must_use]
    pub fn log_dir(&self) -> PathBuf {
        self.root.join(".local").join("log")
    }

    /// Audit chain (`.local/audit/`).
    #[must_use]
    pub fn audit_dir(&self) -> PathBuf {
        self.root.join(".local").join("audit")
    }

    /// Capability tokens (`.local/tokens/`).
    #[must_use]
    pub fn tokens_dir(&self) -> PathBuf {
        self.root.join(".local").join("tokens")
    }

    /// Temporary files, VFS-mounted as `/tmp` (`.local/tmp/`).
    #[must_use]
    pub fn tmp_dir(&self) -> PathBuf {
        self.root.join(".local").join("tmp")
    }

    /// Configuration directory (`.config/`).
    #[must_use]
    pub fn config_dir(&self) -> PathBuf {
        self.root.join(".config")
    }

    /// Capsule environment config overrides (`.config/env/`).
    #[must_use]
    pub fn env_dir(&self) -> PathBuf {
        self.root.join(".config").join("env")
    }
}

// ── WorkspaceDir (per-project) ───────────────────────────────────────────

/// Per-project workspace directory (`<project>/.astrid/`).
///
/// Contains only committable project-level config. A `workspace-id` UUID
/// links the project to its global state in `~/.astrid/`.
#[derive(Debug, Clone)]
pub struct WorkspaceDir {
    /// The project root (parent of `.astrid/`).
    project_root: PathBuf,
}

impl WorkspaceDir {
    /// Detect the workspace directory by walking up from `start_dir`.
    ///
    /// Detection order:
    /// 1. Directory containing `.astrid/`
    /// 2. Directory containing `.git`
    /// 3. Directory containing `ASTRID.md`
    /// 4. Fallback to `start_dir` itself
    #[must_use]
    pub fn detect(start_dir: &Path) -> Self {
        let start = if start_dir.is_absolute() {
            start_dir.to_path_buf()
        } else {
            std::env::current_dir().unwrap_or_default().join(start_dir)
        };

        let mut current = start.as_path();

        loop {
            if current.join(".astrid").is_dir() {
                return Self {
                    project_root: current.to_path_buf(),
                };
            }
            if current.join(".git").exists() {
                return Self {
                    project_root: current.to_path_buf(),
                };
            }
            if current.join("ASTRID.md").exists() {
                return Self {
                    project_root: current.to_path_buf(),
                };
            }
            match current.parent() {
                Some(parent) if parent != current => current = parent,
                _ => break,
            }
        }

        Self {
            project_root: start,
        }
    }

    /// Create from an explicit project root (useful for testing).
    #[must_use]
    pub fn from_path(project_root: impl Into<PathBuf>) -> Self {
        Self {
            project_root: project_root.into(),
        }
    }

    /// Ensure the `.astrid/` directory exists and generate a workspace ID
    /// if one does not already exist.
    ///
    /// # Errors
    ///
    /// Returns an error if directory creation or workspace ID generation fails.
    pub fn ensure(&self) -> io::Result<()> {
        std::fs::create_dir_all(self.dot_astrid())?;
        let _ = self.workspace_id()?;
        Ok(())
    }

    /// Project root directory (parent of `.astrid/`).
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.project_root
    }

    /// The `.astrid/` directory itself.
    #[must_use]
    pub fn dot_astrid(&self) -> PathBuf {
        self.project_root.join(".astrid")
    }

    /// Workspace capsules directory (`.astrid/capsules/`).
    #[must_use]
    pub fn capsules_dir(&self) -> PathBuf {
        self.dot_astrid().join("capsules")
    }

    /// Path to the workspace-id file (`.astrid/workspace-id`).
    #[must_use]
    pub fn workspace_id_path(&self) -> PathBuf {
        self.dot_astrid().join("workspace-id")
    }

    /// Read or generate the workspace ID.
    ///
    /// If the file exists (e.g. cloned from a repo), its UUID is adopted.
    /// Otherwise a new UUID is generated and written.
    ///
    /// # Errors
    ///
    /// Returns an error if the file cannot be read or written.
    pub fn workspace_id(&self) -> io::Result<Uuid> {
        let path = self.workspace_id_path();
        if let Ok(content) = std::fs::read_to_string(&path) {
            let trimmed = content.trim();
            if let Ok(id) = Uuid::parse_str(trimmed) {
                return Ok(id);
            }
        }
        std::fs::create_dir_all(self.dot_astrid())?;
        let id = Uuid::new_v4();
        std::fs::write(&path, id.to_string())?;
        Ok(id)
    }

    /// Path to the project-level instructions file (`.astrid/ASTRID.md`).
    #[must_use]
    pub fn instructions_path(&self) -> PathBuf {
        self.dot_astrid().join("ASTRID.md")
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ── AstridHome resolution ────────────────────────────────────────

    #[test]
    fn test_astrid_home_resolve_with_env() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().to_path_buf();
        let path_str = path.to_string_lossy().to_string();

        let home = AstridHome::resolve_with_env(Some(path_str), None).unwrap();
        assert_eq!(home.root(), path);
    }

    #[test]
    fn test_astrid_home_resolve_default() {
        let home_val = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
        let home = AstridHome::resolve_with_env(None, Some(home_val.clone())).unwrap();
        let expected = PathBuf::from(home_val).join(".astrid");
        assert_eq!(home.root(), expected);
    }

    #[test]
    fn test_astrid_home_rejects_traversal_in_astrid_home() {
        let result = AstridHome::resolve_with_env(Some("/tmp/../etc".to_string()), None);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(
            err.to_string().contains("'..'"),
            "expected path traversal error, got: {err}"
        );
    }

    #[test]
    fn test_astrid_home_rejects_traversal_in_home() {
        let result = AstridHome::resolve_with_env(None, Some("/tmp/../etc".to_string()));
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(
            err.to_string().contains("'..'"),
            "expected path traversal error, got: {err}"
        );
    }

    #[test]
    fn test_astrid_home_rejects_relative_env() {
        let result = AstridHome::resolve_with_env(Some("relative/path".to_string()), None);
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("absolute"));
    }

    #[test]
    fn test_astrid_home_rejects_empty_env() {
        let result = AstridHome::resolve_with_env(Some(String::new()), None);
        assert!(result.is_err());
    }

    #[test]
    fn test_astrid_home_rejects_relative_home() {
        let result = AstridHome::resolve_with_env(None, Some("relative/path".to_string()));
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("absolute"));
    }

    // ── AstridHome ensure ────────────────────────────────────────────

    #[test]
    fn test_astrid_home_ensure_creates_dirs() {
        let dir = tempfile::tempdir().unwrap();
        let home = AstridHome::from_path(dir.path());
        home.ensure().unwrap();

        assert!(home.etc_dir().exists());
        assert!(home.hooks_dir().exists());
        assert!(home.var_dir().exists());
        assert!(home.run_dir().exists());
        assert!(home.log_dir().exists());
        assert!(home.keys_dir().exists());
        assert!(home.bin_dir().exists());
        assert!(home.home_dir().exists());
    }

    #[test]
    fn test_astrid_home_ensure_writes_layout_version() {
        let dir = tempfile::tempdir().unwrap();
        let home = AstridHome::from_path(dir.path());
        home.ensure().unwrap();

        let version_path = home.etc_dir().join("layout-version");
        assert!(version_path.exists());
        let content = std::fs::read_to_string(&version_path).unwrap();
        assert_eq!(content, LAYOUT_VERSION);
    }

    #[test]
    fn test_astrid_home_ensure_idempotent() {
        let dir = tempfile::tempdir().unwrap();
        let home = AstridHome::from_path(dir.path());
        home.ensure().unwrap();
        home.ensure().unwrap(); // second call should not fail
    }

    #[cfg(unix)]
    #[test]
    fn test_astrid_home_ensure_sets_permissions() {
        use std::os::unix::fs::PermissionsExt;

        let dir = tempfile::tempdir().unwrap();
        let home = AstridHome::from_path(dir.path());
        home.ensure().unwrap();

        let root_perms = std::fs::metadata(home.root()).unwrap().permissions();
        assert_eq!(root_perms.mode() & 0o777, 0o700);

        let keys_perms = std::fs::metadata(home.keys_dir()).unwrap().permissions();
        assert_eq!(keys_perms.mode() & 0o777, 0o700);
    }

    // ── AstridHome path accessors ────────────────────────────────────

    #[test]
    fn test_astrid_home_fhs_paths() {
        let home = AstridHome::from_path("/tmp/test-astrid");
        let r = "/tmp/test-astrid";

        assert_eq!(home.root(), Path::new(r));
        assert_eq!(home.etc_dir(), PathBuf::from(format!("{r}/etc")));
        assert_eq!(
            home.config_path(),
            PathBuf::from(format!("{r}/etc/config.toml"))
        );
        assert_eq!(
            home.servers_config_path(),
            PathBuf::from(format!("{r}/etc/servers.toml"))
        );
        assert_eq!(
            home.gateway_config_path(),
            PathBuf::from(format!("{r}/etc/gateway.toml"))
        );
        assert_eq!(home.hooks_dir(), PathBuf::from(format!("{r}/etc/hooks")));
        assert_eq!(home.var_dir(), PathBuf::from(format!("{r}/var")));
        assert_eq!(
            home.state_db_path(),
            PathBuf::from(format!("{r}/var/state.db"))
        );
        assert_eq!(home.run_dir(), PathBuf::from(format!("{r}/run")));
        assert_eq!(
            home.socket_path(),
            PathBuf::from(format!("{r}/run/system.sock"))
        );
        assert_eq!(
            home.token_path(),
            PathBuf::from(format!("{r}/run/system.token"))
        );
        assert_eq!(
            home.ready_path(),
            PathBuf::from(format!("{r}/run/system.ready"))
        );
        assert_eq!(
            home.deferred_db_path(),
            PathBuf::from(format!("{r}/run/deferred.db"))
        );
        assert_eq!(home.log_dir(), PathBuf::from(format!("{r}/log")));
        assert_eq!(home.keys_dir(), PathBuf::from(format!("{r}/keys")));
        assert_eq!(
            home.runtime_key_path(),
            PathBuf::from(format!("{r}/keys/runtime.key"))
        );
        assert_eq!(home.bin_dir(), PathBuf::from(format!("{r}/bin")));
        assert_eq!(home.home_dir(), PathBuf::from(format!("{r}/home")));
    }

    // ── PrincipalHome ────────────────────────────────────────────────

    #[test]
    fn test_principal_home_from_astrid_home() {
        let home = AstridHome::from_path("/tmp/test-astrid");
        let principal = PrincipalId::default();
        let ph = home.principal_home(&principal);
        assert_eq!(ph.root(), Path::new("/tmp/test-astrid/home/default"));
    }

    #[test]
    fn test_principal_home_paths() {
        let ph = PrincipalHome::from_path("/tmp/test-astrid/home/alice");
        let r = "/tmp/test-astrid/home/alice";

        assert_eq!(ph.root(), Path::new(r));
        assert_eq!(
            ph.capsules_dir(),
            PathBuf::from(format!("{r}/.local/capsules"))
        );
        assert_eq!(ph.kv_dir(), PathBuf::from(format!("{r}/.local/kv")));
        assert_eq!(ph.log_dir(), PathBuf::from(format!("{r}/.local/log")));
        assert_eq!(ph.audit_dir(), PathBuf::from(format!("{r}/.local/audit")));
        assert_eq!(ph.tokens_dir(), PathBuf::from(format!("{r}/.local/tokens")));
        assert_eq!(ph.tmp_dir(), PathBuf::from(format!("{r}/.local/tmp")));
        assert_eq!(ph.config_dir(), PathBuf::from(format!("{r}/.config")));
        assert_eq!(ph.env_dir(), PathBuf::from(format!("{r}/.config/env")));
    }

    #[test]
    fn test_principal_home_ensure_creates_dirs() {
        let dir = tempfile::tempdir().unwrap();
        let ph = PrincipalHome::from_path(dir.path().join("alice"));
        ph.ensure().unwrap();

        assert!(ph.capsules_dir().exists());
        assert!(ph.kv_dir().exists());
        assert!(ph.log_dir().exists());
        assert!(ph.audit_dir().exists());
        assert!(ph.tokens_dir().exists());
        assert!(ph.tmp_dir().exists());
        assert!(ph.env_dir().exists());
    }

    #[cfg(unix)]
    #[test]
    fn test_principal_home_ensure_sets_permissions() {
        use std::os::unix::fs::PermissionsExt;

        let dir = tempfile::tempdir().unwrap();
        let ph = PrincipalHome::from_path(dir.path().join("bob"));
        ph.ensure().unwrap();

        let root_perms = std::fs::metadata(ph.root()).unwrap().permissions();
        assert_eq!(root_perms.mode() & 0o777, 0o700);

        let local_perms = std::fs::metadata(ph.root().join(".local"))
            .unwrap()
            .permissions();
        assert_eq!(local_perms.mode() & 0o777, 0o700);

        let config_perms = std::fs::metadata(ph.root().join(".config"))
            .unwrap()
            .permissions();
        assert_eq!(config_perms.mode() & 0o777, 0o700);
    }

    #[test]
    fn test_principal_home_ensure_idempotent() {
        let dir = tempfile::tempdir().unwrap();
        let ph = PrincipalHome::from_path(dir.path().join("charlie"));
        ph.ensure().unwrap();
        ph.ensure().unwrap(); // second call should not fail
    }

    // ── WorkspaceDir ─────────────────────────────────────────────────

    #[test]
    fn test_workspace_detect_with_dot_astrid() {
        let dir = tempfile::tempdir().unwrap();
        let astrid_dir = dir.path().join(".astrid");
        std::fs::create_dir(&astrid_dir).unwrap();

        let sub = dir.path().join("src").join("deep");
        std::fs::create_dir_all(&sub).unwrap();

        let ws = WorkspaceDir::detect(&sub);
        assert_eq!(ws.root(), dir.path());
    }

    #[test]
    fn test_workspace_detect_with_git() {
        let dir = tempfile::tempdir().unwrap();
        let git_dir = dir.path().join(".git");
        std::fs::create_dir(&git_dir).unwrap();

        let sub = dir.path().join("src");
        std::fs::create_dir_all(&sub).unwrap();

        let ws = WorkspaceDir::detect(&sub);
        assert_eq!(ws.root(), dir.path());
    }

    #[test]
    fn test_workspace_detect_with_astrid_md() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("ASTRID.md"), "# Project").unwrap();

        let sub = dir.path().join("src");
        std::fs::create_dir_all(&sub).unwrap();

        let ws = WorkspaceDir::detect(&sub);
        assert_eq!(ws.root(), dir.path());
    }

    #[test]
    fn test_workspace_detect_fallback() {
        let dir = tempfile::tempdir().unwrap();
        let isolated = dir.path().join("isolated");
        std::fs::create_dir_all(&isolated).unwrap();

        let ws = WorkspaceDir::from_path(&isolated);
        assert_eq!(ws.root(), isolated);
    }

    #[test]
    fn test_workspace_detect_prefers_dot_astrid_over_git() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir(dir.path().join(".astrid")).unwrap();
        std::fs::create_dir(dir.path().join(".git")).unwrap();

        let sub = dir.path().join("src");
        std::fs::create_dir_all(&sub).unwrap();

        let ws = WorkspaceDir::detect(&sub);
        assert_eq!(ws.root(), dir.path());
    }

    #[test]
    fn test_workspace_ensure_creates_dirs_and_id() {
        let dir = tempfile::tempdir().unwrap();
        let ws = WorkspaceDir::from_path(dir.path());
        ws.ensure().unwrap();

        assert!(ws.dot_astrid().exists());
        assert!(ws.workspace_id_path().exists());

        let content = std::fs::read_to_string(ws.workspace_id_path()).unwrap();
        uuid::Uuid::parse_str(content.trim()).expect("workspace-id should be a valid UUID");
    }

    #[test]
    fn test_workspace_id_adopts_existing() {
        let dir = tempfile::tempdir().unwrap();
        let ws = WorkspaceDir::from_path(dir.path());

        std::fs::create_dir_all(ws.dot_astrid()).unwrap();
        let pre_id = uuid::Uuid::new_v4();
        std::fs::write(ws.workspace_id_path(), pre_id.to_string()).unwrap();

        let id = ws.workspace_id().unwrap();
        assert_eq!(id, pre_id);
    }

    #[test]
    fn test_workspace_id_stable_across_calls() {
        let dir = tempfile::tempdir().unwrap();
        let ws = WorkspaceDir::from_path(dir.path());
        let id1 = ws.workspace_id().unwrap();
        let id2 = ws.workspace_id().unwrap();
        assert_eq!(id1, id2);
    }

    #[test]
    fn test_workspace_path_accessors() {
        let ws = WorkspaceDir::from_path("/home/user/project");
        assert_eq!(ws.root(), Path::new("/home/user/project"));
        assert_eq!(ws.dot_astrid(), PathBuf::from("/home/user/project/.astrid"));
        assert_eq!(
            ws.capsules_dir(),
            PathBuf::from("/home/user/project/.astrid/capsules")
        );
        assert_eq!(
            ws.workspace_id_path(),
            PathBuf::from("/home/user/project/.astrid/workspace-id")
        );
        assert_eq!(
            ws.instructions_path(),
            PathBuf::from("/home/user/project/.astrid/ASTRID.md")
        );
    }
}