codetour-cli 0.1.0__tar.gz → 0.3.0__tar.gz

codetour_cli-0.3.0/PKG-INFO

@@ -0,0 +1,138 @@
+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.

codetour_cli-0.3.0/README.md

@@ -0,0 +1,99 @@
+# 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.

{codetour_cli-0.1.0 → codetour_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codetour-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension"
 authors = [{name = "Jérémie Lumbroso"}]
 readme = "README.md"
@@ -41,6 +41,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# MCP server (ADR-0017): thin wrapper over the same machinery the CLI
+# verbs call, exposed as `codetour-mcp` (stdio).
+mcp = [
+    "mcp>=1.2",
+]
 dev = [
     "pytest",
     "pytest-cov",
@@ -51,6 +56,10 @@ dev = [
 
 [project.scripts]
 codetour-cli = "codetour_cli.cli:main"
+# Installed unconditionally; the mcp SDK lives in the [mcp] extra, and the
+# launcher answers a bare install with an install hint, not a traceback
+# (the json-source-edit playground-launcher pattern).
+codetour-mcp = "codetour_cli.mcp_server:main"
 
 [project.urls]
 Homepage = "https://github.com/jlumbroso/codetour-cli"

{codetour_cli-0.1.0 → codetour_cli-0.3.0}/src/codetour_cli/cli.py

@@ -319,6 +319,77 @@ def load_parsing_schema(report_content: str) -> ParsingSchema:
     return schema
 
 
+def select_review_steps(review, auto_approve_above: Optional[float] = None):
+    """
+    Decide which parsed review steps to apply.
+
+    Base set: steps the human checked (the report workflow's contract).
+    With auto_approve_above set (0.0-1.0), UNCHECKED steps whose confidence
+    clears the threshold are promoted in as well -- except steps marked for
+    deletion, which are never auto-approved: removing a step from a tour is
+    destructive and stays behind an explicit human checkbox regardless of
+    confidence (the same never-auto principle the migrate path applies).
+
+    Returns (selected_steps, promoted_steps) -- promoted ⊆ selected.
+    """
+    selected = list(review.get_corrected_steps())
+    promoted = []
+    if auto_approve_above is not None:
+        cutoff = auto_approve_above * 100.0
+        already = {s.step_number for s in selected}
+        for r in review.step_reviews:
+            if r.step_number in already or r.status_checked:
+                continue
+            if r.is_marked_for_deletion():
+                continue
+            if r.confidence is not None and r.confidence >= cutoff:
+                promoted.append(r)
+        selected.extend(promoted)
+        selected.sort(key=lambda s: s.step_number)
+    return selected, promoted
+
+
+def clean_stale_review_reports(
+    tours_dir: Path,
+    tour_name: str,
+    keep: Optional[Path],
+    dry_run: bool = False,
+) -> list:
+    """
+    Remove MIGRATION-REVIEW-{tour_name}-*.md reports for OTHER target
+    commits than the current run's (whose report, if any, is `keep`).
+
+    Matching is by literal prefix/suffix on the filename, deliberately not
+    glob (tour names are user-controlled; glob metacharacters in a name
+    must not widen the match). In dry_run, returns the candidates without
+    deleting. Returns the list of removed (or would-remove) paths.
+    """
+    prefix = f"MIGRATION-REVIEW-{tour_name}-"
+    removed = []
+    if not tours_dir.is_dir():
+        return removed
+    for p in sorted(tours_dir.iterdir()):
+        if not (p.is_file() and p.name.startswith(prefix) and p.name.endswith(".md")):
+            continue
+        if keep is not None and p.name == keep.name:
+            continue
+        if not dry_run:
+            p.unlink()
+        removed.append(p)
+    return removed
+
+
+def resolve_context_lines(args, config: dict) -> int:
+    """CLI flag wins over config review.context_lines; default 7; floor 0."""
+    cli_val = getattr(args, 'context_lines', None)
+    if cli_val is not None:
+        return max(0, cli_val)
+    try:
+        return max(0, int(config.get('review', {}).get('context_lines', 7)))
+    except (TypeError, ValueError):
+        return 7
+
+
 def generate_review_report(
     tour_path: Path,
     result,
@@ -327,7 +398,8 @@ def generate_review_report(
     repo_root: Path,
     is_dry_run: bool = False,
     no_guidance: bool = False,
-    threshold: Optional[float] = None
+    threshold: Optional[float] = None,
+    context_lines: int = 7
 ) -> Optional[Path]:
     """
     Generate a markdown review report for migrations with low-confidence steps.
@@ -469,8 +541,8 @@ def generate_review_report(
             new_line = None
 
         # Get code context for old and new locations (from specific commits)
-        old_context = get_code_context(repo_root, old_file, old_line, source_commit) if old_line else "(No line number)"
-        new_context = get_code_context(repo_root, new_file, new_line, target_commit) if new_line and update.new_location else "(File deleted)"
+        old_context = get_code_context(repo_root, old_file, old_line, source_commit, context_lines=context_lines) if old_line else "(No line number)"
+        new_context = get_code_context(repo_root, new_file, new_line, target_commit, context_lines=context_lines) if new_line and update.new_location else "(File deleted)"
 
         # Quote the description with chevrons
         quoted_description = quote_with_chevrons(step.description)
@@ -794,6 +866,22 @@ Examples:
         dest='auto_approve',
         help='Automatically approve all changes (skip confirmation prompts)'
     )
+    apply_review_parser.add_argument(
+        '--auto-approve-above',
+        type=float,
+        dest='auto_approve_above',
+        metavar='X',
+        help=(
+            'Additionally apply UNCHECKED steps whose confidence >= X '
+            '(0.0-1.0), on top of the checked ones. Steps marked for '
+            'deletion are never auto-approved -- destructive actions stay '
+            'behind an explicit human checkbox. Note: confidence only ever '
+            'takes 5 exact values (see docs/adr/0016-*.md), so a threshold '
+            'between quanta behaves like the nearest quantum above it. '
+            'ADR-0003\'s "batch approve all above confidence X", in the '
+            'report-based workflow that ADR-0007 shipped.'
+        )
+    )
 
     # migrate command
     migrate_parser = subparsers.add_parser(
@@ -860,6 +948,27 @@ Examples:
         dest='no_lint',
         help='Skip the advisory post-migration lint pass (ADR-0014)'
     )
+    migrate_parser.add_argument(
+        '--clean-reviews',
+        action='store_true',
+        dest='clean_reviews',
+        help=(
+            'After migrating each tour, delete stale MIGRATION-REVIEW-'
+            '{tour}-*.md reports left over from earlier target commits '
+            '(the report for THIS run, if any, is kept). In --dry-run, '
+            'lists what would be cleaned without deleting.'
+        )
+    )
+    migrate_parser.add_argument(
+        '--context-lines',
+        type=int,
+        dest='context_lines',
+        metavar='N',
+        help=(
+            'Lines of code context above/below each reviewed line in the '
+            'review report (default: from config review.context_lines, 7)'
+        )
+    )
 
     args = parser.parse_args()
 
@@ -1451,13 +1560,24 @@ def apply_review_command(args, config: dict) -> int:
         print(f"❌ Failed to load tour: {e}", file=sys.stderr)
         return 2
 
-    # Get only reviewed steps (checkbox checked)
-    corrected_steps = review.get_corrected_steps()
+    # Reviewed steps (checkbox checked), plus -- with --auto-approve-above X --
+    # unchecked steps whose confidence clears the threshold (never deletions).
+    auto_above = getattr(args, 'auto_approve_above', None)
+    if auto_above is not None and not (0.0 <= auto_above <= 1.0):
+        print(f"❌ --auto-approve-above must be between 0.0 and 1.0 (got {auto_above})", file=sys.stderr)
+        return 2
+
+    corrected_steps, promoted_steps = select_review_steps(review, auto_above)
+    if promoted_steps:
+        nums = ", ".join(str(s.step_number) for s in promoted_steps)
+        print(f"🔓 Auto-approving {len(promoted_steps)} unchecked step(s) at confidence ≥ {auto_above:.0%}: {nums}")
 
     if not corrected_steps:
         print("ℹ️  No corrections found in review report")
         print("   The report may not have been edited, or no checkboxes were marked")
         print("   Tip: Check the 'Status' checkbox for steps you want to apply")
+        if auto_above is not None:
+            print(f"   (--auto-approve-above {auto_above} promoted nothing: no unchecked, non-deletion step at that confidence)")
         return 0
 
     # Apply corrections
@@ -1849,6 +1969,7 @@ def migrate_all_tours(args, config: dict) -> int:
             print_migration_summary(result, tour_name, is_dry_run)
 
             # Generate review report if needed
+            report_path = None
             if result.num_needs_review > 0:
                 report_path = generate_review_report(
                     tour_path=tour_info.path,
@@ -1858,7 +1979,8 @@ def migrate_all_tours(args, config: dict) -> int:
                     repo_root=repo_info.repo_path,
                     is_dry_run=is_dry_run,
                     no_guidance=getattr(args, 'no_guidance', False),
-                    threshold=threshold
+                    threshold=threshold,
+                    context_lines=resolve_context_lines(args, config)
                 )
                 if report_path:
                     review_reports.append(report_path)
@@ -1867,6 +1989,20 @@ def migrate_all_tours(args, config: dict) -> int:
                     else:
                         print(f"  📄 Review report: {report_path.relative_to(repo_info.repo_path)}")
 
+            # Optionally clean stale reports from earlier target commits
+            # (keyed on the just-generated report's actual filename -- never
+            # re-derived, since to_commit may be symbolic like "HEAD").
+            if getattr(args, 'clean_reviews', False):
+                stale = clean_stale_review_reports(
+                    tours_dir=tour_info.path.parent,
+                    tour_name=tour_info.path.stem,
+                    keep=report_path,
+                    dry_run=is_dry_run,
+                )
+                if stale:
+                    verb = "Would clean" if is_dry_run else "Cleaned"
+                    print(f"  🧹 {verb} {len(stale)} stale review report(s): " + ", ".join(p.name for p in stale))
+
         except Exception as e:
             log.error("migration_failed", tour=tour_name, error=str(e))
             print(f"  ❌ Failed: {e}\n")

{codetour_cli-0.1.0 → codetour_cli-0.3.0}/src/codetour_cli/config.py

@@ -24,6 +24,14 @@ DEFAULT_CONFIG = {
     "display": {
         "color": True,
         "verbosity": "normal",
+    },
+    "review": {
+        # Lines of code context above/below each reviewed line in review
+        # reports. Ratified at 7 (the shipped default) over ADR-0007's
+        # original ±3 recommendation, made configurable per Jérémie's
+        # 2026-08-29 answer ("so we don't leave people... without a way
+        # to tweak the tool to their context").
+        "context_lines": 7,
     }
 }
 
@@ -57,6 +65,12 @@ display:
 
   # Verbosity level (quiet, normal, verbose)
   verbosity: normal
+
+# Review report preferences
+review:
+  # Lines of code context above/below each reviewed line (override per
+  # run with `migrate --context-lines N`)
+  context_lines: 7
 """