diff --git a/AGENTS.md b/AGENTS.md index 653b780..2c7f6b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -765,6 +765,150 @@ Use this checklist when generating QUICKSTART.md: - [ ] Verified all links work - [ ] Ensured consistency with README.md +## Protocol: Cleanup Leftover Files + +This protocol provides instructions for cleaning up leftover files that do not match the original repository's expected file structure. This commonly occurs when a new codebase is scaffolded or generated from this template and produces files that diverge from the canonical layout. + +> **IMPORTANT**: This protocol should **only** be executed when explicitly prompted by a user or LLM. Do not run the cleanup script automatically or as part of CI/CD pipelines. + +### Purpose + +When creating a new codebase from this template repository, the generated project may contain files that are not part of the original repo structure. These leftover files can cause confusion, bloat the repository, and lead to inconsistencies. The `cleanup.sh` script identifies and removes them. + +### Prerequisites + +- A cloned copy of the repository +- The `cleanup.sh` script in the repository root +- All work committed or backed up (the script deletes files permanently) + +### When to Use This Protocol + +Use this protocol **only** when: + +1. An LLM or developer explicitly requests a cleanup of leftover files +2. A new codebase has been generated from this template and contains extra files +3. You need to verify that the current file structure matches the expected layout + +**Do NOT** use this protocol: + +- Automatically during CI/CD +- Without first committing or backing up current work +- Without reviewing the list of files to be deleted + +### Protocol Steps + +#### Step 1: Commit Current Work + +Before running any cleanup, ensure all work is saved: + +```bash +git add . +git commit -m "chore: save work before cleanup" +``` + +#### Step 2: Review the Expected File List + +Open `cleanup.sh` and review the `EXPECTED_FILES` array. Update it if the canonical repository structure has changed: + +```bash +# Open and review the expected files list +cat cleanup.sh | grep -A 100 'EXPECTED_FILES=(' +``` + +#### Step 3: Uncomment the Script + +The `cleanup.sh` script is fully commented out by default. To activate it: + +1. Open `cleanup.sh` in your editor +2. Remove the leading `# ` from all lines in the **CONFIGURATION** section (`EXPECTED_FILES` array) +3. Remove the leading `# ` from all lines in the **ACTIVE CODE** section +4. **Confirm that the `EXPECTED_FILES` array is uncommented and non-empty before running the script.** + +> **Warning:** If `EXPECTED_FILES` is empty or still commented out, the script will treat **every file in the repository** as a leftover. If you confirm deletion in that state, you can delete the entire repo. + +#### Step 4: Run the Script (with a sanity check) + +Before allowing any deletion: + +- Visually confirm that `EXPECTED_FILES` contains a reasonable list of expected files/directories. +- On the first run, you can treat the script as a *dry run* by answering **“no”** at the deletion confirmation prompt. This lets you inspect the list of “leftover” files without deleting anything. + +When you are satisfied with the configuration, run: +```bash +bash cleanup.sh +``` + +The script will: + +1. Verify you are in a git repository root +2. Scan all files (excluding `.git/`) +3. Compare them against the `EXPECTED_FILES` list +4. Display any leftover files that do not match +5. Prompt for confirmation before deleting + +#### Step 5: Review and Confirm + +- Review the list of leftover files displayed by the script +- Only confirm deletion if you are certain the listed files are not needed +- After deletion, the script also removes any empty directories + +#### Step 6: Re-comment the Script + +After use, restore `cleanup.sh` to its default, fully commented state using Git so it remains inert by default: + +```bash +# Verify the cleanup results +git status + +# Restore cleanup.sh to its default (fully commented, inert) state +git restore cleanup.sh # or: git checkout -- cleanup.sh (for older Git versions) +``` + +#### Step 7: Commit the Cleanup + +```bash +git add . +git commit -m "chore: clean up leftover files from scaffolding" +``` + +### Agent Invocation + +This protocol should only be triggered when a user or LLM explicitly requests it: + +```text +@documentation-builder Run the cleanup leftover files protocol. +Remove files that don't match the original repository structure. +``` + +```text +@refactoring-assistant Clean up leftover files in the repository +using the cleanup protocol from AGENTS.md. Follow all steps including +backup, review, and confirmation. +``` + +### Protocol Checklist + +Use this checklist when running the cleanup protocol: + +- [ ] Committed or backed up all current work +- [ ] Reviewed the `EXPECTED_FILES` list in `cleanup.sh` +- [ ] Updated `EXPECTED_FILES` if the canonical structure has changed +- [ ] Uncommented the active code sections in `cleanup.sh` +- [ ] Ran the script and reviewed the list of leftover files +- [ ] Confirmed deletion only after careful review +- [ ] Verified results with `git status` +- [ ] Re-commented `cleanup.sh` to its default state +- [ ] Committed the cleanup changes + +### Best Practices + +1. **Always back up first**: Commit all work before running the cleanup +2. **Review before confirming**: Never blindly confirm file deletion +3. **Keep the script commented**: The default state should be fully commented out +4. **Update the expected list**: Keep `EXPECTED_FILES` current as the repo evolves +5. **Only run when prompted**: This protocol is on-demand only, never automatic +6. **Re-comment after use**: Always return the script to its inert state after cleanup + ## Agent Ideas and Use Cases Here are ideas for agents you might create to enhance your development workflow: @@ -3650,7 +3794,7 @@ To use `bootstrap.sh` in a non-interactive pipeline: Example for a security CI job: ```bash -./bootstrap.sh --env security --yes +bash bootstrap.sh --env security --yes ``` ### Environment Setup @@ -3982,12 +4126,12 @@ git clone https://github.com/swarm-protocol/github.git cd github # 2. Run automated setup (RECOMMENDED) -./bootstrap.sh +bash bootstrap.sh # Or run in non-interactive mode for automation: -./bootstrap.sh --env common --yes -./bootstrap.sh --method nix --env security --yes -./bootstrap.sh --method apt --env all --yes +bash bootstrap.sh --env common --yes +bash bootstrap.sh --method nix --env security --yes +bash bootstrap.sh --method apt --env all --yes # The bootstrap script will: # - Detect your system (Nix or APT) diff --git a/README.md b/README.md index 5fea676..b9a2a38 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ This repository provides ready-to-use templates for creating specialized GitHub Run the bootstrap script to set up your development environment: ```bash -./bootstrap.sh +bash bootstrap.sh ``` ### Automated Setup (Non-interactive) @@ -71,13 +71,13 @@ For automated or CI/CD setup, use the command-line flags to bypass interactive p ```bash # General automated setup (auto-detects method) -./bootstrap.sh --env common --yes +bash bootstrap.sh --env common --yes # Specific method and environment -./bootstrap.sh --method nix --env security --yes +bash bootstrap.sh --method nix --env security --yes # Install all available APT environments -./bootstrap.sh --method apt --env all --yes +bash bootstrap.sh --method apt --env all --yes ``` #### Available Flags: diff --git a/bootstrap.sh b/bootstrap.sh index 17d14e1..146697c 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -26,7 +26,7 @@ ASSUME_YES=false # Helper functions show_help() { - echo "Usage: ./bootstrap.sh [options]" + echo "Usage: bash bootstrap.sh [options]" echo echo "Options:" echo " --method Set the setup method" diff --git a/cleanup.sh b/cleanup.sh new file mode 100755 index 0000000..76b8340 --- /dev/null +++ b/cleanup.sh @@ -0,0 +1,220 @@ +#!/usr/bin/env bash + +############################################################################### +# Cleanup Script for Leftover Files +# +# PURPOSE: +# This script's sole purpose is to delete files that are left over when a +# new codebase is created and the resulting file structure does not match +# the original repository's expected layout. +# +# USAGE: +# This script is FULLY COMMENTED OUT by default. It should only be +# uncommented and executed when explicitly prompted by an LLM or developer. +# +# To use: +# 1. Review the EXPECTED_FILES list below and update it to match your +# repository's canonical file structure. +# 2. Uncomment the active code sections (remove the leading '# ' from +# each line in the "Active Code" sections). +# 3. Run the script: bash cleanup.sh +# 4. Review the output and confirm deletions when prompted. +# 5. Re-comment the script after use to prevent accidental execution. +# +# WARNING: +# - Always commit or back up your work BEFORE running this script. +# - This script will permanently delete files not in the expected list. +# - Review the dry-run output carefully before confirming deletions. +# +# SEE ALSO: +# AGENTS.md - "Protocol: Cleanup Leftover Files" section for full protocol. +############################################################################### + +############################################################################### +# CONFIGURATION +# Define the expected file structure of the original repository. +# Update this list to match your project's canonical files and directories. +# +# TIP: You can generate this list from the original repo with: +# git ls-files | sort +# or: +# find . -not -path './.git/*' -type f | sed 's|^\./||' | sort +############################################################################### + +# EXPECTED_FILES=( +# ".cursor/rules/code-review.md" +# ".cursor/rules/documentation.md" +# ".cursor/rules/general.md" +# ".cursor/rules/testing.md" +# ".dockerignore" +# ".editorconfig" +# ".github/agents/README.md" +# ".github/agents/TEMPLATE.agent.md" +# ".github/agents/ansible-specialist.agent.md" +# ".github/agents/code-reviewer.agent.md" +# ".github/agents/docker-specialist.agent.md" +# ".github/agents/documentation-builder.agent.md" +# ".github/agents/documentation-expert.agent.md" +# ".github/agents/refactoring-assistant.agent.md" +# ".github/agents/security-auditor.agent.md" +# ".github/agents/test-specialist.agent.md" +# ".github/workflows/security-scan.yml" +# ".gitignore" +# "AGENTS.md" +# "CLAUDE.md" +# "CURSOR.md" +# "DOCKERFILE.template" +# "GEMINI.md" +# "LICENSE" +# "N8N.md" +# "QWEN.md" +# "README.md" +# "SUPABASE.md" +# "apt/ansible/packages.txt" +# "apt/code-review/packages.txt" +# "apt/common/packages.txt" +# "apt/docker/packages.txt" +# "apt/documentation/packages.txt" +# "apt/refactoring/packages.txt" +# "apt/security/packages.txt" +# "apt/terraform/packages.txt" +# "apt/test/packages.txt" +# "apt/wrangler/packages.txt" +# "bootstrap.sh" +# "cleanup.sh" +# "data/AGENT_PROMPTS.md" +# "docs/AGENT_PROMPTS.md" +# "nix/ansible/flake.nix" +# "nix/ansible/shell.nix" +# "nix/code-review/flake.nix" +# "nix/code-review/shell.nix" +# "nix/common/flake.nix" +# "nix/common/shell.nix" +# "nix/docker/flake.nix" +# "nix/docker/shell.nix" +# "nix/documentation/flake.nix" +# "nix/documentation/shell.nix" +# "nix/refactoring/flake.nix" +# "nix/refactoring/shell.nix" +# "nix/security/flake.nix" +# "nix/security/shell.nix" +# "nix/terraform/flake.nix" +# "nix/terraform/shell.nix" +# "nix/test/flake.nix" +# "nix/test/shell.nix" +# "nix/wrangler/flake.nix" +# "nix/wrangler/shell.nix" +# "src/AGENT_PROMPTS.md" +# "src/scripts/validate_agents.py" +# "terraform/.gitignore" +# "terraform/examples/worker.js" +# "terraform/main.tf" +# "terraform/modules/dns/main.tf" +# "terraform/modules/dns/outputs.tf" +# "terraform/modules/dns/variables.tf" +# "terraform/modules/pages/main.tf" +# "terraform/modules/pages/outputs.tf" +# "terraform/modules/pages/variables.tf" +# "terraform/modules/workers/main.tf" +# "terraform/modules/workers/outputs.tf" +# "terraform/modules/workers/variables.tf" +# "terraform/outputs.tf" +# "terraform/terraform.tfvars.example" +# "terraform/variables.tf" +# "terraform/versions.tf" +# ) + +############################################################################### +# ACTIVE CODE - UNCOMMENT BELOW TO ENABLE +# Remove the leading '# ' from each line to activate the script logic. +############################################################################### + +# --- Color Definitions --- +# RED='\033[0;31m' +# GREEN='\033[0;32m' +# YELLOW='\033[1;33m' +# BLUE='\033[0;34m' +# NC='\033[0m' # No Color + +# --- Safety Checks --- +# # Ensure we are at the top level of a git repository +# REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || { +# echo -e "${RED}Error: Not inside a git repository.${NC}" +# exit 1 +# } +# if [ "$(pwd)" != "$REPO_ROOT" ]; then +# echo -e "${RED}Error: Not at the repository root. Run from: $REPO_ROOT${NC}" +# exit 1 +# fi + +# --- Build Lookup Set from Expected Files --- +# # Abort if EXPECTED_FILES is unset or empty to prevent accidental deletion +# if [ ${#EXPECTED_FILES[@]} -eq 0 ]; then +# echo -e "${RED}Error: EXPECTED_FILES is empty or not uncommented.${NC}" +# echo -e "${RED}Uncomment the EXPECTED_FILES array in this script before running.${NC}" +# exit 1 +# fi +# +# # Create an associative array for O(1) lookups of expected files +# declare -A expected_set +# for file in "${EXPECTED_FILES[@]}"; do +# expected_set["$file"]=1 +# done + +# --- Discover All Current Files --- +# # Find all git-tracked and untracked (non-ignored) files +# mapfile -t current_files < <({ git ls-files; git ls-files --others --exclude-standard; } | sort -u) + +# --- Identify Leftover Files --- +# # Compare current files against the expected list to find leftovers +# leftover_files=() +# for file in "${current_files[@]}"; do +# if [[ -z "${expected_set[$file]+_}" ]]; then +# leftover_files+=("$file") +# fi +# done + +# --- Report Results --- +# # If no leftover files are found, exit cleanly +# if [ ${#leftover_files[@]} -eq 0 ]; then +# echo -e "${GREEN}No leftover files found. File structure matches expected layout.${NC}" +# exit 0 +# fi + +# # Display the leftover files that would be deleted +# echo -e "${YELLOW}The following ${#leftover_files[@]} file(s) do not match the expected repository structure:${NC}" +# echo "" +# for file in "${leftover_files[@]}"; do +# echo -e " ${RED}-${NC} $file" +# done +# echo "" + +# --- Dry Run / Confirmation --- +# # Prompt the user for confirmation before deleting +# echo -e "${BLUE}Would you like to delete these files? (y/N)${NC}" +# read -r confirmation +# if [[ "$confirmation" != "y" && "$confirmation" != "Y" ]]; then +# echo -e "${YELLOW}Aborted. No files were deleted.${NC}" +# exit 0 +# fi + +# --- Delete Leftover Files --- +# # Remove each leftover file and report progress +# deleted_count=0 +# for file in "${leftover_files[@]}"; do +# if rm -- "$file" 2>/dev/null; then +# echo -e " ${GREEN}Deleted:${NC} $file" +# deleted_count=$((deleted_count + 1)) +# else +# echo -e " ${RED}Failed to delete:${NC} $file" +# fi +# done + +# --- Clean Up Empty Directories --- +# # Remove any directories that are now empty after file deletion +# find . -path './.git' -prune -o -type d -empty -delete 2>/dev/null + +# --- Summary --- +# echo "" +# echo -e "${GREEN}Cleanup complete. Deleted $deleted_count of ${#leftover_files[@]} leftover file(s).${NC}" +# echo -e "${YELLOW}Tip: Run 'git status' to review the changes before committing.${NC}"