loopx 0.4.8__py3-none-any.whl

loopx/presets.py

@@ -0,0 +1,369 @@
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+from typing import Any
+
+
+PRESET_PICKER_SCHEMA_VERSION = "loopx_beginner_preset_picker_v0"
+
+
+@dataclass(frozen=True)
+class BeginnerPreset:
+    preset_id: str
+    title: str
+    tier: str
+    maturity: str
+    cadence: str
+    default_mode: str
+    summary: str
+    goal_text: str
+    capability_path: tuple[str, ...]
+    safety_defaults: tuple[str, ...]
+    useful_when: tuple[str, ...]
+
+
+BEGINNER_PRESETS: tuple[BeginnerPreset, ...] = (
+    BeginnerPreset(
+        preset_id="daily-triage",
+        title="Daily Triage L1",
+        tier="beginner_default",
+        maturity="L1 report-only",
+        cadence="daily or weekday morning",
+        default_mode="report_only",
+        summary=(
+            "Inspect LoopX status, active todos, open gates, stale signals, and the "
+            "single next action so the owner gets a useful project digest."
+        ),
+        goal_text=(
+            "Run Daily Triage L1 for this repository: inspect LoopX status, active "
+            "todos, open gates, stale signals, and next actions; write a compact "
+            "report and ask before code edits or external writes."
+        ),
+        capability_path=(
+            "status",
+            "todo projection",
+            "quota should-run",
+            "thin evidence log",
+        ),
+        safety_defaults=(
+            "No code edits by default.",
+            "No external writes by default.",
+            "Human review before changing project files, publishing, or closing gates.",
+        ),
+        useful_when=(
+            "You want LoopX to keep a long-running repo goal warm.",
+            "You need a low-risk first demo that still uses real LoopX state.",
+        ),
+    ),
+    BeginnerPreset(
+        preset_id="changelog-draft",
+        title="Changelog Draft L1",
+        tier="beginner_default",
+        maturity="L1 draft-only",
+        cadence="per release, or daily during release week",
+        default_mode="draft_only",
+        summary=(
+            "Turn recent merged work and LoopX run history into a release-note draft "
+            "that answers the upgrade decision and preserves PR-backed product groups."
+        ),
+        goal_text=(
+            "Run Changelog Draft L1 for this repository: summarize recent merged "
+            "work and LoopX run history into a human-reviewed release-note draft "
+            "that states who should upgrade, what the release solves, whether it is "
+            "breaking, how to verify it, and who contributed; preserve PR-backed "
+            "product groups and optional-capability activation/rollback guidance; "
+            "do not publish."
+        ),
+        capability_path=(
+            "history",
+            "release notes draft",
+            "PR link evidence",
+            "human review gate",
+        ),
+        safety_defaults=(
+            "Draft only; no release creation or publish action.",
+            "Prefer PR links and compact public evidence over raw logs.",
+            "Human review before tagging, announcing, or editing canonical docs.",
+        ),
+        useful_when=(
+            "You want visible maintainer value without granting write authority.",
+            "You need release copy that is grounded in recent work instead of memory.",
+        ),
+    ),
+    BeginnerPreset(
+        preset_id="pr-watch",
+        title="PR Watch L1",
+        tier="beginner_default",
+        maturity="L1 watch-only",
+        cadence="every 10-30 minutes while the PR is active",
+        default_mode="watch_only",
+        summary=(
+            "Watch review, CI, and merge blockers for a PR, then report what changed "
+            "and what needs a human decision."
+        ),
+        goal_text=(
+            "Run PR Watch L1 for this repository: watch review, CI, and merge "
+            "blockers for the target PR; report material changes, blockers, and "
+            "next human decisions; do not auto-merge."
+        ),
+        capability_path=(
+            "continuous monitor todo",
+            "quota monitor-poll",
+            "CI/review blocker summary",
+            "human merge gate",
+        ),
+        safety_defaults=(
+            "No auto-merge.",
+            "No code edits unless the owner upgrades the preset to an explicit L2 fix lane.",
+            "Quiet unchanged polls should not spend quota.",
+        ),
+        useful_when=(
+            "You want fewer manual PR refreshes while keeping merge authority human.",
+            "You need an automation-friendly monitor that still produces concrete blockers.",
+        ),
+    ),
+    BeginnerPreset(
+        preset_id="ci-sweeper",
+        title="CI Sweeper L2",
+        tier="advanced_opt_in",
+        maturity="L2 opt-in patch lane",
+        cadence="on failing checks, or every 30-60 minutes while a PR is active",
+        default_mode="dry_run_report_first",
+        summary=(
+            "Classify failing checks, propose the smallest bounded fix, and only draft "
+            "a worktree patch after explicit owner opt-in."
+        ),
+        goal_text=(
+            "Run CI Sweeper L2 for this repository: inspect failing checks and recent "
+            "CI context, classify the likely fix, then produce a dry-run report first. "
+            "Only after explicit owner opt-in, draft a bounded patch in an isolated "
+            "codex/ worktree, run focused verification, and stop for human review before "
+            "push, merge, rerun-cost expansion, or external writes."
+        ),
+        capability_path=(
+            "failing-check intake",
+            "bounded codex/ worktree patch",
+            "focused verifier or smoke",
+            "human review gate",
+        ),
+        safety_defaults=(
+            "Dry-run report first; no patch until owner opt-in.",
+            "Patch only in an isolated codex/ worktree with a narrow allowed scope.",
+            "Verifier or focused smoke must pass before marking a patch ready.",
+            "Human review before push, merge, rerun-cost expansion, or external writes.",
+            "Escalate after repeated failures or unchanged error signatures.",
+        ),
+        useful_when=(
+            "A PR or main branch has boring, well-scoped check failures.",
+            "You want LoopX to reduce maintainer toil without granting merge authority.",
+        ),
+    ),
+    BeginnerPreset(
+        preset_id="dependency-sweeper",
+        title="Dependency Sweeper L2",
+        tier="advanced_opt_in",
+        maturity="L2 opt-in dependency lane",
+        cadence="weekly, per security notice, or during release hardening",
+        default_mode="policy_report_first",
+        summary=(
+            "Review dependency update candidates against a patch/minor policy, denylist, "
+            "and verifier plan before drafting any update patch."
+        ),
+        goal_text=(
+            "Run Dependency Sweeper L2 for this repository: inspect dependency update "
+            "candidates, apply a patch/minor policy and denylist, then produce a policy "
+            "report first. Only after explicit owner opt-in, draft a bounded dependency "
+            "patch in an isolated codex/ worktree, run focused verification, and stop "
+            "for human review before push, merge, publish, or rollout."
+        ),
+        capability_path=(
+            "dependency candidate intake",
+            "patch/minor policy and denylist",
+            "bounded codex/ worktree patch",
+            "focused verifier or smoke",
+            "human review gate",
+        ),
+        safety_defaults=(
+            "Policy report first; no dependency edit until owner opt-in.",
+            "Default to patch and minor updates; deny major, runtime, lockfile-wide, "
+            "and toolchain jumps unless explicitly allowed.",
+            "Verifier or focused smoke must pass before marking an update ready.",
+            "Human review before push, merge, publish, rollout, or dependency source changes.",
+            "Escalate when updates fail twice, widen scope, or hit a denied package.",
+        ),
+        useful_when=(
+            "A repo has recurring safe dependency bumps or security patch noise.",
+            "You want update toil reduced while keeping rollout and publish authority human.",
+        ),
+    ),
+)
+
+PRESET_IDS = tuple(preset.preset_id for preset in BEGINNER_PRESETS)
+DEFAULT_PRESET_IDS = tuple(
+    preset.preset_id for preset in BEGINNER_PRESETS if preset.tier == "beginner_default"
+)
+ADVANCED_PRESET_IDS = tuple(
+    preset.preset_id for preset in BEGINNER_PRESETS if preset.tier == "advanced_opt_in"
+)
+
+
+def _shell(value: str) -> str:
+    return shlex.quote(value)
+
+
+def _preset_commands(
+    preset: BeginnerPreset,
+    *,
+    cli_bin: str,
+    project: str,
+    goal_id: str,
+    agent_id: str,
+    agent_scope: str,
+) -> dict[str, str]:
+    return {
+        "slash_start": f"/loopx {preset.goal_text}",
+        "cli_start": (
+            f"{cli_bin} start-goal --guided --project {_shell(project)} "
+            f"--goal-text {_shell(preset.goal_text)}"
+        ),
+        "quota_guard": (
+            f"{cli_bin} --format json quota should-run "
+            f"--goal-id {_shell(goal_id)} --agent-id {_shell(agent_id)} "
+            "--runtime-profile codex_app_heartbeat"
+        ),
+        "heartbeat_prompt": (
+            f"{cli_bin} heartbeat-prompt --thin --goal-id {_shell(goal_id)} "
+            f"--agent-id {_shell(agent_id)} --agent-scope {_shell(agent_scope)} "
+            "--runtime-profile codex_app_heartbeat"
+        ),
+    }
+
+
+def _preset_to_dict(
+    preset: BeginnerPreset,
+    *,
+    cli_bin: str,
+    project: str,
+    goal_id: str,
+    agent_id: str,
+    agent_scope: str,
+) -> dict[str, Any]:
+    return {
+        "id": preset.preset_id,
+        "title": preset.title,
+        "tier": preset.tier,
+        "maturity": preset.maturity,
+        "cadence": preset.cadence,
+        "default_mode": preset.default_mode,
+        "summary": preset.summary,
+        "goal_text": preset.goal_text,
+        "capability_path": list(preset.capability_path),
+        "safety_defaults": list(preset.safety_defaults),
+        "useful_when": list(preset.useful_when),
+        "commands": _preset_commands(
+            preset,
+            cli_bin=cli_bin,
+            project=project,
+            goal_id=goal_id,
+            agent_id=agent_id,
+            agent_scope=agent_scope,
+        ),
+    }
+
+
+def build_beginner_preset_packet(
+    *,
+    preset_id: str | None = None,
+    cli_bin: str = "loopx",
+    project: str = ".",
+    goal_id: str = "<goal-id>",
+    agent_id: str = "<agent-id>",
+    agent_scope: str = "<agent-scope>",
+) -> dict[str, Any]:
+    presets = BEGINNER_PRESETS
+    if preset_id:
+        presets = tuple(preset for preset in BEGINNER_PRESETS if preset.preset_id == preset_id)
+        if not presets:
+            raise ValueError(f"unknown beginner preset: {preset_id}")
+    return {
+        "ok": True,
+        "schema_version": PRESET_PICKER_SCHEMA_VERSION,
+        "summary": (
+            "Beginner LoopX presets compile common loop-engineering use cases into "
+            "existing LoopX start, quota, heartbeat, and evidence flows."
+        ),
+        "mutation_policy": "read_only; renders commands only; does not write registry, state, automation, PRs, or docs",
+        "recommended_order": list(PRESET_IDS),
+        "default_preset_ids": list(DEFAULT_PRESET_IDS),
+        "advanced_preset_ids": list(ADVANCED_PRESET_IDS),
+        "placeholders": {
+            "goal_id": goal_id,
+            "agent_id": agent_id,
+            "agent_scope": agent_scope,
+            "project": project,
+        },
+        "common_setup": [
+            f"{cli_bin} doctor",
+            f"{cli_bin} slash-commands --install",
+            f"{cli_bin} preset list",
+        ],
+        "presets": [
+            _preset_to_dict(
+                preset,
+                cli_bin=cli_bin,
+                project=project,
+                goal_id=goal_id,
+                agent_id=agent_id,
+                agent_scope=agent_scope,
+            )
+            for preset in presets
+        ],
+    }
+
+
+def render_beginner_preset_markdown(payload: dict[str, Any]) -> str:
+    lines = [
+        "# LoopX beginner preset picker",
+        "",
+        str(payload.get("summary") or ""),
+        "",
+        f"Mutation policy: {payload.get('mutation_policy')}",
+        "",
+        "Common setup:",
+    ]
+    for command in payload.get("common_setup", []):
+        lines.append(f"- `{command}`")
+    lines.append("")
+    presets = payload.get("presets") if isinstance(payload.get("presets"), list) else []
+    for preset in presets:
+        if not isinstance(preset, dict):
+            continue
+        lines.extend(
+            [
+                f"## {preset.get('title')}",
+                "",
+                f"- id: `{preset.get('id')}`",
+                f"- tier: `{preset.get('tier')}`",
+                f"- maturity: {preset.get('maturity')}",
+                f"- cadence: {preset.get('cadence')}",
+                f"- default mode: `{preset.get('default_mode')}`",
+                f"- summary: {preset.get('summary')}",
+                "",
+                "Useful when:",
+            ]
+        )
+        for item in preset.get("useful_when", []):
+            lines.append(f"- {item}")
+        lines.extend(["", "Safety defaults:"])
+        for item in preset.get("safety_defaults", []):
+            lines.append(f"- {item}")
+        lines.extend(["", "Commands:", ""])
+        commands = preset.get("commands") if isinstance(preset.get("commands"), dict) else {}
+        for label in ("slash_start", "cli_start", "quota_guard", "heartbeat_prompt"):
+            command = commands.get(label)
+            if command:
+                lines.extend([f"{label}:", "```bash", str(command), "```", ""])
+        lines.append(f"Show only this preset: `loopx preset show {preset.get('id')}`")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

loopx/project_alias.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .paths import DEFAULT_RUNTIME_ROOT, global_registry_path
+from .registry import registry_goals
+
+
+def _resolve_path(path: Path) -> Path:
+    try:
+        return path.expanduser().resolve()
+    except OSError:
+        return path.expanduser().absolute()
+
+
+def _run_git(project: Path, *args: str) -> subprocess.CompletedProcess[str] | None:
+    try:
+        return subprocess.run(
+            ["git", "-C", str(project), *args],
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+            timeout=2,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+def _git_root(project: Path) -> Path | None:
+    result = _run_git(project, "rev-parse", "--show-toplevel")
+    if result is None or result.returncode != 0:
+        return None
+    value = result.stdout.strip()
+    return _resolve_path(Path(value)) if value else None
+
+
+def _git_common_dir(project: Path) -> Path | None:
+    root = _git_root(project)
+    if root is None:
+        return None
+    result = _run_git(root, "rev-parse", "--git-common-dir")
+    if result is None or result.returncode != 0:
+        return None
+    value = result.stdout.strip()
+    if not value:
+        return None
+    common = Path(value).expanduser()
+    if not common.is_absolute():
+        common = root / common
+    return _resolve_path(common)
+
+
+def _primary_repo_from_common_dir(common_dir: Path | None) -> Path | None:
+    if common_dir is None:
+        return None
+    if common_dir.name == ".git":
+        return _resolve_path(common_dir.parent)
+    return None
+
+
+def _default_global_registry_path() -> Path:
+    runtime_env = os.environ.get("LOOPX_RUNTIME_ROOT")
+    runtime_root = Path(runtime_env).expanduser() if runtime_env else DEFAULT_RUNTIME_ROOT
+    return global_registry_path(runtime_root)
+
+
+def _read_global_registry(path: Path) -> dict[str, Any] | None:
+    try:
+        with path.expanduser().open(encoding="utf-8") as f:
+            payload = json.load(f)
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _source_repo_for_goal(goal: dict[str, Any]) -> Path | None:
+    repo = goal.get("repo")
+    if repo:
+        return _resolve_path(Path(str(repo)))
+    source_registry = goal.get("source_registry")
+    if not source_registry:
+        return None
+    path = _resolve_path(Path(str(source_registry)))
+    try:
+        return path.parents[1]
+    except IndexError:
+        return None
+
+
+def _same_path(left: Path | None, right: Path | None) -> bool:
+    if left is None or right is None:
+        return False
+    return _resolve_path(left) == _resolve_path(right)
+
+
+def resolve_canonical_project_alias(
+    project: Path,
+    *,
+    goal_id: str | None = None,
+    global_registry: Path | None = None,
+) -> dict[str, Any]:
+    """Map linked git worktrees back to the canonical LoopX source project."""
+
+    resolved_project = _resolve_path(project)
+    target_common_dir = _git_common_dir(resolved_project)
+    global_path = _resolve_path(global_registry or _default_global_registry_path())
+    payload = _read_global_registry(global_path)
+    if not payload or target_common_dir is None:
+        return {
+            "applied": False,
+            "kind": "none",
+            "input_project": str(resolved_project),
+            "global_registry": str(global_path),
+            "git_common_dir": str(target_common_dir) if target_common_dir else None,
+            "reason": "global registry or git common-dir unavailable",
+        }
+
+    primary_repo = _primary_repo_from_common_dir(target_common_dir)
+    current_registry = _resolve_path(resolved_project / ".loopx" / "registry.json")
+    candidates: list[dict[str, Any]] = []
+    for goal in registry_goals(payload):
+        candidate_goal_id = str(goal.get("id") or "")
+        if goal_id and candidate_goal_id != goal_id:
+            continue
+        source_repo = _source_repo_for_goal(goal)
+        if source_repo is None:
+            continue
+        source_common_dir = _git_common_dir(source_repo)
+        if not _same_path(source_common_dir, target_common_dir):
+            continue
+        source_registry_value = goal.get("source_registry")
+        source_registry = _resolve_path(Path(str(source_registry_value))) if source_registry_value else None
+        candidates.append(
+            {
+                "goal_id": candidate_goal_id,
+                "source_repo": str(source_repo),
+                "source_registry": str(source_registry) if source_registry else None,
+                "source_is_primary_repo": _same_path(source_repo, primary_repo),
+                "source_is_current_project": _same_path(source_repo, resolved_project),
+                "source_registry_is_current_project": _same_path(source_registry, current_registry),
+            }
+        )
+
+    if not candidates:
+        return {
+            "applied": False,
+            "kind": "none",
+            "input_project": str(resolved_project),
+            "global_registry": str(global_path),
+            "git_common_dir": str(target_common_dir),
+            "primary_repo": str(primary_repo) if primary_repo else None,
+            "reason": "no global source_registry shares this git common-dir",
+        }
+
+    if any(item["source_registry_is_current_project"] for item in candidates):
+        current_ids = [
+            str(item["goal_id"])
+            for item in candidates
+            if item["source_registry_is_current_project"] and item.get("goal_id")
+        ]
+        non_current_primary = [
+            item
+            for item in candidates
+            if item["source_is_primary_repo"] and not item["source_registry_is_current_project"]
+        ]
+        if not non_current_primary:
+            return {
+                "applied": False,
+                "kind": "current_project_is_registered_source",
+                "input_project": str(resolved_project),
+                "global_registry": str(global_path),
+                "git_common_dir": str(target_common_dir),
+                "primary_repo": str(primary_repo) if primary_repo else None,
+                "registered_goal_ids": current_ids,
+                "reason": "current project already owns a registered source_registry route",
+            }
+
+    def rank(item: dict[str, Any]) -> tuple[int, int, int, str]:
+        return (
+            0 if item["source_is_primary_repo"] else 1,
+            0 if not item["source_is_current_project"] else 1,
+            0 if item.get("source_registry") else 1,
+            str(item.get("source_registry") or item.get("source_repo") or ""),
+        )
+
+    selected = sorted(candidates, key=rank)[0]
+    selected_repo = Path(str(selected["source_repo"]))
+    if _same_path(selected_repo, resolved_project):
+        return {
+            "applied": False,
+            "kind": "selected_current_project",
+            "input_project": str(resolved_project),
+            "global_registry": str(global_path),
+            "git_common_dir": str(target_common_dir),
+            "primary_repo": str(primary_repo) if primary_repo else None,
+            "candidate_goal_ids": sorted({str(item["goal_id"]) for item in candidates if item.get("goal_id")}),
+            "reason": "best global route is the current project",
+        }
+
+    return {
+        "applied": True,
+        "kind": "git_worktree_canonical_source_registry",
+        "input_project": str(resolved_project),
+        "canonical_project": str(selected_repo),
+        "global_registry": str(global_path),
+        "git_common_dir": str(target_common_dir),
+        "primary_repo": str(primary_repo) if primary_repo else None,
+        "source_registry": selected.get("source_registry"),
+        "candidate_goal_ids": sorted({str(item["goal_id"]) for item in candidates if item.get("goal_id")}),
+        "selected_goal_id": selected.get("goal_id"),
+        "reason": "project is a git worktree; reusing canonical source_registry route",
+    }