S207: ESM SDK on Cloudflare + End-to-End Generation Test

Prerequisites: S206 complete. Template at gograbspace/platform-base-template (0 build errors). gspace1 pipeline changes on session-206 branch (uncommitted — commit first).

Session Goals

1. Commit S206 gspace1 pipeline changes (4 modified files on session-206 branch)
2. End-to-end generation test — trigger real Vitto generation, verify build + CRUD
3. Build ESM SDK compilation pipeline — ng-packagr → Cloudflare R2
4. Create AI-ready library manifest — machine-readable catalog for Vitto LLM
5. Port gmodules1 composables (useCrudList/Form/Detail) to template

Phase 0: Commit S206 Pipeline Changes (10 min)

Uncommitted files in gspace1 (session-206 branch):

M  APIs/backend-ai-api/src/app/workflow/templates/template-registry.service.ts
M  APIs/backend-vitto-api/src/app/module-generation/generators/app-shell-generator.service.ts
M  APIs/backend-vitto-api/src/app/module-generation/phases/module-gen-phase.executor.ts
M  APIs/backend-vitto-api/src/app/studio/universe-git.service.ts

Changes summary:

• universe-git.service.ts: Added initializeFromTemplate() + getFileTreeRecursive()
• module-gen-phase.executor.ts: PRE-FLIGHT uses template; CI uses yarn; feature/* branches build
• app-shell-generator.service.ts: provideApiConfig(), providePlatformBootstrap(), extends tsconfig.base.json, no more standalone package.json generation, budget increased to 2mb/5mb
• template-registry.service.ts: CRUD templates use UniverseDataCrudService, renamed to {entity}-api.service.ts

Action:

git add APIs/backend-ai-api/src/app/workflow/templates/template-registry.service.ts \
       APIs/backend-vitto-api/src/app/module-generation/generators/app-shell-generator.service.ts \
       APIs/backend-vitto-api/src/app/module-generation/phases/module-gen-phase.executor.ts \
       APIs/backend-vitto-api/src/app/studio/universe-git.service.ts
git commit -m "[S206.3] feat: pipeline uses base template, UniverseDataCrudService, providePlatformBootstrap"

Phase 1: End-to-End Generation Test (30 min)

1.1 Ensure backends are running

yarn serve:backend-api      # Port 3000
yarn serve:backend-ai       # Port 3001
yarn serve:backend-vitto    # Port 3003

1.2 Trigger generation via Vitto Studio

• Navigate to a universe in gspace1
• Use Vitto Studio's generate button
• Request: "A soccer league management platform with Players, Teams, Matches"
• Watch SSE stream for PRE-FLIGHT (should say "template-based")

1.3 Verify generated repo

git clone https://gitlab.com/gograbspace/{space}/{universe}.git
cd {universe}
yarn install
yarn ng build {slug} --configuration development
# Must: 0 errors
yarn ng serve {slug}
# Must: app bootstraps at localhost:4200

1.4 Test CRUD

1. Navigate to Players list
2. Create a player → verify POST to /api/spaces/{spaceId}/universes/{universeId}/data/players/insert
3. Edit → verify PUT
4. Delete → verify DELETE
5. Check MongoDB: space_{spaceId} DB → universe_{universeId}_players collection

1.5 Expected issues and fixes

• Missing proxy config: Generated platforms may need proxy.conf.json for dev server → backend CORS
• Schema registration timing: BackendSetupPhase must complete before first CRUD call
• Environment values: Verify spaceId/universeId in generated environment.ts match real IDs

Phase 2: ESM SDK Build Pipeline (2-3 hours)

2.1 Create build script in platform-base-template

repo-templates/platform-base-template/
  tools/
    build-esm-sdk.ts          ← Compiles each lib to ESM
    generate-manifest.ts       ← Generates manifest.json
    upload-to-r2.ts           ← Uploads to Cloudflare R2
  sdk/
    dist/                     ← Build output (gitignored)
    manifest.json             ← AI-ready library catalog

2.2 ng-packagr compilation

For each library in the template:

1. Configure ng-package.json (entry point, dependencies)
2. Run ng-packagr to produce FESM2022 bundles
3. Output to sdk/dist/{lib-path}/

Grouping strategy (reduces HTTP requests):

sdk/dist/
  @gograb/core.mjs           ← api-config + core-angular + core-models + storage-system
  @gograb/ui.mjs              ← ui-core + ui-feedback + ui-forms + ui-structure
  @gograb/ux.mjs              ← ux-icons + ux-portal + ux-loading + ux-menu
  @gograb/theme.mjs           ← theme-runtime + theme-styles
  @gograb/data.mjs            ← module-base + data-access + event-system + shared-models
  @gograb/auth.mjs            ← auth-ui + user-context + security
  @gograb/platform.mjs        ← platform-bootstrap + utilities + log-system

2.3 AI-ready manifest

{
  "version": "1.0.0",
  "buildDate": "2026-03-12T00:00:00Z",
  "cdnBase": "https://sdk.gograb.space/v1",
  "bundles": {
    "@gograb/core": {
      "url": "/core.mjs",
      "size": "245KB",
      "gzip": "68KB",
      "libraries": ["@libs-foundational/api-config", "@libs-foundational/core-angular", ...],
      "exports": {
        "UniverseDataService": { "description": "Generic CRUD for any entity. Auto-scopes to current space/universe.", "when": "Every generated platform" },
        "provideApiConfig": { "description": "Configures all 4 backend URL tokens", "when": "Every generated platform" },
        "providePlatformBootstrap": { "description": "Seeds space/universe context from environment", "when": "Every generated platform" }
      }
    },
    ...
  },
  "allLibraries": {
    "@libs-foundational/api-config": {
      "tier": "core",
      "bundle": "@gograb/core",
      "description": "API URL tokens for all 4 backends (api:3000, ai:3001, docs:3002, vitto:3003)",
      "key_exports": ["API_BASE_URL", "AI_API_URL", "DOCS_API_URL", "VITTO_API_URL", "provideApiConfig", "ENVIRONMENT_PRESETS"],
      "when_to_use": "Always — every platform needs backend connectivity",
      "depends_on": []
    },
    "@libs-structural/platform-shell": {
      "tier": "optional",
      "bundle": null,
      "description": "App shell with Cmd+K quick switcher, navigation, presence overlay",
      "key_exports": ["QuickSwitcherComponent", "UnifiedNavigationService"],
      "when_to_use": "Complex platforms with many modules and keyboard-driven navigation",
      "depends_on": ["@libs-foundational/core-angular"]
    },
    // ... ALL 137 libraries documented
  },
  "tiers": {
    "core": "Always included. Required for any platform to function.",
    "recommended": "Included by default unless platform is minimal.",
    "optional": "Vitto decides based on user requirements.",
    "internal": "gspace1-specific. Never include in generated platforms."
  }
}

2.4 Cloudflare R2 setup

# Create R2 bucket
wrangler r2 bucket create gograb-sdk

# Upload SDK
wrangler r2 object put gograb-sdk/v1/core.mjs --file sdk/dist/@gograb/core.mjs
wrangler r2 object put gograb-sdk/v1/manifest.json --file sdk/manifest.json
# ... for each bundle

# Create Worker for routing
# sdk.gograb.space/v1/* → R2 bucket/v1/*
# sdk.gograb.space/latest/* → R2 bucket/v{latest}/*

2.5 GitLab CI for automatic SDK builds

Add to platform-base-template/.gitlab-ci.yml:

build-sdk:
  stage: build
  image: node:20
  script:
    - yarn install --frozen-lockfile
    - yarn build:sdk
    - yarn upload:sdk
  only:
    - main
  variables:
    CLOUDFLARE_ACCOUNT_ID: $CLOUDFLARE_ACCOUNT_ID
    CLOUDFLARE_API_TOKEN: $CLOUDFLARE_API_TOKEN

Phase 3: Import Maps in Generated Platforms (1 hour)

3.1 Update app-shell-generator

Two modes:

• source mode (current): Template with full libs/ directory (fallback)
• cdn mode (new): Import map pointing to SDK CDN (preferred)

// Generated index.html (cdn mode)
<script type="importmap">
{
  "imports": {
    "@libs-foundational/api-config": "https://sdk.gograb.space/v1/core.mjs",
    "@libs-foundational/core-angular": "https://sdk.gograb.space/v1/core.mjs",
    ...
  }
}
</script>

3.2 Angular esbuild external configuration

// angular.json build options
{
  "externalDependencies": [
    "@libs-foundational/*",
    "@libs-core/*",
    "@libs-ui-core/*",
    "@libs-ux/*",
    "@theme-system/*",
    "@storage-system"
  ]
}

3.3 Verify: generated platform with CDN libs

# Clone generated repo (should have NO libs/ directory)
yarn install   # Only Angular + rxjs (5-10s)
yarn build     # Only compiles domain modules (2-3s)
yarn serve     # Loads shared libs from CDN at runtime

Phase 4: Port Composables (1 hour)

4.1 Files to port from gmodules1

4.2 Type adaptations needed

4.3 Composables already work with UniverseDataCrudService because:

• It implements the same interface (getList, getById, create, update, delete)
• Returns the same types (CrudPaginatedResult<T>)
• The mapping happens inside the adapter, transparent to composables

4.4 Update template-registry CRUD templates to use composables

// Generated list component with composable
export class PlayerListComponent {
  private readonly api = inject(PlayerApiService);
  readonly crud = useCrudList<Player>({
    loadFn: (params) => this.api.getList(params),
    basePath: '/players',
    entityName: 'Player'
  });
}

Phase 5: Manifest Generation for ALL 137 Libraries (1 hour)

5.1 Script to scan gspace1/libs/

For each of the 137 NX libraries:

1. Read project.json for metadata
2. Read src/index.ts for public exports
3. Classify tier (core/recommended/optional/internal)
4. Extract description from JSDoc
5. Map dependencies from import analysis

5.2 Output: sdk.gograb.space/v1/manifest.json

This becomes the contract between gspace1 and Vitto. The LLM prompt includes:

Available libraries (from manifest):
- @libs-foundational/core-angular [core]: CRUD, context, guards
- @libs-structural/platform-shell [optional]: App shell with Cmd+K
- @libs-ai/vitto-chat [optional]: Embedded AI chat
...

Based on the user's requirements, select which optional libraries this platform needs.

5.3 Continuous update pipeline

gspace1 lib change → PR merged to main
  → CI: rebuild affected ESM bundles
  → CI: regenerate manifest.json
  → Upload to R2 with new version tag
  → Worker routes /latest/ to new version

Verification Checklist

• S206 pipeline changes committed on gspace1
• End-to-end generation produces a building platform
• CRUD operations hit real backend-api and persist in MongoDB
• ESM SDK compiles from template libs
• Manifest covers all 137 gspace1 libraries
• R2 bucket created and SDK uploaded
• Worker routes sdk.gograb.space correctly
• At least one generated platform runs with CDN libs (no source copy)
• Composables ported and working with UniverseDataCrudService

Risk Mitigation

Environment Setup for S207

# Ensure all backends running
yarn serve:backend-api      # Terminal 1
yarn serve:backend-ai       # Terminal 2
yarn serve:backend-vitto    # Terminal 3
yarn serve:space            # Terminal 4 (port 6200)

# Ensure env vars
GITLAB_TEMPLATE_REPO=gograbspace/platform-base-template
GITLAB_TEMPLATE_BRANCH=main

# Ensure Cloudflare credentials for R2
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_API_TOKEN=...