aw-spec-cli 0.1.26 → 0.1.27

package/assets/.appweaver/scripts/python/aw-stack.py

@@ -21,23 +21,26 @@ stays optional in the schema for a future caller that proposes a lane without a
 person in the loop; a reader that branches on it keeps working either way.
 
 A person editing stacks.json in a text editor is the other way a lane arrives,
-and it is supported: the kit ships the file holding `{"lanes": []}` for exactly
-that. It is the one path that does not pass the writer's checks, which is why
+and it is supported: the kit ships the file with an empty `lanes` array for exactly
+that, plus a `_lane_format` key holding one sample lane of each kind with every field
+filled in. Nothing reads `_lane_format`; it is there to copy from. It is the one path that does not pass the writer's checks, which is why
 `verify` re-checks the roots-disjoint invariant rather than trusting that
 `declare` already did. `resolve` can never write, which is why these are two
 subcommands and not one with a mode flag.
 
-A lane's `root` IS its source path — the subtree the lane owns and the only place
+A lane's `root` IS the lane root folder — the subtree the lane owns and the only place
 its implement phase may write. The two words name one field, and `--source-path`
 is accepted wherever `--root` is.
 
-WHERE THE COMMANDS RUN is a separate question, because for most stacks the answer
-is a different directory: `dotnet build` wants the solution file at the top while
-the lane owns `src/`, and `npm run build` wants the package.json at the top while
-the lane owns `web/`. `run_from` carries that answer — "repo" (the default, and
-the shape of every lane written before the key existed) or "root". A stack whose
-manifest lives INSIDE its subtree needs "root" and cannot work without it: a Maven
-wrapper at backend/<app>/mvnw is unreachable from the repository root.
+WHERE THE COMMANDS RUN is a separate question, because the answer can be a different
+directory: a classic .NET repository keeps its solution file at the top while the
+lane owns `src/`. `run_from` carries that answer — "repo" (the default, and the shape
+of every lane written before the key existed) or "root". A stack whose build file
+lives INSIDE its subtree needs "root" and cannot work without it: a Maven wrapper at
+backend/<app>/mvnw is unreachable from the repository root. A NEW project is one
+self-contained folder per lane — every profile defaults to `backend/` or `frontend/`
+with `run_from: "root"` — while `declare` answers for code that already exists from
+where its build file actually sits (see `build_files_at`).
 
 WHERE THE PATH IS CHECKED AGAINST THE DISK. `declare` records a path; it does not
 require the path to exist, because in a greenfield project it does not exist yet —
@@ -270,6 +273,11 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
         files_for_prof = scoped if prof.get("kind") != "frontend" else files
         evidence, matched, anchored_hits = [], 0, 0
         prof_root = norm_root(prof.get("root") or "")
+        # The `detect` patterns are written against the layout an EXISTING repository of
+        # this stack usually has (`src/**/*.csproj`, `web/next.config.*`), which is the
+        # profile's `conventional_root` — not its `root`, the folder a NEW project gets.
+        conv_root = norm_root(prof.get("conventional_root") or "")
+        bases = [b for b in (prof_root, conv_root) if b and b != REPO_ROOT]
         for pat in patterns:
             rx = _glob_rx(pat)
             rx_any = _glob_rx("**/" + pat)
@@ -278,8 +286,8 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
                 anchored_hits += 1
             else:
                 hits = [f for f in files_for_prof if rx_any.match(f)]
-            if not hits and prof_root and pat.startswith(prof_root) \
-                    and os.path.basename(pat) not in ambiguous:
+            base = next((b for b in bases if pat.startswith(b)), "")
+            if not hits and base and os.path.basename(pat) not in ambiguous:
                 # RELOCATED, with the profile's own root segment substituted rather than
                 # prefixed. Prefixing alone only ever finds the profile's own folder name
                 # deeper in the tree — `apps/portal/web/angular.json` — so a UI in
@@ -288,7 +296,7 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
                 # Restricted to names only one kind claims, so substitution widens where a
                 # stack may live without widening what counts as evidence for it.
                 hits = [f for f in files_for_prof
-                        if _glob_rx("**/" + pat[len(prof_root):]).match(f)]
+                        if _glob_rx("**/" + pat[len(base):]).match(f)]
             if not hits:
                 continue
             matched += 1
@@ -298,20 +306,21 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
         dirs = sorted({os.path.dirname(f) for f in evidence}, key=lambda d: (d.count("/"), len(d)))
         # WHERE THE SOURCE LIVES, which is not always where the evidence sits. A manifest
         # at the repo root — `App.sln`, a workspace `package.json` — marks the repository,
-        # not the subtree: the code it describes is under the profile's own root. So repo-
-        # root evidence defers to that root when the directory is really there, and only
+        # not the subtree: the code it describes is under one of the profile's roots. So
+        # repo-root evidence defers to that root when the directory is really there, and only
         # falls back to the repo root itself when it is not, which is the case for the
         # single-package layouts (`create-next-app`, a UI checked out at the top level)
-        # whose files genuinely are at the top.
+        # whose files genuinely are at the top. The conventional root is tried first:
+        # repo-root evidence (`App.sln`) is the classic layout, whose code sits under
+        # `src/` — not under the `backend/` a new project would get.
         prof_default = norm_root(prof.get("root") or "")
         if not dirs:
             root = prof_default
         elif dirs[0]:
             root = norm_root(dirs[0])
-        elif prof_default and os.path.isdir(os.path.join(repo, prof_default)):
-            root = prof_default
         else:
-            root = REPO_ROOT
+            root = next((r for r in (conv_root, prof_default)
+                         if r and os.path.isdir(os.path.join(repo, r))), REPO_ROOT)
         out.append({
             "id": prof["id"],
             "kind": prof.get("kind", ""),
@@ -404,7 +413,7 @@ def cmd_list(args):
     repository looks like. Two subcommands would walk the file tree twice and add
     two steps to a workflow whose whole value is being short. One call returns the
     options, the profile the files point at, and the directory the evidence sits
-    in — which is the source path the operator is about to be asked to confirm.
+    in — which is the lane root folder the operator is about to be asked to confirm.
 
     HOW A DETECTED STACK IS PROPOSED, and why it is not preselected. Detection
     moves its match to the FRONT of the option list; it never fills `preselect`.
@@ -448,10 +457,10 @@ def cmd_list(args):
     preselect = resolve_preselect(args.preselect, profiles, args.include_none, args.kind)
     preselect_source = "argument" if preselect else ""
 
-    # Candidate SOURCE PATHS for the follow-up question, best first. Labelled with why
+    # Candidate LANE ROOT FOLDERS for the follow-up question, best first. Labelled with why
     # each is offered, because the operator picking from this list is choosing the
     # subtree a generator will be allowed to write into. Free text is always
-    # accepted — a repo that matches no profile still has a source path.
+    # accepted — a repo that matches no profile still has a lane root folder.
     #
     # WITH --profile the stack is already chosen, and the list answers for it alone:
     # where THAT stack's evidence sits, then its own default, then where another
@@ -460,7 +469,7 @@ def cmd_list(args):
     # operator did not choose.
     #
     # WITHOUT --profile the list is built before any choice, and a default root is
-    # usually shared (six frontend profiles default to web/), so its label names every
+    # usually shared (every frontend profile defaults to frontend/), so its label names every
     # profile that proposes it rather than whichever one sorts first.
     chosen = None
     if args.profile:
@@ -541,16 +550,16 @@ def strip_root_label(value):
     return (value or "").split(ROOT_LABEL_SEP, 1)[0].strip()
 
 
-# The repository root as a source path. A single-module project — a Maven, Cargo, Go
+# The repository root as a lane root folder. A single-module project — a Maven, Cargo, Go
 # or Node repo whose manifest sits at the top — has no subdirectory to name, and the
-# empty string cannot carry it: `verify` reads an empty root as "no source path
+# empty string cannot carry it: `verify` reads an empty root as "no lane root folder
 # declared". "./" is the one spelling that survives being normalised twice, which is
 # what makes it usable as a STORED value rather than only as typed input.
 REPO_ROOT = "./"
 
 
 def norm_root(root):
-    """Canonicalise a source path, IDEMPOTENTLY.
+    """Canonicalise a lane root folder, IDEMPOTENTLY.
 
     Idempotence is a correctness requirement, not tidiness: `declare` normalises what it
     writes and `verify` normalises what it reads, so a value that changes on the second
@@ -575,7 +584,7 @@ def norm_root(root):
 
 
 def root_on_disk(repo, root):
-    """Does the lane's source path exist as a directory?
+    """Does the lane root folder exist as a directory?
 
     Reported everywhere a root is reported and enforced only by `verify`. A false
     here is an ordinary state before any code is written and a hard error once a
@@ -588,14 +597,15 @@ def root_on_disk(repo, root):
 def lane_workdir(repo, lane):
     """The directory a lane's commands run in.
 
-    `run_from: "root"` runs them in the lane's own source path; anything else — including
+    `run_from: "root"` runs them in the lane root folder; anything else — including
     the key being ABSENT, which is the shape of every lane written before this key
-    existed — runs them at the repository root. That default is not laziness: a .NET
-    solution file, a go.mod or a package.json at the top is what `dotnet build`,
-    `go build ./...` and `npm run build` need to find, and those profiles declare a `root`
-    that is their SOURCE directory rather than their build directory. The two coincide for
-    a stack whose manifest lives inside the subtree — a Maven wrapper at
-    backend/orderservice/mvnw cannot be reached from the repo root at all.
+    existed — runs them at the repository root. That default is not laziness: in a
+    classic repository a .NET solution file, a go.mod or a package.json at the top is what
+    `dotnet build`, `go build ./...` and `npm run build` need to find, while the lane is
+    the SOURCE directory under it. The two coincide for a stack whose build file lives
+    inside the subtree — a Maven wrapper at backend/orderservice/mvnw cannot be reached
+    from the repo root at all — and for every new project, which is one self-contained
+    folder per lane.
 
     Falls back to the repo root when the declared root is not on disk, so the phase
     reports the command's own failure instead of a chdir error.
@@ -608,27 +618,108 @@ def lane_workdir(repo, lane):
     return repo
 
 
-def lane_command(lane, phase):
-    """The command for one phase, with `{{root}}` standing for the lane's root.
+def build_files_at(repo, root, build_files):
+    """Where a stack's build file already sits for a lane at `root`: "root" when one is
+    directly inside the lane root folder, "repo" when one is only at the repository root,
+    "" when neither — nothing is on disk yet, so the caller falls back to the profile.
+
+    This is what lets one profile serve both kinds of repository. A new project is one
+    self-contained folder per lane (`backend/api.sln`), and its commands run inside it; a
+    classic .NET repository keeps `api.sln` at the top with the code under `src/`, and its
+    commands have to run at the top. Reading the answer off the disk at declare time gives
+    each its own, where a fixed profile default would break one of them.
+    """
+    if not build_files:
+        return ""
+    r = norm_root(root)
+    lane_dir = repo if (not r or r == REPO_ROOT) else os.path.join(repo, r.rstrip("/"))
+
+    def has(d):
+        return any(os.path.isfile(p) for pat in build_files
+                   for p in glob.glob(os.path.join(d, pat)))
+
+    if os.path.isdir(lane_dir) and has(lane_dir):
+        return "root"
+    if has(repo):
+        return "repo"
+    return ""
+
+
+# Folders a runnable project is never looked for in: build output, dependencies, tests.
+HOST_SKIP_DIRS = {"bin", "obj", "node_modules", ".git", ".vs", "packages", "tests", "test"}
 
-    A profile command sometimes has to NAME the source path — `dotnet run --project
-    src/`, `python -m compileall app`. Written literally, that is the profile's
-    default root frozen into the command, and it stays frozen when the lane declares
-    a different one: a service at `Services/Api/` runs the project at `src/`, or
-    fails looking for it. The placeholder lets the profile say "the root this lane
-    declares" and be right on every layout.
+
+def lane_host(repo, lane):
+    """The lane's runnable project folder, which `{{host}}` in a command stands for.
+
+    A lane root folder often holds several projects and only one of them is the thing to
+    run — a .NET solution's Aspire AppHost, or its API when there is no AppHost. The
+    profile's `host_patterns` say where that project sits, best first, as paths relative
+    to the lane root folder (`**/` for any depth, case ignored). The first pattern that
+    matches exactly ONE file names the project; its folder is returned as seen from where
+    the lane's commands run. None when the profile has no patterns, the lane root folder is
+    not on disk, or no pattern has a single match — the caller then uses the lane root folder.
+    """
+    if not repo:
+        return None
+    patterns = [p.lower() for p in profile_of(repo, lane).get("host_patterns") or []]
+    r = norm_root(lane.get("root"))
+    lane_dir = repo if (not r or r == REPO_ROOT) else os.path.join(repo, r.rstrip("/"))
+    if not patterns or not os.path.isdir(lane_dir):
+        return None
+    leaves = {p.rsplit("/", 1)[-1] for p in patterns}
+    files = []
+    for dirpath, dirnames, filenames in os.walk(lane_dir):
+        dirnames[:] = [d for d in dirnames if d.lower() not in HOST_SKIP_DIRS]
+        for name in filenames:
+            if any(fnmatch.fnmatchcase(name.lower(), leaf) for leaf in leaves):
+                rel = os.path.relpath(os.path.join(dirpath, name), lane_dir).replace("\\", "/")
+                files.append(rel)
+    for pat in patterns:
+        bare = pat[3:] if pat.startswith("**/") else pat
+        hits = [f for f in files
+                if fnmatch.fnmatchcase(f.lower(), pat) or fnmatch.fnmatchcase(f.lower(), bare)]
+        if len(hits) == 1:
+            project_dir = os.path.join(lane_dir, os.path.dirname(hits[0]))
+            rel = os.path.relpath(project_dir, lane_workdir(repo, lane)).replace("\\", "/")
+            return rel
+    return None
+
+
+def lane_command(lane, phase, repo=None):
+    """The command for one phase, with `{{root}}` standing for the lane root folder and
+    `{{host}}` for the lane's runnable project inside it (see lane_host).
+
+    A profile command sometimes has to NAME the lane root folder — `python -m
+    compileall app`. Written literally, that is the profile's default root frozen into
+    the command, and it stays frozen when the lane declares a different one: a service
+    at `Services/Api/` compiles the code at `app/`, or fails looking for it. The
+    placeholder lets the profile say "the root this lane declares" and be right on
+    every layout.
 
     Expanded at RUN time, not at declare time, so editing `root` in stacks.json by
     hand keeps the command consistent with it. A command with no placeholder is
     returned untouched, so every literal command already on disk is unaffected.
+
+    The root is named as seen from where the command RUNS: a `run_from: "root"` lane
+    runs inside its root, so there `{{root}}` is `.` — the repository-relative path
+    would point at `backend/backend`.
+
+    `{{host}}` exists because the lane root folder is not always runnable: `dotnet run
+    --project <folder>` needs exactly one project in that folder, and a solution has
+    several. It is looked up when the command is read, so a project scaffolded after the
+    lane was declared is found; with no single match it falls back to `{{root}}`.
     """
     cmd = (lane.get(phase) or "").strip()
+    if "{{host}}" in cmd:
+        cmd = cmd.replace("{{host}}", lane_host(repo, lane) or "{{root}}")
     if "{{root}}" not in cmd:
         return cmd
     r = norm_root(lane.get("root"))
     # `./` is the repo root: a bare `./` reads as noise in a command line, and the
     # only sensible substitution for "the root, which is here" is the cwd itself.
-    sub = "." if (r == REPO_ROOT or not r) else r.rstrip("/")
+    runs_inside = (lane.get("run_from") or "repo") == "root"
+    sub = "." if (r == REPO_ROOT or not r or runs_inside) else r.rstrip("/")
     return cmd.replace("{{root}}", sub)
 
 
@@ -654,7 +745,7 @@ def lane_test_path(repo, lane, prof=None):
 
     Most backend stacks keep tests BESIDE the source rather than in it: .NET's `tests/`
     next to `src/`, Maven's `src/test/java/` next to `src/main/java/`, pytest's `tests/`
-    next to `app/`. A lane that owned only its source path could not hold its own tests.
+    next to `app/`. A lane that owned only its lane root folder could not hold its own tests.
 
     Answered at READ time, like `ecosystem`, so a lane declared before this existed has
     one without being re-declared:
@@ -662,8 +753,11 @@ def lane_test_path(repo, lane, prof=None):
         does not describe;
       - else the profile's `test_root`, which pairs with the profile's default `root`. A
         lane at that root takes it as is; a lane whose root ends with it takes it under
-        the same prefix (`backend/src/` ⇒ `backend/tests/`);
-      - else the tests live inside the source path. That is right for every frontend
+        the same prefix (`apps/backend/` ⇒ `apps/backend/tests/`);
+      - else the profile's `conventional_test_root`, which pairs the same way with its
+        `conventional_root` — the classic layout an existing repository has (`src/` ⇒
+        `tests/`), so a lane declared at it keeps the test path it always had;
+      - else the tests live inside the lane root folder. That is right for every frontend
         profile, for Go's colocated `_test.go` files, and for a Maven lane rooted at the
         directory holding its pom.xml.
     """
@@ -676,24 +770,25 @@ def lane_test_path(repo, lane, prof=None):
     if own:
         return own
     prof = profile_of(repo, lane) if prof is None else prof
-    default_root = norm_root(prof.get("root"))
-    default_tests = norm_root(prof.get("test_root"))
-    if not default_root or not default_tests or REPO_ROOT in (default_root, default_tests):
-        return root
-    if root == default_root:
-        return default_tests
-    if root.endswith("/" + default_root):
-        return root[: -len(default_root)] + default_tests
+    for key_root, key_tests in (("root", "test_root"),
+                                ("conventional_root", "conventional_test_root")):
+        base, tests = norm_root(prof.get(key_root)), norm_root(prof.get(key_tests))
+        if not base or not tests or REPO_ROOT in (base, tests):
+            continue
+        if root == base:
+            return tests
+        if root.endswith("/" + base):
+            return root[: -len(base)] + tests
     return root
 
 
 def lane_owned_paths(repo, lane, prof=None):
-    """Every subtree a lane owns, labelled: its source path, and its test path when that
+    """Every subtree a lane owns, labelled: its lane root folder, and its test path when that
     is a different directory. Ownership checks compare these, so a test path can never
     land inside another lane's subtree."""
     root = norm_root(lane.get("root"))
     tests = lane_test_path(repo, lane, prof)
-    owned = [("source path", root)] if root else []
+    owned = [("lane root folder", root)] if root else []
     if tests and tests != root:
         owned.append(("test path", tests))
     return owned
@@ -768,7 +863,7 @@ def cmd_declare(args):
     lane_id = args.id or DEFAULT_LANE_ID.get(kind, kind)
     root = norm_root(args.root or (prof or {}).get("root") or "")
     if not root:
-        fail("lane-declare: lane '%s' has no source path. A lane without a root owns "
+        fail("lane-declare: lane '%s' has no lane root folder. A lane without a root owns "
              "nothing, so nothing can be built, run or written into it. Pass "
              "--source-path <dir> (the profile declares no default)." % lane_id)
 
@@ -777,7 +872,7 @@ def cmd_declare(args):
     # is about to read the code out of it.
     exists = root_on_disk(repo, root)
     if args.require_existing_root and not exists:
-        fail("lane-declare: source path '%s' for lane '%s' does not exist under %s. "
+        fail("lane-declare: lane root folder '%s' for lane '%s' does not exist under %s. "
              "Point the lane at the directory that actually holds this lane's source, "
              "or re-run /appweaver select-stack to correct it."
              % (root, lane_id, repo))
@@ -802,8 +897,12 @@ def cmd_declare(args):
         lane["migrate"] = migrate
     # WHERE this lane's commands run — see lane_workdir. Recorded only when it is not
     # the default, so a lane reads the same as it always did unless its stack needs the
-    # other answer.
-    run_from = getattr(args, "run_from", "") or (prof or {}).get("run_from", "")
+    # other answer. An explicit --run-from wins; else the stack's build file decides when
+    # it is on disk (build_files_at); else — a greenfield lane, nothing written yet — the
+    # profile's own answer, which for a new project is inside the lane.
+    run_from = (getattr(args, "run_from", "")
+                or build_files_at(repo, root, (prof or {}).get("build_files") or [])
+                or (prof or {}).get("run_from", ""))
     if run_from == "root":
         lane["run_from"] = "root"
     # What the code was found to be, when no shipped profile names it.
@@ -824,7 +923,7 @@ def cmd_declare(args):
             for theirs_label, theirs in lane_owned_paths(repo, other):
                 if roots_overlap(mine, theirs):
                     fail("lane-declare: %s '%s' for lane '%s' overlaps lane '%s''s %s '%s'. "
-                         "A lane owns its source path and its test path, and no two lanes "
+                         "A lane owns its lane root folder and its test path, and no two lanes "
                          "may share a subtree."
                          % (mine_label, mine, lane_id, other.get("id"), theirs_label, theirs))
 
@@ -893,7 +992,7 @@ def profile_of(repo, lane):
 def kind_block(repo, lanes, kind):
     """Every field a caller needs about ONE kind, flattened and prefixed.
 
-    A workflow that wants the service source path binds `$.backend_source_path`
+    A workflow that wants the service lane root folder binds `$.backend_source_path`
     and is done — no `--kind` argument, no second call, and no branch on which
     lane came back. Both kinds are always present in the payload, so the two-lane
     steps (a gate that needs backend, a report that names both) resolve one script
@@ -927,14 +1026,21 @@ def kind_block(repo, lanes, kind):
         kind + "_root": root,
         kind + "_source_path": root,
         kind + "_root_exists": root_on_disk(repo, root),
-        # Where the lane's paired tests go. Equal to the source path when the stack keeps
+        # Where the lane's paired tests go. Equal to the lane root folder when the stack keeps
         # its tests inside it; see lane_test_path.
         kind + "_test_path": test_path,
         kind + "_test_path_exists": root_on_disk(repo, test_path),
-        kind + "_build": lane_command(lane, "build"),
-        kind + "_test": lane_command(lane, "test"),
-        kind + "_run": lane_command(lane, "run"),
-        kind + "_migrate": lane_command(lane, "migrate") or prof.get("migrate", ""),
+        # Where the lane's commands run, as DECLARED — `./` for the repository root.
+        # Read from the declaration rather than from lane_workdir, which falls back to the
+        # repo root while the lane root folder is not on disk yet; a phase that creates the
+        # project has to be told where its build will run before that path exists.
+        kind + "_workdir": (norm_root(root) or REPO_ROOT)
+                           if lane and (lane.get("run_from") or "repo") == "root"
+                           else (REPO_ROOT if lane else ""),
+        kind + "_build": lane_command(lane, "build", repo),
+        kind + "_test": lane_command(lane, "test", repo),
+        kind + "_run": lane_command(lane, "run", repo),
+        kind + "_migrate": lane_command(lane, "migrate", repo) or prof.get("migrate", ""),
     }
 
 
@@ -956,7 +1062,7 @@ def lane_options(repo, lanes):
         title = (prof.get("title", "") or lane.get("stack", "")
                  or lane.get("profile", "") or "no stack declared")
         root = norm_root(lane.get("root"))
-        where = "the repo root" if root == REPO_ROOT else (root or "no source path")
+        where = "the repo root" if root == REPO_ROOT else (root or "no lane root folder")
         label = "%s %s at %s" % (lane.get("kind", "lane"), title, where)
         tests = lane_test_path(repo, lane, prof)
         if tests and tests != root:
@@ -1029,7 +1135,7 @@ def cmd_resolve(args):
     lanes = data.get("lanes") or []
     match = {}
     # The id may arrive as a whole option line — `user_select` hands back the string it
-    # displayed, label and all — so strip it the way a source path is stripped.
+    # displayed, label and all — so strip it the way a lane root folder is stripped.
     wanted = strip_root_label(args.id) if args.id else ""
     if wanted:
         match = next((l for l in lanes if l.get("id") == wanted), {})
@@ -1052,10 +1158,10 @@ def cmd_resolve(args):
         "source_path": match.get("root", ""),
         "test_path": lane_test_path(args.repo, match),
         "root_exists": root_on_disk(args.repo, match.get("root", "")),
-        "build": lane_command(match, "build"),
-        "test": lane_command(match, "test"),
-        "run": lane_command(match, "run"),
-        "migrate": lane_command(match, "migrate") or profile_of(args.repo, match).get("migrate", ""),
+        "build": lane_command(match, "build", args.repo),
+        "test": lane_command(match, "test", args.repo),
+        "run": lane_command(match, "run", args.repo),
+        "migrate": lane_command(match, "migrate", args.repo) or profile_of(args.repo, match).get("migrate", ""),
         "language": profile_of(args.repo, match).get("language", ""),
         "ecosystem": profile_of(args.repo, match).get("ecosystem", ""),
         "prototype": data.get("prototype", {}),
@@ -1077,7 +1183,7 @@ def cmd_resolve(args):
 #   only for the kinds a caller asks for with --require, because "no frontend
 #   lane" is the correct and common state and must never fail a backend build.
 #
-#   BROKEN — a lane IS declared and its source path is empty or is not a directory.
+#   BROKEN — a lane IS declared and its lane root folder is empty or is not a directory.
 #   Checked for EVERY declared lane whether or not the caller asked about it. A
 #   stack named against a path that is not there is a mistake in every phase, and
 #   letting it through means discovering it as an empty build or a generator
@@ -1106,7 +1212,7 @@ def cmd_verify(args):
     issues = []
 
     # An empty file and an absent one are the SAME state. The kit ships
-    # stacks.json holding `{"lanes": []}` so a project can fill it in by hand, so
+    # stacks.json with an empty `lanes` array so a project can fill it in by hand, so
     # the file being there says nothing about whether a lane was declared — only
     # its contents do. Both cases report one issue naming which of the two it is.
     if not lanes:
@@ -1130,13 +1236,13 @@ def cmd_verify(args):
             root = lane.get("root", "")
             if not root:
                 issues.append(
-                    "lane '%s' (%s, stack %s) declares no source path. A lane owns a "
+                    "lane '%s' (%s, stack %s) declares no lane root folder. A lane owns a "
                     "subtree; without one nothing can be built, run or written into it. "
-                    "Re-run `/appweaver select-stack` and give it a source path."
+                    "Re-run `/appweaver select-stack` and give it a lane root folder."
                     % (lane_id, kind, lane.get("profile", "?")))
             elif not args.allow_missing_root and not root_on_disk(repo, root):
                 issues.append(
-                    "lane '%s' (%s, stack %s) declares source path '%s', which is not a "
+                    "lane '%s' (%s, stack %s) declares lane root folder '%s', which is not a "
                     "directory in this repository. Re-run `/appweaver select-stack` and "
                     "point the lane at the directory that holds its source."
                     % (lane_id, kind, lane.get("profile", "?"), root))
@@ -1144,7 +1250,7 @@ def cmd_verify(args):
         # hand-edited file — a supported way to fill this in, and the one path that
         # does not pass the writer. The invariant is worth a second check anywhere:
         # two lanes sharing a subtree means two generators can write one file. A lane
-        # owns its test path as well as its source path, so both are compared.
+        # owns its test path as well as its lane root folder, so both are compared.
         for i, first in enumerate(lanes):
             for second in lanes[i + 1:]:
                 clash = next(((fl, fp, sl, sp)
@@ -1154,7 +1260,7 @@ def cmd_verify(args):
                 if clash:
                     issues.append(
                         "lanes '%s' and '%s' claim overlapping subtrees: %s '%s' and %s '%s'. "
-                        "A lane owns its source path and its test path, and they must be "
+                        "A lane owns its lane root folder and its test path, and they must be "
                         "disjoint from every other lane's, or two generators can write the "
                         "same file. Give each lane paths outside the other's."
                         % (first.get("id", "?"), second.get("id", "?"),
@@ -1191,7 +1297,7 @@ def cmd_verify(args):
 # ────────────────────────────── run-phase ──────────────────────────────────
 # Execute a phase's project-supplied command for EVERY declared lane.
 #
-# This is the payoff of declaring a source path. Without a declaration, `build`
+# This is the payoff of declaring a lane root folder. Without a declaration, `build`
 # sniffs: it looks for a .sln, then for a package.json, and takes the first hit.
 # On a single-lane repo that is right. On a two-lane repo it is wrong in the worst
 # way available — it builds the backend, reports green, and never mentions that the
@@ -1256,21 +1362,21 @@ def cmd_run_phase(args):
     testlog = _testlog()
     ok, ran = True, False
     for lane in lanes:
-        cmd = lane_command(lane, args.phase)
+        cmd = lane_command(lane, args.phase, repo)
         lane_id, root = lane.get("id", "?"), lane.get("root", "")
         if not cmd:
             results.append({"lane": lane_id, "root": root, "cmd": "",
                             "ran": False, "ok": True, "skipped": "no %s command" % args.phase})
             continue
-        # The source path has to be there before a command is run against it.
+        # The lane root folder has to be there before a command is run against it.
         # Reported per lane rather than raised, so a two-lane run still reports
         # what the other lane did.
         if not root_on_disk(repo, root):
             ok = False
             results.append({"lane": lane_id, "root": root, "cmd": cmd, "ran": False, "ok": False,
-                            "error": "source path '%s' is not a directory" % root})
-            tails.append("[%s] source path '%s' is not a directory" % (lane_id, root))
-            excerpts.append("[%s] source path '%s' is not a directory — nothing ran"
+                            "error": "lane root folder '%s' is not a directory" % root})
+            tails.append("[%s] lane root folder '%s' is not a directory" % (lane_id, root))
+            excerpts.append("[%s] lane root folder '%s' is not a directory — nothing ran"
                             % (lane_id, root))
             failing.append(lane_id)
             continue
@@ -1456,7 +1562,7 @@ def main():
     p.add_argument("--kind", choices=["backend", "frontend"])
     p.add_argument("--id", help="lane id (default: service for backend, web for frontend)")
     p.add_argument("--root", "--source-path", dest="root",
-                   help="the lane's SOURCE PATH — the subtree it owns, overriding the "
+                   help="the LANE ROOT FOLDER — the subtree it owns, overriding the "
                         "profile's default root. The two spellings are one field")
     p.add_argument("--run-from", dest="run_from", choices=["repo", "root"],
                    help="where this lane's build/test/run commands execute: 'repo' (default) "
@@ -1466,7 +1572,7 @@ def main():
                         "subtree (a Maven wrapper at backend/<app>/mvnw). Defaults to the "
                         "profile's own setting")
     p.add_argument("--require-existing-root", dest="require_existing_root", action="store_true",
-                   help="refuse a source path that is not a directory. For a caller about "
+                   help="refuse a lane root folder that is not a directory. For a caller about "
                         "to READ the subtree (onboard); greenfield declares a path that "
                         "implement has not created yet, and leaves this off")
     p.add_argument("--stack", default="",
@@ -1498,7 +1604,7 @@ def main():
                    help="a lane kind this phase cannot run without; repeatable. Omit to "
                         "check only that whatever IS declared is sound")
     p.add_argument("--allow-missing-root", dest="allow_missing_root", action="store_true",
-                   help="do not require the source paths to exist on disk yet — the "
+                   help="do not require the lane root folders to exist on disk yet — the "
                         "greenfield state, where select-stack declares a path implement "
                         "will create")
     p.add_argument("--command", default="",

package/assets/.appweaver/stack-profiles/angular.json

@@ -4,8 +4,9 @@
   "title": "Angular",
   "language": "TypeScript",
   "ecosystem": "node",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "npm run build",
   "test": "npm test",
   "run": "npm start",

package/assets/.appweaver/stack-profiles/blazor-wasm.json

@@ -4,8 +4,9 @@
   "title": "Blazor WebAssembly",
   "language": "C#",
   "ecosystem": "dotnet",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "dotnet build",
   "test": "dotnet test",
   "run": "dotnet run",

package/assets/.appweaver/stack-profiles/dotnet-webapi.json

@@ -4,11 +4,24 @@
   "title": "ASP.NET Core Web API",
   "language": "C#",
   "ecosystem": "dotnet",
-  "root": "src/",
-  "test_root": "tests/",
+  "root": "backend/",
+  "test_root": "backend/tests/",
+  "run_from": "root",
+  "conventional_root": "src/",
+  "conventional_test_root": "tests/",
+  "build_files": [
+    "*.sln",
+    "*.slnx",
+    "*.csproj"
+  ],
   "build": "dotnet build",
   "test": "dotnet test",
-  "run": "dotnet run --project {{root}}",
+  "run": "dotnet run --project {{host}}",
+  "host_patterns": [
+    "**/*.AppHost.csproj",
+    "**/*.Api.csproj",
+    "**/*.Service.csproj"
+  ],
   "detect": [
     "*.sln",
     "src/**/*.csproj"