@event4u/agent-config 2.2.2 → 2.4.0

package/scripts/_lib/agent_settings.py

@@ -5,11 +5,18 @@ how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
 
 Resolution order (deepest wins; user-global is whitelist-filtered only):
 
-  N. ``~/.config/agent-config/agent-settings.yml``  (user-global; whitelist only)
+  N. ``~/.event4u/agent-config/agent-settings.yml`` (user-global; whitelist only)
 N-1. ``<repo-root>/.agent-settings.yml``            (project-wide; all keys)
 N-2. ``<intermediate-dir>/.agent-settings.yml``     (subsystem-scoped; all keys)
   1. ``<CWD>/.agent-settings.yml``                  (deepest, wins; all keys)
 
+The user-global path is resolved via the sibling
+:mod:`work_engine._lib.user_global_paths` module (vendored from
+``scripts/_lib/user_global_paths.py`` so the engine stays self-contained
+when shipped into consumer projects) with a read-fallback to the legacy
+``~/.config/agent-config/agent-settings.yml`` so pre-2.4 installs keep
+working during the namespace migration.
+
 ``<repo-root>`` is the nearest ancestor that contains ``.git`` (directory
 **or** file — submodule support). The walk stops there — it never drifts
 into a parent repo or ``$HOME``. When ``cwd`` is ``None`` (default), the
@@ -37,12 +44,26 @@ import logging
 from pathlib import Path
 from typing import Any, Iterator
 
+from . import user_global_paths
+
 logger = logging.getLogger(__name__)
 
 DEFAULT_PROJECT_FILE = ".agent-settings.yml"
-DEFAULT_USER_GLOBAL_FILE = (
-    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
-)
+USER_GLOBAL_FILENAME = "agent-settings.yml"
+
+#: Canonical write target under the new ``~/.event4u/agent-config/``
+#: namespace. Reads route through :func:`_resolve_user_global_file` so
+#: pre-2.4 installs are still picked up from ``~/.config/agent-config/``
+#: until the migration shim copies them across.
+DEFAULT_USER_GLOBAL_FILE = user_global_paths.write_target(USER_GLOBAL_FILENAME)
+
+
+def _resolve_user_global_file() -> Path:
+    """Return the active user-global settings path with legacy fallback."""
+    found = user_global_paths.resolve_with_fallback(USER_GLOBAL_FILENAME)
+    if found is not None:
+        return found
+    return DEFAULT_USER_GLOBAL_FILE
 
 #: Exact dotted paths allowed to cascade from user-global into the merged
 #: settings. Anything not listed here is silently ignored when present in
@@ -129,7 +150,8 @@ def load_agent_settings(
 
     ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
     ``user_global_path`` defaults to
-    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``~/.event4u/agent-config/agent-settings.yml`` (with a read fallback
+    to the legacy ``~/.config/agent-config/agent-settings.yml``). Both arguments accept
     ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
     user-global that are not on the whitelist.
 
@@ -143,7 +165,7 @@ def load_agent_settings(
     with pre-cascade callers.
     """
     user_global_raw = _read_yaml(
-        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+        Path(user_global_path) if user_global_path else _resolve_user_global_file(),
     ) or {}
 
     user_global_filtered, ignored = _filter_whitelist(
@@ -181,7 +203,7 @@ def iter_setting_overrides(
     Never blocks, never raises on missing files.
     """
     user_global_path_resolved = (
-        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE
+        Path(user_global_path) if user_global_path else _resolve_user_global_file()
     )
     user_global_raw = _read_yaml(user_global_path_resolved) or {}
     user_global_filtered, _ = _filter_whitelist(user_global_raw, MERGEABLE_KEYS)

package/scripts/_lib/agents_overlay.py

@@ -8,9 +8,12 @@ user-global directory (when the ``kind`` is whitelisted).
 
 Resolution order (deepest wins, every layer optional):
 
-  N. ``~/.config/agent-config/agents/<kind>/<name>.md``  (user-global; weakest;
+  N. ``~/.event4u/agent-config/agents/<kind>/<name>.md`` (user-global; weakest;
                                                           ``kind`` must be in
-                                                          ``USER_GLOBAL_OVERLAY_KINDS``)
+                                                          ``USER_GLOBAL_OVERLAY_KINDS``;
+                                                          legacy
+                                                          ``~/.config/agent-config/agents/``
+                                                          tree read as fallback)
 N-1. ``<repo-root>/agents/<kind>/<name>.md``
 N-2. ``<intermediate-dir>/agents/<kind>/<name>.md``      (optional)
   1. ``<CWD>/agents/<kind>/<name>.md``                   (deepest, wins)
@@ -34,6 +37,7 @@ from __future__ import annotations
 import logging
 from pathlib import Path
 
+from scripts._lib import user_global_paths
 from scripts._lib.agent_settings import find_project_root
 
 logger = logging.getLogger(__name__)
@@ -50,13 +54,17 @@ CASCADE_ELIGIBLE_KINDS: frozenset[str] = frozenset({
 })
 
 #: Subset of :data:`CASCADE_ELIGIBLE_KINDS` allowed to live at the
-#: user-global layer (``~/.config/agent-config/agents/<kind>/``).
+#: user-global layer (``~/.event4u/agent-config/agents/<kind>/``).
 #: ``contexts/`` and ``decisions/`` are project-shaped and must not leak
 #: across projects; only ``overrides/`` — the developer's personal
 #: layer — is whitelisted.
 USER_GLOBAL_OVERLAY_KINDS: frozenset[str] = frozenset({"overrides"})
 
-USER_GLOBAL_AGENTS_DIR = Path.home() / ".config" / "agent-config" / "agents"
+#: Canonical write target under the new vendor namespace. The probe in
+#: :func:`resolve_overlay` adds the legacy ``~/.config/agent-config/agents/``
+#: tree as a read-only fallback for pre-2.4 installs.
+USER_GLOBAL_AGENTS_DIR = user_global_paths.write_target("agents")
+_LEGACY_USER_GLOBAL_AGENTS_DIR = user_global_paths.legacy_xdg_root() / "agents"
 
 
 def resolve_overlay(name: str, kind: str, cwd: Path) -> Path | None:
@@ -83,6 +91,9 @@ def resolve_overlay(name: str, kind: str, cwd: Path) -> Path | None:
     candidates: list[Path] = []
 
     if kind in USER_GLOBAL_OVERLAY_KINDS:
+        # Legacy first, new last — deepest wins, so the new namespace
+        # overrides the legacy path when both happen to exist mid-migration.
+        candidates.append(_LEGACY_USER_GLOBAL_AGENTS_DIR / kind / f"{name}.md")
         candidates.append(USER_GLOBAL_AGENTS_DIR / kind / f"{name}.md")
 
     root = find_project_root(cwd)

package/scripts/_lib/claude_desktop_bundler.py

@@ -0,0 +1,150 @@
+"""Claude Desktop skill ZIP bundler (Phase 4 of event4u-namespace roadmap).
+
+Claude Desktop has no filesystem convention for skills; the Customize →
+Skills UI accepts a ZIP per skill via the Upload button. This module
+walks ``<package_root>/.claude/skills/*`` and produces one
+``<skill-name>.zip`` per directory into ``dest_dir``.
+
+Contract:
+
+- Each ZIP contains ``SKILL.md`` plus every sibling file under the same
+  directory (recursive). Symlinks are dereferenced so the ZIP is
+  self-contained.
+- Exclusions: ``.git*``, ``__pycache__``, ``*.pyc`` — matched on the
+  basename of any path component.
+- A skill folder without a ``SKILL.md`` is skipped (defensive: avoids
+  shipping Claude-Code orchestrator stubs that don't follow the
+  Anthropic skill schema).
+- Writes are atomic via tempfile → ``os.replace``.
+- Idempotent: each ZIP gets a sibling ``<skill-name>.sha256`` recording
+  the manifest digest. If the recomputed digest matches the recorded
+  one, the existing ZIP is left untouched (unless ``force=True``).
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Iterable, Optional
+
+#: Filenames or path components that are never included in a bundle.
+_EXCLUDED_BASENAMES = frozenset({"__pycache__", ".DS_Store"})
+_EXCLUDED_PREFIXES = (".git",)
+_EXCLUDED_SUFFIXES = (".pyc", ".pyo")
+
+
+def _is_excluded(rel_parts: tuple[str, ...]) -> bool:
+    """Return True if any component matches the exclusion lists."""
+    for part in rel_parts:
+        if part in _EXCLUDED_BASENAMES:
+            return True
+        if part.startswith(_EXCLUDED_PREFIXES):
+            return True
+        if part.endswith(_EXCLUDED_SUFFIXES):
+            return True
+    return False
+
+
+def _walk_skill_files(skill_dir: Path) -> list[tuple[Path, tuple[str, ...]]]:
+    """Return ``[(abs_path, rel_parts), ...]`` for every file in the skill.
+
+    Symlinks are followed (``os.walk(..., followlinks=True)``) so a
+    bundle from a symlinked entry under ``.claude/skills/`` contains the
+    actual target content, not a dangling symlink.
+    """
+    out: list[tuple[Path, tuple[str, ...]]] = []
+    resolved = skill_dir.resolve()
+    for root, dirs, files in os.walk(resolved, followlinks=True):
+        root_path = Path(root)
+        rel_root = root_path.relative_to(resolved)
+        # Prune excluded dirs in-place so os.walk skips them.
+        dirs[:] = [d for d in dirs if not _is_excluded((d,))]
+        for fname in files:
+            rel_parts = (*rel_root.parts, fname) if rel_root.parts else (fname,)
+            if _is_excluded(rel_parts):
+                continue
+            out.append((root_path / fname, rel_parts))
+    out.sort(key=lambda item: item[1])
+    return out
+
+
+def _manifest_digest(files: Iterable[tuple[Path, tuple[str, ...]]]) -> str:
+    """Hash sorted (rel_path, content_sha256) pairs into one digest.
+
+    Stable across runs as long as the input set + bytes are stable. Used
+    as the idempotency token written to ``<skill>.sha256``.
+    """
+    h = hashlib.sha256()
+    for abs_path, rel_parts in files:
+        rel = "/".join(rel_parts)
+        h.update(rel.encode("utf-8"))
+        h.update(b"\x00")
+        h.update(hashlib.sha256(abs_path.read_bytes()).digest())
+        h.update(b"\x00")
+    return h.hexdigest()
+
+
+def _atomic_write_zip(
+    zip_path: Path, files: list[tuple[Path, tuple[str, ...]]]
+) -> None:
+    """Write ``files`` into ``zip_path`` atomically (temp + rename)."""
+    zip_path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{zip_path.stem}.", suffix=".zip.tmp", dir=str(zip_path.parent),
+    )
+    os.close(fd)
+    tmp_path = Path(tmp_name)
+    try:
+        with zipfile.ZipFile(tmp_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for abs_path, rel_parts in files:
+                zf.write(abs_path, arcname="/".join(rel_parts))
+        os.replace(tmp_path, zip_path)
+    finally:
+        if tmp_path.exists():
+            tmp_path.unlink()
+
+
+def build_skill_bundles(
+    package_root: Path,
+    dest_dir: Path,
+    force: bool = False,
+    curation: Optional[list[str]] = None,
+) -> list[Path]:
+    """Build per-skill ZIPs under ``dest_dir``.
+
+    Returns the list of ZIP paths that were (re-)written this call. ZIPs
+    skipped because their content digest matched the existing sidecar
+    are not in the returned list (but remain on disk).
+
+    ``curation`` optionally restricts the build to the given skill
+    names; ``None`` bundles every skill folder containing ``SKILL.md``.
+    """
+    skills_root = package_root / ".claude" / "skills"
+    if not skills_root.is_dir():
+        return []
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for entry in sorted(skills_root.iterdir()):
+        if not (entry.is_dir() or entry.is_symlink()):
+            continue
+        skill_name = entry.name
+        if curation is not None and skill_name not in curation:
+            continue
+        skill_md = entry / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        files = _walk_skill_files(entry)
+        if not files:
+            continue
+        digest = _manifest_digest(files)
+        zip_path = dest_dir / f"{skill_name}.zip"
+        digest_path = dest_dir / f"{skill_name}.sha256"
+        recorded = digest_path.read_text(encoding="utf-8").strip() if digest_path.exists() else ""
+        if not force and recorded == digest and zip_path.exists():
+            continue
+        _atomic_write_zip(zip_path, files)
+        digest_path.write_text(digest + "\n", encoding="utf-8")
+        written.append(zip_path)
+    return written

package/scripts/_lib/fs_atomic.py

@@ -0,0 +1,116 @@
+"""Atomic file-write primitive shared by lockfile-schema-v2 writers.
+
+P1.0 of road-to-multi-package-coexistence. Single source of truth for
+crash-safe writes used by ``installed_tools.write_manifest``,
+P1.5 merge tracking, P2.2 uninstall, and P3.x conflict-resolution
+paths. Centralising the mechanism prevents per-phase implementation
+drift (Council amendment, Anthropic 2026-05-12).
+
+Guarantees, in order:
+
+1. Write to ``<path>.tmp.<pid>.<rand>`` in the same directory as the
+   target. Same-directory keeps the final ``os.replace`` atomic on
+   every POSIX filesystem we support; cross-fs renames are not atomic.
+2. ``fsync(tmp_fd)`` flushes the file's data + metadata to disk before
+   we let the temp file become the visible target.
+3. ``os.replace(tmp, path)`` is the atomic rename. Either the old or
+   the new content is visible to readers; never a half-written mix.
+4. ``fsync(parent_dir_fd)`` durably commits the directory entry so a
+   crash immediately after the rename does not resurrect the old file
+   on next boot. Skipped on platforms where directory fsync is
+   unsupported (Windows) — the rename is still atomic from the
+   filesystem's perspective, only durability across power loss is
+   weaker there.
+
+The temp file is always cleaned up on failure, so a raise mid-write
+never leaves orphaned ``.tmp.*`` siblings behind.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Union
+
+__all__ = ["write_atomic"]
+
+
+def write_atomic(
+    path: Union[str, Path],
+    data: Union[str, bytes],
+    *,
+    encoding: str = "utf-8",
+) -> Path:
+    """Atomically write ``data`` to ``path``; return the resolved path.
+
+    ``data`` may be ``str`` (encoded via ``encoding``) or ``bytes``
+    (written verbatim, ``encoding`` ignored). The parent directory is
+    created if missing — callers don't have to ``mkdir`` beforehand.
+
+    On failure (any exception raised by the OS during write / fsync /
+    rename), the temporary file is unlinked and the original target —
+    if any — is untouched. The exception propagates so callers can
+    distinguish disk-full from permission errors etc.
+    """
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    if isinstance(data, str):
+        payload = data.encode(encoding)
+    elif isinstance(data, (bytes, bytearray)):
+        payload = bytes(data)
+    else:
+        raise TypeError(
+            f"write_atomic: data must be str or bytes, got {type(data).__name__}"
+        )
+
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{target.name}.tmp.",
+        dir=str(target.parent),
+    )
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(payload)
+            fh.flush()
+            try:
+                os.fsync(fh.fileno())
+            except OSError:
+                # File-level fsync unsupported (e.g. some tmpfs).
+                # Continue — os.replace is still atomic.
+                pass
+        os.replace(tmp_path, target)
+    except Exception:
+        try:
+            tmp_path.unlink()
+        except OSError:
+            pass
+        raise
+
+    _fsync_dir(target.parent)
+    return target
+
+
+def _fsync_dir(directory: Path) -> None:
+    """Best-effort directory fsync; silent no-op on unsupported platforms.
+
+    Directory fsync is required on POSIX for the rename's durability
+    across power loss. Windows does not expose ``open(dir)`` /
+    ``fsync(dir_fd)`` semantics — the kernel commits the directory
+    entry implicitly. We swallow the OSError there rather than fail
+    the write.
+    """
+    try:
+        dir_fd = os.open(str(directory), os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        try:
+            os.fsync(dir_fd)
+        except OSError:
+            # Some filesystems / mounts reject directory fsync.
+            # The rename is still atomic — durability is weaker but
+            # the write is not corrupted.
+            pass
+    finally:
+        os.close(dir_fd)

package/scripts/_lib/installed_lock.py

@@ -1,4 +1,4 @@
-"""Global-install lockfile at ``~/.config/agent-config/installed.lock``.
+"""Global-install lockfile at ``~/.event4u/agent-config/installed.lock``.
 
 Phase 1.6 of road-to-global-first-install (ADR-007 D5). Records the
 package version that performed the most recent user-scope install plus
@@ -10,6 +10,12 @@ flip in ``.agent-settings.yml``.
 The schema is intentionally minimal YAML so the module can read and
 write without depending on ``pyyaml``. Atomic writes go through
 ``tempfile + os.replace`` per ADR-007 risk-mitigation row.
+
+Path resolution is delegated to :mod:`scripts._lib.user_global_paths`
+(Phase 1 of road-to-event4u-namespace-and-claude-desktop.md): writes
+land at ``~/.event4u/agent-config/installed.lock``; reads fall back to
+the legacy ``~/.config/agent-config/installed.lock`` if the new path
+is missing, so pre-2.4 installs keep working during the transition.
 """
 from __future__ import annotations
 
@@ -21,10 +27,22 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from scripts._lib import user_global_paths
+
 LOCKFILE_ENV = "AGENT_CONFIG_INSTALLED_LOCK"
-DEFAULT_LOCKFILE = Path.home() / ".config" / "agent-config" / "installed.lock"
 SCHEMA_VERSION = 1
 
+
+def _default_lockfile() -> Path:
+    """Canonical write target for the lockfile (new namespace)."""
+    return user_global_paths.write_target("installed.lock")
+
+
+# Module-level constant retained for back-compat with importers that read
+# ``installed_lock.DEFAULT_LOCKFILE`` directly. Derived from the helper so
+# the path tracks any future override of ``event4u_root()``.
+DEFAULT_LOCKFILE = _default_lockfile()
+
 _VERSION_RE = re.compile(r'^\s*agent_config_version\s*:\s*"?([^"\s]+)"?\s*$')
 _SCHEMA_RE = re.compile(r"^\s*schema_version\s*:\s*(\d+)\s*$")
 _INSTALLED_AT_RE = re.compile(r'^\s*installed_at\s*:\s*"?([^"\s]+)"?\s*$')
@@ -32,12 +50,27 @@ _TOOL_RE = re.compile(r"^\s*-\s*([A-Za-z0-9_\-.]+)\s*$")
 
 
 def lockfile_path(env: Optional[dict] = None) -> Path:
-    """Return the active lockfile path, honoring the env override."""
+    """Return the active lockfile path, honoring the env override.
+
+    Resolution order:
+
+    1. ``$AGENT_CONFIG_INSTALLED_LOCK``  — explicit full-path override.
+    2. ``~/.event4u/agent-config/installed.lock`` if it exists on disk.
+    3. ``~/.config/agent-config/installed.lock``  (legacy fallback, read-only).
+    4. Canonical write target under the new namespace (Step 2 fallthrough).
+
+    Writers always end up at (4) when no lockfile exists yet; readers
+    benefit from (3) so pre-2.4 installs keep working while the
+    migration shim has not yet run.
+    """
     env = env if env is not None else os.environ
     override = env.get(LOCKFILE_ENV)
     if override:
         return Path(override).expanduser()
-    return DEFAULT_LOCKFILE
+    resolved = user_global_paths.resolve_with_fallback("installed.lock", env=env)
+    if resolved is not None:
+        return resolved
+    return user_global_paths.write_target("installed.lock", env=env)
 
 
 def read_lockfile(path: Optional[Path] = None) -> Optional[dict]: