Starter Kit Upgrade

#!/usr/bin/env bash
# apply_new_files.sh — write upstream HEAD's content for every file the
# classifier reports as `new`, and stage each.
#
# Usage: apply_new_files.sh <kit_dir> <sha> <user_repo>
#
# Files with any other classifier status (already-present, differs,
# deleted-upstream, lockfile) are left alone for the agent to handle
# interactively per Phase 5 step 5.
#
# Prints "applied <path>" for each file written so the caller can include
# the list in the feature commit message and the report.

set -euo pipefail

usage() {
    echo "Usage: $0 <kit_dir> <sha> <user_repo>" >&2
    exit 2
}

[[ $# -lt 3 ]] && usage

kit_dir="$1"
sha="$2"
user_repo="$3"

script_dir="$(cd "$(dirname "$0")" && pwd)"

"$script_dir/classify_feature.sh" "$kit_dir" "$sha" "$user_repo" \
    | awk -F'\t' '$1=="new"{print $2}' \
    | while IFS= read -r path; do
        mkdir -p "$user_repo/$(dirname "$path")"
        git -C "$kit_dir" show "HEAD:$path" > "$user_repo/$path"
        git -C "$user_repo" add -- "$path"
        echo "applied $path"
      done

#!/usr/bin/env bash
# classify_feature.sh — classify each file touched by an upstream feature commit
# against the user's repo, comparing only against upstream's current branch tip.
#
# Usage: classify_feature.sh <kit_dir> <sha> <user_repo>
#
# The SHA enumerates which files the feature touches. Comparison is always
# against upstream HEAD (already checked out in <kit_dir>). The user's git
# history is unrelated to the kit's, so "what was the file before the change"
# is not meaningful on their side.
#
# Per file, prints "<status>\t<path>". Statuses:
#   new                 absent in user repo, exists at upstream HEAD
#   already-present     user's bytes equal upstream HEAD's bytes
#   differs             user has the file but bytes differ from upstream HEAD
#   deleted-upstream    upstream HEAD lacks the file but the user still has it
#   lockfile            composer/package manifest or lockfile (always user-mediated)
#
# All comparisons are byte-exact via diff(1).

set -euo pipefail

kit_dir="$1"
sha="$2"
user_repo="$3"

classify() {
    local path="$1"
    local user_file="$user_repo/$path"

    case "$path" in
        composer.json|composer.lock|package.json|package-lock.json|pnpm-lock.yaml|yarn.lock|bun.lockb|bun.lock)
            printf "lockfile\t%s\n" "$path"
            return
            ;;
    esac

    local upstream
    upstream=$(mktemp)

    # Single call: succeeds iff upstream has the file. No separate existence check.
    if git -C "$kit_dir" show "HEAD:$path" >"$upstream" 2>/dev/null; then
        if [[ -e "$user_file" ]]; then
            if diff -q "$upstream" "$user_file" >/dev/null 2>&1; then
                printf "already-present\t%s\n" "$path"
            else
                printf "differs\t%s\n" "$path"
            fi
        else
            printf "new\t%s\n" "$path"
        fi
    else
        # Upstream HEAD doesn't have this path — only meaningful if the user still does.
        if [[ -e "$user_file" ]]; then
            printf "deleted-upstream\t%s\n" "$path"
        else
            printf "already-present\t%s\n" "$path"
        fi
    fi

    rm -f "$upstream"
}

# diff-tree gives us the paths the feature touched; classification is against HEAD.
git -C "$kit_dir" diff-tree --no-commit-id --name-only --no-renames -r "$sha" \
    | while IFS= read -r path; do
        [[ -z "${path:-}" ]] && continue
        classify "$path"
    done

#!/usr/bin/env bash
# fetch_kit.sh — clone (or update) a Laravel starter kit repo into a local
# cache so other scripts can read upstream state.
#
# Usage: fetch_kit.sh <kit> <branch> [dest]
#   <kit>    one of: vue-starter-kit, react-starter-kit, svelte-starter-kit, livewire-starter-kit
#   <branch> one of: main, teams, workos, workos-teams
#   [dest]   destination dir (default: /tmp/starter-kit-<kit>)
#
# Idempotent: if dest already has a clone of the same repo, fetches the
# branch and resets to upstream rather than re-cloning. Prints the
# destination path on stdout so the caller can capture it (e.g.
# `kit_dir=$(scripts/fetch_kit.sh vue-starter-kit main)`).

set -euo pipefail

usage() {
    echo "Usage: $0 <kit> <branch> [dest]" >&2
    exit 2
}

[[ $# -lt 2 ]] && usage

kit="$1"
branch="$2"
dest="${3:-/tmp/starter-kit-$kit}"

case "$kit" in
    vue-starter-kit|react-starter-kit|svelte-starter-kit|livewire-starter-kit) ;;
    *)
        echo "ERROR: unknown kit '$kit'" >&2
        echo "Supported: vue-starter-kit, react-starter-kit, svelte-starter-kit, livewire-starter-kit" >&2
        exit 3
        ;;
esac

url="https://github.com/laravel/$kit.git"

if [[ -d "$dest/.git" ]]; then
    # Match the exact repo (HTTPS or SSH, with or without .git suffix) so
    # forks like 'vue-starter-kit-fork' don't pass the check.
    existing=$(git -C "$dest" remote get-url origin 2>/dev/null || true)
    if [[ ! "$existing" =~ ^(https://github\.com/|git@github\.com:)laravel/${kit}(\.git)?$ ]]; then
        echo "ERROR: '$dest' exists but is not a clone of laravel/$kit (origin: ${existing:-none})" >&2
        exit 4
    fi

    git -C "$dest" fetch --quiet --depth 500 origin "$branch"
    git -C "$dest" checkout --quiet "origin/$branch"
else
    git clone --quiet --depth 500 --branch "$branch" "$url" "$dest"
fi

echo "$dest"

#!/usr/bin/env bash
# later_edits.sh — for the files a feature commit touches, list which
# of those files have ALSO been modified by later upstream commits.
#
# Usage: later_edits.sh <kit_dir> <sha> <user_repo>
#
# Output: one path per line. If the list is non-empty, copying upstream
# HEAD's content for those paths will pull in changes beyond the feature.
# In that case, scope to <sha>:<path> instead of HEAD:<path> when applying.

set -euo pipefail

usage() {
    echo "Usage: $0 <kit_dir> <sha> <user_repo>" >&2
    exit 2
}

[[ $# -lt 3 ]] && usage

kit_dir="$1"
sha="$2"
user_repo="$3"

script_dir="$(cd "$(dirname "$0")" && pwd)"

# Read paths as an array so filenames with spaces/globs survive intact when
# passed to `git log -- <paths>`.
paths=()
while IFS= read -r path; do
    [[ -n "$path" ]] && paths+=("$path")
done < <("$script_dir/classify_feature.sh" "$kit_dir" "$sha" "$user_repo" | cut -f2)

[[ ${#paths[@]} -eq 0 ]] && exit 0

git -C "$kit_dir" log --name-only --pretty=format: "${sha}..HEAD" -- "${paths[@]}" \
    | sort -u \
    | sed '/^$/d'

#!/usr/bin/env bash
# preflight.sh — verify the user's repo is in a state where the skill can
# safely operate. Run before any side effects.
#
# Usage: preflight.sh <user_repo>
#
# Checks (in order):
#   1. Path is a git repo
#   2. Working tree is clean (no uncommitted changes)
#   3. `gh` is available and authenticated
#   4. `jq` is available
#
# Exits non-zero with a clear message about which check failed and how to fix.
# Exit codes are stable so the agent can branch on them if needed:
#   2 = not a git repo
#   3 = dirty working tree
#   4 = gh missing
#   5 = gh not authenticated
#   6 = jq missing

set -euo pipefail

usage() {
    echo "Usage: $0 <user_repo>" >&2
    exit 2
}

[[ $# -lt 1 ]] && usage

repo="$1"

fail() {
    local code="$1" message="$2" hint="$3"

    echo "FAIL: $message" >&2
    echo "$hint" >&2

    exit "$code"
}

check_git_repo() {
    git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 \
        || fail 2 "'$repo' is not a git repository." \
                  "Run 'git init' (or pass a path inside an existing repo)."
}

check_clean_tree() {
    [[ -z "$(git -C "$repo" status --porcelain)" ]] && return

    echo "FAIL: '$repo' has uncommitted changes." >&2
    echo "Commit or stash them before running this skill." >&2
    git -C "$repo" status --short >&2

    exit 3
}

check_gh_installed() {
    command -v gh >/dev/null 2>&1 \
        || fail 4 "'gh' CLI is not installed." \
                  "Install: https://cli.github.com/"
}

check_gh_authenticated() {
    gh auth status >/dev/null 2>&1 \
        || fail 5 "'gh' is not authenticated." \
                  "Run: gh auth login"
}

check_jq_installed() {
    command -v jq >/dev/null 2>&1 \
        || fail 6 "'jq' is not installed." \
                  "Install via your package manager (e.g. 'brew install jq')."
}

check_git_repo
check_clean_tree
check_gh_installed
check_gh_authenticated
check_jq_installed

echo "preflight: OK"

#!/usr/bin/env bash
# reconcile_manifests.sh — regenerate composer.lock and the JS lockfile
# after the user has merged manifest changes from upstream.
#
# Usage: reconcile_manifests.sh <user_repo>
#
# - Runs `composer install` if composer.json + composer.lock both exist.
# - Auto-detects the JS package manager from the existing lockfile and runs
#   `<pm> install`. On install failure (often ERESOLVE after a major bump),
#   removes node_modules and the lockfile, then reinstalls. The recovery is
#   announced on stderr so the agent can include it in the report.
#
# The user must have already agreed to run this — the script doesn't ask.

set -euo pipefail

usage() {
    echo "Usage: $0 <user_repo>" >&2
    exit 2
}

[[ $# -lt 1 ]] && usage

repo="$1"
cd "$repo"

# Mirror run_tests.sh's auto-detection. Both helpers return non-zero (via
# the `[[ -f package.json ]] || return 1` guard) when the project has no
# package.json, so callers must guard their use behind that check.
js_package_manager() {
    [[ -f package.json ]] || return 1

    if   [[ -f pnpm-lock.yaml ]];           then echo pnpm
    elif [[ -f bun.lockb || -f bun.lock ]]; then echo bun
    elif [[ -f yarn.lock ]];                then echo yarn
    else                                         echo npm
    fi
}

js_lockfile() {
    [[ -f package.json ]] || return 1

    if   [[ -f pnpm-lock.yaml ]]; then echo pnpm-lock.yaml
    elif [[ -f bun.lockb ]];      then echo bun.lockb
    elif [[ -f bun.lock ]];       then echo bun.lock
    elif [[ -f yarn.lock ]];      then echo yarn.lock
    else                               echo package-lock.json
    fi
}

if [[ -f composer.json && -f composer.lock ]]; then
    echo "==> composer install --no-interaction" >&2
    composer install --no-interaction
fi

if [[ -f package.json ]]; then
    pm=$(js_package_manager)
    lock=$(js_lockfile)

    echo "==> $pm install" >&2
    if ! "$pm" install; then
        # Common cause: stale node_modules after a major bump (ERESOLVE).
        # Try the standard recovery once before giving up.
        echo "==> '$pm install' failed; removing node_modules + $lock and retrying" >&2
        rm -rf node_modules "$lock"
        "$pm" install
    fi
fi

#!/usr/bin/env bash
# run_tests.sh — discover and run the user's verification commands, optionally
# comparing pre-upgrade and post-upgrade results so we don't blame the upgrade
# for failures that already existed.
#
# Usage:
#   run_tests.sh <user_repo>                          # run, print summary, exit 0/1
#   run_tests.sh <user_repo> --baseline <out.json>    # record results to out.json
#   run_tests.sh <user_repo> --compare  <baseline.json>  # compare to baseline
#
# Discovery (per category, first match wins):
#   php_tests:    composer.json scripts.test → vendor/bin/pest → vendor/bin/phpunit → php artisan test
#   js_typecheck: package.json scripts.types → scripts.typecheck → scripts.tsc
#   js_build:     package.json scripts.build
#
# All three checks run in parallel. Each check's combined stdout+stderr is
# captured to /tmp/skup-tests-<label>.log so failures can be surfaced.
#
# Results JSON shape (built and parsed with jq — never with grep/sed):
#   {
#     "php_tests":    {"ran": true,  "command": "vendor/bin/pest", "passed": true,  "exit": 0, "log": "/tmp/..."},
#     "js_typecheck": {"ran": false, "reason": "no command discovered"},
#     "js_build":     {"ran": true,  "command": "pnpm run build", "passed": false, "exit": 1, "log": "/tmp/..."}
#   }
#
# Compare mode: prints regressions only — labels that passed in baseline and now fail.

set -uo pipefail

usage() {
    echo "Usage: $0 <user_repo> [--baseline <out.json> | --compare <baseline.json>]" >&2
    exit 2
}

[[ $# -lt 1 ]] && usage
command -v jq >/dev/null 2>&1 || { echo "ERROR: jq is required" >&2; exit 3; }

repo="$1"; shift
mode="run"
ref=""

case "${1:-}" in
    "")            mode="run" ;;
    --baseline)    mode="baseline"; ref="${2:-}"; [[ -z "$ref" ]] && usage ;;
    --compare)     mode="compare";  ref="${2:-}"; [[ -z "$ref" ]] && usage ;;
    *)             usage ;;
esac

cd "$repo"

# Pick the JS package manager; only meaningful when package.json exists.
js_package_manager() {
    [[ -f package.json ]] || return 1
    if [[ -f pnpm-lock.yaml ]]; then echo pnpm
    elif [[ -f bun.lockb || -f bun.lock ]]; then echo bun
    elif [[ -f yarn.lock ]]; then echo yarn
    else echo npm
    fi
}

has_npm_script() {
    [[ -f package.json ]] || return 1
    jq -e --arg s "$1" '.scripts[$s] // empty' package.json >/dev/null 2>&1
}

# Each discover_* prints the discovered command (one line, command + args)
# or nothing if no command exists for that category.
discover_php_tests() {
    if [[ -f composer.json ]] && jq -e '.scripts.test // empty' composer.json >/dev/null 2>&1; then
        echo "composer test"
    elif [[ -x vendor/bin/pest ]]; then echo "vendor/bin/pest"
    elif [[ -x vendor/bin/phpunit ]]; then echo "vendor/bin/phpunit"
    elif [[ -f artisan ]]; then echo "php artisan test"
    fi
}

discover_js_typecheck() {
    local pm; pm=$(js_package_manager) || return 0

    for s in types typecheck tsc; do
        if has_npm_script "$s"; then echo "$pm run $s"; return; fi
    done
}

discover_js_build() {
    local pm; pm=$(js_package_manager) || return 0

    has_npm_script build && echo "$pm run build"
}

# Run a single check in the background. Writes one JSON object to <out_json>.
# stdout+stderr go to /tmp/skup-tests-<label>.log for later surfacing.
run_check() {
    local label="$1" cmd="$2" out_json="$3"
    local logfile="/tmp/skup-tests-${label}.log"

    if [[ -z "$cmd" ]]; then
        jq -nc --arg l "$label" '{($l): {ran: false, reason: "no command discovered"}}' > "$out_json"
        return
    fi

    : > "$logfile"
    bash -c "$cmd" >"$logfile" 2>&1
    local ec=$?
    jq -nc --arg l "$label" --arg c "$cmd" --arg log "$logfile" --argjson ec "$ec" \
        '{($l): {ran: true, command: $c, passed: ($ec == 0), exit: $ec, log: $log}}' > "$out_json"
}

# Run all three checks in parallel and merge their result fragments.
build_results() {
    local php js_t js_b
    php=$(discover_php_tests)
    js_t=$(discover_js_typecheck)
    js_b=$(discover_js_build)

    local f1 f2 f3
    f1=$(mktemp); f2=$(mktemp); f3=$(mktemp)

    run_check php_tests    "$php"  "$f1" &
    run_check js_typecheck "$js_t" "$f2" &
    run_check js_build     "$js_b" "$f3" &
    wait

    jq -s 'add' "$f1" "$f2" "$f3"
    rm -f "$f1" "$f2" "$f3"
}

case "$mode" in
    run)
        results=$(build_results)
        echo "$results"

        # Exit 1 if anything that ran failed.
        if [[ $(echo "$results" | jq '[.. | objects | select(.passed == false)] | length') -gt 0 ]]; then
            exit 1
        fi
        ;;

    baseline)
        build_results > "$ref"
        echo "baseline recorded: $ref" >&2
        ;;

    compare)
        [[ -f "$ref" ]] || { echo "ERROR: baseline '$ref' not found" >&2; exit 2; }

        post=$(build_results)
        regressed=0

        for label in php_tests js_typecheck js_build; do
            was_pass=$(jq -r --arg l "$label" '.[$l].passed == true' "$ref")
            is_fail=$(echo "$post" | jq -r --arg l "$label" '.[$l].passed == false')
            if [[ "$was_pass" == "true" ]] && [[ "$is_fail" == "true" ]]; then
                logfile=$(echo "$post" | jq -r --arg l "$label" '.[$l].log // ""')
                echo "REGRESSION: $label was passing, now fails (log: $logfile)" >&2
                regressed=1
            fi
        done

        echo "$post"
        exit $regressed
        ;;
esac

#!/usr/bin/env bash
# scan_transitive_imports.sh — scan applied `new` files for imports that
# may point at helpers absent in the user's repo.
#
# Usage: scan_transitive_imports.sh <kit> <new_files...>
#   <kit>  one of: vue-starter-kit, react-starter-kit, svelte-starter-kit, livewire-starter-kit
#
# Vue / React / Svelte: TS/JS imports with @, ~, ./, ../ aliases.
# Livewire: Blade includes, x-components, livewire tags.
#
# Output mirrors `grep -EHn` so the agent sees `<file>:<line>:<match>` for
# every import. Empty output means no transitive imports to chase. Always
# exits 0 — finding nothing is not an error.

set -euo pipefail

usage() {
    echo "Usage: $0 <kit> <new_files...>" >&2
    exit 2
}

[[ $# -lt 2 ]] && usage

kit="$1"; shift

# Pick the import-style regex for the kit. Same DRY shape as run_tests.sh's
# discover_* helpers: each kit maps to one canonical pattern.
case "$kit" in
    vue-starter-kit|react-starter-kit|svelte-starter-kit)
        pattern="from ['\"](@/|~/|\\./|\\.\\./)"
        ;;
    livewire-starter-kit)
        pattern="@(include|extends|component|livewire)\\(|<x-|<livewire:"
        ;;
    *)
        echo "ERROR: unknown kit '$kit'" >&2
        exit 3
        ;;
esac

grep -EHn "$pattern" "$@" 2>/dev/null || true