Investigate consolidating file import logic across @ commands, memory imports, and custom commands

[allenhutchison]

Background

Currently, we have three separate systems that handle @-based file references:

1. Memory Import Processor (packages/core/src/utils/memoryImportProcessor.ts): Processes @path directives in markdown files (e.g., GEMINI.md) to import content from other files during memory/context processing.

2. At Command Processor (packages/cli/src/ui/hooks/atCommandProcessor.ts): Handles @path syntax in user chat queries to dynamically read files using the read_many_files tool.

3. At File Processor (packages/cli/src/services/prompt-processors/atFileProcessor.ts): Processes @{path} syntax in custom slash commands (.toml files) to inject file content.

Current Overlap

All three systems independently implement similar functionality:

• Parsing @ symbols followed by file paths
• Path resolution and validation
• File reading logic
• Error handling
• Support for directories and glob patterns

Additionally, the first two systems share:

• Code region detection (to avoid processing @ symbols inside code blocks)
• Similar output formatting

Syntax Differences

• Memory imports and at commands: @path/to/file.txt
• Custom command injection: @{path/to/file.txt}

Related Context

This came up during PR #10201, which fixed a bug in the memory import processor's code region detection logic. The fix involved carefully handling nested markdown tokens to ensure @ symbols inside code blocks are not treated as import directives.

Proposal

Investigate whether it's feasible to consolidate the shared logic between these three systems into common utilities. This could potentially:

Benefits:

• Reduce code duplication across three separate systems
• Ensure consistent behavior across all @-based file reference features
• Make bug fixes (like the code region detection fix) apply to all systems automatically
• Potentially unify the syntax (@path vs @{path})
• Simplify testing and maintenance
• Provide a unified interface for file path parsing and resolution

Potential Challenges:

• The three systems have different contexts and use cases:
  • Memory imports: Processed at file load time with recursive import support and circular dependency protection
  • At commands: Processed at chat time using the tool system
  • Custom commands: Processed during command expansion with shell and argument injection
• Different output formats (flat vs. tree for memory imports, tool invocations for at commands, inline for custom commands)
• Different error handling requirements and user feedback mechanisms
• Syntax differences may be intentional to distinguish contexts
• May need to preserve existing APIs for backward compatibility

Suggested Investigation

1. Audit all three systems to identify truly shared logic vs. context-specific logic
2. Determine if a common parsing/validation/resolution layer would be beneficial
3. Assess whether the code region detection logic from findCodeRegions() should apply to at commands and custom commands
4. Evaluate if syntax could be unified without breaking changes
5. Propose a design for shared utilities if consolidation makes sense
6. Consider whether this would be a breaking change or could be done incrementally

Questions

• Should at commands and custom command injection also respect code blocks (i.e., ignore @path inside `code` spans)?
• Can we extract a common FileReferenceParser or FileInjectionService abstraction?
• Should we unify the syntax (@path vs @{path}), or is the distinction useful?
• Would this consolidation simplify or complicate the architecture?
• Could we create a migration path for unifying syntax if desired?

[allenhutchison]

/cc @abhipatel12

[github-actions[bot]]

This issue has been automatically marked as stale due to 60 days of inactivity. It will be closed in 14 days if no further activity occurs.