Skip to content

Commit e9f87ad

Browse files
ToolboxAidToolboxAid
authored
Merge pull request #250 from ToolboxAid/PR_26171_ALFA_009-team-aware-bootstrap
PR_26171_ALFA_009-team-aware-bootstrap
2 parents a4e671e + 69c3fba commit e9f87ad

11 files changed

Lines changed: 1516 additions & 48 deletions

‎dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_branch-validation.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# PR_26171_ALFA_009 Branch Validation
2+
3+
| Check | Status | Evidence |
4+
| --- | --- | --- |
5+
| Failed dirty attempt recorded | PASS | Dirty files listed in PR report before reset. |
6+
| Failed dirty attempt discarded | PASS | Ran `git reset --hard` and `git clean -fd`. |
7+
| Clean `main` confirmed before implementation | PASS | `main...origin/main` was `0 0`; worktree was clean. |
8+
| Branch recreated from `main` | PASS | Current branch is `PR_26171_ALFA_009-team-aware-bootstrap` at source commit `a4e671ec8`. |
9+
| Scope check | PASS | Changes limited to approved bootstrap scripts, package scripts, tests, and reports. |
10+
| Validation | PASS | Targeted validation commands passed. |

‎dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_manual-validation-notes.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# PR_26171_ALFA_009 Manual Validation Notes
2+
3+
## Primary Alfa Owner Command
4+
5+
```powershell
6+
npm run dev:bootstrap -- --team alfa
7+
```
8+
9+
Expected diagnostics:
10+
11+
- `Team: alfa`
12+
- `Role: owner`
13+
- `Web URL: http://127.0.0.1:5510`
14+
- `API URL: http://127.0.0.1:5511/api`
15+
- `Browser launch: http://127.0.0.1:5510/index.html`
16+
17+
## Primary Alfa Codex Command
18+
19+
```powershell
20+
npm run dev:bootstrap -- --team alfa --role codex
21+
```
22+
23+
Expected diagnostics:
24+
25+
- `Team: alfa`
26+
- `Role: codex`
27+
- `Web URL: http://127.0.0.1:5512`
28+
- `API URL: http://127.0.0.1:5513/api`
29+
- `Browser launch: skipped for codex role`
30+
31+
## Legacy Command
32+
33+
```powershell
34+
npm run dev:local-api
35+
```
36+
37+
Expected result:
38+
39+
- Legacy startup remains available.
40+
- The legacy command still runs `node --use-system-ca ./dev/scripts/start-local-api-server.mjs`.
41+
42+
## Other Startup Commands
43+
44+
```powershell
45+
npm run dev:bootstrap -- --team owner
46+
npm run dev:bootstrap -- --team bravo
47+
npm run dev:bootstrap -- --team charlie
48+
npm run dev:bootstrap -- charlie
49+
npm run dev:bootstrap -- --team delta
50+
npm run dev:bootstrap -- --team echo
51+
npm run dev:bootstrap -- --team foxtrot
52+
npm run dev:bootstrap -- --team golf
53+
npm run dev:bootstrap -- --team hotel
54+
```
55+
56+
For Charlie, both forms should show:
57+
58+
- `Team: charlie`
59+
- `Web URL: http://127.0.0.1:5530`
60+
- `API URL: http://127.0.0.1:5531/api`
61+
- `Browser launch: http://127.0.0.1:5530/index.html`
62+
63+
If `.env` or the current shell already has `GAMEFOUNDRY_SITE_URL` or `GAMEFOUNDRY_API_URL`, bootstrap should still show the resolved team/role ports in diagnostics and launch the browser from the computed `GAMEFOUNDRY_SITE_URL`.
64+
65+
## Failure Checks
66+
67+
```powershell
68+
npm run dev:bootstrap -- --team omega
69+
npm run dev:bootstrap -- --team alfa --role reviewer
70+
```
71+
72+
Expected result:
73+
74+
- Unknown team fails with the supported team list.
75+
- Unknown role fails with the supported role list.

‎dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_report.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# PR_26171_ALFA_009 Team-Aware Bootstrap Report
2+
3+
## Purpose
4+
5+
Implement team-aware local dev bootstrap commands with role-aware port assignment while preserving the legacy local API command.
6+
7+
## Reset Note
8+
9+
Before rebuilding from clean `main`, the failed dirty attempt included:
10+
11+
- `dev/reports/codex_changed_files.txt`
12+
- `dev/reports/codex_review.diff`
13+
- `dev/scripts/start-local-api-server.mjs`
14+
- `package.json`
15+
- untracked bootstrap reports
16+
- untracked `dev/scripts/start-dev.mjs`
17+
- untracked `dev/scripts/team-port-config.mjs`
18+
- untracked `dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs`
19+
20+
Per OWNER instruction, those uncommitted changes were discarded with `git reset --hard` and `git clean -fd`, then this branch was recreated from clean `main`.
21+
22+
## Implementation Summary
23+
24+
- Added `npm run dev:bootstrap`.
25+
- Added `npm run dev:api`.
26+
- Added `npm run dev:web`.
27+
- Preserved `npm run dev:local-api` unchanged as the legacy alias.
28+
- Added `dev/scripts/team-port-config.mjs` for full team name and role-aware port resolution.
29+
- Added `dev/scripts/start-dev.mjs` as the bootstrap orchestrator.
30+
- Added focused node tests for team resolution, role offsets, invalid team/role validation, script wiring, `.env` loading behavior, and bootstrap diagnostics.
31+
- Added automatic browser launch for owner-role `dev:bootstrap` after the API and web servers are both ready.
32+
- Skipped automatic browser launch for the `codex` role.
33+
- Fixed npm argument forwarding/parsing so both `--team charlie` and positional `charlie` select the same team after the package script's `--mode bootstrap` argument.
34+
- Treats `.env` `GAMEFOUNDRY_SITE_URL` and `GAMEFOUNDRY_API_URL` as legacy/default local values for bootstrap mode, then overwrites runtime URLs from the resolved team/role ports.
35+
36+
## Supported Teams
37+
38+
`owner`, `alfa`, `bravo`, `charlie`, `delta`, `echo`, `foxtrot`, `golf`, `hotel`
39+
40+
## Supported Roles
41+
42+
`owner`, `codex`
43+
44+
## Port Mapping
45+
46+
`owner` role uses base ports. `codex` role uses base ports plus 2.
47+
48+
| Team | Owner Web | Owner API | Codex Web | Codex API |
49+
| --- | ---: | ---: | ---: | ---: |
50+
| owner | 5500 | 5501 | 5502 | 5503 |
51+
| alfa | 5510 | 5511 | 5512 | 5513 |
52+
| bravo | 5520 | 5521 | 5522 | 5523 |
53+
| charlie | 5530 | 5531 | 5532 | 5533 |
54+
| delta | 5540 | 5541 | 5542 | 5543 |
55+
| echo | 5550 | 5551 | 5552 | 5553 |
56+
| foxtrot | 5560 | 5561 | 5562 | 5563 |
57+
| golf | 5570 | 5571 | 5572 | 5573 |
58+
| hotel | 5580 | 5581 | 5582 | 5583 |
59+
60+
## Commands Added
61+
62+
```powershell
63+
npm run dev:bootstrap
64+
npm run dev:api
65+
npm run dev:web
66+
```
67+
68+
## Legacy Command Preserved
69+
70+
```powershell
71+
npm run dev:local-api
72+
```
73+
74+
## Exact Startup Commands
75+
76+
```powershell
77+
npm run dev:bootstrap -- --team owner
78+
npm run dev:bootstrap -- --team alfa
79+
npm run dev:bootstrap -- --team bravo
80+
npm run dev:bootstrap -- --team charlie
81+
npm run dev:bootstrap -- --team delta
82+
npm run dev:bootstrap -- --team echo
83+
npm run dev:bootstrap -- --team foxtrot
84+
npm run dev:bootstrap -- --team golf
85+
npm run dev:bootstrap -- --team hotel
86+
```
87+
88+
Codex role example:
89+
90+
```powershell
91+
npm run dev:bootstrap -- --team alfa --role codex
92+
```
93+
94+
## Browser Launch Behavior
95+
96+
- `owner` role launches the browser automatically to the selected team's `index.html`.
97+
- `codex` role skips browser launch.
98+
- Browser launch happens only after both API and web servers are ready.
99+
- The Alfa owner launch target is `http://127.0.0.1:5510/index.html`.
100+
- The Alfa codex browser launch is skipped while using web `5512` and API `5513`.
101+
- The Charlie launch target is `http://127.0.0.1:5530/index.html` for both `npm run dev:bootstrap -- --team charlie` and `npm run dev:bootstrap -- charlie`.
102+
- Computed team/role ports override any `.env` or inherited process `GAMEFOUNDRY_SITE_URL` / `GAMEFOUNDRY_API_URL` values loaded before bootstrap startup.
103+
- Bootstrap runtime sets `GAMEFOUNDRY_SITE_URL=http://127.0.0.1:<webPort>` and `GAMEFOUNDRY_API_URL=http://127.0.0.1:<apiPort>/api` after team/role resolution.
104+
105+
## Files Changed
106+
107+
- `package.json` - updated
108+
- `dev/scripts/start-dev.mjs` - added
109+
- `dev/scripts/team-port-config.mjs` - added
110+
- `dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs` - added
111+
112+
## Validation Summary
113+
114+
All requested targeted validation passed.

‎dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_requirement-checklist.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# PR_26171_ALFA_009 Requirement Checklist
2+
3+
| Requirement | Status | Evidence |
4+
| --- | --- | --- |
5+
| Start from clean `main` | PASS | Reset failed attempt, switched to `main`, pulled fast-forward, confirmed `main...origin/main` was `0 0`, then recreated branch. |
6+
| Add `npm run dev:bootstrap` | PASS | Added to `package.json`. |
7+
| Keep `npm run dev:local-api` as legacy alias | PASS | Existing command remains unchanged. |
8+
| Add `npm run dev:api` | PASS | Added to `package.json`. |
9+
| Add `npm run dev:web` | PASS | Added to `package.json`. |
10+
| Create `dev/scripts/start-dev.mjs` | PASS | Added orchestrator. |
11+
| Create `dev/scripts/team-port-config.mjs` | PASS | Added team/role port resolver. |
12+
| Support full team names only | PASS | Supported teams are owner, alfa, bravo, charlie, delta, echo, foxtrot, golf, hotel. |
13+
| Support roles owner/codex | PASS | Role resolver supports owner and codex only. |
14+
| Codex role uses base ports plus 2 | PASS | Covered by targeted unit test. |
15+
| Do not use unsupported old team names | PASS | Scan returned no matches in new bootstrap files. |
16+
| Do not use single-letter public team commands | PASS | Scan returned no matches in new bootstrap files. |
17+
| Validate unknown team names | PASS | `omega` fails clearly with supported team list. |
18+
| Validate unknown role names | PASS | `reviewer` fails clearly with supported role list. |
19+
| Support `--team` argument forwarding | PASS | `npm run dev:bootstrap -- --team charlie` resolves Charlie ports. |
20+
| Support positional team forwarding | PASS | `npm run dev:bootstrap -- charlie` resolves Charlie ports. |
21+
| Support positional team/role forwarding | PASS | `npm run dev:bootstrap -- alfa codex` resolves Alfa codex ports and skips browser launch. |
22+
| Prevent `.env` and process URL port override | PASS | Unit and live startup tests confirm computed team/role ports overwrite loaded or inherited API/site URL port values. |
23+
| Load environment | PASS | Orchestrator loads `.env` values without overriding existing environment values. |
24+
| Resolve team ports | PASS | Unit tests cover all teams and both roles. |
25+
| Start Local API | PASS | `dev:bootstrap` starts the existing Local API server on resolved API port. |
26+
| Start web server when requested | PASS | `dev:bootstrap` starts web plus API; `dev:web` mode is wired. |
27+
| Print startup diagnostics | PASS | Diagnostics include mode, team, role, web URL, API URL, environment source, supported teams, and supported roles. |
28+
| Owner role launches browser automatically | PASS | Live startup validation opened `http://127.0.0.1:5510/index.html` after API and web were ready. |
29+
| Codex role skips browser launch | PASS | Live startup validation reported `Browser launch: skipped for codex role`. |
30+
| Wait for both servers before browser launch | PASS | Targeted unit test asserts API ready, web ready, then browser launch order. |
31+
| Preserve legacy behavior | PASS | `dev:local-api` command unchanged and startup validation passed. |
32+
| No unrelated cleanup | PASS | Scope limited to package scripts, new dev scripts, targeted tests, and reports. |

‎dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_validation-report.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# PR_26171_ALFA_009 Validation Report
2+
3+
## Validation Results
4+
5+
| Command | Result | Notes |
6+
| --- | --- | --- |
7+
| `node --check dev/scripts/team-port-config.mjs` | PASS | Syntax valid. |
8+
| `node --check dev/scripts/start-dev.mjs` | PASS | Syntax valid. |
9+
| `node --check dev/scripts/start-local-api-server.mjs` | PASS | Legacy startup entrypoint remains valid. |
10+
| `node --check dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs` | PASS | Test syntax valid. |
11+
| `node ./dev/scripts/run-node-test-files.mjs dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs dev/tests/dev-runtime/LocalApiStartupLogging.test.mjs` | PASS | 2 targeted files passed; 14 subtests passed. |
12+
| Unsupported team token scan in new bootstrap files | PASS | No unsupported old team names or single-letter public team commands found in package scripts, bootstrap scripts, or targeted bootstrap tests. |
13+
| `npm run validate:canonical-structure` | PASS | Canonical repository structure guardrail passed. |
14+
| `npm run dev:bootstrap -- --team alfa` | PASS | Started with team `alfa`, role `owner`, web `5510`, API `5511`, launched browser to `http://127.0.0.1:5510/index.html`, then process tree was stopped. |
15+
| `npm run dev:bootstrap -- --team alfa --role codex` | PASS | Started with team `alfa`, role `codex`, web `5512`, API `5513`, skipped browser launch, then process tree was stopped. |
16+
| `npm run dev:bootstrap -- alfa codex` | PASS | Positional team/role forwarding selected team `alfa`, role `codex`, web `5512`, API `5513`, and skipped browser launch. |
17+
| `npm run dev:bootstrap -- --team charlie` with inherited stale URL env values | PASS | Started with team `charlie`, role `owner`, web `5530`, API `5531`, launched browser to `http://127.0.0.1:5530/index.html`, and ignored inherited `GAMEFOUNDRY_SITE_URL` / `GAMEFOUNDRY_API_URL` port values before process cleanup. |
18+
| `npm run dev:bootstrap -- charlie` | PASS | Positional team forwarding selected team `charlie`, web `5530`, API `5531`, and browser target `http://127.0.0.1:5530/index.html`. |
19+
| `npm run dev:bootstrap -- --team bravo` | PASS | Started with team `bravo`, role `owner`, web `5520`, API `5521`, and browser target `http://127.0.0.1:5520/index.html`. |
20+
| `npm run dev:bootstrap -- --team omega` | PASS | Failed clearly with supported team list. |
21+
| `npm run dev:bootstrap -- --team alfa --role reviewer` | PASS | Failed clearly with supported role list. |
22+
| `npm run dev:local-api` | PASS | Legacy command started and printed legacy startup diagnostics, then process tree was stopped. |
23+
24+
## Notes
25+
26+
The startup-command validations used short-lived process launches and `taskkill /T /F` cleanup after expected diagnostics appeared, so no dev servers were left running. Owner-role validations opened the configured browser target after both server diagnostics were available. Unit coverage verifies loaded `.env` and inherited process URL values are overwritten by computed team/role ports.

‎dev/reports/codex_changed_files.txt‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,21 @@
1-
dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
1+
# git status --short
2+
M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_manual-validation-notes.md
3+
M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_report.md
4+
M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_requirement-checklist.md
5+
M dev/reports/PR_26171_ALFA_009-team-aware-bootstrap_validation-report.md
6+
M dev/scripts/start-dev.mjs
7+
M dev/scripts/team-port-config.mjs
8+
M dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs
9+
10+
# git ls-files --others --exclude-standard
11+
(no output)
12+
13+
# git diff --stat
14+
...team-aware-bootstrap_manual-validation-notes.md | 2 +-
15+
...R_26171_ALFA_009-team-aware-bootstrap_report.md | 6 +-
16+
...9-team-aware-bootstrap_requirement-checklist.md | 3 +-
17+
...A_009-team-aware-bootstrap_validation-report.md | 3 +-
18+
dev/scripts/start-dev.mjs | 2 +-
19+
dev/scripts/team-port-config.mjs | 31 ++++++++--
20+
dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs | 71 ++++++++++++++++------
21+
7 files changed, 87 insertions(+), 31 deletions(-)

0 commit comments

Comments
 (0)