devflow-toolkit 0.3.0__py3-none-any.whl

devflow/commands/init.py

@@ -0,0 +1,544 @@
+"""Implementation of the devflow init 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.agents import AgentsFileWriter
+from devflow.commands.harness import (
+  adapter_for,
+  print_setup_result,
+  resolve_harness,
+  validate_harness_name,
+)
+from devflow.core.architecture import (
+  ARCHITECTURE_RELATIVE_PATH,
+  ArchitectureError,
+  create_architecture_template,
+)
+from devflow.core.config import (
+  EXECUTION_MODES,
+  ConfigError,
+  ConfigManager,
+  DevFlowConfig,
+  canonical_execution_mode,
+)
+from devflow.core.constitution import Constitution, ConstitutionLoader
+from devflow.core.ports import (
+  FileChange,
+  SetupResult,
+  build_setup_context,
+)
+from devflow.core.profile_manager import ProfileError, ProfileManager
+from devflow.core.project import ProjectDetector
+from devflow.models.profile import Profile
+from devflow.models.project import (
+  PROJECT_MODES,
+  Project,
+  canonical_project_mode,
+)
+
+console = Console()
+error_console = Console(stderr=True)
+
+
+def init(
+  path: Path = typer.Argument(
+    Path("."),
+    help="Project root to initialize.",
+  ),
+  name: Optional[str] = typer.Option(
+    None,
+    "--name",
+    "-n",
+    help="Override the detected project name.",
+  ),
+  profile: Optional[list[str]] = typer.Option(
+    None,
+    "--profile",
+    "-p",
+    help="Enable a profile explicitly. Can be repeated.",
+  ),
+  yes: bool = typer.Option(
+    False,
+    "--yes",
+    "-y",
+    help="Do not prompt when no profile or harness is detected.",
+  ),
+  harness: Optional[str] = typer.Option(
+    None,
+    "--harness",
+    help=(
+      "Agent harness: 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="Disable agent harness integration.",
+  ),
+  project_mode: Optional[str] = typer.Option(
+    None,
+    "--project-mode",
+    help=(
+      "Default specification context: existing or greenfield."
+    ),
+  ),
+) -> None:
+  """Initialize DevFlow in a project."""
+  try:
+    _initialize(
+      path,
+      name,
+      profile or [],
+      yes,
+      harness,
+      mode,
+      no_agent,
+      project_mode,
+    )
+  except (
+    ArchitectureError,
+    ConfigError,
+    ProfileError,
+    FileNotFoundError,
+    NotADirectoryError,
+    OSError,
+  ) as error:
+    error_console.print(f"[red]Error:[/red] {error}")
+    raise typer.Exit(code=1) from error
+
+
+def _initialize(
+  path: Path,
+  name: Optional[str],
+  explicit_profiles: list[str],
+  yes: bool,
+  harness: Optional[str],
+  mode: Optional[str],
+  no_agent: bool,
+  project_mode: Optional[str],
+) -> None:
+  requested_harness = _requested_harness(harness, no_agent)
+  execution_mode = _requested_mode(mode)
+  requested_project_mode = _requested_project_mode(project_mode)
+
+  root = path.resolve()
+  if not root.exists():
+    msg = (
+      f"Project path does not exist: {root}. "
+      "Create the directory or pass an existing project."
+    )
+    raise FileNotFoundError(msg)
+  if not root.is_dir():
+    msg = f"Project path is not a directory: {root}"
+    raise NotADirectoryError(msg)
+
+  detector = ProjectDetector()
+  project = detector.detect(root)
+  if name is not None:
+    trimmed_name = name.strip()
+    if not trimmed_name:
+      msg = "Project name cannot be empty."
+      raise ConfigError(msg)
+    project.name = trimmed_name
+
+  profile_manager = ProfileManager()
+  matches = profile_manager.detect(project)
+  detected_names = [match.profile.name for match in matches]
+
+  config_manager = ConfigManager(root)
+  if config_manager.exists():
+    config = config_manager.load()
+    project.name = config.project_name
+    project.project_type = config.project_type
+    project.profiles = list(config.profiles)
+    _refresh_existing(
+      config=config,
+      config_manager=config_manager,
+      profile_manager=profile_manager,
+      project=project,
+      detected_names=detected_names,
+      explicit_profiles=explicit_profiles,
+      requested_harness=requested_harness,
+      execution_mode=execution_mode,
+      harness_override=harness is not None or no_agent,
+      mode_override=mode is not None,
+      project_mode=requested_project_mode,
+      project_mode_override=project_mode is not None,
+      allow_prompt=not yes and sys.stdin.isatty(),
+    )
+    return
+
+  selected = list(explicit_profiles) or detected_names
+  selected = [
+    profile_name
+    for profile_name in selected
+    if profile_name != "base"
+  ]
+
+  if not selected and not yes and not explicit_profiles:
+    selected = _prompt_for_profiles(profile_manager)
+    selected = [
+      profile_name
+      for profile_name in selected
+      if profile_name != "base"
+    ]
+
+  profiles = profile_manager.resolve(selected)
+  selected = [
+    profile.name for profile in profiles if profile.name != "base"
+  ]
+  installed = profile_manager.install_constitution(root, profiles)
+  constitution_files = profile_manager.constitution_documents(profiles)
+
+  config = config_manager.create(
+    project=project,
+    profiles=selected,
+    constitution_files=constitution_files,
+    project_mode=requested_project_mode,
+    agent_harness=requested_harness,
+    execution_mode=execution_mode,
+  )
+  config_manager.ensure_directories(config)
+  _ensure_architecture_template(config, requested_project_mode)
+  constitution = ConstitutionLoader(profile_manager).load(
+    config,
+    profiles,
+  )
+
+  selected_harness, setup_result, harness_warnings = _apply_harness_setup(
+    config=config,
+    project=project,
+    profiles=profiles,
+    constitution=constitution,
+    requested_harness=requested_harness,
+    allow_prompt=not yes and sys.stdin.isatty(),
+  )
+
+  console.print(f"[bold]Project:[/bold] {project.name}")
+  console.print(f"[bold]Root:[/bold] {config.root}")
+  console.print(
+    f"[bold]Project mode:[/bold] {config.project_mode}"
+  )
+  console.print(
+    "[bold]Detected profiles:[/bold] "
+    + (", ".join(detected_names) or "none")
+  )
+  for match in matches:
+    console.print(
+      f"  [dim]{match.profile.name}: "
+      f"{', '.join(match.reasons)}[/dim]"
+    )
+  if not selected:
+    console.print(
+      "[yellow]No technology profile was detected. The base profile "
+      "was installed. Use --profile to enable one explicitly.[/yellow]"
+    )
+
+  if installed.copied:
+    console.print(
+      "[green]Constitution files created:[/green] "
+      + ", ".join(installed.copied)
+    )
+  if installed.skipped:
+    console.print(
+      "[yellow]Constitution files kept:[/yellow] "
+      + ", ".join(installed.skipped)
+    )
+
+  console.print(
+    f"[green]Configuration created:[/green] "
+    f"{config.path.relative_to(root)}"
+  )
+  _report_harness(
+    requested_harness,
+    selected_harness,
+    setup_result,
+    harness_warnings,
+    config,
+  )
+  console.print(
+    f"[green]Specifications directory:[/green] "
+    f"{config.specifications_path.relative_to(root)}"
+  )
+  console.print(
+    "\nNext: [bold]devflow spec \"Describe the change\"[/bold]"
+  )
+
+
+def _refresh_existing(
+  config: DevFlowConfig,
+  config_manager: ConfigManager,
+  profile_manager: ProfileManager,
+  project: Project,
+  detected_names: list[str],
+  explicit_profiles: list[str],
+  requested_harness: str,
+  execution_mode: str,
+  harness_override: bool,
+  mode_override: bool,
+  project_mode: str,
+  project_mode_override: bool,
+  allow_prompt: bool,
+) -> None:
+  if explicit_profiles:
+    msg = (
+      "DevFlow is already initialized. Edit .devflow/config.yaml "
+      "to change profiles, or remove it to reinitialize."
+    )
+    raise ConfigError(msg)
+
+  available = set(profile_manager.names())
+  configured = list(config.profiles)
+  unknown = sorted(set(configured) - available)
+  if unknown:
+    msg = (
+      "Configured profile(s) are no longer available: "
+      + ", ".join(unknown)
+    )
+    raise ProfileError(msg)
+
+  if harness_override or mode_override:
+    config = config_manager.set_agent_harness(
+      requested_harness if harness_override else config.agent_harness,
+      execution_mode if mode_override else None,
+    )
+  if project_mode_override:
+    config = config_manager.set_project_mode(project_mode)
+
+  profiles = profile_manager.resolve(configured)
+  installed = profile_manager.install_constitution(
+    config.root,
+    profiles,
+    destination=config.constitution.path,
+  )
+  config_manager.ensure_directories(config)
+  _ensure_architecture_template(config, config.project_mode)
+
+  constitution = ConstitutionLoader(profile_manager).load(
+    config,
+    profiles,
+  )
+  selected_harness, setup_result, harness_warnings = _apply_harness_setup(
+    config=config,
+    project=project,
+    profiles=profiles,
+    constitution=constitution,
+    requested_harness=config.agent_harness,
+    allow_prompt=allow_prompt,
+  )
+
+  console.print("[yellow]DevFlow is already initialized.[/yellow]")
+  console.print(f"[bold]Root:[/bold] {config.root}")
+  console.print(
+    f"[bold]Project mode:[/bold] {config.project_mode}"
+  )
+  if installed.copied:
+    console.print(
+      "[green]Missing constitution files restored:[/green] "
+      + ", ".join(installed.copied)
+    )
+  if installed.skipped:
+    console.print(
+      "[dim]Existing constitution files left untouched:[/dim] "
+      + ", ".join(installed.skipped)
+    )
+
+  missing = sorted(set(detected_names) - set(configured))
+  if missing:
+    console.print(
+      "[yellow]Detected but not configured:[/yellow] "
+      + ", ".join(missing)
+      + ". Edit .devflow/config.yaml to enable them."
+    )
+
+  for warning in constitution.warnings:
+    console.print(f"[yellow]Warning:[/yellow] {warning}")
+
+  _report_harness(
+    config.agent_harness,
+    selected_harness,
+    setup_result,
+    harness_warnings,
+    config,
+  )
+
+
+def _requested_harness(
+  harness: Optional[str],
+  no_agent: bool,
+) -> str:
+  if no_agent:
+    return "none"
+  return validate_harness_name(harness or "auto")
+
+
+def _requested_project_mode(project_mode: Optional[str]) -> str:
+  if project_mode is None:
+    return "existing"
+  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 _ensure_architecture_template(
+  config: DevFlowConfig,
+  project_mode: str,
+) -> None:
+  if project_mode != "greenfield":
+    return
+  created = create_architecture_template(config.root)
+  if created is None:
+    console.print(
+      "[dim]Architecture manifest kept:[/dim] "
+      f"{ARCHITECTURE_RELATIVE_PATH.as_posix()}"
+    )
+  else:
+    console.print(
+      "[green]Architecture manifest template created:[/green] "
+      f"{ARCHITECTURE_RELATIVE_PATH.as_posix()}"
+    )
+    console.print(
+      "[dim]Edit it before running a Greenfield specification.[/dim]"
+    )
+
+
+def _requested_mode(mode: Optional[str]) -> str:
+  if mode is None:
+    return "interactive"
+  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)
+  return normalized
+
+
+def _apply_harness_setup(
+  config: DevFlowConfig,
+  project: Project,
+  profiles: list[Profile],
+  constitution: Constitution,
+  requested_harness: str,
+  allow_prompt: bool,
+) -> tuple[str | None, SetupResult | None, list[str]]:
+  selected, warnings = resolve_harness(
+    requested_harness,
+    allow_prompt=allow_prompt,
+    require_installed=False,
+  )
+  if selected is not None:
+    adapter = adapter_for(selected)
+    if not adapter.is_available():
+      executable = getattr(adapter, "executable", selected)
+      warnings.append(
+        f"Agent harness '{selected}' is configured, but its executable "
+        f"'{executable}' is not installed or not on PATH. DevFlow will "
+        "use deterministic analysis until it is available."
+      )
+    result = adapter.setup(
+      build_setup_context(
+        config=config,
+        project=project,
+        profiles=profiles,
+        constitution=constitution,
+      )
+    )
+    return selected, result, warnings
+
+  if validate_harness_name(requested_harness) == "none":
+    return None, None, warnings
+
+  writer = AgentsFileWriter()
+  result = writer.write(
+    root=config.root,
+    content=writer.render(
+      project=project,
+      profiles=profiles,
+      constitution_files=list(config.constitution.files),
+      config=config,
+    ),
+  )
+  generic = SetupResult(
+    changes=(FileChange(path=result.path, status=result.status),)
+  )
+  warnings.append(
+    "No specific harness was selected. A generic AGENTS.md fallback "
+    "was generated."
+  )
+  return None, generic, warnings
+
+
+def _report_harness(
+  requested_harness: str,
+  selected_harness: str | None,
+  setup_result: SetupResult | None,
+  warnings: list[str],
+  config: DevFlowConfig,
+) -> None:
+  if selected_harness is not None:
+    label = selected_harness
+    if requested_harness == "auto":
+      label += " (auto-detected)"
+    console.print(f"[bold]Agent harness:[/bold] {label}")
+  elif requested_harness == "none":
+    console.print("[yellow]Agent integration disabled.[/yellow]")
+  else:
+    console.print(
+      "[yellow]No specific harness selected; using the generic "
+      "AGENTS.md fallback.[/yellow]"
+    )
+
+  console.print(
+    f"[bold]Execution mode:[/bold] {config.execution_mode}"
+  )
+  for warning in warnings:
+    console.print(f"[yellow]Warning:[/yellow] {warning}")
+  if setup_result is not None:
+    print_setup_result(setup_result, config.root, console)
+
+
+def _prompt_for_profiles(profile_manager: ProfileManager) -> list[str]:
+  if not sys.stdin.isatty():
+    return []
+
+  available = [
+    profile_name
+    for profile_name in profile_manager.names()
+    if profile_name != "base"
+  ]
+  if not available:
+    return []
+
+  console.print(
+    "[yellow]No project profile was detected automatically.[/yellow]"
+  )
+  console.print("Available profiles: " + ", ".join(available))
+  answer = typer.prompt(
+    "Profiles to enable (comma-separated, leave empty for base only)",
+    default="",
+    show_default=False,
+  )
+  return [
+    value.strip()
+    for value in answer.split(",")
+    if value.strip()
+  ]