paperkit-dev

#!/bin/bash
# -*- mode: sh -*-
# vim: set filetype=sh :

# PaperKit Developer Command Line Interface
# Version: $VERSION
# Development and maintenance commands (requires authorization)
#
# AUTHORIZATION: Two-layer approach
#   1. Local checks (this script) - prevents accidents, can be bypassed by editing
#   2. Service-side enforcement (GitHub Actions) - cannot be bypassed
#
# This script provides local authorization checks for developer convenience.
# However, the actual release process is enforced server-side by GitHub Actions
# using protected environments. Even if these local checks are bypassed, releases
# cannot be published without approval from authorized GitHub users.
#
# See dev-docs/service-side-authorization.md for setup details.

# Get version from YAML config, fallback to VERSION file for backwards compatibility
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Get version from YAML config (get-version.sh handles VERSION file fallback if needed)
if [ -f "$SCRIPT_DIR/.paperkit/tools/get-version.sh" ]; then
VERSION=$("$SCRIPT_DIR/.paperkit/tools/get-version.sh" 2>/dev/null || echo "unknown")
else
VERSION="unknown"
fi

# Get titles from YAML config
if [ -f "$SCRIPT_DIR/.paperkit/tools/get-title.sh" ]; then
TITLE_SHORT=$("$SCRIPT_DIR/.paperkit/tools/get-title.sh" short 2>/dev/null || echo "PaperKit")
TITLE_LONG=$("$SCRIPT_DIR/.paperkit/tools/get-title.sh" long 2>/dev/null || echo "Research Paper Assistant")
else
TITLE_SHORT="PaperKit"
TITLE_LONG="Research Paper Assistant"
fi

# Color codes
BLUE='\033[0;34m'
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m'

# Authorized owners (add git config emails here)
# NOTE: This is a local check only. Service-side authorization is enforced by
# GitHub Actions using protected environments. See dev-docs/service-side-authorization.md
AUTHORIZED_OWNERS=(
)

# Check if current user is authorized
check_authorization() {
local current_email
current_email=$(git config user.email 2>/dev/null)

if [ -z "$current_email" ]; then
echo -e "${RED}Error: Git user.email not configured.${NC}"
echo "Configure with: git config user.email 'your@email.com'"
return 1
fi

for authorized in "${AUTHORIZED_OWNERS[@]}"; do
if [ "$current_email" = "$authorized" ]; then
return 0
fi
done

echo -e "${RED}Error: Unauthorized user.${NC}"
echo "Current git user: $current_email"
echo "Authorized users: ${AUTHORIZED_OWNERS[*]}"
echo ""
echo "Only repository owners can run development commands."
return 1
}

# Show version
show_version() {
echo -e "${YELLOW}${TITLE_SHORT}${NC} ${GREEN}Current Version${NC} $VERSION"
}

# Main help
show_help() {
echo ""
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo ""
echo -e "  ${YELLOW}${TITLE_SHORT}${NC} ${TITLE_LONG} Developer CLI. ${GREEN}Version${NC} $VERSION"
echo ""
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo ""
echo -e "${YELLOW}USAGE${NC}"
echo "  paperkit-dev <command> [options]"
echo ""
echo -e "${YELLOW}DEVELOPER COMMANDS${NC}"
echo -e "  ${GREEN}release${NC}                Create release tags and distribution bundles"
echo -e "  ${GREEN}version${NC}                Manage version (bump, set, view)"
echo -e "  ${GREEN}help${NC}                   Show this help message"
echo ""
echo -e "${YELLOW}AUTHORIZATION${NC}"
echo "  Local checks: Based on git user.email (can be bypassed)"
echo "  Service-side: GitHub Actions with protected environments (enforced)"
echo "  Current user: $(git config user.email 2>/dev/null || echo 'not configured')"
echo ""
echo "  Note: Releases require approval on GitHub even if local checks pass."
echo "  See: dev-docs/service-side-authorization.md"
echo ""
echo -e "${YELLOW}EXAMPLES${NC}"
echo -e "  ${BLUE}#${NC} Create a new release"
echo "  paperkit-dev release --full"
echo ""
echo -e "  ${BLUE}#${NC} Bump patch version"
echo "  paperkit-dev version --bump patch"
echo ""
echo -e "  ${BLUE}#${NC} Set specific version"
echo "  paperkit-dev version --set alpha-1.3.0"
echo ""
echo "For detailed help on a command, use: paperkit-dev <command> --help"
echo ""
}

# Version command (supports flags for update/info)
version_usage() {
echo ""
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo ""
echo -e "  ${YELLOW}${TITLE_SHORT}${NC} Version Management. ${GREEN}Current Version${NC} $VERSION"
echo ""
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo ""
echo -e "${YELLOW}USAGE${NC}"
echo "  paperkit-dev version [options]"
echo ""
echo -e "${YELLOW}OPTIONS${NC}"
echo -e "  ${GREEN}(no flags)${NC}             Show current version"
echo -e "  ${GREEN}--get${NC}                  Show current version"
echo -e "  ${GREEN}--info${NC}                 Show full version info (JSON)"
echo -e "  ${GREEN}--set${NC} <version>        Set version (e.g., alpha-1.3.0 or 1.3.0+45)"
echo -e "  ${GREEN}--bump${NC} <part>          Bump semver part: ${CYAN}major${NC}, ${CYAN}minor${NC}, or ${CYAN}patch${NC}"
echo -e "  ${GREEN}--build${NC} <value>        Set build metadata (appends +value)"
echo -e "  ${GREEN}--clear-build${NC}          Remove build metadata"
echo -e "  ${GREEN}--test${NC}                 Run version system tests"
echo ""
echo -e "${YELLOW}AUTHORIZATION${NC}"
echo "  Version modification commands (--set, --bump, --build) require authorization."
echo ""
echo -e "${YELLOW}EXAMPLES${NC}"
echo -e "  ${BLUE}#${NC} Show current version"
echo "  paperkit-dev version"
echo ""
echo -e "  ${BLUE}#${NC} Bump to next patch version"
echo "  paperkit-dev version --bump patch"
echo ""
echo -e "  ${BLUE}#${NC} Set specific version with build metadata"
echo "  paperkit-dev version --set 1.2.3+build.456"
echo ""
}

version_command() {
local action=""
local setval=""
local bumpval=""
local buildval=""
local clear_build=false
local run_tests=false
local needs_auth=false
local bump_requested=false
local set_requested=false
local build_requested=false

while [[ $# -gt 0 ]]; do
case "$1" in
--get)
action="get"
                shift
                ;;
            --info)
                action="info"
                shift
                ;;
            --set)
                needs_auth=true
                set_requested=true
                if [[ -n "${2:-}" && ! "$2" =~ ^-- ]]; then
                    setval="$2"
                    shift 2
                else
                    shift
                fi
                ;;
            --bump)
                needs_auth=true
                bump_requested=true
                if [[ -n "${2:-}" && ! "$2" =~ ^-- ]]; then
                    bumpval="$2"
                    shift 2
                else
                    shift
                fi
                ;;
            --build)
                needs_auth=true
                build_requested=true
                if [[ -n "${2:-}" && ! "$2" =~ ^-- ]]; then
                    buildval="$2"
                    shift 2
                else
                    shift
                fi
                ;;
            --clear-build)
                needs_auth=true
                clear_build=true
                shift
                ;;
            --test)
                run_tests=true
                shift
                ;;
            -h|--help)
                version_usage
                return 0
                ;;
            bump|set|build|major|minor|patch)
                # Catch common mistake of omitting -- prefix
                echo -e "${RED}Error: Invalid syntax - did you mean --${1}?${NC}"
                echo ""
                echo "Correct usage:"
                echo -e "  ${CYAN}./paperkit-dev version --bump <major|minor|patch>${NC}"
                echo -e "  ${CYAN}./paperkit-dev version --set <version>${NC}"
                echo -e "  ${CYAN}./paperkit-dev version --build <metadata>${NC}"
                echo ""
                echo "For more help: paperkit-dev version --help"
                return 1
                ;;
            *)
                # Ignore unknown args and continue
                shift
                ;;
        esac
    done

    # Check authorization for modification operations
    if $needs_auth; then
        check_authorization || return 1
    fi

    # If no flags were requested, just show version (no auth needed)
    if [[ -z "$action" ]] && ! $set_requested && ! $bump_requested && ! $build_requested && ! $clear_build && ! $run_tests; then
        show_version
        return 0
    fi

local VM_SCRIPT="$SCRIPT_DIR/.paperkit/tools/version-manager.py"
local PYTHON_BIN="python3"
if [ -x "$SCRIPT_DIR/.venv/bin/python" ]; then
PYTHON_BIN="$SCRIPT_DIR/.venv/bin/python"
fi

if [ ! -f "$VM_SCRIPT" ]; then
echo -e "${RED}Error: version-manager.py not found.${NC}"
return 1
fi

# Ensure PyYAML is available for update operations
if ! "$PYTHON_BIN" -c "import yaml" 2>/dev/null; then
echo -e "${YELLOW}PyYAML is required for version updates.${NC}"
echo "Install: pip install pyyaml"
return 1
fi

if [[ "$action" == "get" ]]; then
show_version
return 0
fi

if [[ "$action" == "info" ]]; then
"$PYTHON_BIN" "$VM_SCRIPT" info
return $?
fi

# Check if --set was requested but no value provided
if $set_requested && [[ -z "$setval" ]]; then
echo -e "${RED}Error: --set requires a version value${NC}"
echo ""
echo "Examples:"
echo -e "  ${CYAN}./paperkit-dev version --set alpha-1.3.0${NC}"
echo -e "  ${CYAN}./paperkit-dev version --set 2.0.0${NC}"
echo -e "  ${CYAN}./paperkit-dev version --set 1.2.3+build.456${NC}"
echo ""
echo "For more help: paperkit-dev version --help"
return 1
fi

if [[ -n "$setval" ]]; then
"$PYTHON_BIN" "$VM_SCRIPT" set "$setval"
return $?
fi

# Check if --bump was requested but no value provided
if $bump_requested && [[ -z "$bumpval" ]]; then
echo -e "${RED}Error: --bump requires a value${NC}"
echo ""
echo "Valid values for --bump:"
echo -e "  ${CYAN}major${NC}  - Bump major version (e.g., 1.2.3 → 2.0.0)"
echo -e "  ${CYAN}minor${NC}  - Bump minor version (e.g., 1.2.3 → 1.3.0)"
echo -e "  ${CYAN}patch${NC}  - Bump patch version (e.g., 1.2.3 → 1.2.4)"
echo ""
echo "Usage: paperkit-dev version --bump <major|minor|patch>"
echo "For more help: paperkit-dev version --help"
return 1
fi

if [[ -n "$bumpval" ]]; then
if [[ "$bumpval" != "major" && "$bumpval" != "minor" && "$bumpval" != "patch" ]]; then
echo -e "${RED}Error: Invalid bump value '${bumpval}'${NC}"
echo ""
echo "Valid values for --bump:"
echo -e "  ${CYAN}major${NC}  - Bump major version (e.g., 1.2.3 → 2.0.0)"
echo -e "  ${CYAN}minor${NC}  - Bump minor version (e.g., 1.2.3 → 1.3.0)"
echo -e "  ${CYAN}patch${NC}  - Bump patch version (e.g., 1.2.3 → 1.2.4)"
echo ""
echo "Usage: paperkit-dev version --bump <major|minor|patch>"
echo "For more help: paperkit-dev version --help"
return 1
fi
"$PYTHON_BIN" "$VM_SCRIPT" bump "$bumpval"
return $?
fi

# Check if --build was requested but no value provided
if $build_requested && [[ -z "$buildval" ]]; then
echo -e "${RED}Error: --build requires a value${NC}"
echo ""
echo "Example:"
echo -e "  ${CYAN}./paperkit-dev version --build 456${NC}     # Adds +456 to current version"
echo ""
echo "For more help: paperkit-dev version --help"
return 1
fi

if [[ -n "$buildval" ]]; then
local cur
cur=$("$PYTHON_BIN" "$VM_SCRIPT" get 2>/dev/null || echo "")
if [ -z "$cur" ] || [ "$cur" = "unknown" ]; then
cur=$("$SCRIPT_DIR/.paperkit/tools/get-version.sh" 2>/dev/null || echo "unknown")
fi
# Strip existing +build if present
local base_no_build="${cur%%+*}"
"$PYTHON_BIN" "$VM_SCRIPT" set "${base_no_build}+${buildval}"
return $?
fi

if $clear_build; then
local cur
cur=$("$PYTHON_BIN" "$VM_SCRIPT" get 2>/dev/null || echo "")
if [ -z "$cur" ] || [ "$cur" = "unknown" ]; then
cur=$("$SCRIPT_DIR/.paperkit/tools/get-version.sh" 2>/dev/null || echo "unknown")
fi
local base_no_build="${cur%%+*}"
"$PYTHON_BIN" "$VM_SCRIPT" set "$base_no_build"
return $?
fi

if $run_tests; then
"$PYTHON_BIN" "$VM_SCRIPT" test
return $?
fi
}

# Release management
release_usage() {
echo ""
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo ""
echo -e "  ${YELLOW}${TITLE_SHORT}${NC} Release Management"
echo ""
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo ""
echo -e "${YELLOW}USAGE${NC}"
echo "  paperkit-dev release [options]"
echo ""
echo -e "${YELLOW}OPTIONS${NC}"
echo -e "  ${GREEN}--tag${NC}                  Create and push git tag only"
echo -e "  ${GREEN}--bundle${NC}               Create distribution bundle only"
echo -e "  ${GREEN}--full${NC}                 Create tag + bundle + push (complete release)"
echo -e "  ${GREEN}--dry-run${NC}              Show what would happen without making changes"
echo ""
echo -e "${YELLOW}AUTHORIZATION${NC}"
echo "  Release commands require authorization."
echo ""
echo -e "${YELLOW}EXAMPLES${NC}"
echo -e "  ${BLUE}#${NC} Complete release (recommended)"
echo "  paperkit-dev release --full"
echo ""
echo -e "  ${BLUE}#${NC} Preview release actions"
echo "  paperkit-dev release --full --dry-run"
echo ""
echo -e "  ${BLUE}#${NC} Create tag only"
echo "  paperkit-dev release --tag"
echo ""
}

release_command() {
# Check authorization first
check_authorization || return 1

local do_tag=false
local do_bundle=false
local dry_run=false

while [[ $# -gt 0 ]]; do
case "$1" in
--tag)
do_tag=true
;;
--bundle)
do_bundle=true
;;
--full)
do_tag=true
do_bundle=true
;;
--dry-run)
dry_run=true
;;
-h|--help)
release_usage
return 0
;;
*)
echo -e "${RED}Unknown option: $1${NC}"
release_usage
return 1
;;
esac
shift
done

# If no flags, show usage
if ! $do_tag && ! $do_bundle; then
release_usage
return 1
fi

# Check for uncommitted changes (unless dry-run)
if ! $dry_run; then
if ! git diff-index --quiet HEAD --; then
echo ""
echo -e "${YELLOW}⚠️  Warning: You have uncommitted changes!${NC}"
echo ""
echo "Changed files:"
git status -s
echo ""
echo "Options:"
echo -e "  ${CYAN}1)${NC} Commit changes and proceed with release"
echo -e "  ${CYAN}2)${NC} Ignore and proceed with release as-is"
echo -e "  ${CYAN}3)${NC} Cancel release"
echo ""
read -p "Selection [3]: " change_choice
change_choice=${change_choice:-3}

case $change_choice in
1)
echo ""
read -p "Commit message: " commit_msg
if [ -z "$commit_msg" ]; then
echo -e "${RED}Error: Commit message is required.${NC}"
return 1
fi

if ! git add -A; then
echo -e "${RED}Error: Failed to stage changes.${NC}"
return 1
fi

if ! git commit -m "$commit_msg"; then
echo -e "${RED}Error: Failed to commit changes.${NC}"
return 1
fi

echo -e "${GREEN}✓${NC} Changes committed"
if ! git push origin HEAD; then
echo -e "${YELLOW}⚠️  Failed to push changes automatically.${NC}"
echo "You can push manually with: git push origin master"
fi
echo ""
;;
2)
echo -e "${YELLOW}Proceeding with uncommitted changes...${NC}"
echo ""
;;
3)
echo "Release cancelled."
return 0
;;
*)
echo -e "${RED}Invalid selection.${NC}"
return 1
;;
esac
fi
fi

# Get current version
local CURRENT_VERSION
CURRENT_VERSION=$("$SCRIPT_DIR/.paperkit/tools/get-version.sh" 2>/dev/null || echo "unknown")

if [ "$CURRENT_VERSION" = "unknown" ]; then
echo -e "${RED}Error: Unable to determine current version.${NC}"
return 1
fi

echo ""
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo -e "  ${YELLOW}Release Management${NC}"
echo -e "${BLUE}════════════════════════════════════════════════════════════════════════════${NC}"
echo ""
echo -e "${GREEN}Current Version:${NC} $CURRENT_VERSION"
if $dry_run; then
echo -e "${YELLOW}Mode: DRY RUN (no changes will be made)${NC}"
fi
echo ""

# Create git tag
if $do_tag; then
echo -e "${YELLOW}Creating git tag: ${CURRENT_VERSION}${NC}"

if $dry_run; then
echo "  [dry-run] Would create annotated tag: $CURRENT_VERSION"
echo "  [dry-run] Would push tag to origin"
else
# Check if tag already exists
if git rev-parse "$CURRENT_VERSION" >/dev/null 2>&1; then
echo -e "${RED}Error: Tag $CURRENT_VERSION already exists.${NC}"
echo "Use 'paperkit-dev version --bump <part>' to create a new version first."
return 1
fi

# Create annotated tag
if git tag -a "$CURRENT_VERSION" -m "Release $CURRENT_VERSION"; then
echo -e "${GREEN}✓${NC} Created tag: $CURRENT_VERSION"

# Push tag to remote
if git push origin "$CURRENT_VERSION"; then
echo -e "${GREEN}✓${NC} Pushed tag to origin"
else
echo -e "${RED}Error: Failed to push tag to origin.${NC}"
return 1
fi
else
echo -e "${RED}Error: Failed to create tag.${NC}"
return 1
fi
fi
echo ""
fi

# Create distribution bundle
if $do_bundle; then
echo -e "${YELLOW}Creating distribution bundle${NC}"

local BUNDLE_SCRIPT="$SCRIPT_DIR/.paperkit/tools/bundle.sh"

if [ ! -f "$BUNDLE_SCRIPT" ]; then
echo -e "${RED}Error: bundle.sh not found at $BUNDLE_SCRIPT${NC}"
return 1
fi

if $dry_run; then
echo "  [dry-run] Would run: $BUNDLE_SCRIPT"
echo "  [dry-run] Would create: paperkit-${CURRENT_VERSION}.tar.gz"
else
if bash "$BUNDLE_SCRIPT"; then
echo -e "${GREEN}✓${NC} Created distribution bundle"
else
echo -e "${RED}Error: Failed to create distribution bundle.${NC}"
return 1
fi
fi
echo ""
fi

# Create GitHub release (if both tag and bundle were created)
if $do_tag && $do_bundle && ! $dry_run; then
echo -e "${YELLOW}Creating GitHub release${NC}"

# Check if gh CLI is installed
if ! command -v gh &> /dev/null; then
echo -e "${RED}Error: GitHub CLI (gh) is not installed.${NC}"
echo "Install it from: https://cli.github.com/"
echo ""
echo "Manual steps required:"
echo "  1. Go to GitHub releases page"
echo "  2. Draft a new release from tag: ${CURRENT_VERSION}"
echo "  3. Upload the distribution bundle"
echo "  4. Publish the release"
echo ""
return 1
fi

# Check if authenticated
if ! gh auth status &> /dev/null; then
echo -e "${RED}Error: Not authenticated with GitHub CLI.${NC}"
echo "Run: gh auth login"
echo ""
echo "Manual steps required:"
echo "  1. Go to GitHub releases page"
echo "  2. Draft a new release from tag: ${CURRENT_VERSION}"
echo "  3. Upload the distribution bundle"
echo "  4. Publish the release"
echo ""
return 1
fi

local BUNDLE_FILE="$SCRIPT_DIR/paperkit-${CURRENT_VERSION}.tar.gz"
if [ ! -f "$BUNDLE_FILE" ]; then
echo -e "${RED}Error: Bundle file not found: $BUNDLE_FILE${NC}"
return 1
fi

# Generate release notes
local RELEASE_NOTES="Release $CURRENT_VERSION

**Installation:**
\`\`\`bash
tar -xzf paperkit-${CURRENT_VERSION}.tar.gz
cd paperkit-${CURRENT_VERSION}
./paperkit init
\`\`\`

**What's Changed:**
See [CHANGELOG.md](https://github.com/peternicholls/PaperKit/blob/master/CHANGELOG.md) for details.
"

# Create release with bundle
if gh release create "$CURRENT_VERSION" \
"$BUNDLE_FILE" \
--title "$CURRENT_VERSION" \
--notes "$RELEASE_NOTES"; then
echo -e "${GREEN}✓${NC} Created GitHub release"
echo -e "${GREEN}✓${NC} Uploaded distribution bundle"

# Clean up the bundle file after successful upload
if rm "$BUNDLE_FILE" 2>/dev/null; then
echo -e "${GREEN}✓${NC} Cleaned up local bundle file"
fi
else
echo -e "${RED}Error: Failed to create GitHub release.${NC}"
echo ""
echo "Manual steps required:"
echo "  1. Go to GitHub releases page"
echo "  2. Draft a new release from tag: ${CURRENT_VERSION}"
echo "  3. Upload: $BUNDLE_FILE"
echo "  4. Publish the release"
echo ""
return 1
fi
echo ""
elif $dry_run && $do_tag && $do_bundle; then
echo -e "${YELLOW}Creating GitHub release${NC}"
echo "  [dry-run] Would create GitHub release: $CURRENT_VERSION"
echo "  [dry-run] Would upload: paperkit-${CURRENT_VERSION}.tar.gz"
echo ""
fi

# Summary
echo -e "${GREEN}Release process complete!${NC}"
echo ""

if $do_tag && $do_bundle && ! $dry_run; then
echo "GitHub release: https://github.com/peternicholls/PaperKit/releases/tag/${CURRENT_VERSION}"
echo ""
elif $do_bundle && ! $dry_run; then
# Only show bundle path if it still exists (wasn't cleaned up)
if [ -f "$SCRIPT_DIR/paperkit-${CURRENT_VERSION}.tar.gz" ]; then
echo "Distribution bundle created:"
echo "  paperkit-${CURRENT_VERSION}.tar.gz"
echo ""
fi
fi
}

# Main command dispatcher
case "${1:-help}" in
release)
shift
release_command "$@"
;;
version|--version|-v)
shift
version_command "$@"
;;
help|--help|-h|"")
show_help
;;
*)
echo -e "${RED}Unknown command: $1${NC}"
echo ""
show_help
exit 1
;;
esac