@agentlang/agentmanager 0.0.3

package/libs/agentcraft/src/utils/text-utils.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a kebab-case string to PascalCase.
+ * E.g. "lead-intake" → "LeadIntake"
+ */
+export function kebabToPascalCase(name: string): string {
+  return name
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Converts a PascalCase string to kebab-case.
+ * E.g. "LeadIntake" → "lead-intake"
+ */
+export function pascalToKebabCase(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase();
+}
+
+/**
+ * Extracts the module name from agentlang code (e.g. "module Foo.core" → "Foo.core").
+ */
+export function extractModuleName(code: string): string | null {
+  const match = code.match(/^\s*module\s+([\w.\-]+)/m);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extracts entity names from agentlang code.
+ */
+export function extractEntityNames(code: string): string[] {
+  const names: string[] = [];
+  const regex = /^\s*(?:@public\s+)?entity\s+(\w+)/gm;
+  let match;
+  while ((match = regex.exec(code)) !== null) {
+    names.push(match[1]);
+  }
+  return names;
+}
+
+/**
+ * Strips the `module <name>` line from code.
+ */
+export function stripModuleLine(code: string): string {
+  return code.replace(/^\s*module\s+\S+\s*\n/, '');
+}

package/libs/agentcraft/src/utils/validator.ts

@@ -0,0 +1,231 @@
+export interface ValidationResult {
+  valid: boolean;
+  errors?: string;
+}
+
+/**
+ * Strips markdown code fences from LLM output.
+ */
+export function normalizeGeneratedCode(code: string): string {
+  const fenceRegex = /```(\w+)?\n([\s\S]*?)```/g;
+  const blocks: string[] = [];
+  let match;
+
+  while ((match = fenceRegex.exec(code)) !== null) {
+    blocks.push(match[2].trim());
+  }
+
+  if (blocks.length > 0) {
+    return blocks.join('\n\n');
+  }
+
+  return code;
+}
+
+function ensureModulePrefix(code: string): string {
+  const trimmed = code.trim();
+  if (!trimmed.startsWith('module')) {
+    return `module Temp\n${trimmed}`;
+  }
+  return trimmed;
+}
+
+const RESERVED_WORDS = new Set([
+  'module',
+  'import',
+  'entity',
+  'event',
+  'record',
+  'relationship',
+  'workflow',
+  'agent',
+  'resolver',
+  'flow',
+  'decision',
+  'scenario',
+  'directive',
+  'glossaryEntry',
+  'eval',
+  'if',
+  'else',
+  'for',
+  'in',
+  'return',
+  'throw',
+  'await',
+  'delete',
+  'purge',
+  'case',
+  'not',
+  'true',
+  'false',
+  'or',
+  'and',
+  'like',
+  'between',
+  'create',
+  'update',
+  'query',
+  'upsert',
+  'contains',
+  'extends',
+  'where',
+  'roles',
+  'allow',
+  'subscribe',
+  'backoff',
+  'attempts',
+]);
+
+/**
+ * Checks for common syntax errors:
+ * - Reserved words used as identifiers
+ * - `throw "msg"` without parentheses
+ */
+export function checkCommonErrors(code: string): string[] {
+  const violations: string[] = [];
+  const lines = code.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+
+    const defMatch = line.match(
+      /^\s*(?:@public\s+)?(?:entity|event|record|workflow|agent)\s+(\w+)/,
+    );
+    if (defMatch && RESERVED_WORDS.has(defMatch[1].toLowerCase())) {
+      violations.push(
+        `Line ${lineNum}: "${defMatch[1]}" is a reserved word and cannot be used as a name. Rename it (e.g. "${suggestRename(defMatch[1])}").`,
+      );
+    }
+
+    const attrMatch = line.match(
+      /^\s+(\w+)\s+(?:String|Int|Number|Decimal|Float|Email|Date|Time|DateTime|Boolean|UUID|URL|Password|Map|Any|@ref|@enum)/,
+    );
+    if (attrMatch && RESERVED_WORDS.has(attrMatch[1].toLowerCase())) {
+      violations.push(
+        `Line ${lineNum}: "${attrMatch[1]}" is a reserved word and cannot be used as an attribute name. Rename it (e.g. "${suggestRename(attrMatch[1])}").`,
+      );
+    }
+
+    const throwMatch = line.match(/\bthrow\s+"([^"]*)"/);
+    if (throwMatch && !line.match(/\bthrow\s*\(/)) {
+      violations.push(
+        `Line ${lineNum}: throw requires parentheses. Write throw("${throwMatch[1]}") instead of throw "${throwMatch[1]}".`,
+      );
+    }
+  }
+
+  return violations;
+}
+
+function suggestRename(word: string): string {
+  const suggestions: Record<string, string> = {
+    decision: 'reviewDecision',
+    event: 'calendarEvent',
+    flow: 'appFlow',
+    agent: 'aiAgent',
+    record: 'logEntry',
+    import: 'importData',
+    delete: 'isDeleted',
+    query: 'searchText',
+    case: 'caseItem',
+    scenario: 'testScenario',
+    create: 'createItem',
+    update: 'updateItem',
+    contains: 'includesItem',
+    extends: 'extendsFrom',
+    where: 'location',
+    between: 'betweenRange',
+    return: 'returnValue',
+    module: 'appModule',
+    entity: 'dataEntity',
+    workflow: 'workflowDef',
+    relationship: 'relation',
+    resolver: 'resolverDef',
+    for: 'forItem',
+    in: 'inValue',
+    not: 'isNot',
+    like: 'likePattern',
+    roles: 'userRoles',
+    allow: 'allowAccess',
+    purge: 'purgeItem',
+  };
+  return suggestions[word.toLowerCase()] ?? word + 'Value';
+}
+
+/**
+ * Validates agentlang code. Uses agentlang parser if available, falls back to basic validation.
+ */
+export async function validateCode(rawCode: string): Promise<ValidationResult> {
+  const normalized = normalizeGeneratedCode(rawCode);
+  const code = ensureModulePrefix(normalized);
+
+  const commonErrors = checkCommonErrors(code);
+  if (commonErrors.length > 0) {
+    return {
+      valid: false,
+      errors:
+        'SYNTAX ERRORS detected before parsing — fix these first:\n\n' +
+        commonErrors.join('\n'),
+    };
+  }
+
+  try {
+    const parserModule = 'agentlang/out/language/parser.js';
+    const { parseModule } = await (Function(
+      'm',
+      'return import(m)',
+    )(parserModule) as Promise<any>);
+    await parseModule(code);
+    return { valid: true };
+  } catch (err) {
+    if (err instanceof Error) {
+      const message = err.message;
+      if (
+        message.includes('Cannot find module') ||
+        message.includes('Cannot find package') ||
+        message.includes('ERR_MODULE_NOT_FOUND') ||
+        message.includes('MODULE_NOT_FOUND')
+      ) {
+        return basicValidation(code);
+      }
+      return { valid: false, errors: message };
+    }
+    return { valid: false, errors: String(err) };
+  }
+}
+
+/**
+ * Basic syntax validation when agentlang parser is not available.
+ */
+export function basicValidation(code: string): ValidationResult {
+  const trimmed = code.trim();
+
+  if (!trimmed.startsWith('module')) {
+    return {
+      valid: false,
+      errors: 'Code must start with a module declaration.',
+    };
+  }
+
+  let braceCount = 0;
+  for (const char of trimmed) {
+    if (char === '{') braceCount++;
+    if (char === '}') braceCount--;
+    if (braceCount < 0) {
+      return {
+        valid: false,
+        errors: 'Unbalanced braces: unexpected closing brace.',
+      };
+    }
+  }
+  if (braceCount !== 0) {
+    return {
+      valid: false,
+      errors: `Unbalanced braces: ${braceCount} unclosed opening brace(s).`,
+    };
+  }
+
+  return { valid: true };
+}

package/libs/agentcraft/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/libs/agentcraft",
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}

package/libs/auth/src/auth.guard.ts

@@ -0,0 +1,188 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  ServiceUnavailableException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Reflector } from '@nestjs/core';
+import { CognitoJwtVerifier } from 'aws-jwt-verify';
+import type { FastifyRequest } from 'fastify';
+import { IS_PUBLIC_KEY } from './public.decorator';
+
+type JwtClaims = Record<string, unknown> & {
+  sub?: string;
+  username?: string;
+  'cognito:username'?: string;
+  token_use?: string;
+};
+
+interface AuthenticatedUser {
+  sub: string;
+  username: string;
+  tokenUse: string;
+  claims: JwtClaims;
+}
+
+type AuthenticatedRequest = FastifyRequest & { user?: AuthenticatedUser };
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  private readonly authEnabled: boolean;
+  private readonly localUsername: string;
+  private readonly accessTokenVerifier?: ReturnType<
+    typeof CognitoJwtVerifier.create
+  >;
+  private readonly idTokenVerifier?: ReturnType<
+    typeof CognitoJwtVerifier.create
+  >;
+
+  public constructor(
+    private readonly reflector: Reflector,
+    private readonly configService: ConfigService,
+  ) {
+    this.authEnabled = this.readAuthEnabled();
+    this.localUsername =
+      this.configService.get<string>('AUTH_LOCAL_USER') ?? 'local-dev-user';
+
+    if (!this.authEnabled) {
+      return;
+    }
+
+    const region = this.configService.get<string>('COGNITO_REGION');
+    const userPoolId = this.configService.get<string>('COGNITO_USER_POOL_ID');
+    const clientId = this.configService.get<string>('COGNITO_CLIENT_ID');
+
+    if (!region || !userPoolId || !clientId) {
+      throw new ServiceUnavailableException(
+        'Missing Cognito config. Set COGNITO_REGION, COGNITO_USER_POOL_ID, and COGNITO_CLIENT_ID.',
+      );
+    }
+
+    const issuer = `https://cognito-idp.${region}.amazonaws.com/${userPoolId}`;
+
+    this.accessTokenVerifier = CognitoJwtVerifier.create({
+      userPoolId,
+      tokenUse: 'access',
+      clientId,
+      issuer,
+    });
+    this.idTokenVerifier = CognitoJwtVerifier.create({
+      userPoolId,
+      tokenUse: 'id',
+      clientId,
+      issuer,
+    });
+  }
+
+  public async canActivate(context: ExecutionContext): Promise<boolean> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<AuthenticatedRequest>();
+
+    if (!this.authEnabled) {
+      request.user = this.buildLocalUser();
+      return true;
+    }
+
+    const token = this.extractBearerToken(request);
+    if (!token) {
+      throw new UnauthorizedException('Missing bearer token');
+    }
+
+    const claims = await this.verifyWithCognito(token);
+    request.user = this.buildAuthenticatedUser(claims);
+    return true;
+  }
+
+  private readAuthEnabled() {
+    const authEnabledRaw = this.configService.get<string>('AUTH_ENABLED');
+    if (authEnabledRaw !== undefined) {
+      return authEnabledRaw === 'true';
+    }
+
+    return this.configService.get<boolean>('authEnabled', true);
+  }
+
+  private buildLocalUser(): AuthenticatedUser {
+    return {
+      sub: this.localUsername,
+      username: this.localUsername,
+      tokenUse: 'disabled',
+      claims: {
+        sub: this.localUsername,
+        username: this.localUsername,
+        token_use: 'disabled',
+      },
+    };
+  }
+
+  private buildAuthenticatedUser(claims: JwtClaims): AuthenticatedUser {
+    const username =
+      (typeof claims.username === 'string' && claims.username) ||
+      (typeof claims['cognito:username'] === 'string' &&
+        claims['cognito:username']) ||
+      (typeof claims.sub === 'string' && claims.sub) ||
+      'unknown';
+
+    return {
+      sub: (typeof claims.sub === 'string' && claims.sub) || username,
+      username,
+      tokenUse:
+        (typeof claims.token_use === 'string' && claims.token_use) || 'unknown',
+      claims,
+    };
+  }
+
+  private extractBearerToken(request: AuthenticatedRequest): string | null {
+    const authHeader = request.headers?.authorization;
+    if (!authHeader) {
+      return null;
+    }
+
+    let value: string | undefined;
+    if (typeof authHeader === 'string') {
+      value = authHeader;
+    } else if (Array.isArray(authHeader) && typeof authHeader[0] === 'string') {
+      value = authHeader[0];
+    }
+
+    if (!value) {
+      return null;
+    }
+
+    const matches = /^Bearer\s+(.+)$/i.exec(value);
+    if (!matches?.[1]) {
+      return null;
+    }
+
+    return matches[1];
+  }
+
+  private async verifyWithCognito(token: string): Promise<JwtClaims> {
+    if (!this.accessTokenVerifier || !this.idTokenVerifier) {
+      throw new ServiceUnavailableException(
+        'Cognito verifier is not initialized',
+      );
+    }
+
+    try {
+      const claims = await this.accessTokenVerifier.verify(token);
+      return claims as JwtClaims;
+    } catch {
+      try {
+        const claims = await this.idTokenVerifier.verify(token);
+        return claims as JwtClaims;
+      } catch {
+        throw new UnauthorizedException('Invalid or expired Cognito token');
+      }
+    }
+  }
+}

package/libs/auth/src/auth.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { APP_GUARD } from '@nestjs/core';
+import { AuthGuard } from './auth.guard';
+
+@Module({
+  imports: [ConfigModule],
+  providers: [AuthGuard, { provide: APP_GUARD, useExisting: AuthGuard }],
+  exports: [AuthGuard],
+})
+export class AuthModule {}

package/libs/auth/src/index.ts

@@ -0,0 +1,3 @@
+export { AuthModule } from './auth.module';
+export { AuthGuard } from './auth.guard';
+export { Public, IS_PUBLIC_KEY } from './public.decorator';

package/libs/auth/src/public.decorator.ts

@@ -0,0 +1,5 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

package/libs/auth/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/libs/auth",
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}

package/libs/common/src/database/data-source.service.ts

@@ -0,0 +1,75 @@
+import {
+  Injectable,
+  Logger,
+  OnModuleInit,
+  OnModuleDestroy,
+  Inject,
+} from '@nestjs/common';
+import { DataSource, type Repository, type ObjectLiteral } from 'typeorm';
+import { DATABASE_CONFIG, DatabaseModuleConfig } from './database.config';
+import { DatabaseConnectionHolder } from './database-connection.holder';
+
+@Injectable()
+export class DataSourceService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(DataSourceService.name);
+  private dataSource: DataSource | null = null;
+
+  constructor(
+    private readonly connectionHolder: DatabaseConnectionHolder,
+    @Inject(DATABASE_CONFIG)
+    private readonly config: DatabaseModuleConfig,
+  ) {}
+
+  async onModuleInit() {
+    if (!this.connectionHolder.isConfigured()) {
+      this.logger.log(
+        'No database configured — stores will use file-based persistence',
+      );
+      return;
+    }
+
+    const params = this.connectionHolder.get();
+
+    try {
+      this.dataSource = new DataSource({
+        type: 'postgres',
+        host: params.host,
+        port: params.port,
+        username: params.user,
+        password: params.password,
+        database: this.config.embeddedDbName,
+        entities: this.config.entities,
+        synchronize: process.env.NODE_ENV !== 'production',
+        logging: false,
+      });
+
+      await this.dataSource.initialize();
+      this.logger.log(
+        `TypeORM DataSource connected to ${params.host}:${params.port}/${this.config.embeddedDbName}`,
+      );
+    } catch (err) {
+      this.logger.warn(
+        `Failed to initialize TypeORM DataSource: ${err}. Falling back to file-based persistence.`,
+      );
+      this.dataSource = null;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.dataSource?.isInitialized === true;
+  }
+
+  getRepository<T extends ObjectLiteral>(
+    entity: new () => T,
+  ): Repository<T> | null {
+    if (!this.dataSource?.isInitialized) return null;
+    return this.dataSource.getRepository(entity);
+  }
+
+  async onModuleDestroy() {
+    if (this.dataSource?.isInitialized) {
+      await this.dataSource.destroy();
+      this.logger.log('TypeORM DataSource disconnected');
+    }
+  }
+}

package/libs/common/src/database/database-connection.holder.ts

@@ -0,0 +1,41 @@
+import { Injectable, Inject } from '@nestjs/common';
+import { DATABASE_CONFIG, DatabaseModuleConfig } from './database.config';
+
+export interface DatabaseConnectionParams {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+}
+
+@Injectable()
+export class DatabaseConnectionHolder {
+  private params: DatabaseConnectionParams;
+  private configured: boolean;
+
+  constructor(
+    @Inject(DATABASE_CONFIG)
+    config: DatabaseModuleConfig,
+  ) {
+    this.params = {
+      host: config.database.host ?? 'localhost',
+      port: config.database.port,
+      user: config.database.user,
+      password: config.database.password,
+    };
+    this.configured = config.database.host !== null;
+  }
+
+  set(params: DatabaseConnectionParams): void {
+    this.params = params;
+    this.configured = true;
+  }
+
+  get(): DatabaseConnectionParams {
+    return this.params;
+  }
+
+  isConfigured(): boolean {
+    return this.configured;
+  }
+}

package/libs/common/src/database/database.config.ts

@@ -0,0 +1,14 @@
+export interface DatabaseModuleConfig {
+  dataPath: string;
+  database: {
+    host: string | null;
+    port: number;
+    user: string;
+    password: string;
+  };
+  embeddedDbPort: number;
+  embeddedDbName: string;
+  entities: (new (...args: any[]) => any)[];
+}
+
+export const DATABASE_CONFIG = Symbol('DATABASE_CONFIG');

package/libs/common/src/database/database.module.ts

@@ -0,0 +1,42 @@
+import { DynamicModule, Global, Module } from '@nestjs/common';
+import { DATABASE_CONFIG, DatabaseModuleConfig } from './database.config';
+import { DatabaseConnectionHolder } from './database-connection.holder';
+import { DataSourceService } from './data-source.service';
+import { EmbeddedDatabaseService } from './embedded-database.service';
+import { FileStoreFactory } from './file-store.factory';
+
+export interface DatabaseModuleAsyncOptions {
+  inject?: any[];
+  useFactory: (
+    ...args: any[]
+  ) => DatabaseModuleConfig | Promise<DatabaseModuleConfig>;
+}
+
+@Global()
+@Module({})
+export class DatabaseModule {
+  static forRootAsync(options: DatabaseModuleAsyncOptions): DynamicModule {
+    return {
+      module: DatabaseModule,
+      global: true,
+      providers: [
+        {
+          provide: DATABASE_CONFIG,
+          inject: options.inject || [],
+          useFactory: options.useFactory,
+        },
+        DatabaseConnectionHolder,
+        EmbeddedDatabaseService,
+        DataSourceService,
+        FileStoreFactory,
+      ],
+      exports: [
+        DatabaseConnectionHolder,
+        DataSourceService,
+        EmbeddedDatabaseService,
+        FileStoreFactory,
+        DATABASE_CONFIG,
+      ],
+    };
+  }
+}