Plan format#
Reference for the plan that sourdough new --describe asks a model for, sourdough new --plan <file> reads back (as JSON, or as YAML), and every bake saves in the app as .sourdough/plan.yaml. Every plan is validated against resources/plan.schema.json. For the flags that produce a plan, see Commands.
The plan object#
A plan is a small JSON object:
{
"permutation": "raw",
"parts": ["sesame", "helmet"],
"name": "my-app",
"models": [
{
"name": "Post",
"fields": [
{ "name": "title", "type": "string" },
{ "name": "body", "type": "text" }
]
}
],
"pages": ["/", "/posts"]
}
permutation, parts, and name are required; models and pages are optional.
| Key | Required | Values |
|---|---|---|
permutation |
yes | one of the five permutation values below |
parts |
yes | a subset of sesame, helmet, proctor, and preflight |
name |
yes | the app name |
models |
no | a list of model objects |
pages |
no | a list of page paths, such as / and /posts |
When a plan is printed as JSON, empty models and pages are omitted.
Permutation values#
| Value | Flags | Name |
|---|---|---|
raw |
(none) or --raw |
Raw PHP with WayneUI's standalone path |
raw-vue |
--raw --vue |
Raw PHP + Vue SPA over JSON |
laravel-blade |
--laravel |
Laravel + Blade |
laravel-blade-vue |
--laravel --vue |
Laravel + Blade + Vue islands |
laravel-inertia |
--laravel --inertia (or --inertia) |
Laravel + Inertia/Vue |
Flag resolution, from src/Permutation.php:
--inertiaimplies--laravel: Inertia here means Laravel.--rawand--laravelare mutually exclusive: pick one base.--vueis not needed with--inertia: Inertia already means Vue.- Combinations that make no sense are refused with an error that names the five shapes and their flags.
In 0.1 all five permutations generate.
Parts#
From src/Part.php, the stack parts a Sourdough app is wired with:
| Value | Part |
|---|---|
sesame |
SESAME (auth) |
helmet |
HELMET (baseline runtime) |
proctor |
PROCTOR (checks) |
preflight |
the Preflight CI components |
A plan's parts is a subset of these.
Models#
Each model object has a name and a fields list; each field has a name and a type, both strings, as in the example above.
Pages#
A list of strings, such as ["/", "/posts"].
The saved plan#
Every bake saves its plan in the app as .sourdough/plan.yaml, next to the manifest (ADR-0014, decision 3): the recipe card taped inside the jar's lid. It is written after the bake succeeds, on both paths that bake:
| How you baked | What the saved plan holds |
|---|---|
--plan <file> |
that plan, with the name the app was baked with (--name wins over the plan's name) |
flags (--raw, --laravel, --vue, --inertia) |
the shape, the name, and all four parts, because every shape wires all four in |
--dry-run and a refused bake write nothing, so they save no plan. --describe prints a plan and writes nothing (generation from a description is not built yet), so it saves none either; pass its plan with --plan and that bake saves it. The plan from the example above is saved as:
# The plan this app was baked from, saved by sourdough new (ADR-0014).
# It matches Sourdough's plan schema, so it bakes the same shape again:
# sourdough new <dir> --plan=.sourdough/plan.yaml
# Sourdough never rewrites it after the bake: sourdough feed and
# sourdough manifest --check leave it alone. Commit it with the app.
permutation: raw
parts:
- sesame
- helmet
name: my-app
models:
- name: Post
fields:
- { name: title, type: string }
- { name: body, type: text }
pages:
- /
- /posts
The keys are the plan object's, in the same order, and the comment lines are YAML comments, so the file still matches the schema (which allows no extra keys). --plan reads a file ending in .yaml or .yml as YAML and anything else as JSON, through the same schema, so the saved plan bakes the same loaf again:
sourdough new my-app-copy --plan my-app/.sourdough/plan.yaml
Neither managed nor seeded#
The saved plan is not in the manifest. The manifest lists the files the template wrote, and the plan is not template output: it is what you asked for. Like the manifest itself and .sourdough/base/, it is Sourdough's record about the app, not a file of the app, so it carries neither class:
sourdough manifest --checknever reports it, however you edit it.sourdough feednever reads, rewrites or removes it. Feed bakes from the shape and answers in the manifest, so an edited plan changes nothing a feed does, and an app baked before the plan was saved (Sourdough 0.1.7 and earlier) gets no plan written for it: feed does not guess at what nobody wrote down.
Edit it as the app grows (a new model, a new page), so it stays the record of what the app is for, and commit it with the manifest.
Getting a plan#
Instead of choosing flags, describe what the app does and let a model plan it:
sourdough new --describe "A blog with posts and comments"
Sourdough asks an OpenAI-compatible model for a plan, validates it against resources/plan.schema.json, and prints it. The model kneads the dough, but you decide when the loaf is ready to bake: if the answer is not valid JSON, does not match the schema, or the model gives up after one retry, Sourdough refuses with a message pointing you to --plan=<file> (exit 1). You write the plan yourself and pass it in.
To see the plan as JSON without writing anything:
sourdough new --describe "A blog with posts and comments" --plan-only
--describe stops at the plan: baking straight from a description is not built yet. Save the plan to a file and pass it with --plan, which bakes it:
sourdough new my-app --plan plan.json
--plan reads the file, validates it against the schema, and continues the normal generation flow using the plan's permutation and name. A YAML plan (.yaml or .yml) works the same way, and the bake saves the plan as the saved plan.
Model configuration#
--describe needs three environment variables (no defaults, no key in code):
| Variable | Meaning |
|---|---|
SOURDOUGH_LLM_BASE_URL |
the OpenAI-compatible endpoint, including the API path (usually /v1) |
SOURDOUGH_LLM_API_KEY |
the API key |
SOURDOUGH_LLM_MODEL |
the model name |
Any OpenAI-compatible endpoint works: a hosted API, a local server, or WarriorGPT. Sourdough does not care about the hostname; it only needs the base URL, key, and model.
The steps plan#
The app plan is the what: permutation, parts, name, models, pages. The steps plan in src/Plan.php is the how, that is, what sourdough new will do, and --dry-run prints it. It carries the permutation, the target dir, and a list of steps:
| Condition | Step |
|---|---|
| raw permutation | Copy the raw template into <dir> |
| raw permutation | Replace {{app_name}} and {{app_slug}} in file names and contents |
| raw-vue permutation | Copy the raw template, then the raw-vue template over it, into <dir> |
| raw-vue permutation | Replace {{app_name}} and {{app_slug}} in file names and contents |
| any Laravel permutation | Create the <label> app in <dir> |
| ADVISOR wired in | Wire ADVISOR into the app |
--sail |
Use Sail for the local runtime (compose.yaml, laravel/sail in require-dev) |
--docker |
Use Docker for the local runtime (Dockerfile, compose.yaml, MySQL 8.4) |
--sail and --docker are for the Laravel paths: the raw paths run on plain PHP, and combining either flag with a raw permutation is refused.