codexmgr 0.1.0__tar.gz → 0.1.2__tar.gz

{codexmgr-0.1.0 → codexmgr-0.1.2}/.github/workflows/version_publish_main.yml

@@ -8,7 +8,27 @@ on:
       - master
 
 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
+
   version_publish:
+    needs: test
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -27,9 +47,6 @@ jobs:
         with:
           python_version: 3.12
 
-      - name: Run Tests
-        run: uv run pytest
-
       - name: Get current package version
         shell: bash
         id: get_version

{codexmgr-0.1.0 → codexmgr-0.1.2}/.gitignore

@@ -9,3 +9,7 @@ wheels/
 # Virtual environments
 .venv
 AGENTS.md
+tasks.md
+.thoughts
+.plan
+.agent

{codexmgr-0.1.0 → codexmgr-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexmgr
-Version: 0.1.0
+Version: 0.1.2
 Summary: Manage project-local Codex configuration from reusable templates
 Keywords: agents,cli,codex,configuration,skills
 Classifier: Development Status :: 4 - Beta
@@ -13,8 +13,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: tomlkit>=0.15.0
 Provides-Extra: dev
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # codexmgr
@@ -22,12 +24,14 @@ Description-Content-Type: text/markdown
 `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.
+`.codex/codexmgr.toml` file. It can also keep project-local MCP server
+overrides in sync without editing the user Codex config.
 
 The tool is intentionally narrow:
 
 - compose reusable AGENTS.md instruction fragments
 - enable or disable Codex skills per project
+- enable, disable, inspect, and update safe project-local MCP overrides
 - write reproducible lock data for the resolved project configuration
 - run `codex` with project `.codex/config.toml` values translated into `-c`
   overrides
@@ -91,8 +95,10 @@ This updates `.codex/codexmgr.toml`, runs `apply`, writes
 
 - `.codex/codexmgr.toml`: source configuration edited by CLI commands or by
   hand
-- `.codex/codexmgr.lock`: resolved template and skill state written by `apply`
+- `.codex/codexmgr.lock`: resolved template, skill, and MCP state written by
+  `apply`
 - `.codex/config.toml`: Codex config updated with `[[skills.config]]` entries
+  and `[mcp_servers.<id>]` overrides
 - `AGENTS.md`: project instructions, with only the managed block replaced
 
 The managed AGENTS.md block is:
@@ -107,7 +113,8 @@ Manual content outside this block is preserved. If the block is missing,
 
 ## Project Configuration
 
-`.codex/codexmgr.toml` supports AGENTS.md templates and skill state:
+`.codex/codexmgr.toml` supports AGENTS.md templates, skill state, and MCP
+overrides:
 
 ```toml
 [agents_md]
@@ -116,6 +123,11 @@ src = ["coding", "/absolute/or/project-relative/template.toml"]
 [skills]
 enabled = ["review-helper"]
 disabled = ["experimental-skill", "skills/local-disabled"]
+
+[mcp.servers.browsermcp]
+enabled = true
+bearer_token_env_var = "BROWSERMCP_TOKEN"
+env_vars = ["BROWSER_ENV"]
 ```
 
 Named AGENTS.md templates resolve from `$CODEXMGR_HOME/agentsmd/<name>.toml`.
@@ -163,10 +175,31 @@ keeps template mistakes visible during `apply`.
 ```bash
 codexmgr setup
 codexmgr apply
+codexmgr apply --check
+codexmgr apply --diff
+codexmgr cd [--path | --explorer | --terminal]
+codexmgr doctor
+codexmgr status
+codexmgr agentsmd list
+codexmgr agentsmd show <name-or-template-path>
+codexmgr agentsmd validate <name-or-template-path>
 codexmgr agentsmd add [--no-sync] <name-or-template-path>
 codexmgr agentsmd remove [--no-sync] <name-or-template-path>
+codexmgr init-template agentsmd <name>
+codexmgr skill list
 codexmgr skill enable [--no-sync] <name-or-skill-path>
 codexmgr skill disable [--no-sync] <name-or-skill-path>
+codexmgr mcp list
+codexmgr mcp show <server-id>
+codexmgr mcp validate
+codexmgr mcp enable [--no-sync] <server-id>
+codexmgr mcp disable [--no-sync] <server-id>
+codexmgr mcp set-token-env [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp add-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp remove-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp set-env-header [--no-sync] <server-id> <HEADER> <ENV_VAR>
+codexmgr mcp unset-env-header [--no-sync] <server-id> <HEADER>
+codexmgr mcp set-field [--no-sync] <server-id> <field> <toml-value>
 codexmgr codex <args...>
 ```
 
@@ -174,8 +207,91 @@ codexmgr codex <args...>
 
 `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.
+`[skills]` table is configured, writes local `[mcp_servers.<id>]` overrides when
+`[mcp]` is configured, and refreshes the generated `AGENTS.md` block when
+`[agents_md]` is configured.
+
+`apply --check` exits with a failure if generated files are out of sync without
+writing them. `apply --diff` also avoids writing and prints unified diffs for
+the expected generated-file changes.
+
+`cd` launches a shell in `$CODEXMGR_HOME`. Use
+`codexmgr cd --path` to print only the path, `codexmgr cd --explorer` to open
+the directory in a file explorer, and `codexmgr cd --terminal` to open a new
+terminal there.
+
+`doctor` checks project setup, home environment variables, project TOML syntax,
+referenced snippets, enabled skills, and stale generated files.
+
+`status` prints the resolved homes, configured snippets and skills, and whether
+generated files are in sync.
+
+## Project MCP Overrides
+
+`codexmgr mcp ...` edits only project-local configuration:
+
+- source state is stored in `.codex/codexmgr.toml` under
+  `[mcp.servers.<id>]`
+- `apply` writes generated overrides into `.codex/config.toml` under
+  `[mcp_servers.<id>]`
+- `$CODEX_HOME/config.toml` and `~/.codex/config.toml` are never modified
+
+Mutating MCP commands require a project `.codex/` directory and run `apply`
+automatically unless `--no-sync` is passed. They do not create or remove MCP
+server definitions; use `codex mcp add` or direct Codex config editing for the
+base server setup.
+
+List MCP servers available from Codex and show any project override state:
+
+```bash
+codexmgr mcp list
+codexmgr mcp show context7
+codexmgr mcp validate
+```
+
+`codexmgr mcp list` shells out to `codex mcp list --json` for read-only
+discovery. It does not edit user configuration.
+
+Enable or disable an existing server without deleting its definition:
+
+```bash
+codexmgr mcp disable context7
+codexmgr mcp enable context7
+```
+
+Update token and environment references without storing literal token values:
+
+```bash
+codexmgr mcp set-token-env figma FIGMA_TOKEN
+codexmgr mcp add-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp remove-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp set-env-header figma Authorization FIGMA_AUTH_HEADER
+codexmgr mcp unset-env-header figma Authorization
+```
+
+Set a small allowlist of non-secret fields from TOML literals:
+
+```bash
+codexmgr mcp set-field context7 required true
+codexmgr mcp set-field context7 enabled_tools '["search", "open"]'
+codexmgr mcp set-field context7 default_tools_approval_mode '"prompt"'
+```
+
+Supported `set-field` names are `required`, `startup_timeout_sec`,
+`tool_timeout_sec`, `enabled_tools`, `disabled_tools`, and
+`default_tools_approval_mode`. The direct `enable` and `disable` commands manage
+the `enabled` field.
+
+Literal API token writes are intentionally not part of this command surface;
+prefer environment variable references such as `bearer_token_env_var`,
+`env_vars`, and `env_http_headers`.
+
+`agentsmd list` prints the named templates available under
+`$CODEXMGR_HOME/agentsmd` in sorted order.
+
+`agentsmd show` renders one template as AGENTS.md markdown without changing the
+project configuration. `agentsmd validate` loads and renders a template to catch
+TOML or template-shape errors before adding it.
 
 `agentsmd add` validates that the template exists before writing config.
 Repeated adds keep one source entry.
@@ -183,6 +299,12 @@ Repeated adds keep one source entry.
 `agentsmd remove` removes a configured template source and fails if the source
 is not present.
 
+`init-template agentsmd` creates a starter template under
+`$CODEXMGR_HOME/agentsmd` and refuses to overwrite an existing template.
+
+`skill list` prints available `$CODEX_HOME/skills/*/SKILL.md` entries and marks
+configured skills as enabled, disabled, or missing.
+
 `skill enable` and `skill disable` keep enabled and disabled lists mutually
 exclusive. Repeated commands keep one entry.
 
@@ -212,8 +334,8 @@ 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.
+template rendering, TOML writing, skill resolution, generated-file sync checks,
+Codex command generation, home-directory resolution, and package metadata.
 
 ## Release Notes
 

{codexmgr-0.1.0 → codexmgr-0.1.2}/README.md

@@ -3,12 +3,14 @@
 `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.
+`.codex/codexmgr.toml` file. It can also keep project-local MCP server
+overrides in sync without editing the user Codex config.
 
 The tool is intentionally narrow:
 
 - compose reusable AGENTS.md instruction fragments
 - enable or disable Codex skills per project
+- enable, disable, inspect, and update safe project-local MCP overrides
 - write reproducible lock data for the resolved project configuration
 - run `codex` with project `.codex/config.toml` values translated into `-c`
   overrides
@@ -72,8 +74,10 @@ This updates `.codex/codexmgr.toml`, runs `apply`, writes
 
 - `.codex/codexmgr.toml`: source configuration edited by CLI commands or by
   hand
-- `.codex/codexmgr.lock`: resolved template and skill state written by `apply`
+- `.codex/codexmgr.lock`: resolved template, skill, and MCP state written by
+  `apply`
 - `.codex/config.toml`: Codex config updated with `[[skills.config]]` entries
+  and `[mcp_servers.<id>]` overrides
 - `AGENTS.md`: project instructions, with only the managed block replaced
 
 The managed AGENTS.md block is:
@@ -88,7 +92,8 @@ Manual content outside this block is preserved. If the block is missing,
 
 ## Project Configuration
 
-`.codex/codexmgr.toml` supports AGENTS.md templates and skill state:
+`.codex/codexmgr.toml` supports AGENTS.md templates, skill state, and MCP
+overrides:
 
 ```toml
 [agents_md]
@@ -97,6 +102,11 @@ src = ["coding", "/absolute/or/project-relative/template.toml"]
 [skills]
 enabled = ["review-helper"]
 disabled = ["experimental-skill", "skills/local-disabled"]
+
+[mcp.servers.browsermcp]
+enabled = true
+bearer_token_env_var = "BROWSERMCP_TOKEN"
+env_vars = ["BROWSER_ENV"]
 ```
 
 Named AGENTS.md templates resolve from `$CODEXMGR_HOME/agentsmd/<name>.toml`.
@@ -144,10 +154,31 @@ keeps template mistakes visible during `apply`.
 ```bash
 codexmgr setup
 codexmgr apply
+codexmgr apply --check
+codexmgr apply --diff
+codexmgr cd [--path | --explorer | --terminal]
+codexmgr doctor
+codexmgr status
+codexmgr agentsmd list
+codexmgr agentsmd show <name-or-template-path>
+codexmgr agentsmd validate <name-or-template-path>
 codexmgr agentsmd add [--no-sync] <name-or-template-path>
 codexmgr agentsmd remove [--no-sync] <name-or-template-path>
+codexmgr init-template agentsmd <name>
+codexmgr skill list
 codexmgr skill enable [--no-sync] <name-or-skill-path>
 codexmgr skill disable [--no-sync] <name-or-skill-path>
+codexmgr mcp list
+codexmgr mcp show <server-id>
+codexmgr mcp validate
+codexmgr mcp enable [--no-sync] <server-id>
+codexmgr mcp disable [--no-sync] <server-id>
+codexmgr mcp set-token-env [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp add-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp remove-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp set-env-header [--no-sync] <server-id> <HEADER> <ENV_VAR>
+codexmgr mcp unset-env-header [--no-sync] <server-id> <HEADER>
+codexmgr mcp set-field [--no-sync] <server-id> <field> <toml-value>
 codexmgr codex <args...>
 ```
 
@@ -155,8 +186,91 @@ codexmgr codex <args...>
 
 `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.
+`[skills]` table is configured, writes local `[mcp_servers.<id>]` overrides when
+`[mcp]` is configured, and refreshes the generated `AGENTS.md` block when
+`[agents_md]` is configured.
+
+`apply --check` exits with a failure if generated files are out of sync without
+writing them. `apply --diff` also avoids writing and prints unified diffs for
+the expected generated-file changes.
+
+`cd` launches a shell in `$CODEXMGR_HOME`. Use
+`codexmgr cd --path` to print only the path, `codexmgr cd --explorer` to open
+the directory in a file explorer, and `codexmgr cd --terminal` to open a new
+terminal there.
+
+`doctor` checks project setup, home environment variables, project TOML syntax,
+referenced snippets, enabled skills, and stale generated files.
+
+`status` prints the resolved homes, configured snippets and skills, and whether
+generated files are in sync.
+
+## Project MCP Overrides
+
+`codexmgr mcp ...` edits only project-local configuration:
+
+- source state is stored in `.codex/codexmgr.toml` under
+  `[mcp.servers.<id>]`
+- `apply` writes generated overrides into `.codex/config.toml` under
+  `[mcp_servers.<id>]`
+- `$CODEX_HOME/config.toml` and `~/.codex/config.toml` are never modified
+
+Mutating MCP commands require a project `.codex/` directory and run `apply`
+automatically unless `--no-sync` is passed. They do not create or remove MCP
+server definitions; use `codex mcp add` or direct Codex config editing for the
+base server setup.
+
+List MCP servers available from Codex and show any project override state:
+
+```bash
+codexmgr mcp list
+codexmgr mcp show context7
+codexmgr mcp validate
+```
+
+`codexmgr mcp list` shells out to `codex mcp list --json` for read-only
+discovery. It does not edit user configuration.
+
+Enable or disable an existing server without deleting its definition:
+
+```bash
+codexmgr mcp disable context7
+codexmgr mcp enable context7
+```
+
+Update token and environment references without storing literal token values:
+
+```bash
+codexmgr mcp set-token-env figma FIGMA_TOKEN
+codexmgr mcp add-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp remove-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp set-env-header figma Authorization FIGMA_AUTH_HEADER
+codexmgr mcp unset-env-header figma Authorization
+```
+
+Set a small allowlist of non-secret fields from TOML literals:
+
+```bash
+codexmgr mcp set-field context7 required true
+codexmgr mcp set-field context7 enabled_tools '["search", "open"]'
+codexmgr mcp set-field context7 default_tools_approval_mode '"prompt"'
+```
+
+Supported `set-field` names are `required`, `startup_timeout_sec`,
+`tool_timeout_sec`, `enabled_tools`, `disabled_tools`, and
+`default_tools_approval_mode`. The direct `enable` and `disable` commands manage
+the `enabled` field.
+
+Literal API token writes are intentionally not part of this command surface;
+prefer environment variable references such as `bearer_token_env_var`,
+`env_vars`, and `env_http_headers`.
+
+`agentsmd list` prints the named templates available under
+`$CODEXMGR_HOME/agentsmd` in sorted order.
+
+`agentsmd show` renders one template as AGENTS.md markdown without changing the
+project configuration. `agentsmd validate` loads and renders a template to catch
+TOML or template-shape errors before adding it.
 
 `agentsmd add` validates that the template exists before writing config.
 Repeated adds keep one source entry.
@@ -164,6 +278,12 @@ Repeated adds keep one source entry.
 `agentsmd remove` removes a configured template source and fails if the source
 is not present.
 
+`init-template agentsmd` creates a starter template under
+`$CODEXMGR_HOME/agentsmd` and refuses to overwrite an existing template.
+
+`skill list` prints available `$CODEX_HOME/skills/*/SKILL.md` entries and marks
+configured skills as enabled, disabled, or missing.
+
 `skill enable` and `skill disable` keep enabled and disabled lists mutually
 exclusive. Repeated commands keep one entry.
 
@@ -193,8 +313,8 @@ 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.
+template rendering, TOML writing, skill resolution, generated-file sync checks,
+Codex command generation, home-directory resolution, and package metadata.
 
 ## Release Notes
 

{codexmgr-0.1.0 → codexmgr-0.1.2}/pyproject.toml

@@ -1,10 +1,12 @@
 [project]
 name = "codexmgr"
-version = "0.1.0"
+version = "0.1.2"
 description = "Manage project-local Codex configuration from reusable templates"
 readme = "README.md"
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+    "tomlkit>=0.15.0",
+]
 keywords = ["codex", "cli", "configuration", "agents", "skills"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -24,6 +26,7 @@ codexmgr = "codexmgr.cli:entrypoint"
 [project.optional-dependencies]
 dev = [
     "pytest>=9.0.3",
+    "pyyaml>=6.0.3",
 ]
 
 [build-system]

{codexmgr-0.1.0 → codexmgr-0.1.2}/src/codexmgr/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{codexmgr-0.1.0 → codexmgr-0.1.2}/src/codexmgr/agents_file.py

@@ -19,10 +19,24 @@ def write_managed_agents_md(path: Path, generated_markdown: str) -> None:
         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)
+    updated = render_managed_agents_md(current, generated_markdown)
     path.write_text(updated, encoding="utf-8")
 
 
+def render_managed_agents_md(current: str, generated_markdown: str) -> str:
+    """Render AGENTS.md content with an updated managed block.
+
+    Args:
+        current: Existing AGENTS.md content, or an empty string for a new file.
+        generated_markdown: Markdown content for the managed block.
+
+    Returns:
+        Full AGENTS.md content with the codexmgr managed block replaced or
+        appended.
+    """
+    return _replace_block(current, generated_markdown)
+
+
 def _replace_block(current: str, generated_markdown: str) -> str:
     """Replace or append the generated block in AGENTS.md content.
 
@@ -62,7 +76,8 @@ def _append_block(current: str, block: str) -> str:
     """
     if not current:
         return f"{block}\n"
-    return f"{current.rstrip('\n')}\n\n{block}\n"
+    trimmed = current.rstrip("\n")
+    return f"{trimmed}\n\n{block}\n"
 
 
 def _format_block(generated_markdown: str) -> str: