Merge pull request #1 from totalaudiopromo/feat/professional-release

feat: production-grade release

Author: chrisschouk

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm build

.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm build
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -5,3 +5,14 @@ dist/
 .env
 .env.local
 sink.config.ts
+sink.config.js
+sink.config.json
+NEXT_SESSION.md
+package-lock.json
+/contacts.csv
+contacts-clean.csv
+scrubbed.csv
+clean.csv
+video/node_modules/
+video/out/
+.DS_Store

.npmignore

@@ -0,0 +1,16 @@
+src/
+test/
+video/
+.github/
+.env*
+*.tape
+*.tsbuildinfo
+sink.config.*
+NEXT_SESSION.md
+CONTRIBUTING.md
+CHANGELOG.md
+.prettierrc
+eslint.config.js
+vitest.config.ts
+tsconfig.json
+.DS_Store

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2
+}

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-07
+
+### Added
+
+- Three-phase pipeline: scrub (validate), rinse (dedup), soak (enrich)
+- `wash` command for full pipeline execution
+- `scrub` command with RFC 5322 validation, UK domain typo correction, disposable detection, MX verification, role-based flagging, catch-all detection, and optional SMTP verification
+- `rinse` command with exact email, fuzzy name (Jaro-Winkler), domain cluster, and cross-field deduplication strategies
+- `soak` command with Anthropic (Claude Haiku) and OpenAI (GPT-4o-mini) enrichment providers
+- `spot` command for single email checks
+- `inspect` command for data quality scoring
+- `drain` command for format conversion (CSV, JSON, JSONL)
+- `tui` command for full terminal dashboard (Ink)
+- Interactive mode when run with no arguments
+- Resilient CSV parser with flexible header matching
+- Configurable via `sink.config.ts`
+- Programmatic API (`runPipeline`, `loadConfig`)
+- `--quiet` flag to suppress all output except errors
+- `--dry-run` flag for previewing without writing files
+- `--json` flag for machine-readable output
+- 39 unit tests

CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to sink-cli
+
+Thanks for your interest in contributing. This guide covers what you need to get started.
+
+## Dev Setup
+
+```bash
+git clone https://github.com/totalaudiopromo/sink-cli.git
+cd sink-cli
+pnpm install
+pnpm build
+```
+
+## Scripts
+
+| Command | What it does |
+|---------|-------------|
+| `pnpm build` | Compile TypeScript to `dist/` |
+| `pnpm dev` | Watch mode |
+| `pnpm test` | Run all tests (Vitest) |
+| `pnpm test:watch` | Tests in watch mode |
+| `pnpm typecheck` | Type-check without emitting |
+
+## Running locally
+
+After building, you can run the CLI directly:
+
+```bash
+node dist/cli.js scrub test/fixtures/sample.csv --dry-run
+```
+
+## Tests
+
+Tests live in `test/` and mirror `src/` structure. Run them before pushing:
+
+```bash
+pnpm test
+```
+
+All tests should pass. If you're adding a new feature, add tests for it. If you're fixing a bug, add a test that reproduces it.
+
+## Code Style
+
+- TypeScript strict mode
+- UK spelling in user-facing text (colour, normalise, licence)
+- No emojis in code or output
+- Commits use `feat:` / `fix:` / `docs:` / `test:` / `chore:` prefixes
+
+## Pull Requests
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Run `pnpm typecheck && pnpm test` -- both must pass
+4. Open a PR with a clear description of what changed and why
+
+Keep PRs focused. One feature or fix per PR is ideal.
+
+## Project Structure
+
+```
+src/
+  cli.ts              CLI entry point (Commander)
+  pipeline.ts         Pipeline orchestrator
+  config.ts           Config loader
+  types.ts            Shared types
+  phases/
+    scrub/            Email validation, parsing, typo correction
+    rinse/            Deduplication strategies
+    soak/             AI enrichment providers
+  output/             CSV/JSON/JSONL formatters
+  ui/                 Terminal UI (format helpers, TUI, interactive)
+  utils/              MX cache, helpers
+test/
+  fixtures/           Sample CSV files
+  scrub/              Scrub phase tests
+  rinse/              Rinse phase tests
+  soak/               Provider tests
+  pipeline.test.ts    Integration tests
+```
+
+## Questions?
+
+Open an issue. We're happy to help.