Metadata-Version: 2.5
Name: freelance-dev-suite
Version: 0.2.1
Summary: CLI toolkit for managing freelance development jobs — from intake and estimation through implementation to client handoff.
Author: Mateusz Lewandowski
License: MIT
License-File: LICENSE
Keywords: cli,developer-tools,estimation,freelance,project-management
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: filelock>=3.16
Requires-Dist: pyyaml>=6.0
Provides-Extra: ai-dev
Requires-Dist: ai-dev-cli-tools>=1.2.0; extra == 'ai-dev'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Freelance Dev Suite

[![CI](https://github.com/MatthiasLew/freelance-dev-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/MatthiasLew/freelance-dev-suite/actions/workflows/ci.yml)
[![CodeQL](https://github.com/MatthiasLew/freelance-dev-suite/actions/workflows/codeql.yml/badge.svg)](https://github.com/MatthiasLew/freelance-dev-suite/actions/workflows/codeql.yml)
[![PyPI](https://img.shields.io/pypi/v/freelance-dev-suite.svg)](https://pypi.org/project/freelance-dev-suite/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

CLI toolkit for managing freelance development jobs — from intake and estimation through implementation to client handoff.

## Problem

Freelance developers waste time on:
- Analyzing unfamiliar projects before quoting
- Underestimating AI costs and work hours
- Scope creep after price agreement
- Missing quality checks before delivery
- Assembling handoff packages manually

**Freelance Dev Suite** automates the entire job lifecycle with one CLI.

## Install

Install the latest stable release from PyPI:

```bash
pip install freelance-dev-suite
```

For development, clone the repository and install the development dependencies:

```bash
git clone https://github.com/MatthiasLew/freelance-dev-suite.git
cd freelance-dev-suite
pip install -e ".[dev]"
```

## Quick Start

```bash
# Create a new job
freelance job new

# List active jobs
freelance jobs

# Check job status
freelance status JOB-001
# Start and finish real repository work
freelance work start JOB-001 --task "Implement invoice export" --agent codex --model gpt-5.6-sol
freelance work status JOB-001
freelance work finish WORK-0001
```

## Commands

| Command | Description | Status |
|---|---|---|
| `freelance job new` | Create a new job | ✅ implemented |
| `freelance jobs` | List all active jobs | ✅ implemented |
| `freelance status <JOB-ID>` | Show job details | ✅ implemented |
| `freelance analyze <JOB-ID>` | Run scan, validation, context, and AI-cost analysis | ✅ implemented |
| `freelance estimate <JOB-ID>` | Generate and persist a full quote | ✅ implemented |
| `freelance requirements <JOB-ID>` | Create, track, and confirm requirements checklist | ✅ implemented |
| `freelance templates` | List available project starter templates | ✅ implemented |
| `freelance bootstrap <TEMPLATE>` | Bootstrap standalone project from template | ✅ implemented |
| `freelance start <JOB-ID>` | Bootstrap project and start job implementation | ✅ implemented |
| `freelance handoff <JOB-ID>` | Run final QA Quality Gate & create handoff deliverables | ✅ implemented |
| `freelance finish <JOB-ID>` | Close and archive delivered job | ✅ implemented |
| `freelance bug add <JOB-ID>` | Add, parse, and structure client bug report | ✅ implemented |
| `freelance bug list <JOB-ID>` | List tracked bug reports and status | ✅ implemented |
| `freelance bug show <JOB-ID> <BUG-ID>` | View bug summary or client questions | ✅ implemented |
| `freelance bug status <JOB-ID> <BUG-ID>` | Update bug lifecycle state | ✅ implemented |
| `freelance bug repro <JOB-ID> <BUG-ID>` | View standalone reproduction script | ✅ implemented |
| `freelance bug test <JOB-ID> <BUG-ID>` | Link regression test file | ✅ implemented |
| `freelance scope check <JOB-ID> [REQ]` | Detect scope changes, estimate extra hours/AI cost & surcharge | ✅ implemented |
| `freelance scope list <JOB-ID>` | List all analyzed scope changes | ✅ implemented |
| `freelance scope show <JOB-ID> <CHANGE-ID>` | View scope change impact analysis or client proposal message | ✅ implemented |
| `freelance scope snapshot <JOB-ID>` | Create a frozen baseline snapshot of requirements spec | ✅ implemented |
| `freelance timer start <JOB-ID>` | Start recording development session | ✅ implemented |
| `freelance timer stop [JOB-ID]` | Stop active timer session and log duration | ✅ implemented |
| `freelance timer status [JOB-ID]` | Check active timer session status | ✅ implemented |
| `freelance timer log <JOB-ID>` | Show recorded time log and sessions | ✅ implemented |
| `freelance stats <JOB-ID>` | Calculate profitability, effective hourly rate, and margins | ✅ implemented |
| `freelance portfolio <JOB-ID>` | Generate professional client case study (with optional `--anonymize`) | ✅ implemented |
| `freelance calibrate` | Calculate historical estimation accuracy & multiplier recommendations | ✅ implemented |
| `freelance message <JOB-ID> <STAGE>` | Generate tailored client messages for all project stages (PL/EN) | ✅ implemented |
| `freelance pricing` | Inspect or dynamically update AI model pricing table | ✅ implemented |
| `freelance doctor` | Diagnose environment, git, ai-dev engine, and state schema health | ✅ implemented |
| `freelance config [show\|validate]` | Inspect and validate suite configuration | ✅ implemented |
| `freelance history <JOB-ID>` | View append-only business event audit timeline | ✅ implemented |
| `freelance export <JOB-ID>` | Export job to verified archive with SHA-256 integrity | ✅ implemented |
| `freelance import <ARCHIVE>` | Safely import job archive with path-traversal protection | ✅ implemented |
| `freelance mcp serve` | Local STDIO Model Context Protocol (MCP) server for Cursor & Claude | ✅ implemented |
| `freelance work start <JOB-ID> --task <TASK>` | Check scope, prepare incremental ai-dev context, and start time tracking | ✅ implemented |
| `freelance work status <JOB-ID>` | Show the current task, elapsed time, AI usage, model, and validation | ✅ implemented |
| `freelance work finish <WORK-ID>` | Run changed-file validation, stop time tracking, and record actual AI usage | ✅ implemented |
| `freelance work resume <WORK-ID>` | Resume a `NEEDS_FIX` session with acknowledged incremental context | ✅ implemented |
| `freelance work list <JOB-ID>` | List the complete development-session history for a job | ✅ implemented |
## Integration with ai-dev-cli-tools

This project uses [ai-dev-cli-tools](https://github.com/MatthiasLew/ai-dev-cli-tools) as the technical engine for:
- Project scanning and stack detection
- Test execution and linting
- Diagnostics and context building
- Bootstrap and final checks

Install with AI dev tools integration:

```bash
pip install "freelance-dev-suite[ai-dev]"
```

`freelance analyze` fails with a clear error when the engine is unavailable. During local
cross-repository development, point it at a source checkout executable:

```powershell
$env:AI_DEV_EXECUTABLE = "C:\path\to\ai-dev-cli-tools\.venv\Scripts\ai-dev.exe"
```

Analysis runs `scan`, `map`, `check`, and `context build`. Use `--check-mode fast` when a preview
without the complete validation suite is sufficient. Both MVP commands support structured output:

```bash
freelance analyze JOB-001 --json
freelance estimate JOB-001 --json
```

### Repository-backed work sessions

`freelance work` is the bridge between the business record and actual repository work. A session is
stored under `<job>/work/sessions/WORK-NNNN.json` and records its task, scope classification, related
requirements, timer segments, agent/model, provider-reported token usage, cost, and validation result.

```bash
freelance work start JOB-001 \
  --task "Add CSV invoice export" \
  --agent codex \
  --model gpt-5.6-sol \
  --requirement REQ-7

freelance work status JOB-001
freelance work finish WORK-0001

# When validation produces NEEDS_FIX:
freelance work resume WORK-0001
freelance work finish WORK-0001

freelance work list JOB-001 --json
```

At start, the command uses `ai-dev task` with an adaptive incremental context and saves its state
fingerprint. Resume sends that fingerprint back as acknowledged state, avoiding a blind full-project
reload while still accounting for repository changes. Finish uses `ai-dev check --mode changed`; the
engine may conservatively expand validation when its dependency mapping is uncertain.

Token and cost fields contain only provider-reported telemetry recorded by `ai-dev-cli-tools` during
the session. If telemetry contains tokens but no priced cost, the configured model pricing snapshot
is used. Missing telemetry remains zero instead of being presented as measured usage.

## Pricing configuration

Provider prices and the USD/PLN rate are assumptions, not live market data. The package contains a
reviewable default pricing snapshot. A user configuration may select another model, pricing file,
and exchange rate:

```yaml
models:
  default: claude-sonnet-4
  pricing_file: C:/freelance/model-pricing.yaml

exchange_rates:
  usd_to_pln: 4.0
```

The external pricing file uses a top-level `models` mapping with separate input, output, cached
input, and optional reasoning prices per million tokens.

## Architecture

```
ZLECENIE → intake → estimate → requirements → bootstrap → work → handoff → DONE
```

Freelance Dev Suite is the **business/workflow layer** on top of `ai-dev-cli-tools` (technical engine).

The boundary is intentional:

| Responsibility | Owner |
|---|---|
| Client, scope, pricing, time, profitability, handoff, and job records | `freelance-dev-suite` |
| Repository discovery, context selection, validation, technical telemetry, and environment bootstrap | `ai-dev-cli-tools` |
| Connecting a business work session to repository validation | `freelance work` adapter |

This repository does not implement a second repository scanner, context builder, test selector, or
telemetry collector. It calls the public `ai-dev` CLI contract and stores only the resulting business
evidence.

## Documentation

Comprehensive engineering documentation is available in the [`docs/`](docs) directory:

- [System Architecture](docs/ARCHITECTURE.md): Layer boundary, component design, concurrency model, and atomic storage.
- [State Format & Schema Compatibility](docs/STATE_FORMAT.md): Detailed JSON schemas, versioning policy, and persistent structures.
- [ai-dev Technical Engine Integration](docs/AI_DEV_INTEGRATION.md): Public CLI integration points, subprocess contract, and fallbacks.
- [CLI Contract & Exit Codes](docs/CLI_CONTRACT.md): Standard exit codes (`0`, `1`, `2`, `3`), structured envelopes, `--dry-run`, and `--explain`.
- [Security & Secret Redaction](docs/SECURITY.md): Multi-provider secret masking, path traversal guards, and archive protection.
- [Disaster Recovery & Diagnostics](docs/RECOVERY.md): `freelance doctor`, stale lock resolution, and archive backup/import.
- [Model Context Protocol (MCP) Server](docs/MCP_SERVER.md): Configuration guide for Cursor, Claude Desktop, and VS Code.

## Local MCP Server (Cursor & Claude)

Run the local Model Context Protocol (MCP) server over standard input/output:

```bash
freelance mcp serve
```

Configure Cursor (`~/.cursor/mcp.json`) or Claude Desktop:
```json
{
  "mcpServers": {
    "freelance": {
      "command": "freelance",
      "args": ["mcp", "serve"]
    }
  }
}
```

The server provides 9 specialized tools: `list_jobs`, `get_job_status`, `get_requirements`, `get_scope_changes`, `get_work_sessions`, `get_profitability`, `get_timeline`, `create_job`, and `check_scope`. All tool responses automatically redact sensitive API keys and secrets.

## Safe Mutation UX & Diagnostics

All state-mutating commands support:
- `--dry-run`: Preview operations and calculate changes without writing to disk.
- `--explain`: Explain all steps, affected files, git branches, and locks involved.
- `--json`: Output a structured envelope conforming to schema v1.0.

Verify the overall health of the environment, git, `ai-dev` engine, and all stored job schemas:
```bash
freelance doctor
```

## Performance & Benchmarks

Freelance Dev Suite is optimized in pure Python without external native extensions (no Rust, Go, or C toolchain dependencies required). All optimizations are backed by a reproducible 80-scenario benchmark suite comparing identical workloads against the baseline:

| Scenario | Workload | Baseline Median | Optimized Median | Speedup |
|---|---|---|---|---|
| Job Lookup | 1,000-job workspace | 2.24 ms | **0.23 ms** | **9.61x** |
| Scope Changes Listing | 100 changes | 2.14 ms | **0.21 ms** | **10.19x** |
| Archive Import (1MB) | Safe extract + SHA-256 | 250.2 ms | **28.3 ms** | **8.85x** |
| Archive Import (30MB) | Safe extract + SHA-256 | 4,888 ms | **1,404 ms** | **3.48x** |
| Work Sessions Listing | 150 sessions | 93.3 ms | **19.3 ms** | **4.84x** |
| Bug Report Processing | 100 bug reports | 35.7 ms | **10.2 ms** | **3.49x** |
| MCP Server Job Status | Stdio JSON-RPC tool | 3.93 ms | **1.07 ms** | **3.68x** |
| Cold Start (`--version`) | Fresh Python process | 486.5 ms | **270.2 ms** | **1.80x** |
| Cold Start (`--help`) | Fresh Python process | 463.6 ms | **265.4 ms** | **1.75x** |

### Key Architectural Optimizations
- **$O(1)$ Fast Path for Timeline**: `TimelineManager.record_event()` performs a backward seek within an 8KB tail buffer to determine the next sequential ID, eliminating full-file JSON parsing. An $O(N)$ safety fallback automatically scans the file and recovers the sequence (`max_seen`) if records are malformed or truncated.
- **Lazy Import of Concurrency Tooling**: Deferred `filelock` import to dynamic execution inside `storage_lock()`, reducing Python startup module overhead by over 100 modules and cutting cold-start latency by ~44%.
- **Streaming Directory Traversal**: Replaced recursive `Path.iterdir()` and `Path.glob()` calls with low-overhead `os.scandir()` and high-watermark job ID caching, eliminating repeated filesystem scans.
- **Buffered Single-Pass Archive I/O**: Streamed archive import in 128KB chunks while computing SHA-256 digests in-flight, halving disk I/O and memory usage.

### Native Acceleration (Rust) Analysis
During profiling with `cProfile`, disk-modifying operations were found to be physically dominated by kernel `fsync` (on Linux) and `FlushFileBuffers` (on Windows), which account for 35–50% of execution time. Because native code cannot bypass kernel disk synchronization latency, rewriting storage in Rust or C would not provide meaningful speedups while introducing compilation requirements and cross-platform binary dependencies. Native acceleration will only be revisited if future profiling identifies meaningful CPU-bound hotspots.

Complete methodology and reproducible measurements are documented in [`benchmarks/COMPARISON.md`](benchmarks/COMPARISON.md) and [`benchmarks/PROFILE.md`](benchmarks/PROFILE.md).

## Quality & Engineering Standards

- **Comprehensive Test Suite**: 241 passed tests (1 skipped) validating business logic, concurrency, file locks, MCP protocol, and CLI contracts.
- **Strict Branch Coverage**: 83.11% branch coverage with continuous enforcement in CI (`fail_under = 82%`).
- **Strict Type Checking**: 100% strict type safety enforced across all source modules and tests using `mypy --strict`.
- **Code Hygiene**: Formatted and linted with `ruff` using strict rule sets.
- **Security & Secret Redaction**: Multi-provider runtime secret masking (`mask_text`), path traversal guards (`assert_safe_path`), and automated GitHub Actions CodeQL analysis and Gitleaks history scanning.
- **Cross-Platform Matrix**: Fully verified and continuously tested on Linux and Windows runners across Python 3.11, 3.12, and 3.13.

## Releases

CI tests Linux and Windows on Python 3.11-3.13, installs the built wheel in an isolated environment,
runs a full job lifecycle against `ai-dev-cli-tools`, and scans Git history with Gitleaks. A tag named
`vMAJOR.MINOR.PATCH` starts `.github/workflows/release.yml`, verifies that the tag matches
`pyproject.toml`, builds and tests the distributions, publishes to PyPI with Trusted Publishing, and
creates a GitHub release.

PyPI publishing uses the Trusted Publisher configured for this repository, workflow `release.yml`,
and environment `pypi`. Publishing is intentionally not attempted from developer machines or with
a long-lived API token.

## License

MIT
