spine-framework 0.3.145 → 0.4.0

package/scripts/assemble-functions.sh

@@ -1,65 +1,161 @@
 #!/usr/bin/env bash
 
+# CIL[BEGIN stable_id="~/scripts/assemble-functions.sh:module:script" type="script" identity="assemble-functions" parent="~/scripts/assemble-functions.sh"]
+# CIL[DOC-MACRO purpose="Assemble .framework/functions + custom functions into the flat .assembled/netlify/functions dir Netlify deploys, with duplicate-handler detection."]
+# CIL[DOC-RESPONSIBILITY responsibility="Stage framework functions then custom/functions and custom/apps/*/functions into a temp dir, enforcing basename uniqueness; publish via mtime-preserving rsync."]
+# CIL[DOC-CONTEXT module="assembly" layer="build" related_files="scripts/assemble-frontend.sh,scripts/assemble.sh,netlify.toml"]
+# CIL[DOC-CONTRACT inputs=".framework/functions,custom/functions,custom/apps/*/functions; env SPINE_PROJECT_ROOT (fixture override for tests)" outputs=".assembled/netlify/functions; exit 1 on duplicate basename" errors="hard error naming both sources on basename collision; symlink dev-aliases resolving inside .framework/functions skip silently" side_effects="rewrites .assembled/netlify/functions"]
+# CIL[DOC-MICRO logic_summary="Manifest-tracked staging: each staged basename records its source path; collisions resolve via is_dev_alias (macOS-safe readlink resolution) or fail. Excludes _quarantine and *-test.ts/*.test.ts." notable_decisions="flat layout is required by Netlify, so last-wins overwrite is forbidden; PROJECT_ROOT canonicalized with pwd -P so /var→/private/var symlinked TMPDIR fixtures still match"]
+# CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+# CIL[DOC-STABILITY stability="stable"]
+# CIL[END stable_id="~/scripts/assemble-functions.sh:module:script"]
+
 # Functions Assembly - Merge .framework + custom functions into .assembled/
-# 
+#
 # Purpose: Create unified functions directory for Netlify deployment.
 # - .framework/functions are the canonical Spine runtime
-# - custom/functions are your custom extensions
+# - custom/functions + custom/apps/<app>/functions are your custom extensions
 # - Netlify requires a single functions directory, so we assemble at build time
-# 
-# Process: 
+#
+# Process:
 # 1. Assemble into temp directory first (prevents Netlify observing half-deleted dir)
 # 2. Copy core functions
-# 3. Overlay custom functions (overwrites existing)
-# 4. Atomic move to target directory
-# 
-# Dependencies: standard bash utilities, find, cp, rsync, mv
+# 3. Overlay custom functions — with duplicate-handler detection:
+#    a custom file whose basename is already staged must either be a symlink
+#    resolving inside .framework/functions (safe dev alias → skipped silently)
+#    or a HARD ERROR naming both source paths (no silent last-wins overwrite)
+# 4. rsync -c into target so unchanged files keep their mtimes — Netlify/esbuild
+#    then only rebundles functions that actually changed
+#
+# SPINE_PROJECT_ROOT (optional): override the project root — used by the
+# fixture-based unit tests; production use leaves it unset.
+#
+# Dependencies: standard bash utilities, find, cp, rsync, readlink
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+# Canonicalize (-P resolves symlinks) so dev-alias prefix checks compare
+# physical paths — e.g. macOS /var → /private/var under TMPDIR.
+PROJECT_ROOT="$(cd "${SPINE_PROJECT_ROOT:-$(dirname "$SCRIPT_DIR")}" && pwd -P)"
 
 CORE_DIR="$PROJECT_ROOT/.framework/functions"
 CUSTOM_DIR="$PROJECT_ROOT/custom"
 TARGET_DIR="$PROJECT_ROOT/.assembled/netlify/functions"
 TMP_DIR="$PROJECT_ROOT/.functions-assemble-tmp"
+# basename → source-file map for duplicate-handler error messages
+STAGE_MANIFEST="$TMP_DIR.manifest.tsv"
 
 echo "🔧 Assembling functions → $TARGET_DIR"
 
 # 1. Assemble into a temp directory first so Netlify never observes a half-deleted functions dir
 rm -rf "$TMP_DIR"
 mkdir -p "$TMP_DIR"
+: > "$STAGE_MANIFEST"
+
+# Resolve a symlink to an absolute path (macOS readlink has no -f).
+resolve_link() {
+  local f="$1" t d
+  t="$(readlink "$f")" || return 1
+  case "$t" in
+    /*) printf '%s\n' "$t" ;;
+    *)
+      d="$(cd "$(dirname "$f")" && cd "$(dirname "$t")" && pwd -P)" || return 1
+      printf '%s/%s\n' "$d" "$(basename "$t")"
+      ;;
+  esac
+}
+
+# True when $1 is a symlink whose target resolves inside $CORE_DIR —
+# a safe dev alias back to the framework copy, not an override.
+is_dev_alias() {
+  local f="$1" resolved
+  [ -L "$f" ] || return 1
+  resolved="$(resolve_link "$f")" || return 1
+  case "$resolved" in
+    "$CORE_DIR"|"$CORE_DIR"/*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Copy top-level .ts files from $1 (excluding tests) into the flat TMP_DIR.
+# Basename already staged → dev-alias skip or hard error naming both sources.
+stage_fn_files() {
+  local src_dir="$1"
+  local f base staged prev
+  while IFS= read -r -d '' f; do
+    base="$(basename "$f")"
+    staged="$TMP_DIR/$base"
+    if [ -e "$staged" ]; then
+      if is_dev_alias "$f"; then
+        continue  # dev alias → framework copy already staged, skip silently
+      fi
+      prev="$(awk -F '\t' -v b="$base" '$1 == b { print $2; exit }' "$STAGE_MANIFEST")"
+      echo "  ✗ Duplicate function handler: '$base' is provided by both" >&2
+      echo "      - $prev" >&2
+      echo "      - $f" >&2
+      echo "    Rename one of them — functions assemble flat, last-wins is forbidden." >&2
+      exit 1
+    fi
+    cp "$f" "$staged"
+    printf '%s\t%s\n' "$base" "$f" >> "$STAGE_MANIFEST"
+  done < <(find "$src_dir" -maxdepth 1 -name '*.ts' ! -name '*-test.ts' ! -name '*.test.ts' -print0 | sort -z)
+}
+
+# Copy subdirectories of $1 into TMP_DIR, merging by basename. A real custom
+# dir may overlay a framework dir (e.g. _shared helpers); a symlinked dir is a
+# dev alias when it resolves inside .framework/functions — skipped silently if
+# the name is already staged — otherwise a colliding symlink is a hard error.
+stage_fn_dirs() {
+  local src_dir="$1"
+  local d base
+  while IFS= read -r -d '' d; do
+    base="$(basename "$d")"
+    [ "$base" = "_quarantine" ] && continue
+    if [ -L "$d" ]; then
+      if [ -e "$TMP_DIR/$base" ]; then
+        if is_dev_alias "$d"; then
+          continue
+        fi
+        echo "  ✗ Duplicate function path: '$base' is provided by both" >&2
+        echo "      - $TMP_DIR/$base (already staged)" >&2
+        echo "      - $d -> $(readlink "$d")" >&2
+        exit 1
+      fi
+      cp -R "$d" "$TMP_DIR/" 2>/dev/null || true
+      continue
+    fi
+    # real dir: merge into staged dir if present (cp of dir/. includes dotfiles)
+    mkdir -p "$TMP_DIR/$base"
+    cp -r "$d"/. "$TMP_DIR/$base/" 2>/dev/null || true
+  done < <(find "$src_dir" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) -print0 | sort -z)
+}
 
 # 2. Copy core functions (base layer), excluding _quarantine and test files
 if [ -d "$CORE_DIR" ]; then
-  # Copy all files except _quarantine directory and test files (*-test.ts, *.test.ts)
-  find "$CORE_DIR" -maxdepth 1 -name '*.ts' ! -name '*-test.ts' ! -name '*.test.ts' -exec cp {} "$TMP_DIR"/ \;
-  # Copy subdirectories except _quarantine
-  find "$CORE_DIR" -maxdepth 1 -mindepth 1 -type d ! -name '_quarantine' -exec cp -r {} "$TMP_DIR"/ \;
+  stage_fn_files "$CORE_DIR"
+  stage_fn_dirs "$CORE_DIR"
   echo "  ✓ Core: $(find "$CORE_DIR" -name '*.ts' | grep -v '_quarantine' | grep -v '\-test\.ts$' | grep -v '\.test\.ts$' | wc -l | tr -d ' ') files"
 fi
 
-# 3. Overlay custom functions (overrides + additions), excluding test files
+# 3. Overlay custom functions (additions; basename collisions error out above),
+# excluding test files
 CUSTOM_COUNT=0
 
-# 3a. Copy functions from custom/functions/
+# 3a. Functions from custom/functions/
 if [ -d "$CUSTOM_DIR/functions" ]; then
-  # Copy all files except test files (*-test.ts, *.test.ts)
-  find "$CUSTOM_DIR/functions" -maxdepth 1 -name '*.ts' ! -name '*-test.ts' ! -name '*.test.ts' -exec cp {} "$TMP_DIR"/ \; 2>/dev/null || true
-  # Copy subdirectories if any
-  find "$CUSTOM_DIR/functions" -mindepth 1 -type d -exec sh -c 'dir="$1"; base=$(basename "$dir"); mkdir -p "'"$TMP_DIR"'/$base" && cp -r "$dir"/* "'"$TMP_DIR"'/$base/"' _ {} \; 2>/dev/null || true
+  stage_fn_files "$CUSTOM_DIR/functions"
+  stage_fn_dirs "$CUSTOM_DIR/functions"
   CUSTOM_COUNT=$((CUSTOM_COUNT + $(find "$CUSTOM_DIR/functions" -name '*.ts' ! -name '*-test.ts' ! -name '*.test.ts' 2>/dev/null | wc -l | tr -d ' ')))
 fi
 
-# 3b. Copy functions from custom/apps/*/functions/
+# 3b. Functions from custom/apps/*/functions/ — app-vs-framework AND
+# app-vs-app basename collisions both hit the same staged-name check.
 if [ -d "$CUSTOM_DIR/apps" ]; then
-  for app_dir in "$CUSTOM_DIR/apps"/*; do
+  for app_dir in "$CUSTOM_DIR/apps"/*/; do
     if [ -d "$app_dir/functions" ]; then
-      # Copy all files except test files (*-test.ts, *.test.ts)
-      find "$app_dir/functions" -maxdepth 1 -name '*.ts' ! -name '*-test.ts' ! -name '*.test.ts' -exec cp {} "$TMP_DIR"/ \; 2>/dev/null || true
-      # Copy subdirectories if any
-      find "$app_dir/functions" -mindepth 1 -type d -exec sh -c 'dir="$1"; base=$(basename "$dir"); mkdir -p "'"$TMP_DIR"'/$base" && cp -r "$dir"/* "'"$TMP_DIR"'/$base/"' _ {} \; 2>/dev/null || true
+      stage_fn_files "$app_dir/functions"
+      stage_fn_dirs "$app_dir/functions"
       APP_COUNT=$(find "$app_dir/functions" -name '*.ts' ! -name '*-test.ts' ! -name '*.test.ts' 2>/dev/null | wc -l | tr -d ' ')
       CUSTOM_COUNT=$((CUSTOM_COUNT + APP_COUNT))
       echo "  ✓ $(basename "$app_dir"): $APP_COUNT files"
@@ -67,16 +163,18 @@ if [ -d "$CUSTOM_DIR/apps" ]; then
   done
 fi
 
-if [ $CUSTOM_COUNT -gt 0 ]; then
+if [ "$CUSTOM_COUNT" -gt 0 ]; then
   echo "  ✓ Custom: $CUSTOM_COUNT total files"
 else
   echo "  ○ Custom: (empty)"
 fi
 
-# 4. Atomically swap temp into place
-rm -rf "$TARGET_DIR"
+# 4. Sync temp into place. -c compares content checksums; deliberately NO -t —
+# otherwise rsync "corrects" mtimes of unchanged files to the fresh temp-copy
+# time and Netlify/esbuild reloads all ~100 functions on every assemble.
 mkdir -p "$(dirname "$TARGET_DIR")"
-mv "$TMP_DIR" "$TARGET_DIR"
+rsync -rlc --delete "$TMP_DIR"/ "$TARGET_DIR"/
+rm -rf "$TMP_DIR" "$STAGE_MANIFEST"
 
 echo "  ✓ Assembled: $(find "$TARGET_DIR" -name '*.ts' ! -name '*-test.ts' ! -name '*.test.ts' | wc -l | tr -d ' ') total functions"
 echo "✅ Done"

package/scripts/boundary-check.sh

@@ -29,8 +29,9 @@ fi
 echo ""
 
 # Check 2: Core importing custom_ prefixed modules
+# Only flag actual import/require statements — comments and docs are fine
 echo "2. Checking for custom_ module imports in core..."
-if grep -r "from.*custom_\|import.*custom_" .framework/ --include="*.ts" --include="*.tsx" 2>/dev/null; then
+if grep -rE "^\s*(import|export).*['\"].*custom_|require\(['\"].*custom_" .framework/ --include="*.ts" --include="*.tsx" 2>/dev/null; then
     echo "   ❌ FAIL: Core files import custom_ modules"
     VIOLATIONS=$((VIOLATIONS + 1))
 else
@@ -39,8 +40,11 @@ fi
 echo ""
 
 # Check 2b: Custom apps using relative paths to .framework/ (should use @core alias instead)
+# Only flag actual import/require statements — comments and docs are fine.
+# mcp/ dirs are local dev MCP servers, not bundled frontend/function code —
+# @core does not resolve there, so relative imports are the only option.
 echo "2b. Checking custom apps use @core alias (not relative paths to .framework/)..."
-if grep -r "from.*\.\./.*\.framework\|from.*\.framework/" custom/ --include="*.ts" --include="*.tsx" 2>/dev/null; then
+if grep -rE "^\s*(import|export).*from\s+['\"][^'\"]*\.framework|require\(['\"][^'\"]*\.framework" custom/ --include="*.ts" --include="*.tsx" --exclude-dir=mcp 2>/dev/null; then
     echo "   ❌ FAIL: Custom apps use relative paths to .framework/ — use @core alias instead"
     VIOLATIONS=$((VIOLATIONS + 1))
 else

package/scripts/build-manifest.sh

@@ -1,80 +1,36 @@
 #!/usr/bin/env bash
-
-/**
- * @module scripts/build-manifest
- * @audience installer
- * @layer build
- * @stability orphaned
- *
- * Build Manifest Generator - Generate a signed manifest of core file hashes.
- * **ORPHANED**: References non-existent `core/` directory (should be `v2-core/`).
- * 
- * **Intended Purpose**: Used for build-time integrity verification.
- * - In dev mode (SPINE_INTEGRITY=warn), mismatches log warnings
- * - In production (SPINE_INTEGRITY=enforce), mismatches fail the build
- * 
- * **Current State**: Cannot function - references wrong directory paths.
- * 
- * **Dependencies**: shasum, standard bash utilities
- * 
- * @tags orphaned, build, integrity, manifest, verification
- */
+# CIL[BEGIN stable_id="~/scripts/build-manifest.sh:module:script" type="script" identity="build-manifest" parent="~/scripts/build-manifest.sh"]
+# CIL[DOC-MACRO purpose="Thin wrapper that regenerates .spine-manifest.json via scripts/checksum-manifest.mts"]
+# CIL[DOC-RESPONSIBILITY responsibility="Resolve the repo-local tsx binary and invoke the Node manifest generator against this repo root"]
+# CIL[DOC-CONTEXT module="spine-integrity" layer="build" related_files="scripts/checksum-manifest.mts,scripts/verify-integrity.sh,package.json"]
+# CIL[DOC-CONTRACT inputs="optional passthrough args (e.g. --include-dir)" outputs=".spine-manifest.json at repo root" errors="exit 1 when tsx is missing or the generator fails" side_effects="rewrites .spine-manifest.json, echoes SPINE_INTEGRITY mode for compatibility"]
+# CIL[DOC-MICRO logic_summary="Replaces the legacy inline-bash implementation that used GNU-only sort -z and a broken JSDoc header" notable_decisions="hashing lives in Node — BSD/GNU portability and deterministic ordering come free"]
+# CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+# CIL[DOC-STABILITY stability="stable"]
+# CIL[DOC-AUDIENCE audience="system-admin"]
+# CIL[DOC-VECTOR type="context" content="Invoked by npm run manifest"]
+# CIL[DOC-VECTOR type="implementation_pattern" content="Sibling thin wrapper of verify-integrity.sh; real logic in scripts/checksum-manifest.mts" status="ready"]
+# CIL[END stable_id="~/scripts/build-manifest.sh:module:script"]
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
 
-CORE_DIR="$PROJECT_ROOT/.framework"
-CORE_SRC_DIR="$PROJECT_ROOT/.framework/src"
-MANIFEST_FILE="$PROJECT_ROOT/.spine-manifest.json"
-
 INTEGRITY_MODE="${SPINE_INTEGRITY:-warn}"
+echo "🔒 Generating spine integrity manifest (mode: $INTEGRITY_MODE)"
 
-echo "🔒 Generating core integrity manifest (mode: $INTEGRITY_MODE)"
-
-# Collect hashes of all core files
-HASHES="{"
-FIRST=true
-
-# Core functions
-while IFS= read -r -d '' file; do
-  REL_PATH="${file#$PROJECT_ROOT/}"
-  HASH=$(shasum -a 256 "$file" | cut -d' ' -f1)
-  if [ "$FIRST" = true ]; then
-    FIRST=false
-  else
-    HASHES="$HASHES,"
-  fi
-  HASHES="$HASHES\"$REL_PATH\":\"$HASH\""
-done < <(find "$CORE_DIR" -type f -name '*.ts' -print0 | sort -z)
-
-# Core src components (shared, layout, hooks, lib)
-for SUBDIR in components/shared components/layout hooks lib; do
-  DIR="$CORE_SRC_DIR/$SUBDIR"
-  if [ -d "$DIR" ]; then
-    while IFS= read -r -d '' file; do
-      REL_PATH="${file#$PROJECT_ROOT/}"
-      HASH=$(shasum -a 256 "$file" | cut -d' ' -f1)
-      HASHES="$HASHES,\"$REL_PATH\":\"$HASH\""
-    done < <(find "$DIR" -type f \( -name '*.ts' -o -name '*.tsx' \) -print0 | sort -z)
-  fi
-done
+if [ -f "$PROJECT_ROOT/.spine-export-manifest.json" ]; then
+  echo "❌ Frozen standalone export — .spine-manifest.json regeneration is only allowed in the monorepo (.spine-export-manifest.json present)" >&2
+  exit 1
+fi
 
-HASHES="$HASHES}"
+TSX="$PROJECT_ROOT/node_modules/.bin/tsx"
+if [ ! -x "$TSX" ]; then
+  echo "❌ tsx not found at $TSX — run 'npm install' first" >&2
+  exit 1
+fi
 
-# Write manifest
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-cat > "$MANIFEST_FILE" <<EOF
-{
-  "version": "1",
-  "generated_at": "$TIMESTAMP",
-  "integrity_mode": "$INTEGRITY_MODE",
-  "file_count": $(echo "$HASHES" | tr ',' '\n' | wc -l | tr -d ' '),
-  "hashes": $HASHES
-}
-EOF
+"$TSX" "$SCRIPT_DIR/checksum-manifest.mts" "$PROJECT_ROOT" "$PROJECT_ROOT/.spine-manifest.json" "$@"
 
-echo "  ✓ Manifest written to $MANIFEST_FILE"
-echo "  ✓ $(echo "$HASHES" | tr ',' '\n' | wc -l | tr -d ' ') files hashed"
-echo "✅ Done"
+echo "✅ Manifest written"