feat(spaces): base-dir storage foundation

Foundation for per-Space base directories (scope a workspace root to a Space
by folder prefix). No behavior change yet — just the primitive + storage.

- Domain: path_is_within / longest_matching_base (segment-boundary aware,
  Windows + POSIX, longest-prefix wins) + the SpaceBaseDir entity.
- Storage: migration 019 space_base_dirs (UNIQUE path = one owner per folder,
  FK cascade) + SpaceBaseDirRepository (list/add/remove + find_space_for_root
  longest-prefix lookup).
- Tests: 4 domain prefix tests + 4 repo tests (CRUD, uniqueness, longest
  prefix, cascade).

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

crates/mcpmux-core/src/domain/mod.rs

@@ -38,5 +38,6 @@ pub use server_feature::*;
 pub use server_log::*;
 pub use space::*;
 pub use workspace_binding::{
-    normalize_workspace_root, validate_workspace_root, WorkspaceBinding, WorkspaceRootValidation,
+    longest_matching_base, normalize_workspace_root, path_is_within, validate_workspace_root,
+    WorkspaceBinding, WorkspaceRootValidation,
 };

crates/mcpmux-core/src/domain/space.rs

@@ -75,6 +75,24 @@ impl Default for Space {
     }
 }
 
+/// A base directory claimed by a Space.
+///
+/// Any reported workspace root at or under `path` is scoped to `space_id`
+/// (see [`crate::domain::path_is_within`]). `path` is stored already-normalized
+/// via [`crate::domain::normalize_workspace_root`], and is globally unique —
+/// the same folder can't be a base dir of two Spaces.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SpaceBaseDir {
+    /// Unique identifier for this base-dir row.
+    pub id: String,
+    /// The Space that owns this base directory.
+    pub space_id: String,
+    /// Normalized absolute path.
+    pub path: String,
+    /// Creation timestamp.
+    pub created_at: DateTime<Utc>,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/mcpmux-core/src/domain/workspace_binding.rs

@@ -292,6 +292,52 @@ pub enum WorkspaceRootValidation {
     Invalid { reason: String },
 }
 
+/// True when `root` is the same folder as `base`, or nested inside it —
+/// matching on path-segment boundaries so `/work` contains `/work/proj` but
+/// NOT `/workspace`. Both arguments must already be normalized via
+/// [`normalize_workspace_root`] (same casing + separator conventions) for the
+/// comparison to be meaningful.
+///
+/// Used to scope a workspace root to a Space by its configured base
+/// directories: a reported root at or under a base dir belongs to that Space.
+pub fn path_is_within(root: &str, base: &str) -> bool {
+    if base.is_empty() || root.is_empty() {
+        return false;
+    }
+    if root == base {
+        return true;
+    }
+    // Separator comes from the (normalized) base: Windows drive/UNC paths use
+    // `\`, POSIX uses `/`.
+    let sep = if base.contains('\\') { '\\' } else { '/' };
+    if base.ends_with(sep) {
+        // `base` is already a filesystem/drive root (`c:\`, `\\`, `/`) — its
+        // trailing separator IS the boundary, so a plain prefix check is right.
+        root.starts_with(base)
+    } else {
+        // Otherwise require the next char to be the separator so we only match
+        // whole segments (`/work` ⊄ `/workspace`).
+        let mut prefix = String::with_capacity(base.len() + 1);
+        prefix.push_str(base);
+        prefix.push(sep);
+        root.starts_with(&prefix)
+    }
+}
+
+/// Of all `bases`, return the **longest** one that contains `root` (most
+/// specific wins when base dirs nest — `/work/client` beats `/work`), or
+/// `None` when none contain it. Inputs must be normalized. Equal-length bases
+/// can't both contain the same root, so length ties never occur in practice.
+pub fn longest_matching_base<'a>(
+    root: &str,
+    bases: impl IntoIterator<Item = &'a str>,
+) -> Option<&'a str> {
+    bases
+        .into_iter()
+        .filter(|b| path_is_within(root, b))
+        .max_by_key(|b| b.len())
+}
+
 /// Validate a user-entered workspace root.
 ///
 /// Applied on manual add/edit ONLY — roots reported by connected MCP
@@ -388,6 +434,55 @@ fn check_windows_reserved_chars(path: &str) -> Result<(), String> {
 mod tests {
     use super::*;
 
+    // ---- path_is_within / longest_matching_base --------------------------
+
+    #[test]
+    fn within_posix_segment_boundaries() {
+        assert!(path_is_within("/work", "/work")); // same folder
+        assert!(path_is_within("/work/proj", "/work")); // nested
+        assert!(path_is_within("/work/proj/deep", "/work")); // deeper
+        assert!(!path_is_within("/workspace", "/work")); // NOT a segment boundary
+        assert!(!path_is_within("/other", "/work"));
+        assert!(!path_is_within("/work", "/work/proj")); // parent is not within child
+    }
+
+    #[test]
+    fn within_windows_is_case_and_sep_consistent() {
+        // Inputs are already-normalized Windows form (lower-case, `\`).
+        assert!(path_is_within("c:\\work\\proj", "c:\\work"));
+        assert!(path_is_within("c:\\work", "c:\\work"));
+        assert!(!path_is_within("c:\\workspace", "c:\\work"));
+        // Drive root keeps its trailing separator and contains everything on it.
+        assert!(path_is_within("c:\\proj", "c:\\"));
+    }
+
+    #[test]
+    fn within_filesystem_roots() {
+        assert!(path_is_within("/work", "/")); // POSIX root contains all
+        assert!(path_is_within("/", "/"));
+        assert!(!path_is_within("/x", "")); // empty base never matches
+        assert!(!path_is_within("", "/x")); // empty root never matches
+    }
+
+    #[test]
+    fn longest_base_wins_when_nested() {
+        let bases = ["/work", "/work/client", "/other"];
+        assert_eq!(
+            longest_matching_base("/work/client/app", bases.iter().copied()),
+            Some("/work/client"),
+        );
+        // A root under only the broad base falls to that one.
+        assert_eq!(
+            longest_matching_base("/work/solo", bases.iter().copied()),
+            Some("/work"),
+        );
+        // No base contains it.
+        assert_eq!(
+            longest_matching_base("/elsewhere", bases.iter().copied()),
+            None,
+        );
+    }
+
     // ---- normalize -------------------------------------------------------
 
     #[test]

crates/mcpmux-core/src/repository/mod.rs

@@ -8,7 +8,7 @@ use uuid::Uuid;
 
 use crate::domain::{
     Client, Credential, CredentialType, FeatureSet, FeatureSetMember, InstalledServer, MemberMode,
-    OutboundOAuthRegistration, ServerFeature, Space, WorkspaceBinding,
+    OutboundOAuthRegistration, ServerFeature, Space, SpaceBaseDir, WorkspaceBinding,
 };
 
 /// Result type for repository operations
@@ -39,6 +39,32 @@ pub trait SpaceRepository: Send + Sync {
     async fn set_default(&self, id: &Uuid) -> RepoResult<()>;
 }
 
+/// Per-Space base-directory repository.
+///
+/// Manages the folders a Space claims. A reported workspace root at or under a
+/// base dir is scoped to that Space (longest-prefix wins when base dirs nest).
+#[async_trait]
+pub trait SpaceBaseDirRepository: Send + Sync {
+    /// Every base dir across all Spaces.
+    async fn list_all(&self) -> RepoResult<Vec<SpaceBaseDir>>;
+
+    /// Base dirs for one Space.
+    async fn list_by_space(&self, space_id: &Uuid) -> RepoResult<Vec<SpaceBaseDir>>;
+
+    /// Add a base dir to a Space. `path` MUST already be normalized via
+    /// [`crate::domain::normalize_workspace_root`]. Returns an error if the
+    /// path is already claimed by any Space (one owner per path).
+    async fn add(&self, space_id: &Uuid, path: &str) -> RepoResult<SpaceBaseDir>;
+
+    /// Remove a base dir by its row id.
+    async fn remove(&self, id: &str) -> RepoResult<()>;
+
+    /// The Space whose base dir is the longest prefix of `root` (already
+    /// normalized), or `None` when no base dir contains it. Most-specific
+    /// (longest) base dir wins when several nest.
+    async fn find_space_for_root(&self, root: &str) -> RepoResult<Option<Uuid>>;
+}
+
 /// InstalledServer repository trait
 #[async_trait]
 pub trait InstalledServerRepository: Send + Sync {

crates/mcpmux-storage/src/database.rs

@@ -123,6 +123,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "starter_is_default_fallback_copy",
         sql: include_str!("migrations/018_starter_is_default_fallback_copy.sql"),
     },
+    Migration {
+        version: 19,
+        name: "space_base_dirs",
+        sql: include_str!("migrations/019_space_base_dirs.sql"),
+    },
 ];
 
 /// SQLite database wrapper.

crates/mcpmux-storage/src/migrations/019_space_base_dirs.sql

@@ -0,0 +1,22 @@
+-- Migration 019: per-Space base directories.
+--
+-- A Space can claim one or more base directories. Any workspace root reported
+-- by a connected client that sits at or under a base dir is "scoped" to that
+-- Space: an unmapped root falls back to that Space's Starter (not the global
+-- default), and the meta-tools / mapping popup restrict to that Space.
+--
+-- `path` is the NORMALIZED workspace root (see `normalize_workspace_root`:
+-- lower-cased drive letter on Windows, `\` separators, no trailing slash).
+-- UNIQUE(path) enforces one owner per exact path — the same folder can't be a
+-- base dir of two Spaces. Nesting across Spaces is allowed and resolved by
+-- longest-prefix at lookup time. ON DELETE CASCADE drops a Space's base dirs
+-- with it.
+
+CREATE TABLE IF NOT EXISTS space_base_dirs (
+    id         TEXT PRIMARY KEY,
+    space_id   TEXT NOT NULL REFERENCES spaces(id) ON DELETE CASCADE,
+    path       TEXT NOT NULL UNIQUE,
+    created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_space_base_dirs_space ON space_base_dirs(space_id);

crates/mcpmux-storage/src/repositories/mod.rs

@@ -8,6 +8,7 @@ mod inbound_mcp_client_repository;
 mod installed_server_repository;
 mod outbound_oauth_client_repository;
 mod server_feature_repository;
+mod space_base_dir_repository;
 mod space_builtin_config_repository;
 mod space_repository;
 mod workspace_binding_repository;
@@ -25,6 +26,7 @@ pub use outbound_oauth_client_repository::SqliteOutboundOAuthRepository;
 pub use server_feature_repository::{
     FeatureType, ServerFeature, ServerFeatureRepository, SqliteServerFeatureRepository,
 };
+pub use space_base_dir_repository::SqliteSpaceBaseDirRepository;
 pub use space_builtin_config_repository::SqliteSpaceBuiltinConfigRepository;
 pub use space_repository::SqliteSpaceRepository;
 pub use workspace_binding_repository::SqliteWorkspaceBindingRepository;

crates/mcpmux-storage/src/repositories/space_base_dir_repository.rs

@@ -0,0 +1,125 @@
+//! SQLite implementation of SpaceBaseDirRepository.
+
+use std::sync::Arc;
+
+use anyhow::Result;
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use mcpmux_core::{path_is_within, SpaceBaseDir, SpaceBaseDirRepository};
+use rusqlite::params;
+use tokio::sync::Mutex;
+use uuid::Uuid;
+
+use crate::Database;
+
+/// SQLite-backed implementation of [`SpaceBaseDirRepository`].
+pub struct SqliteSpaceBaseDirRepository {
+    db: Arc<Mutex<Database>>,
+}
+
+impl SqliteSpaceBaseDirRepository {
+    pub fn new(db: Arc<Mutex<Database>>) -> Self {
+        Self { db }
+    }
+
+    fn parse_datetime(s: &str) -> DateTime<Utc> {
+        if let Ok(dt) = DateTime::parse_from_rfc3339(s) {
+            return dt.with_timezone(&Utc);
+        }
+        if let Ok(dt) = chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S") {
+            return dt.and_utc();
+        }
+        Utc::now()
+    }
+
+    /// Columns selected for every read. Order must match `map_row`.
+    const COLUMNS: &'static str = "id, space_id, path, created_at";
+
+    fn map_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<SpaceBaseDir> {
+        Ok(SpaceBaseDir {
+            id: row.get(0)?,
+            space_id: row.get(1)?,
+            path: row.get(2)?,
+            created_at: Self::parse_datetime(&row.get::<_, String>(3)?),
+        })
+    }
+}
+
+#[async_trait]
+impl SpaceBaseDirRepository for SqliteSpaceBaseDirRepository {
+    async fn list_all(&self) -> Result<Vec<SpaceBaseDir>> {
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        let mut stmt = conn.prepare(&format!(
+            "SELECT {} FROM space_base_dirs ORDER BY path ASC",
+            Self::COLUMNS
+        ))?;
+        let rows = stmt
+            .query_map([], Self::map_row)?
+            .collect::<rusqlite::Result<Vec<_>>>()?;
+        Ok(rows)
+    }
+
+    async fn list_by_space(&self, space_id: &Uuid) -> Result<Vec<SpaceBaseDir>> {
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        let mut stmt = conn.prepare(&format!(
+            "SELECT {} FROM space_base_dirs WHERE space_id = ? ORDER BY path ASC",
+            Self::COLUMNS
+        ))?;
+        let rows = stmt
+            .query_map(params![space_id.to_string()], Self::map_row)?
+            .collect::<rusqlite::Result<Vec<_>>>()?;
+        Ok(rows)
+    }
+
+    async fn add(&self, space_id: &Uuid, path: &str) -> Result<SpaceBaseDir> {
+        if path.trim().is_empty() {
+            anyhow::bail!("Base directory path is empty");
+        }
+        let row = SpaceBaseDir {
+            id: Uuid::new_v4().to_string(),
+            space_id: space_id.to_string(),
+            path: path.to_string(),
+            created_at: Utc::now(),
+        };
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        conn.execute(
+            "INSERT INTO space_base_dirs (id, space_id, path, created_at) VALUES (?1, ?2, ?3, ?4)",
+            params![row.id, row.space_id, row.path, row.created_at.to_rfc3339()],
+        )
+        .map_err(|e| {
+            // Turn the UNIQUE(path) collision into an actionable message — the
+            // folder already belongs to some Space (possibly this one).
+            if e.to_string().to_lowercase().contains("unique") {
+                anyhow::anyhow!("That folder is already a base directory of a space: {path}")
+            } else {
+                anyhow::Error::from(e)
+            }
+        })?;
+        Ok(row)
+    }
+
+    async fn remove(&self, id: &str) -> Result<()> {
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        conn.execute("DELETE FROM space_base_dirs WHERE id = ?", params![id])?;
+        Ok(())
+    }
+
+    async fn find_space_for_root(&self, root: &str) -> Result<Option<Uuid>> {
+        if root.trim().is_empty() {
+            return Ok(None);
+        }
+        // Few base dirs in practice — load them and pick the longest prefix
+        // match in Rust (reuses the byte-proven `path_is_within`). The db lock
+        // is taken and released inside `list_all`, so there's no double-lock.
+        let all = self.list_all().await?;
+        let best = all
+            .iter()
+            .filter(|bd| path_is_within(root, &bd.path))
+            .max_by_key(|bd| bd.path.len());
+        Ok(best.and_then(|bd| bd.space_id.parse::<Uuid>().ok()))
+    }
+}

tests/rust/tests/database/mod.rs

@@ -15,3 +15,4 @@ mod installed_server;
 mod migrations;
 mod outbound_oauth;
 mod repositories;
+mod space_base_dir;