agh 0.1.0__tar.gz

agh-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: agh
+Version: 0.1.0
+Summary: Agent Guidance Hub
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.27
+
+<div align="center">
+
+# Agent Guidance Hub (AGH)
+
+<p><strong>Self-hosted agent instructions and skills, synced per repo.</strong></p>
+
+</div>
+
+---
+
+[Español](README.es.md)
+
+## What AGH is for
+
+AGH gives teams one place to publish the instructions and reusable skills their coding agents use in repos: `AGENTS.md`, `CLAUDE.md`, and skill files placed under agent harness directories.
+
+Without AGH, those files tend to drift from repo to repo. With AGH, you publish a versioned pack, assign it to a project, and apply the assigned files in each repo.
+
+```text
+AGH Docker service
+  ├─ /data/agh.sqlite3
+  ├─ /data/packs/
+  ├─ /data/logs/agh.log
+  └─ /data/secrets/initial_owner_token
+        ↓ manifest + pack downloads
+repository
+  ├─ AGENTS.md / CLAUDE.md
+  ├─ .claude/skills/.../SKILL.md
+  ├─ .opencode/skills/.../SKILL.md
+  └─ .agh/lock.toml
+```
+
+## Quick Start
+
+Run the server with Docker:
+
+```bash
+docker build -t agh .
+docker run --rm -p 8912:8912 -v agh-data:/data \
+  -e AGH_BOOTSTRAP_OWNER_EMAIL=owner@example.com \
+  agh
+```
+
+Install the local CLI, then log in with the first owner token:
+
+```bash
+uv tool install --force .
+
+agh login \
+  --url http://127.0.0.1:8912 \
+  --email owner@example.com \
+  --token "$(docker run --rm -v agh-data:/data busybox cat /data/secrets/initial_owner_token)"
+```
+
+Then work from a repo:
+
+```bash
+agh sync
+agh pull --dry-run
+agh pull
+agh agent
+```
+
+## Docs
+
+| Guide | Use it for |
+|-------|------------|
+| [Installation](docs/installation.md) | Install the local `agh` CLI and run the Docker server. |
+| [Quickstart](docs/quickstart.md) | First Docker run, login, project link, and workspace apply flow. |
+| [Packs](docs/packs.md) | Create, publish, and list instruction/skill packs. |
+| [Projects](docs/projects.md) | Create projects and assign packs to repos. |
+| [Admin](docs/admin.md) | Bootstrap owner, users, roles, tokens, and local config. |
+| [Workspace guide](docs/workspace.md) | Repo setup, workspace apply behavior, markers, skills, lockfile, and Git rules. |
+| [Operations](docs/operations.md) | Docker runtime layout, `/data`, logs, healthcheck, backup, and upgrades. |
+
+## Core Concepts
+
+| Concept | Meaning |
+|---------|---------|
+| Pack | Versioned set of instruction files and agent skills. |
+| Project | AGH record linked to a git repository. |
+| Pull manifest | Server plan for the files a repo should download and apply. |
+| Lockfile | `.agh/lock.toml`; resolved versions, checksums, sources, and placement mode. |
+| Cache | `.agh-cache/packs/`; downloaded pack files that AGH can rebuild. |
+
+## Git Rule
+
+Commit the stable project state:
+
+- `.agh/project.toml`
+- `.agh/lock.toml`
+- `AGENTS.md` / `CLAUDE.md`
+
+Ignore the cache:
+
+```gitignore
+.agh-cache/
+```
+
+Skill targets under `.claude/skills/` and `.opencode/skills/` are generated by the workspace pull flow. Commit them only if your team wants agent skills reviewed in Git. If they are symlinks, refresh the workspace after clone to rebuild `.agh-cache/packs/`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+For local server work without Docker, see [Operations](docs/operations.md#local-development).

agh-0.1.0/README.md

@@ -0,0 +1,109 @@
+<div align="center">
+
+# Agent Guidance Hub (AGH)
+
+<p><strong>Self-hosted agent instructions and skills, synced per repo.</strong></p>
+
+</div>
+
+---
+
+[Español](README.es.md)
+
+## What AGH is for
+
+AGH gives teams one place to publish the instructions and reusable skills their coding agents use in repos: `AGENTS.md`, `CLAUDE.md`, and skill files placed under agent harness directories.
+
+Without AGH, those files tend to drift from repo to repo. With AGH, you publish a versioned pack, assign it to a project, and apply the assigned files in each repo.
+
+```text
+AGH Docker service
+  ├─ /data/agh.sqlite3
+  ├─ /data/packs/
+  ├─ /data/logs/agh.log
+  └─ /data/secrets/initial_owner_token
+        ↓ manifest + pack downloads
+repository
+  ├─ AGENTS.md / CLAUDE.md
+  ├─ .claude/skills/.../SKILL.md
+  ├─ .opencode/skills/.../SKILL.md
+  └─ .agh/lock.toml
+```
+
+## Quick Start
+
+Run the server with Docker:
+
+```bash
+docker build -t agh .
+docker run --rm -p 8912:8912 -v agh-data:/data \
+  -e AGH_BOOTSTRAP_OWNER_EMAIL=owner@example.com \
+  agh
+```
+
+Install the local CLI, then log in with the first owner token:
+
+```bash
+uv tool install --force .
+
+agh login \
+  --url http://127.0.0.1:8912 \
+  --email owner@example.com \
+  --token "$(docker run --rm -v agh-data:/data busybox cat /data/secrets/initial_owner_token)"
+```
+
+Then work from a repo:
+
+```bash
+agh sync
+agh pull --dry-run
+agh pull
+agh agent
+```
+
+## Docs
+
+| Guide | Use it for |
+|-------|------------|
+| [Installation](docs/installation.md) | Install the local `agh` CLI and run the Docker server. |
+| [Quickstart](docs/quickstart.md) | First Docker run, login, project link, and workspace apply flow. |
+| [Packs](docs/packs.md) | Create, publish, and list instruction/skill packs. |
+| [Projects](docs/projects.md) | Create projects and assign packs to repos. |
+| [Admin](docs/admin.md) | Bootstrap owner, users, roles, tokens, and local config. |
+| [Workspace guide](docs/workspace.md) | Repo setup, workspace apply behavior, markers, skills, lockfile, and Git rules. |
+| [Operations](docs/operations.md) | Docker runtime layout, `/data`, logs, healthcheck, backup, and upgrades. |
+
+## Core Concepts
+
+| Concept | Meaning |
+|---------|---------|
+| Pack | Versioned set of instruction files and agent skills. |
+| Project | AGH record linked to a git repository. |
+| Pull manifest | Server plan for the files a repo should download and apply. |
+| Lockfile | `.agh/lock.toml`; resolved versions, checksums, sources, and placement mode. |
+| Cache | `.agh-cache/packs/`; downloaded pack files that AGH can rebuild. |
+
+## Git Rule
+
+Commit the stable project state:
+
+- `.agh/project.toml`
+- `.agh/lock.toml`
+- `AGENTS.md` / `CLAUDE.md`
+
+Ignore the cache:
+
+```gitignore
+.agh-cache/
+```
+
+Skill targets under `.claude/skills/` and `.opencode/skills/` are generated by the workspace pull flow. Commit them only if your team wants agent skills reviewed in Git. If they are symlinks, refresh the workspace after clone to rebuild `.agh-cache/packs/`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+For local server work without Docker, see [Operations](docs/operations.md#local-development).

agh-0.1.0/agh/__init__.py

@@ -0,0 +1,3 @@
+"""Agent Guidance Hub."""
+
+__version__ = "0.1.0"

agh-0.1.0/agh/cli/__init__.py

@@ -0,0 +1 @@
+"""AGH Typer CLI."""

agh-0.1.0/agh/cli/agent_integrations.py

@@ -0,0 +1,98 @@
+"""Advisory local agent integration detection."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AgentAvailability:
+    """Advisory availability for a local agent integration."""
+
+    name: str
+    command: str
+    workspace_dir: str
+    available: bool
+    command_path: str | None
+    workspace_dir_exists: bool
+
+
+def detect_agent_availability(
+    *,
+    workspace: Path | None = None,
+    path: str | None = None,
+) -> list[AgentAvailability]:
+    """Detect known local agent integrations without creating or modifying files."""
+    root = Path.cwd() if workspace is None else workspace
+    return [
+        _detect_agent(
+            name="Claude Code",
+            command="claude",
+            workspace_dir=".claude",
+            workspace=root,
+            path=path,
+        ),
+        _detect_agent(
+            name="OpenCode",
+            command="opencode",
+            workspace_dir=".opencode",
+            workspace=root,
+            path=path,
+        ),
+    ]
+
+
+def format_agent_availability(agents: list[AgentAvailability]) -> str:
+    """Render sober, plain advisory output for `agh agent`."""
+    lines: list[str] = []
+    for agent in agents:
+        marker = "✓" if agent.available else "✗"
+        status = "available" if agent.available else "not found"
+        reasons: list[str] = []
+        if agent.command_path is not None:
+            reasons.append(f"command: {agent.command_path}")
+        if agent.workspace_dir_exists:
+            reasons.append(f"workspace: {agent.workspace_dir}/")
+        reason_text = f" ({', '.join(reasons)})" if reasons else ""
+        lines.append(f"{agent.name}: {marker} {status}{reason_text}")
+    return "\n".join(lines)
+
+
+def relative_symlink_target(*, source: Path, target: Path) -> str:
+    """Return a portable relative symlink target from target parent to source."""
+    return os.path.relpath(source, start=target.parent)
+
+
+def symlink_points_to(path: Path, expected: Path) -> bool:
+    """Return whether a symlink points to the expected path without writes."""
+    try:
+        raw_target = os.readlink(path)
+    except OSError:
+        return False
+    target = Path(raw_target)
+    if not target.is_absolute():
+        target = path.parent / target
+    return target.resolve(strict=False) == expected.resolve(strict=False)
+
+
+def _detect_agent(
+    *,
+    name: str,
+    command: str,
+    workspace_dir: str,
+    workspace: Path,
+    path: str | None,
+) -> AgentAvailability:
+    command_path = shutil.which(command, path=path)
+    workspace_dir_exists = (workspace / workspace_dir).is_dir()
+    return AgentAvailability(
+        name=name,
+        command=command,
+        workspace_dir=workspace_dir,
+        available=command_path is not None or workspace_dir_exists,
+        command_path=command_path,
+        workspace_dir_exists=workspace_dir_exists,
+    )

agh-0.1.0/agh/cli/config.py

@@ -0,0 +1,186 @@
+"""Local AGH CLI configuration and login helpers."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import tempfile
+import tomllib
+from typing import Any, NoReturn
+import urllib.error
+import urllib.request
+
+import typer
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Reject redirects so Bearer tokens are never forwarded to another URL."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+_NO_REDIRECT_OPENER = urllib.request.build_opener(_NoRedirectHandler)
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "agh" / "config.toml"
+CONFIG_PATH_ENV = "AGH_CONFIG_FILE"
+
+
+class ConfigError(RuntimeError):
+    """Raised when local CLI configuration cannot be read or written."""
+
+
+class LoginValidationError(RuntimeError):
+    """Raised when remote login validation fails."""
+
+
+@dataclass(frozen=True)
+class AghConfig:
+    """Local AGH connection configuration."""
+
+    instance_url: str
+    email: str
+    token: str
+
+
+def get_config_path() -> Path:
+    """Return the effective config path, allowing tests/users to override it."""
+    override = os.environ.get(CONFIG_PATH_ENV, "").strip()
+    if override:
+        return Path(override).expanduser()
+    return DEFAULT_CONFIG_PATH
+
+
+def normalize_instance_url(url: str) -> str:
+    """Normalize an AGH instance URL for storage and request composition."""
+    normalized = url.strip().rstrip("/")
+    if not normalized:
+        raise ConfigError("Instance URL is required")
+    if not normalized.startswith(("http://", "https://")):
+        raise ConfigError("Instance URL must start with http:// or https://")
+    return normalized
+
+
+def load_config(path: Path | None = None) -> AghConfig:
+    """Load local config from TOML."""
+    config_path = path or get_config_path()
+    try:
+        raw = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ConfigError(
+            f"No AGH config found at {config_path}. Run 'agh login'."
+        ) from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"Invalid AGH config at {config_path}: {exc}") from exc
+
+    try:
+        return AghConfig(
+            instance_url=str(raw["instance_url"]),
+            email=str(raw["email"]),
+            token=str(raw["token"]),
+        )
+    except KeyError as exc:
+        raise ConfigError(f"AGH config missing required field: {exc.args[0]}") from exc
+
+
+def save_config(config: AghConfig, path: Path | None = None) -> None:
+    """Atomically write local config with restrictive permissions where supported."""
+    config_path = path or get_config_path()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    text = _format_config(config)
+
+    fd, temp_name = tempfile.mkstemp(
+        prefix=f".{config_path.name}.", suffix=".tmp", dir=config_path.parent
+    )
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        with suppress(OSError):
+            os.chmod(temp_path, 0o600)
+        os.replace(temp_path, config_path)
+        with suppress(OSError):
+            os.chmod(config_path, 0o600)
+    except Exception:
+        with suppress(FileNotFoundError):
+            temp_path.unlink()
+        raise
+
+
+def validate_login(*, instance_url: str, email: str, token: str) -> dict[str, Any]:
+    """Validate login credentials using GET /api/v1/me."""
+    request = urllib.request.Request(
+        f"{instance_url}/api/v1/me",
+        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
+        method="GET",
+    )
+    try:
+        with _NO_REDIRECT_OPENER.open(request, timeout=10) as response:  # noqa: S310 - user-provided AGH URL
+            status_code = response.status
+            body = response.read()
+    except urllib.error.HTTPError as exc:
+        if 300 <= exc.code < 400:
+            raise LoginValidationError(
+                "Login validation failed: /me redirects are not allowed"
+            ) from exc
+        raise LoginValidationError(
+            f"Login validation failed: /me returned HTTP {exc.code}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        reason = getattr(exc, "reason", exc)
+        raise LoginValidationError(f"Login validation failed: {reason}") from exc
+    except TimeoutError as exc:
+        raise LoginValidationError(f"Login validation failed: {exc}") from exc
+
+    if status_code != 200:
+        raise LoginValidationError(
+            f"Login validation failed: /me returned HTTP {status_code}"
+        )
+
+    try:
+        payload = json.loads(body.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LoginValidationError(
+            "Login validation failed: /me returned invalid JSON"
+        ) from exc
+
+    actual_email = str(payload.get("email", ""))
+    if actual_email.lower() != email.lower():
+        raise LoginValidationError(
+            f"Login validation failed: /me email {actual_email!r} does not match {email!r}"
+        )
+    return payload
+
+
+def mask_token(token: str) -> str:
+    """Return a display-safe token mask."""
+    if len(token) <= 4:
+        return "****"
+    if len(token) <= 8:
+        return f"{token[:2]}****"
+    return f"{token[:4]}****{token[-4:]}"
+
+
+def _format_config(config: AghConfig) -> str:
+    return "".join(
+        [
+            f'instance_url = "{_toml_escape(config.instance_url)}"\n',
+            f'email = "{_toml_escape(config.email)}"\n',
+            f'token = "{_toml_escape(config.token)}"\n',
+        ]
+    )
+
+
+def _toml_escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def fail(message: str, *, code: int = 1) -> NoReturn:
+    """Print an error and exit with a stable non-zero status."""
+    typer.secho(f"Error: {message}", fg=typer.colors.RED, err=False)
+    raise typer.Exit(code)