donobu 5.37.0 → 5.38.0

package/dist/cli/donobu-cli.js

@@ -68,6 +68,7 @@ const merge_1 = require("../reporter/merge");
 const model_1 = require("../reporter/model");
 const render_1 = require("../reporter/render");
 const renderMarkdown_1 = require("../reporter/renderMarkdown");
+const renderPullRequestBody_1 = require("../reporter/renderPullRequestBody");
 const renderSlack_1 = require("../reporter/renderSlack");
 const slack_1 = require("../reporter/slack");
 const Logger_1 = require("../utils/Logger");
@@ -1404,6 +1405,7 @@ async function attemptAutoHealRun(params) {
             }
             if (mergedReport) {
                 await regenerateDonobuReports(mergedReport);
+                await writeAutoHealPullRequestBody(mergedReport, params.playwrightOutputDir);
             }
         }
     }
@@ -1412,6 +1414,38 @@ async function attemptAutoHealRun(params) {
     }
     return { attempted: true, exitCode: healExitCode };
 }
+/**
+ * Filename of the auto-heal PR body artifact. Lands in the Playwright output
+ * directory alongside the merged JSON / HTML / Markdown reports so the
+ * generated GitHub Actions workflow can find it at a stable, well-known path
+ * when preparing the self-healing pull request body.
+ */
+const AUTO_HEAL_PR_BODY_FILENAME = 'auto-heal-pr-body.md';
+/**
+ * Emit a PR-shaped markdown body when auto-heal applied fixes. The generated
+ * GitHub Actions workflow points peter-evans/create-pull-request at this file
+ * via `body-path:`, so all PR-body composition (heading, healed list,
+ * reviewer checklist, workflow-run footer) lives here rather than in
+ * customer-facing YAML. Skipped when no tests were healed; peter-evans is
+ * gated by `hashFiles()` in that case so it won't try to read a missing file.
+ * Failures are logged but never surfaced — a missing PR body should not block
+ * the heal run from exiting cleanly.
+ */
+async function writeAutoHealPullRequestBody(mergedReport, playwrightOutputDir) {
+    try {
+        const body = (0, renderPullRequestBody_1.renderPullRequestBody)(mergedReport);
+        if (!body) {
+            return;
+        }
+        await fs_1.promises.mkdir(playwrightOutputDir, { recursive: true });
+        const outputFile = path.join(playwrightOutputDir, AUTO_HEAL_PR_BODY_FILENAME);
+        await fs_1.promises.writeFile(outputFile, body, 'utf8');
+        Logger_1.appLogger.info(`Donobu auto-heal PR body written to: ${outputFile}`);
+    }
+    catch (error) {
+        Logger_1.appLogger.warn('Failed to write Donobu auto-heal PR body.', error);
+    }
+}
 /**
  * Copy attachment files that live in a temporary directory (e.g. the auto-heal
  * staging area) into the persistent output directory and rewrite the paths in

package/dist/codegen/CodeGenerator.js

@@ -429,17 +429,21 @@ on:
     const pullRequestCreationSection = options.disablePullRequestCreation
         ? ''
         : `
-      # Create a self-healing PR only when this workflow was not triggered by a pull-request.
+      # Open a self-healing PR with whatever auto-heal changed. Donobu writes
+      # the PR body to test-results/auto-heal-pr-body.md when it heals tests;
+      # the hashFiles() guard skips PR creation when no body is present.
       - name: Create Pull Request for Test Fixes (if any)
-        if: \${{ github.event_name != 'pull_request' }}
+        if: \${{ github.event_name != 'pull_request' && hashFiles('test-results/auto-heal-pr-body.md') }}
         uses: peter-evans/create-pull-request@v8
         with:
           token: \${{ secrets.GITHUB_TOKEN }}
-          commit-message: "Fix failing Playwright tests"
-          title: "[Fixed] Playwright tests"
-          body: "Fix failing Playwright tests"
+          commit-message: "Donobu auto-heal: fix failing tests"
+          title: "Donobu auto-heal: Test fixes for \${{ github.ref_name }}"
+          body-path: test-results/auto-heal-pr-body.md
           branch: fix-playwright-tests-for-\${{ github.ref_name }}
-          base: \${{ github.ref_name }}`;
+          base: \${{ github.ref_name }}
+          labels: donobu, auto-heal
+          delete-branch: true`;
     return `name: Run Playwright Tests
 ${triggerSection}
 

package/dist/envVars.d.ts

@@ -42,6 +42,16 @@ export declare const env: Env<{
     DONOBU_REPORT_URL: z.ZodOptional<z.ZodString>;
     DONOBU_SLACK_WEBHOOK_URL: z.ZodOptional<z.ZodString>;
     GITHUB_STEP_SUMMARY: z.ZodOptional<z.ZodString>;
+    GITHUB_RUN_ID: z.ZodOptional<z.ZodString>;
+    GITHUB_RUN_NUMBER: z.ZodOptional<z.ZodString>;
+    GITHUB_SERVER_URL: z.ZodOptional<z.ZodString>;
+    GITHUB_REPOSITORY: z.ZodOptional<z.ZodString>;
+    GITHUB_ACTOR: z.ZodOptional<z.ZodString>;
+    GITHUB_REF_NAME: z.ZodOptional<z.ZodString>;
+    CI_PIPELINE_URL: z.ZodOptional<z.ZodString>;
+    CI_PIPELINE_IID: z.ZodOptional<z.ZodString>;
+    GITLAB_USER_LOGIN: z.ZodOptional<z.ZodString>;
+    CI_COMMIT_REF_NAME: z.ZodOptional<z.ZodString>;
     PLAYWRIGHT_JSON_OUTPUT_DIR: z.ZodOptional<z.ZodString>;
     DONOBU_PAGE_AI_CLEAR_CACHE: z.ZodOptional<z.ZodEnum<{
         0: "0";
@@ -92,6 +102,16 @@ export declare const env: Env<{
     DONOBU_REPORT_URL?: string | undefined;
     DONOBU_SLACK_WEBHOOK_URL?: string | undefined;
     GITHUB_STEP_SUMMARY?: string | undefined;
+    GITHUB_RUN_ID?: string | undefined;
+    GITHUB_RUN_NUMBER?: string | undefined;
+    GITHUB_SERVER_URL?: string | undefined;
+    GITHUB_REPOSITORY?: string | undefined;
+    GITHUB_ACTOR?: string | undefined;
+    GITHUB_REF_NAME?: string | undefined;
+    CI_PIPELINE_URL?: string | undefined;
+    CI_PIPELINE_IID?: string | undefined;
+    GITLAB_USER_LOGIN?: string | undefined;
+    CI_COMMIT_REF_NAME?: string | undefined;
     PLAYWRIGHT_JSON_OUTPUT_DIR?: string | undefined;
     DONOBU_PAGE_AI_CLEAR_CACHE?: "0" | "1" | "true" | "false" | undefined;
     GOOGLE_GENERATIVE_AI_API_KEY?: string | undefined;

package/dist/envVars.js

@@ -79,6 +79,46 @@ network call.`),
         .describe(`Set by the GitHub Actions runner to the path of a per-step Markdown file. Anything
 written here is concatenated into the workflow run's job summary. The Donobu Markdown reporter writes
 to this automatically when running inside a GHA step so no separate workflow step is needed.`),
+    GITHUB_RUN_ID: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Used by the auto-heal PR body footer to link back to the workflow run that produced the heal.`),
+    GITHUB_RUN_NUMBER: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Embedded in the auto-heal PR body footer as a human-friendly run number.`),
+    GITHUB_SERVER_URL: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner (e.g. https://github.com). Combined with GITHUB_REPOSITORY and GITHUB_RUN_ID to build the auto-heal PR body footer link.`),
+    GITHUB_REPOSITORY: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner (owner/repo). Used by the auto-heal PR body footer link.`),
+    GITHUB_ACTOR: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Embedded in the auto-heal PR body footer as the user who triggered the run.`),
+    GITHUB_REF_NAME: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Embedded in the auto-heal PR body footer as the source branch.`),
+    CI_PIPELINE_URL: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner. Used by the auto-heal MR body footer to link back to the pipeline that produced the heal.`),
+    CI_PIPELINE_IID: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner — the per-project pipeline number GitLab shows in its UI. Embedded in the auto-heal MR body footer.`),
+    GITLAB_USER_LOGIN: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner. Embedded in the auto-heal MR body footer as the user who triggered the pipeline.`),
+    CI_COMMIT_REF_NAME: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner. Embedded in the auto-heal MR body footer as the source branch.`),
     PLAYWRIGHT_JSON_OUTPUT_DIR: v4_1.z.string().optional()
         .describe(`Directory where the Playwright JSON reporter writes its output (and where the Donobu
 reporters merge their per-reporter state into a shared sidecar so the auto-heal orchestrator can

package/dist/esm/cli/donobu-cli.js

@@ -68,6 +68,7 @@ const merge_1 = require("../reporter/merge");
 const model_1 = require("../reporter/model");
 const render_1 = require("../reporter/render");
 const renderMarkdown_1 = require("../reporter/renderMarkdown");
+const renderPullRequestBody_1 = require("../reporter/renderPullRequestBody");
 const renderSlack_1 = require("../reporter/renderSlack");
 const slack_1 = require("../reporter/slack");
 const Logger_1 = require("../utils/Logger");
@@ -1404,6 +1405,7 @@ async function attemptAutoHealRun(params) {
             }
             if (mergedReport) {
                 await regenerateDonobuReports(mergedReport);
+                await writeAutoHealPullRequestBody(mergedReport, params.playwrightOutputDir);
             }
         }
     }
@@ -1412,6 +1414,38 @@ async function attemptAutoHealRun(params) {
     }
     return { attempted: true, exitCode: healExitCode };
 }
+/**
+ * Filename of the auto-heal PR body artifact. Lands in the Playwright output
+ * directory alongside the merged JSON / HTML / Markdown reports so the
+ * generated GitHub Actions workflow can find it at a stable, well-known path
+ * when preparing the self-healing pull request body.
+ */
+const AUTO_HEAL_PR_BODY_FILENAME = 'auto-heal-pr-body.md';
+/**
+ * Emit a PR-shaped markdown body when auto-heal applied fixes. The generated
+ * GitHub Actions workflow points peter-evans/create-pull-request at this file
+ * via `body-path:`, so all PR-body composition (heading, healed list,
+ * reviewer checklist, workflow-run footer) lives here rather than in
+ * customer-facing YAML. Skipped when no tests were healed; peter-evans is
+ * gated by `hashFiles()` in that case so it won't try to read a missing file.
+ * Failures are logged but never surfaced — a missing PR body should not block
+ * the heal run from exiting cleanly.
+ */
+async function writeAutoHealPullRequestBody(mergedReport, playwrightOutputDir) {
+    try {
+        const body = (0, renderPullRequestBody_1.renderPullRequestBody)(mergedReport);
+        if (!body) {
+            return;
+        }
+        await fs_1.promises.mkdir(playwrightOutputDir, { recursive: true });
+        const outputFile = path.join(playwrightOutputDir, AUTO_HEAL_PR_BODY_FILENAME);
+        await fs_1.promises.writeFile(outputFile, body, 'utf8');
+        Logger_1.appLogger.info(`Donobu auto-heal PR body written to: ${outputFile}`);
+    }
+    catch (error) {
+        Logger_1.appLogger.warn('Failed to write Donobu auto-heal PR body.', error);
+    }
+}
 /**
  * Copy attachment files that live in a temporary directory (e.g. the auto-heal
  * staging area) into the persistent output directory and rewrite the paths in

package/dist/esm/codegen/CodeGenerator.js

@@ -429,17 +429,21 @@ on:
     const pullRequestCreationSection = options.disablePullRequestCreation
         ? ''
         : `
-      # Create a self-healing PR only when this workflow was not triggered by a pull-request.
+      # Open a self-healing PR with whatever auto-heal changed. Donobu writes
+      # the PR body to test-results/auto-heal-pr-body.md when it heals tests;
+      # the hashFiles() guard skips PR creation when no body is present.
       - name: Create Pull Request for Test Fixes (if any)
-        if: \${{ github.event_name != 'pull_request' }}
+        if: \${{ github.event_name != 'pull_request' && hashFiles('test-results/auto-heal-pr-body.md') }}
         uses: peter-evans/create-pull-request@v8
         with:
           token: \${{ secrets.GITHUB_TOKEN }}
-          commit-message: "Fix failing Playwright tests"
-          title: "[Fixed] Playwright tests"
-          body: "Fix failing Playwright tests"
+          commit-message: "Donobu auto-heal: fix failing tests"
+          title: "Donobu auto-heal: Test fixes for \${{ github.ref_name }}"
+          body-path: test-results/auto-heal-pr-body.md
           branch: fix-playwright-tests-for-\${{ github.ref_name }}
-          base: \${{ github.ref_name }}`;
+          base: \${{ github.ref_name }}
+          labels: donobu, auto-heal
+          delete-branch: true`;
     return `name: Run Playwright Tests
 ${triggerSection}
 

package/dist/esm/envVars.d.ts

@@ -42,6 +42,16 @@ export declare const env: Env<{
     DONOBU_REPORT_URL: z.ZodOptional<z.ZodString>;
     DONOBU_SLACK_WEBHOOK_URL: z.ZodOptional<z.ZodString>;
     GITHUB_STEP_SUMMARY: z.ZodOptional<z.ZodString>;
+    GITHUB_RUN_ID: z.ZodOptional<z.ZodString>;
+    GITHUB_RUN_NUMBER: z.ZodOptional<z.ZodString>;
+    GITHUB_SERVER_URL: z.ZodOptional<z.ZodString>;
+    GITHUB_REPOSITORY: z.ZodOptional<z.ZodString>;
+    GITHUB_ACTOR: z.ZodOptional<z.ZodString>;
+    GITHUB_REF_NAME: z.ZodOptional<z.ZodString>;
+    CI_PIPELINE_URL: z.ZodOptional<z.ZodString>;
+    CI_PIPELINE_IID: z.ZodOptional<z.ZodString>;
+    GITLAB_USER_LOGIN: z.ZodOptional<z.ZodString>;
+    CI_COMMIT_REF_NAME: z.ZodOptional<z.ZodString>;
     PLAYWRIGHT_JSON_OUTPUT_DIR: z.ZodOptional<z.ZodString>;
     DONOBU_PAGE_AI_CLEAR_CACHE: z.ZodOptional<z.ZodEnum<{
         0: "0";
@@ -92,6 +102,16 @@ export declare const env: Env<{
     DONOBU_REPORT_URL?: string | undefined;
     DONOBU_SLACK_WEBHOOK_URL?: string | undefined;
     GITHUB_STEP_SUMMARY?: string | undefined;
+    GITHUB_RUN_ID?: string | undefined;
+    GITHUB_RUN_NUMBER?: string | undefined;
+    GITHUB_SERVER_URL?: string | undefined;
+    GITHUB_REPOSITORY?: string | undefined;
+    GITHUB_ACTOR?: string | undefined;
+    GITHUB_REF_NAME?: string | undefined;
+    CI_PIPELINE_URL?: string | undefined;
+    CI_PIPELINE_IID?: string | undefined;
+    GITLAB_USER_LOGIN?: string | undefined;
+    CI_COMMIT_REF_NAME?: string | undefined;
     PLAYWRIGHT_JSON_OUTPUT_DIR?: string | undefined;
     DONOBU_PAGE_AI_CLEAR_CACHE?: "0" | "1" | "true" | "false" | undefined;
     GOOGLE_GENERATIVE_AI_API_KEY?: string | undefined;

package/dist/esm/envVars.js

@@ -79,6 +79,46 @@ network call.`),
         .describe(`Set by the GitHub Actions runner to the path of a per-step Markdown file. Anything
 written here is concatenated into the workflow run's job summary. The Donobu Markdown reporter writes
 to this automatically when running inside a GHA step so no separate workflow step is needed.`),
+    GITHUB_RUN_ID: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Used by the auto-heal PR body footer to link back to the workflow run that produced the heal.`),
+    GITHUB_RUN_NUMBER: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Embedded in the auto-heal PR body footer as a human-friendly run number.`),
+    GITHUB_SERVER_URL: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner (e.g. https://github.com). Combined with GITHUB_REPOSITORY and GITHUB_RUN_ID to build the auto-heal PR body footer link.`),
+    GITHUB_REPOSITORY: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner (owner/repo). Used by the auto-heal PR body footer link.`),
+    GITHUB_ACTOR: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Embedded in the auto-heal PR body footer as the user who triggered the run.`),
+    GITHUB_REF_NAME: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitHub Actions runner. Embedded in the auto-heal PR body footer as the source branch.`),
+    CI_PIPELINE_URL: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner. Used by the auto-heal MR body footer to link back to the pipeline that produced the heal.`),
+    CI_PIPELINE_IID: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner — the per-project pipeline number GitLab shows in its UI. Embedded in the auto-heal MR body footer.`),
+    GITLAB_USER_LOGIN: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner. Embedded in the auto-heal MR body footer as the user who triggered the pipeline.`),
+    CI_COMMIT_REF_NAME: v4_1.z
+        .string()
+        .optional()
+        .describe(`Set by the GitLab CI runner. Embedded in the auto-heal MR body footer as the source branch.`),
     PLAYWRIGHT_JSON_OUTPUT_DIR: v4_1.z.string().optional()
         .describe(`Directory where the Playwright JSON reporter writes its output (and where the Donobu
 reporters merge their per-reporter state into a shared sidecar so the auto-heal orchestrator can

package/dist/esm/exceptions/FlowIdCollisionException.d.ts

@@ -0,0 +1,6 @@
+import { DonobuException } from './DonobuException';
+export declare class FlowIdCollisionException extends DonobuException {
+    private constructor();
+    static forId(flowId: string): FlowIdCollisionException;
+}
+//# sourceMappingURL=FlowIdCollisionException.d.ts.map

package/dist/esm/exceptions/FlowIdCollisionException.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowIdCollisionException = void 0;
+const DonobuException_1 = require("./DonobuException");
+class FlowIdCollisionException extends DonobuException_1.DonobuException {
+    constructor(message) {
+        super(message, undefined, 409);
+    }
+    static forId(flowId) {
+        return new FlowIdCollisionException(`A flow with ID '${flowId}' already exists. Client-supplied flow IDs must be unique.`);
+    }
+}
+exports.FlowIdCollisionException = FlowIdCollisionException;
+//# sourceMappingURL=FlowIdCollisionException.js.map

package/dist/esm/main.d.ts

@@ -8,6 +8,7 @@ export { VercelAiGptClient } from './clients/VercelAiGptClient';
 export { runGenerateSiteTests } from './codegen/runGenerateSiteTests';
 export { env } from './envVars';
 export * from './exceptions/DonobuException';
+export * from './exceptions/FlowIdCollisionException';
 export * from './exceptions/FlowNotFoundException';
 export * from './exceptions/GptApiKeysNotSetupException';
 export * from './exceptions/GptPlatformAuthenticationFailedException';

package/dist/esm/main.js

@@ -44,6 +44,7 @@ Object.defineProperty(exports, "runGenerateSiteTests", { enumerable: true, get:
 var envVars_2 = require("./envVars");
 Object.defineProperty(exports, "env", { enumerable: true, get: function () { return envVars_2.env; } });
 __exportStar(require("./exceptions/DonobuException"), exports);
+__exportStar(require("./exceptions/FlowIdCollisionException"), exports);
 __exportStar(require("./exceptions/FlowNotFoundException"), exports);
 __exportStar(require("./exceptions/GptApiKeysNotSetupException"), exports);
 __exportStar(require("./exceptions/GptPlatformAuthenticationFailedException"), exports);

package/dist/esm/managers/DonobuFlowsManager.d.ts

@@ -186,6 +186,12 @@ export declare class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    private assertFlowIdAvailable;
     private resolveLayerForFlowCreate;
     private findTestLayerKey;
     private isLocallyRunning;

package/dist/esm/managers/DonobuFlowsManager.js

@@ -45,6 +45,7 @@ const CodeGenerator_1 = require("../codegen/CodeGenerator");
 const ActiveFlowNotFoundException_1 = require("../exceptions/ActiveFlowNotFoundException");
 const BrowserStateNotFoundException_1 = require("../exceptions/BrowserStateNotFoundException");
 const CannotDeleteRunningFlowException_1 = require("../exceptions/CannotDeleteRunningFlowException");
+const FlowIdCollisionException_1 = require("../exceptions/FlowIdCollisionException");
 const FlowNotFoundException_1 = require("../exceptions/FlowNotFoundException");
 const InvalidParamValueException_1 = require("../exceptions/InvalidParamValueException");
 const TestNotFoundException_1 = require("../exceptions/TestNotFoundException");
@@ -96,7 +97,10 @@ class DonobuFlowsManager {
      *          related parameters are will be ignored.
      */
     async createFlow(flowParams, gptClient, browserContextOverride) {
-        const flowId = (0, crypto_1.randomUUID)();
+        if (flowParams.id) {
+            await this.assertFlowIdAvailable(flowParams.id);
+        }
+        const flowId = flowParams.id ?? (0, crypto_1.randomUUID)();
         const logBuffer = new FlowLogBuffer_1.FlowLogBuffer();
         return Logger_1.loggingContext.run({ flowId, logBuffer }, async () => {
             const messageDuration = flowParams.defaultMessageDuration ??
@@ -670,6 +674,27 @@ class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    async assertFlowIdAvailable(flowId) {
+        for (const persistence of await this.flowsPersistenceRegistry.getAll()) {
+            try {
+                await persistence.getFlowMetadataById(flowId);
+                throw FlowIdCollisionException_1.FlowIdCollisionException.forId(flowId);
+            }
+            catch (error) {
+                if (error instanceof FlowIdCollisionException_1.FlowIdCollisionException) {
+                    throw error;
+                }
+                if (!(error instanceof FlowNotFoundException_1.FlowNotFoundException)) {
+                    throw error;
+                }
+            }
+        }
+    }
     async resolveLayerForFlowCreate(testId) {
         if (!testId) {
             return this.flowsPersistenceRegistry.get();

package/dist/esm/models/CreateDonobuFlow.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod/v4';
 export declare const CreateDonobuFlowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
     target: z.ZodString;
     web: z.ZodOptional<z.ZodObject<{
         browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/esm/models/CreateDonobuFlow.js

@@ -8,6 +8,19 @@ const ProposedToolCall_1 = require("./ProposedToolCall");
 const RunMode_1 = require("./RunMode");
 exports.CreateDonobuFlowSchema = v4_1.z
     .object({
+    id: v4_1.z
+        .string()
+        .uuid()
+        .optional()
+        .describe('⚠️ ADVANCED — DO NOT USE unless you have a specific reason. ' +
+        'Pre-assigned flow ID (UUID). Useful only when the caller must know ' +
+        'the ID before flow creation completes (e.g. orchestrators that ' +
+        'pre-allocate IDs to track an in-flight execution). The SDK does a ' +
+        'best-effort collision check against the persistence layer and ' +
+        'throws FlowIdCollisionException if the ID already exists, but ' +
+        'concurrent calls with the same ID are RACY: there is no locking, ' +
+        'so two callers can both pass the check and create dueling rows. ' +
+        'If you do not need this, omit it and let the SDK mint a UUID.'),
     target: v4_1.z
         .string()
         .describe('The target type: "web", "mobile", or a plugin-provided target.'),

package/dist/esm/reporter/renderPullRequestBody.d.ts

@@ -0,0 +1,16 @@
+import type { DonobuReport } from './model';
+type FooterEnv = {
+    readonly GITHUB_RUN_ID?: string;
+    readonly GITHUB_RUN_NUMBER?: string;
+    readonly GITHUB_SERVER_URL?: string;
+    readonly GITHUB_REPOSITORY?: string;
+    readonly GITHUB_ACTOR?: string;
+    readonly GITHUB_REF_NAME?: string;
+    readonly CI_PIPELINE_URL?: string;
+    readonly CI_PIPELINE_IID?: string;
+    readonly GITLAB_USER_LOGIN?: string;
+    readonly CI_COMMIT_REF_NAME?: string;
+};
+export declare function renderPullRequestBody(report: DonobuReport, envData?: FooterEnv): string;
+export {};
+//# sourceMappingURL=renderPullRequestBody.d.ts.map

package/dist/esm/reporter/renderPullRequestBody.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPullRequestBody = renderPullRequestBody;
+/**
+ * @fileoverview Donobu auto-heal pull request body renderer.
+ *
+ * Turns the merged auto-heal `DonobuReport` into the markdown body of the
+ * PR/MR opened by the surrounding CI job. Pure: callers pass the env subset
+ * the footer needs as a plain object, defaulting to the central `env.pick`
+ * view of the relevant CI vars when running in production.
+ *
+ * Returns an empty string when nothing was healed — the CLI uses that to
+ * decide whether to write the file at all.
+ */
+const envVars_1 = require("../envVars");
+function parseHealedKey(rawKey) {
+    // Composite key shape from buildTestKey(): `file::projectName::title`.
+    // Titles can themselves contain `::`, so we only split off the first two
+    // segments and treat the remainder as the title.
+    const firstSep = rawKey.indexOf('::');
+    if (firstSep < 0) {
+        return { file: 'unknown-file', projectName: 'default', title: rawKey };
+    }
+    const file = rawKey.slice(0, firstSep);
+    const rest = rawKey.slice(firstSep + 2);
+    const secondSep = rest.indexOf('::');
+    if (secondSep < 0) {
+        return { file, projectName: 'default', title: rest };
+    }
+    return {
+        file,
+        projectName: rest.slice(0, secondSep),
+        title: rest.slice(secondSep + 2),
+    };
+}
+function renderPullRequestBody(report, envData = envVars_1.env.pick('GITHUB_RUN_ID', 'GITHUB_RUN_NUMBER', 'GITHUB_SERVER_URL', 'GITHUB_REPOSITORY', 'GITHUB_ACTOR', 'GITHUB_REF_NAME', 'CI_PIPELINE_URL', 'CI_PIPELINE_IID', 'GITLAB_USER_LOGIN', 'CI_COMMIT_REF_NAME').data) {
+    const healedKeys = report.metadata?.donobuHealedTests ?? [];
+    if (healedKeys.length === 0) {
+        return '';
+    }
+    const parsed = healedKeys.map(parseHealedKey);
+    const noun = parsed.length === 1 ? 'test' : 'tests';
+    let body = `🩹 **Donobu auto-heal applied fixes to ${parsed.length} failing ${noun}** in this branch.\n\n`;
+    body += `The auto-heal rerun applied a treatment plan to the failing ${noun}.\n\n`;
+    body += `## Healed ${noun}\n\n`;
+    for (const entry of parsed) {
+        const projectSuffix = entry.projectName && entry.projectName !== 'default'
+            ? ` _(project: \`${entry.projectName}\`)_`
+            : '';
+        body += `- ❤️‍🩹 \`${entry.file}\` — ${entry.title}${projectSuffix}\n`;
+    }
+    const footer = buildCiFooter(envData);
+    if (footer) {
+        body += `\n---\n\n${footer}\n`;
+    }
+    return body;
+}
+function buildCiFooter(e) {
+    if (e.GITHUB_RUN_ID && e.GITHUB_SERVER_URL && e.GITHUB_REPOSITORY) {
+        const url = `${e.GITHUB_SERVER_URL}/${e.GITHUB_REPOSITORY}/actions/runs/${e.GITHUB_RUN_ID}`;
+        const label = e.GITHUB_RUN_NUMBER
+            ? `workflow run #${e.GITHUB_RUN_NUMBER}`
+            : 'workflow run';
+        return assembleFooter(label, url, e.GITHUB_ACTOR, e.GITHUB_REF_NAME);
+    }
+    else if (e.CI_PIPELINE_URL) {
+        // `CI_PIPELINE_IID` is the per-project pipeline number GitLab shows in
+        // its UI ("#42") — far more useful in a footer than the global numeric
+        // `CI_PIPELINE_ID` reviewers don't recognize.
+        const label = e.CI_PIPELINE_IID
+            ? `pipeline #${e.CI_PIPELINE_IID}`
+            : 'pipeline';
+        return assembleFooter(label, e.CI_PIPELINE_URL, e.GITLAB_USER_LOGIN, e.CI_COMMIT_REF_NAME);
+    }
+    else {
+        return undefined;
+    }
+}
+function assembleFooter(label, url, actor, refName) {
+    let footer = `🤖 Generated by Donobu auto-heal · [${label}](${url})`;
+    if (actor) {
+        footer += ` · triggered by @${actor}`;
+    }
+    if (refName) {
+        footer += ` · on \`${refName}\``;
+    }
+    return footer;
+}
+//# sourceMappingURL=renderPullRequestBody.js.map

package/dist/esm/tools/TriggerDonobuFlowTool.d.ts

@@ -4,6 +4,7 @@ import type { ToolCallResult } from '../models/ToolCallResult';
 import { Tool } from './Tool';
 export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -151,6 +152,7 @@ export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const TriggerDonobuFlowGptSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/exceptions/FlowIdCollisionException.d.ts

@@ -0,0 +1,6 @@
+import { DonobuException } from './DonobuException';
+export declare class FlowIdCollisionException extends DonobuException {
+    private constructor();
+    static forId(flowId: string): FlowIdCollisionException;
+}
+//# sourceMappingURL=FlowIdCollisionException.d.ts.map

package/dist/exceptions/FlowIdCollisionException.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowIdCollisionException = void 0;
+const DonobuException_1 = require("./DonobuException");
+class FlowIdCollisionException extends DonobuException_1.DonobuException {
+    constructor(message) {
+        super(message, undefined, 409);
+    }
+    static forId(flowId) {
+        return new FlowIdCollisionException(`A flow with ID '${flowId}' already exists. Client-supplied flow IDs must be unique.`);
+    }
+}
+exports.FlowIdCollisionException = FlowIdCollisionException;
+//# sourceMappingURL=FlowIdCollisionException.js.map

package/dist/main.d.ts

@@ -8,6 +8,7 @@ export { VercelAiGptClient } from './clients/VercelAiGptClient';
 export { runGenerateSiteTests } from './codegen/runGenerateSiteTests';
 export { env } from './envVars';
 export * from './exceptions/DonobuException';
+export * from './exceptions/FlowIdCollisionException';
 export * from './exceptions/FlowNotFoundException';
 export * from './exceptions/GptApiKeysNotSetupException';
 export * from './exceptions/GptPlatformAuthenticationFailedException';

package/dist/main.js

@@ -44,6 +44,7 @@ Object.defineProperty(exports, "runGenerateSiteTests", { enumerable: true, get:
 var envVars_2 = require("./envVars");
 Object.defineProperty(exports, "env", { enumerable: true, get: function () { return envVars_2.env; } });
 __exportStar(require("./exceptions/DonobuException"), exports);
+__exportStar(require("./exceptions/FlowIdCollisionException"), exports);
 __exportStar(require("./exceptions/FlowNotFoundException"), exports);
 __exportStar(require("./exceptions/GptApiKeysNotSetupException"), exports);
 __exportStar(require("./exceptions/GptPlatformAuthenticationFailedException"), exports);

package/dist/managers/DonobuFlowsManager.d.ts

@@ -186,6 +186,12 @@ export declare class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    private assertFlowIdAvailable;
     private resolveLayerForFlowCreate;
     private findTestLayerKey;
     private isLocallyRunning;

package/dist/managers/DonobuFlowsManager.js

@@ -45,6 +45,7 @@ const CodeGenerator_1 = require("../codegen/CodeGenerator");
 const ActiveFlowNotFoundException_1 = require("../exceptions/ActiveFlowNotFoundException");
 const BrowserStateNotFoundException_1 = require("../exceptions/BrowserStateNotFoundException");
 const CannotDeleteRunningFlowException_1 = require("../exceptions/CannotDeleteRunningFlowException");
+const FlowIdCollisionException_1 = require("../exceptions/FlowIdCollisionException");
 const FlowNotFoundException_1 = require("../exceptions/FlowNotFoundException");
 const InvalidParamValueException_1 = require("../exceptions/InvalidParamValueException");
 const TestNotFoundException_1 = require("../exceptions/TestNotFoundException");
@@ -96,7 +97,10 @@ class DonobuFlowsManager {
      *          related parameters are will be ignored.
      */
     async createFlow(flowParams, gptClient, browserContextOverride) {
-        const flowId = (0, crypto_1.randomUUID)();
+        if (flowParams.id) {
+            await this.assertFlowIdAvailable(flowParams.id);
+        }
+        const flowId = flowParams.id ?? (0, crypto_1.randomUUID)();
         const logBuffer = new FlowLogBuffer_1.FlowLogBuffer();
         return Logger_1.loggingContext.run({ flowId, logBuffer }, async () => {
             const messageDuration = flowParams.defaultMessageDuration ??
@@ -670,6 +674,27 @@ class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    async assertFlowIdAvailable(flowId) {
+        for (const persistence of await this.flowsPersistenceRegistry.getAll()) {
+            try {
+                await persistence.getFlowMetadataById(flowId);
+                throw FlowIdCollisionException_1.FlowIdCollisionException.forId(flowId);
+            }
+            catch (error) {
+                if (error instanceof FlowIdCollisionException_1.FlowIdCollisionException) {
+                    throw error;
+                }
+                if (!(error instanceof FlowNotFoundException_1.FlowNotFoundException)) {
+                    throw error;
+                }
+            }
+        }
+    }
     async resolveLayerForFlowCreate(testId) {
         if (!testId) {
             return this.flowsPersistenceRegistry.get();

package/dist/models/CreateDonobuFlow.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod/v4';
 export declare const CreateDonobuFlowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
     target: z.ZodString;
     web: z.ZodOptional<z.ZodObject<{
         browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/models/CreateDonobuFlow.js

@@ -8,6 +8,19 @@ const ProposedToolCall_1 = require("./ProposedToolCall");
 const RunMode_1 = require("./RunMode");
 exports.CreateDonobuFlowSchema = v4_1.z
     .object({
+    id: v4_1.z
+        .string()
+        .uuid()
+        .optional()
+        .describe('⚠️ ADVANCED — DO NOT USE unless you have a specific reason. ' +
+        'Pre-assigned flow ID (UUID). Useful only when the caller must know ' +
+        'the ID before flow creation completes (e.g. orchestrators that ' +
+        'pre-allocate IDs to track an in-flight execution). The SDK does a ' +
+        'best-effort collision check against the persistence layer and ' +
+        'throws FlowIdCollisionException if the ID already exists, but ' +
+        'concurrent calls with the same ID are RACY: there is no locking, ' +
+        'so two callers can both pass the check and create dueling rows. ' +
+        'If you do not need this, omit it and let the SDK mint a UUID.'),
     target: v4_1.z
         .string()
         .describe('The target type: "web", "mobile", or a plugin-provided target.'),

package/dist/reporter/renderPullRequestBody.d.ts

@@ -0,0 +1,16 @@
+import type { DonobuReport } from './model';
+type FooterEnv = {
+    readonly GITHUB_RUN_ID?: string;
+    readonly GITHUB_RUN_NUMBER?: string;
+    readonly GITHUB_SERVER_URL?: string;
+    readonly GITHUB_REPOSITORY?: string;
+    readonly GITHUB_ACTOR?: string;
+    readonly GITHUB_REF_NAME?: string;
+    readonly CI_PIPELINE_URL?: string;
+    readonly CI_PIPELINE_IID?: string;
+    readonly GITLAB_USER_LOGIN?: string;
+    readonly CI_COMMIT_REF_NAME?: string;
+};
+export declare function renderPullRequestBody(report: DonobuReport, envData?: FooterEnv): string;
+export {};
+//# sourceMappingURL=renderPullRequestBody.d.ts.map

package/dist/reporter/renderPullRequestBody.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPullRequestBody = renderPullRequestBody;
+/**
+ * @fileoverview Donobu auto-heal pull request body renderer.
+ *
+ * Turns the merged auto-heal `DonobuReport` into the markdown body of the
+ * PR/MR opened by the surrounding CI job. Pure: callers pass the env subset
+ * the footer needs as a plain object, defaulting to the central `env.pick`
+ * view of the relevant CI vars when running in production.
+ *
+ * Returns an empty string when nothing was healed — the CLI uses that to
+ * decide whether to write the file at all.
+ */
+const envVars_1 = require("../envVars");
+function parseHealedKey(rawKey) {
+    // Composite key shape from buildTestKey(): `file::projectName::title`.
+    // Titles can themselves contain `::`, so we only split off the first two
+    // segments and treat the remainder as the title.
+    const firstSep = rawKey.indexOf('::');
+    if (firstSep < 0) {
+        return { file: 'unknown-file', projectName: 'default', title: rawKey };
+    }
+    const file = rawKey.slice(0, firstSep);
+    const rest = rawKey.slice(firstSep + 2);
+    const secondSep = rest.indexOf('::');
+    if (secondSep < 0) {
+        return { file, projectName: 'default', title: rest };
+    }
+    return {
+        file,
+        projectName: rest.slice(0, secondSep),
+        title: rest.slice(secondSep + 2),
+    };
+}
+function renderPullRequestBody(report, envData = envVars_1.env.pick('GITHUB_RUN_ID', 'GITHUB_RUN_NUMBER', 'GITHUB_SERVER_URL', 'GITHUB_REPOSITORY', 'GITHUB_ACTOR', 'GITHUB_REF_NAME', 'CI_PIPELINE_URL', 'CI_PIPELINE_IID', 'GITLAB_USER_LOGIN', 'CI_COMMIT_REF_NAME').data) {
+    const healedKeys = report.metadata?.donobuHealedTests ?? [];
+    if (healedKeys.length === 0) {
+        return '';
+    }
+    const parsed = healedKeys.map(parseHealedKey);
+    const noun = parsed.length === 1 ? 'test' : 'tests';
+    let body = `🩹 **Donobu auto-heal applied fixes to ${parsed.length} failing ${noun}** in this branch.\n\n`;
+    body += `The auto-heal rerun applied a treatment plan to the failing ${noun}.\n\n`;
+    body += `## Healed ${noun}\n\n`;
+    for (const entry of parsed) {
+        const projectSuffix = entry.projectName && entry.projectName !== 'default'
+            ? ` _(project: \`${entry.projectName}\`)_`
+            : '';
+        body += `- ❤️‍🩹 \`${entry.file}\` — ${entry.title}${projectSuffix}\n`;
+    }
+    const footer = buildCiFooter(envData);
+    if (footer) {
+        body += `\n---\n\n${footer}\n`;
+    }
+    return body;
+}
+function buildCiFooter(e) {
+    if (e.GITHUB_RUN_ID && e.GITHUB_SERVER_URL && e.GITHUB_REPOSITORY) {
+        const url = `${e.GITHUB_SERVER_URL}/${e.GITHUB_REPOSITORY}/actions/runs/${e.GITHUB_RUN_ID}`;
+        const label = e.GITHUB_RUN_NUMBER
+            ? `workflow run #${e.GITHUB_RUN_NUMBER}`
+            : 'workflow run';
+        return assembleFooter(label, url, e.GITHUB_ACTOR, e.GITHUB_REF_NAME);
+    }
+    else if (e.CI_PIPELINE_URL) {
+        // `CI_PIPELINE_IID` is the per-project pipeline number GitLab shows in
+        // its UI ("#42") — far more useful in a footer than the global numeric
+        // `CI_PIPELINE_ID` reviewers don't recognize.
+        const label = e.CI_PIPELINE_IID
+            ? `pipeline #${e.CI_PIPELINE_IID}`
+            : 'pipeline';
+        return assembleFooter(label, e.CI_PIPELINE_URL, e.GITLAB_USER_LOGIN, e.CI_COMMIT_REF_NAME);
+    }
+    else {
+        return undefined;
+    }
+}
+function assembleFooter(label, url, actor, refName) {
+    let footer = `🤖 Generated by Donobu auto-heal · [${label}](${url})`;
+    if (actor) {
+        footer += ` · triggered by @${actor}`;
+    }
+    if (refName) {
+        footer += ` · on \`${refName}\``;
+    }
+    return footer;
+}
+//# sourceMappingURL=renderPullRequestBody.js.map

package/dist/tools/TriggerDonobuFlowTool.d.ts

@@ -4,6 +4,7 @@ import type { ToolCallResult } from '../models/ToolCallResult';
 import { Tool } from './Tool';
 export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -151,6 +152,7 @@ export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const TriggerDonobuFlowGptSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.37.0",
+  "version": "5.38.0",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",