trae-coding-engine 0.1.0

package/templates/scripts/check-runbooks.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# Lint docs/runbooks/*.md for broken references so an oncall never follows a
+# dead link or a stale source citation mid-incident. Three checks:
+#   1. Relative links  `](./X.md)`  -> target must exist under docs/runbooks/.
+#   2. In-page anchors `](#slug)`   -> a heading in the SAME file must slugify
+#      to that slug (lowercase, spaces->hyphens, strip punctuation, KEEP unicode
+#      so `## 速查表` -> `速查表` and `## Cheat-sheet` -> `cheat-sheet` both resolve).
+#   3. Backticked PATH-LIKE code refs (`dir/file.ext` or `dir/file.ext:NN`,
+#      ext in go|tpl|yaml|yml|thrift|sql|md|example|sh — an allow-list of text
+#      source/config types an oncall can grep offline; binaries and unlisted
+#      types are intentionally not treated as repo-path claims): must exist at
+#      the repo root; if `:NN`, the file must have at least NN lines. A ref whose
+#      first path segment is NOT a tracked repo-root entry (e.g. chart-relative
+#      `templates/secret.yaml`, absolute `/etc/conf/config.yaml`) is treated as a
+#      non-repo citation and skipped — it is not a repo-root path claim.
+#      Bare filenames without `/` (e.g. `controller.go:173`) are also skipped.
+#   4. Every actual runbook (NOT README*.md / TEMPLATE.md / INCIDENTS.md) must
+#      carry a visible `**Last verified:** YYYY-MM-DD` line with a parseable ISO
+#      date — so an oncall can see staleness at a glance and lint flags a page
+#      that drifted without its metadata being re-touched. Missing or malformed
+#      date -> VIOLATION.
+set -euo pipefail
+
+# Force a UTF-8 locale: runbooks contain multibyte text (em-dash, CJK headings
+# like 速查表). Under a C / non-UTF-8 locale, BSD grep/sed/tr abort with
+# "illegal byte sequence" (SIGABRT) — which happens when invoked via `make`
+# with a scrubbed environment. Pick the first UTF-8 locale that exists.
+for _loc in C.UTF-8 en_US.UTF-8; do
+  if locale -a 2>/dev/null | grep -qx "$_loc"; then
+    export LC_ALL="$_loc" LANG="$_loc"
+    break
+  fi
+done
+
+cd "$(dirname "$0")/.."
+
+RUNBOOK_DIR="docs/runbooks"
+VIOLATIONS=0
+GRANDFATHERED_HITS=0
+
+# Grandfathered refs — a path-like citation we knowingly keep despite not
+# resolving. Format: "<relpath>:<lineno>\t<reason>". Empty by design: prefer
+# FIXING a ref over grandfathering (a wrong citation misleads oncall).
+GRANDFATHERED=()
+
+is_grandfathered() {
+  local key=$1
+  for g in "${GRANDFATHERED[@]+"${GRANDFATHERED[@]}"}"; do
+    [ "${g%%$'\t'*}" = "$key" ] && return 0
+  done
+  return 1
+}
+
+# Repo-root segments that mark a backticked ref as a genuine repo path claim.
+# Built once from the git index so it tracks real top-level entries.
+ROOT_ENTRIES="$(git ls-tree --name-only HEAD 2>/dev/null || ls -A)"
+
+is_repo_root_segment() {
+  local seg=$1
+  printf '%s\n' "$ROOT_ENTRIES" | grep -qx -- "$seg"
+}
+
+# slugify <heading-text> -> GitHub slug, unicode preserved.
+# GitHub's rule: lowercase -> strip punctuation (em-dash, etc.) -> replace each
+# space with a hyphen. It does NOT collapse the consecutive hyphens that result
+# when punctuation sat between two spaces, so `Step 2 — Migrate` -> `step-2--migrate`
+# (double hyphen). Existing hyphens in the heading are preserved. Do not collapse.
+slugify() {
+  # Strip ASCII punctuation plus the unicode dashes that show up in headings
+  # (em-dash —, en-dash –). CJK word characters (速查表) are NOT punctuation and
+  # are kept. Keeping the unicode-dash strip explicit avoids a blanket
+  # "remove all non-ASCII" that would also eat CJK.
+  # One sed pass: strip ASCII punctuation + unicode dashes, then spaces->hyphens.
+  printf '%s' "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[][`~!@#$%^&*()+=|\\{}:;"'"'"'<>,.?/—–]//g; s/[[:space:]]/-/g'
+}
+
+# Collect all heading slugs in a file (one per line).
+file_slugs() {
+  local f=$1 line heading
+  while IFS= read -r line; do
+    case "$line" in
+      \#*)
+        heading=$(printf '%s' "$line" | sed -E 's/^#+[[:space:]]*//')
+        # slugify emits no trailing newline; add one so each slug is its own line.
+        printf '%s\n' "$(slugify "$heading")"
+        ;;
+    esac
+  done <"$f"
+}
+
+report_violation() {
+  echo "  [VIOLATION]     $1"
+  VIOLATIONS=$((VIOLATIONS + 1))
+}
+
+# Files that are NOT incident runbooks and therefore exempt from the
+# Last-verified requirement: the two READMEs, the copy-me TEMPLATE, and the
+# append-only INCIDENTS log.
+is_metadata_exempt() {
+  # README.*.md covers any translated front-door (README.zh.md, README.ja.md, …)
+  # without needing this list touched when a locale is added.
+  case "$(basename "$1")" in
+    README.md | README.*.md | TEMPLATE.md | INCIDENTS.md) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Validate a YYYY-MM-DD string is a real calendar date (not just shaped right).
+# Uses `date` for parsing; tries GNU (-d) then BSD (-j -f) so it works on Linux
+# CI and macOS dev boxes alike.
+is_iso_date() {
+  local d=$1
+  case "$d" in
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) ;;
+    *) return 1 ;;
+  esac
+  date -d "$d" +%Y-%m-%d >/dev/null 2>&1 && return 0
+  date -j -f %Y-%m-%d "$d" +%Y-%m-%d >/dev/null 2>&1 && return 0
+  return 1
+}
+
+# Check 4: a runbook must carry a `**Last verified:** YYYY-MM-DD` line.
+check_last_verified() {
+  local f=$1 line date_str
+  is_metadata_exempt "$f" && return 0
+  # Grab the value after the FIRST `**Last verified:**` marker, then the leading
+  # date token (the line also carries Owner / Blast radius / Related fields).
+  line=$(grep -m1 -oE '\*\*Last verified:\*\*[[:space:]]*[0-9]{4}-[0-9]{2}-[0-9]{2}' "$f" || true)
+  if [ -z "$line" ]; then
+    report_violation "$f — missing a '**Last verified:** YYYY-MM-DD' metadata line"
+    return 0
+  fi
+  date_str=${line##* }
+  if ! is_iso_date "$date_str"; then
+    report_violation "$f — '**Last verified:** $date_str' is not a valid ISO date"
+  fi
+}
+
+check_file() {
+  local f=$1
+  local base slugs lineno
+  base=$(basename "$f")
+  # Slug set as newline list; held in a string + matched with an exact lookup.
+  slugs=$(file_slugs "$f")
+
+  # Extract each reference class in ONE grep pass over the whole file (with line
+  # numbers via -n). Iterating the small match set in pure bash avoids a
+  # per-line subshell storm that was slow enough to get OOM/SIGKILL'd under make.
+
+  # 1. Relative .md links: ](./X.md) or ](./X.md#anchor)
+  local m lineno hit path
+  while IFS= read -r m; do
+    [ -n "$m" ] || continue
+    lineno=${m%%:*}
+    hit=${m#*:}
+    path=${hit#*](./}; path=${path%)}; path=${path%%#*}
+    if [ ! -f "$RUNBOOK_DIR/$path" ]; then
+      report_violation "$f:$lineno — relative link './$path' has no target under $RUNBOOK_DIR/"
+    fi
+  done < <(grep -noE '\]\(\./[^)]+\.md(#[^)]*)?\)' "$f")
+
+  # 2. In-page anchors: ](#slug)
+  local slug
+  while IFS= read -r m; do
+    [ -n "$m" ] || continue
+    lineno=${m%%:*}
+    hit=${m#*:}
+    slug=${hit#*](#}; slug=${slug%)}
+    if ! printf '%s\n' "$slugs" | grep -qxF -- "$slug"; then
+      report_violation "$f:$lineno — anchor '#$slug' matches no heading in $base"
+    fi
+  done < <(grep -noE '\]\(#[^)]+\)' "$f")
+
+  # 3. Backticked path-like code refs.
+  local ref relpath want_lines first_seg key have
+  while IFS= read -r m; do
+    [ -n "$m" ] || continue
+    lineno=${m%%:*}
+    hit=${m#*:}
+    ref=${hit#\`}; ref=${ref%\`}
+    relpath=${ref%%:*}; want_lines=""
+    [ "$ref" != "$relpath" ] && want_lines=${ref#*:}
+    # Must contain a slash to be a path claim; skip bare filenames.
+    case "$relpath" in */*) ;; *) continue ;; esac
+    # First segment must be a tracked repo-root entry, else it's a
+    # chart-relative / absolute / non-repo citation — skip.
+    first_seg=${relpath%%/*}
+    [ -n "$first_seg" ] || continue            # leading-slash absolute path
+    is_repo_root_segment "$first_seg" || continue
+
+    key="$f:$lineno"
+    if [ ! -f "$relpath" ]; then
+      if is_grandfathered "$key"; then
+        echo "  [GRANDFATHERED] $key — missing path ref \`$ref\`"
+        GRANDFATHERED_HITS=$((GRANDFATHERED_HITS + 1))
+      else
+        report_violation "$f:$lineno — code ref \`$ref\` does not exist at repo root"
+      fi
+      continue
+    fi
+    if [ -n "$want_lines" ]; then
+      have=$(wc -l <"$relpath")
+      if [ "$have" -lt "$want_lines" ]; then
+        report_violation "$f:$lineno — code ref \`$ref\` points past EOF ($relpath has $have lines)"
+      fi
+    fi
+  done < <(grep -noE '`[A-Za-z0-9_./-]+/[A-Za-z0-9_.-]+\.(go|tpl|yaml|yml|thrift|sql|md|example|sh)(:[0-9]+)?`' "$f")
+}
+
+shopt -s nullglob
+for f in "$RUNBOOK_DIR"/*.md; do
+  check_file "$f"
+  check_last_verified "$f"
+done
+
+if [ "$VIOLATIONS" -eq 0 ]; then
+  if [ "$GRANDFATHERED_HITS" -gt 0 ]; then
+    echo "  [OK]  no new violations (${GRANDFATHERED_HITS} grandfathered)"
+  else
+    echo "  [OK]  runbook links and citations all resolve"
+  fi
+  exit 0
+fi
+
+echo
+echo "  ${VIOLATIONS} broken runbook reference(s)."
+exit 1

package/templates/scripts/check-skill-router-sync.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""Verify the §Skill Router mapping is consistent across its three mirrors.
+
+AGENTS.md §Skill Router is the cross-tool source of truth. The same path->skill
+mapping is duplicated in two derived mirrors so each CLI can read it natively:
+
+  * .cursor/rules/skill-router.mdc   (Cursor: `globs:` frontmatter + a table)
+  * scripts/skill-router-hook.sh     (Claude Code PostToolUse hook: bash `case`)
+
+Nothing regenerates these from the source, so an edit to one can silently drift
+from the others (different glob dialects hide the divergence). This gate parses
+all three, normalizes the glob dialects to a canonical form, and asserts:
+
+  1. AGENTS.md table  == hook `case` mapping        (skill-set -> path-set)
+  2. AGENTS.md table  == .mdc table mapping
+  3. .mdc `globs:` frontmatter == union of all .mdc table paths
+
+It is a structural consistency check, not a generator: authors still edit each
+file, but drift fails the build. Exit 0 when in sync, 1 on drift, 2 on a parse
+or usage error.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SKILL_RE = re.compile(r"coding-[a-z0-9-]+")
+BACKTICK_RE = re.compile(r"`([^`]+)`")
+# A bare glob token: path chars plus glob metacharacters, nothing shell-ish.
+TOKEN_RE = re.compile(r"^[A-Za-z0-9_./*-]+$")
+
+
+def expand_braces(token: str) -> list[str]:
+    """Expand a single `{a,b,c}` brace group into multiple tokens.
+
+    The router patterns use at most one brace group per token, but this recurses
+    so nested or multiple groups still expand correctly.
+    """
+    start = token.find("{")
+    if start == -1:
+        return [token]
+    depth = 0
+    for i in range(start, len(token)):
+        if token[i] == "{":
+            depth += 1
+        elif token[i] == "}":
+            depth -= 1
+            if depth == 0:
+                end = i
+                break
+    else:
+        # Unbalanced brace; treat literally rather than guessing.
+        return [token]
+    prefix, body, suffix = token[:start], token[start + 1 : end], token[end + 1 :]
+    out: list[str] = []
+    for alt in body.split(","):
+        for tail in expand_braces(suffix):
+            out.append(prefix + alt + tail)
+    return out
+
+
+def normalize_path(raw: str) -> set[str]:
+    """Canonicalize one glob token so equivalent dialects compare equal.
+
+    Folds the AGENTS.md (`{a,b}/**`), .mdc (`/**`) and hook (`/*`) dialects onto
+    a shared form: brace-expand, collapse `**`->`*`, drop a leading `*/` and a
+    trailing `/*` directory glob. Returns a set because braces expand to many.
+
+    The `**`->`*` fold is intentional, not a bug: for the rows in use the three
+    dialects denote the same subtree. A bash `case` `*` matches across `/`, so
+    the hook's `dir/*` is the subtree `dir/**` written in AGENTS.md and the
+    .mdc. Folding them is what lets the gate compare the dialects at all. The
+    accepted blind spot is a single-level gitignore-style `*` in the .mdc
+    `globs:` list — there `*` does NOT cross `/`, so swapping `/**` for `/*`
+    there is a real semantic change this gate would treat as equivalent. That
+    has not happened and is cheap to catch in review; depth-sensitivity here
+    would instead flag the current intentionally-equivalent rows as drift.
+    """
+    token = raw.strip().strip("`").strip().strip('"')
+    out: set[str] = set()
+    for expanded in expand_braces(token):
+        p = expanded.replace("**", "*")
+        if p.startswith("*/"):
+            p = p[2:]
+        if p.endswith("/*"):
+            p = p[:-2]
+        if p:
+            out.add(p)
+    return out
+
+
+def normalize_paths(tokens: list[str]) -> frozenset[str]:
+    out: set[str] = set()
+    for t in tokens:
+        out |= normalize_path(t)
+    return frozenset(out)
+
+
+def skill_key(cell: str) -> frozenset[str]:
+    return frozenset(SKILL_RE.findall(cell))
+
+
+def fail(msg: str) -> None:
+    print(f"[FAIL] {msg}", file=sys.stderr)
+
+
+def is_separator_row(cells: list[str]) -> bool:
+    return all(set(c.strip()) <= {"-", ":"} and c.strip() for c in cells)
+
+
+def parse_markdown_table(lines: list[str]) -> dict[frozenset[str], frozenset[str]]:
+    """Parse `| paths | skill | ... |` rows into {skill-set -> path-set}.
+
+    The first cell holds backtick-quoted, comma-separated path globs; the second
+    holds one or more backtick-quoted skill names. The header row (it names the
+    skill column "Load skill") and the `|---|` separator are skipped.
+    """
+    mapping: dict[frozenset[str], set[str]] = {}
+    for line in lines:
+        if not line.lstrip().startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 2 or is_separator_row(cells):
+            continue
+        if "load skill" in cells[1].lower():
+            continue  # header row
+        paths = BACKTICK_RE.findall(cells[0])
+        skills = skill_key(cells[1])
+        if not paths or not skills:
+            continue
+        mapping.setdefault(skills, set()).update(normalize_paths(paths))
+    return {k: frozenset(v) for k, v in mapping.items()}
+
+
+def slice_section(text: str, heading: str) -> list[str]:
+    """Return the lines of a `## heading` section, up to the next `## ` heading."""
+    lines = text.splitlines()
+    out: list[str] = []
+    in_section = False
+    for line in lines:
+        if line.startswith("## "):
+            if in_section:
+                break
+            in_section = line.strip() == f"## {heading}"
+            continue
+        if in_section:
+            out.append(line)
+    return out
+
+
+def parse_agents_md(path: Path) -> dict[frozenset[str], frozenset[str]]:
+    section = slice_section(path.read_text(encoding="utf-8"), "Skill Router")
+    if not section:
+        raise ValueError(f"{path}: '## Skill Router' section not found")
+    return parse_markdown_table(section)
+
+
+def parse_mdc_table(path: Path) -> dict[frozenset[str], frozenset[str]]:
+    text = path.read_text(encoding="utf-8")
+    # Skip the YAML frontmatter so its `globs:` list is not mistaken for a table.
+    parts = text.split("---")
+    body = "---".join(parts[2:]) if text.startswith("---") and len(parts) >= 3 else text
+    return parse_markdown_table(body.splitlines())
+
+
+def parse_mdc_globs(path: Path) -> frozenset[str]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        raise ValueError(f"{path}: missing YAML frontmatter")
+    frontmatter = text.split("---")[1]
+    out: set[str] = set()
+    in_globs = False
+    for line in frontmatter.splitlines():
+        if re.match(r"^\s*globs:\s*$", line):
+            in_globs = True
+            continue
+        if in_globs:
+            m = re.match(r"^\s*-\s*[\"']?([^\"'\s]+)[\"']?\s*$", line)
+            if m:
+                out |= normalize_path(m.group(1))
+            elif line.strip() and not line.startswith(" "):
+                break  # next top-level key
+            elif re.match(r"^\s*\w+:", line):
+                break  # next mapping key at any indent
+    if not out:
+        raise ValueError(f"{path}: no `globs:` entries found")
+    return frozenset(out)
+
+
+def parse_hook(path: Path) -> dict[frozenset[str], frozenset[str]]:
+    """Parse the first `case "$REL" in ... esac` block of the router hook.
+
+    Each branch lists glob patterns separated by `|` and terminated by `)`, then
+    a `SKILL="..."` assignment. A later ADR-note `case` block has no SKILL and is
+    ignored because we stop at the first `esac`.
+    """
+    text = path.read_text(encoding="utf-8")
+    start = text.find('case "$REL" in')
+    if start == -1:
+        raise ValueError(f"{path}: `case \"$REL\" in` block not found")
+    end = text.find("esac", start)
+    if end == -1:
+        raise ValueError(f"{path}: unterminated case block")
+    block = text[start:end]
+
+    mapping: dict[frozenset[str], set[str]] = {}
+    for branch in block.split(";;"):
+        sk = re.search(r'SKILL="([^"]*)"', branch)
+        if not sk:
+            continue
+        skills = skill_key(sk.group(1))
+        if not skills:
+            continue
+        pattern_text = branch[: sk.start()]
+        tokens: list[str] = []
+        for line in pattern_text.splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            for tok in re.split(r"[|)]", stripped):
+                tok = tok.strip().rstrip("\\").strip()
+                if tok and TOKEN_RE.match(tok):
+                    tokens.append(tok)
+        if tokens:
+            mapping.setdefault(skills, set()).update(normalize_paths(tokens))
+    return {k: frozenset(v) for k, v in mapping.items()}
+
+
+def diff_mapping(
+    name_a: str,
+    map_a: dict[frozenset[str], frozenset[str]],
+    name_b: str,
+    map_b: dict[frozenset[str], frozenset[str]],
+) -> list[str]:
+    errors: list[str] = []
+    keys = sorted(set(map_a) | set(map_b), key=lambda k: ",".join(sorted(k)))
+    for key in keys:
+        label = " + ".join(sorted(key))
+        a = map_a.get(key)
+        b = map_b.get(key)
+        if a is None:
+            errors.append(f"skill `{label}` present in {name_b} but missing in {name_a}")
+            continue
+        if b is None:
+            errors.append(f"skill `{label}` present in {name_a} but missing in {name_b}")
+            continue
+        only_a = a - b
+        only_b = b - a
+        if only_a:
+            errors.append(f"skill `{label}`: paths only in {name_a}: {sorted(only_a)}")
+        if only_b:
+            errors.append(f"skill `{label}`: paths only in {name_b}: {sorted(only_b)}")
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--root",
+        default=str(Path(__file__).resolve().parent.parent),
+        help="repo root containing AGENTS.md, .cursor/, scripts/ (default: repo root)",
+    )
+    args = parser.parse_args()
+    root = Path(args.root)
+
+    agents_md = root / "AGENTS.md"
+    mdc = root / ".cursor" / "rules" / "skill-router.mdc"
+    hook = root / "scripts" / "skill-router-hook.sh"
+    for f in (agents_md, mdc, hook):
+        if not f.is_file():
+            fail(f"required file not found: {f}")
+            return 2
+
+    try:
+        agents_map = parse_agents_md(agents_md)
+        mdc_map = parse_mdc_table(mdc)
+        mdc_globs = parse_mdc_globs(mdc)
+        hook_map = parse_hook(hook)
+    except ValueError as exc:
+        fail(str(exc))
+        return 2
+
+    # An empty parse means a parser/format regression, not "in sync". Without
+    # this guard, two sides both parsing to {} would diff-clean and pass — the
+    # gate would silently stop protecting anything. parse_mdc_globs already
+    # raises on an empty `globs:` list.
+    if not agents_map:
+        fail("AGENTS.md §Skill Router table parsed to an empty mapping")
+        return 2
+    if not hook_map:
+        fail("scripts/skill-router-hook.sh case block parsed to an empty mapping")
+        return 2
+    if not mdc_map:
+        fail(".cursor/rules/skill-router.mdc table parsed to an empty mapping")
+        return 2
+
+    errors: list[str] = []
+    errors += diff_mapping("AGENTS.md", agents_map, "skill-router-hook.sh", hook_map)
+    errors += diff_mapping("AGENTS.md", agents_map, "skill-router.mdc table", mdc_map)
+
+    # The .mdc `globs:` frontmatter has no skill labels; assert it covers exactly
+    # the same path set as its own table so the two halves cannot drift apart.
+    mdc_table_paths: set[str] = set()
+    for paths in mdc_map.values():
+        mdc_table_paths |= set(paths)
+    only_globs = mdc_globs - mdc_table_paths
+    only_table = mdc_table_paths - mdc_globs
+    if only_globs:
+        errors.append(f".mdc `globs:` lists paths absent from its table: {sorted(only_globs)}")
+    if only_table:
+        errors.append(f".mdc table lists paths absent from `globs:`: {sorted(only_table)}")
+
+    if errors:
+        fail("Skill Router mirrors are out of sync:")
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        print(
+            "\nUpdate AGENTS.md §Skill Router first, then mirror the change in\n"
+            ".cursor/rules/skill-router.mdc and scripts/skill-router-hook.sh.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print("[OK] Skill Router is consistent across AGENTS.md, .cursor mirror, and hook")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())