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

fde_workflow_cli/__init__.py

@@ -0,0 +1 @@
+"""The fde-workflow command line tool."""

fde_workflow_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m fde_workflow_cli`."""
+
+from fde_workflow_cli.main import app
+
+app(prog_name="fde-workflow")

fde_workflow_cli/clock.py

@@ -0,0 +1,7 @@
+"""Today's date, in one place so tests can fix it."""
+
+import datetime as dt
+
+
+def today() -> dt.date:
+    return dt.date.today()

fde_workflow_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""The CLI's command groups."""

fde_workflow_cli/commands/common.py

@@ -0,0 +1,87 @@
+"""Helpers shared by the commands."""
+
+import datetime as dt
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+
+from fde_workflow_cli import clock
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import Decision, DecisionType, Direction, DirectionPath, Kpi
+from fde_workflow_cli.store import Store, describe_validation_error, locate
+
+RootOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--root",
+        help="Repository with .fde/ (default: the closest one from the current directory).",
+    ),
+]
+
+
+def open_store(root: Path | None) -> Store:
+    return Store(root.resolve() if root else locate(Path.cwd()))
+
+
+@contextmanager
+def user_errors() -> Iterator[None]:
+    """Turn problems the user can fix into a one-line error and exit code 1."""
+    try:
+        yield
+    except FdeError as error:
+        typer.echo(f"Error: {error}", err=True)
+        raise typer.Exit(1) from error
+    except ValidationError as error:
+        typer.echo(f"Error: {describe_validation_error('The input', error)}", err=True)
+        raise typer.Exit(1) from error
+
+
+def require(value: str | None, option: str, why: str) -> str:
+    if not value:
+        raise FdeError(f"{option} is required {why}.")
+    return value
+
+
+def parse_date(text: str, option: str) -> dt.date:
+    try:
+        return dt.date.fromisoformat(text)
+    except ValueError as error:
+        raise FdeError(f"{option} must be a date like 2026-10-12, not {text!r}.") from error
+
+
+def find_kpi(direction: Direction, kpi_id: str) -> Kpi:
+    kpi = direction.kpi(kpi_id)
+    if kpi is None:
+        raise FdeError(f"There is no KPI {kpi_id}.")
+    return kpi
+
+
+def find_path(direction: Direction, path_id: str) -> DirectionPath:
+    path = direction.path(path_id)
+    if path is None:
+        raise FdeError(f"There is no path {path_id}.")
+    return path
+
+
+def record(
+    store: Store,
+    decision_type: DecisionType,
+    summary: str,
+    reason: str,
+    approved_by: str = "",
+    refs: list[str] | None = None,
+) -> None:
+    store.append_decision(
+        Decision(
+            date=clock.today(),
+            type=decision_type,
+            summary=summary,
+            reason=reason,
+            approved_by=approved_by,
+            refs=refs or [],
+        )
+    )

fde_workflow_cli/commands/decision.py

@@ -0,0 +1,31 @@
+"""`fde-workflow decision`: record a direction decision no other command records."""
+
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli.commands.common import RootOption, open_store, record, user_errors
+from fde_workflow_cli.model import DecisionType
+
+app = typer.Typer(help="Record direction decisions.", no_args_is_help=True)
+
+
+@app.command()
+def add(
+    summary: Annotated[str, typer.Option(help="What was decided.")],
+    reason: Annotated[str, typer.Option(help="Why.")],
+    decision_type: Annotated[
+        DecisionType, typer.Option("--type", help="Kind of decision.")
+    ] = DecisionType.OTHER,
+    approved_by: Annotated[str, typer.Option("--approved-by", help="Who approved it.")] = "",
+    ref: Annotated[
+        list[str] | None, typer.Option("--ref", help="Related id or URL; repeat it.")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Record a decision, e.g. a scope change."""
+    with user_errors():
+        store = open_store(root)
+        store.load()
+        record(store, decision_type, summary, reason, approved_by, ref or [])
+    typer.echo("Decision recorded.")

fde_workflow_cli/commands/hook.py

@@ -0,0 +1,52 @@
+"""`fde-workflow hook`: entry points of the plugin's hooks. A hook never fails a session."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import typer
+
+from fde_workflow_cli import rules, summary
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.store import Store, locate
+
+app = typer.Typer(help="Entry points of the Claude Code plugin hooks.", no_args_is_help=True)
+
+
+def session_context(payload: str) -> str | None:
+    """The context for a new session, or None when the repository has no .fde/."""
+    try:
+        data = json.loads(payload) if payload.strip() else {}
+    except json.JSONDecodeError:
+        data = {}
+    cwd = data.get("cwd") if isinstance(data, dict) else None
+    start = Path(cwd) if isinstance(cwd, str) else Path(os.environ.get("CLAUDE_PROJECT_DIR", "."))
+    store = Store(locate(start))
+    if not store.exists():
+        return None
+    try:
+        direction = store.load()
+        measurements = store.measurements()
+    except FdeError as error:
+        return (
+            f"{summary.CONTEXT_HEADER}\n\n.fde/ cannot be read: {error}\n"
+            "Run `fde-workflow validate`."
+        )
+    issues = rules.check(direction, measurements, store.dir)
+    return summary.context(direction, measurements, issues, brief=True)
+
+
+@app.command("session-start")
+def session_start() -> None:
+    """Print the direction as SessionStart context (reads the hook's JSON on stdin)."""
+    try:
+        text = session_context(sys.stdin.read())
+    except Exception as error:  # a hook must never interrupt the session
+        typer.echo(f"fde-workflow hook: {error}", err=True)
+        return
+    if text:
+        output = {
+            "hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": text}
+        }
+        typer.echo(json.dumps(output))

fde_workflow_cli/commands/kpi.py

@@ -0,0 +1,210 @@
+"""`fde-workflow kpi`: define KPIs and record their measurements."""
+
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import clock, recipes, rules
+from fde_workflow_cli.commands.common import (
+    RootOption,
+    find_kpi,
+    open_store,
+    parse_date,
+    record,
+    require,
+    user_errors,
+)
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import (
+    BaselineType,
+    Better,
+    DecisionType,
+    Kpi,
+    KpiKind,
+    Measurement,
+    Recipe,
+    RecipeType,
+)
+from fde_workflow_cli.summary import number
+
+app = typer.Typer(help="Define KPIs and record their measurements.", no_args_is_help=True)
+
+
+@app.command()
+def add(
+    kpi_id: Annotated[str, typer.Argument(help="Kebab-case id, e.g. resolution-time.")],
+    name: Annotated[str, typer.Option(help="Human-readable name.")],
+    kind: Annotated[KpiKind, typer.Option(help="primary, secondary or guardrail.")],
+    definition: Annotated[str, typer.Option(help="What it measures and its formula.")],
+    source: Annotated[str, typer.Option(help="Where the data comes from.")],
+    better: Annotated[Better, typer.Option("--direction", help="Which way is better.")],
+    target: Annotated[
+        float, typer.Option(help="Numeric target; for a guardrail, the worst acceptable value.")
+    ],
+    recipe_type: Annotated[RecipeType, typer.Option("--recipe-type", help="How to measure it.")],
+    recipe_file: Annotated[
+        str, typer.Option("--recipe-file", help="Inside .fde/, e.g. measures/resolution-time.sql.")
+    ],
+    unit: Annotated[str, typer.Option(help="Unit, e.g. min or %.")] = "",
+    window: Annotated[str, typer.Option(help="Measurement window in days, e.g. 28d.")] = "28d",
+    root: RootOption = None,
+) -> None:
+    """Define a KPI; its recipe file must already exist."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        if direction.kpi(kpi_id):
+            raise FdeError(f"KPI {kpi_id} already exists: use `fde-workflow kpi update`.")
+        direction.kpis.append(
+            Kpi(
+                id=kpi_id,
+                name=name,
+                kind=kind,
+                definition=definition,
+                source=source,
+                unit=unit,
+                direction=better,
+                target=target,
+                window=window,
+                recipe=Recipe(type=recipe_type, file=recipe_file),
+            )
+        )
+        store.save(direction)
+    typer.echo(f"Added KPI {kpi_id}.")
+
+
+@app.command()
+def update(
+    kpi_id: Annotated[str, typer.Argument()],
+    name: Annotated[str | None, typer.Option()] = None,
+    kind: Annotated[KpiKind | None, typer.Option()] = None,
+    definition: Annotated[str | None, typer.Option()] = None,
+    source: Annotated[str | None, typer.Option()] = None,
+    better: Annotated[Better | None, typer.Option("--direction")] = None,
+    target: Annotated[float | None, typer.Option()] = None,
+    unit: Annotated[str | None, typer.Option()] = None,
+    window: Annotated[str | None, typer.Option()] = None,
+    recipe_type: Annotated[RecipeType | None, typer.Option("--recipe-type")] = None,
+    recipe_file: Annotated[str | None, typer.Option("--recipe-file")] = None,
+    reason: Annotated[str | None, typer.Option(help="Why the target changes.")] = None,
+    approved_by: Annotated[
+        str | None, typer.Option("--approved-by", help="Who approves a target change.")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Change a KPI; changing its target records a decision."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        kpi = find_kpi(direction, kpi_id)
+        fields = {
+            "name": name,
+            "kind": kind,
+            "definition": definition,
+            "source": source,
+            "direction": better,
+            "target": target,
+            "unit": unit,
+            "window": window,
+        }
+        changes: dict[str, object] = {k: v for k, v in fields.items() if v is not None}
+        if recipe_type or recipe_file:
+            changes["recipe"] = Recipe(
+                type=recipe_type or kpi.recipe.type, file=recipe_file or kpi.recipe.file
+            )
+        target_changed = target is not None and target != kpi.target
+        if target_changed:
+            reason = require(reason, "--reason", "to change a target")
+            approved_by = require(approved_by, "--approved-by", "to change a target")
+        direction.kpis[direction.kpis.index(kpi)] = kpi.model_copy(update=changes)
+        store.save(direction)
+        if target_changed and target is not None:
+            record(
+                store,
+                DecisionType.TARGET_CHANGE,
+                f"Target of {kpi_id}: {number(kpi.target)} → {number(target)}",
+                reason or "",
+                approved_by or "",
+                [kpi_id],
+            )
+    typer.echo(f"Updated KPI {kpi_id}.")
+
+
+@app.command()
+def measure(
+    kpi_id: Annotated[str, typer.Argument()],
+    baseline: Annotated[
+        BaselineType | None, typer.Option(help="Record it as the KPI's baseline.")
+    ] = None,
+    window_end: Annotated[
+        str | None,
+        typer.Option("--window-end", help="Last day measured, YYYY-MM-DD (default: today)."),
+    ] = None,
+    value: Annotated[float | None, typer.Option(help="The measured value.")] = None,
+    source: Annotated[str | None, typer.Option(help="Where the value came from.")] = None,
+    factors: Annotated[
+        str, typer.Option(help="External factors that may have moved the value.")
+    ] = "",
+    run: Annotated[
+        bool, typer.Option("--run", help="Run a script recipe and record its output.")
+    ] = False,
+    root: RootOption = None,
+) -> None:
+    """Record a measurement; without --value or --run, show how to take it."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        kpi = find_kpi(direction, kpi_id)
+        start, end = kpi.window_ending(
+            parse_date(window_end, "--window-end") if window_end else clock.today()
+        )
+        if end > clock.today():
+            raise FdeError(f"--window-end {end} is in the future.")
+        fingerprint = recipes.fingerprint(store.dir, kpi.recipe)
+        if fingerprint is None:
+            raise FdeError(f"Recipe .fde/{kpi.recipe.file} does not exist: write it first.")
+        if kpi.recipe.type is RecipeType.SCRIPT:
+            if value is not None:
+                raise FdeError("Script recipes are run, not typed: use --run.")
+            if not run:
+                typer.echo(
+                    f"Would run .fde/{kpi.recipe.file} with FDE_WINDOW_START={start} "
+                    f"FDE_WINDOW_END={end}.\nAdd --run to execute it and record the result."
+                )
+                return
+            value = recipes.run_script(store.dir, kpi.recipe, start, end)
+            source = source or f"script .fde/{kpi.recipe.file}"
+        else:
+            if run:
+                raise FdeError(f"Only script recipes run; {kpi.id} has a {kpi.recipe.type} recipe.")
+            if value is None:
+                text = recipes.render(store.dir, kpi.recipe, start, end)
+                typer.echo(
+                    f"{kpi.recipe.type} recipe of {kpi.id}, window {start} to {end}:\n\n{text}\n"
+                    "Take the measurement, then record it with --value N --source TEXT."
+                )
+                return
+            source = require(source, "--source", "to record a measurement")
+        previous = rules.latest_baseline(store.measurements(), kpi.id)
+        store.append_measurement(
+            Measurement(
+                kpi=kpi.id,
+                taken=clock.today(),
+                window_start=start,
+                window_end=end,
+                value=value,
+                baseline=baseline,
+                source=source,
+                external_factors=factors,
+                recipe_sha256=fingerprint,
+            )
+        )
+    unit = f" {kpi.unit}" if kpi.unit else ""
+    label = f"{baseline} baseline" if baseline else "measurement"
+    typer.echo(f"Recorded {label} {kpi.id} = {number(value)}{unit} (window {start} to {end}).")
+    if baseline is None and previous is None:
+        typer.echo(f"! {kpi.id} has no baseline yet: this measurement is not one.")
+    elif baseline is None and previous is not None and previous.recipe_sha256 != fingerprint:
+        typer.echo(
+            "! [K4] The recipe changed after the baseline: measure it again with --baseline."
+        )

fde_workflow_cli/commands/northstar.py

@@ -0,0 +1,90 @@
+"""`fde-workflow northstar`: define, change and confirm the North Star."""
+
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli.commands.common import RootOption, open_store, record, require, user_errors
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import DecisionType, NorthStar
+
+app = typer.Typer(help="Define, change and confirm the North Star.", no_args_is_help=True)
+
+
+@app.command("set")
+def set_(
+    statement: Annotated[
+        str | None, typer.Option(help="The outcome, for someone; never a solution.")
+    ] = None,
+    beneficiary: Annotated[str | None, typer.Option(help="Who gets the outcome.")] = None,
+    problem: Annotated[str | None, typer.Option(help="The problem it solves.")] = None,
+    non_goal: Annotated[
+        list[str] | None,
+        typer.Option("--non-goal", help="Out of scope; repeat it, the list is replaced."),
+    ] = None,
+    primary_kpi: Annotated[
+        str | None, typer.Option("--primary-kpi", help="Id of the primary KPI.")
+    ] = None,
+    inferred: Annotated[
+        bool, typer.Option("--inferred", help="Inferred from existing work; needs confirmation.")
+    ] = False,
+    reason: Annotated[str | None, typer.Option(help="Why a confirmed North Star changes.")] = None,
+    approved_by: Annotated[
+        str | None, typer.Option("--approved-by", help="Who approves the change (the sponsor).")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Create the North Star, or change it; changing a confirmed one records a decision."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        current = direction.north_star
+        if current is None:
+            new = NorthStar(
+                statement=require(statement, "--statement", "to create the North Star"),
+                beneficiary=beneficiary or "",
+                problem=problem or "",
+                non_goals=non_goal or [],
+                primary_kpi=primary_kpi,
+                confirmed=not inferred,
+            )
+        else:
+            fields = {
+                "statement": statement,
+                "beneficiary": beneficiary,
+                "problem": problem,
+                "non_goals": non_goal,
+                "primary_kpi": primary_kpi,
+            }
+            changes: dict[str, object] = {k: v for k, v in fields.items() if v is not None}
+            if inferred:
+                changes["confirmed"] = False
+            new = current.model_copy(update=changes)
+        is_change = current is not None and current.confirmed and new != current
+        if is_change:
+            reason = require(reason, "--reason", "to change a confirmed North Star")
+            approved_by = require(approved_by, "--approved-by", "to change a confirmed North Star")
+        direction.north_star = new
+        store.save(direction)
+        if is_change:
+            record(
+                store,
+                DecisionType.NORTH_STAR_CHANGE,
+                f"North Star: {new.statement}",
+                reason or "",
+                approved_by or "",
+            )
+    typer.echo("North Star changed." if is_change else "North Star saved.")
+
+
+@app.command()
+def confirm(root: RootOption = None) -> None:
+    """Mark an inferred North Star as confirmed."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        if direction.north_star is None:
+            raise FdeError("There is no North Star to confirm.")
+        direction.north_star.confirmed = True
+        store.save(direction)
+    typer.echo("North Star confirmed.")