cgh-codegen 0.1.0__py3-none-any.whl

cgh_codegen/generate.py

@@ -0,0 +1,193 @@
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# __creation__ = 2026-09-15
+# __author__ = "jndjama (Joy Ndjama)"
+# __copyright__ = "Copyright 2026 ALTIKVA."
+# __licence__ = "MIT"
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# Description: The pure, I/O-free core of code generation. build_prompt turns
+#              a spec plus reference files into a (system, user) pair;
+#              extract_code pulls the code out of a model reply, dropping any
+#              surrounding prose so a cheap model's apology or half-answer
+#              never reaches disk; generate_code runs a Backend and returns
+#              the cleaned result. No file writes, no network, no gate here:
+#              those wrap this. A Backend is injectable, so FakeBackend is the
+#              whole test harness.
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+# Appended to both prompts. These are exactly the smells the in-flow ruff pass
+# cannot clean on its own: ruff classes the fixes as "unsafe" (renaming an
+# unused binding, rewriting % into an f-string), so `ruff check --fix` leaves
+# them and the file would need a hand pass. Steering the cheap model away from
+# them up front keeps generated code landing ruff-clean.
+_CLEAN_CODE_RULE = (
+    " Write clean code that a linter accepts with no edits: no unused imports "
+    "or variables (use _ for an intentionally unused unpacked value), and use "
+    "f-strings, never %-formatting or .format(), for string interpolation."
+)
+
+# The system instruction. Two things it has to get right, both learned from
+# dogfooding a cheap model: (1) the reference is a STYLE example, not content
+# to reproduce, or the model echoes the whole reference back with the change
+# spliced in; (2) the file must come inside a single fenced block, the frame
+# that lets extract_code keep the code and drop any prose the model adds. A
+# reply with no fence is treated as "nothing usable" rather than written out.
+SYSTEM_PROMPT = (
+    "You write the complete contents of ONE new code file from a spec. "
+    "The reference files show the conventions, naming, structure and style to "
+    "follow. Imitate their style, but do NOT reproduce their content: output "
+    "only the new file the spec describes, never the reference itself. Return "
+    "it as a single fenced code block (```) and nothing outside the fence. If "
+    "you cannot produce the file, return an empty fenced block." + _CLEAN_CODE_RULE
+)
+
+# The extend-mode twin. The instruction above is the wrong one when a file is
+# being grown: told to write a complete file, a cheap model returns the whole
+# thing rewritten, and appending that would duplicate everything already there.
+EXTEND_SYSTEM_PROMPT = (
+    "You write ONE block of code to append to the end of an existing file. "
+    "You are shown that file: match its conventions, and do NOT repeat any of "
+    "it. Output only the new code, never the file's existing contents and "
+    "never the whole file. Return it as a single fenced code block (```) and "
+    "nothing outside the fence. If you cannot produce it, return an empty "
+    "fenced block." + _CLEAN_CODE_RULE
+)
+
+_FENCE_RE = re.compile(r"```[^\n]*\n(.*?)```", re.DOTALL)
+
+# The same match, but running to the LAST fence instead of the first. Needed
+# when the generated file legitimately contains fences of its own.
+_OUTER_FENCE_RE = re.compile(r"```[^\n]*\n(.*)```", re.DOTALL)
+
+
+class GenerationError(RuntimeError):
+    """Raised when a backend returns nothing usable."""
+
+
+@dataclass(frozen=True, slots=True)
+class GenResult:
+    """A backend's reply after cleaning. ``cost`` is the backend's own
+    estimate in whatever unit it reports (0.0 for local backends)."""
+
+    code: str
+    cost: float = 0.0
+    backend: str = ""
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """A code-generating model. One method, so FakeBackend is trivial and
+    the real backends (agent CLI, local, cloud) drop in behind the same
+    seam later. ``is_local`` is True when generation never leaves the
+    machine (e.g. a local model); the flow skips the egress gate for those,
+    exactly like the rest of cgh."""
+
+    name: str
+    is_local: bool
+
+    def generate(self, system: str, user: str) -> tuple[str, float]:
+        """Return (raw_text, cost). Must not raise for an empty reply,
+        return ("", cost) instead so the caller decides."""
+        ...
+
+
+def build_prompt(
+    spec: str,
+    references: list[tuple[str, str]],
+    target: str | None = None,
+    prior: tuple[str, str] | None = None,
+    existing: str | None = None,
+) -> tuple[str, str]:
+    """Build the (system, user) prompt. ``references`` is a list of
+    (path, text), each wrapped as a style example the model imitates but does
+    not copy. Naming the ``target`` file up front keeps the model producing a
+    new file rather than echoing the reference; the spec leads so it is not
+    buried under a long reference. ``prior`` is (previous_code, check_output)
+    from a failed verify: it is fed back so the model fixes the specific
+    failure instead of guessing, which is what makes the self-correct loop
+    catch the subtleties a first pass misses. ``existing`` is the current text
+    of a file being extended rather than created: the model sees it and returns
+    only the block to append, never a rewrite, so nothing already in the file
+    can be lost to a careless regeneration."""
+    if existing is not None:
+        lead = (
+            f"Add to the existing file: {target}\n"
+            "Return ONLY the new code to append at the end of the file, not "
+            "the whole file. Match the conventions already in it and do not "
+            "repeat anything it already contains. Everything it needs must "
+            "already be imported there: if your addition would require a new "
+            "import, use a fully qualified reference instead.\n\n"
+        )
+    else:
+        lead = f"Write the new file: {target}\n\n" if target else ""
+    blocks = [f"{lead}SPEC:\n{spec.strip()}\n"]
+    if existing is not None:
+        blocks.append(
+            f'<file_to_extend path="{target}">\n{existing}\n</file_to_extend>'
+        )
+    for path, text in references:
+        blocks.append(f'<style_example path="{path}">\n{text}\n</style_example>')
+    if prior is not None:
+        prev_code, check_output = prior
+        blocks.append(
+            "Your previous attempt did not pass its check. Return a corrected "
+            + ("block to append" if existing is not None else "complete file")
+            + " that fixes the failure below (keep everything that "
+            "was already correct).\n"
+            f"<previous_attempt>\n{prev_code}\n</previous_attempt>\n"
+            f"<check_failure>\n{check_output}\n</check_failure>"
+        )
+    system = EXTEND_SYSTEM_PROMPT if existing is not None else SYSTEM_PROMPT
+    return system, "\n\n".join(blocks)
+
+
+def extract_code(reply: str) -> str:
+    """Pull the code out of a model reply.
+
+    Only the first fenced code block counts: its contents are the file, and
+    any prose the model added around the fence is dropped. A reply with no
+    fence returns the empty string, which the caller reads as "nothing
+    usable" and refuses to write. This is deliberate: it is safer to refuse
+    an unframed reply than to write a cheap model's apology or half-answer
+    over a target file.
+
+    A generated file can legitimately contain fences of its own: a test that
+    builds a fenced model reply, a docs generator, anything that writes
+    Markdown. Stopping at the first closing fence cuts those off mid-file,
+    often mid-string, and the truncation is silent. So when the reply holds
+    more than the outer pair, run to the last fence instead of the first.
+    """
+    pattern = _OUTER_FENCE_RE if reply.count("```") > 2 else _FENCE_RE
+    m = pattern.search(reply)
+    if m:
+        return m.group(1).strip("\n")
+    return ""
+
+
+def generate_code(
+    spec: str,
+    references: list[tuple[str, str]],
+    backend: Backend,
+    target: str | None = None,
+    prior: tuple[str, str] | None = None,
+    existing: str | None = None,
+) -> GenResult:
+    """Run one generation. Pure orchestration: build the prompt, call the
+    backend, clean the reply. No file is written and no egress gate is
+    consulted here; that is the caller's job. Raises GenerationError when the
+    backend returns nothing usable so an empty file is never produced.
+    ``prior`` feeds a failed attempt's code + check output back for a retry.
+    ``existing`` switches the prompt to extend that text instead of writing a
+    new file, in which case the result holds only the block to append."""
+    if not spec.strip():
+        raise GenerationError("empty spec")
+    system, user = build_prompt(spec, references, target, prior, existing)
+    raw, cost = backend.generate(system, user)
+    code = extract_code(raw)
+    if not code.strip():
+        raise GenerationError(f"backend {backend.name!r} returned no code")
+    return GenResult(code=code, cost=cost, backend=backend.name)

cgh_codegen/logview.py

@@ -0,0 +1,42 @@
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# __creation__ = 2026-09-19
+# __author__ = "jndjama (Joy Ndjama)"
+# __copyright__ = "Copyright 2026 ALTIKVA."
+# __licence__ = "MIT"
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# Description: The human's model-free view of what codegen did. codegen already
+#              audits every generation to the shared activity log; codegen_activity
+#              reads that log back and keeps only codegen's own events, so the
+#              CLI can show the work without a single line entering an agent's
+#              context. This is the token-cheap surface: results are read from
+#              disk, never relayed through the expensive model.
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# The events codegen writes via flow._audit. Kept in one place so the log view
+# and the writer cannot silently disagree about what counts as codegen activity.
+CODEGEN_EVENTS = (
+    "codegen_generated",
+    "codegen_extended",
+    "codegen_egress_denied",
+)
+
+
+def codegen_activity(
+    repo_root: str | Path, limit: int = 20, scan: int = 1000
+) -> list[tuple[float, str, str]]:
+    """The recent codegen entries from the repo's activity log, oldest first,
+    as ``(ts, event, detail)`` tuples.
+
+    Reads at most the last ``scan`` activity entries (the log holds every
+    kind of event, not just codegen's), keeps the codegen ones, and returns
+    the last ``limit`` of those. An empty list means codegen has done nothing
+    here, or nothing within the scan window.
+    """
+    from codegraph.plugin_api import activity_tail
+
+    entries = activity_tail(str(repo_root), max(1, scan))
+    hits = [e for e in entries if len(e) >= 2 and e[1] in CODEGEN_EVENTS]
+    return hits[-max(0, limit) :]

cgh_codegen/mcp_tools.py

@@ -0,0 +1,94 @@
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# __creation__ = 2026-09-14
+# __author__ = "jndjama (Joy Ndjama)"
+# __copyright__ = "Copyright 2026 ALTIKVA."
+# __licence__ = "MIT"
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# Description: MCP tools codegen_pick(target, reference?) and
+#              codegen_write(spec, target, ...): pick the reference to mirror, and
+#              generate the file from a spec behind the egress gate. Both run
+#              inside the owner, so the graph read reuses the owner's
+#              connection.
+
+from __future__ import annotations
+
+import json
+
+
+def make_mcp_registrar(config: dict):
+    def register_tools(mcp) -> None:
+        from codegraph.plugin_api import server_root
+
+        @mcp.tool()
+        def codegen_pick(target: str, reference: str = "") -> str:
+            """
+            Pick the existing file to mirror when generating `target`
+            (a path you intend to write, e.g. tests/test_user_service.py).
+            Combines the code graph (a file defining a symbol related to
+            the target's name) with the target's own directory (a sibling
+            of the same kind), and returns the chosen reference, the reason,
+            and the runner-up candidates. Use it before writing boilerplate
+            so the new file matches an established pattern. Pass `reference`
+            to validate a specific file instead of picking one.
+            """
+            from .picker import CodegenError, pick_reference
+
+            root = server_root()
+            if root is None:
+                return json.dumps({"error": "no repo root"})
+            try:
+                result = pick_reference(root, target, reference or None)
+            except CodegenError as exc:
+                return json.dumps({"error": str(exc)})
+            return json.dumps(result, indent=2)
+
+        @mcp.tool()
+        def codegen_write(
+            spec: str, target: str, reference: str = "", force: bool = False
+        ) -> str:
+            """
+            Generate `target` from `spec` with a cheap model, mirroring an
+            existing file's conventions (picked from the graph, or the one
+            you pass as `reference`), and write it. Use this to hand off
+            predictable, pattern-following code (stubs, config, boilerplate)
+            so you spend no tokens producing it yourself. The reference is
+            run through the egress gate before it reaches a cloud model; a
+            confidential or PII-labeled reference is refused. An existing
+            target is not overwritten unless `force` is true.
+
+            The returned code is unverified: confirm it by running the
+            type-checker, linter, or tests, never by trusting that it is
+            correct because a later check was green.
+            """
+            from .backends import resolve_backend
+            from .flow import run_generation
+            from .generate import GenerationError
+            from .picker import CodegenError
+
+            root = server_root()
+            if root is None:
+                return json.dumps({"error": "no repo root"})
+            backend = resolve_backend(config)
+            if backend is None:
+                return json.dumps(
+                    {"error": "no backend configured ([plugin.codegen] command)"}
+                )
+            try:
+                # The verify check comes from config, never the caller: an
+                # agent-supplied shell command would be an injection surface.
+                result = run_generation(
+                    root,
+                    spec,
+                    target,
+                    reference or None,
+                    config=config,
+                    backend=backend,
+                    force=force,
+                    verify=config.get("verify") or None,
+                    max_attempts=max(1, int(config.get("max_attempts", 1))),
+                )
+            except (CodegenError, GenerationError) as exc:
+                return json.dumps({"error": str(exc)})
+            return json.dumps(result, indent=2)
+
+    return register_tools

cgh_codegen/picker.py

@@ -0,0 +1,238 @@
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# __creation__ = 2026-09-14
+# __author__ = "jndjama (Joy Ndjama)"
+# __copyright__ = "Copyright 2026 ALTIKVA."
+# __licence__ = "MIT"
+# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+# Description: Reference selection. Given the file to generate, find the best
+#              existing file to mirror. Two signals combined: the graph (a
+#              file defining a symbol related to the target's name, via the
+#              public find_symbol_files) and the filesystem (a sibling in the
+#              same directory of the same kind). Degrades to filesystem-only
+#              when the graph is unavailable. All candidate paths are confined
+#              to the repo root.
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class CodegenError(RuntimeError):
+    """Base error for the cgh-codegen plugin."""
+
+
+# Name-stem prefixes/suffixes that carry no pattern signal on their own.
+_NOISE_TOKENS = frozenset({"test", "tests", "spec", "specs", "impl", "base", "mod"})
+
+# How long reference selection waits on the graph before giving up and using
+# filesystem siblings only. Reference selection is normally sub-second; this is
+# a generous ceiling that turns an indefinite hang behind a wedged owner into a
+# bounded, fail-fast degradation.
+_GRAPH_DEADLINE_S = 10.0
+
+
+@dataclass(slots=True)
+class Candidate:
+    path: Path
+    score: int
+    reasons: list[str] = field(default_factory=list)
+
+
+def _confine(root: Path, candidate: str) -> Path | None:
+    """Resolve ``candidate`` under ``root``; None if it escapes the root."""
+    p = Path(candidate)
+    resolved = (p if p.is_absolute() else root / p).resolve()
+    if resolved == root or root in resolved.parents:
+        return resolved
+    return None
+
+
+def _split_words(stem: str) -> list[str]:
+    """Break a file stem into lowercase words across snake_case and
+    camelCase/PascalCase, e.g. test_userService -> [test, user, service]."""
+    parts: list[str] = []
+    for chunk in re.split(r"[_\-.]+", stem):
+        parts.extend(re.findall(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+", chunk))
+    return [p.lower() for p in parts if p]
+
+
+def name_tokens(stem: str) -> list[str]:
+    """Case variants a symbol search should try for this stem. Drops the
+    noise words (test, spec, ...) so `test_user_service` searches for the
+    thing under test, then offers snake, Pascal and per-word variants since
+    the graph's substring match is case-sensitive."""
+    words = _split_words(stem)
+    meaningful = [w for w in words if w not in _NOISE_TOKENS] or words
+    tokens: list[str] = []
+
+    def add(t: str) -> None:
+        if t and t not in tokens:
+            tokens.append(t)
+
+    add("_".join(meaningful))  # snake_case
+    add("".join(w.capitalize() for w in meaningful))  # PascalCase
+    for w in meaningful:
+        add(w)
+        add(w.capitalize())
+    return tokens
+
+
+def _graph_candidates_query(
+    root: Path, tokens: list[str]
+) -> tuple[set[Path], bool | None]:
+    """Files the graph says define a symbol matching any token. The bool is
+    graph availability: True if a query succeeded, False if the graph could
+    not be read at all, None if there was nothing to ask."""
+    from codegraph.plugin_api import find_symbol_files
+
+    files: set[Path] = set()
+    available: bool | None = None
+    for tok in tokens:
+        rows = find_symbol_files(str(root), tok)
+        if rows is None:
+            if available is None:
+                available = False
+            continue
+        available = True
+        for r in rows:
+            confined = _confine(root, r["file"])
+            if confined is not None:
+                files.add(confined)
+    return files, available
+
+
+def _graph_candidates(
+    root: Path, tokens: list[str], timeout: float = _GRAPH_DEADLINE_S
+) -> tuple[set[Path], bool | None]:
+    """Bounded wrapper around the graph query. find_symbol_files talks to the
+    repo's owner, and a wedged owner (one whose reindex is stuck holding the
+    write lock) can block that read indefinitely, which is how a codegen call
+    hung for half an hour with no output. Run it under a deadline: if it does
+    not answer in time, treat the graph as unavailable and let selection fall
+    back to filesystem siblings, so codegen degrades instead of hanging."""
+    import threading
+
+    box: dict = {"result": (set(), None)}
+
+    def _run() -> None:
+        box["result"] = _graph_candidates_query(root, tokens)
+
+    worker = threading.Thread(target=_run, daemon=True)
+    worker.start()
+    worker.join(timeout)
+    if worker.is_alive():
+        # The graph read is stuck. Don't wait it out; the daemon thread unwinds
+        # on its own if the query ever returns. Graph unavailable, siblings only.
+        return set(), False
+    return box["result"]
+
+
+def pick_reference(
+    repo_root: str | Path,
+    target: str,
+    explicit_reference: str | None = None,
+    graph_timeout: float | None = None,
+) -> dict:
+    """Choose the file to mirror when generating ``target``.
+
+    Returns ``{reference, reason, candidates, graph_available}``.
+    ``reference`` is a repo-relative path or None when nothing fits (the
+    caller then requires an explicit reference). An explicit reference is
+    validated and returned as-is.
+    """
+    root = Path(repo_root).resolve()
+
+    if explicit_reference:
+        ref = _confine(root, explicit_reference)
+        if ref is None:
+            raise CodegenError(f"reference {explicit_reference!r} is outside the repo")
+        if not ref.is_file():
+            raise CodegenError(f"reference {explicit_reference!r} is not a file")
+        return {
+            "reference": _rel(root, ref),
+            "reason": "given by the caller",
+            "candidates": [],
+            "graph_available": None,
+        }
+
+    tgt = _confine(root, target)
+    if tgt is None:
+        raise CodegenError(f"target {target!r} is outside the repo")
+
+    suffix = tgt.suffix
+    parent = tgt.parent
+    tokens = name_tokens(tgt.stem)
+    graph_files, graph_available = _graph_candidates(
+        root, tokens, graph_timeout if graph_timeout is not None else _GRAPH_DEADLINE_S
+    )
+    tgt_words = set(_split_words(tgt.stem))
+
+    # Candidate pool: existing files of the same kind, from the target's
+    # directory and from the graph hits. The target itself never counts.
+    pool: set[Path] = set()
+    if parent.exists():
+        pool.update(
+            p.resolve()
+            for p in parent.glob(f"*{suffix}")
+            if p.is_file() and p.resolve() != tgt
+        )
+    pool.update(f for f in graph_files if f.suffix == suffix and f != tgt)
+
+    # A file in the target's own directory is the same kind of thing in the
+    # same place (a new commands_*.py mirrors its commands_*.py neighbours,
+    # not a test that merely mentions the name), so the sibling weight is set
+    # above the graph-match weight: a same-directory sibling outranks a bare
+    # cross-directory symbol match, while a file that is BOTH still wins.
+    _GRAPH_WEIGHT = 3
+    _SIBLING_WEIGHT = 4
+    # Each shared name word weighs more than a bare graph symbol match, so
+    # among same-directory siblings the closest NAME wins: for a test the file
+    # name is the signal (test_dedup_family for a family-dedup test), and a
+    # graph hit on a differently-named sibling should not outrank it. Two
+    # shared words (2 x 2 = 4) clear the graph weight (3); one word does not.
+    _OVERLAP_WEIGHT = 2
+    scored: list[Candidate] = []
+    for path in pool:
+        c = Candidate(path=path, score=0)
+        if path in graph_files:
+            c.score += _GRAPH_WEIGHT
+            c.reasons.append("defines a matching symbol")
+        if path.parent == parent:
+            c.score += _SIBLING_WEIGHT
+            c.reasons.append("sibling in the same directory")
+        overlap = len(tgt_words & set(_split_words(path.stem)))
+        if overlap:
+            c.score += overlap * _OVERLAP_WEIGHT
+            c.reasons.append(f"shares {overlap} name word(s)")
+        if c.score:
+            scored.append(c)
+
+    scored.sort(key=lambda c: (c.score, str(c.path)), reverse=True)
+
+    if not scored:
+        return {
+            "reference": None,
+            "reason": (
+                "no analogue found in the graph or the target directory; "
+                "pass an explicit reference"
+            ),
+            "candidates": [],
+            "graph_available": graph_available,
+        }
+
+    best = scored[0]
+    return {
+        "reference": _rel(root, best.path),
+        "reason": ", ".join(best.reasons),
+        "candidates": [_rel(root, c.path) for c in scored[:5]],
+        "graph_available": graph_available,
+    }
+
+
+def _rel(root: Path, path: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)

cgh_codegen-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+cgh_codegen/__init__.py,sha256=gsXAnk3XIH5y-GdH6AsHqkii6X8cPMJWd5IJsMjeJsM,876
+cgh_codegen/backends.py,sha256=aCNggT4xfRokhM3UAl7Xe-XzLan24KO1uUXVTGmyz4E,4943
+cgh_codegen/cli.py,sha256=TvuYwe9GOuPac5vZ1TqlfM5uq4WNBDWg3ppNOllZUxA,10963
+cgh_codegen/flow.py,sha256=JVZGpFqEZySxYO_PsXno1O-kiyjq-uyNXyzDtFhX_zI,17311
+cgh_codegen/gate.py,sha256=WLEf15Giy2ZWDq_M42s9qbWsB5Tss9YpwNV9nEdZQsY,3170
+cgh_codegen/generate.py,sha256=I-X_Lwwhw7RgH_gBryaissctV9m-5PRBiub3NijGo74,9169
+cgh_codegen/logview.py,sha256=V9-eqrUp8yj-9ltYRgajqQ8y2RNYMwJutflwxempKyA,1826
+cgh_codegen/mcp_tools.py,sha256=dI3AQSmrhuoscOq_UXXZCJhp_IdrU0vkVHhcmJoaodU,4187
+cgh_codegen/picker.py,sha256=dhcuKPpsXSMNLPWbAFHxfiONQ5Rs0SiJrkkyAnkGMXQ,8953
+cgh_codegen/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cgh_codegen-0.1.0.dist-info/METADATA,sha256=_Z2A_c322WgSAJfFYMOUNWil9lMEFi36FEFanQYliKY,3607
+cgh_codegen-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cgh_codegen-0.1.0.dist-info/entry_points.txt,sha256=pFElgu1LhxBxkgjFepEH5mNCjIk8FIFTBzUMK65Ss9s,28
+cgh_codegen-0.1.0.dist-info/top_level.txt,sha256=TXgsFyhkFZ5D1GWrgYK-oSGtK4vYFwfGxQTKbqwISi8,12
+cgh_codegen-0.1.0.dist-info/RECORD,,

cgh_codegen-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+