@sumrco/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sumrco/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "SUMR public CLI",
   "type": "module",
   "repository": {

package/ai/modules/kontract/resources/language-sdk-generator-extension.rf.md

@@ -1,62 +0,0 @@
----
-category: reference
-name: language-sdk-generator-extension
-title: Language SDK Generator Extension
-description: "How Kontract should add future non-TypeScript SDK generators such as Java or Rust."
-label: Language SDK Generator Extension
-when: Researching or implementing a new Kontract SDK generator for another language
-order: 47
----
-
-# Language SDK Generator Extension
-
-Kontract can add Java, Rust, or other SDK generators, but only as explicit
-generator types after research and tests prove the output is useful.
-
-## Current support
-
-Implemented generators:
-
-- `typescript-nestjs`
-- `asyncapi-nats`
-- `typescript-fetch`
-- `typescript-axios`
-- `typescript-angular`
-- `typescript-models`
-
-Java and Rust are not implemented yet. Config such as `type: java` or
-`type: rust` must fail until a real generator exists.
-
-## Add a new language generator
-
-Use this sequence:
-
-1. Research mature public generators for the target language and record lessons
-   in `resources/`.
-2. Add the generator type to `src/types/contracts.types.ts`.
-3. Add config parsing and allowed options in `src/lib/sumr-yaml.ts`.
-4. Add dependency warnings in `src/cli/dependency-check.ts` only when generated
-   output requires runtime packages in the consumer repo.
-5. Add a generator implementation under `src/generators/openapi/<language>/` or
-   a shared SDK emitter if the language can reuse one.
-6. Wire generation planning in `src/cli/generate-plan.ts`.
-7. Add tests that prove config parsing, output shape, unsafe-schema failures,
-   and generated file roots.
-8. Update `README.md`, `docs/**`, `resources/**`, and regenerate AI resources
-   with `bun run sync`.
-
-## Test coverage required
-
-Every generator must have at least:
-
-- a config parsing test;
-- a direct generation test for expected root files;
-- an edge-case test for reserved names or language keywords;
-- query array serialization coverage for HTTP SDKs;
-- enum and `additionalProperties` coverage where the language supports them;
-- a rejection test for unsupported schema features such as unsafe polymorphism;
-- a catalog coverage test so the documented generator list and implemented list
-  stay aligned.
-
-Do not add a generator type first and fill behavior later. Unsupported language
-targets should stay rejected until they can generate useful, validated output.

package/ai/modules/kontract/resources/openapi-generator-lessons.rf.md

@@ -1,61 +0,0 @@
----
-category: reference
-name: openapi-generator-lessons
-title: OpenAPI Generator Bug Lessons
-description: "Hardening lessons Kontract applies from public OpenAPI Generator NestJS/TypeScript bug reports. Use when reviewing generated output risks, query parameters, inline schemas, and strict TypeScript compatibility."
-label: OpenAPI Generator Lessons
-when: Reviewing Kontract specs or generator changes for known OpenAPI/NestJS codegen failure modes
-order: 45
----
-
-# OpenAPI Generator Bug Lessons
-
-Kontract learns from public OpenAPI/NestJS generator bugs without inheriting their
-architecture. These lessons are guardrails for spec authors, reviewers, and AI agents
-working on generated contracts.
-
-## Core lessons
-
-- **Preserve query parameter semantics.** Optional query params stay optional, array query
-  params serialize as repeated keys, and enum query params use generated enum symbols instead
-  of raw literal imports.
-- **Do not let wire names become unsafe local variables.** Parameter names such as `from`,
-  `class`, and `default` must remain valid wire keys while generated local identifiers are
-  safe TypeScript names.
-- **Prefer component `$ref` schemas over anonymous inline operation models.** Kontract rejects
-  inline request/response schemas because anonymous model naming commonly causes duplicate
-  `InlineObject` outputs and unstable imports.
-- **Generate maps deliberately.** `additionalProperties` map schemas must preserve named
-  properties and typed catch-all/index-signature values consistently across Zod, DTOs, models,
-  and SDK output. Unsupported `oneOf`, `anyOf`, `not`, and discriminators should produce clear
-  errors instead of partially generated code with missing symbols such as `AnyType` or
-  `InnerEnum`.
-- **Keep NestJS ownership boundaries clean.** Kontract emits contracts, DTOs, models, swagger
-  metadata, and SDK clients. Application modules, controllers, providers, and DI wiring stay in
-  the consuming NestJS app.
-- **Compile generated code under strict TypeScript assumptions.** Generated output should avoid
-  dangling imports, deprecated Nest HTTP client imports, stale `basePath` globals, `Map` headers
-  where records are expected, and framework symbols that were never emitted.
-- **Stay Bun-native.** Kontract does not depend on Java, Docker images, downloaded generator
-  binaries, or template folders at generation time.
-
-## Spec authoring rules
-
-- Put reusable request/response bodies, parameters, enums, and object fragments under
-  `components` and reference them with `$ref`.
-- Encode validation constraints in the OpenAPI schema (`minLength`, `maxLength`, `minimum`,
-  `maximum`, `pattern`, `format`) so DTO/Zod output can enforce them.
-- Use `additionalProperties` when the payload is intentionally map-shaped. Prefer typed map values
-  over `additionalProperties: true`; Kontract preserves named fields and emits a safe unknown
-  catch-all when the spec intentionally allows arbitrary values.
-- For repeated query values, use `type: array` with scalar `items`; generated SDKs must not
-  collapse values into comma-separated strings.
-
-## Reviewer checklist
-
-- Generated files include the auto-generated header and are not hand-edited.
-- Query DTOs and SDK request types preserve optionality from the spec.
-- No generated file contains `any`, `AnyType`, `InlineObject`, `InnerEnum`, `queryParameters`,
-  deprecated `HttpService`, stale `basePath`, or unsafe `apiKeys` access.
-- Operation schemas reference named components instead of inline request/response objects.
-- Unsupported schema features fail before any consumer repo is left with partial broken output.

package/ai/modules/kontract/resources/spec-layout.rf.md

@@ -1,275 +0,0 @@
----
-category: reference
-name: spec-layout
-title: Spec File Layout
-description: "Required folder and file conventions for Kontract OpenAPI/AsyncAPI source specs."
-label: Spec Layout
-when: Creating or moving API spec files, adding a shared base spec, or debugging why a spec is not picked up
-order: 10
----
-
-# Spec File Layout
-
-Kontract discovers specs by filename convention under the configured schema
-directory (default `schema/`).
-
-```text
-schema/
-  recipes.openapi.yml           ← one OpenAPI doc per service/domain
-  recipes.asyncapi.yml          ← one AsyncAPI doc per service/domain
-  recipes.schema.yml            ← neutral suffix; detected by openapi:/asyncapi:
-  base.yml                      ← shared components, referenced via $ref
-  bookstore/
-    bookstore.openapi.yml       ← root entrypoint
-    bookstore.asyncapi.yml      ← root entrypoint
-    paths/catalog.yml           ← OpenAPI path fragments
-    messages/events.yml         ← AsyncAPI channel/message fragments
-    models/shared.yml          ← protocol-neutral model fragments
-```
-
-## Rules
-
-- OpenAPI specs end in `*.openapi.yml` / `*.openapi.yaml`.
-- AsyncAPI specs end in `*.asyncapi.yml` / `*.asyncapi.yaml`.
-- Use `*.schema.yml` / `*.schema.yaml` when a domain folder already makes the
-  protocol obvious less useful than the business surface name. Kontract reads
-  the file marker and treats `openapi:` as OpenAPI and `asyncapi:` as AsyncAPI.
-- Discovery is recursive; `base.yml` is skipped as an entry point.
-- Service output paths mirror nested spec paths under the configured source
-  input directory.
-- A root `*.openapi.yml` or `*.asyncapi.yml` may reference plain `.yml`
-  fragments for paths, messages, parameters, and schemas. Kontract bundles the
-  root before generation when it finds external `$ref` links.
-- OpenAPI and AsyncAPI roots may share neutral model fragments when the shapes
-  mean the same thing for HTTP and messaging. Keep protocol-specific path,
-  operation, parameter, channel, and message metadata in separate fragments.
-- Nested `*.schema.yml` files are grouped by their first folder. This supports a
-  DDD layout where the folder is the domain and each file is a subdomain surface:
-
-  ```text
-  schema/
-    recipes/
-      catalog.schema.yml        ← OpenAPI
-      publishing.schema.yml     ← AsyncAPI
-  ```
-
-  Both files generate under `contracts/recipes/`.
-- Use nested domain/subdomain paths when one root file would mix independently
-  owned API surfaces; see the scope and splitting reference for line-count
-  thresholds and naming rules.
-- Use comments only as editor navigation markers. Comments may label groups such
-  as `Catalog paths` or `Response schemas`, but they must not explain endpoint
-  behavior or replace `summary` / `description`.
-- Share common schemas through `$ref` into `base.yml`. Do **not** duplicate
-  schemas across specs and do **not** merge by hand-mutating parsed JSON.
-- Prefer a `schema/shared/` folder for cross-domain components such as common
-  parameters, error responses, pagination, scalar constraints, response envelope
-  fragments, schedules, and reusable config objects.
-- The NATS namespace comes from the AsyncAPI `info.title`, not the filename —
-  set `info.title` deliberately.
-- Multi-file specs are bundled automatically (OpenAPI via Redocly core in-process
-  with CLI fallback, AsyncAPI via `@asyncapi/cli bundle`); keep `$ref` paths
-  repo-relative.
-
-## Split root-entrypoint layout
-
-Use this layout when one product domain should generate as one contract package,
-but the root files are getting too large:
-
-```text
-schema/
-  bookstore/
-    bookstore.openapi.yml
-    bookstore.asyncapi.yml
-    components/
-      parameters.yml
-    paths/
-      books.yml
-      authors.yml
-    messages/
-      books.yml
-      authors.yml
-    models/
-      shared.yml
-      books.yml
-      authors.yml
-```
-
-The root files stay small and readable. Fragment files are plain `.yml` because
-they are not standalone OpenAPI or AsyncAPI documents.
-
-If a root file needs many visual section markers to stay readable, split the
-internals into domain/subdomain fragments before adding more comments.
-
-```yaml
-# schema/bookstore/bookstore.openapi.yml
-openapi: 3.0.3
-info:
-  title: Bookstore Contracts
-  version: 1.0.0
-paths:
-  /books:
-    $ref: ./paths/books.yml#/paths/~1books
-components:
-  schemas:
-    Book:
-      $ref: ./models/books.yml#/Book
-    PaginatedBooks:
-      $ref: ./models/books.yml#/PaginatedBooks
-```
-
-```yaml
-# schema/bookstore/paths/books.yml
-paths:
-  /books:
-    get:
-      operationId: listBooks
-      responses:
-        "200":
-          description: Paginated book list.
-          content:
-            application/json:
-              schema:
-                $ref: ../models/books.yml#/PaginatedBooks
-```
-
-```yaml
-# schema/bookstore/bookstore.asyncapi.yml
-asyncapi: 3.0.0
-info:
-  title: Bookstore
-  version: 1.0.0
-channels:
-  listBooks:
-    $ref: ./messages/books.yml#/channels/listBooks
-  listBooksReply:
-    $ref: ./messages/books.yml#/channels/listBooksReply
-operations:
-  listBooks:
-    $ref: ./messages/books.yml#/operations/listBooks
-components:
-  messages:
-    ListBooksQuery:
-      $ref: ./messages/books.yml#/messages/ListBooksQuery
-    PaginatedBooksReply:
-      $ref: ./messages/books.yml#/messages/PaginatedBooksReply
-  schemas:
-    ListBooksQuery:
-      $ref: ./models/books.yml#/ListBooksQuery
-    PaginatedBooks:
-      $ref: ./models/books.yml#/PaginatedBooks
-```
-
-```yaml
-# schema/bookstore/messages/books.yml
-channels:
-  listBooks:
-    address: qry.bookstore.books.list
-    messages:
-      listBooksQuery:
-        $ref: ./books.yml#/messages/ListBooksQuery
-  listBooksReply:
-    address: qry.bookstore.books.list.reply
-    messages:
-      paginatedBooksReply:
-        $ref: ./books.yml#/messages/PaginatedBooksReply
-operations:
-  listBooks:
-    action: receive
-    channel:
-      $ref: "#/channels/listBooks"
-    messages:
-      - $ref: "#/channels/listBooks/messages/listBooksQuery"
-    reply:
-      channel:
-        $ref: "#/channels/listBooksReply"
-      messages:
-        - $ref: "#/channels/listBooksReply/messages/paginatedBooksReply"
-messages:
-  ListBooksQuery:
-    payload:
-      $ref: ../models/books.yml#/ListBooksQuery
-  PaginatedBooksReply:
-    payload:
-      $ref: ../models/books.yml#/PaginatedBooks
-```
-
-Shared schemas can be referenced by both roots when they carry the same business
-meaning:
-
-```yaml
-# schema/bookstore/models/shared.yml
-BookSlug:
-  type: string
-  minLength: 1
-  maxLength: 120
-  pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-```
-
-```yaml
-# schema/bookstore/models/books.yml
-Book:
-  type: object
-  required: [id, slug, title]
-  properties:
-    id:
-      type: string
-      format: uuid
-    slug:
-      $ref: ./shared.yml#/BookSlug
-    title:
-      type: string
-      minLength: 1
-```
-
-Do not put graph, routing, or protocol behavior into shared model fragments.
-Share only business payload shapes.
-
-## OpenAPI authoring rules
-
-- Put reusable HTTP payloads in `components.schemas`.
-- Operation request/response schemas should reference components with `$ref`.
-  Inline operation schemas are rejected so generated DTO/model names stay stable.
-- Use operation `summary` to name the action. Use `description` to explain
-  outcome, scope, caller context, constraints, or next steps; do not repeat the
-  summary in sentence form.
-- Avoid tag echo. If the API docs already show a tag such as `Playbook` or
-  `Accounts`, omit that word from the summary unless the operation would become
-  ambiguous.
-- Route public or developer-facing `summary`, `description`, parameter, schema,
-  and response text through the repo's copywriter/microcopy standard before
-  validating.
-- Prefer explicit object schemas over anonymous nested shapes when a payload is
-  shared by multiple operations.
-- If multiple responses repeat the same envelope fields, extract the envelope
-  fragment and compose concrete responses with supported object `allOf`.
-- If multiple schemas repeat the same regex or scalar validation, extract a
-  named scalar component and reference it.
-- Use stable `operationId` values. They become Swagger metadata constants such
-  as `SWG_LIST_RECIPES`.
-- Unsupported composition features (`oneOf`, `anyOf`, `not`, `discriminator`)
-  must either be modeled differently or implemented in Kontract before use.
-
-## AsyncAPI operation classification
-
-| AsyncAPI shape      | Generated client kind |
-|---------------------|-----------------------|
-| `receive` + `reply` | Query                 |
-| `receive`           | Command               |
-| `send`              | Event                 |
-
-Run `sumr kontract validate` after any layout change to confirm specs still
-resolve before generating.
-
-## AsyncAPI copy rules
-
-AsyncAPI `title`, `summary`, and `description` fields can appear in generated
-docs, SDK docs, and AI answers. Write them with the same copy gate as OpenAPI:
-
-- `title` names the message or operation.
-- `summary` states the job or event in one concise sentence.
-- `description` adds context only when the outcome, constraint, or event
-  semantics need more detail.
-- Do not repeat the channel, operation id, schema key, or title in the summary.
-- Keep transport terms such as subject, payload, NATS, command, and query only
-  when the reader needs that exact implementation detail.

package/ai/modules/kontract/resources/team-members/contract-author.tm.md

@@ -1,60 +0,0 @@
----
-category: team-member
-name: contract-author
-title: Contract Author
-description: "Owns API spec authoring and Kontract regeneration discipline. Use when changing OpenAPI/AsyncAPI specs, validating, regenerating, or reviewing generated contract diffs."
-modelTier: reasoning
-access: write
-channels:
-  codex:
-    sandbox_mode: workspace-write
----
-
-# Contract Author
-
-You own the API contract source of truth for this repo. You change YAML specs
-and let Kontract generate the TypeScript — you never hand-write or hand-patch
-generated contracts.
-
-Apply the generated **sumr-kontract-usage** skill, plus the configuration,
-spec-layout, schema-reuse, scope-and-splitting, and generated-output references,
-before acting.
-
-## Responsibilities
-
-- Translate API requirements into OpenAPI/AsyncAPI specs under `schema/`.
-- After writing or updating any `*.openapi.yml` / `*.asyncapi.yml` file, review
-  it against Kontract reuse, layout, and generation rules before validating.
-- Route changed public or developer-facing summaries, descriptions, parameter
-  descriptions, response descriptions, message titles, and message summaries
-  through the repo's copywriter/microcopy standard before generation.
-- Keep shared shapes in shared component files and reference them with `$ref`.
-- Keep specs domain-aligned and reviewable: use domain/subdomain paths, split
-  oversized files at documented thresholds, and avoid generic `common` buckets
-  for unrelated concepts.
-- Use comments only as visual editor landmarks. Do not explain endpoint behavior
-  with comments; use OpenAPI/AsyncAPI descriptions for that.
-- Name schemas from domain meaning first, using operation-specific response
-  names only when the shape belongs to one operation.
-- Proactively spot duplicated envelope fields, pagination metadata, error
-  schemas, path/query params, regex scalar constraints, schedules, and config
-  objects before generating.
-- Prefer supported object `allOf` composition when a concrete response extends
-  a shared base envelope.
-- Run `sumr kontract validate` then `sumr kontract generate` for every change.
-- Review the generated diff for correctness and unintended breakage.
-- If a generated diff creates many near-identical DTO/model files, pause and
-  propose a spec-level shared component refactor.
-- Keep spec + regenerated output committed together.
-- When generated files are missing, check `sumr.yaml` target options and the
-  installed `SUMR Kontract module` version before changing application code.
-
-## Boundaries
-
-- Never edit files under the generated `contracts/` output.
-- Never hand-write Zod schemas, DTOs, NATS subjects, or clients that Kontract owns.
-- Do not introduce a second source of truth; the spec is authoritative.
-- Do not over-share unrelated concepts only because their current fields look
-  similar; shared components must have the same product meaning and owner.
-- Flag breaking contract changes for human review before commit.
-- Scope `--clean` to the intended source/target in consumer repos.