@event4u/agent-config 2.1.0 → 2.2.0

package/scripts/_lib/installed_tools.py

@@ -0,0 +1,237 @@
+"""Project-scope installed-tools manifest at ``agents/installed-tools.lock``.
+
+Phase 3 of road-to-global-first-install (ADR-008). Committed
+bill-of-materials for AI tooling a project depends on. Sibling to the
+global lockfile (``installed_lock.py``) but architecturally distinct:
+
+- ``installed_lock.py`` lives in ``~/.config/agent-config/`` and tracks
+  the user-scope environment (a single ``agent_config_version`` and a
+  flat ``tools[]`` list).
+- ``installed_tools.py`` lives in ``agents/`` and tracks **per-project**
+  tooling with richer per-entry metadata (``scope``, ``bridge_marker``,
+  ``installed_at``).
+
+The file is machine-managed: ``init`` appends / merges; ``sync`` replays;
+``validate`` drift-checks. Schema is YAML; ``pyyaml`` is used when
+available, otherwise a constrained manual parser handles the documented
+schema (no anchors, no flow style, single-level nesting under
+``tools``).
+"""
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+MANIFEST_ENV = "AGENT_CONFIG_INSTALLED_TOOLS"
+DEFAULT_MANIFEST_RELATIVE = Path("agents") / "installed-tools.lock"
+SCHEMA_VERSION = 1
+
+_VALID_SCOPES = ("global", "project")
+
+
+def manifest_path(project_root: Path, env: Optional[dict] = None) -> Path:
+    """Return the active manifest path, honoring the env override."""
+    env = env if env is not None else os.environ
+    override = env.get(MANIFEST_ENV)
+    if override:
+        return Path(override).expanduser()
+    return project_root / DEFAULT_MANIFEST_RELATIVE
+
+
+# ---------------------------------------------------------------------------
+# Read
+# ---------------------------------------------------------------------------
+
+_TOP_KEY_RE = re.compile(r'^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*"?([^"\n]*?)"?\s*$')
+_LIST_DASH_RE = re.compile(r"^\s*-\s*(.+?)\s*$")
+_INDENT_KEY_RE = re.compile(r'^\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*"?([^"\n]*?)"?\s*$')
+
+
+def read_manifest(path: Path) -> Optional[dict[str, Any]]:
+    """Parse the manifest into a dict; return ``None`` if absent.
+
+    Tolerates partial / malformed files: missing keys yield missing dict
+    entries rather than raising, so a corrupted file does not brick
+    ``init``.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+        data = yaml.safe_load(text) or {}
+        if isinstance(data, dict):
+            data.setdefault("tools", [])
+            return data
+    except ImportError:
+        pass
+    except Exception:
+        # Fall through to the manual parser; corrupt YAML is recoverable
+        # from our strict schema as long as the top-level shape holds.
+        pass
+    return _parse_manual(text)
+
+
+def _parse_manual(text: str) -> dict[str, Any]:
+    data: dict[str, Any] = {"tools": []}
+    in_tools = False
+    current: Optional[dict[str, Any]] = None
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped == "tools:":
+            in_tools = True
+            current = None
+            continue
+        if in_tools:
+            m = _LIST_DASH_RE.match(raw)
+            if m:
+                first = m.group(1)
+                current = {}
+                data["tools"].append(current)
+                # Could be inline like `- name: foo` — handle that.
+                inline = _TOP_KEY_RE.match(first)
+                if inline:
+                    current[inline.group(1)] = inline.group(2)
+                continue
+            mk = _INDENT_KEY_RE.match(raw)
+            if mk and current is not None:
+                current[mk.group(1)] = mk.group(2)
+                continue
+        m_top = _TOP_KEY_RE.match(raw)
+        if m_top:
+            key, value = m_top.group(1), m_top.group(2)
+            if key == "schema_version":
+                try:
+                    data[key] = int(value)
+                except ValueError:
+                    data[key] = value
+            else:
+                data[key] = value
+            in_tools = False
+            current = None
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Write
+# ---------------------------------------------------------------------------
+
+
+def _render(
+    version: str,
+    tools: list[dict[str, Any]],
+) -> str:
+    lines = [
+        f"schema_version: {SCHEMA_VERSION}",
+        f'agent_config_version: "{version}"',
+        "tools:",
+    ]
+    for tool in tools:
+        lines.append(f"  - name: {tool['name']}")
+        lines.append(f"    scope: {tool['scope']}")
+        lines.append(f"    bridge_marker: {tool['bridge_marker']}")
+        lines.append(f'    installed_at: "{tool["installed_at"]}"')
+    return "\n".join(lines) + "\n"
+
+
+def write_manifest(
+    path: Path,
+    version: str,
+    tools: list[dict[str, Any]],
+) -> Path:
+    """Atomically write the manifest; return the path written."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    rendered = _render(version, tools)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=".installed-tools.lock.", dir=str(path.parent), text=False
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(rendered)
+        os.replace(tmp_name, path)
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Mutation helpers
+# ---------------------------------------------------------------------------
+
+
+class ScopeMismatchError(RuntimeError):
+    """Raised when an existing manifest entry conflicts with the new scope."""
+
+    def __init__(self, name: str, recorded_scope: str, new_scope: str):
+        super().__init__(
+            f"tool {name!r} is committed as scope={recorded_scope}; "
+            f"refusing to change it to scope={new_scope} without --force"
+        )
+        self.name = name
+        self.recorded_scope = recorded_scope
+        self.new_scope = new_scope
+
+
+def upsert_tool(
+    existing: list[dict[str, Any]],
+    *,
+    name: str,
+    scope: str,
+    bridge_marker: str,
+    installed_at: Optional[str] = None,
+    force: bool = False,
+) -> list[dict[str, Any]]:
+    """Return a new tools list with ``name`` added or refreshed.
+
+    Idempotency rules from ADR-008 §Lifecycle:
+    * Same name, same scope → no-op (timestamp preserved).
+    * Same name, different scope → raise ``ScopeMismatchError`` unless
+      ``force=True``, in which case the entry is rewritten.
+    * New name → appended in install order (not alphabetised).
+    """
+    if scope not in _VALID_SCOPES:
+        raise ValueError(f"scope must be one of {_VALID_SCOPES}: {scope!r}")
+    stamp = installed_at or _today()
+    result: list[dict[str, Any]] = []
+    found = False
+    for entry in existing:
+        if entry.get("name") == name:
+            found = True
+            recorded = str(entry.get("scope", ""))
+            if recorded == scope:
+                # Idempotent no-op — preserve original installed_at.
+                result.append(entry)
+                continue
+            if not force:
+                raise ScopeMismatchError(name, recorded, scope)
+            result.append({
+                "name": name,
+                "scope": scope,
+                "bridge_marker": bridge_marker,
+                "installed_at": stamp,
+            })
+            continue
+        result.append(entry)
+    if not found:
+        result.append({
+            "name": name,
+            "scope": scope,
+            "bridge_marker": bridge_marker,
+            "installed_at": stamp,
+        })
+    return result
+
+
+def _today() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")

package/scripts/agent-config

@@ -98,6 +98,19 @@ Commands:
                              Flags: --check (read-only) | --to <version> (explicit pin)
   migrate                    One-shot migration off legacy composer / npm install paths
                              Flags: --dry-run (detect only)
+  global                     Install to user-scope paths (~/.claude/, ~/.cursor/, …)
+                             Forwards to `scripts/install --global` (ADR-007).
+                             Flags: --tools=<list> | --ai=<list> | --yes | --force
+  export                     Eject a tool's canonical content into a chosen path
+                             (real file, no symlink). Idempotent; --force overrides
+                             content drift. See `./agent-config export --list`.
+                             Flags: --tool=<id> | --output=<path> | --force | --list
+  sync                       Replay agents/installed-tools.lock — re-installs any
+                             tool whose bridge marker is missing locally (ADR-008).
+                             Flags: --dry-run | --force | --project=<path>
+  validate                   Read-only drift detection on the manifest
+                             (marker missing, scope divergence, version drift).
+                             Exits 1 on drift. Flags: --quiet | --skip-version-check
   help                       Show this help
   --version, -V              Print package version
 
@@ -126,6 +139,14 @@ Examples:
   ./agent-config council:estimate prompt.txt
   ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
   ./agent-config council:render agents/council-sessions/out.json
+  ./agent-config global --tools=claude-code --yes
+  ./agent-config global --ai=cursor,windsurf
+  ./agent-config export --list
+  ./agent-config export --tool=agents-md --output=AGENTS.md
+  ./agent-config export --tool=copilot-instructions --output=.github/copilot-instructions.md
+  ./agent-config sync --dry-run
+  ./agent-config sync
+  ./agent-config validate
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -524,6 +545,43 @@ cmd_migrate() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_migrate "$@"
 }
 
+# `agent-config global` — user-scope install entry point. Forwards to the
+# bash installer with `--global` set (ADR-007). Phase 1.2 of
+# road-to-global-first-install.md. The bash wrapper handles option parsing
+# and forwards to `scripts/install.py --global`, where `install_global()`
+# currently scaffolds the per-tool anchor paths from USER_SCOPE_PATHS.
+# Concrete writes land in Phase 1.5 (export) and Phase 1.6 (lockfile).
+cmd_global() {
+  local script
+  script="$(resolve_script "scripts/install")" || return 1
+  exec bash "$script" --global "$@"
+}
+
+# `agent-config export` — write a tool's canonical content into a
+# user-chosen path. ADR-007 D3 / Phase 1.5 of
+# road-to-global-first-install.md. Replaces the rejected symlink-bridge.
+# See scripts/_cli/cmd_export.py for the registry and idempotency logic.
+cmd_export() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_export "$@"
+}
+
+# `agent-config sync` — replay agents/installed-tools.lock (ADR-008
+# Phase 3.3). Re-installs any tool whose bridge marker is missing on
+# disk. Typical onboarding flow: clone → `./agent-config sync` → done.
+cmd_sync() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_sync "$@"
+}
+
+# `agent-config validate` — read-only drift detection (ADR-008 Phase 3.4).
+# Surfaces marker-missing, scope-divergence, and version-drift; exits 1 on
+# any drift. Never edits the manifest or re-runs the installer.
+cmd_validate() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -564,6 +622,10 @@ main() {
     council:render)          cmd_council render "$@" ;;
     update)                  cmd_update "$@" ;;
     migrate)                 cmd_migrate "$@" ;;
+    global)                  cmd_global "$@" ;;
+    export)                  cmd_export "$@" ;;
+    sync)                    cmd_sync "$@" ;;
+    validate)                cmd_validate "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)

package/scripts/install

@@ -17,7 +17,10 @@
 #   --profile <name>  Cost profile for bridges (minimal|balanced|full)
 #   --tools <list>    Comma-separated tool IDs to install (default: all).
 #                     Valid: claude-code,claude-desktop,cursor,windsurf,
-#                            cline,gemini-cli,copilot,augment,aider,codex,all
+#                            cline,gemini-cli,copilot,augment,aider,codex,
+#                            roocode,continue,kilocode,zed,jetbrains,kiro,all
+#   --ai <list>       Alias for --tools (same IDs). When both are passed
+#                     the comma-separated values are unioned.
 #   --list-tools      Print supported tool IDs with descriptions, then exit
 #   --yes, -y         Non-interactive mode: do not prompt (default for non-TTY)
 #   --force           Overwrite existing bridge files
@@ -26,12 +29,22 @@
 #   --quiet           Suppress non-error output
 #   --skip-sync       Skip payload sync (install.sh)
 #   --skip-bridges    Skip bridge files (install.py)
+#   --global          Install to user-scope paths (~/.claude/, ~/.cursor/, …)
+#                     instead of project-locally. Implies --skip-sync (the
+#                     payload sync stage is project-only). See ADR-007.
+#   --scope <mode>    Override scope detection: auto | project | global | prompt.
+#                     auto   = honor multi-signal detection (Phase 1.3)
+#                     project = force project-local install
+#                     global = force user-scope install (same as --global)
+#                     prompt = always show the 3-option chooser
+#   --custom-path <d> Use <d> as the project root when prompted; rejected with
+#                     --scope=global / --global.
 #   --help, -h        Show this help
 #
 # Examples:
 #   bash scripts/install                                # everything (default)
 #   bash scripts/install --tools=claude-code,cursor     # only those two
-#   bash scripts/install --tools=cursor --yes           # CI-friendly
+#   bash scripts/install --ai=cursor --yes              # alias form (CI-friendly)
 #   bash scripts/install --list-tools                   # show catalog
 
 set -uo pipefail
@@ -53,12 +66,15 @@ QUIET=false
 SKIP_SYNC=false
 SKIP_BRIDGES=false
 LIST_TOOLS=false
+GLOBAL=false
+SCOPE=""
+CUSTOM_PATH=""
 
 # 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"
+VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,29p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,48p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -66,19 +82,26 @@ list_tools() {
 Supported --tools IDs (default: all):
 
   claude-code      .claude/rules, .claude/skills, .claude/commands, .claude/settings.json
-  claude-desktop   ~/Library/Application Support/Claude/ (global, see Phase 4 docs)
+  claude-desktop   .claude-desktop/agent-config.md marker (global-scope tool — see ADR-007)
   cursor           .cursor/rules, .cursor/commands (legacy .cursorrules also written)
   windsurf         .windsurf/rules, .windsurf/workflows (legacy .windsurfrules also written)
   cline            .clinerules/ symlinks
   gemini-cli       GEMINI.md, .gemini/settings.json
   copilot          .github/copilot-instructions.md, .vscode/settings.json
   augment          .augment/ payload + settings (substrate — recommended for every install)
-  aider            AGENTS.md (Linux Foundation cross-tool contract; always written)
-  codex            AGENTS.md (same as aider — no extra action)
+  aider            .aider/agent-config.md marker (wire via `read:` in .aider.conf.yml)
+  codex            .codex/agent-config.md marker (Codex reads AGENTS.md directly)
+  roocode          .roo/rules/agent-config.md marker (Roo Code auto-discovery)
+  continue         .continue/rules/agent-config.md marker (Continue.dev auto-discovery)
+  kilocode         .kilocode/rules/agent-config.md marker (Kilo Code auto-discovery)
+  zed              .zed/agent-config.md marker (Zed reads .rules at project root)
+  jetbrains        .jetbrains/agent-config.md marker (JetBrains AI Assistant)
+  kiro             .kiro/steering/agent-config.md marker (Kiro auto-discovery)
   all              every ID above (the default; backward-compatible)
 
 Examples:
   --tools=claude-code,cursor       project-local install for those two surfaces
+  --ai=cursor                      alias for --tools=cursor
   --tools=all                      equivalent to omitting the flag
 EOF
 }
@@ -110,8 +133,10 @@ while [[ $# -gt 0 ]]; do
         --target=*)      TARGET_DIR="${1#*=}"; shift ;;
         --profile)       PROFILE="$2"; shift 2 ;;
         --profile=*)     PROFILE="${1#*=}"; shift ;;
-        --tools)         TOOLS="$2"; TOOLS_EXPLICIT=true; shift 2 ;;
-        --tools=*)       TOOLS="${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
+        --tools)         TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
+        --tools=*)       TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
+        --ai)            TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
+        --ai=*)          TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
         --list-tools)    LIST_TOOLS=true; shift ;;
         --yes|-y)        YES=true; shift ;;
         --force)         FORCE=true; shift ;;
@@ -120,6 +145,11 @@ while [[ $# -gt 0 ]]; do
         --quiet)         QUIET=true; shift ;;
         --skip-sync)     SKIP_SYNC=true; shift ;;
         --skip-bridges)  SKIP_BRIDGES=true; shift ;;
+        --global)        GLOBAL=true; SKIP_SYNC=true; shift ;;
+        --scope)         SCOPE="$2"; shift 2 ;;
+        --scope=*)       SCOPE="${1#*=}"; shift ;;
+        --custom-path)   CUSTOM_PATH="$2"; shift 2 ;;
+        --custom-path=*) CUSTOM_PATH="${1#*=}"; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
@@ -138,7 +168,7 @@ fi
 # Otherwise we fall through to the backward-compatible "all" default.
 prompt_tools() {
     local choice picked tool i=0
-    local -a menu=(claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex)
+    local -a menu=(claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro)
     echo ""
     echo "  📦 Pick the tools to install (comma-separated numbers, blank = all):"
     for tool in "${menu[@]}"; do
@@ -263,6 +293,9 @@ run_bridges() {
     [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
     $FORCE && args+=(--force)
     $QUIET && args+=(--quiet)
+    $GLOBAL && args+=(--global)
+    [[ -n "$SCOPE" ]] && args+=(--scope="$SCOPE")
+    [[ -n "$CUSTOM_PATH" ]] && args+=(--custom-path="$CUSTOM_PATH")
     args+=(--tools="$TOOLS")
     "$python_bin" "$INSTALL_PY" "${args[@]}"
 }