diff --git a/.github/workflows/auto-progress-update.yml b/.github/workflows/auto-progress-update.yml new file mode 100644 index 00000000..5c76c66e --- /dev/null +++ b/.github/workflows/auto-progress-update.yml @@ -0,0 +1,95 @@ +--- +name: auto/progress-update + +# Automatically updates module progress when PRs are merged to claude-yolo +# Looks for progress markers in PR body like: progress:bridge=+10 + +on: + pull_request: + types: [closed] + branches: + - claude-yolo + - main + +permissions: + contents: write + pull-requests: read + +jobs: + update-progress: + name: auto/progress-update + if: github.event.pull_request.merged == true + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.base.ref }} + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract progress updates from PR body + id: extract + uses: actions/github-script@v7 + with: + script: | + const body = context.payload.pull_request.body || ""; + const title = context.payload.pull_request.title || ""; + + // Look for progress markers like: + // progress:bridge=+10 + // progress:governance=25 + // progress:scaffold=+5 + const progressRegex = /progress:([a-z-]+)=(\+?\d+)/g; + const updates = []; + + let match; + while ((match = progressRegex.exec(body)) !== null) { + updates.push({ + module: match[1], + value: match[2] + }); + } + + core.setOutput('updates', JSON.stringify(updates)); + core.setOutput('has_updates', updates.length > 0 ? 'true' : 'false'); + core.setOutput('pr_title', title); + + - name: Apply progress updates + if: steps.extract.outputs.has_updates == 'true' + env: + UPDATES: ${{ steps.extract.outputs.updates }} + PR_TITLE: ${{ steps.extract.outputs.pr_title }} + run: | + echo "Applying progress updates from PR..." + echo "${UPDATES}" | jq -r '.[] | "\(.module) \(.value)"' | while read -r module value; do + echo "Updating ${module} to ${value}%" + bash scripts/update-progress.sh "${module}" "${value}" "Auto-update from PR: ${PR_TITLE}" + done + + - name: Configure git + if: steps.extract.outputs.has_updates == 'true' + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + - name: Commit progress updates + if: steps.extract.outputs.has_updates == 'true' + env: + UPDATES: ${{ steps.extract.outputs.updates }} + run: | + if git diff --quiet docs/STATUS_v2.md; then + echo "No changes to commit" + exit 0 + fi + + MODULE_LIST=$(echo "${UPDATES}" | jq -r '.[].module' | paste -sd "," -) + + git add docs/STATUS_v2.md STATUS/progress-log.md || true + git commit -m "chore(status): auto-update progress for ${MODULE_LIST} + +Triggered by PR #${{ github.event.pull_request.number }} +[skip ci]" + git push + + - name: Update marker + run: echo "AUTO_PROGRESS_UPDATE=OK" diff --git a/.github/workflows/sync-github-project.yml b/.github/workflows/sync-github-project.yml new file mode 100644 index 00000000..35991829 --- /dev/null +++ b/.github/workflows/sync-github-project.yml @@ -0,0 +1,42 @@ +--- +name: sync/github-project + +# Syncs module progress to GitHub Projects when STATUS_v2.md changes + +on: + push: + branches: + - claude-yolo + - main + paths: + - 'docs/STATUS_v2.md' + workflow_dispatch: + +permissions: + contents: read + issues: write + repository-projects: write + +jobs: + sync-project: + name: sync/github-project + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup GitHub CLI with project scope + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + echo "$GH_TOKEN" | gh auth login --with-token + gh auth status + + - name: Sync to GitHub Project + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + bash scripts/sync-to-github-project.sh + + - name: Sync marker + run: echo "GITHUB_PROJECT_SYNC=OK" diff --git a/STATUS/progress-log.md b/STATUS/progress-log.md new file mode 100644 index 00000000..b692046a --- /dev/null +++ b/STATUS/progress-log.md @@ -0,0 +1,52 @@ +# Progress Update Log + +This file tracks module progress changes with timestamps and descriptions. + +## 2025-10-29 - Comprehensive Progress Assessment + +**Major Milestone:** Completed comprehensive codebase assessment and progress report + +### Completed Systems (70-80%) +- **Authentication & User System (70%)**: JWT-based auth, signup/login, session management, progressive profiling, multi-step onboarding, profile APIs +- **Database Infrastructure (80%)**: PostgreSQL schema with users/sessions/activity, OAuth provider fields, indexed queries +- **Infrastructure & DevOps (50%)**: Next.js 14 monorepo, Vercel config, VPS deployment, production environment, CI workflows + +### In Progress (20-60%) +- **Core Application Pages (40%)**: signup, login, dashboard, onboarding, profile, bridge, design showcase +- **Documentation (60%)**: manifesto, operations playbook, CI/CD docs, auth system docs, PR workflows +- **Support Points & Reputation (20%)**: Initial structure planned +- **Design System (20%)**: Warm minimalism philosophy, basic Tailwind setup + +### Not Started (0%) +- UI System (shadcn/ui, design tokens, dark mode) +- OAuth Integration (Google, Facebook, Bluesky, Mastodon handlers) +- Groups & Organizations +- Forum/Deliberation +- Proposals & Governance +- Search & Tags +- Notifications & Inbox +- Social Economy primitives +- All Path-specific features +- Observability & Security (error boundaries, logging, monitoring) + +### Key Blockers Identified +1. OAuth strategy decision (NextAuth vs custom) +2. Federation design for groups +3. Secret storage strategy +4. UI framework confirmation (shadcn/ui) +5. Moderation framework definition + +### Next Priority Steps +1. Complete OAuth integration (2 weeks) +2. Install shadcn/ui and build core UI components (2 weeks) +3. Implement groups & basic forum (2 weeks) +4. Add proposals/voting system (2 weeks) +5. Polish onboarding and search (2 weeks) + +**Estimated MVP Date:** Late January 2026 (~10-12 weeks) + +--- + +## Previous Updates + +- **2025-10-28 03:45:55 UTC** - scaffold: 10% - Created bridge scaffold with UI component and route diff --git a/STATUS/progress-report.md b/STATUS/progress-report.md new file mode 100644 index 00000000..eea1f83a --- /dev/null +++ b/STATUS/progress-report.md @@ -0,0 +1,568 @@ +# TogetherOS — What We Finished & What Is Left (v2) + +**Last Updated:** 2025-10-29 +**Status:** Early Development Phase (Seed Stage) +**Current Branch:** claude-yolo (clean) + +--- + +## WHAT WE FINISHED + +### 1. Authentication & User System (70% Complete) + +#### Completed: +- JWT-based authentication with bcrypt password hashing (10 rounds) +- User signup flow with automatic login (/api/auth/signup) +- User login with password verification (/api/auth/login) +- Session management with 7-day HttpOnly cookies +- Logout functionality (/api/auth/logout) +- Progressive user profiling system (minimal intake -> full profile) +- Multi-step onboarding flow +- Profile management APIs (GET/PATCH /api/profile) +- User activity logging system +- Session storage in database with expiry tracking + +#### Files: +- lib/auth/session.ts - JWT session management +- lib/auth/middleware.ts - Auth middleware +- lib/db/users.ts - User database operations +- apps/web/app/api/auth/* - Auth API routes +- apps/web/app/signup/page.tsx - Signup page +- apps/web/app/login/page.tsx - Login page + +#### Still Needed: +- OAuth provider implementations (Google, Facebook, Bluesky, Mastodon) +- Email verification flow +- Password reset functionality +- Two-factor authentication +- Rate limiting on auth endpoints + +--- + +### 2. Database Infrastructure (80% Complete) + +#### Completed: +- PostgreSQL schema with users, sessions, and user_activity tables +- Progressive profiling fields (email -> name/username -> bio/avatar -> location -> paths/skills) +- OAuth provider ID fields (google_id, facebook_id, bluesky_handle, mastodon_handle, instagram_id) +- OAuth auto-capture fields (oauth_display_name, oauth_avatar_url, oauth_locale, oauth_verified) +- Full OAuth profile storage (oauth_raw_profile JSONB) +- Onboarding progress tracking (onboarding_step, onboarding_completed_at) +- Cooperation paths JSONB array (8 canonical paths) +- Skills and offers/seeking arrays +- Indexed queries for performance +- Auto-updating updated_at timestamps +- Soft delete support (deleted_at) + +#### Files: +- db/schema.sql - Complete database schema + +#### Still Needed: +- Tables for groups, organizations, proposals, votes +- Forum/deliberation tables (topics, posts, comments) +- Social economy tables (mutual aid, timebank, marketplace) +- Support points and reputation tables +- Notifications and inbox tables +- Media/file storage tables +- Database migration system +- Backup and recovery procedures + +--- + +### 3. Core Application Pages (40% Complete) + +#### Completed: +- /signup - User registration page +- /login - Authentication page +- /dashboard - User dashboard (DashboardClient.tsx) +- /onboarding - Multi-step onboarding (OnboardingClient.tsx) +- /profile - Profile management (ProfileClient.tsx) +- /bridge - TogetherOS introduction/chat interface +- /design - Design system showcase +- Root layout with navigation structure + +#### Files: +- apps/web/app/signup/page.tsx +- apps/web/app/login/page.tsx +- apps/web/app/dashboard/page.tsx & DashboardClient.tsx +- apps/web/app/onboarding/page.tsx & OnboardingClient.tsx +- apps/web/app/profile/page.tsx & ProfileClient.tsx +- apps/web/app/bridge/page.tsx +- apps/web/app/design/page.tsx +- apps/web/app/layout.tsx + +#### Still Needed: +- Groups & organizations pages +- Forum/deliberation interface +- Proposals and voting UI +- Search interface +- Notifications inbox +- Social economy pages (mutual aid, timebank, marketplace) +- Path-specific pages (8 paths x multiple pages each) +- Settings and preferences pages +- Admin/moderation interfaces + +--- + +### 4. Infrastructure & DevOps (50% Complete) + +#### Completed: +- Next.js 14 monorepo with workspaces (apps/web, packages/ui) +- TypeScript configuration +- VPS deployment scripts and configuration for coopeverything.org +- Production environment variables (.env.production) +- Multiple GitHub Actions workflows: + - ci_docs.yml - Markdown linting and link checking + - lint.yml - Code linting + - smoke.yml - Smoke tests + - auto-progress-update.yml - Automatic progress tracking + - sync-github-project.yml - GitHub project sync + - deploy.yml - Deployment automation +- Database connection pooling (pg package) +- Environment variable structure + +#### Files: +- .github/workflows/* - CI/CD workflows +- scripts/* - Deployment and utility scripts +- scripts/deploy-coopeverything.sh - VPS deployment script +- package.json - Monorepo configuration + +#### Still Needed: +- Dev container completion +- Docker/docker-compose setup +- Staging environment +- Automated testing suite (unit, integration, e2e) +- Performance monitoring +- Error tracking (e.g., Sentry) +- Logging infrastructure +- CDN configuration +- Database backup automation +- SSL/TLS certificate automation + +--- + +### 5. Documentation (60% Complete) + +#### Completed: +- Comprehensive manifesto (docs/Manifesto.md) +- Operations playbook (docs/OPERATIONS.md) +- CI/CD playbook (docs/CI/Actions_Playbook.md) +- Authentication system documentation (docs/auth/authentication-system.md) +- OAuth data mapping guide (docs/auth/oauth-data-mapping.md) +- PR checklist and workflow (docs/dev/pr-checklist.md) +- Status tracking system (docs/STATUS_v2.md) +- Progress log (STATUS/progress-log.md) +- 8 Cooperation Paths defined canonically +- Taxonomy and keywords documentation +- README with quickstart +- AGENTS.md for contributor agents + +#### Files: +- docs/* - All documentation +- README.md - Project overview +- OPERATIONS.md - Operations guide + +#### Still Needed: +- API documentation +- Component documentation +- Database schema documentation (beyond inline comments) +- Deployment runbooks +- Security documentation +- User guides +- Contributor tutorials +- Architecture decision records (ADRs) +- Changelog maintenance + +--- + +### 6. Design System (20% Complete) + +#### Completed: +- "Warm minimalism" design philosophy documented +- Basic Tailwind CSS setup +- Design showcase page (/design) + +#### Files: +- apps/web/app/design/page.tsx +- docs/design/system.md + +#### Still Needed: +- shadcn/ui installation and configuration +- Design tokens system (colors, spacing, typography) +- Typography scale definition +- Component library (buttons, forms, cards, modals, etc.) +- Dark mode implementation +- Icon system +- Animation guidelines +- Responsive breakpoints +- Accessibility guidelines (WCAG AA compliance) + +--- + +### 7. UI Components (10% Complete) + +#### Completed: +- BridgeChat component (packages/ui/src/bridge/BridgeChat.tsx) +- Basic client components for dashboard, onboarding, profile + +#### Files: +- packages/ui/src/bridge/BridgeChat.tsx + +#### Still Needed: +- Complete component library +- Form components with validation +- Navigation components +- Layout components +- Data display components (tables, lists, cards) +- Feedback components (toasts, modals, alerts) +- Loading states and skeletons +- Empty states +- Error boundaries + +--- + +## WHAT IS LEFT (Priority Order) + +### CRITICAL PATH (Must-Have for MVP) + +#### 1. OAuth Integration (2 weeks) +**Priority:** HIGH - Critical for user acquisition + +Tasks: +- [ ] Decide on OAuth library (NextAuth.js vs custom) +- [ ] Implement Google OAuth handler (lib/auth/oauth/google.ts) +- [ ] Implement Facebook OAuth handler (lib/auth/oauth/facebook.ts) +- [ ] Implement Bluesky OAuth handler (lib/auth/oauth/bluesky.ts) +- [ ] Implement Mastodon OAuth handler (lib/auth/oauth/mastodon.ts) +- [ ] OAuth provider selection UI on signup/login pages +- [ ] OAuth profile data capture and mapping +- [ ] OAuth account linking for existing users +- [ ] Error handling for OAuth failures + +Blockers: +- Need to decide OAuth strategy (NextAuth vs custom) +- Need OAuth app credentials from providers + +--- + +#### 2. UI System & Component Library (2-3 weeks) +**Priority:** HIGH - Needed for all feature development + +Tasks: +- [ ] Install and configure shadcn/ui +- [ ] Define design tokens (colors, spacing, typography) +- [ ] Create color palette (primary, secondary, accent, neutral) +- [ ] Define typography scale (headings, body, labels) +- [ ] Set up dark mode with theme provider +- [ ] Create base layout primitives (Container, Grid, Stack) +- [ ] Install and configure icon system (lucide-react or similar) +- [ ] Create button variants (primary, secondary, ghost, destructive) +- [ ] Create form components (Input, Textarea, Select, Checkbox, Radio) +- [ ] Create card components +- [ ] Create modal/dialog components +- [ ] Create toast notification system +- [ ] Document all components in Storybook or design showcase + +Blockers: +- None (ready to start) + +--- + +#### 3. Groups & Organizations (2 weeks) +**Priority:** MEDIUM-HIGH - Core social feature + +Tasks: +- [ ] Design database schema for groups and organizations +- [ ] Create group model and CRUD operations +- [ ] Implement group creation flow +- [ ] Implement group discovery/browse page +- [ ] Implement join/leave group functionality +- [ ] Create group detail page +- [ ] Add group membership management +- [ ] Add group settings and configuration +- [ ] Design federation handles system (future-proofing) + +Blockers: +- Federation design needs specification + +--- + +#### 4. Forum & Deliberation (2 weeks) +**Priority:** MEDIUM-HIGH - Core collaboration feature + +Tasks: +- [ ] Design database schema for topics, posts, comments +- [ ] Create topic list page +- [ ] Create topic detail page with posts +- [ ] Implement post composer with rich text +- [ ] Add comment threading +- [ ] Add summarization hooks (AI-assisted) +- [ ] Implement empathy tools (active listening prompts, etc.) +- [ ] Add moderation framework +- [ ] Create moderation interface + +Blockers: +- Moderation rules need definition +- Summarization integration needs design + +--- + +#### 5. Proposals & Governance (2 weeks) +**Priority:** MEDIUM - Core governance feature + +Tasks: +- [ ] Design database schema for proposals, votes, reviews +- [ ] Create proposal creation form +- [ ] Implement proposal detail page +- [ ] Add evidence and options structure +- [ ] Implement voting mechanism (simple, ranked choice, etc.) +- [ ] Create vote casting UI +- [ ] Add review and comment system +- [ ] Implement quorum rules +- [ ] Add proposal status workflow (draft, active, passed, rejected) +- [ ] Create proposal list/browse page + +Blockers: +- Ballot types need specification +- Quorum rules need definition + +--- + +#### 6. Support Points & Reputation (1-2 weeks) +**Priority:** MEDIUM - Nice to have for MVP + +Current: 20% complete (initial structure) + +Tasks: +- [ ] Design database schema for points and badges +- [ ] Implement 100-point wallet system +- [ ] Create point allocation UI +- [ ] Add per-idea allocation limits +- [ ] Implement anti-abuse mechanisms (rate limiting, caps) +- [ ] Create badge system +- [ ] Design badge award criteria +- [ ] Add points history/ledger view +- [ ] Create leaderboard (if desired) + +Blockers: +- Anti-abuse strategy needs refinement + +--- + +#### 7. Search & Discovery (1-2 weeks) +**Priority:** MEDIUM - Important for usability + +Tasks: +- [ ] Decide on search implementation (client-side vs server-side) +- [ ] Implement global search API endpoint +- [ ] Create search UI with autocomplete +- [ ] Add Path/keyword filters +- [ ] Implement tag facet filtering +- [ ] Add search to groups, proposals, forum topics +- [ ] Optimize search performance (indexing strategy) +- [ ] Add search analytics + +Blockers: +- Search technology decision (PostgreSQL full-text, Elasticsearch, etc.) + +--- + +### POST-MVP FEATURES + +#### 8. Notifications & Inbox (1-2 weeks) +**Priority:** LOW for MVP, HIGH for v1.1 + +Tasks: +- [ ] Design database schema for notifications +- [ ] Create notification event system +- [ ] Implement in-app toast notifications +- [ ] Create inbox page +- [ ] Add mention notifications +- [ ] Add proposal update notifications +- [ ] Add group activity notifications +- [ ] Implement email digest batching +- [ ] Add notification preferences + +--- + +#### 9. Social Economy Module (3-4 weeks) +**Priority:** POST-MVP + +Tasks: +- [ ] Design database schema for mutual aid, timebank, marketplace +- [ ] Create mutual aid request/offer board +- [ ] Implement request fulfillment workflow +- [ ] Create timebank system (hours tracking) +- [ ] Implement time credit transfers +- [ ] Create fair marketplace listings +- [ ] Add listing creation and browsing +- [ ] Design payment integration (future) +- [ ] Add Social Horizon crypto integration (future) + +Blockers: +- Payment provider decision +- Crypto integration design + +--- + +#### 10. Path-Specific Features (12+ weeks total) +**Priority:** POST-MVP + +Each of the 8 Cooperation Paths needs specific features: + +**Collaborative Education:** +- Cohort creation and management +- Skill tree visualization +- Lesson runner/player +- Certification system + +**Collective Governance:** +- Advanced proposal types +- Complex ballot systems +- Delegation mechanisms + +**Community Connection:** +- Interactive map of groups/events +- Event creation and RSVP +- Group directory with filters + +**Collaborative Media & Culture:** +- Media upload and hosting +- Gallery/showcase pages +- Collaborative projects + +**Common Wellbeing:** +- Peer support board templates +- Resource sharing +- Care networks + +**Social Economy:** +- (See module #9 above) + +**Cooperative Technology:** +- OSS project integrations +- Dev tools and utilities +- Code collaboration features + +**Common Planet:** +- Impact metrics tracking +- Project cards with progress +- Climate-positive logistics + +--- + +#### 11. Observability & Security (2-3 weeks) +**Priority:** ONGOING + +Tasks: +- [ ] Implement error boundary components +- [ ] Set up centralized logging (Winston, Pino, or similar) +- [ ] Add uptime monitoring +- [ ] Integrate error tracking (Sentry or similar) +- [ ] Implement rate limiting on all API routes +- [ ] Add CSRF protection +- [ ] Implement security headers (helmet.js) +- [ ] Create threat model document +- [ ] Audit PII handling and add encryption +- [ ] Set up secrets management (Vault or similar) +- [ ] Conduct security audit +- [ ] Add API request logging (with PII redaction) +- [ ] Create alerting system for critical errors + +Blockers: +- Monitoring provider decision + +--- + +## KEY BLOCKERS & DECISIONS NEEDED + +1. **OAuth Strategy** + - Decision: NextAuth.js vs custom implementation + - Impact: 2 weeks of development time + - Recommendation: NextAuth.js for speed, custom for flexibility + +2. **Federation Design** + - Need: Specification for federation IDs and claims for groups + - Impact: Groups module architecture + - Timeline: Need decision before starting groups module + +3. **Secret Storage** + - Decision: Environment variables vs Vault vs other + - Impact: Security posture + - Current: Using .env files (not suitable for production) + +4. **UI Framework** + - Decision: Confirm shadcn/ui as component library + - Impact: All UI development + - Recommendation: Yes (modern, accessible, customizable) + +5. **Moderation Framework** + - Need: Define empathy-first moderation rules + - Impact: Forum and proposal systems + - Timeline: Need before forum launch + +6. **Search Technology** + - Decision: PostgreSQL full-text vs Elasticsearch vs other + - Impact: Search performance and features + - Recommendation: Start with PostgreSQL, migrate if needed + +--- + +## METRICS + +- **Total Modules Defined:** 30 +- **Modules Started:** 6 (20%) +- **Modules Complete:** 0 (0% - all partial) +- **Average Progress:** ~15% across all modules +- **Lines of Code:** ~5,000 (estimate) +- **Database Tables:** 3 (users, sessions, user_activity) +- **API Routes:** ~8 +- **Pages:** 7 +- **Components:** ~10 + +--- + +## TIMELINE ESTIMATE + +**Current Phase:** Seed (10-20% complete) +**Target MVP:** Late January 2026 (~10-12 weeks) +**Target v1.0:** March 2026 (~16-20 weeks) + +### Recommended Sprint Schedule: + +**Sprint 1-2 (Weeks 1-2):** OAuth Integration +**Sprint 3-4 (Weeks 3-4):** UI System & Components +**Sprint 5-6 (Weeks 5-6):** Groups & Organizations +**Sprint 7-8 (Weeks 7-8):** Forum & Deliberation +**Sprint 9-10 (Weeks 9-10):** Proposals & Governance +**Sprint 11-12 (Weeks 11-12):** Polish, Testing, MVP Launch + +Post-MVP: +**Sprint 13-14:** Search & Discovery +**Sprint 15-16:** Notifications & Inbox +**Sprint 17-20:** Social Economy Module +**Sprint 21+:** Path-specific features + +--- + +## RECENT COMMITS (Last 10) + +1. docs: fix README documentation links and make them clickable (#105) +2. feat(deploy): add production environment configuration +3. docs(auth): add comprehensive authentication system documentation +4. feat(auth): complete user authentication and onboarding system +5. fix(auth): add database dependencies +6. fix(auth): use path alias for imports +7. feat(auth): implement user signup system +8. feat(auth): add OAuth auto-capture fields +9. feat(db): add user schema with progressive profiling +10. style(bridge): improve spacing and alignment + +--- + +**Report Generated:** 2025-10-29 +**Next Update:** After major milestone completion + +--- + +END OF REPORT diff --git a/apps/web/app/api/status/route.ts b/apps/web/app/api/status/route.ts new file mode 100644 index 00000000..52c66e4d --- /dev/null +++ b/apps/web/app/api/status/route.ts @@ -0,0 +1,120 @@ +// apps/web/app/api/status/route.ts +import { NextResponse } from 'next/server'; +import { readFile } from 'fs/promises'; +import { join } from 'path'; + +interface Module { + key: string; + name: string; + progress: number; + category: 'core' | 'path' | 'devex'; +} + +// Module name mapping +const moduleNames: Record = { + // Core modules + scaffold: 'Monorepo & Scaffolding', + ui: 'UI System', + auth: 'Identity & Auth', + profiles: 'Profiles', + groups: 'Groups & Orgs', + forum: 'Forum / Deliberation', + governance: 'Proposals & Decisions', + 'social-economy': 'Social Economy Primitives', + reputation: 'Support Points & Reputation', + onboarding: 'Onboarding (Bridge)', + search: 'Search & Tags', + notifications: 'Notifications & Inbox', + 'docs-hooks': 'Docs Site Hooks', + observability: 'Observability', + security: 'Security & Privacy', + + // Path modules + 'path-education': 'Collaborative Education', + 'path-governance': 'Collective Governance', + 'path-community': 'Community Connection', + 'path-media': 'Collaborative Media & Culture', + 'path-wellbeing': 'Common Wellbeing', + 'path-economy': 'Social Economy', + 'path-technology': 'Cooperative Technology', + 'path-planet': 'Common Planet', + + // DevEx modules + devcontainer: 'Dev Container', + 'ci-lint': 'CI Lint', + 'ci-docs': 'CI Docs', + 'ci-smoke': 'CI Smoke Tests', + deploy: 'Deploy', + secrets: 'Secrets', +}; + +// Determine category from module key +function getModuleCategory(key: string): 'core' | 'path' | 'devex' { + if (key.startsWith('path-')) return 'path'; + if (['devcontainer', 'ci-lint', 'ci-docs', 'ci-smoke', 'deploy', 'secrets'].includes(key)) { + return 'devex'; + } + return 'core'; +} + +export async function GET() { + try { + // Read STATUS_v2.md from the repo root + const statusFilePath = join(process.cwd(), '..', '..', 'docs', 'STATUS_v2.md'); + const content = await readFile(statusFilePath, 'utf-8'); + + // Extract progress markers using regex + // Pattern: + const progressRegex = //g; + const modules: Module[] = []; + let match; + + while ((match = progressRegex.exec(content)) !== null) { + const key = match[1]; + const progress = parseInt(match[2], 10); + const name = moduleNames[key]; + + if (name) { + modules.push({ + key, + name, + progress, + category: getModuleCategory(key), + }); + } + } + + // Calculate statistics + const stats = { + overall: Math.round( + modules.reduce((sum, m) => sum + m.progress, 0) / modules.length + ), + total: modules.length, + started: modules.filter((m) => m.progress > 0).length, + completed: modules.filter((m) => m.progress === 100).length, + }; + + // Group by category + const grouped = { + core: modules.filter((m) => m.category === 'core'), + path: modules.filter((m) => m.category === 'path'), + devex: modules.filter((m) => m.category === 'devex'), + }; + + return NextResponse.json({ + success: true, + stats, + modules: grouped, + lastUpdated: new Date().toISOString(), + }); + } catch (error) { + console.error('Failed to read STATUS_v2.md:', error); + return NextResponse.json( + { + success: false, + error: 'Failed to load progress data', + }, + { status: 500 } + ); + } +} diff --git a/apps/web/app/status/StatusClient.tsx b/apps/web/app/status/StatusClient.tsx new file mode 100644 index 00000000..48383a3e --- /dev/null +++ b/apps/web/app/status/StatusClient.tsx @@ -0,0 +1,455 @@ +'use client'; + +import { useEffect, useState } from 'react'; + +interface Module { + key: string; + name: string; + progress: number; + category: 'core' | 'path' | 'devex'; +} + +interface StatusData { + success: boolean; + stats: { + overall: number; + total: number; + started: number; + completed: number; + }; + modules: { + core: Module[]; + path: Module[]; + devex: Module[]; + }; + lastUpdated: string; +} + +// Get status color based on progress +const getProgressColor = (progress: number): string => { + if (progress === 0) return 'bg-slate-200 dark:bg-slate-700'; + if (progress < 30) return 'bg-gradient-to-r from-rose-400 to-pink-500'; + if (progress < 70) return 'bg-gradient-to-r from-amber-400 to-orange-500'; + return 'bg-gradient-to-r from-emerald-400 to-green-500'; +}; + +// Get status text based on progress +const getStatusText = (progress: number): string => { + if (progress === 0) return 'Not Started'; + if (progress < 30) return 'Early Stage'; + if (progress < 70) return 'In Progress'; + if (progress < 100) return 'Nearly Complete'; + return 'Complete'; +}; + +// Get ring color for progress circle +const getRingColor = (progress: number): string => { + if (progress === 0) return 'ring-slate-200 dark:ring-slate-700'; + if (progress < 30) return 'ring-rose-400'; + if (progress < 70) return 'ring-amber-400'; + return 'ring-emerald-400'; +}; + +interface ModuleCardProps { + module: Module; +} + +function ModuleCard({ module }: ModuleCardProps) { + const progressColor = getProgressColor(module.progress); + const statusText = getStatusText(module.progress); + const ringColor = getRingColor(module.progress); + + return ( +
+ {/* Glow effect on hover */} +
+ +
+
+
+

+ {module.name} +

+

+ #{module.key} +

+
+
+ + {module.progress}% + +
+
+ + {/* Progress bar */} +
+
+
+
+
+ + {/* Status badge */} +
+ + {statusText} + + + {module.progress > 0 && module.progress < 100 && '🚧'} + {module.progress === 0 && '⏳'} + {module.progress === 100 && '✅'} + +
+
+
+ ); +} + +interface ModuleSectionProps { + title: string; + description: string; + modules: Module[]; + icon: string; +} + +function ModuleSection({ title, description, modules, icon }: ModuleSectionProps) { + const avgProgress = + modules.length > 0 + ? Math.round(modules.reduce((sum, m) => sum + m.progress, 0) / modules.length) + : 0; + const started = modules.filter((m) => m.progress > 0).length; + + return ( +
+
+
+
+ {icon} +

+ {title} +

+
+
+
+ {avgProgress}% +
+
average
+
+
+

+ {description}{' '} + + {started}/{modules.length} started + +

+
+
+ {modules.map((module, idx) => ( +
+ +
+ ))} +
+
+ ); +} + +function LoadingSkeleton() { + return ( +
+
+
+ {[...Array(6)].map((_, i) => ( +
+ ))} +
+
+ ); +} + +export default function StatusClient() { + const [data, setData] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + + useEffect(() => { + async function fetchStatus() { + try { + const response = await fetch('/api/status'); + if (!response.ok) { + throw new Error('Failed to fetch status data'); + } + const json = await response.json(); + setData(json); + } catch (err) { + setError(err instanceof Error ? err.message : 'Unknown error'); + } finally { + setLoading(false); + } + } + + fetchStatus(); + }, []); + + if (loading) { + return ( +
+
+
+

+ TogetherOS Progress +

+

Loading status data...

+
+
+
+ +
+
+ ); + } + + if (error || !data?.success) { + return ( +
+
+
⚠️
+

+ Failed to Load Status +

+

{error}

+
+
+ ); + } + + return ( +
+ {/* Floating orbs background effect */} +
+
+
+
+ + {/* Header */} +
+
+
+
+

+ TogetherOS Progress +

+

+ + Live tracking • Auto-updated via GitHub Actions +

+
+ + + + + View on GitHub + + + + +
+
+
+ + {/* Overall Stats */} +
+
+ {/* Animated background */} +
+ +
+
+
+
+ Overall Progress +
+
+ {data.stats.overall}% +
+
+
+
+
+
+
+ Total Modules +
+
+ {data.stats.total} +
+
+ Across all categories +
+
+
+
+ In Progress +
+
+ {data.stats.started} +
+
+ Active development +
+
+
+
+ Completed +
+
+ {data.stats.completed} +
+
+ Ready for production +
+
+
+
+
+ + {/* Module Sections */} + + + + + + + {/* Footer */} +
+
+

+ Progress data synced from{' '} + + docs/STATUS_v2.md + +

+

+ Automated by{' '} + + auto-progress-update.yml + {' '} + GitHub Action +

+

+ Last updated: {new Date(data.lastUpdated).toLocaleString()} +

+
+
+
+ + {/* Custom animations */} + +
+ ); +} diff --git a/apps/web/app/status/page.tsx b/apps/web/app/status/page.tsx new file mode 100644 index 00000000..e38f0c6a --- /dev/null +++ b/apps/web/app/status/page.tsx @@ -0,0 +1,12 @@ +// apps/web/app/status/page.tsx +import { Metadata } from 'next'; +import StatusClient from './StatusClient'; + +export const metadata: Metadata = { + title: 'Progress Status - TogetherOS', + description: 'Track development progress across all TogetherOS modules', +}; + +export default function StatusPage() { + return ; +} diff --git a/docs/dev/progress-tracking-automation.md b/docs/dev/progress-tracking-automation.md new file mode 100644 index 00000000..07da760f --- /dev/null +++ b/docs/dev/progress-tracking-automation.md @@ -0,0 +1,408 @@ +# Progress Tracking Automation + +**Version:** 1.0 +**Last Updated:** 2025-10-29 + +## Overview + +TogetherOS has an automated progress tracking system that keeps project status up-to-date across multiple documentation files. This guide explains how the system works and how to use it. + +## Progress Tracking Files + +### 1. `docs/STATUS_v2.md` +**Purpose:** Technical status dashboard with module-by-module progress percentages + +**Format:** Markdown table with HTML comment markers for automation +```markdown +| **Identity & Auth** | ... | 70% | ... | +``` + +**Update Method:** Automated via scripts or manual edit + +### 2. `STATUS/progress-log.md` +**Purpose:** Append-only chronological log of progress milestones + +**Format:** Timestamped entries with descriptions +```markdown +## 2025-10-29 - Milestone Name +- **auth:** 70% - Completed JWT authentication +``` + +**Update Method:** Appended by automation scripts + +### 3. `STATUS/progress-report.md` +**Purpose:** Comprehensive progress report (what's done, what's left, blockers, timeline) + +**Format:** Structured text document with sections +- What We Finished (by module) +- What Is Left (prioritized task list) +- Blockers & Decisions +- Metrics & Timeline + +**Update Method:** Manual updates after major milestones + +--- + +## Automation Tools + +### Script 1: `update-progress.sh` + +**Purpose:** Update individual module progress percentages + +**Usage:** +```bash +# Set a module to a specific percentage +./scripts/update-progress.sh auth 70 + +# Increment a module's progress +./scripts/update-progress.sh auth +5 + +# With description (logs to progress-log.md) +./scripts/update-progress.sh auth 75 "Completed OAuth integration" +``` + +**What it does:** +1. Updates the HTML comment marker in `docs/STATUS_v2.md` +2. Updates the visible percentage in the table +3. If description provided, appends entry to `STATUS/progress-log.md` + +**Module Keys:** +``` +Core Modules: + scaffold, ui, auth, profiles, groups, forum, governance, + social-economy, reputation, onboarding, search, notifications, + docs-hooks, observability, security + +Path Modules: + path-education, path-governance, path-community, path-media, + path-wellbeing, path-economy, path-technology, path-planet + +DevEx Modules: + devcontainer, ci-lint, ci-docs, ci-smoke, deploy, secrets +``` + +--- + +### Script 2: `generate-progress-report.sh` + +**Purpose:** Generate comprehensive progress snapshot with project metrics + +**Usage:** +```bash +# Generate report with default milestone name +./scripts/generate-progress-report.sh + +# Generate report with custom milestone description +./scripts/generate-progress-report.sh "Completed OAuth integration" +``` + +**What it does:** +1. Extracts all module progress percentages from `STATUS_v2.md` +2. Counts TypeScript files, pages, API routes, database tables, components +3. Gathers recent commit history +4. Appends detailed milestone entry to `STATUS/progress-log.md` +5. Displays summary statistics + +**Output Example:** +``` +============================================ +Progress Summary +============================================ +Authentication: 70% +Scaffolding: 40% +UI System: 20% +... +Average Progress: 35% +TypeScript Files: 42 +Pages: 7 +API Routes: 8 +Database Tables: 3 +UI Components: 10 +``` + +--- + +### GitHub Action: `auto-progress-update.yml` + +**Purpose:** Automatically update progress when PRs are merged + +**Trigger:** When a PR is merged to `claude-yolo` or `main` + +**How to use in PRs:** + +Add progress markers in your PR description: +```markdown +## Progress Updates + +progress:auth=+10 +progress:onboarding=+5 +``` + +**Syntax:** +- `progress:MODULE_KEY=XX` - Set to specific percentage +- `progress:MODULE_KEY=+XX` - Increment by percentage + +**What it does:** +1. Extracts progress markers from PR body +2. Calls `update-progress.sh` for each update +3. Commits changes back to the branch +4. Uses `[skip ci]` to prevent infinite loops + +**Example PR Description:** +```markdown +## What & Why +Completed OAuth integration with Google and Facebook providers. + +## Progress Updates +progress:auth=+15 + +## Touchpoints +- lib/auth/oauth/google.ts +- lib/auth/oauth/facebook.ts +- apps/web/app/api/auth/oauth/route.ts + +## Proof +LINT=OK +SMOKE=OK +``` + +--- + +## Manual Workflows + +### After Completing a Major Feature + +1. **Update module progress:** + ```bash + ./scripts/update-progress.sh auth 75 "OAuth integration complete" + ``` + +2. **Generate progress report:** + ```bash + ./scripts/generate-progress-report.sh "OAuth integration milestone" + ``` + +3. **Update comprehensive report (if major milestone):** + - Manually edit `STATUS/progress-report.md` + - Update the "What We Finished" section for the module + - Update blockers if resolved + - Update timeline if needed + +4. **Commit changes:** + ```bash + git add docs/STATUS_v2.md STATUS/progress-log.md + git commit -m "docs(status): update progress for auth module" + ``` + +### Weekly Progress Review + +Run weekly to track overall progress: + +```bash +./scripts/generate-progress-report.sh "Week of $(date +%Y-%m-%d)" +``` + +This creates a timestamped snapshot in `progress-log.md` for historical tracking. + +--- + +## Git Hooks (Optional) + +### Post-Commit Hook + +To automatically generate progress snapshots after significant commits: + +Create `.git/hooks/post-commit`: + +```bash +#!/usr/bin/env bash + +# Only run on commits that mention "feat" or "fix" +COMMIT_MSG=$(git log -1 --pretty=%B) + +if [[ "${COMMIT_MSG}" =~ ^(feat|fix) ]]; then + echo "Generating progress snapshot..." + ./scripts/generate-progress-report.sh "Auto: ${COMMIT_MSG:0:50}" +fi +``` + +Make it executable: +```bash +chmod +x .git/hooks/post-commit +``` + +**Note:** This is optional and may add overhead to commits. Consider if it's useful for your workflow. + +--- + +## Best Practices + +### 1. Update Progress Incrementally + +Don't wait for 100% completion. Update progress as you make meaningful increments: +- Small feature completed: +5-10% +- Significant milestone: +15-25% +- Module fully functional: 80-100% + +### 2. Use Descriptions + +Always provide descriptions when updating progress: +```bash +# Good +./scripts/update-progress.sh auth 70 "JWT auth and session management complete" + +# Less helpful +./scripts/update-progress.sh auth 70 +``` + +### 3. Include Progress Markers in PRs + +Make it a habit to include `progress:MODULE=+XX` in PR descriptions so the automation can track changes. + +### 4. Generate Reports at Milestones + +Run `generate-progress-report.sh` at significant milestones: +- End of each sprint/week +- Major feature completion +- Before demos or releases +- After completing multiple modules + +### 5. Update Comprehensive Report Quarterly + +The `progress-report.md` file is detailed and should be updated: +- At major milestones (MVP, beta, v1.0) +- When blockers are resolved +- When timeline changes significantly +- Quarterly for comprehensive review + +--- + +## Integration with CI/CD + +### Automatic Checks + +The progress tracking system integrates with CI: + +1. **Lint checks:** Ensure `STATUS_v2.md` is well-formed +2. **Docs validation:** Links and formatting checks +3. **Progress markers:** PR checks validate progress syntax + +### Status Badges (Future) + +Consider adding progress badges to README: + +```markdown +![Auth Progress](https://img.shields.io/badge/Auth-70%25-yellow) +![UI Progress](https://img.shields.io/badge/UI-20%25-red) +``` + +Can be auto-generated from `STATUS_v2.md` markers. + +--- + +## Troubleshooting + +### Script Not Finding Module + +**Error:** `Module key 'xyz' not found` + +**Solution:** Check available module keys: +```bash +grep -oP " XX% +if grep -q " [0-9]*%/ ${NEW_PERCENTAGE}%/g" "${STATUS_FILE}" + echo "✓ Updated ${MODULE_KEY} to ${NEW_PERCENTAGE}% in ${STATUS_FILE}" +else + echo "ERROR: Module key '${MODULE_KEY}' not found in ${STATUS_FILE}" >&2 + echo "Available keys:" >&2 + grep -oP "