File: CLAUDE.md

Recommend this page to a friend!

CLAUDE.md

File:	`CLAUDE.md`
Role:	Auxiliary data
Content type:	`text/markdown`
Description:	Auxiliary data
Class:	Laravel Truss View a diagram of a Laravel application models
Author:	By Alberto Arena
Last change:	feat: schema export command for CI and tooling (#20) Add `php artisan truss:export`, the command-line counterpart to the dashboard export button, so a CI job, script, or tool can pull the database structure without a human opening the diagram. It writes DBML, JSON, CSV, a Markdown data dictionary, or Mermaid to stdout by default or to a file with --output. The output is deterministic (tables, foreign keys, and indexes are given a canonical order, and nothing time-, version-, or host-dependent enters it), so the same schema always produces the same bytes. That makes the headline CI use case reliable: --check regenerates the export, compares it against --output, writes nothing, and exits non-zero on drift, failing a build when a committed schema file has gone stale. A new src/Export/ layer holds one Generator per format plus a SchemaExporter service that filters and orders the tables and dispatches to the generator. The generators are ported from the browser versions in resources/js; while both coexist they are pinned byte-for-byte to the same golden fixtures, checked from both Pest and Vitest, so the CLI and the dashboard download cannot drift. The export reuses the managed- connection allow-list and the excluded_tables merge, and config exclusions always win over --tables, so it never widens the structure surface the dashboard already exposes. Structure only, no row data, no network call, proven by a canary test that seeds a real row and asserts it appears in no format.
Date:	7 days ago
Size:	`4,998 bytes`

Download

CLAUDE.md ? Instructions for Claude Code

Project Overview

Package: albertoarena/laravel-truss Type: Laravel Composer package Purpose: A live database structure viewer. Scans migrations, builds a cached schema snapshot, and renders it as a scrollable, zoomable ER diagram inside the app. Structure only, no data is ever exposed. License: MIT

Stack

PHP 8.3+
Laravel 12+
Pest for testing
Laravel native schema introspection (`Schema::getTables/getColumns/getIndexes/getForeignKeys`) ? no Doctrine DBAL
Mermaid.js for diagram rendering (no build step)
`spatie/laravel-package-tools` for package scaffolding

Commands

`composer test` ? run the Pest suite
`composer lint` ? Laravel Pint (code style check)
`composer lint:fix` ? fix Pint issues automatically
`npm test` ? Vitest unit tests for the client-side diagram logic (`resources/js`)
`npx playwright test` ? browser tests for the dashboard (`tests/e2e`)
`php artisan truss:show` ? print the database structure as a terminal table (structure only)
`php artisan truss:open` ? open the Truss dashboard in the browser
`php artisan truss:rebuild` ? manually rebuild the cached schema snapshot
`php artisan truss:export` ? export the structure (dbml/json/csv/markdown/mermaid) for CI and tooling; `--check` fails on drift

Frontend assets (JS/CSS + a vendored Mermaid) are served from the package via a gated {prefix}/assets/{file} route ? no vendor:publish, no CDN. Set TRUSS_MERMAID_URL to load Mermaid from a CDN instead.

Conventions (always true)

TDD is mandatory. Write a failing test first, then implement. Never commit implementation code without a corresponding test. Applies to every change: features, fixes, refactors. PHP uses Pest; client-side code under `resources/js` uses Vitest for pure logic and Playwright for rendering/interaction.
No data exposed, ever. Only table, column, index, and foreign key structure. Never row contents. This is the package's core promise, treat it as a hard constraint, not a config default. The boundary is the `CREATE TABLE` definition vs. table rows: column defaults count as structure and are in scope (see `docs/DECISIONS.md`).
Introspection stays pure. Code under `src/Introspection/` must have zero knowledge of HTTP, Blade, or Mermaid. It only builds and returns a schema representation. The detailed layer rules live in `.claude/rules/introspection.md`, which loads automatically when you touch that layer or its tests.
Config is the single source of truth for excluded tables, route path, cache TTL, per-connection settings, diagram styling, focus depth, the large-schema warning threshold, the route middleware stack, and the default viewer allow-list (`authorization.allowed_emails`). Don't hardcode any of these. Authorization is a fixed `viewTruss` gate ? the ability name is not configurable, and the gate callback is always the app's to override. The allow-list only feeds the default gate; it is not a renamable ability. The gate is consulted only in non-local environments (local is open), and a denial returns 404. See `docs/DECISIONS.md` ? Authorization: production-gated model.
Git commits: `type: short subject` (max 50 chars), then a body paragraph explaining what and why, not how. Never include "Generated with Claude Code" or "Co-Authored-By: Claude". Use a heredoc for multi-line commit messages.
Docs stay in sync. Any change to commands, config, or user-facing behavior must be reflected in `README.md` and `docs/` in the same change. The public docs site is a separate repo, `albertoarena/laravel-truss-docs` (published at trussphp.com); it tracks this package and must be updated there too, but it reads from the latest package release, so its update lands when the next release ships and the docs site rebuilds.
Roadmap check on every release. A release is not done until the public roadmap reflects it. When a release ships, review `src/data/roadmap.ts` in the `laravel-truss-docs` repo and move whatever the release delivered into Shipped with its version. A partially delivered item is split: the shipped part moves to Shipped, the remainder stays in Approved next or Exploring (e.g. schema doctor Phase 1 shipped in v1.5.0 while the later phases stayed on the roadmap).

Frontend-specific conventions (keeping the live demo aligned, the no-build/no-CDN asset rule, and where the Mermaid generator lives) are in .claude/rules/frontend.md, which loads automatically when you touch resources/.

Pointers

Architecture and domain model: `docs/DESIGN.md`
Phased build plan: `docs/INSTRUCTIONS.md`
Decision log: `docs/DECISIONS.md`
Path-scoped rules (auto-load when matching files are touched): `.claude/rules/` (`introspection.md`, `frontend.md`)

This file should stay short enough to read in under a minute. If you're about to add detail, it probably belongs in docs/ instead, with a pointer added here.