feat: add CLAUDE.md for AI-assisted development

.github/workflows/orchestrator-async-checks.yml

@@ -54,7 +54,7 @@ jobs:
           # AWS_STACK_NAME: game-ci-github-pipelines
           CHECKS_UPDATE: ${{ github.event.inputs.checksObject }}
         run: |
-          git clone -b orchestrator-develop https://github.com/game-ci/unity-builder
+          git clone -b main https://github.com/game-ci/unity-builder
           cd unity-builder
           yarn
           ls

CLAUDE.md

@@ -0,0 +1,80 @@
+# Unity-Builder
+
+GitHub Action and CLI that builds Unity projects for multiple platforms. Part of the [GameCI](https://game.ci) project.
+
+## Quick Reference
+
+```bash
+yarn              # install dependencies
+yarn build        # full build: tsc → ncc bundle (src/ → lib/ → dist/index.js)
+yarn test         # run all tests (jest)
+yarn test:ci      # run tests in CI mode (single-threaded, 2min timeout)
+yarn lint         # prettier + eslint check
+yarn format       # auto-format with prettier
+```
+
+## Architecture
+
+**Entry point:** `src/index.ts` → decides between CLI mode and GitHub Action mode.
+
+**Two execution paths:**
+1. **Local builds** — Docker container or native macOS (`src/model/docker.ts`, `src/model/mac-builder.ts`)
+2. **Orchestrator builds** — Remote execution on AWS ECS, Kubernetes, or other providers (`src/model/orchestrator/`)
+
+**Key modules:**
+
+| Path | Purpose |
+|---|---|
+| `src/model/build-parameters.ts` | Central config object — all build settings flow through here |
+| `src/model/input.ts` | Input resolution with priority: Action inputs → CLI flags → env override → env vars |
+| `src/model/orchestrator/orchestrator.ts` | Remote build orchestration — provider selection, workflow execution |
+| `src/model/orchestrator/providers/` | Provider plugin system (AWS, K8s, Docker, Local, Test) |
+| `src/model/orchestrator/remote-client/` | Code that runs inside remote containers (caching, hooks, artifacts) |
+| `src/model/orchestrator/workflows/` | Build workflow types (standard, custom, async) |
+| `src/model/orchestrator/services/` | Logging, locking, resource tracking |
+| `src/model/cli/` | CLI mode using commander — dispatches to `@CliFunction`-decorated methods |
+| `action.yml` | GitHub Action manifest — all inputs/outputs defined here |
+| `dist/index.js` | Bundled output (committed to repo, used by action.yml at runtime) |
+
+**Provider interface:** All providers implement `ProviderInterface` (`providers/provider-interface.ts`) with methods: `setupWorkflow`, `runTaskInWorkflow`, `cleanupWorkflow`, `garbageCollect`, `listResources`, `listWorkflow`, `watchWorkflow`.
+
+**Provider loading:** Providers can be built-in, loaded from npm, cloned from GitHub repos, or loaded from local paths (`provider-loader.ts`).
+
+## Build System
+
+The build pipeline is: `yarn` → `tsc` (src/ → lib/) → `ncc build lib` (lib/ → dist/index.js).
+
+- **dist/ is committed** — GitHub Actions loads `dist/index.js` directly, no install step on runners
+- **Pre-commit hooks** (lefthook) auto-run formatting, linting, related tests, and `yarn build` to keep dist/ in sync
+- Runtime: Node 20 (configured via Volta and action.yml `runs.using: node20`)
+
+## Code Conventions
+
+- **Files:** kebab-case (enforced by eslint `unicorn/filename-case`)
+- **Code:** camelCase variables/functions, PascalCase classes/types
+- **Formatting:** Prettier — 120 char width, single quotes, trailing commas, semicolons
+- **Linting:** ESLint with unicorn, github, prettier, jest plugins
+- **TypeScript:** strict mode, ES2020 target, CommonJS modules, experimental decorators enabled
+- **Blank line before return statements** (enforced)
+- **Blank line before block/line comments** (enforced)
+- **No `for...in` loops** — use `for...of`
+
+## Testing
+
+- **Framework:** Jest 27 with ts-jest
+- **Pattern:** `**/*.test.ts` files colocated with source
+- **Orchestrator tests:** Concentrated in `src/model/orchestrator/tests/`
+- **Run specific tests:** `yarn test -t "pattern"` or `yarn jest path/to/file.test.ts`
+- **Orchestrator integration tests** require `orchestratorTests=true` env var: `cross-env orchestratorTests=true yarn test -i -t "orchestrator"`
+
+## Security
+
+- **Never log, output, or hardcode credentials** — cloud provider secrets (AWS, GCP, K8s), Unity serial keys, keystores, and private tokens must stay in secret inputs
+- **Input validation matters** — user-supplied hook commands and custom parameters can be injection vectors; use `shell-quote` for shell escaping
+- **Keystore/license data** is base64-encoded in inputs and written to temp files at build time
+
+## CI Workflows
+
+- `integrity-check.yml` — lint, test, build on every push/PR
+- `build-tests-{ubuntu,windows,mac}.yml` — matrix builds across Unity versions and platforms
+- `orchestrator-integrity.yml` / `orchestrator-async-checks.yml` — orchestrator-specific validation

src/model/orchestrator/tests/e2e/orchestrator-end2end-caching.test.ts

@@ -30,7 +30,7 @@ describe('Orchestrator Caching', () => {
         targetPlatform: 'StandaloneLinux64',
         cacheKey: `test-case-${uuidv4()}`,
         containerHookFiles: `debug-cache`,
-        orchestratorBranch: `orchestrator-develop`,
+        orchestratorBranch: `main`,
         orchestratorDebug: true,
       };
 

src/model/orchestrator/workflows/async-workflow.ts

@@ -33,8 +33,7 @@ if [ -n "$(git ls-remote --heads "$REPO" "$BRANCH" 2>/dev/null)" ]; then
   git clone -q -b "$BRANCH" "$REPO" /builder
 else
   echo "Remote branch $BRANCH not found in $REPO; falling back to a known branch"
-  git clone -q -b orchestrator-develop "$REPO" /builder \
-    || git clone -q -b main "$REPO" /builder \
+  git clone -q -b main "$REPO" /builder \
     || git clone -q "$REPO" /builder
 fi
 git clone -q -b ${Orchestrator.buildParameters.branch} ${OrchestratorFolders.targetBuildRepoUrl} /repo

src/model/orchestrator/workflows/build-automation-workflow.ts

@@ -99,8 +99,7 @@ if [ -n "$(git ls-remote --heads "$REPO" "$BRANCH" 2>/dev/null)" ]; then
   git clone -q -b "$BRANCH" "$REPO" "$DEST"
 else
   echo "Remote branch $BRANCH not found in $REPO; falling back to a known branch"
-  git clone -q -b orchestrator-develop "$REPO" "$DEST" \
-    || git clone -q -b main "$REPO" "$DEST" \
+  git clone -q -b main "$REPO" "$DEST" \
     || git clone -q "$REPO" "$DEST"
 fi
 chmod +x ${builderPath}`;