@sumrco/cli 0.3.0 → 0.3.2

package/ai/modules/kontract/resources/api-generation-standards.rf.md

@@ -0,0 +1,83 @@
+---
+category: reference
+name: api-generation-standards
+title: API Generation Standards
+description: "Professional guardrails for Kontract API generation, including query parameters, safe identifiers, component schemas, map output, strict TypeScript, and Bun-native execution."
+label: API Generation Standards
+when: Reviewing Kontract schema modules or generator changes for API output quality, SDK behavior, query parameters, inline schemas, or strict TypeScript compatibility
+order: 45
+---
+
+# API Generation Standards
+
+Use these standards when authoring API schemas, changing API generation, or
+reviewing generated API contracts and SDKs. The goal is predictable,
+professional output that compiles under strict TypeScript and stays aligned with
+the source contract.
+
+## Required behavior
+
+- **Preserve query parameter semantics.** Optional query params stay optional,
+  array query params serialize according to the spec, and enum query params use
+  generated enum symbols instead of raw literal imports.
+- **Keep wire names and local identifiers separate.** Wire keys such as `from`,
+  `class`, and `default` must remain unchanged in requests, while generated local
+  variables use safe TypeScript identifiers.
+- **Use named component schemas for operation payloads.** Request and response
+  bodies should reference `components.schemas` so generated DTO/model/SDK symbols
+  are stable and reviewable.
+- **Generate map-shaped schemas deliberately.** `additionalProperties` schemas
+  must preserve named fields plus the typed catch-all/index-signature behavior
+  across Zod, DTO, model, and SDK output.
+- **Fail clearly for unsupported schema features.** Unsupported `oneOf`,
+  `anyOf`, `not`, and discriminator shapes should stop generation before a
+  consumer repo is left with partial or missing symbols.
+- **Keep application ownership boundaries clean.** Kontract emits contracts,
+  DTOs, framework-models, API metadata, and SDK clients. Application
+  modules, handlers, providers, and wiring stay in the consuming app.
+- **Compile generated output under strict TypeScript.** Generated files must not
+  contain dangling imports, unsafe `any`, stale runtime globals, deprecated Nest
+  HTTP client imports, or framework symbols that were never emitted.
+- **Stay Bun-native.** Generation must not require Java, Docker images,
+  downloaded generator binaries, or template folders at runtime.
+
+## Spec authoring rules
+
+- Put reusable request bodies, response bodies, parameters, enums, and object
+  fragments under `components` and reference them with `$ref`.
+- Encode validation constraints in API schema (`minLength`, `maxLength`, `minimum`,
+  `maximum`, `pattern`, `format`) so DTO and Zod output can enforce the same
+  contract.
+- Use `additionalProperties` only when the payload is intentionally map-shaped.
+  Prefer typed map values over `additionalProperties: true`.
+- For repeated query values, use `type: array` with scalar `items` and an
+  explicit API schema serialization shape when the default is not correct for the
+  API.
+- Keep operation IDs stable. They become generated operation metadata, SDK method
+  names, and review anchors.
+
+## Generator implementation rules
+
+- Normalize SDK request parameter names without changing wire keys.
+- Sort required model properties before optional ones unless the target explicitly
+  preserves source order.
+- Generate enum values once and import the generated enum symbol everywhere that
+  target expects a reusable enum.
+- Prune stale files when a schema, enum, or operation is removed from the source
+  spec.
+- Keep generated runtime helpers small and target-specific; do not add a heavy
+  shared runtime unless a target explicitly requires it.
+
+## Reviewer checklist
+
+- Generated files include the auto-generated header and are not hand-edited.
+- Query DTOs and SDK request types preserve optionality and array semantics from
+  the spec.
+- Operation payload schemas reference named components instead of anonymous
+  inline request/response objects.
+- Map-shaped schemas preserve named properties and catch-all value types.
+- Generated files avoid unsafe symbols such as `any`, anonymous `InlineObject`
+  models, missing enum aliases, stale `basePath` globals, deprecated client
+  imports, and unsafe `apiKeys` access.
+- Unsupported schema features fail before any consumer repo is left with partial
+  broken output.

package/ai/modules/kontract/resources/{configuration.rf.md → authoring/configuration.rf.md}

@@ -10,11 +10,17 @@ order: 15
 
 # Kontract Configuration
 
-Kontract reads repo-local configuration from `sumr.yaml`. A source points at a
-schema directory; each target chooses an output directory and generator.
+Kontract reads repo-local configuration from `sumr.yaml`. A guidance profile
+controls docs and AI examples only. A source points at a schema directory; each
+target chooses an output directory and generator.
 
 ```yaml
 kontract:
+  guidance:
+    profile:
+      apiStyle: pragmatic-rest
+      asyncStyle: command-event
+      schemaLayoutStyle: by-product-capability
   sources:
     - name: api
       input: schema
@@ -36,12 +42,44 @@ kontract:
             stringEnums: true
 ```
 
+## Guidance profile
+
+| Field | Meaning |
+|---|---|
+| `guidance.profile.apiStyle` | API style used in examples: `pragmatic-rest`, `resource-oriented`, `json-api`, `odata`, `rpc-action`, `graphql-http`, `hypermedia-rest`, `webhook-callback`, or `mixed`. |
+| `guidance.profile.asyncStyle` | async style used in examples: `command-event`, `event-driven`, `request-reply`, `cloud-events`, or `mixed`. |
+| `guidance.profile.schemaLayoutStyle` | Schema layout style used in examples: `by-product-capability`, `by-api-surface`, `by-service-owner`, `by-resource-area`, `by-workflow`, `by-message-family`, or `mixed`. |
+
+`rpc-action` is an HTTP example style for action-oriented endpoints and real
+RPC surfaces when they exist. Do not infer that the application implements a
+generic RPC framework only because a path contains verbs such as `confirm`,
+`process`, or `check-conflicts`.
+
+For schema layout examples, use the canonical layout trees in
+`design-profile/schema-layout-styles.rf.md`. In particular, do not confuse
+resource-area fragments inside a product-capability folder with a repo-wide
+`by-resource-area` layout. Moving schema root files changes generated output
+namespaces/import paths; ask whether the user wants a guidance-only profile
+change or an actual schema migration.
+Choose the protocol scenario before writing examples: API-only,
+async-only, or API + async with shared components such as
+enums and scalar value objects.
+
+Use `sumr kontract init` to set the profile during activation. Use
+`sumr kontract config` to show or update the current profile. For the current
+flag list and supported interactive choices, run `sumr kontract init --help` or
+`sumr kontract config --help`. Existing profile values stay unchanged unless a
+flag or interactive choice updates them.
+
+Activation also keeps local VS Code Material Icon associations in sync for
+`*.api.yml`, `*.api.yaml`, `*.async.yml`, and `*.async.yaml`.
+
 ## Sources
 
 | Field | Meaning |
 |---|---|
 | `name` | Stable source name used by `--source`. |
-| `input` | Directory scanned recursively for `*.openapi.yml`, `*.openapi.yaml`, `*.asyncapi.yml`, and `*.asyncapi.yaml`. |
+| `input` | Directory scanned recursively for `*.api.yml`, `*.api.yaml`, `*.async.yml`, and `*.async.yaml`. |
 | `targets` | One or more generated outputs. |
 
 Use `--source <name>` to scope validation or generation to one source.
@@ -65,10 +103,10 @@ Use `--target <name>` to scope generation to one target.
 | Client/SDK | `typescript-fetch` | TypeScript fetch SDK. |
 | Client/SDK | `typescript-axios` | TypeScript axios SDK. |
 | Client/SDK | `typescript-angular` | Angular SDK. |
-| Model | `typescript-models` | Framework-neutral model-only output. |
+| Model | `typescript-models` | Framework-model-only output. |
 
 Kontract is structured for more generator targets over time: runtime evidence,
-docs-ready OpenAPI artifacts, packaged API contracts, SDKs, mocks, contract
+docs-ready API schema artifacts, packaged API contracts, SDKs, mocks, contract
 tests, and breaking-change reports.
 
 ## `typescript-nestjs` options
@@ -83,18 +121,18 @@ tests, and breaking-change reports.
 `dtos` is the canonical spelling. `dto: true` is accepted as a compatibility
 alias and is normalized internally to `dtos: true`.
 
-Framework-neutral interfaces under `http/models/` and enums under `http/enums/`
-are emitted for OpenAPI object schemas regardless of the Zod/DTO flavor.
+Framework-interfaces under `http/models/` and enums under `http/enums/`
+are emitted for API schema object schemas regardless of the Zod/DTO flavor.
 
 Use `sdk: true` on a NestJS target when a backend service should call another
 generated HTTP API. Use a standalone `typescript-fetch`, `typescript-axios`, or
 `typescript-angular` target when a frontend/admin app should own its SDK output
 separately.
 
-## OpenAPI schema mode
+## API schema schema mode
 
 Standalone SDK and model targets default to `schemaMode: normalize`. In this
-mode, Kontract accepts real-world OpenAPI specs with inline operation request or
+mode, Kontract accepts real-world API schema specs with inline operation request or
 response schemas, hoists those schemas into generated component names in memory,
 and emits named TypeScript models.
 
@@ -115,10 +153,10 @@ generator:
 
 Kontract still recommends reusable component schemas for owned APIs because they
 produce stable names and cleaner docs. Normalization exists so customers can
-generate SDKs from external or imperfect OpenAPI specs without rewriting the API
+generate SDKs from external or imperfect API schema specs without rewriting the API
 description first.
 
-Use generic OpenAPI metadata for docs/runtime surfaces:
+Use generic API schema metadata for docs/runtime surfaces:
 
 ```yaml
 x-kontract-surface: public

package/ai/modules/kontract/resources/authoring/design-profile/api-styles.rf.md

@@ -0,0 +1,241 @@
+---
+category: reference
+name: api-styles
+title: HTTP Style Examples
+description: "API profile styles for Kontract examples, including path and component naming samples."
+label: HTTP Styles
+when: Choosing or explaining `kontract.guidance.profile.apiStyle`, HTTP paths, API schema components, or action-oriented endpoints
+order: 16
+---
+
+# HTTP Style Examples
+
+Use `kontract.guidance.profile.apiStyle` to choose the API examples an
+agent should produce. This is guidance only; it does not change generation.
+
+The `rpc-action` value means **action-oriented HTTP contract examples**. It does
+not mean the service implements a generic RPC framework. Use it for endpoints
+such as `/v1/bookings/{bookingId}/confirm`,
+`/v1/payments/refunds/{refundId}/process`, or a real JSON-RPC surface when one
+exists.
+
+| Style | Choose this when | Sample path | Sample component |
+|---|---|---|---|
+| `pragmatic-rest` | You want predictable REST without strict methodology overhead. | `/v1/orders/{orderId}/items` | `Order`, `CreateOrderBody` |
+| `resource-oriented` | You follow resource hierarchy and standard methods closely. | `/v1/publishers/{publisherId}/books/{bookId}` | `Book`, `ListBooksResponse` |
+| `json-api` | Clients expect JSON:API document, relationship, and sparse-field conventions. | `/articles/1/relationships/comments` | `ArticleResource`, `ArticleRelationship` |
+| `odata` | Consumers need OData-style query, filtering, and metadata conventions. | `/Products?$filter=price gt 10` | `ProductEntity`, `ProductCollection` |
+| `rpc-action` | The HTTP contract is action-first, command-like, or includes a real RPC endpoint; this does not require an RPC framework. | `/v1/bookings/{bookingId}/confirm` | `ConfirmBookingRequest`, `BookingConfirmationResult` |
+| `graphql-http` | HTTP mainly carries GraphQL operations. | `/graphql` with operation `GetOrder` | `GraphqlError`, `GetOrderVariables` |
+| `hypermedia-rest` | Clients navigate links and state transitions from representations. | `/v1/orders/{orderId}` with `links.cancel` | `OrderLinks`, `OrderRepresentation` |
+| `webhook-callback` | The contract documents callbacks or externally delivered HTTP events. | `/webhooks/order-created` | `OrderCreatedWebhook`, `WebhookAck` |
+| `mixed` | Multiple HTTP styles are intentional and documented by surface. | `/v1/orders` and `/graphql` | Style-specific names per surface |
+
+## Concrete snippets
+
+### `pragmatic-rest`
+
+Use resource paths and conventional operations without forcing one strict REST
+school.
+
+```yaml
+api: 3.1.0
+paths:
+  /v1/orders/{orderId}:
+    get:
+      operationId: getOrder
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Order"
+components:
+  schemas:
+    Order:
+      type: object
+      required: [id, status]
+```
+
+### `resource-oriented`
+
+Use nested resources, stable identifiers, and standard list/get/create/update/delete
+operations.
+
+```yaml
+api: 3.1.0
+paths:
+  /v1/publishers/{publisherId}/books/{bookId}:
+    get:
+      operationId: getPublisherBook
+      parameters:
+        - name: publisherId
+          in: path
+          required: true
+          schema: { type: string }
+        - name: bookId
+          in: path
+          required: true
+          schema: { type: string }
+```
+
+### `json-api`
+
+Use JSON:API document envelopes, resource objects, attributes, and relationships.
+
+```yaml
+api: 3.1.0
+paths:
+  /articles/{articleId}/relationships/comments:
+    get:
+      operationId: listArticleCommentRelationships
+components:
+  schemas:
+    ArticleResource:
+      type: object
+      required: [type, id, attributes]
+      properties:
+        type: { const: articles }
+        id: { type: string }
+        relationships:
+          $ref: "#/components/schemas/ArticleRelationships"
+```
+
+### `odata`
+
+Use OData-style collection names and query parameters for filtering, expansion,
+and selection.
+
+```yaml
+api: 3.1.0
+paths:
+  /Products:
+    get:
+      operationId: listProducts
+      parameters:
+        - name: $filter
+          in: query
+          schema: { type: string }
+        - name: $select
+          in: query
+          schema: { type: string }
+        - name: $expand
+          in: query
+          schema: { type: string }
+```
+
+### `rpc-action`
+
+Use action names when the operation is a business command, not natural resource
+CRUD.
+
+```yaml
+api: 3.1.0
+paths:
+  /v1/reports:generate:
+    post:
+      operationId: generateReport
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GenerateReportRequest"
+      responses:
+        "202":
+          description: Report generation accepted
+```
+
+### `graphql-http`
+
+Use one HTTP endpoint where request bodies carry GraphQL operations and variables.
+
+```yaml
+api: 3.1.0
+paths:
+  /graphql:
+    post:
+      operationId: executeGraphqlOperation
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [query]
+              properties:
+                query: { type: string }
+                variables: { type: object }
+```
+
+### `hypermedia-rest`
+
+Use representations that include links or allowed state transitions clients can
+follow.
+
+```yaml
+api: 3.1.0
+components:
+  schemas:
+    OrderRepresentation:
+      type: object
+      required: [id, status, links]
+      properties:
+        id: { type: string }
+        status: { type: string }
+        links:
+          type: object
+          properties:
+            cancel:
+              $ref: "#/components/schemas/LinkAction"
+```
+
+### `webhook-callback`
+
+Use inbound HTTP event contracts with explicit event names, payloads, and
+acknowledgement responses.
+
+```yaml
+api: 3.1.0
+paths:
+  /webhooks/order-created:
+    post:
+      operationId: receiveOrderCreatedWebhook
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OrderCreatedWebhook"
+      responses:
+        "202":
+          description: Webhook accepted
+```
+
+### `mixed`
+
+Use separate surfaces when a product intentionally exposes more than one HTTP
+style.
+
+```yaml
+api: 3.1.0
+paths:
+  /v1/orders:
+    get:
+      tags: [pragmatic-rest]
+      operationId: listOrders
+  /graphql:
+    post:
+      tags: [graphql-http]
+      operationId: executeGraphqlOperation
+  /v1/reports:generate:
+    post:
+      tags: [rpc-action]
+      operationId: generateReport
+```
+
+## Guardrails
+
+- Do not use `rpc-action` as proof that an application has implemented an RPC
+  framework.
+- If `apiStyle: mixed`, label which HTTP surface uses which style before adding
+  examples.
+- Keep path and component examples aligned to the selected directory structure
+  style from `schema-layout-styles.rf.md`.

package/ai/modules/kontract/resources/authoring/design-profile/async-styles.rf.md

@@ -0,0 +1,134 @@
+---
+category: reference
+name: async-styles
+title: async schema Style Examples
+description: "async profile styles for Kontract examples, including channel/address and message naming samples."
+label: async schema Styles
+when: Choosing or explaining `kontract.guidance.profile.asyncStyle`, messaging channels, async schema addresses, or message names
+order: 17
+---
+
+# async schema Style Examples
+
+Use `kontract.guidance.profile.asyncStyle` to choose the async
+examples an agent should produce. This is guidance only; it does not change
+generation.
+
+| Style | Choose this when | Sample channel/address | Sample message |
+|---|---|---|---|
+| `command-event` | You separate imperative commands from past-tense events. | `cmd.billing.invoices.create`, `evt.billing.invoices.created` | `CreateInvoiceCommand`, `InvoiceCreatedEvent` |
+| `event-driven` | Services primarily publish facts that subscribers react to. | `billing.invoice.created` | `InvoiceCreated` |
+| `request-reply` | Messaging models query/reply or command/reply interactions. | `qry.catalog.products.get` | `GetProductQuery`, `ProductReply` |
+| `cloud-events` | Events must follow CloudEvents envelope semantics. | `com.example.invoice.created` | `InvoiceCreatedCloudEvent` |
+| `mixed` | Multiple messaging styles are intentional and documented by channel family. | `cmd.*`, `evt.*`, and CloudEvents topics | Names match each family |
+
+## Concrete snippets
+
+### `command-event`
+
+Separate imperative commands from fact events and name the reply path explicitly.
+
+```yaml
+async: 3.0.0
+channels:
+  createInvoice:
+    address: cmd.billing.invoices.create
+    messages:
+      createInvoiceCommand:
+        $ref: "#/components/messages/CreateInvoiceCommand"
+  invoiceCreated:
+    address: evt.billing.invoices.created
+    messages:
+      invoiceCreatedEvent:
+        $ref: "#/components/messages/InvoiceCreatedEvent"
+```
+
+### `event-driven`
+
+Publish facts that subscribers can react to without coupling to the producer
+workflow.
+
+```yaml
+async: 3.0.0
+channels:
+  invoiceCreated:
+    address: billing.invoice.created
+    messages:
+      invoiceCreated:
+        $ref: "#/components/messages/InvoiceCreated"
+operations:
+  publishInvoiceCreated:
+    action: send
+    channel:
+      $ref: "#/channels/invoiceCreated"
+```
+
+### `request-reply`
+
+Model query or command messages together with the reply channel and payload.
+
+```yaml
+async: 3.0.0
+channels:
+  getProduct:
+    address: qry.catalog.products.get
+    messages:
+      getProductQuery:
+        $ref: "#/components/messages/GetProductQuery"
+  getProductReply:
+    address: qry.catalog.products.get.reply
+    messages:
+      productReply:
+        $ref: "#/components/messages/ProductReply"
+```
+
+### `cloud-events`
+
+Wrap events in CloudEvents-compatible metadata when consumers expect that
+envelope.
+
+```yaml
+async: 3.0.0
+components:
+  messages:
+    InvoiceCreatedCloudEvent:
+      payload:
+        type: object
+        required: [specversion, type, source, id, data]
+        properties:
+          specversion: { const: "1.0" }
+          type: { const: com.example.billing.invoice.created }
+          source: { type: string }
+          data:
+            $ref: "#/components/schemas/InvoiceCreated"
+```
+
+### `mixed`
+
+Keep message families explicit when one system has commands, events, and
+request/reply contracts.
+
+```yaml
+async: 3.0.0
+channels:
+  createInvoice:
+    address: cmd.billing.invoices.create
+  invoiceCreated:
+    address: evt.billing.invoices.created
+  getInvoice:
+    address: qry.billing.invoices.get
+components:
+  messages:
+    CreateInvoiceCommand: {}
+    InvoiceCreatedEvent: {}
+    GetInvoiceQuery: {}
+```
+
+## Guardrails
+
+- If `asyncStyle: mixed`, label which channel family uses which style before
+  adding examples.
+- Keep channel and message examples aligned to the selected directory structure
+  style from `schema-layout-styles.rf.md`.
+- Do not move async schema roots only because the messaging style changed; profile
+  values are guidance-only.

package/ai/modules/kontract/resources/authoring/design-profile/overview.md

@@ -0,0 +1,64 @@
+---
+name: design-profile
+title: Contract Design Profile
+description: "How Kontract profile values guide HTTP, async schema, and schema directory examples without changing generation."
+tags: [kontract, design-profile, http, asyncapi, schema-layout]
+---
+
+# Contract Design Profile
+
+`sumr kontract init` writes a guidance-only profile to `sumr.yaml`.
+`sumr kontract config` shows or updates it later without hand-editing YAML:
+
+```yaml
+kontract:
+  guidance:
+    profile:
+      apiStyle: pragmatic-rest
+      asyncStyle: command-event
+      schemaLayoutStyle: by-product-capability
+```
+
+The profile guides docs and AI examples. It does not change generator output,
+API schema validation, async schema validation, or application architecture.
+
+```bash
+sumr kontract config
+sumr kontract config --api-style rpc-action --async-style cloud-events
+```
+
+## Profile axes
+
+| Config key | Reader-facing meaning | Axis reference |
+|---|---|---|
+| `apiStyle` | API path and component example style. | `api-styles.rf.md` |
+| `asyncStyle` | async schema channel/address and message example style. | `async-styles.rf.md` |
+| `schemaLayoutStyle` | Schema layout style for schema file and folder examples. | `schema-layout-styles.rf.md` |
+
+Read the axis-specific references before writing examples. Do not infer file
+moves from the profile alone: the profile is guidance-only.
+
+## CLI and YAML names
+
+Use `schemaLayoutStyle` in `sumr.yaml` and `--schema-layout-style` in the CLI.
+Do not use organization wording for this axis.
+
+## Safe interpretation
+
+- HTTP examples must follow `apiStyle`.
+- async schema examples must follow `asyncStyle`, but only when the repo has
+  async schema sources/targets or the user asks for messaging contracts.
+- Schema file/folder examples must follow `schemaLayoutStyle`, described as the
+  schema layout style.
+- If the repo is API-only, keep examples API-only; do not add
+  `*.async.yml`, channels, messages, or `messages/` folders only because the
+  profile has an `asyncStyle` default.
+- If the repo is async-only, keep examples async-only; do not add
+  `*.api.yml`, paths, parameters, or HTTP responses only because the profile
+  has an `apiStyle` default.
+- If the repo has both protocols, keep API schema and async schema roots and
+  protocol-specific folders separate. Share only components with
+  identical meaning, especially enums and scalar value objects.
+- If an agent recommends moving root specs, it must call out that generated
+  output namespaces/import paths can change because Kontract mirrors root spec
+  paths under the configured source input directory.