test

Author: Dan Clayton

.cursor/rules/build-and-deployment.mdc

@@ -0,0 +1,60 @@
+---
+globs: package.json,tsconfig.json,vitest.config.ts,packages/*/package.json
+---
+
+# Build and Deployment Patterns
+
+## Build System
+
+- Use Bun as the primary runtime and package manager
+- TypeScript compilation with strict settings
+- Monorepo workspace management
+- Changesets for version management
+
+## Package Configuration
+
+Each package should have:
+- Proper `main` and `types` fields pointing to `dist/` directory
+- Correct `engines` field for Bun version requirements
+- Proper `publishConfig` for GitHub Packages registry
+- Workspace dependencies using `workspace:*`
+
+## Development Workflow
+
+- Use `bun run build` to build all packages
+- Use `bun run test` for running tests
+- Use `bun run test:watch` for development
+- Use `bun run test:coverage` for coverage reports
+
+## Publishing
+
+- Use Changesets for version management
+- Publish to GitHub Packages registry
+- Follow semantic versioning
+- Update CHANGELOG.md files automatically
+
+## TypeScript Configuration
+
+- Use strict TypeScript settings
+- Enable all recommended compiler options
+- Use path mapping for monorepo imports
+- Configure proper module resolution
+
+## Example Package.json Structure
+
+```json
+{
+  "name": "@dotgithub/package-name",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "bun": ">=1.2.19"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "public"
+  }
+}
+```

.cursor/rules/cli-commands.mdc

@@ -0,0 +1,56 @@
+---
+globs: packages/cli/src/commands/*.ts
+---
+
+# CLI Command Patterns
+
+## Command Structure
+
+All CLI commands should follow the pattern established in [packages/cli/src/index.ts](mdc:packages/cli/src/index.ts):
+
+- Export a `create*Command` function that takes a context factory
+- Use Commander.js for argument parsing
+- Implement proper error handling and logging
+- Use the global options pattern
+
+## Context Usage
+
+Commands receive a `DotGithubContext` factory function:
+
+```typescript
+export function createMyCommand(
+  createContext: () => DotGithubContext
+): Command {
+  const command = new Command('my-command');
+  
+  command.action(async (options) => {
+    const context = createContext();
+    // Use context for operations
+  });
+  
+  return command;
+}
+```
+
+## Error Handling
+
+- Use the logger from `@dotgithub/core` for consistent output
+- Handle configuration errors gracefully
+- Provide helpful error messages with suggestions
+- Use appropriate exit codes
+
+## Global Options
+
+Commands inherit these global options:
+- `--config, -c` - Path to config file
+- `--verbose, -v` - Verbose logging
+- `--debug` - Debug logging  
+- `--quiet` - Suppress output except errors
+- `--token, -t` - GitHub token override
+
+## Testing Commands
+
+- Use Vitest for command testing
+- Mock external dependencies (GitHub API, file system)
+- Test both success and error cases
+- Verify proper logging output

.cursor/rules/configuration-management.mdc

@@ -0,0 +1,49 @@
+---
+globs: packages/core/src/config.ts,*.json
+---
+
+# Configuration Management Patterns
+
+## Configuration Structure
+
+The main configuration is managed through [packages/core/src/config.ts](mdc:packages/core/src/config.ts):
+
+- Use `DotGithubConfig` interface for type safety
+- Support both JSON and programmatic configuration
+- Validate configuration on load
+- Provide helpful error messages for invalid config
+
+## Configuration Loading
+
+- Use `readConfig()` to load configuration from file
+- Support multiple configuration file formats
+- Handle missing configuration gracefully
+- Provide configuration validation and fixing
+
+## Action Management
+
+- Use `addActionToConfig()` for adding actions
+- Use `removeActionFromConfig()` for removing actions
+- Use `getActionsFromConfig()` for retrieving actions
+- Support action pinning and version management
+
+## Construct Configuration
+
+- Use `getConstructsFromConfig()` for construct configuration
+- Support construct-specific configuration sections
+- Validate construct configuration schemas
+- Handle construct loading errors
+
+## Stack Configuration
+
+- Use `getStacksFromConfig()` for stack definitions
+- Support multiple stacks per configuration
+- Validate stack configuration
+- Handle stack synthesis errors
+
+## Configuration Validation
+
+- Use Zod schemas for runtime validation
+- Provide detailed error messages
+- Support configuration migration
+- Handle backward compatibility

.cursor/rules/construct-development.mdc

@@ -0,0 +1,58 @@
+---
+description: Guidelines for developing GitHub constructs and extending DotGitHub functionality
+---
+
+# Construct Development Guidelines
+
+## Construct Architecture
+
+Constructs in DotGitHub follow a specific pattern for extending functionality:
+
+- Constructs (loadable modules) are located in `packages/core/src/plugins/`
+- Each construct should export a main class and any helper classes
+- Constructs receive configuration through the stack context
+- Use dependency injection for better testability
+
+## Construct Interface
+
+```typescript
+export abstract class GitHubConstruct {
+  readonly name: string;
+  readonly version?: string;
+
+  validate?(stack: GitHubStack): void;
+  synthesize(stack: GitHubStack): Promise<void> | void;
+  describe?(): ConstructDescription | Promise<ConstructDescription>;
+}
+```
+
+## Action Collection Constructs
+
+For constructs that provide actions, extend [ActionCollection](mdc:packages/core/src/plugins/action-collection.ts):
+
+- Use `invokeAction()` for type-safe action invocation
+- Use `createOutputs()` for output management
+- Access the stack via `this.stack`
+- Implement proper error handling
+
+## Construct Configuration
+
+- Constructs receive configuration through `stack.config`
+- Use Zod schemas for configuration validation
+- Provide sensible defaults for optional configuration
+- Document all configuration options
+
+## Construct Registration
+
+- Constructs are registered in the configuration file under `constructs`
+- Use the construct manager for loading and initialization
+- Support construct dependencies and ordering
+- Handle construct loading errors gracefully
+
+## Testing Constructs
+
+- Create comprehensive unit tests for construct logic
+- Test configuration validation
+- Test construct integration with the stack
+- Use mocks for external dependencies
+- Test error conditions and edge cases

.cursor/rules/constructs-patterns.mdc

@@ -0,0 +1,46 @@
+---
+globs: packages/core/src/constructs/*.ts,packages/core/src/plugins/*.ts
+---
+
+# Constructs and GitHub Construct Patterns
+
+## Construct Base Classes
+
+All constructs should extend from [Construct](mdc:packages/core/src/constructs/base.ts) and follow CDK patterns:
+
+- Use `super(scope, id)` in constructor
+- Implement proper resource management
+- Use `this.node` for construct tree operations
+- Follow naming conventions: `GitHub*` for GitHub-specific constructs
+
+## Action Collection Pattern
+
+Action collections should extend [ActionCollection](mdc:packages/core/src/plugins/action-collection.ts):
+
+```typescript
+export class MyActionCollection extends ActionCollection {
+  // Use invokeAction() for type-safe action invocation
+  // Use createOutputs() for output management
+  // Access stack via this.stack
+}
+```
+
+## GitHub Construct Development
+
+- Constructs (loadable modules) live in `packages/core/src/plugins/`
+- Export main construct class and any helper classes
+- Use dependency injection for configuration
+- Follow the GitHubConstruct interface patterns
+
+## Resource Management
+
+- Use `addWorkflow()` for GitHub workflows
+- Use `addResource()` for file resources
+- Use `addFileResource()` for simple file content
+- Use `addDirectoryResource()` for directory structures
+
+## Stack Synthesis
+
+- Implement `synth()` method for file generation
+- Use YAML formatting for workflow files
+- Maintain proper file structure in output

.cursor/rules/documentation-standards.mdc

@@ -0,0 +1,59 @@
+---
+globs: docs/*.md,*.md
+---
+
+# Documentation Standards
+
+## Documentation Structure
+
+The project uses comprehensive documentation in the `docs/` directory:
+
+- [README.md](mdc:README.md) - Main project overview and quick start
+- [docs/getting-started.md](mdc:docs/getting-started.md) - Detailed getting started guide
+- [docs/user-guide.md](mdc:docs/user-guide.md) - Comprehensive user guide
+- [docs/api-reference.md](mdc:docs/api-reference.md) - API documentation
+- [docs/construct-development.md](mdc:docs/construct-development.md) - Construct development guide
+
+## Code Documentation
+
+- Use JSDoc comments for all public APIs
+- Include parameter descriptions and return types
+- Document complex algorithms and business logic
+- Provide usage examples in comments
+
+## Markdown Standards
+
+- Use proper heading hierarchy
+- Include table of contents for long documents
+- Use code blocks with language specification
+- Include links to related documentation
+
+## API Documentation
+
+- Document all public methods and properties
+- Include parameter types and descriptions
+- Provide usage examples
+- Document error conditions and exceptions
+
+## Example Documentation
+
+```typescript
+/**
+ * Creates a new GitHub workflow with the specified configuration.
+ * 
+ * @param config - The workflow configuration
+ * @returns A new GitHubWorkflow instance
+ * @throws {ValidationError} When the configuration is invalid
+ * 
+ * @example
+ * ```typescript
+ * const workflow = createWorkflow({
+ *   name: 'CI',
+ *   on: { push: { branches: ['main'] } }
+ * });
+ * ```
+ */
+export function createWorkflow(config: WorkflowConfig): GitHubWorkflow {
+  // Implementation
+}
+```

.cursor/rules/example-development.mdc

@@ -0,0 +1,53 @@
+---
+globs: examples/**/*.ts,examples/**/*.json
+---
+
+# Example Development Guidelines
+
+## Example Structure
+
+Examples should be located in the `examples/` directory and demonstrate real-world usage patterns:
+
+- Each example should be a complete, runnable project
+- Include a `dotgithub.json` configuration file
+- Provide TypeScript source code in `src/` directory
+- Include generated workflows in `workflows/` directory
+
+## Example Configuration
+
+Use the example in [examples/example/](mdc:examples/example/) as a template:
+
+- [examples/example/dotgithub.json](mdc:examples/example/dotgithub.json) - Main configuration
+- [examples/example/src/index.ts](mdc:examples/example/src/index.ts) - Main entry point
+- [examples/example/src/actions/](mdc:examples/example/src/actions/) - Generated action wrappers
+- [examples/example/workflows/](mdc:examples/example/workflows/) - Generated workflow files
+
+## Example Development
+
+- Start with a simple configuration
+- Build up complexity gradually
+- Show different patterns and use cases
+- Include comments explaining the approach
+- Test that examples can be synthesized successfully
+
+## Example Documentation
+
+- Include a README.md explaining the example
+- Document the configuration options used
+- Show the expected output
+- Provide step-by-step instructions
+
+## Example Testing
+
+- Ensure examples can be built and run
+- Test synthesis produces valid workflows
+- Verify examples work with the CLI
+- Update examples when APIs change
+
+## Best Practices
+
+- Use realistic but simple scenarios
+- Show both basic and advanced features
+- Include error handling examples
+- Demonstrate construct usage
+- Show integration with external services