plain-forge 1.0.5 → 1.0.6

package/forge/rules/examples/integration-embedded-testing/prepare_environment_java.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if build folder name is provided
+if [ -z "$1" ]; then
+  printf "Error: No build folder name provided.\n"
+  printf "Usage: $0 <build_folder_name>\n"
+  exit 1
+fi
+
+JAVA_BUILD_SUBFOLDER=../../../
+
+if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+  printf "Copying generated code to main project folder: $JAVA_BUILD_SUBFOLDER\n"
+fi
+
+# Check if the main project folder exists
+if [ ! -d "$JAVA_BUILD_SUBFOLDER" ]; then
+  echo "Error: Main project folder '$JAVA_BUILD_SUBFOLDER' does not exist."
+  exit 2
+fi
+
+# clean existing code from the main project folder
+rm -rf $JAVA_BUILD_SUBFOLDER/<placeholder for integration code>/*
+rm -rf $JAVA_BUILD_SUBFOLDER/<placeholder for integration code tests>/*
+
+# copy generated code to the main project folder
+# FIX: added the mkdir lines otherwise it complains that the cp destintation directory does not exist
+mkdir -p $JAVA_BUILD_SUBFOLDER/<placeholder for integration code>
+mkdir -p $JAVA_BUILD_SUBFOLDER/<placeholder for integration code tests>
+cp -R $1/<placeholder for integration code>/* $JAVA_BUILD_SUBFOLDER/<<placeholder for integration code>
+cp -R $1/<placeholder for integration code tests>/* $JAVA_BUILD_SUBFOLDER/<placeholder for integration code tests>
+
+# Move to the subfolder
+echo "Moving to: $JAVA_BUILD_SUBFOLDER"
+cd "$JAVA_BUILD_SUBFOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java build folder '$JAVA_BUILD_SUBFOLDER' does not exist.\n"
+  exit 2
+fi
+
+# Remove target directory to avoid conflicts
+rm -rf ./target || echo "Warning: some files may be locked"
+
+echo "Runinng maven install in the build folder..."
+mvn clean install -Dspring-boot.repackage.skip=true -DskipTests

package/forge/rules/examples/integration-embedded-testing/run_conformance_tests_java.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if build folder name is provided
+if [ -z "$1" ]; then
+  printf "Error: No build folder name provided.\n"
+  printf "Usage: $0 <build_folder_name> <conformance_tests_folder>\n"
+  exit 1
+fi
+
+# Check if conformance tests folder name is provided
+if [ -z "$2" ]; then
+  printf "Error: No conformance tests folder name provided.\n"
+  printf "Usage: $0 <build_folder_name> <conformance_tests_folder>\n"
+  exit 1
+fi
+
+current_dir=$(pwd)
+
+CONFORMANCE_TESTS_FOLDER=".tmp/java_conformance"
+
+cd "$current_dir" 2>/dev/null
+
+printf "Preparing Java conformance tests subfolder: $CONFORMANCE_TESTS_FOLDER\n"
+
+# Check if the go build subfolder exists
+if [ -d "$CONFORMANCE_TESTS_FOLDER" ]; then
+  # Find and delete all files and folders
+  find "$CONFORMANCE_TESTS_FOLDER" -mindepth 1 -exec rm -rf {} +
+
+  if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+    printf "Cleanup completed.\n"
+  fi
+else
+  # print the current directory
+  printf "Current directory: $(pwd)\n"
+
+  printf "Subfolder does not exist. Creating it...\n"
+  mkdir -p $CONFORMANCE_TESTS_FOLDER
+fi
+
+printf "Copying all files and folders from $2 to $CONFORMANCE_TESTS_FOLDER...\n"
+cp -R $2/* $CONFORMANCE_TESTS_FOLDER
+
+# Move to the subfolder
+printf "Moving to $CONFORMANCE_TESTS_FOLDER...\n"
+cd "$CONFORMANCE_TESTS_FOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java conformance tests folder '$CONFORMANCE_TESTS_FOLDER' does not exist.\n"
+  exit 2
+fi
+
+echo "Running maven install in the conformance tests folder..."
+mvn clean install -DskipTests
+
+
+if [ $? -ne 0 ]; then
+  exit 2
+fi
+
+echo "Running maven test in the conformance tests folder..."
+
+output=$(mvn test --no-transfer-progress 2>&1)
+exit_code=$?
+
+echo "Finished running maven test in the conformance tests folder..."
+
+# Check if no tests were run
+if echo "$output" | grep -q 'Tests run: [1-9][0-9]*, Failures: 0, Errors: 0, Skipped: 0'; then
+    echo "All tests passed"
+    echo "$output"
+    exit $exit_code
+else
+    # Check if no tests were run
+    if echo "$output" | grep -q 'Tests run: 0, Failures: 0, Errors: 0, Skipped: 0'; then
+        echo "Tests run: 0"
+        echo "Error: No tests were executed (Tests run: 0)"
+        echo "You are seeing this cause the following appeared in the output: Tests run: 0, Failures: 0, Errors: 0, Skipped: 0"
+    else
+        echo "Some tests failed, had errors, or were skipped. This is not allowed. All tests must pass."
+    fi
+fi
+
+# If there was an error, print the output and exit with the error code
+if [ $exit_code -ne 0 ]; then
+    echo "Error: Maven test failed in the conformance tests folder with exit code $exit_code..."
+    echo "$output"
+    exit $exit_code
+fi
+
+echo "Finished running conformance tests..."
+echo "$output"
+# Echo the original exit code of the unittest command
+exit $exit_code

package/forge/rules/examples/integration-embedded-testing/run_unittests_java.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if subfolder name is provided
+if [ -z "$1" ]; then
+  echo "Error: No subfolder name provided."
+  echo "Usage: $0 <subfolder_name>"
+  exit 1
+fi
+# FIX: Changed this line from "../../" to "../../.." to go up three levels to the main project folder
+MAIN_PROJECT_FOLDER="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+  printf "Copying generated code to main project folder: $MAIN_PROJECT_FOLDER\n"
+fi
+
+# Check if the main project folder exists
+if [ ! -d "$MAIN_PROJECT_FOLDER" ]; then
+  echo "Error: Main project folder '$MAIN_PROJECT_FOLDER' does not exist."
+  exit 2
+fi
+
+# clean existing code from the main project folder
+rm -rf $MAIN_PROJECT_FOLDER/<placeholder for integration code>/*
+rm -rf $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>/*
+
+# copy generated code to the main project folder
+# FIX: added the mkdir lines otherwise it complains that the cp destintation directory does not exist
+mkdir -p $MAIN_PROJECT_FOLDER/<placeholder for integration code>
+mkdir -p $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>
+cp -R $1/<placeholder for integration code>/* $MAIN_PROJECT_FOLDER/<placeholder for integration code>
+cp -R $1/<placeholder for integration code tests>/* $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>
+
+# Move to the subfolder
+# FIX: added this line to print the current directory to help the LLM
+echo "Moving to: $MAIN_PROJECT_FOLDER"
+cd "$MAIN_PROJECT_FOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java build folder '$MAIN_PROJECT_FOLDER' does not exist.\n"
+  exit 2
+fi
+
+
+# Execute all Java unittests in the subfolder
+echo "Running Java unittests in $1..."
+mvn test -Dtest='<placeholder for integration code tests package>.**.*Test' checkstyle:check

package/forge/rules/integration-embedded-testing.md

@@ -0,0 +1,203 @@
+---
+description: Rules for authoring the three test scripts that an embedded ***plain integration ships
+globs: "**/*.plain"
+---
+
+# Rules for embedded-integration test scripts
+
+When an embedded integration ships its three `test_scripts/` (prepare-environment, unit, conformance) — whether you author them by hand or via the `implement-*-testing-script` skills — these rules apply on top of the shared testing-script rules in [PLAIN_REFERENCE.md](../docs/PLAIN_REFERENCE.md) (exit-code conventions, the activate-only vs install-inline conformance distinction, `VERBOSE=1`, etc.).
+
+## Staging model (read this first)
+
+The three scripts do **not** all stage into the same place. Embedded integrations need a runnable host project, so the prepare and unit-test scripts operate **inside the host codebase itself**; only the conformance script uses a `.tmp/` scratch folder because the conformance suite lives in a separate project.
+
+| Script | Where it operates | What it does to the host source tree |
+|--------|-------------------|---------------------------------------|
+| `prepare_environment_<lang>` | Inside the host codebase | Copies `$1` into the module's package path under the host's source tree, then compiles / installs the host project |
+| `run_unittests_<lang>` | Inside the host codebase | Same copy as above (self-contained), then runs the module's unit tests + lint inside the host |
+| `run_conformance_tests_<lang>` | `.tmp/<lang>_conformance/` | Copies `$2` (the conformance-tests folder) into the scratch directory and runs the conformance suite there, which depends on the host build that `prepare_environment` already installed |
+
+This deliberately writes into the host's `src/main/...` and `src/test/...` (or the language equivalent). Two consequences flow from that:
+
+- **The host codebase root must come from a configured env var** (`HOST_CODEBASE_ROOT` is the conventional name; declare it in the integration's configuration concept). Scripts never hardcode it
+- **The destructive-op scoping rule below becomes critical.** `rm -rf` must target only the module's own package path under the host's source tree, never the host's `src/main/`, `target/`, `node_modules/`, or `build/` at the project root
+
+This rule covers the **mechanics each script must obey** regardless of language: argument handling, exit codes, idempotency, path resolution, output parsing, and the "what NOT to put here" guard rails. The language-specific install / test commands come from the skills; the contract below is invariant.
+
+## What the `.plain` spec must declare in `***implementation reqs***`
+
+The three scripts are generated from facts in the integration's spec. For an embedded integration, those facts cannot be inferred — they have to be **declared explicitly** in `***implementation reqs***` so the renderer (and the `implement-*-testing-script` skills) can fill them into the three placeholders that every script body needs:
+
+1. **Integration source path inside the host** — where `$1/<source>/*` gets copied to. Example: `src/main/java/com/example/integrations/foo`
+2. **Integration test source path inside the host** — where `$1/<tests>/*` gets copied to, and where `:UnitTests:` are discovered. Example: `src/test/java/com/example/integrations/foo`
+3. **Test package for the test-filter argument** — the fully qualified package the test runner uses to scope discovery. Example: `com.example.integrations.foo`
+
+Author one `***implementation reqs***` entry per fact (use the `add-implementation-requirement` skill). Phrase each one in terms of `:UnitTests:` (the predefined concept) and the integration's other concepts, not as raw paths floating in the spec — that keeps the reqs reviewable and the renderer can resolve them when emitting scripts:
+
+```plain
+- :UnitTests: of :Implementation: live in `src/test/java/com/example/integrations/foo` inside the host codebase.
+  - The corresponding integration source code lives in `src/main/java/com/example/integrations/foo`.
+  - The fully qualified test package used for test discovery is `com.example.integrations.foo`.
+```
+
+These three facts feed directly into the script bodies:
+
+```bash
+# clean existing code from the host
+rm -rf $MAIN_PROJECT_FOLDER/<integration source path>/*
+rm -rf $MAIN_PROJECT_FOLDER/<integration test source path>/*
+
+# create destinations and copy generated code into the host
+mkdir -p $MAIN_PROJECT_FOLDER/<integration source path>
+mkdir -p $MAIN_PROJECT_FOLDER/<integration test source path>
+cp -R $1/<integration source path>/* $MAIN_PROJECT_FOLDER/<integration source path>
+cp -R $1/<integration test source path>/* $MAIN_PROJECT_FOLDER/<integration test source path>
+
+# run the unit tests scoped to the integration's package
+mvn test -Dtest='<test package>.**.*Test' checkstyle:check
+```
+
+Rules that flow from this:
+
+- **The three paths must agree.** The source path, the test-source path, and the test package describe the same module from three angles. A mismatch (e.g. test path `src/test/java/com/example/foo` but test package `com.example.bar`) silently produces a green build with stale or zero tests
+- **Paths are host-relative**, not absolute. `MAIN_PROJECT_FOLDER` comes from `HOST_CODEBASE_ROOT` (per the configuration concept); the paths above join onto it
+- **The renderer's output folder `$1` mirrors the same layout.** `$1/<integration source path>/*` exists because the renderer emits the generated code into the same package directories it'll be copied into — the `cp -R` is a straight overlay, not a path translation
+- **Each fact lives in one place.** If two `***implementation reqs***` entries declare slightly different test paths, the renderer can't tell which to use. Author the three reqs as a tight group (the example above is one bullet with two sub-bullets) so a future reviewer sees them together
+- **For non-Java languages**, the three facts have language-specific equivalents — Python: `src/foo/`, `tests/foo/`, `tests.foo`; Node: `src/foo/`, `test/foo/`, `test/foo/**/*.test.ts`. The `implement-*-testing-script` skills know the mapping per language, but the spec still has to declare the host-relative paths so the skill knows where to copy
+
+## Common contract (all three scripts)
+
+All three scripts are invoked by the `codeplain` renderer with positional arguments. They MUST:
+
+1. **Be POSIX-bash (`.sh`) on macOS / Linux, PowerShell (`.ps1`) on Windows.** Executable, idempotent — re-running with the same inputs produces the same result
+2. **Validate every positional argument up front.** Exit with a clear `Usage:` line on bad args. Conventional exit codes (consistent with the shared testing-script rules):
+   - `1` — bad arguments / usage error (and "no tests discovered" for the conformance runner)
+   - `2` — missing or inaccessible input folder
+   - `69` — unrecoverable environment failure (missing toolchain, cannot enter working folder, install failed)
+   - Any other non-zero code — propagated verbatim from the underlying build / test tool
+3. **Echo the toolchain home at the top** — the first thing a developer checks when CI breaks. For Java: `JAVA_HOME`. For Python: the active interpreter (`python --version` / `which python`). For Node: `node --version`. For Go: `go env GOROOT`. Pick the variable whose value most often explains "why does it work locally but not on the CI runner?"
+4. **Respect `VERBOSE=1`.** Gate chatty diagnostic prints behind `if [ "${VERBOSE:-}" = "1" ]` (and the PowerShell equivalent). Errors and key step markers print unconditionally
+5. **Resolve paths relative to the script, not `$PWD`.** Use `"$(cd "$(dirname "$0")/<relative-path-to-anchor>" && pwd)"`. Hard-coded `../../` chains break the moment the renderer's `cwd` changes
+6. **Create destination directories before copying.** `mkdir -p` before any `cp -R` / `rsync` / `robocopy` — most copy commands do not create intermediate directories and fail silently in some shells
+7. **Scope destructive operations narrowly.** Any `rm -rf` (or `Remove-Item -Recurse -Force`) targets only the module's own package path inside the working folder — never the host's `src/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root. Only `prepare_environment` owns the build-output directory's lifecycle for its `.tmp/` working folder
+8. **Print where you are before you `cd`.** `echo "Moving to: $DIR"` saves an hour of debugging when paths are wrong. PowerShell: `Write-Host "Moving to: $DIR"`
+
+## 1. `prepare_environment_<lang>` — copy into the host, then compile
+
+Receives one positional argument: the renderer's build output folder (e.g. `plain_modules/<module>/`).
+
+Purpose: stage the generated code **into the host codebase at the module's package path**, then run the host's install / build so that downstream test projects (specifically the conformance suite) can depend on it from the local dependency cache.
+
+Required steps:
+
+1. Validate `$1` (the renderer's output folder); fail with usage if missing
+2. Resolve the host codebase root from the env var declared in the `host-codebase` concept (`HOST_CODEBASE_ROOT` is the conventional name; surface it in `--help` / usage)
+3. `rm -rf` the module's package directories under the host's source tree — both main / source AND test directories. Both, because stale tests in the target package cause confusing failures
+4. `mkdir -p` the destination directories
+5. Copy `$1/src/...` (or the language-equivalent layout) into the host's source tree at the module's package path
+6. `cd` into the host codebase root, verify with an explicit exit-code check (`if [ $? -ne 0 ]` / `if (! $?) { ... }`)
+7. Clean the host's build-output directory before compiling — stale class / object files from a previous build cause confusing link-time mismatches when the contract has changed. Maven: `rm -rf ./target`. Cargo: `cargo clean -p <pkg>`. Go: `go clean -cache` (usually unnecessary, but mention if applicable). For npm projects with incremental builds disabled, wipe the relevant `dist/` / `build/` folder
+8. Run the host's standard install / build command — but **skip the fat-artifact and skip tests** when the build system supports it:
+   - Maven: `mvn clean install -DskipTests` (plus any host-specific repackage-skip flag)
+   - npm / pnpm / yarn: `npm ci` (no test script; dependency install only)
+   - Python: `pip install -e .` (then any extra integration dependencies)
+   - Go: `go mod tidy && go build ./...`
+   - Cargo: `cargo fetch && cargo build --tests --no-run`
+9. Exit `0` on success; propagate the underlying build tool's exit code on failure
+
+**Why this script exists separately.** Conformance tests live in a separate project and resolve the integration's code as a dependency from a local cache (`~/.m2`, `node_modules`, the language equivalent). Without an explicit install step, conformance tests link against whatever was last built — which may not be the renderer's most recent output.
+
+## 2. `run_unittests_<lang>` — copy into the host, then run unit tests there
+
+Receives one positional argument: the renderer's build output folder.
+
+Purpose: stage the generated code **into the host codebase** (the same way `prepare_environment` does) and run the module's unit tests + language-appropriate quality gates against the host project from inside the host root.
+
+Required steps:
+
+1. Validate `$1`
+2. Resolve the host codebase root from the configured env var
+3. `rm -rf` the module's main + test package directories under the host's source tree
+4. `mkdir -p` and copy `$1/src/...` into place — **same staging as `prepare_environment`**
+5. `cd` into the host codebase root
+6. Run the test command **scoped to the module's package only**:
+   - Maven: `mvn test -Dtest='<fully.qualified.package>.**.*Test' <lint-check>:check`
+   - pytest: `pytest tests/<module>/` (or whatever path matches the module)
+   - Jest: `npm test -- --testPathPattern '<module>/'`
+   - Go: `go test ./<module>/...`
+7. Always include the host's lint / static-analysis gate in the same invocation when the build system has one (Checkstyle, ESLint, Pylint / Ruff, `go vet`, `cargo clippy`, …). Running tests without the lint gate produces a false-green when style violations would otherwise block the build
+
+Hard rules:
+
+- **Yes, this duplicates `prepare_environment`'s copy step.** That's intentional — `run_unittests` must be self-contained per the shared testing-script rules (there is no activate-only variant for unit tests). A user invoking the unit-test script independently must not need `prepare_environment` to have run first
+- **Never use a "clean and test" shortcut** (`mvn clean test`, `npm run rebuild`, …) — the cleanup belongs in `prepare_environment` and would erase whatever it installed
+- **Never run the full test suite** when scoping is possible. A per-module script that runs the entire host's tests wastes minutes on every render iteration
+
+## 3. `run_conformance_tests_<lang>` — copy into `.tmp/`, then run the external suite
+
+Receives two positional arguments: the renderer's build output folder (`$1`) and the conformance-tests folder (`$2`).
+
+Purpose: run the conformance suite in `$2` against the build that `prepare_environment` produced. The conformance suite is a separate project that consumes the integration as a dependency.
+
+Required steps:
+
+1. Validate `$1` and `$2`. **Only `$2` is actually used by the script body today** — but keep `$1` in the signature; the renderer passes both positionally
+2. Stage `$2/*` into a scratch directory under `.tmp/<lang>_conformance/`. Wipe it first if it exists. Use a deletion form that handles hidden files and odd shells safely:
+   - Bash: `find "$DIR" -mindepth 1 -exec rm -rf {} +` (safer than `rm -rf "$DIR"/*`)
+   - PowerShell: `Remove-Item -Recurse -Force "$DIR\*"` after confirming the path exists
+3. `cd` into the scratch directory
+4. Compile / set up the conformance project — exit early if this fails:
+   - Maven: `mvn clean install -DskipTests`
+   - npm: `npm ci`
+   - Python: `pip install -r requirements.txt`
+   - Go / Cargo: standard build
+5. Run the conformance test command and **capture stdout to a variable**:
+   - Bash: `output=$(mvn test --no-transfer-progress 2>&1)` (or the language equivalent)
+   - PowerShell: `$output = & <cmd> 2>&1 | Out-String`
+6. **Parse the captured output strictly** (see *Pass criteria* below) — don't trust the test tool's exit code alone
+7. On the failure path: print the captured output unconditionally so the renderer (and the user) can see what failed
+8. On the success path: print the output only if `VERBOSE=1`
+
+### Pass criteria (strict)
+
+These are the **only** valid pass criteria. Anything outside this list is a failure:
+
+- At least one test ran AND zero failures AND zero errors AND zero skipped. Maven example: `Tests run: [1-9][0-9]*, Failures: 0, Errors: 0, Skipped: 0`. Each language's test runner has an equivalent summary line — match it with a regex, not by substring
+- Exit with the test tool's exit code on the success path (almost always `0`)
+
+Failure cases — each must be detected explicitly:
+
+- `Tests run: 0` (or the language equivalent) → **failure**. The renderer must never be told "green" when nothing ran. Exit `1` per the shared testing-script rules (the "no tests discovered" exit code)
+- Any non-zero `Failures:`, `Errors:`, or `Skipped:` count → **failure**. Dump the captured output and propagate the test tool's exit code
+- The test tool exited non-zero but the summary line shows `Tests run: 0` → still a `1` (no-tests-discovered), not the tool's own exit code
+
+**Why parse stdout instead of trusting the test tool's exit code.** Every major test runner returns `0` when zero test classes match a filter. Maven Surefire, pytest with no collected tests, `go test ./pkg/that/has/no/_test.go/files`, Jest with an empty pattern — all green-by-default. The renderer's contract is "tests must run AND must pass" — the exit code alone cannot express that.
+
+## Cross-cutting rules
+
+- **No secrets in scripts.** Read credentials from env vars the renderer (or the user's shell) already sets. If a required env var is missing, fail fast with a clear `Error: $FOO is required for ...` and exit `69`. Never hardcode an API key, never read from a checked-in file
+- **Mirror the package / module path exactly.** A typo in the package segment (e.g. one wrong directory in `com/example/foo/...` or `host_pkg/foo/bar/...`) makes `rm -rf` silently do nothing and the subsequent copy put files in the wrong place. Both produce a **green** build with stale code. Derive the package path from the `host-codebase` concept; never retype it inline
+- **Don't add cleverness to the script that belongs in the build.** If you're tempted to `grep` the test output for more than the pass/fail summary, change the test or the test-runner config instead. The script is a thin contract — keep it that way
+- **Don't use shortcut profiles that skip quality gates.** Maven's `-Pfast`, Gradle's `-x check`, npm's `--ignore-scripts`, pytest's `--no-cov`, `-DskipTests` outside `prepare_environment` — all defeat the purpose of these scripts. The build's full quality gate (tests + lint + coverage thresholds) must run for unit and conformance
+- **Failure messages are for humans.** `printf "Error: <what failed> at <where>\n"` then exit with the right code. No silent failures, no `|| true` to paper over errors, no `2>/dev/null` on commands whose stderr matters
+- **Use existing scripts as templates.** When you add a new embedded integration, copy from a known-good module, then search-and-replace only the package path and the test-filter argument. Resist the urge to "improve" structure mid-port — pattern-matching across many modules is a feature, not a bug
+
+## Reference implementation (Java + Maven)
+
+A working three-script set for a Java / Maven embedded integration lives under [`examples/integration-embedded-testing/`](examples/integration-embedded-testing/) next to this file:
+
+- [`prepare_environment_java.sh`](examples/integration-embedded-testing/prepare_environment_java.sh) — copies `$1` into the host's source tree, cleans `target/`, runs `mvn clean install -DskipTests`
+- [`run_unittests_java.sh`](examples/integration-embedded-testing/run_unittests_java.sh) — re-stages into the host and runs `mvn test -Dtest='<module-pkg>.**.*Test' checkstyle:check`
+- [`run_conformance_tests_java.sh`](examples/integration-embedded-testing/run_conformance_tests_java.sh) — copies `$2` into `.tmp/java_conformance/`, builds the conformance project, runs the suite, and parses the Surefire summary line per the strict pass criteria above
+
+Use them as a template when adding a new embedded integration in Java / Maven — copy, search-and-replace only the package segment and the `-Dtest` filter, then wire into `config.yaml`. For other languages (Python, Node.js, Go, Rust, …), the `implement-*-testing-script` skills generate the equivalent three-script set following the same contract.
+
+## Adding a script for a new module
+
+1. Copy the three scripts from a working embedded-integration module into the new module's directory
+2. Search-and-replace the package segment everywhere it appears — including the test-filter argument (the most commonly missed spot)
+3. `chmod +x` all three (and verify ACLs on Windows for the `.ps1` siblings)
+4. Wire them into the module's `config.yaml` via the `unittests-script`, `conformance-tests-script`, and `prepare-environment-script` keys. Use `init-config-file` to assemble the canonical form
+5. Smoke-test by running each script manually with the renderer's output folder as `$1` (and the conformance-tests folder as `$2` for the conformance runner). Confirm exit codes match what the renderer expects
+
+For non-Java languages, the plain-forge skills [`implement-prepare-environment-script`](../skills/implement-prepare-environment-script/SKILL.md), [`implement-unit-testing-script`](../skills/implement-unit-testing-script/SKILL.md), and [`implement-conformance-testing-script`](../skills/implement-conformance-testing-script/SKILL.md) adapt the contract above to Python, Node.js, Go, Rust, Flutter, and others. Always route script creation through these skills so the cross-cutting rules above are applied uniformly.

package/forge/rules/integration-embedded.md

@@ -16,6 +16,29 @@ Embedded means: the host codebase already exists, has its own language / framewo
 - If a Phase 3 (`forge-plain`) tech-stack question seems to push back on a host rule, treat the host as ground truth and rewrite the question
 - Implementation reqs added in Phase 3 are **transcribed** from the host stack verbatim — host language and exact version, host framework + version, dependency manager and manifest path, packaging layout, host conventions the contract must follow, and every host-package version the contract pins
 
+## Project layout — the integration lives under `plain/` at the host root
+
+The embedded integration's `.plain` specs (and the rest of the ***plain project — `template/`, `resources/`, `test_scripts/`, `config.yaml`, generated `plain_modules/`) live in a single top-level `plain/` folder at the host repository root, alongside the host's own source tree:
+
+```
+<host repo>/
+├── docs/
+├── plain/          # ← the embedded ***plain integration lives here
+│   ├── <module>.plain
+│   ├── template/
+│   ├── resources/
+│   ├── test_scripts/
+│   ├── plain_modules/     # generated; gitignored
+│   └── config.yaml
+└── src/            # host source tree (Java, Python, etc.)
+```
+
+This keeps the integration self-contained in one directory the user can `cd` into to render, while leaving the host's own source layout untouched.
+
+- If the host **already** has a `plain/` directory, adopt it verbatim — see step 1 of *Discover before you ask* below
+- If the host does **not** yet have one, create `plain/` at the repo root; do not invent a different name (`specs/`, `plain_specs/`, …)
+- The three test scripts still `cd` into `$HOST_CODEBASE_ROOT` (the host repo root) to compile and run tests against the host project; the `plain/` folder is the integration's **authoring** root, not its **runtime** root
+
 ## Discover before you ask
 
 Run host discovery **before** the first Phase 1 question. Treat the results as ground truth for everything that follows.
@@ -91,47 +114,25 @@ The renderer reads the directives from the spec and the shapes from the linked s
 - If two reqs are in tension (one from the host, one newly authored), the host wins; rewrite or drop the newly authored req
 - Do not author a req that re-declares something the host already enforces — that's a maintenance burden with no benefit
 
-## Test-script wiring — merge `plain_modules` into the host, run tests there
+## Test-script wiring — copy into the host, run tests there
 
-Embedded integrations are tested **inside a working copy of the host codebase** with the generated `plain_modules/` overlaid on top. Both `run_unittests_<lang>` and `run_conformance_tests_<lang>` follow this pattern — neither uses `PYTHONPATH` / `NODE_PATH` tricks to stitch two trees together at import time. The host *is* the runtime environment; the generated module is dropped into it and exercised as if it had always lived there.
+Embedded integrations are tested **inside the host codebase itself**. The prepare and unit-test scripts copy the renderer's output (`$1`, i.e. `plain_modules/<module>/`) into the host's source tree at the module's package path, then compile / test the host project in place. Only the conformance script uses a `.tmp/` scratch folder, because the conformance suite is a separate project that consumes the host build as a dependency.
 
 This matters because the integration's generated code references host symbols by their full import path (e.g. `from host_project.integrations.base import IntegrationContract`). Those imports only resolve cleanly when the test process is rooted in the host's package layout — anything else creates path edge cases that bite later in conformance failures.
 
-### The merge step (used by both `prepare_environment` and `run_unittests`)
-
-Both scripts stage their own working copy under `.tmp/<lang>_<arg>/` per the shared testing-script rules (input folders are read-only). Inside that working folder:
-
-1. **Copy the host codebase into the working folder.** Use a recursive copy (`rsync -a --delete`, `cp -R`, or `robocopy`) so each test run starts from a clean, identical host tree
-2. **Overlay `plain_modules/<module>/` into the host's package tree at the target package path** recorded in the `host-codebase` concept (e.g. `plain_modules/integrations/<provider>/` → `<host_copy>/host_project/integrations/<provider>/`). Use a copy that overwrites — the generated module replaces any same-named files in the host copy
-3. **Install dependencies inside the merged tree.** The host's own manifest (`pyproject.toml` / `package.json` / `go.mod` / …) drives the install. The integration's extra dependencies are layered on top by either (a) the renderer having written them into the host's manifest already, or (b) the script installing them explicitly after the host install
-4. **Run the test command from inside the merged tree** — `cwd` is `<host_copy>`, and the test runner discovers tests using the host's normal layout
-
-### Per-script responsibilities
-
-- **`prepare_environment_<lang>`** performs the full merge once per render (host copy + plain_modules overlay + dependency install + any build artifacts) into `.tmp/<lang>_<arg>/`. The N subsequent `run_conformance_tests_<lang>` invocations attach to this populated folder (activate-only variant — see the shared testing-script rules)
-- **`run_unittests_<lang>`** performs its **own** merge into its **own** `.tmp/<lang>_<arg>/` working folder — it does not share `prepare`'s folder, and it does not depend on `prepare` having run. The host copy + overlay + install steps are duplicated inside the unit-test script for self-containedness
-- **`run_conformance_tests_<lang>`** does **not** re-merge. It `cd`s into the working folder that `prepare_environment` populated and runs the conformance command against the merged tree
-
-### Language-specific merge primitives
-
-| Language | Host copy | Overlay | Dependency install | Test invocation (inside merged tree) |
-|----------|-----------|---------|--------------------|--------------------------------------|
-| Python | `rsync -a <host>/ .tmp/python_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/python_<arg>/<host_pkg_path>/` | `cd .tmp/python_<arg> && pip install -e .` (then integration extras) | `cd .tmp/python_<arg> && pytest …` |
-| Node.js | `rsync -a <host>/ .tmp/node_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/node_<arg>/<host_pkg_path>/` | `cd .tmp/node_<arg> && npm ci` (then integration extras) | `cd .tmp/node_<arg> && npm test …` |
-| Go | `rsync -a <host>/ .tmp/go_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/go_<arg>/<host_pkg_path>/` | `cd .tmp/go_<arg> && go mod tidy` | `cd .tmp/go_<arg> && go test ./…` |
-| Java / Kotlin | `rsync -a <host>/ .tmp/java_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/java_<arg>/<host_pkg_path>/` | `cd .tmp/java_<arg> && mvn -q -DskipTests install` | `cd .tmp/java_<arg> && mvn test …` |
-| Rust | `rsync -a <host>/ .tmp/rust_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/rust_<arg>/<host_pkg_path>/` | `cd .tmp/rust_<arg> && cargo fetch` | `cd .tmp/rust_<arg> && cargo test …` |
+See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the full per-script contract (arg validation, exit codes, idempotency, output parsing, pass criteria, cross-cutting rules). The summary that belongs in *this* file:
 
-Adjust the language-specific install / test commands to whatever the host's manifest actually uses (Poetry instead of pip, pnpm instead of npm, Gradle instead of Maven, …). The merge primitive itself does not change.
+- **`prepare_environment_<lang>`** copies `$1` into the host's source tree at the module's package path, cleans the host's build-output directory, then runs the host's install / build (e.g. `mvn clean install -DskipTests`). The conformance suite later resolves the integration from the host's local dependency cache
+- **`run_unittests_<lang>`** repeats the same copy into the host (self-contained — must work without `prepare_environment` having run first), then runs the module's unit tests + lint scoped to the module's package
+- **`run_conformance_tests_<lang>`** copies `$2` (the conformance-tests folder) into `.tmp/<lang>_conformance/`, `cd`s in, builds the conformance project, and runs it against the build that `prepare_environment` already installed into the host
 
 ### Invariants the scripts must enforce
 
 - **Host root is a parameter, not a literal.** No script may hardcode an absolute host path. Read the host root from an env var (e.g. `HOST_CODEBASE_ROOT`) with a sensible default matching the user's layout (e.g. `../host_project`). Surface the env var in each script's `--help` / usage banner. Capture this env var in the integration's configuration concept so it has exactly one declared name across specs, scripts, and runtime
-- **Target package path is read from the `host-codebase` concept** — never inferred from a heuristic. The renderer writes that path into the generated module's location too, so the overlay destination is unambiguous
-- **The host source tree is read-only.** The merge writes into `.tmp/<lang>_<arg>/`; the user's `<host>` checkout is never modified. If a script appears to need to write into `<host>`, it is buggy — the working copy under `.tmp/` is what's mutable
-- **Each merge is idempotent.** Re-running the script (or two scripts back-to-back) yields the same merged tree
-- **No new `config.yaml` key is needed** — the merge happens inside the scripts. The renderer reads the `host-codebase` concept (for the package path) and the configuration concept (for `HOST_CODEBASE_ROOT`) to wire the script bodies correctly
-- **`***test reqs***` must document the merge contract** — name the merge primitive (`rsync` / `cp -R` / `robocopy`), the env var the host root is read from, the target package path inside the host where `plain_modules/<module>/` is overlaid, and the language-appropriate install + test commands. The renderer reads this req and emits the right script bodies
+- **Target package path is read from the `host-codebase` concept** — never inferred from a heuristic. The renderer writes that path into the generated module's location too, so the copy destination is unambiguous
+- **Destructive ops are scoped to the module's own package path** under the host's source tree. `rm -rf` never touches the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root. Only the module-specific package directories are wiped
+- **Each script is idempotent.** Re-running the same script with the same `$1` yields the same result
+- **`***test reqs***` must document the script contract** — name the env var the host root is read from, the target package path inside the host where `$1` is copied, and the language-appropriate install + test commands. The renderer reads this req and emits the right script bodies
 
 ## Embedded-specific completion checklist
 
@@ -143,13 +144,13 @@ Before declaring an embedded integration done, in addition to the shared checkli
 - [ ] Every host file the integration touches is linked at its **original host-relative path** — no host file has been copied into `resources/host/` or anywhere else, and no host file contents are inlined in any spec
 - [ ] `forge-plain` Phase 2's tech-stack decisions are transcribed verbatim from the host (no independent stack choices)
 - [ ] Host-package version pins are copied into `***implementation reqs***`
-- [ ] `prepare_environment` copies the host into `.tmp/<lang>_<arg>/`, overlays `plain_modules/<module>/` at the target package path, installs the merged tree's dependencies, and is the working folder conformance attaches to
-- [ ] `run_unittests` runs the same host-copy + overlay + install sequence into its **own** `.tmp/<lang>_<arg>/` and invokes the test runner from inside the merged tree
-- [ ] `run_conformance_tests` `cd`s into `prepare_environment`'s populated working folder and runs the conformance command from there — it does not re-merge and does not use import-path stitching
+- [ ] `prepare_environment` copies `$1` into the host's source tree at the module's package path, cleans the host's build-output directory, and runs the host's install / build so the conformance suite can resolve the integration from the local dependency cache
+- [ ] `run_unittests` runs the same copy-into-host sequence (self-contained — does not depend on `prepare_environment` having run) and invokes the host's test runner scoped to the module's package
+- [ ] `run_conformance_tests` copies `$2` into `.tmp/<lang>_conformance/`, `cd`s in, builds the conformance project, and runs it against the host build that `prepare_environment` already installed
 - [ ] Host codebase root is read from a named env var (default value documented in each script's usage) — never hardcoded
-- [ ] Target package path (where `plain_modules/<module>/` is overlaid inside the host copy) is read from the `host-codebase` concept — never inferred
-- [ ] The host source tree itself is never written to — every script mutation lands in `.tmp/<lang>_<arg>/`
-- [ ] A `***test reqs***` entry documents the merge contract (primitive used, env var name, target package path inside the host, install + test commands)
+- [ ] Target package path inside the host where `$1` is copied is read from the `host-codebase` concept — never inferred
+- [ ] Every `rm -rf` in the scripts is scoped to the module's own package directory under the host's source tree — never targets the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root
+- [ ] A `***test reqs***` entry documents the script contract (env var name, target package path inside the host, install + test commands)
 
 ## Anti-patterns specific to embedded integrations
 
@@ -160,6 +161,6 @@ Before declaring an embedded integration done, in addition to the shared checkli
 - **Hardcoding the host codebase path in any spec or script.** Read it from the env var declared in the configuration concept
 - **Asking the user to design the integration's tech stack.** Read it from the host's manifest files
 - **Authoring an integration spec that contradicts an existing integration in the same host** without first surfacing the conflict and getting explicit user confirmation
-- **Wiring tests with `PYTHONPATH` / `NODE_PATH` / Go `replace` directives instead of physically merging `plain_modules/<module>/` into a host copy.** The import-stitching approach is forbidden — every embedded test run starts by overlaying the generated module onto a working copy of the host tree
-- **Writing into the user's `<host>` checkout from any test script.** The host source is read-only; the merged tree lives in `.tmp/<lang>_<arg>/`
-- **Sharing one `.tmp/` working folder between `run_unittests` and `run_conformance_tests`.** Each script stages its own copy; only `run_conformance_tests` attaches to the folder `prepare_environment` populated
+- **Wiring tests with `PYTHONPATH` / `NODE_PATH` / Go `replace` directives instead of physically copying `$1` into the host's package tree.** The import-stitching approach is forbidden — every prepare / unit test starts by copying the generated module into the host's source tree at the module's package path
+- **Letting an `rm -rf` in a test script reach the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root.** Destructive ops are scoped strictly to the module's own package directory. A wrong package path in the script silently does nothing and copies files in the wrong place — both produce a green build with stale code
+- **Running conformance tests against a stale local dependency cache.** `prepare_environment` must run before conformance for the conformance project to resolve the integration from `~/.m2` (or the language equivalent). If conformance gets invoked without a fresh prepare, dependent on which build last hit the cache, the suite tests the wrong code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {