devflow-toolkit 0.3.0__py3-none-any.whl

devflow/commands/spec.py

@@ -0,0 +1,514 @@
+"""Implementation of the devflow spec command."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from devflow.adapters.base import execute_invocation
+from devflow.commands.harness import (
+  adapter_for,
+  print_setup_result,
+  resolve_harness,
+  validate_harness_name,
+)
+from devflow.core.architecture import ArchitectureError
+from devflow.core.artifacts.errors import ArtifactError
+from devflow.core.config import (
+  EXECUTION_MODES,
+  ConfigError,
+  ConfigManager,
+  DevFlowConfig,
+  canonical_execution_mode,
+)
+from devflow.core.constitution import ConstitutionError
+from devflow.core.discovery import DiscoveryError
+from devflow.core.profile_manager import ProfileError
+from devflow.core.project import ProjectDetector
+from devflow.core.spec_workflow import (
+  SpecWorkflow,
+  SpecWorkflowRequest,
+  SpecWorkflowResult,
+)
+from devflow.core.state import (
+  StateError,
+  WorkflowLocator,
+  WorkflowStateManager,
+  WorkflowStatus,
+)
+from devflow.models.project import (
+  PROJECT_MODES,
+  canonical_project_mode,
+)
+from devflow.prompts import PromptError
+
+console = Console()
+error_console = Console(stderr=True)
+
+
+def spec(
+  description: Optional[str] = typer.Argument(
+    None,
+    help=(
+      "Description of the new change. Omit it when using --continue."
+    ),
+  ),
+  path: Path = typer.Argument(
+    Path("."),
+    help="Project root or a path inside it.",
+  ),
+  harness: Optional[str] = typer.Option(
+    None,
+    "--harness",
+    help=(
+      "Agent harness for this run: auto, codex, opencode, claude-code, "
+      "kiro or none."
+    ),
+  ),
+  mode: Optional[str] = typer.Option(
+    None,
+    "--mode",
+    help="Agent execution mode: interactive or non-interactive.",
+  ),
+  no_agent: bool = typer.Option(
+    False,
+    "--no-agent",
+    help="Use deterministic static analysis without invoking an agent.",
+  ),
+  project_mode: Optional[str] = typer.Option(
+    None,
+    "--project-mode",
+    help=(
+      "Specification context: existing (default) or greenfield."
+    ),
+  ),
+  continue_id: Optional[str] = typer.Option(
+    None,
+    "--continue",
+    help=(
+      "Resume an existing change by id (006) or directory name. "
+      "Does not create a new specification."
+    ),
+  ),
+) -> None:
+  """Generate or resume a specification for a change request."""
+  try:
+    _create_specification(
+      description,
+      path,
+      harness,
+      mode,
+      no_agent,
+      project_mode,
+      continue_id,
+    )
+  except (
+    ArchitectureError,
+    ConfigError,
+    ConstitutionError,
+    DiscoveryError,
+    ProfileError,
+    PromptError,
+    StateError,
+    ArtifactError,
+    FileNotFoundError,
+    NotADirectoryError,
+    OSError,
+  ) as error:
+    error_console.print(f"[red]Error:[/red] {error}")
+    raise typer.Exit(code=1) from error
+
+
+def _create_specification(
+  description: Optional[str],
+  path: Path,
+  harness: Optional[str],
+  mode: Optional[str],
+  no_agent: bool,
+  project_mode: Optional[str],
+  continue_id: Optional[str],
+) -> None:
+  request = (description or "").strip()
+  resume = (continue_id or "").strip() or None
+  if resume is not None and request:
+    # `devflow spec --continue 001 .` binds the path to the first
+    # positional argument. Treat an existing directory as the project
+    # path and keep --continue unambiguous.
+    candidate = Path(request).expanduser()
+    if path == Path(".") and candidate.is_dir():
+      path = candidate
+      request = ""
+    else:
+      msg = (
+        "Pass either a new change description or --continue, not both. "
+        "--continue reuses the request stored in discovery.yaml."
+      )
+      raise ConfigError(msg)
+  if resume is None and not request:
+    msg = (
+      "The change description cannot be empty. Use "
+      "'devflow spec \"...\"' or 'devflow spec --continue <id>'."
+    )
+    raise ConfigError(msg)
+
+  detector = ProjectDetector()
+  root = detector.find_root(path)
+  config = ConfigManager(root).load()
+
+  if resume is not None:
+    _ensure_continuable(config, resume)
+
+  requested_harness = validate_harness_name(
+    "none" if no_agent else (harness or config.agent_harness)
+  )
+  execution_mode, mode_warnings = _execution_mode(
+    mode or config.execution_mode,
+  )
+  effective_project_mode = _project_mode(
+    project_mode or config.project_mode,
+  )
+
+  allow_prompt = sys.stdin.isatty()
+  selected_harness, selection_warnings = resolve_harness(
+    requested_harness,
+    allow_prompt=allow_prompt,
+    require_installed=True,
+  )
+  adapter = adapter_for(selected_harness) if selected_harness else None
+
+  workflow = SpecWorkflow(executor=execute_invocation)
+  result = workflow.run(
+    SpecWorkflowRequest(
+      description=request,
+      config=config,
+      execution_mode=execution_mode,
+      adapter=adapter,
+      warnings=tuple([*mode_warnings, *selection_warnings]),
+      project_mode=effective_project_mode,
+      continue_spec_id=resume,
+    )
+  )
+
+  console.print(
+    f"[bold]Project mode:[/bold] {result.project_mode}"
+  )
+  if result.architecture_digest is not None:
+    console.print(
+      f"[bold]Architecture digest:[/bold] "
+      f"{result.architecture_digest}",
+      soft_wrap=True,
+    )
+  if result.discovery is not None:
+    console.print(
+      f"[bold]Discovery:[/bold] {result.discovery.status} "
+      f"({len(result.discovery.pending_blocking)} blocking, "
+      f"{len(result.discovery.pending_assumptions)} assumptions)"
+    )
+    if result.discovery_digest:
+      console.print(
+        f"[bold]Discovery digest:[/bold] {result.discovery_digest}",
+        soft_wrap=True,
+      )
+  if result.harness_name is not None:
+    console.print(
+      f"[bold]Agent harness:[/bold] {result.harness_name} "
+      f"({result.execution_mode})"
+    )
+  _print_warnings(list(result.warnings))
+  if result.setup_result is not None:
+    print_setup_result(result.setup_result, config.root, console)
+  _print_warnings(list(result.run_warnings))
+
+  if result.blocked:
+    _print_blocked(result=result, config=config)
+  elif result.spec_reused and result.spec is not None:
+    console.print(
+      f"[bold green]Specification {result.spec.spec_id} is current."
+      "[/bold green] No changes were made."
+    )
+    console.print(
+      f"[bold]File:[/bold] "
+      f"{result.spec.path.relative_to(config.root)}",
+      soft_wrap=True,
+    )
+  else:
+    _print_result(result=result, config=config)
+
+  _record_workflow(
+    config=config,
+    result=result,
+    workflow=workflow,
+  )
+
+
+def _ensure_continuable(config: DevFlowConfig, selector: str) -> None:
+  """Reject continuing a change whose specification is already approved."""
+  manager = WorkflowStateManager(
+    config.specifications_path,
+    project_root=config.root,
+  )
+  location = WorkflowLocator(config.specifications_path).find(selector)
+  state = manager.load(location)
+  allowed = {
+    WorkflowStatus.DRAFT.value,
+    WorkflowStatus.AWAITING_CLARIFICATION.value,
+  }
+  if state.status not in allowed or "spec" in state.approvals:
+    msg = (
+      f"Change '{location.change}' is already approved or advanced "
+      f"({state.status}). --continue does not regenerate approved "
+      "artifacts. Start a new specification or request an explicit "
+      "revision."
+    )
+    raise StateError(msg)
+
+
+def _record_workflow(
+  *,
+  config: DevFlowConfig,
+  result: SpecWorkflowResult,
+  workflow: SpecWorkflow,
+) -> None:
+  """Register Discovery and the specification in the workflow state."""
+  directory = result.directory
+  if directory is None:
+    return
+  manager = WorkflowStateManager(
+    config.specifications_path,
+    project_root=config.root,
+  )
+  manager.initialize_change(directory)
+  location = WorkflowLocator(
+    config.specifications_path
+  ).from_directory(directory)
+
+  if result.discovery_path is not None and result.discovery is not None:
+    manager.record_artifact(
+      location,
+      stage="discovery",
+      path=result.discovery_path,
+      validated=result.discovery.is_complete,
+      source=result.discovery_source,
+    )
+
+  if result.spec is not None:
+    content = result.spec.path.read_text(encoding="utf-8")
+    valid, _ = workflow.manager.validate(
+      content,
+      project_mode=result.project_mode,
+      architecture=result.architecture,
+      discovery_digest=result.discovery_digest,
+    )
+    source = (
+      "deterministic"
+      if result.spec.source == "static"
+      else result.spec.source
+    )
+    if result.spec_written:
+      _invalidate_replaced_spec(
+        manager=manager,
+        location=location,
+        path=result.spec.path,
+      )
+    metadata: dict[str, str] = {}
+    if result.discovery_digest:
+      metadata["discovery_digest"] = result.discovery_digest
+    if result.architecture_digest:
+      metadata["architecture_digest"] = result.architecture_digest
+    manager.record_artifact(
+      location,
+      stage="spec",
+      path=result.spec.path,
+      validated=valid,
+      source=source,
+      metadata=metadata,
+    )
+
+  state = manager.load(location)
+  if result.blocked:
+    _invalidate_outdated_spec(
+      manager=manager,
+      location=location,
+      result=result,
+    )
+    state = manager.transition(
+      location,
+      WorkflowStatus.AWAITING_CLARIFICATION.value,
+    )
+  elif state.status == WorkflowStatus.AWAITING_CLARIFICATION.value:
+    state = manager.transition(
+      location,
+      WorkflowStatus.DRAFT.value,
+    )
+
+  console.print(
+    "[bold]Workflow:[/bold] "
+    f"{state.status} · metadata in "
+    f"{location.directory.relative_to(config.root).as_posix()}"
+  )
+
+
+def _invalidate_replaced_spec(
+  *,
+  manager: WorkflowStateManager,
+  location,
+  path: Path,
+) -> None:
+  """Mark the previous specification stale before writing a new digest."""
+  state = manager.load(location)
+  record = state.artifacts.get("spec")
+  if record is None:
+    return
+  current_digest = manager.store.digest_file(path)
+  if record.digest == current_digest:
+    return
+  manager.invalidate_artifact(
+    location,
+    stage="spec",
+    kind="spec",
+  )
+
+
+def _invalidate_outdated_spec(
+  *,
+  manager: WorkflowStateManager,
+  location,
+  result: SpecWorkflowResult,
+) -> None:
+  """Mark a specification stale when Discovery changed under it."""
+  if not result.discovery_digest:
+    return
+  state = manager.load(location)
+  record = state.artifacts.get("spec")
+  if record is None:
+    return
+  recorded = str(record.metadata.get("discovery_digest", ""))
+  if recorded and recorded != result.discovery_digest:
+    manager.invalidate_artifact(
+      location,
+      stage="spec",
+      kind="spec",
+    )
+
+
+def _project_mode(project_mode: str) -> str:
+  normalized = canonical_project_mode(project_mode)
+  if normalized not in PROJECT_MODES:
+    msg = (
+      f"Unknown project mode: {project_mode}. "
+      f"Supported values: {', '.join(PROJECT_MODES)}."
+    )
+    raise ConfigError(msg)
+  return normalized
+
+
+def _execution_mode(mode: str) -> tuple[str, list[str]]:
+  normalized = canonical_execution_mode(mode)
+  if normalized not in EXECUTION_MODES:
+    msg = (
+      f"Unknown execution mode: {mode}. "
+      f"Supported values: {', '.join(EXECUTION_MODES)}."
+    )
+    raise ConfigError(msg)
+
+  warnings: list[str] = []
+  if normalized == "interactive" and not sys.stdin.isatty():
+    warnings.append(
+      "Interactive mode requires a terminal. This run will use "
+      "non-interactive mode."
+    )
+    normalized = "non-interactive"
+  return normalized, warnings
+
+
+def _print_warnings(warnings: list[str]) -> None:
+  for warning in warnings:
+    console.print(f"[yellow]Warning:[/yellow] {warning}")
+
+
+def _print_blocked(
+  *,
+  result: SpecWorkflowResult,
+  config: DevFlowConfig,
+) -> None:
+  discovery = result.discovery
+  console.print(
+    "[bold yellow]Discovery is awaiting clarification."
+    "[/bold yellow] No specification was generated."
+  )
+  if result.discovery_path is not None:
+    console.print(
+      f"[bold]Discovery file:[/bold] "
+      f"{result.discovery_path.relative_to(config.root)}",
+      soft_wrap=True,
+    )
+  if discovery is None:
+    return
+  blockers = discovery.blockers()
+  if blockers:
+    console.print("\n[bold]Pending decisions[/bold]")
+    for blocker in blockers:
+      console.print(f"  - {blocker}", soft_wrap=True)
+  console.print(
+    "\nAnswer the pending questions and explicitly accept or reject "
+    "each proposed assumption. Edit discovery.yaml, or run an "
+    "interactive harness, then resume:"
+  )
+  console.print(
+    f"  devflow spec --continue {discovery.spec_id}",
+    soft_wrap=True,
+  )
+
+
+def _print_result(
+  *,
+  result: SpecWorkflowResult,
+  config: DevFlowConfig,
+) -> None:
+  for warning in result.constitution_warnings:
+    console.print(f"[yellow]Warning:[/yellow] {warning}")
+
+  spec = result.spec
+  if spec is None:
+    return
+  console.print(
+    f"[bold green]Specification {spec.spec_id} created.[/bold green]"
+  )
+  console.print(
+    f"[bold]File:[/bold] {spec.path.relative_to(config.root)}",
+    soft_wrap=True,
+  )
+  if result.harness_name is not None and spec.source != "static":
+    console.print(
+      f"[bold]Generated by:[/bold] {spec.source}"
+    )
+  else:
+    console.print("[bold]Generated by:[/bold] deterministic analysis")
+    if result.harness_name is not None:
+      console.print(
+        "[dim]The harness was available but its output could not be "
+        "validated.[/dim]"
+      )
+  console.print(
+    "[bold]Profiles:[/bold] "
+    + (", ".join(config.profiles) or "base only")
+  )
+  console.print(
+    "[bold]Constitution:[/bold] "
+    + ", ".join(result.constitution_names)
+  )
+  console.print(
+    f"[bold]Open questions:[/bold] {len(spec.open_questions)}"
+  )
+  if result.discovery is not None:
+    console.print(
+      f"[bold]Discovery:[/bold] {result.discovery.status}"
+    )
+  console.print(
+    "\nNext: review the specification, resolve any remaining "
+    "non-blocking questions, and approve it before implementation."
+  )

devflow/commands/status.py

@@ -0,0 +1,156 @@
+"""Implementation of the devflow status command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devflow.core.artifacts.errors import ArtifactError
+from devflow.core.config import (
+  ConfigError,
+  ConfigManager,
+  DevFlowConfig,
+)
+from devflow.core.discovery import DiscoveryError, DiscoveryManager
+from devflow.core.project import ProjectDetector
+from devflow.core.state import (
+  ChangeLocation,
+  StateError,
+  WorkflowLocator,
+  WorkflowStateManager,
+)
+
+console = Console()
+error_console = Console(stderr=True)
+
+
+def status(
+  spec_id: str = typer.Argument(
+    ...,
+    help="Change id (001) or change directory (001-add-health).",
+  ),
+  path: Path = typer.Argument(
+    Path("."),
+    help="Project root or a path inside it.",
+  ),
+) -> None:
+  """Show workflow state, artifact digests and approvals."""
+  try:
+    _status(spec_id, path)
+  except (
+    ConfigError,
+    StateError,
+    ArtifactError,
+    FileNotFoundError,
+    NotADirectoryError,
+    OSError,
+  ) as error:
+    error_console.print(f"[red]Error:[/red] {error}")
+    raise typer.Exit(code=1) from error
+
+
+def _status(spec_id: str, path: Path) -> None:
+  root = ProjectDetector().find_root(path)
+  config = ConfigManager(root).load()
+  manager = WorkflowStateManager(
+    config.specifications_path,
+    project_root=config.root,
+  )
+  location = WorkflowLocator(config.specifications_path).find(spec_id)
+  current = manager.status(location)
+  state = current.state
+
+  console.print(f"[bold]Change:[/bold] {location.change}")
+  console.print(f"[bold]Spec id:[/bold] {location.spec_id}")
+  console.print(f"[bold]Status:[/bold] {state.status}")
+  console.print(f"[bold]Updated:[/bold] {state.updated_at or 'unknown'}")
+  if current.last_event is not None:
+    console.print(
+      f"[bold]Last event:[/bold] #{current.last_event.seq} "
+      f"{current.last_event.type}"
+    )
+  else:
+    console.print("[bold]Last event:[/bold] none")
+
+  if state.artifacts:
+    console.print("\n[bold]Artifacts[/bold]")
+    for kind, record in sorted(state.artifacts.items()):
+      console.print(
+        f"  {kind}: {record.status} · {record.digest} · "
+        f"{record.path}",
+        soft_wrap=True,
+      )
+  else:
+    console.print("\n[yellow]No artifacts are registered.[/yellow]")
+
+  _print_discovery(config=config, location=location)
+
+  if state.approvals:
+    console.print("\n[bold]Approvals[/bold]")
+    for stage, approval in sorted(state.approvals.items()):
+      bound = ", ".join(
+        f"{kind}={digest}"
+        for kind, digest in sorted(approval.artifacts.items())
+      )
+      console.print(
+        f"  {stage}: {approval.by} at {approval.at} · {bound}",
+        soft_wrap=True,
+      )
+
+  if current.warnings:
+    console.print("\n[bold]Warnings[/bold]")
+    for warning in current.warnings:
+      console.print(f"[yellow]- {warning}[/yellow]")
+  if current.orphans:
+    console.print(
+      "\n[dim]Orphan artifacts were written without a workflow event. "
+      "They are not approved and do not advance the change.[/dim]"
+    )
+
+
+def _print_discovery(
+  *,
+  config: DevFlowConfig,
+  location: ChangeLocation,
+) -> None:
+  manager = DiscoveryManager(config.root)
+  if not manager.exists(location.directory):
+    return
+  console.print("\n[bold]Discovery[/bold]")
+  try:
+    discovery = manager.load(location.directory, required=True)
+  except DiscoveryError as error:
+    console.print(f"[yellow]- invalid discovery: {error}[/yellow]")
+    return
+  if discovery is None:
+    return
+  console.print(
+    f"  status: {discovery.status} · "
+    f"{len(discovery.pending_blocking)} blocking · "
+    f"{len(discovery.pending_assumptions)} assumptions"
+  )
+  for question in discovery.questions:
+    marker = "blocking" if question.blocking else "non-blocking"
+    answer = (
+      f" -> {question.answer}"
+      if question.answer
+      else " (pending)"
+    )
+    console.print(
+      f"  {question.id} [{question.category}, {marker}] "
+      f"{question.status}{answer}",
+      soft_wrap=True,
+    )
+  for assumption in discovery.assumptions:
+    state = (
+      f"accepted by {assumption.accepted_by}"
+      if assumption.is_accepted
+      else "pending acceptance"
+    )
+    console.print(
+      f"  {assumption.id} [{assumption.source}] {state}: "
+      f"{assumption.value}",
+      soft_wrap=True,
+    )

devflow/core/__init__.py

@@ -0,0 +1,15 @@
+"""Core services for DevFlow."""
+
+from devflow.core.config import ConfigManager
+from devflow.core.constitution import ConstitutionLoader
+from devflow.core.profile_manager import ProfileManager
+from devflow.core.project import ProjectDetector
+from devflow.core.specification import SpecificationManager
+
+__all__ = [
+  "ConfigManager",
+  "ConstitutionLoader",
+  "ProfileManager",
+  "ProjectDetector",
+  "SpecificationManager",
+]