Build Log

Detailed record of every build step — what was done, what commands were run, what decisions were made, and what the outcome was. Useful for debugging, onboarding, and reproducing the setup.

Step 1: Project Scaffolding

Date: 2026-02-12 Status: Complete

1.1 Environment

1.2 Create Laravel 12 App

Command:

laravel new laraschema_temp --pest --no-interaction

Outcome: Created Laravel 12.51.0 app with Pest testing framework in a temp folder. Then moved contents into LaraSchema/ while preserving existing documentation files (PLANNING.md, README.md, docs/).

What shipped with Laravel 12:

• Tailwind CSS 4 (via @tailwindcss/vite plugin)
• Vite build system
• SQLite as default database
• Pest PHP 4.3 for testing

1.3 Install Livewire 4

Command:

composer require livewire/livewire

Outcome: Installed livewire/livewire v4.1. Auto-discovered by Laravel.

1.4 Configure Tailwind for Package Views

File modified: resources/css/app.css

Change: Added @source directive so Tailwind scans our package's Blade views for utility classes:

@source '../../packages/laraschema/resources/views/**/*.blade.php';

Why: Without this, any Tailwind classes used in packages/laraschema/resources/views/ would be purged during production builds because Tailwind wouldn't know they exist.

1.5 Create Package Directory Structure

Created under packages/laraschema/:

packages/laraschema/
├── composer.json
├── config/
├── database/migrations/
├── resources/views/
│   ├── layouts/
│   └── livewire/
├── routes/
└── src/
    ├── LaraSchemaServiceProvider.php   (placeholder)
    ├── Enums/
    ├── Generators/
    ├── Http/
    │   ├── Controllers/
    │   └── Livewire/
    ├── Models/
    └── Services/

1.6 Package composer.json

File: packages/laraschema/composer.json

Key settings:

• Name: laraschema/laraschema
• PSR-4 Autoload: LaraSchema\\ maps to src/
• Laravel Auto-discovery: Registers LaraSchema\LaraSchemaServiceProvider automatically
• Dependencies: illuminate/support ^12.0, livewire/livewire ^4.0

1.7 Wire Up Monorepo

File modified: Root composer.json

Changes:

1. Added path repository pointing to packages/laraschema
2. Added "laraschema/laraschema": "@dev" to require
3. Changed minimum-stability from "stable" to "dev" (required for @dev packages)

Path repository config:

"repositories": [
    {
        "type": "path",
        "url": "packages/laraschema"
    }
]

1.8 Composer Update

Command:

composer update

Outcome:

• Package symlinked: vendor/laraschema/laraschema -> ../../packages/laraschema/
• Auto-discovery confirmed: laraschema/laraschema ... DONE
• No errors

1.9 Verification

Files Created/Modified in Step 1

Step 2: Package Foundation

Date: 2026-02-12 Status: Complete

2.1 Config — packages/laraschema/config/laraschema.php

Published configuration with three sections:

Publishable via php artisan vendor:publish --tag=laraschema-config

2.2 Routes — packages/laraschema/routes/web.php

Routes are wrapped with configurable prefix and middleware by the service provider.

2.3 Enums

ColumnType — 35 cases covering all Laravel migration column types.

• Grouped into 8 categories: Numeric, String, Date & Time, Binary & Boolean, JSON, UUID & ULID, Network, Special
• Helper methods: requiresLength(), requiresPrecision(), requiresValues(), label(), category()
• Static grouped() method returns types organized by category for UI dropdowns

RelationshipType — 10 cases for all Eloquent relationship types.

• Helper methods: label(), description(), foreignKeyLocation(), requiresPivot(), sourceCardinality(), targetCardinality()
• Static mvpTypes() returns the 4 types used in Phase 1 (hasOne, hasMany, belongsTo, belongsToMany)

2.4 Migrations

All 5 ran successfully:

Key constraints:

• laraschema_tables has unique constraint on [project_id, name]
• laraschema_columns has unique constraint on [table_id, name]
• All child tables cascade-delete when parent is removed
• laraschema_projects supports soft deletes

2.5 Models

All 5 models created with proper relationships, casts, and $fillable:

2.6 Service Provider — LaraSchemaServiceProvider.php

Full implementation replacing the Step 1 placeholder:

2.7 Layout — resources/views/layouts/app.blade.php

• Uses @vite() from the host app for CSS + JS
• Includes @livewireStyles and @livewireScripts
• Top nav bar with LaraSchema icon (SVG grid) and branding
• {{ $actions ?? '' }} slot for page-specific toolbar buttons
• {{ $slot }} for main content
• Full viewport, light gray background, antialiased text

2.8 Placeholder Components

Created minimal Livewire components to make routes functional:

• ProjectManager — Renders placeholder view at /laraschema
• Canvas — Accepts Project model, renders placeholder at /laraschema/project/{project}
• ExportController — Returns 501 "not yet implemented" (full version in Step 8)

2.9 Verification

Tinker test output:

Project created: 1
Table created: 1
Column created: 1
Tables count: 1
Columns count: 1
String requires length: yes
Decimal requires precision: yes
Enum requires values: yes
BelongsToMany requires pivot: yes
HasMany FK location: target

Files Created in Step 2

Step 3: Project Management (CRUD)

Date: 2026-02-12 Status: Complete

3.1 ProjectManager Livewire Component

File: packages/laraschema/src/Http/Livewire/ProjectManager.php

Full CRUD component replacing the Step 2 placeholder. Uses WithPagination trait.

Key decisions:

• Projects are paginated at 12 per page (fits 3x4 grid nicely)
• withCount('tables') used for efficient table count display without N+1
• New projects get canvas_settings from config defaults
• Delete uses soft delete (via the SoftDeletes trait on the model)

3.2 Project Manager View

File: packages/laraschema/resources/views/livewire/project-manager.blade.php

UI layout:

┌──────────────────────────────────────────────┐
│  Projects                    [+ New Project] │
│  Design and manage your database schemas.    │
├──────────────────────────────────────────────┤
│                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │E-Commerce│ │Blog      │ │CRM       │    │
│  │Online... │ │Multi...  │ │          │    │
│  │3 tables  │ │1 table   │ │0 tables  │    │
│  │2m ago    │ │2m ago    │ │2m ago    │    │
│  │   [✎][🗑]│ │   [✎][🗑]│ │   [✎][🗑]│    │
│  └──────────┘ └──────────┘ └──────────┘    │
│                                              │
└──────────────────────────────────────────────┘

Components:

• Header section: Title, subtitle, "New Project" button (blue, top-right)
• Card grid: Responsive 1/2/3 columns (sm/md/lg), rounded-xl cards with hover shadow
• Each card contains:
  • Clickable body (links to canvas designer)
  • Project name (or inline rename input when editing)
  • Description (line-clamped to 2 lines)
  • Meta: table count with icon + relative timestamp
  • Footer: Rename (pencil) and Delete (trash) icon buttons
• Empty state: Database icon, "No projects yet" message, CTA button
• Create modal: Name input (auto-focused) + description textarea, Cancel/Create buttons
• Delete modal: Warning icon, project name in bold, explains cascading impact, Cancel/Delete buttons

Alpine.js integration:

• x-on:keydown.escape closes modals
• x-init="$el.focus(); $el.select()" on rename input auto-focuses and selects text
• x-on:click.stop on rename input prevents card click navigation

3.3 Verification

Test data created:

• "E-Commerce App" (3 tables: users, products, orders)
• "Blog Platform" (1 table: posts)
• "CRM System" (0 tables)

Files Modified in Step 3

Steps 4-5: Canvas + Table Nodes

Date: 2026-02-12 Status: Complete

4.1 Canvas Livewire Component

File: packages/laraschema/src/Http/Livewire/Canvas.php

Replaced the Step 2 placeholder with full implementation. This component is the server-side backbone — it handles data persistence while Alpine.js handles all visual interactions.

Key decisions:

• addTable() generates unique names (new_table, new_table_1, etc.) and positions in a 4-column staggered grid
• New table positions snap to the grid automatically
• formatTableForAlpine() casts all values to proper JS types (float, bool) to avoid Alpine issues
• Dynamic title via ->title($project->name . ' — LaraSchema')

4.2 Canvas Blade View + Alpine.js Component

File: packages/laraschema/resources/views/livewire/canvas.blade.php

This is the most complex file in the project. It contains three main sections:

Toolbar (HTML overlay)

• Back arrow link to projects
• Project name display
• "Add Table" button (blue, calls wire:click="addTable")
• Zoom controls: -, percentage display (clickable to reset), +
• Snap-to-grid toggle (highlights blue when active)

SVG Canvas

• Wrapped in wire:ignore to prevent Livewire DOM-diffing during interactions
• Grid background: Two <pattern> elements — minor-grid (every gridSize px) and major-grid (every 5x gridSize px)
• Transform group: <g :transform="translate(panX, panY) scale(zoom)"> applies pan + zoom
• Relationship lines: <template x-for> rendering <line> elements between table edges
• Table nodes: <template x-for="table in tables"> rendering card-like <g> groups:
  • Shadow rect (2px offset, subtle)
  • White card background with gray border (blue border when selected)
  • Colored header rect with table name text
  • Built-in field rows: id (italic, gray), user columns, timestamps, softDeletes
  • Column rows: name on left (with ? nullable and FK indicators), type on right
  • Dynamic height calculated from row count

Side Panel

• Slides in from right when a table is double-clicked (w-96)
• Alpine.js transition: slide in/out with opacity
• Contains a nested <livewire:laraschema.table-editor> component (placeholder for Step 6)
• Close button + Escape key to dismiss

Alpine.js schemaCanvas Component (inline <script>)

Table node rendering breakdown:

┌──────────────────────────────────┐
│  ██████ table_name ██████████████│  <- colored header (36px)
├──────────────────────────────────┤
│  id                 bigIncrements│  <- built-in (italic, gray)
├──────────────────────────────────┤
│  email ?                  string │  <- column (? = nullable)
│  user_id FK               string │  <- column (FK indicator)
├──────────────────────────────────┤
│  timestamps       created/updated│  <- built-in (italic, gray)
│  softDeletes          deleted_at │  <- built-in (italic, gray)
└──────────────────────────────────┘

Each row is 28px high. Total height = 36 (header) + rows × 28 + 12 (padding).

4.3 Placeholder Components

Created minimal TableEditor component so double-click doesn't crash:

• packages/laraschema/src/Http/Livewire/TableEditor.php — loads table by ID
• packages/laraschema/resources/views/livewire/table-editor.blade.php — shows table name + "coming in Step 6"

4.4 Verification

Files Created/Modified in Steps 4-5

Step 6: Table Editor Panel

Date: 2026-02-12 Status: Complete

6.1 TableEditor Livewire Component

File: packages/laraschema/src/Http/Livewire/TableEditor.php

Replaced the Step 4-5 placeholder with full implementation. This component handles all table settings and column CRUD operations via the side panel.

Properties:

Methods:

Key decisions:

• updateColumn() uses an allowlist of 11 fields for security — only these can be updated: name, type, nullable, default_value, is_unique, is_index, is_unsigned, length, precision, scale, comment
• Column name validation applies snake_case regex and uniqueness per table (same as addColumn())
• dispatchTableUpdated() sends a structured array (not a model) to avoid serialization issues between Livewire and Alpine.js
• deleteTable() dispatches to Canvas::class specifically (not broadcast) so only the canvas reacts
• After every mutation, $this->table->load('columns') is called to refresh the column collection

6.2 Table Editor Blade View

File: packages/laraschema/resources/views/livewire/table-editor.blade.php

The view is organized into 4 distinct sections separated by <hr> dividers:

┌──────────────────────────────┐
│  TABLE SETTINGS              │
│  ┌────────────────────────┐  │
│  │ Name: [users_______]   │  │
│  │ Color: [■] #3B82F6     │  │
│  │ id()           [=====] │  │
│  │ timestamps()   [=====] │  │
│  │ softDeletes()  [=====] │  │
│  └────────────────────────┘  │
├──────────────────────────────┤
│  COLUMNS (3)                 │
│  ┌────────────────────────┐  │
│  │ ▲ name      string   ✕ │  │
│  │ ▼ ☐Null ☐Unique ☐Idx  │  │
│  ├────────────────────────┤  │
│  │ ▲ email     string   ✕ │  │
│  │ ▼ ☑Null ☐Unique ☐Idx  │  │
│  ├────────────────────────┤  │
│  │ ▲ password  string   ✕ │  │
│  │ ▼ ☐Null ☐Unique ☐Idx  │  │
│  └────────────────────────┘  │
├──────────────────────────────┤
│  ADD COLUMN                  │
│  [column_name_____________]  │
│  [string ▼                ]  │
│  [Default value (optional)]  │
│  ☐ Nullable ☐ Unique ☐ Idx  │
│  [+ Add Column             ] │
├──────────────────────────────┤
│  [🗑 Delete Table           ] │
└──────────────────────────────┘

Section details:

1. Table Settings — Name input (wire:model.blur + wire:change for debounced save), native <input type="color">, three custom toggle switches styled as blue/gray pills with animated knob transition

2. Columns List — Each column is a card with:

   • Reorder arrows (▲/▼) — hidden when at top/bottom boundary
   • Inline name input (wire:blur for update on focus loss)
   • Type dropdown with <optgroup> categories from ColumnType::grouped()
   • Delete button (appears on hover via group-hover:opacity-100)
   • Modifier checkboxes (Null, Unique, Index) below
   • Delete confirmation replaces the row with a red banner + Yes/No buttons

3. Add Column Form — wire:submit="addColumn", includes name input, type select (with type labels), default value input, modifier checkboxes, and submit button

4. Delete Table — Red outlined button expands to confirmation box with warning about cascading deletes

UI polish details:

• Toggle switches use :class="@js($var)" for reactive Alpine-in-Blade state
• Column rows use group class for hover-reveal delete button
• Font-mono on name inputs for code-like appearance
• wire:key="col-{{ $column->id }}" for correct Livewire diffing
• Validation errors show beneath relevant inputs in red

6.3 Verification

Files Modified in Step 6

Step 7: Relationships

Date: 2026-02-12 Status: Complete

7.1 RelationshipManager Livewire Component

File: packages/laraschema/src/Http/Livewire/RelationshipManager.php

Handles all relationship CRUD operations including auto-creation of FK columns.

Properties:

Methods:

FK column auto-creation logic:

Key decisions:

• FK columns are created as unsignedBigInteger with is_foreign = true and is_index = true
• If onDelete is set null, the FK column is made nullable automatically
• If a column with the FK name already exists, it's reused and marked as foreign
• Pivot table names follow Laravel convention: alphabetically sorted singular names joined with underscore
• Both relationship-created and table-updated events are dispatched so the canvas updates both the line and the table node

7.2 Relationship Manager Blade View

File: packages/laraschema/resources/views/livewire/relationship-manager.blade.php

Two main sections:

1. Create Relationship Modal (shown when $showCreateModal is true):

   • Header showing source → target table names
   • Radio button group for relationship types (4 MVP types with descriptions)
   • On-delete and on-update dropdowns
   • FK column preview showing what will be auto-created
   • Pivot table name preview for belongsToMany
   • Cancel / Create buttons

2. Relationships List (always visible in side panel):

   • Each relationship shows: source name → type badge → target name
   • Metadata: on_delete action, pivot table name (if applicable)
   • Delete button (hover-reveal) with inline Yes/No confirmation
   • Empty state: "No relationships yet" message

7.3 Canvas Integration

Updated files:

• Canvas.php — Added event listeners and cardinality data
• canvas.blade.php — Major update for relationship mode

Canvas.php changes:

Canvas Blade view changes:

Toolbar additions:

• "Draw Relationship" button (amber when active) with dynamic text: "Draw Relationship" → "Click Source..." → "Click Target..."
• Add Table button disabled (opacity-50) during relationship mode

Relationship Mode Banner:

• Floating amber banner centered at top with instructions
• Shows "Click the source table to start" or "Now click the target table"
• Cancel button to exit mode

SVG enhancements:

• Cardinality markers: 4 SVG <marker> definitions (one-start, one-end, many-start, many-end)
  • "1" marker: vertical line
  • "Many" marker: crow's foot (3 fanning lines)
• Relationship paths: Changed from <line> to <path> using cubic bezier curves for smoother routing
• Relationship labels: Type name displayed at midpoint of each line
• Preview line: Dashed amber line from source table center to mouse cursor during drawing
• Source highlight: Selected source table gets amber dashed border
• Target hints: All other tables get subtle amber border during relationship mode

Alpine.js additions:

Cursor states:

• Default: cursor-grab
• Panning: cursor-grabbing
• Relationship mode: cursor-crosshair

7.4 User Flow

1. Click "Draw Relationship" button → toolbar button turns amber, banner appears
2. Click source table → amber dashed border appears, preview line follows mouse
3. Click target table → relationship modal opens with source/target pre-filled
4. Select type (hasOne, hasMany, belongsTo, belongsToMany), on_delete, on_update
5. See FK column preview or pivot table name
6. Click "Create Relationship" → FK column auto-created, SVG line appears with cardinality markers
7. Escape key cancels relationship mode at any point

7.5 Verification

Files Created/Modified in Step 7

Step 8: Code Generation + Export

Date: 2026-02-12 Status: Complete

8.1 MigrationGenerator

File: packages/laraschema/src/Generators/MigrationGenerator.php

Pure PHP service class with no HTTP or Livewire dependency. Generates valid Laravel migration files from a project's schema.

Public API:

Protected methods (internal):

Output structure:

1. {timestamp}_000001_create_{table1}_table.php   ← Table migrations (sorted by sort_order)
2. {timestamp}_000002_create_{table2}_table.php
3. {timestamp}_000003_create_{table3}_table.php
4. {timestamp}_000004_add_foreign_keys.php         ← FK constraints (single file, if any)
5. {timestamp}_000005_create_{pivot}_table.php     ← Pivot tables (one per belongsToMany)

Column type handling:

Modifier chaining order: ->unsigned()->nullable()->default(val)->unique()->index()->comment(str)

Default value formatting:

• 'null' → null
• Boolean type + 'true'/'1' → true/false
• Numeric types + numeric string → unquoted number
• Everything else → 'quoted string'

FK migration features:

• Uses ->cascadeOnDelete(), ->restrictOnDelete(), ->nullOnDelete() based on on_delete setting
• down() method uses $table->dropForeign(['column_name'])
• Pivot tables use foreignId()->constrained()->cascadeOnDelete() with a unique composite key

8.2 SchemaExportService

File: packages/laraschema/src/Services/SchemaExportService.php

• Injects MigrationGenerator via constructor
• Creates ZIP at storage/app/laraschema-exports/{slug}-migrations-{datetime}.zip
• Files placed inside database/migrations/ folder within the ZIP
• Creates export directory if it doesn't exist

8.3 CodePreview Livewire Component

File: packages/laraschema/src/Http/Livewire/CodePreview.php

8.4 CodePreview Blade View

File: packages/laraschema/resources/views/livewire/code-preview.blade.php

┌──────────────────────────────────────────────────┐
│  Migration Preview              [Refresh] [Export]│
├───────────┬──────────────────────────────────────┤
│ File Tabs │  Code View                     [Copy]│
│           │                                      │
│ > users   │   1  <?php                           │
│   posts   │   2                                  │
│   tags    │   3  use Illuminate\Database\...     │
│   fk      │   4  use Illuminate\Database\...     │
│   pivot   │   5                                  │
│           │   6  return new class extends ...     │
│           │   7  {                               │
│           │   8      public function up()        │
│           │   ...                                │
└───────────┴──────────────────────────────────────┘

Features:

• Header bar: "Migration Preview" title, Refresh button (regenerates code), Export ZIP link
• File tabs (left sidebar, w-56): Clickable list of migration files, active file highlighted with blue icon
• Code view (right panel): Dark background (gray-900), monospace font, line numbers, Copy button (uses navigator.clipboard)
• Empty state: Shown when no tables exist, with code icon and guidance text
• Copy feedback: "Copy" → "Copied!" for 2 seconds via Alpine.js

8.5 ExportController

File: packages/laraschema/src/Http/Controllers/ExportController.php

Replaced Step 2 placeholder with full implementation:

• Uses Laravel's dependency injection to resolve SchemaExportService
• Download filename: {project-slug}-migrations.zip
• ->deleteFileAfterSend(true) cleans up the temporary ZIP file

8.6 Canvas Integration

Canvas.php changes:

• Added $showCodePreview boolean property
• Added toggleCodePreview() and closeCodePreview() methods
• Code preview deselects any selected table when opened

Canvas Blade view changes:

• Added "Preview Code" button in toolbar (dark when active)
• Added code preview bottom panel (50vh height, absolute positioned)
• Panel respects side panel: adjusts right offset when table editor is open

8.7 Verification

Tinker test with complex schema (users/posts/tags with relationships):

Files Created/Modified in Step 8

Phase 1 Complete

All 8 steps of the MVP implementation plan have been completed:

Total files in package: 30 (matching the plan's file manifest)

Final asset sizes:

• CSS: 63.6KB (gzip: 12.3KB)
• JS: 36.7KB (gzip: 14.8KB)

Phase 2: Complete Code Generation

Date: 2026-02-16 Status: Complete

Phase 2 Overview

Phase 2 expands LaraSchema from a migration-only generator to a complete Laravel code scaffolding tool. Users can now export production-ready Eloquent Models, Factories, and Seeders alongside migrations.

Goals achieved:

• ✅ Generate Eloquent models with relationships, $fillable, casts(), traits
• ✅ Generate factories with intelligent Faker methods and state management
• ✅ Generate seeders with dependency ordering (topological sort)
• ✅ Category-based code preview UI (Migrations, Models, Factories, Seeders)
• ✅ Complete codebase ZIP export with proper Laravel directory structure

Step 9: ColumnType Enum Enhancements

Date: 2026-02-16 Status: Complete

9.1 Added phpCastType() Method

File modified: packages/laraschema/src/Enums/ColumnType.php

Maps column types to Eloquent cast types for model generation:

public function phpCastType(): ?string
{
    return match ($this) {
        self::Boolean => 'boolean',
        self::Integer, self::BigInteger => 'integer',
        self::Decimal => 'decimal:2',
        self::DateTime, self::Timestamp => 'datetime',
        self::Date => 'date',
        self::Json, self::Jsonb => 'array',
        default => null,
    };
}

Used by: ModelGenerator for generating casts() method

9.2 Added fakerMethod() Method

Maps column types to appropriate Faker method calls for factory generation:

public function fakerMethod(): string
{
    return match ($this) {
        self::String => 'fake()->text(50)',
        self::Text => 'fake()->paragraph()',
        self::Integer => 'fake()->randomNumber()',
        self::Boolean => 'fake()->boolean()',
        self::DateTime => 'fake()->dateTime()',
        self::Uuid => 'fake()->uuid()',
        default => 'fake()->word()',
    };
}

Coverage: All 35+ column types mapped to realistic Faker calls

Step 10: ModelGenerator

Date: 2026-02-16 Status: Complete

10.1 ModelGenerator Implementation

File created: packages/laraschema/src/Generators/ModelGenerator.php

Pure PHP service following the established generator pattern. Generates Eloquent models with Laravel 12 conventions.

Public API:

Protected methods:

Output structure:

User.php → namespace App\Models; class User extends Model { ... }
Post.php → namespace App\Models; class Post extends Model { ... }
Tag.php  → namespace App\Models; class Tag extends Model { ... }

Features:

• Uses casts() method (Laravel 12 style) not $casts property
• Handles decimal precision: 'price' => 'decimal:2'
• Auto-hides sensitive fields: password, remember_token
• Generates typed relationship methods with proper imports
• BelongsToMany includes pivot table name and keys
• Relationship method naming: hasOne/belongsTo → singular, hasMany/belongsToMany → plural

10.2 Verification

Tinker test:

$project = Project::with(['tables.columns', 'relationships'])->first();
$generator = new ModelGenerator();
$models = $generator->generateForProject($project);

// Generated 5 models
count($models); // 5

// Syntax validation
foreach ($models as $filename => $content) {
    token_get_all($content); // All pass
}

// Sample output check
$models['User.php']; // Contains proper fillable, casts, relationships

Generated model quality checks:

• ✅ All models use declare(strict_types=1);
• ✅ Fillable arrays exclude id, timestamps, soft_deletes
• ✅ Casts method uses correct types (boolean, integer, datetime, array)
• ✅ Relationship methods have return type hints
• ✅ SoftDeletes trait added when table uses soft deletes
• ✅ Timestamps disabled when table doesn't use timestamps

Step 11: FactoryGenerator

Date: 2026-02-16 Status: Complete

11.1 FactoryGenerator Implementation

File created: packages/laraschema/src/Generators/FactoryGenerator.php

Generates factory files with intelligent Faker method selection and state management.

Public API:

Protected methods:

Special column handling (heuristics):

Foreign key handling:

• Detects FK from relationships: 'user_id' => User::factory()
• Falls back to naming convention: author_id → Author::factory()

State methods (auto-generated):

• unverified() — if email_verified_at column exists
• trashed() — if deleted_at column exists (soft deletes)
• Status-based — if status enum exists, generates state per value

11.2 Verification

Tinker test:

$generator = new FactoryGenerator();
$factories = $generator->generateForProject($project);

// Generated 5 factories
count($factories); // 5

// Syntax validation
foreach ($factories as $filename => $content) {
    token_get_all($content); // All pass
}

// Foreign key check
$factories['PostFactory.php']; // Contains 'user_id' => User::factory()

Generated factory quality checks:

• ✅ All factories extend Factory with proper PHPDoc
• ✅ Faker methods match column types (text → paragraph, boolean → boolean)
• ✅ Special columns handled (email unique, password hashed, slug generated)
• ✅ Foreign keys use Model::factory() not random IDs
• ✅ State methods generated for email_verified_at, deleted_at, status enums
• ✅ Nullable columns wrapped in fake()->optional(0.7)

Step 12: SeederGenerator

Date: 2026-02-16 Status: Complete

12.1 SeederGenerator Implementation

File created: packages/laraschema/src/Generators/SeederGenerator.php

Generates seeder files with dependency ordering using topological sort (Kahn's algorithm).

Public API:

Protected methods:

Dependency ordering (Kahn's algorithm):

1. Build dependency graph from relationships
2. BelongsTo → source depends on target
3. HasOne/HasMany → target depends on source
4. Calculate in-degree for each table
5. Queue tables with in-degree = 0
6. Process queue, decrement dependencies
7. Result: users → posts → comments (respects FK order)

Pivot table seeding:

Post::all()->each(function (Post $model) {
    $model->tags()->attach(
        Tag::inRandomOrder()->take(rand(1, 3))->pluck('id')
    );
});

Output structure:

UserSeeder.php           → User::factory()->count(10)->create();
PostSeeder.php           → Post::factory()->count(10)->create(); + pivot seeding
TagSeeder.php            → Tag::factory()->count(10)->create();
DatabaseSeeder.php       → $this->call([...]) in dependency order

12.2 Verification

Tinker test:

$generator = new SeederGenerator();
$seeders = $generator->generateForProject($project);

// Generated 6 seeders (5 tables + DatabaseSeeder)
count($seeders); // 6

// Syntax validation
foreach ($seeders as $filename => $content) {
    token_get_all($content); // All pass
}

// Dependency order check
$seeders['DatabaseSeeder.php'];
// Contains: UserSeeder, PostSeeder, CommentSeeder (correct order)

Dependency ordering test:

// Test project: users → posts → comments (linear dependency)
$order = (new SeederGenerator())->buildDependencyOrder($project);
$order[0]->name; // 'users'
$order[1]->name; // 'posts'
$order[2]->name; // 'comments'

Generated seeder quality checks:

• ✅ Individual seeders call Model::factory()->count(10)->create()
• ✅ Pivot seeding uses attach() with random associations
• ✅ DatabaseSeeder lists seeders in dependency order
• ✅ Circular dependencies fall back to original table order
• ✅ All seeders have proper namespace and use statements

Step 13: UI Integration - CodePreview Component

Date: 2026-02-16 Status: Complete

13.1 CodePreview Component Updates

File modified: packages/laraschema/src/Http/Livewire/CodePreview.php

Refactored from flat file list to category-based structure.

Before (Phase 1):

public array $files = []; // Flat array of migrations
public string $activeFile = '';

After (Phase 2):

public array $filesByCategory = [
    'migrations' => [],
    'models' => [],
    'factories' => [],
    'seeders' => [],
];
public string $activeCategory = 'migrations';
public string $activeFile = '';

New methods:

Code generation:

public function generateCode(): void
{
    $this->filesByCategory = [
        'migrations' => (new MigrationGenerator())->generateForProject($this->project),
        'models' => (new ModelGenerator())->generateForProject($this->project),
        'factories' => (new FactoryGenerator())->generateForProject($this->project),
        'seeders' => (new SeederGenerator())->generateForProject($this->project),
    ];
}

13.2 CodePreview Blade View Updates

File modified: packages/laraschema/resources/views/livewire/code-preview.blade.php

Added category navigation section with file counts and icons.

New UI sections:

1. Category Tabs (vertical button group):

   • Migrations (database icon) + count badge
   • Models (box icon) + count badge
   • Factories (beaker icon) + count badge
   • Seeders (palette icon) + count badge
   • Active category highlighted with blue background
   • Click calls wire:click="selectCategory('...')"

2. File List (per category):

   • Iterates $this->activeFiles instead of $files
   • Shows files only for active category
   • File selection updates within category

3. Code View:

   • Uses $this->activeFiles[$activeFile] for content
   • Copy button uses same Alpine.js mechanism

Visual polish:

• Active category: bg-blue-50 text-blue-700
• Badge colors match active state
• Empty state: "No files to generate" (generic across categories)

13.3 Verification

Step 14: SchemaExportService Integration

Date: 2026-02-16 Status: Complete

14.1 Service Updates

File modified: packages/laraschema/src/Services/SchemaExportService.php

Before (Phase 1):

public function __construct(
    protected MigrationGenerator $generator
) {}

After (Phase 2):

public function __construct(
    protected MigrationGenerator $migrationGenerator,
    protected ModelGenerator $modelGenerator,
    protected FactoryGenerator $factoryGenerator,
    protected SeederGenerator $seederGenerator
) {}

Updated generateZip() method:

public function generateZip(Project $project): string
{
    $migrations = $this->migrationGenerator->generateForProject($project);
    $models = $this->modelGenerator->generateForProject($project);
    $factories = $this->factoryGenerator->generateForProject($project);
    $seeders = $this->seederGenerator->generateForProject($project);

    // Add to ZIP with Laravel directory structure
    foreach ($migrations as $filename => $content) {
        $zip->addFromString("database/migrations/{$filename}", $content);
    }
    foreach ($models as $filename => $content) {
        $zip->addFromString("app/Models/{$filename}", $content);
    }
    foreach ($factories as $filename => $content) {
        $zip->addFromString("database/factories/{$filename}", $content);
    }
    foreach ($seeders as $filename => $content) {
        $zip->addFromString("database/seeders/{$filename}", $content);
    }
}

Filename change:

• Before: {slug}-migrations-{date}.zip
• After: {slug}-{date}.zip (contains all file types)

14.2 Exported ZIP Structure

laraschema-export-2026-02-16.zip
├── database/
│   ├── migrations/
│   │   ├── 2026_02_16_000001_create_users_table.php
│   │   ├── 2026_02_16_000002_create_posts_table.php
│   │   ├── 2026_02_16_000003_add_foreign_keys.php
│   │   └── 2026_02_16_000004_create_post_tag_table.php
│   ├── factories/
│   │   ├── UserFactory.php
│   │   ├── PostFactory.php
│   │   └── TagFactory.php
│   └── seeders/
│       ├── DatabaseSeeder.php
│       ├── UserSeeder.php
│       ├── PostSeeder.php
│       └── TagSeeder.php
└── app/
    └── Models/
        ├── User.php
        ├── Post.php
        └── Tag.php

14.3 Verification

Test export flow:

1. Created test project with 3 tables (users, posts, tags)
2. Added relationships (users hasMany posts, posts belongsToMany tags)
3. Clicked "Export ZIP" button
4. Downloaded ZIP file
5. Extracted contents

Verification checks:

• ✅ ZIP contains 4 directories (migrations, models, factories, seeders)
• ✅ File count matches: 4 migrations, 3 models, 3 factories, 4 seeders
• ✅ All files have valid PHP syntax
• ✅ Models contain relationships
• ✅ Factories use Model::factory() for foreign keys
• ✅ DatabaseSeeder lists seeders in dependency order

Manual Laravel installation test:

1. Extracted ZIP into fresh Laravel 12 app
2. Ran php artisan migrate → All tables created ✅
3. Ran php artisan tinker → User::factory()->create() works ✅
4. Ran php artisan db:seed → Database populated with relationships ✅

Step 15: Code Formatting

Date: 2026-02-16 Status: Complete

15.1 Laravel Pint Formatting

Command:

vendor/bin/pint --dirty --format agent

Result: All new and modified files formatted to match Laravel conventions

Files formatted:

• packages/laraschema/src/Enums/ColumnType.php
• packages/laraschema/src/Generators/ModelGenerator.php
• packages/laraschema/src/Generators/FactoryGenerator.php
• packages/laraschema/src/Generators/SeederGenerator.php
• packages/laraschema/src/Http/Livewire/CodePreview.php
• packages/laraschema/src/Services/SchemaExportService.php

Phase 2 Complete

Summary:

Generated code quality:

• ✅ All generators produce valid PHP syntax
• ✅ Follows Laravel 12 conventions
• ✅ Models use casts() method (not $casts property)
• ✅ Factories use realistic Faker methods
• ✅ Seeders respect dependency ordering
• ✅ Complete codebase ready for immediate use

Key achievements:

1. Generator Pattern — Established reusable, testable pattern for code generation
2. Intelligent Code — Heuristic detection for common columns (email, password, slug)
3. Dependency Ordering — Topological sort ensures seeders run in correct order
4. Complete Codebase — Users now get migrations + models + factories + seeders
5. Category UI — Organized code preview improves UX

Phase 2 deliverables ready for production use.

Documentation Updates

Date: 2026-02-16 Status: Complete

Documentation Files Updated

Documentation completeness:

• ✅ Architecture patterns documented
• ✅ Implementation details with code examples
• ✅ Verification procedures recorded
• ✅ Roadmap updated to reflect progress
• ✅ Team can understand and extend generators

Phase 2.5: Full Project Export

Date: 2026-02-17 Status: Complete

Phase 2.5 Overview

Phase 2.5 transforms the ZIP export from a collection of code files into a complete, ready-to-run Laravel + Filament application. The user experience goes from 6+ terminal commands to two commands + one browser click.

Goals achieved:

• ✅ LaravelProjectGenerator service — orchestrates full project assembly
• ✅ Base Laravel 12 + Filament 5 template
• ✅ Pre-generated .env with unique APP_KEY
• ✅ Browser-based one-click setup wizard (Alpine.js, 4 states)
• ✅ Idempotent setup steps with retry support
• ✅ Auto-seeded admin user (admin@example.com / password)
• ✅ Cleaned up orphaned code (shell scripts, dead methods)

Step 16: LaravelProjectGenerator Service

Date: 2026-02-17 Status: Complete

16.1 Service Implementation

File created: packages/laraschema/src/Services/LaravelProjectGenerator.php

Orchestrates the full project generation pipeline:

Key decisions:

• try/finally around all steps guarantees temp directory cleanup even on exception
• File::ensureDirectoryExists() called before each write batch (no silent failures)
• DatabaseSeeder.php written separately via writeDatabaseSeeder() to inject admin user

Constructor:

public function __construct(
    protected MigrationGenerator $migrationGenerator,
    protected ModelGenerator $modelGenerator,
    protected FactoryGenerator $factoryGenerator,
    protected SeederGenerator $seederGenerator
) {}

16.2 Admin User Injection

writeDatabaseSeeder() checks whether a users table exists in the schema. If found, buildAdminUserAttributes() inspects actual columns and injects only the attributes that exist:

// If users table has email, name, password, email_verified_at:
\App\Models\User::factory()->create([
    'email' => 'admin@example.com',
    'name' => 'Admin User',
    'password' => \Illuminate\Support\Facades\Hash::make('password'),
    'email_verified_at' => now(),
]);

16.3 Files Created/Modified

Step 17: Base Template + Stubs

Date: 2026-02-17 Status: Complete

17.1 Base Laravel Template

Location: packages/laraschema/templates/laravel-12/base/

A clean Laravel 12 installation managed via:

php artisan laraschema:setup-template

This command clones a fresh Laravel 12 app into the template directory and removes files that the generator will inject (migrations, models, factories, seeders, default welcome view).

What the base template includes:

• Full Laravel 12 directory structure
• composer.json (pre-configured — generator adds Filament dependency)
• bootstrap/, config/, routes/web.php, public/
• Default Laravel migrations (users, password_resets, etc.)

What the generator injects on top:

• Schema-specific migrations, models, factories, seeders
• app/Providers/Filament/AdminPanelProvider.php
• app/Http/Controllers/SetupController.php
• Updated routes/web.php with setup routes
• Generated welcome.blade.php with setup wizard
• Pre-generated .env with unique APP_KEY
• Project README.md

17.2 Stub Files

17.3 Files Created

Step 18: Browser-Based Setup Wizard

Date: 2026-02-17 Status: Complete

18.1 Setup Wizard Architecture

The generated project's welcome page (/) is the setup wizard. It detects setup state server-side and initializes Alpine.js directly in the correct state — no flash or loading spinner.

States:

State detection:

@php
    $isSetupComplete = File::exists(storage_path('app/.setup_complete'));
@endphp
<div x-data="setupWizard({{ $isSetupComplete ? 'true' : 'false' }})">

18.2 SetupController Steps

Idempotency: Each step is safe to retry. The seed step checks Schema::hasTable('users') && User::exists() before seeding.

18.3 Files Created/Modified

Step 19: Pre-Generated .env

Date: 2026-02-17 Status: Complete

19.1 Implementation

LaravelProjectGenerator::createEnvFile() copies .env.example and injects a unique APP_KEY:

protected function createEnvFile(string $projectDir): void
{
    $envExample = File::get("{$projectDir}/.env.example");
    $key = 'base64:' . base64_encode(random_bytes(32));
    $env = str_replace('APP_KEY=', "APP_KEY={$key}", $envExample);
    File::put("{$projectDir}/.env", $env);
}

Benefit: Eliminates cp .env.example .env && php artisan key:generate from the user workflow.

Security: Each generated project gets a unique key via random_bytes(32).

Step 20: Cleanup + Robustness

Date: 2026-02-17 Status: Complete

20.1 Removed Orphaned Code

20.2 Robustness Improvements

20.3 Files Modified

Phase 2.5 Complete

Summary:

User workflow after Phase 2.5:

composer install   # install dependencies
php artisan serve  # start server
# Open http://localhost:8000
# Click "Run Setup"
# Click "Open Admin Panel"

Generated project quality:

• ✅ Runs immediately after composer install
• ✅ No cp .env.example .env or key:generate needed
• ✅ Browser wizard handles migrate, seed, assets, resource generation
• ✅ Admin panel ready at /admin after setup completes
• ✅ Setup is idempotent — safe to retry if a step fails

Documentation Updates (Phase 2.5)

Date: 2026-02-17 Status: Complete

Documentation Files Updated

MCP Server Integration

Date: 2026-06-24 Status: Complete Plan: docs/14-MCP-SERVER-PLAN.md

Exposed LaraSchema as an authenticated MCP server so external AI clients (Claude Desktop, Claude Code, Cursor) can read and design a user's schema projects.

Build steps

New dependency

• laravel/sanctum (approved) — bearer-token auth for MCP clients.

Tools exposed

All tools authorize the project against the authenticated token's owner.

• list_projects — the user's projects (id, name, table count, public flag)
• get_schema — a project's tables/columns/relationships as JSON
• apply_schema — non-destructive bulk merge of a full schema
• create_table, add_column, delete_column, create_relationship, delete_table — surgical edits

Manual verification

php artisan mcp:inspector mcp/laraschema   # add an Authorization: Bearer <token> header

MCP Server — OAuth 2.1 via Passport

Date: 2026-06-25 Status: Complete

Added OAuth 2.1 so MCP clients that only support OAuth — notably claude.ai's "Add custom connector" form — can authenticate via the browser consent flow. Migrated the API auth layer from Sanctum to Laravel Passport so a single auth:api guard validates both OAuth tokens and personal access tokens (the existing bearer-token / mcp-remote flow keeps working).

Changes

How clients authenticate now

• claude.ai custom connector — paste https://laraschema.com/mcp/laraschema, leave OAuth Client ID/Secret blank. The server advertises discovery via .well-known/oauth-protected-resource + .well-known/oauth-authorization-server and self-registers the client via POST /oauth/register. User approves in browser.
• Claude Desktop / Claude Code — still work with a personal access token from /mcp-tokens as a bearer header (validated by the same auth:api guard).

Production deployment steps (run on the server, e.g. laraschema.com)

composer install --no-dev
php artisan migrate                       # creates oauth_* tables
php artisan passport:keys                 # generate encryption keys (DO NOT commit)
php artisan passport:client --personal    # personal access client (for token minting)

• Ensure APP_URL=https://laraschema.com so OAuth/MCP URLs are correct.
• storage/oauth-private.key / oauth-public.key are gitignored — generate them on each environment (or set PASSPORT_PRIVATE_KEY / PASSPORT_PUBLIC_KEY env vars).
• Sanctum is left installed but unused (guard + trait removed); its personal_access_tokens table is now dead weight and can be dropped later.

Amended: that cleanup was completed the same day, not later — the package was removed from composer.json and the table dropped by 2026_06_25_120000_drop_personal_access_tokens_table.php. Sanctum is gone; the only remaining laravel/sanctum string in composer.lock belongs to another package's dev-requires. docs/14-MCP-SERVER-PLAN.md has been marked superseded where it still described the Sanctum plan.

MCP Server — Full Relationship Type Coverage

Date: 2026-08-18 Status: Complete Plan: docs/14-MCP-SERVER-PLAN.md

MCP could only create 4 of the 8 relationship types the canvas offers, so an external client could not build the polymorphic schemas the editor can — or reproduce two of our own seeded templates.

The two bugs behind the gap

create_relationship hard-coded ['hasOne', 'hasMany', 'belongsTo', 'belongsToMany'] in its input schema, and SchemaMutator::createRelationship() rejected anything where isMorphic() was true. That much was a clean, tested limitation.

Worse was apply_schema. It bypassed SchemaMutator entirely and went through AiSchemaChat::apply(), whose relationship pass only special-cased belongsToMany. A morphMany therefore passed RelationshipType::tryFrom(), skipped every column-creating branch, and persisted with no {morph}_type / {morph}_id columns and no morphic pivot table — while ModelGenerator happily emitted morphTo() against columns that never existed. The same line silently coerced an unrecognized type string into hasMany. And SchemaDesigner's prompt advertised morphOne / morphMany as valid, so the in-app AI chat was actively steered into producing the broken shape.

Changes

Adjacent bugs fixed

• Self-referential belongsToMany in the mutator derived both pivot keys from the same table name, so ensureForeignKeyColumn created post_id once and the pivot ended up with a single column. Now parent_id / child_id, matching the editor.
• The AI prompt asked for setNull / noAction, but MigrationGenerator matches on 'set null' / 'no action' and nothing normalized between them, so those referential actions silently generated no clause at all.

Behavior change

apply_schema now creates the FK column a belongsTo / hasMany implies (and flags an existing one is_foreign). It previously created nothing and relied on the AI declaring user_id itself as a plain column, so AI- and MCP-authored schemas rendered and generated differently from hand-drawn ones.

Divergences left in place deliberately

• Pivot table flags differ: the canvas editor creates pivots with use_id = true, use_timestamps = true; the mutator uses false, false. Changing either shifts generated migrations.
• The editor blocks a second relationship reusing a pivot_table_name; the mutator allows it. That is what lets MCP build the canonical shared taggables shape (the polymorphic-tags template's) which the editor itself cannot draw, since it derives per-source names (postables, videoables).
• There is no delete_relationship MCP tool, so the morph-column cleanup in RelationshipManager::deleteRelationship() has no MCP counterpart.
• hasOneThrough / hasManyThrough remain unsupported everywhere.

Tests

packages/laraschema/tests/Feature/Services/SchemaMutatorRelationshipTest.php (18 tests) pins the mutator to the same shapes RelationshipManagerTest pins the editor to, including two end-to-end tests asserting a mutator-built polymorphic schema generates real morphMany() / morphTo() and a migration containing the morph columns. Plus 4 new apply_schema tests and 3 new create_relationship tests.

CrudToolsTest's "rejects an unsupported relationship type" was asserting the gap itself (morphMany errors) — it now uses hasManyThrough, which is still genuinely unsupported.

Both suites green: 686 package, 608 root.

MCP Server — Column Vocabulary Parity + Enum Correctness

Date: 2026-08-18 Status: Complete Plan: docs/14-MCP-SERVER-PLAN.md

Follow-up to the relationship-coverage work above. Auditing the rest of the MCP surface for the same defect class turned up four issues, three of them identical in shape to the ones just fixed.

1. add_column silently coerced an invalid type

AddColumnTool declared type as a bare string with no enum, and SchemaMutator::addColumn() did ColumnType::tryFrom(...) ?? ColumnType::String. Probed directly: type: "varchar" became a string column, no error. This was the same silent coercion as the relationship pass's ?? HasMany, and a test (CrudToolsTest > falls back to string for an unknown column type) had pinned it as intended behavior.

addColumn() now throws SchemaMutationException listing the valid types, and the tool's type enum is generated from a new ColumnType::values().

2. Enum columns generated a migration that cannot run

Nothing required values for enum / set. MigrationGenerator guards on $column->enum_values and fell through to the plain branch, emitting:

$table->enum('status');

That is not valid Laravel — enum() needs its allowed-values array, so the generated migration throws on php artisan migrate.

Reachable two ways. Via MCP/AI, because enum_values could not be set at all (issue 3) while enum was advertised as a valid type in both the tool description and the SchemaDesigner prompt. And via the canvas — not through the add-column form, which already validates newColumnEnumValues as required for those types, but through TableEditor::updateColumn(), which let an inline edit switch a column's type to enum or clear the values off an existing one with no validation at all.

Fixed at all three layers: addColumn() rejects a valueless enum/set, updateColumn() rejects the switch and the clear, and MigrationGenerator degrades a legacy valueless enum to string('x') so already-saved projects still generate something that migrates.

3. MCP could not set 7 of a column's attributes

SchemaMutator::addColumn() already accepted length, precision, scale, default_value, is_unsigned, enum_values and comment — only the callers never passed them. AddColumnTool now exposes all seven, and AiSchemaChat had three duplicated inline column-creates (pass 1, pass 2, mergeTableChanges), each copying five flags and each with its own ?? ColumnType::String fallback; all three now route through one private createColumns() helper that delegates to the mutator and skips a rejected column rather than aborting the merge.

4. get_schema was lossy in both directions

SchemaSerializer emitted only name/type/nullable/is_unique/is_index, so a decimal read back without its precision and an enum without its values — and apply_schema could not restore them. It also kept morph columns, because the is_foreign filter misses them by design, contradicting the contract's own rule that implied columns are never declared.

It now carries the seven attributes (each key present only when set, so a plain string column stays as terse as before) and derives the implied morph pairs from the project's relationships in order to filter them alongside foreign keys.

Tests

• SchemaSerializerColumnsTest (6) — attribute round-trip, terse output for a plain column, and FK/morph-pair omission on both a polymorphic target and a morphic pivot.
• SchemaMutatorRelationshipTest +7 — type rejection, enum/set requiring values, enum_values accepted as a list or comma-separated string, and the generator's legacy-valueless-enum fallback.
• TableEditorTest +3 — the inline-edit guard in both directions, and that setting values first then switching type is allowed.
• CrudToolsTest +4, ApplySchemaToolTest +3.

CrudToolsTest > falls back to string for an unknown column type was replaced by rejects an unknown column type instead of falling back to string — it was asserting the defect.

Doc corrections

docs/14 claimed add_column "validates type against ColumnType" (§4) and "rejects an invalid type with a clear message" (§7). Neither was true when written; both are now.

Both suites green: 702 package, 615 root.

MCP Server — Edit and Delete Tools

Date: 2026-08-18 Status: Complete Plan: docs/14-MCP-SERVER-PLAN.md

The last gap against the canvas editor. MCP could create and delete tables and columns, but not edit them, and could not delete a relationship at all — so the morph-column cleanup the editor does had no MCP counterpart.

New tools

All three go through SchemaMutator, which gained renameTable(), updateTableOptions(), updateColumn() and deleteRelationship().

Guards worth noting

Pivot tables cannot be renamed. A pivot's name is duplicated onto every relationship that uses it as pivot_table_name, which MigrationGenerator and ModelGenerator both read; renaming the table without rewriting those emits migrations for a table that does not exist. The canvas disables the name field for pivots (and for system tables) in the Blade template only, which is not a check.

Corrected: this entry originally claimed putting the rule in the mutator closed the hole for the web path as well. It did not — updateTableName() used the mutator only for normalizeName() and tableNameRules(), and wrote the column itself, so only MCP was guarded. updateTableName() now delegates to renameTable() and surfaces its refusals on the tableName error bag, with a test asserting a pivot rename is rejected.

Deleting a relationship never takes something another one needs. Three cases: a foreign key shared with the mirrored relationship on the other side of a one-to-many; a morph name shared by a second polymorphic parent on the same child; and a pivot table shared by two polymorphic many-to-many sides. The editor's version of this logic destroys the pivot unconditionally — safe there only because it blocks reusing a pivot name in the first place. Through SchemaMutator a shared pivot is reachable (it is how the canonical taggables shape is built), so the delete checks for remaining references first.

enum guard on edits. updateColumn() evaluates the enum rule against the resulting state, so switching a column's type to enum without values in the same call fails, as does clearing the values off one that is still an enum.

Server instructions were stale

LaraSchemaServer::$instructions — the prompt every MCP client reads — still said "Unknown types fall back to string" and listed only four relationship types. Both were wrong before this session's earlier changes and would have actively steered a model into the broken shapes. Rewritten to cover all eight relationship types, the full column vocabulary, the enum requirement, the implied-columns rule, and the both-sides convention for one-to-many and many-to-many.

Tests

tests/Feature/Mcp/MutationToolsTest.php (20) covers all three tools including the rename normalization, the system- and pivot-table refusals, selective updates, null-clearing, the enum switch in both directions, and every delete-cleanup case — FK, pivot, morph pair, second-parent morph pair retained, and shared pivot kept until the last relationship goes. ToolAnnotationsTest's dataset covers the new tools' titles and safety hints. SchemaMutatorRelationshipTest +5 for the mirrored-FK invariant, the same-source morph-name invariant, and updateColumn edge cases (comma-separated enum string, a scale of zero, duplicate rename).

Doc and UI lists updated: docs/14 §4, docs/15's annotation table, and the tool list on the /mcp-tokens page.

Both suites green: 707 package, 638 root.

MCP Server — Project Entry Points (create_project, import_sql)

Date: 2026-08-18 Status: Complete Plan: docs/14-MCP-SERVER-PLAN.md

Until now the MCP server could edit schemas but not start one. list_projects returned what already existed, and every mutation tool required a project_id, so a user driving LaraSchema from Claude Desktop had to open the web app, create a project by hand, and come back. That undercut the whole point of the connector.

create_project

Creates an empty project owned by the caller and returns its id.

The important part is that it does not just insert a row. ProjectManager::createProject() also builds the protected users table — five authentication columns, is_system so it cannot be renamed or deleted — because the generated Filament panel logs in against it, and a project without it produces an app nobody can sign into. A tool that skipped that would produce projects that export broken.

So project creation moved into SchemaMutator::createProject() plus a public createDefaultUserTable(), and ProjectManager was refactored onto them, deleting its private copy (~2.2 KB). Ownership stays with the caller: the Livewire component passes a user_id or a guest token, the MCP tool always passes the authenticated user_id. The guest project limit is a web concern and does not apply.

import_sql

Turns a SQL dump into a new project, reusing the exact services behind the web wizard — SqlSchemaInspector::inspect() and SchemaImporter::import() — so an imported project is indistinguishable from one imported through the UI.

• preview: true reports the tables, their column and foreign-key counts, and which are pivots, without creating anything. Lets the model show the user what it found and ask before committing.
• tables: [...] imports a subset, validated against the dump's actual tables so a typo is answered with the real list rather than a silent partial import.
• Capped at 5 MB, matching the web wizard's max:5120 upload rule.
• The response carries inferred_relationship_count and has_foreign_keys, so a dump with no declared FKs — where relationships were guessed from *_id naming — can be flagged to the user as needing a check.

Always creates a NEW project; it never merges into an existing one. The tool description says so, and points at apply_schema for merging.

Server instructions

Step 1 of the designing flow now offers all three entry points — list_projects for existing work, create_project from scratch, import_sql from a dump — and a convention notes the protected users table so the model builds on it instead of adding a second one.

Tests

tests/Feature/Mcp/ProjectToolsTest.php (12): ownership and the exact authentication column set for create_project, canvas settings present so the editor can open the result, and that get_schema can immediately read a just-created project; for import_sql, columns and foreign keys imported, INSERT statements ignored, preview creating nothing, subset selection, the unknown-table error naming what the dump does contain, no-CREATE-TABLE input, the name requirement, and that an imported project is editable by the schema tools.

The 212 existing Livewire tests cover the ProjectManager refactor unchanged.

Both suites green: 707 package, 663 root.

AI Assistant — Explicit Removals and Renames

Date: 2026-08-18 Status: Complete

apply() could only add. A user asking the assistant to "drop the audit table" or "rename posts to articles" got a confident reply and no change — or worse, a duplicate. Probed before starting:

after first apply:                              posts, comments
after "rename posts→articles, drop comments":   posts, comments, articles
articles columns after dropping title:          title

Why removals are explicit rather than diffed

The obvious design — treat the returned schema as desired state and delete anything missing — is unsafe here, and the reason is in the prompt builder: SchemaDesigner summarises the injected schema to table and column names once it exceeds 40 KB, then instructs "never omit existing tables". On a large schema the model is not shown enough to reproduce it, so inferring deletion from absence would delete tables it was never given. Removals and renames are therefore two explicit blocks:

{
  "renames":  { "tables": [{"from": "posts", "to": "articles"}],
                "columns": [{"table": "articles", "from": "body", "to": "content"}] },
  "removals": { "tables": ["audit_logs"],
                "columns": [{"table": "articles", "name": "legacy_flag"}],
                "relationships": [{"type": "hasMany", "source_table": "users", "target_table": "articles"}] }
}

Renames run first, so a table listed under its new name merges into the existing row instead of creating a second one. Removals run last. Both delegate to SchemaMutator, inheriting its guards — system and pivot tables cannot be renamed, required columns cannot be dropped — and an instruction that cannot be carried out is collected in a skipped list rather than aborting the apply.

Undo had to be rebuilt first

buildCanvasSnapshot() stores only table_ids, column_ids and relationship_ids, and undoApply() works by deleting whatever is not in those lists. That undoes additions perfectly and cannot undo a deletion at all — an id list has nothing to restore from. Shipping a destructive apply on top of it would have meant unrecoverable data loss behind an Undo button.

So apply() now returns a report, and SchemaMutator gained describeTable() / describeColumn() / describeRelationship() — capturing the canvas geometry SchemaSerializer omits — plus restoreRemoved(), which rebuilds tables first, then columns, then relationships through createRelationship() so their foreign-key and morph columns come back too. applySchema() merges that report into the undo snapshot; undoApply() reverses renames by name (a renamed row keeps its id, so the id-based steps leave it renamed) and then restores the removals.

Two cascades are captured that nothing announced before: deleteTable() removes the table's relationships, and deleteColumn() removes relationships that used the column. Both are recorded so undo restores them.

SchemaChatService::apply() changed from void to returning the report; the contract, the adapter, Canvas and ApplySchemaTool were updated together.

The preview shows deletions

Canvas::schemaDiff() was additive-only — newTables, modifiedTables, unchangedTables, newRelationships. It now also returns renames and removals, and computes them even when no tables are proposed, since "drop the audit table" is a complete instruction on its own and the destructive half of the preview must never be the part that gets skipped. The blade renders removals in red with a warning icon, a per-table column count, and a note that it can be undone.

A bug the tests caught

ApplySchemaTool validated schema.tables and schema.relationships but not the new blocks. Laravel's nested validation prunes keys it has no rules for, so renames and removals were silently stripped between the request and apply() — a removals-only call reached a schema key that no longer existed. Both are now declared, with a regression test for the mixed tables-plus-removals case.

Tests

• tests/Feature/Mcp/ApplySchemaRemovalsTest.php (18) — renames without duplication, column renames resolved against either table name, every removal kind, the users-table refusal, that omission still never deletes, removal-only schemas, restore fidelity (length, unique, enum values), restore of cascaded relationships, idempotent restore, and the MCP round trip.
• tests/Feature/Ai/CanvasUndoRemovalsTest.php (7) — undo brings back a removed table with its columns and relationships, a removed column, reverses table and column renames, handles a mixed add-and-remove apply, and the preview lists both renames and removals.
• SchemaDesignerInstructionsTest extended to pin the new prompt contract.

Both suites green: 707 package, 694 root.