codexmgr 0.1.0__tar.gz

codexmgr-0.1.0/.github/actions/install_package/action.yml

@@ -0,0 +1,29 @@
+name: install_package
+description: Install a package from local pyproject.toml
+inputs:
+  python_version:
+    description: "Python version to install"
+    default: "3.12"
+
+runs:
+  using: "composite"
+
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      id: setup_python
+      with:
+        python-version: ${{ inputs.python_version }}
+
+    - name: Install UV
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+        echo "python-version=${{ steps.setup_python.outputs.python-version }}" >> "$GITHUB_OUTPUT"
+
+    - name: Install Dependencies
+      shell: bash
+      run: |
+        uv sync --group dev
+        echo "python-version=${{ steps.setup_python.outputs.python-version }}" >> "$GITHUB_OUTPUT"

codexmgr-0.1.0/.github/workflows/py_test.yml

@@ -0,0 +1,36 @@
+# this is an autogenerated file, do not edit it directly or your changes might be lost.
+name: Python Tests
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - dev
+      - test
+  pull_request:
+    branches:
+      - main
+      - master
+      - dev
+      - test
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install Package
+        uses: ./.github/actions/install_package
+        with:
+          python_version: ${{ matrix.python-version }}
+
+      - name: Run Tests
+        run: uv run pytest

codexmgr-0.1.0/.github/workflows/version_publish_main.yml

@@ -0,0 +1,94 @@
+# this is an autogenerated file, do not edit it directly or your changes might be lost.
+name: version_publish
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  version_publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: read
+      id-token: write
+    environment:
+      name: main
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Package
+        uses: ./.github/actions/install_package
+        with:
+          python_version: 3.12
+
+      - name: Run Tests
+        run: uv run pytest
+
+      - name: Get current package version
+        shell: bash
+        id: get_version
+        run: |
+          CURRENT_VERSION=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          echo "CURRENT_VERSION=${CURRENT_VERSION}" >> $GITHUB_ENV
+          echo "CURRENT_VERSION=${CURRENT_VERSION}"
+
+      - name: Get latest version from PyPI
+        shell: bash
+        id: get_pypi_version
+        run: |
+          PACKAGE_NAME=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["name"])')
+          PYPI_JSON=$(curl -fsS "https://pypi.org/pypi/${PACKAGE_NAME}/json" || true)
+          if [ -z "$PYPI_JSON" ]; then
+            LATEST_VERSION=""
+          else
+            LATEST_VERSION=$(jq -r '.info.version // ""' <<< "$PYPI_JSON")
+          fi
+          echo "LATEST_VERSION=${LATEST_VERSION}" >> $GITHUB_ENV
+          echo "LATEST_VERSION=${LATEST_VERSION}"
+
+      - name: Compare versions
+        shell: bash
+        id: compare_versions
+        run: |
+          if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then
+            echo "should_update=true" >> $GITHUB_OUTPUT
+          else
+            echo "should_update=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Package project
+        if: steps.compare_versions.outputs.should_update == 'true'
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        if: steps.compare_versions.outputs.should_update == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+
+      - name: Check if tag exists
+        shell: bash
+        id: check_tag
+        if: steps.compare_versions.outputs.should_update == 'true'
+        run: |
+          TAG_EXISTS=$(git tag -l "v$CURRENT_VERSION")
+          if [ "$TAG_EXISTS" ]; then
+            echo "tag_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "tag_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create new tag
+        shell: bash
+        if: steps.compare_versions.outputs.should_update == 'true' && steps.check_tag.outputs.tag_exists == 'false'
+        run: |
+          git config --local user.name "${GITHUB_ACTOR}"
+          git config --local user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+          git tag -a v$CURRENT_VERSION -m "Release version $CURRENT_VERSION"
+          git push origin v$CURRENT_VERSION

codexmgr-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+AGENTS.md

codexmgr-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,203 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "codexmgr"
+version = "0.1.0"
+description = "Manage project-local Codex configuration from reusable templates"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["codex", "cli", "configuration", "agents", "skills"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+codexmgr = "codexmgr.cli:entrypoint"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codexmgr"]
+
+[dependency-groups]
+dev = [
+    "codexmgr[dev]",
+]
+
+[tool.uv.sources]
+codexmgr = { workspace = true }

codexmgr-0.1.0/pytest.toml

@@ -0,0 +1,3 @@
+[pytest]
+pythonpath = ["src"]
+testpaths = ["tests"]

codexmgr-0.1.0/src/codexmgr/__init__.py

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