ahmido
03b1beb616
## 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
70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# 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. |