Skip to content

Commit 149c383

Browse files
ToolboxAidToolboxAid
committed
ALFA 009 add team-aware bootstrap
1 parent a4e671e commit 149c383

11 files changed

Lines changed: 1779 additions & 36 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: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
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+
16+
## Primary Alfa Codex Command
17+
18+
```powershell
19+
npm run dev:bootstrap -- --team alfa --role codex
20+
```
21+
22+
Expected diagnostics:
23+
24+
- `Team: alfa`
25+
- `Role: codex`
26+
- `Web URL: http://127.0.0.1:5512`
27+
- `API URL: http://127.0.0.1:5513/api`
28+
29+
## Legacy Command
30+
31+
```powershell
32+
npm run dev:local-api
33+
```
34+
35+
Expected result:
36+
37+
- Legacy startup remains available.
38+
- The legacy command still runs `node --use-system-ca ./dev/scripts/start-local-api-server.mjs`.
39+
40+
## Other Startup Commands
41+
42+
```powershell
43+
npm run dev:bootstrap -- --team owner
44+
npm run dev:bootstrap -- --team bravo
45+
npm run dev:bootstrap -- --team charlie
46+
npm run dev:bootstrap -- --team delta
47+
npm run dev:bootstrap -- --team echo
48+
npm run dev:bootstrap -- --team foxtrot
49+
npm run dev:bootstrap -- --team golf
50+
npm run dev:bootstrap -- --team hotel
51+
```
52+
53+
## Failure Checks
54+
55+
```powershell
56+
npm run dev:bootstrap -- --team omega
57+
npm run dev:bootstrap -- --team alfa --role reviewer
58+
```
59+
60+
Expected result:
61+
62+
- Unknown team fails with the supported team list.
63+
- Unknown role fails with the supported role list.

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

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
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+
32+
## Supported Teams
33+
34+
`owner`, `alfa`, `bravo`, `charlie`, `delta`, `echo`, `foxtrot`, `golf`, `hotel`
35+
36+
## Supported Roles
37+
38+
`owner`, `codex`
39+
40+
## Port Mapping
41+
42+
`owner` role uses base ports. `codex` role uses base ports plus 2.
43+
44+
| Team | Owner Web | Owner API | Codex Web | Codex API |
45+
| --- | ---: | ---: | ---: | ---: |
46+
| owner | 5500 | 5501 | 5502 | 5503 |
47+
| alfa | 5510 | 5511 | 5512 | 5513 |
48+
| bravo | 5520 | 5521 | 5522 | 5523 |
49+
| charlie | 5530 | 5531 | 5532 | 5533 |
50+
| delta | 5540 | 5541 | 5542 | 5543 |
51+
| echo | 5550 | 5551 | 5552 | 5553 |
52+
| foxtrot | 5560 | 5561 | 5562 | 5563 |
53+
| golf | 5570 | 5571 | 5572 | 5573 |
54+
| hotel | 5580 | 5581 | 5582 | 5583 |
55+
56+
## Commands Added
57+
58+
```powershell
59+
npm run dev:bootstrap
60+
npm run dev:api
61+
npm run dev:web
62+
```
63+
64+
## Legacy Command Preserved
65+
66+
```powershell
67+
npm run dev:local-api
68+
```
69+
70+
## Exact Startup Commands
71+
72+
```powershell
73+
npm run dev:bootstrap -- --team owner
74+
npm run dev:bootstrap -- --team alfa
75+
npm run dev:bootstrap -- --team bravo
76+
npm run dev:bootstrap -- --team charlie
77+
npm run dev:bootstrap -- --team delta
78+
npm run dev:bootstrap -- --team echo
79+
npm run dev:bootstrap -- --team foxtrot
80+
npm run dev:bootstrap -- --team golf
81+
npm run dev:bootstrap -- --team hotel
82+
```
83+
84+
Codex role example:
85+
86+
```powershell
87+
npm run dev:bootstrap -- --team alfa --role codex
88+
```
89+
90+
## Files Changed
91+
92+
- `package.json` - updated
93+
- `dev/scripts/start-dev.mjs` - added
94+
- `dev/scripts/team-port-config.mjs` - added
95+
- `dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs` - added
96+
97+
## Validation Summary
98+
99+
All requested targeted validation passed.

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
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+
| Load environment | PASS | Orchestrator loads `.env` values without overriding existing environment values. |
20+
| Resolve team ports | PASS | Unit tests cover all teams and both roles. |
21+
| Start Local API | PASS | `dev:bootstrap` starts the existing Local API server on resolved API port. |
22+
| Start web server when requested | PASS | `dev:bootstrap` starts web plus API; `dev:web` mode is wired. |
23+
| Print startup diagnostics | PASS | Diagnostics include mode, team, role, web URL, API URL, environment source, supported teams, and supported roles. |
24+
| Preserve legacy behavior | PASS | `dev:local-api` command unchanged and startup validation passed. |
25+
| 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: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
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; 10 subtests passed. |
12+
| Unsupported team token scan in new bootstrap files | PASS | No unsupported old team names or single-letter public team commands found. |
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`, 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`, then process tree was stopped. |
16+
| `npm run dev:bootstrap -- --team omega` | PASS | Failed clearly with supported team list. |
17+
| `npm run dev:bootstrap -- --team alfa --role reviewer` | PASS | Failed clearly with supported role list. |
18+
| `npm run dev:local-api` | PASS | Legacy command started and printed legacy startup diagnostics, then process tree was stopped. |
19+
20+
## Notes
21+
22+
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.

‎dev/reports/codex_changed_files.txt‎

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

0 commit comments

Comments
 (0)