codexmgr 0.1.0__py3-none-any.whl

codexmgr/paths.py

@@ -0,0 +1,137 @@
+"""Filesystem path helpers for codexmgr project and home directories."""
+
+import os
+from pathlib import Path
+
+from .errors import CommandError
+
+
+def global_codex_dir() -> Path:
+    """Return the Codex home directory.
+
+    Returns:
+        CODEX_HOME when set, otherwise ~/.codex.
+    """
+    return Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+
+
+def global_codexmgr_dir() -> Path:
+    """Return the codexmgr home directory.
+
+    Returns:
+        CODEXMGR_HOME when set, otherwise ~/.codexmgr.
+    """
+    return Path(os.environ.get("CODEXMGR_HOME", Path.home() / ".codexmgr"))
+
+
+def project_codex_dir(cwd: Path) -> Path:
+    """Return the project-local .codex directory path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        The project .codex directory path.
+    """
+    return cwd / ".codex"
+
+
+def config_path(cwd: Path) -> Path:
+    """Return the project codexmgr.toml path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        Path to .codex/codexmgr.toml.
+    """
+    return project_codex_dir(cwd) / "codexmgr.toml"
+
+
+def lock_path(cwd: Path) -> Path:
+    """Return the project codexmgr lockfile path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        Path to .codex/codexmgr.lock.
+    """
+    return project_codex_dir(cwd) / "codexmgr.lock"
+
+
+def codex_config_path(cwd: Path) -> Path:
+    """Return the generated project Codex config path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        Path to .codex/config.toml.
+    """
+    return project_codex_dir(cwd) / "config.toml"
+
+
+def agents_md_path(cwd: Path) -> Path:
+    """Return the project AGENTS.md path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        Path to AGENTS.md in the project root.
+    """
+    return cwd / "AGENTS.md"
+
+
+def resolve_template(reference: str, cwd: Path, codexmgr_home: Path) -> tuple[str, Path]:
+    """Resolve an AGENTS.md template reference to a source id and file path.
+
+    Args:
+        reference: Named template reference or path-like TOML file reference.
+        cwd: Project directory used for relative path references.
+        codexmgr_home: codexmgr home used for named template references.
+
+    Returns:
+        The source identifier and resolved template path.
+    """
+    if _is_named_template(reference):
+        source_id = reference
+        path = codexmgr_home / "agentsmd" / f"{reference}.toml"
+    else:
+        path = _expand_path(reference, cwd)
+        source_id = path.stem
+
+    if not path.is_file():
+        raise CommandError(f"Template not found: {path}")
+
+    return source_id, path
+
+
+def _is_named_template(reference: str) -> bool:
+    """Return whether a template reference should resolve by name.
+
+    Args:
+        reference: Template reference from project configuration or CLI input.
+
+    Returns:
+        True when the reference is a bare template name.
+    """
+    raw = reference.strip()
+    return "/" not in raw and "\\" not in raw and not raw.endswith(".toml")
+
+
+def _expand_path(reference: str, cwd: Path) -> Path:
+    """Expand a path-like template reference.
+
+    Args:
+        reference: Path-like template reference.
+        cwd: Project directory used for relative references.
+
+    Returns:
+        Absolute or project-relative template path.
+    """
+    path = Path(reference).expanduser()
+    if path.is_absolute():
+        return path
+    return cwd / path

codexmgr/project.py

@@ -0,0 +1,74 @@
+"""Project-level codexmgr orchestration commands."""
+
+from pathlib import Path
+from typing import Any
+
+from .agentsmd import resolve_locked_agents_md, write_agents_md
+from .paths import codex_config_path, lock_path, project_codex_dir
+from .project_config import load_required_project_config
+from .skills import build_codex_skill_config, resolve_codex_skill_entries
+from .toml_io import write_toml_file
+
+
+def setup_project(cwd: Path) -> Path:
+    """Create the project .codex directory.
+
+    Args:
+        cwd: Project directory to initialize.
+
+    Returns:
+        The created or existing .codex directory path.
+    """
+    codex_dir = project_codex_dir(cwd)
+    codex_dir.mkdir(parents=True, exist_ok=True)
+    return codex_dir
+
+
+def apply_project_config(cwd: Path, codex_home: Path, codexmgr_home: Path) -> None:
+    """Apply project codexmgr configuration to generated Codex files.
+
+    Args:
+        cwd: Project directory whose .codex/codexmgr.toml should be applied.
+        codex_home: Global Codex home used to resolve named skills.
+        codexmgr_home: codexmgr home used to resolve named AGENTS.md sources.
+    """
+    config = load_required_project_config(cwd)
+    locked_agents_md = resolve_locked_agents_md(config, cwd, codexmgr_home)
+    skill_entries = resolve_codex_skill_entries(config, cwd, codex_home)
+    skills_configured = "skills" in config
+    codex_config = build_codex_skill_config(
+        skill_entries,
+        cwd,
+        include_empty=skills_configured,
+    )
+    lock_data = _lock_data(config, locked_agents_md, skill_entries)
+
+    if lock_data:
+        write_toml_file(lock_path(cwd), lock_data)
+    if "agents_md" in config:
+        write_agents_md(cwd, locked_agents_md)
+    if codex_config is not None:
+        write_toml_file(codex_config_path(cwd), codex_config)
+
+
+def _lock_data(
+    config: dict[str, Any],
+    locked_agents_md: dict[str, Any],
+    skill_entries: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Build lockfile data for configured AGENTS.md sources and skills.
+
+    Args:
+        config: Parsed project codexmgr configuration.
+        locked_agents_md: Resolved AGENTS.md source data.
+        skill_entries: Resolved Codex skill configuration entries.
+
+    Returns:
+        Lockfile data to write, or an empty dictionary when nothing is configured.
+    """
+    lock_data: dict[str, Any] = {}
+    if "agents_md" in config:
+        lock_data["agents_md"] = locked_agents_md
+    if "skills" in config:
+        lock_data["skills"] = {"config": skill_entries}
+    return lock_data

codexmgr/project_config.py

@@ -0,0 +1,70 @@
+"""Helpers for reading and updating project codexmgr configuration."""
+
+from pathlib import Path
+from typing import Any
+
+from .errors import CommandError
+from .paths import config_path, project_codex_dir
+from .toml_io import load_toml_file
+
+
+def require_codex_dir(cwd: Path) -> Path:
+    """Return the project .codex directory or fail if it is missing.
+
+    Args:
+        cwd: Project directory to inspect.
+
+    Returns:
+        The project .codex directory path.
+    """
+    codex_dir = project_codex_dir(cwd)
+    if not codex_dir.is_dir():
+        raise CommandError(f"Project .codex directory not found: {codex_dir}")
+    return codex_dir
+
+
+def load_required_project_config(cwd: Path) -> dict[str, Any]:
+    """Load .codex/codexmgr.toml or fail if it is missing.
+
+    Args:
+        cwd: Project directory whose codexmgr.toml should be loaded.
+
+    Returns:
+        Parsed project configuration.
+    """
+    require_codex_dir(cwd)
+    path = config_path(cwd)
+    if not path.is_file():
+        raise CommandError(f"Project codexmgr.toml not found: {path}")
+    return load_toml_file(path)
+
+
+def agents_md_sources(config: dict[str, Any]) -> list[str]:
+    """Return the configured AGENTS.md sources from project config.
+
+    Args:
+        config: Parsed .codex/codexmgr.toml content.
+
+    Returns:
+        The agents_md.src list.
+    """
+    agents_md = config.get("agents_md", {})
+    if not isinstance(agents_md, dict):
+        raise CommandError("codexmgr.toml [agents_md] must be a table")
+    sources = agents_md.get("src", [])
+    if not isinstance(sources, list) or not all(isinstance(item, str) for item in sources):
+        raise CommandError("codexmgr.toml agents_md.src must be a list of strings")
+    return list(sources)
+
+
+def set_agents_md_sources(config: dict[str, Any], sources: list[str]) -> None:
+    """Set the AGENTS.md source list in project config.
+
+    Args:
+        config: Parsed .codex/codexmgr.toml content to mutate.
+        sources: Source list to write as agents_md.src.
+    """
+    agents_md = config.setdefault("agents_md", {})
+    if not isinstance(agents_md, dict):
+        raise CommandError("codexmgr.toml [agents_md] must be a table")
+    agents_md["src"] = sources

codexmgr/py.typed

@@ -0,0 +1 @@
+

codexmgr/renderer.py

@@ -0,0 +1,131 @@
+"""Render locked AGENTS.md template data into managed markdown."""
+
+from collections import OrderedDict
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import CommandError
+
+
+@dataclass
+class RenderNode:
+    """A merged markdown section from one or more TOML templates.
+
+    Attributes:
+        texts: Ordered text blocks attached to this markdown heading.
+        children: Child headings keyed by their TOML table name.
+    """
+
+    texts: list[str] = field(default_factory=list)
+    children: OrderedDict[str, "RenderNode"] = field(default_factory=OrderedDict)
+
+
+def render_agents_markdown(sources: Mapping[str, Any]) -> str:
+    """Render resolved AGENTS.md template data into markdown.
+
+    Args:
+        sources: Mapping of source identifiers to parsed TOML template tables.
+
+    Returns:
+        Markdown content for the managed AGENTS.md block.
+    """
+    root = RenderNode()
+
+    for source_data in sources.values():
+        if not isinstance(source_data, Mapping):
+            raise CommandError("Source entries must be TOML tables")
+        _merge_source(root, source_data)
+
+    blocks = _render_children(root, 1)
+    return "\n\n".join(blocks) + ("\n" if blocks else "")
+
+
+def _merge_source(parent: RenderNode, source_data: Mapping[str, Any]) -> None:
+    """Merge one parsed template source into the render tree.
+
+    Args:
+        parent: Root render node that receives template sections.
+        source_data: Parsed TOML table for one configured source.
+    """
+    for name, value in source_data.items():
+        if not isinstance(value, Mapping):
+            raise CommandError(f"Template section must be a table: {name}")
+        _merge_table(parent, (name,), value)
+
+
+def _merge_table(root: RenderNode, path: tuple[str, ...], table: Mapping[str, Any]) -> None:
+    """Merge a TOML table into the render tree.
+
+    Args:
+        root: Root render node that receives section data.
+        path: Current TOML path being merged.
+        table: Parsed TOML table at the current path.
+    """
+    node = _node_for_path(root, path)
+    text = table.get("text")
+    if text is not None:
+        if not isinstance(text, str):
+            raise CommandError(f"Text entry must be a string: {'.'.join(path)}")
+        stripped = text.strip("\n")
+        if stripped:
+            node.texts.append(stripped)
+
+    for name, value in table.items():
+        if name == "text":
+            continue
+        if not isinstance(value, Mapping):
+            section = ".".join((*path, name))
+            raise CommandError(f"Unsupported template entry: {section}")
+        _merge_table(root, (*path, name), value)
+
+
+def _node_for_path(root: RenderNode, path: tuple[str, ...]) -> RenderNode:
+    """Return or create the render node for a TOML path.
+
+    Args:
+        root: Root render node to traverse from.
+        path: TOML table path to resolve.
+
+    Returns:
+        The render node for the requested path.
+    """
+    node = root
+    for part in path:
+        if part not in node.children:
+            node.children[part] = RenderNode()
+        node = node.children[part]
+    return node
+
+
+def _render_children(parent: RenderNode, level: int) -> list[str]:
+    """Render all child nodes under a parent.
+
+    Args:
+        parent: Render node whose children should be rendered.
+        level: Markdown heading level to use for direct children.
+
+    Returns:
+        Rendered markdown blocks for all descendants.
+    """
+    blocks: list[str] = []
+    for name, node in parent.children.items():
+        blocks.extend(_render_node(name, node, level))
+    return blocks
+
+
+def _render_node(name: str, node: RenderNode, level: int) -> list[str]:
+    """Render one node and its descendants.
+
+    Args:
+        name: Markdown heading text.
+        node: Render node containing body text and child sections.
+        level: Markdown heading level for this node.
+
+    Returns:
+        Rendered markdown blocks for the node and descendants.
+    """
+    heading = f"{'#' * level} {name}"
+    body = "\n\n".join(node.texts)
+    block = f"{heading}\n{body}" if body else heading
+    return [block, *_render_children(node, level + 1)]

codexmgr/skills.py

@@ -0,0 +1,286 @@
+"""Manage skill enable and disable lists in project configuration."""
+
+from pathlib import Path
+from typing import Any
+
+from .errors import CommandError
+from .paths import codex_config_path, config_path, project_codex_dir
+from .toml_io import load_optional_toml_file, write_toml_file
+
+
+def enable_skill(skill: str, cwd: Path) -> str:
+    """Add a skill to [skills].enabled and remove it from disabled.
+
+    Args:
+        skill: Skill name or path to record in the project configuration.
+        cwd: Project directory whose .codex/codexmgr.toml should be updated.
+
+    Returns:
+        The skill value that was enabled.
+    """
+    return _set_skill_state(skill, cwd, enabled=True)
+
+
+def disable_skill(skill: str, cwd: Path) -> str:
+    """Add a skill to [skills].disabled and remove it from enabled.
+
+    Args:
+        skill: Skill name or path to record in the project configuration.
+        cwd: Project directory whose .codex/codexmgr.toml should be updated.
+
+    Returns:
+        The skill value that was disabled.
+    """
+    return _set_skill_state(skill, cwd, enabled=False)
+
+
+def build_codex_skill_config(
+    entries: list[dict[str, Any]],
+    cwd: Path,
+    *,
+    include_empty: bool = False,
+) -> dict[str, Any] | None:
+    """Build .codex/config.toml content for configured skill states.
+
+    Args:
+        entries: Resolved skills.config entries to write.
+        cwd: Project directory whose .codex/config.toml should be updated.
+        include_empty: Whether to write an empty skills.config list when no
+            skill entries are configured.
+
+    Returns:
+        A parsed .codex/config.toml document with updated skills.config entries,
+        or None when no skills are configured and include_empty is false.
+    """
+    if not entries and not include_empty:
+        return None
+
+    codex_config = load_optional_toml_file(codex_config_path(cwd))
+    skills = codex_config.setdefault("skills", {})
+    if not isinstance(skills, dict):
+        raise CommandError(".codex/config.toml [skills] must be a table")
+    skills["config"] = entries
+    return codex_config
+
+
+def resolve_codex_skill_entries(
+    project_config: dict[str, Any],
+    cwd: Path,
+    codex_home: Path,
+) -> list[dict[str, Any]]:
+    """Resolve configured project skills into Codex skill config entries.
+
+    Args:
+        project_config: Parsed .codex/codexmgr.toml content.
+        cwd: Project directory used to resolve relative skill paths.
+        codex_home: Global Codex home used to resolve named skills.
+
+    Returns:
+        A list of dictionaries suitable for [[skills.config]] entries.
+    """
+    enabled_skills, disabled_skills = _skill_lists(project_config)
+    return [
+        *_skill_config_entries(enabled_skills, cwd, codex_home, enabled=True),
+        *_skill_config_entries(disabled_skills, cwd, codex_home, enabled=False),
+    ]
+
+
+def _set_skill_state(skill: str, cwd: Path, *, enabled: bool) -> str:
+    """Set one skill reference to enabled or disabled in project config.
+
+    Args:
+        skill: Skill name or path to update.
+        cwd: Project directory whose codexmgr.toml should be updated.
+        enabled: Desired skill state.
+
+    Returns:
+        The updated skill reference.
+    """
+    _require_codex_dir(cwd)
+    config = load_optional_toml_file(config_path(cwd))
+    enabled_skills, disabled_skills = _skill_lists(config)
+
+    if enabled:
+        enabled_skills = _append_once(enabled_skills, skill)
+        disabled_skills = _without(disabled_skills, skill)
+    else:
+        disabled_skills = _append_once(disabled_skills, skill)
+        enabled_skills = _without(enabled_skills, skill)
+
+    _set_skill_lists(config, enabled_skills, disabled_skills)
+    write_toml_file(config_path(cwd), config)
+    return skill
+
+
+def _require_codex_dir(cwd: Path) -> Path:
+    """Return the project .codex directory or fail when it is missing.
+
+    Args:
+        cwd: Project directory to inspect.
+
+    Returns:
+        Path to the project .codex directory.
+    """
+    codex_dir = project_codex_dir(cwd)
+    if not codex_dir.is_dir():
+        raise CommandError(f"Project .codex directory not found: {codex_dir}")
+    return codex_dir
+
+
+def _skill_lists(config: dict[str, Any]) -> tuple[list[str], list[str]]:
+    """Read enabled and disabled skill lists from project config.
+
+    Args:
+        config: Parsed project codexmgr configuration.
+
+    Returns:
+        The enabled list and disabled list.
+    """
+    skills = config.get("skills", {})
+    if not isinstance(skills, dict):
+        raise CommandError("codexmgr.toml [skills] must be a table")
+    return _string_list(skills, "enabled"), _string_list(skills, "disabled")
+
+
+def _string_list(table: dict[str, Any], key: str) -> list[str]:
+    """Read a string list from a project config table.
+
+    Args:
+        table: TOML table to inspect.
+        key: List key to read.
+
+    Returns:
+        A shallow copy of the configured string list.
+    """
+    values = table.get(key, [])
+    if not isinstance(values, list) or not all(isinstance(item, str) for item in values):
+        raise CommandError(f"codexmgr.toml skills.{key} must be a list of strings")
+    return list(values)
+
+
+def _set_skill_lists(config: dict[str, Any], enabled: list[str], disabled: list[str]) -> None:
+    """Write enabled and disabled skill lists into project config.
+
+    Args:
+        config: Parsed project codexmgr configuration to mutate.
+        enabled: Skill references to write to skills.enabled.
+        disabled: Skill references to write to skills.disabled.
+    """
+    skills = config.setdefault("skills", {})
+    if not isinstance(skills, dict):
+        raise CommandError("codexmgr.toml [skills] must be a table")
+    skills["enabled"] = enabled
+    skills["disabled"] = disabled
+
+
+def _append_once(values: list[str], value: str) -> list[str]:
+    """Append a value to a list only when it is absent.
+
+    Args:
+        values: Existing values.
+        value: Value to append.
+
+    Returns:
+        A list containing the value once.
+    """
+    if value in values:
+        return values
+    return [*values, value]
+
+
+def _without(values: list[str], value: str) -> list[str]:
+    """Remove all matching values from a list.
+
+    Args:
+        values: Existing values.
+        value: Value to remove.
+
+    Returns:
+        Filtered list.
+    """
+    return [item for item in values if item != value]
+
+
+def _skill_config_entries(
+    skills: list[str],
+    cwd: Path,
+    codex_home: Path,
+    *,
+    enabled: bool,
+) -> list[dict[str, Any]]:
+    """Resolve a list of skill references into Codex config entries.
+
+    Args:
+        skills: Skill names or paths from project config.
+        cwd: Project directory used to resolve relative paths.
+        codex_home: Global Codex home used to resolve named skills.
+        enabled: State to write for each entry.
+
+    Returns:
+        Resolved Codex skills.config entries.
+    """
+    return [
+        _skill_config_entry(skill, cwd, codex_home, enabled=enabled)
+        for skill in skills
+    ]
+
+
+def _skill_config_entry(
+    skill: str,
+    cwd: Path,
+    codex_home: Path,
+    *,
+    enabled: bool,
+) -> dict[str, Any]:
+    """Resolve one skill reference into a Codex config entry.
+
+    Args:
+        skill: Skill name or path from project config.
+        cwd: Project directory used to resolve relative paths.
+        codex_home: Global Codex home used to resolve named skills.
+        enabled: State to write for the entry.
+
+    Returns:
+        A path-based entry when SKILL.md exists, otherwise a name-based entry.
+    """
+    skill_file = _resolve_skill_file(skill, cwd, codex_home)
+    if skill_file is None:
+        return {"name": skill, "enabled": enabled}
+    return {"path": str(skill_file), "enabled": enabled}
+
+
+def _resolve_skill_file(skill: str, cwd: Path, codex_home: Path) -> Path | None:
+    """Resolve a skill name or path to an existing SKILL.md file.
+
+    Args:
+        skill: Skill name or path from project config.
+        cwd: Project directory used to resolve relative paths.
+        codex_home: Global Codex home used to resolve named skills.
+
+    Returns:
+        Absolute SKILL.md path, or None when it cannot be resolved.
+    """
+    if _is_named_skill(skill):
+        skill_file = codex_home / "skills" / skill / "SKILL.md"
+    else:
+        path = Path(skill).expanduser()
+        if not path.is_absolute():
+            path = cwd / path
+        skill_file = path if path.name == "SKILL.md" else path / "SKILL.md"
+
+    if not skill_file.is_file():
+        return None
+    return skill_file.resolve()
+
+
+def _is_named_skill(skill: str) -> bool:
+    """Return whether a skill reference should resolve from CODEX_HOME.
+
+    Args:
+        skill: Skill reference from project configuration or CLI input.
+
+    Returns:
+        True when the reference is a bare skill name.
+    """
+    raw = skill.strip()
+    return "/" not in raw and "\\" not in raw and raw != "SKILL.md"