ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
6d41618dd3
TenantAtlas/specs/183-website-workspace-foundation/contracts/workspace-command-model.md
Ahmed Darrazi 6d41618dd3 feat: implement workspace foundation website app
2026-04-08 14:14:54 +02: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.