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

fde_workflow_cli/commands/path.py

@@ -0,0 +1,257 @@
+"""`fde-workflow path`: open paths, move them through their life cycle, link execution work."""
+
+import datetime as dt
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import clock
+from fde_workflow_cli.commands.common import (
+    RootOption,
+    find_path,
+    open_store,
+    parse_date,
+    record,
+    require,
+    user_errors,
+)
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import DecisionType, DirectionPath, PathStatus, StageName
+
+app = typer.Typer(help="Manage paths: hypotheses that move the KPIs.", no_args_is_help=True)
+
+TRANSITIONS: dict[PathStatus, set[PathStatus]] = {
+    PathStatus.PROPOSED: {PathStatus.ACTIVE, PathStatus.DISCARDED},
+    PathStatus.ACTIVE: {PathStatus.MEASURING, PathStatus.DISCARDED},
+    PathStatus.MEASURING: {PathStatus.VALIDATED, PathStatus.DISCARDED, PathStatus.ACTIVE},
+    PathStatus.VALIDATED: set(),
+    PathStatus.DISCARDED: set(),
+}
+STATUSES_AT_ADD = (PathStatus.PROPOSED, PathStatus.ACTIVE, PathStatus.MEASURING)
+
+
+def parse_expects(items: list[str]) -> dict[str, float]:
+    expects: dict[str, float] = {}
+    for item in items:
+        kpi_id, separator, value = item.partition("=")
+        if not separator:
+            raise FdeError(f"--expects {item!r} must look like KPI_ID=VALUE.")
+        try:
+            expects[kpi_id.strip()] = float(value)
+        except ValueError as error:
+            raise FdeError(f"--expects {item!r}: {value!r} is not a number.") from error
+    return expects
+
+
+def normalise_ref(root: Path, ref: str) -> str:
+    """URLs stay as they are; files become POSIX paths relative to the repository root."""
+    if "://" in ref:
+        return ref
+    path = Path(ref)
+    absolute = (path if path.is_absolute() else Path.cwd() / path).resolve()
+    if absolute.is_relative_to(root.resolve()):
+        return absolute.relative_to(root.resolve()).as_posix()
+    return path.as_posix()
+
+
+@app.command()
+def add(
+    path_id: Annotated[str, typer.Argument(help="Kebab-case id, e.g. auto-triage.")],
+    hypothesis: Annotated[
+        str, typer.Option(help='"If we do X, we expect KPI Y to go from A to B."')
+    ],
+    expects: Annotated[
+        list[str], typer.Option("--expects", help="KPI_ID=VALUE expected; repeat per KPI.")
+    ],
+    reason: Annotated[
+        str | None, typer.Option(help="Why the path opens (not needed with --inferred).")
+    ] = None,
+    status: Annotated[
+        PathStatus, typer.Option(help="Initial status: proposed, active or measuring.")
+    ] = PathStatus.PROPOSED,
+    activated: Annotated[
+        str | None, typer.Option(help="When work started, YYYY-MM-DD (default: today).")
+    ] = None,
+    maturity: Annotated[
+        StageName | None, typer.Option(help="The path's own stage, when it differs.")
+    ] = None,
+    link: Annotated[
+        list[str] | None, typer.Option("--link", help="Execution artifact; repeat it.")
+    ] = None,
+    inferred: Annotated[
+        bool, typer.Option("--inferred", help="Inferred from existing work; needs confirmation.")
+    ] = False,
+    root: RootOption = None,
+) -> None:
+    """Open a path; records a path-open decision unless it is --inferred."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        if direction.path(path_id):
+            raise FdeError(f"Path {path_id} already exists: use `fde-workflow path update`.")
+        if status not in STATUSES_AT_ADD:
+            raise FdeError("A path starts as proposed, active or measuring; use `path move` later.")
+        if not inferred:
+            reason = require(reason, "--reason", "to open a path (or use --inferred)")
+        started: dt.date | None = None
+        if activated:
+            started = parse_date(activated, "--activated")
+        elif status is not PathStatus.PROPOSED:
+            started = clock.today()
+        direction.paths.append(
+            DirectionPath(
+                id=path_id,
+                hypothesis=hypothesis,
+                expects=parse_expects(expects),
+                status=status,
+                activated=started,
+                maturity=maturity,
+                confirmed=not inferred,
+                links=[normalise_ref(store.root, ref) for ref in link or []],
+            )
+        )
+        store.save(direction)
+        if not inferred:
+            record(
+                store,
+                DecisionType.PATH_OPEN,
+                f"Open path {path_id}: {hypothesis}",
+                reason or "",
+                refs=[path_id],
+            )
+    typer.echo(f"Added path {path_id} ({status}{', inferred' if inferred else ''}).")
+
+
+@app.command()
+def update(
+    path_id: Annotated[str, typer.Argument()],
+    hypothesis: Annotated[str | None, typer.Option()] = None,
+    expects: Annotated[
+        list[str] | None, typer.Option("--expects", help="Replaces every expectation.")
+    ] = None,
+    maturity: Annotated[StageName | None, typer.Option()] = None,
+    learning: Annotated[str | None, typer.Option()] = None,
+    root: RootOption = None,
+) -> None:
+    """Change a path's hypothesis, expectations, maturity or learning."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        path = find_path(direction, path_id)
+        if hypothesis is not None:
+            path.hypothesis = hypothesis
+        if expects is not None:
+            path.expects = parse_expects(expects)
+        if maturity is not None:
+            path.maturity = maturity
+        if learning is not None:
+            path.learning = learning
+        store.save(direction)
+    typer.echo(f"Updated path {path_id}.")
+
+
+@app.command()
+def move(
+    path_id: Annotated[str, typer.Argument()],
+    status: Annotated[PathStatus, typer.Argument(help="The new status.")],
+    reason: Annotated[str, typer.Option(help="Why the status changes.")],
+    learning: Annotated[
+        str | None, typer.Option(help="What the path taught us (required to discard).")
+    ] = None,
+    approved_by: Annotated[str | None, typer.Option("--approved-by")] = None,
+    root: RootOption = None,
+) -> None:
+    """Move a path: proposed → active → measuring → validated | discarded."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        path = find_path(direction, path_id)
+        if status not in TRANSITIONS[path.status]:
+            allowed = ", ".join(sorted(TRANSITIONS[path.status])) or "none, it is final"
+            raise FdeError(
+                f"Path {path_id} cannot go from {path.status} to {status} (allowed: {allowed})."
+            )
+        if status is PathStatus.DISCARDED and not learning:
+            raise FdeError("--learning is required to discard a path: what did it teach us?")
+        path.status = status
+        if status is PathStatus.ACTIVE and path.activated is None:
+            path.activated = clock.today()
+        if learning:
+            path.learning = learning
+        store.save(direction)
+        if status is PathStatus.VALIDATED:
+            record(
+                store,
+                DecisionType.PATH_VALIDATE,
+                f"Validate path {path_id}",
+                reason,
+                approved_by or "",
+                [path_id],
+            )
+        if status is PathStatus.DISCARDED:
+            record(
+                store,
+                DecisionType.PATH_DISCARD,
+                f"Discard path {path_id}",
+                reason,
+                approved_by or "",
+                [path_id],
+            )
+    typer.echo(f"Path {path_id} is now {status}.")
+
+
+@app.command()
+def link(
+    refs: Annotated[
+        list[str], typer.Argument(help="PATH_ID REF..., or REF... with --pre-framework.")
+    ],
+    pre_framework: Annotated[
+        bool, typer.Option("--pre-framework", help="Mark artifacts as pre-framework instead.")
+    ] = False,
+    root: RootOption = None,
+) -> None:
+    """Link execution artifacts (files or URLs) to a path, or mark them pre-framework."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        known = direction.artifacts.pre_framework
+        if pre_framework:
+            targets = [normalise_ref(store.root, ref) for ref in refs]
+            known.extend(ref for ref in dict.fromkeys(targets) if ref not in known)
+            message = f"Marked {len(targets)} artifact(s) as pre-framework."
+        else:
+            if len(refs) < 2:
+                raise FdeError("Usage: fde-workflow path link PATH_ID REF... (or --pre-framework).")
+            path = find_path(direction, refs[0])
+            targets = [normalise_ref(store.root, ref) for ref in refs[1:]]
+            path.links.extend(ref for ref in dict.fromkeys(targets) if ref not in path.links)
+            direction.artifacts.pre_framework = [ref for ref in known if ref not in targets]
+            message = f"Linked {len(targets)} artifact(s) to {path.id}."
+        store.save(direction)
+    typer.echo(message)
+
+
+@app.command()
+def confirm(
+    path_id: Annotated[str, typer.Argument()],
+    reason: Annotated[
+        str, typer.Option(help="Why it is confirmed.")
+    ] = "Confirmed a path inferred from existing work.",
+    root: RootOption = None,
+) -> None:
+    """Mark an inferred path as confirmed; records a path-open decision."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        path = find_path(direction, path_id)
+        path.confirmed = True
+        store.save(direction)
+        record(
+            store,
+            DecisionType.PATH_OPEN,
+            f"Confirm path {path_id}: {path.hypothesis}",
+            reason,
+            refs=[path_id],
+        )
+    typer.echo(f"Path {path_id} confirmed.")

fde_workflow_cli/commands/project.py

@@ -0,0 +1,123 @@
+"""Commands on the whole `.fde/`: init, detect, validate, status and context."""
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import clock, detect, rules, summary
+from fde_workflow_cli.commands.common import RootOption, open_store, user_errors
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import Artifacts, Direction, Project, StageState
+from fde_workflow_cli.store import Store, locate
+
+app = typer.Typer(help="Name the project, its customer and its sponsor.", no_args_is_help=True)
+
+
+def init(
+    root: RootOption = None,
+    name: Annotated[
+        str | None, typer.Option(help="Project name (default: the directory's name).")
+    ] = None,
+    preset: Annotated[
+        detect.Preset, typer.Option(help="Where execution artifacts live (auto detects it).")
+    ] = detect.Preset.AUTO,
+    glob: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--glob", help="Where execution artifacts live; repeat it; overrides --preset."
+        ),
+    ] = None,
+) -> None:
+    """Create .fde/ with an empty direction in stage discovery."""
+    with user_errors():
+        directory = (root or Path.cwd()).resolve()
+        if root is None and locate(directory) != directory:
+            raise FdeError(
+                f"{locate(directory)} already has .fde/: run the commands from there, "
+                "or pass --root to create a separate direction on purpose."
+            )
+        store = Store(directory)
+        globs = glob or detect.globs_for(preset, directory)
+        store.create(
+            Direction(
+                project=Project(name=name or directory.name),
+                stage=StageState(entered=clock.today()),
+                artifacts=Artifacts(globs=globs),
+            )
+        )
+    typer.echo(
+        f"Created {store.dir} (stage discovery; artifact globs: {', '.join(globs) or 'none'})."
+    )
+
+
+def detect_command(root: RootOption = None) -> None:
+    """Print the repository's methodology, artifacts and deployment signals as JSON."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load() if store.exists() else None
+        typer.echo(json.dumps(detect.report(store.root, direction), indent=2))
+
+
+def validate(root: RootOption = None) -> None:
+    """Check .fde/ against the framework's rules; exit 1 when a rule is broken."""
+    with user_errors():
+        store = open_store(root)
+        issues = rules.check(store.load(), store.measurements(), store.dir)
+    for issue in issues:
+        typer.echo(f"{'✗' if issue.level == 'error' else '!'} [{issue.rule}] {issue.message}")
+    errors = sum(issue.level == "error" for issue in issues)
+    warnings = len(issues) - errors
+    if errors:
+        typer.echo(f"Invalid: {errors} error(s), {warnings} warning(s).")
+        raise typer.Exit(1)
+    typer.echo(f"Valid with {warnings} warning(s)." if warnings else "Valid.")
+
+
+def status(root: RootOption = None) -> None:
+    """Summarise the direction for people."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        measurements = store.measurements()
+        issues = rules.check(direction, measurements, store.dir)
+    typer.echo(summary.render(direction, measurements, issues))
+
+
+def context(
+    root: RootOption = None,
+    brief: Annotated[bool, typer.Option("--brief", help="Only what every session needs.")] = False,
+) -> None:
+    """Summarise the direction for Claude."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        measurements = store.measurements()
+        issues = rules.check(direction, measurements, store.dir)
+    typer.echo(summary.context(direction, measurements, issues, brief=brief))
+
+
+@app.command("set")
+def set_project(
+    name: Annotated[str | None, typer.Option(help="Project name.")] = None,
+    customer: Annotated[str | None, typer.Option(help="The customer.")] = None,
+    sponsor: Annotated[
+        str | None, typer.Option(help="Who approves direction changes and gate decisions.")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Set the project's name, customer or sponsor."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        changes = {
+            k: v
+            for k, v in {"name": name, "customer": customer, "sponsor": sponsor}.items()
+            if v is not None
+        }
+        if not changes:
+            raise FdeError("Nothing to change: pass --name, --customer or --sponsor.")
+        direction.project = direction.project.model_copy(update=changes)
+        store.save(direction)
+    typer.echo("Project updated.")

fde_workflow_cli/commands/stage.py

@@ -0,0 +1,155 @@
+"""`fde-workflow stage`: set the project stage, its gate criteria and gate decisions."""
+
+from typing import Annotated
+
+import typer
+
+from fde_workflow_cli import clock
+from fde_workflow_cli.commands.common import (
+    RootOption,
+    open_store,
+    parse_date,
+    record,
+    require,
+    user_errors,
+)
+from fde_workflow_cli.errors import FdeError
+from fde_workflow_cli.model import (
+    STAGE_ORDER,
+    DecisionType,
+    GateDecision,
+    Outcome,
+    StageName,
+    StageState,
+)
+
+app = typer.Typer(help="Set the project stage and record gate decisions.", no_args_is_help=True)
+
+
+@app.command("set")
+def set_(
+    stage: Annotated[StageName, typer.Argument(help="The stage the project is in.")],
+    reason: Annotated[str, typer.Option(help="Why the stage is set without a gate.")],
+    outcome: Annotated[
+        Outcome | None, typer.Option(help="Required when the stage is closed.")
+    ] = None,
+    entered: Annotated[
+        str | None, typer.Option(help="When the project got there, YYYY-MM-DD (default: today).")
+    ] = None,
+    inferred: Annotated[
+        bool, typer.Option("--inferred", help="Inferred from evidence; needs confirmation.")
+    ] = False,
+    approved_by: Annotated[str | None, typer.Option("--approved-by")] = None,
+    root: RootOption = None,
+) -> None:
+    """Set the stage directly, without a gate (e.g. when adopting an existing project)."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        direction.stage = StageState(
+            current=stage,
+            entered=parse_date(entered, "--entered") if entered else clock.today(),
+            outcome=outcome,
+            confirmed=not inferred,
+        )
+        store.save(direction)
+        suffix = " (inferred)" if inferred else ""
+        record(
+            store,
+            DecisionType.STAGE_SET,
+            f"Stage set to {stage}{suffix}",
+            reason,
+            approved_by or "",
+        )
+    typer.echo(f"Stage set to {stage}{suffix}.")
+
+
+@app.command()
+def confirm(root: RootOption = None) -> None:
+    """Mark an inferred stage as confirmed."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        direction.stage.confirmed = True
+        store.save(direction)
+    typer.echo(f"Stage {direction.stage.current} confirmed.")
+
+
+@app.command()
+def criteria(
+    items: Annotated[list[str], typer.Argument(help="One argument per gate criterion.")],
+    reason: Annotated[str | None, typer.Option(help="Why agreed criteria change.")] = None,
+    approved_by: Annotated[
+        str | None, typer.Option("--approved-by", help="Who approves the change.")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Set the current stage's gate criteria; replacing agreed criteria records a decision."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        stage = direction.stage
+        replacing = bool(stage.gate_criteria) and stage.gate_criteria != items
+        if replacing:
+            reason = require(reason, "--reason", "to change agreed gate criteria")
+            approved_by = require(approved_by, "--approved-by", "to change agreed gate criteria")
+        stage.gate_criteria = list(items)
+        store.save(direction)
+        if replacing:
+            record(
+                store,
+                DecisionType.STAGE_GATE,
+                f"Gate criteria of {stage.current} changed",
+                reason or "",
+                approved_by or "",
+            )
+    typer.echo(f"Gate criteria of {stage.current}: {len(items)}.")
+
+
+@app.command()
+def decide(
+    gate: Annotated[GateDecision, typer.Argument(help="go, recycle, hold or kill.")],
+    reason: Annotated[str, typer.Option(help="The evidence behind the decision.")],
+    approved_by: Annotated[str, typer.Option("--approved-by", help="The sponsor.")],
+    to: Annotated[
+        StageName | None, typer.Option("--to", help="With go: skip to a later stage.")
+    ] = None,
+    root: RootOption = None,
+) -> None:
+    """Record a gate decision and apply it to the stage."""
+    with user_errors():
+        store = open_store(root)
+        direction = store.load()
+        before = direction.stage
+        if before.current is StageName.CLOSED:
+            raise FdeError("The project is closed.")
+        if to is not None and gate is not GateDecision.GO:
+            raise FdeError("--to only applies to go.")
+        today = clock.today()
+        if gate is GateDecision.GO:
+            position = STAGE_ORDER.index(before.current)
+            target = to or STAGE_ORDER[position + 1]
+            if STAGE_ORDER.index(target) <= position:
+                raise FdeError(f"--to must be a stage after {before.current}.")
+            if target is StageName.CLOSED and before.current is not StageName.PRODUCTION:
+                raise FdeError("Only go from production closes a project; otherwise use kill.")
+            outcome = Outcome.COMPLETED if target is StageName.CLOSED else None
+            direction.stage = StageState(current=target, entered=today, outcome=outcome)
+        elif gate is GateDecision.KILL:
+            direction.stage = StageState(
+                current=StageName.CLOSED, entered=today, outcome=Outcome.DISCONTINUED
+            )
+        else:
+            before.on_hold = gate is GateDecision.HOLD
+        store.save(direction)
+        after = direction.stage.current
+        record(
+            store,
+            DecisionType.STAGE_GATE,
+            f"{gate} at {before.current}" + (f" → {after}" if after != before.current else ""),
+            reason,
+            approved_by,
+        )
+    typer.echo(
+        f"Recorded {gate}; stage is {after}{' (on hold)' if direction.stage.on_hold else ''}."
+    )

fde_workflow_cli/detect.py

@@ -0,0 +1,123 @@
+"""Find the execution methodology and its artifacts in a repository. Read-only."""
+
+import subprocess
+from enum import StrEnum
+from pathlib import Path
+
+from fde_workflow_cli.model import Direction
+
+
+class Preset(StrEnum):
+    AUTO = "auto"
+    SUPERPOWERS = "superpowers"
+    SPEC_KIT = "spec-kit"
+    NONE = "none"
+
+
+PRESET_GLOBS: dict[Preset, list[str]] = {
+    Preset.SUPERPOWERS: ["docs/superpowers/specs/**", "docs/superpowers/plans/**"],
+    Preset.SPEC_KIT: ["specs/**"],
+    Preset.NONE: [],
+}
+DEPLOYMENT_MARKERS = (
+    "Dockerfile",
+    "docker-compose.yml",
+    "compose.yaml",
+    "Procfile",
+    "fly.toml",
+    "vercel.json",
+    "netlify.toml",
+    "render.yaml",
+    "app.yaml",
+    "serverless.yml",
+    "k8s",
+    "helm",
+    "terraform",
+)
+DEPLOYMENT_WORKFLOW_WORDS = ("deploy", "release", "publish")
+READMES = ("README.md", "README.rst", "README.txt", "README")
+
+
+def detect_methodology(root: Path) -> Preset:
+    if (root / "docs" / "superpowers").is_dir():
+        return Preset.SUPERPOWERS
+    if (root / ".specify").is_dir() or (root / "specs").is_dir():
+        return Preset.SPEC_KIT
+    return Preset.NONE
+
+
+def globs_for(preset: Preset, root: Path) -> list[str]:
+    resolved = detect_methodology(root) if preset is Preset.AUTO else preset
+    return list(PRESET_GLOBS[resolved])
+
+
+def artifact_files(root: Path, globs: list[str]) -> list[str]:
+    """Files under `root` matching any glob, as sorted POSIX paths relative to `root`."""
+    found: set[str] = set()
+    for pattern in globs:
+        for path in root.glob(pattern):
+            if path.is_file():
+                found.add(path.relative_to(root).as_posix())
+    return sorted(found)
+
+
+def first_commit_date(root: Path, relative: str) -> str | None:
+    """Date (YYYY-MM-DD) of the commit that added the file, or None outside git history."""
+    try:
+        result = subprocess.run(  # noqa: S603 - fixed read-only git query
+            ["git", "log", "--diff-filter=A", "--format=%cs", "--", relative],  # noqa: S607
+            cwd=root,
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    dates = result.stdout.split()
+    return dates[-1] if result.returncode == 0 and dates else None
+
+
+def deployment_signals(root: Path) -> list[str]:
+    signals = [name for name in DEPLOYMENT_MARKERS if (root / name).exists()]
+    workflows = root / ".github" / "workflows"
+    if workflows.is_dir():
+        signals += sorted(
+            f".github/workflows/{path.name}"
+            for path in workflows.iterdir()
+            if any(word in path.name.lower() for word in DEPLOYMENT_WORKFLOW_WORDS)
+        )
+    return signals
+
+
+def linked_to(direction: Direction | None, relative: str) -> str | None:
+    """The path id that links the artifact, "pre-framework", or None."""
+    if direction is None:
+        return None
+    for path in direction.paths:
+        if relative in path.links:
+            return path.id
+    if relative in direction.artifacts.pre_framework:
+        return "pre-framework"
+    return None
+
+
+def report(root: Path, direction: Direction | None) -> dict[str, object]:
+    methodology = detect_methodology(root)
+    globs = direction.artifacts.globs if direction else PRESET_GLOBS[methodology]
+    return {
+        "root": str(root),
+        "fde_initialised": direction is not None,
+        "methodology": methodology.value,
+        "globs": globs,
+        "readme": next((name for name in READMES if (root / name).is_file()), None),
+        "deployment_signals": deployment_signals(root),
+        "artifacts": [
+            {
+                "path": relative,
+                "first_commit": first_commit_date(root, relative),
+                "linked_to": linked_to(direction, relative),
+            }
+            for relative in artifact_files(root, globs)
+        ],
+    }