devflow-cli 2.3.0__py3-none-any.whl → 2.8.0__py3-none-any.whl

devflow_cli/__init__.py

@@ -1,6 +1,7 @@
 """devflow CLI — Spec-Driven Development workflow."""
 
-VERSION = "2.3.0"
+VERSION = "2.8.0"
+STATE_SCHEMA_VERSION = 3
 
 STEPS = [
     "constitution",  # Pré-requis projet (1/projet). Auto-complétée si .specify/memory/constitution.md existe.
@@ -20,6 +21,12 @@ STEPS = [
 
 OPTIONAL_STEPS = {"clarify", "research", "contracts", "docs"}
 
+# Le mode fast conserve les gates et les bornes du pipeline. Il compte donc
+# 9 etapes effectives, dont 4 etapes productives principales.
+FAST_PRODUCTIVE_STEPS = ("spec", "plan", "tasks", "implement")
+FAST_STEP_COUNT = len(STEPS) - len(OPTIONAL_STEPS)
+FULL_STEP_COUNT = len(STEPS)
+
 REVIEW_GATES = {"review-spec", "review-tasks", "review-impl"}
 
 STEP_ARTIFACTS = {
@@ -51,6 +58,20 @@ STEP_LINEAR_MAPPING = {
     "done": "Done",
 }
 
+# Ordre de progression des statuts Linear (pour non-régression lors de la sync).
+# Un statut ne doit jamais régresser : si l'index courant >= index cible, on ne met pas à jour.
+STEP_LINEAR_ORDER = [
+    "Backlog",
+    "Spec",
+    "Research",
+    "Plan",
+    "Tasks",
+    "Review",
+    "In Progress",
+    "Doc",
+    "Done",
+]
+
 SUPPORTED_AGENTS = ["claude-code", "cursor"]
 
 # Mapping speckit → devflow pour la migration
@@ -85,4 +106,8 @@ assert OPTIONAL_STEPS <= _steps_set, f"OPTIONAL_STEPS not subset of STEPS: {OPTI
 assert REVIEW_GATES <= _steps_set, f"REVIEW_GATES not subset of STEPS: {REVIEW_GATES - _steps_set}"
 assert set(STEP_ARTIFACTS.keys()) <= _steps_set, f"STEP_ARTIFACTS has unknown keys: {set(STEP_ARTIFACTS.keys()) - _steps_set}"
 assert set(STEP_LINEAR_MAPPING.keys()) <= _steps_set, f"STEP_LINEAR_MAPPING has unknown keys: {set(STEP_LINEAR_MAPPING.keys()) - _steps_set}"
+assert set(STEP_LINEAR_MAPPING.values()) <= set(STEP_LINEAR_ORDER), (
+    f"STEP_LINEAR_MAPPING values not in STEP_LINEAR_ORDER: "
+    f"{set(STEP_LINEAR_MAPPING.values()) - set(STEP_LINEAR_ORDER)}"
+)
 assert set(SPECKIT_STEP_MAP.values()) <= _steps_set, f"SPECKIT_STEP_MAP maps to unknown steps: {set(SPECKIT_STEP_MAP.values()) - _steps_set}"

devflow_cli/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""Adaptateurs des services externes utilisés par devflow."""
+
+from devflow_cli.adapters.agents import (
+    AgentAdapter,
+    AgentExecution,
+    ClaudeCodeAdapter,
+    CodexAdapter,
+    CursorAdapter,
+    get_agent_adapter,
+)
+
+__all__ = [
+    "AgentAdapter",
+    "AgentExecution",
+    "ClaudeCodeAdapter",
+    "CodexAdapter",
+    "CursorAdapter",
+    "get_agent_adapter",
+]

devflow_cli/adapters/agents.py

@@ -0,0 +1,148 @@
+"""Adaptateurs d'exécution pour les agents IA en mode non interactif."""
+
+from __future__ import annotations
+
+import subprocess
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+
+PermissionMode = Literal["auto", "acceptEdits", "manual"]
+
+
+@dataclass(frozen=True)
+class AgentExecution:
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+    timed_out: bool = False
+
+
+class AgentAdapter(ABC):
+    """Contrat minimal d'un agent pilotable par le CLI."""
+
+    name: str
+    executable: str
+
+    @abstractmethod
+    def build_command(self, prompt: str, permission_mode: PermissionMode) -> list[str]:
+        """Construit une commande sans passer par un shell."""
+
+    def build_named_agent_command(self, agent_name: str, prompt: str) -> list[str]:
+        raise ValueError(f"L'adaptateur {self.name} ne supporte pas les agents nommés")
+
+    def execute(
+        self,
+        prompt: str,
+        cwd: Path,
+        timeout: int,
+        permission_mode: PermissionMode = "auto",
+        *,
+        capture_output: bool = False,
+    ) -> AgentExecution:
+        command = self.build_command(prompt, permission_mode)
+        try:
+            result = subprocess.run(
+                command,
+                cwd=cwd,
+                timeout=timeout,
+                text=True,
+                capture_output=capture_output,
+                shell=False,
+            )
+            return AgentExecution(
+                result.returncode,
+                result.stdout or "",
+                result.stderr or "",
+            )
+        except subprocess.TimeoutExpired as exc:
+            return AgentExecution(
+                124,
+                _text(exc.stdout),
+                _text(exc.stderr),
+                timed_out=True,
+            )
+        except FileNotFoundError:
+            return AgentExecution(127, stderr=f"Executable '{self.executable}' introuvable")
+
+
+class ClaudeCodeAdapter(AgentAdapter):
+    name = "claude-code"
+    executable = "claude"
+
+    def build_command(self, prompt: str, permission_mode: PermissionMode) -> list[str]:
+        return [
+            self.executable,
+            "--print",
+            "--permission-mode",
+            permission_mode,
+            prompt,
+        ]
+
+    def build_named_agent_command(self, agent_name: str, prompt: str) -> list[str]:
+        return [self.executable, "--print", "--agent", agent_name, prompt]
+
+
+class CodexAdapter(AgentAdapter):
+    name = "codex"
+    executable = "codex"
+
+    def build_command(self, prompt: str, permission_mode: PermissionMode) -> list[str]:
+        command = [self.executable, "exec", "--sandbox", "workspace-write"]
+        if permission_mode in {"auto", "acceptEdits"}:
+            command.append("--approve-for-me")
+        command.append(_portable_prompt(prompt))
+        return command
+
+
+class CursorAdapter(AgentAdapter):
+    name = "cursor"
+    executable = "cursor-agent"
+
+    def build_command(self, prompt: str, permission_mode: PermissionMode) -> list[str]:
+        command = [self.executable, "--print", "--output-format", "text"]
+        if permission_mode in {"auto", "acceptEdits"}:
+            command.append("--force")
+        command.append(_portable_prompt(prompt))
+        return command
+
+
+_AGENT_ADAPTERS = {
+    "claude": ClaudeCodeAdapter,
+    "claude-code": ClaudeCodeAdapter,
+    "codex": CodexAdapter,
+    "cursor": CursorAdapter,
+    "cursor-agent": CursorAdapter,
+}
+
+
+def get_agent_adapter(name: str) -> AgentAdapter:
+    try:
+        adapter_type = _AGENT_ADAPTERS[name.casefold()]
+    except KeyError as exc:
+        supported = ", ".join(sorted({kind().name for kind in _AGENT_ADAPTERS.values()}))
+        raise ValueError(f"Agent inconnu '{name}'. Agents supportés: {supported}") from exc
+    return adapter_type()
+
+
+def _portable_prompt(prompt: str) -> str:
+    """Traduit une slash-command Claude en instruction portable pour les autres agents."""
+    match = re.fullmatch(r"/devflow\.([a-z0-9-]+)(?:\s+(.*))?", prompt.strip())
+    if not match:
+        return prompt
+    command_name, arguments = match.groups()
+    arguments = arguments or ""
+    return (
+        f"Exécute strictement le workflow décrit dans "
+        f"commands/devflow.{command_name}.md avec $ARGUMENTS = {arguments!r}. "
+        "Travaille dans le dépôt courant et respecte toutes les validations de ce fichier."
+    )
+
+
+def _text(value: str | bytes | None) -> str:
+    if value is None:
+        return ""
+    return value.decode(errors="replace") if isinstance(value, bytes) else value

devflow_cli/adapters/linear.py

@@ -0,0 +1,79 @@
+"""Politique de synchronisation Linear, indépendante du transport MCP/API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from devflow_cli import STEP_LINEAR_MAPPING, STEP_LINEAR_ORDER
+
+
+LinearAction = Literal["update", "keep", "skip"]
+
+
+class LinearAdapter(Protocol):
+    """Transport minimal requis pour synchroniser le statut d'une issue."""
+
+    def get_status(self, issue_id: str) -> str | None: ...
+
+    def update_status(self, issue_id: str, status: str) -> None: ...
+
+
+@dataclass(frozen=True)
+class LinearDecision:
+    action: LinearAction
+    step: str
+    current_status: str | None
+    target_status: str | None
+    reason: str
+
+    @property
+    def should_update(self) -> bool:
+        return self.action == "update"
+
+    def to_dict(self) -> dict[str, str | bool | None]:
+        return {
+            "action": self.action,
+            "step": self.step,
+            "currentStatus": self.current_status,
+            "targetStatus": self.target_status,
+            "shouldUpdate": self.should_update,
+            "reason": self.reason,
+        }
+
+
+def decide_linear_transition(step: str, current_status: str | None) -> LinearDecision:
+    """Applique le mapping et la règle de non-régression canonique."""
+    target = STEP_LINEAR_MAPPING.get(step)
+    if target is None:
+        return LinearDecision("skip", step, current_status, None, "Étape sans statut Linear")
+    if current_status not in STEP_LINEAR_ORDER:
+        return LinearDecision(
+            "skip",
+            step,
+            current_status,
+            target,
+            "Statut Linear courant absent de l'ordre canonique",
+        )
+    current_index = STEP_LINEAR_ORDER.index(current_status)
+    target_index = STEP_LINEAR_ORDER.index(target)
+    if current_index >= target_index:
+        return LinearDecision(
+            "keep",
+            step,
+            current_status,
+            target,
+            "Statut courant identique ou plus avancé",
+        )
+    return LinearDecision("update", step, current_status, target, "Progression autorisée")
+
+
+def sync_linear_status(
+    adapter: LinearAdapter, issue_id: str, step: str
+) -> LinearDecision:
+    """Synchronise via un transport injecté lorsque la politique l'autorise."""
+    current_status = adapter.get_status(issue_id)
+    decision = decide_linear_transition(step, current_status)
+    if decision.should_update and decision.target_status is not None:
+        adapter.update_status(issue_id, decision.target_status)
+    return decision

devflow_cli/cli.py

@@ -18,6 +18,14 @@ from devflow_cli.commands.upgrade_cmd import upgrade
 from devflow_cli.commands.rollback import rollback
 from devflow_cli.commands.migrate_speckit import migrate_speckit
 from devflow_cli.commands import extension
+from devflow_cli.commands import hooks_cmd
+from devflow_cli.commands import linear
+from devflow_cli.commands import review
+from devflow_cli.commands import step
+from devflow_cli.commands.run import run
+from devflow_cli.commands.docs_sync import docs_sync
+from devflow_cli.commands.traceability import traceability
+from devflow_cli.commands.verify import verify
 
 app = typer.Typer(
     name="devflow",
@@ -53,6 +61,14 @@ app.command()(upgrade)
 app.command()(rollback)
 app.command(name="migrate-speckit")(migrate_speckit)
 app.add_typer(extension.app, name="extension")
+app.add_typer(hooks_cmd.app, name="hooks")
+app.add_typer(linear.app, name="linear")
+app.add_typer(step.app, name="step")
+app.add_typer(review.app, name="review")
+app.command()(run)
+app.command(name="docs-sync")(docs_sync)
+app.command()(traceability)
+app.command()(verify)
 
 
 if __name__ == "__main__":

devflow_cli/commands/docs_sync.py

@@ -0,0 +1,33 @@
+"""devflow docs-sync — Synchronise la documentation dérivée des constantes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from devflow_cli.core.docgen import sync_pipeline_docs
+from devflow_cli.utils.console import fail, ok
+
+
+def docs_sync(
+    path: Path = typer.Argument(Path("."), help="Racine du depot devflow"),
+    check: bool = typer.Option(False, "--check", help="Vérifie sans modifier"),
+) -> None:
+    """Génère les références du pipeline depuis les constantes Python."""
+    root = path.resolve()
+    try:
+        stale = sync_pipeline_docs(root, check=check)
+    except (OSError, ValueError) as exc:
+        fail(str(exc))
+        raise typer.Exit(1) from exc
+
+    if check and stale:
+        for path in stale:
+            fail(f"Documentation obsolète: {path.relative_to(root)}")
+        raise typer.Exit(1)
+    if stale:
+        for path in stale:
+            ok(f"Synchronisé: {path.relative_to(root)}")
+    else:
+        ok("Documentation déjà synchronisée.")

devflow_cli/commands/extension.py

@@ -76,7 +76,9 @@ def add(name: str = typer.Argument(..., help="Nom de l'extension a installer"))
         console.print("Utilisez 'devflow extension catalog' pour voir les extensions disponibles.")
         raise typer.Exit(1)
 
-    source_label = f" [{ext.source}]" if ext.source != "principal" else ""
+    # Des crochets nus sont interpretes comme du markup Rich et rendent le
+    # libelle invisible (ex: "[communaute]").
+    source_label = f" ({ext.source})" if ext.source != "principal" else ""
     console.print(f"Installation de '{name}'{source_label}...")
     console.print()
 

devflow_cli/commands/feature.py

@@ -65,7 +65,7 @@ def _init_feature_files(
 def feature(
     issue_id: str = typer.Argument(..., help="Identifiant de l'issue (ex: KS-123)"),
     short_name: Optional[str] = typer.Option(None, "--short-name", help="Nom court pour le repertoire (ex: user-auth)"),
-    fast: bool = typer.Option(False, "--fast", help="Mode minimal (4 etapes : spec, plan, tasks, implement)"),
+    fast: bool = typer.Option(False, "--fast", help="Mode accelere (9 etapes, dont 4 productives)"),
 ) -> None:
     """Initialise une feature : branche git + state.json + review-log.md."""
     _validate_issue_id(issue_id)
@@ -102,9 +102,9 @@ def feature(
     console.print(f"Feature [bold]{issue_id}[/bold] initialisee :")
     console.print(f"  Branche : {branch}")
     console.print(f"  Dossier : {feature_dir}/")
-    from devflow_cli import STEPS, OPTIONAL_STEPS
-    total = len(STEPS)
-    fast_count = total - len(OPTIONAL_STEPS)
+    from devflow_cli import FAST_STEP_COUNT, FULL_STEP_COUNT
+    total = FULL_STEP_COUNT
+    fast_count = FAST_STEP_COUNT
     console.print(f"  Mode    : {mode} ({fast_count} etapes)" if fast else f"  Mode    : {mode} ({total} etapes)")
     console.print(f"  Etat    : spec (etape initiale)")
     console.print()

devflow_cli/commands/hooks_cmd.py

@@ -0,0 +1,193 @@
+"""devflow hooks — Gestion et exécution contrôlée des hooks devflow."""
+
+from __future__ import annotations
+
+import stat
+import subprocess
+from pathlib import Path
+
+import typer
+
+from devflow_cli.core.git import is_git_repo
+from devflow_cli.core.hooks import (
+    DEFAULT_HOOK_TIMEOUT,
+    MAX_HOOK_TIMEOUT,
+    VALID_HOOK_POINTS,
+    run_hook_point,
+)
+from devflow_cli.utils.console import console, ok, fail, warn
+
+app = typer.Typer(help="Gestion et execution des hooks devflow")
+
+HOOKS_DIR_NAME = ".githooks"
+HOOK_FILES = ("post-checkout", "post-merge")
+
+
+def _configure_hooks_path(repo: Path) -> None:
+    subprocess.run(
+        ["git", "-C", str(repo), "config", "core.hooksPath", HOOKS_DIR_NAME],
+        check=True,
+        capture_output=True,
+    )
+
+
+def _current_hooks_path(repo: Path) -> str | None:
+    result = subprocess.run(
+        ["git", "-C", str(repo), "config", "--get", "core.hooksPath"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def _unset_hooks_path(repo: Path) -> None:
+    subprocess.run(
+        ["git", "-C", str(repo), "config", "--unset", "core.hooksPath"],
+        capture_output=True,
+    )
+
+
+@app.command("install")
+def install() -> None:
+    """Active les git hooks devflow (core.hooksPath + chmod +x)."""
+    repo = Path.cwd().resolve()
+
+    if not is_git_repo(repo):
+        fail(f"{repo} n'est pas un depot git.")
+        raise typer.Exit(1)
+
+    hooks_dir = repo / HOOKS_DIR_NAME
+    if not hooks_dir.is_dir():
+        fail(f"Dossier {HOOKS_DIR_NAME}/ introuvable a la racine du repo.")
+        raise typer.Exit(1)
+
+    missing = [h for h in HOOK_FILES if not (hooks_dir / h).is_file()]
+    if missing:
+        fail(f"Hooks manquants dans {HOOKS_DIR_NAME}/ : {', '.join(missing)}")
+        raise typer.Exit(1)
+
+    for name in HOOK_FILES:
+        path = hooks_dir / name
+        mode = path.stat().st_mode
+        path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        ok(f"chmod +x {HOOKS_DIR_NAME}/{name}")
+
+    _configure_hooks_path(repo)
+    ok(f"git config core.hooksPath {HOOKS_DIR_NAME}")
+
+    console.print()
+    console.print("[green]Hooks devflow actifs.[/green] Un checkout ou merge sur develop lancera `devflow init --here --force`.")
+
+
+@app.command("uninstall")
+def uninstall() -> None:
+    """Desactive les git hooks devflow (supprime core.hooksPath)."""
+    repo = Path.cwd().resolve()
+
+    if not is_git_repo(repo):
+        fail(f"{repo} n'est pas un depot git.")
+        raise typer.Exit(1)
+
+    current = _current_hooks_path(repo)
+    if current is None:
+        warn("core.hooksPath n'est pas configure — rien a desactiver.")
+        return
+
+    if current != HOOKS_DIR_NAME:
+        warn(f"core.hooksPath pointe sur '{current}' (pas sur '{HOOKS_DIR_NAME}'). Abandon.")
+        raise typer.Exit(1)
+
+    _unset_hooks_path(repo)
+    ok(f"git config core.hooksPath supprime (etait: {current})")
+
+
+@app.command("status")
+def status() -> None:
+    """Affiche l'etat des hooks devflow pour ce repo."""
+    repo = Path.cwd().resolve()
+
+    if not is_git_repo(repo):
+        fail(f"{repo} n'est pas un depot git.")
+        raise typer.Exit(1)
+
+    hooks_path = _current_hooks_path(repo)
+    hooks_dir = repo / HOOKS_DIR_NAME
+
+    console.print(f"Repo         : {repo}")
+    console.print(f"hooksPath    : {hooks_path or '[dim](non configure)[/dim]'}")
+    console.print(f"{HOOKS_DIR_NAME}/    : {'present' if hooks_dir.is_dir() else '[dim]absent[/dim]'}")
+
+    if hooks_dir.is_dir():
+        for name in HOOK_FILES:
+            p = hooks_dir / name
+            if not p.is_file():
+                console.print(f"  {name:<15} : [dim]absent[/dim]")
+                continue
+            executable = bool(p.stat().st_mode & stat.S_IXUSR)
+            console.print(f"  {name:<15} : present ({'exec' if executable else 'non-exec'})")
+
+    active = hooks_path == HOOKS_DIR_NAME and hooks_dir.is_dir()
+    console.print()
+    console.print(f"Statut       : {'[green]actif[/green]' if active else '[yellow]inactif[/yellow]'}")
+
+
+@app.command("run")
+def run(
+    hook_point: str = typer.Argument(..., help="Point de hook devflow"),
+    issue_id: str = typer.Argument(..., help="ID de l'issue courante"),
+    allow_shell: bool = typer.Option(
+        False,
+        "--allow-shell",
+        help="Autorise explicitement les hooks de type shell",
+    ),
+    timeout: int = typer.Option(
+        DEFAULT_HOOK_TIMEOUT,
+        min=1,
+        max=MAX_HOOK_TIMEOUT,
+        help="Timeout par defaut par hook",
+    ),
+) -> None:
+    """Execute un point de hook depuis devflow-hooks.yml."""
+    if hook_point not in VALID_HOOK_POINTS:
+        fail(f"Hook point inconnu: {hook_point}")
+        raise typer.Exit(1)
+
+    repo = Path.cwd().resolve()
+    hooks_file = repo / "devflow-hooks.yml"
+    if not hooks_file.is_file():
+        console.print("Aucun devflow-hooks.yml — rien a executer.")
+        return
+
+    try:
+        executions = run_hook_point(
+            hooks_file,
+            hook_point,
+            issue_id,
+            repo,
+            allow_shell=allow_shell,
+            default_timeout=timeout,
+        )
+    except (ValueError, PermissionError) as exc:
+        fail(str(exc))
+        raise typer.Exit(1) from exc
+
+    if not executions:
+        console.print(f"Aucun hook configure pour {hook_point}.")
+        return
+
+    failed = False
+    for execution in executions:
+        label = " ".join(execution.command)
+        if execution.succeeded:
+            ok(f"{execution.hook_type}: {label}")
+        else:
+            failed = True
+            reason = "timeout" if execution.timed_out else f"code {execution.returncode}"
+            fail(f"{execution.hook_type}: {label} ({reason})")
+            if execution.stderr.strip():
+                console.print(f"  {execution.stderr.strip()}")
+
+    if failed:
+        raise typer.Exit(1)

devflow_cli/commands/linear.py

@@ -0,0 +1,30 @@
+"""Commandes de politique Linear indépendantes du transport."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from devflow_cli.adapters.linear import decide_linear_transition
+from devflow_cli.utils.console import console
+
+
+app = typer.Typer(help="Évalue la politique de synchronisation Linear.")
+
+
+@app.command()
+def decision(
+    step: str = typer.Argument(..., help="Étape devflow"),
+    current_status: str = typer.Argument(..., help="Statut Linear courant"),
+    json_output: bool = typer.Option(False, "--json", help="Sortie JSON"),
+) -> None:
+    """Décide si le statut Linear peut progresser sans régression."""
+    result = decide_linear_transition(step, current_status)
+    if json_output:
+        console.print_json(json.dumps(result.to_dict(), ensure_ascii=False))
+        return
+    console.print(
+        f"{result.action}: {current_status} → {result.target_status or '—'} "
+        f"({result.reason})"
+    )