README

Part of Barn.

The barncept command: barncept init, which sets up a project to use Barncept by recording where its concepts live, barncept check, which says whether every concept still composes, barncept export, which prints or writes one as a document, folders or a diagram, and — when Barncept GUI is installed alongside — barncept gui, which opens those concepts in a browser.

Requirements

PHP 8.5+

Installation

composer require rmb32/barncept-cli

Usage

vendor/bin/barncept init                          # prompts; blank = concepts/custom
vendor/bin/barncept init --concepts=concepts/my   # non-interactive
echo "my/concepts" | vendor/bin/barncept init     # piped answer
vendor/bin/barncept init --concepts=concepts/my --borrow-from=vendor/acme/shared

This creates (or updates) barncept.json at the project root, and creates the concept folder if it doesn't exist. Commit barncept.json with the rest of your project. Re-running init updates the existing file.

--borrow-from (repeatable) records read-only folders of concepts your own can borrow from, in barncept.json's borrowFrom. A later source shadows an earlier one, and your own concepts shadow them all.

Other Barn tools read it — for example barnscaff scaffold library Root ./out resolves library to <concepts folder>/library.json.

Checking every concept

A concept that borrows another reads it afresh each time, so a change to one concept can break the concepts that borrow it. check composes every concept in the project and prints one line for each:

vendor/bin/barncept check

Checking the concepts in /path/to/project/concepts
Garden: open: nothing chosen yet
House: broken: Concept "Kitchen" references concept "Room" but no such concept is registered
Kitchen: broken: Concept "Kitchen" references concept "Room" but no such concept is registered
Pet: open: nothing chosen yet

Each concept is settled (every slot beneath its entry points is filled), open: <slots> (some are still open), open: nothing chosen yet (a plan with no entry point), or broken: <problem> (it does not compose, with the first problem found). Files that can't be read follow, as fault: <file>: <reason>.

It reads the same barncept.json as init writes, or concepts/ when there is none. It exits with 1 if any concept is broken or any file is faulty, and 0 otherwise. Open slots don't fail it, because a plan left open is often deliberate. That makes it a CI step:

- run: vendor/bin/barncept check

Exporting a concept

export resolves one entry point of a concept and prints it, or writes it with --to:

vendor/bin/barncept export House                          # the tree, to stdout
vendor/bin/barncept export House "Orchard Lane" --as=markdown
vendor/bin/barncept export House --as=markdown --to=docs/house.md
vendor/bin/barncept export House --as=folder              # a preview; writes nothing
vendor/bin/barncept export House --as=folder --to=house   # one folder per thought
vendor/bin/barncept export House --as=mermaid | mmdc -i - -o house.svg

`--as`	What you get
`text` (the default)	the indented tree
`markdown`	a document: a heading per thought, its meaning beneath, "Kitchen: Our kitchen" for a choice
`folder`	a folder per thought, each with a `README.md`; without `--to`, the tree of folders it would write
`mermaid`	a Mermaid `flowchart`, which GitHub draws as it is; pipe it into mermaid-cli for SVG

$ vendor/bin/barncept export House --as=folder
12 Orchard Lane/
├── README.md
├── Ground floor/
│   ├── README.md
│   ├── Hallway/
│   │   └── README.md
…

The entry point is a key, and may be left out when the concept has exactly one settled entry point. Otherwise export lists each one with its open slots and exits with 1:

$ vendor/bin/barncept export Kitchen
Kitchen has no single settled entry point; name one.
  Shaker kitchen: open: Space::Lighting

--to never overwrites and never merges: a file must go to a path that does not exist yet, and folders to one that does not exist or is an empty folder. A thought whose name cannot be a folder (Why?, a trailing dot, two siblings that differ only in case) is reported, every one at once, rather than renamed. An unknown --as lists the kinds there are. Every refusal goes to stderr and exits with 1, with no stack trace.

The GUI

With rmb32/barncept-gui installed in the same project, the CLI also offers:

vendor/bin/barncept gui                    # http://localhost:8082, opens your browser
vendor/bin/barncept gui --port=9000        # start looking for a free port here
vendor/bin/barncept gui --no-open          # don't open a browser
vendor/bin/barncept gui --dry-run          # print what would be started

It serves the concept folder from this project's barncept.json (or concepts/ when there is none), picking the next free port if the default is taken. Stop it with Ctrl-C. Without the GUI package installed, gui simply isn't offered.

rmb32 / barncept-cli

Package info

Security

Statistics