feat: 서버 임베드 모듈 + maestro-server CLI (플러그인화 1단계)

[redsunjin]

Summary

플러그인화 트랙 1단계 — Claude Code 플러그인·VS Code 확장·CLI가 공용으로 쓸 서버 임베드 코어입니다. 스펙: docs/superpowers/specs/2026-07-22-server-embed-design.md

lib/server-embed.mjs — startMaestroServer(options)

• maestro-server.js를 자식 프로세스로 스폰하고 /health로 기동 확인 (서버 본체 무변경 — in-process 리팩터 대신 supervisor 래핑으로 회귀 0)
• reuseExisting(기본 on): 이미 떠 있는 Maestro 서버 재사용(핸들 비소유 — stop은 no-op), 비-Maestro 프로세스가 포트 점유 시 명확한 에러
• 옵션: port/host/repoPath/mdns/token/env/onLog/startTimeoutMs. 실패 시 최근 로그 tail을 담은 에러. 멱등 stop(SIGTERM→2s→SIGKILL), waitForExit()

bin/maestro-server.mjs — 한 줄 실행 CLI

• --port --host --repo --no-mdns --token --help (신규 의존성 0, node:util parseArgs)
• cwd가 git 레포면 자동 지정, package.json bin 등록(퍼블리시/npm link 시 npx maestro-server)
• ready 출력 전 시그널 핸들러 등록 — 소비자가 ready 직후 보낸 SIGTERM에도 서버 고아화 없음(테스트로 재현·수정)

Test plan

• tests/server-embed.test.mjs 5 tests: 기동/멱등 stop, 재사용(비소유 stop 안전), mdns off, 비-Maestro 포트 에러, CLI 스모크(SIGTERM 전파)
• 서버 65 tests / UI 125 tests / e2e 5 tests / 빌드 — 전부 PASS (본체 무변경 회귀 확인)

다음 단계: 이 모듈을 소비하는 Claude Code 플러그인(별도 스펙 — monitors 기반 서버 자동 기동 + Stop 훅 + /maestro 스킬)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ab742a74d2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Validate the requested repo before reusing a server

When the default port already hosts Maestro for repository A and a caller requests repoPath B, this branch returns the existing server without comparing probe.health.project.path to the requested path. The returned handle therefore claims success while subsequent operations still default to A via runtimeProjectState.path, potentially applying approvals or merges to the wrong repository. Reuse should be refused unless the requested and active repositories resolve to the same path.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Bracket IPv6 hosts when constructing probe URLs

When host is an unbracketed IPv6 literal such as ::1, which is valid for server.listen() and accepted by the CLI, this produces the invalid URL http://::1:<port>. Every health probe is consequently treated as unreachable even though the child binds successfully, and the supervisor eventually kills the healthy server and reports a startup timeout. Preserve the unbracketed bind host but bracket IPv6 literals when constructing HTTP and WebSocket URLs.

Useful? React with 👍 / 👎.