diff --git a/.cursor/rules/adr-001.mdc b/.cursor/rules/adr-001.mdc new file mode 100644 index 0000000..3ca90a1 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-002.mdc b/.cursor/rules/adr-002.mdc new file mode 100644 index 0000000..08ad166 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-003.mdc b/.cursor/rules/adr-003.mdc new file mode 100644 index 0000000..e3f2fdf --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-004.mdc b/.cursor/rules/adr-004.mdc new file mode 100644 index 0000000..4780ef8 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-005.mdc b/.cursor/rules/adr-005.mdc new file mode 100644 index 0000000..05ca41e --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-006.mdc b/.cursor/rules/adr-006.mdc new file mode 100644 index 0000000..a4c3344 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-007.mdc b/.cursor/rules/adr-007.mdc new file mode 100644 index 0000000..b063bb0 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-008.mdc b/.cursor/rules/adr-008.mdc new file mode 100644 index 0000000..5c5a619 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-009.mdc b/.cursor/rules/adr-009.mdc new file mode 100644 index 0000000..6902145 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-010.mdc b/.cursor/rules/adr-010.mdc new file mode 100644 index 0000000..c787cda --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-011.mdc b/.cursor/rules/adr-011.mdc new file mode 100644 index 0000000..4070cfb --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-012.mdc b/.cursor/rules/adr-012.mdc new file mode 100644 index 0000000..440db8c --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-013.mdc b/.cursor/rules/adr-013.mdc new file mode 100644 index 0000000..1864605 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-014.mdc b/.cursor/rules/adr-014.mdc new file mode 100644 index 0000000..c7f38e6 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-015.mdc b/.cursor/rules/adr-015.mdc new file mode 100644 index 0000000..7289fb0 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-016.mdc b/.cursor/rules/adr-016.mdc new file mode 100644 index 0000000..62c7185 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-017.mdc b/.cursor/rules/adr-017.mdc new file mode 100644 index 0000000..b97e504 --- /dev/null +++ b/.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()) +``` \ No newline at end of file diff --git a/.cursor/rules/adr-018.mdc b/.cursor/rules/adr-018.mdc new file mode 100644 index 0000000..70453f5 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-019.mdc b/.cursor/rules/adr-019.mdc new file mode 100644 index 0000000..f9f8d1b --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-020.mdc b/.cursor/rules/adr-020.mdc new file mode 100644 index 0000000..b8a90a8 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-021.mdc b/.cursor/rules/adr-021.mdc new file mode 100644 index 0000000..5576850 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-022.mdc b/.cursor/rules/adr-022.mdc new file mode 100644 index 0000000..e9fc71e --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-023.mdc b/.cursor/rules/adr-023.mdc new file mode 100644 index 0000000..c91d62e --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-024.mdc b/.cursor/rules/adr-024.mdc new file mode 100644 index 0000000..4bfe697 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-025.mdc b/.cursor/rules/adr-025.mdc new file mode 100644 index 0000000..0547460 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/adr-026.mdc b/.cursor/rules/adr-026.mdc new file mode 100644 index 0000000..c4552c4 --- /dev/null +++ b/.cursor/rules/adr-026.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Centralize Runtime Configuration Sources for Design System Theming + +## Policies + +1. Theme configuration SHOULD be validated at runtime to ensure type safety and prevent invalid values from propagating \ No newline at end of file diff --git a/.cursor/rules/adr-027.mdc b/.cursor/rules/adr-027.mdc new file mode 100644 index 0000000..d1be559 --- /dev/null +++ b/.cursor/rules/adr-027.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Centralize Runtime Configuration Sources for Design System Theming + +## Policies + +1. Configuration sources MUST be accessible through a consistent API or interface across all modules that require theming \ No newline at end of file diff --git a/.cursor/rules/adr-028.mdc b/.cursor/rules/adr-028.mdc new file mode 100644 index 0000000..2808451 --- /dev/null +++ b/.cursor/rules/adr-028.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Centralize Runtime Configuration Sources for Design System Theming + +## Policies + +1. Runtime configuration sources MUST support hierarchical precedence (e.g., environment variables > user preferences > defaults) \ No newline at end of file diff --git a/.cursor/rules/adr-029.mdc b/.cursor/rules/adr-029.mdc new file mode 100644 index 0000000..8898fe7 --- /dev/null +++ b/.cursor/rules/adr-029.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Centralize Runtime Configuration Sources for Design System Theming + +## Policies + +1. All design system theme configuration MUST be sourced from centralized runtime configuration sources rather than hardcoded values \ No newline at end of file diff --git a/.cursor/rules/adr-030.mdc b/.cursor/rules/adr-030.mdc new file mode 100644 index 0000000..e81c7e1 --- /dev/null +++ b/.cursor/rules/adr-030.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Establish Core Library Module Structure with Standard Entry Points + +## Policies + +1. Libraries MAY include utility modules for cross-cutting concerns such as warning suppression, logging configuration, or environment setup \ No newline at end of file diff --git a/.cursor/rules/adr-031.mdc b/.cursor/rules/adr-031.mdc new file mode 100644 index 0000000..56825f4 --- /dev/null +++ b/.cursor/rules/adr-031.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Establish Core Library Module Structure with Standard Entry Points + +## Policies + +1. Library __init__.py files SHOULD NOT contain complex business logic or perform expensive operations at import time \ No newline at end of file diff --git a/.cursor/rules/adr-032.mdc b/.cursor/rules/adr-032.mdc new file mode 100644 index 0000000..751e217 --- /dev/null +++ b/.cursor/rules/adr-032.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Establish Core Library Module Structure with Standard Entry Points + +## Policies + +1. Package structure MUST follow Python namespace conventions with clear separation between public API and internal implementation \ No newline at end of file diff --git a/.cursor/rules/adr-033.mdc b/.cursor/rules/adr-033.mdc new file mode 100644 index 0000000..98637da --- /dev/null +++ b/.cursor/rules/adr-033.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Establish Core Library Module Structure with Standard Entry Points + +## Policies + +1. Library initialization code SHOULD handle runtime warnings and error conditions gracefully through dedicated utility modules \ No newline at end of file diff --git a/.cursor/rules/adr-034.mdc b/.cursor/rules/adr-034.mdc new file mode 100644 index 0000000..39fa099 --- /dev/null +++ b/.cursor/rules/adr-034.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Establish Core Library Module Structure with Standard Entry Points + +## Policies + +1. Distributable libraries MUST include a setup.py or pyproject.toml file with complete package metadata including name, version, dependencies, and entry points \ No newline at end of file diff --git a/.cursor/rules/adr-035.mdc b/.cursor/rules/adr-035.mdc new file mode 100644 index 0000000..5ea9f42 --- /dev/null +++ b/.cursor/rules/adr-035.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Establish Core Library Module Structure with Standard Entry Points + +## Policies + +1. All Python library packages MUST include an __init__.py file to define the package namespace and public API surface \ No newline at end of file diff --git a/.cursor/rules/adr-036.mdc b/.cursor/rules/adr-036.mdc new file mode 100644 index 0000000..c9beb67 --- /dev/null +++ b/.cursor/rules/adr-036.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for Public API Endpoints + +## Policies + +1. Different API endpoints MAY have different rate limit tiers based on resource intensity and business requirements \ No newline at end of file diff --git a/.cursor/rules/adr-037.mdc b/.cursor/rules/adr-037.mdc new file mode 100644 index 0000000..d989991 --- /dev/null +++ b/.cursor/rules/adr-037.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for Public API Endpoints + +## Policies + +1. API responses SHOULD include rate limit status headers (e.g., X-RateLimit-Remaining, X-RateLimit-Reset) to inform clients \ No newline at end of file diff --git a/.cursor/rules/adr-038.mdc b/.cursor/rules/adr-038.mdc new file mode 100644 index 0000000..ae32a90 --- /dev/null +++ b/.cursor/rules/adr-038.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for Public API Endpoints + +## Policies + +1. Rate limit violations SHOULD return HTTP 429 (Too Many Requests) with appropriate retry-after headers \ No newline at end of file diff --git a/.cursor/rules/adr-039.mdc b/.cursor/rules/adr-039.mdc new file mode 100644 index 0000000..fd80a1c --- /dev/null +++ b/.cursor/rules/adr-039.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for Public API Endpoints + +## Policies + +1. Rate limiting logic SHOULD be centralized in dedicated utility modules (e.g., rate_limiter.py, token_tracker.py) to ensure consistency \ No newline at end of file diff --git a/.cursor/rules/adr-040.mdc b/.cursor/rules/adr-040.mdc new file mode 100644 index 0000000..1dbd659 --- /dev/null +++ b/.cursor/rules/adr-040.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for Public API Endpoints + +## Policies + +1. Token tracking mechanisms MUST be implemented to monitor API usage patterns and enforce quota limits \ No newline at end of file diff --git a/.cursor/rules/adr-041.mdc b/.cursor/rules/adr-041.mdc new file mode 100644 index 0000000..d727224 --- /dev/null +++ b/.cursor/rules/adr-041.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for Public API Endpoints + +## Policies + +1. API rate limiters MUST track consumption on a per-client or per-token basis to enforce individual quotas \ No newline at end of file diff --git a/.cursor/rules/adr-042.mdc b/.cursor/rules/adr-042.mdc new file mode 100644 index 0000000..7e92fc2 --- /dev/null +++ b/.cursor/rules/adr-042.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for Public API Endpoints + +## Policies + +1. All public-facing API endpoints MUST implement rate limiting to prevent resource exhaustion and abuse \ No newline at end of file diff --git a/.cursor/rules/adr-043.mdc b/.cursor/rules/adr-043.mdc new file mode 100644 index 0000000..e2c39d5 --- /dev/null +++ b/.cursor/rules/adr-043.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. Systems MAY implement circuit breakers in conjunction with rate limiters to fail fast when external APIs are consistently unavailable \ No newline at end of file diff --git a/.cursor/rules/adr-044.mdc b/.cursor/rules/adr-044.mdc new file mode 100644 index 0000000..43b51af --- /dev/null +++ b/.cursor/rules/adr-044.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. Utility functions interacting with external APIs SHOULD encapsulate rate limiting and token tracking logic to ensure consistent application \ No newline at end of file diff --git a/.cursor/rules/adr-045.mdc b/.cursor/rules/adr-045.mdc new file mode 100644 index 0000000..c4f1e3c --- /dev/null +++ b/.cursor/rules/adr-045.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. Rate limiting configuration MUST be externalized and configurable per API provider without code changes \ No newline at end of file diff --git a/.cursor/rules/adr-046.mdc b/.cursor/rules/adr-046.mdc new file mode 100644 index 0000000..7b781c6 --- /dev/null +++ b/.cursor/rules/adr-046.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. Token tracking SHOULD provide visibility into consumption patterns through logging and metrics for capacity planning \ No newline at end of file diff --git a/.cursor/rules/adr-047.mdc b/.cursor/rules/adr-047.mdc new file mode 100644 index 0000000..87c18d5 --- /dev/null +++ b/.cursor/rules/adr-047.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. API clients SHOULD pre-emptively throttle requests when approaching known rate limits rather than waiting for 429 responses \ No newline at end of file diff --git a/.cursor/rules/adr-048.mdc b/.cursor/rules/adr-048.mdc new file mode 100644 index 0000000..ca04f7e --- /dev/null +++ b/.cursor/rules/adr-048.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. Rate limiters MUST implement exponential backoff with jitter when rate limits are exceeded to prevent thundering herd problems \ No newline at end of file diff --git a/.cursor/rules/adr-049.mdc b/.cursor/rules/adr-049.mdc new file mode 100644 index 0000000..44a5b33 --- /dev/null +++ b/.cursor/rules/adr-049.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. Token consumption MUST be tracked and monitored using a dedicated token tracker for APIs with token-based billing or quota systems \ No newline at end of file diff --git a/.cursor/rules/adr-050.mdc b/.cursor/rules/adr-050.mdc new file mode 100644 index 0000000..4d665d5 --- /dev/null +++ b/.cursor/rules/adr-050.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Implement Rate Limiting and Token Tracking for External API Interactions + +## Policies + +1. All external API clients MUST implement rate limiting using a centralized rate limiter component to enforce provider-specific rate limits \ No newline at end of file diff --git a/.cursor/rules/adr-051.mdc b/.cursor/rules/adr-051.mdc new file mode 100644 index 0000000..e6d19b8 --- /dev/null +++ b/.cursor/rules/adr-051.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. External API clients MAY implement caching strategies to reduce API calls and improve performance where appropriate \ No newline at end of file diff --git a/.cursor/rules/adr-052.mdc b/.cursor/rules/adr-052.mdc new file mode 100644 index 0000000..042b587 --- /dev/null +++ b/.cursor/rules/adr-052.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. External API client modules SHOULD expose consistent interfaces (e.g., common base classes or protocols) to enable polymorphic usage and dependency injection \ No newline at end of file diff --git a/.cursor/rules/adr-053.mdc b/.cursor/rules/adr-053.mdc new file mode 100644 index 0000000..0f56ad5 --- /dev/null +++ b/.cursor/rules/adr-053.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. API credentials and tokens MUST be stored in environment variables or secure credential stores, never hardcoded in source files \ No newline at end of file diff --git a/.cursor/rules/adr-054.mdc b/.cursor/rules/adr-054.mdc new file mode 100644 index 0000000..2d22d5d --- /dev/null +++ b/.cursor/rules/adr-054.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. External API integrations SHOULD provide mock implementations or test doubles to enable offline development and testing \ No newline at end of file diff --git a/.cursor/rules/adr-055.mdc b/.cursor/rules/adr-055.mdc new file mode 100644 index 0000000..8ba7bb5 --- /dev/null +++ b/.cursor/rules/adr-055.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. External API clients SHOULD implement usage tracking and logging to monitor API consumption, costs, and performance metrics \ No newline at end of file diff --git a/.cursor/rules/adr-056.mdc b/.cursor/rules/adr-056.mdc new file mode 100644 index 0000000..6930c7d --- /dev/null +++ b/.cursor/rules/adr-056.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. All external API calls MUST be wrapped in try-except blocks with specific exception handling for network, authentication, and API-specific errors \ No newline at end of file diff --git a/.cursor/rules/adr-057.mdc b/.cursor/rules/adr-057.mdc new file mode 100644 index 0000000..dec10f6 --- /dev/null +++ b/.cursor/rules/adr-057.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. External API client modules MUST handle rate limiting, timeouts, and transient failures with exponential backoff retry logic \ No newline at end of file diff --git a/.cursor/rules/adr-058.mdc b/.cursor/rules/adr-058.mdc new file mode 100644 index 0000000..a1874b2 --- /dev/null +++ b/.cursor/rules/adr-058.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**/*"] +alwaysApply: false +--- + +# Standardize External API Client Integration Patterns + +## Policies + +1. All external API clients MUST implement explicit authentication token management with tracking and refresh capabilities \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5f3b3a0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,84 @@ +## Project Structure & Module Organization + +1. All Python library packages MUST include an __init__.py file to define the package namespace and public API surface +2. Distributable libraries MUST include a setup.py or pyproject.toml file with complete package metadata including name, version, dependencies, and entry points +3. Library initialization code SHOULD handle runtime warnings and error conditions gracefully through dedicated utility modules +4. Package structure MUST follow Python namespace conventions with clear separation between public API and internal implementation +5. Library __init__.py files SHOULD NOT contain complex business logic or perform expensive operations at import time +6. Libraries MAY include utility modules for cross-cutting concerns such as warning suppression, logging configuration, or environment setup +7. Libraries intended for command-line execution SHOULD provide a __main__.py file to enable 'python -m package_name' invocation + +## Build, Test, and Development Commands + +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 +2. Dependency management and initialization logic MUST be centralized and follow consistent import and setup patterns across all tooling modules +3. Build automation scripts SHOULD separate configuration, execution, and error handling concerns following the pattern established in build.py +4. Dependency resolution and fixing utilities MUST NOT introduce alternative patterns that conflict with the established fix_dependencies.py approach +5. Teams MAY extend the base patterns with additional functionality provided core architectural principles are preserved + +## Coding Style & Naming Conventions + +1. Use Jotai for global state management +2. All Python CLI scripts MUST use argparse for command-line argument parsing +3. CLI scripts MUST separate argument parsing logic from business logic through modular function design +4. Scripts MUST implement a main() function that serves as the primary entry point +5. CLI tools SHOULD provide help text and descriptions for all arguments using argparse help parameter +6. Scripts SHOULD organize related functionality into separate functions that can be tested independently +7. Error handling SHOULD be implemented with clear error messages and appropriate exit codes +8. Scripts MAY use subparsers for complex multi-command CLI tools +9. New CLI commands SHOULD be structured using the same command registration and argument parsing patterns as existing tools in rulectl/cli.py +10. Components SHOULD use naming conventions (e.g., underscore prefix) or visibility modifiers to distinguish private implementation from public API + +## Testing Guidelines + +1. External API integrations SHOULD provide mock implementations or test doubles to enable offline development and testing + +## Commit & Pull Request Guidelines + +1. Breaking changes to public API contracts MUST follow semantic versioning with major version increments + +## Security & Configuration Tips + +1. All design system theme configuration MUST be sourced from centralized runtime configuration sources rather than hardcoded values +2. Runtime configuration sources MUST support hierarchical precedence (e.g., environment variables > user preferences > defaults) +3. Configuration sources MUST be accessible through a consistent API or interface across all modules that require theming +4. Theme configuration SHOULD be validated at runtime to ensure type safety and prevent invalid values from propagating +5. Configuration changes SHOULD be reactive, allowing theme updates without full application reload where technically feasible +6. Configuration sources MAY include remote configuration services for enterprise deployments requiring centralized theme management +7. Components MUST NOT directly access environment variables or configuration files; they MUST use the centralized configuration API +8. API credentials and tokens MUST be stored in environment variables or secure credential stores, never hardcoded in source files + +## Public API Design & Contracts + +1. All design system components MUST explicitly declare their public API surface through documented interfaces, type definitions, or API contracts +2. Public API contracts MUST include component props, events, slots, methods, and CSS custom properties exposed for external use +3. Internal implementation details, private methods, and undocumented properties MUST NOT be considered part of the public API contract +4. Public API contracts SHOULD be validated through automated tooling in the build pipeline to detect unintended exposure +5. Components MAY expose experimental APIs with explicit unstable markers that are exempt from semantic versioning guarantees + +## External API Integration & Rate Limiting + +1. All external API clients MUST implement explicit authentication token management with tracking and refresh capabilities +2. External API client modules MUST handle rate limiting, timeouts, and transient failures with exponential backoff retry logic +3. All external API calls MUST be wrapped in try-except blocks with specific exception handling for network, authentication, and API-specific errors +4. External API clients SHOULD implement usage tracking and logging to monitor API consumption, costs, and performance metrics +5. External API client modules SHOULD expose consistent interfaces (e.g., common base classes or protocols) to enable polymorphic usage and dependency injection +6. External API clients MAY implement caching strategies to reduce API calls and improve performance where appropriate +7. All external API clients MUST implement rate limiting using a centralized rate limiter component to enforce provider-specific rate limits +8. Token consumption MUST be tracked and monitored using a dedicated token tracker for APIs with token-based billing or quota systems +9. Rate limiters MUST implement exponential backoff with jitter when rate limits are exceeded to prevent thundering herd problems +10. API clients SHOULD pre-emptively throttle requests when approaching known rate limits rather than waiting for 429 responses +11. Token tracking SHOULD provide visibility into consumption patterns through logging and metrics for capacity planning +12. Rate limiting configuration MUST be externalized and configurable per API provider without code changes +13. Utility functions interacting with external APIs SHOULD encapsulate rate limiting and token tracking logic to ensure consistent application +14. Systems MAY implement circuit breakers in conjunction with rate limiters to fail fast when external APIs are consistently unavailable + +## Public API Endpoint Development + +1. All public-facing API endpoints MUST implement rate limiting to prevent resource exhaustion and abuse +2. API rate limiters MUST track consumption on a per-client or per-token basis to enforce individual quotas +3. Token tracking mechanisms MUST be implemented to monitor API usage patterns and enforce quota limits +4. Rate limiting logic SHOULD be centralized in dedicated utility modules (e.g., rate_limiter.py, token_tracker.py) to ensure consistency +5. Rate limit violations SHOULD return HTTP 429 (Too Many Requests) with appropriate retry-after headers +6. API responses SHOULD include rate limit status headers (e.g., X-RateLimit-Remaining, X-RateLimit-Reset) to inform clients +7. Different API endpoints MAY have different rate limit tiers based on resource intensity and business requirements \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..057cd16 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,115 @@ +# Architecture Decision Records + +This document contains architectural decisions and policies for the rulectl repository. + +--- + +## ADR: Use Jotai For Global State Management + +Policies: +1. Use Jotai for global state management + +--- + +## ADR: 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 +2. Libraries MAY include utility modules for cross-cutting concerns such as warning suppression, logging configuration, or environment setup +3. Library __init__.py files SHOULD NOT contain complex business logic or perform expensive operations at import time +4. Package structure MUST follow Python namespace conventions with clear separation between public API and internal implementation +5. Library initialization code SHOULD handle runtime warnings and error conditions gracefully through dedicated utility modules +6. Distributable libraries MUST include a setup.py or pyproject.toml file with complete package metadata including name, version, dependencies, and entry points +7. All Python library packages MUST include an __init__.py file to define the package namespace and public API surface + +--- + +## ADR: 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 +2. Components SHOULD use naming conventions (e.g., underscore prefix) or visibility modifiers to distinguish private implementation from public API +3. Public API contracts SHOULD be validated through automated tooling in the build pipeline to detect unintended exposure +4. Breaking changes to public API contracts MUST follow semantic versioning with major version increments +5. Internal implementation details, private methods, and undocumented properties MUST NOT be considered part of the public API contract +6. Public API contracts MUST include component props, events, slots, methods, and CSS custom properties exposed for external use +7. All design system components MUST explicitly declare their public API surface through documented interfaces, type definitions, or API contracts + +--- + +## ADR: 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 +2. Dependency resolution and fixing utilities MUST NOT introduce alternative patterns that conflict with the established fix_dependencies.py approach +3. Build automation scripts SHOULD separate configuration, execution, and error handling concerns following the pattern established in build.py +4. New CLI commands SHOULD be structured using the same command registration and argument parsing patterns as existing tools in rulectl/cli.py +5. Dependency management and initialization logic MUST be centralized and follow consistent import and setup patterns across all tooling modules +6. 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 + +--- + +## ADR: Standardize Python Script Structure with Argparse CLI and Modular Architecture + +Policies: +1. Scripts MAY use subparsers for complex multi-command CLI tools +2. Error handling SHOULD be implemented with clear error messages and appropriate exit codes +3. Scripts SHOULD organize related functionality into separate functions that can be tested independently +4. CLI tools SHOULD provide help text and descriptions for all arguments using argparse help parameter +5. Scripts MUST implement a main() function that serves as the primary entry point +6. CLI scripts MUST separate argument parsing logic from business logic through modular function design +7. All Python CLI scripts MUST use argparse for command-line argument parsing + +--- + +## ADR: 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 +2. Configuration sources MAY include remote configuration services for enterprise deployments requiring centralized theme management +3. Configuration changes SHOULD be reactive, allowing theme updates without full application reload where technically feasible +4. Theme configuration SHOULD be validated at runtime to ensure type safety and prevent invalid values from propagating +5. Configuration sources MUST be accessible through a consistent API or interface across all modules that require theming +6. Runtime configuration sources MUST support hierarchical precedence (e.g., environment variables > user preferences > defaults) +7. All design system theme configuration MUST be sourced from centralized runtime configuration sources rather than hardcoded values + +--- + +## ADR: Implement Rate Limiting and Token Tracking for Public API Endpoints + +Policies: +1. Different API endpoints MAY have different rate limit tiers based on resource intensity and business requirements +2. API responses SHOULD include rate limit status headers (e.g., X-RateLimit-Remaining, X-RateLimit-Reset) to inform clients +3. Rate limit violations SHOULD return HTTP 429 (Too Many Requests) with appropriate retry-after headers +4. Rate limiting logic SHOULD be centralized in dedicated utility modules (e.g., rate_limiter.py, token_tracker.py) to ensure consistency +5. Token tracking mechanisms MUST be implemented to monitor API usage patterns and enforce quota limits +6. API rate limiters MUST track consumption on a per-client or per-token basis to enforce individual quotas +7. All public-facing API endpoints MUST implement rate limiting to prevent resource exhaustion and abuse + +--- + +## ADR: Implement Rate Limiting and Token Tracking for External API Interactions + +Policies: +1. Systems MAY implement circuit breakers in conjunction with rate limiters to fail fast when external APIs are consistently unavailable +2. Utility functions interacting with external APIs SHOULD encapsulate rate limiting and token tracking logic to ensure consistent application +3. Rate limiting configuration MUST be externalized and configurable per API provider without code changes +4. Token tracking SHOULD provide visibility into consumption patterns through logging and metrics for capacity planning +5. API clients SHOULD pre-emptively throttle requests when approaching known rate limits rather than waiting for 429 responses +6. Rate limiters MUST implement exponential backoff with jitter when rate limits are exceeded to prevent thundering herd problems +7. Token consumption MUST be tracked and monitored using a dedicated token tracker for APIs with token-based billing or quota systems +8. All external API clients MUST implement rate limiting using a centralized rate limiter component to enforce provider-specific rate limits + +--- + +## ADR: Standardize External API Client Integration Patterns + +Policies: +1. External API clients MAY implement caching strategies to reduce API calls and improve performance where appropriate +2. External API client modules SHOULD expose consistent interfaces (e.g., common base classes or protocols) to enable polymorphic usage and dependency injection +3. API credentials and tokens MUST be stored in environment variables or secure credential stores, never hardcoded in source files +4. External API integrations SHOULD provide mock implementations or test doubles to enable offline development and testing +5. External API clients SHOULD implement usage tracking and logging to monitor API consumption, costs, and performance metrics +6. All external API calls MUST be wrapped in try-except blocks with specific exception handling for network, authentication, and API-specific errors +7. External API client modules MUST handle rate limiting, timeouts, and transient failures with exponential backoff retry logic +8. All external API clients MUST implement explicit authentication token management with tracking and refresh capabilities \ No newline at end of file