@event4u/agent-config 3.0.0 → 3.1.1

package/scripts/_lib/agent_src.py

@@ -0,0 +1,157 @@
+"""Locate artefact source roots across the monorepo physical layout.
+
+Phase 4 of the monorepo migration (ADR-017) physically moves source
+artefacts out of the flat ``.agent-src.uncompressed/`` directory into
+``packages/core/.agent-src.uncompressed/`` and
+``packages/pack-*/.agent-src.uncompressed/`` trees. This helper hides
+that decision from every scanner so they keep working pre-move and
+post-move with the same call shape.
+
+Contract:
+
+- ``artefact_roots()`` returns every directory that contains source
+  ``.md`` artefacts. Pre-move that is ``.agent-src.uncompressed/`` at
+  the repo root. Post-move it is every ``packages/*/.agent-src.uncompressed/``.
+  Both can coexist during the migration window.
+- ``iter_artefacts()`` yields every source ``.md`` path under those roots.
+- ``logical_relpath(p)`` returns the artefact's stable identity path
+  (e.g. ``skills/laravel/SKILL.md``), independent of which physical
+  root contains it. This is what manifests, hash maps, and projections
+  use as the artefact key.
+- ``strip_source_prefix(p)`` returns the same as ``logical_relpath``
+  but accepts repo-relative POSIX strings (used by the compressor's
+  output-path computation and the LEGACY_SRC_PREFIX logic).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator
+
+ROOT = Path(__file__).resolve().parents[2]
+LEGACY_SRC = ROOT / ".agent-src.uncompressed"
+PACKAGES = ROOT / "packages"
+
+# Repo-relative POSIX path prefixes that anchor an artefact source tree.
+# Order: legacy first (kept until the move lands), then packages/*. Each
+# entry is the prefix that gets stripped to obtain the logical path.
+_LEGACY_PREFIX = ".agent-src.uncompressed/"
+_PACKAGE_SUFFIX = "/.agent-src.uncompressed/"
+
+
+def artefact_roots() -> list[Path]:
+    """Every existing directory that contains source ``.md`` artefacts.
+
+    Returns at most one ``.agent-src.uncompressed/`` root (legacy) plus
+    one root per ``packages/*/`` subdirectory that exposes its own
+    ``.agent-src.uncompressed/`` tree. Order is stable: legacy first,
+    then ``packages/`` entries sorted alphabetically.
+    """
+    roots: list[Path] = []
+    if LEGACY_SRC.exists():
+        roots.append(LEGACY_SRC)
+    if PACKAGES.exists():
+        for pkg in sorted(PACKAGES.iterdir()):
+            sub = pkg / ".agent-src.uncompressed"
+            if sub.is_dir():
+                roots.append(sub)
+    return roots
+
+
+def iter_artefacts(suffix: str = ".md") -> Iterator[Path]:
+    """Yield every artefact file under every active source root.
+
+    Files are returned in deterministic order: roots in the order from
+    ``artefact_roots()``, files within each root sorted by path. Symlinks
+    and non-files are skipped.
+    """
+    for root in artefact_roots():
+        for p in sorted(root.rglob(f"*{suffix}")):
+            if p.is_file():
+                yield p
+
+
+def iter_all_sources() -> Iterator[tuple[Path, str]]:
+    """Yield ``(physical_path, logical_relpath)`` for every file under every root.
+
+    Same deterministic order as :func:`iter_artefacts` but covers *all*
+    files (md and non-md) and pre-computes the logical relative path.
+    If a logical path appears in multiple roots (legacy + packages/ during
+    the move window) the first wins — caller is responsible for ensuring
+    that does not happen post-move.
+    """
+    seen: set[str] = set()
+    for root in artefact_roots():
+        for p in sorted(root.rglob("*")):
+            if not p.is_file():
+                continue
+            try:
+                rel = p.relative_to(root).as_posix()
+            except ValueError:
+                continue
+            if rel in seen:
+                continue
+            seen.add(rel)
+            yield p, rel
+
+
+def resolve_logical(logical_rel: str) -> Path | None:
+    """Return the physical path that backs ``logical_rel``, or ``None``.
+
+    Walks :func:`artefact_roots` in order and returns the first hit.
+    """
+    rel = logical_rel.replace("\\", "/").lstrip("/")
+    for root in artefact_roots():
+        p = root / rel
+        if p.exists():
+            return p
+    return None
+
+
+def logical_relpath(path: Path) -> str:
+    """Return the artefact's logical identity path (POSIX, no prefix).
+
+    Examples:
+        ``.agent-src.uncompressed/skills/laravel/SKILL.md``
+            → ``skills/laravel/SKILL.md``
+        ``packages/pack-laravel/.agent-src.uncompressed/skills/laravel/SKILL.md``
+            → ``skills/laravel/SKILL.md``
+        ``packages/core/.agent-src.uncompressed/rules/scope-control.md``
+            → ``rules/scope-control.md``
+
+    Raises ``ValueError`` if ``path`` is not under any known source root.
+    """
+    p = path.resolve() if path.is_absolute() else (ROOT / path).resolve()
+    for root in artefact_roots():
+        try:
+            return p.relative_to(root.resolve()).as_posix()
+        except ValueError:
+            continue
+    raise ValueError(f"path is not under any artefact root: {path}")
+
+
+def strip_source_prefix(rel: str) -> str | None:
+    """Strip the ``.agent-src.uncompressed/`` anchor from a repo-relative path.
+
+    Accepts both the legacy flat layout and the monorepo packages layout.
+    Returns ``None`` if the path is not under any source root.
+
+    Examples:
+        ``".agent-src.uncompressed/rules/foo.md"`` → ``"rules/foo.md"``
+        ``"packages/core/.agent-src.uncompressed/rules/foo.md"`` → ``"rules/foo.md"``
+        ``"packages/pack-laravel/.agent-src.uncompressed/skills/x/SKILL.md"``
+            → ``"skills/x/SKILL.md"``
+        ``"docs/architecture.md"`` → ``None``
+    """
+    posix = rel.replace("\\", "/")
+    if posix.startswith(_LEGACY_PREFIX):
+        return posix[len(_LEGACY_PREFIX):]
+    if posix.startswith("packages/"):
+        idx = posix.find(_PACKAGE_SUFFIX)
+        if idx != -1:
+            return posix[idx + len(_PACKAGE_SUFFIX):]
+    return None
+
+
+def is_artefact_path(rel: str) -> bool:
+    """``True`` if a repo-relative POSIX path sits under any source root."""
+    return strip_source_prefix(rel) is not None

package/scripts/agent-config

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
-# Deprecated direct invocation.
+# Maintainer / source-checkout entry point.
 #
-# Public entry point is now `dist/cli/agent-config.js` via
-# `npx @event4u/agent-config`. This shim survives one minor cycle
-# then is removed (see ADR-012 + roadmap typescript-cli-and-local-gui-foundation).
+# Public consumer entry point is `dist/cli/agent-config.js` via
+# `npx @event4u/agent-config` — that's the path documented in README.
+# This shim is the canonical local invocation for maintainers working
+# in a source checkout, where `npx` can't resolve the bin without a
+# prior `npm link` (no `node_modules/.bin/agent-config` symlink).
 #
 # Behaviour:
 #   - If dist/cli/agent-config.js exists  → forward to the TS binary
@@ -12,8 +14,14 @@
 #     tests, work_engine harness — that pre-date the TS shell).
 #   - Else → error with a one-line build hint
 #
+# Deprecation warning is only emitted when this script is invoked from
+# an installed npm package (i.e. not a source-repo checkout). Source-
+# checkout detection: `$here/../src/cli/registry.ts` exists. Maintainers
+# running `./agent-config` from the repo root see no warning.
+#
 # Set AGENT_CONFIG_QUIET_DEPRECATION=1 to suppress the deprecation
-# warning (used by test harnesses that pin the stderr surface).
+# warning unconditionally (used by test harnesses that pin the stderr
+# surface).
 set -euo pipefail
 
 # Resolve $0 through symlinks (maintainer repo root has a ./agent-config
@@ -28,8 +36,11 @@ done
 here="$(cd -- "$(dirname -- "$src")" && pwd)"
 ts_entry="$here/../dist/cli/agent-config.js"
 legacy_entry="$here/_dispatch.bash"
+source_marker="$here/../src/cli/registry.ts"
 
-if [[ "${AGENT_CONFIG_QUIET_DEPRECATION:-0}" != "1" ]]; then
+# Suppress the deprecation warning when invoked from a source checkout
+# (maintainer path) — `src/` is not shipped in the published tarball.
+if [[ "${AGENT_CONFIG_QUIET_DEPRECATION:-0}" != "1" && ! -f "$source_marker" ]]; then
   echo "warning: scripts/agent-config is deprecated; use 'npx @event4u/agent-config' instead" >&2
 fi
 

package/scripts/audit_skill_descriptions.py

@@ -27,7 +27,10 @@ from dataclasses import asdict, dataclass, field
 from pathlib import Path
 from typing import List
 
-DEFAULT_ROOT = Path(".agent-src.uncompressed/skills")
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+DEFAULT_ROOT: Path | None = None
 MIN_LENGTH = 150
 # Mirrors scripts/skill_linter.py `description_too_long` threshold.
 MAX_LENGTH = 200
@@ -149,14 +152,23 @@ def render_text(findings: List[Finding], worst_only: bool) -> str:
 
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--root", type=Path, default=DEFAULT_ROOT)
+    parser.add_argument("--root", type=Path, default=None)
     parser.add_argument("--json", action="store_true", help="emit JSON")
     parser.add_argument("--full", action="store_true", help="show all flagged, not just top 15")
     args = parser.parse_args()
-    if not args.root.exists():
-        print(f"error: {args.root} does not exist", file=sys.stderr)
-        return 2
-    findings = collect_findings(args.root)
+    if args.root is not None:
+        if not args.root.exists():
+            print(f"error: {args.root} does not exist", file=sys.stderr)
+            return 2
+        roots = [args.root]
+    else:
+        roots = [r / "skills" for r in artefact_roots() if (r / "skills").is_dir()]
+        if not roots:
+            print("error: no skills/ directories found across artefact roots", file=sys.stderr)
+            return 2
+    findings: List[Finding] = []
+    for r in roots:
+        findings.extend(collect_findings(r))
     if args.json:
         print(json.dumps([asdict(f) for f in findings], indent=2))
     else: