README

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

Part of Barn.

A browser-based template editor for Barntree. Design reusable Templates and create named Constructions from them. Templates define the structure; Constructions hold real members and keep their own immutable history in the same editor.

Templates

The existing editor works with Barntree Tree files, which can contain both type definitions and a saved item tree. Existing files appear immediately in the Templates catalogue; there is nothing to import or recreate.

Template tree. Pick an entry under Templates to see what it allows from the root down. Maps show their fixed children alphabetically by display name. A dashed Each … row shows what a list repeats and expands to show the member's structure. Select a row to replace the tree with that building block’s details. The disclosure arrow expands a branch; Back to tree restores its expansion and scroll position.
Sidebar. The catalogue lists Constructions before Templates. Opening a Template replaces the sidebar with Tree, Overview, Skeleton, History, Construct and its building blocks. The workspace menu slides in from the right; the back arrow returns the catalogue from the left. Reduced-motion preferences disable these transitions. Templates are sorted by name. Maps, Lists, and Leaves are sorted by identifier and show the display name beside it when it differs. The type groups follow the open template. Drag a type’s six-dot grip onto a map to add a fixed child or onto a dashed row to replace the member type. Use Add child or Replace member type for the keyboard alternative. Barntree validates each tree action. Only the focused root or explicitly edited type accepts structural changes. A valid drop from viewing starts a visible edit session. Expanded descendants stay read-only. While dragging, a translucent identifier follows the grabbing cursor. The compatible target directly under the pointer gains an outline and a Drop to add or Drop to replace cue. Releasing elsewhere changes nothing; Save commits a valid drop and Cancel discards it.
Types. Maps, lists, and leaves have separate sections, sorted by identifier with the display name beside it when it differs. Use + beside Maps, Lists or Leaves in the sidebar to add a definition of that kind or select one to inspect its details, then choose Edit. Enter the Name first; Identifier starts with the same text and follows name changes until you edit Identifier yourself. Your custom identifier is then kept when you change Name. An identifier is unique within the template and identifies a type wherever it appears. When editing a map, Add child searches by identifier or display name. The building block’s own page shows an explicit editing form; a map’s main tree shows its draft structure. × removes a complete direct-child connection from the focused map, keeping the definition available. Expanded descendants have no removal controls until their parent is explicitly edited. Maps always sort by display name, ignoring case, with the identifier breaking ties. List members keep their chosen sequence. Use Overview to see the description and, while editing the Template, change Template starts with.
Skeleton. Open Skeleton for a read-only, fully expanded preview of the starting tree. Maps include their required children alphabetically; lists start empty. The preview follows draft Template edits without needing a save and preserves any existing saved items. An item is one element of a tree built from a template; a member is an item in a list with its own name. This editor changes template rules, not individual members.
Tags. A template may declare tags, and a type may carry some of them (Barntree 6.2). A type's tags show as pills beside it, in the Types table and on its own screen; hover one for its meaning. Every save and type change keeps them. They are edited in the document, not here.
Meaning. A type's meaning explains what it is. Write clearly and concisely, with enough detail for humans and AI to understand the tree. Use as many sentences or paragraphs as needed.
Editing and saving. Viewing has no Save button. Choosing ✏️ Edit starts an explicit session, with a persistent heading, a Save button and Cancel. Field edits, × and drag-and-drop share one draft. Save validates and records the complete session as one revision, then returns to viewing; Cancel restores the saved version. Unsaved changes are labelled clearly. Leaving a changed session offers Save, Discard or Stay. Shared definition changes apply to every use within the Template and ask for confirmation; losses are previewed before saving. A Template saved, Map saved, List saved, Leaf saved or Construction saved notification confirms successful persistence. Failed saves retain editing and explain the error.
Creating and managing. The + controls open forms whose Create action saves a Template or building block. A new building block opens in read-only details, with Back to tree returning to the Template’s tree. It stays available but unattached until explicitly placed. Clicking its sidebar text opens details; only the grip drags. Construct, confirmed Template renames and confirmed building-block deletions also finish immediately. Each records history and shows a success notification, with no additional Save. Delete appears in a building block’s details only when it is unused and is not the Template’s root. Opening an existing Template records its saved baseline once. Unchanged saves create no revision.

Each template also has two read-only views, each with a link you can share:

Types (/trees/<name>/types): every type in one table, with what it holds, which you can filter to leaves, lists or maps (?show=list,map). Click a row to open its details.
Glossary (/trees/<name>/glossary): every type with its meaning, grouped by kind, so a newcomer can learn the template's vocabulary in one read. It shows only the meanings you wrote and generates nothing. Click a card to open that type’s details.

View and export under Overview asks you to resolve pending edits before opening the preview. It uses the saved item tree, including any existing list members, rather than the empty-list Skeleton preview. It can show that tree as

Tree: every item by name, indented, for a quick look;
Document: Markdown for people, a heading per item with its type's meaning beneath (shown as its source);
Folders: a folder per item, each with a README.md, for developers and tools, as an expandable tree that shows a folder's README when you select it;
Diagram: a Mermaid flowchart, drawn in the browser, for a README, a pull request or a slide.

Each has an Export button that downloads <tree>.<extension>: a .txt, a .md, a .zip of the folders (built in your browser), or the diagram as an .svg picture or its .mmd source. Export downloads a copy rather than writing a projection into your project; barntree export --to in the CLI writes projections to a chosen path. An item whose name cannot be a folder (Why?, or two siblings that differ only in case) is named in the Folders tab, and the other views still work.

/?tree=<name> opens a template in the editor.

Help in the top bar (/help) explains the words and symbols the editor uses. A square marks a leaf, stacked bars mark a list, and a grid marks a map. Close returns to the screen you opened it from, keeping your draft.

Constructions and History

Select a saved Template and open 🏗️ Construct, highlighted in pale gold in the workspace menu. Its page has a name field and a Construct button. Creating saves the first revision, adds the Construction to the catalogue and opens its initial tree. Its History immediately contains “Construction created”. Pending Template edits must first be saved or discarded.

The outer sidebar lists Constructions alphabetically before Templates, with each source Template’s name beneath its Construction. Selecting one replaces the sidebar with Tree, Overview and History. The back arrow beside its name returns to the catalogue.
Use + Add on an eligible list and enter the member name. Its captured definition determines the allowed type. Constructions have no drag-and-drop or editable building-block palette.
Selecting a tree member replaces the tree with its details and location. Back to tree restores the expanded branches, scroll and member focus. Named list members can be renamed or removed; required map children and captured type definitions remain read-only.
Edit, + Add and member actions start a scoped editing session. Save records the draft together; Cancel restores the saved content. Leaving changed editing offers Save, Discard or Stay.
Overview provides the Construction name, rename and its source Template’s exact revision. The source link opens a read-only snapshot without requiring the live Template file. Captured definitions stay independent of later Template changes. Creation refuses a changed source; errors retain the entered name.

Templates and Constructions each have History in their own workspace navigation. Both show a compact history table, newest first, with 25 revisions per page. Rows show revision number, local date and time, event and identifier. Expand a “changes” row to see the individual changes saved together. Click a revision number to open its read-only snapshot and full GUID; Back to history returns to the same page. Returning to the tree shows the saved current document. Baseline dates record when history began; they are not the original document’s creation date. Renaming retains history, while a copy starts its own.

Templates continue to use .barn/barntree/trees/. Revision metadata is kept behind the storage interface. Barnark integration, exports for Constructions, source upgrades and restoring historical revisions are outside this version.

Requirements

PHP 8.5+
Barntree 8.1+ (installed as a dependency)
Node.js (only if you want to develop the frontend)

Installation

Install it alongside Barntree CLI, which then offers barntree gui:

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

Run it

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

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

It serves the templates of the barn you run it in. Barntree finds the project by walking up to the nearest .barn/ folder. Existing templates are in .barn/barntree/trees/. The page names the barn in use. With no barn, the GUI offers to make one in the folder it was started in, adding only .barn/. It picks the next free port if the default is taken.

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

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

Open http://localhost:8080. BARNTREE_START_DIRECTORY (default: the current folder) is where the search for the barn starts. The tree folder is scanned recursively for *.barntree.json trees. Barntree uses the template’s name to look it up. A template that breaks a rule is listed as broken with the reason. A file without a template name stops the list and shows the fault to fix.

To work on the frontend with hot reload:

cd frontend
npm install
npm run dev     # proxies /api to localhost:8080, serves on :5173

Using the command line

Barntree CLI reads the same Templates, Constructions and history: template:list, template:show, type:show, template:history, construction:list, construction:show and construction:history. construction:show <id> --view=source reads its captured Template. Each read command supports --json. Template/building-block editing is currently available in this GUI.

The CLI also creates and renames Constructions and adds, renames or removes their real list members: construction:create, construction:rename, member:add, member:rename and member:remove. Changes save through the same workspace and appear here immediately. Member removal asks for confirmation; --yes supports unattended use. Write commands offer JSON results and expected-base options. See the CLI README for IDs, options and examples.

JSON API

Method	Path	Behaviour
GET	`/api/barn`	The barn in use: `{ root, folder }`, `root` null when there is none, `folder` where the GUI was started
POST	`/api/barn`	Make a barn in `folder`: only `.barn/`. `409` if the folder is already in a barn
GET	`/api/trees`	`{ trees, fault }`: each tree's `name`, `description`, `rootKind` (`leaf`, `list` or `map`) and `valid`, with an `error` when it is broken; `fault` is `{ path, reason }` for a file that names no tree, when nothing can be listed, else `null`
POST	`/api/trees`	Start an unsaved Template draft: `{ name, description }`, or `{ name, from }` for a copy; returns content without writing
GET	`/api/trees/{name}`	Load one, as written
PUT	`/api/trees/{name}`	Save `{ originalName, token, content }`; new/copy use null originalName and token. Validates content, detects external edits, and records history; returns content and checkout metadata
GET	`/api/trees/{name}/checkout`	Content, conflict token and current revision metadata; establishes an existing Template’s initial baseline once
DELETE	`/api/trees/{name}`	Apply a confirmed deletion with `{token}`; retain historical snapshots
POST	`/api/edits/add-member`	`{ tree, list, name }`: the tree with a member added to the list at `list` (names from the root), its own items made to fit its type. Nothing is written
POST	`/api/edits/remove-member`	`{ tree, member }`: the tree without the member at `member`, or anything beneath it. Nothing is written
POST	`/api/edits/change-types`	`{ tree, root, types }`: the tree with these types and its tree fitted to them. Items of a type still expected where they are stay, new map entries are made, and members and entries whose type has gone are dropped. Nothing is written
GET	`/api/documents/construction`	Alphabetical saved Constructions
POST	`/api/documents/construction/drafts`	Unsaved Construction from `{templateId, name}`
GET	`/api/documents/{kind}/{id}`	Current saved revision, or exact snapshot with `?revision=<revisionId>`; kind template or construction
PUT	`/api/documents/construction/{id}`	Save `{baseRevisionId, content, source}`; stale base returns `409`
GET	`/api/documents/{kind}/{id}/history`	Current identity and newest-first saved snapshots
POST	`/api/edits/rename-member`	`{tree, member, name}`: rename a list member while preserving its identity; nothing is written
GET	`/api/projection-kinds`	`{ kinds }`: each projection's `kind` and `label`, in the order to offer them; a projector the host registers appears here with no frontend change
GET	`/api/trees/{name}/projections/{kind}`	The saved tree projected: `{ kind, mediaType, extension, content }` for a file, `{ kind, tree }` for folders (each folder `{ name, files: [{ name, content }], folders }`). `422` with `problems` (each `{ path, name, fault, message }`) when names cannot be folders; `404` for an unknown kind

With no barn, every other /api/ path answers 409, naming the folder searched from.

A refusal answers with { type, message } and the refusal's own detail: every Barntree refusal carries what it is about as properties, and each one is sent as it is, with keys and kinds as text and lists as lists. A tree that doesn't fit the shape of a tree document answers 422 with every fault at once in faults, each { path, message, code }.

Related packages

Barntree — the trees and model this edits.
Barntree CLI — barntree init for project setup, barntree check for CI, and barntree export to write a projection into your project.
Barnscaff — scaffold a PHP codebase's folders from the trees you edit here.
Barnark GUI and Barnspec GUI — sibling browser tools.

More docs

Internals · History · Known issues

rmb32 / barntree-gui

Package info

Security

Statistics