@event4u/agent-config 2.21.0 → 2.24.0

package/scripts/ai-video/lib/validate-deps.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# validate-deps.sh — startup validator invoked by every /video:* command
+# BEFORE any adapter or network call. Reads the YAML frontmatter from
+# the command file, resolves every declared persona + skill against
+# .agent-src/personas/ and .agent-src/skills/, and fails fast with the
+# missing-id list.
+#
+# Scope (per roadmap Phase 5 Step 5): existence + frontmatter `id` match
+# only. No version pinning (scope-control § rules); no schema validation
+# of persona / skill bodies — that lives in `task lint-skills`.
+#
+# Usage:
+#   validate-deps.sh <path-to-command.md>
+#
+# Exit codes:
+#   0   all declared personas + skills resolve
+#   2   command file missing or no frontmatter
+#   3   one or more declared ids do not resolve (list on stderr)
+
+set -euo pipefail
+
+if [ "$#" -ne 1 ]; then
+  printf 'validate-deps: usage: %s <path-to-command.md>\n' "$0" >&2
+  exit 2
+fi
+
+cmd_file="$1"
+if [ ! -f "${cmd_file}" ]; then
+  printf 'validate-deps: command file not found: %s\n' "${cmd_file}" >&2
+  exit 2
+fi
+
+# Resolve repo root from this script's location (scripts/ai-video/lib/).
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "${script_dir}/../../.." && pwd)"
+
+# AIV_PERSONAS_DIR / AIV_SKILLS_DIR allow overrides for tests; defaults
+# point at the generated mirrors (skills+personas live there at runtime).
+personas_dir="${AIV_PERSONAS_DIR:-${repo_root}/.agent-src/personas}"
+skills_dir="${AIV_SKILLS_DIR:-${repo_root}/.agent-src/skills}"
+
+# Extract the frontmatter block (between the first two `---` lines).
+fm="$(awk '
+  BEGIN { in_fm=0; count=0 }
+  /^---[[:space:]]*$/ { count++; if (count==1) { in_fm=1; next } if (count==2) { exit } }
+  in_fm { print }
+' "${cmd_file}")"
+
+if [ -z "${fm}" ]; then
+  printf 'validate-deps: no YAML frontmatter in %s\n' "${cmd_file}" >&2
+  exit 2
+fi
+
+# Parse `personas:` and `skills:` lines. We accept inline-list form only
+# (the template we ship), e.g. `personas: [a, b]`. No multi-line block
+# form — keeps the validator dependency-free (no yq / python).
+_extract_list() {
+  # $1 = key name (personas|skills)
+  printf '%s\n' "${fm}" \
+    | awk -v key="$1" '
+        $0 ~ "^" key ":" {
+          line=$0
+          sub("^" key ":[[:space:]]*", "", line)
+          sub("^\\[", "", line)
+          sub("\\][[:space:]]*$", "", line)
+          gsub(",", " ", line)
+          print line
+        }' \
+    | tr -s ' ' '\n' \
+    | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' \
+    | sed '/^$/d'
+}
+
+# Portable to macOS bash 3.2 — no `mapfile`.
+personas=()
+while IFS= read -r _id; do
+  personas+=("${_id}")
+done < <(_extract_list personas)
+skills=()
+while IFS= read -r _id; do
+  skills+=("${_id}")
+done < <(_extract_list skills)
+
+missing=()
+
+# bash 3.2 treats `"${arr[@]}"` on an empty array as unbound under
+# `set -u`. Guard each loop with the length check.
+
+# A persona is "present" if .agent-src/personas/<id>.md exists OR
+# .agent-src/personas/<id>/persona.md exists (template-specialist shape).
+if [ "${#personas[@]}" -gt 0 ]; then
+for p in "${personas[@]}"; do
+  [ -z "${p}" ] && continue
+  if [ ! -f "${personas_dir}/${p}.md" ] && [ ! -f "${personas_dir}/${p}/persona.md" ]; then
+    missing+=("persona:${p}")
+    continue
+  fi
+  # Frontmatter id match: read `id:` (optional) or `name:` from the
+  # persona file; if present it must equal the declared slug.
+  src_file="${personas_dir}/${p}.md"
+  [ -f "${src_file}" ] || src_file="${personas_dir}/${p}/persona.md"
+  declared_id="$(awk '/^id:[[:space:]]*/ { sub("^id:[[:space:]]*", ""); print; exit } /^name:[[:space:]]*/ { sub("^name:[[:space:]]*", ""); print; exit }' "${src_file}" | tr -d '"' | tr -d "'")"
+  if [ -n "${declared_id}" ] && [ "${declared_id}" != "${p}" ]; then
+    missing+=("persona:${p} (file declares id=${declared_id})")
+  fi
+done
+fi
+
+# A skill is "present" if .agent-src/skills/<id>/SKILL.md exists.
+if [ "${#skills[@]}" -gt 0 ]; then
+for s in "${skills[@]}"; do
+  [ -z "${s}" ] && continue
+  skill_file="${skills_dir}/${s}/SKILL.md"
+  if [ ! -f "${skill_file}" ]; then
+    missing+=("skill:${s}")
+    continue
+  fi
+  declared_id="$(awk '/^name:[[:space:]]*/ { sub("^name:[[:space:]]*", ""); print; exit }' "${skill_file}" | tr -d '"' | tr -d "'")"
+  if [ -n "${declared_id}" ] && [ "${declared_id}" != "${s}" ]; then
+    missing+=("skill:${s} (file declares name=${declared_id})")
+  fi
+done
+fi
+
+if [ "${#missing[@]}" -gt 0 ]; then
+  printf 'validate-deps: unresolved declarations in %s:\n' "${cmd_file}" >&2
+  printf '  - %s\n' "${missing[@]}" >&2
+  exit 3
+fi
+
+# Silent success — callers can `set -e` and continue.
+exit 0

package/scripts/ai-video/stitch.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# stitch.sh — ffmpeg-based clip concatenator for /video:* pipelines.
+#
+# Drives the cut from <project>/manifest.json (an ordered array of
+# `{scene_id, clip_path, audio_embedded, audio_path?, duration}`).
+# Pass-through for audio_embedded=true; ffmpeg mux for audio_embedded
+# =false; operator-supplied bed for video-only clips.
+#
+# Usage:
+#   stitch.sh <manifest.json> <output.mp4>
+#               [--skip-scene <id> ...]
+#               [--abort-on-missing | --continue]
+#               [--crossfade <seconds>]
+#
+# Failure semantics:
+#   - Missing clip → fail loud with scene_id and re-render hint
+#     unless --skip-scene <id> drops the clip from the cut or
+#     --continue is passed (the dropped scenes are written to stderr).
+#   - --abort-on-missing is the default.
+#   - Adapter-failure rollback contract: a failed adapter writes
+#     <project>/scenes/<id>/error.json; stitch.sh checks for that
+#     file alongside the clip and surfaces it instead of an opaque
+#     ffmpeg error.
+
+set -euo pipefail
+
+# shellcheck source=lib/adapter-common.sh
+. "$(dirname "$0")/lib/adapter-common.sh"
+
+aiv_require_cmd jq
+
+DRYRUN="${AIV_DRYRUN:-true}"
+case "${DRYRUN}" in
+  false|FALSE|0|no|NO) DRYRUN_FLAG=0 ;;
+  *) DRYRUN_FLAG=1 ;;
+esac
+[ "${DRYRUN_FLAG}" -eq 0 ] && aiv_require_cmd ffmpeg
+
+MANIFEST="${1:-}"
+OUTPUT="${2:-}"
+[ -n "${MANIFEST}" ] && [ -n "${OUTPUT}" ] \
+  || aiv_die 2 "usage: stitch.sh <manifest.json> <output.mp4> [--skip-scene <id>] [--abort-on-missing|--continue] [--crossfade <s>]"
+[ -r "${MANIFEST}" ] || aiv_die 2 "manifest not readable: ${MANIFEST}"
+shift 2 || true
+
+SKIP_IDS=""
+MISSING_POLICY="abort"
+CROSSFADE=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --skip-scene) SKIP_IDS="${SKIP_IDS} ${2:-}"; shift 2 ;;
+    --abort-on-missing) MISSING_POLICY="abort"; shift ;;
+    --continue) MISSING_POLICY="continue"; shift ;;
+    --crossfade) CROSSFADE="${2:-}"; shift 2 ;;
+    *) aiv_die 2 "stitch.sh: unknown flag '$1'" ;;
+  esac
+done
+
+skip_match() {
+  local id="$1" s
+  for s in ${SKIP_IDS}; do
+    [ "${s}" = "${id}" ] && return 0
+  done
+  return 1
+}
+
+PROJECT_DIR="$(cd "$(dirname "${MANIFEST}")" && pwd)"
+WORK_DIR="$(mktemp -d -t aiv-stitch-XXXXXX)"
+trap 'rm -rf "${WORK_DIR}"' EXIT
+CONCAT_LIST="${WORK_DIR}/concat.txt"
+: > "${CONCAT_LIST}"
+
+# Accept both bare-array manifests and the documented object shape
+# (`{ "scenes": [...] }`). Field names tolerate the legacy
+# `scene_id` / `clip_path` keys and the example `id` / `expected_clip`.
+SCENES_JQ='if type == "array" then .[] else .scenes[] end'
+
+count=0
+missing=0
+plan=""
+while IFS= read -r row; do
+  [ -n "${row}" ] || continue
+  scene_id="$(printf '%s' "${row}" | jq -r '.scene_id // .id')"
+  clip_path="$(printf '%s' "${row}" | jq -r '.clip_path // .expected_clip')"
+  audio_embedded="$(printf '%s' "${row}" | jq -r '.audio_embedded // false')"
+  audio_path="$(printf '%s' "${row}" | jq -r '.audio_path // empty')"
+
+  case "${clip_path}" in
+    /*) ;;
+    *) clip_path="${PROJECT_DIR}/${clip_path}" ;;
+  esac
+
+  if skip_match "${scene_id}"; then
+    printf 'stitch: skip scene=%s (operator --skip-scene)\n' "${scene_id}" >&2
+    continue
+  fi
+
+  if [ "${DRYRUN_FLAG}" -eq 1 ]; then
+    plan="${plan}${scene_id}\taudio_embedded=${audio_embedded}\t${clip_path}\n"
+    count=$((count + 1))
+    continue
+  fi
+
+  if [ ! -f "${clip_path}" ]; then
+    err_json="${PROJECT_DIR}/scenes/${scene_id}/error.json"
+    if [ -f "${err_json}" ]; then
+      printf 'stitch: scene=%s adapter-error: ' "${scene_id}" >&2
+      jq -r '"adapter=\(.adapter) exit=\(.exit_code) user_action=\(.user_action)"' "${err_json}" >&2
+    fi
+    if [ "${MISSING_POLICY}" = "continue" ]; then
+      printf 'stitch: continue past missing scene=%s clip=%s (re-render or --skip-scene next time)\n' \
+        "${scene_id}" "${clip_path}" >&2
+      missing=$((missing + 1))
+      continue
+    fi
+    aiv_die 7 "missing clip for scene=${scene_id} at ${clip_path} (re-render the scene, pass --skip-scene ${scene_id}, or use --continue)"
+  fi
+
+  # For clips without embedded audio that ship a sibling track, mux
+  # via ffmpeg into a tmp file before concat. Pure pass-through for
+  # the embedded-audio case.
+  if [ "${audio_embedded}" = "false" ] && [ -n "${audio_path}" ] && [ -f "${audio_path}" ]; then
+    muxed="${WORK_DIR}/${scene_id}.mp4"
+    ffmpeg -loglevel error -y -i "${clip_path}" -i "${audio_path}" \
+      -c:v copy -c:a aac -shortest "${muxed}" >/dev/null \
+      || aiv_die 8 "ffmpeg mux failed for scene=${scene_id}"
+    printf "file '%s'\n" "${muxed}" >> "${CONCAT_LIST}"
+  else
+    printf "file '%s'\n" "${clip_path}" >> "${CONCAT_LIST}"
+  fi
+  count=$((count + 1))
+done <<EOF
+$(jq -c "${SCENES_JQ}" "${MANIFEST}")
+EOF
+
+[ "${count}" -gt 0 ] || aiv_die 7 "stitch: no usable clips after manifest scan (missing=${missing}, skipped via --skip-scene)"
+
+if [ "${DRYRUN_FLAG}" -eq 1 ]; then
+  printf 'stitch: dry-run plan (output=%s, scenes=%d):\n' "${OUTPUT}" "${count}" >&2
+  printf '%b' "${plan}" >&2
+  printf '{"output":"%s","scenes":%d,"missing":0,"dry_run":true}\n' "${OUTPUT}" "${count}"
+  exit 0
+fi
+
+if [ -n "${CROSSFADE}" ]; then
+  printf 'stitch: crossfade=%ss requested — passing through ffmpeg xfade filter not yet implemented (concat path used)\n' \
+    "${CROSSFADE}" >&2
+fi
+
+ffmpeg -loglevel error -y -f concat -safe 0 -i "${CONCAT_LIST}" \
+  -c copy "${OUTPUT}" >/dev/null \
+  || aiv_die 8 "ffmpeg concat failed (manifest=${MANIFEST}, output=${OUTPUT})"
+
+printf '{"output":"%s","scenes":%d,"missing":%d}\n' "${OUTPUT}" "${count}" "${missing}"

package/scripts/ai-video/test-pipeline.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# test-pipeline.sh — offline smoke test for /video:* against
+# agents/ai-video/examples/banana-arc/. Dry-run only; no network.
+#
+# Asserts (per agents/roadmaps/ai-video-pipeline.md Phase 6 Step 3):
+#   1. parse-blueprint.sh output matches the committed expected.json
+#      per scene (3 scenes, 3 tiers).
+#   2. character.json descriptor tokens (silhouette, palette, wardrobe,
+#      prop) appear verbatim in each scene's prompt.subject — the
+#      load-bearing character-lock substring assertion.
+#   3. audio.* branching is correct: scene 2 → enable_native_audio=true,
+#      scenes 1+3 → false.
+#   4. native-audio-capable adapter (gemini-veo) advertises capability
+#      audio=native; non-audio adapter (openai-images) advertises
+#      audio=none; stitch.sh sees audio_embedded per scene.
+#   5. stitch.sh dry-run returns the committed manifest's stitch_output
+#      path without invoking ffmpeg or any network.
+#   6. visual regression: each scene's locked.png is non-empty + has
+#      PNG magic; pairwise NCC ≥ 0.95 when `compare` is available.
+#      When unavailable, asserts byte-identity (the three frames are
+#      committed identical for the offline path).
+#
+# Exit 0 = all assertions pass; 1 = at least one failure (counted +
+# summarized at the end).
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROJECT="$ROOT/agents/ai-video/examples/banana-arc"
+
+PASS=0
+FAIL=0
+FAILS=""
+
+ok()   { PASS=$((PASS+1)); printf '  ✅  %s\n' "$1"; }
+fail() { FAIL=$((FAIL+1)); FAILS="$FAILS\n  ❌  $1"; printf '  ❌  %s\n' "$1"; }
+
+require() {
+  if command -v "$1" >/dev/null 2>&1; then return 0; fi
+  fail "required tool missing: $1"
+  return 1
+}
+
+require jq || exit 1
+
+printf '\n== test-pipeline.sh — banana-arc golden run (offline) ==\n\n'
+
+# ---------------------------------------------------------------- 1
+printf '[1/6] parse-blueprint vs. expected.json\n'
+SCENES="01-simple 02-dialogue-native-audio 03-edge-duration"
+for s in $SCENES; do
+  actual="$(bash "$ROOT/scripts/ai-video/lib/parse-blueprint.sh" "$PROJECT/scenes/$s/blueprint.txt" 2>/dev/null \
+    | jq -S . 2>/dev/null || true)"
+  expected="$(jq -S . "$PROJECT/scenes/$s/expected.json" 2>/dev/null || true)"
+  if [ -z "$actual" ]; then
+    fail "$s: parse-blueprint produced no output"
+  elif [ "$actual" = "$expected" ]; then
+    ok "$s: parse-blueprint matches expected.json"
+  else
+    fail "$s: parse-blueprint mismatch (diff actual vs. expected.json)"
+  fi
+done
+
+# ---------------------------------------------------------------- 2
+printf '\n[2/6] character.json descriptors verbatim in prompt.subject\n'
+SILHOUETTE="$(jq -r '.characters[0].silhouette' "$PROJECT/character.json")"
+PALETTE="$(jq -r '.characters[0].palette'    "$PROJECT/character.json")"
+WARDROBE="$(jq -r '.characters[0].wardrobe'  "$PROJECT/character.json")"
+PROP="$(jq -r '.characters[0].prop'          "$PROJECT/character.json")"
+
+for s in $SCENES; do
+  subj="$(jq -r '.prompt.subject' "$PROJECT/scenes/$s/expected.json")"
+  miss=""
+  case "$subj" in *"$SILHOUETTE"*) :;; *) miss="$miss silhouette";; esac
+  case "$subj" in *"$PALETTE"*)    :;; *) miss="$miss palette";; esac
+  case "$subj" in *"$WARDROBE"*)   :;; *) miss="$miss wardrobe";; esac
+  case "$subj" in *"$PROP"*)       :;; *) miss="$miss prop";; esac
+  if [ -z "$miss" ]; then
+    ok "$s: silhouette + palette + wardrobe + prop verbatim in prompt.subject"
+  else
+    fail "$s: missing verbatim tokens in prompt.subject:$miss"
+  fi
+done
+
+# ---------------------------------------------------------------- 3
+printf '\n[3/6] audio.* branching matches manifest\n'
+for entry in 01-simple:false 02-dialogue-native-audio:true 03-edge-duration:false; do
+  s="${entry%%:*}"
+  want="${entry##*:}"
+  got="$(jq -r '.audio.enable_native_audio' "$PROJECT/scenes/$s/expected.json")"
+  manifest_got="$(jq -r --arg id "$s" '.scenes[] | select(.id==$id) | .audio_embedded' "$PROJECT/manifest.json")"
+  if [ "$got" = "$want" ] && [ "$manifest_got" = "$want" ]; then
+    ok "$s: enable_native_audio=$got, manifest.audio_embedded=$manifest_got"
+  else
+    fail "$s: audio branching drift (expected=$want, blueprint=$got, manifest=$manifest_got)"
+  fi
+done
+
+# ---------------------------------------------------------------- 4
+printf '\n[4/6] adapter capability declarations\n'
+declare_caps() {
+  local adapter="$1"; local expected="$2"
+  local out got
+  out="$(AIV_DRYRUN=true bash "$ROOT/scripts/ai-video/adapters/$adapter.sh" capability 2>/dev/null || true)"
+  got="$(printf '%s' "$out" | jq -r '.audio // empty' 2>/dev/null || true)"
+  if [ "$got" = "$expected" ]; then
+    ok "$adapter: capability.audio=$got"
+  else
+    fail "$adapter: capability mismatch (want audio=$expected, got: ${got:-<unparseable: $out>})"
+  fi
+}
+declare_caps gemini-veo    "native"
+declare_caps openai-images "none"
+declare_caps sora          "native"
+declare_caps kling         "none"
+
+# ---------------------------------------------------------------- 5
+printf '\n[5/6] stitch.sh dry-run returns manifest output path\n'
+STITCH_OUT="$(jq -r '.stitch_output' "$PROJECT/manifest.json")"
+stitch_log="$(AIV_DRYRUN=true bash "$ROOT/scripts/ai-video/stitch.sh" \
+  "$PROJECT/manifest.json" "$PROJECT/$STITCH_OUT" 2>&1 || true)"
+case "$stitch_log" in
+  *"$STITCH_OUT"*) ok   "stitch.sh dry-run referenced $STITCH_OUT";;
+  *)               fail "stitch.sh dry-run did not reference $STITCH_OUT (log: $stitch_log)";;
+esac
+
+# ---------------------------------------------------------------- 6
+printf '\n[6/6] visual regression (locked.png pairwise)\n'
+PNG_MAGIC="$(printf '\x89PNG\r\n\x1a\n')"
+prev=""
+have_compare=0
+command -v compare >/dev/null 2>&1 && have_compare=1
+for s in $SCENES; do
+  f="$PROJECT/scenes/$s/fixtures/frames/locked.png"
+  if [ ! -s "$f" ]; then
+    fail "$s: locked.png missing or empty"
+    continue
+  fi
+  head -c 8 "$f" | od -An -c | tr -d ' \n' | grep -q '211PNG' \
+    && ok "$s: locked.png is a valid PNG ($(wc -c < "$f" | tr -d ' ') bytes)" \
+    || fail "$s: locked.png lacks PNG magic"
+  if [ -n "$prev" ]; then
+    if [ "$have_compare" -eq 1 ]; then
+      ncc="$(compare -metric NCC "$prev" "$f" null: 2>&1 || true)"
+      awk_ok="$(awk -v v="$ncc" 'BEGIN { exit !(v+0 >= 0.95) }' && echo yes || echo no)"
+      if [ "$awk_ok" = "yes" ]; then
+        ok "$s: NCC vs. previous = $ncc (≥ 0.95)"
+      else
+        fail "$s: NCC vs. previous = $ncc (< 0.95)"
+      fi
+    else
+      if cmp -s "$prev" "$f"; then
+        ok "$s: byte-identical to previous (compare unavailable; offline fallback)"
+      else
+        fail "$s: differs from previous frame and compare is unavailable"
+      fi
+    fi
+  fi
+  prev="$f"
+done
+
+# ----------------------------------------------------------------
+printf '\n----------------\nresult: %d passed · %d failed\n' "$PASS" "$FAIL"
+if [ "$FAIL" -gt 0 ]; then
+  printf '%b\n' "$FAILS"
+  exit 1
+fi
+exit 0

package/scripts/schemas/command.schema.json

@@ -34,6 +34,14 @@
         "pattern": "^[a-z][a-z0-9-]*$"
       }
     },
+    "personas": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "description": "Personas this command invokes (see .agent-src.uncompressed/personas/). Mirrors `skills:`; each entry must match a persona slug."
+    },
     "cluster": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",