atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a3_og_features/forge_pipeline.py

@@ -0,0 +1,295 @@
+"""Tier a3 — Forge feature orchestrators.
+
+These wire the a1 helpers + a2 composites into the user-facing verbs:
+``recon`` (scout + emergent overlay), ``cherry`` (cherry-pick),
+``finalize`` (assimilate + wire + certify), and ``auto`` (the whole chain).
+
+Every entry point returns a structured dict so downstream tools can pipe
+output reliably.  When ``apply=False`` the pipeline runs in dry-run mode —
+nothing is written to disk except into the project's ``.atomadic-forge/``
+manifest store.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from .. import __version__
+from ..a0_qk_constants.tier_names import TIER_NAMES
+from ..a1_at_functions.agent_plan_emitter import emit_agent_plan
+from ..a1_at_functions.certify_checks import certify
+from ..a1_at_functions.cherry_pick import select_items
+from ..a1_at_functions.scout_walk import harvest_repo
+from ..a1_at_functions.wire_check import scan_violations
+from ..a2_mo_composites.manifest_store import ManifestStore
+
+_STATUS_TEMPLATE = """# Atomadic Forge — Assimilation Status
+
+This directory was produced by ``forge auto`` / ``forge finalize``.  It is
+**bootstrapped material**, not a finished product.
+
+## What's here
+- 5-tier monadic layout (``a0_qk_constants/`` … ``a4_sy_orchestration/``)
+- Symbols ingested from {source_count} source repo(s)
+- {component_count} components emitted
+- Digest: ``{digest}``
+
+## What's still required before shipping
+1. **Integration tests** against real inputs — the bootstrap copies code
+   verbatim where possible, but cross-symbol semantics (two ``User`` classes,
+   two ``authenticate`` flows) need human reconciliation.
+2. **Runtime configuration** — secrets, environment variables, DB URLs.
+3. **Observability** — logging, metrics, error reporting.
+4. **Wire enforcement** — run ``forge wire`` and address any violations.
+5. **Certification** — ``forge certify`` should hit ≥ 75 before public use.
+
+## Provenance
+Source repos: {source_list}
+
+Generated by atomadic-forge {version}.
+"""
+
+
+def _current_version() -> str:
+    """Return the source version for generated artifacts."""
+    return __version__
+
+
+def _target_file_for_symbol(target_dir: Path, slug: str, source_file: Path) -> Path:
+    """Keep absorbed source in its original language extension."""
+    suffix = source_file.suffix.lower() or ".py"
+    return target_dir / f"{slug}{suffix}"
+
+
+def run_recon(
+    target: Path,
+    *,
+    store_manifest: bool = True,
+    progress: Callable[[int, int, str], None] | None = None,
+) -> dict[str, Any]:
+    """``forge recon`` — scout walk + persist scout.json under .atomadic-forge/.
+
+    ``progress`` (optional): forwarded to ``harvest_repo`` for per-file
+    reporting on big repos. The CLI builds a stderr reporter; library
+    callers can pass any callback or ``None``.
+    """
+    target = Path(target).resolve()
+    report = harvest_repo(target, progress=progress)
+    if store_manifest:
+        ManifestStore(target).save("scout", report)
+    return report
+
+
+def run_cherry(target: Path, *, names: Iterable[str] | None = None,
+               pick_all: bool = False, only_tier: str | None = None,
+               store_manifest: bool = True,
+               progress: Callable[[int, int, str], None] | None = None,
+               ) -> dict[str, Any]:
+    """``forge cherry`` — derive a cherry-pick manifest from the latest scout."""
+    target = Path(target).resolve()
+    store = ManifestStore(target)
+    scout = store.load("scout") or harvest_repo(target, progress=progress)
+    if not store.load("scout") and store_manifest:
+        store.save("scout", scout)
+    manifest = select_items(scout, names=names, pick_all=pick_all,
+                            only_tier=only_tier)
+    if store_manifest:
+        store.save("cherry", manifest)
+    return manifest
+
+
+def run_finalize(*, target: Path, output: Path, package: str = "absorbed",
+                 cherry_manifest: dict[str, Any] | None = None,
+                 apply: bool = False,
+                 on_conflict: str = "rename") -> dict[str, Any]:
+    """``forge finalize`` — assimilate + wire + certify.
+
+    ``on_conflict`` resolves duplicate qualnames across roots:
+    ``rename``  (default) appends a suffix
+    ``first``   keep first-seen
+    ``last``    keep last-seen
+    ``fail``    raise ValueError
+    """
+    target = Path(target).resolve()
+    output = Path(output).resolve()
+    if cherry_manifest is None:
+        cherry_manifest = run_cherry(target, pick_all=True)
+
+    pkg_root = output / "src" / package
+    if apply:
+        for tier in TIER_NAMES:
+            (pkg_root / tier).mkdir(parents=True, exist_ok=True)
+            (pkg_root / tier / "__init__.py").write_text(
+                f'"""{tier}."""\n', encoding="utf-8",
+            )
+        (pkg_root / "__init__.py").write_text(
+            '"""Absorbed package — bootstrapped by atomadic-forge."""\n'
+            '__version__ = "0.0.1"\n',
+            encoding="utf-8",
+        )
+
+    items = cherry_manifest.get("items", [])
+    seen_targets: dict[Path, dict] = {}  # target file → originating item
+    components_emitted = 0
+    tier_dist: dict[str, int] = {}
+    skipped: list[dict] = []
+
+    for it in items:
+        qual = it["qualname"]
+        tier = it["target_tier"]
+        # Find the source file from the scout report
+        scout = ManifestStore(target).load("scout") or {}
+        sym = next((s for s in scout.get("symbols", []) if s["qualname"] == qual),
+                    None)
+        if sym is None:
+            skipped.append({"qualname": qual, "reason": "not in scout"})
+            continue
+        src_file = target / sym["file"]
+        if not src_file.exists():
+            skipped.append({"qualname": qual, "reason": "source file gone"})
+            continue
+        slug = qual.replace(".", "_").lower()
+        target_dir = pkg_root / tier
+        target_file = _target_file_for_symbol(target_dir, slug, src_file)
+
+        if target_file in seen_targets:
+            if on_conflict == "fail":
+                raise ValueError(f"conflict on {target_file}: {qual} vs "
+                                 f"{seen_targets[target_file]['qualname']}")
+            if on_conflict == "first":
+                skipped.append({"qualname": qual, "reason": "first-wins"})
+                continue
+            if on_conflict == "last":
+                pass  # fall through, overwrite
+            if on_conflict == "rename":
+                target_file = target_dir / f"{slug}__alt{target_file.suffix}"
+
+        if apply:
+            target_dir.mkdir(parents=True, exist_ok=True)
+            try:
+                shutil.copyfile(src_file, target_file)
+            except OSError as exc:
+                skipped.append({"qualname": qual, "reason": f"copy failed: {exc}"})
+                continue
+        seen_targets[target_file] = it
+        components_emitted += 1
+        tier_dist[tier] = tier_dist.get(tier, 0) + 1
+
+    digest = hashlib.sha256(
+        json.dumps([{**it, "_": "x"} for it in items], sort_keys=True).encode()
+    ).hexdigest()[:16]
+
+    if apply:
+        status = _STATUS_TEMPLATE.format(
+            source_count=1,
+            component_count=components_emitted,
+            digest=digest,
+            source_list=str(target),
+            version=_current_version(),
+        )
+        (output / "STATUS.md").write_text(status, encoding="utf-8")
+
+    wire_report = scan_violations(pkg_root) if apply else {
+        "verdict": "DRY_RUN", "violation_count": 0, "violations": []
+    }
+    cert = certify(output, project=package, package=package) if apply else {
+        "score": 0, "issues": ["dry-run — re-run with --apply to certify"],
+        "schema_version": "atomadic-forge.certify/v1",
+    }
+
+    report = {
+        "schema_version": "atomadic-forge.assimilate/v1",
+        "target_root": str(output),
+        "source_repos": [str(target)],
+        "components_emitted": components_emitted,
+        "tier_distribution": tier_dist,
+        "skipped": skipped,
+        "digest": digest,
+        "wire": wire_report,
+        "certify": cert,
+        "applied": apply,
+        "on_conflict": on_conflict,
+    }
+    if apply:
+        ManifestStore(output).save("assimilate", report)
+    return report
+
+
+def run_auto(*, target: Path, output: Path, package: str = "absorbed",
+             apply: bool = False, on_conflict: str = "rename",
+             progress: Callable[[int, int, str], None] | None = None,
+             ) -> dict[str, Any]:
+    """``forge auto`` — the flagship single-command pipeline.
+
+    Runs: scout → cherry-pick (all) → finalize (assimilate + wire + certify).
+    Always returns a structured report.  Set ``apply=True`` to actually write
+    files; otherwise it's a deterministic dry-run.
+
+    ``progress`` (optional): per-file scout-phase reporter. Cherry/finalize
+    are typically fast enough to skip; only the scout walk is plumbed.
+    """
+    scout = run_recon(target, progress=progress)
+    cherry = run_cherry(target, pick_all=True)
+    final = run_finalize(target=target, output=output, package=package,
+                          cherry_manifest=cherry, apply=apply,
+                          on_conflict=on_conflict)
+    return {
+        "schema_version": "atomadic-forge.auto/v1",
+        "scout": {
+            "symbol_count": scout["symbol_count"],
+            "tier_distribution": scout["tier_distribution"],
+            "recommendations": scout["recommendations"],
+        },
+        "cherry": {"items": len(cherry["items"])},
+        "finalize": final,
+        "applied": apply,
+    }
+
+
+def run_auto_plan(
+    *,
+    target: Path,
+    goal: str = "improve repo conformance",
+    mode: str = "improve",
+    package: str | None = None,
+    top_n: int = 7,
+) -> dict[str, Any]:
+    """Codex-driven 'observe → propose cards' orchestrator.
+
+    Runs scout + wire + certify (and, when available, emergent +
+    synergy) and emits a single ``agent_plan/v1`` with top-N action
+    cards. Does NOT mutate the filesystem — handoff is the agent's
+    responsibility.
+
+    Mode 'improve' (default): the agent operates on the repo at
+    ``target`` in-place; certify runs against ``target`` and the
+    generated cards reference its layout.
+    Mode 'absorb': used by the legacy ``forge auto`` flow when the
+    target is a flat repo and the next action is to scaffold a new
+    tier-organized output.
+
+    The returned dict matches AgentPlan exactly (schema_version
+    'atomadic-forge.agent_plan/v1') so MCP clients can round-trip
+    it without unwrapping.
+    """
+    target = Path(target).resolve()
+    wire = scan_violations(target, suggest_repairs=True)
+    try:
+        cert = certify(target, project=target.name, package=package)
+    except (OSError, RuntimeError, ValueError):
+        cert = None
+    # emergent / synergy reports are optional; the emitter degrades
+    # gracefully when they're absent. Wiring them in here would
+    # require a3→a3 imports (allowed) but would slow the plan call.
+    plan = emit_agent_plan(
+        project_root=str(target),
+        goal=goal, mode=mode,
+        wire_report=wire, certify_report=cert,
+        package=package, top_n=top_n,
+    )
+    return plan

atomadic_forge/a3_og_features/forge_plan_apply.py

@@ -0,0 +1,222 @@
+"""Tier a3 — apply ONE card / ALL applyable cards from an agent_plan.
+
+Codex's prescription: 'agent picks one card, runs its next_command'.
+This module is the bounded-execution helper Forge supplies so the
+agent doesn't have to reimplement card-routing.
+
+Routing strategy:
+  * architectural cards with auto_fixable F-codes → forge enforce
+    --apply against the card's write_scope; Forge enforce already
+    rolls back if violations rise.
+  * operational F0050 (docs missing) → write a minimal README.md
+    using the card's write_scope[0].
+  * operational F0051 (tests missing) → not yet implemented; the
+    apply call records 'skipped' with a 'manual_required' reason.
+  * synthesis / composition cards → not yet implemented; require
+    forge synergy implement / forge emergent synthesize integration.
+
+Every apply attempt records a per-card event in the plan store
+(applied / skipped / rolled_back / failed) so the agent (and Lane F
+W26 audit trail) can reason about what was done.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..a0_qk_constants.agent_plan_schema import AgentActionCard
+from ..a2_mo_composites.plan_store import PlanStore
+from .forge_enforce import run_enforce
+
+_ARCHITECTURAL_AUTO_FIX_FCODES: frozenset[str] = frozenset({
+    "F0041", "F0042", "F0043", "F0044", "F0045", "F0046",
+})
+
+
+def _find_card(plan: dict, card_id: str) -> AgentActionCard | None:
+    for card in plan.get("top_actions", []) or []:
+        if card.get("id") == card_id:
+            return card
+    return None
+
+
+def _apply_architectural_card(
+    project_root: Path,
+    card: AgentActionCard,
+    *,
+    apply: bool,
+) -> dict[str, Any]:
+    """Route an F0041..F0046 card through forge enforce.
+
+    The card's write_scope identifies the file under threat; we run
+    enforce against its package root so the rollback-safe orchestrator
+    handles it. apply=False -> dry-run; apply=True -> actually move.
+    """
+    write_scope = card.get("write_scope") or []
+    if not write_scope:
+        return {"status": "failed",
+                "detail": {"reason": "card has empty write_scope"}}
+    rel = write_scope[0]
+    # Walk up from the file to the nearest tier-organized package.
+    file_path = (project_root / rel).resolve()
+    candidate = file_path.parent
+    pkg_root: Path | None = None
+    while candidate != candidate.parent:
+        # A package root contains tier directories.
+        if any((candidate / t).is_dir() for t in (
+                "a0_qk_constants", "a1_at_functions", "a2_mo_composites",
+                "a3_og_features", "a4_sy_orchestration",
+        )):
+            pkg_root = candidate
+            break
+        candidate = candidate.parent
+    if pkg_root is None:
+        return {"status": "failed",
+                "detail": {"reason": "no tier-organized package root above "
+                                       f"{rel}"}}
+    report = run_enforce(pkg_root, apply=apply)
+    pre, post = report["pre_violations"], report["post_violations"]
+    if not apply:
+        return {"status": "dry_run",
+                "detail": {"pre_violations": pre, "post_violations": post,
+                            "plan": report["plan"]}}
+    if post < pre:
+        return {"status": "applied",
+                "detail": {"pre_violations": pre, "post_violations": post,
+                            "applied": report["applied"]}}
+    if post > pre:
+        return {"status": "rolled_back",
+                "detail": {"pre_violations": pre, "post_violations": post,
+                            "rollbacks": report["rollbacks"]}}
+    return {"status": "noop",
+            "detail": {"pre_violations": pre, "post_violations": post}}
+
+
+def _apply_docs_card(
+    project_root: Path,
+    card: AgentActionCard,
+    *,
+    apply: bool,
+) -> dict[str, Any]:
+    """F0050 minimal-README writer.
+
+    The card's write_scope[0] tells us where the README belongs.
+    apply=True writes a one-line H1 + paragraph; apply=False is a
+    no-op dry-run.
+    """
+    rel = (card.get("write_scope") or ["README.md"])[0]
+    target = (project_root / rel).resolve()
+    if target.exists():
+        return {"status": "skipped",
+                "detail": {"reason": f"{rel} already exists"}}
+    if not apply:
+        return {"status": "dry_run",
+                "detail": {"would_write": str(target.relative_to(project_root))}}
+    pkg = card.get("sample_path") or project_root.name
+    body = (
+        f"# {pkg}\n\n"
+        f"_Stub README written by `forge plan-apply` "
+        f"({card.get('id')})._\n\n"
+        f"Replace this with a real overview before shipping.\n"
+    )
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(body, encoding="utf-8")
+    return {"status": "applied",
+            "detail": {"written": str(target.relative_to(project_root))}}
+
+
+def _route_card(
+    project_root: Path,
+    card: AgentActionCard,
+    *,
+    apply: bool,
+) -> dict[str, Any]:
+    if not card.get("applyable"):
+        return {"status": "skipped",
+                "detail": {"reason": "card.applyable=False (review_manually)"}}
+    related = set(card.get("related_fcodes") or [])
+    if related & _ARCHITECTURAL_AUTO_FIX_FCODES:
+        return _apply_architectural_card(project_root, card, apply=apply)
+    if "F0050" in related:
+        return _apply_docs_card(project_root, card, apply=apply)
+    # F0051 / synthesis / composition: not yet implementable.
+    return {
+        "status": "skipped",
+        "detail": {
+            "reason": "card kind not yet implementable in plan-apply v1",
+            "kind": card.get("kind"),
+            "related_fcodes": list(related),
+        },
+    }
+
+
+def apply_card(
+    project_root: Path,
+    plan: dict,
+    card_id: str,
+    *,
+    apply: bool = False,
+) -> dict[str, Any]:
+    """Apply a single card from a plan.
+
+    Returns a result dict with shape:
+      {schema_version, plan_id, card_id, apply, status, detail}
+
+    Always records the event to the plan store regardless of apply
+    flag (dry runs included) so the audit trail is complete.
+    """
+    project_root = Path(project_root).resolve()
+    plan_id = plan.get("id") or "<unsaved>"
+    card = _find_card(plan, card_id)
+    if card is None:
+        return {
+            "schema_version": "atomadic-forge.plan_apply/v1",
+            "plan_id": plan_id, "card_id": card_id, "apply": apply,
+            "status": "failed",
+            "detail": {"reason": f"card_id {card_id!r} not in plan"},
+        }
+    outcome = _route_card(project_root, card, apply=apply)
+    PlanStore(project_root).record_card_event(
+        plan_id, card_id=card_id,
+        status=outcome["status"],
+        detail={"apply": apply, **outcome.get("detail", {})},
+    )
+    return {
+        "schema_version": "atomadic-forge.plan_apply/v1",
+        "plan_id": plan_id, "card_id": card_id, "apply": apply,
+        **outcome,
+    }
+
+
+def apply_all_applyable(
+    project_root: Path,
+    plan: dict,
+    *,
+    apply: bool = False,
+) -> dict[str, Any]:
+    """Iterate applyable cards in plan order; collect results.
+
+    Stops on the first ``rolled_back`` or ``failed`` outcome — the
+    agent should inspect that result before proceeding rather than
+    cascading further mutations against a now-suspect repo.
+    """
+    project_root = Path(project_root).resolve()
+    plan_id = plan.get("id") or "<unsaved>"
+    results: list[dict] = []
+    halted = None
+    for card in plan.get("top_actions", []) or []:
+        if not card.get("applyable"):
+            continue
+        outcome = apply_card(project_root, plan, card["id"], apply=apply)
+        results.append(outcome)
+        if outcome["status"] in {"rolled_back", "failed"}:
+            halted = outcome["status"]
+            break
+    return {
+        "schema_version": "atomadic-forge.plan_apply_all/v1",
+        "plan_id": plan_id, "apply": apply,
+        "results": results,
+        "halted_on": halted,
+        "applied_count": sum(1 for r in results if r["status"] == "applied"),
+        "skipped_count": sum(1 for r in results if r["status"] == "skipped"),
+    }

atomadic_forge/a3_og_features/lsp_server.py

@@ -0,0 +1,98 @@
+"""Tier a3 — LSP stdio loop wrapping the pure dispatcher.
+
+Golden Path Lane D W12 deliverable. The pure dispatcher lives at
+``a1_at_functions.lsp_protocol``; this module owns the LSP framing
+(Content-Length headers + JSON body) over stdin/stdout, exactly the
+shape every LSP client (VS Code, Neovim, Helix, Sublime, IntelliJ)
+expects on first connect.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import IO
+
+from ..a1_at_functions.lsp_protocol import (
+    LspState,
+    dispatch_request,
+    new_state,
+)
+
+
+def serve_stdio(
+    *,
+    stdin: IO[bytes] | None = None,
+    stdout: IO[bytes] | None = None,
+    stderr: IO[str] | None = None,
+) -> int:
+    """Read LSP messages from stdin (Content-Length framed) and write
+    responses + notifications to stdout. Exits 0 on clean shutdown."""
+    src_in = stdin if stdin is not None else sys.stdin.buffer
+    src_out = stdout if stdout is not None else sys.stdout.buffer
+    src_err = stderr if stderr is not None else sys.stderr
+
+    state: LspState = new_state()
+    src_err.write("forge-lsp: ready (Content-Length framed JSON-RPC)\n")
+    src_err.flush()
+
+    while True:
+        msg = _read_message(src_in)
+        if msg is None:
+            break  # client closed stdin
+        try:
+            request = json.loads(msg.decode("utf-8"))
+        except json.JSONDecodeError:
+            _write_message(src_out, {
+                "jsonrpc": "2.0", "id": None,
+                "error": {"code": -32700, "message": "Parse error"},
+            })
+            continue
+        responses, notifications = dispatch_request(request, state=state)
+        for resp in responses:
+            _write_message(src_out, resp)
+        for note in notifications:
+            _write_message(src_out, note)
+        if request.get("method") == "exit":
+            return 0 if state.get("shutdown_requested") else 1
+    return 0
+
+
+def _read_message(stream: IO[bytes]) -> bytes | None:
+    """Read one LSP message frame: headers terminated by \\r\\n\\r\\n
+    followed by Content-Length bytes of body."""
+    headers: dict[str, str] = {}
+    while True:
+        line = stream.readline()
+        if not line:
+            return None  # EOF
+        s = line.decode("ascii").rstrip("\r\n")
+        if s == "":
+            break
+        if ":" not in s:
+            continue
+        key, _, value = s.partition(":")
+        headers[key.strip().lower()] = value.strip()
+    length_str = headers.get("content-length", "0")
+    try:
+        length = int(length_str)
+    except ValueError:
+        return None
+    if length <= 0:
+        return b""
+    body = b""
+    remaining = length
+    while remaining > 0:
+        chunk = stream.read(remaining)
+        if not chunk:
+            return None  # EOF mid-message
+        body += chunk
+        remaining -= len(chunk)
+    return body
+
+
+def _write_message(stream: IO[bytes], payload: dict) -> None:
+    body = json.dumps(payload, default=str).encode("utf-8")
+    header = f"Content-Length: {len(body)}\r\n\r\n".encode("ascii")
+    stream.write(header)
+    stream.write(body)
+    stream.flush()