@travetto/llm-support 8.0.0-alpha.20

package/src/recommendation.ts

@@ -0,0 +1,306 @@
+import {
+  type InstallGuidance,
+  type LlmOperation,
+  type RecommendationQuery,
+  type RecommendationResponse,
+  type WorkflowGuidance
+} from './types.ts';
+import { INSTALL_BUNDLES } from './install-guidance.ts';
+import { recommendSnippets } from './snippet-catalog.ts';
+import { WORKFLOWS } from './workflow-guidance.ts';
+
+const OPERATIONS: LlmOperation[] = [
+  {
+    id: 'project-bootstrap',
+    category: 'project',
+    title: 'Project bootstrap',
+    summary: 'Create a project with guided module and backend selection.',
+    requiredModules: ['@travetto/runtime', '@travetto/config'],
+    optionalModules: ['@travetto/web', '@travetto/model', '@travetto/test', '@travetto/eslint']
+  },
+  {
+    id: 'create-web-route',
+    category: 'web',
+    title: 'Create route/controller/service',
+    summary: 'Generate a web route with controller and service separation.',
+    requiredModules: ['@travetto/web', '@travetto/schema', '@travetto/di'],
+    optionalModules: ['@travetto/auth-web', '@travetto/model-query']
+  },
+  {
+    id: 'enable-file-upload',
+    category: 'upload',
+    title: 'Enable file upload',
+    summary: 'Support direct upload and presigned URL upload flows.',
+    requiredModules: ['@travetto/web-upload'],
+    optionalModules: ['@travetto/model-s3', '@travetto/model-firestore']
+  },
+  {
+    id: 'enable-auth-session',
+    category: 'auth',
+    title: 'Enable auth/session',
+    summary: 'Add login, self, and logout flows with session support.',
+    requiredModules: ['@travetto/auth', '@travetto/auth-web'],
+    optionalModules: ['@travetto/auth-session', '@travetto/auth-web-session', '@travetto/model-memory']
+  },
+  {
+    id: 'rest-rpc-client',
+    category: 'web',
+    title: 'Create rest-rpc client',
+    summary: 'Generate UI-focused rest-rpc client integration.',
+    requiredModules: ['@travetto/web-rpc'],
+    optionalModules: ['@travetto/openapi']
+  },
+  {
+    id: 'model-indexed-assistant',
+    category: 'model',
+    title: 'Model indexed support',
+    summary: 'Add indexes and index-aware query helpers.',
+    requiredModules: ['@travetto/model-indexed'],
+    optionalModules: ['@travetto/model-query']
+  },
+  {
+    id: 'model-query-assistant',
+    category: 'model',
+    title: 'Model query support',
+    summary: 'Craft query expressions from natural language intent.',
+    requiredModules: ['@travetto/model-query'],
+    optionalModules: ['@travetto/model-query-language']
+  },
+  {
+    id: 'workflow-gcp-deploy',
+    category: 'workflow',
+    title: 'Generate GCP deploy workflow',
+    summary: 'Create GitHub workflows for GCP deploy pipelines.',
+    requiredModules: [],
+    optionalModules: []
+  },
+  {
+    id: 'workflow-cloudfront-deploy',
+    category: 'workflow',
+    title: 'Generate CloudFront deploy workflow',
+    summary: 'Create GitHub workflows for S3 + CloudFront UI deploy pipelines.',
+    requiredModules: [],
+    optionalModules: []
+  },
+  {
+    id: 'enable-linting',
+    category: 'quality',
+    title: 'Enable linting and fix',
+    summary: 'Configure linting support and fix workflows for generated code.',
+    requiredModules: ['@travetto/eslint'],
+    optionalModules: ['@travetto/test']
+  },
+  {
+    id: 'generate-config',
+    category: 'config',
+    title: 'Create configuration classes/files',
+    summary: 'Generate config schema classes and profile-aware config files.',
+    requiredModules: ['@travetto/config'],
+    optionalModules: []
+  },
+  {
+    id: 'generate-test-suite',
+    category: 'test',
+    title: 'Create test suite',
+    summary: 'Generate unit/integration tests and fixture setup.',
+    requiredModules: ['@travetto/test'],
+    optionalModules: []
+  },
+  {
+    id: 'create-web-interceptor',
+    category: 'web',
+    title: 'Create web interceptor',
+    summary: 'Generate web interceptor for cross-cutting concerns.',
+    requiredModules: ['@travetto/web'],
+    optionalModules: ['@travetto/auth-web', '@travetto/cache']
+  },
+  {
+    id: 'email-create-template',
+    category: 'email',
+    title: 'Create email template',
+    summary: 'Generate template files for transactional email.',
+    requiredModules: ['@travetto/email'],
+    optionalModules: ['@travetto/email-compiler', '@travetto/email-inky']
+  },
+  {
+    id: 'email-context-schema',
+    category: 'email',
+    title: 'Generate email context schema',
+    summary: 'Create typed context contracts for template rendering.',
+    requiredModules: ['@travetto/email', '@travetto/schema'],
+    optionalModules: []
+  },
+  {
+    id: 'email-render-pipeline',
+    category: 'email',
+    title: 'Add email render pipeline',
+    summary: 'Wire template compiler and renderer integration.',
+    requiredModules: ['@travetto/email'],
+    optionalModules: ['@travetto/email-compiler', '@travetto/email-inky']
+  },
+  {
+    id: 'email-transport-provider',
+    category: 'email',
+    title: 'Add email transport/provider',
+    summary: 'Configure provider wiring for runtime delivery.',
+    requiredModules: ['@travetto/email'],
+    optionalModules: ['@travetto/email-nodemailer']
+  },
+  {
+    id: 'email-preview-snapshot',
+    category: 'email',
+    title: 'Add email preview/snapshot',
+    summary: 'Generate preview and snapshot validation support.',
+    requiredModules: ['@travetto/email', '@travetto/test'],
+    optionalModules: []
+  },
+  {
+    id: 'email-send-flow',
+    category: 'email',
+    title: 'Add email send integration',
+    summary: 'Integrate send operations with endpoint or worker execution.',
+    requiredModules: ['@travetto/email'],
+    optionalModules: ['@travetto/worker', '@travetto/web']
+  },
+  {
+    id: 'email-test-fixtures',
+    category: 'email',
+    title: 'Add email test fixtures',
+    summary: 'Generate fixture data and tests for email generation flows.',
+    requiredModules: ['@travetto/email', '@travetto/test'],
+    optionalModules: []
+  },
+  {
+    id: 'cache-enhancements',
+    category: 'cache',
+    title: 'Add cache enhancements',
+    summary: 'Generate cache decorators and eviction workflows.',
+    requiredModules: ['@travetto/cache'],
+    optionalModules: ['@travetto/model']
+  },
+  {
+    id: 'openapi-spec-pipeline',
+    category: 'web',
+    title: 'Add OpenAPI spec pipeline',
+    summary: 'Generate OpenAPI specification workflow and persistence settings.',
+    requiredModules: ['@travetto/openapi'],
+    optionalModules: ['@travetto/web', '@travetto/schema']
+  },
+  {
+    id: 'openapi-client-generation',
+    category: 'web',
+    title: 'Add OpenAPI client generation',
+    summary: 'Generate client workflow from OpenAPI spec artifacts.',
+    requiredModules: ['@travetto/openapi'],
+    optionalModules: ['@travetto/web-rpc', '@travetto/web']
+  },
+  {
+    id: 'aws-lambda-package-and-deploy',
+    category: 'workflow',
+    title: 'Add AWS Lambda package/deploy',
+    summary: 'Generate packaging and deployment workflow for web AWS Lambda targets.',
+    requiredModules: ['@travetto/web-aws-lambda', '@travetto/pack'],
+    optionalModules: ['@travetto/web', '@travetto/config']
+  },
+  {
+    id: 'pack-docker-release',
+    category: 'workflow',
+    title: 'Add Docker pack release',
+    summary: 'Generate workflow for container image build and publish via pack:docker.',
+    requiredModules: ['@travetto/pack'],
+    optionalModules: ['@travetto/config', '@travetto/runtime']
+  },
+  {
+    id: 'repo-version-release',
+    category: 'workflow',
+    title: 'Add repo version release flow',
+    summary: 'Generate monorepo versioning workflow using repo:version.',
+    requiredModules: ['@travetto/repo'],
+    optionalModules: ['@travetto/pack', '@travetto/registry']
+  },
+  {
+    id: 'excluded-log-config',
+    category: 'quality',
+    title: 'Log configuration (excluded)',
+    summary: 'Excluded by scope decision.',
+    requiredModules: ['@travetto/log'],
+    optionalModules: [],
+    excluded: true
+  },
+  {
+    id: 'excluded-log-instrumentation',
+    category: 'quality',
+    title: 'Log instrumentation (excluded)',
+    summary: 'Excluded by scope decision.',
+    requiredModules: ['@travetto/log'],
+    optionalModules: [],
+    excluded: true
+  },
+  {
+    id: 'excluded-eslint-profile',
+    category: 'quality',
+    title: 'ESLint profile generation (excluded)',
+    summary: 'Excluded by scope decision.',
+    requiredModules: ['@travetto/eslint'],
+    optionalModules: [],
+    excluded: true
+  },
+  {
+    id: 'excluded-test-mock-service',
+    category: 'test',
+    title: 'Test mock service generation (excluded)',
+    summary: 'Excluded by scope decision.',
+    requiredModules: ['@travetto/test'],
+    optionalModules: [],
+    excluded: true
+  }
+];
+
+function matchesIds<T extends { id: string }>(items: T[], ids?: string[]): T[] {
+  if (!ids || ids.length === 0) {
+    return items;
+  }
+  const wanted = new Set(ids);
+  return items.filter(item => wanted.has(item.id));
+}
+
+export function recommendBundles(ids?: string[]): InstallGuidance[] {
+  return matchesIds(INSTALL_BUNDLES, ids);
+}
+
+export function recommendWorkflows(ids?: string[]): WorkflowGuidance[] {
+  return matchesIds(WORKFLOWS, ids);
+}
+
+export function recommendOperations(query: RecommendationQuery = {}): LlmOperation[] {
+  const { categories, includeExcluded = false } = query;
+  const selected = categories && categories.length ?
+    OPERATIONS.filter(item => categories.includes(item.category)) :
+    OPERATIONS;
+  return selected.filter(item => includeExcluded || !item.excluded);
+}
+
+export const LLM_OPERATION_CATEGORIES = [...new Set(OPERATIONS.map(item => item.category))].sort();
+
+export function getValidOperationIds(includeExcluded = false): string[] {
+  return recommendOperations({ includeExcluded }).map(item => item.id);
+}
+
+export async function recommend(query: RecommendationQuery = {}): Promise<RecommendationResponse> {
+  const operations = recommendOperations(query);
+  return {
+    bundles: recommendBundles(query.bundles),
+    workflows: recommendWorkflows(query.workflows),
+    operations,
+    snippets: await recommendSnippets({
+      ...query,
+      operations: operations.map(item => item.id)
+    })
+  };
+}
+
+export const EXCLUDED_OPERATION_IDS = OPERATIONS
+  .filter(item => item.excluded)
+  .map(item => item.id);
+
+export const LLM_OPERATIONS = OPERATIONS;

package/src/snippet-catalog.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { SchemaValidator } from '@travetto/schema';
+import { JSONUtil, RuntimeIndex } from '@travetto/runtime';
+
+import type { RecommendationQuery, SnippetSource } from './types.ts';
+import { SnippetSourceSchema } from './snippet-shapes.ts';
+
+const SNIPPET_RELATIVE_DIR = 'snippets';
+
+function snippetDirectory(): string {
+  return path.resolve(RuntimeIndex.getModule('@travetto/llm-support')!.sourcePath, 'resources', SNIPPET_RELATIVE_DIR);
+}
+
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+  return typeof err === 'object' && err !== null && 'code' in err;
+}
+
+async function loadSnippet(fullPath: string): Promise<SnippetSource> {
+  const content = await fs.readFile(fullPath, 'utf8');
+  const match = content.match(/<!--\s*json\s*([\s\S]*?)\s*-->/i);
+  if (!match) {
+    throw new Error(`Invalid snippet markdown: ${fullPath}`);
+  }
+  const bound = SnippetSourceSchema.from(JSONUtil.fromUTF8(match[1].trim()));
+  await SchemaValidator.validate(SnippetSourceSchema, bound);
+  return bound;
+}
+
+async function loadSnippets(): Promise<SnippetSource[]> {
+  try {
+    const dir = snippetDirectory();
+    const files = await fs.readdir(dir);
+    const filtered = files
+      .filter(file => file.endsWith('.md'))
+      .sort();
+    return Promise.all(filtered.map(file => loadSnippet(path.join(dir, file))));
+  } catch (err) {
+    if (isErrnoException(err) && (err.code === 'ENOENT' || err.code === 'ERR_MODULE_NOT_FOUND')) {
+      return [];
+    }
+    throw err;
+  }
+}
+
+let snippetsPromise: Promise<SnippetSource[]> | undefined;
+
+async function getSnippets(): Promise<SnippetSource[]> {
+  snippetsPromise ??= loadSnippets();
+  return snippetsPromise;
+}
+
+function matchesAny(value: string[], desired?: string[]): boolean {
+  if (!desired || desired.length === 0) {
+    return true;
+  }
+  const wanted = new Set(desired);
+  return value.some(item => wanted.has(item));
+}
+
+export async function recommendSnippets(query: RecommendationQuery = {}): Promise<SnippetSource[]> {
+  const snippets = await getSnippets();
+  const byOperation = query.operations && query.operations.length > 0 ?
+    snippets.filter(item => matchesAny(item.operationIds ?? [], query.operations)) :
+    snippets;
+
+  const byTag = query.snippetTags && query.snippetTags.length > 0 ?
+    byOperation.filter(item => matchesAny(item.capabilityTags, query.snippetTags)) :
+    byOperation;
+
+  return byTag;
+}
+
+export async function getValidSnippetTags(): Promise<string[]> {
+  const snippets = await getSnippets();
+  return [...new Set(snippets.flatMap(item => item.capabilityTags))].sort();
+}
+
+export const LLM_SNIPPET_SOURCES = getSnippets();

package/src/snippet-shapes.ts

@@ -0,0 +1,14 @@
+import { Schema } from '@travetto/schema';
+
+import type { SnippetSource } from './types.ts';
+
+@Schema()
+export class SnippetSourceSchema implements SnippetSource {
+  sourceId!: string;
+  repositoryId!: string;
+  filePath!: string;
+  capabilityTags!: string[];
+  operationIds?: string[];
+  applicability?: string[];
+  notes!: string[];
+}

package/src/template-shapes.ts

@@ -0,0 +1,13 @@
+import { Schema } from '@travetto/schema';
+import type { Package } from '@travetto/manifest';
+
+export type PackageJsonShape = Partial<Pick<Package, 'name' | 'private' | 'type' | 'scripts' | 'devDependencies'>>;
+
+@Schema()
+export class PackageJsonSchema implements PackageJsonShape {
+  name?: string;
+  private?: boolean;
+  type?: string;
+  scripts?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}

package/src/tooling.ts

@@ -0,0 +1,197 @@
+import type { Class } from '@travetto/runtime';
+import { SchemaValidator } from '@travetto/schema';
+
+import { executeOperations } from './execute.ts';
+import { buildPlans } from './plan.ts';
+import { recommend } from './recommendation.ts';
+import {
+  type ExecutionRequest,
+  type ExecutionResponse,
+  ExecutionResponseSchema,
+  LlmSupportExecuteToolInput,
+  LlmSupportPlanToolInput,
+  LlmSupportRecommendToolInput,
+  type PlanResponse,
+  PlanResponseSchema,
+  type RecommendationQuery,
+  type RecommendationResponse,
+  RecommendationResponseSchema
+} from './types.ts';
+
+export type LlmSupportToolName = 'llm_support_recommend' | 'llm_support_plan' | 'llm_support_execute';
+
+export interface LlmSupportToolDefinition {
+  name: LlmSupportToolName;
+  description: string;
+  inputSchema: object;
+}
+
+export interface LlmSupportFlowInput {
+  query?: RecommendationQuery;
+  execute?: Omit<ExecutionRequest, 'operations'> & { operations?: string[] };
+}
+
+export interface LlmSupportFlowResult {
+  recommendation: RecommendationResponse;
+  plan: PlanResponse;
+  execution: ExecutionResponse;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function toList(value: unknown): string[] | undefined {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === 'string');
+  }
+  if (typeof value === 'string') {
+    return [value];
+  }
+  return undefined;
+}
+
+function normalizeQuery(input: RecommendationQuery): RecommendationQuery {
+  return {
+    ...input,
+    bundles: toList(input.bundles) ?? input.bundles,
+    workflows: toList(input.workflows) ?? input.workflows,
+    operations: toList(input.operations) ?? input.operations,
+    snippetTags: toList(input.snippetTags) ?? input.snippetTags
+  };
+}
+
+async function validateInput<T extends object>(schema: Class<T>, payload: unknown): Promise<T> {
+  const bound = schema.from({});
+  Object.assign(bound, isRecord(payload) ? payload : {});
+  await SchemaValidator.validate(schema, bound);
+  return bound;
+}
+
+async function validateOutput<T extends object>(schema: Class<T>, payload: unknown): Promise<T> {
+  const bound = schema.from({});
+  Object.assign(bound, isRecord(payload) ? payload : {});
+  await SchemaValidator.validate(schema, bound);
+  return bound;
+}
+
+export function getLlmSupportToolDefinitions(): LlmSupportToolDefinition[] {
+  return [
+    {
+      name: 'llm_support_recommend',
+      description: 'Recommend bundles, workflows, operations, and snippets for Travetto implementation goals.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          bundles: { type: 'array', items: { type: 'string' } },
+          workflows: { type: 'array', items: { type: 'string' } },
+          operations: { type: 'array', items: { type: 'string' } },
+          categories: { type: 'array', items: { type: 'string' } },
+          snippetTags: { type: 'array', items: { type: 'string' } },
+          includeExcluded: { type: 'boolean' }
+        },
+        additionalProperties: false
+      }
+    },
+    {
+      name: 'llm_support_plan',
+      description: 'Build file-level plans for selected operations with rationale and snippets.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          operations: { type: 'array', items: { type: 'string' } },
+          categories: { type: 'array', items: { type: 'string' } },
+          snippetTags: { type: 'array', items: { type: 'string' } },
+          includeExcluded: { type: 'boolean' }
+        },
+        additionalProperties: false
+      }
+    },
+    {
+      name: 'llm_support_execute',
+      description: 'Execute selected operations against a target directory. Dry-run is the default unless apply is true.',
+      inputSchema: {
+        type: 'object',
+        required: ['operations', 'targetDir'],
+        properties: {
+          operations: { type: 'array', items: { type: 'string' }, minItems: 1 },
+          targetDir: { type: 'string', minLength: 1 },
+          apply: { type: 'boolean' },
+          overwrite: { type: 'boolean' },
+          monorepo: { type: 'boolean' },
+          workspacePath: { type: 'string' },
+          workspaceName: { type: 'string' },
+          routePath: { type: 'string' },
+          controllerName: { type: 'string' },
+          serviceName: { type: 'string' },
+          modelName: { type: 'string' },
+          projectName: { type: 'string' },
+          emailName: { type: 'string' },
+          sendRoutePath: { type: 'string' }
+        },
+        additionalProperties: false
+      }
+    }
+  ];
+}
+
+export async function runLlmSupportTool(
+  name: LlmSupportToolName,
+  payload: unknown
+): Promise<RecommendationResponse | PlanResponse | ExecutionResponse> {
+  switch (name) {
+    case 'llm_support_recommend': {
+      const input = await validateInput(LlmSupportRecommendToolInput, payload);
+      const output = await recommend(normalizeQuery(input));
+      return validateOutput(RecommendationResponseSchema, output);
+    }
+    case 'llm_support_plan': {
+      const input = await validateInput(LlmSupportPlanToolInput, payload);
+      const output = await buildPlans(normalizeQuery(input));
+      return validateOutput(PlanResponseSchema, output);
+    }
+    case 'llm_support_execute': {
+      const input = await validateInput(LlmSupportExecuteToolInput, payload);
+      const request: ExecutionRequest = {
+        operations: toList(input.operations) ?? [],
+        targetDir: input.targetDir,
+        dryRun: input.apply !== true,
+        overwrite: input.overwrite,
+        monorepo: input.monorepo,
+        workspacePath: input.workspacePath,
+        workspaceName: input.workspaceName,
+        routePath: input.routePath,
+        controllerName: input.controllerName,
+        serviceName: input.serviceName,
+        modelName: input.modelName,
+        projectName: input.projectName,
+        emailName: input.emailName,
+        sendRoutePath: input.sendRoutePath
+      };
+      const output = await executeOperations(request);
+      return validateOutput(ExecutionResponseSchema, output);
+    }
+  }
+}
+
+export async function runLlmSupportFlow(input: LlmSupportFlowInput = {}): Promise<LlmSupportFlowResult> {
+  const query = normalizeQuery(input.query ?? {});
+  const recommendation = await validateOutput(RecommendationResponseSchema, await recommend(query));
+  const plan = await validateOutput(PlanResponseSchema, await buildPlans(query));
+
+  const execute = input.execute ?? { targetDir: '.', dryRun: true };
+  const operations = toList(execute.operations) ?? plan.plans.map(item => item.operationId);
+
+  const executionRequest: ExecutionRequest = {
+    ...execute,
+    operations,
+    targetDir: execute.targetDir
+  };
+  const execution = await validateOutput(ExecutionResponseSchema, await executeOperations(executionRequest));
+
+  return {
+    recommendation,
+    plan,
+    execution
+  };
+}