@sumrco/cli 0.2.1 → 0.3.1

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/authoring/configuration.rf.md

@@ -0,0 +1,220 @@
+---
+category: reference
+name: configuration
+title: Kontract Configuration
+description: "How `sumr.yaml` configures Kontract sources, targets, generator types, and NestJS output options."
+label: Configuration
+when: Adding a Kontract target, debugging missing generated files, or comparing generated output across repos
+order: 15
+---
+
+# Kontract Configuration
+
+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
+      targets:
+        - name: backend
+          output: backend/src/shared/models
+          generator:
+            type: typescript-nestjs
+            zod: true
+            dtos: true
+            sdk: true
+        - name: frontend
+          output: frontend/src/shared/api
+          generator:
+            type: typescript-fetch
+            schemaMode: normalize
+            modelPropertyNaming: original
+            paramNaming: original
+            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 `*.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.
+
+## Targets
+
+| Field | Meaning |
+|---|---|
+| `name` | Stable target name used by `--target`. |
+| `output` | Root directory for generated output. Treat this folder as generated/read-only. |
+| `generator.type` | Generator family. |
+
+Use `--target <name>` to scope generation to one target.
+
+## Generator types
+
+| Category | Type | Outputs |
+|---|---|---|
+| Server/framework | `typescript-nestjs` | Zod DTOs, class-validator DTOs, models, Swagger metadata, generated `ApiDoc` decorators. |
+| Messaging | `asyncapi-nats` | NATS subjects, message schemas, server interfaces, and clients. |
+| Client/SDK | `typescript-fetch` | TypeScript fetch SDK. |
+| Client/SDK | `typescript-axios` | TypeScript axios SDK. |
+| Client/SDK | `typescript-angular` | Angular SDK. |
+| Model | `typescript-models` | Framework-model-only output. |
+
+Kontract is structured for more generator targets over time: runtime evidence,
+docs-ready API schema artifacts, packaged API contracts, SDKs, mocks, contract
+tests, and breaking-change reports.
+
+## `typescript-nestjs` options
+
+| Option | Output |
+|---|---|
+| `zod: true` | Emits `http/zod/*.contract.ts` with Zod schemas and `createZodDto()` classes. |
+| `dtos: true` | Emits `http/dto/*.dto.ts`; also keeps the compatibility behavior of emitting `http/swagger.ts`. |
+| `swagger: true` | Emits per-service `http/swagger.ts` operation metadata and one shared `shared/http/decorators/api-doc.ts` helper for NestJS controllers. |
+| `sdk: true` | Emits a fetch-based `http/sdk/` client that reuses the target's `http/models/` and `http/enums/` types. |
+
+`dtos` is the canonical spelling. `dto: true` is accepted as a compatibility
+alias and is normalized internally to `dtos: true`.
+
+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.
+
+## API schema schema mode
+
+Standalone SDK and model targets default to `schemaMode: normalize`. In this
+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.
+
+Use `schemaMode: strict` when the source spec is product-owned and should fail
+fast unless operation request/response schemas use reusable `$ref` components.
+
+```yaml
+generator:
+  type: typescript-fetch
+  schemaMode: normalize # default for SDK/model targets
+```
+
+```yaml
+generator:
+  type: typescript-fetch
+  schemaMode: strict
+```
+
+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 API schema specs without rewriting the API
+description first.
+
+Use generic API schema metadata for docs/runtime surfaces:
+
+```yaml
+x-kontract-surface: public
+security: []
+```
+
+`x-kontract-surface` values are consumer-defined strings. SUMR uses `public`,
+`app`, `admin`, and `internal`; another product might use `partner`, `mobile`,
+or `marketplace`.
+
+## Common debugging cases
+
+### `http/dto/`, `http/swagger.ts`, or `shared/http/decorators/api-doc.ts` is missing
+
+Check both:
+
+1. The target config has `generator.type: typescript-nestjs` and `dtos: true`.
+   `dto: true` is also accepted, but prefer `dtos` in new config. If you use
+   Zod without class-validator DTOs, set `swagger: true` explicitly.
+2. The installed `SUMR Kontract module` version includes Swagger/ApiDoc support.
+
+If two configs generate identical output and both miss `dto/` + `swagger.ts`,
+the likely issue is the generator version being executed, not the consumer
+repo's config.
+
+### `http/zod/` is missing
+
+Check that the NestJS target has `zod: true` or that Zod generation has not been
+explicitly disabled.
+
+### `http/sdk/` is missing
+
+Check that the NestJS target has `sdk: true`. Standalone SDK generator targets
+emit service folders with `models.ts`, `runtime.ts`, and `api.ts`; the NestJS
+composed SDK emits under `http/sdk/` and imports types from existing
+`http/models/` and `http/enums/`.
+
+### Generated files are stale
+
+Run a scoped clean generation:
+
+```bash
+sumr kontract generate --source api --target backend --clean
+```
+
+Prefer scoping `--clean` in large repos so only the intended generated output
+and selected Kontract cache are removed before regeneration.
+
+### Warm generation is still slow
+
+Kontract stores incremental manifests under `.sumr-cache/kontract`. An unchanged
+warm run should skip unchanged services before parse/emit and should not run a
+formatter subprocess.
+
+If warm runs regenerate everything, check for:
+
+1. generated files being manually edited or deleted;
+2. changing generator config in `sumr.yaml`;
+3. a changed installed `SUMR Kontract module` version;
+4. ambiguous or remote `$ref` usage that forces the safe path;
+5. `--clean`, which intentionally clears selected output and cache state.

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.