@event4u/agent-config 6.0.0 → 7.0.0

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)

package/src/scripts/_lib/script_output.py

@@ -1,144 +0,0 @@
-"""Verbosity-aware print router for scripts/*.py.
-
-Phase 10 of road-to-token-frugality. Single source of truth for how
-maintenance scripts emit progress, success, warnings, and errors.
-
-Resolution order (first wins):
-  1. AGENT_SCRIPT_VERBOSITY env var      (silent | minimal | verbose)
-  2. SCRIPT_OUTPUT_VERBOSE=1 alias       (== verbose)
-  3. .agent-settings.yml verbosity.script_output
-  4. Default: minimal
-
-Once resolved, the level is exported back into AGENT_SCRIPT_VERBOSITY
-so child processes inherit the same level (Phase 10.1c). Explicit
---quiet flags on the child still win at the call site.
-
-Levels:
-  silent   = stderr only; success() drops; info() drops; warn() drops
-  minimal  = success() collapsed to one end-of-run summary; info() drops
-  verbose  = pre-Phase-10 behaviour, every call prints
-
-error() always writes to stderr regardless of level. Iron-Law surfaces
-(release confirms, install secrets prompts) bypass this module and use
-plain print() so they cannot be silenced.
-"""
-from __future__ import annotations
-
-import os
-import sys
-from pathlib import Path
-from typing import Final
-
-VALID_LEVELS: Final[tuple[str, ...]] = ("silent", "minimal", "verbose")
-DEFAULT_LEVEL: Final[str] = "minimal"
-ENV_VAR: Final[str] = "AGENT_SCRIPT_VERBOSITY"
-ENV_ALIAS: Final[str] = "SCRIPT_OUTPUT_VERBOSE"
-SETTINGS_FILE: Final[str] = ".agent-settings.yml"
-
-_resolved_level: str | None = None
-_pending_summary: list[str] = []
-
-
-def _read_settings_level(settings_path: Path) -> str | None:
-    """Read verbosity.script_output from .agent-settings.yml.
-
-    Returns None when the file is missing, PyYAML is unavailable, or
-    the key is absent. Errors fall through to the default level. Goes
-    through the centralized loader (road-to-portable-dev-preferences P3)
-    so the tolerance contract — missing file, malformed YAML, no PyYAML
-    — degrades uniformly across scripts. ``verbosity.script_output`` is
-    not on the user-global whitelist, so a value there is silently
-    ignored; the project file is the only source for this knob.
-    """
-    # Lazy import — supports both `python3 scripts/foo.py` (sys.path
-    # contains scripts/) and `pytest` (scripts._lib is a proper package).
-    try:
-        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]  # noqa: PLC0415
-    except ImportError:
-        from scripts._lib.agent_settings import (  # noqa: PLC0415
-            load_agent_settings,
-        )
-
-    data = load_agent_settings(project_path=settings_path)
-    section = data.get("verbosity")
-    if not isinstance(section, dict):
-        return None
-    value = section.get("script_output")
-    if isinstance(value, str) and value in VALID_LEVELS:
-        return value
-    return None
-
-
-def resolve_level(settings_path: Path | None = None) -> str:
-    """Resolve and cache the active verbosity level.
-
-    First call wins; subsequent calls return the cached value so the
-    process is internally consistent. Tests reset via reset_level().
-    """
-    global _resolved_level
-    if _resolved_level is not None:
-        return _resolved_level
-
-    env_value = os.environ.get(ENV_VAR, "").strip().lower()
-    if env_value in VALID_LEVELS:
-        _resolved_level = env_value
-    elif os.environ.get(ENV_ALIAS, "").strip() == "1":
-        _resolved_level = "verbose"
-    else:
-        path = settings_path or Path(SETTINGS_FILE)
-        _resolved_level = _read_settings_level(path) or DEFAULT_LEVEL
-
-    # Inheritance: export resolved level so child processes see it.
-    os.environ[ENV_VAR] = _resolved_level
-    return _resolved_level
-
-
-def reset_level() -> None:
-    """Clear the cached level. Test helper."""
-    global _resolved_level
-    _resolved_level = None
-    _pending_summary.clear()
-
-
-def info(message: str) -> None:
-    """Per-step progress note. Drops at silent + minimal."""
-    if resolve_level() == "verbose":
-        print(message)
-
-
-def success(message: str) -> None:
-    """Per-step success. At minimal collected for end-of-run summary;
-    at verbose printed immediately; at silent dropped."""
-    level = resolve_level()
-    if level == "verbose":
-        print(message)
-    elif level == "minimal":
-        _pending_summary.append(message)
-
-
-def warn(message: str) -> None:
-    """Warning. Stderr at all levels except silent."""
-    if resolve_level() != "silent":
-        print(message, file=sys.stderr)
-
-
-def error(message: str) -> None:
-    """Error. Always stderr regardless of level."""
-    print(message, file=sys.stderr)
-
-
-def flush_summary(headline: str | None = None) -> None:
-    """Emit the pending success() summary at end-of-run.
-
-    No-op at verbose (already printed) and silent (suppressed).
-    Use the explicit `headline` arg to override the auto-pick.
-    """
-    level = resolve_level()
-    if level != "minimal" or not _pending_summary:
-        return
-    if headline:
-        print(headline)
-    else:
-        # Default: print the last collected line as the headline.
-        print(_pending_summary[-1])
-    _pending_summary.clear()

package/src/scripts/_lib/token_count.py

@@ -1,95 +0,0 @@
-#!/usr/bin/env python3
-"""Real-tokenizer counting for the budget tooling (roadmap 0B.1).
-
-`char != token`. Every budget in this suite is historically in characters;
-the lean-initial-context goal is tokens. This helper adds a token count
-*alongside* chars so chars stay the cheap, stdlib-only proxy and tokens
-become the truth where a real tokenizer is available.
-
-Design — no silent installs, no mandatory network (per `missing-tool-handling`):
-
-- **GPT** — exact via `tiktoken` (`o200k_base`, the GPT-4o/4.1 encoding) when
-  the optional dependency is installed; otherwise a documented `chars / 4`
-  proxy flagged `exact=False`. Install `tiktoken` to activate exact counts.
-- **Claude** — no offline tokenizer ships in `anthropic` 0.98 (the SDK exposes
-  only the live `messages.count_tokens` endpoint, which needs an API call).
-  Offline we use a documented `chars / 3.6` proxy flagged `exact=False`; the
-  exact API count is reserved for the live-bench boundaries to avoid spend on
-  the cheap path.
-
-Both proxies are intentionally conservative ratios drawn from English-prose +
-markdown samples; they are estimates, never gates. The char budgets remain the
-enforced floor (`measure_rule_budget --kernel-budget-check`).
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-# Proxy ratios (chars per token) for the no-tokenizer fallback. Tuned for
-# English markdown rule/skill prose; deliberately conservative.
-_GPT_CHARS_PER_TOKEN = 4.0
-_CLAUDE_CHARS_PER_TOKEN = 3.6
-
-_TIKTOKEN_ENCODING = "o200k_base"  # GPT-4o / GPT-4.1 family.
-
-# Resolve the optional tiktoken encoder once at import.
-try:  # pragma: no cover - exercised by env presence, not unit tests
-    import tiktoken  # type: ignore
-
-    _ENC = tiktoken.get_encoding(_TIKTOKEN_ENCODING)
-except Exception:  # ImportError, or model-data fetch failure offline
-    _ENC = None
-
-TIKTOKEN_AVAILABLE = _ENC is not None
-
-
-@dataclass(frozen=True)
-class TokenCount:
-    """A single token measurement and whether it is exact or a proxy."""
-
-    tokens: int
-    exact: bool
-
-
-def gpt_tokens(text: str) -> TokenCount:
-    """GPT token count — exact via tiktoken when present, else a char proxy."""
-    if _ENC is not None:
-        return TokenCount(len(_ENC.encode(text)), True)
-    return TokenCount(round(len(text) / _GPT_CHARS_PER_TOKEN), False)
-
-
-def claude_tokens(text: str) -> TokenCount:
-    """Claude token count — documented offline proxy (no local tokenizer)."""
-    return TokenCount(round(len(text) / _CLAUDE_CHARS_PER_TOKEN), False)
-
-
-def measure(text: str) -> dict[str, object]:
-    """Return chars + per-model token counts for one text blob.
-
-    Keys: chars, tokens_gpt, tokens_gpt_exact, tokens_claude,
-    tokens_claude_exact. The `*_exact` booleans tell a report consumer
-    whether the number is a real tokenizer count or a proxy estimate.
-    """
-    g = gpt_tokens(text)
-    c = claude_tokens(text)
-    return {
-        "chars": len(text),
-        "tokens_gpt": g.tokens,
-        "tokens_gpt_exact": g.exact,
-        "tokens_claude": c.tokens,
-        "tokens_claude_exact": c.exact,
-    }
-
-
-def method_note() -> str:
-    """One-line provenance of how token counts were produced (for reports)."""
-    if TIKTOKEN_AVAILABLE:
-        return (
-            f"tokens_gpt: exact (tiktoken {_TIKTOKEN_ENCODING}); "
-            f"tokens_claude: proxy (chars/{_CLAUDE_CHARS_PER_TOKEN})"
-        )
-    return (
-        f"tokens_gpt: proxy (chars/{_GPT_CHARS_PER_TOKEN}, tiktoken not installed); "
-        f"tokens_claude: proxy (chars/{_CLAUDE_CHARS_PER_TOKEN})"
-    )