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: clone a template into a project under a name you give and make its folder, browse the folder's tree, fill the slots its template offers, run conformance checks, and keep templates of your own.

The Barnark GUI: the project's one folder, src, following Hotel, its own copy of Domain Driven Design, with the shipped templates below it, and its tree open with Create New Aggregate and Create New Context buttons where the template allows them.

The side panel has two headings. Project holds the project's one bound folder and its template. Templates holds your own templates first, then the shipped ones, marked Shipped, which are read-only. Click a shipped template to see its tree; click one of your own to see its History.

Clone into the project makes the project's template and its folder together. You pick a template, and beside the choice is the shape a folder following it takes: the folders every clone has, ‹named›/ placeholders for the member types you add to yourself, and the members a template of your own already has. Point at any part to see what it is for. You also name the project's template: it is a copy of the one you picked, and changing one never changes the other. A project has one template, so once it has one, cloning is turned off.

Copy makes a new template of your own from any template, shipped, yours or the bound one, members included. Delete removes one of your own templates, and only git brings it back. The project's template and its folder have no Remove: ending a template's life is not built yet.

In Browse, 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 bound 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 bound 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.

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

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

Method	Path	Behaviour
GET	`/api/barn`	Return `{ root, folder }`. The root is `null` if no barn was found.
POST	`/api/barn`	Create `.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/folders`	List the bound folder, with its template
POST	`/api/folders`	Clone a template into the project and make its folder (`{ 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}/members`	Add a named member (`{ collectionPath, memberType, name }`)
GET	`/api/folders/{path}/check`	Run a conformance check against the folder's template
POST	`/api/folders/{path}/template-folders`	Add a folder of the template's own (`{ folderPath, meaning }`, `folderPath` inside the bound 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/meaning`	Change what a folder of the template's own means (`{ folderPath, meaning }`, `folderPath` `""` for the bound folder); returns `{ changed }`
GET	`/api/templates`	List every template: the bound one, your own and the shipped ones, each with its `description`, `folder` and `shipped`
POST	`/api/templates`	Copy 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}/shape`	A 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`
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}/revisions`	List the template's revisions, with reasons, timestamps and the current marker
GET	`/api/templates/{name}/revisions/current`	Read 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.

rmb32 / barnark-gui

Package info

Security

Statistics

README

Requirements

Installation

Run it

Serving it from your own front controller

JSON API

Related packages

More docs

License