@event4u/agent-config 1.9.1 → 1.13.0

package/scripts/sync_agent_settings.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Sync `.agent-settings.yml` against the template + profile.
+
+Applies the section-aware merge rules documented in
+`.agent-src.uncompressed/guidelines/agent-infra/layered-settings.md`:
+
+- Template section order always wins — reorder keys to match.
+- Existing user scalar values are preserved verbatim (as parsed).
+- Missing keys land with their template / profile default.
+- Template comments replace user comments in the same position.
+- Unknown user keys (not in the template) are preserved in a trailing
+  `_user:` block so custom additions never get silently dropped.
+
+Idempotent — writing a file that is already in sync is a no-op.
+
+Usage:
+    python3 scripts/sync_agent_settings.py                       # write (default)
+    python3 scripts/sync_agent_settings.py --dry-run             # show diff, no write
+    python3 scripts/sync_agent_settings.py --check               # exit 2 on drift (for CI)
+    python3 scripts/sync_agent_settings.py --profile balanced    # use a specific profile
+    python3 scripts/sync_agent_settings.py --path path/to/.agent-settings.yml
+
+Exit codes:
+    0 — already in sync, or changes applied (or --dry-run ran cleanly)
+    2 — drift detected under --check, or invalid arguments / missing files
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import install as _install  # noqa: E402 — shares _yaml_scalar + _replace_template_value
+
+try:
+    import yaml  # type: ignore
+except ImportError:
+    print("error: PyYAML not installed (pip install pyyaml)", file=sys.stderr)
+    sys.exit(2)
+
+DEFAULT_SETTINGS = ".agent-settings.yml"
+DEFAULT_TEMPLATE = Path(__file__).resolve().parent.parent / "config" / "agent-settings.template.yml"
+DEFAULT_PROFILE_DIR = Path(__file__).resolve().parent.parent / "config" / "profiles"
+
+
+def _flatten(data: dict, prefix: str = "") -> dict[str, object]:
+    """Flatten nested dicts to dotted keys — one level of nesting supported."""
+    out: dict[str, object] = {}
+    for key, value in data.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, dict):
+            for sub_key, sub_val in value.items():
+                out[f"{path}.{sub_key}"] = sub_val
+        else:
+            out[path] = value
+    return out
+
+
+def _as_scalar_text(value: object) -> str:
+    """Normalize a parsed YAML value to the raw string form expected by
+    `install._replace_template_value` — which re-quotes via `_yaml_scalar`
+    internally, so we must pass the *unquoted* payload here."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _template_keys(template_body: str) -> set[str]:
+    """Return the set of dotted keys declared by the rendered template."""
+    data = yaml.safe_load(template_body) or {}
+    if not isinstance(data, dict):
+        return set()
+    return set(_flatten(data).keys())
+
+
+def _apply_user_values(template_body: str, user_flat: dict[str, object]) -> str:
+    """Overlay every known user value on the rendered template body."""
+    body = template_body
+    for dotted, value in user_flat.items():
+        body = _install._replace_template_value(body, dotted, _as_scalar_text(value))
+    return body
+
+
+def _append_unknown(body: str, user_flat: dict[str, object], known: set[str]) -> str:
+    """Emit user keys that have no home in the template under `_user:`."""
+    unknown = sorted(k for k in user_flat if k not in known)
+    if not unknown:
+        return body
+    lines = [
+        "",
+        "# Unknown keys preserved by sync_agent_settings.py — review and move",
+        "# them into the template or drop them.",
+        "_user:",
+    ]
+    for key in unknown:
+        lines.append(f"  {key}: {_install._yaml_scalar(_as_scalar_text(user_flat[key]))}")
+    suffix = "\n".join(lines) + "\n"
+    return body + (suffix if body.endswith("\n") else "\n" + suffix)
+
+
+def render_target(template_body: str, user_data: dict) -> str:
+    """Return the desired `.agent-settings.yml` body for the given user data."""
+    user_flat = _flatten(user_data) if user_data else {}
+    known = _template_keys(template_body)
+    body = _apply_user_values(template_body, user_flat)
+    return _append_unknown(body, user_flat, known)
+
+
+def load_profile(profile_dir: Path, profile: str) -> dict[str, str]:
+    profile_source = profile_dir / f"{profile}.ini"
+    if not profile_source.is_file():
+        raise FileNotFoundError(f"profile not found: {profile_source}")
+    return _install._parse_profile_ini(profile_source)
+
+
+def load_template(path: Path, profile_values: dict[str, str]) -> str:
+    if not path.is_file():
+        raise FileNotFoundError(f"template not found: {path}")
+    return _install._render_template(path.read_text(encoding="utf-8"), profile_values)
+
+
+def load_user(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def render_diff(old_text: str, new_text: str, path: str) -> str:
+    return "".join(difflib.unified_diff(
+        old_text.splitlines(keepends=True),
+        new_text.splitlines(keepends=True),
+        fromfile=path, tofile=path, n=3,
+    ))
+
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--path", default=DEFAULT_SETTINGS,
+                    help=f"target settings file (default: ./{DEFAULT_SETTINGS})")
+    ap.add_argument("--template", default=str(DEFAULT_TEMPLATE),
+                    help="path to the settings template")
+    ap.add_argument("--profile", default=None,
+                    help="cost_profile preset (minimal|balanced|full). "
+                         "Default: inferred from target, else 'minimal'")
+    ap.add_argument("--profile-dir", default=str(DEFAULT_PROFILE_DIR),
+                    help="directory containing profile .ini files")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="print diff; do not modify the file")
+    ap.add_argument("--check", action="store_true",
+                    help="exit 2 if the target is out of sync (no writes)")
+    ap.add_argument("--quiet", action="store_true",
+                    help="suppress summary on success")
+    args = ap.parse_args(argv)
+
+    target = Path(args.path)
+    template_path = Path(args.template)
+    profile_dir = Path(args.profile_dir)
+
+    try:
+        user_data = load_user(target)
+        profile = args.profile or str(user_data.get("cost_profile") or "minimal")
+        if profile not in _install.SUPPORTED_PROFILES:
+            print(f"error: unsupported profile {profile!r}", file=sys.stderr)
+            return 2
+        profile_values = load_profile(profile_dir, profile)
+        template_body = load_template(template_path, profile_values)
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    new_text = render_target(template_body, user_data)
+    existing_text = target.read_text(encoding="utf-8") if target.is_file() else ""
+
+    if new_text == existing_text:
+        if not args.quiet:
+            print(f"✅  {target}: already in sync (profile={profile})")
+        return 0
+
+    if args.check:
+        diff = render_diff(existing_text, new_text, str(target))
+        sys.stdout.write(diff)
+        print(f"\n❌  {target}: drift detected (profile={profile})", file=sys.stderr)
+        return 2
+
+    if args.dry_run:
+        diff = render_diff(existing_text, new_text, str(target))
+        sys.stdout.write(diff)
+        if not args.quiet:
+            print(f"\n(dry-run) would update {target} (profile={profile})", file=sys.stderr)
+        return 0
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(new_text, encoding="utf-8")
+    if not args.quiet:
+        print(f"✅  {target}: updated (profile={profile})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sync_gitignore.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Sync the `event4u/agent-config` block in a project's `.gitignore`.
+
+Reads the canonical block body from `config/gitignore-block.txt` and
+ensures every managed entry is present in `.gitignore` between the
+START and END markers:
+
+    # event4u/agent-config
+    ...managed entries...
+    # event4u/agent-config — END
+
+Idempotent. Append-only by default (user-added lines inside the block
+are preserved). Call with `--replace` for a destructive full rewrite.
+
+Usage:
+    python3 scripts/sync_gitignore.py [--path .gitignore] [--template config/gitignore-block.txt]
+                                      [--dry-run] [--replace] [--quiet]
+
+Exit codes:
+    0 — no changes needed (or --dry-run ran successfully)
+    0 — changes applied
+    2 — invalid arguments / template missing
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import sys
+from pathlib import Path
+
+SECTION_HEADER = "# event4u/agent-config"
+SECTION_FOOTER = "# event4u/agent-config — END"
+DEFAULT_GITIGNORE = ".gitignore"
+DEFAULT_TEMPLATE = Path(__file__).resolve().parent.parent / "config" / "gitignore-block.txt"
+
+
+def _strip(ln: str) -> str:
+    return ln.rstrip("\n").rstrip()
+
+
+def _is_entry(ln: str) -> bool:
+    """Non-empty, non-comment line = a path/pattern entry."""
+    s = _strip(ln).lstrip()
+    return bool(s) and not s.startswith("#")
+
+
+def load_template(path: Path) -> list[str]:
+    if not path.is_file():
+        raise FileNotFoundError(f"template not found: {path}")
+    text = path.read_text(encoding="utf-8")
+    # Keep trailing newlines stripped; we splice explicit newlines.
+    return [_strip(ln) for ln in text.splitlines()]
+
+
+def find_block(lines: list[str]) -> tuple[int, int] | None:
+    """Locate the managed block; return (start_idx, end_idx_exclusive).
+
+    `start_idx` points at the SECTION_HEADER line.
+    `end_idx_exclusive` points one past the last line of the block.
+    Honors explicit SECTION_FOOTER when present; otherwise treats the
+    block as extending to EOF or to the next non-managed section.
+    Returns None if no header is found.
+    """
+    for i, ln in enumerate(lines):
+        if _strip(ln) == SECTION_HEADER:
+            start = i
+            # Explicit footer?
+            for j in range(i + 1, len(lines)):
+                if _strip(lines[j]) == SECTION_FOOTER:
+                    return (start, j + 1)
+            # Legacy: extend to EOF or next non-managed section break.
+            end = len(lines)
+            for j in range(i + 1, len(lines)):
+                s = _strip(lines[j]).lstrip()
+                if (s.startswith("#")
+                        and not s.startswith("# Agent config")
+                        and s != SECTION_HEADER):
+                    end = j
+                    while end > i + 1 and _strip(lines[end - 1]) == "":
+                        end -= 1
+                    break
+            return (start, end)
+    return None
+
+
+def block_entries(block_lines: list[str]) -> list[str]:
+    """Return entries (paths/patterns) present in the given block."""
+    return [_strip(ln).lstrip() for ln in block_lines if _is_entry(ln)]
+
+
+def template_entries(template_lines: list[str]) -> list[str]:
+    return [ln.lstrip() for ln in template_lines if _is_entry(ln)]
+
+
+def build_fresh_block(template_lines: list[str]) -> list[str]:
+    """Return a fresh, fully-managed block with START + body + END."""
+    return [SECTION_HEADER, *template_lines, SECTION_FOOTER]
+
+
+def sync_block(existing_lines: list[str],
+               template_lines: list[str],
+               *, replace: bool = False) -> tuple[list[str], list[str]]:
+    """Return (new_lines, added_entries).
+
+    - If block missing: append fresh block (preceded by a blank line if
+      the file's last line is not already empty).
+    - If block present and replace=True: rewrite block in full.
+    - If block present and replace=False: append any missing managed
+      entries before the END marker (adding END if absent). User-added
+      lines inside the block are preserved.
+    """
+    loc = find_block(existing_lines)
+    fresh = build_fresh_block(template_lines)
+
+    # Missing block → append with leading blank if needed.
+    if loc is None:
+        new = list(existing_lines)
+        if new and _strip(new[-1]) != "":
+            new.append("")
+        new.extend(fresh)
+        return new, template_entries(template_lines)
+
+    start, end = loc
+    head = existing_lines[:start]
+    block = existing_lines[start:end]
+    tail = existing_lines[end:]
+
+    if replace:
+        added = [e for e in template_entries(template_lines)
+                 if e not in block_entries(block)]
+        return head + fresh + tail, added
+
+    # Append-only mode.
+    existing_entries = set(block_entries(block))
+    missing = [e for e in template_entries(template_lines)
+               if e not in existing_entries]
+    if not missing:
+        return existing_lines, []
+
+    # Ensure block ends with SECTION_FOOTER; insert missing entries
+    # right before it.
+    if block and _strip(block[-1]) == SECTION_FOOTER:
+        insert_at = len(block) - 1
+    else:
+        block = [*block, SECTION_FOOTER]
+        insert_at = len(block) - 1
+    new_block = block[:insert_at] + missing + block[insert_at:]
+    return head + new_block + tail, missing
+
+
+def format_file(lines: list[str]) -> str:
+    """Join lines with newlines and enforce exactly one trailing newline."""
+    text = "\n".join(lines)
+    return text.rstrip("\n") + "\n"
+
+
+def render_diff(old_text: str, new_text: str, path: str) -> str:
+    return "".join(difflib.unified_diff(
+        old_text.splitlines(keepends=True),
+        new_text.splitlines(keepends=True),
+        fromfile=path, tofile=path, n=3,
+    ))
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--path", default=DEFAULT_GITIGNORE,
+                    help="target .gitignore (default: ./.gitignore)")
+    ap.add_argument("--template", default=str(DEFAULT_TEMPLATE),
+                    help="path to the managed-block template")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="print diff; do not modify the file")
+    ap.add_argument("--replace", action="store_true",
+                    help="rewrite the block in full (discards user-added "
+                         "lines inside the block)")
+    ap.add_argument("--quiet", action="store_true",
+                    help="suppress summary on success")
+    args = ap.parse_args(argv)
+
+    template_path = Path(args.template)
+    try:
+        template_lines = load_template(template_path)
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    target = Path(args.path)
+    if target.is_file():
+        existing_text = target.read_text(encoding="utf-8")
+        existing_lines = [_strip(ln) for ln in existing_text.splitlines()]
+    else:
+        existing_text = ""
+        existing_lines = []
+
+    new_lines, added = sync_block(
+        existing_lines, template_lines, replace=args.replace,
+    )
+    new_text = format_file(new_lines)
+
+    if new_text == existing_text:
+        if not args.quiet:
+            print(f"✅  {target}: block already in sync "
+                  f"({len(template_entries(template_lines))} entries)")
+        return 0
+
+    if args.dry_run:
+        diff = render_diff(existing_text, new_text, str(target))
+        sys.stdout.write(diff)
+        if not args.quiet:
+            print(f"\n(dry-run) would add {len(added)} entr"
+                  f"{'y' if len(added) == 1 else 'ies'} to {target}",
+                  file=sys.stderr)
+        return 0
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(new_text, encoding="utf-8")
+    if not args.quiet:
+        action = "replaced" if args.replace else "updated"
+        print(f"✅  {target}: {action} block "
+              f"({len(added)} entr{'y' if len(added) == 1 else 'ies'} added)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/agent-config-wrapper.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# agent-config — thin wrapper for the event4u/agent-config CLI.
+#
+# Auto-generated by the package installer. Delegates to the master CLI
+# shipped inside the installed package (node_modules or vendor). Do NOT
+# edit — this file is gitignored and regenerated on every install.
+#
+# Usage:
+#   ./agent-config help
+#   ./agent-config mcp:render
+#   ./agent-config roadmap:progress
+#
+# See: https://github.com/event4u-app/agent-config
+
+set -euo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+locate_master() {
+  local candidates=(
+    "$SELF_DIR/node_modules/@event4u/agent-config/scripts/agent-config"
+    "$SELF_DIR/vendor/event4u/agent-config/scripts/agent-config"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    if [[ -x "$c" ]]; then
+      printf '%s' "$c"
+      return 0
+    fi
+  done
+  return 1
+}
+
+if ! MASTER="$(locate_master)"; then
+  cat >&2 <<EOF
+❌  agent-config: master CLI not found.
+    Tried:
+      - node_modules/@event4u/agent-config/scripts/agent-config
+      - vendor/event4u/agent-config/scripts/agent-config
+    Reinstall the package, then retry:
+      npm install        # for Node projects
+      composer install   # for PHP projects
+EOF
+  exit 127
+fi
+
+exec "$MASTER" "$@"

package/.agent-src/commands/config-agent-settings.md

@@ -1,126 +0,0 @@
----
-name: config-agent-settings
-description: Create or update .agent-settings.yml — syncs with template, preserves existing values, adds new defaults
-skills: [file-editor]
-disable-model-invocation: true
----
-
-# /config-agent-settings
-
-Creates or updates `.agent-settings.yml` in the project root by syncing with the
-template in `.augment/templates/agent-settings.md`. Both files are YAML with the
-same section layout (`personal`, `project`, `github`, `eloquent`, `pipelines`,
-`subagents`).
-
-If a **legacy** flat `.agent-settings` (key=value) is present, `scripts/install`
-migrates it to `.agent-settings.yml` automatically (with backup). This command
-assumes migration has already happened.
-
-## Steps
-
-### 1. Read the template
-
-Read `.augment/templates/agent-settings.md` and extract the YAML block (between
-the ` ```yaml ` markers). Parse it into a nested mapping preserving section
-order and comments.
-
-### 2. Read existing settings (if any)
-
-Read `.agent-settings.yml` from the project root. If a legacy `.agent-settings`
-(key=value, no `.yml`) is present, stop and tell the user to run
-`scripts/install` first — do not re-implement the migration here.
-
-### 3. Merge settings (section-aware)
-
-For each section in the template (in template order):
-
-- Keep the section header and its comments verbatim from the template.
-- For each key under the section:
-  - **Key exists in user's file** → use the user's current value.
-  - **Key missing** → use the template default.
-- **Unknown sections/keys** the user has added → preserve at the end of the
-  section (or in a trailing `_user:` block if no matching section exists).
-
-Invariants:
-- Template section **order** always wins.
-- Existing scalar values are **never overwritten**.
-- New keys added to the template land with their default value.
-- Comments from the template always replace user comments in the same position
-  (comments are documentation, not user data).
-
-### 4. Write the file
-
-Write the merged YAML to `.agent-settings.yml` with 2-space indentation and no
-trailing whitespace.
-
-### 5. Show diff
-
-If the file already existed, show what changed in YAML dotted-key notation:
-
-```
-✅  .agent-settings.yml updated!
-
-Added:
-  + project.pr_comment_bot_icon: true   (new setting, default applied)
-
-Unchanged:
-  personal.ide: phpstorm
-  personal.open_edited_files: true
-```
-
-If the file was created fresh:
-
-```
-✅  .agent-settings.yml created!
-
-Settings (all defaults applied):
-  personal.ide: ""
-  personal.open_edited_files: false
-  project.pr_comment_bot_icon: false
-
-Run /config-agent-settings again to change values, or edit .agent-settings.yml directly.
-```
-
-### 6. Interactive setup for empty values
-
-If any required setting has an empty value (e.g. `personal.ide: ""`), offer to
-configure it:
-
-```
-> `personal.ide` is empty. Which IDE do you use?
->
-> 1. VS Code (code)
-> 2. PhpStorm (phpstorm)
-> 3. Cursor (cursor)
-> 4. Skip — I'll set it later
-```
-
-For `personal.ide`, also try auto-detection first:
-
-```bash
-ps aux | grep -iE '(Visual Studio Code|Code Helper|phpstorm|cursor)' | grep -v grep
-```
-
-- If detected → confirm with the user before setting.
-- If not detected → ask.
-
-### 7. Verify IDE command
-
-If `personal.ide` was set and `personal.open_edited_files: true`, verify the CLI
-command works:
-
-```bash
-{ide} --version 2>/dev/null
-```
-
-Warn if it fails and suggest how to install the CLI.
-
-## Rules
-
-- **Do NOT commit `.agent-settings.yml`** — it's in `.gitignore`.
-- **Never overwrite existing values** — only add missing keys with defaults.
-- **Always use template section order** — reorder keys to match the template.
-- **Template is the source of truth** for which keys exist and their defaults.
-- **Legacy migration is `scripts/install`'s job**, not this command's. If a flat
-  `.agent-settings` file is still present, ask the user to run `scripts/install`
-  and stop.