Filament

@webship.co/workspace-filament 1.0.0 · github.com/webship/workspace-filament · npm

Filament for the Webship Workspace dashboard, on top of its Laravel plugin (@webship.co/workspace-laravel): a builder that makes a real Laravel app with an admin panel in a container — a new app with the panel installed the documented way, or the panel's official demo app with its own seed — the default accounts, the Filament step pack wired into the workspace's testing setup next to the Laravel one it extends, and its AI items — two agents, a skill, a command and two prompts — each listed in the workspace folder of its kind.

The workspace is container-based (DDEV by default): an app with a panel is a Laravel project like any other, so the row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it unchanged.

It builds on the Laravel plugin: a new app is made by that plugin's builder (the official installer and a starter kit), the accounts are written with its account writer (the password hashed with the app's own hasher), and the panel's command line is that plugin's Artisan tool (cmd-tools-laravel-artisan.sh, with the panel's make:filament-* and filament:* commands).

Use it

cd ~/workspace
bash core/scripts/plugins.sh --require @webship.co/workspace-filament --with-needs   # npm install into the dashboard, with the Laravel plugin
bash core/scripts/plugins.sh --activate filament --with-needs                         # plugins.filament in settings.yml, and what it needs
bash core/scripts/plugins.sh --install filament                                       # the builder, functions, args, AI items
bash core/scripts/plugins.sh --configure filament                                     # nothing to configure: it has no settings file

The same four steps are buttons on the dashboard's Settings → Plugins page. --install is idempotent. --uninstall removes what it placed; an AI item you edited stays. The Laravel plugin cannot be deactivated or uninstalled while this one is in use: take this one off first.

Everything the plugin carries lands in the folder it belongs to, when that folder is an active workspace folder:

What Lands in
cmd-filament-project.sh every active sites folder: dev/, test/, sandboxes/, demos/
The panel's first feature core/scripts/plugins/filament/, beside its functions
The agents filament-site-builder, filament-tester ai-agents/
The skill filament-scenarios ai-skills/
The command /filament-test ai-commands/
The prompts filament-build-and-test, filament-scenarios-for-a-resource ai-prompts/

There they are listed like any other item of the folder, and installed into Claude Code from there.

What it needs

A workspace starts empty, so the manifest says what else this plugin needs (needs):

  • one sites folder, for the builder: dev, test, sandboxes, demos (dev is the one added when none is there). The folder also carries cmd-tools-testing.sh and the Users tools this plugin's hooks answer to.
  • laravel, the Laravel plugin, 1.0.1 or later: a new app is made by its builder (laravel_build), the accounts are written with its writer (laravel_write_accounts, which hashes the password with the app's hasher from 1.0.1 on: the demo app's User model does not hash it itself), its testing hook adds the Laravel step pack beside this one, and the panel's Artisan goes through its tool. --with-needs requires it from npm (@webship.co/workspace-laravel), or from the folder beside this package when it was required from a path.
  • ai-agents, ai-skills, ai-commands and ai-prompts: the AI folders its agents, its skill, its command and its prompts are placed in.

--require says so, --activate and --install stop until the workspace has them, and --with-needs adds what is missing first:

bash core/scripts/plugins.sh --activate filament --with-needs   # dev, laravel and the four AI folders are required, activated and installed first
bash core/scripts/plugins.sh --install filament

Everything the builder runs for an app runs in the app's own container, through the container tool the workspace already needs: PHP, Composer, Artisan and Node.js are in the web container. The plugin asks for no command of its own on the machine (the demo app is downloaded with git, which the workspace already uses).

What the package holds

Path What it is
commands/cmd-filament-project.sh The builder, in the Build list as Filament (admin panel on Laravel), installed into every sites folder
scripts/functions/fun-filament.sh The bash functions behind it, sourced by bootstrap once installed; the names the core's tools look for (set_filament_users, add_filament_users, cancel_filament_users, testing_configure_filament)
scripts/args/arg-filament.sh Its argparse; the Build form draws the builder's flags from it
testing/panel.feature The first feature an app with a panel gets when testing is set up, with the paths of its panel filled in
ai/agents/filament-site-builder.md The agent that builds and maintains apps with a panel with these commands
ai/agents/filament-tester.md The agent that writes and runs scenarios with the panel's step pack
ai/skills/filament-scenarios/ The skill: the step packs' phrases by area, the traps found on a real panel, three example features
ai/commands/filament-test.md The slash command /filament-test <app>: set up, match every step, run, report
ai/prompts/filament-build-and-test.md, filament-scenarios-for-a-resource.md Two prompts: whole launch commands for a new session
src/index.ts register(api): what the assistant is told about Filament here
features/filament.feature Scenarios for the dashboard's own browser suite

The workspacePlugin block in package.json is the manifest the installer reads.

The builder

Run it from a sites folder. --help is safe.

cd ~/workspace/dev
bash cmd-filament-project.sh myapp --install --add-users            # a new app, its panel at /admin
bash cmd-filament-project.sh mydemo --install --add-users --demo    # the panel's official demo app
Flag What it does
--install Migrate the database (with --demo, with the demo's own seed: a shop, a blog, an HR suite and their records) and write the workspace account as the panel's first account, its address verified. Without it, the app is built and its database left to migrate
--add-users With --install: add the default accounts
--demo The panel's official demo app (filamentphp/demo, MIT) at the head of the branch of the panel's release line (5.x), with the newest release of the panel of that line, built as its README builds it. Its admin panel is at the root of the app, a second panel with teams at /app. Without it: a new app made by the Laravel plugin's builder with composer require filament/filament and artisan filament:install --panels, its panel at /admin
--starter-kit <kit> Without --demo: the starter kit of the new app, livewire (the default), react or vue
--production Run the app as a live app runs (APP_ENV=production, APP_DEBUG=false): the error pages instead of the debug page
--php-version <x> The PHP of the project container (8.4 by default: the demo app's packages need it)
--launch Open the panel when it is ready

What the builder changes, each change marked "Webship Workspace" where it is made: the User model says which accounts the panel lets in, as the panel's documentation shows it for an app in production (an address verified); the demo app's admin panel checks it with the panel's own middleware on every page; a new panel offers the password reset; the app's mail gets a sender address (the password reset mail needs one); a new app runs its queue in the request (QUEUE_CONNECTION=sync: the panel's password reset mail is a queued notification, and a local app runs no queue worker).

The app answers at https://myapp.ddev.site (the panel at /admin, or at the root of the demo app), its mail catcher at https://myapp.ddev.site:8026. The builder runs ddev config --project-type=laravel with the Node.js of the workspace (24); the container tool writes the database settings, the builder writes none. A project of the same name is deleted first.

Nothing paid and no account anywhere: the open-source panel from Packagist and its open-source demo app.

The panel's command line

The panel's CLI is Artisan, through the Laravel plugin's tool:

bash cmd-tools-laravel-artisan.sh myapp                                              # the app, its versions, its accounts
bash cmd-tools-laravel-artisan.sh myapp --run "make:filament-resource Post --generate"
bash cmd-tools-laravel-artisan.sh myapp --run "filament:upgrade"
bash cmd-tools-laravel-artisan.sh myapp --update                                     # packages, migrations, assets

The default accounts

Account Address What the panel does with it Handle in the tests
administrator administrator@example.com lets it in: its address is verified administrator
unverified unverified@example.com refuses it: its login form says the credentials do not match, and a session of it gets the 403 page unverified

A panel has no roles of its own: what it decides is whether an account may use it, so the list holds one account it lets in and one it refuses, with the password of the workspace's other default lists. They are for local apps and for tests; the panel's first account is the workspace account and is never written into a test. bash cmd-tools-add-users.sh myapp filament adds the same list (bash cmd-tools-cancel-users.sh myapp filament deletes it); adding them again gives them back their password and their state. An app with a panel is a project of the DDEV type laravel, so the row's Users menu on the dashboard adds the Laravel plugin's list: the panel's own accounts come with the builder's --add-users, the testing setup, and the command above.

Test an app with a panel

bash cmd-tools-testing.sh myapp                 # webship-js, both step packs, the users registry, the first feature
bash cmd-tools-testing.sh myapp --run           # run the suite in the container
bash cmd-tools-testing.sh myapp --run --path tests/features/site.feature
bash cmd-tools-testing.sh myapp --list-steps    # the step packs the project has, in one profile

cmd-tools-testing.sh is the workspace's own. For an app with a panel, this plugin's hook adds @webship-js/filament-steps to package.json and its step definitions to cucumber.js right after webship-js's, writes the users registry (administrator, unverified; overridable with FILAMENT_<HANDLE>_EMAIL and FILAMENT_<HANDLE>_PASSWORD), the panel's home and login page (homePath, loginPath), the mailbox of the project (mailUrl), the tags that keep the packs' assertions that must fail out of a normal run, places tests/features/site.feature with the paths of the panel when the project has none, and makes sure the default accounts are on the app. The Laravel plugin's hook then adds the Laravel step pack beside it and keeps what this one wrote. Run it again and it adds what is missing and keeps what you changed.

The AI items

ai/ in the package holds one folder per kind, the manifest's ai block names each item, and --install places it in the workspace folder of that kind.

Kind Item Use it to
Agent filament-site-builder Build, update, maintain or remove an app with a panel with the builder and the Artisan tool, in containers only, with no account of the vendor and nothing paid
Agent filament-tester Set the testing stack up, look at the panel in the Playwright MCP browser first, write scenarios from the packs' steps and run them; it never creates an account in a suite, deletes what a scenario made, and never writes a platform name into a step phrase
Skill filament-scenarios Write a scenario from phrases that exist: the packs' steps by area, the handles of the users registry, the traps found on a real panel, and three features that pass on the demo app
Command /filament-test <app> [feature or @tag] Run the suite of an app from inside a session: set up when missing, match every step, run, report what failed and why
Prompt filament-build-and-test Start a session that builds an app with a panel, says what it is, sets the testing stack up and runs the first feature
Prompt filament-scenarios-for-a-resource Start a session that writes and runs the scenarios of one resource of the panel: its list, its form, its actions

After --install each is in its folder on the dashboard. Install there puts an agent, a skill or a command into Claude Code (~/.claude/agents, ~/.claude/skills, ~/.claude/commands), or from the command line:

cd ~/workspace/ai-agents   && bash cmd-tools-ai-items.sh filament-tester --install
cd ~/workspace/ai-skills   && bash cmd-tools-ai-items.sh filament-scenarios --install
cd ~/workspace/ai-commands && bash cmd-tools-ai-items.sh filament-test --install

A prompt is not installed: it is the whole claude … launch command of a new session, and the dashboard's New screen form lists it as a template. By hand, fill the placeholders in and run the command of the file from the folder it names.

The items are written for any AI CLI, with Claude Code as the default shape: the frontmatter and the file layout are Claude Code's, the body of each item is plain Markdown that names no tool or feature of one CLI, a command says in words what its arguments are, and the text between the triple quotes of a prompt can be given to another AI CLI as it is.

Every step phrase the items show is checked against the definitions of the panel's step pack, of the Laravel pack it brings and of webship-js (tests/fixtures/step-definitions.txt), and every command and flag against the plugin's own, the Laravel plugin's and the workspace's.

Develop it

npm install     # builds dist/ (TypeScript)
npm run lint
npm test        # the manifest, the builder, the AI items, the functions against a scaffolded project

CI runs the same on Node.js 20 and 24, parses every shell script, and runs the plugin's features/filament.feature against a dashboard with this plugin (and the Laravel plugin it needs) installed (webship/workspace/.github/workflows/plugin-browser-suite.yml).

When the step pack's release line changes, refresh the fixture from a project whose testing stack is set up: node <this plugin>/tests/fixtures/refresh-step-definitions.js > <this plugin>/tests/fixtures/step-definitions.txt.

In pictures

Build a Filament admin panel

  1. Add the plugin: require, activate and install @webship.co/workspace-filament (see "Add a Webship Workspace plugin"). Its tab in Settings says it is turned on and what it needs.

    bash core/scripts/plugins.sh --require filament

    The Filament tab in Settings: the plugin, its package and version, what it does, and that it is turned on.

  2. Open a sites folder such as Dev, pick "Filament (admin panel on Laravel)", type a name and open Arguments for its options.

    The Build form of Dev with "Filament (admin panel on Laravel)" chosen and its arguments open.

  3. Press Build. The builder makes the admin panel in a container (DDEV by default) and runs in a screen session you can watch on Screens.

    bash dev/cmd-filament-project.sh filament-demo --install --add-users
  4. A Filament app is a Laravel app: the Laravel plugin, which it needs, brings cmd-tools-laravel-artisan.sh for it.

  5. The plugin brings two AI agents, a site builder and a tester. They are on AI Agents, ready to install into your AI CLI.

    AI Agents filtered to the agents of the Filament plugin: its site builder and its tester.

Test it

  1. Set up testing on the built admin panel: Tests → Set up the testing environment, or the command. The setup wires the Filament step pack (@webship-js/filament-steps) into cucumber.js with the accounts registry and writes a first feature, tests/features/site.feature.

    bash cmd-tools-testing.sh filament-demo

    The @webship-js/filament-steps step pack as Tests → Extra steps lists it: its logo, version and what it covers.

  2. Run the tests from Tests → Run the tests, or the command. The run is a screen session, and the row shows the result.

    bash cmd-tools-testing.sh filament-demo --run
  3. The tester agent writes and runs scenarios with the step pack. For tags, one feature, dry runs, failures and recordings, see "Test a project with Webship-js".

    AI Agents filtered to the agents of the Filament plugin: its site builder and its tester.