cgh-codegen 0.1.0__tar.gz

cgh_codegen-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: cgh-codegen
+Version: 0.1.0
+Summary: Pattern-matched code generation for cgh: a cheap model writes boilerplate that mirrors a reference file cgh picks from the graph
+Author-email: Joy Ndjama <joy.ndjama@altikva.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# cgh-codegen
+
+A cgh plugin that delegates predictable, pattern-following code (tests,
+stubs, config, boilerplate) to a cheap model so the primary model spends
+no tokens producing it. Its distinguishing move: cgh picks the reference
+file to mirror straight from the code graph, so you do not have to name it.
+
+Installs through cgh's plugin entry point. Inert without cgh.
+
+## Surfaces
+
+### `cgh codegen pick`
+
+Report the existing file a generator should mirror for a target, and why.
+
+```
+cgh codegen pick --target tests/test_user_service.py
+# reference: tests/test_order_service.py
+# defines a matching symbol, sibling in the same directory
+```
+
+The pick combines two signals: the graph (a file defining a symbol
+related to the target's name) and the filesystem (a sibling of the same
+kind in the target's directory). It degrades to a filesystem-only pick
+when the graph is not readable (no index yet, or an owner holds the write
+lock). Pass `--reference` to validate a specific file instead.
+
+### `cgh codegen gen`
+
+Generate a file from a spec, mirroring the reference, and write it.
+
+```
+cgh codegen gen --spec "pytest tests for UserService: create, update, delete" \
+                  --target tests/test_user_service.py
+```
+
+The reference (picked, or forced with `--reference`) is run through the
+egress gate before it reaches a cloud model: a confidential or PII-labeled
+reference is refused. A local backend skips the gate. An existing target is
+never overwritten without `--force`; `--stdout` prints instead of writing.
+
+`--extend` grows a file that already exists instead of writing a new one:
+
+```
+cgh codegen gen --extend --target tests/test_user_service.py \
+                  --spec "add a test for the soft-delete path" \
+                  --verify "pytest tests/test_user_service.py -q"
+```
+
+The file itself goes to the model as the thing to add to, and the model
+returns only the block to append, so nothing already in the file passes
+through the model's output and nothing can be dropped from it. The block
+lands before a trailing `if __name__ == "__main__":` guard rather than after
+it. With `--verify`, a check that never passes restores the original: a
+damaged existing file is worse than no change, which is the opposite of the
+tradeoff for a new file, where the failed draft is left for you to read.
+Anything the addition needs must already be imported in the file.
+
+Configure the backend in `.codegraph/config.toml`:
+
+```toml
+[plugin.codegen]
+command = "claude -p"   # any agent CLI, invoked with the prompt on stdin
+```
+
+The generated code is a proposal. Verify it by running the type-checker,
+linter, or tests, never by trusting that it is correct because a later check
+was green. This matters most for generated tests: a green run of tests you
+did not read proves nothing.
+
+### `codegen_pick` and `codegen_write` (MCP tools)
+
+`codegen_pick(target, reference?)` returns the selection as JSON.
+`codegen_write(spec, target, reference?, force?)` generates and writes the
+file, returning what it wrote, the reference used, the egress decision, and
+the cost. Both run inside the owner, so the graph read reuses its
+connection.
+
+## License
+
+MIT. Plugins that interact with cgh only through the documented plugin
+interfaces are not derivative works of cgh.

cgh_codegen-0.1.0/README.md

@@ -0,0 +1,82 @@
+# cgh-codegen
+
+A cgh plugin that delegates predictable, pattern-following code (tests,
+stubs, config, boilerplate) to a cheap model so the primary model spends
+no tokens producing it. Its distinguishing move: cgh picks the reference
+file to mirror straight from the code graph, so you do not have to name it.
+
+Installs through cgh's plugin entry point. Inert without cgh.
+
+## Surfaces
+
+### `cgh codegen pick`
+
+Report the existing file a generator should mirror for a target, and why.
+
+```
+cgh codegen pick --target tests/test_user_service.py
+# reference: tests/test_order_service.py
+# defines a matching symbol, sibling in the same directory
+```
+
+The pick combines two signals: the graph (a file defining a symbol
+related to the target's name) and the filesystem (a sibling of the same
+kind in the target's directory). It degrades to a filesystem-only pick
+when the graph is not readable (no index yet, or an owner holds the write
+lock). Pass `--reference` to validate a specific file instead.
+
+### `cgh codegen gen`
+
+Generate a file from a spec, mirroring the reference, and write it.
+
+```
+cgh codegen gen --spec "pytest tests for UserService: create, update, delete" \
+                  --target tests/test_user_service.py
+```
+
+The reference (picked, or forced with `--reference`) is run through the
+egress gate before it reaches a cloud model: a confidential or PII-labeled
+reference is refused. A local backend skips the gate. An existing target is
+never overwritten without `--force`; `--stdout` prints instead of writing.
+
+`--extend` grows a file that already exists instead of writing a new one:
+
+```
+cgh codegen gen --extend --target tests/test_user_service.py \
+                  --spec "add a test for the soft-delete path" \
+                  --verify "pytest tests/test_user_service.py -q"
+```
+
+The file itself goes to the model as the thing to add to, and the model
+returns only the block to append, so nothing already in the file passes
+through the model's output and nothing can be dropped from it. The block
+lands before a trailing `if __name__ == "__main__":` guard rather than after
+it. With `--verify`, a check that never passes restores the original: a
+damaged existing file is worse than no change, which is the opposite of the
+tradeoff for a new file, where the failed draft is left for you to read.
+Anything the addition needs must already be imported in the file.
+
+Configure the backend in `.codegraph/config.toml`:
+
+```toml
+[plugin.codegen]
+command = "claude -p"   # any agent CLI, invoked with the prompt on stdin
+```
+
+The generated code is a proposal. Verify it by running the type-checker,
+linter, or tests, never by trusting that it is correct because a later check
+was green. This matters most for generated tests: a green run of tests you
+did not read proves nothing.
+
+### `codegen_pick` and `codegen_write` (MCP tools)
+
+`codegen_pick(target, reference?)` returns the selection as JSON.
+`codegen_write(spec, target, reference?, force?)` generates and writes the
+file, returning what it wrote, the reference used, the egress decision, and
+the cost. Both run inside the owner, so the graph read reuses its
+connection.
+
+## License
+
+MIT. Plugins that interact with cgh only through the documented plugin
+interfaces are not derivative works of cgh.

cgh_codegen-0.1.0/cgh_codegen/__init__.py

@@ -0,0 +1,24 @@
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# __creation__ = 2026-09-14
+# __author__ = "jndjama (Joy Ndjama)"
+# __copyright__ = "Copyright 2026 ALTIKVA."
+# __licence__ = "MIT"
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# Description: cgh plugin entry point. Registers the `cgh codegen` CLI
+#              verbs (pick, gen) and the codegen_pick / codegen_write MCP
+#              tools: pick the file to mirror, then generate the target from
+#              a spec with a cheap model, behind the egress gate.
+
+from __future__ import annotations
+
+CGH_PLUGIN_API = 1
+
+
+def register(api) -> None:
+    from .cli import make_cli_registrar
+
+    api.register_cli(make_cli_registrar(api.config))
+
+    from .mcp_tools import make_mcp_registrar
+
+    api.register_mcp_tools(make_mcp_registrar(api.config))

cgh_codegen-0.1.0/cgh_codegen/backends.py

@@ -0,0 +1,133 @@
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# __creation__ = 2026-09-15
+# __author__ = "jndjama (Joy Ndjama)"
+# __copyright__ = "Copyright 2026 ALTIKVA."
+# __licence__ = "MIT"
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# Description: Two backends. CliBackend shells out to a configured agent CLI
+#              (claude, codex, ...), a cloud egress the flow gates. OllamaBackend
+#              calls a local Ollama model, so nothing leaves the machine and the
+#              gate is skipped, the leanest, free path for boilerplate.
+#              resolve_backend picks between them from config. The four-backend
+#              matrix from cgh-summarize is not rebuilt; more come with demand.
+#              Every call goes through the Backend protocol, so tests use a fake.
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import urllib.error
+import urllib.request
+
+_OLLAMA_DEFAULT_URL = "http://127.0.0.1:11434/api/generate"
+
+
+class CliBackend:
+    """Generate by invoking a configured agent CLI. The agent reaches a
+    cloud model, so this is NOT local: the flow runs each reference through
+    the egress gate before calling it."""
+
+    is_local = False
+
+    def __init__(self, command: list[str], timeout: float = 120.0) -> None:
+        # command is an argv list from config, e.g. ["claude", "-p"]. Never a
+        # shell string: no shell=True, so nothing in the prompt is interpreted.
+        self._command = list(command)
+        self._timeout = timeout
+
+    @property
+    def name(self) -> str:
+        return f"cli:{self._command[0]}" if self._command else "cli"
+
+    def available(self) -> bool:
+        return bool(self._command) and shutil.which(self._command[0]) is not None
+
+    def generate(self, system: str, user: str) -> tuple[str, float]:
+        from codegraph.plugin_api import quiet_subprocess_kwargs
+
+        prompt = f"{system}\n\n{user}"
+        try:
+            proc = subprocess.run(
+                [*self._command, "--"],
+                input=prompt,
+                capture_output=True,
+                text=True,
+                timeout=self._timeout,
+                check=False,
+                **quiet_subprocess_kwargs(),
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            return "", 0.0
+        # Cost is unknown for an agent CLI (it bills its own account); report
+        # 0.0 rather than invent a number.
+        return proc.stdout or "", 0.0
+
+
+class OllamaBackend:
+    """Generate with a local Ollama model. Nothing leaves the machine, so
+    is_local is True and the flow skips the egress gate. The leanest option:
+    no cloud round-trip, no per-token cost."""
+
+    is_local = True
+
+    def __init__(
+        self, model: str, url: str = _OLLAMA_DEFAULT_URL, timeout: float = 120.0
+    ) -> None:
+        self._model = model
+        self._url = url
+        self._timeout = timeout
+
+    @property
+    def name(self) -> str:
+        return f"ollama:{self._model}"
+
+    def available(self) -> bool:
+        return bool(self._model)
+
+    def generate(self, system: str, user: str) -> tuple[str, float]:
+        payload = json.dumps(
+            {
+                "model": self._model,
+                "prompt": f"{system}\n\n{user}",
+                "stream": False,
+            }
+        ).encode("utf-8")
+        req = urllib.request.Request(
+            self._url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                body = json.loads(resp.read().decode("utf-8"))
+        except (urllib.error.URLError, TimeoutError, ValueError, OSError):
+            return "", 0.0
+        # Local generation is free; report 0.0 cost.
+        return body.get("response", ""), 0.0
+
+
+def resolve_backend(config: dict):
+    """The backend to generate with, chosen from config. An explicit
+    ``backend = "ollama"`` (or an ``ollama_model`` with no ``command``) selects
+    the local model; otherwise a ``command`` selects the agent CLI. Returns
+    None when nothing is configured, so the caller reports a clear "no backend"
+    instead of guessing."""
+    kind = str(config.get("backend", "")).strip().lower()
+    if kind == "ollama" or (not config.get("command") and config.get("ollama_model")):
+        model = config.get("ollama_model")
+        if not model:
+            return None
+        return OllamaBackend(
+            model,
+            config.get("ollama_url", _OLLAMA_DEFAULT_URL),
+            timeout=float(config.get("timeout", 120.0)),
+        )
+
+    command = config.get("command")
+    if isinstance(command, str):
+        command = command.split()
+    if not command:
+        return None
+    return CliBackend(command, timeout=float(config.get("timeout", 120.0)))

cgh_codegen-0.1.0/cgh_codegen/cli.py

@@ -0,0 +1,295 @@
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# __creation__ = 2026-09-14
+# __author__ = "jndjama (Joy Ndjama)"
+# __copyright__ = "Copyright 2026 ALTIKVA."
+# __licence__ = "MIT"
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# Description: CLI verbs `cgh codegen pick` (report the reference to mirror),
+#              `cgh codegen gen` (generate the file from a spec plus that
+#              reference, behind the egress gate, refusing to clobber without
+#              --force), and `cgh codegen log` (show what codegen has done in
+#              this repo, read from the activity log, at no model-token cost).
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def plugin_config_for_root(root: str | Path, fallback: dict) -> dict:
+    """The [plugin.codegen] table resolved from ``root``.
+
+    Plugins are loaded once at CLI startup against the current directory, so
+    the config captured then belongs to the CWD, not to a --root passed on
+    the command line. Re-resolve from the requested root so --root governs
+    the backend and the egress posture too, not just where the file lands.
+    Falls back to the captured config when the root declares no table.
+    """
+    from codegraph.plugin_api import load_config
+
+    return load_config(root).plugin_tables.get("codegen", fallback)
+
+
+def make_cli_registrar(config: dict):
+    def add_cli(sub) -> None:
+        p = sub.add_parser("codegen", help="Pattern-matched code generation helpers")
+        actions = p.add_subparsers(dest="cw_action")
+
+        pick = actions.add_parser(
+            "pick", help="Show the reference file to mirror for a target"
+        )
+        pick.add_argument("--target", required=True, help="File you intend to write")
+        pick.add_argument(
+            "--reference", default="", help="Force a reference instead of picking one"
+        )
+        pick.add_argument("--root", default=os.getcwd())
+        pick.set_defaults(func=lambda args: _cmd_pick(args, config))
+
+        gen = actions.add_parser(
+            "gen", help="Generate a file from a spec, mirroring a reference"
+        )
+        gen.add_argument(
+            "--spec",
+            default="",
+            help="What to generate. Use '-' to read the spec from stdin. "
+            "Single-quote it in the shell, or use --spec-file, to avoid the "
+            "shell running backticks or $(...) inside it.",
+        )
+        gen.add_argument(
+            "--spec-file",
+            default="",
+            help="Read the spec from this file ('-' for stdin), instead of "
+            "--spec. Sidesteps shell quoting for long or backtick-heavy specs.",
+        )
+        gen.add_argument("--target", required=True, help="File to write")
+        gen.add_argument(
+            "--reference", default="", help="Force a reference instead of picking one"
+        )
+        gen.add_argument(
+            "--force", action="store_true", help="Overwrite the target if it exists"
+        )
+        gen.add_argument(
+            "--stdout", action="store_true", help="Print the code, do not write a file"
+        )
+        gen.add_argument(
+            "--extend",
+            action="store_true",
+            help="Add to an existing target instead of writing a new file; "
+            "the model returns only the block to append",
+        )
+        gen.add_argument(
+            "--verify",
+            default="",
+            help="Shell check (exit 0 = pass) run after writing; drives the "
+            "self-correct loop",
+        )
+        gen.add_argument(
+            "--max-attempts",
+            type=int,
+            default=1,
+            help="With --verify, regenerate up to N times feeding the failure back",
+        )
+        gen.add_argument("--root", default=os.getcwd())
+        gen.set_defaults(func=lambda args: _cmd_gen(args, config))
+
+        log = actions.add_parser(
+            "log",
+            help="Show what codegen has done here, read from the activity log "
+            "(no model tokens)",
+        )
+        log.add_argument("--limit", type=int, default=20, help="Max entries to show")
+        log.add_argument("--root", default=os.getcwd())
+        log.set_defaults(func=lambda args: _cmd_log(args, config))
+
+    return add_cli
+
+
+def _cmd_log(args, config: dict) -> None:
+    from datetime import datetime
+
+    from rich.console import Console
+    from rich.table import Table
+
+    from .logview import codegen_activity
+
+    console = Console()
+    root = Path(os.path.abspath(args.root))
+    rows = codegen_activity(root, limit=args.limit)
+    if not rows:
+        console.print(
+            "[dim]No codegen activity logged in this repo yet. "
+            "Runs of cgh codegen gen show up here.[/dim]"
+        )
+        return
+
+    table = Table(show_header=True, header_style="bold cyan", box=None, pad_edge=False)
+    table.add_column("when", style="dim", no_wrap=True)
+    table.add_column("event")
+    table.add_column("detail", overflow="fold")
+    for ts, event, detail in rows:
+        try:
+            when = datetime.fromtimestamp(float(ts)).strftime("%Y-%m-%d %H:%M")
+        except (ValueError, OSError):
+            when = "?"
+        kind = event.removeprefix("codegen_")
+        label = f"[red]{kind}[/red]" if kind == "egress_denied" else kind
+        table.add_row(when, label, detail)
+    console.print(f"[bold]codegen activity[/bold]  [dim]({len(rows)})[/dim]")
+    console.print(table)
+    console.print(
+        "[dim]Read straight from .codegraph/activity.log; "
+        "nothing here entered a model's context.[/dim]"
+    )
+
+
+def _cmd_pick(args, config: dict) -> None:
+    from rich.console import Console
+
+    from .picker import CodegenError, pick_reference
+
+    console = Console()
+    root = Path(os.path.abspath(args.root))
+    try:
+        result = pick_reference(root, args.target, args.reference or None)
+    except CodegenError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise SystemExit(1) from exc
+
+    if result["reference"] is None:
+        console.print(f"[yellow]{result['reason']}[/yellow]")
+        if result["graph_available"] is False:
+            console.print(
+                "[dim]graph unavailable (no index, or an owner holds the "
+                "lock); picked from the filesystem only.[/dim]"
+            )
+        return
+
+    console.print(f"[bold]reference:[/bold] {result['reference']}")
+    console.print(f"[dim]{result['reason']}[/dim]")
+    others = [c for c in result["candidates"] if c != result["reference"]]
+    if others:
+        console.print("[dim]other candidates: " + ", ".join(others) + "[/dim]")
+    if result["graph_available"] is False:
+        console.print("[dim]graph unavailable; filesystem-only pick.[/dim]")
+
+
+def _resolve_spec(args, console) -> str:
+    """The spec text, from --spec, --spec-file, or stdin ('-' in either).
+
+    Reading from a file or stdin lets an agent pass a long or backtick-heavy
+    spec without the shell running command-substitution inside it (the reported
+    footgun of an unquoted --spec). Exits with a clear message on an empty or
+    missing spec.
+    """
+    import sys
+
+    spec_file = getattr(args, "spec_file", "") or ""
+    spec = getattr(args, "spec", "") or ""
+    text: str | None = None
+    if spec_file == "-" or spec == "-":
+        text = sys.stdin.read()
+    elif spec_file:
+        try:
+            text = Path(spec_file).read_text(encoding="utf-8")
+        except OSError as exc:
+            console.print(f"[red]cannot read --spec-file {spec_file}: {exc}[/red]")
+            raise SystemExit(1) from exc
+    elif spec:
+        text = spec
+    text = (text or "").strip()
+    if not text:
+        console.print(
+            "[red]empty spec.[/red] Pass --spec '...' (single-quoted), "
+            "--spec-file <path>, or --spec - to read from stdin."
+        )
+        raise SystemExit(1)
+    return text
+
+
+def _cmd_gen(args, config: dict) -> None:
+    from rich.console import Console
+
+    from .backends import resolve_backend
+    from .flow import run_generation
+    from .generate import GenerationError
+    from .picker import CodegenError
+
+    console = Console()
+    root = Path(os.path.abspath(args.root))
+    config = plugin_config_for_root(root, config)
+
+    spec = _resolve_spec(args, console)
+
+    backend = resolve_backend(config)
+    if backend is None:
+        console.print(
+            "[red]no backend configured.[/red] Set a backend command under "
+            "plugin.codegen in .codegraph/config.toml "
+            '(command = "claude -p").'
+        )
+        raise SystemExit(1)
+
+    try:
+        result = run_generation(
+            root,
+            spec,
+            args.target,
+            args.reference or None,
+            config=config,
+            backend=backend,
+            force=args.force,
+            to_stdout=args.stdout,
+            verify=args.verify or None,
+            max_attempts=max(1, args.max_attempts),
+            extend=args.extend,
+        )
+    except (CodegenError, GenerationError) as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise SystemExit(1) from exc
+
+    if args.stdout:
+        # code to stdout stays clean; the notes go to stderr via rich stderr
+        stderr = Console(stderr=True)
+        if result.get("ref_fallback"):
+            stderr.print(f"[yellow]note:[/yellow] [dim]{result['ref_fallback']}[/dim]")
+        stderr.print(
+            f"[dim]{result['reference']} -> {result['lines']} lines "
+            f"({result['backend']}, egress: {result['egress']})[/dim]"
+        )
+        print(result["code"])
+        return
+
+    if result.get("rolled_back"):
+        console.print(
+            f"[red]not appended[/red] to {result['target']}: the check never "
+            f"passed in {result['attempts']} attempt(s), so the file was left "
+            "as it was."
+        )
+        raise SystemExit(1)
+    if result.get("ref_fallback"):
+        console.print(f"[yellow]note:[/yellow] [dim]{result['ref_fallback']}[/dim]")
+    if result["extended"]:
+        console.print(
+            f"[green]appended to[/green] {result['target']}  "
+            f"[dim]({result['lines']} lines added)[/dim]"
+        )
+    else:
+        console.print(
+            f"[green]wrote[/green] {result['target']}  "
+            f"[dim]({result['lines']} lines, mirror of {result['reference']})[/dim]"
+        )
+    v = result.get("verified")
+    if v is True:
+        console.print(
+            f"[green]check passed[/green] "
+            f"[dim]after {result['attempts']} attempt(s)[/dim]"
+        )
+    elif v is False:
+        console.print(
+            f"[yellow]check still failing[/yellow] after {result['attempts']} "
+            "attempt(s); the written file is the last try, review it."
+        )
+    console.print(
+        f"[dim]backend: {result['backend']}  egress: {result['egress']}  "
+        "verify by running the checks, not by trusting this output.[/dim]"
+    )