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

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

The package has not been published to PyPI yet. Install the current version directly from the
repository:

```bash
pip install "git+https://github.com/MatthiasLew/freelance-dev-suite.git"
```

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

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

Before the first tag, configure a PyPI Trusted Publisher 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
