@sumrco/cli 0.2.1 → 0.3.1

package/package.json

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

package/ai/modules/kontract/resources/configuration.rf.md

@@ -1,123 +0,0 @@
----
-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 source points at a
-schema directory; each target chooses an output directory and generator.
-
-```yaml
-kontract:
-  sources:
-    - name: api
-      input: schema
-      targets:
-        - name: backend
-          output: backend/src/shared/models
-          generator:
-            type: typescript-nestjs
-            zod: true
-            dtos: true
-        - name: frontend
-          output: frontend/src/shared/api
-          generator:
-            type: typescript-fetch
-            modelPropertyNaming: original
-            paramNaming: original
-            stringEnums: true
-```
-
-## Sources
-
-| Field | Meaning |
-|---|---|
-| `name` | Stable source name used by `--source`. |
-| `input` | Directory scanned recursively for `*.openapi.yml`, `*.openapi.yaml`, `*.asyncapi.yml`, and `*.asyncapi.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
-
-| Type | Purpose |
-|---|---|
-| `typescript-nestjs` | Backend HTTP contracts for NestJS services. |
-| `asyncapi-nats` | NATS subjects, message schemas, server interfaces, and clients. |
-| `typescript-fetch` | TypeScript fetch SDK. |
-| `typescript-axios` | TypeScript axios SDK. |
-| `typescript-angular` | Angular SDK. |
-| `typescript-models` | Framework-neutral model-only output. |
-
-## `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` plus `http/swagger.ts` operation metadata. |
-
-`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.
-
-## Common debugging cases
-
-### `http/dto/` or `http/swagger.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.
-2. The installed `SUMR Kontract module` version includes DTO/swagger 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.
-
-### 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/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/schema-reuse.rf.md

@@ -1,233 +0,0 @@
----
-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."
-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
----
-
-# Schema Reuse and Shared Components
-
-Kontract works best when the spec is designed like a product API, not like a
-collection of copied YAML snippets. If the same concept appears in multiple
-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.
-
-## What to share
-
-Prefer shared components for concepts that mean the same thing everywhere:
-
-- scalar primitives: UUIDs, ISO dates, slugs, URLs, MIME types, time strings;
-- path/query parameters: `id`, `recipeId`, pagination, date ranges;
-- standard error responses and error body schemas;
-- pagination metadata;
-- common response envelope fields such as `success`, `timestamp`, `path`, and
-  optional `message`;
-- weekly schedules and reusable time-slot shapes;
-- repeated configuration objects, such as measurement units, recipe step labels,
-  display colors, notification settings, or payment settings when they truly
-  share semantics.
-
-Example shared scalar and parameter file:
-
-```yaml
-# schema/shared/common.yml
-components:
-  schemas:
-    UuidString:
-      type: string
-      format: uuid
-    ImageMimeType:
-      type: string
-      pattern: '^image\/(jpeg|png|webp|gif)$'
-    PaginationMeta:
-      type: object
-      required: [page, pageSize, pageCount, total]
-      properties:
-        page:
-          type: integer
-          minimum: 1
-        pageSize:
-          type: integer
-          minimum: 1
-        pageCount:
-          type: integer
-          minimum: 0
-        total:
-          type: integer
-          minimum: 0
-  parameters:
-    id:
-      name: id
-      in: path
-      required: true
-      schema:
-        $ref: '#/components/schemas/UuidString'
-```
-
-Use those components from service specs:
-
-```yaml
-parameters:
-  - $ref: ../shared/common.yml#/components/parameters/id
-content:
-  application/json:
-    schema:
-      $ref: ../shared/common.yml#/components/schemas/ImageMimeType
-```
-
-## Response envelopes
-
-If every endpoint repeats the same envelope fields, do not retype them in every
-schema. Put the shared part in a component and compose concrete responses with
-`allOf`.
-
-```yaml
-# schema/shared/common.yml
-components:
-  schemas:
-    SuccessResponseBase:
-      type: object
-      required: [success, timestamp, path]
-      properties:
-        success:
-          type: boolean
-        timestamp:
-          type: string
-          format: date-time
-        path:
-          type: string
-        message:
-          type: string
-```
-
-```yaml
-# schema/recipes/catalog.openapi.yml
-components:
-  schemas:
-    RecipesFindOneResponse:
-      allOf:
-        - $ref: ../shared/common.yml#/components/schemas/SuccessResponseBase
-        - type: object
-          required: [data]
-          properties:
-            data:
-              $ref: '#/components/schemas/RecipeResponse'
-```
-
-Use the same pattern for paginated responses:
-
-```yaml
-components:
-  schemas:
-    RecipesFindAllResponse:
-      allOf:
-        - $ref: ../shared/common.yml#/components/schemas/SuccessResponseBase
-        - type: object
-          required: [data]
-          properties:
-            data:
-              type: array
-              items:
-                $ref: '#/components/schemas/RecipeResponse'
-            meta:
-              $ref: ../shared/common.yml#/components/schemas/PaginationMeta
-```
-
-Kontract supports object `allOf` composition by flattening supported object refs
-and inline object parts. Today this mainly reduces YAML duplication and contract
-semantic drift. It may still emit concrete generated DTO/model properties per
-response until the generator grows preserved composition or shared-output
-emission.
-
-## Schedules and repeated nested objects
-
-If several features define the same day-of-week schedule or time-slot object,
-share the object definitions instead of duplicating each day shape.
-
-```yaml
-# schema/shared/scheduling.yml
-components:
-  schemas:
-    WeeklyTimeSlot:
-      type: object
-      required: [from, to]
-      properties:
-        from:
-          type: string
-          pattern: '^(0[6-9]|1\d|2[0-3]):[0-5]\d$'
-        to:
-          type: string
-          pattern: '^(0[6-9]|1\d|2[0-3]):[0-5]\d$'
-    WeeklySchedule:
-      type: object
-      properties:
-        sunday:
-          type: array
-          items:
-            $ref: '#/components/schemas/WeeklyTimeSlot'
-        monday:
-          type: array
-          items:
-            $ref: '#/components/schemas/WeeklyTimeSlot'
-```
-
-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
-the spec before running generation. Actively look for these smells:
-
-- the same `success/timestamp/path/message` fields repeated in many response
-  schemas;
-- identical pagination `meta` objects or `PaginationMeta` definitions copied
-  across services instead of referencing a shared component;
-- many `id` parameters declared inline instead of referencing a shared
-  parameter;
-- inline UUID, date, date-time, URL, slug, or enum-like scalar constraints that
-  already exist in a shared component;
-- identical regex patterns copied into multiple schemas;
-- 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
-  meaning;
-- generated diffs adding many near-identical DTO/model files after a small API
-  change.
-
-When you see a smell, propose a shared component before generating.
-
-## When not to share
-
-Do not share only because two shapes currently look alike. Keep separate
-components when:
-
-- endpoints have different validation rules or lifecycle/backwards-compatibility
-  needs;
-- a request DTO and response DTO intentionally differ, even if fields overlap;
-- names would become vague (`CommonThing`, `BaseData`, `GenericConfig`);
-- sharing would force unrelated teams/domains 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
-   shared base.
-4. Run `sumr kontract validate`.
-5. 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.

package/ai/modules/kontract/resources/scope-and-splitting.rf.md

@@ -1,147 +0,0 @@
----
-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."
-label: Scope and Splitting
-when: Reviewing large specs or code files, deciding whether to split a domain/subdomain spec, or optimizing oversized Kontract modules
-order: 18
----
-
-# Scope, Size, and Splitting
-
-Kontract is the next iteration of the AutoSync/AsyncAPI 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
-triggers first and hard caps second.
-
-## Source-of-truth rule
-
-Put durable guidance in Playbook resources and module docs; generated editor
-rules should point back to those resources. Do not copy long rules into Cursor,
-Claude, Codex, or generated contracts. The source contract spec and the source
-Playbook resource are the maintained truth.
-
-## Public example hygiene
-
-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:
-
-- kitchen recipes and ingredients;
-- bookstore inventory;
-- parcel shipping;
-- job hierarchies and departments;
-- todos or calendar events.
-
-Prefer `example.*`, `recipes`, `orders`, `ingredients`, `jobs`, or similarly
-generic names. Do not use real service names, internal nouns, customer nouns,
-NATS subject prefixes, API paths, or entity relationships as examples. Internal
-examples are acceptable in private `docs/` only when they are necessary to
-explain the module's current behavior.
-
-## File size budgets
-
-| 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 |
-| 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 |
-
-Exceptions require a documented reason in the PR or handoff. Generated files,
-large fixtures, and intentionally dense compatibility snapshots are exempt from
-manual splitting, but they can still reveal generator or spec-design problems.
-
-## Split triggers
-
-Split or optimize before adding more content when a file shows any of these:
-
-- multiple product domains or subdomains 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;
-- repeated operation patterns that should become shared parameters/responses;
-- a TypeScript file with orchestration, parsing, emitting, IO, and formatting
-  responsibilities mixed together;
-- a generated diff where a small spec change creates many near-identical files.
-
-Do not split only by line count. First identify the product or technical
-boundary that gives the new file a stable name and owner.
-
-## Domain and subdomain 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?"
-
-```text
-schema/
-  shared/
-    scalars.yml
-    pagination.yml
-    errors.yml
-    events.yml
-    scheduling.yml
-  recipes/
-    recipes.openapi.yml
-    ingredients.openapi.yml
-    publishing.asyncapi.yml
-  kitchen/
-    stations.openapi.yml
-    prep-jobs.asyncapi.yml
-    inventory.asyncapi.yml
-```
-
-Guidelines:
-
-- Keep one entry-point spec per bounded 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`.
-- 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;
-  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
-   workflows.
-4. Validate the moved refs with `sumr kontract validate`.
-5. Generate with the smallest useful scope and review both the spec diff and
-   generated output diff.
-
-## Refactor order for oversized code
-
-1. Name the current responsibilities in the file.
-2. Extract pure helpers first, then emitters/readers, then orchestration.
-3. Move interfaces and types into `src/types/` or `*.types.ts`; logic files
-   should import types instead of declaring them inline.
-4. Move reusable constants to `src/lib/constants.ts` or the existing constants
-   module.
-5. Add or adjust focused tests around the extracted seam before broad rewrites.
-
-Prefer small safe extractions over a big rewrite. The goal is a clearer module
-boundary, not a larger abstraction layer.
-
-## Review checklist
-
-Before accepting a large spec or source file:
-
-- [ ] The file is under the healthy target, or the reason for exceeding it is
-      documented.
-- [ ] The file has one clear product/technical owner.
-- [ ] Shared concepts are referenced with `$ref` rather than copied.
-- [ ] No generic bucket names (`common`, `misc`, `utils`) hide unrelated
-      responsibilities.
-- [ ] Generated output changes match the intended API surface only.
-- [ ] Any split keeps spec and regenerated output committed together.

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

@@ -1,69 +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
-  base.yml                      ← shared components, referenced via $ref
-```
-
-## Rules
-
-- OpenAPI specs end in `*.openapi.yml` / `*.openapi.yaml`.
-- AsyncAPI specs end in `*.asyncapi.yml` / `*.asyncapi.yaml`.
-- Discovery is recursive; `base.yml` is skipped as an entry point.
-- Service output paths mirror nested spec paths under the configured source
-  input directory.
-- 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.
-- 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.
-
-## 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.
-- 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.