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

@@ -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`);
}
}
}