linkedin-automation-cli 1.0.0

package/.env.example

@@ -0,0 +1,12 @@
+# Dashscope Claude API Configuration
+# Get your API key from: https://dashscope.aliyun.com/
+DASHSCOPE_API_KEY=your_key_here
+DASHSCOPE_BASE_URL=https://coding.dashscope.aliyuncs.com/apps/anthropic/v1
+DASHSCOPE_MODEL=qwen3.5-plus
+
+# Page Agent Extension Configuration (for fast mode)
+# Get auth token from extension side panel
+PAGE_AGENT_AUTH_TOKEN=your_extension_auth_token
+
+# Page Agent CDP Port (default: 9222)
+PAGE_AGENT_CDP_PORT=9222

package/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+        continue-on-error: true
+
+      - name: Format check
+        run: npm run format:check
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify dist output
+        run: |
+          test -d dist/
+          test -f dist/index.js
+          echo "Build verified successfully"

package/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'  # Trigger on version tags like v1.0.0
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run lint and format checks before commit
+npm run lint
+npm run format:check

package/.prettierignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+coverage/
+*.log

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "always"
+}

package/AGENTS.md

@@ -0,0 +1,294 @@
+# AGENTS.md - LinkedIn CLI Development Guide
+
+This document provides essential information for AI coding agents working on the LinkedIn CLI codebase.
+
+## Project Overview
+
+LinkedIn CLI is a Go-based command-line tool for LinkedIn automation using PinchTab (browser automation HTTP server). It sends connection requests and direct messages with built-in rate limiting for safety.
+
+**Tech Stack:** Go 1.21+, Cobra CLI, PinchTab HTTP client
+
+## Build, Test, and Lint Commands
+
+### Build
+```bash
+make build              # Build binary → linkedin-cli
+go build -o linkedin-cli ./cmd/linkedin
+```
+
+### Test
+```bash
+make test               # Run all tests
+go test -v ./...        # Run all tests with verbose output
+
+# Run single test
+go test -v -run TestFunctionName ./path/to/package
+go test -v -run TestProfileCRUD ./internal/config
+
+# Run tests in specific package
+go test -v ./internal/config
+go test -v ./internal/pinchtab
+```
+
+### Lint and Format
+```bash
+make lint               # Run golangci-lint
+make fmt                # Format code with go fmt
+golangci-lint run       # Run linter directly
+go fmt ./...            # Format all files
+```
+
+### Clean
+```bash
+make clean              # Remove binary and clean build cache
+```
+
+## Project Structure
+
+```
+linkedin-cli/
+├── cmd/linkedin/main.go          # Entry point
+├── internal/                     # Private packages
+│   ├── cmd/                      # CLI commands (Cobra)
+│   │   ├── root.go              # Base command, flags, helpers
+│   │   ├── auth.go              # Authentication flow
+│   │   ├── connect.go           # Send connection requests
+│   │   ├── message.go           # Send direct messages
+│   │   └── profiles.go          # Profile management
+│   ├── config/                   # Configuration persistence
+│   │   ├── config.go            # Manager for profile/rate limits
+│   │   └── profile.go           # Profile and RateLimits types
+│   ├── linkedin/                 # LinkedIn page interactions
+│   │   ├── navigator.go         # Page interaction logic
+│   │   ├── selectors.go         # CSS selectors (fragile!)
+│   │   └── validator.go         # URL validation
+│   ├── pinchtab/                 # PinchTab HTTP client
+│   │   ├── client.go            # API wrapper
+│   │   └── types.go             # Instance, Tab, Snapshot types
+│   └── ratelimit/                # Rate limiting logic
+│       ├── limiter.go           # Check/Record methods
+│       └── limits.go            # Default/Conservative limits
+├── go.mod
+├── Makefile
+└── README.md
+```
+
+## Code Style Guidelines
+
+### Imports
+Organize imports in three groups, separated by blank lines:
+1. Standard library
+2. External packages
+3. Internal packages
+
+```go
+import (
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/thaddeus-git/linkedin-cli/internal/config"
+	"github.com/thaddeus-git/linkedin-cli/internal/pinchtab"
+)
+```
+
+### Naming Conventions
+- **Packages:** lowercase, single word if possible (e.g., `config`, `cmd`, `pinchtab`)
+- **Types:** PascalCase for exported, camelCase for private
+- **Functions/Methods:** PascalCase for exported, camelCase for private
+- **Variables:** camelCase, descriptive but concise
+- **Constants:** PascalCase or UPPER_SNAKE_CASE
+- **Interfaces:** typically end with `-er` (e.g., `Navigator`, `Sleeper`)
+
+### Comments
+- Start with the name of the thing being commented
+- Use complete sentences
+- No inline comments explaining obvious code
+
+```go
+// Manager handles configuration and state
+type Manager struct {
+	configDir string
+}
+
+// NewManager creates a new config manager
+func NewManager() (*Manager, error) {
+	// Implementation
+}
+```
+
+### Error Handling
+- Wrap errors with context using `fmt.Errorf` and `%w`
+- Provide actionable error messages
+- Use `exitWithError()` in CLI commands for user-facing errors
+
+```go
+// Good: wrap with context
+if err := client.Navigate(url); err != nil {
+	return fmt.Errorf("failed to navigate: %w", err)
+}
+
+// Good: user-facing error in CLI
+if profileName == "" {
+	exitWithError("Profile name is required (--profile or LINKEDIN_PROFILE)")
+}
+
+// Avoid: bare error returns without context
+return err
+```
+
+### Types and Structures
+- Use structs for data, interfaces for behavior
+- Prefer composition over inheritance
+- Keep structs small and focused
+
+```go
+// Good: focused struct with clear purpose
+type Profile struct {
+	Name      string    `json:"name"`
+	CreatedAt time.Time `json:"created_at"`
+	LastUsed  time.Time `json:"last_used"`
+}
+```
+
+## Testing Guidelines
+
+### Test Structure
+- Place tests in `*_test.go` files alongside source code
+- Use `t.TempDir()` for test isolation (auto-cleanup)
+- Follow AAA pattern: Arrange, Act, Assert
+
+```go
+func TestProfileCRUD(t *testing.T) {
+	// Arrange
+	tempDir := t.TempDir()
+	mgr := &Manager{configDir: tempDir}
+	profile := &Profile{Name: "test"}
+
+	// Act
+	err := mgr.SaveProfile(profile)
+
+	// Assert
+	if err != nil {
+		t.Fatalf("failed to save: %v", err)
+	}
+	if !mgr.ProfileExists("test") {
+		t.Error("profile should exist")
+	}
+}
+```
+
+### Table-Driven Tests
+Use for testing multiple scenarios:
+
+```go
+func TestValidateProfileURL(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{"full URL", "https://linkedin.com/in/john", "https://linkedin.com/in/john", false},
+		{"username only", "john", "https://linkedin.com/in/john", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ValidateProfileURL(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ValidateProfileURL() error = %v", err)
+			}
+			if got != tt.want {
+				t.Errorf("ValidateProfileURL() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+```
+
+## Architecture Patterns
+
+### CLI Commands
+- Use Cobra framework for all commands
+- Define commands in `init()` function
+- Extract logic to separate `run*` functions
+- Use `exitWithError()` for errors, not `log.Fatal()`
+
+```go
+func init() {
+	rootCmd.AddCommand(connectCmd)
+	connectCmd.Flags().StringVarP(&connectURL, "url", "u", "", "LinkedIn profile URL")
+}
+
+var connectCmd = &cobra.Command{
+	Use:   "connect",
+	Short: "Send a connection request",
+	Run:   runConnect,
+}
+
+func runConnect(cmd *cobra.Command, args []string) {
+	// Validate, execute, handle errors
+}
+```
+
+### HTTP Client Pattern
+- Wrap external APIs in dedicated client packages
+- Use struct with methods for API calls
+- Return errors with context
+
+```go
+type Client struct {
+	baseURL string
+	client  *http.Client
+}
+
+func (c *Client) Navigate(url string) error {
+	return c.post("/navigate", map[string]string{"url": url}, nil)
+}
+```
+
+### Configuration Management
+- Store in `~/.linkedin-cli/` directory
+- JSON format for persistence
+- Separate files for profiles and rate limits
+
+## Important Notes
+
+### LinkedIn Selectors
+- Selectors in `internal/linkedin/selectors.go` are **fragile**
+- LinkedIn changes their UI frequently
+- These may need updates when LinkedIn updates
+
+### Rate Limiting
+- Default: 20 connections/day, 100/week, 50 messages/day
+- Delays: 3-8 seconds between actions
+- Stored per profile in `~/.linkedin-cli/ratelimit.json`
+
+### PinchTab Integration
+- Requires PinchTab running on `http://localhost:9867`
+- Install: `curl -fsSL https://pinchtab.com/install.sh | bash`
+- No built-in session persistence - user must re-login manually
+
+### No External Dependencies
+- Only use `github.com/spf13/cobra` for CLI
+- Use standard library for everything else
+- Avoid adding unnecessary dependencies
+
+## Development Workflow
+
+1. **Make changes** → Edit relevant files in `internal/`
+2. **Format code** → `make fmt` or `go fmt ./...`
+3. **Run tests** → `make test` or `go test -v ./...`
+4. **Lint check** → `make lint`
+5. **Build** → `make build`
+6. **Test manually** → `./linkedin-cli --help`
+
+## Debugging
+
+- Use `--verbose` flag for detailed output
+- Use `--dry-run` flag to preview actions without executing
+- Check PinchTab logs if browser automation fails
+- Use `curl http://localhost:9867/health` to verify PinchTab is running

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-03-14
+
+### Breaking Changes
+
+- **`agent ext:connect` removed** - Merged into `agent connect`
+  - Old: `linkedin agent ext:connect <url>`
+  - New: `linkedin agent connect <url>` (auto-detects extension)
+
+### Changed
+
+- **`agent connect` now auto-detects extension** - Uses fast extension mode when CDP browser available
+  - Falls back to Playwright when no CDP browser found
+  - Add `--playwright` flag to force Playwright mode
+
+### Added
+
+- **`agent playwright` command** - Explicit Playwright mode (old `connect` behavior)
+- **`PAGE_AGENT_AUTH_TOKEN` env var** - Configure extension auth token
+- **CDP auto-detection** - Automatically uses fastest available method
+
+### Migration Guide
+
+```bash
+# Before (v0.3.0)
+linkedin agent ext:connect https://linkedin.com/in/user/
+
+# After (v1.0.0)
+linkedin agent connect https://linkedin.com/in/user/
+```
+
+### Prerequisites for Extension Mode
+
+1. Install [Page Agent Extension](https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj)
+2. Start Chrome with CDP: `chrome --remote-debugging-port=9222`
+3. Log into LinkedIn in that browser
+4. Set `DASHSCOPE_API_KEY` env var

package/GIT_RELEASE.md

@@ -0,0 +1,167 @@
+# Git Release Guide
+
+This guide walks you through committing and pushing all changes to GitHub.
+
+## Quick Release
+
+```bash
+# 1. Navigate to worktree
+cd /Users/thaddeus/projects/linkedin-automation/.worktrees/linkedin-automation-cli
+
+# 2. Install new dependencies
+npm install
+
+# 3. Run all quality checks
+npm run typecheck
+npm run lint
+npm run format
+npm run test:coverage
+
+# 4. Build the project
+npm run build
+
+# 5. Stage all changes
+git add -A
+
+# 6. Commit
+git commit -m "feat: add startup best practices (tests, CI/CD, linting)
+
+- Added Vitest for unit testing with 80% coverage threshold
+- Added ESLint + Prettier for code quality
+- Added GitHub Actions CI/CD workflows
+- Added Husky pre-commit hooks
+- Created test files for core modules:
+  - storage.test.ts (encryption, secure storage)
+  - config.test.ts (configuration management)
+  - audit.test.ts (audit logging)
+  - selector-engine.test.ts (multi-layer selectors)
+  - engine.test.ts (template rendering)
+- Fixed duplicate code in browser.ts and cli/auth.ts
+- Updated package.json with new scripts and dependencies
+- Added npm publishing guide
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+
+# 7. Push to main branch
+git push origin main
+
+# 8. Create and push version tag (triggers auto-publish)
+npm version minor  # or patch/major as needed
+git push origin --tags
+```
+
+## Step-by-Step Verification
+
+### 1. Check Git Status
+
+```bash
+git status
+```
+
+You should see all the new files staged for commit.
+
+### 2. Verify Tests Pass
+
+```bash
+npm run test:coverage
+```
+
+Expected output:
+- All tests pass
+- Coverage meets 80% threshold
+
+### 3. Verify Build
+
+```bash
+npm run build
+node dist/index.js --help
+```
+
+Should display CLI help text.
+
+### 4. Verify CI Configuration
+
+Check that `.github/workflows/ci.yml` exists and contains:
+- Test job (runs on push/PR)
+- Build job (runs after tests pass)
+
+### 5. Commit and Push
+
+```bash
+git add -A
+git commit -m "feat: add startup best practices"
+git push origin main
+```
+
+### 6. Create Release Tag
+
+```bash
+# This bumps version, creates commit, and creates tag
+npm version minor
+
+# Push the tag (triggers GitHub Actions publish workflow)
+git push && git push --tags
+```
+
+## Verify on GitHub
+
+1. Go to: https://github.com/thaddeus-git/linkedin-cli
+2. Check that all files are visible
+3. Check Actions tab for CI run
+4. After tag push, check Releases for auto-created release
+
+## Manual npm Publish (if needed)
+
+If GitHub Actions doesn't auto-publish:
+
+```bash
+# Login (one-time)
+npm login
+
+# Dry run
+npm publish --dry-run
+
+# Publish
+npm publish --access public
+```
+
+## Files Added Summary
+
+### Configuration Files
+- `vitest.config.ts` - Vitest test configuration
+- `eslint.config.mjs` - ESLint configuration
+- `.prettierrc` - Prettier formatting rules
+- `.prettierignore` - Files to ignore for formatting
+- `.husky/pre-commit` - Pre-commit hook script
+
+### GitHub Actions
+- `.github/workflows/ci.yml` - CI pipeline
+- `.github/workflows/publish.yml` - npm publish pipeline
+
+### Test Files
+- `src/core/storage.test.ts`
+- `src/core/config.test.ts`
+- `src/core/audit.test.ts`
+- `src/linkedin/selector-engine.test.ts`
+- `src/templates/engine.test.ts`
+
+### Documentation
+- `NPM_PUBLISHING.md` - npm publishing guide
+- `GIT_RELEASE.md` - This file
+- Updated `README.md` with development workflow
+
+### Code Fixes
+- Fixed duplicate code in `src/core/browser.ts`
+- Fixed duplicate code in `src/cli/auth.ts`
+
+---
+
+**Troubleshooting:**
+
+| Issue | Solution |
+|-------|----------|
+| Tests fail | Run `npm run test:watch` to debug |
+| Lint errors | Run `npm run lint:fix` to auto-fix |
+| Format errors | Run `npm run format` |
+| Coverage too low | Add more tests for uncovered code |
+| Git push rejected | Run `git pull --rebase` first |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thaddeus Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,30 @@
+.PHONY: build test clean install lint
+
+BINARY_NAME=linkedin-cli
+MAIN_PACKAGE=./cmd/linkedin
+
+build:
+	go build -o $(BINARY_NAME) $(MAIN_PACKAGE)
+
+test:
+	go test -v ./...
+
+clean:
+	rm -f $(BINARY_NAME)
+	go clean
+
+install: build
+	mv $(BINARY_NAME) $(GOPATH)/bin/linkedin
+
+dev:
+	go run $(MAIN_PACKAGE)
+
+lint:
+	golangci-lint run
+
+fmt:
+	go fmt ./...
+
+deps:
+	go mod download
+	go mod tidy