codexmgr 0.3.0__tar.gz → 0.4.1__tar.gz

{codexmgr-0.3.0 → codexmgr-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexmgr
-Version: 0.3.0
+Version: 0.4.1
 Summary: Manage project-local Codex configuration from reusable templates
 Project-URL: Repository, https://github.com/JulianKimmig/codexmgr/
 Keywords: agents,cli,codex,configuration,skills
@@ -40,7 +40,7 @@ Use `codexmgr` when a project should:
 - enable packaged Codex setups made from those reusable pieces
 - keep reusable MCP server definitions out of the user-level Codex config
 - check whether generated Codex files match the project config
-- run `codex` with project `.codex/config.toml` values passed as `-c` overrides
+- run `codex` with the project `.codex` directory as its local Codex home
 
 The basic model has three parts:
 
@@ -92,7 +92,8 @@ codexmgr setup
 ```
 
 `setup` creates `.codex/`, creates `.codex/codexmgr.toml` if it is missing, and
-runs `apply`. Existing project config is preserved.
+runs `apply`. Existing project config is preserved. Apply also creates or
+refreshes codexmgr's managed block in `.codex/.gitignore`.
 
 Create a reusable `AGENTS.md` snippet in the manager home. This command creates
 `$CODEXMGR_HOME/agentsmd/coding.toml` and refuses to overwrite an existing file:
@@ -146,6 +147,9 @@ file for you, and you can also edit it by hand when that is clearer.
 
 `apply` resolves the source config and may write or update these managed files:
 
+- `.codex/.gitignore`: preserves manual rules outside its managed block,
+  ignores every unknown `.codex` entry by default, and explicitly exposes the
+  codexmgr-owned files and directories listed below
 - `.codex/codexmgr.lock`: resolved AGENTS.md, agent, skill, hook, rule, and MCP
   state
 - `.codex/config.toml`: project-local Codex config, including generated
@@ -368,6 +372,12 @@ managed project files, and refreshes generated state.
 writing them. `apply --diff` also avoids writing and prints unified diffs for
 the expected generated-file changes.
 
+The `.codex/.gitignore` managed block uses a default-ignore rule rather than a
+list of known runtime filenames. New caches, databases, sessions, and other
+state created by future Codex versions therefore remain outside Git without a
+codexmgr update. Project configuration, custom agents, and hook support files
+remain visible to Git.
+
 `doctor` checks project setup, home environment variables, project TOML syntax,
 referenced snippets, enabled skills, enabled custom agents, enabled hook
 bundles, enabled rules, and stale generated files.
@@ -460,14 +470,28 @@ Codex wrapper command:
 
 ```bash
 codexmgr codex <args...>
-```
-
-`codexmgr codex` applies the current project config, flattens
-`.codex/config.toml` into `-c key=value` overrides, and forwards the remaining
-arguments to the real `codex` command.
-
-User-provided `-c` or `--config` overrides are merged after project config.
-Scalar values replace earlier values, while list values append.
+codexmgr codex --simple <args...>
+```
+
+By default, `codexmgr codex` applies the current project config, launches the
+real `codex` command with `CODEX_HOME` set to
+`<project>/.codex/.runtime`, and forwards Codex arguments unchanged. For a
+trusted project, Codex discovers the tracked `.codex/config.toml` as its
+project configuration independently of `CODEX_HOME`. This keeps generated MCP
+servers and other shared project settings in Git while mutable Codex state is
+written below the ignored `.codex/.runtime` directory. User-provided `-c` and
+`--config` arguments retain their normal Codex behavior.
+
+The wrapper links the global authentication file into
+`.codex/.runtime/auth.json`. It uses `CODEX_GLOBAL_AUTH` when that variable is
+non-empty and otherwise uses `$HOME/.codex/auth.json`. A missing auth source
+produces a warning but does not stop Codex, which can then authenticate within
+the project runtime home.
+
+Use `--simple` immediately after `codex` to run the basic command without
+applying project state, changing the child `CODEX_HOME`, or managing an auth
+link. This launch wrapper is intentionally CLI-only because the TUI does not
+embed or proxy external terminal sessions.
 
 The wrapper can run with a just-in-time package/profile overlay without changing
 `.codex/codexmgr.toml`. Put Codex arguments after `--` when using this syntax:

{codexmgr-0.3.0 → codexmgr-0.4.1}/README.md

@@ -16,7 +16,7 @@ Use `codexmgr` when a project should:
 - enable packaged Codex setups made from those reusable pieces
 - keep reusable MCP server definitions out of the user-level Codex config
 - check whether generated Codex files match the project config
-- run `codex` with project `.codex/config.toml` values passed as `-c` overrides
+- run `codex` with the project `.codex` directory as its local Codex home
 
 The basic model has three parts:
 
@@ -68,7 +68,8 @@ codexmgr setup
 ```
 
 `setup` creates `.codex/`, creates `.codex/codexmgr.toml` if it is missing, and
-runs `apply`. Existing project config is preserved.
+runs `apply`. Existing project config is preserved. Apply also creates or
+refreshes codexmgr's managed block in `.codex/.gitignore`.
 
 Create a reusable `AGENTS.md` snippet in the manager home. This command creates
 `$CODEXMGR_HOME/agentsmd/coding.toml` and refuses to overwrite an existing file:
@@ -122,6 +123,9 @@ file for you, and you can also edit it by hand when that is clearer.
 
 `apply` resolves the source config and may write or update these managed files:
 
+- `.codex/.gitignore`: preserves manual rules outside its managed block,
+  ignores every unknown `.codex` entry by default, and explicitly exposes the
+  codexmgr-owned files and directories listed below
 - `.codex/codexmgr.lock`: resolved AGENTS.md, agent, skill, hook, rule, and MCP
   state
 - `.codex/config.toml`: project-local Codex config, including generated
@@ -344,6 +348,12 @@ managed project files, and refreshes generated state.
 writing them. `apply --diff` also avoids writing and prints unified diffs for
 the expected generated-file changes.
 
+The `.codex/.gitignore` managed block uses a default-ignore rule rather than a
+list of known runtime filenames. New caches, databases, sessions, and other
+state created by future Codex versions therefore remain outside Git without a
+codexmgr update. Project configuration, custom agents, and hook support files
+remain visible to Git.
+
 `doctor` checks project setup, home environment variables, project TOML syntax,
 referenced snippets, enabled skills, enabled custom agents, enabled hook
 bundles, enabled rules, and stale generated files.
@@ -436,14 +446,28 @@ Codex wrapper command:
 
 ```bash
 codexmgr codex <args...>
-```
-
-`codexmgr codex` applies the current project config, flattens
-`.codex/config.toml` into `-c key=value` overrides, and forwards the remaining
-arguments to the real `codex` command.
-
-User-provided `-c` or `--config` overrides are merged after project config.
-Scalar values replace earlier values, while list values append.
+codexmgr codex --simple <args...>
+```
+
+By default, `codexmgr codex` applies the current project config, launches the
+real `codex` command with `CODEX_HOME` set to
+`<project>/.codex/.runtime`, and forwards Codex arguments unchanged. For a
+trusted project, Codex discovers the tracked `.codex/config.toml` as its
+project configuration independently of `CODEX_HOME`. This keeps generated MCP
+servers and other shared project settings in Git while mutable Codex state is
+written below the ignored `.codex/.runtime` directory. User-provided `-c` and
+`--config` arguments retain their normal Codex behavior.
+
+The wrapper links the global authentication file into
+`.codex/.runtime/auth.json`. It uses `CODEX_GLOBAL_AUTH` when that variable is
+non-empty and otherwise uses `$HOME/.codex/auth.json`. A missing auth source
+produces a warning but does not stop Codex, which can then authenticate within
+the project runtime home.
+
+Use `--simple` immediately after `codex` to run the basic command without
+applying project state, changing the child `CODEX_HOME`, or managing an auth
+link. This launch wrapper is intentionally CLI-only because the TUI does not
+embed or proxy external terminal sessions.
 
 The wrapper can run with a just-in-time package/profile overlay without changing
 `.codex/codexmgr.toml`. Put Codex arguments after `--` when using this syntax:

{codexmgr-0.3.0 → codexmgr-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexmgr"
-version = "0.3.0"
+version = "0.4.1"
 description = "Manage project-local Codex configuration from reusable templates"
 readme = "README.md"
 requires-python = ">=3.11"

{codexmgr-0.3.0 → codexmgr-0.4.1}/src/codexmgr/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.0"
+__version__ = "0.4.1"

codexmgr-0.4.1/src/codexmgr/agents/file.py

@@ -0,0 +1,43 @@
+"""Helpers for preserving manual AGENTS.md content around a managed block."""
+
+from pathlib import Path
+
+from ..core.managed_text import render_managed_block
+
+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 = 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 render_managed_block(
+        current,
+        generated_markdown,
+        begin_marker=BEGIN_MARKER,
+        end_marker=END_MARKER,
+        artifact_name="AGENTS.md",
+    )

codexmgr-0.4.1/src/codexmgr/commands/codex.py

@@ -0,0 +1,114 @@
+"""Orchestration and subprocess execution for the external Codex command."""
+
+import subprocess
+from pathlib import Path
+from typing import TextIO
+
+from ..core.errors import CommandError
+from .codex_jit import parse_codex_jit_request, run_with_jit_overlay
+from .codex_launch import (
+    build_project_codex_environment,
+    parse_codex_launch_request,
+)
+
+
+def run_codex_command(
+    cwd: Path,
+    codex_home: Path,
+    codexmgr_home: Path,
+    codex_args: list[str],
+    stderr: TextIO,
+) -> int:
+    """Select a launch mode and run the external Codex executable.
+
+    Args:
+        cwd: Project working directory for the external Codex process.
+        codex_home: Codex home used to resolve project skills.
+        codexmgr_home: codexmgr home containing package sources.
+        codex_args: Raw arguments after ``codexmgr codex``.
+        stderr: Stream that receives launch warnings.
+
+    Returns:
+        The external Codex process return code.
+    """
+    launch_request = parse_codex_launch_request(codex_args)
+    if launch_request.simple:
+        return run_codex(cwd, launch_request.codex_args)
+
+    request = parse_codex_jit_request(launch_request.codex_args)
+
+    def run_project_codex(project_cwd: Path, args: list[str]) -> int:
+        """Launch Codex with the prepared project-local environment.
+
+        Args:
+            project_cwd: Project working directory for the child process.
+            args: Arguments to proxy to the Codex executable.
+
+        Returns:
+            The external Codex process return code.
+        """
+        environment = build_project_codex_environment(project_cwd, stderr)
+        return _run_subprocess(project_cwd, args, environment)
+
+    if request.enabled:
+        return run_with_jit_overlay(
+            request,
+            cwd,
+            codex_home,
+            codexmgr_home,
+            run_project_codex,
+        )
+    from ..project.apply import apply_project_config
+
+    apply_project_config(cwd, codex_home, codexmgr_home)
+    return run_project_codex(cwd, launch_request.codex_args)
+
+
+def run_codex(cwd: Path, codex_args: list[str]) -> int:
+    """Run the basic external Codex command without project modifications.
+
+    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.
+    """
+    return _run_subprocess(cwd, codex_args)
+
+
+def build_codex_command(cwd: Path, codex_args: list[str]) -> list[str]:
+    """Build an argument-preserving external Codex command invocation.
+
+    Args:
+        cwd: Project working directory, retained for the public helper contract.
+        codex_args: Arguments to pass through to codex.
+
+    Returns:
+        The complete argv for the external codex process.
+    """
+    return ["codex", *codex_args]
+
+
+def _run_subprocess(
+    cwd: Path,
+    codex_args: list[str],
+    environment: dict[str, str] | None = None,
+) -> int:
+    """Run Codex and translate executable lookup failures.
+
+    Args:
+        cwd: Working directory for the external Codex process.
+        codex_args: Arguments to pass through to Codex.
+        environment: Optional explicit child process environment.
+
+    Returns:
+        The external Codex process return code.
+    """
+    command = build_codex_command(cwd, codex_args)
+    try:
+        if environment is None:
+            return subprocess.run(command, cwd=cwd).returncode
+        return subprocess.run(command, cwd=cwd, env=environment).returncode
+    except FileNotFoundError as exc:
+        raise CommandError("codex command not found") from exc

codexmgr-0.4.1/src/codexmgr/commands/codex_launch.py

@@ -0,0 +1,102 @@
+"""Launch-mode parsing and project-local Codex environment preparation."""
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO
+
+from ..core.paths import project_codex_dir, project_codex_runtime_dir
+
+
+@dataclass(frozen=True)
+class CodexLaunchRequest:
+    """A parsed request to launch Codex in managed or simple mode.
+
+    Attributes:
+        simple: Whether to bypass all codexmgr project preparation.
+        codex_args: Arguments to proxy to the external Codex executable.
+    """
+
+    simple: bool
+    codex_args: list[str]
+
+
+def parse_codex_launch_request(codex_args: list[str]) -> CodexLaunchRequest:
+    """Parse the optional leading codexmgr ``--simple`` launch flag.
+
+    Args:
+        codex_args: Raw arguments following ``codexmgr codex``.
+
+    Returns:
+        The selected launch mode and external Codex arguments.
+    """
+    if codex_args[:1] == ["--simple"]:
+        return CodexLaunchRequest(simple=True, codex_args=codex_args[1:])
+    return CodexLaunchRequest(simple=False, codex_args=list(codex_args))
+
+
+def build_project_codex_environment(
+    cwd: Path,
+    stderr: TextIO,
+    environ: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Build the child environment for a project-local Codex launch.
+
+    Args:
+        cwd: Project directory whose local Codex home may be selected.
+        stderr: Stream that receives a missing-auth warning.
+        environ: Source process environment, or ``os.environ`` when omitted.
+
+    Returns:
+        A copied child environment. ``CODEX_HOME`` points to
+        ``.codex/.runtime`` when the project ``.codex`` directory contains
+        ``config.toml``.
+    """
+    environment = dict(os.environ if environ is None else environ)
+    config_dir = project_codex_dir(cwd)
+    if not (config_dir / "config.toml").is_file():
+        return environment
+
+    runtime_dir = project_codex_runtime_dir(cwd)
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    environment["CODEX_HOME"] = str(runtime_dir)
+    global_auth = _global_auth_path(environment)
+    if global_auth.is_file():
+        _replace_auth_link(runtime_dir / "auth.json", global_auth)
+    else:
+        stderr.write(
+            "codexmgr codex: warning: no global auth found at "
+            f"{global_auth}; you may need to auth once.\n"
+        )
+    return environment
+
+
+def _global_auth_path(environment: Mapping[str, str]) -> Path:
+    """Resolve the read-only global authentication source.
+
+    Args:
+        environment: Launch environment containing HOME and optional override.
+
+    Returns:
+        ``CODEX_GLOBAL_AUTH`` when non-empty, otherwise HOME's Codex auth path.
+    """
+    configured_auth = environment.get("CODEX_GLOBAL_AUTH")
+    if configured_auth:
+        return Path(configured_auth)
+    return Path(environment["HOME"]) / ".codex" / "auth.json"
+
+
+def _replace_auth_link(auth_link: Path, global_auth: Path) -> None:
+    """Replace the project auth entry with a link to global authentication.
+
+    Args:
+        auth_link: Project-local ``.codex/.runtime/auth.json`` link path.
+        global_auth: Existing global authentication source file.
+
+    Returns:
+        None. Any existing file or symbolic link at ``auth_link`` is replaced.
+    """
+    if auth_link.exists() or auth_link.is_symlink():
+        auth_link.unlink()
+    auth_link.symlink_to(global_auth)

codexmgr-0.4.1/src/codexmgr/core/managed_text.py

@@ -0,0 +1,78 @@
+"""Reusable rendering for marker-delimited codexmgr-managed text blocks."""
+
+from ..core.errors import CommandError
+
+
+def render_managed_block(
+    current: str,
+    generated: str,
+    *,
+    begin_marker: str,
+    end_marker: str,
+    artifact_name: str,
+) -> str:
+    """Replace or append one marker-delimited generated text block.
+
+    Args:
+        current: Existing artifact content, or an empty string when missing.
+        generated: Generated content to place between the markers.
+        begin_marker: Exact line marking the beginning of managed content.
+        end_marker: Exact line marking the end of managed content.
+        artifact_name: Human-readable artifact name for validation errors.
+
+    Returns:
+        Full artifact content with one current codexmgr-managed block.
+
+    Raises:
+        CommandError: If existing managed-block markers are malformed.
+    """
+    begin_count = current.count(begin_marker)
+    end_count = current.count(end_marker)
+    if begin_count != end_count:
+        raise CommandError(
+            f"Incomplete CODEXMGR generated block in {artifact_name}"
+        )
+    if begin_count > 1:
+        raise CommandError(f"Multiple CODEXMGR generated blocks in {artifact_name}")
+
+    block = _format_block(generated, begin_marker, end_marker)
+    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 managed block to existing content.
+
+    Args:
+        current: Existing artifact content.
+        block: Fully formatted block including both markers.
+
+    Returns:
+        Content ending in the appended managed block and a newline.
+    """
+    if not current:
+        return f"{block}\n"
+    trimmed = current.rstrip("\n")
+    return f"{trimmed}\n\n{block}\n"
+
+
+def _format_block(generated: str, begin_marker: str, end_marker: str) -> str:
+    """Wrap generated content in its managed-block markers.
+
+    Args:
+        generated: Generated text to normalize and wrap.
+        begin_marker: Beginning marker line.
+        end_marker: Ending marker line.
+
+    Returns:
+        Marker-delimited content without a trailing newline.
+    """
+    body = generated.rstrip("\n")
+    if not body:
+        return f"{begin_marker}\n{end_marker}"
+    return f"{begin_marker}\n{body}\n{end_marker}"

{codexmgr-0.3.0 → codexmgr-0.4.1}/src/codexmgr/core/paths.py

@@ -36,6 +36,18 @@ def project_codex_dir(cwd: Path) -> Path:
     return cwd / ".codex"
 
 
+def project_codex_runtime_dir(cwd: Path) -> Path:
+    """Return the project-local Codex runtime-home path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        The ignored ``.codex/.runtime`` directory used as ``CODEX_HOME``.
+    """
+    return project_codex_dir(cwd) / ".runtime"
+
+
 def config_path(cwd: Path) -> Path:
     """Return the project codexmgr.toml path.
 
@@ -72,6 +84,18 @@ def codex_config_path(cwd: Path) -> Path:
     return project_codex_dir(cwd) / "config.toml"
 
 
+def codex_gitignore_path(cwd: Path) -> Path:
+    """Return the managed project Codex ignore-file path.
+
+    Args:
+        cwd: Project directory.
+
+    Returns:
+        Path to .codex/.gitignore.
+    """
+    return project_codex_dir(cwd) / ".gitignore"
+
+
 def agents_md_path(cwd: Path) -> Path:
     """Return the project AGENTS.md path.
 

{codexmgr-0.3.0 → codexmgr-0.4.1}/src/codexmgr/interface/cli.py

@@ -65,7 +65,7 @@ def main(
     )
 
     try:
-        return _dispatch(args, project_dir, codex_dir, codexmgr_dir, out)
+        return _dispatch(args, project_dir, codex_dir, codexmgr_dir, out, err)
     except CommandError as exc:
         err.write(f"{exc}\n")
         return 1
@@ -100,6 +100,7 @@ def _dispatch(
     codex_home: Path,
     codexmgr_home: Path,
     stdout: TextIO,
+    stderr: TextIO,
 ) -> int:
     """Run the parsed command.
 
@@ -109,6 +110,7 @@ def _dispatch(
         codex_home: Global Codex home for resolving named skills.
         codexmgr_home: codexmgr home for resolving named AGENTS.md templates.
         stdout: Stream for command output.
+        stderr: Stream for command warnings.
 
     Returns:
         A process-style exit code where zero means success.
@@ -136,7 +138,13 @@ def _dispatch(
         return run_codexmgr_home_action(codexmgr_home, args.cd_action, stdout)
 
     if args.command == "codex":
-        return run_codex_command(cwd, codex_home, codexmgr_home, args.codex_args)
+        return run_codex_command(
+            cwd,
+            codex_home,
+            codexmgr_home,
+            args.codex_args,
+            stderr,
+        )
 
     if args.command == "agentsmd" and args.agentsmd_command == "list":
         options = list_agentsmd_options(codexmgr_home)

{codexmgr-0.3.0 → codexmgr-0.4.1}/src/codexmgr/project/generated.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import Any
 
+from .gitignore import build_project_gitignore_file
 from .state import GeneratedFile
 from ..agents.file import render_managed_agents_md
 from ..agents.renderer import render_agents_markdown
@@ -67,7 +68,7 @@ def build_generated_files(
     Returns:
         Expected generated files in write order.
     """
-    files: list[GeneratedFile] = []
+    files: list[GeneratedFile] = [build_project_gitignore_file(cwd)]
     if lock_data:
         files.append(GeneratedFile(lock_path(cwd), dump_toml(lock_data)))
     if "agents_md" in config:

codexmgr-0.4.1/src/codexmgr/project/gitignore.py

@@ -0,0 +1,43 @@
+"""Managed ignore rules for project-local Codex runtime state."""
+
+from pathlib import Path
+
+from .state import GeneratedFile
+from ..core.managed_text import render_managed_block
+from ..core.paths import codex_gitignore_path
+
+BEGIN_MARKER = "# BEGIN CODEXMGR GENERATED"
+END_MARKER = "# END CODEXMGR GENERATED"
+MANAGED_IGNORE_RULES = """*
+!/.gitignore
+!/codexmgr.toml
+!/codexmgr.lock
+!/config.toml
+!/hooks.json
+!/agents/
+!/agents/**
+!/hooks/
+!/hooks/**
+__pycache__/
+"""
+
+
+def build_project_gitignore_file(cwd: Path) -> GeneratedFile:
+    """Build the future-proof project Codex ignore-file state.
+
+    Args:
+        cwd: Project directory containing the local ``.codex`` home.
+
+    Returns:
+        Generated file preserving manual content outside codexmgr's block.
+    """
+    path = codex_gitignore_path(cwd)
+    current = path.read_text(encoding="utf-8") if path.exists() else ""
+    content = render_managed_block(
+        current,
+        MANAGED_IGNORE_RULES,
+        begin_marker=BEGIN_MARKER,
+        end_marker=END_MARKER,
+        artifact_name=".codex/.gitignore",
+    )
+    return GeneratedFile(path, content)