Merge pull request #555 from JohT/feature/introduce-neo4j-management-domain

Introduce neo4j management domain

Author: JohT

.github/prompts/plan-neo4jManagementDomain.prompt.md

@@ -0,0 +1,116 @@
+# Plan: Introduce neo4j-management Domain
+
+Create `domains/neo4j-management/` containing all scripts, configs, and tests for installing, configuring, starting, and stopping Neo4j. Move 15 files (10 shell scripts + 5 configuration templates) into the domain. Keep profiles in `scripts/profiles/` and jQAssistant YAML templates in `scripts/configuration/`. Update all references. Create a README with agent-friendly examples.
+
+---
+
+### Phase 1 — Create Domain Structure & Move Files
+
+1. Create `domains/neo4j-management/` with a `configuration/` subdirectory
+2. Move **10 shell scripts** from `scripts/` → `domains/neo4j-management/`:
+   - [setupNeo4j.sh](domains/neo4j-management/setupNeo4j.sh), [setupNeo4jInitialPassword.sh](domains/neo4j-management/setupNeo4jInitialPassword.sh), [configureNeo4j.sh](domains/neo4j-management/configureNeo4j.sh) *(pre-move locations: `scripts/setupNeo4j.sh`, `scripts/setupNeo4jInitialPassword.sh`, `scripts/configureNeo4j.sh`)*
+   - [startNeo4j.sh](domains/neo4j-management/startNeo4j.sh), [stopNeo4j.sh](domains/neo4j-management/stopNeo4j.sh) *(pre-move locations: `scripts/startNeo4j.sh`, `scripts/stopNeo4j.sh`)*
+   - [detectNeo4j.sh](domains/neo4j-management/detectNeo4j.sh), [detectNeo4jWindows.sh](domains/neo4j-management/detectNeo4jWindows.sh) *(pre-move locations: `scripts/detectNeo4j.sh`, `scripts/detectNeo4jWindows.sh`)*
+   - [waitForNeo4jHttpFunctions.sh](domains/neo4j-management/waitForNeo4jHttpFunctions.sh), [useNeo4jHighMemoryProfile.sh](domains/neo4j-management/useNeo4jHighMemoryProfile.sh) *(pre-move locations: `scripts/waitForNeo4jHttpFunctions.sh`, `scripts/useNeo4jHighMemoryProfile.sh`)*
+   - [testConfigureNeo4j.sh](domains/neo4j-management/testConfigureNeo4j.sh) *(pre-move location: `scripts/testConfigureNeo4j.sh`)*
+3a. Replace the pre-move scripts `scripts/startNeo4j.sh` and `scripts/stopNeo4j.sh` with **minimal redirect stubs** that forward to [domains/neo4j-management/startNeo4j.sh](domains/neo4j-management/startNeo4j.sh) and [domains/neo4j-management/stopNeo4j.sh](domains/neo4j-management/stopNeo4j.sh) for backward compatibility with existing projects that have forwarding scripts pointing to the old location. The stubs must not be referenced by any new code; they exist solely to avoid breaking old workspaces. Each stub contains only:
+   ```bash
+   #!/usr/bin/env bash
+   # Deprecated: moved to domains/neo4j-management/. This stub exists for backward compatibility only.
+   source "$(dirname -- "${BASH_SOURCE[0]}")/../domains/neo4j-management/$(basename -- "${BASH_SOURCE[0]}")" "${@}"
+   ```
+3. Move **5 neo4j.conf templates** from `scripts/configuration/` → `domains/neo4j-management/configuration/`:
+   - `template-neo4j.conf`, `template-neo4j-high-memory.conf`, `template-neo4j-low-memory.conf`, `template-neo4j-v4.conf`, `template-neo4j-v4-low-memory.conf`
+
+### Phase 2 — Update Internal References (within moved scripts)
+
+4. Add `NEO4J_MANAGEMENT_DIR` resolution to each moved script (same pattern as `DOMAIN_SCRIPT_DIR` in other domains), keeping a `SCRIPTS_DIR` fallback for shared utilities like `download.sh` and `operatingSystemFunctions.sh`
+5. Update `configureNeo4j.sh` — resolve config templates from `domains/neo4j-management/configuration/` instead of `scripts/configuration/`
+6. Update `setupNeo4j.sh` — source `configureNeo4j.sh` and `setupNeo4jInitialPassword.sh` from co-located directory
+7. Update the moved `startNeo4j.sh` and `stopNeo4j.sh` in the domain — source `waitForNeo4jHttpFunctions.sh` from the co-located directory
+8. Update `useNeo4jHighMemoryProfile.sh` — source `configureNeo4j.sh` from co-located directory
+9. Update `testConfigureNeo4j.sh` — source `configureNeo4j.sh` from co-located directory
+
+### Phase 3 — Update External Callers
+
+10. Update [scripts/analysis/analyze.sh](scripts/analysis/analyze.sh) — source `setupNeo4j.sh`, `startNeo4j.sh`, `stopNeo4j.sh` from `${DOMAINS_DIRECTORY}/neo4j-management/` (already resolves `DOMAINS_DIRECTORY`) *(critical path)*
+11. Update [init.sh](init.sh) — change forwarding script paths for `startNeo4j.sh` and `stopNeo4j.sh` from `./../../scripts/` to `./../../domains/neo4j-management/`. The redirect stubs in `scripts/` ensure old workspaces (where `init.sh` was already run before this change) still work without any manual migration.
+12. Check [scripts/resetAndScan.sh](scripts/resetAndScan.sh) — references `template-neo4j` for jQAssistant YAML path resolution; verify this is about jQAssistant templates (which stay) not neo4j.conf templates
+
+### Phase 4 — Update Documentation
+
+13. Update [COMMANDS.md](COMMANDS.md) — fix links to `setupNeo4j.sh`, `configureNeo4j.sh`, `stopNeo4j.sh`, `useNeo4jHighMemoryProfile.sh`, and configuration template references
+14. Update [README.md](README.md) — fix `useNeo4jHighMemoryProfile.sh` usage examples (lines ~304–307)
+15. Update [.github/prompts/plan-coding_agent_instructions.prompt.md](.github/prompts/plan-coding_agent_instructions.prompt.md) — fix `startNeo4j.sh` reference
+16. Do not change [SCRIPTS.md](SCRIPTS.md) its will be regenerated via `generateScriptReference.sh`
+17. Add [CHANGELOG.md](CHANGELOG.md) entry for the domain creation
+
+### Phase 5 — Verify Renovate Patterns
+
+18. Verify [renovate.json](renovate.json) — 5 regex managers use `^scripts/profiles/Neo4j-latest.*\\.sh$` and `^scripts/[^/]*\\.sh$`. Since profiles stay in `scripts/profiles/`, no changes needed unless moved scripts contain `NEO4J_VERSION:-` defaults (unlikely — those are in profiles). *Parallel with Phase 4.*
+
+### Phase 6 — Create README.md
+
+19. Create `domains/neo4j-management/README.md` with:
+    - Purpose & scope (install, configure, start, stop Neo4j)
+    - Prerequisites (Java, `jq`, `NEO4J_INITIAL_PASSWORD`)
+    - Quick-start examples for setting up, starting, stopping Neo4j
+    - Environment variables reference
+    - Configuration templates explanation
+    - Agent-friendly structured instructions for future AGENTS.md / skill usage
+
+---
+
+### Relevant Files
+
+**Move (15 files):** 10 scripts from `scripts/` + 5 templates from `scripts/configuration/` (listed above)
+
+**Create (1 file):** `domains/neo4j-management/README.md`
+
+**Replace with redirect stubs (2 files):** `scripts/startNeo4j.sh`, `scripts/stopNeo4j.sh` — replaced in-place with minimal stubs that forward to the domain; not deleted
+
+**Update (9–11 files):** [analyze.sh](scripts/analysis/analyze.sh), [init.sh](init.sh), [scripts/runTests.sh](scripts/runTests.sh), [COMMANDS.md](COMMANDS.md), [README.md](README.md), [CHANGELOG.md](CHANGELOG.md), [.github/prompts/plan-coding_agent_instructions.prompt.md](.github/prompts/plan-coding_agent_instructions.prompt.md), possibly [scripts/resetAndScan.sh](scripts/resetAndScan.sh) and [renovate.json](renovate.json)
+
+**Stay in place:** All 11 profile scripts, 5 jQAssistant YAML templates, all query function scripts, `scripts/startNeo4j.sh` (as stub), `scripts/stopNeo4j.sh` (as stub)
+
+---
+
+### Verification
+
+1. Update [scripts/runTests.sh](scripts/runTests.sh) — it currently discovers tests with `find "${SCRIPTS_DIR}" -type f -name 'test*.sh'`, searching only the `scripts/` directory. Extend it to also search `domains/` so that `testConfigureNeo4j.sh` in its new location is picked up automatically (and any future domain-level tests are discovered too).
+2. Run `./scripts/runTests.sh` from the repository root — verify that `testConfigureNeo4j.sh` is discovered and executed from its new domain location, and that all other tests still pass.
+3. Run `shellcheck` on all moved scripts
+4. Grep for old paths (`scripts/setupNeo4j|scripts/configureNeo4j|scripts/detectNeo4j|scripts/waitForNeo4j|scripts/useNeo4jHighMemory|scripts/setupNeo4jInitialPassword|scripts/testConfigureNeo4j`) — no stale references should remain. `scripts/startNeo4j.sh` and `scripts/stopNeo4j.sh` are intentionally kept as redirect stubs, so references to them from *outside* this repository (e.g., old workspace forwarding scripts) are expected and acceptable.
+5. Verify `init.sh` forwarding scripts point to new locations
+6. Verify Renovate regex patterns still match profile files
+
+---
+
+### Decisions
+
+- **Profiles stay in `scripts/profiles/`** — they also contain jQAssistant settings (separate concern)
+- **jQAssistant YAML templates stay in `scripts/configuration/`** — not neo4j-specific
+- **No COPIED_FILES.md** — files are moved, not copied (clean cut)
+- **testConfigureNeo4j.sh moves** into the domain
+- **init.sh paths updated directly** — forwarding scripts created by `init.sh` point to the domain going forward
+- **`scripts/startNeo4j.sh` and `scripts/stopNeo4j.sh` replaced with redirect stubs** — they forward to the domain implementation; not referenced by any pipeline code after the change, but kept so old project workspaces (already initialised before this change) continue to work without migration
+- **No domain entry-point scripts** (`*Csv.sh`, `*Python.sh`) — this domain is infrastructure, not report generation
+
+---
+
+### Pros and Cons: Moving Query Functions
+
+The query execution infrastructure (`executeQueryFunctions.sh`, `executeQuery.sh`, `parseCsvFunctions.sh`, `projectionFunctions.sh`) was evaluated for inclusion:
+
+**Pros of moving:**
+- Cohesive grouping — all Neo4j interaction in one place
+- Agent-friendly — a single domain to fully operate Neo4j
+- Cleaner `scripts/` directory
+
+**Cons of moving:**
+- **30+ consumer files need path changes** — every report script, every domain script, `prepareAnalysis.sh`, `importGit.sh`
+- **Cross-domain coupling** — other domains would now depend on neo4j-management, breaking vertical-slice independence where each domain only depends on `scripts/`
+- **Mixing concerns** — management (lifecycle) and query execution (runtime API) are different layers
+- **No benefit to consumers** — the functions are already a stable, well-abstracted API
+
+**Recommendation:** Don't move query functions now. Keep neo4j-management focused on lifecycle management. Query functions could become a separate `neo4j-query-api` domain later if desired.

.github/skills/neo4j-management/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: neo4j-management
+description: "Manage a local Neo4j database for code graph analysis. Use when: starting Neo4j, stopping Neo4j, detecting if Neo4j is running, checking Neo4j status, answering 'Is Neo4j running?', 'Is Neo4j currently running?', 'where is Neo4j running?', increasing Neo4j memory, switching analysis workspace, troubleshooting Neo4j, setting up Neo4j."
+argument-hint: "is neo4j running | detect | start [workspace] | stop | memory | setup"
+---
+
+# Neo4j Management
+
+Manage the local Neo4j graph database lifecycle: detect, start, stop, reconfigure memory.
+
+**Quick reference:**
+
+| Action | Script | Typical trigger |
+|--------|--------|-----------------|
+| Detect | `detectNeo4j.sh` / `detectNeo4jWindows.sh` | First step always |
+| Start  | `startNeo4j.sh` | Neo4j not running |
+| Stop   | `stopNeo4j.sh` | Free resources, switch workspace |
+| Memory | `useNeo4jHighMemoryProfile.sh` | Out-of-memory or slow queries |
+| Setup  | Use `analyze.sh` (see [GETTING_STARTED](../../GETTING_STARTED.md)) | New installation |
+
+## When to Use
+
+- User asks to start, stop, or check on Neo4j
+- User wants to switch to a different analysis workspace
+- User runs into memory issues (heap, page cache) and wants to increase Neo4j memory
+- User asks to set up or install Neo4j
+
+## Domain Scripts
+
+The scripts live in `domains/neo4j-management/`. **Detection scripts** (`detectNeo4j.sh`, `detectNeo4jWindows.sh`) inspect the process table and can be run from **any directory**, including the repository root. **Start/stop/configure scripts** must be run from the **analysis workspace directory** (e.g. `temp/my-project`).
+
+| Script | Purpose |
+|--------|---------|
+| `detectNeo4j.sh` | Detect if Neo4j is running (Linux/macOS) |
+| `detectNeo4jWindows.sh` | Detect if Neo4j is running (WSL/Git Bash on Windows) |
+| `startNeo4j.sh` | Start Neo4j and wait until queryable |
+| `stopNeo4j.sh` | Stop Neo4j gracefully |
+| `useNeo4jHighMemoryProfile.sh` | Reconfigure with high-memory template |
+| `configureNeo4j.sh` | Apply a configuration template |
+
+### Internal scripts — do NOT use directly
+
+- `setupNeo4jInitialPassword.sh`
+- `waitForNeo4jHttpFunctions.sh`
+- `testConfigureNeo4j.sh`
+
+## Procedure
+
+### Step 1 — Detect if Neo4j Is Running
+
+Always run the detect script first — do **not** attempt to read processes, ports, or any other signals manually before the script has been executed.
+
+Determine the operating system. On **Windows** (WSL / Git Bash), run:
+
+```shell
+./domains/neo4j-management/detectNeo4jWindows.sh
+```
+
+On **Linux or macOS**, run:
+
+```shell
+./domains/neo4j-management/detectNeo4j.sh
+```
+
+If the script produces no output at all, run it a **second time** before drawing any conclusions. Only if the second run also returns nothing, treat it as equivalent to `Neo4j not running`.
+
+The output is one of:
+
+- `Neo4j not running`
+- `Neo4j running in <path> (workspace: <name>)` — workspace successfully identified
+- `Neo4j running in <path>` — path found but workspace could not be derived
+- `Neo4j running in (path undetermined)` — Neo4j is running but the path could not be read
+
+#### Workspace identified `(workspace: <name>)`
+
+The analysis workspace directory is the path **before** the `/tools` segment. For example, if the path is `/Users/me/repo/temp/my-project/tools/neo4j-community-2026.01.4`, the workspace is `/Users/me/repo/temp/my-project`. Inform the user and `cd` into that directory.
+
+#### Path found but no workspace in parentheses
+
+Neo4j is running outside the standard `temp/<workspace>/tools/...` layout.
+Ask the user if they know the workspace directory. If yes, `cd` into it and continue.
+If no — see [Troubleshooting guide](./references/troubleshooting.md) for manual stop and kill commands.
+
+#### Path undetermined
+
+Neo4j is running but the path cannot be read. Ask the user to run:
+
+```shell
+ps -eo pid,command | grep -i neo4j | grep -v grep
+```
+
+Once the path is identified, follow the "Path found" branch above or the [Troubleshooting guide](./references/troubleshooting.md).
+
+### Step 2 — Decide Based on User Intent and Neo4j State
+
+#### Neo4j is NOT running + user wants to start it
+
+1. Ask the user which analysis workspace to use (e.g. `temp/my-project`) if not already known.
+2. `cd` into the analysis workspace directory.
+3. Prompt the user for the Neo4j password:
+   > "What is your `NEO4J_INITIAL_PASSWORD`? (You can skip this if you prefer to set it yourself in the terminal — just type `skip` or press Enter.)"
+
+   - If the user provides a password, generate the export command:
+     ```shell
+     export NEO4J_INITIAL_PASSWORD=<provided-password>
+     ```
+   - If the user skips, remind them to run the export themselves before starting:
+     > "Please run `export NEO4J_INITIAL_PASSWORD=<your-password>` in your terminal before starting Neo4j."
+4. Start Neo4j:
+   ```shell
+   ./startNeo4j.sh
+   ```
+
+#### Neo4j IS running + user wants to start a DIFFERENT workspace
+
+**Strongly warn the user**: running two analysis workspaces against the same Neo4j instance corrupts data by mixing results from different projects.
+
+Recommend stopping the current analysis first:
+
+```shell
+cd <current-workspace>
+./stopNeo4j.sh
+```
+
+Only proceed with starting the new workspace after the user confirms they have stopped the old one.
+
+#### Neo4j IS running + user wants to stop it
+
+`cd` into the workspace where Neo4j is running, then:
+
+```shell
+./stopNeo4j.sh
+```
+
+#### User reports memory issues
+
+Apply the high-memory configuration template. Neo4j must be **stopped** first.
+
+```shell
+cd <workspace>
+./stopNeo4j.sh
+./useNeo4jHighMemoryProfile.sh
+./startNeo4j.sh
+```
+
+### Step 3 — Setup / Installation Requests
+
+> **Always recommend using `analyze.sh` first.** It handles download, installation, configuration, start, and stop automatically via profiles. Point the user to the [GETTING_STARTED guide](../../GETTING_STARTED.md).
+
+Only assist with a manual `setupNeo4j.sh` invocation if the user can explain a concrete reason why the automated `analyze.sh` workflow does not fit their needs (e.g. custom Neo4j version, enterprise edition, non-standard directory layout).
+
+## Environment Variables
+
+All are set automatically by `analyze.sh` in normal runs. For manual operation:
+
+| Variable | Default | Required |
+|----------|---------|----------|
+| `NEO4J_INITIAL_PASSWORD` | — | **Yes** |
+| `NEO4J_VERSION` | `2026.01.4` | No |
+| `NEO4J_EDITION` | `community` | No |
+| `NEO4J_HTTP_PORT` | `7474` | No |
+| `TOOLS_DIRECTORY` | `tools` | No |
+
+## Important Warnings
+
+- **Stop Neo4j before switching projects.** Data from different projects will mix in the same database instance otherwise.
+- **`NEO4J_INITIAL_PASSWORD` must be set** before starting or setting up Neo4j.
+- Scripts expect to be run from the analysis workspace directory (where the `tools/` folder lives).
+- **Docker is not supported.** Detection and management scripts rely on native process inspection (`ps`) and do not detect or manage Neo4j running inside a Docker container.

.github/skills/neo4j-management/references/troubleshooting.md

@@ -0,0 +1,68 @@
+# Neo4j Management — Troubleshooting
+
+Reference for edge cases where Neo4j is running but the analysis workspace cannot be determined automatically.
+
+## Path found but workspace unknown
+
+Neo4j is running in a path that does not follow the standard `temp/<workspace>/tools/...` layout.
+
+**Step 1:** Ask the user:
+
+> "Neo4j is running in `<path>` but I could not determine the analysis workspace automatically. Do you know which workspace directory this belongs to?"
+
+- If the user provides the workspace → `cd` into it and continue normally with `startNeo4j.sh` / `stopNeo4j.sh`.
+
+**Step 2:** If the user does not know or says Neo4j is running outside the pipeline, help with manual control:
+
+Locate the `bin/` directory inside the detected path (contains `neo4j` or `neo4j.bat`), then:
+
+```shell
+# Stop (Linux/macOS)
+NEO4J_HOME=<path> <path>/bin/neo4j stop
+
+# Stop (Windows, Git Bash or CMD)
+<path>\bin\neo4j.bat stop
+```
+
+If the command above fails:
+
+```shell
+# Linux/macOS — find the PID and send SIGTERM
+kill $(ps -eo pid,command | grep -i neo4j | grep -v grep | awk '{print $1}')
+
+# Force kill if process does not stop after ~30 s
+kill -9 $(ps -eo pid,command | grep -i neo4j | grep -v grep | awk '{print $1}')
+```
+
+```powershell
+# Windows PowerShell — find and stop Neo4j process
+Get-CimInstance Win32_Process -Filter "Name='java.exe'" |
+  Where-Object { $_.CommandLine -like '*neo4j*' } |
+  Select-Object -ExpandProperty ProcessId |
+  Stop-Process -Id
+```
+
+## Path undetermined
+
+Neo4j is running but the detect script could not read the path from the process.
+
+**Step 1:** Ask the user to run the appropriate command to find the process:
+
+```shell
+# Linux/macOS
+ps -eo pid,command | grep -i neo4j | grep -v grep
+```
+
+```powershell
+# Windows PowerShell
+Get-CimInstance Win32_Process -Filter "Name='java.exe'" |
+  Where-Object { $_.CommandLine -like '*neo4j*' } |
+  Select-Object ProcessId, CommandLine
+```
+
+**Step 2:** From the command output help the user identify the Neo4j home path:
+- Look for `--home-dir=<path>` in the command line (Neo4j 5+)
+- Or `-Dneo4j.home=<path>` (Neo4j 4)
+- Or a classpath entry ending in `/lib/*` — strip `/lib/*` to get the home
+
+**Step 3:** Once the path is known, follow the "Path found but workspace unknown" section above.