fde-workflow-cli 0.1.0__py3-none-any.whl

fde_workflow_cli/doctor.py

@@ -0,0 +1,45 @@
+"""Readiness checks behind `fde-workflow doctor`. Add one function per check to CHECKS."""
+
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import SCHEMA_VERSION
+from fde_workflow_cli.store import Store, locate
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    ok: bool
+    message: str
+
+
+MINIMUM_PYTHON = (3, 13)
+
+
+def check_python() -> CheckResult:
+    found = ".".join(str(part) for part in sys.version_info[:3])
+    if sys.version_info >= MINIMUM_PYTHON:
+        return CheckResult(ok=True, message=f"Python {found}")
+    return CheckResult(ok=False, message=f"Python {found} is too old: install Python 3.13 or newer")
+
+
+def check_direction() -> CheckResult:
+    store = Store(locate(Path.cwd()))
+    if not store.exists():
+        return CheckResult(ok=True, message="No .fde/ here yet: the adopt skill sets one up")
+    try:
+        store.load()
+    except FdeError as error:
+        first_line = str(error).splitlines()[0]
+        return CheckResult(ok=False, message=f".fde/ cannot be read: {first_line}")
+    return CheckResult(ok=True, message=f".fde/ uses schema {SCHEMA_VERSION}: {store.dir}")
+
+
+CHECKS: list[Callable[[], CheckResult]] = [check_python, check_direction]
+
+
+def run_checks() -> list[CheckResult]:
+    return [check() for check in CHECKS]

fde_workflow_cli/errors.py

@@ -0,0 +1,5 @@
+"""The error type for problems the user can fix."""
+
+
+class FdeError(Exception):
+    """A problem the user can fix; the message says how."""

fde_workflow_cli/main.py

@@ -0,0 +1,62 @@
+"""Commands of the fde-workflow command line tool."""
+
+from importlib.metadata import version
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import doctor as checks
+from fde_workflow_cli.commands import decision, hook, kpi, northstar, path, project, stage
+
+COMMAND = "fde-workflow"
+DIST_NAME = "fde-workflow-cli"
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"{COMMAND} {version(DIST_NAME)}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    show_version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_print_version,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Command line tool of the fde-workflow Claude Code plugin."""
+
+
+@app.command()
+def doctor() -> None:
+    """Check that fde-workflow is ready to use."""
+    results = checks.run_checks()
+    for result in results:
+        typer.echo(f"{'✓' if result.ok else '✗'} {result.message}")
+    problems = sum(not result.ok for result in results)
+    if problems:
+        typer.echo(f"Not ready: {problems} problem(s).")
+        raise typer.Exit(1)
+    typer.echo("Ready.")
+
+
+app.command()(project.init)
+app.command("detect")(project.detect_command)
+app.command()(project.validate)
+app.command()(project.status)
+app.command()(project.context)
+app.add_typer(project.app, name="project")
+app.add_typer(kpi.app, name="kpi")
+app.add_typer(northstar.app, name="northstar")
+app.add_typer(path.app, name="path")
+app.add_typer(stage.app, name="stage")
+app.add_typer(decision.app, name="decision")
+app.add_typer(hook.app, name="hook")

fde_workflow_cli/model.py

@@ -0,0 +1,226 @@
+"""The direction framework's data model: what the files in `.fde/` contain."""
+
+import datetime as dt
+from enum import StrEnum
+from pathlib import PurePosixPath
+from typing import Annotated, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    FiniteFloat,
+    StringConstraints,
+    field_validator,
+    model_validator,
+)
+
+SCHEMA_VERSION = 1
+
+Identifier = Annotated[str, StringConstraints(pattern=r"^[a-z0-9]+(-[a-z0-9]+)*$")]
+Window = Annotated[str, StringConstraints(pattern=r"^[1-9][0-9]*d$")]
+
+
+class StageName(StrEnum):
+    DISCOVERY = "discovery"
+    POC = "poc"
+    MVP = "mvp"
+    EARLY_ACCESS = "early-access"
+    PRODUCTION = "production"
+    CLOSED = "closed"
+
+
+STAGE_ORDER: list[StageName] = list(StageName)
+
+
+class Outcome(StrEnum):
+    COMPLETED = "completed"
+    DISCONTINUED = "discontinued"
+
+
+class GateDecision(StrEnum):
+    GO = "go"
+    RECYCLE = "recycle"
+    HOLD = "hold"
+    KILL = "kill"
+
+
+class KpiKind(StrEnum):
+    PRIMARY = "primary"
+    SECONDARY = "secondary"
+    GUARDRAIL = "guardrail"
+
+
+class Better(StrEnum):
+    INCREASE = "increase"
+    DECREASE = "decrease"
+
+
+class RecipeType(StrEnum):
+    SCRIPT = "script"
+    QUERY = "query"
+    MANUAL = "manual"
+
+
+class PathStatus(StrEnum):
+    PROPOSED = "proposed"
+    ACTIVE = "active"
+    MEASURING = "measuring"
+    VALIDATED = "validated"
+    DISCARDED = "discarded"
+
+
+class BaselineType(StrEnum):
+    HISTORICAL = "historical"
+    LATE = "late"
+
+
+class DecisionType(StrEnum):
+    NORTH_STAR_CHANGE = "north-star-change"
+    TARGET_CHANGE = "target-change"
+    PATH_OPEN = "path-open"
+    PATH_VALIDATE = "path-validate"
+    PATH_DISCARD = "path-discard"
+    STAGE_GATE = "stage-gate"
+    STAGE_SET = "stage-set"
+    SCOPE_CHANGE = "scope-change"
+    OTHER = "other"
+
+
+class Record(BaseModel):
+    """Base of every model: unknown keys are errors, so typos in hand-edited files surface."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Project(Record):
+    name: str = Field(min_length=1)
+    customer: str = ""
+    sponsor: str = ""
+
+
+class NorthStar(Record):
+    statement: str = Field(min_length=1)
+    beneficiary: str = ""
+    problem: str = ""
+    non_goals: list[str] = Field(default_factory=list)
+    primary_kpi: Identifier | None = None
+    confirmed: bool = True
+
+
+class StageState(Record):
+    current: StageName = StageName.DISCOVERY
+    entered: dt.date
+    outcome: Outcome | None = None
+    on_hold: bool = False
+    confirmed: bool = True
+    gate_criteria: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _outcome_only_when_closed(self) -> Self:
+        if (self.current is StageName.CLOSED) != (self.outcome is not None):
+            raise ValueError("outcome must be set when, and only when, the stage is closed")
+        return self
+
+
+class Recipe(Record):
+    type: RecipeType
+    file: str = Field(min_length=1)
+
+
+class Kpi(Record):
+    id: Identifier
+    name: str = Field(min_length=1)
+    kind: KpiKind
+    definition: str = Field(min_length=1)
+    source: str = Field(min_length=1)
+    unit: str = ""
+    direction: Better
+    target: FiniteFloat
+    window: Window = "28d"
+    recipe: Recipe
+
+    def window_ending(self, end: dt.date) -> tuple[dt.date, dt.date]:
+        """The measurement window (first day, last day) that ends on `end`."""
+        days = int(self.window.removesuffix("d"))
+        return end - dt.timedelta(days=days - 1), end
+
+
+class DirectionPath(Record):
+    id: Identifier
+    hypothesis: str = Field(min_length=1)
+    expects: dict[Identifier, FiniteFloat]
+    status: PathStatus = PathStatus.PROPOSED
+    activated: dt.date | None = None
+    maturity: StageName | None = None
+    confirmed: bool = True
+    links: list[str] = Field(default_factory=list)
+    learning: str | None = None
+
+
+class Artifacts(Record):
+    globs: list[str] = Field(default_factory=list)
+    pre_framework: list[str] = Field(default_factory=list)
+
+    @field_validator("globs")
+    @classmethod
+    def _globs_stay_inside_the_repository(cls, globs: list[str]) -> list[str]:
+        for pattern in globs:
+            path = PurePosixPath(pattern)
+            if not pattern or path.is_absolute() or ".." in path.parts:
+                raise ValueError(f"{pattern!r} must be a relative pattern inside the repository")
+        return globs
+
+
+class Direction(Record):
+    schema_version: int = SCHEMA_VERSION
+    project: Project
+    north_star: NorthStar | None = None
+    stage: StageState
+    kpis: list[Kpi] = Field(default_factory=list)
+    paths: list[DirectionPath] = Field(default_factory=list)
+    artifacts: Artifacts = Field(default_factory=Artifacts)
+
+    @model_validator(mode="after")
+    def _ids_are_unique(self) -> Self:
+        for label, ids in (
+            ("KPI", [k.id for k in self.kpis]),
+            ("path", [p.id for p in self.paths]),
+        ):
+            duplicates = sorted({i for i in ids if ids.count(i) > 1})
+            if duplicates:
+                raise ValueError(f"duplicate {label} id(s): {', '.join(duplicates)}")
+        return self
+
+    def kpi(self, kpi_id: str) -> Kpi | None:
+        return next((k for k in self.kpis if k.id == kpi_id), None)
+
+    def path(self, path_id: str) -> DirectionPath | None:
+        return next((p for p in self.paths if p.id == path_id), None)
+
+
+class Measurement(Record):
+    kpi: Identifier
+    taken: dt.date
+    window_start: dt.date
+    window_end: dt.date
+    value: FiniteFloat
+    baseline: BaselineType | None = None
+    source: str = Field(min_length=1)
+    external_factors: str = ""
+    recipe_sha256: str
+
+    @model_validator(mode="after")
+    def _window_is_ordered(self) -> Self:
+        if self.window_start > self.window_end:
+            raise ValueError("window_start must not be after window_end")
+        return self
+
+
+class Decision(Record):
+    date: dt.date
+    type: DecisionType
+    summary: str = Field(min_length=1)
+    reason: str = Field(min_length=1)
+    approved_by: str = ""
+    refs: list[str] = Field(default_factory=list)

fde_workflow_cli/recipes.py

@@ -0,0 +1,79 @@
+"""Measurement recipes: where they live, their fingerprint, and running script recipes."""
+
+import datetime as dt
+import hashlib
+import math
+import os
+import subprocess
+from pathlib import Path
+
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import Recipe
+
+SCRIPT_TIMEOUT_SECONDS = 600
+
+
+def recipe_path(fde_dir: Path, recipe: Recipe) -> Path:
+    """Return the recipe's file, which must stay inside `.fde/`."""
+    path = (fde_dir / recipe.file).resolve()
+    if not path.is_relative_to(fde_dir.resolve()):
+        raise FdeError(f"Recipe {recipe.file!r} must be inside .fde/ (e.g. measures/<kpi>.sql).")
+    return path
+
+
+def fingerprint(fde_dir: Path, recipe: Recipe) -> str | None:
+    """SHA-256 of the recipe file, or None when the file does not exist."""
+    path = recipe_path(fde_dir, recipe)
+    if not path.is_file():
+        return None
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def render(fde_dir: Path, recipe: Recipe, start: dt.date, end: dt.date) -> str:
+    """The recipe's text with its window placeholders filled in."""
+    text = recipe_path(fde_dir, recipe).read_text(encoding="utf-8")
+    return text.replace("{{window_start}}", start.isoformat()).replace(
+        "{{window_end}}", end.isoformat()
+    )
+
+
+def run_script(fde_dir: Path, recipe: Recipe, start: dt.date, end: dt.date) -> float:
+    """Run a script recipe from the repository root and return the number it prints."""
+    path = recipe_path(fde_dir, recipe)
+    if not os.access(path, os.X_OK):
+        raise FdeError(f"{path} is not executable: run `chmod +x {path}`.")
+    env = {**os.environ, "FDE_WINDOW_START": start.isoformat(), "FDE_WINDOW_END": end.isoformat()}
+    try:
+        result = subprocess.run(  # noqa: S603 - the project's own recipe, run only with --run
+            [str(path)],
+            cwd=fde_dir.parent,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=SCRIPT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except OSError as error:
+        raise FdeError(
+            f"Recipe {recipe.file} cannot be executed ({error.strerror}): start it with a "
+            "shebang such as #!/bin/sh."
+        ) from error
+    except subprocess.TimeoutExpired as error:
+        raise FdeError(
+            f"Recipe {recipe.file} did not finish in {SCRIPT_TIMEOUT_SECONDS} s."
+        ) from error
+    if result.returncode != 0:
+        raise FdeError(
+            f"Recipe {recipe.file} failed with exit code {result.returncode}:\n"
+            f"{result.stderr.strip()}"
+        )
+    output = result.stdout.strip()
+    try:
+        value = float(output)
+    except ValueError as error:
+        raise FdeError(
+            f"Recipe {recipe.file} must print one number; it printed {output!r}."
+        ) from error
+    if not math.isfinite(value):
+        raise FdeError(f"Recipe {recipe.file} must print a finite number; it printed {output!r}.")
+    return value

fde_workflow_cli/rules.py

@@ -0,0 +1,168 @@
+"""The framework's rules (spec §2), checked over a whole `.fde/`."""
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from fde_workflow_cli import recipes
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import (
+    Direction,
+    DirectionPath,
+    KpiKind,
+    Measurement,
+    PathStatus,
+    StageName,
+)
+
+STAGES_THAT_MEASURE = (StageName.MVP, StageName.EARLY_ACCESS, StageName.PRODUCTION)
+
+
+@dataclass(frozen=True)
+class Issue:
+    level: Literal["error", "warning"]
+    rule: str
+    message: str
+
+
+def check(direction: Direction, measurements: list[Measurement], fde_dir: Path) -> list[Issue]:
+    """Every broken rule, errors first. Errors block writes; warnings are reported."""
+    issues = [
+        *_north_star(direction),
+        *_kpis(direction, measurements, fde_dir),
+        *_paths(direction, measurements),
+        *_stage(direction, measurements),
+    ]
+    return sorted(issues, key=lambda issue: issue.level != "error")
+
+
+def latest_baseline(measurements: list[Measurement], kpi_id: str) -> Measurement | None:
+    """The KPI's most recently recorded baseline (files keep recording order)."""
+    baselines = [m for m in measurements if m.kpi == kpi_id and m.baseline is not None]
+    return baselines[-1] if baselines else None
+
+
+def has_evidence(path: DirectionPath, measurements: list[Measurement]) -> bool:
+    """P2: a non-baseline measurement of a targeted KPI whose whole window follows activation."""
+    activated = path.activated
+    if activated is None:
+        return False
+    return any(
+        m.kpi in path.expects and m.baseline is None and m.window_start > activated
+        for m in measurements
+    )
+
+
+def _north_star(direction: Direction) -> Iterator[Issue]:
+    north_star = direction.north_star
+    if north_star is None:
+        yield Issue("warning", "N1", "No North Star yet: define it with the discovery skill.")
+        return
+    if not north_star.confirmed:
+        yield Issue(
+            "warning",
+            "C1",
+            "The North Star was inferred and is not confirmed: "
+            "`fde-workflow northstar confirm` once the FDE and the sponsor agree.",
+        )
+    if north_star.primary_kpi is None:
+        yield Issue("warning", "N1", "The North Star has no primary KPI yet.")
+        return
+    kpi = direction.kpi(north_star.primary_kpi)
+    if kpi is None:
+        yield Issue(
+            "error", "N1", f"The North Star's primary KPI {north_star.primary_kpi} does not exist."
+        )
+    elif kpi.kind is not KpiKind.PRIMARY:
+        yield Issue(
+            "error",
+            "K2",
+            f"The North Star's primary KPI {kpi.id} has kind {kpi.kind}, not primary.",
+        )
+
+
+def _kpis(direction: Direction, measurements: list[Measurement], fde_dir: Path) -> Iterator[Issue]:
+    primaries = [kpi.id for kpi in direction.kpis if kpi.kind is KpiKind.PRIMARY]
+    if len(primaries) > 1:
+        yield Issue("error", "K2", f"Only one KPI can be primary; found {', '.join(primaries)}.")
+    for kpi in direction.kpis:
+        try:
+            current = recipes.fingerprint(fde_dir, kpi.recipe)
+        except FdeError as error:
+            yield Issue("error", "M1", f"KPI {kpi.id}: {error}")
+            continue
+        if current is None:
+            yield Issue(
+                "error",
+                "M1",
+                f"KPI {kpi.id}: recipe .fde/{kpi.recipe.file} does not exist; write it first.",
+            )
+            continue
+        baseline = latest_baseline(measurements, kpi.id)
+        if baseline is None:
+            yield Issue(
+                "warning",
+                "K3",
+                f"KPI {kpi.id} has no baseline: measure it before work that should move it starts.",
+            )
+        elif baseline.recipe_sha256 != current:
+            yield Issue(
+                "warning",
+                "K4",
+                f"KPI {kpi.id}: the recipe changed after the baseline, so comparisons are not "
+                "valid; measure the baseline again with --baseline.",
+            )
+
+
+def _paths(direction: Direction, measurements: list[Measurement]) -> Iterator[Issue]:
+    for path in direction.paths:
+        if not path.expects:
+            yield Issue("error", "P1", f"Path {path.id} targets no KPI.")
+        for kpi_id in path.expects:
+            if direction.kpi(kpi_id) is None:
+                yield Issue("error", "P1", f"Path {path.id} targets unknown KPI {kpi_id}.")
+        if path.status is PathStatus.VALIDATED and not has_evidence(path, measurements):
+            yield Issue(
+                "error",
+                "P2",
+                f"Path {path.id} cannot be validated without evidence: it needs a measurement of "
+                f"{', '.join(path.expects)} whose window starts after it became active.",
+            )
+        if not path.confirmed:
+            yield Issue(
+                "warning",
+                "C1",
+                f"Path {path.id} was inferred and is not confirmed: `fde-workflow path confirm`.",
+            )
+
+
+def _stage(direction: Direction, measurements: list[Measurement]) -> Iterator[Issue]:
+    stage = direction.stage
+    if not stage.confirmed:
+        yield Issue(
+            "warning",
+            "C1",
+            "The stage was inferred and is not confirmed: `fde-workflow stage confirm`.",
+        )
+    if stage.current is StageName.CLOSED:
+        return
+    if not stage.gate_criteria:
+        yield Issue(
+            "warning",
+            "S1",
+            f"Stage {stage.current} has no gate criteria: agree them with the sponsor now, "
+            "not when leaving the stage.",
+        )
+    primary = direction.north_star.primary_kpi if direction.north_star else None
+    if (
+        stage.current in STAGES_THAT_MEASURE
+        and primary is not None
+        and not any(m.kpi == primary and m.window_end >= stage.entered for m in measurements)
+    ):
+        yield Issue(
+            "warning",
+            "S3",
+            f"Primary KPI {primary} has no measurement since entering {stage.current} "
+            f"on {stage.entered}.",
+        )