@travetto/llm-support 8.0.0-alpha.20

package/README.md

@@ -0,0 +1,101 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/llm-support/DOC.tsx and execute "npx trv doc" to rebuild -->
+# LLM Support
+
+## Task-oriented synthesized LLM guidance for Travetto modules.
+
+The [LLM Support](https://github.com/travetto/travetto/tree/main/module/llm-support#readme "Task-oriented synthesized LLM guidance for Travetto modules.") module provides guided LLM assistance for Travetto projects. It helps you move from a target outcome to a concrete plan by combining bundle recommendations, workflow guidance, operation planning, and snippet selection.
+
+## Install
+In a Travetto workspace, install the module and use the standard CLI entrypoint:
+
+**Code: Install the module**
+```bash
+npm install @travetto/llm-support
+```
+
+The module is designed to be used through [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") commands, so once the package is available you can invoke the LLM support workflow with `trv`.
+
+## Usage
+The recommended flow is intentionally plan-first:
+   1. Run `trv llm:support:recommend` to choose a bundle, workflow, category, or snippet set.
+   1. Run `trv llm:support:plan` to preview the files and changes that would be produced.
+   1. Run `trv llm:support:execute` to apply the selected operations, with dry-run behavior available by default.
+
+**Code: Recommended flow**
+```bash
+trv llm:support:recommend\ntrv llm:support:plan\ntrv llm:support:execute
+```
+
+The recommendation command supports filtering by `bundles`, `workflows`, `categories`, and `snippet-tags`.  The plan command focuses on selected `operations` and produces file-level change steps.  Execution supports dry-run, overwrite, target directory selection, monorepo bootstrap selection (`--monorepo`), and several operation-specific hints such as route, controller, service, model, and email naming.
+
+## What It Supports
+The module covers the core assistant paths used by Travetto projects:
+   *  **Project bootstrap** - guided module and backend selection for a new application.
+   *  **Web** - route, controller, service, interceptor, and client-oriented flows.
+   *  **Auth** - session-backed identity and auth-web guided setup.
+   *  **Model** - persistence, query, indexed, and backend selection guidance.
+   *  **Upload** - direct upload and presigned URL support.
+   *  **Workflow** - deployment-oriented GitHub workflow generation.
+   *  **Quality** - linting and test suite setup.
+   *  **Email** - templates, rendering, transport, preview, and send flows.
+   *  **Test** - fixture and suite generation guidance.
+   *  **Config** - configuration class and file generation.
+   *  **Cache** - cache decorators and evictions workflows.
+
+The available categories exposed by the CLI are `project`, `web`, `auth`, `model`, `upload`, `workflow`, `quality`, `email`, `test`, `config`, and `cache`.
+
+## Bundles And Workflows
+Recommendations are grouped into install guidance bundles and workflow guidance:
+   *  `web-api-baseline` - web application fundamentals with DI and schema support.
+   *  `web-model-crud` - controller/service CRUD flows backed by model-query.
+   *  `model-persistence-stack` - model persistence and adapter selection.
+   *  `auth-enabled-web` - web auth with auth-web integration.
+   *  `quality-lint-and-test` - linting and test guardrails.
+   *  `email-generation-stack` - email template and delivery setup.
+   *  `project-bootstrap` - guided new-project setup.
+   *  `create-web-route` - route/controller/service generation workflow.
+   *  `generate-web-model-crud` - model-backed CRUD generation workflow.
+
+The recommendation output also includes snippets that match the selected operations and capability tags, so the generated plan stays tied to reusable implementation patterns.
+
+## Command Options
+The CLI surface is designed for narrow, predictable selection:
+   *  `--module` - scope recommendations to the active module.
+   *  `--bundles` - choose specific install guidance bundles.
+   *  `--workflows` - choose specific workflow guidance entries.
+   *  `--operations` - choose specific operations for planning.
+   *  `--categories` - filter by capability category.
+   *  `--snippet-tags` - narrow the snippet catalog.
+   *  `--include-excluded` - include excluded operations when you need the full catalog.
+   *  `--monorepo` - when used with `project-bootstrap`, generate a workspace root and `packages/app` project layout.
+   *  `--workspace-path` - customize the monorepo app location (for example `packages/api`).
+   *  `--workspace-name` - customize the generated workspace package name used by root scripts.
+
+That combination lets you start broad, then narrow to exactly the path you want before making changes.
+
+## MCP Integration
+The module exposes a minimal stdio MCP entrypoint for tool-calling integrations:
+
+**Code: Start MCP server**
+```bash
+trv llm:support:mcp
+```
+
+Supported methods are `initialize`, `tools/list`, and `tools/call`. Requests and responses are newline-delimited JSON-RPC 2.0 payloads.
+
+**Code: MCP request examples**
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize"}
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"llm_support_plan","arguments":{"operations":["create-web-route"]}}}
+```
+
+## Contract Model
+Contributor contract model for this module:
+   *  Boundary contracts are schema classes first (inputs and outputs).
+   *  Public type names are derived from classes instead of parallel interface trees.
+   *  Runtime boundaries validate both inbound payloads and outbound responses.
+   *  Tests should prefer schema bind+validate over custom shape guards when practical.
+
+For execution and tooling helpers in this module, prefer non-assertion-safe binding where required by project rules.

package/__index__.ts

@@ -0,0 +1,11 @@
+export * from './src/types.ts';
+export * from './src/install-guidance.ts';
+export * from './src/workflow-guidance.ts';
+export * from './src/snippet-catalog.ts';
+export * from './src/snippet-shapes.ts';
+export * from './src/recommendation.ts';
+export * from './src/plan.ts';
+export * from './src/execute.ts';
+export * from './src/tooling.ts';
+export * from './src/mcp.ts';
+export * from './src/consumer-docs.ts';

package/llm/consumer/INSTRUCTIONS.md

@@ -0,0 +1,44 @@
+# LLM Support Instructions
+Task-oriented guidance and operations for generating Travetto projects and features.
+
+## Core Intent
+Use this module to discover and execute generation-ready guidance for:
+- project bootstrap and model backend selection
+- web/controller/service and interceptor creation
+- auth, uploads, model-indexed/model-query flows
+- lint/test quality enablement
+- email generation and delivery sub-operations
+
+## Scope Decisions
+Do not recommend excluded operations unless explicitly requested:
+- log:config
+- log:instrumentation
+- eslint:profile
+- test:mock-service
+
+## Usage Workflow
+1. Discover command shapes with `npx trv cli:schema` when uncertain.
+2. Request recommendations with `npx trv llm:support:recommend`.
+3. Select bundles/workflows/operations and generate plan-first changes.
+4. Validate with lint/test and targeted compile checks.
+
+## Framework Development Principles
+- Prefer explicit contracts over implicit behavior; generated guidance should map to named operations, modules, and outcomes.
+- Keep module boundaries clear: routing, service logic, persistence, and transport concerns should remain separable.
+- Optimize for composability; recommendations should combine cleanly without hidden coupling.
+- Default to safe behavior (plan-first, dry-run-first, minimal scope changes) and require explicit opt-in for destructive actions.
+- Favor deterministic outputs so repeated runs with the same inputs produce equivalent guidance.
+
+## Best Practices
+- Schema-first boundaries: define input/output contracts with schema classes at ownership boundaries.
+- Dependency clarity: always separate required modules from optional adapters and explain why optional items exist.
+- Compatibility discipline: preserve stable operation ids and tool names; additive changes are preferred over breaking renames.
+- Validation before confidence: verify recommendations against command shape, then verify generated output with targeted tests/lint.
+- Incremental adoption: start with baseline bundles and layer advanced features only when requirements justify complexity.
+- Explain tradeoffs: when multiple stack choices exist, provide capability-based selection criteria (query, indexed, blob, expiry, etc.).
+- Keep examples production-oriented: avoid toy guidance that skips error handling, configuration boundaries, or testability.
+
+## Change Quality Expectations
+- Every new operation should include clear intent, required modules, optional modules, and verification checks.
+- Every guidance expansion should include corresponding tests for discoverability and metadata integrity.
+- Every consumer-facing behavior change should be reflected in these instructions so agent behavior stays aligned with framework expectations.

package/llm/maintainer/INSTRUCTIONS.md

@@ -0,0 +1,37 @@
+# Maintainer Notes
+
+## Module Role
+This module owns LLM-oriented generation guidance for Travetto.
+
+## Implementation Rules
+- Keep operation metadata explicit and testable.
+- Track excluded operations in `src/recommendation.ts`.
+- Keep install/workflow guidance focused on direct generation workflows.
+- Avoid provider-specific integrations in this phase.
+
+## Framework Principles
+- Treat llm-support as framework guidance infrastructure, not app-specific scaffolding.
+- Preserve stable public contracts (operation ids, tool names, output shapes) unless a versioned compatibility change is planned.
+- Keep guidance declarative and data-driven when possible to reduce execution branching and drift.
+- Favor explicit policy over convention: codify exclusions, defaults, and verification expectations in source.
+
+## Engineering Best Practices
+- Use schema classes for boundary contracts and runtime validation.
+- Keep recommendations explainable: each operation should have intent, dependency rationale, and verification guidance.
+- Maintain deterministic execution planning and artifact reporting for traceability.
+- Prefer additive evolution of guidance catalogs and workflows over mutation of existing semantics.
+- Ensure every new capability has at least one integrity test (metadata shape, discoverability, or execution coverage).
+- Keep documentation synchronized with behavior changes in the same change set.
+
+## Compatibility And Change Discipline
+- Breaking contract changes require an explicit compatibility note and migration guidance.
+- New operations should avoid overlapping semantics unless distinction is documented.
+- Excluded operations must remain visible in policy/tests, even when omitted from default recommendations.
+- Guidance should remain monorepo-aware and avoid assumptions that only apply to single-package apps.
+
+## Catalog Evolution
+When adding operations:
+1. Add type-safe operation metadata.
+2. Add workflow/install entries if module dependencies change.
+3. Add/update tests for filtering and exclusion behavior.
+4. Update consumer instructions if scope changes.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@travetto/llm-support",
+  "version": "8.0.0-alpha.20",
+  "type": "module",
+  "description": "Task-oriented synthesized LLM guidance for Travetto modules.",
+  "keywords": [
+    "travetto",
+    "llm",
+    "docs",
+    "guidance"
+  ],
+  "main": "__index__.ts",
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src",
+    "support",
+    "resources",
+    "llm"
+  ],
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/llm-support"
+  },
+  "dependencies": {
+    "@travetto/runtime": "^8.0.0-alpha.0",
+    "@travetto/schema": "^8.0.0-alpha.0"
+  },
+  "peerDependencies": {
+    "@travetto/cli": "^8.0.0-alpha.0",
+    "@travetto/test": "^8.0.0-alpha.0"
+  },
+  "peerDependenciesMeta": {
+    "@travetto/cli": {
+      "optional": true
+    },
+    "@travetto/test": {
+      "optional": true
+    }
+  },
+  "travetto": {
+    "workspaceInclude": true,
+    "displayName": "LLM Support",
+    "roles": [
+      "build"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/resources/snippets/autograph-cli-orchestration.md

@@ -0,0 +1,21 @@
+<!-- json
+{
+  "sourceId": "autograph-cli-orchestration",
+  "repositoryId": "autograph-typesetter",
+  "filePath": "support/cli.render.ts",
+  "capabilityTags": ["project", "cli", "orchestration"],
+  "operationIds": ["project-bootstrap"],
+  "applicability": ["sample-project"],
+  "notes": [
+    "Reference complex CLI orchestration and staged execution patterns."
+  ]
+}
+-->
+
+# autograph-cli-orchestration
+
+- Source: `support/cli.render.ts`
+- Capability tags: project, cli, orchestration
+- Applicability: sample-project
+- Notes:
+  - Reference complex CLI orchestration and staged execution patterns.

package/resources/snippets/code/aws-lambda-package-and-deploy.yml.tpl

@@ -0,0 +1,36 @@
+name: lambda-deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Deployment environment
+        required: true
+        default: dev
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx trv pack:lambda --output dist/lambda
+      - uses: actions/upload-artifact@v4
+        with:
+          name: lambda-package
+          path: dist/lambda
+
+  deploy:
+    needs: package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: lambda-package
+          path: dist/lambda
+      - run: echo "Deploy dist/lambda to AWS Lambda for ${{ inputs.environment }}"

package/resources/snippets/code/cache-enhancements.config.ts.tpl

@@ -0,0 +1,6 @@
+import { Config } from '@travetto/config';
+
+@Config('cache')
+export class CacheConfig {
+  ttlMs = 30000;
+}

package/resources/snippets/code/cache-enhancements.service.ts.tpl

@@ -0,0 +1,16 @@
+import { Injectable } from '@travetto/di';
+
+@Injectable()
+export class CacheableService {
+  private readonly cache = new Map<string, string>();
+
+  getOrPopulate(key: string, producer: () => string): string {
+    const cached = this.cache.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const value = producer();
+    this.cache.set(key, value);
+    return value;
+  }
+}

package/resources/snippets/code/create-web-interceptor.ts.tpl

@@ -0,0 +1,15 @@
+import { Injectable } from '@travetto/di';
+import { Interceptor } from '@travetto/web';
+
+@Injectable()
+export class RequestLoggingInterceptor implements Interceptor {
+  async intercept<T>(next: () => Promise<T>): Promise<T> {
+    const start = Date.now();
+    try {
+      return await next();
+    } finally {
+      const duration = Date.now() - start;
+      console.log('request-duration-ms', duration);
+    }
+  }
+}

package/resources/snippets/code/create-web-route.controller.ts.tpl

@@ -0,0 +1,15 @@
+import { Inject } from '@travetto/di';
+import { Controller, Get } from '@travetto/web';
+
+import { {{serviceName}} } from '../service/{{serviceFile}}.ts';
+
+@Controller('/{{routePath}}')
+export class {{controllerName}} {
+  @Inject()
+  service: {{serviceName}};
+
+  @Get('/')
+  list(): { items: string[] } {
+    return { items: this.service.getItems() };
+  }
+}

package/resources/snippets/code/create-web-route.service.ts.tpl

@@ -0,0 +1,8 @@
+import { Injectable } from '@travetto/di';
+
+@Injectable()
+export class {{serviceName}} {
+  getItems(): string[] {
+    return ['item-1', 'item-2'];
+  }
+}

package/resources/snippets/code/email-config.ts.tpl

@@ -0,0 +1,6 @@
+import { Config } from '@travetto/config';
+
+@Config('email')
+export class EmailConfig {
+  from = 'noreply@example.com';
+}

package/resources/snippets/code/email-context-schema.ts.tpl

@@ -0,0 +1,7 @@
+import { Schema } from '@travetto/schema';
+
+@Schema()
+export class {{emailType}}Context {
+  title: string;
+  message: string;
+}

package/resources/snippets/code/email-create-template.mustache.tpl

@@ -0,0 +1,2 @@
+<h1>{{title}}</h1>
+<p>{{message}}</p>

package/resources/snippets/code/email-fixture.json.tpl

@@ -0,0 +1,6 @@
+{
+  "to": "test@example.com",
+  "subject": "Sample Email",
+  "title": "Welcome",
+  "message": "Thanks for signing up"
+}

package/resources/snippets/code/email-preview-test.ts.tpl

@@ -0,0 +1,14 @@
+import assert from 'node:assert';
+
+import { Suite, Test } from '@travetto/test';
+
+import { renderTransactionalEmail } from '../../src/email/render.ts';
+
+@Suite()
+class EmailPreviewTest {
+  @Test()
+  async preview() {
+    const html = await renderTransactionalEmail({ title: 'Hello', message: 'World' });
+    assert(html.includes('Hello'));
+  }
+}

package/resources/snippets/code/email-render-pipeline.ts.tpl

@@ -0,0 +1,12 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import mustache from 'mustache';
+
+import type { TransactionalEmailContext } from './schema.ts';
+
+export async function render{{renderName}}Email(ctx: TransactionalEmailContext): Promise<string> {
+  const tplPath = path.resolve(process.cwd(), 'src/email/templates/{{emailName}}.mustache');
+  const tpl = await fs.readFile(tplPath, 'utf8');
+  return mustache.render(tpl, ctx);
+}

package/resources/snippets/code/email-send-controller.ts.tpl

@@ -0,0 +1,18 @@
+import { Inject } from '@travetto/di';
+import { Body, Controller, Post } from '@travetto/web';
+
+import { EmailProvider } from '../email/provider.ts';
+import { renderTransactionalEmail } from '../email/render.ts';
+
+@Controller('/{{routePath}}')
+export class EmailController {
+  @Inject()
+  provider: EmailProvider;
+
+  @Post('/')
+  async send(@Body() body: { to: string; subject: string; title: string; message: string }): Promise<{ sent: true }> {
+    const html = await renderTransactionalEmail({ title: body.title, message: body.message });
+    await this.provider.send(body.to, body.subject, html);
+    return { sent: true };
+  }
+}

package/resources/snippets/code/email-transport-provider.ts.tpl

@@ -0,0 +1,8 @@
+import { Injectable } from '@travetto/di';
+
+@Injectable()
+export class EmailProvider {
+  async send(to: string, subject: string, html: string): Promise<void> {
+    console.log('email-send', { to, subject, size: html.length });
+  }
+}

package/resources/snippets/code/enable-auth-session.config.ts.tpl

@@ -0,0 +1,34 @@
+import { type Authenticator, AuthenticationError, type Principal } from '@travetto/auth';
+import { SessionModelSymbol } from '@travetto/auth-session';
+import { InjectableFactory } from '@travetto/di';
+import { MemoryModelConfig, MemoryModelService } from '@travetto/model-memory';
+
+export const BasicAuthSymbol = Symbol.for('AUTH_BASIC');
+
+type User = { username: string; password: string };
+
+export class AuthConfig {
+
+  @InjectableFactory(SessionModelSymbol)
+  static getSessionModel(): MemoryModelService {
+    return new MemoryModelService(new MemoryModelConfig());
+  }
+
+  @InjectableFactory(BasicAuthSymbol)
+  static getAuthenticator(): Authenticator<User> {
+    return {
+      authenticate(user): Principal {
+        if (user.username && user.password === 'password') {
+          return {
+            issuer: 'self',
+            id: user.username,
+            permissions: [],
+            details: {},
+            source: 'insecure'
+          };
+        }
+        throw new AuthenticationError('Unknown user');
+      }
+    };
+  }
+}

package/resources/snippets/code/enable-auth-session.controller.ts.tpl

@@ -0,0 +1,30 @@
+import { type Principal } from '@travetto/auth';
+import { Authenticated, Login, Logout } from '@travetto/auth-web';
+import { ContextParam, Controller, Get, Post, WebResponse } from '@travetto/web';
+
+import { BasicAuthSymbol } from './auth.config.ts';
+
+@Controller('/auth')
+export class AuthController {
+
+  @ContextParam()
+  user: Principal;
+
+  @Post('/login')
+  @Login(BasicAuthSymbol)
+  async login(): Promise<WebResponse> {
+    return WebResponse.redirect('/auth/self');
+  }
+
+  @Get('/self')
+  @Authenticated()
+  async self(): Promise<Principal> {
+    return this.user;
+  }
+
+  @Get('/logout')
+  @Logout()
+  async logout(): Promise<WebResponse> {
+    return WebResponse.redirect('/auth/self');
+  }
+}

package/resources/snippets/code/enable-file-upload.config.ts.tpl

@@ -0,0 +1,6 @@
+import { Config } from '@travetto/config';
+
+@Config('upload')
+export class UploadConfig {
+  maxSize = 10_000_000;
+}

package/resources/snippets/code/enable-file-upload.controller.ts.tpl

@@ -0,0 +1,16 @@
+import { Controller, Post } from '@travetto/web';
+import { type FileMap, Upload } from '@travetto/web-upload';
+
+@Controller('/upload')
+export class UploadController {
+
+  @Post('/')
+  uploadOne(@Upload() file: File): { name: string; size: number } {
+    return { name: file.name, size: file.size };
+  }
+
+  @Post('/batch')
+  async uploadMany(@Upload() files: FileMap): Promise<{ count: number }> {
+    return { count: Object.keys(files).length };
+  }
+}

package/resources/snippets/code/enable-linting.package.json.tpl

@@ -0,0 +1,13 @@
+{
+  "name": "sample-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint:register": "trv eslint:register",
+    "lint": "npm run lint:register && trv eslint",
+    "lint:fix": "npm run lint:register && trv eslint --fix"
+  },
+  "devDependencies": {
+    "@travetto/eslint": "^8.0.0-alpha.20"
+  }
+}

package/resources/snippets/code/generate-config.app-config.ts.tpl

@@ -0,0 +1,7 @@
+import { Config } from '@travetto/config';
+
+@Config('app')
+export class AppConfig {
+  name = 'app';
+  version = '1.0.0';
+}

package/resources/snippets/code/generate-config.application.yml.tpl

@@ -0,0 +1,3 @@
+app:
+  name: {{projectName}}
+  version: 1.0.0

package/resources/snippets/code/generate-config.local.yml.tpl

@@ -0,0 +1,2 @@
+app:
+  name: local-app

package/resources/snippets/code/generate-test-suite.fixture.json.tpl

@@ -0,0 +1,4 @@
+{
+  "name": "example",
+  "enabled": true
+}

package/resources/snippets/code/generate-test-suite.unit.ts.tpl

@@ -0,0 +1,11 @@
+import assert from 'node:assert';
+
+import { Suite, Test } from '@travetto/test';
+
+@Suite()
+class ExampleUnitTest {
+  @Test()
+  basicAssertion() {
+    assert.strictEqual(1 + 1, 2);
+  }
+}

package/resources/snippets/code/model-indexed.indexes.ts.tpl

@@ -0,0 +1,14 @@
+import { keyedIndex, sortedIndex } from '@travetto/model-indexed';
+
+import { {{modelName}} } from './{{modelFile}}.ts';
+
+export const {{modelVar}}ByName = keyedIndex({{modelName}}, {
+  name: '{{modelFile}}_by_name',
+  key: { name: true }
+});
+
+export const {{modelVar}}ByNameCreatedAt = sortedIndex({{modelName}}, {
+  name: '{{modelFile}}_by_name_created_at',
+  key: { name: true },
+  sort: { createdAt: -1 }
+});

package/resources/snippets/code/model-indexed.model.ts.tpl

@@ -0,0 +1,8 @@
+import { Model } from '@travetto/model';
+
+@Model()
+export class {{modelName}} {
+  id: string;
+  name: string;
+  createdAt: Date;
+}

package/resources/snippets/code/model-indexed.service.ts.tpl

@@ -0,0 +1,15 @@
+import { Inject, Injectable } from '@travetto/di';
+import type { ModelIndexedSupport } from '@travetto/model-indexed';
+
+import { {{modelVar}}ByName } from '../model/{{modelFile}}.indexes.ts';
+import { {{modelName}} } from '../model/{{modelFile}}.ts';
+
+@Injectable()
+export class {{modelName}}IndexedService {
+  @Inject()
+  source: ModelIndexedSupport;
+
+  getByName(name: string): Promise<{{modelName}}> {
+    return this.source.getByIndex({{modelName}}, {{modelVar}}ByName, { name });
+  }
+}