@sumrco/cli 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+<h1 align="center">
+  <p align="center">
+    <img src="https://dev.sumr.co/sumr-docs.svg" alt="SUMR" width="250" />
+  </p>
+</h1>
+
+<p align="center">
+  <strong>The official SUMR CLI for project setup, account access, and AI workflow tooling.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sumrco/cli"><img src="https://img.shields.io/npm/v/@sumrco/cli?color=693776&label=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/runtime-Bun-4d4d4d" alt="Bun runtime" />
+</p>
+
+<p align="center">
+  <a href="#-install">Install</a>
+  ·
+  <a href="#-quick-start">Quick start</a>
+</p>
+
+---
+
+## 🚀 Install
+
+```bash
+bun add -g @sumrco/cli
+```
+
+## ⚡ Quick start
+
+```bash
+sumr --help
+sumr login
+sumr init
+```

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

@@ -0,0 +1,123 @@
+---
+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/generated-output.rf.md

@@ -0,0 +1,179 @@
+---
+category: reference
+name: generated-output
+title: Generated Output Contract
+description: "The exact shape of TypeScript files Kontract generates and how to consume them in NestJS."
+label: Generated Output
+when: Importing generated contracts, reviewing a generation diff, or wiring NATS/HTTP clients into a service
+order: 20
+---
+
+# Generated Output Contract
+
+Generated files are deterministic outputs. Import them; never edit them.
+Every generated TypeScript file starts with an `<auto-generated>` comment that
+warns users not to edit the file directly.
+
+## HTTP output — one folder per OpenAPI service
+
+For an OpenAPI service such as `recipes.openapi.yml`, the NestJS target
+emits a service folder:
+
+```text
+contracts/recipes/
+  index.ts
+  http/
+    index.ts
+    enums/
+    models/
+    zod/              # when zod generation is enabled
+    dto/              # when dtos generation is enabled
+    swagger.ts        # when dtos generation is enabled
+```
+
+Shared `$ref` components keep the source spec DRY and semantically consistent.
+Today, supported `allOf` object composition is flattened in the generated
+service output, so some concrete response DTOs may still repeat envelope fields.
+Do not fix that by hand-editing generated files. If generated code repeats too
+much, first improve the spec with shared components; then consider a Kontract
+generator improvement such as preserved composition or shared external
+component output.
+
+`http/index.ts` intentionally uses namespace exports for folders that can share
+symbol names:
+
+```typescript
+export * as Dtos from './dto';
+export * as Models from './models';
+export * as ZodContracts from './zod';
+export * from './enums';
+export * from './swagger';
+```
+
+Do not flatten-import everything blindly when DTO/model/Zod symbols collide.
+Use the namespace exports or import from the leaf folder.
+
+## Zod contract — one file per OpenAPI `components/schemas` entry
+
+```typescript
+// contracts/recipes/http/zod/recipe.contract.ts
+import { z } from 'zod';
+import { createZodDto } from 'nestjs-zod';
+
+export const RecipeSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(255),
+  status: z.enum(['draft', 'published', 'archived']),
+});
+
+export class RecipeDto extends createZodDto(RecipeSchema) {}
+export type Recipe = z.infer<typeof RecipeSchema>;
+```
+
+Every generated Zod contract yields `${Name}Schema` + `${Name}Dto` +
+`type ${Name}`.
+
+## Model interface — one file per object schema
+
+```typescript
+// contracts/recipes/http/models/recipe.ts
+export interface Recipe {
+  id: string;
+  name: string;
+  status: RecipeStatus;
+}
+```
+
+Model interfaces are framework-neutral and are safe for backend and frontend
+type-only imports.
+
+Map-shaped schemas follow OpenAPI `additionalProperties` semantics:
+
+- map-only schemas generate index signatures such as `[key: string]: string`;
+- named properties with `additionalProperties: true` preserve the named fields
+  and use `[key: string]: unknown`;
+- named properties with typed `additionalProperties` preserve named fields and
+  widen the index signature with known property value types, matching the
+  practical TypeScript approach used by current OpenAPI TypeScript generators.
+
+## Class-validator DTO — when `dtos: true`
+
+```typescript
+// contracts/recipes/http/dto/recipe.dto.ts
+import { ApiProperty } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+import { IsString, IsUUID } from 'class-validator';
+
+export class RecipeDto {
+  @ApiProperty({ format: 'uuid' })
+  @IsUUID()
+  @Expose()
+  id!: string;
+
+  @ApiProperty()
+  @IsString()
+  @Expose()
+  name!: string;
+}
+```
+
+DTO files are generated for NestJS controllers and Swagger decorators. Generated
+properties include `@Expose()` so they remain compatible with class-transformer
+serializers that use `excludeExtraneousValues: true`. Do not hand-write parallel
+DTOs for schemas Kontract owns.
+
+## Swagger operation metadata — when `dtos: true`
+
+```typescript
+// contracts/recipes/http/swagger.ts
+import type { RecipeDto } from './dto/recipe.dto';
+
+export const SWG_LIST_RECIPES = {
+  method: 'GET',
+  path: '/recipes',
+  operationId: 'listRecipes',
+  responseDto: RecipeDto,
+} as const;
+```
+
+Controllers can consume `SWG_*` metadata to keep operation IDs, paths, params,
+body DTOs, and response DTOs aligned with OpenAPI.
+
+## NATS contract — one `nats/index.ts` per AsyncAPI service
+
+```typescript
+// contracts/recipes/nats/index.ts
+export namespace Recipes {
+  export const CreateRecipeMessage = z.object({ name: z.string(), slug: z.string() });
+  export type CreateRecipeMessage = z.infer<typeof CreateRecipeMessage>;
+  export type CreateRecipeMessageInput = z.input<typeof CreateRecipeMessage>;
+
+  export const SUBJECTS = {
+    CREATE_RECIPE: 'example.recipes.command.createRecipe',
+  } as const;
+
+  export interface ICommandServer { /* ... */ }
+  export class CommandClient { /* validates with .parse() then proxy.send() */ }
+  export class QueryClient { /* ... */ }
+  export class EventClient { /* ... */ }
+}
+```
+
+- Namespace name comes from AsyncAPI `info.title`.
+- Every message yields a Zod const + `z.infer<>` type + `z.input<>` input type.
+- Subjects live in a single `SUBJECTS` const used directly by NestJS NATS.
+- Clients validate input with `.parse()` before sending.
+
+## Consuming in NestJS
+
+- Use `http/zod` `${Name}Dto` classes when you want `nestjs-zod` request/response
+  validation.
+- Use `http/dto` classes and `http/swagger.ts` when a controller follows the
+  class-validator + Swagger metadata pattern.
+- Use `http/models` interfaces for type-only internal code.
+- Use the generated `*Client` classes and `SUBJECTS` for NATS — do not
+  hand-write subjects or message shapes.
+- Each generated directory has a barrel `index.ts` for local aggregation only.
+- Regenerate (`sumr kontract generate`) after any spec change; unchanged
+  work items are skipped with `.sumr-cache/kontract` manifests when source,
+  config, generator, and output hashes still match.

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

@@ -0,0 +1,61 @@
+---
+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/overview.md

@@ -0,0 +1,115 @@
+---
+name: usage
+title: Kontract Usage
+description: "How to use the SUMR Kontract CLI to generate NestJS-ready TypeScript contracts from OpenAPI and AsyncAPI specs. Use when adding, changing, reviewing, validating, or generating API contracts."
+tags: [kontract, contracts, openapi, asyncapi, nestjs, codegen]
+---
+
+# Kontract Usage
+
+Kontract turns YAML API specs into typed, validated TypeScript: NestJS HTTP
+contracts, optional class-validator DTOs, Swagger operation metadata, frontend
+SDKs, NATS subjects, server interfaces, and clients — all from a single source
+of truth so implementations do not drift from the contract.
+
+## When to Use
+
+- Adding or editing an OpenAPI (`*.openapi.yml`) or AsyncAPI (`*.asyncapi.yml`) spec.
+- Reviewing newly written or updated `*.openapi.yml` / `*.asyncapi.yml` files
+  against Kontract best practices before validation or generation.
+- Refactoring duplicated schema fields into shared `$ref` components.
+- Regenerating contracts after a spec change.
+- Validating specs before committing or in CI.
+- Wiring generated contracts into a NestJS microservice.
+
+## Commands
+
+```bash
+sumr kontract init        # activate Kontract AI guidance for this repo
+sumr kontract validate    # validate configured OpenAPI/AsyncAPI sources
+sumr kontract generate    # generate TypeScript contracts and SDKs
+```
+
+Useful flags:
+
+- `--source <name>` — limit to one configured source
+- `--target <name>` — limit to one configured target
+- `-c, --concurrency <n>` — max parallel workers
+- `--verbose` / `--quiet` — log level (`CI=true` implies quiet)
+- `generate` also accepts `-s, --specific <name>` to generate one service spec
+- `generate` also accepts `--clean` to remove selected generated outputs and the
+  selected Kontract bundle cache before regenerating
+
+## The Model
+
+```text
+schema/
+  recipes.openapi.yml   →  contracts/recipes/http/
+  recipes.asyncapi.yml  →  contracts/recipes/nats/index.ts
+```
+
+One source of truth (the YAML spec) → many generated, always-consistent
+TypeScript artifacts. Generated files are outputs: never hand-edit them — change
+the spec and regenerate.
+
+## Configuration
+
+Kontract is configured from the repo's `sumr.yaml` under `kontract.sources`.
+Each source points at an input directory and one or more targets:
+
+```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
+```
+
+For `typescript-nestjs`:
+
+- `zod: true` emits NestJS-Zod contracts under `http/zod/`.
+- `dtos: true` emits class-validator DTOs under `http/dto/` plus
+  `http/swagger.ts` operation metadata.
+- `dto: true` is accepted as a compatibility alias for `dtos: true`; prefer
+  `dtos` in new config.
+- Framework-neutral model interfaces are emitted under `http/models/`.
+
+If a consuming repo is missing `http/dto/` or `http/swagger.ts`, first confirm
+the target has `dtos: true` (or `dto: true`) and that the installed
+`SUMR Kontract module` version contains DTO/swagger support.
+
+## Core Rules
+
+- Validate before you generate: `sumr kontract validate` then `sumr kontract generate`.
+- Treat everything under the generated `contracts/` output as read-only.
+- Keep specs the single source of truth; do not hand-write Zod/DTOs that Kontract owns.
+- After writing or updating any `*.openapi.yml` or `*.asyncapi.yml` file, review
+  the spec for duplicated concepts before generation.
+- Design specs for reuse: shared parameters, scalar constraints, error responses,
+  response envelope fragments, pagination metadata, schedule/time-slot shapes,
+  and common config objects belong in shared components referenced with `$ref`.
+- See the spec layout and generated output references for the exact file shapes.
+- See the scope and splitting reference when a spec or Kontract source file
+  crosses the review thresholds, mixes domains, or needs domain/subdomain
+  structure.
+- See the schema reuse reference before adding repeated fields or reviewing a
+  generated diff with many near-identical DTO/model files.
+- See the OpenAPI generator lessons reference before changing query params,
+  inline schemas, SDK serialization, or strict TypeScript compatibility rules.
+- Use scoped flags (`--source`, `--target`, `--specific`) before `--clean` in a
+  large consumer repo.
+- Warm generation is manifest-driven. Kontract stores per-service manifests in
+  `.sumr-cache/kontract`, skips only when source/config/generator/output hashes
+  match, and regenerates if generated files were manually changed or deleted.
+- For large repos, use normal generation first; use `--clean` only when you need
+  to intentionally clear selected generated outputs and Kontract cache state.

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

@@ -0,0 +1,90 @@
+---
+category: reference
+name: performance
+title: Kontract Performance and Incremental Generation
+description: "How Kontract uses manifests, bundle cache, workers, and batched formatting to keep large schema generations safe and fast."
+label: Performance
+when: Debugging slow `sumr kontract generate`, deciding whether to use `--clean`, or estimating large schema runs
+order: 30
+---
+
+# Kontract Performance and Incremental Generation
+
+Kontract is optimized for safe warm runs in large repos. It prefers correctness over stale output: if a cache state is ambiguous, it regenerates.
+
+## Incremental manifests
+
+For each configured source/target/service/channel, Kontract writes a manifest under the repo-local cache:
+
+```text
+.sumr-cache/kontract/bundles/<source>/<target>/manifests/<channel>/<service>/manifest.json
+```
+
+The manifest records the generator config hash, generator implementation hash, source dependency graph hash, output tree hash, generated files, Bun version, and package version.
+
+Warm generation skips a service before parsing/emitting only when all hashes still match. Manual generated-file edits or deletions invalidate the output tree hash and force regeneration.
+
+## Clean generation
+
+Use scoped clean when the cache or generated output may be stale:
+
+```bash
+sumr kontract generate --source api --target backend --clean
+```
+
+`--clean` removes the selected generated output roots and selected Kontract cache/manifests. It does not remove `.sumr-cache/activations.json`.
+
+## Formatting strategy
+
+CLI generation does not spawn Biome once per generated file. It writes changed files first, then runs one Biome directory format per changed output root. Unchanged warm runs should have zero formatter subprocesses.
+
+## Bundling strategy
+
+OpenAPI roots with no `$ref` or only internal `#/...` refs skip bundling. Roots with external
+refs use Redocly's OpenAPI core in-process, and safe bundles are cached under:
+
+```text
+.sumr-cache/kontract/bundles/<source>/source-cache/bundle-cache/
+```
+
+The source-scoped bundle cache is shared across targets in the same source. A BCHQ-style source
+that generates backend NestJS contracts and frontend models should bundle each unchanged external
+OpenAPI root once, not once per target. Unsafe or ambiguous refs still fall back to target-scoped
+temporary bundling.
+
+Ambiguous multiline or remote refs take the safe path and regenerate/bundle rather than trusting a stale cache.
+
+Emergency fallback:
+
+```bash
+KONTRACT_DISABLE_REDOCLY_CORE=1 sumr kontract generate
+```
+
+## Worker strategy
+
+When concurrency is greater than one, Kontract uses a Bun worker pool for parse/extract/emit/write tasks. The main process still owns discovery, manifest validation, final barrels, final formatting, and summaries.
+
+Emergency/debug fallbacks:
+
+```bash
+KONTRACT_DISABLE_WORKERS=1 sumr kontract generate
+KONTRACT_FORCE_MAIN_THREAD=1 sumr kontract generate
+```
+
+## Benchmarking
+
+Use the local synthetic benchmark before changing generation orchestration, formatting, file writing, bundling, or cache behavior:
+
+```bash
+bun run tools perf generate --count=50 --concurrency=8 --mode=both
+bun run tools perf generate --count=100 --concurrency=8 --mode=both --root=.tmp/kontract-performance-100
+bun run tools perf generate --count=20 --concurrency=8 --mode=both --refs=external --targets=both
+```
+
+Benchmark output stays under `.tmp/` and writes both `results.json` and `README.md` with phase timings, counters, and subprocess resource usage. Use `--refs=internal` to confirm bundling is skipped, and `--refs=external --targets=both` to confirm the shared bundle cache keeps cold-run in-process bundling at roughly one per schema root instead of one per target.
+
+Local signal after in-process OpenAPI bundling:
+
+- `--count=1000 --refs=external --targets=both --concurrency=8`: cold `8.72s`, warm `0.83s`.
+- Warm manifests skipped all `2000` source/target work items and ran zero formatter/bundler subprocesses.
+- Cold formatting stayed at 2 Biome subprocesses for 2 changed output roots.