build(workspaces): promote repo root to npm workspace root (#53)

## Summary
Restructure the npm workspace tree to be rooted at the repository root
instead of under `app/`, simplifying dependency management and build
workflows across the entire project.

## Key Changes

- **Workspace root relocation**: Moved workspace configuration from
`app/package.json` to a new root `package.json`, with workspaces now
defined as `["app", "app/packages/*", "scripts"]`
- **Root-level npm commands**: Added convenience scripts at the root
level (e.g., `npm run app:dev`, `npm run app:build`) that delegate to
workspace-specific commands, eliminating the need to `cd app` before
running tasks
- **Dockerfile updates**: 
- Changed `WORKDIR` from `/app` to `/workspace` to match the new
structure
- Updated all `COPY` commands to reference the root `package.json` and
adjust paths accordingly
- Added stub `scripts/package.json` to prevent npm from installing
maintainer-only dev tools in production
- Added final `WORKDIR /workspace/app` to preserve existing behavior for
`ConfigService` path probing
- **CI/CD workflow updates**: Removed `working-directory: app` defaults
and updated cache paths to use root-level `package-lock.json`; updated
lint and test commands to use new root-level scripts
- **Documentation updates**: 
- Updated `CLAUDE.md` with new command patterns (e.g., `npm run app:dev`
instead of `cd app && npm run dev`)
  - Updated submodule setup guide to use the new workspace structure
- Updated `docker-compose.yml` volume mounts to reflect `/workspace`
paths
- **Setup script**: Updated `setup.sh` to run `npm ci` from repo root
instead of `app/` directory

## Implementation Details

The restructuring maintains backward compatibility by:
- Keeping the `app/` directory structure intact with its own
`package.json` (now without workspace declarations)
- Using root-level convenience scripts that target specific workspaces
with `-w` flag
- Preserving the final working directory in Docker as `/workspace/app`
to ensure existing path-based logic continues to work
- Creating a stub `scripts/package.json` to prevent unnecessary
dependencies in the production image while still allowing the workspace
to be referenced

This change simplifies the mental model of the project structure and
reduces friction when running commands from the repository root.

https://claude.ai/code/session_01BfCUaJBR6wTmdH2ET8oov4

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: CoderCoco

.github/workflows/lint.yml

@@ -11,21 +11,18 @@ permissions:
 jobs:
   eslint:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: app
     steps:
       - uses: actions/checkout@v5
 
       - uses: actions/setup-node@v5
         with:
           node-version: '24'
           cache: npm
-          cache-dependency-path: app/package-lock.json
+          cache-dependency-path: package-lock.json
 
       - run: npm ci
 
-      - run: npm run lint
+      - run: npm run app:lint
 
   tflint:
     runs-on: ubuntu-latest

.github/workflows/test.yml

@@ -8,18 +8,15 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: app
     steps:
       - uses: actions/checkout@v5
 
       - uses: actions/setup-node@v5
         with:
           node-version: '24'
           cache: npm
-          cache-dependency-path: app/package-lock.json
+          cache-dependency-path: package-lock.json
 
       - run: npm ci
 
-      - run: npm test
+      - run: npm run app:test

CLAUDE.md

@@ -4,32 +4,44 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Common Commands
 
-The management app is a TypeScript **npm-workspaces** monorepo under `app/`. Dependencies are installed once at the workspace root. The workspaces are:
+The repo uses a single **npm-workspaces** tree rooted at the repo root. Workspaces are:
 
 - `@gsd/shared` — types, `canRun`, sanitizers, status formatter, command descriptors, DynamoDB + Secrets Manager helpers (used by both the server and the Lambdas).
 - `@gsd/server` — Nest.js management API.
 - `@gsd/web` — React + Vite client.
 - `@gsd/lambda-interactions`, `@gsd/lambda-followup`, `@gsd/lambda-update-dns`, `@gsd/lambda-watchdog` — four Lambda packages, each bundled to a single `dist/handler.cjs` by esbuild.
+- `@gsd/scripts` — maintainer helper scripts (`init-parent.ts` scaffolder).
 
 ```bash
-# Install all workspaces in one go
-cd app && npm install
+# Install all workspaces in one go (run from repo root)
+npm install
 
 # Run the dev servers (Nest on 3001, Vite on 5173 with /api proxy)
-cd app && npm run dev
+npm run app:dev
 
 # Production build (shared → server → web)
-cd app && npm run build && npm start    # http://localhost:3001
+npm run app:build && npm run app:start  # http://localhost:3001
 
 # Build all Lambda bundles (required before `terraform apply`)
-cd app && npm run build:lambdas
+npm run app:build:lambdas
+
+# Unit tests (vitest + aws-sdk-client-mock) — discovered across every workspace
+npm run app:test             # one-off run
+npm run app:test:watch       # watch mode
+
+# Lint / autofix
+npm run app:lint
+npm run app:lint:fix
+
+# Run the scaffolder script
+npm run scripts:init-parent
 
 # Run the app in Docker (mounts ./terraform ro, ./app/server_config.json, ~/.aws)
 docker compose up --build               # http://localhost:5000
 
 # Terraform (all infra lives under terraform/). NOTE: terraform apply reads
 # the Lambda bundles from app/packages/lambda/*/dist/handler.cjs — run
-# `npm run build:lambdas` first or the archive_file data sources will fail.
+# `npm run app:build:lambdas` first or the archive_file data sources will fail.
 cd terraform
 terraform init
 terraform plan
@@ -39,13 +51,9 @@ terraform destroy
 # First-time environment bootstrap (installs terraform + aws CLI if missing,
 # runs npm ci, builds Lambdas, runs terraform init)
 ./setup.sh
-
-# Unit tests (vitest + aws-sdk-client-mock) — discovered across every workspace
-cd app && npm test             # one-off run
-cd app && npm run test:watch   # watch mode
 ```
 
-ESLint (flat config) lives at `app/eslint.config.js` using `@eslint/js` + `typescript-eslint` recommended presets, plus `eslint-plugin-react` and `eslint-plugin-react-hooks` recommended for the web package. Run `npm run lint` (or `npm run lint:fix`) from `app/`.
+ESLint (flat config) lives at `app/eslint.config.js` using `@eslint/js` + `typescript-eslint` recommended presets, plus `eslint-plugin-react` and `eslint-plugin-react-hooks` recommended for the web package. Run `npm run app:lint` (or `npm run app:lint:fix`) from the repo root.
 
 Terraform linting uses [tflint](https://github.com/terraform-linters/tflint) with its `recommended` preset and the AWS ruleset plugin. Config lives at `terraform/.tflint.hcl`. Run `tflint --init` once to install the plugin, then `tflint` from `terraform/`. `terraform fmt -check -recursive` and `terraform validate` cover formatting and syntax.
 

Dockerfile

@@ -1,24 +1,36 @@
 FROM node:20-slim
 
-WORKDIR /app
-
-# Install dependencies first (layer cache).  npm ci uses the workspace root's
-# package.json + lockfile, which installs every workspace package's deps.
-COPY app/package.json app/package-lock.json* ./
-COPY app/packages/shared/package.json packages/shared/
-COPY app/packages/server/package.json packages/server/
-COPY app/packages/web/package.json packages/web/
-COPY app/packages/lambda/interactions/package.json packages/lambda/interactions/
-COPY app/packages/lambda/followup/package.json packages/lambda/followup/
-COPY app/packages/lambda/update-dns/package.json packages/lambda/update-dns/
-COPY app/packages/lambda/watchdog/package.json packages/lambda/watchdog/
+# Workspace root lives at /workspace (= repo root).  All npm workspace
+# members (app, app/packages/*, scripts) are installed from here.
+WORKDIR /workspace
+
+# Copy root manifest + lockfile first for layer-cache-efficient installs.
+COPY package.json package-lock.json ./
+
+# Copy every workspace member's package.json so npm ci can resolve them.
+COPY app/package.json app/
+COPY app/packages/shared/package.json app/packages/shared/
+COPY app/packages/server/package.json app/packages/server/
+COPY app/packages/web/package.json app/packages/web/
+COPY app/packages/lambda/interactions/package.json app/packages/lambda/interactions/
+COPY app/packages/lambda/followup/package.json app/packages/lambda/followup/
+COPY app/packages/lambda/update-dns/package.json app/packages/lambda/update-dns/
+COPY app/packages/lambda/watchdog/package.json app/packages/lambda/watchdog/
+COPY app/packages/lambda/efs-seeder/package.json app/packages/lambda/efs-seeder/
+
+COPY scripts/package.json scripts/
+
 RUN npm ci --ignore-scripts
 
 # Copy source and build the server + web bundle for the management app. The
 # Lambda packages are NOT built here — they are bundled and deployed by
 # `terraform apply` (see `setup.sh`) and have no place inside the container.
-COPY app/ .
-RUN npm run build
+COPY app/ app/
+RUN npm run build -w game-server-manager
+
+# Switch to the app directory so ConfigService path probing and process.cwd()
+# behave the same as in the previous single-WORKDIR setup.
+WORKDIR /workspace/app
 
 EXPOSE 3001
 

README.md

@@ -62,7 +62,7 @@ $EDITOR terraform/terraform.tfvars        # game_servers, hosted_zone_name, ...
 cd terraform && terraform apply
 
 # 4a. Run the management app in dev mode
-cd ../app && npm run dev
+cd .. && npm run app:dev
 #     http://localhost:5173  (Nest on :3001, Vite proxy)
 
 # 4b. …or in Docker (production mode — requires a bearer token)

app/package.json

@@ -3,12 +3,6 @@
   "version": "1.0.0",
   "private": true,
   "type": "module",
-  "workspaces": [
-    "packages/shared",
-    "packages/server",
-    "packages/web",
-    "packages/lambda/*"
-  ],
   "scripts": {
     "predev": "node scripts/embed-tfstate.mjs",
     "dev": "concurrently -n server,client -c cyan,magenta \"npm run dev -w @gsd/server\" \"npm run dev -w @gsd/web\"",

docker-compose.yml

@@ -5,7 +5,7 @@ services:
       - "5000:3001"
     volumes:
       # Makes terraform.tfstate readable by the app
-      - ./terraform:/app/terraform:ro
+      - ./terraform:/workspace/terraform:ro
       # Persists server_config.json across container restarts.
       # NOTE: the host file must exist before `docker compose up` — create it with
       #       `touch app/server_config.json` on first run. With
@@ -15,7 +15,7 @@ services:
       #       default short-syntax mounts would otherwise cause.
       - type: bind
         source: ./app/server_config.json
-        target: /app/server_config.json
+        target: /workspace/app/server_config.json
         bind:
           create_host_path: false
       # AWS credentials — remove if using env vars instead

docs/docs/guides/submodule.md

@@ -86,10 +86,9 @@ cd your-private-games
 # 2. Add the submodule.
 git submodule add https://github.com/CoderCoco/game-server-deploy.git
 
-# 3. Install scaffolder deps and run it from the parent repo root.
-(cd game-server-deploy/scripts && npm install)
-npx --prefix game-server-deploy/scripts tsx \
-    game-server-deploy/scripts/init-parent.ts
+# 3. Install all deps and run the scaffolder.
+(cd game-server-deploy && npm install)
+(cd game-server-deploy && npm run scripts:init-parent)
 ```
 
 The script prompts for project name, AWS region, hosted zone, and