Metadata-Version: 2.4
Name: codetour-cli
Version: 0.3.0
Summary: Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension
Author: Jérémie Lumbroso
License: MIT
Project-URL: Homepage, https://github.com/jlumbroso/codetour-cli
Project-URL: Repository, https://github.com/jlumbroso/codetour-cli
Keywords: codetour,code-tour,vscode,git,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gitpython
Requires-Dist: pydantic>=2.0
Requires-Dist: structlog
Requires-Dist: rich
Requires-Dist: python-dotenv
Requires-Dist: pyyaml
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.0
Requires-Dist: json-source-edit<2,>=1.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# CodeTour CLI

[![Tests](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml/badge.svg)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
[![Coverage ≥60%](https://img.shields.io/badge/coverage-%E2%89%A560%25-yellowgreen)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/codetour-cli)](https://pypi.org/project/codetour-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/codetour-cli)](https://pypi.org/project/codetour-cli/)
[![Downloads](https://static.pepy.tech/badge/codetour-cli)](https://pepy.tech/projects/codetour-cli)
[![License](https://img.shields.io/github/license/jlumbroso/codetour-cli)](https://github.com/jlumbroso/codetour-cli/blob/main/LICENSE)

**Algorithmic maintenance of [CodeTour](https://github.com/microsoft/codetour) files: keep `.tour` walkthroughs accurate as the code they narrate evolves.**

> **Unofficial companion tool.** `codetour-cli` is an independent,
> unofficial companion to [CodeTour](https://github.com/microsoft/codetour),
> the VS Code extension by Jonathan Carter (Microsoft). It is not
> affiliated with, endorsed by, or maintained by Microsoft or the CodeTour
> project. It exists to *serve* CodeTour and its users — keeping `.tour`
> files accurate as the code they walk through evolves.

---

## The problem

A CodeTour step pinned to `src/auth.py:42` is correct the day it's written. Twenty commits later, line 42 is something else entirely — and every tour in the repository is silently lying. Tours are the best onboarding artifact a codebase can have, *if* someone keeps them true. Nobody keeps them true by hand.

`codetour-cli` tracks each step across the commits between a tour's pinned `ref` and `HEAD` (git hunk mapping plus content heuristics), applies high-confidence line updates automatically with **byte-preserving surgical edits** (your diff shows the step change, not a rewritten file — via [`json-source-edit`](https://pypi.org/project/json-source-edit/)), and routes everything it isn't sure about to a review report designed to be worked by humans *and* AI agents alike.

## Install

```bash
pip install codetour-cli        # Python ≥ 3.10
```

## Quickstart

```bash
codetour-cli status                  # which tours lag HEAD?
codetour-cli migrate --dry-run       # preview: what would move, what needs review
codetour-cli migrate                 # apply confident updates; write review report
codetour-cli lint                    # ground-truth check tours against the workspace
```

## The maintenance loop

```
author tour ──► lint ──► commit, pin `ref`
     ▲                        │
     │               ...code evolves...
     │                        │
     │                   status  (tour lags HEAD?)
     │                        │
apply-review ◄── review report ◄── migrate [--dry-run]
(checked steps            (auto-applies confident updates;
 written back)             low-confidence → the report)
```

Steps the migration can't confidently place land in `MIGRATION-REVIEW-{tour}-{commit}.md`: each entry carries the step's original description (its *intent*), old → new location, why confidence dropped, and the actual code now at the proposed location. Check the boxes you approve — or correct the locations inline — then:

```bash
codetour-cli apply-review MIGRATION-REVIEW-mytour-abc12345.md
```

**The report is deliberately dual-audience**: an AI agent can read it, judge each proposed location against the step's stated intent, mark the checkboxes, and apply — the same workflow, no human bottleneck for the easy calls. (A companion [Claude skill](https://github.com/jlumbroso/codetour-skill/releases) teaches agents both tour authoring and this maintenance loop.)

## Commands

| Command | Purpose |
|---|---|
| `init` | Set up `.codetour-cli.yml` configuration |
| `status` | Health of every tour: current vs. lagging HEAD |
| `check [tour]` | Validate tour structure without migrating |
| `lint [paths]` | Step-level checks against the workspace: missing files, out-of-range lines, non-matching or ambiguous patterns, broken `nextTour` links (`--format json`, `--strict`) |
| `migrate [tour]` | Track steps to HEAD; apply confident updates; report the rest |
| `apply-review <report>` | Write checked corrections back to the tour file |
| `undo [tour]` | Restore from the `.tour.backup` files migrate creates |

**Flags worth knowing** (`migrate`): `--threshold X` — the auto-apply confidence bar (note: confidence takes 5 exact values, not a smooth dial; see `docs/adr/0016-*.md`); `--clean-reviews` — drop stale review reports from earlier target commits; `--context-lines N` — code context in reports (default 7, config `review.context_lines`). (`apply-review`): `--auto-approve-above X` — also apply *unchecked* steps at or above that confidence; steps marked for deletion are **never** auto-approved.

## MCP server

For agents on MCP-capable surfaces, the same operations are exposed as structured tools:

```bash
pip install "codetour-cli[mcp]"
codetour-mcp                       # stdio MCP server
```

Five tools — `tour_status`, `lint_tours`, `migrate_tour` (defaults to dry-run; a model-facing tool must not mutate by default), `read_review_report`, `apply_review` — each a thin wrapper calling the exact functions the CLI verbs call, with identical semantics (including: deletion-marked steps are never auto-approved). Register it e.g. in `.mcp.json`:

```json
{ "mcpServers": { "codetour": { "command": "codetour-mcp" } } }
```

## Design record

This tool is developed with the [ADRs4AI](https://github.com/jlumbroso) methodology — every architectural decision, including the ones that were later reversed, lives in `docs/adr/` as a first-class deliberation record: the byte-preserving editing contract, the confidence quantization study, the review-workflow design, and the retirement of ideas that eight months of shipped reality outvoted.

## License

[MIT](LICENSE) — like CodeTour itself.
