@sumrco/cli 0.3.0 → 0.3.2

package/ai/modules/kontract/resources/{schema-reuse.rf.md → authoring/schema-reuse.rf.md}

@@ -2,7 +2,7 @@
 category: reference
 name: schema-reuse
 title: Schema Reuse and Shared Components
-description: "How to author OpenAPI/AsyncAPI specs with reusable shared components, $ref, and safe composition so Kontract output stays consistent and avoids copy-pasted contract drift."
+description: "How to author API and async schemas with reusable shared components, $ref, Kontract sets, and safe composition so Kontract output stays consistent and avoids duplicated contract shapes."
 label: Schema Reuse
 when: Adding repeated fields, response envelopes, pagination, errors, schedules, config objects, or reviewing generated diffs with duplicated DTO/model shapes
 order: 12
@@ -17,10 +17,25 @@ operations or services, define it once and reference it with `$ref`.
 This reduces drift in the source specs immediately. It also gives Kontract a
 clear path to emit more shared generated code as the generator evolves.
 
-Before extracting or naming a shared component, choose a name from the domain
+Before extracting or naming a shared component, choose a name from product
 language. Shared names should stay specific enough for generated DTO/model/SDK
 symbols.
 
+## Local-first promotion model
+
+Keep a schema in the smallest owning place until reuse proves it should move:
+
+1. **Surface-local** — define one-off request, response, and model shapes in the
+   root file's `components.schemas`.
+2. **Capability-local shared** — move the shape into the capability's
+   `shared/` folder when two or more surfaces in that capability reuse the same
+   concept.
+3. **Repo-level shared** — move the shape into `schema/shared/` only when two or
+   more capabilities share the same semantics, lifecycle, and owner.
+
+Do not create shared files only because a shape might become reusable later.
+Shared components are a promotion step, not the default folder for every model.
+
 ## What to share
 
 Prefer shared components for concepts that mean the same thing everywhere:
@@ -84,26 +99,107 @@ content:
       $ref: ../shared/common.yml#/components/schemas/ImageMimeType
 ```
 
-## Sharing schemas across OpenAPI and AsyncAPI fragments
+## Protocol scenarios for reuse
+
+Pick the protocol scenario before extracting shared components:
+
+1. **API-only** — share HTTP schemas, parameters, responses, envelopes,
+   pagination, errors, and scalar constraints through API schema components.
+2. **async-only** — share message payload schemas, message enums, scalar
+   constraints, and value objects through async schema components or
+   capability-local model fragments.
+3. **API + async** — keep protocol layers separate and share only neutral
+   components with identical meaning. The safest cross-protocol sharing is
+   usually enums, IDs, slugs, scalar value objects, and simple payload shapes.
+
+Do not create cross-protocol shared files only because API schema and async schema
+payloads look similar today. Shared components must have the same product
+meaning and owner.
+
+## API-only reuse
+
+If the repo only has API schema sources, keep one-off schemas in the owning
+API schema surface. Use a capability-local `shared/` folder only after multiple
+surfaces in that capability reuse the same concept. Use `schema/shared/` only
+after multiple capabilities share the same concept.
+
+```text
+schema/
+  bookstore/
+    main.api.yml
+    catalog.api.yml
+    reviews.api.yml
+    shared/
+      enums.yml                 # reused by catalog and reviews
+      components.yml
+  shared/
+    errors.yml                  # reused by multiple capabilities
+    pagination.yml
+```
+
+Use API schema `components` for reusable HTTP shapes:
+
+```yaml
+# schema/bookstore/shared/enums.yml
+components:
+  schemas:
+    BookFormat:
+      type: string
+      enum: [hardcover, paperback, ebook]
+```
+
+## async-only reuse
 
-When one domain has both HTTP and messaging contracts, keep protocol entrypoints
-separate and share only neutral business schemas.
+If the repo only has async schema sources, keep reusable message payload schemas and
+enums close to the messaging roots or under `schema/shared/` when several
+message families share the same meaning.
 
 ```text
 schema/
+  shared/
+    message-enums.yml
   bookstore/
-    bookstore.openapi.yml
-    bookstore.asyncapi.yml
+    bookstore.async.yml
+    messages/
+      book-commands.yml
+      book-events.yml
+    models/
+      books.yml
+      enums.yml
+```
+
+```yaml
+# schema/bookstore/models/enums.yml
+BookFormat:
+  type: string
+  enum: [hardcover, paperback, ebook]
+```
+
+## API + async shared components
+
+When one product capability has both HTTP and messaging contracts, keep protocol
+entrypoints separate and share only business schemas.
+
+```text
+schema/
+  bookstore/
+    bookstore.api.yml
+    bookstore.async.yml
     paths/books.yml
     messages/books.yml
-    models/shared.yml
+    models/enums.yml
     models/books.yml
 ```
 
 Good shared fragment:
 
 ```yaml
-# schema/bookstore/models/shared.yml
+# schema/bookstore/models/enums.yml
+BookFormat:
+  type: string
+  enum: [hardcover, paperback, ebook]
+
+# schema/bookstore/models/books.yml
 BookSlug:
   type: string
   minLength: 1
@@ -114,30 +210,28 @@ PaginationMeta:
   $ref: ../../shared/common.yml#/components/schemas/PaginationMeta
 ```
 
-OpenAPI can use it through path and response fragments:
+API schema can use it through path and response fragments:
 
 ```yaml
 # schema/bookstore/paths/books.yml
-paths:
-  /books/{bookSlug}:
-    parameters:
-      - name: bookSlug
-        in: path
-        required: true
-        schema:
-          $ref: ../models/shared.yml#/BookSlug
-    get:
-      operationId: getBook
-      responses:
-        "200":
-          description: Book detail.
-          content:
-            application/json:
-              schema:
-                $ref: ../models/books.yml#/Book
+parameters:
+  - name: bookSlug
+    in: path
+    required: true
+    schema:
+      $ref: ../models/books.yml#/BookSlug
+get:
+  operationId: getBook
+  responses:
+    "200":
+      description: Book detail.
+      content:
+        application/json:
+          schema:
+            $ref: ../models/books.yml#/Book
 ```
 
-AsyncAPI can use the same payload schema from a message fragment:
+async schema can use the same payload schema from a message fragment:
 
 ```yaml
 # schema/bookstore/messages/books.yml
@@ -152,15 +246,94 @@ messages:
 
 Keep protocol-specific pieces out of `models/`:
 
-- OpenAPI paths, parameters, request bodies, responses → `paths/` or
+- API schema paths, parameters, request bodies, responses → `paths/` or
   `components/`.
-- AsyncAPI channels, operations, messages → `messages/`.
-- Payload objects, enums, scalars, pagination, and reusable business shapes →
-  `models/`.
+- async schema channels, operations, messages → `messages/`.
+- Payload objects, enums, scalars, and reusable business shapes → `models/`.
+- Share enums through `models/enums.yml` when API schema and async schema use the same
+  vocabulary and values.
 
-This keeps HTTP DTOs, NATS zod messages, and generated models aligned without
+This keeps API contracts, async messages, and generated models aligned without
 making either protocol depend on the other's metadata.
 
+## Kontract sets for reusable map fragments
+
+Use `kontract.sets` when repeated YAML maps make the source noisy but the
+reusable concept is not a standalone schema. `$sets` can apply reusable maps in
+responses, parameters, schema properties, headers, request bodies, async
+operations, messages, payload schemas, or any other mapping.
+
+```yaml
+# schema/bookings/shared/components.yml
+kontract:
+  sets:
+    StandardErrors:
+      "400":
+        $ref: '#/components/responses/BadRequest'
+      "401":
+        $ref: '#/components/responses/Unauthorized'
+      "403":
+        $ref: '#/components/responses/Forbidden'
+      "404":
+        $ref: '#/components/responses/NotFound'
+      "500":
+        $ref: '#/components/responses/InternalServerError'
+    AuditedFields:
+      createdAt:
+        type: string
+        format: date-time
+      updatedAt:
+        type: string
+        format: date-time
+components:
+  responses:
+    BadRequest:
+      description: Bad request.
+    Unauthorized:
+      description: Unauthorized.
+    Forbidden:
+      description: Forbidden.
+    NotFound:
+      description: Not found.
+    InternalServerError:
+      description: Internal server error.
+```
+
+```yaml
+# schema/bookings/public.api.yml
+api: 3.0.3
+paths:
+  /bookings:
+    post:
+      responses:
+        $sets:
+          - $ref: ./shared/components.yml#/kontract/sets/StandardErrors
+        "201":
+          description: Booking created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateBookingResponse'
+components:
+  schemas:
+    Booking:
+      type: object
+      properties:
+        $sets:
+          - $ref: ./shared/components.yml#/kontract/sets/AuditedFields
+        id:
+          type: string
+```
+
+Set rules:
+
+- `$sets` merges maps only; it does not concatenate arrays.
+- Local keys override set keys.
+- Multiple sets that define the same key must use identical values.
+- Kontract rebases copied `$ref` values when a set comes from another file.
+- Normalized files passed to validators and generators do not contain
+  `kontract` or `$sets`.
+
 ## Response envelopes
 
 If every endpoint repeats the same envelope fields, do not retype them in every
@@ -187,7 +360,7 @@ components:
 ```
 
 ```yaml
-# schema/recipes/catalog.openapi.yml
+# schema/recipes/catalog.api.yml
 components:
   schemas:
     RecipesFindOneResponse:
@@ -261,7 +434,7 @@ Then service-specific schedules can reference or compose those shared pieces.
 
 ## Review checklist
 
-After writing or updating any `*.openapi.yml` or `*.asyncapi.yml` file, review
+After writing or updating any `*.api.yml` or `*.async.yml` file, review
 the spec before running generation. Actively look for these smells:
 
 - the same `success/timestamp/path/message` fields repeated in many response
@@ -276,7 +449,7 @@ the spec before running generation. Actively look for these smells:
 - repeated day-of-week schedule structures;
 - error response schemas or problem-details bodies copied instead of referencing
   shared responses;
-- event envelopes or AsyncAPI reply wrappers copied with the same product
+- event envelopes or async schema reply wrappers copied with the same product
   meaning;
 - generated diffs adding many near-identical DTO/model files after a small API
   change.
@@ -293,24 +466,27 @@ components when:
 - a request DTO and response DTO intentionally differ, even if fields overlap;
 - names would become vague (`CommonThing`, `BaseData`, `GenericConfig`);
 - the reusable name would hide a real product term, such as using `Collection`
-  when collections are a domain concept in the product;
-- sharing would force unrelated teams/domains to coordinate every future change.
+  when collections are a product concept;
+- sharing would force unrelated teams or product areas to coordinate every
+  future change.
 
 A good shared component has a clear product meaning and a stable owner.
 
 ## Safe workflow
 
-1. Move the repeated shape into `schema/shared/*.yml` or a domain-level shared
-   component.
-2. Replace duplicated schemas/parameters/responses with `$ref`.
-3. Use supported `allOf` object composition when a concrete response extends a
+1. Keep new schemas local to the root or surface that owns them.
+2. When reuse appears inside one capability, move the repeated shape into that
+   capability's `shared/` folder and replace duplicates with `$ref`.
+3. When reuse appears across capabilities, promote the shape to
+   `schema/shared/` and update `$ref` links deliberately.
+4. Use supported `allOf` object composition when a concrete response extends a
    shared base.
-4. Run `sumr kontract validate`.
-5. Run a scoped generation first, for example:
+5. Run `sumr kontract validate`.
+6. Run a scoped generation first, for example:
 
 ```bash
 sumr kontract generate --source api --target backend --specific recipes/catalog
 ```
 
-6. Review both the spec diff and generated diff. If generated output changed in
-   unrelated domains, stop and investigate before committing.
+7. Review both the spec diff and generated diff. If generated output changed in
+   unrelated product areas, stop and investigate before committing.

package/ai/modules/kontract/resources/{scope-and-splitting.rf.md → authoring/scope-and-splitting.rf.md}

@@ -2,18 +2,18 @@
 category: reference
 name: scope-and-splitting
 title: Scope, Size, and Splitting
-description: "How to keep Kontract specs and generator code small, domain-aligned, and reviewable with explicit line-count budgets and split triggers."
+description: "How to keep Kontract specs and generator code small, product-aligned, and reviewable with explicit line-count budgets and split triggers."
 label: Scope and Splitting
-when: Reviewing large specs or code files, deciding whether to split a domain/subdomain spec, or optimizing oversized Kontract modules
+when: Reviewing large specs or code files, deciding whether to split a product capability/API surface spec, or optimizing oversized Kontract modules
 order: 18
 ---
 
 # Scope, Size, and Splitting
 
-Kontract is the next iteration of the AutoSync/AsyncAPI idea: keep the
+Kontract is the next iteration of the AutoSync/async schema idea: keep the
 documentation-first and DRY discipline, but make the boundaries more explicit.
 Large files are not automatically bad, but they hide duplicated concepts,
-mixed domains, and unstable generated output. Treat size limits as review
+mixed product areas, and unstable generated output. Treat size limits as review
 triggers first and hard caps second.
 
 ## Source-of-truth rule
@@ -29,7 +29,7 @@ Files under `resources/` become public AI guidance. Never use internal SUMR,
 customer, product, infrastructure, event-subject, route, table, or data-model
 examples there. Public examples must be sanitized and generic.
 
-Use neutral domains such as:
+Use example areas such as:
 
 - kitchen recipes and ingredients;
 - bookstore inventory;
@@ -48,7 +48,7 @@ explain the module's current behavior.
 | File kind | Healthy target | Review trigger | Split/optimize trigger | Hard stop |
 |---|---:|---:|---:|---:|
 | Kontract TypeScript source | <= 200 lines | > 250 lines | > 400 lines | > 500 lines |
-| OpenAPI/AsyncAPI service spec | 150-350 lines | > 400 lines | > 700 lines | > 1000 lines |
+| API/async service spec | 150-350 lines | > 400 lines | > 700 lines | > 1000 lines |
 | Shared component YAML | 100-300 lines | > 400 lines | > 600 lines | > 900 lines |
 | Generated TypeScript output | no manual target | review if surprising | fix generator/spec, never hand-split | no hand edits |
 
@@ -60,7 +60,7 @@ manual splitting, but they can still reveal generator or spec-design problems.
 
 Split or optimize before adding more content when a file shows any of these:
 
-- multiple product domains or subdomains in one spec;
+- multiple product capabilities or API surfaces in one spec;
 - more than roughly 7-10 operations with different lifecycle owners;
 - request/response schemas for unrelated use cases in one component block;
 - repeated envelope, pagination, error, scalar, schedule, or config shapes;
@@ -73,92 +73,148 @@ Do not split only by line count. First identify the product or technical
 boundary that gives the new file a stable name and owner.
 
 Visual section comments can help readers navigate a healthy file, but they are
-not a substitute for splitting an oversized or mixed-domain spec. If comments
-start acting like a table of contents, split by domain/subdomain instead.
+not a substitute for splitting an oversized or mixed-surface spec. If comments
+start acting like a table of contents, split by capability/surface instead.
 
-## Domain and subdomain spec structure
+## Product capability and API surface spec structure
 
 Use directory nesting to communicate product ownership. The path should answer
 "who owns this contract?" and the filename should answer "which surface is this?"
+Read `kontract.guidance.profile.schemaLayoutStyle` before proposing a layout and
+use the canonical trees in the schema layout style reference. Do not describe
+resource-area fragments inside a product-capability folder as a repo-wide
+`by-resource-area` layout.
+
+For an API-only repo, keep the example API-only:
 
 ```text
 schema/
+  recipes/
+    main.api.yml             # api: 3.0.3; grouped under recipes/http
+    catalog.api.yml
+    ingredients.api.yml
+    shared/                     # only promoted reusable recipe concepts
+      enums.yml
+      components.yml
+  kitchen/
+    stations.api.yml
   shared/
-    scalars.yml
-    pagination.yml
+    pagination.yml              # only promoted cross-capability components
     errors.yml
-    events.yml
-    scheduling.yml
+```
+
+For an async-only repo, keep the example async-only:
+
+```text
+schema/
+  shared/
+    message-enums.yml
   recipes/
-    recipes.openapi.yml
-    ingredients.openapi.yml
-    publishing.asyncapi.yml
-  kitchen/
-    stations.openapi.yml
-    prep-jobs.asyncapi.yml
-    inventory.asyncapi.yml
-  bookstore/
-    bookstore.openapi.yml       # OpenAPI root entrypoint
-    bookstore.asyncapi.yml      # AsyncAPI root entrypoint
-    paths/
-      books.yml                 # HTTP paths by subdomain
-      authors.yml
+    recipes.async.yml
     messages/
-      books.yml                 # NATS channels/messages by subdomain
-      authors.yml
+      recipe-commands.yml
+      recipe-events.yml
     models/
-      shared.yml                # model fragments shared by both roots
-      books.yml
-      authors.yml
+      recipe.yml
+      enums.yml
 ```
 
-When a folder already carries the domain name, prefer `*.schema.yml` for
-subdomain surfaces that should generate as one domain package:
+When a folder already carries the product-capability name, prefer
+`*.api.yml` for focused surfaces that should generate as one package:
 
 ```text
 schema/
   recipes/
-    catalog.schema.yml          # openapi: 3.0.3
-    publishing.schema.yml       # asyncapi: 3.0.0
-    inventory.schema.yml        # asyncapi: 3.0.0
+    catalog.api.yml          # api: 3.0.3
+    ingredients.api.yml      # api: 3.0.3
+    shared/
+      enums.yml                 # promoted after both surfaces need it
+      components.yml
 ```
 
 Kontract content-detects the protocol marker and groups those files under the
-first folder (`recipes` in this example). Use explicit `*.openapi.yml` or
-`*.asyncapi.yml` when each nested file should remain an independently generated
+first folder (`recipes` in this example). Use explicit `*.api.yml` or
+`*.async.yml` when each nested file should remain an independently generated
 service path.
 
-When one domain should keep a single generated package but the contract is too
-large for one file, keep the explicit root files and split the internals into
-plain `.yml` fragments. This mirrors Redocly-style authoring: roots are the
-public entrypoints, fragments are implementation detail, and schemas can be
-shared by OpenAPI and AsyncAPI only when the business shape is protocol-neutral.
+Add async schema examples only when messaging contracts exist:
+
+```text
+schema/
+  recipes/
+    catalog.api.yml          # api: 3.0.3
+    publishing.async.yml     # async: 3.0.0
+    inventory.async.yml      # async: 3.0.0
+```
+
+When API schema and async schema both exist, keep `paths/` and `messages/` separate.
+Share only schemas, especially enums, scalar value objects, IDs, and
+slugs, through `models/` or `schema/shared/`.
+
+If the selected schema layout style is `by-resource-area`, the resource
+areas should be top-level roots under the configured schema input, not nested
+under a product-capability folder. Moving from capability roots to resource-area
+roots changes generated output namespaces/import paths, so call it out as a
+schema and generated-output migration before recommending it.
+
+When one product capability should keep a single generated package but the
+contract is too large for one file, keep the explicit root files and split the
+internals into plain `.yml` fragments. This mirrors Redocly-style authoring:
+roots are the public entrypoints, fragments are implementation detail, and
+schemas can be shared by API schema and async schema only when the business shape is
+protocol-neutral.
+
+```text
+schema/
+  bookstore/
+    bookstore.api.yml       # API schema root entrypoint
+    paths/
+      books.yml                 # API schema Path Item fragment
+      authors.yml               # API schema Path Item fragment
+    models/
+      shared.yml
+      books.yml
+      authors.yml
+```
+
+Only add `bookstore.async.yml` and `messages/` fragments if the repo has
+async schema contracts or the user asks for messaging. Do not use split fragments as
+the default answer for a small API schema file.
 
 Guidelines:
 
-- Keep one entry-point spec per bounded API surface, not one giant file per
-  repo.
+- Keep one entry-point spec per independently released API surface, not one
+  giant file per repo.
 - Split by product meaning: `recipes`, `ingredients`, `orders`, `jobs`, or
   `inventory`, not by generic words like `common`, `misc`, or `helpers`.
+- Keep API schema route hierarchies aligned with the selected HTTP style. When a
+  child route depends on a parent for authorization, tenancy, lifecycle, or
+  meaning, nest it under that parent unless the selected style documents a
+  different public pattern.
 - Use short section markers only as editor landmarks inside a file that is still
   small enough to review.
-- Use `schema/shared/` only for cross-domain concepts with stable semantics and
-  an obvious owner.
-- Prefer domain-local shared components when a concept is reused only inside one
-  domain.
-- Keep `info.title` deliberate because AsyncAPI NATS namespaces derive from it;
+- Use `schema/shared/` only for cross-capability concepts with stable semantics
+  and an obvious owner.
+- Prefer capability-local shared components when a concept is reused only inside
+  one product capability.
+- Keep one-off schemas inside the surface that owns them. Do not move every
+  component into `shared/` to anticipate future reuse.
+- Keep `info.title` deliberate because async schema NATS namespaces derive from it;
   filenames and titles should not drift semantically.
 - Keep `$ref` paths repo-relative and validate after moving files.
 
 ## Refactor order for oversized specs
 
-1. Extract repeated cross-domain scalars, pagination, errors, envelopes, events,
-   schedules, and config objects into `schema/shared/`.
-2. Extract repeated domain-only shapes into a domain-local shared YAML file.
-3. Split operations by subdomain when the file still mixes independently owned
+1. Keep one-off schemas local to the root or surface that owns them.
+2. Extract repeated capability-only shapes into a capability-local `shared/`
+   folder.
+3. Promote repeated cross-capability scalars, pagination, errors, envelopes,
+   schedules, and config objects into `schema/shared/` only when the same meaning
+   is reused across capabilities.
+4. Split operations by API surface when the file still mixes independently owned
    workflows.
-4. Validate the moved refs with `sumr kontract validate`.
-5. Generate with the smallest useful scope and review both the spec diff and
+5. Validate the moved refs with `sumr kontract validate`.
+6. Generate with the smallest useful scope and review both the spec diff and
    generated output diff.
 
 ## Refactor order for oversized code