# Maestro CORE — AI Working Guide

> Detailed conventions are in `.cursor/rules/`. This file covers the patterns most likely to cause mistakes.

## What this repo is

`maestro/core` (PHP) + `@maestro/core` (npm) is a **reusable Laravel + Vue + PrimeVue SPA package**.  
It is **not** a standalone app — it is installed into consuming Laravel apps (e.g. `test-5`).

```
maestro-new/          ← this repo (the package)
  src/                ← PHP: Maestro\Core\…
  resources/js/       ← Vue SPA source
  stubs/              ← TEMPLATES copied to consuming apps by `php artisan core:install`
  routes/             ← PHP routes (loaded by service providers)
  vite.config.js      ← dev-only (for running maestro-new itself)

test-5/ (or any other consuming app)
  vite.config.js      ← generated FROM stubs/vite.config.js — NOT from maestro-new root
  node_modules/@maestro/core/   ← installed npm package
```

## The stubs rule — always update both

`stubs/` contains the templates that `php artisan core:install [--force]` copies into consuming apps.  
Files marked `@maestro-core-managed` in their header are managed stubs.

| Managed stub | Deployed to consuming app |
|---|---|
| `stubs/vite.config.js` | `<app>/vite.config.js` |
| `stubs/tailwind.config.js` | `<app>/tailwind.config.js` |
| `stubs/resources/js/app.js` | `<app>/resources/js/app.js` |
| `stubs/routes/web.php` | `<app>/routes/web.php` |
| … | … |

**Rule: whenever you change any infrastructure file in maestro-new root (`vite.config.js`, `tailwind.config.js`, etc.), make the identical change in the matching `stubs/` file.**  
Changing only the root file has zero effect on consuming apps.

## How changes reach consuming apps

```
1. Fix code in maestro-new
2. run ./release.sh <version>        ← commits, tags, publishes npm + composer
3. In the consuming app:
   composer update maestro/core
   npm update @maestro/core
   php artisan core:install --force  ← re-copies stubs (vite.config.js etc.)
   rm -rf node_modules/.vite         ← clear Vite dep cache after config changes
   npm run dev (or npm run build)
```

For **infrastructure fixes** (vite.config, build tooling): the consuming app's Vite cache **must be cleared** (`rm -rf node_modules/.vite`) after any `optimizeDeps` or `resolve` change, then the dev server restarted. A hot reload is not enough — Vite config changes require a full restart.

## Known infrastructure gotchas

### Vite + quill-delta (CJS in ESM context)
`@maestro/core` is excluded from Vite's `optimizeDeps` to prevent a dual Vue runtime. This stops Vite from crawling transitive CJS deps like `quill-delta` (used by Quill 2.x / PrimeVue Editor). The symptom:
```
SyntaxError: does not provide an export named 'default' (at block.ts:9:8)
```
**Fix**: `stubs/vite.config.js` and all consuming app `vite.config.js` files must include:
```js
optimizeDeps: {
  exclude: ["@maestro/core"],
  include: ["quill", "quill-delta"],   // force CJS→ESM pre-bundling
}
```
If you add any other CJS dependency inside `@maestro/core`, add it here too.

### Base components — no `@` alias
Components published under `resources/js/components/base/` must use **relative imports** (`../../../services/api.js`), never the `@` alias. The `@` alias resolves to the **consuming app's** `resources/js/` at build time, not to `@maestro/core`.

## Release workflow

```bash
./release.sh <version>            # e.g. ./release.sh 1.0.60
./release.sh <version> --full-satis   # also rebuilds Composer Satis mirror
```

This auto-commits pending changes, bumps `package.json` + `composer.json`, tags, pushes, and publishes to the private npm + Satis registries.

## Module anatomy (quick ref)

```
src/Modules/{Pascal}/
  Providers/{Pascal}ModuleServiceProvider.php   ← loadMigrationsFrom, loadRoutesFrom
  Http/Controllers/
  Http/Requests/
  Http/Resources/
  Models/
  database/migrations/
routes/modules/{slug}.php
resources/js/modules/{feature}/
  index.js          ← exports route array with meta.module = '{slug}'
  views/
  composables/
```

Full rollout checklist: `.cursor/rules/maestro-module-rollout-workflow.mdc`  
PHP conventions: `.cursor/rules/maestro-php-backend.mdc`  
Vue SPA patterns: `.cursor/rules/maestro-vue-spa.mdc`

## Host custom layer (consuming apps)

- **Managed zone** (`@maestro-core-managed`): safe to refresh with `core:install --force`.
- **Custom zone** (never `--force`): `app/Custom/Features/`, `CustomDatabaseSeeder`, `resources/js/maestro/boot.js`, `resources/js/modules/custom/`.
- Scaffold: `php artisan make:custom-feature {Name}`.
- Register `CustomServiceProvider` in `AppServiceProvider`.
- Do not name host folders `customer` — use `custom` (CORE Customers module uses slug `customers`).
- Host Cursor rule: `maestro-host-custom-code.mdc` (published by `core:install`).
