Move dope.sh to top level

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,9 @@
 #!/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,11 @@
 #!/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

tools/README.md

@@ -0,0 +1,53 @@
+# Open SaaS Tools
+
+This directory contains utilities for managing derived projects that are built on top of the Open SaaS template.
+
+## 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.
+
+### 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
+
+### Workflow
+
+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.
+
+The typical workflow is:
+
+1. Run `dope.sh` with `patch` action to generate `app/` from `../template/` and `app_diff/`:
+   ```bash
+   ./dope.sh ../template app patch
+   ```
+
+2. If there are any conflicts (normally due to updates to the template), modify `app/` until you resolve them. Make any additional changes as needed.
+
+3. Generate new `app_diff/` based on the current updated `app/` by running:
+   ```bash
+   ./dope.sh ../template app diff
+   ```
+
+### Running on MacOS
+
+If you're running the `dope.sh` script on Mac, you need to install:
+
+- `grealpath` (packaged within `coreutils`)
+- `gpatch`
+- `diffutils`
+
+```sh
+brew install coreutils  # contains grealpath
+brew install gpatch
+brew install diffutils
+```
+
+The script will automatically detect macOS and use `gpatch` instead of the default `patch` command.