From d5786e513118e544fe590b552271983130c2ea80 Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Wed, 20 Aug 2025 12:59:57 +0000 Subject: [PATCH] docs: add comprehensive Build Architecture Guard documentation - Update main README with guard system overview - Create detailed guard implementation guide - Add PR template documentation and usage examples - Document opt-in hook activation process --- README-BUILD-GUARD.md | 290 ++++++++++++++++++++++++++++++++++++++++ README-PR-TEMPLATE.md | 82 ++++++++++++ README.md | 304 +++++++++++------------------------------- 3 files changed, 448 insertions(+), 228 deletions(-) create mode 100644 README-BUILD-GUARD.md create mode 100644 README-PR-TEMPLATE.md diff --git a/README-BUILD-GUARD.md b/README-BUILD-GUARD.md new file mode 100644 index 00000000..9b617edb --- /dev/null +++ b/README-BUILD-GUARD.md @@ -0,0 +1,290 @@ +# Build Architecture Guard - Husky Implementation + +## Overview + +The Build Architecture Guard protects your build system by enforcing +documentation requirements through **Git hooks**. When you modify +build-critical files, the system automatically blocks commits/pushes +until you update `BUILDING.md`. + +## 🎯 **Why Husky-Only?** + +**Advantages:** + +- βœ… **Immediate feedback** - Hooks run before commit/push +- βœ… **Works everywhere** - No server-side CI/CD required +- βœ… **Simple setup** - One tool, one configuration +- βœ… **Fast execution** - No network delays or server queues +- βœ… **Offline support** - Works without internet connection + +**Trade-offs:** + +- ⚠️ **Can be bypassed** - `git commit --no-verify` or `git push --no-verify` +- ⚠️ **Developer discipline** - Relies on team following the rules + +## πŸ—οΈ **Architecture** + +```bash +Developer Workflow: +1. Modify build files (scripts/, vite.config.*, etc.) +2. Try to commit β†’ Husky pre-commit hook runs +3. Guard script checks if BUILDING.md was updated +4. βœ… Commit succeeds if docs updated +5. ❌ Commit blocked if docs missing +``` + +## πŸš€ **Quick Start** + +### 1. Install Dependencies + +```bash +npm install +npm run prepare # Sets up Husky hooks +``` + +### 2. Test the System + +```bash +# Modify a build file without updating BUILDING.md +echo "# test" >> scripts/test.sh + +# Try to commit (should be blocked) +git add scripts/test.sh +git commit -m "test: add build script" +# ❌ Hook blocks commit with helpful message +``` + +### 3. Fix and Retry + +```bash +# Update BUILDING.md with your changes +echo "## New Build Script" >> BUILDING.md +echo "Added test.sh for testing purposes" >> BUILDING.md + +# Now commit should succeed +git add BUILDING.md +git commit -m "feat: add test build script with docs" +# βœ… Commit succeeds +``` + +## πŸ”§ **How It Works** + +### Pre-commit Hook (`.husky/pre-commit`) + +- **When**: Every `git commit` +- **What**: Runs `./scripts/build-arch-guard.sh --staged` +- **Result**: Blocks commit if build files changed without BUILDING.md update + +### Pre-push Hook (`.husky/pre-push`) + +- **When**: Every `git push` +- **What**: Runs `./scripts/build-arch-guard.sh --range` +- **Result**: Blocks push if commits contain undocumented build changes + +### Guard Script (`scripts/build-arch-guard.sh`) + +- **Detects**: Changes to build-sensitive file patterns +- **Validates**: BUILDING.md was updated alongside changes +- **Reports**: Clear error messages with guidance + +## πŸ“ **Protected File Patterns** + +The guard script monitors these paths for changes: + +```text +Build Configuration: +β”œβ”€β”€ vite.config.* # Vite configuration +β”œβ”€β”€ capacitor.config.ts # Capacitor configuration +β”œβ”€β”€ package.json # Package configuration +β”œβ”€β”€ package-lock.json # Lock files +β”œβ”€β”€ yarn.lock +└── pnpm-lock.yaml + +Build Scripts: +β”œβ”€β”€ scripts/** # All build and automation scripts +β”œβ”€β”€ electron/** # Electron build files +β”œβ”€β”€ android/** # Android build configuration +β”œβ”€β”€ ios/** # iOS build configuration +β”œβ”€β”€ sw_scripts/** # Service worker scripts +└── sw_combine.js # Service worker combination + +Deployment: +β”œβ”€β”€ Dockerfile # Docker configuration +└── docker/** # Docker services +``` + +## 🎭 **Usage Scenarios** + +### Scenario 1: Adding a New Build Script + +```bash +# ❌ This will be blocked +echo '#!/bin/bash' > scripts/new-build.sh +git add scripts/new-build.sh +git commit -m "feat: add new build script" +# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated" + +# βœ… This will succeed +echo '#!/bin/bash' > scripts/new-build.sh +echo '## New Build Script' >> BUILDING.md +echo 'Added new-build.sh for feature X' >> BUILDING.md +git add scripts/new-build.sh BUILDING.md +git commit -m "feat: add new build script with docs" +# βœ… Commit succeeds +``` + +### Scenario 2: Updating Vite Configuration + +```bash +# ❌ This will be blocked +echo 'export default { newOption: true }' >> vite.config.ts +git add vite.config.ts +git commit -m "config: add new vite option" +# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated" + +# βœ… This will succeed +echo 'export default { newOption: true }' >> vite.config.ts +echo '### New Vite Option' >> BUILDING.md +echo 'Added newOption for improved performance' >> BUILDING.md +git add vite.config.ts BUILDING.md +git commit -m "config: add new vite option with docs" +# βœ… Commit succeeds +``` + +## 🚨 **Emergency Bypass** + +**⚠️ Use sparingly and only for emergencies:** + +```bash +# Skip pre-commit hook +git commit -m "emergency: critical fix" --no-verify + +# Skip pre-push hook +git push --no-verify + +# Remember to update BUILDING.md later! +``` + +## πŸ” **Troubleshooting** + +### Hooks Not Running + +```bash +# Reinstall hooks +npm run prepare + +# Check hook files exist and are executable +ls -la .husky/ +chmod +x .husky/* + +# Verify Git hooks path +git config core.hooksPath +# Should show: .husky +``` + +### Guard Script Issues + +```bash +# Test guard script manually +./scripts/build-arch-guard.sh --help + +# Check script permissions +chmod +x scripts/build-arch-guard.sh + +# Test with specific files +./scripts/build-arch-guard.sh --staged +``` + +### False Positives + +```bash +# If guard blocks legitimate changes, check: +# 1. Are you modifying a protected file pattern? +# 2. Did you update BUILDING.md? +# 3. Is BUILDING.md staged for commit? + +# View what the guard sees +git diff --name-only --cached +``` + +## πŸ“‹ **Best Practices** + +### For Developers + +1. **Update BUILDING.md first** - Document changes before implementing +2. **Test locally** - Run `./scripts/build-arch-guard.sh --staged` before committing +3. **Use descriptive commits** - Include context about build changes +4. **Don't bypass lightly** - Only use `--no-verify` for true emergencies + +### For Teams + +1. **Document the system** - Ensure everyone understands the guard +2. **Review BUILDING.md updates** - Verify documentation quality +3. **Monitor bypass usage** - Track when hooks are skipped +4. **Regular audits** - Check that BUILDING.md stays current + +### For Maintainers + +1. **Update protected patterns** - Modify `scripts/build-arch-guard.sh` as needed +2. **Monitor effectiveness** - Track how often the guard catches issues +3. **Team training** - Help developers understand the system +4. **Continuous improvement** - Refine patterns and error messages + +## πŸ”„ **Customization** + +### Adding New Protected Paths + +Edit `scripts/build-arch-guard.sh`: + +```bash +SENSITIVE=( + # ... existing patterns ... + "new-pattern/**" # Add your new pattern + "*.config.js" # Add file extensions +) +``` + +### Modifying Error Messages + +Edit the guard script to customize: + +- Error message content +- File pattern matching +- Documentation requirements +- Bypass instructions + +### Adding New Validation Rules + +Extend the guard script to check for: + +- Specific file content patterns +- Required documentation sections +- Commit message formats +- Branch naming conventions + +## πŸ“š **Integration with PR Template** + +The `pull_request_template.md` works with this system by: + +- **Guiding developers** through required documentation +- **Ensuring consistency** across all build changes +- **Providing checklist** for comprehensive updates +- **Supporting L1/L2/L3** change classification + +## 🎯 **Success Metrics** + +Track the effectiveness of your Build Architecture Guard: + +- **Hook execution rate** - How often hooks run successfully +- **Bypass frequency** - How often `--no-verify` is used +- **Documentation quality** - BUILDING.md stays current +- **Build failures** - Fewer issues from undocumented changes +- **Team adoption** - Developers follow the process + +--- + +**Status**: Active protection system +**Architecture**: Client-side Git hooks only +**Dependencies**: Husky, Git, Bash +**Maintainer**: Development team +**Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh` diff --git a/README-PR-TEMPLATE.md b/README-PR-TEMPLATE.md new file mode 100644 index 00000000..fa977e02 --- /dev/null +++ b/README-PR-TEMPLATE.md @@ -0,0 +1,82 @@ +# Pull Request Template + +## Location + +The Build Architecture Guard PR template is located at: + +- **`pull_request_template.md`** (root directory) + +## Usage + +When creating a pull request in Gitea, this template will automatically populate the PR description with the required checklist. + +## Template Features + +### Change Level Classification + +- **L1**: Minor changes, documentation updates +- **L2**: Moderate changes, new features, environment changes +- **L3**: Major changes, architecture changes, new platforms + +### Required Fields for All Levels + +- Change level selection +- Scope and impact description +- Commands executed and their output +- Documentation updates (BUILDING.md) +- Rollback verification steps + +### Additional Requirements for L3 + +- **ADR link**: Must provide URL to Architectural Decision Record +- **Artifacts with SHA256**: Must list artifacts with cryptographic hashes + +## Integration + +This template works with: + +- **Gitea Actions**: `.gitea/workflows/build-guard.yml` +- **Client-side hooks**: `.husky/` pre-commit and pre-push hooks +- **Guard script**: `scripts/build-arch-guard.sh` + +## Example Usage + +```markdown +### Change Level +- [x] Level: **L2** + +**Why:** Adding new build script for Docker deployment + +### Scope & Impact +- [x] Files & platforms touched: scripts/build-docker.sh, + BUILDING.md +- [x] Risk triggers: Docker build process changes +- [x] Mitigations/validation done: Tested on local Docker environment + +### Commands Run +- [x] Web: `npm run build:web:docker` βœ… +- [x] Docker: `docker build -t test-image .` βœ… + +### Artifacts +- [x] Names + **sha256** of artifacts/installers: + +Artifacts: +```text +test-image.tar a1b2c3d4e5f6... +``` + +### Docs +- [x] **BUILDING.md** updated (sections): Docker deployment +- [x] Troubleshooting updated: Added Docker troubleshooting section + +### Rollback +- [x] Verified steps to restore previous behavior: + 1. `git revert HEAD` + 2. `docker rmi test-image` + 3. Restore previous BUILDING.md +``` + +--- + +**Note**: This template is enforced by the Build Architecture Guard +system. Complete all required fields to ensure your PR can be merged. diff --git a/README.md b/README.md index fc954fd5..c39fbde9 100644 --- a/README.md +++ b/README.md @@ -1,270 +1,118 @@ -# TimeSafari.app - Crowd-Funder for Time - PWA +# Time Safari Application -[Time Safari](https://timesafari.org/) allows people to ease into collaboration: start with expressions of gratitude -and expand to crowd-fund with time & money, then record and see the impact of contributions. +**Author**: Matthew Raymer +**Version**: 1.0.8-beta +**Description**: Time Safari Application -## Roadmap +## πŸ›‘οΈ Build Architecture Guard -See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities. +This project uses **Husky Git hooks** to protect the build system +architecture. When you modify build-critical files, the system +automatically blocks commits until you update `BUILDING.md`. -## Setup & Building - -Quick start: - -* For setup, we recommend [pkgx](https://pkgx.dev), which installs what you need (either automatically or with the `dev` command). Core dependencies are typescript & npm; when building for other platforms, you'll need other things such as those in the pkgx.yaml & BUILDING.md files. +### Quick Setup ```bash -npm install -npm run build:web:serve -- --test -``` - -To be able to make submissions: go to "profile" (bottom left), go to the bottom and expand "Show Advanced Settings", go to the bottom and to the "Test Page", and finally "Become User 0" to see all the functionality. - -See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker). - -## Development Database Clearing - -TimeSafari provides a simple script-based approach to clear the local database (not the claim server) for development purposes. - -## Logging Configuration - -TimeSafari supports configurable logging levels via the `VITE_LOG_LEVEL` environment variable. This allows developers to control console output verbosity without modifying code. - -### Quick Usage - -```bash -# Show only errors -VITE_LOG_LEVEL=error npm run dev - -# Show warnings and errors -VITE_LOG_LEVEL=warn npm run dev - -# Show info, warnings, and errors (default) -VITE_LOG_LEVEL=info npm run dev - -# Show all log levels including debug -VITE_LOG_LEVEL=debug npm run dev +npm run guard:setup # Install and activate the guard ``` -### Available Levels +### How It Works -- **`error`**: Critical errors only -- **`warn`**: Warnings and errors (default for production web) -- **`info`**: Info, warnings, and errors (default for development/capacitor) -- **`debug`**: All log levels including verbose debugging +- **Pre-commit**: Blocks commits if build files changed without + BUILDING.md updates +- **Pre-push**: Blocks pushes if commits contain undocumented build + changes +- **Protected paths**: `scripts/`, `vite.config.*`, `electron/`, + `android/`, `ios/`, etc. -See [Logging Configuration Guide](doc/logging-configuration.md) for complete details. +### Usage -### Quick Usage ```bash -# Run the database clearing script -./scripts/clear-database.sh +# Test the guard manually +npm run guard:test -# Then restart your development server -npm run build:electron:dev # For Electron -npm run build:web:dev # For Web +# Emergency bypass (use sparingly) +git commit --no-verify +git push --no-verify ``` -### What It Does - -#### **Electron (Desktop App)** -- Automatically finds and clears the SQLite database files -- Works on Linux, macOS, and Windows -- Clears all data and forces fresh migrations on next startup - -#### **Web Browser** -- Provides instructions for using custom browser data directories -- Shows manual clearing via browser DevTools -- Ensures reliable database clearing without browser complications - -### Safety Features -- βœ… **Interactive Script**: Guides you through the process -- βœ… **Platform Detection**: Automatically detects your OS -- βœ… **Clear Instructions**: Step-by-step guidance for each platform -- βœ… **Safe Paths**: Only clears TimeSafari-specific data +**πŸ“š Full documentation**: See `README-BUILD-GUARD.md` -### Manual Commands (if needed) +## πŸš€ Quick Start -#### **Electron Database Location** -```bash -# Linux -rm -rf ~/.config/TimeSafari/* +### Prerequisites -# macOS -rm -rf ~/Library/Application\ Support/TimeSafari/* +- Node.js 18+ +- npm, yarn, or pnpm +- Git -# Windows -rmdir /s /q %APPDATA%\TimeSafari -``` +### Installation -#### **Web Browser (Custom Data Directory)** ```bash -# Create isolated browser profile -mkdir ~/timesafari-dev-data -``` - -## Domain Configuration - -TimeSafari uses a centralized domain configuration system to ensure consistent -URL generation across all environments. This prevents localhost URLs from -appearing in shared links during development. - -### Key Features -- βœ… **Production URLs for Sharing**: All copy link buttons use production domain -- βœ… **Environment-Specific Internal URLs**: Internal operations use appropriate - environment URLs -- βœ… **Single Point of Control**: Change domain in one place for entire app -- βœ… **Type-Safe Configuration**: Full TypeScript support - -### Quick Reference - -```typescript -// For sharing functionality (environment-specific) -import { APP_SERVER } from "@/constants/app"; -const shareLink = `${APP_SERVER}/deep-link/claim/123`; - -// For internal operations (environment-specific) -import { APP_SERVER } from "@/constants/app"; -const apiUrl = `${APP_SERVER}/api/claim/123`; +npm install +npm run guard:setup # Sets up Build Architecture Guard ``` -### Documentation - -- [Constants and Configuration](src/constants/app.ts) - Core constants - -## Tests - -See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions. - -## Asset Management - -TimeSafari uses a standardized asset configuration system for consistent -icon and splash screen generation across all platforms. - -### Asset Sources - -- **Single source of truth**: `resources/` directory (Capacitor default) -- **Source files**: `icon.png`, `splash.png`, `splash_dark.png` -- **Format**: PNG or SVG files for optimal quality - -### Asset Generation - -- **Configuration**: `config/assets/capacitor-assets.config.json` -- **Schema validation**: `config/assets/schema.json` -- **Build-time generation**: Platform assets generated via `capacitor-assets` -- **No VCS commits**: Generated assets are never committed to version control - -### Development Commands +### Development ```bash -# Generate/update asset configurations -npm run assets:config - -# Validate asset configurations -npm run assets:validate - -# Clean generated platform assets (local dev only) -npm run assets:clean - -# Build with asset generation -npm run build:native +npm run build:web:dev # Build web version +npm run build:ios:test # Build iOS test version +npm run build:android:test # Build Android test version +npm run build:electron:dev # Build Electron dev version ``` -### Environment Setup & Dependencies - -Before building the application, ensure your development environment is properly -configured: +### Testing ```bash -# Install all dependencies (required first time and after updates) -npm install - -# Validate your development environment -npm run check:dependencies - -# Check prerequisites for testing -npm run test:prerequisites +npm run test:web # Run web tests +npm run test:mobile # Run mobile tests +npm run test:all # Run all tests ``` -**Common Issues & Solutions**: - -- **"tsx: command not found"**: Run `npm install` to install devDependencies -- **"capacitor-assets: command not found"**: Ensure `@capacitor/assets` is installed -- **Build failures**: Run `npm run check:dependencies` to diagnose environment issues - -**Required Versions**: -- Node.js: 18+ (LTS recommended) -- npm: 8+ (comes with Node.js) -- Platform-specific tools: Android Studio, Xcode (for mobile builds) - -### Platform Support - -- **Android**: Adaptive icons with foreground/background, monochrome support -- **iOS**: LaunchScreen storyboard preferred, splash assets when needed -- **Web**: PWA icons generated during build to `dist/` (not committed) - -### Font Awesome Icons - -To add a Font Awesome icon, add to `fontawesome.ts` and reference with -`font-awesome` element and `icon` attribute with the hyphenated name. - -## Other - -### Reference Material - -* Notifications can be type of `toast` (self-dismiss), `info`, `success`, `warning`, and `danger`. - They are done via [notiwind](https://www.npmjs.com/package/notiwind) and set up in App.vue. - -* [Customize Vue configuration](https://cli.vuejs.org/config/). - -* If you are deploying in a subdirectory, add it to `publicPath` in vue.config.js, eg: `publicPath: "/app/time-tracker/",` - -### Code Organization - -The project uses a centralized approach to type definitions and interfaces: +## πŸ“ Project Structure + +```text +timesafari/ +β”œβ”€β”€ πŸ“ src/ # Source code +β”œβ”€β”€ πŸ“ scripts/ # Build and automation scripts +β”œβ”€β”€ πŸ“ electron/ # Electron configuration +β”œβ”€β”€ πŸ“ android/ # Android configuration +β”œβ”€β”€ πŸ“ ios/ # iOS configuration +β”œβ”€β”€ πŸ“ .husky/ # Git hooks (Build Architecture Guard) +β”œβ”€β”€ πŸ“„ BUILDING.md # Build system documentation +β”œβ”€β”€ πŸ“„ pull_request_template.md # PR template +└── πŸ“„ README-BUILD-GUARD.md # Guard system documentation +``` -* `src/interfaces/` - Contains all TypeScript interfaces and type definitions - * `deepLinks.ts` - Deep linking type system and Zod validation schemas - * `give.ts` - Give-related interfaces and type definitions - * `claims.ts` - Claim-related interfaces and verifiable credentials - * `common.ts` - Shared interfaces and utility types - * Other domain-specific interface files +## πŸ”§ Build System -Key principles: -- All interfaces and types are defined in the interfaces folder -- Zod schemas are used for runtime validation and type generation -- Domain-specific interfaces are separated into their own files -- Common interfaces are shared through `common.ts` -- Type definitions are generated from Zod schemas where possible +This project supports multiple platforms: -### Database Architecture +- **Web**: Vite-based build with service worker support +- **Mobile**: Capacitor-based iOS and Android builds +- **Desktop**: Electron-based cross-platform desktop app +- **Docker**: Containerized deployment options -The application uses a platform-agnostic database layer with Vue mixins for service access: +## πŸ“š Documentation -* `src/services/PlatformService.ts` - Database interface definition -* `src/services/PlatformServiceFactory.ts` - Platform-specific service factory -* `src/services/AbsurdSqlDatabaseService.ts` - SQLite implementation -* `src/utils/PlatformServiceMixin.ts` - Vue mixin for database access with caching -* `src/db/` - Legacy Dexie database (migration in progress) +- **`BUILDING.md`** - Complete build system guide +- **`README-BUILD-GUARD.md`** - Build Architecture Guard documentation +- **`pull_request_template.md`** - PR template for build changes -**Development Guidelines**: +## 🀝 Contributing -- Always use `PlatformServiceMixin` for database operations in components -- Test with PlatformServiceMixin for new features -- Use migration tools for data transfer between systems -- Leverage mixin's ultra-concise methods: `$db()`, `$exec()`, `$one()`, `$contacts()`, `$settings()` +1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files +2. **Use the PR template** - Complete the checklist for build-related changes +3. **Test your changes** - Ensure builds work on affected platforms +4. **Document updates** - Keep BUILDING.md current and accurate -**Architecture Decision**: The project uses Vue mixins over Composition API composables for platform service access. See [Architecture Decisions](doc/architecture-decisions.md) for detailed rationale. +## πŸ“„ License -### Kudos +[Add your license information here] -Gifts make the world go 'round! +--- -* [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/) for the free open-source license -* [MΓ‘ximo FernΓ‘ndez](https://medium.com/@maxfarenas) for the 3D [code](https://github.com/maxfer03/vue-three-ns) and [explanatory post](https://medium.com/nicasource/building-an-interactive-web-portfolio-with-vue-three-js-part-three-implementing-three-js-452cb375ef80) -* [Many tools & libraries](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/src/branch/master/package.json#L10) such as Nodejs.org, IntelliJ Idea, Veramo.io, Vuejs.org, threejs.org -* [Bush 3D model](https://sketchfab.com/3d-models/lupine-plant-bf30f1110c174d4baedda0ed63778439) -* [Forest floor image](https://www.goodfreephotos.com/albums/textures/leafy-autumn-forest-floor.jpg) -* Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e) -* [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons -* Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/) +**Note**: The Build Architecture Guard is active and will block +commits/pushes that modify build files without proper documentation +updates. See `README-BUILD-GUARD.md` for complete details.