README

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

A barn is a project with a .barn/ folder. This package builds a new PHP project with Barnspec for stories and scenarios and Barnark for architecture templates and folder checks. Its browser UI shows the Spec and Ark views side by side.

Requirements

PHP 8.5+ with ext-ds 2
Composer, and git (for a new barn's repository)

Installation

To use the Barn CLI from any project, install it globally, with rmb32/barn-gui for the browser UI (barn gui):

composer global require rmb32/barn-cli rmb32/barn-gui

A barn you build requires it itself (require-dev), so vendor/bin/barn is available in that project after Composer installs its dependencies.

Update Barn itself

barn self-update shows your installed version and the latest stable release, then asks before updating the global installation. Press Enter to cancel. A same-version-line update (a patch, or a minor from 1.0 on) uses your current Composer requirement. A breaking upgrade (a new major, or under 0.x a new minor) shows the proposed requirement before asking you to confirm. Self-update requires Composer 2.7 or later. For a project-local copy, use Composer in that project.

To get self-update on an older global installation, including one pinned to an older major, run this once.

composer global require 'rmb32/barn-cli:^0.1' --with-all-dependencies --minimal-changes

Check the result with barn --version. Barn needs PHP 8.5 or later. It uses the shared .barn/ layout for project data, and keeps architecture templates in .barn/barnark/catalogue/. Templates kept in .barn/barnark/templates/ by Barn 6 are no longer read.

Manage apps in an existing project

From the folder containing your project's composer.json, add the app you want to use.

barn add barntree       # Install the Barntree CLI and GUI as development dependencies
barn apps               # See which app CLIs and GUIs are installed
barn gui barntree       # Open the editor
barn update barntree    # Update within the project's current version constraints
barn remove barntree    # Remove direct development requirements and keep .barn data

Use barnark or barnspec in place of barntree. For add, update and remove, use all to select all three apps. If the project has no composer.json, run composer init first. add preserves existing direct requirements.

update and remove show the project and selected packages and ask for confirmation. Press Enter to cancel. Both require Composer 2.7 or later.

Update works on directly declared app packages. Run composer install first if the project has no composer.lock.
Remove keeps runtime requirements and all .barn/ data. Barn lists any packages still installed because another dependency needs them.

Run barn apps from the project root or a subfolder to check Barntree, Barnark and Barnspec in the nearest Composer project. It lists each CLI and GUI separately and flags declared packages whose installed files are missing.

The standalone GUI can also be opened from a subfolder. If it finds no .barn/ folder, it offers to create one. To initialise from the terminal, run composer exec -- barntree init or use the corresponding app name.

Build a barn

barn build shop

It asks for the barn's name, Composer package, root namespace and architecture template, offering a suggestion for each (Domain Driven Design is the default template). Then it asks what to call the project's template: your own copy of the one picked, which src/ is made from and checked against. That name has no suggestion, and can't be a shipped template's name. Each can be given as an option instead:

barn build shop --name="Shop" --package=acme/shop --namespace="Acme\Shop" --template=Library --template-name=Shop

The build folder must be new or empty. You get:

shop/
  .barn/
    barn/settings.json       # names the barn
    barnspec/                # the story map
      settings.json          # where generated Port stubs go: tests/Spec/Port
    barnark/
      tracked-folders.json   # src/ is bound to the template Shop
      catalogue/             # that template, kept as revisions, beside any others of your own
  composer.json              # PSR-4 for src/ and tests/, require-dev rmb32/barn-cli
  src/                       # made from the project's template
  tests/
  .gitignore

then git init (nothing is committed) and composer install; --no-install skips the install. Everything in .barn/ is meant to be committed.

The project's template is a copy, tied to nothing: a later change to the shipped one never reaches it, and nothing in .barn/ names the template it came from. Adding a member to src/ (a new Context, say) adds it to the project's template as a new revision, and so does deleting one. The Ark tab's History shows its revisions, read-only.

A barn has one bound template. The Ark tab also lists the unbound ones: the shipped ones, read-only, and your own, which you make by copying any template.

A folder holding a .barn/ folder is a barn, settings file or not; with none, the barn is called after its folder.

Work in a barn

barn gui        # http://localhost:8090, opens your browser
barn status     # the same overview, in the terminal

The GUI has three tabs:

Home: each area of business with its Scenarios counted by colour (green, yellow, red, not started), and the bound folder with its template and whether it conforms to it.
Spec: the Barnspec GUI, for the story map, scenarios and work.
Ark: the Barnark GUI, for the bound folder, its template and your other templates.

barn gui takes --host, --port, --no-open and --dry-run. Started outside a barn, it offers to build one, and then serves it without a restart.

In the development checkout, give the command an app name to open that app’s standalone GUI.

barn gui barntree
barn gui barnark
barn gui barnspec

Run from the project root or a subfolder. Barn finds the closest composer.json and launches the app installed in that project, using Composer's configured executable directory. The app looks for the closest .barn/ from the folder you started in. The same launch options are available for standalone GUIs. Press Ctrl-C in the terminal to stop the server.

Every tool in the barn finds it from any folder inside it, so these work from src/Context/Ordering as well as from the root:

vendor/bin/barnspec show
vendor/bin/barnark template:check
vendor/bin/port-generator generate ordering
vendor/bin/scenario-bridge run-all ordering

Barnspec, Barnark and Barntree also work without this package. Start a barn with barnspec init, barnark init or barntree init, or accept the offer in the standalone GUI. Port Generator and Scenario Bridge use the Barnspec records in the same barn.

Related packages

rmb32/barn-paths: finds a barn and says where each tool's files are inside it
rmb32/barnspec-cli and rmb32/barnark-cli: the tools' own CLIs
rmb32/port-generator and rmb32/scenario-bridge: turn scenarios into runnable tests

More at the Barn website.

rmb32 / barn-cli

Package info

Security

Statistics