codexmgr 0.1.0__py3-none-any.whl

codexmgr/__init__.py

@@ -0,0 +1,5 @@
+"""Project-local Codex setup manager."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

codexmgr/agents_file.py

@@ -0,0 +1,80 @@
+"""Helpers for preserving manual AGENTS.md content around a managed block."""
+
+from pathlib import Path
+
+from .errors import CommandError
+
+BEGIN_MARKER = "<!-- BEGIN CODEXMGR GENERATED -->"
+END_MARKER = "<!-- END CODEXMGR GENERATED -->"
+
+
+def write_managed_agents_md(path: Path, generated_markdown: str) -> None:
+    """Write generated markdown into the CODEXMGR managed block.
+
+    Args:
+        path: Project AGENTS.md path to create or update.
+        generated_markdown: Markdown content to place inside the managed block.
+
+    Returns:
+        None. The file is written with UTF-8 encoding.
+    """
+    current = path.read_text(encoding="utf-8") if path.exists() else ""
+    updated = _replace_block(current, generated_markdown)
+    path.write_text(updated, encoding="utf-8")
+
+
+def _replace_block(current: str, generated_markdown: str) -> str:
+    """Replace or append the generated block in AGENTS.md content.
+
+    Args:
+        current: Existing AGENTS.md content.
+        generated_markdown: Markdown content for the managed block.
+
+    Returns:
+        Updated AGENTS.md content.
+    """
+    begin_count = current.count(BEGIN_MARKER)
+    end_count = current.count(END_MARKER)
+    if begin_count != end_count:
+        raise CommandError("Incomplete CODEXMGR generated block in AGENTS.md")
+    if begin_count > 1:
+        raise CommandError("Multiple CODEXMGR generated blocks in AGENTS.md")
+
+    block = _format_block(generated_markdown)
+    if begin_count == 0:
+        return _append_block(current, block)
+
+    begin_index = current.index(BEGIN_MARKER)
+    end_index = current.index(END_MARKER, begin_index)
+    after_index = end_index + len(END_MARKER)
+    return f"{current[:begin_index]}{block}{current[after_index:]}"
+
+
+def _append_block(current: str, block: str) -> str:
+    """Append a formatted generated block to AGENTS.md content.
+
+    Args:
+        current: Existing AGENTS.md content.
+        block: Fully formatted generated block with markers.
+
+    Returns:
+        AGENTS.md content with the block appended.
+    """
+    if not current:
+        return f"{block}\n"
+    return f"{current.rstrip('\n')}\n\n{block}\n"
+
+
+def _format_block(generated_markdown: str) -> str:
+    """Format generated markdown with CODEXMGR block markers.
+
+    Args:
+        generated_markdown: Markdown body for the managed block.
+
+    Returns:
+        Block text including begin and end markers.
+    """
+    body = generated_markdown.rstrip("\n")
+    if not body:
+        return f"{BEGIN_MARKER}\n{END_MARKER}"
+    return f"{BEGIN_MARKER}\n{body}\n{END_MARKER}"

codexmgr/agentsmd.py

@@ -0,0 +1,96 @@
+"""Manage configured AGENTS.md template sources and rendered output."""
+
+from pathlib import Path
+from typing import Any
+
+from .agents_file import write_managed_agents_md
+from .errors import CommandError
+from .paths import agents_md_path, config_path, resolve_template
+from .project_config import (
+    agents_md_sources,
+    load_required_project_config,
+    require_codex_dir,
+    set_agents_md_sources,
+)
+from .renderer import render_agents_markdown
+from .toml_io import load_optional_toml_file, load_toml_file, write_toml_file
+
+
+def add_agentsmd(reference: str, cwd: Path, codexmgr_home: Path) -> str:
+    """Add an AGENTS.md template reference to project configuration.
+
+    Args:
+        reference: Named template or TOML path to add.
+        cwd: Project directory whose codexmgr.toml should be updated.
+        codexmgr_home: codexmgr home used to validate named template references.
+
+    Returns:
+        The reference that was added or already present.
+    """
+    require_codex_dir(cwd)
+    resolve_template(reference, cwd, codexmgr_home)
+
+    config = load_optional_toml_file(config_path(cwd))
+    sources = agents_md_sources(config)
+    if reference not in sources:
+        sources.append(reference)
+    set_agents_md_sources(config, sources)
+    write_toml_file(config_path(cwd), config)
+    return reference
+
+
+def remove_agentsmd(source_id: str, cwd: Path) -> str:
+    """Remove an AGENTS.md template reference from project configuration.
+
+    Args:
+        source_id: Source identifier or reference to remove.
+        cwd: Project directory whose codexmgr.toml should be updated.
+
+    Returns:
+        The removed source identifier.
+    """
+    config = load_required_project_config(cwd)
+    sources = agents_md_sources(config)
+    if source_id not in sources:
+        raise CommandError(f"Source not found in codexmgr.toml: {source_id}")
+
+    set_agents_md_sources(config, [source for source in sources if source != source_id])
+    write_toml_file(config_path(cwd), config)
+    return source_id
+
+
+def resolve_locked_agents_md(
+    config: dict[str, Any],
+    cwd: Path,
+    codexmgr_home: Path,
+) -> dict[str, Any]:
+    """Resolve configured AGENTS.md sources into lock data.
+
+    Args:
+        config: Parsed .codex/codexmgr.toml content.
+        cwd: Project directory used to resolve path sources.
+        codexmgr_home: codexmgr home used to resolve named sources.
+
+    Returns:
+        Resolved source data keyed by source identifier.
+    """
+    locked_sources: dict[str, Any] = {}
+    for reference in agents_md_sources(config):
+        source_id, template_path = resolve_template(reference, cwd, codexmgr_home)
+        if source_id in locked_sources:
+            raise CommandError(f"Duplicate AGENTS.md source identifier: {source_id}")
+        template_data = load_toml_file(template_path)
+        if not template_data:
+            raise CommandError(f"Template is empty: {template_path}")
+        locked_sources[source_id] = template_data
+    return locked_sources
+
+
+def write_agents_md(cwd: Path, locked_sources: dict[str, Any]) -> None:
+    """Write resolved AGENTS.md lock data to the managed block.
+
+    Args:
+        cwd: Project directory whose root AGENTS.md should be updated.
+        locked_sources: Resolved source data keyed by source identifier.
+    """
+    write_managed_agents_md(agents_md_path(cwd), render_agents_markdown(locked_sources))

codexmgr/cli.py

@@ -0,0 +1,240 @@
+"""Command line parsing and dispatch for codexmgr."""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import TextIO
+
+from .agentsmd import add_agentsmd, remove_agentsmd
+from .codex import run_codex
+from .errors import CommandError
+from .paths import global_codex_dir, global_codexmgr_dir
+from .project import apply_project_config, setup_project
+from .skills import disable_skill, enable_skill
+
+
+def main(
+    argv: list[str] | None = None,
+    *,
+    cwd: Path | None = None,
+    codex_home: Path | None = None,
+    codexmgr_home: Path | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    """Run the codexmgr command line interface.
+
+    Args:
+        argv: Optional argument list without the executable name.
+        cwd: Optional project directory used instead of the current directory.
+        codex_home: Optional Codex home used instead of CODEX_HOME or ~/.codex.
+        codexmgr_home: Optional codexmgr home used instead of CODEXMGR_HOME
+            or ~/.codexmgr.
+        stdout: Optional stream for normal command output.
+        stderr: Optional stream for command errors.
+
+    Returns:
+        A process-style exit code where zero means success.
+    """
+    out = stdout if stdout is not None else sys.stdout
+    err = stderr if stderr is not None else sys.stderr
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    args = _parse_args(raw_argv)
+    project_dir = cwd if cwd is not None else Path.cwd()
+    codex_dir = codex_home if codex_home is not None else global_codex_dir()
+    codexmgr_dir = (
+        codexmgr_home if codexmgr_home is not None else global_codexmgr_dir()
+    )
+
+    try:
+        return _dispatch(args, project_dir, codex_dir, codexmgr_dir, out)
+    except CommandError as exc:
+        err.write(f"{exc}\n")
+        return 1
+
+
+def entrypoint() -> None:
+    """Run the console-script entrypoint.
+
+    Returns:
+        None. The function raises SystemExit with the CLI exit code.
+    """
+    raise SystemExit(main())
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    """Parse raw command line arguments.
+
+    Args:
+        argv: Command line arguments without the executable name.
+
+    Returns:
+        Parsed argparse namespace for dispatch.
+    """
+    if argv[:1] == ["codex"]:
+        return argparse.Namespace(command="codex", codex_args=argv[1:])
+    return _build_parser().parse_args(argv)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the codexmgr argument parser.
+
+    Returns:
+        Configured top-level argparse parser.
+    """
+    parser = argparse.ArgumentParser(prog="codexmgr")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("setup", help="Create a project .codex directory")
+    subparsers.add_parser("apply", help="Apply the project Codex configuration")
+
+    codex = subparsers.add_parser("codex", add_help=False, help="Run codex with project config")
+    codex.add_argument("codex_args", nargs=argparse.REMAINDER)
+
+    agentsmd = subparsers.add_parser("agentsmd", help="Manage AGENTS.md fragments")
+    agentsmd_subparsers = agentsmd.add_subparsers(dest="agentsmd_command", required=True)
+
+    add = agentsmd_subparsers.add_parser("add", help="Add an AGENTS.md template")
+    _add_no_sync_argument(add)
+    add.add_argument("reference", help="Template name or TOML file path")
+
+    remove = agentsmd_subparsers.add_parser("remove", help="Remove an AGENTS.md template")
+    _add_no_sync_argument(remove)
+    remove.add_argument("source_id", help="Template source identifier")
+
+    skill = subparsers.add_parser("skill", help="Manage project skill configuration")
+    skill_subparsers = skill.add_subparsers(dest="skill_command", required=True)
+
+    enable = skill_subparsers.add_parser("enable", help="Enable a skill")
+    _add_no_sync_argument(enable)
+    enable.add_argument("skill", help="Skill name or path")
+
+    disable = skill_subparsers.add_parser("disable", help="Disable a skill")
+    _add_no_sync_argument(disable)
+    disable.add_argument("skill", help="Skill name or path")
+
+    return parser
+
+
+def _add_no_sync_argument(parser: argparse.ArgumentParser) -> None:
+    """Add the shared sync opt-out flag to a mutating command.
+
+    Args:
+        parser: Subcommand parser that updates .codex/codexmgr.toml.
+
+    Returns:
+        None. The parser is mutated in place.
+    """
+    parser.add_argument(
+        "--no-sync",
+        action="store_true",
+        help="Do not run apply after updating codexmgr.toml",
+    )
+
+
+def _dispatch(
+    args: argparse.Namespace,
+    cwd: Path,
+    codex_home: Path,
+    codexmgr_home: Path,
+    stdout: TextIO,
+) -> int:
+    """Run the parsed command.
+
+    Args:
+        args: Parsed command line namespace.
+        cwd: Project directory for project-local operations.
+        codex_home: Global Codex home for resolving named skills.
+        codexmgr_home: codexmgr home for resolving named AGENTS.md templates.
+        stdout: Stream for command output.
+
+    Returns:
+        A process-style exit code where zero means success.
+    """
+    if args.command == "setup":
+        codex_dir = setup_project(cwd)
+        stdout.write(f"Created {codex_dir}\n")
+        return 0
+
+    if args.command == "apply":
+        apply_project_config(cwd, codex_home, codexmgr_home)
+        stdout.write("Applied project Codex configuration\n")
+        return 0
+
+    if args.command == "codex":
+        return run_codex(cwd, args.codex_args)
+
+    if args.command == "agentsmd" and args.agentsmd_command == "add":
+        source_id = add_agentsmd(args.reference, cwd, codexmgr_home)
+        return _finish_config_change(
+            f"Added {source_id}",
+            args.no_sync,
+            cwd,
+            codex_home,
+            codexmgr_home,
+            stdout,
+        )
+
+    if args.command == "agentsmd" and args.agentsmd_command == "remove":
+        source_id = remove_agentsmd(args.source_id, cwd)
+        return _finish_config_change(
+            f"Removed {source_id}",
+            args.no_sync,
+            cwd,
+            codex_home,
+            codexmgr_home,
+            stdout,
+        )
+
+    if args.command == "skill" and args.skill_command == "enable":
+        skill = enable_skill(args.skill, cwd)
+        return _finish_config_change(
+            f"Enabled {skill}",
+            args.no_sync,
+            cwd,
+            codex_home,
+            codexmgr_home,
+            stdout,
+        )
+
+    if args.command == "skill" and args.skill_command == "disable":
+        skill = disable_skill(args.skill, cwd)
+        return _finish_config_change(
+            f"Disabled {skill}",
+            args.no_sync,
+            cwd,
+            codex_home,
+            codexmgr_home,
+            stdout,
+        )
+
+    raise CommandError(f"Unsupported command: {args.command}")
+
+
+def _finish_config_change(
+    message: str,
+    no_sync: bool,
+    cwd: Path,
+    codex_home: Path,
+    codexmgr_home: Path,
+    stdout: TextIO,
+) -> int:
+    """Apply generated files after a project config mutation unless opted out.
+
+    Args:
+        message: Command-specific success message to write after all work succeeds.
+        no_sync: Whether the command should skip the automatic apply step.
+        cwd: Project directory whose configuration changed.
+        codex_home: Global Codex home for resolving named skills during apply.
+        codexmgr_home: codexmgr home for resolving named AGENTS.md templates.
+        stdout: Stream for command output.
+
+    Returns:
+        Zero when the mutation and optional apply step succeed.
+    """
+    messages = [message]
+    if not no_sync:
+        apply_project_config(cwd, codex_home, codexmgr_home)
+        messages.append("Applied project Codex configuration")
+    stdout.write("\n".join(messages) + "\n")
+    return 0

codexmgr/codex.py

@@ -0,0 +1,197 @@
+"""Pass-through wrapper for the external codex command."""
+
+import subprocess
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .errors import CommandError
+from .paths import codex_config_path
+from .toml_io import format_toml_value, load_optional_toml_file
+
+
+def run_codex(cwd: Path, codex_args: list[str]) -> int:
+    """Run the external codex command with project config prepended.
+
+    Args:
+        cwd: Project working directory for the external codex process.
+        codex_args: Arguments to pass through to codex.
+
+    Returns:
+        The external codex process return code.
+    """
+    command = build_codex_command(cwd, codex_args)
+    try:
+        return subprocess.run(command, cwd=cwd).returncode
+    except FileNotFoundError as exc:
+        raise CommandError("codex command not found") from exc
+
+
+def build_codex_command(cwd: Path, codex_args: list[str]) -> list[str]:
+    """Build the external codex command invocation.
+
+    Args:
+        cwd: Project directory whose .codex/config.toml should be read.
+        codex_args: Arguments to pass through to codex.
+
+    Returns:
+        The complete argv for the external codex process.
+    """
+    user_config, passthrough_args = _extract_config_args(codex_args)
+    return ["codex", *_config_overrides(cwd, user_config), *passthrough_args]
+
+
+def _config_overrides(cwd: Path, user_config: list[str]) -> list[str]:
+    """Build Codex ``-c`` arguments from project and user config.
+
+    Args:
+        cwd: Project directory whose .codex/config.toml should be read.
+        user_config: Raw key=value config overrides from the user command.
+
+    Returns:
+        A flat argv fragment containing repeated ``-c`` overrides.
+    """
+    config = _merged_config(cwd, user_config)
+    overrides: list[str] = []
+    for key, value in config.items():
+        overrides.extend(["-c", f"{key}={format_toml_value(value)}"])
+    return overrides
+
+
+def _merged_config(cwd: Path, user_config: list[str]) -> dict[str, Any]:
+    """Merge project Codex config with user-provided overrides.
+
+    Args:
+        cwd: Project directory whose .codex/config.toml should be read.
+        user_config: Raw key=value config overrides from the user command.
+
+    Returns:
+        Flattened Codex config override values keyed by dotted config path.
+    """
+    merged = dict(_iter_overrides(load_optional_toml_file(codex_config_path(cwd))))
+    for raw_config in user_config:
+        key, value = _parse_config_override(raw_config)
+        _merge_config_value(merged, key, value)
+    return merged
+
+
+def _extract_config_args(codex_args: list[str]) -> tuple[list[str], list[str]]:
+    """Split Codex config overrides from pass-through arguments.
+
+    Args:
+        codex_args: Raw arguments intended for the external codex command.
+
+    Returns:
+        The raw config override values and the remaining pass-through args.
+    """
+    config_args: list[str] = []
+    passthrough_args: list[str] = []
+    index = 0
+    while index < len(codex_args):
+        arg = codex_args[index]
+        if arg in {"-c", "--config"}:
+            if index + 1 >= len(codex_args):
+                raise CommandError(f"{arg} requires a key=value argument")
+            config_args.append(codex_args[index + 1])
+            index += 2
+        elif arg.startswith("--config="):
+            config_args.append(arg.removeprefix("--config="))
+            index += 1
+        else:
+            passthrough_args.append(arg)
+            index += 1
+    return config_args, passthrough_args
+
+
+def _parse_config_override(raw_config: str) -> tuple[str, Any]:
+    """Parse a Codex ``key=value`` config override.
+
+    Args:
+        raw_config: Raw override text after ``-c`` or ``--config``.
+
+    Returns:
+        The config key and parsed TOML value.
+    """
+    key, separator, raw_value = raw_config.partition("=")
+    if not separator or not key:
+        raise CommandError(f"Invalid codex config override: {raw_config}")
+    return key, _parse_config_value(raw_value)
+
+
+def _parse_config_value(raw_value: str) -> Any:
+    """Parse a config override value as TOML when possible.
+
+    Args:
+        raw_value: Raw value string from a key=value override.
+
+    Returns:
+        Parsed TOML value, or the raw string when it is not valid TOML.
+    """
+    try:
+        return tomllib.loads(f"value = {raw_value}")["value"]
+    except tomllib.TOMLDecodeError:
+        return raw_value
+
+
+def _merge_config_value(config: dict[str, Any], key: str, value: Any) -> None:
+    """Merge one parsed user override into accumulated config.
+
+    Args:
+        config: Mutable flattened config dictionary.
+        key: Dotted config key to merge.
+        value: Parsed override value.
+    """
+    if isinstance(value, list):
+        existing = config.get(key)
+        config[key] = [*(existing if isinstance(existing, list) else []), *value]
+    else:
+        config[key] = value
+
+
+def _iter_overrides(
+    config: Mapping[str, Any],
+    prefix: tuple[str, ...] = (),
+) -> list[tuple[str, Any]]:
+    """Flatten nested project Codex config into dotted override keys.
+
+    Args:
+        config: Parsed Codex config table to flatten.
+        prefix: Dotted key path accumulated during recursion.
+
+    Returns:
+        Flattened key/value pairs suitable for ``codex -c``.
+    """
+    overrides: list[tuple[str, Any]] = []
+    for key, value in config.items():
+        path = (*prefix, key)
+        if _is_nested_table(value):
+            overrides.extend(_iter_overrides(value, path))
+        else:
+            _validate_override_value(path, value)
+            overrides.append((".".join(path), value))
+    return overrides
+
+
+def _is_nested_table(value: Any) -> bool:
+    """Return whether a config value should recurse as a TOML table.
+
+    Args:
+        value: Parsed TOML value.
+
+    Returns:
+        True when the value is a mapping.
+    """
+    return isinstance(value, Mapping)
+
+
+def _validate_override_value(path: tuple[str, ...], value: Any) -> None:
+    """Validate a flattened project config value before formatting.
+
+    Args:
+        path: Dotted config path represented as path segments.
+        value: Parsed TOML value at that path.
+    """
+    if isinstance(value, list) and any(isinstance(item, Mapping) for item in value):
+        if not all(isinstance(item, Mapping) for item in value):
+            raise CommandError(f".codex/config.toml {'.'.join(path)} must not mix tables and values")

codexmgr/errors.py

@@ -0,0 +1,5 @@
+"""Shared exceptions for command-facing codexmgr failures."""
+
+
+class CommandError(Exception):
+    """Raised when a command cannot complete with the provided inputs."""