use std::io;
use std::path::{Path, PathBuf};
pub const SYMFORGE_DIR_NAME: &str = ".symforge";
pub const FRECENCY_DB_NAME: &str = "frecency.db";
pub const COUPLING_DB_NAME: &str = "coupling.db";
pub const ANALYTICS_DB_NAME: &str = "analytics.db";
pub const API_KEYS_DB_NAME: &str = "api-keys.db";
pub const STEL_LEDGER_DB_NAME: &str = "stel-ledger.db";
pub const SYMFORGE_IDEMPOTENCY_DIR_PATH: &str = ".symforge/idempotency";
pub const SYMFORGE_IDEMPOTENCY_RECORDS_DIR_PATH: &str = ".symforge/idempotency/records";
pub const SYMFORGE_IDEMPOTENCY_QUARANTINE_DIR_PATH: &str = ".symforge/idempotency/quarantine";
pub const SYMFORGE_INDEX_SNAPSHOT_QUARANTINE_DIR_PATH: &str =
".symforge/quarantine/index-snapshots";
pub const SYMFORGE_ARTIFACT_QUARANTINE_DIR_PATH: &str = ".symforge/quarantine/artifacts";
#[must_use]
pub fn os_runtime_tag() -> &'static str {
std::env::consts::OS
}
#[must_use]
pub fn os_tagged_runtime_file_name(stem: &str, ext: &str) -> String {
format!("{stem}.{tag}.{ext}", tag = os_runtime_tag())
}
pub fn resolve_symforge_dir(base: &Path) -> PathBuf {
base.join(SYMFORGE_DIR_NAME)
}
pub fn global_symforge_home() -> io::Result<PathBuf> {
if let Some(explicit_home) = std::env::var_os("SYMFORGE_HOME") {
let dir = PathBuf::from(explicit_home);
std::fs::create_dir_all(&dir).map_err(|e| {
io::Error::new(
e.kind(),
format!("ensuring symforge global home at {}: {}", dir.display(), e),
)
})?;
return Ok(dir);
}
let home = dirs::home_dir()
.ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "home directory not found"))?;
ensure_symforge_dir(&home)
}
fn is_unsafe_data_dir_base(path: &Path) -> bool {
let canonical = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
is_sensitive_path(&canonical)
}
pub fn select_runtime_data_base(project_root: Option<&Path>, cwd: Option<&Path>) -> PathBuf {
if let Some(root) = project_root.filter(|p| !is_unsafe_data_dir_base(p)) {
return resolve_symforge_dir(root);
}
if let Some(cwd) = cwd.filter(|p| !is_unsafe_data_dir_base(p)) {
return resolve_symforge_dir(cwd);
}
global_symforge_home().unwrap_or_else(|error| {
tracing::warn!(
"falling back to cwd-relative .symforge after global home resolution failed: {error}"
);
cwd.as_ref()
.map(|path| resolve_symforge_dir(path))
.unwrap_or_else(|| PathBuf::from(SYMFORGE_DIR_NAME))
})
}
pub fn ensure_runtime_symforge_dir(project_root: Option<&Path>) -> io::Result<PathBuf> {
let cwd = std::env::current_dir().ok();
let preferred_base = project_root
.filter(|p| !is_unsafe_data_dir_base(p))
.map(|p| p.to_path_buf())
.or_else(|| {
cwd.as_ref()
.filter(|p| !is_unsafe_data_dir_base(p))
.cloned()
});
if let Some(base) = preferred_base {
match ensure_symforge_dir(&base) {
Ok(dir) => return Ok(dir),
Err(error) if error.kind() == io::ErrorKind::PermissionDenied => {
tracing::warn!(
path = %base.display(),
"cannot create project-local .symforge (permission denied); using global SymForge home"
);
}
Err(error) => return Err(error),
}
} else if let Some(ref launch_cwd) = cwd {
tracing::info!(
path = %launch_cwd.display(),
"launch cwd is not a safe project root for .symforge; using global SymForge home"
);
}
global_symforge_home()
}
pub fn ensure_symforge_dir(base: &Path) -> io::Result<PathBuf> {
let dir = resolve_symforge_dir(base);
std::fs::create_dir_all(&dir).map_err(|e| {
io::Error::new(
e.kind(),
format!("ensuring symforge data dir at {}: {}", dir.display(), e),
)
})?;
Ok(dir)
}
#[must_use]
pub fn symforge_db_path(root: &Path, name: &str) -> PathBuf {
debug_assert!(
!name.contains('/') && !name.contains('\\'),
"symforge_db_path `name` must be a BARE filename (got {name:?}); \
the `.symforge/` prefix is owned by this helper"
);
root.join(SYMFORGE_DIR_NAME).join(name)
}
pub fn ensure_symforge_db_path(root: &Path, name: &str) -> io::Result<PathBuf> {
ensure_symforge_dir(root)?;
Ok(symforge_db_path(root, name))
}
pub fn resolve_idempotency_dir(base: &Path) -> PathBuf {
base.join(SYMFORGE_IDEMPOTENCY_DIR_PATH)
}
pub fn ensure_idempotency_dir(base: &Path) -> io::Result<PathBuf> {
let dir = resolve_idempotency_dir(base);
std::fs::create_dir_all(&dir).map_err(|e| {
io::Error::new(
e.kind(),
format!("ensuring idempotency dir at {}: {}", dir.display(), e),
)
})?;
Ok(dir)
}
pub fn resolve_index_snapshot_quarantine_dir(base: &Path) -> PathBuf {
base.join(SYMFORGE_INDEX_SNAPSHOT_QUARANTINE_DIR_PATH)
}
pub fn ensure_index_snapshot_quarantine_dir(base: &Path) -> io::Result<PathBuf> {
let dir = resolve_index_snapshot_quarantine_dir(base);
std::fs::create_dir_all(&dir).map_err(|e| {
io::Error::new(
e.kind(),
format!(
"ensuring index snapshot quarantine dir at {}: {}",
dir.display(),
e
),
)
})?;
Ok(dir)
}
pub fn resolve_artifact_quarantine_dir(base: &Path) -> PathBuf {
base.join(SYMFORGE_ARTIFACT_QUARANTINE_DIR_PATH)
}
pub fn ensure_artifact_quarantine_dir(base: &Path) -> io::Result<PathBuf> {
let dir = resolve_artifact_quarantine_dir(base);
std::fs::create_dir_all(&dir).map_err(|e| {
io::Error::new(
e.kind(),
format!(
"ensuring team artifact quarantine dir at {}: {}",
dir.display(),
e
),
)
})?;
Ok(dir)
}
fn strip_verbatim_prefix(s: &str) -> &str {
if let Some(rest) = s.strip_prefix(r"\\?\UNC\") {
rest
} else if let Some(rest) = s.strip_prefix(r"\\?\") {
rest
} else {
s
}
}
const WINDOWS_SENSITIVE_SEGMENTS: &[&str] = &[
"windows",
"program files",
"program files (x86)",
"programdata",
"system32",
];
fn is_windows_sensitive_under_drive(comps: &[&str]) -> bool {
comps
.get(1)
.is_some_and(|first| WINDOWS_SENSITIVE_SEGMENTS.contains(first))
}
fn is_windows_user_container(comps: &[&str]) -> bool {
matches!(comps.get(1), Some(&"users")) && comps.len() <= 3
}
#[must_use]
pub fn is_sensitive_path(canonical: &Path) -> bool {
let raw = canonical.to_string_lossy();
let stripped = strip_verbatim_prefix(&raw);
#[cfg(windows)]
{
let lower = stripped.replace('\\', "/").to_ascii_lowercase();
let comps: Vec<&str> = lower.split('/').filter(|c| !c.is_empty()).collect();
if let [drive] = comps.as_slice()
&& drive.len() == 2
&& drive.ends_with(':')
&& drive.as_bytes()[0].is_ascii_alphabetic()
{
return true;
}
is_windows_sensitive_under_drive(&comps) || is_windows_user_container(&comps)
}
#[cfg(unix)]
{
let path = Path::new(stripped);
const BLOCKED_RECURSIVE: &[&str] = &[
"/bin", "/boot", "/dev", "/etc", "/lib", "/lib64", "/proc", "/run", "/sbin", "/sys",
"/usr", "/var", "/root", "/Library", "/System", "/private",
];
const BLOCKED_ROOT_ONLY: &[&str] = &["/opt", "/srv", "/media", "/tmp", "/snap"];
let has_normal_component = path
.components()
.any(|c| matches!(c, std::path::Component::Normal(_)));
if path.is_absolute() && !has_normal_component {
return true;
}
for blocked in BLOCKED_RECURSIVE {
if path == Path::new(blocked) || path.starts_with(blocked) {
return true;
}
}
for blocked in BLOCKED_ROOT_ONLY {
if path == Path::new(blocked) {
return true;
}
}
let lower = stripped.to_ascii_lowercase();
let comps: Vec<&str> = lower.split('/').filter(|c| !c.is_empty()).collect();
if let [container, rest @ ..] = comps.as_slice()
&& (*container == "home" || *container == "users")
&& rest.len() <= 1
{
return true;
}
if comps.first() == Some(&"mnt") {
match comps.as_slice() {
[_mnt] => return true,
[_mnt, drive, rest @ ..]
if drive.len() == 1 && drive.as_bytes()[0].is_ascii_alphabetic() =>
{
if rest.is_empty() {
return true;
}
let mut drive_view = Vec::with_capacity(rest.len() + 1);
drive_view.push(*drive);
drive_view.extend_from_slice(rest);
if is_windows_user_container(&drive_view) {
return true;
}
if is_windows_sensitive_under_drive(&drive_view) {
return true;
}
}
_ => {}
}
}
false
}
}
#[cfg(test)]
mod tests {
use super::*;
use tempfile::TempDir;
#[test]
fn select_runtime_data_base_prefers_project_root_over_launch_cwd() {
let tmp = TempDir::new().unwrap();
let project = tmp.path().join("repo");
std::fs::create_dir_all(&project).unwrap();
let chosen = select_runtime_data_base(Some(&project), Some(Path::new("/tmp")));
assert_eq!(chosen, resolve_symforge_dir(&project));
}
#[cfg(windows)]
#[test]
fn select_runtime_data_base_skips_system32_launch_cwd() {
let chosen = select_runtime_data_base(None, Some(Path::new(r"C:\Windows\System32")));
assert!(
!chosen
.to_string_lossy()
.to_ascii_lowercase()
.contains("system32"),
"System32 launch cwd must not host .symforge; got {}",
chosen.display()
);
}
#[test]
fn test_resolve_symforge_dir_prefers_existing_canonical_dir() {
let tmp = TempDir::new().unwrap();
let symforge_dir = tmp.path().join(SYMFORGE_DIR_NAME);
std::fs::create_dir_all(&symforge_dir).unwrap();
let resolved = resolve_symforge_dir(tmp.path());
assert_eq!(resolved, symforge_dir);
}
#[test]
fn test_ensure_symforge_dir_creates_canonical_dir_when_missing() {
let tmp = TempDir::new().unwrap();
let dir = ensure_symforge_dir(tmp.path()).unwrap();
assert_eq!(dir, tmp.path().join(SYMFORGE_DIR_NAME));
assert!(dir.exists(), "canonical directory should be created");
}
#[test]
fn symforge_db_path_is_single_prefixed_never_doubled() {
let tmp = TempDir::new().unwrap();
let root = tmp.path();
for name in [
FRECENCY_DB_NAME,
COUPLING_DB_NAME,
ANALYTICS_DB_NAME,
API_KEYS_DB_NAME,
STEL_LEDGER_DB_NAME,
] {
let got = symforge_db_path(root, name);
assert_eq!(
got,
root.join(SYMFORGE_DIR_NAME).join(name),
"{name}: production path must be single-prefixed root/.symforge/<name>"
);
let doubled = root
.join(SYMFORGE_DIR_NAME)
.join(SYMFORGE_DIR_NAME)
.join(name);
assert_ne!(
got, doubled,
"{name}: helper must never produce the doubled root/.symforge/.symforge/<name> path"
);
}
}
#[test]
fn ensure_symforge_db_path_creates_parent_and_returns_single_prefixed() {
let tmp = TempDir::new().unwrap();
let root = tmp.path();
let db = ensure_symforge_db_path(root, ANALYTICS_DB_NAME).unwrap();
assert_eq!(db, root.join(SYMFORGE_DIR_NAME).join(ANALYTICS_DB_NAME));
assert!(
db.parent().unwrap().is_dir(),
"parent .symforge dir must exist after ensure_symforge_db_path"
);
}
#[test]
fn test_idempotency_paths_stay_under_canonical_symforge_dir() {
let tmp = TempDir::new().unwrap();
assert_eq!(
resolve_idempotency_dir(tmp.path()),
tmp.path().join(SYMFORGE_DIR_NAME).join("idempotency")
);
assert_eq!(
tmp.path().join(SYMFORGE_IDEMPOTENCY_RECORDS_DIR_PATH),
resolve_idempotency_dir(tmp.path()).join("records")
);
assert_eq!(
tmp.path().join(SYMFORGE_IDEMPOTENCY_QUARANTINE_DIR_PATH),
resolve_idempotency_dir(tmp.path()).join("quarantine")
);
}
#[test]
fn test_index_snapshot_quarantine_path_stays_under_canonical_symforge_dir() {
let tmp = TempDir::new().unwrap();
assert_eq!(
resolve_index_snapshot_quarantine_dir(tmp.path()),
tmp.path()
.join(SYMFORGE_DIR_NAME)
.join("quarantine")
.join("index-snapshots")
);
}
#[test]
fn test_artifact_quarantine_path_stays_under_canonical_symforge_dir() {
let tmp = TempDir::new().unwrap();
assert_eq!(
resolve_artifact_quarantine_dir(tmp.path()),
tmp.path()
.join(SYMFORGE_DIR_NAME)
.join("quarantine")
.join("artifacts")
);
let dir = ensure_artifact_quarantine_dir(tmp.path()).unwrap();
assert!(dir.is_dir(), "artifact quarantine dir should be created");
}
#[test]
fn strip_verbatim_prefix_handles_plain_unc_and_verbatim() {
assert_eq!(strip_verbatim_prefix(r"\\?\C:\Windows"), r"C:\Windows");
assert_eq!(
strip_verbatim_prefix(r"\\?\UNC\server\share\proj"),
r"server\share\proj"
);
assert_eq!(
strip_verbatim_prefix(r"C:\Users\me\proj"),
r"C:\Users\me\proj"
);
assert_eq!(
strip_verbatim_prefix("/home/user/project"),
"/home/user/project"
);
}
#[cfg(windows)]
#[test]
fn is_sensitive_path_windows_blocks_system_roots_and_subdirs() {
let blocked = [
r"\\?\C:\Windows\System32",
r"\\?\C:\Windows",
r"C:\Windows",
"C:/Windows",
r"C:\Windows\System32\drivers",
r"C:\Program Files\X",
r"C:\Program Files (x86)\Y\bin",
r"C:\ProgramData",
r"C:\ProgramData\some\creds",
r"C:\",
"C:/",
r"D:\",
];
for path in blocked {
assert!(
is_sensitive_path(Path::new(path)),
"expected `{path}` to be refused as sensitive"
);
}
}
#[cfg(windows)]
#[test]
fn is_sensitive_path_windows_blocks_user_profile_container_and_root() {
let blocked = [
r"C:\Users",
"C:/Users",
r"\\?\C:\Users",
r"C:\Users\victim",
"C:/Users/victim",
r"\\?\C:\Users\victim",
];
for path in blocked {
assert!(
is_sensitive_path(Path::new(path)),
"expected `{path}` to be refused as sensitive (profile container/root)"
);
}
}
#[cfg(windows)]
#[test]
fn is_sensitive_path_windows_allows_normal_project_paths() {
let allowed = [
r"\\?\C:\Users\me\project",
r"C:\Users\me\project",
r"C:\Users\me\projects\repo",
r"C:\Users\me\my-windows-project",
r"C:\Users\me\system32-emulator",
r"C:\dev\windows-tools\src",
r"\\?\UNC\server\share\proj",
];
for path in allowed {
assert!(
!is_sensitive_path(Path::new(path)),
"expected `{path}` to be allowed (not sensitive)"
);
}
}
#[cfg(unix)]
#[test]
fn is_sensitive_path_unix_blocks_roots_and_subdirs() {
let blocked = [
"/",
"/etc",
"/etc/passwd",
"/etc/sub",
"/usr",
"/usr/lib/x",
"/root",
"/Library",
"/System",
"/private",
"/home",
"/home/victim",
"/Users",
"/Users/victim",
"/mnt",
"/opt",
"/srv",
"/media",
"/tmp",
"/snap",
"/mnt/c",
"/mnt/c/Users",
"/mnt/c/Users/victim",
"/mnt/c/Windows",
"/mnt/c/Windows/System32",
"/mnt/c/Program Files/X",
"/mnt/c/ProgramData",
];
for path in blocked {
assert!(
is_sensitive_path(Path::new(path)),
"expected `{path}` to be refused as sensitive"
);
}
}
#[cfg(unix)]
#[test]
fn is_sensitive_path_unix_allows_normal_project_paths() {
let allowed = [
"/home/user/project",
"/home/me/repo",
"/home/user/etc-notes",
"/home/user/usr-local-clone",
"/home/me/etcd-client",
"/opt/app",
"/srv/site",
"/tmp/build/proj",
"/mnt/c/Users/me/project",
"/mnt/c/Users/me/repo",
"/mnt/d/dev/windows-tools",
"/mnt/c/code/proj",
];
for path in allowed {
assert!(
!is_sensitive_path(Path::new(path)),
"expected `{path}` to be allowed (not sensitive)"
);
}
}
}