Search by

rmb32 / barnark-gui

rogerbarnfather

A web GUI for cloning a template into a project and making its folder, creating what the template offers, and viewing conformance checks

Package info

bitbucket.org/rmb32/barnark-gui/

Homepage

pkg:composer/rmb32/barnark-gui

Statistics

Installs: 234

Dependents: 3

Suggesters: 1

v0.2.12 2026-11-15 19:44 UTC

README

Early, version 0.x. Not ready for real projects yet; the minor version is the breaking one.

Part of Barn.

A browser UI for Barnark: copy a scaffold into the project, create arks from it, browse each ark's folders, add what its scaffold offers, run conformance checks, and keep scaffolds of your own. (The command line and the code call a scaffold a template.)

The Barnark GUI: Hotel’s Tree view at /src, with FrontDesk, Property and Reservation contexts, a Booking aggregate, layer tags and buttons for new members.

The side panel has three headings. Arks lists the project's arks by name. Choose one and its views slide in under a back arrow carrying its name: Tree, Check, History, Scaffold, the ark's own scaffold, and Components. Your scaffolds holds the scaffolds you have copied; Barnark scaffolds holds the ones Barnark ships, read-only, among them Blank project, a single empty folder for a project whose shape is still to be decided. An ark's own scaffold is reached through its ark, never listed.

Every scaffold also shows its Components: the building blocks it is made from, each a folder with a meaning, holding fixed folders, a collection of members or nothing. They are grouped as Placed (in the scaffold's tree) and Available (not placed yet, shown only when there are some). Choose one to see its meaning, its tags and what it holds, with a back arrow to the list.

One of Your scaffolds, or an ark's, takes copies: Copy from… finds a component in any of Your or Barnark's scaffolds (Blank component, an empty folder you name, is always first) and adds a copy with everything it holds, available to place. Nothing in the tree uses it yet, so no folder changes. A component's details offer Copy to… one of Your scaffolds or a new one (never on an ark's component: nothing is copied out of an ark), and an available component in one of your own can be Removed, with what only it holds. Later changes to the original never reach a copy. A copy says where it came from, above its tree on a scaffold's page, on an ark's Scaffold tab and in a component's details: "Copied from Aggregate in Domain Driven Design, revision 3", the original linked while it is there, with "original deleted" once it is gone and, for a Barnark scaffold, "changed in Barnark since" when a later Barnark changed it.

Place on a folder of the scaffold's own tree (or Place a component at its top) puts an available component there, under its own folder name. In an ark its folders are then made, one already made by hand being kept, and a collection arrives empty, ready for members. A component is placed only once. One of Your scaffolds opens on its Tree, where folders are added and their meanings changed as on an ark's Scaffold tab, with nothing made on disk, and its history below. There every folder, a member type's included, offers + (a folder), List (a folder that holds members, with the member type each follows), Meaning and Remove, and the top offers Add a list; Remove asks whether to take the folder out of this scaffold only (it stays available to place again) or to delete its definition too. An ark's tree offers neither List nor Remove: it holds members, so its shape only grows.

To make an ark, choose a Barnark scaffold and Copy to Your scaffolds, under a name such as "My DDD". Then, on your copy, Create ark asks for the ark's name and its folder, and says what it does: "Creates the ark Shop from a copy of My DDD. Later changes to My DDD won't reach it." The ark's own scaffold takes the ark's name. A project can have many arks.

Copy makes a new scaffold of your own from any of yours or an ark's, members included. Delete removes one of Your scaffolds, and only git brings it back; copies made from it, arks included, keep working. An ark and its folder have no Remove: ending an ark's life is not built yet.

In Tree, the tree shows a folder's folders (never its files), and wherever the template has a slot for a folder you name, it offers a button for it — on the directory's own row, and inside the directory once it is open. Click, for example, Create New Context, give the new folder a name, and the template's whole structure for it is scaffolded underneath. The folder panel on the left is dragged to whatever width you like (double-click the divider to put it back).

A member is part of the template, so adding or deleting one makes a new revision, with a reason Barnark writes, such as "Added Context/Billing.". Before a member goes, the delete dialog says so. The History tab lists the template's revisions and shows each as a read-only tree of its fixed folders, member types and members.

The Template tab shows the ark's template's current tree with what each folder means. A folder of the template's own offers +, to add a folder of yours inside it with a name and a meaning, and Meaning, to change what it means; Add a folder and Change what /src means do the same for the ark's folder itself. Each is a new revision. A collection holds only members, so it offers no +, and nothing inside a member offers anything. In Check, an unexpected folder offers Add to template: give it a meaning and it becomes part of the template as it is, and the check runs again. If the ark has file rules (set with barnark rule:set), Check also lists, under File rules, each file in a folder whose tag has a rule it doesn't match.

A template can tag its folders, as Domain Driven Design tags its layers Application, Domain, Infrastructure and Transport. A folder's tags show as coloured pills beside its name, in Browse and in a template's tree; point at one to see what the tag means. Above a template's current tree, a bar holds each of its tags: choose one to see only the folders with that tag and the folders above them, every context's Application among them, and choose it again to see the whole tree.

Requirements

Requires Barnark core 0.3 through its installed dependencies; stored barns need no conversion.

  • PHP 8.5+
  • Node.js (only if you want to develop the frontend)

Installation

Install it alongside Barnark CLI, which then offers barnark gui:

composer require --dev rmb32/barnark-cli rmb32/barnark-gui

Run it

If the barnark CLI is installed in the same project, just run:

barnark gui                  # http://localhost:8081, opens your browser
barnark gui --port=9000 --no-open

It serves the barn it is started in: the nearest folder at or above the current one that holds a .barn/ folder, where Barnark keeps its templates and records (.barn/barnark/). It prints the barn's root and picks the next free port if the default is taken. With no barn there, the page says so and offers to make one in the folder it was started in; making one adds only the .barn/ folder.

To start the server directly, run this from the Barnark GUI package directory:

BARNARK_GUI_START_DIRECTORY=/path/to/project php -S localhost:8080 -t public

Open http://localhost:8080. BARNARK_GUI_START_DIRECTORY names the folder the search for a barn starts from, and defaults to the current directory.

To work on the frontend with hot reload:

cd frontend
npm install
npm run dev     # proxies /api to localhost:8080, serves on :5173
npm test        # Vitest + Testing Library

The served bundle in dist/ is rebuilt with composer build-frontend.

Serving it from your own front controller

BarnarkGuiApp::serve($mountPath, $startDirectory) serves the GUI under a path prefix, for example /ark, from any PHP router script:

Rmb32\BarnarkGui\BarnarkGuiApp::serve('/ark', '/path/to/project');

The JSON API below then lives under the prefix too (/ark/api/...).

JSON API

MethodPathBehaviour
GET/api/barnReturn { root, folder }. The root is null if no barn was found.
POST/api/barnCreate .barn/ in the starting folder. Send Content-Type: application/json and an empty JSON object. Returns 409 if the folder is already in a barn.
GET/api/foldersList the project's arks, each with its folder, template and name
POST/api/foldersClone a template into the project as an ark and make its folder ({ ark, name, baseDir, from, template }, where template names the copy); a refused template name is a 400
GET/api/folders/{path}/tree?path=Browse a folder's tree, with the offers (slots that can be filled) at each level and directory, each folder's tags, and the tags its template declares
DELETE/api/folders/{path}/tree?path=Delete a member or a folder the template doesn't know
POST/api/folders/{path}/membersAdd a named member ({ collectionPath, memberType, name })
GET/api/folders/{path}/checkRun a conformance check against the folder's template
POST/api/folders/{path}/template-foldersAdd a folder of the template's own ({ folderPath, meaning }, folderPath inside the ark's folder), then make it unless it is there; returns its rooted path. A change the template can't take is a 409
PUT/api/folders/{path}/template-folders/meaningChange what a folder of the template's own means ({ folderPath, meaning }, folderPath "" for the ark's folder); returns { changed }
GET/api/templatesList every template: the arks', your own and the shipped ones, each with its description, folder, shipped and origin (where it was copied from, or null)
POST/api/templatesCopy a template into a new one of your own ({ from, name })
DELETE/api/templates/{name}Delete one of your own; a shipped one is a 422
GET/api/templates/{name}/componentsA template's components, placed ones first, each with its shape and, when it was copied in, its origin
GET/api/templates/{name}/shapeA template's tree: nested nodes (fixed, memberType or member), each with its meaning and tags, and the tags the template declares, each with its meaning
POST/api/templates/{name}/tree/{key}/foldersAdd a folder ({ name, meaning }) inside the component key of one of Your scaffolds, a member type's or one not placed yet included
POST/api/templates/{name}/tree/{key}/listsAdd a list inside it ({ name, meaning, memberName, memberMeaning }); an ark's template is a 409
PUT/api/templates/{name}/tree/{key}/meaningChange what the component means ({ meaning }); returns { changed }
DELETE/api/templates/{name}/tree/{key}?deleteDefinition=Take the folder out of the tree, keeping its definition unless deleteDefinition=true; returns the keys deleted. The root, a member type, a folder used in several places and an ark's template are a 409
GET/api/templates/{name}/tags/{tag}A template's current tree cut down to the folders with the tag and the folders above them; a tag it doesn't declare is a 404
GET/api/templates/{name}/revisionsList the template's revisions, with reasons, timestamps and the current marker
GET/api/templates/{name}/revisions/currentRead the current template tree, with its tags as shape gives them
GET/api/templates/{name}/revisions/{revisionId}Read a historical template tree (read-only)

The JSON API is the bundled frontend's contract with its server, and changes with the frontend in any release. A {path} or {name} containing / must be URL-encoded as %2F. Folder paths are canonical: rooted, with a single leading slash (/Widgets). The frontend sends the URL-encoded barn root as X-Barn-Root on project requests. If that root has changed, the server returns 409 and asks you to reload.

Related packages

More docs

Internals · History · Known issues

License

Proprietary. See LICENSE. Copyright (c) Roger Barnfather.