@travetto/llm-support 8.0.0-alpha.20

package/src/types.ts

@@ -0,0 +1,215 @@
+import { MinLength, Required, Schema } from '@travetto/schema';
+
+export type AdapterNeed = 'blob' | 'query' | 'indexed' | 'expiry';
+
+export type LlmOperationCategory =
+  | 'project'
+  | 'web'
+  | 'auth'
+  | 'model'
+  | 'upload'
+  | 'workflow'
+  | 'quality'
+  | 'email'
+  | 'test'
+  | 'config'
+  | 'cache';
+
+export type ExecutionArtifactStatus = 'planned' | 'created' | 'skipped';
+export type PlanStepId = 'validate-assumptions' | 'generate-artifacts' | 'verify-output';
+
+@Schema()
+export class DependencyGraphNodeSchema {
+  package = '';
+  requires: string[] = [];
+  optionalAdapters: string[] = [];
+}
+
+@Schema()
+export class RecommendationQuerySchema {
+  @Required(false)
+  bundles?: string[];
+
+  @Required(false)
+  workflows?: string[];
+
+  @Required(false)
+  operations?: string[];
+
+  @Required(false)
+  categories?: LlmOperationCategory[];
+
+  @Required(false)
+  snippetTags?: string[];
+
+  @Required(false)
+  includeExcluded?: boolean;
+}
+
+@Schema()
+export class LlmSupportRecommendToolInput extends RecommendationQuerySchema { }
+
+@Schema()
+export class LlmSupportPlanToolInput extends RecommendationQuerySchema { }
+
+@Schema()
+export class LlmSupportExecuteToolInput {
+  @MinLength(1)
+  operations: string[] = [];
+
+  @MinLength(1)
+  targetDir = '.';
+
+  @Required(false)
+  apply?: boolean;
+
+  @Required(false)
+  overwrite?: boolean;
+
+  @Required(false)
+  monorepo?: boolean;
+
+  @Required(false)
+  workspacePath?: string;
+
+  @Required(false)
+  workspaceName?: string;
+
+  @Required(false)
+  routePath?: string;
+
+  @Required(false)
+  controllerName?: string;
+
+  @Required(false)
+  serviceName?: string;
+
+  @Required(false)
+  modelName?: string;
+
+  @Required(false)
+  projectName?: string;
+
+  @Required(false)
+  emailName?: string;
+
+  @Required(false)
+  sendRoutePath?: string;
+}
+
+@Schema()
+export class InstallGuidanceSchema {
+  id = '';
+  title = '';
+  required: string[] = [];
+  optional: string[] = [];
+  notes: string[] = [];
+}
+
+@Schema()
+export class WorkflowGuidanceSchema {
+  id = '';
+  title = '';
+  intent = '';
+  recommendedModules: string[] = [];
+  optionalModules: string[] = [];
+  commandDiscoveryRule = '';
+  verification: string[] = [];
+}
+
+@Schema()
+export class LlmOperationSchema {
+  id = '';
+  category: LlmOperationCategory = 'project';
+  title = '';
+  summary = '';
+  requiredModules: string[] = [];
+  optionalModules: string[] = [];
+
+  @Required(false)
+  excluded?: boolean;
+}
+
+@Schema()
+export class SnippetSourceSchema {
+  sourceId = '';
+  repositoryId = '';
+  filePath = '';
+  capabilityTags: string[] = [];
+
+  @Required(false)
+  operationIds?: string[];
+
+  @Required(false)
+  applicability?: string[];
+
+  notes: string[] = [];
+}
+
+@Schema()
+export class PlannedChangeSchema {
+  stepId: PlanStepId = 'generate-artifacts';
+  step = '';
+  files: string[] = [];
+  rationale = '';
+}
+
+@Schema()
+export class OperationPlanSchema {
+  operationId = '';
+  title = '';
+  requiredModules: string[] = [];
+  optionalModules: string[] = [];
+  changes: PlannedChangeSchema[] = [];
+}
+
+@Schema()
+export class ExecutionArtifactSchema {
+  operationId = '';
+  file = '';
+  status: ExecutionArtifactStatus = 'planned';
+
+  @Required(false)
+  stepId?: PlanStepId;
+
+  @Required(false)
+  reason?: string;
+}
+
+@Schema()
+export class RecommendationResponseSchema {
+  bundles: InstallGuidanceSchema[] = [];
+  workflows: WorkflowGuidanceSchema[] = [];
+  operations: LlmOperationSchema[] = [];
+  snippets: SnippetSourceSchema[] = [];
+}
+
+@Schema()
+export class PlanResponseSchema {
+  plans: OperationPlanSchema[] = [];
+  snippets: SnippetSourceSchema[] = [];
+}
+
+@Schema()
+export class ExecutionResponseSchema {
+  dryRun = true;
+  targetDir = '';
+  artifacts: ExecutionArtifactSchema[] = [];
+  warnings: string[] = [];
+}
+
+export type DependencyGraphNode = InstanceType<typeof DependencyGraphNodeSchema>;
+export type RecommendationQuery = InstanceType<typeof RecommendationQuerySchema>;
+export type InstallGuidance = InstanceType<typeof InstallGuidanceSchema>;
+export type WorkflowGuidance = InstanceType<typeof WorkflowGuidanceSchema>;
+export type LlmOperation = InstanceType<typeof LlmOperationSchema>;
+export type SnippetSource = InstanceType<typeof SnippetSourceSchema>;
+export type PlannedChange = InstanceType<typeof PlannedChangeSchema>;
+export type OperationPlan = InstanceType<typeof OperationPlanSchema>;
+export type RecommendationResponse = InstanceType<typeof RecommendationResponseSchema>;
+export type PlanResponse = InstanceType<typeof PlanResponseSchema>;
+export type ExecutionArtifact = InstanceType<typeof ExecutionArtifactSchema>;
+export type ExecutionResponse = InstanceType<typeof ExecutionResponseSchema>;
+export type ExecutionRequest = Omit<InstanceType<typeof LlmSupportExecuteToolInput>, 'apply'> & {
+  dryRun?: boolean;
+};

package/src/workflow-guidance.ts

@@ -0,0 +1,220 @@
+import { type WorkflowGuidance } from './types.ts';
+
+export const WORKFLOWS: WorkflowGuidance[] = [
+  {
+    id: 'build-api-service',
+    title: 'Build a REST API service',
+    intent: 'Expose schema-backed endpoints with DI-managed services.',
+    recommendedModules: ['@travetto/web', '@travetto/schema', '@travetto/di', '@travetto/config'],
+    optionalModules: ['@travetto/openapi', '@travetto/auth', '@travetto/auth-web'],
+    commandDiscoveryRule: 'If CLI command shape is uncertain, validate with npx trv cli:schema before recommending command arguments.',
+    verification: [
+      'Confirm endpoint decorators and schema decorators are documented in module LLM consumer docs.',
+      'Confirm generated guidance is consistent with current CLI schema output.'
+    ]
+  },
+  {
+    id: 'enable-persistence',
+    title: 'Enable persistent model storage',
+    intent: 'Provide model contracts and adapter-backed persistence with one adapter family choice (SQL or non-SQL).',
+    recommendedModules: ['@travetto/model'],
+    optionalModules: [
+      '@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'
+    ],
+    commandDiscoveryRule: 'Use npx trv cli:schema before proposing model:install or model:export argument forms.',
+    verification: [
+      'Ensure selected adapter family and module match datastore target and install bundle guidance.',
+      'Ensure required capability needs (blob/query/indexed/expiry) align with selected adapter support.'
+    ]
+  },
+  {
+    id: 'run-background-jobs',
+    title: 'Run worker-based background jobs',
+    intent: 'Process asynchronous or scheduled work safely across shutdown boundaries.',
+    recommendedModules: ['@travetto/worker', '@travetto/runtime', '@travetto/config'],
+    optionalModules: ['@travetto/model', '@travetto/context', '@travetto/log'],
+    commandDiscoveryRule: 'Validate worker command patterns with npx trv cli:schema whenever command signatures are referenced.',
+    verification: [
+      'Ensure shutdown behavior and lifecycle guidance references runtime abstractions.',
+      'Confirm job storage guidance aligns with selected model adapter.'
+    ]
+  },
+  {
+    id: 'enable-google-oauth-passport',
+    title: 'Enable Google OAuth with Passport',
+    intent: 'Configure auth-web-passport with Google OAuth strategy and map provider profile to application principal.',
+    recommendedModules: ['@travetto/web', '@travetto/auth', '@travetto/auth-web', '@travetto/auth-web-passport', '@travetto/config'],
+    optionalModules: ['@travetto/model', '@travetto/model-indexed', '@travetto/model-firestore', '@travetto/auth-model'],
+    commandDiscoveryRule: 'Validate auth and web command signatures with npx trv cli:schema before recommending CLI invocations.',
+    verification: [
+      'Ensure google.auth config includes clientID, clientSecret, and callbackUrl.',
+      'Ensure a PassportAuthenticator is registered with Google OAuth strategy and stable principal mapping.',
+      'If user persistence is required, ensure external-id lookup/index and one model adapter are configured.'
+    ]
+  },
+  {
+    id: 'project-bootstrap',
+    title: 'Bootstrap a new project',
+    intent: 'Create a project baseline using guided prompts for model backend, quality, and initial web stack.',
+    recommendedModules: ['@travetto/web', '@travetto/web-http', '@travetto/openapi', '@travetto/runtime', '@travetto/config'],
+    optionalModules: ['@travetto/schema', '@travetto/di', '@travetto/model', '@travetto/test', '@travetto/eslint'],
+    commandDiscoveryRule: 'Validate command signatures with npx trv cli:schema before suggesting starter commands.',
+    verification: [
+      'Ensure generated project includes selected web and model modules from prompt answers.',
+      'Ensure generated package scripts include startup, test, and lint commands when selected.'
+    ]
+  },
+  {
+    id: 'create-web-route',
+    title: 'Create route/controller/service',
+    intent: 'Generate web route handlers with controller and service separation, aligned with schema and DI conventions.',
+    recommendedModules: ['@travetto/web', '@travetto/schema', '@travetto/di'],
+    optionalModules: ['@travetto/auth', '@travetto/auth-web', '@travetto/model-query'],
+    commandDiscoveryRule: 'Validate web and schema command references with npx trv cli:schema before publishing examples.',
+    verification: [
+      'Ensure route methods use controller decorators and typed parameter bindings.',
+      'Ensure service wiring uses @Injectable and @Inject patterns.'
+    ]
+  },
+  {
+    id: 'enable-auth-session',
+    title: 'Enable auth with sessions',
+    intent: 'Configure login/self/logout with session-backed identity in local memory.',
+    recommendedModules: ['@travetto/auth', '@travetto/auth-web', '@travetto/auth-session', '@travetto/auth-web-session', '@travetto/model-memory'],
+    optionalModules: ['@travetto/model', '@travetto/model-indexed', '@travetto/web'],
+    commandDiscoveryRule: 'Validate auth-web decorators and auth command references with npx trv cli:schema before publishing examples.',
+    verification: [
+      'Ensure auth config exposes authenticator, authorizer, and session store factories.',
+      'Ensure /auth/login, /auth/self, and /auth/logout routes are registered and session-aware.'
+    ]
+  },
+  {
+    id: 'generate-web-model-crud',
+    title: 'Generate web-model CRUD API',
+    intent: 'Generate web + model CRUD patterns from curated templates and adapt to domain classes.',
+    recommendedModules: ['@travetto/web', '@travetto/model', '@travetto/model-query', '@travetto/schema', '@travetto/di'],
+    optionalModules: ['@travetto/auth', '@travetto/auth-web', '@travetto/model-indexed'],
+    commandDiscoveryRule: 'Validate web/controller command references and generated route assumptions with npx trv cli:schema.',
+    verification: [
+      'Ensure controller CRUD methods bind to a model-query capable source.',
+      'Ensure principal-scoped filtering is applied when auth-web integration is enabled.'
+    ]
+  },
+  {
+    id: 'model-backend-selection',
+    title: 'Model backend selection',
+    intent: 'Choose one supported datastore adapter and align model service/config classes.',
+    recommendedModules: ['@travetto/model'],
+    optionalModules: [
+      '@travetto/model-elasticsearch',
+      '@travetto/model-mongo',
+      '@travetto/model-sql',
+      '@travetto/model-mysql',
+      '@travetto/model-postgres',
+      '@travetto/model-sqlite'
+    ],
+    commandDiscoveryRule: 'Validate model command signatures and adapter setup commands with npx trv cli:schema before recommendation output.',
+    verification: [
+      'Ensure selected adapter is supported and matches deployment datastore target.',
+      'Ensure SQL-family selections include shared SQL runtime package requirements.'
+    ]
+  },
+  {
+    id: 'quality-lint-and-test',
+    title: 'Enable lint and test quality checks',
+    intent: 'Enable quality features so generated projects have immediate test and lint feedback loops.',
+    recommendedModules: ['@travetto/test', '@travetto/eslint'],
+    optionalModules: [],
+    commandDiscoveryRule: 'Validate test and lint command examples with npx trv cli:schema or generated package scripts before suggesting execution.',
+    verification: [
+      'Ensure generated package scripts include test and lint commands when selected.',
+      'Run test and lint once after generation to catch template/config drift early.'
+    ]
+  },
+  {
+    id: 'add-email-generation',
+    title: 'Add email generation and delivery',
+    intent: 'Generate template, schema contract, compiler pipeline, provider wiring, and send integration for email flows.',
+    recommendedModules: ['@travetto/email'],
+    optionalModules: ['@travetto/email-compiler', '@travetto/email-inky', '@travetto/email-nodemailer', '@travetto/worker'],
+    commandDiscoveryRule: 'Validate command signatures with npx trv cli:schema before recommending email generation commands.',
+    verification: [
+      'Ensure generated template context has a typed schema contract.',
+      'Ensure renderer and transport wiring are both validated by tests or snapshots.',
+      'Ensure send integration supports direct and worker-based execution paths.'
+    ]
+  },
+  {
+    id: 'openapi-spec-pipeline',
+    title: 'Add OpenAPI spec pipeline',
+    intent: 'Generate and persist OpenAPI specs as build artifacts and optionally commit outputs.',
+    recommendedModules: ['@travetto/openapi', '@travetto/web', '@travetto/schema'],
+    optionalModules: ['@travetto/cli'],
+    commandDiscoveryRule: 'Validate OpenAPI command signatures with npx trv cli:schema before recommending command invocations.',
+    verification: [
+      'Ensure openapi:spec output path and format match repository conventions.',
+      'Ensure generated spec is available as CI artifact for downstream use.'
+    ]
+  },
+  {
+    id: 'openapi-client-generation',
+    title: 'Add OpenAPI client generation workflow',
+    intent: 'Generate API clients from OpenAPI artifacts and keep them synchronized with endpoint changes.',
+    recommendedModules: ['@travetto/openapi'],
+    optionalModules: ['@travetto/web-rpc', '@travetto/web'],
+    commandDiscoveryRule: 'Validate openapi:client command signatures with npx trv cli:schema before recommending formats or arguments.',
+    verification: [
+      'Ensure generated client output location is stable and committed when required.',
+      'Ensure workflow runs after spec generation and fails fast on generator errors.'
+    ]
+  },
+  {
+    id: 'aws-lambda-package-and-deploy',
+    title: 'Add AWS Lambda package and deploy workflow',
+    intent: 'Package web entrypoint for AWS Lambda and deploy artifacts through CI.',
+    recommendedModules: ['@travetto/web-aws-lambda', '@travetto/pack'],
+    optionalModules: ['@travetto/web', '@travetto/config'],
+    commandDiscoveryRule: 'Validate pack:lambda command signatures with npx trv cli:schema before recommending packaging flags.',
+    verification: [
+      'Ensure lambda package artifact is produced and published by CI.',
+      'Ensure workflow includes environment-specific deploy step stubs.'
+    ]
+  },
+  {
+    id: 'pack-docker-release',
+    title: 'Add Docker pack release workflow',
+    intent: 'Build and publish container images from Travetto pack:docker in CI.',
+    recommendedModules: ['@travetto/pack'],
+    optionalModules: ['@travetto/runtime', '@travetto/config'],
+    commandDiscoveryRule: 'Validate pack:docker command signatures with npx trv cli:schema before recommending image/tag flags.',
+    verification: [
+      'Ensure image tags, registry targets, and build platform inputs are explicit.',
+      'Ensure workflow supports dry runs or stage-only builds for PR validation.'
+    ]
+  },
+  {
+    id: 'repo-version-release',
+    title: 'Add repo version release flow',
+    intent: 'Automate monorepo versioning with change-aware release mode and optional tagging.',
+    recommendedModules: ['@travetto/repo'],
+    optionalModules: ['@travetto/registry', '@travetto/pack'],
+    commandDiscoveryRule: 'Validate repo:version and repo:publish command signatures with npx trv cli:schema before suggesting release automation.',
+    verification: [
+      'Ensure release mode and semver level are explicit and reviewed in CI inputs.',
+      'Ensure release commits and tags align with repository policy.'
+    ]
+  }
+];

package/support/base-command.ts

@@ -0,0 +1,57 @@
+import { CliFlag, CliModuleFlag, type CliCommandShape } from '@travetto/cli';
+import { Required } from '@travetto/schema';
+import { JSONUtil } from '@travetto/runtime';
+
+import { getValidOperationIds, LLM_OPERATION_CATEGORIES } from '../src/recommendation.ts';
+import { getValidSnippetTags } from '../src/snippet-catalog.ts';
+import type { LlmOperationCategory } from '../src/types.ts';
+
+interface LlmSupportValidValues {
+  categories: readonly LlmOperationCategory[];
+  operations: string[];
+  snippetTags: string[];
+}
+
+export abstract class LlmSupportCommandBase implements CliCommandShape {
+
+  @CliModuleFlag(({ scope: 'command' }))
+  module: string = '';
+
+  async getValidValues(includeExcluded: boolean): Promise<LlmSupportValidValues> {
+    return {
+      categories: LLM_OPERATION_CATEGORIES,
+      operations: getValidOperationIds(includeExcluded),
+      snippetTags: await getValidSnippetTags()
+    };
+  }
+
+  async writeOutput(payload: object, includeExcluded: boolean): Promise<void> {
+    const valid = await this.getValidValues(includeExcluded);
+    process.stdout.write(`${JSONUtil.toUTF8({ ...payload, valid }, { indent: 2 })}\n`);
+  }
+
+  abstract main(): Promise<void>;
+}
+
+export abstract class LlmSupportScopedCommandBase extends LlmSupportCommandBase {
+
+  @CliFlag({ short: 'c', full: 'categories' })
+  @Required(false)
+  categories?: LlmOperationCategory[];
+
+  @CliFlag({ full: 'include-excluded' })
+  includeExcluded = false;
+
+  getScopedCategories(): LlmOperationCategory[] {
+    return this.categories?.filter(item =>
+      LLM_OPERATION_CATEGORIES.some(allowed => allowed === item)
+    ) ?? [];
+  }
+}
+
+export abstract class LlmSupportScopedSnippetCommandBase extends LlmSupportScopedCommandBase {
+
+  @CliFlag({ short: 't', full: 'snippet-tags' })
+  @Required(false)
+  snippetTags?: string[];
+}

package/support/cli.llm_support_execute.ts

@@ -0,0 +1,80 @@
+import path from 'node:path';
+
+import { CliCommand, CliFlag } from '@travetto/cli';
+import { MinLength } from '@travetto/schema';
+
+import { executeOperations } from '../src/execute.ts';
+import { LlmSupportCommandBase } from './base-command.ts';
+
+/**
+ * Execute llm-support operations with dry-run by default.
+ */
+@CliCommand()
+export class LlmSupportExecuteCommand extends LlmSupportCommandBase {
+
+  @CliFlag({ short: 'o', full: 'operations' })
+  @MinLength(1)
+  operations?: string[];
+
+  @CliFlag({ short: 'd', full: 'dir' })
+  targetDir = process.cwd();
+
+  @CliFlag({ full: 'apply' })
+  apply = false;
+
+  @CliFlag({ full: 'overwrite' })
+  overwrite = false;
+
+  @CliFlag({ full: 'monorepo' })
+  monorepo = false;
+
+  @CliFlag({ full: 'workspace-path' })
+  workspacePath?: string;
+
+  @CliFlag({ full: 'workspace-name' })
+  workspaceName?: string;
+
+  @CliFlag({ full: 'route-path' })
+  routePath?: string;
+
+  @CliFlag({ full: 'controller-name' })
+  controllerName?: string;
+
+  @CliFlag({ full: 'service-name' })
+  serviceName?: string;
+
+  @CliFlag({ full: 'model-name' })
+  modelName?: string;
+
+  @CliFlag({ full: 'project-name' })
+  projectName?: string;
+
+  @CliFlag({ full: 'email-name' })
+  emailName?: string;
+
+  @CliFlag({ full: 'send-route-path' })
+  sendRoutePath?: string;
+
+  async main(): Promise<void> {
+    const operations = this.operations ?? [];
+
+    const payload = await executeOperations({
+      operations,
+      targetDir: path.resolve(this.targetDir),
+      dryRun: !this.apply,
+      overwrite: this.overwrite,
+      monorepo: this.monorepo,
+      workspacePath: this.workspacePath,
+      workspaceName: this.workspaceName,
+      routePath: this.routePath,
+      controllerName: this.controllerName,
+      serviceName: this.serviceName,
+      modelName: this.modelName,
+      projectName: this.projectName,
+      emailName: this.emailName,
+      sendRoutePath: this.sendRoutePath
+    });
+
+    await this.writeOutput(payload, true);
+  }
+}

package/support/cli.llm_support_mcp.ts

@@ -0,0 +1,62 @@
+import { createInterface } from 'node:readline';
+
+import { CliCommand, type CliCommandShape } from '@travetto/cli';
+import { JSONUtil } from '@travetto/runtime';
+
+import { handleMcpRequest, type JsonRpcRequest } from '../src/mcp.ts';
+
+/**
+ * Minimal MCP stdio server for llm-support tools.
+ */
+@CliCommand()
+export class LlmSupportMcpCommand implements CliCommandShape {
+  async main(): Promise<void> {
+    const rl = createInterface({
+      input: process.stdin,
+      crlfDelay: Infinity
+    });
+
+    const active: Promise<void>[] = [];
+
+    const processLine = async (line: string): Promise<void> => {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        return;
+      }
+
+      let request: JsonRpcRequest;
+      try {
+        request = JSONUtil.fromUTF8(trimmed);
+      } catch {
+        const parseError = {
+          jsonrpc: '2.0',
+          id: null,
+          error: {
+            code: -32700,
+            message: 'Parse error'
+          }
+        };
+        process.stdout.write(`${JSONUtil.toUTF8(parseError)}\n`);
+        return;
+      }
+
+      const response = await handleMcpRequest(request);
+      if (response) {
+        process.stdout.write(`${JSONUtil.toUTF8(response)}\n`);
+      }
+    };
+
+    rl.on('line', line => {
+      const run = processLine(line).finally(() => {
+        const idx = active.indexOf(run);
+        if (idx >= 0) {
+          active.splice(idx, 1);
+        }
+      });
+      active.push(run);
+    });
+
+    await new Promise<void>(resolve => rl.on('close', resolve));
+    await Promise.all(active);
+  }
+}

package/support/cli.llm_support_plan.ts

@@ -0,0 +1,30 @@
+import { CliCommand, CliFlag } from '@travetto/cli';
+import { MinLength, Required } from '@travetto/schema';
+
+import { buildPlans } from '../src/plan.ts';
+import { LlmSupportScopedSnippetCommandBase } from './base-command.ts';
+
+/**
+ * Build plan-first execution details for llm-support operations.
+ */
+@CliCommand()
+export class LlmSupportPlanCommand extends LlmSupportScopedSnippetCommandBase {
+
+  @CliFlag({ short: 'o', full: 'operations' })
+  @Required(false)
+  @MinLength(1)
+  operations?: string[];
+
+  async main(): Promise<void> {
+    const categories = this.getScopedCategories();
+
+    const payload = await buildPlans({
+      operations: this.operations?.filter(Boolean) ?? [],
+      categories,
+      snippetTags: this.snippetTags?.filter(Boolean) ?? [],
+      includeExcluded: this.includeExcluded
+    });
+
+    await this.writeOutput(payload, this.includeExcluded);
+  }
+}