linkedin-automation-cli 1.0.0

package/docs/plans/2026-03-03-linkedin-cli-oss-publishing-design.md

@@ -0,0 +1,394 @@
+# LinkedIn CLI - Open Source Publishing Design
+
+**Date:** 2026-03-03  
+**Status:** Approved  
+**Author:** Thaddeus Liu
+
+## Overview
+
+This design document outlines the preparations needed to publish the LinkedIn CLI tool as an open source project for the community. The goal is comprehensive quality without over-engineering.
+
+## Goals
+
+1. **Code Quality** - Ensure the codebase is well-tested and maintainable
+2. **Open Source Ready** - Include all standard OSS metadata and contribution guidelines
+3. **CI/CD Pipeline** - Automated testing and builds for community confidence
+4. **Developer Experience** - Clear documentation for users and contributors
+5. **YAGNI** - Avoid over-engineering; add complexity only when needed
+
+## Non-Goals
+
+- Release automation (manual releases for now)
+- Docker containerization
+- Homebrew distribution
+- Web UI or GUI
+- Database support
+
+---
+
+## Architecture
+
+### Current Structure (No Changes)
+
+```
+linkedin-cli/
+├── cmd/linkedin/          # Entry point
+├── internal/
+│   ├── cmd/               # Cobra commands
+│   ├── config/            # Profile & rate limit persistence
+│   ├── linkedin/          # LinkedIn page interactions
+│   ├── pinchtab/          # PinchTab HTTP client
+│   └── ratelimit/         # Rate limiting logic
+├── docs/
+│   └── plans/             # Design and implementation docs
+├── go.mod
+└── README.md
+```
+
+**Decision:** Keep existing package structure - it follows Go best practices.
+
+---
+
+## Components
+
+### 1. Testing Coverage
+
+**Current State:**
+- `config/` - 4 tests ✅
+- `pinchtab/` - 3 tests ✅
+- `linkedin/` - 0 tests ❌
+- `ratelimit/` - 0 tests ❌
+
+**Required:**
+
+| Package | Tests to Add | Priority |
+|---------|-------------|----------|
+| `linkedin/validator.go` | URL validation (valid, invalid, edge cases) | High |
+| `linkedin/navigator.go` | Mock client tests for button finding, modal handling | High |
+| `ratelimit/limiter.go` | Rate limit logic, daily/weekly reset | High |
+| `ratelimit/limits.go` | Default/conservative limits verification | Medium |
+
+**Approach:**
+- Use table-driven tests for validators
+- Create mock PinchTab client for navigator tests
+- Test rate limit boundary conditions
+
+---
+
+### 2. Open Source Metadata
+
+**Files to Create:**
+
+| File | Purpose | Priority |
+|------|---------|----------|
+| `LICENSE` | MIT License | Critical |
+| `CONTRIBUTING.md` | How to contribute | High |
+| `.github/ISSUE_TEMPLATE/bug_report.md` | Bug reports | Medium |
+| `.github/ISSUE_TEMPLATE/feature_request.md` | Feature requests | Medium |
+| `.github/PULL_REQUEST_TEMPLATE.md` | PR guidelines | Medium |
+| `.github/CODEOWNERS` | Default reviewers | Low |
+
+**LICENSE Content:**
+```
+MIT License - matches PinchTab's license
+Copyright (c) 2026 Thaddeus Liu
+```
+
+**CONTRIBUTING.md Sections:**
+- Development setup (Go version, dependencies)
+- Running tests
+- Code style guidelines
+- Pull request process
+- Issue reporting guidelines
+
+---
+
+### 3. CI/CD Pipeline
+
+**GitHub Actions Workflow:**
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+      - run: go test -v ./...
+      - run: go test -coverprofile=coverage.out ./...
+      - uses: codecov/codecov-action@v4
+
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+      - run: go build -o linkedin-cli ./cmd/linkedin
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+      - uses: golangci/golangci-lint-action@v4
+```
+
+**What's NOT included:**
+- No release automation
+- No Docker builds
+- No deployment steps
+
+---
+
+### 4. Version Management
+
+**Implementation:**
+
+```go
+// cmd/linkedin/main.go
+var Version = "dev"
+
+func main() {
+    cmd.Version = Version
+    cmd.Execute()
+}
+```
+
+**Build with version:**
+```bash
+go build -ldflags "-X main.Version=$(git describe --tags)" ./cmd/linkedin
+```
+
+**Usage:**
+```bash
+linkedin --version
+# Output: linkedin version 0.1.0
+```
+
+---
+
+### 5. Structured Logging
+
+**Replace `fmt.Printf` with `log/slog`:**
+
+```go
+import "log/slog"
+
+var logger = slog.New(slog.NewTextHandler(os.Stdout, nil))
+
+// Before
+fmt.Printf("Sending connection request to %s...\n", profileURL)
+
+// After
+logger.Info("sending connection request", "url", profileURL)
+```
+
+**Benefits:**
+- JSON output option for CI/CD
+- Log levels (Debug, Info, Warn, Error)
+- Consistent formatting
+- Built into Go 1.21+ (no external dependency)
+
+**Migration:**
+- Replace user-facing output with `fmt` (keep CLI UX)
+- Use `slog` for debug/verbose logging only
+
+---
+
+### 6. Testable Time Handling
+
+**Problem:** Hard-coded `time.Sleep()` in navigator
+
+**Solution:**
+
+```go
+// internal/linkedin/navigator.go
+type Sleeper interface {
+    Sleep(time.Duration)
+}
+
+type RealSleeper struct{}
+func (RealSleeper) Sleep(d time.Duration) { time.Sleep(d) }
+
+type NoOpSleeper struct{}
+func (NoOpSleeper) Sleep(time.Duration) {}
+
+type Navigator struct {
+    client  *pinchtab.Client
+    sleeper Sleeper
+}
+
+func NewNavigator(client *pinchtab.Client) *Navigator {
+    return &Navigator{
+        client:  client,
+        sleeper: RealSleeper{},
+    }
+}
+
+// In tests
+navigator := NewNavigator(mockClient)
+navigator.sleeper = NoOpSleeper{}
+```
+
+**Not over-engineering:**
+- Simple interface, no DI framework
+- Default injection in constructor
+- Tests override as needed
+
+---
+
+### 7. Documentation
+
+**README.md Additions:**
+
+1. **Badges** (top of README)
+   - Build status
+   - Test coverage
+   - License
+   - Go version
+
+2. **"Why This Tool"** section
+   - Problem statement
+   - How it differs from alternatives
+
+3. **"How It Works"** diagram
+   - Architecture overview
+
+4. **Troubleshooting** section
+   - Common issues and solutions
+
+5. **Development** section
+   - Setup instructions
+   - Running tests
+   - Contributing guidelines
+
+**New Documentation:**
+
+| File | Purpose |
+|------|---------|
+| `docs/ARCHITECTURE.md` | Package organization, data flow |
+| `docs/RATE_LIMITS.md` | LinkedIn safety guidelines |
+| `docs/SECURITY.md` | Security considerations |
+
+---
+
+### 8. Code Quality
+
+**Refactors:**
+
+| Change | Impact | Effort |
+|--------|--------|--------|
+| Extract magic numbers to constants | Low | Low |
+| Add context to error messages | Medium | Low |
+| Improve user-facing errors | Medium | Low |
+| Consistent naming conventions | Low | Low |
+
+**Not Changing:**
+- Package structure (already good)
+- Command structure (clean)
+- Overall architecture (solid)
+
+---
+
+## Error Handling
+
+**Current State:**
+```go
+return fmt.Errorf("failed to navigate: %w", err)
+```
+
+**Improvements:**
+```go
+// Add context
+return fmt.Errorf("navigating to profile %s: %w", profileURL, err)
+
+// User-friendly errors
+if strings.Contains(err.Error(), "connect button not found") {
+    return fmt.Errorf("could not send request: profile may already be connected")
+}
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+**Coverage Target:** 70%+ for core logic
+
+**Test Files to Add:**
+- `internal/linkedin/validator_test.go`
+- `internal/linkedin/navigator_test.go`
+- `internal/ratelimit/limiter_test.go`
+- `internal/ratelimit/limits_test.go`
+
+### Integration Tests
+
+**Manual test script** (already exists: `test_auth.sh`)
+
+**Future:** Add automated integration tests with mock LinkedIn (not in scope)
+
+---
+
+## Trade-offs
+
+### Approach Considered
+
+| Option | Pros | Cons | Decision |
+|--------|------|------|----------|
+| Minimal (just LICENSE) | Fast | Not community-ready | ❌ Rejected |
+| Comprehensive (this design) | Professional, maintainable | More work upfront | ✅ Selected |
+| Full enterprise (CI/CD, releases, benchmarks) | Production-ready | Over-engineered for v1 | ❌ Rejected |
+
+### Why Not Over-Engineer?
+
+- No users yet (validate demand first)
+- Can add features based on community feedback
+- Keep maintenance burden low
+
+---
+
+## Implementation Plan
+
+See: `docs/plans/YYYY-MM-DD-linkedin-cli-oss-publishing-plan.md`
+
+**Phases:**
+
+1. **Phase 1 (Critical):** LICENSE, tests, version
+2. **Phase 2 (Important):** CI/CD, logging, OSS metadata
+3. **Phase 3 (Nice to have):** Docs, refactors
+
+---
+
+## Success Criteria
+
+- [ ] All packages have tests (70%+ coverage)
+- [ ] MIT LICENSE file present
+- [ ] CI runs tests on every PR
+- [ ] `linkedin --version` works
+- [ ] CONTRIBUTING.md exists
+- [ ] README has badges and examples
+
+---
+
+## References
+
+- [Go Project Layout](https://github.com/golang-standards/project-layout)
+- [Go Testing Best Practices](https://github.com/golang/go/wiki/TestComments)
+- [GitHub Actions for Go](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go)
+- [MIT License](https://opensource.org/licenses/MIT)