@event4u/agent-config 1.41.2 → 2.1.0

package/scripts/agent-config

@@ -94,6 +94,10 @@ Commands:
                              Usage: council:run <question> --output <path> --confirm
   council:render             Re-render a saved council responses JSON to markdown
                              Usage: council:render <responses.json>
+  update                     Update the agent_config_version pin in .agent-settings.yml
+                             Flags: --check (read-only) | --to <version> (explicit pin)
+  migrate                    One-shot migration off legacy composer / npm install paths
+                             Flags: --dry-run (detect only)
   help                       Show this help
   --version, -V              Print package version
 
@@ -504,6 +508,22 @@ cmd_council() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 "$script" "$sub" "$@"
 }
 
+# `agent-config update` — flip the agent_config_version pin in
+# .agent-settings.yml. See scripts/_cli/cmd_update.py (P3.1 of
+# road-to-portable-runtime-and-update-check.md).
+cmd_update() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_update "$@"
+}
+
+# `agent-config migrate` — one-shot migration off legacy composer / npm
+# install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.py
+# (P3.5 of road-to-portable-runtime-and-update-check.md).
+cmd_migrate() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_migrate "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -542,6 +562,8 @@ main() {
     council:estimate)        cmd_council estimate "$@" ;;
     council:run)             cmd_council run "$@" ;;
     council:render)          cmd_council render "$@" ;;
+    update)                  cmd_update "$@" ;;
+    migrate)                 cmd_migrate "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)
@@ -552,4 +574,54 @@ main() {
   esac
 }
 
-main "$@"
+# Pre-flight pin resolver: when `.agent-settings.yml` carries a
+# non-empty `agent_config_version` that differs from the running
+# package version, re-exec via `npx @event4u/agent-config@<pin>`.
+# Skipped for `--version`, `help`, `update` and `migrate` (so consumers
+# can escape a bad pin or run the legacy-cleanup before a pin exists),
+# and when `AGENT_CONFIG_NO_PIN_REEXEC=1`. See P3.2 of
+# road-to-portable-runtime-and-update-check.md.
+maybe_pin_reexec() {
+  local cmd="${1-}"
+  case "$cmd" in
+    help|--help|-h|--version|-V|update|migrate|"") return 0 ;;
+  esac
+  if ! command -v python3 >/dev/null 2>&1; then
+    return 0
+  fi
+  local installed
+  installed="$(print_version)"
+  [[ -z "$installed" || "$installed" == "unknown" ]] && return 0
+  env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._lib.pin_resolver \
+    --cwd "$CONSUMER_ROOT" --installed "$installed" -- "$@" || true
+}
+
+# Post-subcommand banner: best-effort daily update-check notice on
+# stderr. Runs after the dispatch returns (subshell wrapper below)
+# so the banner appears post-output and never delays the subcommand.
+# Suppressed in CI, on non-TTY stdout, by AGENT_CONFIG_NO_UPDATE_CHECK=1,
+# or by `update_check.enabled: false` in settings. See P2 of
+# road-to-portable-runtime-and-update-check.md.
+run_update_check_banner() {
+  local cmd="${1-}"
+  case "$cmd" in
+    help|--help|-h|--version|-V|"") return 0 ;;
+  esac
+  if ! command -v python3 >/dev/null 2>&1; then
+    return 0
+  fi
+  local banner_script="$PACKAGE_ROOT/scripts/check_update_banner.py"
+  [[ -f "$banner_script" ]] || return 0
+  python3 "$banner_script" --cwd "$CONSUMER_ROOT" 2>/dev/null || true
+}
+
+# Pin re-exec runs before dispatch — if it triggers, the process is
+# replaced and nothing else here matters.
+maybe_pin_reexec "$@"
+
+# Dispatch in a subshell so internal ``exec`` calls do not replace this
+# process — we still get to run the post-subcommand banner.
+( main "$@" )
+rc=$?
+run_update_check_banner "${1-}"
+exit "$rc"

package/scripts/check_overlay_cascade_subdirs.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Guard: ``CASCADE_ELIGIBLE_KINDS`` / ``USER_GLOBAL_OVERLAY_KINDS`` ↔ docs.
+
+Phase 1 of road-to-portable-runtime-and-update-check (P1.6). The
+overlay resolver in :mod:`scripts._lib.agents_overlay` ships two
+constants that gate which ``agents/<kind>/`` subdirs participate in
+the cascade and which of those may live at the user-global layer.
+The same lists are restated in
+``docs/customization.md`` § *"agents/ overlay cascade"* so consumers
+can see them without reading source.
+
+Drift between code and docs is the failure mode this guard catches.
+
+Exit codes: 0 = clean, 1 = drift detected, 3 = internal error.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+sys.path.insert(0, str(REPO_ROOT))
+
+from scripts._lib.agents_overlay import (  # noqa: E402
+    CASCADE_ELIGIBLE_KINDS,
+    USER_GLOBAL_OVERLAY_KINDS,
+)
+
+DOCS_PATH = REPO_ROOT / "docs" / "customization.md"
+
+# Match `agents/<kind>/` in the first column of the overlay table, plus
+# the ✅/❌ markers in columns 2 and 3.
+ROW_RE = re.compile(
+    r"^\|\s*`agents/([a-z][a-z0-9_-]*)/`\s*\|\s*(✅|❌)[^|]*\|\s*(✅|❌)[^|]*\|",
+)
+
+
+def _parse_doc_table(text: str) -> tuple[set[str], set[str], set[str]]:
+    """Return (all-kinds-listed, cascade-yes, user-global-yes) from the table."""
+    all_kinds: set[str] = set()
+    cascade_yes: set[str] = set()
+    user_global_yes: set[str] = set()
+    for line in text.splitlines():
+        match = ROW_RE.match(line)
+        if not match:
+            continue
+        kind, cascade_mark, user_mark = match.groups()
+        all_kinds.add(kind)
+        if cascade_mark == "✅":
+            cascade_yes.add(kind)
+        if user_mark == "✅":
+            user_global_yes.add(kind)
+    return all_kinds, cascade_yes, user_global_yes
+
+
+def main() -> int:
+    if not DOCS_PATH.is_file():
+        print(f"❌  {DOCS_PATH} not found", file=sys.stderr)
+        return 3
+    text = DOCS_PATH.read_text(encoding="utf-8")
+    _, doc_cascade, doc_user_global = _parse_doc_table(text)
+
+    errors: list[str] = []
+
+    code_cascade = set(CASCADE_ELIGIBLE_KINDS)
+    if doc_cascade != code_cascade:
+        only_code = sorted(code_cascade - doc_cascade)
+        only_doc = sorted(doc_cascade - code_cascade)
+        if only_code:
+            errors.append(
+                "CASCADE_ELIGIBLE_KINDS has entries missing from "
+                f"docs/customization.md table: {only_code}",
+            )
+        if only_doc:
+            errors.append(
+                "docs/customization.md table marks these as cascade-eligible "
+                f"but the code list does not: {only_doc}",
+            )
+
+    code_user_global = set(USER_GLOBAL_OVERLAY_KINDS)
+    if doc_user_global != code_user_global:
+        only_code = sorted(code_user_global - doc_user_global)
+        only_doc = sorted(doc_user_global - code_user_global)
+        if only_code:
+            errors.append(
+                "USER_GLOBAL_OVERLAY_KINDS has entries missing from "
+                f"docs/customization.md table: {only_code}",
+            )
+        if only_doc:
+            errors.append(
+                "docs/customization.md table marks these as user-global-eligible "
+                f"but the code list does not: {only_doc}",
+            )
+
+    # Sanity: user-global subset of cascade-eligible.
+    if not code_user_global.issubset(code_cascade):
+        errors.append(
+            "USER_GLOBAL_OVERLAY_KINDS must be a subset of "
+            f"CASCADE_ELIGIBLE_KINDS; surplus: "
+            f"{sorted(code_user_global - code_cascade)}",
+        )
+
+    if errors:
+        print("❌  agents/ overlay cascade drift detected:", file=sys.stderr)
+        for err in errors:
+            print(f"   - {err}", file=sys.stderr)
+        print(
+            "\nFix: update either scripts/_lib/agents_overlay.py "
+            "or docs/customization.md so they agree.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"✅  agents/ overlay cascade in sync · "
+        f"{len(code_cascade)} cascade-eligible, "
+        f"{len(code_user_global)} user-global-eligible",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_template_pin_drift.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Fail when ``package.json.version`` and the project-template pin drift.
+
+CI guard for P3.3 of road-to-portable-runtime-and-update-check.md.
+
+A release bump of ``package.json`` must update
+``agent_config_version`` in
+``.agent-src.uncompressed/templates/agents/agent-project-settings.example.yml``
+(and its compressed twin under ``.agent-src/``) in lockstep. Otherwise
+a fresh ``init`` on a new project would bootstrap onto a stale pin,
+and the pin-resolver would re-exec back to the older version.
+
+Exit codes:
+    0 — pin matches package.json.version (or pin is empty and the
+        ``--allow-empty`` flag is set, used for early development).
+    1 — pin missing, drift detected, or template file unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+PACKAGE_JSON = REPO_ROOT / "package.json"
+TEMPLATE_FILES = (
+    REPO_ROOT / ".agent-src.uncompressed" / "templates" / "agents" / "agent-project-settings.example.yml",
+    REPO_ROOT / ".agent-src" / "templates" / "agents" / "agent-project-settings.example.yml",
+)
+PIN_LINE_RE = re.compile(r"^\s*agent_config_version\s*:\s*\"?([^\"\s#]*)\"?")
+
+
+def _read_package_version() -> str | None:
+    try:
+        data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+    version = data.get("version")
+    return version.strip() if isinstance(version, str) else None
+
+
+def _read_template_pin(path: Path) -> str | None:
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            match = PIN_LINE_RE.match(line)
+            if match:
+                return match.group(1).strip()
+    except OSError:
+        return None
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Fail when package.json version and template pin drift.",
+    )
+    parser.add_argument(
+        "--allow-empty",
+        action="store_true",
+        help="Accept an empty pin (used during early-stage development).",
+    )
+    args = parser.parse_args(argv)
+
+    pkg_version = _read_package_version()
+    if not pkg_version:
+        print("❌  check_template_pin_drift: failed to read package.json version.", file=sys.stderr)
+        return 1
+
+    failures: list[str] = []
+    for template in TEMPLATE_FILES:
+        if not template.is_file():
+            failures.append(f"missing template file: {template.relative_to(REPO_ROOT)}")
+            continue
+        pin = _read_template_pin(template)
+        rel = template.relative_to(REPO_ROOT)
+        if pin is None:
+            failures.append(f"{rel}: no `agent_config_version:` line found")
+            continue
+        if pin == "":
+            if not args.allow_empty:
+                failures.append(
+                    f"{rel}: agent_config_version is empty; expected {pkg_version}"
+                )
+            continue
+        if pin != pkg_version:
+            failures.append(
+                f"{rel}: agent_config_version={pin!r} does not match package.json version {pkg_version!r}"
+            )
+
+    if failures:
+        print(
+            "❌  check_template_pin_drift: template pin drift detected.",
+            file=sys.stderr,
+        )
+        for line in failures:
+            print(f"    - {line}", file=sys.stderr)
+        print(
+            "    Fix: update `agent_config_version:` in the listed template(s) to "
+            f"{pkg_version!r} before releasing.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"✅  template pin = package.json version ({pkg_version}).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_update_banner.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Thin CLI wrapper: emit the daily update-check banner to stderr.
+
+Invoked by the ``scripts/agent-config`` dispatcher **after** a
+subcommand finishes. Never raises, never exits non-zero — banner is
+best-effort. See ``scripts/_lib/update_check.py`` for the decision
+logic.
+
+Usage:
+    python3 scripts/check_update_banner.py [--installed-version X.Y.Z]
+
+When ``--installed-version`` is omitted, reads ``package.json`` next to
+the package root (``$PACKAGE_ROOT/package.json``).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from scripts._lib import agent_settings  # noqa: E402
+from scripts._lib import update_check  # noqa: E402
+
+
+def _read_installed_version(package_root: Path) -> str:
+    candidate = package_root / "package.json"
+    try:
+        data = json.loads(candidate.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 ""
+
+
+def _read_settings_flag(cwd: Path) -> bool:
+    try:
+        settings = agent_settings.load_agent_settings(cwd=cwd)
+    except Exception:
+        return True
+    block = settings.get("update_check")
+    if isinstance(block, dict) and block.get("enabled") is False:
+        return False
+    return True
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="check-update-banner", add_help=False)
+    parser.add_argument("--installed-version", default="")
+    parser.add_argument("--cwd", default=str(Path.cwd()))
+    parser.add_argument("--help", "-h", action="store_true")
+    args, _unknown = parser.parse_known_args(argv)
+    if args.help:
+        print(__doc__ or "")
+        return 0
+
+    installed = args.installed_version or _read_installed_version(ROOT)
+    if not installed:
+        return 0
+
+    try:
+        cwd = Path(args.cwd).resolve()
+    except OSError:
+        cwd = ROOT
+    enabled = _read_settings_flag(cwd)
+
+    try:
+        banner = update_check.check_for_update(
+            installed,
+            settings_enabled=enabled,
+        )
+    except Exception:
+        return 0
+
+    if banner:
+        print(banner, file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install

@@ -26,12 +26,6 @@
 #   --quiet           Suppress non-error output
 #   --skip-sync       Skip payload sync (install.sh)
 #   --skip-bridges    Skip bridge files (install.py)
-#   --global          Phase-3: ship kernel rules + curated skills to user-scope
-#                     dirs (~/.claude/, ~/.cursor/, ~/.codeium/windsurf/,
-#                     ~/.config/agent-config/) so the agent has them in every
-#                     project. Pair with --tools to scope surfaces; default = all.
-#   --uninstall       With --global: remove the event4u/ namespace dir from each
-#                     enabled surface (no effect on user-added files).
 #   --help, -h        Show this help
 #
 # Examples:
@@ -59,14 +53,12 @@ QUIET=false
 SKIP_SYNC=false
 SKIP_BRIDGES=false
 LIST_TOOLS=false
-GLOBAL_INSTALL=false
-UNINSTALL=false
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex all"
 
 show_help() {
-    sed -n '3,35p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,29p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -128,8 +120,6 @@ while [[ $# -gt 0 ]]; do
         --quiet)         QUIET=true; shift ;;
         --skip-sync)     SKIP_SYNC=true; shift ;;
         --skip-bridges)  SKIP_BRIDGES=true; shift ;;
-        --global)        GLOBAL_INSTALL=true; shift ;;
-        --uninstall)     UNINSTALL=true; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
@@ -175,16 +165,11 @@ prompt_tools() {
     echo "  ✅  Selected: $TOOLS"
 }
 
-if ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && ! $GLOBAL_INSTALL && [[ -t 0 && -t 1 ]]; then
+if ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && [[ -t 0 && -t 1 ]]; then
     prompt_tools
     TOOLS_EXPLICIT=true
 fi
 
-if $UNINSTALL && ! $GLOBAL_INSTALL; then
-    err "--uninstall is only valid combined with --global"
-    exit 1
-fi
-
 # Default = "all": backward compatible with pre-Phase-1 invocations. An
 # explicit --tools= (empty value) is rejected by validate_tools — only an
 # absent flag falls through to "all".
@@ -201,12 +186,10 @@ if [[ -z "$SOURCE_DIR" ]]; then
     SOURCE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 fi
 
-# Auto-detect target: PROJECT_ROOT env, or derive from vendor/node_modules path, else cwd
+# Auto-detect target: PROJECT_ROOT env, or derive from node_modules path, else cwd
 if [[ -z "$TARGET_DIR" ]]; then
     if [[ -n "${PROJECT_ROOT:-}" ]]; then
         TARGET_DIR="$PROJECT_ROOT"
-    elif [[ "$SOURCE_DIR" == */vendor/event4u/agent-config ]]; then
-        TARGET_DIR="$(cd "$SOURCE_DIR/../../.." && pwd)"
     elif [[ "$SOURCE_DIR" == */node_modules/@event4u/agent-config ]]; then
         TARGET_DIR="$(cd "$SOURCE_DIR/../../.." && pwd)"
     elif [[ "$SOURCE_DIR" == */node_modules/*/agent-config ]]; then
@@ -216,6 +199,30 @@ if [[ -z "$TARGET_DIR" ]]; then
     fi
 fi
 
+# Source-repo guard: refuse to install into the agent-config dev tree itself.
+# Mirrors packages/create-agent-config/src/install.js — defense-in-depth so a
+# direct `bash scripts/install` from inside the source checkout (without the
+# Node wrapper) cannot corrupt .augment/ symlinks. Override for self-tests:
+# AGENT_CONFIG_ALLOW_SELF_INSTALL=1.
+if [[ "${AGENT_CONFIG_ALLOW_SELF_INSTALL:-0}" != "1" ]]; then
+    self_marker=""
+    if [[ -d "$TARGET_DIR/.agent-src.uncompressed" ]]; then
+        self_marker=".agent-src.uncompressed/"
+    elif [[ -f "$TARGET_DIR/package.json" ]] && \
+         grep -qE '"name"[[:space:]]*:[[:space:]]*"@event4u/(create-)?agent-config"' "$TARGET_DIR/package.json" 2>/dev/null; then
+        self_marker='package.json::name === "@event4u/(create-)agent-config"'
+    fi
+    if [[ -n "$self_marker" ]]; then
+        err "Refusing to install agent-config into its own source checkout."
+        echo "      Target:   $TARGET_DIR" >&2
+        echo "      Detected: $self_marker" >&2
+        echo "      Run \`task sync\` to regenerate .agent-src/ + .augment/ from" >&2
+        echo "      .agent-src.uncompressed/ instead. To force this anyway, set" >&2
+        echo "      AGENT_CONFIG_ALLOW_SELF_INSTALL=1." >&2
+        exit 2
+    fi
+fi
+
 # Find python3 for the bridges stage (optional until SKIP_BRIDGES=false)
 find_python() {
     local candidate path
@@ -262,26 +269,6 @@ run_bridges() {
 
 RC=0
 
-# --global: dedicated user-scope path. Skips the project-bridge sync entirely
-# and forwards to install.py --global (Phase 3 / S13). --uninstall pairs with
-# --global to wipe the event4u/ namespace dir under each surface.
-if $GLOBAL_INSTALL; then
-    if ! python_bin="$(find_python)"; then
-        err "Python 3 not found — required for --global install"
-        exit 1
-    fi
-    if [[ ! -f "$INSTALL_PY" ]]; then
-        err "Missing $INSTALL_PY"
-        exit 1
-    fi
-    args=(--package "$SOURCE_DIR" --global --tools="$TOOLS")
-    $FORCE     && args+=(--force)
-    $QUIET     && args+=(--quiet)
-    $UNINSTALL && args+=(--uninstall)
-    "$python_bin" "$INSTALL_PY" "${args[@]}"
-    exit $?
-fi
-
 if ! $SKIP_SYNC; then
     if [[ ! -f "$INSTALL_SH" ]]; then
         err "Missing $INSTALL_SH"