@event4u/agent-config 1.41.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.41.2",
+    "version": "2.1.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,
@@ -16,7 +16,6 @@
         ".agent-src/",
         ".augment-plugin/",
         ".claude-plugin/",
-        "bin/",
         "config/",
         "docs/",
         "scripts/",
@@ -26,15 +25,11 @@
         "CONTRIBUTING.md",
         "LICENSE",
         "README.md",
-        "composer.json",
         "llms.txt"
     ],
     "bin": {
         "agent-config": "scripts/agent-config"
     },
-    "scripts": {
-        "postinstall": "bash scripts/postinstall.sh"
-    },
     "publishConfig": {
         "access": "public",
         "provenance": true

package/scripts/_cli/cmd_migrate.py

@@ -0,0 +1,270 @@
+"""``agent-config migrate`` — one-shot migration off legacy install paths.
+
+P3.5/P3.6 of road-to-portable-runtime-and-update-check.md. Migrates a
+consumer project from the legacy composer / npm install paths onto
+the ``npx``-only runtime described in ``docs/architecture.md``.
+
+Steps performed (idempotent):
+
+1. Detect legacy install signals (composer.json entry, package.json
+   devDependency, in-project symlinks pointing at vendor/ or
+   node_modules/).
+2. Remove the package entry from composer.json / package.json
+   in-place, preserving sibling keys + formatting.
+3. Delete agent-config managed symlinks that point inside the legacy
+   install dirs. User-added links elsewhere are preserved with a
+   warning.
+4. Write a fresh ``.agent-settings.yml`` (only if missing) with
+   ``agent_config_version`` pinned to the running version.
+5. Update the consumer's ``.gitignore`` block (legacy paths out, new
+   project-scope entries in).
+6. Print a summary so the developer can review + commit.
+
+Re-runs on an already-migrated repo emit ``already migrated`` and
+exit 0.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Iterable, Optional
+
+PACKAGE_NAME_NPM = "@event4u/agent-config"
+PACKAGE_NAME_COMPOSER = "event4u/agent-config"
+LEGACY_DIRS = ("vendor", "node_modules")
+MANAGED_SYMLINKS = (
+    ".augment",
+    ".claude",
+    ".cursor",
+    ".clinerules",
+    ".windsurfrules",
+)
+GITIGNORE_BLOCK_START = "# >>> event4u/agent-config (managed) >>>"
+GITIGNORE_BLOCK_END = "# <<< event4u/agent-config (managed) <<<"
+GITIGNORE_NEW_BODY = (
+    ".agent-settings.yml\n"
+    "agents/sessions/\n"
+    "agents/council-responses/\n"
+    "agents/council-sessions/\n"
+)
+
+
+def _detect_npm(pkg_json: Path) -> bool:
+    if not pkg_json.is_file():
+        return False
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    for key in ("dependencies", "devDependencies"):
+        section = data.get(key) or {}
+        if isinstance(section, dict) and PACKAGE_NAME_NPM in section:
+            return True
+    return False
+
+
+def _detect_composer(composer_json: Path) -> bool:
+    if not composer_json.is_file():
+        return False
+    try:
+        data = json.loads(composer_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    for key in ("require", "require-dev"):
+        section = data.get(key) or {}
+        if isinstance(section, dict) and PACKAGE_NAME_COMPOSER in section:
+            return True
+    return False
+
+
+def _strip_npm_entry(pkg_json: Path) -> bool:
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    changed = False
+    for key in ("dependencies", "devDependencies"):
+        section = data.get(key)
+        if isinstance(section, dict) and PACKAGE_NAME_NPM in section:
+            del section[PACKAGE_NAME_NPM]
+            changed = True
+            if not section:
+                del data[key]
+    if changed:
+        pkg_json.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return changed
+
+
+def _strip_composer_entry(composer_json: Path) -> bool:
+    try:
+        data = json.loads(composer_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    changed = False
+    for key in ("require", "require-dev"):
+        section = data.get(key)
+        if isinstance(section, dict) and PACKAGE_NAME_COMPOSER in section:
+            del section[PACKAGE_NAME_COMPOSER]
+            changed = True
+            if not section:
+                del data[key]
+    if changed:
+        composer_json.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return changed
+
+
+def _classify_symlink(link: Path) -> Optional[str]:
+    """Return 'legacy' if the link points into vendor/ or node_modules/, 'user' otherwise."""
+    if not link.is_symlink():
+        return None
+    try:
+        target = Path(link.readlink()) if hasattr(link, "readlink") else Path(link.resolve())
+    except OSError:
+        return None
+    target_str = str(target)
+    if any(seg in target_str.split("/") for seg in LEGACY_DIRS):
+        return "legacy"
+    return "user"
+
+
+def _purge_legacy_symlinks(project: Path) -> tuple[list[str], list[str]]:
+    removed: list[str] = []
+    preserved: list[str] = []
+    for name in MANAGED_SYMLINKS:
+        link = project / name
+        kind = _classify_symlink(link)
+        if kind == "legacy":
+            try:
+                link.unlink()
+                removed.append(name)
+            except OSError:
+                preserved.append(name)
+        elif kind == "user":
+            preserved.append(name)
+    return removed, preserved
+
+
+def _write_settings(project: Path, version: str) -> bool:
+    settings = project / ".agent-settings.yml"
+    if settings.exists():
+        return False
+    body = (
+        "# .agent-settings.yml — generated by `agent-config migrate`.\n"
+        "# See docs/customization.md for the full key reference.\n"
+        f'agent_config_version: "{version}"\n'
+    )
+    settings.write_text(body, encoding="utf-8")
+    try:
+        settings.chmod(0o644)
+    except OSError:
+        pass
+    return True
+
+
+def _update_gitignore(project: Path) -> bool:
+    gitignore = project / ".gitignore"
+    block = (
+        f"{GITIGNORE_BLOCK_START}\n"
+        f"{GITIGNORE_NEW_BODY}"
+        f"{GITIGNORE_BLOCK_END}\n"
+    )
+    if not gitignore.exists():
+        gitignore.write_text(block, encoding="utf-8")
+        return True
+
+    text = gitignore.read_text(encoding="utf-8")
+    pattern = re.compile(
+        re.escape(GITIGNORE_BLOCK_START) + r".*?" + re.escape(GITIGNORE_BLOCK_END) + r"\n?",
+        re.DOTALL,
+    )
+    if pattern.search(text):
+        new_text = pattern.sub(block, text)
+    else:
+        new_text = text
+        if new_text and not new_text.endswith("\n"):
+            new_text += "\n"
+        new_text += block
+    if new_text == text:
+        return False
+    gitignore.write_text(new_text, encoding="utf-8")
+    return True
+
+
+def _detect_already_migrated(project: Path) -> bool:
+    """A repo counts as migrated when no legacy signal remains."""
+    if _detect_npm(project / "package.json"):
+        return False
+    if _detect_composer(project / "composer.json"):
+        return False
+    for name in MANAGED_SYMLINKS:
+        if _classify_symlink(project / name) == "legacy":
+            return False
+    return True
+
+
+def main(
+    argv: Optional[list[str]] = None,
+    *,
+    cwd: Optional[Path] = None,
+    version: Optional[str] = None,
+    out=sys.stdout,
+    err=sys.stderr,  # noqa: ARG001 — reserved for future error paths
+) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config migrate",
+        description="One-shot migration off legacy composer / npm install paths.",
+    )
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Detect only; do not write any files.")
+    args = parser.parse_args(argv)
+
+    project = (cwd or Path.cwd()).resolve()
+    version = version or _detect_installed_version()
+
+    if _detect_already_migrated(project):
+        print("✅  already migrated — nothing to do.", file=out)
+        return 0
+
+    if args.dry_run:
+        print("ℹ️  legacy install detected — re-run without --dry-run to migrate.", file=out)
+        return 0
+
+    summary: list[str] = []
+    if _strip_npm_entry(project / "package.json"):
+        summary.append(f"removed {PACKAGE_NAME_NPM} from package.json")
+    if _strip_composer_entry(project / "composer.json"):
+        summary.append(f"removed {PACKAGE_NAME_COMPOSER} from composer.json")
+    removed_links, preserved_links = _purge_legacy_symlinks(project)
+    for name in removed_links:
+        summary.append(f"removed legacy symlink {name}")
+    for name in preserved_links:
+        summary.append(f"preserved user-managed {name} (review manually)")
+    if _write_settings(project, version):
+        summary.append(f".agent-settings.yml written (pinned to {version})")
+    if _update_gitignore(project):
+        summary.append(".gitignore agent-config block refreshed")
+
+    print("✅  migration complete:", file=out)
+    for line in summary:
+        print(f"    - {line}", file=out)
+    print("\n    Next: review the diff and commit.", file=out)
+    return 0
+
+
+def _detect_installed_version() -> str:
+    pkg_json = Path(__file__).resolve().parents[2] / "package.json"
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+        version = data.get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    except (OSError, ValueError, json.JSONDecodeError):
+        pass
+    return "0.0.0"
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/_cli/cmd_update.py

@@ -0,0 +1,226 @@
+"""``agent-config update`` — explicit, opt-in update of the version pin.
+
+Phase 3 of road-to-portable-runtime-and-update-check (P3.1). The
+command is the only user-driven path that flips
+``agent_config_version`` in ``.agent-settings.yml``; the daily banner
+(P2) never writes settings files.
+
+Flags:
+
+* ``--check`` — print the available latest version + return; no write.
+* ``--to <version>`` — pin to an exact version (registry-existence
+  checked). Downgrades are allowed; the pin is a project decision.
+* (no flag) — pin to the registry's ``latest`` tag.
+
+Write target: the **deepest** ``.agent-settings.yml`` in the project
+cascade that already carries the ``agent_config_version`` key. When no
+file carries it, the repo-root file is created/edited. Comments and
+key ordering are preserved by line-based substitution.
+
+The npx cache is warmed via
+``npx --yes @event4u/agent-config@<new> --version`` so the next
+invocation is offline-fast. The P2 state file is refreshed in
+lockstep — the new ``installed_version`` is recorded so the banner
+does not yell about the old pin.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from scripts._lib import update_check
+from scripts._lib.agent_settings import (
+    DEFAULT_PROJECT_FILE,
+    _resolve_cascade_paths,
+    find_project_root,
+)
+
+PACKAGE_NAME = "@event4u/agent-config"
+PIN_KEY = "agent_config_version"
+REGISTRY_VERSION_URL = f"https://registry.npmjs.org/{PACKAGE_NAME}/{{version}}"
+PIN_LINE_RE = re.compile(r"^(\s*agent_config_version\s*:\s*)(.*)$")
+
+
+def _normalize(version: str) -> str:
+    return version.strip().lstrip("v")
+
+
+def _registry_has_version(version: str, *, timeout: float = 1.0) -> bool:
+    url = REGISTRY_VERSION_URL.format(version=_normalize(version))
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            return resp.status == 200
+    except (urllib.error.URLError, TimeoutError, OSError):
+        return False
+
+
+def _find_pin_file(cwd: Path) -> Path:
+    """Return the deepest cascade file that carries the pin, else repo root."""
+    cascade = _resolve_cascade_paths(cwd, None)
+    for path in reversed(cascade):
+        if path.is_file() and _read_pin_line(path) is not None:
+            return path
+    # No file carries it — pick the repo-root cascade entry (shallowest).
+    if cascade:
+        return cascade[0]
+    return cwd / DEFAULT_PROJECT_FILE
+
+
+def _read_pin_line(path: Path) -> Optional[int]:
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            for idx, line in enumerate(fh):
+                if PIN_LINE_RE.match(line):
+                    return idx
+    except OSError:
+        return None
+    return None
+
+
+def _write_pin(path: Path, new_version: str) -> bool:
+    """Rewrite the pin in ``path``; return ``True`` if the file changed."""
+    target = f'agent_config_version: "{_normalize(new_version)}"\n'
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+    except FileNotFoundError:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(target, encoding="utf-8")
+        return True
+    for idx, line in enumerate(lines):
+        if PIN_LINE_RE.match(line):
+            if lines[idx] == target:
+                return False
+            lines[idx] = target
+            path.write_text("".join(lines), encoding="utf-8")
+            return True
+    # File exists but has no pin line — append at end.
+    if lines and not lines[-1].endswith("\n"):
+        lines.append("\n")
+    lines.append(target)
+    path.write_text("".join(lines), encoding="utf-8")
+    return True
+
+
+def _warm_npx_cache(version: str, *, runner=subprocess.run) -> None:
+    try:
+        runner(
+            ["npx", "--yes", f"{PACKAGE_NAME}@{_normalize(version)}", "--version"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=120,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+def _refresh_state(installed: str, latest: str, state_path: Path) -> None:
+    state = update_check._read_state(state_path)
+    payload = {
+        "last_check_utc": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "last_seen_version": latest,
+        "installed_version": installed,
+    }
+    state.update(payload)
+    try:
+        update_check._write_state(state_path, state)
+    except OSError:
+        pass
+
+
+def main(
+    argv: Optional[list[str]] = None,
+    *,
+    cwd: Optional[Path] = None,
+    installed_version: Optional[str] = None,
+    fetcher=update_check.fetch_latest_from_npm,
+    version_checker=_registry_has_version,
+    cache_warmer=_warm_npx_cache,
+    state_path: Optional[Path] = None,
+    out=sys.stdout,
+    err=sys.stderr,
+) -> int:
+    """Entry point. ``scripts/agent-config`` dispatches here."""
+    parser = argparse.ArgumentParser(
+        prog="agent-config update",
+        description="Update the agent_config_version pin in .agent-settings.yml.",
+    )
+    parser.add_argument("--check", action="store_true",
+                        help="Print the latest available version and exit. No file is written.")
+    parser.add_argument("--to", metavar="VERSION",
+                        help="Pin to an explicit version (registry-existence checked).")
+    args = parser.parse_args(argv)
+
+    cwd = (cwd or Path.cwd()).resolve()
+    installed_version = installed_version or _detect_installed_version()
+    state_path = state_path or update_check.DEFAULT_STATE_PATH
+
+    if args.to:
+        target = _normalize(args.to)
+        if not version_checker(target):
+            print(
+                f"❌  agent-config: version {target} not found on the npm registry.",
+                file=err,
+            )
+            return 1
+        latest = target
+    else:
+        latest = fetcher()
+        if not latest:
+            print(
+                "❌  agent-config: failed to fetch latest version from the npm registry.",
+                file=err,
+            )
+            return 1
+        latest = _normalize(latest)
+
+    if args.check:
+        if update_check._is_newer(latest, installed_version):
+            print(f"agent-config {latest} available (you have {installed_version}).", file=out)
+            print(f"Update: npx {PACKAGE_NAME} update", file=out)
+        else:
+            print(f"agent-config is up to date ({installed_version}).", file=out)
+        return 0
+
+    pin_file = _find_pin_file(cwd)
+    changed = _write_pin(pin_file, latest)
+    try:
+        rel = pin_file.relative_to(cwd)
+    except ValueError:
+        rel = pin_file
+
+    if changed:
+        print(f"✅  Pinned {PACKAGE_NAME} to {latest} in {rel}.", file=out)
+    else:
+        print(f"ℹ️  {rel} already pins to {latest}.", file=out)
+
+    cache_warmer(latest)
+    _refresh_state(latest, latest, state_path)
+    return 0
+
+
+def _detect_installed_version() -> str:
+    """Read ``version`` from the package's own ``package.json``."""
+    pkg_json = Path(__file__).resolve().parents[2] / "package.json"
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+        version = data.get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    except (OSError, ValueError, json.JSONDecodeError):
+        pass
+    return "0.0.0"
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())
+