platformforge 0.1.0__py3-none-any.whl

platformforge/ui/tui.py

@@ -0,0 +1,94 @@
+"""Full-screen TUI for this Forge — vendored canonical.
+
+Each menu entry maps to the same real CLI argv the inline home menu
+runs. Quick read-only commands are captured into the content pane;
+long-running/interactive ones suspend the alt-screen and stream
+attached. No fake buttons: every action is the real CLI.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from platformforge.ui import home
+from platformforge.ui.app import ActionData, DocMeta, Entry, ForgeApp, TextData
+from platformforge.ui.kit import UIContext
+
+# argv[0]s that stream progressively or open external surfaces —
+# those run attached (alt-screen suspended) instead of captured.
+_SUSPEND_VERBS = {
+    "agents",
+    "analyze",
+    "doctor",
+    "graph",
+    "hosts",
+    "install",
+    "mcp",
+    "risk",
+    "sdd",
+    "inspect",
+}
+
+
+_LEARN_DOC: dict[str, str] = {}
+
+
+def _action_for(label: str, extra: list[str]) -> ActionData:
+    suspend = bool(extra) and extra[0] in _SUSPEND_VERBS
+
+    def _run() -> int:
+        argv = home._cli_argv(list(extra))
+        if argv is None:
+            print(f"{home.CLI_NAME} not resolvable — run ./setup.sh")
+            return 127
+        print("$ " + " ".join(argv[:4]) + (" …" if len(argv) > 4 else ""))
+        if suspend:
+            return home._run_argv(argv)
+        env = {**__import__("os").environ, "FORGE_TEXT_OUTPUT": "1", "NO_COLOR": "1"}
+        try:
+            cp = subprocess.run(argv, capture_output=True, text=True, env=env, timeout=300, check=False)
+        except subprocess.TimeoutExpired:
+            print("command timed out after 300s; run it directly for live progress")
+            return 124
+        sys.stdout.write(cp.stdout)
+        if cp.stderr:
+            sys.stdout.write("\n[stderr]\n" + cp.stderr)
+        return cp.returncode
+
+    doc = DocMeta(
+        description=label,
+        example=f"{home.CLI_NAME} {' '.join(extra)}",
+        doc_path=_LEARN_DOC.get(extra[0], ""),
+    )
+    return ActionData(callable=_run, title=f"{home.CLI_NAME} {' '.join(extra)}", suspend=suspend, doc=doc)
+
+
+def _wizard_entry() -> Entry:
+    return Entry(
+        label="installation wizard",
+        provider=lambda: ActionData(
+            callable=lambda: home._run_wizard(UIContext.detect(force_plain=True)),
+            title="install wizard",
+            suspend=True,
+        ),
+    )
+
+
+def entries() -> list[Entry]:
+    out: list[Entry] = []
+    for label, argv in home._MENU:
+        if argv is None:
+            continue  # quit lives in the app chrome (q)
+        if argv == "__wizard__":
+            out.append(_wizard_entry())
+        else:
+            out.append(Entry(label=label, provider=lambda a=argv, lbl=label: _action_for(lbl, a)))
+    return out
+
+
+def run_tui(*, ctx: UIContext | None = None, version: str = "") -> int:
+    ctx = ctx or UIContext.detect()
+    return ForgeApp(
+        ctx, forge_id=home.FORGE_NAME, title="command center", entries=entries(), version=version
+    ).run()

platformforge/ui/wizard.py

@@ -0,0 +1,309 @@
+"""Guided installation wizard (Experience Program §1.2).
+
+Drives the *real* install service — every choice maps to an actual
+``install()`` call; the review step is the real dry-run plan, and the
+apply step is the governed ``--yes`` path. Nothing here writes files
+itself.
+
+Flow: env check → scope → profile → hosts → review (dry-run plan) →
+confirm → apply → doctor → finish. Any step can be cancelled (Esc/q)
+without side effects; nothing is written before the explicit confirm.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from platformforge.ui import i18n
+from platformforge.ui.kit import (
+    NonInteractive,
+    UIContext,
+    _c,
+    confirm,
+    dashboard,
+    multi_select,
+    select,
+)
+
+_ALL_HOSTS = ("claude", "devin", "codex", "copilot")
+_PROFILES = ("recommended", "minimal", "full")  # service contract names
+_PROFILE_LABELS = {
+    "recommended": "Balanced (Recommended)",
+    "minimal": "Economy",
+    "full": "Full",
+}
+_GATEWAY_PROFILES = ("economy", "balanced", "deep")
+_GATEWAY_LABELS = {
+    "economy": "Economy (lowest context cost)",
+    "balanced": "Balanced (recommended)",
+    "deep": "Deep (maximum verification)",
+}
+_SCOPE_LABELS = {
+    "project": "Current repository",
+    "workspace": "Entire workspace",
+    "user": "My user account",
+}
+
+
+def _has_vcs_root(start: Path) -> bool:
+    """Return whether current directory belongs to a supported project root."""
+    return any(
+        (candidate / ".git").exists() or (candidate / "forge.json").is_file()
+        for candidate in (start, *start.parents)
+    )
+
+
+def _scope_choices(ctx: UIContext) -> list[str]:
+    """Hide repository-only choice when operator is in a fresh directory."""
+    scopes = ["project", "workspace", "user"]
+    if not _has_vcs_root(Path.cwd()):
+        print(
+            _c(
+                ctx,
+                "33",
+                "  No repository detected; choose Entire workspace to use this directory "
+                "or My user account.",
+            )
+        )
+        scopes.remove("project")
+    return scopes
+
+
+def env_check_rows() -> list[tuple[str, str]]:
+    """Real environment evidence: python, git, host binaries."""
+    v = sys.version_info
+    rows = [("Python", f"{v.major}.{v.minor}.{v.micro}")]
+    rows.append(("Git", "OK" if shutil.which("git") else "missing"))
+    for h in _ALL_HOSTS:
+        rows.append((h.capitalize(), "Available" if shutil.which(h) else "not detected"))
+    return rows
+
+
+def _banner(ctx: UIContext, forge_name: str) -> None:
+    print()
+    print(_c(ctx, "1", f" {forge_name.upper()}"))
+    print(_c(ctx, "2", " " + ("─" if ctx.unicode else "-") * max(10, len(forge_name) + 4)))
+    print(f"  {i18n.t('env_detected', ctx.language)}:")
+
+
+def run_wizard(
+    *,
+    forge_name: str,
+    install_fn: Any,
+    doctor_fn: Any | None = None,
+    hosts_available: tuple[str, ...] = _ALL_HOSTS,
+    ctx: UIContext | None = None,
+    out_json: bool = False,
+    family: bool = False,
+) -> int:
+    """Interactive install wizard. Returns exit code.
+
+    ``install_fn(**kwargs)`` is the forge's real install service
+    (``host``/``scope``/``profile``/``yes``/``dry_run`` kwargs).
+    ``doctor_fn`` optionally verifies post-install.
+    """
+    ctx = ctx or UIContext.detect()
+    if not ctx.interactive:
+        raise NonInteractive("install wizard requires a TTY")
+
+    _banner(ctx, forge_name)
+    env_rows = env_check_rows()
+    for label, val in env_rows:
+        print(f"    {label:<14} {_c(ctx, '32' if val in ('OK', 'Available') else '2', val)}")
+    print()
+    if family:
+        print(_c(ctx, "36", "  family mode: The Forge + registered specialist forges"))
+        print(_c(ctx, "2", "  one real plan, one approval, each forge keeps its own installer"))
+        print()
+
+    # --- scope ---------------------------------------------------------------
+    scopes = _scope_choices(ctx)
+    idx = select(
+        i18n.t("install_scope_q", ctx.language),
+        [_SCOPE_LABELS[s] for s in scopes],
+        ctx=ctx,
+    )
+    if idx is None:
+        return 130
+    scope = scopes[idx]
+
+    # --- profile -------------------------------------------------------------
+    idx = select(
+        i18n.t("install_profile_q", ctx.language),
+        [_PROFILE_LABELS[p] for p in _PROFILES],
+        ctx=ctx,
+    )
+    if idx is None:
+        return 130
+    profile = _PROFILES[idx]
+
+    # --- execution profile --------------------------------------------------
+    idx = select(
+        i18n.t("install_gateway_profile_q", ctx.language),
+        [_GATEWAY_LABELS[p] for p in _GATEWAY_PROFILES],
+        ctx=ctx,
+    )
+    if idx is None:
+        return 130
+    gateway_profile = _GATEWAY_PROFILES[idx]
+
+    # --- optional components ---------------------------------------------------
+    # The profile decides the default; the operator can narrow or extend it.
+    # "graph-studio"/"tui" are runtime flags persisted to components.json —
+    # skills/agents/mcp map to real asset kinds.
+    _COMP_LABELS = {
+        "skills": "Skills",
+        "agents": "Agents",
+        "mcp": "MCP",
+        "tui": "TUI",
+        "graph-studio": "Graph Studio",
+    }
+    _COMP_ORDER = ("skills", "agents", "mcp", "tui", "graph-studio")
+    _COMP_DETAILS = {
+        "skills": "host-discoverable skills and progressive capability guidance",
+        "agents": "specialists, subagents and declared agent instructions",
+        "mcp": "MCP configuration and governed server entry points",
+        "tui": "the terminal command center runtime",
+        "graph-studio": "federated graph views and local graph navigation",
+    }
+    _profile_defaults = {
+        "minimal": {"mcp", "tui"},
+        "recommended": {"skills", "agents", "mcp", "tui", "graph-studio"},
+        "full": {"skills", "agents", "mcp", "tui", "graph-studio"},
+    }
+    comp_checked = _profile_defaults.get(profile, set())
+    print(_c(ctx, "2", "  component choices (economy loads optional knowledge/evals on demand):"))
+    for component in _COMP_ORDER:
+        print(f"    {component:<13} {_COMP_DETAILS[component]}")
+    comp_chosen = multi_select(
+        i18n.t("install_components_q", ctx.language),
+        [_COMP_LABELS[c] for c in _COMP_ORDER],
+        checked={i for i, c in enumerate(_COMP_ORDER) if c in comp_checked},
+        ctx=ctx,
+    )
+    if comp_chosen is None:
+        return 130
+    components = tuple(sorted(_COMP_ORDER[i] for i in comp_chosen))
+
+    # --- hosts ---------------------------------------------------------------
+    detected = {
+        i
+        for i, h in enumerate(hosts_available)
+        if any(h in r[0].lower() and r[1] == "Available" for r in env_rows)
+    }
+    chosen = multi_select(
+        i18n.t("install_hosts_q", ctx.language),
+        list(hosts_available),
+        checked=detected,
+        ctx=ctx,
+    )
+    if chosen is None:
+        return 130
+    if not chosen:
+        host_arg: str | None = None
+    elif len(chosen) == len(hosts_available):
+        host_arg = "all"
+    else:
+        host_arg = ",".join(hosts_available[i] for i in sorted(chosen))
+
+    # --- review (real dry-run plan) ------------------------------------------
+    # Contrato explícito: install_fn aceita `components` — wrappers **kw
+    # encaminham sem inspeção de assinatura (GAP-002).
+    kwargs: dict[str, Any] = {
+        "scope": scope,
+        "profile": profile,
+        "gateway_profile": gateway_profile,
+        "components": components,
+    }
+    try:
+        # `none` é opt-out explícito — zero hosts escolhidos nunca vira
+        # "all" (GAP-003); csv de subconjunto é contrato válido (GAP-003b).
+        plan = install_fn(host=host_arg or "none", dry_run=True, **kwargs)
+    except Exception as exc:
+        print(_c(ctx, "31", f"plan failed: {exc}"))
+        return 1
+
+    planned = plan.get("planned") or plan.get("planned_files") or plan.get("writes") or []
+    dashboard(
+        f"{forge_name} — {i18n.t('review', ctx.language)}",
+        [
+            (
+                "Plan",
+                [
+                    ("scope", scope),
+                    ("profile", profile),
+                    ("execution", gateway_profile),
+                    ("mode", "family" if family else "this forge"),
+                    ("components", ", ".join(components) or "none"),
+                    ("hosts", host_arg or "none"),
+                    ("managed writes", str(len(planned) if isinstance(planned, list) else planned)),
+                ],
+            )
+        ],
+        ctx=ctx,
+    )
+    if isinstance(planned, list):
+        for entry in planned[:10]:
+            path = str(entry.get("path")) if isinstance(entry, dict) else str(entry)
+            print(f"    {_c(ctx, '2', path)}")
+        if len(planned) > 10:
+            print(f"    … {len(planned) - 10} more")
+
+    if not confirm(i18n.t("confirm_q", ctx.language), default=True, ctx=ctx):
+        return 130
+
+    # --- apply (real governed install) ---------------------------------------
+    receipt = install_fn(host=host_arg or "none", yes=True, dry_run=False, **kwargs)
+    status = receipt.get("status", "unknown")
+    if out_json:
+        print(json.dumps(receipt, indent=2, ensure_ascii=False))
+    color = "32" if status == "completed" else "31"
+    print(f"\n  {i18n.t('status', ctx.language)}: {_c(ctx, color, status)}")
+
+    # --- verify --------------------------------------------------------------
+    if doctor_fn is not None and status == "completed":
+        health = doctor_fn(scope=scope)
+        raw_health = health.get("status") or health.get("health") or "unknown"
+        hstatus = raw_health
+        if isinstance(raw_health, dict):
+            hstatus = raw_health.get("status", "unknown")
+        color = "32" if hstatus in ("healthy", "PASS") else "33"
+        print(f"  {i18n.t('health', ctx.language)}: {_c(ctx, color, str(hstatus))}")
+
+    if status == "completed":
+        print("  next: theforge specialists status · theforge doctor · theforge portal")
+
+    return 0 if status == "completed" else 1
+
+
+def run_setup_wizard(
+    *,
+    root: Any = None,
+    ctx: UIContext | None = None,
+    out_json: bool = False,
+) -> int:
+    """Family onboarding over the same real plan/approval/apply wizard."""
+    try:
+        service = importlib.import_module("theforge.install.service")
+    except ModuleNotFoundError as exc:
+        if exc.name == "theforge" or (exc.name or "").startswith("theforge."):
+            print(
+                "family onboarding unavailable: install The Forge separately; "
+                "native Forge commands remain available"
+            )
+            return 2
+        raise
+
+    return run_wizard(
+        forge_name="the-forge family",
+        install_fn=lambda **kw: service.install_auto(root=root, **kw),
+        doctor_fn=lambda **kw: service.doctor(root=root, **kw),
+        ctx=ctx,
+        out_json=out_json,
+        family=True,
+    )

platformforge/workspace/__init__.py

@@ -0,0 +1,13 @@
+"""Portable workspace lifecycle."""
+from .models import WorkspaceManifest, WorkspaceMember
+from .service import add_repo, doctor, ensure_workspace, load_workspace, remove_repo
+
+__all__ = [
+           "WorkspaceManifest",
+           "WorkspaceMember",
+           "add_repo",
+           "doctor",
+           "ensure_workspace",
+           "load_workspace",
+           "remove_repo",
+]

platformforge/workspace/models.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+SCHEMA = "platformforge/workspace-manifest/v1"
+
+@dataclass
+class WorkspaceMember:
+    name: str
+    path: str
+
+@dataclass
+class WorkspaceManifest:
+    root: str
+    profile: str = "agentic"
+    hosts: list[str] = field(default_factory=list)
+    repos: list[WorkspaceMember] = field(default_factory=list)
+    state_mode: str = "workspace-local"
+    installed_version: str = ""
+    schema: str = SCHEMA
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["repos"] = [asdict(x) for x in self.repos]
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> WorkspaceManifest:
+        return cls(root=d["root"], profile=d.get("profile", "agentic"),
+                   hosts=list(d.get("hosts", [])),
+                   repos=[WorkspaceMember(**x) for x in d.get("repos", [])],
+                   state_mode=d.get("state_mode", "workspace-local"),
+                   installed_version=d.get("installed_version", ""),
+                   schema=d.get("schema", SCHEMA))

platformforge/workspace/service.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from platformforge import __version__
+from platformforge.workspace.models import WorkspaceManifest, WorkspaceMember
+
+
+def _path(root: Path) -> Path:
+    return root / ".platformforge" / "workspace.json"
+
+def ensure_workspace(root: str | Path, profile: str = "agentic",
+                     hosts: list[str] | None = None) -> WorkspaceManifest:
+    root = Path(root).resolve()
+    p = _path(root)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    if p.is_file():
+        ws = WorkspaceManifest.from_dict(json.loads(p.read_text()))
+        ws.profile, ws.hosts, ws.installed_version = profile, hosts or ws.hosts, __version__
+    else:
+        ws = WorkspaceManifest(str(root), profile, hosts or [], [],
+                               "workspace-local", __version__)
+    p.write_text(json.dumps(ws.to_dict(), indent=2, sort_keys=True) + "\n")
+    return ws
+
+def load_workspace(root: str | Path) -> WorkspaceManifest:
+    p = _path(Path(root).resolve())
+    if not p.is_file():
+        raise FileNotFoundError("PF-WORKSPACE-MANIFEST-MISSING")
+    return WorkspaceManifest.from_dict(json.loads(p.read_text()))
+
+def add_repo(root: str | Path, repo: str | Path, name: str = "") -> WorkspaceManifest:
+    root = Path(root).resolve()
+    ws = ensure_workspace(root)
+    rp = Path(repo).resolve()
+    if rp != root and root not in rp.parents:
+        # external members are explicit, but never silently inferred
+        rel = str(rp)
+    else:
+        rel = str(rp.relative_to(root)) or "."
+    name = name or rp.name
+    if not any(x.name == name for x in ws.repos):
+        ws.repos.append(WorkspaceMember(name, rel))
+    _path(root).write_text(json.dumps(ws.to_dict(), indent=2, sort_keys=True) + "\n")
+    return ws
+
+def remove_repo(root: str | Path, name: str) -> WorkspaceManifest:
+    root = Path(root).resolve()
+    ws = load_workspace(root)
+    ws.repos = [x for x in ws.repos if x.name != name]
+    _path(root).write_text(json.dumps(ws.to_dict(), indent=2, sort_keys=True) + "\n")
+    return ws
+
+def doctor(root: str | Path) -> dict:
+    root = Path(root).resolve()
+    try:
+        ws = load_workspace(root)
+    except FileNotFoundError:
+        return {"state": "failed", "refusal": "PF-WORKSPACE-MANIFEST-MISSING"}
+    missing = []
+    for m in ws.repos:
+        p = Path(m.path)
+        if not p.is_absolute():
+            p = root / p
+        if not p.exists():
+            missing.append(m.name)
+    return {"state": "healthy" if not missing else "warning",
+            "workspace": ws.to_dict(), "missing_repos": missing}