feat(versioning): version scenarios and snippets, bump to 1.16.0

- snapshot scenario and snippet content into version tables on every
  content change; live tables keep holding the latest version
- record the scenario version on each run and copy its steps into the
  run steps, so runs execute and show the version they were created with
- keep run step history when a step is deleted (FK set null)
- pin a snippet version with runSnippet('alias@N')
- add version picker to the run modal and version info across the UI
- add version list/get endpoints and MCP tools
- include version in exports and require it on import, restoring the
  exact version by id + version
This commit is contained in:
ars9 committed 2026-09-30 15:24:44 +03:00
1 parent a328ef5ea7
commit ff83b6c7da
40 files changed
+1457 -137

No files matched your search

+4
View File
@@ -19,6 +19,8 @@ import { ScenarioRunLogEntity } from "./scenario/scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario/scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario/scenario-run.entity";
import { ScenarioStepEntity } from "./scenario/scenario-step.entity";
import { ScenarioVersionEntity } from "./scenario/scenario-version.entity";
import { SnippetVersionEntity } from "./snippet/snippet-version.entity";
import { ScenarioEntity } from "./scenario/scenario.entity";
import { ScenarioModule } from "./scenario/scenario.module";
import { SessionEntity } from "./session/session.entity";
@@ -44,11 +46,13 @@ import { SnippetModule } from "./snippet/snippet.module";
CredentialEntity,
ScenarioEntity,
ScenarioStepEntity,
ScenarioVersionEntity,
ScenarioRunEntity,
ScenarioRunStepEntity,
ScenarioRunLogEntity,
ScenarioCredentialEntity,
SnippetEntity,
SnippetVersionEntity,
FileEntity,
ScenarioFileEntity,
ScenarioRunFileEntity,
+14
View File
@@ -32,3 +32,17 @@ export function resolveUsedSnippetAliases(
}
return used;
}
/**
* Splits a `runSnippet` reference into its alias and pinned version:
* `"login@3"` → `{ alias: "login", version: 3 }`, `"login"` → `{ alias: "login", version: null }`.
*/
export function parseSnippetRef(ref: string): {
alias: string;
version: number | null;
} {
const match = /^(.+)@(\d+)$/.exec(ref);
return match
? { alias: match[1], version: Number(match[2]) }
: { alias: ref, version: null };
}
+130 -7
View File
@@ -946,15 +946,24 @@ export class McpService {
.describe(
"Playwright trace recording: on (keep every trace), retain-on-failure, or off. Defaults to the server's PLAYWRIGHT_TRACE_MODE",
),
version: z
.number()
.int()
.min(1)
.optional()
.describe(
"Scenario version to run (see list_scenario_versions). Defaults to the latest",
),
},
},
async ({ id, environmentId, saveSession, traceMode }) => {
async ({ id, environmentId, saveSession, traceMode, version }) => {
try {
const run = await this.scenarioService.createRun(
id,
environmentId,
saveSession,
traceMode,
version,
);
return {
content: [{ type: "text" as const, text: JSON.stringify(run) }],
@@ -1155,19 +1164,74 @@ export class McpService {
);
server.registerTool(
"export_scenario",
"list_scenario_versions",
{
description:
"Export a scenario as a portable JSON payload (name + steps)",
"List a scenario's versions, newest first. Each version holds the scenario content and steps as of that version",
inputSchema: {
id: z.uuid().describe("Scenario ID to export"),
id: z.uuid().describe("Scenario ID"),
},
},
async ({ id }) => {
try {
const versions = await this.scenarioService.listVersions(id);
return {
content: [{ type: "text" as const, text: JSON.stringify(versions) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"get_scenario_version",
{
description: "Get one version of a scenario, with its steps",
inputSchema: {
id: z.uuid().describe("Scenario ID"),
version: z.number().int().min(1).describe("Scenario version"),
},
},
async ({ id, version }) => {
try {
const row = await this.scenarioService.findVersion(id, version);
return {
content: [{ type: "text" as const, text: JSON.stringify(row) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"export_scenario",
{
description:
"Export one version of a scenario as a portable JSON payload (version, name + steps)",
inputSchema: {
id: z.uuid().describe("Scenario ID to export"),
version: z
.number()
.int()
.min(1)
.optional()
.describe("Scenario version to export. Defaults to the latest"),
},
},
async ({ id, version }) => {
try {
const exported = await this.scenarioService.exportScenario(id, {
includeEnvironment: false,
credentialIds: [],
version,
});
return {
content: [
@@ -1187,8 +1251,17 @@ export class McpService {
"import_scenario",
{
description:
"Import a scenario from an export payload, creating a new scenario with all its steps",
"Import one scenario version from an export payload. Upserts by id + version: an existing version is left untouched; a new one is stored under its number and becomes the latest when higher than the current latest. Without an id a new scenario is created",
inputSchema: {
id: z
.uuid()
.optional()
.describe("Scenario ID to import into (from the export)"),
version: z
.number()
.int()
.min(1)
.describe("Scenario version the payload holds (from the export)"),
name: z.string().describe("Scenario name"),
description: z
.string()
@@ -1210,10 +1283,12 @@ export class McpService {
.describe("Ordered list of steps"),
},
},
async ({ name, description, steps }) => {
async ({ id, version, name, description, steps }) => {
try {
const scenario = await this.scenarioService.importScenario({
kind: "scenario",
id,
version,
name,
description,
steps: steps as { title: string | null; execCode: string | null }[],
@@ -1595,7 +1670,7 @@ export class McpService {
alias: z
.string()
.describe(
"Unique identifier used to invoke the snippet via context.runSnippet(alias, ...args)",
"Unique identifier used to invoke the snippet via context.runSnippet(alias, ...args). Use 'alias@<version>' to pin a specific version instead of the latest",
),
title: z.string().describe("Human-readable title"),
description: z
@@ -1664,6 +1739,54 @@ export class McpService {
},
);
server.registerTool(
"list_snippet_versions",
{
description:
"List a snippet's versions, newest first. Step code pins a version with context.runSnippet('alias@<version>')",
inputSchema: {
id: z.uuid().describe("Snippet ID"),
},
},
async ({ id }) => {
try {
const versions = await this.snippetService.listVersions(id);
return {
content: [{ type: "text" as const, text: JSON.stringify(versions) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"get_snippet_version",
{
description: "Get one version of a snippet",
inputSchema: {
id: z.uuid().describe("Snippet ID"),
version: z.number().int().min(1).describe("Snippet version"),
},
},
async ({ id, version }) => {
try {
const row = await this.snippetService.findVersion(id, version);
return {
content: [{ type: "text" as const, text: JSON.stringify(row) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"delete_snippet",
{
@@ -1,9 +1,11 @@
import {
IsBoolean,
IsEnum,
IsInt,
IsNotEmpty,
IsOptional,
IsUUID,
Min,
} from "class-validator";
import { TraceMode } from "../../config/app.config";
@@ -19,4 +21,10 @@ export class CreateScenarioRunDto {
@IsEnum(TraceMode)
@IsOptional()
traceMode?: TraceMode;
/** Scenario version to run; defaults to the latest. */
@IsInt()
@Min(1)
@IsOptional()
version?: number;
}
@@ -3,11 +3,13 @@ import { Type } from "class-transformer";
import {
IsArray,
IsIn,
IsInt,
IsNotEmpty,
IsObject,
IsOptional,
IsString,
IsUUID,
Min,
ValidateNested,
} from "class-validator";
import { EnvironmentData } from "../../environment/environment.entity";
@@ -24,6 +26,12 @@ export class ScenarioStepExportDto {
@IsString()
@IsNotEmpty()
execCode: string | null;
@ApiPropertyOptional()
@IsOptional()
@IsInt()
@Min(1)
timeoutSeconds?: number | null;
}
export class CredentialExportDto {
@@ -117,6 +125,17 @@ export class ScenarioExportDto {
@IsUUID()
environmentId?: string;
@ApiProperty({ description: "Scenario version this export holds" })
@IsInt()
@Min(1)
version: number;
@ApiPropertyOptional()
@IsOptional()
@IsInt()
@Min(1)
timeoutSeconds?: number;
@ApiPropertyOptional({ type: [ScenarioCredentialMappingDto] })
@IsOptional()
@IsArray()
@@ -32,12 +32,24 @@ export class ScenarioRunStepEntity {
@JoinColumn({ name: "runId" })
run: ScenarioRunEntity;
@Column("text")
scenarioStepId: string;
/** Live step this run step was created from; null once that step is deleted. */
@Column("text", { nullable: true })
scenarioStepId: string | null;
@ManyToOne(() => ScenarioStepEntity, { onDelete: "CASCADE" })
@ManyToOne(() => ScenarioStepEntity, { onDelete: "SET NULL", nullable: true })
@JoinColumn({ name: "scenarioStepId" })
scenarioStep: ScenarioStepEntity;
scenarioStep: ScenarioStepEntity | null;
// Step content copied from the run's scenario version, so the run executes
// (and keeps showing) exactly what it was created with.
@Column({ type: "text", nullable: true })
title: string | null;
@Column({ type: "text", nullable: true })
execCode: string | null;
@Column({ type: "int", nullable: true })
timeoutSeconds: number | null;
@Column({ type: "text", default: "waiting" })
status: RunStepStatus;
@@ -42,6 +42,10 @@ export class ScenarioRunEntity {
@JoinColumn({ name: "sessionId" })
session: SessionEntity | null;
/** Scenario version this run executes; null for runs created before versioning. */
@Column({ type: "int", nullable: true, default: null })
scenarioVersion: number | null;
@Column({ type: "text", default: "pending" })
status: RunStatus;
@@ -27,7 +27,6 @@ import { SnippetService } from "../snippet/snippet.service";
import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario-run.entity";
import { ScenarioStepEntity } from "./scenario-step.entity";
import { ScenarioService } from "./scenario.service";
interface BrowserHandle {
@@ -215,10 +214,19 @@ export class ScenarioSchedulerService implements OnModuleInit {
.then((env) => env?.data ?? {})
.catch(() => ({}) as EnvironmentData);
this.runEnvironments.set(run.id, environmentData);
const scenario = await this.scenarioService
.findOne(run.scenarioId)
.catch(() => null);
this.runScenarioTimeouts.set(run.id, scenario?.timeoutSeconds ?? null);
// Legacy runs (no scenarioVersion) fall back to the live scenario
const versioned =
run.scenarioVersion != null
? await this.scenarioService
.findVersion(run.scenarioId, run.scenarioVersion)
.catch(() => null)
: await this.scenarioService
.findOne(run.scenarioId)
.catch(() => null);
this.runScenarioTimeouts.set(
run.id,
versioned?.timeoutSeconds ?? null,
);
this.runScenarioIds.set(run.id, run.scenarioId);
this.runTraceModes.set(
run.id,
@@ -263,7 +271,6 @@ export class ScenarioSchedulerService implements OnModuleInit {
try {
let stepRun = await this.runStepRepo.findOne({
where: { runId, status: "pending" },
relations: ["scenarioStep"],
order: { order: "ASC" },
});
while (stepRun) {
@@ -280,7 +287,6 @@ export class ScenarioSchedulerService implements OnModuleInit {
await this.executeStepRun(stepRun);
stepRun = await this.runStepRepo.findOne({
where: { runId, status: "pending" },
relations: ["scenarioStep"],
order: { order: "ASC" },
});
}
@@ -365,12 +371,13 @@ export class ScenarioSchedulerService implements OnModuleInit {
}
private async executeStepRun(stepRun: ScenarioRunStepEntity): Promise<void> {
const step = stepRun.scenarioStep as ScenarioStepEntity;
// Run steps carry a copy of the step from the run's scenario version
const step = stepRun;
stepRun.status = "in_progress";
await this.runStepRepo.save(stepRun);
this.logger.log(
`StepRun #${stepRun.id} (run #${stepRun.runId}, step #${step.id} order=${step.order}) → in_progress`,
`StepRun #${stepRun.id} (run #${stepRun.runId}, step #${step.scenarioStepId ?? "deleted"} order=${step.order}) → in_progress`,
);
this.persistLog(
stepRun.runId,
@@ -549,7 +556,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
stepRun.runId,
stepRun.id,
"log",
`Step ${(stepRun.scenarioStep as ScenarioStepEntity | undefined)?.order ?? "?"} passed`,
`Step ${stepRun.order} passed`,
);
// Find the next waiting step in this run (next by order)
@@ -591,7 +598,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
stepRun.runId,
stepRun.id,
"error",
`Step ${(stepRun.scenarioStep as ScenarioStepEntity | undefined)?.order ?? "?"} failed: ${description}`,
`Step ${stepRun.order} failed: ${description}`,
);
await this.dumpPageOnFailure(stepRun);
@@ -624,8 +631,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
const handle = this.runBrowsers.get(stepRun.runId);
if (!handle) return; // no browser was ever opened for this run (e.g. setup error)
const step = stepRun.scenarioStep as ScenarioStepEntity | undefined;
const namePrefix = `step-${step?.order ?? stepRun.id}-failure`;
const namePrefix = `step-${stepRun.order}-failure`;
try {
const screenshot = await handle.page.screenshot({ fullPage: true });
@@ -659,7 +665,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
stepRun.runId,
stepRun.id,
"log",
`Step ${step?.order ?? "?"} failed: page dump uploaded to run files`,
`Step ${stepRun.order} failed: page dump uploaded to run files`,
);
}
}
@@ -0,0 +1,59 @@
import {
Column,
CreateDateColumn,
Entity,
JoinColumn,
ManyToOne,
PrimaryGeneratedColumn,
Unique,
} from "typeorm";
import { ScenarioEntity } from "./scenario.entity";
/** A step as it was at a given scenario version. */
export interface ScenarioStepSnapshot {
/** Id of the live step this snapshot was taken from (may no longer exist). */
id: string | null;
order: number;
title: string | null;
execCode: string | null;
timeoutSeconds: number | null;
}
/**
* Immutable snapshot of a scenario's content at one version. The `scenarios`
* and `scenario_steps` tables always hold the latest version.
*/
@Entity("scenario_versions")
@Unique(["scenarioId", "version"])
export class ScenarioVersionEntity {
@PrimaryGeneratedColumn("uuid")
id: string;
@Column("text")
scenarioId: string;
@ManyToOne(() => ScenarioEntity, { onDelete: "CASCADE" })
@JoinColumn({ name: "scenarioId" })
scenario: ScenarioEntity;
@Column({ type: "int" })
version: number;
@Column()
name: string;
@Column("text", { nullable: true })
description: string | null;
@Column({ type: "text", nullable: true })
environmentId: string | null;
@Column({ type: "int", nullable: true })
timeoutSeconds: number | null;
@Column("simple-json")
steps: ScenarioStepSnapshot[];
@CreateDateColumn()
createdAt: Date;
}
@@ -5,6 +5,7 @@ import {
Get,
HttpCode,
Param,
ParseIntPipe,
ParseUUIDPipe,
Patch,
Post,
@@ -105,6 +106,25 @@ export class ScenarioController {
return this.scenarioService.remove(id);
}
@Get(":id/versions")
@ApiOperation({ summary: "List a scenario's versions, newest first" })
@ApiResponse({ status: 200 })
@ApiResponse({ status: 404, description: "Scenario not found" })
listVersions(@Param("id", ParseUUIDPipe) id: string) {
return this.scenarioService.listVersions(id);
}
@Get(":id/versions/:version")
@ApiOperation({ summary: "Get one version of a scenario, with its steps" })
@ApiResponse({ status: 200 })
@ApiResponse({ status: 404, description: "Scenario or version not found" })
findVersion(
@Param("id", ParseUUIDPipe) id: string,
@Param("version", ParseIntPipe) version: number,
) {
return this.scenarioService.findVersion(id, version);
}
@Get(":id/export")
@ApiOperation({ summary: "Export a scenario as portable YAML" })
@ApiResponse({ status: 200 })
@@ -113,6 +133,8 @@ export class ScenarioController {
@Param("id", ParseUUIDPipe) id: string,
@Query("includeEnvironment") includeEnvironment: string,
@Query("credentialIds") credentialIds: string | string[] | undefined,
@Query("version", new ParseIntPipe({ optional: true }))
version: number | undefined,
@Res({ passthrough: true }) res: Response,
) {
const credIds: string[] = credentialIds
@@ -123,6 +145,7 @@ export class ScenarioController {
const entities = await this.scenarioService.exportScenario(id, {
includeEnvironment: includeEnvironment === "true",
credentialIds: credIds,
version,
});
res.setHeader("Content-Type", "application/yaml; charset=utf-8");
// Serialize as YAML stream: each entity separated by a comment header
@@ -284,6 +307,7 @@ export class ScenarioController {
dto.environmentId,
dto.saveSession,
dto.traceMode,
dto.version,
);
}
+4
View File
@@ -29,6 +29,10 @@ export class ScenarioEntity {
@Column({ type: "int", nullable: true })
timeoutSeconds: number | null;
/** Latest version number; incremented whenever the scenario content changes. */
@Column({ type: "int", default: 1 })
version: number;
@ManyToOne(() => EnvironmentEntity, { nullable: true, onDelete: "SET NULL", eager: false })
@JoinColumn({ name: "environmentId" })
environment: EnvironmentEntity | null;
+2
View File
@@ -14,6 +14,7 @@ import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario-run.entity";
import { ScenarioSchedulerService } from "./scenario-scheduler.service";
import { ScenarioVersionEntity } from "./scenario-version.entity";
import { ScenarioStepEntity } from "./scenario-step.entity";
import { ScenarioController } from "./scenario.controller";
import { ScenarioEntity } from "./scenario.entity";
@@ -25,6 +26,7 @@ import { E2eExportService } from "./e2e-export.service";
TypeOrmModule.forFeature([
ScenarioEntity,
ScenarioStepEntity,
ScenarioVersionEntity,
ScenarioRunEntity,
ScenarioRunStepEntity,
ScenarioRunLogEntity,
+257 -54
View File
@@ -3,6 +3,7 @@ import {
ConflictException,
Injectable,
NotFoundException,
OnModuleInit,
} from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { InjectRepository } from "@nestjs/typeorm";
@@ -13,7 +14,10 @@ import {
PaginatedResult,
PaginationQueryDto,
} from "../common/dto/pagination.dto";
import { resolveUsedSnippetAliases } from "../common/snippet-usage";
import {
parseSnippetRef,
resolveUsedSnippetAliases,
} from "../common/snippet-usage";
import type { AppConfig, TraceMode } from "../config/app.config";
import { CredentialEntity } from "../credential/credential.entity";
import { EnvironmentEntity } from "../environment/environment.entity";
@@ -39,6 +43,10 @@ import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario-run.entity";
import { ScenarioStepEntity } from "./scenario-step.entity";
import {
ScenarioStepSnapshot,
ScenarioVersionEntity,
} from "./scenario-version.entity";
import { ScenarioEntity } from "./scenario.entity";
import { Response } from "express";
import type { File as MulterFile } from "multer";
@@ -46,13 +54,49 @@ import type { File as MulterFile } from "multer";
export { PaginatedResult } from "../common/dto/pagination.dto";
export type ScenarioOrderBy = "id" | "name" | "createdAt" | "updatedAt";
/** The versioned content of a scenario. */
type ScenarioContent = Pick<
ScenarioVersionEntity,
"name" | "description" | "environmentId" | "timeoutSeconds" | "steps"
>;
function contentKey(c: ScenarioContent): string {
return JSON.stringify([
c.name,
c.description ?? null,
c.environmentId ?? null,
c.timeoutSeconds ?? null,
// Step ids are not content: re-created steps with equal content are equal
c.steps.map((s) => [s.order, s.title, s.execCode, s.timeoutSeconds]),
]);
}
function stepsSnapshot(steps: ScenarioStepEntity[]): ScenarioStepSnapshot[] {
return [...steps]
.sort((a, b) => a.order - b.order)
.map((s) => ({
id: s.id,
order: s.order,
title: s.title,
execCode: s.execCode,
timeoutSeconds: s.timeoutSeconds,
}));
}
export type UsedSnippet = SnippetEntity & {
/** Version pinned via `runSnippet("alias@N")`, or null for the latest. */
pinnedVersion: number | null;
};
@Injectable()
export class ScenarioService {
export class ScenarioService implements OnModuleInit {
constructor(
@InjectRepository(ScenarioEntity)
private readonly scenarioRepo: Repository<ScenarioEntity>,
@InjectRepository(ScenarioStepEntity)
private readonly stepRepo: Repository<ScenarioStepEntity>,
@InjectRepository(ScenarioVersionEntity)
private readonly versionRepo: Repository<ScenarioVersionEntity>,
@InjectRepository(ScenarioRunEntity)
private readonly runRepo: Repository<ScenarioRunEntity>,
@InjectRepository(ScenarioRunStepEntity)
@@ -74,10 +118,93 @@ export class ScenarioService {
private readonly configService: ConfigService<AppConfig, true>,
) {}
async onModuleInit(): Promise<void> {
await this.backfillVersions();
await this.backfillRunStepSnapshots();
}
/** Records the current content of scenarios that have no row for their current version yet. */
private async backfillVersions(): Promise<void> {
const scenarios = await this.scenarioRepo.find({ select: { id: true } });
for (const { id } of scenarios) await this.commitVersion(id);
}
/**
* Run steps created before versioning point at the live step instead of
* holding a copy of it; copy the live step content into them.
*/
private async backfillRunStepSnapshots(): Promise<void> {
await this.runStepRepo.query(`
UPDATE scenario_run_steps SET
title = (SELECT title FROM scenario_steps WHERE id = scenarioStepId),
execCode = (SELECT execCode FROM scenario_steps WHERE id = scenarioStepId),
timeoutSeconds = (SELECT timeoutSeconds FROM scenario_steps WHERE id = scenarioStepId)
WHERE title IS NULL AND execCode IS NULL AND timeoutSeconds IS NULL
AND scenarioStepId IS NOT NULL
AND runId IN (SELECT id FROM scenario_runs WHERE scenarioVersion IS NULL)
`);
}
// ── Versions ──────────────────────────────────────────────────────────────
/**
* Snapshots the scenario's current content. The first snapshot is stored as
* the scenario's current version; later ones bump the version, unless the
* content is unchanged since the latest snapshot.
*/
private async commitVersion(scenarioId: string): Promise<void> {
const scenario = await this.findOne(scenarioId);
const content: ScenarioContent = {
name: scenario.name,
description: scenario.description,
environmentId: scenario.environmentId,
timeoutSeconds: scenario.timeoutSeconds,
steps: stepsSnapshot(scenario.steps),
};
const latest = await this.versionRepo.findOneBy({
scenarioId,
version: scenario.version,
});
if (latest && contentKey(latest) === contentKey(content)) return;
const version = latest ? scenario.version + 1 : scenario.version;
if (version !== scenario.version) {
await this.scenarioRepo.update(scenarioId, { version });
}
await this.versionRepo.save(
this.versionRepo.create({ scenarioId, version, ...content }),
);
}
async listVersions(scenarioId: string): Promise<ScenarioVersionEntity[]> {
await this.findOne(scenarioId); // 404 guard
return this.versionRepo.find({
where: { scenarioId },
order: { version: "DESC" },
});
}
async findVersion(
scenarioId: string,
version: number,
): Promise<ScenarioVersionEntity> {
await this.findOne(scenarioId); // 404 guard
const row = await this.versionRepo.findOneBy({ scenarioId, version });
if (!row) {
throw new NotFoundException(
`Scenario ${scenarioId} has no version ${version}`,
);
}
return row;
}
// ── Scenarios ─────────────────────────────────────────────────────────────
create(dto: CreateScenarioDto): Promise<ScenarioEntity> {
return this.scenarioRepo.save(this.scenarioRepo.create(dto));
async create(dto: CreateScenarioDto): Promise<ScenarioEntity> {
const scenario = await this.scenarioRepo.save(
this.scenarioRepo.create({ ...dto, version: 1 }),
);
await this.commitVersion(scenario.id);
return this.findOne(scenario.id);
}
async findAll(
@@ -145,7 +272,9 @@ export class ScenarioService {
async update(id: string, dto: UpdateScenarioDto): Promise<ScenarioEntity> {
const scenario = await this.findOne(id);
Object.assign(scenario, dto);
return this.scenarioRepo.save(scenario);
await this.scenarioRepo.save(scenario);
await this.commitVersion(id);
return this.findOne(id);
}
async remove(id: string): Promise<void> {
@@ -185,6 +314,7 @@ export class ScenarioService {
}),
);
await this.normalizeStepOrder(scenarioId);
await this.commitVersion(scenarioId);
return this.findStep(scenarioId, created.id);
}
@@ -243,6 +373,7 @@ export class ScenarioService {
await this.normalizeStepOrder(scenarioId);
}
await this.commitVersion(scenarioId);
return this.findStep(scenarioId, stepId);
}
@@ -250,6 +381,7 @@ export class ScenarioService {
await this.findStep(scenarioId, stepId);
await this.stepRepo.delete(stepId);
await this.normalizeStepOrder(scenarioId);
await this.commitVersion(scenarioId);
}
// ── Scenario Credentials ──────────────────────────────────────────────────
@@ -343,19 +475,22 @@ export class ScenarioService {
* Returns the snippets referenced (directly, or transitively via other snippets)
* by this scenario's step code, in discovery order - for linking to them from the UI.
*/
async getUsedSnippets(scenarioId: string): Promise<SnippetEntity[]> {
async getUsedSnippets(scenarioId: string): Promise<UsedSnippet[]> {
const scenario = await this.findOne(scenarioId);
const snippetMap = await this.snippetService.buildSnippetMap();
const usedAliases = resolveUsedSnippetAliases(
const usedRefs = resolveUsedSnippetAliases(
scenario.steps.map((s) => s.execCode ?? ""),
snippetMap,
);
if (usedAliases.length === 0) return [];
const snippets = await this.snippetService.findByAliases(usedAliases);
).map(parseSnippetRef);
if (usedRefs.length === 0) return [];
const snippets = await this.snippetService.findByAliases([
...new Set(usedRefs.map((r) => r.alias)),
]);
const byAlias = new Map(snippets.map((s) => [s.alias, s]));
return usedAliases
.map((alias) => byAlias.get(alias))
.filter((s): s is SnippetEntity => s != null);
return usedRefs.flatMap(({ alias, version }) => {
const snippet = byAlias.get(alias);
return snippet ? [{ ...snippet, pinnedVersion: version }] : [];
});
}
// ── Runs ──────────────────────────────────────────────────────────────────
@@ -500,8 +635,13 @@ export class ScenarioService {
environmentId: string,
saveSession = false,
traceMode?: TraceMode,
version?: number,
): Promise<ScenarioRunEntity> {
const scenario = await this.findOne(scenarioId);
const scenarioVersion = await this.findVersion(
scenarioId,
version ?? scenario.version,
);
const environment = await this.environmentRepo.findOneBy({
id: environmentId,
});
@@ -516,14 +656,19 @@ export class ScenarioService {
status: "pending",
saveSession,
traceMode: traceMode ?? this.getRunDefaults().traceMode,
scenarioVersion: scenarioVersion.version,
}),
);
const stepRuns = scenario.steps.map((step, index) =>
const liveStepIds = new Set(scenario.steps.map((s) => s.id));
const stepRuns = scenarioVersion.steps.map((step, index) =>
this.runStepRepo.create({
runId: run.id,
scenarioStepId: step.id,
scenarioStepId: step.id && liveStepIds.has(step.id) ? step.id : null,
order: step.order,
title: step.title,
execCode: step.execCode,
timeoutSeconds: step.timeoutSeconds,
status: index === 0 ? "pending" : "waiting",
description: null,
}),
@@ -542,9 +687,18 @@ export class ScenarioService {
async exportScenario(
id: string,
options: { includeEnvironment: boolean; credentialIds: string[] },
options: {
includeEnvironment: boolean;
credentialIds: string[];
/** Version to export; defaults to the latest. */
version?: number;
},
): Promise<ExportEntity[]> {
const scenario = await this.findOne(id);
const content = await this.findVersion(
id,
options.version ?? scenario.version,
);
const entities: ExportEntity[] = [];
// Include environment entity if requested and linked
@@ -591,13 +745,16 @@ export class ScenarioService {
const scenarioDto: ScenarioExportDto = {
kind: "scenario",
id: scenario.id,
name: scenario.name,
description: scenario.description ?? undefined,
environmentId: scenario.environmentId ?? undefined,
version: content.version,
name: content.name,
description: content.description ?? undefined,
environmentId: content.environmentId ?? undefined,
timeoutSeconds: content.timeoutSeconds ?? undefined,
credentials: credentialMappings.length > 0 ? credentialMappings : undefined,
steps: scenario.steps.map((s) => ({
steps: content.steps.map((s) => ({
title: s.title,
execCode: s.execCode,
...(s.timeoutSeconds != null ? { timeoutSeconds: s.timeoutSeconds } : {}),
})),
};
entities.push(scenarioDto);
@@ -678,46 +835,72 @@ export class ScenarioService {
throw new BadRequestException("steps must be an array");
}
if (!Number.isInteger(scenarioDto.version) || scenarioDto.version < 1) {
throw new BadRequestException("version must be a positive integer");
}
// Restore the exported version: upsert by id + version. An existing
// version is left untouched; a new one is stored under its number and
// becomes the latest when it is higher than the current latest.
const dto = scenarioDto;
const content: ScenarioContent = {
name: dto.name,
description: dto.description ?? null,
environmentId: dto.environmentId ?? null,
timeoutSeconds: dto.timeoutSeconds ?? null,
steps: dto.steps.map((s, index) => ({
id: null,
order: index + 1,
title: s.title ?? null,
execCode: s.execCode ?? null,
timeoutSeconds: s.timeoutSeconds ?? null,
})),
};
const existing = dto.id
? await this.scenarioRepo.findOneBy({ id: dto.id })
: null;
let scenario: ScenarioEntity;
if (dto.id) {
const existing = await this.scenarioRepo.findOneBy({ id: dto.id });
if (existing) {
existing.name = dto.name;
existing.description = dto.description ?? null;
existing.environmentId = dto.environmentId ?? existing.environmentId;
scenario = await this.scenarioRepo.save(existing);
await this.stepRepo.delete({ scenarioId: scenario.id });
} else {
scenario = await this.scenarioRepo.save(
this.scenarioRepo.create({
id: dto.id,
name: dto.name,
description: dto.description ?? null,
environmentId: dto.environmentId ?? null,
}),
);
}
} else {
if (!existing) {
scenario = await this.scenarioRepo.save(
this.scenarioRepo.create({
name: dto.name,
description: dto.description ?? null,
environmentId: dto.environmentId ?? null,
...(dto.id ? { id: dto.id } : {}),
name: content.name,
description: content.description,
environmentId: content.environmentId,
timeoutSeconds: content.timeoutSeconds,
version: dto.version,
}),
);
}
if (dto.steps.length > 0) {
const steps = dto.steps.map((s, index) =>
this.stepRepo.create({
scenarioId: scenario.id,
order: index,
title: s.title ?? null,
execCode: s.execCode ?? null,
}),
);
await this.stepRepo.save(steps);
await this.normalizeStepOrder(scenario.id);
await this.replaceSteps(scenario.id, content.steps);
await this.commitVersion(scenario.id);
} else {
scenario = existing;
const hasVersion = await this.versionRepo.existsBy({
scenarioId: existing.id,
version: dto.version,
});
if (!hasVersion) {
if (dto.version > existing.version) {
Object.assign(existing, {
name: content.name,
description: content.description,
environmentId: content.environmentId ?? existing.environmentId,
timeoutSeconds: content.timeoutSeconds,
version: dto.version,
});
scenario = await this.scenarioRepo.save(existing);
await this.replaceSteps(scenario.id, content.steps);
await this.commitVersion(scenario.id);
} else {
await this.versionRepo.save(
this.versionRepo.create({
scenarioId: existing.id,
version: dto.version,
...content,
}),
);
}
}
}
// Restore credential alias mappings
if (dto.credentials && dto.credentials.length > 0) {
@@ -734,6 +917,26 @@ export class ScenarioService {
return this.findOne(scenario.id);
}
private async replaceSteps(
scenarioId: string,
steps: ScenarioStepSnapshot[],
): Promise<void> {
await this.stepRepo.delete({ scenarioId });
if (steps.length === 0) return;
await this.stepRepo.save(
steps.map((s) =>
this.stepRepo.create({
scenarioId,
order: s.order,
title: s.title,
execCode: s.execCode,
timeoutSeconds: s.timeoutSeconds,
}),
),
);
await this.normalizeStepOrder(scenarioId);
}
// ── Files ─────────────────────────────────────────────────────────────────
async uploadFile(
@@ -1,6 +1,8 @@
import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
import {
IsIn,
IsInt,
Min,
IsNotEmpty,
IsOptional,
IsString,
@@ -18,6 +20,11 @@ export class SnippetExportDto {
@IsUUID()
id?: string;
@ApiProperty({ description: "Snippet version this export holds" })
@IsInt()
@Min(1)
version: number;
@ApiPropertyOptional()
@IsOptional()
@IsString()
@@ -0,0 +1,47 @@
import {
Column,
CreateDateColumn,
Entity,
JoinColumn,
ManyToOne,
PrimaryGeneratedColumn,
Unique,
} from "typeorm";
import { SnippetEntity } from "./snippet.entity";
/**
* Immutable snapshot of a snippet at one version. The `snippets` table always
* holds the latest version. Step code pins a version with
* `runSnippet("alias@<version>")`.
*/
@Entity("snippet_versions")
@Unique(["snippetId", "version"])
export class SnippetVersionEntity {
@PrimaryGeneratedColumn("uuid")
id: string;
@Column("text")
snippetId: string;
@ManyToOne(() => SnippetEntity, { onDelete: "CASCADE" })
@JoinColumn({ name: "snippetId" })
snippet: SnippetEntity;
@Column({ type: "int" })
version: number;
@Column()
alias: string;
@Column({ default: "" })
title: string;
@Column("text", { nullable: true })
description: string | null;
@Column("text")
code: string;
@CreateDateColumn()
createdAt: Date;
}
+25 -2
View File
@@ -5,6 +5,7 @@ import {
Get,
HttpCode,
Param,
ParseIntPipe,
ParseUUIDPipe,
Patch,
Post,
@@ -48,9 +49,31 @@ export class SnippetController {
@ApiOperation({ summary: "Export a snippet as a plain object" })
@ApiResponse({ status: 200, description: "Snippet export payload" })
@ApiResponse({ status: 404, description: "Snippet not found" })
async exportSnippet(@Param("id", ParseUUIDPipe) id: string) {
async exportSnippet(
@Param("id", ParseUUIDPipe) id: string,
@Query("version", new ParseIntPipe({ optional: true })) version?: number,
) {
const snippet = await this.snippetService.findOne(id);
return this.snippetService.exportSnippet(snippet);
return this.snippetService.exportSnippet(snippet, version);
}
@Get(":id/versions")
@ApiOperation({ summary: "List a snippet's versions, newest first" })
@ApiResponse({ status: 200, description: "Snippet versions" })
@ApiResponse({ status: 404, description: "Snippet not found" })
listVersions(@Param("id", ParseUUIDPipe) id: string) {
return this.snippetService.listVersions(id);
}
@Get(":id/versions/:version")
@ApiOperation({ summary: "Get one version of a snippet" })
@ApiResponse({ status: 200, description: "Snippet version" })
@ApiResponse({ status: 404, description: "Snippet or version not found" })
findVersion(
@Param("id", ParseUUIDPipe) id: string,
@Param("version", ParseIntPipe) version: number,
) {
return this.snippetService.findVersion(id, version);
}
@Get(":id")
+4
View File
@@ -30,6 +30,10 @@ export class SnippetEntity {
@Column("text")
code: string;
/** Latest version number; incremented whenever the snippet changes. */
@Column({ type: "int", default: 1 })
version: number;
@CreateDateColumn()
createdAt: Date;
+2 -1
View File
@@ -2,10 +2,11 @@ import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { SnippetController } from "./snippet.controller";
import { SnippetEntity } from "./snippet.entity";
import { SnippetVersionEntity } from "./snippet-version.entity";
import { SnippetService } from "./snippet.service";
@Module({
imports: [TypeOrmModule.forFeature([SnippetEntity])],
imports: [TypeOrmModule.forFeature([SnippetEntity, SnippetVersionEntity])],
controllers: [SnippetController],
providers: [SnippetService],
exports: [SnippetService],
+154 -35
View File
@@ -5,7 +5,7 @@ import {
OnModuleInit,
} from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { In, Repository } from "typeorm";
import { In, Not, Repository } from "typeorm";
import {
PaginatedResult,
PaginationQueryDto,
@@ -13,8 +13,20 @@ import {
import { CreateSnippetDto } from "./dto/create-snippet.dto";
import { SnippetExportDto } from "./dto/snippet-export.dto";
import { UpdateSnippetDto } from "./dto/update-snippet.dto";
import { SnippetVersionEntity } from "./snippet-version.entity";
import { SnippetEntity } from "./snippet.entity";
type SnippetContent = Pick<
SnippetEntity,
"alias" | "title" | "description" | "code"
>;
const sameContent = (a: SnippetContent, b: SnippetContent): boolean =>
a.alias === b.alias &&
a.title === b.title &&
(a.description ?? null) === (b.description ?? null) &&
a.code === b.code;
export type SnippetOrderBy =
| "id"
| "alias"
@@ -27,6 +39,8 @@ export class SnippetService implements OnModuleInit {
constructor(
@InjectRepository(SnippetEntity)
private readonly repo: Repository<SnippetEntity>,
@InjectRepository(SnippetVersionEntity)
private readonly versionRepo: Repository<SnippetVersionEntity>,
) {}
async onModuleInit(): Promise<void> {
@@ -47,6 +61,32 @@ export class SnippetService implements OnModuleInit {
"UPDATE snippets SET title = COALESCE(alias, '') WHERE title IS NULL OR title = ''",
);
}
await this.backfillVersions();
}
/** Records the current content of snippets that have no row for their current version yet. */
private async backfillVersions(): Promise<void> {
const snippets = await this.repo.find();
for (const snippet of snippets) {
const exists = await this.versionRepo.existsBy({
snippetId: snippet.id,
version: snippet.version,
});
if (!exists) await this.recordVersion(snippet);
}
}
private recordVersion(snippet: SnippetEntity): Promise<SnippetVersionEntity> {
return this.versionRepo.save(
this.versionRepo.create({
snippetId: snippet.id,
version: snippet.version,
alias: snippet.alias,
title: snippet.title,
description: snippet.description,
code: snippet.code,
}),
);
}
async create(dto: CreateSnippetDto): Promise<SnippetEntity> {
@@ -56,14 +96,17 @@ export class SnippetService implements OnModuleInit {
`Snippet alias "${dto.alias}" already exists`,
);
}
return this.repo.save(
const snippet = await this.repo.save(
this.repo.create({
alias: dto.alias,
title: dto.title,
description: dto.description ?? null,
code: dto.code,
version: 1,
}),
);
await this.recordVersion(snippet);
return snippet;
}
async findAll(
@@ -96,8 +139,37 @@ export class SnippetService implements OnModuleInit {
`Snippet alias "${dto.alias}" already exists`,
);
}
Object.assign(snippet, dto);
return this.repo.save(snippet);
const next: SnippetContent = {
alias: dto.alias ?? snippet.alias,
title: dto.title ?? snippet.title,
description:
dto.description !== undefined ? dto.description : snippet.description,
code: dto.code ?? snippet.code,
};
if (sameContent(snippet, next)) return snippet;
Object.assign(snippet, next, { version: snippet.version + 1 });
const saved = await this.repo.save(snippet);
await this.recordVersion(saved);
return saved;
}
// ── Versions ──────────────────────────────────────────────────────────────
async listVersions(id: string): Promise<SnippetVersionEntity[]> {
await this.findOne(id); // 404 guard
return this.versionRepo.find({
where: { snippetId: id },
order: { version: "DESC" },
});
}
async findVersion(id: string, version: number): Promise<SnippetVersionEntity> {
await this.findOne(id); // 404 guard
const row = await this.versionRepo.findOneBy({ snippetId: id, version });
if (!row) {
throw new NotFoundException(`Snippet ${id} has no version ${version}`);
}
return row;
}
async remove(id: string): Promise<void> {
@@ -105,10 +177,25 @@ export class SnippetService implements OnModuleInit {
await this.repo.delete(id);
}
/** Returns an alias→code map for all snippets (used by the executor). */
/**
* Returns the code map used by the executor: `alias` → latest code, plus
* `alias@<version>` → that version's code for every stored version. Pinned
* references use the snippet's current alias.
*/
async buildSnippetMap(): Promise<Record<string, string>> {
const { data } = await this.findAll({ limit: 1000 });
return Object.fromEntries(data.map((s) => [s.alias, s.code]));
const map: Record<string, string> = Object.fromEntries(
data.map((s) => [s.alias, s.code]),
);
if (data.length === 0) return map;
const aliasById = new Map(data.map((s) => [s.id, s.alias]));
const versions = await this.versionRepo.find({
where: { snippetId: In([...aliasById.keys()]) },
});
for (const v of versions) {
map[`${aliasById.get(v.snippetId)}@${v.version}`] = v.code;
}
return map;
}
/** Returns the snippet entities matching the given aliases (used by executor/executor consumers). */
@@ -117,52 +204,84 @@ export class SnippetService implements OnModuleInit {
return this.repo.find({ where: { alias: In(aliases) } });
}
exportSnippet(snippet: SnippetEntity): SnippetExportDto {
/** Exports the latest version, or `version` when given. */
async exportSnippet(
snippet: SnippetEntity,
version?: number,
): Promise<SnippetExportDto> {
const content: SnippetContent & { version: number } =
version === undefined || version === snippet.version
? snippet
: await this.findVersion(snippet.id, version);
return {
kind: "snippet",
id: snippet.id,
alias: snippet.alias,
title: snippet.title,
description: snippet.description,
code: snippet.code,
version: content.version,
alias: content.alias,
title: content.title,
description: content.description,
code: content.code,
};
}
/**
* Restores the exported version: upsert by id + version. An existing version
* is left untouched; a new one is stored under its number and becomes the
* latest when it is higher than the current latest.
*/
async importSnippet(dto: SnippetExportDto): Promise<SnippetEntity> {
const alias = dto.alias ?? dto.name;
if (!alias) {
throw new ConflictException("Snippet alias is required");
}
const title = dto.title ?? alias;
const content: SnippetContent = {
alias,
title: dto.title ?? alias,
description: dto.description ?? null,
code: dto.code,
};
if (dto.id) {
const existing = await this.repo.findOneBy({ id: dto.id });
if (existing) {
Object.assign(existing, {
alias,
title,
description: dto.description ?? null,
code: dto.code,
});
return this.repo.save(existing);
}
return this.repo.save(
const existing = dto.id ? await this.repo.findOneBy({ id: dto.id }) : null;
if (!existing) {
await this.assertAliasFree(alias);
const created = await this.repo.save(
this.repo.create({
id: dto.id,
alias,
title,
description: dto.description ?? null,
code: dto.code,
...(dto.id ? { id: dto.id } : {}),
...content,
version: dto.version,
}),
);
await this.recordVersion(created);
return created;
}
return this.repo.save(
this.repo.create({
alias,
title,
description: dto.description ?? null,
code: dto.code,
const hasVersion = await this.versionRepo.existsBy({
snippetId: existing.id,
version: dto.version,
});
if (hasVersion) return existing;
await this.versionRepo.save(
this.versionRepo.create({
snippetId: existing.id,
version: dto.version,
...content,
}),
);
if (dto.version > existing.version) {
if (alias !== existing.alias) await this.assertAliasFree(alias, existing.id);
Object.assign(existing, content, { version: dto.version });
return this.repo.save(existing);
}
return existing;
}
private async assertAliasFree(alias: string, exceptId?: string): Promise<void> {
const conflict = await this.repo.findOneBy(
exceptId ? { alias, id: Not(exceptId) } : { alias },
);
if (conflict) {
throw new ConflictException(`Snippet alias "${alias}" already exists`);
}
}
}