@specverse/engines 4.1.0

package/libs/instance-factories/scaffolding/templates/generic/gitignore-generator.ts

@@ -0,0 +1,69 @@
+/**
+ * Generic .gitignore Generator
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generateGitIgnore(context: TemplateContext): string {
+  const { manifest } = context;
+
+  const ignorePatterns = [
+    '# Dependencies',
+    'node_modules/',
+    '',
+    '# Build output',
+    'dist/',
+    'build/',
+    '',
+    '# Environment',
+    '.env',
+    '.env.local',
+    '.env.*.local',
+    '',
+    '# TypeScript',
+    '*.tsbuildinfo',
+    '',
+    '# Logs',
+    'logs/',
+    '*.log',
+    'npm-debug.log*',
+    '',
+  ];
+
+  // Add Prisma specific ignores if using Prisma
+  if (usesPrisma(manifest)) {
+    ignorePatterns.push(
+      '# Prisma',
+      'prisma/migrations/',
+      '',
+    );
+  }
+
+  ignorePatterns.push(
+    '# IDE',
+    '.vscode/',
+    '.idea/',
+    '*.swp',
+    '*.swo',
+    '',
+    '# OS',
+    '.DS_Store',
+    'Thumbs.db',
+    '',
+    '# Testing',
+    'coverage/',
+    '.nyc_output/'
+  );
+
+  return ignorePatterns.join('\n');
+}
+
+function usesPrisma(manifest: any): boolean {
+  if (!manifest || !manifest.capabilityMappings) {
+    return false;
+  }
+
+  return manifest.capabilityMappings.some((m: any) =>
+    m.instanceFactory?.toLowerCase().includes('prisma')
+  );
+}

package/libs/instance-factories/scaffolding/templates/generic/package-json-generator.ts

@@ -0,0 +1,176 @@
+/**
+ * Generic Package.json Generator
+ *
+ * Aggregates requirements from all implementation types in manifest
+ * and generates a complete package.json file
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generatePackageJson(context: TemplateContext): string {
+  const { spec, manifest, configuration } = context;
+
+  // Check if we're in monorepo mode
+  const outputStructure = configuration?.outputStructure || 'monorepo';
+  const isMonorepo = outputStructure === 'monorepo';
+
+  // Aggregate requirements from all implementation types
+  const aggregated = aggregateRequirements(context.instanceFactories || context.implementationTypes || []);
+
+  const pkg: any = {
+    name: (spec.metadata?.component || 'specverse-app')
+      .toLowerCase()
+      .replace(/\s+/g, '-'),
+    version: spec.metadata?.version || '1.0.0',
+    description: spec.metadata?.description || '',
+    private: true,
+    type: 'module'
+  };
+
+  // Add workspaces for monorepo
+  if (isMonorepo) {
+    const frontendDir = configuration?.frontendDir || 'frontend';
+    const backendDir = configuration?.backendDir || 'backend';
+
+    pkg.workspaces = [backendDir, frontendDir];
+
+    // Add convenience scripts for monorepo
+    pkg.scripts = {
+      // Build all workspaces
+      'build': 'npm run build --workspaces',
+      'build:backend': `npm run build --workspace=${backendDir}`,
+      'build:frontend': `npm run build --workspace=${frontendDir}`,
+
+      // Production
+      'start': `npm run start --workspace=${backendDir}`,
+
+      // Development
+      'dev': 'npm run dev --workspaces',
+      'dev:backend': `npm run dev --workspace=${backendDir}`,
+      'dev:frontend': `npm run dev --workspace=${frontendDir}`,
+
+      // Testing
+      'test': 'npm test --workspaces',
+      'test:backend': `npm test --workspace=${backendDir}`,
+      'test:frontend': `npm test --workspace=${frontendDir}`,
+
+      // Database management (backend)
+      'db:setup': `npm run db:setup --workspace=${backendDir}`,
+      'db:generate': `npm run db:generate --workspace=${backendDir}`,
+      'db:push': `npm run db:push --workspace=${backendDir}`,
+      'db:migrate': `npm run db:migrate --workspace=${backendDir}`,
+      'db:studio': `npm run db:studio --workspace=${backendDir}`,
+
+      // Linting
+      'lint': 'npm run lint --workspaces',
+      'lint:fix': 'npm run lint:fix --workspaces'
+    };
+  } else {
+    // Standalone mode - merge all scripts
+    pkg.scripts = {
+      ...aggregated.scripts,
+      // Ensure we have build script if TypeScript
+      ...(aggregated.usesTypeScript && !aggregated.scripts.build && {
+        build: 'tsc'
+      }),
+      // Add database setup script
+      'db:setup': 'node -e "const{execSync:e}=require(\'child_process\');const{readFileSync:r}=require(\'fs\');try{const d=r(\'.env\',\'utf8\').match(/DATABASE_URL=.*\\/([^?\\"]+)/)?.[1];if(!d)throw new Error(\'DATABASE_URL not found\');console.log(\'Creating database:\',d);try{e(\'createdb \'+d)}catch(err){const errMsg=err.stderr?err.stderr.toString():err.message;if(errMsg.includes(\'already exists\')){console.log(\'✅ Database already exists\')}else throw err}console.log(\'✅ Database created successfully\')}catch(err){console.error(\'❌ Database setup failed:\',err.message);process.exit(1)}"',
+      // Add test script if not provided by implementation types
+      ...(!aggregated.scripts.test && {
+        test: 'echo "Error: no test specified" && exit 1'
+      })
+    };
+
+    // In standalone mode, include dependencies
+    pkg.dependencies = aggregated.dependencies;
+    pkg.devDependencies = {
+      ...aggregated.devDependencies,
+      // Ensure TypeScript is present if needed
+      ...(aggregated.usesTypeScript && !aggregated.devDependencies.typescript && {
+        typescript: '^5.3.0',
+        '@types/node': '^20.0.0'
+      })
+    };
+
+    // TypeScript-specific fields
+    if (aggregated.usesTypeScript) {
+      pkg.main = 'dist/main.js';
+      pkg.types = 'dist/main.d.ts';
+    }
+  }
+
+  // Add common Node.js fields
+  pkg.engines = {
+    node: '>=18.0.0'
+  };
+
+  return JSON.stringify(pkg, null, 2);
+}
+
+/**
+ * Aggregate requirements from all implementation types
+ */
+function aggregateRequirements(implementationTypes: any[]) {
+  const result = {
+    dependencies: {} as Record<string, string>,
+    devDependencies: {} as Record<string, string>,
+    scripts: {} as Record<string, string>,
+    environment: [] as any[],
+    usesTypeScript: false,
+    usesDocker: false
+  };
+
+  if (!implementationTypes || implementationTypes.length === 0) {
+    return result;
+  }
+
+  // Iterate through all implementation types
+  for (const implType of implementationTypes) {
+    // Handle dependencies from the top level (v3.3 format)
+    if (implType.dependencies) {
+      // Runtime dependencies
+      if (implType.dependencies.runtime && Array.isArray(implType.dependencies.runtime)) {
+        for (const dep of implType.dependencies.runtime) {
+          if (dep.name && dep.version) {
+            result.dependencies[dep.name] = dep.version;
+          }
+        }
+      }
+      // Dev dependencies
+      if (implType.dependencies.dev && Array.isArray(implType.dependencies.dev)) {
+        for (const dep of implType.dependencies.dev) {
+          if (dep.name && dep.version) {
+            result.devDependencies[dep.name] = dep.version;
+          }
+        }
+      }
+    }
+
+    // Also handle old requirements.dependencies.npm structure for backwards compatibility
+    const requirements = implType.requirements;
+    if (requirements) {
+      if (requirements.dependencies?.npm) {
+        Object.assign(result.dependencies, requirements.dependencies.npm.dependencies || {});
+        Object.assign(result.devDependencies, requirements.dependencies.npm.devDependencies || {});
+        Object.assign(result.scripts, requirements.dependencies.npm.scripts || {});
+      }
+
+      // Collect environment variables
+      if (requirements.environment) {
+        result.environment.push(...requirements.environment);
+      }
+    }
+
+    // Detect TypeScript usage
+    if (implType.technology?.language === 'typescript') {
+      result.usesTypeScript = true;
+    }
+
+    // Detect Docker usage
+    if (implType.capabilities?.provides?.includes('container.dev')) {
+      result.usesDocker = true;
+    }
+  }
+
+  return result;
+}

package/libs/instance-factories/scaffolding/templates/generic/readme-generator.ts

@@ -0,0 +1,207 @@
+/**
+ * Generic README Generator
+ *
+ * Generates README based on spec and manifest choices
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generateReadme(context: TemplateContext): string {
+  const { spec, manifest } = context;
+
+  const sections: string[] = [];
+
+  // Title and description
+  sections.push(`# ${spec.metadata?.component || 'SpecVerse Application'}`);
+  sections.push('');
+  sections.push(spec.metadata?.description || 'Generated with SpecVerse');
+  sections.push('');
+
+  // Tech stack (inferred from manifest)
+  const techStack = inferTechStack(manifest);
+  if (techStack.length > 0) {
+    sections.push('## Tech Stack');
+    sections.push('');
+    for (const tech of techStack) {
+      sections.push(`- **${tech.category}**: ${tech.items.join(', ')}`);
+    }
+    sections.push('');
+  }
+
+  // Prerequisites
+  sections.push('## Getting Started');
+  sections.push('');
+  sections.push('### Prerequisites');
+  sections.push('');
+  sections.push('- Node.js 18+');
+  sections.push('- npm or yarn');
+
+  if (usesPrisma(manifest)) {
+    sections.push('- PostgreSQL (or your database of choice)');
+  }
+
+  sections.push('');
+
+  // Installation
+  sections.push('### Installation');
+  sections.push('');
+  sections.push('```bash');
+  sections.push('npm install');
+  sections.push('```');
+  sections.push('');
+
+  // Environment setup
+  const hasEnvVars = manifestHasEnvVars(manifest);
+  if (hasEnvVars) {
+    sections.push('### Environment Setup');
+    sections.push('');
+    sections.push('```bash');
+    sections.push('cp .env.example .env');
+    sections.push('```');
+    sections.push('');
+    sections.push('Configure your environment variables in `.env`');
+    sections.push('');
+  }
+
+  // Database setup if using Prisma
+  if (usesPrisma(manifest)) {
+    sections.push('### Database Setup');
+    sections.push('');
+    sections.push('**Important**: Create the database before running Prisma commands.');
+    sections.push('');
+    sections.push('```bash');
+    sections.push('# Create database (PostgreSQL example)');
+    sections.push('createdb your_database_name');
+    sections.push('');
+    sections.push('# Or using psql:');
+    sections.push('# psql postgres');
+    sections.push('# CREATE DATABASE your_database_name;');
+    sections.push('# \\q');
+    sections.push('');
+    sections.push('# Update DATABASE_URL in .env with your database name');
+    sections.push('# DATABASE_URL="postgresql://localhost:5432/your_database_name"');
+    sections.push('');
+    sections.push('# Generate Prisma client');
+    sections.push('npm run db:generate');
+    sections.push('');
+    sections.push('# Push schema to database (for development)');
+    sections.push('npm run db:push');
+    sections.push('');
+    sections.push('# Or use migrations (for production)');
+    sections.push('npm run db:migrate');
+    sections.push('```');
+    sections.push('');
+  }
+
+  // Development
+  sections.push('### Development');
+  sections.push('');
+  sections.push('```bash');
+  sections.push('npm run dev');
+  sections.push('```');
+  sections.push('');
+
+  // Production
+  sections.push('### Production Build');
+  sections.push('');
+  sections.push('```bash');
+  sections.push('npm run build');
+  sections.push('npm start');
+  sections.push('```');
+  sections.push('');
+
+  // API Documentation
+  if (hasRestAPI(manifest)) {
+    sections.push('## API');
+    sections.push('');
+    sections.push('The API server runs on `http://localhost:${PORT}` (default: 3000)');
+    sections.push('');
+
+    // List controllers if present
+    if (spec.controllers && spec.controllers.length > 0) {
+      sections.push('### Endpoints');
+      sections.push('');
+      for (const controller of spec.controllers) {
+        sections.push(`- **${controller.name}**: \`${controller.basePath || '/api'}\``);
+      }
+      sections.push('');
+    }
+  }
+
+  // Generated notice
+  sections.push('---');
+  sections.push('');
+  sections.push('_Generated with [SpecVerse](https://github.com/specverse/specverse-lang)_');
+
+  return sections.join('\n');
+}
+
+function inferTechStack(manifest: any): Array<{category: string, items: string[]}> {
+  const stack: Array<{category: string, items: string[]}> = [];
+
+  if (!manifest || !manifest.capabilityMappings) {
+    return stack;
+  }
+
+  // Runtime
+  stack.push({
+    category: 'Runtime',
+    items: ['Node.js', 'TypeScript']
+  });
+
+  // Framework - extract from capability mapping
+  const apiMapping = manifest.capabilityMappings.find((m: any) =>
+    m.capability === 'api.rest'
+  );
+  if (apiMapping) {
+    stack.push({
+      category: 'Web Framework',
+      items: [apiMapping.instanceFactory]
+    });
+  }
+
+  // ORM - extract from capability mapping
+  const ormMapping = manifest.capabilityMappings.find((m: any) =>
+    m.capability === 'orm.client' || m.capability === 'orm.schema'
+  );
+  if (ormMapping) {
+    stack.push({
+      category: 'ORM',
+      items: [ormMapping.instanceFactory]
+    });
+  }
+
+  return stack;
+}
+
+function usesPrisma(manifest: any): boolean {
+  if (!manifest || !manifest.capabilityMappings) {
+    return false;
+  }
+
+  return manifest.capabilityMappings.some((m: any) =>
+    m.instanceFactory?.toLowerCase().includes('prisma')
+  );
+}
+
+function hasRestAPI(manifest: any): boolean {
+  if (!manifest || !manifest.capabilityMappings) {
+    return false;
+  }
+
+  return manifest.capabilityMappings.some((m: any) =>
+    m.capability === 'api.rest'
+  );
+}
+
+function manifestHasEnvVars(manifest: any): boolean {
+  // In v3.3, we always assume there are env vars if we have database or server config
+  if (!manifest || !manifest.capabilityMappings) {
+    return false;
+  }
+
+  // Check if there are database or API capabilities (they typically need env vars)
+  return manifest.capabilityMappings.some((m: any) =>
+    m.capability === 'storage.database' || m.capability === 'api.rest'
+  );
+}

package/libs/instance-factories/scaffolding/templates/generic/tsconfig-generator.ts

@@ -0,0 +1,78 @@
+/**
+ * Generic TSConfig Generator
+ *
+ * Generates TypeScript configuration based on manifest choices
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generateTsConfig(context: TemplateContext): string {
+  const { manifest, spec } = context;
+
+  // Extract TypeScript options from implementation types
+  const mergedOptions = extractTsConfigOptions(context.implementationTypes || []);
+
+  // Detect if we're using React - check both implementation types AND if we have views in the spec
+  const hasViews = spec && (spec.views || (Array.isArray(spec.views) && spec.views.length > 0));
+  const usesReact = hasViews && (context.implementationTypes || []).some((implType: any) =>
+    implType.capabilities?.provides?.includes('ui.components') &&
+    implType.technology?.framework === 'react'
+  );
+
+  // Base tsconfig for backend code
+  const tsconfig = {
+    compilerOptions: {
+      // Defaults
+      target: 'ES2022',
+      module: 'ESNext',
+      moduleResolution: 'node',
+      lib: ['ES2022'],
+      outDir: './dist',
+      rootDir: './src',
+
+      // Strict mode
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+
+      // Module resolution
+      resolveJsonModule: true,
+      allowSyntheticDefaultImports: true,
+
+      // Output
+      declaration: true,
+      declarationMap: true,
+      sourceMap: true,
+
+      // Merge options from implementation types
+      ...mergedOptions
+    },
+    include: usesReact ? ['src/**/*.ts'] : ['src/**/*'],  // Exclude .tsx files if React is used
+    exclude: usesReact
+      ? ['node_modules', 'dist', '**/*.test.ts', '**/*.spec.ts', 'src/components/**', 'src/hooks/**', 'src/types/**']  // Exclude React-specific dirs
+      : ['node_modules', 'dist', '**/*.test.ts', '**/*.spec.ts'],
+    ...(usesReact && {
+      references: [{ path: './tsconfig.react.json' }]  // Reference React config
+    })
+  };
+
+  return JSON.stringify(tsconfig, null, 2);
+}
+
+function extractTsConfigOptions(implementationTypes: any[]): any {
+  const options: any = {};
+
+  if (!implementationTypes || implementationTypes.length === 0) {
+    return options;
+  }
+
+  for (const implType of implementationTypes) {
+    // Access from generic configuration.tsconfig structure
+    if (implType.requirements?.configuration?.tsconfig?.compilerOptions) {
+      Object.assign(options, implType.requirements.configuration.tsconfig.compilerOptions);
+    }
+  }
+
+  return options;
+}

package/libs/instance-factories/scaffolding/templates/generic/tsconfig-react-generator.ts

@@ -0,0 +1,41 @@
+/**
+ * React TSConfig Generator
+ *
+ * Generates TypeScript configuration for React components with bundler module resolution
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generateReactTsConfig(context: TemplateContext): string {
+  const tsconfigReact = {
+    extends: './tsconfig.json',
+    compilerOptions: {
+      // React/Vite specific settings
+      moduleResolution: 'bundler',
+      lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+      jsx: 'react-jsx',
+      jsxImportSource: 'react',
+      types: ['vite/client'],
+
+      // Allow importing .ts/.tsx files with extensions
+      allowImportingTsExtensions: true,
+
+      // Project reference settings
+      composite: true,
+      outDir: './dist/react'
+    },
+    include: ['src/**/*.tsx', 'src/**/*.ts'],
+    exclude: [
+      'node_modules',
+      'dist',
+      '**/*.test.ts',
+      '**/*.spec.ts',
+      'src/main.ts',  // Backend entry point
+      'src/controllers/**',  // Backend controllers
+      'src/routes/**',  // Backend routes
+      'src/services/**'  // Backend services (if any)
+    ]
+  };
+
+  return JSON.stringify(tsconfigReact, null, 2);
+}

package/libs/instance-factories/sdks/README.md

@@ -0,0 +1,28 @@
+# SDKs Instance Factory
+
+Generates typed client SDKs for consuming REST APIs produced by a SpecVerse specification.
+
+## Definitions
+
+- **`python-sdk.yaml`** -- Python SDK with async support (aiohttp + Pydantic)
+- **`typescript-sdk.yaml`** -- TypeScript SDK with native fetch (zero runtime dependencies)
+
+## Generators
+
+- `templates/python/sdk-generator.ts` -- Wraps `generate-sdk-python.js` (1000+ lines). Produces a complete Python package: async client class, per-controller resource classes, Pydantic models, exception classes, `setup.py`, and `requirements.txt`.
+- `templates/typescript/sdk-generator.ts` -- Wraps `generate-sdk-typescript.js` (900+ lines). Produces a complete npm package: client class, resource classes, TypeScript interfaces, error classes, `package.json`, and `tsconfig.json`.
+
+## Capabilities
+
+| SDK | Provides | Requires |
+|---|---|---|
+| Python | `sdk.python`, `client.rest.async` | `api.rest`, `api.rest.crud` |
+| TypeScript | `sdk.typescript`, `client.rest` | `api.rest`, `api.rest.crud` |
+
+## Default Configuration
+
+Both SDKs include authentication support, automatic retries (3 attempts), and a 30s timeout. The Python SDK defaults to package name `specverse_client`; TypeScript defaults to `@specverse/sdk`.
+
+## Status
+
+Wrapper implementations. Both YAMLs note future TODOs to convert the monolithic JS generators into native TypeScript template generators.

package/libs/instance-factories/sdks/python-sdk.yaml

@@ -0,0 +1,66 @@
+name: PythonSDK
+version: "1.0.0"
+category: view
+description: "Python SDK generator for consuming REST APIs with async support and type hints"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [python, sdk, client, rest-api, async]
+
+compatibility:
+  specverse: ">=3.3.0"
+  python: ">=3.8"
+
+capabilities:
+  provides:
+    - "sdk.python"
+    - "client.rest.async"
+  requires:
+    - "api.rest"
+    - "api.rest.crud"
+
+technology:
+  runtime: "python"
+  language: "python"
+  framework: "native"
+  httpClient: "aiohttp"
+
+dependencies:
+  runtime:
+    - name: "aiohttp"
+      version: "^3.9.0"
+    - name: "pydantic"
+      version: "^2.0.0"
+  dev:
+    - name: "mypy"
+      version: "^1.7.0"
+    - name: "pytest"
+      version: "^7.4.0"
+    - name: "pytest-asyncio"
+      version: "^0.21.0"
+
+codeTemplates:
+  sdk:
+    engine: typescript
+    generator: "libs/instance-factories/sdks/templates/python/sdk-generator.ts"
+    outputPattern: "sdk-python/"
+
+configuration:
+  packageName: "specverse_client"
+  packageVersion: "1.0.0"
+  includeAuth: true
+  includeRetry: true
+  includeAsync: true
+  timeout: 30000
+  retries: 3
+
+# NOTE: This implementation type wraps the existing generate-sdk-python.js script
+# TODO: Future enhancement - Convert generate-sdk-python.js to native TypeScript template generator
+#       The current script is 1000+ lines and generates a complete Python package structure.
+#       Converting to native templates would require breaking it into multiple template files:
+#       - client-generator.ts (main async client class)
+#       - resource-generator.ts (per-controller resource classes)
+#       - types-generator.ts (Pydantic models)
+#       - errors-generator.ts (exception classes)
+#       - package-generator.ts (setup.py, requirements.txt)