Jason Woltje
80c3680ccb
Rename the `rails/` directory to `tools/` for agent discoverability — agents frequently failed to locate helper scripts due to the non-intuitive directory name. Add backward-compat symlink `rails/ → tools/`. New tool suites: - Authentik: auth-token, user-list, user-create, group-list, app-list, flow-list, admin-status (8 scripts) - Coolify: team-list, project-list, service-list, service-status, deploy, env-set (7 scripts) - Woodpecker: pipeline-list, pipeline-status, pipeline-trigger (3 stubs) - GLPI: session-init, computer-list, ticket-list, ticket-create, user-list (6 scripts) - Health: stack-health.sh — stack-wide connectivity check Infrastructure: - Shared credential loader at tools/_lib/credentials.sh - install.sh creates symlink + chmod on tool scripts - All ~253 rails/ path references updated across 68+ files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
81 lines
2.6 KiB
Markdown
81 lines
2.6 KiB
Markdown
# Frontend Development Guide
|
|
|
|
## Before Starting
|
|
1. Check assigned issue in git repo: `~/.config/mosaic/tools/git/issue-list.sh -a @me`
|
|
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
|
3. Review existing components and patterns in the codebase
|
|
|
|
## Development Standards
|
|
|
|
### Framework Conventions
|
|
- Follow project's existing framework patterns (React, Vue, Svelte, etc.)
|
|
- Use existing component library/design system if present
|
|
- Maintain consistent file structure with existing code
|
|
|
|
### Styling
|
|
- Use project's established styling approach (CSS modules, Tailwind, styled-components, etc.)
|
|
- Follow existing naming conventions for CSS classes
|
|
- Ensure responsive design unless explicitly single-platform
|
|
|
|
### State Management
|
|
- Use project's existing state management solution
|
|
- Keep component state local when possible
|
|
- Document any new global state additions
|
|
|
|
### Accessibility
|
|
- Include proper ARIA labels
|
|
- Ensure keyboard navigation works
|
|
- Test with screen reader considerations
|
|
- Maintain color contrast ratios (WCAG 2.1 AA minimum)
|
|
|
|
## Testing Requirements (TDD)
|
|
1. Write tests BEFORE implementation
|
|
2. Minimum 85% coverage
|
|
3. Test categories:
|
|
- Unit tests for utility functions
|
|
- Component tests for UI behavior
|
|
- Integration tests for user flows
|
|
|
|
### Test Patterns
|
|
```javascript
|
|
// Component test example structure
|
|
describe('ComponentName', () => {
|
|
it('renders without crashing', () => {});
|
|
it('handles user interaction correctly', () => {});
|
|
it('displays error states appropriately', () => {});
|
|
it('is accessible', () => {});
|
|
});
|
|
```
|
|
|
|
## Code Style
|
|
- Follow Google JavaScript/TypeScript Style Guide
|
|
- **TypeScript: Follow `~/.config/mosaic/guides/TYPESCRIPT.md` — MANDATORY**
|
|
- Use ESLint/Prettier configuration from project
|
|
- Prefer functional components over class components (React)
|
|
- TypeScript strict mode is REQUIRED, not optional
|
|
|
|
### TypeScript Quick Rules (see TYPESCRIPT.md for full guide)
|
|
- **NO `any`** — define explicit types always
|
|
- **NO lazy `unknown`** — only for error catches and external data with validation
|
|
- **Explicit return types** on all exported functions
|
|
- **Explicit parameter types** always
|
|
- **Interface for props** — never inline object types
|
|
- **Event handlers** — use proper React event types
|
|
|
|
## Commit Format
|
|
```
|
|
feat(#123): Add user profile component
|
|
|
|
- Implement avatar display
|
|
- Add edit mode toggle
|
|
- Include form validation
|
|
|
|
Refs #123
|
|
```
|
|
|
|
## Before Completing
|
|
1. Run full test suite
|
|
2. Verify build succeeds
|
|
3. Update scratchpad with completion notes
|
|
4. Reference issue in commit: `Fixes #N` or `Refs #N`
|