Expand description
§DX Forge - Production-Ready VCS and Orchestration Engine
Forge is the orchestration backbone for the DX tools ecosystem, providing:
- Content-addressable storage with SHA-256 blob hashing
- Git-compatible versioning with traffic branch safety system
- Dual-watcher architecture (LSP + File System monitoring)
- Tool orchestration with priority-based execution and dependency resolution
- Component injection for zero-bloat dependency management
- Semantic versioning with dependency resolution
- Pattern detection for dx-tools (dxButton, dxiIcon, dxfRoboto, etc.)
- R2 component caching and injection
- Production error handling with retry logic
§Architecture Overview
Forge eliminates node_modules bloat by detecting code patterns via LSP, injecting only needed components directly into user files, and coordinating DX tool execution with traffic branch safety logic.
§Core Components
- Orchestrator: Coordinates tool execution with lifecycle hooks, circular dependency detection
- Dual-Watcher: Monitors LSP + file system changes with pattern detection
- Traffic Branch System: Green (auto), Yellow (merge), Red (manual) for safe updates
- Storage Layer: Content-addressable blobs with R2 cloud sync
- Version Manager: Semantic versioning with compatibility checking
- Pattern Detector: Identifies dx-tool patterns in source code
- Injection Manager: Fetches and caches components from R2 storage
§Quick Start - Tool Development
use dx_forge::{DxTool, ExecutionContext, ToolOutput, Orchestrator};
use async_trait::async_trait;
use anyhow::Result;
struct MyDxTool;
#[async_trait]
impl DxTool for MyDxTool {
fn name(&self) -> &str { "dx-mytool" }
fn version(&self) -> &str { "1.0.0" }
fn priority(&self) -> i32 { 50 }
async fn execute(&self, ctx: &ExecutionContext) -> Result<ToolOutput> {
// Your tool logic here
Ok(ToolOutput::success("Done!"))
}
}
#[tokio::main]
async fn main() -> Result<()> {
let mut orchestrator = Orchestrator::new(".")?;
orchestrator.register_tool(Box::new(MyDxTool));
orchestrator.execute_all().await?;
Ok(())
}§Quick Start - Change Detection
use dx_forge::{DualWatcher, FileChange};
use tokio::sync::broadcast;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let watcher = DualWatcher::new(".")?;
let mut rx = watcher.subscribe();
tokio::spawn(async move {
watcher.start().await
});
while let Ok(change) = rx.recv().await {
println!("Change detected: {:?} ({})", change.path, change.source);
}
Ok(())
}Re-exports§
pub use core::Forge;pub use core::ForgeConfig;pub use core::LifecycleEvent;pub use core::ToolId;pub use core::ToolStatus;pub use core::EditorInfo;pub use core::EditorType;pub use core::OutputStrategy;pub use core::GeneratedFileInfo;pub use orchestrator::Conflict;pub use orchestrator::DxTool;pub use orchestrator::ExecutionContext;pub use orchestrator::Orchestrator;pub use orchestrator::OrchestratorConfig;pub use orchestrator::ToolOutput;pub use orchestrator::TrafficAnalyzer;pub use orchestrator::TrafficBranch;pub use watcher::ChangeKind;pub use watcher::ChangeSource;pub use watcher::DualWatcher;pub use watcher::FileChange;pub use watcher::FileWatcher;pub use watcher::LspWatcher;pub use context::ComponentStateManager;pub use context::UpdateResult;pub use crdt::Operation;pub use crdt::OperationType;pub use crdt::Position;pub use storage::Database;pub use storage::OperationLog;pub use version::ToolInfo;pub use version::ToolRegistry;pub use version::ToolSource;pub use version::Version;pub use version::VersionReq;pub use version::Snapshot;pub use version::SnapshotId;pub use version::SnapshotManager;pub use version::Branch;pub use version::ToolState;pub use version::FileSnapshot;pub use version::SnapshotDiff;pub use patterns::DxToolType;pub use patterns::PatternDetector;pub use patterns::PatternMatch;pub use injection::CacheStats;pub use injection::ComponentMetadata;pub use injection::InjectionManager;pub use error::categorize_error;pub use error::EnhancedError;pub use error::EnhancedResult;pub use error::ErrorCategory;pub use error::RetryPolicy;pub use error::ToEnhanced;pub use error::with_retry;pub use watcher::DualWatcher as ForgeWatcher;pub use api::lifecycle::initialize_forge;pub use api::lifecycle::register_tool;pub use api::lifecycle::get_tool_context;pub use api::lifecycle::shutdown_forge;pub use api::version::declare_tool_version;pub use api::version::enforce_exact_version;pub use api::version::require_forge_minimum;pub use api::version::current_forge_version;pub use api::version::query_active_package_variant;pub use api::version::activate_package_variant;pub use api::pipeline::execute_pipeline;pub use api::pipeline::execute_tool_immediately;pub use api::pipeline::get_resolved_execution_order;pub use api::pipeline::temporarily_override_pipeline_order;pub use api::pipeline::restart_current_pipeline;pub use api::pipeline::suspend_pipeline_execution;pub use api::pipeline::resume_pipeline_execution;pub use api::reactivity::trigger_realtime_event;pub use api::reactivity::trigger_debounced_event;pub use api::reactivity::trigger_idle_event;pub use api::reactivity::begin_batch_operation;pub use api::reactivity::end_batch_operation;pub use api::branching::apply_changes;pub use api::branching::apply_changes_with_preapproved_votes;pub use api::branching::apply_changes_force_unchecked;pub use api::branching::preview_proposed_changes;pub use api::branching::automatically_accept_green_conflicts;pub use api::branching::prompt_review_for_yellow_conflicts;pub use api::branching::automatically_reject_red_conflicts;pub use api::branching::revert_most_recent_application;pub use api::branching::submit_branching_vote;pub use api::branching::register_permanent_branching_voter;pub use api::branching::query_predicted_branch_color;pub use api::branching::is_change_guaranteed_safe;pub use api::branching::issue_immediate_veto;pub use api::branching::reset_branching_engine_state;pub use api::branching::BranchColor;pub use api::branching::BranchingVote;pub use api::events::publish_event;pub use api::events::subscribe_to_event_stream;pub use api::events::emit_tool_started_event;pub use api::events::emit_tool_completed_event;pub use api::events::emit_pipeline_started_event;pub use api::events::emit_pipeline_completed_event;pub use api::events::emit_package_installation_begin;pub use api::events::emit_package_installation_success;pub use api::events::emit_security_violation_detected;pub use api::events::emit_magical_config_injection;pub use api::events::ForgeEvent;pub use api::config::get_active_config_file_path;pub use api::config::reload_configuration_manifest;pub use api::config::enable_live_config_watching;pub use api::config::inject_full_config_section_at_cursor;pub use api::config::expand_config_placeholder;pub use api::config::jump_to_config_section;pub use api::config::validate_config_in_realtime;pub use api::config::provide_config_completion_suggestions;pub use api::config::auto_format_config_file;pub use api::config::perform_config_schema_migration;pub use api::config::inject_style_tooling_config;pub use api::config::inject_authentication_config;pub use api::config::inject_ui_framework_config;pub use api::config::inject_icon_system_config;pub use api::config::inject_font_system_config;pub use api::config::inject_media_pipeline_config;pub use api::config::inject_package_specific_config;pub use api::cicd::trigger_ci_cd_pipeline;pub use api::cicd::register_ci_stage;pub use api::cicd::query_current_ci_status;pub use api::cicd::abort_running_ci_job;pub use api::cicd::synchronize_monorepo_workspace;pub use api::cicd::detect_workspace_root;pub use api::cicd::list_all_workspace_members;pub use api::cicd::broadcast_change_to_workspace;pub use api::dx_directory::get_dx_directory_path;pub use api::dx_directory::get_dx_binary_storage_path;pub use api::dx_directory::cache_tool_offline_binary;pub use api::dx_directory::load_tool_offline_binary;pub use api::dx_directory::commit_current_dx_state;pub use api::dx_directory::checkout_dx_state;pub use api::dx_directory::list_dx_history;pub use api::dx_directory::show_dx_state_diff;pub use api::dx_directory::push_dx_state_to_remote;pub use api::dx_directory::pull_dx_state_from_remote;pub use api::offline::detect_offline_mode;pub use api::offline::force_offline_operation;pub use api::offline::download_missing_tool_binaries;pub use api::offline::verify_binary_integrity_and_signature;pub use api::offline::update_tool_binary_atomically;pub use api::cart::stage_item_in_cart;pub use api::cart::commit_entire_cart;pub use api::cart::commit_cart_immediately;pub use api::cart::clear_cart_completely;pub use api::cart::remove_specific_cart_item;pub use api::cart::get_current_cart_contents;pub use api::cart::import_cart_from_json;pub use api::cart::CartItem;pub use api::packages::install_package_with_variant;pub use api::packages::uninstall_package_safely;pub use api::packages::update_package_intelligently;pub use api::packages::list_all_installed_packages;pub use api::packages::search_dx_package_registry;pub use api::packages::pin_package_to_exact_version;pub use api::packages::fork_existing_variant;pub use api::packages::publish_your_variant;pub use api::packages::PackageInfo;pub use api::codegen::mark_code_region_as_dx_generated;pub use api::codegen::is_region_dx_generated;pub use api::codegen::allow_safe_manual_edit_of_generated_code;pub use api::codegen::claim_full_ownership_of_file;pub use api::codegen::release_ownership_of_file;pub use api::dx_experience::project_root_directory;pub use api::dx_experience::path_to_forge_manifest;pub use api::dx_experience::dx_global_cache_directory;pub use api::dx_experience::create_watcher_ignored_scratch_file;pub use api::dx_experience::log_structured_tool_action;pub use api::dx_experience::schedule_task_for_idle_time;pub use api::dx_experience::await_editor_idle_state;pub use api::dx_experience::request_user_attention_flash;pub use api::dx_experience::open_file_and_reveal_location;pub use api::dx_experience::display_inline_code_suggestion;pub use api::dx_experience::apply_user_accepted_suggestion;pub use api::dx_experience::show_onboarding_welcome_tour;pub use api::dx_experience::execute_full_security_audit;pub use api::dx_experience::generate_comprehensive_project_report;pub use api::dx_experience::display_dx_command_palette;pub use api::dx_experience::open_embedded_dx_terminal;pub use api::dx_experience::trigger_ai_powered_suggestion;pub use api::dx_experience::apply_ai_generated_completion;pub use api::dx_experience::update_dx_status_bar_indicator;
Modules§
- api
- DX Forge Public API - The 132 Eternal Functions
- auto_
update - Auto-Update System with Green Traffic Support
- cache
- Multi-layer Caching System
- context
- core
- Core Forge functionality
- crdt
- error
- Production Error Handling and Retry Logic
- injection
- Component Injection System
- orchestrator
- Simple Orchestrator - Only controls WHEN to run tools
- patterns
- LSP Pattern Detection for DX Tools
- profiler
- Performance Profiler for Critical Paths
- server
- storage
- sync
- version
- Version control and tool registry
- watcher
- Dual-Watcher Architecture - LSP + File System monitoring
- watcher_
legacy
Macros§
- profile
- Profile a code block
Constants§
- VERSION
- Library version