buildlog 0.1.0__py3-none-any.whl

buildlog-0.1.0.data/data/share/buildlog/template/buildlog/2026-01-01-example.md

@@ -0,0 +1,269 @@
+# Build Journal: User Authentication API
+
+**Date:** 2026-01-01
+**Duration:** 4 hours
+**Status:** Complete
+
+---
+
+## The Goal
+
+Add JWT-based authentication to our REST API. Users need to register, login, and access protected endpoints. We're using Express.js with a PostgreSQL database.
+
+This is foundational infrastructure - every future feature depends on knowing who the user is.
+
+---
+
+## What We Built
+
+### Architecture
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Client    │────▶│  Express    │────▶│  PostgreSQL │
+│             │     │  + JWT      │     │  (users)    │
+└─────────────┘     └─────────────┘     └─────────────┘
+                          │
+                    ┌─────▼─────┐
+                    │  bcrypt   │
+                    │ (hashing) │
+                    └───────────┘
+```
+
+### Components
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| POST /auth/register | Working | Creates user, returns JWT |
+| POST /auth/login | Working | Validates creds, returns JWT |
+| GET /auth/me | Working | Returns current user from token |
+| authMiddleware | Working | Protects routes |
+| User model | Working | email, password_hash, created_at |
+
+---
+
+## The Journey
+
+### Phase 1: Database Setup
+
+**What we tried:**
+Set up the users table with a simple schema.
+
+**What happened:**
+Forgot to add a unique constraint on email. Found out when registration started silently creating duplicate users.
+
+```
+ERROR: duplicate key value violates unique constraint "users_email_key"
+```
+
+Wait, no - we didn't get this error. That's the problem. Duplicates were allowed.
+
+**The fix:**
+```sql
+ALTER TABLE users ADD CONSTRAINT users_email_unique UNIQUE (email);
+```
+
+**Lesson:**
+Always add unique constraints at the database level, not just application validation.
+
+---
+
+### Phase 2: Password Hashing
+
+**What we tried:**
+Used bcrypt to hash passwords on registration.
+
+**What happened:**
+Login always failed. Spent 30 minutes debugging before realizing we were comparing the plaintext password to itself, not to the hash.
+
+```javascript
+// Wrong - comparing password to password
+const valid = await bcrypt.compare(password, password);
+
+// Right - comparing password to stored hash
+const valid = await bcrypt.compare(password, user.password_hash);
+```
+
+**The fix:**
+Actually read the bcrypt docs. `compare(plaintext, hash)` - order matters.
+
+**Lesson:**
+When auth fails silently, log what you're actually comparing (redacted).
+
+---
+
+### Phase 3: JWT Middleware
+
+**What we tried:**
+Created middleware to verify JWT and attach user to request.
+
+**What happened:**
+Tokens from yesterday stopped working. Turns out we set expiry to 1 hour but were testing with day-old tokens from our notes.
+
+```
+JsonWebTokenError: jwt expired
+```
+
+**The fix:**
+Set expiry to 7 days for development, added refresh token TODO for production.
+
+**Lesson:**
+Use short expiry in tests, longer in dev. Don't copy-paste tokens between sessions.
+
+---
+
+## Test Results
+
+### Registration
+
+**Command:**
+```bash
+curl -X POST http://localhost:3000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email": "test@example.com", "password": "secretpass123"}'
+```
+
+**Response:**
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "user": {
+    "id": 1,
+    "email": "test@example.com",
+    "created_at": "2026-01-01T10:30:00Z"
+  }
+}
+```
+
+**Result:** Pass - user created, token returned
+
+### Protected Route
+
+**Command:**
+```bash
+curl http://localhost:3000/auth/me \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+**Response:**
+```json
+{
+  "id": 1,
+  "email": "test@example.com"
+}
+```
+
+**Result:** Pass - user data returned from token
+
+---
+
+## Code Samples
+
+### Auth Middleware
+
+```javascript
+const authMiddleware = async (req, res, next) => {
+  const header = req.headers.authorization;
+  if (!header?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'No token provided' });
+  }
+
+  try {
+    const token = header.slice(7);
+    const payload = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = await User.findById(payload.userId);
+    next();
+  } catch (err) {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+};
+```
+
+This middleware extracts the JWT, verifies it, and attaches the full user object to the request. The `?.` optional chaining handles missing headers gracefully.
+
+---
+
+## What's Left
+
+- [ ] Refresh token implementation
+- [ ] Password reset flow
+- [ ] Rate limiting on auth endpoints
+- [ ] Email verification
+
+---
+
+## Cost/Performance Analysis
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| bcrypt rounds | 12 | ~250ms hash time, good balance |
+| JWT expiry | 7 days | Too long for prod, fine for dev |
+| Token size | 284 bytes | Acceptable for headers |
+
+---
+
+## AI Experience Reflection
+
+### What Worked Well
+
+- Incremental approach: got each endpoint working before moving to the next
+- Agent suggested adding the unique constraint after I described the duplicate user bug
+- Quick iteration on the curl commands for testing
+
+### What Was Frustrating
+
+- Spent too long on the bcrypt comparison bug - should have asked for help sooner
+- Context about the existing database schema was lost mid-conversation
+
+### Communication Notes
+
+- Worked best when I described the symptom ("login always fails") rather than my guess ("I think JWT is broken")
+- Breaking the work into phases helped maintain focus
+
+---
+
+## Improvements
+
+*Actionable learnings for future work.*
+
+### Architectural
+
+- Should have added database constraints BEFORE writing application code - the schema is the source of truth
+- Password hashing belongs in the User model (as a pre-save hook), not in the route handler
+
+### Workflow
+
+- Write the curl test commands FIRST, then implement to make them pass - TDD but for APIs
+- Test with fresh tokens, not ones from previous sessions
+
+### Tool Usage
+
+- Use `jwt.io` to decode tokens when debugging - faster than console.log
+- The `--verbose` flag on curl shows headers, useful for auth debugging
+
+### Domain Knowledge
+
+- bcrypt.compare() argument order is (plaintext, hash) - not obvious
+- JWT expiry is in seconds when using jsonwebtoken library, not milliseconds
+- PostgreSQL unique constraints create an index automatically - no need to add one separately
+
+---
+
+## Files Changed
+
+```
+src/
+├── routes/
+│   └── auth.js           # Register, login, me endpoints
+├── middleware/
+│   └── auth.js           # JWT verification middleware
+├── models/
+│   └── user.js           # User model with password hashing
+└── db/
+    └── migrations/
+        └── 001_users.sql # Users table with constraints
+```
+
+---
+
+*Next entry: Adding role-based access control (admin vs regular users)*

buildlog-0.1.0.data/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md

@@ -0,0 +1,114 @@
+# Build Journal System
+
+A documentation-as-code system for capturing development work as publishable content.
+
+## Philosophy
+
+1. **Write fast, not pretty** - "Refrigerator to-do list" energy
+2. **Never delete mistakes** - They're the most valuable teaching content
+3. **Include the journey** - Wrong turns > polished outcomes
+4. **AI reflection is required** - Meta-commentary on the collaboration itself
+
+## Directory Structure
+
+```
+buildlog/
+├── BUILDLOG_SYSTEM.md          # This file (system docs)
+├── _TEMPLATE.md                # Entry template
+├── 2026-01-15-runpod-deploy.md # Entries by date + slug
+├── 2026-01-16-supabase-storage.md
+└── assets/                     # Screenshots, outputs
+    ├── viking-portrait.png
+    └── error-screenshot.png
+```
+
+## Entry Template
+
+Copy `_TEMPLATE.md` for each new entry. Sections:
+
+### Required Sections
+
+| Section | Purpose |
+|---------|---------|
+| **The Goal** | What we're building and why (1-2 paragraphs) |
+| **What We Built** | Architecture, components table |
+| **The Journey** | Chronological, including fuckups |
+| **Test Results** | Actual commands, actual outputs |
+| **Code Samples** | Key snippets, not full files |
+| **AI Experience** | Reflection on collaboration |
+| **Improvements** | Actionable learnings for next time (see below) |
+
+### Optional Sections
+
+| Section | When to Include |
+|---------|-----------------|
+| **Cost Analysis** | Infrastructure/API costs involved |
+| **Performance** | Benchmarks, timing data |
+| **What's Left** | If work is incomplete |
+| **Screenshots** | When visual context helps |
+
+### The Improvements Section
+
+The **Improvements** section is critical for accumulating knowledge over time. It captures actionable learnings in four categories:
+
+| Category | What to Capture |
+|----------|-----------------|
+| **Architectural** | Better design patterns, abstractions, system structure |
+| **Workflow** | Better development process, order of operations |
+| **Tool Usage** | More effective use of available tools and capabilities |
+| **Domain Knowledge** | Technology-specific facts that apply broadly |
+
+Write these as **concrete, reusable insights** - not vague observations. Bad: "Should have planned better." Good: "Should have defined the API contract before implementing the client."
+
+These entries form the substrate for future knowledge extraction. Even raw natural language thoughts are valuable here.
+
+## When to Write Entries
+
+Write an entry when:
+- Major feature/component completed
+- Significant debugging session resolved
+- Infrastructure deployed
+- After any 2+ hour focused session
+- Before context-switching to different work
+
+## Quality Bar
+
+Each entry should be **publishable** as:
+- Envato Tuts+ tutorial ($500-750 value)
+- Manning/O'Reilly book chapter
+- Dev.to / Hashnode article
+- Internal team knowledge base
+
+This means:
+- Complete code samples that actually run
+- Real error messages, not sanitized versions
+- Honest reflection on what didn't work
+
+## AI Instructions (for CLAUDE.md)
+
+Add to your project's CLAUDE.md:
+
+```markdown
+## Build Journal
+
+After completing significant work (features, debugging sessions, deployments),
+write a build journal entry to `buildlog/YYYY-MM-DD-{slug}.md`.
+
+Use the template at `buildlog/_TEMPLATE.md`. Include:
+- The goal and what was built
+- The journey INCLUDING mistakes and wrong turns
+- Actual test commands and outputs
+- Code samples with context
+- AI Experience reflection on the collaboration
+
+Quality bar: Publishable as a $500+ tutorial article.
+
+Ask user: "Should I write a build journal entry for this work?"
+```
+
+## Maintenance
+
+- Review monthly for patterns/themes
+- Extract recurring mistakes into "lessons learned"
+- Consider publishing standout entries
+- Link related entries together

buildlog-0.1.0.data/data/share/buildlog/template/buildlog/_TEMPLATE.md

@@ -0,0 +1,162 @@
+# Build Journal: [TITLE]
+
+**Date:** [YYYY-MM-DD]
+**Duration:** [X hours]
+**Status:** [Complete | Partial | Blocked]
+
+---
+
+## The Goal
+
+[1-2 paragraphs: What are we building? Why does it matter? What problem does it solve?]
+
+---
+
+## What We Built
+
+### Architecture
+
+```
+[ASCII diagram of the system/component]
+```
+
+### Components
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| [Name] | [Working/Pending/Blocked] | [Brief note] |
+
+---
+
+## The Journey
+
+### [Phase/Hour 1]: [Title]
+
+**What we tried:**
+[Approach taken]
+
+**What happened:**
+[Actual result, including errors]
+
+```
+[Actual error message or output]
+```
+
+**The fix:**
+[What resolved it]
+
+**Lesson:**
+[One-liner takeaway]
+
+---
+
+### [Phase/Hour 2]: [Title]
+
+[Repeat pattern...]
+
+---
+
+## Test Results
+
+### [Test Name]
+
+**Command:**
+```bash
+[Actual command run]
+```
+
+**Response:**
+```json
+[Actual response received]
+```
+
+**Result:** [Pass/Fail + brief assessment]
+
+---
+
+## Code Samples
+
+### [Component/Function Name]
+
+```[language]
+[Key code snippet - not entire file, just the important parts]
+```
+
+[Brief explanation of why this code matters]
+
+---
+
+## What's Left
+
+- [ ] [Pending task 1]
+- [ ] [Pending task 2]
+- [ ] [Blocker or dependency]
+
+---
+
+## Cost/Performance Analysis
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| [Time/Cost/Memory] | [Value] | [Context] |
+
+---
+
+## AI Experience Reflection
+
+### What Worked Well
+
+[Specific things about the collaboration that were effective]
+
+### What Was Frustrating
+
+[Pain points, unclear instructions, context loss]
+
+### Communication Notes
+
+[Observations about pace, tone, information density, interruptions]
+
+---
+
+## Improvements
+
+*Actionable learnings for future work. This section accumulates knowledge that can improve agent practices over time.*
+
+### Architectural
+
+[Things to do differently in system design, abstractions, patterns]
+- [e.g., "Should have used a plugin architecture from the start instead of hardcoding backends"]
+- [e.g., "The retry logic belongs in a shared util, not duplicated across services"]
+
+### Workflow
+
+[Better approaches to the development process itself]
+- [e.g., "Run the type checker before committing, not after"]
+- [e.g., "Should have written the integration test first to clarify the API contract"]
+
+### Tool Usage
+
+[More effective ways to use available tools and capabilities]
+- [e.g., "Use grep with -C flag for context instead of reading entire files"]
+- [e.g., "The batch endpoint would have been faster than individual requests"]
+
+### Domain Knowledge
+
+[Things learned about the specific technology/domain that apply broadly]
+- [e.g., "ComfyUI node IDs must be strings, not integers"]
+- [e.g., "Supabase storage returns 400 not 404 for missing files"]
+
+---
+
+## Files Changed
+
+```
+path/to/
+├── changed/
+│   └── file.ext      # Brief description
+└── another.ext       # Brief description
+```
+
+---
+
+*Next entry: [Preview of what's coming]*