coding-os 0.3.2__py3-none-any.whl

templates/rust-axum/skills/rust/references/anatomy.md

@@ -0,0 +1,63 @@
+<!-- domain:RUSTAXUM | layer:reference | ssot:true | updated:2026-06-27 -->
+# Rust + Axum Anatomy
+
+> P: Canonical file map + entity recipes for the Rust + Axum (tokio, tower, AppError) stack.
+> R: Adding any `.rs` under `src/backend/`, or routing a backend task.
+> S: Reading frontend / mobile code — wrong stack.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: `src/templates/rust-axum/scaffold-boundary.yaml`.
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Handler | `src/routes/<domain>.rs` | `<domain>.rs` | service, error | Thin async fn → `Result<Json<_>, AppError>` |
+| Router | `src/app.rs` | `app.rs` | routes | Route table + tower middleware layers |
+| Error | `src/error.rs` | `error.rs` | none | The ONE `AppError` → `IntoResponse` shaper |
+| Entry | `src/main.rs` | `main.rs` | `app` | tokio entry; binds the listener — no logic |
+| Module index | `src/routes/mod.rs` | `mod.rs` | route files | Re-exports the domain handlers |
+| Test | `#[cfg(test)]` / `tests/<name>.rs` | `<name>.rs` | source under test | `tokio::test` + `tower::ServiceExt` |
+
+## 3. Entity recipes
+
+### Add a new endpoint
+- **Trigger:** "add `GET /<domain>`".
+- **Files emitted:**
+  1. `src/routes/<domain>.rs`
+  2. registration in `src/routes/mod.rs` + `src/app.rs`
+- **Steps:**
+  1. Handler is an async fn with extractors (validate fail-closed) → `Result<_, AppError>`.
+  2. Return `Ok(Json(..))` or an `AppError`; never write a response body inline.
+  3. Layer the route into the router in `app.rs`.
+
+### Add a new model
+- **Trigger:** "persist `<Entity>`".
+- **Files emitted:** `src/<domain>/model.rs` (+ repository).
+- **Steps:**
+  1. Plain struct + `serde`; DB access behind a repository, not the handler.
+
+### Add a new test
+- **Trigger:** any new handler.
+- **Files emitted:** `#[cfg(test)] mod tests` or `tests/<name>.rs`.
+- **Steps:**
+  1. Drive the router via `app.oneshot(request)`; assert status + body.
+
+## 4. Conventions
+
+#### Naming
+- Files / modules: `snake_case.rs`. Types: `PascalCase`; fns: `snake_case`.
+
+#### Test colocation
+- Colocated: `#[cfg(test)] mod tests` in the source file; integration in `tests/`.
+
+#### Dependency rules
+- ✓ handler → service → repository; errors flow up as `AppError`.
+- ✗ no `.unwrap()` on fallible paths in a handler — return `AppError`.
+- ✗ `src/backend/` never imports from `src/frontend/` / `src/mobile/` — share via `src/shared/`.

templates/rust-axum/stack.yaml

@@ -0,0 +1,65 @@
+version: 1
+id: rust-axum
+language: rust
+label: "Rust + Axum"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── Cargo.toml
+    └── src/
+        ├── main.rs             # tokio entry — builds the router, binds the listener (no logic)
+        ├── app.rs              # Router assembly: routes + tower middleware layers
+        ├── error.rs            # the ONE central AppError → IntoResponse error shaper
+        └── routes/             # one module per domain
+            ├── mod.rs
+            └── health.rs       # handler fn + extractors; returns Result<Json<_>, AppError>
+  notes: "handlers are thin async fns returning Result<_, AppError>; tower middleware (TraceLayer, etc.) layered in app.rs; one AppError type implementing IntoResponse is the ONLY error-response shaper; extractors validate input fail-closed before the handler body runs"
+primary_skill: rust
+skills: [rust]
+
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/rust-axum-service.md`"
+  SKILL_ROUTES: "Backend→`rust`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/rust-axum-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && cargo clippy -- -D warnings && cargo test`"
+  QUICK_ROUTING: |-
+    - Axum handler / router task → [Rust + Axum Service Playbook](./playbooks/rust-axum-service.md)
+    - Extractor / tower middleware / AppError → [Rust + Axum Service Playbook](./playbooks/rust-axum-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-RUST-AXUM` → `./playbooks/rust-axum-service.md`
+    - `REF:RUST-AXUM-RULES` → `./engineering/rust-axum-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-RUST-AXUM", path: "./playbooks/rust-axum-service.md", desc: "Rust + Axum service playbook"}
+  - {code: "REF:RUST-AXUM-RULES",    path: "./engineering/rust-axum-rules.md", desc: "Rust + Axum engineering rules"}
+
+routing_entries:
+  - "Axum handler / router task → [Rust + Axum Service Playbook](./playbooks/rust-axum-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.rs"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "cd src/backend && cargo clippy -- -D warnings"}
+  - {name: test-backend, cmd: "cd src/backend && cargo test"}
+
+verify:
+  - {glob: "src/backend/**/*.rs", suites: "lint-backend + test-backend", cmd: "cd src/backend && cargo clippy -- -D warnings && cargo test"}
+
+dimensions:
+  - {name: "Axum handler",            read_files: ["docs/playbooks/rust-axum-service.md", "docs/engineering/rust-axum-rules.md"]}
+  - {name: "Router / app wiring",     read_files: ["docs/engineering/rust-axum-rules.md"]}
+  - {name: "Extractor / DTO",         read_files: ["docs/engineering/rust-axum-rules.md", "docs/api-contracts/error-format.md"]}
+  - {name: "Tower middleware",        read_files: ["docs/engineering/rust-axum-rules.md"]}
+  - {name: "AppError / IntoResponse", read_files: ["docs/engineering/rust-axum-rules.md", "docs/api-contracts/error-format.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.rs"], primary: rust, secondary: [clean-code, backend-fundamentals, api-design, hexagonal-architecture, testing-strategy, observability]}
+  - {globs: ["src/backend/**/routes/**/*.rs", "src/backend/**/handlers/**/*.rs"], primary: rust, secondary: [clean-code, api-design, backend-fundamentals]}
+  - {globs: ["src/backend/**/auth*.rs", "src/backend/**/middleware/**/*.rs"], primary: rust, secondary: [auth-patterns, security-web, clean-code]}

templates/rust-plain/scaffold/src/backend/Cargo.toml

@@ -0,0 +1,6 @@
+[package]
+name = "{{PROJECT_NAME}}"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]

templates/rust-plain/scaffold/src/backend/src/main.rs

@@ -0,0 +1,3 @@
+fn main() {
+    println!("{{PROJECT_NAME}} — scaffolded by coding-os (rust-plain)");
+}

templates/rust-plain/scaffold-boundary.yaml

@@ -0,0 +1,23 @@
+# Scaffold boundary for the rust-plain stack (std + Cargo only).
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: rust-plain
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.rs"
+  - "src/backend/**/Cargo.toml"
+
+imports_from:
+  - src/shared/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Plain Cargo crate — Cargo.toml lives in src/backend/. Framework stacks (rust-axum) replace this layout."

templates/rust-plain/stack.yaml

@@ -0,0 +1,51 @@
+version: 1
+id: rust-plain
+language: rust
+label: "Rust (plain — std + Cargo, no web framework)"
+category: backend
+primary_skill: null
+skills: []
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── Cargo.toml
+    └── src/
+        └── main.rs        # grow into lib.rs + modules as the crate grows
+  notes: "plain Cargo binary; split into lib.rs + a module tree (domain/ports/adapters) when it becomes a service"
+
+# Plain-language stack (template-authoring.md § Language layer): picked when
+# the user chooses "rust" without a framework. Ships a runnable crate skeleton
+# and the verify wiring; framework stacks (rust-axum) extend the language with
+# their own conventions.
+
+substitutions:
+  DOMAIN_ROUTES: "Rust crate / CLI task → AGENTS.md critical rules"
+  SKILL_ROUTES: "Rust → `clean-code` (generic) + `thinking_os` (kernel)"
+  ENGINEERING_RULE_ROUTING: "Rust → AGENTS.md critical rules + `docs/governance/`"
+  TOOL_ROUTING_IMPL: "`lint-rust`, `test-rust`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-rust + test-rust"
+  VERIFY_BACKEND: "`cd src/backend && cargo clippy -- -D warnings && cargo test`"
+  QUICK_ROUTING: |-
+    - Rust crate / module task → see AGENTS.md critical rules
+  STACK_REF_CODES: ""
+
+ref_codes: []
+
+routing_entries:
+  - "Rust crate / CLI task → see AGENTS.md critical rules"
+
+rules: []
+
+makefile_targets:
+  - {name: lint-rust, cmd: "cd src/backend && cargo clippy -- -D warnings"}
+  - {name: test-rust, cmd: "cd src/backend && cargo test"}
+
+verify:
+  - {glob: "src/backend/**/*.rs", suites: "lint-rust + test-rust", cmd: "cd src/backend && cargo clippy -- -D warnings && cargo test"}
+
+dimensions: []
+
+skill_enforcement: []

templates/spring-boot/rules/backend.md

@@ -0,0 +1,20 @@
+---
+globs: ["src/backend/**/*.java"]
+alwaysApply: false
+---
+
+# Spring Boot Backend Rules (auto-loaded on src/backend/**/*.java)
+
+When editing any Java file under `src/backend/` in a Spring Boot project, follow these standards:
+
+- **Controller signature** — `@RestController` handlers take the `@Valid` DTO + path/query params and return a typed value or `ResponseEntity<T>`. No response envelope built by hand.
+- **Typed errors** — throw a typed exception (a domain exception or `ResponseStatusException`); a single `@RestControllerAdvice` maps it to the RFC 9457 problem shape `{type, title, status}`. Never write an error body anywhere else.
+- **Validation** — annotate request DTOs with Bean Validation constraints and `@Valid` at the controller boundary; reject fail-closed with field-level details. No raw `@RequestBody` reaching a service unvalidated.
+- **Dependency injection** — inject collaborators by constructor (`final` fields); never `new` a bean or use field injection. A `new SomeService()` bypasses the container and breaks test overrides.
+- **Layering** — `@RestController` → `@Service` → `@Repository`. Controllers don't touch a repository or `EntityManager` directly — services do.
+- **Transport-free services** — a `@Service` importing `HttpServletRequest`/`ServletResponse` or building a response is a build-blocking review finding.
+- **Tests** — every endpoint gets a `@SpringBootTest` + `MockMvc` (or `WebTestClient`) test, happy + error paths; services get context-free unit tests with mocked collaborators.
+
+Canonical policy: `docs/engineering/spring-boot-rules.md`
+Playbook: `docs/playbooks/spring-boot-service.md`
+Primary skill: `spring-boot`

templates/spring-boot/scaffold/docs/engineering/spring-boot-rules.md

@@ -0,0 +1,35 @@
+<!-- domain:BACKEND | layer:rules | ssot:true | updated:{{DATE}} -->
+# Spring Boot Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} Spring Boot backend.
+Read when: Editing anything under `src/backend/`.
+Skip when: Frontend/mobile work.
+Read next: [Spring Boot Service Playbook](../playbooks/spring-boot-service.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Layering** — `@RestController` → `@Service` → `@Repository`, imports flow one
+   way only (the table in the `spring-boot` skill is the SSOT).
+2. **Transport-free services** — a `@Service` importing `HttpServletRequest` or
+   building a response is a build-blocking review finding.
+3. **One error shaper** — only the global `@RestControllerAdvice` writes error
+   bodies; it logs full detail and returns the problem shape with no internals
+   (no stack traces, no driver messages).
+4. **Validation fail-closed** — every input is a `@Valid` Bean Validation DTO; an
+   unvalidated `@RequestBody` never reaches a service.
+5. **Dependency injection** — inject by constructor into `final` fields; never
+   `new` a bean and never use field injection — both bypass the container and
+   break test overrides.
+6. **No floating config** — bind configuration once via `@ConfigurationProperties`
+   types; services receive typed config, never read raw `Environment` keys deep in
+   a method.
+7. **Formatted + warning-clean** — `spotless:check` (Google Java Format) is the lint
+   gate; a suppressed warning requires a written justification at the call site.
+
+## Testing bar
+
+Services ≥ unit-tested per public method (no context, mocked collaborators);
+controllers ≥ happy + error path via `@SpringBootTest` + `MockMvc`; repositories
+integration-tested with `@DataJpaTest` against a disposable database.

templates/spring-boot/scaffold/docs/playbooks/spring-boot-service.md

@@ -0,0 +1,45 @@
+<!-- domain:BACKEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Spring Boot Service Playbook
+
+Purpose: The end-to-end recipe for adding or changing a Spring Boot endpoint in {{PROJECT_NAME}}.
+Read when: Any task that adds a controller, service, repository, DTO, or security config.
+Skip when: Pure infra/devops work — see the deployment docs.
+Read next: [Spring Boot Engineering Rules](../engineering/spring-boot-rules.md), [Error Format](../api-contracts/error-format.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add an endpoint (the only sanctioned path)
+
+1. **Contract first** — define the request/response DTOs as records with Bean
+   Validation constraints; error cases use the shared problem format
+   ([error-format](../api-contracts/error-format.md)).
+2. **Feature package** — `src/main/java/com/example/app/<feature>/` holds the
+   controller + service for one domain; nothing else reaches into it.
+3. **Controller** — `<Feature>Controller.java`: `@RestController`, validate the
+   `@Valid` DTO, call exactly one service method, return the value. No response
+   envelope built by hand.
+4. **Service** — `<Feature>Service.java`: `@Service`, business logic only, no
+   `HttpServletRequest` and no transport types, typed domain exceptions on failure.
+5. **Repository** — `<Feature>Repository.java` (Spring Data) for one aggregate;
+   services never touch the `EntityManager` directly.
+6. **Wire** — nothing to register by hand: component scanning discovers the
+   beans; the container injects them by constructor.
+7. **Test** — unit-test the service (no context) with mocked collaborators +
+   `@SpringBootTest` + `MockMvc` integration-test the endpoint (happy + error path).
+8. **Verify** — `cd src/backend && ./mvnw -q verify`.
+
+## Global wiring (set once)
+
+`@SpringBootApplication` boots the context; the single `@RestControllerAdvice`
+(`common/GlobalExceptionHandler.java`) is auto-registered so every route inherits
+one error shape. The global `@Valid` + Bean Validation rejects bad input before a
+service runs.
+
+## Anti-patterns
+
+- Error JSON built inside a controller — the `@RestControllerAdvice` owns the shape.
+- A service importing `HttpServletRequest`/`ServletResponse` — that layer must stay
+  transport-free.
+- `new SomeService()` or field injection instead of constructor injection —
+  bypasses the container and breaks test overrides.
+- An unvalidated `@RequestBody` reaching a service — every input is a `@Valid` DTO.

templates/spring-boot/scaffold/src/backend/mvnw

@@ -0,0 +1,302 @@
+#!/bin/sh
+# ----------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+# ----------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------
+# Apache Maven Wrapper startup batch script, version 3.3.2
+#
+# Optional ENV vars
+# -----------------
+#   JAVA_HOME - location of a JDK home dir, required when download maven via java source
+#   MVNW_REPOURL - repo url base for downloading maven distribution
+#   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+#   MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output
+# ----------------------------------------------------------------------------
+
+set -euf
+[ "${MVNW_VERBOSE-}" != debug ] || set -x
+
+# OS specific support.
+native_path() { printf %s\\n "$1"; }
+case "$(uname)" in
+CYGWIN* | MINGW*)
+  [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")"
+  native_path() { cygpath --path --windows "$1"; }
+  ;;
+esac
+
+# set JAVACMD and JAVACCMD
+set_java_home() {
+  # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched
+  if [ -n "${JAVA_HOME-}" ]; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ]; then
+      # IBM's JDK on AIX uses strange locations for the executables
+      JAVACMD="$JAVA_HOME/jre/sh/java"
+      JAVACCMD="$JAVA_HOME/jre/sh/javac"
+    else
+      JAVACMD="$JAVA_HOME/bin/java"
+      JAVACCMD="$JAVA_HOME/bin/javac"
+
+      if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then
+        echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2
+        echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2
+        return 1
+      fi
+    fi
+  else
+    JAVACMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v java
+    )" || :
+    JAVACCMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v javac
+    )" || :
+
+    if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then
+      echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2
+      return 1
+    fi
+  fi
+}
+
+# hash string like Java String::hashCode
+hash_string() {
+  str="${1:-}" h=0
+  while [ -n "$str" ]; do
+    char="${str%"${str#?}"}"
+    h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296))
+    str="${str#?}"
+  done
+  printf %x\\n $h
+}
+
+verbose() { :; }
+[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; }
+
+die() {
+  printf %s\\n "$1" >&2
+  exit 1
+}
+
+trim() {
+  # MWRAPPER-139:
+  #   Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds.
+  #   Needed for removing poorly interpreted newline sequences when running in more
+  #   exotic environments such as mingw bash on Windows.
+  printf "%s" "${1}" | tr -d '[:space:]'
+}
+
+scriptDir="$(dirname "$0")"
+scriptName="$(basename "$0")"
+
+# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties
+while IFS="=" read -r key value; do
+  case "${key-}" in
+  distributionUrl) distributionUrl=$(trim "${value-}") ;;
+  distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;;
+  esac
+done <"$scriptDir/.mvn/wrapper/maven-wrapper.properties"
+[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+
+case "${distributionUrl##*/}" in
+maven-mvnd-*bin.*)
+  MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/
+  case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in
+  *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;;
+  :Darwin*x86_64) distributionPlatform=darwin-amd64 ;;
+  :Darwin*arm64) distributionPlatform=darwin-aarch64 ;;
+  :Linux*x86_64*) distributionPlatform=linux-amd64 ;;
+  *)
+    echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2
+    distributionPlatform=linux-amd64
+    ;;
+  esac
+  distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip"
+  ;;
+maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;;
+*) MVN_CMD="mvn${scriptName#mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;;
+esac
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}"
+distributionUrlName="${distributionUrl##*/}"
+distributionUrlNameMain="${distributionUrlName%.*}"
+distributionUrlNameMain="${distributionUrlNameMain%-bin}"
+MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}"
+MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")"
+
+exec_maven() {
+  unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || :
+  exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD"
+}
+
+if [ -d "$MAVEN_HOME" ]; then
+  verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  exec_maven "$@"
+fi
+
+case "${distributionUrl-}" in
+*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;;
+*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;;
+esac
+
+# prepare tmp dir
+if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then
+  clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; }
+  trap clean HUP INT TERM EXIT
+else
+  die "cannot create temp dir"
+fi
+
+mkdir -p -- "${MAVEN_HOME%/*}"
+
+# select .zip or .tar.gz
+if ! command -v unzip >/dev/null; then
+  distributionUrl="${distributionUrl%.zip}.tar.gz"
+  distributionUrlName="${distributionUrl##*/}"
+fi
+
+# Download and Install Apache Maven
+verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+verbose "Downloading from: $distributionUrl"
+verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+# verbose opt
+__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR=''
+[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v
+
+# normalize http auth
+case "${MVNW_PASSWORD:+has-password}" in
+'') MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+esac
+
+if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then
+  verbose "Found wget ... using wget"
+  wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl"
+elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then
+  verbose "Found curl ... using curl"
+  curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl"
+elif set_java_home; then
+  verbose "Falling back to use Java to download"
+  javaSource="$TMP_DOWNLOAD_DIR/Downloader.java"
+  targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName"
+  cat >"$javaSource" <<END
+    public class Downloader extends java.net.Authenticator
+    {
+      protected java.net.PasswordAuthentication getPasswordAuthentication()
+      {
+        return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() );
+      }
+      public static void main( String[] args ) throws Exception
+      {
+        setDefault( new Downloader() );
+        java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() );
+      }
+    }
+END
+  # For Cygwin/MinGW, switch paths to Windows format before running javac and java
+  verbose " - Compiling Downloader.java ..."
+  "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java"
+  verbose " - Running Downloader.java ..."
+  "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")"
+fi
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+if [ -n "${distributionSha256Sum-}" ]; then
+  distributionSha256Result=false
+  computedSha256Sum=""
+  if [ "$MVN_CMD" = mvnd.sh ]; then
+    echo "Checksum validation is not supported for maven-mvnd." >&2
+    echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  elif command -v sha256sum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c --strict - >/dev/null 2>&1; then
+      distributionSha256Result=true
+    else
+      computedSha256Sum=$(sha256sum "$TMP_DOWNLOAD_DIR/$distributionUrlName" | cut -b -64)
+    fi
+  elif command -v shasum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then
+      distributionSha256Result=true
+    else
+      computedSha256Sum=$(shasum "$TMP_DOWNLOAD_DIR/$distributionUrlName" | cut -b -64)
+    fi
+  else
+    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2
+    echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  fi
+  if [ $distributionSha256Result = false ]; then
+    echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2
+    echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2
+    echo "expected: $distributionSha256Sum" >&2
+    echo "received: $computedSha256Sum" >&2
+    exit 1
+  fi
+fi
+
+# unzip and move
+if command -v unzip >/dev/null; then
+  unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip"
+else
+  tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar"
+fi
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+actualDistributionDir=""
+
+# First try the expected directory name (for regular distributions)
+if [ -d "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" ]; then
+  if [ -f "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/bin/$MVN_CMD" ]; then
+    actualDistributionDir="$distributionUrlNameMain"
+  fi
+fi
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if [ -z "$actualDistributionDir" ]; then
+  # enable globbing to iterate over items
+  set +f
+  for dir in "$TMP_DOWNLOAD_DIR"/*; do
+    if [ -d "$dir" ]; then
+      if [ -f "$dir/bin/$MVN_CMD" ]; then
+        actualDistributionDir="$(basename "$dir")"
+        break
+      fi
+    fi
+  done
+  set -f
+fi
+
+if [ -z "$actualDistributionDir" ]; then
+  verbose "Contents of $TMP_DOWNLOAD_DIR:"
+  verbose "$(ls -la "$TMP_DOWNLOAD_DIR")"
+  die "Could not find Maven distribution directory in extracted archive"
+fi
+
+verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$actualDistributionDir/mvnw.url"
+mv -- "$TMP_DOWNLOAD_DIR/$actualDistributionDir" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME"
+
+clean || :
+exec_maven "$@"