Rule Files Sync

.cursor/rules/adr-001.mdc

@@ -0,0 +1,9 @@
+---
+alwaysApply: false
+---
+
+# Use Jotai For Global State Management
+
+## Policies
+
+1. Use Jotai for global state management

.cursor/rules/adr-002.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Core Library Module Structure with Standard Entry Points
+
+## Policies
+
+1. Libraries intended for command-line execution SHOULD provide a __main__.py file to enable 'python -m package_name' invocation

.cursor/rules/adr-003.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Public API Contracts for Design System Components
+
+## Policies
+
+1. Components MAY expose experimental APIs with explicit unstable markers that are exempt from semantic versioning guarantees

.cursor/rules/adr-004.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Public API Contracts for Design System Components
+
+## Policies
+
+1. Components SHOULD use naming conventions (e.g., underscore prefix) or visibility modifiers to distinguish private implementation from public API

.cursor/rules/adr-005.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Public API Contracts for Design System Components
+
+## Policies
+
+1. Public API contracts SHOULD be validated through automated tooling in the build pipeline to detect unintended exposure

.cursor/rules/adr-006.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Public API Contracts for Design System Components
+
+## Policies
+
+1. Breaking changes to public API contracts MUST follow semantic versioning with major version increments

.cursor/rules/adr-007.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Public API Contracts for Design System Components
+
+## Policies
+
+1. Internal implementation details, private methods, and undocumented properties MUST NOT be considered part of the public API contract

.cursor/rules/adr-008.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Public API Contracts for Design System Components
+
+## Policies
+
+1. Public API contracts MUST include component props, events, slots, methods, and CSS custom properties exposed for external use

.cursor/rules/adr-009.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Establish Public API Contracts for Design System Components
+
+## Policies
+
+1. All design system components MUST explicitly declare their public API surface through documented interfaces, type definitions, or API contracts

.cursor/rules/adr-010.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Build and CLI Tooling Configuration Patterns
+
+## Policies
+
+1. Teams MAY extend the base patterns with additional functionality provided core architectural principles are preserved

.cursor/rules/adr-011.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Build and CLI Tooling Configuration Patterns
+
+## Policies
+
+1. Dependency resolution and fixing utilities MUST NOT introduce alternative patterns that conflict with the established fix_dependencies.py approach

.cursor/rules/adr-012.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Build and CLI Tooling Configuration Patterns
+
+## Policies
+
+1. Build automation scripts SHOULD separate configuration, execution, and error handling concerns following the pattern established in build.py

.cursor/rules/adr-013.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Build and CLI Tooling Configuration Patterns
+
+## Policies
+
+1. New CLI commands SHOULD be structured using the same command registration and argument parsing patterns as existing tools in rulectl/cli.py

.cursor/rules/adr-014.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Build and CLI Tooling Configuration Patterns
+
+## Policies
+
+1. Dependency management and initialization logic MUST be centralized and follow consistent import and setup patterns across all tooling modules

.cursor/rules/adr-015.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Build and CLI Tooling Configuration Patterns
+
+## Policies
+
+1. All Python build scripts and CLI tools MUST follow the established configuration pattern detected in analyzer.py, baml_init.py, build.py, fix_dependencies.py, and cli.py

.cursor/rules/adr-016.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Script Structure with Argparse CLI and Modular Architecture
+
+## Policies
+
+1. Scripts MAY use subparsers for complex multi-command CLI tools

.cursor/rules/adr-017.mdc

@@ -0,0 +1,66 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# ADR 017: Standardize Python Script Structure with Argparse CLI and Modular Architecture
+
+## Context
+
+Python scripts require consistent structure for maintainability, testability, and CLI usability.
+
+## Decision
+
+Standardize Python scripts with argparse for CLI argument parsing and modular function-based architecture.
+
+## Policies
+
+1. Scripts SHALL use argparse for command-line argument parsing
+2. Main logic SHALL be encapsulated in functions, not at module level
+3. Scripts SHALL include a `if __name__ == "__main__":` guard
+4. Error handling SHOULD be implemented with clear error messages and appropriate exit codes
+5. Functions SHALL be single-purpose and independently testable
+6. Import statements SHALL follow PEP 8 ordering: standard library, third-party, local
+7. Scripts SHALL include docstrings for the module and all public functions
+8. Configuration values SHOULD be parameterized through CLI arguments or constants
+9. Script entry point SHALL call a main() function that orchestrates execution
+10. Return codes SHALL follow Unix conventions: 0 for success, non-zero for errors
+
+## Example Structure
+
+```python
+#!/usr/bin/env python3
+"""Module docstring describing script purpose."""
+
+import argparse
+import sys
+from typing import Optional
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(description="Script description")
+    parser.add_argument("--input", required=True, help="Input file path")
+    return parser.parse_args()
+
+
+def process_data(input_path: str) -> bool:
+    """Process data from input file."""
+    # Implementation
+    return True
+
+
+def main() -> int:
+    """Main entry point."""
+    args = parse_args()
+    try:
+        success = process_data(args.input)
+        return 0 if success else 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+```

.cursor/rules/adr-018.mdc

@@ -0,0 +1,24 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Script Structure with Argparse CLI and Modular Architecture
+
+## Policies
+
+1. Scripts SHOULD organize related functionality into separate functions that can be tested independently
+
+2. Scripts SHOULD use argparse for command-line argument parsing instead of sys.argv manipulation
+
+3. Scripts SHOULD define a main() function that serves as the primary entry point
+
+4. Scripts SHOULD use the if __name__ == "__main__" guard to enable both script execution and module import
+
+5. Scripts SHOULD separate business logic from argument parsing to improve testability
+
+6. Scripts SHOULD define argument parsers in a separate setup_parser() or create_parser() function
+
+7. Scripts SHOULD use meaningful function and variable names that clearly indicate their purpose
+
+8. Scripts SHOULD validate input arguments early and provide clear error messages for invalid inputs

.cursor/rules/adr-019.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Script Structure with Argparse CLI and Modular Architecture
+
+## Policies
+
+1. CLI tools SHOULD provide help text and descriptions for all arguments using argparse help parameter

.cursor/rules/adr-020.mdc

@@ -0,0 +1,28 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Standardize Python Script Structure with Argparse CLI and Modular Architecture
+
+## Policies
+
+1. Scripts MUST implement a main() function that serves as the primary entry point
+
+2. Scripts MUST use argparse module for command-line argument parsing
+
+3. Scripts MUST use if __name__ == "__main__": guard when executing main()
+
+4. Scripts SHOULD separate business logic into discrete, reusable functions
+
+5. Scripts SHOULD organize related functionality into separate modules
+
+6. Scripts MUST handle exceptions at appropriate levels with informative error messages
+
+7. Scripts SHOULD include docstrings for public functions and modules
+
+8. Scripts SHOULD use sys.exit() with appropriate exit codes for error conditions
+
+9. Parser definitions SHOULD be extracted into a separate function (e.g., create_parser())
+
+10. Configuration and constants SHOULD be defined at module level or in separate config modules

.cursor/rules/adr-021.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Script Structure with Argparse CLI and Modular Architecture
+
+## Policies
+
+1. CLI scripts MUST separate argument parsing logic from business logic through modular function design

.cursor/rules/adr-022.mdc

@@ -0,0 +1,14 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Standardize Python Script Structure with Argparse CLI and Modular Architecture
+
+## Policies
+
+1. All Python CLI scripts MUST use argparse for command-line argument parsing
+2. Scripts MUST separate business logic into reusable functions distinct from CLI interface code
+3. Main execution logic MUST be wrapped in `if __name__ == "__main__":` block
+4. CLI scripts MUST include `--help` documentation via argparse help text
+5. Argument parsers MUST define clear descriptions for all arguments and subcommands

.cursor/rules/adr-023.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Centralize Runtime Configuration Sources for Design System Theming
+
+## Policies
+
+1. Components MUST NOT directly access environment variables or configuration files; they MUST use the centralized configuration API

.cursor/rules/adr-024.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Centralize Runtime Configuration Sources for Design System Theming
+
+## Policies
+
+1. Configuration sources MAY include remote configuration services for enterprise deployments requiring centralized theme management

.cursor/rules/adr-025.mdc

@@ -0,0 +1,10 @@
+---
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# Centralize Runtime Configuration Sources for Design System Theming
+
+## Policies
+
+1. Configuration changes SHOULD be reactive, allowing theme updates without full application reload where technically feasible