ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
03b1beb616
TenantAtlas/specs/183-website-workspace-foundation/contracts/workspace-command-model.md
ahmido 03b1beb616 feat: implement workspace foundation website app (#214) 
## Summary
- add the first multi-app workspace foundation with a new standalone Astro website under `apps/website`
- introduce repo-root pnpm workspace orchestration and migrate the platform Node workflow from npm assumptions to pnpm
- update root docs, editor or agent guidance, and workspace-focused smoke tests for the new platform plus website command model
- add Spec 183 artifacts for spec, plan, research, contracts, quickstart, checklist, and tasks

## Verification
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/WorkspaceFoundation`
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- `corepack pnpm build:website`
- integrated-browser smoke: verified `http://localhost/up`, `http://localhost/admin/login`, and `http://localhost:4321/` including website anchor navigation and combined root dev flow

## Notes
- branch: `183-website-workspace-foundation`
- commit: `6d41618d`
- root command model now covers `dev:platform`, `dev:website`, `dev`, `build:platform`, and `build:website`
- website port override documentation is included in the command contract, quickstart, and README

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #214
2026-04-08 12:20:31 +00:00

3.4 KiB
Raw Blame History

Contract: Workspace Command Model

Purpose

Define the official repo-root and app-local commands for the first multi-app TenantAtlas workspace.

Ownership Rule

  • Root commands orchestrate.
  • App-local commands execute.
  • The root must never re-implement platform or website runtime logic.

Official Root Commands

Command Responsibility Notes
pnpm install Install workspace JavaScript dependencies Root entry for workspace-managed JS dependencies
pnpm dev:platform Start the platform app Delegates to the existing platform Sail flow
pnpm dev:website Start the website app Runs the Astro dev server from apps/website
pnpm dev Start platform + website for parallel local development Platform may background via Sail while website dev stays foreground
pnpm build:website Build the website app Produces website-only artifacts
pnpm build:platform Build platform frontend assets Delegates into apps/platform and preserves existing Laravel asset flow

Supported Port Override Path

  • If the platform HTTP or Vite ports are already in use, the supported override path is environment-based: set APP_PORT and or VITE_PORT before invoking the root platform command, and pass the same variables through the app-local Sail flow when using apps/platform directly.
  • If the website port is already in use, the supported override path is environment-based: set WEBSITE_PORT before invoking the root website or parallel-dev command, and pass the equivalent --port flag through the app-local apps/website Astro dev command.
  • The root pnpm dev:website and pnpm dev scripts must forward WEBSITE_PORT to the Astro dev server.
  • The supported override path must be documented in the root README and validated in smoke checks.

Valid App-local Commands

Platform

  • cd apps/platform && ./vendor/bin/sail up -d
  • cd apps/platform && ./vendor/bin/sail stop
  • cd apps/platform && ./vendor/bin/sail pnpm dev
  • cd apps/platform && ./vendor/bin/sail pnpm build
  • cd apps/platform && ./vendor/bin/sail artisan test --compact

Website

  • cd apps/website && pnpm dev
  • cd apps/website && pnpm build

Compatibility Helpers

  • ./scripts/platform-sail ... remains valid for tooling that cannot set cwd.
  • This helper is platform-specific in this slice and must not be generalized into a multi-app runner yet.

Tooling Scope Rules

  • .vscode/mcp.json and opencode.json remain platform-only because Boost MCP is Laravel-specific.
  • VS Code tasks may expose official root entry tasks for platform, website, and parallel dev, but must not imply a second hidden workflow.

Invariants

  • The platform remains Sail-first.
  • The website remains independent of Sail, Laravel, Blade, Filament, and platform sessions.
  • Composer remains app-local PHP dependency management for apps/platform.
  • pnpm is the one official JavaScript workspace/package-manager standard.
  • No root command may require the website build to start the platform or vice versa.

Failure Conditions

  • A root command is undocumented but treated as official.
  • A website command depends on platform runtime state.
  • A platform command requires undocumented root-only state.
  • Root tooling suggests npm for one app and pnpm for another as equal official workflows.
  • Port conflicts exist but no documented, supported override path is available for the platform or website commands.