Move dope.sh to top level (#531)

Author: infomiho

.gitignore

@@ -1,7 +1,7 @@
 # Dependencies
 node_modules/
 
-# MacOS-specific files.
+# macOS-specific files.
 .DS_Store
 
 # We want to keep the template clean from the usual build artifacts.

README.md

@@ -73,6 +73,10 @@ There are two ways to get help or provide feedback (and we try to always respond
 1. [Open an issue](https://github.com/wasp-lang/open-saas/issues)
 2. [Wasp Discord](https://discord.gg/aCamt5wCpS) -- please direct questions to the #🙋questions forum channel
 
+## Development Tools
+
+For information about the development tools used to maintain derived projects (like opensaas.sh), see [tools/README.md](./tools/README.md).
+
 ## Contributing
 
 Note that we've tried to get as many of the core features of a SaaS app into this template as possible, but there still might be some missing features or functionality.

opensaas-sh/README.md

@@ -12,25 +12,12 @@ Inception :)!
 
 Since the demo app is just the open saas template with some small tweaks, and we want to be able to easily keep it up to date as the template changes, we don't version (in git) the actual demo app code, instead we version the diffs between it and the template: `app_diff/`.
 
-So because we don't version the actual demo app (`app/`) but its diffs instead (`app_diff`), the typical workflow is as follows:
+**Quick Reference:**
 
-1. Run `./tools/patch.sh` to generate `app/` from `../template/` and `app_diff/`.
-2. If there are any conflicts (normally due to updates to the template), modify `app/` till you resolve them. Do any additional changes also if you wish.
-3. Generate new `app_diff/`, based on the current updated `app/`, by running `./tools/diff.sh`.
+- Generate `app/` from template and diffs: `./tools/patch.sh`
+- Update diffs after modifying `app/`: `./tools/diff.sh`
 
-**Running on MacOS**
-
-If you're running the `patch.sh` or `diff.sh` scripts on Mac, you need to install:
-
-- `grealpath` (packaged within `coreutils`),
-- `gpatch`,
-- and `diffutils`.
-
-```sh
-brew install coreutils # contains grealpath
-brew install gpatch
-brew install diffutils
-```
+For detailed information about the diff/patch workflow and macOS setup requirements, see [../tools/README.md](../tools/README.md).
 
 ### Blog (blog/)
 

opensaas-sh/tools/diff.sh

@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
 
-TOOLS_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `tools/`.
-cd "${TOOLS_DIR}" && cd ../..
+SCRIPT_DIR=$(dirname "$(realpath "$0")")
+# Assumes this script is in `opensaas-sh/tools/`.
+ROOT_DIR="${SCRIPT_DIR}/../.."
+
+cd "${ROOT_DIR}"
 
 rm -rf opensaas-sh/app_diff
-"${TOOLS_DIR}/dope.sh" template/app opensaas-sh/app diff
+"${ROOT_DIR}/tools/dope.sh" template/app opensaas-sh/app diff

opensaas-sh/tools/patch.sh

@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
 
-TOOLS_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `tools/`.
-cd "${TOOLS_DIR}" && cd ../..
+SCRIPT_DIR=$(dirname "$(realpath "$0")")
+# Assumes this script is in `opensaas-sh/tools/`.
+ROOT_DIR="${SCRIPT_DIR}/../.."
+
+cd "${ROOT_DIR}"
 
 # Removes all files except for some gitignored files that we don't want to bother regenerating each time,
 # like node_modules and certain .env files.
 find opensaas-sh/app -mindepth 1 \( -path node_modules -o -name .env.server -o -name .env.me \) -prune -o -exec rm -rf {} +
-"${TOOLS_DIR}/dope.sh" template/app opensaas-sh/app patch
+"${ROOT_DIR}/tools/dope.sh" template/app opensaas-sh/app patch

template/.gitignore

@@ -1,4 +1,4 @@
-# MacOS-specific files.
+# macOS-specific files.
 .DS_Store
 
 # Ignore all dotenv files by default to prevent accidentally committing any secrets.

tools/README.md

@@ -0,0 +1,66 @@
+# Open SaaS Tools
+
+## dope.sh - Diff Or Patch Executor
+
+The `dope.sh` script allows you to easily create a diff between two projects (base and derived),
+or to patch those diffs onto the base project to get the derived one. This is useful when a derived
+project has only small changes on top of the base project and you want to keep it in a directory
+in the same repo as the main project.
+
+Since derived apps (like opensaas-sh) are just the Open SaaS template with some small tweaks, and
+we want to keep them up to date as the template changes, we don't version the actual app code in git.
+Instead, we version the diffs between it and the template in an `app_diff/` directory.
+
+### Usage
+
+```bash
+./dope.sh <BASE_DIR> <DERIVED_DIR> <ACTION>
+```
+
+- `<BASE_DIR>`: The base project directory (e.g., `../template/`)
+- `<DERIVED_DIR>`: The derived project directory (e.g., `app/`)
+- `<ACTION>`: Either `diff` or `patch`
+  - `diff`: Creates a diff between the base and derived directories
+  - `patch`: Applies existing diffs onto the base directory to recreate the derived directory
+
+The diffs are stored in a directory named `<DERIVED_DIR>_diff/` (e.g., `app_diff/`).
+
+### Diff structure
+
+The diff directory can contain `.diff` files to patch files from the base directory,
+and `.copy` files to copy files directly from the diff directory to the derived directory
+(useful for binary files).
+
+### Workflow
+
+The typical workflow is:
+
+1. Run `dope.sh` with the `patch` action to generate `app/` from `../template/` and `app_diff/`:
+   ```bash
+   ./dope.sh ../template app patch
+   ```
+
+2. If there are any conflicts (usually due to updates to the template), modify `app/` until you resolve them. Make any additional changes as needed.
+
+3. Generate a new `app_diff/` based on the updated `app/` by running:
+   ```bash
+   ./dope.sh ../template app diff
+   ```
+
+### Requirements
+
+#### Running on macOS
+
+If you're running the `dope.sh` script on macOS, install:
+
+- `grealpath` (packaged within `coreutils`)
+- `gpatch`
+- `diffutils`
+
+```sh
+brew install coreutils  # contains grealpath
+brew install gpatch
+brew install diffutils
+```
+
+The script automatically detects macOS and uses `gpatch` instead of the default `patch` command.

opensaas-sh/tools/dope.sh renamed to tools/dope.sh

@@ -12,7 +12,7 @@ if [[ "$(uname)" == "Darwin" ]]; then
   if command -v gpatch &> /dev/null; then
     PATCH_CMD="gpatch"
   else
-    echo "Error: GNU patch (gpatch) not found. On MacOS, this script requires GNU patch."
+    echo "Error: GNU patch (gpatch) not found. On macOS, this script requires GNU patch."
     echo "Install it with: brew install gpatch"
     exit 1
   fi