diff --git a/config/providers/auth.yaml b/config/providers/auth.yaml new file mode 100644 index 00000000..75e045f9 --- /dev/null +++ b/config/providers/auth.yaml @@ -0,0 +1,186 @@ +# Auth Capability Providers +# Implements the 'auth' capability defined in capabilities.yaml +# +# Auth providers are genuinely interchangeable — a consumer asks for an +# OIDC-compatible auth server and gets one, regardless of whether it's +# Keycloak or Authentik behind the scenes. The consumer only cares about +# the issuer URL, client ID, and client secret. +# +# Credentials are stored in settings at: auth.{provider_id}.{key} +# e.g. auth.keycloak.server_url, auth.authentik.client_secret + +capability: auth + +providers: + # ========================================================================== + # Keycloak - OIDC Identity Provider + # ========================================================================== + - id: keycloak + name: "Keycloak" + description: "Open-source identity and access management (OIDC/SAML)" + mode: local + + docker: + image: quay.io/keycloak/keycloak:26.0 + compose_file: compose/docker-compose.infra.yml + service_name: keycloak + container_name: keycloak + profiles: ["infra"] + ports: + - host: 8081 + container: 8080 + protocol: http + - host: 9000 + container: 9000 + protocol: http + purpose: management + volumes: + - name: keycloak-theme + host_path: ushadow/frontend/keycloak-theme + path: /opt/keycloak/themes/ushadow + read_only: true + - name: keycloak-realm + host_path: config/keycloak + path: /opt/keycloak/data/import + read_only: true + command: ["start-dev", "--import-realm"] + environment: + KC_HOSTNAME_STRICT: "false" + KC_HTTP_ENABLED: "true" + KC_HEALTH_ENABLED: "true" + KC_PROXY_HEADERS: "xforwarded" + JAVA_OPTS_APPEND: "-XX:-UsePerfData -XX:+DisableAttachMechanism" + health: + http_get: /health/ready + port: 9000 + interval: 10s + timeout: 5s + retries: 8 + start_period: 90s + networks: + - ushadow-network + - infra-network + + # Keycloak needs postgres for its own storage + depends_on: + required: + - postgres + + credentials: + server_url: + env_var: KC_URL + label: "Keycloak URL" + default: "http://keycloak:8080" + realm: + env_var: KC_REALM + label: "Realm" + default: "ushadow" + client_id: + env_var: KC_BACKEND_CLIENT_ID + label: "Backend Client ID" + required: true + client_secret: + env_var: KC_CLIENT_SECRET + label: "Client Secret" + type: secret + required: true + + config: + admin_username: + env_var: KC_BOOTSTRAP_ADMIN_USERNAME + label: "Admin Username" + default: "admin" + admin_password: + env_var: KC_BOOTSTRAP_ADMIN_PASSWORD + label: "Admin Password" + type: secret + default: "admin" + frontend_client_id: + env_var: KC_FRONTEND_CLIENT_ID + label: "Frontend Client ID" + hostname_url: + env_var: KC_HOSTNAME_URL + label: "Public Hostname URL" + description: "External URL for Keycloak (if behind reverse proxy)" + mobile_url: + env_var: KC_MOBILE_URL + label: "Mobile Redirect URL" + + ui: + icon: keycloak + tags: ["infrastructure", "auth", "oidc", "saml"] + + # ========================================================================== + # Authentik - OIDC Identity Provider + # ========================================================================== + - id: authentik + name: "Authentik" + description: "Open-source identity provider with modern UI" + mode: local + + docker: + image: ghcr.io/goauthentik/server:2024.12 + compose_file: "" # Defined in per-project infra compose + service_name: authentik-server + container_name: authentik-server + ports: + - host: 9010 + container: 9000 + protocol: http + - host: 9443 + container: 9443 + protocol: https + health: + http_get: /-/health/live/ + port: 9000 + interval: 10s + timeout: 5s + retries: 5 + start_period: 30s + networks: + - ushadow-network + - infra-network + + # Authentik also has a worker sidecar + sidecars: + - name: authentik-worker + image: ghcr.io/goauthentik/server:2024.12 + container_name: authentik-worker + command: worker + + # Authentik needs both postgres and redis + depends_on: + required: + - postgres + - redis + + credentials: + server_url: + env_var: AUTHENTIK_URL + label: "Authentik URL" + default: "http://authentik-server:9000" + realm: + # Authentik uses "applications" instead of realms, but we map to the + # same abstract capability key for consumer compatibility + env_var: AUTHENTIK_APPLICATION + label: "Application Slug" + client_id: + env_var: AUTHENTIK_CLIENT_ID + label: "OAuth2 Client ID" + required: true + client_secret: + env_var: AUTHENTIK_CLIENT_SECRET + label: "OAuth2 Client Secret" + type: secret + required: true + + config: + secret_key: + env_var: AUTHENTIK_SECRET_KEY + label: "Authentik Secret Key" + type: secret + default: "change-me-in-production" + + ui: + icon: authentik + tags: ["infrastructure", "auth", "oidc"] diff --git a/config/providers/transcription.yaml b/config/providers/transcription.yaml index dab2982f..4dbd987e 100644 --- a/config/providers/transcription.yaml +++ b/config/providers/transcription.yaml @@ -28,10 +28,9 @@ providers: env_var: TRANSCRIPTION_LANGUAGE default: "en" model: - env_var: DEEPGRAM_MODEL + env_var: TRANSCRIPTION_MODEL label: "Model" - description: "Deepgram model to use (e.g. nova-2-general, nova-3)" - default: "nova-2-general" + default: "nova-2" ui: icon: deepgram @@ -58,10 +57,9 @@ providers: env_var: TRANSCRIPTION_LANGUAGE default: "en" model: - env_var: MISTRAL_MODEL + env_var: TRANSCRIPTION_MODEL label: "Model" - description: "Mistral transcription model (e.g. voxtral-mini-2507)" - default: "voxtral-mini-2507" + default: "voxtral-mini-latest" ui: icon: mistral diff --git a/docs/code-review/README.md b/docs/code-review/README.md new file mode 100644 index 00000000..54f07608 --- /dev/null +++ b/docs/code-review/README.md @@ -0,0 +1,33 @@ +# Code Review Workflow + +This directory contains templates and examples for implementing an automated code review system that provides comprehensive feedback on code changes. This workflow, inspired by Anthropic's own Claude Code development process and their [claude-code-action](https://github.com/anthropics/claude-code-action) GitHub repository, enables teams to scale code review capacity while maintaining high quality standards through AI-assisted reviews. + +## Concept + +This workflow establishes a comprehensive methodology for automated code reviews in Claude Code, replacing manual line-by-line reviews with intelligent AI agents that handle pattern matching and consistency checks: + +**Core Methodology:** +- **Automated Code Reviews**: Deploy AI reviewers that handle the "blocking and tackling" of code review - syntax, completeness, style guide adherence, and bug detection +- **Dual-Loop Architecture**: Leverage both inner loop (slash commands, subagents) for iterative development and outer loop (GitHub Actions) for automated PR validation +- **Standards-Based Evaluation**: Enforce consistent code quality through pattern matching, fast analysis, and adherence to your team's specific coding standards +- **Human-AI Collaboration**: Free human reviewers to focus on high-level strategic thinking, architectural alignment, and business logic while AI handles routine checks + +**Implementation Features:** +- **Claude Code Subagents**: Deploy specialized code review agents that preserve context and provide detailed analysis without consuming main thread tokens +- **Slash Commands**: Enable instant code reviews with `/review` that automatically analyzes recent commits or specified PRs +- **GitHub Actions Integration**: Fully automated reviewers that run on every PR, providing consistent feedback before human review +- **Customizable Review Criteria**: Tailor review standards to your organization's specific needs, architectural patterns, and coding conventions +- **Learning Opportunities**: Teams learn from AI-generated reviews, improving their understanding of best practices and common pitfalls + +This approach, battle-tested by Anthropic's own engineering team building Claude Code with Claude Code, enables teams to handle the increased volume of AI-generated code while maintaining rigorous quality standards. + +## Resources + +### Templates & Examples +- [Claude Code Review YAML](./claude-code-review.yml) - Standard GitHub Action configuration for automated code reviews +- [Custom Code Review YAML](./claude-code-review-custom.yml) - Extended configuration with custom review criteria +- [Pragmatic Code Review Slash Command](./pragmatic-code-review-slash-command.md) - Custom slash command for on-demand pragmatic code reviews +- [Pragmatic Code Review Subagent](./pragmatic-code-review-subagent.md) - Subagent configuration for comprehensive code analysis + +### Video Tutorial +For a detailed walkthrough of this workflow, watch the [comprehensive tutorial on YouTube](https://www.youtube.com/watch?v=nItsfXwujjg). diff --git a/docs/code-review/pragmatic-code-review-slash-command.md b/docs/code-review/pragmatic-code-review-slash-command.md new file mode 100644 index 00000000..2b6e6c0d --- /dev/null +++ b/docs/code-review/pragmatic-code-review-slash-command.md @@ -0,0 +1,42 @@ +--- +allowed-tools: Grep, LS, Read, Edit, MultiEdit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__playwright__browser_close, mcp__playwright__browser_resize, mcp__playwright__browser_console_messages, mcp__playwright__browser_handle_dialog, mcp__playwright__browser_evaluate, mcp__playwright__browser_file_upload, mcp__playwright__browser_install, mcp__playwright__browser_press_key, mcp__playwright__browser_type, mcp__playwright__browser_navigate, mcp__playwright__browser_navigate_back, mcp__playwright__browser_navigate_forward, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_drag, mcp__playwright__browser_hover, mcp__playwright__browser_select_option, mcp__playwright__browser_tab_list, mcp__playwright__browser_tab_new, mcp__playwright__browser_tab_select, mcp__playwright__browser_tab_close, mcp__playwright__browser_wait_for, Bash, Glob +description: Conduct a comprehensive code review of the pending changes on the current branch based on the Pragmatic Quality framework. +--- + +You are acting as the Principal Engineer AI Reviewer for a high-velocity, lean startup. Your mandate is to enforce the "Pragmatic Quality" framework: balance rigorous engineering standards with development speed to ensure the codebase scales effectively. + +Analyze the following outputs to understand the scope and content of the changes you must review. + +GIT STATUS: + +``` +!`git status` +``` + +FILES MODIFIED: + +``` +!`git diff --name-only origin/HEAD...` +``` + +COMMITS: + +``` +!`git log --no-decorate origin/HEAD...` +``` + +DIFF CONTENT: + +``` +!`git diff --merge-base origin/HEAD` +``` + +Review the complete diff above. This contains all code changes in the PR. + + +OBJECTIVE: +Use the pragmatic-code-review agent to comprehensively review the complete diff above, and reply back to the user with the completed code review report. Your final reply must contain the markdown report and nothing else. + + +OUTPUT GUIDELINES: +Provide specific, actionable feedback. When suggesting changes, explain the underlying engineering principle that motivates the suggestion. Be constructive and concise. diff --git a/docs/code-review/pragmatic-code-review-subagent.md b/docs/code-review/pragmatic-code-review-subagent.md new file mode 100644 index 00000000..33458733 --- /dev/null +++ b/docs/code-review/pragmatic-code-review-subagent.md @@ -0,0 +1,99 @@ +--- +name: pragmatic-code-review +description: Use this agent when you need a thorough code review that balances engineering excellence with development velocity. This agent should be invoked after completing a logical chunk of code, implementing a feature, or before merging a pull request. The agent focuses on substantive issues but also addresses style.\n\nExamples:\n- \n Context: After implementing a new API endpoint\n user: "I've added a new user authentication endpoint"\n assistant: "I'll review the authentication endpoint implementation using the pragmatic-code-review agent"\n \n Since new code has been written that involves security-critical functionality, use the pragmatic-code-review agent to ensure it meets quality standards.\n \n\n- \n Context: After refactoring a complex service\n user: "I've refactored the payment processing service to improve performance"\n assistant: "Let me review these refactoring changes with the pragmatic-code-review agent"\n \n Performance-critical refactoring needs review to ensure improvements don't introduce regressions.\n \n\n- \n Context: Before merging a feature branch\n user: "The new dashboard feature is complete and ready for review"\n assistant: "I'll conduct a comprehensive review using the pragmatic-code-review agent before we merge"\n \n Complete features need thorough review before merging to main branch.\n \n +tools: Bash, Glob, Grep, Read, Edit, MultiEdit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, ListMcpResourcesTool, ReadMcpResourceTool, mcp__playwright__browser_close, mcp__playwright__browser_resize, mcp__playwright__browser_console_messages, mcp__playwright__browser_handle_dialog, mcp__playwright__browser_evaluate, mcp__playwright__browser_file_upload, mcp__playwright__browser_fill_form, mcp__playwright__browser_install, mcp__playwright__browser_press_key, mcp__playwright__browser_type, mcp__playwright__browser_navigate, mcp__playwright__browser_navigate_back, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_drag, mcp__playwright__browser_hover, mcp__playwright__browser_select_option, mcp__playwright__browser_tabs, mcp__playwright__browser_wait_for +model: opus +color: red +--- + +You are the Principal Engineer Reviewer for a high-velocity, lean startup. Your mandate is to enforce the 'Pragmatic Quality' framework: balance rigorous engineering standards with development speed to ensure the codebase scales effectively. + +## Review Philosophy & Directives + +1. **Net Positive > Perfection:** Your primary objective is to determine if the change definitively improves the overall code health. Do not block on imperfections if the change is a net improvement. + +2. **Focus on Substance:** Focus your analysis on architecture, design, business logic, security, and complex interactions. + +3. **Grounded in Principles:** Base feedback on established engineering principles (e.g., SOLID, DRY, KISS, YAGNI) and technical facts, not opinions. + +4. **Signal Intent:** Prefix minor, optional polish suggestions with '**Nit:**'. + +## Hierarchical Review Framework + +You will analyze code changes using this prioritized checklist: + +### 1. Architectural Design & Integrity (Critical) +- Evaluate if the design aligns with existing architectural patterns and system boundaries +- Assess modularity and adherence to Single Responsibility Principle +- Identify unnecessary complexity - could a simpler solution achieve the same goal? +- Verify the change is atomic (single, cohesive purpose) not bundling unrelated changes +- Check for appropriate abstraction levels and separation of concerns + +### 2. Functionality & Correctness (Critical) +- Verify the code correctly implements the intended business logic +- Identify handling of edge cases, error conditions, and unexpected inputs +- Detect potential logical flaws, race conditions, or concurrency issues +- Validate state management and data flow correctness +- Ensure idempotency where appropriate + +### 3. Security (Non-Negotiable) +- Verify all user input is validated, sanitized, and escaped (XSS, SQLi, command injection prevention) +- Confirm authentication and authorization checks on all protected resources +- Check for hardcoded secrets, API keys, or credentials +- Assess data exposure in logs, error messages, or API responses +- Validate CORS, CSP, and other security headers where applicable +- Review cryptographic implementations for standard library usage + +### 4. Maintainability & Readability (High Priority) +- Assess code clarity for future developers +- Evaluate naming conventions for descriptiveness and consistency +- Analyze control flow complexity and nesting depth +- Verify comments explain 'why' (intent/trade-offs) not 'what' (mechanics) +- Check for appropriate error messages that aid debugging +- Identify code duplication that should be refactored + +### 5. Testing Strategy & Robustness (High Priority) +- Evaluate test coverage relative to code complexity and criticality +- Verify tests cover failure modes, security edge cases, and error paths +- Assess test maintainability and clarity +- Check for appropriate test isolation and mock usage +- Identify missing integration or end-to-end tests for critical paths + +### 6. Performance & Scalability (Important) +- **Backend:** Identify N+1 queries, missing indexes, inefficient algorithms +- **Frontend:** Assess bundle size impact, rendering performance, Core Web Vitals +- **API Design:** Evaluate consistency, backwards compatibility, pagination strategy +- Review caching strategies and cache invalidation logic +- Identify potential memory leaks or resource exhaustion + +### 7. Dependencies & Documentation (Important) +- Question necessity of new third-party dependencies +- Assess dependency security, maintenance status, and license compatibility +- Verify API documentation updates for contract changes +- Check for updated configuration or deployment documentation + +## Communication Principles & Output Guidelines + +1. **Actionable Feedback**: Provide specific, actionable suggestions. +2. **Explain the "Why"**: When suggesting changes, explain the underlying engineering principle that motivates the suggestion. +3. **Triage Matrix**: Categorize significant issues to help the author prioritize: + - **[Critical/Blocker]**: Must be fixed before merge (e.g., security vulnerability, architectural regression). + - **[Improvement]**: Strong recommendation for improving the implementation. + - **[Nit]**: Minor polish, optional. +4. **Be Constructive**: Maintain objectivity and assume good intent. + +**Your Report Structure (Example):** +```markdown +### Code Review Summary +[Overall assessment and high-level observations] + +### Findings + +#### Critical Issues +- [File/Line]: [Description of the issue and why it's critical, grounded in engineering principles] + +#### Suggested Improvements +- [File/Line]: [Suggestion and rationale] + +#### Nitpicks +- Nit: [File/Line]: [Minor detail] diff --git a/docs/design-review/design-principles-example.md b/docs/design-review/design-principles-example.md new file mode 100644 index 00000000..c97bb8ae --- /dev/null +++ b/docs/design-review/design-principles-example.md @@ -0,0 +1,129 @@ +# S-Tier SaaS Dashboard Design Checklist (Inspired by Stripe, Airbnb, Linear) + +## I. Core Design Philosophy & Strategy + +* [ ] **Users First:** Prioritize user needs, workflows, and ease of use in every design decision. +* [ ] **Meticulous Craft:** Aim for precision, polish, and high quality in every UI element and interaction. +* [ ] **Speed & Performance:** Design for fast load times and snappy, responsive interactions. +* [ ] **Simplicity & Clarity:** Strive for a clean, uncluttered interface. Ensure labels, instructions, and information are unambiguous. +* [ ] **Focus & Efficiency:** Help users achieve their goals quickly and with minimal friction. Minimize unnecessary steps or distractions. +* [ ] **Consistency:** Maintain a uniform design language (colors, typography, components, patterns) across the entire dashboard. +* [ ] **Accessibility (WCAG AA+):** Design for inclusivity. Ensure sufficient color contrast, keyboard navigability, and screen reader compatibility. +* [ ] **Opinionated Design (Thoughtful Defaults):** Establish clear, efficient default workflows and settings, reducing decision fatigue for users. + +## II. Design System Foundation (Tokens & Core Components) + +* [ ] **Define a Color Palette:** + * [ ] **Primary Brand Color:** User-specified, used strategically. + * [ ] **Neutrals:** A scale of grays (5-7 steps) for text, backgrounds, borders. + * [ ] **Semantic Colors:** Define specific colors for Success (green), Error/Destructive (red), Warning (yellow/amber), Informational (blue). + * [ ] **Dark Mode Palette:** Create a corresponding accessible dark mode palette. + * [ ] **Accessibility Check:** Ensure all color combinations meet WCAG AA contrast ratios. +* [ ] **Establish a Typographic Scale:** + * [ ] **Primary Font Family:** Choose a clean, legible sans-serif font (e.g., Inter, Manrope, system-ui). + * [ ] **Modular Scale:** Define distinct sizes for H1, H2, H3, H4, Body Large, Body Medium (Default), Body Small/Caption. (e.g., H1: 32px, Body: 14px/16px). + * [ ] **Font Weights:** Utilize a limited set of weights (e.g., Regular, Medium, SemiBold, Bold). + * [ ] **Line Height:** Ensure generous line height for readability (e.g., 1.5-1.7 for body text). +* [ ] **Define Spacing Units:** + * [ ] **Base Unit:** Establish a base unit (e.g., 8px). + * [ ] **Spacing Scale:** Use multiples of the base unit for all padding, margins, and layout spacing (e.g., 4px, 8px, 12px, 16px, 24px, 32px). +* [ ] **Define Border Radii:** + * [ ] **Consistent Values:** Use a small set of consistent border radii (e.g., Small: 4-6px for inputs/buttons; Medium: 8-12px for cards/modals). +* [ ] **Develop Core UI Components (with consistent states: default, hover, active, focus, disabled):** + * [ ] Buttons (primary, secondary, tertiary/ghost, destructive, link-style; with icon options) + * [ ] Input Fields (text, textarea, select, date picker; with clear labels, placeholders, helper text, error messages) + * [ ] Checkboxes & Radio Buttons + * [ ] Toggles/Switches + * [ ] Cards (for content blocks, multimedia items, dashboard widgets) + * [ ] Tables (for data display; with clear headers, rows, cells; support for sorting, filtering) + * [ ] Modals/Dialogs (for confirmations, forms, detailed views) + * [ ] Navigation Elements (Sidebar, Tabs) + * [ ] Badges/Tags (for status indicators, categorization) + * [ ] Tooltips (for contextual help) + * [ ] Progress Indicators (Spinners, Progress Bars) + * [ ] Icons (use a single, modern, clean icon set; SVG preferred) + * [ ] Avatars + +## III. Layout, Visual Hierarchy & Structure + +* [ ] **Responsive Grid System:** Design based on a responsive grid (e.g., 12-column) for consistent layout across devices. +* [ ] **Strategic White Space:** Use ample negative space to improve clarity, reduce cognitive load, and create visual balance. +* [ ] **Clear Visual Hierarchy:** Guide the user's eye using typography (size, weight, color), spacing, and element positioning. +* [ ] **Consistent Alignment:** Maintain consistent alignment of elements. +* [ ] **Main Dashboard Layout:** + * [ ] Persistent Left Sidebar: For primary navigation between modules. + * [ ] Content Area: Main space for module-specific interfaces. + * [ ] (Optional) Top Bar: For global search, user profile, notifications. +* [ ] **Mobile-First Considerations:** Ensure the design adapts gracefully to smaller screens. + +## IV. Interaction Design & Animations + +* [ ] **Purposeful Micro-interactions:** Use subtle animations and visual feedback for user actions (hovers, clicks, form submissions, status changes). + * [ ] Feedback should be immediate and clear. + * [ ] Animations should be quick (150-300ms) and use appropriate easing (e.g., ease-in-out). +* [ ] **Loading States:** Implement clear loading indicators (skeleton screens for page loads, spinners for in-component actions). +* [ ] **Transitions:** Use smooth transitions for state changes, modal appearances, and section expansions. +* [ ] **Avoid Distraction:** Animations should enhance usability, not overwhelm or slow down the user. +* [ ] **Keyboard Navigation:** Ensure all interactive elements are keyboard accessible and focus states are clear. + +## V. Specific Module Design Tactics + +### A. Multimedia Moderation Module + +* [ ] **Clear Media Display:** Prominent image/video previews (grid or list view). +* [ ] **Obvious Moderation Actions:** Clearly labeled buttons (Approve, Reject, Flag, etc.) with distinct styling (e.g., primary/secondary, color-coding). Use icons for quick recognition. +* [ ] **Visible Status Indicators:** Use color-coded Badges for content status (Pending, Approved, Rejected). +* [ ] **Contextual Information:** Display relevant metadata (uploader, timestamp, flags) alongside media. +* [ ] **Workflow Efficiency:** + * [ ] Bulk Actions: Allow selection and moderation of multiple items. + * [ ] Keyboard Shortcuts: For common moderation actions. +* [ ] **Minimize Fatigue:** Clean, uncluttered interface; consider dark mode option. + +### B. Data Tables Module (Contacts, Admin Settings) + +* [ ] **Readability & Scannability:** + * [ ] Smart Alignment: Left-align text, right-align numbers. + * [ ] Clear Headers: Bold column headers. + * [ ] Zebra Striping (Optional): For dense tables. + * [ ] Legible Typography: Simple, clean sans-serif fonts. + * [ ] Adequate Row Height & Spacing. +* [ ] **Interactive Controls:** + * [ ] Column Sorting: Clickable headers with sort indicators. + * [ ] Intuitive Filtering: Accessible filter controls (dropdowns, text inputs) above the table. + * [ ] Global Table Search. +* [ ] **Large Datasets:** + * [ ] Pagination (preferred for admin tables) or virtual/infinite scroll. + * [ ] Sticky Headers / Frozen Columns: If applicable. +* [ ] **Row Interactions:** + * [ ] Expandable Rows: For detailed information. + * [ ] Inline Editing: For quick modifications. + * [ ] Bulk Actions: Checkboxes and contextual toolbar. + * [ ] Action Icons/Buttons per Row: (Edit, Delete, View Details) clearly distinguishable. + +### C. Configuration Panels Module (Microsite, Admin Settings) + +* [ ] **Clarity & Simplicity:** Clear, unambiguous labels for all settings. Concise helper text or tooltips for descriptions. Avoid jargon. +* [ ] **Logical Grouping:** Group related settings into sections or tabs. +* [ ] **Progressive Disclosure:** Hide advanced or less-used settings by default (e.g., behind "Advanced Settings" toggle, accordions). +* [ ] **Appropriate Input Types:** Use correct form controls (text fields, checkboxes, toggles, selects, sliders) for each setting. +* [ ] **Visual Feedback:** Immediate confirmation of changes saved (e.g., toast notifications, inline messages). Clear error messages for invalid inputs. +* [ ] **Sensible Defaults:** Provide default values for all settings. +* [ ] **Reset Option:** Easy way to "Reset to Defaults" for sections or entire configuration. +* [ ] **Microsite Preview (If Applicable):** Show a live or near-live preview of microsite changes. + +## VI. CSS & Styling Architecture + +* [ ] **Choose a Scalable CSS Methodology:** + * [ ] **Utility-First (Recommended for LLM):** e.g., Tailwind CSS. Define design tokens in config, apply via utility classes. + * [ ] **BEM with Sass:** If not utility-first, use structured BEM naming with Sass variables for tokens. + * [ ] **CSS-in-JS (Scoped Styles):** e.g., Stripe's approach for Elements. +* [ ] **Integrate Design Tokens:** Ensure colors, fonts, spacing, radii tokens are directly usable in the chosen CSS architecture. +* [ ] **Maintainability & Readability:** Code should be well-organized and easy to understand. +* [ ] **Performance:** Optimize CSS delivery; avoid unnecessary bloat. + +## VII. General Best Practices + +* [ ] **Iterative Design & Testing:** Continuously test with users and iterate on designs. +* [ ] **Clear Information Architecture:** Organize content and navigation logically. +* [ ] **Responsive Design:** Ensure the dashboard is fully functional and looks great on all device sizes (desktop, tablet, mobile). +* [ ] **Documentation:** Maintain clear documentation for the design system and components. diff --git a/docs/design-review/design-review-agent.md b/docs/design-review/design-review-agent.md new file mode 100644 index 00000000..0275c07a --- /dev/null +++ b/docs/design-review/design-review-agent.md @@ -0,0 +1,107 @@ +--- +name: design-review +description: Use this agent when you need to conduct a comprehensive design review on front-end pull requests or general UI changes. This agent should be triggered when a PR modifying UI components, styles, or user-facing features needs review; you want to verify visual consistency, accessibility compliance, and user experience quality; you need to test responsive design across different viewports; or you want to ensure that new UI changes meet world-class design standards. The agent requires access to a live preview environment and uses Playwright for automated interaction testing. Example - "Review the design changes in PR 234" +tools: Grep, LS, Read, Edit, MultiEdit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__playwright__browser_close, mcp__playwright__browser_resize, mcp__playwright__browser_console_messages, mcp__playwright__browser_handle_dialog, mcp__playwright__browser_evaluate, mcp__playwright__browser_file_upload, mcp__playwright__browser_install, mcp__playwright__browser_press_key, mcp__playwright__browser_type, mcp__playwright__browser_navigate, mcp__playwright__browser_navigate_back, mcp__playwright__browser_navigate_forward, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_drag, mcp__playwright__browser_hover, mcp__playwright__browser_select_option, mcp__playwright__browser_tab_list, mcp__playwright__browser_tab_new, mcp__playwright__browser_tab_select, mcp__playwright__browser_tab_close, mcp__playwright__browser_wait_for, Bash, Glob +model: sonnet +color: pink +--- + +You are an elite design review specialist with deep expertise in user experience, visual design, accessibility, and front-end implementation. You conduct world-class design reviews following the rigorous standards of top Silicon Valley companies like Stripe, Airbnb, and Linear. + +**Your Core Methodology:** +You strictly adhere to the "Live Environment First" principle - always assessing the interactive experience before diving into static analysis or code. You prioritize the actual user experience over theoretical perfection. + +**Your Review Process:** + +You will systematically execute a comprehensive design review following these phases: + +## Phase 0: Preparation +- Analyze the PR description to understand motivation, changes, and testing notes (or just the description of the work to review in the user's message if no PR supplied) +- Review the code diff to understand implementation scope +- Set up the live preview environment using Playwright +- Configure initial viewport (1440x900 for desktop) + +## Phase 1: Interaction and User Flow +- Execute the primary user flow following testing notes +- Test all interactive states (hover, active, disabled) +- Verify destructive action confirmations +- Assess perceived performance and responsiveness + +## Phase 2: Responsiveness Testing +- Test desktop viewport (1440px) - capture screenshot +- Test tablet viewport (768px) - verify layout adaptation +- Test mobile viewport (375px) - ensure touch optimization +- Verify no horizontal scrolling or element overlap + +## Phase 3: Visual Polish +- Assess layout alignment and spacing consistency +- Verify typography hierarchy and legibility +- Check color palette consistency and image quality +- Ensure visual hierarchy guides user attention + +## Phase 4: Accessibility (WCAG 2.1 AA) +- Test complete keyboard navigation (Tab order) +- Verify visible focus states on all interactive elements +- Confirm keyboard operability (Enter/Space activation) +- Validate semantic HTML usage +- Check form labels and associations +- Verify image alt text +- Test color contrast ratios (4.5:1 minimum) + +## Phase 5: Robustness Testing +- Test form validation with invalid inputs +- Stress test with content overflow scenarios +- Verify loading, empty, and error states +- Check edge case handling + +## Phase 6: Code Health +- Verify component reuse over duplication +- Check for design token usage (no magic numbers) +- Ensure adherence to established patterns + +## Phase 7: Content and Console +- Review grammar and clarity of all text +- Check browser console for errors/warnings + +**Your Communication Principles:** + +1. **Problems Over Prescriptions**: You describe problems and their impact, not technical solutions. Example: Instead of "Change margin to 16px", say "The spacing feels inconsistent with adjacent elements, creating visual clutter." + +2. **Triage Matrix**: You categorize every issue: + - **[Blocker]**: Critical failures requiring immediate fix + - **[High-Priority]**: Significant issues to fix before merge + - **[Medium-Priority]**: Improvements for follow-up + - **[Nitpick]**: Minor aesthetic details (prefix with "Nit:") + +3. **Evidence-Based Feedback**: You provide screenshots for visual issues and always start with positive acknowledgment of what works well. + +**Your Report Structure:** +```markdown +### Design Review Summary +[Positive opening and overall assessment] + +### Findings + +#### Blockers +- [Problem + Screenshot] + +#### High-Priority +- [Problem + Screenshot] + +#### Medium-Priority / Suggestions +- [Problem] + +#### Nitpicks +- Nit: [Problem] +``` + +**Technical Requirements:** +You utilize the Playwright MCP toolset for automated testing: +- `mcp__playwright__browser_navigate` for navigation +- `mcp__playwright__browser_click/type/select_option` for interactions +- `mcp__playwright__browser_take_screenshot` for visual evidence +- `mcp__playwright__browser_resize` for viewport testing +- `mcp__playwright__browser_snapshot` for DOM analysis +- `mcp__playwright__browser_console_messages` for error checking + +You maintain objectivity while being constructive, always assuming good intent from the implementer. Your goal is to ensure the highest quality user experience while balancing perfectionism with practical delivery timelines. diff --git a/docs/design-review/design-review-claude-md-snippet.md b/docs/design-review/design-review-claude-md-snippet.md new file mode 100644 index 00000000..de43d9e7 --- /dev/null +++ b/docs/design-review/design-review-claude-md-snippet.md @@ -0,0 +1,24 @@ +## Visual Development + +### Design Principles +- Comprehensive design checklist in `/context/design-principles.md` +- Brand style guide in `/context/style-guide.md` +- When making visual (front-end, UI/UX) changes, always refer to these files for guidance + +### Quick Visual Check +IMMEDIATELY after implementing any front-end change: +1. **Identify what changed** - Review the modified components/pages +2. **Navigate to affected pages** - Use `mcp__playwright__browser_navigate` to visit each changed view +3. **Verify design compliance** - Compare against `/context/design-principles.md` and `/context/style-guide.md` +4. **Validate feature implementation** - Ensure the change fulfills the user's specific request +5. **Check acceptance criteria** - Review any provided context files or requirements +6. **Capture evidence** - Take full page screenshot at desktop viewport (1440px) of each changed view +7. **Check for errors** - Run `mcp__playwright__browser_console_messages` + +This verification ensures changes meet design standards and user requirements. + +### Comprehensive Design Review +Invoke the `@agent-design-review` subagent for thorough design validation when: +- Completing significant UI/UX features +- Before finalizing PRs with visual changes +- Needing comprehensive accessibility and responsiveness testing diff --git a/docs/design-review/design-review-slash-command.md b/docs/design-review/design-review-slash-command.md new file mode 100644 index 00000000..55c304ff --- /dev/null +++ b/docs/design-review/design-review-slash-command.md @@ -0,0 +1,38 @@ +--- +allowed-tools: Grep, LS, Read, Edit, MultiEdit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__playwright__browser_close, mcp__playwright__browser_resize, mcp__playwright__browser_console_messages, mcp__playwright__browser_handle_dialog, mcp__playwright__browser_evaluate, mcp__playwright__browser_file_upload, mcp__playwright__browser_install, mcp__playwright__browser_press_key, mcp__playwright__browser_type, mcp__playwright__browser_navigate, mcp__playwright__browser_navigate_back, mcp__playwright__browser_navigate_forward, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_drag, mcp__playwright__browser_hover, mcp__playwright__browser_select_option, mcp__playwright__browser_tab_list, mcp__playwright__browser_tab_new, mcp__playwright__browser_tab_select, mcp__playwright__browser_tab_close, mcp__playwright__browser_wait_for, Bash, Glob +description: Complete a design review of the pending changes on the current branch +--- + +You are an elite design review specialist with deep expertise in user experience, visual design, accessibility, and front-end implementation. You conduct world-class design reviews following the rigorous standards of top Silicon Valley companies like Stripe, Airbnb, and Linear. + +GIT STATUS: + +``` +!`git status` +``` + +FILES MODIFIED: + +``` +!`git diff --name-only origin/HEAD...` +``` + +COMMITS: + +``` +!`git log --no-decorate origin/HEAD...` +``` + +DIFF CONTENT: + +``` +!`git diff --merge-base origin/HEAD` +``` + +Review the complete diff above. This contains all code changes in the PR. + + +OBJECTIVE: +Use the design-review agent to comprehensively review the complete diff above, and reply back to the user with the design and review of the report. Your final reply must contain the markdown report and nothing else. + +Follow and implement the design principles and style guide located in the ../context/design-principles.md and ../context/style-guide.md docs. diff --git a/docs/design-review/install.sh b/docs/design-review/install.sh new file mode 100644 index 00000000..f8fca963 --- /dev/null +++ b/docs/design-review/install.sh @@ -0,0 +1,31 @@ +# Design Review Workflow + +This directory contains templates and examples for implementing an automated design review system that provides feedback on front-end code changes with design implications. This workflow allows engineers to automatically run design reviews on pull requests or working changes, ensuring design consistency and quality throughout the development process. + +## Concept + +This workflow establishes a comprehensive methodology for automated design reviews in Claude Code, leveraging multiple advanced features to ensure world-class UI/UX standards in your codebase: + +**Core Methodology:** +- **Automated Design Reviews**: Trigger comprehensive design assessments either automatically on PRs or on-demand via slash commands +- **Live Environment Testing**: Uses [Playwright MCP](https://github.com/microsoft/playwright-mcp) server integration to interact with and test actual UI components in real-time, not just static code analysis +- **Standards-Based Evaluation**: Follows rigorous design principles inspired by top-tier companies (Stripe, Airbnb, Linear), covering visual hierarchy, accessibility (WCAG AA+), responsive design, and interaction patterns + +**Implementation Features:** +- **Claude Code Subagents**: Deploy specialized design review agents with pre-configured tools and prompts for consistent, thorough reviews, by taging `@agent-code-reviewer` +- **Slash Commands**: Enable instant design reviews with `/design-review` that automatically analyzes git diffs and provides structured feedback +- **CLAUDE.md Memory Integration**: Store design principles and brand guidelines in your project's CLAUDE.md file, ensuring Claude Code always references your specific design system +- **Multi-Phase Review Process**: Systematic evaluation covering interaction flows, responsiveness, visual polish, accessibility, robustness testing, and code health + +This approach transforms design reviews from manual, subjective processes into automated, objective assessments that maintain consistency across your entire frontend development workflow. + +## Resources + +### Templates & Examples +- [Design Principles Example](./design-principles-example.md) - Sample design principles document for guiding automated reviews +- [Design Review Agent](./design-review-agent.md) - Agent configuration for automated design reviews +- [Claude.md Snippet](./design-review-claude-md-snippet.md) - Claude.md configuration snippet for design review integration +- [Slash Command](./design-review-slash-command.md) - Custom slash command implementation for on-demand design reviews + +### Video Tutorial +For a detailed walkthrough of this workflow, watch the comprehensive tutorial on YouTube: [Patrick Ellis' Channel](https://www.youtube.com/watch?v=xOO8Wt_i72s) diff --git a/docs/integrations/openmemory.md b/docs/integrations/openmemory.md new file mode 100644 index 00000000..228a8f86 --- /dev/null +++ b/docs/integrations/openmemory.md @@ -0,0 +1,250 @@ +# OpenMemory Integration Guide + +OpenMemory is an advanced semantic memory service based on [mem0.ai](https://mem0.ai/) that provides: +- **Semantic search** - Find memories by meaning, not just keywords +- **Knowledge graphs** - Connect related memories using Neo4j +- **Context-aware retrieval** - Get relevant memories based on conversation context +- **Multi-user support** - Isolated memory spaces per user + +## Prerequisites + +1. **OpenMemory service running** (typically on port 8765) + - If using Chronicle's OpenMemory: `docker compose -f compose/openmemory.yml up -d` + - If self-hosted: Follow [mem0 deployment guide](https://docs.mem0.ai/) + +2. **Required infrastructure** (if using knowledge graphs): + - Neo4j (for graph relationships) + - Qdrant (for vector embeddings) + - OpenAI API key (for embeddings and LLM) + +## Quick Setup + +### 1. Enable OpenMemory + +Create or edit `config/config.local.yaml`: + +```yaml +services: + openmemory: + enabled: true + url: "http://localhost:8765" # or "http://mem0:8765" in Docker + user_id: "ushadow" + sync_interval: 1800 # Sync every 30 minutes (optional) +``` + +### 2. Test the Connection + +Start Ushadow backend and test the OpenMemory connection: + +```bash +# Via curl +curl http://localhost:8010/api/services/openmemory/test + +# Or use the UI +# Navigate to http://localhost:3000/services +# Click "Test" on the OpenMemory card +``` + +### 3. Preview Data + +See what memories will be synced before actually syncing: + +```bash +curl http://localhost:8010/api/services/openmemory/preview?limit=5 +``` + +### 4. Sync Memories + +Manually trigger a sync: + +```bash +curl -X POST http://localhost:8010/api/services/openmemory/sync?limit=100 +``` + +## Configuration Options + +### Basic Configuration + +```yaml +services: + openmemory: + enabled: true + url: "http://localhost:8765" + user_id: "your-user-id" # Unique identifier for memory isolation + sync_interval: 1800 # Seconds between auto-syncs +``` + +### Advanced Configuration + +Edit `config/services.yaml` to customize field mappings: + +```yaml +- service_id: openmemory + # ... (existing config) + + memory_mapping: + field_mappings: + # Customize how OpenMemory data maps to Ushadow memories + - source_field: "memory" + target_field: "content" + + - source_field: "metadata.category" + target_field: "tags" + transform: "split" + + # Add custom mappings + - source_field: "metadata.priority" + target_field: "metadata.priority" + + include_unmapped: true # Preserve all other fields in metadata +``` + +## API Endpoints + +OpenMemory exposes the following mem0 API endpoints: + +- `GET /v1/memories/?user_id={user_id}` - List all memories +- `POST /v1/memories/` - Create a new memory +- `GET /v1/memories/{id}/` - Get specific memory +- `PUT /v1/memories/{id}/` - Update memory +- `DELETE /v1/memories/{id}/` - Delete memory +- `POST /v1/memories/search/` - Semantic search + +## Usage Examples + +### Create Memory via OpenMemory + +```bash +curl -X POST http://localhost:8765/v1/memories/ \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + {"role": "user", "content": "I prefer Python over JavaScript"} + ], + "user_id": "ushadow" + }' +``` + +### Search Memories + +```bash +curl -X POST http://localhost:8765/v1/memories/search/ \ + -H "Content-Type: application/json" \ + -d '{ + "query": "programming languages", + "user_id": "ushadow" + }' +``` + +### Sync to Ushadow + +Once memories exist in OpenMemory, sync them to Ushadow: + +```bash +curl -X POST http://localhost:8010/api/services/openmemory/sync +``` + +## Field Mapping + +OpenMemory memory format → Ushadow memory format: + +| OpenMemory Field | Ushadow Field | Transform | +|-----------------|---------------|-----------| +| `memory` | `content` | None | +| `id` | `title` | None (fallback) | +| `metadata.category` | `tags` | Split | +| `created_at` | `created_at` | Date format | +| `updated_at` | `updated_at` | Date format | +| `metadata.*` | `metadata.*` | Preserve all | + +## Troubleshooting + +### Connection Failed + +```bash +# Check if OpenMemory is running +curl http://localhost:8765/health + +# Check Docker container +docker ps | grep mem0 +``` + +### No Memories Returned + +```bash +# Verify user_id matches +curl "http://localhost:8765/v1/memories/?user_id=ushadow" + +# Check Ushadow logs +docker logs ushadow-backend +``` + +### Sync Issues + +1. Check service configuration: + ```bash + curl http://localhost:8010/api/services/openmemory + ``` + +2. Preview data before syncing: + ```bash + curl "http://localhost:8010/api/services/openmemory/preview?limit=5" + ``` + +3. Check backend logs for errors: + ```bash + docker logs ushadow-backend --tail=100 + ``` + +## Architecture + +``` +┌─────────────┐ +│ Ushadow │ +│ Backend │ +└──────┬──────┘ + │ REST API + │ (services/openmemory) + ▼ +┌─────────────┐ +│ OpenMemory │ +│ (mem0 API) │ +└──────┬──────┘ + │ + ├──▶ Neo4j (knowledge graph) + ├──▶ Qdrant (vector embeddings) + └──▶ SQLite (internal storage) +``` + +## Performance Tips + +1. **Adjust sync interval** based on memory creation frequency: + ```yaml + sync_interval: 3600 # 1 hour for low-frequency updates + sync_interval: 300 # 5 minutes for high-frequency updates + ``` + +2. **Limit sync batch size** to avoid overwhelming the system: + ```bash + curl -X POST "http://localhost:8010/api/services/openmemory/sync?limit=50" + ``` + +3. **Use preview** to test mappings before large syncs: + ```bash + curl "http://localhost:8010/api/services/openmemory/preview?limit=10" + ``` + +## References + +- [mem0 Official Documentation](https://docs.mem0.ai/) +- [mem0 API Reference](https://docs.mem0.ai/api-reference) +- [OpenMemory MCP Server Guide](https://apidog.com/blog/openmemory-mcp-server/) +- [Ushadow Services API](../api/services.md) + +## Next Steps + +- Set up automated syncing with cron jobs +- Configure memory retention policies +- Implement bi-directional sync +- Add custom field transformations +- Enable knowledge graph features diff --git a/docs/security-review/README.md b/docs/security-review/README.md new file mode 100644 index 00000000..176b5e91 --- /dev/null +++ b/docs/security-review/README.md @@ -0,0 +1,31 @@ +# Security Review Workflow + +This directory contains templates and examples for implementing an automated security review system that provides comprehensive vulnerability scanning and security analysis on code changes. This workflow is inspired by and taken from Anthropic's [claude-code-security-review](https://github.com/anthropics/claude-code-security-review) GitHub repository, enabling teams to proactively identify and address security issues before they reach production. + +## Concept + +This workflow establishes a comprehensive methodology for automated security reviews in Claude Code, leveraging AI agents to detect vulnerabilities and enforce security best practices: + +**Core Methodology:** +- **Automated Security Scanning**: Deploy AI-powered security reviewers that identify vulnerabilities, exposed secrets, and potential attack vectors +- **OWASP-Based Analysis**: Follow industry-standard security frameworks including OWASP Top 10 to ensure comprehensive coverage +- **Severity Classification**: Automatically categorize findings by severity level (Critical, High, Medium, Low) with clear remediation guidance +- **False Positive Management**: Intelligent filtering to reduce noise and focus on real security issues + +**Implementation Features:** +- **Slash Commands**: Enable instant security reviews with `/security-review` that analyzes recent changes for security vulnerabilities +- **GitHub Actions Integration**: Automated security scanning on every PR, with inline comments highlighting specific security concerns +- **Secret Detection**: Identify exposed API keys, credentials, and sensitive information before they're committed +- **Dependency Analysis**: Review third-party dependencies for known vulnerabilities and security risks +- **Custom Security Policies**: Configure organization-specific security requirements and compliance standards + +This approach ensures that security is built into the development process from the start, catching vulnerabilities early when they're easiest and least expensive to fix. + +## Resources + +### Templates & Examples +- [Security Review Slash Command](./security-review-slash-command.md) - Default security review command from Anthropic (source: [claude-code-security-review](https://github.com/anthropics/claude-code-security-review)) +- [Security YAML](./security.yml) - GitHub Action configuration for automated security scanning + +### Video Tutorial +For a detailed walkthrough of this workflow, watch the [comprehensive tutorial on YouTube](https://www.youtube.com/watch?v=nItsfXwujjg). diff --git a/docs/security-review/security-review-slash-command.md b/docs/security-review/security-review-slash-command.md new file mode 100644 index 00000000..0259edd2 --- /dev/null +++ b/docs/security-review/security-review-slash-command.md @@ -0,0 +1,191 @@ +--- +allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(git show:*), Bash(git remote show:*), Read, Glob, Grep, LS, Task +description: Complete a security review of the pending changes on the current branch +--- + +You are a senior security engineer conducting a focused security review of the changes on this branch. + +GIT STATUS: + +``` +!`git status` +``` + +FILES MODIFIED: + +``` +!`git diff --name-only origin/HEAD...` +``` + +COMMITS: + +``` +!`git log --no-decorate origin/HEAD...` +``` + +DIFF CONTENT: + +``` +!`git diff --merge-base origin/HEAD` +``` + +Review the complete diff above. This contains all code changes in the PR. + + +OBJECTIVE: +Perform a security-focused code review to identify HIGH-CONFIDENCE security vulnerabilities that could have real exploitation potential. This is not a general code review - focus ONLY on security implications newly added by this PR. Do not comment on existing security concerns. + +CRITICAL INSTRUCTIONS: +1. MINIMIZE FALSE POSITIVES: Only flag issues where you're >80% confident of actual exploitability +2. AVOID NOISE: Skip theoretical issues, style concerns, or low-impact findings +3. FOCUS ON IMPACT: Prioritize vulnerabilities that could lead to unauthorized access, data breaches, or system compromise +4. EXCLUSIONS: Do NOT report the following issue types: + - Denial of Service (DOS) vulnerabilities, even if they allow service disruption + - Secrets or sensitive data stored on disk (these are handled by other processes) + - Rate limiting or resource exhaustion issues + +SECURITY CATEGORIES TO EXAMINE: + +**Input Validation Vulnerabilities:** +- SQL injection via unsanitized user input +- Command injection in system calls or subprocesses +- XXE injection in XML parsing +- Template injection in templating engines +- NoSQL injection in database queries +- Path traversal in file operations + +**Authentication & Authorization Issues:** +- Authentication bypass logic +- Privilege escalation paths +- Session management flaws +- JWT token vulnerabilities +- Authorization logic bypasses + +**Crypto & Secrets Management:** +- Hardcoded API keys, passwords, or tokens +- Weak cryptographic algorithms or implementations +- Improper key storage or management +- Cryptographic randomness issues +- Certificate validation bypasses + +**Injection & Code Execution:** +- Remote code execution via deseralization +- Pickle injection in Python +- YAML deserialization vulnerabilities +- Eval injection in dynamic code execution +- XSS vulnerabilities in web applications (reflected, stored, DOM-based) + +**Data Exposure:** +- Sensitive data logging or storage +- PII handling violations +- API endpoint data leakage +- Debug information exposure + +Additional notes: +- Even if something is only exploitable from the local network, it can still be a HIGH severity issue + +ANALYSIS METHODOLOGY: + +Phase 1 - Repository Context Research (Use file search tools): +- Identify existing security frameworks and libraries in use +- Look for established secure coding patterns in the codebase +- Examine existing sanitization and validation patterns +- Understand the project's security model and threat model + +Phase 2 - Comparative Analysis: +- Compare new code changes against existing security patterns +- Identify deviations from established secure practices +- Look for inconsistent security implementations +- Flag code that introduces new attack surfaces + +Phase 3 - Vulnerability Assessment: +- Examine each modified file for security implications +- Trace data flow from user inputs to sensitive operations +- Look for privilege boundaries being crossed unsafely +- Identify injection points and unsafe deserialization + +REQUIRED OUTPUT FORMAT: + +You MUST output your findings in markdown. The markdown output should contain the file, line number, severity, category (e.g. `sql_injection` or `xss`), description, exploit scenario, and fix recommendation. + +For example: + +# Vuln 1: XSS: `foo.py:42` + +* Severity: High +* Description: User input from `username` parameter is directly interpolated into HTML without escaping, allowing reflected XSS attacks +* Exploit Scenario: Attacker crafts URL like /bar?q= to execute JavaScript in victim's browser, enabling session hijacking or data theft +* Recommendation: Use Flask's escape() function or Jinja2 templates with auto-escaping enabled for all user inputs rendered in HTML + +SEVERITY GUIDELINES: +- **HIGH**: Directly exploitable vulnerabilities leading to RCE, data breach, or authentication bypass +- **MEDIUM**: Vulnerabilities requiring specific conditions but with significant impact +- **LOW**: Defense-in-depth issues or lower-impact vulnerabilities + +CONFIDENCE SCORING: +- 0.9-1.0: Certain exploit path identified, tested if possible +- 0.8-0.9: Clear vulnerability pattern with known exploitation methods +- 0.7-0.8: Suspicious pattern requiring specific conditions to exploit +- Below 0.7: Don't report (too speculative) + +FINAL REMINDER: +Focus on HIGH and MEDIUM findings only. Better to miss some theoretical issues than flood the report with false positives. Each finding should be something a security engineer would confidently raise in a PR review. + +FALSE POSITIVE FILTERING: + +> You do not need to run commands to reproduce the vulnerability, just read the code to determine if it is a real vulnerability. Do not use the bash tool or write to any files. +> +> HARD EXCLUSIONS - Automatically exclude findings matching these patterns: +> 1. Denial of Service (DOS) vulnerabilities or resource exhaustion attacks. +> 2. Secrets or credentials stored on disk if they are otherwise secured. +> 3. Rate limiting concerns or service overload scenarios. +> 4. Memory consumption or CPU exhaustion issues. +> 5. Lack of input validation on non-security-critical fields without proven security impact. +> 6. Input sanitization concerns for GitHub Action workflows unless they are clearly triggerable via untrusted input. +> 7. A lack of hardening measures. Code is not expected to implement all security best practices, only flag concrete vulnerabilities. +> 8. Race conditions or timing attacks that are theoretical rather than practical issues. Only report a race condition if it is concretely problematic. +> 9. Vulnerabilities related to outdated third-party libraries. These are managed separately and should not be reported here. +> 10. Memory safety issues such as buffer overflows or use-after-free-vulnerabilities are impossible in rust. Do not report memory safety issues in rust or any other memory safe languages. +> 11. Files that are only unit tests or only used as part of running tests. +> 12. Log spoofing concerns. Outputting un-sanitized user input to logs is not a vulnerability. +> 13. SSRF vulnerabilities that only control the path. SSRF is only a concern if it can control the host or protocol. +> 14. Including user-controlled content in AI system prompts is not a vulnerability. +> 15. Regex injection. Injecting untrusted content into a regex is not a vulnerability. +> 16. Regex DOS concerns. +> 16. Insecure documentation. Do not report any findings in documentation files such as markdown files. +> 17. A lack of audit logs is not a vulnerability. +> +> PRECEDENTS - +> 1. Logging high value secrets in plaintext is a vulnerability. Logging URLs is assumed to be safe. +> 2. UUIDs can be assumed to be unguessable and do not need to be validated. +> 3. Environment variables and CLI flags are trusted values. Attackers are generally not able to modify them in a secure environment. Any attack that relies on controlling an environment variable is invalid. +> 4. Resource management issues such as memory or file descriptor leaks are not valid. +> 5. Subtle or low impact web vulnerabilities such as tabnabbing, XS-Leaks, prototype pollution, and open redirects should not be reported unless they are extremely high confidence. +> 6. React and Angular are generally secure against XSS. These frameworks do not need to sanitize or escape user input unless it is using dangerouslySetInnerHTML, bypassSecurityTrustHtml, or similar methods. Do not report XSS vulnerabilities in React or Angular components or tsx files unless they are using unsafe methods. +> 7. Most vulnerabilities in github action workflows are not exploitable in practice. Before validating a github action workflow vulnerability ensure it is concrete and has a very specific attack path. +> 8. A lack of permission checking or authentication in client-side JS/TS code is not a vulnerability. Client-side code is not trusted and does not need to implement these checks, they are handled on the server-side. The same applies to all flows that send untrusted data to the backend, the backend is responsible for validating and sanitizing all inputs. +> 9. Only include MEDIUM findings if they are obvious and concrete issues. +> 10. Most vulnerabilities in ipython notebooks (*.ipynb files) are not exploitable in practice. Before validating a notebook vulnerability ensure it is concrete and has a very specific attack path where untrusted input can trigger the vulnerability. +> 11. Logging non-PII data is not a vulnerability even if the data may be sensitive. Only report logging vulnerabilities if they expose sensitive information such as secrets, passwords, or personally identifiable information (PII). +> 12. Command injection vulnerabilities in shell scripts are generally not exploitable in practice since shell scripts generally do not run with untrusted user input. Only report command injection vulnerabilities in shell scripts if they are concrete and have a very specific attack path for untrusted input. +> +> SIGNAL QUALITY CRITERIA - For remaining findings, assess: +> 1. Is there a concrete, exploitable vulnerability with a clear attack path? +> 2. Does this represent a real security risk vs theoretical best practice? +> 3. Are there specific code locations and reproduction steps? +> 4. Would this finding be actionable for a security team? +> +> For each finding, assign a confidence score from 1-10: +> - 1-3: Low confidence, likely false positive or noise +> - 4-6: Medium confidence, needs investigation +> - 7-10: High confidence, likely true vulnerability + +START ANALYSIS: + +Begin your analysis now. Do this in 3 steps: + +1. Use a sub-task to identify vulnerabilities. Use the repository exploration tools to understand the codebase context, then analyze the PR changes for security implications. In the prompt for this sub-task, include all of the above. +2. Then for each vulnerability identified by the above sub-task, create a new sub-task to filter out false-positives. Launch these sub-tasks as parallel sub-tasks. In the prompt for these sub-tasks, include everything in the "FALSE POSITIVE FILTERING" instructions. +3. Filter out any vulnerabilities where the sub-task reported a confidence less than 8. + +Your final reply must contain the markdown report and nothing else. diff --git a/docs/security-review/security.yml b/docs/security-review/security.yml new file mode 100644 index 00000000..b17af368 --- /dev/null +++ b/docs/security-review/security.yml @@ -0,0 +1,24 @@ +name: Security Review + +permissions: + pull-requests: write # Needed for leaving PR comments + contents: read + +on: + pull_request: + +jobs: + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha || github.sha }} + fetch-depth: 2 + + - uses: anthropics/claude-code-security-review@main + with: + comment-pr: true + claude-api-key: ${{ secrets.ANTHROPIC_API_KEY }} + claude-model: claude-opus-4-1-20250805 + custom-security-scan-instructions: "" # Add any custom instructions specific to your codebase here. diff --git a/multi-environment-setup-guide.md b/multi-environment-setup-guide.md new file mode 100644 index 00000000..723ae68c --- /dev/null +++ b/multi-environment-setup-guide.md @@ -0,0 +1,906 @@ +# Multi-Environment Setup Guide with Port Offsets and Vite Hot Reloading + +## Overview + +This guide explains how to set up a multi-environment development system that allows multiple isolated environments to run simultaneously using: + +1. **Port Offsets**: Each environment uses unique ports to avoid conflicts +2. **Shared Infrastructure**: Single database instances with logical isolation +3. **Vite Hot Reloading**: Development server with instant UI updates +4. **Git Worktrees**: Optional multi-branch development support + +Based on the Chronicle codebase architecture. + +--- + +## Architecture Principles + +### The Three-Layer Approach + +**Layer 1: Shared Infrastructure (Same Ports)** +- MongoDB: Single instance on port 27017 +- Redis: Single instance on port 6379 +- Qdrant/Vector Store: Single instance on port 6333 +- **Why?** Resource efficient, simpler to manage, no duplicate data services + +**Layer 2: Application Services (Offset Ports)** +- Backend API: 8000 + PORT_OFFSET +- Frontend/WebUI: 3000 + PORT_OFFSET +- **Why?** Each environment needs its own application, but they can share databases + +**Layer 3: Logical Isolation (Database Names)** +- MongoDB databases: `projectname`, `projectname_env1`, `projectname_env2` +- Redis databases: 0, 1, 2, 3... (Redis supports 0-15) +- **Why?** Data isolation without duplicate database services + +--- + +## File Structure + +``` +project/ +├── .env.default # Committed template with defaults +├── backends/advanced/ +│ ├── .env # Generated, gitignored overrides +│ ├── docker-compose.yml # Main compose file +│ ├── compose/ +│ │ ├── backend.yml # Backend service definition +│ │ ├── frontend.yml # Frontend service definition +│ │ └── overrides/ +│ │ ├── dev-webui.yml # Vite dev server override +│ │ └── prod.yml # Production build override +│ └── webui/ +│ ├── Dockerfile.dev # Dev container with npm +│ ├── vite.config.ts # Vite configuration +│ └── src/ # Source files (volume mounted) +├── compose/ +│ └── infrastructure-shared.yml # Shared databases +└── setup/ + └── setuputils.py # Port/DB validation utilities +``` + +--- + +## Step-by-Step Implementation + +### Step 1: Create Setup Utilities + +Create `setup/setuputils.py` for validation: + +```python +#!/usr/bin/env python3 +""" +Setup utilities for multi-environment configuration. +Provides port checking and Redis database validation. +""" + +import sys +import socket +import subprocess +import json +from typing import List, Tuple, Optional + + +def check_port_in_use(port: int) -> bool: + """Check if a TCP port is already in use.""" + try: + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock: + sock.settimeout(0.5) + result = sock.connect_ex(('127.0.0.1', port)) + return result == 0 + except Exception: + return False + + +def find_available_redis_db( + preferred_db: int = 0, + env_name: Optional[str] = None, + container_name: str = "redis" +) -> int: + """ + Find available Redis database (0-15) for the environment. + + First checks if environment already has a marked database (reuse it). + If not, tries preferred database, then finds empty one. + This prevents database exhaustion in multi-worktree setups. + """ + # Check if this environment already has a marked database + if env_name: + for db in range(16): + marker = get_redis_db_env_marker(db, container_name) + if marker == env_name: + return db + + # Try preferred database if empty + if not check_redis_db_has_data(preferred_db, container_name): + return preferred_db + + # Find any empty database + for db in range(16): + if not check_redis_db_has_data(db, container_name): + return db + + # All full - return preferred + return preferred_db + + +def set_redis_db_env_marker( + db_num: int, + env_name: str, + container_name: str = "redis" +) -> bool: + """ + Set environment marker in Redis database. + Marker: chronicle:env:name = environment_name + """ + try: + result = subprocess.run( + ["docker", "exec", container_name, "redis-cli", "-n", str(db_num), + "SET", "chronicle:env:name", env_name], + capture_output=True, + text=True, + timeout=5 + ) + return result.returncode == 0 + except Exception: + return False + + +def validate_ports(ports: List[int]) -> Tuple[bool, List[int]]: + """Validate that ports are available.""" + conflicts = [port for port in ports if check_port_in_use(port)] + return (len(conflicts) == 0, conflicts) +``` + +**Key Features:** +- Port conflict detection +- Redis database finder with environment markers +- Prevents database exhaustion (important for 16 DB limit) +- JSON output for shell script consumption + +--- + +### Step 2: Create Configuration Templates + +#### `.env.default` (Committed Template) + +```bash +# Project Default Configuration +# Committed to repository - provides base defaults + +# ========================================== +# DOCKER COMPOSE PROJECT NAME +# ========================================== +COMPOSE_PROJECT_NAME=projectname + +# ========================================== +# DATABASE CONFIGURATION (Shared Infrastructure) +# ========================================== +MONGODB_URI=mongodb://mongo:27017 +MONGODB_DATABASE=projectname +REDIS_URL=redis://redis:6379/0 +REDIS_DATABASE=0 +QDRANT_BASE_URL=qdrant + +# ========================================== +# NETWORK CONFIGURATION (Application Ports) +# ========================================== +PORT_OFFSET=0 +BACKEND_PORT=8000 +WEBUI_PORT=3000 +HOST_IP=localhost + +# CORS with variable substitution support +CORS_ORIGINS=http://localhost:${WEBUI_PORT:-3000},http://localhost:${BACKEND_PORT:-8000} +VITE_BACKEND_URL=http://localhost:${BACKEND_PORT:-8000} + +# ========================================== +# TEST ENVIRONMENT PORTS +# ========================================== +TEST_BACKEND_PORT=8001 +TEST_WEBUI_PORT=3001 + +# ========================================== +# AUTHENTICATION & API KEYS +# ========================================== +AUTH_SECRET_KEY= +# Add other secrets... +``` + +**Why this structure?** +- ✅ Committed template everyone can use +- ✅ Variable substitution for dynamic ports +- ✅ Clear separation of concerns +- ✅ Test ports automatically offset by 1 + +--- + +### Step 3: Create Quick Start Script + +Create `quick-start.sh`: + +```bash +#!/bin/bash +set -e + +ENV_FILE="backends/advanced/.env" +SETUP_UTILS="setup/setuputils.py" + +# Colors for output +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' + +echo "🚀 Multi-Environment Setup" +echo "" + +# Prompt for environment name +read -p "Environment name [projectname]: " INPUT_ENV_NAME +ENV_NAME="${INPUT_ENV_NAME:-projectname}" +ENV_NAME=$(echo "$ENV_NAME" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-') + +# Find available ports with validation +PORTS_AVAILABLE=false +while [ "$PORTS_AVAILABLE" = false ]; do + read -p "Port offset [0]: " INPUT_PORT_OFFSET + PORT_OFFSET="${INPUT_PORT_OFFSET:-0}" + + BACKEND_PORT=$((8000 + PORT_OFFSET)) + WEBUI_PORT=$((3000 + PORT_OFFSET)) + + # Validate ports using Python utility + PORT_CHECK=$(python3 "$SETUP_UTILS" validate-ports "$BACKEND_PORT" "$WEBUI_PORT") + if [ $? -eq 0 ]; then + PORTS_AVAILABLE=true + else + CONFLICTS=$(echo "$PORT_CHECK" | python3 -c "import sys, json; print('\n'.join([f'Port {p}' for p in json.load(sys.stdin)['conflicts']]))") + echo -e "${RED}⚠️ Port conflicts: ${CONFLICTS}${NC}" + echo "Please choose different offset" + fi +done + +# Find available Redis database +PREFERRED_REDIS_DB=$(( (PORT_OFFSET / 10) % 16 )) +REDIS_RESULT=$(python3 "$SETUP_UTILS" find-redis-db "$PREFERRED_REDIS_DB" "$ENV_NAME") +REDIS_DATABASE=$(echo "$REDIS_RESULT" | python3 -c "import sys, json; print(json.load(sys.stdin)['db_num'])") + +# Set environment marker +python3 "$SETUP_UTILS" set-redis-marker "$REDIS_DATABASE" "$ENV_NAME" + +# Calculate test ports +TEST_BACKEND_PORT=$((8001 + PORT_OFFSET)) +TEST_WEBUI_PORT=$((3001 + PORT_OFFSET)) + +# Set database names +if [[ "$ENV_NAME" == "projectname" ]]; then + MONGODB_DATABASE="projectname" + COMPOSE_PROJECT_NAME="projectname" +else + MONGODB_DATABASE="projectname_${ENV_NAME}" + COMPOSE_PROJECT_NAME="projectname-${ENV_NAME}" +fi + +echo "" +echo -e "${GREEN}✅ Configuration:${NC}" +echo " Environment: $ENV_NAME" +echo " Backend: $BACKEND_PORT" +echo " WebUI: $WEBUI_PORT" +echo " Redis DB: $REDIS_DATABASE" +echo "" + +# Generate .env file +cat > "$ENV_FILE" <> backends/advanced/.env +``` + +5. **Test and verify:** +```bash +docker compose down +docker compose -f compose/infrastructure-shared.yml up -d +cd backends/advanced +docker compose up -d +``` + +--- + +## Summary Checklist + +### Setup Checklist +- [ ] Create `setuputils.py` with port and Redis DB validation +- [ ] Create `.env.default` with variable substitution +- [ ] Create `quick-start.sh` for interactive setup +- [ ] Set up infrastructure-shared.yml (MongoDB, Redis, Qdrant) +- [ ] Configure backend.yml with env_file layers +- [ ] Create dev-webui.yml override for hot reload +- [ ] Configure vite.config.ts with HMR settings +- [ ] Create Dockerfile.dev with volume mounts +- [ ] Add .env to .gitignore +- [ ] Test hot reload with source file change + +### Hot Reload Checklist +- [ ] Vite server on host: '0.0.0.0' +- [ ] VITE_HMR_PORT set to external port +- [ ] src/ folder volume mounted +- [ ] vite.config.ts volume mounted +- [ ] Port mapping: ${WEBUI_PORT}:5173 +- [ ] Using dev-webui.yml override +- [ ] npm run dev starts Vite dev server + +### Multi-Environment Checklist +- [ ] Each environment has unique PORT_OFFSET +- [ ] Each environment has unique MONGODB_DATABASE +- [ ] Each environment has unique REDIS_DATABASE (0-15) +- [ ] Each environment has unique COMPOSE_PROJECT_NAME +- [ ] Port validation runs before starting +- [ ] Redis DB markers prevent exhaustion +- [ ] Test ports automatically calculated (+1 offset) +- [ ] Infrastructure started only once +- [ ] .env files gitignored + +--- + +## Additional Resources + +### Useful Commands + +```bash +# Check which ports are in use +python3 setup/setuputils.py validate-ports 8000 3000 8010 3010 + +# Find available Redis database for environment +python3 setup/setuputils.py find-redis-db 2 "gold" + +# List running containers by environment +docker ps --filter "name=projectname-gold" + +# View all environment containers +docker ps --format "table {{.Names}}\t{{.Ports}}" | grep projectname + +# Stop specific environment +docker compose -p projectname-gold down + +# View logs for specific environment +docker logs projectname-gold-backend-1 -f +``` + +### Debugging Hot Reload + +```bash +# Check if WebSocket connection works +# Open browser dev console → Network → WS tab +# Should see: ws://localhost:3010/ (connected) + +# Verify volume mounts +docker inspect projectname-webui-1 | grep -A 20 Mounts + +# Check HMR environment variables +docker exec projectname-webui-1 env | grep VITE_HMR_PORT +``` + +--- + +## Conclusion + +This multi-environment setup provides: + +✅ **Parallel Development**: Multiple environments run simultaneously +✅ **Resource Efficiency**: Single database infrastructure shared by all +✅ **Fast Iteration**: Vite hot reload for instant UI updates +✅ **Data Isolation**: Separate databases prevent cross-contamination +✅ **Parallel Testing**: Test suites run concurrently without conflicts +✅ **Simple Management**: Clear container naming, easy identification +✅ **Scalability**: Supports up to 16 environments (Redis DB limit) + +By following this guide, other agents can implement the same robust multi-environment architecture used in the Chronicle project. diff --git a/ushadow/backend/test_user_api.py b/ushadow/backend/test_user_api.py new file mode 100644 index 00000000..e86eaae0 --- /dev/null +++ b/ushadow/backend/test_user_api.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python3 +""" +Quick test script to check what /api/auth/me returns +""" +import asyncio +from src.models.user import UserRead, User +from beanie import PydanticObjectId + +async def test_user_serialization(): + # Simulate a user record from DB + user = User( + id=PydanticObjectId("69830c0045d101deddb5ceb8"), + email="stu@theawesome.co.uk", + display_name="stu alexander", + is_active=True, + is_superuser=False, + is_verified=True, + hashed_password="" + ) + + # Serialize using UserRead + user_read = UserRead( + id=user.id, + email=user.email, + display_name=user.display_name, + is_active=user.is_active, + is_superuser=user.is_superuser, + is_verified=user.is_verified, + created_at=None, + updated_at=None, + ) + + # Check what gets serialized + print("UserRead model_dump():") + print(user_read.model_dump()) + print() + print("UserRead model_dump_json():") + print(user_read.model_dump_json()) + +if __name__ == "__main__": + asyncio.run(test_user_serialization()) diff --git a/ushadow/mobile/Gemfile.lock b/ushadow/mobile/Gemfile.lock index 40415c04..96ecab14 100644 --- a/ushadow/mobile/Gemfile.lock +++ b/ushadow/mobile/Gemfile.lock @@ -15,7 +15,7 @@ GEM minitest (>= 5.1) securerandom (>= 0.3) tzinfo (~> 2.0, >= 2.0.5) - addressable (2.8.8) + addressable (2.8.9) public_suffix (>= 2.0.2, < 8.0) algoliasearch (1.27.5) httpclient (~> 2.8, >= 2.8.3) @@ -23,7 +23,7 @@ GEM artifactory (3.0.17) atomos (0.1.3) aws-eventstream (1.4.0) - aws-partitions (1.1213.0) + aws-partitions (1.1220.0) aws-sdk-core (3.242.0) aws-eventstream (~> 1, >= 1.3.0) aws-partitions (~> 1, >= 1.992.0) @@ -32,7 +32,7 @@ GEM bigdecimal jmespath (~> 1, >= 1.6.1) logger - aws-sdk-kms (1.121.0) + aws-sdk-kms (1.122.0) aws-sdk-core (~> 3, >= 3.241.4) aws-sigv4 (~> 1.5) aws-sdk-s3 (1.213.0) @@ -130,7 +130,7 @@ GEM faraday_middleware (1.2.1) faraday (~> 1.0) fastimage (2.4.0) - fastlane (2.232.1) + fastlane (2.232.2) CFPropertyList (>= 2.3, < 4.0.0) abbrev (~> 0.1.2) addressable (>= 2.8, < 3.0.0) @@ -201,7 +201,7 @@ GEM google-apis-core (>= 0.15.0, < 2.a) google-apis-playcustomapp_v1 (0.17.0) google-apis-core (>= 0.15.0, < 2.a) - google-apis-storage_v1 (0.60.0) + google-apis-storage_v1 (0.61.0) google-apis-core (>= 0.15.0, < 2.a) google-cloud-core (1.8.0) google-cloud-env (>= 1.0, < 3.a) @@ -261,7 +261,7 @@ GEM declarative (< 0.1.0) trailblazer-option (>= 0.1.1, < 0.2.0) uber (< 0.2.0) - retriable (3.1.2) + retriable (3.2.1) rexml (3.4.4) rouge (3.28.0) ruby-macho (2.5.1)