agent-bootstrap 0.1.0__py3-none-any.whl

bootstrapper/dirtree.py

@@ -0,0 +1,115 @@
+"""Parser for classic `tree`-style directory listings.
+
+Handles both Unicode (``├── └── │``) and ASCII (``|-- `-- |``) glyphs,
+plus plain indentation-only layouts.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Each prefix element is the 4-char column block preceding a depth level.
+_UNICODE_PREFIXES = ("    ", "│   ")
+_ASCII_PREFIXES = ("    ", "|   ")
+
+
+def _strip_connector(stripped: str) -> tuple[str, bool]:
+    """Return (name, is_dir) after removing a tree connector, if present."""
+    for c in ("├── ", "└── ", "|-- ", "`-- "):
+        if stripped.startswith(c):
+            body = stripped[len(c) :]
+            return body.rstrip(), body.endswith("/")
+    return stripped.rstrip(), stripped.endswith("/")
+
+
+def parse_dirtree(text: str) -> dict:
+    """Parse a dirtree listing into a nested ``{name: children}`` dict.
+
+    A directory's children live under its key; files map to ``None``.
+    The root entry (first non-blank line) becomes the outermost dict key.
+    """
+    lines = [ln for ln in text.splitlines() if ln.strip()]
+    if not lines:
+        return {}
+
+    root_raw, root_is_dir = _strip_connector(lines[0].strip())
+    root_name = root_raw.rstrip("/")
+    if not root_is_dir and "." in root_name:
+        # Single-file "tree" output: root itself is a file.
+        return {root_name: None}
+
+    root_children: dict = {}
+    root: dict = {root_name: root_children}
+    # stack[k] is the children dict for entries at depth k; stack[0] = root's.
+    stack: list[dict] = [root_children]
+
+    for line in lines[1:]:
+        prefixes, name_part = _split_prefix(line)
+        level = len(prefixes)
+        name, is_dir = _strip_connector(name_part.strip())
+        name = name.rstrip("/")
+
+        # Clamp to the deepest known frame, then drop deeper frames so the
+        # parent is the dict at this line's level.
+        level = min(level, len(stack) - 1)
+        del stack[level + 1 :]
+        parent = stack[level]
+
+        if is_dir:
+            child: dict = {}
+            parent[name] = child
+            stack.append(child)
+        else:
+            parent[name] = None
+
+    return root
+
+
+def _split_prefix(line: str) -> tuple[list[str], str]:
+    """Split a body line into fixed-width prefix columns and the remainder."""
+    prefixes: list[str] = []
+    rest = line
+    candidates = _UNICODE_PREFIXES + _ASCII_PREFIXES
+    while len(rest) >= 4 and rest[:4] in candidates:
+        prefixes.append(rest[:4])
+        rest = rest[4:]
+    return prefixes, rest
+
+
+def flatten(tree: dict, prefix: str = "") -> list[str]:
+    """Yield newline-free paths for every file and directory in a parsed tree.
+
+    Directories are suffixed with ``/``; files are not.
+    """
+    out: list[str] = []
+    for name, children in tree.items():
+        path = f"{prefix}{name}"
+        if children is None:
+            out.append(path)
+        else:
+            out.append(f"{path}/")
+            out.extend(flatten(children, f"{path}/"))
+    return out
+
+
+def empty_dirs(entries: list[str]) -> list[str]:
+    """Directories (explicit or implied) that contain no files."""
+    dirs: set[str] = set()
+    files: set[str] = set()
+    for e in entries:
+        if e.endswith("/"):
+            dirs.add(e.rstrip("/"))
+        else:
+            files.add(e)
+            parts = e.split("/")
+            for i in range(1, len(parts)):  # all ancestors are dirs
+                dirs.add("/".join(parts[:i]))
+    return sorted(
+        d
+        for d in dirs
+        if not any(f == d or f.startswith(d + "/") for f in files)
+    )
+
+
+def read_tree_file(path: Path) -> dict:
+    return parse_dirtree(path.read_text())

bootstrapper/github_utils.py

@@ -0,0 +1,68 @@
+"""GitHub token handling and repo/file helpers (PyGithub)."""
+
+from __future__ import annotations
+
+import os
+
+from github import Github
+from github.GithubException import GithubException, UnknownObjectException
+from github.Repository import Repository
+
+
+class RepoExistsError(RuntimeError):
+    """The target repository already exists on the remote."""
+
+    def __init__(self, full_name: str) -> None:
+        super().__init__(full_name)
+        self.full_name = full_name
+
+
+def get_github() -> Github:
+    token = os.getenv("GITHUB_TOKEN")
+    if not token:
+        raise SystemExit("Environment variable GITHUB_TOKEN not set.")
+    return Github(token)
+
+
+def get_owner(gh: Github, org: str | None):
+    return gh.get_organization(org) if org else gh.get_user()
+
+
+def create_repo(owner, name: str, description: str, private: bool, *, force: bool = False) -> Repository:
+    """Return the remote repo, creating it if missing.
+
+    Refuses to reuse an existing repo unless ``force`` is set, so a push never
+    silently overwrites an unrelated repository's files.
+    """
+    try:
+        existing = owner.get_repo(name)
+    except (UnknownObjectException, ValueError):
+        return owner.create_repo(name=name, description=description, private=private)
+    if not force:
+        raise RepoExistsError(getattr(existing, "full_name", name))
+    return existing
+
+
+def add_file(
+    repo: Repository,
+    path: str,
+    content: str,
+    message: str = "Add file",
+    branch: str | None = None,
+) -> None:
+    """Create a file, or overwrite it if it already exists.
+
+    We try ``create_file`` first: it bootstraps a brand-new repo (no commits, no
+    default branch yet) in one call, which ``get_contents`` cannot do. A 422
+    means the path already exists, so we re-read its blob SHA and update instead.
+    Intermediate directories are created implicitly from the path.
+    """
+    kwargs = {"branch": branch} if branch else {}
+    try:
+        repo.create_file(path, message, content, **kwargs)
+    except GithubException as exc:
+        if exc.status != 422:
+            raise
+        ref = branch or repo.default_branch
+        existing = repo.get_contents(path, ref=ref)
+        repo.update_file(path, message, content, existing.sha, **kwargs)

bootstrapper/presets.py

@@ -0,0 +1,242 @@
+"""Preset management and ~/.config/projboot/ user store loader."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import os
+from pathlib import Path, PurePosixPath
+import tomllib
+
+
+@dataclass(frozen=True)
+class PresetConfig:
+    name: str
+    arch: str = "modular"
+    outputs_dir: str = "outputs"
+    scripts_dir: str = "scripts"
+    prompts_file: str = "PROMPTS.md"
+    agents: list[str] = field(default_factory=list)
+
+
+BUILTIN_PRESETS: dict[str, PresetConfig] = {
+    "default": PresetConfig(
+        name="default",
+        arch="modular",
+        outputs_dir="outputs",
+        scripts_dir="scripts",
+        prompts_file="PROMPTS.md",
+        agents=[],
+    ),
+    "clean-arch": PresetConfig(
+        name="clean-arch",
+        arch="clean-architecture",
+        outputs_dir="artifacts/outputs",
+        scripts_dir="scripts",
+        prompts_file="docs/PROMPTS.md",
+        agents=["claude", "gh-copilot"],
+    ),
+}
+
+DEFAULT_PRESETS_TOML = """\
+# projboot workflow presets
+# Customize folders, architecture style, and default AI agents per preset.
+
+[presets.default]
+arch = "modular"
+outputs_dir = "outputs"
+scripts_dir = "scripts"
+prompts_file = "PROMPTS.md"
+agents = []
+
+[presets.clean-arch]
+arch = "clean-architecture"
+outputs_dir = "artifacts/outputs"
+scripts_dir = "scripts"
+prompts_file = "docs/PROMPTS.md"
+agents = ["claude", "gh-copilot"]
+"""
+
+DEFAULT_REMEMBER_FILES: dict[str, str] = {
+    "MEMORY.md": (
+        "# Project Memory ($name)\n\n"
+        "Persistent context and facts for AI agents working in `$name`.\n\n"
+        "## Key Conventions\n"
+        "- Architecture: `$arch`\n"
+        "- Generated outputs directory: `$outputs_dir/`\n"
+        "- Helper scripts directory: `$scripts_dir/`\n"
+        "- Ordered prompts file: `$prompts_file`\n"
+    ),
+    "decisions.md": (
+        "# Architectural & Product Decisions ($name)\n\n"
+        "Log key technical decisions chronologically so agents preserve context across sessions.\n\n"
+        "## $year — Initial Bootstrap\n"
+        "- Bootstrapped `$name` with `$arch` architecture.\n"
+    ),
+}
+
+DEFAULT_SKILL_FILES: dict[str, str] = {
+    "project-conventions/SKILL.md": (
+        "---\n"
+        "name: project-conventions\n"
+        "description: Core workspace layout, output directories, and prompt tracking rules for $name.\n"
+        "---\n\n"
+        "# Project Conventions for `$name`\n\n"
+        "1. **Architecture**: Follow the `$arch` architecture pattern.\n"
+        "2. **Outputs**: Write generated artifacts, reports, and exports to `$outputs_dir/`.\n"
+        "3. **Scripts**: Save reusable automation and helper scripts in `$scripts_dir/`.\n"
+        "4. **Prompts**: Keep reusable and ordered prompts documented in `$prompts_file`.\n"
+        "5. **Memory**: Read and update `.remember/MEMORY.md` and `.remember/decisions.md`.\n"
+        "6. **Knowledge Graph**: Use `graphify-out/` and run `graphify update .` after code edits.\n"
+    ),
+}
+
+
+def validate_rel_path(value: str, field: str) -> str:
+    """Ensure a preset path is a safe, repo-relative POSIX path.
+
+    Rejects absolute paths, ``~`` home expansion, and any ``..`` traversal so a
+    custom --outputs-dir/--scripts-dir/--prompts-file cannot escape the project
+    root or overwrite files outside it.
+    """
+    raw = value.strip()
+    if not raw:
+        raise ValueError(f"{field} must not be empty")
+    if "\x00" in raw:
+        raise ValueError(f"{field} contains a null byte")
+    norm = raw.replace("\\", "/")
+    if norm.startswith("/") or norm.startswith("~"):
+        raise ValueError(f"{field} must be relative to the project root: {value!r}")
+    parts = PurePosixPath(norm).parts
+    if ".." in parts:
+        raise ValueError(f"{field} must not contain '..': {value!r}")
+    return norm
+
+
+def get_config_dir() -> Path:
+    env_dir = os.environ.get("PROJBOOT_HOME")
+    if env_dir:
+        return Path(env_dir).expanduser()
+    return Path.home() / ".config" / "projboot"
+
+
+def load_presets(config_dir: Path | None = None) -> dict[str, PresetConfig]:
+    root = config_dir if config_dir is not None else get_config_dir()
+    presets: dict[str, PresetConfig] = dict(BUILTIN_PRESETS)
+
+    toml_path = root / "presets.toml"
+    if not toml_path.is_file():
+        return presets
+
+    data = tomllib.loads(toml_path.read_text())
+    raw_presets = data.get("presets", {})
+    if not isinstance(raw_presets, dict):
+        return presets
+
+    for name, cfg in raw_presets.items():
+        if not isinstance(cfg, dict):
+            continue
+        base = presets.get(name, PresetConfig(name=name))
+        presets[name] = PresetConfig(
+            name=name,
+            arch=str(cfg.get("arch", base.arch)),
+            outputs_dir=str(cfg.get("outputs_dir", base.outputs_dir)),
+            scripts_dir=str(cfg.get("scripts_dir", base.scripts_dir)),
+            prompts_file=str(cfg.get("prompts_file", base.prompts_file)),
+            agents=[str(a) for a in cfg.get("agents", base.agents)],
+        )
+    return presets
+
+
+def resolve_preset(
+    preset_name: str = "default",
+    *,
+    arch: str | None = None,
+    outputs_dir: str | None = None,
+    scripts_dir: str | None = None,
+    prompts_file: str | None = None,
+    agents: list[str] | None = None,
+    config_dir: Path | None = None,
+) -> PresetConfig:
+    presets = load_presets(config_dir)
+    if preset_name not in presets:
+        available = ", ".join(sorted(presets))
+        raise KeyError(f"Unknown preset '{preset_name}'. Available: {available}")
+    base = presets[preset_name]
+
+    merged_agents: list[str] = list(base.agents)
+    for a in agents or []:
+        if a not in merged_agents:
+            merged_agents.append(a)
+
+    return PresetConfig(
+        name=base.name,
+        arch=arch if arch is not None else base.arch,
+        outputs_dir=validate_rel_path(
+            (outputs_dir if outputs_dir is not None else base.outputs_dir).rstrip("/"),
+            "--outputs-dir",
+        ),
+        scripts_dir=validate_rel_path(
+            (scripts_dir if scripts_dir is not None else base.scripts_dir).rstrip("/"),
+            "--scripts-dir",
+        ),
+        prompts_file=validate_rel_path(
+            prompts_file if prompts_file is not None else base.prompts_file,
+            "--prompts-file",
+        ),
+        agents=merged_agents,
+    )
+
+
+def _collect_dir_files(directory: Path) -> dict[str, str]:
+    out: dict[str, str] = {}
+    if not directory.is_dir():
+        return out
+    for path in sorted(directory.rglob("*")):
+        if path.is_file() and not path.name.startswith("."):
+            rel = path.relative_to(directory).as_posix()
+            out[rel] = path.read_text()
+    return out
+
+
+def load_user_store_files(config_dir: Path | None = None) -> dict[str, str]:
+    """Load `.remember/` and `.agents/skills/` templates from user store or built-in defaults."""
+    root = config_dir if config_dir is not None else get_config_dir()
+    files: dict[str, str] = {}
+
+    user_remember = _collect_dir_files(root / "remember")
+    remember_source = user_remember if user_remember else DEFAULT_REMEMBER_FILES
+    for rel, content in remember_source.items():
+        files[f".remember/{rel}"] = content
+
+    user_skills = _collect_dir_files(root / "skills")
+    skills_source = user_skills if user_skills else DEFAULT_SKILL_FILES
+    for rel, content in skills_source.items():
+        files[f".agents/skills/{rel}"] = content
+
+    return files
+
+
+def init_config_dir(config_dir: Path | None = None, *, force: bool = False) -> list[Path]:
+    """Materialize default presets.toml, skills/, and remember/ into the user config dir."""
+    root = config_dir if config_dir is not None else get_config_dir()
+    root.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+
+    targets: list[tuple[Path, str]] = [
+        (root / "presets.toml", DEFAULT_PRESETS_TOML),
+        *[
+            (root / "remember" / rel, body)
+            for rel, body in DEFAULT_REMEMBER_FILES.items()
+        ],
+        *[
+            (root / "skills" / rel, body)
+            for rel, body in DEFAULT_SKILL_FILES.items()
+        ],
+    ]
+    for path, content in targets:
+        if path.exists() and not force:
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content)
+        written.append(path)
+    return written