aw-spec-cli 0.1.27 → 0.1.28

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

@@ -2,24 +2,45 @@
 """
 aw-stack — the lane model's deterministic core.
 
-Backs seven aw-spec-actions subcommands, called identically by the bash and the
+Backs ten aw-spec-actions subcommands, called identically by the bash and the
 powershell twin so the two stay in parity by construction rather than by review:
 
     list      enumerate .appweaver/stack-profiles/ — the candidate list
     detect    match the repo's own files against those profiles — the BROWNFIELD
               candidate list, since an existing repo already answered the question
-    declare   upsert a lane into .appweaver/stacks.json — THE SOLE WRITER
+    declare   upsert a lane into .appweaver/stacks.json — the writer of WHOLE lanes
+    set       change named keys on a lane already declared — the writer of SETTINGS
     resolve   read .appweaver/stacks.json — for every downstream reader; with
               --feature-dir, narrowed to the lanes that feature has a surface in
     verify    is the declaration USABLE for the phase about to run — the gate
     run-phase run a phase's command for EVERY declared lane, not just the first
     probe     is there evidence of a lane of this kind — read-only, never fatal
-
-`declare` is the sole writer and has exactly one caller — `select-stack`, where a
-person picks — so the rule is a grep rather than a convention. The `origin` key
-stays optional in the schema for a future caller that proposes a lane without a
+    contract-export  start the service lane, fetch its API document, stop it
+    contract-check   the operation ids a frontend plan cites vs that document
+
+This file is the only code that writes stacks.json, through two subcommands with
+different jobs. `declare` creates or replaces a whole lane and has exactly one caller —
+`select-stack`, where a person picks. `set` changes only the keys in CONTRACT_KEYS on a lane that is
+already there, and never its root, profile or phase commands: `foundation` records the
+API-export settings the pack it unpacked carries, and `implement` records the client
+command a developer supplies. Re-declaring a lane to change one key would reset every
+other command to the profile's default, which is why the two are separate. The `origin`
+key 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.
 
+THE API CONTRACT BETWEEN THE LANES. The service lane publishes an API document and the
+frontend lane generates its client from it. Three lane keys carry that, each read from
+the lane first and from its stack profile when the lane does not set it, so a lane
+declared before the keys existed answers them too:
+
+    contract_run  (backend)  the command that starts the service for the export
+    contract      (backend)  the URL the running service serves its document at
+    client        (frontend) the command that generates the client; `{{contract}}` in
+                             it is the exported document, as seen from where it runs
+
+The document is written to CONTRACT_DOC under the service lane root folder, so it is
+committed with the service that publishes it.
+
 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 with an empty `lanes` array for exactly
 that, plus a `_lane_format` key holding one sample lane of each kind with every field
@@ -64,6 +85,14 @@ import sys
 STACKS_REL = ".appweaver/stacks.json"
 PROFILES_REL = ".appweaver/stack-profiles"
 
+# Where the exported API document lands, relative to the service lane root folder.
+CONTRACT_DOC = "contracts/openapi.json"
+
+# The API-contract keys: the only ones `set` may change, and the ones read from the
+# stack profile when the lane does not set them (lane_value). Everything else on a lane
+# is the declaration itself and changes only through `declare`.
+CONTRACT_KEYS = ("contract_run", "contract", "client")
+
 # A lane id names the ROLE in the project; the profile names the technology.
 # Keeping them separate is what lets a project re-stack a lane without renaming
 # the paths, rules and constitution half that hang off the lane id.
@@ -709,8 +738,20 @@ def lane_command(lane, phase, repo=None):
     --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}}`.
+
+    `{{contract}}` is the service lane's exported API document (contract_doc), named as
+    seen from where THIS lane's command runs — what a frontend lane's `client` command
+    generates from. With no service lane it is left as written.
     """
-    cmd = (lane.get(phase) or "").strip()
+    if phase in CONTRACT_KEYS:
+        cmd = lane_value(repo, lane, phase)
+    else:
+        cmd = (lane.get(phase) or "").strip()
+    if "{{contract}}" in cmd and repo:
+        doc = contract_doc(repo)
+        if doc:
+            rel = os.path.relpath(os.path.join(repo, doc), lane_workdir(repo, lane))
+            cmd = cmd.replace("{{contract}}", rel.replace("\\", "/"))
     if "{{host}}" in cmd:
         cmd = cmd.replace("{{host}}", lane_host(repo, lane) or "{{root}}")
     if "{{root}}" not in cmd:
@@ -723,6 +764,31 @@ def lane_command(lane, phase, repo=None):
     return cmd.replace("{{root}}", sub)
 
 
+def lane_value(repo, lane, key):
+    """A lane's value for one key, or its stack profile's when the lane sets none.
+
+    Only CONTRACT_KEYS fall back. The phase commands are written onto the lane when it
+    is declared; these are read from the profile at run time, so a lane declared before
+    they existed answers them, and a value set on the lane — by a pack or a developer —
+    overrides the profile's.
+    """
+    value = (lane.get(key) or "").strip() if lane else ""
+    if not value and lane and repo and key in CONTRACT_KEYS:
+        value = (profile_of(repo, lane).get(key) or "").strip()
+    return value
+
+
+def contract_doc(repo, lanes=None):
+    """The service lane's exported API document, repo-relative; "" with no service lane."""
+    if lanes is None:
+        lanes = (read_stacks(repo) or {}).get("lanes") or []
+    lane = next((l for l in lanes if l.get("kind") == "backend"), {})
+    r = norm_root(lane.get("root"))
+    if not r:
+        return ""
+    return CONTRACT_DOC if r == REPO_ROOT else r + CONTRACT_DOC
+
+
 def roots_overlap(a, b):
     """Roots own their subtree, so containment either way is an overlap.
 
@@ -979,6 +1045,53 @@ def write_stacks(repo, data):
         fh.write("\n")
 
 
+def cmd_set(args):
+    """Change CONTRACT_KEYS on a lane that is already declared, leaving the rest of it
+    as it is. `--set KEY=` with an empty value changes nothing, so a caller can pass every
+    key it might have; `--unset KEY` removes one, so the lane reads its profile's again."""
+    repo = args.repo
+    data = read_stacks(repo) or {"lanes": []}
+    lanes = data.get("lanes") or []
+    wanted = strip_root_label(args.id) if args.id else ""
+    lane = next((l for l in lanes if (l.get("id") == wanted if wanted
+                                      else l.get("kind") == args.kind)), None)
+    if lane is None:
+        fail("lane-set: no lane %s is declared in %s"
+             % ("'%s'" % wanted if wanted else "of kind '%s'" % (args.kind or "?"), STACKS_REL))
+
+    set_, removed = {}, []
+    for item in args.set or []:
+        key, sep, value = item.partition("=")
+        key = key.strip()
+        if not sep or key not in CONTRACT_KEYS:
+            fail("lane-set: '%s' is not KEY=VALUE with KEY one of %s"
+                 % (item, ", ".join(CONTRACT_KEYS)))
+        if value.strip():
+            set_[key] = value.strip()
+    for key in args.unset or []:
+        if key not in CONTRACT_KEYS:
+            fail("lane-set: --unset '%s' is not one of %s" % (key, ", ".join(CONTRACT_KEYS)))
+        if key not in set_ and key in lane:
+            removed.append(key)
+
+    lane.update(set_)
+    for key in removed:
+        del lane[key]
+    if set_ or removed:
+        data["lanes"] = lanes
+        write_stacks(repo, data)
+    emit({
+        "ok": True,
+        "lane_id": lane.get("id", ""),
+        "kind": lane.get("kind", ""),
+        "set": set_,
+        "removed": removed,
+        "lane": lane,
+        "path": STACKS_REL,
+        "written": bool(set_ or removed),
+    })
+
+
 def profile_of(repo, lane):
     """The stack profile a lane names, or {} when it names none the kit ships."""
     if not lane:
@@ -1041,6 +1154,12 @@ def kind_block(repo, lanes, kind):
         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", ""),
+        # The API-contract settings, the lane's own or its profile's (lane_value). A
+        # service lane uses the first two and a frontend lane the third; the others read
+        # empty on each.
+        kind + "_contract_run": lane_command(lane, "contract_run", repo),
+        kind + "_contract": lane_value(repo, lane, "contract"),
+        kind + "_client": lane_command(lane, "client", repo),
     }
 
 
@@ -1124,6 +1243,7 @@ def cmd_resolve(args):
             "lane_id": "", "root": "", "source_path": "", "test_path": "", "root_exists": False,
             "build": "", "test": "", "run": "", "migrate": "",
             "language": "", "ecosystem": "",
+            "contract_doc": "", "contract_doc_exists": False,
             "path": STACKS_REL,
         }
         payload.update(kind_block(args.repo, [], "backend"))
@@ -1141,6 +1261,7 @@ def cmd_resolve(args):
         match = next((l for l in lanes if l.get("id") == wanted), {})
     elif args.kind:
         match = next((l for l in lanes if l.get("kind") == args.kind), {})
+    doc = contract_doc(args.repo, lanes)
 
     # `declared` is about LANES and `exists` about the file — they part company on
     # the shipped-but-unfilled seed, which is on disk and declares nothing.
@@ -1165,6 +1286,9 @@ def cmd_resolve(args):
         "language": profile_of(args.repo, match).get("language", ""),
         "ecosystem": profile_of(args.repo, match).get("ecosystem", ""),
         "prototype": data.get("prototype", {}),
+        # The service lane's exported API document, and whether an export has written it.
+        "contract_doc": doc,
+        "contract_doc_exists": bool(doc) and os.path.isfile(os.path.join(args.repo, doc)),
         "path": STACKS_REL,
     }
     payload.update(kind_block(args.repo, lanes, "backend"))
@@ -1443,6 +1567,329 @@ def cmd_run_phase(args):
     })
 
 
+# ─────────────────────────── contract-export ───────────────────────────────
+# The service lane's API document, taken from the service itself. A document served by a
+# running service is the one thing every web stack can produce the same way — Swagger,
+# springdoc, FastAPI and the rest all serve one — so the export starts the service with
+# the lane's `contract_run`, fetches `contract`, and stops it. How a stack (or the pack
+# the lane was scaffolded from) has to be started is the command's business, not this
+# code's.
+
+CONTRACT_HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
+
+
+def _fetch(url, timeout=5):
+    """(status, body bytes, error text). A local https service usually has a development
+    certificate, so certificate checks are skipped for localhost only."""
+    import ssl
+    import urllib.error
+    import urllib.parse
+    import urllib.request
+    ctx = None
+    if url.lower().startswith("https://"):
+        host = (urllib.parse.urlparse(url).hostname or "").lower()
+        if host in ("localhost", "127.0.0.1", "::1"):
+            ctx = ssl._create_unverified_context()
+    try:
+        with urllib.request.urlopen(url, timeout=timeout, context=ctx) as resp:
+            return resp.status, resp.read(), ""
+    except urllib.error.HTTPError as e:
+        return e.code, b"", "HTTP %d" % e.code
+    except Exception as e:  # refused, reset, timed out — the service is not up yet
+        return 0, b"", str(getattr(e, "reason", e))
+
+
+def _api_document(body):
+    """The parsed document, or None when the body is not an OpenAPI/Swagger document."""
+    try:
+        doc = json.loads(body.decode("utf-8-sig"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if isinstance(doc, dict) and ("openapi" in doc or "swagger" in doc) \
+            and isinstance(doc.get("paths"), dict):
+        return doc
+    return None
+
+
+def _operations(doc):
+    """Every operation in a document: [{"id", "method", "path"}], in document order."""
+    ops = []
+    for path, item in (doc.get("paths") or {}).items():
+        if not isinstance(item, dict):
+            continue
+        for method in CONTRACT_HTTP_METHODS:
+            op = item.get(method)
+            if isinstance(op, dict):
+                ops.append({"id": str(op.get("operationId") or ""),
+                            "method": method.upper(), "path": path})
+    return ops
+
+
+def _start(cmd, cwd, log):
+    import subprocess
+    kw = {"shell": True, "cwd": cwd, "stdout": log, "stderr": subprocess.STDOUT}
+    if os.name == "nt":
+        kw["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        kw["start_new_session"] = True   # its own process group, so the stop reaches children
+    return subprocess.Popen(cmd, **kw)
+
+
+def _stop(proc):
+    """Stop the service and everything it started — `dotnet run` and `npm run` both run
+    the real server as a child, which outlives a kill of the parent alone."""
+    import signal
+    import subprocess
+    if proc.poll() is not None:
+        return
+    if os.name == "nt":
+        subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    else:
+        try:
+            os.killpg(proc.pid, signal.SIGTERM)
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=15)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(proc.pid, signal.SIGKILL)
+            except OSError:
+                pass
+    try:
+        proc.wait(timeout=15)
+    except Exception:
+        pass
+
+
+def _tail(path, budget=LANE_TAIL):
+    try:
+        with open(path, "rb") as fh:
+            return fh.read().decode("utf-8", "replace")[-budget:].strip()
+    except OSError:
+        return ""
+
+
+def cmd_contract_export(args):
+    import tempfile
+    import time
+
+    repo = args.repo
+    lanes = (read_stacks(repo) or {}).get("lanes") or []
+    lane = next((l for l in lanes if l.get("kind") == "backend"), {})
+    doc_rel = contract_doc(repo, lanes)
+    doc_abs = os.path.join(repo, doc_rel) if doc_rel else ""
+    cmd = lane_command(lane, "contract_run", repo)
+    url = lane_value(repo, lane, "contract")
+    result = {
+        "ok": False, "ran": False, "lane": lane.get("id", ""), "cmd": cmd, "url": url,
+        "cwd": "", "doc": doc_rel, "doc_exists": bool(doc_abs) and os.path.isfile(doc_abs),
+        "operations": 0, "unnamed": 0, "seconds": 0, "already_running": False,
+        "reason": "", "log_tail": "",
+        # The placeholder a `client` command names the document by, spelled out for a
+        # prompt that asks for one — a workflow cannot write it literally, since the
+        # engine would read it as a variable.
+        "placeholder": "{{contract}}",
+    }
+
+    def done(**kw):
+        result.update(kw)
+        result["doc_exists"] = bool(doc_abs) and os.path.isfile(doc_abs)
+        # One line on which document a reader now has, for a prompt to quote.
+        if result["ok"]:
+            result["status"] = "%s, exported from the built service in this run" % doc_rel
+        elif result["doc_exists"]:
+            result["status"] = ("%s, from an earlier export — this run's failed, so it may "
+                                "be older than the code" % doc_rel)
+        else:
+            result["status"] = ""
+        emit(result)
+
+    if not lane:
+        return done(reason="no service lane is declared in %s" % STACKS_REL)
+    if not root_on_disk(repo, lane.get("root", "")):
+        return done(reason="the service lane root folder '%s' is not on disk yet"
+                    % lane.get("root", ""))
+    if not url:
+        return done(reason="the service lane has no `contract` URL — set it in %s, or in "
+                           "its stack profile" % STACKS_REL)
+
+    # A service already answering at the URL is used as it is: a second instance could
+    # not bind the port anyway. It may be running older code than this run built, which
+    # the caller is told.
+    status, body, _err = _fetch(url)
+    proc, log_path, started, exited = None, "", time.time(), None
+    if status != 200 or _api_document(body) is None:
+        if not cmd:
+            return done(reason="the service lane has no `contract_run` command to start it "
+                               "— set it in %s, or in its stack profile" % STACKS_REL)
+        workdir = lane_workdir(repo, lane)
+        result["cwd"] = os.path.relpath(workdir, repo).replace("\\", "/")
+        fd, log_path = tempfile.mkstemp(prefix="aw-contract-", suffix=".log")
+        log = os.fdopen(fd, "wb")
+        try:
+            proc = _start(cmd, workdir, log)
+            result["ran"] = True
+            deadline = started + args.timeout
+            status, body = 0, b""
+            while time.time() < deadline:
+                if proc.poll() is not None:
+                    exited = proc.returncode
+                    break
+                status, body, _err = _fetch(url)
+                if status == 200 and _api_document(body) is not None:
+                    break
+                time.sleep(2)
+        finally:
+            if proc is not None:
+                _stop(proc)
+            log.close()
+    else:
+        result["already_running"] = True
+
+    seconds = int(time.time() - started)
+    tail = _tail(log_path) if log_path else ""
+    if log_path:
+        try:
+            os.remove(log_path)
+        except OSError:
+            pass
+    doc = _api_document(body) if status == 200 else None
+    if doc is None:
+        if exited is not None:
+            why = "`%s` exited (code %s) before %s answered" % (cmd, exited, url)
+        elif status == 200:
+            why = "%s answered, but not with an OpenAPI or Swagger JSON document" % url
+        elif status:
+            why = "%s answered HTTP %d for %d s" % (url, status, seconds)
+        else:
+            why = "nothing answered at %s within %d s" % (url, args.timeout)
+        return done(seconds=seconds, log_tail=tail,
+                    reason=why + (" — the last exported document is kept" if result["doc_exists"] else ""))
+
+    os.makedirs(os.path.dirname(doc_abs), exist_ok=True)
+    with open(doc_abs, "w", encoding="utf-8") as fh:
+        json.dump(doc, fh, indent=2)
+        fh.write("\n")
+    ops = _operations(doc)
+    note = ("fetched from a service that was already running at %s — it may be older than "
+            "the code this run built" % url) if result["already_running"] else ""
+    done(ok=True, seconds=seconds, operations=len(ops),
+         unnamed=sum(1 for o in ops if not o["id"]), reason=note, log_tail="")
+
+
+# ─────────────────────────── contract-check ────────────────────────────────
+# Do the operation ids a frontend plan cites exist in the exported document? Read by
+# script, so the answer does not depend on a model reading two documents carefully.
+#
+# The ids are read from two table shapes, the two plan templates' own:
+#   - the master plan's §5, a table with an `Operation id` column;
+#   - a delta plan's ADDED/MODIFIED tables, where a row whose section is `Contract
+#     Binding` names the operation id as its element's first `code` span.
+
+_OP_ID = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
+_NOT_AN_ID = {"none", "tbd", "todo", "na"}
+
+
+def _cells(line):
+    s = line.strip()
+    if not s.startswith("|"):
+        return None
+    return [c.strip() for c in s.strip("|").split("|")]
+
+
+def _is_rule(cells):
+    return bool(cells) and all(re.fullmatch(r":?-{3,}:?", c or "") for c in cells)
+
+
+def _op_ids(text):
+    """The operation ids a cell names: `code` spans first, else bare words. Placeholders
+    (`[OperationId]`), dashes and anything with a space are not ids."""
+    spans = re.findall(r"`([^`]+)`", text)
+    tokens = [t.strip() for t in (spans if spans else re.split(r"[,·;]\s*|\s+", text))]
+    return [t for t in tokens if _OP_ID.match(t) and t.lower() not in _NOT_AN_ID]
+
+
+def plan_operation_ids(text):
+    """(cited ids in order, rows with a binding but no id)."""
+    lines = text.splitlines()
+    cited, uncited = [], 0
+    i = 0
+    while i < len(lines):
+        header = _cells(lines[i])
+        rule = _cells(lines[i + 1]) if i + 1 < len(lines) else None
+        if header is None or rule is None or not _is_rule(rule):
+            i += 1
+            continue
+        lowered = [h.lower() for h in header]
+        id_col = next((n for n, h in enumerate(lowered) if h.replace("-", " ") == "operation id"), -1)
+        section_col = next((n for n, h in enumerate(lowered) if h.startswith("section")), -1)
+        i += 2
+        while i < len(lines) and _cells(lines[i]) is not None:
+            row = _cells(lines[i])
+            i += 1
+            if id_col >= 0 and id_col < len(row):
+                ids = _op_ids(row[id_col])
+            elif section_col >= 0 and section_col < len(row) \
+                    and "contract binding" in row[section_col].lower() and section_col + 1 < len(row):
+                spans = re.findall(r"`([^`]+)`", row[section_col + 1])
+                ids = [s for s in spans[:1] if _OP_ID.match(s)]
+            else:
+                continue
+            if ids:
+                cited.extend(x for x in ids if x not in cited)
+            else:
+                uncited += 1
+    return cited, uncited
+
+
+def cmd_contract_check(args):
+    repo = args.repo
+    plan_abs = args.plan if os.path.isabs(args.plan) else os.path.join(repo, args.plan)
+    doc_rel = args.doc or contract_doc(repo)
+    doc_abs = (doc_rel if os.path.isabs(doc_rel) else os.path.join(repo, doc_rel)) if doc_rel else ""
+    result = {"ok": False, "plan": args.plan, "doc": doc_rel,
+              "doc_exists": bool(doc_abs) and os.path.isfile(doc_abs),
+              "cited": 0, "ids": [], "missing": [], "uncited": 0,
+              "doc_operations": 0, "doc_unnamed": 0, "reason": ""}
+    if not os.path.isfile(plan_abs):
+        result["reason"] = "the frontend plan %s is not on disk" % args.plan
+        return emit(result)
+    with open(plan_abs, encoding="utf-8", errors="replace") as fh:
+        cited, uncited = plan_operation_ids(fh.read())
+    result.update(cited=len(cited), ids=cited, uncited=uncited)
+    if not result["doc_exists"]:
+        result["reason"] = "no exported API document at %s" % (doc_rel or "(no service lane)")
+        return emit(result)
+    with open(doc_abs, "rb") as fh:
+        doc = _api_document(fh.read())
+    if doc is None:
+        result["reason"] = "%s is not an OpenAPI or Swagger JSON document" % doc_rel
+        return emit(result)
+    ops = _operations(doc)
+    known = {o["id"] for o in ops if o["id"]}
+    lower = {k.lower(): k for k in known}
+    missing = []
+    for x in cited:
+        if x not in known:
+            near = lower.get(x.lower())
+            missing.append(x + (" (the document has %s)" % near if near else ""))
+    result.update(missing=missing, doc_operations=len(ops),
+                  doc_unnamed=sum(1 for o in ops if not o["id"]))
+    parts = []
+    if missing:
+        parts.append("%d cited operation id(s) are not in %s: %s"
+                     % (len(missing), doc_rel, ", ".join(missing)))
+    if not cited:
+        parts.append("the plan cites no operation id")
+    if uncited:
+        parts.append("%d binding row(s) cite no operation id" % uncited)
+    result["reason"] = "; ".join(parts)
+    result["ok"] = bool(cited) and not missing
+    emit(result)
+
+
 # ──────────────────────────────── probe ────────────────────────────────────
 
 def profile_terms(prof):
@@ -1555,7 +2002,7 @@ def main():
                         "evidence there, so a service profile cannot relocate onto the UI's files")
     p.set_defaults(func=cmd_detect)
 
-    p = sub.add_parser("declare", help="upsert a lane into stacks.json (sole writer)")
+    p = sub.add_parser("declare", help="upsert a whole lane into stacks.json")
     p.add_argument("--profile", required=True,
                    help="profile id, a select_options label, 'none', or 'detected' "
                         "(a stack the kit ships no profile for — needs --stack and --root)")
@@ -1612,12 +2059,36 @@ def main():
     p.set_defaults(func=cmd_verify)
 
     p = sub.add_parser("run-phase", help="run a phase's command for every declared lane")
-    p.add_argument("--phase", required=True, choices=["build", "test", "run", "migrate"],
-                   help="which project-supplied command to run")
+    p.add_argument("--phase", required=True, choices=["build", "test", "run", "migrate", "client"],
+                   help="which project-supplied command to run; `client` is a frontend lane's "
+                        "client generator, with {{contract}} expanded")
     p.add_argument("--kind", choices=["backend", "frontend"],
                    help="restrict to one lane kind (default: every declared lane)")
     p.set_defaults(func=cmd_run_phase)
 
+    p = sub.add_parser("set", help="change API-contract keys on a declared lane")
+    p.add_argument("--id", default="", help="the lane id")
+    p.add_argument("--kind", choices=["backend", "frontend"],
+                   help="the lane of this kind, when --id is not given")
+    p.add_argument("--set", action="append", default=[], metavar="KEY=VALUE",
+                   help="repeatable; KEY is one of %s, and an empty VALUE changes nothing"
+                        % ", ".join(CONTRACT_KEYS))
+    p.add_argument("--unset", action="append", default=[], metavar="KEY",
+                   help="repeatable; remove KEY, so the lane reads its profile's value again")
+    p.set_defaults(func=cmd_set)
+
+    p = sub.add_parser("contract-export",
+                       help="start the service lane, save its API document, stop it")
+    p.add_argument("--timeout", type=int, default=180,
+                   help="seconds to wait for the document after starting the service")
+    p.set_defaults(func=cmd_contract_export)
+
+    p = sub.add_parser("contract-check",
+                       help="the operation ids a frontend plan cites vs the exported document")
+    p.add_argument("--plan", required=True, help="the frontend plan (master or delta)")
+    p.add_argument("--doc", default="", help="the API document (default: the exported one)")
+    p.set_defaults(func=cmd_contract_check)
+
     p = sub.add_parser("probe", help="evidence of a lane of this kind (file signals only)")
     p.add_argument("--kind", choices=["backend", "frontend"], default="frontend")
     p.add_argument("--hint", default="", help="free prose to scan for a stack name")

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

@@ -17,6 +17,8 @@
   "build": "dotnet build",
   "test": "dotnet test",
   "run": "dotnet run --project {{host}}",
+  "contract_run": "dotnet run --project {{host}} -- --environment Development --urls http://localhost:5000",
+  "contract": "http://localhost:5000/swagger/v1/swagger.json",
   "host_patterns": [
     "**/*.AppHost.csproj",
     "**/*.Api.csproj",

package/assets/.appweaver/stack-profiles/java-spring.json

@@ -17,6 +17,8 @@
   "build": "./mvnw clean install",
   "test": "./mvnw test",
   "run": "./mvnw spring-boot:run",
+  "contract_run": "./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8080",
+  "contract": "http://localhost:8080/v3/api-docs",
   "detect": [
     "pom.xml",
     "build.gradle"

package/assets/.appweaver/stacks.json

@@ -14,7 +14,9 @@
         "build": "dotnet build",
         "test": "dotnet test",
         "run": "dotnet run --project {{host}}",
-        "migrate": "dotnet ef database update --project {{host}}"
+        "migrate": "dotnet ef database update --project {{host}}",
+        "contract_run": "dotnet run --project {{host}} -- --environment Development --urls http://localhost:5000",
+        "contract": "http://localhost:5000/swagger/v1/swagger.json"
       },
       {
         "id": "web",
@@ -28,7 +30,8 @@
         "build": "npm run build",
         "test": "npm test",
         "run": "npm run dev",
-        "migrate": ""
+        "migrate": "",
+        "client": "npx openapi-typescript {{contract}} -o lib/api/schema.d.ts"
       }
     ],
     "prototype": {

package/assets/.appweaver/templates/delta-design-template.md

@@ -89,7 +89,7 @@ it realises. "Realisation only — no spec delta" for a plan-only change.]
 | Section (§) | Element | Kind | Serves |
 |---|---|---|---|
 | Application (§2) | `[Command/Query]` + handler | use-case | US-[n] · FR-[nnn] |
-| API (§3) | `[VERB] [/route]` | endpoint | US-[n] · FR-[nnn] |
+| API (§3) | `[OperationId]` · `[VERB] [/route]` | endpoint | US-[n] · FR-[nnn] |
 | Domain (§1) | `[Event]` handling / `[VO]` mapping | model realisation | BR-[nnn] · CN-[nnn] |
 | Infrastructure (§4.2) | `I[External]` adapter | contract realisation | IC-[nnn] |
 | Cross-cutting (§5) | [audit / retention / exposure decision] | constraint realisation | CN-[nnn] · DC-[nnn] |
@@ -118,12 +118,14 @@ realisation); new migration needed? (yes/no); any contract change other systems
   What this change adds to or alters in the service's PUBLISHED surface — the only part
   of this document the frontend lane may bind against. One row per contract; the frontend
   delta plan cites these rather than re-deriving them. "None" when the surface is
-  unchanged, which is what a purely internal refactor should say.
+  unchanged, which is what a purely internal refactor should say. The operation id is the
+  endpoint's name in the published API document, unique across the service; an endpoint
+  the master plan already names keeps that id.
 -->
 
-| Contract | Change | Shape | Serves |
-|---|---|---|---|
-| `[VERB] [/route]` | added / changed | [request → response field shapes] | IC-[nnn] · FR-[nnn] |
+| Operation id | Contract | Change | Shape | Serves |
+|---|---|---|---|---|
+| `[OperationId]` | `[VERB] [/route]` | added / changed | [request → response field shapes] | IC-[nnn] · FR-[nnn] |
 
 ## Other open deltas