codexmgr 0.1.1__tar.gz → 0.1.3__tar.gz

{codexmgr-0.1.1 → codexmgr-0.1.3}/.gitignore

@@ -9,3 +9,10 @@ wheels/
 # Virtual environments
 .venv
 AGENTS.md
+tasks.md
+.thoughts
+.brainstorm
+.plan
+.agent
+.rules
+.docs

codexmgr-0.1.3/PKG-INFO

@@ -0,0 +1,457 @@
+Metadata-Version: 2.4
+Name: codexmgr
+Version: 0.1.3
+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
+Requires-Dist: textual>=8.2.7
+Requires-Dist: tomlkit>=0.15.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: pyyaml>=6.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. 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 or disable reusable Codex hook bundles per project
+- enable or disable packaged sets of AGENTS.md, skill, and hook settings
+- enable, disable, inspect, and update safe project-local MCP overrides
+- use an interactive terminal UI for common project management tasks
+- 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, skill, hook, and MCP state written by
+  `apply`
+- `.codex/config.toml`: Codex config updated with `[[skills.config]]` entries
+  and `[mcp_servers.<id>]` overrides
+- `.codex/hooks.json`: Codex hook config updated with enabled reusable hook
+  bundles while preserving unmanaged local hooks
+- `.codex/hooks/<name>`: project-local copies of enabled hook bundle support
+  files
+- `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, skill state, hook state, and MCP
+overrides:
+
+```toml
+[agents_md]
+src = ["coding", "/absolute/or/project-relative/template.toml"]
+
+[skills]
+enabled = ["review-helper"]
+disabled = ["experimental-skill", "skills/local-disabled"]
+
+[hooks]
+enabled = ["repo-rules"]
+disabled = ["experimental-hook"]
+
+[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`.
+Path-like template values resolve relative to the project unless they are
+absolute paths.
+
+Named skills resolve from `$CODEXMGR_HOME/skills/<name>/SKILL.md` or
+`$CODEX_HOME/skills/<name>/SKILL.md`; duplicate names across distinct homes
+fail. Enabled CODEXMGR_HOME skills are copied into `.agents/skills/<name>` on
+every apply by overlaying source files while preserving extra local files.
+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.
+
+Named hooks resolve from `$CODEXMGR_HOME/hooks/<name>/hooks.json`. Enabled hook
+bundles are merged into `.codex/hooks.json` on every apply with
+`codexmanager_meta` added to each managed handler. Existing unmanaged hooks are
+preserved. Bundle files other than the root `hooks.json` are copied into
+`.codex/hooks/<name>`.
+
+Packaged configurations resolve from
+`$CODEXMGR_HOME/packages/<name>/config.toml`. A package config is a TOML
+document that can contain root `agentsmd`, `hooks`, and `skills` string lists
+plus optional profile tables:
+
+```toml
+agentsmd = []
+hooks = ["repo-rules"]
+skills = ["repo-rule-manager"]
+
+[profiles.strict]
+agentsmd = ["strict-coding"]
+hooks = ["strict-rules"]
+skills = ["strict-review"]
+```
+
+`codexmgr package enable <name>` validates package AGENTS.md and hook
+references, then updates `.codex/codexmgr.toml` as if the corresponding
+`agentsmd add`, `hooks enable`, and `skill enable` commands had been run.
+`codexmgr package disable <name>` removes package AGENTS.md entries when
+present and disables the package skills and hooks.
+
+Package profiles are merged with the root package entries:
+
+```bash
+codexmgr package enable repo-rules --profile strict coding --profile python
+```
+
+Direct mutating commands also accept batch targets, for example:
+
+```bash
+codexmgr agentsmd add coding python
+codexmgr skill enable review-helper repo-rule-manager
+codexmgr hooks enable repo-rules audit
+codexmgr mcp enable browsermcp context7
+```
+
+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.
+
+## Interactive TUI
+
+`codexmgr tui` opens a Textual-based terminal UI for managing project-local
+configuration. It shows AGENTS.md templates, skills, hooks, packages, and MCP
+server enable overrides in selectable lists. Changes are staged in memory while
+you navigate and toggle entries. Press `s` to save; the save writes
+`.codex/codexmgr.toml` once and runs `apply` once unless `--no-sync` was used.
+Package profiles appear as separate selectable rows under their package.
+
+```bash
+codexmgr tui
+codexmgr tui --no-sync
+codexmgr tui --show-diff
+```
+
+The dashboard shows generated-file sync state. By default it lists stale
+generated paths; with `--show-diff`, it shows unified diffs for the staged
+configuration. MCP editing in the TUI is intentionally limited to the
+project-local `enabled` override. Advanced MCP fields remain available through
+the classic `codexmgr mcp ...` commands.
+
+## 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 apply --check
+codexmgr apply --diff
+codexmgr cd [--path | --explorer | --terminal]
+codexmgr doctor
+codexmgr status
+codexmgr tui [--no-sync] [--show-diff]
+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 hooks list
+codexmgr hooks enable [--no-sync] <hook-name> [...]
+codexmgr hooks disable [--no-sync] <hook-name> [...]
+codexmgr package list
+codexmgr package enable [--no-sync] <package-name> [...] [--profile <name> [...]]
+codexmgr package disable [--no-sync] <package-name> [...] [--profile <name> [...]]
+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...>
+```
+
+`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, writes `.codex/hooks.json` when `[hooks]` 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, enabled hook bundles, and stale generated
+files.
+
+`status` prints the resolved homes, configured snippets, skills, hooks, and
+whether generated files are in sync.
+
+`codexmgr codex` can run with a just-in-time package/profile overlay without
+changing `.codex/codexmgr.toml`. Put Codex arguments after `--` when using this
+syntax:
+
+```bash
+codexmgr codex repo-rules --profile strict coding --profile python -- exec "review this"
+```
+
+## 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.
+
+`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 `$CODEXMGR_HOME/skills/*/SKILL.md`,
+`$CODEX_HOME/skills/*/SKILL.md`, and local `.agents/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.
+
+`hooks list` prints available `$CODEXMGR_HOME/hooks/*/hooks.json` entries and
+marks configured hook bundles as enabled, disabled, or missing.
+
+`hooks enable` validates that the named hook bundle exists before writing
+config. `hooks enable` and `hooks disable` keep enabled and disabled lists
+mutually exclusive. Repeated commands keep one entry.
+
+`package list` prints available `$CODEXMGR_HOME/packages/*/config.toml`
+entries in sorted order.
+
+`package enable` and `package disable` proxy to existing AGENTS.md, skill, and
+hook project-config mutations. Package state is not tracked separately; the
+resulting `[agents_md]`, `[skills]`, and `[hooks]` tables remain the source of
+truth.
+
+`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, generated-file sync checks,
+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.