Metadata-Version: 2.5
Name: freelance-dev-suite
Version: 0.2.0
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
```

## 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
