codexmgr 0.1.0__py3-none-any.whl

codexmgr/toml_io.py

@@ -0,0 +1,213 @@
+"""Small TOML IO helpers for codexmgr-managed configuration files."""
+
+import json
+import re
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .errors import CommandError
+
+BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def load_toml_file(path: Path) -> dict[str, Any]:
+    """Load a TOML file and convert parse failures into CommandError.
+
+    Args:
+        path: TOML file path to read.
+
+    Returns:
+        Parsed TOML document.
+    """
+    try:
+        return tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise CommandError(f"Invalid TOML in {path}: {exc}") from exc
+
+
+def load_optional_toml_file(path: Path) -> dict[str, Any]:
+    """Load a TOML file or return an empty document when it is missing.
+
+    Args:
+        path: Optional TOML file path to read.
+
+    Returns:
+        Parsed TOML document, or an empty dictionary.
+    """
+    if not path.exists():
+        return {}
+    return load_toml_file(path)
+
+
+def write_toml_file(path: Path, data: Mapping[str, Any]) -> None:
+    """Write TOML data with UTF-8 encoding.
+
+    Args:
+        path: TOML file path to write.
+        data: Mapping to serialize.
+
+    Returns:
+        None. The file is replaced atomically by pathlib's write_text behavior.
+    """
+    path.write_text(dump_toml(data), encoding="utf-8")
+
+
+def format_toml_value(value: Any) -> str:
+    """Format a Python value as a TOML literal.
+
+    Args:
+        value: Supported TOML scalar, list, or mapping value.
+
+    Returns:
+        TOML literal string.
+    """
+    return _format_value(value)
+
+
+def dump_toml(data: Mapping[str, Any]) -> str:
+    """Serialize supported TOML data into a deterministic TOML document.
+
+    Args:
+        data: Parsed TOML-style mapping to serialize.
+
+    Returns:
+        TOML document text ending with a newline when non-empty.
+    """
+    tables = list(_iter_tables(data))
+    chunks = [_format_table(path, values, is_array) for is_array, path, values in tables]
+    return "\n\n".join(chunks) + ("\n" if chunks else "")
+
+
+def _iter_tables(
+    data: Mapping[str, Any],
+    prefix: tuple[str, ...] = (),
+) -> list[tuple[bool, tuple[str, ...], dict[str, Any]]]:
+    """Flatten nested TOML tables into renderable table chunks.
+
+    Args:
+        data: Mapping for the current TOML table.
+        prefix: TOML path for the current table.
+
+    Returns:
+        Table chunks as ``(is_array, path, values)`` tuples.
+    """
+    scalars: dict[str, Any] = {}
+    children: list[tuple[str, Mapping[str, Any]]] = []
+    arrays: list[tuple[str, list[Mapping[str, Any]]]] = []
+
+    for key, value in data.items():
+        if _is_array_of_tables(value):
+            arrays.append((key, value))
+        elif isinstance(value, Mapping):
+            children.append((key, value))
+        else:
+            scalars[key] = value
+
+    tables: list[tuple[bool, tuple[str, ...], dict[str, Any]]] = []
+    if scalars:
+        tables.append((False, prefix, scalars))
+
+    for key, child in children:
+        tables.extend(_iter_tables(child, (*prefix, key)))
+
+    for key, items in arrays:
+        tables.extend(_iter_array_tables(items, (*prefix, key)))
+
+    return tables
+
+
+def _iter_array_tables(
+    items: list[Mapping[str, Any]],
+    prefix: tuple[str, ...],
+) -> list[tuple[bool, tuple[str, ...], dict[str, Any]]]:
+    """Flatten TOML array-of-table items into renderable chunks.
+
+    Args:
+        items: Array items that are all mappings.
+        prefix: TOML path for the array-of-table.
+
+    Returns:
+        Array table chunks as ``(True, path, values)`` tuples.
+    """
+    tables: list[tuple[bool, tuple[str, ...], dict[str, Any]]] = []
+    for item in items:
+        for key, value in item.items():
+            if isinstance(value, Mapping):
+                path = ".".join((*prefix, key))
+                raise CommandError(
+                    f"Unsupported nested table in TOML array item: {path}"
+                )
+        scalars = dict(item)
+        tables.append((True, prefix, scalars))
+    return tables
+
+
+def _format_table(path: tuple[str, ...], values: Mapping[str, Any], is_array: bool) -> str:
+    """Format one TOML table chunk.
+
+    Args:
+        path: TOML table path.
+        values: Scalar values to write in the table.
+        is_array: Whether the table is an array-of-tables item.
+
+    Returns:
+        TOML text for the table chunk.
+    """
+    formatted_path = ".".join(_format_key(part) for part in path)
+    lines = []
+    if path:
+        heading = f"[[{formatted_path}]]" if is_array else f"[{formatted_path}]"
+        lines.append(heading)
+    lines.extend(f"{_format_key(key)} = {_format_value(value)}" for key, value in values.items())
+    return "\n".join(lines)
+
+
+def _is_array_of_tables(value: Any) -> bool:
+    """Return whether a value should be emitted as TOML array-of-tables.
+
+    Args:
+        value: Candidate value from a TOML mapping.
+
+    Returns:
+        True when the value is a non-empty list containing only mappings.
+    """
+    return isinstance(value, list) and bool(value) and all(isinstance(item, Mapping) for item in value)
+
+
+def _format_key(key: str) -> str:
+    """Format a TOML key, quoting keys that are not bare-key compatible.
+
+    Args:
+        key: Raw key name.
+
+    Returns:
+        TOML key text.
+    """
+    if BARE_KEY.match(key):
+        return key
+    return json.dumps(key)
+
+
+def _format_value(value: Any) -> str:
+    """Format a supported Python value as TOML.
+
+    Args:
+        value: Value to serialize.
+
+    Returns:
+        TOML literal or inline table text.
+    """
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, list):
+        return f"[{', '.join(_format_value(item) for item in value)}]"
+    if isinstance(value, Mapping):
+        items = (f"{_format_key(key)}={_format_value(item)}" for key, item in value.items())
+        return f"{{{', '.join(items)}}}"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return str(value)
+    raise CommandError(f"Unsupported TOML value type: {type(value).__name__}")

codexmgr-0.1.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: codexmgr
+Version: 0.1.0
+Summary: Manage project-local Codex configuration from reusable templates
+Keywords: agents,cli,codex,configuration,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# codexmgr
+
+`codexmgr` manages project-local Codex configuration from reusable templates.
+It keeps hand-written project instructions in `AGENTS.md` and generated Codex
+configuration in `.codex/` synchronized from a small declarative
+`.codex/codexmgr.toml` file.
+
+The tool is intentionally narrow:
+
+- compose reusable AGENTS.md instruction fragments
+- enable or disable Codex skills per project
+- write reproducible lock data for the resolved project configuration
+- run `codex` with project `.codex/config.toml` values translated into `-c`
+  overrides
+
+## Requirements
+
+- Python 3.11 or newer
+- `uv` for local development
+- `codex` on `PATH` only when using `codexmgr codex ...`
+
+## Installation
+
+From a checkout:
+
+```bash
+uv sync --group dev
+uv run codexmgr --help
+```
+
+For local command-line use from this repository:
+
+```bash
+uv tool install .
+```
+
+## Quick Start
+
+Create the project `.codex/` directory:
+
+```bash
+codexmgr setup
+```
+
+Create or install a named AGENTS.md template under
+`$CODEXMGR_HOME/agentsmd/<name>.toml`. If `CODEXMGR_HOME` is unset,
+`~/.codexmgr` is used.
+
+```toml
+[coding]
+text = """
+- Keep source files focused and small.
+- Add tests for behavior changes before implementation.
+"""
+
+[coding.debugging]
+text = "Prefer lasting regression tests over temporary scripts."
+```
+
+Add the template to the current project:
+
+```bash
+codexmgr agentsmd add coding
+```
+
+This updates `.codex/codexmgr.toml`, runs `apply`, writes
+`.codex/codexmgr.lock`, and refreshes the managed block in `AGENTS.md`.
+
+## Managed Files
+
+`codexmgr` reads and writes these project files:
+
+- `.codex/codexmgr.toml`: source configuration edited by CLI commands or by
+  hand
+- `.codex/codexmgr.lock`: resolved template and skill state written by `apply`
+- `.codex/config.toml`: Codex config updated with `[[skills.config]]` entries
+- `AGENTS.md`: project instructions, with only the managed block replaced
+
+The managed AGENTS.md block is:
+
+```markdown
+<!-- BEGIN CODEXMGR GENERATED -->
+<!-- END CODEXMGR GENERATED -->
+```
+
+Manual content outside this block is preserved. If the block is missing,
+`codexmgr` appends it. If `AGENTS.md` is missing, `codexmgr` creates it.
+
+## Project Configuration
+
+`.codex/codexmgr.toml` supports AGENTS.md templates and skill state:
+
+```toml
+[agents_md]
+src = ["coding", "/absolute/or/project-relative/template.toml"]
+
+[skills]
+enabled = ["review-helper"]
+disabled = ["experimental-skill", "skills/local-disabled"]
+```
+
+Named AGENTS.md templates resolve from `$CODEXMGR_HOME/agentsmd/<name>.toml`.
+Path-like template values resolve relative to the project unless they are
+absolute paths.
+
+Named skills resolve from `$CODEX_HOME/skills/<name>/SKILL.md`. If `CODEX_HOME`
+is unset, `~/.codex` is used. Path-like skill values resolve to either a
+`SKILL.md` file or a directory containing `SKILL.md`. Missing skills are written
+as name-based entries so Codex can resolve them later.
+
+Mutating commands run `apply` automatically unless `--no-sync` is passed.
+Project guidelines require `apply` whenever `.codex/codexmgr.toml` changes,
+unless `--no-sync` was explicitly requested.
+
+## Template Format
+
+Template files are TOML documents. Each top-level key must be a table and
+becomes an AGENTS.md heading. A `text` value inside a table becomes the body
+under that heading. Nested tables become nested headings.
+
+```toml
+[coding]
+text = "Top-level guidance."
+
+[coding.tests]
+text = "Test behavior, not implementation details."
+```
+
+renders as:
+
+```markdown
+# coding
+Top-level guidance.
+
+## tests
+Test behavior, not implementation details.
+```
+
+Unsupported scalar entries fail loudly instead of being silently ignored. This
+keeps template mistakes visible during `apply`.
+
+## Commands
+
+```bash
+codexmgr setup
+codexmgr apply
+codexmgr agentsmd add [--no-sync] <name-or-template-path>
+codexmgr agentsmd remove [--no-sync] <name-or-template-path>
+codexmgr skill enable [--no-sync] <name-or-skill-path>
+codexmgr skill disable [--no-sync] <name-or-skill-path>
+codexmgr codex <args...>
+```
+
+`setup` creates `.codex/` in the current project.
+
+`apply` reads `.codex/codexmgr.toml`, resolves configured sources, writes
+`.codex/codexmgr.lock`, updates `.codex/config.toml` skill entries when a
+`[skills]` table is configured, and refreshes the generated `AGENTS.md` block
+when `[agents_md]` is configured.
+
+`agentsmd add` validates that the template exists before writing config.
+Repeated adds keep one source entry.
+
+`agentsmd remove` removes a configured template source and fails if the source
+is not present.
+
+`skill enable` and `skill disable` keep enabled and disabled lists mutually
+exclusive. Repeated commands keep one entry.
+
+`codex` forwards arguments to the real `codex` command. Values from
+`.codex/config.toml` are flattened into `-c key=value` overrides. User-provided
+`-c` or `--config` overrides are merged after project config: scalar values
+replace earlier values, while list values append.
+
+## Development
+
+Install dependencies:
+
+```bash
+uv sync --group dev
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Build distributions:
+
+```bash
+uv build
+```
+
+The package is typed (`py.typed`) and the test suite covers CLI behavior,
+template rendering, TOML writing, skill resolution, Codex command generation,
+home-directory resolution, and package metadata.
+
+## Release Notes
+
+The GitHub workflow runs the test matrix on Python 3.11, 3.12, and 3.13 across
+Linux, Windows, and macOS. The publish workflow builds and publishes to PyPI
+when the version in `pyproject.toml` differs from the latest published version.

codexmgr-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+codexmgr/__init__.py,sha256=sAP_YLKd-Zt6dty5Rp0ipIcZEBbCrL-PNqdCUqJ-TxA,91
+codexmgr/agents_file.py,sha256=HsRjqYs4QMkgk64J7dBc6sn1QifEup-m_6s3vJbpHNU,2561
+codexmgr/agentsmd.py,sha256=G8_X0H5HB79j-0DyGeW1WgzAM6EZowEI8qBIX-ygWEA,3382
+codexmgr/cli.py,sha256=kRsEYBwbLA74BMM10p0nKU-jS3TGx7S3hH9188hDW6o,7806
+codexmgr/codex.py,sha256=dy837exLosUAcu2_ExGZ9kZ2nfWy7rUGH4_tPDIwjDQ,6441
+codexmgr/errors.py,sha256=9xne9BtVD2pzaMVRgPhJvJRCudIePQqsc13JHspG9Sk,169
+codexmgr/paths.py,sha256=DgDpgdYkce5x8n7X9g6ylcm8yQNFUrpz2Vo8iklqgYM,3380
+codexmgr/project.py,sha256=KdZyQwU_jnnnC4BW1q6TOy4X7_b0YLB8DuPYOkiYB-4,2537
+codexmgr/project_config.py,sha256=JUtvZ00v_kTbWhl5BxxYWHLUVKF75lUHkl_sE5zypIQ,2204
+codexmgr/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+codexmgr/renderer.py,sha256=ocdZsj_jWRqt0QYF-V7ODOYpICNFz5qe9Hofgmx3jTU,4189
+codexmgr/skills.py,sha256=9ssCQJ2JXt5Tci3G2QMnYwWlDstTj3o1LJlfxtN4L24,8911
+codexmgr/toml_io.py,sha256=YyvCGopi5rSkDd6nPp4mmLESwjBENtDxeD7vq7qVTi8,6153
+codexmgr-0.1.0.dist-info/METADATA,sha256=Z6PkPtRwR7WfRkdghZEgrwmskTlhyiO2OiAp5R4ATiA,6219
+codexmgr-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+codexmgr-0.1.0.dist-info/entry_points.txt,sha256=k0bRhfoAzWhclwvkJNKhYXc21amhujQ_EGy5G36j_Wc,53
+codexmgr-0.1.0.dist-info/RECORD,,

codexmgr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

codexmgr-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codexmgr = codexmgr.cli:entrypoint