diff --git a/.circleci/config.yml b/.circleci/config.yml index f1bd355..8dc3c23 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,85 +1,76 @@ -version: 2 +version: 2.1 + +orbs: + node: circleci/node@7.2.1 -references: - js_deps_cache_key: &js_deps_cache_key v1-dependencies-{{ checksum "yarn.lock" }} - workspace_root: &workspace_root . - attach_workspace: &attach_workspace - attach_workspace: - at: *workspace_root jobs: build: - docker: - - image: circleci/node:gallium - working_directory: ~/react-mosaic + executor: + name: node/default + tag: '22.22.1' + resource_class: large steps: - checkout + - node/install-packages: + pkg-manager: npm + with-cache: true - run: - name: Install Yarn - command: | - curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.22.18 - export PATH="$HOME/.yarn/bin:$PATH" - - restore_cache: - keys: - - *js_deps_cache_key - - run: yarn install --frozen-lockfile - - save_cache: - paths: - - node_modules - - ~/.cache/yarn - key: *js_deps_cache_key - - run: - name: Build - command: yarn build + name: Build library and demo app + command: npm run build:lib && npm run build:app - persist_to_workspace: - root: *workspace_root + root: . paths: - - . + - dist + - node_modules + test: - docker: - - image: circleci/node:dubnium - working_directory: ~/react-mosaic + executor: + name: node/default + tag: '22.22.1' + resource_class: large steps: - - *attach_workspace - - run: mkdir reports + - checkout + - node/install-packages: + pkg-manager: npm + with-cache: true - run: - name: Run unit tests - command: yarn test:unit --reporter mocha-junit-reporter --reporter-options mochaFile=reports/mocha/test-results.xml + name: Run linting + command: npm run lint - run: - name: Lint - command: yarn test:lint --format junit -o ./reports/tslint/tslint.xml - - store_test_results: - path: reports - - store_artifacts: - path: ./reports/mocha/test-results.xml - - store_artifacts: - path: ./reports/tslint/tslint.xml - deploy: - docker: - - image: circleci/node:dubnium - working_directory: ~/react-mosaic + name: Run tests + command: npm test + + publish: + executor: + name: node/default + tag: '22.22.1' + resource_class: medium steps: - - *attach_workspace + - checkout + - attach_workspace: + at: . - run: - name: Publish - command: | - npm set //registry.npmjs.org/:_authToken=$NPM_TOKEN - npm publish + name: Authenticate with NPM registry + command: npm set //registry.npmjs.org/:_authToken=$NPM_TOKEN + - run: + name: Publish to NPM + command: npm publish dist/libs/react-mosaic-component/ + workflows: - version: 2 - build-test-deploy: + version: 2.1 + build-test-publish: jobs: - build: filters: tags: only: /^v.*/ - test: - requires: - - build filters: tags: only: /^v.*/ - - deploy: + - publish: requires: + - build - test filters: tags: diff --git a/.claude/README.md b/.claude/README.md new file mode 100644 index 0000000..a885cfe --- /dev/null +++ b/.claude/README.md @@ -0,0 +1,194 @@ +# Claude Code Integration for React Mosaic + +This directory contains all the files for optimal Claude Code and LLM integration with the React Mosaic project. + +## Directory Contents + +### Configuration Files +- **`settings.json`**: Claude Code project settings and preferences +- **`.claudeignore`** (in root): Files/directories to exclude from LLM context + +### Documentation +- **`../claude.md`**: Comprehensive project documentation for LLMs (in root) +- **`../CONTRIBUTING_AI.md`**: AI/LLM-specific contribution guidelines (in root) +- **`../QUICKREF.md`**: Quick reference guide for common operations (in root) + +### Slash Commands (`commands/`) +Quick commands for common development tasks: + +- `/test` - Run tests and report failures +- `/build` - Build the library +- `/lint` - Run linting checks +- `/type-check` - Run TypeScript type checking +- `/analyze-tree` - Analyze tree manipulation utilities +- `/review-component` - Review a specific component +- `/explain-concept` - Explain core React Mosaic concepts +- `/add-feature` - Plan and implement a new feature +- `/fix-issue` - Debug and fix an issue +- `/refactor` - Refactor code for better quality +- `/update-deps` - Check for outdated dependencies + +### Prompt Templates (`prompts/`) +Reusable templates for common scenarios: + +- **`tree-analysis.md`**: Template for analyzing tree structures +- **`code-review.md`**: Template for reviewing code +- **`feature-planning.md`**: Template for planning new features +- **`debugging.md`**: Template for debugging issues + +## Quick Start for AI Assistants + +1. **Read `claude.md` first** - This provides comprehensive context about the project +2. **Check `QUICKREF.md`** - Quick reference for common operations +3. **Review `.claudeignore`** - Know what files to skip +4. **Use slash commands** - Quick access to common tasks +5. **Follow patterns in `CONTRIBUTING_AI.md`** - Guidelines for code contributions + +## Project Structure Overview + +``` +react-mosaic/ +├── .claude/ # Claude Code integration files +│ ├── commands/ # Slash commands +│ ├── prompts/ # Prompt templates +│ ├── settings.json # Project settings +│ └── README.md # This file +├── libs/react-mosaic-component/ # Main library [PRIMARY FOCUS] +│ └── src/lib/ # Source code +│ ├── types.ts # Type definitions +│ ├── contextTypes.ts # Context types +│ └── util/ # Utility functions +├── apps/demo-app/ # Demo application +├── claude.md # LLM integration guide +├── CONTRIBUTING_AI.md # AI contribution guidelines +├── QUICKREF.md # Quick reference +├── .claudeignore # Files to ignore +└── README.md # User documentation +``` + +## Key Concepts + +React Mosaic is a tiling window manager built on: + +1. **N-ary Tree Structure**: Layout represented as a tree with split nodes, tab nodes, and leaf nodes +2. **Numeric Paths**: Nodes identified by array of indices (e.g., `[0, 1, 2]`) +3. **Immutable Updates**: Tree modifications always create new instances +4. **React Context**: Components communicate via context API +5. **Drag & Drop**: Built on react-dnd with multi-backend support + +## Development Workflow + +```bash +# Setup +npm install + +# Development +npm start # Start dev server +npm test # Run tests +npm run build:lib # Build library + +# Code Quality +npm run lint # Lint code +npm run format # Format code +``` + +## Important Files + +| File | Description | +|------|-------------| +| `libs/react-mosaic-component/src/index.ts` | Public API exports | +| `libs/react-mosaic-component/src/lib/types.ts` | Type definitions | +| `libs/react-mosaic-component/src/lib/util/mosaicUtilities.ts` | Tree operations | +| `libs/react-mosaic-component/src/lib/util/mosaicUpdates.ts` | Tree mutations | + +## Using Slash Commands + +Slash commands provide quick access to common tasks: + +``` +/test # Run the test suite +/build # Build the library +/explain-concept # Learn about a core concept +/add-feature # Plan and add a new feature +``` + +## Using Prompt Templates + +Prompt templates help maintain consistency: + +1. Navigate to `.claude/prompts/` +2. Choose appropriate template +3. Follow the structure provided +4. Adapt to your specific need + +## Best Practices for AI + +1. **Always read files before modifying** - Use Read tool first +2. **Use utility functions** - Don't manually manipulate trees +3. **Follow existing patterns** - Match code style and conventions +4. **Write tests** - Add tests for new functionality +5. **Check types** - Ensure TypeScript compilation passes +6. **Use type guards** - Use `isSplitNode()` and `isTabsNode()` +7. **Validate paths** - Check paths before tree operations +8. **Handle edge cases** - Test with empty, single, and nested trees + +## Common Patterns + +### Tree Manipulation +```typescript +import { updateTree, createRemoveUpdate } from 'react-mosaic-component'; + +const newTree = updateTree(currentTree, [ + createRemoveUpdate(path) +]); +``` + +### Type Checking +```typescript +import { isSplitNode, isTabsNode } from 'react-mosaic-component'; + +if (isSplitNode(node)) { + // node is MosaicSplitNode +} +``` + +### Context Access +```typescript +import { useContext } from 'react'; +import { MosaicContext } from 'react-mosaic-component'; + +const { mosaicActions } = useContext(MosaicContext); +mosaicActions.remove(path); +``` + +## Resources + +- **Project Documentation**: `../claude.md` +- **Quick Reference**: `../QUICKREF.md` +- **AI Guidelines**: `../CONTRIBUTING_AI.md` +- **User Documentation**: `../README.md` +- **Live Demo**: https://nomcopter.github.io/react-mosaic/ +- **GitHub**: https://github.com/nomcopter/react-mosaic + +## Contributing + +See `CONTRIBUTING_AI.md` for detailed guidelines on: +- Code style and conventions +- Testing requirements +- Common patterns +- Debugging strategies +- Performance considerations + +## Support + +For issues or questions: +- Check `claude.md` for comprehensive information +- Use `/explain-concept` to understand core concepts +- Review existing code for patterns +- Ask specific questions about the codebase + +## Version + +This integration is designed for React Mosaic v0.20.0. + +Last updated: 2025-12-04 diff --git a/.claude/commands/add-feature.md b/.claude/commands/add-feature.md new file mode 100644 index 0000000..cc03866 --- /dev/null +++ b/.claude/commands/add-feature.md @@ -0,0 +1,16 @@ +--- +description: Plan and implement a new feature +--- + +I'll help you plan and implement a new feature for react-mosaic. + +First, describe the feature you want to add. I will then: + +1. Analyze the existing codebase to understand relevant patterns +2. Create a detailed implementation plan +3. Identify files that need to be modified or created +4. Implement the feature following existing code conventions +5. Add appropriate tests +6. Update documentation if needed + +What feature would you like to add? diff --git a/.claude/commands/analyze-tree.md b/.claude/commands/analyze-tree.md new file mode 100644 index 0000000..de28766 --- /dev/null +++ b/.claude/commands/analyze-tree.md @@ -0,0 +1,10 @@ +--- +description: Analyze the MosaicNode tree structure utilities +--- + +Analyze the tree manipulation utilities in the codebase, specifically: + +1. Read and explain the tree utilities in `libs/react-mosaic-component/src/lib/util/mosaicUtilities.ts` +2. Read and explain the tree update functions in `libs/react-mosaic-component/src/lib/util/mosaicUpdates.ts` +3. Provide examples of how to use these utilities for common operations +4. Identify any potential improvements or edge cases to handle diff --git a/.claude/commands/build.md b/.claude/commands/build.md new file mode 100644 index 0000000..821b774 --- /dev/null +++ b/.claude/commands/build.md @@ -0,0 +1,5 @@ +--- +description: Build the react-mosaic library +--- + +Build the react-mosaic library using `npm run build:lib`. Report any build errors or warnings and suggest fixes if needed. diff --git a/.claude/commands/explain-concept.md b/.claude/commands/explain-concept.md new file mode 100644 index 0000000..2b54dbc --- /dev/null +++ b/.claude/commands/explain-concept.md @@ -0,0 +1,16 @@ +--- +description: Explain a core concept of react-mosaic +--- + +Explain a core concept of the react-mosaic library. I can explain: + +1. **Tree Structure**: How the n-ary tree layout works +2. **Path System**: How paths identify nodes in the tree +3. **Drag & Drop**: How the drag-and-drop system is implemented +4. **Split Nodes**: How split containers divide space +5. **Tab Nodes**: How tabbed interfaces work +6. **Context API**: How components communicate via React context +7. **Tree Updates**: How immutable tree updates work +8. **Migration**: How legacy binary trees are converted to n-ary + +Which concept would you like me to explain? diff --git a/.claude/commands/fix-issue.md b/.claude/commands/fix-issue.md new file mode 100644 index 0000000..a15d526 --- /dev/null +++ b/.claude/commands/fix-issue.md @@ -0,0 +1,19 @@ +--- +description: Debug and fix an issue in the codebase +--- + +I'll help you debug and fix an issue in the react-mosaic codebase. + +Describe the issue you're experiencing, including: +- What behavior you're seeing +- What behavior you expected +- Steps to reproduce (if applicable) +- Error messages (if any) + +I will then: + +1. Investigate the relevant code +2. Identify the root cause +3. Propose a solution +4. Implement the fix +5. Add tests to prevent regression diff --git a/.claude/commands/lint.md b/.claude/commands/lint.md new file mode 100644 index 0000000..ee7eac0 --- /dev/null +++ b/.claude/commands/lint.md @@ -0,0 +1,5 @@ +--- +description: Run linting checks on the codebase +--- + +Run ESLint on the codebase using `npm run lint`. Report any linting errors or warnings and offer to fix them automatically. diff --git a/.claude/commands/refactor.md b/.claude/commands/refactor.md new file mode 100644 index 0000000..3496d1a --- /dev/null +++ b/.claude/commands/refactor.md @@ -0,0 +1,21 @@ +--- +description: Refactor code for better quality or maintainability +--- + +I'll help you refactor code in the react-mosaic project. + +Tell me what you want to refactor: +- A specific file or component +- A particular pattern or approach +- Code duplication +- Performance optimization +- Type safety improvements + +I will: + +1. Analyze the current implementation +2. Identify improvement opportunities +3. Propose a refactoring plan +4. Implement the changes while maintaining functionality +5. Ensure all tests still pass +6. Update related documentation diff --git a/.claude/commands/review-component.md b/.claude/commands/review-component.md new file mode 100644 index 0000000..b018188 --- /dev/null +++ b/.claude/commands/review-component.md @@ -0,0 +1,16 @@ +--- +description: Review a specific component in the library +--- + +Review the React component file you specify. The review should cover: + +1. Code quality and best practices +2. TypeScript type safety +3. React patterns and hooks usage +4. Performance considerations +5. Accessibility concerns +6. Potential bugs or edge cases +7. Documentation and comments +8. Suggested improvements + +Ask me which component file to review (e.g., Mosaic.tsx, MosaicWindow.tsx, etc.). diff --git a/.claude/commands/test.md b/.claude/commands/test.md new file mode 100644 index 0000000..891c590 --- /dev/null +++ b/.claude/commands/test.md @@ -0,0 +1,5 @@ +--- +description: Run tests for the react-mosaic library +--- + +Run the test suite for the react-mosaic library and report any failures. If tests fail, analyze the failures and suggest fixes. diff --git a/.claude/commands/type-check.md b/.claude/commands/type-check.md new file mode 100644 index 0000000..a0a53d5 --- /dev/null +++ b/.claude/commands/type-check.md @@ -0,0 +1,7 @@ +--- +description: Run TypeScript type checking +--- + +Run TypeScript type checking on the library code using `npm run build-lib:check`. + +Report any type errors and offer to fix them. Ensure all code is properly typed and follows TypeScript best practices. diff --git a/.claude/commands/update-deps.md b/.claude/commands/update-deps.md new file mode 100644 index 0000000..ca4f062 --- /dev/null +++ b/.claude/commands/update-deps.md @@ -0,0 +1,11 @@ +--- +description: Check for outdated dependencies and suggest updates +--- + +Check for outdated dependencies in the project and suggest safe updates. + +1. Run `npm outdated` to check for updates +2. Review the current versions and available updates +3. Identify which updates are safe (patch/minor) vs risky (major) +4. Suggest a plan for updating dependencies +5. Warn about any breaking changes in major updates diff --git a/.claude/prompts/code-review.md b/.claude/prompts/code-review.md new file mode 100644 index 0000000..e5fab10 --- /dev/null +++ b/.claude/prompts/code-review.md @@ -0,0 +1,72 @@ +# Code Review Prompt Template + +Use this template when reviewing React Mosaic code. + +## Review Checklist + +### 1. Type Safety +- [ ] All function parameters have explicit types +- [ ] Return types are specified +- [ ] No usage of `any` (use `unknown` if needed) +- [ ] Proper use of generics with `` +- [ ] Type guards used for node type checking + +### 2. Tree Operations +- [ ] Uses utility functions (not manual manipulation) +- [ ] Handles all node types (split, tabs, leaf) +- [ ] Creates new tree instances (immutability) +- [ ] Validates paths before use +- [ ] Handles edge cases (empty, single node, deep nesting) + +### 3. React Patterns +- [ ] Functional components with hooks +- [ ] Proper dependency arrays in hooks +- [ ] Memoization where appropriate (`useMemo`, `useCallback`) +- [ ] Context used correctly +- [ ] No side effects in render + +### 4. Performance +- [ ] No expensive operations in render +- [ ] Tree traversals minimized +- [ ] Callbacks are stable +- [ ] Components memoized if needed + +### 5. Accessibility +- [ ] Semantic HTML used +- [ ] Keyboard navigation considered +- [ ] ARIA labels where needed +- [ ] Focus management appropriate + +### 6. Testing +- [ ] Unit tests present for utilities +- [ ] Edge cases tested +- [ ] Type safety verified +- [ ] Visual testing mentioned if UI change + +### 7. Documentation +- [ ] JSDoc comments for public APIs +- [ ] Complex logic explained +- [ ] Examples provided for new features + +### 8. Code Style +- [ ] Follows existing patterns +- [ ] Naming conventions matched +- [ ] File organization correct +- [ ] Imports organized + +## Review Format + +**Summary**: [One sentence overview] + +**Strengths**: +- [What's done well] + +**Issues**: +1. **[Severity]**: [Description] + - Location: [File:line] + - Fix: [Suggestion] + +**Suggestions**: +- [Optional improvements] + +**Verdict**: ✅ Approve / ⚠️ Needs Changes / ❌ Reject diff --git a/.claude/prompts/debugging.md b/.claude/prompts/debugging.md new file mode 100644 index 0000000..76940be --- /dev/null +++ b/.claude/prompts/debugging.md @@ -0,0 +1,214 @@ +# Debugging Prompt Template + +Use this template when debugging issues in React Mosaic. + +## Debugging Process + +### 1. Gather Information + +**Symptoms**: +- What is the unexpected behavior? +- What was the expected behavior? +- Is this reproducible? +- In what environment (browser, React version, etc.)? + +**Context**: +- What tree structure is involved? +- What operations were performed? +- What's the component hierarchy? +- Are there any error messages? + +### 2. Reproduce the Issue + +Create a minimal reproduction: +```typescript +// Minimal tree structure +const testTree = { ... }; + +// Steps to reproduce +1. ... +2. ... +3. ... + +// Expected result +// Actual result +``` + +### 3. Hypothesis Formation + +Possible causes: +1. [Hypothesis 1] +2. [Hypothesis 2] +3. [Hypothesis 3] + +### 4. Investigation Steps + +#### For Tree-Related Issues +```typescript +// Log the tree +console.log('Tree:', JSON.stringify(tree, null, 2)); + +// Log the path +console.log('Path:', path.join(' → ')); + +// Validate tree structure +function validateTree(node) { + if (isSplitNode(node)) { + // Check children exist + // Check split percentages + // Recurse + } else if (isTabsNode(node)) { + // Check tabs array + // Check activeTabIndex + } +} +``` + +#### For Component Issues +```typescript +// Add console logs +useEffect(() => { + console.log('Props changed:', props); +}, [props]); + +// Check context values +const context = useContext(MosaicContext); +console.log('Context:', context); + +// Track renders +console.log('Rendering:', componentName); +``` + +#### For Drag & Drop Issues +```typescript +// Log drag events +onDragStart={() => console.log('Drag start')} +onDragEnd={(type) => console.log('Drag end:', type)} + +// Check drop target registration +// Verify backend setup +// Log drop position calculations +``` + +### 5. Root Cause Analysis + +**Root Cause**: [Description] + +**Why it happens**: [Explanation] + +**Related code**: [File paths and line numbers] + +### 6. Solution Design + +**Approach**: [Description of fix] + +**Files to modify**: +- `file1.ts`: [What to change] +- `file2.tsx`: [What to change] + +**Trade-offs**: +- Pro: [Benefits] +- Con: [Drawbacks] + +### 7. Implementation + +```typescript +// Before +// [Old code] + +// After +// [New code] + +// Why this fixes it +// [Explanation] +``` + +### 8. Testing + +**Test the fix**: +1. [ ] Original issue resolved +2. [ ] No regressions introduced +3. [ ] Edge cases handled +4. [ ] Unit tests pass +5. [ ] Visual testing confirms + +**Add regression test**: +```typescript +it('should handle [specific case]', () => { + // Test that prevents this bug from returning +}); +``` + +## Common Issue Patterns + +### Pattern 1: Tree Mutation +**Symptom**: Tree changes not reflecting in UI +**Cause**: Mutating tree instead of creating new instance +**Fix**: Use `updateTree` or spread operator + +### Pattern 2: Invalid Path +**Symptom**: Node not found, errors accessing properties +**Cause**: Path doesn't match tree structure +**Fix**: Validate paths, log tree structure + +### Pattern 3: Type Errors +**Symptom**: TypeScript errors, runtime type issues +**Cause**: Missing type guards +**Fix**: Use `isSplitNode()`, `isTabsNode()` + +### Pattern 4: Render Loop +**Symptom**: Infinite re-renders, performance issues +**Cause**: Unstable callbacks, missing dependencies +**Fix**: Use `useCallback`, fix dependency arrays + +### Pattern 5: Drag & Drop Not Working +**Symptom**: Can't drag panels +**Cause**: DnD context not setup, backend issues +**Fix**: Check `Mosaic` setup, verify backend + +## Debugging Tools + +### Browser DevTools +- React DevTools: Component hierarchy, props, state +- Console: Logging, errors +- Performance: Profiling renders +- Network: Loading issues + +### Code Debugging +```typescript +// Add type checking +if (!isSplitNode(node) && !isTabsNode(node)) { + console.warn('Invalid node type:', node); +} + +// Validate tree +function isValidTree(node) { + // Check structure recursively +} + +// Log tree operations +const result = updateTree(tree, updates); +console.log('Before:', tree); +console.log('After:', result); +``` + +### Test Debugging +```bash +# Run single test +npm test -- --testNamePattern="specific test" + +# Add .only to focus +it.only('should do something', () => { ... }); + +# Increase timeout for debugging +it('should do something', () => { ... }, 10000); +``` + +## Prevention + +After fixing: +1. [ ] Add test to prevent regression +2. [ ] Document edge case if needed +3. [ ] Consider if this affects other areas +4. [ ] Update documentation if needed +5. [ ] Share learnings with team diff --git a/.claude/prompts/feature-planning.md b/.claude/prompts/feature-planning.md new file mode 100644 index 0000000..ac01f19 --- /dev/null +++ b/.claude/prompts/feature-planning.md @@ -0,0 +1,140 @@ +# Feature Planning Prompt Template + +Use this template when planning new features for React Mosaic. + +## Feature Planning Steps + +### 1. Requirements Analysis +- What is the feature? +- What problem does it solve? +- Who is the target user? +- What are the acceptance criteria? + +### 2. API Design +- What new types are needed? +- What new components are needed? +- What new utilities are needed? +- How will users consume this feature? +- Is it a breaking change? + +### 3. Implementation Plan + +#### Files to Create +- [ ] Component file(s) +- [ ] Type definitions +- [ ] Utility functions +- [ ] Test files +- [ ] Style files + +#### Files to Modify +- [ ] `index.ts` (exports) +- [ ] `types.ts` (if new types) +- [ ] Existing components (if integrating) +- [ ] Documentation + +#### Testing Strategy +- Unit tests for utilities +- Component tests for React components +- Integration tests if needed +- Visual testing in demo app + +### 4. Dependencies +- Any new npm packages needed? +- Any peer dependency changes? +- Build system changes? + +### 5. Documentation Plan +- README updates +- API documentation +- Code examples +- Migration guide (if breaking) + +### 6. Backwards Compatibility +- Is this a breaking change? +- Can we provide a migration path? +- Do we need deprecation warnings? + +### 7. Performance Considerations +- Will this impact render performance? +- Are there expensive operations? +- Should we add memoization? + +### 8. Accessibility Considerations +- Keyboard navigation support? +- Screen reader support? +- ARIA labels needed? +- Focus management? + +## Implementation Order + +1. **Phase 1: Types & Utilities** + - Define new types + - Implement utility functions + - Write unit tests + +2. **Phase 2: Components** + - Implement core component + - Add styles + - Write component tests + +3. **Phase 3: Integration** + - Export from index.ts + - Integrate with existing components + - Update context if needed + +4. **Phase 4: Documentation** + - Update README + - Add code examples + - Update QUICKREF + +5. **Phase 5: Testing** + - Visual testing in demo app + - Cross-browser testing + - Accessibility testing + +## Example Plan Template + +```markdown +## Feature: [Name] + +### Overview +[1-2 sentence description] + +### Requirements +1. [Requirement 1] +2. [Requirement 2] + +### API Design + +```typescript +// New types +interface NewFeatureProps { + // ... +} + +// New components + + prop1={...} + prop2={...} +/> +``` + +### Implementation Steps +1. [ ] Create types in `types.ts` +2. [ ] Create component in `NewFeature.tsx` +3. [ ] Add tests in `NewFeature.spec.tsx` +4. [ ] Add styles in `styles/new-feature.less` +5. [ ] Export from `index.ts` +6. [ ] Update README +7. [ ] Add demo example + +### Testing +- Unit tests: [Describe] +- Integration tests: [Describe] +- Manual testing: [Describe] + +### Timeline +- Phase 1: [Duration] +- Phase 2: [Duration] +- Total: [Duration] +``` diff --git a/.claude/prompts/tree-analysis.md b/.claude/prompts/tree-analysis.md new file mode 100644 index 0000000..bfa23e3 --- /dev/null +++ b/.claude/prompts/tree-analysis.md @@ -0,0 +1,55 @@ +# Tree Analysis Prompt Template + +Use this template when analyzing tree structures or tree operations. + +## Analyzing a Tree Structure + +When given a tree structure, analyze it by: + +1. **Structure Overview** + - Root node type (split, tabs, or leaf) + - Total depth of the tree + - Number of leaf nodes + - Number of split nodes + - Number of tab nodes + +2. **Visual Representation** + - Draw ASCII tree diagram + - Show split directions and percentages + - Show tab groups and active tabs + +3. **Validation** + - Check for invalid node types + - Verify split percentages (should sum to ~100) + - Check for orphaned nodes + - Validate path references + +4. **Optimization Suggestions** + - Identify redundant nesting + - Suggest balanced alternatives + - Point out deep nesting issues + +## Example Analysis + +```typescript +// Given tree +const tree = { + type: 'split', + direction: 'row', + children: ['left', { type: 'split', direction: 'column', children: ['top', 'bottom'] }] +}; + +// Analysis output: +Structure: +├── Split (row) +│ ├── Leaf: 'left' +│ └── Split (column) +│ ├── Leaf: 'top' +│ └── Leaf: 'bottom' + +Metrics: +- Depth: 2 +- Leaves: 3 +- Split nodes: 2 +- Layout: 2 columns, right column split into 2 rows +``` diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..709d721 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,41 @@ +{ + "description": "React Mosaic - A React Tiling Window Manager", + "projectContext": { + "type": "library", + "language": "TypeScript", + "framework": "React", + "buildSystem": "Nx + Vite + tsup", + "testFramework": "Vitest", + "packageManager": "npm" + }, + "preferences": { + "codeStyle": { + "quotes": "single", + "semi": true, + "trailingComma": "all", + "tabWidth": 2, + "printWidth": 100 + }, + "testing": { + "framework": "vitest", + "coverage": true, + "location": "co-located" + } + }, + "keyFiles": [ + "claude.md", + "README.md", + "libs/react-mosaic-component/src/index.ts", + "libs/react-mosaic-component/src/lib/types.ts", + "libs/react-mosaic-component/src/lib/contextTypes.ts", + "libs/react-mosaic-component/src/lib/util/mosaicUtilities.ts", + "libs/react-mosaic-component/src/lib/util/mosaicUpdates.ts" + ], + "commonTasks": { + "start": "npm start", + "test": "npm test", + "build": "npm run build:lib", + "lint": "npm run lint", + "format": "npm run format" + } +} diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..f50118a --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,11 @@ +{ + "enableAllProjectMcpServers": true, + "enabledMcpjsonServers": [ + "nx-mcp" + ], + "permissions": { + "allow": [ + "Bash(npm run build:lib:*)" + ] + } +} diff --git a/.claudeignore b/.claudeignore new file mode 100644 index 0000000..dc858d8 --- /dev/null +++ b/.claudeignore @@ -0,0 +1,88 @@ +# Build outputs +dist/ +build/ +out/ +*.tsbuildinfo + +# Dependencies +node_modules/ +.pnp.* +.yarn/ + +# Cache directories +.cache/ +.nx/ +.vite/ +.turbo/ + +# Test coverage +coverage/ +*.lcov +.nyc_output/ + +# Logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +.pnpm-debug.log* + +# OS files +.DS_Store +Thumbs.db +desktop.ini + +# IDE files +.vscode/ +.idea/ +*.swp +*.swo +*.sublime-* +*.code-workspace + +# Environment files +.env +.env.local +.env.*.local +.env.production + +# Temporary files +*.tmp +*.temp +.tmp/ +.temp/ + +# Lock files (can be regenerated) +package-lock.json +yarn.lock +pnpm-lock.yaml + +# Build artifacts +*.js.map +*.css.map + +# Demo app specific +apps/demo-app/dist/ +apps/demo-app/.vite/ + +# Git files +.git/ +.gitignore + +# Documentation (already have claude.md) +CHANGELOG.md +CONTRIBUTING.md + +# Media files (screenshots, gifs, etc.) +*.gif +*.png +*.jpg +*.jpeg +*.svg +*.ico +*.webp + +# Compiled CSS +*.css +!libs/react-mosaic-component/src/lib/styles/*.less diff --git a/.commitlintrc.json b/.commitlintrc.json new file mode 100644 index 0000000..9cd680a --- /dev/null +++ b/.commitlintrc.json @@ -0,0 +1,27 @@ +{ + "extends": ["@commitlint/config-conventional"], + "rules": { + "type-enum": [ + 2, + "always", + [ + "feat", + "fix", + "docs", + "style", + "refactor", + "perf", + "test", + "build", + "ci", + "chore", + "revert" + ] + ], + "subject-case": [0], + "subject-empty": [2, "never"], + "subject-full-stop": [2, "never", "."], + "type-case": [2, "always", "lower-case"], + "type-empty": [2, "never"] + } +} diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000..6a6aacd --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,7 @@ +{ + "mcpServers": { + "nx-mcp": { + "url": "http://localhost:9124/sse" + } + } +} \ No newline at end of file diff --git a/.cursor/setting.json b/.cursor/setting.json new file mode 100644 index 0000000..17ea7e9 --- /dev/null +++ b/.cursor/setting.json @@ -0,0 +1,26 @@ + { + "permissions": { + "allow": [ + "mcp__ide__getDiagnostics", + "Bash(npm run build:*)", + "Bash(npm install:*)", + "Bash(npm run:*)", + "Bash(npx eslint:*)", + "Bash(npx nx build:*)", + "Bash(npx nx test:*)", + "Bash(npx nx graph)", + "Bash(npx nx show project:*)" + ], + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Read(./apps/vinto/.env.*)", + "Bash(npx tsc:*)", + "Bash(npm run typecheck:*)" + ], + "ask": [] + }, + "env": { + "NODE_ENV": "development" + } + } diff --git a/.github/agents/ci-monitor-subagent.agent.md b/.github/agents/ci-monitor-subagent.agent.md new file mode 100644 index 0000000..ac25b5b --- /dev/null +++ b/.github/agents/ci-monitor-subagent.agent.md @@ -0,0 +1,616 @@ +--- +description: Polls Nx Cloud CI pipeline and self-healing status. Returns structured state when actionable. Spawned by /monitor-ci command to monitor CI Attempt status. +--- + +# CI Monitor Subagent + +You are a CI monitoring subagent responsible for polling Nx Cloud CI Attempt status and self-healing state. You report status back to the main agent - you do NOT make apply/reject decisions. + +## Your Responsibilities + +1. Poll CI status using the `ci_information` MCP tool +2. Implement exponential backoff between polls +3. Return structured state when an actionable condition is reached +4. Track iteration count and elapsed time +5. Output status updates based on verbosity level + +## Input Parameters (from Main Agent) + +The main agent may provide these optional parameters in the prompt: + +| Parameter | Description | +| ------------------- | --------------------------------------------------------------------------- | +| `branch` | Branch to monitor (auto-detected if not provided) | +| `expectedCommitSha` | Commit SHA that should trigger a new CI Attempt | +| `previousCipeUrl` | CI Attempt URL before the action (to detect change) | +| `subagentTimeout` | Polling timeout in minutes (default: 30) | +| `newCipeTimeout` | Minutes to wait for CI Attempt before returning `no_new_cipe` (default: 10) | +| `verbosity` | Output level: minimal, medium, verbose (default: medium) | + +When `expectedCommitSha` or `previousCipeUrl` is provided, you must detect whether a new CI Attempt has spawned. + +## MCP Tool Reference + +### `ci_information` + +**Input:** + +```json +{ + "branch": "string (optional, defaults to current git branch)", + "select": "string (optional, comma-separated field names)", + "pageToken": "number (optional, 0-based pagination for long strings)" +} +``` + +**Output:** + +```json +{ + "cipeStatus": "NOT_STARTED | IN_PROGRESS | SUCCEEDED | FAILED | CANCELED | TIMED_OUT", + "cipeUrl": "string", + "branch": "string", + "commitSha": "string | null", + "failedTaskIds": "string[]", + "verifiedTaskIds": "string[]", + "selfHealingEnabled": "boolean", + "selfHealingStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null", + "selfHealingSkippedReason": "string | null", + "selfHealingSkipMessage": "string | null", + "verificationStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null", + "userAction": "NONE | APPLIED | REJECTED | APPLIED_LOCALLY | APPLIED_AUTOMATICALLY | null", + "failureClassification": "string | null", + "taskOutputSummary": "string | null", + "suggestedFixReasoning": "string | null", + "suggestedFixDescription": "string | null", + "suggestedFix": "string | null", + "shortLink": "string | null", + "couldAutoApplyTasks": "boolean | null", + "confidence": "number | null", + "confidenceReasoning": "string | null", + "hints": "string[]" +} +``` + +**Select Parameter:** + +| Usage | Returns | +| --------------- | ----------------------------------------------------------- | +| No `select` | Formatted overview (truncated, not recommended for polling) | +| Single field | Raw value with pagination for long strings | +| Multiple fields | Object with requested field values | + +**Field Sets for Efficient Polling:** + +```yaml +WAIT_FIELDS: + 'cipeUrl,commitSha,cipeStatus' + # Minimal fields for detecting new CI Attempt + +LIGHT_FIELDS: + 'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning,hints,selfHealingSkippedReason,selfHealingSkipMessage' + # Status fields for determining actionable state (includes hints for contextual guidance) + +HEAVY_FIELDS: + 'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription' + # Large content fields - fetch only when returning to main agent +``` + +## Initial Poll + +Start polling immediately — no initial wait. The exponential backoff between polls +(60s → 90s → 120s cap) handles pacing naturally. The first poll provides immediate +feedback on CI state, even if it's NOT_STARTED. + +## Stale Detection (CRITICAL) + +**Before EVERY poll iteration**, check if this subagent instance is stale: + +### Stale Check Protocol + +1. **Immediately after waking from sleep**, before calling `ci_information`: + + ``` + IF main agent has moved on (CI already passed or new cycle started): + → Output: "[ci-monitor-subagent] Stale instance detected. Exiting." + → Return immediately with status: stale_exit + → Do NOT continue polling + ``` + +2. **After each `ci_information` call**, check for early exit: + + ``` + IF cipeStatus == 'SUCCEEDED': + → CI passed while we were sleeping + → Return immediately with status: ci_success + → Do NOT continue to next poll iteration + ``` + +### Why Stale Instances Happen + +When main agent spawns a new subagent cycle, previous subagent instances may still be in a `sleep` call. Upon waking: + +- They have outdated context (old `expectedCommitSha`, old `previousCipeUrl`) +- Main agent has already moved on +- Continuing to poll wastes resources and causes confusing output + +**The subagent MUST self-terminate when detecting staleness rather than continuing.** + +## Two-Phase Operation + +The subagent operates in one of two modes depending on input: + +### Mode 1: Fresh Start (no `expectedCommitSha` or `previousCipeUrl`) + +Normal polling - process whatever CI Attempt is returned by `ci_information`. If `ci_information` returns no CI Attempt for the branch after `newCipeTimeout` (default 10 min), return `no_new_cipe`. + +### Mode 2: Wait-for-New-CI-Attempt (when `expectedCommitSha` or `previousCipeUrl` provided) + +**CRITICAL**: When expecting a new CI Attempt, the subagent must **completely ignore** the old/stale CI Attempt. Do NOT process its status, do NOT return actionable states based on it. + +#### Phase A: Wait Mode + +1. Start a **new-CI-Attempt timeout** timer (default: 10 minutes, configurable via main agent) +2. On each poll of `ci_information`: + - Check if CI Attempt is NEW: + - `cipeUrl` differs from `previousCipeUrl` → **new CI Attempt detected** + - `commitSha` matches `expectedCommitSha` → **correct CI Attempt detected** + - If still OLD CI Attempt: **ignore all status fields**, just wait and poll again + - Do NOT return `fix_available`, `ci_success`, etc. based on old CI Attempt! +3. Output wait status (see below) +4. If `newCipeTimeout` reached → return `no_new_cipe` + +#### Phase B: Normal Polling (after new CI Attempt detected) + +Once new CI Attempt is detected: + +1. Clear the new-CI-Attempt timeout +2. Switch to normal polling mode +3. Process the NEW CI Attempt's status normally +4. Return when actionable state reached + +### Wait Mode Output + +While in wait mode, output clearly that you're waiting (not processing): + +``` +[ci-monitor-subagent] ═══════════════════════════════════════════════════════ +[ci-monitor-subagent] WAIT MODE - Expecting new CI Attempt +[ci-monitor-subagent] Expected SHA: +[ci-monitor-subagent] Previous CI Attempt: +[ci-monitor-subagent] ═══════════════════════════════════════════════════════ + +[ci-monitor-subagent] Polling... (elapsed: 0m 30s) +[ci-monitor-subagent] Still seeing previous CI Attempt (ignoring): + +[ci-monitor-subagent] Polling... (elapsed: 1m 30s) +[ci-monitor-subagent] Still seeing previous CI Attempt (ignoring): + +[ci-monitor-subagent] Polling... (elapsed: 2m 30s) +[ci-monitor-subagent] ✓ New CI Attempt detected! URL: , SHA: +[ci-monitor-subagent] Switching to normal polling mode... +``` + +### Why This Matters (Context Preservation) + +**The problem**: Stale CI Attempt data can be very large: + +- `taskOutputSummary`: potentially thousands of characters of build/test output +- `suggestedFix`: entire patch files +- `suggestedFixReasoning`: detailed explanation + +If subagent returns stale CI Attempt data to main agent, it **pollutes main agent's context** with useless information (we already processed that CI Attempt). This wastes valuable context window. + +**Without wait mode:** + +1. Poll `ci_information` → get old CI Attempt with huge data +2. Return to main agent with all that stale data +3. Main agent's context gets polluted with useless info +4. Main agent has to process/ignore it anyway + +**With wait mode:** + +1. Poll `ci_information` → get old CI Attempt → **ignore it, don't return** +2. Keep waiting internally (stale data stays in subagent) +3. New CI Attempt appears → switch to normal mode +4. Return to main agent with only the NEW, relevant CI Attempt data + +## Polling Loop + +### Subagent State Management + +Maintain internal accumulated state across polls: + +``` +accumulated_state = {} +``` + +### Call `ci_information` MCP Tool + +**Wait Mode (expecting new CI Attempt):** + +``` +ci_information({ + branch: "", + select: "cipeUrl,commitSha,cipeStatus" +}) +``` + +Only fetch minimal fields needed to detect CI Attempt change. Do NOT fetch heavy fields - stale data wastes context. + +**Normal Mode (processing CI Attempt):** + +``` +ci_information({ + branch: "", + select: "cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning,hints,selfHealingSkippedReason,selfHealingSkipMessage" +}) +``` + +Merge response into `accumulated_state` after each poll. + +### Stale Check After Each Poll + +**Immediately after receiving `ci_information` response, before any other processing:** + +1. **Check if CI already succeeded:** + + ``` + IF cipeStatus == 'SUCCEEDED': + → Return immediately with ci_success + → Do NOT sleep, do NOT continue polling + ``` + +2. **If in wait mode, verify we're still relevant:** + + ``` + IF expectedCommitSha provided AND current commitSha matches AND cipeStatus == 'SUCCEEDED': + → Our expected CI Attempt ran and passed + → Return immediately with ci_success + ``` + +This prevents continuing to poll after CI has already completed. + +### Analyze Response + +**If in Wait Mode** (expecting new CI Attempt): + +1. Check if CI Attempt is new (see Two-Phase Operation above) +2. If old CI Attempt → **ignore status**, output wait message, poll again +3. If new CI Attempt → switch to normal mode, continue below + +**If in Normal Mode**: +Based on the response, decide whether to **keep polling** or **return to main agent**. + +### Keep Polling When + +Continue polling (with backoff) if ANY of these conditions are true: + +| Condition | Reason | +| --------------------------------------- | ---------------------------------------- | +| `cipeStatus == 'IN_PROGRESS'` | CI still running | +| `cipeStatus == 'NOT_STARTED'` | CI hasn't started yet | +| `selfHealingStatus == 'IN_PROGRESS'` | Self-healing agent working | +| `selfHealingStatus == 'NOT_STARTED'` | Self-healing not started yet (see note) | +| `failureClassification == 'FLAKY_TASK'` | Auto-rerun in progress | +| `userAction == 'APPLIED_AUTOMATICALLY'` | New CI Attempt spawning after auto-apply | + +**Note:** When `selfHealingSkippedReason` is present, do NOT continue polling on `selfHealingStatus == NOT_STARTED`. The throttled state means self-healing will not start — return `self_healing_throttled` immediately. + +When `couldAutoApplyTasks == true`: + +- `verificationStatus` = `NOT_STARTED`, `IN_PROGRESS` → keep polling (verification still in progress) +- `verificationStatus` = `COMPLETED` → return `fix_auto_applying` (auto-apply will happen, main agent spawns wait mode subagent) +- `verificationStatus` = `FAILED`, `NOT_EXECUTABLE` → return `fix_available` (auto-apply won't happen, needs manual action) + +### Exponential Backoff + +Between polls, wait with exponential backoff: + +| Poll Attempt | Wait Time | +| ------------ | ----------------- | +| 1st | 60 seconds | +| 2nd | 90 seconds | +| 3rd+ | 120 seconds (cap) | + +Reset to 60 seconds when state changes significantly. + +### CRITICAL: Foreground-Only Sleep + +**NEVER run sleep as a background command.** This is the #1 cause of stale timer issues. + +| Pattern | Result | +| ------------------- | ------------------------------------------- | +| `sleep 60` | ✅ CORRECT - blocks until complete | +| `sleep 60 &` | ❌ WRONG - creates orphan timer | +| `(sleep 60 && ...)` | ❌ WRONG - subshell continues independently | +| `nohup sleep ...` | ❌ WRONG - survives agent termination | + +**Why this matters**: Background sleep commands create timer processes that outlive the polling context. When they complete, they trigger actions in a stale context, causing "CI already passed" spam. + +```bash +# Example backoff - run in FOREGROUND (blocking) +sleep 60 # First wait - BLOCKS until complete +sleep 90 # Second wait - BLOCKS until complete +sleep 120 # Third and subsequent waits (capped) - BLOCKS until complete +``` + +### Fetch Heavy Fields on Actionable State + +Before returning to main agent, fetch heavy fields if the status requires them: + +| Status | Heavy Fields Needed | +| ------------------------ | ------------------------------------------------------------------------------ | +| `ci_success` | None | +| `fix_auto_applying` | None | +| `fix_available` | `taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription` | +| `fix_failed` | `taskOutputSummary` | +| `no_fix` | `taskOutputSummary` | +| `environment_issue` | None | +| `no_new_cipe` | None | +| `polling_timeout` | None | +| `cipe_canceled` | None | +| `cipe_timed_out` | None | +| `self_healing_throttled` | `selfHealingSkipMessage` | +| `cipe_no_tasks` | None | + +``` +# Example: fetching heavy fields for fix_available +ci_information({ + branch: "", + select: "taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription" +}) +``` + +Merge response into `accumulated_state`, then return merged state to main agent. + +**Pagination:** Heavy string fields return first page only. If `hasMore` indicated, include in return format so main agent knows more content available. + +### Return to Main Agent When + +Return immediately with structured state if ANY of these conditions are true: + +| Status | Condition | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ci_success` | `cipeStatus == 'SUCCEEDED'` | +| `fix_auto_applying` | `selfHealingStatus == 'COMPLETED'` AND `couldAutoApplyTasks == true` AND `verificationStatus == 'COMPLETED'` | +| `fix_available` | `selfHealingStatus == 'COMPLETED'` AND `suggestedFix != null` AND (`couldAutoApplyTasks != true` OR `verificationStatus` in (`FAILED`, `NOT_EXECUTABLE`)) | +| `fix_failed` | `selfHealingStatus == 'FAILED'` | +| `environment_issue` | `failureClassification == 'ENVIRONMENT_STATE'` | +| `no_fix` | `cipeStatus == 'FAILED'` AND (`selfHealingEnabled == false` OR `selfHealingStatus == 'NOT_EXECUTABLE'`) | +| `no_new_cipe` | No CI Attempt found for branch (normal mode) or no new CI Attempt detected (wait mode) after `newCipeTimeout` (default 10 min) | +| `polling_timeout` | Subagent has been polling for > configured timeout (default 30 min) | +| `cipe_canceled` | `cipeStatus == 'CANCELED'` | +| `cipe_timed_out` | `cipeStatus == 'TIMED_OUT'` | +| `self_healing_throttled` | `selfHealingSkippedReason == 'THROTTLED'` | +| `cipe_no_tasks` | `cipeStatus == 'FAILED'` AND `failedTaskIds.length == 0` AND `selfHealingStatus == null` | + +## Subagent Timeout + +Track elapsed time: + +### New-CI-Attempt Timeout (both modes) + +**`newCipeTimeout`** (default: 10 minutes, configurable via main agent). Applies to both normal mode and wait mode: + +- **Normal mode:** If no CI Attempt is found for the branch after `newCipeTimeout` minutes of polling, return `no_new_cipe` with actionable suggestions. +- **Wait mode:** If no new CI Attempt is detected after `newCipeTimeout` minutes of polling, return `no_new_cipe`. + +Track separately from main polling timeout. + +### Main Polling Timeout + +If you have been polling for more than **30 minutes** (configurable via `subagentTimeout`), return with `status: polling_timeout`. + +## Return Format + +When returning to the main agent, provide a structured response with accumulated state: + +``` +## CI Monitor Result + +**Status:** +**Iterations:** +**Elapsed:** m s + +### CI Attempt Details +- **Status:** +- **URL:** +- **Branch:** +- **Commit:** +- **Failed Tasks:** +- **Verified Tasks:** + +### Self-Healing Details +- **Enabled:** +- **Status:** +- **Verification:** +- **User Action:** +- **Classification:** +- **Confidence:** +- **Confidence Reasoning:** + +### Fix Information (if available) +- **Short Link:** +- **Description:** +- **Reasoning:** + +### Hints (if any) + + +### Task Output Summary (first page) + +[MORE_CONTENT_AVAILABLE: taskOutputSummary, pageToken: 1] + +### Suggested Fix (first page) + +[MORE_CONTENT_AVAILABLE: suggestedFix, pageToken: 1] +``` + +### Pagination Indicators + +When a heavy field has more content available, append indicator: + +``` +[MORE_CONTENT_AVAILABLE: , pageToken: ] +``` + +Main agent can fetch additional pages if needed using: + +``` +ci_information({ select: "", pageToken: }) +``` + +Fields that may have pagination: + +- `taskOutputSummary` (reverse pagination - page 0 = most recent) +- `suggestedFix` (forward pagination - page 0 = start) +- `suggestedFixReasoning` + +### Return Format for `no_new_cipe` + +When returning with `status: no_new_cipe`, include additional context: + +``` +## CI Monitor Result + +**Status:** no_new_cipe +**Iterations:** +**Elapsed:** m s +**Timeout:** newCipeTimeout ( min) exceeded + +### Context +- **Mode:** +- **Expected Commit SHA:** (if wait mode) +- **Previous CI Attempt URL:** (if wait mode) +- **Last Seen CI Attempt URL:** +- **Last Seen Commit SHA:** + +### Likely Cause +No CI Attempt appeared within the newCipeTimeout window. +If in wait mode: CI workflow likely failed before Nx tasks could run (e.g., install step, checkout, auth). +If in normal mode: No CI Attempt exists for this branch yet. +Check your CI provider logs for the branch or commit. + +### Suggestions +- Verify the push succeeded and CI workflow was triggered +- Check CI provider configuration and logs +- Ensure commit SHA matches expected value +``` + +### Return Format for `polling_timeout` + +When returning with `status: polling_timeout`, include additional context: + +``` +## CI Monitor Result + +**Status:** polling_timeout +**Iterations:** +**Elapsed:** m s +**Timeout:** 30-minute polling timeout exceeded + +### Last Known CI Attempt State +- **Status:** +- **URL:** +- **Branch:** +- **Commit:** +- **Self-Healing:** +- **Verification:** + +### Suggestions +- CI pipeline or self-healing may be stuck +- Check Nx Cloud dashboard for the CI Attempt +- Consider stopping this agent and starting fresh +``` + +## Status Reporting (Verbosity-Controlled) + +**Important:** When running in background mode, your text output goes to an output file — it is NOT directly visible to users. The main agent is responsible for reading your output and relaying it to the user. Write your status lines clearly and consistently so the main agent can parse and forward them. + +Output is controlled by the `verbosity` parameter from the main agent: + +| Level | What to Output | +| --------- | ------------------------------------------------------------------------- | +| `minimal` | Only critical lifecycle transitions (always output, all verbosity levels) | +| `medium` | Compact status line on every poll (not just state changes). | +| `verbose` | Output detailed phase information after every poll. | + +### Minimal Verbosity + +Output **ONLY significant lifecycle transitions** regardless of verbosity. These critical transitions are ALWAYS output at ALL verbosity levels: + +- CI pipeline failed (`cipeStatus` changed to FAILED) +- Self-healing fix generation started (`selfHealingStatus` changed to IN_PROGRESS) +- Self-healing fix generated (`selfHealingStatus` changed to COMPLETED) +- Fix verification started (`verificationStatus` changed to IN_PROGRESS) +- Fix verification completed (`verificationStatus` changed to COMPLETED or FAILED) + +Use a compact single-line format: + +``` +⚡ CI failed — self-healing fix generation started +⚡ Self-healing fix generated — verification started +⚡ Fix verification completed successfully +⚡ Fix verification failed +``` + +### Medium Verbosity (Default) + +Output **compact status line on every poll** (not just state transitions). Format should be single-line: + +``` +[ci-monitor] Poll #N | CI: STATUS | Self-healing: STATUS | Verification: STATUS | Next poll: Xs +``` + +Example: + +``` +[ci-monitor] Poll #1 | CI: IN_PROGRESS | Self-healing: NOT_STARTED | Verification: NOT_STARTED | Next poll: 60s +[ci-monitor] Poll #2 | CI: FAILED | Self-healing: IN_PROGRESS | Verification: NOT_STARTED | Next poll: 90s +[ci-monitor] Poll #3 | CI: FAILED | Self-healing: COMPLETED | Verification: IN_PROGRESS | Next poll: 120s +``` + +### Verbose Verbosity + +Output detailed phase box after every poll: + +``` +[ci-monitor-subagent] ───────────────────────────────────────────────────── +[ci-monitor-subagent] Iteration | Elapsed: m s +[ci-monitor-subagent] +[ci-monitor-subagent] CI Status: +[ci-monitor-subagent] Self-Healing: +[ci-monitor-subagent] Verification: +[ci-monitor-subagent] Classification: +[ci-monitor-subagent] +[ci-monitor-subagent] → +[ci-monitor-subagent] ───────────────────────────────────────────────────── +``` + +### Phase Descriptions (for verbose output) + +| Status Combo | Description | +| ----------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| `cipeStatus: IN_PROGRESS` | "CI running..." | +| `cipeStatus: NOT_STARTED` | "Waiting for CI to start..." | +| `cipeStatus: FAILED` + `selfHealingStatus: NOT_STARTED` | "CI failed. Self-healing starting..." | +| `cipeStatus: FAILED` + `selfHealingStatus: IN_PROGRESS` | "CI failed. Self-healing generating fix..." | +| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: IN_PROGRESS` | "Fix generated! Verification running..." | +| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: COMPLETED` | "Fix ready! Verified successfully." | +| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: FAILED` | "Fix generated but verification failed." | +| `cipeStatus: FAILED` + `selfHealingStatus: FAILED` | "Self-healing could not generate a fix." | +| `cipeStatus: FAILED` + `selfHealingSkippedReason: 'THROTTLED'` | "Self-healing throttled — too many unapplied fixes." | +| `cipeStatus: SUCCEEDED` | "CI passed!" | + +## Important Notes + +- You do NOT make apply/reject decisions - that's the main agent's job +- You do NOT perform git operations +- You only poll and report state +- Respect the `verbosity` parameter for output (default: medium) +- If `ci_information` returns an error, wait and retry (count as failed poll) +- Track consecutive failures - if 5 consecutive failures, return with `status: error` +- `newCipeTimeout` applies to both normal and wait mode — if no CI Attempt appears within this window, return `no_new_cipe` +- Track `newCipeTimeout` (default 10 minutes) separately from main polling timeout (default 30 minutes) +- If the `hints` array in `ci_information` responses is non-empty, include hints in your return format. diff --git a/.github/prompts/monitor-ci.prompt.md b/.github/prompts/monitor-ci.prompt.md new file mode 100644 index 0000000..f20c77d --- /dev/null +++ b/.github/prompts/monitor-ci.prompt.md @@ -0,0 +1,678 @@ +--- +description: Monitor Nx Cloud CI pipeline and handle self-healing fixes. USE WHEN user says "monitor ci", "watch ci", "ci monitor", "watch ci for this branch", "track ci", "check ci status", wants to track CI status, or needs help with self-healing CI fixes. ALWAYS USE THIS SKILL instead of native CI provider tools (gh, glab, etc.) for CI monitoring. +argument-hint: '[instructions] [--max-cycles N] [--timeout MINUTES] [--verbosity minimal|medium|verbose] [--branch BRANCH] [--fresh] [--auto-fix-workflow] [--new-cipe-timeout MINUTES]' +--- + +# Monitor CI Command + +You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-monitor-subagent` subagent to poll CI status and make decisions based on the results. + +## Context + +- **Current Branch:** !`git branch --show-current` +- **Current Commit:** !`git rev-parse --short HEAD` +- **Remote Status:** !`git status -sb | head -1` + +## User Instructions + +${input:args} + +**Important:** If user provides specific instructions, respect them over default behaviors described below. + +## Configuration Defaults + +| Setting | Default | Description | +| ------------------------- | ------------- | ------------------------------------------------------------------------- | +| `--max-cycles` | 10 | Maximum **agent-initiated** CI Attempt cycles before timeout | +| `--timeout` | 120 | Maximum duration in minutes | +| `--verbosity` | medium | Output level: minimal, medium, verbose | +| `--branch` | (auto-detect) | Branch to monitor | +| `--subagent-timeout` | 30 | Subagent polling timeout in minutes | +| `--fresh` | false | Ignore previous context, start fresh | +| `--auto-fix-workflow` | false | Attempt common fixes for pre-CI-Attempt failures (e.g., lockfile updates) | +| `--new-cipe-timeout` | 10 | Minutes to wait for new CI Attempt after action | +| `--local-verify-attempts` | 3 | Max local verification + enhance cycles before pushing to CI | + +Parse any overrides from `${input:args}` and merge with defaults. + +## Nx Cloud Connection Check + +**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud. + +### Step 0: Verify Nx Cloud Connection + +1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken` +2. **If `nx.json` missing OR neither property exists** → exit with: + + ``` + [monitor-ci] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud + ``` + +3. **If connected** → continue to main loop + +## Anti-Patterns (NEVER DO) + +**CRITICAL**: The following behaviors are strictly prohibited: + +| Anti-Pattern | Why It's Bad | +| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| Using CI provider CLIs with `--watch` flags (e.g., `gh pr checks --watch`, `glab ci status -w`) | Bypasses Nx Cloud self-healing entirely | +| Writing custom CI polling scripts | Unreliable, pollutes context, no self-healing | +| Cancelling CI workflows/pipelines | Destructive, loses CI progress | +| Running CI checks on main agent | Wastes main agent context tokens | +| Independently analyzing/fixing CI failures while subagent polls | Races with self-healing, causes duplicate fixes and confused state | + +**If this skill fails to activate**, the fallback is: + +1. Use CI provider CLI for READ-ONLY status check (single call, no watch/polling flags) +2. Immediately delegate to this skill with gathered context +3. NEVER continue polling on main agent + +**CI provider CLIs are acceptable ONLY for:** + +- One-time read of PR/pipeline status +- Getting PR/branch metadata +- NOT for continuous monitoring or watch mode + +## Session Context Behavior + +**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/monitor-ci`, Claude remembers the previous state and may continue from where it left off. + +- **To continue monitoring:** Just re-run `/monitor-ci` (context is preserved) +- **To start fresh:** Use `/monitor-ci --fresh` to ignore previous context +- **For a completely clean slate:** Exit Claude Code and restart `claude` + +## Default Behaviors by Status + +The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these. + +| Status | Default Behavior | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ci_success` | Exit with success. Log "CI passed successfully!" | +| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CI Attempt. | +| `fix_available` | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below. | +| `fix_failed` | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure. | +| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CI Attempt spawns automatically. Loop to poll for new CI Attempt. | +| `self_healing_throttled` | Self-healing throttled due to unapplied fixes. See **Throttled Self-Healing Flow** below. | +| `no_fix` | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure. | +| `no_new_cipe` | Expected CI Attempt never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance. | +| `polling_timeout` | Subagent polling timeout reached. Exit with timeout. | +| `cipe_canceled` | CI Attempt was canceled. Exit with canceled status. | +| `cipe_timed_out` | CI Attempt timed out. Exit with timeout status. | +| `cipe_no_tasks` | CI Attempt exists but failed with no task data (likely infrastructure issue). Retry once with empty commit. If retry fails, exit with failure and guidance. | +| `error` | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop. | + +### Fix Available Decision Logic + +When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`: + +#### Step 1: Categorize Tasks + +1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds` +2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds` +3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `:` or `::`) +4. **Verifiable tasks** = unverified tasks that are NOT e2e + +#### Step 2: Determine Path + +| Condition | Path | +| --------------------------------------- | ---------------------------------------- | +| No unverified tasks (all verified) | Apply via MCP | +| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) | +| Verifiable tasks exist | Local verification flow | + +#### Step 3a: Apply via MCP (fully/e2e-only verified) + +- Call `update_self_healing_fix({ shortLink, action: "APPLY" })` +- Record `last_cipe_url`, spawn subagent in wait mode + +#### Step 3b: Local Verification Flow + +When verifiable (non-e2e) unverified tasks exist: + +1. **Detect package manager:** + + - `pnpm-lock.yaml` exists → `pnpm nx` + - `yarn.lock` exists → `yarn nx` + - Otherwise → `npx nx` + +2. **Run verifiable tasks in parallel:** + + - Spawn `general` subagents to run each task concurrently + - Each subagent runs: ` nx run ` + - Collect pass/fail results from all subagents + +3. **Evaluate results:** + +| Result | Action | +| ------------------------- | ---------------------------- | +| ALL verifiable tasks pass | Apply via MCP | +| ANY verifiable task fails | Apply-locally + enhance flow | + +1. **Apply-locally + enhance flow:** + + - Run `nx-cloud apply-locally ` + - Enhance the code to fix failing tasks + - Run failing tasks again to verify fix + - If still failing → increment `local_verify_count`, loop back to enhance + - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode + +2. **Track attempts** (wraps step 4): + + - Increment `local_verify_count` after each enhance cycle + - If `local_verify_count >= local_verify_attempts` (default: 3): + + - Get code in commit-able state + - Commit and push with message indicating local verification failed + - Report to user: + + ``` + [monitor-ci] Local verification failed after attempts. Pushed to CI for final validation. Failed: + ``` + + - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge) + +#### Commit Message Format + +```bash +git commit -m "fix(): + +Failed tasks: , +Local verification: passed|enhanced|failed-pushing-to-ci" +``` + +**Git Safety**: Only stage and commit files that were modified as part of the fix. Users may have concurrent local changes (local publish, WIP features, config tweaks) that must NOT be committed. NEVER use `git add -A` or `git add .` — always stage specific files by name. + +### Unverified Fix Flow (No Verification Attempted) + +When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification: + +- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`) +- If fix looks correct → apply via MCP +- If fix needs enhancement → use Apply Locally + Enhance Flow above +- If fix is wrong → reject via MCP, fix from scratch, commit, push + +### Auto-Apply Eligibility + +The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application: + +- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails. +- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject) + +**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode. No local git operations (no commit, no push). + +### Accidental Local Fix Recovery + +If you find yourself with uncommitted local changes from your own fix attempt when the subagent returns (e.g., you accidentally analyzed/fixed the failure while the subagent was polling): + +1. **Compare your local changes with the self-healing fix** (`suggestedFix` / `suggestedFixDescription`) +2. **If identical or substantially similar** → discard only the files you modified (`git checkout -- ...`), then apply via MCP instead. Self-healing's pipeline is the preferred path. Do NOT discard unrelated user changes. +3. **If meaningfully different** (your fix addresses something self-healing missed) → proceed with the Apply Locally + Enhance Flow + +Self-healing fixes go through proper CI verification. Always prefer the self-healing path when fixes overlap. + +### Apply vs Reject vs Apply Locally + +- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CI Attempt spawns automatically. No local git operations needed. +- **Apply Locally**: Runs `nx-cloud apply-locally `. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing. +- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch. + +### Apply Locally + Enhance Flow + +When the fix needs enhancement (use `nx-cloud apply-locally`, NOT reject): + +1. Apply the patch locally: `nx-cloud apply-locally ` (this also updates state to `APPLIED_LOCALLY`) +2. Make additional changes as needed +3. Stage only the files you modified: `git add ...` +4. Commit and push: + + ```bash + git commit -m "fix: resolve " + git push origin $(git branch --show-current) + ``` + +5. Loop to poll for new CI Attempt + +### Reject + Fix From Scratch Flow + +When the fix is completely wrong: + +1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })` +2. Fix the issue from scratch locally +3. Stage only the files you modified: `git add ...` +4. Commit and push: + + ```bash + git commit -m "fix: resolve " + git push origin $(git branch --show-current) + ``` + +5. Loop to poll for new CI Attempt + +### Environment Issue Handling + +When `failureClassification == 'ENVIRONMENT_STATE'`: + +1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })` +2. New CI Attempt spawns automatically (no local git operations needed) +3. Loop to poll for new CI Attempt with `previousCipeUrl` set + +### Throttled Self-Healing Flow + +When `status == 'self_healing_throttled'`: + +Self-healing was skipped because too many previous fixes remain unapplied. The `selfHealingSkipMessage` contains URLs to CIPEs with pending fixes. + +1. **Parse throttle message** for CIPE URLs using regex matching `/cipes/{id}` pattern (format: `https://...nx.app/cipes/{cipeId}/self-healing`) +2. **Reject previous fixes** — for each CIPE URL found: + - Call `ci_information({ url: "" })` to get the `shortLink` + - Call `update_self_healing_fix({ shortLink: "", action: "REJECT" })` to reject +3. **Attempt local fix**: + - Use `failedTaskIds` from the current CIPE + - Use `taskOutputSummary` (fetch via select if available) for context + - Try to fix locally, run tasks to verify +4. **Fallback if local fix not possible**: + - Push empty commit (`git commit --allow-empty -m "ci: rerun after rejecting throttled fixes"`) + - Push to trigger new CI + - Spawn subagent in wait mode to poll for new CI Attempt +5. After rejecting fixes and pushing, self-healing should resume since throttle condition (unapplied fixes) is cleared + +### No-New-CI-Attempt Handling + +When `status == 'no_new_cipe'`: + +This means the expected CI Attempt was never created - CI likely failed before Nx tasks could run. + +1. **Report to user:** + + ``` + [monitor-ci] No CI attempt for after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: + ``` + +2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`): + + - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json` + - Run install to update lockfile: + + ```bash + pnpm install # or npm install / yarn install + ``` + + - If lockfile changed: + + ```bash + git add pnpm-lock.yaml # or appropriate lockfile + git commit -m "chore: update lockfile" + git push origin $(git branch --show-current) + ``` + + - Record new commit SHA, loop to poll with `expectedCommitSha` + +3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate + +### CI-Attempt-No-Tasks Handling + +When `status == 'cipe_no_tasks'`: + +This means the CI Attempt was created but no Nx tasks were recorded before it failed. Common causes: + +- CI timeout before tasks could run +- Critical infrastructure error +- Memory/resource exhaustion +- Network issues connecting to Nx Cloud + +1. **Report to user:** + + ``` + [monitor-ci] CI failed but no Nx tasks were recorded. + [monitor-ci] CI Attempt URL: + [monitor-ci] + [monitor-ci] This usually indicates an infrastructure issue. Attempting retry... + ``` + +2. **Create empty commit to retry CI:** + + ```bash + git commit --allow-empty -m "chore: retry ci [monitor-ci]" + git push origin $(git branch --show-current) + ``` + +3. **Record `expected_commit_sha`, spawn subagent in wait mode** + +4. **If retry also returns `cipe_no_tasks`:** + + - Exit with failure + - Provide guidance: + + ``` + [monitor-ci] Retry failed. Please check: + [monitor-ci] 1. Nx Cloud UI: + [monitor-ci] 2. CI provider logs (GitHub Actions, GitLab CI, etc.) + [monitor-ci] 3. CI job timeout settings + [monitor-ci] 4. Memory/resource limits + ``` + +## Exit Conditions + +Exit the monitoring loop when ANY of these conditions are met: + +| Condition | Exit Type | +| ------------------------------------------------------------ | ---------------------- | +| CI passes (`cipeStatus == 'SUCCEEDED'`) | Success | +| Max agent-initiated cycles reached (after user declines ext) | Timeout | +| Max duration reached | Timeout | +| 3 consecutive no-progress iterations | Circuit breaker | +| No fix available and local fix not possible | Failure | +| No new CI Attempt and auto-fix not configured | Pre-CI-Attempt failure | +| User cancels | Cancelled | + +## Main Loop + +### Step 1: Initialize Tracking + +``` +cycle_count = 0 # Only incremented for agent-initiated cycles (counted against --max-cycles) +start_time = now() +no_progress_count = 0 +local_verify_count = 0 +last_state = null +last_cipe_url = null +expected_commit_sha = null +agent_triggered = false # Set true after monitor takes an action that triggers new CI Attempt +``` + +### Step 2: Spawn Subagent and Monitor Output + +Spawn the `ci-monitor-subagent` subagent to poll CI status. **Run in background** so you can actively monitor and relay its output to the user. + +**Fresh start (first spawn, no expected CI Attempt):** + +``` +Task( + agent: "ci-monitor-subagent", + run_in_background: true, + prompt: "Monitor CI for branch ''. + Subagent timeout: minutes. + New-CI-Attempt timeout: minutes. + Verbosity: ." +) +``` + +**After action that triggers new CI Attempt (wait mode):** + +``` +Task( + agent: "ci-monitor-subagent", + run_in_background: true, + prompt: "Monitor CI for branch ''. + Subagent timeout: minutes. + New-CI-Attempt timeout: minutes. + Verbosity: . + + WAIT MODE: A new CI Attempt should spawn. Ignore old CI Attempt until new one appears. + Expected commit SHA: + Previous CI Attempt URL: " +) +``` + +### Step 2a: Active Output Monitoring (CRITICAL) + +**The subagent's text output is NOT visible to users when running in background.** You MUST actively monitor and relay its output. Do NOT passively wait for completion. + +After spawning the background subagent, enter a monitoring loop: + +1. **Every 60 seconds**, check the subagent output using `TaskOutput(task_id, block=false)` +2. **Parse new lines** since your last check — look for `[ci-monitor]` and `⚡` prefixed lines +3. **Relay to user** based on verbosity: + - `minimal`: Only relay `⚡` critical transition lines + - `medium`: Relay all `[ci-monitor]` status lines + - `verbose`: Relay all subagent output +4. **Continue** until `TaskOutput` returns a completed status +5. When complete, proceed to Step 3 with the final subagent response + +**Example monitoring loop output:** + +``` +[monitor-ci] Checking subagent status... (elapsed: 1m) +[monitor-ci] CI: IN_PROGRESS | Self-healing: NOT_STARTED + +[monitor-ci] Checking subagent status... (elapsed: 3m) +[monitor-ci] CI: FAILED | Self-healing: IN_PROGRESS +[monitor-ci] ⚡ CI failed — self-healing fix generation started + +[monitor-ci] Checking subagent status... (elapsed: 5m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED | Verification: IN_PROGRESS +[monitor-ci] ⚡ Self-healing fix generated — verification started +``` + +**NEVER do this:** + +- Spawn subagent and passively say "Waiting for results..." +- Check once and say "Still working, I'll wait" +- Only show output when the subagent finishes +- Independently analyze CI failures, read task output, or attempt fixes while subagent is polling + +**While the subagent is polling, your ONLY job is to relay its output.** Do not read CI task output, diagnose failures, generate fixes, modify code, or run tasks locally. All fix decisions happen in Step 3 AFTER the subagent returns with a status. Self-healing may already be working on a fix — independent local analysis races with it and causes duplicate/conflicting fixes. + +### Step 3: Handle Subagent Response + +When subagent returns: + +1. Check the returned status +2. Look up default behavior in the table above +3. Check if user instructions override the default +4. Execute the appropriate action +5. **If action expects new CI Attempt**, update tracking (see Step 3a) +6. If action results in looping, go to Step 2 + +### Step 3a: Track State for New-CI-Attempt Detection + +After actions that should trigger a new CI Attempt, record state before looping: + +| Action | What to Track | Subagent Mode | +| ----------------------------------- | --------------------------------------------- | ------------- | +| Fix auto-applying | `last_cipe_url = current cipeUrl` | Wait mode | +| Apply via MCP | `last_cipe_url = current cipeUrl` | Wait mode | +| Apply locally + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| Reject + fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| No fix + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| Environment rerun | `last_cipe_url = current cipeUrl` | Wait mode | +| No-new-CI-Attempt + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| CI Attempt no tasks + retry push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | + +**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**: + +- Subagent will **completely ignore** the old/stale CI Attempt +- Subagent will only wait for new CI Attempt to appear +- Subagent will NOT return to main agent with stale CI Attempt data +- Once new CI Attempt detected, subagent switches to normal polling + +**Why wait mode matters for context preservation**: Stale CI Attempt data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CI Attempt. Wait mode keeps stale data in the subagent, never sending it to main agent. + +### Step 4: Cycle Classification and Progress Tracking + +#### Cycle Classification + +Not all cycles are equal. Only count cycles the monitor itself triggered toward `--max-cycles`: + +1. **After subagent returns**, check `agent_triggered`: + - `agent_triggered == true` → this cycle was triggered by the monitor → `cycle_count++` + - `agent_triggered == false` → this cycle was human-initiated or a first observation → do NOT increment `cycle_count` +2. **Reset** `agent_triggered = false` +3. **After Step 3a** (when the monitor takes an action that triggers a new CI Attempt) → set `agent_triggered = true` + +**How detection works**: Step 3a is only called when the monitor explicitly pushes code, applies a fix via MCP, or triggers an environment rerun. If a human pushes on their own, the subagent detects a new CI Attempt but the monitor never went through Step 3a, so `agent_triggered` remains `false`. + +**When a human-initiated cycle is detected**, log it: + +``` +[monitor-ci] New CI Attempt detected (human-initiated push). Monitoring without incrementing cycle count. (agent cycles: N/max-cycles) +``` + +#### Approaching Limit Gate + +When `cycle_count >= max_cycles - 2`, pause and ask the user before continuing: + +``` +[monitor-ci] Approaching cycle limit (cycle_count/max_cycles agent-initiated cycles used). +[monitor-ci] How would you like to proceed? + 1. Continue with 5 more cycles + 2. Continue with 10 more cycles + 3. Stop monitoring +``` + +Increase `max_cycles` by the user's choice and continue. + +#### Progress Tracking + +After each action: + +- If state changed significantly → reset `no_progress_count = 0` +- If state unchanged → `no_progress_count++` +- On new CI attempt detected → reset `local_verify_count = 0` + +## Status Reporting + +Based on verbosity level: + +| Level | What to Report | +| --------- | -------------------------------------------------------------------------- | +| `minimal` | Only final result (success/failure/timeout) | +| `medium` | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") | +| `verbose` | All of medium + full subagent responses, git outputs, MCP responses | + +## User Instruction Examples + +Users can override default behaviors: + +| Instruction | Effect | +| ------------------------------------------------ | --------------------------------------------------- | +| "never auto-apply" | Always prompt before applying any fix | +| "always ask before git push" | Prompt before each push | +| "reject any fix for e2e tasks" | Auto-reject if `failedTaskIds` contains e2e | +| "apply all fixes regardless of verification" | Skip verification check, apply everything | +| "if confidence < 70, reject" | Check confidence field before applying | +| "run 'nx affected -t typecheck' before applying" | Add local verification step | +| "auto-fix workflow failures" | Attempt lockfile updates on pre-CI-Attempt failures | +| "wait 45 min for new CI Attempt" | Override new-CI-Attempt timeout (default: 10 min) | + +## Error Handling + +| Error | Action | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | +| Git rebase conflict | Report to user, exit | +| `nx-cloud apply-locally` fails | Reject fix via MCP (`action: "REJECT"`), then attempt manual patch (Reject + Fix From Scratch Flow) or exit | +| MCP tool error | Retry once, if fails report to user | +| Subagent spawn failure | Retry once, if fails exit with error | +| No new CI Attempt detected | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance | +| Lockfile auto-fix fails | Report to user, exit with guidance to check CI logs | + +## Example Session + +### Example 1: Normal Flow with Self-Healing (medium verbosity) + +``` +[monitor-ci] Starting CI monitor for branch 'feature/add-auth' +[monitor-ci] Config: max-cycles=5, timeout=120m, verbosity=medium + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 1m) +[monitor-ci] CI: IN_PROGRESS | Self-healing: NOT_STARTED +[monitor-ci] Checking subagent status... (elapsed: 3m) +[monitor-ci] CI: FAILED | Self-healing: IN_PROGRESS +[monitor-ci] ⚡ CI failed — self-healing fix generation started +[monitor-ci] Checking subagent status... (elapsed: 5m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED | Verification: COMPLETED + +[monitor-ci] Fix available! Verification: COMPLETED +[monitor-ci] Applying fix via MCP... +[monitor-ci] Fix applied in CI. Waiting for new CI attempt... + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 7m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] Checking subagent status... (elapsed: 8m) +[monitor-ci] CI: SUCCEEDED + +[monitor-ci] CI passed successfully! + +[monitor-ci] Summary: + - Agent cycles: 1/5 + - Total time: 12m 34s + - Fixes applied: 1 + - Result: SUCCESS +``` + +### Example 2: Pre-CI Failure (medium verbosity) + +``` +[monitor-ci] Starting CI monitor for branch 'feature/add-products' +[monitor-ci] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 2m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Fix available! Applying locally, enhancing, and pushing... +[monitor-ci] Committed: abc1234 + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 6m) +[monitor-ci] Waiting for new CI Attempt... (expected SHA: abc1234) +[monitor-ci] Checking subagent status... (elapsed: 12m) +[monitor-ci] ⚠️ CI Attempt timeout (10 min). Status: no_new_cipe + +[monitor-ci] --auto-fix-workflow enabled. Attempting lockfile update... +[monitor-ci] Lockfile updated. Committed: def5678 + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 16m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] Checking subagent status... (elapsed: 18m) +[monitor-ci] CI: SUCCEEDED + +[monitor-ci] CI passed successfully! + +[monitor-ci] Summary: + - Agent cycles: 3/5 + - Total time: 22m 15s + - Fixes applied: 1 (self-healing) + 1 (lockfile) + - Result: SUCCESS +``` + +### Example 3: Human-in-the-Loop (user pushes during monitoring) + +``` +[monitor-ci] Starting CI monitor for branch 'feature/refactor-api' +[monitor-ci] Config: max-cycles=5, timeout=120m, verbosity=medium + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 4m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Fix available! Applying fix via MCP... (agent cycles: 0/5) +[monitor-ci] Fix applied in CI. Waiting for new CI attempt... + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 8m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Agent-initiated cycle. (agent cycles: 1/5) +[monitor-ci] Fix available! Applying locally and enhancing... +[monitor-ci] Committed: abc1234 + +[monitor-ci] Spawning subagent to poll CI status... + ... (user pushes their own changes to the branch while monitor waits) ... +[monitor-ci] Checking subagent status... (elapsed: 12m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] CI: FAILED | Self-healing: IN_PROGRESS + +[monitor-ci] New CI Attempt detected (human-initiated push). Monitoring without incrementing cycle count. (agent cycles: 2/5) +[monitor-ci] Checking subagent status... (elapsed: 16m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Fix available! Applying via MCP... (agent cycles: 2/5) + ... (continues, human cycles don't eat into the budget) ... +``` diff --git a/.github/skills/link-workspace-packages/SKILL.md b/.github/skills/link-workspace-packages/SKILL.md new file mode 100644 index 0000000..de13134 --- /dev/null +++ b/.github/skills/link-workspace-packages/SKILL.md @@ -0,0 +1,127 @@ +--- +name: link-workspace-packages +description: 'Link workspace packages in monorepos (npm, yarn, pnpm, bun). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace packages (@org/*) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use the package manager''s workspace commands to fix actual linking.' +--- + +# Link Workspace Packages + +Add dependencies between packages in a monorepo. All package managers support workspaces but with different syntax. + +## Detect Package Manager + +Check whether there's a `packageManager` field in the root-level `package.json`. + +Alternatively check lockfile in repo root: + +- `pnpm-lock.yaml` → pnpm +- `yarn.lock` → yarn +- `bun.lock` / `bun.lockb` → bun +- `package-lock.json` → npm + +## Workflow + +1. Identify consumer package (the one importing) +2. Identify provider package(s) (being imported) +3. Add dependency using package manager's workspace syntax +4. Verify symlinks created in consumer's `node_modules/` + +--- + +## pnpm + +Uses `workspace:` protocol - symlinks only created when explicitly declared. + +```bash +# From consumer directory +pnpm add @org/ui --workspace + +# Or with --filter from anywhere +pnpm add @org/ui --filter @org/app --workspace +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "workspace:*" } } +``` + +--- + +## yarn (v2+/berry) + +Also uses `workspace:` protocol. + +```bash +yarn workspace @org/app add @org/ui +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "workspace:^" } } +``` + +--- + +## npm + +No `workspace:` protocol. npm auto-symlinks workspace packages. + +```bash +npm install @org/ui --workspace @org/app +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "*" } } +``` + +npm resolves to local workspace automatically during install. + +--- + +## bun + +Supports `workspace:` protocol (pnpm-compatible). + +```bash +cd packages/app && bun add @org/ui +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "workspace:*" } } +``` + +--- + +## Examples + +**Example 1: pnpm - link ui lib to app** + +```bash +pnpm add @org/ui --filter @org/app --workspace +``` + +**Example 2: npm - link multiple packages** + +```bash +npm install @org/data-access @org/ui --workspace @org/dashboard +``` + +**Example 3: Debug "Cannot find module"** + +1. Check if dependency is declared in consumer's `package.json` +2. If not, add it using appropriate command above +3. Run install (`pnpm install`, `npm install`, etc.) + +## Notes + +- Symlinks appear in `/node_modules/@org/` +- **Hoisting differs by manager:** + - npm/bun: hoist shared deps to root `node_modules` + - pnpm: no hoisting (strict isolation, prevents phantom deps) + - yarn berry: uses Plug'n'Play by default (no `node_modules`) +- Root `package.json` should have `"private": true` to prevent accidental publish diff --git a/.github/skills/monitor-ci/SKILL.md b/.github/skills/monitor-ci/SKILL.md new file mode 100644 index 0000000..e62f8ba --- /dev/null +++ b/.github/skills/monitor-ci/SKILL.md @@ -0,0 +1,678 @@ +--- +name: monitor-ci +description: Monitor Nx Cloud CI pipeline and handle self-healing fixes. USE WHEN user says "monitor ci", "watch ci", "ci monitor", "watch ci for this branch", "track ci", "check ci status", wants to track CI status, or needs help with self-healing CI fixes. ALWAYS USE THIS SKILL instead of native CI provider tools (gh, glab, etc.) for CI monitoring. +--- + +# Monitor CI Command + +You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-monitor-subagent` subagent to poll CI status and make decisions based on the results. + +## Context + +- **Current Branch:** !`git branch --show-current` +- **Current Commit:** !`git rev-parse --short HEAD` +- **Remote Status:** !`git status -sb | head -1` + +## User Instructions + +$ARGUMENTS + +**Important:** If user provides specific instructions, respect them over default behaviors described below. + +## Configuration Defaults + +| Setting | Default | Description | +| ------------------------- | ------------- | ------------------------------------------------------------------------- | +| `--max-cycles` | 10 | Maximum **agent-initiated** CI Attempt cycles before timeout | +| `--timeout` | 120 | Maximum duration in minutes | +| `--verbosity` | medium | Output level: minimal, medium, verbose | +| `--branch` | (auto-detect) | Branch to monitor | +| `--subagent-timeout` | 30 | Subagent polling timeout in minutes | +| `--fresh` | false | Ignore previous context, start fresh | +| `--auto-fix-workflow` | false | Attempt common fixes for pre-CI-Attempt failures (e.g., lockfile updates) | +| `--new-cipe-timeout` | 10 | Minutes to wait for new CI Attempt after action | +| `--local-verify-attempts` | 3 | Max local verification + enhance cycles before pushing to CI | + +Parse any overrides from `$ARGUMENTS` and merge with defaults. + +## Nx Cloud Connection Check + +**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud. + +### Step 0: Verify Nx Cloud Connection + +1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken` +2. **If `nx.json` missing OR neither property exists** → exit with: + + ``` + [monitor-ci] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud + ``` + +3. **If connected** → continue to main loop + +## Anti-Patterns (NEVER DO) + +**CRITICAL**: The following behaviors are strictly prohibited: + +| Anti-Pattern | Why It's Bad | +| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| Using CI provider CLIs with `--watch` flags (e.g., `gh pr checks --watch`, `glab ci status -w`) | Bypasses Nx Cloud self-healing entirely | +| Writing custom CI polling scripts | Unreliable, pollutes context, no self-healing | +| Cancelling CI workflows/pipelines | Destructive, loses CI progress | +| Running CI checks on main agent | Wastes main agent context tokens | +| Independently analyzing/fixing CI failures while subagent polls | Races with self-healing, causes duplicate fixes and confused state | + +**If this skill fails to activate**, the fallback is: + +1. Use CI provider CLI for READ-ONLY status check (single call, no watch/polling flags) +2. Immediately delegate to this skill with gathered context +3. NEVER continue polling on main agent + +**CI provider CLIs are acceptable ONLY for:** + +- One-time read of PR/pipeline status +- Getting PR/branch metadata +- NOT for continuous monitoring or watch mode + +## Session Context Behavior + +**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/monitor-ci`, Claude remembers the previous state and may continue from where it left off. + +- **To continue monitoring:** Just re-run `/monitor-ci` (context is preserved) +- **To start fresh:** Use `/monitor-ci --fresh` to ignore previous context +- **For a completely clean slate:** Exit Claude Code and restart `claude` + +## Default Behaviors by Status + +The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these. + +| Status | Default Behavior | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ci_success` | Exit with success. Log "CI passed successfully!" | +| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CI Attempt. | +| `fix_available` | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below. | +| `fix_failed` | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure. | +| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CI Attempt spawns automatically. Loop to poll for new CI Attempt. | +| `self_healing_throttled` | Self-healing throttled due to unapplied fixes. See **Throttled Self-Healing Flow** below. | +| `no_fix` | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure. | +| `no_new_cipe` | Expected CI Attempt never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance. | +| `polling_timeout` | Subagent polling timeout reached. Exit with timeout. | +| `cipe_canceled` | CI Attempt was canceled. Exit with canceled status. | +| `cipe_timed_out` | CI Attempt timed out. Exit with timeout status. | +| `cipe_no_tasks` | CI Attempt exists but failed with no task data (likely infrastructure issue). Retry once with empty commit. If retry fails, exit with failure and guidance. | +| `error` | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop. | + +### Fix Available Decision Logic + +When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`: + +#### Step 1: Categorize Tasks + +1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds` +2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds` +3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `:` or `::`) +4. **Verifiable tasks** = unverified tasks that are NOT e2e + +#### Step 2: Determine Path + +| Condition | Path | +| --------------------------------------- | ---------------------------------------- | +| No unverified tasks (all verified) | Apply via MCP | +| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) | +| Verifiable tasks exist | Local verification flow | + +#### Step 3a: Apply via MCP (fully/e2e-only verified) + +- Call `update_self_healing_fix({ shortLink, action: "APPLY" })` +- Record `last_cipe_url`, spawn subagent in wait mode + +#### Step 3b: Local Verification Flow + +When verifiable (non-e2e) unverified tasks exist: + +1. **Detect package manager:** + + - `pnpm-lock.yaml` exists → `pnpm nx` + - `yarn.lock` exists → `yarn nx` + - Otherwise → `npx nx` + +2. **Run verifiable tasks in parallel:** + + - Spawn `general` subagents to run each task concurrently + - Each subagent runs: ` nx run ` + - Collect pass/fail results from all subagents + +3. **Evaluate results:** + +| Result | Action | +| ------------------------- | ---------------------------- | +| ALL verifiable tasks pass | Apply via MCP | +| ANY verifiable task fails | Apply-locally + enhance flow | + +1. **Apply-locally + enhance flow:** + + - Run `nx-cloud apply-locally ` + - Enhance the code to fix failing tasks + - Run failing tasks again to verify fix + - If still failing → increment `local_verify_count`, loop back to enhance + - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode + +2. **Track attempts** (wraps step 4): + + - Increment `local_verify_count` after each enhance cycle + - If `local_verify_count >= local_verify_attempts` (default: 3): + + - Get code in commit-able state + - Commit and push with message indicating local verification failed + - Report to user: + + ``` + [monitor-ci] Local verification failed after attempts. Pushed to CI for final validation. Failed: + ``` + + - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge) + +#### Commit Message Format + +```bash +git commit -m "fix(): + +Failed tasks: , +Local verification: passed|enhanced|failed-pushing-to-ci" +``` + +**Git Safety**: Only stage and commit files that were modified as part of the fix. Users may have concurrent local changes (local publish, WIP features, config tweaks) that must NOT be committed. NEVER use `git add -A` or `git add .` — always stage specific files by name. + +### Unverified Fix Flow (No Verification Attempted) + +When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification: + +- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`) +- If fix looks correct → apply via MCP +- If fix needs enhancement → use Apply Locally + Enhance Flow above +- If fix is wrong → reject via MCP, fix from scratch, commit, push + +### Auto-Apply Eligibility + +The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application: + +- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails. +- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject) + +**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode. No local git operations (no commit, no push). + +### Accidental Local Fix Recovery + +If you find yourself with uncommitted local changes from your own fix attempt when the subagent returns (e.g., you accidentally analyzed/fixed the failure while the subagent was polling): + +1. **Compare your local changes with the self-healing fix** (`suggestedFix` / `suggestedFixDescription`) +2. **If identical or substantially similar** → discard only the files you modified (`git checkout -- ...`), then apply via MCP instead. Self-healing's pipeline is the preferred path. Do NOT discard unrelated user changes. +3. **If meaningfully different** (your fix addresses something self-healing missed) → proceed with the Apply Locally + Enhance Flow + +Self-healing fixes go through proper CI verification. Always prefer the self-healing path when fixes overlap. + +### Apply vs Reject vs Apply Locally + +- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CI Attempt spawns automatically. No local git operations needed. +- **Apply Locally**: Runs `nx-cloud apply-locally `. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing. +- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch. + +### Apply Locally + Enhance Flow + +When the fix needs enhancement (use `nx-cloud apply-locally`, NOT reject): + +1. Apply the patch locally: `nx-cloud apply-locally ` (this also updates state to `APPLIED_LOCALLY`) +2. Make additional changes as needed +3. Stage only the files you modified: `git add ...` +4. Commit and push: + + ```bash + git commit -m "fix: resolve " + git push origin $(git branch --show-current) + ``` + +5. Loop to poll for new CI Attempt + +### Reject + Fix From Scratch Flow + +When the fix is completely wrong: + +1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })` +2. Fix the issue from scratch locally +3. Stage only the files you modified: `git add ...` +4. Commit and push: + + ```bash + git commit -m "fix: resolve " + git push origin $(git branch --show-current) + ``` + +5. Loop to poll for new CI Attempt + +### Environment Issue Handling + +When `failureClassification == 'ENVIRONMENT_STATE'`: + +1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })` +2. New CI Attempt spawns automatically (no local git operations needed) +3. Loop to poll for new CI Attempt with `previousCipeUrl` set + +### Throttled Self-Healing Flow + +When `status == 'self_healing_throttled'`: + +Self-healing was skipped because too many previous fixes remain unapplied. The `selfHealingSkipMessage` contains URLs to CIPEs with pending fixes. + +1. **Parse throttle message** for CIPE URLs using regex matching `/cipes/{id}` pattern (format: `https://...nx.app/cipes/{cipeId}/self-healing`) +2. **Reject previous fixes** — for each CIPE URL found: + - Call `ci_information({ url: "" })` to get the `shortLink` + - Call `update_self_healing_fix({ shortLink: "", action: "REJECT" })` to reject +3. **Attempt local fix**: + - Use `failedTaskIds` from the current CIPE + - Use `taskOutputSummary` (fetch via select if available) for context + - Try to fix locally, run tasks to verify +4. **Fallback if local fix not possible**: + - Push empty commit (`git commit --allow-empty -m "ci: rerun after rejecting throttled fixes"`) + - Push to trigger new CI + - Spawn subagent in wait mode to poll for new CI Attempt +5. After rejecting fixes and pushing, self-healing should resume since throttle condition (unapplied fixes) is cleared + +### No-New-CI-Attempt Handling + +When `status == 'no_new_cipe'`: + +This means the expected CI Attempt was never created - CI likely failed before Nx tasks could run. + +1. **Report to user:** + + ``` + [monitor-ci] No CI attempt for after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: + ``` + +2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`): + + - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json` + - Run install to update lockfile: + + ```bash + pnpm install # or npm install / yarn install + ``` + + - If lockfile changed: + + ```bash + git add pnpm-lock.yaml # or appropriate lockfile + git commit -m "chore: update lockfile" + git push origin $(git branch --show-current) + ``` + + - Record new commit SHA, loop to poll with `expectedCommitSha` + +3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate + +### CI-Attempt-No-Tasks Handling + +When `status == 'cipe_no_tasks'`: + +This means the CI Attempt was created but no Nx tasks were recorded before it failed. Common causes: + +- CI timeout before tasks could run +- Critical infrastructure error +- Memory/resource exhaustion +- Network issues connecting to Nx Cloud + +1. **Report to user:** + + ``` + [monitor-ci] CI failed but no Nx tasks were recorded. + [monitor-ci] CI Attempt URL: + [monitor-ci] + [monitor-ci] This usually indicates an infrastructure issue. Attempting retry... + ``` + +2. **Create empty commit to retry CI:** + + ```bash + git commit --allow-empty -m "chore: retry ci [monitor-ci]" + git push origin $(git branch --show-current) + ``` + +3. **Record `expected_commit_sha`, spawn subagent in wait mode** + +4. **If retry also returns `cipe_no_tasks`:** + + - Exit with failure + - Provide guidance: + + ``` + [monitor-ci] Retry failed. Please check: + [monitor-ci] 1. Nx Cloud UI: + [monitor-ci] 2. CI provider logs (GitHub Actions, GitLab CI, etc.) + [monitor-ci] 3. CI job timeout settings + [monitor-ci] 4. Memory/resource limits + ``` + +## Exit Conditions + +Exit the monitoring loop when ANY of these conditions are met: + +| Condition | Exit Type | +| ------------------------------------------------------------ | ---------------------- | +| CI passes (`cipeStatus == 'SUCCEEDED'`) | Success | +| Max agent-initiated cycles reached (after user declines ext) | Timeout | +| Max duration reached | Timeout | +| 3 consecutive no-progress iterations | Circuit breaker | +| No fix available and local fix not possible | Failure | +| No new CI Attempt and auto-fix not configured | Pre-CI-Attempt failure | +| User cancels | Cancelled | + +## Main Loop + +### Step 1: Initialize Tracking + +``` +cycle_count = 0 # Only incremented for agent-initiated cycles (counted against --max-cycles) +start_time = now() +no_progress_count = 0 +local_verify_count = 0 +last_state = null +last_cipe_url = null +expected_commit_sha = null +agent_triggered = false # Set true after monitor takes an action that triggers new CI Attempt +``` + +### Step 2: Spawn Subagent and Monitor Output + +Spawn the `ci-monitor-subagent` subagent to poll CI status. **Run in background** so you can actively monitor and relay its output to the user. + +**Fresh start (first spawn, no expected CI Attempt):** + +``` +Task( + agent: "ci-monitor-subagent", + run_in_background: true, + prompt: "Monitor CI for branch ''. + Subagent timeout: minutes. + New-CI-Attempt timeout: minutes. + Verbosity: ." +) +``` + +**After action that triggers new CI Attempt (wait mode):** + +``` +Task( + agent: "ci-monitor-subagent", + run_in_background: true, + prompt: "Monitor CI for branch ''. + Subagent timeout: minutes. + New-CI-Attempt timeout: minutes. + Verbosity: . + + WAIT MODE: A new CI Attempt should spawn. Ignore old CI Attempt until new one appears. + Expected commit SHA: + Previous CI Attempt URL: " +) +``` + +### Step 2a: Active Output Monitoring (CRITICAL) + +**The subagent's text output is NOT visible to users when running in background.** You MUST actively monitor and relay its output. Do NOT passively wait for completion. + +After spawning the background subagent, enter a monitoring loop: + +1. **Every 60 seconds**, check the subagent output using `TaskOutput(task_id, block=false)` +2. **Parse new lines** since your last check — look for `[ci-monitor]` and `⚡` prefixed lines +3. **Relay to user** based on verbosity: + - `minimal`: Only relay `⚡` critical transition lines + - `medium`: Relay all `[ci-monitor]` status lines + - `verbose`: Relay all subagent output +4. **Continue** until `TaskOutput` returns a completed status +5. When complete, proceed to Step 3 with the final subagent response + +**Example monitoring loop output:** + +``` +[monitor-ci] Checking subagent status... (elapsed: 1m) +[monitor-ci] CI: IN_PROGRESS | Self-healing: NOT_STARTED + +[monitor-ci] Checking subagent status... (elapsed: 3m) +[monitor-ci] CI: FAILED | Self-healing: IN_PROGRESS +[monitor-ci] ⚡ CI failed — self-healing fix generation started + +[monitor-ci] Checking subagent status... (elapsed: 5m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED | Verification: IN_PROGRESS +[monitor-ci] ⚡ Self-healing fix generated — verification started +``` + +**NEVER do this:** + +- Spawn subagent and passively say "Waiting for results..." +- Check once and say "Still working, I'll wait" +- Only show output when the subagent finishes +- Independently analyze CI failures, read task output, or attempt fixes while subagent is polling + +**While the subagent is polling, your ONLY job is to relay its output.** Do not read CI task output, diagnose failures, generate fixes, modify code, or run tasks locally. All fix decisions happen in Step 3 AFTER the subagent returns with a status. Self-healing may already be working on a fix — independent local analysis races with it and causes duplicate/conflicting fixes. + +### Step 3: Handle Subagent Response + +When subagent returns: + +1. Check the returned status +2. Look up default behavior in the table above +3. Check if user instructions override the default +4. Execute the appropriate action +5. **If action expects new CI Attempt**, update tracking (see Step 3a) +6. If action results in looping, go to Step 2 + +### Step 3a: Track State for New-CI-Attempt Detection + +After actions that should trigger a new CI Attempt, record state before looping: + +| Action | What to Track | Subagent Mode | +| ----------------------------------- | --------------------------------------------- | ------------- | +| Fix auto-applying | `last_cipe_url = current cipeUrl` | Wait mode | +| Apply via MCP | `last_cipe_url = current cipeUrl` | Wait mode | +| Apply locally + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| Reject + fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| No fix + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| Environment rerun | `last_cipe_url = current cipeUrl` | Wait mode | +| No-new-CI-Attempt + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | +| CI Attempt no tasks + retry push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode | + +**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**: + +- Subagent will **completely ignore** the old/stale CI Attempt +- Subagent will only wait for new CI Attempt to appear +- Subagent will NOT return to main agent with stale CI Attempt data +- Once new CI Attempt detected, subagent switches to normal polling + +**Why wait mode matters for context preservation**: Stale CI Attempt data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CI Attempt. Wait mode keeps stale data in the subagent, never sending it to main agent. + +### Step 4: Cycle Classification and Progress Tracking + +#### Cycle Classification + +Not all cycles are equal. Only count cycles the monitor itself triggered toward `--max-cycles`: + +1. **After subagent returns**, check `agent_triggered`: + - `agent_triggered == true` → this cycle was triggered by the monitor → `cycle_count++` + - `agent_triggered == false` → this cycle was human-initiated or a first observation → do NOT increment `cycle_count` +2. **Reset** `agent_triggered = false` +3. **After Step 3a** (when the monitor takes an action that triggers a new CI Attempt) → set `agent_triggered = true` + +**How detection works**: Step 3a is only called when the monitor explicitly pushes code, applies a fix via MCP, or triggers an environment rerun. If a human pushes on their own, the subagent detects a new CI Attempt but the monitor never went through Step 3a, so `agent_triggered` remains `false`. + +**When a human-initiated cycle is detected**, log it: + +``` +[monitor-ci] New CI Attempt detected (human-initiated push). Monitoring without incrementing cycle count. (agent cycles: N/max-cycles) +``` + +#### Approaching Limit Gate + +When `cycle_count >= max_cycles - 2`, pause and ask the user before continuing: + +``` +[monitor-ci] Approaching cycle limit (cycle_count/max_cycles agent-initiated cycles used). +[monitor-ci] How would you like to proceed? + 1. Continue with 5 more cycles + 2. Continue with 10 more cycles + 3. Stop monitoring +``` + +Increase `max_cycles` by the user's choice and continue. + +#### Progress Tracking + +After each action: + +- If state changed significantly → reset `no_progress_count = 0` +- If state unchanged → `no_progress_count++` +- On new CI attempt detected → reset `local_verify_count = 0` + +## Status Reporting + +Based on verbosity level: + +| Level | What to Report | +| --------- | -------------------------------------------------------------------------- | +| `minimal` | Only final result (success/failure/timeout) | +| `medium` | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") | +| `verbose` | All of medium + full subagent responses, git outputs, MCP responses | + +## User Instruction Examples + +Users can override default behaviors: + +| Instruction | Effect | +| ------------------------------------------------ | --------------------------------------------------- | +| "never auto-apply" | Always prompt before applying any fix | +| "always ask before git push" | Prompt before each push | +| "reject any fix for e2e tasks" | Auto-reject if `failedTaskIds` contains e2e | +| "apply all fixes regardless of verification" | Skip verification check, apply everything | +| "if confidence < 70, reject" | Check confidence field before applying | +| "run 'nx affected -t typecheck' before applying" | Add local verification step | +| "auto-fix workflow failures" | Attempt lockfile updates on pre-CI-Attempt failures | +| "wait 45 min for new CI Attempt" | Override new-CI-Attempt timeout (default: 10 min) | + +## Error Handling + +| Error | Action | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | +| Git rebase conflict | Report to user, exit | +| `nx-cloud apply-locally` fails | Reject fix via MCP (`action: "REJECT"`), then attempt manual patch (Reject + Fix From Scratch Flow) or exit | +| MCP tool error | Retry once, if fails report to user | +| Subagent spawn failure | Retry once, if fails exit with error | +| No new CI Attempt detected | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance | +| Lockfile auto-fix fails | Report to user, exit with guidance to check CI logs | + +## Example Session + +### Example 1: Normal Flow with Self-Healing (medium verbosity) + +``` +[monitor-ci] Starting CI monitor for branch 'feature/add-auth' +[monitor-ci] Config: max-cycles=5, timeout=120m, verbosity=medium + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 1m) +[monitor-ci] CI: IN_PROGRESS | Self-healing: NOT_STARTED +[monitor-ci] Checking subagent status... (elapsed: 3m) +[monitor-ci] CI: FAILED | Self-healing: IN_PROGRESS +[monitor-ci] ⚡ CI failed — self-healing fix generation started +[monitor-ci] Checking subagent status... (elapsed: 5m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED | Verification: COMPLETED + +[monitor-ci] Fix available! Verification: COMPLETED +[monitor-ci] Applying fix via MCP... +[monitor-ci] Fix applied in CI. Waiting for new CI attempt... + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 7m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] Checking subagent status... (elapsed: 8m) +[monitor-ci] CI: SUCCEEDED + +[monitor-ci] CI passed successfully! + +[monitor-ci] Summary: + - Agent cycles: 1/5 + - Total time: 12m 34s + - Fixes applied: 1 + - Result: SUCCESS +``` + +### Example 2: Pre-CI Failure (medium verbosity) + +``` +[monitor-ci] Starting CI monitor for branch 'feature/add-products' +[monitor-ci] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 2m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Fix available! Applying locally, enhancing, and pushing... +[monitor-ci] Committed: abc1234 + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 6m) +[monitor-ci] Waiting for new CI Attempt... (expected SHA: abc1234) +[monitor-ci] Checking subagent status... (elapsed: 12m) +[monitor-ci] ⚠️ CI Attempt timeout (10 min). Status: no_new_cipe + +[monitor-ci] --auto-fix-workflow enabled. Attempting lockfile update... +[monitor-ci] Lockfile updated. Committed: def5678 + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 16m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] Checking subagent status... (elapsed: 18m) +[monitor-ci] CI: SUCCEEDED + +[monitor-ci] CI passed successfully! + +[monitor-ci] Summary: + - Agent cycles: 3/5 + - Total time: 22m 15s + - Fixes applied: 1 (self-healing) + 1 (lockfile) + - Result: SUCCESS +``` + +### Example 3: Human-in-the-Loop (user pushes during monitoring) + +``` +[monitor-ci] Starting CI monitor for branch 'feature/refactor-api' +[monitor-ci] Config: max-cycles=5, timeout=120m, verbosity=medium + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 4m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Fix available! Applying fix via MCP... (agent cycles: 0/5) +[monitor-ci] Fix applied in CI. Waiting for new CI attempt... + +[monitor-ci] Spawning subagent to poll CI status... +[monitor-ci] Checking subagent status... (elapsed: 8m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Agent-initiated cycle. (agent cycles: 1/5) +[monitor-ci] Fix available! Applying locally and enhancing... +[monitor-ci] Committed: abc1234 + +[monitor-ci] Spawning subagent to poll CI status... + ... (user pushes their own changes to the branch while monitor waits) ... +[monitor-ci] Checking subagent status... (elapsed: 12m) +[monitor-ci] ⚡ New CI Attempt detected! +[monitor-ci] CI: FAILED | Self-healing: IN_PROGRESS + +[monitor-ci] New CI Attempt detected (human-initiated push). Monitoring without incrementing cycle count. (agent cycles: 2/5) +[monitor-ci] Checking subagent status... (elapsed: 16m) +[monitor-ci] CI: FAILED | Self-healing: COMPLETED + +[monitor-ci] Fix available! Applying via MCP... (agent cycles: 2/5) + ... (continues, human cycles don't eat into the budget) ... +``` diff --git a/.github/skills/nx-generate/SKILL.md b/.github/skills/nx-generate/SKILL.md new file mode 100644 index 0000000..af7ba80 --- /dev/null +++ b/.github/skills/nx-generate/SKILL.md @@ -0,0 +1,166 @@ +--- +name: nx-generate +description: Generate code using nx generators. INVOKE IMMEDIATELY when user mentions scaffolding, setup, structure, creating apps/libs, or setting up project structure. Trigger words - scaffold, setup, create a ... app, create a ... lib, project structure, generate, add a new project. ALWAYS use this BEFORE calling nx_docs or exploring - this skill handles discovery internally. +--- + +# Run Nx Generator + +Nx generators are powerful tools that scaffold projects, make automated code migrations or automate repetitive tasks in a monorepo. They ensure consistency across the codebase and reduce boilerplate work. + +This skill applies when the user wants to: + +- Create new projects like libraries or applications +- Scaffold features or boilerplate code +- Run workspace-specific or custom generators +- Do anything else that an nx generator exists for + +## Key Principles + +1. **Always use `--no-interactive`** - Prevents prompts that would hang execution +2. **Read the generator source code** - The schema alone is not enough; understand what the generator actually does +3. **Match existing repo patterns** - Study similar artifacts in the repo and follow their conventions +4. **Verify with lint/test/build/typecheck etc.** - Generated code must pass verification. The listed targets are just an example, use what's appropriate for this workspace. + +## Steps + +### 1. Discover Available Generators + +Use the Nx CLI to discover available generators: + +- List all generators for a plugin: `npx nx list @nx/react` +- View available plugins: `npx nx list` + +This includes plugin generators (e.g., `@nx/react:library`) and local workspace generators. + +### 2. Match Generator to User Request + +Identify which generator(s) could fulfill the user's needs. Consider what artifact type they want, which framework is relevant, and any specific generator names mentioned. + +**IMPORTANT**: When both a local workspace generator and an external plugin generator could satisfy the request, **always prefer the local workspace generator**. Local generators are customized for the specific repo's patterns. + +If no suitable generator exists, you can stop using this skill. However, the burden of proof is high—carefully consider all available generators before deciding none apply. + +### 3. Get Generator Options + +Use the `--help` flag to understand available options: + +```bash +npx nx g @nx/react:library --help +``` + +Pay attention to required options, defaults that might need overriding, and options relevant to the user's request. + +### Library Buildability + +**Default to non-buildable libraries** unless there's a specific reason for buildable. + +| Type | When to use | Generator flags | +| --------------------------- | ----------------------------------------------------------------- | ----------------------------------- | +| **Non-buildable** (default) | Internal monorepo libs consumed by apps | No `--bundler` flag | +| **Buildable** | Publishing to npm, cross-repo sharing, stable libs for cache hits | `--bundler=vite` or `--bundler=swc` | + +Non-buildable libs: + +- Export `.ts`/`.tsx` source directly +- Consumer's bundler compiles them +- Faster dev experience, less config + +Buildable libs: + +- Have their own build target +- Useful for stable libs that rarely change (cache hits) +- Required for npm publishing + +**If unclear, ask the user:** "Should this library be buildable (own build step, better caching) or non-buildable (source consumed directly, simpler setup)?" + +### 4. Read Generator Source Code + +**This step is critical.** The schema alone does not tell you everything. Reading the source code helps you: + +- Know exactly what files will be created/modified and where +- Understand side effects (updating configs, installing deps, etc.) +- Identify behaviors and options not obvious from the schema +- Understand how options interact with each other + +To find generator source code: + +- For plugin generators: Use `node -e "console.log(require.resolve('@nx//generators.json'));"` to find the generators.json, then locate the source from there +- If that fails, read directly from `node_modules//generators.json` +- For local generators: Typically in `tools/generators/` or a local plugin directory. Search the repo for the generator name. + +After reading the source, reconsider: Is this the right generator? If not, go back to step 2. + +> **⚠️ `--directory` flag behavior can be misleading.** +> It should specify the full path of the generated library or component, not the parent path that it will be generated in. +> +> ```bash +> # ✅ Correct - directory is the full path for the library +> nx g @nx/react:library --directory=libs/my-lib +> # generates libs/my-lib/package.json and more +> +> # ❌ Wrong - this will create files at libs and libs/src/... +> nx g @nx/react:library --name=my-lib --directory=libs +> # generates libs/package.json and more +> ``` + +### 5. Examine Existing Patterns + +Before generating, examine the target area of the codebase: + +- Look at similar existing artifacts (other libraries, applications, etc.) +- Identify naming conventions, file structures, and configuration patterns +- Note which test runners, build tools, and linters are used +- Configure the generator to match these patterns + +### 6. Dry-Run to Verify File Placement + +**Always run with `--dry-run` first** to verify files will be created in the correct location: + +```bash +npx nx g @nx/react:library --name=my-lib --dry-run --no-interactive +``` + +Review the output carefully. If files would be created in the wrong location, adjust your options based on what you learned from the generator source code. + +Note: Some generators don't support dry-run (e.g., if they install npm packages). If dry-run fails for this reason, proceed to running the generator for real. + +### 7. Run the Generator + +Execute the generator: + +```bash +nx generate --no-interactive +``` + +> **Tip:** New packages often need workspace dependencies wired up (e.g., importing shared types, being consumed by apps). The `link-workspace-packages` skill can help add these correctly. + +### 8. Modify Generated Code (If Needed) + +Generators provide a starting point. Modify the output as needed to: + +- Add or modify functionality as requested +- Adjust imports, exports, or configurations +- Integrate with existing code patterns + +**Important:** If you replace or delete generated test files (e.g., `*.spec.ts`), either write meaningful replacement tests or remove the `test` target from the project configuration. Empty test suites will cause `nx test` to fail. + +### 9. Format and Verify + +Format all generated/modified files: + +```bash +nx format --fix +``` + +This example is for built-in nx formatting with prettier. There might be other formatting tools for this workspace, use these when appropriate. + +Then verify the generated code works. Keep in mind that the changes you make with a generator or subsequent modifications might impact various projects so it's usually not enough to only run targets for the artifact you just created. + +```bash +# these targets are just an example! +nx run-many -t build,lint,test,typecheck +``` + +These targets are common examples used across many workspaces. You should do research into other targets available for this workspace and its projects. CI configuration is usually a good guide for what the critical targets are that have to pass. + +If verification fails with manageable issues (a few lint errors, minor type issues), fix them. If issues are extensive, attempt obvious fixes first, then escalate to the user with details about what was generated, what's failing, and what you've attempted. diff --git a/.github/skills/nx-plugins/SKILL.md b/.github/skills/nx-plugins/SKILL.md new file mode 100644 index 0000000..89223c7 --- /dev/null +++ b/.github/skills/nx-plugins/SKILL.md @@ -0,0 +1,9 @@ +--- +name: nx-plugins +description: Find and add Nx plugins. USE WHEN user wants to discover available plugins, install a new plugin, or add support for a specific framework or technology to the workspace. +--- + +## Finding and Installing new plugins + +- List plugins: `pnpm nx list` +- Install plugins `pnpm nx add `. Example: `pnpm nx add @nx/react`. diff --git a/.github/skills/nx-run-tasks/SKILL.md b/.github/skills/nx-run-tasks/SKILL.md new file mode 100644 index 0000000..7f1263a --- /dev/null +++ b/.github/skills/nx-run-tasks/SKILL.md @@ -0,0 +1,58 @@ +--- +name: nx-run-tasks +description: Helps with running tasks in an Nx workspace. USE WHEN the user wants to execute build, test, lint, serve, or run any other tasks defined in the workspace. +--- + +You can run tasks with Nx in the following way. + +Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally. Look at the package.json or lockfile to determine which package manager is in use. + +For more details on any command, run it with `--help` (e.g. `nx run-many --help`, `nx affected --help`). + +## Understand which tasks can be run + +You can check those via `nx show project --json`, for example `nx show project myapp --json`. It contains a `targets` section which has information about targets that can be run. You can also just look at the `package.json` scripts or `project.json` targets, but you might miss out on inferred tasks by Nx plugins. + +## Run a single task + +``` +nx run : +``` + +where `project` is the project name defined in `package.json` or `project.json` (if present). + +## Run multiple tasks + +``` +nx run-many -t build test lint typecheck +``` + +You can pass a `-p` flag to filter to specific projects, otherwise it runs on all projects. You can also use `--exclude` to exclude projects, and `--parallel` to control the number of parallel processes (default is 3). + +Examples: + +- `nx run-many -t test -p proj1 proj2` — test specific projects +- `nx run-many -t test --projects=*-app --exclude=excluded-app` — test projects matching a pattern +- `nx run-many -t test --projects=tag:api-*` — test projects by tag + +## Run tasks for affected projects + +Use `nx affected` to only run tasks on projects that have been changed and projects that depend on changed projects. This is especially useful in CI and for large workspaces. + +``` +nx affected -t build test lint +``` + +By default it compares against the base branch. You can customize this: + +- `nx affected -t test --base=main --head=HEAD` — compare against a specific base and head +- `nx affected -t test --files=libs/mylib/src/index.ts` — specify changed files directly + +## Useful flags + +These flags work with `run`, `run-many`, and `affected`: + +- `--skipNxCache` — rerun tasks even when results are cached +- `--verbose` — print additional information such as stack traces +- `--nxBail` — stop execution after the first failed task +- `--configuration=` — use a specific configuration (e.g. `production`) diff --git a/.github/skills/nx-workspace/SKILL.md b/.github/skills/nx-workspace/SKILL.md new file mode 100644 index 0000000..6fd2c57 --- /dev/null +++ b/.github/skills/nx-workspace/SKILL.md @@ -0,0 +1,287 @@ +--- +name: nx-workspace +description: "Explore and understand Nx workspaces. USE WHEN answering questions about the workspace, projects, or tasks. ALSO USE WHEN an nx command fails or you need to check available targets/configuration before running a task. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What depends on library Y?', 'What targets can I run?', 'Cannot find configuration for task', 'debug nx task failure'." +--- + +# Nx Workspace Exploration + +This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies. + +Keep in mind that you might have to prefix commands with `npx`/`pnpx`/`yarn` if nx isn't installed globally. Check the lockfile to determine the package manager in use. + +## Listing Projects + +Use `nx show projects` to list projects in the workspace. + +The project filtering syntax (`-p`/`--projects`) works across many Nx commands including `nx run-many`, `nx release`, `nx show projects`, and more. Filters support explicit names, glob patterns, tag references (e.g. `tag:name`), directories, and negation (e.g. `!project-name`). + +```bash +# List all projects +nx show projects + +# Filter by pattern (glob) +nx show projects --projects "apps/*" +nx show projects --projects "shared-*" + +# Filter by tag +nx show projects --projects "tag:publishable" +nx show projects -p 'tag:publishable,!tag:internal' + +# Filter by target (projects that have a specific target) +nx show projects --withTarget build + +# Combine filters +nx show projects --type lib --withTarget test +nx show projects --affected --exclude="*-e2e" +nx show projects -p "tag:scope:client,packages/*" + +# Negate patterns +nx show projects -p '!tag:private' +nx show projects -p '!*-e2e' + +# Output as JSON +nx show projects --json +``` + +## Project Configuration + +Use `nx show project --json` to get the full resolved configuration for a project. + +**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project --json` command returns the full resolved config including inferred targets from plugins. + +You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options. + +```bash +# Get full project configuration +nx show project my-app --json + +# Extract specific parts from the JSON +nx show project my-app --json | jq '.targets' +nx show project my-app --json | jq '.targets.build' +nx show project my-app --json | jq '.targets | keys' + + +# Check project metadata +nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}' +``` + +## Target Information + +Targets define what tasks can be run on a project. + +```bash +# List all targets for a project +nx show project my-app --json | jq '.targets | keys' + +# Get full target configuration +nx show project my-app --json | jq '.targets.build' + +# Check target executor/command +nx show project my-app --json | jq '.targets.build.executor' +nx show project my-app --json | jq '.targets.build.command' + +# View target options +nx show project my-app --json | jq '.targets.build.options' + +# Check target inputs/outputs (for caching) +nx show project my-app --json | jq '.targets.build.inputs' +nx show project my-app --json | jq '.targets.build.outputs' + +# Find projects with a specific target +nx show projects --withTarget serve +nx show projects --withTarget e2e +``` + +## Workspace Configuration + +Read `nx.json` directly for workspace-level configuration. +You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options. + +```bash +# Read the full nx.json +cat nx.json + +# Or use jq for specific sections +cat nx.json | jq '.targetDefaults' +cat nx.json | jq '.namedInputs' +cat nx.json | jq '.plugins' +cat nx.json | jq '.generators' +``` + +Key nx.json sections: + +- `targetDefaults` - Default configuration applied to all targets of a given name +- `namedInputs` - Reusable input definitions for caching +- `plugins` - Nx plugins and their configuration +- ...and much more, read the schema or nx.json for details + +## Affected Projects + +If the user is asking about affected projects, read the [affected projects reference](references/AFFECTED.md) for detailed commands and examples. + +## Common Exploration Patterns + +### "What's in this workspace?" + +```bash +nx show projects +nx show projects --type app +nx show projects --type lib +``` + +### "How do I build/test/lint project X?" + +```bash +nx show project X --json | jq '.targets | keys' +nx show project X --json | jq '.targets.build' +``` + +### "What depends on library Y?" + +```bash +# Use the project graph to find dependents +nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "Y") | .key' +``` + +## Programmatic Answers + +When processing nx CLI results, use command-line tools to compute the answer programmatically rather than counting or parsing output manually. Always use `--json` flags to get structured output that can be processed with `jq`, `grep`, or other tools you have installed locally. + +### Listing Projects + +```bash +nx show projects --json +``` + +Example output: + +```json +["my-app", "my-app-e2e", "shared-ui", "shared-utils", "api"] +``` + +Common operations: + +```bash +# Count projects +nx show projects --json | jq 'length' + +# Filter by pattern +nx show projects --json | jq '.[] | select(startswith("shared-"))' + +# Get affected projects as array +nx show projects --affected --json | jq '.' +``` + +### Project Details + +```bash +nx show project my-app --json +``` + +Example output: + +```json +{ + "root": "apps/my-app", + "name": "my-app", + "sourceRoot": "apps/my-app/src", + "projectType": "application", + "tags": ["type:app", "scope:client"], + "targets": { + "build": { + "executor": "@nx/vite:build", + "options": { "outputPath": "dist/apps/my-app" } + }, + "serve": { + "executor": "@nx/vite:dev-server", + "options": { "buildTarget": "my-app:build" } + }, + "test": { + "executor": "@nx/vite:test", + "options": {} + } + }, + "implicitDependencies": [] +} +``` + +Common operations: + +```bash +# Get target names +nx show project my-app --json | jq '.targets | keys' + +# Get specific target config +nx show project my-app --json | jq '.targets.build' + +# Get tags +nx show project my-app --json | jq '.tags' + +# Get project root +nx show project my-app --json | jq -r '.root' +``` + +### Project Graph + +```bash +nx graph --print +``` + +Example output: + +```json +{ + "graph": { + "nodes": { + "my-app": { + "name": "my-app", + "type": "app", + "data": { "root": "apps/my-app", "tags": ["type:app"] } + }, + "shared-ui": { + "name": "shared-ui", + "type": "lib", + "data": { "root": "libs/shared-ui", "tags": ["type:ui"] } + } + }, + "dependencies": { + "my-app": [ + { "source": "my-app", "target": "shared-ui", "type": "static" } + ], + "shared-ui": [] + } + } +} +``` + +Common operations: + +```bash +# Get all project names from graph +nx graph --print | jq '.graph.nodes | keys' + +# Find dependencies of a project +nx graph --print | jq '.graph.dependencies["my-app"]' + +# Find projects that depend on a library +nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "shared-ui") | .key' +``` + +## Troubleshooting + +### "Cannot find configuration for task X:target" + +```bash +# Check what targets exist on the project +nx show project X --json | jq '.targets | keys' + +# Check if any projects have that target +nx show projects --withTarget target +``` + +### "The workspace is out of sync" + +```bash +nx sync +nx reset # if sync doesn't fix stale cache +``` diff --git a/.github/skills/nx-workspace/references/AFFECTED.md b/.github/skills/nx-workspace/references/AFFECTED.md new file mode 100644 index 0000000..e30f18f --- /dev/null +++ b/.github/skills/nx-workspace/references/AFFECTED.md @@ -0,0 +1,27 @@ +## Affected Projects + +Find projects affected by changes in the current branch. + +```bash +# Affected since base branch (auto-detected) +nx show projects --affected + +# Affected with explicit base +nx show projects --affected --base=main +nx show projects --affected --base=origin/main + +# Affected between two commits +nx show projects --affected --base=abc123 --head=def456 + +# Affected apps only +nx show projects --affected --type app + +# Affected excluding e2e projects +nx show projects --affected --exclude="*-e2e" + +# Affected by uncommitted changes +nx show projects --affected --uncommitted + +# Affected by untracked files +nx show projects --affected --untracked +``` diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml new file mode 100644 index 0000000..f7de27c --- /dev/null +++ b/.github/workflows/claude.yml @@ -0,0 +1,51 @@ +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + issues: read + id-token: write + actions: read # Required for Claude to read CI results on PRs + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + # This is an optional setting that allows Claude to read CI results on PRs + additional_permissions: | + actions: read + + # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it. + # prompt: 'Update the pull request description to include a summary of changes.' + + # Optional: Add claude_args to customize behavior and configuration + # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md + # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options + # claude_args: '--allowed-tools Bash(gh pr:*)' + claude_args: '--allowedTools Bash(npm:*)' + diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml new file mode 100644 index 0000000..45892ed --- /dev/null +++ b/.github/workflows/deployment.yml @@ -0,0 +1,52 @@ +# Simple workflow for deploying static content to GitHub Pages +name: Deploy static content to Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: ["master"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Single deploy job since we're just deploying + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Npm install + run: npm ci + + - name: Build + run: npm run build:app + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 + with: + # Upload apps dist folder + path: './dist/apps/demo-app' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml new file mode 100644 index 0000000..6c67ae1 --- /dev/null +++ b/.github/workflows/pr-validation.yml @@ -0,0 +1,39 @@ +name: PR Validation + +on: + pull_request: + types: [opened, synchronize, reopened] + branches: + - master + +jobs: + validate: + name: Build and Test + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version-file: '.node-version' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run linting + run: npm run lint + + - name: Run tests + run: npm run test + + - name: Build library + run: npm run build:lib + + - name: Build app + run: npm run build:app \ No newline at end of file diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml new file mode 100644 index 0000000..e58c42e --- /dev/null +++ b/.github/workflows/publish.yaml @@ -0,0 +1,42 @@ +# ./.github/workflows/publish.yml +name: Publish + +on: + release: + types: [published] # Triggers when a GitHub Release is published + +jobs: + publish-npm: + name: Publish + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write # needed for provenance data generation + timeout-minutes: 10 + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - name: Install Node + uses: actions/setup-node@v6 + with: + node-version-file: '.node-version' + registry-url: https://registry.npmjs.org/ + cache: 'npm' + + - name: Install dependencies + run: npm ci + shell: bash + + - name: Print Environment Info + run: npx nx report + shell: bash + + - name: Publish packages + run: npx nx release publish --access public + shell: bash + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + NPM_CONFIG_PROVENANCE: true \ No newline at end of file diff --git a/.github/workflows/validate-commits.yml b/.github/workflows/validate-commits.yml new file mode 100644 index 0000000..2564622 --- /dev/null +++ b/.github/workflows/validate-commits.yml @@ -0,0 +1,60 @@ +name: Validate Commits + +on: + pull_request: + types: [opened, synchronize, reopened, edited] + +jobs: + validate-pr-title: + name: Validate PR Title + runs-on: ubuntu-latest + steps: + - name: Check PR title follows Conventional Commits + uses: amannn/action-semantic-pull-request@v6 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + types: | + feat + fix + docs + style + refactor + perf + test + build + ci + chore + revert + requireScope: false + subjectPattern: ^[A-Za-z].+$ + subjectPatternError: | + The subject "{subject}" found in the PR title "{title}" + didn't match the configured pattern. Please ensure that the subject + starts with an uppercase character. + + validate-commits: + name: Validate Commit Messages + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version-file: '.node-version' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Validate current commit (last commit) + if: github.event.pull_request.commits == 1 + run: npx commitlint --from HEAD~1 --to HEAD --verbose + + - name: Validate all commits in PR + if: github.event.pull_request.commits > 1 + run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose \ No newline at end of file diff --git a/.gitignore b/.gitignore index db8b4c4..ea1c75c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ node_modules/ -lib/ /react-mosaic-component.css* .*.swp react-mosaic.tar.bz2 @@ -8,3 +7,15 @@ yarn-error.log **/.idea/* !**/.idea/*.iml + + + +.nx/cache +.nx/workspace-data +.cursor/rules/nx-rules.mdc +.github/instructions/nx.instructions.md +vite.config.*.timestamp* +vitest.config.*.timestamp* +.parcel-cache +.tsup +/dist \ No newline at end of file diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..2c71f1d --- /dev/null +++ b/.mcp.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "nx-mcp": { + "type": "stdio", + "command": "npx", + "args": ["nx-mcp"] + } + } +} diff --git a/.mocharc.js b/.mocharc.js deleted file mode 100644 index ebdb2c9..0000000 --- a/.mocharc.js +++ /dev/null @@ -1,13 +0,0 @@ -require('jsdom-global/register'); -require('ts-node').register({ - transpileOnly: true, -}); - -const mock = require('mock-require'); -mock('rdndmb-html5-to-touch', {}); -mock('react-dnd', {}); -mock('react-dnd-multi-backend', {}); - -module.exports = { - spec: 'test/*.ts', -}; diff --git a/.node-version b/.node-version new file mode 100644 index 0000000..4555c44 --- /dev/null +++ b/.node-version @@ -0,0 +1 @@ +22.22.1 \ No newline at end of file diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..6d258fb --- /dev/null +++ b/.npmrc @@ -0,0 +1,2 @@ +legacy-peer-deps=true +engine-strict=true \ No newline at end of file diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..fea4413 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,10 @@ +# Add files here to ignore them from prettier formatting +/dist +/coverage +/.nx/cache +/.nx/workspace-data +/.circleci +/.github +/.idea +/.parcel-cache +/.tsup \ No newline at end of file diff --git a/.prettierrc.yml b/.prettierrc.yml index bd874b9..92551e3 100644 --- a/.prettierrc.yml +++ b/.prettierrc.yml @@ -1,5 +1,6 @@ ---- -singleQuote: true -trailingComma: all -arrowParens: always -printWidth: 120 +--- +singleQuote: true +trailingComma: all +printWidth: 80 +semi: true +endOfLine: crlf diff --git a/.verdaccio/config.yml b/.verdaccio/config.yml new file mode 100644 index 0000000..b3520fb --- /dev/null +++ b/.verdaccio/config.yml @@ -0,0 +1,28 @@ +# path to a directory with all packages +storage: ../tmp/local-registry/storage + +# a list of other known repositories we can talk to +uplinks: + npmjs: + url: https://registry.npmjs.org/ + maxage: 60m + +packages: + '**': + # give all users (including non-authenticated users) full access + # because it is a local registry + access: $all + publish: $all + unpublish: $all + + # if package is not available locally, proxy requests to npm registry + proxy: npmjs + +# log settings +log: + type: stdout + format: pretty + level: warn + +publish: + allow_offline: true # set offline to true to allow publish offline diff --git a/.vscode/mcp.json b/.vscode/mcp.json new file mode 100644 index 0000000..e8ffe22 --- /dev/null +++ b/.vscode/mcp.json @@ -0,0 +1,3 @@ +{ + "servers": {} +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..70093a2 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "typescript.tsdk": "node_modules\\typescript\\lib", + "nxConsole.generateAiAgentRules": true +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1bd62dc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ + + + +# General Guidelines for working with Nx + +- For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns for querying projects, targets, and dependencies +- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly +- Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`, `npm exec nx test`) - avoids using globally installed CLI +- You have access to the Nx MCP server and its tools, use them to help the user +- For Nx plugin best practices, check `node_modules/@nx//PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable. +- NEVER guess CLI flags - always check nx_docs or `--help` first when unsure + +## Scaffolding & Generators + +- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the `nx-generate` skill FIRST before exploring or calling MCP tools + +## When to use nx_docs + +- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases +- DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you already know +- The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look up generator syntax + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..93144c5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,218 @@ +# Contributing to React Mosaic + +Thank you for your interest in contributing to React Mosaic! This document provides guidelines and instructions for contributing to the project. + +## Development Setup + +1. **Fork and Clone** + ```bash + git clone https://github.com//react-mosaic.git + cd react-mosaic + ``` + +2. **Install Dependencies** + ```bash + npm install + ``` + + This will automatically set up lefthook Git hooks for commit message validation. + +3. **Start Development Server** + ```bash + npm start + ``` + +## Commit Message Guidelines + +This project uses [Conventional Commits](https://www.conventionalcommits.org/) to automatically generate changelogs and determine version bumps. **All commit messages are validated and must follow this format.** + +### Commit Message Format + +``` +(): + + + +