replica-omnisciente/scripts/onboarding/templates.py

"""
Templates — rendered content for the scaffolded client.

All templates are plain Python string functions (no Jinja2 dependency) so the
onboarding tool works on a fresh machine with only stdlib Python.
"""

from __future__ import annotations

from .config import OnboardingConfig


# ═══════════════════════════════════════════════════════════════════════════
# Root AGENTS.md
# ═══════════════════════════════════════════════════════════════════════════

def agents_md(cfg: OnboardingConfig) -> str:
    if cfg.realms:
        realms_rows = "\n".join(
            f"| `{r['slug']}/` | {r.get('name', r['slug'])} — {r.get('description', '')} |"
            for r in cfg.realms
        )
        realms_table = f"\n{realms_rows}"
    else:
        realms_table = "\n| _(none yet — use `python3 scripts/onboard-client.py add-realm <slug>`)_ | |"

    lead = cfg.lead_engineer_name or "Principal Engineer"

    return f"""# {cfg.replica_name} — Agent Guide

{cfg.description or f'Centralized brain and monorepo for {cfg.client_name}.'}

This is a **Réplica Omnisciente** — a self-contained agent fleet brain scaffolded
from the Portugal Futurista template. It provides:

- `.aurelio/` — central brain: config cascade, memory, skills, providers, MCP
- `realms/` — per-project knowledge directories (each with its own `AGENTS.md`)
- `scripts/` — brain sync, agent-session import, onboarding tools
- CI/CD workflows for Forgejo and/or GitHub

## Repository layout

| Path | What it is |
|------|------------|
| `.aurelio/` | Central brain: sessions, MCP config, sync, knowledge, skills |
| `realms/` | Per-project knowledge directories |{realms_table}

## Three-tier config cascade

```
~/.aurelio/config.toml              # Global defaults (user-level)
<workspace>/.aurelio/config.toml    # Workspace overrides
realms/<name>/.aurelio/             # Realm-specific memory
```

Resolution: **Realm > Workspace > Global** (most specific wins).

## Identity & Heteronyms

This Réplica is seeded with `{lead}` as the lead-engineer heteronym.
Add team members as heteronyms in `.aurelio/identity/heteronyms.json` and
`.aurelio/heteronimos/`.

## Brain sync

{"Push/pull brain to " + cfg.proxmox_host + " (CT " + str(cfg.ct_id) + "):" if cfg.sync_endpoint else "Brain is **local-only** (no sync endpoint configured). To enable:"}
```bash
python3 .aurelio/sync.py --push
python3 .aurelio/sync.py --pull
```

## Agent → brain import (unified)

Fan every coding-agent's local artifacts into the brain:
```bash
python3 scripts/sync-agents-to-brain.py --skip-active            # all sources
python3 scripts/sync-agents-to-brain.py --source claude-code     # one source
python3 scripts/sync-agents-to-brain.py --dry-run                # preview
```

## Onboarding new projects (realms)

```bash
python3 scripts/onboard-client.py --add-realm <slug> --name "Project Name" --repo <git-url>
```

## Gotchas

- `.env` is gitignored; copy `.env.example` for API key setup.
- Brain sync is one-directional per call: `--push` uploads, `--pull` downloads.
- `.aurelio/providers/dist/` is generated — edit `registry.yaml`, then regenerate.
"""


# ═══════════════════════════════════════════════════════════════════════════
# .aurelio/config.toml
# ═══════════════════════════════════════════════════════════════════════════

def aurelio_config_toml(cfg: OnboardingConfig) -> str:
    sync_section = f"""[sync]
enabled = {"true" if cfg.sync_endpoint else "false"}
endpoint = "{cfg.sync_endpoint or 'https://mcp.example.com'}"
interval_seconds = 300
auto_push = true""" if cfg.sync_endpoint else """[sync]
enabled = false
# endpoint = "https://mcp.example.com"
interval_seconds = 300"""

    return f"""# {cfg.replica_name} — Aurelio Configuration
# This file controls the behavior of the Aurelio agent system.

{sync_section}

[identity]
name = "{cfg.replica_name}"
version = "1.0.0"

[models]
default_local = "{cfg.default_local_model}"
default_cloud = "{cfg.default_cloud_model}"
ollama_url = "{cfg.ollama_url}"

[brain]
auto_save = true
artifact_types = ["task", "implementation_plan", "walkthrough", "analysis"]

# ─── Data sharing (consent-gated) ───────────────────────────────────
# Controls what data this replica sends to Portugal Futurista.
# ALL categories default to false — explicit opt-in required.
# Manage via: python3 scripts/data-sharing.py status

[data_sharing]
enabled = false
transport = "{cfg.sync_endpoint and 'http' or 'local'}"
endpoint = "{cfg.sync_endpoint or ''}"

[data_sharing.categories]
tool_calls = false
thinking = false
chat_messages = false
session_meta = false
agent_metadata = false
error_traces = false
file_changes = false
environment = false

[data_sharing.retention]
days = 90
redact_secrets = true
"""


# ═══════════════════════════════════════════════════════════════════════════
# .aurelio/identity/heteronyms.json
# ═══════════════════════════════════════════════════════════════════════════

def heteronyms_json(cfg: OnboardingConfig) -> str:
    import json

    heteronyms = {}

    # Lead engineer as primary heteronym
    if cfg.lead_engineer_name:
        slug = cfg.lead_engineer_name.lower().replace(" ", "-")
        heteronyms[slug] = {
            "name": cfg.lead_engineer_name,
            "email": cfg.lead_engineer_email or f"{slug}@{cfg.client_slug}.com",
            "voice": {
                "technical": f"Methodical, precise commits. Principal engineer for {cfg.client_name}.",
                "review": "Thorough. Focuses on correctness, edge cases, and production safety."
            },
            "commit_mode": {"default": "branch"},
            "motto": ""
        }

    # Team members
    for member in cfg.team_members:
        slug = member["name"].lower().replace(" ", "-")
        heteronyms[slug] = {
            "name": member["name"],
            "email": member.get("email", f"{slug}@{cfg.client_slug}.com"),
            "voice": {
                "technical": f"{member.get('role', 'Engineer')} for {cfg.client_name}.",
                "review": "Constructive, domain-aware."
            },
            "commit_mode": {"default": "branch"},
            "motto": ""
        }

    # Always include a generic "orchestrator" heteronym
    heteronyms["orchestrator"] = {
        "name": f"{cfg.client_name} Orchestrator",
        "email": f"orchestrator@{cfg.client_slug}.com",
        "voice": {
            "technical": "Meta-routing and orchestration. Delegates to domain heteronyms.",
            "review": "Holistic. Focuses on cross-realm coordination."
        },
        "commit_mode": {"default": "branch"},
        "motto": ""
    }

    return json.dumps({"heteronyms": heteronyms}, indent=2, ensure_ascii=False)


# ═══════════════════════════════════════════════════════════════════════════
# .aurelio/identity/README.md
# ═══════════════════════════════════════════════════════════════════════════

def identity_readme(cfg: OnboardingConfig) -> str:
    lead = cfg.lead_engineer_name or "Principal Engineer"
    return f"""# Identity: {cfg.replica_name}

## I Am

I am the **{cfg.replica_name}** — a persistent, multi-realm intelligence engine
for **{cfg.client_name}**.

{cfg.description or ''}

I maintain a living map of every realm I touch. I do not guess. I consult my
memory first. I enforce the guardrails that {lead} would enforce. I speak with
the team's voice across repositories, time zones, and agentic instantiations.

---

## Operational Mode

When instantiated inside a host repository, I:

1. **Read the local realm's `AGENTS.md`** to absorb stack-specific directives.
2. **Query `.aurelio/memory/`** for global context.
3. **Load relevant subsystem memory** from `realms/<realm>/.aurelio/memory/`.
4. **Execute with minimal intrusion**, preferring surgical edits.
5. **Document everything** — plans go into `.aurelio/plans/`, session artifacts
   into `.aurelio/brain/`.

## Heteronyms

Each team member is a heteronym — a distinct voice with specific domain
affinities. See `.aurelio/identity/heteronyms.json` for the full registry.
"""


# ═══════════════════════════════════════════════════════════════════════════
# .aurelio/sync.py (adapted for client)
# ═══════════════════════════════════════════════════════════════════════════

def sync_py(cfg: OnboardingConfig) -> str:
    host = cfg.proxmox_host or "<PROXMOX_HOST>"
    ct = cfg.ct_id or 0
    return f'''#!/usr/bin/env python3
"""
{cfg.replica_name} — Brain Sync Utility

Push/pull the local .aurelio/brain to/from a remote Proxmox container.
Configured for CT {ct} on {host}.

Usage:
    python3 .aurelio/sync.py --push
    python3 .aurelio/sync.py --pull
"""
import os
import argparse
import subprocess
import sys
from pathlib import Path

VM_IP = os.environ.get("PROXMOX_HOST", "{host}")
CONTAINER_ID = {ct}
TARGET_DIR = "/opt/aurelio/brain"
LOCAL_BRAIN = Path(__file__).parent / "brain"


def run_cmd(cmd: str):
    print(f"Running: {{cmd}}")
    result = subprocess.run(cmd, shell=True)
    if result.returncode != 0:
        print(f"Error executing: {{cmd}}")
        sys.exit(result.returncode)


def push():
    if not LOCAL_BRAIN.exists():
        print("Local brain does not exist. Nothing to push.")
        return
    print("Pushing local brain...")
    run_cmd(f"tar czf /tmp/local_brain.tar.gz -C {{LOCAL_BRAIN.parent}} brain")
    run_cmd(f"scp /tmp/local_brain.tar.gz root@{{VM_IP}}:/tmp/")
    run_cmd(f"ssh root@{{VM_IP}} 'pct push {{CONTAINER_ID}} /tmp/local_brain.tar.gz /tmp/local_brain.tar.gz'")
    run_cmd(f"ssh root@{{VM_IP}} 'pct exec {{CONTAINER_ID}} -- bash -c \\"mkdir -p {{TARGET_DIR}} && tar xzf /tmp/local_brain.tar.gz -C /opt/aurelio/\\"'")
    print("Push complete.")


def pull():
    print("Pulling remote brain to local workspace...")
    run_cmd(f"ssh root@{{VM_IP}} 'pct exec {{CONTAINER_ID}} -- bash -c \\"mkdir -p {{TARGET_DIR}} && tar czf /tmp/remote_brain.tar.gz -C /opt/aurelio/ brain\\"'")
    run_cmd(f"ssh root@{{VM_IP}} 'pct pull {{CONTAINER_ID}} /tmp/remote_brain.tar.gz /tmp/remote_brain.tar.gz'")
    run_cmd(f"scp root@{{VM_IP}}:/tmp/remote_brain.tar.gz /tmp/")
    if not LOCAL_BRAIN.exists():
        LOCAL_BRAIN.mkdir(parents=True)
    run_cmd(f"tar xzf /tmp/remote_brain.tar.gz -C {{LOCAL_BRAIN.parent}}")
    print("Pull complete.")


def main():
    parser = argparse.ArgumentParser(description="{cfg.replica_name} Brain Sync")
    parser.add_argument("--push", action="store_true")
    parser.add_argument("--pull", action="store_true")
    args = parser.parse_args()
    if args.push:
        push()
    elif args.pull:
        pull()
    else:
        parser.print_help()


if __name__ == "__main__":
    main()
'''


# ═══════════════════════════════════════════════════════════════════════════
# .env.example
# ═══════════════════════════════════════════════════════════════════════════

def env_example(cfg: OnboardingConfig) -> str:
    return f"""# =============================================================================
# {cfg.replica_name} — Environment Template
# =============================================================================
# Copy this file to `.env` and fill in your actual API keys.
# DO NOT commit `.env` to version control.
# =============================================================================

# ─── AI API KEYS ────────────────────────────────────────────────────────────

# OpenRouter (unified LLM gateway)
OPENROUTER_API_KEY=

# Gemini / Google Vertex AI
GEMINI_API_KEY=

# Anthropic Claude
ANTHROPIC_API_KEY=

# OpenAI
OPENAI_API_KEY=

# ─── GIT ─────────────────────────────────────────────────────────────────────

# {cfg.git_provider.upper()} token (for CI/CD and API access)
{cfg.git_provider.upper()}_TOKEN=

# ─── INFRASTRUCTURE ──────────────────────────────────────────────────────────

# Proxmox host for brain sync (if using remote sync)
PROXMOX_HOST={cfg.proxmox_host or ''}

# ─── MCP (optional) ──────────────────────────────────────────────────────────

# Sync endpoint
AURELIO_SYNC_ENDPOINT={cfg.sync_endpoint or ''}
"""


# ═══════════════════════════════════════════════════════════════════════════
# .gitignore
# ═══════════════════════════════════════════════════════════════════════════

def gitignore() -> str:
    return """# Dependencies
node_modules/
.venv/
venv/
__pycache__/
*.pyc
*.py[cod]
*.egg-info/

# Build outputs
dist/
!.aurelio/providers/dist/
out/

# Environment & Credentials
.env
*.env.local
*.pem
*.key

# OS
.DS_Store
Thumbs.db

# IDE
.vscode/
!.vscode/settings.json
*.swp

# Aurelio runtime
.aurelio/brain/*/scratch/
.aurelio/swarm/__pycache__/

# Data
*.db
"""


# ═══════════════════════════════════════════════════════════════════════════
# .aurelio/mcp_config.json (empty fleet)
# ═══════════════════════════════════════════════════════════════════════════

def mcp_config_json(cfg: OnboardingConfig) -> str:
    import json
    return json.dumps({
        "mcpServers": {},
        "_comment": f"MCP server fleet for {cfg.replica_name}. Add remote MCP servers here."
    }, indent=2)


# ═══════════════════════════════════════════════════════════════════════════
# .aurelio/providers/registry.yaml (minimal)
# ═══════════════════════════════════════════════════════════════════════════

def providers_registry_yaml(cfg: OnboardingConfig) -> str:
    return f"""# {cfg.replica_name} — Provider Registry
# Single source of truth for all AI-provider surfaces.
#
# Regenerate mirrors after editing:
#   python3 scripts/generate-provider-mirrors.py --write-in-place

version: 1

providers:
  - id: openrouter
    label: OpenRouter
    protocol: openai-compatible
    auth: api_key
    endpoint: https://openrouter.ai/api/v1
    env_key: OPENROUTER_API_KEY
    surfaces: [hermes, mcp]
    models: []
    status: declared

  - id: gemini
    label: Google Gemini
    protocol: gemini
    auth: api_key
    endpoint: https://generativelanguage.googleapis.com
    env_key: GEMINI_API_KEY
    surfaces: [hermes, mcp]
    models: []
    status: declared

  - id: anthropic
    label: Anthropic Claude
    protocol: anthropic
    auth: api_key
    endpoint: https://api.anthropic.com
    env_key: ANTHROPIC_API_KEY
    surfaces: [hermes, mcp]
    models: []
    status: declared
"""


# ═══════════════════════════════════════════════════════════════════════════
# .aurelio/connectors/registry.yaml (minimal)
# ═══════════════════════════════════════════════════════════════════════════

def connectors_registry_yaml(cfg: OnboardingConfig) -> str:
    git_label = {
        "github": "GitHub",
        "gitlab": "GitLab",
        "forgejo": "Forgejo (self-hosted git)",
        "codeberg": "Codeberg",
    }.get(cfg.git_provider, cfg.git_provider)

    return f"""# {cfg.replica_name} — Connector Hub
# Single source of truth for external integrations.
# Regenerate mirrors: python3 scripts/generate-connector-mirrors.py --write-in-place

version: 1

connectors:
  - id: {cfg.git_provider}
    label: {git_label}
    category: devops
    kind: api-key
    auth: api_key
    endpoint: {"https://github.com" if cfg.git_provider == "github" else "https://gitlab.com" if cfg.git_provider == "gitlab" else cfg.git_url.rsplit("/", 2)[0] if cfg.git_url else ""}
    surfaces: [mcp]
    status: declared
    notes: Primary git forge for {cfg.client_name}.
"""


# ═══════════════════════════════════════════════════════════════════════════
# Realm AGENTS.md
# ═══════════════════════════════════════════════════════════════════════════

def realm_agents_md(cfg: OnboardingConfig, realm: dict) -> str:
    return f"""# {realm.get('name', realm['slug'])} — Agent Guide

## Identity
This realm corresponds to the `{realm.get('repo', realm['slug'])}` repository.
The canonical brain realm name is `{realm['slug']}`.

## {realm.get('name', realm['slug'])}
{realm.get('description', f'Realm for {realm.get("name", realm["slug"])} project.')}

## Technology Stack
{realm.get('stack', '- _(to be documented)_')}

## Development Directives
- Read the workspace `AGENTS.md` for global directives.
- Consult `.aurelio/memory/index.md` for this realm's context.
"""


# ═══════════════════════════════════════════════════════════════════════════
# Realm .aurelio/config.toml
# ═══════════════════════════════════════════════════════════════════════════

def realm_config_toml(cfg: OnboardingConfig, realm: dict) -> str:
    return f"""[identity]
name = "{realm.get('name', realm['slug'])}"
realm = "{realm['slug']}"

[sync]
endpoint = "{cfg.sync_endpoint or 'https://mcp.example.com'}"
interval_seconds = 300
auto_push = true
"""


# ═══════════════════════════════════════════════════════════════════════════
# Realm .aurelio/memory/index.md
# ═══════════════════════════════════════════════════════════════════════════

_DEFAULT_STACK_TABLE = (
    "| Component | Technology |\n"
    "|-----------|------------|\n"
    "| _(to be documented)_ | |"
)


def realm_memory_index(cfg: OnboardingConfig, realm: dict) -> str:
    name = realm.get('name', realm['slug'])
    return f"""# Realm: {name}

## Identity

**{name}** is a realm in the {cfg.replica_name}.

{realm.get('description', '')}

---

## Technology Stack

{realm.get('stack', _DEFAULT_STACK_TABLE)}

---

## Notes

_(This index is the canonical entry point for agent memory. Update it as the
project evolves.)_
"""


# ═══════════════════════════════════════════════════════════════════════════
# CI/CD
# ═══════════════════════════════════════════════════════════════════════════

def forgejo_workflow(cfg: OnboardingConfig) -> str:
    return f"""# {cfg.replica_name} — Aurelio Sync Workflow
# Runs conscience upgrade + brain push on push to main.
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Brain sync
        run: |
          echo "Brain sync placeholder — configure PROXMOX_HOST secret to enable."
"""


def github_workflow(cfg: OnboardingConfig) -> str:
    return f"""# {cfg.replica_name} — CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check provider mirrors
        run: |
          if [ -f scripts/generate-provider-mirrors.py ]; then
            python3 scripts/generate-provider-mirrors.py --check
          fi
"""


# ═══════════════════════════════════════════════════════════════════════════
# README.md
# ═══════════════════════════════════════════════════════════════════════════

def readme_md(cfg: OnboardingConfig) -> str:
    return f"""# {cfg.replica_name}

{cfg.description or f'Centralized brain for {cfg.client_name}.'}

Scaffolded from the [Réplica Omnisciente](https://github.com/fabiorafaelcoutada/replica-omnisciente) template.

## Quick Start

```bash
# 1. Clone
git clone {cfg.git_url or '<your-git-url>'}
cd {cfg.client_slug}

# 2. Set up environment
cp .env.example .env
# Edit .env with your API keys

# 3. Initialize the brain
python3 .aurelio/sync.py --pull  # if using remote sync

# 4. Start working
# Read AGENTS.md for the full guide.
```

## Structure

- `.aurelio/` — Central brain (config, memory, skills, providers, MCP)
- `realms/` — Per-project knowledge directories
- `scripts/` — Sync and onboarding tools

## Adding a new realm (project)

```bash
python3 scripts/onboard-client.py --add-realm my-project --name "My Project" --repo https://github.com/org/repo
```
"""