scripts/dev-env.sh
Rama main · réplica de lectura del repositorio original.
#!/usr/bin/env bash
# Local development environments as named, listable, deletable objects.
#
# make up # start this checkout's environment (api + web)
# make up C=api,web,daemon # pick the components
# make status # what is running, and is it mine
# make list # every environment on this machine
# make down # stop the processes, keep the data
# make destroy # stop, then delete database + profile + slot
#
# Three rules the old flow got wrong, and why they are here:
#
# 1. Ports, database names and CLI profiles are ALLOCATED under a lock and
# recorded in a registry, not recomputed from cksum($PWD) by every caller.
# Deriving an identity in a 1000-slot namespace with no coordination
# collides, and a collision here is silent: the loser's process fails to
# bind while the winner keeps answering.
# 2. Nothing prints a checkmark for a resource it has not reached the way the
# application reaches it. The database is verified through DATABASE_URL,
# never through `docker exec` — when a native PostgreSQL owns 5432 the
# container never binds the host port, so a docker-exec create lands in a
# server the backend never talks to.
# 3. Creating an environment writes down how to destroy it. Without that
# record there is no destroy, only archaeology; the databases, ports and
# daemons leak, and nothing on the machine can even list them.
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
DEV_HOME="${MULTICA_DEV_HOME:-$HOME/.multica/dev}"
ENVS_DIR="$DEV_HOME/envs"
LOCK_DIR="$DEV_HOME/lock.d"
DEV_WORKSPACES_PARENT="${MULTICA_DEV_WORKSPACES_PARENT:-$HOME}"
DEV_DESKTOP_APP_DATA="${MULTICA_DEV_DESKTOP_APP_DATA:-}"
DEV_PROFILES_HOME="${MULTICA_DEV_PROFILES_HOME:-$HOME/.multica/profiles}"
DEV_EMAIL="${MULTICA_DEV_EMAIL:-dev@localhost}"
DEV_CODE_DEFAULT=888888
WORKSPACE_NAME="${MULTICA_DEV_WORKSPACE_NAME:-Dev}"
WORKSPACE_SLUG="${MULTICA_DEV_WORKSPACE_SLUG:-dev}"
ALL_COMPONENTS="api web daemon desktop"
DEFAULT_COMPONENTS="api web"
# An agent runs with TMPDIR=/tmp/multica-task-<id>, deleted when the run ends.
# Anything the Go toolchain builds there goes with it, so a binary started from
# such a build stops being re-executable the moment its creator finishes.
DEV_TMPDIR="${MULTICA_DEV_TMPDIR:-$HOME/.multica/dev-tmp}"
# The agent runtime exports these pointing at PRODUCTION, and MULTICA_SERVER_URL
# silently outranks server_url in a saved profile config. Every long-lived child
# is launched without them, so a local daemon cannot authenticate its local
# token against the production API — which fails as a bare 401 and reads like a
# product bug. PATH is never stripped: the daemon resolves agent CLI paths by
# forking the login shell.
CLEAN_ENV=(env
-u MULTICA_SERVER_URL -u MULTICA_TOKEN -u MULTICA_WORKSPACE_ID
-u MULTICA_DAEMON_PORT -u MULTICA_AGENT_ID -u MULTICA_AGENT_NAME
-u MULTICA_TASK_ID -u MULTICA_TASK_SLOT
-u MULTICA_TASK_CONFIG_ROOT -u MULTICA_TASK_WORKSPACES_ROOT
-u MULTICA_WORKSPACES_ROOT)
# ---------------------------------------------------------------- output ----
if [ -t 1 ]; then
C_BOLD=$'\033[1m'; C_GREEN=$'\033[32m'; C_RED=$'\033[31m'; C_DIM=$'\033[2m'; C_OFF=$'\033[0m'
else
C_BOLD=""; C_GREEN=""; C_RED=""; C_DIM=""; C_OFF=""
fi
step() { printf '\n%s==> %s%s\n' "$C_BOLD" "$1" "$C_OFF"; }
info() { printf ' %s\n' "$1"; }
ok() { printf ' %s✓%s %s\n' "$C_GREEN" "$C_OFF" "$1"; }
warn() { printf ' %s!%s %s\n' "$C_RED" "$C_OFF" "$1"; }
die() { printf '\n%s✗ %s%s\n' "$C_RED" "$1" "$C_OFF" >&2; exit 1; }
json_escape() {
printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/ /\\t/g'
}
now_iso() { date -u '+%Y-%m-%dT%H:%M:%SZ'; }
now_epoch() { date -u '+%s'; }
expires_at_after_hours() {
node -e '
const hours = Number(process.argv[1]);
process.stdout.write(new Date(Date.now() + hours * 3600_000).toISOString().replace(/\.\d{3}Z$/, "Z"));
' "$1"
}
# ----------------------------------------------------------------- locking ---
# flock is not on a stock macOS, so the lock is an atomic mkdir. The holder's
# pid is recorded so a lock left behind by a killed process is recoverable
# instead of wedging every later command.
acquire_lock() {
local waited=0
mkdir -p "$DEV_HOME"
while ! mkdir "$LOCK_DIR" 2>/dev/null; do
local holder=""
holder="$(cat "$LOCK_DIR/pid" 2>/dev/null || true)"
if [ -n "$holder" ] && ! kill -0 "$holder" 2>/dev/null; then
rm -rf "$LOCK_DIR"
continue
fi
waited=$((waited + 1))
[ "$waited" -lt 100 ] || die "Timed out waiting for the allocation lock at $LOCK_DIR. If nothing else is running, remove it."
sleep 0.1
done
printf '%s\n' "$$" > "$LOCK_DIR/pid"
}
release_lock() { rm -rf "$LOCK_DIR"; }
# ---------------------------------------------------------------- registry ---
env_dir() { printf '%s/%s' "$ENVS_DIR" "$1"; }
manifest_of() { printf '%s/%s/manifest.env' "$ENVS_DIR" "$1"; }
valid_env_name() {
case "$1" in
""|*[!a-z0-9_-]*|-*|_*) return 1 ;;
*) [ "${#1}" -le 128 ] ;;
esac
}
require_env_name() {
valid_env_name "$1" || die "Invalid environment name '$1'. Use 1-128 lowercase letters, numbers, '-' or '_', starting with a letter or number."
}
require_ttl() {
case "$1" in
""|0|*[!0-9]*) die "TTL must be a positive integer number of hours." ;;
esac
}
list_env_names() {
[ -d "$ENVS_DIR" ] || return 0
local path
for path in "$ENVS_DIR"/*/manifest.env; do
[ -f "$path" ] || continue
basename "$(dirname "$path")"
done
return 0
}
# Loads a manifest into NAME/DIR/BACKEND_PORT/... in the caller's scope.
load_manifest() {
local file
require_env_name "$1"
file="$(manifest_of "$1")"
[ -f "$file" ] || return 1
# shellcheck disable=SC1090
. "$file"
[ "$NAME" = "$1" ] || die "Manifest $file declares NAME=$NAME; expected $1."
# Run from an agent task, everything launched for this environment loses the
# task's MULTICA_* identity (CLEAN_ENV) but still sits under the task's
# marker. This tells the CLI why, so its refusal does not call the task's own
# marker a leftover to delete. A human's run exports nothing: a marker in
# their checkout really can be a leftover.
if [ -n "${MULTICA_TASK_ID:-}${MULTICA_AGENT_ID:-}${MULTICA_TASK_CONFIG_ROOT:-}" ]; then
export MULTICA_DEV_ENV="$NAME"
fi
}
# Prints nothing (and succeeds) for a missing manifest or key: callers compare
# the value, and a non-zero return from a command substitution is fatal under
# `set -e` on bash 3.2.
manifest_field() {
local file key=$2
require_env_name "$1"
file="$(manifest_of "$1")"
[ -f "$file" ] || return 0
(
# shellcheck disable=SC1090
. "$file"
case "$key" in
DIR) printf '%s' "$DIR" ;;
OFFSET) printf '%s' "$OFFSET" ;;
DESKTOP_CDP_PORT) printf '%s' "${DESKTOP_CDP_PORT:-}" ;;
*) return 1 ;;
esac
)
}
write_manifest_value() {
printf '%s=' "$1"
printf '%q' "$2"
printf '\n'
}
env_name_for_dir() {
local name
while read -r name; do
[ -n "$name" ] || continue
if [ "$(manifest_field "$name" DIR)" = "$1" ]; then
printf '%s' "$name"
return 0
fi
done <<EOF
$(list_env_names)
EOF
return 1
}
# ------------------------------------------------------------------- ports ---
# -sTCP:LISTEN matters: an unfiltered lsof also returns CLIENTS of the port, and
# the daemon holds a long-lived connection to the backend. Killing what the
# unfiltered lookup returns takes the daemon down with the server (#6573).
#
# The trailing `|| true` is load-bearing on macOS's bash 3.2: `x="$(fn)"` inside
# a function aborts the script under `set -e` when fn's last command fails, and
# "no process is listening" is the normal answer here, not an error.
port_listener_pid() {
lsof -nP -iTCP:"$1" -sTCP:LISTEN -t 2>/dev/null | head -1 || true
}
port_free() { [ -z "$(port_listener_pid "$1")" ]; }
describe_port_owner() {
local pid
pid="$(port_listener_pid "$1")"
[ -n "$pid" ] || { printf 'free'; return; }
printf 'pid %s (%s), up %s' "$pid" \
"$(ps -p "$pid" -o comm= 2>/dev/null | sed 's/^ *//' || echo unknown)" \
"$(ps -p "$pid" -o etime= 2>/dev/null | sed 's/^ *//' || echo unknown)"
}
# -------------------------------------------------------------- allocation ---
slugify() {
local slug
slug="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//')"
printf '%s' "${slug:-env}"
}
path_offset() {
local sum
sum="$(printf '%s' "$1" | cksum | awk '{print $1}')"
printf '%s' $((sum % 1000))
}
renderer_port_for_offset() {
local port=$((5174 + $1))
[ "$port" -ne 6000 ] || port=6174
printf '%s' "$port"
}
desktop_app_data_root() {
if [ -n "$DEV_DESKTOP_APP_DATA" ]; then
printf '%s' "$DEV_DESKTOP_APP_DATA"
return 0
fi
case "$(uname -s)" in
Darwin) printf '%s/Library/Application Support' "$HOME" ;;
MINGW*|MSYS*|CYGWIN*) printf '%s' "${APPDATA:-$HOME/AppData/Roaming}" ;;
*) printf '%s' "${XDG_CONFIG_HOME:-$HOME/.config}" ;;
esac
}
desktop_user_data_dir() {
printf '%s/Multica Canary %s' "$(desktop_app_data_root)" "$1"
}
# Desktop's daemon manager derives its own CLI profile from the backend URL
# (apps/desktop/src/main/daemon-profile.ts), so every managed Desktop that
# signs in owns `desktop-localhost-<backend port>` alongside this environment's
# profile. Its daemon outlives Electron unless something stops it.
desktop_daemon_profile() {
printf 'desktop-localhost-%s' "$BACKEND_PORT"
}
# Chrome's conventional 9222 is left to whatever a human launches by hand.
CDP_PORT_BASE=9223
valid_port() {
case "$1" in
""|*[!0-9]*) return 1 ;;
esac
[ "$1" -ge 1024 ] && [ "$1" -le 65535 ]
}
cdp_port_registered() {
local name
while read -r name; do
[ -n "$name" ] || continue
[ "$name" = "${2:-}" ] && continue
if [ "$(manifest_field "$name" DESKTOP_CDP_PORT)" = "$1" ]; then
return 0
fi
done <<EOF
$(list_env_names)
EOF
return 1
}
allocate_cdp_port() {
local self=$1 start=$2 i port
for i in $(seq 0 999); do
port=$((start + i))
[ "$port" -le 65535 ] || return 1
cdp_port_registered "$port" "$self" && continue
port_free "$port" || continue
printf '%s' "$port"
return 0
done
return 1
}
offset_registered() {
local name
while read -r name; do
[ -n "$name" ] || continue
[ "$name" = "${2:-}" ] && continue
if [ "$(manifest_field "$name" OFFSET)" = "$1" ]; then
return 0
fi
done <<EOF
$(list_env_names)
EOF
return 1
}
# Probes for a usable slot starting at the path hash, so the common case keeps
# the deterministic number a checkout has always had, and only a real conflict
# moves it. A slot is usable when the registry does not hold it AND both ports
# are actually free — the registry alone cannot see a process started before
# this tooling existed.
allocate_offset() {
local dir=$1 self=${2:-} start i offset backend frontend renderer
start="$(path_offset "$dir")"
for i in $(seq 0 999); do
offset=$(((start + i) % 1000))
backend=$((18080 + offset))
frontend=$((13000 + offset))
renderer="$(renderer_port_for_offset "$offset")"
offset_registered "$offset" "$self" && continue
port_free "$backend" || continue
port_free "$frontend" || continue
port_free "$renderer" || continue
printf '%s' "$offset"
return 0
done
return 1
}
# ---------------------------------------------------------------- env file ---
detect_env_file() {
if [ -f "$REPO_ROOT/.env" ]; then
printf '.env'
elif [ -f "$REPO_ROOT/.env.worktree" ]; then
printf '.env.worktree'
elif [ -f "$REPO_ROOT/.git" ] && [ ! -d "$REPO_ROOT/.git" ]; then
printf '.env.worktree'
else
printf '.env'
fi
}
load_env_file() {
local root="${2:-$REPO_ROOT}"
set -a
# shellcheck disable=SC1090
. "$root/$1"
set +a
# shellcheck disable=SC1091
. "$root/scripts/local-env.sh"
}
# The verification code has to be in the file BEFORE the backend starts: the
# handler reads the variable at request time, but the process loads the file
# once. Setting it here removes the start → edit → restart detour, and is what
# makes `up` able to log itself in without a human reading a log for a code.
ensure_dev_code() {
local file="$REPO_ROOT/$1" tmp
if grep -qE '^MULTICA_DEV_VERIFICATION_CODE=[0-9]{6}$' "$file"; then
return 0
fi
if grep -q '^MULTICA_DEV_VERIFICATION_CODE=' "$file"; then
tmp="$(mktemp)"
sed "s/^MULTICA_DEV_VERIFICATION_CODE=.*/MULTICA_DEV_VERIFICATION_CODE=$DEV_CODE_DEFAULT/" "$file" > "$tmp"
mv "$tmp" "$file"
else
printf '\nMULTICA_DEV_VERIFICATION_CODE=%s\n' "$DEV_CODE_DEFAULT" >> "$file"
fi
info "Set MULTICA_DEV_VERIFICATION_CODE=$DEV_CODE_DEFAULT in $1 (ignored when APP_ENV=production)."
}
rewrite_env_ports() {
local file="$REPO_ROOT/$1" offset=$2 backend=$3 frontend=$4 db=$5 tmp database_url escaped_database_url
database_url="$(database_url_with_name "${DATABASE_URL:-}" "$db")" \
|| die "DATABASE_URL is not a valid PostgreSQL URL: ${DATABASE_URL:-<unset>}"
escaped_database_url="$(printf '%s' "$database_url" | sed 's/[\\&|]/\\&/g')"
tmp="$(mktemp)"
sed \
-e "s|^PORT=.*|PORT=${backend}|" \
-e "s|^FRONTEND_PORT=.*|FRONTEND_PORT=${frontend}|" \
-e "s|^FRONTEND_ORIGIN=.*|FRONTEND_ORIGIN=http://localhost:${frontend}|" \
-e "s|^POSTGRES_DB=.*|POSTGRES_DB=${db}|" \
-e "s|^DATABASE_URL=.*|DATABASE_URL=${escaped_database_url}|" \
-e "s|^MULTICA_SERVER_URL=.*|MULTICA_SERVER_URL=ws://localhost:${backend}/ws|" \
-e "s|^MULTICA_PUBLIC_URL=.*|MULTICA_PUBLIC_URL=http://localhost:${backend}|" \
-e "s|^MULTICA_APP_URL=.*|MULTICA_APP_URL=http://localhost:${frontend}|" \
-e "s|^NEXT_PUBLIC_API_URL=.*|NEXT_PUBLIC_API_URL=http://localhost:${backend}|" \
-e "s|^NEXT_PUBLIC_WS_URL=.*|NEXT_PUBLIC_WS_URL=ws://localhost:${backend}/ws|" \
"$file" > "$tmp"
mv "$tmp" "$file"
}
# ---------------------------------------------------------------- database ---
admin_database_url() {
node -e '
const url = new URL(process.argv[1]);
url.pathname = "/postgres";
process.stdout.write(url.toString());
' "$1" 2>/dev/null || true
}
database_url_with_name() {
node -e '
const url = new URL(process.argv[1]);
if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") process.exit(1);
url.pathname = "/" + process.argv[2];
process.stdout.write(url.toString());
' "$1" "$2" 2>/dev/null
}
# Diagnoses the failure mode this whole script exists to make impossible:
# something other than the container owns 5432, so the container never bound
# the host port and a docker-exec create landed in the wrong server.
diagnose_database() {
local owner
owner="$(lsof -nP -iTCP:"${POSTGRES_PORT:-5432}" -sTCP:LISTEN 2>/dev/null | awk 'NR==2 {print $1" (pid "$2", user "$3")"}')"
printf '\n'
warn "The database the tooling created is not the one the application reaches."
info "Port ${POSTGRES_PORT:-5432} is served by: ${owner:-nothing}"
info "DATABASE_URL: ${DATABASE_URL}"
info "If that is a native PostgreSQL, the Docker container never bound the host port."
info "Either stop it (brew services stop postgresql@17) or point DATABASE_URL at it."
}
ensure_database() {
local admin_url=""
if command -v psql >/dev/null 2>&1 && [ -n "${DATABASE_URL:-}" ]; then
admin_url="$(admin_database_url "$DATABASE_URL")"
fi
# Preferred path: create through the same connection string the application
# uses, so "created" and "reachable" cannot describe two different servers.
if [ -n "$admin_url" ] && PGCONNECT_TIMEOUT=3 psql "$admin_url" -tAc 'SELECT 1' >/dev/null 2>&1; then
if ! PGCONNECT_TIMEOUT=3 psql "$admin_url" -tAc "SELECT 1 FROM pg_database WHERE datname='${POSTGRES_DB}'" | grep -q 1; then
psql "$admin_url" -v ON_ERROR_STOP=1 -c "CREATE DATABASE \"${POSTGRES_DB}\"" >/dev/null
info "Created database ${POSTGRES_DB} through DATABASE_URL."
fi
else
info "Nothing is answering on ${POSTGRES_PORT:-5432} yet; starting the shared container."
bash "$REPO_ROOT/scripts/ensure-postgres.sh" "$ENV_FILE" | sed 's/^/ /'
fi
}
migrate_database() {
# `migrate up` connects with DATABASE_URL and pings before doing anything, so
# a successful run is the proof that the application can reach the database
# this script just prepared. That is why nothing above prints a checkmark.
if ! (cd "$REPO_ROOT/server" && go run ./cmd/migrate up) > "$LOG_DIR/migrate.log" 2>&1; then
tail -5 "$LOG_DIR/migrate.log" | sed 's/^/ /' >&2 || true
if grep -q '3D000\|does not exist' "$LOG_DIR/migrate.log"; then
diagnose_database
fi
die "Migrations failed. Full log: $LOG_DIR/migrate.log"
fi
}
# -------------------------------------------------------------- components ---
component_selected() {
case " $COMPONENTS " in *" $1 "*) return 0 ;; *) return 1 ;; esac
}
pid_file() { printf '%s/%s.pid' "$STATE_DIR" "$1"; }
listener_pid_file() { printf '%s/%s.listener.pid' "$STATE_DIR" "$1"; }
log_file() { printf '%s/%s.log' "$LOG_DIR" "$1"; }
component_pid() {
local file
file="$(pid_file "$1")"
[ -f "$file" ] || return 1
local pid
pid="$(cat "$file")"
kill -0 "$pid" 2>/dev/null || return 1
printf '%s' "$pid"
}
# set -m puts the launcher in its own process group, so stopping can signal the
# whole tree (make → go run → server) with one kill, and the child's own
# `trap 'kill 0'` can never reach back into this shell.
launch_detached() {
local name=$1
shift
(
set -m
nohup "${CLEAN_ENV[@]}" "$@" > "$(log_file "$name")" 2>&1 < /dev/null &
printf '%s\n' "$!" > "$(pid_file "$name")"
)
}
health_json() { curl -sf --max-time 3 "http://localhost:${BACKEND_PORT}/health" 2>/dev/null; }
json_field() {
node -e '
let payload;
try { payload = JSON.parse(process.argv[1]); } catch { process.exit(1); }
const value = process.argv[2].split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), payload);
if (value === undefined || value === null || value === "") process.exit(1);
process.stdout.write(String(value));
' "$1" "$2" 2>/dev/null
}
api_started_after() {
local started_at epoch
started_at="$(json_field "$1" started_at || true)"
[ -n "$started_at" ] || return 1
epoch="$(node -e 'process.stdout.write(String(Math.floor(Date.parse(process.argv[1]) / 1000)))' "$started_at" 2>/dev/null || echo 0)"
[ "$epoch" -ge $(($2 - 5)) ]
}
checkout_commit() {
git -C "${DIR:-$REPO_ROOT}" rev-parse --short HEAD 2>/dev/null || printf 'unknown'
}
process_group_id() {
ps -p "$1" -o pgid= 2>/dev/null | tr -d ' ' || true
}
process_parent_id() {
ps -p "$1" -o ppid= 2>/dev/null | tr -d ' ' || true
}
# Every live descendant of a launcher, read from one process-table snapshot.
# Turbo runs a task in its own process group, so a group kill of the launcher
# reaches turbo but not electron-vite or Electron below it; they are found
# here, while the launcher still anchors their PPID chain.
descendant_pids() {
[ -n "$1" ] || return 0
ps -axo pid=,ppid= 2>/dev/null | awk -v root="$1" '
{ parent[$1] = $2; order[NR] = $1 }
END {
keep[root] = 1
do {
changed = 0
for (i = 1; i <= NR; i++) {
pid = order[i]
if (!(pid in keep) && (parent[pid] in keep)) { keep[pid] = 1; changed = 1 }
}
} while (changed)
for (pid in keep) if (pid != root) print pid
}' || true
}
# Package runners may put a descendant in a nested process group (for example,
# Turbo does this before Next binds its port). Follow PPIDs so ownership still
# comes from the launcher tree instead of accepting a weaker command/user match.
process_is_descendant_of() {
local pid=$1 ancestor=$2 parent depth=0
[ -n "$pid" ] && [ -n "$ancestor" ] || return 1
while [ "$depth" -lt 64 ]; do
[ "$pid" = "$ancestor" ] && return 0
[ "$pid" != 1 ] || return 1
parent="$(process_parent_id "$pid")"
[ -n "$parent" ] && [ "$parent" != "$pid" ] || return 1
pid="$parent"
depth=$((depth + 1))
done
return 1
}
listener_pid_belongs_to_component() {
local component=$1 listener=$2 launcher recorded
launcher="$(component_pid "$component" || true)"
[ -n "$launcher" ] && [ -n "$listener" ] || return 1
recorded="$(cat "$(listener_pid_file "$component")" 2>/dev/null || true)"
[ -n "$recorded" ] && [ "$listener" = "$recorded" ] && return 0
[ "$(process_group_id "$listener")" = "$launcher" ] && return 0
process_is_descendant_of "$listener" "$launcher"
}
listener_belongs_to_component() {
local component=$1 port=$2 listener
listener="$(port_listener_pid "$port")"
listener_pid_belongs_to_component "$component" "$listener"
}
# Persist only listeners whose live process tree proves component ownership.
# stop_component can then clean up a nested process group after its launcher has
# exited and the listener has been reparented.
record_component_listener() {
local component=$1 port=$2 listener
listener="$(port_listener_pid "$port")"
listener_pid_belongs_to_component "$component" "$listener" || return 1
printf '%s\n' "$listener" > "$(listener_pid_file "$component")"
printf '%s' "$listener"
}
health_belongs_to_api() {
local health=$1 health_pid listener
health_pid="$(json_field "$health" pid || true)"
listener="$(port_listener_pid "$BACKEND_PORT")"
[ -n "$health_pid" ] && [ "$health_pid" = "$listener" ] \
&& listener_belongs_to_component api "$BACKEND_PORT"
}
api_identity_matches() {
local health=$1 expected_commit=$2 launched_at=${3:-0} reported_commit started_at
health_belongs_to_api "$health" || return 1
reported_commit="$(json_field "$health" commit || true)"
started_at="$(json_field "$health" started_at || true)"
[ -n "$started_at" ] && [ "$reported_commit" = "$expected_commit" ] || return 1
[ "$launched_at" = 0 ] || api_started_after "$health" "$launched_at"
}
start_api() {
local launched_at health waited=0 expected_commit
expected_commit="$(checkout_commit)"
if health="$(health_json)" && [ -n "$health" ] && component_pid api >/dev/null; then
if api_identity_matches "$health" "$expected_commit"; then
record_component_listener api "$BACKEND_PORT" >/dev/null \
|| die "The API listener changed while its identity was being verified. Refusing to reuse it."
ok "api already running on :$BACKEND_PORT (pid $(json_field "$health" pid), commit $expected_commit)"
return 0
fi
if health_belongs_to_api "$health"; then
warn "api on :$BACKEND_PORT is ours but not commit $expected_commit; restarting it."
stop_component api
else
die "Port $BACKEND_PORT answers /health, but its pid/commit does not match this environment. Refusing to reuse or kill it."
fi
fi
if ! port_free "$BACKEND_PORT"; then
die "Port $BACKEND_PORT is busy: $(describe_port_owner "$BACKEND_PORT").
Run 'make down' here first — a leftover instance answers /health with 200 and you would test it instead of your build."
fi
launched_at="$(now_epoch)"
launch_detached api make -C "$REPO_ROOT" -s api-dev ENV_FILE="$ENV_FILE"
info "api launching (pid $(cat "$(pid_file api)")), log: $(log_file api)"
while [ "$waited" -lt 300 ]; do
health="$(health_json || true)"
if [ -n "$health" ]; then
# A 200 is not enough: pid, process group, commit and launch time all have
# to identify the process this environment just started.
if ! api_identity_matches "$health" "$expected_commit" "$launched_at"; then
stop_component api
die "Something else is serving :$BACKEND_PORT, or the launched api did not report pid/commit/started_at for commit $expected_commit."
fi
if ! record_component_listener api "$BACKEND_PORT" >/dev/null; then
stop_component api
die "The API listener changed while its identity was being recorded."
fi
ok "api healthy at http://localhost:$BACKEND_PORT (pid $(json_field "$health" pid), commit $expected_commit)"
return 0
fi
component_pid api >/dev/null || { tail -20 "$(log_file api)" | sed 's/^/ /' >&2; die "api exited during startup. Log: $(log_file api)"; }
sleep 2
waited=$((waited + 2))
done
die "api never became healthy. Log: $(log_file api)"
}
# Next compiles routes on demand and holds `/` until the compile finishes, which
# after a file change can take longer than one probe. Our own listener gets the
# same 300s a fresh launch does before it counts as hung.
wait_for_owned_web() {
local deadline
deadline=$(($(now_epoch) + 300))
curl -sf --max-time 15 "http://localhost:${FRONTEND_PORT}" >/dev/null 2>&1 && return 0
info "web on :$FRONTEND_PORT is ours but not answering yet (likely compiling); waiting for it."
while [ "$(now_epoch)" -lt "$deadline" ]; do
listener_belongs_to_component web "$FRONTEND_PORT" || return 1
sleep 2
curl -sf --max-time 15 "http://localhost:${FRONTEND_PORT}" >/dev/null 2>&1 && return 0
done
return 1
}
start_web() {
local waited=0 listener
if listener_belongs_to_component web "$FRONTEND_PORT"; then
if wait_for_owned_web; then
listener="$(record_component_listener web "$FRONTEND_PORT" || true)"
if [ -n "$listener" ]; then
ok "web already running on :$FRONTEND_PORT (pid $listener)"
return 0
fi
elif listener_belongs_to_component web "$FRONTEND_PORT"; then
warn "web on :$FRONTEND_PORT is ours but did not answer within 300s; restarting it."
stop_component web
fi
fi
if ! port_free "$FRONTEND_PORT"; then
die "Port $FRONTEND_PORT is busy: $(describe_port_owner "$FRONTEND_PORT"). Run 'make down' here first."
fi
launch_detached web make -C "$REPO_ROOT" -s web-dev ENV_FILE="$ENV_FILE"
info "web launching (pid $(cat "$(pid_file web)")), log: $(log_file web)"
while [ "$waited" -lt 300 ]; do
if curl -sf --max-time 15 "http://localhost:${FRONTEND_PORT}" >/dev/null 2>&1; then
listener="$(record_component_listener web "$FRONTEND_PORT" || true)"
if [ -z "$listener" ]; then
stop_component web
die "Web on :$FRONTEND_PORT is not descended from the process this environment launched."
fi
ok "web serving http://localhost:$FRONTEND_PORT (pid ${listener:-?})"
return 0
fi
component_pid web >/dev/null || { tail -20 "$(log_file web)" | sed 's/^/ /' >&2; die "web exited during startup. Log: $(log_file web)"; }
sleep 2
waited=$((waited + 2))
done
die "web never came up. Log: $(log_file web)"
}
# send-code once, verify-code once. Repeated verify attempts lock the code out
# and start returning 400 even when it is correct, so retrying is self-defeating.
write_profile_config() {
local config=$1 pat=$2 ws=$3
mkdir -p "$PROFILE_DIR"
cat > "$config" <<EOF
{
"server_url": "http://localhost:${BACKEND_PORT}",
"app_url": "http://localhost:${FRONTEND_PORT}",
"token": "$(json_escape "$pat")",
"workspace_id": "$(json_escape "$ws")",
"workspaces_root": "$(json_escape "$WORKSPACES_ROOT")"
}
EOF
chmod 600 "$config"
}
ensure_credentials() {
local server="http://localhost:${BACKEND_PORT}" config="$PROFILE_DIR/config.json"
local code="${MULTICA_DEV_VERIFICATION_CODE:-$DEV_CODE_DEFAULT}"
local verify jwt pat ws
if [ -f "$config" ]; then
pat="$(json_field "$(cat "$config")" token || true)"
ws="$(json_field "$(cat "$config")" workspace_id || true)"
if [ -n "$pat" ] && curl -sf --max-time 5 "$server/api/me" -H "Authorization: Bearer $pat" >/dev/null 2>&1; then
WORKSPACE_ID="$ws"
DEV_TOKEN="$pat"
write_profile_config "$config" "$pat" "$ws"
ensure_onboarded
ok "CLI profile $PROFILE already authenticated"
return 0
fi
fi
curl -sf -X POST "$server/auth/send-code" -H 'Content-Type: application/json' \
-d "{\"email\":\"${DEV_EMAIL}\"}" >/dev/null \
|| die "send-code failed. Is MULTICA_DEV_VERIFICATION_CODE set and APP_ENV non-production?"
verify="$(curl -sS -X POST "$server/auth/verify-code" -H 'Content-Type: application/json' \
-d "{\"email\":\"${DEV_EMAIL}\",\"code\":\"${code}\"}")"
jwt="$(json_field "$verify" token || true)"
[ -n "$jwt" ] || die "verify-code failed: $verify
Do not retry immediately — repeated attempts lock the code. Wait ~40s and re-run."
local pat_response
pat_response="$(curl -sS -X POST "$server/api/tokens" -H "Authorization: Bearer $jwt" \
-H 'Content-Type: application/json' -d '{"name":"dev-env","expires_in_days":365}')"
pat="$(json_field "$pat_response" token || true)"
[ -n "$pat" ] || die "Personal access token creation failed: $pat_response"
local ws_response
ws_response="$(curl -sS -X POST "$server/api/workspaces" -H "Authorization: Bearer $pat" \
-H 'Content-Type: application/json' \
-d "{\"name\":\"${WORKSPACE_NAME}\",\"slug\":\"${WORKSPACE_SLUG}\"}")"
ws="$(json_field "$ws_response" id || true)"
if [ -z "$ws" ]; then
ws="$(node -e '
let list;
try { list = JSON.parse(process.argv[1]); } catch { process.exit(1); }
const match = (Array.isArray(list) ? list : []).find(w => w.slug === process.argv[2]);
if (!match) process.exit(1);
process.stdout.write(match.id);
' "$(curl -sS "$server/api/workspaces" -H "Authorization: Bearer $pat")" "$WORKSPACE_SLUG" 2>/dev/null || true)"
fi
[ -n "$ws" ] || die "Workspace creation failed: $ws_response"
write_profile_config "$config" "$pat" "$ws"
WORKSPACE_ID="$ws"
DEV_TOKEN="$pat"
ensure_onboarded
ok "Logged in as $DEV_EMAIL and wrote profile $PROFILE"
}
# A fresh user has onboarded_at = NULL and a browser login is bounced to
# /onboarding, so the URL this script prints would not land in the app. The
# server keeps the first completion time, so repeating this is harmless.
ensure_onboarded() {
curl -sf --max-time 5 -X POST "http://localhost:${BACKEND_PORT}/api/me/onboarding/complete" \
-H "Authorization: Bearer $DEV_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
-d "{\"completion_path\":\"skip_existing\",\"workspace_id\":\"$(json_escape "$WORKSPACE_ID")\"}" \
>/dev/null || warn "could not mark $DEV_EMAIL onboarded; the browser may open /onboarding"
}
# Every component set gets the same signed-in, onboarded workspace with issues
# in it: Web, Playwright and scripts/dev-fixtures.mjs all start from the profile
# token, and Desktop and the daemon sign in with it.
seed_dev_workspace() {
ensure_credentials
ensure_fixture_issues
}
# A fresh workspace has no issues, so neither an issue page nor the dedicated
# issue window has anything to open. Two are created once; a workspace that
# already holds any issue is left as it is.
ensure_fixture_issues() {
local server="http://localhost:${BACKEND_PORT}" list total entry status title
list="$(curl -sf --max-time 5 "$server/api/issues?limit=1" \
-H "Authorization: Bearer $DEV_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" || true)"
total="$(json_field "$list" total || true)"
if [ -z "$total" ]; then
warn "could not list issues in workspace $WORKSPACE_SLUG; skipped the issue fixture"
return 0
fi
[ "$total" = 0 ] || return 0
for entry in "todo|Fixture: issue list and board" "in_progress|Fixture: dedicated issue window"; do
status="${entry%%|*}"
title="${entry#*|}"
curl -sf --max-time 5 -X POST "$server/api/issues" \
-H "Authorization: Bearer $DEV_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
-d "{\"title\":\"$title\",\"status\":\"$status\",\"priority\":\"medium\",\"description\":\"Seeded by scripts/dev-env.sh so issue views have content.\"}" \
>/dev/null || { warn "failed to create fixture issue '$title'"; return 0; }
done
ok "seeded 2 issues in workspace $WORKSPACE_SLUG"
}
# Under a daemon-task marker the CLI refuses daemon commands for every profile
# except one this registry assigns to an environment, reached without the task's
# identity and pointed at that environment's API — exactly how CLEAN_ENV and
# the profile written above launch it (server/cmd/multica/dev_env_profile.go).
start_daemon() {
local status state build_commit
# Built, never `go run`: the daemon records its own executable path at startup
# and re-execs it as the execution-environment helper for every task. Under
# `go run` the toolchain deletes that binary when the launcher exits, so the
# daemon registers, heartbeats, and then fails every task with
# "fork/exec .../go-build.../exe/multica: no such file or directory".
info "Building $MULTICA_BIN (a go run daemon would fail every task later)."
build_commit="$(git -C "$REPO_ROOT" rev-parse HEAD 2>/dev/null || printf 'unknown')"
(cd "$REPO_ROOT/server" && go build -ldflags "-X main.buildCommit=$build_commit" -o bin/multica ./cmd/multica) || die "Failed to build the multica CLI."
"${CLEAN_ENV[@]}" MULTICA_WORKSPACES_ROOT="$WORKSPACES_ROOT" \
"$MULTICA_BIN" daemon start --profile "$PROFILE" 2>&1 | sed 's/^/ /' || true
status="$("${CLEAN_ENV[@]}" MULTICA_WORKSPACES_ROOT="$WORKSPACES_ROOT" \
"$MULTICA_BIN" daemon status --profile "$PROFILE" --output json 2>/dev/null || true)"
state="$(json_field "$status" status || echo unknown)"
# `daemon status` reports "stopped" plus port_conflict when the daemon
# answering this profile's health port belongs to another profile, so a
# collision can never be read here as a healthy daemon.
if [ "$state" != running ]; then
if [ -n "$(json_field "$status" port_conflict.profile || true)" ]; then
die "The health port for $PROFILE is served by profile $(json_field "$status" port_conflict.profile). Rename one of them."
fi
die "Daemon is '$state' after start. Log: $PROFILE_DIR/daemon.log"
fi
ok "daemon running for profile $PROFILE (pid $(json_field "$status" pid || echo '?'))"
}
start_desktop() {
local waited=0 listener stable_listener
if component_pid desktop >/dev/null \
&& curl -sf --max-time 10 "http://localhost:${DESKTOP_RENDERER_PORT}" >/dev/null 2>&1 \
&& listener_belongs_to_component desktop "$DESKTOP_RENDERER_PORT" \
&& desktop_env_matches \
&& [ "${DESKTOP_CDP_CHANGED:-0}" != 1 ] && desktop_cdp_ready; then
listener="$(record_component_listener desktop "$DESKTOP_RENDERER_PORT" || true)"
[ -n "$listener" ] || die "The Desktop listener changed while its identity was being recorded."
ok "desktop already running (pid $(component_pid desktop), renderer $listener on :$DESKTOP_RENDERER_PORT$(desktop_cdp_suffix))"
return 0
fi
if component_pid desktop >/dev/null; then
warn "desktop launcher exists but its renderer/backend/CDP identity is stale; restarting it."
stop_component desktop
fi
if ! port_free "$DESKTOP_RENDERER_PORT"; then
die "Desktop renderer port $DESKTOP_RENDERER_PORT is busy: $(describe_port_owner "$DESKTOP_RENDERER_PORT")."
fi
if [ -n "$DESKTOP_CDP_PORT" ] && ! port_free "$DESKTOP_CDP_PORT"; then
die "Desktop CDP port $DESKTOP_CDP_PORT is busy: $(describe_port_owner "$DESKTOP_CDP_PORT"). Pick another with --remote-debugging-port N."
fi
write_desktop_env_file
# Desktop's main process delivers MULTICA_DEV_AUTH_TOKEN to the renderer the
# way a browser login's deep link does, so the session is stored exactly as
# it is for a human. electron-vite turns REMOTE_DEBUGGING_PORT into
# --remote-debugging-port; turbo.json passes both through to the dev task.
local launch_env=(env
DESKTOP_RENDERER_PORT="$DESKTOP_RENDERER_PORT" DESKTOP_APP_SUFFIX="$DESKTOP_APP_SUFFIX"
MULTICA_DEV_AUTH_TOKEN="$DEV_TOKEN")
[ -z "$DESKTOP_CDP_PORT" ] || launch_env+=(REMOTE_DEBUGGING_PORT="$DESKTOP_CDP_PORT")
launch_detached desktop "${launch_env[@]}" \
make -C "$REPO_ROOT" -s desktop-dev ENV_FILE="$ENV_FILE"
while [ "$waited" -lt 300 ]; do
if curl -sf --max-time 10 "http://localhost:${DESKTOP_RENDERER_PORT}" >/dev/null 2>&1; then
listener="$(port_listener_pid "$DESKTOP_RENDERER_PORT")"
if ! listener_pid_belongs_to_component desktop "$listener" || ! desktop_env_matches; then
stop_component desktop
die "Desktop renderer on :$DESKTOP_RENDERER_PORT does not belong to this environment."
fi
# Electron can bring Vite up and then crash during renderer bootstrap.
# Require a short stable window before the environment claims readiness.
sleep 5
stable_listener="$(port_listener_pid "$DESKTOP_RENDERER_PORT")"
if ! component_pid desktop >/dev/null || [ "$stable_listener" != "$listener" ] \
|| ! curl -sf --max-time 10 "http://localhost:${DESKTOP_RENDERER_PORT}" >/dev/null 2>&1; then
tail -20 "$(log_file desktop)" | sed 's/^/ /' >&2 || true
stop_component desktop
die "desktop exited during renderer bootstrap. Log: $(log_file desktop)"
fi
printf '%s\n' "$listener" > "$(listener_pid_file desktop)"
# Vite answers before electron-vite has built main and started Electron,
# so the CDP endpoint is the proof that the app itself is up.
while ! desktop_cdp_ready; do
if ! component_pid desktop >/dev/null || [ "$waited" -ge 300 ]; then
tail -20 "$(log_file desktop)" | sed 's/^/ /' >&2 || true
stop_component desktop
die "Desktop never served CDP on :$DESKTOP_CDP_PORT from its own process tree. Log: $(log_file desktop)"
fi
sleep 2
waited=$((waited + 2))
done
ok "desktop ready (launcher $(component_pid desktop), renderer pid ${listener:-?}, backend :$BACKEND_PORT$(desktop_cdp_suffix))"
return 0
fi
component_pid desktop >/dev/null \
|| { tail -20 "$(log_file desktop)" | sed 's/^/ /' >&2; die "desktop exited during startup. Log: $(log_file desktop)"; }
sleep 2
waited=$((waited + 2))
done
stop_component desktop
die "desktop renderer never became ready on :$DESKTOP_RENDERER_PORT. Log: $(log_file desktop)"
}
# The marker makes destroy remove only a file this tool owns. Explicit
# renderer/app values bind Desktop to the registry allocation rather than
# independently hashing the checkout path again.
write_desktop_env_file() {
cat > "$DESKTOP_ENV_FILE" <<EOF
# Managed by scripts/dev-env.sh for environment ${NAME}.
VITE_API_URL=http://localhost:${BACKEND_PORT}
VITE_WS_URL=ws://localhost:${BACKEND_PORT}/ws
VITE_APP_URL=http://localhost:${FRONTEND_PORT}
EOF
}
desktop_env_file_managed() {
grep -q '^# Managed by scripts/dev-env.sh for environment ' "$DESKTOP_ENV_FILE" 2>/dev/null
}
# Every environment owns a Desktop slot, so `up` without the desktop component
# still points the file at this backend: a Desktop started later through
# env-exec otherwise talks to a backend that no longer exists. A file someone
# wrote by hand is left alone unless the desktop component is selected.
sync_desktop_env_file() {
if [ ! -f "$DESKTOP_ENV_FILE" ] || desktop_env_file_managed; then
desktop_env_matches || { write_desktop_env_file; info "Desktop env file → backend :$BACKEND_PORT"; }
else
info "Left $DESKTOP_ENV_FILE alone: it was not written by this tool."
fi
}
desktop_env_matches() {
[ -f "$DESKTOP_ENV_FILE" ] \
&& grep -Fqx "# Managed by scripts/dev-env.sh for environment ${NAME}." "$DESKTOP_ENV_FILE" \
&& grep -Fqx "VITE_API_URL=http://localhost:${BACKEND_PORT}" "$DESKTOP_ENV_FILE" \
&& grep -Fqx "VITE_WS_URL=ws://localhost:${BACKEND_PORT}/ws" "$DESKTOP_ENV_FILE" \
&& grep -Fqx "VITE_APP_URL=http://localhost:${FRONTEND_PORT}" "$DESKTOP_ENV_FILE"
}
desktop_cdp_ready() {
[ -n "${DESKTOP_CDP_PORT:-}" ] || return 0
curl -sf --max-time 5 "http://127.0.0.1:${DESKTOP_CDP_PORT}/json/version" >/dev/null 2>&1 \
&& listener_belongs_to_component desktop "$DESKTOP_CDP_PORT"
}
desktop_cdp_suffix() {
[ -z "${DESKTOP_CDP_PORT:-}" ] || printf ', CDP :%s' "$DESKTOP_CDP_PORT"
}
# Electron does not stop the daemon it started when it quits (autoStop is off
# by default), and that daemon talks to this environment's backend only.
# A plain `daemon stop` exits 0 while the daemon is still finishing a run;
# --force waits for the profile lock, escalates, and confirms cleanup. The pid
# is checked again because the profile directory holding it is deleted next.
stop_desktop_daemon() {
local profile pid bin
profile="$(desktop_daemon_profile)"
pid="$(cat "$DEV_PROFILES_HOME/$profile/daemon.pid" 2>/dev/null || true)"
[ -n "$pid" ] && kill -0 "$pid" 2>/dev/null || return 0
bin="$MULTICA_BIN"
[ -x "$bin" ] || bin="$DIR/apps/desktop/resources/bin/multica"
if [ -x "$bin" ] && "${CLEAN_ENV[@]}" "$bin" daemon stop --force --profile "$profile" >/dev/null 2>&1 \
&& ! kill -0 "$pid" 2>/dev/null; then
ok "stopped Desktop's daemon for profile $profile"
return 0
fi
warn "Desktop's daemon for profile $profile (pid $pid) is still running"
return 1
}
stop_component() {
local name=$1 pid launcher="" status state recorded_listener="" port="" listener=""
local descendants="" child survivors=""
case "$name" in
daemon)
if [ -x "$MULTICA_BIN" ]; then
if "${CLEAN_ENV[@]}" MULTICA_WORKSPACES_ROOT="$WORKSPACES_ROOT" \
"$MULTICA_BIN" daemon stop --profile "$PROFILE" >/dev/null 2>&1; then
ok "daemon stopped"
else
status="$("${CLEAN_ENV[@]}" MULTICA_WORKSPACES_ROOT="$WORKSPACES_ROOT" \
"$MULTICA_BIN" daemon status --profile "$PROFILE" --output json 2>/dev/null || true)"
state="$(json_field "$status" status || echo stopped)"
if [ "$state" = running ]; then
warn "daemon for profile $PROFILE is still running"
return 1
fi
info "daemon was not running"
fi
else
pid="$(cat "$PROFILE_DIR/daemon.pid" 2>/dev/null || true)"
if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
warn "cannot stop daemon pid $pid because no usable multica binary was found"
return 1
fi
info "daemon skipped (no usable binary and no live profile pid)"
fi
return 0
;;
esac
case "$name" in
api) port="$BACKEND_PORT" ;;
web) port="$FRONTEND_PORT" ;;
desktop) port="$DESKTOP_RENDERER_PORT" ;;
esac
recorded_listener="$(cat "$(listener_pid_file "$name")" 2>/dev/null || true)"
pid="$(component_pid "$name" || true)"
if [ -n "$pid" ]; then
launcher="$pid"
# Capture an older environment's listener before killing the launcher. A
# nested process group may survive that signal and then lose its PPID chain
# when the launcher exits, so it must be proven and recorded first.
if [ -n "$port" ]; then
listener="$(port_listener_pid "$port")"
if [ -n "$listener" ] && listener_pid_belongs_to_component "$name" "$listener"; then
recorded_listener="$listener"
printf '%s\n' "$listener" > "$(listener_pid_file "$name")"
fi
fi
descendants="$(descendant_pids "$pid")"
# Negative pid targets the process group, so make → go run → server all go
# down together instead of leaving the real listener orphaned.
kill -TERM -"$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
sleep 1
if kill -0 "$pid" 2>/dev/null; then
kill -KILL -"$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
sleep 1
fi
if kill -0 "$pid" 2>/dev/null; then
warn "$name launcher pid $pid is still running"
return 1
fi
# Descendants in a nested process group (turbo → electron-vite → Electron)
# survive the group signal and would keep the app window open.
for child in $descendants; do
kill -0 "$child" 2>/dev/null && survivors="$survivors $child"
done
if [ -n "$survivors" ]; then
for child in $survivors; do kill -TERM "$child" 2>/dev/null || true; done
sleep 1
for child in $survivors; do
if kill -0 "$child" 2>/dev/null; then kill -KILL "$child" 2>/dev/null || true; fi
done
sleep 1
for child in $survivors; do
if kill -0 "$child" 2>/dev/null; then
warn "$name descendant pid $child is still running"
return 1
fi
done
info "stopped$survivors left in $name's nested process groups"
fi
rm -f "$(pid_file "$name")"
ok "$name stopped (pid $pid)"
else
rm -f "$(pid_file "$name")"
info "$name was not running"
fi
# A process group kill can miss a nested listener that has reparented away
# from its launcher. Only kill the listener captured above or one still in
# the launcher's direct process group; never infer ownership from the port.
if [ -n "$port" ]; then
listener="$(port_listener_pid "$port")"
if [ -n "$listener" ]; then
if { [ -n "$recorded_listener" ] && [ "$listener" = "$recorded_listener" ]; } \
|| { [ -n "$launcher" ] && [ "$(process_group_id "$listener")" = "$launcher" ]; }; then
kill -TERM "$listener" 2>/dev/null || true
sleep 1
if kill -0 "$listener" 2>/dev/null; then
kill -KILL "$listener" 2>/dev/null || true
sleep 1
fi
if kill -0 "$listener" 2>/dev/null; then
warn "$name listener pid $listener is still running"
return 1
fi
info "released :$port (pid $listener)"
else
warn "left :$port alone: listener pid $listener is not owned by this environment"
fi
fi
fi
rm -f "$(listener_pid_file "$name")"
[ "$name" != desktop ] || stop_desktop_daemon
}
# ------------------------------------------------------------------ status ---
component_state() {
case "$1" in
api)
local health expected_commit reported_commit
health="$(health_json || true)"
expected_commit="$(checkout_commit)"
reported_commit="$(json_field "$health" commit || true)"
if [ -n "$health" ] && api_identity_matches "$health" "$expected_commit"; then
printf 'running|http://localhost:%s|pid %s commit %s started %s' "$BACKEND_PORT" \
"$(json_field "$health" pid || echo '?')" \
"$reported_commit" \
"$(json_field "$health" started_at || echo '?')"
elif [ -n "$health" ] && health_belongs_to_api "$health" \
&& [ "$reported_commit" != "$expected_commit" ]; then
# Same process this environment launched; only the checkout moved on.
# `make up` restarts it, so this is not an external conflict.
printf 'stale|http://localhost:%s|running %s, checkout at %s; run make up to restart' \
"$BACKEND_PORT" "${reported_commit:-?}" "$expected_commit"
elif [ -n "$health" ]; then
printf 'mismatch|http://localhost:%s|health responder is not this checkout/process' "$BACKEND_PORT"
else
printf 'stopped|http://localhost:%s|' "$BACKEND_PORT"
fi
;;
web)
local listener
listener="$(port_listener_pid "$FRONTEND_PORT")"
if [ -z "$listener" ]; then
printf 'stopped|http://localhost:%s|' "$FRONTEND_PORT"
elif ! listener_pid_belongs_to_component web "$listener"; then
printf 'mismatch|http://localhost:%s|listener pid %s is not owned by this environment' \
"$FRONTEND_PORT" "$listener"
elif curl -sf --max-time 10 "http://localhost:${FRONTEND_PORT}" >/dev/null 2>&1; then
printf 'running|http://localhost:%s|pid %s' "$FRONTEND_PORT" "$listener"
else
# Next dev serializes compiles, so a probe can time out behind a slow
# route compile even though the listener is ours.
printf 'busy|http://localhost:%s|pid %s is ours but not responding (likely compiling); re-run make status' \
"$FRONTEND_PORT" "$listener"
fi
;;
daemon)
local status state
if [ -x "$MULTICA_BIN" ]; then
status="$("${CLEAN_ENV[@]}" MULTICA_WORKSPACES_ROOT="$WORKSPACES_ROOT" \
"$MULTICA_BIN" daemon status --profile "$PROFILE" --output json 2>/dev/null || true)"
state="$(json_field "$status" status || echo stopped)"
printf '%s|%s|pid %s' "$state" "$PROFILE" "$(json_field "$status" pid || echo '-')"
else
printf 'stopped|%s|not built' "$PROFILE"
fi
;;
desktop)
local pid
pid="$(component_pid desktop || true)"
if [ -n "$pid" ] \
&& curl -sf --max-time 10 "http://localhost:${DESKTOP_RENDERER_PORT}" >/dev/null 2>&1 \
&& listener_belongs_to_component desktop "$DESKTOP_RENDERER_PORT" \
&& desktop_env_matches && desktop_cdp_ready; then
printf 'running|http://localhost:%s|launcher %s renderer %s%s' \
"$DESKTOP_RENDERER_PORT" "$pid" "$(port_listener_pid "$DESKTOP_RENDERER_PORT")" \
"$( [ -z "${DESKTOP_CDP_PORT:-}" ] || printf ' cdp http://127.0.0.1:%s' "$DESKTOP_CDP_PORT" )"
elif [ -n "$pid" ] || [ -n "$(port_listener_pid "$DESKTOP_RENDERER_PORT")" ]; then
printf 'mismatch|http://localhost:%s|renderer/backend%s identity does not match' "$DESKTOP_RENDERER_PORT" \
"$( [ -z "${DESKTOP_CDP_PORT:-}" ] || printf '/CDP :%s' "$DESKTOP_CDP_PORT" )"
else
printf 'stopped|http://localhost:%s|' "$DESKTOP_RENDERER_PORT"
fi
;;
esac
}
print_status_human() {
local comp state url detail row
printf '\n%s%s%s %s%s%s\n' "$C_BOLD" "$NAME" "$C_OFF" "$C_DIM" "$DIR" "$C_OFF"
printf ' %-9s %-9s %-32s %s\n' COMPONENT STATE ADDRESS DETAIL
for comp in $ALL_COMPONENTS; do
row="$(component_state "$comp")"
state="${row%%|*}"; row="${row#*|}"
url="${row%%|*}"; detail="${row#*|}"
printf ' %-9s %-9s %-32s %s\n' "$comp" "$state" "${url:--}" "${detail:--}"
done
printf ' %-9s %-9s %-32s %s\n' database "$(database_state)" "$DB_NAME" "${DATABASE_URL%%\?*}"
printf '\n owner %s · created %s%s\n' "$OWNER" "$CREATED_AT" "$( [ "${TTL_HOURS:-0}" != 0 ] && printf ' · expires %s' "$EXPIRES_AT" )"
printf ' logs %s\n' "$LOG_DIR"
}
# Reported from the connection string the application uses, so "present" can
# never mean "present in a server nothing talks to".
database_state() {
local admin_url
command -v psql >/dev/null 2>&1 || { printf 'unknown'; return; }
admin_url="$(admin_database_url "$DATABASE_URL")"
PGCONNECT_TIMEOUT=3 psql "$admin_url" -tAc 'SELECT 1' >/dev/null 2>&1 || { printf 'no-server'; return; }
if PGCONNECT_TIMEOUT=3 psql "$admin_url" -tAc "SELECT 1 FROM pg_database WHERE datname='${DB_NAME}'" 2>/dev/null | grep -q 1; then
printf 'present'
else
printf 'missing'
fi
}
print_status_json() {
local comp row state url detail first=1
printf '{"name":"%s","dir":"%s","owner":"%s","created_at":"%s","ttl_hours":%s,"expires_at":"%s",' \
"$(json_escape "$NAME")" "$(json_escape "$DIR")" "$(json_escape "$OWNER")" \
"$(json_escape "$CREATED_AT")" "${TTL_HOURS:-0}" "$(json_escape "$EXPIRES_AT")"
printf '"backend_port":%s,"frontend_port":%s,"desktop_renderer_port":%s,"desktop_cdp_port":%s,"workspace_slug":"%s","database":"%s","profile":"%s","env_file":"%s","logs":"%s","components":{' \
"$BACKEND_PORT" "$FRONTEND_PORT" "$DESKTOP_RENDERER_PORT" "${DESKTOP_CDP_PORT:-null}" \
"$(json_escape "$WORKSPACE_SLUG")" "$(json_escape "$DB_NAME")" "$(json_escape "$PROFILE")" \
"$(json_escape "$ENV_FILE")" "$(json_escape "$LOG_DIR")"
for comp in $ALL_COMPONENTS; do
row="$(component_state "$comp")"
state="${row%%|*}"; row="${row#*|}"
url="${row%%|*}"; detail="${row#*|}"
[ "$first" = 1 ] || printf ','
first=0
printf '"%s":{"state":"%s","address":"%s","detail":"%s"}' \
"$comp" "$(json_escape "$state")" "$(json_escape "$url")" "$(json_escape "$detail")"
done
printf '}}\n'
}
print_handoff() {
local entrypoint
if component_selected web; then
entrypoint="Open http://localhost:${FRONTEND_PORT}/${WORKSPACE_SLUG}/issues"
elif component_selected desktop; then
entrypoint="Desktop renderer http://localhost:${DESKTOP_RENDERER_PORT} → backend :${BACKEND_PORT}"
else
entrypoint="API only http://localhost:${BACKEND_PORT}"
fi
if component_selected desktop; then
entrypoint="${entrypoint}
Desktop signed in as ${DEV_EMAIL}, workspace /${WORKSPACE_SLUG}/issues"
[ -z "${DESKTOP_CDP_PORT:-}" ] || entrypoint="${entrypoint}
CDP http://127.0.0.1:${DESKTOP_CDP_PORT} (chromium.connectOverCDP)"
fi
cat <<EOF
${C_GREEN}✓ Environment ready.${C_OFF}
${entrypoint}
Sign in ${DEV_EMAIL} · code ${MULTICA_DEV_VERIFICATION_CODE:-$DEV_CODE_DEFAULT}
Token profile ${PROFILE} (onboarded, workspace /${WORKSPACE_SLUG})
Fixtures make env-exec ARGS="-- node scripts/dev-fixtures.mjs all"
Backend http://localhost:${BACKEND_PORT} (GET /health reports pid + commit + started_at)
Commit $(git -C "$REPO_ROOT" rev-parse --short HEAD 2>/dev/null || echo unknown)
Environment ${NAME}$( [ "${TTL_HOURS:-0}" != 0 ] && printf ' (expires %s)' "$EXPIRES_AT" )
Inspect make status
Stop make down (keeps the database, restarts in seconds)
Delete make destroy (drops the database and frees the slot)
EOF
}
# ------------------------------------------------------------------- verbs ---
resolve_env_for_read() {
local name="${1:-}"
if [ -z "$name" ]; then
name="$(env_name_for_dir "$REPO_ROOT" || true)"
[ -n "$name" ] || die "No environment registered for $REPO_ROOT. Run 'make up' first."
fi
require_env_name "$name"
load_manifest "$name" || die "Unknown environment '$name'. Run 'make list' to see what exists."
bind_paths
}
bind_paths() {
STATE_DIR="$(env_dir "$NAME")"
LOG_DIR="$STATE_DIR/logs"
PROFILE_DIR="$DEV_PROFILES_HOME/$PROFILE"
WORKSPACES_ROOT="${WORKSPACES_ROOT:-$DEV_WORKSPACES_PARENT/multica_workspaces_$PROFILE}"
DESKTOP_RENDERER_PORT="${DESKTOP_RENDERER_PORT:-$(renderer_port_for_offset "$OFFSET")}"
DESKTOP_APP_SUFFIX="${DESKTOP_APP_SUFFIX:-$NAME}"
DESKTOP_USER_DATA_DIR="${DESKTOP_USER_DATA_DIR:-$(desktop_user_data_dir "$DESKTOP_APP_SUFFIX")}"
DESKTOP_ENV_FILE="${DESKTOP_ENV_FILE:-$DIR/apps/desktop/.env.development.local}"
DESKTOP_CDP_PORT="${DESKTOP_CDP_PORT:-}"
EXPIRES_AT="${EXPIRES_AT:-}"
MULTICA_BIN="$DIR/server/bin/multica"
if [ ! -x "$MULTICA_BIN" ] && [ -x "$REPO_ROOT/server/bin/multica" ]; then
MULTICA_BIN="$REPO_ROOT/server/bin/multica"
fi
mkdir -p "$LOG_DIR"
}
save_manifest() {
{
write_manifest_value NAME "$NAME"
write_manifest_value DIR "$DIR"
write_manifest_value CREATED_AT "$CREATED_AT"
write_manifest_value OWNER "$OWNER"
write_manifest_value TTL_HOURS "$TTL_HOURS"
write_manifest_value EXPIRES_AT "$EXPIRES_AT"
write_manifest_value ENV_FILE "$ENV_FILE"
write_manifest_value OFFSET "$OFFSET"
write_manifest_value BACKEND_PORT "$BACKEND_PORT"
write_manifest_value FRONTEND_PORT "$FRONTEND_PORT"
write_manifest_value DB_NAME "$DB_NAME"
write_manifest_value DATABASE_URL "$DATABASE_URL"
write_manifest_value PROFILE "$PROFILE"
write_manifest_value WORKSPACES_ROOT "$WORKSPACES_ROOT"
write_manifest_value DESKTOP_RENDERER_PORT "$DESKTOP_RENDERER_PORT"
write_manifest_value DESKTOP_APP_SUFFIX "$DESKTOP_APP_SUFFIX"
write_manifest_value DESKTOP_USER_DATA_DIR "$DESKTOP_USER_DATA_DIR"
write_manifest_value DESKTOP_ENV_FILE "$DESKTOP_ENV_FILE"
write_manifest_value DESKTOP_CDP_PORT "${DESKTOP_CDP_PORT:-}"
} > "$(manifest_of "$NAME")"
}
cmd_up() {
local requested="$DEFAULT_COMPONENTS" name="" owner=human ttl=0 lifecycle_requested=0 comp
local cdp_request=""
while [ $# -gt 0 ]; do
case "$1" in
--components|-c) requested="$(printf '%s' "$2" | tr ',' ' ')"; shift 2 ;;
--all) requested="$ALL_COMPONENTS"; shift ;;
--name) name="$2"; shift 2 ;;
--ephemeral) owner=agent; lifecycle_requested=1; [ "$ttl" != 0 ] || ttl=24; shift ;;
--ttl) ttl="$2"; owner=agent; lifecycle_requested=1; shift 2 ;;
--cdp) cdp_request=auto; shift ;;
--remote-debugging-port) cdp_request="${2:-}"; shift 2 ;;
--remote-debugging-port=*) cdp_request="${1#*=}"; shift ;;
--no-cdp) cdp_request=off; shift ;;
*) die "Unknown flag for up: $1" ;;
esac
done
[ -z "$name" ] || require_env_name "$name"
[ "$ttl" = 0 ] || require_ttl "$ttl"
case "$cdp_request" in
""|auto|off) ;;
*) valid_port "$cdp_request" || die "--remote-debugging-port needs a port number between 1024 and 65535." ;;
esac
for comp in $requested; do
case " $ALL_COMPONENTS " in *" $comp "*) ;; *) die "Unknown component '$comp'. Valid: $ALL_COMPONENTS" ;; esac
done
# Changing the port without the desktop component would rewrite the record
# while a running Desktop keeps serving the old port.
case " $requested " in
*" desktop "*) ;;
*) [ -z "$cdp_request" ] \
|| die "--cdp, --remote-debugging-port and --no-cdp need the desktop component (C=desktop)." ;;
esac
# web, daemon and desktop are all clients of the backend; selecting one
# without api would produce an environment that cannot serve a single request.
case " $requested " in *" api "*) ;; *) requested="api $requested" ;; esac
COMPONENTS="$requested"
# No resident cleanup service is required: every future environment start is
# a safe opportunity to collect expired or directory-less environments.
cmd_gc --auto
step "Prerequisites"
local missing=() tool needed="node go curl"
# pnpm is only required by the components that actually build JavaScript, so
# `up C=api` works on a checkout that has never run an install.
if component_selected web || component_selected desktop; then needed="$needed pnpm"; fi
for tool in $needed; do
command -v "$tool" >/dev/null 2>&1 || missing+=("$tool")
done
[ ${#missing[@]} -eq 0 ] || die "Missing prerequisites: ${missing[*]}"
mkdir -p "$DEV_TMPDIR"
if [ "${TMPDIR:-}" != "$DEV_TMPDIR" ]; then
info "TMPDIR pinned to $DEV_TMPDIR (was ${TMPDIR:-<unset>}) so builds outlive the run that made them."
export TMPDIR="$DEV_TMPDIR" TMP="$DEV_TMPDIR" TEMP="$DEV_TMPDIR"
fi
ok "node, go, curl found"
step "Environment"
ENV_FILE="$(detect_env_file)"
if [ ! -f "$REPO_ROOT/$ENV_FILE" ]; then
if [ "$ENV_FILE" = .env.worktree ]; then
bash "$REPO_ROOT/scripts/init-worktree-env.sh" "$ENV_FILE" >/dev/null
else
cp "$REPO_ROOT/.env.example" "$REPO_ROOT/$ENV_FILE"
fi
info "Created $ENV_FILE"
fi
ensure_dev_code "$ENV_FILE"
load_env_file "$ENV_FILE"
acquire_lock
trap release_lock EXIT
local existing offset
existing="$(env_name_for_dir "$REPO_ROOT" || true)"
if [ -n "$existing" ] && [ -z "$name" ]; then
name="$existing"
fi
if [ -n "$existing" ]; then
load_manifest "$existing"
NAME="$existing"
bind_paths
if [ "$lifecycle_requested" = 1 ]; then
OWNER="$owner"
TTL_HOURS="$ttl"
EXPIRES_AT="$(expires_at_after_hours "$ttl")"
save_manifest
fi
info "Reusing environment $NAME (ports $BACKEND_PORT/$FRONTEND_PORT, database $DB_NAME)"
else
offset=$((PORT - 18080))
# A slot is adopted only when the registry does not hold it and both ports
# are genuinely free; otherwise a fresh one is allocated and the env file is
# rewritten, which is the whole point of allocating instead of computing.
local candidate_renderer
candidate_renderer="$(renderer_port_for_offset "$offset")"
if [ "$PORT" -lt 18080 ] || [ "$FRONTEND_PORT" -ne $((13000 + offset)) ] \
|| offset_registered "$offset" || ! port_free "$PORT" \
|| ! port_free "$FRONTEND_PORT" || ! port_free "$candidate_renderer"; then
if [ "$PORT" -ge 18080 ] && { offset_registered "$offset" || ! port_free "$PORT"; }; then
warn "Slot $offset (port $PORT) is taken: $(describe_port_owner "$PORT"). Allocating another."
fi
offset="$(allocate_offset "$REPO_ROOT")" || die "No free slot left; run 'make gc' or 'make list'."
local new_backend=$((18080 + offset)) new_frontend=$((13000 + offset))
local new_db="multica_$(slugify "$(basename "$REPO_ROOT")")_${offset}"
rewrite_env_ports "$ENV_FILE" "$offset" "$new_backend" "$new_frontend" "$new_db"
load_env_file "$ENV_FILE"
info "Allocated slot $offset — backend $new_backend, frontend $new_frontend, database $new_db"
fi
NAME="${name:-$(slugify "$(basename "$REPO_ROOT")")-${offset}}"
require_env_name "$NAME"
PROFILE="dev-$(slugify "$(basename "$REPO_ROOT")")-${offset}"
WORKSPACES_ROOT="$DEV_WORKSPACES_PARENT/multica_workspaces_$PROFILE"
DESKTOP_RENDERER_PORT="$(renderer_port_for_offset "$offset")"
DESKTOP_APP_SUFFIX="$NAME"
DESKTOP_USER_DATA_DIR="$(desktop_user_data_dir "$DESKTOP_APP_SUFFIX")"
DESKTOP_ENV_FILE="$REPO_ROOT/apps/desktop/.env.development.local"
DESKTOP_CDP_PORT=""
[ ! -f "$(manifest_of "$NAME")" ] || die "Environment '$NAME' already exists for a different directory."
mkdir -p "$(env_dir "$NAME")/logs"
DIR="$REPO_ROOT"
CREATED_AT="$(now_iso)"
OWNER="$owner"
TTL_HOURS="$ttl"
EXPIRES_AT=""
[ "$ttl" = 0 ] || EXPIRES_AT="$(expires_at_after_hours "$ttl")"
OFFSET="$offset"
BACKEND_PORT="$PORT"
DB_NAME="$POSTGRES_DB"
save_manifest
load_manifest "$NAME"
ok "Registered environment $NAME"
fi
bind_paths
# The CDP port is recorded like any other allocation: later `make up` runs
# and restarts keep it until --no-cdp clears it.
local previous_cdp="$DESKTOP_CDP_PORT"
case "$cdp_request" in
"") ;;
off) DESKTOP_CDP_PORT="" ;;
auto)
if [ -z "$DESKTOP_CDP_PORT" ]; then
DESKTOP_CDP_PORT="$(allocate_cdp_port "$NAME" $((CDP_PORT_BASE + OFFSET)))" \
|| die "No free port for the Desktop CDP endpoint; pass --remote-debugging-port N."
fi
;;
*)
! cdp_port_registered "$cdp_request" "$NAME" \
|| die "Port $cdp_request is already the CDP port of another environment."
DESKTOP_CDP_PORT="$cdp_request"
;;
esac
DESKTOP_CDP_CHANGED=0
if [ "$DESKTOP_CDP_PORT" != "$previous_cdp" ]; then
DESKTOP_CDP_CHANGED=1
save_manifest
fi
release_lock
trap - EXIT
bind_paths
# The manifest is the source of truth from here on; re-export so every child
# sees the same values the registry recorded.
export PORT="$BACKEND_PORT" FRONTEND_PORT DATABASE_URL POSTGRES_DB="$DB_NAME"
if [ ! -d "$REPO_ROOT/node_modules" ] && { component_selected web || component_selected desktop; }; then
step "Dependencies"
(cd "$REPO_ROOT" && pnpm install) || die "pnpm install failed."
fi
step "Database"
ensure_database
migrate_database
ok "$DB_NAME reachable through DATABASE_URL and migrated"
component_selected desktop || sync_desktop_env_file
step "Components: $COMPONENTS"
component_selected api && start_api
seed_dev_workspace
component_selected web && start_web
component_selected daemon && start_daemon
component_selected desktop && start_desktop
print_handoff
}
cmd_down() {
local name="" requested="$ALL_COMPONENTS"
while [ $# -gt 0 ]; do
case "$1" in
--components|-c) requested="$(printf '%s' "$2" | tr ',' ' ')"; shift 2 ;;
-*) die "Unknown flag for down: $1" ;;
*) name="$1"; shift ;;
esac
done
resolve_env_for_read "$name"
export PORT="$BACKEND_PORT" FRONTEND_PORT DATABASE_URL POSTGRES_DB="$DB_NAME"
step "Stopping $NAME: $requested"
local comp
for comp in $requested; do
case " $ALL_COMPONENTS " in *" $comp "*) ;; *) die "Unknown component '$comp'. Valid: $ALL_COMPONENTS" ;; esac
stop_component "$comp"
done
printf '\n%s✓ %s stopped.%s Database, profile and slot kept — `make up` restarts in seconds.\n' "$C_GREEN" "$NAME" "$C_OFF"
}
cmd_destroy() {
local name="" assume_yes=0 reply admin_url failures=0
local expected_workspaces expected_desktop_data desktop_profile_dir
while [ $# -gt 0 ]; do
case "$1" in
--yes|-y) assume_yes=1; shift ;;
-*) die "Unknown flag for destroy: $1" ;;
*) name="$1"; shift ;;
esac
done
resolve_env_for_read "$name"
if [ "$assume_yes" != 1 ]; then
printf 'Destroy %s? This drops database %s and profile %s. [y/N] ' "$NAME" "$DB_NAME" "$PROFILE"
read -r reply || reply=n
case "$reply" in y|Y|yes|YES) ;; *) printf 'Cancelled.\n'; return 0 ;; esac
fi
export PORT="$BACKEND_PORT" FRONTEND_PORT DATABASE_URL POSTGRES_DB="$DB_NAME"
step "Destroying $NAME"
local comp desktop_stopped=1
for comp in $ALL_COMPONENTS; do
if ! stop_component "$comp"; then
failures=$((failures + 1))
[ "$comp" != desktop ] || desktop_stopped=0
fi
done
if command -v psql >/dev/null 2>&1; then
admin_url="$(admin_database_url "$DATABASE_URL")"
if PGCONNECT_TIMEOUT=3 psql "$admin_url" -tAc 'SELECT 1' >/dev/null 2>&1; then
if psql "$admin_url" -v ON_ERROR_STOP=1 -c "DROP DATABASE IF EXISTS \"$DB_NAME\" WITH (FORCE)" >/dev/null; then
ok "dropped database $DB_NAME"
else
warn "failed to drop database $DB_NAME; keeping its manifest"
failures=$((failures + 1))
fi
else
warn "Nothing answered on the database host; $DB_NAME was left in place."
failures=$((failures + 1))
fi
else
warn "psql not found; $DB_NAME was left in place."
failures=$((failures + 1))
fi
if rm -rf "$PROFILE_DIR"; then
ok "removed CLI profile $PROFILE"
else
warn "failed to remove CLI profile $PROFILE"
failures=$((failures + 1))
fi
expected_workspaces="$DEV_WORKSPACES_PARENT/multica_workspaces_$PROFILE"
if [ "$WORKSPACES_ROOT" != "$expected_workspaces" ]; then
warn "refusing to remove unexpected workspaces root $WORKSPACES_ROOT (expected $expected_workspaces)"
failures=$((failures + 1))
elif rm -rf "$WORKSPACES_ROOT"; then
ok "removed daemon workspaces $WORKSPACES_ROOT"
else
warn "failed to remove daemon workspaces $WORKSPACES_ROOT"
failures=$((failures + 1))
fi
expected_desktop_data="$(desktop_user_data_dir "$DESKTOP_APP_SUFFIX")"
if [ "$DESKTOP_USER_DATA_DIR" != "$expected_desktop_data" ]; then
warn "refusing to remove unexpected Desktop userData $DESKTOP_USER_DATA_DIR"
failures=$((failures + 1))
elif rm -rf "$DESKTOP_USER_DATA_DIR"; then
ok "removed Desktop userData $DESKTOP_USER_DATA_DIR"
else
warn "failed to remove Desktop userData $DESKTOP_USER_DATA_DIR"
failures=$((failures + 1))
fi
# The profile holds the daemon's pid and config, which a retried destroy
# needs to stop it; keep it until Desktop and its daemon are confirmed gone.
desktop_profile_dir="$DEV_PROFILES_HOME/$(desktop_daemon_profile)"
if [ "$desktop_stopped" != 1 ]; then
[ ! -d "$desktop_profile_dir" ] \
|| warn "kept Desktop's CLI profile $(desktop_daemon_profile) for the retry"
elif [ -d "$desktop_profile_dir" ]; then
if rm -rf "$desktop_profile_dir"; then
ok "removed Desktop's CLI profile $(desktop_daemon_profile)"
else
warn "failed to remove Desktop's CLI profile $desktop_profile_dir"
failures=$((failures + 1))
fi
fi
if [ -f "$DESKTOP_ENV_FILE" ] \
&& grep -Fqx "# Managed by scripts/dev-env.sh for environment ${NAME}." "$DESKTOP_ENV_FILE"; then
if rm -f "$DESKTOP_ENV_FILE"; then
ok "removed managed Desktop env file"
else
warn "failed to remove $DESKTOP_ENV_FILE"
failures=$((failures + 1))
fi
fi
if [ "$failures" -ne 0 ]; then
die "$NAME was only partially destroyed ($failures cleanup failure(s)). Its manifest and slot were kept so 'make destroy' can retry."
fi
rm -rf "$(env_dir "$NAME")"
ok "released slot $OFFSET"
printf '\n%s✓ %s destroyed.%s\n' "$C_GREEN" "$NAME" "$C_OFF"
}
cmd_status() {
local name="" as_json=0
while [ $# -gt 0 ]; do
case "$1" in
--json) as_json=1; shift ;;
-*) die "Unknown flag for status: $1" ;;
*) name="$1"; shift ;;
esac
done
resolve_env_for_read "$name"
if [ "$as_json" = 1 ]; then print_status_json; else print_status_human; fi
}
cmd_list() {
local as_json=0 name first=1 alive
[ "${1:-}" = "--json" ] && as_json=1
if [ "$as_json" = 1 ]; then printf '['; fi
local printed=0
while read -r name; do
[ -n "$name" ] || continue
(
load_manifest "$name"
bind_paths
alive="$(component_state api)"
alive="${alive%%|*}"
if [ "$as_json" = 1 ]; then
printf '{"name":"%s","dir":"%s","owner":"%s","api":"%s","backend_port":%s,"frontend_port":%s,"desktop_renderer_port":%s,"database":"%s","created_at":"%s","ttl_hours":%s,"expires_at":"%s"}' \
"$(json_escape "$NAME")" "$(json_escape "$DIR")" "$(json_escape "$OWNER")" "$alive" \
"$BACKEND_PORT" "$FRONTEND_PORT" "$DESKTOP_RENDERER_PORT" "$(json_escape "$DB_NAME")" "$(json_escape "$CREATED_AT")" "${TTL_HOURS:-0}" "$(json_escape "$EXPIRES_AT")"
else
printf '%-24s %-8s %-8s %-6s %-28s %s\n' "$NAME" "$alive" "$OWNER" \
"$BACKEND_PORT" "$DB_NAME" "$( [ -d "$DIR" ] && printf '%s' "$DIR" || printf '%s(directory gone)%s' "$C_RED" "$C_OFF" )"
fi
) | { if [ "$as_json" = 1 ] && [ "$printed" != 0 ]; then printf ','; fi; cat; }
printed=1
first=0
done <<EOF
$(list_env_names)
EOF
if [ "$as_json" = 1 ]; then
printf ']\n'
elif [ "$printed" = 0 ]; then
printf 'No environments registered. Run `make up`.\n'
fi
}
# Leaks become visible here rather than being discovered by counting databases
# in psql: an environment whose directory is gone, or whose TTL has passed, has
# no owner left to stop it.
cmd_gc() {
local dry_run=0 automatic=0 name age_hours created_epoch expiry_epoch reason
while [ $# -gt 0 ]; do
case "$1" in
--dry-run) dry_run=1 ;;
--auto) automatic=1 ;;
*) die "Unknown flag for gc: $1" ;;
esac
shift
done
while read -r name; do
[ -n "$name" ] || continue
(
load_manifest "$name"
reason=""
[ -d "$DIR" ] || reason="its checkout directory is gone"
if [ -z "$reason" ] && [ "${TTL_HOURS:-0}" != 0 ]; then
if [ -n "${EXPIRES_AT:-}" ]; then
expiry_epoch="$(node -e 'process.stdout.write(String(Math.floor(Date.parse(process.argv[1]) / 1000)))' "$EXPIRES_AT" 2>/dev/null || echo 0)"
[ "$(now_epoch)" -lt "$expiry_epoch" ] || reason="it expired at $EXPIRES_AT"
else
created_epoch="$(node -e 'process.stdout.write(String(Math.floor(Date.parse(process.argv[1]) / 1000)))' "$CREATED_AT" 2>/dev/null || echo 0)"
age_hours=$(( ($(now_epoch) - created_epoch) / 3600 ))
[ "$age_hours" -lt "$TTL_HOURS" ] || reason="it expired ${age_hours}h after a ${TTL_HOURS}h ttl"
fi
fi
[ -n "$reason" ] || exit 0
if [ "$dry_run" = 1 ]; then
printf '%s would be collected: %s\n' "$NAME" "$reason"
else
printf '%s: %s\n' "$NAME" "$reason"
if ! bash "$REPO_ROOT/scripts/dev-env.sh" destroy "$NAME" --yes; then
if [ "$automatic" = 1 ]; then
warn "automatic cleanup of $NAME failed; its manifest was kept for retry"
else
exit 1
fi
fi
fi
)
done <<EOF
$(list_env_names)
EOF
}
# Runs a command with this environment's variables, without the agent runtime's
# production MULTICA_* values and with a durable TMPDIR. Replaces the prefix
# people used to have to copy out of a document by hand.
cmd_exec() {
local name=""
if [ "${1:-}" != "--" ] && [ $# -gt 0 ]; then name="$1"; shift; fi
[ "${1:-}" = "--" ] && shift
[ $# -gt 0 ] || die "Usage: dev-env.sh exec [name] -- <command> [args...]"
resolve_env_for_read "$name"
mkdir -p "$DEV_TMPDIR"
cd "$DIR"
load_env_file "$ENV_FILE" "$DIR"
export PORT="$BACKEND_PORT" FRONTEND_PORT DATABASE_URL POSTGRES_DB="$DB_NAME"
export TMPDIR="$DEV_TMPDIR" TMP="$DEV_TMPDIR" TEMP="$DEV_TMPDIR"
export MULTICA_DEV_PROFILE="$PROFILE"
# Read by scripts/desktop-cdp.mjs to find this environment's Desktop.
export MULTICA_DEV_DESKTOP_RENDERER_URL="http://localhost:${DESKTOP_RENDERER_PORT}"
if [ -n "${DESKTOP_CDP_PORT:-}" ]; then
export MULTICA_DEV_DESKTOP_CDP_URL="http://127.0.0.1:${DESKTOP_CDP_PORT}"
else
unset MULTICA_DEV_DESKTOP_CDP_URL
fi
exec "${CLEAN_ENV[@]}" MULTICA_WORKSPACES_ROOT="$WORKSPACES_ROOT" "$@"
}
usage() {
cat <<'EOF'
Local development environments: named, listable, deletable.
dev-env.sh up [--components api,web,daemon,desktop] [--all]
[--name N] [--ephemeral] [--ttl HOURS]
[--cdp | --remote-debugging-port N | --no-cdp]
dev-env.sh status [name] [--json]
dev-env.sh list [--json]
dev-env.sh down [name] [--components ...]
dev-env.sh destroy [name] [--yes]
dev-env.sh gc [--dry-run]
dev-env.sh exec [name] -- <command> [args...]
Components: api (Go backend), web (Next.js), daemon (agent daemon),
desktop (Electron). Anything selected implies api.
Every environment has an onboarded workspace with two issues, signed in
through its CLI profile; scripts/dev-fixtures.mjs adds chat, Agent Builder and
wide-markdown issue content. desktop starts signed in. --cdp exposes a Chrome
DevTools Protocol port (printed by up and status --json) for Playwright's
connectOverCDP; the port is kept for later runs until --no-cdp.
down keeps the database, the CLI profile and the allocated slot.
destroy consumes them.
EOF
}
main() {
local verb="${1:-}"
[ $# -gt 0 ] && shift || true
case "$verb" in
up) cmd_up "$@" ;;
down) cmd_down "$@" ;;
status) cmd_status "$@" ;;
list|ls) cmd_list "$@" ;;
destroy) cmd_destroy "$@" ;;
gc) cmd_gc "$@" ;;
exec) cmd_exec "$@" ;;
""|-h|--help|help) usage ;;
*) usage >&2; exit 2 ;;
esac
}
if [ "${BASH_SOURCE[0]}" = "$0" ]; then
main "$@"
fi