"""Write AGENTS.md and CLAUDE.md symlink into __generated__/ directories.

These files tell coding agents (Claude Code, Copilot, etc.) that the directory
is machine-managed and its contents should not be edited or deleted.
"""

from __future__ import annotations

import os
from pathlib import Path

_AGENTS_MD = """\
# Auto-Generated Directory — Do Not Edit

This `__generated__/` directory is managed by **Jaunt**, a spec-driven code
generation framework for Python.

**Do NOT manually edit, delete, or move files in this directory.** All contents
are regenerated from spec stubs and any manual changes will be silently
overwritten on the next `jaunt build` or `jaunt test`.

## What are these files?

Each `.py` file here was generated by an LLM from a corresponding *spec stub* —
a Python function or class decorated with `@jaunt.magic` (for implementations)
or `@jaunt.test` (for tests). Jaunt reads the stub's signature and full
docstring contract, and for whole-class specs also tracks the class member
surface, then generates a full implementation.

## How to make changes

Edit the **spec stub** that produced the generated file. Each generated file
contains a header comment identifying its source module:

```
# jaunt:source_module=<module.name>
```

Find and edit that source module, then regenerate:

```bash
jaunt build     # regenerate implementations
jaunt test      # regenerate and run tests
jaunt status    # see which modules need rebuilding, including affected dependents
```
"""


def ensure_agent_docs(generated_dir_path: Path) -> None:
    """Ensure AGENTS.md and a CLAUDE.md symlink exist in *generated_dir_path*.

    Safe to call repeatedly — skips writing if the files already exist.
    """
    if not generated_dir_path.is_dir():
        return

    agents_md = generated_dir_path / "AGENTS.md"
    claude_md = generated_dir_path / "CLAUDE.md"

    if not agents_md.exists():
        agents_md.write_text(_AGENTS_MD, encoding="utf-8")

    # CLAUDE.md → AGENTS.md (relative symlink so it survives moves).
    if not claude_md.exists():
        os.symlink("AGENTS.md", claude_md)
