arkaos 2.2.2 → 2.3.1

package/scripts/knowledge-index.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Knowledge Indexer — index markdown files into vector store.
+
+Usage:
+    python scripts/knowledge-index.py --vault ~/Documents/Personal
+    python scripts/knowledge-index.py --dir departments/ --db /tmp/test.db
+    python scripts/knowledge-index.py --stats
+    python scripts/knowledge-index.py --search "security vulnerability"
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+ARKAOS_ROOT = Path(os.environ.get("ARKAOS_ROOT", Path(__file__).resolve().parent.parent))
+sys.path.insert(0, str(ARKAOS_ROOT))
+
+DEFAULT_DB = Path.home() / ".arkaos" / "knowledge.db"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="ArkaOS Knowledge Indexer")
+    parser.add_argument("--vault", type=str, help="Obsidian vault path to index")
+    parser.add_argument("--dir", type=str, help="Directory to index")
+    parser.add_argument("--db", type=str, default=str(DEFAULT_DB), help="Vector DB path")
+    parser.add_argument("--search", type=str, help="Search query")
+    parser.add_argument("--stats", action="store_true", help="Show DB statistics")
+    parser.add_argument("--clear", action="store_true", help="Clear all indexed data")
+    parser.add_argument("--json", action="store_true", dest="json_output", help="JSON output")
+    args = parser.parse_args()
+
+    from core.knowledge.vector_store import VectorStore
+
+    db_path = Path(args.db)
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    store = VectorStore(db_path)
+
+    if args.clear:
+        store.clear()
+        print("Knowledge base cleared." if not args.json_output else json.dumps({"cleared": True}))
+        return 0
+
+    if args.stats:
+        stats = store.get_stats()
+        if args.json_output:
+            print(json.dumps(stats, indent=2))
+        else:
+            print(f"Chunks:     {stats['total_chunks']}")
+            print(f"Files:      {stats['total_files']}")
+            print(f"VSS:        {'enabled' if stats['vss_available'] else 'disabled (keyword fallback)'}")
+            print(f"DB:         {stats['db_path']}")
+        return 0
+
+    if args.search:
+        results = store.search(args.search, top_k=5)
+        if args.json_output:
+            print(json.dumps(results, indent=2))
+        else:
+            if not results:
+                print("No results found.")
+            for i, r in enumerate(results, 1):
+                src = Path(r.get("source", "")).name if r.get("source") else "unknown"
+                print(f"\n[{i}] Score: {r['score']:.3f} | {src}")
+                if r.get("heading"):
+                    print(f"    Heading: {r['heading']}")
+                print(f"    {r['text'][:200]}...")
+        return 0
+
+    # Index mode
+    directory = args.vault or args.dir
+    if not directory:
+        # Auto-detect vault from config
+        config_path = ARKAOS_ROOT / "knowledge" / "obsidian-config.json"
+        if config_path.exists():
+            config = json.loads(config_path.read_text())
+            vault = config.get("vault_path", "")
+            if vault and Path(vault).exists():
+                directory = vault
+
+    if not directory:
+        print("No directory specified. Use --vault or --dir.", file=sys.stderr)
+        return 2
+
+    if not Path(directory).exists():
+        print(f"Directory not found: {directory}", file=sys.stderr)
+        return 2
+
+    from core.knowledge.indexer import index_directory
+
+    def progress(current, total, name):
+        if not args.json_output:
+            print(f"\r  [{current}/{total}] {name[:50]}...", end="", flush=True)
+
+    print(f"Indexing: {directory}" if not args.json_output else "", file=sys.stderr)
+    result = index_directory(directory, store, on_progress=progress)
+
+    if not args.json_output:
+        print()  # newline after progress
+        print(f"\nFiles scanned:  {result['files_scanned']}")
+        print(f"Files indexed:  {result['files_indexed']}")
+        print(f"Files skipped:  {result['files_skipped']}")
+        print(f"Chunks created: {result['chunks_created']}")
+    else:
+        print(json.dumps(result, indent=2))
+
+    store.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/skill_validator.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""ArkaOS v2 Skill Validator — validates SKILL.md files against project standards.
+
+Exit codes: 0 = all passed, 1 = warnings only, 2 = failures found.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+WEIGHTS = {
+    "skill_md_exists": 20, "frontmatter_present": 15, "required_fields": 15,
+    "name_format": 10, "allowed_tools_list": 5, "has_h1": 10, "has_h2": 5,
+    "line_count": 5, "agent_attribution": 10, "output_section": 5,
+}
+
+
+@dataclass
+class SkillResult:
+    """Validation result for a single skill."""
+    name: str
+    score: int = 100
+    level: str = "EXCELLENT"
+    issues: list[str] = field(default_factory=list)
+
+    def deduct(self, points: int, reason: str) -> None:
+        self.score = max(0, self.score - points)
+        self.issues.append(reason)
+
+    def finalize(self) -> None:
+        if self.score >= 90:
+            self.level = "EXCELLENT"
+        elif self.score >= 70:
+            self.level = "GOOD"
+        elif self.score >= 50:
+            self.level = "WARN"
+        else:
+            self.level = "FAIL"
+
+    @property
+    def passed(self) -> bool:
+        return self.level in ("EXCELLENT", "GOOD")
+
+    @property
+    def is_warning(self) -> bool:
+        return self.level == "WARN"
+
+    @property
+    def is_failure(self) -> bool:
+        return self.level == "FAIL"
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "score": self.score, "level": self.level, "issues": self.issues}
+
+
+def parse_frontmatter(content: str) -> dict[str, str | list[str]] | None:
+    """Extract YAML frontmatter between --- markers (no PyYAML needed)."""
+    match = re.match(r"^---\s*\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        return None
+    data: dict[str, str | list[str]] = {}
+    for line in match.group(1).split("\n"):
+        key_match = re.match(r"^(\w[\w-]*)\s*:\s*(.*)", line)
+        if key_match:
+            key, value = key_match.group(1), key_match.group(2).strip()
+            list_match = re.match(r"^\[(.+)]$", value)
+            if list_match:
+                data[key] = [v.strip() for v in list_match.group(1).split(",")]
+            elif value in (">", "|"):
+                data[key] = ""
+            else:
+                data[key] = value
+        elif line.startswith("  ") and data:
+            last_key = list(data.keys())[-1]
+            if isinstance(data[last_key], str):
+                data[last_key] = (data[last_key] + " " + line.strip()).strip()
+    return data
+
+
+def validate_skill(skill_dir: Path) -> SkillResult:
+    """Validate a single skill directory against ArkaOS v2 standards."""
+    parts = skill_dir.resolve().parts
+    try:
+        dept = parts[parts.index("departments") + 1]
+    except (ValueError, IndexError):
+        dept = "unknown"
+    result = SkillResult(name=f"{dept}/{skill_dir.name}")
+    skill_md = skill_dir / "SKILL.md"
+
+    if not skill_md.is_file():
+        result.deduct(WEIGHTS["skill_md_exists"], "missing SKILL.md")
+        result.finalize()
+        return result
+
+    content = skill_md.read_text(encoding="utf-8")
+    line_count = content.count("\n") + 1
+
+    # Frontmatter checks
+    fm = parse_frontmatter(content)
+    if fm is None:
+        for key in ("frontmatter_present", "required_fields", "name_format", "allowed_tools_list"):
+            result.deduct(WEIGHTS[key], f"no {key.replace('_', ' ')} (no frontmatter)")
+    else:
+        missing = [f for f in ("name", "description", "allowed-tools") if f not in fm]
+        if missing:
+            result.deduct(WEIGHTS["required_fields"], f"missing fields: {', '.join(missing)}")
+        name_val = fm.get("name", "")
+        if isinstance(name_val, str) and not re.match(r"^[a-z][\w-]*/[\w-]+$", name_val):
+            result.deduct(WEIGHTS["name_format"], f"name '{name_val}' does not match dept/slug format")
+        tools = fm.get("allowed-tools")
+        if tools is not None and not isinstance(tools, list):
+            result.deduct(WEIGHTS["allowed_tools_list"], "allowed-tools is not a list")
+
+    # Content checks (strip frontmatter)
+    body = re.sub(r"^---.*?---\s*", "", content, count=1, flags=re.DOTALL)
+    if not re.search(r"^# ", body, re.MULTILINE):
+        result.deduct(WEIGHTS["has_h1"], "no H1 heading found")
+    if not re.search(r"^## ", body, re.MULTILINE):
+        result.deduct(WEIGHTS["has_h2"], "no H2 heading found")
+
+    # Line count: error if outside 30-200, soft warn if outside 60-120
+    if line_count < 30 or line_count > 200:
+        result.deduct(WEIGHTS["line_count"], f"line count {line_count} outside 30-200 range")
+    elif line_count < 60 or line_count > 120:
+        result.deduct(WEIGHTS["line_count"] // 2, f"line count {line_count} outside ideal 60-120 range")
+
+    if not re.search(r"^>\s*\*\*Agent:", body, re.MULTILINE):
+        result.deduct(WEIGHTS["agent_attribution"], "missing agent attribution (> **Agent:** line)")
+    if not re.search(r"^##\s+Output", body, re.MULTILINE):
+        result.deduct(WEIGHTS["output_section"], "missing ## Output section")
+
+    result.finalize()
+    return result
+
+
+def discover_skills(root: Path) -> list[Path]:
+    """Recursively find all directories containing SKILL.md."""
+    skills = [Path(dp) for dp, _, fns in os.walk(root) if "SKILL.md" in fns]
+    skills.sort(key=lambda p: str(p))
+    return skills
+
+
+def _counts(results: list[SkillResult]) -> tuple[int, int, int]:
+    passed = sum(1 for r in results if r.passed)
+    warnings = sum(1 for r in results if r.is_warning)
+    failures = sum(1 for r in results if r.is_failure)
+    return passed, warnings, failures
+
+
+def print_text(results: list[SkillResult], summary_only: bool = False) -> None:
+    """Print human-readable validation output."""
+    if not summary_only:
+        for r in results:
+            icon = "\u2713" if r.passed else ("\u26A0" if r.is_warning else "\u2717")
+            suffix = f" ({', '.join(r.issues)})" if r.issues else ""
+            print(f"{icon} {r.name} \u2014 {r.score}/100 {r.level}{suffix}")
+        print()
+    passed, warnings, failures = _counts(results)
+    print(f"Summary: {len(results)} skills validated, {passed} passed, {warnings} warnings, {failures} failures")
+
+
+def print_json(results: list[SkillResult]) -> None:
+    """Print JSON validation output."""
+    passed, warnings, failures = _counts(results)
+    output = {
+        "total": len(results), "passed": passed, "warnings": warnings,
+        "failures": failures, "skills": [r.to_dict() for r in results],
+    }
+    print(json.dumps(output, indent=2))
+
+
+def main() -> int:
+    """Entry point. Returns exit code."""
+    parser = argparse.ArgumentParser(
+        description="ArkaOS v2 Skill Validator — validate SKILL.md files against project standards.",
+        epilog="Exit codes: 0 = all passed, 1 = warnings only, 2 = failures found.",
+    )
+    parser.add_argument("path", type=Path, help="Skill directory or parent to scan recursively.")
+    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON.")
+    parser.add_argument("--summary", action="store_true", help="Print only summary totals.")
+    args = parser.parse_args()
+    target: Path = args.path.resolve()
+
+    if not target.exists():
+        print(f"Error: path does not exist: {target}", file=sys.stderr)
+        return 2
+
+    if (target / "SKILL.md").is_file():
+        skill_dirs = [target]
+    elif target.is_dir():
+        skill_dirs = discover_skills(target)
+    else:
+        print(f"Error: {target} is not a directory", file=sys.stderr)
+        return 2
+
+    if not skill_dirs:
+        print("No SKILL.md files found.", file=sys.stderr)
+        return 2
+
+    results = [validate_skill(d) for d in skill_dirs]
+    if args.json_output:
+        print_json(results)
+    else:
+        print_text(results, summary_only=args.summary)
+
+    if any(r.is_failure for r in results):
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/start-dashboard.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# ArkaOS Dashboard — Start FastAPI + Nuxt servers
+set -euo pipefail
+
+ARKAOS_ROOT="${ARKAOS_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+DASHBOARD_DIR="${ARKAOS_ROOT}/dashboard"
+PID_FILE="$HOME/.arkaos/dashboard.pid"
+API_PORT="${ARKAOS_DASHBOARD_API_PORT:-3334}"
+UI_PORT="${ARKAOS_DASHBOARD_UI_PORT:-3333}"
+
+mkdir -p "$HOME/.arkaos"
+
+# Check if already running
+if [ -f "$PID_FILE" ]; then
+  api_pid=$(head -1 "$PID_FILE" 2>/dev/null || echo "")
+  ui_pid=$(tail -1 "$PID_FILE" 2>/dev/null || echo "")
+  if [ -n "$api_pid" ] && kill -0 "$api_pid" 2>/dev/null; then
+    echo "Dashboard already running (API PID: $api_pid, UI PID: $ui_pid)"
+    echo "  API: http://localhost:${API_PORT}"
+    echo "  UI:  http://localhost:${UI_PORT}"
+    exit 0
+  fi
+  rm -f "$PID_FILE"
+fi
+
+# Start FastAPI backend
+echo "Starting API server on :${API_PORT}..."
+ARKAOS_ROOT="$ARKAOS_ROOT" python3 "${ARKAOS_ROOT}/scripts/dashboard-api.py" --port "$API_PORT" &
+API_PID=$!
+
+# Check if Nuxt is built
+if [ -d "${DASHBOARD_DIR}/.output" ]; then
+  echo "Starting dashboard on :${UI_PORT}..."
+  PORT="$UI_PORT" node "${DASHBOARD_DIR}/.output/server/index.mjs" &
+  UI_PID=$!
+elif [ -d "${DASHBOARD_DIR}/node_modules" ]; then
+  echo "Starting dashboard (dev mode) on :${UI_PORT}..."
+  cd "$DASHBOARD_DIR" && npx nuxt dev --port "$UI_PORT" &
+  UI_PID=$!
+else
+  echo "Dashboard not built. Run: cd dashboard && npm install && npm run build"
+  UI_PID=""
+fi
+
+# Save PIDs
+echo "$API_PID" > "$PID_FILE"
+[ -n "${UI_PID:-}" ] && echo "$UI_PID" >> "$PID_FILE"
+
+echo ""
+echo "ArkaOS Dashboard running:"
+echo "  API: http://localhost:${API_PORT}/api/overview"
+[ -n "${UI_PID:-}" ] && echo "  UI:  http://localhost:${UI_PORT}"
+echo ""
+echo "Stop with: kill \$(cat $PID_FILE)"

package/scripts/synapse-bridge.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Synapse Bridge — standalone script for hook integration.
+
+Reads JSON from stdin, runs the 8-layer Synapse engine, outputs JSON to stdout.
+Loads constitution, agent registry, and command registry automatically.
+
+Usage:
+    echo '{"user_input":"validate my saas idea"}' | python3 scripts/synapse-bridge.py
+    echo '{}' | python3 scripts/synapse-bridge.py --layers-only
+
+Exit codes: 0 = success, 1 = degraded (partial layers), 2 = error
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+# Resolve ArkaOS root from environment or script location
+ARKAOS_ROOT = Path(os.environ.get("ARKAOS_ROOT", Path(__file__).resolve().parent.parent))
+sys.path.insert(0, str(ARKAOS_ROOT))
+
+
+def load_constitution(root: Path) -> str:
+    """Load and compress constitution rules."""
+    config_path = root / "config" / "constitution.yaml"
+    if not config_path.exists():
+        return ""
+    try:
+        from core.governance.constitution import load_constitution as _load
+        const = _load(str(config_path))
+        parts = []
+        for level_name in ("non_negotiable", "quality_gate", "must", "should"):
+            level = getattr(const, level_name, None)
+            if level and hasattr(level, "rules"):
+                ids = [r.id for r in level.rules]
+                if ids:
+                    parts.append(f"{level_name.upper()}: {', '.join(ids)}")
+        return " | ".join(parts) if parts else ""
+    except Exception:
+        return ""
+
+
+def load_agents_registry(root: Path) -> dict:
+    """Load agents registry JSON."""
+    path = root / "knowledge" / "agents-registry-v2.json"
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+        agents = {}
+        for agent in data.get("agents", []):
+            agent_id = agent.get("id", "")
+            if agent_id:
+                agents[agent_id] = agent
+        return agents
+    except Exception:
+        return {}
+
+
+def load_commands_registry(root: Path) -> list:
+    """Load commands registry JSON."""
+    path = root / "knowledge" / "commands-registry-v2.json"
+    if not path.exists():
+        return []
+    try:
+        data = json.loads(path.read_text())
+        return data.get("commands", [])
+    except Exception:
+        return []
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Synapse Bridge — context injection for hooks")
+    parser.add_argument("--layers-only", action="store_true", help="Output layer breakdown instead of context string")
+    parser.add_argument("--root", type=str, default=str(ARKAOS_ROOT), help="ArkaOS root directory")
+    args = parser.parse_args()
+
+    root = Path(args.root)
+    start = time.time()
+
+    # Read input from stdin
+    try:
+        raw = sys.stdin.read().strip()
+        input_data = json.loads(raw) if raw else {}
+    except (json.JSONDecodeError, Exception):
+        input_data = {}
+
+    # Extract context fields
+    user_input = input_data.get("user_input", "")
+    if not user_input:
+        # Claude Code hook format: the full input is the user message
+        user_input = raw if raw and not raw.startswith("{") else ""
+
+    # Load registries
+    constitution = load_constitution(root)
+    agents = load_agents_registry(root)
+    commands = load_commands_registry(root)
+
+    # Load vector store (optional — graceful if unavailable)
+    vector_store = None
+    kb_db = Path(os.environ.get("ARKAOS_KNOWLEDGE_DB", Path.home() / ".arkaos" / "knowledge.db"))
+    if kb_db.exists():
+        try:
+            from core.knowledge.vector_store import VectorStore
+            vector_store = VectorStore(kb_db)
+        except Exception:
+            pass
+
+    # Build engine
+    try:
+        from core.synapse.engine import create_default_engine
+        from core.synapse.layers import PromptContext
+
+        engine = create_default_engine(
+            constitution_compressed=constitution,
+            commands=commands,
+            agents_registry=agents,
+            vector_store=vector_store,
+        )
+
+        # Build context
+        import subprocess
+        try:
+            branch = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                capture_output=True, text=True, timeout=2,
+                cwd=input_data.get("cwd", os.getcwd()),
+            ).stdout.strip()
+        except Exception:
+            branch = ""
+
+        ctx = PromptContext(
+            user_input=user_input,
+            cwd=input_data.get("cwd", os.getcwd()),
+            git_branch=branch,
+            project_name=input_data.get("project_name", ""),
+            project_stack=input_data.get("project_stack", ""),
+            active_agent=input_data.get("active_agent", ""),
+            runtime_id=input_data.get("runtime_id", "claude-code"),
+        )
+
+        result = engine.inject(ctx)
+        total_ms = int((time.time() - start) * 1000)
+
+        # Record token usage in budget tracker
+        try:
+            from core.budget.manager import BudgetManager
+            budget_mgr = BudgetManager(storage_path=Path.home() / ".arkaos" / "budget-usage.json")
+            # Extract department from result layers
+            dept = ""
+            for lr in result.layers:
+                if lr.layer_id == "L1" and lr.tag:
+                    dept = lr.tag.replace("[dept:", "").replace("]", "")
+                    break
+            budget_mgr.record_usage(
+                agent_id=ctx.active_agent or "system",
+                tokens=result.total_tokens_est,
+                tier=2,
+                department=dept,
+                description="synapse-context-injection",
+            )
+        except Exception:
+            pass  # Never block on budget tracking
+
+        if args.layers_only:
+            output = {
+                "context_string": result.context_string,
+                "layers": [
+                    {"id": lr.layer_id, "tag": lr.tag, "tokens": lr.tokens_est, "cached": lr.cached, "ms": lr.compute_ms}
+                    for lr in result.layers
+                ],
+                "total_ms": total_ms,
+                "total_tokens": result.total_tokens_est,
+                "cache_stats": result.cache_stats,
+                "layers_skipped": result.layers_skipped,
+            }
+        else:
+            output = {"context_string": result.context_string, "total_ms": total_ms}
+
+        print(json.dumps(output))
+        return 0
+
+    except ImportError as e:
+        # Python dependencies not available — output minimal context
+        sys.stderr.write(f"synapse-bridge: import error: {e}\n")
+        print(json.dumps({"context_string": "", "error": str(e)}))
+        return 1
+
+    except Exception as e:
+        sys.stderr.write(f"synapse-bridge: error: {e}\n")
+        print(json.dumps({"context_string": "", "error": str(e)}))
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())