@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/_lib/linked_projects.py

@@ -1,238 +0,0 @@
-"""Detect IDE-attached sibling projects (linked-projects scope, Option A).
-
-Pure, dependency-free detector. Reads on-disk IDE config the developer already
-created by attaching a sibling repo, and returns the sibling project roots that
-sit *outside* the current project. Config-driven only — never guesses from
-arbitrary adjacent directories.
-
-Sources:
-  * PhpStorm / IntelliJ  — ``.idea/modules.xml`` (``<module fileurl>``) and
-    ``.idea/vcs.xml`` (``<mapping directory>``).
-  * VS Code              — ``*.code-workspace`` (``folders[].path``).
-
-Guardrails (per the linked-projects council, Option A):
-  * a candidate must resolve OUTSIDE the project root, exist, and contain a
-    ``.git/`` directory;
-  * a candidate whose file count exceeds ``max_files`` (default 20000) is
-    **flagged** ``large: true`` — NOT excluded. Under Option A the agent only
-    carries a passive awareness note and never bulk-includes sibling files, so
-    repo size is cost-irrelevant to detection; a real frontend repo routinely
-    exceeds 20000 files (excluding node_modules) and must still be surfaced.
-    The flag lets the awareness note say "large repo — check targeted impact,
-    do not scan the whole tree";
-  * the bloat directories ``node_modules``/``.git``/``dist``/``build``/
-    ``.venv``/``target`` are never descended into while counting.
-
-The detector returns awareness candidates; it does NOT include any sibling
-files in context and does NOT persist anything. Opt-in + persistence is the
-caller's job.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import re
-import xml.etree.ElementTree as ET
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-#: File-count ceiling above which a sibling is skipped (token-blowup guard).
-DEFAULT_MAX_FILES = 20000
-
-#: Directories never descended into while counting a sibling's size.
-SKIP_DIRS: frozenset[str] = frozenset(
-    {"node_modules", ".git", "dist", "build", ".venv", "target", ".idea"}
-)
-
-
-def detect_linked_projects(
-    project_root: Path | str,
-    *,
-    max_files: int = DEFAULT_MAX_FILES,
-) -> list[dict[str, Any]]:
-    """Return IDE-attached sibling projects outside ``project_root``.
-
-    Each entry is ``{"path": <absolute str>, "detected_via": <source>,
-    "large": <bool>}`` where source is one of ``phpstorm_modules`` /
-    ``phpstorm_vcs`` / ``vscode_workspace`` and ``large`` is true when the
-    sibling's file count (excluding bloat dirs) exceeds ``max_files``. Results
-    are de-duplicated by resolved path (first source wins) and sorted by path.
-    Size never excludes — see the module docstring.
-    """
-    root = Path(project_root).resolve()
-    if not root.is_dir():
-        logger.info("linked_projects: project_root %s is not a directory", root)
-        return []
-
-    candidates: list[tuple[Path, str]] = []
-    candidates.extend((p, "phpstorm_modules") for p in _phpstorm_modules(root))
-    candidates.extend((p, "phpstorm_vcs") for p in _phpstorm_vcs(root))
-    candidates.extend((p, "vscode_workspace") for p in _vscode_workspace(root))
-
-    seen: set[Path] = set()
-    out: list[dict[str, Any]] = []
-    for path, source in candidates:
-        try:
-            resolved = path.resolve()
-        except OSError:
-            logger.info("linked_projects: cannot resolve %s", path)
-            continue
-        if resolved in seen:
-            continue
-        if not _is_valid_sibling(resolved, root):
-            continue
-        large = _exceeds_size(resolved, max_files)
-        if large:
-            logger.info(
-                "linked_projects: %s exceeds %d files — flagged large (awareness only)",
-                resolved,
-                max_files,
-            )
-        seen.add(resolved)
-        out.append(
-            {"path": str(resolved), "detected_via": source, "large": large}
-        )
-
-    out.sort(key=lambda e: e["path"])
-    return out
-
-
-def _is_valid_sibling(candidate: Path, root: Path) -> bool:
-    """A sibling must be outside the project root, exist, and be a git repo."""
-    try:
-        if candidate == root or root in candidate.parents:
-            return False  # inside the project — that's the module system's job
-        if candidate in root.parents:
-            return False  # an ancestor of the project, not a sibling
-        if not candidate.is_dir():
-            logger.info("linked_projects: candidate missing/not-a-dir %s", candidate)
-            return False
-        if not (candidate / ".git").exists():
-            logger.info("linked_projects: candidate not a git repo %s", candidate)
-            return False
-    except OSError:
-        logger.info("linked_projects: unreadable candidate %s", candidate)
-        return False
-    return True
-
-
-def _exceeds_size(candidate: Path, max_files: int) -> bool:
-    """True if the tree (minus SKIP_DIRS) holds more than ``max_files`` files."""
-    import os
-
-    count = 0
-    for dirpath, dirnames, filenames in os.walk(candidate):
-        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
-        count += len(filenames)
-        if count > max_files:
-            return True
-    return False
-
-
-def _phpstorm_modules(root: Path) -> list[Path]:
-    """Sibling roots from ``.idea/modules.xml`` ``<module fileurl>`` entries."""
-    path = root / ".idea" / "modules.xml"
-    elems = _iter_xml_attrs(path, "module", ("fileurl", "filepath"))
-    out: list[Path] = []
-    for attrs in elems:
-        raw = attrs.get("fileurl") or attrs.get("filepath")
-        if not raw:
-            continue
-        resolved = _resolve_idea_url(raw, root)
-        if resolved is None:
-            continue
-        # raw points at <sibling>/.idea/<name>.iml → sibling is .idea's parent.
-        if resolved.parent.name == ".idea":
-            out.append(resolved.parent.parent)
-        else:
-            out.append(resolved)
-    return out
-
-
-def _phpstorm_vcs(root: Path) -> list[Path]:
-    """Sibling roots from ``.idea/vcs.xml`` ``<mapping directory>`` entries."""
-    path = root / ".idea" / "vcs.xml"
-    out: list[Path] = []
-    for attrs in _iter_xml_attrs(path, "mapping", ("directory",)):
-        raw = attrs.get("directory")
-        if not raw:
-            continue
-        resolved = _resolve_idea_url(raw, root)
-        if resolved is not None:
-            out.append(resolved)
-    return out
-
-
-def _vscode_workspace(root: Path) -> list[Path]:
-    """Sibling roots from ``*.code-workspace`` ``folders[].path`` entries."""
-    out: list[Path] = []
-    try:
-        workspaces = sorted(root.glob("*.code-workspace"))
-    except OSError:
-        return out
-    for ws in workspaces:
-        data = _read_jsonc(ws)
-        if not isinstance(data, dict):
-            continue
-        folders = data.get("folders")
-        if not isinstance(folders, list):
-            continue
-        for folder in folders:
-            if not isinstance(folder, dict):
-                continue
-            rel = folder.get("path")
-            if not isinstance(rel, str) or not rel.strip():
-                continue
-            out.append((root / rel).resolve())
-    return out
-
-
-def _resolve_idea_url(raw: str, root: Path) -> Path | None:
-    """Resolve a PhpStorm path token to an absolute Path, or None."""
-    value = raw.strip()
-    if value.startswith("file://"):
-        value = value[len("file://") :]
-    value = value.replace("$PROJECT_DIR$", str(root))
-    if not value:
-        return None
-    try:
-        return (Path(value) if Path(value).is_absolute() else root / value).resolve()
-    except OSError:
-        return None
-
-
-def _iter_xml_attrs(
-    path: Path, tag: str, _attrs: tuple[str, ...]
-) -> list[dict[str, str]]:
-    """Return the attribute dicts of every ``<tag>`` in ``path`` (tolerant)."""
-    if not path.is_file():
-        return []
-    try:
-        tree = ET.parse(path)
-    except (ET.ParseError, OSError) as exc:
-        logger.info("linked_projects: malformed/unreadable %s (%s)", path, exc)
-        return []
-    return [dict(el.attrib) for el in tree.iter(tag)]
-
-
-def _read_jsonc(path: Path) -> Any:
-    """Parse JSON that may carry ``//`` comments and trailing commas (VS Code)."""
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
-        return None
-    try:
-        return json.loads(text)
-    except json.JSONDecodeError:
-        pass
-    # tolerant fallback: strip line comments + trailing commas, retry once.
-    stripped = re.sub(r"^\s*//.*$", "", text, flags=re.MULTILINE)
-    stripped = re.sub(r",(\s*[}\]])", r"\1", stripped)
-    try:
-        return json.loads(stripped)
-    except json.JSONDecodeError as exc:
-        logger.info("linked_projects: malformed workspace JSON %s (%s)", path, exc)
-        return None

package/src/scripts/_lib/model_tier.py

@@ -1,52 +0,0 @@
-"""Shared `model_tier` → native Claude `model:` mapping (ADR-034 / ADR-035).
-
-Single source of truth for the tier→model rewrite, used by **both** render
-paths so they can never drift:
-
-- the repo generator (`condense.py generate_claude_skills`), which builds the
-  package's own `.claude/skills/` tree, and
-- the consumer install finalizer (`install.py finalize_claude_model_tiers`),
-  which rewrites the installed `.claude/skills/` tree so Claude Code performs
-  the per-turn model switch on a consumer with `model.auto_switch: auto`.
-
-Only `auto` triggers the rewrite — `suggest` / `off` keep skills as pure
-symlinks so the package never silently overrides a user's explicit `/model`
-choice. A skill with `model_tier: inherit` (or no `model_tier`) is never
-rewritten.
-"""
-from __future__ import annotations
-
-import re
-from pathlib import Path
-from typing import Optional
-
-# Tier → Claude model. The ONLY per-vendor mapping the package maintains
-# (ADR-035 § 3); other agents resolve the tier band to their own line-up.
-TIER_TO_CLAUDE_MODEL = {"high": "opus", "medium": "sonnet", "lite": "haiku"}
-
-# Matches a `model_tier: <tier>` frontmatter line (quoted or bare).
-MODEL_TIER_RE = re.compile(r'^model_tier:\s*"?([a-z]+)"?\s*$', re.MULTILINE)
-
-
-def read_model_tier(skill_md: Path) -> Optional[str]:
-    """Return the `model_tier` frontmatter value, or None if absent/unparsable."""
-    if not skill_md.exists():
-        return None
-    text = skill_md.read_text(encoding="utf-8", errors="replace")
-    if not text.startswith("---\n"):
-        return None
-    end = text.find("\n---\n", 4)
-    if end == -1:
-        return None
-    m = MODEL_TIER_RE.search(text[4:end])
-    return m.group(1) if m else None
-
-
-def render_native_model_md(text: str, tier: str) -> str:
-    """Rewrite the first `model_tier: <tier>` line to native `model: <mapped>`.
-
-    The rest of the SKILL.md stays byte-identical. `tier` must be a key of
-    :data:`TIER_TO_CLAUDE_MODEL` (callers gate on that).
-    """
-    model = TIER_TO_CLAUDE_MODEL[tier]
-    return MODEL_TIER_RE.sub(f"model: {model}", text, count=1)

package/src/scripts/_lib/module_detection.py

@@ -1,223 +0,0 @@
-"""Detect module root directories from a project tree.
-
-Phase B of road-to-configurable-modules. Lifts the multi-stack
-detection table from ``commands/module/explore.md`` Step 1 into a
-reusable, pure Python helper that the installer, onboarding wizard,
-and ``/agents init`` flow all share.
-
-Contract — pure, read-only, tolerant:
-
-* :func:`detect_module_roots` walks the candidate paths once and
-  reports every directory that *exists*. It never creates files,
-  never recurses past the first level needed to score confidence,
-  and silently skips paths it cannot read.
-* The return shape is a list of :class:`ModuleCandidate` typed
-  dicts ordered by descending confidence; callers may turn that
-  list straight into numbered options.
-* Confidence is a three-step ladder:
-
-  - ``high`` — directory exists *and* its first level contains
-    plausible module subdirectories for the stack.
-  - ``medium`` — directory exists but is empty / unclear; still
-    surfaced so the installer can ask the user.
-  - Absent paths are skipped entirely; they never appear in the
-    output.
-
-No interactive logic, no settings I/O, no logging side-effects.
-Settings wiring lives in ``scripts/install.py`` (Step 2) and the
-GUI wizard (Step 3).
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Iterable
-
-#: Directory entry names that never count as modules. Mirrors the
-#: ``modules.skip_dirs`` default from
-#: ``templates/agents/agent-project-settings.example.yml``.
-_SKIP_DIRS: frozenset[str] = frozenset({
-    ".module-template",
-    ".example",
-})
-
-#: Path segments that exclude a file from module-like detection.
-#: Vendored dependencies, build artefacts, VCS state, IDE config —
-#: never a real module no matter what shape the parent directory has.
-_NOISE_SEGMENTS: frozenset[str] = frozenset({
-    "vendor",
-    "node_modules",
-    ".git",
-    ".idea",
-    ".vscode",
-    "dist",
-    "build",
-    "tmp",
-    "var",
-    "storage",
-    "bootstrap",
-    "public",
-    ".venv",
-    "venv",
-    "__pycache__",
-})
-
-#: Parent directory names that hint at a module layout when their
-#: immediate child is a non-noise segment (i.e. ``Modules/User/...``,
-#: ``packages/foo/...``). Case-sensitive — ``Modules`` (Laravel HMVC)
-#: differs from ``modules`` (Node convention) intentionally; both are
-#: accepted.
-_MODULE_PARENTS: frozenset[str] = frozenset({
-    "Modules",
-    "modules",
-    "packages",
-    "apps",
-    "internal",
-})
-
-
-def is_module_like_path(rel_path: str) -> bool:
-    """Return ``True`` when ``rel_path`` sits inside a module-shaped tree.
-
-    Heuristic for the ``module-detect-on-the-fly`` skill: triggered by
-    repo-relative POSIX paths the agent is about to edit or reference.
-    A path is *module-like* when:
-
-    1. None of its segments are in :data:`_NOISE_SEGMENTS` (vendored,
-       build, VCS, IDE state — never a real module).
-    2. At least one segment matches :data:`_MODULE_PARENTS` AND has a
-       non-noise sibling directly underneath (so ``Modules/`` alone
-       does not trigger, but ``Modules/User/...`` does).
-
-    Pure, case-sensitive on parent names. Empty / dotted / Windows-style
-    inputs return ``False``. The function never touches the filesystem
-    — callers pass in a path string they already know about.
-    """
-    if not rel_path:
-        return False
-    normalised = rel_path.replace("\\", "/").strip("/")
-    if not normalised:
-        return False
-    parts = normalised.split("/")
-    for segment in parts:
-        if segment in _NOISE_SEGMENTS:
-            return False
-    for idx, segment in enumerate(parts[:-1]):
-        if segment not in _MODULE_PARENTS:
-            continue
-        child = parts[idx + 1]
-        if not child or child.startswith("."):
-            continue
-        if child in _SKIP_DIRS:
-            continue
-        return True
-    return False
-
-
-@dataclass(frozen=True)
-class ModuleCandidate:
-    """One detected module-root candidate.
-
-    Attributes mirror the JSON shape callers ultimately persist into
-    ``modules.root_paths`` (the ``path`` field) plus metadata used
-    by the installer to phrase the numbered-options prompt.
-    """
-
-    path: str
-    """Repo-relative POSIX path of the module root (e.g. ``app/Modules``)."""
-
-    stack: str
-    """Stack identifier — one of ``laravel-hmvc``, ``symfony-ddd``,
-    ``node-monorepo``, ``python-src``, ``go-internal``, ``composer-src``."""
-
-    namespace_template_guess: str
-    """PHP-style namespace template with ``{ModuleName}`` placeholder
-    (e.g. ``App\\Modules\\{ModuleName}``). Empty string for stacks
-    without a PHP-style namespace (Node, Python, Go)."""
-
-    confidence: str
-    """One of ``high`` or ``medium`` per the ladder in the module
-    docstring."""
-
-
-# Detection rules — order encodes priority when two rules match the
-# same directory. ``namespace_template`` is the value emitted as
-# ``namespace_template_guess`` on a hit; empty for non-PHP stacks.
-_RULES: tuple[tuple[str, str, str], ...] = (
-    ("app/Modules", "laravel-hmvc", "App\\Modules\\{ModuleName}"),
-    ("src/Module", "symfony-ddd", "App\\Module\\{ModuleName}"),
-    ("packages", "node-monorepo", ""),
-    ("apps", "node-monorepo", ""),
-    ("modules", "node-monorepo", ""),
-    ("src", "python-src", ""),
-    ("internal", "go-internal", ""),
-    ("cmd", "go-internal", ""),
-)
-
-
-def _list_module_subdirs(root: Path) -> list[Path]:
-    """Return first-level subdirectories of ``root`` that look like modules."""
-    try:
-        entries = sorted(root.iterdir())
-    except (OSError, PermissionError):
-        return []
-    out: list[Path] = []
-    for entry in entries:
-        if not entry.is_dir():
-            continue
-        if entry.name.startswith("."):
-            continue
-        if entry.name in _SKIP_DIRS:
-            continue
-        out.append(entry)
-    return out
-
-
-def _score_confidence(stack: str, subdirs: Iterable[Path]) -> str:
-    """Return ``high`` when ``subdirs`` looks like a populated module root."""
-    subdirs_list = list(subdirs)
-    if not subdirs_list:
-        return "medium"
-    if stack in {"laravel-hmvc", "symfony-ddd"}:
-        capitalized = [d for d in subdirs_list if d.name[:1].isupper()]
-        return "high" if capitalized else "medium"
-    if stack == "node-monorepo":
-        with_pkg_json = [d for d in subdirs_list if (d / "package.json").is_file()]
-        return "high" if with_pkg_json else "medium"
-    if stack == "python-src":
-        with_init = [d for d in subdirs_list if (d / "__init__.py").is_file()]
-        return "high" if with_init else "medium"
-    if stack == "go-internal":
-        return "high" if subdirs_list else "medium"
-    return "medium"
-
-
-def detect_module_roots(project_root: Path) -> list[ModuleCandidate]:
-    """Return module-root candidates discovered under ``project_root``.
-
-    Pure read-only scan. Walks each rule in :data:`_RULES`, reports
-    every directory that exists, and never recurses past the first
-    level needed to score confidence. Order: ``high`` first, then
-    ``medium``; rule order breaks ties. Absent paths never appear
-    in the output.
-    """
-    project_root = Path(project_root)
-    high: list[ModuleCandidate] = []
-    medium: list[ModuleCandidate] = []
-    for rel_path, stack, namespace_template in _RULES:
-        abs_path = project_root / rel_path
-        if not abs_path.is_dir():
-            continue
-        subdirs = _list_module_subdirs(abs_path)
-        confidence = _score_confidence(stack, subdirs)
-        candidate = ModuleCandidate(
-            path=rel_path,
-            stack=stack,
-            namespace_template_guess=namespace_template,
-            confidence=confidence,
-        )
-        if confidence == "high":
-            high.append(candidate)
-        else:
-            medium.append(candidate)
-    return high + medium

package/src/scripts/_lib/pin_resolver.py

@@ -1,152 +0,0 @@
-"""Pin-aware version resolver for the ``agent-config`` dispatcher.
-
-Phase 3 of road-to-portable-runtime-and-update-check (P3.2). The
-dispatcher consults this module **before** doing any work. If
-``.agent-settings.yml`` carries a non-empty ``agent_config_version``
-pin and the currently running package version does not match, the
-process re-execs via ``npx @event4u/agent-config@<pin> <argv>``.
-
-Determinism is the goal: a consumer's ``npx`` cache may resolve to a
-different version than the project pinned to, and the resolver
-guarantees the pinned version is the one that actually runs.
-
-Escape hatch: ``AGENT_CONFIG_NO_PIN_REEXEC=1`` disables the re-exec
-entirely (used for local development of the package itself and for
-the recursion guard described below).
-
-Recursion guard: the parent sets ``AGENT_CONFIG_PIN_REEXEC_DEPTH=1``
-on the child env so the re-exec'd child does not loop if the freshly
-spawned ``npx`` resolves to a still-mismatched version. One re-exec
-per process, full stop.
-"""
-from __future__ import annotations
-
-import os
-import shutil
-import sys
-from pathlib import Path
-from typing import Optional
-
-PACKAGE_NAME = "@event4u/agent-config"
-PIN_KEY = "agent_config_version"
-NO_REEXEC_ENV = "AGENT_CONFIG_NO_PIN_REEXEC"
-REEXEC_DEPTH_ENV = "AGENT_CONFIG_PIN_REEXEC_DEPTH"
-
-
-def _normalize(version: str) -> str:
-    return version.strip().lstrip("v")
-
-
-def read_pin(cwd: Path, *, settings_loader=None) -> Optional[str]:
-    """Return the pinned version from the cascaded settings, or ``None``.
-
-    Empty string and missing key both yield ``None``.
-    """
-    if settings_loader is None:
-        from scripts._lib import agent_settings  # local import (test override)
-
-        settings_loader = agent_settings.load_agent_settings
-
-    try:
-        settings = settings_loader(cwd=cwd)
-    except Exception:
-        return None
-    raw = settings.get(PIN_KEY)
-    if not isinstance(raw, str):
-        return None
-    pin = raw.strip()
-    return pin or None
-
-
-def should_reexec(
-    pin: Optional[str],
-    installed: str,
-    *,
-    env: Optional[dict] = None,
-) -> bool:
-    """Pure predicate: do we need to re-exec under the pinned version?"""
-    env = env if env is not None else os.environ
-    if env.get(NO_REEXEC_ENV) == "1":
-        return False
-    if env.get(REEXEC_DEPTH_ENV) == "1":
-        return False
-    if not pin:
-        return False
-    if not installed:
-        return False
-    return _normalize(pin) != _normalize(installed)
-
-
-def build_reexec_argv(pin: str, argv: list[str]) -> list[str]:
-    """Build the ``npx`` argv that re-execs at the pinned version."""
-    return ["npx", "--yes", f"{PACKAGE_NAME}@{_normalize(pin)}", *argv]
-
-
-def maybe_reexec(
-    installed: str,
-    *,
-    cwd: Optional[Path] = None,
-    argv: Optional[list[str]] = None,
-    env: Optional[dict] = None,
-    runner=None,
-) -> Optional[int]:
-    """Re-exec at the pinned version if needed; return the child exit code.
-
-    Returns ``None`` when no re-exec is performed (caller continues).
-    The injected ``runner`` covers the test path — defaults to
-    :func:`os.execvpe` on real invocations.
-    """
-    cwd = cwd or Path.cwd()
-    argv = argv if argv is not None else sys.argv
-    env = env if env is not None else os.environ
-
-    pin = read_pin(cwd)
-    if not should_reexec(pin, installed, env=env):
-        return None
-
-    assert pin is not None  # narrowed by should_reexec
-    npx = shutil.which("npx")
-    if not npx:
-        # Cannot re-exec without npx — silently fall back to running
-        # the locally-installed version. Better to do something than
-        # to die because of a missing CLI.
-        return None
-
-    new_argv = build_reexec_argv(pin, argv[1:] if argv else [])
-    child_env = dict(env)
-    child_env[REEXEC_DEPTH_ENV] = "1"
-
-    if runner is None:
-        # Replace the current process; never returns on success.
-        os.execvpe(npx, new_argv, child_env)
-        return 1  # unreachable on POSIX
-    return runner(npx, new_argv, child_env)
-
-
-def _parse_cli(argv: list[str]) -> tuple[Path, str, list[str]]:
-    """Parse the dispatcher-facing argv: ``--cwd X --installed Y -- ARGS``."""
-    cwd = Path.cwd()
-    installed = ""
-    forward: list[str] = []
-    i = 0
-    while i < len(argv):
-        token = argv[i]
-        if token == "--cwd" and i + 1 < len(argv):
-            cwd = Path(argv[i + 1])
-            i += 2
-        elif token == "--installed" and i + 1 < len(argv):
-            installed = argv[i + 1]
-            i += 2
-        elif token == "--":
-            forward = argv[i + 1:]
-            break
-        else:
-            i += 1
-    return cwd, installed, forward
-
-
-if __name__ == "__main__":  # pragma: no cover
-    cwd, installed, forward = _parse_cli(sys.argv[1:])
-    # Build the argv the child should see: ``agent-config <forward...>``.
-    child_argv = ["agent-config", *forward]
-    maybe_reexec(installed, cwd=cwd, argv=child_argv)