forgex-cli 0.1.0__py3-none-any.whl

forgex/cli/commands/plan.py

@@ -0,0 +1,103 @@
+"""`forgex plan` — run the Architect agent standalone (spec sections 7, 34)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+from rich.markup import escape
+from rich.table import Table
+
+from forgex.agents.architect import build_planner, plan_project
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, ui_from
+from forgex.config import load_config
+from forgex.orchestration.stores import open_stores
+from forgex.research.citations import format_note
+from forgex.schemas.error import ProjectError
+from forgex.schemas.plan import specs_to_tasks
+from forgex.utils.paths import find_project_root
+
+STAGE_LABELS = {
+    "analyzing": "Analyzing request & repository",
+    "researching": "Researching dependencies",
+    "planning": "Producing implementation plan",
+}
+
+
+def plan_command(
+    ctx: typer.Context,
+    request: Annotated[str, typer.Argument(help="What should be built?")],
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show the plan without persisting anything.")] = False,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Run the Architect agent: analysis, research, implementation plan."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    config = load_config(root)
+    step = {"n": 0}
+
+    def progress(stage: str) -> None:
+        step["n"] += 1
+        ui.text(f"[{step['n']}/3] {STAGE_LABELS.get(stage, stage)}...")
+
+    with open_stores(root) as stores:
+        planner = build_planner(config=config, workspace=root, stores=stores)
+        try:
+            result = asyncio.run(
+                plan_project(
+                    planner,
+                    stores=stores,
+                    request=request,
+                    dry_run=dry_run,
+                    progress=progress,
+                )
+            )
+        finally:
+            aclose = getattr(planner, "aclose", None)
+            if aclose is not None:
+                asyncio.run(aclose())
+
+    tasks = specs_to_tasks(result.plan.tasks)
+    ui.data({
+        "request": request,
+        "plan": result.plan.model_dump(mode="json"),
+        "research": [note.model_dump(mode="json") for note in result.research],
+        "tasks_created": len(tasks),
+        "persisted": not dry_run,
+    })
+
+    suffix = " (dry run — nothing persisted)" if dry_run else ""
+    ui.ok(f"Plan created — {len(tasks)} tasks, {len(result.plan.libraries)} libraries{suffix}")
+
+    if ui.mode is Output.RICH:
+        table = Table(show_header=True, header_style="bold", expand=False)
+        table.add_column("ID")
+        table.add_column("Priority")
+        table.add_column("Deps")
+        table.add_column("Description", overflow="fold")
+        for task in tasks:
+            table.add_row(
+                task.id,
+                task.priority.value,
+                ", ".join(task.depends_on) or "—",
+                escape(task.description),
+            )
+        ui.console.print(table)
+        if result.plan.libraries:
+            ui.text(f"Libraries: {', '.join(escape(lib) for lib in result.plan.libraries)}")
+        if result.research:
+            ui.text("")
+            ui.text("Research:")
+            for note in result.research:
+                ui.text(f"  {escape(format_note(note))}")
+    elif ui.mode is Output.PLAIN:
+        for task in tasks:
+            deps = ",".join(task.depends_on) or "-"
+            ui.text(f"{task.id} [{task.priority.value}] {task.description} (deps: {deps})")
+        for note in result.research:
+            ui.text(format_note(note))

forgex/cli/commands/review.py

@@ -0,0 +1,76 @@
+"""`forgex review` — run the Expert Coder over recent changes (spec section 10)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+from rich.markup import escape
+
+from forgex.agents.expert_coder import review_work
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, make_approval, ui_from
+from forgex.config import load_config
+from forgex.orchestration.stores import open_stores
+from forgex.schemas.error import ProjectError
+from forgex.utils.paths import find_project_root
+
+
+def review_command(
+    ctx: typer.Context,
+    task_id: Annotated[str | None, typer.Argument(help="Review this task's changes (default: current uncommitted changes).")] = None,
+    base: Annotated[str | None, typer.Option("--base", help="Explicit base commit for the review diff.")] = None,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Expert review of recent changes: fix, simplify, harden — minimally."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    config = load_config(root)
+    with open_stores(root) as stores:
+        result = asyncio.run(
+            review_work(
+                stores=stores,
+                config=config,
+                task_id=task_id,
+                base_commit=base,
+                approval=make_approval(ui),
+            )
+        )
+
+    if result is None:
+        ui.data({"reviewed": False})
+        ui.ok("Nothing to review — no changes detected.")
+        return
+
+    ui.data({
+        "reviewed": True,
+        "status": result.status,
+        "summary": result.summary,
+        "improvements": result.improvements,
+        "issues_found": result.issues_found,
+        "unfixed_issues": result.unfixed_issues,
+        "changed_files": result.changed_files,
+    })
+
+    if result.status != "completed":
+        ui.error(f"Review failed: {result.summary}")
+        raise typer.Exit(code=1)
+
+    if result.changed_files:
+        ui.ok(f"Review complete — {len(result.improvements)} improvement(s), {len(result.changed_files)} file(s) changed")
+    else:
+        ui.ok(f"Review complete — no changes needed ({result.summary})")
+
+    if ui.mode in (Output.RICH, Output.PLAIN):
+        for item in result.improvements:
+            ui.text(f"  • {escape(item)}")
+        for path in result.changed_files:
+            ui.text(f"  changed: {escape(path)}")
+        if result.unfixed_issues:
+            ui.text("  Unfixed issues:")
+            for issue in result.unfixed_issues:
+                ui.text(f"    - {escape(issue)}")

forgex/cli/commands/rollback.py

@@ -0,0 +1,65 @@
+"""`forgex rollback` — restore workspace to a checkpoint (spec sections 21, 33)."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import typer
+from rich.prompt import Confirm
+
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, ui_from
+from forgex.orchestration.checkpoints import get_checkpoint, latest_checkpoint, rollback_to
+from forgex.orchestration.stores import open_stores
+from forgex.schemas.error import ProjectError
+from forgex.tools.git import git_diff_stat
+from forgex.utils.paths import find_project_root
+
+
+def rollback_command(
+    ctx: typer.Context,
+    checkpoint_id: Annotated[str | None, typer.Argument(help="Checkpoint id (default: latest)")] = None,
+    last: Annotated[bool, typer.Option("--last", help="Rollback to latest checkpoint.")] = False,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip confirmation prompt.")] = False,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Roll the workspace back to a checkpoint (reversible)."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    with open_stores(root) as stores:
+        if checkpoint_id and not last:
+            record = get_checkpoint(checkpoint_id, stores=stores)
+            if record is None:
+                raise ProjectError(f"Unknown checkpoint: {checkpoint_id}")
+        else:
+            record = latest_checkpoint(stores=stores)
+            if record is None:
+                raise ProjectError("No checkpoints recorded yet — run `forgex checkpoint`.")
+
+        ui.text(f"Rolling back to {record.id} — {record.label} (commit {record.git_commit[:8] if record.git_commit else '?'})")
+        preview = git_diff_stat(root, record.git_commit) if record.git_commit else ""
+        if preview and preview != "(no diff preview available)":
+            ui.text(f"Changes to be reverted:\n{preview}")
+
+        if not yes:
+            if not sys.stdin.isatty() or ui.mode is not Output.RICH:
+                ui.warn("Refusing to rollback non-interactively without --yes.")
+                raise typer.Exit(code=1)
+            if not Confirm.ask("Proceed with rollback?", default=False):
+                ui.warn("Aborted — nothing changed.")
+                raise typer.Exit(code=1)
+
+        safety = rollback_to(record, stores=stores)
+
+    ui.data({
+        "rolled_back_to": record.id,
+        "commit": record.git_commit,
+        "safety_checkpoint": safety.id if safety else None,
+    })
+    ui.ok(f"Rolled back to {record.id} ({record.label})")
+    if safety:
+        ui.text(f"Safety checkpoint: {safety.id} — undo this rollback with `forgex rollback {safety.id}`")

forgex/cli/commands/run.py

@@ -0,0 +1,75 @@
+"""`forgex run` — run the project (spec section 22)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, make_approval, ui_from
+from forgex.config import load_config
+from forgex.orchestration.stores import open_stores
+from forgex.schemas.agent import AgentRole
+from forgex.schemas.error import ProjectError
+from forgex.tools import create_context
+from forgex.utils.paths import find_project_root
+
+
+def detect_run_command(root: Path) -> list[str] | None:
+    pkg = root / "package.json"
+    if pkg.is_file():
+        try:
+            scripts = json.loads(pkg.read_text(encoding="utf-8")).get("scripts") or {}
+        except (OSError, ValueError):
+            return None
+        if scripts.get("start"):
+            return ["npm", "start"]
+    return None
+
+
+def run_command(
+    ctx: typer.Context,
+    command: Annotated[list[str] | None, typer.Argument(help="Command to run (default: detected npm start).")] = None,
+    timeout: Annotated[int | None, typer.Option("--timeout", help="Seconds before run is killed.")] = None,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Run the project's start command through the policy-gated executor."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    cmd = list(command) if command else detect_run_command(root)
+    if not cmd:
+        raise ProjectError("No run command detected — pass one: forgex run -- python main.py")
+
+    config = load_config(root)
+    with open_stores(root) as stores:
+        tool_ctx = create_context(
+            workspace=root,
+            config=config,
+            events=stores.recorder,
+            approval=make_approval(ui),
+            agent=AgentRole.BUILDER,
+        )
+        result = asyncio.run(tool_ctx.executor.run(cmd, cwd=".", timeout=timeout))
+
+    ui.data({
+        "command": result.argv,
+        "exit_code": result.exit_code,
+        "timed_out": result.timed_out,
+        "duration_ms": round(result.duration_ms, 1),
+    })
+
+    if ui.mode is not Output.JSON and ui.mode is not Output.QUIET:
+        ui.text(f"$ {' '.join(result.argv)}")
+        if result.stdout:
+            ui.text(result.stdout.rstrip())
+        if result.stderr:
+            ui.text(result.stderr.rstrip())
+
+    raise typer.Exit(code=0 if result.exit_code == 0 and not result.timed_out else 1)

forgex/cli/commands/status.py

@@ -0,0 +1,141 @@
+"""`forgex status` — project detection, git state, ProjectState summary and run history."""
+
+from __future__ import annotations
+
+import typer
+from rich.panel import Panel
+
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, ui_from
+from forgex.config import load_config
+from forgex.orchestration.state import StateStore, TaskStore
+from forgex.orchestration.stores import open_stores
+from forgex.project import detect_project
+from forgex.schemas.error import ProjectError
+from forgex.schemas.task import TaskStatus
+from forgex.tools.git import current_branch, is_dirty
+from forgex.utils.paths import find_project_root
+
+
+def status_command(
+    ctx: typer.Context,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Show project status."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    config = load_config(root)
+    detection = detect_project(root)
+    branch = current_branch(root)
+    dirty = is_dirty(root) if branch else None
+
+    state = StateStore(root).load()
+    tasks = TaskStore(root).load()
+
+    task_counts = {s.value: 0 for s in TaskStatus}
+    for t in tasks:
+        task_counts[t.status.value] += 1
+
+    runs_payload: list[dict] = []
+    usage_totals = None
+    with open_stores(root, create_db=False) as stores:
+        if stores.runs is not None:
+            pid = state.project_id if state else None
+            runs_payload = [r.model_dump(mode="json") for r in stores.runs.list_recent(pid, limit=5)]
+        if stores.usage is not None:
+            raw_totals = stores.usage.totals()
+            usage_totals = {k: (int(v) if v is not None else None) for k, v in raw_totals.items()}
+
+    events_path = root / ".forgex" / "events.jsonl"
+    n_events = (
+        sum(1 for ln in events_path.read_text(encoding="utf-8").splitlines() if ln.strip())
+        if events_path.is_file()
+        else 0
+    )
+    n_checkpoints = len(list((root / ".forgex" / "checkpoints").glob("*")))
+    git_state = f"{branch} ({'dirty' if dirty else 'clean'})" if branch else "not a git repository"
+
+    state_summary = None
+    if state:
+        state_summary = {
+            "project_id": state.project_id,
+            "status": state.status.value,
+            "iteration": state.iteration,
+            "current_agent": state.current_agent.value if state.current_agent else None,
+            "current_task": state.current_task,
+            "user_request": state.user_request,
+            "git_commit": state.git_commit,
+            "changed_files": len(state.changed_files),
+            "errors": len(state.errors),
+            "last_supervisor_status": state.last_supervisor_status,
+            "test_results": (
+                {
+                    "passed": state.test_results.passed,
+                    "failed": state.test_results.failed,
+                    "exit_code": state.test_results.exit_code,
+                }
+                if state.test_results
+                else None
+            ),
+        }
+
+    payload = {
+        "project": root.name,
+        "root": str(root),
+        "detection": detection.as_dict(),
+        "git": {"branch": branch, "dirty": dirty},
+        "state": state_summary,
+        "tasks": {"total": len(tasks), "by_status": task_counts},
+        "runs": runs_payload,
+        "model_usage": usage_totals,
+        "checkpoints": n_checkpoints,
+        "events": n_events,
+        "workflow": {"max_iterations": config.workflow.max_iterations},
+        "permissions": {"mode": config.permissions.mode},
+    }
+    ui.data(payload)
+
+    lines = [
+        f"Detected:    {detection.summary()}",
+        f"Git:         {git_state}",
+        f"Status:      {state.status.value if state else 'no state file'}",
+    ]
+    if state:
+        agent = state.current_agent.value if state.current_agent else "—"
+        lines.append(f"Iteration:   {state.iteration}")
+        lines.append(f"Current:     agent={agent} task={state.current_task or '—'}")
+    lines.append(
+        f"Tasks:       {task_counts['completed']}/{len(tasks)} completed"
+        + (f", {task_counts['failed']} failed" if task_counts["failed"] else "")
+    )
+    if state:
+        tr = state.test_results
+        if tr is not None:
+            p = tr.passed if tr.passed is not None else "?"
+            f = tr.failed if tr.failed is not None else "?"
+            lines.append(f"Tests:       {p} passed, {f} failed (exit {tr.exit_code})")
+        else:
+            lines.append("Tests:       not run")
+        lines.append(f"Supervisor:  {state.last_supervisor_status or 'not run'}")
+    lines.extend([
+        f"Checkpoints: {n_checkpoints}",
+        f"Events:      {n_events}",
+        f"Workflow:    max_iterations={config.workflow.max_iterations}",
+        f"Permissions: {config.permissions.mode}",
+    ])
+
+    if usage_totals and usage_totals.get("calls"):
+        tokens_in, tokens_out = usage_totals.get("input_tokens"), usage_totals.get("output_tokens")
+        lines.append(
+            f"Model usage: {usage_totals['calls']} call(s)"
+            + (f", {tokens_in} in / {tokens_out} out tokens" if tokens_in is not None else " (tokens unreported)")
+        )
+
+    if ui.mode is Output.RICH:
+        ui.console.print(Panel("\n".join(lines), title=f"FORGEX — {root.name}", expand=False))
+    elif ui.mode is Output.PLAIN:
+        for line in lines:
+            ui.console.print(line)

forgex/cli/commands/supervise.py

@@ -0,0 +1,61 @@
+"""`forgex supervise` — full supervision: verification + LLM audit + quality gates."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+from rich.markup import escape
+
+from forgex.agents.supervisor import supervise
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, make_approval, ui_from
+from forgex.config import load_config
+from forgex.orchestration.stores import open_stores
+from forgex.schemas.error import ProjectError
+from forgex.utils.paths import find_project_root
+
+
+def supervise_command(
+    ctx: typer.Context,
+    no_build: Annotated[bool, typer.Option("--no-build", help="Skip the build step.")] = False,
+    no_lint: Annotated[bool, typer.Option("--no-lint", help="Skip the lint step.")] = False,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Inspect → diagnose → instruct repair."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    config = load_config(root)
+    with open_stores(root) as stores:
+        report = asyncio.run(
+            supervise(
+                stores=stores,
+                config=config,
+                approval=make_approval(ui),
+                include_build=not no_build,
+                include_lint=not no_lint,
+            )
+        )
+
+    ui.data(report.model_dump(mode="json"))
+    color = {"pass": "green", "fail": "red", "needs_review": "yellow"}.get(report.status, "white")
+    if ui.mode is Output.RICH:
+        ui.console.print(f"[bold {color}]VERDICT: {report.status.upper()}[/bold {color}]")
+    else:
+        ui.text(f"VERDICT: {report.status.upper()}")
+
+    ui.text(report.summary)
+    for item in report.errors:
+        ui.text(f"  error: {escape(item)}")
+    for item in report.warnings:
+        ui.text(f"  warning: {escape(item)}")
+    if report.required_changes:
+        ui.text("  Required changes:")
+        for change in report.required_changes:
+            ui.text(f"    - {escape(change)}")
+
+    raise typer.Exit(code=0 if report.status == "pass" else 1)

forgex/cli/commands/task.py

@@ -0,0 +1,136 @@
+"""`forgex task` — inspect and execute plan tasks (Builder surface)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+from rich.markup import escape
+from rich.table import Table
+
+from forgex.agents.builder import build_builder, execute_task
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, make_approval, ui_from
+from forgex.config import load_config
+from forgex.orchestration.state import TaskStore
+from forgex.orchestration.stores import open_stores
+from forgex.schemas.error import ProjectError
+from forgex.schemas.task import ready_tasks
+from forgex.utils.paths import find_project_root
+
+app = typer.Typer(no_args_is_help=True, help="Inspect and execute plan tasks.")
+
+
+@app.command("list")
+def list_command(
+    ctx: typer.Context,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """List tasks with status and readiness."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    tasks = TaskStore(root).load()
+    ready_ids = {t.id for t in ready_tasks(tasks)}
+    payload = [
+        {
+            "id": t.id,
+            "status": t.status.value,
+            "priority": t.priority.value,
+            "depends_on": t.depends_on,
+            "attempts": t.attempts,
+            "ready": t.id in ready_ids,
+            "description": t.description,
+        }
+        for t in tasks
+    ]
+    ui.data({"tasks": payload})
+
+    if ui.mode is Output.RICH:
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("ID")
+        table.add_column("Status")
+        table.add_column("Priority")
+        table.add_column("Deps")
+        table.add_column("Ready")
+        table.add_column("Description", overflow="fold")
+        for item in payload:
+            ready_str = "[green]✓[/green]" if item["ready"] else "[yellow]—[/yellow]"
+            deps = item["depends_on"]
+            deps_str = ", ".join(deps) if isinstance(deps, list) else str(deps)
+            table.add_row(
+                str(item["id"]),
+                str(item["status"]),
+                str(item["priority"]),
+                deps_str or "—",
+                ready_str,
+                escape(str(item["description"])),
+            )
+        ui.console.print(table)
+    elif ui.mode is Output.PLAIN:
+        for item in payload:
+            ui.console.print(f"{item['id']} [{item['status']}] ready={item['ready']}: {item['description']}")
+
+
+@app.command("run")
+def run_command(
+    ctx: typer.Context,
+    task_id: Annotated[str, typer.Argument(help="Task ID to execute, e.g. TASK-001")],
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Execute one task with the Builder agent."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    config = load_config(root)
+    with open_stores(root) as stores:
+        tasks = stores.tasks.load()
+        task = next((t for t in tasks if t.id == task_id), None)
+        if task is None:
+            raise ProjectError(f"Task '{task_id}' not found in tasks.json")
+
+        state = stores.state.load()
+        if not state or not state.architecture_plan:
+            raise ProjectError("No architecture plan found in project state. Run `forgex plan` first.")
+
+        builder = build_builder(
+            config=config,
+            workspace=root,
+            stores=stores,
+            approval=make_approval(ui),
+            run_id=state.current_run_id,
+        )
+        try:
+            result = asyncio.run(
+                execute_task(
+                    task,
+                    builder=builder,
+                    stores=stores,
+                    config=config,
+                    plan=state.architecture_plan,
+                    research=state.research,
+                )
+            )
+        finally:
+            asyncio.run(builder.aclose())
+
+    ui.data({
+        "task_id": task_id,
+        "status": result.status,
+        "summary": result.summary,
+        "changed_files": result.changed_files,
+        "issues": result.issues,
+    })
+
+    if result.status == "completed":
+        ui.ok(f"Task {task_id} completed: {result.summary}")
+    else:
+        ui.error(f"Task {task_id} failed: {result.summary}")
+
+    raise typer.Exit(code=0 if result.status == "completed" else 1)