@mamdouh-aboammar/agentic-workflow 1.2.0

package/core/system/__init__.py

@@ -0,0 +1,25 @@
+"""
+core/system/__init__.py — Python System Engines Package
+"""
+
+from core.system.updater import AutoUpdater
+from core.system.installer import AutoInstaller
+from core.system.refresher import Refresher
+from core.system.doctor import DoctorEngine
+from core.system.health import HealthEngine
+from core.system.dependencies import DependenciesEngine
+from core.system.notifications import NotificationEngine
+from core.system.announcements import AnnouncementEngine
+from core.system.version_tracker import VersionTracker
+
+__all__ = [
+    "AutoUpdater",
+    "AutoInstaller",
+    "Refresher",
+    "DoctorEngine",
+    "HealthEngine",
+    "DependenciesEngine",
+    "NotificationEngine",
+    "AnnouncementEngine",
+    "VersionTracker",
+]

package/core/system/announcements.py

@@ -0,0 +1,72 @@
+"""
+core/system/announcements.py — Python Announcement & Bulletin Engine
+"""
+
+import json
+from pathlib import Path
+from typing import Dict, Any, List
+
+
+class AnnouncementEngine:
+    def __init__(self, project_dir: str = "."):
+        self.project_dir = Path(project_dir).resolve()
+        self.state_file = self.project_dir / ".announcements_seen.json"
+
+    def get_default_announcements(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "id": "ann_v110_engines",
+                "title": "Universal System Engines Suite Online",
+                "body": "AgenticWorkflow now features 9 core toolchain engines with dual-runtime parity.",
+                "category": "FEATURE",
+                "date": "2026-09-06",
+                "version": "1.1.0",
+                "priority": "high"
+            },
+            {
+                "id": "ann_toon_v41",
+                "title": "TOON Protocol v4.1 Released",
+                "body": "Token-Oriented Object Notation (v4.1) delivers 30-60% token compression.",
+                "category": "UPDATE",
+                "date": "2026-09-01",
+                "version": "1.0.5",
+                "priority": "normal"
+            }
+        ]
+
+    def get_seen_ids(self) -> List[str]:
+        if self.state_file.exists():
+            try:
+                with open(self.state_file, "r", encoding="utf-8") as f:
+                    return json.load(f).get("seen_ids", [])
+            except Exception:
+                pass
+        return []
+
+    def list_all(self) -> List[Dict[str, Any]]:
+        seen = set(self.get_seen_ids())
+        anns = self.get_default_announcements()
+        for a in anns:
+            a["seen"] = a["id"] in seen
+        return anns
+
+    def get_unread(self) -> List[Dict[str, Any]]:
+        return [a for a in self.list_all() if not a.get("seen")]
+
+    def mark_as_read(self, ann_id: str):
+        seen = self.get_seen_ids()
+        if ann_id not in seen:
+            seen.append(ann_id)
+            try:
+                with open(self.state_file, "w", encoding="utf-8") as f:
+                    json.dump({"seen_ids": seen}, f, indent=2)
+            except Exception:
+                pass
+
+    def mark_all_as_read(self):
+        all_ids = [a["id"] for a in self.list_all()]
+        try:
+            with open(self.state_file, "w", encoding="utf-8") as f:
+                json.dump({"seen_ids": all_ids}, f, indent=2)
+        except Exception:
+            pass

package/core/system/dependencies.py

@@ -0,0 +1,69 @@
+"""
+core/system/dependencies.py — Python Dependencies & Multi-Ecosystem Auditor Engine
+"""
+
+import os
+import json
+import subprocess
+from pathlib import Path
+from typing import Dict, Any, List
+
+
+class DependenciesEngine:
+    def __init__(self, project_dir: str = "."):
+        self.project_dir = Path(project_dir).resolve()
+
+    def audit(self) -> Dict[str, Any]:
+        deps = []
+
+        # 1. Package.json dependencies
+        pkg_file = self.project_dir / "package.json"
+        if pkg_file.exists():
+            try:
+                with open(pkg_file, "r", encoding="utf-8") as f:
+                    pkg_data = json.load(f)
+                    all_deps = {**pkg_data.get("dependencies", {}), **pkg_data.get("devDependencies", {})}
+                    for name, ver in all_deps.items():
+                        node_mod = self.project_dir / "node_modules" / name
+                        deps.append({
+                            "name": name,
+                            "type": "bun-npm",
+                            "status": "SATISFIED" if node_mod.exists() else "MISSING",
+                            "version": ver
+                        })
+            except Exception:
+                pass
+
+        # 2. Python standard modules
+        for mod in ["json", "pathlib", "unittest", "dataclasses", "asyncio"]:
+            try:
+                __import__(mod)
+                deps.append({"name": f"python:{mod}", "type": "python", "status": "SATISFIED"})
+            except ImportError:
+                deps.append({"name": f"python:{mod}", "type": "python", "status": "MISSING"})
+
+        # 3. Binaries
+        for b in ["bun", "python3", "git"]:
+            try:
+                res = subprocess.run(f"{b} --version", shell=True, capture_output=True)
+                deps.append({"name": f"bin:{b}", "type": "system-binary", "status": "SATISFIED" if res.returncode == 0 else "MISSING"})
+            except Exception:
+                deps.append({"name": f"bin:{b}", "type": "system-binary", "status": "MISSING"})
+
+        satisfied = sum(1 for d in deps if d["status"] == "SATISFIED")
+        missing = sum(1 for d in deps if d["status"] == "MISSING")
+
+        return {
+            "total": len(deps),
+            "satisfied": satisfied,
+            "missing": missing,
+            "dependencies": deps,
+            "all_satisfied": missing == 0
+        }
+
+    def install_missing(self) -> Dict[str, Any]:
+        try:
+            res = subprocess.run("bun install", shell=True, cwd=self.project_dir, capture_output=True, text=True)
+            return {"success": res.returncode == 0, "message": "bun install executed"}
+        except Exception as e:
+            return {"success": False, "message": str(e)}

package/core/system/doctor.py

@@ -0,0 +1,171 @@
+"""
+core/system/doctor.py — Python Doctor Diagnostic & Auto-Fix Engine
+"""
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Dict, Any, List
+
+
+class DoctorEngine:
+    def __init__(self, project_dir: str = "."):
+        self.project_dir = Path(project_dir).resolve()
+        self.home_dir = Path.home()
+
+    def _run_cmd(self, cmd: str) -> Dict[str, Any]:
+        try:
+            res = subprocess.run(cmd, shell=True, cwd=self.project_dir, capture_output=True, text=True)
+            return {"ok": res.returncode == 0, "stdout": res.stdout.strip()}
+        except Exception:
+            return {"ok": False, "stdout": ""}
+
+    def diagnose(self) -> Dict[str, Any]:
+        checks = []
+
+        # 1. Bun Runtime
+        bun = self._run_cmd("bun --version")
+        checks.append({
+            "id": "runtime-bun",
+            "title": "Bun Runtime",
+            "status": "PASS" if bun["ok"] else "FAIL",
+            "details": f"Bun v{bun['stdout']}" if bun["ok"] else "Bun not found.",
+            "fixable": False
+        })
+
+        # 2. Python 3 Runtime
+        py = self._run_cmd("python3 --version")
+        checks.append({
+            "id": "runtime-python",
+            "title": "Python 3 Runtime",
+            "status": "PASS" if py["ok"] else "FAIL",
+            "details": py["stdout"] if py["ok"] else "Python 3 not found.",
+            "fixable": False
+        })
+
+        # 3. CLI Permission
+        cli_js = self.project_dir / "bin" / "cli.js"
+        if cli_js.exists():
+            is_exec = os.access(cli_js, os.X_OK)
+            checks.append({
+                "id": "cli-permission",
+                "title": "CLI Permission (bin/cli.js)",
+                "status": "PASS" if is_exec else "WARN",
+                "details": "Executable" if is_exec else "Not executable",
+                "fixable": not is_exec
+            })
+        else:
+            checks.append({
+                "id": "cli-permission",
+                "title": "CLI Permission (bin/cli.js)",
+                "status": "FAIL",
+                "details": "bin/cli.js missing",
+                "fixable": False
+            })
+
+        # 4. CLI Symlink
+        local_bin = self.home_dir / ".local" / "bin" / "agentic-workflow"
+        usr_bin = Path("/usr/local/bin/agentic-workflow")
+        linked = local_bin.exists() or usr_bin.exists()
+        checks.append({
+            "id": "cli-symlink",
+            "title": "Global CLI Symlink",
+            "status": "PASS" if linked else "WARN",
+            "details": f"Linked at {local_bin if local_bin.exists() else usr_bin}" if linked else "Not linked in user PATH",
+            "fixable": not linked
+        })
+
+        # 5. Dependencies
+        node_modules = self.project_dir / "node_modules"
+        toon_pkg = node_modules / "@toon-format" / "toon"
+        has_deps = node_modules.exists() and toon_pkg.exists()
+        checks.append({
+            "id": "dependencies-npm",
+            "title": "Dependencies (@toon-format/toon)",
+            "status": "PASS" if has_deps else "WARN",
+            "details": "Installed" if has_deps else "node_modules missing or incomplete",
+            "fixable": not has_deps
+        })
+
+        # 6. SOT State
+        sot = self.project_dir / "state.yaml"
+        checks.append({
+            "id": "state-sot",
+            "title": "Single Source of Truth (state.yaml)",
+            "status": "PASS" if sot.exists() else "WARN",
+            "details": "state.yaml present" if sot.exists() else "Workflow state idle",
+            "fixable": False
+        })
+
+        # 7. UAHF Hooks
+        hooks = self.project_dir / ".claude" / "hooks" / "scripts" / "context_guard.py"
+        checks.append({
+            "id": "hooks-uahf",
+            "title": "UAHF Safety & Verification Scripts",
+            "status": "PASS" if hooks.exists() else "FAIL",
+            "details": "UAHF hooks online" if hooks.exists() else "Hooks missing",
+            "fixable": False
+        })
+
+        # 8. Skills Index
+        skills_toon = self.project_dir / "skills-index.toon"
+        checks.append({
+            "id": "skills-mesh",
+            "title": "Skills Mesh Index (skills-index.toon)",
+            "status": "PASS" if skills_toon.exists() else "WARN",
+            "details": "skills-index.toon present" if skills_toon.exists() else "Missing index",
+            "fixable": not skills_toon.exists()
+        })
+
+        passed = sum(1 for c in checks if c["status"] == "PASS")
+        warned = sum(1 for c in checks if c["status"] == "WARN")
+        failed = sum(1 for c in checks if c["status"] == "FAIL")
+
+        return {
+            "passed": passed,
+            "warned": warned,
+            "failed": failed,
+            "total": len(checks),
+            "checks": checks,
+            "overall_healthy": failed == 0
+        }
+
+    def fix_all(self) -> List[Dict[str, Any]]:
+        diag = self.diagnose()
+        fixable = [c for c in diag["checks"] if c["fixable"] and c["status"] != "PASS"]
+        results = []
+
+        for c in fixable:
+            cid = c["id"]
+            if cid == "cli-permission":
+                cli_js = self.project_dir / "bin" / "cli.js"
+                try:
+                    os.chmod(cli_js, 0o755)
+                    results.append({"check_id": cid, "remediated": True, "message": "Chmod 0755 bin/cli.js"})
+                except Exception as e:
+                    results.append({"check_id": cid, "remediated": False, "message": str(e)})
+            elif cid == "cli-symlink":
+                local_bin = self.home_dir / ".local" / "bin"
+                local_bin.mkdir(parents=True, exist_ok=True)
+                target = local_bin / "agentic-workflow"
+                src = self.project_dir / "bin" / "cli.js"
+                try:
+                    if target.exists() or target.is_symlink():
+                        target.unlink()
+                    target.symlink_to(src)
+                    results.append({"check_id": cid, "remediated": True, "message": f"Symlinked {target}"})
+                except Exception as e:
+                    results.append({"check_id": cid, "remediated": False, "message": str(e)})
+            elif cid == "dependencies-npm":
+                try:
+                    subprocess.run("bun install", shell=True, cwd=self.project_dir, capture_output=True)
+                    results.append({"check_id": cid, "remediated": True, "message": "Ran bun install"})
+                except Exception as e:
+                    results.append({"check_id": cid, "remediated": False, "message": str(e)})
+            elif cid == "skills-mesh":
+                try:
+                    subprocess.run("python3 core/skills_indexer.py index", shell=True, cwd=self.project_dir, capture_output=True)
+                    results.append({"check_id": cid, "remediated": True, "message": "Rebuilt skills index"})
+                except Exception as e:
+                    results.append({"check_id": cid, "remediated": False, "message": str(e)})
+        return results

package/core/system/health.py

@@ -0,0 +1,144 @@
+"""
+core/system/health.py — Python Health Telemetry & Scoring Engine
+"""
+
+import os
+import platform
+import subprocess
+import time
+import json
+from pathlib import Path
+from typing import Dict, Any, List
+
+
+class HealthEngine:
+    def __init__(self, project_dir: str = "."):
+        self.project_dir = Path(project_dir).resolve()
+
+    def collect_vitals(self) -> Dict[str, Any]:
+        bun_v = None
+        try:
+            res = subprocess.run("bun --version", shell=True, capture_output=True, text=True)
+            if res.returncode == 0:
+                bun_v = res.stdout.strip()
+        except Exception:
+            pass
+
+        py_v = platform.python_version()
+
+        # Workflow vitals
+        sot = self.project_dir / "state.yaml"
+        has_wf = False
+        step = "idle"
+        if sot.exists():
+            try:
+                txt = sot.read_text(encoding="utf-8")
+                has_wf = "status: in_progress" in txt or "status: planning" in txt
+                for line in txt.splitlines():
+                    if line.strip().startswith("current_step:"):
+                        step = line.split(":", 1)[1].strip().strip('"\'')
+            except Exception:
+                pass
+
+        # Circuit breaker
+        cb = "CLOSED"
+        streak = 0
+        fable_state = self.project_dir / ".fable" / "state.json"
+        if fable_state.exists():
+            try:
+                with open(fable_state, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                    if data.get("circuit_breaker_tripped"):
+                        cb = "OPEN"
+                    streak = data.get("failure_streak", 0)
+            except Exception:
+                pass
+
+        # Traces count
+        traces = 0
+        trace_dir = self.project_dir / ".traces"
+        if trace_dir.exists():
+            for f in trace_dir.glob("*.jsonl"):
+                try:
+                    with open(f, "r", encoding="utf-8") as fp:
+                        traces += sum(1 for _ in fp)
+                except Exception:
+                    pass
+
+        return {
+            "platform": platform.system().lower(),
+            "arch": platform.machine(),
+            "bun_version": bun_v,
+            "python_version": py_v,
+            "has_workflow": has_wf,
+            "current_step": step,
+            "circuit_breaker": cb,
+            "failure_streak": streak,
+            "traces_count": traces
+        }
+
+    def evaluate_score(self, vitals: Dict[str, Any]) -> Dict[str, Any]:
+        score = 100
+        warnings = []
+
+        if not vitals.get("bun_version"):
+            score -= 10
+            warnings.append("Bun runtime missing")
+        if vitals.get("circuit_breaker") == "OPEN":
+            score -= 25
+            warnings.append("Circuit breaker OPEN")
+        elif vitals.get("failure_streak", 0) > 0:
+            score -= min(15, vitals["failure_streak"] * 5)
+            warnings.append(f"Active failure streak: {vitals['failure_streak']}")
+
+        if not (self.project_dir / "node_modules").exists():
+            score -= 10
+            warnings.append("node_modules missing")
+
+        if not (self.project_dir / "skills-index.toon").exists():
+            score -= 10
+            warnings.append("skills-index.toon missing")
+
+        score = max(0, min(100, score))
+        grade = "F"
+        if score >= 95:
+            grade = "A+"
+        elif score >= 85:
+            grade = "A"
+        elif score >= 70:
+            grade = "B"
+        elif score >= 50:
+            grade = "C"
+
+        return {
+            "score": score,
+            "grade": grade,
+            "warnings": warnings
+        }
+
+    def get_report(self) -> Dict[str, Any]:
+        vitals = self.collect_vitals()
+        eval_res = self.evaluate_score(vitals)
+        return {
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "score": eval_res["score"],
+            "grade": eval_res["grade"],
+            "warnings": eval_res["warnings"],
+            "vitals": vitals,
+            "services": {
+                "TS_ENGINE": "HEALTHY" if vitals["bun_version"] else "DEGRADED",
+                "PY_ENGINE": "HEALTHY",
+                "UAHF_HOOKS": "HEALTHY" if (self.project_dir / ".claude" / "hooks" / "scripts").exists() else "DOWN",
+                "SKILLS_MESH": "HEALTHY" if (self.project_dir / "skills-index.toon").exists() else "DEGRADED"
+            }
+        }
+
+    def format_toon(self, report: Dict[str, Any]) -> str:
+        v = report["vitals"]
+        return f"""health_telemetry{{timestamp:"{report['timestamp']}",score:{report['score']},grade:"{report['grade']}"}}:
+  runtime[1]{{os,arch,bun_v,py_v}}:
+    {v['platform']},{v['arch']},{v.get('bun_version') or 'none'},{v['python_version']}
+  workflow[1]{{active,step,circuit_breaker,streak,spans}}:
+    {v['has_workflow']},{v['current_step']},{v['circuit_breaker']},{v['failure_streak']},{v['traces_count']}
+  warnings[{len(report['warnings'])}]:
+""" + "\n".join(f"    - \"{w}\"" for w in report["warnings"])

package/core/system/installer.py

@@ -0,0 +1,137 @@
+"""
+core/system/installer.py — Python Auto-Installer Engine for AgenticWorkflow
+"""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, Any, List
+
+
+class AutoInstaller:
+    def __init__(self, project_dir: str = "."):
+        self.project_dir = Path(project_dir).resolve()
+        self.home_dir = Path.home()
+
+    def _check_binary(self, cmd: str) -> Dict[str, Any]:
+        try:
+            res = subprocess.run(f"{cmd} --version", shell=True, capture_output=True, text=True)
+            return {"available": res.returncode == 0, "version": res.stdout.strip().split("\n")[0]}
+        except Exception:
+            return {"available": False}
+
+    def get_host_targets(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "Claude Code Skills",
+                "platform": "claude",
+                "path": str(self.home_dir / ".claude" / "skills" / "agentic-workflow"),
+                "installed": (self.home_dir / ".claude" / "skills" / "agentic-workflow").exists()
+            },
+            {
+                "name": "Gemini CLI / Antigravity Skills",
+                "platform": "gemini",
+                "path": str(self.home_dir / ".gemini" / "config" / "skills" / "agentic-workflow"),
+                "installed": (self.home_dir / ".gemini" / "config" / "skills" / "agentic-workflow").exists()
+            },
+            {
+                "name": "Cursor IDE Skills",
+                "platform": "cursor",
+                "path": str(self.home_dir / ".cursor" / "skills" / "agentic-workflow"),
+                "installed": (self.home_dir / ".cursor" / "skills" / "agentic-workflow").exists()
+            },
+            {
+                "name": "Codex / OpenCode Skills",
+                "platform": "codex",
+                "path": str(self.home_dir / ".codex" / "skills" / "agentic-workflow"),
+                "installed": (self.home_dir / ".codex" / "skills" / "agentic-workflow").exists()
+            },
+            {
+                "name": "Universal Agent Kernel",
+                "platform": "agents",
+                "path": str(self.home_dir / ".agents" / "skills" / "agentic-workflow"),
+                "installed": (self.home_dir / ".agents" / "skills" / "agentic-workflow").exists()
+            }
+        ]
+
+    def check_status(self) -> Dict[str, Any]:
+        targets = self.get_host_targets()
+        installed = [t for t in targets if t["installed"]]
+        skipped = [t for t in targets if not t["installed"]]
+
+        bin_paths = [
+            str(self.home_dir / ".local" / "bin" / "agentic-workflow"),
+            "/usr/local/bin/agentic-workflow"
+        ]
+        linked = [p for p in bin_paths if os.path.exists(p)]
+
+        deps = [
+            {"name": "bun", **self._check_binary("bun")},
+            {"name": "node", **self._check_binary("node")},
+            {"name": "python3", **self._check_binary("python3")},
+            {"name": "git", **self._check_binary("git")}
+        ]
+
+        return {
+            "success": True,
+            "installed_targets": installed,
+            "skipped_targets": skipped,
+            "bin_linked": linked,
+            "system_deps": deps
+        }
+
+    def install(self, platforms: Optional[List[str]] = None, global_bin: bool = True) -> Dict[str, Any]:
+        requested = platforms or ["claude", "gemini", "cursor", "codex", "agents"]
+        messages = []
+        installed_targets = []
+        bin_linked = []
+
+        targets = self.get_host_targets()
+        for t in targets:
+            if t["platform"] not in requested:
+                continue
+
+            target_path = Path(t["path"])
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            if target_path.exists():
+                shutil.rmtree(target_path, ignore_errors=True)
+
+            try:
+                shutil.copytree(
+                    self.project_dir,
+                    target_path,
+                    ignore=shutil.ignore_patterns("node_modules", ".git", "__pycache__", ".pytest_cache")
+                )
+                t["installed"] = True
+                installed_targets.append(t)
+                messages.append(f"✓ Installed skill to {t['name']}")
+            except Exception as e:
+                messages.append(f"! Failed installing to {t['name']}: {e}")
+
+        # CLI symlink
+        cli_src = self.project_dir / "bin" / "cli.js"
+        if cli_src.exists():
+            try:
+                os.chmod(cli_src, 0o755)
+            except Exception:
+                pass
+
+            local_bin = self.home_dir / ".local" / "bin"
+            local_bin.mkdir(parents=True, exist_ok=True)
+            link_target = local_bin / "agentic-workflow"
+            try:
+                if link_target.exists() or link_target.is_symlink():
+                    link_target.unlink()
+                link_target.symlink_to(cli_src)
+                bin_linked.append(str(link_target))
+                messages.append(f"✓ Linked executable to {link_target}")
+            except Exception as e:
+                messages.append(f"! Failed linking CLI: {e}")
+
+        return {
+            "success": len(installed_targets) > 0 or len(bin_linked) > 0,
+            "installed_targets": installed_targets,
+            "bin_linked": bin_linked,
+            "messages": messages
+        }