@event4u/agent-config 1.9.1 → 1.12.0

package/scripts/check_portability.py

@@ -248,10 +248,137 @@ def check_file(filepath: Path, patterns: list, allowlist: list) -> List[Violatio
     return violations
 
 
+# ── Task-command detector ───────────────────────────────────────────────
+# Artefact files shipped in the package must not reference `task <name>`
+# invocations (per augment-portability rule). Consumer projects may not
+# have Taskfile installed; agents must use direct script paths instead.
+ARTIFACT_SUBDIRS = ["skills", "rules", "commands", "guidelines", "personas", "contexts"]
+
+# Inline code: `task foo` or `task foo-bar` or `task foo:bar`
+_TASK_INLINE_RE = re.compile(r"`task\s+([a-z][a-z0-9:_-]*)`")
+# Code-fence line: "task foo …" (optional leading whitespace)
+_TASK_FENCE_RE = re.compile(r"^\s*task\s+([a-z][a-z0-9:_-]*)\b")
+
+# Files that legitimately document the forbidden pattern — they define
+# the rule itself. Any path containing one of these suffixes is skipped
+# by the task-invocation detector (but still scanned for layer 1 + 2).
+_TASK_DETECTOR_SKIP = (
+    "rules/augment-portability.md",
+)
+
+
+def check_task_invocations(filepath: Path) -> List[Violation]:
+    """Flag `task <cmd>` invocations in inline code or code fence lines."""
+    violations: List[Violation] = []
+    try:
+        lines = filepath.read_text(encoding="utf-8").splitlines()
+    except Exception:
+        return violations
+
+    in_code_block = False
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            continue
+        if in_code_block:
+            m = _TASK_FENCE_RE.search(line)
+            if m:
+                violations.append(Violation(
+                    file=str(filepath), line=i, match=m.group(0).strip(),
+                    pattern_name="task-invocation", severity="error",
+                    context=stripped,
+                ))
+        else:
+            for m in _TASK_INLINE_RE.finditer(line):
+                violations.append(Violation(
+                    file=str(filepath), line=i, match=m.group(0),
+                    pattern_name="task-invocation", severity="error",
+                    context=stripped,
+                ))
+
+    return violations
+
+
+# ── Direct script-invocation detector ───────────────────────────────────
+# Artefacts shipped to consumers must use the `./agent-config` CLI for
+# commands it already covers. Direct `python3 scripts/…` / `bash scripts/…`
+# invocations only work inside the package repo, not in a consumer project
+# where the scripts live under node_modules/ or vendor/.
+#
+# Each entry: (regex, suggested replacement). Patterns match inside inline
+# backticks OR anywhere on a code-fence line.
+_CLI_INVOCATION_MAP: list[tuple[re.Pattern, str]] = [
+    (
+        re.compile(r"python3\s+scripts/mcp_render\.py\s+--check\b"),
+        "./agent-config mcp:check",
+    ),
+    (
+        re.compile(r"python3\s+scripts/mcp_render\.py\b"),
+        "./agent-config mcp:render",
+    ),
+    (
+        re.compile(r"python3\s+\.(?:agent-src|augment)/scripts/update_roadmap_progress\.py\s+--check\b"),
+        "./agent-config roadmap:progress-check",
+    ),
+    (
+        re.compile(r"python3\s+\.(?:agent-src|augment)/scripts/update_roadmap_progress\.py\b"),
+        "./agent-config roadmap:progress",
+    ),
+    (
+        re.compile(r"bash\s+scripts/first-run\.sh\b"),
+        "./agent-config first-run",
+    ),
+]
+
+# Paths that legitimately document the raw invocations (e.g. the CLI's
+# own help, the portability rule that defines the mapping).
+_CLI_DETECTOR_SKIP = (
+    "rules/augment-portability.md",
+)
+
+
+def check_cli_invocations(filepath: Path) -> List[Violation]:
+    """Flag direct script invocations that should go through `./agent-config`."""
+    violations: List[Violation] = []
+    try:
+        lines = filepath.read_text(encoding="utf-8").splitlines()
+    except Exception:
+        return violations
+
+    in_code_block = False
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            continue
+
+        # In prose lines, only check content inside inline `...` spans to
+        # avoid false positives in running text. In code fences, check the
+        # whole line.
+        if in_code_block:
+            segments = [line]
+        else:
+            segments = re.findall(r"`([^`]+)`", line)
+
+        for seg in segments:
+            for pattern, replacement in _CLI_INVOCATION_MAP:
+                m = pattern.search(seg)
+                if m:
+                    violations.append(Violation(
+                        file=str(filepath), line=i, match=m.group(0),
+                        pattern_name=f"cli-bypass → use `{replacement}`",
+                        severity="error", context=stripped,
+                    ))
+                    break  # one hit per segment is enough
+
+    return violations
+
+
 def scan_all(root: Path) -> tuple[List[Violation], list[str]]:
     """Scan all package files for portability violations. Returns (violations, detected_identifiers).
 
-    Scanning has two layers:
+    Scanning has four layers:
     1. Auto-detected identifiers — applied to `.agent-src/` and
        `.agent-src.uncompressed/` only. The package's own root AGENTS.md and
        copilot-instructions.md are meta docs ABOUT the package, so the
@@ -259,6 +386,13 @@ def scan_all(root: Path) -> tuple[List[Violation], list[str]]:
     2. Optional FORBIDDEN_IDENTIFIERS from AGENT_CONFIG_BLOCKLIST —
        applied to every scanned file, including the root files. Catches
        leakage from renamed or adjacent projects in downstream forks.
+    3. `task <name>` invocations inside artefact subdirs — skills, rules,
+       commands, guidelines, personas, contexts. These shipped artefacts
+       run in consumer projects that may not have Taskfile installed.
+    4. Direct script invocations that bypass the `./agent-config` CLI
+       (e.g. `python3 scripts/mcp_render.py`). Same artefact-subdir scope
+       as layer 3; consumer projects only have the package under
+       `node_modules/` or `vendor/`, so the raw paths never resolve.
     """
     patterns, detected = _compile_patterns(root)
     forbidden = _compile_forbidden_patterns()
@@ -279,6 +413,22 @@ def scan_all(root: Path) -> tuple[List[Violation], list[str]]:
         if f.is_file():
             violations.extend(check_file(f, forbidden, allowlist))
 
+    # Layer 3 + 4: artefact-subdir-only scans (task invocations, CLI bypass)
+    for scan_dir in SCAN_DIRS:
+        base = root / scan_dir
+        if not base.exists():
+            continue
+        for sub in ARTIFACT_SUBDIRS:
+            d = base / sub
+            if not d.exists():
+                continue
+            for f in sorted(d.rglob("*.md")):
+                path_str = str(f)
+                if not any(path_str.endswith(skip) for skip in _TASK_DETECTOR_SKIP):
+                    violations.extend(check_task_invocations(f))
+                if not any(path_str.endswith(skip) for skip in _CLI_DETECTOR_SKIP):
+                    violations.extend(check_cli_invocations(f))
+
     return violations, detected
 
 

package/scripts/install.py

@@ -223,11 +223,17 @@ def _parse_legacy_settings(text: str) -> "tuple[dict, list]":
     return values, unknown
 
 
+_BARE_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
 def _yaml_scalar(value: str) -> str:
     """Format a string value as a YAML scalar with minimal quoting.
 
-    Booleans and non-negative integers are emitted unquoted; everything
-    else is double-quoted so the migrated file is unambiguous.
+    Booleans and non-negative integers are emitted unquoted. Bare
+    lowercase identifiers (``per_turn``, ``rotate``, ``getters_setters``
+    — the shape of profile values and enum-like strings) are emitted
+    unquoted so `sync_agent_settings.py` stays idempotent against its
+    own output. Everything else is double-quoted.
     """
     if value == "":
         return '""'
@@ -235,6 +241,8 @@ def _yaml_scalar(value: str) -> str:
         return value
     if value.isdigit():
         return value
+    if _BARE_ID_RE.match(value):
+        return value
     # Escape backslashes and double-quotes, then wrap
     escaped = value.replace("\\", "\\\\").replace('"', '\\"')
     return f'"{escaped}"'
@@ -330,6 +338,44 @@ def _migrate_legacy_if_present(project_root: Path, template_body: str) -> "str |
 
 # --- Bridge generators ---
 
+def _parse_profile_ini(path: Path) -> "dict[str, str]":
+    """Parse a simple key=value profile preset (comments start with ; or #)."""
+    values: "dict[str, str]" = {}
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith(";") or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        values[key.strip()] = val.strip()
+    return values
+
+
+_PLACEHOLDER_RE = re.compile(r"__[A-Z][A-Z0-9_]*__")
+
+
+def _render_template(template: str, profile_values: "dict[str, str]") -> str:
+    """Substitute __UPPER_KEY__ placeholders using ini values.
+
+    Each ini key `foo_bar` maps to the `__FOO_BAR__` placeholder. Fails
+    if any placeholder remains unfilled — catches typos and missing
+    profile entries early.
+    """
+    body = template
+    for key, value in profile_values.items():
+        placeholder = f"__{key.upper()}__"
+        if placeholder in body:
+            body = body.replace(placeholder, value)
+    leftover = sorted(set(_PLACEHOLDER_RE.findall(body)))
+    if leftover:
+        fail(
+            "Template has unfilled placeholders after profile render: "
+            + ", ".join(leftover)
+        )
+    return body
+
+
 def ensure_agent_settings(project_root: Path, package_root: Path, profile: str, force: bool) -> None:
     target = project_root / SETTINGS_FILE
     profile_source = package_root / "config" / "profiles" / f"{profile}.ini"
@@ -343,7 +389,13 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
     template = template_source.read_text(encoding="utf-8")
     if COST_PROFILE_PLACEHOLDER not in template:
         fail(f"Template is missing placeholder {COST_PROFILE_PLACEHOLDER}")
-    template_body = template.replace(COST_PROFILE_PLACEHOLDER, profile)
+    profile_values = _parse_profile_ini(profile_source)
+    if profile_values.get("cost_profile") != profile:
+        fail(
+            f"Profile preset {profile_source.name} has cost_profile="
+            f"{profile_values.get('cost_profile')!r} but --profile={profile}"
+        )
+    template_body = _render_template(template, profile_values)
 
     legacy_target = project_root / LEGACY_SETTINGS_FILE
     if legacy_target.is_file() and target.exists():

package/scripts/install.sh

@@ -19,7 +19,6 @@ set -euo pipefail
 
 # --- Configuration ---
 COPY_DIRS="rules"  # Subdirectories where files must be real copies (space-separated)
-GITIGNORE_MARKER="# event4u/agent-config"
 
 # Rules that are internal to the agent-config package and should NOT be shipped to consumers.
 # These are only relevant when developing the agent-config package itself.
@@ -35,6 +34,7 @@ TARGET_DIR=""
 DRY_RUN=false
 VERBOSE=false
 QUIET=false
+SKIP_GITIGNORE=false
 
 # --- Logging ---
 log_info()    { $QUIET || echo "  ✅  $*"; }
@@ -51,6 +51,7 @@ parse_args() {
             --dry-run) DRY_RUN=true; shift ;;
             --verbose) VERBOSE=true; shift ;;
             --quiet)   QUIET=true; shift ;;
+            --skip-gitignore) SKIP_GITIGNORE=true; shift ;;
             --help|-h) show_help; exit 0 ;;
             *) log_error "Unknown argument: $1"; show_help; exit 1 ;;
         esac
@@ -103,6 +104,7 @@ Options:
   --dry-run        Show what would happen without making changes
   --verbose        Show detailed output
   --quiet          Suppress all output except errors
+  --skip-gitignore Do not touch the target project's .gitignore
   --help, -h       Show this help
 
 Environment:
@@ -561,39 +563,63 @@ copy_if_missing() {
     cp "$source" "$target"
 }
 
-# Ensure .gitignore contains agent-config entries
+# Ensure .gitignore contains the managed agent-config block.
+# Delegates to scripts/sync_gitignore.py so the installer and the
+# standalone /sync-gitignore command share one source of truth
+# (config/gitignore-block.txt). Honors --dry-run and --skip-gitignore.
 ensure_gitignore() {
     local project_root="$1"
     local gitignore="$project_root/.gitignore"
+    local sync_script="$SOURCE_DIR/scripts/sync_gitignore.py"
+    local template="$SOURCE_DIR/config/gitignore-block.txt"
 
+    if $SKIP_GITIGNORE; then
+        log_verbose "skip .gitignore (--skip-gitignore)"
+        return 0
+    fi
+
+    # Match the pre-refactor behavior: don't create .gitignore in a
+    # project that doesn't use git / doesn't already have one.
     if [[ ! -f "$gitignore" ]]; then
         return 0
     fi
 
-    if grep -qF "$GITIGNORE_MARKER" "$gitignore"; then
-        return 0  # Already present
+    if [[ ! -f "$sync_script" || ! -f "$template" ]]; then
+        log_warn ".gitignore sync skipped — script or template missing"
+        return 0
+    fi
+
+    local args=(--path "$gitignore" --template "$template" --quiet)
+    $DRY_RUN && args+=(--dry-run)
+
+    if python3 "$sync_script" "${args[@]}" >/dev/null 2>&1; then
+        log_verbose ".gitignore synced"
+    else
+        log_warn ".gitignore sync failed (exit $?)"
+    fi
+}
+
+# Install the consumer-facing CLI wrapper `./agent-config` at the project
+# root. Gitignored, overwritten on every install, delegates to the master
+# CLI shipped in the package (node_modules or vendor).
+install_cli_wrapper() {
+    local project_root="$1"
+    local template="$SOURCE_DIR/templates/agent-config-wrapper.sh"
+    local target="$project_root/agent-config"
+
+    if [[ ! -f "$template" ]]; then
+        log_verbose "CLI wrapper template missing: $template — skipping"
+        return 0
     fi
 
     if $DRY_RUN; then
-        log_verbose "append .gitignore block"
+        log_verbose "install CLI wrapper → $target"
         return
     fi
 
-    cat >> "$gitignore" << 'BLOCK'
-
-# event4u/agent-config
-# Agent config — symlinked from vendor (auto-managed)
-.augment/skills/
-.augment/commands/
-.augment/guidelines/
-.augment/templates/
-.augment/contexts/
-.augment/scripts/
-.augment/README.md
-
-# Agent config — NOT ignored (real copies, may contain project overrides)
-# .augment/rules/
-BLOCK
+    cp "$template" "$target"
+    chmod +x "$target"
+    log_info "Installed ./agent-config wrapper"
 }
 
 # --- Main ---
@@ -626,7 +652,10 @@ main() {
     generate_windsurfrules "$TARGET_DIR"
     create_gemini_md "$TARGET_DIR"
 
-    # 5. Manage .gitignore
+    # 5. Install consumer CLI wrapper (gitignored, overwritten on every install)
+    install_cli_wrapper "$TARGET_DIR"
+
+    # 6. Manage .gitignore
     ensure_gitignore "$TARGET_DIR"
 
     echo ""

package/scripts/mcp_render.py

@@ -31,16 +31,23 @@ import sys
 from pathlib import Path
 from typing import Any
 
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-SOURCE_FILE = PROJECT_ROOT / "mcp.json"
-
 ENV_PLACEHOLDER = re.compile(r"\$\{env:([^}]+)\}")
 
-# In-project targets. Claude Desktop is user-scope, opt-in via --claude-desktop.
-IN_PROJECT_TARGETS: dict[str, Path] = {
-    "cursor": PROJECT_ROOT / ".cursor" / "mcp.json",
-    "windsurf": PROJECT_ROOT / ".windsurf" / "mcp.json",
-}
+# Project root defaults to the current working directory so the renderer
+# works both for package maintainers (running from the package root via
+# Taskfile) and for consumer projects (running via `./agent-config
+# mcp:render` from their own repo root). Override with --project-root.
+def default_project_root() -> Path:
+    return Path.cwd().resolve()
+
+
+def in_project_targets(project_root: Path) -> dict[str, Path]:
+    return {
+        "cursor": project_root / ".cursor" / "mcp.json",
+        "windsurf": project_root / ".windsurf" / "mcp.json",
+    }
+
+
 CLAUDE_DESKTOP_TARGET = Path.home() / ".config" / "claude-desktop" / "claude_desktop_config.json"
 
 
@@ -104,20 +111,25 @@ def write_target(path: Path, content: dict[str, Any]) -> None:
     path.write_text(serialized, encoding="utf-8")
 
 
-def collect_targets(include_claude_desktop: bool) -> dict[str, Path]:
-    targets = dict(IN_PROJECT_TARGETS)
+def collect_targets(project_root: Path, include_claude_desktop: bool) -> dict[str, Path]:
+    targets = dict(in_project_targets(project_root))
     if include_claude_desktop:
         targets["claude-desktop"] = CLAUDE_DESKTOP_TARGET
     return targets
 
 
+def resolve_source(args: argparse.Namespace, project_root: Path) -> Path:
+    return Path(args.source) if args.source else project_root / "mcp.json"
+
+
 def cmd_render(args: argparse.Namespace) -> int:
-    data = load_source(Path(args.source))
+    project_root = Path(args.project_root).resolve() if args.project_root else default_project_root()
+    data = load_source(resolve_source(args, project_root))
     rendered, missing = render(data)
     if missing:
         print(format_missing_report(missing), file=sys.stderr)
         return 1
-    targets = collect_targets(args.claude_desktop)
+    targets = collect_targets(project_root, args.claude_desktop)
     for name, path in targets.items():
         write_target(path, rendered)
         print(f"✅  {name:16} → {path}")
@@ -125,20 +137,21 @@ def cmd_render(args: argparse.Namespace) -> int:
 
 
 def cmd_check(args: argparse.Namespace) -> int:
-    data = load_source(Path(args.source))
+    project_root = Path(args.project_root).resolve() if args.project_root else default_project_root()
+    data = load_source(resolve_source(args, project_root))
     rendered, missing = render(data)
     if missing:
         print(format_missing_report(missing), file=sys.stderr)
         return 1
     serialized = json.dumps(rendered, indent=2, sort_keys=True) + "\n"
-    targets = collect_targets(args.claude_desktop)
+    targets = collect_targets(project_root, args.claude_desktop)
     diffs = []
     for name, path in targets.items():
         actual = path.read_text(encoding="utf-8") if path.exists() else ""
         if actual != serialized:
             diffs.append((name, path))
     if diffs:
-        print("❌  Targets out of date (run `task mcp:render`):", file=sys.stderr)
+        print("❌  Targets out of date (run `./agent-config mcp:render`):", file=sys.stderr)
         for name, path in diffs:
             print(f"  - {name}: {path}", file=sys.stderr)
         return 1
@@ -148,7 +161,8 @@ def cmd_check(args: argparse.Namespace) -> int:
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Render mcp.json → per-tool config files.")
-    parser.add_argument("--source", default=str(SOURCE_FILE), help="Source mcp.json (default: repo root)")
+    parser.add_argument("--source", default=None, help="Source mcp.json (default: <project-root>/mcp.json)")
+    parser.add_argument("--project-root", default=None, help="Project root for resolving source and targets (default: CWD)")
     parser.add_argument("--claude-desktop", action="store_true", help="Also write Claude Desktop user-scope config")
     parser.add_argument("--check", action="store_true", help="Dry-run; exit non-zero if targets are stale")
     args = parser.parse_args(argv)