Skip to content
Menu

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:

  • --inertia implies --laravel: Inertia here means Laravel.
  • --raw and --laravel are mutually exclusive: pick one base.
  • --vue is 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 --check never reports it, however you edit it.
  • sourdough feed never 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.