@travetto/llm-support 8.0.0-alpha.20

package/src/install-guidance.ts

@@ -0,0 +1,187 @@
+import { type DependencyGraphNode, type InstallGuidance } from './types.ts';
+
+export const INSTALL_BUNDLES: InstallGuidance[] = [
+  {
+    id: 'web-api-baseline',
+    title: 'Web API Baseline',
+    required: ['@travetto/runtime', '@travetto/config', '@travetto/schema', '@travetto/di', '@travetto/web'],
+    optional: ['@travetto/openapi', '@travetto/log', '@travetto/test'],
+    notes: [
+      'Use this baseline for HTTP endpoint development with dependency injection and schema contracts.',
+      'Add @travetto/openapi when API contract generation is required.'
+    ]
+  },
+  {
+    id: 'auth-enabled-web',
+    title: 'Auth Enabled Web',
+    required: ['@travetto/web', '@travetto/auth', '@travetto/auth-web'],
+    optional: ['@travetto/auth-session', '@travetto/auth-web-session', '@travetto/auth-web-passport'],
+    notes: [
+      'Start with auth plus auth-web for core identity and permission checks in HTTP flows.',
+      'Session and passport adapters are optional and depend on runtime identity needs.'
+    ]
+  },
+  {
+    id: 'auth-google-passport-web',
+    title: 'Google OAuth with Passport (Web)',
+    required: [
+      '@travetto/web',
+      '@travetto/auth',
+      '@travetto/auth-web',
+      '@travetto/auth-web-passport',
+      '@travetto/config',
+      'passport',
+      'passport-google-oauth20'
+    ],
+    optional: ['@travetto/model', '@travetto/model-indexed', '@travetto/model-firestore', '@travetto/auth-model'],
+    notes: [
+      'Define google.auth config fields (clientID, clientSecret, callbackUrl) and bind with @Config.',
+      'Register a PassportAuthenticator using OAuth2Strategy and map profile -> principal details.',
+      'If persisting principals by external id, add one model adapter (for example @travetto/model-firestore) and an indexed lookup.'
+    ]
+  },
+  {
+    id: 'model-persistence-stack',
+    title: 'Model Persistence Stack',
+    required: ['@travetto/model'],
+    optional: [
+      '@travetto/model-query',
+      '@travetto/model-indexed',
+      '@travetto/model-sql',
+      '@travetto/model-postgres',
+      '@travetto/model-mysql',
+      '@travetto/model-sqlite',
+      '@travetto/model-memory',
+      '@travetto/model-mongo',
+      '@travetto/model-dynamodb',
+      '@travetto/model-file',
+      '@travetto/model-firestore',
+      '@travetto/model-redis',
+      '@travetto/model-s3',
+      '@travetto/model-elasticsearch',
+      '@travetto/model-query-language'
+    ],
+    notes: [
+      'Pick one adapter family first (SQL or non-SQL), then select one primary adapter package for your datastore target.',
+      'Use needs-driven adapter selection (blob/query/indexed/expiry) to narrow non-SQL options before finalizing a package.',
+      'Add @travetto/model-query-language when exposing user-facing query parsing.'
+    ]
+  },
+  {
+    id: 'worker-baseline',
+    title: 'Worker Baseline',
+    required: ['@travetto/runtime', '@travetto/config', '@travetto/worker'],
+    optional: ['@travetto/model', '@travetto/log', '@travetto/context'],
+    notes: [
+      'Use worker for scheduled or background job execution.',
+      'Add model when jobs persist state between runs.'
+    ]
+  },
+  {
+    id: 'quality-lint-and-test',
+    title: 'Quality Setup (Lint + Test)',
+    required: ['@travetto/test', '@travetto/eslint'],
+    optional: ['@travetto/log'],
+    notes: [
+      'Use this bundle for project quality guardrails and lint-fix workflows.',
+      'Pair with generated operation plans so every new feature ships with test and lint coverage.'
+    ]
+  },
+  {
+    id: 'web-auth-session-stack',
+    title: 'Web Auth + Session Stack',
+    required: [
+      '@travetto/web',
+      '@travetto/auth',
+      '@travetto/auth-web',
+      '@travetto/auth-session',
+      '@travetto/auth-web-session',
+      '@travetto/model-memory'
+    ],
+    optional: ['@travetto/model', '@travetto/model-indexed'],
+    notes: [
+      'Use this bundle for login/self/logout flows with session-backed identity.',
+      'Use model-memory for local session storage unless a persistent session store is required.'
+    ]
+  },
+  {
+    id: 'web-model-crud',
+    title: 'Web + Model CRUD',
+    required: ['@travetto/web', '@travetto/model', '@travetto/model-query', '@travetto/schema', '@travetto/di'],
+    optional: ['@travetto/auth', '@travetto/auth-web', '@travetto/model-indexed'],
+    notes: [
+      'Use this bundle when creating route/controller/service flows backed by model-query.',
+      'Add auth/auth-web when CRUD endpoints should be principal-scoped.'
+    ]
+  },
+  {
+    id: 'model-backend-selection',
+    title: 'Model Backend Selection',
+    required: ['@travetto/model'],
+    optional: [
+      '@travetto/model-elasticsearch',
+      '@travetto/model-mongo',
+      '@travetto/model-sql',
+      '@travetto/model-mysql',
+      '@travetto/model-postgres',
+      '@travetto/model-sqlite'
+    ],
+    notes: [
+      'Use this bundle to drive backend selection prompts for datastore adapters.',
+      'Choose exactly one backend adapter for active datastore target.'
+    ]
+  },
+  {
+    id: 'email-generation-stack',
+    title: 'Email Generation + Delivery',
+    required: ['@travetto/email'],
+    optional: ['@travetto/email-compiler', '@travetto/email-inky', '@travetto/email-nodemailer', '@travetto/worker'],
+    notes: [
+      'Use this bundle when generating templates, compiler pipelines, and transport wiring.',
+      'Add worker when routing send operations through async background execution.'
+    ]
+  }
+];
+
+export const DEPENDENCY_GRAPH: DependencyGraphNode[] = [
+  {
+    package: '@travetto/auth',
+    requires: ['@travetto/runtime', '@travetto/schema', '@travetto/di'],
+    optionalAdapters: ['@travetto/auth-model', '@travetto/auth-session']
+  },
+  {
+    package: '@travetto/web',
+    requires: ['@travetto/runtime', '@travetto/config', '@travetto/schema', '@travetto/di'],
+    optionalAdapters: ['@travetto/web-express', '@travetto/web-fastify', '@travetto/web-koa']
+  },
+  {
+    package: '@travetto/auth-web',
+    requires: ['@travetto/auth', '@travetto/web'],
+    optionalAdapters: ['@travetto/auth-web-session', '@travetto/auth-web-passport']
+  },
+  {
+    package: '@travetto/model',
+    requires: ['@travetto/schema', '@travetto/di', '@travetto/config'],
+    optionalAdapters: [
+      '@travetto/model-memory',
+      '@travetto/model-sql',
+      '@travetto/model-mongo',
+      '@travetto/model-dynamodb',
+      '@travetto/model-file',
+      '@travetto/model-firestore',
+      '@travetto/model-redis',
+      '@travetto/model-s3',
+      '@travetto/model-elasticsearch'
+    ]
+  },
+  {
+    package: '@travetto/model-query',
+    requires: ['@travetto/model'],
+    optionalAdapters: ['@travetto/model-query-language']
+  },
+  {
+    package: '@travetto/worker',
+    requires: ['@travetto/runtime', '@travetto/config'],
+    optionalAdapters: ['@travetto/model', '@travetto/log', '@travetto/context']
+  }
+];

package/src/mcp.ts

@@ -0,0 +1,170 @@
+import { Schema } from '@travetto/schema';
+import { JSONUtil } from '@travetto/runtime';
+
+import { getLlmSupportToolDefinitions, runLlmSupportTool, type LlmSupportToolName } from './tooling.ts';
+
+@Schema()
+export class JsonRpcRequestSchema {
+  jsonrpc?: '2.0';
+
+  id?: string | number | null;
+
+  method: string;
+
+  params?: unknown;
+}
+
+@Schema()
+export class JsonRpcErrorSchema {
+  code = 0;
+  message = '';
+
+  data?: unknown;
+}
+
+@Schema()
+export class JsonRpcResponseSchema {
+  jsonrpc: '2.0';
+  id: string | number | null;
+
+  result?: unknown;
+
+  error?: JsonRpcErrorSchema;
+}
+
+@Schema()
+export class McpInitializeCapabilitiesSchema {
+  tools?: object;
+}
+
+@Schema()
+export class McpInitializeServerInfoSchema {
+  name?: string;
+  version?: string;
+}
+
+@Schema()
+export class McpInitializeResultSchema {
+  protocolVersion?: string;
+  capabilities?: McpInitializeCapabilitiesSchema;
+  serverInfo?: McpInitializeServerInfoSchema;
+}
+
+@Schema()
+export class McpToolDefinitionSchema {
+  name = '';
+  description = '';
+  inputSchema?: object;
+}
+
+@Schema()
+export class McpToolsListResultSchema {
+  tools: McpToolDefinitionSchema[] = [];
+}
+
+@Schema()
+export class McpToolCallContentSchema {
+  type = '';
+  text = '';
+}
+
+@Schema()
+export class McpToolCallResultSchema {
+  content: McpToolCallContentSchema[] = [];
+  structuredContent?: unknown;
+}
+
+export type JsonRpcRequest = InstanceType<typeof JsonRpcRequestSchema>;
+export type JsonRpcResponse = InstanceType<typeof JsonRpcResponseSchema>;
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+function toError(id: string | number | null, code: number, message: string, data?: unknown): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code,
+      message,
+      data
+    }
+  };
+}
+
+function toResult(id: string | number | null, result: unknown): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    result
+  };
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(value));
+}
+
+function toToolName(value: unknown): LlmSupportToolName | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  if (value === 'llm_support_recommend' || value === 'llm_support_plan' || value === 'llm_support_execute') {
+    return value;
+  }
+  return undefined;
+}
+
+export async function handleMcpRequest(input: JsonRpcRequest): Promise<JsonRpcResponse | undefined> {
+  const id = input.id ?? null;
+
+  switch (input.method) {
+    case 'initialize':
+      return toResult(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {
+          tools: {}
+        },
+        serverInfo: {
+          name: '@travetto/llm-support',
+          version: '1.0.0'
+        }
+      });
+
+    case 'notifications/initialized':
+      return undefined;
+
+    case 'tools/list':
+      return toResult(id, {
+        tools: getLlmSupportToolDefinitions()
+      });
+
+    case 'tools/call': {
+      const params = asObject(input.params);
+      const name = toToolName(params.name);
+      if (!name) {
+        return toError(id, -32602, 'Invalid tool name', { name: params.name });
+      }
+      try {
+        const args = asObject(params.arguments);
+        const output = await runLlmSupportTool(name, args);
+        return toResult(id, {
+          content: [
+            {
+              type: 'text',
+              text: JSONUtil.toUTF8(output, { indent: 2 })
+            }
+          ],
+          structuredContent: output
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Tool execution failed';
+        return toError(id, -32000, message);
+      }
+    }
+
+    default:
+      return toError(id, -32601, `Method not found: ${input.method}`);
+  }
+}

package/src/plan.ts

@@ -0,0 +1,110 @@
+import { recommend, recommendOperations } from './recommendation.ts';
+import type {
+  LlmOperation,
+  OperationPlan,
+  PlanResponse,
+  PlannedChange,
+  RecommendationQuery
+} from './types.ts';
+
+function filesFor(op: LlmOperation): string[] {
+  switch (op.id) {
+    case 'project-bootstrap':
+      return ['package.json', 'resources/application.yml', 'src/', 'packages/app/'];
+    case 'create-web-route':
+      return ['src/web/', 'src/service/'];
+    case 'enable-file-upload':
+      return ['src/web/', 'src/config/'];
+    case 'enable-auth-session':
+      return ['src/web/auth.ts', 'src/web/auth.config.ts'];
+    case 'rest-rpc-client':
+      return ['src/client/', '__index__.ts'];
+    case 'model-indexed-assistant':
+      return ['src/model/', 'src/service/'];
+    case 'model-query-assistant':
+      return ['src/model/', 'src/service/'];
+    case 'workflow-gcp-deploy':
+      return ['.github/workflows/deploy-api.yml'];
+    case 'workflow-cloudfront-deploy':
+      return ['.github/workflows/deploy-ui.yml'];
+    case 'enable-linting':
+      return ['package.json'];
+    case 'generate-config':
+      return ['src/config/', 'resources/'];
+    case 'generate-test-suite':
+      return ['test/'];
+    case 'create-web-interceptor':
+      return ['src/interceptor/'];
+    case 'email-create-template':
+      return ['src/email/templates/'];
+    case 'email-context-schema':
+      return ['src/email/schema.ts'];
+    case 'email-render-pipeline':
+      return ['src/email/service.ts'];
+    case 'email-transport-provider':
+      return ['src/email/provider.ts', 'src/config/'];
+    case 'email-preview-snapshot':
+      return ['test/email/'];
+    case 'email-send-flow':
+      return ['src/web/', 'src/worker/'];
+    case 'email-test-fixtures':
+      return ['test/email/fixtures/'];
+    case 'cache-enhancements':
+      return ['src/service/', 'src/config/'];
+    default:
+      return ['src/'];
+  }
+}
+
+function changesFor(op: LlmOperation): PlannedChange[] {
+  return [
+    {
+      stepId: 'validate-assumptions',
+      step: 'Validate command and module assumptions',
+      files: [],
+      rationale: 'Use cli schema and module metadata to avoid stale command signatures.'
+    },
+    {
+      stepId: 'generate-artifacts',
+      step: 'Generate core implementation artifacts',
+      files: filesFor(op),
+      rationale: op.summary
+    },
+    {
+      stepId: 'verify-output',
+      step: 'Run verification checks',
+      files: [],
+      rationale: 'Compile, lint, and test generated code paths before apply confirmation.'
+    }
+  ];
+}
+
+function toPlan(op: LlmOperation): OperationPlan {
+  return {
+    operationId: op.id,
+    title: op.title,
+    requiredModules: op.requiredModules,
+    optionalModules: op.optionalModules,
+    changes: changesFor(op)
+  };
+}
+
+export async function buildPlans(query: RecommendationQuery = {}): Promise<PlanResponse> {
+  const operations = query.operations && query.operations.length > 0 ?
+    recommendOperations({
+      categories: query.categories,
+      includeExcluded: query.includeExcluded
+    }).filter(item => query.operations?.includes(item.id)) :
+    recommendOperations({
+      categories: query.categories,
+      includeExcluded: query.includeExcluded
+    });
+
+  const plans = operations.map(toPlan);
+  const snippets = (await recommend({
+    ...query,
+    operations: plans.map(item => item.operationId)
+  })).snippets;
+
+  return { plans, snippets };
+}