mirror of
https://github.com/MCCTeam/Minecraft-Console-Client
synced 2026-08-15 13:04:36 +00:00
[skipci] docs: update .gitignore and config for superpowers documentation
This commit is contained in:
BruceChen
parent
8dccdaa7aa
commit
58ad896021
4 changed files with 3 additions and 1105 deletions
|
|
@ -77,6 +77,8 @@ export default defineUserConfig({
|
|||
// set site base to default value
|
||||
base: '/',
|
||||
|
||||
pagePatterns: ['**/*.md', '!.vuepress', '!node_modules', '!superpowers'],
|
||||
|
||||
// extra tags in `<head>`
|
||||
head: headConfig,
|
||||
|
||||
|
|
|
|||
|
|
@ -1,789 +0,0 @@
|
|||
# MCC 共享服务器与隔离会话 Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 让多个 Git worktree 共享同一套本地 Minecraft 测试服务器，同时让每个 MCC 调试会话按 `session` 隔离，并支持按 worktree 选择性把构建输出放到 tmpfs。
|
||||
|
||||
**Architecture:** 保持 `mc-*` 命令面向共享服务器，保留 `MCC_SERVERS` 作为共享 server root override；把 `mcc-*` 命令改成面向显式 `session` 的客户端会话工具，默认 `session` 取当前 worktree 名，默认用户名从 `session` 派生。构建层通过统一的 helper 和 `Directory.Build.props` 接入可选的 tmpfs 构建根，不再依赖 shell 中泄漏的 `MCC_REPO`。
|
||||
|
||||
**Tech Stack:** Bash, tmux, dotnet CLI, MSBuild `Directory.Build.props`, repo 自带的 MCC integration harness
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 建立会话与构建根解析的基础 helper，并补一个可重复运行的 shell smoke test
|
||||
|
||||
**Files:**
|
||||
- Create: `tools/test-mcc-env.sh`
|
||||
- Modify: `tools/mcc-env.sh`
|
||||
|
||||
- [ ] **Step 1: 先写一个会失败的 shell smoke test，锁定会话名、用户名和路径解析规则**
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
source "$REPO_ROOT/tools/mcc-env.sh"
|
||||
|
||||
assert_eq() {
|
||||
local expected="$1"
|
||||
local actual="$2"
|
||||
local label="$3"
|
||||
if [[ "$expected" != "$actual" ]]; then
|
||||
echo "FAIL: $label" >&2
|
||||
echo " expected: $expected" >&2
|
||||
echo " actual: $actual" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
assert_regex() {
|
||||
local regex="$1"
|
||||
local actual="$2"
|
||||
local label="$3"
|
||||
if [[ ! "$actual" =~ $regex ]]; then
|
||||
echo "FAIL: $label" >&2
|
||||
echo " regex: $regex" >&2
|
||||
echo " actual: $actual" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
session="$(_mcc_resolve_session "demo-branch")"
|
||||
assert_eq "demo-branch" "$session" "explicit session"
|
||||
|
||||
short_name="$(_mcc_resolve_username "feature-ai")"
|
||||
assert_eq "mcc_feature_ai" "$short_name" "short derived username"
|
||||
|
||||
long_name="$(_mcc_resolve_username "very-long-worktree-name")"
|
||||
assert_regex '^mcc_[a-z0-9_]{7}_[0-9a-f]{4}$' "$long_name" "long derived username shape"
|
||||
assert_eq "16" "${#long_name}" "long derived username length"
|
||||
|
||||
assert_eq "${TMPDIR:-/tmp}/mcc-debug/demo-branch" "$(_mcc_session_root "demo-branch")" "session root"
|
||||
assert_eq "mcc-demo-branch" "$(_mcc_tmux_session_name "demo-branch")" "tmux session name"
|
||||
|
||||
MCC_BUILD_MODE=tmpfs
|
||||
build_root="$(_mcc_build_root)"
|
||||
assert_regex '^(/dev/shm|/tmp)/mcc-build/.+$' "$build_root" "tmpfs build root"
|
||||
|
||||
echo "PASS"
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试，确认它先失败**
|
||||
|
||||
Run: `bash tools/test-mcc-env.sh`
|
||||
|
||||
Expected: FAIL，错误类似 `_mcc_resolve_session: command not found`
|
||||
|
||||
- [ ] **Step 3: 在 `tools/mcc-env.sh` 中加入 repo root、server root、session、username、会话目录、tmux 名和 build root helper**
|
||||
|
||||
```bash
|
||||
if [[ -n "${BASH_SOURCE[0]:-}" ]]; then
|
||||
_mcc_env_source="${BASH_SOURCE[0]}"
|
||||
elif [[ -n "${ZSH_VERSION:-}" ]]; then
|
||||
_mcc_env_source="${(%):-%N}"
|
||||
else
|
||||
_mcc_env_source="$0"
|
||||
fi
|
||||
|
||||
TOOLS_DIR="$(cd "$(dirname "$_mcc_env_source")" && pwd)"
|
||||
MCC_REPO_ROOT="$(cd "$TOOLS_DIR/.." && pwd)"
|
||||
unset _mcc_env_source
|
||||
|
||||
_mcc_repo_root() {
|
||||
printf '%s\n' "$MCC_REPO_ROOT"
|
||||
}
|
||||
|
||||
_mcc_servers_root() {
|
||||
printf '%s\n' "${MCC_SERVERS:-$MCC_REPO_ROOT/MinecraftOfficial/downloads}"
|
||||
}
|
||||
|
||||
_mcc_current_worktree_name() {
|
||||
git -C "$MCC_REPO_ROOT" rev-parse --show-toplevel 2>/dev/null | xargs basename
|
||||
}
|
||||
|
||||
_mcc_resolve_session() {
|
||||
local explicit="${1:-}"
|
||||
if [[ -n "$explicit" ]]; then
|
||||
printf '%s\n' "$explicit"
|
||||
return 0
|
||||
fi
|
||||
|
||||
local worktree
|
||||
worktree="$(_mcc_current_worktree_name)"
|
||||
if [[ -n "$worktree" ]]; then
|
||||
printf '%s\n' "$worktree"
|
||||
else
|
||||
basename "$MCC_REPO_ROOT"
|
||||
fi
|
||||
}
|
||||
|
||||
_mcc_sha1_short() {
|
||||
if command -v sha1sum >/dev/null 2>&1; then
|
||||
printf '%s' "$1" | sha1sum | awk '{print substr($1, 1, 4)}'
|
||||
else
|
||||
printf '%s' "$1" | shasum -a 1 | awk '{print substr($1, 1, 4)}'
|
||||
fi
|
||||
}
|
||||
|
||||
_mcc_resolve_username() {
|
||||
local session="$1"
|
||||
local normalized
|
||||
normalized="$(printf '%s' "$session" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9_]/_/g')"
|
||||
local candidate="mcc_${normalized}"
|
||||
if (( ${#candidate} <= 16 )); then
|
||||
printf '%s\n' "$candidate"
|
||||
return 0
|
||||
fi
|
||||
|
||||
local hash
|
||||
hash="$(_mcc_sha1_short "$normalized")"
|
||||
printf '%s_%s\n' "${candidate:0:11}" "$hash"
|
||||
}
|
||||
|
||||
_mcc_session_root() {
|
||||
printf '%s/mcc-debug/%s\n' "${TMPDIR:-/tmp}" "$1"
|
||||
}
|
||||
|
||||
_mcc_session_log_file() {
|
||||
printf '%s/mcc-debug.log\n' "$(_mcc_session_root "$1")"
|
||||
}
|
||||
|
||||
_mcc_session_input_file() {
|
||||
printf '%s/mcc_input.txt\n' "$(_mcc_session_root "$1")"
|
||||
}
|
||||
|
||||
_mcc_session_pid_file() {
|
||||
printf '%s/mcc.pid\n' "$(_mcc_session_root "$1")"
|
||||
}
|
||||
|
||||
_mcc_session_meta_file() {
|
||||
printf '%s/session.meta\n' "$(_mcc_session_root "$1")"
|
||||
}
|
||||
|
||||
_mcc_tmux_session_name() {
|
||||
printf 'mcc-%s\n' "$1"
|
||||
}
|
||||
|
||||
_mcc_build_root() {
|
||||
local worktree
|
||||
worktree="$(_mcc_current_worktree_name)"
|
||||
if [[ "${MCC_BUILD_MODE:-local}" == "tmpfs" ]]; then
|
||||
if [[ -d /dev/shm && -w /dev/shm ]]; then
|
||||
printf '/dev/shm/mcc-build/%s\n' "$worktree"
|
||||
else
|
||||
printf '%s/mcc-build/%s\n' "${TMPDIR:-/tmp}" "$worktree"
|
||||
fi
|
||||
return 0
|
||||
fi
|
||||
|
||||
printf '%s\n' "$MCC_REPO_ROOT"
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 再跑 smoke test，确认规则都落地**
|
||||
|
||||
Run: `bash tools/test-mcc-env.sh`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: 提交这一小步**
|
||||
|
||||
```bash
|
||||
git add tools/mcc-env.sh tools/test-mcc-env.sh
|
||||
git commit -m "tools: add MCC session and build root helpers"
|
||||
```
|
||||
|
||||
### Task 2: 让 `mcc-*` shell helper 全部按 `session` 工作，并新增安全的 session reset
|
||||
|
||||
**Files:**
|
||||
- Modify: `tools/mcc-env.sh`
|
||||
- Test: `tools/test-mcc-env.sh`
|
||||
|
||||
- [ ] **Step 1: 在 smoke test 里加入 `mcc-cmd` 和 `mcc-reset-session` 的行为检查**
|
||||
|
||||
```bash
|
||||
session="wrapper-smoke"
|
||||
input_file="$(_mcc_session_input_file "$session")"
|
||||
rm -rf "$(_mcc_session_root "$session")"
|
||||
|
||||
mcc-cmd --session "$session" "debug state"
|
||||
grep -Fq "debug state" "$input_file"
|
||||
|
||||
mcc-reset-session --session "$session"
|
||||
[[ ! -e "$(_mcc_session_root "$session")" ]]
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试，确认它先因为参数解析或命令不存在而失败**
|
||||
|
||||
Run: `bash tools/test-mcc-env.sh`
|
||||
|
||||
Expected: FAIL，错误类似 `mcc-reset-session: command not found` 或 `Unknown option: --session`
|
||||
|
||||
- [ ] **Step 3: 在 `tools/mcc-env.sh` 里把 `mcc-*` helper 改成 session-aware**
|
||||
|
||||
```bash
|
||||
mcc-build() {
|
||||
local repo_root
|
||||
repo_root="$(_mcc_repo_root)"
|
||||
if [[ "${MCC_BUILD_MODE:-local}" == "tmpfs" ]]; then
|
||||
local build_root
|
||||
build_root="$(_mcc_build_root)"
|
||||
mkdir -p "$build_root"
|
||||
MCC_BUILD_ROOT="$build_root" dotnet build "$repo_root/MinecraftClient.sln" -c Release
|
||||
else
|
||||
dotnet build "$repo_root/MinecraftClient.sln" -c Release
|
||||
fi
|
||||
}
|
||||
|
||||
mcc-cmd() {
|
||||
local session=""
|
||||
local command=""
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) session="$2"; shift 2 ;;
|
||||
*) command="$1"; shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
[[ -n "$command" ]] || { echo "Usage: mcc-cmd [--session NAME] <command>" >&2; return 1; }
|
||||
session="$(_mcc_resolve_session "$session")"
|
||||
local input_file
|
||||
input_file="$(_mcc_session_input_file "$session")"
|
||||
mkdir -p "$(dirname "$input_file")"
|
||||
printf '%s\n' "$command" >> "$input_file"
|
||||
}
|
||||
|
||||
mcc-log-mcc() {
|
||||
local session="${1:-}"
|
||||
if [[ "$session" == "--session" ]]; then
|
||||
session="${2:-}"
|
||||
fi
|
||||
session="$(_mcc_resolve_session "$session")"
|
||||
tail -f "$(_mcc_session_log_file "$session")"
|
||||
}
|
||||
|
||||
mcc-state() {
|
||||
local session=""
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) session="$2"; shift 2 ;;
|
||||
*) echo "Unknown option: $1" >&2; return 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
session="$(_mcc_resolve_session "$session")"
|
||||
mcc-cmd --session "$session" "debug state"
|
||||
sleep 1
|
||||
tail -30 "$(_mcc_session_log_file "$session")"
|
||||
}
|
||||
|
||||
mcc-reset-session() {
|
||||
local session=""
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) session="$2"; shift 2 ;;
|
||||
*) echo "Unknown option: $1" >&2; return 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
session="$(_mcc_resolve_session "$session")"
|
||||
tmux kill-session -t "$(_mcc_tmux_session_name "$session")" 2>/dev/null || true
|
||||
rm -rf "$(_mcc_session_root "$session")"
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 smoke test，确认 session input 与 reset 生效**
|
||||
|
||||
Run: `bash tools/test-mcc-env.sh`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: 提交这一小步**
|
||||
|
||||
```bash
|
||||
git add tools/mcc-env.sh tools/test-mcc-env.sh
|
||||
git commit -m "tools: scope MCC shell helpers by session"
|
||||
```
|
||||
|
||||
### Task 3: 改造 `mcc-debug.sh`、`mcc-log-tail.sh` 和 kill 流程，隔离 tmux、log、config、PID、metadata
|
||||
|
||||
**Files:**
|
||||
- Modify: `tools/mcc-debug.sh`
|
||||
- Modify: `tools/mcc-log-tail.sh`
|
||||
- Modify: `tools/mcc-env.sh`
|
||||
|
||||
- [ ] **Step 1: 用真实命令先验证当前行为会互相覆盖**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
source tools/mcc-env.sh
|
||||
mcc-debug -v 1.21.11 --file-input --no-build
|
||||
ls -la /tmp/mcc-debug
|
||||
tmux list-sessions | grep '^mcc-debug:'
|
||||
```
|
||||
|
||||
Expected: 看到固定目录 `/tmp/mcc-debug` 和固定 tmux 名 `mcc-debug`
|
||||
|
||||
- [ ] **Step 2: 在 `tools/mcc-debug.sh` 中加入 `--session` 和 `--username`，并把所有运行时工件改成 session-scoped**
|
||||
|
||||
```bash
|
||||
SESSION=""
|
||||
USERNAME=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) SESSION="$2"; shift 2 ;;
|
||||
--username) USERNAME="$2"; shift 2 ;;
|
||||
-v|--version) VERSION="$2"; shift 2 ;;
|
||||
-m|--mode) MODE="$2"; shift 2 ;;
|
||||
-p|--port) PORT="$2"; PORT_SET_BY_USER=true; shift 2 ;;
|
||||
--no-build) DO_BUILD=false; shift ;;
|
||||
--debug-on) DEBUG_ON=true; shift ;;
|
||||
--file-input) FILE_INPUT=true; shift ;;
|
||||
-h|--help) usage; exit 0 ;;
|
||||
*) echo "Unknown option: $1" >&2; usage >&2; exit 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
SESSION="$(_mcc_resolve_session "$SESSION")"
|
||||
USERNAME="${USERNAME:-$(_mcc_resolve_username "$SESSION")}"
|
||||
SESSION_ROOT="$(_mcc_session_root "$SESSION")"
|
||||
CFG="$SESSION_ROOT/MinecraftClient.debug.ini"
|
||||
MCC_LOG="$(_mcc_session_log_file "$SESSION")"
|
||||
INPUT_FILE="$(_mcc_session_input_file "$SESSION")"
|
||||
PID_FILE="$(_mcc_session_pid_file "$SESSION")"
|
||||
META_FILE="$(_mcc_session_meta_file "$SESSION")"
|
||||
MCC_TMUX_SESSION="$(_mcc_tmux_session_name "$SESSION")"
|
||||
|
||||
mkdir -p "$SESSION_ROOT"
|
||||
|
||||
cat > "$META_FILE" <<EOF
|
||||
SESSION=$SESSION
|
||||
USERNAME=$USERNAME
|
||||
MODE=$MODE
|
||||
CFG=$CFG
|
||||
LOG=$MCC_LOG
|
||||
INPUT=$INPUT_FILE
|
||||
PID_FILE=$PID_FILE
|
||||
TMUX_SESSION=$MCC_TMUX_SESSION
|
||||
SERVER_VERSION=$VERSION
|
||||
EOF
|
||||
|
||||
MCC_ARGS=("$CFG" "$USERNAME" "-" "localhost:$PORT")
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 把 `mcc-kill` 改成精准杀当前 session，不再 `pkill -f MinecraftClient`**
|
||||
|
||||
```bash
|
||||
mcc-kill() {
|
||||
local session=""
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) session="$2"; shift 2 ;;
|
||||
*) echo "Unknown option: $1" >&2; return 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
session="$(_mcc_resolve_session "$session")"
|
||||
local pid_file meta_file tmux_name
|
||||
pid_file="$(_mcc_session_pid_file "$session")"
|
||||
meta_file="$(_mcc_session_meta_file "$session")"
|
||||
tmux_name="$(_mcc_tmux_session_name "$session")"
|
||||
|
||||
if [[ -f "$pid_file" ]]; then
|
||||
pid="$(cat "$pid_file")"
|
||||
if kill -0 "$pid" 2>/dev/null; then
|
||||
kill "$pid"
|
||||
wait "$pid" 2>/dev/null || true
|
||||
fi
|
||||
rm -f "$pid_file"
|
||||
fi
|
||||
|
||||
tmux kill-session -t "$tmux_name" 2>/dev/null || true
|
||||
[[ -f "$meta_file" ]] && rm -f "$meta_file"
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 让 `tools/mcc-log-tail.sh` 支持 `--session`，读取 session-specific log**
|
||||
|
||||
```bash
|
||||
SESSION=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) SESSION="$2"; shift 2 ;;
|
||||
--server) SERVER_VER="$2"; shift 2 ;;
|
||||
--server-only) SERVER_ONLY=true; SERVER_VER="$2"; shift 2 ;;
|
||||
-h|--help) echo "Usage: tools/mcc-log-tail.sh [--session NAME] [--server VER] [--server-only VER]"; exit 0 ;;
|
||||
*) echo "Unknown option: $1"; exit 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
SESSION="$(_mcc_resolve_session "$SESSION")"
|
||||
MCC_LOG="$(_mcc_session_log_file "$SESSION")"
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 用两个显式 session 跑一次真实 smoke**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
source tools/mcc-env.sh
|
||||
mcc-debug -v 1.21.11 --session smoke-a --username SmokeA --file-input --no-build
|
||||
mcc-debug -v 1.21.11 --session smoke-b --username SmokeB --file-input --no-build
|
||||
test -f "$(_mcc_session_log_file smoke-a)"
|
||||
test -f "$(_mcc_session_log_file smoke-b)"
|
||||
test -f "$(_mcc_session_meta_file smoke-a)"
|
||||
test -f "$(_mcc_session_meta_file smoke-b)"
|
||||
tmux list-sessions | grep '^mcc-smoke-a:'
|
||||
tmux list-sessions | grep '^mcc-smoke-b:'
|
||||
```
|
||||
|
||||
Expected: 两套独立文件与两套 tmux 会话都存在
|
||||
|
||||
- [ ] **Step 6: 提交这一小步**
|
||||
|
||||
```bash
|
||||
git add tools/mcc-debug.sh tools/mcc-log-tail.sh tools/mcc-env.sh
|
||||
git commit -m "tools: isolate MCC debug state by session"
|
||||
```
|
||||
|
||||
### Task 4: 加入按 worktree 选择性启用的 tmpfs 构建根，并修正外置 `obj` 的 MSBuild 过滤问题
|
||||
|
||||
**Files:**
|
||||
- Create: `Directory.Build.props`
|
||||
- Modify: `tools/mcc-env.sh`
|
||||
- Test: `tools/test-mcc-env.sh`
|
||||
|
||||
- [ ] **Step 1: 先用当前仓库验证“直接外置 obj 会失败”，把这个回归固定住**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
rm -rf /tmp/mcc-plan-build-smoke
|
||||
dotnet build MinecraftClient.sln -c Release -v minimal --nologo \
|
||||
-p:BaseOutputPath=/tmp/mcc-plan-build-smoke/bin/ \
|
||||
-p:BaseIntermediateOutputPath=/tmp/mcc-plan-build-smoke/obj/ \
|
||||
-p:MSBuildProjectExtensionsPath=/tmp/mcc-plan-build-smoke/obj/
|
||||
```
|
||||
|
||||
Expected: FAIL，包含重复 `AssemblyInfo` 或 `TargetFrameworkAttribute` 一类错误
|
||||
|
||||
- [ ] **Step 2: 新建 `Directory.Build.props`，统一把 `MCC_BUILD_ROOT` 接到每个项目自己的外置 `bin/obj`，并显式排除仓库内 `bin/obj`**
|
||||
|
||||
```xml
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<DefaultItemExcludes>$(DefaultItemExcludes);**/bin/**;**/obj/**</DefaultItemExcludes>
|
||||
</PropertyGroup>
|
||||
|
||||
<PropertyGroup Condition="'$(MCC_BUILD_ROOT)' != ''">
|
||||
<BaseOutputPath>$(MCC_BUILD_ROOT)/$(MSBuildProjectName)/bin/</BaseOutputPath>
|
||||
<BaseIntermediateOutputPath>$(MCC_BUILD_ROOT)/$(MSBuildProjectName)/obj/</BaseIntermediateOutputPath>
|
||||
<MSBuildProjectExtensionsPath>$(BaseIntermediateOutputPath)</MSBuildProjectExtensionsPath>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 在 `tools/mcc-env.sh` 中把 `mcc-build`、`mcc-run`、`mcc-tui`、`mcc-debug` 的 `dotnet` 调用统一接入 `MCC_BUILD_MODE=tmpfs`**
|
||||
|
||||
```bash
|
||||
_mcc_dotnet_env() {
|
||||
if [[ "${MCC_BUILD_MODE:-local}" == "tmpfs" ]]; then
|
||||
local build_root
|
||||
build_root="$(_mcc_build_root)"
|
||||
mkdir -p "$build_root"
|
||||
env MCC_BUILD_ROOT="$build_root" "$@"
|
||||
return 0
|
||||
fi
|
||||
|
||||
"$@"
|
||||
}
|
||||
|
||||
mcc-run() {
|
||||
local session="" username="" port="25565"
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) session="$2"; shift 2 ;;
|
||||
--username) username="$2"; shift 2 ;;
|
||||
--port) port="$2"; shift 2 ;;
|
||||
*) break ;;
|
||||
esac
|
||||
done
|
||||
|
||||
session="$(_mcc_resolve_session "$session")"
|
||||
username="${username:-$(_mcc_resolve_username "$session")}"
|
||||
mkdir -p "$(_mcc_session_root "$session")"
|
||||
_mcc_dotnet_env env \
|
||||
MCC_FILE_INPUT=1 \
|
||||
MCC_INPUT_FILE="$(_mcc_session_input_file "$session")" \
|
||||
dotnet run --project "$(_mcc_repo_root)/MinecraftClient" -c Release -- \
|
||||
"$(_mcc_session_root "$session")/MinecraftClient.debug.ini" \
|
||||
"$username" \
|
||||
- \
|
||||
"localhost:$port"
|
||||
}
|
||||
|
||||
mcc-tui() {
|
||||
local session="" username="" port="25565"
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--session) session="$2"; shift 2 ;;
|
||||
--username) username="$2"; shift 2 ;;
|
||||
--port) port="$2"; shift 2 ;;
|
||||
*) break ;;
|
||||
esac
|
||||
done
|
||||
|
||||
session="$(_mcc_resolve_session "$session")"
|
||||
username="${username:-$(_mcc_resolve_username "$session")}"
|
||||
tmux new-session -d -s "$(_mcc_tmux_session_name "$session")" -x 160 -y 50 \
|
||||
"cd '$(_mcc_repo_root)' && MCC_BUILD_MODE='${MCC_BUILD_MODE:-local}' bash tools/mcc-debug.sh --session '$session' --username '$username' -p '$port' -m tui --no-build"
|
||||
}
|
||||
|
||||
mcc-build-clean() {
|
||||
if [[ "${MCC_BUILD_MODE:-local}" == "tmpfs" ]]; then
|
||||
rm -rf "$(_mcc_build_root)"
|
||||
else
|
||||
dotnet clean "$(_mcc_repo_root)/MinecraftClient.sln" -c Release
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 扩展 smoke test，检查 `tmpfs` build root helper 和清理命令**
|
||||
|
||||
```bash
|
||||
MCC_BUILD_MODE=tmpfs
|
||||
build_root="$(_mcc_build_root)"
|
||||
mkdir -p "$build_root/probe"
|
||||
mcc-build-clean
|
||||
[[ ! -e "$build_root/probe" ]]
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 用 tmpfs 模式重新 build，确认能成功且产物出现在 worktree 专属构建根**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
source tools/mcc-env.sh
|
||||
export MCC_BUILD_MODE=tmpfs
|
||||
mcc-build
|
||||
find "$(_mcc_build_root)" -maxdepth 3 -type d | sed -n '1,20p'
|
||||
```
|
||||
|
||||
Expected: `Build succeeded.`，并且构建目录位于 `/dev/shm/mcc-build/<worktree>/` 或 `/tmp/mcc-build/<worktree>/`
|
||||
|
||||
- [ ] **Step 6: 提交这一小步**
|
||||
|
||||
```bash
|
||||
git add Directory.Build.props tools/mcc-env.sh tools/test-mcc-env.sh
|
||||
git commit -m "build: add worktree-aware tmpfs build mode"
|
||||
```
|
||||
|
||||
### Task 5: 更新 integration harness，并新增“单服务器双会话”自动化 smoke test
|
||||
|
||||
**Files:**
|
||||
- Create: `.skills/mcc-integration-testing/scripts/run_parallel_session_smoke_test.sh`
|
||||
- Modify: `.skills/mcc-integration-testing/scripts/reset_shared_test_state.sh`
|
||||
- Modify: `.skills/mcc-integration-testing/scripts/run_full_spectrum_test.sh`
|
||||
- Modify: `tools/run-creative-e2e.sh`
|
||||
|
||||
- [ ] **Step 1: 新增并行会话 smoke test 脚本，先把预期行为写下来**
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
|
||||
source "$REPO_ROOT/tools/mcc-env.sh"
|
||||
source "$SCRIPT_DIR/common.sh"
|
||||
|
||||
VERSION="${1:-1.21.11}"
|
||||
SESSION_A="parallel-a"
|
||||
SESSION_B="parallel-b"
|
||||
USER_A="ParallelA"
|
||||
USER_B="ParallelB"
|
||||
|
||||
bash "$SCRIPT_DIR/preflight_test_env.sh" "$VERSION" >/dev/null
|
||||
bash "$SCRIPT_DIR/reset_shared_test_state.sh" "$VERSION" >/dev/null
|
||||
mcc-reset-session --session "$SESSION_A"
|
||||
mcc-reset-session --session "$SESSION_B"
|
||||
mcc-build
|
||||
mc-start "$VERSION" >/dev/null
|
||||
wait_for_server_ready "$VERSION"
|
||||
|
||||
mcc-debug -v "$VERSION" --session "$SESSION_A" --username "$USER_A" --file-input --no-build
|
||||
mcc-debug -v "$VERSION" --session "$SESSION_B" --username "$USER_B" --file-input --no-build
|
||||
|
||||
grep -Fq "Server was successfully joined" "$(_mcc_session_log_file "$SESSION_A")"
|
||||
grep -Fq "Server was successfully joined" "$(_mcc_session_log_file "$SESSION_B")"
|
||||
mcc-cmd --session "$SESSION_A" "debug state"
|
||||
mcc-cmd --session "$SESSION_B" "debug state"
|
||||
|
||||
mcc-kill --session "$SESSION_A"
|
||||
tmux has-session -t "$(_mcc_tmux_session_name "$SESSION_B")"
|
||||
mc-log "$VERSION" 50 | grep -Fq "$USER_B joined the game"
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行脚本，确认它先因为新参数或旧的共享路径逻辑而失败**
|
||||
|
||||
Run: `bash .skills/mcc-integration-testing/scripts/run_parallel_session_smoke_test.sh 1.21.11`
|
||||
|
||||
Expected: FAIL，错误类似 `Unknown option: --session`、固定 `mcc_input.txt` 被共用，或者只有一个客户端会话存活
|
||||
|
||||
- [ ] **Step 3: 把 `reset_shared_test_state.sh` 缩回“只管共享服务器”，不要再删除 repo 根下 `mcc_input.txt`**
|
||||
|
||||
```bash
|
||||
if [[ $# -eq 0 || "${1:-}" == "--all" ]]; then
|
||||
while IFS= read -r session_name; do
|
||||
[[ -z "$session_name" ]] && continue
|
||||
kill_named_session "$session_name"
|
||||
done < <(tmux list-sessions 2>/dev/null | awk -F: '/^mc-/{print $1}' || true)
|
||||
|
||||
while IFS= read -r pipe_path; do
|
||||
[[ -z "$pipe_path" ]] && continue
|
||||
if [[ ! -p "$pipe_path" ]]; then
|
||||
rm -f "$pipe_path"
|
||||
fi
|
||||
done < <(find "$MCC_SERVERS" -maxdepth 2 -name 'stdin.pipe' 2>/dev/null || true)
|
||||
fi
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 更新现有 integration 脚本，让它们使用 session-specific input/log，而不是 repo 根下固定文件**
|
||||
|
||||
```bash
|
||||
SESSION="creative-e2e-${SERVER_DIR//\//_}"
|
||||
USERNAME="$(_mcc_resolve_username "$SESSION")"
|
||||
INPUT_FILE="$(_mcc_session_input_file "$SESSION")"
|
||||
MCC_LOG="$(_mcc_session_log_file "$SESSION")"
|
||||
|
||||
rm -rf "$(_mcc_session_root "$SESSION")"
|
||||
mkdir -p "$(_mcc_session_root "$SESSION")"
|
||||
|
||||
(
|
||||
cd "$REPO_ROOT"
|
||||
MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release --no-build -- \
|
||||
"$CFG" \
|
||||
"$USERNAME" \
|
||||
- \
|
||||
"localhost:$SERVER_PORT" \
|
||||
> "$MCC_LOG" 2>&1
|
||||
) &
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 重新运行并行 smoke test 与现有 creative/full-spectrum 回归**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
bash .skills/mcc-integration-testing/scripts/run_parallel_session_smoke_test.sh 1.21.11
|
||||
bash tools/run-creative-e2e.sh 1.21.11 1.21.11 modern
|
||||
bash .skills/mcc-integration-testing/scripts/run_full_spectrum_test.sh 1.21.11
|
||||
```
|
||||
|
||||
Expected: 三个脚本都 PASS；并行 smoke test 中一个 session 被 kill 后，另一个 session 和共享服务器继续存活
|
||||
|
||||
- [ ] **Step 6: 提交这一小步**
|
||||
|
||||
```bash
|
||||
git add .skills/mcc-integration-testing/scripts/reset_shared_test_state.sh \
|
||||
.skills/mcc-integration-testing/scripts/run_full_spectrum_test.sh \
|
||||
.skills/mcc-integration-testing/scripts/run_parallel_session_smoke_test.sh \
|
||||
tools/run-creative-e2e.sh
|
||||
git commit -m "test: cover shared server with isolated MCC sessions"
|
||||
```
|
||||
|
||||
### Task 6: 更新文档，并给出两个 worktree 并行调试的标准操作流程
|
||||
|
||||
**Files:**
|
||||
- Modify: `tools/README.md`
|
||||
- Modify: `docs/guide/ai-assisted-development.md`
|
||||
- Modify: `.skills/mcc-dev-workflow/SKILL.md`
|
||||
|
||||
- [ ] **Step 1: 在文档里先补“共享服务器，隔离 MCC 会话”的核心规则**
|
||||
|
||||
```md
|
||||
## Shared Server, Isolated MCC Sessions
|
||||
|
||||
- `mc-*` commands operate on the shared local Minecraft server.
|
||||
- `mcc-*` commands operate on one MCC client session.
|
||||
- Default `session` = current worktree name.
|
||||
- Default username is derived from `session`, so two worktrees can join the same server without kicking each other.
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 在 `mcc-dev-workflow` 文档和 skill 里补两个 worktree 的真实示例**
|
||||
|
||||
````md
|
||||
```bash
|
||||
# worktree A
|
||||
cd ~/Minecraft/Minecraft-Console-Client
|
||||
source tools/mcc-env.sh
|
||||
mc-start 1.21.11
|
||||
mcc-debug -v 1.21.11 --file-input
|
||||
|
||||
# worktree B
|
||||
cd ~/Minecraft/Minecraft-Console-Client-foo
|
||||
source tools/mcc-env.sh
|
||||
mcc-debug -v 1.21.11 --file-input
|
||||
|
||||
# Each worktree gets:
|
||||
# - its own session
|
||||
# - its own username
|
||||
# - its own log/input/config/tmux session
|
||||
# - the same shared server
|
||||
```
|
||||
````
|
||||
|
||||
- [ ] **Step 3: 在文档里加入 tmpfs 构建模式与清理命令**
|
||||
|
||||
````md
|
||||
### tmpfs build mode
|
||||
|
||||
```bash
|
||||
source tools/mcc-env.sh
|
||||
export MCC_BUILD_MODE=tmpfs
|
||||
mcc-build
|
||||
mcc-build-clean
|
||||
```
|
||||
|
||||
When `MCC_BUILD_MODE=tmpfs`, build outputs are redirected to `/dev/shm/mcc-build/<worktree>/` on Linux, or `${TMPDIR:-/tmp}/mcc-build/<worktree>/` if `/dev/shm` is unavailable.
|
||||
````
|
||||
|
||||
- [ ] **Step 4: 跑最终验证矩阵并保存关键输出**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
bash tools/test-mcc-env.sh
|
||||
source tools/mcc-env.sh && unset MCC_BUILD_MODE && mcc-build
|
||||
source tools/mcc-env.sh && export MCC_BUILD_MODE=tmpfs && mcc-build
|
||||
bash .skills/mcc-integration-testing/scripts/run_parallel_session_smoke_test.sh 1.21.11
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
```text
|
||||
PASS
|
||||
Build succeeded.
|
||||
Build succeeded.
|
||||
parallel session smoke: PASS
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 提交文档与最终验证结果**
|
||||
|
||||
```bash
|
||||
git add tools/README.md docs/guide/ai-assisted-development.md .skills/mcc-dev-workflow/SKILL.md
|
||||
git commit -m "docs: document shared server and isolated MCC sessions"
|
||||
```
|
||||
|
||||
### Self-Review Checklist
|
||||
|
||||
- [ ] 计划里的 `session`、`username`、`MCC_BUILD_MODE`、`MCC_BUILD_ROOT` 命名在所有任务中一致
|
||||
- [ ] 没有任何步骤重新引入 repo 根下固定 `mcc_input.txt`
|
||||
- [ ] 没有任何步骤重新使用 `pkill -f "MinecraftClient"`
|
||||
- [ ] 并行 smoke test 明确验证“共享服务器 + 双会话 + 单边 kill 不影响另一边”
|
||||
- [ ] tmpfs build 任务明确覆盖了当前已知的 `obj` 外置重复编译问题
|
||||
|
|
@ -1,316 +0,0 @@
|
|||
# Shared Server, Isolated MCC Sessions Design
|
||||
|
||||
## Goal
|
||||
|
||||
Keep local Minecraft server instances shared across worktrees while making MCC debug sessions fully isolated by default.
|
||||
|
||||
The desired workflow is:
|
||||
|
||||
- Multiple Git worktrees can build in parallel without output collisions.
|
||||
- One shared local test server can be reused by multiple MCC clients.
|
||||
- Multiple MCC debug sessions can connect to that shared server at the same time without clobbering each other's tmux sessions, logs, temp config, input file, PID tracking, or usernames.
|
||||
|
||||
## Background
|
||||
|
||||
The current repository tooling mixes two different scopes:
|
||||
|
||||
- Shared infrastructure state, such as local server jars and tmux server sessions
|
||||
- Per-MCC-client debug state, such as `mcc_input.txt`, `/tmp/mcc-debug`, and the fixed `mcc-debug` tmux session
|
||||
|
||||
That works for one active workspace, but it breaks down once multiple worktrees are used at the same time.
|
||||
|
||||
Today the main problems are:
|
||||
|
||||
1. `MCC_REPO` can leak from one shell into another and point helper commands at the wrong worktree.
|
||||
2. `mcc-debug.sh` writes all temp artifacts into the same `/tmp/mcc-debug` directory.
|
||||
3. MCC tmux sessions use the same fixed name, `mcc-debug`.
|
||||
4. MCC helper commands such as `mcc-kill` operate globally instead of targeting one debug session.
|
||||
5. The default MCC username is fixed, so two clients connecting to the same server will kick each other.
|
||||
6. Build outputs live inside each worktree by default, which is correct for isolation, but the workflow does not offer an intentional tmpfs-backed fast path for machines with large RAM.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not isolate or duplicate server assets by worktree.
|
||||
- Do not support multiple independent servers with the same version name running in parallel in this change.
|
||||
- Do not redesign the Minecraft runtime or MCC account model.
|
||||
- Do not make tmpfs build output mandatory.
|
||||
|
||||
## Design Principles
|
||||
|
||||
- Shared resources stay explicit and few.
|
||||
- Per-session MCC state is isolated by default.
|
||||
- Repo discovery is local to each script, not inherited from an ambient shell variable.
|
||||
- Existing workflows should keep working with minimal changes when only one MCC session is active.
|
||||
- Performance optimizations must not undermine correctness or isolation.
|
||||
|
||||
## State Model
|
||||
|
||||
### Shared State
|
||||
|
||||
The following remain shared across worktrees and shells:
|
||||
|
||||
- `MCC_SERVERS`, when explicitly set by the user
|
||||
- Default server root at `<repo>/MinecraftOfficial/downloads` when `MCC_SERVERS` is not set
|
||||
- Server tmux session names, still keyed by Minecraft version, for example `mc-1_21_11`
|
||||
- Server stdin pipes and world data under the shared server root
|
||||
- RCON access to the shared server
|
||||
|
||||
### Per-Session MCC State
|
||||
|
||||
Each MCC debug session is keyed by a session identifier.
|
||||
|
||||
The following must be isolated per session:
|
||||
|
||||
- MCC tmux session
|
||||
- Temp config
|
||||
- MCC log
|
||||
- MCC input file
|
||||
- MCC PID file
|
||||
- Session metadata used by helper commands
|
||||
- Default username
|
||||
|
||||
### Per-Worktree Build State
|
||||
|
||||
Each worktree gets its own build output root.
|
||||
|
||||
Build isolation is keyed by worktree name, not MCC session name, so multiple MCC sessions from one worktree can share the same compiled binaries.
|
||||
|
||||
## Naming and Identity
|
||||
|
||||
### Session Name
|
||||
|
||||
- A new `session` concept is introduced for all `mcc-*` commands.
|
||||
- If the user passes `--session NAME`, that value is used.
|
||||
- Otherwise the default is the current Git worktree name.
|
||||
- If a worktree name cannot be resolved, the fallback is the basename of the current repo root.
|
||||
|
||||
### Username
|
||||
|
||||
- If the user passes `--username NAME`, that value is used.
|
||||
- Otherwise the username is derived from the resolved `session`.
|
||||
- The derived name must:
|
||||
- use only Minecraft-safe characters already accepted by the existing config flow
|
||||
- be deterministic
|
||||
- be at most 16 characters
|
||||
- remain stable for the same session across runs
|
||||
|
||||
Recommended derivation:
|
||||
|
||||
1. Lowercase the session name.
|
||||
2. Replace invalid characters with underscores.
|
||||
3. Prefix with `mcc_`.
|
||||
4. If the result is longer than 16 characters, keep the first 11 characters and append `_` plus the first 4 hexadecimal characters of the SHA-1 of the normalized session string.
|
||||
|
||||
Example:
|
||||
|
||||
- `feature-ai` -> `mcc_feature_ai`
|
||||
- `very-long-worktree-name` -> `mcc_veryl_ab12`
|
||||
|
||||
This truncation algorithm must be implemented and tested exactly as written so future changes do not silently rename active debug identities.
|
||||
|
||||
## Repo and Server Root Resolution
|
||||
|
||||
### Repo Root
|
||||
|
||||
Helper scripts must stop exporting `MCC_REPO` as shell-global state.
|
||||
|
||||
Instead:
|
||||
|
||||
- Each script resolves its own repo root from its own location.
|
||||
- Shared shell helper functions may cache that resolved path internally, but not as a required ambient variable.
|
||||
- Child commands should receive explicit paths or recompute the repo root themselves.
|
||||
|
||||
This removes the current failure mode where a shell sourced from one clone or worktree accidentally drives tools in another.
|
||||
|
||||
### Server Root
|
||||
|
||||
`MCC_SERVERS` stays as the supported override for the shared server root.
|
||||
|
||||
Resolution order:
|
||||
|
||||
1. If `MCC_SERVERS` is set, use it.
|
||||
2. Otherwise use `<resolved repo root>/MinecraftOfficial/downloads`.
|
||||
|
||||
This keeps the useful part of the current workflow: one intentionally shared set of server assets.
|
||||
|
||||
## File and Process Layout
|
||||
|
||||
### MCC Session Root
|
||||
|
||||
Each MCC session gets a unique root directory:
|
||||
|
||||
- `${TMPDIR:-/tmp}/mcc-debug/<session>/`
|
||||
|
||||
That directory contains:
|
||||
|
||||
- `MinecraftClient.debug.ini`
|
||||
- `mcc-debug.log`
|
||||
- `mcc_input.txt`
|
||||
- `mcc.pid`
|
||||
- `session.meta`
|
||||
|
||||
### tmux Sessions
|
||||
|
||||
MCC tmux sessions must be renamed from the fixed `mcc-debug` to a session-scoped name, for example:
|
||||
|
||||
- `mcc-<session>`
|
||||
|
||||
Server tmux sessions remain version-scoped:
|
||||
|
||||
- `mc-<version>`
|
||||
|
||||
### Kill and Reset Scope
|
||||
|
||||
- `mcc-kill --session X` only stops the MCC process and tmux session for `X`.
|
||||
- A new `mcc-reset-session` command should clear only session-scoped files and tmux sessions.
|
||||
- Existing shared server reset logic must continue to operate on server state only.
|
||||
- No `mcc-*` command may kill all `MinecraftClient` processes by pattern.
|
||||
|
||||
## Command Interface
|
||||
|
||||
### Shared Server Commands
|
||||
|
||||
These remain shared-resource commands and do not take `--session`:
|
||||
|
||||
- `mc-start`
|
||||
- `mc-stop`
|
||||
- `mc-log`
|
||||
- `mc-rcon`
|
||||
- `mc-wait-ready`
|
||||
- `mc-wait-stop`
|
||||
|
||||
### Session-Scoped MCC Commands
|
||||
|
||||
These commands gain `--session`, and where applicable `--username`:
|
||||
|
||||
- `mcc-debug`
|
||||
- `mcc-run`
|
||||
- `mcc-tui`
|
||||
- `mcc-cmd`
|
||||
- `mcc-log-mcc`
|
||||
- `mcc-state`
|
||||
- `mcc-kill`
|
||||
|
||||
Expected defaults:
|
||||
|
||||
- `--session`: current worktree name
|
||||
- `--username`: derived from session
|
||||
|
||||
Example commands:
|
||||
|
||||
```bash
|
||||
mcc-debug -v 1.21.11 --session alice-a --username AliceA --file-input
|
||||
mcc-debug -v 1.21.11 --session alice-b --username AliceB --file-input
|
||||
mcc-cmd --session alice-a "debug state"
|
||||
mcc-log-mcc --session alice-b
|
||||
mcc-kill --session alice-a
|
||||
mcc-reset-session --session alice-b
|
||||
```
|
||||
|
||||
## Build Output Isolation
|
||||
|
||||
### Base Rule
|
||||
|
||||
Build outputs must be isolated by worktree, not mixed across worktrees.
|
||||
|
||||
This should be implemented by introducing a build root override passed through the helper scripts into `dotnet build` and `dotnet run`, without requiring users to manually edit project files per worktree.
|
||||
|
||||
The important behavior is:
|
||||
|
||||
- Worktree A writes to build root A
|
||||
- Worktree B writes to build root B
|
||||
- Both can build concurrently without sharing `bin/obj`
|
||||
|
||||
### tmpfs Acceleration
|
||||
|
||||
Add an opt-in tmpfs-backed build root for machines with large RAM.
|
||||
|
||||
Suggested layout:
|
||||
|
||||
- `/dev/shm/mcc-build/<worktree>/` on Linux
|
||||
- fallback to `${TMPDIR:-/tmp}/mcc-build/<worktree>/` when `/dev/shm` is unavailable
|
||||
|
||||
Requirements:
|
||||
|
||||
- tmpfs mode is optional, not mandatory
|
||||
- the resolved build root must be printed in debug output
|
||||
- a new `mcc-build-clean` command should clear build outputs for the current worktree
|
||||
- helper scripts must fail clearly if the chosen build root is not writable
|
||||
|
||||
### Compatibility
|
||||
|
||||
If tmpfs mode is disabled, behavior should remain functionally equivalent to today, except for the added worktree-aware path selection.
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
- Existing single-session workflows should still work without requiring `--session`.
|
||||
- Existing external `MCC_SERVERS` setups must continue to work.
|
||||
- Existing server-side helper scripts should keep their public behavior.
|
||||
- Existing documentation examples can be updated gradually, but the basic commands should remain recognizable.
|
||||
|
||||
## Error Handling
|
||||
|
||||
The tooling should fail early and clearly for:
|
||||
|
||||
- missing server root
|
||||
- invalid or empty session name
|
||||
- invalid derived username after normalization
|
||||
- requested tmux session already in use by a different live MCC process
|
||||
- unwritable tmpfs or build root
|
||||
- missing PID file on targeted kill operations
|
||||
|
||||
When possible, the error should print the resolved repo root, shared server root, session name, username, and session root to make misconfiguration obvious.
|
||||
|
||||
## Validation Plan
|
||||
|
||||
### Manual Verification Matrix
|
||||
|
||||
1. Build from two different worktrees at the same time and confirm isolated output roots.
|
||||
2. Start one shared `1.21.11` server and confirm only one `mc-1_21_11` session exists.
|
||||
3. Launch two MCC sessions from two different worktrees without explicit usernames and confirm distinct derived usernames.
|
||||
4. Join both clients to the shared server and confirm neither client disconnects the other.
|
||||
5. Send different commands through each session's input file and confirm only the intended client responds.
|
||||
6. Tail each session's log and confirm no cross-session log mixing.
|
||||
7. Kill one MCC session and confirm:
|
||||
- the other MCC session stays connected
|
||||
- the shared server remains running
|
||||
8. Enable tmpfs build mode in one worktree and verify outputs are written to the resolved tmpfs path.
|
||||
9. Rebuild after cleaning tmpfs outputs and confirm the worktree still functions.
|
||||
|
||||
### Regression Checks
|
||||
|
||||
- Single-session debug loop still works with no explicit `--session`
|
||||
- Shared server helpers still work when `MCC_SERVERS` points outside the repo
|
||||
- TUI mode still works inside tmux with session-specific naming
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
The most likely files to change are:
|
||||
|
||||
- `tools/mcc-env.sh`
|
||||
- `tools/mcc-debug.sh`
|
||||
- `tools/start-server.sh`
|
||||
- `.skills/mcc-integration-testing/scripts/preflight_test_env.sh`
|
||||
- `.skills/mcc-integration-testing/scripts/reset_shared_test_state.sh`
|
||||
- `tools/README.md`
|
||||
- `docs/guide/ai-assisted-development.md`
|
||||
- `.skills/mcc-dev-workflow/SKILL.md`
|
||||
|
||||
If build-output redirection is implemented through MSBuild configuration rather than pure shell arguments, related project or props files may also need changes.
|
||||
|
||||
## Open Decisions Resolved In This Design
|
||||
|
||||
- Keep `MCC_SERVERS`: yes
|
||||
- Keep `MCC_REPO` as shell-global state: no
|
||||
- Shared server instances across worktrees: yes
|
||||
- MCC debug isolation keyed by explicit `session`: yes
|
||||
- Default `session`: current worktree name
|
||||
- Default username: derived from session
|
||||
- Build output isolation key: current worktree
|
||||
- tmpfs build output: opt-in optimization
|
||||
|
||||
## Summary
|
||||
|
||||
The resulting workflow intentionally shares the expensive and durable part of local MCC development, the server installation and running server instance, while isolating the volatile and user-specific part, the MCC client debug session and build outputs.
|
||||
|
||||
That gives parallel worktree development without forcing duplicate local servers, while removing the current collisions around shell state, tmux naming, temp files, input routing, and username reuse.
|
||||
Loading…
Add table
Add a link
Reference in a new issue