feat(snippets): add snippets entity, crud, and auto-browser-per-run

- add Snippet entity with name, description, code; full CRUD backend
- add snippets pages (list, create, edit, detail) and nav entry
- add runSnippet helper in code-executor using new Function with args array
- add result param to execute() so validateCode can access exec output
- remove sessionName from steps; each run now spawns its own fresh browser
- fix waitForURL race by polling localStorage for token instead

server/src/app.module.ts

@@ -19,6 +19,8 @@ import { ScenarioRunStepEntity } from "./scenario/scenario-run-step.entity";
 import { ScenarioRunLogEntity } from "./scenario/scenario-run-log.entity";
 import { ScenarioCredentialEntity } from "./scenario/scenario-credential.entity";
 import { ScenarioModule } from "./scenario/scenario.module";
+import { SnippetEntity } from "./snippet/snippet.entity";
+import { SnippetModule } from "./snippet/snippet.module";
 
 @Module({
   imports: [
@@ -43,6 +45,7 @@ import { ScenarioModule } from "./scenario/scenario.module";
           ScenarioRunStepEntity,
           ScenarioRunLogEntity,
           ScenarioCredentialEntity,
+          SnippetEntity,
         ],
         synchronize: true,
       }),
@@ -52,6 +55,7 @@ import { ScenarioModule } from "./scenario/scenario.module";
     EnvironmentModule,
     CredentialModule,
     ScenarioModule,
+    SnippetModule,
     McpModule,
     HealthModule,
   ],

server/src/code-executor/code-executor.service.ts

@@ -50,6 +50,8 @@ export class CodeExecutorService {
     getStepOutput?: (order: number) => Promise<unknown>,
     credentials?: Record<string, unknown>,
     environment?: EnvironmentUrls | null,
+    snippets?: Record<string, string> | null,
+    result?: unknown,
   ): Promise<ExecResult> {
     const scriptLog: ScriptLogger =
       log ?? ((level, msg) => this.logger[level](msg));
@@ -60,9 +62,22 @@ export class CodeExecutorService {
 
     const credMap: Record<string, unknown> = credentials ?? {};
     const envUrls: EnvironmentUrls = environment ?? {};
+    const snippetMap: Record<string, string> = snippets ?? {};
+
+    // pageHelpers is referenced by runSnippet, so we declare it as a var first.
+    // eslint-disable-next-line prefer-const
+    let pageHelpers: Record<string, unknown>;
+
+    const fakeConsole = {
+      log: (...args: unknown[]) => scriptLog("log", toStr(args)),
+      warn: (...args: unknown[]) => scriptLog("warn", toStr(args)),
+      error: (...args: unknown[]) => scriptLog("error", toStr(args)),
+      info: (...args: unknown[]) => scriptLog("log", toStr(args)),
+      debug: (...args: unknown[]) => scriptLog("log", toStr(args)),
+    };
 
     try {
-      const pageHelpers = {
+      pageHelpers = {
         dumpDom: (selector?: string) => dumpDom(page, selector),
         log: (...args: unknown[]) => scriptLog("log", toStr(args)),
         warn: (...args: unknown[]) => scriptLog("warn", toStr(args)),
@@ -88,14 +103,27 @@ export class CodeExecutorService {
           }
           return value;
         },
-      };
-
-      const fakeConsole = {
-        log: (...args: unknown[]) => scriptLog("log", toStr(args)),
-        warn: (...args: unknown[]) => scriptLog("warn", toStr(args)),
-        error: (...args: unknown[]) => scriptLog("error", toStr(args)),
-        info: (...args: unknown[]) => scriptLog("log", toStr(args)),
-        debug: (...args: unknown[]) => scriptLog("log", toStr(args)),
+        /**
+         * Runs a named snippet by name. Snippets receive the same page/context/helpers
+         * as regular exec code, plus any positional args you pass.
+         *
+         * Example: await helpers.runSnippet('clickLoginButton', '#submit')
+         */
+        runSnippet: async (name: string, ...args: unknown[]): Promise<unknown> => {
+          const snippetCode = snippetMap[name];
+          if (snippetCode == null) {
+            throw new Error(`Snippet "${name}" not found`);
+          }
+          const snippetFn = new Function(
+            "page",
+            "context",
+            "helpers",
+            "console",
+            "snippetArgs",
+            `return (async (page, context, helpers, ...args) => { ${snippetCode} })(page, context, helpers, ...snippetArgs)`,
+          );
+          return snippetFn(page, context, pageHelpers, fakeConsole, args);
+        },
       };
 
       // Passing `console` as a named parameter shadows the global in the script scope.
@@ -104,11 +132,12 @@ export class CodeExecutorService {
         "context",
         "helpers",
         "console",
+        "result",
         `return (async (page, context, helpers) => { ${code} })(page, context, helpers)`,
       );
       this.logger.debug("Executing user code");
-      const result = await fn(page, context, pageHelpers, fakeConsole);
-      return { result };
+      const execResult = await fn(page, context, pageHelpers, fakeConsole, result);
+      return { result: execResult };
     } catch (err) {
       throw new InternalServerErrorException(
         `Code execution failed: ${(err as Error).message}`,

server/src/scenario/dto/create-scenario-step.dto.ts

@@ -24,14 +24,14 @@ export class CreateScenarioStepDto {
   @IsIn(["login", "exec", "sign"])
   type: StepType;
 
-  @ApiProperty({
-    description:
-      "Session name used by this step. login steps create it; exec steps consume it.",
+  @ApiPropertyOptional({
+    description: "Session name (deprecated — browser is created automatically per run).",
     example: "my-session",
   })
+  @IsOptional()
   @IsString()
   @IsNotEmpty()
-  sessionName: string;
+  sessionName?: string;
 
   @ApiPropertyOptional({ example: "return await page.title();" })
   @IsOptional()

server/src/scenario/dto/scenario-export.dto.ts

@@ -25,7 +25,7 @@ export class ScenarioStepExportDto {
   @ApiProperty()
   @IsString()
   @IsNotEmpty()
-  sessionName: string;
+  sessionName: string | null;
 
   @ApiPropertyOptional()
   @IsOptional()

server/src/scenario/scenario-scheduler.service.ts

@@ -14,10 +14,10 @@ import { ScenarioStepEntity } from "./scenario-step.entity";
 import type { ScriptLogger } from "../code-executor/code-executor.service";
 import { AuthService } from "../auth/auth.service";
 import { CodeExecutorService } from "../code-executor/code-executor.service";
-import { SessionService } from "../session/session.service";
 import { ScenarioService } from "./scenario.service";
 import { EnvironmentService } from "../environment/environment.service";
 import type { EnvironmentUrls } from "../environment/environment.entity";
+import { SnippetService } from "../snippet/snippet.service";
 
 interface ValidateResult {
   success: boolean;
@@ -39,6 +39,8 @@ export class ScenarioSchedulerService {
   private readonly runCredentials = new Map<number, Record<string, unknown>>();
   // Cache environment URLs per run (resolved from the first login step)
   private readonly runEnvironments = new Map<number, EnvironmentUrls>();
+  // Cache snippet code map per run (built once when a run starts)
+  private readonly runSnippets = new Map<number, Record<string, string>>();
 
   constructor(
     @InjectRepository(ScenarioRunEntity)
@@ -49,9 +51,9 @@ export class ScenarioSchedulerService {
     private readonly runLogRepo: Repository<ScenarioRunLogEntity>,
     private readonly authService: AuthService,
     private readonly codeExecutor: CodeExecutorService,
-    private readonly sessionService: SessionService,
     private readonly scenarioService: ScenarioService,
     private readonly environmentService: EnvironmentService,
+    private readonly snippetService: SnippetService,
   ) {}
 
   private persistLog(
@@ -133,6 +135,11 @@ export class ScenarioSchedulerService {
       // Resolve environment from the first login step (best-effort)
       const envUrls = await this.resolveRunEnvironment(run.scenarioId);
       if (envUrls) this.runEnvironments.set(run.id, envUrls);
+      // Pre-load snippet map
+      const snippetMap = await this.snippetService
+        .buildSnippetMap()
+        .catch(() => ({} as Record<string, string>));
+      this.runSnippets.set(run.id, snippetMap);
       const traceId = crypto.randomUUID();
       void traceStorage.run({ traceId }, () =>
         this.processRunToCompletion(run.id),
@@ -170,6 +177,7 @@ export class ScenarioSchedulerService {
       this.activeRuns.delete(runId);
       this.runCredentials.delete(runId);
       this.runEnvironments.delete(runId);
+      this.runSnippets.delete(runId);
     }
   }
 
@@ -199,39 +207,20 @@ export class ScenarioSchedulerService {
 
   // ── Shared browser per run ─────────────────────────────────────────────────
 
-  private async getOrCreateBrowserHandle(
-    runId: number,
-    sessionName: string,
-  ): Promise<BrowserHandle> {
+  private async getOrCreateBrowserHandle(runId: number): Promise<BrowserHandle> {
     const existing = this.runBrowsers.get(runId);
     if (existing) return existing;
 
-    const session = await this.sessionService.findBySessionName(sessionName);
-    if (!session) throw new Error(`Session not found: ${sessionName}`);
-
-    const cookies = JSON.parse(session.cookies) as Parameters<
-      BrowserContext["addCookies"]
-    >[0];
-    const localStorageData: Record<string, string> = JSON.parse(
-      session.localStorage,
-    );
-
     const browser = await chromium.launch({
       headless: true,
-      // TODO: env var move to config
       executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
     });
     const context = await browser.newContext();
-    await context.addCookies(cookies);
-    await context.addInitScript((entries: Record<string, string>) => {
-      for (const [k, v] of Object.entries(entries))
-        window.localStorage.setItem(k, v);
-    }, localStorageData);
     const page = await context.newPage();
 
     const handle: BrowserHandle = { browser, context, page };
     this.runBrowsers.set(runId, handle);
-    this.logger.log(`Run #${runId}: browser created (session: ${sessionName})`);
+    this.logger.log(`Run #${runId}: browser created`);
     return handle;
   }
 
@@ -273,7 +262,7 @@ export class ScenarioSchedulerService {
     const loginResult = await this.authService.login(
       params.keyId,
       params.environmentName,
-      step.sessionName,
+      step.sessionName ?? undefined,
     );
     this.logger.log(
       `StepRun #${stepRun.id}: login OK, session=${loginResult.sessionName}`,
@@ -282,7 +271,6 @@ export class ScenarioSchedulerService {
     if (step.validateCode) {
       const { page, context } = await this.getOrCreateBrowserHandle(
         stepRun.runId,
-        step.sessionName,
       );
       this.codeExecutor.validate(step.validateCode);
       const { result } = await this.codeExecutor.execute(
@@ -293,6 +281,8 @@ export class ScenarioSchedulerService {
         this.makeGetStepOutput(stepRun),
         this.runCredentials.get(stepRun.runId),
         this.runEnvironments.get(stepRun.runId),
+        this.runSnippets.get(stepRun.runId),
+        null,
       );
       const vr = this.parseValidateResult(result);
       if (!vr.success) throw new Error(vr.description ?? "Validation failed");
@@ -312,11 +302,11 @@ export class ScenarioSchedulerService {
     this.codeExecutor.validate(step.execCode);
     const { page, context } = await this.getOrCreateBrowserHandle(
       stepRun.runId,
-      step.sessionName,
     );
     const getStepOutput = this.makeGetStepOutput(stepRun);
     const creds = this.runCredentials.get(stepRun.runId);
     const env = this.runEnvironments.get(stepRun.runId);
+    const snips = this.runSnippets.get(stepRun.runId);
     const { result: execOutput } = await this.codeExecutor.execute(
       page,
       context,
@@ -325,6 +315,7 @@ export class ScenarioSchedulerService {
       getStepOutput,
       creds,
       env,
+      snips,
     );
     this.logger.log(`StepRun #${stepRun.id}: exec OK`);
 
@@ -338,6 +329,8 @@ export class ScenarioSchedulerService {
         getStepOutput,
         creds,
         env,
+        snips,
+        execOutput,
       );
       const vr = this.parseValidateResult(result);
       if (!vr.success) throw new Error(vr.description ?? "Validation failed");
@@ -363,7 +356,6 @@ export class ScenarioSchedulerService {
 
     const { page, context } = await this.getOrCreateBrowserHandle(
       stepRun.runId,
-      step.sessionName,
     );
     await this.authService.signWithKey(params.keyId, page);
     this.logger.log(`StepRun #${stepRun.id}: sign OK`);
@@ -378,6 +370,8 @@ export class ScenarioSchedulerService {
         this.makeGetStepOutput(stepRun),
         this.runCredentials.get(stepRun.runId),
         this.runEnvironments.get(stepRun.runId),
+        this.runSnippets.get(stepRun.runId),
+        null,
       );
       const vr = this.parseValidateResult(result);
       if (!vr.success) throw new Error(vr.description ?? "Validation failed");

server/src/scenario/scenario-step.entity.ts

@@ -34,8 +34,8 @@ export class ScenarioStepEntity {
   @Column({ type: "text", nullable: true })
   title: string | null;
 
-  @Column({ type: "text" })
-  sessionName: string;
+  @Column({ type: "text", nullable: true })
+  sessionName: string | null;
 
   @Column({ type: "text", nullable: true })
   execCode: string | null;

server/src/scenario/scenario.module.ts

@@ -14,6 +14,7 @@ import { AuthModule } from "../auth/auth.module";
 import { CodeExecutorModule } from "../code-executor/code-executor.module";
 import { SessionModule } from "../session/session.module";
 import { EnvironmentModule } from "../environment/environment.module";
+import { SnippetModule } from "../snippet/snippet.module";
 
 @Module({
   imports: [
@@ -30,6 +31,7 @@ import { EnvironmentModule } from "../environment/environment.module";
     CodeExecutorModule,
     SessionModule,
     EnvironmentModule,
+    SnippetModule,
   ],
   controllers: [ScenarioController],
   providers: [ScenarioService, ScenarioSchedulerService],

server/src/snippet/dto/create-snippet.dto.ts

@@ -0,0 +1,19 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { IsNotEmpty, IsOptional, IsString } from "class-validator";
+
+export class CreateSnippetDto {
+  @ApiProperty({ example: "clickLoginButton" })
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @ApiPropertyOptional({ example: "Clicks the login button and waits for navigation" })
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiProperty({ example: "await page.click('#login-btn');\nawait page.waitForNavigation();" })
+  @IsString()
+  @IsNotEmpty()
+  code: string;
+}

server/src/snippet/dto/update-snippet.dto.ts

@@ -0,0 +1,21 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsNotEmpty, IsOptional, IsString } from "class-validator";
+
+export class UpdateSnippetDto {
+  @ApiPropertyOptional({ example: "clickLoginButton" })
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  name?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  code?: string;
+}

server/src/snippet/snippet.controller.ts

@@ -0,0 +1,67 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  Param,
+  ParseIntPipe,
+  Patch,
+  Post,
+  Query,
+} from "@nestjs/common";
+import { ApiOperation, ApiResponse, ApiTags } from "@nestjs/swagger";
+import { SnippetService, SnippetOrderBy } from "./snippet.service";
+import { CreateSnippetDto } from "./dto/create-snippet.dto";
+import { UpdateSnippetDto } from "./dto/update-snippet.dto";
+import { PaginationQueryDto } from "../common/dto/pagination.dto";
+
+@ApiTags("snippets")
+@Controller("snippets")
+export class SnippetController {
+  constructor(private readonly snippetService: SnippetService) {}
+
+  @Post()
+  @ApiOperation({ summary: "Create a new snippet" })
+  @ApiResponse({ status: 201, description: "Snippet created" })
+  @ApiResponse({ status: 409, description: "Name already taken" })
+  create(@Body() dto: CreateSnippetDto) {
+    return this.snippetService.create(dto);
+  }
+
+  @Get()
+  @ApiOperation({ summary: "List all snippets (paginated)" })
+  @ApiResponse({ status: 200, description: "Paginated snippets" })
+  findAll(@Query() query: PaginationQueryDto<SnippetOrderBy>) {
+    return this.snippetService.findAll(query);
+  }
+
+  @Get(":id")
+  @ApiOperation({ summary: "Get snippet by ID" })
+  @ApiResponse({ status: 200, description: "Snippet record" })
+  @ApiResponse({ status: 404, description: "Snippet not found" })
+  findOne(@Param("id", ParseIntPipe) id: number) {
+    return this.snippetService.findOne(id);
+  }
+
+  @Patch(":id")
+  @ApiOperation({ summary: "Update a snippet" })
+  @ApiResponse({ status: 200, description: "Snippet updated" })
+  @ApiResponse({ status: 404, description: "Snippet not found" })
+  @ApiResponse({ status: 409, description: "Name already taken" })
+  update(
+    @Param("id", ParseIntPipe) id: number,
+    @Body() dto: UpdateSnippetDto,
+  ) {
+    return this.snippetService.update(id, dto);
+  }
+
+  @Delete(":id")
+  @HttpCode(204)
+  @ApiOperation({ summary: "Delete a snippet" })
+  @ApiResponse({ status: 204, description: "Snippet deleted" })
+  @ApiResponse({ status: 404, description: "Snippet not found" })
+  remove(@Param("id", ParseIntPipe) id: number) {
+    return this.snippetService.remove(id);
+  }
+}

server/src/snippet/snippet.entity.ts

@@ -0,0 +1,34 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+} from "typeorm";
+
+@Entity("snippets")
+export class SnippetEntity {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  /** Unique identifier used to call the snippet: helpers.runSnippet('mySnippet', ...) */
+  @Column({ unique: true })
+  name: string;
+
+  @Column("text", { nullable: true })
+  description: string | null;
+
+  /**
+   * The snippet body — written as a regular async function body.
+   * It receives the same `page`, `context`, and `helpers` as exec code, plus
+   * any positional `...args` passed by the caller.
+   */
+  @Column("text")
+  code: string;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}

server/src/snippet/snippet.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { SnippetEntity } from "./snippet.entity";
+import { SnippetService } from "./snippet.service";
+import { SnippetController } from "./snippet.controller";
+
+@Module({
+  imports: [TypeOrmModule.forFeature([SnippetEntity])],
+  controllers: [SnippetController],
+  providers: [SnippetService],
+  exports: [SnippetService],
+})
+export class SnippetModule {}

server/src/snippet/snippet.service.ts

@@ -0,0 +1,76 @@
+import {
+  ConflictException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { SnippetEntity } from "./snippet.entity";
+import { CreateSnippetDto } from "./dto/create-snippet.dto";
+import { UpdateSnippetDto } from "./dto/update-snippet.dto";
+import {
+  PaginationQueryDto,
+  PaginatedResult,
+} from "../common/dto/pagination.dto";
+
+export type SnippetOrderBy = "id" | "name" | "createdAt" | "updatedAt";
+
+@Injectable()
+export class SnippetService {
+  constructor(
+    @InjectRepository(SnippetEntity)
+    private readonly repo: Repository<SnippetEntity>,
+  ) {}
+
+  async create(dto: CreateSnippetDto): Promise<SnippetEntity> {
+    const existing = await this.repo.findOneBy({ name: dto.name });
+    if (existing) {
+      throw new ConflictException(`Snippet "${dto.name}" already exists`);
+    }
+    return this.repo.save(
+      this.repo.create({ ...dto, description: dto.description ?? null }),
+    );
+  }
+
+  async findAll(
+    query: PaginationQueryDto<SnippetOrderBy> = {},
+  ): Promise<PaginatedResult<SnippetEntity>> {
+    const page = query.page ?? 1;
+    const limit = query.limit ?? 50;
+    const orderBy = query.orderBy ?? "id";
+    const orderDir = query.orderDir ?? "ASC";
+    const [data, total] = await this.repo.findAndCount({
+      order: { [orderBy]: orderDir },
+      skip: (page - 1) * limit,
+      take: limit,
+    });
+    return { data, total, page, limit };
+  }
+
+  async findOne(id: number): Promise<SnippetEntity> {
+    const snippet = await this.repo.findOneBy({ id });
+    if (!snippet) throw new NotFoundException(`Snippet ${id} not found`);
+    return snippet;
+  }
+
+  async update(id: number, dto: UpdateSnippetDto): Promise<SnippetEntity> {
+    const snippet = await this.findOne(id);
+    if (dto.name && dto.name !== snippet.name) {
+      const conflict = await this.repo.findOneBy({ name: dto.name });
+      if (conflict) throw new ConflictException(`Snippet "${dto.name}" already exists`);
+    }
+    Object.assign(snippet, dto);
+    return this.repo.save(snippet);
+  }
+
+  async remove(id: number): Promise<void> {
+    await this.findOne(id);
+    await this.repo.delete(id);
+  }
+
+  /** Returns a name→code map for all snippets (used by the executor). */
+  async buildSnippetMap(): Promise<Record<string, string>> {
+    const { data } = await this.findAll({ limit: 1000 });
+    return Object.fromEntries(data.map((s) => [s.name, s.code]));
+  }
+}