refactor: migrate from directories to hierarchical paths module (#3309)

- Replace directories module with new paths module using PathResolver pattern
- Add workspace and global path scopes with clear separation of concerns
- Implement static path methods to avoid circular dependencies in Database/Settings
- Centralize all path constants and patterns in dedicated modules

This refactoring improves path management consistency and provides a cleaner,
more maintainable architecture for handling file system paths throughout
the application.

Author: dk19y

.gitignore

@@ -49,3 +49,4 @@ book/
 .env*
 
 run-build.sh
+.amazonq/

crates/chat-cli/src/auth/mod.rs

@@ -31,7 +31,7 @@ pub enum AuthError {
     #[error(transparent)]
     TimeComponentRange(#[from] time::error::ComponentRange),
     #[error(transparent)]
-    Directories(#[from] crate::util::directories::DirectoryError),
+    Directories(#[from] crate::util::paths::DirectoryError),
     #[error(transparent)]
     SerdeJson(#[from] serde_json::Error),
     #[error(transparent)]

crates/chat-cli/src/cli/agent/legacy/mod.rs

@@ -19,7 +19,7 @@ use crate::cli::agent::hook::Hook;
 use crate::cli::agent::legacy::context::LegacyContextConfig;
 use crate::os::Os;
 use crate::theme::StyledText;
-use crate::util::directories;
+use crate::util::paths::PathResolver;
 
 /// Performs the migration from legacy profile configuration to agent configuration if it hasn't
 /// already been done.
@@ -32,15 +32,16 @@ pub async fn migrate(os: &mut Os, force: bool) -> eyre::Result<Option<Vec<Agent>
         return Ok(None);
     }
 
-    let legacy_global_context_path = directories::chat_global_context_path(os)?;
+    let resolver = PathResolver::new(os);
+    let legacy_global_context_path = resolver.global().global_context()?;
     let legacy_global_context: Option<LegacyContextConfig> = 'global: {
         let Ok(content) = os.fs.read(&legacy_global_context_path).await else {
             break 'global None;
         };
         serde_json::from_slice::<LegacyContextConfig>(&content).ok()
     };
 
-    let legacy_profile_path = directories::chat_profiles_dir(os)?;
+    let legacy_profile_path = resolver.global().profiles_dir()?;
     let mut legacy_profiles: HashMap<String, LegacyContextConfig> = 'profiles: {
         let mut profiles = HashMap::<String, LegacyContextConfig>::new();
         let Ok(mut read_dir) = os.fs.read_dir(&legacy_profile_path).await else {
@@ -78,7 +79,7 @@ pub async fn migrate(os: &mut Os, force: bool) -> eyre::Result<Option<Vec<Agent>
     };
 
     let mcp_servers = {
-        let config_path = directories::chat_legacy_global_mcp_config(os)?;
+        let config_path = resolver.global().mcp_config()?;
         if os.fs.exists(&config_path) {
             match McpServerConfig::load_from_file(os, config_path).await {
                 Ok(mut config) => {
@@ -145,7 +146,12 @@ pub async fn migrate(os: &mut Os, force: bool) -> eyre::Result<Option<Vec<Agent>
         new_agents.push(Agent {
             name: LEGACY_GLOBAL_AGENT_NAME.to_string(),
             description: Some(DEFAULT_DESC.to_string()),
-            path: Some(directories::chat_global_agent_path(os)?.join(format!("{LEGACY_GLOBAL_AGENT_NAME}.json"))),
+            path: Some(
+                resolver
+                    .global()
+                    .agents_dir()?
+                    .join(format!("{LEGACY_GLOBAL_AGENT_NAME}.json")),
+            ),
             resources: context.paths.iter().map(|p| format!("file://{p}").into()).collect(),
             hooks: HashMap::from([
                 (
@@ -168,7 +174,7 @@ pub async fn migrate(os: &mut Os, force: bool) -> eyre::Result<Option<Vec<Agent>
         });
     }
 
-    let global_agent_path = directories::chat_global_agent_path(os)?;
+    let global_agent_path = resolver.global().ensure_agents_dir().await?;
 
     // Migration of profile context
     for (profile_name, context) in legacy_profiles.drain() {
@@ -205,10 +211,6 @@ pub async fn migrate(os: &mut Os, force: bool) -> eyre::Result<Option<Vec<Agent>
         });
     }
 
-    if !os.fs.exists(&global_agent_path) {
-        os.fs.create_dir_all(&global_agent_path).await?;
-    }
-
     for agent in &mut new_agents {
         let content = agent.to_str_pretty()?;
         if let Some(path) = agent.path.as_ref() {

crates/chat-cli/src/cli/agent/mod.rs

@@ -63,11 +63,12 @@ use crate::cli::agent::hook::{
 use crate::database::settings::Setting;
 use crate::os::Os;
 use crate::theme::StyledText;
+use crate::util::paths::PathResolver;
 use crate::util::{
     self,
     MCP_SERVER_TOOL_DELIMITER,
-    directories,
     file_uri,
+    paths,
 };
 
 pub const DEFAULT_AGENT_NAME: &str = "q_cli_default";
@@ -84,7 +85,7 @@ pub enum AgentConfigError {
         error: Box<jsonschema::ValidationError<'static>>,
     },
     #[error("Encountered directory error: {0}")]
-    Directories(#[from] util::directories::DirectoryError),
+    Directories(#[from] util::paths::DirectoryError),
     #[error("Encountered io error: {0}")]
     Io(#[from] std::io::Error),
     #[error("Failed to parse legacy mcp config: {0}")]
@@ -165,7 +166,7 @@ pub struct Agent {
     #[serde(default)]
     #[schemars(schema_with = "tool_settings_schema")]
     pub tools_settings: HashMap<ToolSettingTarget, serde_json::Value>,
-    /// Whether or not to include the legacy ~/.aws/amazonq/mcp.json in the agent
+    /// Whether or not to include the legacy global MCP configuration in the agent
     /// You can reference tools brought in by these servers as just as you would with the servers
     /// you configure in the mcpServers field in this config
     #[serde(default)]
@@ -193,15 +194,12 @@ impl Default for Agent {
                 set.extend(default_approve);
                 set
             },
-            resources: vec![
-                "file://AmazonQ.md",
-                "file://AGENTS.md",
-                "file://README.md",
-                "file://.amazonq/rules/**/*.md",
-            ]
-            .into_iter()
-            .map(Into::into)
-            .collect::<Vec<_>>(),
+            resources: {
+                let mut resources = Vec::new();
+                resources.extend(paths::workspace::DEFAULT_AGENT_RESOURCES.iter().map(|&s| s.into()));
+                resources.push(format!("file://{}", paths::workspace::RULES_PATTERN).into());
+                resources
+            },
             hooks: Default::default(),
             tools_settings: Default::default(),
             use_legacy_mcp_json: true,
@@ -342,14 +340,15 @@ impl Agent {
     /// Retrieves an agent by name. It does so via first seeking the given agent under local dir,
     /// and falling back to global dir if it does not exist in local.
     pub async fn get_agent_by_name(os: &Os, agent_name: &str) -> eyre::Result<(Agent, PathBuf)> {
+        let resolver = PathResolver::new(os);
         let config_path: Result<PathBuf, PathBuf> = 'config: {
             // local first, and then fall back to looking at global
-            let local_config_dir = directories::chat_local_agent_dir(os)?.join(format!("{agent_name}.json"));
+            let local_config_dir = resolver.workspace().agents_dir()?.join(format!("{agent_name}.json"));
             if os.fs.exists(&local_config_dir) {
                 break 'config Ok(local_config_dir);
             }
 
-            let global_config_dir = directories::chat_global_agent_path(os)?.join(format!("{agent_name}.json"));
+            let global_config_dir = resolver.global().agents_dir()?.join(format!("{agent_name}.json"));
             if os.fs.exists(&global_config_dir) {
                 break 'config Ok(global_config_dir);
             }
@@ -542,20 +541,21 @@ impl Agents {
             vec![]
         };
 
+        let resolver = PathResolver::new(os);
         let mut global_mcp_config = None::<McpServerConfig>;
 
         let mut local_agents = 'local: {
             // We could be launching from the home dir, in which case the global and local agents
             // are the same set of agents. If that is the case, we simply skip this.
-            match (std::env::current_dir(), directories::home_dir(os)) {
+            match (std::env::current_dir(), paths::home_dir(os)) {
                 (Ok(cwd), Ok(home_dir)) if cwd == home_dir => break 'local Vec::<Agent>::new(),
                 _ => {
                     // noop, we keep going with the extraction of local agents (even if we have an
                     // error retrieving cwd or home_dir)
                 },
             }
 
-            let Ok(path) = directories::chat_local_agent_dir(os) else {
+            let Ok(path) = resolver.workspace().agents_dir() else {
                 break 'local Vec::<Agent>::new();
             };
             let Ok(files) = os.fs.read_dir(path).await else {
@@ -585,7 +585,7 @@ impl Agents {
         };
 
         let mut global_agents = 'global: {
-            let Ok(path) = directories::chat_global_agent_path(os) else {
+            let Ok(path) = resolver.global().agents_dir() else {
                 break 'global Vec::<Agent>::new();
             };
             let files = match os.fs.read_dir(&path).await {
@@ -629,10 +629,11 @@ impl Agents {
         // there.
         // Note that this config is not what q chat uses. It merely serves as an example.
         'example_config: {
-            let Ok(path) = directories::example_agent_config(os) else {
+            let Ok(agents_dir) = resolver.global().agents_dir() else {
                 error!("Error obtaining example agent path.");
                 break 'example_config;
             };
+            let path = agents_dir.join("agent_config.json.example");
             if os.fs.exists(&path) {
                 break 'example_config;
             }
@@ -744,7 +745,7 @@ impl Agents {
                 if mcp_enabled {
                     'load_legacy_mcp_json: {
                         if global_mcp_config.is_none() {
-                            let Ok(global_mcp_path) = directories::chat_legacy_global_mcp_config(os) else {
+                            let Ok(global_mcp_path) = resolver.global().mcp_config() else {
                                 tracing::error!("Error obtaining legacy mcp json path. Skipping");
                                 break 'load_legacy_mcp_json;
                             };
@@ -906,7 +907,8 @@ async fn load_agents_from_entries(
 /// Loads legacy mcp config by combining workspace and global config.
 /// In case of a server naming conflict, the workspace config is prioritized.
 async fn load_legacy_mcp_config(os: &Os) -> eyre::Result<Option<McpServerConfig>> {
-    let global_mcp_path = directories::chat_legacy_global_mcp_config(os)?;
+    let resolver = PathResolver::new(os);
+    let global_mcp_path = resolver.global().mcp_config()?;
     let global_mcp_config = match McpServerConfig::load_from_file(os, global_mcp_path).await {
         Ok(config) => Some(config),
         Err(e) => {
@@ -915,7 +917,7 @@ async fn load_legacy_mcp_config(os: &Os) -> eyre::Result<Option<McpServerConfig>
         },
     };
 
-    let workspace_mcp_path = directories::chat_legacy_workspace_mcp_config(os)?;
+    let workspace_mcp_path = resolver.workspace().mcp_config()?;
     let workspace_mcp_config = match McpServerConfig::load_from_file(os, workspace_mcp_path).await {
         Ok(config) => Some(config),
         Err(e) => {

crates/chat-cli/src/cli/agent/root_command_args.rs

@@ -25,7 +25,8 @@ use super::{
 use crate::database::settings::Setting;
 use crate::os::Os;
 use crate::theme::StyledText;
-use crate::util::directories;
+use crate::util::paths;
+use crate::util::paths::PathResolver;
 
 #[derive(Clone, Debug, Subcommand, PartialEq, Eq)]
 pub enum AgentSubcommands {
@@ -336,9 +337,9 @@ pub async fn create_agent(
             bail!("Path must be a directory");
         }
 
-        directories::agent_config_dir(path)?
+        path.join(paths::workspace::AGENTS_DIR)
     } else {
-        directories::chat_global_agent_path(os)?
+        PathResolver::new(os).global().agents_dir()?
     };
 
     if let Some((name, _)) = agents.agents.iter().find(|(agent_name, agent)| {

crates/chat-cli/src/cli/chat/cli/checkpoint.rs

@@ -28,7 +28,7 @@ use crate::cli::experiment::experiment_manager::{
 };
 use crate::os::Os;
 use crate::theme::StyledText;
-use crate::util::directories::get_shadow_repo_dir;
+use crate::util::paths::PathResolver;
 
 #[derive(Debug, PartialEq, Subcommand)]
 pub enum CheckpointSubcommand {
@@ -134,8 +134,11 @@ impl CheckpointSubcommand {
                 StyledText::reset(),
             )?;
         } else {
-            let path = get_shadow_repo_dir(os, session.conversation.conversation_id().to_string())
-                .map_err(|e| ChatError::Custom(e.to_string().into()))?;
+            let path = PathResolver::new(os)
+                .global()
+                .shadow_repo_dir()
+                .map_err(|e| ChatError::Custom(e.to_string().into()))?
+                .join(session.conversation.conversation_id());
 
             let start = std::time::Instant::now();
             session.conversation.checkpoint_manager = Some(

crates/chat-cli/src/cli/chat/cli/logdump.rs

@@ -19,7 +19,7 @@ use crate::cli::chat::{
     ChatState,
 };
 use crate::theme::StyledText;
-use crate::util::directories::logs_dir;
+use crate::util::paths::logs_dir;
 
 /// Arguments for the logdump command that collects logs for support investigation
 #[derive(Debug, PartialEq, Args)]

crates/chat-cli/src/cli/chat/cli/profile.rs

@@ -41,11 +41,8 @@ use crate::cli::chat::{
 use crate::database::settings::Setting;
 use crate::os::Os;
 use crate::theme::StyledText;
-use crate::util::directories::chat_global_agent_path;
-use crate::util::{
-    NullWriter,
-    directories,
-};
+use crate::util::NullWriter;
+use crate::util::paths::PathResolver;
 
 #[deny(missing_docs)]
 #[derive(Debug, PartialEq, Subcommand)]
@@ -54,7 +51,7 @@ use crate::util::{
 
 Notes
 • Launch q chat with a specific agent with --agent
-• Construct an agent under ~/.aws/amazonq/cli-agents/ (accessible globally) or cwd/.amazonq/cli-agents (accessible in workspace)
+• Construct an agent in the global agents directory (accessible globally) or workspace agents directory (accessible in workspace)
 • See example config under global directory
 • Set default agent to assume with settings by running \"q settings chat.defaultAgent agent_name\"
 • Each agent maintains its own set of context and customizations"
@@ -395,7 +392,7 @@ impl AgentSubcommand {
                 // switch / create profile after a session has started.
                 // TODO: perhaps revive this after we have a decision on profile create /
                 // switch
-                let global_path = if let Ok(path) = chat_global_agent_path(os) {
+                let global_path = if let Ok(path) = PathResolver::new(os).global().agents_dir() {
                     path.to_str().unwrap_or("default global agent path").to_string()
                 } else {
                     "default global agent path".to_string()
@@ -537,8 +534,10 @@ pub async fn get_all_available_mcp_servers(os: &mut Os) -> Result<Vec<McpServerI
         }
     }
 
+    let resolver = PathResolver::new(os);
+
     // 2. Load from workspace legacy config (medium priority)
-    if let Ok(workspace_path) = directories::chat_legacy_workspace_mcp_config(os) {
+    if let Ok(workspace_path) = resolver.workspace().mcp_config() {
         if let Ok(workspace_config) = McpServerConfig::load_from_file(os, workspace_path).await {
             for (server_name, server_config) in workspace_config.mcp_servers {
                 if !servers.values().any(|s| s.config.command == server_config.command) {
@@ -552,7 +551,7 @@ pub async fn get_all_available_mcp_servers(os: &mut Os) -> Result<Vec<McpServerI
     }
 
     // 3. Load from global legacy config (lowest priority)
-    if let Ok(global_path) = directories::chat_legacy_global_mcp_config(os) {
+    if let Ok(global_path) = resolver.global().mcp_config() {
         if let Ok(global_config) = McpServerConfig::load_from_file(os, global_path).await {
             for (server_name, server_config) in global_config.mcp_servers {
                 if !servers.values().any(|s| s.config.command == server_config.command) {