blob: 5026b06b5547b0722eaeaf3f8a4e5c4b186bb45a (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
# Punchcard Development Guide
## Project Overview
Punchcard is a CLI time tracking tool for freelancers and consultants, built in Go with SQLite storage.
## Architecture
### Core Components
- **CLI Interface**: spf13/cobra for command structure
- **Database**: SQLite with sqlc for type-safe queries
- **Report Generation**: Typst templates compiled to PDF
- **Storage**: Local SQLite database file
### Commands Structure
- `punch in` - Starts timer (inserts row with start_time, NULL end_time)
- `punch out` - Stops active timer (updates end_time), exits non-zero if no active timer
- `punch invoice` - Generates invoice PDF via Typst
- `punch timesheet` - Generates timesheet PDF via Typst
## Database Schema
```sql
-- Time tracking entries
CREATE TABLE time_entries (
id INTEGER PRIMARY KEY AUTOINCREMENT,
start_time DATETIME NOT NULL,
end_time DATETIME NULL,
description TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Future: client/project tables for invoicing
```
## Technology Stack
- **Language**: Go 1.21+
- **CLI Framework**: github.com/spf13/cobra
- **Database**: SQLite3
- **Query Builder**: github.com/sqlc-dev/sqlc
- **PDF Generation**: Typst (external dependency)
## File Structure
```
punchcard/
├── cmd/
│ └── punch/ # Main CLI entry point
├── internal/
│ ├── commands/ # Cobra command implementations
│ ├── database/ # Database connection and migrations
│ ├── models/ # Data models
│ ├── queries/ # sqlc generated queries
│ └── reports/ # Typst template handling
├── templates/ # Typst templates for PDF generation
├── go.mod
├── go.sum
├── README.md
└── CLAUDE.md
```
## Development Guidelines
### Database
- Use sqlc for all database interactions
- Store timestamps in UTC
- Active timer = row with NULL end_time
### CLI Design
- Follow cobra conventions
- Provide helpful error messages
- Exit codes: 0 = success, 1 = general error, 2 = no active timer
### PDF Generation
- Use Typst templates in `templates/` directory
- Invoke `typst compile` subprocess for PDF generation
- Handle Typst installation check gracefully
### Testing
- Use table-driven tests for business logic
- Test CLI commands with cobra testing utilities
- Use in-memory SQLite for test database
## Build and Run
```bash
# Build
go build -o punch cmd/punch/main.go
# Run
./punch in
./punch out
# Install locally
go install ./cmd/punch
```
## Dependencies
```bash
go get github.com/spf13/cobra
go get github.com/mattn/go-sqlite3
go get modernc.org/sqlite
```
|
