@meistrari/mise-en-place 2.19.1 → 2.21.0

package/README.md

@@ -58,6 +58,94 @@ You can customize the update behaviour through a `miseEnPlace.updateMeistrariLib
 
 When `exact` is `true`, every updated package is written as an exact version: each package is still updated as far as its strategy allows, but the resulting version is written without a `^` or `~`.
 
+## Local proxy for Compose services
+The `tela-proxy` mise tasks run one Traefik container shared by every project on the machine. It serves each Compose service attached to the `tela-network` Docker network at a `*.localhost` host, so services publish no HTTP ports and several projects run side by side.
+
+Requires Docker; mise installs the `jq` the tasks use. The proxy listens on port 80 of the loopback interface only, and the dashboard of active routes is at `http://tela-proxy.localhost`.
+
+### Tasks
+- **`mise run tela-proxy`** (alias `tela-proxy:start`): creates `tela-network` when missing and starts the proxy. Make it a dependency of every task that starts your Compose project (`#MISE depends=["tela-proxy"]`), so it also runs the conflict check below.
+- **`mise run tela-proxy:stop`**: stops the proxy. It stays stopped across reboots until `tela-proxy` runs again.
+- **`mise run tela-proxy:worktree [label] [-- command...]`** (aliases `worktree`, `wt`): runs the command under a separate Compose project for a worktree. Without a command, it opens `$SHELL` with the same environment.
+
+### Hosts
+A service gets `http://{service}.{project}.localhost`, where `project` is the Compose project name. Set it with `name:` in the Compose file so it stays the same in every clone; otherwise Compose uses the directory name.
+
+- A service named after the project prefix drops it: service `auth-api` in project `auth` is `api.auth.localhost`.
+- A service named exactly like the project is `{project}.localhost`.
+- Traefik uses the port the image exposes (`EXPOSE`).
+- A service opts out with the `traefik.enable=false` label.
+
+A `tela-proxy.host` label replaces a service's host. `{project}` in the value becomes the project's domain, including the worktree suffix, so a worktree keeps its own host:
+
+```yaml
+services:
+  web:
+    labels:
+      tela-proxy.host: '{project}.localhost' # service.localhost, or service-feat-x.localhost in a worktree
+  admin:
+    labels:
+      tela-proxy.host: 'painel.{project}.localhost'
+```
+
+A value without `{project}` is the same in every worktree, so the main checkout and its worktrees answer on one host.
+
+`{project}.localhost` is the value of `TELA_LOCAL_DOMAIN` (see [Worktrees](#worktrees)), so the URL for the `admin` service above is `http://painel.${TELA_LOCAL_DOMAIN:-service.localhost}`.
+
+Only HTTP is routed. Databases keep their published ports.
+
+### Networks
+Keep the Compose `default` network private to the project, and attach only the services the proxy routes to `tela-network`:
+
+```yaml
+services:
+  auth-api:
+    networks:
+      default:
+        aliases: [auth-api-internal]
+      tela-network: {}
+  auth-postgres: {} # default only
+
+networks:
+  tela-network:
+    external: true
+```
+
+Every project and worktree registers its service names on `tela-network`, so a name there can resolve to another checkout's container. On the private `default` network, names resolve only within the project:
+
+- Databases and other internal services stay on `default` only, and their names are safe to use. Label them `traefik.enable=false`: the proxy sees every container and would otherwise create a route it cannot reach.
+- Calls from one service of the project to an HTTP service of the same project use an alias declared only on `default` (`http://auth-api-internal:3001`), because the service name is also on `tela-network`.
+- Another project reaches an HTTP service by its service name on `tela-network` (`http://auth-api:3001`).
+
+Changing `networks:` needs the containers recreated: stop the stack and start it again.
+
+Inside a container, `*.localhost` resolves to the container itself, so containers never call each other through the proxy hosts.
+
+### Worktrees
+`tela-proxy:worktree` exports these variables before running the command:
+
+- **`COMPOSE_PROJECT_NAME`**: `{project}_{label}`. It overrides `name:`, so the worktree gets its own containers and volumes.
+- **`TELA_LOCAL_DOMAIN`**: `{project}-{label}.localhost`, the parent domain of the worktree's hosts (`api.auth-feat-x.localhost`).
+- **`TELA_PROXY_WORKTREE`**: the label. The task refuses to open a shell inside another one.
+
+The label defaults to the name of the current git worktree, lowercased and limited to `a-z`, `0-9` and `-`. In the main checkout, pass one explicitly.
+
+Build the URLs a project gives its own services from `TELA_LOCAL_DOMAIN`, defaulting to the main checkout's domain:
+
+```yaml
+services:
+  auth-api:
+    environment:
+      BETTER_AUTH_URL: http://api.${TELA_LOCAL_DOMAIN:-auth.localhost}
+```
+
+Published database ports still collide with the main checkout. Override them through the variables your Compose file reads, for example `AUTH_POSTGRES_PORT=5434 mise run wt -- mise run dev`.
+
+### Conflict check
+`tela-proxy` and `tela-proxy:worktree` look up the containers of the current Compose project. When they were started from another directory that still exists, the task fails instead of letting `up` recreate them and share their volumes. Running `mise run dev` inside a worktree without `tela-proxy:worktree` fails this way. Containers from a directory that no longer exists, such as a removed worktree, only produce a warning and are taken over.
+
+The check only covers commands that go through these tasks. A plain `docker compose` call, or one that passes `-p`, bypasses it.
+
 ## Makefile
 The postinstall script does not create a `Makefile` automatically. To use the shared Makefile commands, create a `Makefile` and include this package's `Makefile`.
 

package/mise/tasks/registry-login.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-#MISE description="Login to the internal registry. Opens the UI so you can copy your CLI secret."
+#MISE description="Login to the internal npm and container registries. Opens the browser for npm, then the registry UI so you can copy your CLI secret."
+#USAGE flag "--npm-registry <url>" default="https://npm.internal.tela.tools/" help="npm registry to log in to through the browser." env="NPM_REGISTRY"
 #USAGE flag "-r --registry <registry>" default="registry.internal.tela.tools" help="Registry host to authenticate against." env="REGISTRY_HOST"
 #USAGE flag "-u --username <username>" default="" help="Registry OIDC username. Prompted for when omitted." env="REGISTRY_USERNAME"
 #USAGE flag "-f --force" default=#false help="Re-authenticate even if the stored credential still works."
@@ -9,6 +10,7 @@
 
 set -euo pipefail
 
+NPM_REGISTRY="${usage_npm_registry:-${NPM_REGISTRY:-https://npm.internal.tela.tools/}}"
 REGISTRY="${usage_registry:-${REGISTRY_HOST:-registry.internal.tela.tools}}"
 USERNAME="${usage_username:-${REGISTRY_USERNAME:-}}"
 
@@ -60,6 +62,16 @@ open_browser() {
 
 command -v docker >/dev/null 2>&1 || die "docker is not installed"
 command -v jq >/dev/null 2>&1 || die "jq is not installed"
+command -v npm >/dev/null 2>&1 || die "npm is not installed"
+
+# The internal npm registry comes first: its web login only needs the browser,
+# while the Harbor step below waits for a pasted secret. Like Harbor, it is only
+# reachable over the NetBird VPN.
+if [ "${usage_force:-false}" != "true" ] && npm whoami --registry "$NPM_REGISTRY" >/dev/null 2>&1; then
+    echo "Already logged in to ${NPM_REGISTRY}."
+else
+    npm login --auth-type=web --registry "$NPM_REGISTRY"
+fi
 
 check_reachable || die "cannot reach ${REGISTRY}. It is only routable over the NetBird VPN — connect and retry."
 

package/mise/tasks/tela-proxy/_default.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+#MISE description="Create tela-network and start the shared proxy that serves Compose services on *.localhost"
+#MISE alias="tela-proxy:start"
+#MISE tools={jq="1.8.2"}
+
+set -euo pipefail
+
+# shellcheck source=lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+enter_caller_dir
+
+check_project_conflict
+
+acquire_proxy_lock
+ensure_network
+if ! proxy_compose up -d --quiet-pull >/dev/null; then
+    die "could not start the proxy. If port 80 is taken, find who holds it with:
+  sudo ss -ltnp 'sport = :80'    (Linux)
+  sudo lsof -iTCP:80 -sTCP:LISTEN (macOS)"
+fi
+release_proxy_lock
+
+info "tela-proxy is running: http://<service>.<project>.localhost (dashboard: http://tela-proxy.localhost)"

package/mise/tasks/tela-proxy/compose.yaml

@@ -0,0 +1,26 @@
+# Shared local proxy. Started by `mise run tela-proxy`, never by hand: the task
+# copies traefik.yml to TELA_PROXY_TRAEFIK_CONFIG and sets TELA_PROXY_CONFIG_HASH,
+# so a changed config recreates the container.
+name: tela-proxy
+
+services:
+  traefik:
+    image: traefik:v3.7.18
+    restart: unless-stopped
+    command: [--configFile=/etc/traefik/traefik.yml]
+    ports:
+      # Loopback only, on both stacks: *.localhost resolves to ::1 on Linux.
+      - '127.0.0.1:80:80'
+      - '[::1]:80:80'
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ${TELA_PROXY_TRAEFIK_CONFIG:?run mise run tela-proxy}:/etc/traefik/traefik.yml:ro
+    labels:
+      tela-proxy.config-hash: ${TELA_PROXY_CONFIG_HASH:-unset}
+      traefik.http.routers.tela-proxy.rule: Host(`tela-proxy.localhost`)
+      traefik.http.routers.tela-proxy.service: api@internal
+
+networks:
+  default:
+    name: tela-network
+    external: true

package/mise/tasks/tela-proxy/lib.sh

@@ -0,0 +1,168 @@
+# Shared helpers for the tela-proxy mise tasks. Sourced, not executed.
+
+TELA_PROXY_HOME="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TELA_PROXY_NETWORK="tela-network"
+TELA_PROXY_PROJECT="tela-proxy"
+
+die() { printf '\033[31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+warn() { printf '\033[33mwarning:\033[0m %s\n' "$*" >&2; }
+info() { printf '\033[36m%s\033[0m\n' "$*" >&2; }
+
+# mise runs a task from its config root, not from where it was called. It keeps
+# the caller's directory in MISE_ORIGINAL_CWD.
+enter_caller_dir() {
+    cd "${MISE_ORIGINAL_CWD:-$PWD}"
+}
+
+sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum | cut -d' ' -f1
+    else
+        shasum -a 256 | cut -d' ' -f1
+    fi
+}
+
+# Each repository runs these tasks from its own node_modules, so traefik.yml is
+# copied to a fixed path before mounting it. Mounting it from node_modules would
+# change the container config with every repository and recreate the proxy.
+TELA_PROXY_STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/tela-proxy"
+
+# Starts from several repositories can run at once and touch the same network,
+# config file and container. mkdir is atomic and works the same on Linux and
+# macOS, which has no flock.
+TELA_PROXY_LOCK_DIR="$TELA_PROXY_STATE_DIR/lock"
+TELA_PROXY_LOCK_TIMEOUT_SECONDS=120
+
+acquire_proxy_lock() {
+    mkdir -p "$TELA_PROXY_STATE_DIR"
+    local waited=0
+    until mkdir "$TELA_PROXY_LOCK_DIR" 2>/dev/null; do
+        if [ "$waited" -ge "$TELA_PROXY_LOCK_TIMEOUT_SECONDS" ]; then
+            die "another tela-proxy start has held $TELA_PROXY_LOCK_DIR for ${TELA_PROXY_LOCK_TIMEOUT_SECONDS}s. If no start is running, remove that directory."
+        fi
+        sleep 1
+        waited=$((waited + 1))
+    done
+    trap 'rmdir "$TELA_PROXY_LOCK_DIR" 2>/dev/null || true' EXIT
+}
+
+release_proxy_lock() {
+    rmdir "$TELA_PROXY_LOCK_DIR" 2>/dev/null || true
+    trap - EXIT
+}
+
+proxy_compose() {
+    mkdir -p "$TELA_PROXY_STATE_DIR"
+    if ! cmp -s "$TELA_PROXY_HOME/traefik.yml" "$TELA_PROXY_STATE_DIR/traefik.yml"; then
+        # Replace the file in one rename, so Traefik never reads a partial copy.
+        cp "$TELA_PROXY_HOME/traefik.yml" "$TELA_PROXY_STATE_DIR/traefik.yml.$$"
+        mv "$TELA_PROXY_STATE_DIR/traefik.yml.$$" "$TELA_PROXY_STATE_DIR/traefik.yml"
+    fi
+
+    # The caller's Compose env (a worktree's COMPOSE_PROJECT_NAME, COMPOSE_FILE)
+    # must not leak into the proxy project.
+    TELA_PROXY_CONFIG_HASH="$(cat "$TELA_PROXY_HOME/compose.yaml" "$TELA_PROXY_HOME/traefik.yml" | sha256)" \
+        TELA_PROXY_TRAEFIK_CONFIG="$TELA_PROXY_STATE_DIR/traefik.yml" \
+        env -u COMPOSE_PROJECT_NAME -u COMPOSE_FILE -u COMPOSE_PROFILES \
+        docker compose -p "$TELA_PROXY_PROJECT" -f "$TELA_PROXY_HOME/compose.yaml" "$@"
+}
+
+ensure_network() {
+    docker network inspect "$TELA_PROXY_NETWORK" >/dev/null 2>&1 \
+        || docker network create --driver bridge "$TELA_PROXY_NETWORK" >/dev/null
+}
+
+# Prints the Compose project name for the current directory, honoring
+# COMPOSE_PROJECT_NAME and COMPOSE_FILE from the environment or `.env`, since
+# Compose resolves them itself. Prints nothing when there is no Compose project
+# here. --no-env-resolution keeps a missing env_file from failing the lookup.
+compose_project_name() {
+    # stderr goes to its own file: Compose can warn (an unset variable, an
+    # obsolete `version`) and still succeed, and the warning must not reach jq.
+    local output errors status=0
+    errors="$(mktemp)"
+    output="$(docker compose config --no-env-resolution --format json 2>"$errors")" || status=$?
+    if [ "$status" -eq 0 ]; then
+        rm -f "$errors"
+        jq -r '.name // empty' <<<"$output"
+        return
+    fi
+    output="$(cat "$errors")"
+    rm -f "$errors"
+    case "$output" in
+        *"no configuration file provided"*) return 0 ;;
+    esac
+    die "could not read the Compose project in $(pwd): $output"
+}
+
+# Prints COMPOSE_FILE as Compose sees it: from the environment, else from the
+# `.env` in the current directory.
+compose_file_setting() {
+    if [ -n "${COMPOSE_FILE:-}" ]; then
+        printf '%s\n' "$COMPOSE_FILE"
+    elif [ -f .env ]; then
+        sed -n -E 's/^[[:space:]]*(export[[:space:]]+)?COMPOSE_FILE[[:space:]]*=[[:space:]]*["'\'']?([^"'\'']*)["'\'']?[[:space:]]*$/\2/p' .env | tail -n 1
+    fi
+}
+
+# Prints the Compose project directory for the current directory: the
+# directory of the first COMPOSE_FILE entry, resolved from here, else the
+# nearest ancestor with a default-named file. This is the working_dir label
+# Compose writes on the containers it creates.
+compose_project_dir() {
+    local compose_file first
+    compose_file="$(compose_file_setting)"
+    if [ -n "$compose_file" ]; then
+        first="${compose_file%%"${COMPOSE_PATH_SEPARATOR:-:}"*}"
+        (cd "$(dirname "$first")" && pwd -P)
+        return
+    fi
+
+    local dir name
+    dir="$(pwd -P)"
+    while :; do
+        for name in compose.yaml compose.yml docker-compose.yaml docker-compose.yml; do
+            if [ -f "$dir/$name" ]; then
+                printf '%s\n' "$dir"
+                return
+            fi
+        done
+        [ "$dir" = "/" ] && return
+        dir="$(dirname "$dir")"
+    done
+}
+
+# Fails when containers of this Compose project were started from another
+# directory that still exists: `up` would recreate them and `down -v` would
+# delete their volumes. Containers from a directory that is gone (a removed
+# worktree) only warn, and are taken over.
+check_project_conflict() {
+    local project project_dir
+    project="$(compose_project_name)"
+    [ -n "$project" ] || return 0
+
+    # Compose found a project, so failing to place it must not skip the check.
+    project_dir="$(compose_project_dir)"
+    [ -n "$project_dir" ] \
+        || die "could not find the directory of Compose project '$project' from $(pwd)"
+
+    local dirs other other_real
+    dirs="$(docker ps -a \
+        --filter "label=com.docker.compose.project=$project" \
+        --format '{{ .Label "com.docker.compose.project.working_dir" }}' | sort -u)" \
+        || die "could not list the containers of Compose project '$project'"
+
+    while IFS= read -r other; do
+        [ -n "$other" ] || continue
+        if [ ! -d "$other" ]; then
+            warn "Compose project '$project' has containers from $other, which no longer exists. They will be recreated from $project_dir and keep their volumes."
+            continue
+        fi
+        other_real="$(cd "$other" && pwd -P)"
+        [ "$other_real" = "$project_dir" ] && continue
+        die "Compose project '$project' is already used by $other_real.
+Starting it from $project_dir would recreate those containers and share their volumes.
+Run this checkout under its own project name instead:
+  mise run tela-proxy:worktree [label] -- <command>"
+    done <<< "$dirs"
+}

package/mise/tasks/tela-proxy/stop.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+#MISE description="Stop the shared proxy. It stays stopped across reboots until tela-proxy runs again"
+
+set -euo pipefail
+
+# shellcheck source=lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+proxy_compose stop

package/mise/tasks/tela-proxy/traefik.yml

@@ -0,0 +1,59 @@
+# Static config for the shared local proxy started by `mise run tela-proxy`.
+#
+# Every Compose container on tela-network gets an HTTP route without declaring
+# anything. The host comes from the Compose project and service labels:
+#
+#   service auth-api,  project auth        -> api.auth.localhost
+#   service auth,      project auth        -> auth.localhost
+#   service dashboard, project auth        -> dashboard.auth.localhost
+#   service auth-api,  project auth_feat-x -> api.auth-feat-x.localhost
+#
+# The `_` in a project name separates the base from a worktree label, set by
+# `mise run tela-proxy:worktree`. A container opts out with traefik.enable=false.
+#
+# A tela-proxy.host label replaces the host. `{project}` in it becomes the
+# project's domain, worktree suffix included:
+#
+#   tela-proxy.host: '{project}.localhost',     project auth_feat-x -> auth-feat-x.localhost
+#   tela-proxy.host: 'app.{project}.localhost', project auth        -> app.auth.localhost
+
+entryPoints:
+  web:
+    address: ':80'
+
+providers:
+  docker:
+    network: tela-network
+    exposedByDefault: true
+    defaultRule: |-
+      {{- $project := index .Labels "com.docker.compose.project" -}}
+      {{- $service := index .Labels "com.docker.compose.service" -}}
+      {{- $override := index .Labels "tela-proxy.host" -}}
+      {{- if or (not $project) (not $service) -}}
+        {{- if $override -}}
+          Host(`{{ $override }}`)
+        {{- else -}}
+          Host(`{{ normalize .Name }}.localhost`)
+        {{- end -}}
+      {{- else -}}
+        {{- $parts := splitList "_" $project -}}
+        {{- $base := first $parts -}}
+        {{- /* Every part is kept, so team_app_one and team_app_two stay apart. */ -}}
+        {{- $domain := join "-" $parts -}}
+        {{- $host := printf "%s.%s.localhost" $service $domain -}}
+        {{- if eq $service $base -}}
+          {{- $host = printf "%s.localhost" $domain -}}
+        {{- else if hasPrefix (printf "%s-" $base) $service -}}
+          {{- $host = printf "%s.%s.localhost" (trimPrefix (printf "%s-" $base) $service) $domain -}}
+        {{- end -}}
+        {{- if $override -}}
+          {{- $host = replace "{project}" $domain $override -}}
+        {{- end -}}
+        Host(`{{ $host }}`)
+      {{- end -}}
+
+api:
+  dashboard: true
+
+log:
+  level: INFO

package/mise/tasks/tela-proxy/worktree.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+#MISE description="Run a command, or open a shell, with Compose isolated under a worktree project name"
+#MISE alias=["worktree", "wt"]
+#MISE interactive=true
+#MISE tools={jq="1.8.2"}
+#USAGE arg "[label]" help="Worktree label. Defaults to the name of the current git worktree."
+#USAGE arg "[cmd]..." var=#true double_dash="required" help="Command to run. Opens $SHELL when omitted."
+
+set -euo pipefail
+
+# shellcheck source=lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+enter_caller_dir
+
+# mise passes the label (when given) followed by the command, and a single empty
+# argument when there is neither.
+label="${usage_label:-}"
+if [ -n "$label" ] && [ "${1:-}" = "$label" ]; then
+    shift
+fi
+if [ "$#" -eq 1 ] && [ -z "$1" ]; then
+    shift
+fi
+
+if [ -n "${TELA_PROXY_WORKTREE:-}" ]; then
+    die "already inside worktree '$TELA_PROXY_WORKTREE'. Run commands directly, or exit this shell first."
+fi
+
+if [ -z "$label" ]; then
+    git_dir="$(git rev-parse --absolute-git-dir 2>/dev/null)" \
+        || die "not inside a git repository. Pass a label: mise run tela-proxy:worktree <label>"
+    common_dir="$(cd "$(git rev-parse --git-common-dir)" && pwd -P)"
+    if [ "$(cd "$git_dir" && pwd -P)" = "$common_dir" ]; then
+        die "this is the main checkout, not a linked worktree. Pass a label: mise run tela-proxy:worktree <label>"
+    fi
+    label="$(basename "$(git rev-parse --show-toplevel)")"
+fi
+
+label="$(printf '%s' "$label" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9-]+/-/g; s/-+/-/g; s/^-//; s/-$//')"
+[ -n "$label" ] || die "the worktree label is empty after keeping only a-z, 0-9 and '-'"
+
+base="$(unset COMPOSE_PROJECT_NAME; compose_project_name)"
+[ -n "$base" ] || die "no Compose project found in $(pwd)"
+case "$base" in
+    *_*) die "Compose project name '$base' contains '_', which the proxy uses to separate the worktree label. Rename it with 'name:' in the Compose file." ;;
+esac
+
+export COMPOSE_PROJECT_NAME="${base}_${label}"
+export TELA_LOCAL_DOMAIN="${base}-${label}.localhost"
+export TELA_PROXY_WORKTREE="$label"
+
+check_project_conflict
+
+info "Compose project: $COMPOSE_PROJECT_NAME"
+info "Hosts: http://<service>.$TELA_LOCAL_DOMAIN"
+
+if [ "$#" -gt 0 ]; then
+    exec "$@"
+fi
+
+info "Opening ${SHELL:-bash} for worktree '$label'. Exit it to leave."
+exec "${SHELL:-bash}"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@meistrari/mise-en-place",
-    "version": "2.19.1",
+    "version": "2.21.0",
     "description": "",
     "repository": {
         "type": "git",